@design-edito/tools 0.3.9 → 0.3.11

package/components/Scrllgngn/styles.module.css

@@ -0,0 +1,74 @@
+.root {
+  position: relative;
+}
+
+/* MAIN LAYOUTS (back / front blocks, scrolling content) */
+
+.back-blocks {
+  z-index: 1;
+}
+
+.scrolling-content {
+  z-index: 2;
+}
+
+.front-blocks {
+  z-index: 3;
+}
+
+/* Scrllgngn entering the viewport, blocks not fixed yet */
+.back-blocks,
+.front-blocks,
+.root.root--top-visible.root--content-visible .back-blocks,
+.root.root--top-visible.root--content-visible .front-blocks {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 100vh;
+}
+
+/*
+Scrllgngn well in the viewport, fixed blocks
+OR
+Force stick blocks option
+*/
+.root.root--content-visible .back-blocks,
+.root.root--content-visible .front-blocks,
+
+.root.root--top-visible.root--content-visible.root--force-stick-blocks-before .back-blocks,
+.root.root--top-visible.root--content-visible.root--force-stick-blocks-before .front-blocks,
+.root.root--top-visible.root--content-visible.root--force-stick-blocks-both .back-blocks,
+.root.root--top-visible.root--content-visible.root--force-stick-blocks-both .front-blocks,
+
+.root.root--bottom-visible.root--content-visible.root--force-stick-blocks-after .back-blocks,
+.root.root--bottom-visible.root--content-visible.root--force-stick-blocks-after .front-blocks,
+.root.root--bottom-visible.root--content-visible.root--force-stick-blocks-both .back-blocks,
+.root.root--bottom-visible.root--content-visible.root--force-stick-blocks-both .front-blocks {
+  position: fixed;
+  top: 0;
+  left: var(--PRIVATE-left);
+  width: var(--PRIVATE-width);
+  height: 100vh;
+}
+
+/* Scrllgngn leaving the viewport, blocks not fixed but have offset */
+.root.root--bottom-visible.root--content-visible .back-blocks,
+.root.root--bottom-visible.root--content-visible .front-blocks {
+  position: absolute;
+  top: calc(var(--PRIVATE-height) - 100vh);
+  left: 0;
+  right: 0;
+  height: 100vh;
+}
+
+/* INDIVIDUAL FIXED BLOCKS */
+
+.back-block,
+.front-block {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  right: 0;
+}

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

@@ -0,0 +1,78 @@
+import { type FunctionComponent, type PropsWithChildren } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Props for the {@link SequencerControlled} component.
+ *
+ * This is the low-level controlled interface. All state is driven externally —
+ * the component holds no internal state of its own. For the uncontrolled
+ * version that reacts to external events and derives these props automatically,
+ * see the default export of the parent module.
+ *
+ * @property step - Zero-based index of the currently active step. Determines
+ * which child is marked active, which are previous, and which are next.
+ * Defaults to `0`.
+ * @property activateOnStep - Optional 2D array that overrides the default
+ * one-child-per-step activation logic. Each entry at index `i` is the list of
+ * child indices that should be active when `step === i`, allowing multiple
+ * children to be simultaneously active on a given step. When omitted, exactly
+ * one child is active at a time (the child at index `step`).
+ * @property _modifiers - Internal modifier flags forwarded directly to the
+ * BEM class builder on the root element. Intended to be injected by the
+ * uncontrolled wrapper; avoid setting manually in consumer code.
+ * - `playing` — sequence is currently progressing.
+ * - `at-start` — current step is the first step.
+ * - `at-end` — current step is the last step.
+ * @property _dataAttributes - Internal data attribute values forwarded to the
+ * root element as `data-<key>`. Intended to be injected by the uncontrolled
+ * wrapper; avoid setting manually in consumer code.
+ * - `tempo` — exposed as `data-tempo`, reflects the current playback tempo.
+ * @property className - Optional additional class name(s) applied to the root element.
+ * @property children - The items to sequence. Each child is wrapped in a
+ * classifier `<div>` and receives one of the `--active`, `--previous`, or
+ * `--next` modifiers depending on its position relative to the current `step`.
+ */
+export type ControlledProps = PropsWithChildren<WithClassName<{
+    step?: number;
+    activateOnStep?: number[][];
+    _modifiers?: {
+        playing?: boolean;
+        'at-start'?: boolean;
+        'at-end'?: boolean;
+    };
+    _dataAttributes?: {
+        tempo?: number;
+    };
+}>>;
+/**
+ * Controlled sequencer component. Renders each child inside a classifier
+ * wrapper and assigns step-relative modifiers based on `step` and the optional
+ * `activateOnStep` override map.
+ *
+ * This component is purely presentational and holds no internal state.
+ * It is designed to be driven by the uncontrolled wrapper, which handles
+ * timing, playback events, and derives the props passed here.
+ *
+ * ### Root element modifiers
+ * The root `<div>` receives the public class name defined by `sequencer` and
+ * the following BEM-style modifier classes, sourced from `_modifiers`:
+ * - `--playing` — when the sequence is actively progressing.
+ * - `--at-start` — when the current step is the first step.
+ * - `--at-end` — when the current step is the last step.
+ *
+ * ### Data attributes on the root element
+ * Derived from `_dataAttributes`, each key is prefixed with `data-`:
+ * - `data-tempo` — current playback tempo, when provided.
+ *
+ * ### Child wrapper elements
+ * Each child is wrapped in a `<div>` with the `__child` element class and
+ * exactly one of the following mutually exclusive modifiers:
+ * - `--active` — this child corresponds to the current step (or is included
+ * in `activateOnStep[step]`).
+ * - `--previous` — this child was active in a prior step.
+ * - `--next` — this child has not yet been reached.
+ *
+ * @param props - Component properties.
+ * @see {@link ControlledProps}
+ * @returns A root `<div>` containing one classifier wrapper per child.
+ */
+export declare const SequencerControlled: FunctionComponent<ControlledProps>;

