@fusion.dev/helix-headless 0.144.0 → 0.146.0

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

@@ -11,6 +11,7 @@ import { property, state } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
 import '../../menu/index.js';
 import { HelixHeadlessMenu } from '../../menu/root/menu-root.js';
+import { relayMedia } from '../media-events.js';
 import { barControls, menuControls, ownFile } from './extra-controls.js';
 import { takeKey } from './keys.js';
 const clock = (seconds) => {
@@ -53,6 +54,7 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
         this.pauseLabel = 'Pause';
         this.percentLabel = '{percent} percent';
         this.pipLabel = 'Picture in picture';
+        this.playerLabel = 'Video';
         this.playLabel = 'Play';
         this.playsInline = true;
         this.poster = '';
@@ -149,7 +151,6 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
                 this.claimSession();
             }
             this.session.report(this.playing);
-            this.dispatchEvent(new Event(event.type, { bubbles: false, composed: false }));
         };
         this.handleVolume = () => {
             const video = this.video;
@@ -179,6 +180,10 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
             }
             this.toggle();
         };
+        this.handleStart = () => {
+            this.partNamed('stage')?.focus({ preventScroll: true });
+            this.toggle();
+        };
         this.handleKeydown = (event) => {
             if (this.controls) {
                 return;
@@ -296,7 +301,14 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
         return this.partNamed('video');
     }
     play() {
-        void this.video?.play().catch(() => { });
+        const video = this.video;
+        const started = video
+            ? video.play()
+            : this.updateComplete.then(async () => {
+                await this.video?.play();
+            });
+        started.catch(() => { });
+        return started;
     }
     pause() {
         this.video?.pause();
@@ -307,7 +319,7 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
             return;
         }
         if (video.paused) {
-            this.play();
+            void this.play();
         }
         else {
             this.pause();
@@ -419,6 +431,7 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
             this.silent = video.muted;
             this.loudness = video.volume;
             void this.remote.attach(video);
+            relayMedia(video, (event) => this.relayNativeEvent(event));
         }
     }
     updated(changed) {
@@ -438,7 +451,7 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
         aria-pressed=${this.remoteConnected ? 'true' : 'false'}
         @click=${() => void this.remote.prompt()}
       >
-        ${drawIcon(airplay)}
+        <slot name="remote-icon">${drawIcon(airplay)}</slot>
       </button>`;
         }
         if (one === 'rewind') {
@@ -448,7 +461,7 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
         aria-label=${fillTemplate(this.rewindLabel, { seconds: SKIP_SECONDS })}
         @click=${() => this.skipBy(-SKIP_SECONDS)}
       >
-        ${drawIcon(arrowCounterClockwise)}
+        <slot name="rewind-icon">${drawIcon(arrowCounterClockwise)}</slot>
       </button>`;
         }
         if (one === 'forward') {
@@ -458,7 +471,7 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
         aria-label=${fillTemplate(this.forwardLabel, { seconds: SKIP_SECONDS })}
         @click=${() => this.skipBy(SKIP_SECONDS)}
       >
-        ${drawIcon(arrowClockwise)}
+        <slot name="forward-icon">${drawIcon(arrowClockwise)}</slot>
       </button>`;
         }
         if (one === 'speed') {
@@ -478,7 +491,7 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
         aria-label=${this.previousLabel}
         @click=${() => this.skip(true)}
       >
-        ${drawIcon(skipBack)}
+        <slot name="previous-icon">${drawIcon(skipBack)}</slot>
       </button>`;
         }
         if (one === 'next') {
@@ -488,7 +501,7 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
         aria-label=${this.nextLabel}
         @click=${() => this.skip(false)}
       >
-        ${drawIcon(skipForward)}
+        <slot name="next-icon">${drawIcon(skipForward)}</slot>
       </button>`;
         }
         if (one === 'download') {
@@ -501,7 +514,7 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
         rel=${local ? nothing : 'noreferrer'}
         aria-label=${this.downloadLabel}
       >
-        ${drawIcon(download)}
+        <slot name="download-icon">${drawIcon(download)}</slot>
       </a>`;
         }
         return html `<button
@@ -510,7 +523,7 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
       aria-label=${this.pipLabel}
       @click=${() => void this.togglePip()}
     >
-      ${drawIcon(pictureInPicture)}
+      <slot name="pip-icon">${drawIcon(pictureInPicture)}</slot>
     </button>`;
     }
     renderCaptions() {
@@ -526,7 +539,7 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
         aria-pressed=${this.captioned ? 'true' : 'false'}
         @click=${() => this.toggleCaptions()}
       >
-        ${drawIcon(closedCaptioning)}
+        <slot name="captions-icon">${drawIcon(closedCaptioning)}</slot>
       </button>`;
         }
         return html `<${this.tag('menu')} part="captions-menu"
@@ -542,11 +555,13 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
         aria-haspopup="menu"
         aria-expanded=${this.menuOpen === 'captions' ? 'true' : 'false'}
       >
-        ${drawIcon(closedCaptioning)}
+        <slot name="captions-icon">${drawIcon(closedCaptioning)}</slot>
       </button>
       <${this.tag('menu-item')}
         part="entry"
-      exportparts="item: entry-item, mark: entry-mark, start: entry-start"
+      exportparts="end: entry-end, item: entry-item, mark: entry-mark, shortcut: entry-shortcut,
+        shortcut-kbd: entry-shortcut-kbd, shortcut-key: entry-shortcut-key,
+        shortcut-separator: entry-shortcut-separator, start: entry-start"
         value="off"
         checkable
         exclusive
@@ -557,7 +572,9 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
         ${this.captionsOffLabel}
       </${this.tag('menu-item')}>
       ${tracks.map((track, at) => html `<${this.tag('menu-item')} part="entry"
-        exportparts="item: entry-item, mark: entry-mark, start: entry-start"
+        exportparts="end: entry-end, item: entry-item, mark: entry-mark, shortcut: entry-shortcut,
+        shortcut-kbd: entry-shortcut-kbd, shortcut-key: entry-shortcut-key,
+        shortcut-separator: entry-shortcut-separator, start: entry-start"
           value=${track.language || String(at)}
           checkable
           exclusive
@@ -584,63 +601,79 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
     renderOverflowItem(one) {
         if (one === 'remote') {
             return html `<${this.tag('menu-item')} part="entry"
-      exportparts="item: entry-item, mark: entry-mark, start: entry-start"
+      exportparts="end: entry-end, item: entry-item, mark: entry-mark, shortcut: entry-shortcut,
+        shortcut-kbd: entry-shortcut-kbd, shortcut-key: entry-shortcut-key,
+        shortcut-separator: entry-shortcut-separator, start: entry-start"
         value="remote"
         @helix-select=${() => void this.remote.prompt()}
       >
-        ${drawIcon(airplay, { slot: 'start' })}
+        <slot name="remote-icon" slot="start">${drawIcon(airplay)}</slot>
         ${this.remoteLabel}
       </${this.tag('menu-item')}>`;
         }
         if (one === 'speed') {
             return html `<${this.tag('menu-item')} part="entry"
-      exportparts="item: entry-item, mark: entry-mark, start: entry-start" value="speed" @helix-select=${() => this.cycleSpeed()}>
-        ${drawIcon(gauge, { slot: 'start' })}
+      exportparts="end: entry-end, item: entry-item, mark: entry-mark, shortcut: entry-shortcut,
+        shortcut-kbd: entry-shortcut-kbd, shortcut-key: entry-shortcut-key,
+        shortcut-separator: entry-shortcut-separator, start: entry-start" value="speed" @helix-select=${() => this.cycleSpeed()}>
+        <slot name="speed-icon" slot="start">${drawIcon(gauge)}</slot>
         ${this.speedLabel}: ${this.rate}x
       </${this.tag('menu-item')}>`;
         }
         if (one === 'rewind' || one === 'forward') {
             const back = one === 'rewind';
             return html `<${this.tag('menu-item')} part="entry"
-      exportparts="item: entry-item, mark: entry-mark, start: entry-start"
+      exportparts="end: entry-end, item: entry-item, mark: entry-mark, shortcut: entry-shortcut,
+        shortcut-kbd: entry-shortcut-kbd, shortcut-key: entry-shortcut-key,
+        shortcut-separator: entry-shortcut-separator, start: entry-start"
         value=${one}
         @helix-select=${() => this.skipBy(back ? -SKIP_SECONDS : SKIP_SECONDS)}
       >
-        ${drawIcon(back ? arrowCounterClockwise : arrowClockwise, { slot: 'start' })}
+        ${back
+                ? html `<slot name="rewind-icon" slot="start">${drawIcon(arrowCounterClockwise)}</slot>`
+                : html `<slot name="forward-icon" slot="start">${drawIcon(arrowClockwise)}</slot>`}
         ${fillTemplate(back ? this.rewindLabel : this.forwardLabel, { seconds: SKIP_SECONDS })}
       </${this.tag('menu-item')}>`;
         }
         if (one === 'previous') {
             return html `<${this.tag('menu-item')} part="entry"
-      exportparts="item: entry-item, mark: entry-mark, start: entry-start" value="previous" @helix-select=${() => this.skip(true)}>
-        ${drawIcon(skipBack, { slot: 'start' })}
+      exportparts="end: entry-end, item: entry-item, mark: entry-mark, shortcut: entry-shortcut,
+        shortcut-kbd: entry-shortcut-kbd, shortcut-key: entry-shortcut-key,
+        shortcut-separator: entry-shortcut-separator, start: entry-start" value="previous" @helix-select=${() => this.skip(true)}>
+        <slot name="previous-icon" slot="start">${drawIcon(skipBack)}</slot>
         ${this.previousLabel}
       </${this.tag('menu-item')}>`;
         }
         if (one === 'next') {
             return html `<${this.tag('menu-item')} part="entry"
-      exportparts="item: entry-item, mark: entry-mark, start: entry-start" value="next" @helix-select=${() => this.skip(false)}>
-        ${drawIcon(skipForward, { slot: 'start' })}
+      exportparts="end: entry-end, item: entry-item, mark: entry-mark, shortcut: entry-shortcut,
+        shortcut-kbd: entry-shortcut-kbd, shortcut-key: entry-shortcut-key,
+        shortcut-separator: entry-shortcut-separator, start: entry-start" value="next" @helix-select=${() => this.skip(false)}>
+        <slot name="next-icon" slot="start">${drawIcon(skipForward)}</slot>
         ${this.nextLabel}
       </${this.tag('menu-item')}>`;
         }
         if (one === 'download') {
             const local = ownFile(this.src);
             return html `<${this.tag('menu-item')} part="entry"
-      exportparts="item: entry-item, mark: entry-mark, start: entry-start"
+      exportparts="end: entry-end, item: entry-item, mark: entry-mark, shortcut: entry-shortcut,
+        shortcut-kbd: entry-shortcut-kbd, shortcut-key: entry-shortcut-key,
+        shortcut-separator: entry-shortcut-separator, start: entry-start"
         ?download=${local}
         href=${this.src}
         rel=${local ? nothing : 'noreferrer'}
         target=${local ? nothing : '_blank'}
         value="download"
       >
-        ${drawIcon(download, { slot: 'start' })}
+        <slot name="download-icon" slot="start">${drawIcon(download)}</slot>
         ${this.downloadLabel}
       </${this.tag('menu-item')}>`;
         }
         return html `<${this.tag('menu-item')} part="entry"
-    exportparts="item: entry-item, mark: entry-mark, start: entry-start" value="pip" @helix-select=${() => void this.togglePip()}>
-      ${drawIcon(pictureInPicture, { slot: 'start' })}
+    exportparts="end: entry-end, item: entry-item, mark: entry-mark, shortcut: entry-shortcut,
+        shortcut-kbd: entry-shortcut-kbd, shortcut-key: entry-shortcut-key,
+        shortcut-separator: entry-shortcut-separator, start: entry-start" value="pip" @helix-select=${() => void this.togglePip()}>
+      <slot name="pip-icon" slot="start">${drawIcon(pictureInPicture)}</slot>
       ${this.pipLabel}
     </${this.tag('menu-item')}>`;
     }
@@ -653,7 +686,9 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
         aria-label=${this.playing ? this.pauseLabel : this.playLabel}
         @click=${() => this.toggle()}
       >
-        ${drawIcon(this.playing ? pause : play)}
+        ${this.playing
+            ? html `<slot name="pause-icon">${drawIcon(pause)}</slot>`
+            : html `<slot name="play-icon">${drawIcon(play)}</slot>`}
       </button>
       <span part="time">${clock(this.position)} / ${clock(this.knownDuration)}</span>
       <!-- Left to right on every page. A player's timeline is a tape running
@@ -691,7 +726,9 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
             }
         }}
       >
-        ${drawIcon(this.silent || this.loudness === 0 ? speakerX : speakerHigh)}
+        ${this.silent || this.loudness === 0
+            ? html `<slot name="mute-icon">${drawIcon(speakerX)}</slot>`
+            : html `<slot name="volume-icon">${drawIcon(speakerHigh)}</slot>`}
       </button>
       <input
         part="volume"
@@ -725,7 +762,7 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
                 aria-haspopup="menu"
                 aria-expanded=${this.menuOpen === 'overflow' ? 'true' : 'false'}
               >
-                ${drawIcon(dotsThreeVertical)}
+                <slot name="more-icon">${drawIcon(dotsThreeVertical)}</slot>
               </button>
               ${this.overflow.map((one) => this.renderOverflowItem(one))}
             </${this.tag('menu')}>`}
@@ -738,16 +775,35 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
         aria-pressed=${this.full ? 'true' : 'false'}
         @click=${() => void this.fullscreen.toggle()}
       >
-        ${drawIcon(this.full ? cornersIn : cornersOut)}
+        ${this.full
+            ? html `<slot name="exit-fullscreen-icon">${drawIcon(cornersIn)}</slot>`
+            : html `<slot name="fullscreen-icon">${drawIcon(cornersOut)}</slot>`}
       </button>
     </div>`;
     }
+    renderStart() {
+        if (this.controls ||
+            this.playing ||
+            this.buffering ||
+            this.failed ||
+            this.startControl === 'none') {
+            return nothing;
+        }
+        return html `<button
+      part="start"
+      type="button"
+      tabindex="-1"
+      aria-hidden="true"
+      aria-label=${this.playLabel}
+      @click=${this.handleStart}
+    ><slot name="start-icon">${drawIcon(play)}</slot></button>`;
+    }
     render() {
         return html `<div
         part="stage"
         tabindex=${this.controls ? nothing : '0'}
         role=${this.controls ? nothing : 'group'}
-        aria-label=${this.controls ? nothing : this.label || 'Video'}
+        aria-label=${this.controls ? nothing : this.label || this.playerLabel}
         @keydown=${this.handleKeydown}
         @pointermove=${this.idler.stir}
         @pointerleave=${this.idler.leave}
@@ -820,20 +876,7 @@ let HelixHeadlessVideo = class HelixHeadlessVideo extends HelixElement {
               ${this.errorLabel}
             </div>`
             : nothing}
-      ${this.controls ||
-            this.playing ||
-            this.buffering ||
-            this.failed ||
-            this.startControl === 'none'
-            ? nothing
-            : html `<button
-              part="start"
-              type="button"
-              aria-label=${this.playLabel}
-              @click=${() => this.toggle()}
-            >
-              ${drawIcon(play)}
-            </button>`}
+      ${this.renderStart()}
       ${this.controls ? nothing : this.renderBar()}
     </div>`;
     }
@@ -910,6 +953,9 @@ __decorate([
 __decorate([
     property({ attribute: 'pip-label' })
 ], HelixHeadlessVideo.prototype, "pipLabel", void 0);
+__decorate([
+    property({ attribute: 'player-label' })
+], HelixHeadlessVideo.prototype, "playerLabel", void 0);
 __decorate([
     property({ attribute: 'play-label' })
 ], HelixHeadlessVideo.prototype, "playLabel", void 0);

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

@@ -22,8 +22,13 @@ import '../../menu/index.js';
  * @event {HelixSelectEvent} helix-select - An entry was chosen. The event carries its value, and the playlist listens for it. Cancelable: cancel it to keep the current entry.
  *
  * @csspart entry - One entry in the menu.
+ * @csspart entry-end - The column at the end of an entry, which holds its shortcut. It is always present.
  * @csspart entry-item - The entry's row. It is an `<a>` when `href` is set.
  * @csspart entry-mark - The mark at the end of an entry: a check mark when it is checked, or a caret when it opens a submenu.
+ * @csspart entry-shortcut - The key drawn for an entry's shortcut. The playlist's entries set none.
+ * @csspart entry-shortcut-kbd - The key inside `entry-shortcut`.
+ * @csspart entry-shortcut-key - One key of an entry's shortcut chord, inside `entry-shortcut`. The playlist's entries set none.
+ * @csspart entry-shortcut-separator - The `+` between two keys of an entry's shortcut, where the platform writes one.
  * @csspart entry-start - The column at the start of an entry. It is a slot and is always present.
  * @csspart menu - The menu that holds the entries.
  * @csspart menu-back - The button that goes back from a submenu.

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

@@ -85,7 +85,9 @@ let HelixHeadlessVideoPlaylistMenu = class HelixHeadlessVideoPlaylistMenu extend
       </slot>
       ${this.entries.map((entry) => html `<${this.tag('menu-item')}
           part="entry"
-      exportparts="item: entry-item, mark: entry-mark, start: entry-start"
+      exportparts="end: entry-end, item: entry-item, mark: entry-mark, shortcut: entry-shortcut,
+        shortcut-kbd: entry-shortcut-kbd, shortcut-key: entry-shortcut-key,
+        shortcut-separator: entry-shortcut-separator, start: entry-start"
           value=${entry.value}
           checkable
           ?checked=${entry.current}

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

@@ -0,0 +1,41 @@
+/**
+ * The order a playlist plays its entries in, and where a step from one lands.
+ *
+ * Separable because every answer is taken from a list of values and two
+ * settings, before anything moves: nothing here reaches a player or an entry.
+ * The playlist asks it which value comes next and applies the answer.
+ */
+/**
+ * How a playlist goes on at its end. `one` plays the same entry again when it
+ * ends, and `all` goes from the last entry back to the first.
+ */
+export type Repeat = 'all' | 'one';
+/**
+ * A shuffled copy of a list, with `first` leading where it is in the list.
+ *
+ * `first` leads because a reader turning shuffle on is watching something, and
+ * a shuffle that could put that entry anywhere would bring it round again
+ * before the rest have played.
+ *
+ * Fisher and Yates' shuffle, which gives every order of the rest the same
+ * chance. `random` is the source of chance, `Math.random` unless a caller
+ * passes one.
+ */
+export declare const shuffled: <T>(items: readonly T[], first?: T, random?: () => number) => T[];
+/**
+ * The order to play in.
+ *
+ * As written without shuffle. With it, the shuffled order already `held` for
+ * as long as it covers the same entries, so stepping back retraces what was
+ * played; a new one, led by `current`, once an entry arrives or leaves.
+ */
+export declare const playOrder: (values: readonly string[], shuffle: boolean, held: readonly string[] | undefined, current: string | undefined, random?: () => number) => string[];
+/**
+ * Where a step of `by` from `current` lands in `order`, or `undefined` past an
+ * end.
+ *
+ * `wrap` goes round instead of stopping, which is what `repeat="all"` asks
+ * for. With no current entry, a step forward lands on the first one and a step
+ * back on nothing, as a list that has not started has nothing behind it.
+ */
+export declare const stepTo: (order: readonly string[], current: string | undefined, by: number, wrap: boolean) => string | undefined;

package/dist/video-playlist/order.js

@@ -0,0 +1,34 @@
+export const shuffled = (items, first, random = Math.random) => {
+    const rest = items.filter((one) => one !== first);
+    for (let at = rest.length - 1; at > 0; at -= 1) {
+        const swap = Math.floor(random() * (at + 1));
+        const held = rest[at];
+        rest[at] = rest[swap];
+        rest[swap] = held;
+    }
+    return first !== undefined && items.includes(first) ? [first, ...rest] : rest;
+};
+const sameValues = (one, other) => one.length === other.length && one.every((value) => other.includes(value));
+export const playOrder = (values, shuffle, held, current, random = Math.random) => {
+    if (!shuffle) {
+        return [...values];
+    }
+    if (held !== undefined && sameValues(held, values)) {
+        return [...held];
+    }
+    return shuffled(values, current, random);
+};
+export const stepTo = (order, current, by, wrap) => {
+    const at = current === undefined ? -1 : order.indexOf(current);
+    if (at < 0) {
+        return by > 0 ? order[0] : undefined;
+    }
+    const to = at + by;
+    if (to >= 0 && to < order.length) {
+        return order[to];
+    }
+    if (!wrap || order.length === 0) {
+        return undefined;
+    }
+    return order[((to % order.length) + order.length) % order.length];
+};

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

@@ -1,5 +1,6 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
+import { type Repeat } from '../order.js';
 declare const HelixHeadlessVideoPlaylist_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerActiveInterface) & typeof HelixElement;
 /**
  * @summary A list of video clips that play one after another in a single player.
@@ -22,7 +23,17 @@ declare const HelixHeadlessVideoPlaylist_base: (new (...args: any[]) => import("
  * - the player reaches the end.
  *
  * On `ended` the playlist advances and the next clip starts playing, because
- * the user already pressed play once.
+ * the user already pressed play once. `repeat` decides what happens at the
+ * end: `one` plays the same entry again, and `all` goes from the last entry
+ * back to the first. Without it, the playlist stops on the last entry and
+ * sends `helix-end`. `shuffle` plays the entries in a random order, starting
+ * from the one that is current, and `previous` retraces that order.
+ *
+ * **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.
  *
  * @since 0.1.0
  * @status stable
@@ -33,8 +44,9 @@ declare const HelixHeadlessVideoPlaylist_base: (new (...args: any[]) => import("
  * @slot - The entries.
  * @slot player - The player that plays the entries.
  *
- * @event {HelixActivateEvent} helix-activate - The current entry changed. The playlist already holds the new entry when this is sent.
+ * @event {HelixActivateEvent} helix-activate - The current entry changed. The playlist already holds the new entry when this is sent, and `detail.previous` is the entry it left.
  * @event {HelixBeforeActivateEvent} helix-before-activate - The current entry is about to change. Cancelable: cancel it to keep the current entry.
+ * @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 player - The region that holds the player.
@@ -44,6 +56,30 @@ export declare class HelixHeadlessVideoPlaylist extends HelixHeadlessVideoPlayli
      * The list's name, read by screen readers.
      */
     label: string;
+    /**
+     * 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.
+     * Absent, the playlist stops on the last entry and sends `helix-end`.
+     *
+     * `all` also lets the next and previous controls go round, so next on the
+     * last entry is the first. `one` changes only what an ending does: next and
+     * previous still move, being a reader asking for another entry.
+     */
+    repeat?: Repeat;
+    /**
+     * Whether the entries play in a random order. The order starts from the
+     * entry that is current, and holds until shuffle is turned off or an entry
+     * arrives or leaves, so previous goes back through what has played.
+     */
+    shuffle: boolean;
+    /**
+     * The shuffled order of the entries' values, while `shuffle` is on.
+     *
+     * Held rather than drawn on each step, so previous retraces the way next
+     * came. Dropped when shuffle turns off, so turning it on again deals a new
+     * order from wherever the reader is.
+     */
+    private dealt;
     /**
      * The entries, in the order the consumer wrote them.
      *
@@ -82,14 +118,52 @@ export declare class HelixHeadlessVideoPlaylist extends HelixHeadlessVideoPlayli
      * contract.
      */
     private get player();
-    /** Moves by one, and does nothing at either end. */
+    /**
+     * The entry a step of `by` lands on, in the order the playlist plays in, or
+     * `undefined` past an end. Disabled entries are not in the order, so a step
+     * passes over them.
+     */
+    private following;
+    /**
+     * Moves by one in the playing order and plays what it lands on. At an end it
+     * stays, unless `repeat` is `all`.
+     *
+     * A move a consumer refuses with `helix-before-activate` plays nothing, and
+     * leaves nothing behind to play on a later change.
+     */
     private step;
+    /**
+     * Plays the current entry again from its start, which is what an ending
+     * under `repeat="one"` asks for, and a list of one under `repeat="all"`.
+     */
+    private replay;
+    /**
+     * Moves to the next entry and plays it, as the player's next control does.
+     * Follows `shuffle`, goes round under `repeat="all"`, and stays on the last
+     * entry otherwise.
+     */
+    next(): void;
+    /**
+     * Moves to the previous entry and plays it, as the player's previous control
+     * does. Under `shuffle` it goes back through the order that played.
+     */
+    previous(): void;
     private readonly handleSelect;
     private readonly handleNext;
     private readonly handlePrevious;
+    /**
+     * An entry ended: the same one again under `repeat="one"`, the next one in
+     * the order, or, past the last, `helix-end`.
+     *
+     * **A notification with no class of its own**, sent as a plain event and
+     * carrying nothing: the playlist is still on the last entry, and `active`
+     * says which. Not sent under `repeat`, where a list never runs out.
+     */
     private readonly handleEnded;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** A shuffle turned off forgets its order, so the next one is new. */
+    protected willUpdate(changed: PropertyValues): void;
     /**
      * Points the player at the current entry, and tells the entries which is on.
      *