dsh-model-everything 0.5.0 → 0.5.2

package/src/render/collapse.ts

@@ -1,155 +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(diagram: Diagram, groupId: string, seen: Set<string>): number {
-  if (seen.has(groupId)) return 0
-  seen.add(groupId)
-  const groups = diagram.groups ?? []
-  const group = groups.find((entry) => entry.id === groupId)
-  if (group === undefined) return 0
-  const children = groups.filter((entry) => entry.parent === groupId)
-  return group.members.length + children.reduce((total, child) => total + subtreeSize(diagram, child.id, seen), 0)
-}
-
-/** The group that directly holds a node, when one does. */
-function ownerOf(diagram: Diagram, nodeId: string): string | undefined {
-  return (diagram.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(diagram, 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, seen: Set<string>): void => {
-    if (seen.has(groupId)) return
-    seen.add(groupId)
-    removedGroups.add(groupId)
-    const group = byId.get(groupId)
-    if (group === undefined) return
-    for (const member of group.members) removedNodes.add(member)
-    for (const child of groups.filter((entry) => entry.parent === groupId)) descend(child.id, seen)
-  }
-  for (const id of targets) descend(id, new Set())
-
-  /** 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(diagram, id) ?? '', 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(diagram, 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(diagram, 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 || targets.has(parent) || removedGroups.has(parent)) 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,
-  }
-}
+/**
+ * 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)
+}