@bendyline/squisq 1.5.2 → 2.0.1

package/src/doc/templates/listBlock.ts

@@ -19,6 +19,43 @@ import {
 } from '../utils/themeUtils.js';
 import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
 
+const LIST_ITEM_LINE_HEIGHT = 1.2;
+const LIST_ITEM_GAP_PX = 18;
+
+/**
+ * Mirror the renderer's character-based wrapping closely enough to reserve
+ * vertical space for each independently positioned text layer.
+ */
+function estimateWrappedLineCount(text: string, fontSize: number, maxWidth: number): number {
+  if (!text.trim()) return 1;
+
+  const charsPerLine = Math.floor(maxWidth / (fontSize * 0.5));
+  if (charsPerLine <= 0) return 1;
+
+  let lineCount = 0;
+  let currentLineLength = 0;
+
+  for (const word of text.split(/\s+/)) {
+    const testLineLength = currentLineLength ? currentLineLength + 1 + word.length : word.length;
+
+    if (testLineLength <= charsPerLine) {
+      currentLineLength = testLineLength;
+      continue;
+    }
+
+    if (currentLineLength) lineCount += 1;
+
+    let remainingLength = word.length;
+    while (remainingLength > charsPerLine) {
+      lineCount += 1;
+      remainingLength -= charsPerLine;
+    }
+    currentLineLength = remainingLength;
+  }
+
+  return Math.max(1, lineCount + (currentLineLength ? 1 : 0));
+}
+
 export function listBlock(input: ListBlockInput, context: TemplateContext): Layer[] {
   const { title, accentImage } = input;
   // `items` is required by the schema, but malformed / partially-authored
@@ -66,8 +103,9 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
   // defensive against future edits to the accent-layout types).
   const centerX = parseFloat(accentLayout.textCenterX);
   const widthPct = parseFloat(accentLayout.textWidth);
-  const leftX =
-    Number.isFinite(centerX) && Number.isFinite(widthPct) ? `${centerX - widthPct / 2}%` : '8%';
+  const leftPct =
+    Number.isFinite(centerX) && Number.isFinite(widthPct) ? centerX - widthPct / 2 : 8;
+  const leftX = `${leftPct}%`;
 
   // Title if provided
   const startY = title ? 34 : 26;
@@ -95,28 +133,49 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
     });
   }
 
-  // Stack items with a fixed compact gap rather than stretching them
-  // across the available band. Distributing items across (startY → 80%)
-  // left big vertical gaps for short lists and made the slide read as a
-  // sparse menu instead of a tight enumeration; conversely a bare
-  // line-height gap read as a cramped paragraph — 18px of air keeps each
-  // entry its own line without breaking the group.
-  //
-  // Spacing = item line-height (34px base × 1.2) + 18px gap, expressed
-  // as % of the 1080px design canvas (~5.4%). Wrapped items push the
-  // next entry down via their own line-height, so this sets the
-  // minimum baseline-to-baseline distance for unwrapped items.
-  const LIST_ITEM_BASE_PX = 34;
-  const LIST_ITEM_LINE_HEIGHT = 1.2;
-  const LIST_ITEM_GAP_PX = 18;
-  const DESIGN_HEIGHT_PX = 1080;
-  const spacing =
-    ((LIST_ITEM_BASE_PX * LIST_ITEM_LINE_HEIGHT + LIST_ITEM_GAP_PX) / DESIGN_HEIGHT_PX) * 100;
+  // Render the number and body in separate columns. The body is therefore a
+  // single text layer whose wrapped lines all share the same x coordinate,
+  // producing a hanging indent instead of wrapping underneath the number.
+  const textWidthPx = (Number.isFinite(widthPct) ? widthPct / 100 : 0.85) * context.viewport.width;
+  const markerText = `${items.length}.`;
+  const markerWidthPx = Math.max(itemFontSize, markerText.length * itemFontSize * 0.5);
+  const markerGapPx = itemFontSize * 0.35;
+  const bodyIndentPx = markerWidthPx + markerGapPx;
+  const bodyLeftX = `${leftPct + (bodyIndentPx / context.viewport.width) * 100}%`;
+  const bodyWidthPx = Math.max(itemFontSize, textWidthPx - bodyIndentPx);
+  let itemY = startY;
 
   // List items with staggered animation
   for (let i = 0; i < items.length; i++) {
-    const y = startY + spacing * i;
-    const itemText = `${i + 1}.  ${items[i]}`;
+    const itemText = items[i]!;
+    const lineCount = estimateWrappedLineCount(itemText, itemFontSize, bodyWidthPx);
+    const animation = themedEntrance(context, 'text', {
+      type: 'fadeIn',
+      duration: 0.8,
+      delay: 0.3 + 0.3 * i,
+    });
+
+    layers.push({
+      type: 'text',
+      id: `item-${i}-marker`,
+      content: {
+        text: `${i + 1}.`,
+        style: {
+          fontSize: itemFontSize,
+          fontFamily: getThemeFont(context, 'body'),
+          color: theme.colors.text,
+          textAlign: 'right',
+          lineHeight: LIST_ITEM_LINE_HEIGHT,
+          shadow: shouldUseShadow(context),
+        },
+      },
+      position: {
+        x: leftX,
+        y: adjustY(`${itemY}%`, accentLayout),
+        width: markerWidthPx,
+      },
+      animation,
+    });
 
     layers.push({
       type: 'text',
@@ -128,21 +187,20 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
           fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.text,
           textAlign: 'left',
-          lineHeight: 1.2,
+          lineHeight: LIST_ITEM_LINE_HEIGHT,
           shadow: shouldUseShadow(context),
         },
       },
       position: {
-        x: leftX,
-        y: adjustY(`${y}%`, accentLayout),
-        width: accentLayout.textWidth,
+        x: bodyLeftX,
+        y: adjustY(`${itemY}%`, accentLayout),
+        width: bodyWidthPx,
       },
-      animation: themedEntrance(context, 'text', {
-        type: 'fadeIn',
-        duration: 0.8,
-        delay: 0.3 + 0.3 * i,
-      }),
+      animation,
     });
