@diagrammo/dgmo 0.47.0 → 0.48.0

package/src/boxes-and-lines/focus.ts

@@ -1,257 +0,0 @@
-// ============================================================
-// Boxes and Lines — Focus (1-hop neighborhood) Transform
-// ============================================================
-//
-// Pure transform that filters a parsed boxes-and-lines diagram down to a single
-// focused element plus its direct (1-hop) graph neighbours, mirroring the shape
-// of `org/collapse.ts#focusOrgTree` but for a general graph instead of a tree.
-//
-// Unlike the org tree (subtree extraction), boxes-and-lines is a general graph,
-// so "focus" = the focused element + everything one edge away. Neighbour groups
-// come back COLLAPSED (reusing `collapseBoxesAndLines`'s edge-redirect + dedup),
-// the focused group comes back EXPANDED, and everything else is hidden.
-//
-// Composition: this owns ALL collapse decisions for the focused view, so it is
-// fed the un-(manually-)collapsed parsed model — focus supersedes the user's
-// manual collapse selection for its duration (Decision 12). It runs after
-// tag-hide in the app pipeline (FM10).
-
-import type { ParsedBoxesAndLines, BLGroup, BLEdge } from './types';
-import { collapseBoxesAndLines } from './collapse';
-
-const GROUP_PREFIX = '__group_';
-const groupKey = (label: string): string => `${GROUP_PREFIX}${label}`;
-const isGroupKey = (k: string): boolean => k.startsWith(GROUP_PREFIX);
-const groupLabelOf = (k: string): string => k.slice(GROUP_PREFIX.length);
-
-export interface FocusTarget {
-  readonly kind: 'box' | 'group';
-  /** Canonical endpoint key the parser uses for edges: a node label for a box,
-   *  or `__group_<label>` for a group. */
-  readonly id: string;
-}
-
-export interface FocusResult {
-  /** Filtered model to lay out + render (neighbour groups already collapsed via
-   *  `collapseBoxesAndLines`; `nodePositions` cleared so the subset auto-lays). */
-  readonly parsed: ParsedBoxesAndLines;
-  /** Canonical keys of the 1-hop neighbours kept in view (box labels +
-   *  `__group_<label>` for neighbour groups). */
-  readonly neighborIds: Set<string>;
-  /** Group LABELS of neighbours rendered collapsed. */
-  readonly collapsedNeighborGroupIds: Set<string>;
-  /** GLOBAL value-ramp domain computed from the ORIGINAL model before filtering
-   *  (Decision 20 / FM1); null when the diagram has no `heat:` data. */
-  readonly rampDomain: { min: number; max: number } | null;
-  /** Collapse metadata for `layoutBoxesAndLines` so neighbour groups materialise
-   *  as collapsed boxes — mirrors the manual-collapse path's `collapseInfo`. */
-  readonly collapseInfo: {
-    collapsedChildCounts: Map<string, number>;
-    originalGroups: readonly BLGroup[];
-  };
-}
-
-/**
- * Filter `parsed` to the focused element + its 1-hop neighbours.
- *
- * Pure, synchronous, no I/O. Tolerant of dangling/alias endpoints (skips them,
- * never throws). For an edge-less target it returns the lone element (the app
- * decides the "no connections" affordance, Decision 19).
- */
-export function focusBoxesAndLines(
-  parsed: ParsedBoxesAndLines,
-  target: FocusTarget
-): FocusResult {
-  // ── Step 1: GLOBAL ramp domain, computed BEFORE any filtering (Dec 20/FM1) ──
-  const allValues = parsed.nodes
-    .filter((n) => n.value !== undefined)
-    .map((n) => n.value!);
-  const rampDomain =
-    allValues.length > 0
-      ? { min: Math.min(...allValues), max: Math.max(...allValues) }
-      : null;
-
-  // ── Lookups ──
-  const nodeLabelSet = new Set(parsed.nodes.map((n) => n.label));
-  const groupByLabel = new Map<string, BLGroup>();
-  for (const g of parsed.groups) groupByLabel.set(g.label, g);
-  // child label (node or sub-group) → its direct parent group label
-  const parentOf = new Map<string, string>();
-  for (const g of parsed.groups)
-    for (const child of g.children) parentOf.set(child, g.label);
-
-  /** Top-most ancestor group of a node/group label (undefined if top-level). */
-  const topAncestor = (label: string): string | undefined => {
-    let p = parentOf.get(label);
-    if (p === undefined) return undefined;
-    for (;;) {
-      const up = parentOf.get(p);
-      if (up === undefined) return p;
-      p = up;
-    }
-  };
-
-  /** All descendant node + sub-group labels of a group (recursive, cycle-safe). */
-  const descendantsOf = (
-    groupLabel: string
-  ): { nodes: Set<string>; groups: Set<string> } => {
-    const nodes = new Set<string>();
-    const groups = new Set<string>();
-    const seen = new Set<string>([groupLabel]);
-    const stack = [groupLabel];
-    while (stack.length) {
-      const cur = stack.pop()!;
-      const g = groupByLabel.get(cur);
-      if (!g) continue;
-      for (const child of g.children) {
-        if (groupByLabel.has(child)) {
-          if (!seen.has(child)) {
-            seen.add(child);
-            groups.add(child);
-            stack.push(child);
-          }
-        } else {
-          nodes.add(child);
-        }
-      }
-    }
-    return { nodes, groups };
-  };
-
-  // ── Step 2: resolve the focused element ──
-  // focusNodeLabels  — focus boxes shown standalone (focused box, or a group's members)
-  // focusGroupLabels — groups kept EXPANDED (focused group + its sub-groups)
-  // focusEndpointSet — canonical keys that count as "the focus" for edge adjacency
-  const focusNodeLabels = new Set<string>();
-  const focusGroupLabels = new Set<string>();
-  const focusEndpointSet = new Set<string>();
-
-  if (target.kind === 'group') {
-    const gl = isGroupKey(target.id) ? groupLabelOf(target.id) : target.id;
-    if (groupByLabel.has(gl)) {
-      focusGroupLabels.add(gl);
-      focusEndpointSet.add(groupKey(gl));
-      const desc = descendantsOf(gl);
-      for (const n of desc.nodes) {
-        focusNodeLabels.add(n);
-        focusEndpointSet.add(n);
-      }
-      for (const sg of desc.groups) {
-        focusGroupLabels.add(sg);
-        focusEndpointSet.add(groupKey(sg));
-      }
-    }
-  } else {
-    // box — shown standalone even if it belongs to a group (framing stripped).
-    if (nodeLabelSet.has(target.id)) {
-      focusNodeLabels.add(target.id);
-      focusEndpointSet.add(target.id);
-    }
-  }
-
-  // ── Step 3: walk edges → neighbours + kept (focus-incident / internal) edges ──
-  const neighborIds = new Set<string>();
-  const collapsedNeighborGroupIds = new Set<string>();
-  const neighborBoxes = new Set<string>();
-  const keepGroupLabels = new Set<string>(focusGroupLabels);
-  const keptEdges: BLEdge[] = [];
-  const selfLoops: BLEdge[] = [];
-
-  const keepGroupAndSubgroups = (gl: string): void => {
-    keepGroupLabels.add(gl);
-    for (const sg of descendantsOf(gl).groups) keepGroupLabels.add(sg);
-  };
-
-  /** Classify a neighbour endpoint; returns whether the incident edge survives. */
-  const classifyNeighbor = (key: string): boolean => {
-    if (isGroupKey(key)) {
-      const gl = groupLabelOf(key);
-      if (!groupByLabel.has(gl)) return false; // dangling group ref (FM7)
-      if (focusGroupLabels.has(gl)) return true; // part of focus (internal)
-      neighborIds.add(key);
-      collapsedNeighborGroupIds.add(gl);
-      keepGroupAndSubgroups(gl);
-      return true;
-    }
-    if (focusNodeLabels.has(key)) return true; // part of focus
-    if (!nodeLabelSet.has(key)) return false; // dangling box endpoint (FM7)
-    // A neighbour box inside a group → collapse that group so the edge redirects
-    // to a single collapsed box (AC3 / Dec 11); never expand the group (FM4).
-    const top = topAncestor(key);
-    if (top !== undefined && !focusGroupLabels.has(top)) {
-      neighborIds.add(groupKey(top));
-      collapsedNeighborGroupIds.add(top);
-      keepGroupAndSubgroups(top);
-      return true;
-    }
-    // Standalone neighbour box (no group, or already inside the focused group).
-    neighborIds.add(key);
-    neighborBoxes.add(key);
-    return true;
-  };
-
-  for (const edge of parsed.edges) {
-    const inS = focusEndpointSet.has(edge.source);
-    const inT = focusEndpointSet.has(edge.target);
-    if (edge.source === edge.target) {
-      // Self-loop: kept iff incident to focus, re-added after the collapse pass
-      // (which drops src===tgt) — FM5.
-      if (inS) selfLoops.push(edge);
-      continue;
-    }
-    if (inS && inT) {
-      keptEdges.push(edge); // internal (member↔member inside focused group) — FM3
-      continue;
-    }
-    if (!inS && !inT) continue; // unrelated to focus
-    const other = inS ? edge.target : edge.source;
-    if (classifyNeighbor(other)) keptEdges.push(edge);
-  }
-
-  // ── Step 4: build the filtered model ──
-  const keepNodeLabels = new Set<string>([
-    ...focusNodeLabels,
-    ...neighborBoxes,
-  ]);
-  const nodes = parsed.nodes.filter((n) => keepNodeLabels.has(n.label));
-  const groups = parsed.groups.filter((g) => keepGroupLabels.has(g.label));
-  // Notes follow their owner: kept iff the owning box survives (FM9).
-  const notes = parsed.notes?.filter((note) => keepNodeLabels.has(note.ref));
-
-  const filtered: ParsedBoxesAndLines = {
-    ...parsed,
-    nodes,
-    edges: keptEdges,
-    groups,
-    ...(notes !== undefined && { notes }),
-  };
-  // Clear pinned positions so the subset auto-lays-out (Dec 21 / FM2). Pins are
-  // restored on exit because exit re-renders the original unfiltered model.
-  delete (filtered as { nodePositions?: unknown }).nodePositions;
-
-  // ── Step 5: collapse neighbour groups via the shared redirect+dedup (ADR-3) ──
-  const collapsed = collapseBoxesAndLines(filtered, collapsedNeighborGroupIds);
-
-  // ── Step 6: re-add self-loops the collapse pass dropped (FM5) ──
-  let resultParsed = collapsed.parsed;
-  if (selfLoops.length > 0) {
-    const visible = new Set(resultParsed.nodes.map((n) => n.label));
-    const survivors = selfLoops.filter((e) => visible.has(e.source));
-    if (survivors.length > 0)
-      resultParsed = {
-        ...resultParsed,
-        edges: [...resultParsed.edges, ...survivors],
-      };
-  }
-
-  return {
-    parsed: resultParsed,
-    neighborIds,
-    collapsedNeighborGroupIds,
-    rampDomain,
-    collapseInfo: {
-      collapsedChildCounts: collapsed.collapsedChildCounts,
-      originalGroups: collapsed.originalGroups,
-    },
-  };
-}

