@fusion.dev/helix-headless 0.144.0 → 0.145.0

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

@@ -29,6 +29,11 @@ import '../../menu/index.js';
  * `readyState` of zero, and it would not play. They are copied so your light
  * DOM stays intact, and are copied again whenever the slot changes.
  *
+ * The player sends every media event of its inner video under the same name,
+ * without bubbling, as a `<video>` sends it. Listen on the player as you would
+ * on a video: `timeupdate`, `volumechange`, `loadedmetadata`, `error`, and the
+ * rest.
+ *
  * @since 0.1.0
  * @status stable
  * @category media
@@ -36,15 +41,52 @@ import '../../menu/index.js';
  * @documentation https://fusion.dev/helix/components/video
  *
  * @slot - `<source>` and `<track>` elements, which are copied into the video.
+ * @slot captions-icon - Replaces the glyph on the captions control.
  * @slot controls - Extra controls, added to the control bar before the fullscreen button.
+ * @slot download-icon - Replaces the glyph on the download control, on the bar or in the `overflow` menu.
+ * @slot exit-fullscreen-icon - Replaces the glyph on the fullscreen control while the player fills the screen.
+ * @slot forward-icon - Replaces the glyph on the control that skips forward, on the bar or in the `overflow` menu.
+ * @slot fullscreen-icon - Replaces the glyph on the fullscreen control.
  * @slot header - Content over the top left of the picture, such as a heading and a back button.
+ * @slot more-icon - Replaces the glyph on the button that opens the `overflow` menu.
+ * @slot mute-icon - Replaces the glyph on the mute control while there is no sound.
+ * @slot next-icon - Replaces the glyph on the control that asks for the next video, on the bar or in the `overflow` menu.
+ * @slot pause-icon - Replaces the glyph on the play control while the video plays.
+ * @slot pip-icon - Replaces the glyph on the picture-in-picture control, on the bar or in the `overflow` menu.
+ * @slot play-icon - Replaces the glyph on the play control while the video is paused.
  * @slot poster - Shown over the video until it starts.
+ * @slot previous-icon - Replaces the glyph on the control that asks for the previous video, on the bar or in the `overflow` menu.
+ * @slot remote-icon - Replaces the glyph on the control that plays on another device, on the bar or in the `overflow` menu.
+ * @slot rewind-icon - Replaces the glyph on the control that skips back, on the bar or in the `overflow` menu.
+ * @slot speed-icon - Replaces the glyph beside the playback speed in the `overflow` menu. On the bar, the speed is shown as a number.
+ * @slot start-icon - Replaces the glyph on the large play button over the picture.
+ * @slot volume-icon - Replaces the glyph on the mute control while there is sound.
  *
- * @event {Event} ended - The video reached its end. Relayed from the inner video, since the native event does not cross the shadow boundary.
+ * @event {Event} abort - The media stopped loading before it finished, without an error.
+ * @event {Event} canplay - Enough has loaded to start playing.
+ * @event {Event} canplaythrough - Enough has loaded to play to the end without stopping, at the current rate.
+ * @event {Event} durationchange - The duration changed, which it does once the metadata is in.
+ * @event {Event} emptied - The media was reset, as when `src` changes.
+ * @event {Event} ended - The video reached its end.
+ * @event {Event} error - The source could not be loaded or played. The player shows `error-label` as well.
  * @event {HelixNextEvent} helix-next - The next video was requested. Load it in response.
  * @event {HelixPreviousEvent} helix-previous - The previous video was requested. Load it in response.
- * @event {Event} pause - Playback paused. Relayed from the inner video.
- * @event {Event} play - Playback started. Relayed from the inner video.
+ * @event {Event} loadeddata - The frame at the current position has loaded.
+ * @event {Event} loadedmetadata - The duration and the size of the video are known.
+ * @event {Event} loadstart - The video started looking for its media.
+ * @event {Event} pause - Playback paused.
+ * @event {Event} play - Playback was asked to start.
+ * @event {Event} playing - Playback started, or started again after waiting for data.
+ * @event {Event} progress - More of the media has downloaded.
+ * @event {Event} ratechange - The playback rate changed. Read `playbackRate`.
+ * @event {Event} resize - The video's own width or height changed. Read `videoWidth` and `videoHeight`.
+ * @event {Event} seeked - A move to a new position finished.
+ * @event {Event} seeking - A move to a new position started.
+ * @event {Event} stalled - The browser is trying to load more data and none is arriving.
+ * @event {Event} suspend - Loading paused on purpose, as when `preload` asks for no more.
+ * @event {Event} timeupdate - The position changed. Read `currentTime`.
+ * @event {Event} volumechange - The volume or the mute changed. Read `volume` and `muted`.
+ * @event {Event} waiting - Playback stopped to wait for more data.
  *
  * @csspart captions - The button that turns captions on and off.
  * @csspart captions-menu - The menu of caption languages, when the video has more than one track.
@@ -60,8 +102,11 @@ import '../../menu/index.js';
  * @csspart cue - The caption currently on screen, drawn by this element.
  * @csspart download - The button that downloads the file, when `extra-controls` includes it.
  * @csspart entry - One row in a menu that the player opens.
+ * @csspart entry-end - The trailing column of a row, which holds its shortcut. It is always rendered.
  * @csspart entry-item - The row, which is an `<a>` where `href` is set.
  * @csspart entry-mark - The trailing mark: a check mark when the row is checked, or a caret when it opens a submenu.
