@bendyline/squisq 1.4.1 → 1.5.1

package/src/doc/templates/layoutLayout.ts

@@ -0,0 +1,243 @@
+/**
+ * Layout layout — pure derivation of positioned layers from a `layout`
+ * block's child sub-blocks. The layout counterpart to `drawingLayout.ts`,
+ * with two deliberate differences:
+ *
+ *  - **Absolute** positioning. Each child's `x`/`y`/`width`/`height` are
+ *    used as-is in viewport units (no auto-grid, no fit-to-viewport
+ *    scaling). A layout is a free-form canvas; authors place things where
+ *    they want them.
+ *  - **Text content lives in the child body.** A `{[text …]}` child's
+ *    paragraphs/lists/marks under its heading become the text — readable
+ *    markdown rather than an encoded blob. (`content.html` is filled by the
+ *    editor for rich on-canvas rendering; SSR uses the plain `content.text`.)
+ *
+ * Each child heading is one layer: `### {#id} {[<type> x=.. y=.. …]}`.
+ * Children are emitted in document order, so the first child is the
+ * back-most layer (painters' order).
+ */
+
+import type { Layer, ShapeLayer, TextLayer, PathLayer, ImageLayer } from '../../schemas/Doc.js';
+import { extractPlainText } from '../../markdown/utils.js';
+import { normalizeShapeKind } from './drawingLayout.js';
+import { shapePath } from '../utils/shapeGeometry.js';
+
+export interface LayoutLayersResult {
+  layers: Layer[];
+  warnings: string[];
+}
+
+export interface LayoutLayerDefaults {
+  /**
+   * Default ink — text color and path/line stroke — used when the author
+   * omits `color=`/`stroke=`. `layoutBlock` passes the theme text color so
+   * un-styled text stays legible on dark themes; the editor's scene canvas
+   * omits it and gets the dark-slate default that suits its fixed light
+   * surface.
+   */
+  ink?: string;
+}
+
+/** Fallback ink for callers that don't supply defaults (editor scene canvas). */
+const DEFAULT_INK = '#1e293b';
+
+/** Minimal Block shape this derivation reads (subset of `Block`). */
+interface LayoutChildBlock {
+  id: string;
+  template?: string;
+  templateOverrides?: Record<string, string>;
+  title?: string;
+  contents?: import('../../markdown/types.js').MarkdownNode[];
+}
+
+const DEFAULT_TEXT = { w: 300, h: 80 };
+const DEFAULT_SHAPE = { w: 160, h: 90 };
+const DEFAULT_IMAGE = { w: 320, h: 240 };
+
+/**
+ * Map a layout block's children → positioned layers. Pure: same children
+ * always produce the same layers.
+ */
+export function computeLayoutLayers(
+  children: readonly LayoutChildBlock[],
+  _viewport: { width: number; height: number },
+  defaults: LayoutLayerDefaults = {},
+): LayoutLayersResult {
+  const ink = defaults.ink ?? DEFAULT_INK;
+  const layers: Layer[] = [];
+  const warnings: string[] = [];
+
+  for (const child of children) {
+    const params = child.templateOverrides ?? {};
+    const annotation = (child.template ?? '').toLowerCase();
+    const x = numParam(params, 'x') ?? 0;
+    const y = numParam(params, 'y') ?? 0;
+
+    if (annotation === 'image' || annotation === 'img') {
+      const src = strParam(params, 'src');
+      if (!src) {
+        warnings.push(`Layout image "${child.id}" has no src= and was skipped`);
+        continue;
+      }
+      const layer: ImageLayer = {
+        id: child.id,
+        type: 'image',
+        position: {
+          x,
+          y,
+          width: numParam(params, 'width') ?? DEFAULT_IMAGE.w,
+          height: numParam(params, 'height') ?? DEFAULT_IMAGE.h,
+        },
+        content: {
+          src,
+          alt: strParam(params, 'alt') ?? '',
+          ...(strParam(params, 'fit')
+            ? { fit: strParam(params, 'fit') as 'cover' | 'contain' | 'fill' }
+            : {}),
+        },
+      };
+      layers.push(layer);
+      continue;
+    }
+
+    const kind = normalizeShapeKind(child.template);
+    if (!kind) {
+      warnings.push(
+        `Layout child "${child.id}" is not a layer (annotation "${child.template ?? '—'}") and was skipped`,
+      );
+      continue;
+    }
+
+    if (kind === 'text') {
+      const text = bodyText(child) || child.title || '';
+      const layer: TextLayer = {
+        id: child.id,
+        type: 'text',
+        position: {
+          x,
+          y,
+          width: numParam(params, 'width') ?? DEFAULT_TEXT.w,
+          height: numParam(params, 'height') ?? DEFAULT_TEXT.h,
+        },
+        content: { text, style: textStyleFromParams(params, ink) },
+      };
+      layers.push(layer);
+      continue;
+    }
+
+    const width = numParam(params, 'width') ?? numParam(params, 'w') ?? DEFAULT_SHAPE.w;
+    const height = numParam(params, 'height') ?? numParam(params, 'h') ?? DEFAULT_SHAPE.h;
+
+    if (kind === 'rect' || kind === 'circle') {
+      const shape: ShapeLayer = {
+        id: child.id,
+        type: 'shape',
+        position: { x, y, width, height },
+        content: {
+          shape: kind,
+          ...(strParam(params, 'fill') ? { fill: strParam(params, 'fill') } : {}),
+          ...(strParam(params, 'stroke') ? { stroke: strParam(params, 'stroke') } : {}),
+          ...(numParam(params, 'strokeWidth') != null
+            ? { strokeWidth: numParam(params, 'strokeWidth') }
+            : {}),
+          ...(strParam(params, 'borderStyle')
+            ? { borderStyle: strParam(params, 'borderStyle') as 'solid' | 'dashed' | 'dotted' }
+            : {}),
+          ...(kind === 'rect' && numParam(params, 'borderRadius') != null
+            ? { borderRadius: numParam(params, 'borderRadius') }
+            : {}),
+        },
+      };
+      layers.push(shape);
+      continue;
+    }
+
+    // line / arrow / path / named polygon → PathLayer (absolute geometry).
+    const diagonal = `M ${round(x)} ${round(y)} L ${round(x + width)} ${round(y + height)}`;
+    let d = diagonal;
+    let pathFill = 'none';
+    let endMarker: 'none' | 'arrow' = 'none';
+    if (kind === 'path') {
+      d = strParam(params, 'd') ?? diagonal;
+      pathFill = strParam(params, 'fill') ?? 'none';
+    } else if (kind === 'arrow') {
+      endMarker = 'arrow';
+    } else if (kind !== 'line') {
+      d = shapePath(kind, x, y, width, height) ?? diagonal;
+      pathFill = strParam(params, 'fill') ?? 'none';
+    }
+    const path: PathLayer = {
+      id: child.id,
+      type: 'path',
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+      content: {
+        d,
+        stroke: strParam(params, 'stroke') ?? ink,
+        strokeWidth: numParam(params, 'strokeWidth') ?? 2,
+        fill: pathFill,
+        ...(strParam(params, 'dasharray') ? { dasharray: strParam(params, 'dasharray') } : {}),
+        ...(endMarker !== 'none' ? { endMarker } : {}),
+      },
+    };
+    layers.push(path);
+  }
+
+  return { layers, warnings };
+}
+
+/** Build a TextStyle from a text layer's annotation params. */
+function textStyleFromParams(
+  params: Record<string, string>,
+  ink: string,
+): TextLayer['content']['style'] {
+  const style: TextLayer['content']['style'] = {
+    fontSize: numParam(params, 'fontSize') ?? 32,
+    color: strParam(params, 'color') ?? ink,
+  };
+  const fontFamily = strParam(params, 'fontFamily');
+  if (fontFamily) style.fontFamily = fontFamily;
+  const fontWeight = strParam(params, 'fontWeight');
+  if (fontWeight === 'bold' || fontWeight === 'normal') style.fontWeight = fontWeight;
+  const fontStyle = strParam(params, 'fontStyle');
+  if (fontStyle === 'italic' || fontStyle === 'normal') style.fontStyle = fontStyle;
+  const align = strParam(params, 'align');
+  if (align === 'left' || align === 'center' || align === 'right') style.textAlign = align;
+  const valign = strParam(params, 'valign');
+  if (valign === 'top' || valign === 'middle' || valign === 'bottom') style.verticalAlign = valign;
+  const lineHeight = numParam(params, 'lineHeight');
+  if (lineHeight != null) style.lineHeight = lineHeight;
+  const padding = numParam(params, 'padding');
+  if (padding != null) style.padding = padding;
+  const background = strParam(params, 'background');
+  if (background) style.background = background;
+  return style;
+}
+
+/** Read a raw string param (trims a trailing comma — `x=21, y=25` tolerated). */
+function strParam(params: Record<string, string>, key: string): string | undefined {
+  const raw = params[key];
+  if (raw == null) return undefined;
+  const v = raw.replace(/,\s*$/, '').trim();
+  return v.length > 0 ? v : undefined;
+}
+
+/** Coerce a numeric param, tolerating a trailing comma. Undefined on failure. */
+function numParam(params: Record<string, string>, key: string): number | undefined {
+  const v = strParam(params, key);
+  if (v == null) return undefined;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/** Plain text of a block's body content. */
+function bodyText(block: LayoutChildBlock): string {
+  if (!block.contents || block.contents.length === 0) return '';
+  return block.contents
+    .map((node) => extractPlainText(node))
+    .join('\n')
+    .trim();
+}
+
+function round(n: number): number {
+  return Math.round(n * 100) / 100;
+}

package/src/doc/templates/listBlock.ts

@@ -10,8 +10,13 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { ListBlockInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { getThemeFont } from '../utils/themeUtils.js';
+import {
+  getThemeFont,
+  shouldUseShadow,
+  themedEntrance,
+  themedFontSize,
+  themedImageTreatment,
+} from '../utils/themeUtils.js';
 import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
 
 export function listBlock(input: ListBlockInput, context: TemplateContext): Layer[] {
@@ -27,8 +32,8 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
   // Get layout adjustments if accent image is present
   const accentLayout = accentImage ? getAccentLayout(accentImage.position) : DEFAULT_LAYOUT;
 
-  const titleFontSize = scaledFontSize(44, context, true);
-  const itemFontSize = scaledFontSize(34, context, false);
+  const titleFontSize = themedFontSize(44, context, true);
+  const itemFontSize = themedFontSize(34, context, false);
 
   const layers: Layer[] = [
     // Background — gradient
@@ -45,11 +50,27 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
 
   // Add accent image layers
   if (accentImage) {
-    layers.push(...createAccentLayers(accentImage, input.id));
+    layers.push(
+      ...createAccentLayers(
+        accentImage,
+        input.id,
+        themedImageTreatment(context, input.imageTreatment),
+      ),
+    );
   }
 
+  // Left edge of the text column — derived from the center+width pair so
+  // the title and items share one left axis instead of a centered title
+  // floating over a left-aligned column. Falls back to a safe 8% if the
+  // layout strings ever turn out unparseable (they're authored, but
+  // 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%';
+
   // Title if provided
-  const startY = title ? 30 : 22;
+  const startY = title ? 34 : 26;
   if (title) {
     layers.push({
       type: 'text',
@@ -61,35 +82,36 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
           fontFamily: getThemeFont(context, 'title'),
           fontWeight: 'bold',
           color: theme.colors.text,
-          textAlign: 'center',
-          shadow: !!accentImage,
+          textAlign: 'left',
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
-        x: accentLayout.textCenterX,
-        y: adjustY('16%', accentLayout),
-        anchor: 'center',
+        x: leftX,
+        y: adjustY('20%', accentLayout),
+        width: accentLayout.textWidth,
       },
-      animation: { type: 'fadeIn', duration: 1 },
+      animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 1 }),
     });
   }
 
-  // Left edge of the text column — derived from the center+width pair so
-  // items sit flush with the column's left margin instead of being
-  // centered. Falls back to a safe 8% if the layout strings ever turn
-  // out unparseable (they're authored, but 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%';
-
-  // Calculate vertical spacing for items. We keep the available band
-  // (startY → endY) but use a tighter line-height (1.2) so wrapped
-  // items don't bleed into the next entry as aggressively as the old
-  // 1.4 value did.
-  const endY = 80;
-  const spacing = items.length > 1 ? (endY - startY) / (items.length - 1) : 0;
+  // 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;
 
   // List items with staggered animation
   for (let i = 0; i < items.length; i++) {
@@ -107,7 +129,7 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
           color: theme.colors.text,
           textAlign: 'left',
           lineHeight: 1.2,
-          shadow: !!accentImage,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
@@ -115,7 +137,11 @@ export function listBlock(input: ListBlockInput, context: TemplateContext): Laye
         y: adjustY(`${y}%`, accentLayout),
         width: accentLayout.textWidth,
       },
-      animation: { type: 'fadeIn', duration: 0.8, delay: 0.3 + 0.3 * i },
+      animation: themedEntrance(context, 'text', {
+        type: 'fadeIn',
+        duration: 0.8,
+        delay: 0.3 + 0.3 * i,
+      }),
     });
   }
 

