@fusion.dev/helix-headless 0.45.0 → 0.46.0

package/custom-elements.json

@@ -10397,7 +10397,7 @@
               "type": {
                 "text": "HelixSelectEvent"
               },
-              "description": "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`.",
+              "description": "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`.",
               "name": "helix-select",
               "reactProp": "onhelix-select"
             }
@@ -11388,7 +11388,7 @@
               "type": {
                 "text": "'failed' | 'sending' | 'sent' | 'streaming' | undefined"
               },
-              "description": "What has happened to it.\n\nReflected, because every one of the four is a visual state and a stylesheet\nhas no other way to know. Absent is a settled message with nothing to\nreport, which is what most of a transcript is, and it is the absence of the\nattribute rather than a value of it: there is no initializer, so nothing is\nreflected until something happens.",
+              "description": "What has happened to it.\n\nReflected, because every one of the four is a visual state and a stylesheet\nhas no other way to know. Absent is a settled message with nothing to\nreport, which is what most of a transcript is, and it is the absence of the\nattribute rather than a value of it: there is no initializer, so nothing is\nreflected until something happens.\n\n**The turn writes this once, on a retry nobody refused**, and `handleRetry`\nholds the reason. Everything else that moves it is the consumer's.",
               "attribute": "state",
               "reflects": true
             },
@@ -11477,7 +11477,7 @@
               "name": "handleRetry",
               "privacy": "private",
               "readonly": true,
-              "description": "Retry is `helix-send` again, from the message rather than the composer.\n\n**Not an event of its own**, because a retry is the same request: the reader\nis offering what they wrote, and the only difference is which element is\noffering it. A listener that wants to tell them apart has `event.target`,\nwhich is the message on a retry and the composer on a first send, and that\nis a distinction the DOM already makes without a second name for it."
+              "description": "Retry is `helix-send` again, from the message rather than the composer.\n\n**Not an event of its own**, because a retry is the same request: the reader\nis offering what they wrote, and the only difference is which element is\noffering it. A listener that wants to tell them apart has `event.target`,\nwhich is the message on a retry and the composer on a first send, and that\nis a distinction the DOM already makes without a second name for it.\n\n**Through `requestChange`, and the turn is what moves.** `helix-send` is\ncancelable because the composer clears only when nobody refused, and this\ndispatch had nothing behind it: the reader pressed the control, the turn sat\nat \"Not sent\" with the same control still on it, and `preventDefault()`\nrefused a decision nobody here was about to take. A retry that stands is a\nturn on its way, which is what `sending` means, so that is the default\naction and refusing it leaves the failure exactly where it was. A consumer\nwho wants something else refuses and assigns `state` themselves, which is\nhow control is taken from every other stateful element in the library."
             },
             {
               "kind": "field",
@@ -11809,7 +11809,7 @@
               "type": {
                 "text": "HelixSendEvent"
               },
-              "description": "Fired when the reader asks to send a failed message again, and cancelable.",
+              "description": "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.",
               "name": "helix-send",
               "reactProp": "onhelix-send"
             }
@@ -11870,7 +11870,7 @@
               "type": {
                 "text": "'failed' | 'sending' | 'sent' | 'streaming' | undefined"
               },
-              "description": "What has happened to it.\n\nReflected, because every one of the four is a visual state and a stylesheet\nhas no other way to know. Absent is a settled message with nothing to\nreport, which is what most of a transcript is, and it is the absence of the\nattribute rather than a value of it: there is no initializer, so nothing is\nreflected until something happens.",
+              "description": "What has happened to it.\n\nReflected, because every one of the four is a visual state and a stylesheet\nhas no other way to know. Absent is a settled message with nothing to\nreport, which is what most of a transcript is, and it is the absence of the\nattribute rather than a value of it: there is no initializer, so nothing is\nreflected until something happens.\n\n**The turn writes this once, on a retry nobody refused**, and `handleRetry`\nholds the reason. Everything else that moves it is the consumer's.",
               "fieldName": "state"
             }
           ],
@@ -19257,6 +19257,17 @@
               "readonly": true,
               "description": "Dragging in the square.\n\nThe two ranges are the state, so this reads a point and writes to them\nrather than keeping a position of its own. Pointer capture, so a drag that\nleaves the square keeps going: leaving and coming back is how a reader\nreaches a corner, and without it the handle stops wherever the pointer left."
             },
