@fusion.dev/helix-headless 0.144.0 → 0.146.0

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

@@ -1,23 +1,30 @@
 import { HelixElement } from '@fusion.dev/helix-core';
-import { type TemplateResult } from 'lit';
+import { type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary An indicator that shows which way a measurement moved, and whether the change is good.
  *
  * @description
- * 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
+ * A trend has three parts: a `movement` of up, down, or neutral, the metric
+ * that moved, and a label for the period it moved over. The arrow shows the
+ * movement and its color shows whether the change is good. Movement and
  * judgment are separate properties because they are separate facts.
  *
  * `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.
+ * movement. The judgment is also a custom state, `better` or `worse`, for a
+ * sheet of your own.
  *
- * The direction is also written as a word, so a screen reader reads it. The
+ * The movement 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. The words are properties, `up-label` through
- * `worse-label`, so a page in another language can set its own.
+ * `worse-label`, so a page in another language can set its own. The arrow and
+ * any glyph slotted in its place are hidden from screen readers.
+ *
+ * Slot one glyph per movement into `up-icon`, `down-icon` and `neutral-icon`,
+ * and the trend shows the one that matches; a glyph in `icon` stands in for
+ * all three. Inside a `Stat`, put the trend in the stat's `trend` slot so it is
+ * read with the figure it qualifies.
  *
  * 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
@@ -30,11 +37,17 @@ import { type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/trend
  *
  * @slot - The metric that moved.
- * @slot icon - Replaces the arrow, such as with a glyph of your own set. Slot the one for the current direction.
+ * @slot down-icon - Replaces the arrow while `movement` is `down`. Hidden from screen readers.
+ * @slot icon - Replaces the arrow for every movement, such as with a glyph of your own set. Hidden from screen readers, since the movement is also a word.
  * @slot label - The period the metric moved over.
+ * @slot neutral-icon - Replaces the bar while the trend has not moved. Hidden from screen readers.
+ * @slot up-icon - Replaces the arrow while `movement` is `up`. Hidden from screen readers.
  *
- * @csspart direction - The direction as a word, for people who cannot see the arrow.
+ * @csspart direction - The movement as a word, for people who cannot see the arrow.
  * @csspart icon - The arrow.
+ *
+ * @cssstate better - The trend moved the way `good` names.
+ * @cssstate worse - The trend moved against the way `good` names.
  */
 export declare class HelixHeadlessTrend extends HelixElement {
     /**
@@ -42,14 +55,11 @@ export declare class HelixHeadlessTrend extends HelixElement {
      */
     betterLabel: string;
     /**
-     * Which way the measurement moved.
+     * Which way the measurement moved, as `movement` says it.
      *
-     * Absent is neutral, so a trend with nothing to report draws a bar rather
-     * than picking a direction. Optional rather than defaulted for the reason
-     * `Stat.direction` is: a reflecting property with a default writes its
-     * attribute onto the host the moment the element upgrades, and the host is
-     * markup the consumer rendered, which React compares against what it rendered
-     * and reports as a hydration mismatch.
+     * @deprecated Use `movement`. `direction` is a layout on `Stat` and `Flex`,
+     * which are written beside a trend, so one word meant two things. Still read
+     * when `movement` is absent.
      */
     direction?: 'down' | 'neutral' | 'up';
     /**
@@ -57,14 +67,24 @@ export declare class HelixHeadlessTrend extends HelixElement {
      */
     downLabel: string;
     /**
-     * Which direction counts as an improvement for this metric.
+     * Which movement 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
      * knows which one this is. Set it once per metric and it holds while the
-     * direction changes underneath.
+     * movement changes underneath.
      */
     good?: 'down' | 'up';
+    /**
+     * Which way the measurement moved.
+     *
+     * Absent is neutral, so a trend with nothing to report draws a bar rather
+     * than picking a direction. Optional rather than defaulted: a reflecting
+     * property with a default writes its attribute onto the host the moment the
+     * element upgrades, and the host is markup the consumer rendered, which React
+     * compares against what it rendered and reports as a hydration mismatch.
+     */
+    movement?: 'down' | 'neutral' | 'up';
     /**
      * The word read out for no move, or for a direction that is not one of the
      * three.
@@ -90,6 +110,11 @@ export declare class HelixHeadlessTrend extends HelixElement {
         content: string;
         viewBox: string;
     }): TemplateResult;
+    /** The movement, read from `movement` and then from the old `direction`. */
+    private get moved();
+    /** Better or worse, or neither when `good` is unset or nothing moved. */
+    private get judged();
+    protected willUpdate(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/trend/root/trend-root.js

@@ -25,7 +25,7 @@ let HelixHeadlessTrend = class HelixHeadlessTrend extends HelixElement {
         this.worseLabel = 'worse';
     }
     renderIcon(icon) {
-        return html `<slot name="icon"
+        return html `<slot aria-hidden="true" name="icon"
       ><svg
         aria-hidden="true"
         data-glyph
@@ -37,12 +37,34 @@ let HelixHeadlessTrend = class HelixHeadlessTrend extends HelixElement {
       </svg></slot
     >`;
     }
