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
- Conditional classes:
class:name={condition}on any element applies one utility (any prefixes allowed, such asclass: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}overtext-ink). An unknown name is E0103; text instead of an expression is E0105. In the IR:IrNode::Element.conditional_classes: [{ condition, style?, class? }]. - 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_bindableandIrNode::Component.two_way. - 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 />.pieceis 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. - Accessibility attributes, common to every element:
roletakes one word from theroleslist inelements.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 webaria-checkedfor a radio,aria-pressedotherwise);invalidoninputandtextarea(on the webaria-invalid);idanddescribed-by={id}, which points a control at the text that describes it, such as a hint or an error (on the webaria-describedby). Aradio-grouphas 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 managestabindexand the keys. - **
disabled** onbutton,input,textarea,toggle,checkboxandslider: the control cannot be used or focused, and thedisabled:prefix applies. On aviewit only tells assistive technology (on the webaria-disabled).submit={...}on a button may now be an expression. - 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. - New elements, each the platform's real control:
textarea(several lines,bind:value,rows),checkbox(bind:checked),slider(min,max,step,bind:valuewriting a number) andprogress(valuefrom 0 to 1, indeterminate without one).<icon>is decision 0030.
Alternatives considered
| Option | Why not |
|---|---|
Variants as a class={expression} string | Class 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 selectors | Web-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 element | Spreads a component concern onto every element and reuses the word the glossary avoids |
Free-form aria-* attributes | Web-only words; a short role list maps to every target's accessibility traits |
| A range input built from pointer events in the Slider part | Not 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;propsWithDefaultsgains 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
:emptyin its style block. - Native emitters will need the same seven additions when they arrive.