@fusion.dev/helix-headless 0.44.0 → 0.46.0

package/dist/filter-input/field/filter-field.d.ts

@@ -43,7 +43,7 @@ import type { HelixHeadlessFilterOperator } from '../operator/filter-operator.js
  * what fills a chip then is whatever the consumer types.
  *
  * @since 0.23.0
- * @status experimental
+ * @status stable
  * @category forms
  * @aliases Facet, Dimension
  * @documentation https://fusion.dev/helix/components/filter-input

package/dist/filter-input/menu/filter-menu.d.ts

@@ -50,7 +50,7 @@ import '../../menu/index.js';
  * rather than inventing one. Refusing `helix-facet` refuses the change.
  *
  * @since 0.25.0
- * @status experimental
+ * @status stable
  * @category forms
  * @aliases FacetPicker, FilterBuilder
  * @documentation https://fusion.dev/helix/components/filter-input

package/dist/filter-input/operator/filter-operator.d.ts

@@ -23,7 +23,7 @@ import { nothing, type PropertyValues } from 'lit';
  * consumer bug and the field reports it rather than guessing.
  *
  * @since 0.23.0
- * @status experimental
+ * @status stable
  * @category forms
  * @aliases Comparator, Predicate
  * @documentation https://fusion.dev/helix/components/filter-input

package/dist/filter-input/root/filter-input-root.d.ts

@@ -83,7 +83,7 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * and the chip goes because the filter went.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category forms
  * @aliases SearchField, FacetInput, TokenInput
  * @documentation https://fusion.dev/helix/components/filter-input

package/dist/listbox/root/listbox-root.js

@@ -77,6 +77,9 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         });
         this.handleSelection = (event) => {
             event.stopPropagation();
+            if (event.defaultPrevented) {
+                return;
+            }
             this.activeValue = event.detail.value;
             this.choose(event.detail.value);
         };

package/dist/option/group/option-group.d.ts

@@ -13,7 +13,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * an option is in without the heading becoming something to land on.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @aliases OptGroup, Section
  * @documentation https://fusion.dev/helix/components/option
  *
@@ -29,6 +29,29 @@ export declare class HelixHeadlessOptionGroup extends HelixElement {
      */
     label: string;
     protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Names the run after the heading it drew, whatever the heading is made of.
+     *
+     * **The string alone was not the name of the heading, it was the name of one
+     * way of writing it.** `label` reached `ariaLabel` and the slot reached the
+     * screen, so a consumer who took the documented `label` slot for a heading
+     * richer than a string got a `role="group"` with no accessible name at all,
+     * and the words they wrote were the one thing a reader could not hear: the
+     * heading carries `aria-hidden`, because the name was supposed to be on the
+     * host already. Set both and they disagreed, the host saying the string and
+     * the panel showing the slot.
+     *
+     * So the host points at the heading, which is the one thing that is always
+     * what a reader sees. `ElementInternals` and not an IDREF, because the host
+     * is in the light DOM and the heading is in this shadow root, which is the
+     * boundary `aria-labelledby` cannot cross. `MixinField.linkHost` does the
+     * same for a field's label and records the measurement.
+     *
+     * Client only. Element references need the nodes to exist, and the server has
+     * the string.
+     */
+    private nameFromHeading;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/option/group/option-group.js

@@ -16,6 +16,14 @@ let HelixHeadlessOptionGroup = class HelixHeadlessOptionGroup extends HelixEleme
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label, role: 'group' });
     }
