@bendyline/squisq-react 1.4.0 → 1.4.2

package/README.md

@@ -22,37 +22,54 @@ import { DocPlayer } from '@bendyline/squisq-react';
 import '@bendyline/squisq-react/styles';
 
 function App() {
-  return <DocPlayer doc={myDoc} />;
+  return <DocPlayer markdown={'# Hello\n\nWelcome to Squisq.'} />;
 }
 ```
 
+`DocPlayer` accepts **either** raw `markdown` (parsed and converted internally)
+**or** a parsed `doc`; if you already have a `Doc`, pass `<DocPlayer doc={doc} />`.
+`basePath` is optional (default `'.'`) and is the base URL for resolving relative
+media paths. With neither `markdown` nor `doc`, the player renders a themed empty
+state rather than crashing.
+
+> **v1.5 breaking changes:** the old `script` prop is now `doc`, and the
+> `audioProvider` prop is now `audioController` (its type `AudioProvider` was
+> renamed to `AudioController`). `LinearDocView` gained the same `markdown` prop.
+
 ## Components
 
-| Component              | Description                                                        |
-| ---------------------- | ------------------------------------------------------------------ |
-| `DocPlayer`            | Main document player with timed playback, audio sync, and controls |
-| `LinearDocView`        | Scroll-based linear rendering of all blocks                        |
-| `BlockRenderer`        | SVG-based renderer for a single block                              |
-| `MarkdownRenderer`     | Renders Squisq markdown as a visual document                       |
-| `DocPlayerWithSidebar` | DocPlayer with a sidebar navigation panel                          |
-| `CaptionOverlay`       | Timed caption/subtitle overlay                                     |
-| `DocProgressBar`       | Playback progress indicator                                        |
-| `DocControlsOverlay`   | Floating playback controls                                         |
-| `DocControlsBottom`    | Bottom-bar playback controls                                       |
-| `DocControlsSidebar`   | Sidebar navigation controls                                        |
-| `DocControlsSlideshow` | Slideshow-style navigation controls                                |
+| Component              | Description                                                         |
+| ---------------------- | ------------------------------------------------------------------- |
+| `DocPlayer`            | Main document player with timed playback, audio sync, and controls  |
+| `LinearDocView`        | Scroll-based linear rendering of all blocks                         |
+| `BlockRenderer`        | SVG-based renderer for a single block                               |
+| `MarkdownRenderer`     | Renders Squisq markdown as a visual document                        |
+| `DocPlayerWithSidebar` | DocPlayer with a sidebar navigation panel                           |
+| `CaptionOverlay`       | Timed caption/subtitle overlay                                      |
+| `DocProgressBar`       | Playback progress indicator                                         |
+| `DocControlsOverlay`   | Floating playback controls                                          |
+| `DocControlsBottom`    | Bottom-bar playback controls                                        |
+| `DocControlsSidebar`   | Sidebar navigation controls                                         |
+| `DocControlsSlideshow` | Slideshow-style navigation controls                                 |
+| `SocialCaptionOverlay` | Large centered word-by-word (TikTok/Reels-style) captions           |
+| `InlineVideoPlayer`    | Native `<video>` wrapper resolving `src`/`poster` via MediaContext  |
+| `InlineAudioPlayer`    | Native `<audio>` wrapper resolving `src` via MediaContext           |
+| `MediaClipLayer`       | Hidden `<audio>`/`<video>` elements for timed media clips           |
+| `JsonView`             | Read-only viewer for JSON values bound to a Squisq-annotated schema |
 
 ## Layers
 
 Blocks are composed of typed layers rendered as SVG:
 
-| Layer        | Description                                |
-| ------------ | ------------------------------------------ |
-| `ImageLayer` | Background and foreground images           |
-| `TextLayer`  | Styled text with positioning and animation |
-| `ShapeLayer` | SVG shapes (rectangles, circles, lines)    |
-| `VideoLayer` | Embedded video with playback sync          |
-| `MapLayer`   | Tile-based map rendering                   |
+| Layer        | Description                                   |
+| ------------ | --------------------------------------------- |
+| `ImageLayer` | Background and foreground images              |
+| `TextLayer`  | Styled text with positioning and animation    |
+| `ShapeLayer` | SVG shapes (rectangles, circles, lines)       |
+| `PathLayer`  | Freeform SVG path drawing                     |
+| `VideoLayer` | Embedded video with playback sync             |
+| `TableLayer` | HTML table embedded via SVG `<foreignObject>` |
+| `MapLayer`   | Tile-based map rendering                      |
 
 ## Hooks
 
@@ -60,21 +77,33 @@ Blocks are composed of typed layers rendered as SVG:
 | ---------------------------------- | ------------------------------------------------------------------ |
 | `useDocPlayback`                   | Core playback state machine — timing, block transitions, scripting |
 | `useAudioSync`                     | Synchronizes audio playback with doc timeline                      |
+| `useMediaSchedule`                 | Resolves which timed media clips are active at the current time    |
 | `useViewportOrientation`           | Tracks viewport orientation for responsive layouts                 |
+| `useAutoSurface`                   | Live light/dark surface detection via `prefers-color-scheme`       |
 | `useMediaProvider` / `useMediaUrl` | Media URL resolution via `MediaContext`                            |
 
 ## Standalone Player
 
-A self-contained global build is available for non-React environments:
+A self-contained global build is available for non-React environments. It
+exposes a `SquisqPlayer` global with `mount`, `mountStatic`, `unmount`, and
+`version`:
 
 ```html
 <script src="https://unpkg.com/@bendyline/squisq-react/dist/squisq-player.global.js"></script>
 <div id="player"></div>
 <script>
