@steffolino/diagram-kit-core 0.1.0

package/dist/structuralLayout.d.ts

@@ -0,0 +1,30 @@
+import type { DiagramGraph } from './graph.js';
+import type { PositionedGraph } from './layout.js';
+export interface StructuralLayoutOptions {
+    showDetails?: boolean;
+    /** Inner padding between a container's border and its children. Default 16. */
+    padding?: number;
+    /** Gap between sibling boxes, both within a row and between rows. Default 10. */
+    gap?: number;
+    /** Minimum leaf width — leaves with longer labels grow wider to fit, up to `maxLeafWidth`, when `nodeSizing` is "responsive". Default 140. */
+    leafWidth?: number;
+    /** Cap on how wide a single leaf can grow to fit its label. Default 420. */
+    maxLeafWidth?: number;
+    /** "responsive" (default): leaves grow to fit their label, up to `maxLeafWidth`. "fixed": every leaf is exactly `leafWidth` wide, and a label too long to fit gets truncated with an ellipsis instead. */
+    nodeSizing?: 'responsive' | 'fixed';
+    leafHeight?: number;
+    /** Space reserved at the top of a container for its own label. Default 30. */
+    headerHeight?: number;
+    /** Children wrap onto a new row once a row would exceed this width. Default 560. */
+    maxRowWidth?: number;
+}
+/**
+ * Nested-box layout from `DiagramNode.parentId` containment — a container
+ * is sized to fit its children (wrapped into rows), no connector lines are
+ * produced, and containment is read from nesting instead. This is the
+ * "structural" counterpart to `layoutGraph`'s node-and-edge DAG layout, for
+ * data that's naturally a tree (a directory walk, a context's internal
+ * layers) rather than an arbitrary graph.
+ */
+export declare function layoutStructural(graph: DiagramGraph, options?: StructuralLayoutOptions): PositionedGraph;
+//# sourceMappingURL=structuralLayout.d.ts.map

package/dist/structuralLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuralLayout.d.ts","sourceRoot":"","sources":["../src/structuralLayout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,aAAa,CAAA;AAIlE,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iFAAiF;IACjF,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,8IAA8I;IAC9I,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,0MAA0M;IAC1M,UAAU,CAAC,EAAE,YAAY,GAAG,OAAO,CAAA;IACnC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAqCD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,GAAE,uBAA4B,GAAG,eAAe,CAoF5G"}

package/dist/structuralLayout.js

