@videojs/html 10.0.0-rc.1 → 10.0.0-rc.3

package/docs/reference/components/status-announcer.md

@@ -0,0 +1,270 @@
+# media-status-announcer
+
+Announce player state changes through a persistent status live region
+
+## Import
+
+```ts
+import '@videojs/html/ui/status-announcer';
+```
+
+## Anatomy
+
+```html
+<media-status-announcer></media-status-announcer>
+```
+
+## Behavior
+
+`<media-status-announcer>` watches player-store snapshots, so it reports changes made by buttons, sliders, custom controls, or direct player actions. It does not depend on [`<media-hotkey>`](./hotkey.md) or [`<media-gesture>`](./gesture.md) events.
+
+The first snapshot establishes a baseline without announcing it. Later changes are handled in two groups:
+
+| Timing | Changes |
+| --- | --- |
+| Immediate | Playing or paused, captions on or off, fullscreen entered or exited, picture-in-picture entered or exited, and playback rate |
+| Debounced by 200 milliseconds | The final volume or mute value and the final time after a completed seek |
+
+Regular playback-time updates are ignored. A seek announcement is queued only after `seeking` changes from `true` to `false` at a different time. When several immediate states change in one snapshot, their translated labels are combined into one announcement.
+
+The component always renders with `role="status"`. Its `[data-status-announcer-content]` child is replaced for every announcement, including repeated text, so assistive technology receives a fresh live-region change. After `closeDelay`, which defaults to 800 milliseconds, the label is cleared while the status region remains rendered.
+
+Announcements use the active Video.js locale and translations.
+
+The custom element receives labels from the nearest player i18n context.
+
+## Styling
+
+`<media-status-announcer>` is not visually hidden by the primitive. Apply a visually-hidden class while keeping it in the accessibility tree. Do not use `display: none`, `visibility: hidden`, or the `hidden` attribute.
+
+```css
+media-status-announcer {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  white-space: nowrap;
+  border: 0;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+}
+```
+
+## Accessibility
+
+The `status` role provides implicit polite live-region behavior, so the component does not add an explicit `aria-live` attribute.
+
+Keep one announcer inside each player `<media-container>` whose state changes should be reported.
+
+Debounced volume and completed-seek announcements are suppressed while an element with `role="slider"` inside the same container has focus. The focused slider provides its own value feedback, and suppressing the separate status message avoids duplicate announcements. A focused slider outside that container does not suppress it.
+
+Use [`<media-seek-indicator>`](./seek-indicator.md) for temporary visual seek feedback. Keep that visual value out of a live region; `<media-status-announcer>` owns the accessible announcement.
+
+## Examples
+
+### Basic Usage
+
+Use the playback button for an immediate announcement and the mute button for a debounced announcement. The sliders provide their own focused value feedback, so `<media-status-announcer>` suppresses its duplicate volume and completed-seek message.
+
+**index.html**
+
+```html
+<video-player>
+  <media-container class="html-status-announcer-basic">
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline></video>
+    <p class="html-status-announcer-basic__instructions">These controls announce status changes to screen readers.</p>
+    <div class="html-status-announcer-basic__controls">
+      <media-play-button class="html-status-announcer-basic__button">
+        <span class="show-when-paused">Play</span>
+        <span class="show-when-playing">Pause</span>
+        <span class="show-when-ended">Replay</span>
+      </media-play-button>
+      <media-mute-button class="html-status-announcer-basic__button">
+        <span class="show-when-muted">Unmute</span>
+        <span class="show-when-unmuted">Mute</span>
+      </media-mute-button>
+      <media-volume-slider class="html-status-announcer-basic__volume-slider">
+        <media-slider-track class="html-status-announcer-basic__track">
+          <media-slider-fill class="html-status-announcer-basic__fill"></media-slider-fill>
+        </media-slider-track>
+        <media-slider-thumb class="html-status-announcer-basic__thumb"></media-slider-thumb>
+      </media-volume-slider>
+    </div>
+    <media-time-slider class="html-status-announcer-basic__time-slider">
+      <media-slider-track class="html-status-announcer-basic__track">
+        <media-slider-buffer class="html-status-announcer-basic__buffer"></media-slider-buffer>
+        <media-slider-fill class="html-status-announcer-basic__fill"></media-slider-fill>
+      </media-slider-track>
+      <media-slider-thumb class="html-status-announcer-basic__thumb"></media-slider-thumb>
+    </media-time-slider>
+    <media-status-announcer class="html-status-announcer-basic__announcer"></media-status-announcer>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.html-status-announcer-basic {
+  position: relative;
+}
+
+.html-status-announcer-basic video {
+  display: block;
+  width: 100%;
+}
+
+.html-status-announcer-basic__instructions {
+  position: absolute;
+  top: 10px;
+  left: 10px;
+  padding: 6px 10px;
+  margin: 0;
+  color: white;
+  background: rgb(0 0 0 / 70%);
+  border-radius: 4px;
+}
+
+.html-status-announcer-basic__controls {
+  position: absolute;
+  right: 12px;
+  bottom: 36px;
+  left: 12px;
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.html-status-announcer-basic__button {
+  padding: 7px 14px;
+  color: black;
+  cursor: pointer;
+  background: rgb(255 255 255 / 85%);
+  border: 1px solid rgb(255 255 255 / 30%);
+  border-radius: 9999px;
+}
+
+.html-status-announcer-basic__button .show-when-paused,
+.html-status-announcer-basic__button .show-when-playing,
+.html-status-announcer-basic__button .show-when-ended,
+.html-status-announcer-basic__button .show-when-muted,
+.html-status-announcer-basic__button .show-when-unmuted {
+  display: none;
+}
+
+.html-status-announcer-basic__button[data-paused]:not([data-ended]) .show-when-paused,
+.html-status-announcer-basic__button:not([data-paused]) .show-when-playing,
+.html-status-announcer-basic__button[data-ended] .show-when-ended,
+.html-status-announcer-basic__button[data-muted] .show-when-muted,
+.html-status-announcer-basic__button:not([data-muted]) .show-when-unmuted {
+  display: inline;
+}
+
+.html-status-announcer-basic__volume-slider,
+.html-status-announcer-basic__time-slider {
+  position: relative;
+  display: flex;
+  align-items: center;
+  height: 20px;
+  cursor: pointer;
+}
+
+.html-status-announcer-basic__volume-slider {
+  width: 100px;
+}
+
+.html-status-announcer-basic__time-slider {
+  position: absolute;
+  right: 12px;
+  bottom: 8px;
+  left: 12px;
+}
+
+.html-status-announcer-basic__track {
+  position: absolute;
+  right: 0;
+  left: 0;
+  height: 5px;
+  overflow: hidden;
+  background: rgb(255 255 255 / 30%);
+  border-radius: 9999px;
+}
+
+.html-status-announcer-basic__buffer,
+.html-status-announcer-basic__fill {
+  position: absolute;
+  top: 0;
+  left: 0;
+  height: 100%;
+  border-radius: inherit;
+}
+
+.html-status-announcer-basic__buffer {
+  width: var(--media-slider-buffer);
+  background: rgb(255 255 255 / 30%);
+}
+
+.html-status-announcer-basic__fill {
+  width: var(--media-slider-fill);
+  background: white;
+}
+
+.html-status-announcer-basic__thumb {
+  position: absolute;
+  left: var(--media-slider-fill);
+  width: 14px;
+  height: 14px;
+  background: white;
+  border-radius: 50%;
+  box-shadow: 0 1px 3px rgb(0 0 0 / 40%);
+  translate: -50%;
+}
+
+.html-status-announcer-basic__announcer {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  white-space: nowrap;
+  border: 0;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/mute-button';
+import '@videojs/html/ui/play-button';
+import '@videojs/html/ui/status-announcer';
+import '@videojs/html/ui/time-slider';
+import '@videojs/html/ui/slider-track';
+import '@videojs/html/ui/slider-buffer';
+import '@videojs/html/ui/slider-fill';
+import '@videojs/html/ui/slider-thumb';
+import '@videojs/html/ui/volume-slider';
+```
+
+## API Reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `closeDelay` (attribute `close-delay`) | `number` | — | Delay in milliseconds before the current announcement label is cleared. |
+
+### State
+
+State is reflected as data attributes for CSS styling.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `generation` | `number` | Increments for each announcement so repeated labels replace the live-region content. |
+| `label` | `string \| null` | Current announcement text, or `null` when the live region is empty. |

