@bendyline/squisq-react 0.1.2

package/src/__tests__/LinearDocView.test.tsx

@@ -0,0 +1,180 @@
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { LinearDocView } from '../LinearDocView';
+import type { Doc, Block } from '@bendyline/squisq/schemas';
+import type {
+  MarkdownBlockNode,
+  MarkdownInlineNode,
+  MarkdownHeading,
+} from '@bendyline/squisq/markdown';
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+function text(value: string): MarkdownInlineNode {
+  return { type: 'text', value };
+}
+
+function paragraph(...children: MarkdownInlineNode[]): MarkdownBlockNode {
+  return { type: 'paragraph', children };
+}
+
+function mkHeading(depth: 1 | 2 | 3, value: string): MarkdownHeading {
+  return { type: 'heading', depth, children: [text(value)] };
+}
+
+function mkBlock(overrides: Partial<Block> = {}): Block {
+  return {
+    id: 'block-1',
+    startTime: 0,
+    duration: 3,
+    audioSegment: 0,
+    ...overrides,
+  };
+}
+
+function mkDoc(blocks: Block[]): Doc {
+  return {
+    articleId: 'test-article',
+    duration: 10,
+    blocks,
+    audio: { segments: [] },
+  };
+}
+
+// ── Tests ──────────────────────────────────────────────────────────
+
+describe('LinearDocView', () => {
+  it('renders a scrollable container', () => {
+    const doc = mkDoc([
+      mkBlock({
+        id: 'preamble',
+        contents: [paragraph(text('Introduction text'))],
+      }),
+    ]);
+    const { container } = render(<LinearDocView doc={doc} />);
+    const el = container.querySelector('.squisq-linear');
+    expect(el).toBeTruthy();
+    expect((el as HTMLElement).style.overflowY).toBe('auto');
+  });
+
+  it('renders preamble content (no heading)', () => {
+    const doc = mkDoc([
+      mkBlock({
+        id: 'preamble',
+        contents: [paragraph(text('Preamble body'))],
+      }),
+    ]);
+    const { container } = render(<LinearDocView doc={doc} />);
+    // Should render paragraph but no heading
+    expect(container.textContent).toContain('Preamble body');
+    const headings = container.querySelectorAll('h1, h2, h3');
+    expect(headings.length).toBe(0);
+  });
+
+  it('renders non-annotated block with heading + content', () => {
+    const doc = mkDoc([
+      mkBlock({
+        id: 'section-1',
+        sourceHeading: mkHeading(2, 'My Section'),
+        contents: [paragraph(text('Section body text'))],
+      }),
+    ]);
+    const { container } = render(<LinearDocView doc={doc} />);
+    expect(container.querySelector('h2')?.textContent).toBe('My Section');
+    expect(container.textContent).toContain('Section body text');
+  });
+
+  it('renders annotated block as SVG card', () => {
+    const doc = mkDoc([
+      mkBlock({
+        id: 'annotated-1',
+        template: 'sectionHeader',
+        sourceHeading: {
+          type: 'heading',
+          depth: 2,
+          children: [text('Visual Block')],
+          templateAnnotation: {
+            template: 'sectionHeader',
+          },
+        },
+        contents: [paragraph(text('Body'))],
+      }),
+    ]);
+    const { container } = render(<LinearDocView doc={doc} />);
+    // Should have a card wrapper
+    const card = container.querySelector('.squisq-linear-card');
+    expect(card).toBeTruthy();
+    // Should contain an SVG (from BlockRenderer)
+    const svg = card?.querySelector('svg');
+    expect(svg).toBeTruthy();
+  });
+
+  it('renders children recursively', () => {
+    const doc = mkDoc([
+      mkBlock({
+        id: 'parent',
+        sourceHeading: mkHeading(1, 'Parent'),
+        contents: [paragraph(text('Parent body'))],
+        children: [
+          mkBlock({
+            id: 'child',
+            sourceHeading: mkHeading(2, 'Child'),
+            contents: [paragraph(text('Child body'))],
+          }),
+        ],
+      }),
+    ]);
+    const { container } = render(<LinearDocView doc={doc} />);
+    expect(container.querySelector('h1')?.textContent).toBe('Parent');
+    expect(container.querySelector('h2')?.textContent).toBe('Child');
+    expect(container.textContent).toContain('Parent body');
+    expect(container.textContent).toContain('Child body');
+  });
+
+  it('renders multiple top-level blocks', () => {
+    const doc = mkDoc([
+      mkBlock({
+        id: 'b1',
+        sourceHeading: mkHeading(1, 'First'),
+        contents: [],
+      }),
+      mkBlock({
+        id: 'b2',
+        sourceHeading: mkHeading(1, 'Second'),
+        contents: [],
+      }),
+    ]);
+    const { container } = render(<LinearDocView doc={doc} />);
+    const sections = container.querySelectorAll('.squisq-linear-section');
+    expect(sections.length).toBe(2);
+  });
+
+  it('does not render SVG for non-annotated blocks', () => {
+    const doc = mkDoc([
+      mkBlock({
+        id: 'plain',
+        sourceHeading: mkHeading(2, 'Plain Section'),
+        contents: [paragraph(text('Just text'))],
+      }),
+    ]);
+    const { container } = render(<LinearDocView doc={doc} />);
+    expect(container.querySelector('.squisq-linear-card')).toBeNull();
+    expect(container.querySelector('svg')).toBeNull();
+  });
+
+  it('applies custom className', () => {
+    const doc = mkDoc([mkBlock({ id: 'x', contents: [] })]);
+    const { container } = render(<LinearDocView doc={doc} className="my-class" />);
+    expect(container.querySelector('.squisq-linear.my-class')).toBeTruthy();
+  });
+
+  it('sets data-block-id on each section', () => {
+    const doc = mkDoc([
+      mkBlock({ id: 'alpha', contents: [] }),
+      mkBlock({ id: 'beta', contents: [] }),
+    ]);
+    const { container } = render(<LinearDocView doc={doc} />);
+    expect(container.querySelector('[data-block-id="alpha"]')).toBeTruthy();
+    expect(container.querySelector('[data-block-id="beta"]')).toBeTruthy();
+  });
+});

