@bendyline/squisq 1.5.0 → 1.5.2

package/src/__tests__/customTemplateSample.test.ts

@@ -11,8 +11,12 @@ import { describe, it, expect } from 'vitest';
 import { markdownToDoc } from '../doc/markdownToDoc';
 import { expandDocBlocks } from '../doc/templates/index';
 import { parseMarkdown } from '../markdown/parse';
-import { writeCustomTemplatesToFrontmatter } from '../doc/customTemplatesFrontmatter';
-import type { CustomTemplateDefinition } from '../schemas/CustomTemplates.js';
+import {
+  writeCustomTemplatesToFrontmatter,
+  readCustomTemplatesFromFrontmatter,
+  FRONTMATTER_CUSTOM_TEMPLATES_KEY,
+} from '../doc/customTemplatesFrontmatter';
+import type { CustomTemplateDefinition, LayerRepeat } from '../schemas/CustomTemplates.js';
 import type { TextLayer } from '../schemas/Doc.js';
 import { VIEWPORT_PRESETS } from '../schemas/Viewport.js';
 
@@ -80,4 +84,61 @@ describe('Custom template pipeline (markdown → expanded layers)', () => {
     expect(layers[0].position.x).toBe('6%');
     expect(layers[0].position.width).toBe('88%');
   });
+
+  it('resolves {attr:key} against a block heading annotation through the pipeline', () => {
+    const attrDef: CustomTemplateDefinition = {
+      name: 'badge',
+      label: 'Badge',
+      viewport: { width: 1920, height: 1080 },
+      layers: [
+        {
+          id: 'badge-role',
+          type: 'text',
+          position: { x: '6%', y: '20%', width: '88%' },
+          content: { text: 'Role: {attr:role|none}', style: { fontSize: 48, color: '#000' } },
+        },
+      ],
+    };
+    const payload = writeCustomTemplatesToFrontmatter([attrDef]);
+    const md = `---
+squisq-custom-templates: "${payload}"
+---
+
+# Team {[badge role=lead]}
+
+Body.
+`;
+    const doc = markdownToDoc(parseMarkdown(md));
+    const blocks = expandDocBlocks(doc.blocks, { customTemplates: doc.customTemplates });
+    const layers = blocks[0].layers ?? [];
+    expect((layers[0] as TextLayer).content.text).toBe('Role: lead');
+  });
+});
+
+describe('Custom template codec — repeat round-trip', () => {
+  it('preserves a layer.repeat directive through write → read (passes through unmapped)', () => {
+    const repeat: LayerRepeat = { source: 'images', direction: 'row', gap: 12, max: 4 };
+    const def: CustomTemplateDefinition = {
+      name: 'gallery',
+      label: 'Gallery',
+      viewport: { width: 1920, height: 1080 },
+      layers: [
+        {
+          id: 'thumb',
+          type: 'image',
+          position: { x: '0%', y: '0%', width: '25%', height: '25%' },
+          content: { src: '{item:src}', alt: '{item:label}' },
+          repeat,
+        },
+      ],
+    };
+    const payload = writeCustomTemplatesToFrontmatter([def]);
+    expect(payload).toBeDefined();
+    const round = readCustomTemplatesFromFrontmatter({
+      [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: JSON.parse(payload as string),
+    });
+    expect(round).toBeDefined();
+    const layer = round?.[0].layers[0] as (typeof def.layers)[number];
+    expect(layer.repeat).toEqual(repeat);
+  });
 });

package/src/__tests__/customTemplatesFrontmatter.test.ts

@@ -71,6 +71,37 @@ describe('writeCustomTemplatesToFrontmatter → readCustomTemplatesFromFrontmatt
     expect(out![0]).toEqual(heroDef);
   });
 
