Duolith docs

0027. The language definition says how each attribute is written and what each handler receives

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

Context

Editors need two facts the language definition did not hold: whether an attribute's value is written in braces (each={posts}), in quotes (as="post"), not at all (submit), or either way; and the type of the object an event's handler receives. The language server was guessing the first and hand-writing the second.

Decision

spec/language/elements.yaml gains two optional fields, added without changing any existing entry:

  • on an attribute, value: expression, text, none or either (the default when absent);
  • on an event, receives: a TypeScript type, such as "{ readonly value: string }" for on:input. It matches the detail object the runtime passes (packages/client/src/web/events.ts).

The analyzer's Language reads both (Described::value, EventDefinition::receives) without using them yet. The language server inserts attributes the way value says and types each handler with receives in the script view.

Alternatives considered

OptionWhy not
Keep the facts in the language serverA second place that knows the language; it drifts as elements are added
A JSON Schema type per eventHandlers are TypeScript; a TypeScript type is what the editor needs and what people read

Consequences

The analyzer could later report a value written the wrong way (such as each="posts") from value instead of special cases, and reference docs can show both facts. on:change receives { value?, checked? } because the same event serves text fields and toggles; a per-element type can come later.