@threadlabs/looma 0.9.2 → 0.10.0

package/components/shared/form-reset.js

@@ -0,0 +1,21 @@
+/**
+ * Calls back once a form reset has restored `control`'s form to its defaults. The browser restores
+ * each native control after the reset event has been dispatched, and a reset button's event runs
+ * its listeners before that, so the callback waits a task.
+ *
+ * @ownership A controller that keeps its own copy of a control's state reads it back here; the
+ * native defaults (defaultValue, defaultChecked, defaultSelected) are what the reset restores.
+ * @lifecycle Returns the function that stops listening.
+ */
+export function afterFormReset(control, callback) {
+  const document = control.ownerDocument;
+  let timer;
+  const onReset = (event) => {
+    if (event.target === control.form) timer = setTimeout(callback);
+  };
+  document.addEventListener("reset", onReset);
+  return () => {
+    clearTimeout(timer);
+    document.removeEventListener("reset", onReset);
+  };
+}

package/components/ui-checkbox/ui-checkbox.html

@@ -1,20 +1,33 @@
 <template component="ui-checkbox" controller="./ui-checkbox.js">
   <defs>
-    <prop name="checked" type="boolean" default="false">Whether the checkbox is checked initially or when set externally.</prop>
+    <prop name="checked" type="boolean" default="false"
+    >Whether the checkbox is checked initially or when set externally. A form reset returns it to this.</prop>
     <prop name="disabled" type="boolean" default="false">Disables the native checkbox, so it cannot be toggled or focused.</prop>
     <prop name="indeterminate" type="boolean" default="false"
     >Shows the mixed state, for a checkbox that summarises a group whose items are partly checked. It sets the native indeterminate property, which is
       independent of checked, so update it as the group changes.</prop>
     <prop name="required" type="boolean" default="false"
     >Marks the native checkbox required, so native form validation treats it as invalid until it is checked.</prop>
+    <prop name="name" type="string" default=""
+    >The native name the checkbox submits under: a form that contains it sends name=value while it is checked, and nothing while it is unchecked, as a native
+      checkbox does. Left empty, it takes no part in form submission.</prop>
     <prop name="value" type="string" default="on"
-    >The value set on the native input and reported in the change event's detail, so one handler can tell checkboxes apart. on by default, as on a native
-      checkbox.</prop>
+    >The value a form submits under name while the checkbox is checked, also reported in the change event's detail so one handler can tell checkboxes apart. on
+      by default, as on a native checkbox.</prop>
     <state name="internalChecked" :value="false"></state>
     <event name="change" type="object({ checked: boolean, value: string, trigger: keyboard | pointer | programmatic })"></event>
   </defs>
   <label>
-    <input type="checkbox" $ref="input" .checked="internalChecked" .indeterminate="indeterminate" :disabled="disabled" :required="required" :value="value">
+    <input
+      type="checkbox"
+      $ref="input"
+      .checked="internalChecked"
+      .indeterminate="indeterminate"
+      :disabled="disabled"
+      :required="required"
+      :name="name"
+      :value="value"
+    >
     <span class="label"><slot></slot></span>
   </label>
   <style>

package/components/ui-checkbox/ui-checkbox.js

@@ -1,12 +1,16 @@
+import { afterFormReset } from "../shared/form-reset.js";
 import { trackTrigger } from "../shared/trigger.js";
 
 // `checked` sets the control initially and whenever it changes; the user's changes update the state.
