@fusion.dev/helix-headless 0.105.0 → 0.106.0

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

@@ -2,16 +2,16 @@ import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessTree_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerActiveInterface) & typeof HelixElement;
 /**
- * @summary A tree of items, navigable entirely from the keyboard.
+ * @summary A hierarchy of items, with branches that open and close.
  *
  * @description
- * Focus is a single tab stop, moved with the arrow keys, which is what the tree
- * pattern requires: a sidebar of forty items should not be forty presses of Tab
- * to get past. The tree owns which item is the tab stop and moves it as focus
- * moves, so the browser's own focus order is never fought with.
+ * The tree is a single tab stop, and arrow keys move focus between items, as
+ * the tree pattern requires, so Tab moves past a long sidebar in one press. The
+ * tree moves the tab stop to the focused item, so the browser's focus order
+ * stays intact.
  *
  * Items are found with `instanceof`, never by tag name, so the headless tier
- * does not learn about the styled one.
+ * does not depend on the styled one.
  *
  * @since 0.1.0
  * @status stable
@@ -21,13 +21,13 @@ declare const HelixHeadlessTree_base: (new (...args: any[]) => import("@fusion.d
  *
  * @slot - The tree's items.
  *
- * @event {HelixActivateEvent} helix-activate - Fired once the current one has moved, so the element already holds it.
- * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the current node moves, and cancelable. The only way to refuse one.
- * @event {HelixSelectEvent} helix-select - Fired when an item is chosen. Dispatched by the item and listened for here, because the tree is what a consumer holds a reference to. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixActivateEvent} helix-activate - Fired after the current node changes, so the tree already holds the new one.
+ * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the current node changes, and cancelable. Canceling it is the only way to stop the change.
+ * @event {HelixSelectEvent} helix-select - Fired when an item is chosen. The item sends it, and you can listen for it on the tree. Cancelable: canceling it changes nothing.
  *
  * @csspart empty - Shown when there are no rows to show.
- * @csspart live - The empty and loading lines again, in a region a screen reader hears when they change. Visually hidden in the styled tier.
- * @csspart loading - Shown while the rows are still on their way.
+ * @csspart live - A copy of the empty and loading messages, in a live region that announces them when they change. Visually hidden in the styled tier.
+ * @csspart loading - Shown while the rows load.
  * @csspart tree - The tree container.
  */
 export declare class HelixHeadlessTree extends HelixHeadlessTree_base {
@@ -36,7 +36,8 @@ export declare class HelixHeadlessTree extends HelixHeadlessTree_base {
      */
     label: string;
     /**
-     * What a step inward means: nothing, a rank, or a heading over what follows.
+     * What a deeper level means: `peer` for no change, `subordinate` for a lower
+     * rank, or `heading` for a parent that heads the items under it.
      *
      * All three answers are right, for different trees, which is why this is
      * asked rather than decided. `peer` is a file explorer: every row is the same

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

@@ -1,27 +1,26 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type TemplateResult } from 'lit';
 /**
- * @summary Which way a measurement moved, and whether that is good news.
+ * @summary An indicator that shows which way a measurement moved, and whether the change is good.
  *
  * @description
- * Three parts: a direction that is up, down or neutral, the metric that moved,
- * and a label saying over what. The arrow carries the direction and its color
- * carries the judgment, and the two are separate properties because they are
- * separate facts.
+ * A trend has three parts: a direction of up, down, or neutral, the metric that
+ * moved, and a label for the period it moved over. The arrow shows the
+ * direction and its color shows whether the change is good. Direction and
+ * judgment are separate properties because they are separate facts.
  *
- * **`good` is absent by default, so an unjudged trend is gray.** Every
- * dashboard convention says up is green, and for churn, latency, error rate,
- * cost and bounce rate that convention is a lie told in the most legible color
- * on the page. State the metric's polarity once and the component does the part
- * that varies.
+ * `good` is unset by default, so a trend with no judgment is gray. For churn,
+ * latency, error rate, cost, and bounce rate, up is bad. Set the metric's
+ * polarity once with `good`, and the component picks the color from the
+ * direction.
  *
- * The direction is also written as a word, because a colored arrow says
- * nothing to a reader who is not looking at it. `part="direction"` is what the
- * styled tier clips out of sight and leaves in the accessibility tree.
+ * The direction is also written as a word, so a screen reader reads it. The
+ * styled tier hides `part="direction"` visually and keeps it in the
+ * accessibility tree.
  *
- * Both the metric and the label are bare slots. An element whose only job is to
- * assign itself a slot on connect gives its own host an attribute after
- * upgrade, which a React consumer's server markup never had.
+ * The metric and the label are bare slots. An element that assigned its own
+ * slot on connect would add an attribute to its host after upgrade, which the
+ * React server markup did not have.
  *
  * @since 0.1.0
  * @status stable
@@ -30,9 +29,9 @@ import { type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/trend
  *
  * @slot - The metric that moved.
- * @slot label - What it moved over.
+ * @slot label - The period the metric moved over.
  *
- * @csspart direction - The direction as a word, for readers who are not looking.
+ * @csspart direction - The direction as a word, for people who cannot see the arrow.
  * @csspart icon - The arrow.
  */
 export declare class HelixHeadlessTrend extends HelixElement {
@@ -48,7 +47,7 @@ export declare class HelixHeadlessTrend extends HelixElement {
      */
     direction?: 'down' | 'neutral' | 'up';
     /**
-     * Which direction is the improvement, for this metric.
+     * Which direction counts as an improvement for this metric.
      *
      * Absent states the movement without judging it, which is the honest default:
      * revenue up is good news and latency up is bad news, and only the consumer

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;