@bendyline/squisq 1.4.1 → 1.5.1

package/src/recommend/templates.ts

@@ -251,6 +251,30 @@ function recommendedNamesForProfile(profile: BlockContentProfile): string[] {
   return Array.from(names);
 }
 
+/**
+ * Deterministic single-template choice for an unannotated heading block,
+ * from strong content signals only. Returns `undefined` when no signal is
+ * decisive — the caller keeps its structural default (`sectionHeader`).
+ *
+ * Precedence favors the most specific/structured content: a table beats
+ * an image beats a blockquote beats a stat-looking line. `blockIndex`
+ * alternates left/right feature composition for single-image blocks so a
+ * run of image sections doesn't stack the same layout.
+ *
+ * Used by `markdownToDoc`'s auto template picking (see its `autoTemplates`
+ * option); the multi-candidate `recommendTemplatesForBlock` below serves
+ * the editor's template-picker UI instead.
+ */
+export function pickAutoTemplate(profile: BlockContentProfile, blockIndex = 0): string | undefined {
+  if (profile.hasTable) return 'dataTable';
+  if (profile.imageCount >= 2) return 'photoGrid';
+  if (profile.hasImage) return blockIndex % 2 === 0 ? 'leftFeature' : 'rightFeature';
+  if (profile.hasBlockquote) return 'quote';
+  if (profile.hasNumberHighlight) return 'statHighlight';
+  if (profile.hasList) return 'list';
+  return undefined;
+}
+
 /**
  * Split a flat list of template names into a "Recommended" bucket
  * (matches the active block's content profile) and a "rest" bucket

package/src/schemas/BlockTemplates.ts

@@ -20,7 +20,7 @@
  * - imageWithCaption: Image with text overlay
  */
 
-import type { Layer, Block, Transition, MapTileStyle, MapMarker } from './Doc.js';
+import type { Layer, Block, Transition, MapTileStyle, MapMarker, MarkerStyle } from './Doc.js';
 import type { ViewportConfig, ViewportOrientation } from './Viewport.js';
 import type { LayoutHints } from './LayoutStrategy.js';
 import type { Theme } from './Theme.js';
