@fusion.dev/helix-headless 0.44.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"
             },
@@ -38128,7 +38193,7 @@
           "helix": {
             "category": "forms",
             "since": "0.23.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/filter-input",
             "aliases": [
               "FilterToken",
@@ -38596,7 +38661,7 @@
           "helix": {
             "category": "forms",
             "since": "0.23.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/filter-input",
             "aliases": [
               "Facet",
@@ -39325,7 +39390,7 @@
           "helix": {
             "category": "forms",
             "since": "0.25.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/filter-input",
             "aliases": [
               "FacetPicker",
@@ -39789,7 +39854,7 @@
           "helix": {
             "category": "forms",
             "since": "0.23.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/filter-input",
             "aliases": [
               "Comparator",
@@ -41812,7 +41877,7 @@
           "helix": {
             "category": "forms",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/filter-input",
             "aliases": [
               "SearchField",
@@ -62513,6 +62578,17 @@
               "description": "The heading over the run.",
               "attribute": "label"
             },
+            {
+              "kind": "method",
+              "name": "nameFromHeading",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Names the run after the heading it drew, whatever the heading is made of.\n\n**The string alone was not the name of the heading, it was the name of one\nway of writing it.** `label` reached `ariaLabel` and the slot reached the\nscreen, so a consumer who took the documented `label` slot for a heading\nricher than a string got a `role=\"group\"` with no accessible name at all,\nand the words they wrote were the one thing a reader could not hear: the\nheading carries `aria-hidden`, because the name was supposed to be on the\nhost already. Set both and they disagreed, the host saying the string and\nthe panel showing the slot.\n\nSo the host points at the heading, which is the one thing that is always\nwhat a reader sees. `ElementInternals` and not an IDREF, because the host\nis in the light DOM and the heading is in this shadow root, which is the\nboundary `aria-labelledby` cannot cross. `MixinField.linkHost` does the\nsame for a field's label and records the measurement.\n\nClient only. Element references need the nodes to exist, and the server has\nthe string."
+            },
             {
               "kind": "field",
               "name": "tier",
@@ -62856,7 +62932,7 @@
           "summary": "A named run of options inside a listbox.",
           "helix": {
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/option",
             "aliases": [
               "OptGroup",
@@ -63532,7 +63608,7 @@
           "helix": {
             "category": "forms",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/option",
             "aliases": [
               "Item",
@@ -70345,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",
@@ -71390,7 +71466,7 @@
           "summary": "A set of choices where exactly one is the answer.",
           "helix": {
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/radio",
             "aliases": [
               "RadioButtons",
@@ -71504,6 +71580,15 @@
               },
               "description": "Whether the markup declared this one chosen, which is what a reset returns to.\n\n`<option selected>` reflects to `defaultSelected` and `option.selected` is\nlive state that does not reflect, and those are two different facts. This\nelement has one `selected` doing both jobs, so the declaration is the\nattribute and the state is the property.\n\n**The attribute, read when it is asked for, and never a snapshot taken in\nthe constructor.** A field initializer runs there, and an element the HTML\nparser created has none of its attributes yet at that moment: measured on\nthis element, on `Option` and on `Toggle`, `<helix-radio value=\"a\"\nselected>` reported `defaultSelected` as `false` both from parsed markup\nand from `createElement` followed by `setAttribute`, which is every way a\nconsumer writes one. The snapshot could only ever be true for an element\nalready in the document when `customElements.define` ran.\n\nNothing overwrites it either, which is what makes reading it late correct\nrather than merely later: `selected` does not reflect, for the reason\n`willUpdate` records, so the group's writes never reach the attribute and\nwhat it says is what the markup said.\n\n**The deeper half is not this.** State reflecting under the declaration's\nname is the fault `TreeItem` avoids by mirroring to `data-selected`.\nSplitting them means moving what every stylesheet selects on, which is a\nchange of its own rather than a property being added."
             },
+            {
+              "kind": "field",
+              "name": "focusable",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether this choice holds the group's tab stop while nothing is chosen.\n\nThe stop rides on the selection, and an unanswered group has no selection,\nso without this every choice is `tabindex=\"-1\"` and the keyboard cannot\nenter the set at all.\n\n**Written by the group, with no attribute, and it reaches the control\nrather than the host.** A `tabindex` on the host is two faults at once: it\nis markup a consumer rendered and their server never sent, which React\nreports as a mismatch and does not patch up, and it puts the tab stop on\nthe element rather than on the `<button role=\"radio\">` inside it, so a\nscreen reader meets an unnamed box where a native group would have given\nthem an unchecked radio. `Toggle.Root` carries the same property for the\nsame reason."
+            },
             {
               "kind": "field",
               "name": "selected",
@@ -71936,7 +72021,7 @@
           "helix": {
             "category": "forms",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/radio",
             "aliases": [
               "Option",
@@ -77274,7 +77359,7 @@
           "helix": {
             "category": "navigation",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/skip-link",
             "aliases": [
               "Skip navigation",

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/filter-input/chip/filter-chip.d.ts

@@ -37,7 +37,7 @@ declare const HelixHeadlessFilterChip_base: (new (...args: any[]) => import("@fu
  * gives: what the words mean is the domain's.
  *
  * @since 0.23.0
- * @status experimental
+ * @status stable
  * @category forms
  * @aliases FilterToken, FacetChip
  * @documentation https://fusion.dev/helix/components/filter-input