package/components/Sequencer/index.d.ts

@@ -0,0 +1,85 @@
+import { type FunctionComponent } from 'react';
+import { type Props as IOCompProps } from '../IntersectionObserver/index.js';
+import { type ControlledProps } from './index.controlled.js';
+/**
+ * Props for the {@link Sequencer} component.
+ *
+ * Extends {@link ControlledProps} (minus `_modifiers`, which are derived
+ * internally) with uncontrolled playback and viewport-driven behaviour.
+ *
+ * @property defaultStep - Initial step index when running in uncontrolled mode.
+ * Ignored if `step` is provided. Defaults to `0`.
+ * @property tempo - Playback speed in beats per minute. The interval between
+ * steps is derived as `1000 / (tempo / 60)` ms. Clamped to a minimum of `1`.
+ * Defaults to `60`.
+ * @property play - Controlled play state. When provided, overrides the internal
+ * play state. The auto-advance interval only runs when this is `true`.
+ * @property loop - When `true`, the step wraps around using absolute modulo so
+ * it never exceeds the number of steps.
+ * @property clampFirst - When `true` (and `loop` is `false`), clamps the step
+ * to `0` at the lower bound, preventing negative step values.
+ * @property clampLast - When `true` (and `loop` is `false`), clamps the step
+ * to `stepsCount - 1` at the upper bound, preventing overflow.
+ * @property resetOnVisible - When `true`, resets the internal step to `0` each
+ * time the component enters the viewport. No-op when `step` or `play` is controlled.
+ * @property resetOnHidden - When `true`, resets the internal step to `0` each
+ * time the component leaves the viewport. No-op when `step` or `play` is controlled.
+ * @property playOnVisible - When `true`, starts internal playback when the
+ * component enters the viewport. No-op when `play` is controlled.
+ * @property pauseOnHidden - When `true`, pauses internal playback when the
+ * component leaves the viewport. No-op when `play` is controlled.
+ * @property actionHandlers - Optional handlers for imperative actions triggered
+ * by external events:
+ * - `intersected` — forwarded verbatim to the internal
+ * {@link IntersectionObserverComponent}'s `onIntersected`, called on every
+ * intersection change regardless of controlled state.
+ * @property stateHandlers - Optional callbacks invoked when derived state changes:
+ * - `isPlaying` — called with the new play state whenever it changes.
+ * - `stepChanged` — called with the new forwarded step index whenever it changes.
+ */
+export type Props = Omit<ControlledProps, '_modifiers'> & {
+    defaultStep?: number;
+    tempo?: number;
+    play?: boolean;
+    loop?: boolean;
+    clampFirst?: boolean;
+    clampLast?: boolean;
+    resetOnVisible?: boolean;
+    resetOnHidden?: boolean;
+    playOnVisible?: boolean;
+    pauseOnHidden?: boolean;
+    actionHandlers?: {
+        intersected?: IOCompProps['onIntersected'];
+    };
+    stateHandlers?: {
+        isPlaying?: (isPlaying: boolean) => void;
+        stepChanged?: (step: number) => void;
+    };
+};
+/**
+ * Uncontrolled, self-advancing sequencer component. Drives a
+ * {@link SequencerControlled} instance with an internal tempo-based interval,
+ * optional loop/clamp boundary behaviour, and viewport-driven play/reset triggers
+ * via an {@link IntersectionObserverComponent}.
+ *
+ * Supports mixed controlled/uncontrolled usage: passing `step` disables the
+ * internal interval while still applying loop/clamp arithmetic before forwarding
+ * to the controlled layer. Passing `play` disables internal play state management
+ * while still allowing viewport handlers to fire `actionHandlers.intersected`.
+ *
+ * ### Forwarded modifiers to {@link SequencerControlled}
+ * The following `_modifiers` are computed and injected automatically:
+ * - `playing` — `true` when the effective play state is active.
+ * - `at-start` — `true` when the forwarded step is `0`.
+ * - `at-end` — `true` when the forwarded step equals `stepsCount - 1`.
+ *
+ * ### Forwarded data attributes to {@link SequencerControlled}
+ * - `data-tempo` — the current `tempo` value.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @see {@link SequencerControlled}
+ * @returns An {@link IntersectionObserverComponent} wrapping a
+ * {@link SequencerControlled} with the computed step and modifiers applied.
+ */
+export declare const Sequencer: FunctionComponent<Props>;

