@design-edito/tools 0.3.10 → 0.3.12

package/components/Subtitles/index.js

@@ -0,0 +1,111 @@
+// src/components/Subtitles/index.tsx
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState
+} from "react";
+import { clss } from "../../agnostic/css/clss/index.js";
+import { toError } from "../../agnostic/misc/cast/index.js";
+import { unknownToString } from "../../agnostic/errors/unknown-to-string/index.js";
+import { mergeClassNames } from "../utils/index.js";
+import { subtitles as publicClassName } from "../public-classnames.js";
+import {
+  computeSubGroupsWithBoundaries,
+  getCurrentGroup,
+  parseSubs
+} from "./utils.js";
+import cssModule from "./styles.module.css";
+import { jsx } from "react/jsx-runtime";
+var Subtitles = ({
+  src,
+  srtFileContent,
+  subsGroups,
+  timecodeMs,
+  isEnded,
+  className,
+  onLoaded,
+  onParsed,
+  onLoadFailed
+}) => {
+  const [isLoading, setIsLoading] = useState(false);
+  const [loadError, setLoadError] = useState(null);
+  const [parsedSubs, setParsedSubs] = useState([]);
+  const pParsedSubs = useRef(parsedSubs);
+  useEffect(() => {
+    if (pParsedSubs.current === parsedSubs) return;
+    onParsed?.(parsedSubs);
+  }, [parsedSubs]);
+  const fetchAndParseSubs = useCallback(async (src2, srtFileContent2) => {
+    if (src2 === void 0) return;
+    if (srtFileContent2 !== void 0) return setParsedSubs(parseSubs(srtFileContent2));
+    setIsLoading(true);
+    setLoadError(null);
+    try {
+      const response = await fetch(src2);
+      const srtContent = await response.text();
+      onLoaded?.(srtContent);
+      const parsedSubs2 = parseSubs(srtContent);
+      setParsedSubs(parsedSubs2);
+    } catch (error) {
+      setLoadError(error instanceof Error ? error : new Error(unknownToString(error)));
+      console.error(error);
+      onLoadFailed?.(toError(error));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [onLoadFailed, onLoaded]);
+  useEffect(() => {
+    fetchAndParseSubs(src, srtFileContent).catch((error) => {
+      console.error(error);
+    });
+  }, [fetchAndParseSubs, src, srtFileContent]);
+  const c = clss(publicClassName, { cssModule });
+  const rootClss = mergeClassNames(
+    c(null, {
+      loading: isLoading,
+      error: loadError !== null
+    }),
+    className
+  );
+  const prevSubs = parsedSubs.filter(({ start }) => start != null && start < (timecodeMs ?? 0));
+  const lastPrevSub = prevSubs[prevSubs.length - 1];
+  const highestSubId = Math.max(...parsedSubs.map((sub) => sub.id));
+  const subsGroupsWithBoundaries = computeSubGroupsWithBoundaries(subsGroups, highestSubId);
+  const currentGroup = getCurrentGroup(subsGroupsWithBoundaries, lastPrevSub?.id, isEnded);
+  return /* @__PURE__ */ jsx("div", { className: rootClss, children: timecodeMs !== void 0 && parsedSubs.length > 0 && subsGroupsWithBoundaries.map((group) => {
+    const groupSubs = parsedSubs.filter((sub) => sub.id >= group.startId && sub.id <= group.endId);
+    const totalSubs = groupSubs.length;
+    const groupClass = c("group", { curr: currentGroup?.startId === group.startId });
+    const subsNodes = groupSubs.map((sub, subIndex) => {
+      let subText = sub.content?.trim() ?? "";
+      if (subIndex !== totalSubs - 1) subText += " ";
+      const subClass = c("sub", {
+        prev: sub.start !== void 0 && lastPrevSub?.start !== void 0 && sub.start <= lastPrevSub.start,
+        curr: sub.start !== void 0 && timecodeMs >= sub.start && sub.end !== void 0 && timecodeMs <= sub.end
+      });
+      return /* @__PURE__ */ jsx(
+        "span",
+        {
+          className: subClass,
+          "data-sub-pos": sub.id,
+          children: subText
+        },
+        sub.id
+      );
+    });
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: groupClass,
+        "data-start-sub-pos": group.startId,
+        "data-end-sub-pos": group.endId,
+        children: subsNodes
+      },
+      group.startId
+    );
+  }) });
+};
+export {
+  Subtitles
+};