@@ -110,6 +110,12 @@ interface BaseTemplateBlock {
    * Used with sourceStartTime to precisely position the block.
    */
   sourceDuration?: number;
+  /**
+   * Per-block override for the theme's photographic image grade
+   * (`theme.style.imageTreatment`). `'none'` opts this block's imagery out;
+   * a treatment type forces that grade regardless of the theme.
+   */
+  imageTreatment?: 'none' | 'mono' | 'duotone' | 'warm' | 'cool';
 }
 
 /**
@@ -470,6 +476,78 @@ export interface VideoPullQuoteInput extends BaseTemplateBlock {
   };
 }
 
+/**
+ * Diagram block - renders child headings as a node-and-edge diagram.
+ *
+ * Unlike other templates, the diagram template reads its content from
+ * the parent block's `children` (passed via `context.children`) — each
+ * child heading becomes a node, positioned by its `x`/`y` and connected
+ * by its `connectsTo`. Per-diagram options on this input control overall
+ * appearance; per-node data lives on the child blocks themselves.
+ */
+export interface DiagramBlockInput extends BaseTemplateBlock {
+  template: 'diagram';
+  /** Optional diagram title displayed above the canvas. */
+  title?: string;
+  /** Color scheme for nodes and edges. */
+  colorScheme?: ColorScheme;
+  /** Node shape style (default: 'rounded'). */
+  nodeShape?: 'rounded' | 'rect' | 'pill';
+  /** Edge routing (default: 'curved'). */
+  edgeStyle?: 'curved' | 'straight' | 'orthogonal';
+  /** Marker at each edge's start (default: 'none'). */
+  startStyle?: MarkerStyle;
+  /** Marker at each edge's end (default: 'arrow'). */
+  endStyle?: MarkerStyle;
+  /** Edge line style (default: 'solid'). */
+  lineStyle?: 'solid' | 'dashed' | 'dotted';
+}
+
+/**
+ * Free-form 2D canvas block (`layout`). Like `drawing`/`diagram`, the
+ * `layout` template is a children-driven container: each child heading is
+ * one absolutely-positioned layer (`{[text …]}` / `{[rectangle …]}` /
+ * `{[image …]}`), read from `context.children`. A text box's content is the
+ * child's body markdown. Backed by the `layoutBlock` template.
+ *
+ * (Legacy documents stored layers as a base64-JSON `layers=` param on the
+ * heading; the editor auto-migrates those to child sub-blocks on first edit.)
+ */
+export interface RawLayersInput extends BaseTemplateBlock {
+  template: 'layout';
+}
+
+/**
+ * Drawing block — renders child headings as free-form shapes on a canvas.
+ *
+ * Like `diagram`, the drawing template reads its content from the parent
+ * block's `children` (passed via `context.children`). Each child heading
+ * is a shape: its `{[shape …]}` annotation names the primitive
+ * (`rectangle`/`rect`, `circle`, `line`, `arrow`, `path`, `text`) and
+ * carries geometry/style as params; its `{#id}` makes it referenceable;
+ * its heading text is the shape label and its body text an optional
+ * sublabel. Connectors (`line`/`arrow` with `from`/`to`) join shapes by id.
+ *
+ * Coordinates are author-defined units; the template fits the bounding box
+ * of all shapes to the viewport (same scaling as `diagram`), so authors
+ * don't have to think in absolute pixels.
+ *
+ * Legacy drawings authored visually persist their `Layer[]` as a base64
+ * `layers="…"` Pandoc param instead of children; the template decodes and
+ * returns those directly when no children are present (see `drawingBlock`).
+ */
+export interface DrawingBlockInput extends BaseTemplateBlock {
+  template: 'drawing';
+  /** Optional title displayed above the canvas. */
+  title?: string;
+  /** Color scheme for shapes that don't pin their own fill/stroke. */
+  colorScheme?: ColorScheme;
+  /** Default fill for shapes that don't specify one (default: 'none'). */
+  fill?: string;
+  /** Default stroke for shapes that don't specify one (default: theme text). */
+  stroke?: string;
+}
+
 /**
  * Data table - renders a themed table with headers and rows.
  * Ideal for structured data, comparisons, and reference information.
@@ -511,7 +589,10 @@ export type TemplateBlock =
   | PullQuoteInput
   | VideoWithCaptionInput
   | VideoPullQuoteInput
-  | DataTableInput;
+  | DataTableInput
+  | DiagramBlockInput
+  | DrawingBlockInput
+  | RawLayersInput;
 
 /**
  * A block can be either a raw Block or a TemplateBlock.
@@ -548,6 +629,20 @@ export interface TemplateContext {
   orientation: ViewportOrientation;
   /** Layout hints for this orientation */
   layout: LayoutHints;
