@bendyline/squisq-react 2.2.0 → 2.3.1

package/dist/chunk-YQC3AXXU.js

@@ -0,0 +1,92 @@
+// src/hooks/useModalDialog.ts
+import { useEffect, useRef } from "react";
+var FOCUSABLE_SELECTOR = [
+  "a[href]",
+  "button:not([disabled])",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  '[tabindex]:not([tabindex="-1"])'
+].join(",");
+function isolateModal(root) {
+  const snapshots = [];
+  let branch = root;
+  while (branch?.parentElement) {
+    for (const sibling of branch.parentElement.children) {
+      if (sibling === branch || !(sibling instanceof HTMLElement)) continue;
+      snapshots.push({
+        element: sibling,
+        inert: sibling.inert === true,
+        ariaHidden: sibling.getAttribute("aria-hidden")
+      });
+      sibling.inert = true;
+      sibling.setAttribute("aria-hidden", "true");
+    }
+    branch = branch.parentElement;
+    if (branch === document.body) break;
+  }
+  return snapshots;
+}
+function useModalDialog({
+  rootRef,
+  dialogRef,
+  initialFocusRef,
+  returnFocusRef,
+  onClose
+}) {
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
+  useEffect(() => {
+    const root = rootRef.current;
+    const dialog = dialogRef.current;
+    if (!root || !dialog) return;
+    const previousFocus = returnFocusRef?.current ?? (document.activeElement instanceof HTMLElement ? document.activeElement : null);
+    const inertSnapshots = isolateModal(root);
+    const activeWithinDialog = document.activeElement instanceof HTMLElement && dialog.contains(document.activeElement) ? document.activeElement : null;
+    const focusTarget = initialFocusRef?.current ?? activeWithinDialog ?? dialog.querySelector(FOCUSABLE_SELECTOR) ?? dialog;
+    focusTarget.focus();
+    if (focusTarget instanceof HTMLInputElement || focusTarget instanceof HTMLTextAreaElement) {
+      focusTarget.select();
+    }
+    const handleKeyDown = (event) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        event.stopPropagation();
+        onCloseRef.current();
+        return;
+      }
+      if (event.key !== "Tab") return;
+      const focusable = [...dialog.querySelectorAll(FOCUSABLE_SELECTOR)].filter(
+        (element) => !element.hidden && element.getAttribute("aria-hidden") !== "true" && element.getAttribute("aria-disabled") !== "true"
+      );
+      if (focusable.length === 0) {
+        event.preventDefault();
+        dialog.focus();
+        return;
+      }
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (event.shiftKey && (document.activeElement === first || !dialog.contains(document.activeElement))) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && (document.activeElement === last || !dialog.contains(document.activeElement))) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener("keydown", handleKeyDown, true);
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown, true);
+      for (const snapshot of inertSnapshots) {
+        snapshot.element.inert = snapshot.inert;
+        if (snapshot.ariaHidden === null) snapshot.element.removeAttribute("aria-hidden");
+        else snapshot.element.setAttribute("aria-hidden", snapshot.ariaHidden);
+      }
+      if (previousFocus?.isConnected) previousFocus.focus();
+    };
+  }, [dialogRef, initialFocusRef, returnFocusRef, rootRef]);
+}
+
+export {
+  useModalDialog
+};

package/dist/hooks/index.d.ts

