@bendyline/squisq 1.4.0 → 1.5.0

package/src/__tests__/rootExports.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import * as root from '../index';
+import * as icons from '../icons/index';
+import * as transform from '../transform/index';
+
+const transformRuntimeExports = [
+  'applyTransform',
+  'resolveTransformStyle',
+  'getTransformStyleIds',
+  'getTransformStyleSummaries',
+  'DEFAULT_TRANSFORM_STYLE_ID',
+  'analyzeBlocks',
+  'extractDocImages',
+] as const;
+
+const iconRuntimeExports = [
+  'ICONS',
+  'resolveIcon',
+  'canonicalIconToken',
+  'looksLikeIconToken',
+  'suggestIcons',
+  'iconGlyph',
+] as const;
+
+function expectReExported(
+  rootExports: Record<string, unknown>,
+  subpathExports: Record<string, unknown>,
+  names: readonly string[],
+): void {
+  for (const name of names) {
+    expect(rootExports[name], `root barrel should re-export ${name}`).toBe(subpathExports[name]);
+  }
+}
+
+describe('root barrel exports', () => {
+  it('re-exports transform runtime APIs', () => {
+    expectReExported(root, transform, transformRuntimeExports);
+  });
+
+  it('re-exports icon runtime APIs', () => {
+    expectReExported(root, icons, iconRuntimeExports);
+  });
+});

package/src/__tests__/shapeGeometry.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+import {
+  shapePath,
+  markerPath,
+  connectorPath,
+  clipEndpoints,
+  lineStyleDasharray,
+  PATH_SHAPE_KINDS,
+} from '../doc/utils/shapeGeometry.js';
+
+describe('shapePath', () => {
+  it('returns a non-empty path beginning with M for every path-shape kind', () => {
+    for (const kind of PATH_SHAPE_KINDS) {
+      const d = shapePath(kind, 0, 0, 100, 80);
+      expect(d, kind).toBeTruthy();
+      expect(d?.startsWith('M'), kind).toBe(true);
+    }
+  });
+
+  it('returns null for natively-rendered primitives', () => {
+    for (const kind of ['rect', 'circle', 'line', 'text', 'path', 'arrow']) {
+      expect(shapePath(kind, 0, 0, 10, 10), kind).toBeNull();
+    }
+  });
+
+  it('triangle is a closed 3-point polygon inscribed in the box', () => {
+    expect(shapePath('triangle', 0, 0, 100, 100)).toBe('M 50 0 L 100 100 L 0 100 Z');
+  });
+
+  it('diamond hits the four edge midpoints', () => {
+    expect(shapePath('diamond', 0, 0, 100, 100)).toBe('M 50 0 L 100 50 L 50 100 L 0 50 Z');
+  });
+
+  it('honors the bounding-box offset', () => {
+    expect(shapePath('triangle', 10, 20, 100, 100)).toBe('M 60 20 L 110 120 L 10 120 Z');
+  });
+});
+
+describe('markerPath', () => {
+  it('arrow end is a filled triangle; none is null', () => {
+    expect(markerPath('arrow', 'end')).toEqual({ d: 'M 0 0 L 10 5 L 0 10 z', filled: true });
+    expect(markerPath('none', 'end')).toBeNull();
+  });
+
+  it('open is unfilled; diamond/circle/square are filled', () => {
+    expect(markerPath('open', 'end')?.filled).toBe(false);
+    expect(markerPath('diamond', 'end')?.filled).toBe(true);
+    expect(markerPath('circle', 'end')?.filled).toBe(true);
+    expect(markerPath('square', 'end')?.filled).toBe(true);
+  });
+
+  it('start mirrors the arrow horizontally', () => {
+    expect(markerPath('arrow', 'start')).toEqual({ d: 'M 10 0 L 0 5 L 10 10 z', filled: true });
+  });
+});
+
+describe('connectorPath', () => {
+  const a = { x: 0, y: 0 };
+  const b = { x: 100, y: 50 };
+
+  it('straight is a single line segment', () => {
+    expect(connectorPath('straight', a, b)).toBe('M 0 0 L 100 50');
+  });
+
+  it('orthogonal has a mid elbow', () => {
+    expect(connectorPath('orthogonal', a, b)).toBe('M 0 0 L 50 0 L 50 50 L 100 50');
+  });
+
+  it('curved is a cubic bezier', () => {
+    expect(connectorPath('curved', a, b).startsWith('M 0 0 C')).toBe(true);
+  });
+});
+
+describe('clipEndpoints', () => {
+  it('clips both endpoints to the box edges', () => {
+    const r = clipEndpoints({ cx: 0, cy: 0, rx: 10, ry: 10 }, { cx: 100, cy: 0, rx: 10, ry: 10 });
+    expect(r.start).toEqual({ x: 10, y: 0 });
+    expect(r.end).toEqual({ x: 90, y: 0 });
+  });
+});
+
+describe('lineStyleDasharray', () => {
+  it('maps line styles to dash patterns', () => {
+    expect(lineStyleDasharray('dashed')).toBe('8 6');
+    expect(lineStyleDasharray('dotted')).toBe('2 6');
+    expect(lineStyleDasharray('solid')).toBeUndefined();
+    expect(lineStyleDasharray(undefined)).toBeUndefined();
+  });
+});

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,179 @@
+import { describe, it, expect } from 'vitest';
+import { parseMarkdown } from '../markdown/parse.js';
+import { markdownToDoc } from '../doc/markdownToDoc.js';
+import { parseYamlSubset } from '../doc/structuredData.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('rejects nested mappings with a line-anchored error', () => {
+    expect(() => parseYamlSubset('outer:\n  inner: 1')).toThrow(/line 2/);
+  });
+});
+
+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('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,21 @@
+import { describe, it, expect } from 'vitest';
+import { templateRegistry, TEMPLATE_METADATA } 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();
+    }
+  });
+});