+  /**
+   * The block's direct children (set by `getLayers` when the block has
+   * `children`). Most templates ignore this; aggregate templates like
+   * `diagram` consume it to render each child as part of their output.
+   */
+  children?: Block[];
+  /**
+   * The source block being expanded. Used by user-defined custom
+   * templates so the token resolver can substitute `{title}`,
+   * `{content}`, `{children}`, and `{image:N}` against the block's
+   * data at render time. Built-in templates ignore this and rely on
+   * their typed `input` parameters instead.
+   */
+  block?: Block;
 }
 
 /**
@@ -560,6 +655,10 @@ export function createTemplateContext(
   viewport: ViewportConfig = VIEWPORT_PRESETS.landscape,
 ): TemplateContext {
   const orientation = getViewportOrientation(viewport);
+  // Theme renderStyle may override individual layout hints (e.g. a theme
+  // that wants a lower primaryY across every template).
+  const overrides = theme.renderStyle.layoutOverrides;
+  const baseLayout = getLayoutHints(orientation);
   return {
     theme,
     blockIndex,
@@ -567,7 +666,7 @@ export function createTemplateContext(
     viewport,
     fontScale: calculateFontScale(viewport),
     orientation,
-    layout: getLayoutHints(orientation),
+    layout: overrides ? { ...baseLayout, ...overrides } : baseLayout,
   };
 }
 
@@ -647,7 +746,9 @@ export type PersistentLayerTemplateType =
   | 'solidBackground' // Solid color fill
   | 'gradientBackground' // CSS gradient or preset
   | 'imageBackground' // Blurred/faded hero image
-  | 'patternBackground' // Subtle pattern (dots, grid)
+  | 'patternBackground' // Subtle pattern (dots, grid, diagonal, noise/grain)
+  | 'vignette' // Soft radial edge darkening (top layer)
+  | 'ambientGradient' // Slowly drifting surface gradient (bottom layer)
   | 'titleCaption' // Article title in corner
   | 'cornerBranding' // Logo or text badge
   | 'progressIndicator'; // Bar/dots showing position
@@ -660,6 +761,8 @@ export type PersistentLayerTemplateConfig =
   | GradientBackgroundConfig
   | ImageBackgroundConfig
   | PatternBackgroundConfig
+  | VignetteConfig
+  | AmbientGradientConfig
   | TitleCaptionConfig
   | CornerBrandingConfig
   | ProgressIndicatorConfig;
@@ -718,6 +821,32 @@ export interface PatternBackgroundConfig {
   scale?: number;
 }
 
+/**
+ * Soft radial vignette (top layer) — transparent center darkening toward
+ * the frame edges. The classic film-look framing device.
+ */
+export interface VignetteConfig {
+  type: 'vignette';
+  /** Edge darkness 0-1 (default 0.3). */
+  strength?: number;
+  /** Vignette color (default black). */
+  color?: string;
+}
+
+/**
+ * Slowly drifting surface gradient (bottom layer). Colors default to the
+ * theme's surface family at expansion time.
+ */
+export interface AmbientGradientConfig {
+  type: 'ambientGradient';
+  /** Gradient start color. */
+  from?: string;
+  /** Gradient end color. */
+  to?: string;
+  /** Drift loop duration in seconds (default 40). */
+  duration?: number;
+}
+
 // ============================================
 // Overlay Layer Configs
 // ============================================

package/src/schemas/CustomTemplates.ts