package/components/Sequencer/index.js

@@ -0,0 +1,109 @@
+// src/components/Sequencer/index.tsx
+import {
+  useState,
+  useEffect,
+  useCallback,
+  Children,
+  useRef
+} from "react";
+import { absoluteModulo } from "../../agnostic/numbers/absolute-modulo/index.js";
+import { clamp } from "../../agnostic/numbers/clamp/index.js";
+import {
+  IntersectionObserverComponent
+} from "../IntersectionObserver/index.js";
+import {
+  SequencerControlled
+} from "./index.controlled.js";
+import { jsx } from "react/jsx-runtime";
+var Sequencer = ({
+  defaultStep,
+  tempo = 60,
+  play,
+  loop,
+  clampFirst,
+  clampLast,
+  resetOnVisible,
+  resetOnHidden,
+  playOnVisible,
+  pauseOnHidden,
+  actionHandlers,
+  stateHandlers,
+  ...controlledProps
+}) => {
+  const { step, activateOnStep, children } = controlledProps;
+  const [internalPlay, setInternalPlay] = useState(play ?? false);
+  const [internalStep, setInternalStep] = useState(step ?? defaultStep ?? 0);
+  const actualPlay = play ?? internalPlay;
+  const actualStep = step ?? internalStep;
+  const actualPlayRef = useRef(actualPlay);
+  useEffect(() => {
+    const clampedTempo = Math.max(tempo, 1);
+    if (!actualPlay || step !== void 0) return;
+    const interval = window.setInterval(() => {
+      setInternalStep((s) => s + 1);
+    }, 1e3 / (clampedTempo / 60));
+    return () => window.clearInterval(interval);
+  }, [actualPlay, tempo, step]);
+  const stepsCount = activateOnStep !== void 0 ? activateOnStep.length : Children.toArray(children).length;
+  let forwardedStep;
+  if (loop === true) {
+    forwardedStep = absoluteModulo(actualStep, stepsCount);
+  } else {
+    const leftClamp = clampFirst === true ? 0 : -Infinity;
+    const rightClamp = clampLast === true ? stepsCount - 1 : Infinity;
+    forwardedStep = clamp(actualStep, leftClamp, rightClamp);
+  }
+  const forwardedStepRef = useRef(forwardedStep);
+  useEffect(() => {
+    if (actualPlay !== actualPlayRef.current) {
+      actualPlayRef.current = actualPlay;
+      stateHandlers?.isPlaying?.(actualPlay);
+    }
+    if (forwardedStep !== forwardedStepRef.current) {
+      forwardedStepRef.current = forwardedStep;
+      stateHandlers?.stepChanged?.(forwardedStep);
+    }
+  }, [actualPlay, forwardedStep]);
+  const handleIntersection = useCallback(({ ioEntry, observer }) => {
+    if (play === true || step !== void 0) return;
+    const { isIntersecting } = ioEntry ?? {};
+    actionHandlers?.intersected?.({ ioEntry, observer });
+    if (isIntersecting === true) {
+      if (resetOnVisible === true) setInternalStep(0);
+      if (playOnVisible === true) setInternalPlay(true);
+    } else {
+      if (resetOnHidden === true) setInternalStep(0);
+      if (pauseOnHidden === true) setInternalPlay(false);
+    }
+  }, [
+    resetOnVisible,
+    playOnVisible,
+    resetOnHidden,
+    pauseOnHidden,
+    play,
+    step,
+    actionHandlers
+  ]);
+  return /* @__PURE__ */ jsx(
+    IntersectionObserverComponent,
+    {
+      onIntersected: handleIntersection,
+      children: /* @__PURE__ */ jsx(
+        SequencerControlled,
+        {
+          ...controlledProps,
+          step: forwardedStep,
+          _modifiers: {
+            playing: actualPlay,
+            "at-start": forwardedStep === 0,
+            "at-end": forwardedStep === stepsCount - 1
+          },
+          _dataAttributes: { tempo }
+        }
+      )
+    }
+  );
+};
+export {
+  Sequencer
+};