@@ -0,0 +1,187 @@
+import * as react from 'react';
+import { RefObject } from 'react';
+import { AudioTrack, ScheduledClip, Theme, Doc, Block, MediaProvider, SurfaceScheme } from '@bendyline/squisq/schemas';
+import { a as AudioController } from '../AudioController-DwMsPe38.js';
+export { A as AudioActions, b as AudioState } from '../AudioController-DwMsPe38.js';
+import { ViewportConfig, ViewportOrientation } from '@bendyline/squisq/doc';
+import { ResourcePolicy } from '@bendyline/squisq/markdown';
+
+/**
+ * useAudioSync Hook
+ *
+ * Synchronizes playback state with an audio element. Provides current
+ * playback time, playing state, and methods to control audio playback.
+ *
+ * Handles multiple audio segments (MP3 files) by tracking which segment
+ * is currently playing and calculating the overall timeline position.
+ *
+ * This is the HTML5 Audio implementation of the AudioController interface.
+ * Hosts that drive audio through an external player (e.g. a native shell)
+ * can supply their own AudioController to DocPlayer instead of this hook.
+ */
+
+type AudioSyncMode = 'media' | 'synthetic';
+declare function useAudioSync(audioRef: RefObject<HTMLAudioElement>, audioTrack: AudioTrack | undefined, basePath?: string, enabled?: boolean, mode?: AudioSyncMode): AudioController;
+
+interface ModalDialogOptions {
+    /** The backdrop/portal root. Siblings of this branch are made inert. */
+    rootRef: RefObject<HTMLElement | null>;
+    /** The element with `role="dialog"`; focus is trapped within it. */
+    dialogRef: RefObject<HTMLElement | null>;
+    initialFocusRef?: RefObject<HTMLElement | null>;
+    /** Explicit opener/owner to restore after unmount (important when a child uses autofocus). */
+    returnFocusRef?: RefObject<HTMLElement | null>;
+    onClose: () => void;
+}
+/** Shared focus, keyboard, background-isolation, and restoration behavior for modal dialogs. */
+declare function useModalDialog({ rootRef, dialogRef, initialFocusRef, returnFocusRef, onClose, }: ModalDialogOptions): void;
+
+/**
+ * useMediaSchedule
+ *
+ * Pure follower of the playback clock for the media-clip model. Given the
+ * resolved {@link ScheduledClip}s and the current time, it returns the clips
+ * the player should mount and which of them are active right now.
+ * {@link MediaClipLayer} consumes this to drive one hidden `<audio>` /
+ * full-bleed `<video>` element per clip. (Annotation-authored clips all render
+ * at the player level; template-produced `VideoLayer`s are a separate path and
+ * are not part of the schedule.)
+ *
+ * It owns no clock: `currentTime`/`isPlaying` come from the existing
+ * `useAudioSync` provider via `DocPlayer`. With an empty schedule it returns
+ * empty lists, so documents without the new media model are unaffected.
+ */
+
+interface MediaScheduleController {
+    /** Clips the player mounts (every scheduled clip). */
+    renderClips: ScheduledClip[];
+    /** Ids of clips whose [absoluteStart, absoluteEnd) contains currentTime. */
+    activeIds: Set<string>;
+}
+declare function useMediaSchedule(schedule: ScheduledClip[], currentTime: number): MediaScheduleController;
+
+/**
+ * useDocPlayback Hook
+ *
+ * Manages the playback state for a visual doc, including which block
+ * is currently active, transition states, and synchronization with audio.
+ *
+ * This hook provides:
+ * - Current block determination based on time
+ * - Transition tracking (entering/exiting blocks)
+ * - Manual navigation (next/prev block)
+ * - Time-based seeking
+ * - Automatic expansion of template blocks
+ */
+
+interface PlaybackState {
+    /** Currently visible block */
+    currentBlock: Block | null;
+    /** Index of current block */
+    currentBlockIndex: number;
+    /** Previous block (for transitions) */
+    previousBlock: Block | null;
+    /** Whether current block is entering */
+    isEntering: boolean;
+    /** Whether previous block is exiting */
+    isExiting: boolean;
+    /** Time relative to current block start */
+    blockTime: number;
+    /** Progress through current block (0-1) */
+    blockProgress: number;
+    /** Overall progress through doc (0-1) */
+    docProgress: number;
+    /** Expanded blocks (templates converted to full blocks with layers) */
+    blocks: Block[];
+}
+interface PlaybackActions {
+    /** Go to next block */
+    nextBlock: () => void;
+    /** Go to previous block */
+    prevBlock: () => void;
+    /** Go to specific block by index */
+    goToBlock: (index: number) => void;
+    /**
+     * Let the identified block enter without remounting the outgoing block.
+     * Used when another interaction (such as a swipe) already removed it.
+     */
+    suppressOutgoingForNextBlock: (blockId: string) => void;
+}
+interface UseDocPlaybackOptions {
+    /** Target viewport used to materialize template blocks. */
+    viewport?: ViewportConfig;
+    /** Active theme used for materialization and transition defaults. */
+    theme?: Theme;
+    /** Host seek callback used by block navigation actions. */
+    onSeek?: (time: number) => void;
+}
+declare function useDocPlayback(script: Doc | null, currentTime: number, options?: UseDocPlaybackOptions): PlaybackState & PlaybackActions;
+
+/**
+ * useViewportOrientation Hook
+ *
+ * Detects the current viewport orientation and returns the appropriate
+ * VIEWPORT_PRESET for rendering docs. Automatically updates when
+ * the window is resized.
+ *
+ * Thresholds:
+ * - Portrait: height > width * 1.2 (significantly taller than wide)
+ * - Square: width and height within 20% of each other
+ * - Landscape: width > height * 1.2 (significantly wider than tall)
+ */
+
+interface UseViewportOrientationResult {
+    /** Current viewport preset configuration */
+    viewport: ViewportConfig;
+    /** Current orientation name */
+    orientation: ViewportOrientation;
+    /** Current window dimensions */
+    windowSize: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Hook to detect viewport orientation and return appropriate preset.
+ * Updates automatically when window is resized.
+ */
+declare function useViewportOrientation(): UseViewportOrientationResult;
+
+/**
+ * React context holding the current MediaProvider (or null if none provided).
+ */
+declare const MediaContext: react.Context<MediaProvider | null>;
+/**
+ * Policy for document-controlled media URLs. Hosts rendering untrusted
+ * documents can provide `LOCAL_ONLY_RESOURCE_POLICY` or an explicit host
+ * allow-list without changing their MediaProvider.
+ */
+declare const ResourcePolicyContext: react.Context<ResourcePolicy>;
+declare function useResourcePolicy(): ResourcePolicy;
+/**
+ * Hook to access the current MediaProvider from context.
+ * Returns null if no provider is set.
+ */
+declare function useMediaProvider(): MediaProvider | null;
+/**
+ * Hook to resolve a media URL via the MediaProvider (if available),
+ * falling back to basePath-based resolution.
+ *
+ * Returns the resolved URL string. Updates when the provider or path changes.
+ *
+ * @param relativePath - Relative media path from the document (e.g., 'hero.jpg')
+ * @param basePath - Fallback base path for URL construction
+ */
+declare function useMediaUrl(relativePath: string, basePath: string): string;
+
+/**
+ * Live-track `prefers-color-scheme` and return a stable SurfaceScheme.
+ * `enabled: false` short-circuits to LIGHT_SURFACE (callers pass `false`
+ * when a static surface was provided so the hook never observes the
+ * media query). The `MediaQueryList` and the `subscribe`/`getSnapshot`
+ * callbacks are memoized so `useSyncExternalStore` doesn't resubscribe on
+ * every parent render.
+ */
+declare function useAutoSurface(enabled: boolean): SurfaceScheme;
+
+export { AudioController, MediaContext, type MediaScheduleController, type ModalDialogOptions, ResourcePolicyContext, type UseDocPlaybackOptions, useAudioSync, useAutoSurface, useDocPlayback, useMediaProvider, useMediaSchedule, useMediaUrl, useModalDialog, useResourcePolicy, useViewportOrientation };

package/dist/hooks/index.js

@@ -0,0 +1,32 @@
+import {
+  useModalDialog
+} from "../chunk-YQC3AXXU.js";
+import {
+  useAudioSync,
+  useDocPlayback,
+  useMediaSchedule,
+  useViewportOrientation
+} from "../chunk-NWZQGZIJ.js";
+import {
+  useAutoSurface
+} from "../chunk-TT6ENR6T.js";
+import {
+  MediaContext,
+  ResourcePolicyContext,
+  useMediaProvider,
+  useMediaUrl,
+  useResourcePolicy
+} from "../chunk-LR3AIGDD.js";
+export {
+  MediaContext,
+  ResourcePolicyContext,
+  useAudioSync,
+  useAutoSurface,
+  useDocPlayback,
+  useMediaProvider,
+  useMediaSchedule,
+  useMediaUrl,
+  useModalDialog,
+  useResourcePolicy,
+  useViewportOrientation
+};