@bendyline/squisq 0.1.1

package/src/doc/templates/photoGrid.ts

@@ -0,0 +1,199 @@
+/**
+ * Photo Grid Template
+ *
+ * Displays 2-4 images in a tiled layout for visual variety.
+ * Layout adapts based on image count and viewport orientation:
+ *
+ * Landscape:
+ * - 2 images: side-by-side 50/50
+ * - 3 images: one large left (60%) + two stacked right
+ * - 4 images: 2x2 grid
+ *
+ * Portrait (9:16): images stack horizontally (top/bottom) instead of
+ * side-by-side, giving each image full width on narrow screens.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+import type { Layer } from '../../schemas/Doc.js';
+import type { PhotoGridInput, TemplateContext } from '../../schemas/BlockTemplates.js';
+import { scaledFontSize } from '../../schemas/BlockTemplates.js';
+import { cleanCaption } from './captionUtils.js';
+
+/** Gap between images as percentage */
+const GAP = 0.5;
+
+export function photoGrid(input: PhotoGridInput, context: TemplateContext): Layer[] {
+  const { images, caption: rawCaption, ambientMotion } = input;
+
+  // Guard: images array is required
+  if (!images || images.length === 0) return [];
+
+  const caption = rawCaption ? cleanCaption(rawCaption) : rawCaption;
+  const { theme, layout } = context;
+
+  const layers: Layer[] = [
+    // Black background (visible in gaps between images)
+    {
+      type: 'shape',
+      id: 'bg',
+      content: { shape: 'rect', fill: '#000000' },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    },
+  ];
+
+  // Reserve bottom space for caption — more room in landscape for larger text
+  const captionHeight = caption ? (layout.stackColumns ? 18 : 22) : 0;
+  const gridHeight = 100 - captionHeight;
+
+  // Generate image positions based on count; stack vertically in portrait
+  const positions = getGridPositions(images.length, gridHeight, layout.stackColumns);
+
+  const altFontSize = scaledFontSize(24, context, false);
+
+  for (let i = 0; i < Math.min(images.length, 4); i++) {
+    const img = images[i];
+    const pos = positions[i];
+
+    // Placeholder behind image (visible if image fails to load)
+    layers.push({
+      type: 'shape',
+      id: `grid-placeholder-${i}`,
+      content: { shape: 'rect', fill: theme.colors.background },
+      position: { x: `${pos.x}%`, y: `${pos.y}%`, width: `${pos.w}%`, height: `${pos.h}%` },
+    });
+
+    // Alt-text label on placeholder
+    if (img.alt) {
+      layers.push({
+        type: 'text',
+        id: `grid-alt-${i}`,
+        content: {
+          text: img.alt,
+          style: {
+            fontSize: altFontSize,
+            color: theme.colors.textMuted,
+            textAlign: 'center' as const,
+          },
+        },
+        position: { x: `${pos.x + pos.w / 2}%`, y: `${pos.y + pos.h / 2}%`, anchor: 'center' },
+      });
+    }
+
+    // Image layer (covers placeholder when loaded)
+    layers.push({
+      type: 'image',
+      id: `grid-img-${i}`,
+      content: {
+        src: img.src,
+        alt: img.alt,
+        fit: 'cover',
+        credit: img.credit,
+        license: img.license,
+      },
+      position: {
+        x: `${pos.x}%`,
+        y: `${pos.y}%`,
+        width: `${pos.w}%`,
+        height: `${pos.h}%`,
+      },
+      // Apply ambient motion to the first (largest) image only
+      animation:
+        i === 0 && ambientMotion
+          ? { type: ambientMotion, duration: 15 }
+          : { type: 'fadeIn', duration: 1, delay: 0.2 * i },
+    });
+  }
+
+  // Caption with gradient overlay
+  if (caption) {
+    const captionFontSize = scaledFontSize(layout.stackColumns ? 28 : 40, context, false);
+
+    layers.push({
+      type: 'shape',
+      id: 'caption-bg',
+      content: {
+        shape: 'rect',
+        fill: 'linear-gradient(transparent, rgba(0,0,0,0.8))',
+      },
+      position: { x: 0, y: `${gridHeight - 4}%`, width: '100%', height: `${captionHeight + 4}%` },
+    });
+
+    layers.push({
+      type: 'text',
+      id: 'caption',
+      content: {
+        text: caption,
+        style: {
+          fontSize: captionFontSize,
+          color: theme.colors.text,
+          textAlign: 'center',
+          shadow: true,
+        },
+      },
+      position: {
+        x: '50%',
+        y: `${gridHeight + (layout.stackColumns ? captionHeight / 2 : captionHeight * 0.3)}%`,
+        anchor: 'center',
+        width: '90%',
+      },
+      animation: { type: 'fadeIn', duration: 1, delay: 0.5 },
+    });
+  }
+
+  return layers;
+}
+
+interface GridPos {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+function getGridPositions(count: number, gridHeight: number, stacked: boolean): GridPos[] {
+  const halfW = 50 - GAP / 2;
+  const halfH = gridHeight / 2 - GAP / 2;
+
+  switch (count) {
+    case 2:
+      if (stacked) {
+        // Portrait: stack top/bottom
+        return [
+          { x: 0, y: 0, w: 100, h: halfH },
+          { x: 0, y: gridHeight / 2 + GAP / 2, w: 100, h: halfH },
+        ];
+      }
+      return [
+        { x: 0, y: 0, w: halfW, h: gridHeight },
+        { x: 50 + GAP / 2, y: 0, w: halfW, h: gridHeight },
+      ];
+    case 3: {
+      if (stacked) {
+        // Portrait: stack all three vertically
+        const thirdH = gridHeight / 3 - (GAP * 2) / 3;
+        return [
+          { x: 0, y: 0, w: 100, h: thirdH },
+          { x: 0, y: gridHeight / 3 + GAP / 3, w: 100, h: thirdH },
+          { x: 0, y: (gridHeight * 2) / 3 + (GAP * 2) / 3, w: 100, h: thirdH },
+        ];
+      }
+      const leftW = 60 - GAP / 2;
+      const rightW = 40 - GAP / 2;
+      return [
+        { x: 0, y: 0, w: leftW, h: gridHeight },
+        { x: 60 + GAP / 2, y: 0, w: rightW, h: halfH },
+        { x: 60 + GAP / 2, y: gridHeight / 2 + GAP / 2, w: rightW, h: halfH },
+      ];
+    }
+    case 4:
+    default:
+      // 2x2 grid works well in both orientations
+      return [
+        { x: 0, y: 0, w: halfW, h: halfH },
+        { x: 50 + GAP / 2, y: 0, w: halfW, h: halfH },
+        { x: 0, y: gridHeight / 2 + GAP / 2, w: halfW, h: halfH },
+        { x: 50 + GAP / 2, y: gridHeight / 2 + GAP / 2, w: halfW, h: halfH },
+      ];
+  }
+}

package/src/doc/templates/pullQuote.ts

@@ -0,0 +1,119 @@
+/**
+ * Pull Quote Template
+ *
+ * Quote text over a full-bleed background image with dark overlay.
+ * Cinematic alternative to quoteBlock when a high-quality image is available.
+ * Combines the visual impact of imageWithCaption with the text focus of quoteBlock.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+import type { Layer } from '../../schemas/Doc.js';
+import type { PullQuoteInput, TemplateContext } from '../../schemas/BlockTemplates.js';
+import { scaledFontSize } from '../../schemas/BlockTemplates.js';
+
+export function pullQuote(input: PullQuoteInput, context: TemplateContext): Layer[] {
+  const { text, attribution, backgroundImage, ambientMotion } = input;
+
+  // Guard: backgroundImage is required
+  if (!backgroundImage?.src) return [];
+
+  const quoteFontSize = scaledFontSize(52, context, true);
+  const attrFontSize = scaledFontSize(24, context, false);
+  const decoFontSize = scaledFontSize(200, context, true);
+
+  const layers: Layer[] = [
+    // Full-bleed background image
+    {
+      type: 'image',
+      id: 'bg-image',
+      content: {
+        src: backgroundImage.src,
+        alt: backgroundImage.alt,
+        fit: 'cover',
+        credit: backgroundImage.credit,
+        license: backgroundImage.license,
+      },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+      animation: ambientMotion ? { type: ambientMotion, duration: 15 } : undefined,
+    },
+
+    // Dark overlay for text readability
+    {
+      type: 'shape',
+      id: 'overlay',
+      content: {
+        shape: 'rect',
+        fill: 'rgba(0, 0, 0, 0.55)',
+      },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    },
+
+    // Decorative quotation mark
+    {
+      type: 'text',
+      id: 'deco-quote',
+      content: {
+        text: '\u201C',
+        style: {
+          fontSize: decoFontSize,
+          color: 'rgba(255, 255, 255, 0.08)',
+          textAlign: 'center',
+        },
+      },
+      position: {
+        x: '50%',
+        y: '20%',
+        anchor: 'center',
+      },
+    },
+
+    // Quote text
+    {
+      type: 'text',
+      id: 'quote-text',
+      content: {
+        text,
+        style: {
+          fontSize: quoteFontSize,
+          color: '#ffffff',
+          textAlign: 'center',
+          lineHeight: 1.5,
+          shadow: true,
+        },
+      },
+      position: {
+        x: '50%',
+        y: attribution ? '45%' : '50%',
+        anchor: 'center',
+        width: '80%',
+      },
+      animation: { type: 'fadeIn', duration: 2 },
+    },
+  ];
+
+  // Attribution
+  if (attribution) {
+    layers.push({
+      type: 'text',
+      id: 'attribution',
+      content: {
+        text: `\u2014 ${attribution}`,
+        style: {
+          fontSize: attrFontSize,
+          color: 'rgba(255, 255, 255, 0.7)',
+          textAlign: 'center',
+          shadow: true,
+        },
+      },
+      position: {
+        x: '50%',
+        y: '72%',
+        anchor: 'center',
+      },
+      animation: { type: 'fadeIn', duration: 1, delay: 1.5 },
+    });
+  }
+
+  return layers;
+}

package/src/doc/templates/quoteBlock.ts

@@ -0,0 +1,112 @@
+/**
+ * Quote Block Template
+ *
+ * Large centered quote with optional attribution.
+ * Good for impactful statements or descriptions.
+ * Adapts font sizes and positioning for different viewports.
+ *
+ * Supports optional accent images that appear as tasteful side/bottom strips.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+import type { Layer } from '../../schemas/Doc.js';
+import type { QuoteBlockInput, TemplateContext } from '../../schemas/BlockTemplates.js';
+import { scaledFontSize } from '../../schemas/BlockTemplates.js';
+import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
+import { createBackgroundLayer } from './captionUtils.js';
+
+export function quoteBlock(input: QuoteBlockInput, context: TemplateContext): Layer[] {
+  const { quote, attribution, accentImage } = input;
+  const { theme, layout } = context;
+
+  // Get layout adjustments if accent image is present
+  const accentLayout = accentImage ? getAccentLayout(accentImage.position) : DEFAULT_LAYOUT;
+
+  // Scale font sizes for viewport
+  const quoteFontSize = scaledFontSize(48, context, true);
+  const attrFontSize = scaledFontSize(24, context, false);
+
+  // Decorative quotation mark font size
+  const decorativeQuoteFontSize = scaledFontSize(280, context, true);
+
+  const layers: Layer[] = [
+    createBackgroundLayer(
+      'bg',
+      `linear-gradient(160deg, ${theme.colors.backgroundLight} 0%, #1e2636 100%)`,
+    ),
+  ];
+
+  // Add accent image layers (behind text, after background)
+  if (accentImage) {
+    layers.push(...createAccentLayers(accentImage, input.id));
+  }
+
+  // Decorative opening quotation mark — oversized, low-opacity behind quote
+  layers.push({
+    type: 'text',
+    id: 'deco-quote',
+    content: {
+      text: '\u201C',
+      style: {
+        fontSize: decorativeQuoteFontSize,
+        color: 'rgba(255, 255, 255, 0.06)',
+        textAlign: 'center',
+      },
+    },
+    position: {
+      x: accentLayout.textCenterX,
+      y: adjustY('18%', accentLayout),
+      anchor: 'center',
+    },
+  });
+
+  // Quote text - positioned based on accent layout
+  const quoteY = attribution ? layout.primaryY : '50%';
+  layers.push({
+    type: 'text',
+    id: 'quote',
+    content: {
+      text: quote,
+      style: {
+        fontSize: quoteFontSize,
+        color: theme.colors.text,
+        textAlign: 'center',
+        lineHeight: 1.6,
+        shadow: true,
+      },
+    },
+    position: {
+      x: accentLayout.textCenterX,
+      y: adjustY(quoteY, accentLayout),
+      anchor: 'center',
+      width: accentLayout.textWidth,
+    },
+    animation: { type: 'fadeIn', duration: 2 },
+  });
+
+  // Add attribution if provided
+  if (attribution) {
+    layers.push({
+      type: 'text',
+      id: 'attribution',
+      content: {
+        text: `— ${attribution}`,
+        style: {
+          fontSize: attrFontSize,
+          color: theme.colors.textMuted,
+          textAlign: 'center',
+          shadow: !!accentImage,
+        },
+      },
+      position: {
+        x: accentLayout.textCenterX,
+        y: adjustY(layout.captionY, accentLayout),
+        anchor: 'center',
+      },
+      animation: { type: 'fadeIn', duration: 1, delay: 1.5 },
+    });
+  }
+
+  return layers;
+}

package/src/doc/templates/sectionHeader.ts

@@ -0,0 +1,105 @@
+/**
+ * Section Header Template
+ *
+ * Section title card with optional background image.
+ * Used to introduce new sections of a story.
+ * When an image is provided, displays like a title slide with the image as background.
+ * Without an image, falls back to a colored background.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+import type { Layer, AnimationType } from '../../schemas/Doc.js';
+import type { SectionHeaderInput, TemplateContext } from '../../schemas/BlockTemplates.js';
+import { scaledFontSize } from '../../schemas/BlockTemplates.js';
+import { resolveColorScheme } from '../utils/themeUtils.js';
+
+export function sectionHeader(input: SectionHeaderInput, context: TemplateContext): Layer[] {
+  const { title, colorScheme = 'blue', imageSrc, imageAlt, ambientMotion } = input;
+  const { layout } = context;
+  const colors = resolveColorScheme(context, colorScheme);
+
+  // Scale font sizes for viewport
+  const titleFontSize = scaledFontSize(72, context, true);
+
+  const layers: Layer[] = [];
+
+  // Background - either image or solid color
+  if (imageSrc) {
+    // Image background with Ken Burns effect
+    layers.push({
+      type: 'image',
+      id: 'bg-image',
+      content: {
+        src: imageSrc,
+        alt: imageAlt || title,
+        fit: 'cover',
+      },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+      animation: ambientMotion
+        ? { type: ambientMotion as AnimationType, duration: 8 }
+        : { type: 'slowZoom', duration: 8, direction: 'in' },
+    });
+
+    // Dark overlay for text readability
+    layers.push({
+      type: 'shape',
+      id: 'overlay',
+      content: {
+        shape: 'rect',
+        fill: 'rgba(0, 0, 0, 0.5)',
+      },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    });
+  } else {
+    // Solid color background
+    layers.push({
+      type: 'shape',
+      id: 'bg',
+      content: {
+        shape: 'rect',
+        fill: colors.bg,
+      },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    });
+
+    // Decorative lines above and below title
+    layers.push({
+      type: 'shape',
+      id: 'line-top',
+      content: { shape: 'rect', fill: `${colors.text}33` },
+      position: { x: '50%', y: '40%', width: '20%', height: '2px', anchor: 'center' },
+    });
+    layers.push({
+      type: 'shape',
+      id: 'line-bottom',
+      content: { shape: 'rect', fill: `${colors.text}33` },
+      position: { x: '50%', y: '60%', width: '20%', height: '2px', anchor: 'center' },
+    });
+  }
+
+  // Section title - white text with shadow for readability over images
+  layers.push({
+    type: 'text',
+    id: 'title',
+    content: {
+      text: title,
+      style: {
+        fontSize: titleFontSize,
+        fontWeight: 'bold',
+        color: imageSrc ? '#ffffff' : colors.text,
+        textAlign: 'center',
+        shadow: true,
+      },
+    },
+    position: {
+      x: '50%',
+      y: '50%',
+      anchor: 'center',
+      width: layout.maxTextWidth,
+    },
+    animation: { type: 'fadeIn', duration: 1.5 },
+  });
+
+  return layers;
+}

package/src/doc/templates/statHighlight.ts

@@ -0,0 +1,113 @@
+/**
+ * Stat Highlight Template
+ *
+ * Large statistic/number with description and optional detail.
+ * Great for emphasizing key data points.
+ * Adapts font sizes and positioning for different viewports.
+ *
+ * Supports optional accent images that appear as tasteful side/bottom strips.
+ *
+ * This is shared code used by both site and efb-app doc renderers.
+ */
+
+import type { Layer } from '../../schemas/Doc.js';
+import type { StatHighlightInput, TemplateContext } from '../../schemas/BlockTemplates.js';
+import { scaledFontSize } from '../../schemas/BlockTemplates.js';
+import { resolveColorScheme } from '../utils/themeUtils.js';
+import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
+import { createBackgroundLayer } from './captionUtils.js';
+
+export function statHighlight(input: StatHighlightInput, context: TemplateContext): Layer[] {
+  const { stat, description, detail, colorScheme = 'blue', accentImage } = input;
+  const { theme } = context;
+  const colors = resolveColorScheme(context, colorScheme);
+
+  // Get layout adjustments if accent image is present
+  const accentLayout = accentImage ? getAccentLayout(accentImage.position) : DEFAULT_LAYOUT;
+
+  // Scale font sizes — stat is dramatically large, description is understated
+  const statFontSize = scaledFontSize(148, context, true);
+  const descFontSize = scaledFontSize(32, context, false);
+  const detailFontSize = scaledFontSize(26, context, false);
+
+  const layers: Layer[] = [
+    createBackgroundLayer(
+      'bg',
+      `linear-gradient(180deg, ${theme.colors.background} 0%, #0f1520 100%)`,
+    ),
+  ];
+
+  // Add accent image layers (behind text, after background)
+  if (accentImage) {
+    layers.push(...createAccentLayers(accentImage, input.id));
+  }
+
+  // Big stat — hero element, dominates the slide
+  layers.push({
+    type: 'text',
+    id: 'stat',
+    content: {
+      text: stat,
+      style: {
+        fontSize: statFontSize,
+        fontWeight: 'bold',
+        color: colors.text,
+        shadow: !!accentImage,
+      },
+    },
+    position: {
+      x: accentLayout.textCenterX,
+      y: adjustY('32%', accentLayout),
+      anchor: 'center',
+    },
+    animation: { type: 'zoomIn', duration: 0.6 },
+  });
+
+  // Description — smaller and understated beneath the stat
+  layers.push({
+    type: 'text',
+    id: 'description',
+    content: {
+      text: description,
+      style: {
+        fontSize: descFontSize,
+        color: theme.colors.textMuted,
+        textAlign: 'center',
+        lineHeight: 1.6,
+        shadow: !!accentImage,
+      },
+    },
+    position: {
+      x: accentLayout.textCenterX,
+      y: adjustY('58%', accentLayout),
+      width: accentLayout.textWidth,
+      anchor: 'center',
+    },
+    animation: { type: 'fadeIn', duration: 1, delay: 0.3 },
+  });
+
+  // Add detail if provided
+  if (detail) {
+    layers.push({
+      type: 'text',
+      id: 'detail',
+      content: {
+        text: detail,
+        style: {
+          fontSize: detailFontSize,
+          color: colors.accent,
+          textAlign: 'center',
+          shadow: !!accentImage,
+        },
+      },
+      position: {
+        x: accentLayout.textCenterX,
+        y: adjustY('75%', accentLayout),
+        anchor: 'center',
+      },
+      animation: { type: 'fadeIn', duration: 1, delay: 1 },
+    });
+  }
+
+  return layers;
+}