@fusion.dev/helix-headless 0.144.0 → 0.146.0

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

@@ -1,5 +1,6 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
+import type { HelixHeadlessStep } from '../step/step.js';
 declare const HelixHeadlessSteps_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerActiveInterface) & typeof HelixElement;
 /**
  * @summary A sequence of stages that shows which stage the user is on.
@@ -13,6 +14,29 @@ declare const HelixHeadlessSteps_base: (new (...args: any[]) => import("@fusion.
  * sequence is correct in the server's markup, where the root cannot count its
  * slotted children.
  *
+ * `linear` keeps a reader from passing a stage they have not finished, as Ark
+ * UI's linear steps do: a stage ahead is out of reach, and its button disabled,
+ * until every stage before it is `complete` or `optional`. Going back is always
+ * allowed. `next()` and `previous()` move one stage either way, under the
+ * same rules, for your own buttons.
+ *
+ * To check a stage before a reader moves on from it, set `validate` to a
+ * function that answers whether the stage is valid, as Ark UI's `isStepValid`
+ * does. Moving forward asks it about the stage the reader is on, and where it
+ * answers `false` the reader stays and the stage is `:state(invalid)` until it
+ * answers `true`. An `optional` stage is not asked. `helix-before-activate`
+ * is still sent for every move, for a check of your own.
+ *
+ * `progress` is how far through the sequence is, from 0 to 100: the share of
+ * its stages that are `complete`. The `progress` part carries it as a
+ * `progressbar` and as `--steps-progress`, and is hidden until a stylesheet
+ * gives it a `display`, so a bar of your own costs nothing until you draw it.
+ * The sequence is `:state(complete)` once every stage is.
+ *
+ * The sequence is a list named by `label`, and each step a list item. The
+ * current stage's button says `aria-current="step"`, and a finished stage's
+ * button is described by its `complete-label`.
+ *
  * @since 0.1.0
  * @status stable
  * @category navigation
@@ -24,6 +48,12 @@ declare const HelixHeadlessSteps_base: (new (...args: any[]) => import("@fusion.
  * @event {HelixActivateEvent} helix-activate - Fired after the current step changes, when the element already holds the new step.
  * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the active step changes. Cancelable: cancel it to keep the current step.
  * @event {HelixSelectEvent} helix-select - Fired when a step is pressed. The step dispatches it, and you can listen for it on the sequence. Cancelable: cancel it to keep the current step.
+ *
+ * @csspart progress - How far through the sequence is, as a `progressbar` carrying `--steps-progress`. Hidden until a stylesheet gives it a `display`.
+ *
+ * @cssproperty --steps-progress - How far through the sequence is, as a percentage, written on the `progress` part.
+ *
+ * @cssstate complete - Every stage is complete.
  */
 export declare class HelixHeadlessSteps extends HelixHeadlessSteps_base {
     /**
@@ -33,6 +63,11 @@ export declare class HelixHeadlessSteps extends HelixHeadlessSteps_base {
      * needs a name of its own rather than borrowing the heading above it.
      */
     label: string;
+    /**
+     * Whether a reader has to finish each stage, or pass an `optional` one,
+     * before going on to the next.
+     */
+    linear: boolean;
     /**
      * Which way the steps run.
      *
@@ -47,6 +82,17 @@ export declare class HelixHeadlessSteps extends HelixHeadlessSteps_base {
      * catches people out.
      */
     orientation?: 'vertical';
+    /**
+     * A function that answers whether a stage is valid, asked about the stage a
+     * reader is on before they move forward from it. Return `false` to keep them
+     * there. Not asked of an `optional` stage, nor for a move back.
+     */
+    validate?: (step: HelixHeadlessStep) => boolean;
+    /**
+     * How far through the sequence is, from 0 to 100: the share of its stages
+     * that are `complete`, rounded to a whole number.
+     */
+    get progress(): number;
     /**
      * What each step is marked with.
      *
@@ -62,6 +108,30 @@ export declare class HelixHeadlessSteps extends HelixHeadlessSteps_base {
     variant?: 'numeric';
     /** The steps, in the order the consumer wrote them. */
     private get steps();
+    /** The index of the stage the reader is on, or `-1`. */
+    private get at();
+    /**
+     * Moves to the next stage that can be gone to, as Ark UI's `goToNextStep`
+     * does. Returns whether it moved: not past the last stage, not into a stage
+     * `linear` holds out of reach, and not where a listener refused.
+     */
+    next(): boolean;
+    /** Moves to the stage before, as Ark UI's `goToPrevStep` does. Returns whether it moved. */
+    previous(): boolean;
+    /** Moves `delta` stages, skipping disabled ones. */
+    private step;
+    /**
+     * Whether the stage the reader is on lets them go to the stage at `index`,
+     * by `validate`. Only a move forward is asked, and an `optional` stage is
+     * never asked. The stage is marked invalid while the answer is no.
+     */
+    private valid;
+    /** Whether the stage at `index` can be gone to from where the reader is. */
+    private reachable;
+    /** Marks the stages a linear sequence holds out of reach. Client only. */
+    private lock;
+    /** Watches what decides a stage's reach: which is current, which are done. */
+    private watcher;
     /**
      * Puts `active` on whichever step owns it.
      *
@@ -78,7 +148,13 @@ export declare class HelixHeadlessSteps extends HelixHeadlessSteps_base {
     private readonly handleSlotChange;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /**
+     * The steps where they can be known, and none on a server or while
+     * hydrating, so the progress drawn first is the server's.
+     */
+    private get known();
     protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }

