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,noneoreither(the default when absent); - on an event,
receives: a TypeScript type, such as"{ readonly value: string }"foron: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
| Option | Why not |
|---|---|
| Keep the facts in the language server | A second place that knows the language; it drifts as elements are added |
| A JSON Schema type per event | Handlers 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.