@laitszkin/apollo-toolkit 3.10.0 → 3.11.1

package/init-project-html/lib/atlas/layout.js

@@ -0,0 +1,330 @@
+'use strict';
+
+// layout.js — wraps elkjs to lay out the macro atlas. Features are
+// nested compound nodes; submodules are leaf nodes inside them.
+// hierarchyHandling=INCLUDE_CHILDREN lets cross-cluster edges route
+// past intermediate nodes. The flatten step rebases every node and
+// edge section into absolute (root-relative) coordinates so render.js
+// can emit SVG without further math.
+//
+// Layout is async because elkjs returns a Promise even in Node.
+
+const ELK = require('elkjs');
+
+// Default fallback box. The actual width/height for each sub-module
+// is computed per node by measureSubmodule() so the role/description
+// fits without overflowing the rectangle.
+const SUB_WIDTH = 240;
+const SUB_HEIGHT = 92;
+
+// Box-sizing knobs (intrinsic SVG coordinates).
+const SUB_WIDTH_MIN = 220;
+const SUB_WIDTH_MAX = 360;
+const SUB_HEIGHT_MIN = 92;
+const SUB_HEIGHT_MAX = 220;
+const SUB_SIDE_PAD = 16;
+const SUB_TOP_PAD = 14;
+const SUB_BOTTOM_PAD = 14;
+const TITLE_LINE = 22;     // slug line
+const KIND_LINE = 16;      // kind chip line
+const ROLE_LINE = 16;      // each role line
+const KIND_GAP = 4;
+const ROLE_GAP = 8;
+const MAX_ROLE_LINES = 4;
+
+const CLUSTER_PAD_TOP = 60;
+const CLUSTER_PAD_SIDE = 24;
+const CLUSTER_PAD_BOTTOM = 28;
+const EDGE_LABEL_HEIGHT = 18;
+
+const KIND_LABELS = {
+  ui: 'UI',
+  api: 'API',
+  service: 'service',
+  db: 'database',
+  'pure-fn': 'pure function',
+  queue: 'queue',
+  external: 'external',
+};
+
+function estimateLabelWidth(text) {
+  if (!text) return 0;
+  return Math.min(220, Math.max(40, String(text).length * 7 + 16));
+}
+
+// Approximate render width of a string in the target font. The 0.6
+// factor is a deliberate over-estimate for our sans-serif stack so
+// the chosen width almost always leaves a little breathing room.
+function approxTextWidth(text, fontPx) {
+  return String(text || '').length * fontPx * 0.6;
+}
+
+function wrapToLines(text, maxChars) {
+  if (!text) return [];
+  const words = String(text).split(/\s+/).filter(Boolean);
+  const lines = [];
+  let current = '';
+  for (const word of words) {
+    if (!current) { current = word; continue; }
+    if ((current.length + 1 + word.length) <= maxChars) current = `${current} ${word}`;
+    else { lines.push(current); current = word; }
+  }
+  if (current) lines.push(current);
+  return lines;
+}
+
+// measureSubmodule picks a width + height that fit the slug, the kind
+// chip, and the wrapped role text. Both layout.js (when telling elkjs
+// how much room each node needs) and render.js (when actually drawing
+// the text inside the box) call it so the rendered text never spills
+// outside the rectangle the layout engine reserved.
+function measureSubmodule(sub) {
+  const slug = (sub && sub.slug) || '';
+  const kindLabel = KIND_LABELS[sub && sub.kind] || (sub && sub.kind) || 'service';
+  const role = (sub && sub.role) || '';
+
+  const slugW = approxTextWidth(slug, 14);
+  const kindW = approxTextWidth(kindLabel, 11);
+  const baseInner = Math.max(slugW, kindW);
+
+  // Aim to keep the role within ~3 lines: choose a width whose text
+  // area can hold ceil(roleLen / 3) characters, then clamp.
+  const roleLen = role.length;
+  let chosenInner;
+  if (!role) {
+    chosenInner = baseInner;
+  } else {
+    const targetCharsPerLine = Math.max(20, Math.ceil(roleLen / 3));
+    chosenInner = Math.max(baseInner, targetCharsPerLine * 11 * 0.55);
+  }
+  const width = Math.max(SUB_WIDTH_MIN, Math.min(SUB_WIDTH_MAX, Math.ceil(chosenInner + SUB_SIDE_PAD * 2)));
+
+  // With the chosen width fixed, wrap the role for real and count lines.
+  const innerW = width - SUB_SIDE_PAD * 2;
+  const charsPerLine = Math.max(12, Math.floor(innerW / (11 * 0.55)));
+  let roleLines = role ? wrapToLines(role, charsPerLine) : [];
+  if (roleLines.length > MAX_ROLE_LINES) {
+    roleLines = roleLines.slice(0, MAX_ROLE_LINES);
+    const last = roleLines[MAX_ROLE_LINES - 1];
+    roleLines[MAX_ROLE_LINES - 1] = last.length > 3 ? `${last.slice(0, -1)}…` : `${last}…`;
+  }
+
+  const roleBlock = roleLines.length > 0 ? ROLE_GAP + roleLines.length * ROLE_LINE : 0;
+  const intrinsicH = SUB_TOP_PAD + TITLE_LINE + KIND_GAP + KIND_LINE + roleBlock + SUB_BOTTOM_PAD;
+  const height = Math.max(SUB_HEIGHT_MIN, Math.min(SUB_HEIGHT_MAX, Math.ceil(intrinsicH)));
+
+  return { width, height, roleLines, kindLabel };
+}
+
+function endpointId(endpoint, ownerFeature) {
+  if (typeof endpoint === 'string') {
+    return `submodule::${ownerFeature}::${endpoint}`;
+  }
+  if (endpoint && endpoint.submodule) {
+    return `submodule::${endpoint.feature}::${endpoint.submodule}`;
+  }
+  if (endpoint && endpoint.feature) {
+    return `feature::${endpoint.feature}`;
+  }
+  return null;
+}
+
+function buildGraph(state) {
+  const children = (state.features || []).map((feature) => ({
+    id: `feature::${feature.slug}`,
+    labels: [{
+      id: `feature::${feature.slug}::label`,
+      text: feature.title || feature.slug,
+      width: estimateLabelWidth(feature.title || feature.slug),
+      height: 24,
+    }],
+    layoutOptions: {
+      'elk.padding': `[top=${CLUSTER_PAD_TOP},left=${CLUSTER_PAD_SIDE},bottom=${CLUSTER_PAD_BOTTOM},right=${CLUSTER_PAD_SIDE}]`,
+      'elk.spacing.nodeNode': '24',
+      'elk.algorithm': 'layered',
+      'elk.direction': 'DOWN',
+      'elk.layered.spacing.nodeNodeBetweenLayers': '36',
+      'elk.nodeLabels.placement': '[H_CENTER, V_TOP, INSIDE]',
+    },
+    children: (feature.submodules || []).map((sub) => {
+      const box = measureSubmodule(sub);
+      return {
+        id: `submodule::${feature.slug}::${sub.slug}`,
+        width: box.width,
+        height: box.height,
+        labels: [{
+          id: `submodule::${feature.slug}::${sub.slug}::label`,
+          text: sub.slug,
+          width: estimateLabelWidth(sub.slug),
+          height: 18,
+        }],
+      };
+    }),
+  }));
+
+  let nextEdgeId = 0;
+  const rootEdges = [];
+  const nestedEdges = new Map(); // feature slug → edges[]
+
+  function pushEdge(list, raw, sourceId, targetId) {
+    if (!sourceId || !targetId) return;
+    list.push({
+      id: raw.id || `e-${nextEdgeId++}`,
+      sources: [sourceId],
+      targets: [targetId],
+      labels: raw.label ? [{
+        id: `${raw.id || `e-${nextEdgeId}`}::label`,
+        text: raw.label,
+        width: estimateLabelWidth(raw.label),
+        height: EDGE_LABEL_HEIGHT,
+      }] : [],
+    });
+  }
+
+  for (const feature of state.features || []) {
+    const list = [];
+    for (const edge of feature.edges || []) {
+      pushEdge(list, edge, endpointId(edge.from, feature.slug), endpointId(edge.to, feature.slug));
+    }
+    if (list.length > 0) nestedEdges.set(feature.slug, list);
+  }
+  for (const edge of state.edges || []) {
+    pushEdge(rootEdges, edge, endpointId(edge.from), endpointId(edge.to));
+  }
+
+  for (const child of children) {
+    const slug = child.id.replace(/^feature::/, '');
+    if (nestedEdges.has(slug)) child.edges = nestedEdges.get(slug);
+  }
+
+  return {
+    id: 'root',
+    layoutOptions: {
+      'elk.algorithm': 'layered',
+      'elk.direction': 'RIGHT',
+      'elk.hierarchyHandling': 'INCLUDE_CHILDREN',
+      'elk.spacing.nodeNode': '60',
+      'elk.layered.spacing.nodeNodeBetweenLayers': '100',
+      'elk.padding': '[top=40,left=40,bottom=40,right=40]',
+      'elk.edgeRouting': 'ORTHOGONAL',
+      'elk.edgeLabels.inline': 'false',
+      'elk.edgeLabels.placement': 'CENTER',
+    },
+    children,
+    edges: rootEdges,
+  };
+}
+
+function collectAbsolute(node, offsetX, offsetY, acc) {
+  // node may be root, a cluster, or a leaf.
+  const absX = offsetX + (node.x || 0);
+  const absY = offsetY + (node.y || 0);
+
+  if (node.id && node.id.startsWith('feature::')) {
+    acc.features.push({
+      id: node.id,
+      slug: node.id.replace(/^feature::/, ''),
+      x: absX,
+      y: absY,
+      width: node.width || 0,
+      height: node.height || 0,
+      labels: (node.labels || []).map((l) => ({
+        text: l.text,
+        x: absX + (l.x || 0),
+        y: absY + (l.y || 0),
+        width: l.width || 0,
+        height: l.height || 0,
+      })),
+    });
+  } else if (node.id && node.id.startsWith('submodule::')) {
+    const parts = node.id.split('::');
+    acc.submodules.push({
+      id: node.id,
+      featureSlug: parts[1],
+      slug: parts[2],
+      x: absX,
+      y: absY,
+      width: node.width || SUB_WIDTH,
+      height: node.height || SUB_HEIGHT,
+      labels: (node.labels || []).map((l) => ({
+        text: l.text,
+        x: absX + (l.x || 0),
+        y: absY + (l.y || 0),
+        width: l.width || 0,
+        height: l.height || 0,
+      })),
+    });
+  }
+
+  for (const edge of node.edges || []) {
+    const sections = (edge.sections || []).map((section) => ({
+      startPoint: { x: section.startPoint.x + absX, y: section.startPoint.y + absY },
+      endPoint: { x: section.endPoint.x + absX, y: section.endPoint.y + absY },
+      bendPoints: (section.bendPoints || []).map((p) => ({ x: p.x + absX, y: p.y + absY })),
+    }));
+    const labels = (edge.labels || []).map((label) => ({
+      text: label.text,
+      x: absX + (label.x || 0),
+      y: absY + (label.y || 0),
+      width: label.width || 0,
+      height: label.height || 0,
+    }));
+    acc.edges.push({ id: edge.id, sections, labels });
+  }
+
+  for (const child of node.children || []) {
+    collectAbsolute(child, absX, absY, acc);
+  }
+}
+
+function assertNoOverlap(layout) {
+  const boxes = [];
+  for (const sub of layout.submodules) {
+    boxes.push({ id: sub.id, x: sub.x, y: sub.y, w: sub.width, h: sub.height });
+  }
+  for (let i = 0; i < boxes.length; i += 1) {
+    for (let j = i + 1; j < boxes.length; j += 1) {
+      const a = boxes[i];
+      const b = boxes[j];
+      const overlapX = a.x < b.x + b.w && b.x < a.x + a.w;
+      const overlapY = a.y < b.y + b.h && b.y < a.y + a.h;
+      if (overlapX && overlapY) {
+        throw new Error(`atlas layout: submodule rectangles overlap: ${a.id} vs ${b.id}`);
+      }
+    }
+  }
+}
+
+async function layoutMacro(state) {
+  if (!state.features || state.features.length === 0) {
+    return { width: 320, height: 160, features: [], submodules: [], edges: [], empty: true };
+  }
+  const elk = new ELK();
+  const graph = buildGraph(state);
+  const laidOut = await elk.layout(graph);
+  const acc = { features: [], submodules: [], edges: [] };
+  collectAbsolute(laidOut, 0, 0, acc);
+  const layout = {
+    width: laidOut.width || 0,
+    height: laidOut.height || 0,
+    features: acc.features,
+    submodules: acc.submodules,
+    edges: acc.edges,
+    empty: false,
+  };
+  assertNoOverlap(layout);
+  return layout;
+}
+
+module.exports = {
+  SUB_WIDTH,
+  SUB_HEIGHT,
+  SUB_WIDTH_MIN,
+  SUB_WIDTH_MAX,
+  SUB_HEIGHT_MIN,
+  SUB_HEIGHT_MAX,
+  layoutMacro,
+  assertNoOverlap,
+  buildGraph,
+  measureSubmodule,
+};