@design-edito/tools 0.3.11 → 0.3.12

package/components/ScrollListener/index.d.ts

@@ -0,0 +1,47 @@
+import { type FunctionComponent, type PropsWithChildren } from 'react';
+import type { WithClassName } from '../utils/types.js';
+import { type ScrollState } from './utils.js';
+/**
+ * Props for the ScrollListener component.
+ *
+ * @property startOnVisible - When `true`, scroll tracking starts only when the component
+ * becomes visible in the viewport. Visibility is detected using an IntersectionObserver.
+ * @property stopOnHidden - When `true`, scroll tracking stops when the component leaves
+ * the viewport.
+ * @property stateHandlers - Optional callbacks invoked when internal state changes.
+ * @property stateHandlers.scrollDataChanged - Called whenever the computed scroll data
+ * changes. Receives the current {@link ScrollState} or `undefined`.
+ * @property stateHandlers.visibilityChanged - Called when the visibility state of the
+ * component changes. Receives `true` when the component is intersecting the viewport,
+ * otherwise `false`.
+ * @property className - Optional additional class name(s) applied to the root element.
+ * @property children - React nodes rendered inside the scroll listener container.
+ */
+export type Props = PropsWithChildren<WithClassName<{
+    stopOnHidden?: boolean;
+    startOnVisible?: boolean;
+    stateHandlers?: {
+        scrollDataChanged?: (scrollData?: ScrollState) => void;
+        visibilityChanged?: (isVisible: boolean) => void;
+    };
+}>>;
+/**
+ * Component that listens to global scroll events and exposes scroll-related data
+ * through CSS custom properties and optional state callbacks.
+ *
+ * The component measures both global scroll metrics (window size, document size,
+ * scroll offsets) and local metrics relative to the component (dimensions and
+ * position within the document).
+ *
+ * Computed values are exposed as CSS variables on the root element, enabling
+ * scroll-driven styling without additional JavaScript.
+ *
+ * Scroll observation can optionally start only when the component becomes visible
+ * and stop when it leaves the viewport.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A container element exposing scroll metrics through CSS variables and
+ * wrapping its children inside an IntersectionObserver boundary.
+ */
+export declare const ScrollListener: FunctionComponent<Props>;

package/components/ScrollListener/index.js