@@ -0,0 +1,117 @@
+import { estimateNodeWidth, estimateTextWidth } from './textWidth.js';
+import { detailHeight } from './detailText.js';
+const DEFAULTS = {
+    showDetails: false,
+    padding: 16,
+    gap: 10,
+    leafWidth: 140,
+    maxLeafWidth: 420,
+    nodeSizing: 'responsive',
+    leafHeight: 40,
+    headerHeight: 30,
+    maxRowWidth: 560,
+};
+function wrapIntoRows(items, gap, maxRowWidth) {
+    const rows = [];
+    let row = [];
+    let rowWidth = 0;
+    for (const item of items) {
+        const nextWidth = rowWidth + (row.length > 0 ? gap : 0) + item.width;
+        if (row.length > 0 && nextWidth > maxRowWidth) {
+            rows.push(row);
+            row = [];
+            rowWidth = 0;
+        }
+        row.push(item);
+        rowWidth += (row.length > 1 ? gap : 0) + item.width;
+    }
+    if (row.length > 0)
+        rows.push(row);
+    return rows;
+}
+/**
+ * Nested-box layout from `DiagramNode.parentId` containment — a container
+ * is sized to fit its children (wrapped into rows), no connector lines are
+ * produced, and containment is read from nesting instead. This is the
+ * "structural" counterpart to `layoutGraph`'s node-and-edge DAG layout, for
+ * data that's naturally a tree (a directory walk, a context's internal
+ * layers) rather than an arbitrary graph.
+ */
+export function layoutStructural(graph, options = {}) {
+    const opts = { ...DEFAULTS, ...options };
+    const childrenByParent = new Map();
+    const nodeById = new Map(graph.nodes.map((n) => [n.id, n]));
+    for (const node of graph.nodes) {
+        const list = childrenByParent.get(node.parentId) ?? [];
+        list.push(node.id);
+        childrenByParent.set(node.parentId, list);
+    }
+    const sizeCache = new Map();
+    function measure(id) {
+        const cached = sizeCache.get(id);
+        if (cached)
+            return cached;
+        const node = nodeById.get(id);
+        const childIds = childrenByParent.get(id) ?? [];
+        let size;
+        if (childIds.length === 0) {
+            const width = estimateNodeWidth(node.label, node.badge, {
+                minWidth: opts.leafWidth,
+                maxWidth: opts.nodeSizing === 'fixed' ? opts.leafWidth : opts.maxLeafWidth,
+            });
+            size = { width, height: opts.leafHeight + detailHeight(node, width, opts.showDetails) };
+        }
+        else {
+            const childSizes = childIds.map(measure);
+            const rows = wrapIntoRows(childSizes, opts.gap, opts.maxRowWidth);
+            const contentWidth = Math.max(...rows.map((row) => row.reduce((sum, s, i) => sum + s.width + (i > 0 ? opts.gap : 0), 0)));
+            const contentHeight = rows.reduce((sum, row, i) => sum + Math.max(...row.map((s) => s.height)) + (i > 0 ? opts.gap : 0), 0);
+            // A container must also be wide enough for its own header label —
+            // otherwise a container with few/narrow children but a long name
+            // (e.g. a deeply-nested directory) overflows its own header text.
+            // In "fixed" mode the header is capped instead (and truncated when
+            // rendered), matching leaves not growing either.
+            const rawHeaderWidth = estimateTextWidth(node.label, 12) + 40;
+            const headerWidth = opts.nodeSizing === 'fixed' ? Math.min(rawHeaderWidth, opts.leafWidth) : rawHeaderWidth;
+            size = {
+                width: Math.max(contentWidth + opts.padding * 2, headerWidth),
+                height: contentHeight + opts.padding * 2 + opts.headerHeight,
+            };
+            size.height += detailHeight(node, size.width, opts.showDetails);
+        }
+        sizeCache.set(id, size);
+        return size;
+    }
+    for (const node of graph.nodes)
+        measure(node.id);
+    const positioned = [];
+    function place(id, x, y) {
+        const size = sizeCache.get(id);
+        positioned.push({ id, x: x + size.width / 2, y: y + size.height / 2, width: size.width, height: size.height });
+        const childIds = childrenByParent.get(id) ?? [];
+        if (childIds.length === 0)
+            return;
+        const children = childIds.map((childId) => ({ id: childId, ...sizeCache.get(childId) }));
+        const rows = wrapIntoRows(children, opts.gap, opts.maxRowWidth);
+        let cursorY = y + opts.padding + opts.headerHeight + detailHeight(nodeById.get(id), size.width, opts.showDetails);
+        for (const row of rows) {
+            let cursorX = x + opts.padding;
+            const rowHeight = Math.max(...row.map((c) => c.height));
+            for (const child of row) {
+                place(child.id, cursorX, cursorY);
+                cursorX += child.width + opts.gap;
+            }
+            cursorY += rowHeight + opts.gap;
+        }
+    }
+    const roots = childrenByParent.get(undefined) ?? [];
+    let cursorX = 0;
+    for (const rootId of roots) {
+        place(rootId, cursorX, 0);
+        cursorX += sizeCache.get(rootId).width + opts.gap;
+    }
+    const width = Math.max(0, ...positioned.map((p) => p.x + p.width / 2));
+    const height = Math.max(0, ...positioned.map((p) => p.y + p.height / 2));
+    return { nodes: positioned, edges: [], width, height };
+}
+//# sourceMappingURL=structuralLayout.js.map