+            {
+              "kind": "method",
+              "name": "sync",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Reports the color to the form.\n\n**The one thing a form-associated element owes, and this element owed it\nfrom the start without paying.** It extends `HelixFormElement`, takes\n`MixinControllerValue` and carries `name`, so a consumer writing\n`<helix-color-picker name=\"brand\">` inside a form has every reason to\nexpect an entry, and the form carried none: no error, nothing in the\nmarkup to look at, and a field silently missing from the submission. Its\ntwo siblings in the same composition position, Color Input and Slider,\nboth report.\n\n`null` rather than an empty string where there is no color, which is the\ndifference between a control that submits nothing and one that submits a\nblank. There is no `setValidity` beside it: this element does not take\n`MixinField`, and every validity member of `ElementInternals` is the\nconsumer's to reach through the field that wraps it."
+            },
             {
               "kind": "method",
               "name": "focus",
@@ -36529,9 +36540,63 @@
                 "text": "removeAt(at: number) => void"
               }
             },
+            {
+              "kind": "field",
+              "name": "committed",
+              "type": {
+                "text": "File[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "The files this element last stood behind, so a refusal has somewhere to go.\n\nThe picker and a drop both write the input before anything here runs, so\nthe list being replaced is gone by the time the request is announced.\nNothing else records it: `files` reads the control, which is already the\nnew answer."
+            },
             {
               "kind": "method",
-              "name": "announce",
+              "name": "commit",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "next",
+                  "type": {
+                    "text": "File[]"
+                  }
+                }
+              ],
+              "description": "Asks for a set of files, and puts them in unless a listener refuses.\n\n**The request was announced after the fact and nothing read it.** This\nelement dispatched `helix-before-change` from `announce`, after the input\nhad taken the files and after `setFormValue` had reported them, and\ndiscarded what the dispatch returned: an `@event` line promising that\nrefusing it left nothing moved, over a veto with no reader. The other\ndirection of that same fault is what `requestChange` exists to prevent, so\nthis goes through it like every other value control.\n\n**A refusal puts the input back rather than stopping an assignment**, which\nis the shape a file input forces. Two of the four paths in are the browser\nwriting `control.files` before this element hears anything, so there is no\nassignment left to skip and the honest answer is to restore the list the\nelement last stood behind."
+            },
+            {
+              "kind": "method",
+              "name": "put",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "control",
+                  "type": {
+                    "text": "HTMLInputElement"
+                  }
+                },
+                {
+                  "name": "files",
+                  "type": {
+                    "text": "File[]"
+                  }
+                }
+              ],
+              "description": "Writes a list onto the input, which is the only way a `FileList` is built.\n\n`value = ''` for the empty case rather than an empty `DataTransfer`,\nbecause emptying is the one write a control accepts everywhere and a\nharness without `DataTransfer` still has to be able to clear."
+            },
+            {
+              "kind": "method",
+              "name": "settle",
               "privacy": "private",
               "return": {
                 "type": {
@@ -36611,7 +36676,7 @@
                   "text": "void"
                 }
               },
-              "description": "Empties it, which is what a form reset means for a file input.",
+              "description": "Empties it, which is what a form reset means for a file input.\n\nNot through `commit`, and that is the point of the split: a reset is the\nform's decision and there is nothing here for a listener to refuse. What it\nowes is the report and the platform's own announcement, which is what\n`settle` is.",
               "type": {
                 "text": "formResetCallback() => void"
               }
@@ -37353,7 +37418,7 @@
               "type": {
                 "text": "HelixBeforeChangeEvent"
               },
-              "description": "Fired before the chosen files change, with their names. Cancelable: refusing it takes the decision and nothing moves.",
+              "description": "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.",
               "name": "helix-before-change",
               "reactProp": "onhelix-before-change"
             },
@@ -70356,7 +70421,7 @@
               "name": "handleSelection",
               "privacy": "private",
               "readonly": true,
