Add headless HTML controls and interactive element behavior

Author: cowboyd

packages/dom/README.md

@@ -65,7 +65,7 @@ dispatch.keyup({ key: 'Tab' });
 
 Event names preserve case. Capture, target, bubbling, cancellation, listener snapshots, once/passive/signal options, listener objects, and shadow retargeting are exercised by unit tests and selected upstream WPT cases. Listener exceptions are reported without escaping dispatch. The default error reporter queues an uncaught exception; hosts can provide `reportError`.
 
-`element.dispatchEvent()` delivers a synthetic event. It does not move focus, edit text, or perform browser default actions. `Dispatch` is the explicit host-input boundary and implements logical Tab navigation; its dispatched events are still untrusted. See [focus and controls](docs/focus-and-controls.md).
+`element.dispatchEvent()` delivers a synthetic event. Synthetic keyboard and focus events do not run host input actions. Following HTML activation semantics, an uncanceled `MouseEvent("click")` can activate controls; `element.click()` provides that operation. `Dispatch` is the explicit host-input boundary for logical navigation, text editing, keyboard activation and option selection; all generated events remain untrusted. See [focus and controls](docs/focus-and-controls.md).
 
 ## Two independent selection systems
 
@@ -105,6 +105,40 @@ Each environment has an explicit `document.HTMLElement` base and registry. Auton
 
 `parse5` is the only production dependency. The separate `@bomb.sh/dom/parsing` entry uses its HTML tokenizer/tree builder, then creates nodes in this implementation. The core entry does not load it. No LinkeDOM runtime, second DOM hierarchy, framework, browser process, or worker is required.
 
+## Interactive HTML and terminal elements
+
+Forms, buttons, labels, fieldsets, inputs, textareas, selects/options, output,
+progress/meter, details/summary and dialogs have specialized classes and tested
+state transitions. See [forms and element extensions](docs/forms-and-elements.md)
+for examples and limits, and [interactive standards](docs/interactive-standards.md)
+for browser comparisons and known differences.
+
+Arbitrary names still work without registration. To give a terminal element
+application behavior, register its factory explicitly on each document:
+
+```ts
+import { Document, Element } from '@bomb.sh/dom';
+
+class Box extends Element {
+	constructor(document: Document) {
+		super('box', document);
+	}
+	status = 'ready';
+}
+declare module '@bomb.sh/dom' {
+	interface Elements {
+		box: Box;
+	}
+}
+document.registerElement('box', (owner) => new Box(owner));
+document.createElement('box').status; // string, with a real Box instance
+```
+
+Declaration merging is a TypeScript contract: install the factory in every
+application document that relies on that declaration. Registration affects future
+creation, cloning and parsing; it does not upgrade existing nodes. Hyphenated
+custom elements use `document.customElements` and its lifecycle model.
+
 ## Development
 
 From the playground root:

packages/dom/docs/capabilities.md

@@ -17,16 +17,22 @@ The implementation follows the
 where applicable to a headless environment. Eligibility includes native controls,
 links with `href`, valid `tabindex`, and editable elements. Disconnected,
 hidden, inert, disabled, and hidden-type input elements cannot receive focus.
-Disabled fieldsets honor the first-legend exception. There is no CSS visibility,
-geometry, platform focus preference, browsing-context, or modal-dialog model.
+Disabled fieldsets honor the first-legend exception. Closed dialogs and collapsed
+details content are excluded; a details element's first summary remains eligible.
+An open modal dialog makes the rest of its document logically inert. There is no
+CSS visibility, geometry, platform focus preference, or browsing-context model.
 
 Logical Tab order sorts positive `tabindex` values within each document,
 shadow-host, and slot scope, then flattens those scopes. Zero/default values keep
 tree order within their scope. Negative scope owners omit their subtree from
 sequential navigation while allowing programmatic focus. Navigation wraps within