package/dist/structuralLayout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuralLayout.js","sourceRoot":"","sources":["../src/structuralLayout.ts"],"names":[],"mappings":"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"}

package/dist/structuralLayout.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=structuralLayout.test.d.ts.map

package/dist/structuralLayout.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuralLayout.test.d.ts","sourceRoot":"","sources":["../src/structuralLayout.test.ts"],"names":[],"mappings":""}

package/dist/structuralLayout.test.js

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import { createGraph } from './graph.js';
+import { layoutStructural } from './structuralLayout.js';
+describe('layoutStructural', () => {
+    it('produces no edges regardless of the input graph having any', () => {
+        const graph = createGraph([
+            { id: 'parent', label: 'Parent' },
+            { id: 'child', label: 'Child', parentId: 'parent' },
+        ], [{ id: 'x', source: 'parent', target: 'child' }]);
+        const positioned = layoutStructural(graph);
+        expect(positioned.edges).toEqual([]);
+    });
+    it('sizes a container to enclose its children', () => {
+        const graph = createGraph([
+            { id: 'parent', label: 'Parent' },
+            { id: 'a', label: 'A', parentId: 'parent' },
+            { id: 'b', label: 'B', parentId: 'parent' },
+        ]);
+        const positioned = layoutStructural(graph);
+        const parent = positioned.nodes.find((n) => n.id === 'parent');
+        const a = positioned.nodes.find((n) => n.id === 'a');
+        const b = positioned.nodes.find((n) => n.id === 'b');
+        const parentLeft = parent.x - parent.width / 2;
+        const parentRight = parent.x + parent.width / 2;
+        const parentTop = parent.y - parent.height / 2;
+        const parentBottom = parent.y + parent.height / 2;
+        for (const child of [a, b]) {
+            expect(child.x - child.width / 2).toBeGreaterThanOrEqual(parentLeft);
+            expect(child.x + child.width / 2).toBeLessThanOrEqual(parentRight);
+            expect(child.y - child.height / 2).toBeGreaterThanOrEqual(parentTop);
+            expect(child.y + child.height / 2).toBeLessThanOrEqual(parentBottom);
+        }
+    });
+    it('wraps children onto a new row once maxRowWidth is exceeded', () => {
+        const graph = createGraph([
+            { id: 'parent', label: 'Parent' },
+            { id: 'a', label: 'A', parentId: 'parent' },
+            { id: 'b', label: 'B', parentId: 'parent' },
+            { id: 'c', label: 'C', parentId: 'parent' },
+        ]);
+        const positioned = layoutStructural(graph, { leafWidth: 100, maxRowWidth: 250, gap: 10 });
+        const a = positioned.nodes.find((n) => n.id === 'a');
+        const c = positioned.nodes.find((n) => n.id === 'c');
+        // 3 leaves at 100 + 2 gaps of 10 = 320 > maxRowWidth 250, so the third
+        // leaf should wrap onto a second row (different y than the first).
+        expect(c.y).toBeGreaterThan(a.y);
+    });
+    it('sizes a leaf wide enough for a long label', () => {
+        const graph = createGraph([
+            { id: 'short', label: 'A' },
+            { id: 'long', label: 'A Much Much Longer Node Label' },
+        ]);
+        const positioned = layoutStructural(graph);
+        const short = positioned.nodes.find((n) => n.id === 'short');
+        const long = positioned.nodes.find((n) => n.id === 'long');
+        expect(long.width).toBeGreaterThan(short.width);
+    });
+    it('clamps leaf width in "fixed" sizing mode', () => {
+        const graph = createGraph([{ id: 'long', label: 'A Much Much Longer Node Label Than Default' }]);
+        const positioned = layoutStructural(graph, { nodeSizing: 'fixed', leafWidth: 140 });
+        expect(positioned.nodes[0].width).toBe(140);
+    });
+    it('places multiple root nodes side by side without overlapping', () => {
+        const graph = createGraph([
+            { id: 'root1', label: 'Root 1' },
+            { id: 'root2', label: 'Root 2' },
+        ]);
+        const positioned = layoutStructural(graph);
+        const root1 = positioned.nodes.find((n) => n.id === 'root1');
+        const root2 = positioned.nodes.find((n) => n.id === 'root2');
+        expect(root2.x - root2.width / 2).toBeGreaterThanOrEqual(root1.x + root1.width / 2);
+    });
+});
+//# sourceMappingURL=structuralLayout.test.js.map

