@fusion.dev/helix-headless 0.160.0 → 0.161.0

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

@@ -5,25 +5,58 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { customElement, drawStatus, formatWords, HelixElement, HelixEndEvent, inlineStep, MixinControllerActive, StatusController, words, } from '@fusion.dev/helix-core';
-import { html } from 'lit';
+import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { HelixHeadlessVideoPlaylistItem } from '../item/video-playlist-item.js';
 import { playOrder, stepTo } from '../order.js';
 let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinControllerActive(HelixElement) {
     constructor() {
         super(...arguments);
+        this.emptyLabel = 'No videos';
         this.label = 'Playlist';
+        this.noAdvance = false;
         this.playingLabel = 'Now playing {title}';
         this.status = new StatusController(this);
         this.shuffle = false;
         this.chased = false;
+        this.known = {
+            current: undefined,
+            values: [],
+        };
         this.handleSelect = (event) => {
             event.stopImmediatePropagation();
             if (event.defaultPrevented) {
                 return;
             }
             this.chased = true;
-            this.requestActive(event.detail.value);
+            this.requestActive(event.detail.value, 'press');
+        };
+        this.handleFocusIn = (event) => {
+            const entry = event.target;
+            if (entry instanceof HelixHeadlessVideoPlaylistItem && this.items.includes(entry)) {
+                this.stop = entry.value;
+                this.placeStop(this.items);
+            }
+        };
+        this.handleEntries = () => {
+            const { current, values } = this.known;
+            const items = this.items;
+            const present = new Set(items.filter((one) => !one.disabled).map((one) => one.value));
+            if (current !== undefined && !items.some((one) => one.value === current)) {
+                const at = values.indexOf(current);
+                const next = values.slice(at + 1).find((value) => present.has(value)) ??
+                    values
+                        .slice(0, at)
+                        .reverse()
+                        .find((value) => present.has(value));
+                if (next !== undefined) {
+                    this.chased = this.player?.paused === false;
+                    if (!this.requestActive(next, 'removed')) {
+                        this.chased = false;
+                    }
+                }
+            }
+            this.requestUpdate();
         };
         this.handleKeydown = (event) => {
             const from = event.target;
@@ -77,7 +110,9 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
                 this.dispatchEvent(new HelixEndEvent());
                 return;
             }
-            this.step(1);
+            if (!this.noAdvance) {
+                this.step(1, 'ended');
+            }
         };
     }
     static { this.words = 'helix-video-playlist'; }
@@ -96,7 +131,7 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
         const order = this.dealt ?? values;
         return { current, next: stepTo(order, current, by, this.repeat === 'all') };
     }
