@bendyline/squisq-react 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,563 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Block, Doc, Theme, CaptionTrack, ViewportConfig as ViewportConfig$1, ImageLayer as ImageLayer$1, TextLayer as TextLayer$1, ShapeLayer as ShapeLayer$1, VideoLayer as VideoLayer$1, MapLayer as MapLayer$1, AudioTrack, MediaProvider } from '@bendyline/squisq/schemas';
+import { ViewportConfig, ViewportOrientation } from '@bendyline/squisq/doc';
+export { getAnimationStyle, getTransitionClass } from '@bendyline/squisq/doc';
+import { MarkdownBlockNode } from '@bendyline/squisq/markdown';
+import * as react from 'react';
+import { RefObject } from 'react';
+
+/**
+ * AudioProvider - Abstraction for audio playback in DocPlayer
+ *
+ * This module defines an interface for audio playback operations that can have
+ * different implementations depending on the runtime environment:
+ *
+ * - Site/Browser: Uses HTML5 Audio element directly
+ * - EFB/MSFS: Routes through CompanionAPI to Electron app
+ *
+ * The DocPlayer uses this abstraction instead of directly manipulating audio,
+ * allowing the same component code to work in both environments.
+ */
+
+interface AudioState {
+    /** Current time in overall timeline (seconds) */
+    currentTime: number;
+    /** Whether audio is currently playing */
+    isPlaying: boolean;
+    /** Index of current audio segment */
+    currentSegment: number;
+    /** Total duration of all segments */
+    totalDuration: number;
+    /** Whether audio has finished */
+    isEnded: boolean;
+    /** Whether audio is loaded and ready to play */
+    isReady: boolean;
+    /** Whether the audio backend is available/connected */
+    isAvailable: boolean;
+    /** Message to show when not available */
+    unavailableMessage?: string;
+}
+interface AudioActions {
+    /** Start or resume playback */
+    play: () => Promise<void>;
+    /** Pause playback */
+    pause: () => Promise<void>;
+    /** Toggle play/pause */
+    toggle: () => Promise<void>;
+    /** Seek to specific time in timeline */
+    seekTo: (time: number) => Promise<void>;
+    /** Skip to specific segment */
+    skipToSegment: (index: number) => Promise<void>;
+    /** Restart from beginning */
+    restart: () => Promise<void>;
+}
+type AudioProvider = AudioState & AudioActions;
+
+/**
+ * Doc Player Control Types
+ *
+ * Shared type definitions for doc player controls across different
+ * layout modes (overlay, sidebar, bottom). These interfaces allow
+ * control components to be decoupled from the core DocPlayer.
+ *
+ * Related Files:
+ * - DocPlayer.tsx — Core player component
+ * - DocProgressBar.tsx — Extracted progress bar
+ * - DocControlsOverlay.tsx — Overlay controls (default)
+ * - DocControlsSidebar.tsx — Vertical sidebar controls
+ * - DocControlsBottom.tsx — Horizontal bottom strip controls
+ */
+
+/** Layout mode for doc player controls */
+type ControlsLayout = 'overlay' | 'sidebar' | 'bottom';
+/**
+ * Display mode for DocPlayer.
+ *
+ * - `'video'` — Traditional video-style playback with play/pause, scrub bar,
+ *   and time-based auto-advance. Default mode.
+ * - `'slideshow'` — PowerPoint-style presentation with prev/next navigation.
+ *   Blocks are treated as static slides that only change on user click.
+ *   No auto-advance, no scrub bar.
+ * - `'linear'` — Long-scrolling document view. Renders the full markdown as
+ *   readable HTML with template-annotated sections shown as inline SVG cards.
+ *   No audio, no timeline, no controls — just a scrollable page.
+ */
+type DisplayMode = 'video' | 'slideshow' | 'linear';
+/** Slide navigation actions for slideshow display mode */
+interface SlideNavActions {
+    /** Navigate to the next slide */
+    nextSlide: () => void;
+    /** Navigate to the previous slide */
+    prevSlide: () => void;
+    /** Navigate to a specific slide by index (0-based) */
+    goToSlide: (index: number) => void;
+}
+/** Playback state exposed to external control components */
+interface PlaybackState$1 {
+    isPlaying: boolean;
+    currentTime: number;
+    totalDuration: number;
+    currentBlockIndex: number;
+    totalBlocks: number;
+    docProgress: number;
+    hasCaptions: boolean;
+    captionsEnabled: boolean;
+    isFullscreen?: boolean;
+    /** Current audio segment index (0-based) */
+    currentSegmentIndex: number;
+    /** Current audio segment name (e.g., 'intro', 'history') */
+    currentSegmentName: string | null;
+    /** Current block data (for extracting image info, etc.) */
+    currentBlock: Block | null;
+}
+/** Playback actions exposed to external control components */
+interface PlaybackActions$1 {
+    toggle: () => void;
+    restart: () => void;
+    seekTo: (time: number) => void;
+    setCaptionsEnabled: (enabled: boolean) => void;
+    toggleFullscreen?: () => void;
+}
+/** Block marker data for the progress bar */
+interface BlockMarker {
+    block: Block;
+    index: number;
+    position: number;
+    title: string;
+    /** True if this block is the first in a new audio segment (section boundary) */
+    isSectionStart: boolean;
+}
+/** Block metadata returned by SquisqRenderAPI.getBlocks() */
+interface RenderBlockInfo {
+    id: string;
+    template: string;
+    startTime: number;
+    duration: number;
+}
+/** Audio segment info returned by SquisqRenderAPI.getAudioSegments() */
+interface RenderAudioSegmentInfo {
+    src: string;
+    name: string;
+    duration: number;
+    startTime: number;
+}
+/** Caption phrase info returned by SquisqRenderAPI.getCaptions() */
+interface RenderCaptionInfo {
+    text: string;
+    startTime: number;
+    endTime: number;
+}
+/** Chapter marker returned by SquisqRenderAPI.getChapters() */
+interface RenderChapterInfo {
+    title: string;
+    startTime: number;
+    duration: number;
+}
+/**
+ * API surface exposed on `window` in render mode and debug mode.
+ * Used by Playwright for video export and by ?debug=true for testing.
+ *
+ * @example
+ * ```ts
+ * // In Playwright:
+ * const w = window as unknown as SquisqWindow;
+ * await w.seekTo!(5.0);
+ * const blocks = w.getBlocks!();
+ * ```
+ */
+interface SquisqRenderAPI {
+    seekTo: (time: number) => Promise<void>;
+    getDuration: () => number;
+    getBlocks: () => RenderBlockInfo[];
+    getAudioSegments: () => RenderAudioSegmentInfo[];
+    getCaptions: () => RenderCaptionInfo[];
+    getChapters: () => RenderChapterInfo[];
+    showCover: () => Promise<void>;
+    hideCover: () => Promise<void>;
+    hasCoverBlock: () => boolean;
+}
+/**
+ * Window augmented with optional SquisqRenderAPI properties.
+ * Each property is optional because they're only present in render/debug mode.
+ */
+type SquisqWindow = Window & typeof globalThis & Partial<SquisqRenderAPI>;
+/** Format time in seconds to MM:SS string */
+declare function formatTime(seconds: number): string;
+
+interface DocPlayerProps {
+    /** Doc script to play */
+    script: Doc;
+    /** Base path for resolving media URLs */
+    basePath: string;
+    /** Render mode for video capture (hides controls, exposes seekTo) */
+    renderMode?: boolean;
+    /** Auto-play when loaded */
+    autoPlay?: boolean;
+    /** Callback when playback ends */
+    onEnded?: () => void;
+    /** Callback for time updates */
+    onTimeUpdate?: (time: number) => void;
+    /** Optional audio provider (if not provided, uses default HTML5 audio) */
+    audioProvider?: AudioProvider;
+    /** Show built-in controls (default: true). Set to false for custom controls. */
+    showControls?: boolean;
+    /** Show only the progress bar/scrubber at bottom (no other controls).
+     *  Only takes effect when showControls is false. Allows external controls
+     *  while keeping the scrubber in-video. */
+    showScrubber?: boolean;
+    /** Mute audio (default: false) */
+    muted?: boolean;
+    /** Enable captions (default: true) */
+    captionsEnabled?: boolean;
+    /** Callback when captions enabled state is toggled */
+    onCaptionsToggle?: (enabled: boolean) => void;
+    /** Callback for playback state changes (for external controls) */
+    onPlaybackStateChange?: (state: PlaybackState$1) => void;
+    /** Callback when playback controls are ready (for external controls) */
+    onControlsReady?: (controls: PlaybackActions$1 & {
+        play: () => void;
+        pause: () => void;
+    }) => void;
+    /** Whether the player is currently in fullscreen mode */
+    isFullscreen?: boolean;
+    /** Callback to toggle fullscreen mode */
+    onFullscreenToggle?: () => void;
+    /** Callback when block markers are computed (for external progress bars) */
+    onBlockMarkers?: (markers: BlockMarker[]) => void;
+    /** Force a specific viewport preset, bypassing window-based orientation detection.
+     *  Used when the player is rendered in a constrained container (e.g., map overlay panel)
+     *  whose shape differs from the window's. */
+    forceViewport?: ViewportConfig;
+    /** Theme to use for rendering (default: DEFAULT_THEME from the theme library) */
+    theme?: Theme;
+    /**
+     * Display mode for the player.
+     * - `'video'` (default) — Traditional video playback with play/pause, scrub bar, auto-advance.
+     * - `'slideshow'` — PowerPoint-style with prev/next buttons. Blocks are static slides
+     *   that only change on user click. No auto-advance, no scrub bar.
+     * - `'linear'` — Long-scrolling document view. Renders markdown as readable HTML with
+     *   template-annotated sections as inline SVG cards. No audio, no timeline.
+     */
+    displayMode?: DisplayMode;
+}
+declare function DocPlayer({ script, basePath, renderMode, autoPlay, onEnded, onTimeUpdate, audioProvider: externalAudioProvider, showControls, showScrubber, muted, captionsEnabled: captionsEnabledProp, onCaptionsToggle, onPlaybackStateChange, onControlsReady, isFullscreen, onFullscreenToggle, onBlockMarkers, forceViewport, displayMode, theme, }: DocPlayerProps): react_jsx_runtime.JSX.Element;
+
+/** Default viewport dimensions (1080p landscape) - for backwards compatibility */
+declare const VIEWPORT: {
+    width: number;
+    height: number;
+};
+/** Viewport configuration type */
+interface ViewportDimensions {
+    width: number;
+    height: number;
+}
+interface BlockRendererProps {
+    /** The block to render */
+    block: Block;
+    /** Current time relative to block start (seconds) */
+    blockTime: number;
+    /** Base path for resolving media URLs */
+    basePath: string;
+    /** Whether this block is entering (for transition) */
+    isEntering?: boolean;
+    /** Whether this block is exiting (for transition) */
+    isExiting?: boolean;
+    /** Viewport dimensions (defaults to 1920x1080 landscape) */
+    viewport?: ViewportDimensions;
+    /** Whether the doc is currently playing (controls video playback) */
+    isPlaying?: boolean;
+}
+declare function BlockRenderer({ block, blockTime, basePath, isEntering, isExiting, viewport, isPlaying, }: BlockRendererProps): react_jsx_runtime.JSX.Element;
+
+interface CaptionOverlayProps {
+    /** Caption track with timestamped phrases */
+    captions: CaptionTrack | undefined;
+    /** Current playback time in seconds */
+    currentTime: number;
+    /** Whether captions are enabled */
+    enabled?: boolean;
+    /** Font size in pixels (default: 16) */
+    fontSize?: number;
+}
+declare function CaptionOverlay({ captions, currentTime, enabled, fontSize, }: CaptionOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface DocControlsOverlayProps {
+    state: PlaybackState$1;
+    actions: PlaybackActions$1;
+    blockMarkers: BlockMarker[];
+    expandedBlocks: Block[];
+    getBlockTitle?: (block: Block) => string;
+}
+declare function DocControlsOverlay({ state, actions, blockMarkers, expandedBlocks, getBlockTitle, }: DocControlsOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface DocControlsBottomProps {
+    state: PlaybackState$1;
+    actions: PlaybackActions$1;
+    blockMarkers: BlockMarker[];
+    expandedBlocks: Block[];
+    getBlockTitle?: (block: Block) => string;
+}
+declare function DocControlsBottom({ state, actions, blockMarkers, expandedBlocks, getBlockTitle, }: DocControlsBottomProps): react_jsx_runtime.JSX.Element;
+
+interface DocControlsSidebarProps {
+    state: PlaybackState$1;
+    actions: PlaybackActions$1;
+}
+declare function DocControlsSidebar({ state, actions }: DocControlsSidebarProps): react_jsx_runtime.JSX.Element;
+
+interface DocControlsSlideshowProps {
+    state: PlaybackState$1;
+    slideNav: SlideNavActions;
+}
+declare function DocControlsSlideshow({ state, slideNav }: DocControlsSlideshowProps): react_jsx_runtime.JSX.Element;
+
+interface DocPlayerWithSidebarProps {
+    script: Doc;
+    basePath: string;
+    autoPlay?: boolean;
+    onEnded?: () => void;
+    onTimeUpdate?: (time: number) => void;
+    audioProvider?: AudioProvider;
+    muted?: boolean;
+    captionsEnabled?: boolean;
+    isFullscreen?: boolean;
+    onFullscreenToggle?: () => void;
+    /** Force a specific viewport preset, bypassing window-based orientation detection. */
+    forceViewport?: ViewportConfig$1;
+    /** Called when playing state changes */
+    onPlayingChange?: (isPlaying: boolean) => void;
+}
+declare function DocPlayerWithSidebar({ script, basePath, autoPlay, onEnded, onTimeUpdate, audioProvider, muted, captionsEnabled, isFullscreen, onFullscreenToggle, forceViewport, onPlayingChange, }: DocPlayerWithSidebarProps): react_jsx_runtime.JSX.Element;
+
+interface DocProgressBarProps {
+    state: PlaybackState$1;
+    actions: PlaybackActions$1;
+    blockMarkers: BlockMarker[];
+    /** All expanded blocks for hover lookup */
+    expandedBlocks: Block[];
+    /** Optional: get block title for hover tooltip */
+    getBlockTitle?: (block: Block) => string;
+}
+declare function DocProgressBar({ state, actions, blockMarkers, expandedBlocks, getBlockTitle, }: DocProgressBarProps): react_jsx_runtime.JSX.Element;
+
+interface MarkdownRendererProps {
+    /** Block-level AST nodes to render */
+    nodes: MarkdownBlockNode[];
+    /** Optional CSS class for the wrapper element */
+    className?: string;
+}
+/**
+ * Renders MarkdownBlockNode[] AST as React HTML elements.
+ *
+ * @example
+ * ```tsx
+ * <MarkdownRenderer nodes={block.contents} />
+ * ```
+ */
+declare function MarkdownRenderer({ nodes, className }: MarkdownRendererProps): react_jsx_runtime.JSX.Element | null;
+
+interface LinearDocViewProps {
+    /** The Doc to render */
+    doc: Doc;
+    /** Base path for resolving media URLs (images, etc.) */
+    basePath?: string;
+    /** Viewport config for SVG card rendering (default: landscape) */
+    viewport?: ViewportConfig$1;
+    /** Optional CSS class for the outer container */
+    className?: string;
+    /** Theme to use for rendering (default: DEFAULT_THEME from the theme library) */
+    theme?: Theme;
+}
+/**
+ * Renders a Doc as a long-scrolling, readable document.
+ *
+ * Non-annotated blocks are rendered as HTML text (headings, paragraphs,
+ * lists, etc.) via MarkdownRenderer. Template-annotated blocks are
+ * rendered as inline SVG visual cards via BlockRenderer.
+ *
+ * @example
+ * ```tsx
+ * <LinearDocView doc={doc} basePath="/media/" />
+ * ```
+ */
+declare function LinearDocView({ doc, basePath, viewport, className, theme, }: LinearDocViewProps): react_jsx_runtime.JSX.Element;
+
+interface ImageLayerProps {
+    layer: ImageLayer$1;
+    /** Base path for resolving relative image URLs */
+    basePath: string;
+    /** Viewport dimensions for percentage calculations */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Current time relative to block start (for animation timing) */
+    blockTime: number;
+}
+declare function ImageLayer({ layer, basePath, viewport, blockTime }: ImageLayerProps): react_jsx_runtime.JSX.Element;
+
+interface TextLayerProps {
+    layer: TextLayer$1;
+    /** Viewport dimensions for percentage calculations */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Current time relative to block start */
+    blockTime: number;
+}
+declare function TextLayer({ layer, viewport, blockTime }: TextLayerProps): react_jsx_runtime.JSX.Element;
+
+interface ShapeLayerProps {
+    layer: ShapeLayer$1;
+    /** Viewport dimensions for percentage calculations */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Current time relative to block start */
+    blockTime: number;
+}
+declare function ShapeLayer({ layer, viewport, blockTime }: ShapeLayerProps): react_jsx_runtime.JSX.Element;
+
+interface VideoLayerProps {
+    layer: VideoLayer$1;
+    /** Base path for resolving relative video URLs */
+    basePath: string;
+    /** Viewport dimensions for percentage calculations */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Current time relative to block start (for playback sync) */
+    blockTime: number;
+    /** Whether the doc is currently playing */
+    isPlaying?: boolean;
+}
+declare function VideoLayer({ layer, basePath, viewport, blockTime: _blockTime, isPlaying, }: VideoLayerProps): react_jsx_runtime.JSX.Element;
+
+interface MapLayerProps {
+    layer: MapLayer$1;
+    /** Base path for resolving relative image URLs */
+    basePath: string;
+    /** Viewport dimensions for percentage calculations */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Current time relative to block start (for animation timing) */
+    blockTime: number;
+}
+declare function MapLayer({ layer, basePath, viewport, blockTime }: MapLayerProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * 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 AudioProvider interface.
+ * For EFB/MSFS environments, use useCompanionAudioSync instead.
+ */
+
+declare function useAudioSync(audioRef: RefObject<HTMLAudioElement>, audioTrack: AudioTrack | undefined, basePath?: string): AudioProvider;
+
+/**
+ * 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;
+}
+declare function useDocPlayback(script: Doc | null, currentTime: number, viewport?: ViewportConfig, renderMode?: boolean, theme?: Theme): 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>;
+/**
+ * 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;
+
+export { type AudioActions, type AudioProvider, type AudioState, type BlockMarker, BlockRenderer, CaptionOverlay, type ControlsLayout, type DisplayMode, DocControlsBottom, DocControlsOverlay, DocControlsSidebar, DocControlsSlideshow, DocPlayer, DocPlayerWithSidebar, DocProgressBar, ImageLayer, LinearDocView, MapLayer, MarkdownRenderer, MediaContext, type PlaybackActions$1 as PlaybackActions, type PlaybackState$1 as PlaybackState, type RenderAudioSegmentInfo, type RenderBlockInfo, type RenderCaptionInfo, type RenderChapterInfo, ShapeLayer, type SlideNavActions, type SquisqRenderAPI, type SquisqWindow, TextLayer, VIEWPORT, VideoLayer, formatTime, useAudioSync, useDocPlayback, useMediaProvider, useMediaUrl, useViewportOrientation };