@bendyline/squisq-react 2.0.1 → 2.2.0

package/src/__tests__/useAudioSync.test.ts

@@ -1,49 +0,0 @@
-import { act, renderHook, waitFor } from '@testing-library/react';
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import type { AudioTrack } from '@bendyline/squisq/schemas';
-import { useAudioSync } from '../hooks/useAudioSync';
-
-const track: AudioTrack = {
-  segments: [{ src: 'https://cdn.example.test/a.mp3', name: 'a', duration: 2, startTime: 0 }],
-};
-
-afterEach(() => vi.restoreAllMocks());
-
-describe('useAudioSync resource loading', () => {
-  it('does not prefix absolute URLs and revokes a blob that resolves after cleanup', async () => {
-    let resolveFetch!: (value: unknown) => void;
-    const fetchPromise = new Promise((resolve) => {
-      resolveFetch = resolve;
-    });
-    const fetchSpy = vi
-      .spyOn(globalThis, 'fetch')
-      .mockReturnValue(fetchPromise as Promise<Response>);
-    const create = vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:late');
-    const revoke = vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => {});
-    const audioRef = { current: null };
-    const { unmount } = renderHook(() => useAudioSync(audioRef, track, '.'));
-
-    await waitFor(() => expect(fetchSpy).toHaveBeenCalled());
-    expect(fetchSpy.mock.calls[0][0]).toBe('https://cdn.example.test/a.mp3');
-    unmount();
-
-    await act(async () => {
-      resolveFetch({ ok: true, blob: async () => new Blob(['audio']) });
-      await fetchPromise;
-      await Promise.resolve();
-      await Promise.resolve();
-    });
-    expect(create).toHaveBeenCalled();
-    expect(revoke).toHaveBeenCalledWith('blob:late');
-  });
-
-  it('does not preload when an external controller disables the hook', async () => {
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue({
-      ok: true,
-      blob: async () => new Blob(['audio']),
-    } as Response);
-    renderHook(() => useAudioSync({ current: null }, track, '.', false));
-    await act(async () => Promise.resolve());
-    expect(fetchSpy).not.toHaveBeenCalled();
-  });
-});

package/src/__tests__/useDocPlayback.transition.test.ts

