@bendyline/squisq 1.4.1 → 1.5.1

package/src/__tests__/shapeVocabulary.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect } from 'vitest';
+import { computeDrawingLayout } from '../doc/templates/drawingLayout.js';
+import { drawingBlock } from '../doc/templates/drawingBlock.js';
+import { diagramBlock } from '../doc/templates/diagramBlock.js';
+import { createTemplateContext } from '../schemas/BlockTemplates.js';
+import { DEFAULT_THEME } from '../schemas/themeLibrary.js';
+import { VIEWPORT_PRESETS } from '../schemas/Viewport.js';
+import type { Block, PathLayer } from '../schemas/Doc.js';
+import type { DiagramBlockInput } from '../schemas/BlockTemplates.js';
+
+function shape(id: string, template: string, overrides: Record<string, string> = {}): Block {
+  return {
+    id,
+    startTime: 0,
+    duration: 0,
+    audioSegment: 0,
+    template,
+    templateOverrides: overrides,
+  } as Block;
+}
+
+function ctx(children: Block[]) {
+  const c = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+  c.children = children;
+  return c;
+}
+
+describe('drawing shape vocabulary', () => {
+  it('recognizes new polygon kinds and aliases', () => {
+    const layout = computeDrawingLayout([
+      shape('s', 'star', { x: '0', y: '0' }),
+      shape('h', 'hexagon', { x: '0', y: '0' }),
+      shape('r', 'rhombus', { x: '0', y: '0' }), // alias → diamond
+      shape('a', 'rightarrow', { x: '0', y: '0' }), // alias → arrow-right
+    ]);
+    const kinds = layout.shapes.map((s) => s.kind);
+    expect(kinds).toEqual(['star', 'hexagon', 'diamond', 'arrow-right']);
+  });
+
+  it('renders a polygon kind as a PathLayer in the block', () => {
+    const layers = drawingBlock(
+      { template: 'drawing', id: 'd', duration: 0, audioSegment: 0 },
+      ctx([shape('s', 'star', { x: '10', y: '10', width: '100', height: '100' })]),
+    );
+    const star = layers.find((l) => l.id === 'shape-s');
+    expect(star?.type).toBe('path');
+  });
+});
+
+describe('drawing connector semantics', () => {
+  function conn(overrides: Record<string, string>) {
+    return computeDrawingLayout([
+      shape('a', 'rect', { x: '0', y: '0', width: '50', height: '50' }),
+      shape('b', 'rect', { x: '0', y: '200', width: '50', height: '50' }),
+      shape('c', 'arrow', { from: 'a', to: 'b', ...overrides }),
+    ]).connectors[0];
+  }
+
+  it('parses end/start markers, line style, and routing', () => {
+    expect(
+      conn({
+        endStyle: 'diamond',
+        startStyle: 'circle',
+        lineStyle: 'dashed',
+        routing: 'orthogonal',
+      }),
+    ).toMatchObject({
+      endMarker: 'diamond',
+      startMarker: 'circle',
+      dasharray: '8 6',
+      routing: 'orthogonal',
+    });
+  });
+
+  it('defaults arrow → end arrow, line → no marker, straight routing', () => {
+    expect(conn({})).toMatchObject({
+      endMarker: 'arrow',
+      startMarker: 'none',
+      routing: 'straight',
+    });
+    const line = computeDrawingLayout([
+      shape('a', 'rect', { x: '0', y: '0', width: '50', height: '50' }),
+      shape('b', 'rect', { x: '0', y: '200', width: '50', height: '50' }),
+      shape('l', 'line', { from: 'a', to: 'b' }),
+    ]).connectors[0];
+    expect(line.endMarker).toBe('none');
+  });
+
+  it('emits the marker + dash on the rendered connector PathLayer', () => {
+    const layers = drawingBlock(
+      { template: 'drawing', id: 'd', duration: 0, audioSegment: 0 },
+      ctx([
+        shape('a', 'rect', { x: '0', y: '0', width: '50', height: '50' }),
+        shape('b', 'rect', { x: '0', y: '200', width: '50', height: '50' }),
+        shape('c', 'arrow', { from: 'a', to: 'b', endStyle: 'diamond', lineStyle: 'dashed' }),
+      ]),
+    );
+    const connector = layers.find((l) => l.id === 'connector-c') as PathLayer | undefined;
+    expect(connector?.content.endMarker).toBe('diamond');
+    expect(connector?.content.dasharray).toBe('8 6');
+  });
+});
+
+describe('diagram edge styles', () => {
+  function node(id: string, x: number, y: number, connectsTo?: string): Block {
+    return {
+      id,
+      startTime: 0,
+      duration: 0,
+      audioSegment: 0,
+      x,
+      y,
+      ...(connectsTo ? { connectsTo: [{ target: connectsTo }] } : {}),
+    } as Block;
+  }
+
+  it('applies endStyle and lineStyle to all edges', () => {
+    const c = createTemplateContext(DEFAULT_THEME, 0, 1, VIEWPORT_PRESETS.landscape);
+    c.children = [node('a', 0, 0, 'b'), node('b', 300, 0)];
+    const input: DiagramBlockInput = {
+      template: 'diagram',
+      id: 'g',
+      duration: 0,
+      audioSegment: 0,
+      endStyle: 'circle',
+      lineStyle: 'dashed',
+    };
+    const layers = diagramBlock(input, c);
+    const edge = layers.find((l) => l.id.startsWith('edge-')) as PathLayer | undefined;
+    expect(edge?.content.endMarker).toBe('circle');
+    expect(edge?.content.dasharray).toBe('8 6');
+  });
+});

