@videojs/html 10.0.0-beta.23 → 10.0.0-beta.24

package/docs/reference/time.md

@@ -0,0 +1,488 @@
+# media-time
+
+Time display components for showing current time, duration, and remaining time in a video player
+
+## Anatomy
+
+html
+
+```
+<media-time-group>
+  <media-time type="current"></media-time>
+  <media-time-separator></media-time-separator>
+  <media-time type="duration"></media-time>
+</media-time-group>
+```
+
+## Behavior
+
+Three display types — `current`, `duration`, and `remaining` — in digital format with smart padding:
+
+*   **Hours** are never padded (`1:05:30`, not `01:05:30`)
+*   **Minutes** are padded when hours are shown (`1:05:30`, but `5:30`)
+*   **Seconds** are always padded (`1:05`, not `1:5`)
+
+Hour display is triggered when either the current value or the duration exceeds 1 hour, ensuring consistency within a Group. Remaining time displays a negative sign (customizable via the `negativeSign` prop).
+
+## Styling
+
+The negative sign is rendered inside `<span aria-hidden="true">` and can be hidden with CSS:
+
+css
+
+```
+[data-type="remaining"] > span[aria-hidden] {
+  display: none;
+}
+```
+
+## Accessibility
+
+Each `<media-time>` has:
+
+*   `aria-label` for the static role label (“Current time”, “Duration”, “Remaining”)
+*   `aria-valuetext` for the dynamic human-readable time (“1 minute, 30 seconds”)
+
+No `aria-live` region is used — time updates too frequently and might overwhelm screen readers. The separator is `aria-hidden="true"` since screen readers already hear each time value separately. The negative sign is also `aria-hidden` because `aria-valuetext` already conveys “remaining”. In React, `<time datetime>` provides machine-readable time for parsers.
+
+## Examples
+
+### Current Time
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<video-player class="video-player">
+    <media-container>
+        <video
+            src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+            autoplay
+            muted
+            playsinline
+            loop
+        ></video>
+        <media-time class="media-time" type="current"></media-time>
+    </media-container>
+</video-player>
+```
+```
+.video-player {
+  position: relative;
+}
+
+.video-player video {
+  width: 100%;
+}
+
+.media-time {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  font-variant-numeric: tabular-nums;
+  color: black;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/ui/time';
+```
+
+### Current / Duration
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<video-player class="video-player">
+    <media-container>
+        <video
+            src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+            autoplay
+            muted
+            playsinline
+            loop
+        ></video>
+        <media-time-group class="time-group">
+            <media-time type="current"></media-time>
+            <media-time-separator></media-time-separator>
+            <media-time type="duration"></media-time>
+        </media-time-group>
+    </media-container>
+</video-player>
+```
+```
+.video-player {
+  position: relative;
+}
+
+.video-player video {
+  width: 100%;
+}
+
+.time-group {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  display: flex;
+  gap: 4px;
+  align-items: center;
+  padding-block: 8px;
+  padding-inline: 20px;
+  font-variant-numeric: tabular-nums;
+  color: black;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/ui/time';
+```
+
+### Remaining
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<video-player class="video-player">
+    <media-container>
+        <video
+            src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+            autoplay
+            muted
+            playsinline
+            loop
+        ></video>
+        <media-time class="media-time" type="remaining"></media-time>
+    </media-container>
+</video-player>
+```
+```
+.video-player {
+  position: relative;
+}
+
+.video-player video {
+  width: 100%;
+}
+
+.media-time {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  font-variant-numeric: tabular-nums;
+  color: black;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/ui/time';
+```
+
+### Custom Separator
+
+of
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<video-player class="video-player">
+    <media-container>
+        <video
+            src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+            autoplay
+            muted
+            playsinline
+            loop
+        ></video>
+        <media-time-group class="time-group">
+            <media-time type="current"></media-time>
+            <media-time-separator> of </media-time-separator>
+            <media-time type="duration"></media-time>
+        </media-time-group>
+    </media-container>
+</video-player>
+```
+```
+.video-player {
+  position: relative;
+}
+
+.video-player video {
+  width: 100%;
+}
+
+.time-group {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  display: flex;
+  gap: 4px;
+  align-items: center;
+  padding-block: 8px;
+  padding-inline: 20px;
+  font-variant-numeric: tabular-nums;
+  color: black;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/ui/time';
+```
+
+### Custom Negative Sign
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<video-player class="video-player">
+    <media-container>
+        <video
+            src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+            autoplay
+            muted
+            playsinline
+            loop
+        ></video>
+        <media-time
+            class="media-time"
+            type="remaining"
+            negative-sign="~"
+            ></media-time>
+    </media-container>
+</video-player>
+```
+```
+.video-player {
+  position: relative;
+}
+
+.video-player video {
+  width: 100%;
+}
+
+.media-time {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  font-variant-numeric: tabular-nums;
+  color: black;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/ui/time';
+```
+
+## API Reference
+
+### 
+
+media-time
+
+Displays a formatted time value (current, duration, or remaining).
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`label`
+
+`string | function`
+
+`''`
+
+▸
+
+Attribute
+
+`label`
+
+Description
+
+Custom label for accessibility.
+
+Type
+
+`string | ((state: TimeState) => string)`
+
+`negativeSign`
+
+`string`
+
+`'-'`
+
+▸
+
+Attribute
+
+`negative-sign`
+
+Description
+
+Symbol prepended to remaining time.
+
+`type`
+
+`'current' | 'duration' | 'remaining'`
+
+`'current'`
+
+▸
+
+Attribute
+
+`type`
+
+Description
+
+Which time value to display.
+
+#### State
+
+State is reflected as data attributes for CSS styling.
+
+Property
+
+Type
+
+Details
+
+`type`
+
+`'current' | 'duration' | 'remaining'`
+
+▸
+
+Description
+
+Time display type.
+
+`seconds`
+
+`number`
+
+▸
+
+Description
+
+Raw value in seconds.
+
+`negative`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the time value is negative (remaining time before end).
+
+`text`
+
+`string`
+
+▸
+
+Description
+
+Formatted display text without sign (e.g., "1:30").
+
+`phrase`
+
+`string`
+
+▸
+
+Description
+
+Human-readable phrase (e.g., "1 minute, 30 seconds").
+
+`datetime`
+
+`string`
+
+▸
+
+Description
+
+ISO 8601 duration (e.g., "PT1M30S").
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-type`
+
+`'current' | 'duration' | 'remaining'`
+
+▸
+
+Description
+
+The type of time being displayed.
+
+### 
+
+media-time-group
+
+Container for composed time displays. Renders a `<span>` element.
+
+### 
+
+media-time-separator
+
+Divider between time values. Hidden from screen readers.