@danxbot/ui 2.4.0 → 2.5.0

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

@@ -0,0 +1,58 @@
+import type { CanvasNode, CanvasOrientation, NodeRenderer } from "./types";
+export interface NodeCanvasProps<Extra = unknown> {
+    /** The whole tree. The canvas walks into it; it never mutates it. */
+    root: CanvasNode<Extra>;
+    /**
+     * What this canvas IS — "Org chart", "Dependency graph for the March build".
+     *
+     * 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
+     * they are inside.
+     */
+    label: string;
+    /**
+     * The node body. Receives the consumer's own node type and a context of
+     * purely structural facts.
+     *
+     * 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.
+     */
+    renderNode?: NodeRenderer<Extra>;
+    /** 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;
+    /** Fired when a node drag commits. The offset is from its laid-out position. */
+    onNodeDragEnd?: (event: {
+        id: string;
+        offset: {
+            x: number;
+            y: number;
+        };
+    }) => void;
+    /** Nothing pans, drags or descends. Reading still works, including by keyboard. */
+    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;

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

@@ -0,0 +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";

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

@@ -0,0 +1,17 @@
+import type { CanvasLayout, CanvasNode, LayoutOptions } from "./types";
+export declare const LAYOUT_DEFAULTS: Required<LayoutOptions>;
+/**
+ * Lay a tree out.
+ *
+ * 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>;
+/**
+ * The ids from the ORIGINAL root down to `targetId`, inclusive.
+ *
+ * `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.
+ */
+export declare function pathToNode<Extra>(root: CanvasNode<Extra>, targetId: string): CanvasNode<Extra>[] | null;

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

@@ -0,0 +1,113 @@
+import type { ReactNode } from "react";
+/**
+ * One node of the tree.
+ *
+ * `Extra` carries the consumer's own fields DOWN THE WHOLE TREE, 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>} />
+ * ```
+ *
+ * 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.
+     *
+     * 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
+     * an element tree. Rich content belongs in `renderNode`.
+     */
+    label: string;
+    children?: readonly CanvasNode<Extra>[];
+    /** 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;
+};
+/**
+ * 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.
+ */
+export type CanvasOrientation = "vertical" | "horizontal";
+/** A node with its box resolved, in plane coordinates. `x`/`y` are its TOP-LEFT. */
+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;
+    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 {
+    from: string;
+    to: string;
+}
+export interface CanvasLayout<Extra = unknown> {
+    nodes: PlacedNode<Extra>[];
+    edges: CanvasEdge[];
+    /** Extent of the laid-out nodes. The plane is this plus padding on each side. */
+    width: number;
+    height: number;
+}
+export interface LayoutOptions {
+    /** Along-axis extent of a node that does not declare its own. */
+    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. */
+    siblingGap?: number;
+    /** Clear space between one level 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.
+ */
+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 node carries the canvas's single tab stop. */
+    isFocused: boolean;
+    /** A pointer is carrying this node right now. */
+    isDragging: boolean;
+}
+export type NodeRenderer<Extra = unknown> = (node: CanvasNode<Extra>, context: NodeRenderContext) => ReactNode;

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

@@ -0,0 +1,39 @@
+import type { Point } from "@/lib/dnd/types";
+/** Plane-local box of a node, as the layout placed it. */
+export interface NodeBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface CanvasGestureOptions {
+    /** Where a node sits before any drag offset. Null for an id not on screen. */
+    layoutBoxOf: (id: string) => NodeBox | null;
+    /** Extent of the scrolled plane. Node positions are clamped inside it. */
+    planeSize: {
+        width: number;
+        height: number;
+    };
+    /** A press that released without activating — the click that descends. */
+    onNodeClick: (id: string) => void;
+    /** A drag that committed. Offsets stay owned here either way. */
+    onNodeDragEnd?: (event: {
+        id: string;
+        offset: Point;
+    }) => void;
+    disabled?: boolean;
+}
+export interface CanvasGestures {
+    /** Drag offsets from the layout position, by node id. */
+    offsets: Readonly<Record<string, Point>>;
+    /** The node a pointer is currently carrying, or null. */
+    draggingId: string | null;
+    panning: boolean;
+    /** Ref callback for the scroll viewport. Stable — see the note at its use. */
+    bindViewport: (node: HTMLDivElement | null) => void;
+    /** Ref callback for one node's element. Stable per id. */
+    bindNode: (id: string) => (node: HTMLElement | null) => void;
+    /** Drop every offset — called when the layout underneath them changes. */
+    clearOffsets: () => void;
+}
+export declare function useCanvasGestures(options: CanvasGestureOptions): CanvasGestures;

package/dist/types/index.d.ts

@@ -101,3 +101,4 @@ export { RBACProvider, useRBAC, AccountMenu, DevToolsPopover, RolePermissionMatr
 export { UseCaseCard, RoadmapItemCard, RoadmapSwimlaneBoard, UseCaseLedgerPage, RoadmapPage, PhaseManager, TrackManager, deriveRoadmapItemStatus, isFullyBuilt, isUnbuilt, trackIds, trackProgress, toneForIndex, CATEGORY_TONES, type Domain, type Phase, type Track, type RoadmapItem, type RoadmapItemStatus, type UseCase, type UseCaseStatus, type UseCaseDecision, type UseCaseCardProps, type RoadmapItemCardProps, type RoadmapSwimlaneBoardProps, type UseCaseLedgerPageProps, type RoadmapPageProps, type PhaseManagerProps, type TrackManagerProps, } from "./components/roadmap";
 export { ProvenanceDisclosure, ProvenanceBadge, ConfidenceMeter, provenanceStateLabel, confidenceBand, type ProvenanceRecord, type ProvenanceState, type ProvenanceSource, type ProvenanceCheck, type ProvenanceCall, type ProvenanceSignoff, type ConfidenceBand, type ProvenanceDisclosureProps, type ProvenanceTriggerBadge, type ProvenanceBadgeProps, type ProvenanceBadgeAppearance, type ConfidenceMeterProps, } from "./components/provenance";
 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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",
@@ -78,7 +78,7 @@
     "audit:arrows": "node scripts/audit-arrows.mjs",
     "audit:motion": "node scripts/audit-motion.mjs",
     "audit:responsive": "node scripts/audit-responsive.mjs",
-    "audit:dnd": "node scripts/audit-dnd.mjs && node scripts/probe-dnd-sensors.mjs && node scripts/probe-dnd-a11y.mjs && node scripts/probe-drag-follow.mjs",
+    "audit:dnd": "node scripts/audit-dnd.mjs && node scripts/probe-dnd-sensors.mjs && node scripts/probe-dnd-a11y.mjs && node scripts/probe-drag-follow.mjs && node scripts/probe-drag-overflow.mjs && node scripts/probe-node-canvas.mjs",
     "audit:axtree": "node scripts/audit-axtree.mjs",
     "audit:mutations": "node scripts/audit-mutations.mjs",
     "audit:palette": "node scripts/audit-palette.mjs",