package/components/ShadowRoot/index.d.ts

@@ -0,0 +1,35 @@
+import { type PropsWithChildren, type FunctionComponent } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Props for the ShadowRootComponent.
+ *
+ * @property className - Optional additional class name(s) applied to the host element
+ * that owns the Shadow Root.
+ * @property mode - Shadow DOM mode. `"open"` exposes the shadowRoot via `element.shadowRoot`,
+ * `"closed"` keeps it inaccessible from the outside. Defaults to `"open"`.
+ * @property delegatesFocus - When true, enables focus delegation from the host
+ * to the first focusable element inside the Shadow Root.
+ * @property slotAssignment - Slot assignment mode. `"named"` uses standard named slot behavior,
+ * `"manual"` requires manual slot assignment via `HTMLSlotElement.assign()`.
+ * @property adoptedStyleSheets - Array of constructable `CSSStyleSheet` instances
+ * assigned to `shadowRoot.adoptedStyleSheets` (if supported by the browser).
+ * @property injectedStyles - Raw CSS string injected into the Shadow Root inside a `<style>` element.
+ * Useful as a fallback when constructable stylesheets are not used.
+ * @property children - React children rendered inside the Shadow Root via a React portal.
+ */
+export type Props = PropsWithChildren<WithClassName<{
+    mode?: 'open' | 'closed';
+    delegatesFocus?: boolean;
+    slotAssignment?: 'named' | 'manual';
+    adoptedStyleSheets?: CSSStyleSheet[];
+    injectedStyles?: string;
+}>>;
+/**
+ * Component that creates a Shadow Root on its host element and renders
+ * its children inside that Shadow Root using a React portal.
+ *
+ * @param props - Component properties
+ * @see {@link Props}
+ * @returns A host `div` element that owns the created Shadow Root.
+ */
+export declare const ShadowRootComponent: FunctionComponent<Props>;

package/components/ShadowRoot/index.js

