@fusion.dev/helix-headless 0.170.0 → 0.172.0

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

@@ -1,4 +1,4 @@
-import { HelixElement, KeyboardNavigationController } from '@fusion.dev/helix-core';
+import { CommandController, HelixElement, KeyboardNavigationController } 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;
@@ -14,12 +14,21 @@ 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.
  *
+ * `active` names a step by its `value`. A step with no `value` is named by its
+ * place, counted from 1, so a sequence written without values moves as one
+ * written with them, and `helix-activate` says `1`, `2` and so on. Give every
+ * step a value or none, because a value of `2` and the second place are one
+ * name.
+ *
  * `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. `reset()` goes back to the first stage and
- * clears every stage's `complete`, as Ark UI's `resetStep` does.
+ * clears every stage's `complete`, as Ark UI's `resetStep` does. A button
+ * anywhere on the page calls them with no script, as Ark UI's previous and
+ * next triggers do: give it `commandfor` with the sequence's `id`, and
+ * `command="--previous"`, `"--next"` or `"--reset"`.
  *
  * `completion="passed"` marks a stage `complete` once a reader moves past it,
  * as Ark UI counts a stage before the current one as completed. Going back
@@ -46,11 +55,13 @@ declare const HelixHeadlessSteps_base: (new (...args: any[]) => import("@fusion.
  * button is described by its `complete-label`.
  *
  * **Keyboard.** Each stage's name is a button and its own tab stop, and Enter
- * or Space goes to the stage. Set `arrows` and the arrow keys move focus
- * between the names as well, as Ark UI's steps do: Left and Right along a row,
- * Up and Down a column, Home and End to the first and the last. The arrows
- * pass over a disabled stage and one a linear sequence holds out of reach,
- * and they move focus without going to the stage.
+ * or Space goes to the stage. Set `arrows` and the names are one tab stop, the
+ * current stage's, and the arrow keys move focus between them: Left and Right
+ * along a row, Up and Down a column, Home and End to the first and the last.
+ * The stop follows focus, so Tab leaves the sequence and Shift+Tab comes back
+ * to the name the reader left. The arrows pass over a disabled stage and one a
+ * linear sequence holds out of reach, and they move focus without going to the
+ * stage.
  *
  * @since 0.1.0
  * @status stable
@@ -78,7 +89,8 @@ export declare class HelixHeadlessSteps extends HelixHeadlessSteps_base {
     static words: string;
     /**
      * Whether the arrow keys move focus between the stages' names, along the
-     * way the steps run. Off by default, so the arrows keep scrolling the page.
+     * way the steps run, and the names are one tab stop. Off by default, so the
+     * arrows keep scrolling the page.
      */
     arrows: boolean;
     /**
@@ -148,6 +160,7 @@ export declare class HelixHeadlessSteps extends HelixHeadlessSteps_base {
      */
     variant?: 'numeric';
     protected readonly keys: KeyboardNavigationController;
+    protected readonly commands: CommandController;
     /** The steps, in the order the consumer wrote them. */
     private get steps();
     /**
@@ -158,6 +171,8 @@ export declare class HelixHeadlessSteps extends HelixHeadlessSteps_base {
      * calls to `next()` in one task then move two stages.
      */
     private get at();
+    /** The step `active` names, by `value` or by place, or the first enabled one. */
+    private named;
     /**
      * Requests a new current stage, and returns whether it moved.
      *
@@ -207,6 +222,15 @@ export declare class HelixHeadlessSteps extends HelixHeadlessSteps_base {
      */
     private sync;
     private readonly handleSelection;
+    /** The step whose name holds the sequence's one tab stop under `arrows`, once focus has chosen it. */
+    private holder;
+    /**
+     * Gives the one tab stop to a name, under `arrows`: the one focus last left,
+     * else the current stage's, else the first a reader can go to. Without
+     * `arrows` every name is its own stop. Client only.
+     */
+    private rove;
+    private readonly handleFocus;
     private readonly handleSlotChange;
     connectedCallback(): void;
     disconnectedCallback(): void;

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

@@ -4,7 +4,7 @@ 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, focusItemOf, formatWords, HelixElement, hostAria, KeyboardNavigationController, MixinControllerActive, whenHydrated, words, } from '@fusion.dev/helix-core';
+import { CommandController, customElement, focusItemOf, formatWords, HelixElement, hostAria, KeyboardNavigationController, MixinControllerActive, whenHydrated, words, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 import { canReach, progressOf } from '../reach.js';
@@ -19,6 +19,7 @@ const navigable = (step) => {
         },
     });
 };
+const keyOf = (step, index) => step.value || String(index + 1);
 let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(HelixElement) {
     constructor() {
         super(...arguments);
@@ -33,6 +34,13 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
             selects: () => false,
             wrap: false,
         });
+        this.commands = new CommandController(this, {
+            commands: {
+                '--next': () => this.next(),
+                '--previous': () => this.previous(),
+                '--reset': () => this.reset(),
+            },
+        });
         this.handleSelection = (event) => {
             if (!this.steps.includes(event.target)) {
                 return;
@@ -42,12 +50,27 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
                 if (event.defaultPrevented || !this.reachable(index) || !this.valid(index)) {
                     return;
                 }
-                this.requestActive(event.detail.value);
+                this.requestActive(keyOf(this.steps[index], index));
             });
         };
+        this.handleFocus = (event) => {
+            if (!this.arrows) {
+                return;
+            }
+            const path = event.composedPath();
+            const step = this.steps.find((one) => {
+                const name = one.shadowRoot?.querySelector('[part="label"]');
+                return name ? path.includes(name) : false;
+            });
+            if (step && step !== this.holder) {
+                this.holder = step;
+                this.rove();
+            }
+        };
         this.handleSlotChange = () => {
             this.sync();
             this.lock();
+            this.rove();
         };
     }
     static { this.words = 'helix-steps'; }
@@ -62,11 +85,20 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
         if (this.active === '') {
             return steps.findIndex((step) => step.current);
         }
-        const item = this.resolveActive(steps);
+        const item = this.named(steps);
         return item ? steps.indexOf(item) : -1;
     }
+    named(steps) {
+        const keyed = steps.map((step, index) => ({
+            disabled: step.disabled,
+            step,
+            value: keyOf(step, index),
+        }));
+        return this.resolveActive(keyed)?.step;
+    }
     requestActive(next, cause) {
-        const here = this.active === '' ? this.steps[this.at]?.value : undefined;
+        const at = this.active === '' ? this.at : -1;
+        const here = at === -1 ? undefined : keyOf(this.steps[at], at);
         if (here) {
             this.active = here;
         }
@@ -80,8 +112,8 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
     }
     reset() {
         const steps = this.steps;
-        const first = steps.find((one) => !one.disabled);
-        if (!first || !this.requestActive(first.value)) {
+        const first = steps.findIndex((one) => !one.disabled);
+        if (first === -1 || !this.requestActive(keyOf(steps[first], first))) {
             return false;
         }
         for (const one of steps) {
@@ -100,7 +132,7 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
         if (!target || !this.reachable(index) || !this.valid(index)) {
             return false;
         }
-        return this.requestActive(target.value);
+        return this.requestActive(keyOf(target, index));
     }
     valid(index) {
         const from = this.steps[this.at];
@@ -128,8 +160,8 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
             return;
         }
         const steps = this.steps;
-        const value = this.resolveActive(steps)?.value ?? '';
-        const reached = steps.findIndex((step) => step.value === value);
+        const named = this.named(steps);
+        const reached = named ? steps.indexOf(named) : -1;
         steps.forEach((step, index) => {
             const current = index === reached;
             const passed = this.completion === 'passed' && index < reached;
@@ -141,11 +173,30 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
             });
         });
     }
+    rove() {
+        const steps = this.steps;
+        const open = steps.filter((step, index) => !step.disabled && this.reachable(index));
+        const current = steps[this.at];
+        const holder = !this.arrows
+            ? undefined
+            : this.holder && open.includes(this.holder)
+                ? this.holder
+                : current && open.includes(current)
+                    ? current
+                    : open[0];
+        for (const step of steps) {
+            whenHydrated(step, () => {
+                step.stop = !this.arrows || step === holder;
+            });
+        }
+    }
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('helix-select', this.handleSelection);
+        this.addEventListener('focusin', this.handleFocus);
         this.watcher = new MutationObserver(() => {
             this.lock();
+            this.rove();
             this.requestUpdate();
         });
         this.watcher.observe(this, {
@@ -157,6 +208,7 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener('helix-select', this.handleSelection);
+        this.removeEventListener('focusin', this.handleFocus);
         this.watcher?.disconnect();
         this.watcher = undefined;
     }
@@ -181,6 +233,15 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
         if (changed.has('linear') || changed.has('active') || changed.has('completion')) {
             this.lock();
         }
+        if (changed.has('active')) {
+            this.holder = undefined;
+        }
+        if (changed.has('arrows') ||
+            changed.has('linear') ||
+            changed.has('active') ||
+            changed.has('completion')) {
+            this.rove();
+        }
     }
     render() {
         const progress = progressOf(this.known);

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

@@ -106,7 +106,15 @@ export declare class HelixHeadlessStep extends HelixElement {
      */
     optional: boolean;
     /**
-     * The value the step sends in `helix-select`.
+     * @internal Set by a sequence with `arrows`: whether the name holds the
+     * sequence's one tab stop. A property, because the sequence writes it after
+     * the step upgrades.
+     */
+    stop: boolean;
+    /**
+     * The value the step sends in `helix-select`, and what names the step in its
+     * sequence's `active`. Without one, the sequence names the step by its place,
+     * counted from 1.
      */
     value: string;
     /** Whether anything is slotted into `content`, which makes it a named group. */

package/dist/steps/step/step.js

@@ -22,6 +22,7 @@ let HelixHeadlessStep = class HelixHeadlessStep extends HelixElement {
         this.invalid = false;
         this.locked = false;
         this.optional = false;
+        this.stop = true;
         this.value = '';
         this.holding = false;
         this.readContent = () => {
@@ -73,6 +74,7 @@ let HelixHeadlessStep = class HelixHeadlessStep extends HelixElement {
       part="label"
       exportparts="button: label-button, live: label-live, spinner: label-spinner, text: label-text"
       emphasis="ghost"
+      .focusable=${this.stop}
       aria-current=${this.current ? 'step' : nothing}
       aria-describedby=${this.complete ? 'state' : nothing}
       ?disabled=${this.disabled || this.locked}
@@ -122,6 +124,9 @@ __decorate([
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessStep.prototype, "optional", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessStep.prototype, "stop", void 0);
 __decorate([
     property()
 ], HelixHeadlessStep.prototype, "value", void 0);

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

@@ -217,6 +217,14 @@ export declare class HelixHeadlessTextarea extends HelixHeadlessTextarea_base {
      * and so does this.
      */
     setSelectionRange(start: number, end: number, direction?: SelectionDirection): void;
+    /**
+     * Replaces a range of the text, as the native method does: the selection
+     * where `start` and `end` are left out, and `selectMode` says what is
+     * selected after. It sends no event, as the native method sends none.
+     */
+    setRangeText(replacement: string, start?: number, end?: number, selectMode?: SelectionMode): void;
+    /** Selects everything in the field. */
+    select(): void;
     /** How many characters the value holds. */
     get textLength(): number;
     /** The control's type, which is always `textarea`. */

package/dist/textarea/root/textarea-root.js

@@ -111,6 +111,22 @@ let HelixHeadlessTextarea = class HelixHeadlessTextarea extends MixinControllerV
     setSelectionRange(start, end, direction) {
         this.control?.setSelectionRange(start, end, direction);
     }
+    setRangeText(replacement, start, end, selectMode) {
+        const control = this.control;
+        if (!control) {
+            return;
+        }
+        if (start === undefined || end === undefined) {
+            control.setRangeText(replacement);
+        }
+        else {
+            control.setRangeText(replacement, start, end, selectMode);
+        }
+        this.value = control.value;
+    }
+    select() {
+        this.control?.select();
+    }
     get textLength() {
         return this.value.length;
     }

package/dist/video-playlist/root/video-playlist-root.d.ts

@@ -11,6 +11,12 @@ declare const HelixHeadlessVideoPlaylist_base: (new (...args: any[]) => import("
  * captions, and poster treatment. `Sandbox` takes its preview and `Menu` its
  * trigger the same way.
  *
+ * **The player is a `Video` or a plain `<video>`.** Either takes `src` and
+ * `poster` from the entry, is named by it, plays on, and answers Shift with N
+ * or P while focused. A plain `<video>` has no previous and next controls
+ * that send `helix-previous` or `helix-next`, so its moves are the entries,
+ * the menu, and your own buttons calling `previous()` and `next()`.
+ *
  * **Entries are markup.** React skips properties it would set imperatively
  * during hydration, so an array property on a custom element is missing on the
  * first paint of a server-rendered page. `using-the-elements.mdx` has the
@@ -43,7 +49,8 @@ declare const HelixHeadlessVideoPlaylist_base: (new (...args: any[]) => import("
  *
  * **The player is named by the current entry**, and the device's own media
  * controls show the entry as the title. A player you gave a `label` keeps
- * your name, and only the title follows the entry.
+ * your name, and only the title follows the entry. A plain `<video>` is
+ * named through `aria-label`, unless you wrote one.
  *
  * **Keyboard.** The entries take one stop in the tab order: the entry you
  * last focused, or the current entry before you have focused one. Enter or
@@ -235,6 +242,17 @@ export declare class HelixHeadlessVideoPlaylist extends HelixHeadlessVideoPlayli
      * Before they focus one, the current entry holds it.
      */
     private stop;
+    /** The name this playlist last wrote on a plain media player, to tell it from yours. */
+    private wroteName;
+    /**
+     * Names the player by the entry.
+     *
+     * The consumer's own name for the player stands. Only a player named by
+     * nobody takes the entry's words as its name: `label` on a player that has
+     * one, and `aria-label` on a plain `<video>` or `<audio>`, which has none and
+     * was heard as an unnamed video.
+     */
+    private name;
     /** The entry the player was last pointed at. */
     private pointed;
     /** Hears entries arrive and leave, which change no property here. */

package/dist/video-playlist/root/video-playlist-root.js

@@ -161,6 +161,19 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
     get items() {
         return [...this.querySelectorAll('*')].filter((one) => one instanceof HelixHeadlessVideoPlaylistItem && one.value !== '');
     }
+    name(player, text) {
+        if (player instanceof HTMLMediaElement) {
+            const own = player.getAttribute('aria-label');
+            if (own === null || own === this.wroteName) {
+                player.setAttribute('aria-label', text);
+                this.wroteName = text;
+            }
+            return;
+        }
+        if (!player.hasAttribute('label')) {
+            player.label = text;
+        }
+    }
     get player() {
         const slot = this.renderRoot?.querySelector('slot[name="player"]');
         return slot?.assignedElements()[0] ?? null;
@@ -299,9 +312,7 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
             }
             player.poster = current.poster;
             player.mediaTitle = current.text;
-            if (!player.hasAttribute('label')) {
-                player.label = current.text;
-            }
+            this.name(player, current.text);
             if (this.chased) {
                 this.status.say(formatWords(this, 'playingLabel', { title: current.text }));
                 void player.updateComplete?.then(() => player.play()).catch(() => { });

package/dist/virtual-list/root/virtual-list-root.d.ts

@@ -119,6 +119,11 @@ export interface VirtualListRange {
  * commas. Their rows carry `aria-disabled`, the keys and typing pass over
  * them, and a press, Space, or Control with A does not select them.
  *
+ * **Rows a stylesheet can tell apart.** A chosen row carries `data-selected`,
+ * a disabled one `data-disabled`, as React Aria's rows do, and the row the
+ * keys are on, which holds the tab stop, `data-active`, whether or not the
+ * list has focus.
+ *
  * **Loading more.** `helix-range-change` fires as the items on screen change,
  * and `range` holds them. `helix-load-more` fires once a reader is within one
  * screen of the end, once for each length of the set: add to `items` and it can
@@ -560,6 +565,9 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * `option` with `aria-selected` there, and `listitem` otherwise, and
      * `aria-disabled` on an item `disabled-keys` names. Every pass,
      * since a choice changes no row's content.
+     *
+     * `data-selected` and `data-disabled` say the same to a stylesheet, as
+     * React Aria's rows do, so one rule reads the same in either kind of list.
      */
     private mark;
     /** Writes a row's place in the set. */

package/dist/virtual-list/root/virtual-list-root.js

@@ -532,18 +532,22 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
     }
     mark(element, at, chosen, off) {
         element.setAttribute('role', this.selectionMode ? 'option' : 'listitem');
+        const selected = Boolean(this.selectionMode) && chosen.has(this.keyAt(at));
         if (this.selectionMode) {
-            element.setAttribute('aria-selected', String(chosen.has(this.keyAt(at))));
+            element.setAttribute('aria-selected', String(selected));
         }
         else {
             element.removeAttribute('aria-selected');
         }
-        if (off.size > 0 && off.has(this.keyAt(at))) {
+        element.toggleAttribute('data-selected', selected);
+        const disabled = off.size > 0 && off.has(this.keyAt(at));
+        if (disabled) {
             element.setAttribute('aria-disabled', 'true');
         }
         else {
             element.removeAttribute('aria-disabled');
         }
+        element.toggleAttribute('data-disabled', disabled);
     }
     stamp(element, at) {
         element.setAttribute('aria-posinset', String(at + 1));
@@ -660,6 +664,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             }
             const stop = at === this.active;
             group[0]?.setAttribute('tabindex', stop ? '0' : '-1');
+            group[0]?.toggleAttribute('data-active', stop);
             if (stop && (fresh.has(at) || this.released !== at)) {
                 releaseControls(group);
             }