@@ -1,113 +0,0 @@
-/**
- * useDocPlayback — block transition state is derived synchronously.
- *
- * Regression guard for the between-block "flash": a newly active block must
- * report `isEntering` (and its outgoing `previousBlock`) on the SAME render it
- * becomes current — not a frame later via an effect. Otherwise the block paints
- * fully settled for a frame and then snaps back to the start of its entrance
- * animation. The distinguishing assertion is `previousBlock` during the next
- * block's entrance with NO timer/effect advanced (the old effect-based path
- * only set it after a `setTimeout`).
- */
-
-import { describe, it, expect, vi } from 'vitest';
-import { act, renderHook } from '@testing-library/react';
-import { VIEWPORT_PRESETS } from '@bendyline/squisq/doc';
-import type { Doc, Block } from '@bendyline/squisq/schemas';
-import { useDocPlayback } from '../hooks/useDocPlayback';
-
-function block(id: string, startTime: number): Block {
-  return {
-    id,
-    startTime,
-    duration: 5,
-    audioSegment: 0,
-    transition: { type: 'fade', duration: 0.5 },
-    layers: [],
-  };
-}
-
-const doc: Doc = {
-  articleId: 'd',
-  duration: 10,
-  blocks: [block('a', 0), block('b', 5)],
-  audio: { segments: [] },
-};
-
-describe('useDocPlayback — synchronous block transitions', () => {
-  it('exposes the entering block + outgoing previousBlock on the same render (no effect flush)', () => {
-    const { result, rerender } = renderHook(
-      ({ t }: { t: number }) => useDocPlayback(doc, t, { viewport: VIEWPORT_PRESETS.landscape }),
-      { initialProps: { t: 0 } },
-    );
-
-    // Establish block A as the current block first.
-    expect(result.current.currentBlockIndex).toBe(0);
-
-    // Cross into block B's entrance window: it is entering AND crossfading from
-    // A immediately — the old code left previousBlock null until a setTimeout.
-    rerender({ t: 5.1 });
-    expect(result.current.currentBlockIndex).toBe(1);
-    expect(result.current.isEntering).toBe(true);
-    expect(result.current.isExiting).toBe(true);
-    expect(result.current.previousBlock?.id).toBe('a');
-
-    // Past the entrance window: settled, no crossfade.
-    rerender({ t: 7 });
-    expect(result.current.isEntering).toBe(false);
-    expect(result.current.isExiting).toBe(false);
-    expect(result.current.previousBlock).toBeNull();
-  });
-
-  it('isEntering is a pure function of blockTime vs the transition duration', () => {
-    const enteringAt = (t: number) =>
-      renderHook(() => useDocPlayback(doc, t, { viewport: VIEWPORT_PRESETS.landscape })).result
-        .current.isEntering;
-    expect(enteringAt(5.0)).toBe(true); // blockTime 0.0 < 0.5
-    expect(enteringAt(5.4)).toBe(true); // blockTime 0.4 < 0.5
-    expect(enteringAt(5.6)).toBe(false); // blockTime 0.6 >= 0.5
-  });
-
-  it('can enter a swipe destination without restoring the outgoing block', () => {
-    const { result, rerender } = renderHook(
-      ({ t }: { t: number }) => useDocPlayback(doc, t, { viewport: VIEWPORT_PRESETS.landscape }),
-      { initialProps: { t: 0 } },
-    );
-
-    act(() => result.current.suppressOutgoingForNextBlock('b'));
-    rerender({ t: 5 });
-
-    // The destination still gets its own entrance animation, but the slide
-    // already carried away by the swipe is not mounted again as context.
-    expect(result.current.isEntering).toBe(true);
-    expect(result.current.isExiting).toBe(false);
-    expect(result.current.previousBlock).toBeNull();
-  });
-
-  it('clears stale outgoing context when a cover reveals the already-active block', () => {
-    const { result, rerender } = renderHook(
-      ({ t }: { t: number }) => useDocPlayback(doc, t, { viewport: VIEWPORT_PRESETS.landscape }),
-      { initialProps: { t: 0 } },
-    );
-    rerender({ t: 5 });
-    expect(result.current.previousBlock?.id).toBe('a');
-
-    act(() => result.current.suppressOutgoingForNextBlock('b'));
-    rerender({ t: 5 });
-
-    expect(result.current.isEntering).toBe(true);
-    expect(result.current.isExiting).toBe(false);
-    expect(result.current.previousBlock).toBeNull();
-  });
-
-  it('navigation actions seek to the target block', () => {
-    const seek = vi.fn();
-    const { result } = renderHook(() =>
-      useDocPlayback(doc, 0, { viewport: VIEWPORT_PRESETS.landscape, onSeek: seek }),
-    );
-    act(() => result.current.nextBlock());
-    expect(seek).toHaveBeenCalledWith(5);
-    act(() => result.current.goToBlock(0));
-    expect(seek).toHaveBeenLastCalledWith(0);
-  });
-});

package/src/__tests__/useJsonViewTokens.test.ts