@@ -0,0 +1,56 @@
+// src/components/ShadowRoot/index.tsx
+import {
+  useRef,
+  useEffect,
+  useState
+} from "react";
+import { createPortal } from "react-dom";
+import { clss } from "../../agnostic/css/clss/index.js";
+import { shadowRoot as publicClassName } from "../public-classnames.js";
+import { mergeClassNames } from "../utils/index.js";
+import cssModule from "./styles.module.css";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var ShadowRootComponent = ({
+  mode = "open",
+  delegatesFocus,
+  slotAssignment,
+  adoptedStyleSheets,
+  injectedStyles,
+  className,
+  children
+}) => {
+  const hostRef = useRef(null);
+  const [shadowRoot, setShadowRoot] = useState(null);
+  const [styles, setStyles] = useState(injectedStyles);
+  useEffect(() => {
+    if (hostRef.current === null || shadowRoot !== null) return;
+    const root = hostRef.current.attachShadow({ mode, delegatesFocus, slotAssignment });
+    if (adoptedStyleSheets !== void 0 && "adoptedStyleSheets" in root) {
+      root.adoptedStyleSheets = adoptedStyleSheets;
+    }
+    if (injectedStyles !== void 0) setStyles(injectedStyles);
+    setShadowRoot(root);
+  }, [
+    mode,
+    delegatesFocus,
+    slotAssignment,
+    adoptedStyleSheets,
+    injectedStyles
+  ]);
+  const c = clss(publicClassName, { cssModule });
+  const rootClss = mergeClassNames(c(), className);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: hostRef,
+      className: rootClss,
+      children: shadowRoot !== null && createPortal(/* @__PURE__ */ jsxs(Fragment, { children: [
+        styles !== void 0 && /* @__PURE__ */ jsx("style", { children: styles }),
+        children
+      ] }), shadowRoot)
+    }
+  );
+};
+export {
+  ShadowRootComponent
+};

package/components/Subtitles/index.d.ts

@@ -0,0 +1,58 @@
+import { type FunctionComponent, type PropsWithChildren } from 'react';
+import type { WithClassName } from '../utils/types.js';
+import type { ParsedSub } from './types.js';
+/**
+ * Props for the {@link Subtitles} component.
+ *
+ * @property src - URL of an SRT file to fetch. Ignored if `srtFileContent` is provided.
+ * If both are undefined, no subtitles are loaded.
+ * @property srtFileContent - Raw SRT string used directly, bypassing any network fetch.
+ * Takes precedence over `src`.
+ * @property subsGroups - Optional array of subtitle IDs that act as group boundaries,
+ * splitting the full subtitle list into named sections. If omitted, all subtitles
+ * belong to a single group.
+ * @property timecodeMs - Current media position in milliseconds. Drives which subtitles
+ * receive the `--prev` and `--curr` modifiers. When `undefined`, nothing is rendered.
+ * @property isEnded - When `true`, forces the last group to be treated as current,
+ * regardless of `timecodeMs`. Useful to keep the final subtitle group visible after
+ * media playback finishes.
+ * @property onLoaded - Callback invoked with the raw SRT string after a successful
+ * fetch and parse. Not called when `srtFileContent` is used directly.
+ * @property onParsed - Callback invoked with the raw SRT string has been parsed.
+ * @property onLoadFailed - Callback invoked with an `Error` if the fetch or parse step fails.
+ * @property className - Optional additional class name(s) applied to the root element.
+ * @property children - React children rendered inside the root element, after the subtitle groups.
+ */
+export type Props = PropsWithChildren<WithClassName<{
+    src?: string;
+    srtFileContent?: string;
+    subsGroups?: number[];
+    timecodeMs?: number;
+    isEnded?: boolean;
+    onLoaded?: (subs: string) => void;
+    onParsed?: (subs: ParsedSub[]) => void;
+    onLoadFailed?: (error: Error) => void;
+}>>;
+/**
+ * Subtitle synchronization component. Fetches or receives an SRT source, parses it,
+ * and renders subtitle groups whose individual spans are styled according to the
+ * current media timecode.
+ *
+ * ### Group elements
+ * Each subtitle group is a `<div>` with the following:
+ * - `--curr` modifier when the group contains the subtitle at the current timecode.
+ * - `data-start-sub-pos` — ID of the first subtitle in the group.
+ * - `data-end-sub-pos` — ID of the last subtitle in the group.
+ *
+ * ### Subtitle span elements
+ * Each individual subtitle is a `<span>` with the following:
+ * - `--prev` modifier when the subtitle's start time is at or before the last elapsed subtitle.
+ * - `--curr` modifier when `timecodeMs` falls within the subtitle's `[start, end]` interval.
+ * - `data-sub-pos` — the subtitle's numeric ID from the SRT source.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A root `<div>` containing the rendered subtitle groups, or an empty `<div>`
+ * when `timecodeMs` is undefined or no subtitles have been parsed yet.
+ */
+export declare const Subtitles: FunctionComponent<Props>;

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;