package/components/Subtitles/types.d.ts

@@ -0,0 +1,10 @@
+export type ParsedSub = {
+    id: number;
+    start?: number;
+    end?: number;
+    content?: string;
+};
+export type SubGroupBoundaries = {
+    startId: number;
+    endId: number;
+};

package/components/Subtitles/utils.d.ts

@@ -0,0 +1,28 @@
+import type { ParsedSub, SubGroupBoundaries } from './types.js';
+/**
+ * Convertit un timecode au format SRT (hh:mm:ss,ms) en millisecondes.
+ * @param timecode - Timecode sous forme de chaîne (ex: '00:01:23,456')
+ * @returns Le temps en millisecondes
+ */
+export declare const getTimecodeToMs: (timecode: string) => number;
+/**
+ * Parse un texte brut de sous-titres SRT en une liste d'objets ParsedSub.
+ * @param rawSubs - Sous-titres bruts au format SRT
+ * @returns Tableau d'objets ParsedSub
+ */
+export declare const parseSubs: (rawSubs: string) => ParsedSub[];
+/**
+ * Calcule les groupes de sous-titres avec leurs bornes (startId, endId).
+ * @param subsGroups - Tableau d'IDs de fin de groupe
+ * @param highestSubId - ID le plus élevé des sous-titres
+ * @returns Tableau de SubGroupBoundaries
+ */
+export declare const computeSubGroupsWithBoundaries: (subsGroups: number[] | undefined, highestSubId: number) => SubGroupBoundaries[];
+/**
+ * Retourne le groupe de sous-titres courant selon l'ID du dernier sous-titre précédent et l'état.
+ * @param subsGroupsWithBoundaries - Tableau des groupes avec bornes
+ * @param lastPrevSubId - ID du dernier sous-titre précédent
+ * @param isEnded - Indique si la lecture est terminée
+ * @returns Le groupe courant ou undefined
+ */
+export declare const getCurrentGroup: (subsGroupsWithBoundaries: SubGroupBoundaries[], lastPrevSubId: number | undefined, isEnded: boolean | undefined) => SubGroupBoundaries | undefined;

package/components/Theatre/index.d.ts

@@ -0,0 +1,64 @@
+import { type FunctionComponent, type PropsWithChildren, type ReactNode } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Props for the {@link Theatre} component.
+ *
+ * @property closeBtnContent - Custom content rendered inside the close/exit button.
+ * @property openBtnContent - Custom content rendered inside the open/enter button.
+ * @property isOn - Controlled theatre mode state. When provided, overrides the
+ * internal state. Use together with {@link Props.onToggleClick} for fully
+ * controlled usage.
+ * @property defaultIsOn - Default state for the theatre mode.
+ * @property exitOnEscape — When uncontrolled and on, toggles internal state to off when 'esc' key is pressed
+ * @property exitOnBgClick — When uncontrolled and on, toggles internal state to off when the background is clicked
+ * @property stateHandlers - Callbacks called after the internal state changed
+ * @property stateHandlers.toggled - Callback invoked after the state changed
+ * @property actionHandlers - Callbacks called after a user action on children elements
+ * @property actionHandlers.toggleClick - Callback invoked when either the open or close
+ * button is clicked, the 'esc' key pressed or the background clicked. Receives the theatre state value (`isOn`) at the time of the click,
+ * i.e. the previous state before the toggle.
+ * @property className - Optional additional class name(s) applied to the root element.
+ * @property children - Content rendered both in the default slot and, when theatre
+ * mode is active, duplicated inside the stage element.
+ */
+export type Props = PropsWithChildren<WithClassName<{
+    closeBtnContent?: ReactNode;
+    openBtnContent?: ReactNode;
+    isOn?: boolean;
+    defaultIsOn?: boolean;
+    exitOnEscape?: boolean;
+    exitOnBgClick?: boolean;
+    stateHandlers?: {
+        toggled?: (isOn: boolean) => void;
+    };
+    actionHandlers?: {
+        toggleClick?: (prevIsOn: boolean) => void;
+    };
+}>>;
+/**
+ * Theatre mode component. Wraps content in a toggleable fullscreen-like "stage"
+ * overlay. Supports both controlled and uncontrolled usage.
+ *
+ * When `isOn` is not provided the component manages its own open/closed state
+ * internally. When `isOn` is provided it acts as the source of truth and the
+ * internal state is ignored.
+ *
+ * ### Root element modifiers
+ * The root `<div>` receives the public class name defined by `theatre` and the
+ * following BEM-style modifier classes:
+ * - `--on` — when theatre mode is active.
+ * - `--off` — when theatre mode is inactive.
+ *
+ * ### Child elements
+ * - `__stage` — container rendered inside the root that holds the duplicated
+ * `children` when theatre mode is active. Only mounted when `isOn` is `true`.
+ * - `__open-btn` — clickable element that activates theatre mode.
+ * - `__close-btn` — clickable element that deactivates theatre mode.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A root `<div>` containing the children in their original position,
+ * a stage overlay with the duplicated children (when active), and the open/close
+ * toggle buttons.
+ */
+export declare const Theatre: FunctionComponent<Props>;

