@bendyline/squisq 1.4.0 → 1.5.0

package/src/doc/structuredData.ts

@@ -0,0 +1,230 @@
+/**
+ * Structured template data from markdown body content.
+ *
+ * Attribute strings on a heading annotation are fine for scalar params,
+ * but tabular or nested inputs (dataTable rows, map markers, chart data)
+ * don't pack well into a single quoted line. This module supplies the two
+ * structured channels instead:
+ *
+ * 1. **Data fences** — a fenced code block whose info string is
+ *    `json data` or `yaml data`, placed in a heading's body content:
+ *
+ *    ````markdown
+ *    ## Quarterly numbers {[dataTable]}
+ *
+ *    ```json data
+ *    { "headers": ["Q", "Revenue"], "rows": [["Q1", "1.2M"], ["Q2", "1.4M"]] }
+ *    ```
+ *    ````
+ *
+ *    The parsed object lands on `block.templateData` and merges into the
+ *    template input (after defaults, before `{[…]}` string overrides).
+ *    The `data` marker keeps ordinary ```json code samples — which should
+ *    render as code — out of the template input.
+ *
+ * 2. **GFM tables** — for the `dataTable` template, the first table in the
+ *    section body supplies `headers` / `rows` / `align` when the author
+ *    didn't provide them explicitly.
+ *
+ * YAML support is a documented subset (this package has no YAML
+ * dependency): top-level `key: scalar`, `key: [inline, array]`, and
+ * `key:` followed by an indented `- item` block sequence whose items are
+ * scalars or inline arrays. Nested maps are rejected with a clear error —
+ * use a `json data` fence for deeply nested input.
+ */
+
+import type {
+  MarkdownBlockNode,
+  MarkdownCodeBlock,
+  MarkdownTable,
+  MarkdownTableRow,
+} from '../markdown/types.js';
+import { extractPlainText } from '../markdown/utils.js';
+
+// ============================================
+// Data fences
+// ============================================
+
+/** Languages accepted for data fences. */
+const DATA_FENCE_LANGS = new Set(['json', 'yaml', 'yml']);
+
+/**
+ * Whether a code block is a structured-data fence: lang `json`/`yaml`/`yml`
+ * with the word `data` in the fence meta (` ```json data `).
+ */
+export function isDataFence(node: MarkdownCodeBlock): boolean {
+  if (!node.lang || !DATA_FENCE_LANGS.has(node.lang.toLowerCase())) return false;
+  const meta = node.meta ?? '';
+  return /\bdata\b/.test(meta);
+}
+
+export interface DataFenceParseResult {
+  /** Parsed key→value map. Undefined when parsing failed. */
+  data?: Record<string, unknown>;
+  /** Parse failure description. Undefined when parsing succeeded. */
+  error?: string;
+}
+
+/**
+ * Parse a data fence's content into a key→value map. JSON fences must
+ * contain a top-level object (arrays have no key to merge under); YAML
+ * fences are parsed with {@link parseYamlSubset}.
+ */
+export function parseDataFence(node: MarkdownCodeBlock): DataFenceParseResult {
+  const lang = node.lang?.toLowerCase();
+  if (lang === 'json') {
+    try {
+      const parsed: unknown = JSON.parse(node.value);
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { error: 'JSON data fence must contain a top-level object ({"key": …})' };
+      }
+      return { data: parsed as Record<string, unknown> };
+    } catch (err) {
+      return { error: `invalid JSON: ${err instanceof Error ? err.message : String(err)}` };
+    }
+  }
+  try {
+    return { data: parseYamlSubset(node.value) };
+  } catch (err) {
+    return { error: `invalid YAML: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+// ============================================
+// YAML subset parser
+// ============================================
+
+/** Parse a scalar token: quoted string, boolean, null, number, or string. */
+function parseScalar(raw: string): unknown {
+  const trimmed = raw.trim();
+  if (trimmed.length >= 2) {
+    const q = trimmed[0];
+    if ((q === '"' || q === "'") && trimmed.endsWith(q)) {
+      return trimmed.slice(1, -1);
+    }
+  }
+  if (trimmed === 'true') return true;
+  if (trimmed === 'false') return false;
+  if (trimmed === 'null' || trimmed === '~') return null;
+  if (trimmed !== '' && !isNaN(Number(trimmed))) return Number(trimmed);
+  return trimmed;
+}
+
+/**
+ * Split an inline-array interior on top-level commas, respecting quotes.
+ */
+function splitInlineArray(interior: string): string[] {
+  const items: string[] = [];
+  let current = '';
+  let quote: string | null = null;
+  for (const ch of interior) {
+    if (quote) {
+      current += ch;
+      if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+      current += ch;
+    } else if (ch === ',') {
+      items.push(current);
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  items.push(current);
+  // A trailing comma (or empty interior) leaves an empty final item — drop it.
+  return items.map((s) => s.trim()).filter((s) => s !== '');
+}
+
+/** Parse a value that may be an inline array `[a, b]` or a scalar. */
+function parseInlineValue(raw: string): unknown {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+    return splitInlineArray(trimmed.slice(1, -1)).map(parseScalar);
+  }
+  return parseScalar(trimmed);
+}
+
+/**
+ * Parse the supported YAML subset (see module doc) into a key→value map.
+ * Throws an Error with a line-anchored message on anything outside the
+ * subset, so callers can surface a precise diagnostic.
+ */
+export function parseYamlSubset(src: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const lines = src.split('\n');
+  let pendingListKey: string | null = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const indented = /^\s/.test(line);
+
+    if (indented && trimmed.startsWith('- ')) {
+      if (!pendingListKey) {
+        throw new Error(`line ${i + 1}: list item without a preceding "key:" line`);
+      }
+      (result[pendingListKey] as unknown[]).push(parseInlineValue(trimmed.slice(2)));
+      continue;
+    }
+
+    if (indented) {
+      throw new Error(
+        `line ${i + 1}: nested mappings are not supported — use a \`\`\`json data fence for nested input`,
+      );
+    }
+
+    pendingListKey = null;
+    const colonIdx = trimmed.indexOf(':');
+    if (colonIdx < 1) {
+      throw new Error(`line ${i + 1}: expected "key: value"`);
+    }
+    const key = trimmed.slice(0, colonIdx).trim();
+    const rawValue = trimmed.slice(colonIdx + 1).trim();
+
+    if (rawValue === '') {
+      // `key:` opens a block sequence; items follow as indented `- …` lines.
+      result[key] = [];
+      pendingListKey = key;
+    } else {
+      result[key] = parseInlineValue(rawValue);
+    }
+  }
+
+  return result;
+}
+
+// ============================================
+// GFM table extraction
+// ============================================
+
+export interface ExtractedTableData {
+  headers: string[];
+  rows: string[][];
+  align?: (('left' | 'right' | 'center') | null)[];
+}
+
+/** Find the first GFM table among a block's body contents. */
+export function findFirstTable(
+  contents: MarkdownBlockNode[] | undefined,
+): MarkdownTable | undefined {
+  return contents?.find((n): n is MarkdownTable => n.type === 'table');
+}
+
+/**
+ * Extract `headers` / `rows` / `align` (the `dataTable` input shape) from a
+ * GFM table node. The first row is the header row.
+ */
+export function extractTableData(table: MarkdownTable): ExtractedTableData {
+  const toCells = (row: MarkdownTableRow): string[] =>
+    row.children.map((cell) => extractPlainText(cell).trim());
+
+  const [headerRow, ...bodyRows] = table.children;
+  return {
+    headers: headerRow ? toCells(headerRow) : [],
+    rows: bodyRows.map(toCells),
+    ...(table.align && table.align.some((a) => a != null) ? { align: table.align } : {}),
+  };
+}