-              "description": "Announces before it applies, so a listener can refuse the change.\n\nThe item has not moved by the time this runs, unlike a native input, so\nrefusing is simply not writing the value: there is nothing to put back."
+              "description": "Announces before it applies, so a listener can refuse the change.\n\nThe item has not moved by the time this runs, unlike a native input, so\nrefusing is simply not writing the value: there is nothing to put back.\n\n**The radio's own `helix-select` is a request, and the argument that it was\na notification is the one this settles.** That argument ran: the group's\nveto is `helix-before-change` a step later, so the item could be read as\nannouncing a choice the group then decides about. What it leaves out is who\ncan reach which event. `helix-before-change` is dispatched on the group, so\nrefusing it needs a listener on the group, and a consumer ruling out one\nanswer binds to that answer. Two gates in two positions is the shape, and\nthe item's is the one that was doing nothing."
             },
             {
               "kind": "method",

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

@@ -27,7 +27,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @slot - The slides.
  *
- * @event {HelixSelectEvent} 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`.
+ * @event {HelixSelectEvent} 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`.
  *
  * @csspart controls - The row of controls.
  * @csspart indicator - One of them, and a way to reach that slide.

package/dist/carousel/root/carousel-root.js

@@ -60,9 +60,19 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
             if (nearest === this.index) {
                 return;
             }
-            this.indexState = nearest;
-            this.requestUpdate('index');
-            this.dispatchEvent(new HelixSelectEvent({ value: String(nearest) }));
+            const applied = requestChange({
+                apply: (value) => {
+                    const previous = this.index;
+                    this.indexState = value;
+                    this.requestUpdate('index', previous);
+                },
+                event: (value) => new HelixSelectEvent({ value: String(value) }),
+                host: this,
+                next: nearest,
+            });
+            if (!applied) {
+                this.scrollToIndex();
+            }
         };
         this.scrollFrame = 0;
         this.stopped = false;

package/dist/chat/message/chat-message.d.ts

@@ -35,7 +35,7 @@ export declare const FAILED_LABEL = "Not sent";
  * indicator, so slotting nothing is what this has always done.
  * @slot sources - What it was said from: citations, documents, a retrieved page.
  *
- * @event {HelixSendEvent} helix-send - Fired when the reader asks to send a failed message again, and cancelable.
+ * @event {HelixSendEvent} 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.
  *
  * @csspart actions - The controls offered on the turn, beside its time.
  * @csspart avatar - The leading slot's box.
@@ -91,6 +91,9 @@ export declare class HelixHeadlessChatMessage extends HelixElement {
      * 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.
      */
     state?: 'failed' | 'sending' | 'sent' | 'streaming';
     /**
@@ -180,6 +183,16 @@ export declare class HelixHeadlessChatMessage extends HelixElement {
      * offering it. A listener that wants to tell them apart has `event.target`,
      * which is the message on a retry and the composer on a first send, and that
      * is a distinction the DOM already makes without a second name for it.
+     *
+     * **Through `requestChange`, and the turn is what moves.** `helix-send` is
+     * cancelable because the composer clears only when nobody refused, and this
+     * dispatch had nothing behind it: the reader pressed the control, the turn sat
+     * at "Not sent" with the same control still on it, and `preventDefault()`
+     * refused a decision nobody here was about to take. A retry that stands is a
+     * turn on its way, which is what `sending` means, so that is the default
+     * action and refusing it leaves the failure exactly where it was. A consumer
+     * who wants something else refuses and assigns `state` themselves, which is
+     * how control is taken from every other stateful element in the library.
      */
     private readonly handleRetry;
 }

package/dist/chat/message/chat-message.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, HelixElement, HelixSendEvent, hostAria, relativeTime, slotFilled, TONE_MARKS, } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, HelixSendEvent, hostAria, relativeTime, requestChange, slotFilled, TONE_MARKS, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
@@ -24,7 +24,14 @@ let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixEleme
         };
         this.handleRetry = (event) => {
             event.stopPropagation();
-            this.dispatchEvent(new HelixSendEvent({ value: this.textContent?.trim() ?? '' }));
+            requestChange({
+                apply: (next) => {
+                    this.state = next;
+                },
+                event: () => new HelixSendEvent({ value: this.textContent?.trim() ?? '' }),
+                host: this,
+                next: 'sending',
+            });
         };
     }
     get moment() {

package/dist/checkbox-group/root/checkbox-group-root.js

@@ -23,6 +23,9 @@ let HelixHeadlessCheckboxGroup = class HelixHeadlessCheckboxGroup extends MixinF
                 return;
             }
             event.stopImmediatePropagation();
+            if (event.defaultPrevented) {
+                return;
+            }
             const wanted = event.detail.checked;
             const next = this.boxes
                 .filter((box) => (box === changed ? wanted : box.checked))

package/dist/color-picker/root/color-picker-root.d.ts

@@ -223,6 +223,25 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      */
     private readonly handleGridPointer;
     protected firstUpdated(changed: import('lit').PropertyValues): void;
