dsh-model-everything 0.4.1 → 0.5.1

package/src/render/channels.ts

@@ -0,0 +1,309 @@
+/**
+ * Channel assignment: where the vertical lanes and the horizontal runs between two rows go.
+ *
+ * The stages before this one decide where the boxes are, and the painter decides what a box looks like. What is left
+ * is the space between two rows, and an edge that decides that space alone will collide with the next one: every long
+ * edge has to cross a row somewhere, and every edge whose two ends are not vertically aligned needs one horizontal run
+ * inside the gap it crosses. Chosen independently, two runs land on one height and read as a junction, and a run
+ * sweeps across a vertical another edge is already using.
+ *
+ * So this stage assigns both, after the boxes have settled and before anything is drawn:
+ *
+ * - **A lane's x.** A long edge owns one vertical lane through the rows it crosses. The x is a position no box
+ *   occupies in any of those rows, and lanes keep the order their dummies have in the ordering, so two lanes never
+ *   share an x inside one gap. Alignment is worth a detour: a lane that lands inside a box's own port span turns a
+ *   four-bend staircase into a straight drop, so alignment comes before distance from the proposed position.
+ * - **A run's y.** The horizontal runs inside one gap are stacked at distinct heights - Graphviz's virtual nodes - so
+ *   two runs never lie on one line, and a nested run stays near the box it leaves.
+ *
+ * Pure: rows, chains and coordinates in; lane positions and run heights out.
+ */
+
+import type { Chain } from './dummy.js'
+
+/** A box, as far as routing is concerned: only a box can move a lane. */
+export interface ChannelBox {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface ChannelInput {
+  /** The ordered rows, dummies included: a lane keeps its dummy's order. */
+  layers: string[][]
+  /** Every edge's chain, from the layout source to the layout target. */
+  chains: Chain[]
+  /** A dummy instance, and the lane it belongs to. */
+  chainOf: ReadonlyMap<string, string>
+  /** The boxes that block a lane. A dummy has none. */
+  boxes: ReadonlyMap<string, ChannelBox>
+  /** The top of each row, and how tall it is. */
+  layerY: number[]
+  layerHeight: number[]
+  /** What coordinate assignment proposed for each lane. */
+  laneX: ReadonlyMap<string, number>
+}
+
+export interface ChannelOptions {
+  /** How far a lane stays from a box in a row it crosses. */
+  clearance: number
+  /** The narrowest two lanes sharing a gap may be. */
+  spacing: number
+}
+
+/** One long edge's lane: the x of its vertical run, and the height of a run in each gap it crosses. */
+export interface LaneChannel {
+  x: number
+  y: number[]
+}
+
+export interface ChannelPlan {
+  /** By diagram edge index: the lane a long edge reserved, with one corridor height per gap it crosses. */
+  lanes: Map<number, LaneChannel>
+  /** By diagram edge index: the height of the one run an edge between two adjacent rows needs. */
+  runs: Map<number, number>
+}
+
+/** How far a port sits from a box's corner. The painter places ports from this same number. */
+export const PORT_INSET = 10
+
+/** An x-interval, open at either end when nothing bounds it. */
+interface Span {
+  lo: number
+  hi: number
+}
+
+/** The x's a port may sit at on a box's top or bottom side. */
+function spanOf(box: ChannelBox): Span {
+  const lo = box.x + PORT_INSET
+  const hi = box.x + box.width - PORT_INSET
+  return hi > lo ? { lo, hi } : { lo: box.x + box.width / 2, hi: box.x + box.width / 2 }
+}
+
+function clamp(value: number, span: Span): number {
+  return Math.min(span.hi, Math.max(span.lo, value))
+}
+
+function inside(value: number, span: Span): boolean {
+  return value >= span.lo - 0.001 && value <= span.hi + 0.001
+}
+
+/** The intervals a blocked strip cuts out of the free ones. */
+function cut(free: Span[], blocked: Span): Span[] {
+  const out: Span[] = []
+  for (const span of free) {
+    if (blocked.hi <= span.lo || blocked.lo >= span.hi) {
+      out.push(span)
+      continue
+    }
+    if (blocked.lo > span.lo) out.push({ lo: span.lo, hi: blocked.lo })
+    if (blocked.hi < span.hi) out.push({ lo: blocked.hi, hi: span.hi })
+  }
+  return out
+}
+
+/** The nearest free x at or after `value`: a lane pushed right never lands inside a box. */
+function atOrAfter(value: number, free: Span[]): number {
+  let found = value
+  for (const span of free) {
+    if (span.hi < value) continue
+    found = Math.max(value, span.lo)
+    break
+  }
+  return found
+}
+
+/** One long edge, and the space its lane may use. */
+interface Long {
+  edge: number
+  lane: string
+  /** The ids it passes through, dummies included. */
+  path: string[]
+  /** The rows it starts in and ends in. */
+  from: number
+  to: number
+  /** The x-intervals free of boxes in every row it crosses. */
+  free: Span[]
+  source: Span
+  target: Span
+  /** What coordinate assignment proposed, and what was finally chosen. */
+  proposal: number
+  x: number
+}
+
+/** The x a lane takes: aligned with a box's own port if it can be, then the proposed position, then the detour. */
+function choose(entry: Long): number {
+  const candidates: number[] = [entry.proposal, entry.source.lo, entry.source.hi, entry.target.lo, entry.target.hi]
+  candidates.push((clamp(entry.proposal, entry.source) + clamp(entry.proposal, entry.target)) / 2)
+  // Ordered by what the drawing wants: no detour at either end first, then the position coordinate assignment
+  // proposed, then the shorter detour. A free x is never this stage's to invent - the corridor is already there.
+  let best = entry.proposal
+  let bestBends = Infinity
+  let bestFar = Infinity
+  let bestReach = Infinity
+  for (const span of entry.free) {
+    for (const value of candidates) {
+      const x = clamp(value, span)
+      const bends = (inside(x, entry.source) ? 0 : 1) + (inside(x, entry.target) ? 0 : 1)
+      const far = Math.abs(x - entry.proposal)
+      const reach = Math.abs(x - clamp(x, entry.source)) + Math.abs(x - clamp(x, entry.target))
+      const better =
+        bends < bestBends ||
+        (bends === bestBends && (far < bestFar - 0.001 || (Math.abs(far - bestFar) <= 0.001 && reach < bestReach)))
+      if (!better) continue
+      best = x
+      bestBends = bends
+      bestFar = far
+      bestReach = reach
+    }
+  }
+  return best
+}
+
+/**
+ * The two ports the painter will place for an edge between two adjacent rows.
+ *
+ * The painter reads the side off the rows and the position off the box the edge points at; this repeats that rule so
+ * the run's height can be stacked against the runs it will actually share a gap with.
+ */
+function adjacentPorts(source: ChannelBox, target: ChannelBox): { from: number; to: number } {
+  const fromMiddle = source.x + source.width / 2
+  const toMiddle = target.x + target.width / 2
+  const fromSpan = spanOf(source)
+  const toSpan = spanOf(target)
+  const chosen = inside(fromMiddle, toSpan) ? fromMiddle : clamp(toMiddle, fromSpan)
+  return { from: clamp(chosen, fromSpan), to: clamp(chosen, toSpan) }
+}
+
+export function assignChannels(input: ChannelInput, options: ChannelOptions): ChannelPlan {
+  const { layers, chains, chainOf, boxes, layerY, layerHeight, laneX } = input
+  const rowOf = new Map<string, number>()
+  layers.forEach((row, depth) => {
+    for (const id of row) rowOf.set(id, depth)
+  })
+
+  // A lane's x: free in every row it crosses, and reachable from both ends.
+  const long: Long[] = []
+  for (const chain of chains) {
+    if (chain.path.length <= 2) continue
+    const head = chain.path[0] as string
+    const tail = chain.path[chain.path.length - 1] as string
+    const from = rowOf.get(head)
+    const to = rowOf.get(tail)
+    if (from === undefined || to === undefined || to <= from) continue
+    const lane = chainOf.get(chain.path[1] as string)
+    const source = boxes.get(head)
+    const target = boxes.get(tail)
+    // A lane into a boundary has no box to arrive at: that edge is the router's.
+    if (lane === undefined || source === undefined || target === undefined) continue
+    let free: Span[] = [{ lo: -Infinity, hi: Infinity }]
+    for (let depth = from + 1; depth < to; depth += 1) {
+      for (const id of layers[depth] as string[]) {
+        const box = boxes.get(id)
+        if (box === undefined) continue
+        free = cut(free, { lo: box.x - options.clearance, hi: box.x + box.width + options.clearance })
+      }
+    }
+    const centre = (source.x + source.width / 2 + target.x + target.width / 2) / 2
+    long.push({
+      edge: chain.index,
+      lane,
+      path: chain.path,
+      from,
+      to,
+      free,
+      source: spanOf(source),
+      target: spanOf(target),
+      proposal: laneX.get(lane) ?? centre,
+      x: 0,
+    })
+  }
+  for (const entry of long) entry.x = choose(entry)
+
+  // The order inside a gap: two lanes never share an x, and the left one is the one the ordering put left.
+  const byGap = new Map<number, Array<{ entry: Long; index: number }>>()
+  for (const entry of long) {
+    for (let gap = entry.from; gap < entry.to; gap += 1) {
+      // The dummy in the lower row of the gap; the last gap has none, and its upper row's dummy orders it.
+      const row = gap + 1 < entry.to ? gap + 1 : gap
+      const id = entry.path[row - entry.from] as string
+      const index = (layers[row] as string[]).indexOf(id)
+      byGap.set(gap, [...(byGap.get(gap) ?? []), { entry, index }])
+    }
+  }
+  for (const [, list] of byGap) list.sort((left, right) => left.index - right.index)
+  for (let round = 0; round < 4; round += 1) {
+    let moved = false
+    for (const [, list] of byGap) {
+      let previous = -Infinity
+      for (const item of list) {
+        const x = item.entry.x < previous + options.spacing ? atOrAfter(previous + options.spacing, item.entry.free) : item.entry.x
+        if (x !== item.entry.x) {
+          item.entry.x = x
+          moved = true
+        }
+        previous = item.entry.x
+      }
+    }
+    if (!moved) break
+  }
+
+  // The runs: one per edge end that does not land on its lane, stacked at distinct heights inside the gap.
+  const stacks = new Map<number, Array<{ edge: number; gap: number; left: number }>>()
+  const want = (gap: number, edge: number, left: number): void => {
+    stacks.set(gap, [...(stacks.get(gap) ?? []), { edge, gap, left }])
+  }
+  for (const entry of long) {
+    const head = clamp(entry.x, entry.source)
+    const tail = clamp(entry.x, entry.target)
+    if (Math.abs(head - entry.x) > 0.5) want(entry.from, entry.edge, Math.min(head, entry.x))
+    if (Math.abs(tail - entry.x) > 0.5) want(entry.to - 1, entry.edge, Math.min(tail, entry.x))
+  }
+  for (const chain of chains) {
+    if (chain.path.length > 2) continue
+    const head = chain.path[0] as string
+    const tail = chain.path[chain.path.length - 1] as string
+    const from = rowOf.get(head)
+    const to = rowOf.get(tail)
+    if (from === undefined || to === undefined || Math.abs(from - to) !== 1) continue
+    const source = boxes.get(head)
+    const target = boxes.get(tail)
+    if (source === undefined || target === undefined) continue
+    const ports = adjacentPorts(source, target)
+    want(Math.min(from, to), chain.index, Math.min(ports.from, ports.to))
+  }
+
+  // A gap always has a row below it, so its strip is bounded: one stack per gap, inside that strip.
+  const midOf = (gap: number): number => (layerY[gap] + layerHeight[gap] + layerY[gap + 1]) / 2
+  const heightOf = new Map<number, Map<number, number>>()
+  for (const [gap, list] of stacks) {
+    const top = layerY[gap] + layerHeight[gap]
+    const bottom = layerY[gap + 1]
+    const pad = Math.min(8, Math.max(1, (bottom - top) / 3))
+    const lo = top + pad
+    const hi = Math.max(lo, bottom - pad)
+    // Left to right, so a run that stays near its box sits near the row it left.
+    const sorted = [...list].sort((left, right) => left.left - right.left || left.edge - right.edge)
+    sorted.forEach((item, index) => {
+      const y = sorted.length === 1 ? (lo + hi) / 2 : lo + ((hi - lo) * (index + 1)) / (sorted.length + 1)
+      const heights = heightOf.get(item.edge) ?? new Map<number, number>()
+      heights.set(item.gap, y)
+      heightOf.set(item.edge, heights)
+    })
+  }
+
+  const lanes = new Map<number, LaneChannel>()
+  for (const entry of long) {
+    const y: number[] = []
+    for (let gap = entry.from; gap < entry.to; gap += 1) y.push(heightOf.get(entry.edge)?.get(gap) ?? midOf(gap))
+    lanes.set(entry.edge, { x: entry.x, y })
+  }
+  const runs = new Map<number, number>()
+  for (const [edge, heights] of heightOf) {
+    // A long edge's heights belong to its lane; an edge between two rows has the one run it asked for.
+    if (lanes.has(edge)) continue
+    runs.set(edge, [...heights.values()][0])
+  }
+  return { lanes, runs }
+}

package/src/render/collapse.ts

@@ -0,0 +1,150 @@
+/**
+ * Collapsing a group: the drawing with one boundary folded into a single box.
+ *
+ * A fold is a transform on the model, not a mode of the painter. That keeps the painter's rules unchanged -
+ * it still draws boxes and edges it is given - and it makes the behaviour testable without a browser: feed a
+ * diagram in, assert what came out.
+ *
+ * Folding is what makes a hierarchy usable: a reader who has understood a package wants it out of the way, and
+ * an architecture diagram that cannot be folded is read at one zoom level forever.
+ */
+
+import type { Diagram, DiagramEdge, DiagramGroup, DiagramNode } from './model.js'
+
+/** How many nodes a group holds, counting the whole subtree - what the folded box offers to unfold. */
+function subtreeSize(groups: DiagramGroup[], groupId: string, seen: Set<string>): number {
+  if (seen.has(groupId)) return 0
+  seen.add(groupId)
+  const group = groups.find((entry) => entry.id === groupId) as DiagramGroup
+  const children = groups.filter((entry) => entry.parent === groupId)
+  return group.members.length + children.reduce((total, child) => total + subtreeSize(groups, child.id, seen), 0)
+}
+
+/** The group that directly holds a node, when one does. */
+function ownerOf(groups: DiagramGroup[], nodeId: string): string | undefined {
+  return groups.find((group) => group.members.includes(nodeId))?.id
+}
+
+/**
+ * Fold the named groups.
+ *
+ * A folded group becomes a node carrying its name and how many nodes it holds; its members - and every group
+ * inside it - leave the drawing. An edge that pointed at something inside the fold is re-aimed at the fold's
+ * box, and an edge between two members of the same fold disappears: both ends are now the same box, and a
+ * self-loop would be a claim the source never made.
+ *
+ * Ids nobody declared are ignored, and folding a group whose contents are already gone changes nothing, so the
+ * function is total on any diagram and any set of names.
+ */
+export function collapse(diagram: Diagram, folded: Iterable<string>): Diagram {
+  const asked = new Set(folded)
+  const groups: DiagramGroup[] = diagram.groups ?? []
+  if (asked.size === 0 || groups.length === 0) return diagram
+
+  // Only groups that exist, and that still have contents, can be folded.
+  const byId = new Map(groups.map((group) => [group.id, group] as const))
+  const targets = new Set<string>()
+  for (const id of asked) {
+    const group = byId.get(id)
+    if (group !== undefined && subtreeSize(groups, id, new Set()) > 0) targets.add(id)
+  }
+  if (targets.size === 0) return diagram
+
+  // A fold inside another fold is served by the outer one: the inner box would not be drawn anyway.
+  for (const id of [...targets]) {
+    let cursor = byId.get(id)?.parent
+    const seen = new Set<string>()
+    while (cursor !== undefined && !seen.has(cursor)) {
+      seen.add(cursor)
+      if (targets.has(cursor)) {
+        targets.delete(id)
+        break
+      }
+      cursor = byId.get(cursor)?.parent
+    }
+  }
+
+  const removedNodes = new Set<string>()
+  const removedGroups = new Set<string>()
+  const descend = (groupId: string): void => {
+    removedGroups.add(groupId)
+    const group = byId.get(groupId) as DiagramGroup
+    for (const member of group.members) removedNodes.add(member)
+    for (const child of groups.filter((entry) => entry.parent === groupId)) descend(child.id)
+  }
+  for (const id of targets) descend(id)
+
+  /** The innermost fold that swallowed this id, if any. */
+  const foldOf = (id: string): string | undefined => {
+    for (const target of targets) {
+      const inSubtree = (groupId: string, seen: Set<string>): boolean => {
+        if (seen.has(groupId)) return false
+        seen.add(groupId)
+        if (groupId === target) return true
+        return groups.filter((entry) => entry.parent === groupId).some((child) => inSubtree(child.id, seen))
+      }
+      const group = byId.get(target) as DiagramGroup
+      if (group.members.includes(id) || inSubtree(ownerOf(groups, id) as string, new Set())) return target
+    }
+    return undefined
+  }
+
+  // The box that replaces a fold takes the place of its first member, so the drawing keeps the order the source
+  // gave it: a folded package belongs where the package was, not at the end of the page.
+  const nodes: DiagramNode[] = []
+  const emitted = new Set<string>()
+  for (const node of diagram.nodes) {
+    if (!removedNodes.has(node.id)) {
+      nodes.push(node)
+      continue
+    }
+    const fold = foldOf(node.id)
+    if (fold === undefined || emitted.has(fold)) continue
+    emitted.add(fold)
+    const group = byId.get(fold) as DiagramGroup
+    nodes.push({ id: fold, label: group.label + ' (' + String(subtreeSize(groups, fold, new Set())) + ')', role: 'normal' })
+  }
+  // A fold whose members are not in `nodes` at all still deserves a box rather than vanishing.
+  for (const id of targets) {
+    if (emitted.has(id)) continue
+    const group = byId.get(id) as DiagramGroup
+    nodes.push({ id, label: group.label + ' (' + String(subtreeSize(groups, id, new Set())) + ')', role: 'normal' })
+  }
+
+  const edges: DiagramEdge[] = []
+  const seenEdges = new Set<string>()
+  for (const edge of diagram.edges) {
+    const from = removedNodes.has(edge.from) ? foldOf(edge.from) : edge.from
+    const to = removedNodes.has(edge.to) ? foldOf(edge.to) : edge.to
+    if (from === undefined || to === undefined) continue
+    if (from === to) continue
+    const key = from + '>' + to + ':' + edge.label
+    if (seenEdges.has(key)) continue
+    seenEdges.add(key)
+    edges.push({ ...edge, from, to })
+  }
+
+  // A folded box stands where its group stood, so it belongs to that group's parent: without this the box that
+  // replaced an inner boundary would be drawn outside the outer one, which reads as "it left the package".
+  const adopted = new Map<string, string[]>()
+  for (const id of targets) {
+    const parent = byId.get(id)?.parent
+    if (parent === undefined) continue
+    adopted.set(parent, [...(adopted.get(parent) ?? []), id])
+  }
+  const remaining = groups
+    .filter((group) => !removedGroups.has(group.id) && targets.has(group.id) === false)
+    .map((group) => {
+      const extra = adopted.get(group.id)
+      if (extra === undefined) return group
+      return { ...group, members: [...group.members.filter((member) => !removedNodes.has(member)), ...extra] }
+    })
+  const caption = diagram.caption + (targets.size === 1 ? ', 1 group folded' : ', ' + String(targets.size) + ' groups folded')
+  return {
+    ...diagram,
+    nodes,
+    edges,
+    ...(remaining.length === 0 ? { groups: undefined } : { groups: remaining }),
+    caption,
+  }
+}

package/src/render/components.ts

@@ -0,0 +1,126 @@
+/**
+ * The two decompositions a drawing needs before it can be packed.
+ *
+ * **Weakly connected components.** Two subgraphs with no edge between them are two drawings that happen to share a
+ * page. Laying them out together makes them share one set of layers, so the wider one sets every column width and
+ * the narrower one is squeezed beside it; moving one moves the other. Split first, lay each out on its own, then pack
+ * the rectangles.
+ *
+ * **Packing.** A pile of rectangles has to become a page. The target is the aspect ratio a page and a screen share -
+ * 1.6 - and a shelf packer is enough to get there: sort by height, fill a shelf until the next rectangle would make
+ * the drawing wider than the page it is aiming at, then start the next shelf. No overlap, and a deterministic order,
+ * so the same rectangles always pack the same way.
+ *
+ * Pure, and asserted on the rectangles themselves.
+ */
+
+export interface SizedRectangle {
+  width: number
+  height: number
+}
+
+export interface PackedRectangle {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/** The aspect ratio a page and a landscape screen share. */
+const PAGE_ASPECT = 1.6
+
+/**
+ * The nodes of each weakly connected component, in the order the nodes were written.
+ *
+ * An isolated node is a component of its own: it is not noise, it is a drawing with nothing joining it, and the
+ * packer is what decides where it goes.
+ */
+export function weakComponents(
+  nodes: ReadonlyArray<{ id: string }>,
+  edges: ReadonlyArray<{ from: string; to: string }>,
+): string[][] {
+  const known = new Set(nodes.map((node) => node.id))
+  const neighbours = new Map<string, string[]>()
+  const link = (from: string, to: string): void => {
+    neighbours.set(from, [...(neighbours.get(from) ?? []), to])
+  }
+  for (const edge of edges) {
+    if (!known.has(edge.from) || !known.has(edge.to) || edge.from === edge.to) continue
+    link(edge.from, edge.to)
+    link(edge.to, edge.from)
+  }
+  const seen = new Set<string>()
+  const components: string[][] = []
+  for (const node of nodes) {
+    if (seen.has(node.id)) continue
+    const members: string[] = []
+    const queue = [node.id]
+    seen.add(node.id)
+    for (let head = 0; head < queue.length; head += 1) {
+      const id = queue[head]
+      members.push(id)
+      for (const next of neighbours.get(id) ?? []) {
+        if (seen.has(next)) continue
+        seen.add(next)
+        queue.push(next)
+      }
+    }
+    components.push(members)
+  }
+  return components
+}
+
+export interface PackOptions {
+  /** The empty strip kept between two rectangles, on both axes. */
+  gap?: number
+  /** The page the packer aims at; the drawing comes out as close to it as the rectangles allow. */
+  aspect?: number
+}
+
+/**
+ * Pack rectangles into a page of roughly `aspect`, using shelves.
+ *
+ * The shelf width is derived from the total area and the target aspect: that is the width at which a perfect grid
+ * would have the wanted shape, so a shelf that fills it lands near the target. Rectangles are taken tallest first,
+ * which is what keeps a shelf from being mostly empty air above a short rectangle.
+ */
+export function packRectangles(rectangles: ReadonlyArray<SizedRectangle>, options: PackOptions = {}): {
+  placements: PackedRectangle[]
+  width: number
+  height: number
+} {
+  const gap = options.gap ?? 30
+  const aspect = options.aspect ?? PAGE_ASPECT
+  if (rectangles.length === 0) return { placements: [], width: 0, height: 0 }
+
+  const area = rectangles.reduce((total, rectangle) => total + (rectangle.width + gap) * (rectangle.height + gap), 0)
+  const targetWidth = Math.max(gap, Math.sqrt(area * aspect))
+  const order = rectangles
+    .map((rectangle, index) => ({ rectangle, index }))
+    .sort((left, right) => right.rectangle.height - left.rectangle.height || right.rectangle.width - left.rectangle.width || left.index - right.index)
+
+  const placements: PackedRectangle[] = rectangles.map((rectangle) => ({ x: 0, y: 0, width: rectangle.width, height: rectangle.height }))
+  let x = 0
+  let y = 0
+  let shelfHeight = 0
+  let width = 0
+  for (const entry of order) {
+    const rectangle = entry.rectangle
+    if (x > 0 && x + rectangle.width > targetWidth) {
+      y += shelfHeight + gap
+      x = 0
+      shelfHeight = 0
+    }
+    placements[entry.index] = { x, y, width: rectangle.width, height: rectangle.height }
+    x += rectangle.width + gap
+    width = Math.max(width, x - gap)
+    shelfHeight = Math.max(shelfHeight, rectangle.height)
+  }
+  return { placements, width, height: y + shelfHeight }
+}
+
+/** The aspect ratio of a box, as a number a reader can compare against the page's. */
+export function aspectOf(width: number, height: number): number {
+  if (width <= 0 || height <= 0) return 1
+  return Math.max(width, height) / Math.min(width, height)
+}