package/src/doc/templateInputs.ts

@@ -0,0 +1,240 @@
+/**
+ * Template input derivation — build a template's required inputs from a
+ * block's heading + markdown body.
+ *
+ * Used by:
+ * - `markdownToDoc`'s content-aware auto template picking, so an
+ *   auto-picked `quote`/`statHighlight`/`leftFeature` block carries the
+ *   inputs its template needs through every render path (player, linear
+ *   view, exports).
+ * - `LinearDocView` / editor previews, to render annotated blocks whose
+ *   authors didn't spell out every template param.
+ *
+ * Two modes:
+ * - strict (default): returns `null` when an essential input can't be
+ *   derived (no image for a feature block, no table for dataTable…) —
+ *   auto-picking uses this to fall back to the structural default.
+ * - placeholders: returns visible placeholder values instead of failing —
+ *   preview surfaces use this so a half-authored block still renders.
+ */
+
+import type { MarkdownBlockNode, MarkdownList, MarkdownTable } from '../markdown/types.js';
+import { extractPlainText } from '../markdown/utils.js';
+
+/** First image discovered in a block's body, with explicit dimensions when present. */
+export interface FirstImage {
+  src: string;
+  alt: string;
+  width?: number;
+  height?: number;
+}
+
+/** Plain text of a block's body contents (excluding the heading). */
+export function extractBodyPlainText(contents?: MarkdownBlockNode[]): string {
+  if (!contents || contents.length === 0) return '';
+  return contents
+    .map((n) => extractPlainText(n))
+    .join('\n')
+    .trim();
+}
+
+/** Extract list items as plain text. */
+export function extractListItems(contents?: MarkdownBlockNode[]): string[] {
+  if (!contents) return [];
+  const items: string[] = [];
+  for (const node of contents) {
+    if (node.type === 'list') {
+      for (const item of (node as MarkdownList).children) {
+        const text = extractPlainText(item).trim();
+        if (text) items.push(text);
+      }
+    }
+  }
+  return items;
+}
+
+/** Parse a `width`/`height` HTML attribute to a positive number. */
+function parseDim(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  const n = parseFloat(raw);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+/**
+ * Find images referenced anywhere in block contents — both markdown
+ * shorthand `![alt](url)` (type `image`) and raw HTML `<img>` tags
+ * (type `htmlBlock`/`htmlInline`). The WYSIWYG editor emits the HTML form
+ * whenever a user resizes an image, so missing that path silently breaks
+ * every resized image.
+ *
+ * @param limit Stop after this many images (default: all).
+ */
+export function extractImages(
+  contents: MarkdownBlockNode[] | undefined,
+  limit = Infinity,
+): FirstImage[] {
+  if (!contents || contents.length === 0) return [];
+  const found: FirstImage[] = [];
+
+  function fromHtml(nodes: unknown[]): void {
+    for (const node of nodes) {
+      if (found.length >= limit) return;
+      if (!node || typeof node !== 'object') continue;
+      const n = node as Record<string, unknown>;
+      if (n.type === 'htmlElement' && n.tagName === 'img') {
+        const attrs = n.attributes as Record<string, string> | undefined;
+        if (attrs && typeof attrs.src === 'string' && attrs.src) {
+          found.push({
+            src: attrs.src,
+            alt: typeof attrs.alt === 'string' ? attrs.alt : '',
+            width: parseDim(attrs.width),
+            height: parseDim(attrs.height),
+          });
+        }
+      }
+      if (Array.isArray(n.children)) fromHtml(n.children);
+    }
+  }
+
+  function walk(node: unknown): void {
+    if (found.length >= limit) return;
+    if (!node || typeof node !== 'object') return;
+    const n = node as Record<string, unknown>;
+    if (n.type === 'image' && typeof n.url === 'string' && n.url) {
+      found.push({ src: n.url, alt: typeof n.alt === 'string' ? n.alt : '' });
+      return;
+    }
+    if ((n.type === 'htmlBlock' || n.type === 'htmlInline') && Array.isArray(n.htmlChildren)) {
+      fromHtml(n.htmlChildren);
+    }
+    if (Array.isArray(n.children)) {
+      for (const child of n.children) walk(child);
+    }
+  }
+
+  for (const node of contents) {
+    if (found.length >= limit) break;
+    walk(node);
+  }
+  return found;
+}
+
+/** First image in a block's body, or null. */
+export function extractFirstImage(contents: MarkdownBlockNode[] | undefined): FirstImage | null {
+  return extractImages(contents, 1)[0] ?? null;
+}
+
+/** Extract table data (headers, rows, alignment) from block contents. */
+export function extractTableFromContents(contents?: MarkdownBlockNode[]): {
+  headers: string[];
+  rows: string[][];
+  align?: (('left' | 'right' | 'center') | null)[];
+} | null {
+  if (!contents) return null;
+  for (const node of contents) {
+    if (node.type === 'table') {
+      const table = node as MarkdownTable;
+      const [headerRow, ...bodyRows] = table.children;
+      if (!headerRow) return null;
+      const headers = headerRow.children.map((cell) => extractPlainText(cell).trim());
+      const rows = bodyRows.map((row) => row.children.map((cell) => extractPlainText(cell).trim()));
+      return { headers, rows, align: table.align };
+    }
+  }
+  return null;
+}
+
+/** First blockquote's plain text, or ''. */
+export function extractBlockquoteText(contents?: MarkdownBlockNode[]): string {
+  if (!contents) return '';
+  for (const node of contents) {
+    if (node.type === 'blockquote') return extractPlainText(node).trim();
+  }
+  return '';
+}
+
+export interface DeriveTemplateInputsOptions {
+  /**
+   * Return visible placeholder values instead of `null` when an essential
+   * input can't be derived (preview surfaces). Default false (strict).
+   */
+  placeholders?: boolean;
+}
+
+/**
+ * Derive a template's inputs from a block's heading text and body nodes.
+ * Returns the input fields to merge onto the block, or `null` in strict
+ * mode when an essential input is missing.
+ */
+export function deriveTemplateInputs(
+  templateName: string,
+  headingText: string,
+  contents: MarkdownBlockNode[] | undefined,
+  options: DeriveTemplateInputsOptions = {},
+): Record<string, unknown> | null {
+  const placeholders = options.placeholders === true;
+  const bodyText = extractBodyPlainText(contents);
+
+  switch (templateName) {
+    case 'statHighlight':
+      return { stat: headingText, description: bodyText || headingText };
+    case 'quote': {
+      const quote = extractBlockquoteText(contents) || bodyText || headingText;
+      return { quote };
+    }
+    case 'fullBleedQuote':
+    case 'pullQuote': {
+      // These templates take `text` (not `quote`).
+      const text = extractBlockquoteText(contents) || bodyText || headingText;
+      return { text };
+    }
+    case 'factCard':
+      return { fact: headingText, explanation: bodyText || headingText };
+    case 'comparisonBar':
+      return placeholders
+        ? { leftLabel: 'A', leftValue: 60, rightLabel: 'B', rightValue: 40 }
+        : null;
+    case 'list': {
+      const items = extractListItems(contents);
+      if (items.length > 0) return { items };
+      return placeholders ? { items: ['Item 1', 'Item 2', 'Item 3'] } : null;
+    }
+    case 'definitionCard':
+      return { term: headingText, definition: bodyText || headingText };
+    case 'dateEvent':
+      return { date: headingText, description: bodyText || headingText };
+    case 'dataTable': {
+      const tableData = extractTableFromContents(contents);
+      if (tableData) return tableData;
+      return placeholders ? { headers: ['Column'], rows: [['Data']] } : null;
+    }
+    case 'imageWithCaption': {
+      const img = extractFirstImage(contents);
+      if (!img) return placeholders ? { caption: headingText } : null;
+      return { imageSrc: img.src, imageAlt: img.alt || headingText, caption: headingText };
+    }
+    case 'photoGrid': {
+      const images = extractImages(contents, 4);
+      if (images.length < 2) return placeholders ? {} : null;
+      return {
+        images: images.map((i) => ({ src: i.src, alt: i.alt })),
+        caption: headingText,
+      };
+    }
+    case 'leftFeature':
+    case 'rightFeature': {
+      const img = extractFirstImage(contents);
+      if (!img && !placeholders) return null;
+      return {
+        imageSrc: img?.src ?? '',
+        imageAlt: img?.alt || headingText,
+        imageWidth: img?.width,
+        imageHeight: img?.height,
+        title: headingText,
+        body: bodyText,
+      };
+    }
+    default:
+      return placeholders ? {} : null;
+  }
+}

package/src/doc/templates/__tests__/customTemplate.test.ts

@@ -0,0 +1,151 @@
+/**
+ * makeCustomTemplateFn — verifies a CustomTemplateDefinition expands
+ * correctly via the standard template function signature and that
+ * `%`-based positions resolve correctly across viewport presets.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { makeCustomTemplateFn } from '../customTemplate';
+import type { CustomTemplateDefinition } from '../../../schemas/CustomTemplates.js';
+import type { Block, TextLayer } from '../../../schemas/Doc.js';
+import type { RawLayersInput, TemplateContext } from '../../../schemas/BlockTemplates.js';
+import { createTemplateContext } from '../../../schemas/BlockTemplates.js';
+import { DEFAULT_THEME } from '../../../schemas/themeLibrary.js';
+import { VIEWPORT_PRESETS, type ViewportConfig } from '../../../schemas/Viewport.js';
+
+function defn(layers: TextLayer[]): CustomTemplateDefinition {
+  return {
+    name: 'hero',
+    label: 'Hero',
+    viewport: { width: 1920, height: 1080 },
+    layers,
+  };
+}
+
+function makeContext(
+  block: Block,
+  viewport: ViewportConfig = VIEWPORT_PRESETS.landscape,
+): TemplateContext {
+  const ctx = createTemplateContext(DEFAULT_THEME, 0, 1, viewport);
+  ctx.block = block;
+  return ctx;
+}
+
+function makeBlock(overrides: Partial<Block> = {}): Block {
+  return {
+    id: 'b',
+    startTime: 0,
+    duration: 1,
+    audioSegment: 0,
+    title: 'Welcome',
+    template: 'hero',
+    ...overrides,
+  };
+}
+
+function makeInput(): RawLayersInput {
+  return {
+    id: 'b',
+    template: 'layout',
+    duration: 1,
+    audioSegment: 0,
+  };
+}
+
+describe('makeCustomTemplateFn', () => {
+  it('substitutes the block title into a layer carrying {title}', () => {
+    const fn = makeCustomTemplateFn(
+      defn([
+        {
+          id: 't',
+          type: 'text',
+          position: { x: '10%', y: '20%', width: '80%', height: '15%' },
+          content: { text: 'Hello, {title}!', style: { fontSize: 48, color: '#000' } },
+        },
+      ]),
+    );
+    const ctx = makeContext(makeBlock({ title: 'World' }));
+    const layers = fn(makeInput(), ctx);
+    expect(layers).toHaveLength(1);
+    expect((layers[0] as TextLayer).content.text).toBe('Hello, World!');
+  });
+
+  it('returns layers unchanged when context.block is missing', () => {
+    const fn = makeCustomTemplateFn(
+      defn([
+        {
+          id: 't',
+          type: 'text',
+          position: { x: '0%', y: '0%', width: '100%', height: '10%' },
+          content: { text: '{title}', style: { fontSize: 24, color: '#000' } },
+        },
+      ]),
+    );
+    const ctx = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+    const layers = fn(makeInput(), ctx);
+    expect((layers[0] as TextLayer).content.text).toBe('{title}');
+  });
+
+  it('preserves %-based positions verbatim — they resolve at SSR render time', () => {
+    const fn = makeCustomTemplateFn(
+      defn([
+        {
+          id: 't',
+          type: 'text',
+          position: { x: '10%', y: '20%', width: '80%' },
+          content: { text: 'static', style: { fontSize: 24, color: '#000' } },
+        },
+      ]),
+    );
+
+    // Landscape: 1920×1080
+    const landscapeLayers = fn(makeInput(), makeContext(makeBlock(), VIEWPORT_PRESETS.landscape));
+    expect(landscapeLayers[0].position.x).toBe('10%');
+
+    // Portrait: 1080×1920
+    const portraitLayers = fn(makeInput(), makeContext(makeBlock(), VIEWPORT_PRESETS.portrait));
+    expect(portraitLayers[0].position.x).toBe('10%');
+
+    // Square: 1080×1080
+    const squareLayers = fn(makeInput(), makeContext(makeBlock(), VIEWPORT_PRESETS.square));
+    expect(squareLayers[0].position.x).toBe('10%');
+
+    // The positions stay as `%`-strings — the SSR layer renderer (not
+    // this function) is responsible for resolving them into pixels
+    // against the target viewport. We verify the function doesn't
+    // perturb authoring intent.
+  });
+
+  it('round-trips multiple tokens in one definition', () => {
+    const fn = makeCustomTemplateFn(
+      defn([
+        {
+          id: 'title',
+          type: 'text',
+          position: { x: '5%', y: '5%', width: '90%', height: '20%' },
+          content: { text: '{title}', style: { fontSize: 72, color: '#000' } },
+        },
+        {
+          id: 'body',
+          type: 'text',
+          position: { x: '5%', y: '30%', width: '90%', height: '60%' },
+          content: { text: '{content}', style: { fontSize: 32, color: '#333' } },
+        },
+      ]),
+    );
+    const ctx = makeContext(
+      makeBlock({
+        title: 'Welcome',
+        contents: [
+          {
+            type: 'paragraph',
+            children: [{ type: 'text', value: 'A small editor for big ideas.' }],
+          },
+        ],
+      }),
+    );
+    const layers = fn(makeInput(), ctx);
+    expect((layers[0] as TextLayer).content.text).toBe('Welcome');
+    expect((layers[1] as TextLayer).content.text).toBe('A small editor for big ideas.');
+  });
+});