package/components/Theatre/index.js

@@ -0,0 +1,97 @@
+// src/components/Theatre/index.tsx
+import {
+  useEffect,
+  useState,
+  useRef
+} from "react";
+import { clss } from "../../agnostic/css/clss/index.js";
+import { mergeClassNames } from "../utils/index.js";
+import { theatre as publicClassName } from "../public-classnames.js";
+import cssModule from "./styles.module.css";
+import { jsx, jsxs } from "react/jsx-runtime";
+var Theatre = ({
+  closeBtnContent,
+  openBtnContent,
+  isOn,
+  defaultIsOn,
+  exitOnEscape,
+  exitOnBgClick,
+  stateHandlers,
+  actionHandlers,
+  children,
+  className
+}) => {
+  const [internalIsOn, setInternalIsOn] = useState(defaultIsOn ?? false);
+  const stageRef = useRef(null);
+  const isTheatreOn = isOn ?? internalIsOn;
+  const prevIsTheatreOnRef = useRef(isTheatreOn);
+  const handleCloseBtnClick = () => {
+    actionHandlers?.toggleClick?.(isTheatreOn);
+    if (isOn === void 0) setInternalIsOn(false);
+  };
+  const handleOpenBtnClick = () => {
+    actionHandlers?.toggleClick?.(isTheatreOn);
+    if (isOn === void 0) setInternalIsOn(true);
+  };
+  const handleStageBgClick = (e) => {
+    if (exitOnBgClick !== true) return;
+    if (e.target !== stageRef.current) return;
+    actionHandlers?.toggleClick?.(isTheatreOn);
+    if (isOn === void 0) setInternalIsOn(false);
+  };
+  useEffect(() => {
+    if (prevIsTheatreOnRef.current !== isTheatreOn) {
+      stateHandlers?.toggled?.(isTheatreOn);
+      prevIsTheatreOnRef.current = isTheatreOn;
+    }
+  }, [isTheatreOn, stateHandlers]);
+  useEffect(() => {
+    if (exitOnEscape === true || !isTheatreOn || isOn !== void 0) return;
+    const listener = (e) => {
+      if (e.key !== "Escape") return;
+      actionHandlers?.toggleClick?.(isTheatreOn);
+      setInternalIsOn(false);
+    };
+    window.addEventListener("keydown", listener);
+    return () => window.removeEventListener("keydown", listener);
+  }, [exitOnEscape, isTheatreOn, isOn]);
+  const c = clss(publicClassName, { cssModule });
+  const rootClss = mergeClassNames(c(null, {
+    "on": isTheatreOn,
+    "off": !isTheatreOn
+  }), className);
+  const stageClass = c("stage");
+  const openBtnClass = c("open-btn");
+  const closeBtnClass = c("close-btn");
+  return /* @__PURE__ */ jsxs("div", { className: rootClss, children: [
+    children,
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: stageClass,
+        onClick: handleStageBgClick,
+        ref: stageRef,
+        children: isTheatreOn && children
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: closeBtnClass,
+        onClick: handleCloseBtnClick,
+        children: closeBtnContent
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: openBtnClass,
+        onClick: handleOpenBtnClick,
+        children: openBtnContent
+      }
+    )
+  ] });
+};
+export {
+  Theatre
+};