-the document. Shadow delegation preserves an existing delegate and respects
-nested delegation boundaries. Browser chrome, popover/navigation-context scopes,
-radio-group behavior, and platform focus preferences remain unfinished.
+the document, restricted to the topmost modal dialog when one is present. Shadow
+delegation preserves an existing delegate and respects nested delegation boundaries.
+Autofocus runs in a queued task after connection, once per document, and preserves
+focus that was explicitly placed before that task. Dialog opening independently
+honors autofocus. Named radio groups contribute their checked member to sequential
+navigation, or their first eligible member when unchecked. Browser chrome,
+popover/navigation-context scopes and platform focus preferences remain unfinished.
 
 ```ts
 import { Document, Dispatch } from '@bomb.sh/dom';
@@ -45,10 +51,45 @@ dispatch.keyup({ key: 'Tab' }); // Routes keyup to the newly focused button.
 ```
 
 `Dispatch.keydown()` and `keyup()` accept host data and construct synthetic
-`KeyboardEvent` objects. Uncanceled Tab performs explicit logical navigation.
-The DOM event remains untrusted. Dispatching a keyboard or focus event directly
-never performs focus navigation, text editing, activation, or other default
-actions. Byte decoding belongs to the host.
+`KeyboardEvent` objects. Uncanceled Tab performs logical navigation. Enter activates
+buttons and summaries; Space activates buttons, summaries, checkboxes, and radios
+on an uncanceled matching keyup. Radio arrow navigation changes the focused and
+checked member. Select arrow/Home/End keys skip disabled options. Escape requests
+closure of the topmost eligible dialog. Text-input Enter commits a pending change
+and applies implicit form submission. The generated events remain untrusted.
+Dispatching a keyboard or focus event directly never performs these host actions.
+Byte decoding belongs to the host.
+
+Host typing and `dispatch.insertText(text)` edit selection-capable inputs and
+textareas. `beforeinput` can cancel the edit; a successful edit emits `input`.
+Readonly and disabled controls reject editing. Host insertion honors `maxlength`;
+script assignments remain unrestricted. Control edits emit `change` on blur or
+input Enter when the value has changed since the edit session began. Programmatic
+assignments do not independently start an edit session.
+
+Left/Right, Backspace, and Delete use grapheme boundaries while all exposed offsets
+remain UTF-16 code units. Shift extends selection, Home/End go to the start/end of
+the value, and Ctrl/Meta+A selects it. Textarea Enter inserts a line break. The host
+can call `dispatch.select(indices)` to commit an option selection from its own picker.
+IME composition orchestration, clipboard access, visual-line movement, and editing
+non-selection input types such as number/date/email remain unfinished.
+
+```ts
+input.focus();
+document.dispatch.insertText('hello');
+document.dispatch.keydown({ key: 'ArrowLeft', shiftKey: true });
+document.dispatch.insertText('!');
+```
+
+Connected `contenteditable` and `plaintext-only` editing hosts also accept host text
+insertion, range replacement, selection movement, deletion, and plaintext line
+breaks. Their caret is the document's live `Selection`; mixed text/element boundary
+points work without replacing the entire subtree. Input events target the editing
+host. As an explicit conservative editing policy, edits whose selected range
+intersects a `contenteditable=false` island are rejected. Rich-text formatting,
+atomic deletion of noneditable widgets, HTML paragraph creation, and editable
+selection inside shadow trees are unfinished. This is a defined plaintext editing
+subset, not a browser editing-engine compatibility claim.
 
 Input and textarea value selection is separate from document `Selection`.
 The [HTML text selection algorithms](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#textFieldSelection)
@@ -74,6 +115,31 @@ listeners are not copied. A shallow pristine textarea clone retains the current
 value despite having no default-value children. Moving/adopting the existing
 element preserves its selection and value.
 
-Form submission, validity, input-type-specific value sanitization beyond newline
-handling, native editing actions, and select/option value models are unfinished.
-No caret geometry, painting, or terminal width calculation is included.
+Details and dialogs follow the state/event algorithms in the
+[HTML interactive elements specification](https://html.spec.whatwg.org/multipage/interactive-elements.html).
+Details `open` changes queue a coalesced `ToggleEvent`; a nonempty `name` enforces
+one open member per tree. Canceling a summary's click prevents its toggle. Dialog
+`show()`/`showModal()` send cancelable opening `beforetoggle`, focus an autofocus
+candidate, the first eligible descendant, or the dialog itself, and queue `toggle`.
+`requestClose()` sends cancelable `cancel`; `close()` bypasses cancellation, updates
+`returnValue`, restores applicable prior focus, and queues `close`. Closing
+`beforetoggle` is not cancelable. Nested modal dialogs have independent focus
+restoration, and removing a dialog subtree releases modal state, including shadow
+descendants. State is owned by document-keyed weak maps.
+
+```ts
+const dialog = document.createElement('dialog');
+const accept = document.createElement('button');
+accept.textContent = 'Accept';
+accept.addEventListener('click', () => dialog.close('accepted'));
+dialog.append(accept);
+box.append(dialog);
+dialog.showModal();
+```
+
+One intentional standards surprise: removing a modal dialog's `open` attribute
+directly does not release its modal blocking. Use `close()` or remove the dialog.
+`closedBy` controls host Escape requests; an explicit `requestClose()` ignores it.
+Pointer light-dismiss, popovers, browser CloseWatcher activation-history policy,
+caret geometry, painting, and terminal width calculation are outside this tested
+scope.

packages/dom/docs/focus-and-controls.md

@@ -0,0 +1,149 @@
+# Forms and element extensions
+
+`Document.createElement()` constructs actual specialized classes for `input`,
+`textarea`, `button`, `form`, `label`, `fieldset`, `legend`, `select`, `option`,
+`optgroup`, `datalist`, `selectedcontent`, `output`, `progress`, `meter`, `details`,
+`summary`, `dialog`, `template` and `slot`. Arbitrary names use the common Element
+base unless the document registers an application factory.
+
+## Forms without network submission
+
+```ts
+import { Document, FormDataEvent, SubmitEvent } from '@bomb.sh/dom';
+
+const document = new Document();
+const form = document.createElement('form');
+const name = document.createElement('input');
+name.name = 'name';
+name.required = true;
+const submit = document.createElement('button');
+submit.textContent = 'Continue';
+form.append(name, submit);
+document.append(form);
+
+form.addEventListener('submit', (event) => {
+	if (event instanceof SubmitEvent) console.info(event.submitter);
+});
+form.addEventListener('formdata', (event) => {
+	if (event instanceof FormDataEvent) console.info([...event.formData]);
+});
+name.value = 'Ada';
+form.requestSubmit(submit); // Validation → submit → formdata; no network request.
+```
+
+Controls resolve their form through ancestors or an explicit `form` ID in a
+connected document. Moving controls, changing IDs, and adoption update association.
+Labels resolve their control through `for` or a nested labelable element. Disabled
+fieldsets exclude descendants except those inside the first legend. Collections
+are live, protected arrays; they do not claim the browser's complete
+HTMLFormControlsCollection or HTMLOptionsCollection interface.
+
+`checkValidity()` and `reportValidity()` dispatch cancelable `invalid` events;
+reporting focuses an eligible uncanceled invalid control. There is no browser
+validation popup. Validity covers the implemented required/type/pattern/length/
+min/max/step constraints plus custom errors. Invalid values can still be assigned
+by application code. Minimum/maximum text length validity applies to user edits.
+
+`requestSubmit()` validates and sends a cancelable `SubmitEvent`. `submit()` bypasses
+validation and that event. Both construct an entry list and send `FormDataEvent`.
+`method="dialog"` closes the ancestor dialog after collecting entries. Canceling
+`submit` prevents those subsequent actions. Submitting a disconnected form does
+nothing. `reset()` sends a cancelable reset event and restores defaults without
+synthesizing input/change events. `new FormData(form, submitter)` can collect entries
+independently; it uses the host's actual FormData/Blob implementation (Node 22 in
+this workspace). Reentrant entry collection is rejected.
+
+Input/textarea dirty values and checkedness are distinct from attributes/defaults.
+Checkbox click activation happens before listeners and rolls back when canceled.
+Radio groups share a nonempty name, form owner and tree; cloned controls preserve
+current values, checkedness, dirty flags and input indeterminateness. Numeric/date
+input types support applicable `valueAsNumber`, `valueAsDate`, `stepUp` and `stepDown`.
+Programmatic changes invalidate connected state but do not synthesize input/change.
+See [focus and controls](focus-and-controls.md) for host editing and selection.
+
+File-input files/selection, picker UI, numeric editor display state (`badInput`),
+modern color alpha/color-space handling, form-associated custom elements,
+submission encoding/navigation, and complete HTML control properties are unfinished
+or outside the package's scope. No file-selection API or browser window is claimed.
+
+## Choices and calculated values
+
+```ts
+const select = document.createElement('select');
+select.name = 'mode';
+for (const value of ['quick', 'thorough']) {
+	const option = document.createElement('option');
+	option.value = value;
+	option.text = value;
+	select.add(option);
+}
+form.append(select);
+select.value = 'thorough';
+select.focus();
+document.dispatch.select([0]); // Explicit host selection, with input/change events.
+
+const output = document.createElement('output');
+output.defaultValue = 'Ready';
+output.value = 'Running';
+form.append(output);
+form.reset(); // Restores output to Ready, alongside the other controls.
+```
+
+Single and multiple selects preserve option selectedness and dirtiness through
+mutation, cloning, reset and adoption. Disabled options/groups are excluded from
+host selection and form entries. `selectedcontent` mirrors selected option contents
+as snapshots; it is not a general live cloning facility. Datalist exposes options
+without a popup. Output exposes default/current values and `htmlFor` tokens.
+Progress supports determinate/indeterminate position; meter clamps its numeric
+range and thresholds. Painting is the renderer's responsibility.
+
+## Templates and shadow composition
+
+```ts
+import { installParsing } from '@bomb.sh/dom/parsing';
+installParsing(document);
+const container = document.createElement('div');
+container.setHTMLUnsafe(`
+  <section>
+    <template shadowrootmode="open" shadowrootclonable shadowrootserializable>
+      <slot></slot>
+    </template>
+    Light content
+  </section>
+`);
+console.info(container.getHTML({ serializableShadowRoots: true }));
+```
+
+`innerHTML` keeps shadow templates inert. `setHTMLUnsafe` explicitly enables
+declarative shadow parsing for hosts inside the parsed fragment; a top-level
+template does not attach a root to the existing context element. There is no
+sanitizer, and scripts remain inert. A same-mode `attachShadow` on a declarative
+root clears it and returns the same root for hydration. Clonable roots copy their
+shadow descendants even when the host clone is shallow. `getHTML` includes roots
+only when requested through `serializableShadowRoots` or an explicit `shadowRoots`
+list. Ordinary serialization omits them.
+
+```ts
+const host = document.createElement('box');
+const shadow = host.attachShadow({ mode: 'open', slotAssignment: 'manual' });
+const slot = document.createElement('slot');
+shadow.append(slot);
+const first = document.createElement('text');
+const second = document.createTextNode('second');
+host.append(first, second);
+slot.assign(second, first); // Assignment order; light-tree order stays unchanged.
+```
+
+Manual assignments use weak references and survive removal/reinsertion of the
+assigned node. Changing connected composition invalidates the host renderer and
+queues slotchange without inventing a tree mutation record. The package permits
+HTML terminal names as shadow hosts; this deliberately extends the browser's
+restricted valid-shadow-host-name list. SVG/MathML shadow hosts are rejected.
+Scoped registries, ElementInternals and the complete shadow/custom-element
+specification remain unfinished.
+
+Custom-element reactions belong to document-keyed weak state. Mutations share a
+bounded local queue across participating documents and drain it in `finally`;
+direct parser calls also own a scope, including failed parsing. Backup reactions
+receive their own microtask. There is no module-global strong pending-element
+queue that waits for an unrelated document mutation.