@fusion.dev/helix-headless 0.154.0 → 0.156.0

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

@@ -1,5 +1,5 @@
 import { HelixElement } from '@fusion.dev/helix-core';
-import { type TemplateResult } from 'lit';
+import { type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary One entry in a video playlist.
  *
@@ -34,6 +34,8 @@ import { type TemplateResult } from 'lit';
  * @csspart label - The name and the content after it.
  * @csspart media - The column at the start of the row.
  * @csspart thumbnail - The image of `poster`, shown when the `media` slot is empty.
+ *
+ * @cssstate current - The entry that is playing.
  */
 export declare class HelixHeadlessVideoPlaylistItem extends HelixElement {
     /**
@@ -78,6 +80,11 @@ export declare class HelixHeadlessVideoPlaylistItem extends HelixElement {
      * where there is no slot to ask. `Option.text` reads its own the same way.
      */
     get text(): string;
+    /**
+     * Focuses the entry's button, which is where the playlist's arrow keys send
+     * focus. The host itself takes no focus.
+     */
+    focus(options?: FocusOptions): void;
     private readonly choose;
     /**
      * What stands for the row: a thumbnail where there is one, and nothing where
@@ -88,6 +95,13 @@ export declare class HelixHeadlessVideoPlaylistItem extends HelixElement {
      * slots `media` for the same reasons and neither has to know about the other.
      */
     protected renderMedia(): TemplateResult;
+    /**
+     * Mirrors the playing entry where a stylesheet can select on the host,
+     * `helix-video-playlist-item:state(current)`. A custom state, because the
+     * playlist writes `current`, and an attribute it wrote would be markup a
+     * server never sent.
+     */
+    protected willUpdate(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }
 declare global {

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

@@ -29,11 +29,18 @@ let HelixHeadlessVideoPlaylistItem = class HelixHeadlessVideoPlaylistItem extend
             .join('')
             .trim();
     }
+    focus(options) {
+        this.renderRoot?.querySelector('button')?.focus(options);
+    }
     renderMedia() {
         return html `<slot name="media">
       ${this.poster === '' ? nothing : html `<img part="thumbnail" alt="" src=${this.poster} />`}
     </slot>`;
     }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        this.toggleState('current', this.current);
+    }
     render() {
         return html `<div part="container" role="listitem">
       <button

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

@@ -35,10 +35,17 @@ declare const HelixHeadlessVideoPlaylist_base: (new (...args: any[]) => import("
  * 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
- * and next controls move through the entries in the same order the playlist
- * does.
+ * plays it. The arrow keys move focus to the entry before or after, and Home
+ * and End to the first and the last, passing over disabled entries. The
+ * current entry carries `aria-current`. While focus is on the player, the
+ * player's own keys work, and `Video` lists them, and Shift with N or P plays
+ * the next or the previous entry. The player's previous and next controls
+ * move through the entries in the same order the playlist does.
+ *
+ * **What a screen reader hears.** A list named by `label`, with a button for
+ * each entry. When the playlist moves to another entry, by a press, by the
+ * player's controls, or at the end of a clip, a live region says
+ * `playing-label`, "Now playing" and the entry's name.
  *
  * @since 0.1.0
  * @status stable
@@ -54,7 +61,10 @@ declare const HelixHeadlessVideoPlaylist_base: (new (...args: any[]) => import("
  * @event {HelixEndEvent} helix-end - The last entry finished playing, and the playlist stopped there. Not sent while `repeat` is set.
  *
  * @csspart items - The list of entries.
+ * @csspart live - A live region that says which entry plays after the playlist moves.
  * @csspart player - The region that holds the player.
+ *
+ * @cssstate ended - The last entry finished and the playlist stopped there, until an entry plays again.
  */
 export declare class HelixHeadlessVideoPlaylist extends HelixHeadlessVideoPlaylist_base {
     /**
@@ -66,6 +76,17 @@ export declare class HelixHeadlessVideoPlaylist extends HelixHeadlessVideoPlayli
      * The list's name, read by screen readers.
      */
     label: string;
+    /**
+     * What the live region says when the playlist moves to another entry.
+     * `{title}` is the entry's name.
+     *
+     * **A move a reader did not make is said.** At the end of a clip the
+     * playlist starts the next one, and the only other trace of that is the
+     * `aria-current` on a button the reader is not on.
+     */
+    playingLabel: string;
+    /** The live region, rendered from the first move. */
+    private readonly status;
     /**
      * What happens when an entry ends with no next one to go to. `one` plays the
      * same entry again, and `all` goes from the last entry back to the first.
@@ -168,6 +189,24 @@ export declare class HelixHeadlessVideoPlaylist extends HelixHeadlessVideoPlayli
      */
     previous(): void;
     private readonly handleSelect;
+    /**
+     * The arrow keys, Home and End on an entry move focus to another one.
+     *
+     * **The entries the keys reach are the enabled ones**, because a disabled
+     * button cannot take focus and a key that landed on one would leave focus
+     * where it was. Up and Left go back, Down and Right go on, and Left and
+     * Right swap on a right-to-left page, so a list laid out in a row moves the
+     * way it reads.
+     */
+    private readonly handleKeydown;
+    /** The player playing again, after the end or anywhere, means the list has not ended. */
+    private readonly handlePlay;
+    /**
+     * Shift with N plays the next entry and Shift with P the previous one, while
+     * focus is on the player, the keys a reader knows from the common players.
+     * Not inside a field the player holds, where they are letters.
+     */
+    private takePlayerKey;
     private readonly handleNext;
     private readonly handlePrevious;
     /**

package/dist/video-playlist/root/video-playlist-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, HelixElement, HelixEndEvent, MixinControllerActive, words, } from '@fusion.dev/helix-core';
+import { customElement, drawStatus, formatWords, HelixElement, HelixEndEvent, inlineStep, MixinControllerActive, StatusController, words, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 import { HelixHeadlessVideoPlaylistItem } from '../item/video-playlist-item.js';
@@ -13,6 +13,8 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
     constructor() {
         super(...arguments);
         this.label = 'Playlist';
+        this.playingLabel = 'Now playing {title}';
+        this.status = new StatusController(this);
         this.shuffle = false;
         this.chased = false;
         this.handleSelect = (event) => {
@@ -23,6 +25,39 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
             this.chased = true;
             this.requestActive(event.detail.value);
         };
+        this.handleKeydown = (event) => {
+            const from = event.target;
+            if (this.takePlayerKey(event)) {
+                return;
+            }
+            if (!(from instanceof HelixHeadlessVideoPlaylistItem) ||
+                event.altKey ||
+                event.ctrlKey ||
+                event.metaKey ||
+                event.shiftKey) {
+                return;
+            }
+            const reachable = this.items.filter((one) => !one.disabled);
+            const at = reachable.indexOf(from);
+            const step = event.key === 'ArrowDown' ? 1 : event.key === 'ArrowUp' ? -1 : inlineStep(this, event.key);
+            const to = event.key === 'Home'
+                ? 0
+                : event.key === 'End'
+                    ? reachable.length - 1
+                    : step !== 0 && at !== -1
+                        ? Math.min(Math.max(at + step, 0), reachable.length - 1)
+                        : undefined;
+            if (to === undefined) {
+                return;
+            }
+            event.preventDefault();
+            reachable[to]?.focus();
+        };
+        this.handlePlay = (event) => {
+            if (event.target === this.player) {
+                this.toggleState('ended', false);
+            }
+        };
         this.handleNext = () => {
             this.next();
         };
@@ -38,6 +73,7 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
                 return;
             }
             if (this.following(1).next === undefined) {
+                this.toggleState('ended', true);
                 this.dispatchEvent(new HelixEndEvent());
                 return;
             }
@@ -91,19 +127,43 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
     previous() {
         this.step(-1);
     }
+    takePlayerKey(event) {
+        const player = this.player;
+        if (!player ||
+            event.target !== player ||
+            event.defaultPrevented ||
+            !event.shiftKey ||
+            event.altKey ||
+            event.ctrlKey ||
+            event.metaKey ||
+            (event.key !== 'N' && event.key !== 'P')) {
+            return false;
+        }
+        const origin = event.composedPath()[0];
+        if (origin?.tagName === 'INPUT' || origin?.isContentEditable) {
+            return false;
+        }
+        event.preventDefault();
+        this.step(event.key === 'N' ? 1 : -1);
+        return true;
+    }
     connectedCallback() {
         super.connectedCallback();
         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);
     }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener('helix-select', this.handleSelect);
+        this.removeEventListener('keydown', this.handleKeydown);
         this.removeEventListener('helix-next', this.handleNext);
         this.removeEventListener('helix-previous', this.handlePrevious);
         this.removeEventListener('ended', this.handleEnded, true);
+        this.removeEventListener('play', this.handlePlay, true);
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -123,6 +183,7 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
             return;
         }
         if (player.src !== current.src) {
+            this.toggleState('ended', false);
             player.src = current.src;
             player.poster = current.poster;
             player.mediaTitle = current.text;
@@ -130,6 +191,7 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
                 player.label = current.text;
             }
             if (this.chased) {
+                this.status.say(formatWords(this, 'playingLabel', { title: current.text }));
                 void player.updateComplete?.then(() => player.play()).catch(() => { });
             }
         }
@@ -139,13 +201,18 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
         return html `<div part="player"><slot name="player"></slot></div>
       <div part="items" role="list" aria-label=${this.label}>
         <slot></slot>
-      </div>`;
+      </div>
+      ${drawStatus(this.status)}`;
     }
 };
 __decorate([
     words,
     property()
 ], HelixHeadlessVideoPlaylist.prototype, "label", void 0);
