@design-edito/tools 0.5.14 → 0.5.16

package/agnostic/time/dates/format-date/types.d.ts

@@ -1,21 +1,21 @@
 /** Every token `formatDate` substitutes in a template. */
-export type DateToken = 'D' | 'DD' | 'd' | 'dd' | 'M' | 'MM' | 'MMM' | 'MMMM' | 'YY' | 'YYYY' | 'H' | 'HH' | 'h' | 'hh' | 'm' | 'mm' | 's' | 'ss' | 'ms' | 'A' | 'a' | 'th';
+export type DateToken = 'D' | 'DD' | 'd' | 'dd' | 'ddd' | 'dddd' | 'M' | 'MM' | 'MMM' | 'MMMM' | 'YY' | 'YYYY' | 'H' | 'HH' | 'h' | 'hh' | 'm' | 'mm' | 's' | 'ss' | 'ms' | 'A' | 'a' | 'th';
 /**
  * A date's parts, keyed by unit token.
  *
  * Quantities are **numbers** — a day of month is `1`, not `'01'`. Padding and
  * truncation are rendering concerns and belong to `formatDate`, which is why the
- * `DD`, `MM`, `YY`, `HH`, `hh`, `mm` and `ss` tokens have no entry here: they
- * render the same quantity as their unpadded twin. The parts that are localised
- * text rather than a quantity stay strings.
+ * `d`, `dd`, `DD`, `MM`, `YY`, `HH`, `hh`, `mm` and `ss` tokens have no entry
+ * here: they render the same quantity as the bare token they double. The parts
+ * that are localised text rather than a quantity stay strings.
  */
 export type DateTokenParts = {
-    /** Day of month, 1–31. */
+    /** Day of month, 1–31. Rendered by `D`, `DD`, `d` and `dd` alike. */
     D: number;
     /** Short weekday name, localised. */
-    d: string;
+    ddd: string;
     /** Full weekday name, localised. */
-    dd: string;
+    dddd: string;
     /** Month number, 1–12 — January is `1`, not `0`. */
     M: number;
     /** Short month name, localised. */
@@ -51,9 +51,9 @@ export type DateTokenParts = {
 export type NamedDateParts = {
     /** {@link DateTokenParts.D} */
     dayOfMonth: number;
-    /** {@link DateTokenParts.d} */
+    /** {@link DateTokenParts.ddd} */
     shortWeekdayName: string;
-    /** {@link DateTokenParts.dd} */
+    /** {@link DateTokenParts.dddd} */
     fullWeekdayName: string;
     /** {@link DateTokenParts.M} */
     monthNumber: number;

package/agnostic/time/duration/format-duration/index.d.ts

@@ -19,14 +19,31 @@ import type { FormatDurationOptions } from './types.js';
  * - `m` / `mm` : Minutes
  * - `s` / `ss` : Seconds
  * - `ms` : Milliseconds, padded to three digits
+ * - `f` / `ff` : The millisecond part counted in frames, at `options.fps`
  *
  * @param duration - The duration to format, as a {@link Duration} or a number of
  * milliseconds.
  * @param format - The template string containing tokens.
- * @param options - How to handle the remainder and the month/year approximation.
+ * @param options - How to handle the remainder, the month/year approximation and
+ * the frame rate.
  * @returns Formatted duration string. An unknown token is left untouched, braces
  * included.
  * @see {@link getDurationParts} to reach the same parts as plain values.
+ * @see {@link formatDate} — the same template grammar, for a point in time rather
+ * than a length of it.
+ *
+ * @remarks
+ * This function and `formatDate` share one grammar: `{{…}}` delimiters, everything
+ * outside them literal, the bare token being the plain number and the doubled one
+ * that same number padded to two digits, `ms` padded to three, and an unknown token
+ * left as written. No token means two different kinds of thing across the two.
+ *
+ * @remarks
+ * **The template decides the breakdown, so nothing is ever lost for not having been
+ * asked for.** `'{{w}}w {{h}}h'` counts hours up to 167 because the week is there and
+ * the day is not; `'{{mm}}:{{ss}}'` on an hour-long video reads `62:05` rather than
+ * dropping the hour. The single-unit case follows from the same rule: `'{{s}}s'`
+ * carries the whole duration.
  *
  * @remarks
  * A negative duration yields negative parts, so every token renders a signed

package/agnostic/time/duration/format-duration/index.js

@@ -1,8 +1,14 @@
 import { getDurationParts } from './parts.js';
 // Alternation is ordered, and the first branch that fits wins — so the longest
 // tokens come first. `m` ahead of `ms` or `mm` would swallow them.
-const tokenRegexp = /\{\{(YY|MM|ww|dd|hh|mm|ss|ms|Y|M|w|d|h|m|s)\}\}/gv;
-/** Which tokens read which unit, longest unit first. */
+const tokenRegexp = /\{\{(YY|MM|ww|dd|hh|mm|ss|ms|ff|Y|M|w|d|h|m|s|f)\}\}/gv;
+/**
+ * Which tokens read which unit, longest unit first.
+ *
+ * `f` and `ff` sit under `ms` rather than under a unit of their own: a frame is
+ * the millisecond part counted in another base, so a template asking for frames
+ * is a template asking the cascade to run down to milliseconds.
+ */
 const unitTokens = [
     ['Y', ['Y', 'YY']],
     ['M', ['M', 'MM']],
@@ -11,7 +17,7 @@ const unitTokens = [
     ['h', ['h', 'hh']],
     ['m', ['m', 'mm']],
     ['s', ['s', 'ss']],
-    ['ms', ['ms']]
+    ['ms', ['ms', 'f', 'ff']]
 ];
 function pad(value, length) {
     return `${value}`.padStart(length, '0');
@@ -36,8 +42,22 @@ const renderers = {
     'mm': parts => pad(parts.m, 2),
     's': parts => `${parts.s}`,
     'ss': parts => pad(parts.s, 2),
-    'ms': parts => pad(parts.ms, 3)
+    'ms': parts => pad(parts.ms, 3),
+    'f': (parts, fps) => `${toFrames(parts.ms, fps)}`,
+    'ff': (parts, fps) => pad(toFrames(parts.ms, fps), 2)
 };
+/**
+ * The millisecond part counted in frames.
+ *
+ * Truncated rather than rounded: a frame is only reached once it has fully
+ * elapsed, so 39 ms at 25 fps is frame `0`, not frame `1`. The sign is carried
+ * around the truncation, so a negative part stays negative — the whole function
+ * keeps a duration's parts faithful rather than tidying them.
+ */
+function toFrames(ms, fps) {
+    const sign = ms < 0 ? -1 : 1;
+    return Math.floor(Math.abs(ms) / 1000 * fps) * sign;
+}
 /** The units a template asks for, read off the tokens it actually uses. */
 function unitsInFormat(format) {
     return unitTokens
@@ -63,14 +83,31 @@ function unitsInFormat(format) {
  * - `m` / `mm` : Minutes
  * - `s` / `ss` : Seconds
  * - `ms` : Milliseconds, padded to three digits
+ * - `f` / `ff` : The millisecond part counted in frames, at `options.fps`
  *
  * @param duration - The duration to format, as a {@link Duration} or a number of
  * milliseconds.
  * @param format - The template string containing tokens.
- * @param options - How to handle the remainder and the month/year approximation.
+ * @param options - How to handle the remainder, the month/year approximation and
+ * the frame rate.
  * @returns Formatted duration string. An unknown token is left untouched, braces
  * included.
  * @see {@link getDurationParts} to reach the same parts as plain values.
+ * @see {@link formatDate} — the same template grammar, for a point in time rather
+ * than a length of it.
+ *
+ * @remarks
+ * This function and `formatDate` share one grammar: `{{…}}` delimiters, everything
+ * outside them literal, the bare token being the plain number and the doubled one
+ * that same number padded to two digits, `ms` padded to three, and an unknown token
+ * left as written. No token means two different kinds of thing across the two.
+ *
+ * @remarks
+ * **The template decides the breakdown, so nothing is ever lost for not having been
+ * asked for.** `'{{w}}w {{h}}h'` counts hours up to 167 because the week is there and
+ * the day is not; `'{{mm}}:{{ss}}'` on an hour-long video reads `62:05` rather than
+ * dropping the hour. The single-unit case follows from the same rule: `'{{s}}s'`
+ * carries the whole duration.
  *
  * @remarks
  * A negative duration yields negative parts, so every token renders a signed
@@ -84,11 +121,11 @@ function unitsInFormat(format) {
  * // => "1:02:05"
  */
 export function formatDuration(duration, format, options = {}) {
-    const { floorSmallestUnit = true, useApproximateMonthAndYear = true } = options;
+    const { floorSmallestUnit = true, useApproximateMonthAndYear = true, fps = 25 } = options;
     const parts = getDurationParts(duration, {
         units: unitsInFormat(format),
         floorSmallestUnit,
         useApproximateMonthAndYear
     });
-    return format.replace(tokenRegexp, (_match, token) => renderers[token](parts));
+    return format.replace(tokenRegexp, (_match, token) => renderers[token](parts, fps));
 }

package/agnostic/time/duration/format-duration/index.test.js

@@ -53,6 +53,33 @@ describe('formatDuration', () => {
             expect(formatDuration(seconds(-90), '{{m}}:{{ss}}')).toBe('-1:-30');
         });
     });
+    describe('frames', () => {
+        it('counts the sub-second remainder in frames, at 25 fps by default', () => {
+            expect(formatDuration(3725240, '{{mm}}:{{ss}}.{{ff}}')).toBe('62:05.06');
+            expect(formatDuration(3725240, '{{mm}}:{{ss}}.{{f}}')).toBe('62:05.6');
+        });
+        it('counts in the frame rate it is given', () => {
+            expect(formatDuration(3725240, '{{ss}}.{{ff}}', { fps: 50 })).toBe('3725.12');
+        });
+        // A frame is reached once it has fully elapsed, so the 40th millisecond is
+        // where frame 1 starts at 25 fps — not the 39th.
+        it('truncates rather than rounds to the frame', () => {
+            expect(formatDuration(39, '{{s}}.{{ff}}')).toBe('0.00');
+            expect(formatDuration(40, '{{s}}.{{ff}}')).toBe('0.01');
+        });
+        // Frames are milliseconds in another base, so they pull the cascade down to
+        // milliseconds exactly as `{{ms}}` would — without needing `{{ms}}` written.
+        it('runs the cascade down to milliseconds without a ms token', () => {
+            expect(formatDuration(3725240, '{{ss}}')).toBe('3725');
+            expect(formatDuration(3725240, '{{ss}}.{{ff}}')).toBe('3725.06');
+        });
+        it('puts the whole duration on frames when it is the only token', () => {
+            expect(formatDuration(seconds(2), '{{f}}')).toBe('50');
+        });
+        it('signs a frame count like every other part', () => {
+            expect(formatDuration(-240, '{{s}}.{{f}}')).toBe('0.-6');
+        });
+    });
 });
 describe('getDurationParts', () => {
     describe('breakdown', () => {

package/agnostic/time/duration/format-duration/types.d.ts

@@ -4,7 +4,7 @@
  */
 export type DurationUnit = 'ms' | 's' | 'm' | 'h' | 'd' | 'w' | 'M' | 'Y';
 /** Every token `formatDuration` substitutes in a template. */
-export type DurationToken = 'Y' | 'YY' | 'M' | 'MM' | 'w' | 'ww' | 'd' | 'dd' | 'h' | 'hh' | 'm' | 'mm' | 's' | 'ss' | 'ms';
+export type DurationToken = 'Y' | 'YY' | 'M' | 'MM' | 'w' | 'ww' | 'd' | 'dd' | 'h' | 'hh' | 'm' | 'mm' | 's' | 'ss' | 'ms' | 'f' | 'ff';
 /** Options for `getDurationParts`. */
 export type GetDurationPartsOptions = {
     /**
@@ -25,6 +25,16 @@ export type GetDurationPartsOptions = {
      * 365.2425 days and a month of exactly a twelfth of it.
      */
     useApproximateMonthAndYear?: boolean;
+    /**
+     * Frame rate the `f` and `ff` tokens count in. Defaults to `25`.
+     *
+     * Frames are a *rendering* of the millisecond part, not a unit of their own —
+     * they never appear in {@link DurationParts}, and a template asking for them
+     * asks for milliseconds under another base. So `'{{ss}}.{{ff}}'` reads the
+     * sub-second remainder, while `'{{f}}'` alone puts the whole duration on
+     * frames, exactly as `'{{ms}}'` alone puts it on milliseconds.
+     */
+    fps?: number;
 };
 /**
  * A duration's parts, keyed by unit token.
@@ -90,4 +100,14 @@ export type FormatDurationOptions = {
      * 365.2425 days and a month of exactly a twelfth of it.
      */
     useApproximateMonthAndYear?: boolean;
+    /**
+     * Frame rate the `f` and `ff` tokens count in. Defaults to `25`.
+     *
+     * Frames are a *rendering* of the millisecond part, not a unit of their own —
+     * they never appear in {@link DurationParts}, and a template asking for them
+     * asks for milliseconds under another base. So `'{{ss}}.{{ff}}'` reads the
+     * sub-second remainder, while `'{{f}}'` alone puts the whole duration on
+     * frames, exactly as `'{{ms}}'` alone puts it on milliseconds.
+     */
+    fps?: number;
 };

package/agnostic/time/index.d.ts

@@ -1,5 +1,5 @@
 export * as dates from './dates/index.js'
 export * as duration from './duration/index.js'
 export * as timeout from './timeout/index.js'
-export * as wait from './wait/index.js'
 export * as transitions from './transitions/index.js'
+export * as wait from './wait/index.js'

package/agnostic/time/index.js

@@ -1,5 +1,5 @@
 export * as dates from './dates/index.js'
 export * as duration from './duration/index.js'
 export * as timeout from './timeout/index.js'
-export * as wait from './wait/index.js'
 export * as transitions from './transitions/index.js'
+export * as wait from './wait/index.js'

package/components/Video/index.controlled.d.ts

@@ -66,6 +66,8 @@ type TrackData = {
  * the component reacts, with the target and current rates.
  * @property onFullscreenButtonClicked - Called when the fullscreen button is
  * clicked, before the component reacts, with the fullscreen state as it was.
+ * @property onSubtitlesButtonClicked - Called when the subtitles button is clicked,
+ * before the component reacts, with the subtitles state as it was.
  * @property onTimelineClicked - Called when the timeline is clicked, before the
  * component reacts, with the target and current times (in seconds). The component
  * seeks to the target right after, unless the time is controlled.
@@ -77,6 +79,8 @@ type TrackData = {
  * @property onIsEndedChanged - Called after playback reached the end, and again
  * once it left it — a seek back or a new play. Never on mount.
  * @property onIsLoudChanged - Called once the mute state has changed (`true` = unmuted).
+ * @property onIsSubtitlesOnChanged - Called once the subtitles have been shown or
+ * hidden. Never on mount.
  * @property onVolumeChanged - Called once the volume has changed (`0` to `1`).
  * @property onPlaybackRateChanged - Called once the playback rate has changed.
  * @property onCurrentTimeMsChanged - Called once the current time has changed, in
@@ -85,12 +89,24 @@ type TrackData = {
  * fullscreen on its own — pressing Escape, typically — with the new state. This is
  * the signal a parent needs to update its `fullscreen` prop, and it is distinct
  * from `onIsFullscreenChanged`, which merely echoes that prop back once changed.
- * @property timeFormat - How the two clocks are written, as a {@link formatTime}
+ * @property timeFormat - How the two clocks are written, as a {@link formatDuration}
  * pattern. Tokens go in `{{…}}` and the rest is literal, so `'{{m}} min {{ss}}'` is a
  * valid answer. Defaults to `'{{mm}}:{{ss}}:{{ms}}'` — milliseconds included, which is
  * what a cutting room wants and almost never what an article does: `'{{mm}}:{{ss}}'` is
- * the usual one. Frames (`{{frame}}`, `{{f}}`) are derived at 25 fps, not configurable
+ * the usual one. Frames (`{{f}}`, `{{ff}}`) are derived at 25 fps, not configurable
  * here.
+ *
+ * The pattern decides how the duration is split: the units it names are the units it
+ * gets, each taking its whole part and handing the rest down. So `'{{mm}}:{{ss}}'` on
+ * an hour-long video reads `62:05` rather than dropping the hour — nothing is ever
+ * lost for not having been asked for.
+ * @property subtitlesBtnContent - Glyph for the subtitles button, like the five other
+ * button contents. The button renders only when `subtitles` is set: with no cues there
+ * is nothing to toggle, and unlike `Disclaimer`'s missing toggler this withholds no
+ * behaviour — a stylesheet has nothing it could do with it either.
+ * @property subtitlesOn - Whether the subtitles show. Controlled: the component never
+ * changes it, it reports a click through `onSubtitlesButtonClicked` and leaves the
+ * decision to the parent. `Video` holds it for you.
  * @property className - Additional CSS class for the root element.
  * @property children - React content inserted into the <video> tag (fallback, etc).
  *
@@ -105,7 +121,9 @@ export type Props = PropsWithChildren<WithClassName<{
     loudBtnContent?: React.ReactNode;
     muteBtnContent?: React.ReactNode;
     fullscreenBtnContent?: React.ReactNode;
+    subtitlesBtnContent?: React.ReactNode;
     play?: boolean;
+    subtitlesOn?: boolean;
     fullscreen?: boolean;
     volume?: number;
     mute?: boolean;
@@ -119,10 +137,12 @@ export type Props = PropsWithChildren<WithClassName<{
     onVolumeRangeChanged?: (e: React.ChangeEvent<HTMLInputElement>, targetVolume: number, currentVolume: number, video: HTMLVideoElement | null) => void;
     onRateRangeChanged?: (e: React.ChangeEvent<HTMLInputElement>, targetRate: number, currentRate: number, video: HTMLVideoElement | null) => void;
     onFullscreenButtonClicked?: (e: React.MouseEvent<HTMLButtonElement>, isFullscreen: boolean, video: HTMLVideoElement | null) => void;
+    onSubtitlesButtonClicked?: (e: React.MouseEvent<HTMLButtonElement>, isSubtitlesOn: boolean, video: HTMLVideoElement | null) => void;
     onTimelineClicked?: (e: React.MouseEvent<HTMLDivElement>, targetTime: number, currentTime: number, video: HTMLVideoElement | null) => void;
     onIsPlayingChanged?: (isPlaying: boolean) => void;
     onIsFullscreenChanged?: (isFullscreen: boolean) => void;
     onIsLoudChanged?: (isLoud: boolean) => void;
+    onIsSubtitlesOnChanged?: (isSubtitlesOn: boolean) => void;
     onIsEndedChanged?: (isEnded: boolean) => void;
     onVolumeChanged?: (volume: number) => void;
     onPlaybackRateChanged?: (playbackRate: number) => void;

package/components/Video/index.controlled.js

@@ -1,11 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useRef, useState, useCallback, useEffect } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
+import { formatDuration } from '../../agnostic/time/duration/format-duration/index.js';
 import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import cssModule from './styles.module.css';
 import { video as publicClassName } from '../public-classnames.js';
 import { Subtitles } from '../Subtitles/index.js';
-import { forceExitFullscreen, forceFullscreen, forceLoud, forceMute, forcePause, forcePlay, forcePlaybackRate, forceVolume, formatTime, getTimelineClickProgress, msToSeconds, secondsToMs } from './utils.js';
+import { forceExitFullscreen, forceFullscreen, forceLoud, forceMute, forcePause, forcePlay, forcePlaybackRate, forceVolume, getTimelineClickProgress, msToSeconds, secondsToMs } from './utils.js';
 /**
  * Full-featured video player component. Wraps a native `<video>` element with
  * playback controls, volume, playback rate, a timeline, optional subtitles
@@ -49,11 +50,14 @@ import { forceExitFullscreen, forceFullscreen, forceLoud, forceMute, forcePause,
  * @returns A `<figure>` element containing the video, its controls, optional
  * subtitles.
  */
-export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pauseBtnContent, loudBtnContent, muteBtnContent, fullscreenBtnContent, play, fullscreen, mute, muted, volume = 1, playbackRate = 1, currentTimeMs: givenCurrentTimeMs, 
+export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pauseBtnContent, loudBtnContent, muteBtnContent, fullscreenBtnContent, subtitlesBtnContent, play, fullscreen, 
+// Les sous-titres sont montrés tant que personne n'a dit le contraire : un article qui
+// en fournit veut qu'on les lise.
+subtitlesOn = true, mute, muted, volume = 1, playbackRate = 1, currentTimeMs: givenCurrentTimeMs, 
 // Milliseconds by default, which is what this component has always rendered — a
 // default that changes under a consumer is a change nobody asked for. An article
 // usually wants `'{{mm}}:{{ss}}'` and says so.
-timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, onTimelineClicked, onIsPlayingChanged, onIsFullscreenChanged, onIsLoudChanged, onIsEndedChanged, onVolumeChanged, onPlaybackRateChanged, onCurrentTimeMsChanged, onFullscreenChange, children, className, ...intrinsicVideoAttributes }) => {
+timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, onSubtitlesButtonClicked, onTimelineClicked, onIsPlayingChanged, onIsFullscreenChanged, onIsLoudChanged, onIsSubtitlesOnChanged, onIsEndedChanged, onVolumeChanged, onPlaybackRateChanged, onCurrentTimeMsChanged, onFullscreenChange, children, className, ...intrinsicVideoAttributes }) => {
     const videoRef = useRef(null);
     const [totalTime, setTotalTime] = useState(0);
     const totalTimeMs = useMemo(() => secondsToMs(totalTime), [totalTime]);
@@ -130,6 +134,9 @@ timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked,
     const handleFullscreenButtonClick = useCallback((e) => {
         onFullscreenButtonClicked?.(e, isFullscreen, videoRef.current);
     }, [onFullscreenButtonClicked, isFullscreen]);
+    const handleSubtitlesButtonClick = useCallback((e) => {
+        onSubtitlesButtonClicked?.(e, subtitlesOn, videoRef.current);
+    }, [onSubtitlesButtonClicked, subtitlesOn]);
     const handleVolumeRangeChange = useCallback((e) => {
         const targetVolume = Number(e.currentTarget.value) / 100;
         onVolumeRangeChanged?.(e, targetVolume, volume, videoRef.current);
@@ -158,7 +165,12 @@ timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked,
         'fullscreen-on': isFullscreen,
         'fullscreen-off': !isFullscreen,
         'loud': isLoud,
-        'muted': !isLoud
+        'muted': !isLoud,
+        // Rien des deux quand aucun sous-titre n'est fourni : l'absence n'est pas un état
+        // caché, c'est l'absence d'un état. Une feuille qui veut viser ce cas le reconnaît à
+        // ce qu'aucun des deux modifieurs n'est là.
+        'subtitles-on': subtitles !== undefined && subtitlesOn,
+        'subtitles-off': subtitles !== undefined && !subtitlesOn
     }), className);
     // Guarded: the duration is unknown until the metadata lands, and an unguarded
     // division would expose the string 'NaN' on every render until then.
@@ -171,6 +183,8 @@ timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked,
         'data-fullscreen-off': !isFullscreen ? '' : undefined,
         'data-loud': isLoud ? '' : undefined,
         'data-muted': !isLoud ? '' : undefined,
+        'data-subtitles-on': subtitles !== undefined && subtitlesOn ? '' : undefined,
+        'data-subtitles-off': subtitles !== undefined && !subtitlesOn ? '' : undefined,
         'data-volume': volume.toFixed(8),
         'data-volume-percent': volumePercent,
         'data-playback-rate': playbackRate,
@@ -227,6 +241,7 @@ timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked,
     const muteBtnClss = c('mute-btn');
     const volumePcntClss = c('volume-percent');
     const fullscreenBtnClss = c('fullscreen-btn');
+    const subtitlesBtnClss = c('subtitles-btn');
     const volumeRangeClss = c('volume-range');
     const playbackRateRangeClss = c('playback-rate-range');
     const playbackRateClss = c('playback-rate');
@@ -299,6 +314,7 @@ timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked,
     useChangeDispatch(isElementPlaying, onIsPlayingChanged);
     useChangeDispatch(isFullscreen, onIsFullscreenChanged);
     useChangeDispatch(isLoud, onIsLoudChanged);
+    useChangeDispatch(subtitlesOn, onIsSubtitlesOnChanged);
     useChangeDispatch(isEnded, onIsEndedChanged);
     useChangeDispatch(volume, onVolumeChanged);
     useChangeDispatch(playbackRate, onPlaybackRateChanged);
@@ -306,5 +322,5 @@ timeFormat = '{{mm}}:{{ss}}:{{ms}}', onPlayButtonClicked, onPauseButtonClicked,
                         ? _jsx("source", { src: source }, index)
                         : _jsx("source", { src: source.src, type: source.type }, index)), parsedTracks.map((track, index) => typeof track === 'string'
                         ? _jsx("track", { src: track }, index)
-                        : _jsx("track", { src: track.src, kind: track.kind, srcLang: track.srclang, label: track.label, default: track.default }, index)), children] }), _jsxs("div", { className: videoControlsClss, children: [_jsx("button", { className: playBtnClss, onClick: handlePlayButtonClick, children: playBtnContent }), _jsx("button", { className: pauseBtnClss, onClick: handlePauseButtonClick, children: pauseBtnContent }), _jsx("button", { className: loudBtnClss, onClick: handleLoudButtonClick, children: loudBtnContent }), _jsx("button", { className: muteBtnClss, onClick: handleMuteButtonClick, children: muteBtnContent }), _jsx("input", { type: 'range', className: volumeRangeClss, value: volumePercent, onChange: handleVolumeRangeChange, min: 0, max: 100, step: 1 }), _jsx("span", { className: volumePcntClss, children: Math.round(volumePercent) }), _jsx("button", { className: fullscreenBtnClss, onClick: handleFullscreenButtonClick, children: fullscreenBtnContent }), _jsx("input", { type: 'range', className: playbackRateRangeClss, value: playbackRate, onChange: handleRateRangeChange, min: 0.25, max: 4, step: 0.25 }), _jsx("span", { className: playbackRateClss, children: playbackRate })] }), _jsxs("div", { className: timeControlsClss, children: [_jsx("span", { className: currentTimeClss, children: formatTime(currentTimeMs, timeFormat) }), _jsx("span", { className: totalTimeClss, children: formatTime(totalTimeMs, timeFormat) }), _jsx("div", { className: timelineClss, onClick: handleTimelineClick })] }), subtitles !== undefined && _jsx(Subtitles, { ...subtitles, timecodeMs: currentTimeMs, isEnded: isEnded })] });
+                        : _jsx("track", { src: track.src, kind: track.kind, srcLang: track.srclang, label: track.label, default: track.default }, index)), children] }), _jsxs("div", { className: videoControlsClss, children: [_jsx("button", { className: playBtnClss, onClick: handlePlayButtonClick, children: playBtnContent }), _jsx("button", { className: pauseBtnClss, onClick: handlePauseButtonClick, children: pauseBtnContent }), _jsx("button", { className: loudBtnClss, onClick: handleLoudButtonClick, children: loudBtnContent }), _jsx("button", { className: muteBtnClss, onClick: handleMuteButtonClick, children: muteBtnContent }), _jsx("input", { type: 'range', className: volumeRangeClss, value: volumePercent, onChange: handleVolumeRangeChange, min: 0, max: 100, step: 1 }), _jsx("span", { className: volumePcntClss, children: Math.round(volumePercent) }), _jsx("button", { className: fullscreenBtnClss, onClick: handleFullscreenButtonClick, children: fullscreenBtnContent }), subtitles !== undefined && _jsx("button", { className: subtitlesBtnClss, onClick: handleSubtitlesButtonClick, children: subtitlesBtnContent }), _jsx("input", { type: 'range', className: playbackRateRangeClss, value: playbackRate, onChange: handleRateRangeChange, min: 0.25, max: 4, step: 0.25 }), _jsx("span", { className: playbackRateClss, children: playbackRate })] }), _jsxs("div", { className: timeControlsClss, children: [_jsx("span", { className: currentTimeClss, children: formatDuration(currentTimeMs, timeFormat) }), _jsx("span", { className: totalTimeClss, children: formatDuration(totalTimeMs, timeFormat) }), _jsx("div", { className: timelineClss, onClick: handleTimelineClick })] }), subtitles !== undefined && _jsx(Subtitles, { ...subtitles, timecodeMs: currentTimeMs, isEnded: isEnded })] });
 };

