@bendyline/squisq 1.5.2 → 2.0.0

package/src/doc/asciiDiagram/index.ts

@@ -0,0 +1,38 @@
+/**
+ * ASCII diagram codec: detect / parse / render box-and-line art, plus
+ * mapping helpers between the grid model and the diagram canvas model.
+ *
+ * The fence text is the source of truth end-to-end: the editor parses it
+ * live for an interactive canvas and re-renders it after each semantic
+ * edit; the doc pipeline derives `templateData.nodes`/`edges` from it so
+ * preview/player/exports show the same diagram.
+ */
+
+export { parseAsciiDiagram, parseAsciiDiagramWithStats } from './parse.js';
+export type { AsciiParseStats } from './parse.js';
+export { renderAsciiDiagram } from './render.js';
+export type { RenderAsciiDiagramOptions } from './render.js';
+export {
+  ASCII_DIAGRAM_FENCE_LANGS,
+  detectAsciiDiagram,
+  isAsciiDiagramFence,
+  isEligibleAsciiFenceLang,
+  isExplicitDiagramLang,
+} from './detect.js';
+export type { DetectDiagramOptions } from './detect.js';
+export { repairAsciiDiagram, isRepairableDiagram } from './repair.js';
+export type { RepairResult } from './repair.js';
+export {
+  asciiCellToCanvas,
+  asciiDiagramFromBlocks,
+  asciiDiagramFromTemplateData,
+  asciiDiagramToTemplateData,
+  canvasToAsciiCell,
+} from './mapping.js';
+export { ASCII_CHAR_H, ASCII_CHAR_W } from './types.js';
+export type {
+  AsciiDiagram,
+  AsciiDiagramDetection,
+  AsciiDiagramEdge,
+  AsciiDiagramNode,
+} from './types.js';

package/src/doc/asciiDiagram/mapping.ts

