0014. Derived values, two-way binding and the new events
- Status: Proposed
- Date: 2026-11-14
- Decided by: integrator (internal only), pending Mik's approval as part of Specification v0
- Planning item: D18 (how reactive state is written)
Context
Pages computed totals and counts inline in markup, and every field needed an on:input handler that copied its value into state. D18 settled on one explicit marker per reactive value (state(...)) followed by plain reads and assignments. Computed values and fields should follow the same rule, and the events forms and fields need (change, submit, focus, blur, long press) were missing.
Decision
- **
let total = derived(() => price * quantity)**, exported from@duolith/client. The compiler rewrites reads exactly as forstate, so pages readtotal, never.value. A derived value is recomputed when what it read changes; views that read it update only when its value actually changes; code that assigns state and then reads a derived value in the same handler sees the new value. Assigning to a derived value, in the script or in markup, is diagnostic E0109. - **
bind:value={draft}** on<input>and **bind:checked={on}on the new<toggle>** (a real switch:input type=checkbox role=switchon the web) show a state variable and write the user's changes back, with no handler. The target must be a state variable declared in this file; a derived value, prop, list item or any other expression is diagnostic E0108. In the IR this isIrTwoWay { property, state, read, write }, wherereadandwriteare ordinary expressions, so emitters need no new evaluation rules. - Events (each documented in
elements.yaml):on:change(input, toggle),on:submiton the new **<form>** (never reloads the page),on:focusandon:blur(input, button, toggle),on:longpress(button, view; pointer held still for 500 ms on the web, and the release is not also a press). Inside a form, a button sends the form only when markedsubmit, so other buttons in a form are safe to press.
Alternatives considered
| Option | Why not |
|---|---|
$derived rune or $: labels | Invisible reactivity, the lesson D18 cites against |
state(() => ...) for computed values | D18 reserves the function form of state for loaded data |
Allow bind:value={user.name} (member paths) | Writes into objects held in state would bypass the assignment rule; can be added once state paths are defined |
| HTML's default (every button in a form submits) | A filter or delete button inside a form would submit it by surprise |
Consequences
@duolith/client exports derived, DerivedCell and untracked. A derived value created inside a component stops when the component is removed, a list row with it: on the web through the row's lifetime (packages/client/test/web-row-lifetime.test.ts removes 45 of 50 rows and checks only 5 compute again), on native when the component's view unmounts (packages/client/src/native/instance.ts).