@bendyline/squisq-react 1.4.0 → 1.4.1

package/src/__tests__/useSlideSwipe.test.ts

@@ -0,0 +1,81 @@
+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/hooks/{AudioProvider.ts → AudioController.ts}

@@ -1,5 +1,5 @@
 /**
- * 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:
@@ -47,9 +47,9 @@ export interface AudioActions {
   restart: () => Promise<void>;
 }
 
-export type AudioProvider = AudioState & AudioActions;
+export type AudioController = AudioState & AudioActions;
 
-export interface AudioProviderConfig {
+export interface AudioControllerConfig {
   /** Audio track with segments */
   audioTrack: AudioTrack | undefined;
   /** Base path for resolving audio URLs */

package/src/hooks/index.ts

@@ -1,5 +1,10 @@
-export { calculateSegmentTiming, findSegmentAtTime } from './AudioProvider';
-export type { AudioState, AudioActions, AudioProvider, AudioProviderConfig } from './AudioProvider';
+export { calculateSegmentTiming, findSegmentAtTime } from './AudioController';
+export type {
+  AudioState,
+  AudioActions,
+  AudioController,
+  AudioControllerConfig,
+} from './AudioController';
 
 export { useAudioSync } from './useAudioSync';
 export { useDocPlayback } from './useDocPlayback';

package/src/hooks/useAudioSync.ts

@@ -7,20 +7,21 @@
  * 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.
  */
 
 import { useState, useEffect, useRef, useCallback } from 'react';
 import type { RefObject } from 'react';
 import type { AudioTrack } from '@bendyline/squisq/schemas';