@@ -0,0 +1,110 @@
+// src/components/ScrollListener/index.tsx
+import {
+  useEffect,
+  useRef,
+  useState,
+  useCallback
+} from "react";
+import { clss } from "../../agnostic/css/clss/index.js";
+import { randomHash } from "../../agnostic/random/uuid/index.js";
+import { mergeClassNames } from "../utils/index.js";
+import {
+  IntersectionObserverComponent
+} from "../IntersectionObserver/index.js";
+import { scrollListener as publicClassName } from "../public-classnames.js";
+import { register, unregister } from "./utils.js";
+import cssModule from "./styles.module.css";
+import { jsx } from "react/jsx-runtime";
+var ScrollListener = ({
+  startOnVisible,
+  stopOnHidden,
+  stateHandlers,
+  className,
+  children
+}) => {
+  const [privateId] = useState(randomHash(6));
+  const [scrollData, setScrollData] = useState();
+  const rootRef = useRef(null);
+  useEffect(() => {
+    stateHandlers?.scrollDataChanged?.(scrollData);
+  }, [scrollData]);
+  useEffect(() => {
+    register({ id: privateId, rootRef, setData: setScrollData });
+    return () => {
+      unregister(privateId);
+    };
+  }, []);
+  const handleIntersection = useCallback(({ ioEntry, observer }) => {
+    stateHandlers?.visibilityChanged?.(ioEntry?.isIntersecting ?? false);
+    if (startOnVisible !== true && stopOnHidden !== true) return;
+    if (ioEntry?.isIntersecting === true && startOnVisible === true) register({ id: privateId, rootRef, setData: setScrollData });
+    if (ioEntry?.isIntersecting !== true && stopOnHidden === true) unregister(privateId);
+  }, [startOnVisible, stopOnHidden]);
+  const customProps = Object.entries(
+    scrollData !== void 0 ? {
+      // Global
+      [`--${publicClassName}-window-width`]: scrollData.global.win.width,
+      [`--${publicClassName}-window-height`]: scrollData.global.win.height,
+      [`--${publicClassName}-html-width`]: scrollData.global.html.width,
+      [`--${publicClassName}-html-height`]: scrollData.global.html.height,
+      [`--${publicClassName}-scroll-x`]: scrollData.global.scroll.x,
+      [`--${publicClassName}-scroll-y`]: scrollData.global.scroll.y,
+      // Local
+      [`--${publicClassName}-width`]: scrollData.local.width,
+      [`--${publicClassName}-height`]: scrollData.local.height,
+      [`--${publicClassName}-offset-x`]: scrollData.local.offsetX,
+      [`--${publicClassName}-offset-y`]: scrollData.local.offsetY
+    } : {}
+  ).reduce((acc, [key, val]) => ({
+    ...acc,
+    [key]: val,
+    [`${key}-px`]: `${val}px`
+  }), {});
+  if (scrollData !== void 0) {
+    customProps[`--${publicClassName}-window-scrolled-x-ratio`] = scrollData.global.scroll.x / Math.max(scrollData.global.html.width - scrollData.global.win.width, 1);
+    customProps[`--${publicClassName}-window-scrolled-y-ratio`] = scrollData.global.scroll.y / Math.max(scrollData.global.html.height - scrollData.global.win.height, 1);
+    const topTouchesTop = scrollData.local.offsetY;
+    const topTouchesBottom = scrollData.local.offsetY - scrollData.global.win.height;
+    const bottomTouchesTop = scrollData.local.offsetY + scrollData.local.height;
+    const bottomTouchesBottom = scrollData.local.offsetY + scrollData.local.height - scrollData.global.win.height;
+    const leftTouchesLeft = scrollData.local.offsetX;
+    const leftTouchesRight = scrollData.local.offsetX - scrollData.global.win.width;
+    const rightTouchesLeft = scrollData.local.offsetX + scrollData.local.width;
+    const rightTouchesRight = scrollData.local.offsetX + scrollData.local.width - scrollData.global.win.width;
+    const innerYRange = [bottomTouchesBottom, topTouchesTop];
+    const outerYRange = [topTouchesBottom, bottomTouchesTop];
+    const innerXRange = [rightTouchesRight, leftTouchesLeft];
+    const outerXRange = [leftTouchesRight, rightTouchesLeft];
+    const innerScrollYRatio = (scrollData.global.scroll.y - innerYRange[0]) / Math.max(innerYRange[1] - innerYRange[0], 1);
+    const outerScrollYRatio = (scrollData.global.scroll.y - outerYRange[0]) / Math.max(outerYRange[1] - outerYRange[0], 1);
+    const innerScrollXRatio = (scrollData.global.scroll.x - innerXRange[0]) / Math.max(innerXRange[1] - innerXRange[0], 1);
+    const outerScrollXRatio = (scrollData.global.scroll.x - outerXRange[0]) / Math.max(outerXRange[1] - outerXRange[0], 1);
+    customProps[`--${publicClassName}-self-inner-scrolled-y-ratio`] = innerScrollYRatio;
+    customProps[`--${publicClassName}-self-outer-scrolled-y-ratio`] = outerScrollYRatio;
+    customProps[`--${publicClassName}-self-inner-scrolled-x-ratio`] = innerScrollXRatio;
+    customProps[`--${publicClassName}-self-outer-scrolled-x-ratio`] = outerScrollXRatio;
+  }
+  const c = clss(publicClassName, { cssModule });
+  const rootClss = mergeClassNames(
+    c(),
+    className
+  );
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: rootClss,
+      ref: rootRef,
+      style: { ...customProps },
+      children: /* @__PURE__ */ jsx(
+        IntersectionObserverComponent,
+        {
+          onIntersected: handleIntersection,
+          children
+        }
+      )
+    }
+  );
+};
+export {
+  ScrollListener
+};