+__decorate([
+    words,
+    property({ attribute: 'playing-label' })
+], HelixHeadlessVideoPlaylist.prototype, "playingLabel", void 0);
 __decorate([
     property()
 ], HelixHeadlessVideoPlaylist.prototype, "repeat", void 0);

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

@@ -97,6 +97,11 @@ export interface VirtualListRange {
  * shows nothing, since a list whose items have not arrived yet has not said
  * it has none.
  *
+ * The list takes the `empty` state while it has read its items and holds none,
+ * and the `loading` state while `loading` is set, so your stylesheet can
+ * change the box around it for either. A list with no name is reported once
+ * in a development build. Name it with `label` or `aria-label`.
+ *
  * **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
@@ -131,6 +136,9 @@ export interface VirtualListRange {
  * @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.
+ *
+ * @cssstate empty - While the list has read its items and holds none.
+ * @cssstate loading - While `loading` is set.
  */
 export declare class HelixHeadlessVirtualList extends HelixElement {
     /**

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

@@ -33,6 +33,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         this.aria = new AriaForwardController(this, {
             label: true,
             target: () => this.partNamed('viewport'),
+            unnamed: 'Give it a `label`, or an `aria-label` that says what the items are.',
         });
         this.virtualize = new VirtualizeController(this, {
             container: () => this.partNamed('viewport'),
@@ -210,6 +211,8 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
     }
     updated(changed) {
         super.updated?.(changed);
+        this.toggleState('empty', this.readFor !== undefined && this.data.length === 0);
+        this.toggleState('loading', this.loading);
         this.virtualize.measure();
         this.place();
         this.virtualize.settle();