@bendyline/squisq 1.4.0 → 1.5.0

package/src/doc/templates/definitionCard.ts

@@ -10,8 +10,15 @@
 
 import type { Layer } from '../../schemas/Doc.js';
 import type { DefinitionCardInput, TemplateContext } from '../../schemas/BlockTemplates.js';
-import { scaledFontSize } from '../../schemas/BlockTemplates.js';
-import { resolveColorScheme, getThemeFont } from '../utils/themeUtils.js';
+import {
+  resolveColorScheme,
+  getThemeFont,
+  shouldUseShadow,
+  themedEntrance,
+  themedFontSize,
+  themedSurfaceGradient,
+  themedImageTreatment,
+} from '../utils/themeUtils.js';
 import { createAccentLayers, getAccentLayout, adjustY, DEFAULT_LAYOUT } from './accentImage.js';
 import { createBackgroundLayer } from './captionUtils.js';
 
@@ -23,20 +30,21 @@ export function definitionCard(input: DefinitionCardInput, context: TemplateCont
   // Get layout adjustments if accent image is present
   const accentLayout = accentImage ? getAccentLayout(accentImage.position) : DEFAULT_LAYOUT;
 
-  const termFontSize = scaledFontSize(72, context, true);
-  const defFontSize = scaledFontSize(32, context, false);
-  const originFontSize = scaledFontSize(22, context, false);
+  const termFontSize = themedFontSize(72, context, true);
+  const defFontSize = themedFontSize(32, context, false);
+  const originFontSize = themedFontSize(22, context, false);
 
-  const layers: Layer[] = [
-    createBackgroundLayer(
-      'bg',
-      `linear-gradient(145deg, #1e2030 0%, ${theme.colors.background} 100%)`,
-    ),
-  ];
+  const layers: Layer[] = [createBackgroundLayer('bg', themedSurfaceGradient(context, 145))];
 
   // Add accent image layers
   if (accentImage) {
-    layers.push(...createAccentLayers(accentImage, input.id));
+    layers.push(
+      ...createAccentLayers(
+        accentImage,
+        input.id,
+        themedImageTreatment(context, input.imageTreatment),
+      ),
+    );
   }
 
   // Term — large, accent-colored
@@ -51,7 +59,7 @@ export function definitionCard(input: DefinitionCardInput, context: TemplateCont
         fontWeight: 'bold',
         color: colors.text,
         textAlign: 'center',
-        shadow: !!accentImage,
+        shadow: shouldUseShadow(context),
       },
     },
     position: {
@@ -59,7 +67,7 @@ export function definitionCard(input: DefinitionCardInput, context: TemplateCont
       y: adjustY('30%', accentLayout),
       anchor: 'center',
     },
-    animation: { type: 'fadeIn', duration: 1.5 },
+    animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 1.5 }),
   });
 
   // Horizontal separator line
@@ -92,7 +100,7 @@ export function definitionCard(input: DefinitionCardInput, context: TemplateCont
         textAlign: 'center',
         lineHeight: 1.6,
         maxLines: 4,
-        shadow: !!accentImage,
+        shadow: shouldUseShadow(context),
       },
     },
     position: {
@@ -101,7 +109,7 @@ export function definitionCard(input: DefinitionCardInput, context: TemplateCont
       width: accentLayout.textWidth,
       anchor: 'center',
     },
-    animation: { type: 'fadeIn', duration: 1, delay: 0.8 },
+    animation: themedEntrance(context, 'text', { type: 'fadeIn', duration: 1, delay: 0.8 }),
   });
 
   // Origin if provided
@@ -116,12 +124,12 @@ export function definitionCard(input: DefinitionCardInput, context: TemplateCont
           fontFamily: getThemeFont(context, 'body'),
           color: theme.colors.textMuted,
           textAlign: 'center',
-          shadow: !!accentImage,
+          shadow: shouldUseShadow(context),
         },
       },
       position: {
         x: accentLayout.textCenterX,
-        y: adjustY('78%', accentLayout),
+        y: adjustY('70%', accentLayout),
         anchor: 'center',
       },
       animation: { type: 'fadeIn', duration: 0.8, delay: 1.5 },

