@bendyline/squisq 2.1.0 → 2.3.0

package/src/doc/templates/titleBlock.ts

@@ -1,150 +0,0 @@
-/**
- * Title Block Template
- *
- * Large title with optional subtitle for doc intros.
- * Centered text with fade-in animations, composed as one lockup:
- * accent rule, title, and subtitle are spaced from the title's
- * estimated height instead of fixed slots that collide on wrap.
- * Adapts font sizes and positioning for different viewports.
- *
- * This is shared code used by both site and efb-app doc renderers.
- */
-
-import type { Layer } from '../../schemas/Doc.js';
-import type { TitleBlockInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import {
-  getTemplateHint,
-  getThemeFont,
-  shouldUseShadow,
-  themedEntrance,
-  themedFontSize,
-} from '../utils/themeUtils.js';
-import { withAlpha } from '../../schemas/colorUtils.js';
-import { estimateTextHeight } from './captionUtils.js';
-
-/**
- * Hint schema published for the theme validator + future customizer hint UI.
- * Themes may set `templateHints.title` entries matching these keys.
- */
-export const titleBlockHintSchema = {
-  /** Whether to render a thin accent line above the title. Default: theme-dependent. */
-  showAccentLine: { type: 'boolean' as const, default: true },
-} as const;
-
-export function titleBlock(input: TitleBlockInput, context: TemplateContext): Layer[] {
-  const { title, subtitle, backgroundColor } = input;
-  const { theme, layout, viewport } = context;
-
-  // Scale font sizes for viewport
-  const titleFontSize = themedFontSize(96, context, true);
-  const subtitleFontSize = themedFontSize(36, context, false);
-
-  const baseBg = backgroundColor || theme.colors.primary;
-
-  // Estimate the title's rendered height so the rule and subtitle key off
-  // its real extent — fixed slots let the rule overlap the ascenders and
-  // stranded the subtitle when the title wrapped.
-  const maxWidthPx = (parseFloat(layout.maxTextWidth) / 100) * viewport.width;
-  const titleH = estimateTextHeight(title, titleFontSize, maxWidthPx, 1.15);
-  const titleYPct = subtitle ? 42 : 48;
-  const px = (v: number) => (v / viewport.height) * 100;
-
-  const layers: Layer[] = [
-    // Background — theme surface with a soft radial accent tint. The tint
-    // is translucent so the theme's text color keeps its contrast with the
-    // surface; a full-strength `primary` hotspot behind the title made
-    // dark-primary light themes unreadable.
-    {
-      type: 'shape',
-      id: 'bg',
-      content: {
-        shape: 'rect',
-        fill: theme.colors.background,
-      },
-      position: { x: 0, y: 0, width: '100%', height: '100%' },
-    },
-    {
-      type: 'shape',
-      id: 'bg-tint',
-      content: {
-        shape: 'rect',
-        fill: `radial-gradient(ellipse at 50% 40%, ${withAlpha(baseBg, 0.32)} 0%, ${withAlpha(baseBg, 0)} 75%)`,
-      },
-      position: { x: 0, y: 0, width: '100%', height: '100%' },
-    },
-  ];
-
-  // Subtle decorative line, clear above the title's ascenders. Themes can
-  // hide it via `templateHints.title.showAccentLine: false` (the line is
-  // decorative; title/subtitle positions don't depend on it).
-  if (getTemplateHint(context, 'title', 'showAccentLine', true)) {
-    layers.push({
-      type: 'shape',
-      id: 'accent-line',
-      content: {
-        shape: 'rect',
-        fill: withAlpha(theme.colors.text, 0.3),
-      },
-      position: {
-        x: '44%',
-        y: `${titleYPct - px(titleH / 2 + 56)}%`,
-        width: '12%',
-        height: '3px',
-      },
-    });
-  }
-
-  layers.push(
-    // Title
-    {
-      type: 'text',
-      id: 'title',
-      content: {
-        text: title,
-        style: {
-          fontSize: titleFontSize,
-          fontFamily: getThemeFont(context, 'title'),
-          fontWeight: 'bold',
-          color: theme.colors.text,
-          textAlign: 'center',
-          shadow: shouldUseShadow(context),
-        },
-      },
-      position: {
-        x: '50%',
-        y: `${titleYPct}%`,
-        anchor: 'center',
-        width: layout.maxTextWidth,
-      },
-      animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 2 }),
-    },
-  );
-
-  // Add subtitle if provided — hangs from the title's estimated bottom edge
-  if (subtitle) {
-    const subH = estimateTextHeight(subtitle, subtitleFontSize, maxWidthPx, 1.5);
-    layers.push({
-      type: 'text',
-      id: 'subtitle',
-      content: {
-        text: subtitle,
-        style: {
-          fontSize: subtitleFontSize,
-          fontFamily: getThemeFont(context, 'body'),
-          color: theme.colors.textMuted,
-          textAlign: 'center',
-          lineHeight: 1.5,
-        },
-      },
-      position: {
-        x: '50%',
-        y: `${titleYPct + px(titleH / 2 + 56 + subH / 2)}%`,
-        anchor: 'center',
-        width: layout.maxTextWidth,
-      },
-      animation: { type: 'fadeIn', duration: 1.5, delay: 1 },
-    });
-  }
-
-  return layers;
-}

