@fusion.dev/helix-headless 0.150.0 → 0.152.0

package/dist/tour/naming.js

@@ -1,10 +1,16 @@
 import { headingIn } from '@fusion.dev/helix-core';
-export const stopNaming = ({ content, description, heading, labeled, progress, }) => {
+import { wordsAmong } from '../dialog/description.js';
+export const stopNaming = ({ content, description, heading, labeled, loose = null, progress, }) => {
     const first = heading.length > 0 ? null : headingIn(content);
     const found = heading.length > 0 ? [...heading] : first ? [first] : [];
     const place = progress ? [progress] : [];
+    const said = description.length > 0
+        ? [...description]
+        : content.length === 0 && loose
+            ? [loose]
+            : wordsAmong(content, first);
     if (found.length === 0 && !labeled) {
-        return { describedBy: [...description], labelledBy: place };
+        return { describedBy: said, labelledBy: place };
     }
-    return { describedBy: [...description, ...place], labelledBy: found };
+    return { describedBy: [...said, ...place], labelledBy: found };
 };

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

@@ -40,11 +40,27 @@ declare const HelixHeadlessTour_base: (new (...args: any[]) => import("@fusion.d
  * you have moved it somewhere else on the page. A stop does not trap focus, so
  * you can still `Tab` out to the element it describes.
  *
- * **The arrow keys move between stops** while focus is in one: the arrow that
- * points the way the line runs goes on, and the other goes back, so on a
- * right-to-left page `ArrowLeft` goes on. Neither finishes the tour at the last
- * stop, and a text field in a stop keeps its own arrows. `Escape` skips the
- * tour.
+ * **The target is scrolled into view** before its stop is shown, by the
+ * least distance that brings it on screen, so the stop that points at it is
+ * on screen too.
+ *
+ * **Keyboard.** Focus is on the current stop's panel, which is not in the
+ * `Tab` order itself.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Right | Goes to the next stop. On the last stop it does nothing, and Next finishes the tour. |
+ * | Left | Goes back to the previous stop. |
+ * | Escape | Skips the tour, and puts focus back where it was when the tour opened. |
+ * | Tab, Shift+Tab | Moves through the controls in the stop, and on out to the page. A stop does not trap focus. |
+ * | Enter, Space | On Back, Next, or Skip, presses it. |
+ *
+ * The arrow that points the way the line runs goes on, and the other goes
+ * back, so on a right-to-left page Left goes on and Right goes back. A text field in a stop keeps
+ * its own arrows.
+ *
+ * The tour is a region named by `label` while it runs. A development build
+ * warns when a tour opens with no `label`.
  *
  * @since 0.1.0
  * @status stable
@@ -186,6 +202,14 @@ export declare class HelixHeadlessTour extends HelixHeadlessTour_base {
     disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /** The target last scrolled into view, so a render that moved nothing scrolls nothing. */
+    private revealed;
+    /**
+     * Scrolls the current target into view, by the least distance that brings
+     * it on screen, before its stop is shown beside it. Zag's tour does the same.
+     * A target already on screen does not move.
+     */
+    private reveal;
     /** Where focus was when the tour opened, to give it back when it ends. */
     private returnFocus;
     /** Whether `follow` has seen the first update. */

package/dist/tour/root/tour-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 { controlsIn, customElement, deepActiveElement, deepContains, formatWords, HelixActivateEvent, HelixBeforeActivateEvent, HelixCompleteEvent, HelixElement, HelixTourStatusEvent, hostAria, inlineStep, keyClaimed, MixinControllerOpen, requestChange, whenHydrated, words, } from '@fusion.dev/helix-core';
+import { auditName, controlsIn, customElement, deepActiveElement, deepContains, formatWords, HelixActivateEvent, HelixBeforeActivateEvent, HelixCompleteEvent, HelixElement, HelixTourStatusEvent, hostAria, inlineStep, keyClaimed, MixinControllerOpen, requestChange, whenHydrated, words, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property, queryAssignedElements, state } from 'lit/decorators.js';
 import { stopBefore } from '../back.js';
@@ -151,11 +151,23 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
     }
     updated(changed) {
         super.updated(changed);
+        this.reveal();
         this.settle();
         this.light();
+        if (changed.has('open') && this.open) {
+            auditName(this, () => null, 'Give it a `label`, such as "Getting started".', () => this.label !== '');
+        }
         this.follow(changed);
         this.wait();
     }
+    reveal() {
+        const target = this.lit ?? undefined;
+        if (target === this.revealed) {
+            return;
+        }
+        this.revealed = target;
+        target?.scrollIntoView?.({ block: 'nearest', inline: 'nearest' });
+    }
     follow(changed) {
         if (!this.followed) {
             this.followed = true;

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

@@ -37,7 +37,8 @@ import '../../button/index.js';
  * The panel is a `group`, and a `dialog` for a dialog stop, only while the
  * stop is shown. It is named by the `heading` slot, then by the first heading
  * in the content, then by `label`, and otherwise by its place in the tour. It
- * is described by the `description` slot and by its place, such as "2 of 5",
+ * is described by the `description` slot, or where that is empty by the words
+ * at the start of the content, and by its place, such as "2 of 5",
  * so a screen reader says where the reader is at every stop. `focus()` moves
  * focus to the panel, which is what the tour does when it opens or moves on.
  *

package/dist/tour/stop/tour-stop.js

@@ -68,6 +68,9 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
             description: slotted('description'),
             heading: slotted('heading'),
             labeled: this.label !== '',
+            loose: [...this.childNodes].some((one) => one.nodeType === Node.TEXT_NODE && (one.textContent ?? '').trim() !== '')
+                ? this.partNamed('content')
+                : null,
             progress: this.position === '' ? null : this.partNamed('progress'),
         });
         reflectElements(bubble, 'ariaLabelledByElements', labelledBy, true);
@@ -127,7 +130,7 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
       ></div>
       <slot name="heading" part="heading" @slotchange=${this.nameByHeading}></slot>
       <slot name="description" part="description" @slotchange=${this.nameByHeading}></slot>
-      <div part="content"><slot></slot></div>
+      <div part="content"><slot @slotchange=${this.nameByHeading}></slot></div>
       ${this.position === ''
             ? ''
             : html `<span part="progress" ?hidden=${!this.progress}>${this.position}</span>`}

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

@@ -36,6 +36,9 @@ declare const HelixHeadlessTree_base: (new (...args: any[]) => import("@fusion.d
  * tree of check marks, Control+A (Command+A on an Apple keyboard) checks every
  * item or clears them all, and Shift with Up or Down Arrow moves and checks.
  *
+ * Removing the item that has focus moves focus to the item after it among its
+ * siblings, or the one before, or its parent, so focus stays in the tree.
+ *
  * **`reorderable` lets you move items among their siblings.** Alt with Up or
  * Down moves the focused item a place, and Alt with Home or End to the first
  * or the last place among its siblings, as the APG's rearrangeable listbox
@@ -183,6 +186,16 @@ export declare class HelixHeadlessTree extends HelixHeadlessTree_base {
     /** Whether many items can be checked. */
     private get multiple();
     private watcher;
+    /** The item that last had focus, so its removal can hand focus on. */
+    private focused;
+    private readonly handleFocusIn;
+    /**
+     * Puts focus back in the tree where the item that had it was removed and
+     * focus fell to the page: on the item after it among its siblings, or the
+     * one before, or its parent. Read from the removal itself, which knows where
+     * the item stood.
+     */
+    private refocus;
     /**
      * Every item, in the order a reader moving down would meet them.
      *

package/dist/tree/root/tree-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 { AriaForwardController, closestInstance, commaList, customElement, HelixElement, inlineStep, keyClaimed, MixinCollection, MixinControllerActive, ReorderController, scrollItemIntoView, selectsAll, slottedWords, Typeahead, treeArrow, typesCharacter, whenHydrated, words, } from '@fusion.dev/helix-core';
+import { AriaForwardController, closestInstance, commaList, customElement, deepActiveElement, HelixElement, inlineStep, keyClaimed, MixinCollection, MixinControllerActive, ReorderController, scrollItemIntoView, selectsAll, slottedWords, Typeahead, treeArrow, typesCharacter, whenHydrated, words, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { fromGrip } from '../grip.js';
@@ -52,6 +52,11 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
         });
         this.pickedUpLabel = 'Picked up {name}';
         this.reorderable = false;
+        this.handleFocusIn = (event) => {
+            this.focused = event
+                .composedPath()
+                .find((node) => node instanceof HelixHeadlessTreeItem);
+        };
         this.handleSelection = (event) => {
             const origin = event.target;
             if (!(origin instanceof HelixHeadlessTreeItem) || !this.items.includes(origin)) {
@@ -162,6 +167,36 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
     get multiple() {
         return this.selectionMode === 'multiple';
     }
+    refocus(records) {
+        const gone = this.focused;
+        if (!gone || this.items.includes(gone)) {
+            return;
+        }
+        this.focused = undefined;
+        const active = deepActiveElement();
+        if (active !== null && active !== document.body) {
+            return;
+        }
+        const record = records.find((one) => [...one.removedNodes].some((node) => node === gone || node.contains(gone)));
+        const near = (from, forward) => {
+            let node = from ?? null;
+            while (node) {
+                if (node instanceof HelixHeadlessTreeItem && !node.disabled && node.isConnected) {
+                    return node;
+                }
+                node = forward ? node.nextSibling : node.previousSibling;
+            }
+            return undefined;
+        };
+        const parent = record ? closestInstance(record.target, HelixHeadlessTreeItem) : null;
+        const next = near(record?.nextSibling, true) ??
+            near(record?.previousSibling, false) ??
+            (parent instanceof HelixHeadlessTreeItem && this.items.includes(parent)
+                ? parent
+                : undefined) ??
+            this.visibleItems.find((item) => !item.disabled);
+        this.focusOn(next);
+    }
     get items() {
         return [...this.querySelectorAll('*')].filter((node) => node instanceof HelixHeadlessTreeItem);
     }
@@ -305,7 +340,11 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
         this.addEventListener('helix-select', this.handleSelection);
         this.addEventListener('toggle', this.handleBranch, true);
         this.addEventListener('keydown', this.handleKeydown);
-        this.watcher = new MutationObserver(() => this.syncItems());
+        this.addEventListener('focusin', this.handleFocusIn);
+        this.watcher = new MutationObserver((records) => {
+            this.syncItems();
+            this.refocus(records);
+        });
         this.watcher.observe(this, { childList: true, subtree: true });
     }
     disconnectedCallback() {
@@ -313,6 +352,7 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
         this.removeEventListener('helix-select', this.handleSelection);
         this.removeEventListener('toggle', this.handleBranch, true);
         this.removeEventListener('keydown', this.handleKeydown);
+        this.removeEventListener('focusin', this.handleFocusIn);
         this.watcher?.disconnect();
         this.watcher = undefined;
     }

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

@@ -316,6 +316,12 @@ export declare class HelixHeadlessVideo extends HelixElement {
      * Whether the video starts again at the end.
      */
     loop: boolean;
+    /**
+     * The title the device's own media controls show while the video plays,
+     * such as on a lock screen. Empty, the default, shows `label`. A playlist
+     * writes the current entry's name here.
+     */
+    mediaTitle: string;
     /**
      * What the button that opens `overflow-controls` is called.
      */

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

@@ -47,6 +47,7 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
         this.label = '';
         this.loadingLabel = 'Loading';
         this.loop = false;
+        this.mediaTitle = '';
         this.moreLabel = 'More controls';
         this.muteLabel = 'Mute';
         this.nextLabel = 'Next';
@@ -351,7 +352,7 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
     }
     claimSession() {
         const skips = writtenList(`${this.extraControls} ${this.overflowControls}`);
-        this.session.claim({ artwork: this.poster, title: this.label }, {
+        this.session.claim({ artwork: this.poster, title: this.mediaTitle || this.label }, {
             next: skips.includes('next') ? () => this.skip(false) : null,
             previous: skips.includes('previous') ? () => this.skip(true) : null,
             seek: (seconds) => this.seek(seconds),
@@ -954,6 +955,9 @@ __decorate([
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessVideo.prototype, "loop", void 0);
+__decorate([
+    property({ attribute: 'media-title' })
+], HelixHeadlessVideo.prototype, "mediaTitle", void 0);
 __decorate([
     words,
     property({ attribute: 'more-label' })

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

@@ -30,6 +30,10 @@ declare const HelixHeadlessVideoPlaylist_base: (new (...args: any[]) => import("
  * sends `helix-end`. `shuffle` plays the entries in a random order, starting
  * from the one that is current, and `previous` retraces that order.
  *
+ * **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.
+ *
  * **Keyboard.** Each entry is a button in the tab order, and Enter or Space
  * plays it. The current entry carries `aria-current`. While focus is on the
  * player, the player's own keys work, and `Video` lists them. Its previous

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

@@ -125,7 +125,10 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
         if (player.src !== current.src) {
             player.src = current.src;
             player.poster = current.poster;
-            player.label = current.text;
+            player.mediaTitle = current.text;
+            if (!player.hasAttribute('label')) {
+                player.label = current.text;
+            }
             if (this.chased) {
                 void player.updateComplete?.then(() => player.play()).catch(() => { });
             }

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

@@ -91,6 +91,12 @@ export interface VirtualListRange {
  * the last item says "Loading more" (`loading-label`, or your own content in
  * the `loading` slot). `scrollToIndex` takes a reader to an item.
  *
+ * **An empty list.** Set `empty-label`, or put your own content in the `empty`
+ * slot, for a row shown when there are no items and none are loading, such as
+ * "No messages yet" and a link to write one. Without either, an empty list
+ * shows nothing, since a list whose items have not arrived yet has not said
+ * it has none.
+ *
  * **Row height.** Rows are placed by `estimate` until they are drawn. Then the
  * list reads the drawn rows' height once and places every row by it, so a
  * wrong estimate still reaches the last item. Set `measured` for rows of
@@ -112,6 +118,7 @@ export interface VirtualListRange {
  * @documentation https://fusion.dev/helix/components/virtual-list
  *
  * @slot - The `<template>` that defines one row. The list writes the rows it renders beside it, and this slot shows them between the two spacers.
+ * @slot empty - Content for the row shown when there are no items and none are loading. Falls back to `empty-label`.
  * @slot loading - Content for the row after the last item while `loading` is set. Falls back to `loading-label`.
  *
  * @event {Event} change - Fired once a press or a key has changed which items are selected, in a list with `selection-mode`.
@@ -121,6 +128,7 @@ export interface VirtualListRange {
  *
  * @csspart after - The space that stands in for the rows below the rendered ones.
  * @csspart before - The space that stands in for the rows above the rendered ones.
+ * @csspart empty - The row shown when there are no items and none are loading, where `empty-label` or the `empty` slot gives it content.
  * @csspart loading - The row after the last item while `loading` is set.
  * @csspart viewport - The scrolling box. On this tier, it needs only a block size.
  */
@@ -136,6 +144,11 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * time, with Left and Right moving along a line.
      */
     columns: number;
+    /**
+     * The text of the row shown when there are no items and none are loading,
+     * where the `empty` slot is empty. Empty, the default, shows no row.
+     */
+    emptyLabel: string;
     /**
      * The height of one row, in pixels, used to find the row at a scroll offset.
      *
@@ -376,7 +389,16 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * first when it is not drawn.
      */
     private focusIndex;
-    /** The row kept for focus is let go once focus has left it. */
+    /**
+     * The row kept for focus is let go once focus has left it.
+     *
+     * **A task later, and not at once.** Between `focusout` and `focusin` the
+     * page's focus is on `<body>`, and Chromium runs microtasks there when a key
+     * moves focus. An update asked for here ran in that gap: Tab from a kept row
+     * to its own link found no row holding focus, removed the row, and the link
+     * went with it, leaving focus on `<body>`. A move to a control inside this
+     * list asks for its own update in `handleFocusIn`, so it needs nothing here.
+     */
     private readonly handleFocusOut;
     /** A row that takes focus, by a press or by Tab, takes the tab stop with it. */
     private readonly handleFocusIn;

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

@@ -15,6 +15,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
     constructor() {
         super(...arguments);
         this.columns = 1;
+        this.emptyLabel = '';
         this.estimate = 32;
         this.for = '';
         this.keyField = '';
@@ -103,8 +104,14 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             }
             this.press(at, event.shiftKey && this.selectionMode === 'multiple');
         };
-        this.handleFocusOut = () => {
-            this.requestUpdate();
+        this.handleFocusOut = (event) => {
+            const next = event.relatedTarget;
+            if (next instanceof Node && this.contains(next)) {
+                return;
+            }
+            setTimeout(() => {
+                this.requestUpdate();
+            }, 0);
         };
         this.handleFocusIn = (event) => {
             let node = event.target;
@@ -433,6 +440,10 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         const kept = this.hasUpdated ? this.keptIndex() : undefined;
         const { after, before } = this.virtualize.spacers(kept === undefined ? undefined : Math.floor(kept / this.across));
         const across = this.across;
+        const empty = this.readFor !== undefined &&
+            !this.loading &&
+            this.data.length === 0 &&
+            (this.emptyLabel !== '' || this.querySelector(':scope > [slot="empty"]') !== null);
         return html `<div
       data-scroller
       part="viewport"
@@ -457,12 +468,20 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
               <slot name="loading">${this.loadingLabel}</slot>
             </div>`
             : nothing}
+      ${empty
+            ? html `<div part="empty" role=${this.selectionMode ? 'option' : 'listitem'}>
+              <slot name="empty">${this.emptyLabel}</slot>
+            </div>`
+            : nothing}
     </div>`;
     }
 };
 __decorate([
     property({ type: Number })
 ], HelixHeadlessVirtualList.prototype, "columns", void 0);
+__decorate([
+    property({ attribute: 'empty-label' })
+], HelixHeadlessVirtualList.prototype, "emptyLabel", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessVirtualList.prototype, "estimate", void 0);