@danxbot/ui 10.0.1 → 11.0.0

package/dist/types/components/node-canvas/NodeCanvas.d.ts

@@ -1,48 +1,56 @@
-import type { CanvasNode, CanvasOrientation, NodeRenderer } from "./types";
+import type { CanvasGraph, CanvasGroup, CanvasNode, CanvasOrientation, CanvasPlacedEdge, NodeRenderer } from "./types";
 export interface NodeCanvasProps<Extra = unknown> {
-    /** The whole tree. The canvas walks into it; it never mutates it. */
-    root: CanvasNode<Extra>;
+    /** The whole graph — every node and edge, however many scopes it spans. Never mutated. */
+    graph: CanvasGraph<Extra>;
+    /** Named clusters nodes can belong to via `CanvasNode.groupId`. Flat — see `CanvasGroup`. */
+    groups?: readonly CanvasGroup[];
     /**
-     * What this canvas IS — "Org chart", "Dependency graph for the March build".
+     * What this canvas IS — "Import graph for the docs map", "Service dependency graph".
      *
-     * Required for the same reason `StatusChecklist.label` and
-     * `KanbanBoard.label` are: it is the accessible name of the whole structure,
-     * and somebody landing on it by keyboard has nothing else to tell them what
+     * Required for the same reason `StatusChecklist.label` and `KanbanBoard.label`
+     * are: it is the accessible name of the whole structure, and somebody landing
+     * on it by keyboard or in the list view has nothing else to tell them what
      * they are inside.
      */
     label: string;
     /**
      * The node body. Receives the consumer's own node type and a context of
-     * purely structural facts.
+     * purely structural facts — see `NodeRenderContext`.
      *
-     * A RENDER PROP RATHER THAN CHILDREN-AS-A-FUNCTION, because a canvas draws
-     * MANY nodes and `children` reads as one. `<NodeCanvas>{(node) => …}` looks
-     * like a single child and is really a template invoked N times, which is the
-     * ambiguity this library already avoids elsewhere (`ProvenanceDisclosure`
-     * takes `actions`, `Chat` takes a `components` map). It is optional: the
-     * default draws the `label` the node already declares and nothing else, so
-     * the component is usable with no wiring and the default introduces no
-     * vocabulary of its own.
+     * A RENDER PROP RATHER THAN CHILDREN-AS-A-FUNCTION, for the same reason
+     * `ProvenanceDisclosure` takes `actions` and `Chat` takes a `components` map:
+     * a canvas draws MANY nodes and `children` reads as one. Optional: the
+     * default draws the label, and a member count when this box stands in for a
+     * group or a condensed cycle.
+     *
+     * Called with a SYNTHETIC node for a collapsed group or cycle — `{id, label}`
+     * only, `Extra`'s own fields absent — since no single real node's `Extra`
+     * would be honest to hand back for a box standing in for several.
      */
     renderNode?: NodeRenderer<Extra>;
+    /**
+     * The hover summary's content. Defaults to the node's `label`. Return
+     * `null`/`undefined` to suppress the tooltip for a particular node.
+     */
+    renderSummary?: (node: CanvasNode<Extra>) => React.ReactNode;
+    /** A class name for one drawn edge, keyed on its (possibly aggregated) `kind`. */
+    edgeClassName?: (edge: CanvasPlacedEdge) => string | undefined;
     /** Which way the chart grows. See `CanvasOrientation`. */
     orientation?: CanvasOrientation;
-    /** Levels below the current root to draw. `1` is the root and its children. */
-    depth?: number;
     /** Along-axis extent of a node that does not declare its own, in px. */
     nodeWidth?: number;
     /** Cross-axis extent of a node that does not declare its own, in px. */
     nodeHeight?: number;
     /** Height of the scrolling viewport. Any CSS length. */
     height?: string;
-    /**
-     * Fired after the canvas re-roots, with the trail from the ORIGINAL root.
-     *
-     * Observation, not control: the canvas owns where it is. A consumer that
-     * needs to restore a position across a reload stores this and remounts with
-     * a different `root`.
-     */
-    onRootChange?: (node: CanvasNode<Extra>, path: CanvasNode<Extra>[]) => void;
+    /** Which group is currently drilled into. `null` is the top level. Controlled. */
+    expandedGroupId?: string | null;
+    /** Initial drilled-into group for uncontrolled use. Default `null` (top level). */
+    defaultExpandedGroupId?: string | null;
+    /** Fired whenever the drilled-into group changes, from either a click or the keyboard. */
+    onExpandedGroupIdChange?: (groupId: string | null) => void;
+    /** Fired when an ORDINARY node (not a group, not a cycle) is clicked. Navigation is the consumer's. */
+    onNodeClick?: (node: CanvasNode<Extra>) => void;
     /** Fired when a node drag commits. The offset is from its laid-out position. */
     onNodeDragEnd?: (event: {
         id: string;
@@ -55,4 +63,4 @@ export interface NodeCanvasProps<Extra = unknown> {
     disabled?: boolean;
     className?: string;
 }
-export declare function NodeCanvas<Extra = unknown>({ root, label, renderNode, orientation, depth, nodeWidth, nodeHeight, height, onRootChange, onNodeDragEnd, disabled, className, }: NodeCanvasProps<Extra>): import("react").JSX.Element;
+export declare function NodeCanvas<Extra = unknown>({ graph, groups, label, renderNode, renderSummary, edgeClassName, orientation, nodeWidth, nodeHeight, height, expandedGroupId, defaultExpandedGroupId, onExpandedGroupIdChange, onNodeClick, onNodeDragEnd, disabled, className, }: NodeCanvasProps<Extra>): import("react").JSX.Element;

package/dist/types/components/node-canvas/index.d.ts

@@ -1,3 +1,3 @@
 export { NodeCanvas, type NodeCanvasProps } from "./NodeCanvas";
-export { LAYOUT_DEFAULTS, layoutTree, pathToNode } from "./layout";
-export type { CanvasEdge, CanvasLayout, CanvasNode, CanvasOrientation, LayoutOptions, NodeRenderContext, NodeRenderer, PlacedNode, } from "./types";
+export { LAYOUT_DEFAULTS, edgePath, layoutGraph, neighbourhood } from "./layout";
+export type { CanvasCycleScope, CanvasEdge, CanvasGraph, CanvasGroup, CanvasLayout, CanvasNode, CanvasOrientation, CanvasPlacedEdge, CanvasScope, LayoutOptions, NodeRenderContext, NodeRenderer, PlacedNode, } from "./types";

package/dist/types/components/node-canvas/layout.d.ts

@@ -1,17 +1,29 @@
-import type { CanvasLayout, CanvasNode, LayoutOptions } from "./types";
+import type { CanvasGraph, CanvasGroup, CanvasLayout, CanvasPlacedEdge, CanvasScope, LayoutOptions } from "./types";
 export declare const LAYOUT_DEFAULTS: Required<LayoutOptions>;
 /**
- * Lay a tree out.
+ * Lay out one scope of a graph.
  *
- * Coordinates are plane-local and start at 0 on both axes: the caller decides
- * where the plane sits and how much padding surrounds it.
+ * `scope` is `null` for the top level, a `CanvasGroup.id` to draw that
+ * group's own members, or a `CanvasCycleScope` to draw a condensed cycle's
+ * own members (see that type's doc for why it is not just "another group
+ * id" — it skips this function's own condensing pre-pass on purpose).
+ * Coordinates are plane-local and start at 0 on both axes: the caller
+ * decides where the plane sits and how much padding surrounds it.
  */
-export declare function layoutTree<Extra>(root: CanvasNode<Extra>, options?: LayoutOptions): CanvasLayout<Extra>;
+export declare function layoutGraph<Extra>(graph: CanvasGraph<Extra>, groups: readonly CanvasGroup[], scope: CanvasScope, options?: LayoutOptions): CanvasLayout<Extra>;
+/** The SVG `d` attribute for one drawn edge. See `smoothPath` above. */
+export declare function edgePath(edge: CanvasPlacedEdge): string;
 /**
- * The ids from the ORIGINAL root down to `targetId`, inclusive.
+ * Every real node id reachable from `id` within `hops` steps, along either
+ * edge direction — the "1–2-hop neighbourhood" `NodeRenderContext.focusDistance`
+ * reports. Undirected on purpose: a node's neighbourhood, for the purpose of
+ * "what should stay legible while I'm reading this one", is what points at it
+ * as much as what it points at.
  *
- * `null` when the id is not in the tree, which the canvas treats as a
- * programming error rather than as an empty trail — a breadcrumb that silently
- * renders nothing is how a broken `rootId` looks like a styling bug.
+ * Keyed by the drawn (possibly condensed) ids, not raw graph node ids — the
+ * canvas calls this with whatever `CanvasPlacedEdge` already uses.
  */
-export declare function pathToNode<Extra>(root: CanvasNode<Extra>, targetId: string): CanvasNode<Extra>[] | null;
+export declare function neighbourhood(id: string, edges: readonly {
+    from: string;
+    to: string;
+}[], hops: number): Map<string, number>;

package/dist/types/components/node-canvas/types.d.ts

@@ -1,76 +1,165 @@
 import type { ReactNode } from "react";
 /**
- * One node of the tree.
+ * One node of the graph.
  *
- * `Extra` carries the consumer's own fields DOWN THE WHOLE TREE, so
- * `renderNode` receives their type rather than ours plus a cast:
+ * `Extra` carries the consumer's own fields, so `renderNode` receives their
+ * type rather than ours plus a cast:
  *
  * ```ts
- * type Task = { owner: string; done: boolean };
- * const root: CanvasNode<Task> = { id: "r", label: "Release", owner: "ada", done: false, children: [...] };
- * <NodeCanvas root={root} renderNode={(node) => <span>{node.owner}</span>} />
+ * type Service = { owner: string; deployed: boolean };
+ * const nodes: CanvasNode<Service>[] = [
+ *   { id: "api", label: "API", owner: "ada", deployed: true },
+ * ];
+ * <NodeCanvas graph={{ nodes, edges }} renderNode={(node) => <span>{node.owner}</span>} />
  * ```
- *
- * Written as an intersection rather than an interface with a type parameter
- * because the recursion has to carry `Extra` into `children` — an interface
- * cannot refer to its own instantiation that way without a self-referencing
- * constraint that every consumer then has to spell out.
  */
 export type CanvasNode<Extra = unknown> = Extra & {
     /** Stable across renders. Node positions, focus and drag offsets are keyed on it. */
     id: string;
     /**
-     * The accessible name, the breadcrumb text, and the default body.
+     * The accessible name, the list-view row text, and the default body.
      *
      * A plain string, not a `ReactNode`, and that is deliberate: it is read
-     * aloud and printed into a trail, and neither of those can do anything with
+     * aloud and printed into a row, and neither of those can do anything with
      * an element tree. Rich content belongs in `renderNode`.
      */
     label: string;
-    children?: readonly CanvasNode<Extra>[];
+    /**
+     * Which `CanvasGroup` this node belongs to, if any. A node with no group
+     * sits at the top level next to every declared group's own aggregate node.
+     * Groups are flat — a group cannot itself belong to another group — which
+     * matches every real case this shipped with (a domain, a package, a team):
+     * one level of clustering is what "collapse the noisy part" needs, and nested
+     * clustering is a UI nobody asked for yet. Add it if a real consumer needs it.
+     */
+    groupId?: string;
     /** Along-axis extent for this node only, when it differs from the canvas default. */
     width?: number;
     /** Cross-axis extent for this node only, when it differs from the canvas default. */
     height?: number;
 };
+/**
+ * A directed connection between two node ids.
+ *
+ * `kind` is a free-form string the library assigns NO meaning to — same rule
+ * as `label`'s absence of a `type` field. A consumer distinguishing "imports"
+ * from "calls" reads `kind` back out in `edgeClassName` or in its own styling;
+ * the library never brands one kind as more important than another.
+ */
+export interface CanvasEdge {
+    from: string;
+    to: string;
+    kind?: string;
+}
+/**
+ * A named cluster of nodes, collapsed to one box by default.
+ *
+ * COLLAPSED IS THE DEFAULT because a real graph worth drawing (the spike's
+ * 402-node/2,099-edge import graph) is unreadable — and, for a graph with
+ * enough cross-cluster cycles, catastrophically slow to lay out — at full
+ * detail. A group's aggregate node stands in for every member until a
+ * consumer drills into it; see `NodeCanvasProps.expandedGroupId`.
+ */
+export interface CanvasGroup {
+    id: string;
+    label: string;
+    /** Along-axis extent of this group's collapsed box, when it differs from the default. */
+    width?: number;
+    /** Cross-axis extent of this group's collapsed box, when it differs from the default. */
+    height?: number;
+}
+/** The whole graph. Never mutated by the canvas. */
+export interface CanvasGraph<Extra = unknown> {
+    nodes: readonly CanvasNode<Extra>[];
+    edges: readonly CanvasEdge[];
+}
+/**
+ * The scope drilled into when a consumer clicks a CONDENSED CYCLE rather than
+ * a declared group — captured directly from the `PlacedNode.memberIds` the
+ * click landed on, since a cycle has no stable, externally-nameable id of its
+ * own the way a `CanvasGroup` does.
+ *
+ * `layoutGraph` treats this shape as an instruction to skip its own
+ * cycle-condensing pre-pass for this call: every member of a genuine strongly
+ * connected component is, by definition, reachable from every other member
+ * using ONLY edges between members of that same component (that is what
+ * "strongly connected" means) — so re-running Tarjan on exactly this member
+ * set would immediately re-discover the identical single component and
+ * collapse it right back to one box, drilling in would show nothing new, and
+ * a naive implementation of "drill into a cycle" is a no-op wearing a
+ * breadcrumb. Skipping condensation here hands the (now small, already
+ * isolated) subgraph to dagre's OWN cycle-breaking pass directly — the exact
+ * cost/quality tradeoff this card's condensing pre-pass exists to avoid at
+ * the FULL graph's scale is perfectly acceptable once bounded to one cycle's
+ * membership.
+ */
+export interface CanvasCycleScope {
+    cycleMemberIds: readonly string[];
+}
+/**
+ * What `layoutGraph`'s third argument names: the top level (`null`), a
+ * declared group's own members (its `CanvasGroup.id`), or a condensed
+ * cycle's own members (`CanvasCycleScope`). See `CanvasCycleScope` for why
+ * the last case is not just "another group id".
+ */
+export type CanvasScope = string | null | CanvasCycleScope;
 /**
  * Which way the chart grows.
  *
- * `vertical` puts the root at the top with children below it — the shape most
- * people picture. `horizontal` puts the root at the left with children to the
- * right, which is what deep trees with long labels actually want: label text
- * runs along the level axis in one and across it in the other, so a horizontal
- * chart of the same tree is narrower and reads without truncation.
+ * `vertical` ranks top to bottom — the shape most people picture. `horizontal`
+ * ranks left to right, which is what a graph with long labels and few ranks
+ * actually wants: label text runs along the rank axis in one and across it in
+ * the other, so a horizontal chart of the same graph is narrower and reads
+ * without truncation.
  */
 export type CanvasOrientation = "vertical" | "horizontal";
-/** A node with its box resolved, in plane coordinates. `x`/`y` are its TOP-LEFT. */
+/**
+ * A node with its box resolved, in plane coordinates. `x`/`y` are its
+ * TOP-LEFT. This is what the layout actually drew — which is not always one
+ * real node: a collapsed group or a condensed cycle draws as ONE placed node
+ * standing in for several.
+ */
 export interface PlacedNode<Extra = unknown> {
     id: string;
-    node: CanvasNode<Extra>;
-    /** 0 for the node the canvas is currently rooted on. */
-    depth: number;
-    /** Null for the current root. Ids of nodes outside this view never appear. */
-    parentId: string | null;
+    /** Null for a placed node standing in for a group or a condensed cycle. */
+    node: CanvasNode<Extra> | null;
+    /** Set when this placed node IS a collapsed group's aggregate box. */
+    group: CanvasGroup | null;
+    /**
+     * Set when this placed node is a condensed strongly-connected cluster —
+     * nodes that mutually reach each other with no acyclic rank to give them.
+     * Collapsing a cycle is not a user-facing "group" (nobody named it), but it
+     * renders and drills in exactly like one: see the module doc in `layout.ts`.
+     */
+    cycle: boolean;
+    /**
+     * How many real graph nodes this placed node stands for. `1` for an
+     * ordinary node; more than one for a collapsed group or a condensed cycle.
+     */
+    memberCount: number;
+    /** Ids of the real nodes this placed node stands for. `[id]` for an ordinary node. */
+    memberIds: readonly string[];
     x: number;
     y: number;
     width: number;
     height: number;
-    /** How many children it has, whether or not this view is showing them. */
-    childCount: number;
-    /**
-     * It has children and this view is not drawing them — the node sits on the
-     * bottom row of the visible depth. The affordance to descend belongs here.
-     */
-    hasHiddenChildren: boolean;
 }
-/** Parent → child, by id. Both ends are always present in `nodes`. */
-export interface CanvasEdge {
+/** One drawn connection. Both ends are always present in the returned `nodes`. */
+export interface CanvasPlacedEdge {
     from: string;
     to: string;
+    kind?: string;
+    /** How many raw edges this drawn edge aggregates. `1` for an ordinary edge. */
+    weight: number;
+    /** The route dagre computed, in plane coordinates, at least two points. */
+    points: readonly {
+        x: number;
+        y: number;
+    }[];
 }
 export interface CanvasLayout<Extra = unknown> {
     nodes: PlacedNode<Extra>[];
-    edges: CanvasEdge[];
+    edges: CanvasPlacedEdge[];
     /** Extent of the laid-out nodes. The plane is this plus padding on each side. */
     width: number;
     height: number;
@@ -80,34 +169,39 @@ export interface LayoutOptions {
     nodeWidth?: number;
     /** Cross-axis extent of a node that does not declare its own. */
     nodeHeight?: number;
-    /** Clear space between two adjacent nodes on the same level. */
+    /** Clear space between two adjacent nodes on the same rank. */
     siblingGap?: number;
-    /** Clear space between one level and the next. */
+    /** Clear space between one rank and the next. */
     levelGap?: number;
     orientation?: CanvasOrientation;
-    /**
-     * How many levels BELOW the root to draw. `1` shows the root and its
-     * children; `0` shows the root alone.
-     */
-    depth?: number;
 }
 /**
  * What `renderNode` is told about the node it is drawing.
  *
- * Every field is structural — a fact about the node's place in the tree or in
- * the current interaction. None of them is a fact about what the node is.
+ * Every field is structural — a fact about the node's place in the graph or
+ * in the current interaction. None of them is a fact about what the node is.
  */
 export interface NodeRenderContext {
-    /** 0 for the node the canvas is rooted on. */
-    depth: number;
-    isRoot: boolean;
-    childCount: number;
-    hasChildren: boolean;
-    /** Children exist and this view stops short of them — clicking descends. */
-    hasHiddenChildren: boolean;
+    /**
+     * This placed node stands in for a whole group or a condensed cycle rather
+     * than one real node. `renderNode` still receives a `CanvasNode`-shaped
+     * value for it (see `NodeCanvas`'s synthetic node), but `memberCount` is
+     * what says there is more inside.
+     */
+    isGroup: boolean;
+    /** How many real nodes this placed node represents. `1` for an ordinary node. */
+    memberCount: number;
     /** This node carries the canvas's single tab stop. */
     isFocused: boolean;
     /** A pointer is carrying this node right now. */
     isDragging: boolean;
+    /**
+     * Hops from the focused node, along either edge direction: `0` is the
+     * focused node itself, `1`/`2` its one- and two-hop neighbours. `null` when
+     * nothing is focused, or this node is further away than the canvas tracks.
+     * Lets `renderNode` dim everything outside the neighbourhood a keyboard or
+     * screen-reader user is currently reading.
+     */
+    focusDistance: number | null;
 }
 export type NodeRenderer<Extra = unknown> = (node: CanvasNode<Extra>, context: NodeRenderContext) => ReactNode;

package/dist/types/index.d.ts

@@ -124,7 +124,7 @@ export { UseCaseCard, RoadmapItemCard, RoadmapSwimlaneBoard, UseCaseLedgerPage,
 export { ProvenanceDisclosure, ProvenanceDetail, ProvenanceBadge, ConfidenceReadout, ConfidenceMeter, ConfidenceBar, provenanceStateLabel, confidenceBand, confidenceScore, scoredConfidence, ratedConfidence, type ProvenanceRecord, type ProvenanceState, type ProvenanceSource, type ProvenanceCheck, type ProvenanceCall, type ProvenanceSignoff, type ConfidenceBand, type ConfidenceScore, type ProvenanceConfidence, type ConfidenceReadoutProps, type ConfidenceBarProps, type ConfidenceBarSize, type ProvenanceDisclosureProps, type ProvenanceDetailProps, type ProvenanceDetailTitleAs, type ProvenanceTriggerBadge, type ProvenanceBadgeProps, type ProvenanceBadgeAppearance, type ConfidenceMeterProps, } from "./components/provenance";
 export { confidenceLevel, CONFIDENCE_LEVEL_LABELS, type ConfidenceLevel } from "./lib/confidence";
 export { createSimStore, resetSimStores, useSimSettings, setSimSettings, getNetworkSpeed, getDataSource, simulateLatency, SimNetworkError, type SimStore, type SimStoreOptions, type SimSettings, type NetworkSpeed, type DataSource, type SimNamespace, } from "./lib/sim";
-export { NodeCanvas, LAYOUT_DEFAULTS, layoutTree, pathToNode, type NodeCanvasProps, type CanvasEdge, type CanvasLayout, type CanvasNode, type CanvasOrientation, type LayoutOptions, type NodeRenderContext, type NodeRenderer, type PlacedNode, } from "./components/node-canvas";
+export { NodeCanvas, LAYOUT_DEFAULTS, edgePath, layoutGraph, neighbourhood, type NodeCanvasProps, type CanvasCycleScope, type CanvasEdge, type CanvasGraph, type CanvasGroup, type CanvasLayout, type CanvasNode, type CanvasOrientation, type CanvasPlacedEdge, type CanvasScope, type LayoutOptions, type NodeRenderContext, type NodeRenderer, type PlacedNode, } from "./components/node-canvas";
 export { defineRecordType, resetRecordTypes, useRecord, useRecords, useStaleness, write, writeAll, peekRecord, readState, readStaleness, subscribeToKey, subscribeToStaleness, retainKeys, sweepRecords, setRecordStoreTenant, getRecordStoreTenant, flushRecordNotifications, resetRecordStore, recordStoreStats, UNKNOWN_STATE, normalizeTypeName, normalizeTimestamp, recordKey, isRecordRef, type RecordRef, type ReadOptions, type RecordPayload, type RecordState, type RecordTypeOptions, type RecordTypeToken, type StalenessEntry, type WriteAllResult, type WriteOptions, type WriteResult, type WriteSource, type WriteVerdict, } from "./lib/records";
 export { RealtimeProvider, useRealtime, useRealtimeEpoch, useRealtimeHealth, useRealtimeRegistry, SubscriptionRegistry, normalizeScope, scopeKey, subscriptionKey, readRealtimeEpoch, subscribeToRealtimeEpoch, subscribeToRealtimeEvents, resetRealtimeSignals, type RealtimeChannel, type RealtimeConnectionState, type RealtimeDiagnostic, type RealtimeEvent, type RealtimeHealth, type RealtimeProviderProps, type RealtimeScope, type RealtimeScopeInput, type RealtimeStatus, type RealtimeTransport, type RegistryOptions, type SubscriptionHealth, type SubscriptionLease, type SubscriptionRequest, } from "./lib/realtime";
 export { useRecordRead, useRecordListRead, useRecordStoreSweep, applyMutationResult, optimisticWrite, beginOptimisticWrite, resetOptimisticWrites, type OptimisticHandle, type OptimisticWriteOptions, type OptimisticWriteSpec, type SlotDescriptor, acquireSlot, appendCreated, emptySlotSnapshot, readSlot, resetSlots, slotKeys, subscribeToSlot, writeSlot, RefetchRunner, registerActiveRead, resetActiveReads, type ActiveRead, type ListFetch, type ListFetchResult, type ListReadOptions, type ListReadResult, type ReadError, type RecordFetch, type RecordReadOptions, type RecordReadResult, type RunnerOptions, type SlotSnapshot, } from "./lib/reads";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "10.0.1",
+  "version": "11.0.0",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",
@@ -101,6 +101,7 @@
   },
   "dependencies": {
     "@base-ui/react": "^1.7.0",
+    "@dagrejs/dagre": "^3.1.1",
     "@tanstack/react-table": "^8.21.3",
     "clsx": "^2.1.1",
     "tailwind-merge": "^3.3.1",