+    updated(changed) {
+        super.updated(changed);
+        this.nameFromHeading();
+    }
+    nameFromHeading() {
+        const heading = this.partNamed('label');
+        hostAria(this.internals, { labelledBy: heading ? [heading] : [] });
+    }
     render() {
         return html `<span part="label" aria-hidden="true">
         <slot name="label">${this.label}</slot>

package/dist/option/root/option-root.d.ts

@@ -41,7 +41,7 @@ export declare const optionsAmong: (elements: readonly Element[]) => HelixHeadle
  * question and differs between a select and a command palette.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category forms
  * @aliases Item, Choice
  * @documentation https://fusion.dev/helix/components/option

package/dist/radio/group/radio-group.d.ts

@@ -26,7 +26,7 @@ declare const HelixHeadlessRadioGroup_base: (new (...args: any[]) => import("@fu
  * anything is chosen.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @aliases RadioButtons, Choice group
  * @documentation https://fusion.dev/helix/components/radio
  *
@@ -67,6 +67,15 @@ export declare class HelixHeadlessRadioGroup extends HelixHeadlessRadioGroup_bas
      *
      * The item has not moved by the time this runs, unlike a native input, so
      * refusing is simply not writing the value: there is nothing to put back.
+     *
+     * **The radio's own `helix-select` is a request, and the argument that it was
+     * a notification is the one this settles.** That argument ran: the group's
+     * veto is `helix-before-change` a step later, so the item could be read as
+     * announcing a choice the group then decides about. What it leaves out is who
+     * can reach which event. `helix-before-change` is dispatched on the group, so
+     * refusing it needs a listener on the group, and a consumer ruling out one
+     * answer binds to that answer. Two gates in two positions is the shape, and
+     * the item's is the one that was doing nothing.
      */
     private readonly handleSelection;
     /** Writes the answer onto the items, and nothing onto the host. */

package/dist/radio/group/radio-group.js

@@ -17,6 +17,9 @@ let HelixHeadlessRadioGroup = class HelixHeadlessRadioGroup extends MixinControl
         });
         this.handleSelection = (event) => {
             event.stopPropagation();
+            if (event.defaultPrevented) {
+                return;
+            }
             const next = event.detail.value;
             if (next === this.value) {
                 return;
@@ -29,17 +32,13 @@ let HelixHeadlessRadioGroup = class HelixHeadlessRadioGroup extends MixinControl
     }
     place() {
         const items = this.items;
+        const answer = items.find((item) => item.value === this.value);
         for (const item of items) {
-            item.selected = item.value === this.value;
+            item.selected = item === answer;
         }
-        const entered = this.value === '' && items.length > 0 ? items[0] : undefined;
+        const entry = answer ? undefined : items.find((item) => !item.disabled);
         for (const item of items) {
-            if (item === entered) {
-                item.setAttribute('tabindex', '0');
-            }
-            else {
-                item.removeAttribute('tabindex');
-            }
+            item.focusable = item === entry;
         }
     }
     sync() {

package/dist/radio/root/radio-root.d.ts

@@ -20,7 +20,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * be a second source of truth for which one is on.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category forms
  * @aliases Option, Choice
  * @documentation https://fusion.dev/helix/components/radio
@@ -75,6 +75,23 @@ export declare class HelixHeadlessRadio extends HelixElement {
      */
     get defaultSelected(): boolean;
     set defaultSelected(next: boolean);
+    /**
+     * Whether this choice holds the group's tab stop while nothing is chosen.
+     *
+     * The stop rides on the selection, and an unanswered group has no selection,
+     * so without this every choice is `tabindex="-1"` and the keyboard cannot
+     * enter the set at all.
+     *
+     * **Written by the group, with no attribute, and it reaches the control
+     * rather than the host.** A `tabindex` on the host is two faults at once: it
+     * is markup a consumer rendered and their server never sent, which React
+     * reports as a mismatch and does not patch up, and it puts the tab stop on
+     * the element rather than on the `<button role="radio">` inside it, so a
+     * screen reader meets an unnamed box where a native group would have given
+     * them an unchecked radio. `Toggle.Root` carries the same property for the
+     * same reason.
+     */
+    focusable: boolean;
     /**
      * Whether this is the current choice.
      *

package/dist/radio/root/radio-root.js

@@ -11,6 +11,7 @@ let HelixHeadlessRadio = class HelixHeadlessRadio extends HelixElement {
     constructor() {
         super(...arguments);
         this.disabled = false;
+        this.focusable = false;
         this.selected = false;
         this.value = '';
     }
@@ -40,7 +41,7 @@ let HelixHeadlessRadio = class HelixHeadlessRadio extends HelixElement {
       role="radio"
       aria-checked=${this.selected ? 'true' : 'false'}
       ?disabled=${this.disabled}
-      tabindex=${this.selected ? '0' : '-1'}
+      tabindex=${this.selected || this.focusable ? '0' : '-1'}
       @click=${() => this.select()}
     >
       <span part="box"><span part="mark" aria-hidden="true"></span></span>
@@ -52,6 +53,9 @@ let HelixHeadlessRadio = class HelixHeadlessRadio extends HelixElement {
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessRadio.prototype, "disabled", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessRadio.prototype, "focusable", void 0);
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessRadio.prototype, "selected", void 0);

package/dist/skip-link/root/skip-link-root.d.ts

@@ -32,7 +32,7 @@ import { type TemplateResult } from 'lit';
  * broken.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category navigation
  * @aliases Skip navigation, Skip to content
  * @documentation https://fusion.dev/helix/components/skip-link

package/dist/steps/root/steps-root.js

@@ -12,6 +12,9 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
         super(...arguments);
         this.label = 'Steps';
         this.handleSelection = (event) => {
+            if (event.defaultPrevented) {
+                return;
+            }
             this.requestActive(event.detail.value);
         };
         this.handleSlotChange = () => {

package/dist/tabs/root/tabs-root.js

@@ -26,6 +26,9 @@ let HelixHeadlessTabs = class HelixHeadlessTabs extends MixinControllerActive(He
         this.label = 'Tabs';
         this.manual = false;
         this.handleSelection = (event) => {
+            if (event.defaultPrevented) {
+                return;
+            }
             this.requestActive(event.detail.value);
         };
         this.handleSlotChange = () => {

package/dist/toggle/group/toggle-group.js

@@ -22,6 +22,9 @@ let HelixHeadlessToggleGroup = class HelixHeadlessToggleGroup extends MixinContr
             items: () => this.items,
         });
         this.handleSelection = (event) => {
+            if (event.defaultPrevented) {
+                return;
+            }
             this.requestValue(event.detail.value);
         };
     }

package/dist/tree/root/tree-root.js

@@ -23,7 +23,9 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
         super(...arguments);
         this.label = 'Tree';
         this.handleSelection = (event) => {
-            this.requestActive(event.detail.value);
+            if (!event.defaultPrevented) {
+                this.requestActive(event.detail.value);
+            }
             this.syncItems();
         };
         this.handleKeydown = (event) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-headless",
   "description": "Headless component tier. Structure, accessibility, state, and form participation. No styling.",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -46,14 +46,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.44.0",
-    "@fusion.dev/helix-icons": "0.44.0",
+    "@fusion.dev/helix-core": "0.46.0",
+    "@fusion.dev/helix-icons": "0.46.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.44.0",
-    "@fusion.dev/helix-testing": "0.44.0",
+    "@fusion.dev/helix-cem": "0.46.0",
+    "@fusion.dev/helix-testing": "0.46.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",

package/types/jsx.d.ts

@@ -1861,7 +1861,7 @@ server markup never had, which React reports as a mismatch. The one-across
 case is the absent attribute, and the styles read it that way. */
   perView?: (HelixHeadlessCarousel["perView"]) | undefined;
 
-  /** Fired when the slide in view changes, with its index. Cancelable where the carousel is about to move: refusing a control or an indicator takes the decision and nothing moves. A drag has already moved the track, so that one announces after the fact and refusing it does nothing. See `handleScroll`. */
+  /** Fired before the slide in view changes, with the index being asked for. Cancelable: refusing it takes the decision and nothing moves, including a drag, which is put back on the slide the index still holds. See `handleScroll`. */
   "onhelix-select"?: ((e: HelixHeadlessCarouselHelixSelectElementEvent) => void) | undefined;
 };
 
@@ -1961,7 +1961,7 @@ its attribute on upgrade, and the host then carries something a consumer's
 server markup never had, which React reports as a mismatch. The one-across
 case is the absent attribute, and the styles read it that way. */
   "prop:perView"?: (HelixHeadlessCarousel["perView"]) | undefined;
-  /** Fired when the slide in view changes, with its index. Cancelable where the carousel is about to move: refusing a control or an indicator takes the decision and nothing moves. A drag has already moved the track, so that one announces after the fact and refusing it does nothing. See `handleScroll`. */
+  /** Fired before the slide in view changes, with the index being asked for. Cancelable: refusing it takes the decision and nothing moves, including a drag, which is put back on the slide the index still holds. See `handleScroll`. */
   "on:helix-select"?: ((e: HelixHeadlessCarouselHelixSelectElementEvent) => void) | undefined;
 
   /** Set the innerHTML of the element */
@@ -2097,10 +2097,13 @@ Reflected, because every one of the four is a visual state and a stylesheet
 has no other way to know. Absent is a settled message with nothing to
 report, which is what most of a transcript is, and it is the absence of the
 attribute rather than a value of it: there is no initializer, so nothing is
-reflected until something happens. */
+reflected until something happens.
+
+**The turn writes this once, on a retry nobody refused**, and `handleRetry`
+holds the reason. Everything else that moves it is the consumer's. */
   state?: (HelixHeadlessChatMessage["state"]) | undefined;
 
-  /** Fired when the reader asks to send a failed message again, and cancelable. */
+  /** Fired when the reader asks to send a failed message again. Cancelable: a retry that stands puts the turn back on its way, and refusing it leaves the failure and the control offering it exactly where they were. */
   "onhelix-send"?: ((e: HelixHeadlessChatMessageHelixSendElementEvent) => void) | undefined;
 };
 
@@ -2137,9 +2140,12 @@ Reflected, because every one of the four is a visual state and a stylesheet
 has no other way to know. Absent is a settled message with nothing to
 report, which is what most of a transcript is, and it is the absence of the
 attribute rather than a value of it: there is no initializer, so nothing is
-reflected until something happens. */
+reflected until something happens.
+
+**The turn writes this once, on a retry nobody refused**, and `handleRetry`
+holds the reason. Everything else that moves it is the consumer's. */
   "prop:state"?: (HelixHeadlessChatMessage["state"]) | undefined;
-  /** Fired when the reader asks to send a failed message again, and cancelable. */
+  /** Fired when the reader asks to send a failed message again. Cancelable: a retry that stands puts the turn back on its way, and refusing it leaves the failure and the control offering it exactly where they were. */
   "on:helix-send"?: ((e: HelixHeadlessChatMessageHelixSendElementEvent) => void) | undefined;
 
   /** Set the innerHTML of the element */
@@ -6195,7 +6201,7 @@ Here rather than on each control. */
 
   /** Announced once the value has moved. */
   onchange?: ((e: HelixHeadlessFileInputElementEvent) => void) | undefined;
-  /** Fired before the chosen files change, with their names. Cancelable: refusing it takes the decision and nothing moves. */
+  /** Fired before the chosen files change, with their names. Cancelable: refusing it takes the decision and the field keeps the files it had, a pick the browser has already written included. */
   "onhelix-before-change"?: ((
     e: HelixHeadlessFileInputHelixBeforeChangeElementEvent,
   ) => void) | undefined;
@@ -6258,7 +6264,7 @@ Here rather than on each control. */
   "prop:name"?: (HelixHeadlessFileInput["name"]) | undefined;
   /** Announced once the value has moved. */
   "on:change"?: ((e: HelixHeadlessFileInputElementEvent) => void) | undefined;
-  /** Fired before the chosen files change, with their names. Cancelable: refusing it takes the decision and nothing moves. */
+  /** Fired before the chosen files change, with their names. Cancelable: refusing it takes the decision and the field keeps the files it had, a pick the browser has already written included. */
   "on:helix-before-change"?: ((
     e: HelixHeadlessFileInputHelixBeforeChangeElementEvent,
   ) => void) | undefined;
@@ -11715,6 +11721,21 @@ name is the fault `TreeItem` avoids by mirroring to `data-selected`.
 Splitting them means moving what every stylesheet selects on, which is a
 change of its own rather than a property being added. */
   defaultSelected?: (HelixHeadlessRadio["defaultSelected"]) | undefined;
+  /** Whether this choice holds the group's tab stop while nothing is chosen.
+
+The stop rides on the selection, and an unanswered group has no selection,
+so without this every choice is `tabindex="-1"` and the keyboard cannot
+enter the set at all.
+
+**Written by the group, with no attribute, and it reaches the control
+rather than the host.** A `tabindex` on the host is two faults at once: it
+is markup a consumer rendered and their server never sent, which React
+reports as a mismatch and does not patch up, and it puts the tab stop on
+the element rather than on the `<button role="radio">` inside it, so a
+screen reader meets an unnamed box where a native group would have given
+them an unchecked radio. `Toggle.Root` carries the same property for the
+same reason. */
+  focusable?: (HelixHeadlessRadio["focusable"]) | undefined;
 
   /** Fired when this choice is made. Cancelable: refusing it takes the decision and nothing moves. */
   "onhelix-select"?: ((e: HelixHeadlessRadioHelixSelectElementEvent) => void) | undefined;
@@ -11755,6 +11776,21 @@ name is the fault `TreeItem` avoids by mirroring to `data-selected`.
 Splitting them means moving what every stylesheet selects on, which is a
 change of its own rather than a property being added. */
   "prop:defaultSelected"?: (HelixHeadlessRadio["defaultSelected"]) | undefined;
+  /** Whether this choice holds the group's tab stop while nothing is chosen.
+
+The stop rides on the selection, and an unanswered group has no selection,
+so without this every choice is `tabindex="-1"` and the keyboard cannot
+enter the set at all.
+
+**Written by the group, with no attribute, and it reaches the control
+rather than the host.** A `tabindex` on the host is two faults at once: it
+is markup a consumer rendered and their server never sent, which React
+reports as a mismatch and does not patch up, and it puts the tab stop on
+the element rather than on the `<button role="radio">` inside it, so a
+screen reader meets an unnamed box where a native group would have given
+them an unchecked radio. `Toggle.Root` carries the same property for the
+same reason. */
+  "prop:focusable"?: (HelixHeadlessRadio["focusable"]) | undefined;
   /** Fired when this choice is made. Cancelable: refusing it takes the decision and nothing moves. */
   "on:helix-select"?: ((e: HelixHeadlessRadioHelixSelectElementEvent) => void) | undefined;
 
@@ -19148,7 +19184,7 @@ export type CustomElements = {
    *
    * Events that will be emitted by the component.
    *
-   * - `helix-select`: Fired when the slide in view changes, with its index. Cancelable where the carousel is about to move: refusing a control or an indicator takes the decision and nothing moves. A drag has already moved the track, so that one announces after the fact and refusing it does nothing. See `handleScroll`.
+   * - `helix-select`: Fired before the slide in view changes, with the index being asked for. Cancelable: refusing it takes the decision and nothing moves, including a drag, which is put back on the slide the index still holds. See `handleScroll`.
    *
    * ## Slots
    *
@@ -19336,6 +19372,9 @@ export type CustomElements = {
    * report, which is what most of a transcript is, and it is the absence of the
    * attribute rather than a value of it: there is no initializer, so nothing is
    * reflected until something happens.
+   *
+   * **The turn writes this once, on a retry nobody refused**, and `handleRetry`
+   * holds the reason. Everything else that moves it is the consumer's.
    * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
    *
    * **Named `whenSettled` because `settled` is taken four times over**, by
@@ -19361,7 +19400,7 @@ export type CustomElements = {
    *
    * Events that will be emitted by the component.
    *
-   * - `helix-send`: Fired when the reader asks to send a failed message again, and cancelable.
+   * - `helix-send`: Fired when the reader asks to send a failed message again. Cancelable: a retry that stands puts the turn back on its way, and refusing it leaves the failure and the control offering it exactly where they were.
    *
    * ## Slots
    *
@@ -23208,7 +23247,7 @@ export type CustomElements = {
    * Events that will be emitted by the component.
    *
    * - `change`: Announced once the value has moved.
-   * - `helix-before-change`: Fired before the chosen files change, with their names. Cancelable: refusing it takes the decision and nothing moves.
+   * - `helix-before-change`: Fired before the chosen files change, with their names. Cancelable: refusing it takes the decision and the field keeps the files it had, a pick the browser has already written included.
    * - `input`: Announced once the value has moved.
    *
    * ## Slots
@@ -23239,6 +23278,11 @@ export type CustomElements = {
    * picker come back out the same way.
    * - `focus(options?: FocusOptions) => void`: Puts focus on the input, the way a label pointing at one would.
    * - `formResetCallback() => void`: Empties it, which is what a form reset means for a file input.
+   *
+   * Not through `commit`, and that is the point of the split: a reset is the
+   * form's decision and there is nothing here for a listener to refuse. What it
+   * owes is the report and the platform's own announcement, which is what
+   * `settle` is.
    * - `formDisabledCallback(disabled: boolean) => void`: The platform's notice that an ancestor fieldset changed.
    *
    * **The argument is the effective state, and taking it whole is what latched
@@ -29054,6 +29098,20 @@ export type CustomElements = {
    * name is the fault `TreeItem` avoids by mirroring to `data-selected`.
    * Splitting them means moving what every stylesheet selects on, which is a
    * change of its own rather than a property being added. (property only)
+   * - `focusable`: Whether this choice holds the group's tab stop while nothing is chosen.
+   *
+   * The stop rides on the selection, and an unanswered group has no selection,
+   * so without this every choice is `tabindex="-1"` and the keyboard cannot
+   * enter the set at all.
+   *
+   * **Written by the group, with no attribute, and it reaches the control
+   * rather than the host.** A `tabindex` on the host is two faults at once: it
+   * is markup a consumer rendered and their server never sent, which React
+   * reports as a mismatch and does not patch up, and it puts the tab stop on
+   * the element rather than on the `<button role="radio">` inside it, so a
+   * screen reader meets an unnamed box where a native group would have given
+   * them an unchecked radio. `Toggle.Root` carries the same property for the
+   * same reason. (property only)
    * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
    *
    * **Named `whenSettled` because `settled` is taken four times over**, by
@@ -36868,7 +36926,7 @@ export type CustomElementsSolidJs = {
    *
    * Events that will be emitted by the component.
    *
-   * - `helix-select`: Fired when the slide in view changes, with its index. Cancelable where the carousel is about to move: refusing a control or an indicator takes the decision and nothing moves. A drag has already moved the track, so that one announces after the fact and refusing it does nothing. See `handleScroll`.
+   * - `helix-select`: Fired before the slide in view changes, with the index being asked for. Cancelable: refusing it takes the decision and nothing moves, including a drag, which is put back on the slide the index still holds. See `handleScroll`.
    *
    * ## Slots
    *
@@ -37060,6 +37118,9 @@ export type CustomElementsSolidJs = {
    * report, which is what most of a transcript is, and it is the absence of the
    * attribute rather than a value of it: there is no initializer, so nothing is
    * reflected until something happens.
+   *
+   * **The turn writes this once, on a retry nobody refused**, and `handleRetry`
+   * holds the reason. Everything else that moves it is the consumer's.
    * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
    *
    * **Named `whenSettled` because `settled` is taken four times over**, by
@@ -37085,7 +37146,7 @@ export type CustomElementsSolidJs = {
    *
    * Events that will be emitted by the component.
    *
-   * - `helix-send`: Fired when the reader asks to send a failed message again, and cancelable.
+   * - `helix-send`: Fired when the reader asks to send a failed message again. Cancelable: a retry that stands puts the turn back on its way, and refusing it leaves the failure and the control offering it exactly where they were.
    *
    * ## Slots
    *
@@ -40981,7 +41042,7 @@ export type CustomElementsSolidJs = {
    * Events that will be emitted by the component.
    *
    * - `change`: Announced once the value has moved.
-   * - `helix-before-change`: Fired before the chosen files change, with their names. Cancelable: refusing it takes the decision and nothing moves.
+   * - `helix-before-change`: Fired before the chosen files change, with their names. Cancelable: refusing it takes the decision and the field keeps the files it had, a pick the browser has already written included.
    * - `input`: Announced once the value has moved.
    *
    * ## Slots
@@ -41012,6 +41073,11 @@ export type CustomElementsSolidJs = {
    * picker come back out the same way.
    * - `focus(options?: FocusOptions) => void`: Puts focus on the input, the way a label pointing at one would.
    * - `formResetCallback() => void`: Empties it, which is what a form reset means for a file input.
+   *
+   * Not through `commit`, and that is the point of the split: a reset is the
+   * form's decision and there is nothing here for a listener to refuse. What it
+   * owes is the report and the platform's own announcement, which is what
+   * `settle` is.
    * - `formDisabledCallback(disabled: boolean) => void`: The platform's notice that an ancestor fieldset changed.
    *
    * **The argument is the effective state, and taking it whole is what latched
@@ -46914,6 +46980,20 @@ export type CustomElementsSolidJs = {
    * name is the fault `TreeItem` avoids by mirroring to `data-selected`.
    * Splitting them means moving what every stylesheet selects on, which is a
    * change of its own rather than a property being added. (property only)
+   * - `focusable`: Whether this choice holds the group's tab stop while nothing is chosen.
+   *
+   * The stop rides on the selection, and an unanswered group has no selection,
+   * so without this every choice is `tabindex="-1"` and the keyboard cannot
+   * enter the set at all.
+   *
+   * **Written by the group, with no attribute, and it reaches the control
+   * rather than the host.** A `tabindex` on the host is two faults at once: it
+   * is markup a consumer rendered and their server never sent, which React
+   * reports as a mismatch and does not patch up, and it puts the tab stop on
+   * the element rather than on the `<button role="radio">` inside it, so a
+   * screen reader meets an unnamed box where a native group would have given
+   * them an unchecked radio. `Toggle.Root` carries the same property for the
+   * same reason. (property only)
    * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
    *
    * **Named `whenSettled` because `settled` is taken four times over**, by

package/types/vue.d.ts

@@ -1009,7 +1009,7 @@ case is the absent attribute, and the styles read it that way. */
 };
 
 export type HelixHeadlessCarouselVueEvents = {
-  /** Fired when the slide in view changes, with its index. Cancelable where the carousel is about to move: refusing a control or an indicator takes the decision and nothing moves. A drag has already moved the track, so that one announces after the fact and refusing it does nothing. See `handleScroll`. */
+  /** Fired before the slide in view changes, with the index being asked for. Cancelable: refusing it takes the decision and nothing moves, including a drag, which is put back on the slide the index still holds. See `handleScroll`. */
   "helix-select": HelixHeadlessCarouselHelixSelectElementEvent;
 };
 
@@ -1102,12 +1102,15 @@ Reflected, because every one of the four is a visual state and a stylesheet
 has no other way to know. Absent is a settled message with nothing to
 report, which is what most of a transcript is, and it is the absence of the
 attribute rather than a value of it: there is no initializer, so nothing is
-reflected until something happens. */
+reflected until something happens.
+
+**The turn writes this once, on a retry nobody refused**, and `handleRetry`
+holds the reason. Everything else that moves it is the consumer's. */
   state?: (HelixHeadlessChatMessage["state"]) | undefined;
 };
 
 export type HelixHeadlessChatMessageVueEvents = {
-  /** Fired when the reader asks to send a failed message again, and cancelable. */
+  /** Fired when the reader asks to send a failed message again. Cancelable: a retry that stands puts the turn back on its way, and refusing it leaves the failure and the control offering it exactly where they were. */
   "helix-send": HelixHeadlessChatMessageHelixSendElementEvent;
 };
 
@@ -3211,7 +3214,7 @@ Here rather than on each control. */
 export type HelixHeadlessFileInputVueEvents = {
   /** Announced once the value has moved. */
   change: HelixHeadlessFileInputElementEvent;
-  /** Fired before the chosen files change, with their names. Cancelable: refusing it takes the decision and nothing moves. */
+  /** Fired before the chosen files change, with their names. Cancelable: refusing it takes the decision and the field keeps the files it had, a pick the browser has already written included. */
   "helix-before-change": HelixHeadlessFileInputHelixBeforeChangeElementEvent;
   /** Announced once the value has moved. */
   input: HelixHeadlessFileInputElementEvent;
@@ -6021,6 +6024,21 @@ name is the fault `TreeItem` avoids by mirroring to `data-selected`.
 Splitting them means moving what every stylesheet selects on, which is a
 change of its own rather than a property being added. */
   defaultSelected?: (HelixHeadlessRadio["defaultSelected"]) | undefined;
+  /** Whether this choice holds the group's tab stop while nothing is chosen.
+
+The stop rides on the selection, and an unanswered group has no selection,
+so without this every choice is `tabindex="-1"` and the keyboard cannot
+enter the set at all.
+
+**Written by the group, with no attribute, and it reaches the control
+rather than the host.** A `tabindex` on the host is two faults at once: it
+is markup a consumer rendered and their server never sent, which React
+reports as a mismatch and does not patch up, and it puts the tab stop on
+the element rather than on the `<button role="radio">` inside it, so a
+screen reader meets an unnamed box where a native group would have given
+them an unchecked radio. `Toggle.Root` carries the same property for the
+same reason. */
+  focusable?: (HelixHeadlessRadio["focusable"]) | undefined;
 };
 
 export type HelixHeadlessRadioVueEvents = {