@yassimba/pi-loom-mermaid 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yassimba/pi-loom-mermaid",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Loom's advanced Mermaid renderer for Pi, with better routing and color.",
   "license": "MIT",
   "type": "module",

package/src/loom-mermaid/diagrams/architecture.ts

@@ -1,12 +1,11 @@
 /**
  * `architecture-beta`: services and junctions inside nested groups.
  *
- * Architecture's cardinal ports choose exact SVG attachment points. The
- * terminal graph router already chooses reachable box sides, so this parser
- * preserves endpoints and arrowheads while leaving port placement to it.
+ * Built-in icons use stable Unicode stand-ins; custom Iconify names remain
+ * visible as text because a terminal cannot draw their SVGs.
  */
 
-import { Graph, MAX_GROUP_DEPTH, MAX_GROUPS } from '../graph.ts'
+import { Graph, MAX_GROUP_DEPTH, MAX_GROUPS, type PortSide } from '../graph.ts'
 import { cleanLabel } from '../labels.ts'
 import { layoutFlowchart, layoutGrouped } from '../graph-render.ts'
 import type { Diagram } from '../registry.ts'
@@ -27,6 +26,14 @@ export const architecture: Diagram = {
 const DECLARATION = /^(group|service)\s+([^\s()[\]:{}]+)\(([^)]*)\)\[([^\]]*)\](?:\s+in\s+([^\s]+))?$/i
 const JUNCTION = /^junction\s+([^\s:{}]+)(?:\s+in\s+([^\s]+))?$/i
 const EDGE = /^([^\s:{}]+)(?:\{group\})?:([TBLR])\s*(<)?--(>)?\s*([TBLR]):([^\s:{}]+)(?:\{group\})?$/i
