Duolith docs

0029. Language additions the kit needs: conditional classes, bindable props, pieces, roles, disabled and four elements

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval as part of Specification v0
  • Planning item: WP7 (kit)

Context

Building the first half of the kit from the language's own elements (decision 0028) showed gaps: a part could not change its classes with a variant prop, could not pass a bind: through to the field inside it, could not take more than one place of children (a row's leading and trailing content), had no way to say "disabled", "radio" or "invalid", and the language lacked a multi-line field, a checkbox, a range input and a progress bar. Each addition below is the smallest one that closes a gap, and each maps to a native control or trait for the Lynx targets.

Decision

  1. Conditional classes: class:name={condition} on any element applies one utility (any prefixes allowed, such as class:pressed:bg-raised) or one class from the file's style block while the condition is truthy. A utility gets a style table entry of its own, marked with the attribute name, and targets apply those entries after the element's own classes, so a conditional class wins where they disagree (class:text-danger={destructive} over text-ink). An unknown name is E0103; text instead of an expression is E0105. In the IR: IrNode::Element.conditional_classes: [{ condition, style?, class? }].
  2. Bindable props: a prop whose default is bindable(...) (exported by @duolith/client, the default itself at run time) may be assigned by the component and bound inside it, <input bind:value={value} />. A placing file binds it with <TextField bind:value={email} />: the prop shows the state, and the component's writes assign the state. When the placing file binds nothing, writes stay the component's own, so an unbound field still works; that own copy lasts only while the placing file passes the same value, so when a value passed one way (value={name}) changes, the new value shows again. Binding a prop that is not bindable, on either side, is E0108; assigning one is still E0114. In the IR: IrProp.is_bindable and IrNode::Component.two_way.
  3. Pieces: a component writes <slot name="leading" />; a placing file fills it with <piece name="leading">...</piece> directly inside the component. Children outside any piece still go to <slot />. piece is the glossary's word for a named section of a part. A piece elsewhere is E0126; a name the component never shows, or a name not written as text, is E0127; the same name given twice is E0128. In the IR: IrNode::Slot { name }, IrNode::Component.pieces.
  4. Accessibility attributes, common to every element: role takes one word from the roles list in elements.yaml (group, radio-group, radio, status, alert, heading, image, separator; E0124 otherwise), each mapped to the target's role; selected={...} marks the chosen one of a group (on the web aria-checked for a radio, aria-pressed otherwise); invalid on input and textarea (on the web aria-invalid); id and described-by={id}, which points a control at the text that describes it, such as a hint or an error (on the web aria-describedby). A radio-group has one Tab stop, its checked radio or else its first, and the arrow keys move between its radios and choose, wrapping at the ends; on the web the runtime manages tabindex and the keys.
  5. **disabled** on button, input, textarea, toggle, checkbox and slider: the control cannot be used or focused, and the disabled: prefix applies. On a view it only tells assistive technology (on the web aria-disabled). submit={...} on a button may now be an expression.
  6. Kit imports by name: import { Button } from "@duolith/kit" names each part; a default or namespace import of the kit is E0129, and each import statement brings in only the parts it names.
  7. New elements, each the platform's real control: textarea (several lines, bind:value, rows), checkbox (bind:checked), slider (min, max, step, bind:value writing a number) and progress (value from 0 to 1, indeterminate without one). <icon> is decision 0030.

Alternatives considered

OptionWhy not
Variants as a class={expression} stringClass names would no longer be known at build time, so the style table and native styles could not be precomputed
Variants through data-* attributes and attribute selectorsWeb-shaped; Lynx styling of attribute selectors is uncertain, and it is a second way to do one thing
Every prop writable (Svelte 4)Loses E0114, which catches real mistakes; bindable() makes the intent visible, as Svelte 5's $bindable does
Event props only (value plus onInput)Every form would repeat the same handler; bind:value already exists for elements
Named slots called slot="name" attributes on any elementSpreads a component concern onto every element and reuses the word the glossary avoids
Free-form aria-* attributesWeb-only words; a short role list maps to every target's accessibility traits
A range input built from pointer events in the Slider partNot the platform control, worse with screen readers and keyboards

Consequences

  • Runtime: the web mount toggles conditional classes, passes component bind: props as getters and setters, and fills named slots; propsWithDefaults gains a setter. Older hand-written templates without the new fields still mount.
  • Styling: a style block class used conditionally is still scoped, so E0122 keeps parts from leaking.
  • Pieces have no fallback content yet; a part hides an empty wrapper with :empty in its style block.
  • Native emitters will need the same seven additions when they arrive.