package/src/doc/templates/tokens/__tests__/resolveTokens.test.ts

@@ -1,487 +0,0 @@
-/**
- * resolveTokens — placeholder substitution unit tests.
- *
- * Covers each supported token, the escape syntax, and the edge cases
- * called out in the plan (missing data, out-of-range image index,
- * unknown token left literal).
- */
-
-import { describe, it, expect } from 'vitest';
-import { resolveTokens, collectListItems } from '../resolveTokens';
-import type { Block, TextLayer, ImageLayer } from '../../../../schemas/Doc.js';
-import type { CustomTemplateLayer } from '../../../../schemas/CustomTemplates.js';
-
-function textLayer(id: string, text: string): TextLayer {
-  return {
-    id,
-    type: 'text',
-    position: { x: 0, y: 0, width: 100, height: 50 },
-    content: { text, style: { fontSize: 24, color: '#000' } },
-  };
-}
-
-function imageLayer(id: string, src: string, alt = ''): ImageLayer {
-  return {
-    id,
-    type: 'image',
-    position: { x: 0, y: 0, width: 100, height: 100 },
-    content: { src, alt },
-  };
-}
-
-function block(overrides: Partial<Block> = {}): Block {
-  return {
-    id: 'b',
-    startTime: 0,
-    duration: 1,
-    audioSegment: 0,
-    title: 'Block title',
-    ...overrides,
-  };
-}
-
-describe('resolveTokens — TextLayer', () => {
-  it('substitutes {title} with block.title', () => {
-    const layers = resolveTokens([textLayer('a', 'Hello, {title}!')], block({ title: 'World' }));
-    const out = layers[0] as TextLayer;
-    expect(out.content.text).toBe('Hello, World!');
-  });
-
-  it('collapses {title} to empty when block has no title', () => {
-    const layers = resolveTokens([textLayer('a', '[{title}]')], block({ title: undefined }));
-    expect((layers[0] as TextLayer).content.text).toBe('[]');
-  });
-
-  it('substitutes {content} from block.contents (plain text of body)', () => {
-    const layers = resolveTokens(
-      [textLayer('a', 'Body: {content}')],
-      block({
-        contents: [
-          {
-            type: 'paragraph',
-            children: [{ type: 'text', value: 'Hello there' }],
-          },
-        ],
-      }),
-    );
-    expect((layers[0] as TextLayer).content.text).toBe('Body: Hello there');
-  });
-
-  it('joins multiple paragraphs in {content} with single spaces', () => {
-    const layers = resolveTokens(
-      [textLayer('a', '{content}')],
-      block({
-        contents: [
-          { type: 'paragraph', children: [{ type: 'text', value: 'First.' }] },
-          { type: 'paragraph', children: [{ type: 'text', value: 'Second.' }] },
-        ],
-      }),
-    );
-    expect((layers[0] as TextLayer).content.text).toBe('First. Second.');
-  });
-
-  it('joins child titles for {children}', () => {
-    const layers = resolveTokens(
-      [textLayer('a', 'Sections: {children}')],
-      block({
-        children: [
-          block({ id: 'c1', title: 'Alpha' }),
-          block({ id: 'c2', title: 'Beta' }),
-          block({ id: 'c3', title: 'Gamma' }),
-        ],
-      }),
-    );
-    expect((layers[0] as TextLayer).content.text).toBe('Sections: Alpha, Beta, Gamma');
-  });
-
-  it('substitutes {image:N} with the Nth image alt text', () => {
-    const layers = resolveTokens(
-      [textLayer('a', 'Caption: {image:0}')],
-      block({
-        contents: [
-          {
-            type: 'paragraph',
-            children: [{ type: 'image', url: '/a.png', alt: 'Alpha image' }],
-          },
-        ],
-      }),
-    );
-    expect((layers[0] as TextLayer).content.text).toBe('Caption: Alpha image');
-  });
-
-  it('preserves {{title}} as literal {title}', () => {
-    const layers = resolveTokens(
-      [textLayer('a', 'Use {{title}} as a token, or {title} to expand')],
-      block({ title: 'My Doc' }),
-    );
-    expect((layers[0] as TextLayer).content.text).toBe(
-      'Use {title} as a token, or My Doc to expand',
-    );
-  });
-
-  it('leaves unknown tokens literal', () => {
-    const layers = resolveTokens([textLayer('a', 'Hello {nope} world')], block());
-    expect((layers[0] as TextLayer).content.text).toBe('Hello {nope} world');
-  });
-
-  it('substitutes multiple tokens in a single string', () => {
-    const layers = resolveTokens(
-      [textLayer('a', '{title} — {content}')],
-      block({
-        title: 'Doc',
-        contents: [{ type: 'paragraph', children: [{ type: 'text', value: 'body' }] }],
-      }),
-    );
-    expect((layers[0] as TextLayer).content.text).toBe('Doc — body');
-  });
-});
-
-describe('resolveTokens — ImageLayer', () => {
-  it('substitutes {image:0} with the Nth image URL in src', () => {
-    const layers = resolveTokens(
-      [imageLayer('a', '{image:0}')],
-      block({
-        contents: [
-          {
-            type: 'paragraph',
-            children: [{ type: 'image', url: '/hero.png', alt: 'hero' }],
-          },
-        ],
-      }),
-    );
-    expect(layers).toHaveLength(1);
-    expect((layers[0] as ImageLayer).content.src).toBe('/hero.png');
-  });
-
-  it('drops the layer entirely when the requested image index is out of range', () => {
-    const layers = resolveTokens(
-      [imageLayer('a', '{image:99}'), imageLayer('b', '/keep.png')],
-      block({
-        contents: [
-          {
-            type: 'paragraph',
-            children: [{ type: 'image', url: '/one.png', alt: '' }],
-          },
-        ],
-      }),
-    );
-    expect(layers).toHaveLength(1);
-    expect(layers[0].id).toBe('b');
-  });
-
-  it('substitutes tokens in the alt text when the src is also a token', () => {
-    const layers = resolveTokens(
-      [imageLayer('a', '{image:0}', 'Image for {title}')],
-      block({
-        title: 'My Doc',
-        contents: [
-          {
-            type: 'paragraph',
-            children: [{ type: 'image', url: '/x.png', alt: '' }],
-          },
-        ],
-      }),
-    );
-    const img = layers[0] as ImageLayer;
-    expect(img.content.src).toBe('/x.png');
-    expect(img.content.alt).toBe('Image for My Doc');
-  });
-
-  it('passes through ImageLayer with no token in src', () => {
-    const layers = resolveTokens([imageLayer('a', '/static.png')], block());
-    expect((layers[0] as ImageLayer).content.src).toBe('/static.png');
-  });
-});
-
-describe('resolveTokens — other layer types', () => {
-  it('passes ShapeLayer / PathLayer through unchanged', () => {
-    const shape = {
-      id: 's',
-      type: 'shape' as const,
-      position: { x: 0, y: 0, width: 50, height: 50 },
-      content: { shape: 'rect' as const, fill: '#fff' },
-    };
-    const path = {
-      id: 'p',
-      type: 'path' as const,
-      position: { x: 0, y: 0, width: 100, height: 100 },
-      content: { d: 'M 0 0 L 100 100', stroke: '#000' },
-    };
-    const layers = resolveTokens([shape, path], block());
-    expect(layers).toEqual([shape, path]);
-  });
-});
-
-describe('resolveTokens — purity', () => {
-  it('does not mutate the input layers array or the layers themselves', () => {
-    const original = textLayer('a', '{title}');
-    const before = JSON.stringify(original);
-    resolveTokens([original], block({ title: 'X' }));
-    expect(JSON.stringify(original)).toBe(before);
-  });
-});
-
-describe('resolveTokens — {attr:key}', () => {
-  it('reads from templateOverrides first, then templateData, then metadata', () => {
-    // key present in all three → overrides wins
-    const over = resolveTokens(
-      [textLayer('a', '{attr:role}')],
-      block({
-        templateOverrides: { role: 'from-overrides' },
-        templateData: { role: 'from-data' },
-        metadata: { role: 'from-metadata' },
-      }),
-    );
-    expect((over[0] as TextLayer).content.text).toBe('from-overrides');
-
-    // absent from overrides → templateData wins over metadata
-    const data = resolveTokens(
-      [textLayer('a', '{attr:role}')],
-      block({ templateData: { role: 'from-data' }, metadata: { role: 'from-metadata' } }),
-    );
-    expect((data[0] as TextLayer).content.text).toBe('from-data');
-
-    // only metadata has it
-    const meta = resolveTokens(
-      [textLayer('a', '{attr:role}')],
-      block({ metadata: { role: 'from-metadata' } }),
-    );
-    expect((meta[0] as TextLayer).content.text).toBe('from-metadata');
-  });
-
-  it('stringifies non-string templateData values', () => {
-    const layers = resolveTokens(
-      [textLayer('a', 'n={attr:count}')],
-      block({ templateData: { count: 42 } }),
-    );
-    expect((layers[0] as TextLayer).content.text).toBe('n=42');
-  });
-
-  it('collapses a missing attr to empty string', () => {
-    const layers = resolveTokens([textLayer('a', '[{attr:missing}]')], block());
-    expect((layers[0] as TextLayer).content.text).toBe('[]');
-  });
-});
-
-describe('resolveTokens — pipe defaults', () => {
-  it('uses the default when {title} is empty, the value when present', () => {
-    const empty = resolveTokens([textLayer('a', '{title|Untitled}')], block({ title: undefined }));
-    expect((empty[0] as TextLayer).content.text).toBe('Untitled');
-
-    const present = resolveTokens([textLayer('a', '{title|Untitled}')], block({ title: 'Real' }));
-    expect((present[0] as TextLayer).content.text).toBe('Real');
-  });
-
-  it('uses the default on a missing {attr:key|…}', () => {
-    const layers = resolveTokens(
-      [textLayer('a', '{attr:subtitle|Untitled}')],
-      block({ templateOverrides: {} }),
-    );
-    expect((layers[0] as TextLayer).content.text).toBe('Untitled');
-  });
-
-  it('uses the image-src default (and keeps the layer) when the image index is out of range', () => {
-    const layers = resolveTokens([imageLayer('a', '{image:1|fallback.jpg}')], block());
-    expect(layers).toHaveLength(1);
-    expect((layers[0] as ImageLayer).content.src).toBe('fallback.jpg');
-  });
-
-  it('still drops the image layer when {image:N} misses and no default is given', () => {
-    const layers = resolveTokens([imageLayer('a', '{image:1}')], block());
-    expect(layers).toHaveLength(0);
-  });
-
-  it('an empty default renders as empty (present token collapses to blank)', () => {
-    const layers = resolveTokens([textLayer('a', '[{attr:x|}]')], block());
-    expect((layers[0] as TextLayer).content.text).toBe('[]');
-  });
-});
-
-describe('resolveTokens — escape vs pipe defaults', () => {
-  it('leaves {{title|Untitled}} literal (escape shields the pipe default too)', () => {
-    const layers = resolveTokens(
-      [textLayer('a', 'Token: {{title|Untitled}}')],
-      block({ title: 'Real' }),
-    );
-    expect((layers[0] as TextLayer).content.text).toBe('Token: {title|Untitled}');
-  });
-});
-
-function repeatText(
-  id: string,
-  text: string,
-  repeat: CustomTemplateLayer['repeat'],
-): CustomTemplateLayer {
-  return {
-    id,
-    type: 'text',
-    position: { x: '0%', y: '10%', width: '30%', height: '20%' },
-    content: { text, style: { fontSize: 24, color: '#000' } },
-    repeat,
-  };
-}
-
-const imagesBlock = block({
-  contents: [
-    {
-      type: 'paragraph',
-      children: [
-        { type: 'image', url: '/one.png', alt: 'One' },
-        { type: 'image', url: '/two.png', alt: 'Two' },
-        { type: 'image', url: '/three.png', alt: 'Three' },
-      ],
-    },
-  ],
-});
-
-describe('resolveTokens — repeat', () => {
-  it('clones a layer once per image and resolves per-item tokens', () => {
-    const layers = resolveTokens(
-      [repeatText('cap', '{index}. {item} ({item:src})', { source: 'images' })],
-      imagesBlock,
-    );
-    expect(layers).toHaveLength(3);
-    expect((layers[0] as TextLayer).content.text).toBe('1. One (/one.png)');
-    expect((layers[1] as TextLayer).content.text).toBe('2. Two (/two.png)');
-    expect((layers[2] as TextLayer).content.text).toBe('3. Three (/three.png)');
-  });
-
-  it('gives each clone a unique id and strips the repeat prop', () => {
-    const layers = resolveTokens([repeatText('cap', '{item}', { source: 'images' })], imagesBlock);
-    expect(layers.map((l) => l.id)).toEqual(['cap-0', 'cap-1', 'cap-2']);
-    expect(layers.every((l) => !('repeat' in l))).toBe(true);
-  });
-
-  it('iterates children titles', () => {
-    const layers = resolveTokens(
-      [repeatText('c', '{index}:{item}', { source: 'children' })],
-      block({ children: [block({ id: 'a', title: 'Alpha' }), block({ id: 'b', title: 'Beta' })] }),
-    );
-    expect(layers.map((l) => (l as TextLayer).content.text)).toEqual(['1:Alpha', '2:Beta']);
-  });
-
-  it('iterates list items', () => {
-    const layers = resolveTokens(
-      [repeatText('li', '- {item}', { source: 'listItems' })],
-      block({
-        contents: [
-          {
-            type: 'list',
-            ordered: false,
-            children: [
-              {
-                type: 'listItem',
-                children: [{ type: 'paragraph', children: [{ type: 'text', value: 'First' }] }],
-              },
-              {
-                type: 'listItem',
-                children: [{ type: 'paragraph', children: [{ type: 'text', value: 'Second' }] }],
-              },
-            ],
-          },
-        ],
-      }),
-    );
-    expect(layers.map((l) => (l as TextLayer).content.text)).toEqual(['- First', '- Second']);
-  });
-
-  it('caps the number of clones at max', () => {
-    const layers = resolveTokens(
-      [repeatText('cap', '{item}', { source: 'images', max: 2 })],
-      imagesBlock,
-    );
-    expect(layers).toHaveLength(2);
-    expect(layers.map((l) => (l as TextLayer).content.text)).toEqual(['One', 'Two']);
-  });
-
-  it('offsets position.y in column direction by height + gap', () => {
-    const layers = resolveTokens(
-      [repeatText('cap', '{item}', { source: 'images', direction: 'column', gap: 4 })],
-      imagesBlock,
-    );
-    // base y = 10%, height = 20%, gap = 4 → cursor advances by 24 each item
-    expect(layers.map((l) => l.position.y)).toEqual(['10%', '34%', '58%']);
-    // x is untouched in column direction
-    expect(layers.every((l) => l.position.x === '0%')).toBe(true);
-  });
-
-  it('offsets position.x in row direction by width + gap', () => {
-    const layers = resolveTokens(
-      [repeatText('cap', '{item}', { source: 'images', direction: 'row', gap: 10 })],
-      imagesBlock,
-    );
-    // base x = 0%, width = 30%, gap = 10 → cursor advances by 40 each item
-    expect(layers.map((l) => l.position.x)).toEqual(['0%', '40%', '80%']);
-    expect(layers.every((l) => l.position.y === '10%')).toBe(true);
-  });
-
-  it('renders nothing when the source collection is empty', () => {
-    const layers = resolveTokens([repeatText('cap', '{item}', { source: 'images' })], block());
-    expect(layers).toHaveLength(0);
-  });
-
-  it('resolves {item:src} in an image layer inside a repeat', () => {
-    const imgRepeat: CustomTemplateLayer = {
-      id: 'img',
-      type: 'image',
-      position: { x: '0%', y: '0%', width: '25%', height: '25%' },
-      content: { src: '{item:src}', alt: '{item:label}' },
-      repeat: { source: 'images', direction: 'row', gap: 0 },
-    };
-    const layers = resolveTokens([imgRepeat], imagesBlock);
-    expect(layers).toHaveLength(3);
-    expect((layers[0] as ImageLayer).content.src).toBe('/one.png');
-    expect((layers[0] as ImageLayer).content.alt).toBe('One');
-    expect((layers[2] as ImageLayer).content.src).toBe('/three.png');
-  });
-});
-
-describe('resolveTokens — {item}/{index} outside a repeat', () => {
-  it('leaves per-item tokens literal when there is no repeat context', () => {
-    const layers = resolveTokens([textLayer('a', '{item} {index}')], block());
-    expect((layers[0] as TextLayer).content.text).toBe('{item} {index}');
-  });
-});
-
-describe('collectListItems', () => {
-  it('returns top-level list-item text and skips nested double-counting', () => {
-    const b = block({
-      contents: [
-        {
-          type: 'list',
-          ordered: false,
-          children: [
-            {
-              type: 'listItem',
-              children: [
-                { type: 'paragraph', children: [{ type: 'text', value: 'Parent' }] },
-                {
-                  type: 'list',
-                  ordered: false,
-                  children: [
-                    {
-                      type: 'listItem',
-                      children: [
-                        { type: 'paragraph', children: [{ type: 'text', value: 'Nested' }] },
-                      ],
-                    },
-                  ],
-                },
-              ],
-            },
-            {
-              type: 'listItem',
-              children: [{ type: 'paragraph', children: [{ type: 'text', value: 'Sibling' }] }],
-            },
-          ],
-        },
-      ],
-    });
-    // Only two top-level items; the nested item is folded into "Parent Nested".
-    expect(collectListItems(b)).toEqual(['Parent Nested', 'Sibling']);
-  });
-
-  it('returns [] when the block has no list content', () => {
-    expect(collectListItems(block())).toEqual([]);
-  });
-});