package/dist/structuralLayout.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structuralLayout.test.js","sourceRoot":"","sources":["../src/structuralLayout.test.ts"],"names":[],"mappings":"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"}

package/dist/textWidth.d.ts

@@ -0,0 +1,18 @@
+export declare function estimateTextWidth(text: string, fontSize?: number): number;
+export interface NodeWidthOptions {
+    minWidth?: number;
+    maxWidth?: number;
+    fontSize?: number;
+    /** Fixed space consumed by the accent dot, gaps, and left/right padding. Default 46. */
+    horizontalPadding?: number;
+}
+/** Estimates the box width a node's chip/rect needs to fit its label (and badge) without the text overflowing, clamped to [minWidth, maxWidth]. */
+export declare function estimateNodeWidth(label: string, badge: string | undefined, options?: NodeWidthOptions): number;
+/**
+ * Shortens `label` with a trailing "…" until it fits `maxWidth`, for
+ * renderers (like static SVG) with no native text-truncation of their
+ * own — the React renderer gets this for free from CSS `text-overflow:
+ * ellipsis` instead.
+ */
+export declare function truncateLabel(label: string, maxWidth: number, fontSize?: number): string;
+//# sourceMappingURL=textWidth.d.ts.map

package/dist/textWidth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textWidth.d.ts","sourceRoot":"","sources":["../src/textWidth.ts"],"names":[],"mappings":"AAaA,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,MAAM,CASrE;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wFAAwF;IACxF,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,mJAAmJ;AACnJ,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAKlH;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,MAAM,CAOpF"}

package/dist/textWidth.js

@@ -0,0 +1,50 @@
+// Per-character width ratios (fraction of font-size), approximating a
+// typical system-ui/sans-serif proportional font. There's no canvas or DOM
+// available in a headless/static rendering context, so this is a portable
+// estimate rather than a real text measurement — good enough to size a box
+// to its label instead of using one fixed width for every node regardless
+// of content.
+const NARROW_CHARS = new Set(['i', 'l', 'j', '.', ',', "'", '!', ':', ';', '|', ' ', '"']);
+const WIDE_CHARS = new Set(['m', 'w', 'M', 'W']);
+const NARROW_WIDTH = 0.3;
+const WIDE_WIDTH = 0.92;
+const UPPERCASE_WIDTH = 0.66;
+const DEFAULT_WIDTH = 0.56;
+export function estimateTextWidth(text, fontSize = 12) {
+    let total = 0;
+    for (const ch of text) {
+        if (NARROW_CHARS.has(ch))
+            total += NARROW_WIDTH;
+        else if (WIDE_CHARS.has(ch))
+            total += WIDE_WIDTH;
+        else if (ch >= 'A' && ch <= 'Z')
+            total += UPPERCASE_WIDTH;
+        else
+            total += DEFAULT_WIDTH;
+    }
+    return total * fontSize;
+}
+/** Estimates the box width a node's chip/rect needs to fit its label (and badge) without the text overflowing, clamped to [minWidth, maxWidth]. */
+export function estimateNodeWidth(label, badge, options = {}) {
+    const { minWidth = 140, maxWidth = 420, fontSize = 12, horizontalPadding = 46 } = options;
+    let width = estimateTextWidth(label, fontSize) + horizontalPadding;
+    if (badge)
+        width += estimateTextWidth(badge, 10) + 10;
+    return Math.min(maxWidth, Math.max(minWidth, Math.ceil(width)));
+}
+/**
+ * Shortens `label` with a trailing "…" until it fits `maxWidth`, for
+ * renderers (like static SVG) with no native text-truncation of their
+ * own — the React renderer gets this for free from CSS `text-overflow:
+ * ellipsis` instead.
+ */
+export function truncateLabel(label, maxWidth, fontSize = 12) {
+    if (estimateTextWidth(label, fontSize) <= maxWidth)
+        return label;
+    let end = label.length - 1;
+    while (end > 0 && estimateTextWidth(label.slice(0, end) + '…', fontSize) > maxWidth) {
+        end--;
+    }
+    return label.slice(0, end) + '…';
+}
+//# sourceMappingURL=textWidth.js.map

