@zvk/graphs 0.1.1 → 0.1.2

package/dist/model.d.ts

@@ -8,11 +8,54 @@ export interface GraphSize {
     readonly width: number;
     readonly height: number;
 }
+export type GraphMetadataValue = string | number | boolean | null;
+export type GraphMetadataVisibility = "summary" | "detail";
+export type GraphTone = "neutral" | "info" | "success" | "warning" | "danger" | "destructive";
+export interface GraphAccessibilityText {
+    readonly label?: string;
+    readonly description?: string;
+}
+export interface GraphMetadataItem {
+    readonly key: string;
+    readonly label: string;
+    readonly value: GraphMetadataValue;
+    readonly visibility?: GraphMetadataVisibility;
+    readonly tone?: GraphTone;
+}
+export type GraphNodeShape = "rect" | "rounded" | "pill" | "circle" | "diamond";
+export type GraphNodeDensity = "comfortable" | "compact" | "dense";
+export interface GraphNodePresentation {
+    readonly shape?: GraphNodeShape;
+    readonly tone?: GraphTone;
+    readonly density?: GraphNodeDensity;
+    readonly glyph?: string;
+    readonly badge?: string;
+}
+export interface GraphStatusPresentation {
+    readonly statusLabel?: string;
+    readonly statusGlyph?: string;
+}
+export interface GraphGroup {
+    readonly id: GraphId;
+    readonly label: string;
+    readonly summary?: string;
+    readonly accessibility?: GraphAccessibilityText;
+    readonly metadata?: readonly GraphMetadataItem[];
+    readonly tone?: GraphTone;
+    readonly status?: string;
+    readonly position?: GraphPoint;
+    readonly size?: GraphSize;
+}
 export interface GraphNode<TData = unknown, TKind extends string = string> {
     readonly id: GraphId;
     readonly label: string;
     readonly kind?: TKind;
     readonly data?: TData;
+    readonly metadata?: readonly GraphMetadataItem[];
+    readonly summary?: string;
+    readonly accessibility?: GraphAccessibilityText;
+    readonly presentation?: GraphNodePresentation & GraphStatusPresentation;
+    readonly labelLines?: readonly string[];
     readonly position?: GraphPoint;
     readonly size?: GraphSize;
     readonly status?: string;
@@ -25,6 +68,9 @@ export interface GraphEdge<TData = unknown, TKind extends string = string> {
     readonly target: GraphId;
     readonly label?: string;
     readonly ariaLabel?: string;
+    readonly accessibility?: GraphAccessibilityText;
+    readonly summary?: string;
+    readonly metadata?: readonly GraphMetadataItem[];
     readonly kind?: TKind;
     readonly data?: TData;
     readonly directed?: boolean;
@@ -35,6 +81,7 @@ export interface GraphModel<TNodeData = unknown, TEdgeData = unknown, TNodeKind
     readonly title: string;
     readonly description?: string;
     readonly direction?: GraphDirection;
+    readonly groups?: readonly GraphGroup[];
     readonly nodes: readonly GraphNode<TNodeData, TNodeKind>[];
     readonly edges: readonly GraphEdge<TEdgeData, TEdgeKind>[];
 }

package/dist/serialization.d.ts

@@ -0,0 +1,14 @@
+import type { GraphModel } from "./model.js";
+export type GraphJsonPrimitive = string | number | boolean | null;
+export type GraphJsonValue = GraphJsonPrimitive | readonly GraphJsonValue[] | GraphJsonObject;
+export interface GraphJsonObject {
+    readonly [key: string]: GraphJsonValue;
+}
+export interface GraphJsonNormalizationOptions {
+    readonly sortItems?: boolean;
+}
+export interface GraphJsonStringifyOptions extends GraphJsonNormalizationOptions {
+    readonly space?: number | string;
+}
+export declare function normalizeGraphForJson<TNodeData = unknown, TEdgeData = unknown, TNodeKind extends string = string, TEdgeKind extends string = string>(graph: GraphModel<TNodeData, TEdgeData, TNodeKind, TEdgeKind>, options?: GraphJsonNormalizationOptions): GraphJsonObject;
+export declare function stringifyGraphForJson<TNodeData = unknown, TEdgeData = unknown, TNodeKind extends string = string, TEdgeKind extends string = string>(graph: GraphModel<TNodeData, TEdgeData, TNodeKind, TEdgeKind>, options?: GraphJsonStringifyOptions): string;

package/dist/serialization.js

@@ -0,0 +1,68 @@
+function normalizeJsonValue(value, seen = new WeakSet()) {
+    if (value === undefined || typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
+        return undefined;
+    }
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : null;
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value)) {
+            throw new TypeError("Cannot normalize cyclic graph JSON data.");
+        }
+        seen.add(value);
+        try {
+            return value.flatMap((item) => {
+                const normalized = normalizeJsonValue(item, seen);
+                return normalized === undefined ? [] : [normalized];
+            });
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    if (typeof value === "object") {
+        if (seen.has(value)) {
+            throw new TypeError("Cannot normalize cyclic graph JSON data.");
+        }
+        seen.add(value);
+        try {
+            const output = {};
+            for (const key of Object.keys(value).sort((left, right) => left.localeCompare(right))) {
+                const normalized = normalizeJsonValue(value[key], seen);
+                if (normalized !== undefined) {
+                    output[key] = normalized;
+                }
+            }
+            return output;
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    return undefined;
+}
+function sortById(items, sortItems) {
+    if (!items || !sortItems) {
+        return items;
+    }
+    return [...items].sort((left, right) => left.id.localeCompare(right.id));
+}
+function graphForJson(graph, options) {
+    const sortItems = options.sortItems === true;
+    const groups = sortById(graph.groups, sortItems);
+    return {
+        ...graph,
+        ...(groups !== undefined ? { groups: groups } : {}),
+        nodes: sortById(graph.nodes, sortItems),
+        edges: sortById(graph.edges, sortItems)
+    };
+}
+export function normalizeGraphForJson(graph, options = {}) {
+    return normalizeJsonValue(graphForJson(graph, options));
+}
+export function stringifyGraphForJson(graph, options = {}) {
+    return JSON.stringify(normalizeGraphForJson(graph, options), null, options.space);
+}

package/dist/styles.css

@@ -3,14 +3,20 @@
 
 /* src/styles/graph.css */
 @layer zvk-graphs-tokens {
-  :root {
+  :where(.zvk-graphs, .zvk-graphs__svg) {
     --zvk-graphs-canvas-bg: var(--zvk-ui-color-background, Canvas);
     --zvk-graphs-node-bg: var(--zvk-ui-color-surface, Canvas);
     --zvk-graphs-node-border: var(--zvk-ui-card-border, GrayText);
     --zvk-graphs-node-text: var(--zvk-ui-color-foreground, CanvasText);
+    --zvk-graphs-node-badge-text: var(--zvk-ui-color-muted-foreground, CanvasText);
+    --zvk-graphs-group-bg: var(--zvk-ui-color-muted, color-mix(in srgb, CanvasText 5%, Canvas));
+    --zvk-graphs-group-border: var(--zvk-ui-color-border, GrayText);
+    --zvk-graphs-group-label-text: var(--zvk-ui-color-muted-foreground, GrayText);
     --zvk-graphs-muted-text: var(--zvk-ui-color-muted-foreground, GrayText);
     --zvk-graphs-edge-stroke: var(--zvk-ui-color-border-strong, CanvasText);
     --zvk-graphs-edge-muted-stroke: var(--zvk-ui-color-border, GrayText);
+    --zvk-graphs-edge-label-bg: var(--zvk-ui-color-background, Canvas);
+    --zvk-graphs-edge-label-border: var(--zvk-ui-color-border, GrayText);
     --zvk-graphs-selected-bg: var(--zvk-ui-color-primary-soft, color-mix(in srgb, Highlight 12%, Canvas));
     --zvk-graphs-selected-stroke: var(--zvk-ui-color-primary, Highlight);
     --zvk-graphs-focus-outline: var(--zvk-ui-focus-ring, 0 0 0 3px Highlight);
@@ -23,6 +29,9 @@
     --zvk-graphs-node-shadow: var(--zvk-ui-shadow-xs, none);
     --zvk-graphs-edge-width: 1.5px;
     --zvk-graphs-selected-edge-width: 2.5px;
+    --zvk-graphs-font-primary: var(--zvk-ui-font-family-primary, var(--zvk-ui-font-family-sans, system-ui, sans-serif));
+    --zvk-graphs-font-secondary: var(--zvk-ui-font-family-secondary, var(--zvk-graphs-font-primary));
+    --zvk-graphs-font-tertiary: var(--zvk-ui-font-family-tertiary, var(--zvk-ui-font-family-mono, ui-monospace, monospace));
   }
 }
 
@@ -30,6 +39,7 @@
   :where(.zvk-graphs) {
     color: var(--zvk-graphs-node-text);
     background: var(--zvk-graphs-canvas-bg);
+    margin: 0;
   }
 
   :where(.zvk-graphs__svg) {
@@ -39,6 +49,41 @@
     overflow: visible;
   }
 
+  :where(.zvk-graphs__group-shape) {
+    fill: var(--zvk-graphs-group-bg);
+    stroke: var(--zvk-graphs-group-border);
+    stroke-dasharray: 8 4;
+    stroke-width: 1px;
+  }
+
+  :where(.zvk-graphs__group-label) {
+    fill: var(--zvk-graphs-group-label-text);
+    font: 700 12px var(--zvk-graphs-font-secondary);
+    pointer-events: none;
+  }
+
+  :where(.zvk-graphs__group[data-status="success"] .zvk-graphs__group-shape),
+  :where(.zvk-graphs__group[data-tone="success"] .zvk-graphs__group-shape) {
+    stroke: var(--zvk-graphs-success);
+  }
+
+  :where(.zvk-graphs__group[data-status="warning"] .zvk-graphs__group-shape),
+  :where(.zvk-graphs__group[data-tone="warning"] .zvk-graphs__group-shape) {
+    stroke: var(--zvk-graphs-warning);
+  }
+
+  :where(.zvk-graphs__group[data-status="danger"] .zvk-graphs__group-shape),
+  :where(.zvk-graphs__group[data-status="destructive"] .zvk-graphs__group-shape),
+  :where(.zvk-graphs__group[data-tone="danger"] .zvk-graphs__group-shape),
+  :where(.zvk-graphs__group[data-tone="destructive"] .zvk-graphs__group-shape) {
+    stroke: var(--zvk-graphs-destructive);
+  }
+
+  :where(.zvk-graphs__group[data-status="info"] .zvk-graphs__group-shape),
+  :where(.zvk-graphs__group[data-tone="info"] .zvk-graphs__group-shape) {
+    stroke: var(--zvk-graphs-info);
+  }
+
   :where(.zvk-graphs__edge) {
     fill: none;
     stroke: var(--zvk-graphs-edge-stroke);
@@ -50,19 +95,38 @@
     stroke-width: var(--zvk-graphs-selected-edge-width);
   }
 
+  :where(.zvk-graphs__edge-group[data-status="success"] .zvk-graphs__edge) {
+    stroke: var(--zvk-graphs-success);
+    stroke-width: calc(var(--zvk-graphs-edge-width) + 0.5px);
+  }
+
+  :where(.zvk-graphs__edge-group[data-status="warning"] .zvk-graphs__edge) {
+    stroke: var(--zvk-graphs-warning);
+    stroke-dasharray: 5 4;
+  }
+
+  :where(.zvk-graphs__edge-group[data-status="destructive"] .zvk-graphs__edge) {
+    stroke: var(--zvk-graphs-destructive);
+    stroke-dasharray: 2 3;
+    stroke-width: calc(var(--zvk-graphs-edge-width) + 0.75px);
+  }
+
   :where(.zvk-graphs__marker) {
     fill: var(--zvk-graphs-edge-stroke);
   }
 
   :where(.zvk-graphs__edge-label) {
     fill: var(--zvk-graphs-muted-text);
-    font: 12px system-ui, sans-serif;
-    paint-order: stroke;
-    stroke: var(--zvk-graphs-canvas-bg);
-    stroke-width: 3px;
+    font: 12px var(--zvk-graphs-font-primary);
     text-anchor: middle;
   }
 
+  :where(.zvk-graphs__edge-label-bg) {
+    fill: var(--zvk-graphs-edge-label-bg);
+    stroke: var(--zvk-graphs-edge-label-border);
+    stroke-width: 1px;
+  }
+
   :where(.zvk-graphs__node-shape) {
     fill: var(--zvk-graphs-node-bg);
     stroke: var(--zvk-graphs-node-border);
@@ -72,12 +136,57 @@
 
   :where(.zvk-graphs__node-label) {
     fill: var(--zvk-graphs-node-text);
-    font: 13px system-ui, sans-serif;
+    font: 13px var(--zvk-graphs-font-primary);
     dominant-baseline: middle;
     pointer-events: none;
     text-anchor: middle;
   }
 
+  :where(.zvk-graphs__node-glyph) {
+    fill: var(--zvk-graphs-muted-text);
+    font: 700 10px var(--zvk-graphs-font-secondary);
+    pointer-events: none;
+    text-anchor: start;
+  }
+
+  :where(.zvk-graphs__node-badge) {
+    fill: var(--zvk-graphs-node-badge-text);
+    font: 700 10px var(--zvk-graphs-font-secondary);
+    pointer-events: none;
+    text-anchor: end;
+  }
+
+  :where(.zvk-graphs__node-metadata-item) {
+    fill: var(--zvk-graphs-muted-text);
+    font: 10px var(--zvk-graphs-font-tertiary);
+    pointer-events: none;
+    text-anchor: middle;
+  }
+
+  :where(.zvk-graphs__node-metadata-item[data-tone="success"]) {
+    fill: var(--zvk-graphs-success);
+  }
+
+  :where(.zvk-graphs__node-metadata-item[data-tone="warning"]) {
+    fill: var(--zvk-graphs-warning);
+  }
+
+  :where(.zvk-graphs__node-metadata-item[data-tone="danger"]),
+  :where(.zvk-graphs__node-metadata-item[data-tone="destructive"]) {
+    fill: var(--zvk-graphs-destructive);
+  }
+
+  :where(.zvk-graphs__node-metadata-item[data-tone="info"]) {
+    fill: var(--zvk-graphs-info);
+  }
+
+  :where(.zvk-graphs__node-status) {
+    fill: var(--zvk-graphs-muted-text);
+    font: 700 10px var(--zvk-graphs-font-secondary);
+    pointer-events: none;
+    text-anchor: end;
+  }
+
   :where(.zvk-graphs__node-selection) {
     fill: var(--zvk-graphs-selected-bg);
     stroke: var(--zvk-graphs-selected-stroke);
@@ -86,6 +195,7 @@
 
   :where(.zvk-graphs__node[data-status="success"] .zvk-graphs__node-shape) {
     stroke: var(--zvk-graphs-success);
+    stroke-width: 2px;
   }
 
   :where(.zvk-graphs__node[data-status="warning"] .zvk-graphs__node-shape) {
@@ -95,6 +205,46 @@
 
   :where(.zvk-graphs__node[data-status="destructive"] .zvk-graphs__node-shape) {
     stroke: var(--zvk-graphs-destructive);
+    stroke-dasharray: 2 3;
+    stroke-width: 2px;
+  }
+
+  :where(.zvk-graphs__node[data-status="info"] .zvk-graphs__node-shape) {
+    stroke: var(--zvk-graphs-info);
+    stroke-dasharray: 8 3 2 3;
+  }
+
+  :where(.zvk-graphs__node[data-status="danger"] .zvk-graphs__node-shape),
+  :where(.zvk-graphs__node[data-tone="danger"] .zvk-graphs__node-shape),
+  :where(.zvk-graphs__node[data-tone="destructive"] .zvk-graphs__node-shape) {
+    stroke: var(--zvk-graphs-destructive);
+    stroke-dasharray: 2 3;
+    stroke-width: 2px;
+  }
+
+  :where(.zvk-graphs__node[data-tone="success"] .zvk-graphs__node-shape) {
+    stroke: var(--zvk-graphs-success);
+    stroke-width: 2px;
+  }
+
+  :where(.zvk-graphs__node[data-tone="warning"] .zvk-graphs__node-shape) {
+    stroke: var(--zvk-graphs-warning);
+    stroke-dasharray: 4 3;
+  }
+
+  :where(.zvk-graphs__node[data-tone="info"] .zvk-graphs__node-shape) {
+    stroke: var(--zvk-graphs-info);
+    stroke-dasharray: 8 3 2 3;
+  }
+
+  :where(.zvk-graphs__node[data-density="compact"] .zvk-graphs__node-label),
+  :where(.zvk-graphs__node[data-density="compact"] .zvk-graphs__node-metadata-item) {
+    font-size: 11px;
+  }
+
+  :where(.zvk-graphs__node[data-density="dense"] .zvk-graphs__node-label),
+  :where(.zvk-graphs__node[data-density="dense"] .zvk-graphs__node-metadata-item) {
+    font-size: 10px;
   }
 
   :where(.zvk-graphs__fallback) {
@@ -103,13 +253,65 @@
 
   :where(.zvk-graphs__fallback h3) {
     margin: 0.75rem 0 0.25rem;
-    font: 600 0.875rem system-ui, sans-serif;
+    font: 600 0.875rem var(--zvk-graphs-font-secondary);
   }
 
   :where(.zvk-graphs__fallback ul) {
     margin: 0;
     padding-inline-start: 1.25rem;
   }
+
+  :where(.zvk-graphs__fallback-details) {
+    display: grid;
+    grid-template-columns: max-content minmax(0, 1fr);
+    column-gap: 0.5rem;
+    margin: 0.25rem 0 0;
+    color: var(--zvk-graphs-muted-text);
+    font: 0.8125rem var(--zvk-graphs-font-primary);
+  }
+
+  :where(.zvk-graphs__fallback-details dt) {
+    font-weight: 600;
+  }
+
+  :where(.zvk-graphs__fallback-details dd) {
+    margin: 0;
+  }
+
+  @media (forced-colors: active) {
+    :where(.zvk-graphs__edge),
+    :where(.zvk-graphs__group-shape),
+    :where(.zvk-graphs__node-shape),
+    :where(.zvk-graphs__edge-label-bg),
+    :where(.zvk-graphs__node-selection) {
+      forced-color-adjust: auto;
+      stroke: CanvasText;
+    }
+
+    :where(.zvk-graphs__node-shape),
+    :where(.zvk-graphs__group-shape),
+    :where(.zvk-graphs__edge-label-bg) {
+      fill: Canvas;
+    }
+
+    :where(.zvk-graphs__node-label),
+    :where(.zvk-graphs__group-label),
+    :where(.zvk-graphs__node-badge),
+    :where(.zvk-graphs__node-glyph),
+    :where(.zvk-graphs__node-metadata-item),
+    :where(.zvk-graphs__edge-label) {
+      fill: CanvasText;
+    }
+
+    :where(.zvk-graphs__marker) {
+      fill: CanvasText;
+    }
+
+    :where(.zvk-graphs__node[data-selected="true"] .zvk-graphs__node-selection),
+    :where(.zvk-graphs__edge-group[data-selected="true"] .zvk-graphs__edge) {
+      stroke: Highlight;
+    }
+  }
 }