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 <b>!");-
Add the dependency (no build script, Rust ≥ 1.88):
[dependencies] damask = "0.5"
-
Create a component as two files that share a basename, in the same directory —
button.rsandbutton.dmk. -
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.
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.
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(…)} 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(…)} 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"anddata={self.url}are the ordinary attribute they look like, on<object>as anywhere else; it is the helper that expands, not the name.
{...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 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.
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.
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.
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.
#[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 atRenderinstead, which is all composition asks for.
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.
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)}.
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.
| 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 |
cargo test --workspace # runtime, macro, parser, LSP, examples, trybuild
cargo clippy --workspace --all-targets -- -D warningsThe 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.
MIT.