@bendyline/squisq 1.4.1 → 1.5.1

package/src/doc/standaloneAnnotation.ts

@@ -0,0 +1,58 @@
+/**
+ * Standalone-paragraph annotation parser.
+ *
+ * A paragraph whose entire trimmed text is exactly a `{[…]}` annotation
+ * (nothing before or after) is a *standalone annotation*. Two features share
+ * this shape:
+ *
+ * - **Media annotations** (`{[audio …]}` / `{[video …]}`) — lifted into typed
+ *   {@link import('../schemas/Media.js').MediaClip}s by `mediaAnnotations.ts`.
+ * - **Standalone template blocks** (`{[quote]}`, `{[statHighlight …]}`, …) —
+ *   turned into heading-less {@link import('../schemas/Doc.js').Block}s by
+ *   `annotationBlocks.ts`.
+ *
+ * Both call the single parser here so the annotation grammar (quoting,
+ * escaping, first-token-is-template) stays identical to the heading form.
+ */
+
+import {
+  matchTrailingTemplateAnnotation,
+  tokenizeAttrTokens,
+  splitKeyValueToken,
+} from '../markdown/attrTokens.js';
+import type { MarkdownBlockNode } from '../markdown/types.js';
+
+/** The template name + params parsed out of a standalone `{[…]}` paragraph. */
+export interface ParsedAnnotation {
+  /** First bare token, when the annotation leads with one (e.g. `quote`). */
+  template?: string;
+  /** Remaining `key=value` tokens, unquoted/unescaped. */
+  params: Record<string, string>;
+}
+
+/**
+ * Parse a paragraph node that is *exactly* a `{[…]}` annotation (nothing
+ * before or after). Returns the template + params, or null when the node
+ * isn't a standalone annotation (not a paragraph, more than one child, a
+ * non-text child such as a resolved inline icon, or trailing text).
+ */
+export function parseStandaloneAnnotation(node: MarkdownBlockNode): ParsedAnnotation | null {
+  if (node.type !== 'paragraph') return null;
+  const children = node.children ?? [];
+  if (children.length !== 1 || children[0].type !== 'text') return null;
+  const text = children[0].value.trim();
+  const match = matchTrailingTemplateAnnotation(text);
+  // index 0 means the whole (trimmed) paragraph is the annotation.
+  if (!match || match.index !== 0) return null;
+
+  const tokens = tokenizeAttrTokens(match.inner.trim());
+  const firstIsParam = tokens.length > 0 && tokens[0].indexOf('=') > 0;
+  const template = firstIsParam || tokens.length === 0 ? undefined : tokens[0];
+  const startIdx = firstIsParam ? 0 : 1;
+  const params: Record<string, string> = {};
+  for (let i = startIdx; i < tokens.length; i++) {
+    const kv = splitKeyValueToken(tokens[i]);
+    if (kv) params[kv.key] = kv.value;
+  }
+  return { template, params };
+}

package/src/doc/structuredData.ts

@@ -0,0 +1,301 @@
+/**
+ * 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]`, `key:`
+ * followed by an indented `- item` block sequence (scalars or inline
+ * arrays), and `key:` followed by *one level* of indented `subkey: scalar`
+ * lines (a nested map, e.g. `center:` + indented `lat:` / `lng:`). Deeper
+ * nesting, and mixing list items with mapping keys under one key, are
+ * rejected with a clear error — use a `json data` fence for those.
+ */
+
+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: unknown) {
+      return { error: `invalid JSON: ${err instanceof Error ? err.message : String(err)}` };
+    }
+  }
+  try {
+    return { data: parseYamlSubset(node.value) };
+  } catch (err: unknown) {
+    return { error: `invalid YAML: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+/**
+ * Return a new contents array with the first data fence's code content
+ * replaced by `data` (pretty-printed JSON). The fence node keeps its
+ * language and `data` marker; only `value` changes. When no data fence
+ * exists, a new ` ```json data ` fence is appended instead.
+ *
+ * Pure: neither `contents` nor its nodes are mutated. This is the write
+ * half of the data-fence channel — editors update `block.templateData`
+ * and call this to reflect the change back into `block.contents`.
+ */
+export function replaceDataFence(
+  contents: MarkdownBlockNode[],
+  data: Record<string, unknown>,
+): MarkdownBlockNode[] {
+  const value = JSON.stringify(data, null, 2);
+  const index = contents.findIndex((node) => node.type === 'code' && isDataFence(node));
+  if (index < 0) {
+    const fence: MarkdownCodeBlock = { type: 'code', lang: 'json', meta: 'data', value };
+    return [...contents, fence];
+  }
+  const next = [...contents];
+  next[index] = { ...(contents[index] as MarkdownCodeBlock), value };
+  return next;
+}
+
+// ============================================
+// 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');
+
+  // Open block under the most recent `key:` line: whether its children are a
+  // block sequence (`- …`) or a nested map (`subkey: …`) is decided by the
+  // first indented child; `childIndent` pins the one allowed child depth.
+  let pendingKey: string | null = null;
+  let pendingKind: 'list' | 'map' | null = null;
+  let childIndent = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const indent = line.length - line.trimStart().length;
+
+    if (indent > 0) {
+      if (!pendingKey) {
+        throw new Error(`line ${i + 1}: unexpected indented line without a preceding "key:" line`);
+      }
+      if (childIndent < 0) childIndent = indent;
+      if (indent > childIndent) {
+        throw new Error(
+          `line ${i + 1}: nesting deeper than one level is not supported — use a \`\`\`json data fence for nested input`,
+        );
+      }
+
+      if (trimmed.startsWith('- ')) {
+        if (pendingKind === 'map') {
+          throw new Error(
+            `line ${i + 1}: cannot mix list items and mapping keys under "${pendingKey}"`,
+          );
+        }
+        pendingKind = 'list';
+        (result[pendingKey] as unknown[]).push(parseInlineValue(trimmed.slice(2)));
+        continue;
+      }
+
+      // Otherwise this is a nested `subkey: value` mapping line.
+      if (pendingKind === 'list') {
+        throw new Error(
+          `line ${i + 1}: cannot mix mapping keys and list items under "${pendingKey}"`,
+        );
+      }
+      const subColon = trimmed.indexOf(':');
+      if (subColon < 1) {
+        throw new Error(`line ${i + 1}: expected "key: value"`);
+      }
+      const subValue = trimmed.slice(subColon + 1).trim();
+      if (subValue === '') {
+        // A nested `subkey:` opening its own block would be a second level.
+        throw new Error(
+          `line ${i + 1}: nesting deeper than one level is not supported — use a \`\`\`json data fence for nested input`,
+        );
+      }
+      if (pendingKind !== 'map') {
+        pendingKind = 'map';
+        result[pendingKey] = {};
+      }
+      (result[pendingKey] as Record<string, unknown>)[trimmed.slice(0, subColon).trim()] =
+        parseInlineValue(subValue);
+      continue;
+    }
+
+    pendingKey = null;
+    pendingKind = null;
+    childIndent = -1;
+    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: an indented `- …` sequence or a `subkey: …`
+      // map. Default to an empty list so a `key:` with no children stays
+      // back-compatible (`{ key: [] }`); the map branch replaces it wholesale.
+      result[key] = [];
+      pendingKey = 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;
+  }
+}