package/dist/steps/root/steps-root.js

@@ -7,23 +7,75 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria, MixinControllerActive, whenHydrated, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
+import { canReach, progressOf } from '../reach.js';
 let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(HelixElement) {
     constructor() {
         super(...arguments);
         this.label = 'Steps';
+        this.linear = false;
         this.handleSelection = (event) => {
             if (event.defaultPrevented || !this.steps.includes(event.target)) {
                 return;
             }
+            const index = this.steps.indexOf(event.target);
+            if (!this.reachable(index) || !this.valid(index)) {
+                return;
+            }
             this.requestActive(event.detail.value);
         };
         this.handleSlotChange = () => {
             this.sync();
+            this.lock();
         };
     }
+    get progress() {
+        return progressOf(this.steps);
+    }
     get steps() {
         return [...this.querySelectorAll(':scope > *')].filter((one) => 'current' in one);
     }
+    get at() {
+        return this.steps.findIndex((step) => step.current);
+    }
+    next() {
+        return this.step(1);
+    }
+    previous() {
+        return this.step(-1);
+    }
+    step(delta) {
+        const steps = this.steps;
+        let index = this.at + delta;
+        while (steps[index]?.disabled) {
+            index += delta;
+        }
+        const target = steps[index];
+        if (!target || !this.reachable(index) || !this.valid(index)) {
+            return false;
+        }
+        return this.requestActive(target.value);
+    }
+    valid(index) {
+        const from = this.steps[this.at];
+        if (!from || index <= this.at || !this.validate || from.optional) {
+            return true;
+        }
+        const valid = this.validate(from);
+        from.invalid = !valid;
+        return valid;
+    }
+    reachable(index) {
+        return !this.linear || canReach(this.steps, this.at, index);
+    }
+    lock() {
+        const steps = this.steps;
+        steps.forEach((step, index) => {
+            const locked = !this.reachable(index);
+            whenHydrated(step, () => {
+                step.locked = locked;
+            });
+        });
+    }
     sync() {
         if (this.active === '') {
             return;
@@ -40,31 +92,71 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('helix-select', this.handleSelection);
+        this.watcher = new MutationObserver(() => {
+            this.lock();
+            this.requestUpdate();
+        });
+        this.watcher.observe(this, {
+            attributeFilter: ['complete', 'current', 'optional'],
+            attributes: true,
+            subtree: true,
+        });
     }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener('helix-select', this.handleSelection);
+        this.watcher?.disconnect();
+        this.watcher = undefined;
+    }
+    get known() {
+        return this.knownChildren.filter((one) => 'current' in one);
     }
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label, role: 'list' });
+        const known = this.known;
+        this.toggleState('complete', known.length > 0 && known.every((step) => step.complete));
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.finishHydration();
     }
     updated(changed) {
         super.updated(changed);
         if (changed.has('active')) {
             this.sync();
         }
+        if (changed.has('linear') || changed.has('active')) {
+            this.lock();
+        }
     }
     render() {
-        return html `<slot @slotchange=${this.handleSlotChange}></slot>`;
+        const progress = progressOf(this.known);
+        return html `<slot @slotchange=${this.handleSlotChange}></slot>
+      <div
+        part="progress"
+        role="progressbar"
+        aria-label=${this.label}
+        aria-valuemin="0"
+        aria-valuemax="100"
+        aria-valuenow=${progress}
+        style="--steps-progress: ${progress}%"
+        hidden
+      ></div>`;
     }
 };
 __decorate([
     property()
 ], HelixHeadlessSteps.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessSteps.prototype, "linear", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessSteps.prototype, "orientation", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessSteps.prototype, "validate", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessSteps.prototype, "variant", void 0);