package/src/__tests__/MarkdownRenderer.test.tsx

@@ -0,0 +1,234 @@
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { MarkdownRenderer } from '../MarkdownRenderer';
+import type { MarkdownBlockNode, MarkdownInlineNode } from '@bendyline/squisq/markdown';
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+function text(value: string): MarkdownInlineNode {
+  return { type: 'text', value };
+}
+
+function paragraph(...children: MarkdownInlineNode[]): MarkdownBlockNode {
+  return { type: 'paragraph', children };
+}
+
+function heading(
+  depth: 1 | 2 | 3 | 4 | 5 | 6,
+  ...children: MarkdownInlineNode[]
+): MarkdownBlockNode {
+  return { type: 'heading', depth, children };
+}
+
+// ── Tests ──────────────────────────────────────────────────────────
+
+describe('MarkdownRenderer', () => {
+  it('renders null for empty nodes', () => {
+    const { container } = render(<MarkdownRenderer nodes={[]} />);
+    expect(container.innerHTML).toBe('');
+  });
+
+  it('renders a paragraph', () => {
+    const { container } = render(<MarkdownRenderer nodes={[paragraph(text('Hello world'))]} />);
+    const p = container.querySelector('p.squisq-md-p');
+    expect(p).toBeTruthy();
+    expect(p?.textContent).toBe('Hello world');
+  });
+
+  it('renders headings at correct depth', () => {
+    const nodes: MarkdownBlockNode[] = [
+      heading(1, text('Title')),
+      heading(2, text('Subtitle')),
+      heading(3, text('Section')),
+    ];
+    const { container } = render(<MarkdownRenderer nodes={nodes} />);
+    expect(container.querySelector('h1')?.textContent).toBe('Title');
+    expect(container.querySelector('h2')?.textContent).toBe('Subtitle');
+    expect(container.querySelector('h3')?.textContent).toBe('Section');
+  });
+
+  it('renders emphasis and strong inline', () => {
+    const nodes: MarkdownBlockNode[] = [
+      paragraph(text('normal '), { type: 'emphasis', children: [text('italic')] }, text(' and '), {
+        type: 'strong',
+        children: [text('bold')],
+      }),
+    ];
+    const { container } = render(<MarkdownRenderer nodes={nodes} />);
+    expect(container.querySelector('em')?.textContent).toBe('italic');
+    expect(container.querySelector('strong')?.textContent).toBe('bold');
+  });
+
+  it('renders inline code', () => {
+    const nodes: MarkdownBlockNode[] = [
+      paragraph(text('run '), { type: 'inlineCode', value: 'npm install' }),
+    ];
+    const { container } = render(<MarkdownRenderer nodes={nodes} />);
+    const code = container.querySelector('code.squisq-md-inline-code');
+    expect(code?.textContent).toBe('npm install');
+  });
+
+  it('renders a link with target _blank', () => {
+    const nodes: MarkdownBlockNode[] = [
+      paragraph({
+        type: 'link',
+        url: 'https://example.com',
+        title: 'Example',
+        children: [text('click')],
+      }),
+    ];
+    const { container } = render(<MarkdownRenderer nodes={nodes} />);
+    const a = container.querySelector('a.squisq-md-link') as HTMLAnchorElement;
+    expect(a).toBeTruthy();
+    expect(a.href).toContain('example.com');
+    expect(a.target).toBe('_blank');
+    expect(a.textContent).toBe('click');
+  });
+
+  it('renders an image', () => {
+    const nodes: MarkdownBlockNode[] = [
+      paragraph({
+        type: 'image',
+        url: '/cat.jpg',
+        alt: 'A cat',
+      }),
+    ];
+    const { container } = render(<MarkdownRenderer nodes={nodes} />);
+    const img = container.querySelector('img.squisq-md-image') as HTMLImageElement;
+    expect(img).toBeTruthy();
+    expect(img.alt).toBe('A cat');
+  });
+
+  it('renders an unordered list', () => {
+    const nodes: MarkdownBlockNode[] = [
+      {
+        type: 'list',
+        ordered: false,
+        children: [
+          { type: 'listItem', children: [paragraph(text('Item A'))] },
+          { type: 'listItem', children: [paragraph(text('Item B'))] },
+        ],
+      },
+    ];
+    const { container } = render(<MarkdownRenderer nodes={nodes} />);
+    const ul = container.querySelector('ul.squisq-md-ul');
+    expect(ul).toBeTruthy();
+    const items = ul?.querySelectorAll('li');
+    expect(items?.length).toBe(2);
+    expect(items?.[0]?.textContent).toBe('Item A');
+  });
+
+  it('renders an ordered list with start number', () => {
+    const nodes: MarkdownBlockNode[] = [
+      {
+        type: 'list',
+        ordered: true,
+        start: 3,
+        children: [{ type: 'listItem', children: [paragraph(text('Third'))] }],
+      },
+    ];
+    const { container } = render(<MarkdownRenderer nodes={nodes} />);
+    const ol = container.querySelector('ol.squisq-md-ol') as HTMLOListElement;
+    expect(ol).toBeTruthy();
+    expect(ol.start).toBe(3);
+  });
+
+  it('renders a task list item with checkbox', () => {
+    const nodes: MarkdownBlockNode[] = [
+      {
+        type: 'list',
+        ordered: false,
+        children: [
+          { type: 'listItem', checked: true, children: [paragraph(text('Done'))] },
+          { type: 'listItem', checked: false, children: [paragraph(text('Todo'))] },
+        ],
+      },
+    ];
+    const { container } = render(<MarkdownRenderer nodes={nodes} />);
+    const checkboxes = container.querySelectorAll('input[type="checkbox"]');
+    expect(checkboxes.length).toBe(2);
+    expect((checkboxes[0] as HTMLInputElement).checked).toBe(true);
+    expect((checkboxes[1] as HTMLInputElement).checked).toBe(false);
+  });
+
+  it('renders a code block', () => {
+    const nodes: MarkdownBlockNode[] = [
+      { type: 'code', lang: 'typescript', value: 'const x = 1;' },
+    ];
+    const { container } = render(<MarkdownRenderer nodes={nodes} />);
+    const pre = container.querySelector('pre.squisq-md-code-block');
+    expect(pre).toBeTruthy();
+    const code = pre?.querySelector('code.language-typescript');
+    expect(code?.textContent).toBe('const x = 1;');
+  });
+
+  it('renders a blockquote', () => {
+    const nodes: MarkdownBlockNode[] = [
+      { type: 'blockquote', children: [paragraph(text('Quoted text'))] },
+    ];
+    const { container } = render(<MarkdownRenderer nodes={nodes} />);
+    const bq = container.querySelector('blockquote.squisq-md-blockquote');
+    expect(bq).toBeTruthy();
+    expect(bq?.textContent).toBe('Quoted text');
+  });
+
+  it('renders a thematic break', () => {
+    const nodes: MarkdownBlockNode[] = [
+      paragraph(text('Before')),
+      { type: 'thematicBreak' },
+      paragraph(text('After')),
+    ];
+    const { container } = render(<MarkdownRenderer nodes={nodes} />);
+    expect(container.querySelector('hr.squisq-md-hr')).toBeTruthy();
+  });
+
+  it('renders a table', () => {
+    const nodes: MarkdownBlockNode[] = [
+      {
+        type: 'table',
+        align: ['left', 'right'],
+        children: [
+          {
+            type: 'tableRow',
+            children: [
+              { type: 'tableCell', isHeader: true, children: [text('Name')] },
+              { type: 'tableCell', isHeader: true, children: [text('Value')] },
+            ],
+          },
+          {
+            type: 'tableRow',
+            children: [
+              { type: 'tableCell', children: [text('A')] },
+              { type: 'tableCell', children: [text('1')] },
+            ],
+          },
+        ],
+      },
+    ];
+    const { container } = render(<MarkdownRenderer nodes={nodes} />);
+    const table = container.querySelector('table.squisq-md-table');
+    expect(table).toBeTruthy();
+    expect(table?.querySelectorAll('th').length).toBe(2);
+    expect(table?.querySelectorAll('td').length).toBe(2);
+  });
+
+  it('renders strikethrough', () => {
+    const nodes: MarkdownBlockNode[] = [paragraph({ type: 'delete', children: [text('removed')] })];
+    const { container } = render(<MarkdownRenderer nodes={nodes} />);
+    const del = container.querySelector('del.squisq-md-del');
+    expect(del?.textContent).toBe('removed');
+  });
+
+  it('renders a hard break', () => {
+    const nodes: MarkdownBlockNode[] = [paragraph(text('line1'), { type: 'break' }, text('line2'))];
+    const { container } = render(<MarkdownRenderer nodes={nodes} />);
+    expect(container.querySelector('br')).toBeTruthy();
+  });
+
+  it('applies custom className', () => {
+    const { container } = render(
+      <MarkdownRenderer nodes={[paragraph(text('test'))]} className="custom" />,
+    );
+    expect(container.querySelector('.squisq-md.custom')).toBeTruthy();
+  });
+});