package/components/UIModule/index.d.ts

@@ -0,0 +1,85 @@
+import { type FunctionComponent } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Describes the contract a dynamically imported UI module must satisfy.
+ * Every member is validated at runtime after the import resolves.
+ *
+ * @property init - Called once after the module loads. Receives the current
+ * `props` and must return the root `Element` that will be appended to the
+ * host `<div>`. Throwing inside `init` is caught and surfaced as an error state.
+ * @property destroy - Called when the component unmounts or `src` changes.
+ * Receives the `Element` previously returned by `init`. Use it to tear down
+ * event listeners, timers, or third-party instances.
+ * @property update - Optional. Called when `props` change after the module is
+ * already initialized. Receives the live `Element` and the new props object.
+ * @property css - Optional array of raw CSS strings scoped automatically to
+ * the host element via `.<publicClassName>#<id> { … }` and injected as
+ * `<style>` elements.
+ */
+type ModuleData = {
+    init: (props: Record<string, unknown>) => Element;
+    destroy: (target: Element) => void;
+    update?: (target: Element, props: Record<string, unknown>) => void;
+    css?: string[];
+};
+/**
+ * Props for the {@link UIModule} component.
+ *
+ * @property src - URL of the ES module to import dynamically. The module must
+ * satisfy the {@link ModuleData} interface — `init` and `destroy` are required,
+ * `update` and `css` are optional. When `undefined`, nothing is loaded and the
+ * component stays in the `--no-module` state.
+ * @property props - Arbitrary key-value object forwarded verbatim to the
+ * module's `init` call and, on subsequent changes, to `update` (if exported).
+ * @property stateHandlers - Optional callbacks invoked whenever internal state changes:
+ * - `idChanged` — called with the stable instance ID once on mount.
+ * - `isLoadingChanged` — called with the new loading state on every transition.
+ * - `loadedModuleChanged` — called with the new module value (`ModuleData`, `Error`, or `null`)
+ * after each load attempt or teardown.
+ * - `moduleTargetChanged` — called with the `Element` returned by `init`, or `null`
+ * when the module is unloaded or errored.
+ * @property className - Optional additional class name(s) applied to the root element.
+ */
+export type Props = WithClassName<{
+    src?: string;
+    props?: Record<string, unknown>;
+    stateHandlers?: {
+        idChanged?: (id: string) => void;
+        isLoadingChanged?: (isLoading: boolean) => void;
+        loadedModuleChanged?: (loadedModule: ModuleData | Error | null) => void;
+        moduleTargetChanged?: (moduleTarget: Element | null) => void;
+    };
+}>;
+/**
+ * Dynamic UI module host component. Asynchronously imports an ES module by URL,
+ * validates its exported interface, calls its `init` lifecycle to obtain a DOM
+ * `Element`, and appends that element to its own root `<div>`. Handles loading,
+ * error, and teardown states automatically.
+ *
+ * The imported module is expected to conform to the {@link ModuleData} interface.
+ * Any violation (missing exports, wrong types, `init` not returning an `Element`)
+ * transitions the component into the `--error` state and logs to `console.error`.
+ *
+ * ### Root element modifiers
+ * The root `<div>` receives the public class name defined by `uiModule` and
+ * the following BEM-style modifier classes reflecting the current load lifecycle:
+ * - `--loading` — the module fetch is in progress.
+ * - `--no-module` — no module has been loaded yet (`src` is undefined or the
+ * effect has not run).
+ * - `--error` — the import, validation, or `init` call failed.
+ * - `--loaded` — the module passed validation and `init` returned successfully.
+ * - `--initialized` — the `Element` returned by `init` has been appended to the
+ * host `<div>`.
+ *
+ * ### Root element attributes
+ * - `id` — a stable randomly generated ID (prefixed `f`) assigned once on mount.
+ * Used to scope the module's `css` entries to this specific instance.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @see {@link ModuleData}
+ * @returns A host `<div>` into which the module's root `Element` is appended,
+ * along with any `<style>` blocks exported by the module.
+ */
+export declare const UIModule: FunctionComponent<Props>;
+export {};

