@bendyline/squisq-react 0.1.2

package/src/styles/doc-animations.css

@@ -0,0 +1,458 @@
+/**
+ * Doc Animations
+ *
+ * CSS keyframe animations for the visual doc system.
+ * Designed to be ES2015/Chrome 49 compatible for Coherent GT (MSFS).
+ *
+ * Animation classes are applied dynamically based on Doc.
+ * Each animation has variants for common durations.
+ */
+
+/* ============================================
+   Slow Zoom Effect
+   Slow zoom with optional pan for cinematic feel
+   ============================================ */
+
+@keyframes slowZoomIn {
+  from {
+    transform: scale(1);
+  }
+  to {
+    transform: scale(1.15);
+  }
+}
+
+@keyframes slowZoomOut {
+  from {
+    transform: scale(1.15);
+  }
+  to {
+    transform: scale(1);
+  }
+}
+
+@keyframes slowZoomPanLeft {
+  from {
+    transform: translateX(0) scale(1.1);
+  }
+  to {
+    transform: translateX(-8%) scale(1.1);
+  }
+}
+
+@keyframes slowZoomPanRight {
+  from {
+    transform: translateX(-8%) scale(1.1);
+  }
+  to {
+    transform: translateX(0) scale(1.1);
+  }
+}
+
+@keyframes slowZoomPanUp {
+  from {
+    transform: translateY(0) scale(1.1);
+  }
+  to {
+    transform: translateY(-8%) scale(1.1);
+  }
+}
+
+@keyframes slowZoomPanDown {
+  from {
+    transform: translateY(-8%) scale(1.1);
+  }
+  to {
+    transform: translateY(0) scale(1.1);
+  }
+}
+
+/* Slow zoom combined zoom + pan */
+@keyframes slowZoomCombinedPanLeft {
+  from {
+    transform: translateX(0) scale(1);
+  }
+  to {
+    transform: translateX(-5%) scale(1.12);
+  }
+}
+
+@keyframes slowZoomCombinedPanRight {
+  from {
+    transform: translateX(-5%) scale(1.12);
+  }
+  to {
+    transform: translateX(0) scale(1);
+  }
+}
+
+/* ============================================
+   Fade Animations
+   ============================================ */
+
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes fadeOut {
+  from {
+    opacity: 1;
+  }
+  to {
+    opacity: 0;
+  }
+}
+
+@keyframes fadeInUp {
+  from {
+    opacity: 0;
+    transform: translateY(20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes fadeInDown {
+  from {
+    opacity: 0;
+    transform: translateY(-20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/* ============================================
+   Zoom Animations
+   ============================================ */
+
+@keyframes zoomIn {
+  from {
+    transform: scale(0.9);
+    opacity: 0;
+  }
+  to {
+    transform: scale(1);
+    opacity: 1;
+  }
+}
+
+@keyframes zoomOut {
+  from {
+    transform: scale(1);
+    opacity: 1;
+  }
+  to {
+    transform: scale(0.9);
+    opacity: 0;
+  }
+}
+
+/* ============================================
+   Pan/Slide Animations
+   ============================================ */
+
+@keyframes panLeft {
+  from {
+    transform: translateX(0);
+  }
+  to {
+    transform: translateX(-10%);
+  }
+}
+
+@keyframes panRight {
+  from {
+    transform: translateX(-10%);
+  }
+  to {
+    transform: translateX(0);
+  }
+}
+
+@keyframes slideInLeft {
+  from {
+    transform: translateX(-100%);
+  }
+  to {
+    transform: translateX(0);
+  }
+}
+
+@keyframes slideInRight {
+  from {
+    transform: translateX(100%);
+  }
+  to {
+    transform: translateX(0);
+  }
+}
+
+@keyframes slideOutLeft {
+  from {
+    transform: translateX(0);
+  }
+  to {
+    transform: translateX(-100%);
+  }
+}
+
+@keyframes slideOutRight {
+  from {
+    transform: translateX(0);
+  }
+  to {
+    transform: translateX(100%);
+  }
+}
+
+/* ============================================
+   Text Animations
+   ============================================ */
+
+@keyframes typewriter {
+  from {
+    clip-path: inset(0 100% 0 0);
+  }
+  to {
+    clip-path: inset(0 0 0 0);
+  }
+}
+
+/* Fallback for browsers without clip-path */
+@keyframes typewriterFallback {
+  from {
+    width: 0;
+    overflow: hidden;
+  }
+  to {
+    width: 100%;
+    overflow: hidden;
+  }
+}
+
+/* ============================================
+   Block Transitions
+   Applied to entire block containers
+   ============================================ */
+
+.transition-fade-enter {
+  animation: fadeIn var(--transition-duration, 1.5s) ease-out forwards;
+}
+
+.transition-fade-exit {
+  animation: fadeOut var(--transition-duration, 1.5s) ease-out forwards;
+}
+
+.transition-dissolve-enter {
+  animation: fadeIn var(--transition-duration, 2s) ease-in-out forwards;
+}
+
+.transition-dissolve-exit {
+  animation: fadeOut var(--transition-duration, 2s) ease-in-out forwards;
+}
+
+.transition-slideLeft-enter {
+  animation: slideInRight var(--transition-duration, 0.8s) ease-out forwards;
+}
+
+.transition-slideLeft-exit {
+  animation: slideOutLeft var(--transition-duration, 0.8s) ease-out forwards;
+}
+
+.transition-slideRight-enter {
+  animation: slideInLeft var(--transition-duration, 0.8s) ease-out forwards;
+}
+
+.transition-slideRight-exit {
+  animation: slideOutRight var(--transition-duration, 0.8s) ease-out forwards;
+}
+
+/* ============================================
+   Animation Utility Classes
+   Applied dynamically based on layer.animation
+   ============================================ */
+
+.anim-none {
+  animation: none;
+}
+
+.anim-fadeIn {
+  animation: fadeIn var(--anim-duration, 1s) var(--anim-easing, ease-out) var(--anim-delay, 0s)
+    forwards;
+}
+
+.anim-fadeOut {
+  animation: fadeOut var(--anim-duration, 1s) var(--anim-easing, ease-out) var(--anim-delay, 0s)
+    forwards;
+}
+
+.anim-fadeInUp {
+  animation: fadeInUp var(--anim-duration, 0.6s) var(--anim-easing, ease-out) var(--anim-delay, 0s)
+    forwards;
+}
+
+.anim-slowZoom-in {
+  animation: slowZoomIn var(--anim-duration, 8s) var(--anim-easing, linear) var(--anim-delay, 0s)
+    forwards;
+}
+
+.anim-slowZoom-out {
+  animation: slowZoomOut var(--anim-duration, 8s) var(--anim-easing, linear) var(--anim-delay, 0s)
+    forwards;
+}
+
+.anim-slowZoom-panLeft {
+  animation: slowZoomCombinedPanLeft var(--anim-duration, 8s) var(--anim-easing, linear)
+    var(--anim-delay, 0s) forwards;
+}
+
+.anim-slowZoom-panRight {
+  animation: slowZoomCombinedPanRight var(--anim-duration, 8s) var(--anim-easing, linear)
+    var(--anim-delay, 0s) forwards;
+}
+
+.anim-zoomIn {
+  animation: zoomIn var(--anim-duration, 0.5s) var(--anim-easing, ease-out) var(--anim-delay, 0s)
+    forwards;
+}
+
+.anim-zoomOut {
+  animation: zoomOut var(--anim-duration, 0.5s) var(--anim-easing, ease-out) var(--anim-delay, 0s)
+    forwards;
+}
+
+.anim-panLeft {
+  animation: panLeft var(--anim-duration, 8s) var(--anim-easing, linear) var(--anim-delay, 0s)
+    forwards;
+}
+
+.anim-panRight {
+  animation: panRight var(--anim-duration, 8s) var(--anim-easing, linear) var(--anim-delay, 0s)
+    forwards;
+}
+
+.anim-typewriter {
+  animation: typewriter var(--anim-duration, 2s) var(--anim-easing, steps(40, end))
+    var(--anim-delay, 0s) forwards;
+}
+
+/* ============================================
+   Doc Player Container Styles
+   ============================================ */
+
+.doc-player {
+  position: relative;
+  overflow: hidden;
+  /* clip-path provides a hard pixel clip that catches SVG foreignObject bleed
+     which can escape overflow:hidden in some browsers */
+  clip-path: inset(0);
+  background: #000;
+  /* Ensure max dimensions work with aspect-ratio */
+  max-width: 100%;
+  max-height: 100%;
+}
+
+.doc-player__viewport {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+}
+
+.doc-player__block {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+}
+
+.doc-player__block--active {
+  z-index: 2;
+}
+
+.doc-player__block--previous {
+  z-index: 1;
+}
+
+/* Tap-to-toggle play/pause feedback */
+.doc-player__tap-feedback {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  z-index: 150;
+  pointer-events: none;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 72px;
+  height: 72px;
+  border-radius: 50%;
+  background: rgba(0, 0, 0, 0.45);
+  animation: tap-feedback-fade 0.6s ease-out forwards;
+}
+
+@keyframes tap-feedback-fade {
+  0% {
+    opacity: 1;
+    transform: translate(-50%, -50%) scale(1);
+  }
+  100% {
+    opacity: 0;
+    transform: translate(-50%, -50%) scale(1.3);
+  }
+}
+
+/* SVG block container */
+.block-svg {
+  width: 100%;
+  height: 100%;
+  display: block;
+}
+
+/* Layer containers within SVG */
+.block-layer {
+  overflow: hidden;
+}
+
+.block-layer--image {
+  /* Images need overflow visible for Ken Burns */
+  overflow: visible;
+}
+
+/* ============================================
+   Text Styling Helpers
+   ============================================ */
+
+.text-shadow {
+  text-shadow:
+    0 2px 4px rgba(0, 0, 0, 0.8),
+    0 4px 8px rgba(0, 0, 0, 0.4);
+}
+
+.text-shadow-light {
+  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.6);
+}
+
+/* Text background box */
+.text-box {
+  background: rgba(0, 0, 0, 0.6);
+  padding: 16px 24px;
+  border-radius: 4px;
+}
+
+.text-box--light {
+  background: rgba(255, 255, 255, 0.9);
+  color: #1a1a1a;
+}

package/src/types.ts

@@ -0,0 +1,152 @@
+/**
+ * Doc Player Control Types
+ *
+ * Shared type definitions for doc player controls across different
+ * layout modes (overlay, sidebar, bottom). These interfaces allow
+ * control components to be decoupled from the core DocPlayer.
+ *
+ * Related Files:
+ * - DocPlayer.tsx — Core player component
+ * - DocProgressBar.tsx — Extracted progress bar
+ * - DocControlsOverlay.tsx — Overlay controls (default)
+ * - DocControlsSidebar.tsx — Vertical sidebar controls
+ * - DocControlsBottom.tsx — Horizontal bottom strip controls
+ */
+
+import type { Block } from '@bendyline/squisq/schemas';
+
+/** Layout mode for doc player controls */
+export type ControlsLayout = 'overlay' | 'sidebar' | 'bottom';
+
+/**
+ * Display mode for DocPlayer.
+ *
+ * - `'video'` — Traditional video-style playback with play/pause, scrub bar,
+ *   and time-based auto-advance. Default mode.
+ * - `'slideshow'` — PowerPoint-style presentation with prev/next navigation.
+ *   Blocks are treated as static slides that only change on user click.
+ *   No auto-advance, no scrub bar.
+ * - `'linear'` — Long-scrolling document view. Renders the full markdown as
+ *   readable HTML with template-annotated sections shown as inline SVG cards.
+ *   No audio, no timeline, no controls — just a scrollable page.
+ */
+export type DisplayMode = 'video' | 'slideshow' | 'linear';
+
+/** Slide navigation actions for slideshow display mode */
+export interface SlideNavActions {
+  /** Navigate to the next slide */
+  nextSlide: () => void;
+  /** Navigate to the previous slide */
+  prevSlide: () => void;
+  /** Navigate to a specific slide by index (0-based) */
+  goToSlide: (index: number) => void;
+}
+
+/** Playback state exposed to external control components */
+export interface PlaybackState {
+  isPlaying: boolean;
+  currentTime: number;
+  totalDuration: number;
+  currentBlockIndex: number;
+  totalBlocks: number;
+  docProgress: number;
+  hasCaptions: boolean;
+  captionsEnabled: boolean;
+  isFullscreen?: boolean;
+  /** Current audio segment index (0-based) */
+  currentSegmentIndex: number;
+  /** Current audio segment name (e.g., 'intro', 'history') */
+  currentSegmentName: string | null;
+  /** Current block data (for extracting image info, etc.) */
+  currentBlock: Block | null;
+}
+
+/** Playback actions exposed to external control components */
+export interface PlaybackActions {
+  toggle: () => void;
+  restart: () => void;
+  seekTo: (time: number) => void;
+  setCaptionsEnabled: (enabled: boolean) => void;
+  toggleFullscreen?: () => void;
+}
+
+/** Block marker data for the progress bar */
+export interface BlockMarker {
+  block: Block;
+  index: number;
+  position: number;
+  title: string;
+  /** True if this block is the first in a new audio segment (section boundary) */
+  isSectionStart: boolean;
+}
+
+// ============================================
+// Render-mode API (exposed on window for Playwright / debug)
+// ============================================
+
+/** Block metadata returned by SquisqRenderAPI.getBlocks() */
+export interface RenderBlockInfo {
+  id: string;
+  template: string;
+  startTime: number;
+  duration: number;
+}
+
+/** Audio segment info returned by SquisqRenderAPI.getAudioSegments() */
+export interface RenderAudioSegmentInfo {
+  src: string;
+  name: string;
+  duration: number;
+  startTime: number;
+}
+
+/** Caption phrase info returned by SquisqRenderAPI.getCaptions() */
+export interface RenderCaptionInfo {
+  text: string;
+  startTime: number;
+  endTime: number;
+}
+
+/** Chapter marker returned by SquisqRenderAPI.getChapters() */
+export interface RenderChapterInfo {
+  title: string;
+  startTime: number;
+  duration: number;
+}
+
+/**
+ * API surface exposed on `window` in render mode and debug mode.
+ * Used by Playwright for video export and by ?debug=true for testing.
+ *
+ * @example
+ * ```ts
+ * // In Playwright:
+ * const w = window as unknown as SquisqWindow;
+ * await w.seekTo!(5.0);
+ * const blocks = w.getBlocks!();
+ * ```
+ */
+export interface SquisqRenderAPI {
+  seekTo: (time: number) => Promise<void>;
+  getDuration: () => number;
+  getBlocks: () => RenderBlockInfo[];
+  getAudioSegments: () => RenderAudioSegmentInfo[];
+  getCaptions: () => RenderCaptionInfo[];
+  getChapters: () => RenderChapterInfo[];
+  showCover: () => Promise<void>;
+  hideCover: () => Promise<void>;
+  hasCoverBlock: () => boolean;
+}
+
+/**
+ * Window augmented with optional SquisqRenderAPI properties.
+ * Each property is optional because they're only present in render/debug mode.
+ */
+export type SquisqWindow = Window & typeof globalThis & Partial<SquisqRenderAPI>;
+
+/** Format time in seconds to MM:SS string */
+export function formatTime(seconds: number): string {
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.floor(seconds % 60);
+  return `${mins}:${secs.toString().padStart(2, '0')}`;
+}

package/src/utils/animationUtils.ts

@@ -0,0 +1,13 @@
+/**
+ * Animation Utilities (React)
+ *
+ * Re-exports the shared animation utilities for use in the React package.
+ * All animation logic is in shared/doc/utils.
+ */
+
+export {
+  getAnimationStyle,
+  getDefaultAnimationDuration,
+  getTransitionClass,
+  getAnimationProgress,
+} from '@bendyline/squisq/doc';

package/src/utils/layerUtils.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared utilities for layer components.
+ *
+ * Resolves position values and anchor offsets used by all layer types.
+ */
+
+/**
+ * Resolve a position value (number or percentage string) to pixels.
+ */
+export function resolveValue(value: number | string, dimension: number): number {
+  if (typeof value === 'number') {
+    return value;
+  }
+  if (value.endsWith('%')) {
+    const percent = parseFloat(value);
+    return (percent / 100) * dimension;
+  }
+  return parseFloat(value);
+}
+
+/**
+ * Get offset based on anchor point.
+ */
+export function getAnchorOffset(
+  anchor: string | undefined,
+  width: number,
+  height: number,
+): { x: number; y: number } {
+  switch (anchor) {
+    case 'center':
+      return { x: -width / 2, y: -height / 2 };
+    case 'top-right':
+      return { x: -width, y: 0 };
+    case 'bottom-left':
+      return { x: 0, y: -height };
+    case 'bottom-right':
+      return { x: -width, y: -height };
+    case 'top-left':
+    default:
+      return { x: 0, y: 0 };
+  }
+}