@fusion.dev/helix-headless 0.42.0 → 0.44.0

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

@@ -101,20 +101,30 @@ export declare class HelixHeadlessOption extends HelixElement {
      *
      * `<option selected>` reflects to `defaultSelected` and `option.selected` is
      * live state that does not reflect, and those are two different facts. This
-     * element has one `selected` doing both jobs, so what is captured here is what
-     * the markup said at upgrade, before anything could overwrite it: read the
-     * attribute later and the listbox's own writes answer instead.
-     *
-     * **The deeper half is 302 and is not this.** State reflecting under the
-     * declaration's name is the fault `TreeItem` already avoids by mirroring to
-     * `data-selected`, and four families here still write `selected` back into a
-     * consumer's markup. Splitting them means moving what every stylesheet selects
-     * on, which is a change of its own rather than a property being added.
+     * element has one `selected` doing both jobs, so the declaration is the
+     * attribute and the state is the property.
+     *
+     * **The attribute, read when it is asked for, and never a snapshot taken in
+     * the constructor.** A field initializer runs there, and an element the HTML
+     * parser created has none of its attributes yet at that moment: measured on
+     * this element, on `Radio` and on `Toggle`, `<helix-option value="a"
+     * selected>` reported `defaultSelected` as `false` both from parsed markup
+     * and from `createElement` followed by `setAttribute`, which is every way a
+     * consumer writes one. The snapshot could only ever be true for an element
+     * already in the document when `customElements.define` ran.
+     *
+     * Nothing overwrites it either, which is what makes reading it late correct
+     * rather than merely later: `selected` does not reflect, for the reason
+     * `willUpdate` records, so the listbox's writes never reach the attribute and
+     * what it says is what the markup said.
+     *
+     * **The deeper half is not this.** State reflecting under the declaration's
+     * name is the fault `TreeItem` avoids by mirroring to `data-selected`.
+     * Splitting them means moving what every stylesheet selects on, which is a
+     * change of its own rather than a property being added.
      */
     get defaultSelected(): boolean;
     set defaultSelected(next: boolean);
-    /** What the markup said, read once at construction for the reason above. */
-    private seeded;
     /**
      * A second line under the words, for what the choice actually is.
      *

package/dist/option/root/option-root.js

@@ -17,17 +17,16 @@ let HelixHeadlessOption = class HelixHeadlessOption extends HelixElement {
         this.active = false;
         this.alternate = '';
         this.alternateLabel = '';
-        this.seeded = this.hasAttribute('selected');
         this.disabled = false;
         this.label = '';
         this.selected = false;
         this.value = '';
     }
     get defaultSelected() {
-        return this.seeded;
+        return this.hasAttribute('selected');
     }
     set defaultSelected(next) {
-        this.seeded = next;
+        this.toggleAttribute('selected', next);
     }
     get text() {
         return [...this.childNodes]

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

@@ -51,9 +51,22 @@ export declare class HelixHeadlessRadio extends HelixElement {
      *
      * `<option selected>` reflects to `defaultSelected` and `option.selected` is
      * live state that does not reflect, and those are two different facts. This
-     * element has one `selected` doing both jobs, so what is captured here is what
-     * the markup said at upgrade, before anything could overwrite it: read the
-     * attribute later and the listbox's own writes answer instead.
+     * element has one `selected` doing both jobs, so the declaration is the
+     * attribute and the state is the property.
+     *
+     * **The attribute, read when it is asked for, and never a snapshot taken in
+     * the constructor.** A field initializer runs there, and an element the HTML
+     * parser created has none of its attributes yet at that moment: measured on
+     * this element, on `Option` and on `Toggle`, `<helix-radio value="a"
+     * selected>` reported `defaultSelected` as `false` both from parsed markup
+     * and from `createElement` followed by `setAttribute`, which is every way a
+     * consumer writes one. The snapshot could only ever be true for an element
+     * already in the document when `customElements.define` ran.
+     *
+     * Nothing overwrites it either, which is what makes reading it late correct
+     * rather than merely later: `selected` does not reflect, for the reason
+     * `willUpdate` records, so the group's writes never reach the attribute and
+     * what it says is what the markup said.
      *
      * **The deeper half is not this.** State reflecting under the declaration's
      * name is the fault `TreeItem` avoids by mirroring to `data-selected`.
@@ -62,8 +75,6 @@ export declare class HelixHeadlessRadio extends HelixElement {
      */
     get defaultSelected(): boolean;
     set defaultSelected(next: boolean);
-    /** What the markup said, read once at construction for the reason above. */
-    private seeded;
     /**
      * Whether this is the current choice.
      *

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

@@ -11,15 +11,14 @@ let HelixHeadlessRadio = class HelixHeadlessRadio extends HelixElement {
     constructor() {
         super(...arguments);
         this.disabled = false;
-        this.seeded = this.hasAttribute('selected');
         this.selected = false;
         this.value = '';
     }
     get defaultSelected() {
-        return this.seeded;
+        return this.hasAttribute('selected');
     }
     set defaultSelected(next) {
-        this.seeded = next;
+        this.toggleAttribute('selected', next);
     }
     focusItem() {
         this.partNamed('item')?.focus();

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

@@ -23,8 +23,15 @@ declare const HelixHeadlessSlider_base: (new (...args: any[]) => import("@fusion
  * **A range is two of them.** There is no native two-thumb range, so two are
  * stacked on one track and each thumb keeps its own.
  *
+ * **`required` arrives with the field mixin and cannot fail here**, which is
+ * worth saying rather than leaving a reader to find. A range is never empty:
+ * the platform shows its own midpoint whatever is set, and `willUpdate` seeds
+ * that midpoint into `defaultValue` so the value agrees with the handle from the
+ * first render. HTML does not apply `required` to a range either, so it stays
+ * off the control and the marker beside the label is all it does.
+ *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category forms
  * @aliases Range, Range input
  * @documentation https://fusion.dev/helix/components/slider
@@ -44,9 +51,9 @@ declare const HelixHeadlessSlider_base: (new (...args: any[]) => import("@fusion
  * @csspart output - The current value, shown beside it.
  *
  * @cssproperty --slider-fraction - The value as a fraction of the range, 0 to 1.
- * @cssproperty --slider-from - Where the filled span starts, as a percentage of the track.
+ * @cssproperty --slider-from - Where a range's filled span starts, as a fraction of the track, 0 to 1.
  * @cssproperty --slider-marker-at - Where one marker sits, as a percentage of the track.
- * @cssproperty --slider-to - Where the filled span ends, as a percentage of the track.
+ * @cssproperty --slider-to - Where a range's filled span ends, as a fraction of the track, 0 to 1.
  *
  * @cssstate invalid - While there is feedback to show: the platform's verdict, or the consumer's `feedback`.
  */

package/dist/speed-dial/item/speed-dial-item.d.ts

@@ -16,7 +16,7 @@ import { type TemplateResult } from 'lit';
  * being there, so it is read, searched and translated like anything else.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category actions
  * @aliases Speed dial action, FAB action, Quick action
  * @documentation https://fusion.dev/helix/components/speed-dial

package/dist/speed-dial/root/speed-dial-root.d.ts

@@ -28,7 +28,7 @@ declare const HelixHeadlessSpeedDial_base: (new (...args: any[]) => import("@fus
  * with no reason to argue with it.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category actions
  * @aliases FAB, Floating action button, Action button, Quick actions
  * @documentation https://fusion.dev/helix/components/speed-dial

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

@@ -41,8 +41,8 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @slot end - The pane after it.
  * @slot start - The pane before the divider.
  *
- * @event {HelixBeforeCollapseEvent} helix-before-collapse - Fired before a pane shuts or reopens, and cancelable.
- * @event {HelixBeforeResizeEvent} helix-before-resize - Fired before the divider settles, and cancelable.
+ * @event {HelixBeforeCollapseEvent} helix-before-collapse - Fired before a pane shuts or reopens, and only where the position it is derived from stood. Cancelable: refusing it leaves the pane as it was and the divider where the gesture put it.
+ * @event {HelixBeforeResizeEvent} helix-before-resize - Fired before the divider settles. Cancelable: refusing it takes the whole of where the gesture ended, so no collapse follows from it either. A drag has already drawn itself by then and holds where it was dropped until the consumer assigns their own.
  *
  * @csspart corner - The handle where two dividers cross, added on the client.
  * @csspart end - The box holding the second.
@@ -300,11 +300,18 @@ export declare class HelixHeadlessSplitter extends HelixElement {
      */
     get vertical(): boolean;
     /**
-     * Asks to move, and applies it where the position is this element's to move.
+     * Moves the divider under a gesture that is still happening.
      *
      * Not announced per step: `helix-before-resize` is the settling, below. A drag that
      * announced every position would be asking a consumer to record a hundred
      * decisions to keep one.
+     *
+     * **A drag only, which is the whole of why applying before announcing is
+     * right here.** The divider has to follow the hand, and the one number worth
+     * a decision is where the hand let go. Nothing discrete calls this: a key and
+     * a double click go straight to `settle`, so their announcement comes before
+     * their change and refusing one takes the decision, and the corner's arrows
+     * already did.
      */
     private move;
     /**
@@ -312,6 +319,22 @@ export declare class HelixHeadlessSplitter extends HelixElement {
      *
      * Through the audited path, so a consumer who owns `position` is told what was
      * asked for and decides, and one who does not has already had it applied.
+     *
+     * **The second announcement is conditional on the first, because it is derived
+     * from it.** `shutAt` reads the position the gesture ended on, so a refused
+     * `helix-before-resize` leaves a collapse computed from a number that was
+     * refused. Announced anyway, the refusal produced the outcome it was refusing:
+     * measured on a divider at 40 with a listener calling `preventDefault`, Home
+     * left `position` reporting 0 and `collapsed` reporting `start`, because the
+     * collapse applied and `position` reads the sliver once a pane is shut. The
+     * return of the first request is what says so, and it was being dropped: a
+     * cancelable event dispatched as a bare statement with nothing reading the
+     * answer, which is the shape the navigation cohort named on `Outline` and left.
+     *
+     * Refusing the collapse alone still leaves the resize, which is the other way
+     * round and is coherent: the divider goes where the drag put it and the pane
+     * is not declared shut. What a consumer cannot have is a pane that collapses
+     * out from under a position they said no to.
      */
     private settle;
     private readonly handlePointerDown;

package/dist/splitter/root/splitter-root.js

@@ -82,7 +82,6 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
             else {
                 return;
             }
-            this.move(next);
             this.settle(next);
             event.preventDefault();
         };
@@ -300,7 +299,7 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
     settle(next) {
         const wanted = this.clamp(next);
         const shut = this.shutAt(wanted);
-        requestChange({
+        const moved = requestChange({
             apply: (value) => {
                 const previous = this.position;
                 this.positionState = value;
@@ -310,6 +309,9 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
             host: this,
             next: wanted,
         });
+        if (!moved) {
+            return;
+        }
         if (shut !== this.collapsed) {
             requestChange({
                 apply: (value) => {
@@ -334,7 +336,6 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
     }
     reset() {
         const home = this.clamp(this.defaultPosition);
-        this.move(home);
         this.settle(home);
     }
     cross(by, at) {

package/dist/toast/item/toast-item.d.ts

@@ -18,7 +18,7 @@ declare const HelixHeadlessToastItem_base: (new (...args: any[]) => import("@fus
  * something.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @documentation https://fusion.dev/helix/components/toast
  *
  * @slot - The message.

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

@@ -29,9 +29,9 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * test, or twice.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category overlays
- * @aliases Toaster, Snackbar, Notifications
+ * @aliases Toaster, Snackbar
  * @documentation https://fusion.dev/helix/components/toast
  *
  * @slot - The messages, as `helix-toast-item` elements.

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

@@ -16,11 +16,13 @@ declare const HelixHeadlessToggleGroup_base: (new (...args: any[]) => import("@f
  * it has somewhere to be, which is the harmless direction.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @aliases SegmentedControl, Segmented, Navigation, Switcher
  * @documentation https://fusion.dev/helix/components/toggle
  *
  * @slot - The group's items.
+ * @slot end - Whatever sits after the track on its own line, such as a count or a reset.
+ * @slot start - Whatever sits before the track on its own line, such as an icon or a caption.
  *
  * @event {Event} change - Announced once the value has moved.
  * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the answer moves, and cancelable. The only way to refuse one.
@@ -38,6 +40,48 @@ declare const HelixHeadlessToggleGroup_base: (new (...args: any[]) => import("@f
  * @cssstate invalid - While there is feedback to show: the platform's verdict, or the consumer's `feedback`.
  */
 export declare class HelixHeadlessToggleGroup extends HelixHeadlessToggleGroup_base {
+    /**
+     * Takes the markup's own answer where nothing has set a value.
+     *
+     * **The case a server renders**, and `Tabs` records the same fault from the
+     * other side. This element cannot choose on the server, having no children to
+     * count, so a consumer whose first paint is right wrote `selected` on the
+     * item: that serves `aria-checked="true"`, and `sync` then cleared it one
+     * frame later, because `value` is `''` and nothing matches it. The shipped
+     * `disabled` example is exactly that markup, and drew both of its groups with
+     * nothing chosen.
+     *
+     * **Onto `defaultValue`, never onto `value`**, which is the same call
+     * `Slider` makes about the midpoint it seeds: what the markup declared is a
+     * fact about the markup, so it is where a reset returns to rather than
+     * something the reader chose. It also makes the group report the answer it is
+     * showing, which marking the item alone would not: a `required` group would
+     * otherwise tell a reader a value is missing while they are looking at one.
+     *
+     * A written `value` still wins, a declared property being a seed and a
+     * correction, and a group with neither still marks nothing at all.
+     *
+     * **The property and never `defaultSelected`, which is the attribute.** React
+     * assigns a JSX prop as a property where the custom element has one, and
+     * writes no attribute at all, so keying on the attribute answers for markup
+     * and not for JSX. Measured by the parity check on the shipped `disabled`
+     * example, whose two syntaxes are the same tree: 192 pixels apart, the HTML
+     * marking `List` and the TSX marking nothing. The attribute seeds the
+     * property at upgrade, so reading the property covers both.
+     *
+     * Read before `sync` writes to it, which is the only moment it still holds
+     * what the consumer declared: after that it holds this group's answer, and
+     * `value` is no longer empty, so this returns above.
+     *
+     * **Called from `willUpdate` and from the slot, never from `sync`**, which
+     * runs in `updated`: a reactive property set there schedules a second update,
+     * and Lit's development build warns about exactly that once per group. From
+     * `willUpdate` the first render already carries the value, which is the pass
+     * that has to be right. `children` is undefined on the server, whose element
+     * shim carries attributes and no tree, and that is the same guard
+     * `MixinCollection` records for the same reason.
+     */
+    private adopt;
     /** Marks the chosen item, separately from placing the indicator. */
     private sync;
     private readonly indicator;

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

@@ -25,6 +25,15 @@ let HelixHeadlessToggleGroup = class HelixHeadlessToggleGroup extends MixinContr
             this.requestValue(event.detail.value);
         };
     }
+    adopt() {
+        if (this.value !== '' || this.children === undefined) {
+            return;
+        }
+        const declared = this.items.find((item) => item.selected);
+        if (declared) {
+            this.defaultValue = declared.value;
+        }
+    }
     sync() {
         const active = this.items.find((item) => item.value === this.value);
         const entry = active ? undefined : this.items.find((item) => !item.disabled);
@@ -57,6 +66,7 @@ let HelixHeadlessToggleGroup = class HelixHeadlessToggleGroup extends MixinContr
     }
     willUpdate(changed) {
         super.willUpdate(changed);
+        this.adopt();
         hostAria(this.internals, { label: this.label, role: 'radiogroup' });
         this.internals.setFormValue(this.value === '' ? null : this.value);
     }
@@ -74,6 +84,7 @@ let HelixHeadlessToggleGroup = class HelixHeadlessToggleGroup extends MixinContr
         <div part="indicator" aria-hidden="true"></div>
         <slot
           @slotchange=${() => {
+            this.adopt();
             this.sync();
             this.indicator.place();
         }}

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

@@ -11,7 +11,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * without radio semantics announcing destinations as choices.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category actions
  * @aliases Segment, NavItem, Option
  * @documentation https://fusion.dev/helix/components/toggle
@@ -34,9 +34,22 @@ export declare class HelixHeadlessToggle extends HelixElement {
      *
      * `<option selected>` reflects to `defaultSelected` and `option.selected` is
      * live state that does not reflect, and those are two different facts. This
-     * element has one `selected` doing both jobs, so what is captured here is what
-     * the markup said at upgrade, before anything could overwrite it: read the
-     * attribute later and the listbox's own writes answer instead.
+     * element has one `selected` doing both jobs, so the declaration is the
+     * attribute and the state is the property.
+     *
+     * **The attribute, read when it is asked for, and never a snapshot taken in
+     * the constructor.** A field initializer runs there, and an element the HTML
+     * parser created has none of its attributes yet at that moment: measured on
+     * this element, on `Option` and on `Radio`, `<helix-toggle value="light"
+     * selected>` reported `defaultSelected` as `false` both from parsed markup
+     * and from `createElement` followed by `setAttribute`, which is every way a
+     * consumer writes one. The snapshot could only ever be true for an element
+     * already in the document when `customElements.define` ran.
+     *
+     * Nothing overwrites it either, which is what makes reading it late correct
+     * rather than merely later: `selected` does not reflect, for the reason
+     * `willUpdate` records, so the group's writes never reach the attribute and
+     * what it says is what the markup said.
      *
      * **The deeper half is not this.** State reflecting under the declaration's
      * name is the fault `TreeItem` avoids by mirroring to `data-selected`.
@@ -45,8 +58,6 @@ export declare class HelixHeadlessToggle extends HelixElement {
      */
     get defaultSelected(): boolean;
     set defaultSelected(next: boolean);
-    /** What the markup said, read once at construction for the reason above. */
-    private seeded;
     /**
      * Whether this item holds the group's tab stop while nothing is chosen.
      *

package/dist/toggle/root/toggle-root.js

@@ -11,16 +11,15 @@ let HelixHeadlessToggle = class HelixHeadlessToggle extends HelixElement {
     constructor() {
         super(...arguments);
         this.disabled = false;
-        this.seeded = this.hasAttribute('selected');
         this.focusable = false;
         this.selected = false;
         this.value = '';
     }
     get defaultSelected() {
-        return this.seeded;
+        return this.hasAttribute('selected');
     }
     set defaultSelected(next) {
-        this.seeded = next;
+        this.toggleAttribute('selected', next);
     }
     focusItem() {
         this.partNamed('item')?.focus();

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

@@ -32,7 +32,6 @@ import type { HelixHeadlessTourStop } from '../stop/tour-stop.js';
  * @event {HelixCompleteEvent} helix-complete - Fired when the last stop is
  * finished.
  * @event {HelixTourAskEvent} helix-tour-ask - A stop's own controls asking the tour to move, dispatched by the stop and heard here because the tour is what moves.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
  *
  * @csspart spotlight - The box over the current target, which paints the scrim.
  */

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.42.0",
+  "version": "0.44.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.42.0",
-    "@fusion.dev/helix-icons": "0.42.0",
+    "@fusion.dev/helix-core": "0.44.0",
+    "@fusion.dev/helix-icons": "0.44.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.42.0",
-    "@fusion.dev/helix-testing": "0.42.0",
+    "@fusion.dev/helix-cem": "0.44.0",
+    "@fusion.dev/helix-testing": "0.44.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",