package/src/__tests__/exports.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import * as squisqReact from '../index';
+
+describe('@bendyline/squisq-react exports', () => {
+  it('exports DocPlayer component', () => {
+    expect(squisqReact.DocPlayer).toBeDefined();
+    expect(typeof squisqReact.DocPlayer).toBe('function');
+  });
+
+  it('exports BlockRenderer component', () => {
+    expect(squisqReact.BlockRenderer).toBeDefined();
+    expect(typeof squisqReact.BlockRenderer).toBe('function');
+  });
+
+  it('exports all layer components', () => {
+    expect(typeof squisqReact.ImageLayer).toBe('function');
+    expect(typeof squisqReact.TextLayer).toBe('function');
+    expect(typeof squisqReact.ShapeLayer).toBe('function');
+    expect(typeof squisqReact.VideoLayer).toBe('function');
+    expect(typeof squisqReact.MapLayer).toBe('function');
+  });
+
+  it('exports control components', () => {
+    expect(typeof squisqReact.CaptionOverlay).toBe('function');
+    expect(typeof squisqReact.DocControlsOverlay).toBe('function');
+    expect(typeof squisqReact.DocControlsBottom).toBe('function');
+    expect(typeof squisqReact.DocControlsSidebar).toBe('function');
+    expect(typeof squisqReact.DocControlsSlideshow).toBe('function');
+    expect(typeof squisqReact.DocPlayerWithSidebar).toBe('function');
+    expect(typeof squisqReact.DocProgressBar).toBe('function');
+  });
+
+  it('exports MarkdownRenderer and LinearDocView', () => {
+    expect(typeof squisqReact.MarkdownRenderer).toBe('function');
+    expect(typeof squisqReact.LinearDocView).toBe('function');
+  });
+
+  it('exports hooks', () => {
+    expect(typeof squisqReact.useAudioSync).toBe('function');
+    expect(typeof squisqReact.useDocPlayback).toBe('function');
+    expect(typeof squisqReact.useViewportOrientation).toBe('function');
+  });
+
+  it('exports utility functions', () => {
+    expect(typeof squisqReact.getAnimationStyle).toBe('function');
+    expect(typeof squisqReact.getTransitionClass).toBe('function');
+  });
+
+  it('exports formatTime utility', () => {
+    expect(typeof squisqReact.formatTime).toBe('function');
+    expect(squisqReact.formatTime(65)).toBe('1:05');
+    expect(squisqReact.formatTime(0)).toBe('0:00');
+    expect(squisqReact.formatTime(3661)).toBe('61:01');
+  });
+});