package/components/ScrollListener/utils.d.ts

@@ -0,0 +1,41 @@
+import type { RefObject, Dispatch, SetStateAction } from 'react';
+export type GlobalScrollData = {
+    win: {
+        height: number;
+        width: number;
+    };
+    html: {
+        width: number;
+        height: number;
+    };
+    scroll: {
+        x: number;
+        y: number;
+    };
+    viewport: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    };
+};
+export type LocalScrollData = {
+    offsetX: number;
+    offsetY: number;
+    width: number;
+    height: number;
+};
+export type ScrollState = {
+    global: GlobalScrollData;
+    local: LocalScrollData;
+};
+export declare const globalDocumentScrollListener: () => GlobalScrollData;
+export declare const localElementScrollListener: (div: HTMLDivElement) => LocalScrollData;
+export type RegisterEntry = {
+    id: string;
+    rootRef: RefObject<HTMLDivElement | null>;
+    setData: Dispatch<SetStateAction<ScrollState | undefined>>;
+};
+export declare const registeredIds: Map<string, RegisterEntry>;
+export declare const register: (props: RegisterEntry) => void;
+export declare const unregister: (id: string) => void;

package/components/Theatre/index.d.ts

@@ -14,7 +14,7 @@ import type { WithClassName } from '../utils/types.js';
  * @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.toggleTrigger - Callback invoked when either the open or close
