Duolith docs

0013. Control flow is written as markup: show, otherwise and keyed lists

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval as part of Specification v0
  • Planning item: none; extends the walking skeleton (0012)

Context

Pages need to show markup only while a condition holds, to show something else otherwise, and to keep list rows (and the focus and typed text inside them) when a list is reordered. The walking skeleton had only <list each as>, which rebuilt every row on any change. Whatever we choose has to compile to native views later, read well to agents, and stay checkable by the analyzer against spec/language/elements.yaml.

Decision

  • **<show when={expr}>…</show>** shows its children while expr is truthy. It may be followed directly (only whitespace between) by **<otherwise>…</otherwise>**, shown while it is falsy. An <otherwise> anywhere else is diagnostic E0107. Neither produces a view; on the web each is a range of nodes between two comment markers, so layout is unchanged.
  • The side that is shown is built once, and rebuilt only when the condition flips, not each time it is re-evaluated.
  • **<list each={items} as="item" key={item.id} index="i">**: key gives each item a stable identity. Rows with the same key are kept (DOM nodes, focus, selection and typed text survive) and only moved; rows whose key is gone are removed; new keys get new rows. A kept row's item and index are live, so its bindings follow the new item. Without key, rows are matched by position. index names the row's position for the row's expressions.
  • These control-flow names live in a new flow: section of elements.yaml, beside elements:, with slot (decision 0015).
  • In the Screen IR, show is its own node kind (IrNode::Show { when, children, otherwise }), not an element, and IrRepeat gains key and index, documented in crates/analyzer/src/ir.rs.

Alternatives considered

OptionWhy not
{#if} / {:else} blocks (Svelte)A second syntax inside markup; the brief asked for markup only, and agents mix up block and tag forms
<show when> with an else attribute naming a fragmentTwo places to read one choice; harder to check
<switch> / <case when> wrapper for every branchMore nesting for the common two-way case; can be added later for many-way choices without changing show
otherwise as a child of showMixes the shown and hidden content in one element, and makes "the children of show" ambiguous
Keys always required on listsStatic lists would carry noise; matching by position is the right default when rows hold no state of their own

Consequences

The native emitter must implement IrNode::Show and keyed recycling against the same IR. Many-way choices are written as a chain of shows today. The web runtime now manages reactions per part of the screen (the screen, each row, each side of a show), so removed parts stop updating.