Skip to content
JWo1FPublic

About

Damask — compile-time components for Rust

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Damask — compile-time components for Rust

React-like, compile-time components for Rust. A component is a struct (its fields are its props) paired with an HTML template that uses a { … } tag syntax. The Component derive turns the template into a render method at build time, so rendering is plain, allocation-light Rust — no runtime template engine.

use damask::Component;

// greeting.rs  (paired with greeting.dmk)
#[derive(Component)]
pub struct Greeting {
    pub name: String,
}
<!-- greeting.dmk -->
Hello {self.name}!
assert_eq!(Greeting { name: "Ada".into() }.render(), "Hello Ada!");
// `{ … }` HTML-escapes:
assert_eq!(Greeting { name: "<b>".into() }.render(), "Hello &lt;b&gt;!");

Quickstart

  1. Add the dependency (no build script, Rust ≥ 1.88):

    [dependencies]
    damask = "0.5"
  2. Create a component as two files that share a basename, in the same directory — button.rs and button.dmk.

  3. use damask::Component;, #[derive(Component)] your struct, and call .render().

The template is found automatically next to the struct (via Span::local_file), and editing it triggers a rebuild — no build.rs, no configuration.

Template syntax

Templates are HTML with brace tags. A { … } tag holds a Rust block: if it's an expression, its value is printed (HTML-escaped); if it's a statement or binding, it runs and prints nothing.

