@fusion.dev/helix 0.45.0 → 0.46.1

package/custom-elements.json

@@ -14517,7 +14517,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",
               "inheritedFrom": {
@@ -15700,7 +15700,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,
               "inheritedFrom": {
@@ -15825,7 +15825,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.",
               "inheritedFrom": {
                 "name": "HelixHeadlessChatMessage",
                 "module": "src/chat/message/chat-message.ts"
@@ -16230,7 +16230,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",
               "inheritedFrom": {
                 "name": "HelixHeadlessChatMessage",
@@ -16259,7 +16259,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",
               "inheritedFrom": {
@@ -25070,6 +25070,21 @@
                 "module": "src/color-picker/root/color-picker-root.ts"
               }
             },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessColorPicker",
+                "module": "src/color-picker/root/color-picker-root.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "focus",
@@ -45844,9 +45859,75 @@
                 "module": "src/file-input/root/file-input-root.ts"
               }
             },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFileInput",
+                "module": "src/file-input/root/file-input-root.ts"
+              }
+            },
             {
               "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFileInput",
+                "module": "src/file-input/root/file-input-root.ts"
+              }
+            },
+            {
+              "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.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessFileInput",
+                "module": "src/file-input/root/file-input-root.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "settle",
               "privacy": "private",
               "return": {
                 "type": {
@@ -45958,7 +46039,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"
               },
@@ -46868,7 +46949,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",
               "inheritedFrom": {
@@ -89098,7 +89179,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.",
               "inheritedFrom": {
                 "name": "HelixHeadlessRadioGroup",
                 "module": "src/radio/group/radio-group.ts"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix",
   "description": "Styled component tier. Extends the headless tier with token-driven presentation.",
-  "version": "0.45.0",
+  "version": "0.46.1",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -47,14 +47,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.45.0",
-    "@fusion.dev/helix-headless": "0.45.0",
-    "@fusion.dev/helix-styles": "0.45.0"
+    "@fusion.dev/helix-core": "0.46.1",
+    "@fusion.dev/helix-headless": "0.46.1",
+    "@fusion.dev/helix-styles": "0.46.1"
   },
   "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.1",
+    "@fusion.dev/helix-testing": "0.46.1",
     "@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

@@ -2826,7 +2826,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?: (HelixCarousel["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: HelixCarouselHelixSelectElementEvent) => void) | undefined;
 };
 
@@ -3056,7 +3056,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"?: (HelixCarousel["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: HelixCarouselHelixSelectElementEvent) => void) | undefined;
 
   /** Set the innerHTML of the element */
@@ -3211,10 +3211,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?: (HelixChatMessage["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: HelixChatMessageHelixSendElementEvent) => void) | undefined;
 };
 
@@ -3270,9 +3273,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"?: (HelixChatMessage["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: HelixChatMessageHelixSendElementEvent) => void) | undefined;
 
   /** Set the innerHTML of the element */
@@ -7558,7 +7564,7 @@ Here rather than on each control. */
 
   /** Announced once the value has moved. */
   onchange?: ((e: HelixFileInputElementEvent) => 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: HelixFileInputHelixBeforeChangeElementEvent,
   ) => void) | undefined;
@@ -7621,7 +7627,7 @@ Here rather than on each control. */
   "prop:name"?: (HelixFileInput["name"]) | undefined;
   /** Announced once the value has moved. */
   "on:change"?: ((e: HelixFileInputElementEvent) => 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: HelixFileInputHelixBeforeChangeElementEvent,
   ) => void) | undefined;
@@ -22660,7 +22666,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
    *
@@ -22863,6 +22869,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
@@ -22888,7 +22897,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
    *
@@ -26820,7 +26829,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
@@ -26851,6 +26860,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
@@ -41960,7 +41974,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
    *
@@ -42169,6 +42183,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
@@ -42194,7 +42211,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
    *
@@ -46193,7 +46210,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
@@ -46224,6 +46241,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

@@ -1558,7 +1558,7 @@ case is the absent attribute, and the styles read it that way. */
 };
 
 export type HelixCarouselVueEvents = {
-  /** 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": HelixCarouselHelixSelectElementEvent;
 };
 
@@ -1670,12 +1670,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?: (HelixChatMessage["state"]) | undefined;
 };
 
 export type HelixChatMessageVueEvents = {
-  /** 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": HelixChatMessageHelixSendElementEvent;
 };
 
@@ -3907,7 +3910,7 @@ Here rather than on each control. */
 export type HelixFileInputVueEvents = {
   /** Announced once the value has moved. */
   change: HelixFileInputElementEvent;
-  /** 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": HelixFileInputHelixBeforeChangeElementEvent;
   /** Announced once the value has moved. */
   input: HelixFileInputElementEvent;