@zvk/graphs 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @zvk/graphs Changelog
 
+## [0.1.4](https://github.com/brandon-schabel/zvk/compare/graphs-v0.1.3...graphs-v0.1.4) (2026-06-25)
+
+
+### Features
+
+* improve out-of-box DX and UI components ([#24](https://github.com/brandon-schabel/zvk/issues/24)) ([b01272a](https://github.com/brandon-schabel/zvk/commit/b01272a2b35099f5e1fa1dea5883687a0fb4c2e6))
+
+## [0.1.3](https://github.com/brandon-schabel/zvk/compare/graphs-v0.1.2...graphs-v0.1.3) (2026-06-20)
+
+
+### Features
+
+* improve package release workflow and repo maintainability ([#22](https://github.com/brandon-schabel/zvk/issues/22)) ([a41cb66](https://github.com/brandon-schabel/zvk/commit/a41cb66554496f241c5a8e30b29a76c8b8ca92b3))
+
 ## [0.1.2](https://github.com/brandon-schabel/zvk/compare/graphs-v0.1.1...graphs-v0.1.2) (2026-06-19)
 
 

package/README.md

@@ -456,3 +456,7 @@ after export validation.
 `bun run --filter @zvk/graphs verify:style-contract` checks the positive style
 surface: graph layers, public `.zvk-graphs*` selectors, graph token definitions,
 UI-token inheritance, state selectors, and forced-colors coverage.
+
+## Repo Skill
+
+Use `.codex/skills/use-zvk-graphs/SKILL.md` when maintaining this package.

package/dist/layout/dag.js

@@ -1,6 +1,7 @@
 import { createGraphIndex, detectGraphCycle, topologicalSortGraph } from "../algorithms.js";
 import { validateGraphLayout } from "../diagnostics.js";
 import { defaultGraphNodeSize, edgesWithPoints, getGraphEdgeLabelOverlapDiagnostics } from "./types.js";
+import { resolveGraphNodeSize } from "./node-size.js";
 function rankedPoint(rank, indexInRank, size, nodeGap, rankGap, direction) {
     if (direction === "left-right") {
         return {
@@ -77,7 +78,7 @@ export function layoutDagGraph(graph, options = {}) {
         return {
             ...node,
             position: rankedPoint(rank, indexInRank, size, nodeGap, rankGap, direction),
-            size: node.size ?? size
+            size: resolveGraphNodeSize(node, size)
         };
     });
     const nodeById = new Map(nodes.map((node) => [node.id, node]));

package/dist/layout/manual.js

@@ -1,5 +1,6 @@
 import { validateGraphLayout } from "../diagnostics.js";
 import { defaultGraphNodeSize, edgesWithPoints, getGraphEdgeLabelOverlapDiagnostics } from "./types.js";
+import { resolveGraphNodeSize } from "./node-size.js";
 function gridPosition(index, size) {
     const columns = 4;
     return {
@@ -24,7 +25,7 @@ export function layoutManualGraph(graph, options = {}) {
         return {
             ...node,
             position: node.position ?? fallbackPosition,
-            size: node.size ?? defaultNodeSize
+            size: resolveGraphNodeSize(node, defaultNodeSize)
         };
     });
     const nodeById = new Map(nodes.map((node) => [node.id, node]));

package/dist/layout/node-size.d.ts

@@ -0,0 +1,2 @@
+import type { GraphNode, GraphSize } from "../model.js";
+export declare function resolveGraphNodeSize(node: GraphNode, defaultSize: GraphSize): GraphSize;

package/dist/layout/node-size.js

@@ -0,0 +1,83 @@
+const baseTextPaddingX = 20;
+const labelCharacterWidth = 7;
+const metadataCharacterWidth = 6;
+const chromeCharacterWidth = 6;
+const chromeGap = 40;
+const topLaneHeight = 18;
+const metadataLineHeight = 12;
+const verticalPadding = 18;
+const labelLineHeightByDensity = {
+    comfortable: 14,
+    compact: 12,
+    dense: 11
+};
+function summaryValue(value) {
+    if (value === null) {
+        return "None";
+    }
+    if (typeof value === "string") {
+        return value.trim().length > 0 ? value : undefined;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return undefined;
+}
+function summaryMetadataRows(metadata) {
+    return (metadata ?? []).flatMap((item) => {
+        const value = summaryValue(item.value);
+        if (value === undefined || item.visibility !== "summary") {
+            return [];
+        }
+        return `${item.label}: ${value}`;
+    });
+}
+function nodeLabelLines(node) {
+    const lines = node.labelLines?.filter((line) => line.trim().length > 0);
+    return lines && lines.length > 0 ? lines : [node.label];
+}
+function nodeBadge(node) {
+    return node.presentation?.badge ?? node.presentation?.statusLabel;
+}
+function nodeGlyph(node) {
+    return node.presentation?.glyph ?? node.presentation?.statusGlyph;
+}
+function textWidth(text, characterWidth) {
+    return text.length * characterWidth + baseTextPaddingX;
+}
+function richNodeHeight(node, labelLineCount, summaryRowCount) {
+    const density = node.presentation?.density ?? "comfortable";
+    const labelLineHeight = labelLineHeightByDensity[density];
+    const hasTopLane = nodeGlyph(node) !== undefined || nodeBadge(node) !== undefined;
+    const topHeight = hasTopLane ? topLaneHeight : 0;
+    const labelHeight = labelLineCount * labelLineHeight;
+    const metadataHeight = summaryRowCount * metadataLineHeight;
+    const shapeReserve = node.presentation?.shape === "diamond" ? 12 : 0;
+    return topHeight + labelHeight + metadataHeight + verticalPadding + shapeReserve;
+}
+function richNodeWidth(node, labelLines, summaryRows) {
+    const glyph = nodeGlyph(node);
+    const badge = nodeBadge(node);
+    const labelWidth = Math.max(...labelLines.map((line) => textWidth(line, labelCharacterWidth)));
+    const metadataWidth = summaryRows.length > 0 ? Math.max(...summaryRows.map((row) => textWidth(row, metadataCharacterWidth))) : 0;
+    const chromeWidth = glyph || badge
+        ? (glyph?.length ?? 0) * chromeCharacterWidth + (badge?.length ?? 0) * chromeCharacterWidth + chromeGap
+        : 0;
+    const shapeReserve = node.presentation?.shape === "diamond" ? 24 : node.presentation?.shape === "circle" ? 12 : 0;
+    return Math.max(labelWidth, metadataWidth, chromeWidth) + shapeReserve;
+}
+export function resolveGraphNodeSize(node, defaultSize) {
+    if (node.size) {
+        return node.size;
+    }
+    const labelLines = nodeLabelLines(node);
+    const summaryRows = summaryMetadataRows(node.metadata);
+    const hasRichPresentation = labelLines.length > 1 || summaryRows.length > 0 || nodeGlyph(node) !== undefined || nodeBadge(node) !== undefined;
+    if (!hasRichPresentation) {
+        return defaultSize;
+    }
+    return {
+        width: Math.max(defaultSize.width, Math.ceil(richNodeWidth(node, labelLines, summaryRows))),
+        height: Math.max(defaultSize.height, Math.ceil(richNodeHeight(node, labelLines.length, summaryRows.length)))
+    };
+}

package/dist/layout/tree.js

@@ -1,6 +1,7 @@
 import { createGraphIndex, validateTreeGraph } from "../algorithms.js";
 import { validateGraphLayout } from "../diagnostics.js";
 import { defaultGraphNodeSize, edgesWithPoints, getGraphEdgeLabelOverlapDiagnostics } from "./types.js";
+import { resolveGraphNodeSize } from "./node-size.js";
 function orientPoint(depth, breadth, size, levelGap, direction) {
     if (direction === "left-right") {
         return {
@@ -57,7 +58,7 @@ export function layoutTreeGraph(graph, options = {}) {
         return {
             ...node,
             position: positions.get(node.id) ?? orientPoint(0, index * (size.width + siblingGap), size, levelGap, direction),
-            size: node.size ?? size
+            size: resolveGraphNodeSize(node, size)
         };
     });
     const nodeById = new Map(nodes.map((node) => [node.id, node]));

package/dist/layout/types.d.ts

@@ -78,6 +78,8 @@ export interface GraphBoundsOptions {
 }
 export interface GraphGroupBoundsOptions {
     readonly padding?: number;
+    readonly labelGap?: number;
+    readonly labelHeight?: number;
 }
 export interface DerivedGraphGroupBounds {
     readonly groupId: GraphId;

package/dist/layout/types.js

@@ -38,6 +38,54 @@ function parallelOffset(options) {
     }
     return (parallelIndex - (parallelCount - 1) / 2) * parallelGap;
 }
+function pointInsideNodeBounds(point, node) {
+    return (point.x >= node.position.x &&
+        point.x <= node.position.x + node.size.width &&
+        point.y >= node.position.y &&
+        point.y <= node.position.y + node.size.height);
+}
+function clipRoutePointToNodeBounds(node, from, to) {
+    if (!pointInsideNodeBounds(from, node)) {
+        return from;
+    }
+    const dx = to.x - from.x;
+    const dy = to.y - from.y;
+    if (dx === 0 && dy === 0) {
+        return from;
+    }
+    const minX = node.position.x;
+    const maxX = node.position.x + node.size.width;
+    const minY = node.position.y;
+    const maxY = node.position.y + node.size.height;
+    const candidates = [];
+    if (dx > 0) {
+        candidates.push((maxX - from.x) / dx);
+    }
+    else if (dx < 0) {
+        candidates.push((minX - from.x) / dx);
+    }
+    if (dy > 0) {
+        candidates.push((maxY - from.y) / dy);
+    }
+    else if (dy < 0) {
+        candidates.push((minY - from.y) / dy);
+    }
+    const routeT = candidates
+        .filter((candidate) => candidate > 0 && candidate <= 1)
+        .sort((left, right) => left - right)
+        .find((candidate) => {
+        const x = from.x + dx * candidate;
+        const y = from.y + dy * candidate;
+        return x >= minX - 0.0001 && x <= maxX + 0.0001 && y >= minY - 0.0001 && y <= maxY + 0.0001;
+    });
+    if (routeT === undefined) {
+        return from;
+    }
+    return {
+        x: normalizeNumber(from.x + dx * routeT),
+        y: normalizeNumber(from.y + dy * routeT)
+    };
+}
 function labelSide(edge, labelPosition) {
     const start = edge.points[0];
     const end = edge.points.at(-1);
@@ -107,6 +155,14 @@ function paddedLabelBounds(bounds, padding) {
         height: bounds.height + padding * 2
     };
 }
+function nodeLabelClearanceBounds(node, padding = 4) {
+    return {
+        x: node.position.x - padding,
+        y: node.position.y - padding,
+        width: node.size.width + padding * 2,
+        height: node.size.height + padding * 2
+    };
+}
 function labelBoundsOverlap(first, second) {
     const width = Math.min(first.x + first.width, second.x + second.width) - Math.max(first.x, second.x);
     const height = Math.min(first.y + first.height, second.y + second.height) - Math.max(first.y, second.y);
@@ -176,8 +232,88 @@ export function getGraphEdgeLabelOverlapDiagnostics(graph, options = {}) {
     }
     return diagnostics;
 }
+function labelOverlapsEndpointNodes(bounds, source, target) {
+    return {
+        source: labelBoundsOverlap(bounds, nodeLabelClearanceBounds(source)) !== undefined,
+        target: labelBoundsOverlap(bounds, nodeLabelClearanceBounds(target)) !== undefined
+    };
+}
+function shiftPoint(point, direction, distance) {
+    return {
+        x: normalizeNumber(point.x + direction.x * distance),
+        y: normalizeNumber(point.y + direction.y * distance)
+    };
+}
+function normalizeDirection(start, end) {
+    const dx = end.x - start.x;
+    const dy = end.y - start.y;
+    const length = Math.hypot(dx, dy);
+    if (length === 0) {
+        return undefined;
+    }
+    return {
+        x: dx / length,
+        y: dy / length
+    };
+}
+function labelBoundsAtPosition(edge, route, labelPosition) {
+    return deriveGraphEdgeLabelAnchor({
+        ...edge,
+        points: route.points,
+        labelPosition,
+        routeKind: route.kind
+    })?.bounds;
+}
+function clearEndpointLabelPosition(edge, route, source, target) {
+    if (!edge.label || !route.labelPosition) {
+        return route.labelPosition;
+    }
+    const initialBounds = labelBoundsAtPosition(edge, route, route.labelPosition);
+    if (!initialBounds) {
+        return route.labelPosition;
+    }
+    const initialOverlap = labelOverlapsEndpointNodes(initialBounds, source, target);
+    if (!initialOverlap.source && !initialOverlap.target) {
+        return route.labelPosition;
+    }
+    const start = route.points[0];
+    const end = route.points.at(-1);
+    if (!start || !end) {
+        return route.labelPosition;
+    }
+    const alongRoute = normalizeDirection(start, end);
+    if (!alongRoute) {
+        return route.labelPosition;
+    }
+    const awayFromSource = alongRoute;
+    const awayFromTarget = { x: -alongRoute.x, y: -alongRoute.y };
+    const normal = { x: -alongRoute.y, y: alongRoute.x };
+    const oppositeNormal = { x: alongRoute.y, y: -alongRoute.x };
+    const primaryDirections = initialOverlap.source && !initialOverlap.target
+        ? [awayFromSource, normal, oppositeNormal, awayFromTarget]
+        : initialOverlap.target && !initialOverlap.source
+            ? [awayFromTarget, normal, oppositeNormal, awayFromSource]
+            : [normal, oppositeNormal, awayFromSource, awayFromTarget];
+    for (const distance of [8, 16, 24, 32, 40, 48, 64, 80, 96]) {
+        for (const direction of primaryDirections) {
+            const candidate = shiftPoint(route.labelPosition, direction, distance);
+            const bounds = labelBoundsAtPosition(edge, route, candidate);
+            if (!bounds) {
+                continue;
+            }
+            const overlap = labelOverlapsEndpointNodes(bounds, source, target);
+            if (!overlap.source && !overlap.target) {
+                return candidate;
+            }
+        }
+    }
+    return route.labelPosition;
+}
 export function deriveGraphGroupBounds(graph, options = {}) {
     const padding = options.padding ?? 16;
+    const labelHeight = options.labelHeight ?? 18;
+    const labelGap = options.labelGap ?? 8;
+    const topPadding = Math.max(padding, labelHeight + labelGap);
     const groups = graph.groups ?? [];
     return groups.flatMap((group) => {
         const nodes = graph.nodes.filter((node) => node.groupId === group.id);
@@ -202,8 +338,8 @@ export function deriveGraphGroupBounds(graph, options = {}) {
             {
                 groupId: group.id,
                 nodeIds: nodes.map((node) => node.id),
-                position: { x: minX - padding, y: minY - padding },
-                size: { width: maxX - minX + padding * 2, height: maxY - minY + padding * 2 }
+                position: { x: minX - padding, y: minY - topPadding },
+                size: { width: maxX - minX + padding * 2, height: maxY - minY + topPadding + padding }
             }
         ];
     });
@@ -227,8 +363,10 @@ export function routeGraphEdge(source, target, options = {}) {
         const labelPosition = points[2];
         return labelPosition ? { kind, points, labelPosition } : { kind, points };
     }
-    const routedStart = { x: start.x + offset.x, y: start.y + offset.y };
-    const routedEnd = { x: end.x + offset.x, y: end.y + offset.y };
+    const offsetStart = { x: start.x + offset.x, y: start.y + offset.y };
+    const offsetEnd = { x: end.x + offset.x, y: end.y + offset.y };
+    const routedStart = clipRoutePointToNodeBounds(source, offsetStart, offsetEnd);
+    const routedEnd = clipRoutePointToNodeBounds(target, offsetEnd, offsetStart);
     if (kind === "curve") {
         const middle = midpoint(routedStart, routedEnd);
         const controlOffset = offsetPoint(routedStart, routedEnd, options.parallelGap ?? 24);
@@ -274,6 +412,21 @@ export function getGraphBounds(graph, options = {}) {
         ];
     });
     const edgePoints = includeEdges ? graph.edges.flatMap((edge) => edge.points) : [];
+    const edgeLabelPoints = includeEdges
+        ? graph.edges.flatMap((edge) => {
+            const labelAnchor = deriveGraphEdgeLabelAnchor(edge);
+            if (!labelAnchor) {
+                return [];
+            }
+            return [
+                { x: labelAnchor.bounds.x, y: labelAnchor.bounds.y },
+                {
+                    x: labelAnchor.bounds.x + labelAnchor.bounds.width,
+                    y: labelAnchor.bounds.y + labelAnchor.bounds.height
+                }
+            ];
+        })
+        : [];
     const groupPoints = deriveGraphGroupBounds(graph).flatMap((group) => {
         return [
             group.position,
@@ -283,7 +436,7 @@ export function getGraphBounds(graph, options = {}) {
             }
         ];
     });
-    const points = [...nodePoints, ...edgePoints, ...groupPoints];
+    const points = [...nodePoints, ...edgePoints, ...edgeLabelPoints, ...groupPoints];
     if (points.length === 0) {
         return {
             x: -padding,
@@ -316,8 +469,9 @@ export function edgeWithPoints(edge, nodes, options = {}) {
     if (!route) {
         return { ...edge, points: [] };
     }
-    return route.labelPosition
-        ? { ...edge, points: route.points, labelPosition: route.labelPosition, routeKind: route.kind }
+    const labelPosition = source && target ? clearEndpointLabelPosition(edge, route, source, target) : route.labelPosition;
+    return labelPosition
+        ? { ...edge, points: route.points, labelPosition, routeKind: route.kind }
         : { ...edge, points: route.points, routeKind: route.kind };
 }
 export function edgesWithPoints(edges, nodes, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvk/graphs",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Accessible SVG-first node and edge graph utilities, deterministic layouts, and static React renderers for ZVK applications.",
   "private": false,
   "type": "module",
@@ -70,6 +70,7 @@
     "test": "vitest run",
     "test:ssr": "vitest run tests/ssr --environment node",
     "test:exports": "vitest run tests/exports --environment node",
+    "test:docs-examples": "bun run build && vitest run tests/docs-examples --environment node",
     "test:types": "tsd",
     "validate:exports": "bun run scripts/validate-exports.mjs",
     "validate:source-policy": "bun run scripts/validate-source-policy.mjs",