Tag Meaning
{ expr } print the block's value, HTML-escaped ({2+3; 10} prints 10)
{ let x = e } / { x; } a binding / statement — runs, prints nothing
{@html expr} print expr raw (unescaped)
{@render expr} render a snippet / fragment
{use path} a Rust use, scoped to the enclosing element
{#if c}…{:else if c2}…{:else}…{/if} conditional
{#for pat in E}…{/for} loop — a Rust for
{#snippet name(params)}…{/snippet} define a reusable fragment
<ul>
{#for item in &self.items}
  <li>{item}</li>
{/for}
</ul>

Literal braces are written as expressions: {"{"}. <!-- … --> comments pass through.

Elements, components, and slots

Lowercase tags are HTML. Capitalized tags are components — built from their attributes and rendered. Attributes carry Rust: attr={expr}, attr="literal", or bare attr (boolean). Omitting a required field is a compile error naming it; a field whose type is Option<_> may be omitted and arrives as None, and #[component(default)] on the struct makes every field skippable, filling the omitted ones from its Default. A framework that re-exports Damask instead of having its users depend on it names its own path with #[component(crate = my_framework::view)], since the default ::damask resolves only where damask is a direct dependency.

Quoted values interpolate, and on an HTML element attr={expr} asks the value's type how to appear — a bool renders a bare attribute or none at all, an Option renders nothing when None:

<input title="row {self.n}" disabled={self.locked} placeholder={self.hint}/>

disabled appears only when locked, because in HTML the presence of the attribute is what disables the control — disabled="false" disables it too.

@tokens — one value from many parts

{@tokens(…)} builds a space-separated value, on whatever attribute it is written. A class: directive still overrules a class built this way:

<div class={@tokens(self.extra, "base", "is-open": self.open)} class:base={!self.bare}>
<a rel={@tokens("noopener", external: self.away)}>

A positional entry is a name, a list of them, or an Option — a literal None is dropped at compile time (a bare None has no type to infer). A name: cond entry is there while cond holds; the name is a bare identifier or, for anything an identifier cannot spell, a string: "md:px-3": cond. Names are deduplicated and keep their first-mention order, and an empty result omits the attribute.

CSS scanners and class:. A directive puts the class name in the attribute name (class:animate-pulse), where Tailwind and friends do not look — the rule gets compiled out of your stylesheet. When a class has to be discoverable by a scanner, write it in a helper, whose names are ordinary strings: class={@tokens("animate-pulse": cond)}.

@attrs — many attributes from one

{@attrs(…)} expands into a run of <name>-* attributes, the way a Rails view does with data: { … } — and, since the prefix is the attribute it was written on, the same helper serves aria and anything else shaped that way:

<div data={@attrs(self.hooks(), controller: "modal", index: self.i)}
     aria={@attrs(label: self.title)}>

A key becomes <name>-<key> verbatim — user_id is data-user_id — and is a bare identifier or a string, checked when the template compiles, because a name is not something escaping can make safe. A positional entry contributes whole pairs and a later one overrides an earlier, keeping the first mention's position. Values follow the Attr rules one level down, so a bool renders a bare data-open or nothing, and an Option renders nothing when None. AttrSet is implemented for pair lists, HashMap, BTreeMap, Attrs, Option of any of them, and whatever you implement it for.

No attribute is special. data="movie.swf" and data={self.url} are the ordinary attribute they look like, on <object> as anywhere else; it is the helper that expands, not the name.

Spreading attributes

{...expr} splices a prepared run of attributes — for the ones a component cannot name, such as a computed data-<controller>-target, or a map:

<input {...self.wiring} {...&self.data}/>

AttrSpread is implemented for &'static str (markup the author wrote — the lifetime is what keeps a request-derived value out) and for [(K, V)] / Vec<(K, V)>, which escapes and is where anything derived from state belongs. A tag that writes an attribute itself and also spreads a set holding it writes it once, from the tag.

A component takes attributes it never declared the same way, given one field to put them in:

#[derive(Component, Default)]
#[component(default)]
pub struct Hidden {
    #[prop(rest)]
    pub attrs: Attrs,
}
<input type="hidden" {...self.attrs}>       <!-- hidden.dmk -->

<Hidden data-cover-target="input" autofocus/>

Which of a tag's attributes are props is settled when it compiles: a declared prop wins, and everything else goes to the bag. Without a #[prop(rest)] field a component still refuses an attribute it does not name, so a misspelled prop is a build failure rather than something rendered into the page.

<div>
  {use crate::widgets::Frame}        <!-- import, scoped to this <div> -->
  <Frame title={self.heading.clone()}>
    <p>{self.body}</p>                          <!-- fills the default slot -->
    <span slot="footer">© {self.year}</span>
    <a slot="footer" href="/about">About</a>
    <Avatar slot="footer">{self.name}</Avatar>  <!-- a component fills one too -->
  </Frame>
</div>

A component places its slots with <slot/>, and a caller routes content into a named one with slot="…" on a direct child — the web-component pair. The whole element goes in, several children may name the same slot (they land in the order written), and the slot attribute itself is consumed rather than rendered.

The child may be a component. <Avatar slot="footer">…</Avatar> puts the whole Avatar in the footer, content and all — slot routes it and never reaches its props, so a component needs neither a slot field nor a #[prop(rest)] bag to be placed this way.

Slots are not fields — a template declares as many as it likes without the struct changing, and a <slot>'s body is the fallback rendered when the caller leaves it unfilled:

use damask::Component;

#[derive(Component)]
pub struct Frame {
    pub title: String,
}
<!-- frame.dmk -->
<section><h2>{self.title}</h2><slot/><footer><slot name="footer">© anon</slot></footer></section>

Slots are matched by name at render time, so a misspelled name fails silently rather than at compile time — the price of keeping them off the struct.

<slot> is only ever a placeholder, so putting one where a fill goes forwards — it resolves against this component's caller and slot= hands the result to the child:

<!-- shell.dmk -->
<Frame title={self.title.clone()}>
  <slot/>                                   <!-- forward the default slot -->
  <slot name="footer" slot="footer"/>       <!-- forward "footer" -->
</Frame>

Outside a component element slot is an ordinary attribute, so a template can still address a browser-side custom element's shadow slots.

A template can also ask about its slots: the caller's fills are in scope as slots, which answers what a fallback cannot — whether the markup around the content should exist at all.

<!-- dialog.dmk -->
<div class="dialog">
  <h2>{self.title}</h2>
  {#if slots.has_default()}<p class="body"><slot/></p>{/if}
  {#if slots.has("actions")}<footer>{@render slots.get("actions")}</footer>{/if}
</div>

slots.get(name) is renderable as it comes — an unfilled slot renders nothing — so {@render} needs no guard of its own; the {#if}s above are guarding the wrappers. has_default() / get_default() are the same pair for the default slot.

{use} is an ordinary Rust use — import components, functions, or anything else — and it is scoped to the HTML element that encloses it.

Snippets

Snippets are reusable fragments, defined with {#snippet} and rendered with {@render}; parameters make them render-props:

{#snippet item(label)}<li>{label}</li>{/snippet}
<ul>{#for label in &self.labels}{@render item(label)}{/for}</ul>

Slots can also be filled from Rust, with render_with:

use damask::{fragment, Component, Renderer, Slot, Slots, DEFAULT_SLOT};

let body = fragment(|r: &mut dyn Renderer| r.write_raw("<p>hi</p>"));
Layout.render_with(Slots::new(&[Slot::new(DEFAULT_SLOT, &body)]));

The fills are borrowed, not owned, so slot content stays on the caller's stack and can borrow the caller's data without boxing.

Whitespace

A whitespace run containing a newline becomes one space when the template compiles; a run within a line is the author's own spacing and is left as written. That is the one transformation that provably cannot change the page: HTML already draws such a run as a single space wherever whitespace is insignificant, and where it is significant — inside <pre>, <textarea>, <script> and <style> — the run is not touched at all. Nothing is closed up that the author wrote apart, and nothing is separated that they wrote together.

It happens at compile time rather than at render time, which is the whole of the change: the indentation never becomes bytes in the binary, and the space that replaces it merges into the tag literal beside it, so it costs no call of its own. Across three applications that removes between 42% and 47% of the calls a template makes to its renderer.

Templates that are not HTML

The whitespace rule above is HTML's, and a plain-text mail body is not HTML: there a line break is the content, and one space is not the same thing as one newline. #[component(text)] turns the rule off for a template, which then keeps every byte it was written with.

#[derive(Component)]
#[component(text)]
pub struct ReceiptText {
    pub number: u32,
    pub total: String,
}
Receipt #{self.number}
Total: {self.total}
assert_eq!(ReceiptText { number: 7, total: "£12.00".into() }.render(), "Receipt #7\nTotal: £12.00\n");

Nothing in a template says which it is — the renderer that decides is chosen far from it, often in another crate — so the author says.

Writing markup in Rust

A .dmk is the usual way to write a component, and the derive turns one into calls on an API that is meant to be written by hand as well — for the markup a template is the wrong shape for, and for a component assembled somewhere other than a file pair.

use damask::{attrs, Element};

let html = Element::builder("article")
    .props(attrs![class = "card", "data-tone" = self.tone.skin()])
    .default_slot(|w| {
        Element::builder("h3").text(&self.title).render_into(w);
        Element::builder("p").text("Templates can await.").render_into(w);
    })
    .render();

attrs![…] expands to a fixed array of pairs, not a map, and a value keeps the rules it has in a template: true is a bare attribute, false and None write nothing. A name is an identifier, or a string where an identifier cannot spell it — anything hyphenated, and every Rust keyword. Writing .props(…) twice accumulates, with a repeated name taking the later value and keeping the earlier position.

.text(v) is the shorthand for an element whose content is one escaped value; .default_slot(|w| …) is the general form. Both escape. write_raw is the loud name for the other thing, which is the point of it having one.

A component with no template

#[component(manual)] says there is no .dmk and the body is written below. The derive still generates everything a call site needs, which is the reason to ask for it:

use damask::{attrs, Component, Element, Render, Renderer, Slots};

#[derive(Component)]
#[component(manual)]
pub struct Card {
    pub title: String,
    pub tone: Tone,
}

impl Render for Card {
    fn render_into(&self, w: &mut dyn Renderer, slots: Slots<'_>) {
        Element::builder("article")
            .props(attrs![class = "card", "data-tone" = self.tone.skin()])
            .default_slot(|w| {
                Element::builder("h3").text(&self.title).render_into(w);
                slots.render_default(w);
                Element::builder("footer")
                    .default_slot(|w| slots.render_with("meta", w, |w| w.write_text("Just now")))
                    .render_into(w);
            })
            .render_into(w);
    }
}

A <slot> is placed with one of four calls, so that a call site never spells the default slot "" nor passes an empty closure for a slot that has no fallback: render_default(w), render_default_with(w, …), render(name, w), render_with(name, w, …). Each has an _async counterpart. The lowering picks between them too, which is why a template's expansion reads the way the template does.

It is then built and filled the way a template's <Card …/> is — the same builder, reached the same way:

let html = Card::builder()
    .title("Damask 0.11".to_string())
    .tone(Tone::Note)
    .default_slot(|w| Element::builder("p").text("body").render_into(w))
    .slot("meta", |w| w.write_text("a moment ago"))
    .render();

Card::builder() is what <Card …/> goes through in a template too, so a prop left out is the same compile error naming it, whichever side wrote the call. .render() gives the string; .render_into(w) writes into a renderer someone else owns; an asynchronous component gets .render_async() and .render_into_async(w) instead.

The lowering does not go through this API. A template writes its static attributes as bytes, and the builder collects them so that .props() can accumulate — an allocation per element, bought for a flexibility a template does not need. The two meet at Render instead, which is all composition asks for.

Reading the output

A template's own indentation never reaches the page: a whitespace run holding a newline becomes, when the template compiles, the single space HTML already draws it as — so a render is one line. That is what should go over the wire, and it is miserable to read. .render_tidy() puts the newlines back, as a second pass the caller asks for:

let html = Frame::builder().title("Damask".into()).render_tidy();
<section class="frame">
  <h2>Damask</h2>
  <footer>© anon</footer>
</section>

It is on every terminal — Component::render_tidy, an element or component builder's .render_tidy(), and .render_tidy_async() for the async pair — and damask::tidy::tidy takes any HTML string, not only Damask's own.

A line is broken only around elements known to be block-level. Everything else is left byte for byte, including custom elements, which HTML gives display: inline by default — a newline added between two inline elements is a gap the page did not have. A whitespace run beside a block boundary is absorbed into the line break replacing it, and one between two inline elements is the space between two words and stays. <pre>, <textarea>, <script> and <style> are passed through whole, and input that does not parse is returned unchanged.

The one thing it cannot know is CSS: an element a stylesheet makes display: inline is one it will still break around. That is the bargain every HTML formatter makes, and the reason this is a pass you call rather than something the renderer does on the way out. A binary that never calls it does not carry it — measured at zero bytes in examples/showcase.

Async templates

A component renders on one of two paths, and the author picks which by choosing a derive:

use damask::AsyncComponent;

// profile.rs  (paired with profile.dmk)
#[derive(AsyncComponent)]
pub struct Profile<'a> {
    pub store: &'a Store,
    pub id: UserId,
}
<!-- profile.dmk -->
<p>{self.store.load_name(self.id).await}</p>

#[derive(AsyncComponent)] implements AsyncComponent / AsyncRender instead of Component / Render, so it renders with .render_async().await:

let html = Profile { store: &store, id }.render_async().await;

Two things need it. One is writing .await yourself — anywhere the template holds Rust: a { … } tag, an {#if} / {#for} condition or iterable, an attribute value, a snippet body. Forget it and the error says so, naming the derive rather than pointing at a .await inside macro expansion.

The other is holding a child that awaits, while awaiting nothing yourself. That case is why this is a choice at all: <Card/> is a type, and whether it renders asynchronously is settled after the derive has run, on the other side of macro expansion. No reading of the template can answer it, so the template does not try.

Composition is free in one direction: every sync Render gets an AsyncRender whose future has nothing left to poll, so an async template embeds a plain sync child at no real cost. The other direction is a compile error naming the missing Render — an async component has no sync fallback, because producing one would mean blocking on a future inside the executor already driving the caller. Make the enclosing template async too, or load the child's data before constructing it.

The render future is Send, so a request handler can await one. Three bounds buy that, one per thing held across an .await: Renderer: Send, a slot fill is Sync (on Slot, deliberately not a Render supertrait), and AsyncRender: Sync — automatic for a struct of data, and something a generic component that awaits must name on the parameters it holds.

Only one place .await cannot go, with a one-line rewrite the compiler spells out: a {#snippet} that takes parameters cannot await in its body, since its closure has to stay callable more than once. Await at the call site instead, as {@render row(self.fetch().await)}.

Custom renderers

Renderer is the extensibility seam — it owns the output buffer and the escaping policy. Implement it to change escaping or target a different sink; components are compiled against &mut dyn Renderer, so any renderer drives any component. It requires Send, which a buffer-backed renderer satisfies without saying anything, and which is what lets an async render be awaited on a work-stealing executor.

Workspace

Crate / dir Purpose
damask the facade: traits, the HTML renderer, and the derive
damask-macros the Component derive + template resolution
damask-template the .dmk parser (shared by macro + LSP)
tree-sitter-damask the vendored Tree-sitter grammar, for the website
damask-lsp language server (diagnostics + completion)
editors/zed Zed extension (highlighting + LSP)
skills/damask agent skill for authoring components
examples/showcase runnable example components
examples/dashboard a full HTML page from 7 composed components

Development

cargo test --workspace          # runtime, macro, parser, LSP, examples, trybuild
cargo clippy --workspace --all-targets -- -D warnings

The Tree-sitter grammar lives in crates/tree-sitter-damask/grammar, with the Rust binding the website reads it through in the crate around it. Zed reads the same directory: extension.toml pins a revision of this repository and points path at it, so a grammar change is one commit — and reaches editors when that commit is pushed and the rev is bumped to name it.

The website highlights .dmk with that grammar and with the extension's own queries in editors/zed/languages/damask — so a snippet looks the same on the site as it does in an editor, and editing a query changes both.

License

MIT.

About

Damask — compile-time components for Rust

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages