@bendyline/squisq-react 0.1.2

package/src/DocPlayerWithSidebar.tsx

@@ -0,0 +1,138 @@
+/**
+ * DocPlayerWithSidebar Component
+ *
+ * Wrapper that composes DocPlayer + DocControlsSidebar in a horizontal
+ * flex layout. The video renders on the left with only a scrubber at the
+ * bottom, and playback controls render in a vertical sidebar on the right.
+ *
+ * This layout eliminates black bars for portrait (9:16) video in portrait
+ * viewports by placing controls in the space that would otherwise be unused.
+ *
+ * Uses refs + forceUpdate pattern to avoid infinite render loops between
+ * the DocPlayer's callbacks and this component's state. The DocPlayer
+ * fires onPlaybackStateChange frequently (every currentTime tick), so we
+ * store state in a ref and only trigger re-renders at controlled intervals.
+ *
+ * Related Files:
+ * - DocPlayer.tsx -- Core player (renders with showControls=false, showScrubber=true)
+ * - DocControlsSidebar.tsx -- Vertical sidebar controls
+ */
+
+import { useRef, useState, useCallback, useEffect } from 'react';
+import type { Doc } from '@bendyline/squisq/schemas';
+import type { ViewportConfig } from '@bendyline/squisq/schemas';
+import type { AudioProvider } from './hooks/AudioProvider';
+import { DocPlayer } from './DocPlayer';
+import { DocControlsSidebar } from './DocControlsSidebar';
+import type { PlaybackState, PlaybackActions } from './types';
+
+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;
+  /** Called when playing state changes */
+  onPlayingChange?: (isPlaying: boolean) => void;
+}
+
+const DEFAULT_STATE: PlaybackState = {
+  isPlaying: false,
+  currentTime: 0,
+  totalDuration: 0,
+  currentBlockIndex: 0,
+  totalBlocks: 0,
+  docProgress: 0,
+  hasCaptions: false,
+  captionsEnabled: false,
+  currentSegmentIndex: 0,
+  currentSegmentName: null,
+  currentBlock: null,
+};
+
+export function DocPlayerWithSidebar({
+  script,
+  basePath,
+  autoPlay = false,
+  onEnded,
+  onTimeUpdate,
+  audioProvider,
+  muted,
+  captionsEnabled,
+  isFullscreen,
+  onFullscreenToggle,
+  forceViewport,
+  onPlayingChange,
+}: DocPlayerWithSidebarProps) {
+  // Store playback state in a ref to avoid triggering re-renders from DocPlayer callbacks
+  const stateRef = useRef<PlaybackState>(DEFAULT_STATE);
+  const actionsRef = useRef<PlaybackActions | null>(null);
+  const wasPlayingRef = useRef(false);
+
+  // Use a counter to force sidebar re-renders at controlled intervals
+  const [, setTick] = useState(0);
+
+  // Update ref without triggering re-render
+  const handleStateChange = useCallback(
+    (state: PlaybackState) => {
+      stateRef.current = state;
+      if (onPlayingChange && state.isPlaying !== wasPlayingRef.current) {
+        wasPlayingRef.current = state.isPlaying;
+        onPlayingChange(state.isPlaying);
+      }
+    },
+    [onPlayingChange],
+  );
+
+  const handleControlsReady = useCallback(
+    (controls: PlaybackActions & { play: () => void; pause: () => void }) => {
+      const isFirst = !actionsRef.current;
+      actionsRef.current = controls;
+      // Force one re-render on first call to show the sidebar
+      if (isFirst) setTick((t) => t + 1);
+    },
+    [],
+  );
+
+  // Periodically sync the ref to trigger sidebar UI updates
+  useEffect(() => {
+    const interval = setInterval(() => {
+      setTick((t) => t + 1);
+    }, 250); // 4 updates per second is smooth enough for time/progress display
+    return () => clearInterval(interval);
+  }, []);
+
+  return (
+    <div className="doc-player-sidebar-layout">
+      <div className="doc-player-sidebar-layout__video">
+        <DocPlayer
+          script={script}
+          basePath={basePath}
+          autoPlay={autoPlay}
+          onEnded={onEnded}
+          onTimeUpdate={onTimeUpdate}
+          audioProvider={audioProvider}
+          muted={muted}
+          captionsEnabled={captionsEnabled}
+          showControls={isFullscreen}
+          showScrubber={!isFullscreen}
+          onPlaybackStateChange={handleStateChange}
+          onControlsReady={handleControlsReady}
+          isFullscreen={isFullscreen}
+          onFullscreenToggle={onFullscreenToggle}
+          forceViewport={forceViewport}
+        />
+      </div>
+      {actionsRef.current && (
+        <DocControlsSidebar state={stateRef.current} actions={actionsRef.current} />
+      )}
+    </div>
+  );
+}

package/src/DocProgressBar.tsx

@@ -0,0 +1,200 @@
+/**
+ * DocProgressBar Component
+ *
+ * Interactive progress/scrubber bar for doc playback. Shows a track with
+ * progress fill, block markers as clickable dots, hover tooltip with time
+ * and block title, and a hover line indicator.
+ *
+ * Extracted from DocPlayer to enable reuse across different control layouts
+ * (overlay, sidebar, bottom). When used in sidebar/bottom layouts, this
+ * component renders at the bottom of the video while other controls are
+ * externalized.
+ *
+ * Related Files:
+ * - DocPlayer.tsx -- Parent component
+ * - DocControlsOverlay.tsx -- Uses this within the overlay
+ * - types.ts -- Shared type definitions
+ */
+
+import { useRef, useState, useCallback } from 'react';
+import type { PlaybackState, PlaybackActions, BlockMarker } from './types';
+import { formatTime } from './types';
+import type { Block } from '@bendyline/squisq/schemas';
+
+interface DocProgressBarProps {
+  state: PlaybackState;
+  actions: PlaybackActions;
+  blockMarkers: BlockMarker[];
+  /** All expanded blocks for hover lookup */
+  expandedBlocks: Block[];
+  /** Optional: get block title for hover tooltip */
+  getBlockTitle?: (block: Block) => string;
+}
+
+export function DocProgressBar({
+  state,
+  actions,
+  blockMarkers,
+  expandedBlocks,
+  getBlockTitle,
+}: DocProgressBarProps) {
+  const progressBarRef = useRef<HTMLDivElement>(null);
+  const [hoverPosition, setHoverPosition] = useState<number | null>(null);
+
+  const handleProgressHover = useCallback((e: React.MouseEvent) => {
+    const bar = progressBarRef.current;
+    if (!bar) return;
+    const rect = bar.getBoundingClientRect();
+    const x = e.clientX - rect.left;
+    const progress = Math.max(0, Math.min(1, x / rect.width));
+    setHoverPosition(progress);
+  }, []);
+
+  const handleProgressLeave = useCallback(() => {
+    setHoverPosition(null);
+  }, []);
+
+  const getBlockAtTimeLocal = useCallback(
+    (time: number): { block: Block; index: number } | null => {
+      for (let i = expandedBlocks.length - 1; i >= 0; i--) {
+        const blk = expandedBlocks[i];
+        if (time >= blk.startTime) {
+          return { block: blk, index: i };
+        }
+      }
+      return expandedBlocks.length > 0 ? { block: expandedBlocks[0], index: 0 } : null;
+    },
+    [expandedBlocks],
+  );
+
+  return (
+    <div
+      ref={progressBarRef}
+      style={{
+        flex: 1,
+        height: '24px',
+        cursor: 'pointer',
+        position: 'relative',
+        display: 'flex',
+        alignItems: 'center',
+      }}
+      onClick={(e) => {
+        const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();
+        const x = e.clientX - rect.left;
+        const progress = x / rect.width;
+        actions.seekTo(progress * state.totalDuration);
+      }}
+      onMouseMove={handleProgressHover}
+      onMouseLeave={handleProgressLeave}
+    >
+      {/* Track background */}
+      <div
+        style={{
+          position: 'absolute',
+          left: 0,
+          right: 0,
+          height: '6px',
+          background: 'rgba(255,255,255,0.2)',
+          borderRadius: '3px',
+        }}
+      />
+
+      {/* Progress fill */}
+      <div
+        style={{
+          position: 'absolute',
+          left: 0,
+          width: `${state.docProgress * 100}%`,
+          height: '6px',
+          background: '#3d5a80',
+          borderRadius: '3px',
+          transition: 'width 0.1s',
+        }}
+      />
+
+      {/* Block markers (dots) */}
+      {blockMarkers.map((marker, i) => (
+        <div
+          key={`${marker.block.id}-${i}`}
+          style={{
+            position: 'absolute',
+            left: `${marker.position}%`,
+            transform: 'translateX(-50%)',
+            width: '10px',
+            height: '10px',
+            borderRadius: '50%',
+            background:
+              marker.index === state.currentBlockIndex ? '#ffffff' : 'rgba(255,255,255,0.5)',
+            border: '2px solid #3d5a80',
+            cursor: 'pointer',
+            zIndex: 2,
+            transition: 'transform 0.15s, background 0.15s',
+          }}
+          title={marker.title}
+          onClick={(e) => {
+            e.stopPropagation();
+            actions.seekTo(marker.block.startTime);
+          }}
+          onMouseEnter={(e) => {
+            (e.currentTarget as HTMLElement).style.transform = 'translateX(-50%) scale(1.3)';
+          }}
+          onMouseLeave={(e) => {
+            (e.currentTarget as HTMLElement).style.transform = 'translateX(-50%)';
+          }}
+        />
+      ))}
+
+      {/* Hover tooltip */}
+      {hoverPosition !== null && (
+        <div
+          style={{
+            position: 'absolute',
+            left: `${hoverPosition * 100}%`,
+            bottom: '100%',
+            transform: 'translateX(-50%)',
+            marginBottom: '8px',
+            padding: '6px 10px',
+            background: 'rgba(0,0,0,0.9)',
+            borderRadius: '4px',
+            whiteSpace: 'nowrap',
+            pointerEvents: 'none',
+            zIndex: 10,
+          }}
+        >
+          <div style={{ color: 'white', fontSize: '12px', fontFamily: 'monospace' }}>
+            {formatTime(hoverPosition * state.totalDuration)}
+          </div>
+          {(() => {
+            const hoverTime = hoverPosition * state.totalDuration;
+            const slideInfo = getBlockAtTimeLocal(hoverTime);
+            if (slideInfo && getBlockTitle) {
+              return (
+                <div style={{ color: 'rgba(255,255,255,0.7)', fontSize: '11px', marginTop: '2px' }}>
+                  {getBlockTitle(slideInfo.block)}
+                </div>
+              );
+            }
+            return null;
+          })()}
+        </div>
+      )}
+
+      {/* Hover line indicator */}
+      {hoverPosition !== null && (
+        <div
+          style={{
+            position: 'absolute',
+            left: `${hoverPosition * 100}%`,
+            top: '50%',
+            transform: 'translate(-50%, -50%)',
+            width: '2px',
+            height: '16px',
+            background: 'rgba(255,255,255,0.6)',
+            pointerEvents: 'none',
+            zIndex: 1,
+          }}
+        />
+      )}
+    </div>
+  );
+}

package/src/LinearDocView.tsx

@@ -0,0 +1,313 @@
+/**
+ * LinearDocView Component
+ *
+ * Renders a Doc as a long-scrolling document view. Each block is displayed
+ * as a readable section: non-annotated blocks render their markdown content
+ * as HTML, while template-annotated blocks render as inline SVG visual cards
+ * via BlockRenderer.
+ *
+ * This is the view used when `displayMode === 'linear'` in DocPlayer.
+ *
+ * Layout:
+ * - Scrollable container with max-width for readability
+ * - Headings from the block hierarchy rendered as HTML headings
+ * - Body content rendered via MarkdownRenderer
+ * - Template-annotated sections show an SVG card (BlockRenderer)
+ *   using `getLayers()` for on-demand layer computation
+ * - Blocks are rendered recursively to preserve the heading hierarchy
+ */
+
+import { useMemo } from 'react';
+import type { Doc, Block, DocBlock } from '@bendyline/squisq/schemas';
+import type { ViewportConfig } from '@bendyline/squisq/schemas';
+import type { Theme } from '@bendyline/squisq/schemas';
+import { VIEWPORT_PRESETS } from '@bendyline/squisq/schemas';
+import { getLayers, hasTemplate, DEFAULT_THEME } from '@bendyline/squisq/doc';
+import type { RenderContext } from '@bendyline/squisq/doc';
+import { extractPlainText } from '@bendyline/squisq/markdown';
+import type { MarkdownBlockNode, MarkdownList } from '@bendyline/squisq/markdown';
+import { BlockRenderer } from './BlockRenderer';
+import { MarkdownRenderer } from './MarkdownRenderer';
+
+// ── Props ──────────────────────────────────────────────────────────
+
+export 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;
+  /** Optional CSS class for the outer container */
+  className?: string;
+  /** Theme to use for rendering (default: DEFAULT_THEME from the theme library) */
+  theme?: Theme;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+/**
+ * Determine whether a block has a template annotation that should be
+ * rendered as a visual SVG card. A block is "annotated" when:
+ * 1. Its sourceHeading has a templateAnnotation, AND
+ * 2. The annotated template exists in the registry
+ */
+function isAnnotatedBlock(block: Block): boolean {
+  const annotation = block.sourceHeading?.templateAnnotation;
+  if (!annotation) return false;
+  return hasTemplate(annotation.template);
+}
+
+/**
+ * Count total blocks in a hierarchy (for RenderContext.totalBlocks).
+ */
+function countAll(blocks: Block[]): number {
+  let count = 0;
+  for (const b of blocks) {
+    count++;
+    if (b.children) count += countAll(b.children);
+  }
+  return count;
+}
+
+// ── Block Section Renderer ─────────────────────────────────────────
+
+interface BlockSectionProps {
+  block: Block;
+  basePath: string;
+  viewport: ViewportConfig;
+  renderContext: RenderContext;
+  blockIndex: number;
+}
+
+/**
+ * Render a single block section: heading + body content or SVG card.
+ * Recurses into children to render the full heading tree.
+ */
+function BlockSection({ block, basePath, viewport, renderContext, blockIndex }: BlockSectionProps) {
+  const isAnnotated = isAnnotatedBlock(block);
+
+  // For annotated blocks, compute layers and build a Block with them
+  const visualBlock = useMemo(() => {
+    if (!isAnnotated) return null;
+
+    const annotation = block.sourceHeading!.templateAnnotation!;
+    const headingText = extractPlainText(block.sourceHeading!);
+    const bodyText = extractBodyPlainText(block.contents);
+
+    // Build a TemplateBlock-compatible object
+    const templateBlock: Record<string, unknown> = {
+      id: block.id,
+      template: annotation.template,
+      startTime: 0,
+      duration: 1,
+      audioSegment: 0,
+      title: headingText,
+      ...getTemplateDefaults(annotation.template, headingText, bodyText, block.contents),
+      ...annotation.params,
+      ...block.templateOverrides,
+    };
+
+    // Compute layers via getLayers
+    const ctx: RenderContext = {
+      ...renderContext,
+      blockIndex,
+    };
+    const layers = getLayers(templateBlock as unknown as DocBlock, ctx);
+
+    return {
+      ...block,
+      layers,
+      template: annotation.template,
+    } as Block;
+  }, [block, isAnnotated, renderContext, blockIndex]);
+
+  return (
+    <div
+      className="squisq-linear-section"
+      data-block-id={block.id}
+      data-template={isAnnotated ? block.sourceHeading?.templateAnnotation?.template : undefined}
+    >
+      {/* Render the heading (if present — preamble has no sourceHeading) */}
+      {block.sourceHeading && !isAnnotated && <MarkdownRenderer nodes={[block.sourceHeading]} />}
+
+      {/* Annotated block: render SVG card */}
+      {isAnnotated && visualBlock && (
+        <div className="squisq-linear-card">
+          {/* Optional heading label above the card */}
+          {block.sourceHeading && (
+            <div className="squisq-linear-card-label squisq-md">
+              <MarkdownRenderer nodes={[block.sourceHeading]} />
+            </div>
+          )}
+          <div
+            className="squisq-linear-card-svg"
+            style={{
+              width: '100%',
+              aspectRatio: `${viewport.width} / ${viewport.height}`,
+              overflow: 'hidden',
+              borderRadius: '8px',
+              boxShadow: '0 2px 8px rgba(0, 0, 0, 0.12)',
+              marginBottom: '1em',
+            }}
+          >
+            <BlockRenderer
+              block={visualBlock}
+              blockTime={0}
+              basePath={basePath}
+              viewport={viewport}
+            />
+          </div>
+        </div>
+      )}
+
+      {/* Body content (always render for non-annotated blocks, skipped for annotated) */}
+      {!isAnnotated && block.contents && block.contents.length > 0 && (
+        <MarkdownRenderer nodes={block.contents} />
+      )}
+
+      {/* Recurse into children */}
+      {block.children && block.children.length > 0 && (
+        <div className="squisq-linear-children">
+          {block.children.map((child, i) => (
+            <BlockSection
+              key={child.id}
+              block={child}
+              basePath={basePath}
+              viewport={viewport}
+              renderContext={renderContext}
+              blockIndex={blockIndex + i + 1}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ── Template Defaults (mirrored from PreviewPanel) ─────────────────
+
+/** Extract plain text from block contents. */
+function extractBodyPlainText(contents?: MarkdownBlockNode[]): string {
+  if (!contents || contents.length === 0) return '';
+  return contents
+    .map((n) => extractPlainText(n))
+    .join('\n')
+    .trim();
+}
+
+/** Extract list items as plain text. */
+function extractListItems(contents?: MarkdownBlockNode[]): string[] {
+  if (!contents) return [];
+  const items: string[] = [];
+  for (const node of contents) {
+    if (node.type === 'list') {
+      for (const item of (node as MarkdownList).children) {
+        const text = extractPlainText(item).trim();
+        if (text) items.push(text);
+      }
+    }
+  }
+  return items;
+}
+
+/**
+ * Provide sensible default fields for templates that require more than
+ * just a `title`. Prevents crashes from undefined required fields.
+ */
+function getTemplateDefaults(
+  templateName: string,
+  headingText: string,
+  bodyText: string,
+  contents?: MarkdownBlockNode[],
+): Record<string, unknown> {
+  switch (templateName) {
+    case 'statHighlight':
+      return { stat: headingText, description: bodyText || headingText };
+    case 'quoteBlock':
+    case 'fullBleedQuote':
+    case 'pullQuote':
+      return { quote: bodyText || headingText };
+    case 'factCard':
+      return { fact: headingText, explanation: bodyText || headingText };
+    case 'comparisonBar':
+      return { leftLabel: 'A', leftValue: 60, rightLabel: 'B', rightValue: 40 };
+    case 'listBlock':
+      return { items: extractListItems(contents) || ['Item 1', 'Item 2', 'Item 3'] };
+    case 'definitionCard':
+      return { term: headingText, definition: bodyText || headingText };
+    case 'dateEvent':
+      return { date: headingText, description: bodyText || headingText };
+    default:
+      return {};
+  }
+}
+
+// ── Main Component ─────────────────────────────────────────────────
+
+/**
+ * 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/" />
+ * ```
+ */
+export function LinearDocView({
+  doc,
+  basePath = '/',
+  viewport,
+  className,
+  theme,
+}: LinearDocViewProps) {
+  const activeViewport = viewport ?? VIEWPORT_PRESETS.landscape;
+  const totalBlocks = useMemo(() => countAll(doc.blocks), [doc.blocks]);
+
+  const renderContext: RenderContext = useMemo(
+    () => ({
+      theme: theme ?? DEFAULT_THEME,
+      viewport: activeViewport,
+      totalBlocks,
+    }),
+    [activeViewport, totalBlocks, theme],
+  );
+
+  return (
+    <div
+      className={`squisq-linear ${className || ''}`}
+      style={{
+        width: '100%',
+        height: '100%',
+        overflowY: 'auto',
+        overflowX: 'hidden',
+      }}
+    >
+      <div
+        className="squisq-linear-content"
+        style={{
+          maxWidth: '720px',
+          margin: '0 auto',
+          padding: '24px 16px',
+          lineHeight: 1.7,
+          fontSize: '16px',
+          color: 'var(--squisq-text, #1f2937)',
+        }}
+      >
+        {doc.blocks.map((block, i) => (
+          <BlockSection
+            key={block.id}
+            block={block}
+            basePath={basePath}
+            viewport={activeViewport}
+            renderContext={renderContext}
+            blockIndex={i}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}