@fusion.dev/helix-headless 0.0.0-dev → 0.0.2

package/dist/scroll-area/root/scroll-area-root.js

@@ -16,12 +16,12 @@ const EDGES = ['block-start', 'block-end', 'inline-start', 'inline-end'];
  * **The whole component is one fact a stylesheet cannot work out for itself:
  * which edges have content past them.** A fade at the bottom of a list is easy
  * to draw and impossible to decide, because CSS has no reading of scroll
- * position. So this measures and says, in `data-more`, and the styled tier
- * draws whatever it likes on the edges named.
+ * position. So this measures and says, in a custom state per edge, and the
+ * styled tier draws whatever it likes on the edges named.
  *
- * **Tokens rather than four attributes**, so a stylesheet asks
- * `[data-more~="block-end"]` the way it would ask about a class. Four booleans
- * say the same thing in four selectors and read worse at every use.
+ * **States rather than attributes**, so an element that upgrades after a
+ * framework rendered its markup does not hand that framework markup it did not
+ * write. A stylesheet asks `:host(:state(more-block-end))`.
  *
  * **A scrolling region takes the keyboard when it scrolls, and not before.**
  * A box a reader can only reach with a pointer is a box some readers cannot
@@ -103,17 +103,14 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
     /**
      * The box that actually scrolls, for anything that needs to move it.
      *
-     * **Public because the alternative is silence.** Bringing a row into view
-     * means telling a scroll utility which box to scroll, and the scrolling box
-     * here is inside a shadow root: a consumer holding a reference to this
-     * element holds the host, which does not scroll, and `scrollBy` on it is a
-     * no-op that reports nothing. That is exactly how `scrollItemIntoView`'s
-     * `offsetParent` default fails, and the sandbox sidebar spent an afternoon
-     * scrolled to zero because of it.
+     * **Public because the alternative is silence.** The scrolling box is inside
+     * this shadow root: a consumer holding a reference to this element holds the
+     * host, which does not scroll, and `scrollBy` on it is a no-op that reports
+     * nothing. That is how `scrollItemIntoView`'s `offsetParent` default fails
+     * here.
      *
      * The element rather than a method of our own, because the utilities that
-     * want it already take one, and `Tree`, `Combobox` and anything windowing a
-     * long list all want the same thing from it.
+     * want it already take one.
      */
     get scroller() {
         return this.renderRoot?.querySelector('[part="viewport"]') ?? null;
@@ -124,20 +121,14 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
            and the content changing size is a data change, and a fade that only
            answered one of them was wrong every time a list was filtered. */
         this.watcher = new ResizeObserver(this.measure);
-        /* And what it watches, which was registered only in `firstUpdated`.
-         *
-         * The observer was already rebuilt here, so this looked like the one
-         * component that had the lifecycle right, and it was half right. A fresh
-         * observer watches nothing until something calls `observe`, and only
-         * `firstUpdated` did, which runs once for the life of the element. So a
-         * scroll area moved in the DOM came back with a new observer registered on
-         * no targets: the fades stopped answering a resize or a filtered list, and
-         * the component went on rendering.
+        /* And what it watches, which rebuilding the observer does not restore. A
+         * fresh observer watches nothing until something calls `observe`, so a
+         * scroll area moved in the DOM comes back registered on no targets: the
+         * fades stop answering a resize or a filtered list, and the component goes
+         * on rendering.
          *
          * Guarded on `hasUpdated`, because the first connection happens before the
-         * first render and there is no scroller to find yet. `check:observers`
-         * holds it, and had to be tightened to see it: asking for `new` *or*
-         * `observe` passed this on the half that was fine. */
+         * first render and there is no scroller to find yet. */
         if (this.hasUpdated) {
             this.watchContent();
         }
@@ -168,13 +159,28 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
     updated(changed) {
         super.updated?.(changed);
         /* On the host rather than the viewport, so a consumer can style from the
-           outside without reaching through a part. */
-        this.toggleAttribute('data-scrolls', this.scrolls);
-        if (this.more.length > 0) {
-            this.setAttribute('data-more', this.more.join(' '));
-        }
-        else {
-            this.removeAttribute('data-more');
+           outside without reaching through a part.
+    
+           **Custom states and never attributes, which is what keeps hydration
+           clean.** These are a reading of a laid-out box, so they are written on
+           upgrade, and upgrade happens before a framework hydrates the subtree
+           around it. Written as attributes they are markup on the host that the
+           framework did not render: React reported a hydration mismatch naming
+           `data-scrolls` and `data-more` on every load of a page holding one.
+           `states` is not in the DOM at all, so this element may upgrade whenever it
+           likes and a framework finds the markup it rendered. That is the rule the
+           rest of the library already keeps, `app-header`'s `scrolled` being the
+           clearest statement of it.
+    
+           One state per edge rather than one holding tokens, because a custom state
+           is a name and not a value: there is no `~=` to ask with. The four
+           selectors are what the styled tier writes either way. */
+        /* Through `toggleState` for the feature test it carries. This is `updated`
+           rather than `willUpdate`, so the server never reaches it, but Safari
+           below 17.4 and Firefox below 126 do and have no `CustomStateSet`. */
+        this.toggleState('scrolls', this.scrolls);
+        for (const edge of EDGES) {
+            this.toggleState(`more-${edge}`, this.more.includes(edge));
         }
     }
     render() {

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

@@ -61,14 +61,15 @@ declare const HelixHeadlessSelect_base: (new (...args: any[]) => import("@fusion
  */
 export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
     protected readonly aria: AriaForwardController;
+    /**
+     * What it says where there are none.
+     */
+    emptyText: string;
     /**
      * Whether the list can be narrowed by typing.
      *
      * Passed to the listbox rather than acted on here, because the listbox owns
-     * the filtering, the empty state and the keyboard. This property existed and
-     * was never read: it reflected, it type-checked, and nothing anywhere
-     * rendered a field. API that does nothing is worse than API that is missing,
-     * because a consumer sets it and believes it.
+     * the filtering, the empty state and the keyboard.
      */
     filterable: boolean;
     /**
@@ -83,10 +84,6 @@ export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
      * What the list says while they are on their way.
      */
     loadingText: string;
-    /**
-     * What it says where there are none.
-     */
-    emptyText: string;
     /**
      * Whether more than one option can be the answer.
      */
@@ -112,10 +109,8 @@ export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
      *
      * The optional chain is the server. `renderRoot` is a property Lit's element
      * shim does not carry, and this getter is reached from `display`, which is
-     * read during `render`: without it the select threw on every server render
-     * and could not be served at all. Found by writing its SSR spec, which is
-     * the only thing that would have found it, because the client is where every
-     * other path runs and the client always has a root.
+     * read during `render`: without it the select throws on every server render
+     * and cannot be served at all.
      *
      * The other reads of `renderRoot` here are inside callbacks the controllers
      * invoke, and a controller only runs on a connected element, so they cannot

package/dist/select/root/select-root.js

@@ -79,14 +79,15 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
         this.aria = new AriaForwardController(this, {
             target: () => this.renderRoot?.querySelector('[part="trigger"]') ?? null,
         });
+        /**
+         * What it says where there are none.
+         */
+        this.emptyText = 'No matches';
         /**
          * Whether the list can be narrowed by typing.
          *
          * Passed to the listbox rather than acted on here, because the listbox owns
-         * the filtering, the empty state and the keyboard. This property existed and
-         * was never read: it reflected, it type-checked, and nothing anywhere
-         * rendered a field. API that does nothing is worse than API that is missing,
-         * because a consumer sets it and believes it.
+         * the filtering, the empty state and the keyboard.
          */
         this.filterable = false;
         /**
@@ -101,10 +102,6 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
          * What the list says while they are on their way.
          */
         this.loadingText = 'Loading';
-        /**
-         * What it says where there are none.
-         */
-        this.emptyText = 'No matches';
         /**
          * Whether more than one option can be the answer.
          */
@@ -113,15 +110,14 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
          * Shown on the trigger while nothing is chosen.
          */
         this.placeholder = 'Choose';
-        /* The surface floats *and is in the top layer*, which it was not.
+        /* The surface floats *and is in the top layer*.
          *
-         * It had a `FloatingController` and a `DismissController` and never called
-         * `showPopover`, so the panel was an ordinary positioned element and the
-         * first ancestor with `overflow: hidden` clipped it. A select inside a
-         * scrolling card was cut off where a menu in the same place was not, and the
-         * two are the same shape: floating panel, trigger, dismissal. That is what
+         * Without `showPopover` the panel is an ordinary positioned element and the
+         * first ancestor with `overflow: hidden` clips it, so a select inside a
+         * scrolling card is cut off where a menu in the same place is not. The two
+         * are the same shape (floating panel, trigger, dismissal), which is what
          * `PopoverController` is, and having one of them is what stops the third copy
-         * being subtly different again.
+         * being subtly different.
          *
          * Held off the trigger by the controller rather than by a margin on the
          * panel. A margin is inside the box the controller measures, so it would be
@@ -133,15 +129,12 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
              *
              * A control is not always one element: the button that opens this panel is
              * part of it, and a press on it is not a press outside. Scoped to the
-             * surface alone, `pointerdown` on the trigger closed the panel and the
-             * trigger's own `toggleOpen` reopened it on the `click` that followed, so
-             * the panel could never be closed by the button that opened it. Measured
-             * across all five popover-bearing components: Menu, Popover and Tooltip
-             * already named their invoker; this one and its three siblings did not, and
-             * all four stayed open on a second press where Menu closed.
+             * surface alone, `pointerdown` on the trigger closes the panel and the
+             * trigger's own `toggleOpen` reopens it on the `click` that follows, so
+             * the panel can never be closed by the button that opened it.
              *
-             * `DismissController` documents this exact failure and takes a list for it.
-             * The list was the fix; using it was the part that did not happen here. */
+             * `DismissController` documents this exact failure and takes a list for
+             * it. */
             boundary: () => [
                 this.renderRoot?.querySelector('[part="surface"]'),
                 this.renderRoot?.querySelector('[part="trigger"]'),
@@ -156,8 +149,8 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
              *
              * The event carries the value being *proposed*, and it is dispatched before
              * it is applied, which is what makes it refusable. Reading the listbox here
-             * therefore read the value it still held: one choice behind, and on the
-             * first choice nothing at all.
+             * reads the value it still holds: one choice behind, and on the first
+             * choice nothing at all.
              *
              * And the listbox never applies it anyway. The select passes `.value` down,
              * which is a consumer declaring ownership, so the listbox inside the panel
@@ -165,13 +158,12 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
              * right arrangement, and it makes reading the listbox's own value the one
              * thing that can never work. */
             const next = event.detail.value;
-            /* Nothing happens on a refusal, and everything did.
+            /* Nothing happens on a refusal.
              *
-             * The panel closed and a native `change` went out whether or not the change
-             * was taken, so a consumer calling `preventDefault()` on `helix-change`
-             * kept the old value, watched the select shut as though it had been chosen,
-             * and told the form it had moved. Refusing a change should leave the
-             * control exactly where it was. */
+             * Without this return the panel closes and a native `change` goes out
+             * whether or not the change was taken, so a consumer calling
+             * `preventDefault()` on `helix-change` keeps the old value, watches the
+             * select shut as though it had been chosen, and tells the form it moved. */
             if (!this.requestValue(next)) {
                 event.stopPropagation();
                 return;
@@ -184,13 +176,11 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
             }
             /* The listbox's request is stopped and this element's own has already gone
                out, from `requestValue` above: two elements announcing one choice is
-               what a consumer would have to deduplicate. The comment here used to say
-               the listbox's was "left to travel", which the line below it has always
-               contradicted.
+               what a consumer would have to deduplicate.
         
                And no `change` is dispatched here. `requestValue` announces `input` and
                `change` through the mixin, the way every other discrete control does, so
-               a second one from this line was a second `change` per choice: measured on
+               a second one from this line is a second `change` per choice: measured on
                the styled tier at three, one from the mixin, one from here, and one from
                the listbox before it was stopped. */
             event.stopPropagation();
@@ -228,10 +218,8 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
      *
      * The optional chain is the server. `renderRoot` is a property Lit's element
      * shim does not carry, and this getter is reached from `display`, which is
-     * read during `render`: without it the select threw on every server render
-     * and could not be served at all. Found by writing its SSR spec, which is
-     * the only thing that would have found it, because the client is where every
-     * other path runs and the client always has a root.
+     * read during `render`: without it the select throws on every server render
+     * and cannot be served at all.
      *
      * The other reads of `renderRoot` here are inside callbacks the controllers
      * invoke, and a controller only runs on a connected element, so they cannot
@@ -284,25 +272,23 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
                costs nothing. */
             this.panel.show();
             /* Into the list, which is where the keyboard has to be for the arrows to
-               mean anything. It reached the listbox element and stopped there, that
-               element not being focusable, so focus stayed on the trigger and every
-               arrow press went to the page. The listbox delegates focus now, so this
-               lands on the list inside it.
+               mean anything. The listbox delegates focus, so this lands on the list
+               inside it rather than stopping at the listbox element, which is not
+               itself focusable.
              *
              * Only on the update that opened it. `updated` runs for any change while
              * the panel is up, a filter keystroke or a value arriving, and moving
-             * focus on each of those is a focus thief: harmless while the listbox was
-             * unfocusable, and a real one the moment it was made to work. */
+             * focus on each of those is a focus thief. */
             if (changed.has('open')) {
                 this.listbox?.focus();
             }
         }
         else {
             this.panel.hide();
-            /* And the filter goes with it. A filterable select reopened still narrowed
-               with the old needle in its search box, and `hidden` still written on the
-               options it had ruled out, so the second use of the control started from
-               the first one's leftovers. Closing is where a search ends. */
+            /* And the filter goes with it. Without this a filterable select reopens
+               still narrowed by the old needle, with `hidden` still written on the
+               options it ruled out, so the second use of the control starts from the
+               first one's leftovers. Closing is where a search ends. */
             this.listbox?.requestFilter('');
         }
     }
@@ -380,9 +366,8 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
         ''}
         <slot name="end"></slot>
         ${
-        /* The slot has a fallback, and had none: a select written without a
-           hand-slotted icon drew no mark at all saying it opens, and every
-           example in the family passes one, which is what hid it. A caret is
+        /* The slot has a fallback: without one a select written without a
+           hand-slotted icon draws no mark at all saying it opens. A caret is
            the mark, and slotting anything replaces it, which is this
            library's rule for a content property. */
         ''}
@@ -395,6 +380,9 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
       ${this.renderHint()}${this.renderFeedback()}`;
     }
 };
+__decorate([
+    property({ attribute: 'empty-text' })
+], HelixHeadlessSelect.prototype, "emptyText", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessSelect.prototype, "filterable", void 0);
@@ -404,9 +392,6 @@ __decorate([
 __decorate([
     property({ attribute: 'loading-text' })
 ], HelixHeadlessSelect.prototype, "loadingText", void 0);
-__decorate([
-    property({ attribute: 'empty-text' })
-], HelixHeadlessSelect.prototype, "emptyText", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessSelect.prototype, "multiple", void 0);

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

@@ -16,13 +16,12 @@ declare const HelixHeadlessSlider_base: (new (...args: any[]) => import("@fusion
  * value rather than the value itself. `valueAsNumber` is there for anything
  * doing arithmetic on it.
  *
- * **Marks are drawn rather than left to `<datalist>`**, which was the first
- * answer and is the wrong one. A datalist's ticks cannot be styled at all, and
- * Firefox does not render them for a range at all, so the platform's version is
- * a mark that looks like someone else's design where it appears and no mark
- * where it does not. Drawing them costs the semantics nothing, because a mark
- * is decoration: what a reader can actually land on is `step`, which the input
- * enforces whether or not anything is drawn.
+ * **Marks are drawn rather than left to `<datalist>`.** A datalist's ticks
+ * cannot be styled at all, and Firefox does not render them for a range at all,
+ * so the platform's version is a mark that looks like someone else's design
+ * where it appears and no mark where it does not. Drawing them costs the
+ * semantics nothing, because a mark is decoration: what a reader can actually
+ * land on is `step`, which the input enforces whether or not anything is drawn.
  *
  * `markers` is a count rather than a flag tied to `step`. A flag reads well
  * until a slider from zero to a hundred stepping by one asks for a hundred and
@@ -30,11 +29,10 @@ declare const HelixHeadlessSlider_base: (new (...args: any[]) => import("@fusion
  * is what the reader sees, so it cannot surprise anyone.
  *
  * **A range is two of them, not a hand-built one.** There is no native
- * two-thumb range, and the answer is not to stop using the platform's: it is to
- * stack two of them on one track, so each thumb keeps its own drag, its own
- * arrow keys, its own Home and End and its own finger-sized hit area. Rebuilding
- * would throw away every argument this component is made of, to gain a second
- * handle.
+ * two-thumb range, so two are stacked on one track and each thumb keeps its own
+ * drag, its own arrow keys, its own Home and End and its own finger-sized hit
+ * area. Rebuilding would throw away every argument this component is made of,
+ * to gain a second handle.
  *
  * Crossing is stopped in the handler rather than by the bounds, and that is not
  * the obvious way round. Giving the lower input `max` of the upper reads well
@@ -78,25 +76,9 @@ export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
     /** Typed or dragged, so every edit is announced. See `announcesInput`. */
     protected readonly announcesInput = true;
     /**
-     * Whether there are two thumbs and the value is a pair.
-     *
-     * The pair is one string, `"10,50"`, which is what a form submits and what
-     * `MixinControllerValue` already holds. `valueAsNumber` reads the lower of
-     * the two, since a range has no single number.
-     */
-    range: boolean;
-    /**
-     * The largest value the reader can choose.
-     */
-    max: number;
-    /**
-     * The smallest value the reader can choose.
-     */
-    min: number;
-    /**
-     * Whether the chosen value is shown beside the track.
+     * Whether each mark says which value it stands at.
      */
-    showValue: boolean;
+    markerLabels: boolean;
     /**
      * How many marks to draw along the track, evenly spaced, ends included.
      *
@@ -114,11 +96,38 @@ export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
      */
     markers: number;
     /**
-     * Whether each mark says which value it stands at.
+     * The largest value the reader can choose.
      */
-    markerLabels: boolean;
-    /** How far one press of an arrow key moves it. */
-    step: number;
+    max: number;
+    /**
+     * The smallest value the reader can choose.
+     */
+    min: number;
+    /**
+     * Which way the track runs, `vertical` standing it on end.
+     *
+     * For a level rather than a quantity: a fader, a channel, anything a reader
+     * pictures as high and low rather than as less and more. Absent is
+     * horizontal, which is what almost every slider in a form wants.
+     *
+     * **A vertical track has no length of its own**, the way a horizontal one
+     * takes the width of the row it is in. `--slider-length` is that number and
+     * defaults to nine rem, so one dropped into a layout is a usable height
+     * rather than a thumb sitting on nothing.
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Whether there are two thumbs and the value is a pair.
+     *
+     * The pair is one string, `"10,50"`, which is what a form submits and what
+     * `MixinControllerValue` already holds. `valueAsNumber` reads the lower of
+     * the two, since a range has no single number.
+     */
+    range: boolean;
+    /**
+     * Whether the chosen value is shown beside the track.
+     */
+    showValue: boolean;
     /**
      * How many characters the readout has to be able to hold, widest case.
      *
@@ -149,7 +158,7 @@ export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
      */
     private get precision();
     /**
-     * How far one press of an arrow key moves it.
+     * The values the marks stand at, evenly spaced, each snapped to a step.
      */
     private get markerValues();
     /**
@@ -181,18 +190,13 @@ export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
      * Arithmetic rather than a measurement, because the browser already knows
      * where it drew the handle and measuring it would be a guess at that.
      *
-     * **Sanitized here, not read back off the control.** This asked the input for
-     * its value, on the reasoning that a range clamps and snaps whatever it is
-     * given, so the control is the truth about where the thumb is. The reasoning
-     * is right and the timing is not: `fraction` is evaluated inside `render()`,
-     * and the `style` binding carrying it is committed *before* the `.value`
-     * binding below it, so it read the value this very render was about to
-     * replace. The fill was a render behind the thumb, and on the first pass it
-     * read the seeded midpoint and stayed there.
-     *
-     * Measured on a slider from 0 to 1: after dragging to either end, the host's
-     * `value` was `1`, the control's was `1`, and `--slider-fraction` was still
-     * `0.5`. Off by half a track, and stable, which is what made it look like a
+     * **Sanitized here, never read back off the control.** Asking the input for
+     * its value reads well, a range clamping and snapping whatever it is given,
+     * and the timing defeats it: `fraction` is evaluated inside `render()` and the
+     * `style` binding carrying it is committed *before* the `.value` binding below
+     * it, so it reads the value this very render is about to replace. The fill
+     * ends up a render behind the thumb, and on the first pass it reads the seeded
+     * midpoint and stays there: stable and off by half a track, which reads as a
      * drawing bug rather than a timing one.
      *
      * So the same two operations a range performs are done here: snap to the step
@@ -212,19 +216,8 @@ export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
     private snapped;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
-    /**
-     * Which way the track runs, `vertical` standing it on end.
-     *
-     * For a level rather than a quantity: a fader, a channel, anything a reader
-     * pictures as high and low rather than as less and more. Absent is
-     * horizontal, which is what almost every slider in a form wants.
-     *
-     * **A vertical track has no length of its own**, the way a horizontal one
-     * takes the width of the row it is in. `--slider-length` is that number and
-     * defaults to nine rem, so one dropped into a layout is a usable height
-     * rather than a thumb sitting on nothing.
-     */
-    orientation?: 'horizontal' | 'vertical';
+    /** How far one press of an arrow key moves it. */
+    step: number;
     protected render(): TemplateResult;
 }
 declare global {