+
+    const itemHeightPx = lineCount * itemFontSize * LIST_ITEM_LINE_HEIGHT;
+    itemY += ((itemHeightPx + LIST_ITEM_GAP_PX) / context.viewport.height) * 100;
   }
 
   return layers;

package/src/doc/templates/metadata.ts

@@ -108,6 +108,16 @@ export const TEMPLATE_METADATA: Record<string, TemplateMetadata> = {
     description:
       'Renders sub-headings as connected nodes — edit visually as a node-and-edge diagram.',
   },
+  tree: {
+    label: 'Tree',
+    description:
+      'Renders an ASCII file-tree / outline fence as a filesystem-style treeview — edit as an outline.',
+  },
+  timeline: {
+    label: 'Timeline',
+    description:
+      'Plots events across one or more horizontal tracks with callouts and optional branching links.',
+  },
   layout: {
     label: 'Layout',
     description:

package/src/doc/templates/persistentLayers.ts

@@ -27,6 +27,7 @@ import type {
   ProgressIndicatorConfig,
 } from '../../schemas/BlockTemplates.js';
 import type { Theme } from '../../schemas/Theme.js';
+import { cloneData } from '../../internal/immutable.js';
 import { isPersistentLayerTemplate } from '../../schemas/BlockTemplates.js';
 import { oklchDarken, withAlpha } from '../../schemas/colorUtils.js';
 
@@ -415,9 +416,9 @@ function expandProgressIndicator(config: ProgressIndicatorConfig): Layer {
  * Expand a single persistent layer (template or raw) to raw Layer(s).
  */
 export function expandPersistentLayer(layer: PersistentLayer, theme?: Theme): Layer[] {
-  // If already a raw Layer, return as-is
+  // If already a raw Layer, return an owned copy.
   if (!isPersistentLayerTemplate(layer)) {
-    return [layer as Layer];
+    return [cloneData(layer as Layer)];
   }
 
   const template = layer as PersistentLayerTemplate;
@@ -466,128 +467,6 @@ export function expandPersistentLayers(
   );
 }
 
-// ============================================
-// Style Presets (legacy helper — prefer theme.persistentLayers)
-// ============================================
-
-/** Legacy style preset names. Prefer using `Theme.persistentLayers` directly. */
-export type DocStylePreset = 'minimal' | 'documentary' | 'branded' | 'cinematic' | 'clean';
-
-/**
- * Get a PersistentLayerConfig from a style preset.
- *
- * @param preset - Style preset name
- * @param articleTitle - Article title for title caption
- * @param heroSrc - Optional hero image for cinematic style
- */
-export function getDocStyleConfig(
-  preset: DocStylePreset,
-  articleTitle: string,
-  heroSrc?: string,
-  subtitle?: string,
-): PersistentLayerConfig {
-  switch (preset) {
-    case 'minimal':
-      return {};
-
-    case 'documentary':
-      return {
-        bottomLayers: [
-          {
-            template: 'gradientBackground',
-            config: { type: 'gradientBackground', preset: 'dark-vignette' },
-          },
-        ],
-        topLayers: [
-          {
-            template: 'titleCaption',
-            config: {
-              type: 'titleCaption',
-              title: articleTitle,
-              subtitle,
-              position: 'bottom-left',
-              fontSize: 24,
-              showThumbnail: !!heroSrc,
-              thumbnailSrc: heroSrc,
-            },
-          },
-        ],
-      };
-
-    case 'branded':
-      return {
-        bottomLayers: [
-          {
-            template: 'gradientBackground',
-            config: { type: 'gradientBackground', preset: 'cool-blue' },
-          },
-        ],
-        topLayers: [
-          {
-            template: 'titleCaption',
-            config: {
-              type: 'titleCaption',
-              title: articleTitle,
-              subtitle,
-              position: 'bottom-left',
-              fontSize: 26,
-              showThumbnail: !!heroSrc,
-              thumbnailSrc: heroSrc,
-            },
-          },
-        ],
-      };
-
-    case 'cinematic':
-      return {
-        bottomLayers: heroSrc
-          ? [
-              {
-                template: 'imageBackground',
-                config: {
-                  type: 'imageBackground',
-                  src: heroSrc,
-                  blur: 12,
-                  opacity: 0.3,
-                  ambientMotion: 'zoomIn',
-                },
-              },
-            ]
-          : [
-              {
-                template: 'gradientBackground',
-                config: { type: 'gradientBackground', preset: 'radial-dark' },
-              },
-            ],
-        topLayers: [
-          {
-            template: 'titleCaption',
-            config: {
-              type: 'titleCaption',
-              title: articleTitle,
-              subtitle,
-              position: 'bottom-right',
-              fontSize: 22,
-            },
-          },
-        ],
-      };
-
-    case 'clean':
-      return {
-        bottomLayers: [
-          {
-            template: 'solidBackground',
-            config: { type: 'solidBackground', color: '#1a202c' },
-          },
-        ],
-      };
-
-    default:
-      return {};
-  }
-}
-
 /**
  * Get persistent layers from a Theme. Returns the theme's baked-in
  * persistentLayers config, or an empty config when the theme has none.
@@ -625,7 +504,7 @@ export function resolvePersistentLayers(
 /**
  * Compose a block's layers between pre-expanded persistent bottom/top
  * layers, honoring the per-block `useBottomLayer` / `useTopLayer` opt-outs.
- * Single shared implementation for `expandDocBlocks` and `getLayers`.
+ * Shared persistent-layer primitive used by `materializeBlockLayers`.
  */
 export function wrapWithPersistentLayers(
   layers: Layer[],
@@ -636,5 +515,12 @@ export function wrapWithPersistentLayers(
   if (bottomLayers.length === 0 && topLayers.length === 0) return layers;
   const useBottom = block.useBottomLayer !== false;
   const useTop = block.useTopLayer !== false;
-  return [...(useBottom ? bottomLayers : []), ...layers, ...(useTop ? topLayers : [])];
+  // Each expanded block owns its persistent layers. This prevents a renderer
+  // (or a later timing/style pass) from mutating the caller's config or a
+  // sibling block through a shared layer reference.
+  return [
+    ...(useBottom ? bottomLayers.map((layer) => cloneData(layer)) : []),
+    ...layers,
+    ...(useTop ? topLayers.map((layer) => cloneData(layer)) : []),
+  ];
 }

package/src/doc/templates/registry.ts

@@ -0,0 +1,88 @@
+/** Runtime registry composition for built-in and document-scoped templates. */
+
+import type { Layer } from '../../schemas/Doc.js';
+import type {
+  TemplateBlock,
+  TemplateContext,
+  TemplateRegistry,
+} from '../../schemas/BlockTemplates.js';
+import type { CustomTemplateDefinition } from '../../schemas/CustomTemplates.js';
+import { makeCustomTemplateFn } from './customTemplate.js';
+
+import { titleBlock } from './titleBlock.js';
+import { sectionHeader } from './sectionHeader.js';
+import { statHighlight } from './statHighlight.js';
+import { quoteBlock } from './quoteBlock.js';
+import { factCard } from './factCard.js';
+import { twoColumn } from './twoColumn.js';
+import { dateEvent } from './dateEvent.js';
+import { imageWithCaption } from './imageWithCaption.js';
+import { leftFeature, rightFeature } from './featureBlock.js';
+import { mapBlock } from './mapBlock.js';
+import { fullBleedQuote } from './fullBleedQuote.js';
+import { listBlock } from './listBlock.js';
+import { photoGrid } from './photoGrid.js';
+import { definitionCard } from './definitionCard.js';
+import { comparisonBar } from './comparisonBar.js';
+import { pullQuote } from './pullQuote.js';
+import { videoWithCaption } from './videoWithCaption.js';
+import { videoPullQuote } from './videoPullQuote.js';
+import { dataTable } from './dataTable.js';
+import { diagramBlock } from './diagramBlock.js';
+import { treeBlock } from './treeBlock.js';
+import { timelineBlock } from './timelineBlock.js';
+import { drawingBlock } from './drawingBlock.js';
+import { layoutBlock } from './layoutBlock.js';
+
+/** Built-in templates keyed by the ids used in document annotations. */
+export const templateRegistry: TemplateRegistry = {
+  title: titleBlock,
+  sectionHeader,
+  statHighlight,
+  quote: quoteBlock,
+  factCard,
+  twoColumn,
+  dateEvent,
+  imageWithCaption,
+  leftFeature,
+  rightFeature,
+  map: mapBlock,
+  fullBleedQuote,
+  list: listBlock,
+  photoGrid,
+  definitionCard,
+  comparisonBar,
+  pullQuote,
+  videoWithCaption,
+  videoPullQuote,
+  dataTable,
+  diagram: diagramBlock,
+  tree: treeBlock,
+  timeline: timelineBlock,
+  layout: layoutBlock,
+  drawing: drawingBlock,
+};
+
+/** Broad runtime view used after a template name has selected its function. */
+export type RuntimeTemplateRegistry = Record<
+  string,
+  (input: TemplateBlock, context: TemplateContext) => Layer[]
+>;
+
+/** Merge document-scoped templates without mutating the built-in registry. */
+export function buildRegistry(
+  custom?: readonly CustomTemplateDefinition[],
+): RuntimeTemplateRegistry {
+  const merged: RuntimeTemplateRegistry = {
+    ...(templateRegistry as unknown as RuntimeTemplateRegistry),
+  };
+  if (custom) {
+    for (const definition of custom) {
+      if (merged[definition.name]) continue;
+      merged[definition.name] = makeCustomTemplateFn(
+        definition,
+      ) as unknown as RuntimeTemplateRegistry[string];
+    }
+  }
+  return merged;
+}

package/src/doc/templates/templateNames.ts

@@ -0,0 +1,22 @@
+/** Canonical aliases for historical template ids. Kept dependency-free. */
+export const TEMPLATE_ALIASES: Readonly<Record<string, string>> = Object.freeze({
+  titleBlock: 'title',
+  quoteBlock: 'quote',
+  mapBlock: 'map',
+  listBlock: 'list',
+  diagramBlock: 'diagram',
+  diagramNode: 'diagram',
+});
+
+/** Resolve a historical template id to its canonical registry key. */
+export function resolveTemplateName(name: string): string {
+  return TEMPLATE_ALIASES[name] ?? name;
+}
+
+/** Templates that consume their child headings rather than rendering them. */
+export const CONTAINER_TEMPLATES: ReadonlySet<string> = new Set(['diagram', 'drawing', 'layout']);
+
+/** True when `name` (or its alias) consumes child blocks. */
+export function isContainerTemplate(name: string | undefined): boolean {
+  return !!name && CONTAINER_TEMPLATES.has(resolveTemplateName(name));
+}