+    get moved() {
+        return this.movement ?? this.direction;
+    }
+    get judged() {
+        const moved = this.moved;
+        if (!this.good || !moved || !(moved in DIRECTIONS) || moved === 'neutral') {
+            return undefined;
+        }
+        return this.good === moved ? 'better' : 'worse';
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        const judged = this.judged;
+        this.toggleState('better', judged === 'better');
+        this.toggleState('worse', judged === 'worse');
+    }
     render() {
-        const direction = readDirection(this.direction);
-        const judgment = this.good && this.direction && this.direction !== 'neutral'
-            ? `, ${this.good === this.direction ? this.betterLabel : this.worseLabel}`
-            : '';
-        return html `${this.renderIcon(direction.icon)}
+        const moved = this.moved;
+        const direction = readDirection(moved);
+        const judged = this.judged;
+        const judgment = judged ? `, ${judged === 'better' ? this.betterLabel : this.worseLabel}` : '';
+        const icon = this.renderIcon(direction.icon);
+        const glyph = moved === 'up'
+            ? html `<slot aria-hidden="true" name="up-icon">${icon}</slot>`
+            : moved === 'down'
+                ? html `<slot aria-hidden="true" name="down-icon">${icon}</slot>`
+                : html `<slot aria-hidden="true" name="neutral-icon">${icon}</slot>`;
+        return html `${glyph}
       <span part="direction">${`${this[direction.word]}${judgment}`}</span>
       <slot></slot>
       <slot name="label"></slot>`;
@@ -60,6 +82,9 @@ __decorate([
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessTrend.prototype, "good", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessTrend.prototype, "movement", void 0);
 __decorate([
     property({ attribute: 'unchanged-label' })
 ], HelixHeadlessTrend.prototype, "unchangedLabel", void 0);

package/dist/video/media-events.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The media events a player sends on from its inner `<video>`, and how.
+ *
+ * Separable because the set is a decision about the platform, and nothing in it
+ * draws. It is the HTML standard's own summary of the events a media element
+ * fires, every one of them, so a consumer who listened on a `<video>` listens
+ * on the player with the same names and hears the same things. A shorter list
+ * would be one more list for a consumer to learn.
+ *
+ * None of these crosses a shadow boundary on its own. The video is inside the
+ * player's shadow root, so a listener on the element a consumer wrote hears
+ * nothing at all without the relay.
+ */
+/**
+ * Every event a media element fires, by the standard's names, sorted.
+ *
+ * `resize` is on the list because the standard puts it there: it fires when the
+ * video's own width or height changes, which is the moment a consumer sizing
+ * something to the picture needs.
+ */
+export declare const MEDIA_EVENTS: readonly ['abort', 'canplay', 'canplaythrough', 'durationchange', 'emptied', 'ended', 'error', 'loadeddata', 'loadedmetadata', 'loadstart', 'pause', 'play', 'playing', 'progress', 'ratechange', 'resize', 'seeked', 'seeking', 'stalled', 'suspend', 'timeupdate', 'volumechange', 'waiting'];
+/** One of the media events the player relays. */
+export type MediaEventName = (typeof MEDIA_EVENTS)[number];
+/**
+ * Hands each media event the video fires to `relay`, and returns what stops
+ * it. The player relays through `relayNativeEvent`, which sends the same name
+ * with the same `bubbles`, `cancelable` and `composed`.
+ *
+ * **As the platform sends it, neither bubbling nor composed, which is what
+ * makes it reach a React consumer at all.** These names are in react-dom's
+ * `nonDelegatedEvents`, which React wires on a `<video>` and never on a custom
+ * element, so its root listener hears none of them. `bindReactHandler` closes
+ * that for an event that does not bubble, and skips one that does, on the
+ * grounds that a bubbling relay already reaches React's delegated listener and
+ * binding it again would double every call. A copy sent with `bubbles: true`
+ * would land in the branch that refuses to bind, and `onPlay` on the player
+ * would be silent.
+ *
+ * Bound once, after the first render, so the player's own listeners in its
+ * template are ahead of it on the same video: what a consumer reads off the
+ * player in a handler (`paused`, `volume`, `currentTime`) is already the
+ * player's state by the time the copy reaches them.
+ */
+export declare const relayMedia: (video: EventTarget, relay: (event: Event) => void) => (() => void);

package/dist/video/media-events.js

@@ -0,0 +1,35 @@
+export const MEDIA_EVENTS = [
+    'abort',
+    'canplay',
+    'canplaythrough',
+    'durationchange',
+    'emptied',
+    'ended',
+    'error',
+    'loadeddata',
+    'loadedmetadata',
+    'loadstart',
+    'pause',
+    'play',
+    'playing',
+    'progress',
+    'ratechange',
+    'resize',
+    'seeked',
+    'seeking',
+    'stalled',
+    'suspend',
+    'timeupdate',
+    'volumechange',
+    'waiting',
+];
+export const relayMedia = (video, relay) => {
+    for (const name of MEDIA_EVENTS) {
+        video.addEventListener(name, relay);
+    }
+    return () => {
+        for (const name of MEDIA_EVENTS) {
+            video.removeEventListener(name, relay);
+        }
+    };
+};

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

@@ -17,11 +17,22 @@ import '../../menu/index.js';
  * not drawn, and the keys below are not bound, so a key press does not seek
  * twice.
  *
- * 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.
+ * **Keyboard.** The keys match other players, and they are bound on the
+ * element only, so they work while focus is on the player.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Space, `k` | Plays or pauses. Space on a button presses the button. |
+ * | Right, Left | Moves 5 seconds forward or back. |
+ * | Shift with Right or Left | Moves 10 seconds forward or back. |
+ * | `l`, `j` | Moves 10 seconds forward or back, as the skip buttons do. |
+ * | Up, Down | Raises or lowers the volume by a tenth. |
+ * | `m` | Mutes or unmutes. |
+ * | `f` | Enters or leaves fullscreen. |
+ * | Tab | Moves through the controls on the bar. |
+ *
+ * On the scrubber and the volume slider, the arrow keys, Page Up, Page Down,
+ * Home, and End move the slider, as on any range input.
  *
  * `<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
@@ -29,6 +40,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 +52,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 +113,13 @@ 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-shortcut-key - One key of a row's shortcut chord, inside `entry-shortcut`. The player's rows set none.
+ * @csspart entry-shortcut-separator - The `+` between two keys of a row's shortcut, where the platform writes one.
  * @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 +167,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 +340,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 +403,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 +581,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 +721,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 +802,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 {