+// A form reset returns the control to `checked`. Vue writes the checked attribute on every render, so
+// the native default alone cannot hold it there.
 export default function controller(host) {
   const input = host.refs.input;
   const [trigger, stopTracking] = trackTrigger(host);
   let external = host.state.checked;
   host.state.internalChecked = Boolean(external);
   const stop = host.effect(() => {
+    input.defaultChecked = Boolean(host.state.checked);
     if (host.state.checked === external) return;
     external = host.state.checked;
     host.state.internalChecked = Boolean(external);
@@ -16,8 +20,13 @@ export default function controller(host) {
     host.dispatch("change", { checked: input.checked, value: String(host.state.value ?? "on"), trigger: trigger() });
   };
   input.addEventListener("change", onChange);
+  const stopReset = afterFormReset(input, () => {
+    host.state.internalChecked = Boolean(external);
+    input.checked = Boolean(external);
+  });
   return () => {
     stop();
+    stopReset();
     stopTracking();
     input.removeEventListener("change", onChange);
   };

package/components/ui-combobox/ui-combobox.html

@@ -8,11 +8,14 @@
     <prop name="placeholder" type="string" default=""
     >Hint text shown in the empty input, as on a native input. It disappears as the user types, so it never replaces label.</prop>
     <prop name="name" type="string" default=""
-    >The form field name set on the native input. A form submits the input's text, which after a selection is the chosen option's label, not its value; read
-      value-change for the value.</prop>
-    <prop name="value" type="string | null">The selected value in single mode.</prop>
+    >The form field name the combobox submits its value under, never the label shown in the field. Single mode sends one entry: the selected option's value, the
+      typed text when allowFreeText is set and no option is selected, or an empty string. Multiple mode sends one entry per chosen item's value, and nothing
+      when none is chosen. A disabled combobox sends nothing.</prop>
+    <prop name="value" type="string | null"
+    >The selected value in single mode, which a named combobox submits with its form. The field shows the matching option's label, and a form reset returns to
+      this value.</prop>
     <prop name="items" type="list(object({ id: string, value: string, label: string, group?: string, disabled?: boolean }))"
-    >The selected items in multiple mode, as JSON.</prop>
+    >The selected items in multiple mode, as JSON; a named combobox submits each one's value. A form reset returns to these items, or to none when unset.</prop>
     <prop name="multiple" type="boolean" default="false"
     >Lets the user choose several options. Each choice becomes a removable badge before the input, the list stays open between picks, and choosing a checked
       option removes it. value-change then reports the whole list of items; use items, not value, in this mode.</prop>
@@ -25,10 +28,14 @@
     <prop name="allowFreeText" type="boolean" default="false">Allows values that do not match an authored option.</prop>
     <prop name="allowCreate" type="boolean" default="false">Offers the current query as a new option.</prop>
     <prop name="disabled" type="boolean" default="false"
-    >Disables the input, the chosen-item badges, and the help button. The list closes and cannot be opened.</prop>
-    <prop name="readonly" type="boolean" default="false">Whether the current value may be selected but not edited.</prop>
+    >Disables the input and every button in the field: the chosen-item badges, the clear and disclosure buttons, and the help button. The list closes and cannot
+      be opened, the value cannot be cleared, and a named combobox submits nothing with its form.</prop>
+    <prop name="readonly" type="boolean" default="false"
+    >Shows the current value without letting it change: the text can be selected but not edited, the list does not open, and the clear, disclosure, and badge
+      remove buttons are disabled. A named combobox still submits its value.</prop>
     <prop name="required" type="boolean" default="false"
-    >Marks the input required, adds an asterisk to the label, and makes validation report "A value is required." when the field is left empty.</prop>
+    >Requires a value: adds an asterisk to the label, marks the input required for native form validation, and makes validation report "A value is required."
+      when the field is left empty. In multiple mode a chosen item satisfies it, whatever is left in the input.</prop>
     <prop name="size" type="sm | md" default="md"
     >Field height. md is the standard control height; sm is the small control height with tighter padding, for dense forms.</prop>
     <prop name="labelVisibility" type="visible | sr-only" default="visible"
@@ -63,6 +70,7 @@
       :value="{ status: 'pristine', touched: false, dirty: false, issues: [] }"
     ></state>
     <state name="uid" :value="''"></state>
+    <state name="submitted" :value="''"></state>
     <state
       name="groups"
       type="list(object({ name: string, role: group | presentation, label: string | null, rows: list(object({ id: string, value: string, label: string, group?: string, disabled: boolean, selected: boolean, index: integer })) }))"
@@ -135,12 +143,15 @@
           :aria-busy="validationStatus = 'pending'"
           .value="display"
           :placeholder="placeholder"
-          :name="name"
           :disabled="disabled"
           :readonly="readonly"
-          :required="required"
+          :required="required and not (multiple and internalItems[0])"
         >
-        <button $if="clearable" type="button" data-combobox-action="clear" aria-label="Clear">
+        <input $if="name and not multiple" type="hidden" :name="name" :value="submitted" :disabled="disabled">
+        <template $if="name and multiple">
+          <input $each="item of internalItems" $key="item.id" type="hidden" :name="name" :value="item.value" :disabled="disabled">
+        </template>
+        <button $if="clearable" type="button" data-combobox-action="clear" aria-label="Clear" :disabled="disabled or readonly">
           <svg class="affordance-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
             <path d="M7 7l10 10M17 7 7 17"></path>
           </svg>
@@ -152,6 +163,7 @@
           tabindex="-1"
           aria-label="Show suggestions"
           :aria-controls="format('%s-listbox', uid)"
+          :disabled="disabled or readonly"
         >
           <svg
             class="affordance-icon"
@@ -218,7 +230,7 @@
       </div>
       <slot name="footer"></slot>
     </div>
-    <div class="message" :id="format('%s-validation', uid)" :hidden="not validation.issues.length">
+    <div class="message" :id="format('%s-validation', uid)" :hidden="not validation.issues[0]">
       <div $each="issue of validation.issues" $value="issue.message"></div>
     </div>
     <div class="sr-only" role="status" aria-live="polite" aria-atomic="true" $value="statusText"></div>

package/components/ui-combobox/ui-combobox.js

@@ -1,3 +1,4 @@
+import { afterFormReset } from "../shared/form-reset.js";
 import { closeOverlay, createAnchoredSurface, openOverlay } from "../shared/overlay.js";
 
 const instances = new WeakMap();
@@ -288,7 +289,8 @@ export default function controller(host) {
       // Native constraints and the free-text policy; application validation stays in the form.
       const current = config();
       const result = { output: host.state.raw, issues: [] };
-      if (host.state.required && !String(host.state.raw).trim()) result.issues = [...result.issues, { message: "A value is required." }];
+      const empty = host.state.multiple ? !items().length : !String(host.state.raw).trim();
+      if (host.state.required && empty) result.issues = [...result.issues, { message: "A value is required." }];
       else if (host.state.raw && host.state.selected === null && !current.allowFreeText && !current.allowCreate) result.issues = [...result.issues, { message: "Choose a suggestion." }];
       if (result.issues.some((issue) => issue.severity !== "warning")) result.output = undefined;
       if (!run.signal.aborted && alive) setValidation(result);
@@ -335,6 +337,8 @@ export default function controller(host) {
     host.state.groups = groups;
     host.state.creatable = canCreate();
     host.state.createIndex = rows.length;
+    // What a named combobox submits in single mode: the value, never the label the field shows.
+    host.state.submitted = String(host.state.selected ?? (host.state.allowFreeText ? host.state.raw ?? "" : ""));
     host.state.message = host.state.loading ? "Loading suggestions…"
       : host.state.lookupError || (!rows.length && !host.state.creatable ? "No suggestions." : "");
     const validation = host.state.validation ?? { status: "pristine", issues: [] };
@@ -388,6 +392,7 @@ export default function controller(host) {
     const option = event.target.closest?.('[role="option"][data-index]');
     if (option) { choose(Number(option.dataset.index), "pointer"); return; }
     const action = event.target.closest?.("[data-combobox-action]")?.dataset.comboboxAction;
+    if (action && (host.state.disabled || host.state.readonly)) return;
     if (action === "clear") { lastSelection = null; commit(null, "", null, "clear", "pointer"); close(); input.focus(); }
     else if (action === "disclosure") { host.state.expanded ? close() : open("disclosure"); input.focus(); }
     else if (field.contains(event.target) && !event.target.closest?.("button")) input.focus();
@@ -406,18 +411,22 @@ export default function controller(host) {
   const onTooltipOpen = (event) => { if (event.target.closest?.('[data-component~="ui-tooltip"]')) host.state.helpOpen = true; };
   const onTooltipClose = (event) => { if (event.target.closest?.('[data-component~="ui-tooltip"]')) host.state.helpOpen = false; };
 
-  if (host.state.multiple) {
-    host.state.selected = null;
-    host.state.raw = host.state.query ?? "";
-  } else {
-    host.state.selected = host.state.value ?? null;
-    host.state.raw = host.state.query ?? "";
-    if (host.state.query === undefined && !host.state.raw && host.state.selected !== null) {
-      host.state.raw = config().options?.find((row) => row.value === host.state.selected)?.label ?? host.state.selected;
+  // The selection the props describe: where the combobox starts, and where a form reset returns it.
+  const applyDefaults = () => {
+    if (host.state.multiple) {
+      host.state.selected = null;
+      host.state.raw = host.state.query ?? "";
+    } else {
+      host.state.selected = host.state.value ?? null;
+      host.state.raw = host.state.query ?? "";
+      if (host.state.query === undefined && !host.state.raw && host.state.selected !== null) {
+        host.state.raw = config().options?.find((row) => row.value === host.state.selected)?.label ?? host.state.selected;
+      }
+      if (host.state.query === undefined && host.state.selected !== null && host.state.raw === host.state.selected) awaitingLabel = host.state.selected;
     }
-    if (host.state.query === undefined && host.state.selected !== null && host.state.raw === host.state.selected) awaitingLabel = host.state.selected;
-  }
-  host.state.display = host.state.raw;
+    host.state.display = host.state.raw;
+  };
+  applyDefaults();
   initialRaw = host.state.raw;
   host.state.validation = { status: "pristine", touched: false, dirty: false, issues: [] };
   surface = createAnchoredSurface(popup, { anchor: field, placement: "bottom-start" });
@@ -437,6 +446,15 @@ export default function controller(host) {
     host.state.display = label;
     awaitingLabel = null;
   };
+  // Like a native control, a reset reports no change; the browser has already emptied the input.
+  const stopReset = afterFormReset(input, () => {
+    close();
+    lastSelection = null;
+    host.state.internalItems = Array.isArray(host.state.items) ? host.state.items : [];
+    applyDefaults();
+    input.value = host.state.display;
+    resetValidation();
+  });
   const observer = new MutationObserver(relabel);
   observer.observe(authored, { childList: true, subtree: true, characterData: true, attributes: true });
   let lastItems = host.state.items;
@@ -456,6 +474,7 @@ export default function controller(host) {
   return () => {
     alive = false;
     stop();
+    stopReset();
     observer.disconnect();
     for (const [name, listener] of Object.entries(listeners)) element.removeEventListener(name, listener);
     close();

package/components/ui-editable/ui-editable.html

@@ -1,6 +1,8 @@
 <template component="ui-editable" controller="./ui-editable.js">
   <defs>
-    <prop name="value" type="string" default="">The displayed and initial editable value.</prop>
+    <prop name="value" type="string" default=""
+    >The displayed value, and the text the editor starts from. It is not a form field: nothing is submitted with a form, so a form that needs the value copies
+      it from the change event into a field of its own.</prop>
     <prop name="label" type="string" default="Edit value">Accessible name for the editor.</prop>
     <prop name="edit" type="boolean" default="false">Whether edit mode is active initially or when set externally.</prop>
     <prop name="disabled" type="boolean" default="false">Prevents entering or changing edit mode.</prop>

package/components/ui-editable/ui-editable.js

@@ -31,10 +31,11 @@ export default function controller(host) {
     input.tabIndex = host.state.internalEdit ? 0 : -1;
   };
 
-  const setEditing = (next, reason, trigger) => {
+  const setEditing = (next, reason, trigger, returnFocus = true) => {
     if (host.state.disabled || Boolean(host.state.internalEdit) === next) return;
-    // Measured before the input is disabled, which drops focus to the body.
-    const focusWasInside = element.contains(document.activeElement);
+    // Measured before the input is disabled, which drops focus to the body. A press elsewhere has
+    // not moved focus yet, so it says not to return it.
+    const focusWasInside = returnFocus && element.contains(document.activeElement);
     if (next) host.state.draft = host.state.internalValue;
     host.state.internalEdit = next;
     apply();
@@ -51,11 +52,11 @@ export default function controller(host) {
       input.select();
     });
   };
-  const commit = (trigger) => {
+  const commit = (trigger, returnFocus) => {
     const previousValue = String(host.state.internalValue ?? "");
     const value = String(host.state.draft ?? "");
     host.state.internalValue = value;
-    setEditing(false, "commit", trigger);
+    setEditing(false, "commit", trigger, returnFocus);
     if (value !== previousValue) host.dispatch("change", { value, previousValue, trigger });
   };
   const cancel = (reason, trigger) => {
@@ -87,7 +88,7 @@ export default function controller(host) {
   };
   // Leaving the field saves, as with other in-place editors; Escape is the way to discard.
   const onDocumentPointerdown = (event) => {
-    if (host.state.internalEdit && !event.composedPath().includes(element)) commit("pointer");
+    if (host.state.internalEdit && !event.composedPath().includes(element)) commit("pointer", false);
   };
   // Only the input's own blur counts: hiding the display button during the swap also moves focus,
   // and must not end the edit. Tabbing to another control saves; clicks away are handled above.

package/components/ui-input/ui-input.html

@@ -1,8 +1,8 @@
 <template component="ui-input" controller="./ui-input.js">
   <defs>
     <prop name="value" type="string"
-    >The input's text. Setting or changing it replaces the live text; between changes the user's typing stands, so follow input events to keep it in
-      step.</prop>
+    >The input's text. Setting or changing it replaces the live text; between changes the user's typing stands, so follow input events to keep it in step. It is
+      also the input's default, so a form reset returns to it.</prop>
     <prop name="disabled" type="boolean" default="false">Prevents editing and form submission.</prop>
     <prop name="invalid" type="boolean" default="false">Exposes invalid state to assistive technology and styling.</prop>
     <prop name="readonly" type="boolean" default="false">Allows selection without allowing edits.</prop>

package/components/ui-input/ui-input.js

@@ -1,7 +1,10 @@
-// The value attribute only sets the default; a controlled value is applied to the live input.
+// The value attribute only sets the default; a controlled value is applied to the live input. The
+// value is also made the native default, so a form reset returns to it.
 export default function controller(host) {
   return host.effect(() => {
     const value = host.state.value;
-    if (value !== undefined && value !== null && host.element.value !== String(value)) host.element.value = String(value);
+    if (value === undefined || value === null) return;
+    host.element.defaultValue = String(value);
+    if (host.element.value !== String(value)) host.element.value = String(value);
   });
 }

package/components/ui-radio/ui-radio.html

@@ -1,6 +1,8 @@
 <template component="ui-radio" controller="./ui-radio.js">
   <defs>
-    <prop name="checked" type="boolean" default="false">Whether the radio is checked initially or when set externally.</prop>
+    <prop name="checked" type="boolean" default="false"
+    >Whether the radio is checked initially or when set externally. A form reset returns it to this. Inside a ui-radio-group the group's value decides
+      instead.</prop>
     <prop name="disabled" type="boolean" default="false">Disables the native radio, so it cannot be chosen, focused, or reached with the arrow keys.</prop>
     <prop name="name" type="string" default=""
     >The native name that groups radios: of the radios that share a name, only one can be checked, and the arrow keys move between them. Inside a ui-radio-group

package/components/ui-radio/ui-radio.js

@@ -1,12 +1,16 @@
+import { afterFormReset } from "../shared/form-reset.js";
 import { trackTrigger } from "../shared/trigger.js";
 
 // `checked` sets the control initially and whenever it changes; the user's changes update the state.
+// A form reset returns the control to `checked`. Vue writes the checked attribute on every render, so
+// the native default alone cannot hold it there.
 export default function controller(host) {
   const input = host.refs.input;
   const [trigger, stopTracking] = trackTrigger(host);
   let external = host.state.checked;
   host.state.internalChecked = Boolean(external);
   const stop = host.effect(() => {
+    input.defaultChecked = Boolean(host.state.checked);
     if (host.state.checked === external) return;
     external = host.state.checked;
     host.state.internalChecked = Boolean(external);
@@ -17,8 +21,15 @@ export default function controller(host) {
     host.dispatch("change", { checked: input.checked, value: String(host.state.value ?? "on"), trigger: trigger() });
   };
   input.addEventListener("change", onChange);
+  const stopReset = afterFormReset(input, () => {
+    // Inside a ui-radio-group the group's value decides, whichever reset runs first.
+    if (input.closest('[data-component~="ui-radio-group"]')) return;
+    host.state.internalChecked = Boolean(external);
+    input.checked = Boolean(external);
+  });
   return () => {
     stop();
+    stopReset();
     stopTracking();
     input.removeEventListener("change", onChange);
   };

package/components/ui-radio-group/ui-radio-group.html

@@ -2,7 +2,7 @@
   <defs>
     <prop name="value" type="string" default=""
     >The value of the checked radio, initially or when set externally; empty checks none. The user's choice updates it from there and is reported as select and
-      change events.</prop>
+      change events, and a form reset returns the group to it.</prop>
     <prop name="name" type="string" default=""
     >The native name given to every radio in the group, under which a form submits the chosen value. Left empty, the group generates a unique name that keeps
       the radios together, so set it when the choice submits with a form.</prop>
@@ -10,15 +10,17 @@
     >The group's legend, shown above the radios and announced as the group's name. Phrase it as the question the radios answer.</prop>
     <prop name="orientation" type="horizontal | vertical" default="horizontal"
     >horizontal lays the radios out in a row; vertical stacks them in a column. The arrow keys move between radios either way.</prop>
-    <prop name="disabled" type="boolean" default="false">Disables every radio in the group, so no choice can be made.</prop>
+    <prop name="disabled" type="boolean" default="false"
+    >Disables every radio in the group through the native fieldset, so no choice can be made and the group submits nothing with its form. A radio disabled on
+      its own stays disabled when the group is enabled.</prop>
     <prop name="required" type="boolean" default="false"
-    >Not applied yet: the group neither marks its radios required nor checks that one is chosen. Set required on the ui-radio children instead, which native
-      form validation honours for the whole group.</prop>
+    >Makes a choice required, as a required native radio does for its group: the group states aria-required, every radio in it is marked required, and native
+      form validation fails until one is checked.</prop>
     <state name="internalValue" :value="''"></state>
     <event name="select" type="object({ value: string, previousValue: string, trigger: keyboard | pointer | programmatic })"></event>
     <event name="change" type="object({ checked: boolean, value: string, trigger: keyboard | pointer | programmatic })"></event>
   </defs>
-  <fieldset role="radiogroup">
+  <fieldset role="radiogroup" :aria-required="required" :disabled="disabled">
     <legend><template $value="label"></template></legend>
     <slot></slot>
   </fieldset>

package/components/ui-radio-group/ui-radio-group.js

@@ -1,15 +1,20 @@
+import { afterFormReset } from "../shared/form-reset.js";
 import { trackTrigger } from "../shared/trigger.js";
 
 let groups = 0;
 
 // Native radios that share a name already move and check with the arrow keys. The group gives its
-// radios that name, applies a controlled value, and reports the user's choice.
+// radios that name, applies a controlled value, and reports the user's choice. Its fieldset disables
+// them, so a radio's own disabled is never overwritten.
 export default function controller(host) {
   const element = host.element;
   const name = String(host.state.name || `ui-radio-group-${++groups}`);
   const [trigger, stopTracking] = trackTrigger(host);
   const inputs = () => Array.from(element.querySelectorAll('[data-component~="ui-radio"] input[type="radio"]'));
   let external = host.state.value;
+  // A radio's own required survives until the group's required changes, since either one makes the
+  // whole name group required.
+  let required = false;
   host.state.internalValue = String(external ?? "");
   const stop = host.effect(() => {
     if (host.state.value !== external) {
@@ -17,11 +22,14 @@ export default function controller(host) {
       host.state.internalValue = String(external ?? "");
     }
     const value = host.state.internalValue;
-    const disabled = Boolean(host.state.disabled);
+    const applyRequired = Boolean(host.state.required) !== required;
+    required = Boolean(host.state.required);
     for (const input of inputs()) {
+      if (applyRequired) input.required = required;
       input.name = name;
       input.checked = input.value === value;
-      input.disabled = disabled;
+      // The value prop is the choice a form reset returns to.
+      input.defaultChecked = input.value === String(external ?? "");
     }
   });
   const onChange = (event) => {
@@ -34,8 +42,13 @@ export default function controller(host) {
     host.dispatch("change", { checked: true, value: input.value, trigger: how });
   };
   element.addEventListener("change", onChange);
+  const stopReset = afterFormReset(element, () => {
+    host.state.internalValue = String(external ?? "");
+    for (const input of inputs()) input.checked = input.value === host.state.internalValue;
+  });
   return () => {
     stop();
+    stopReset();
     stopTracking();
     element.removeEventListener("change", onChange);
   };

package/components/ui-search-result-row/ui-search-result-row.html

@@ -2,10 +2,10 @@
   <defs>
     <prop name="disabled" type="boolean" default="false">Disables the row's button, so it cannot be chosen or focused, and fades it to 60% opacity.</prop>
     <prop name="selected" type="boolean" default="false"
-    >Highlights the row with its hover surface, to mark the current result. It is visual only and sets no ARIA state, so convey the selection to assistive
-      technology another way where it matters.</prop>
+    >Marks the row as the current result: it gets the hover surface and aria-current="true", which assistive technology announces as current. Set it on one row
+      at a time, such as the result the arrow keys have moved to.</prop>
   </defs>
-  <button type="button" :disabled="disabled">
+  <button type="button" :disabled="disabled" :aria-current="selected">
     <span class="leading"><slot name="leading"></slot></span>
     <span class="content">
       <span class="title"><slot name="title"></slot></span>

package/components/ui-select/ui-select.html

@@ -1,6 +1,8 @@
 <template component="ui-select" controller="./ui-select.js">
   <defs>
-    <prop name="value" type="string">Currently selected option value.</prop>
+    <prop name="value" type="string"
+    >The value of the selected option, initially or when set externally. It is also the default, so a form reset returns to it rather than to the first
+      option.</prop>
     <prop name="disabled" type="boolean" default="false">Prevents selection and form submission.</prop>
     <prop name="invalid" type="boolean" default="false">Exposes invalid state to assistive technology and styling.</prop>
     <prop name="required" type="boolean" default="false">Requires a non-empty option for form validation.</prop>

package/components/ui-select/ui-select.js

@@ -1,10 +1,13 @@
 // A controlled value can arrive before its projected <option> elements, so it is applied again
-// whenever the options change.
+// whenever the options change. The value's option is also marked the native default, so a form
+// reset returns to it rather than to the first option.
 export default function controller(host) {
   const select = host.element;
   const apply = () => {
     const value = host.state.value;
-    if (value !== undefined && value !== null && select.value !== String(value)) select.value = String(value);
+    if (value === undefined || value === null) return;
+    for (const option of select.options) option.defaultSelected = option.value === String(value);
+    if (select.value !== String(value)) select.value = String(value);
   };
   const observer = new MutationObserver(apply);
   observer.observe(select, { childList: true, subtree: true });

package/components/ui-switch/ui-switch.html

@@ -1,16 +1,19 @@
 <template component="ui-switch" controller="./ui-switch.js">
   <defs>
-    <prop name="checked" type="boolean" default="false">Whether the switch is checked initially or when set externally.</prop>
+    <prop name="checked" type="boolean" default="false">Whether the switch is checked initially or when set externally. A form reset returns it to this.</prop>
     <prop name="disabled" type="boolean" default="false">Disables the native switch, so it cannot be toggled or focused.</prop>
     <prop name="required" type="boolean" default="false">Marks the native switch required, so native form validation treats it as invalid until it is on.</prop>
+    <prop name="name" type="string" default=""
+    >The native name the switch submits under: a form that contains it sends name=value while it is on, and nothing while it is off, as a native checkbox does.
+      Left empty, it takes no part in form submission.</prop>
     <prop name="value" type="string" default="on"
-    >The value set on the native input and reported in the change event's detail, so one handler can tell switches apart. on by default, as on a native
-      checkbox.</prop>
+    >The value a form submits under name while the switch is on, also reported in the change event's detail so one handler can tell switches apart. on by
+      default, as on a native checkbox.</prop>
     <state name="internalChecked" :value="false"></state>
     <event name="change" type="object({ checked: boolean, value: string, trigger: keyboard | pointer | programmatic })"></event>
   </defs>
   <label>
-    <input type="checkbox" role="switch" $ref="input" .checked="internalChecked" :disabled="disabled" :required="required" :value="value">
+    <input type="checkbox" role="switch" $ref="input" .checked="internalChecked" :disabled="disabled" :required="required" :name="name" :value="value">
     <span class="label"><slot></slot></span>
   </label>
   <style>

package/components/ui-switch/ui-switch.js

@@ -1,12 +1,16 @@
+import { afterFormReset } from "../shared/form-reset.js";
 import { trackTrigger } from "../shared/trigger.js";
 
 // `checked` sets the control initially and whenever it changes; the user's changes update the state.
+// A form reset returns the control to `checked`. Vue writes the checked attribute on every render, so
+// the native default alone cannot hold it there.
 export default function controller(host) {
   const input = host.refs.input;
   const [trigger, stopTracking] = trackTrigger(host);
   let external = host.state.checked;
   host.state.internalChecked = Boolean(external);
   const stop = host.effect(() => {
+    input.defaultChecked = Boolean(host.state.checked);
     if (host.state.checked === external) return;
     external = host.state.checked;
     host.state.internalChecked = Boolean(external);
@@ -16,8 +20,13 @@ export default function controller(host) {
     host.dispatch("change", { checked: input.checked, value: String(host.state.value ?? "on"), trigger: trigger() });
   };
   input.addEventListener("change", onChange);
+  const stopReset = afterFormReset(input, () => {
+    host.state.internalChecked = Boolean(external);
+    input.checked = Boolean(external);
+  });
   return () => {
     stop();
+    stopReset();
     stopTracking();
     input.removeEventListener("change", onChange);
   };

package/components/ui-textarea/ui-textarea.html

@@ -1,8 +1,8 @@
 <template component="ui-textarea" controller="./ui-textarea.js">
   <defs>
     <prop name="value" type="string"
-    >The textarea's text. Setting or changing it replaces the live text; between changes the user's typing stands, so follow input events to keep it in
-      step.</prop>
+    >The textarea's text. Setting or changing it replaces the live text; between changes the user's typing stands, so follow input events to keep it in step. It
+      is also the textarea's default, so a form reset returns to it.</prop>
     <prop name="disabled" type="boolean" default="false">Prevents editing and form submission.</prop>
     <prop name="invalid" type="boolean" default="false">Exposes invalid state to assistive technology and styling.</prop>
     <prop name="readonly" type="boolean" default="false">Allows selection without allowing edits.</prop>

package/components/ui-textarea/ui-textarea.js

@@ -1,7 +1,10 @@
-// The value attribute only sets the default; a controlled value is applied to the live textarea.
+// The value attribute only sets the default; a controlled value is applied to the live textarea. The
+// value is also made the native default, so a form reset returns to it.
 export default function controller(host) {
   return host.effect(() => {
     const value = host.state.value;
-    if (value !== undefined && value !== null && host.element.value !== String(value)) host.element.value = String(value);
+    if (value === undefined || value === null) return;
+    host.element.defaultValue = String(value);
+    if (host.element.value !== String(value)) host.element.value = String(value);
   });
 }

package/components/ui-tree-item/ui-tree-item.html

@@ -20,8 +20,8 @@
     >The item's kind, for drag rules: it can be dropped before or after only items of the same type, and inside a branch only if that branch's accepts allows
       it. Reported as sourceType and targetType.</prop>
     <prop name="dropScope" type="string" default=""
-    >A label passed through as sourceScope and targetScope in the tree's reorder events. The tree does not enforce it; use it to tell drops within a scope from
-      drops across scopes.</prop>
+    >Names the list the item sits in, such as its parent's id, and is reported as sourceScope and targetScope in the tree's reorder events, so a handler can
+      tell a reorder within one list from a move between lists. It never restricts where an item can be dropped; dragType and accepts do that.</prop>
     <prop name="accepts" type="string" default=""
     >A comma-separated list of the dragType values this branch accepts dropped inside it. Empty accepts any type. It does not affect drops before or after the
       item.</prop>