@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/dist/widgets/c4/elk-layout.js

@@ -0,0 +1,455 @@
+// elk-layout.ts — ELK.js layered auto-layout for C4 diagrams, and the mapping
+// from a C4 element to its SvelteFlow node type. An element with a non-empty
+// `containers` array becomes a nested parent box (a boundary) whatever its
+// `kind`.
+//
+// Every layout goes through runElk: in a browser it runs in one shared module
+// worker (elk-worker.js), so a 200-element layout no longer blocks frames;
+// where no worker can start (SSR, jsdom) or the worker dies, it runs on the
+// main thread, with a fresh ELK per call (a shared instance raced between
+// layouts).
+//
+// computeElkGraph also returns ELK's orthogonal edge routes (absolute points,
+// keyed by the relationship's index in `diagram.relationships`) and a box for
+// each label, which ELK reserves space for, so edges go around nodes and labels
+// do not stack. ELK reports an edge's points relative to its `container` (the
+// lowest common ancestor of its ends); they are offset back to absolute here.
+//
+// A level that comes out far wider than tall (peers sharing a layer, a fan-in of
+// long labels) is laid out once more for reading (runReadable): layers capped,
+// placement compact, middle labels wrapped. A level that fits keeps its first layout.
+import ELK, {} from 'elkjs/lib/elk.bundled.js';
+import { childrenOf } from './semantic.js';
+// No-op on a page. It puts the worker module in a dev server's module graph, which is what lets
+// Vite serve the worker URL when this package is a linked (file:) copy outside the host's root.
+import './elk-worker.js';
+// Default node dimensions by element shape
+const DIMENSIONS = {
+    person: { width: 160, height: 140 },
+    database: { width: 180, height: 130 },
+    queue: { width: 200, height: 110 },
+    group: { width: 280, height: 200 },
+    default: { width: 200, height: 110 },
+};
+/** The text an edge's label shows: its label, then [technology]. */
+export function edgeLabelText(r) {
+    const parts = [];
+    if (r.label)
+        parts.push(r.label);
+    if (r.technology)
+        parts.push(`[${r.technology}]`);
+    return parts.join(' ');
+}
+/** ELK needs a label's size up front; this matches the 11px/500 pill C4Diagram draws. */
+const labelSize = (text) => ({ width: Math.ceil(text.length * 6.3) + 16, height: 20 });
+let makeWorker = () => typeof Worker === 'undefined'
+    ? null
+    : new Worker(new URL('./elk-worker.js', import.meta.url), { type: 'module' });
+/** undefined: not started yet; null: none (no Worker here, or it died). */
+let worker;
+const pending = new Map();
+let seq = 0;
+const WORKER_LOST = Symbol('elk worker lost');
+const ELK_ALGORITHMS = ['layered', 'stress', 'mrtree', 'radial', 'force', 'disco', 'sporeOverlap', 'sporeCompaction', 'rectpacking'];
+/** Swap how the layout worker is made (null: main thread only) and drop the running one. For tests. */
+export function setElkWorkerFactory(factory) {
+    makeWorker = factory;
+    worker = undefined;
+}
+function startWorker() {
+    if (worker !== undefined)
+        return worker;
+    try {
+        worker = makeWorker();
+    }
+    catch {
+        worker = null;
+    }
+    const w = worker;
+    // The same algorithms elkjs registers when it builds a worker itself; replied to, never awaited.
+    w?.postMessage({ id: 0, cmd: 'register', algorithms: ELK_ALGORITHMS });
+    w?.addEventListener('message', (e) => {
+        const { id, data, error } = (e.data ?? {});
+        const p = id === undefined ? undefined : pending.get(id);
+        if (!p || id === undefined)
+            return;
+        pending.delete(id);
+        if (error !== undefined)
+            p.reject(error);
+        else
+            p.resolve(data);
+    });
+    // A worker that fails to load or throws is done for: what it held, and every later layout,
+    // runs on the main thread.
+    // ponytail: any error retires the worker for the page; restart it if one bad graph ever matters.
+    w?.addEventListener('error', () => {
+        if (worker === w)
+            worker = null;
+        const lost = [...pending.values()];
+        pending.clear();
+        for (const p of lost)
+            p.reject(WORKER_LOST);
+    });
+    return w;
+}
+/** Lay out an ELK graph: in the worker when there is one, else on the main thread. */
+export async function runElk(graph) {
+    const w = startWorker();
+    if (w) {
+        try {
+            return await new Promise((resolve, reject) => {
+                const id = ++seq;
+                pending.set(id, { resolve, reject });
+                w.postMessage({ id, cmd: 'layout', graph, layoutOptions: {}, options: {} });
+            });
+        }
+        catch (err) {
+            if (err !== WORKER_LOST)
+                throw err;
+        }
+    }
+    return new ELK().layout(graph);
+}
+/** Wider than this (width / height) and than WIDE_PX, a level is laid out again by runReadable. */
+export const WIDE = 2.5;
+/** Narrower than this, a fit into a usual canvas stays above FIT_MIN_ZOOM, so the first layout stands. */
+export const WIDE_PX = 2000;
+/** The widest a middle label is laid out (and drawn) on a level laid out again. */
+export const LABEL_CAP = 180;
+/** `graph` with every layer capped at five nodes, compact placement and middle labels wrapped at LABEL_CAP. */
+export function readable(graph) {
+    const opts = {
+        'elk.layered.layering.strategy': 'COFFMAN_GRAHAM',
+        'elk.layered.layering.coffmanGraham.layerBound': '5',
+        'elk.layered.nodePlacement.strategy': 'SIMPLE',
+    };
+    const walk = (n) => ({
+        ...n,
+        ...(n.children?.length ? { layoutOptions: { ...n.layoutOptions, ...opts }, children: n.children.map(walk) } : {}),
+        ...(n.edges ? {
+            edges: n.edges.map((e) => ({
+                ...e,
+                labels: e.labels?.map((l) => {
+                    if (l.layoutOptions?.['elk.edgeLabels.placement'] || (l.width ?? 0) <= LABEL_CAP)
+                        return l;
+                    const lines = Math.ceil(((l.width ?? 0) - 16) / (LABEL_CAP - 16));
+                    return { ...l, width: LABEL_CAP, height: 20 + (lines - 1) * 14 };
+                }),
+            })),
+        } : {}),
+    });
+    return walk(graph);
+}
+/** runElk, then once more through `readable` when the result is wider than WIDE and WIDE_PX. */
+export async function runReadable(graph) {
+    const out = await runElk(graph);
+    const w = out.width ?? 0;
+    return w > WIDE_PX && w > WIDE * (out.height ?? 0) ? runElk(readable(graph)) : out;
+}
+/** Determine ELK node dimensions for a given C4 element */
+export function getNodeDimensions(el) {
+    // Person: an explicit kind, or no technology, type, containers, or components
+    const isPerson = el.kind
+        ? el.kind === 'person'
+        : !('technology' in el) && !('type' in el) && !('containers' in el) && !('components' in el);
+    if (isPerson)
+        return DIMENSIONS.person;
+    const subtype = 'type' in el ? el.type : undefined;
+    if (subtype === 'database')
+        return DIMENSIONS.database;
+    if (subtype === 'queue')
+        return DIMENSIONS.queue;
+    return DIMENSIONS.default;
+}
+/**
+ * Compute ELK-based layout for a C4 diagram.
+ *
+ * Strategy:
+ * - For context/container views: systems with containers become ELK parent nodes,
+ *   their containers become ELK children — giving proper nested group boxes.
+ * - Relationships map to ELK edges.
+ * - Returns a flat Map<id, LayoutPosition> for all elements.
+ */
+export async function computeElkLayout(diagram, options = {}) {
+    return (await computeElkGraph(diagram, options)).positions;
+}
+/** computeElkLayout plus ELK's edge routes and label boxes (empty if ELK failed). */
+export async function computeElkGraph(diagram, options = {}) {
+    const { direction = 'DOWN', nodeSpacing = 60, 
+    // Each labelled edge adds a label row between two layers, so a tighter
+    // layer gap keeps a labelled diagram from fitting at a tiny zoom.
+    layerSpacing = 56, } = options;
+    const positions = new Map();
+    const routes = new Map();
+    if (diagram.elements.length === 0)
+        return { positions, routes };
+    // Separate systems (potential parent nodes) from flat elements
+    const systems = diagram.elements.filter((el) => 'containers' in el && Array.isArray(el.containers) && (el.containers?.length ?? 0) > 0);
+    const systemIds = new Set(systems.map((s) => s.id));
+    // Build the ELK graph
+    // For container views, internal systems with containers become group (parent) nodes
+    const elkChildren = [];
+    const allElementIds = new Set();
+    for (const el of diagram.elements) {
+        allElementIds.add(el.id);
+        if (systemIds.has(el.id)) {
+            // This system has containers — make it a parent node in ELK
+            const sys = el;
+            const containers = sys.containers ?? [];
+            const childNodes = containers.map((c) => {
+                allElementIds.add(c.id);
+                const dim = getNodeDimensions(c);
+                return {
+                    id: c.id,
+                    width: dim.width,
+                    height: dim.height,
+                };
+            });
+            // Estimate parent size based on child count (ELK will refine it)
+            const estWidth = Math.max(280, containers.length * 220 + 60);
+            const estHeight = Math.max(200, Math.ceil(containers.length / 2) * 150 + 80);
+            elkChildren.push({
+                id: el.id,
+                width: estWidth,
+                height: estHeight,
+                children: childNodes,
+                layoutOptions: {
+                    'elk.algorithm': 'layered',
+                    'elk.direction': direction,
+                    'elk.spacing.nodeNode': String(nodeSpacing),
+                    'elk.layered.spacing.nodeNodeBetweenLayers': String(layerSpacing),
+                    'elk.padding': '[top=40,left=20,bottom=20,right=20]',
+                },
+            });
+        }
+        else {
+            // Flat leaf node
+            const dim = getNodeDimensions(el);
+            elkChildren.push({
+                id: el.id,
+                width: dim.width,
+                height: dim.height,
+            });
+        }
+    }
+    // Map relationships to ELK edges (only between known elements), keyed by the
+    // relationship's own index so routes map back to it.
+    const elkEdges = [];
+    diagram.relationships.forEach((r, i) => {
+        if (!allElementIds.has(r.from) || !allElementIds.has(r.to))
+            return;
+        const text = edgeLabelText(r);
+        elkEdges.push({
+            id: `edge-${i}`,
+            sources: [r.from],
+            targets: [r.to],
+            ...(text ? { labels: [{ text, ...labelSize(text) }] } : {}),
+        });
+    });
+    const graph = {
+        id: 'root',
+        layoutOptions: {
+            'elk.algorithm': 'layered',
+            'elk.direction': direction,
+            'elk.spacing.nodeNode': String(nodeSpacing),
+            'elk.layered.spacing.nodeNodeBetweenLayers': String(layerSpacing),
+            'elk.hierarchyHandling': 'INCLUDE_CHILDREN',
+            'elk.layered.considerModelOrder.strategy': 'NODES_AND_EDGES',
+        },
+        children: elkChildren,
+        edges: elkEdges,
+    };
+    try {
+        const read = readLayout(await runReadable(graph));
+        for (const [id, box] of read.positions)
+            positions.set(id, box);
+        for (const [id, e] of read.edges) {
+            const index = Number(id.slice('edge-'.length));
+            if (Number.isNaN(index))
+                continue;
+            routes.set(index, { points: e.points, ...(e.labels[0] ? { label: e.labels[0] } : {}) });
+        }
+    }
+    catch (err) {
+        console.error('[C4 ELK layout error]', err);
+        // Fallback: simple grid layout if ELK fails
+        let col = 0;
+        let row = 0;
+        const cols = Math.ceil(Math.sqrt(diagram.elements.length));
+        for (const el of diagram.elements) {
+            const dim = getNodeDimensions(el);
+            positions.set(el.id, {
+                x: col * (dim.width + nodeSpacing),
+                y: row * (dim.height + layerSpacing),
+                width: dim.width,
+                height: dim.height,
+            });
+            col++;
+            if (col >= cols) {
+                col = 0;
+                row++;
+            }
+        }
+    }
+    return { positions, routes };
+}
+/**
+ * Absolute boxes for every laid-out node, and each edge's absolute points and label boxes (in the
+ * order the labels were given). ELK reports an edge relative to its container; offset it back.
+ */
+function readLayout(laid) {
+    const positions = new Map();
+    const walk = (node, ox, oy) => {
+        for (const child of node.children ?? []) {
+            const x = (child.x ?? 0) + ox;
+            const y = (child.y ?? 0) + oy;
+            positions.set(child.id, {
+                x,
+                y,
+                width: child.width ?? DIMENSIONS.default.width,
+                height: child.height ?? DIMENSIONS.default.height,
+            });
+            walk(child, x, y);
+        }
+    };
+    walk(laid, 0, 0);
+    const edges = new Map();
+    const collect = (node) => {
+        for (const e of (node.edges ?? [])) {
+            const section = e.sections?.[0];
+            if (!section)
+                continue;
+            const box = e.container && e.container !== 'root' ? positions.get(e.container) : undefined;
+            const ox = box?.x ?? 0;
+            const oy = box?.y ?? 0;
+            const pts = [section.startPoint, ...(section.bendPoints ?? []), section.endPoint];
+            edges.set(e.id, {
+                points: pts.map((p) => ({ x: p.x + ox, y: p.y + oy })),
+                labels: (e.labels ?? [])
+                    .filter((l) => l.x !== undefined && l.y !== undefined)
+                    .map((l) => ({ x: (l.x ?? 0) + ox, y: (l.y ?? 0) + oy, width: l.width ?? 0, height: l.height ?? 0 })),
+            });
+        }
+        for (const c of node.children ?? [])
+            collect(c);
+    };
+    collect(laid);
+    return { positions, edges };
+}
+/** Boundary label row height: ELK leaves it free above the children. */
+export const BOUNDARY_TOP = 48;
+/**
+ * Layout for semantic zoom: every drawn element, nested to any depth. A boundary is an ELK compound
+ * sized around its children (never smaller than `minBoundary`, so its label row fits); everything
+ * else is a leaf of `sizeOf`. Port badges are ELK end labels, so they sit beside the line right
+ * where it meets the boundary, with space reserved.
+ */
+export async function computeSemanticLayout(tree, vis, edges, sizeOf, minBoundary, options = {}) {
+    const { direction = 'DOWN', nodeSpacing = 60, layerSpacing = 56 } = options;
+    const vertical = direction === 'DOWN' || direction === 'UP';
+    const drawn = new Set(vis.visible);
+    const build = (id) => {
+        if (vis.boundaries.has(id)) {
+            const min = minBoundary(id);
+            const el = tree.byId.get(id);
+            return {
+                id,
+                layoutOptions: {
+                    'elk.padding': `[top=${BOUNDARY_TOP},left=24,bottom=24,right=24]`,
+                    'elk.nodeSize.constraints': 'MINIMUM_SIZE',
+                    // ELK reads a compound's minimum in its internal left-to-right frame, so
+                    // for a vertical layout it is (height, width). Measured, elkjs 0.11.
+                    'elk.nodeSize.minimum': vertical
+                        ? `(${Math.ceil(min.height)}, ${Math.ceil(min.width)})`
+                        : `(${Math.ceil(min.width)}, ${Math.ceil(min.height)})`,
+                },
+                children: (el ? childrenOf(el) : []).filter((c) => drawn.has(c.id)).map((c) => build(c.id)),
+            };
+        }
+        return { id, ...sizeOf(id) };
+    };
+    const label = (text, placement) => ({
+        text,
+        ...labelSize(text),
+        ...(placement === 'CENTER' ? {} : { width: labelSize(text).width + 10, layoutOptions: { 'elk.edgeLabels.placement': placement } }),
+    });
+    const order = new Map();
+    const elkEdges = edges.map((e) => {
+        const labels = [];
+        const kinds = [];
+        if (e.label)
+            (labels.push(label(e.label, 'CENTER')), kinds.push('label'));
+        if (e.fromBadge)
+            (labels.push(label(e.fromBadge, 'TAIL')), kinds.push('tail'));
+        if (e.toBadge)
+            (labels.push(label(e.toBadge, 'HEAD')), kinds.push('head'));
+        order.set(e.key, kinds);
+        return { id: e.key, sources: [e.from], targets: [e.to], labels };
+    });
+    const graph = {
+        id: 'root',
+        layoutOptions: {
+            'elk.algorithm': 'layered',
+            'elk.direction': direction,
+            'elk.spacing.nodeNode': String(nodeSpacing),
+            'elk.layered.spacing.nodeNodeBetweenLayers': String(layerSpacing),
+            'elk.hierarchyHandling': 'INCLUDE_CHILDREN',
+            'elk.layered.considerModelOrder.strategy': 'NODES_AND_EDGES',
+        },
+        children: vis.visible.filter((id) => tree.parent.get(id) === null).map(build),
+        edges: elkEdges,
+    };
+    const read = readLayout(await runReadable(graph));
+    const routes = new Map();
+    for (const [key, e] of read.edges) {
+        const route = { points: e.points };
+        (order.get(key) ?? []).forEach((kind, i) => {
+            if (e.labels[i])
+                route[kind] = e.labels[i];
+        });
+        routes.set(key, route);
+    }
+    return { positions: read.positions, routes };
+}
+/**
+ * Determine whether a given C4 element should render as a "group" node in SvelteFlow.
+ * A group node is a system that has children containers — it draws a dashed boundary box.
+ */
+export function isGroupNode(el) {
+    return 'containers' in el
+        && Array.isArray(el.containers)
+        && (el.containers?.length ?? 0) > 0;
+}
+/**
+ * Get the SvelteFlow node type string for a C4 element.
+ * An explicit `kind` wins; without one the shape is inferred from the fields
+ * present, exactly as before `kind` existed.
+ */
+export function getNodeType(el) {
+    if (el.kind) {
+        if (el.kind === 'person')
+            return 'person';
+        if (isGroupNode(el))
+            return 'group';
+        const sub = 'type' in el ? el.type : undefined;
+        if (sub === 'database' || sub === 'queue')
+            return sub;
+        // `code` (a file, a class) draws as a component node labelled "Code".
+        return el.kind === 'code' ? 'component' : el.kind;
+    }
+    const isPerson = !('technology' in el) && !('type' in el) && !('containers' in el) && !('components' in el);
+    if (isPerson)
+        return 'person';
+    if (isGroupNode(el))
+        return 'group';
+    const subtype = 'type' in el ? el.type : undefined;
+    if (subtype === 'database')
+        return 'database';
+    if (subtype === 'queue')
+        return 'queue';
+    if ('containers' in el)
+        return 'system';
+    if ('components' in el)
+        return 'container';
+    return 'system';
+}