+ * @csspart entry-shortcut - The key drawn for a row's shortcut. The player's rows set none.
+ * @csspart entry-shortcut-kbd - The key inside `entry-shortcut`.
  * @csspart entry-start - The leading column that holds the `start` slot. It is always rendered.
  * @csspart failure - The message shown when the source cannot be played.
  * @csspart forward - The button that skips forward ten seconds.
@@ -109,10 +154,10 @@ export declare class HelixHeadlessVideo extends HelixElement {
      * Whether the video starts playing on its own. Browsers allow this only while
      * it is muted.
      *
-     * Forwarded rather than acted on. Whether an unprompted play is permitted is
-     * the browser's policy and not this element's, and `play()` already swallows
-     * the refusal: what follows a refused autoplay is a paused player showing its
-     * start control, which is the correct thing to be looking at.
+     * Forwarded to the video, which decides. Whether an unprompted play is
+     * permitted is the browser's policy, and what follows a refused autoplay is a
+     * paused player showing its start control, which is the correct thing to be
+     * looking at.
      */
     autoplay: boolean;
     /**
@@ -282,6 +327,11 @@ export declare class HelixHeadlessVideo extends HelixElement {
      * What the control that floats the video over other windows is called.
      */
     pipLabel: string;
+    /**
+     * The name of the player when `label` is not set. The player is a group, and
+     * this is what a screen reader calls it on arriving.
+     */
+    playerLabel: string;
     /**
      * The name of the play control while pressing it would start the video.
      */
@@ -340,6 +390,14 @@ export declare class HelixHeadlessVideo extends HelixElement {
      * behind a hero, a grid of eight thumbnails, anything where the video is
      * decoration rather than something to start.
      *
+     * **It is for the pointer, and the bar's Play is for everyone else.** Both
+     * play the video, so a keyboard met two stops called "Play" one after the
+     * other and a screen reader read the same button twice. The large one is out
+     * of the tab order and hidden from assistive technology while the bar is
+     * drawn, which is whenever it is: it shows only while the video is not
+     * playing, and the bar does not fade then. A press on it leaves focus on the
+     * player, so the keys go on working once it has gone.
+     *
      * A value rather than a boolean, so the resting state is the attribute's
      * absence: a boolean defaulting to on would have to be spelled as its own
      * negation.
@@ -510,14 +568,19 @@ export declare class HelixHeadlessVideo extends HelixElement {
     set volume(level: number);
     private get video();
     /**
-     * Starts playback, if the browser allows it.
+     * Starts playback, and returns the video's own promise: it settles when
+     * playback starts, and rejects when the browser refuses.
+     *
+     * **A refusal is not reported as an unhandled rejection.** A browser refuses
+     * `play()` when nothing the reader did asked for it, and that is a policy
+     * answer: what follows is a paused player showing its start control. So the
+     * promise is marked handled here, and a caller who awaits it still hears the
+     * refusal.
      *
-     * The rejection is swallowed on purpose: a browser refuses `play()` when
-     * nothing the reader did asked for it, and that is a policy answer rather than
-     * a fault. What follows a refused play is a paused player showing its start
-     * control, which is the correct thing to be looking at.
+     * Before the first render there is no video yet, and the promise waits for
+     * one.
      */
-    play(): void;
+    play(): Promise<void>;
     /** Pauses playback and leaves the current frame showing. */
     pause(): void;
     /**
@@ -645,6 +708,16 @@ export declare class HelixHeadlessVideo extends HelixElement {
      * mouse left resting until the bar faded.
      */
     private readonly handlePicture;
+    /**
+     * A press on the large play button plays, and leaves focus on the player.
+     *
+     * The button takes focus from the press and is gone once the video plays,
+     * which drops focus to the page, and the keys bound to the player stop
+     * answering. Moved to the stage first, they keep working. The press came from
+     * a pointer, the button being out of the tab order, so the stage draws no
+     * ring for it.
+     */
+    private readonly handleStart;
     /**
      * The keys every player uses, bound to this element rather than the document.
      *
@@ -716,6 +789,19 @@ export declare class HelixHeadlessVideo extends HelixElement {
     private heardMenu;
     protected renderOverflowItem(one: string): TemplateResult;
     protected renderBar(): TemplateResult;
+    /**
+     * The large play button over the picture, or nothing.
+     *
+     * Drawn whenever the video is not playing, which is what the mark means:
+     * press this to play. Not only before the first play, which would make the
+     * mark mean two different things at two moments that are the same state.
+     * Every player a reader has used shows it on pause, and the one who paused to
+     * study a frame clears it by pressing the thing in the way.
+     *
+     * Not drawn at all where the browser draws its own controls, since that bar
+     * has a play button and two would be two.
+     */
+    protected renderStart(): TemplateResult | typeof nothing;
     protected render(): TemplateResult;
 }
 declare global {

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, this);
         }
     }
     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,12 @@ 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, start: entry-start"
         value="off"
         checkable
         exclusive
@@ -557,7 +571,8 @@ 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, start: entry-start"
           value=${track.language || String(at)}
           checkable
           exclusive
@@ -584,63 +599,72 @@ 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, 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, 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, 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, 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, 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, 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, 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 +677,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 +717,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 +753,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 +766,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 +867,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 +944,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,11 @@ 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-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,8 @@ 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, 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];
+};