@yassimba/pi-loom-mermaid 0.2.0

package/src/loom-mermaid/graph-render.ts

@@ -0,0 +1,195 @@
+/**
+ * Entry points for the layered diagrams (flowchart, state, class, ER):
+ * choose what each node box holds, lay the graph out, paint it, orient it.
+ * Subgraphs recurse: each becomes a framed box holding its own canvas.
+ */
+
+import { Canvas } from './canvas.ts'
+import type { Edge, Node } from './graph.ts'
+import { Graph } from './graph.ts'
+import type { Limits } from './labels.ts'
+import { layout, type NodeExtra } from './layout.ts'
+import { orient, paint } from './paint.ts'
+
+/** A laid-out canvas, or `null` when the diagram is empty or over the cell cap. */
+export type CanvasResult = Canvas | null
+
+/** Flowchart and state diagrams: plain boxes, no extra content. */
+export function layoutFlowchart(graph: Graph, limits: Limits): CanvasResult {
+  const extras: NodeExtra[] = graph.nodes.map(() => ({ kind: 'plain' }))
+  const canvas = layoutCanvas(graph, extras, limits)
+  return canvas && orient(canvas, graph)
+}
+
+/** Class and ER diagrams: boxes divided into title / attribute / method rows. */
+export function layoutClass(graph: Graph, limits: Limits): CanvasResult {
+  const extras: NodeExtra[] = graph.nodes.map((node) => ({
+    kind: 'compartments',
+    sections: node.sections ?? [[node.label]],
+  }))
+  const canvas = layoutCanvas(graph, extras, limits)
+  return canvas && orient(canvas, graph)
+}
+
+// -------------------------------------------------------------------- groups
+
+/** An endpoint inside a scope: a plain node or a (proxied) subgraph. */
+interface ScopeItem {
+  group: boolean
+  i: number
+}
+
+/**
+ * Lay out a flowchart that uses `subgraph`.
+ *
+ * Each subgraph becomes a framed box holding its own independently laid-out
+ * canvas. An edge is drawn in the innermost scope containing both endpoints;
+ * one crossing a subgraph boundary attaches to the frame instead of the node.
+ */
+export function layoutGrouped(graph: Graph, limits: Limits): CanvasResult {
+  // A node whose id matches a subgraph id stands in for that subgraph.
+  const proxy = new Map<number, number>()
+  graph.groups.forEach((g, gi) => {
+    const ni = graph.index.get(g.id)
+    if (ni !== undefined) proxy.set(ni, gi)
+  })
+
+  const groupChain = (g: number | null): number[] => {
+    const chain: number[] = []
+    let cur = g
+    while (cur !== null) {
+      chain.push(cur)
+      cur = graph.groups[cur].parent
+    }
+    return chain.reverse()
+  }
+  const endpoint = (n: number): { item: ScopeItem; chain: number[] } => {
+    const gi = proxy.get(n)
+    return gi === undefined
+      ? { item: { group: false, i: n }, chain: groupChain(graph.nodeGroup[n]) }
+      : { item: { group: true, i: gi }, chain: groupChain(graph.groups[gi].parent) }
+  }
+
+  /** Edges bucketed by the scope that draws them; `null` is the top level. */
+  const scopeEdges = new Map<number | null, [ScopeItem, ScopeItem, number][]>()
+  const referenced = new Array<boolean>(graph.groups.length).fill(false)
+  graph.edges.forEach((e, ei) => {
+    const f = endpoint(e.from)
+    const t = endpoint(e.to)
+    let k = 0
+    while (k < f.chain.length && k < t.chain.length && f.chain[k] === t.chain[k]) k++
+    const scope = k === 0 ? null : f.chain[k - 1]
+    const fItem = f.chain.length > k ? { group: true, i: f.chain[k] } : f.item
+    const tItem = t.chain.length > k ? { group: true, i: t.chain[k] } : t.item
+    for (const item of [fItem, tItem]) {
+      if (item.group) referenced[item.i] = true
+    }
+    const list = scopeEdges.get(scope)
+    if (list) list.push([fItem, tItem, ei])
+    else scopeEdges.set(scope, [[fItem, tItem, ei]])
+  })
+
+  const directNodes = new Map<number | null, number[]>()
+  graph.nodeGroup.forEach((g, ni) => {
+    if (proxy.has(ni)) return
+    const list = directNodes.get(g)
+    if (list) list.push(ni)
+    else directNodes.set(g, [ni])
+  })
+
+  // Drop empty subgraphs, but keep any that an edge attaches to. Walked by
+  // the actual child relation: state `--` regions reparent earlier groups
+  // under later ones, so index order says nothing about depth.
+  const childGroups: number[][] = graph.groups.map(() => [])
+  graph.groups.forEach((g, gi) => {
+    if (g.parent !== null) childGroups[g.parent].push(gi)
+  })
+  const keep = new Array<boolean>(graph.groups.length).fill(false)
+  const visit = (gi: number): boolean => {
+    let kept = referenced[gi] || (directNodes.get(gi) ?? []).length > 0
+    for (const c of childGroups[gi]) if (visit(c)) kept = true
+    keep[gi] = kept
+    return kept
+  }
+  graph.groups.forEach((g, gi) => {
+    if (g.parent === null) visit(gi)
+  })
+
+  const canvas = buildScope(graph, null, scopeEdges, directNodes, keep, limits)
+  return canvas && orient(canvas, graph)
+}
+
+function buildScope(
+  graph: Graph,
+  scope: number | null,
+  scopeEdges: Map<number | null, [ScopeItem, ScopeItem, number][]>,
+  directNodes: Map<number | null, number[]>,
+  keep: boolean[],
+  limits: Limits,
+): CanvasResult {
+  const items: ScopeItem[] = (directNodes.get(scope) ?? []).map((i) => ({ group: false, i }))
+  const childGroups = graph.groups
+    .map((_, gi) => gi)
+    .filter((gi) => graph.groups[gi].parent === scope && keep[gi])
+  items.push(...childGroups.map((i) => ({ group: true, i })))
+
+  if (items.length === 0) return new Canvas(1, 1)
+
+  const nodeAt = new Map<number, number>()
+  const groupAt = new Map<number, number>()
+  const nodes: Node[] = []
+  const extras: NodeExtra[] = []
+  for (const item of items) {
+    ;(item.group ? groupAt : nodeAt).set(item.i, nodes.length)
+    if (!item.group) {
+      nodes.push({
+        label: graph.nodes[item.i].label,
+        shape: graph.nodes[item.i].shape,
+        classes: graph.nodes[item.i].classes,
+        href: graph.nodes[item.i].href,
+      })
+      extras.push({ kind: 'plain' })
+    } else {
+      const sub = buildScope(graph, item.i, scopeEdges, directNodes, keep, limits)
+      if (sub === null) return null
+      nodes.push({ label: graph.groups[item.i].label, shape: 'rect' })
+      extras.push({ kind: 'frame', sub })
+    }
+  }
+
+  const edges: Edge[] = []
+  for (const [f, t, ei] of scopeEdges.get(scope) ?? []) {
+    const fi = (f.group ? groupAt : nodeAt).get(f.i)
+    const ti = (t.group ? groupAt : nodeAt).get(t.i)
+    if (fi === undefined || ti === undefined) continue
+    const e = graph.edges[ei]
+    const collapsed: Edge = {
+      from: fi,
+      to: ti,
+      label: e.label,
+      headTo: e.headTo,
+      headFrom: e.headFrom,
+      line: e.line,
+    }
+    // Edges from (or to) different nodes inside one frame collapse onto
+    // the frame and become indistinguishable; draw them once.
+    const twin = (a: Edge, b: Edge): boolean =>
+      a.from === b.from && a.to === b.to && a.label === b.label && a.headTo === b.headTo && a.headFrom === b.headFrom && a.line === b.line
+    if ((f.group || t.group) && edges.some((x) => twin(x, collapsed))) continue
+    edges.push(collapsed)
+  }
+
+  // Layout only reads nodes/edges/dir, so a bare Graph carrying those is enough.
+  const synth = new Graph(graph.dir)
+  synth.nodes = nodes
+  synth.edges = edges
+  return layoutCanvas(synth, extras, limits)
+}
+
+/** Lay out and paint one scope. */
+function layoutCanvas(graph: Graph, extras: NodeExtra[], limits: Limits): CanvasResult {
+  const lay = layout(graph, extras, limits)
+  return lay === null ? null : paint(graph, extras, lay)
+}
+
+// ------------------------------------------------------------------- drawing

