@threadlabs/looma 0.9.1 → 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-avatar/ui-avatar.html

@@ -1,9 +1,17 @@
 <template component="ui-avatar" controller="./ui-avatar.js">
   <defs>
-    <prop name="src" type="string">Image URL.</prop>
-    <prop name="alt" type="string" default="">alt token.</prop>
-    <prop name="name" type="string" default="">name token.</prop>
-    <prop name="fallback" type="string" default="">fallback token.</prop>
+    <prop name="src" type="string"
+    >The image to show, cropped to fill the circle. Until it loads, or if it fails, the avatar shows initials instead. An img element authored inside the avatar
+      takes precedence over src.</prop>
+    <prop name="alt" type="string" default=""
+    >The avatar's accessible name, announced for it as an image. When empty, name is used, then "Avatar". Initials come from name first, so alt supplies them
+      only when name is empty. An authored img carries its own alt instead.</prop>
+    <prop name="name" type="string" default=""
+    >The person's name. The initials are drawn from it: the first letters of the first two words, or the first two letters of a single word. It is also the
+      accessible name when alt is empty.</prop>
+    <prop name="fallback" type="string" default=""
+    >Text shown instead of the initials derived from name or alt, whenever there is no image. It is uppercased; keep it to a couple of characters, because the
+      circle clips anything wider.</prop>
     <state name="hasImage" :value="false"></state>
     <state name="hasAuthoredImage" :value="false"></state>
     <state name="initials" :value="'?'"></state>

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

@@ -1,7 +1,10 @@
 <template component="ui-avatar-group" controller="./ui-avatar-group.js">
   <defs>
-    <prop name="max" type="number" default="5">max token.</prop>
-    <prop name="label" type="string" default="People">label token.</prop>
+    <prop name="max" type="number" default="5"
+    >How many avatars to show. The rest are hidden and counted in a +N badge after the last visible one. Fractions round down, and 0 hides every avatar behind
+      the badge.</prop>
+    <prop name="label" type="string" default="People"
+    >The group's accessible name, announced for the set of avatars as a whole. Name who they are rather than repeating the default.</prop>
     <state name="overflowCount" :value="0"></state>
   </defs>
   <div role="group" :aria-label="label">

package/components/ui-badge/ui-badge.html

@@ -1,7 +1,11 @@
 <template component="ui-badge">
   <defs>
-    <prop name="variant" type="solid | subtle" default="subtle">variant token.</prop>
-    <prop name="tone" type="neutral | accent | info | success | warning | danger" default="neutral">tone token.</prop>
+    <prop name="variant" type="solid | subtle" default="subtle"
+    >Emphasis. subtle sets the text in its tone over a soft wash of it; solid fills with the tone and uses contrasting text, for a status that has to stand out.
+      The neutral tone looks the same in both.</prop>
+    <prop name="tone" type="neutral | accent | info | success | warning | danger" default="neutral"
+    >Which colour the badge speaks in. neutral is a quiet grey for plain labels; accent draws the eye in the accent colour; info, success, warning, and danger
+      mark a status, so match the tone to what the badge says.</prop>
     <prop name="shape" type="pill | tag" default="pill"
     >Silhouette. pill is rounded at both ends; tag is a label: flat at the start and coming to a point at the end, for a tag or a chosen chip.</prop>
   </defs>

package/components/ui-button/ui-button.html

@@ -3,11 +3,15 @@
     <prop name="variant" type="outline | solid | danger | ghost | link" default="outline"
     >Emphasis: how loudly the button asks. solid fills with its tone, outline draws its tone at the edge over a wash of it, ghost carries only text until it is
       hovered, and link is an inline text action that reads as a link. danger is solid in the danger tone, kept for the call sites that name it.</prop>
-    <prop name="size" type="sm | md | lg" default="md">Control size.</prop>
+    <prop name="size" type="sm | md | lg" default="md"
+    >Height, padding, and type size. sm is the small control height (2rem by default) with tighter padding and smaller text, md is the standard control height
+      (2.5rem), and lg is taller (3rem) with roomier padding.</prop>
     <prop name="tone" type="accent | neutral | danger | success | warning | info" default="accent"
     >Which colour the button speaks in. It applies to every variant, so an outline, a ghost, and a solid in the same tone are the same action at three volumes:
       tone="danger" variant="outline" is a destructive secondary action. neutral is the quiet one, for a button that should not claim a colour.</prop>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
+    <prop name="disabled" type="boolean" default="false"
+    >Makes the button unavailable: it cannot be pressed, its tone fades, and it loses its raised look. A disabled link (as="a" with href) drops its href and
+      states aria-disabled="true" instead, because a link has no native disabled state.</prop>
     <prop name="align" type="center | start" default="center"
     >Content alignment. start lays the content out like a list option: from the start edge, with start-aligned text.</prop>
     <prop name="stretch" type="boolean" default="false">Fills the inline size of its container.</prop>