package/src/__tests__/structuredData.test.ts

@@ -0,0 +1,249 @@
+import { describe, it, expect } from 'vitest';
+import { parseMarkdown } from '../markdown/parse.js';
+import { markdownToDoc } from '../doc/markdownToDoc.js';
+import { parseYamlSubset, replaceDataFence } from '../doc/structuredData.js';
+import type { MarkdownCodeBlock } from '../markdown/types.js';
+
+function toDoc(md: string) {
+  return markdownToDoc(parseMarkdown(md));
+}
+
+describe('parseYamlSubset', () => {
+  it('parses scalars with type coercion', () => {
+    expect(parseYamlSubset('title: Hello world\ncount: 3\nlive: true\nnothing: null')).toEqual({
+      title: 'Hello world',
+      count: 3,
+      live: true,
+      nothing: null,
+    });
+  });
+
+  it('parses inline arrays', () => {
+    expect(parseYamlSubset('headers: [Name, Age]')).toEqual({ headers: ['Name', 'Age'] });
+  });
+
+  it('parses block sequences of scalars and inline arrays', () => {
+    expect(
+      parseYamlSubset('rows:\n  - [Alice, 30]\n  - [Bob, 25]\nmarkers:\n  - "47.6,-122.3"'),
+    ).toEqual({
+      rows: [
+        ['Alice', 30],
+        ['Bob', 25],
+      ],
+      markers: ['47.6,-122.3'],
+    });
+  });
+
+  it('preserves quoted strings (commas, numbers stay strings)', () => {
+    expect(parseYamlSubset('label: "1,234"')).toEqual({ label: '1,234' });
+  });
+
+  it('skips comments and blank lines', () => {
+    expect(parseYamlSubset('# comment\n\nkey: value')).toEqual({ key: 'value' });
+  });
+
+  it('parses one level of nested mapping', () => {
+    expect(parseYamlSubset('center:\n  lat: 47.6\n  lng: -122.3\nzoom: 12')).toEqual({
+      center: { lat: 47.6, lng: -122.3 },
+      zoom: 12,
+    });
+  });
+
+  it('rejects nesting deeper than one level with a line-anchored error', () => {
+    expect(() => parseYamlSubset('a:\n  b:\n    c: 1')).toThrow(/line 2/);
+    expect(() => parseYamlSubset('a:\n  b: 1\n    c: 2')).toThrow(/line 3/);
+  });
+
+  it('rejects mixing list items and mapping keys under one key', () => {
+    expect(() => parseYamlSubset('a:\n  - x\n  b: 1')).toThrow(/mix/);
+    expect(() => parseYamlSubset('a:\n  b: 1\n  - x')).toThrow(/mix/);
+  });
+});
+
+describe('data fences → block.templateData', () => {
+  it('parses a ```json data fence into templateData', () => {
+    const md = [
+      '## Numbers {[dataTable]}',
+      '',
+      '```json data',
+      '{ "headers": ["Q", "Revenue"], "rows": [["Q1", "1.2M"]] }',
+      '```',
+    ].join('\n');
+    const doc = toDoc(md);
+    expect(doc.blocks[0].templateData).toEqual({
+      headers: ['Q', 'Revenue'],
+      rows: [['Q1', '1.2M']],
+    });
+    expect(doc.diagnostics).toBeUndefined();
+  });
+
+  it('parses a ```yaml data fence into templateData', () => {
+    const md = [
+      '## Map {[map]}',
+      '',
+      '```yaml data',
+      'zoom: 12',
+      'markers:',
+      '  - "47.6,-122.3"',
+      '```',
+    ].join('\n');
+    const doc = toDoc(md);
+    expect(doc.blocks[0].templateData).toEqual({ zoom: 12, markers: ['47.6,-122.3'] });
+  });
+
+  it('ignores plain ```json fences without the data marker', () => {
+    const md = '## Code {[sectionHeader]}\n\n```json\n{ "just": "a sample" }\n```';
+    const doc = toDoc(md);
+    expect(doc.blocks[0].templateData).toBeUndefined();
+  });
+
+  it('records a diagnostic for unparseable fences and degrades gracefully', () => {
+    const md = '## Bad {[dataTable]}\n\n```json data\n{ not valid json\n```';
+    const doc = toDoc(md);
+    expect(doc.blocks[0].templateData).toBeUndefined();
+    expect(doc.diagnostics).toHaveLength(1);
+    expect(doc.diagnostics![0]).toMatchObject({ severity: 'error', code: 'data-fence-parse' });
+    expect(doc.diagnostics![0].line).toBe(3);
+  });
+});
+
+describe('replaceDataFence', () => {
+  it('replaces the first data fence content, keeping lang and meta', () => {
+    const doc = toDoc(
+      '## Numbers {[dataTable]}\n\nIntro.\n\n```json data\n{ "headers": ["Q"] }\n```',
+    );
+    const contents = doc.blocks[0].contents!;
+
+    const next = replaceDataFence(contents, { headers: ['Q', 'Revenue'] });
+
+    const fence = next.find((n): n is MarkdownCodeBlock => n.type === 'code')!;
+    expect(fence.lang).toBe('json');
+    expect(fence.meta).toBe('data');
+    expect(JSON.parse(fence.value)).toEqual({ headers: ['Q', 'Revenue'] });
+    // Pretty-printed, not single-line.
+    expect(fence.value).toContain('\n');
+    // Same length, other nodes untouched.
+    expect(next).toHaveLength(contents.length);
+    expect(next[0]).toBe(contents[0]);
+  });
+
+  it('does not mutate the input array or the original fence node', () => {
+    const doc = toDoc('## Numbers {[dataTable]}\n\n```json data\n{ "a": 1 }\n```');
+    const contents = doc.blocks[0].contents!;
+    const originalFence = contents.find((n): n is MarkdownCodeBlock => n.type === 'code')!;
+
+    replaceDataFence(contents, { a: 2 });
+
+    expect(originalFence.value).toBe('{ "a": 1 }');
+  });
+
+  it('appends a new ```json data fence when none exists', () => {
+    const doc = toDoc('## Numbers {[dataTable]}\n\nJust text.');
+    const contents = doc.blocks[0].contents!;
+
+    const next = replaceDataFence(contents, { rows: [['Q1', '1.2M']] });
+
+    expect(next).toHaveLength(contents.length + 1);
+    const fence = next[next.length - 1] as MarkdownCodeBlock;
+    expect(fence).toMatchObject({ type: 'code', lang: 'json', meta: 'data' });
+    expect(JSON.parse(fence.value)).toEqual({ rows: [['Q1', '1.2M']] });
+  });
+
+  it('treats plain code fences (no data marker) as non-fences and appends', () => {
+    const doc = toDoc('## Code {[sectionHeader]}\n\n```json\n{ "just": "a sample" }\n```');
+    const contents = doc.blocks[0].contents!;
+
+    const next = replaceDataFence(contents, { a: 1 });
+
+    // The sample fence is untouched; a data fence is appended after it.
+    const sample = next.find((n): n is MarkdownCodeBlock => n.type === 'code' && !n.meta)!;
+    expect(sample.value).toBe('{ "just": "a sample" }');
+    expect(next).toHaveLength(contents.length + 1);
+    expect((next[next.length - 1] as MarkdownCodeBlock).meta).toBe('data');
+  });
+});
+
+describe('dataTable eats GFM tables', () => {
+  const table = ['| Name | Age |', '| --- | ---: |', '| Alice | 30 |', '| Bob | 25 |'].join('\n');
+
+  it('supplies headers/rows/align from the first table in the body', () => {
+    const doc = toDoc(`## People {[dataTable]}\n\n${table}`);
+    expect(doc.blocks[0].templateData).toEqual({
+      headers: ['Name', 'Age'],
+      rows: [
+        ['Alice', '30'],
+        ['Bob', '25'],
+      ],
+      align: [null, 'right'],
+    });
+  });
+
+  it('does not extract tables for non-dataTable templates', () => {
+    const doc = toDoc(`## People {[sectionHeader]}\n\n${table}`);
+    expect(doc.blocks[0].templateData).toBeUndefined();
+  });
+
+  it('explicit fence data wins over the body table', () => {
+    const md = [
+      '## People {[dataTable]}',
+      '',
+      '```json data',
+      '{ "headers": ["X"], "rows": [["1"]] }',
+      '```',
+      '',
+      table,
+    ].join('\n');
+    const doc = toDoc(md);
+    expect(doc.blocks[0].templateData).toEqual({ headers: ['X'], rows: [['1']] });
+  });
+});
+
+describe('deterministic conversion', () => {
+  const md = '# Title\n\nSome body text.\n\n## Section {[quote]}\n\nA quote here.';
+
+  it('produces identical Docs for identical input', () => {
+    expect(toDoc(md)).toEqual(toDoc(md));
+  });
+
+  it('omits captions.generatedAt unless a timestamp is supplied', () => {
+    const doc = toDoc(md);
+    expect(doc.captions).toBeDefined();
+    expect(doc.captions!.generatedAt).toBeUndefined();
+
+    const stamped = markdownToDoc(parseMarkdown(md), {
+      captionsGeneratedAt: '2026-06-10T00:00:00.000Z',
+    });
+    expect(stamped.captions!.generatedAt).toBe('2026-06-10T00:00:00.000Z');
+  });
+});
+
+describe('conversion diagnostics', () => {
+  it('flags duplicate pinned ids', () => {
+    const doc = toDoc('## A {#dup}\n\n## B {#dup}');
+    expect(doc.diagnostics).toBeDefined();
+    expect(doc.diagnostics![0]).toMatchObject({ severity: 'error', code: 'duplicate-id' });
+  });
+
+  it('a pinned id reserves the slug so a later heading does not collide', () => {
+    const doc = toDoc('## Other name {#intro}\n\n## Intro');
+    const ids = doc.blocks.map((b) => b.id);
+    expect(ids[0]).toBe('intro');
+    expect(ids[1]).not.toBe('intro');
+    expect(doc.diagnostics).toBeUndefined();
+  });
+
+  it('flags connectsTo targets that do not resolve', () => {
+    const doc = toDoc('## A {#a connectsTo=ghost}\n\n## B {#b}');
+    expect(doc.diagnostics).toBeDefined();
+    expect(doc.diagnostics![0]).toMatchObject({
+      severity: 'warning',
+      code: 'unresolved-connection',
+      blockId: 'a',
+    });
+  });
+
+  it('resolved connections produce no diagnostics', () => {
+    const doc = toDoc('## A {#a connectsTo=b}\n\n## B {#b}');
+    expect(doc.diagnostics).toBeUndefined();
+  });
+});