@@ -1,41 +0,0 @@
-import { describe, it, expect, afterEach, vi } from 'vitest';
-import { renderHook } from '@testing-library/react';
-import { DARK_SURFACE, LIGHT_SURFACE, DEFAULT_THEME } from '@bendyline/squisq/schemas';
-import { useJsonViewTokens } from '../jsonView/useJsonViewTokens';
-
-type StyleBag = Record<string, string>;
-
-function mockPrefersDark(dark: boolean): void {
-  Object.defineProperty(window, 'matchMedia', {
-    configurable: true,
-    value: (query: string) => ({
-      matches: dark && query.includes('dark'),
-      media: query,
-      onchange: null,
-      addListener: vi.fn(),
-      removeListener: vi.fn(),
-      addEventListener: vi.fn(),
-      removeEventListener: vi.fn(),
-      dispatchEvent: vi.fn(() => false),
-    }),
-  });
-}
-
-describe('useJsonViewTokens', () => {
-  afterEach(() => vi.restoreAllMocks());
-
-  it('emits json-prefixed tokens for a static surface', () => {
-    const { result } = renderHook(() => useJsonViewTokens(DEFAULT_THEME, LIGHT_SURFACE));
-    const style = result.current.style as StyleBag;
-    expect(style['--squisq-json-bg']).toBe(LIGHT_SURFACE.background);
-    expect(style['--squisq-json-text']).toBe(LIGHT_SURFACE.text);
-  });
-
-  it("tracks a dark OS preference under surface='auto'", () => {
-    mockPrefersDark(true);
-    const { result } = renderHook(() => useJsonViewTokens(DEFAULT_THEME, 'auto'));
-    const style = result.current.style as StyleBag;
-    expect(style['--squisq-json-bg']).toBe(DARK_SURFACE.background);
-    expect(result.current.theme.colors.background).toBe(DARK_SURFACE.background);
-  });
-});

package/src/__tests__/useSlideSwipe.test.ts

@@ -1,81 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { decideSwipe, type SwipeDecisionInput } from '../hooks/useSlideSwipe';
-
-/** A slow drag: long duration so velocity stays well under the flick threshold. */
-function slow(overrides: Partial<SwipeDecisionInput>): SwipeDecisionInput {
-  return {
-    dx: 0,
-    width: 1000,
-    elapsedMs: 1000,
-    canNext: true,
-    canPrev: true,
-    ...overrides,
-  };
-}
-
-describe('decideSwipe', () => {
-  describe('distance threshold (30% of width)', () => {
-    it('snaps back when the drag is below the threshold', () => {
-      // 100px of 1000px = 10% < 30%, and slow enough not to be a flick.
-      expect(decideSwipe(slow({ dx: -100 }))).toBe('snap');
-      expect(decideSwipe(slow({ dx: 100 }))).toBe('snap');
-    });
-
-    it('advances to the next slide when dragged left past the threshold', () => {
-      expect(decideSwipe(slow({ dx: -350 }))).toBe('next');
-    });
-
-    it('goes to the previous slide when dragged right past the threshold', () => {
-      expect(decideSwipe(slow({ dx: 350 }))).toBe('prev');
-    });
-
-    it('commits exactly at the threshold', () => {
-      expect(decideSwipe(slow({ dx: -300 }))).toBe('next');
-    });
-  });
-
-  describe('flick (fast, short drag)', () => {
-    it('commits on a quick flick even below the distance threshold', () => {
-      // 100px in 100ms = 1.0 px/ms >= 0.5, distance 100 >= 12.
-      expect(decideSwipe(slow({ dx: -100, elapsedMs: 100 }))).toBe('next');
-      expect(decideSwipe(slow({ dx: 100, elapsedMs: 100 }))).toBe('prev');
-    });
-
-    it('ignores a fast micro-jitter shorter than the minimum flick distance', () => {
-      // 8px in 5ms = 1.6 px/ms (fast) but distance 8 < 12 → treat as a click.
-      expect(decideSwipe(slow({ dx: -8, elapsedMs: 5 }))).toBe('snap');
-    });
-  });
-
-  describe('deck boundaries', () => {
-    it('snaps back instead of advancing when there is no next slide', () => {
-      expect(decideSwipe(slow({ dx: -350, canNext: false }))).toBe('snap');
-      // A flick past the last slide is also refused.
-      expect(decideSwipe(slow({ dx: -100, elapsedMs: 100, canNext: false }))).toBe('snap');
-    });
-
-    it('snaps back instead of rewinding when there is no previous slide', () => {
-      expect(decideSwipe(slow({ dx: 350, canPrev: false }))).toBe('snap');
-      expect(decideSwipe(slow({ dx: 100, elapsedMs: 100, canPrev: false }))).toBe('snap');
-    });
-  });
-
-  describe('degenerate inputs', () => {
-    it('snaps back on a zero-distance release', () => {
-      expect(decideSwipe(slow({ dx: 0 }))).toBe('snap');
-    });
-
-    it('never commits by distance when the container has no measurable width', () => {
-      // width 0 → distance threshold is Infinity; only a flick can commit.
-      // 500px over 2000ms = 0.25 px/ms, safely below the flick velocity.
-      expect(decideSwipe(slow({ dx: -500, width: 0, elapsedMs: 2000 }))).toBe('snap');
-      expect(decideSwipe(slow({ dx: -500, width: 0, elapsedMs: 100 }))).toBe('next');
-    });
-
-    it('does not divide by zero on an instantaneous release', () => {
-      // elapsedMs 0 → velocity treated as 0; falls back to the distance rule.
-      expect(decideSwipe(slow({ dx: -350, elapsedMs: 0 }))).toBe('next');
-      expect(decideSwipe(slow({ dx: -100, elapsedMs: 0 }))).toBe('snap');
-    });
-  });
-});