package/src/boxes-and-lines/label-placement.ts

@@ -1,339 +0,0 @@
-// ============================================================
-// Boxes and Lines Diagram — Edge label placement
-// ============================================================
-//
-// Makes edge/arrow labels legible regardless of length or layout via a priority
-// ladder (each step only fires when the previous can't make the label legible):
-//
-//   1. WRAP   — cap label width and wrap onto up to MAX_LABEL_LINES lines.
-//   2. MOVE   — if the wrapped box still overlaps a node box, slide it to a clear
-//               spot near its own line (along the polyline, then a small
-//               perpendicular offset), staying proximal. No leader line.
-//   3. RELAYOUT (last resort, owned by layout.ts) — re-run the search reserving
-//               dagre label space so a gap opens; this module only reports which
-//               labels stayed unresolved so the caller can decide to escalate.
-//
-// Placement runs in layout (not the renderer) so it sees node/group boxes and so
-// the relayout decision can re-invoke the search. The renderer is a pure consumer
-// of the labelX/labelY/labelWidth/labelHeight/labelLines fields written here.
-
-import type { BLLayoutResult } from './layout';
-import {
-  measureText,
-  wrapTextToWidth,
-  truncateText,
-} from '../utils/text-measure';
-
-// Keep in sync with EDGE_LABEL_FONT_SIZE in renderer.ts (ScaleContext is identity
-// there, so layout-space px == screen px for the unscaled diagram coords).
-export const EDGE_LABEL_FONT_SIZE = 11;
-
-const LABEL_MAX_WIDTH = 160; // ≈ DESC_NODE_WIDTH + slack; flat (not canvas-relative)
-const MAX_LABEL_LINES = 3;
-const LABEL_LINE_HEIGHT = 1.3;
-const H_PAD = 6; // horizontal halo padding (each side)
-const V_PAD = 3; // vertical halo padding (each side)
-const BOX_CLEAR_PAD = 4; // min clearance kept between a label box and a node box
-const PERP_STEP = 8; // perpendicular offset increment (px)
-const PERP_MAX = 40; // max perpendicular offset before giving up
-const SLIDE_SAMPLES = 9; // arc-length samples per side when sliding along the edge
-
-type Pt = { readonly x: number; readonly y: number };
-
-interface Rect {
-  readonly minX: number;
-  readonly minY: number;
-  readonly maxX: number;
-  readonly maxY: number;
-}
-
-export interface MeasuredLabel {
-  readonly lines: readonly string[];
-  /** Halo box width, including 2·H_PAD. */
-  readonly width: number;
-  /** Halo box height, including 2·V_PAD. */
-  readonly height: number;
-}
-
-/**
- * Wrap + measure an edge label into a bounded multi-line box. Long unbreakable
- * tokens are hard-broken at the char boundary; overflow past MAX_LABEL_LINES is
- * ellipsized so the box is bounded in both axes.
- */
-export function measureEdgeLabel(
-  label: string,
-  fontSize: number = EDGE_LABEL_FONT_SIZE,
-  maxWidth: number = LABEL_MAX_WIDTH
-): MeasuredLabel {
-  let lines = wrapTextToWidth(label, fontSize, maxWidth, { hardBreak: true });
-  if (lines.length > MAX_LABEL_LINES) {
-    const kept = lines.slice(0, MAX_LABEL_LINES - 1);
-    const rest = lines.slice(MAX_LABEL_LINES - 1).join(' ');
-    kept.push(truncateText(rest, fontSize, maxWidth));
-    lines = kept;
-  }
-  let textW = 0;
-  for (const ln of lines) {
-    const w = measureText(ln, fontSize);
-    if (w > textW) textW = w;
-  }
-  return {
-    lines,
-    width: textW + 2 * H_PAD,
-    height: lines.length * fontSize * LABEL_LINE_HEIGHT + 2 * V_PAD,
-  };
-}
-
-/** Point at the half-way arc length along an edge polyline — the geometric
- *  centre of the connector, so a label seeds in the gap BETWEEN the two nodes
- *  rather than drifting under the target. Degenerate point lists fall back. */
-export function edgePolylineMidpoint(points: ReadonlyArray<Pt>): Pt {
-  return pointAtArcFraction(points, 0.5).p;
-}
-
-/** Position + unit normal at arc-length fraction t∈[0,1] of a polyline. The
- *  normal is perpendicular to the local segment (for proximal perp offsets). */
-function pointAtArcFraction(
-  points: ReadonlyArray<Pt>,
-  t: number
-): { p: Pt; nx: number; ny: number } {
-  if (points.length === 0) return { p: { x: 0, y: 0 }, nx: 0, ny: 1 };
-  if (points.length === 1)
-    return { p: { x: points[0]!.x, y: points[0]!.y }, nx: 0, ny: 1 };
-  const segLen: number[] = [];
-  let total = 0;
-  for (let k = 1; k < points.length; k++) {
-    const len = Math.hypot(
-      points[k]!.x - points[k - 1]!.x,
-      points[k]!.y - points[k - 1]!.y
-    );
-    segLen.push(len);
-    total += len;
-  }
-  let want = total * Math.max(0, Math.min(1, t));
-  for (let k = 1; k < points.length; k++) {
-    const len = segLen[k - 1]!;
-    if (want <= len || k === points.length - 1) {
-      const f = len === 0 ? 0 : Math.min(1, want / len);
-      const ax = points[k - 1]!.x;
-      const ay = points[k - 1]!.y;
-      const bx = points[k]!.x;
-      const by = points[k]!.y;
-      const dx = bx - ax;
-      const dy = by - ay;
-      const dlen = Math.hypot(dx, dy) || 1;
-      // Unit normal = perpendicular to the local tangent.
-      return {
-        p: { x: ax + dx * f, y: ay + dy * f },
-        nx: -dy / dlen,
-        ny: dx / dlen,
-      };
-    }
-    want -= len;
-  }
-  const last = points[points.length - 1]!;
-  return { p: { x: last.x, y: last.y }, nx: 0, ny: 1 };
-}
-
-function rectFromCenter(cx: number, cy: number, w: number, h: number): Rect {
-  return {
-    minX: cx - w / 2,
-    minY: cy - h / 2,
-    maxX: cx + w / 2,
-    maxY: cy + h / 2,
-  };
-}
-
-/** Does a label box centred at (cx,cy) overlap any obstacle (within pad)? */
-function overlapsAny(
-  cx: number,
-  cy: number,
-  w: number,
-  h: number,
-  obstacles: readonly Rect[],
-  pad: number
-): boolean {
-  const minX = cx - w / 2 - pad;
-  const minY = cy - h / 2 - pad;
-  const maxX = cx + w / 2 + pad;
-  const maxY = cy + h / 2 + pad;
-  for (const o of obstacles) {
-    if (minX < o.maxX && maxX > o.minX && minY < o.maxY && maxY > o.minY)
-      return true;
-  }
-  return false;
-}
-
-/** Arc-length fractions sampled centre-outward (keeps the label proximal to the
- *  true midpoint), clamped away from the endpoints. */
-function slideFractions(): number[] {
-  const out = [0.5];
-  for (let k = 1; k <= SLIDE_SAMPLES; k++) {
-    const off = k * 0.08;
-    if (0.5 - off >= 0.12) out.push(0.5 - off);
-    if (0.5 + off <= 0.88) out.push(0.5 + off);
-  }
-  return out;
-}
-
-/** Find the nearest clear centre for a label box of (w,h) along/near `points`.
- *  Pass 1 slides along the line; pass 2 offsets perpendicular. null = no clear
- *  spot found within the proximity budget. */
-function findClearPosition(
-  w: number,
-  h: number,
-  points: ReadonlyArray<Pt>,
-  obstacles: readonly Rect[]
-): Pt | null {
-  const ts = slideFractions();
-  for (const t of ts) {
-    const { p } = pointAtArcFraction(points, t);
-    if (!overlapsAny(p.x, p.y, w, h, obstacles, BOX_CLEAR_PAD)) return p;
-  }
-  for (let mag = PERP_STEP; mag <= PERP_MAX; mag += PERP_STEP) {
-    for (const t of ts) {
-      const { p, nx, ny } = pointAtArcFraction(points, t);
-      for (const sign of [-1, 1]) {
-        const x = p.x + nx * mag * sign;
-        const y = p.y + ny * mag * sign;
-        if (!overlapsAny(x, y, w, h, obstacles, BOX_CLEAR_PAD)) return { x, y };
-      }
-    }
-  }
-  return null;
-}
-
-interface LabelBox {
-  edgeIdx: number;
-  cx: number;
-  cy: number;
-  w: number;
-  h: number;
-  lines: readonly string[];
-  resolved: boolean;
-}
-
-/** Separate overlapping label boxes vertically (variable sizes), mirroring the
- *  old renderer pass. Runs after node-collision resolution; the caller re-checks
- *  node overlap afterwards. */
-function resolveLabelOverlaps(boxes: LabelBox[]): void {
-  const MAX_PASSES = 8;
-  const PAD = 4;
-  for (let pass = 0; pass < MAX_PASSES; pass++) {
-    let moved = false;
-    for (let i = 0; i < boxes.length; i++) {
-      for (let j = i + 1; j < boxes.length; j++) {
-        const a = boxes[i]!;
-        const b = boxes[j]!;
-        const dx = Math.abs(a.cx - b.cx);
-        const dy = Math.abs(a.cy - b.cy);
-        const overlapX = (a.w + b.w) / 2 + PAD - dx;
-        const overlapY = (a.h + b.h) / 2 + PAD - dy;
-        if (overlapX > 0 && overlapY > 0) {
-          const shift = overlapY / 2 + 1;
-          if (a.cy < b.cy) {
-            a.cy -= shift;
-            b.cy += shift;
-          } else {
-            a.cy += shift;
-            b.cy -= shift;
-          }
-          moved = true;
-        }
-      }
-    }
-    if (!moved) break;
-  }
-}
-
-export interface PlaceEdgeLabelsResult {
-  readonly layout: BLLayoutResult;
-  /** Edge indices whose label still overlaps a node box (escalate to relayout). */
-  readonly unresolved: number[];
-}
-
-/**
- * Wrap, then collision-resolve every edge label against node boxes (steps 1–2),
- * writing labelX/labelY/labelWidth/labelHeight/labelLines onto each edge. Returns
- * the edge indices that could not be cleared so the caller can trigger a
- * last-resort relayout.
- */
-export function placeEdgeLabels(
-  layout: BLLayoutResult,
-  opts?: { fontSize?: number; maxWidth?: number }
-): PlaceEdgeLabelsResult {
-  const fontSize = opts?.fontSize ?? EDGE_LABEL_FONT_SIZE;
-  const maxWidth = opts?.maxWidth ?? LABEL_MAX_WIDTH;
-
-  // Obstacles = real node boxes + collapsed groups (drawn as boxes). Expanded
-  // groups are containers — their interior is valid label space, so they are NOT
-  // obstacles.
-  const obstacles: Rect[] = [];
-  for (const n of layout.nodes)
-    obstacles.push(rectFromCenter(n.x, n.y, n.width, n.height));
-  for (const g of layout.groups)
-    if (g.collapsed)
-      obstacles.push(rectFromCenter(g.x, g.y, g.width, g.height));
-
-  const boxes: LabelBox[] = [];
-  layout.edges.forEach((e, idx) => {
-    if (!e.label || e.points.length < 2) return;
-    const m = measureEdgeLabel(e.label, fontSize, maxWidth);
-    const mid = edgePolylineMidpoint(e.points);
-    let cy = mid.y;
-    // Fold in the parallel-edge fan offset so each line's label clears its line.
-    if (e.parallelCount > 1 && e.yOffset !== 0)
-      cy += (e.yOffset < 0 ? -1 : 1) * (m.height / 2);
-    boxes.push({
-      edgeIdx: idx,
-      cx: mid.x,
-      cy,
-      w: m.width,
-      h: m.height,
-      lines: m.lines,
-      resolved: true,
-    });
-  });
-
-  // Step 2: reposition any box that overlaps a node.
-  for (const box of boxes) {
-    if (!overlapsAny(box.cx, box.cy, box.w, box.h, obstacles, BOX_CLEAR_PAD))
-      continue;
-    const e = layout.edges[box.edgeIdx]!;
-    const clear = findClearPosition(box.w, box.h, e.points, obstacles);
-    if (clear) {
-      box.cx = clear.x;
-      box.cy = clear.y;
-    } else {
-      box.resolved = false;
-    }
-  }
-
-  // Separate stacked labels, then re-check node overlap (a vertical nudge can
-  // push a label back onto a box — that becomes an unresolved escalation).
-  resolveLabelOverlaps(boxes);
-  for (const box of boxes) {
-    if (overlapsAny(box.cx, box.cy, box.w, box.h, obstacles, BOX_CLEAR_PAD))
-      box.resolved = false;
-  }
-
-  const boxByIdx = new Map<number, LabelBox>();
-  for (const b of boxes) boxByIdx.set(b.edgeIdx, b);
-  const edges = layout.edges.map((e, idx) => {
-    const b = boxByIdx.get(idx);
-    if (!b) return e;
-    return {
-      ...e,
-      labelX: b.cx,
-      labelY: b.cy,
-      labelWidth: b.w,
-      labelHeight: b.h,
-      labelLines: b.lines,
-    };
-  });
-
-  return {
-    layout: { ...layout, edges },
-    unresolved: boxes.filter((b) => !b.resolved).map((b) => b.edgeIdx),
-  };
-}