-    step(by) {
+    step(by, cause) {
         const { current, next } = this.following(by);
         if (next === undefined) {
             return;
@@ -106,7 +141,7 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
             return;
         }
         this.chased = true;
-        if (!this.requestActive(next)) {
+        if (!this.requestActive(next, cause)) {
             this.chased = false;
         }
     }
@@ -122,10 +157,19 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
         return this.resolveActive(this.items);
     }
     next() {
-        this.step(1);
+        this.step(1, 'next');
     }
     previous() {
-        this.step(-1);
+        this.step(-1, 'previous');
+    }
+    placeStop(items) {
+        const enabled = items.filter((one) => !one.disabled);
+        const holder = enabled.find((one) => one.value === this.stop) ??
+            enabled.find((one) => one.current) ??
+            enabled[0];
+        for (const item of items) {
+            item.focusable = item === holder;
+        }
     }
     takePlayerKey(event) {
         const player = this.player;
@@ -144,20 +188,27 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
             return false;
         }
         event.preventDefault();
-        this.step(event.key === 'N' ? 1 : -1);
+        this.step(event.key === 'N' ? 1 : -1, event.key === 'N' ? 'next' : 'previous');
         return true;
     }
     connectedCallback() {
         super.connectedCallback();
+        this.addEventListener('focusin', this.handleFocusIn);
         this.addEventListener('helix-select', this.handleSelect);
         this.addEventListener('keydown', this.handleKeydown);
         this.addEventListener('helix-next', this.handleNext);
         this.addEventListener('helix-previous', this.handlePrevious);
         this.addEventListener('ended', this.handleEnded, true);
         this.addEventListener('play', this.handlePlay, true);
+        if (typeof MutationObserver !== 'undefined') {
+            this.watcher ??= new MutationObserver(this.handleEntries);
+            this.watcher.observe(this, { childList: true, subtree: true });
+        }
     }
     disconnectedCallback() {
         super.disconnectedCallback();
+        this.watcher?.disconnect();
+        this.removeEventListener('focusin', this.handleFocusIn);
         this.removeEventListener('helix-select', this.handleSelect);
         this.removeEventListener('keydown', this.handleKeydown);
         this.removeEventListener('helix-next', this.handleNext);
@@ -165,6 +216,10 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
         this.removeEventListener('ended', this.handleEnded, true);
         this.removeEventListener('play', this.handlePlay, true);
     }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.finishHydration();
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
         if (changed.has('shuffle') && !this.shuffle) {
@@ -178,13 +233,21 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
         for (const item of items) {
             item.current = item === current;
         }
+        this.known = { current: current?.value, values: items.map((one) => one.value) };
+        this.placeStop(items);
         const player = this.player;
         if (!player || !current) {
             return;
         }
-        if (player.src !== current.src) {
+        if (player.src !== current.src || current !== this.pointed) {
+            this.pointed = current;
             this.toggleState('ended', false);
-            player.src = current.src;
+            if (player.src !== current.src) {
+                player.src = current.src;
+            }
+            else if (this.chased) {
+                player.currentTime = 0;
+            }
             player.poster = current.poster;
             player.mediaTitle = current.text;
             if (!player.hasAttribute('label')) {
@@ -198,17 +261,26 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
         this.chased = false;
     }
     render() {
+        const empty = this.childrenKnown && this.items.length === 0;
         return html `<div part="player"><slot name="player"></slot></div>
       <div part="items" role="list" aria-label=${this.label}>
         <slot></slot>
       </div>
+      ${empty ? html `<div part="empty"><slot name="empty">${this.emptyLabel}</slot></div>` : nothing}
       ${drawStatus(this.status)}`;
     }
 };
+__decorate([
+    words,
+    property({ attribute: 'empty-label' })
+], HelixHeadlessVideoPlaylist.prototype, "emptyLabel", void 0);
 __decorate([
     words,
     property()
 ], HelixHeadlessVideoPlaylist.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'no-advance', type: Boolean })
+], HelixHeadlessVideoPlaylist.prototype, "noAdvance", void 0);
 __decorate([
     words,
     property({ attribute: 'playing-label' })

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

@@ -18,7 +18,12 @@
  * does not read "undefined".
  */
 export declare const textOf: (value: unknown) => string;
-/** Fills one element's holes, its own and those below it, from an item. */
+/**
+ * Fills one element's holes, its own and those below it, from an item.
+ *
+ * The element itself whatever hole it carries, so a row whose root is a link
+ * takes its `data-field-href` as readily as its text.
+ */
 export declare const fillHoles: (root: Element, item: unknown) => void;
 /**
  * The key of item `at` in a selecting list's `value`: its `keyField` where it

package/dist/virtual-list/fill.js

@@ -9,7 +9,7 @@ const writeAttribute = (element, name, value) => {
     element.setAttribute(name, value === true ? '' : textOf(value));
 };
 export const fillHoles = (root, item) => {
-    const holes = [...(root.matches('[data-field]') ? [root] : []), ...root.querySelectorAll('*')];
+    const holes = [root, ...root.querySelectorAll('*')];
     for (const hole of holes) {
         for (const { name, value } of [...hole.attributes]) {
             if (name === 'data-field') {

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

@@ -22,3 +22,11 @@ export declare const stepIndex: (key: string, at: number, count: number, page: n
     across?: number;
     forward?: string;
 }) => number | undefined;
+/**
+ * Where a key lands once disabled items are passed over: from `to`, which
+ * `stepIndex` gave, on in the way the key moves until an item that is not
+ * disabled. A line move steps a line at a time, in the same column. Home looks
+ * forward from the first item and End back from the last. `undefined` where
+ * every item that way is disabled, and the key moves nothing.
+ */
+export declare const skipDisabled: (key: string, from: number, to: number, count: number, disabled: (index: number) => boolean, across?: number) => number | undefined;

package/dist/virtual-list/keys.js

@@ -33,3 +33,23 @@ export const stepIndex = (key, at, count, page, { across = 1, forward = 'ArrowRi
             return undefined;
     }
 };
+export const skipDisabled = (key, from, to, count, disabled, across = 1) => {
+    if (!disabled(to)) {
+        return to;
+    }
+    const width = Math.max(1, Math.trunc(across));
+    const line = key === 'ArrowDown' || key === 'ArrowUp' || key === 'PageDown' || key === 'PageUp';
+    const way = key === 'Home' ? 1 : key === 'End' ? -1 : to >= from ? 1 : -1;
+    const step = (line ? width : 1) * way;
+    for (let at = to + step; at >= 0 && at < count; at += step) {
+        if (!disabled(at)) {
+            return at;
+        }
+    }
+    for (let at = to + way; at >= 0 && at < count; at += way) {
+        if (!disabled(at)) {
+            return at === from ? undefined : at;
+        }
+    }
+    return undefined;
+};

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

@@ -4,9 +4,10 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * Draws one item into its row, for a list given `renderItem`.
  *
  * Returns anything Lit renders: a template from `html`, a string, or a DOM
- * node the function built.
+ * node the function built. `Item` types the item, so a page writes
+ * `const row: VirtualListRenderer<Person> = (person) => person.name`.
  */
-export type VirtualListRenderer = (item: unknown, index: number) => unknown;
+export type VirtualListRenderer<Item = unknown> = (item: Item, index: number) => unknown;
 /** Where `scrollToIndex` puts an item, and how it gets there. */
 export interface VirtualListScrollOptions {
     /**
@@ -49,8 +50,10 @@ export interface VirtualListRange {
  * **A grid.** `columns` lays the items out that many to a line, as a grid of
  * equal columns, and windows the set a line at a time, as React Aria's grid
  * layout does. Each item draws one element, a cell of the grid, and
- * `estimate` is the height of a line. Space the items with padding inside
- * each one, which the list measures with the line.
+ * `estimate` is the height of a line. `min-column-width` lays out as many
+ * columns as fit the box instead, as React Aria's grid layout does with its
+ * smallest item size, and follows the box as it resizes. `gap` spaces the rows, and the columns
+ * of a grid, by a number of pixels the list counts in each row's place.
  *
  * **Keyboard.** The list is one tab stop.
  *
@@ -61,6 +64,7 @@ export interface VirtualListRange {
  * | Home, End | Moves to the first or the last item. |
  * | Page Down, Page Up | Moves by the number of items, or of lines in a grid, on screen. |
  * | A letter or a word | Moves to the next item whose text starts with what you typed. |
+ * | Escape | Lets go of every chosen item, in a list with `selection-mode`. |
  * | Tab | Moves into the focused row's own links and buttons, then out of the list. |
  *
  * An item that is not drawn is scrolled into view and focused, so a keyboard
@@ -77,12 +81,23 @@ export interface VirtualListRange {
  * from: `single` selects one item and `multiple` any number. Space or a press
  * selects an item, Shift with Space, an arrow, Home, End or a press takes in
  * the items from the last one chosen, and Control or Command with A selects
- * them all, in `multiple`. `value` holds the chosen items' keys, separated by
- * commas, in the order of the set: `key-field` names each item's key, and a
- * string or a number item is its own key. A change asks with
- * `helix-before-change` and tells with `change`. Each row is an `option`
- * marked `aria-selected`, so a row's own links and buttons are not reached
- * there: keep those to a list without `selection-mode`.
+ * them all, in `multiple`. Escape lets go of every chosen item, and keeps the
+ * key from the dialog or menu around the list while there was something to
+ * let go of. `value` holds the chosen items' keys, separated by commas, in
+ * the order of the set: `key-field` names each item's key, and a string or a
+ * number item is its own key. A change asks with `helix-before-change` and
+ * tells with `change`. Each row is an `option` marked `aria-selected`, so a
+ * row's own links and buttons are not reached there: keep those to a list
+ * without `selection-mode`.
+ *
+ * `selection-behavior="replace"` selects the item pressed alone, as a file
+ * list does, and the arrow keys carry the selection with them. Control or
+ * Command with a press or with Space adds or takes out one item, and with an
+ * arrow moves without selecting.
+ *
+ * **Disabled items.** `disabled-keys` names items by their keys, separated by
+ * 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.
  *
  * **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
@@ -152,6 +167,11 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * time, with Left and Right moving along a line.
      */
     columns: number;
+    /**
+     * The keys of the items a reader cannot choose or move to, separated by
+     * commas, as `value` writes keys. Their rows carry `aria-disabled`.
+     */
+    disabledKeys: string;
     /**
      * 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.
@@ -169,6 +189,13 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * where both are set.
      */
     for: string;
+    /**
+     * The space between two rows, and between two columns in a grid, in
+     * pixels. The list counts it in each row's place, so a gap does not walk
+     * the rows away from the scroll position the way a margin on each row
+     * would.
+     */
+    gap: number;
     /**
      * The items, as an array. Set it as a property.
      *
@@ -214,6 +241,12 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * one-line rows should leave this alone.
      */
     measured: boolean;
+    /**
+     * The narrowest a column of a grid may be, in pixels. Set, the list lays
+     * out as many columns as fit the box at that width, at least one, and
+     * follows the box as it resizes, which `columns` then does not decide.
+     */
+    minColumnWidth: number;
     /**
      * Draws one item into its row, given the item and its index. Set it as a
      * property.
@@ -222,7 +255,13 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * node. The list wraps each result in a `<div>` that carries the row's role
      * and place in the set. Where it is unset, the row `<template>` is used.
      */
-    renderItem: VirtualListRenderer | undefined;
+    renderItem: VirtualListRenderer<any> | undefined;
+    /**
+     * What a press does to the items already chosen: `toggle` adds or takes out
+     * the item, and `replace` selects it alone and lets the arrow keys carry the
+     * selection, with Control or Command adding or taking out one item.
+     */
+    selectionBehavior: 'replace' | 'toggle';
     /**
      * Makes the list a list box a reader chooses from: `single` selects one
      * item, and `multiple` any number. Unset is a list a reader reads.
@@ -279,6 +318,19 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * script replaced under the same id.
      */
     private watcher;
+    /**
+     * Watches the drawn rows for a change of size after they were drawn: an
+     * image that loads, a row that opens, text a page edits in place.
+     *
+     * **Measured once, a row that grew later kept its old height**, so the
+     * window and the spacers placed every row after it by the old one. React
+     * Aria's virtualizer observes its items for the same reason. A frame later,
+     * so a size the next render changes is not asked of the browser's pass over
+     * the observers a second time.
+     */
+    private sizes;
+    /** The frame the next measure of resized rows waits for. */
+    private resized;
     /** Carries a host `aria-label` and `aria-labelledby` to the element with the `list` role. */
     protected readonly aria: AriaForwardController;
     private readonly virtualize;
@@ -289,8 +341,21 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * box to measure.
      */
     get range(): VirtualListRange;
-    /** How many items a line holds: `columns`, at least one. */
+    /** The gap in pixels, none where it is not a positive number. */
+    private get space();
+    /**
+     * How many items a line holds: as many as fit at `min-column-width` where
+     * it is set and the box has a width, and `columns` otherwise, at least one.
+     */
     private get across();
+    /** How wide the box is, read for `min-column-width`. */
+    private boxWidth;
+    /** Watches the box's width, for `min-column-width`. */
+    private widthWatch;
+    /** The items to a line the measurements were taken at. */
+    private measuredAcross;
+    /** Watches the box for its width while `min-column-width` asks for it. */
+    private watchWidth;
     /** The items a span of lines holds. */
     private itemsOn;
     /**
@@ -335,8 +400,21 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * so by itself.
      */
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Keeps the reader on the item they were reading when items arrive before
+     * it, as a feed loading newer posts above does.
+     *
+     * **Every index moves by what arrived**, so the drawn rows are renumbered,
+     * the tab stop moves with its item, and the controller is told, which moves
+     * the scroll offset by the room the new items take. Recognized where the
+     * new array ends with the old one: the same items, or the same keys under
+     * `key-field`.
+     */
+    private keepPlace;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** Watches a row drawn on this pass for a change of size. */
+    private watchSize;
     /**
      * Reads the source again when its text changed or another element took its
      * id. Rows this list drew are its own writes and are not news.
@@ -359,6 +437,10 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * `data-field`, or a string or number item itself.
      */
     private texts;
+    /** The keys `disabled-keys` names. */
+    private get disabled();
+    /** Whether item `at` is one a reader cannot choose or move to. */
+    private isDisabled;
     /** The item a row element drew, for an element that is one of the rows. */
     private indexOf;
     /** The row that holds the tab stop for item `index`, where it is drawn. */
@@ -423,7 +505,8 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
     private keptIndex;
     /**
      * Writes a row's role, and whether it is chosen in a list that selects:
-     * `option` with `aria-selected` there, and `listitem` otherwise. Every pass,
+     * `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.
      */
     private mark;
@@ -458,6 +541,8 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * buttons are in the tab order, and those of every other row wait.
      */
     private place;
+    /** The spacers' heights: the window's, with the line kept for focus taking its own room. */
+    private spacerSizes;
     protected render(): TemplateResult;
 }
 declare global {