+    /**
+     * Reports the color to the form.
+     *
+     * **The one thing a form-associated element owes, and this element owed it
+     * from the start without paying.** It extends `HelixFormElement`, takes
+     * `MixinControllerValue` and carries `name`, so a consumer writing
+     * `<helix-color-picker name="brand">` inside a form has every reason to
+     * expect an entry, and the form carried none: no error, nothing in the
+     * markup to look at, and a field silently missing from the submission. Its
+     * two siblings in the same composition position, Color Input and Slider,
+     * both report.
+     *
+     * `null` rather than an empty string where there is no color, which is the
+     * difference between a control that submits nothing and one that submits a
+     * blank. There is no `setValidity` beside it: this element does not take
+     * `MixinField`, and every validity member of `ElementInternals` is the
+     * consumer's to reach through the field that wraps it.
+     */
+    private sync;
     protected updated(changed: import('lit').PropertyValues): void;
     /** Puts the keyboard on the square, which is the control a reader wants. */
     focus(options?: FocusOptions): void;

package/dist/color-picker/root/color-picker-root.js

@@ -106,8 +106,12 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinContr
         super.firstUpdated(changed);
         this.finishHydration();
     }
+    sync() {
+        this.internals.setFormValue(this.value === '' ? null : this.value);
+    }
     updated(changed) {
         super.updated(changed);
+        this.sync();
         if (changed.has('value')) {
             if (parseColor(this.value)) {
                 this.settled = this.value;

package/dist/drilldown/root/drilldown-root.js

@@ -35,7 +35,11 @@ let HelixHeadlessDrilldown = class HelixHeadlessDrilldown extends MixinCollectio
             }
             if (this.drilldown.hasPage(item)) {
                 event.stopPropagation();
-                this.enter(item);
+                queueMicrotask(() => {
+                    if (!event.defaultPrevented) {
+                        this.enter(item);
+                    }
+                });
             }
         };
         this.handleKeydown = (event) => {

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

@@ -28,7 +28,7 @@ declare const HelixHeadlessFileInput_base: (new (...args: any[]) => import("@fus
  * @slot trigger - What the reader presses to open the picker.
  *
  * @event {Event} change - Announced once the value has moved.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the chosen files change, with their names. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixBeforeChangeEvent} 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.
  * @event {Event} input - Announced once the value has moved.
  *
  * @csspart control - The file input itself, which carries the label and validity.
@@ -129,8 +129,43 @@ export declare class HelixHeadlessFileInput extends HelixHeadlessFileInput_base
      * picker come back out the same way.
      */
     removeAt(at: number): void;
+    /**
+     * The files this element last stood behind, so a refusal has somewhere to go.
+     *
+     * The picker and a drop both write the input before anything here runs, so
+     * the list being replaced is gone by the time the request is announced.
+     * Nothing else records it: `files` reads the control, which is already the
+     * new answer.
+     */
+    private committed;
+    /**
+     * Asks for a set of files, and puts them in unless a listener refuses.
+     *
+     * **The request was announced after the fact and nothing read it.** This
+     * element dispatched `helix-before-change` from `announce`, after the input
+     * had taken the files and after `setFormValue` had reported them, and
+     * discarded what the dispatch returned: an `@event` line promising that
+     * refusing it left nothing moved, over a veto with no reader. The other
+     * direction of that same fault is what `requestChange` exists to prevent, so
+     * this goes through it like every other value control.
+     *
+     * **A refusal puts the input back rather than stopping an assignment**, which
+     * is the shape a file input forces. Two of the four paths in are the browser
+     * writing `control.files` before this element hears anything, so there is no
+     * assignment left to skip and the honest answer is to restore the list the
+     * element last stood behind.
+     */
+    private commit;
+    /**
+     * Writes a list onto the input, which is the only way a `FileList` is built.
+     *
+     * `value = ''` for the empty case rather than an empty `DataTransfer`,
+     * because emptying is the one write a control accepts everywhere and a
+     * harness without `DataTransfer` still has to be able to clear.
+     */
+    private put;
     /** Says what is now chosen, by name, and puts it in the form. */
-    private announce;
+    private settle;
     /**
      * Reports the files and the validity the host stands behind.
      *
@@ -148,7 +183,14 @@ export declare class HelixHeadlessFileInput extends HelixHeadlessFileInput_base
     protected firstUpdated(changed: PropertyValues): void;
     /** Puts focus on the input, the way a label pointing at one would. */
     focus(options?: FocusOptions): void;
-    /** Empties it, which is what a form reset means for a file input. */
+    /**
+     * 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.
+     */
     formResetCallback(): void;
     /**
      * What is known about a chosen file, as tags, behind a seam the styled tier

package/dist/file-input/root/file-input-root.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { AriaForwardController, customElement, drawIcon, HelixBeforeChangeEvent, HelixFormElement, MixinField, restoreValue, } from '@fusion.dev/helix-core';
+import { AriaForwardController, customElement, drawIcon, HelixBeforeChangeEvent, HelixFormElement, MixinField, requestChange, restoreValue, } from '@fusion.dev/helix-core';
 import { trash } from '@fusion.dev/helix-icons';
 import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -44,9 +44,10 @@ let HelixHeadlessFileInput = class HelixHeadlessFileInput extends MixinField(Hel
         this.removeLabel = 'Remove';
         this.triggerLabel = 'Choose files';
         this.dropping = false;
+        this.committed = [];
         this.handleChange = (event) => {
             event.stopPropagation();
-            this.announce();
+            this.commit(this.files);
         };
         this.handleDragOver = (event) => {
             if (this.isDisabled) {
@@ -69,12 +70,7 @@ let HelixHeadlessFileInput = class HelixHeadlessFileInput extends MixinField(Hel
             if (dropped.length === 0) {
                 return;
             }
-            const keeping = new DataTransfer();
-            for (const file of this.multiple ? [...this.files, ...dropped] : dropped.slice(-1)) {
-                keeping.items.add(file);
-            }
-            control.files = keeping.files;
-            this.announce();
+            this.commit(this.multiple ? [...this.files, ...dropped] : dropped.slice(-1));
         };
         this.handleRemove = (event) => {
             const at = Number(event.currentTarget.dataset.at);
@@ -90,33 +86,48 @@ let HelixHeadlessFileInput = class HelixHeadlessFileInput extends MixinField(Hel
         return this.partNamed('control');
     }
     clear() {
+        this.commit([]);
+    }
+    removeAt(at) {
+        this.commit(this.files.filter((_, index) => index !== at));
+    }
+    commit(next) {
         const control = this.control;
         if (!control) {
             return;
         }
-        control.value = '';
-        this.announce();
+        const previous = this.committed;
+        const applied = requestChange({
+            apply: (files) => {
+                this.put(control, files);
+                this.settle();
+            },
+            event: (files) => new HelixBeforeChangeEvent({ value: files.map((file) => file.name).join(', ') }),
+            host: this,
+            next,
+        });
+        if (!applied) {
+            this.put(control, previous);
+        }
     }
-    removeAt(at) {
-        const control = this.control;
-        if (!control || typeof DataTransfer === 'undefined') {
+    put(control, files) {
+        if (files.length === 0) {
+            control.value = '';
             return;
         }
-        const keeping = new DataTransfer();
-        for (const [index, file] of this.files.entries()) {
-            if (index !== at) {
-                keeping.items.add(file);
-            }
+        if (typeof DataTransfer === 'undefined') {
+            return;
+        }
+        const holding = new DataTransfer();
+        for (const file of files) {
+            holding.items.add(file);
         }
-        control.files = keeping.files;
-        this.announce();
+        control.files = holding.files;
     }
-    announce() {
+    settle() {
+        this.committed = this.files;
         this.sync();
         this.requestUpdate();
-        this.dispatchEvent(new HelixBeforeChangeEvent({
-            value: this.files.map((file) => file.name).join(', '),
-        }));
         this.announceInput();
         this.announceChange();
     }
@@ -137,6 +148,7 @@ let HelixHeadlessFileInput = class HelixHeadlessFileInput extends MixinField(Hel
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
+        this.committed = this.files;
         this.sync();
     }
     focus(options) {
@@ -146,7 +158,7 @@ let HelixHeadlessFileInput = class HelixHeadlessFileInput extends MixinField(Hel
         if (this.control) {
             restoreValue(this.control, '');
         }
-        this.announce();
+        this.settle();
     }
     renderMeta(file) {
         return html `<${this.tag('tag')} part="size"

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/radio/group/radio-group.d.ts

@@ -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;

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.45.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.45.0",
-    "@fusion.dev/helix-icons": "0.45.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.45.0",
-    "@fusion.dev/helix-testing": "0.45.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;
@@ -19178,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
    *
@@ -19366,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
@@ -19391,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
    *
@@ -23238,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
@@ -23269,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
@@ -36912,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
    *
@@ -37104,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
@@ -37129,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
    *
@@ -41025,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
@@ -41056,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

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;