-import type { AudioProvider } from './AudioProvider';
+import type { AudioController } from './AudioController';
 
 export function useAudioSync(
   audioRef: RefObject<HTMLAudioElement>,
   audioTrack: AudioTrack | undefined,
   basePath: string = '',
-): AudioProvider {
+): AudioController {
   const [currentTime, setCurrentTime] = useState(0);
   const [isPlaying, setIsPlaying] = useState(false);
   const [currentSegment, setCurrentSegment] = useState(0);

package/src/hooks/useSlideSwipe.ts

@@ -0,0 +1,265 @@
+/**
+ * useSlideSwipe Hook
+ *
+ * Drag-to-swipe navigation for slideshow mode. Press on the current slide to
+ * "pick it up", drag left/right, and on release either snap back (small drag)
+ * or advance to the next/previous slide (large drag or a quick flick).
+ *
+ * The gesture only translates the *current* slide (a "pick up & toss" feel) —
+ * the incoming slide arrives via its normal enter transition once navigation
+ * commits. The current slide is already mounted and settled, so translating it
+ * is a pure `transform` with no animation conflict.
+ *
+ * Mirrors the repo's canonical pointer-drag pattern (imageEditor/CanvasSurface):
+ * ref-held drag start + `setPointerCapture` + window pointermove/up/cancel +
+ * a threshold decision on release. Navigation itself is delegated to the
+ * caller's `onNext`/`onPrev` (DocPlayer's `slideNavActions`).
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { RefObject } from 'react';
+
+/** Fraction of the container width a drag must cross to commit a slide change. */
+const DISTANCE_RATIO = 0.3;
+/** A fast flick commits even below the distance threshold (px per millisecond). */
+const FLICK_VELOCITY = 0.5;
+/** Ignore flicks shorter than this so a click's micro-jitter never navigates (px). */
+const MIN_FLICK_DISTANCE = 12;
+/** Resistance factor applied when dragging past the first/last slide. */
+const RUBBER_BAND = 0.35;
+/** Default settle animation duration (ms). Must match the CSS in doc-animations.css. */
+const DEFAULT_SETTLE_MS = 260;
+
+/** The lifecycle of a swipe gesture. */
+export type SwipePhase = 'idle' | 'dragging' | 'settling';
+
+/** Outcome of a completed drag. */
+export type SwipeDecision = 'next' | 'prev' | 'snap';
+
+export interface SwipeDecisionInput {
+  /** Horizontal delta from drag start (px). Negative = leftward = next. */
+  dx: number;
+  /** Width of the slide container (px). */
+  width: number;
+  /** How long the drag lasted (ms). */
+  elapsedMs: number;
+  /** Whether a next slide exists. */
+  canNext: boolean;
+  /** Whether a previous slide exists. */
+  canPrev: boolean;
+}
+
+/**
+ * Pure decision: given a completed drag, should we advance, go back, or snap
+ * back? Committing requires either crossing the distance threshold or a fast
+ * flick, *and* a slide existing in that direction. Extracted from the hook so
+ * the threshold logic is testable without a DOM.
+ */
+export function decideSwipe({
+  dx,
+  width,
+  elapsedMs,
+  canNext,
+  canPrev,
+}: SwipeDecisionInput): SwipeDecision {
+  const distanceThreshold = width > 0 ? width * DISTANCE_RATIO : Infinity;
+  const velocity = elapsedMs > 0 ? Math.abs(dx) / elapsedMs : 0;
+  const passesDistance = Math.abs(dx) >= distanceThreshold;
+  const passesFlick = velocity >= FLICK_VELOCITY && Math.abs(dx) >= MIN_FLICK_DISTANCE;
+
+  if (!passesDistance && !passesFlick) return 'snap';
+  if (dx < 0) return canNext ? 'next' : 'snap'; // dragged left → next slide
+  if (dx > 0) return canPrev ? 'prev' : 'snap'; // dragged right → previous slide
+  return 'snap';
+}
+
+export interface UseSlideSwipeOptions {
+  /** Master gate — the gesture is inert unless enabled (slideshow mode, not headless). */
+  enabled: boolean;
+  /** Ref to the player container, used to measure width for the threshold. */
+  containerRef: RefObject<HTMLElement>;
+  /** Whether a next slide exists (`currentBlockIndex < total - 1`). */
+  canGoNext: boolean;
+  /** Whether a previous slide exists (`currentBlockIndex > 0`). */
+  canGoPrev: boolean;
+  /** Commit to the next slide. */
+  onNext: () => void;
+  /** Commit to the previous slide. */
+  onPrev: () => void;
+  /** Settle animation duration (ms); must match the CSS. Defaults to 260. */
+  settleMs?: number;
+}
+
+export interface UseSlideSwipeResult {
+  /** Live horizontal offset to apply to the active slide (px). */
+  offsetPx: number;
+  /** Current gesture phase — drives the transform transition class. */
+  phase: SwipePhase;
+  /** Attach to the container's `onPointerDown`. */
+  onPointerDown: (e: React.PointerEvent) => void;
+}
+
+interface DragState {
+  pointerId: number;
+  startX: number;
+  startTime: number;
+  target: Element;
+}
+
+/**
+ * Manage the swipe gesture state machine for a slideshow player.
+ */
+export function useSlideSwipe(opts: UseSlideSwipeOptions): UseSlideSwipeResult {
+  const settleMs = opts.settleMs ?? DEFAULT_SETTLE_MS;
+
+  const [offsetPx, setOffsetPx] = useState(0);
+  const [phase, setPhase] = useState<SwipePhase>('idle');
+
+  // Keep the latest options in a ref so the window listeners (bound once) never
+  // read stale callbacks/flags.
+  const optsRef = useRef(opts);
+  optsRef.current = opts;
+
+  const dragRef = useRef<DragState | null>(null);
+  const phaseRef = useRef<SwipePhase>('idle');
+  phaseRef.current = phase;
+  const settleTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const settleRaf = useRef<number | null>(null);
+
+  const clearPending = useCallback(() => {
+    if (settleTimer.current != null) {
+      clearTimeout(settleTimer.current);
+      settleTimer.current = null;
+    }
+    if (settleRaf.current != null) {
+      cancelAnimationFrame(settleRaf.current);
+      settleRaf.current = null;
+    }
+  }, []);
+
+  const onPointerDown = useCallback((e: React.PointerEvent) => {
+    const o = optsRef.current;
+    if (!o.enabled) return;
+    // Don't interrupt an in-flight fling/snap.
+    if (phaseRef.current === 'settling') return;
+    // Only the primary mouse button initiates a drag; touch/pen always do.
+    if (e.pointerType === 'mouse' && e.button !== 0) return;
+    // Let interactive chrome (prev/next buttons, links) handle their own events.
+    const target = e.target as Element;
+    if (target.closest?.('button, a, input, textarea, select, [data-no-swipe]')) return;
+
+    dragRef.current = {
+      pointerId: e.pointerId,
+      startX: e.clientX,
+      startTime: performance.now(),
+      target,
+    };
+    try {
+      target.setPointerCapture?.(e.pointerId);
+    } catch {
+      // Pointer capture is best-effort; window listeners still receive events.
+    }
+    setPhase('dragging');
+    setOffsetPx(0);
+  }, []);
+
+  // Bind move/up/cancel on window once. Handlers read live state from refs, so
+  // they never need re-binding and never go stale.
+  useEffect(() => {
+    function currentWidth(): number {
+      return optsRef.current.containerRef.current?.getBoundingClientRect().width ?? 0;
+    }
+
+    function endDrag(drag: DragState) {
+      dragRef.current = null;
+      try {
+        drag.target.releasePointerCapture?.(drag.pointerId);
+      } catch {
+        // ignore — capture may already be released
+      }
+    }
+
+    function settleTo(target: number, onArrive?: () => void) {
+      // Switch on the transition class first (offset unchanged), then move to the
+      // target on the next frame so the browser reliably animates the change.
+      setPhase('settling');
+      settleRaf.current = requestAnimationFrame(() => {
+        settleRaf.current = null;
+        setOffsetPx(target);
+        settleTimer.current = setTimeout(() => {
+          settleTimer.current = null;
+          onArrive?.();
+          setOffsetPx(0);
+          setPhase('idle');
+        }, settleMs);
+      });
+    }
+
+    function onMove(e: PointerEvent) {
+      const drag = dragRef.current;
+      if (!drag || e.pointerId !== drag.pointerId) return;
+      const o = optsRef.current;
+      const raw = e.clientX - drag.startX;
+      const blocked = (raw > 0 && !o.canGoPrev) || (raw < 0 && !o.canGoNext);
+      setOffsetPx(blocked ? raw * RUBBER_BAND : raw);
+    }
+
+    function onUp(e: PointerEvent) {
+      const drag = dragRef.current;
+      if (!drag || e.pointerId !== drag.pointerId) return;
+      endDrag(drag);
+      const o = optsRef.current;
+      const rawDx = e.clientX - drag.startX;
+      const width = currentWidth();
+      const elapsedMs = performance.now() - drag.startTime;
+      const decision = decideSwipe({
+        dx: rawDx,
+        width,
+        elapsedMs,
+        canNext: o.canGoNext,
+        canPrev: o.canGoPrev,
+      });
+
+      if (decision === 'snap') {
+        settleTo(0);
+        return;
+      }
+      // Fling fully off-screen in the drag direction, then commit navigation.
+      // Never move the slide back toward center first (guard against over-drag).
+      const distance = Math.max(width, Math.abs(rawDx));
+      const target = decision === 'next' ? -distance : distance;
+      settleTo(target, decision === 'next' ? o.onNext : o.onPrev);
+    }
+
+    function onCancel(e: PointerEvent) {
+      const drag = dragRef.current;
+      if (!drag || e.pointerId !== drag.pointerId) return;
+      endDrag(drag);
+      settleTo(0);
+    }
+
+    window.addEventListener('pointermove', onMove);
+    window.addEventListener('pointerup', onUp);
+    window.addEventListener('pointercancel', onCancel);
+    return () => {
+      window.removeEventListener('pointermove', onMove);
+      window.removeEventListener('pointerup', onUp);
+      window.removeEventListener('pointercancel', onCancel);
+    };
+  }, [settleMs]);
+
+  // Reset all in-flight state if the gesture is disabled mid-drag (e.g. mode switch).
+  useEffect(() => {
+    if (!opts.enabled) {
+      dragRef.current = null;
+      clearPending();
+      setPhase('idle');
+      setOffsetPx(0);
+    }
+  }, [opts.enabled, clearPending]);
+
+  // Cancel any pending settle on unmount.
+  useEffect(() => clearPending, [clearPending]);
+
+  return { offsetPx, phase, onPointerDown };
+}

package/src/index.ts

@@ -40,7 +40,7 @@ export { MediaContext, useMediaProvider, useMediaUrl } from './hooks/MediaContex
 export { useAutoSurface } from './hooks/useAutoSurface.js';
 
 // Types
-export type { AudioProvider, AudioState, AudioActions } from './hooks/AudioProvider.js';
+export type { AudioController, AudioState, AudioActions } from './hooks/AudioController.js';
 export type {
   PlaybackState,
   PlaybackActions,

package/src/jsonView/useJsonViewTokens.ts

@@ -5,13 +5,8 @@
  */
 
 import { useMemo } from 'react';
-import {
-  applySurface,
-  resolveFontFamily,
-  type SurfaceScheme,
-  type Theme,
-} from '@bendyline/squisq/schemas';
-import { DEFAULT_THEME } from '@bendyline/squisq/doc';
+import { type SurfaceScheme, type Theme } from '@bendyline/squisq/schemas';
+import { buildJsonFormTokens, resolveJsonFormTheme } from '@bendyline/squisq/jsonForm';
 import { useAutoSurface } from '../hooks/useAutoSurface';
 
 export interface JsonViewTokens {
@@ -29,29 +24,9 @@ export function useJsonViewTokens(
   const effectiveSurface = surface === 'auto' ? auto : (surface ?? undefined);
 
   return useMemo(() => {
-    const baseTheme = theme ?? DEFAULT_THEME;
-    const finalTheme = effectiveSurface ? applySurface(baseTheme, effectiveSurface) : baseTheme;
-
-    const titleFont = resolveFontFamily(finalTheme.typography.titleFont, 'system-ui, sans-serif');
-    const bodyFont = resolveFontFamily(finalTheme.typography.bodyFont, 'system-ui, sans-serif');
-    const monoFont = resolveFontFamily(
-      finalTheme.typography.monoFont,
-      'ui-monospace, Consolas, monospace',
-    );
-
-    const style: React.CSSProperties = {
-      ['--squisq-json-bg' as string]: finalTheme.colors.background,
-      ['--squisq-json-text' as string]: finalTheme.colors.text,
-      ['--squisq-json-muted' as string]: finalTheme.colors.textMuted,
-      ['--squisq-json-primary' as string]: finalTheme.colors.primary,
-      ['--squisq-json-accent' as string]: finalTheme.colors.secondary,
-      ['--squisq-json-border' as string]: `color-mix(in srgb, ${finalTheme.colors.textMuted} 35%, transparent)`,
-      ['--squisq-json-title-font' as string]: titleFont,
-      ['--squisq-json-body-font' as string]: bodyFont,
-      ['--squisq-json-mono-font' as string]: monoFont,
-      ['--squisq-json-radius' as string]: `${finalTheme.style.borderRadius ?? 8}px`,
-    };
-
-    return { style, theme: finalTheme };
+    const style = buildJsonFormTokens(theme, effectiveSurface, {
+      prefix: '--squisq-json',
+    }) as unknown as React.CSSProperties;
+    return { style, theme: resolveJsonFormTheme(theme, effectiveSurface) };
   }, [theme, effectiveSurface]);
 }

package/src/standalone-entry.tsx

@@ -206,7 +206,7 @@ export function mount(element: Element, doc: Doc, options: MountOptions = {}): v
     });
   } else {
     content = createElement(DocPlayer, {
-      script: finalDoc,
+      doc: finalDoc,
       basePath,
       displayMode: 'slideshow',
       autoPlay: renderMode ? false : autoPlay,

package/src/styles/doc-animations.css

@@ -2215,6 +2215,32 @@
   z-index: 1;
 }
 
+/* Drag-to-swipe (slideshow mode) — the active slide tracks the pointer 1:1
+   while dragging (no transition), then eases to its resting position (snap
+   back) or flings off-screen (commit) on release. The 260ms below must match
+   DEFAULT_SETTLE_MS in hooks/useSlideSwipe.ts. Like the block slide/push
+   transitions, this is a brief, purposeful motion, so it is intentionally left
+   running under prefers-reduced-motion (only long ambient loops are frozen). */
+.doc-player__block--active.doc-player__block--dragging {
+  transition: none;
+}
+
+.doc-player__block--active.doc-player__block--settling {
+  transition: transform 260ms cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+.doc-player--swipe {
+  cursor: grab;
+  /* Slideshow presentation surface: suppress text selection so a mouse drag
+     never starts a selection instead of a swipe. */
+  -webkit-user-select: none;
+  user-select: none;
+}
+
+.doc-player--swipe.doc-player--grabbing {
+  cursor: grabbing;
+}
+
 /* Tap-to-toggle play/pause feedback */
 .doc-player__tap-feedback {
   position: absolute;
@@ -2347,3 +2373,23 @@
     animation: none;
   }
 }
+
+/* ============================================
+   Empty state
+   Rendered by <DocPlayer> when neither `doc` nor `markdown` is provided.
+   ============================================ */
+.doc-player--empty {
+  min-height: 120px;
+  width: 100%;
+  background: #f0f0f0;
+}
+
+/* ============================================
+   Missing-stylesheet sentinel
+   DocPlayer reads this custom property at mount (dev builds only) and
+   warns when it computes empty — i.e. when the host app forgot to import
+   "@bendyline/squisq-react/styles".
+   ============================================ */
+.doc-player {
+  --squisq-styles-loaded: 1;
+}