@bendyline/squisq 0.1.1

package/src/doc/templates/accentImage.ts

@@ -0,0 +1,338 @@
+/**
+ * Accent Image Utility
+ *
+ * Creates image layers and layout adjustments for accent images on text-based slides.
+ * Accent images are tasteful additions that complement text without overwhelming it.
+ *
+ * Layout patterns:
+ * - left-strip: 35% width vertical strip on left, text area shifted to right 65%
+ * - right-strip: 35% width vertical strip on right, text area shifted to left 65%
+ * - bottom-strip: 35% height horizontal strip at bottom, text area in upper 65%
+ * - corner-inset: Small 25% corner image with gradient vignette
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+import type { Layer, ImageLayer, ShapeLayer, Animation } from '../../schemas/Doc.js';
+import type { AccentImage, AccentPosition } from '../../schemas/BlockTemplates.js';
+
+const PERCENTAGE_RE = /^(\d+(?:\.\d+)?)\s*%?$/;
+
+/**
+ * Layout adjustments when an accent image is present.
+ * Templates use these values to reposition their text content.
+ */
+export interface AccentLayout {
+  /** X offset for text center (e.g., '64%' for left-strip) */
+  textCenterX: string;
+  /** Width available for text content */
+  textWidth: string;
+  /** Y offset adjustment for vertical positioning */
+  textYAdjust: number;
+  /** Whether to adjust Y positions (for bottom-strip) */
+  adjustY: boolean;
+}
+
+/**
+ * Default layout when no accent image is present.
+ */
+export const DEFAULT_LAYOUT: AccentLayout = {
+  textCenterX: '50%',
+  textWidth: '85%',
+  textYAdjust: 0,
+  adjustY: false,
+};
+
+/**
+ * Map ambientMotion values to proper Ken Burns animations.
+ * Uses slowZoom variants which provide smooth pan/zoom without opacity changes.
+ * Supports both standard values ('zoomIn', 'panLeft', etc.) and legacy
+ * aliases ('in', 'out', 'left', 'right') for backward compatibility.
+ *
+ * @param motion - The ambient motion value (e.g., 'zoomIn', 'panLeft')
+ * @param duration - Optional animation duration in seconds
+ */
+export function mapAmbientMotion(
+  motion: string | undefined,
+  duration?: number,
+): Animation | undefined {
+  if (!motion) return undefined;
+  const base = duration !== undefined ? { duration } : {};
+  switch (motion) {
+    case 'zoomIn':
+    case 'in':
+      return { type: 'slowZoom', direction: 'in', ...base };
+    case 'zoomOut':
+    case 'out':
+      return { type: 'slowZoom', direction: 'out', ...base };
+    case 'panLeft':
+    case 'left':
+      return { type: 'slowZoom', panDirection: 'left', ...base };
+    case 'panRight':
+    case 'right':
+      return { type: 'slowZoom', panDirection: 'right', ...base };
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Accent strip width/height as percentage.
+ * 35% gives the image enough presence to complement the text without overwhelming it.
+ */
+const STRIP_SIZE = 35;
+const STRIP_SIZE_PCT = `${STRIP_SIZE}%`;
+
+/**
+ * Get layout adjustments based on accent position.
+ */
+export function getAccentLayout(position: AccentPosition): AccentLayout {
+  switch (position) {
+    case 'left-strip':
+      return {
+        textCenterX: `${50 + STRIP_SIZE / 2}%`, // Shift center right
+        textWidth: `${100 - STRIP_SIZE - 8}%`, // Leave margin
+        textYAdjust: 0,
+        adjustY: false,
+      };
+    case 'right-strip':
+      return {
+        textCenterX: `${50 - STRIP_SIZE / 2}%`, // Shift center left
+        textWidth: `${100 - STRIP_SIZE - 8}%`,
+        textYAdjust: 0,
+        adjustY: false,
+      };
+    case 'bottom-strip':
+      return {
+        textCenterX: '50%',
+        textWidth: '85%',
+        textYAdjust: -10, // Shift content up by 10%
+        adjustY: true,
+      };
+    case 'corner-inset':
+      return {
+        textCenterX: '45%', // Slight shift to avoid corner
+        textWidth: '70%',
+        textYAdjust: 0,
+        adjustY: false,
+      };
+    default:
+      return DEFAULT_LAYOUT;
+  }
+}
+
+/**
+ * Create layers for an accent image.
+ * Returns the image layer and any overlay/gradient layers needed.
+ */
+export function createAccentLayers(accent: AccentImage, slideId: string): Layer[] {
+  const layers: Layer[] = [];
+  const { src, alt, position, ambientMotion, credit, license } = accent;
+
+  switch (position) {
+    case 'left-strip':
+      layers.push(createStripImage(src, alt, 'left', slideId, ambientMotion, credit, license));
+      layers.push(createStripGradient('left', slideId));
+      break;
+
+    case 'right-strip':
+      layers.push(createStripImage(src, alt, 'right', slideId, ambientMotion, credit, license));
+      layers.push(createStripGradient('right', slideId));
+      break;
+
+    case 'bottom-strip':
+      layers.push(createBottomStripImage(src, alt, slideId, ambientMotion, credit, license));
+      layers.push(createBottomStripGradient(slideId));
+      break;
+
+    case 'corner-inset':
+      layers.push(createCornerInsetImage(src, alt, slideId, ambientMotion, credit, license));
+      layers.push(createCornerVignette(slideId));
+      break;
+  }
+
+  return layers;
+}
+
+/**
+ * Create a vertical strip image layer.
+ */
+function createStripImage(
+  src: string,
+  alt: string,
+  side: 'left' | 'right',
+  slideId: string,
+  ambientMotion?: AccentImage['ambientMotion'],
+  credit?: string,
+  license?: string,
+): ImageLayer {
+  return {
+    type: 'image',
+    id: `${slideId}-accent-img`,
+    content: {
+      src,
+      alt,
+      fit: 'cover',
+      credit,
+      license,
+    },
+    position: {
+      x: side === 'left' ? 0 : `${100 - STRIP_SIZE}%`,
+      y: 0,
+      width: STRIP_SIZE_PCT,
+      height: '100%',
+    },
+    animation: mapAmbientMotion(ambientMotion, 15),
+  };
+}
+
+/**
+ * Create a gradient overlay for strip images (fades to background).
+ */
+function createStripGradient(side: 'left' | 'right', slideId: string): ShapeLayer {
+  // Gradient from transparent to background color at the edge
+  const gradientId = side === 'left' ? 'accent-gradient-left' : 'accent-gradient-right';
+
+  return {
+    type: 'shape',
+    id: `${slideId}-accent-fade`,
+    content: {
+      shape: 'rect',
+      // SVG gradient will be handled by the renderer
+      // Using a semi-transparent overlay as fallback
+      fill: `url(#${gradientId})`,
+    },
+    position: {
+      x: side === 'left' ? `${STRIP_SIZE - 8}%` : `${100 - STRIP_SIZE}%`,
+      y: 0,
+      width: '10%',
+      height: '100%',
+    },
+  };
+}
+
+/**
+ * Create a horizontal bottom strip image layer.
+ */
+function createBottomStripImage(
+  src: string,
+  alt: string,
+  slideId: string,
+  ambientMotion?: AccentImage['ambientMotion'],
+  credit?: string,
+  license?: string,
+): ImageLayer {
+  return {
+    type: 'image',
+    id: `${slideId}-accent-img`,
+    content: {
+      src,
+      alt,
+      fit: 'cover',
+      credit,
+      license,
+    },
+    position: {
+      x: 0,
+      y: `${100 - STRIP_SIZE}%`,
+      width: '100%',
+      height: STRIP_SIZE_PCT,
+    },
+    animation: mapAmbientMotion(ambientMotion, 15),
+  };
+}
+
+/**
+ * Create a gradient overlay for bottom strip (fades up to background).
+ */
+function createBottomStripGradient(slideId: string): ShapeLayer {
+  return {
+    type: 'shape',
+    id: `${slideId}-accent-fade`,
+    content: {
+      shape: 'rect',
+      fill: 'url(#accent-gradient-bottom)',
+    },
+    position: {
+      x: 0,
+      y: `${100 - STRIP_SIZE - 8}%`,
+      width: '100%',
+      height: '12%',
+    },
+  };
+}
+
+/**
+ * Create a corner inset image layer.
+ */
+function createCornerInsetImage(
+  src: string,
+  alt: string,
+  slideId: string,
+  ambientMotion?: AccentImage['ambientMotion'],
+  credit?: string,
+  license?: string,
+): ImageLayer {
+  return {
+    type: 'image',
+    id: `${slideId}-accent-img`,
+    content: {
+      src,
+      alt,
+      fit: 'cover',
+      credit,
+      license,
+    },
+    position: {
+      x: '70%',
+      y: '60%',
+      width: '28%',
+      height: '38%',
+      anchor: 'top-left',
+    },
+    animation: mapAmbientMotion(ambientMotion, 15) ?? { type: 'fadeIn', duration: 2, delay: 0.5 },
+  };
+}
+
+/**
+ * Create a vignette overlay around corner inset.
+ */
+function createCornerVignette(slideId: string): ShapeLayer {
+  return {
+    type: 'shape',
+    id: `${slideId}-accent-vignette`,
+    content: {
+      shape: 'rect',
+      fill: 'url(#accent-vignette-corner)',
+      borderRadius: 8,
+    },
+    position: {
+      x: '69%',
+      y: '59%',
+      width: '30%',
+      height: '40%',
+    },
+  };
+}
+
+/**
+ * Adjust a Y position value based on accent layout.
+ * Used by templates to shift content when bottom-strip is present.
+ */
+export function adjustY(originalY: string | number, layout: AccentLayout): string {
+  if (!layout.adjustY || layout.textYAdjust === 0) {
+    return typeof originalY === 'number' ? `${originalY}%` : originalY;
+  }
+
+  // Parse percentage value
+  const yStr = typeof originalY === 'number' ? `${originalY}` : originalY;
+  const match = yStr.match(PERCENTAGE_RE);
+
+  if (match) {
+    const yValue = parseFloat(match[1]);
+    const adjusted = Math.max(5, yValue + layout.textYAdjust);
+    return `${adjusted}%`;
+  }
+
+  return yStr;
+}

package/src/doc/templates/captionUtils.ts

@@ -0,0 +1,33 @@
+/**
+ * Template Utilities
+ *
+ * Shared helpers for doc block templates:
+ * - Caption text cleaning
+ * - Common layer construction patterns
+ */
+
+import type { Layer } from '../../schemas/Doc.js';
+
+const TRAILING_PUNCT_RE = /[.;:!?]+$/;
+
+/**
+ * Strip trailing punctuation from a caption string.
+ * Image captions on blocks look cleaner without terminal periods,
+ * semicolons, or other sentence-ending punctuation.
+ */
+export function cleanCaption(text: string): string {
+  return text.replace(TRAILING_PUNCT_RE, '').trim();
+}
+
+/**
+ * Create a full-screen background shape layer.
+ * Most text-based templates start with this as their first layer.
+ */
+export function createBackgroundLayer(id: string, fill: string): Layer {
+  return {
+    type: 'shape',
+    id,
+    content: { shape: 'rect', fill },
+    position: { x: 0, y: 0, width: '100%', height: '100%' },
+  };
+}

package/src/doc/templates/comparisonBar.ts

@@ -0,0 +1,140 @@
+/**
+ * Comparison Bar Template
+ *
+ * Two horizontal bars showing relative numeric values side by side.
+ * Bar widths are proportional to the values for immediate visual comparison.
+ * Good for population, distance, or measurement comparisons.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+import type { Layer } from '../../schemas/Doc.js';
+import type { ComparisonBarInput, TemplateContext } from '../../schemas/BlockTemplates.js';
+import { scaledFontSize } from '../../schemas/BlockTemplates.js';
+import { resolveColorScheme } from '../utils/themeUtils.js';
+
+export function comparisonBar(input: ComparisonBarInput, context: TemplateContext): Layer[] {
+  const { leftLabel, leftValue, rightLabel, rightValue, unit, colorScheme = 'blue' } = input;
+  const { theme } = context;
+  const colors = resolveColorScheme(context, colorScheme);
+
+  const labelFontSize = scaledFontSize(28, context, false);
+  const valueFontSize = scaledFontSize(48, context, true);
+
+  // Calculate proportional bar widths (max bar = 65% of viewport width)
+  const maxValue = Math.max(leftValue, rightValue, 1);
+  const maxBarWidth = 65;
+  const leftBarWidth = (leftValue / maxValue) * maxBarWidth;
+  const rightBarWidth = (rightValue / maxValue) * maxBarWidth;
+
+  // Bar positioning
+  const barStartX = 15;
+  const barHeight = 6; // % of viewport height
+  const topBarY = 36;
+  const bottomBarY = 58;
+
+  // Format values for display
+  const formatValue = (v: number): string => {
+    if (v >= 1_000_000) return `${(v / 1_000_000).toFixed(1)}M`;
+    if (v >= 1_000) return `${(v / 1_000).toFixed(v >= 10_000 ? 0 : 1)}K`;
+    return v.toLocaleString();
+  };
+
+  const leftDisplay = unit ? `${formatValue(leftValue)} ${unit}` : formatValue(leftValue);
+  const rightDisplay = unit ? `${formatValue(rightValue)} ${unit}` : formatValue(rightValue);
+
+  return [
+    // Background
+    {
+      type: 'shape',
+      id: 'bg',
+      content: {
+        shape: 'rect',
+        fill: `linear-gradient(180deg, ${theme.colors.background} 0%, #0f1520 100%)`,
+      },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    },
+
+    // Top bar label
+    {
+      type: 'text',
+      id: 'left-label',
+      content: {
+        text: leftLabel,
+        style: { fontSize: labelFontSize, color: theme.colors.textMuted },
+      },
+      position: { x: `${barStartX}%`, y: `${topBarY - 8}%` },
+    },
+
+    // Top bar value
+    {
+      type: 'text',
+      id: 'left-value',
+      content: {
+        text: leftDisplay,
+        style: { fontSize: valueFontSize, fontWeight: 'bold', color: colors.text },
+      },
+      position: { x: `${barStartX + leftBarWidth + 2}%`, y: `${topBarY - 1}%` },
+      animation: { type: 'fadeIn', duration: 0.8, delay: 0.3 },
+    },
+
+    // Top bar
+    {
+      type: 'shape',
+      id: 'left-bar',
+      content: {
+        shape: 'rect',
+        fill: colors.text,
+        borderRadius: 4,
+      },
+      position: {
+        x: `${barStartX}%`,
+        y: `${topBarY}%`,
+        width: `${leftBarWidth}%`,
+        height: `${barHeight}%`,
+      },
+      animation: { type: 'fadeIn', duration: 1 },
+    },
+
+    // Bottom bar label
+    {
+      type: 'text',
+      id: 'right-label',
+      content: {
+        text: rightLabel,
+        style: { fontSize: labelFontSize, color: theme.colors.textMuted },
+      },
+      position: { x: `${barStartX}%`, y: `${bottomBarY - 8}%` },
+    },
+
+    // Bottom bar value
+    {
+      type: 'text',
+      id: 'right-value',
+      content: {
+        text: rightDisplay,
+        style: { fontSize: valueFontSize, fontWeight: 'bold', color: colors.accent },
+      },
+      position: { x: `${barStartX + rightBarWidth + 2}%`, y: `${bottomBarY - 1}%` },
+      animation: { type: 'fadeIn', duration: 0.8, delay: 0.6 },
+    },
+
+    // Bottom bar
+    {
+      type: 'shape',
+      id: 'right-bar',
+      content: {
+        shape: 'rect',
+        fill: colors.accent,
+        borderRadius: 4,
+      },
+      position: {
+        x: `${barStartX}%`,
+        y: `${bottomBarY}%`,
+        width: `${rightBarWidth}%`,
+        height: `${barHeight}%`,
+      },
+      animation: { type: 'fadeIn', duration: 1, delay: 0.3 },
+    },
+  ];
+}

package/src/doc/templates/coverBlock.ts

@@ -0,0 +1,156 @@
+/**
+ * Cover Block Template
+ *
+ * Full-screen hero image with title overlay, shown before playback starts.
+ * This is the "poster for the doc, displaying the
+ * article's hero image with elegant title treatment.
+ *
+ * Features:
+ * - Full-screen hero image with Ken Burns ambient motion
+ * - Gradient overlay for text readability
+ * - Large centered title with optional subtitle
+ * - No animation delays (shown at rest, not during playback)
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+import type { Layer } from '../../schemas/Doc.js';
+import type { TemplateContext } from '../../schemas/BlockTemplates.js';
+import { scaledFontSize } from '../../schemas/BlockTemplates.js';
+import type { StartBlockConfig } from '../../schemas/Doc.js';
+import { mapAmbientMotion } from './accentImage.js';
+
+/**
+ * Input for coverBlock template - matches StartBlockConfig
+ */
+export interface CoverBlockInput {
+  /** Path to hero image */
+  heroSrc: string;
+  /** Alt text for the hero image */
+  heroAlt?: string;
+  /** Title to display over the hero */
+  title: string;
+  /** Optional subtitle */
+  subtitle?: string;
+  /** Ambient motion for the hero image */
+  ambientMotion?: 'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight';
+  /** Photo credit / artist name */
+  heroCredit?: string;
+  /** License identifier */
+  heroLicense?: string;
+}
+
+/**
+ * Generate cover block layers from StartBlockConfig.
+ */
+export function coverBlock(input: CoverBlockInput, context: TemplateContext): Layer[] {
+  const { heroSrc, heroAlt, title, subtitle, ambientMotion, heroCredit, heroLicense } = input;
+  const { theme, layout } = context;
+
+  // Scale font sizes for viewport - use larger sizes for the cover
+  const titleFontSize = scaledFontSize(96, context, true);
+  const subtitleFontSize = scaledFontSize(36, context, false);
+
+  // Determine Ken Burns animation
+  const imageAnimation = mapAmbientMotion(ambientMotion);
+
+  const layers: Layer[] = [
+    // Full-screen hero image
+    {
+      type: 'image',
+      id: 'cover-hero',
+      content: {
+        src: heroSrc,
+        alt: heroAlt || title,
+        fit: 'cover',
+        credit: heroCredit,
+        license: heroLicense,
+      },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+      animation: imageAnimation,
+    },
+    // Gradient overlay for text readability - from bottom
+    {
+      type: 'shape',
+      id: 'cover-gradient',
+      content: {
+        shape: 'rect',
+        fill: 'linear-gradient(0deg, rgba(0,0,0,0.8) 0%, rgba(0,0,0,0.4) 40%, rgba(0,0,0,0.1) 70%, transparent 100%)',
+      },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    },
+    // Title - positioned lower in the frame to work with hero composition
+    {
+      type: 'text',
+      id: 'cover-title',
+      content: {
+        text: title,
+        style: {
+          fontSize: titleFontSize,
+          fontWeight: 'bold',
+          color: theme.colors.text,
+          textAlign: 'center',
+          shadow: true,
+        },
+      },
+      position: {
+        x: '50%',
+        y: subtitle ? '70%' : '75%',
+        anchor: 'center',
+        width: layout.maxTextWidth,
+      },
+      // No animation delay - shown immediately at rest
+      animation: { type: 'fadeIn', duration: 0.8 },
+    },
+  ];
+
+  // Add subtitle if provided
+  if (subtitle) {
+    layers.push({
+      type: 'text',
+      id: 'cover-subtitle',
+      content: {
+        text: subtitle,
+        style: {
+          fontSize: subtitleFontSize,
+          color: theme.colors.textMuted,
+          textAlign: 'center',
+          lineHeight: 1.5,
+        },
+      },
+      position: {
+        x: '50%',
+        y: '82%',
+        anchor: 'center',
+        width: layout.maxTextWidth,
+      },
+      animation: { type: 'fadeIn', duration: 0.8, delay: 0.2 },
+    });
+  }
+
+  return layers;
+}
+
+/**
+ * Convert StartBlockConfig to CoverBlockInput.
+ */
+export function startBlockToCoverInput(config: StartBlockConfig): CoverBlockInput {
+  return {
+    heroSrc: config.heroSrc,
+    heroAlt: config.heroAlt,
+    title: config.title,
+    subtitle: config.subtitle,
+    ambientMotion: config.ambientMotion,
+    heroCredit: config.heroCredit,
+    heroLicense: config.heroLicense,
+  };
+}
+
+/**
+ * Expand a StartBlockConfig into a renderable Block.
+ * This is used by the player to render the cover block at rest.
+ */
+export function expandCoverBlock(config: StartBlockConfig, context: TemplateContext): Layer[] {
+  const input = startBlockToCoverInput(config);
+  return coverBlock(input, context);
+}