+const SIDES: Record<string, PortSide> = { T: 'top', B: 'bottom', L: 'left', R: 'right' }
+const ICONS: Record<string, string> = {
+  cloud: '☁',
+  database: '◉',
+  disk: '▰',
+  internet: '◎',
+  server: '▣',
+}
 
 function parseArchitecture(src: string): Graph | null {
   const statements = statementsOf(src)
@@ -43,7 +50,7 @@ function parseArchitecture(src: string): Graph | null {
     const edge = st.match(EDGE)
 
     if (declaration) {
-      const [, kind, id, , rawLabel, parentId] = declaration
+      const [, kind, id, icon, rawLabel, parentId] = declaration
       const parent = parentId === undefined ? null : groupIndex.get(parentId)
       if (parentId !== undefined && parent === undefined) {
         graph.drop(st)
@@ -57,10 +64,10 @@ function parseArchitecture(src: string): Graph | null {
           graph.truncated ??= `subgraph cap (${MAX_GROUPS} groups, depth ${MAX_GROUP_DEPTH}) reached`
         } else {
           groupIndex.set(id, graph.groups.length)
-          graph.groups.push({ id, label: cleanLabel(rawLabel) || id, parent: parent ?? null })
+          graph.groups.push({ id, label: iconLabel(icon, rawLabel || id), parent: parent ?? null })
         }
       } else {
-        addNode(graph, id, cleanLabel(rawLabel) || id, parent ?? null, 'rect')
+        addNode(graph, id, iconLabel(icon, rawLabel || id), parent ?? null, 'rect')
       }
     } else if (junction) {
       const [, id, parentId] = junction
@@ -68,7 +75,7 @@ function parseArchitecture(src: string): Graph | null {
       if (parentId !== undefined && parent === undefined) graph.drop(st)
       else addNode(graph, id, '•', parent ?? null, 'round')
     } else if (edge) {
-      const [, fromId, , leftArrow, rightArrow, , toId] = edge
+      const [, fromId, fromPort, leftArrow, rightArrow, toPort, toId] = edge
       const from = graph.index.get(fromId)
       const to = graph.index.get(toId)
       if (from === undefined || to === undefined) {
@@ -81,6 +88,8 @@ function parseArchitecture(src: string): Graph | null {
           headFrom: leftArrow ? 'arrow' : 'none',
           headTo: rightArrow ? 'arrow' : 'none',
           line: 'solid',
+          fromSide: SIDES[fromPort.toUpperCase()],
+          toSide: SIDES[toPort.toUpperCase()],
         })
       }
     } else if (firstWord(st).toLowerCase() !== 'title') {
@@ -96,6 +105,12 @@ function parseArchitecture(src: string): Graph | null {
   return graph.nodes.length === 0 ? null : graph
 }
 
+function iconLabel(icon: string, rawLabel: string): string {
+  const name = cleanLabel(icon)
+  const mark = ICONS[name.toLowerCase()] ?? `[${name.split(':').at(-1)}]`
+  return `${mark} ${cleanLabel(rawLabel)}`
+}
+
 function addNode(
   graph: Graph,
   id: string,

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

@@ -255,6 +255,8 @@ function buildScope(
       headTo: e.headTo,
       headFrom: e.headFrom,
       line: e.line,
+      fromSide: e.fromSide,
+      toSide: e.toSide,
       fromAnchor: anchorOf(f, e.from),
       toAnchor: anchorOf(t, e.to),
     }

package/src/loom-mermaid/graph.ts

@@ -26,6 +26,7 @@ export type Head =
   | 'diamondOpen'
 
 export type LineKind = 'solid' | 'dotted' | 'thick'
+export type PortSide = 'top' | 'bottom' | 'left' | 'right'
 
 type Dir = 'down' | 'up' | 'right' | 'left'
 
@@ -66,6 +67,9 @@ export interface Edge {
   headTo: Head
   headFrom: Head
   line: LineKind
+  /** Exact attachment sides requested by diagrams such as `architecture-beta`. */
+  fromSide?: PortSide
+  toSide?: PortSide
   /**
    * Set on an end that stands for a subgraph frame: the inner node the
    * author actually named, as a box in the frame's sub-canvas coordinates.

package/src/loom-mermaid/layout.ts

@@ -11,7 +11,7 @@
  */
 
 import type { Canvas } from './canvas.ts'
-import type { Anchor, Edge, LineKind } from './graph.ts'
+import type { Anchor, Edge, LineKind, PortSide } from './graph.ts'
 import type { Graph } from './graph.ts'
 import { fitLabel, type Limits, wrapLabel } from './labels.ts'
 import { brandesKoepf, type LayeredGraph } from './placement.ts'
@@ -117,7 +117,7 @@ interface Port {
   wanted: number
 }
 
-type Side = 'top' | 'bottom' | 'left' | 'right'
+type Side = PortSide
 
 function framePort(
   sub: Canvas,
@@ -1690,7 +1690,9 @@ function placeLr(
     })
   }
   const forward = (e: Edge): boolean => e.from !== e.to && ranks[e.to] > ranks[e.from]
-  let ends = resolve((i) => (forward(graph.edges[i]) ? ['right', 'left'] : null))
+  const requestedSides = (e: Edge): [Side, Side] | null =>
+    e.fromSide !== undefined && e.toSide !== undefined ? [e.fromSide, e.toSide] : null
+  let ends = resolve((i) => requestedSides(graph.edges[i]) ?? (forward(graph.edges[i]) ? ['right', 'left'] : null))
   // A node whose incoming edges all leave their frames at one row off the
   // frame's centre sits that far off its own aligned position, so the
   // edges run straight rather than jog to it (`[*]` after a composite
@@ -1753,6 +1755,8 @@ function placeLr(
   })
   ends = resolve((i) => {
     const e = graph.edges[i]
+    const requested = requestedSides(e)
+    if (requested !== null) return requested
     if (e.from === e.to) return null
     if (ranks[e.to] === ranks[e.from] + 1 || edgeStraight[i]) return ['right', 'left']
     return ranks[e.to] < ranks[e.from] ? ['top', 'top'] : ['bottom', 'bottom']
@@ -1871,14 +1875,40 @@ function placeLr(
     const [from, to] = endsOf(i)
     const through = ends[i].flatMap((p, k) => (p === null ? [] : portAt(p, placed[k === 0 ? edge.from : edge.to]).through))
     const route =
-      to.rank === from.rank + 1
-        ? forwardRouteLr(from, to, edge, bandEnd[from.rank] + 1 + edgeBus[i], max, bundleOf(i) !== undefined)
-        : to.rank > from.rank && edgeStraight[i]
-          ? skipRouteLr(from, to, edge, skipRoute[i], max)
-          : laneRoute(from, to, edge, onTop(i) ? edgeLane[i] : laneBase + edgeLane[i], max, onTop(i), laneEntry(i, from, to))
+      edge.fromSide !== undefined && edge.toSide !== undefined
+        ? portRoute(from, to, edge.fromSide, edge.toSide)
+        : to.rank === from.rank + 1
+          ? forwardRouteLr(from, to, edge, bandEnd[from.rank] + 1 + edgeBus[i], max, bundleOf(i) !== undefined)
+          : to.rank > from.rank && edgeStraight[i]
+            ? skipRouteLr(from, to, edge, skipRoute[i], max)
+            : laneRoute(from, to, edge, onTop(i) ? edgeLane[i] : laneBase + edgeLane[i], max, onTop(i), laneEntry(i, from, to))
     return through.length === 0 ? route : { ...route, through: [...(route.through ?? []), ...through] }
   })
-  return { canvasW, canvasH, routes }
+
+  if (!graph.edges.some((e) => e.fromSide !== undefined)) return { canvasW, canvasH, routes }
+  // Exact side ports may face out of the outermost box. Two cells of margin
+  // keep their first/last segments on-canvas at every nested group level.
+  for (const p of placed) {
+    p.x += 2
+    p.y += 2
+    p.cx += 2
+    p.cy += 2
+  }
+  for (const route of routes) {
+    route.points = route.points.map(([x, y]) => [x + 2, y + 2])
+    route.labels = route.labels.map((label) => ({ ...label, row: label.row + 2, x: label.x + 2 }))
+    if (route.laneLabel !== undefined) {
+      route.laneLabel = {
+        ...route.laneLabel,
+        y: route.laneLabel.y + 2,
+        lo: route.laneLabel.lo + 2,
+        hi: route.laneLabel.hi + 2,
+      }
+    }
+    if (route.through !== undefined)
+      route.through = route.through.map(([x, y, kind]) => [x + 2, y + 2, kind])
+  }
+  return { canvasW: canvasW + 4, canvasH: canvasH + 4, routes }
 }
 
 // -------------------------------------------------------------------- canvas
@@ -2213,6 +2243,50 @@ function chainRoute(
   return { points, labels: chainLabel(edge, headRow, entryX, labelLeft, labelAt, max) }
 }
 
+/** An orthogonal route that leaves and enters the exact requested box sides. */
+function portRoute(from: Placed, to: Placed, fromSide: PortSide, toSide: PortSide): Route {
+  const normal = (side: PortSide): [number, number] =>
+    side === 'left' ? [-1, 0] : side === 'right' ? [1, 0] : side === 'top' ? [0, -1] : [0, 1]
+  const border = (p: Placed, side: PortSide): [number, number] =>
+    side === 'left'
+      ? [p.x, p.cy]
+      : side === 'right'
+        ? [p.x + p.w - 1, p.cy]
+        : side === 'top'
+          ? [p.cx, p.y]
+          : [p.cx, p.y + p.h - 1]
+  const move = ([x, y]: [number, number], [dx, dy]: [number, number]): [number, number] => [x + dx, y + dy]
+
+  const fromNormal = normal(fromSide)
+  const toNormal = normal(toSide)
+  const start = border(from, fromSide)
+  const startOut = move(start, fromNormal)
+  const head = move(border(to, toSide), toNormal)
+  const targetOut = move(head, toNormal)
+  const fromHorizontal = fromNormal[0] !== 0
+  const toHorizontal = toNormal[0] !== 0
+  let middle: [number, number][]
+
+  if (fromHorizontal !== toHorizontal) {
+    middle = [fromHorizontal ? [targetOut[0], startOut[1]] : [startOut[0], targetOut[1]]]
+  } else if (fromHorizontal) {
+    const direction = Math.sign(targetOut[0] - startOut[0])
+    const direct = direction === fromNormal[0] && direction === -toNormal[0]
+    const lane = Math.max(from.y + from.h, to.y + to.h) + 1
+    middle = direct ? [] : [[startOut[0], lane], [targetOut[0], lane]]
+  } else {
+    const direction = Math.sign(targetOut[1] - startOut[1])
+    const direct = direction === fromNormal[1] && direction === -toNormal[1]
+    const lane = Math.max(from.x + from.w, to.x + to.w) + 1
+    middle = direct ? [] : [[lane, startOut[1]], [lane, targetOut[1]]]
+  }
+
+  const points = [start, startOut, ...middle, targetOut, head].filter(
+    ([x, y], i, all) => i === 0 || x !== all[i - 1][0] || y !== all[i - 1][1],
+  ) as [number, number][]
+  return { points, labels: [] }
+}
+
 /**
  * Adjacent ranks, left-to-right: out the right side, jog on the bus
  * column. The verb keeps its usual spot above the line; cardinalities hug