package/components/UIModule/index.js

@@ -0,0 +1,134 @@
+// src/components/UIModule/index.tsx
+import {
+  useEffect,
+  useRef,
+  useState
+} from "react";
+import { clss } from "../../agnostic/css/clss/index.js";
+import { unknownToString } from "../../agnostic/errors/unknown-to-string/index.js";
+import { isNonNullObject } from "../../agnostic/objects/is-object/index.js";
+import { randomHash } from "../../agnostic/random/uuid/index.js";
+import { mergeClassNames } from "../utils/index.js";
+import { uiModule as publicClassName } from "../public-classnames.js";
+import cssModule from "./styles.module.css";
+import { jsx, jsxs } from "react/jsx-runtime";
+var UIModule = ({
+  src,
+  props,
+  stateHandlers,
+  className
+}) => {
+  const [id] = useState(`f${randomHash(10)}`);
+  const [loading, setLoading] = useState(false);
+  const [loadedModule, _setLoadedModule] = useState(null);
+  const [moduleTarget, _setModuleTarget] = useState(null);
+  const rootRef = useRef(null);
+  const loadedModuleRef = useRef(null);
+  const moduleTargetRef = useRef(null);
+  const setLoadedModule = (data) => {
+    loadedModuleRef.current = data;
+    _setLoadedModule(data);
+  };
+  const setModuleTarget = (data) => {
+    moduleTargetRef.current = data;
+    _setModuleTarget(data);
+  };
+  useEffect(() => {
+    stateHandlers?.idChanged?.(id);
+  }, [id, stateHandlers]);
+  useEffect(() => {
+    stateHandlers?.isLoadingChanged?.(loading);
+  }, [loading, stateHandlers]);
+  useEffect(() => {
+    stateHandlers?.loadedModuleChanged?.(loadedModule);
+  }, [loadedModule, stateHandlers]);
+  useEffect(() => {
+    stateHandlers?.moduleTargetChanged?.(moduleTarget);
+  }, [moduleTarget, stateHandlers]);
+  useEffect(() => {
+    if (src === void 0) return;
+    try {
+      setLoading(true);
+      import(src).then((data) => {
+        setLoading(false);
+        const errs = {
+          notMod: new Error("Not a module"),
+          initFunc: new Error("Module exported member `init` must be a function"),
+          destroyFunc: new Error("Module exported member `destroy` must be a function"),
+          cssStrArr: new Error("Module exported member `css` must be an array of strings"),
+          updFunc: new Error("Module exported member `update` must be a function"),
+          initRetElt: new Error("Module exported function `init` must return an Element"),
+          initRetFirstElt: new Error("Module exported function `init` must return an array containing an Element in its first position")
+        };
+        if (!isNonNullObject(data)) return setLoadedModule(errs.notMod);
+        if (!("init" in data)) return setLoadedModule(errs.initFunc);
+        if (typeof data.init !== "function") return setLoadedModule(errs.initFunc);
+        if (!("destroy" in data) || typeof data.destroy !== "function") return setLoadedModule(errs.destroyFunc);
+        if ("css" in data) {
+          if (!Array.isArray(data.css)) return setLoadedModule(errs.cssStrArr);
+          if (data.css.some((i) => typeof i !== "string")) return setLoadedModule(errs.cssStrArr);
+        }
+        if ("update" in data && typeof data.update !== "function") return setLoadedModule(errs.updFunc);
+        const module = data;
+        setLoadedModule(module);
+        try {
+          const target = module.init(props ?? {});
+          if (!(target instanceof Element)) return setLoadedModule(errs.initRetElt);
+          setModuleTarget(target);
+        } catch (err) {
+          setModuleTarget(null);
+          const e = err instanceof Error ? err : new Error(unknownToString(err));
+          setLoadedModule(e);
+        }
+      }).catch((err) => {
+        setLoading(false);
+        setLoadedModule(err instanceof Error ? err : new Error(unknownToString(err)));
+        setModuleTarget(null);
+      });
+    } catch (err) {
+      if (err instanceof Error) return setLoadedModule(err);
+      const errStr = unknownToString(err);
+      return setLoadedModule(new Error(errStr));
+    }
+    return () => {
+      if (moduleTargetRef.current === null) return;
+      if (loadedModuleRef.current instanceof Error) return;
+      if (loadedModuleRef.current === null) return;
+      loadedModuleRef.current.destroy(moduleTargetRef.current);
+    };
+  }, [src]);
+  useEffect(() => {
+    if (loadedModule instanceof Error) console.error(loadedModule);
+  }, [loadedModule]);
+  useEffect(() => {
+    if (moduleTarget === null) return;
+    if (rootRef.current === null) return;
+    rootRef.current.appendChild(moduleTarget);
+  }, [moduleTarget]);
+  const c = clss(publicClassName, { cssModule });
+  const rootClss = mergeClassNames(
+    c(null, {
+      loading,
+      "no-module": loadedModule === null,
+      "error": loadedModule instanceof Error,
+      "loaded": !loading && loadedModule !== null && !(loadedModule instanceof Error),
+      "initialized": moduleTarget !== null
+    }),
+    className
+  );
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: rootClss,
+      ref: rootRef,
+      id,
+      children: [
+        loadedModule === null && "",
+        loadedModule !== null && !(loadedModule instanceof Error) && loadedModule.css?.map((css) => /* @__PURE__ */ jsx("style", { children: `.${publicClassName}#${id} { ${css} }` }))
+      ]
+    }
+  );
+};
+export {
+  UIModule
+};

