@fusion.dev/helix-headless 0.104.1 → 0.106.0

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

@@ -2,34 +2,32 @@ import { HelixElement } from '@fusion.dev/helix-core';
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import '../../menu/index.js';
 /**
- * @summary Plays a video, with controls this library draws rather than the
- * browser's.
+ * @summary A video player with controls drawn by Helix.
  *
  * @description
- * **The picture is a real `<video>`.** Decoding, buffering, captions, Picture
- * in Picture, AirPlay and whatever codecs a device has are the platform's. What
- * is replaced is the control bar, which is the one part that cannot be styled.
+ * The picture is a native `<video>`, so decoding, buffering, captions, Picture
+ * in Picture, AirPlay, and codecs come from the platform. The component
+ * replaces the control bar, because the native bar cannot be styled.
  *
- * **Every control is a real control.** The scrubber and the volume are
- * `<input type="range">`, so arrow keys, Home and End, the platform's touch
- * target and its screen reader announcement all come for free.
+ * The scrubber and the volume are `<input type="range">` elements, so arrow
+ * keys, Home and End, touch targets, and screen reader announcements work as
+ * they do natively.
  *
- * **Native controls are the fallback, not the default.** Where a consumer sets
- * `controls` the browser's bar is used and this one is not drawn, and the keys
- * below are not bound: two handlers on one press is a video that seeks twice.
+ * When you set `controls`, the browser's control bar is used, the Helix bar is
+ * not drawn, and the keys below are not bound, so a key press does not seek
+ * twice.
  *
- * The keys are the ones every player uses: Space and `k` to play or pause, the
- * arrows to seek and to change volume, `m` to mute, `f` for fullscreen. They
- * are bound on this element rather than on the document, because a video is not
- * a palette.
+ * The keys match other players, and they are bound on the element only:
+ * - Space and `k` play or pause.
+ * - The arrow keys seek and change the volume.
+ * - `m` mutes.
+ * - `f` toggles fullscreen.
  *
- * **`<source>` and `<track>` are copied into the video, never slotted into it.**
- * A media element runs resource selection over its own child *nodes*, and a slot
- * is one node, so slotted sources reach it as nothing: no text tracks, no
- * current source, `readyState` zero. A video given sources that way does not
- * merely lack captions, it does not play. They are copied rather than moved,
- * because the consumer's light DOM is theirs, and rebuilt whenever the slot
- * changes.
+ * `<source>` and `<track>` children are copied into the video. A media element
+ * selects resources from its own child nodes, and a slot is one node, so
+ * slotted sources would give the video no text tracks, no current source, and a
+ * `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.
  *
  * @since 0.1.0
  * @status stable
@@ -38,71 +36,69 @@ import '../../menu/index.js';
  * @documentation https://fusion.dev/helix/components/video
  *
  * @slot - `<source>` and `<track>` elements, which are copied into the video.
- * @slot controls - Added to the control bar, before fullscreen.
- * @slot header - Top left over the frame: a heading, and a way out of a set beside it.
+ * @slot controls - Extra controls, added to the control bar before the fullscreen button.
+ * @slot header - Content over the top left of the picture, such as a heading and a back button.
  * @slot poster - Shown over the video until it starts.
  *
- * @event {Event} ended - Relayed, because it does not cross a shadow boundary.
- * @event {HelixNextEvent} helix-next - Fired when the reader asks for the next item.
- * @event {HelixPreviousEvent} helix-previous - Fired when they ask for the previous one.
- * @event {Event} pause - Relayed for the same reason.
- * @event {Event} play - Relayed for the same reason.
+ * @event {Event} ended - The video reached its end. Relayed from the inner video, since the native event does not cross the shadow boundary.
+ * @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.
  *
- * @csspart captions - Subtitles on and off.
- * @csspart captions-menu - The language menu, where there is more than one.
+ * @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.
  * @csspart captions-menu-back - The control that returns from a submenu.
  * @csspart captions-menu-back-mark - The glyph on the back control of a submenu.
- * @csspart captions-menu-empty - Shown when there are no items to show.
+ * @csspart captions-menu-empty - The text shown when the menu has no items.
  * @csspart captions-menu-header - The bar above a submenu, holding the way back and its name.
- * @csspart captions-menu-live - The inner menu's `live`, the region a screen reader hears its empty and loading lines from.
- * @csspart captions-menu-loading - Shown while the items are still on their way.
+ * @csspart captions-menu-live - The inner menu's `live` part, a live region that repeats the empty and loading text for screen readers.
+ * @csspart captions-menu-loading - The text shown while the items are loading.
  * @csspart captions-menu-surface - The floating panel the menu is drawn on.
  * @csspart captions-menu-title - The name of the submenu that is showing.
- * @csspart controls - The bar along the bottom.
- * @csspart cue - The caption on screen now, drawn by this element.
- * @csspart download - Saves the file, where it was asked for.
- * @csspart entry - One row in a menu this player opens.
+ * @csspart controls - The control bar along the bottom.
+ * @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-item - The row, which is an `<a>` where `href` is set.
- * @csspart entry-mark - The trailing mark: a tick when checked, a caret when it opens.
- * @csspart entry-start - The leading column, which is a slot and is always there.
- * @csspart failure - What is said when the source will not play.
- * @csspart forward - The control that goes on ten seconds.
- * @csspart fullscreen - The whole screen, and back.
- * @csspart header - The region top left, for a heading and a way out of a set.
- * @csspart live - What the loading line says, in a region a screen reader hears when it changes. Visually hidden in the styled tier.
- * @csspart loading - What is said while the picture waits for more of itself.
- * The part of that which spins is drawn on it, which is `::part(loading)::before`
- * from a consumer's sheet: this tier ships no CSS, so a box it renders for one to
- * paint is an empty child costing whatever the consumer's own layout charges for
- * a child. `ListItem` measured that.
- * @csspart more - The button that opens it.
- * @csspart mute - Sound on and off.
- * @csspart next - Asks for the next item, where it was asked for.
- * @csspart overflow - The menu holding the controls kept off the bar.
+ * @csspart entry-mark - The trailing mark: a check mark when the row is checked, or a caret when it opens a submenu.
+ * @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.
+ * @csspart fullscreen - The button that enters and leaves fullscreen.
+ * @csspart header - The region at the top left that holds the `header` slot.
+ * @csspart live - A live region that repeats the loading text, so screen readers announce it when it changes. Visually hidden in the styled tier.
+ * @csspart loading - The text shown while the video waits for more data. Draw the spinner
+ * with `::part(loading)::before` in your stylesheet. This tier ships no CSS and renders
+ * no extra box for it.
+ * @csspart more - The button that opens the `overflow` menu.
+ * @csspart mute - The button that turns sound on and off.
+ * @csspart next - The button that requests the next video, when `extra-controls` includes it.
+ * @csspart overflow - The menu that holds the controls kept off the bar.
  * @csspart overflow-back - The control that returns from a submenu.
  * @csspart overflow-back-mark - The glyph on the back control of a submenu.
- * @csspart overflow-empty - Shown when there are no items to show.
+ * @csspart overflow-empty - The text shown when the menu has no items.
  * @csspart overflow-header - The bar above a submenu, holding the way back and its name.
- * @csspart overflow-live - The inner menu's `live`, the region a screen reader hears its empty and loading lines from.
- * @csspart overflow-loading - Shown while the items are still on their way.
+ * @csspart overflow-live - The inner menu's `live` part, a live region that repeats the empty and loading text for screen readers.
+ * @csspart overflow-loading - The text shown while the items are loading.
  * @csspart overflow-surface - The floating panel the menu is drawn on.
  * @csspart overflow-title - The name of the submenu that is showing.
- * @csspart pip - Picture in picture, where it was asked for and exists.
- * @csspart play - Play and pause.
- * @csspart poster - What covers it before it plays.
- * @csspart previous - Asks for the previous one.
- * @csspart remote - Play on another device, where one is available.
+ * @csspart pip - The picture-in-picture button, when `extra-controls` includes it and the browser supports it.
+ * @csspart play - The button that plays and pauses.
+ * @csspart poster - The poster that covers the video before it plays.
+ * @csspart previous - The button that requests the previous video, when `extra-controls` includes it.
+ * @csspart remote - The button that plays the video on another device, when one is available.
  * @csspart remote-pressed - The remote control while the picture is on another device, beside `remote`.
- * @csspart rewind - The control that goes back ten seconds.
- * @csspart scrubber - Where it is, and where to go.
- * @csspart sound - The speaker and its level, which are one control.
- * @csspart speed - Playback speed, where it was asked for.
+ * @csspart rewind - The button that skips back ten seconds.
+ * @csspart scrubber - The slider that shows the position and moves playback to a new one.
+ * @csspart sound - The mute button and the volume slider, grouped as one control.
+ * @csspart speed - The playback speed control, when `extra-controls` includes it.
  * @csspart stage - The box holding the picture and its controls, and the focus
  * target the keys are bound to.
- * @csspart start - The mark over the picture before anything has played.
+ * @csspart start - The large play button over the picture, shown while the video is not playing.
  * @csspart time - The position and the duration.
  * @csspart video - The video itself.
- * @csspart volume - How loud.
+ * @csspart volume - The volume slider.
  *
  * @cssproperty --video-intrinsic-ratio - The media's own aspect ratio, once it is known. `--video-aspect-ratio` overrides it.
  * @cssproperty --video-level - The current volume, 0 to 1.
@@ -110,7 +106,8 @@ import '../../menu/index.js';
  */
 export declare class HelixHeadlessVideo extends HelixElement {
     /**
-     * Whether it starts on its own, which a browser only allows while silent.
+     * 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
@@ -119,7 +116,8 @@ export declare class HelixHeadlessVideo extends HelixElement {
      */
     autoplay: boolean;
     /**
-     * What the captions control is called where the video has one track, which it switches on and off.
+     * The name of the captions control when the video has one track. The control
+     * turns that track on and off.
      *
      * **Every word this player speaks is a property**, so a page in another
      * language hears its own: the play, pause, loading and error labels were,
@@ -127,11 +125,13 @@ export declare class HelixHeadlessVideo extends HelixElement {
      */
     captionsLabel: string;
     /**
-     * The row that turns captions off, where the video has several tracks to choose from.
+     * The name of the row that turns captions off, when the video has several
+     * tracks.
      */
     captionsOffLabel: string;
     /**
-     * Whether the browser draws the controls instead of this element.
+     * Whether the browser draws its native controls. When set, this element draws
+     * no controls of its own.
      *
      * A fallback rather than a default. Two bars over one video is worse than
      * either alone, so this one is not drawn at all when it is set.
@@ -143,7 +143,7 @@ export declare class HelixHeadlessVideo extends HelixElement {
      */
     crossOrigin: 'anonymous' | 'use-credentials' | null;
     /**
-     * Whether it *starts* silent, which is what an autoplaying video must do.
+     * Whether the video starts muted, which an autoplaying video must do.
      *
      * **Named for the platform's split, which is real.** The `muted` content
      * attribute reflects to `defaultMuted`; the `muted` property is live state a
@@ -154,11 +154,12 @@ export declare class HelixHeadlessVideo extends HelixElement {
      */
     defaultMuted: boolean;
     /**
-     * Whether the browser may offer picture in picture.
+     * Whether picture in picture is turned off, so the browser does not offer it.
      */
     disablePictureInPicture: boolean;
     /**
-     * Whether the browser may offer playback on a remote device.
+     * Whether remote playback is turned off, so the browser does not offer to
+     * play on another device.
      */
     disableRemotePlayback: boolean;
     /**
@@ -166,11 +167,11 @@ export declare class HelixHeadlessVideo extends HelixElement {
      */
     downloadLabel: string;
     /**
-     * And what they are told when it will not play at all.
+     * The message shown when the video cannot be played.
      */
     errorLabel: string;
     /**
-     * Controls beyond the ones every player has, named in the order they appear.
+     * Extra controls to add to the bar, named in the order they appear.
      *
      * A list rather than a property apiece. A bar is a row with a budget, and a
      * boolean per feature invites a consumer to switch all of them on: naming
@@ -214,7 +215,8 @@ export declare class HelixHeadlessVideo extends HelixElement {
      */
     fullscreenLabel: string;
     /**
-     * How long the bar waits after the pointer stops before it goes, in ms.
+     * How long the control bar stays after the pointer stops moving, in
+     * milliseconds.
      *
      * A wait rather than leaving with the pointer, or a reader moving across the
      * picture to reach a control watches the bar vanish under them. Zero turns
@@ -226,15 +228,15 @@ export declare class HelixHeadlessVideo extends HelixElement {
      */
     idleDelay: number;
     /**
-     * Accessible name, since a video is not described by its filename.
+     * Accessible name for the video, which its filename does not provide.
      */
     label: string;
     /**
-     * What a reader is told while the picture is waiting for more of itself.
+     * The text announced while the video waits for more data.
      */
     loadingLabel: string;
     /**
-     * Whether it starts again at the end.
+     * Whether the video starts again at the end.
      */
     loop: boolean;
     /**
@@ -242,7 +244,8 @@ export declare class HelixHeadlessVideo extends HelixElement {
      */
     moreLabel: string;
     /**
-     * What the control that silences the video is called, pressed while it is silent.
+     * The name of the mute control. The control shows as pressed while the video
+     * is muted.
      */
     muteLabel: string;
     /**
@@ -250,8 +253,8 @@ export declare class HelixHeadlessVideo extends HelixElement {
      */
     nextLabel: string;
     /**
-     * Controls that go behind one button instead of onto the bar, named the same
-     * way.
+     * Controls to place in a menu behind one button, named the same way as
+     * `extra-controls`.
      *
      * **Named rather than measured, and the reason is that a width cannot answer
      * this.** A media query asks about the window, and the bar's problem is its
@@ -268,7 +271,7 @@ export declare class HelixHeadlessVideo extends HelixElement {
      */
     overflowControls: string;
     /**
-     * And while it would stop it.
+     * The name of the play control while pressing it would pause the video.
      */
     pauseLabel: string;
     /**
@@ -280,19 +283,19 @@ export declare class HelixHeadlessVideo extends HelixElement {
      */
     pipLabel: string;
     /**
-     * What the play control is called while it would start the video.
+     * The name of the play control while pressing it would start the video.
      */
     playLabel: string;
     /**
-     * Whether it plays where it sits rather than taking over the screen.
+     * Whether the video plays in place, inside the page.
      */
     playsInline: boolean;
     /**
-     * A still shown before it plays, which the platform draws itself.
+     * An image shown before the video plays, drawn by the browser.
      */
     poster: string;
     /**
-     * How much to fetch before anything is asked for.
+     * How much of the video to load before playback is requested.
      */
     preload: 'auto' | 'metadata' | 'none';
     /**
@@ -320,11 +323,12 @@ export declare class HelixHeadlessVideo extends HelixElement {
      */
     speeds: string;
     /**
-     * Where the video is, for the common case of one file.
+     * The URL of the video, when there is one file.
      */
     src: string;
     /**
-     * The big mark over the picture whenever it is not playing, or `none`.
+     * The large play button over the picture while the video is not playing. Set
+     * `none` to hide it.
      *
      * **On unless it is turned off, because a stopped video has nothing else.**
      * Measured on the bar as it was: the play glyph is 16 by 16 in a 24 by 24
@@ -441,7 +445,7 @@ export declare class HelixHeadlessVideo extends HelixElement {
      */
     private media;
     /**
-     * The media's own state, under the platform's own names.
+     * The URL of the source the video is playing.
      *
      * **Published because there is no other way in.** The `<video>` is inside
      * this shadow root and `querySelector` does not cross it, so a consumer
@@ -469,29 +473,29 @@ export declare class HelixHeadlessVideo extends HelixElement {
      */
     get currentTime(): number;
     set currentTime(seconds: number);
-    /** The rate playback returns to, which `defaultPlaybackRate` names natively. */
+    /** The playback rate the video returns to by default. */
     get defaultPlaybackRate(): number;
     set defaultPlaybackRate(rate: number);
     /** How long the media runs, in seconds, and `NaN` until that is known. */
     get duration(): number;
     /** Whether playback has run off the end. */
     get ended(): boolean;
-    /** Whether playback is stopped, which is the resting state and not an error. */
+    /** Whether playback is paused, which is the resting state. */
     get paused(): boolean;
-    /** How fast it plays, where 1 is the recorded speed. */
+    /** How fast the video plays, where 1 is the recorded speed. */
     get playbackRate(): number;
     set playbackRate(rate: number);
     /** Whether pitch is held steady when the rate changes. */
     get preservesPitch(): boolean;
     set preservesPitch(preserve: boolean);
-    /** Whether it is currently moving to a new position. */
+    /** Whether the video is moving to a new position. */
     get seeking(): boolean;
     /** The media's own height in pixels, and zero until the metadata has loaded. */
     get videoHeight(): number;
     /** The media's own width in pixels, and zero until the metadata has loaded. */
     get videoWidth(): number;
     /**
-     * Whether there is sound, now, which a reader's click moves.
+     * Whether the video is muted right now. The mute control changes it.
      *
      * The live half of the pair above. Writing mutes or unmutes the media itself
      * rather than the attribute, which is what the platform does and what the
@@ -499,12 +503,12 @@ export declare class HelixHeadlessVideo extends HelixElement {
      */
     get muted(): boolean;
     set muted(quiet: boolean);
-    /** How loud it plays, 0 to 1. */
+    /** The volume, from 0 to 1. */
     get volume(): number;
     set volume(level: number);
     private get video();
     /**
-     * Starts playing, where the platform allows it.
+     * Starts playback, if the browser allows it.
      *
      * 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
@@ -512,9 +516,12 @@ export declare class HelixHeadlessVideo extends HelixElement {
      * control, which is the correct thing to be looking at.
      */
     play(): void;
-    /** Stops, leaving the frame up. */
+    /** Pauses playback and leaves the current frame showing. */
     pause(): void;
-    /** Toggles playback, which is what every key and the button both come to. */
+    /**
+     * Plays the video if it is paused, and pauses it if it is playing. The play
+     * button and the play keys call this.
+     */
     toggle(): void;
     /** Moves to a point in seconds, clamped to what exists. */
     seek(seconds: number): void;

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

@@ -4,23 +4,18 @@ import { type TemplateResult } from 'lit';
  * @summary One entry in a video playlist.
  *
  * @description
- * **It holds what the player needs and nothing about playing.** A source, a
- * poster and a name: the entry knows which file it stands for, and the playlist
- * is what hands that to a player. Nothing here touches a `<video>`, which is
- * what keeps a playlist usable with a player the consumer configured
- * themselves.
+ * **An entry holds a source, a poster, and a name**, and the playlist passes
+ * them to the player. The entry does not touch a `<video>`, so the playlist
+ * works with a player you configured yourself.
  *
- * **A real `<button>`, in a `listitem`.** A playlist is a list of things to
- * choose, and the list roles are the honest ones: `list` and `listitem` say how
- * many there are and where you are in them, which `listbox` would too, at the
- * cost of the pattern a listbox obliges. `Option` records that trap in full,
- * that a listbox has to keep focus elsewhere and say which item is current with
- * `aria-activedescendant`. Nothing here needs that, because focus really moves
- * to the button.
+ * **Each entry is a `<button>` inside a `listitem`.** The `list` and `listitem`
+ * roles tell a screen reader how many entries there are and the position of the
+ * focused one. Focus moves to the button, so the entry does not need the
+ * `listbox` pattern, which keeps focus elsewhere and marks the current item
+ * with `aria-activedescendant`. `Option` documents that pattern.
  *
- * `aria-current` rather than `aria-selected`, which belongs to the roles that
- * have a selection. What is true of the entry playing now is that it is the one
- * the player is on.
+ * The entry playing now carries `aria-current`. `aria-selected` belongs to
+ * roles that have a selection.
  *
  * @since 0.1.0
  * @status stable
@@ -28,21 +23,21 @@ import { type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/video-playlist
  *
  * @slot - The entry's name.
- * @slot media - A thumbnail. Falls back to an image of `poster`.
- * @slot meta - After the name. A duration, or a date.
+ * @slot media - A thumbnail. Defaults to an image of `poster`.
+ * @slot meta - Content after the name, such as a duration or a date.
  *
- * @event {HelixSelectEvent} helix-select - Fired when the entry is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - The entry was chosen. Cancelable: cancel it to keep the current entry.
  *
- * @csspart container - The `listitem`, which the button sits in.
+ * @csspart container - The list item that holds the button.
  * @csspart item - The row, which is a button.
- * @csspart item-current - The row of the entry the player is on, beside `item`.
- * @csspart label - The name and whatever follows it.
- * @csspart media - The leading column.
- * @csspart thumbnail - The image `poster` falls back to.
+ * @csspart item-current - Added to `item` for the entry that is playing.
+ * @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.
  */
 export declare class HelixHeadlessVideoPlaylistItem extends HelixElement {
     /**
-     * Whether the player is on this entry.
+     * Whether this entry is the one playing.
      *
      * Written by the playlist rather than by the entry, the way an option's
      * selection is: an entry that made itself current would be a second answer to
@@ -50,11 +45,11 @@ export declare class HelixHeadlessVideoPlaylistItem extends HelixElement {
      */
     current: boolean;
     /**
-     * Whether the entry can be chosen.
+     * Prevents the entry from being chosen.
      */
     disabled: boolean;
     /**
-     * What covers the picture before this entry plays, and the row's thumbnail.
+     * The image shown before this entry plays, also used as the row's thumbnail.
      *
      * One property doing both, because they are the same picture: the frame that
      * stands for the clip stands for it in the list too. It is the `media` slot's
@@ -68,11 +63,11 @@ export declare class HelixHeadlessVideoPlaylistItem extends HelixElement {
      */
     src: string;
     /**
-     * What identifies the entry, and what `active` is compared against.
+     * The entry's identifier, compared against the playlist's `active`.
      */
     value: string;
     /**
-     * The entry's name, which is the words and not everything in it.
+     * The entry's name: its own text, without the content in its named slots.
      *
      * `textContent` takes the whole subtree: a row with a duration in `meta`
      * reads as "His Girl Friday0:06", and that string reaches the player and the

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

@@ -5,15 +5,11 @@ import '../../menu/index.js';
  * @summary The playlist's entries, as a menu inside the player's control bar.
  *
  * @description
- * The entries again, reachable without leaving the picture. A playlist beside
- * the player is a list a reader scrolls to; the same list in the control bar is
- * one they open over the video.
+ * Opens the playlist entries from the player's control bar, over the video.
  *
- * **It is placed by the consumer, not rendered by the playlist**, and that is
- * forced rather than chosen: a shadow root cannot project into a sibling's
- * light DOM, so nothing the playlist renders can land inside the player's
- * control bar. What can is an element the consumer writes there, which is what
- * `Video`'s `controls` slot is for.
+ * **You place the menu yourself**, in `Video`'s `controls` slot. A shadow root
+ * cannot project into a sibling's light DOM, so the playlist cannot render into
+ * the player's control bar.
  *
  * @since 0.1.0
  * @status stable
@@ -23,27 +19,27 @@ import '../../menu/index.js';
  *
  * @slot trigger - Replaces the button that opens the menu.
  *
- * @event {HelixSelectEvent} helix-select - Fired with the chosen entry's value. The playlist listens for it. Cancelable: refusing it takes the decision and nothing moves.
+ * @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-item - The row, which is an `<a>` where `href` is set.
- * @csspart entry-mark - The trailing mark: a tick when checked, a caret when it opens
- * @csspart entry-start - The leading column, which is a slot and is always there.
+ * @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-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 control that returns from a submenu.
- * @csspart menu-back-mark - The glyph on the back control of a submenu.
+ * @csspart menu-back - The button that goes back from a submenu.
+ * @csspart menu-back-mark - The icon on a submenu's back button.
  * @csspart menu-empty - Shown when there are no items to show.
- * @csspart menu-header - The bar above a submenu, holding the way back and its name.
- * @csspart menu-live - The inner menu's `live`, the region a screen reader hears its empty and loading lines from.
- * @csspart menu-loading - Shown while the items are still on their way.
+ * @csspart menu-header - The bar above a submenu, holding the back button and the submenu's name.
+ * @csspart menu-live - The inner menu's `live` part, the region screen readers announce its empty and loading messages from.
+ * @csspart menu-loading - Shown while the items are loading.
  * @csspart menu-surface - The floating panel the menu is drawn on.
- * @csspart menu-title - The name of the submenu that is showing.
- * @csspart poster - An entry's still, where it has one.
- * @csspart trigger - The button that opens it.
+ * @csspart menu-title - The name of the submenu that is shown.
+ * @csspart poster - An entry's poster image, if it has one.
+ * @csspart trigger - The button that opens the menu.
  */
 export declare class HelixHeadlessVideoPlaylistMenu extends HelixElement {
     /**
-     * The menu's accessible name, and its trigger's.
+     * The name of the menu and its trigger, read by screen readers.
      *
      * "Episodes" suits a series and is wrong for a set of camera angles, and the
      * component cannot know which one it is in.