package/src/loom-mermaid/graph.ts

@@ -0,0 +1,205 @@
+/**
+ * The shared diagram model. Flowchart, state, class and ER sources all parse
+ * into a `Graph`; only sequence diagrams have their own model.
+ */
+
+import { asciiUpper } from './labels.ts'
+
+/** Caps that keep layout bounded; exceeding one drops the diagram to fallback. */
+export const MAX_NODES = 128
+export const MAX_EDGES = 512
+export const MAX_GROUPS = 24
+export const MAX_GROUP_DEPTH = 6
+/** Class members / ER attributes listed per box before eliding with `…`. */
+export const MAX_MEMBERS = 8
+
+export type Shape = 'rect' | 'round' | 'diamond'
+
+/** Decoration at one end of an edge. */
+export type Head =
+  | 'none'
+  | 'arrow'
+  | 'circle'
+  | 'cross'
+  | 'triangle'
+  | 'diamondFill'
+  | 'diamondOpen'
+
+export type LineKind = 'solid' | 'dotted' | 'thick'
+
+type Dir = 'down' | 'up' | 'right' | 'left'
+
+export interface Node {
+  label: string
+  shape: Shape
+  /**
+   * Compartment content for class and ER boxes, pre-formatted by the parser:
+   * one string per row, one array per compartment (title, attributes,
+   * methods). Absent on plain nodes; layout draws whatever is here verbatim,
+   * separated by horizontal rules.
+   */
+  sections?: string[][]
+  /**
+   * Author-assigned class names, from `:::name` or a `class A,B name`
+   * statement. The renderer never interprets them; the cells the node paints
+   * carry them out through `Span.classes`.
+   */
+  classes?: string[]
+  /**
+   * Link target from a `click A "url"` / `link A "url"` statement, carried
+   * out through `Span.href` the way classes are; `toAnsi` emits it as an
+   * OSC 8 hyperlink.
+   */
+  href?: string
+}
+
+export interface Edge {
+  from: number
+  to: number
+  label: string | null
+  /**
+   * Cardinalities (ER crow's-foot, class multiplicities), painted at their
+   * own end of the edge so position says which side a number belongs to.
+   */
+  cardFrom?: string
+  cardTo?: string
+  headTo: Head
+  headFrom: Head
+  line: LineKind
+}
+
+export interface Group {
+  id: string
+  label: string
+  parent: number | null
+}
+
+/** `LR`/`RL`/`BT` as written in a header or `direction` statement; else `down`. */
+export function parseDir(token: string): Dir {
+  switch (asciiUpper(token)) {
+    case 'LR':
+      return 'right'
+    case 'RL':
+      return 'left'
+    case 'BT':
+      return 'up'
+    default:
+      return 'down'
+  }
+}
+
+export class Graph {
+  nodes: Node[] = []
+  edges: Edge[] = []
+  index = new Map<string, number>()
+  groups: Group[] = []
+  /** Innermost subgraph each node was declared in, parallel to `nodes`. */
+  nodeGroup: (number | null)[] = []
+  curGroup: number | null = null
+  /**
+   * Set when a size cap was hit, naming the cap. The parser stops consuming
+   * statements and renders the prefix, warning about the truncation — a
+   * streamed diagram that outgrows a cap can never shrink back under it, so
+   * a stable truncated render beats flipping to the source box for good.
+   */
+  truncated: string | null = null
+  /**
+   * Source the grammar could not read and dropped. Parsing is lenient in
+   * every grammar: a statement either contributes what parsed or is dropped
+   * and recorded here, so the reader can tell a clean diagram from one that
+   * is missing something they wrote.
+   */
+  warnings: string[] = []
+  /** Parsed `classDef` declarations: name -> property map. */
+  classDefs: Record<string, Record<string, string>> = {}
+  dir: Dir = 'down'
+
+  constructor(dir: Dir = 'down') {
+    this.dir = dir
+  }
+
+  /**
+   * Index of `id`, creating the node if new. A later declaration carrying a
+   * label overwrites the placeholder one an edge created. Returns `null` once
+   * `MAX_NODES` is reached, which truncates the parse.
+   */
+  nodeIndex(id: string, label: string | null, shape: Shape): number | null {
+    const existing = this.index.get(id)
+    if (existing !== undefined) {
+      if (label !== null) {
+        this.nodes[existing].label = label
+        this.nodes[existing].shape = shape
+      }
+      return existing
+    }
+    if (this.nodes.length >= MAX_NODES) {
+      this.truncated ??= `node cap (${MAX_NODES}) reached`
+      return null
+    }
+    this.index.set(id, this.nodes.length)
+    this.nodes.push({ label: label ?? id, shape })
+    this.nodeGroup.push(this.curGroup)
+    return this.nodes.length - 1
+  }
+
+  /** Set a node's label without disturbing its shape, creating it if new. */
+  nodeLabel(id: string, label: string): number | null {
+    const existing = this.index.get(id)
+    if (existing !== undefined) {
+      this.nodes[existing].label = label
+      return existing
+    }
+    return this.nodeIndex(id, label, 'round')
+  }
+
+  /** Attach an author class name to a node, ignoring a repeat. */
+  addClass(idx: number, name: string): void {
+    const node = this.nodes[idx]
+    node.classes ??= []
+    if (!node.classes.includes(name)) node.classes.push(name)
+  }
+
+  /**
+   * Apply collected `[ids, names]` class assignments. Run after the statement
+   * walk so a `class A,B name` (or `:::` tag) may precede the nodes it names;
+   * unknown ids are ignored.
+   */
+  applyClasses(assignments: [string[], string[]][]): void {
+    for (const [ids, names] of assignments) {
+      for (const id of ids) {
+        const idx = this.index.get(id.trim())
+        if (idx === undefined) continue
+        for (const name of names) {
+          if (name.trim() !== '') this.addClass(idx, name.trim())
+        }
+      }
+    }
+  }
+
+  /** Apply `[id, url]` link targets; the last one per id wins, unknown ids
+   * are ignored. Deferred like `applyClasses`, for the same ordering reason. */
+  applyHrefs(hrefs: [string, string][]): void {
+    for (const [id, url] of hrefs) {
+      const idx = this.index.get(id.trim())
+      if (idx !== undefined) this.nodes[idx].href = url
+    }
+  }
+
+  /**
+   * Record an unreadable statement; the diagram renders without it. Skipped
+   * once truncated — a cap-caused parse failure is not the statement's fault.
+   */
+  drop(st: string): void {
+    if (this.truncated === null) this.warnings.push(`dropped, unreadable statement: "${st}"`)
+  }
+
+  /** Append an edge, or flag `truncated` when `MAX_EDGES` is reached. */
+  pushEdge(edge: Edge): boolean {
+    if (this.edges.length >= MAX_EDGES) {
+      this.truncated ??= `edge cap (${MAX_EDGES}) reached`
+      return false
+    }
+    this.edges.push(edge)
+    return true
+  }
+}