package/dist/textWidth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textWidth.js","sourceRoot":"","sources":["../src/textWidth.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,2EAA2E;AAC3E,0EAA0E;AAC1E,2EAA2E;AAC3E,0EAA0E;AAC1E,cAAc;AACd,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;AAC1F,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;AAChD,MAAM,YAAY,GAAG,GAAG,CAAA;AACxB,MAAM,UAAU,GAAG,IAAI,CAAA;AACvB,MAAM,eAAe,GAAG,IAAI,CAAA;AAC5B,MAAM,aAAa,GAAG,IAAI,CAAA;AAE1B,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,QAAQ,GAAG,EAAE;IAC3D,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACtB,IAAI,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,KAAK,IAAI,YAAY,CAAA;aAC1C,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,KAAK,IAAI,UAAU,CAAA;aAC3C,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,IAAI,GAAG;YAAE,KAAK,IAAI,eAAe,CAAA;;YACpD,KAAK,IAAI,aAAa,CAAA;IAC7B,CAAC;IACD,OAAO,KAAK,GAAG,QAAQ,CAAA;AACzB,CAAC;AAUD,mJAAmJ;AACnJ,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,KAAyB,EAAE,UAA4B,EAAE;IACxG,MAAM,EAAE,QAAQ,GAAG,GAAG,EAAE,QAAQ,GAAG,GAAG,EAAE,QAAQ,GAAG,EAAE,EAAE,iBAAiB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAA;IACzF,IAAI,KAAK,GAAG,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,iBAAiB,CAAA;IAClE,IAAI,KAAK;QAAE,KAAK,IAAI,iBAAiB,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,EAAE,CAAA;IACrD,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,QAAgB,EAAE,QAAQ,GAAG,EAAE;IAC1E,IAAI,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,QAAQ;QAAE,OAAO,KAAK,CAAA;IAChE,IAAI,GAAG,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAA;IAC1B,OAAO,GAAG,GAAG,CAAC,IAAI,iBAAiB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,EAAE,QAAQ,CAAC,GAAG,QAAQ,EAAE,CAAC;QACpF,GAAG,EAAE,CAAA;IACP,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,CAAA;AAClC,CAAC"}