package/src/hooks/AudioProvider.ts

@@ -0,0 +1,114 @@
+/**
+ * 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.
+ */
+
+import type { AudioTrack, AudioSegment } from '@bendyline/squisq/schemas';
+
+export 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;
+}
+
+export 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>;
+}
+
+export type AudioProvider = AudioState & AudioActions;
+
+export interface AudioProviderConfig {
+  /** Audio track with segments */
+  audioTrack: AudioTrack | undefined;
+  /** Base path for resolving audio URLs */
+  basePath: string;
+  /** Article ID (for EFB companion) */
+  articleId?: string;
+  /** Tile/geohash (for EFB companion) */
+  tile?: string;
+}
+
+/**
+ * Calculate segment start times and total duration from an audio track
+ */
+export function calculateSegmentTiming(segments: AudioSegment[] | undefined): {
+  segmentStarts: number[];
+  totalDuration: number;
+} {
+  if (!segments?.length) {
+    return { segmentStarts: [], totalDuration: 0 };
+  }
+
+  let time = 0;
+  const segmentStarts = segments.map((seg) => {
+    const start = time;
+    time += seg.duration;
+    return start;
+  });
+
+  return { segmentStarts, totalDuration: time };
+}
+
+/**
+ * Find which segment a given time falls into
+ */
+export function findSegmentAtTime(
+  time: number,
+  segments: AudioSegment[] | undefined,
+  segmentStarts: number[],
+): { segmentIndex: number; segmentStart: number } {
+  if (!segments?.length) {
+    return { segmentIndex: 0, segmentStart: 0 };
+  }
+
+  let segmentIndex = 0;
+  let segmentStart = 0;
+
+  for (let i = 0; i < segments.length; i++) {
+    const segEnd = segmentStarts[i] + segments[i].duration;
+    if (time < segEnd) {
+      segmentIndex = i;
+      segmentStart = segmentStarts[i];
+      break;
+    }
+    // Handle edge case: time exactly at end goes to last segment
+    if (i === segments.length - 1) {
+      segmentIndex = i;
+      segmentStart = segmentStarts[i];
+    }
+  }
+
+  return { segmentIndex, segmentStart };
+}