@@ -0,0 +1,225 @@
+/**
+ * Mapping between the grid-native ASCII diagram model and the diagram
+ * canvas / template model (canvas units, the same space as `Block.x`/`y`).
+ *
+ * Quantization uses plain `round()` per axis — monotonic and local, so a
+ * small canvas nudge either changes nothing or moves exactly one cell
+ * (cluster-based schemes flap under small moves and churn the art).
+ */
+
+import type {
+  DiagramEdgeAnchor,
+  DiagramTemplateEdge,
+  DiagramTemplateNode,
+} from '../../schemas/BlockTemplates.js';
+import type { Block } from '../../schemas/Doc.js';
+import { computeDiagramLayout } from '../templates/diagramLayout.js';
+import {
+  ASCII_CHAR_H,
+  ASCII_CHAR_W,
+  type AsciiDiagram,
+  type AsciiDiagramEdge,
+  type AsciiDiagramNode,
+} from './types.js';
+
+export function asciiCellToCanvas(col: number, row: number): { x: number; y: number } {
+  return { x: col * ASCII_CHAR_W, y: row * ASCII_CHAR_H };
+}
+
+export function canvasToAsciiCell(x: number, y: number): { col: number; row: number } {
+  return {
+    col: Math.max(0, Math.round(x / ASCII_CHAR_W)),
+    row: Math.max(0, Math.round(y / ASCII_CHAR_H)),
+  };
+}
+
+/** Grid model → template/canvas model (`templateData.nodes`/`edges`). */
+export function asciiDiagramToTemplateData(diagram: AsciiDiagram): {
+  nodes: DiagramTemplateNode[];
+  edges: DiagramTemplateEdge[];
+} {
+  const nodes: DiagramTemplateNode[] = diagram.nodes.map((n) => ({
+    id: n.id,
+    label: n.label,
+    ...asciiCellToCanvas(n.col, n.row),
+    w: n.wCols * ASCII_CHAR_W,
+    h: n.hRows * ASCII_CHAR_H,
+    ...(n.containerId ? { container: n.containerId } : {}),
+  }));
+  const anchors = inferEdgeAnchors(nodes, diagram.edges);
+  const edges: DiagramTemplateEdge[] = diagram.edges.map((e, index) => ({
+    source: e.source,
+    target: e.target,
+    ...(e.label ? { label: e.label } : {}),
+    ...(e.directed ? {} : { directed: false }),
+    ...anchors[index],
+    routing: 'orthogonal',
+  }));
+  return { nodes, edges };
+}
+
+interface EdgeAnchorPair {
+  sourceAnchor: DiagramEdgeAnchor;
+  targetAnchor: DiagramEdgeAnchor;
+}
+
+/**
+ * Recover the visual intent carried by orthogonal ASCII art. Fan-out ports
+ * spread across the source face; fan-in ports spread across the target face.
+ * A single endpoint stays centered on its facing side.
+ */
+function inferEdgeAnchors(
+  nodes: readonly DiagramTemplateNode[],
+  edges: readonly AsciiDiagramEdge[],
+): EdgeAnchorPair[] {
+  const nodeById = new Map(nodes.map((node) => [node.id, node]));
+  const pairs = edges.map((edge) => {
+    const source = nodeById.get(edge.source);
+    const target = nodeById.get(edge.target);
+    if (!source || !target) {
+      return {
+        sourceAnchor: { side: 'right' as const, offset: 0.5 },
+        targetAnchor: { side: 'left' as const, offset: 0.5 },
+      };
+    }
+    const sourceW = source.w ?? ASCII_CHAR_W * 12;
+    const sourceH = source.h ?? ASCII_CHAR_H * 3;
+    const targetW = target.w ?? ASCII_CHAR_W * 12;
+    const targetH = target.h ?? ASCII_CHAR_H * 3;
+    const dx = target.x + targetW / 2 - (source.x + sourceW / 2);
+    const dy = target.y + targetH / 2 - (source.y + sourceH / 2);
+    const horizontalDistance = Math.abs(dx) / Math.max(1, (sourceW + targetW) / 2);
+    const verticalDistance = Math.abs(dy) / Math.max(1, (sourceH + targetH) / 2);
+    if (verticalDistance >= horizontalDistance) {
+      return dy >= 0
+        ? {
+            sourceAnchor: { side: 'bottom' as const, offset: 0.5 },
+            targetAnchor: { side: 'top' as const, offset: 0.5 },
+          }
+        : {
+            sourceAnchor: { side: 'top' as const, offset: 0.5 },
+            targetAnchor: { side: 'bottom' as const, offset: 0.5 },
+          };
+    }
+    return dx >= 0
+      ? {
+          sourceAnchor: { side: 'right' as const, offset: 0.5 },
+          targetAnchor: { side: 'left' as const, offset: 0.5 },
+        }
+      : {
+          sourceAnchor: { side: 'left' as const, offset: 0.5 },
+          targetAnchor: { side: 'right' as const, offset: 0.5 },
+        };
+  });
+
+  distributeOffsets(pairs, edges, nodes, 'source');
+  distributeOffsets(pairs, edges, nodes, 'target');
+  return pairs;
+}
+
+function distributeOffsets(
+  pairs: EdgeAnchorPair[],
+  edges: readonly AsciiDiagramEdge[],
+  nodes: readonly DiagramTemplateNode[],
+  endpoint: 'source' | 'target',
+): void {
+  const nodeById = new Map(nodes.map((node) => [node.id, node]));
+  const groups = new Map<string, number[]>();
+  for (let index = 0; index < edges.length; index++) {
+    const edge = edges[index];
+    const anchor = endpoint === 'source' ? pairs[index].sourceAnchor : pairs[index].targetAnchor;
+    const nodeId = endpoint === 'source' ? edge.source : edge.target;
+    const key = `${nodeId}:${anchor.side}`;
+    const group = groups.get(key) ?? [];
+    group.push(index);
+    groups.set(key, group);
+  }
+  for (const indexes of groups.values()) {
+    if (indexes.length < 2) continue;
+    const side =
+      endpoint === 'source'
+        ? pairs[indexes[0]].sourceAnchor.side
+        : pairs[indexes[0]].targetAnchor.side;
+    indexes.sort((a, b) => {
+      const oppositeA = nodeById.get(endpoint === 'source' ? edges[a].target : edges[a].source);
+      const oppositeB = nodeById.get(endpoint === 'source' ? edges[b].target : edges[b].source);
+      const axisA = side === 'top' || side === 'bottom' ? (oppositeA?.x ?? 0) : (oppositeA?.y ?? 0);
+      const axisB = side === 'top' || side === 'bottom' ? (oppositeB?.x ?? 0) : (oppositeB?.y ?? 0);
+      return axisA - axisB || a - b;
+    });
+    indexes.forEach((edgeIndex, rank) => {
+      const anchor =
+        endpoint === 'source' ? pairs[edgeIndex].sourceAnchor : pairs[edgeIndex].targetAnchor;
+      anchor.offset = (rank + 1) / (indexes.length + 1);
+    });
+  }
+}
+
+/** Template/canvas model → grid model, quantizing positions and sizes. */
+export function asciiDiagramFromTemplateData(
+  nodes: readonly DiagramTemplateNode[],
+  edges: readonly DiagramTemplateEdge[],
+  options: { style?: 'unicode' | 'ascii' } = {},
+): AsciiDiagram {
+  const ids = new Set(nodes.map((n) => n.id));
+  const outNodes: AsciiDiagramNode[] = nodes.map((n) => {
+    const { col, row } = canvasToAsciiCell(n.x, n.y);
+    const labelLines = n.label.length > 0 ? n.label.split('\n') : [];
+    const innerW = labelLines.reduce((w, l) => Math.max(w, l.length), 0);
+    const wCols =
+      typeof n.w === 'number' ? Math.max(3, Math.round(n.w / ASCII_CHAR_W)) : innerW + 4;
+    const hRows =
+      typeof n.h === 'number' ? Math.max(3, Math.round(n.h / ASCII_CHAR_H)) : labelLines.length + 2;
+    return {
+      id: n.id,
+      label: n.label,
+      col,
+      row,
+      wCols: Math.max(wCols, 3),
+      hRows: Math.max(hRows, 3),
+      ...(n.container && ids.has(n.container) && n.container !== n.id
+        ? { containerId: n.container }
+        : {}),
+    };
+  });
+  return {
+    nodes: outNodes,
+    edges: edges
+      .filter((e) => ids.has(e.source) && ids.has(e.target))
+      .map((e) => ({
+        source: e.source,
+        target: e.target,
+        ...(e.label ? { label: e.label } : {}),
+        directed: e.directed !== false,
+      })),
+    style: options.style ?? 'unicode',
+    warnings: [],
+  };
+}
+
+/**
+ * Legacy heading-based diagram children → ASCII diagram model. Used to
+ * migrate `### Node {#id x= y= connectsTo=}` sections to ASCII fences;
+ * positions run through the shared `computeDiagramLayout` so unpinned
+ * children get the same grid placement as the legacy renderer.
+ */
+export function asciiDiagramFromBlocks(
+  children: readonly Block[],
+  options: { style?: 'unicode' | 'ascii' } = {},
+): AsciiDiagram {
+  const layout = computeDiagramLayout(children);
+  const nodes: DiagramTemplateNode[] = layout.nodes.map((n) => ({
+    id: n.id,
+    label: n.label,
+    x: n.x,
+    y: n.y,
+  }));
+  const edges: DiagramTemplateEdge[] = layout.edges.map((e) => ({
+    source: e.source,
+    target: e.target,
+    ...(e.type ? { label: e.type } : {}),
+  }));
+  const diagram = asciiDiagramFromTemplateData(nodes, edges, options);
+  diagram.warnings.push(...layout.warnings);
+  return diagram;
+}