package/src/__tests__/templateAnnotationParse.test.ts

@@ -1,7 +1,15 @@
 import { describe, it, expect } from 'vitest';
 import { parseMarkdown } from '../markdown/parse.js';
+import { stringifyMarkdown } from '../markdown/stringify.js';
 import { markdownToDoc } from '../doc/markdownToDoc.js';
 
+function getHeading(md: string) {
+  const doc = parseMarkdown(md);
+  const heading = doc.children[0];
+  if (heading.type !== 'heading') throw new Error('expected heading');
+  return heading;
+}
+
 describe('Template annotation in Heading parse path', () => {
   it('parseMarkdown extracts {[template]} from a heading', () => {
     const md = '## Getting Started {[comparisonBar]}';
@@ -40,3 +48,103 @@ describe('Template annotation in Heading parse path', () => {
     expect(heading.templateAnnotation).toBeUndefined();
   });
 });
+
+describe('Quoted values in {[…]} annotations', () => {
+  it('parses double-quoted values with spaces (the documented syntax)', () => {
+    const h = getHeading(
+      '## Gallery {[imageWithCaption src="photo.jpg" caption="Beach at sunset"]}',
+    );
+    expect(h.templateAnnotation).toEqual({
+      template: 'imageWithCaption',
+      params: { src: 'photo.jpg', caption: 'Beach at sunset' },
+    });
+  });
+
+  it('parses single-quoted values with spaces', () => {
+    const h = getHeading("## X {[quote text='A long caption']}");
+    expect(h.templateAnnotation?.params).toEqual({ text: 'A long caption' });
+  });
+
+  it('parses a quoted value containing ]', () => {
+    const h = getHeading('## X {[quote text="a ] b"]}');
+    expect(h.templateAnnotation?.params).toEqual({ text: 'a ] b' });
+  });
+
+  it('parses a quoted value containing commas without splitting', () => {
+    const h = getHeading('## X {[quote text="hello, friend"]}');
+    expect(h.templateAnnotation?.params).toEqual({ text: 'hello, friend' });
+  });
+
+  it('treats an apostrophe inside an unquoted value as literal', () => {
+    const h = getHeading("## X {[quote attribution=O'Brien align=left]}");
+    expect(h.templateAnnotation?.params).toEqual({ attribution: "O'Brien", align: 'left' });
+  });
+
+  it('parses a double quote inside a single-quoted value', () => {
+    const h = getHeading('## X {[quote text=\'She said "hi"\']}');
+    expect(h.templateAnnotation?.params).toEqual({ text: 'She said "hi"' });
+  });
+
+  it('parses backslash-escaped emphasis characters inside quoted values', () => {
+    // Bare * would be parsed as markdown emphasis and fragment the heading
+    // text run; the documented escape hatch is to backslash it. remark
+    // resolves the escape before annotation extraction.
+    const h = getHeading('## X {[quote text="a \\*b\\* c"]}');
+    expect(h.templateAnnotation?.params).toEqual({ text: 'a *b* c' });
+  });
+
+  it('parses a template-less key=value annotation with a quoted value', () => {
+    const h = getHeading('## X {[audio="intro track.mp3"]}');
+    expect(h.templateAnnotation).toEqual({ params: { audio: 'intro track.mp3' } });
+  });
+});
+
+describe('Round-trip of quoted template params', () => {
+  function roundTrip(src: string): string {
+    return stringifyMarkdown(parseMarkdown(src)).trim();
+  }
+
+  it('spacey double-quoted values round-trip verbatim', () => {
+    const src = '## Gallery {[imageWithCaption src=photo.jpg caption="Beach at sunset"]}';
+    expect(roundTrip(src)).toBe(src);
+  });
+
+  it('single quotes canonicalize to double quotes', () => {
+    expect(roundTrip("## X {[quote text='A long caption']}")).toBe(
+      '## X {[quote text="A long caption"]}',
+    );
+  });
+
+  it('a value containing a double quote round-trips via single quotes', () => {
+    const src = '## X {[quote text=\'She said "hi"\']}';
+    expect(roundTrip(src)).toBe(src);
+  });
+
+  it('a quoted ] round-trips', () => {
+    const src = '## X {[quote text="a ] b"]}';
+    expect(roundTrip(src)).toBe(src);
+  });
+
+  it('emphasis characters survive a full stringify → parse cycle', () => {
+    // The emitted source keeps \* escaped (so the heading text run stays
+    // intact); reparsing resolves the escape back to the bare character.
+    const src = '## X {[quote text="a \\*b\\* c"]}';
+    const emitted = roundTrip(src);
+    expect(emitted).toBe(src);
+    const h = getHeading(emitted);
+    expect(h.templateAnnotation?.params).toEqual({ text: 'a *b* c' });
+  });
+
+  it('stringify quotes spacey values produced programmatically', () => {
+    const doc = parseMarkdown('## X {[quote]}');
+    const heading = doc.children[0];
+    if (heading.type !== 'heading') throw new Error('expected heading');
+    heading.templateAnnotation = {
+      template: 'quote',
+      params: { text: 'Beach at sunset', attribution: 'someone' },
+    };
+    expect(stringifyMarkdown(doc).trim()).toBe(
+      '## X {[quote text="Beach at sunset" attribution=someone]}',
+    );
+  });
+});

package/src/__tests__/templateMetadata.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from 'vitest';
+import { templateRegistry, TEMPLATE_METADATA, TEMPLATE_ALIASES } from '../doc/templates/index';
+
+describe('TEMPLATE_METADATA', () => {
+  it('stays exactly 1:1 with templateRegistry (same ids)', () => {
+    const registryIds = Object.keys(templateRegistry).sort();
+    const metadataIds = Object.keys(TEMPLATE_METADATA).sort();
+    // If this fails, a template was added to the registry without metadata
+    // (or vice versa). Add the missing entry — the editor's TemplatePicker
+    // renders its gallery from TEMPLATE_METADATA, so a registry-only template
+    // would never appear in the picker.
+    expect(metadataIds).toEqual(registryIds);
+  });
+
+  it('every entry has a non-empty label and description', () => {
+    for (const [id, meta] of Object.entries(TEMPLATE_METADATA)) {
+      expect(meta.label, `label for "${id}"`).toBeTruthy();
+      expect(meta.description, `description for "${id}"`).toBeTruthy();
+    }
+  });
+});
+
+describe('TEMPLATE_ALIASES', () => {
+  it('every alias target resolves to a real registry entry', () => {
+    // A typo'd alias target would otherwise fall through resolveTemplateName's
+    // `?? name` fallback and silently resolve to a non-existent template.
+    for (const [alias, target] of Object.entries(TEMPLATE_ALIASES)) {
+      expect(target in templateRegistry, `alias "${alias}" → "${target}"`).toBe(true);
+    }
+  });
+});