package/components/ui-callout/ui-callout.html

@@ -1,6 +1,8 @@
 <template component="ui-callout">
   <defs>
-    <prop name="tone" type="info | note | warning | success | danger" default="info">Semantic message tone.</prop>
+    <prop name="tone" type="info | note | warning | success | danger" default="info"
+    >Which kind of message the callout carries, shown by its icon and colour: info (the default) for neutral information, note for an aside in muted grey,
+      warning for a caution, success for a confirmation, and danger for an error or a destructive consequence.</prop>
   </defs>
   <div role="note">
     <span class="icon" aria-hidden="true">

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

@@ -1,15 +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="disabled" type="boolean" default="false">disabled token.</prop>
-    <prop name="indeterminate" type="boolean" default="false">indeterminate token.</prop>
-    <prop name="required" type="boolean" default="false">required token.</prop>
-    <prop name="value" type="string" default="on">value token.</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 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-cluster/ui-cluster.html

@@ -1,7 +1,11 @@
 <template component="ui-cluster">
   <defs>
-    <prop name="gap" type="xs | s | m | l | xl">gap token.</prop>
-    <prop name="align" type="start | center | end | stretch">align token.</prop>
+    <prop name="gap" type="xs | s | m | l | xl"
+    >Space between items, on the spacing scale: xs is 0.5rem, s 0.75rem (also the default), m 1rem, l 1.5rem, and xl 2rem. The --ui-cluster-gap custom property,
+      when set, overrides it.</prop>
+    <prop name="align" type="start | center | end | stretch"
+    >How items line up within each row: center (the default) aligns their middles, start their tops, end their bottoms, and stretch makes every item as tall as
+      its row.</prop>
   </defs>
   <div><slot></slot></div>
   <style>

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

@@ -2,25 +2,54 @@
 <link rel="component" href="../ui-tooltip/ui-tooltip.html">
 <template component="ui-combobox" controller="./ui-combobox.js">
   <defs>
-    <prop name="label" type="string" default="">label token.</prop>
-    <prop name="placeholder" type="string" default="">placeholder token.</prop>
-    <prop name="name" type="string" default="">name token.</prop>
-    <prop name="value" type="string | null">The selected value in single mode.</prop>
+    <prop name="label" type="string" default=""
+    >The field's label, tied to its input and shown above it; required adds an asterisk. It also names the suggestion list. Pair it with
+      labelVisibility="sr-only" when the context already labels the field visibly.</prop>
+    <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 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>
-    <prop name="multiple" type="boolean" default="false">multiple token.</prop>
-    <prop name="tokenSeparators" type="list(string)">tokenSeparators token.</prop>
-    <prop name="query" type="string">query token.</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>
+    <prop name="tokenSeparators" type="list(string)"
+    >Keys that commit the typed text in multiple mode, as KeyboardEvent key values such as "," or ";". The text is added as the option whose label matches it,
+      ignoring case, or with allowCreate is reported as create-item; otherwise it stays in the input.</prop>
+    <prop name="query" type="string"
+    >The input's text, when the consumer controls it. Once set, the consumer owns the text: typing reports query-change, and the input returns to query unless
+      query is updated to match. Leave it unset to let the combobox manage its own text, showing the chosen option's label.</prop>
     <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">disabled token.</prop>
-    <prop name="readonly" type="boolean" default="false">Whether the current value may be selected but not edited.</prop>
-    <prop name="required" type="boolean" default="false">required token.</prop>
-    <prop name="size" type="sm | md" default="md">size token.</prop>
-    <prop name="labelVisibility" type="visible | sr-only" default="visible">labelVisibility token.</prop>
-    <prop name="disclosure" type="boolean" default="false">disclosure token.</prop>
-    <prop name="clearable" type="boolean" default="false">clearable token.</prop>
-    <prop name="help" type="string" default="">help token.</prop>
+    <prop name="disabled" type="boolean" default="false"
+    >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"
+    >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"
+    >visible shows the label above the field; sr-only hides it visually but keeps it as the input's accessible name. Use sr-only only when the surrounding
+      layout already makes the field's purpose clear.</prop>
+    <prop name="disclosure" type="boolean" default="false"
+    >Adds a chevron button that opens and closes the full, unfiltered list of options, for users who would rather browse than type. ArrowDown opens the same
+      list with or without it.</prop>
+    <prop name="clearable" type="boolean" default="false"
+    >Adds a clear button to the field that empties the input and clears the selection, reported as value-change with kind "clear". In multiple mode it clears
+      only the typed text; chosen items stay.</prop>
+    <prop name="help" type="string" default=""
+    >Help text for the field. When set, a help button appears beside the field and opens a tooltip with this text; while it is open, the input is described by
+      it.</prop>
     <state name="internalItems" type="list(object({ id: string, value: string, label: string, group?: string, disabled?: boolean }))" :value="[]"></state>
     <state name="raw" :value="''"></state>
     <state name="display" :value="''"></state>