package/dist/theme.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Design tokens, not the fixed CSS "accent" class names used in earlier
+ * hand-built diagrams. A category (an adapter-defined string) is hashed
+ * onto a palette slot, so new categories degrade gracefully instead of
+ * falling back to an "unstyled" state.
+ */
+export interface ThemeColors {
+    background: string;
+    surface: string;
+    border: string;
+    text: string;
+    textMuted: string;
+    edge: string;
+    edgeProjected: string;
+    /** Fallback palette for categories with no explicit entry in `categoryColors` — hashed onto a slot so unregistered categories still degrade gracefully instead of going unstyled. */
+    categories: string[];
+    /** Named category -> color. Takes precedence over `categories`. This is what a color picker keyed by category name (e.g. "application", "external") should write to. */
+    categoryColors?: Record<string, string>;
+}
+export interface DiagramTheme {
+    light: ThemeColors;
+    dark: ThemeColors;
+}
+export interface GenerateThemeOptions {
+    /**
+     * Explicit categorical palette (hex or any CSS color string), used as-is
+     * for both light and dark mode. Set this when you already have brand
+     * colors — it skips generation entirely.
+     */
+    categories?: string[];
+    /**
+     * Named category -> color, e.g. `{ application: '#5F8D6B', external: '#3F8A8C' }`.
+     * Takes precedence over `categories`/generation for any category listed here;
+     * categories not listed still fall back to the generated/explicit palette.
+     */
+    categoryColors?: Record<string, string>;
+    /** Starting hue in degrees (0-360) for a generated palette. Default 250 (blue). */
+    seedHue?: number;
+    /** Degrees between each generated category's hue. Default 47 — avoids evenly-divided wheels landing two categories on near-identical hues. */
+    hueStep?: number;
+    /** How many categories to pre-generate when the graph's category list isn't known yet. Default 8. */
+    categoryCount?: number;
+    /** OKLCH chroma (colorfulness) for generated categories, roughly 0-0.4. Default 0.11 — restrained, not neon. */
+    chroma?: number;
+    /** Tints background/surface/border/edge with `seedHue` at very low chroma instead of pure gray, for a cohesive brand-matched neutral scale. Default false. */
+    tintNeutrals?: boolean;
+}
+/**
+ * Generates a full light/dark theme from a handful of parameters instead of
+ * hand-picked hex codes — pass an explicit `categories` palette if you have
+ * brand colors, or let it derive an evenly-spaced OKLCH palette from a seed
+ * hue. OKLCH (rather than HSL) keeps generated colors at consistent
+ * perceived lightness/vividness across hues, so e.g. yellow and blue
+ * categories read as equally prominent instead of the yellow blowing out.
+ */
+export declare function generateTheme(options?: GenerateThemeOptions): DiagramTheme;
+export declare const defaultTheme: DiagramTheme;
+/** Appends an alpha channel to a hex color, e.g. `withAlpha('#3B6EA5', 0.5)` -> `#3B6EA580`. */
+export declare function withAlpha(hex: string, alpha: number): string;
+/**
+ * Resolves a category string to a color for the given mode: an explicit
+ * `categoryColors[category]` entry wins if present, otherwise the category
+ * is hashed onto a slot in the fallback `categories` palette so unregistered
+ * categories still get a stable (if arbitrary) color instead of going
+ * unstyled.
+ */
+export declare function categoryColor(category: string | undefined, theme: DiagramTheme, mode?: 'light' | 'dark'): string;
+//# sourceMappingURL=theme.d.ts.map

package/dist/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,EAAE,MAAM,CAAA;IACrB,qLAAqL;IACrL,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,wKAAwK;IACxK,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAA;IAClB,IAAI,EAAE,WAAW,CAAA;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8IAA8I;IAC9I,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qGAAqG;IACrG,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,gHAAgH;IAChH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8JAA8J;IAC9J,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AA4CD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,YAAY,CAa9E;AAED,eAAO,MAAM,YAAY,EAAE,YAA8B,CAAA;AAEzD,gGAAgG;AAChG,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK5D;AAWD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,YAAY,EACnB,IAAI,GAAE,OAAO,GAAG,MAAgB,GAC/B,MAAM,CAOR"}

package/dist/theme.js