package/src/doc/templates/mapBlock.ts

@@ -14,8 +14,8 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { MapBlockInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { getThemeFont } from '../utils/themeUtils.js';
+import { getThemeFont, shouldUseShadow, themedFontSize } from '../utils/themeUtils.js';
+import { withAlpha } from '../../schemas/colorUtils.js';
 import { mapAmbientMotion } from './accentImage.js';
 
 export function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[] {
@@ -32,8 +32,8 @@ export function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[
   const { theme, layout } = context;
 
   // Scale font sizes for viewport
-  const titleFontSize = scaledFontSize(64, context, true);
-  const captionFontSize = scaledFontSize(32, context, false);
+  const titleFontSize = themedFontSize(64, context, true);
+  const captionFontSize = themedFontSize(32, context, false);
 
   // Determine animation based on ambientMotion setting
   const mapAnimation = mapAmbientMotion(ambientMotion);
@@ -56,17 +56,21 @@ export function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[
     },
   ];
 
+  // Overlay bands are tinted from the theme background so the theme text
+  // color on them stays readable in light and dark themes alike; they
+  // fade out toward the map so the band doesn't read as a hard seam.
+  const bg = theme.colors.background;
+
   // Add title overlay if provided
   if (title) {
-    // Gradient overlay at top for title readability
     layers.push({
       type: 'shape',
       id: 'title-overlay',
       content: {
         shape: 'rect',
-        fill: 'rgba(0,0,0,0.6)',
+        fill: `linear-gradient(180deg, ${withAlpha(bg, 0.85)} 0%, ${withAlpha(bg, 0.6)} 70%, ${withAlpha(bg, 0)} 100%)`,
       },
-      position: { x: 0, y: 0, width: '100%', height: '18%' },
+      position: { x: 0, y: 0, width: '100%', height: '20%' },
     });
 
     // Title text - positioned at top of slide
@@ -81,7 +85,7 @@ export function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[
           fontWeight: 'bold',
           color: theme.colors.text,
           textAlign: 'center',
-          shadow: true,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
@@ -96,15 +100,14 @@ export function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[
 
   // Add caption if provided
   if (caption) {
-    // Gradient overlay at bottom for caption readability
     layers.push({
       type: 'shape',
       id: 'caption-overlay',
       content: {
         shape: 'rect',
-        fill: 'rgba(0,0,0,0.6)',
+        fill: `linear-gradient(0deg, ${withAlpha(bg, 0.85)} 0%, ${withAlpha(bg, 0.6)} 70%, ${withAlpha(bg, 0)} 100%)`,
       },
-      position: { x: 0, y: '82%', width: '100%', height: '18%' },
+      position: { x: 0, y: '80%', width: '100%', height: '20%' },
     });
 
     // Caption text
@@ -118,7 +121,7 @@ export function mapBlock(input: MapBlockInput, context: TemplateContext): Layer[
           fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.text,
           textAlign: 'center',
-          shadow: true,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {

package/src/doc/templates/metadata.ts

@@ -0,0 +1,120 @@
+/**
+ * Canonical, framework-free UI metadata for every built-in block template.
+ *
+ * This is the single source of truth for the human-readable label and the
+ * one-sentence description of each template id in {@link templateRegistry}.
+ * The editor's `TemplatePicker` renders its gallery from this map (joining
+ * each id with a locally-defined SVG icon, which can't live in this
+ * framework-free package), so a template only has to be added here and to
+ * `templateRegistry` for it to surface in the editor.
+ *
+ * `templateMetadata.test.ts` asserts this map and `templateRegistry` stay
+ * exactly 1:1 — adding a template to one without the other fails the build.
+ *
+ * Order matters: pickers iterate this object's insertion order, so it doubles
+ * as the canonical gallery order.
+ */
+
+export interface TemplateMetadata {
+  /** Human-readable label shown in pickers (e.g. "Image with Caption"). */
+  label: string;
+  /** One-sentence description of when to reach for this template. */
+  description: string;
+}
+
+export const TEMPLATE_METADATA: Record<string, TemplateMetadata> = {
+  title: {
+    label: 'Title',
+    description: 'A bold opening slide with large title text, perfect for covers and chapters.',
+  },
+  sectionHeader: {
+    label: 'Section Header',
+    description: 'A clean section break with a prominent title and optional subtitle.',
+  },
+  statHighlight: {
+    label: 'Stat Highlight',
+    description: 'Showcases a single key number or metric with supporting context.',
+  },
+  quote: {
+    label: 'Quote',
+    description: 'Displays a stylized pull quote with decorative marks and attribution.',
+  },
+  factCard: {
+    label: 'Fact Card',
+    description: 'Presents a focused fact or insight with a labeled header and body text.',
+  },
+  twoColumn: {
+    label: 'Two Column',
+    description: 'Divides the slide into two equal side-by-side content columns.',
+  },
+  dateEvent: {
+    label: 'Date Event',
+    description: 'Highlights a date-based event or milestone with a prominent date display.',
+  },
+  imageWithCaption: {
+    label: 'Image with Caption',
+    description: 'Displays a full-bleed image with an optional caption below.',
+  },
+  leftFeature: {
+    label: 'Left Feature',
+    description: 'Image on the left, title and body text stacked on the right.',
+  },
+  rightFeature: {
+    label: 'Right Feature',
+    description: 'Image on the right, title and body text stacked on the left.',
+  },
+  map: {
+    label: 'Map',
+    description: 'Embeds an interactive map centered on a geographic location.',
+  },
+  fullBleedQuote: {
+    label: 'Full Bleed Quote',
+    description: 'A full-width quote that spans the entire slide for maximum impact.',
+  },
+  list: {
+    label: 'List',
+    description: 'Renders a bulleted or numbered list in a clean, card-style layout.',
+  },
+  photoGrid: {
+    label: 'Photo Grid',
+    description: 'Arranges multiple photos in a 2×2 or 3×3 mosaic grid.',
+  },
+  definitionCard: {
+    label: 'Definition Card',
+    description: 'Shows a term and its definition in a structured, dictionary-style card.',
+  },
+  comparisonBar: {
+    label: 'Comparison Bar',
+    description: 'Visualizes two or more values side-by-side with labeled horizontal bars.',
+  },
+  pullQuote: {
+    label: 'Pull Quote',
+    description: 'A stylized pull quote with large decorative marks and centered text.',
+  },
+  videoWithCaption: {
+    label: 'Video with Caption',
+    description: 'Embeds a video player with an optional caption below.',
+  },
+  videoPullQuote: {
+    label: 'Video Pull Quote',
+    description: 'Combines a video panel with a highlighted pull quote side-by-side.',
+  },
+  dataTable: {
+    label: 'Data Table',
+    description: 'Renders tabular data in a clean, styled table with a header row.',
+  },
+  diagram: {
+    label: 'Diagram',
+    description:
+      'Renders sub-headings as connected nodes — edit visually as a node-and-edge diagram.',
+  },
+  layout: {
+    label: 'Layout',
+    description:
+      "Free-form 2D canvas — drag layers into place. Use for one-off block layouts that don't fit a template.",
+  },
+  drawing: {
+    label: 'Drawing',
+    description: 'Free-form sketches — draw shapes, paths, and text directly on a 2D surface.',
+  },
+};