+  it('default output is compact (single line) and byte-unchanged', () => {
+    const payload = writeCustomTemplatesToFrontmatter([heroDef])!;
+    expect(payload).not.toContain('\n');
+    // Explicit pretty:false must match the historical default exactly.
+    expect(writeCustomTemplatesToFrontmatter([heroDef], { pretty: false })).toBe(payload);
+  });
+
+  it('pretty:true emits multi-line JSON that still reads back', () => {
+    const payload = writeCustomTemplatesToFrontmatter([heroDef], { pretty: true })!;
+    expect(payload).toContain('\n');
+    // Same compact key codec, just pretty-printed.
+    expect(payload).toContain('"lb": "Hero"');
+    const fm = { [FRONTMATTER_CUSTOM_TEMPLATES_KEY]: payload };
+    const out = readCustomTemplatesFromFrontmatter(fm);
+    expect(out).toHaveLength(1);
+    expect(out![0]).toEqual(heroDef);
+  });
+
+  it('a hand-written block-scalar frontmatter parses back into the definition', () => {
+    const payload = writeCustomTemplatesToFrontmatter([heroDef], { pretty: true })!;
+    const body = payload
+      .split('\n')
+      .map((l) => `  ${l}`)
+      .join('\n');
+    const md = `---\n${FRONTMATTER_CUSTOM_TEMPLATES_KEY}: |-\n${body}\n---\n\n# Hi\n`;
+    const parsed = parseMarkdown(md);
+    const out = readCustomTemplatesFromFrontmatter(parsed.frontmatter);
+    expect(out).toHaveLength(1);
+    expect(out![0]).toEqual(heroDef);
+  });
+
   it('is markedly smaller than the legacy base64 form', () => {
     const compact = writeCustomTemplatesToFrontmatter([heroDef])!;
     const legacyBase64 = btoa(unescape(encodeURIComponent(JSON.stringify([{ ...heroDef }]))));

package/src/__tests__/customThemesFrontmatter.test.ts

@@ -37,6 +37,33 @@ describe('writeCustomThemesToFrontmatter → readCustomThemesFromFrontmatter', (
     expect(out![0]).toEqual(brand);
   });
 
+  it('default output is compact (single line) and byte-unchanged', () => {
+    const payload = writeCustomThemesToFrontmatter([brand])!;
+    expect(payload).not.toContain('\n');
+    expect(writeCustomThemesToFrontmatter([brand], { pretty: false })).toBe(payload);
+  });
+
+  it('pretty:true emits multi-line JSON that still reads back', () => {
+    const payload = writeCustomThemesToFrontmatter([brand], { pretty: true })!;
+    expect(payload).toContain('\n');
+    const out = readCustomThemesFromFrontmatter({ [FRONTMATTER_CUSTOM_THEMES_KEY]: payload });
+    expect(out).toHaveLength(1);
+    expect(out![0]).toEqual(brand);
+  });
+
+  it('a hand-written block-scalar frontmatter parses back into the theme', () => {
+    const payload = writeCustomThemesToFrontmatter([brand], { pretty: true })!;
+    const body = payload
+      .split('\n')
+      .map((l) => `  ${l}`)
+      .join('\n');
+    const md = `---\n${FRONTMATTER_CUSTOM_THEMES_KEY}: |-\n${body}\n---\n\n# Hi\n`;
+    const parsed = parseMarkdown(md);
+    const out = readCustomThemesFromFrontmatter(parsed.frontmatter);
+    expect(out).toHaveLength(1);
+    expect(out![0]).toEqual(brand);
+  });
+
   it('round-trips multiple themes keyed by id', () => {
     const second = compileTheme({
       id: 'second',

package/src/__tests__/inputDescriptors.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect } from 'vitest';
+import {
+  BASE_INPUT_DESCRIPTORS,
+  TEMPLATE_INPUT_DESCRIPTORS,
+  coerceTemplateParams,
+  lintTemplateParams,
+} from '../doc/templates/inputDescriptors';
+import { templateRegistry } from '../doc/templates/index';
+
+describe('coerceTemplateParams', () => {
+  it('coerces number keys, leaving the raw string on failure', () => {
+    expect(coerceTemplateParams('map', { zoom: '9' }).input).toEqual({ zoom: 9 });
+
+    const bad = coerceTemplateParams('map', { zoom: 'abc' });
+    expect(bad.input).toEqual({ zoom: 'abc' });
+    expect(bad.warnings).toHaveLength(1);
+    expect(bad.warnings[0]).toContain('zoom');
+  });
+
+  it('coerces boolean keys (true/empty → true, false → false)', () => {
+    const { input } = coerceTemplateParams('imageWithCaption', { isTitle: 'true' });
+    expect(input.isTitle).toBe(true);
+    // A bare flag `{[… isTitle]}` parses to an empty value → true.
+    expect(coerceTemplateParams('imageWithCaption', { isTitle: '' }).input.isTitle).toBe(true);
+    expect(coerceTemplateParams('imageWithCaption', { isTitle: 'false' }).input.isTitle).toBe(
+      false,
+    );
+
+    const bad = coerceTemplateParams('imageWithCaption', { isTitle: 'maybe' });
+    expect(bad.input.isTitle).toBe('maybe');
+    expect(bad.warnings).toHaveLength(1);
+  });
+
+  it('coerces latLng into { lat, lng }, warning on malformed input', () => {
+    expect(coerceTemplateParams('map', { center: '47.6,-122.3' }).input).toEqual({
+      center: { lat: 47.6, lng: -122.3 },
+    });
+
+    const bad = coerceTemplateParams('map', { center: 'nope' });
+    expect(bad.input).toEqual({ center: 'nope' });
+    expect(bad.warnings[0]).toContain('center');
+  });
+
+  it('coerces labeledPair into { label, sublabel? }', () => {
+    expect(coerceTemplateParams('twoColumn', { left: 'Espresso|Bold' }).input).toEqual({
+      left: { label: 'Espresso', sublabel: 'Bold' },
+    });
+    // No separator → label only, no sublabel key.
+    expect(coerceTemplateParams('twoColumn', { right: 'Filter' }).input).toEqual({
+      right: { label: 'Filter' },
+    });
+  });
+
+  it('coerces stringList by splitting on commas and trimming', () => {
+    expect(coerceTemplateParams('photoGrid', { images: 'a.jpg, b.jpg ,c.jpg' }).input).toEqual({
+      images: ['a.jpg', 'b.jpg', 'c.jpg'],
+    });
+  });
+
+  it('passes unknown keys through unchanged as strings (never lossy)', () => {
+    const { input, warnings } = coerceTemplateParams('map', { wobble: 'yes', center: '1,2' });
+    expect(input.wobble).toBe('yes');
+    expect(input.center).toEqual({ lat: 1, lng: 2 });
+    expect(warnings).toEqual([]);
+  });
+
+  it('passes everything through for a template with no descriptors', () => {
+    expect(coerceTemplateParams('sectionHeader', { anything: '5' }).input).toEqual({
+      anything: '5',
+    });
+  });
+
+  it('resolves legacy template aliases before coercing', () => {
+    expect(coerceTemplateParams('mapBlock', { zoom: '7' }).input).toEqual({ zoom: 7 });
+  });
+
+  it('coerces shared base inputs (useTopLayer boolean)', () => {
+    expect(coerceTemplateParams('title', { useTopLayer: 'false' }).input.useTopLayer).toBe(false);
+  });
+});
+
+describe('lintTemplateParams', () => {
+  it('returns [] for a template without descriptors', () => {
+    expect(lintTemplateParams('sectionHeader', { foo: 'bar' })).toEqual([]);
+  });
+
+  it('flags an unknown input with a did-you-mean suggestion', () => {
+    const findings = lintTemplateParams('map', { centre: '1,2' });
+    const unknown = findings.find((f) => f.kind === 'unknown-input');
+    expect(unknown).toBeDefined();
+    expect(unknown!.key).toBe('centre');
+    expect(unknown!.suggestion).toBe('center');
+    expect(unknown!.message).toContain('Did you mean "center"?');
+  });
+
+  it('does not flag block-meta keys carried on the same annotation', () => {
+    const findings = lintTemplateParams('title', { duration: '8', transition: 'fade' });
+    expect(findings.filter((f) => f.kind === 'unknown-input')).toEqual([]);
+  });
+
+  it('flags a value outside a closed enum', () => {
+    const findings = lintTemplateParams('map', { center: '1,2', mapStyle: 'nope' });
+    const invalid = findings.find((f) => f.kind === 'invalid-input-value');
+    expect(invalid).toBeDefined();
+    expect(invalid!.key).toBe('mapStyle');
+    expect(invalid!.message).toContain('terrain');
+  });
+
+  it('flags a value that fails coercion (bad latLng)', () => {
+    const findings = lintTemplateParams('map', { center: 'garbage' });
+    expect(findings.some((f) => f.kind === 'invalid-input-value' && f.key === 'center')).toBe(true);
+  });
+
+  it('flags missing required inputs', () => {
+    const findings = lintTemplateParams('twoColumn', {});
+    const missing = findings
+      .filter((f) => f.kind === 'missing-input')
+      .map((f) => f.key)
+      .sort();
+    expect(missing).toEqual(['left', 'right']);
+  });
+
+  it('does not flag a required input that is present', () => {
+    const findings = lintTemplateParams('map', { center: '1,2' });
+    expect(findings.filter((f) => f.kind === 'missing-input')).toEqual([]);
+  });
+
+  it('accepts a valid enum value', () => {
+    const findings = lintTemplateParams('map', { center: '1,2', mapStyle: 'satellite' });
+    expect(findings).toEqual([]);
+  });
+});
+
+describe('descriptor registry shape', () => {
+  it('base descriptors are declared with unique keys', () => {
+    const keys = BASE_INPUT_DESCRIPTORS.map((d) => d.key);
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+
+  it('has no orphan descriptors — every keyed template exists in the registry', () => {
+    for (const template of Object.keys(TEMPLATE_INPUT_DESCRIPTORS)) {
+      expect(templateRegistry, `orphan descriptor for "${template}"`).toHaveProperty(template);
+    }
+  });
+
+  it('every template descriptor has unique keys and a description', () => {
+    for (const [template, descriptors] of Object.entries(TEMPLATE_INPUT_DESCRIPTORS)) {
+      const keys = descriptors.map((d) => d.key);
+      expect(new Set(keys).size, `duplicate key in ${template}`).toBe(keys.length);
+      for (const d of descriptors) {
+        expect(d.description.length, `empty description for ${template}.${d.key}`).toBeGreaterThan(
+          0,
+        );
+        // values / valueHint are mutually exclusive.
+        expect(
+          !(d.values && d.valueHint),
+          `${template}.${d.key} has both values and valueHint`,
+        ).toBe(true);
+      }
+    }
+  });
+});

package/src/__tests__/jsonForm.tokens.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import { buildJsonFormTokens, resolveJsonFormTheme } from '../jsonForm/index.js';
+import { DARK_SURFACE, LIGHT_SURFACE, DEFAULT_THEME, applySurface } from '../schemas/index.js';
+
+const EXPECTED_SUFFIXES = [
+  'bg',
+  'text',
+  'muted',
+  'primary',
+  'accent',
+  'warning',
+  'border',
+  'input-bg',
+  'title-font',
+  'body-font',
+  'mono-font',
+  'radius',
+];
+
+describe('buildJsonFormTokens', () => {
+  it('emits the full token set for the viewer prefix', () => {
+    const tokens = buildJsonFormTokens(DEFAULT_THEME, LIGHT_SURFACE, { prefix: '--squisq-json' });
+    for (const suffix of EXPECTED_SUFFIXES) {
+      expect(tokens).toHaveProperty(`--squisq-json-${suffix}`);
+    }
+    expect(Object.keys(tokens)).toHaveLength(EXPECTED_SUFFIXES.length);
+  });
+
+  it('emits the full token set for the editor prefix', () => {
+    const tokens = buildJsonFormTokens(DEFAULT_THEME, LIGHT_SURFACE, {
+      prefix: '--squisq-jsonform',
+    });
+    for (const suffix of EXPECTED_SUFFIXES) {
+      expect(tokens).toHaveProperty(`--squisq-jsonform-${suffix}`);
+    }
+    expect(Object.keys(tokens)).toHaveLength(EXPECTED_SUFFIXES.length);
+  });
+
+  it('resolves colors from the applied surface (light vs dark differ)', () => {
+    const light = buildJsonFormTokens(DEFAULT_THEME, LIGHT_SURFACE, { prefix: '--squisq-json' });
+    const dark = buildJsonFormTokens(DEFAULT_THEME, DARK_SURFACE, { prefix: '--squisq-json' });
+    const lightTheme = applySurface(DEFAULT_THEME, LIGHT_SURFACE);
+    const darkTheme = applySurface(DEFAULT_THEME, DARK_SURFACE);
+    expect(light['--squisq-json-bg']).toBe(lightTheme.colors.background);
+    expect(dark['--squisq-json-bg']).toBe(darkTheme.colors.background);
+    // The two surfaces should not produce an identical background.
+    expect(light['--squisq-json-bg']).not.toBe(dark['--squisq-json-bg']);
+  });
+
+  it('falls back to DEFAULT_THEME when theme is undefined', () => {
+    const tokens = buildJsonFormTokens(undefined, undefined, { prefix: '--squisq-json' });
+    expect(tokens['--squisq-json-bg']).toBe(DEFAULT_THEME.colors.background);
+  });
+
+  it('does not apply surface when surface is undefined', () => {
+    const tokens = buildJsonFormTokens(DEFAULT_THEME, undefined, { prefix: '--squisq-json' });
+    expect(tokens['--squisq-json-bg']).toBe(DEFAULT_THEME.colors.background);
+    expect(tokens['--squisq-json-radius']).toBe(`${DEFAULT_THEME.style.borderRadius ?? 8}px`);
+  });
+
+  it('is pure — no window/matchMedia access required', () => {
+    // Runs fine even if window is momentarily undefined-like; the function
+    // never touches globals.
+    expect(() =>
+      buildJsonFormTokens(DEFAULT_THEME, DARK_SURFACE, { prefix: '--squisq-json' }),
+    ).not.toThrow();
+  });
+});
+
+describe('resolveJsonFormTheme', () => {
+  it('applies the surface to the theme', () => {
+    expect(resolveJsonFormTheme(DEFAULT_THEME, DARK_SURFACE)).toEqual(
+      applySurface(DEFAULT_THEME, DARK_SURFACE),
+    );
+  });
+
+  it('returns the base theme untouched when surface is undefined', () => {
+    expect(resolveJsonFormTheme(DEFAULT_THEME, undefined)).toBe(DEFAULT_THEME);
+  });
+
+  it('falls back to DEFAULT_THEME when theme is undefined', () => {
+    expect(resolveJsonFormTheme(undefined, undefined)).toBe(DEFAULT_THEME);
+  });
+});

package/src/__tests__/markdown.test.ts

@@ -11,6 +11,7 @@ import {
   countNodes,
   createDocument,
   parseFrontmatter,
+  setFrontmatterValues,
   plainTextFromInlineHtml,
 } from '../markdown/index';
 import type {
@@ -839,6 +840,69 @@ describe('parseFrontmatter', () => {
     expect(parseFrontmatter('')).toBeNull();
     expect(parseFrontmatter('  \n  ')).toBeNull();
   });
+
+  it('parses a `|-` literal block scalar, dedenting the body', () => {
+    const result = parseFrontmatter('data: |-\n  line one\n  line two\ntitle: After');
+    expect(result).toEqual({ data: 'line one\nline two', title: 'After' });
+  });
+
+  it('parses a `|` literal block scalar (same joined value here)', () => {
+    const result = parseFrontmatter('data: |\n  a\n  b');
+    expect(result).toEqual({ data: 'a\nb' });
+  });
+
+  it('ends the block scalar at a line indented to the key or less', () => {
+    const result = parseFrontmatter('config: |-\n  {\n    "k": 1\n  }\nnext: x');
+    expect(result).toEqual({ config: '{\n  "k": 1\n}', next: 'x' });
+  });
+
+  it('parses multi-line pretty JSON as a block scalar back to a JSON string', () => {
+    const json = JSON.stringify({ hero: { lb: 'Hero' } }, null, 2);
+    const body = json
+      .split('\n')
+      .map((l) => `  ${l}`)
+      .join('\n');
+    const result = parseFrontmatter(`squisq-custom-templates: |-\n${body}`);
+    expect(typeof result!['squisq-custom-templates']).toBe('string');
+    expect(JSON.parse(result!['squisq-custom-templates'] as string)).toEqual({
+      hero: { lb: 'Hero' },
+    });
+  });
+
+  it('leaves single-line values untouched alongside block scalars', () => {
+    const result = parseFrontmatter('title: Plain\ninline: {"a":1}');
+    expect(result).toEqual({ title: 'Plain', inline: '{"a":1}' });
+  });
+});
+
+describe('multi-line frontmatter round-trips', () => {
+  it('round-trips a multi-line string value through stringify → parse', () => {
+    const value = JSON.stringify({ a: 1, b: [2, 3] }, null, 2);
+    const doc = createDocument();
+    doc.frontmatter = { payload: value, title: 'Doc' };
+    const md = stringifyMarkdown(doc);
+    expect(md).toContain('payload: |-');
+    const reparsed = parseMarkdown(md);
+    expect(reparsed.frontmatter!.payload).toBe(value);
+    expect(reparsed.frontmatter!.title).toBe('Doc');
+  });
+
+  it('setFrontmatterValues emits a block scalar for a multi-line value', () => {
+    const value = 'one\ntwo\nthree';
+    const out = setFrontmatterValues('# Body\n', { notes: value });
+    expect(out).toContain('notes: |-');
+    expect(out).toContain('  one');
+    const doc = parseMarkdown(out);
+    expect(doc.frontmatter!.notes).toBe(value);
+  });
+
+  it('keeps single-line frontmatter output unchanged', () => {
+    const doc = createDocument();
+    doc.frontmatter = { 'document-render-as': 'portrait' };
+    const md = stringifyMarkdown(doc);
+    expect(md).toContain('document-render-as: portrait');
+    expect(md).not.toContain('|-');
+  });
 });
 
 describe('frontmatter in parseMarkdown', () => {

package/src/__tests__/markdownSanitize.test.ts

@@ -17,6 +17,21 @@ describe('markdown HTML sanitization', () => {
     expect(sanitizeUrl('data:text/html,<script>alert(1)</script>', 'link')).toBeNull();
   });
 
+  it('extraLinkSchemes allows host-app schemes but never executable ones', () => {
+    expect(sanitizeUrl('gezel-nav:src%2Fa.ts', 'link')).toBeNull();
+    expect(sanitizeUrl('gezel-nav:src%2Fa.ts', 'link', { extraLinkSchemes: ['gezel-nav'] })).toBe(
+      'gezel-nav:src%2Fa.ts',
+    );
+    expect(
+      sanitizeUrl('javascript:alert(1)', 'link', { extraLinkSchemes: ['javascript'] }),
+    ).toBeNull();
+    expect(sanitizeUrl('data:text/html,x', 'link', { extraLinkSchemes: ['data'] })).toBeNull();
+    // media URLs ignore the option entirely
+    expect(
+      sanitizeUrl('gezel-nav:src%2Fa.ts', 'media', { extraLinkSchemes: ['gezel-nav'] }),
+    ).toBeNull();
+  });
+
   it('allows Squisq media URLs without allowing SVG or HTML data payloads', () => {
     expect(sanitizeUrl('blob:http://localhost/abc', 'media')).toBe('blob:http://localhost/abc');
     expect(sanitizeUrl('data:image/png;base64,AAA', 'media')).toBe('data:image/png;base64,AAA');