package/src/__tests__/useViewportOrientation.test.ts

@@ -1,22 +0,0 @@
-import { renderHook } from '@testing-library/react';
-import { VIEWPORT_PRESETS } from '@bendyline/squisq/doc';
-import { afterEach, describe, expect, it } from 'vitest';
-import { useViewportOrientation } from '../hooks/useViewportOrientation';
-
-const originalWidth = window.innerWidth;
-const originalHeight = window.innerHeight;
-
-afterEach(() => {
-  Object.defineProperty(window, 'innerWidth', { configurable: true, value: originalWidth });
-  Object.defineProperty(window, 'innerHeight', { configurable: true, value: originalHeight });
-});
-
-describe('useViewportOrientation', () => {
-  it('uses the square preset for near-square viewports', () => {
-    Object.defineProperty(window, 'innerWidth', { configurable: true, value: 1000 });
-    Object.defineProperty(window, 'innerHeight', { configurable: true, value: 1000 });
-    const { result } = renderHook(() => useViewportOrientation());
-    expect(result.current.orientation).toBe('square');
-    expect(result.current.viewport).toBe(VIEWPORT_PRESETS.square);
-  });
-});

package/src/hooks/AudioController.ts

@@ -1,114 +0,0 @@
-/**
- * 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:
- *
- * - 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 AudioController = AudioState & AudioActions;
-
-export interface AudioControllerConfig {
-  /** 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

@@ -1,97 +0,0 @@
-/**
- * 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();
-
-  // Defensive: callers (esp. preview surfaces like InlinePreviewGutter)
-  // sometimes feed in template-generated layers whose `content.src` is
-  // undefined while the user is still authoring the block. Treat that
-  // as an empty string rather than crashing the whole React tree.
-  const safePath = typeof relativePath === 'string' ? relativePath : '';
-
-  // For absolute/http URLs, skip resolution entirely
-  const isAbsolute =
-    !safePath ||
-    safePath.startsWith('http') ||
-    safePath.startsWith('/') ||
-    safePath.startsWith('data:') ||
-    safePath.startsWith('blob:');
-
-  // Memoize fallback to avoid recalculating on every render
-  const fallback = useMemo(
-    () => (isAbsolute ? safePath : `${basePath}/${safePath}`),
-    [isAbsolute, safePath, 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;
-    // Never show the prior asset while a new provider/path is resolving.
-    setUrl(fallback);
-    provider!.resolveUrl(safePath).then(
-      (resolved) => {
-        if (!cancelled) setUrl(resolved);
-      },
-      () => {
-        // Resolution failures should be non-fatal and must not become
-        // unhandled promise rejections in rendering surfaces.
-        if (!cancelled) setUrl(fallback);
-      },
-    );
-
-    return () => {
-      cancelled = true;
-    };
-  }, [needsProvider, provider, safePath, 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

@@ -1,11 +0,0 @@
-export { calculateSegmentTiming, findSegmentAtTime } from './AudioController';
-export type {
-  AudioState,
-  AudioActions,
-  AudioController,
-  AudioControllerConfig,
-} from './AudioController';
-
-export { useAudioSync } from './useAudioSync';
-export { useDocPlayback } from './useDocPlayback';
-export { useViewportOrientation } from './useViewportOrientation';