@@ -0,0 +1,94 @@
+import { formatHex } from 'culori';
+function oklchHex(l, c, h) {
+    return formatHex({ mode: 'oklch', l, c, h });
+}
+function generateCategories(options, mode) {
+    if (options.categories)
+        return options.categories;
+    const seedHue = options.seedHue ?? 250;
+    const hueStep = options.hueStep ?? 47;
+    const count = options.categoryCount ?? 8;
+    const chroma = options.chroma ?? 0.11;
+    const lightness = mode === 'light' ? 0.52 : 0.78;
+    return Array.from({ length: count }, (_, i) => oklchHex(lightness, chroma, (seedHue + i * hueStep) % 360));
+}
+function neutralScale(options, mode) {
+    const hue = options.seedHue ?? 250;
+    const c = options.tintNeutrals ? 0.02 : 0;
+    if (mode === 'light') {
+        return {
+            background: oklchHex(0.995, c, hue),
+            surface: oklchHex(0.97, c, hue),
+            border: oklchHex(0.87, c, hue),
+            text: oklchHex(0.22, c * 1.5, hue),
+            textMuted: oklchHex(0.48, c, hue),
+            edge: oklchHex(0.68, c, hue),
+            edgeProjected: oklchHex(0.83, c, hue),
+        };
+    }
+    return {
+        background: oklchHex(0.14, c, hue),
+        surface: oklchHex(0.19, c, hue),
+        border: oklchHex(0.28, c, hue),
+        text: oklchHex(0.92, c, hue),
+        textMuted: oklchHex(0.66, c, hue),
+        edge: oklchHex(0.42, c, hue),
+        edgeProjected: oklchHex(0.28, c, hue),
+    };
+}
+/**
+ * Generates a full light/dark theme from a handful of parameters instead of
+ * hand-picked hex codes — pass an explicit `categories` palette if you have
+ * brand colors, or let it derive an evenly-spaced OKLCH palette from a seed
+ * hue. OKLCH (rather than HSL) keeps generated colors at consistent
+ * perceived lightness/vividness across hues, so e.g. yellow and blue
+ * categories read as equally prominent instead of the yellow blowing out.
+ */
+export function generateTheme(options = {}) {
+    return {
+        light: {
+            ...neutralScale(options, 'light'),
+            categories: generateCategories(options, 'light'),
+            categoryColors: options.categoryColors,
+        },
+        dark: {
+            ...neutralScale(options, 'dark'),
+            categories: generateCategories(options, 'dark'),
+            categoryColors: options.categoryColors,
+        },
+    };
+}
+export const defaultTheme = generateTheme();
+/** Appends an alpha channel to a hex color, e.g. `withAlpha('#3B6EA5', 0.5)` -> `#3B6EA580`. */
+export function withAlpha(hex, alpha) {
+    const alphaHex = Math.round(alpha * 255)
+        .toString(16)
+        .padStart(2, '0');
+    return `${hex}${alphaHex}`;
+}
+function hashString(value) {
+    let hash = 0;
+    for (let i = 0; i < value.length; i++) {
+        hash = (hash << 5) - hash + value.charCodeAt(i);
+        hash |= 0;
+    }
+    return Math.abs(hash);
+}
+/**
+ * Resolves a category string to a color for the given mode: an explicit
+ * `categoryColors[category]` entry wins if present, otherwise the category
+ * is hashed onto a slot in the fallback `categories` palette so unregistered
+ * categories still get a stable (if arbitrary) color instead of going
+ * unstyled.
+ */
+export function categoryColor(category, theme, mode = 'light') {
+    const colors = theme[mode];
+    if (!category)
+        return colors.textMuted;
+    const named = colors.categoryColors?.[category];
+    if (named)
+        return named;
+    const index = hashString(category) % colors.categories.length;
+    return colors.categories[index];
+}
+//# sourceMappingURL=theme.js.map

package/dist/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@steffolino/diagram-kit-core",
+  "version": "0.1.0",
+  "description": "Normalized graph model, auto-layout, and theme tokens shared by every diagram-kit renderer and adapter.",
+  "license": "MIT",
+  "author": "Stefan Stretz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/steffolino/diagram-kit.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/steffolino/diagram-kit/tree/master/packages/core#readme",
+  "bugs": "https://github.com/steffolino/diagram-kit/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "diagram",
+    "graph",
+    "layout",
+    "dagre",
+    "visualization"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@dagrejs/dagre": "^1.1.4",
+    "culori": "^4.0.1"
+  },
+  "devDependencies": {
+    "@types/culori": "^4.0.1",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}