package/src/doc/templates/diagramBlock.ts

@@ -0,0 +1,204 @@
+/**
+ * Diagram block template.
+ *
+ * Renders the parent block's children as a node-and-edge diagram:
+ * - Each child becomes a rounded-rect node card with its title as label.
+ * - Each `child.connectsTo` entry becomes a path edge (cubic-bezier curve
+ *   with an arrowhead at the target end).
+ * - Children with `x`/`y` set are placed at those coordinates; the rest
+ *   are auto-laid out below in a square-ish grid (see `diagramLayout.ts`).
+ *
+ * Layout coordinates from `x=`/`y=` are author-defined units. The
+ * template computes a bounding box of all nodes and scales it to fit
+ * the block's viewport with padding, so users don't have to think about
+ * absolute pixel ranges.
+ */
+
+import type { Layer, ShapeLayer, TextLayer, PathLayer, MarkerStyle } from '../../schemas/Doc.js';
+import type { DiagramBlockInput, TemplateContext } from '../../schemas/BlockTemplates.js';
+import { resolveColorScheme, getThemeFont, themedFontSize } from '../utils/themeUtils.js';
+import { clipEndpoints, connectorPath, lineStyleDasharray } from '../utils/shapeGeometry.js';
+import { computeDiagramLayout, type DiagramNodePosition } from './diagramLayout.js';
+
+const NODE_WIDTH = 180;
+const NODE_HEIGHT = 64;
+const PADDING = 80;
+
+export function diagramBlock(input: DiagramBlockInput, context: TemplateContext): Layer[] {
+  const { theme, viewport, children = [] } = context;
+  const colors = resolveColorScheme(context, input.colorScheme ?? 'blue');
+
+  const layout = computeDiagramLayout(children);
+  if (layout.nodes.length === 0) {
+    // Empty diagram — render a single hint label so the block has visible content.
+    return [
+      {
+        type: 'text',
+        id: 'diagram-empty',
+        content: {
+          text: input.title ?? 'Empty diagram',
+          style: {
+            fontSize: themedFontSize(36, context, true),
+            fontFamily: getThemeFont(context, 'title'),
+            color: theme.colors.textMuted,
+            textAlign: 'center',
+          },
+        },
+        position: { x: '50%', y: '50%', anchor: 'center' },
+      },
+    ];
+  }
+
+  // Compute the bounding box of all nodes in author coordinates.
+  const minX = Math.min(...layout.nodes.map((n) => n.x));
+  const maxX = Math.max(...layout.nodes.map((n) => n.x + NODE_WIDTH));
+  const minY = Math.min(...layout.nodes.map((n) => n.y));
+  const maxY = Math.max(...layout.nodes.map((n) => n.y + NODE_HEIGHT));
+
+  // Available area in viewport pixels (after reserving space for the title, if any).
+  const titleHeight = input.title ? 120 : 0;
+  const availW = Math.max(1, viewport.width - PADDING * 2);
+  const availH = Math.max(1, viewport.height - PADDING * 2 - titleHeight);
+  const contentW = Math.max(1, maxX - minX);
+  const contentH = Math.max(1, maxY - minY);
+
+  // Uniform scale so the diagram fits both dimensions. Small diagrams are
+  // allowed to grow (everything here is vector) up to 1.8× so a three-node
+  // flow doesn't render as a tiny cluster in an empty canvas; label fonts
+  // and strokes scale with the nodes, clamped so text never balloons.
+  const scale = Math.min(availW / contentW, availH / contentH, 1.8);
+  const fontAdj = Math.min(Math.max(scale, 1), 1.5);
+  const strokeW = Math.round(2 * fontAdj);
+
+  // Compute viewport-pixel coordinates of each node's top-left corner.
+  // The title and the scaled diagram are centered together as one group —
+  // a top-pinned title over a center-floated diagram split the block into
+  // two stranded pieces.
+  const scaledW = contentW * scale;
+  const scaledH = contentH * scale;
+  const groupTop = Math.max(PADDING / 2, (viewport.height - titleHeight - scaledH) / 2);
+  const offsetX = PADDING + (availW - scaledW) / 2;
+  const offsetY = groupTop + titleHeight;
+  const transform = (n: DiagramNodePosition): { x: number; y: number; w: number; h: number } => ({
+    x: offsetX + (n.x - minX) * scale,
+    y: offsetY + (n.y - minY) * scale,
+    w: NODE_WIDTH * scale,
+    h: NODE_HEIGHT * scale,
+  });
+
+  const layers: Layer[] = [];
+
+  // Optional title above the diagram.
+  if (input.title) {
+    layers.push({
+      type: 'text',
+      id: 'diagram-title',
+      content: {
+        text: input.title,
+        style: {
+          fontSize: themedFontSize(40, context, true),
+          fontFamily: getThemeFont(context, 'title'),
+          fontWeight: 'bold',
+          color: theme.colors.text,
+          textAlign: 'center',
+        },
+      },
+      position: { x: '50%', y: groupTop + titleHeight / 2 - 16, anchor: 'center' },
+    });
+  }
+
+  // Position lookup by id for edge routing.
+  const positions = new Map<string, { cx: number; cy: number; rx: number; ry: number }>();
+  for (const node of layout.nodes) {
+    const t = transform(node);
+    positions.set(node.id, { cx: t.x + t.w / 2, cy: t.y + t.h / 2, rx: t.w / 2, ry: t.h / 2 });
+  }
+
+  // Edge styling (applies to all edges; per-edge styling lives on the nodes).
+  const startMarker: MarkerStyle = input.startStyle ?? 'none';
+  const endMarker: MarkerStyle = input.endStyle ?? 'arrow';
+  const edgeDash = lineStyleDasharray(input.lineStyle);
+
+  // Edges first so they sit behind nodes.
+  for (const edge of layout.edges) {
+    const a = positions.get(edge.source);
+    const b = positions.get(edge.target);
+    if (!a || !b) continue;
+    const { start, end } = clipEndpoints(a, b);
+    const pathLayer: PathLayer = {
+      type: 'path',
+      id: `edge-${edge.id}`,
+      content: {
+        d: connectorPath(input.edgeStyle ?? 'curved', start, end),
+        stroke: colors.text ?? theme.colors.primary,
+        strokeWidth: strokeW,
+        fill: 'none',
+        ...(edgeDash ? { dasharray: edgeDash } : {}),
+        ...(startMarker !== 'none' ? { startMarker } : {}),
+        ...(endMarker !== 'none' ? { endMarker } : {}),
+      },
+      position: { x: 0, y: 0, width: '100%', height: '100%' },
+    };
+    layers.push(pathLayer);
+
+    if (edge.type) {
+      // Connection-type label, floated just above the edge midpoint so the
+      // line never strikes through the text.
+      const mx = (a.cx + b.cx) / 2;
+      const my = (a.cy + b.cy) / 2;
+      const labelFontSize = themedFontSize(Math.round(18 * fontAdj), context, false);
+      const labelLayer: TextLayer = {
+        type: 'text',
+        id: `edge-label-${edge.id}`,
+        content: {
+          text: edge.type,
+          style: {
+            fontSize: labelFontSize,
+            fontFamily: getThemeFont(context, 'body'),
+            color: theme.colors.textMuted,
+            textAlign: 'center',
+          },
+        },
+        position: { x: mx, y: my - labelFontSize * 0.9, anchor: 'center' },
+      };
+      layers.push(labelLayer);
+    }
+  }
+
+  // Nodes (card + label) on top of edges.
+  for (const node of layout.nodes) {
+    const t = transform(node);
+    const card: ShapeLayer = {
+      type: 'shape',
+      id: `node-card-${node.id}`,
+      content: {
+        shape: 'rect',
+        fill: colors.bg ?? theme.colors.backgroundLight,
+        stroke: colors.text ?? theme.colors.primary,
+        strokeWidth: strokeW,
+        borderRadius: input.nodeShape === 'pill' ? t.h / 2 : 10,
+      },
+      position: { x: t.x, y: t.y, width: t.w, height: t.h },
+    };
+    layers.push(card);
+
+    const label: TextLayer = {
+      type: 'text',
+      id: `node-label-${node.id}`,
+      content: {
+        text: node.label,
+        style: {
+          fontSize: themedFontSize(Math.round(22 * fontAdj), context, false),
+          fontFamily: getThemeFont(context, 'body'),
+          fontWeight: 'bold',
+          color: colors.text ?? theme.colors.text,
+          textAlign: 'center',
+        },
+      },
+      position: { x: t.x + t.w / 2, y: t.y + t.h / 2, anchor: 'center', width: t.w },
+    };
+    layers.push(label);
+  }
+
+  return layers;
+}