package/dist/widgets/c4/elk-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/widgets/c4/elk-worker.js

@@ -0,0 +1,21 @@
+// elk-worker.js — the module worker C4 layouts run in (elk-layout.ts runElk starts it). elkjs's
+// layout engine, once loaded in a worker, installs its own `self.onmessage`
+// dispatcher, so loading it is the whole worker: it speaks elkjs's worker protocol
+// ({ id, cmd: 'register' | 'layout', ... } in, { id, data } or { id, error } out).
+//
+// elk.bundled.js loads the engine lazily, inside the ELK constructor, which then throws in a worker
+// (the fake worker it would build is a page-only export); the throw is expected and swallowed.
+// Anywhere else (a page, SSR) this module does nothing: elk-layout.ts imports it there only so a dev server
+// serving a linked (file:) copy of this package lets the worker URL load.
+//
+// Plain JS on purpose: hosts bundle it through `new Worker(new URL('./elk-worker.js', import.meta.url))`,
+// which must name a file that exists both in src and in the packaged dist.
+import ELK from 'elkjs/lib/elk.bundled.js';
+
+if ('WorkerGlobalScope' in globalThis) {
+  try {
+    void new ELK();
+  } catch {
+    // expected: see the header
+  }
+}

package/dist/widgets/c4/index.d.ts

@@ -0,0 +1,5 @@
+export { default as C4Diagram } from './C4Diagram.svelte';
+export { computeElkLayout, getNodeType, isGroupNode } from './elk-layout.js';
+export { childrenOf, indexTree, pathTo, codeView } from './semantic.js';
+export type { C4Tree, CodeSide, CodeView } from './semantic.js';
+export type { C4Kind, C4Status, C4Marker, C4Highlight, C4Reach, C4EdgeShape, C4Flow, C4FlowStep, C4Code, C4PortView, C4Person, C4System, C4Container, C4Component, C4Relationship, C4Element, C4Diagram as C4DiagramData, C4NodeData, LayoutNode, } from './types.js';

package/dist/widgets/c4/index.js

@@ -0,0 +1,6 @@
+// C4 Model diagram widget — the component, its data, live-state and semantic
+// zoom types, the layout utilities, and the tree helpers hosts share with it
+// (index an element tree, walk to an id, compose a code excerpt's side).
+export { default as C4Diagram } from './C4Diagram.svelte';
+export { computeElkLayout, getNodeType, isGroupNode } from './elk-layout.js';
+export { childrenOf, indexTree, pathTo, codeView } from './semantic.js';