package/docs/reference/components/status-indicator.md

@@ -0,0 +1,266 @@
+# media-status-indicator
+
+Display temporary visual feedback for keyboard and gesture actions
+
+## Import
+
+```ts
+import '@videojs/html/ui/status-indicator';
+import '@videojs/html/ui/status-indicator-value';
+```
+
+## Anatomy
+
+```html
+<media-status-indicator>
+  <media-status-indicator-value></media-status-indicator-value>
+</media-status-indicator>
+```
+
+## Behavior
+
+`<media-status-indicator>` displays feedback for actions emitted by a [`<media-hotkey>`](./hotkey.md) or [`<media-gesture>`](./gesture.md) in the same player `<media-container>`. It does not react to buttons, direct player-store changes, or media state changes on their own.
+
+The input event arrives before its action is resolved. The indicator uses the media snapshot from that moment to predict the next visual status:
+
+| Action | `data-status` | Value |
+| --- | --- | --- |
+| `togglePaused` | `"play"` or `"pause"` | Translated playing or paused label |
+| `toggleMuted` | `"volume-off"`, `"volume-low"`, or `"volume-high"` | Predicted volume percentage |
+| `volumeStep` | `"volume-off"`, `"volume-low"`, or `"volume-high"` | Predicted volume percentage |
+| `toggleSubtitles` | `"captions-on"` or `"captions-off"` | Translated captions label |
+| `toggleFullscreen` | `"fullscreen"` or `"exit-fullscreen"` | Translated fullscreen label |
+| `togglePictureInPicture` | `"pip"` or `"exit-pip"` | Translated picture-in-picture label |
+
+`toggleSubtitles` is ignored when the player reports that no captions or subtitles are available. Seek actions, `toggleControls`, playback-rate actions, and custom actions do not open this indicator.
+
+Use `actions` to allow only some of the supported actions. Omitting it allows all supported actions.
+
+Set the `actions` attribute to action names separated by commas, whitespace, or both:
+
+```html
+<media-status-indicator actions="togglePaused, toggleMuted">
+  <media-status-indicator-value></media-status-indicator-value>
+</media-status-indicator>
+```
+
+The indicator closes after `closeDelay`, which defaults to 800 milliseconds. A repeated handled action updates the current value and restarts that close timer without replaying the entry transition.
+
+The element remains in the document with `hidden` until the next handled action.
+
+## Styling
+
+| Attribute | Values | Description |
+| --- | --- | --- |
+| `data-open` | Present / absent | Present while the indicator is open |
+| `data-status` | `"play"`, `"pause"`, `"volume-off"`, `"volume-low"`, `"volume-high"`, `"captions-on"`, `"captions-off"`, `"fullscreen"`, `"exit-fullscreen"`, `"pip"`, or `"exit-pip"` | Predicted status for the handled action |
+| `data-starting-style` | Present / absent | Present during the open transition |
+| `data-ending-style` | Present / absent | Present during the close transition |
+
+Use `data-status` to select an icon or other visual treatment, and use the transition attributes for entry and exit styles.
+
+```css
+media-status-indicator[data-status="play"] {
+  color: green;
+}
+
+media-status-indicator[data-starting-style],
+media-status-indicator[data-ending-style] {
+  opacity: 0;
+}
+```
+
+## Accessibility
+
+`<media-status-indicator>` is visual feedback and does not create a live region. Keep every action available through keyboard-operable controls, and pair the player with [`<media-status-announcer>`](./status-announcer.md) when state changes should be announced to screen readers. Do not make `<media-status-indicator-value>` a live region.
+
+## Examples
+
+### Basic Usage
+
+Focus the player, then press K to play or pause, M to mute, F for fullscreen, C for captions, or I for picture-in-picture.
+
+**index.html**
+
+```html
+<video-player>
+  <media-container class="html-status-indicator-basic" tabindex="0">
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop>
+      <track kind="captions" src="/docs/demos/captions-button/captions.vtt" srclang="en" label="English" />
+    </video>
+    <p class="html-status-indicator-basic__instructions">
+      Focus the player · K: play/pause · M: mute · F: fullscreen · C: captions · I: picture-in-picture
+    </p>
+    <media-status-indicator
+      class="html-status-indicator-basic__indicator"
+      actions="togglePaused toggleMuted toggleSubtitles toggleFullscreen togglePictureInPicture"
+      aria-hidden="true"
+    >
+      <media-status-indicator-value class="html-status-indicator-basic__value"></media-status-indicator-value>
+    </media-status-indicator>
+    <media-hotkey keys="k" action="togglePaused"></media-hotkey>
+    <media-hotkey keys="m" action="toggleMuted"></media-hotkey>
+    <media-hotkey keys="f" action="toggleFullscreen"></media-hotkey>
+    <media-hotkey keys="c" action="toggleSubtitles"></media-hotkey>
+    <media-hotkey keys="i" action="togglePictureInPicture"></media-hotkey>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.html-status-indicator-basic {
+  position: relative;
+}
+
+.html-status-indicator-basic:focus-visible {
+  outline: 3px solid #60a5fa;
+  outline-offset: 2px;
+}
+
+.html-status-indicator-basic video {
+  display: block;
+  width: 100%;
+}
+
+.html-status-indicator-basic__instructions {
+  position: absolute;
+  top: 10px;
+  right: 10px;
+  left: 10px;
+  padding: 6px 10px;
+  margin: 0;
+  color: white;
+  text-align: center;
+  background: rgb(0 0 0 / 70%);
+  border-radius: 4px;
+}
+
+.html-status-indicator-basic__indicator {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  display: grid;
+  min-width: 92px;
+  padding: 16px;
+  color: white;
+  pointer-events: none;
+  background: rgb(0 0 0 / 72%);
+  border-radius: 12px;
+  place-items: center;
+  transform: translate(-50%, -50%);
+  transition:
+    opacity 160ms ease-in-out,
+    scale 160ms ease-in-out;
+}
+
+.html-status-indicator-basic__indicator::before {
+  font-size: 28px;
+  font-weight: 700;
+  line-height: 1;
+}
+
+.html-status-indicator-basic__indicator[data-status="play"]::before {
+  content: "▶";
+}
+
+.html-status-indicator-basic__indicator[data-status="pause"]::before {
+  content: "Ⅱ";
+}
+
+.html-status-indicator-basic__indicator[data-status="volume-off"]::before {
+  content: "🔇";
+}
+
+.html-status-indicator-basic__indicator[data-status="volume-low"]::before {
+  content: "🔉";
+}
+
+.html-status-indicator-basic__indicator[data-status="volume-high"]::before {
+  content: "🔊";
+}
+
+.html-status-indicator-basic__indicator[data-status="captions-on"]::before,
+.html-status-indicator-basic__indicator[data-status="captions-off"]::before {
+  content: "CC";
+}
+
+.html-status-indicator-basic__indicator[data-status="captions-off"]::before {
+  text-decoration: line-through;
+}
+
+.html-status-indicator-basic__indicator[data-status="fullscreen"]::before {
+  content: "⛶";
+}
+
+.html-status-indicator-basic__indicator[data-status="exit-fullscreen"]::before {
+  content: "⊠";
+}
+
+.html-status-indicator-basic__indicator[data-status="pip"]::before,
+.html-status-indicator-basic__indicator[data-status="exit-pip"]::before {
+  content: "▣";
+}
+
+.html-status-indicator-basic__indicator[data-status="exit-pip"]::before {
+  text-decoration: line-through;
+}
+
+.html-status-indicator-basic__indicator[data-starting-style],
+.html-status-indicator-basic__indicator[data-ending-style] {
+  opacity: 0;
+  scale: 0.85;
+}
+
+.html-status-indicator-basic__value {
+  margin-top: 8px;
+  font-variant-numeric: tabular-nums;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/hotkey';
+import '@videojs/html/ui/status-indicator';
+import '@videojs/html/ui/status-indicator-value';
+```
+
+## API Reference
+
+### media-status-indicator
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `actions` | `readonly InputAction[]` | — | Input actions allowed to open the indicator. All supported actions are allowed when omitted. |
+| `closeDelay` (attribute `close-delay`) | `number` | — | Delay in milliseconds before the indicator closes. |
+
+#### State
+
+State is reflected as data attributes for CSS styling.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
+| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
+| `open` | `boolean` | Whether the indicator is open. |
+| `generation` | `number` | Increments each time a supported input action updates the indicator. |
+| `status` | `ReturnType<typeof deriveStatus> extends infer Details ? Details extends { status: infer Status } ? Status \| null : never : never` | Predicted visual status for the handled input action. |
+| `label` | `string \| null` | Translated label for the predicted status. |
+| `value` | `string \| null` | Predicted volume percentage for volume actions, otherwise `null`. |
+
+#### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present while the indicator is open. |
+| `data-status` | `ReturnType<typeof deriveStatus> extends infer Details ? Details extends { status: infer Status } ? Status \| null : never : never` | Predicted visual status for the handled input action. |
+| `data-starting-style` | — | Present during the open transition. |
+| `data-ending-style` | — | Present during the close transition. |
+
+### media-status-indicator-value