package/src/hooks/MediaContext.tsx

@@ -0,0 +1,81 @@
+/**
+ * MediaContext — React context for providing a MediaProvider to layer components.
+ *
+ * When a MediaProvider is available in context, layer components (ImageLayer,
+ * VideoLayer) will use it to resolve media URLs instead of the basePath prop.
+ * This enables slot-based media storage where binary assets are served from
+ * IndexedDB as blob URLs.
+ *
+ * Usage:
+ *   const provider = createSlotMediaProvider(slotId);
+ *   <MediaContext.Provider value={provider}>
+ *     <DocPlayer doc={doc} basePath="/" />
+ *   </MediaContext.Provider>
+ */
+
+import { createContext, useContext, useState, useEffect, useMemo } from 'react';
+import type { MediaProvider } from '@bendyline/squisq/schemas';
+
+/**
+ * React context holding the current MediaProvider (or null if none provided).
+ */
+export const MediaContext = createContext<MediaProvider | null>(null);
+
+/**
+ * Hook to access the current MediaProvider from context.
+ * Returns null if no provider is set.
+ */
+export function useMediaProvider(): MediaProvider | null {
+  return useContext(MediaContext);
+}
+
+/**
+ * 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
+ */
+export function useMediaUrl(relativePath: string, basePath: string): string {
+  const provider = useMediaProvider();
+
+  // For absolute/http URLs, skip resolution entirely
+  const isAbsolute =
+    relativePath.startsWith('http') ||
+    relativePath.startsWith('/') ||
+    relativePath.startsWith('data:') ||
+    relativePath.startsWith('blob:');
+
+  // Memoize fallback to avoid recalculating on every render
+  const fallback = useMemo(
+    () => (isAbsolute ? relativePath : `${basePath}/${relativePath}`),
+    [isAbsolute, relativePath, basePath],
+  );
+
+  // Fast path: no provider or absolute URL — return synchronously, skip effect entirely
+  const needsProvider = !isAbsolute && !!provider;
+
+  const [url, setUrl] = useState(fallback);
+
+  useEffect(() => {
+    if (!needsProvider) {
+      setUrl(fallback);
+      return;
+    }
+
+    let cancelled = false;
+    provider!.resolveUrl(relativePath).then((resolved) => {
+      if (!cancelled) setUrl(resolved);
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [needsProvider, provider, relativePath, fallback]);
+
+  // When provider is not needed, return fallback directly to avoid
+  // the one-frame delay from the initial useState → useEffect cycle
+  return needsProvider ? url : fallback;
+}

package/src/hooks/index.ts

@@ -0,0 +1,6 @@
+export { calculateSegmentTiming, findSegmentAtTime } from './AudioProvider';
+export type { AudioState, AudioActions, AudioProvider, AudioProviderConfig } from './AudioProvider';
+
+export { useAudioSync } from './useAudioSync';
+export { useDocPlayback } from './useDocPlayback';
+export { useViewportOrientation } from './useViewportOrientation';