@bendyline/squisq 1.5.1 → 2.0.0

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));
+}