package/src/doc/templates/diagramLayout.ts

@@ -0,0 +1,159 @@
+/**
+ * Diagram layout — shared between the read-only SVG render path
+ * (`diagramBlock` template) and the interactive editor (React Flow in
+ * `@bendyline/squisq-editor-react`). Same children + same options always
+ * produce the same node positions and edge list, so previews and the
+ * editor stay visually consistent.
+ *
+ * Layout rules:
+ * 1. Children with both `x` and `y` set keep their authored coordinates.
+ * 2. Children missing either coordinate are auto-placed in a square-ish
+ *    grid in declaration order, offset below the bounding box of the
+ *    explicitly-positioned children.
+ * 3. Edges come from each child's `connectsTo`. Targets that don't match
+ *    any sibling id are dropped (and counted in `warnings`).
+ */
+
+import type { Block, BlockConnection } from '../../schemas/Doc.js';
+
+export interface DiagramNodePosition {
+  /** Block id (matches `Block.id`). */
+  id: string;
+  /** Display label (block title or fallback to id). */
+  label: string;
+  /** Pixel x coordinate (canvas-relative). */
+  x: number;
+  /** Pixel y coordinate (canvas-relative). */
+  y: number;
+  /** True when the position came from `x=`/`y=` attributes; false when auto-laid out. */
+  pinned: boolean;
+  /** Optional `.class` tokens carried over from the heading. */
+  classes?: string[];
+}
+
+export interface DiagramEdge {
+  /** Synthetic stable edge id. */
+  id: string;
+  /** Source node id. */
+  source: string;
+  /** Target node id. */
+  target: string;
+  /** Connection type from `connectsTo=target:type` (used as edge label). */
+  type?: string;
+}
+
+export interface DiagramLayout {
+  nodes: DiagramNodePosition[];
+  edges: DiagramEdge[];
+  warnings: string[];
+}
+
+export interface DiagramLayoutOptions {
+  /** Horizontal grid pitch between auto-laid-out nodes. Default: 260 (node width 180 + 80 air). */
+  gapX?: number;
+  /** Vertical grid pitch between auto-laid-out nodes. Default: 140. */
+  gapY?: number;
+  /** Padding around the explicit-positions bounding box before the grid starts. Default: 80. */
+  gridPad?: number;
+  /** Origin x for the grid when no explicit nodes anchor it. Default: 80. */
+  gridOriginX?: number;
+  /** Origin y for the grid when no explicit nodes anchor it. Default: 80. */
+  gridOriginY?: number;
+}
+
+const DEFAULT_OPTS: Required<DiagramLayoutOptions> = {
+  gapX: 260,
+  gapY: 140,
+  gridPad: 80,
+  gridOriginX: 80,
+  gridOriginY: 80,
+};
+
+/**
+ * Compute node positions and edges for a diagram from a parent block's
+ * children. Pure function — same inputs always produce the same output.
+ */
+export function computeDiagramLayout(
+  children: readonly Block[],
+  options: DiagramLayoutOptions = {},
+): DiagramLayout {
+  const opts = { ...DEFAULT_OPTS, ...options };
+  const warnings: string[] = [];
+
+  // First pass: extract explicit positions, record which children still need a grid slot.
+  type Entry = { child: Block; pinned: boolean; x: number; y: number };
+  const entries: Entry[] = [];
+  const unpositionedIdx: number[] = [];
+
+  for (let i = 0; i < children.length; i++) {
+    const c = children[i];
+    const hasX = typeof c.x === 'number';
+    const hasY = typeof c.y === 'number';
+    if (hasX && hasY) {
+      entries.push({ child: c, pinned: true, x: c.x as number, y: c.y as number });
+    } else {
+      entries.push({ child: c, pinned: false, x: 0, y: 0 });
+      unpositionedIdx.push(i);
+    }
+  }
+
+  // Second pass: lay out unpositioned children in a square-ish grid.
+  if (unpositionedIdx.length > 0) {
+    const cols = Math.max(1, Math.ceil(Math.sqrt(unpositionedIdx.length)));
+    // Find the bottom-right of the pinned bounding box so the grid sits below it.
+    let baseX = opts.gridOriginX;
+    let baseY = opts.gridOriginY;
+    const pinned = entries.filter((e) => e.pinned);
+    if (pinned.length > 0) {
+      const minX = Math.min(...pinned.map((e) => e.x));
+      const maxY = Math.max(...pinned.map((e) => e.y));
+      baseX = minX;
+      baseY = maxY + opts.gridPad + opts.gapY;
+    }
+    unpositionedIdx.forEach((entryIdx, k) => {
+      const col = k % cols;
+      const row = Math.floor(k / cols);
+      entries[entryIdx].x = baseX + col * opts.gapX;
+      entries[entryIdx].y = baseY + row * opts.gapY;
+    });
+  }
+
+  // Third pass: emit nodes + the id-set used to validate edge targets.
+  const nodes: DiagramNodePosition[] = entries.map((e) => ({
+    id: e.child.id,
+    label: e.child.title ?? e.child.id,
+    x: e.x,
+    y: e.y,
+    pinned: e.pinned,
+    ...(e.child.classes && e.child.classes.length > 0 ? { classes: e.child.classes } : {}),
+  }));
+  const nodeIds = new Set(nodes.map((n) => n.id));
+
+  // Fourth pass: emit edges from each child's connectsTo, dropping ghosts.
+  const edges: DiagramEdge[] = [];
+  const seenEdgeIds = new Set<string>();
+  for (const child of children) {
+    if (!child.connectsTo) continue;
+    for (const conn of child.connectsTo) {
+      if (!nodeIds.has(conn.target)) {
+        warnings.push(`Edge from "${child.id}" to "${conn.target}" dropped: no such sibling node`);
+        continue;
+      }
+      const edgeId = makeEdgeId(child.id, conn);
+      if (seenEdgeIds.has(edgeId)) continue;
+      seenEdgeIds.add(edgeId);
+      edges.push({
+        id: edgeId,
+        source: child.id,
+        target: conn.target,
+        ...(conn.type ? { type: conn.type } : {}),
+      });
+    }
+  }
+
+  return { nodes, edges, warnings };
+}
+
+function makeEdgeId(source: string, conn: BlockConnection): string {
+  return conn.type ? `${source}->${conn.target}:${conn.type}` : `${source}->${conn.target}`;
+}