@@ -41,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 })) }))"
@@ -113,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>
@@ -130,6 +163,7 @@
           tabindex="-1"
           aria-label="Show suggestions"
           :aria-controls="format('%s-listbox', uid)"
+          :disabled="disabled or readonly"
         >
           <svg
             class="affordance-icon"
@@ -196,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-container/ui-container.html

@@ -1,7 +1,10 @@
 <template component="ui-container">
   <defs>
-    <prop name="measure" type="narrow | wide">measure token.</prop>
-    <prop name="gutters" type="s | m | l">gutters token.</prop>
+    <prop name="measure" type="narrow | wide"
+    >The container's maximum width, in characters of the current font: narrow is 45ch, wide is 80ch, and unset is 65ch, a comfortable reading line. The
+      container centres itself when its parent is wider. The --ui-container-measure custom property, when set, overrides it.</prop>
+    <prop name="gutters" type="s | m | l"
+    >Inline padding on both sides, which keeps content off the edges of a narrow screen: s is 0.75rem, m is 1rem (also the default), and l is 1.5rem.</prop>
   </defs>
   <div><slot></slot></div>
   <style>

package/components/ui-disclosure/ui-disclosure.html

@@ -1,9 +1,12 @@
 <template component="ui-disclosure" controller="./ui-disclosure.js">
   <defs>
     <prop name="density" type="comfortable | compact" default="comfortable">Compact trades padding and type size for rows that fit more on screen.</prop>
-    <prop name="summary" type="string" default="Details">summary token.</prop>
-    <prop name="open" type="boolean" default="false">open token.</prop>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
+    <prop name="summary" type="string" default="Details"
+    >The text of the trigger row that opens and closes the disclosure. It is the trigger button's accessible name, so name what the content is.</prop>
+    <prop name="open" type="boolean" default="false"
+    >Whether the disclosure is open initially or when set externally. The trigger toggles it from there, reporting each change as an open or close event.</prop>
+    <prop name="disabled" type="boolean" default="false"
+    >Disables the trigger and mutes its text, so the disclosure keeps its current state and the user cannot toggle it.</prop>
     <state name="internalOpen" :value="false"></state>
     <state name="contentId" :value="''"></state>
     <event

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-editor-mention-menu/ui-editor-mention-menu.html

@@ -3,7 +3,9 @@
     <prop name="open" type="boolean" default="false">Whether the menu is open.</prop>
     <prop name="query" type="string" default="">The text typed after the @.</prop>
     <prop name="items" type="list(object({ id: string, label: string, detail?: string, initials?: string }))">The people the menu offers.</prop>
-    <prop name="selectedIndex" type="integer" default="0">The highlighted person.</prop>
+    <prop name="selectedIndex" type="integer" default="0"
+    >The zero-based index of the highlighted person, capped at the last one shown, and announced through aria-activedescendant. The menu does not handle arrow
+      keys itself: the editor sets this as the user moves, while hovering a person highlights them and reports a highlight event.</prop>
     <prop name="loading" type="boolean" default="false">Whether a search is in progress.</prop>
     <prop
       name="anchorRect"

package/components/ui-editor-slash-menu/ui-editor-slash-menu.html

@@ -4,7 +4,9 @@
     <prop name="open" type="boolean" default="false">Whether the menu is open.</prop>
     <prop name="query" type="string" default="">The text typed after the slash.</prop>
     <prop name="items" type="list(object({ title: string, description: string, icon: string }))">The blocks the menu offers.</prop>
-    <prop name="selectedIndex" type="integer" default="0">The highlighted item.</prop>
+    <prop name="selectedIndex" type="integer" default="0"
+    >The zero-based index of the highlighted item. The menu does not handle arrow keys itself: the editor sets this as the user moves, while hovering an item
+      highlights it and reports a highlight event.</prop>
     <prop
       name="anchorRect"
       type="object({ left?: number, top?: number, right?: number, bottom?: number, x?: number, y?: number, width?: number, height?: number }) | null"

package/components/ui-floating-action-button/ui-floating-action-button.html

@@ -1,8 +1,10 @@
 <template component="ui-floating-action-button">
   <defs>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