-  SquisqPlayer.render(document.getElementById('player'), { markdown: '# Hello' });
+  // docJson is a Doc (e.g. produced by markdownToDoc and serialized)
+  SquisqPlayer.mount(document.getElementById('player'), docJson, {
+    mode: 'slideshow', // or 'static' for a scrollable document view
+    basePath: '/',
+  });
 </script>
 ```
 
+For build-time embedding, `@bendyline/squisq-react/standalone-source` exports
+the same bundle as a string constant (`PLAYER_BUNDLE`) — used by
+`@bendyline/squisq-formats` and the CLI to produce single-file HTML exports.
+
 ## Styles
 
 Import the animation CSS for block transitions:
@@ -83,6 +112,11 @@ Import the animation CSS for block transitions:
 import '@bendyline/squisq-react/styles';
 ```
 
+## Full API Reference
+
+See [docs/API.md](https://github.com/bendyline/squisq/blob/main/docs/API.md)
+for the complete prop tables, hook signatures, and types.
+
 ## Related Packages
 
 | Package                                                                                        | Description                                                    |

package/dist/index.d.ts

@@ -8,7 +8,7 @@ import { RefObject } from 'react';
 import { SquisqAnnotatedSchema } from '@bendyline/squisq/jsonForm';
 
 /**
- * AudioProvider - Abstraction for audio playback in DocPlayer
+ * AudioController - 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:
@@ -52,7 +52,7 @@ interface AudioActions {
     /** Restart from beginning */
     restart: () => Promise<void>;
 }
-type AudioProvider = AudioState & AudioActions;
+type AudioController = AudioState & AudioActions;
 
 /**
  * Doc Player Control Types
@@ -131,6 +131,12 @@ interface PlaybackState$1 {
     currentSegmentName: string | null;
     /** Current block data (for extracting image info, etc.) */
     currentBlock: Block | null;
+    /** Optional display label for non-block slides, e.g. the managed cover. */
+    currentSlideLabel?: string;
+    /** Optional human-facing slide number, separate from internal nav index. */
+    currentSlideNumber?: number;
+    /** Optional human-facing slide total, separate from internal nav total. */
+    totalSlideNumber?: number;
 }
 /** Playback actions exposed to external control components */
 interface PlaybackActions$1 {
@@ -209,10 +215,20 @@ type SquisqWindow = Window & typeof globalThis & Partial<SquisqRenderAPI>;
 declare function formatTime(seconds: number): string;
 
 interface DocPlayerProps {
-    /** Doc script to play */
-    script: Doc;
-    /** Base path for resolving media URLs */
-    basePath: string;
+    /**
+     * The Doc to play. Wins over `markdown` when both are provided.
+     * When neither `doc` nor `markdown` is given, the player renders a
+     * minimal themed empty state instead of crashing.
+     */
+    doc?: Doc;
+    /**
+     * Markdown source to play. When `doc` is absent, the markdown is parsed
+     * and converted to a Doc via `markdownToDoc(parseMarkdown(markdown))`.
+     * Ignored when `doc` is provided.
+     */
+    markdown?: string;
+    /** Base path for resolving media URLs (default: `'.'`) */
+    basePath?: string;
     /** Render mode for video capture (hides controls, exposes seekTo) */
     renderMode?: boolean;
     /** Auto-play when loaded */
@@ -221,8 +237,8 @@ interface DocPlayerProps {
     onEnded?: () => void;
     /** Callback for time updates */
     onTimeUpdate?: (time: number) => void;
-    /** Optional audio provider (if not provided, uses default HTML5 audio) */
-    audioProvider?: AudioProvider;
+    /** Optional audio controller (if not provided, uses default HTML5 audio) */
+    audioController?: AudioController;
     /** 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).
@@ -270,11 +286,29 @@ interface DocPlayerProps {
      *   template-annotated sections as inline SVG cards. No audio, no timeline.
      */
     displayMode?: DisplayMode;
+    /**
+     * Whether to synthesize and show the managed cover slide from
+     * `doc.startBlock`. Defaults to true for existing documents.
+     */
+    showCoverSlide?: boolean;
     /** Caption display style (default: 'standard').
      *  'social' shows large centered words with the active word highlighted. */
     captionStyle?: CaptionStyle;
+    /**
+     * Enable drag-to-swipe slide navigation in slideshow mode (default: true).
+     * When enabled, press-and-drag on a slide advances/rewinds on release past a
+     * threshold (or a quick flick), and snaps back otherwise. Only applies when
+     * `displayMode === 'slideshow'` and not in render/headless mode.
+     */
+    enableSwipe?: boolean;
 }
-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, surface, captionStyle, }: DocPlayerProps): react_jsx_runtime.JSX.Element;
+/**
+ * Front-door component: resolves the `doc` / `markdown` props into a Doc
+ * and renders a themed empty state when neither is provided. The playback
+ * machinery lives in `DocPlayerContent` so its hook order never changes
+ * when a doc appears or disappears.
+ */
+declare function DocPlayer(props: DocPlayerProps): react_jsx_runtime.JSX.Element;
 
 /** Default viewport dimensions (1080p landscape) - for backwards compatibility */
 declare const VIEWPORT: {
@@ -364,12 +398,15 @@ interface DocControlsSlideshowProps {
 declare function DocControlsSlideshow({ state, slideNav }: DocControlsSlideshowProps): react_jsx_runtime.JSX.Element;
 
 interface DocPlayerWithSidebarProps {
-    script: Doc;
-    basePath: string;
+    /** The Doc to play */
+    doc: Doc;
+    /** Base path for resolving media URLs (default: `'.'`) */
+    basePath?: string;
     autoPlay?: boolean;
     onEnded?: () => void;
     onTimeUpdate?: (time: number) => void;
-    audioProvider?: AudioProvider;
+    /** Optional audio controller (if not provided, uses default HTML5 audio) */
+    audioController?: AudioController;
     muted?: boolean;
     captionsEnabled?: boolean;
     isFullscreen?: boolean;
@@ -378,8 +415,15 @@ interface DocPlayerWithSidebarProps {
     forceViewport?: ViewportConfig$1;
     /** Called when playing state changes */
     onPlayingChange?: (isPlaying: boolean) => void;
+    /**
+     * Theme for rendering. Forwarded to the inner DocPlayer so the sidebar
+     * (portrait) layout matches the default (landscape) layout — without it the
+     * inner player falls back to DEFAULT_THEME, whose dark text is unreadable
+     * over a hero cover image.
+     */
+    theme?: Theme;
 }
-declare function DocPlayerWithSidebar({ script, basePath, autoPlay, onEnded, onTimeUpdate, audioProvider, muted, captionsEnabled, isFullscreen, onFullscreenToggle, forceViewport, onPlayingChange, }: DocPlayerWithSidebarProps): react_jsx_runtime.JSX.Element;
+declare function DocPlayerWithSidebar({ doc, basePath, autoPlay, onEnded, onTimeUpdate, audioController, muted, captionsEnabled, isFullscreen, onFullscreenToggle, forceViewport, onPlayingChange, theme, }: DocPlayerWithSidebarProps): react_jsx_runtime.JSX.Element;
 
 interface DocProgressBarProps {
     state: PlaybackState$1;
@@ -402,6 +446,12 @@ interface MarkdownRendererProps {
      * event handlers, and executable URL schemes before rendering.
      */
     htmlPolicy?: HtmlPolicy;
+    /**
+     * Extra URL schemes to allow on links (e.g. a host app's internal
+     * navigation scheme it intercepts on click). Executable schemes are
+     * never allowed regardless. See {@link SanitizeUrlOptions}.
+     */
+    linkSchemes?: readonly string[];
 }
 /**
  * Renders MarkdownBlockNode[] AST as React HTML elements.
@@ -411,11 +461,20 @@ interface MarkdownRendererProps {
  * <MarkdownRenderer nodes={block.contents} />
  * ```
  */
-declare function MarkdownRenderer({ nodes, className, htmlPolicy, }: MarkdownRendererProps): react_jsx_runtime.JSX.Element | null;
+declare function MarkdownRenderer({ nodes, className, htmlPolicy, linkSchemes, }: MarkdownRendererProps): react_jsx_runtime.JSX.Element | null;
 
 interface LinearDocViewProps {
-    /** The Doc to render */
-    doc: Doc;
+    /**
+     * The Doc to render. Wins over `markdown` when both are provided.
+     * When neither `doc` nor `markdown` is given, an empty container renders.
+     */
+    doc?: Doc;
+    /**
+     * Markdown source to render. When `doc` is absent, the markdown is parsed
+     * and converted to a Doc via `markdownToDoc(parseMarkdown(markdown))`.
+     * Ignored when `doc` is provided.
+     */
+    markdown?: string;
     /** Base path for resolving media URLs (images, etc.) */
     basePath?: string;
     /** Viewport config for SVG card rendering (default: landscape) */
@@ -463,7 +522,7 @@ type ImageDisplayMode = 'inline' | 'thumbnail';
  * <LinearDocView doc={doc} basePath="/media/" />
  * ```
  */
-declare function LinearDocView({ doc, basePath, viewport, className, theme, surface, thinMargins, imageDisplayMode, }: LinearDocViewProps): react_jsx_runtime.JSX.Element;
+declare function LinearDocView({ doc, markdown, basePath, viewport, className, theme, surface, thinMargins, imageDisplayMode, }: LinearDocViewProps): react_jsx_runtime.JSX.Element;
 
 interface InlineVideoPlayerProps {
     /** Source path — resolved through MediaContext when relative. */
@@ -613,11 +672,12 @@ declare function MediaClipLayer({ schedule, currentTime, isPlaying, basePath, re
  * 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.
+ * 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.
  */
 
-declare function useAudioSync(audioRef: RefObject<HTMLAudioElement>, audioTrack: AudioTrack | undefined, basePath?: string): AudioProvider;
+declare function useAudioSync(audioRef: RefObject<HTMLAudioElement>, audioTrack: AudioTrack | undefined, basePath?: string): AudioController;
 
 /**
  * useMediaSchedule
@@ -763,4 +823,4 @@ interface JsonViewProps {
 }
 declare function JsonView(props: JsonViewProps): react_jsx_runtime.JSX.Element;
 
-export { type AudioActions, type AudioProvider, type AudioState, type BlockMarker, BlockRenderer, type CaptionMode, CaptionOverlay, type CaptionStyle, type ControlsLayout, type DisplayMode, DocControlsBottom, DocControlsOverlay, DocControlsSidebar, DocControlsSlideshow, DocPlayer, DocPlayerWithSidebar, DocProgressBar, type ImageDisplayMode, ImageLayer, InlineAudioPlayer, type InlineAudioPlayerProps, InlineVideoPlayer, type InlineVideoPlayerProps, JsonView, type JsonViewProps, LinearDocView, type LinearDocViewProps, MapLayer, MarkdownRenderer, MediaClipLayer, type MediaClipLayerProps, MediaContext, type MediaScheduleController, PathLayer, type PlaybackActions$1 as PlaybackActions, type PlaybackState$1 as PlaybackState, type RenderAudioSegmentInfo, type RenderBlockInfo, type RenderCaptionInfo, type RenderChapterInfo, ShapeLayer, type SlideNavActions, SocialCaptionOverlay, type SquisqRenderAPI, type SquisqWindow, TableLayer, TextLayer, VIEWPORT, VideoLayer, formatTime, useAudioSync, useAutoSurface, useDocPlayback, useMediaProvider, useMediaSchedule, useMediaUrl, useViewportOrientation };
+export { type AudioActions, type AudioController, type AudioState, type BlockMarker, BlockRenderer, type CaptionMode, CaptionOverlay, type CaptionStyle, type ControlsLayout, type DisplayMode, DocControlsBottom, DocControlsOverlay, DocControlsSidebar, DocControlsSlideshow, DocPlayer, DocPlayerWithSidebar, DocProgressBar, type ImageDisplayMode, ImageLayer, InlineAudioPlayer, type InlineAudioPlayerProps, InlineVideoPlayer, type InlineVideoPlayerProps, JsonView, type JsonViewProps, LinearDocView, type LinearDocViewProps, MapLayer, MarkdownRenderer, MediaClipLayer, type MediaClipLayerProps, MediaContext, type MediaScheduleController, PathLayer, type PlaybackActions$1 as PlaybackActions, type PlaybackState$1 as PlaybackState, type RenderAudioSegmentInfo, type RenderBlockInfo, type RenderCaptionInfo, type RenderChapterInfo, ShapeLayer, type SlideNavActions, SocialCaptionOverlay, type SquisqRenderAPI, type SquisqWindow, TableLayer, TextLayer, VIEWPORT, VideoLayer, formatTime, useAudioSync, useAutoSurface, useDocPlayback, useMediaProvider, useMediaSchedule, useMediaUrl, useViewportOrientation };