@@ -0,0 +1,126 @@
+/**
+ * Custom Templates Schema
+ *
+ * User-defined block layout templates. The author designs a visual
+ * layout once (in the editor's TemplateDesigner) and saves it as a
+ * `CustomTemplateDefinition`. The definition lives either in the
+ * document's frontmatter (per-doc, portable, ships with the markdown)
+ * or in the user's local library (cross-doc reuse via localStorage).
+ *
+ * A custom template's content is just a `Layer[]` — the same shape that
+ * built-in templates emit at expansion time. The novel bit is
+ * *placeholder tokens*: TextLayer / ImageLayer content fields may carry
+ * strings like `{title}`, `{content}`, `{children}`, or `{image:N}`
+ * that the resolver (see `doc/templates/tokens/resolveTokens.ts`)
+ * substitutes against the source Block at render time.
+ *
+ * Responsiveness model: every numeric position field in `layers` is
+ * stored as a `%`-string relative to `viewport`, so the same template
+ * renders correctly at any of Squisq's viewport presets (landscape,
+ * portrait, square). The `viewport` field itself is purely an
+ * authoring-time reference — it tells the designer canvas which aspect
+ * ratio to mount with, and the thumbnail renderer which viewBox to use.
+ */
+
+import type { Layer } from './Doc.js';
+
+/**
+ * Iteration directive for a custom-template layer.
+ *
+ * A layer that carries a `repeat` is cloned once per item of a source
+ * collection at render time (see `resolveTokens`). The clones are laid
+ * out in a row or column, offset from the base position by the layer's
+ * own width/height plus `gap`, and each clone resolves per-item tokens
+ * (`{item}`, `{item:src}`, `{item:label}`, `{index}`) against its item.
+ */
+export interface LayerRepeat {
+  /**
+   * Which of the source Block's collections to iterate:
+   *   - `images`    — every image in the block body (alt + url)
+   *   - `children`  — child block titles
+   *   - `listItems` — top-level list-item text in the block body
+   */
+  source: 'images' | 'children' | 'listItems';
+
+  /**
+   * Layout axis for the clones. `column` (default) stacks them
+   * vertically (offsets `position.y`); `row` lays them out horizontally
+   * (offsets `position.x`).
+   */
+  direction?: 'row' | 'column';
+
+  /**
+   * Extra spacing added between consecutive clones, in the same unit as
+   * the layer's `width`/`height`. Defaults to 24.
+   */
+  gap?: number;
+
+  /** Cap on the number of clones rendered (omit for "all items"). */
+  max?: number;
+}
+
+/**
+ * A custom-template layer: a normal render `Layer` that may additionally
+ * carry a `repeat` directive. This is a strict superset of the core
+ * `Layer` type used only inside `CustomTemplateDefinition.layers`; the
+ * resolver strips `repeat` before emitting the final `Layer[]`, so the
+ * core `Layer` type is never widened.
+ */
+export type CustomTemplateLayer = Layer & { repeat?: LayerRepeat };
+
+/**
+ * A single user-defined template. Stored in `Doc.customTemplates`
+ * (frontmatter-backed) or in the user's local library.
+ */
+export interface CustomTemplateDefinition {
+  /**
+   * Stable id used in heading annotations (`### Foo {[name]}`). Must be
+   * a slug — lowercase alphanumerics, hyphens. The picker enforces
+   * uniqueness within a (doc + library) merged namespace.
+   */
+  name: string;
+
+  /** Human-readable label shown in the template picker. */
+  label: string;
+
+  /** Optional one-sentence description for the picker card. */
+  description?: string;
+
+  /**
+   * Authoring viewport — the canvas size the designer drew against.
+   * Stored so the designer and thumbnail renderer can reproduce the
+   * same canvas. Layer positions are stored as `%`-strings, so the
+   * actual render-time viewport can differ from this without breaking
+   * the layout. Defaults to 1920×1080 landscape.
+   */
+  viewport: {
+    width: number;
+    height: number;
+  };
+
+  /**
+   * The visual content. Every `position.x` / `position.y` /
+   * `position.width` / `position.height` should be a `%`-string at
+   * save time (the designer's normalizePositions step enforces this).
+   *
+   * Tokens supported (grammar v2):
+   *   - TextLayer.content.text — `{title}`, `{content}`, `{children}`,
+   *     `{image:N}` (Nth image's alt text), `{attr:key}` (block
+   *     attribute), plus a pipe default on any token
+   *     (`{attr:subtitle|Untitled}`).
+   *   - ImageLayer.content.src — `{image:N}` (the URL) and `{attr:key}`,
+   *     with pipe defaults (`{image:1|fallback.jpg}`).
+   *   - Inside a layer with `repeat`, per-item tokens: `{item}`,
+   *     `{item:src}`, `{item:label}`, `{index}` (1-based).
+   *
+   * A layer may carry a `repeat` directive (see {@link LayerRepeat}) to
+   * be cloned once per item of a source collection.
+   */
+  layers: CustomTemplateLayer[];
+}
+
+/**
+ * Tag value for the YAML frontmatter key that carries inlined custom
+ * template definitions. Exported so the markdown bridge stays in sync.
+ */
+export const FRONTMATTER_CUSTOM_TEMPLATES_KEY = 'squisq-custom-templates';