package/components/Video/index.d.ts

@@ -0,0 +1,139 @@
+import { type FunctionComponent, type PropsWithChildren, type VideoHTMLAttributes } from 'react';
+import { type Props as DisclaimerProps } from '../Disclaimer/index.js';
+import { type Props as SubsProps } from '../Subtitles/index.js';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Describes a single video source.
+ *
+ * @property src - URL of the video file.
+ * @property type - MIME type of the source (e.g. `'video/mp4'`).
+ */
+type SourceData = {
+    src?: string;
+    type?: string;
+};
+/**
+ * Describes a single text track (subtitles, captions, chapters, etc.).
+ *
+ * @property src - URL of the track file.
+ * @property kind - Track type, maps directly to the `<track>` `kind` attribute.
+ * @property srclang - Language of the track content (e.g. `'fr'`, `'en'`).
+ * @property label - Human-readable label shown in the browser's track selector.
+ * @property default - When `true`, marks this track as the default selection.
+ */
+type TrackData = {
+    src?: string;
+    kind?: 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata';
+    srclang?: string;
+    label?: string;
+    default?: boolean;
+};
+type ActionHandlersProps = {
+    playButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isPlaying: boolean, video: HTMLVideoElement | null) => void;
+    pauseButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isPlaying: boolean, video: HTMLVideoElement | null) => void;
+    loudButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isLoud: boolean, video: HTMLVideoElement | null) => void;
+    muteButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isLoud: boolean, video: HTMLVideoElement | null) => void;
+    volumeRangeChange?: (e: React.ChangeEvent<HTMLInputElement>, targetRangeVolume: number, volume: number, video: HTMLVideoElement | null) => void;
+    fullscreenButtonClick?: (e: React.MouseEvent<HTMLButtonElement>, isFullscreen: boolean, video: HTMLVideoElement | null) => void;
+    rateRangeChange?: (e: React.ChangeEvent<HTMLInputElement>, targetRangeRate: number, rate: number, video: HTMLVideoElement | null) => void;
+    timelineClick?: (e: React.MouseEvent<HTMLDivElement>, targetTimeSec: number, timeSec: number, video: HTMLVideoElement | null) => void;
+};
+type StateHandlersProps = {
+    isPlaying?: (isPlaying: boolean) => void;
+    isFullScreen?: (isFullScreen: boolean) => void;
+    isLoud?: (isLoud: boolean) => void;
+    volume?: (volume: number) => void;
+    currentTime?: (currentTime: number) => void;
+    playbackRate?: (rate: number) => void;
+};
+/**
+ * Props for the {@link Video} component.
+ *
+ * Extends all native `VideoHTMLAttributes<HTMLVideoElement>`, so any standard
+ * video attribute (`autoPlay`, `muted`, `loop`, `poster`, etc.) can be passed
+ * and will be forwarded to the underlying `<video>` element.
+ *
+ * @property sources - One or more video sources. Accepts:
+ * - a single URL string,
+ * - an array of URL strings,
+ * - an array of {@link SourceData} objects for fine-grained `type` control.
+ * @property tracks - One or more text tracks. Accepts:
+ * - a single URL string,
+ * - an array of URL strings,
+ * - an array of {@link TrackData} objects.
+ * @property playBtnContent - Custom content for the play button.
+ * @property pauseBtnContent - Custom content for the pause button.
+ * @property loudBtnContent - Custom content for the unmute button.
+ * @property muteBtnContent - Custom content for the mute button.
+ * @property fullScreenBtnContent - Custom content for the fullScreen button.
+ * @property subtitles - Props forwarded to the internal {@link Subtitles} component.
+ * `timecodeMs` is injected automatically from the current playback position.
+ * @property disclaimer - Props forwarded to the internal {@link Disclaimer} component.
+ * While the disclaimer is active, `autoPlay` and `muted` are suppressed on the
+ * underlying `<video>` element.
+ * @property autoPlayWhenVisible - When `true`, triggers playback the first time the
+ * component intersects the viewport, provided no disclaimer is active.
+ * @property autoPauseWhenHidden - When `true`, pauses playback whenever the component
+ * leaves the viewport.
+ * @property autoLoudWhenVisible - When `true`, unmutes the video the first time the
+ * component intersects the viewport, provided no disclaimer is active.
+ * @property autoMuteWhenHidden - When `true`, mutes the video whenever the component
+ * leaves the viewport.
+ * @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 = PropsWithChildren<WithClassName<{
+    sources?: string | string[] | SourceData[];
+    tracks?: string | string[] | TrackData[];
+    playBtnContent?: React.ReactNode;
+    pauseBtnContent?: React.ReactNode;
+    loudBtnContent?: React.ReactNode;
+    muteBtnContent?: React.ReactNode;
+    fullScreenBtnContent?: React.ReactNode;
+    subtitles?: SubsProps;
+    disclaimer?: DisclaimerProps;
+    autoPlayWhenVisible?: boolean;
+    autoPauseWhenHidden?: boolean;
+    autoLoudWhenVisible?: boolean;
+    autoMuteWhenHidden?: boolean;
+    actionHandlers: ActionHandlersProps;
+    stateHandlers: StateHandlersProps;
+}> & VideoHTMLAttributes<HTMLVideoElement>>;
+/**
+ * Full-featured video player component. Wraps a native `<video>` element with
+ * playback controls, volume, playback rate, a timeline, optional subtitles,
+ * an optional disclaimer gate, and viewport-driven auto-play/mute behaviours.
+ *
+ * ### Root element modifiers
+ * The root `<figure>` receives the public class name defined by `video` and
+ * the following BEM-style modifier classes:
+ * - `--play-on` / `--play-off` — reflects current playback state.
+ * - `--fullscreen-on` / `--fullscreen-off` — reflects fullscreen state.
+ * - `--loud` / `--muted` — reflects mute state.
+ *
+ * ### Data attributes on the root element
+ * - `data-play-on` — present (empty string) when playing.
+ * - `data-play-off` — present (empty string) when paused.
+ * - `data-fullscreen-on` — present (empty string) when in fullScreen.
+ * - `data-fullscreen-off` — present (empty string) when not in fullScreen.
+ * - `data-loud` — present (empty string) when unmuted.
+ * - `data-muted` — present (empty string) when muted.
+ * - `data-volume` — current volume as a `0–1` float.
+ * - `data-volume-percent` — current volume as a `0–100` float.
+ * - `data-playback-rate` — current playback rate (e.g. `1`, `1.5`).
+ * - `data-current-time-ms` — current time in milliseconds, fixed to 2 decimals.
+ * - `data-current-time-ratio` — current / total ratio, fixed to 8 decimals.
+ * - `data-total-time-ms` — total duration in milliseconds.
+ *
+ * ### CSS custom properties on the root element
+ * - `--video-current-time-ratio` — current / total ratio, fixed to 8 decimals.
+ * Useful for driving progress-bar animations purely in CSS.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A `<figure>` element containing the video, its controls, optional
+ * subtitles, and an optional disclaimer overlay.
+ */
+export declare const Video: FunctionComponent<Props>;
+export {};