@fusion.dev/helix-headless 0.144.0 → 0.146.0

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

@@ -5,192 +5,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var HelixHeadlessSplitter_1;
-import { AriaForwardController, capturePointer, closestInstance, customElement, HelixBeforeCollapseEvent, HelixBeforeResizeEvent, HelixCollapseEvent, HelixElement, HelixResizedEvent, inlineStep, isRtl, requestChange, } from '@fusion.dev/helix-core';
+import { AriaForwardController, capturePointer, closestInstance, commaList, customElement, HelixBeforeCollapseEvent, HelixBeforeResizeEvent, HelixCollapseEvent, HelixElement, HelixResizedEvent, inlineStep, isRtl, requestChange, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
+import { snapTo } from '../snap.js';
 const STACK_BELOW = 512;
+const channel = new WeakMap();
 let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitter extends HelixElement {
-    constructor() {
-        super(...arguments);
-        this.collapsedLabel = 'Collapsed';
-        this.collapsedSize = 0;
-        this.cornerLabel = 'Resize both';
-        this.defaultPosition = 50;
-        this.label = 'Resize panes';
-        this.aria = new AriaForwardController(this, {
-            label: true,
-            target: () => this.partNamed('separator'),
-        });
-        this.max = 100;
-        this.min = 0;
-        this.step = 2;
-        this.positionState = undefined;
-        this.collapsedState = undefined;
-        this.opened = undefined;
-        this.began = undefined;
-        this.reached = undefined;
-        this.dragging = false;
-        this.crossings = [];
-        this.outer = null;
-        this.crossedAt = undefined;
-        this.cornerOrigin = null;
-        this.origin = null;
-        this.stacked = false;
-        this.handlePointerDown = (event) => {
-            const separator = event.currentTarget;
-            const box = this.getBoundingClientRect();
-            this.origin = this.vertical
-                ? { length: box.height, start: box.top }
-                : { length: box.width, start: box.left };
-            capturePointer(separator, event.pointerId);
-            this.opened = this.collapsed ? undefined : this.position;
-            this.began = this.position;
-            this.reached = undefined;
-            this.dragging = true;
-            event.preventDefault();
-        };
-        this.handlePointerMove = (event) => {
-            const origin = this.origin;
-            if (!origin || origin.length === 0) {
-                return;
-            }
-            const along = this.vertical ? event.clientY : event.clientX;
-            const raw = ((along - origin.start) / origin.length) * 100;
-            const rtl = !this.vertical && isRtl(this);
-            this.move(rtl ? 100 - raw : raw);
-        };
-        this.handlePointerUp = (event) => {
-            if (!this.origin) {
-                return;
-            }
-            const separator = event.currentTarget;
-            if (separator.hasPointerCapture(event.pointerId)) {
-                separator.releasePointerCapture(event.pointerId);
-            }
-            this.origin = null;
-            this.dragging = false;
-            this.settle(this.reached ?? this.position);
-        };
-        this.handleKeydown = (event) => {
-            if (event.key === 'Enter') {
-                this.toggleCollapse();
-                event.preventDefault();
-                return;
-            }
-            const toward = this.travel(event.key);
-            let next;
-            if (toward !== 0) {
-                next = this.position + toward * this.step;
-            }
-            else if (event.key === 'Home') {
-                next = this.minPercent;
-            }
-            else if (event.key === 'End') {
-                next = this.maxPercent;
-            }
-            else {
-                return;
-            }
-            this.settle(next);
-            event.preventDefault();
-        };
-        this.handleDoubleClick = () => {
-            this.reset();
-        };
-        this.handleCornerDoubleClick = (event) => {
-            const crossing = this.crossings[Number(event.currentTarget.dataset.cross)];
-            if (!crossing) {
-                return;
-            }
-            this.reset();
-            crossing.by.reset();
-            this.leaveSeparator(event);
-        };
-        this.handleCornerDown = (event) => {
-            const handle = event.currentTarget;
-            const crossing = this.crossings[Number(handle.dataset.cross)];
-            if (!crossing) {
-                return;
-            }
-            const mine = this.getBoundingClientRect();
-            const theirs = crossing.by.getBoundingClientRect();
-            this.cornerOrigin = {
-                by: crossing.by,
-                inner: crossing.by.vertical
-                    ? { length: theirs.height, start: theirs.top }
-                    : { length: theirs.width, start: theirs.left },
-                outer: this.vertical
-                    ? { length: mine.height, start: mine.top }
-                    : { length: mine.width, start: mine.left },
-            };
-            capturePointer(handle, event.pointerId);
-            this.opened = this.collapsed ? undefined : this.position;
-            crossing.by.opened = crossing.by.collapsed ? undefined : crossing.by.position;
-            this.began = this.position;
-            crossing.by.began = crossing.by.position;
-            this.reached = undefined;
-            crossing.by.reached = undefined;
-            this.dragging = true;
-            crossing.by.dragging = true;
-            this.leaveSeparator(event);
-        };
-        this.handleCornerMove = (event) => {
-            const origin = this.cornerOrigin;
-            if (!origin) {
-                return;
-            }
-            const rtl = isRtl(this);
-            const along = (box, at, inline) => {
-                if (box.length === 0) {
-                    return undefined;
-                }
-                const raw = ((at - box.start) / box.length) * 100;
-                return inline && rtl ? 100 - raw : raw;
-            };
-            const mine = along(origin.outer, this.vertical ? event.clientY : event.clientX, !this.vertical);
-            const theirs = along(origin.inner, origin.by.vertical ? event.clientY : event.clientX, !origin.by.vertical);
-            if (mine !== undefined) {
-                this.moveTo(mine);
-            }
-            if (theirs !== undefined) {
-                origin.by.moveTo(theirs);
-            }
-            this.leaveSeparator(event);
-        };
-        this.handleCornerUp = (event) => {
-            const origin = this.cornerOrigin;
-            if (!origin) {
-                return;
-            }
-            const handle = event.currentTarget;
-            if (handle.hasPointerCapture(event.pointerId)) {
-                handle.releasePointerCapture(event.pointerId);
-            }
-            this.cornerOrigin = null;
-            this.moveTo(this.reached ?? this.position, true);
-            origin.by.moveTo(origin.by.reached ?? origin.by.position, true);
-            this.leaveSeparator(event);
-        };
-        this.handleCornerKeydown = (event) => {
-            const crossing = this.crossings[Number(event.currentTarget.dataset.cross)];
-            if (!crossing) {
-                return;
-            }
-            const inner = crossing.by;
-            const mine = this.travel(event.key);
-            const theirs = inner.travel(event.key);
-            if (mine !== 0) {
-                this.moveTo(this.position + mine * this.step, true);
-            }
-            else if (theirs !== 0) {
-                inner.moveTo(inner.position + theirs * inner.step, true);
-            }
-            else {
-                return;
-            }
-            this.leaveSeparator(event);
-        };
-    }
     get collapsed() {
         const held = this.collapsedState;
         if (held === undefined) {
@@ -345,6 +166,15 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
             });
         }
     }