+ * @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.
@@ -32,7 +32,7 @@ export type Props = PropsWithChildren<WithClassName<{
         toggled?: (isOn: boolean) => void;
     };
     actionHandlers?: {
-        toggleTrigger?: (prevIsOn: boolean) => void;
+        toggleClick?: (prevIsOn: boolean) => void;
     };
 }>>;
 /**

package/components/Theatre/index.js

@@ -26,17 +26,17 @@ var Theatre = ({
   const isTheatreOn = isOn ?? internalIsOn;
   const prevIsTheatreOnRef = useRef(isTheatreOn);
   const handleCloseBtnClick = () => {
-    actionHandlers?.toggleTrigger?.(isTheatreOn);
+    actionHandlers?.toggleClick?.(isTheatreOn);
     if (isOn === void 0) setInternalIsOn(false);
   };
   const handleOpenBtnClick = () => {
-    actionHandlers?.toggleTrigger?.(isTheatreOn);
+    actionHandlers?.toggleClick?.(isTheatreOn);
     if (isOn === void 0) setInternalIsOn(true);
   };
   const handleStageBgClick = (e) => {
     if (exitOnBgClick !== true) return;
     if (e.target !== stageRef.current) return;
-    actionHandlers?.toggleTrigger?.(isTheatreOn);
+    actionHandlers?.toggleClick?.(isTheatreOn);
     if (isOn === void 0) setInternalIsOn(false);
   };
   useEffect(() => {
@@ -49,7 +49,7 @@ var Theatre = ({
     if (exitOnEscape === true || !isTheatreOn || isOn !== void 0) return;
     const listener = (e) => {
       if (e.key !== "Escape") return;
-      actionHandlers?.toggleTrigger?.(isTheatreOn);
+      actionHandlers?.toggleClick?.(isTheatreOn);
       setInternalIsOn(false);
     };
     window.addEventListener("keydown", listener);

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

@@ -28,6 +28,24 @@ type TrackData = {
     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.
  *
@@ -79,6 +97,8 @@ export type Props = PropsWithChildren<WithClassName<{
     autoPauseWhenHidden?: boolean;
     autoLoudWhenVisible?: boolean;
     autoMuteWhenHidden?: boolean;
+    actionHandlers: ActionHandlersProps;
+    stateHandlers: StateHandlersProps;
 }> & VideoHTMLAttributes<HTMLVideoElement>>;
 /**
  * Full-featured video player component. Wraps a native `<video>` element with

package/components/Video/index.js

@@ -25,7 +25,11 @@ import {
   forceLoud,
   forceMute,
   forceFullScreen,
-  forceExitFullScreen
+  forceExitFullScreen,
+  forceVolume,
+  forceCurrentTime,
+  getTimelineClickProgress,
+  forcePlaybackRate
 } from "./utils.js";
 import cssModule from "./styles.module.css";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -43,6 +47,8 @@ var Video = ({
   autoPauseWhenHidden,
   autoLoudWhenVisible,
   autoMuteWhenHidden,
+  actionHandlers,
+  stateHandlers,
   children,
   className,
   ...intrinsicVideoAttributes
@@ -83,65 +89,68 @@ var Video = ({
     setVolume(video.volume);
     setIsLoud(!video.muted);
     intrinsicVideoAttributes.onLoadedMetadata?.(e);
-  }, []);
+  }, [intrinsicVideoAttributes.onLoadedMetadata, intrinsicVideoAttributes.muted]);
   const handleVolumeChangeEvent = useCallback((e) => {
-    const { volume: volume2 } = e.currentTarget;
+    const volume2 = e.currentTarget.volume;
     setVolume(volume2);
     intrinsicVideoAttributes.onVolumeChange?.(e);
-  }, []);
+  }, [intrinsicVideoAttributes.onVolumeChange]);
   const handlePlayEvent = useCallback((e) => {
     setIsPlaying(true);
     setHasBeenAutoPlayed(true);
     intrinsicVideoAttributes.onPlay?.(e);
-  }, []);
+  }, [intrinsicVideoAttributes.onPlay]);
   const handlePauseEvent = useCallback((e) => {
     setIsPlaying(false);
     intrinsicVideoAttributes.onPause?.(e);
-  }, []);
+  }, [intrinsicVideoAttributes.onPause]);
   const handleRateChangeEvent = useCallback((e) => {
-    const rate = e.currentTarget.playbackRate;
-    setPlaybackRate(rate);
+    const currentRate = e.currentTarget.playbackRate;
+    setPlaybackRate(currentRate);
     intrinsicVideoAttributes.onRateChange?.(e);
-  }, []);
+  }, [intrinsicVideoAttributes.onRateChange]);
   const handleTimeUpdateEvent = useCallback((e) => {
     const currentTime2 = e.currentTarget.currentTime;
     setCurrentTime(currentTime2);
     intrinsicVideoAttributes?.onTimeUpdate?.(e);
-  }, [totalTime]);
+  }, [totalTime, intrinsicVideoAttributes.onTimeUpdate]);
   const handleVolumeRangeChange = useCallback((e) => {
-    const volumePercent2 = Number(e.currentTarget.value);
-    const volume2 = volumePercent2 / 100;
-    if (videoRef.current === null) return;
-    videoRef.current.volume = volume2;
-  }, []);
-  const handleLoudButtonClick = useCallback(() => {
+    const targetVolume = Number(e.currentTarget.value);
+    actionHandlers?.volumeRangeChange?.(e, targetVolume, volume, videoRef.current);
+    forceVolume(videoRef.current, targetVolume, setVolume);
+  }, [actionHandlers?.volumeRangeChange, volume]);
+  const handleLoudButtonClick = useCallback((e) => {
+    actionHandlers?.loudButtonClick?.(e, isLoud, videoRef.current);
     forceLoud(videoRef.current, setIsLoud);
-  }, [forceLoud]);
-  const handleMuteButtonClick = useCallback(() => {
+  }, [actionHandlers?.loudButtonClick, isLoud]);
+  const handleMuteButtonClick = useCallback((e) => {
+    actionHandlers?.muteButtonClick?.(e, isLoud, videoRef.current);
     forceMute(videoRef.current, setIsLoud);
-  }, []);
-  const handlePlayButtonClick = useCallback(() => {
+  }, [actionHandlers?.muteButtonClick, isLoud]);
+  const handlePlayButtonClick = useCallback((e) => {
+    actionHandlers?.playButtonClick?.(e, isPlaying, videoRef.current);
     void forcePlay(videoRef.current, shouldDisclaimerBeOn, setIsPlaying);
-  }, [forcePlay, shouldDisclaimerBeOn]);
-  const handlePauseButtonClick = useCallback(() => {
+  }, [actionHandlers?.playButtonClick, isPlaying, shouldDisclaimerBeOn]);
+  const handlePauseButtonClick = useCallback((e) => {
+    actionHandlers?.pauseButtonClick?.(e, isPlaying, videoRef.current);
     forcePause(videoRef.current, setIsPlaying);
-  }, []);
-  const handleFullScreenButtonClick = useCallback(() => {
+  }, [actionHandlers?.pauseButtonClick, isPlaying]);
+  const handleFullScreenButtonClick = useCallback((e) => {
+    actionHandlers?.fullscreenButtonClick?.(e, isFullScreen, videoRef.current);
     if (isFullScreen) void forceExitFullScreen(videoRef.current, setIsFullScreen);
     else void forceFullScreen(videoRef.current, shouldDisclaimerBeOn, setIsFullScreen);
   }, [isFullScreen, shouldDisclaimerBeOn]);
   const handleRateRangeChange = useCallback((e) => {
     const rate = Number(e.currentTarget.value);
-    if (videoRef.current === null) return;
-    videoRef.current.playbackRate = rate;
-  }, []);
+    actionHandlers?.rateRangeChange?.(e, rate, playbackRate, videoRef.current);
+    forcePlaybackRate(videoRef.current, rate, setPlaybackRate);
+  }, [actionHandlers?.rateRangeChange, playbackRate]);
   const handleTimelineClick = useCallback((e) => {
-    if (videoRef.current === null) return;
-    const timelineRect = e.currentTarget.getBoundingClientRect();
-    const position = e.clientX - timelineRect.left;
-    const progress = Math.min(1, Math.max(0, position / timelineRect.width));
-    videoRef.current.currentTime = progress * totalTime;
-  }, []);
+    const progress = getTimelineClickProgress(e, e.currentTarget, videoRef.current);
+    const time = progress * totalTime;
+    actionHandlers?.timelineClick?.(e, time, currentTime, videoRef.current);
+    forceCurrentTime(videoRef.current, time, setCurrentTime);
+  }, [actionHandlers?.timelineClick, totalTime, currentTime]);
   const handleDisclaimerDismiss = useCallback(() => {
     setIsDisclaimerOn(false);
     if (intrinsicVideoAttributes.autoPlay === true && !hasBeenAutoPlayed) void forcePlay(videoRef.current, shouldDisclaimerBeOn, setIsPlaying);
@@ -162,6 +171,24 @@ var Video = ({
     intrinsicVideoAttributes,
     hasBeenAutoPlayed
   ]);
+  useEffect(() => {
+    stateHandlers?.isPlaying?.(isPlaying);
+  }, [isPlaying, stateHandlers?.isPlaying]);
+  useEffect(() => {
+    stateHandlers?.isFullScreen?.(isFullScreen);
+  }, [isFullScreen, stateHandlers?.isFullScreen]);
+  useEffect(() => {
+    stateHandlers?.isLoud?.(isLoud);
+  }, [isLoud, stateHandlers?.isLoud]);
+  useEffect(() => {
+    stateHandlers?.volume?.(volume);
+  }, [volume, stateHandlers?.volume]);
+  useEffect(() => {
+    stateHandlers?.playbackRate?.(playbackRate);
+  }, [playbackRate, stateHandlers?.playbackRate]);
+  useEffect(() => {
+    stateHandlers?.currentTime?.(currentTime);
+  }, [currentTime, stateHandlers?.currentTime]);
   const parsedSources = useMemo(() => {
     if (sources === void 0) return [];
     if (typeof sources === "string") return [{ src: sources }];
@@ -206,7 +233,7 @@ var Video = ({
     "data-total-time-ms": totalTimeMs
   };
   const rootStyles = {
-    [`--${publicClassName}-current-time-ratio`]: (currentTime / totalTime).toFixed(8)
+    [`--${publicClassName}-elapsed-time-ratio`]: (currentTime / totalTime).toFixed(8)
   };
   const videoClss = c("video");
   const videoControlsClss = c("video-controls");