package/src/loom-mermaid/index.ts

@@ -0,0 +1,78 @@
+import type { Canvas } from './canvas.ts'
+import { LIMITS, stripControls } from './labels.ts'
+import { type Diagram, diagramFor } from './registry.ts'
+import { frontmatterTitle } from './statements.ts'
+import type { MermaidArt } from './types.ts'
+import { stringWidth } from './width.ts'
+
+export { type AnsiTheme, classSgr, DEFAULT_THEME, toAnsi } from './ansi.ts'
+export { type ClassStyle, contrastOn, resolveClassStyle } from './class-style.ts'
+export { type DiagramKind, diagramKind } from './registry.ts'
+export { sourceBox } from './source-box.ts'
+export type { MermaidArt, Role, Span } from './types.ts'
+
+/**
+ * Render a Mermaid source block as Unicode box-drawing art.
+ *
+ * Supported: `graph`/`flowchart` (including `subgraph`), `stateDiagram`,
+ * `classDiagram`, `erDiagram`, `sequenceDiagram`, `pie`, `mindmap`,
+ * `timeline` and `gitGraph`.
+ *
+ * The diagram is laid out at whatever size it needs; `art.width` reports the
+ * columns that turned out to be. Given `maxWidth`, a diagram wider than that
+ * is laid out again with progressively tighter label limits and the first
+ * fit is returned. Deciding what to do when even the tightest exceeds the
+ * space at hand is the caller's — `sourceBox` is the usual answer:
+ *
+ * ```ts
+ * const art = render(src, { maxWidth: cols })
+ * show(art && art.width <= cols ? art : sourceBox(src, cols))
+ * ```
+ *
+ * `null` means there is no art to show: blank input, a diagram type this
+ * renderer does not draw, a source in which not one statement parsed, or a
+ * diagram large enough that laying it out is refused. `diagramKind` separates
+ * the middle two.
+ *
+ * Rendering is best-effort in every grammar: a statement either contributes
+ * what parsed or is dropped, and a diagram over a size cap renders its prefix.
+ * Everything given up on is listed in `art.warnings` — advisory only, never a
+ * reason to withhold the art.
+ */
+export function render(src: string, options: { maxWidth?: number } = {}): MermaidArt | null {
+  src = stripControls(src)
+  if (src.trim() === '') return null
+  const diagram = diagramFor(src)
+  if (diagram === null) return null
+  // Too wide for the space given: lay out again with shorter labels and
+  // tighter wrapping, tightest last, and keep the first that fits (else
+  // the tightest, for the caller to judge against `art.width`).
+  let drawn: ReturnType<Diagram['render']> = null
+  let art: ReturnType<Canvas['toLines']> = { plain: [], styled: [], width: 0 }
+  for (const limits of LIMITS) {
+    drawn = diagram.render(src, limits)
+    if (drawn === null) return null
+    art = drawn.canvas.toLines()
+    if (options.maxWidth === undefined || art.width <= options.maxWidth) break
+  }
+  if (drawn === null) return null
+
+  // A frontmatter `title:` is centred above the art, in the `title` role.
+  const title = frontmatterTitle(src)
+  if (title !== null) {
+    const tw = stringWidth(title)
+    art.width = Math.max(art.width, tw)
+    const pad = ' '.repeat(Math.floor((art.width - tw) / 2))
+    art.plain.unshift(pad + title, '')
+    art.styled.unshift(
+      pad === ''
+        ? [{ text: title, role: 'title' }]
+        : [
+            { text: pad, role: 'none' },
+            { text: title, role: 'title' },
+          ],
+      [],
+    )
+  }
+  return { ...art, classDefs: drawn.classDefs, warnings: drawn.warnings }
+}