+    snapped(position, length) {
+        if (this.snap === '' || length <= 0) {
+            return position;
+        }
+        const points = commaList(this.snap)
+            .map((point) => this.toPercent(point, Number.NaN))
+            .filter((point) => Number.isFinite(point));
+        return snapTo(position, points, (this.snapThreshold / length) * 100);
+    }
     travel(key) {
         if (!this.vertical) {
             return inlineStep(this, key);
@@ -376,26 +206,211 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
         const home = this.clamp(this.defaultPosition);
         this.settle(home);
     }
-    cross(by, at) {
-        const found = this.crossings.find((crossing) => crossing.by === by);
-        if (found) {
-            if (found.at === at) {
+    constructor() {
+        super();
+        this.collapsedLabel = 'Collapsed';
+        this.collapsedSize = 0;
+        this.cornerLabel = 'Resize both';
+        this.defaultPosition = 50;
+        this.label = 'Resize panes';
+        this.aria = new AriaForwardController(this, {
+            label: true,
+            target: () => this.partNamed('separator'),
+        });
+        this.max = 100;
+        this.min = 0;
+        this.snap = '';
+        this.snapThreshold = 12;
+        this.step = 2;
+        this.positionState = undefined;
+        this.collapsedState = undefined;
+        this.opened = undefined;
+        this.began = undefined;
+        this.reached = undefined;
+        this.dragging = false;
+        this.crossings = [];
+        this.outer = null;
+        this.crossedAt = undefined;
+        this.cornerOrigin = null;
+        this.origin = null;
+        this.stacked = false;
+        this.handlePointerDown = (event) => {
+            const separator = event.currentTarget;
+            const box = this.getBoundingClientRect();
+            this.origin = this.vertical
+                ? { length: box.height, start: box.top }
+                : { length: box.width, start: box.left };
+            capturePointer(separator, event.pointerId);
+            this.opened = this.collapsed ? undefined : this.position;
+            this.began = this.position;
+            this.reached = undefined;
+            this.dragging = true;
+            event.preventDefault();
+        };
+        this.handlePointerMove = (event) => {
+            const origin = this.origin;
+            if (!origin || origin.length === 0) {
                 return;
             }
-            found.at = at;
-        }
-        else {
-            this.crossings.push({ at, by });
-        }
-        this.requestUpdate();
-    }
-    uncross(by) {
-        const at = this.crossings.findIndex((crossing) => crossing.by === by);
-        if (at === -1) {
-            return;
-        }
-        this.crossings.splice(at, 1);
-        this.requestUpdate();
+            const along = this.vertical ? event.clientY : event.clientX;
+            const raw = ((along - origin.start) / origin.length) * 100;
+            const rtl = !this.vertical && isRtl(this);
+            this.move(this.snapped(rtl ? 100 - raw : raw, origin.length));
+        };
+        this.handlePointerUp = (event) => {
+            if (!this.origin) {
+                return;
+            }
+            const separator = event.currentTarget;
+            if (separator.hasPointerCapture(event.pointerId)) {
+                separator.releasePointerCapture(event.pointerId);
+            }
+            this.origin = null;
+            this.dragging = false;
+            this.settle(this.reached ?? this.position);
+        };
+        this.handleKeydown = (event) => {
+            if (event.key === 'Enter') {
+                this.toggleCollapse();
+                event.preventDefault();
+                return;
+            }
+            const toward = this.travel(event.key);
+            let next;
+            if (toward !== 0) {
+                next = this.position + toward * this.step;
+            }
+            else if (event.key === 'Home') {
+                next = this.minPercent;
+            }
+            else if (event.key === 'End') {
+                next = this.maxPercent;
+            }
+            else {
+                return;
+            }
+            this.settle(next);
+            event.preventDefault();
+        };
+        this.handleDoubleClick = () => {
+            this.reset();
+        };
+        this.handleCornerDoubleClick = (event) => {
+            const crossing = this.crossings[Number(event.currentTarget.dataset.cross)];
+            if (!crossing) {
+                return;
+            }
+            this.reset();
+            crossing.by.reset();
+            this.leaveSeparator(event);
+        };
+        this.handleCornerDown = (event) => {
+            const handle = event.currentTarget;
+            const crossing = this.crossings[Number(handle.dataset.cross)];
+            if (!crossing) {
+                return;
+            }
+            const mine = this.getBoundingClientRect();
+            const theirs = crossing.by.getBoundingClientRect();
+            this.cornerOrigin = {
+                by: crossing.by,
+                inner: crossing.by.vertical
+                    ? { length: theirs.height, start: theirs.top }
+                    : { length: theirs.width, start: theirs.left },
+                outer: this.vertical
+                    ? { length: mine.height, start: mine.top }
+                    : { length: mine.width, start: mine.left },
+            };
+            capturePointer(handle, event.pointerId);
+            this.opened = this.collapsed ? undefined : this.position;
+            crossing.by.opened = crossing.by.collapsed ? undefined : crossing.by.position;
+            this.began = this.position;
+            crossing.by.began = crossing.by.position;
+            this.reached = undefined;
+            crossing.by.reached = undefined;
+            this.dragging = true;
+            crossing.by.dragging = true;
+            this.leaveSeparator(event);
+        };
+        this.handleCornerMove = (event) => {
+            const origin = this.cornerOrigin;
+            if (!origin) {
+                return;
+            }
+            const rtl = isRtl(this);
+            const along = (box, at, inline) => {
+                if (box.length === 0) {
+                    return undefined;
+                }
+                const raw = ((at - box.start) / box.length) * 100;
+                return inline && rtl ? 100 - raw : raw;
+            };
+            const mine = along(origin.outer, this.vertical ? event.clientY : event.clientX, !this.vertical);
+            const theirs = along(origin.inner, origin.by.vertical ? event.clientY : event.clientX, !origin.by.vertical);
+            if (mine !== undefined) {
+                this.moveTo(mine);
+            }
+            if (theirs !== undefined) {
+                origin.by.moveTo(theirs);
+            }
+            this.leaveSeparator(event);
+        };
+        this.handleCornerUp = (event) => {
+            const origin = this.cornerOrigin;
+            if (!origin) {
+                return;
+            }
+            const handle = event.currentTarget;
+            if (handle.hasPointerCapture(event.pointerId)) {
+                handle.releasePointerCapture(event.pointerId);
+            }
+            this.cornerOrigin = null;
+            this.moveTo(this.reached ?? this.position, true);
+            origin.by.moveTo(origin.by.reached ?? origin.by.position, true);
+            this.leaveSeparator(event);
+        };
+        this.handleCornerKeydown = (event) => {
+            const crossing = this.crossings[Number(event.currentTarget.dataset.cross)];
+            if (!crossing) {
+                return;
+            }
+            const inner = crossing.by;
+            const mine = this.travel(event.key);
+            const theirs = inner.travel(event.key);
+            if (mine !== 0) {
+                this.moveTo(this.position + mine * this.step, true);
+            }
+            else if (theirs !== 0) {
+                inner.moveTo(inner.position + theirs * inner.step, true);
+            }
+            else {
+                return;
+            }
+            this.leaveSeparator(event);
+        };
+        channel.set(this, {
+            cross: (by, at) => {
+                const found = this.crossings.find((crossing) => crossing.by === by);
+                if (found) {
+                    if (found.at === at) {
+                        return;
+                    }
+                    found.at = at;
+                }
+                else {
+                    this.crossings.push({ at, by });
+                }
+                this.requestUpdate();
+            },
+            uncross: (by) => {
+                const at = this.crossings.findIndex((crossing) => crossing.by === by);
+                if (at === -1) {
+                    return;
+                }
+                this.crossings.splice(at, 1);
+                this.requestUpdate();
+            },
+        });
     }
     findOuter() {
         const outer = closestInstance(this.parentElement, HelixHeadlessSplitter_1);
@@ -404,7 +419,7 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
         }
         this.outer = outer;
         this.crossedAt = this.position;
-        outer.cross(this, this.position);
+        channel.get(outer)?.cross(this, this.position);
     }
     leaveSeparator(event) {
         event.stopPropagation();
@@ -421,7 +436,9 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
         super.disconnectedCallback();
         this.sizes?.disconnect();
         this.sizes = undefined;
-        this.outer?.uncross(this);
+        if (this.outer) {
+            channel.get(this.outer)?.uncross(this);
+        }
         this.outer = null;
         this.crossedAt = undefined;
     }
@@ -449,7 +466,7 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
         }
         if (this.outer && this.showing !== this.crossedAt) {
             this.crossedAt = this.showing;
-            this.outer.cross(this, this.showing);
+            channel.get(this.outer)?.cross(this, this.showing);
         }
     }
     willUpdate(changed) {
@@ -541,6 +558,12 @@ __decorate([
 __decorate([
     property({ type: Number })
 ], HelixHeadlessSplitter.prototype, "position", null);
+__decorate([
+    property()
+], HelixHeadlessSplitter.prototype, "snap", void 0);
+__decorate([
+    property({ attribute: 'snap-threshold', type: Number })
+], HelixHeadlessSplitter.prototype, "snapThreshold", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessSplitter.prototype, "step", void 0);

package/dist/splitter/snap.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Where a dragged divider lands: on the nearest snap point within `threshold`,
+ * or where the pointer is.
+ *
+ * Every number is a percentage of the splitter's box, so the caller turns a
+ * point written as a length, and the threshold, into one first. Ties go to the
+ * point written first.
+ */
+export declare const snapTo: (position: number, points: readonly number[], threshold: number) => number;

package/dist/splitter/snap.js

@@ -0,0 +1,12 @@
+export const snapTo = (position, points, threshold) => {
+    let best;
+    let distance = Number.POSITIVE_INFINITY;
+    for (const point of points) {
+        const away = Math.abs(point - position);
+        if (away <= threshold && away < distance) {
+            best = point;
+            distance = away;
+        }
+    }
+    return best ?? position;
+};

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

@@ -12,6 +12,13 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * add an attribute after upgrade, which markup rendered on the server by React
  * does not have.
  *
+ * **A stat with a label is a group named by it**, so a reader moving through a
+ * dashboard hears "Revenue, group" and then the figure, its unit and its
+ * trend as one reading, rather than a run of loose words. The role and the name
+ * are set through `ElementInternals` once the label is known, which writes no
+ * attribute; a stat with no label has no role. Put a `Trend` in the `trend`
+ * slot to have it read inside the group, after the figure it qualifies.
+ *
  * @since 0.1.0
  * @status stable
  * @category data
@@ -19,7 +26,8 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/stat
  *
  * @slot - The value.
- * @slot label - What the value measures.
+ * @slot label - What the value measures, which also names the stat for a screen reader.
+ * @slot trend - How the value moved, usually a `Trend`, read after the value inside the stat's group.
  * @slot unit - The unit, shown beside the value.
  *
  * @csspart value - The slot the value is written in. A slot draws no box, so it takes the inherited properties, such as color and font, and passes them to the value.
@@ -40,10 +48,9 @@ export declare class HelixHeadlessStat extends HelixElement {
      * the value's baseline whichever way the pair goes, and only this element
      * knows which of its children the unit belongs to.
      *
-     * **`Trend` has a `direction` too, and there it means which way a number
-     * moved:** `up`, `down` or `neutral`. A Stat and a Trend are often written
-     * side by side, so watch for the mix-up. On a Stat those three words are not
-     * layouts, and the pair stays the column.
+     * The name and the values are `Flex`'s, which lays out the same way. Which
+     * way a number moved is `Trend`'s `movement`. On a Stat, `up`, `down` and
+     * `neutral` are not layouts, and the pair stays the column.
      *
      * **Optional rather than defaulted to `column`, which is not a style
      * preference.** A reflecting property with a default writes its attribute onto
@@ -54,6 +61,8 @@ export declare class HelixHeadlessStat extends HelixElement {
      * carries nothing nobody wrote.
      */
     direction?: 'column-reverse' | 'row' | 'row-reverse';
+    protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }

package/dist/stat/root/stat-root.js

@@ -4,10 +4,25 @@ 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, reportRuntime } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, hostAria, reportRuntime, slottedWords, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 let HelixHeadlessStat = class HelixHeadlessStat extends HelixElement {
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        const labels = this.knownChildren.filter((child) => child.slot === 'label');
+        hostAria(this.internals, {
+            label: labels.length > 0 && !('ariaLabelledByElements' in this.internals)
+                ? slottedWords(this, ['label'])
+                : '',
+            labelledBy: labels,
+            role: labels.length > 0 ? 'group' : '',
+        });
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.finishHydration();
+    }
     updated(changed) {
         super.updated(changed);
         const given = this.direction;
@@ -15,16 +30,17 @@ let HelixHeadlessStat = class HelixHeadlessStat extends HelixElement {
             reportRuntime({
                 kind: 'misread-direction',
                 message: `<${this.localName} direction="${given}"> lays out as the column: \`${given}\` is a ` +
-                    "direction of Trend's, which says which way a number moved. Put it on the " +
-                    '`helix-trend` beside the stat.',
+                    "`movement` of Trend's, which says which way a number moved. Put it on the " +
+                    "`helix-trend` in the stat's `trend` slot.",
                 tag: this.localName,
             });
         }
     }
     render() {
-        return html `<slot name="label"></slot>
+        return html `<slot name="label" @slotchange=${() => this.requestUpdate()}></slot>
       <slot part="value"></slot>
-      <slot name="unit"></slot>`;
+      <slot name="unit"></slot>
+      <slot name="trend"></slot>`;
     }
 };
 __decorate([

package/dist/steps/reach.d.ts

@@ -0,0 +1,20 @@
+/** What linear mode reads of a step. */
+export interface ReachableStep {
+    /** Whether the stage is finished. */
+    complete: boolean;
+    /** Whether a reader may pass the stage without finishing it. */
+    optional: boolean;
+}
+/**
+ * Whether a reader on step `from` may go to step `to`, in a linear sequence.
+ *
+ * Back is always allowed, as Ark UI's linear steps allow it. Forward is allowed
+ * only where every stage from the one the reader is on up to the target is
+ * complete or optional, so no stage is passed unfinished.
+ */
+export declare const canReach: (steps: readonly ReachableStep[], from: number, to: number) => boolean;
+/**
+ * How far through a sequence is, from 0 to 100: the share of its stages that
+ * are complete, rounded to a whole number. An empty sequence is at 0.
+ */
+export declare const progressOf: (steps: readonly Pick<ReachableStep, 'complete'>[]) => number;

package/dist/steps/reach.js

@@ -0,0 +1,15 @@
+export const canReach = (steps, from, to) => {
+    if (to <= from) {
+        return true;
+    }
+    for (let at = Math.max(from, 0); at < to; at += 1) {
+        const step = steps[at];
+        if (step && !step.complete && !step.optional) {
+            return false;
+        }
+    }
+    return true;
+};
+export const progressOf = (steps) => steps.length === 0
+    ? 0
+    : Math.round((steps.filter((step) => step.complete).length / steps.length) * 100);