package/dist/steps/step/step.d.ts

@@ -1,5 +1,5 @@
 import { HelixElement } from '@fusion.dev/helix-core';
-import type { PropertyValues, TemplateResult } from 'lit';
+import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../button/index.js';
 /**
  * @summary One stage in a sequence.
@@ -21,6 +21,12 @@ import '../../button/index.js';
  * and `::after` from properties the list sets, so the step renders no extra
  * element for them.
  *
+ * A finished stage says so in words: the name's button is described by
+ * `complete-label`, "Complete" unless you translate it, and a stage that
+ * becomes complete while the page is open says it once in a polite live
+ * region. The current stage's button carries `aria-current="step"`, and only
+ * the button, so the state is said once, on the control.
+ *
  * @since 0.1.0
  * @status stable
  * @aliases Stage
@@ -40,14 +46,23 @@ import '../../button/index.js';
  * @csspart label-button - The button inside the label.
  * @csspart label-live - The live region inside that button, rendered only from the first time the button is pending.
  * @csspart label-text - The words on that button, trimmed to their capitals and baseline.
+ * @csspart live - The live region that says a stage was completed, rendered from the first time one is.
  * @csspart mark - The glyph inside the marker: a tick, a dot, or an empty ring.
  * @csspart marker - The shape carrying the number or the check.
+ * @csspart state - The words that describe a finished stage's button. Hidden.
+ *
+ * @cssstate invalid - The sequence's `validate` last answered that this stage is not valid.
  */
 export declare class HelixHeadlessStep extends HelixElement {
     /**
      * Whether this stage is finished.
      */
     complete: boolean;
+    /**
+     * The words that tell a screen reader the stage is finished. Translate it
+     * with the page.
+     */
+    completeLabel: string;
     /**
      * Whether this is the current stage.
      */
@@ -56,11 +71,32 @@ export declare class HelixHeadlessStep extends HelixElement {
      * Whether the stage is disabled, so the user cannot go to it.
      */
     disabled: boolean;
+    /**
+     * @internal Set by the sequence: whether its `validate` last answered that
+     * this stage is not valid. Recorded as `:state(invalid)`.
+     */
+    invalid: boolean;
+    /**
+     * @internal Set by a linear sequence: whether the stage is out of reach
+     * until the ones before it are finished. A property, because the sequence
+     * writes it after the step upgrades.
+     */
+    locked: boolean;
+    /**
+     * Whether a reader may pass the stage without finishing it, in a sequence
+     * with `linear`. Ark UI's skippable step.
+     */
+    optional: boolean;
     /**
      * The value the step sends in `helix-select`.
      */
     value: string;
-    /** Fires `helix-select` for the step, unless the step is `disabled`. */
+    /** Says a stage was finished, from the first time one is. */
+    private readonly status;
+    /**
+     * Fires `helix-select` for the step, unless the step is `disabled` or a
+     * linear sequence has it out of reach.
+     */
     select(): void;
     /**
      * The mark this stage's state calls for.
@@ -85,6 +121,13 @@ export declare class HelixHeadlessStep extends HelixElement {
      */
     protected renderMarker(): TemplateResult;
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Says a stage that was finished while the page is open, with its name.
+     *
+     * Only a change after the first update, so a sequence served with its done
+     * stages says nothing when it arrives.
+     */
+    protected updated(changed: PropertyValues): void;
     /**
      * The step's own label, which is a control because a step can be gone to, behind a seam the styled tier can move.
      *

package/dist/steps/step/step.js

@@ -4,8 +4,9 @@ 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, HelixSelectEvent, hostAria } from '@fusion.dev/helix-core';
+import { customElement, drawStatus, HelixElement, HelixSelectEvent, hostAria, StatusController, slottedWords, } from '@fusion.dev/helix-core';
 import { check, circle, record } from '@fusion.dev/helix-icons';
+import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { html } from 'lit/static-html.js';
@@ -14,12 +15,17 @@ let HelixHeadlessStep = class HelixHeadlessStep extends HelixElement {
     constructor() {
         super(...arguments);
         this.complete = false;
+        this.completeLabel = 'Complete';
         this.current = false;
         this.disabled = false;
+        this.invalid = false;
+        this.locked = false;
+        this.optional = false;
         this.value = '';
+        this.status = new StatusController(this);
     }
     select() {
-        if (this.disabled) {
+        if (this.disabled || this.locked) {
             return;
         }
         this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
@@ -35,18 +41,27 @@ let HelixHeadlessStep = class HelixHeadlessStep extends HelixElement {
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { role: 'listitem' });
-        this.internals.ariaCurrent = this.current ? 'step' : null;
+        this.toggleState('invalid', this.invalid);
+    }
+    updated(changed) {
+        super.updated(changed);
+        if (changed.get('complete') === false && this.complete) {
+            const name = slottedWords(this, ['']);
+            this.status.say(name === '' ? this.completeLabel : `${name}, ${this.completeLabel}`);
+        }
     }
     renderLabel() {
         return html `<${this.tag('button')}
       part="label"
       exportparts="button: label-button, live: label-live, text: label-text"
       emphasis="ghost"
-      ?disabled=${this.disabled}
+      aria-current=${this.current ? 'step' : nothing}
+      aria-describedby=${this.complete ? 'state' : nothing}
+      ?disabled=${this.disabled || this.locked}
       @click=${this.select}
     >
       <slot></slot>
-    </${this.tag('button')}>`;
+    </${this.tag('button')}><span id="state" part="state" hidden>${this.complete ? this.completeLabel : ''}</span>`;
     }
     render() {
         return html `<span part="marker" aria-hidden="true">
@@ -56,18 +71,30 @@ let HelixHeadlessStep = class HelixHeadlessStep extends HelixElement {
         ${this.renderLabel()}
         <span part="description"><slot name="description"></slot></span>
       </span>
-      <div part="content"><slot name="content"></slot></div>`;
+      <div part="content"><slot name="content"></slot></div>${drawStatus(this.status)}`;
     }
 };
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessStep.prototype, "complete", void 0);
+__decorate([
+    property({ attribute: 'complete-label' })
+], HelixHeadlessStep.prototype, "completeLabel", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessStep.prototype, "current", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessStep.prototype, "disabled", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessStep.prototype, "invalid", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessStep.prototype, "locked", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessStep.prototype, "optional", void 0);
 __decorate([
     property()
 ], HelixHeadlessStep.prototype, "value", void 0);

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

@@ -18,6 +18,16 @@ declare const HelixHeadlessSwitch_base: (new (...args: any[]) => import("@fusion
  * press, the same as a checkbox. The hint and the message go below the row,
  * because the switch and its label share one line.
  *
+ * **Keyboard.** The switch is one tab stop.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Space | Turns the switch on or off, as a native checkbox does. |
+ *
+ * The input carries `role="switch"`, so a screen reader says "on" or "off".
+ * `aria-readonly` is set under `readonly`, and `aria-invalid` and
+ * `aria-describedby` point at the message while one shows.
+ *
  * @since 0.1.0
  * @status stable
  * @category forms

package/dist/table/column/table-column.d.ts

@@ -10,16 +10,6 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * `undefined` falls back to the field.
  */
 export type CellReader = (row: Readonly<Record<string, unknown>>) => unknown;
-/**
- * A dot path resolved against a row.
- *
- * Written here rather than taken from a library, because the whole of what is
- * needed is "walk the keys and stop at the first thing that is not an object".
- * Returns `undefined` for a path that does not resolve, which the table renders
- * as an empty cell: a missing key is a hole in the data and drawing `undefined`
- * into a table tells a reader the software is broken rather than the row is.
- */
-export declare const at: (row: Readonly<Record<string, unknown>>, path: string) => unknown;
 /**
  * The edge a column names, where it names one of the three.
  *
@@ -84,6 +74,7 @@ export declare const edgeOf: (align: string | undefined) => string | undefined;
  * @slot - The heading.
  *
  * @event {HelixBeforeResizeEvent} helix-before-resize - The column is about to be resized, with the requested width. Cancelable: cancel it to keep the current width.
+ * @event {HelixResizedEvent} helix-resized - Fired after the column is resized, with the new width.
  *
  * @csspart column - The heading cell.
  * @csspart grip - The handle for moving the column, when the table allows it.
@@ -154,6 +145,16 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      * replaced with the heading text.
      */
     resizeLabel: string;
+    /**
+     * Makes this column's cells the headers of their rows, in `DataTable`.
+     *
+     * A screen reader moving along a row or down a column names the row by its
+     * row header, so the cell that identifies a row, a file's name say, is the
+     * one to mark. Where no column sets it, `DataTable` makes the first column
+     * with a `field` the row header. A `Table`'s cells are your markup, so there
+     * a cell is a row header through its own `header` attribute.
+     */
+    rowHeader: boolean;
     /**
      * Whether the table can be sorted by this column.
      *

package/dist/table/column/table-column.js

@@ -5,27 +5,11 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var HelixHeadlessTableColumn_1;
-import { customElement, fillTemplate, HelixBeforeResizeEvent, HelixElement, hostAria, inlineStep, isRtl, requestChange, } from '@fusion.dev/helix-core';
+import { customElement, fillTemplate, HelixBeforeResizeEvent, HelixElement, HelixResizedEvent, hostAria, inlineStep, isRtl, requestChange, valueAt, } from '@fusion.dev/helix-core';
 import { dotsThreeVertical } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-export const at = (row, path) => {
-    if (path === '') {
-        return undefined;
-    }
-    if (!path.includes('.')) {
-        return row[path];
-    }
-    let cursor = row;
-    for (const key of path.split('.')) {
-        if (cursor === null || typeof cursor !== 'object') {
-            return undefined;
-        }
-        cursor = cursor[key];
-    }
-    return cursor;
-};
 const EDGES = new Set(['center', 'end', 'start']);
 export const edgeOf = (align) => align && EDGES.has(align) ? align : undefined;
 let HelixHeadlessTableColumn = class HelixHeadlessTableColumn extends HelixElement {
@@ -37,6 +21,7 @@ let HelixHeadlessTableColumn = class HelixHeadlessTableColumn extends HelixEleme
         this.moveLabel = 'Move {name}';
         this.resizable = false;
         this.resizeLabel = 'Resize {name}';
+        this.rowHeader = false;
         this.sortable = false;
         this.width = '';
         this.widthLabel = '{width} pixels';
@@ -95,11 +80,11 @@ let HelixHeadlessTableColumn = class HelixHeadlessTableColumn extends HelixEleme
     }
     read(row) {
         const rendered = this.cell?.(row);
-        return rendered === undefined ? at(row, this.field) : rendered;
+        return rendered === undefined ? valueAt(row, this.field) : rendered;
     }
     order(row) {
         const compared = this.compare?.(row);
-        return compared === undefined ? at(row, this.field) : compared;
+        return compared === undefined ? valueAt(row, this.field) : compared;
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -172,6 +157,7 @@ let HelixHeadlessTableColumn = class HelixHeadlessTableColumn extends HelixEleme
         requestChange({
             apply: (value) => {
                 this.width = value;
+                this.dispatchEvent(new HelixResizedEvent({ value }));
             },
             event: (value) => new HelixBeforeResizeEvent({ value }),
             host: this,
@@ -237,6 +223,9 @@ __decorate([
 __decorate([
     property({ attribute: 'resize-label' })
 ], HelixHeadlessTableColumn.prototype, "resizeLabel", void 0);
+__decorate([
+    property({ attribute: 'row-header', type: Boolean })
+], HelixHeadlessTableColumn.prototype, "rowHeader", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessTableColumn.prototype, "sortable", void 0);