-    <prop name="mobileOnly" type="boolean" default="false">mobileOnly token.</prop>
-    <prop name="label" type="string" default="">label token.</prop>
+    <prop name="disabled" type="boolean" default="false">Disables the button, so it cannot be pressed or focused, and fades it to 60% opacity.</prop>
+    <prop name="mobileOnly" type="boolean" default="false"
+    >Hides the button on viewports 768px wide and wider, for a shortcut that only phones need. Make sure the action is reachable another way at those
+      widths.</prop>
+    <prop name="label" type="string" default="">The button's accessible name. The button usually holds only an icon, so name the action it performs.</prop>
   </defs>
   <button type="button" :aria-label="label" :disabled="disabled"><slot></slot></button>
   <style>

package/components/ui-form-field/ui-form-field.html

@@ -1,8 +1,14 @@
 <template component="ui-form-field" controller="./ui-form-field.js">
   <defs>
-    <prop name="invalid" type="boolean" default="false">invalid token.</prop>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
-    <prop name="required" type="boolean" default="false">required token.</prop>
+    <prop name="invalid" type="boolean" default="false"
+    >Marks the field's control invalid by setting aria-invalid on it. Pair it with content in the error slot, which the field already links to the control as
+      its description.</prop>
+    <prop name="disabled" type="boolean" default="false"
+    >Disables the field's control: the first input, textarea, or select inside it. The field writes this to the control whenever it updates, so set it here
+      rather than on the control.</prop>
+    <prop name="required" type="boolean" default="false"
+    >Marks the field's control required, for native form validation. Like disabled, it is written to the control, so set it here rather than on the control. It
+      adds no visual marker; show one in the label if the form needs it.</prop>
   </defs>
   <div>
     <div class="label"><slot name="label"></slot></div>

package/components/ui-grid/ui-grid.html

@@ -1,7 +1,11 @@
 <template component="ui-grid">
   <defs>
-    <prop name="gap" type="xs | s | m | l | xl">gap token.</prop>
-    <prop name="min" type="sm | md | lg">min token.</prop>
+    <prop name="gap" type="xs | s | m | l | xl"
+    >Space between cells, on the spacing scale: xs is 0.5rem, s 0.75rem, m 1rem (also the default), l 1.5rem, and xl 2rem. The --ui-grid-gap custom property,
+      when set, overrides it.</prop>
+    <prop name="min" type="sm | md | lg"
+    >The narrowest a column may get before the grid drops to fewer columns: sm is 12rem (also the default), md is 16rem, and lg is 20rem. The grid fits as many
+      equal columns as its width allows, and a single column never overflows a narrower container.</prop>
   </defs>
   <div><slot></slot></div>
   <style>

package/components/ui-icon/ui-icon.html

@@ -1,6 +1,8 @@
 <template component="ui-icon" controller="./ui-icon.js">
   <defs>
-    <prop name="name" type="string" default="">The icon's name.</prop>
+    <prop name="name" type="string" default=""
+    >Which icon to draw, by its name in Looma's icon set (LOOMA_ICONS), such as "align-left". An unknown or empty name draws nothing. The icon is hidden from
+      assistive technology, so name the control it sits in.</prop>
     <state
       name="shapes"
       type="list(object({ tag: path | circle | rect, d?: string, cx?: string, cy?: string, r?: string, x?: string, y?: string, width?: string, height?: string, rx?: string }))"

package/components/ui-icon-button/ui-icon-button.html

@@ -1,10 +1,17 @@
 <template component="ui-icon-button" controller="./ui-icon-button.js">
   <defs>
-    <prop name="disabled" type="boolean" default="false">disabled token.</prop>
+    <prop name="disabled" type="boolean" default="false"
+    >Disables the button, so it cannot be pressed or focused, and greys the icon; outline and solid also take the disabled surface.</prop>
     <prop name="label" type="string">Accessible name for the icon.</prop>
-    <prop name="size" type="sm | md | lg" default="md">size token.</prop>
-    <prop name="variant" type="ghost | outline | solid" default="ghost">variant token.</prop>
-    <prop name="anticipatory" type="boolean" default="false">anticipatory token.</prop>
+    <prop name="size" type="sm | md | lg" default="md"
+    >Button and icon size together: sm is 1.75rem with a small icon, md is 2rem, and lg is 2.5rem with a large icon. On touch, every size gets an invisible hit
+      area of at least 44px.</prop>
+    <prop name="variant" type="ghost | outline | solid" default="ghost"
+    >Emphasis. ghost shows only the icon until it is hovered, for toolbars and dense rows; outline adds a border on the default surface; solid fills with the
+      accent colour, for the one primary action in a group.</prop>
+    <prop name="anticipatory" type="boolean" default="false"
+    >Keeps the button out of sight until it is wanted: at rest a fine pointer sees only a small guide dot, and the button appears on hover, on focus, or when
+      the pointer comes near inside a ui-affordance-scope. Touch devices and the solid variant always show it.</prop>
     <prop name="round" type="boolean" default="false">Use a fully circular shape.</prop>
   </defs>
   <button :disabled="disabled" type="button" :aria-label="label"><slot></slot></button>