Tutorial
The language
Elements
Everything on screen is an element, and every element is written the same way: a name, one positional value, named props, flags and a block.
This chapter covers WebFluent's elements: everything a page shows, whether a built-in such as Button or a component you declare. Every element is written in the same shape, so once you can read one call you can read them all.
In this chapter:
- the shape of an element call, and the order of its block
- props, enum cases and flags, and the props every element takes
- HTML attributes, and which element of a built-in receives them
- parts, such as
Card.Header - the text, heading and layout elements
- the families of built-ins, the HTML they render, and what the compiler checks on every element
The call shape
Every element call has the same five pieces, each optional except the name:
Name(positional, prop: value, prop: value).flag.flag { block }
Nameis PascalCase: a built-in (Card), a part of one (Card.Header), or a component of the project (UserCard,Panel.Footer).- One positional argument comes first, unnamed. It is the element's main value: a button's label, a heading's text, an icon's name. You pass every other value by name.
- Named props,
name: value, come in any order, and the value may be any expression. - Flags,
.name, are written tight against the closing parenthesis, or against the name when there are no parentheses:Button("Save").primary.lg,Spacer.sm,Card.elevated { … }. An element or a component called with no arguments needs no parentheses:SpinnerandSpinner()are the same call, and this book writes the shorter one. - The block,
{ … }, holds its contents in a fixed order:style { }, thentransition { }, thenon … { }handlers, then slot fills, then children.
This button uses all five pieces, with its block in that order:
page Editor(path: "/", title: "Editor", description: "A save button, fully dressed.") {
Heading("Editor").h1
Button("Save", disabled: false).primary.lg {
style { min-width: 120px }
transition { background: 150ms ease-out }
on click { log("saved") }
Icon("check")
}
}
Note
Coming from JSX or a Vue template? There are no tags and no string attributes: <Button variant="primary" size="lg">Save</Button> is Button("Save").primary.lg. A prop's value is an expression, never a string to be parsed, and children go in the block. See Coming from React.
Props, cases and flags
Each prop has a type the compiler knows: String, Number, Bool, a state binding, a path, or an enum, which is a fixed set of named cases. You pass an enum prop a case, written with a leading dot:
page Toolbar(path: "/", title: "Toolbar", description: "Two labels, spaced apart.") {
Heading("Toolbar").h1
Row(gap: .md, align: .center, justify: .between) {
Text("Drafts")
Text("3 unsent")
}
}
A flag is a short way to write one of two things: a Bool prop set to true, or a case of one of the element's enum props. Each comment shows the long spelling of the flags on its line:
page Search(path: "/", title: "Search", description: "A search box and two buttons.") {
state term = ""
Heading("Search").h1
Button("Delete").danger // tone: .danger
Button("Continue").full.outlined // width: .full, outlined: true
Input(bind: term, label: "Search").search.required // type: .search, required: true
}
The two spellings mean the same thing. .md on a Row means gap: .md, because gap is the only prop of Row with an md case. A flag follows these rules:
- When two enum props of an element share a case name, the flag is ambiguous. The compiler reports
E103and asks you to name the prop. - A flag the element does not declare is error
E103, and the message lists the flags the element takes. There is no shared vocabulary of modifiers to guess from. - A
Boolprop may take a condition instead of a flag:Button("Light", outlined: theme != "light").
Universal props
Every element also takes the universal props. The reference does not repeat them on each element:
| Prop | What it does | Read more |
|---|---|---|
|
|
Adds classes from your own stylesheets. It adds; it never replaces | |
|
|
Names a handle on the element: |
|
|
|
Hands the element to a script each time it is made, again when what |
|
|
|
The animation it enters with | |
|
|
The animation it leaves with | |
|
|
How the animation is timed | |
|
|
Inside a |
|
|
|
When the animation plays: |
|
|
|
A name the element keeps across a route change | |
|
|
A number in its text counts up or down to its new value |
The components reference lists every element's own props.
Attributes
A named argument that is not a prop becomes an HTML attribute. These families are declared, so they draw no warning:
- the global attributes:
id,title,role,tabindex,lang,dir,hidden; aria-*anddata-*;- the attributes of the element's kind: input, anchor, media, form and table attributes on the elements that take them.
Any other name is still written to the element, with warning C04. You write a hyphenated name as it is:
page Signup(path: "/", title: "Sign up", description: "A name field and a menu button.") {
state name = ""
Heading("Sign up").h1
Button("More", aria-expanded: "false", aria-controls: "panel", data-track: "more")
Input(bind: name, label: "Name", id: "name", autocomplete: "name", maxlength: 40)
}
Attribute values
An attribute's value follows these rules:
- A value that reads state is kept in step with it.
trueis written as the word:data-open: truerendersdata-open="true", so the selector[data-open="true"]matches it.- A boolean attribute such as
hiddenordisabledis either present or absent. falseremoves an attribute, except anaria-*one, which keeps the string"false"because it is a real ARIA state.
The same rules apply to an attribute you write on a call of your own component, which passes it to the component's root.
Where a built-in puts them
A built-in places your attributes and on handlers on the element it draws:
- On its root, for most built-ins: the scrolling box of a
VirtualList, the handle of aSplitter, the box of aTabsor aCarousel, the panel of aSidebar, the<nav>of aBreadcrumb, the<dialog>of aModal. - On its input, for a control drawn inside a box (
Switch,Checkbox,Radio,Slider,DatePicker,FileUpload). The input is the control, and its own handlers are already there.hidden,langanddirbelong to the whole control, so they stay on its box.
A role: or aria-label: you write takes the place of the one the built-in gives itself: a Splitter's separator, a Switch's switch, a Breadcrumb's name. A Sidebar's id: is the one its toggle points at.
This list box puts role, tabindex and aria-activedescendant on the VirtualList's scrolling box, and a role and id on each row:
page References(path: "/", title: "References", description: "A list box of references.") {
state refs = [{ id: "a" }, { id: "b" }, { id: "c" }]
state current = 0
Heading("References").h1
VirtualList(rowHeight: 24, label: "References", role: "listbox", tabindex: "0", aria-activedescendant: "ref-{current}") {
style { height: 240px }
on keydown(e) { if e.key == "ArrowDown" { current = current + 1 } }
for r in refs by r.id { Text(r.id, id: "ref-{r.id}", role: "option") }
}
}
The pre-rendered page and the template engine write the same attributes on the same elements, as far as the build knows their values.
Parts
Some built-ins are made of parts. You write a part under its owner's name, inside its owner:
page Regions(path: "/", title: "Regions", description: "A card, a table, a select and tabs.") {
state region = "fra1"
Heading("Regions").h1
Card.elevated {
Card.Header { Heading("Frankfurt").h2 }
Card.Body { Text("Our main region.") }
Card.Footer { Button("Open").primary }
}
Table(caption: "Regions") {
Table.Head { Table.Row { Table.Cell("Region").header Table.Cell("Latency").header } }
Table.Body { Table.Row { Table.Cell("fra1") Table.Cell("34 ms") } }
}
Select(bind: region, label: "Region") {
Select.Option("Frankfurt", value: "fra1")
Select.Option("Iowa", value: "iad1")
}
Tabs {
Tabs.Page("Summary") { Text("Two regions.") }
Tabs.Page("Details") { Text("fra1 and iad1.") }
}
}
A part belongs inside its owner. Card.Body outside a Card is error C03. Your own components may declare parts too (Components).
A Tabs keeps the open tab in a state of yours with bind:, holding the open page's value:. Only the open tab is in the Tab order; the arrow keys move between tabs, the other way round in a right-to-left page:
page Account(path: "/account", title: "Account", description: "Your profile and billing.") {
state tab = "profile"
Heading("Account").h1
Tabs(bind: tab, label: "Account") {
Tabs.Page("Profile", value: "profile") { Text("Your name and photo.") }
Tabs.Page("Billing", value: "billing") { Text("Your plan and invoices.") }
}
Text("Open: {tab}")
}
Any element of your own can move the same way: roving: .x makes a row one stop for Tab, with the arrow keys inside it (Events).
Text and headings
The typography elements cover inline text, headings, paragraphs, code, quotations and Markdown:
page Article(path: "/", title: "Article", description: "Every kind of text.") {
state count = 3
Heading("Release notes").h1 // a real <h1>; .h2 is the default
Text("{count} changes").bold.muted // a run of text
Paragraph("Prose, as a <p>.")
Code("let x = 1").block
Blockquote("A quotation.")
Markdown("**Bold** and a [link](/docs)") // Markdown, rendered as HTML
}
The compiler checks the outline the headings form: a page needs an h1 (A12), and a heading level may not be skipped, such as h2 straight to h4 (A11).
Render Markdown shows what Markdown draws, and how to show text somebody else wrote.
Layout elements
The layout elements arrange what is inside them. Each comment says what the element is:
page Dashboard(path: "/", title: "Dashboard", description: "Every layout element at once.") {
Header { Heading("Dashboard").h1 }
Container { // centred, with a max width
Row(gap: .md, align: .center) { // horizontal flex
Column(span: 8) { Text("main") } // a child of a 12-column grid
Column(span: 4) { Text("aside") }
}
Grid(columns: 3, gap: .lg) { Card { Text("a") } Card { Text("b") } Card { Text("c") } }
Stack(gap: .sm) { Text("one") Text("two") } // vertical flex
Spacer.lg
Divider
}
Section { Text("another region") }
Footer { Text("the last region") }
}
Header, Section and Footer render real landmarks: <header>, <section> and <footer>. Use them for the page's regions, so a screen reader and a search engine can follow the page's outline. Inside a Document, Header and Footer mean something else: they are drawn in the margin of every printed page (PDF and slides).
The families of built-ins
The built-ins fall into these families:
| Family | Elements |
|---|---|
| Layout |
|
| Navigation |
|
| Data display |
|
| Content |
|
| Forms |
|
| Feedback |
|
| Actions |
|
| Media |
|
| Typography |
|
| Somebody else's code |
|
| Documents and decks |
|
| Routing |
|
Content: a note, a key, a figure
The content built-ins are the pieces a page of text and figures is made of. Each is drawn the same on the live page, in the static paint and in a PDF:
page Report(path: "/", title: "Report", description: "The month, at a glance.") {
state tags = ["Rust", "Go"]
Heading("Report").h1
Callout("Figures are for the month to date.").note
Row(gap: .lg) {
Stat("Revenue", value: 48210, format: .currency, change: 0.124)
Stat("Churn", value: 0.031, format: .percent, change: -0.02)
}
Row(gap: .xs, align: .center) { Text("Search with") Kbd("mod+k") }
for tag in tags by tag {
Chip(tag).removable { on remove { tags = tags.filter(x => x != tag) } }
}
CodeBlock("wf build", language: "bash", title: "Terminal").copy
Accordion.single {
Accordion.Item("How is revenue counted?") { Text("Paid invoices, by the day they were paid.") }
Accordion.Item("When does the month end?") { Text("At midnight UTC on its last day.") }
}
if tags.length == 0 {
EmptyState(icon: "folder", title: "No tags", text: "Add one to group the report.")
}
}
Calloutis a note set apart from the text, with its kind's icon and word:.note,.tip,.important,.warning,.caution, or atitle:of its own.Statsays which way a figure moved, to a screen reader as well ("Up 12.4%").Kbdwrites a key combination as this system does:⌘Kon a Mac,Ctrl+Kelsewhere.Chipcan be pressed (selected:, a toggle button) and removed (.removable, its button namedRemove Rust, firingon remove).CodeBlockadds a bar with the file name and a copy button, and.linesnumbers the lines.Accordionis native<details>;.singlekeeps one open at a time.VisuallyHiddenis words only a screen reader hears.
What an element renders
Each built-in renders real, semantic HTML. A Button is a <button>, a Link an <a>, a Heading(…).h2 an <h2>, and a Table a <table> with <th scope="col"> cells in its head.
Each also carries a stable class named after it, with a modifier class for each flag. For example, Button("Save").primary.lg renders:
<button class="wf-btn wf-btn--primary wf-btn--large" type="button">Save</button>
These classes are part of the public surface and stay stable across releases, so your own stylesheet may target them (Styling). The reference names each element's class.
What the compiler checks on every element
The compiler holds every element call to these rules:
| What it checks | When it fails |
|---|---|
| The name is a built-in, a part inside its owner, or a declared component |
|
| There is at most one positional argument, and the element takes one |
A second is |
| Every named prop exists, with a value of its type, and an enum prop's case exists |
A wrong type is |
| A named argument that is not a prop is a declared attribute |
Any other is written as an attribute, with |
| Every flag resolves to exactly one prop |
|
| A handler names a DOM event, or one of the component's declared events |
|
| A slot fill names a declared slot |
|
|
An |
|
|
Accessibility: an |
|
Quick reference
| Syntax | Meaning |
|---|---|
|
|
An element with one positional and named props |
|
|
A |
|
|
An enum prop, named |
|
|
The block, in its fixed order |
|
|
HTML attributes |
|
|
A part, inside its owner |
|
|
Universal props, on every element |
The components reference lists each built-in's props, flags, events, slots and parts; wf registry --json prints the same data for a tool.
Common mistakes
A second positional argument. Only the first argument may go without a name, so a tone passed after the label does not build:
page Trash(path: "/", title: "Trash", description: "Empty the trash.") {
Heading("Trash").h1
Button("Empty the trash", "danger")
}
Write the tone as a flag, Button("Empty the trash").danger, or name it, tone: .danger (E113).
A flag the element does not have. Flags are not a shared vocabulary; each element takes its own, and a word it does not declare stops the build:
page Save(path: "/", title: "Save", description: "A save button.") {
Heading("Save").h1
Button("Save").huge
}
The finding lists the flags Button takes; .lg is its largest size (E103).
A part outside its owner. A part only means something inside the element it belongs to:
page Profile(path: "/", title: "Profile", description: "A profile card.") {
Heading("Profile").h1
Card.Body { Text("Sam, designer") }
}
Wrap it in its owner, Card { Card.Body { … } }, or use a plain Stack (C03).
What you learned
-
Read and write any element call:
Name(value, prop: value).flag { block } -
Pick an enum prop's case by name (
gap: .md) or as a flag (.primary) -
Put HTML attributes such as
aria-*,data-*andidon an element -
Place parts inside their owner:
Card.Header,Table.Row -
Know which built-in family to reach for, and what the compiler checks on each call