package/components/Video/index.d.ts

@@ -31,11 +31,16 @@ import { type Props as ControlledProps } from './index.controlled.js';
  * `autoPlay`, `autoPlayWhenVisible` and the play button have no effect for as
  * long as this prop is provided.
  * @property wrapperClassName - Optional additional class name(s) applied to the root wrapper element.
+ * @property defaultSubtitlesOn - Whether the subtitles start shown. `true` by default —
+ * an article that supplies cues means them to be read. The reader's button takes it from
+ * there, so this is a starting point and not a setting: `default…` and never `initial…`,
+ * as everywhere else here.
  * @property className - Optional additional class name(s) applied to the root element.
  * @property children - React children rendered inside the `<video>` element itself
  * (e.g. fallback content).
  */
-export type Props = WithViewportObservation<Omit<ControlledProps, 'play' | 'fullscreen' | 'volume' | 'mute' | 'playbackRate'>> & {
+export type Props = WithViewportObservation<Omit<ControlledProps, 'play' | 'fullscreen' | 'volume' | 'mute' | 'playbackRate' | 'subtitlesOn'>> & {
+    defaultSubtitlesOn?: boolean;
     autoPlayWhenVisible?: boolean;
     autoPlayOnceVisible?: boolean;
     autoPauseWhenHidden?: boolean;
@@ -73,6 +78,13 @@ export type Props = WithViewportObservation<Omit<ControlledProps, 'play' | 'full
  * automatic play the component still owed. Setting both flavours of the same
  * behaviour is the same as setting the `…When…` one alone.
  *
+ * **`loop` reaches the element untouched**, like every other native media attribute
+ * this component does not drive itself. It was once destructured out of the props and
+ * never forwarded, which silently dropped it — so if a native attribute ever stops
+ * arriving, look at the destructuring here before looking at the caller. One
+ * consequence worth knowing: a looping element never fires `ended`, so the `--ended`
+ * modifier and the `isEnded` it feeds to `Subtitles` simply never come.
+ *
  * Browsers refuse an unmuted `play()` outside a user gesture, so pairing an
  * `autoLoud…` with an `autoPlay…` will usually have the playback rejected. The
  * refusal is caught rather than ignored — the element is read back once the attempt

package/components/Video/index.js

@@ -34,6 +34,13 @@ import { ControlledVideo } from './index.controlled.js';
  * automatic play the component still owed. Setting both flavours of the same
  * behaviour is the same as setting the `…When…` one alone.
  *
+ * **`loop` reaches the element untouched**, like every other native media attribute
+ * this component does not drive itself. It was once destructured out of the props and
+ * never forwarded, which silently dropped it — so if a native attribute ever stops
+ * arriving, look at the destructuring here before looking at the caller. One
+ * consequence worth knowing: a looping element never fires `ended`, so the `--ended`
+ * modifier and the `isEnded` it feeds to `Subtitles` simply never come.
+ *
  * Browsers refuse an unmuted `play()` outside a user gesture, so pairing an
  * `autoLoud…` with an `autoPlay…` will usually have the playback rejected. The
  * refusal is caught rather than ignored — the element is read back once the attempt
@@ -41,13 +48,14 @@ import { ControlledVideo } from './index.controlled.js';
  * The media still won't play, though: autoplay muted, and leave unmuting to the
  * reader.
  */
-export const Video = ({ loop, autoPlayWhenVisible, autoPlayOnceVisible, autoPauseWhenHidden, autoPauseOnceHidden, autoMuteWhenHidden, autoMuteOnceHidden, autoLoudWhenVisible, autoLoudOnceVisible, threshold, root, rootMargin, onVisibilityChanged, wrapperClassName, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, ...controlledProps }) => {
+export const Video = ({ defaultSubtitlesOn = true, autoPlayWhenVisible, autoPlayOnceVisible, autoPauseWhenHidden, autoPauseOnceHidden, autoMuteWhenHidden, autoMuteOnceHidden, autoLoudWhenVisible, autoLoudOnceVisible, threshold, root, rootMargin, onVisibilityChanged, wrapperClassName, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, onSubtitlesButtonClicked, ...controlledProps }) => {
     // State & refs
     const [play, setPlay] = useState(false);
     const [volume, setVolume] = useState(1);
     const [mute, setMute] = useState(false);
     const [playbackRate, setPlaybackRate] = useState(1);
     const [fullscreen, setFullscreen] = useState(false);
+    const [subtitlesOn, setSubtitlesOn] = useState(defaultSubtitlesOn);
     // One flag per `…Once…` behaviour, and each is armed by that behaviour's own
     // automatic trigger. A single shared flag conflated four questions, and being set
     // on any `play` event — a user click included — meant the first press cancelled
@@ -143,6 +151,14 @@ export const Video = ({ loop, autoPlayWhenVisible, autoPlayOnceVisible, autoPaus
         onFullscreenButtonClicked?.(e, isFullscreen, video);
         setFullscreen(!isFullscreen);
     }, [onFullscreenButtonClicked]);
+    // Un seul bouton pour les deux sens, contrairement à lecture/pause et son/muet qui en
+    // ont un chacun : ceux-là existent en paire dans le DOM et la feuille en montre un,
+    // parce qu'ils portent deux glyphes opposés. Les sous-titres n'en portent qu'un, dont
+    // seul l'habillage change — inutile d'en rendre deux pour n'en montrer jamais qu'un.
+    const handleSubtitlesButtonClick = useCallback((e, isSubtitlesOn, video) => {
+        onSubtitlesButtonClicked?.(e, isSubtitlesOn, video);
+        setSubtitlesOn(!isSubtitlesOn);
+    }, [onSubtitlesButtonClicked]);
     // Intersection Observer
     const onIntersected = useCallback(({ ioEntry }) => {
         if (ioEntry === undefined)
@@ -188,7 +204,7 @@ export const Video = ({ loop, autoPlayWhenVisible, autoPlayOnceVisible, autoPaus
     // Render
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(), wrapperClassName);
-    const videoContent = _jsx(ControlledVideo, { ...controlledProps, play: play && !isTimeControlled, volume: volume, mute: mute, playbackRate: playbackRate, fullscreen: fullscreen, onPlay: handleOnPlayEvent, onPause: handleOnPauseEvent, onIsPlayingChanged: handleIsPlayingChanged, onVolumeChange: handleOnVolumeChangeEvent, onRateChange: handleOnRateChangeEvent, onLoadedMetadata: handleOnLoadedMetadataEvent, onFullscreenChange: handleFullscreenChange, onPlayButtonClicked: handlePlayButtonClick, onPauseButtonClicked: handlePauseButtonClick, onLoudButtonClicked: handleLoudButtonClick, onMuteButtonClicked: handleMuteButtonClick, onVolumeRangeChanged: handleVolumeRangeChange, onRateRangeChanged: handleRateRangeChange, onFullscreenButtonClicked: handleFullscreenButtonClick });
+    const videoContent = _jsx(ControlledVideo, { ...controlledProps, play: play && !isTimeControlled, volume: volume, mute: mute, playbackRate: playbackRate, fullscreen: fullscreen, subtitlesOn: subtitlesOn, onPlay: handleOnPlayEvent, onPause: handleOnPauseEvent, onIsPlayingChanged: handleIsPlayingChanged, onVolumeChange: handleOnVolumeChangeEvent, onRateChange: handleOnRateChangeEvent, onLoadedMetadata: handleOnLoadedMetadataEvent, onFullscreenChange: handleFullscreenChange, onPlayButtonClicked: handlePlayButtonClick, onPauseButtonClicked: handlePauseButtonClick, onLoudButtonClicked: handleLoudButtonClick, onMuteButtonClicked: handleMuteButtonClick, onVolumeRangeChanged: handleVolumeRangeChange, onRateRangeChanged: handleRateRangeChange, onFullscreenButtonClicked: handleFullscreenButtonClick, onSubtitlesButtonClicked: handleSubtitlesButtonClick });
     return _jsx("div", { className: rootClss, children: needsObserve
             ? _jsx(IntersectionObserverComponent, { threshold: threshold, root: root, rootMargin: rootMargin, onIntersected: onIntersected, children: videoContent })
             : videoContent });

package/components/Video/utils.d.ts

@@ -20,37 +20,6 @@ export declare const forceFullscreen: (video: HTMLVideoElement | null) => Promis
 export declare const forceExitFullscreen: (video: HTMLVideoElement | null) => Promise<boolean>;
 export declare function secondsToMs(seconds: number): number;
 export declare function msToSeconds(ms: number): number;
-/** The fields {@link formatTime} knows how to render. */
-export type TimeToken = 'hh' | 'mm' | 'ss' | 'ms' | 'frame' | 'h' | 'm' | 's' | 'f';
-/**
- * Renders a duration into a caller-defined pattern.
- *
- * Tokens are wrapped in `{{…}}` and everything outside them is literal, so a pattern
- * may carry words: `'{{m}} min {{ss}}'` renders as `'1 min 05'`.
- *
- * - `{{hh}}`, `{{mm}}`, `{{ss}}` — hours, minutes and seconds, zero-padded to two digits.
- * - `{{ms}}` — the remaining milliseconds, zero-padded to three digits.
- * - `{{frame}}` — those milliseconds expressed in frames, zero-padded to two digits.
- * - `{{h}}`, `{{m}}`, `{{s}}`, `{{f}}` — the same four values, unpadded.
- *
- * @param ms - The duration, in milliseconds.
- * @param format - The pattern to fill, e.g. `'{{mm}}:{{ss}}'`.
- * @param fps - Frame rate used to derive the `frame` and `f` tokens. Defaults to `25`.
- * @returns The formatted duration. An unknown token is left as written, braces
- *   included, rather than silently blanked — a typo has to be visible.
- *
- * @remarks
- * Every field is a remainder of the one above it, never a total: at one hour and a half,
- * `{{mm}}` is `30`, not `90`. A pattern that omits `{{hh}}` therefore loses the hours
- * rather than folding them into the minutes.
- *
- * **The delimiters are what make the pattern free-form.** Until they existed, `h`, `m`,
- * `s` and `f` were tokens on their own and every occurrence of those letters was
- * substituted wherever it sat — `'mm min ss'` rendered as `'01 1in 01'`, so a pattern
- * could only ever separate its fields with punctuation. That is why the format could not
- * be exposed as a prop: doing so would have published the trap.
- */
-export declare function formatTime(ms: number, format: string, fps?: number): string;
 /**
  * Where along the timeline a click landed.
  *

package/components/Video/utils.js

@@ -107,64 +107,6 @@ export function secondsToMs(seconds) {
 export function msToSeconds(ms) {
     return ms / 1000;
 }
-// Alternation is ordered and the first branch that fits wins, so the longest tokens
-// come first — the same regexp shape, and the same reason, as
-// `agnostic/time/dates/format-date`.
-const timeTokenRegexp = /\{\{(frame|hh|mm|ss|ms|h|m|s|f)\}\}/gv;
-/**
- * Renders a duration into a caller-defined pattern.
- *
- * Tokens are wrapped in `{{…}}` and everything outside them is literal, so a pattern
- * may carry words: `'{{m}} min {{ss}}'` renders as `'1 min 05'`.
- *
- * - `{{hh}}`, `{{mm}}`, `{{ss}}` — hours, minutes and seconds, zero-padded to two digits.
- * - `{{ms}}` — the remaining milliseconds, zero-padded to three digits.
- * - `{{frame}}` — those milliseconds expressed in frames, zero-padded to two digits.
- * - `{{h}}`, `{{m}}`, `{{s}}`, `{{f}}` — the same four values, unpadded.
- *
- * @param ms - The duration, in milliseconds.
- * @param format - The pattern to fill, e.g. `'{{mm}}:{{ss}}'`.
- * @param fps - Frame rate used to derive the `frame` and `f` tokens. Defaults to `25`.
- * @returns The formatted duration. An unknown token is left as written, braces
- *   included, rather than silently blanked — a typo has to be visible.
- *
- * @remarks
- * Every field is a remainder of the one above it, never a total: at one hour and a half,
- * `{{mm}}` is `30`, not `90`. A pattern that omits `{{hh}}` therefore loses the hours
- * rather than folding them into the minutes.
- *
- * **The delimiters are what make the pattern free-form.** Until they existed, `h`, `m`,
- * `s` and `f` were tokens on their own and every occurrence of those letters was
- * substituted wherever it sat — `'mm min ss'` rendered as `'01 1in 01'`, so a pattern
- * could only ever separate its fields with punctuation. That is why the format could not
- * be exposed as a prop: doing so would have published the trap.
- */
-export function formatTime(ms, format, fps = 25) {
-    const totalSeconds = Math.floor(ms / 1000);
-    const hours = Math.floor(totalSeconds / 3600);
-    const minutes = Math.floor((totalSeconds % 3600) / 60);
-    const seconds = Math.floor(totalSeconds % 60);
-    const frames = Math.floor(((ms % 1000) / 1000) * fps);
-    const msRest = Math.floor(ms % 1000);
-    // Typed by {@link TimeToken} so the table and the regexp above cannot fall out of step,
-    // then read through a widened view: the capture is a `string` as far as the compiler
-    // knows, and widening is what lets it be looked up without asserting it back.
-    const tokens = {
-        hh: String(hours).padStart(2, '0'),
-        mm: String(minutes).padStart(2, '0'),
-        ss: String(seconds).padStart(2, '0'),
-        frame: String(frames).padStart(2, '0'),
-        ms: String(msRest).padStart(3, '0'),
-        h: String(hours),
-        m: String(minutes),
-        s: String(seconds),
-        f: String(frames)
-    };
-    const byName = tokens;
-    // One pass, so a rendered value can never be re-read as a token by a later pass — the
-    // reason the old implementation had to sort its keys by length.
-    return format.replace(timeTokenRegexp, (whole, token) => byName[token] ?? whole);
-}
 /**
  * Where along the timeline a click landed.
  *

package/node/@aws-s3/storage/file/index.d.ts

@@ -1,7 +1,7 @@
 export * as copy from './copy/index.js'
 export * as download from './download/index.js'
 export * as exists from './exists/index.js'
-export * as remove from './remove/index.js'
 export * as move from './move/index.js'
 export * as stat from './stat/index.js'
+export * as remove from './remove/index.js'
 export * as upload from './upload/index.js'

package/node/@aws-s3/storage/file/index.js

@@ -1,7 +1,7 @@
 export * as copy from './copy/index.js'
 export * as download from './download/index.js'
 export * as exists from './exists/index.js'
-export * as remove from './remove/index.js'
 export * as move from './move/index.js'
 export * as stat from './stat/index.js'
+export * as remove from './remove/index.js'
 export * as upload from './upload/index.js'