@danxbot/ui 12.0.0 → 12.1.0

package/dist/types/components/graph-explorer/GraphExplorer.d.ts

@@ -0,0 +1,35 @@
+import type { CanvasNode } from "../node-canvas/types";
+import type { CrossLink, ExplorerNodeRenderer, ExplorerTree, GraphExplorerVariant } from "./types";
+export interface GraphExplorerProps<Extra = unknown> {
+    tree: ExplorerTree<Extra>;
+    /** Secondary relationships drawn over the fixed layout. Never affects positions. */
+    crossLinks?: readonly CrossLink[];
+    /** The accessible name of the whole structure. Required — see `NodeCanvasProps.label`. */
+    label: string;
+    /** The node body. Defaults to the label, wrapped, never truncated. */
+    renderNode?: ExplorerNodeRenderer<Extra>;
+    /** @default "explorer" */
+    variant?: GraphExplorerVariant;
+    /** Which node the camera centres on, with a "you are here" highlight. Controlled. */
+    focusId?: string | null;
+    /** Initial `focusId` for uncontrolled use. */
+    defaultFocusId?: string | null;
+    /** Fired when the controlled `focusId` would change — a node click, or `flyTo` via the keyboard. Never fired with `null`: nothing in this component ever clears focus, only moves it. */
+    onFocusIdChange?: (id: string) => void;
+    /** Nodes styled as already seen. */
+    visitedIds?: ReadonlySet<string> | readonly string[];
+    /** Fired when an ordinary node is clicked or activated by keyboard. */
+    onNodeClick?: (node: CanvasNode<Extra>) => void;
+    /** `variant="minimap"` only: the expand affordance's handler. Defaults to an in-place full-screen dialog. */
+    onExpand?: () => void;
+    /** Along-axis extent of a node that does not need more, in px. @default LAYOUT_DEFAULTS.nodeWidth */
+    nodeWidth?: number;
+    /** Cross-axis extent BEFORE a taller node's own content grows it. @default LAYOUT_DEFAULTS.nodeHeight */
+    nodeHeight?: number;
+    /** `variant="explorer"` only: height of the viewport. @default "32rem" */
+    height?: string;
+    /** Nothing pans, zooms or clicks. Reading is unaffected. */
+    disabled?: boolean;
+    className?: string;
+}
+export declare function GraphExplorer<Extra = unknown>({ tree, crossLinks, label, renderNode, variant, focusId: controlledFocusId, defaultFocusId, onFocusIdChange, visitedIds, onNodeClick, onExpand, nodeWidth, nodeHeight, height, disabled, className, }: GraphExplorerProps<Extra>): import("react").JSX.Element;

package/dist/types/components/graph-explorer/camera-math.d.ts

@@ -0,0 +1,50 @@
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface CameraState {
+    x: number;
+    y: number;
+    scale: number;
+}
+export interface ScaleBounds {
+    minScale?: number;
+    maxScale?: number;
+}
+export declare const CAMERA_DEFAULTS: {
+    readonly minScale: 0.15;
+    readonly maxScale: 3;
+    readonly fitMaxScale: 1;
+    readonly fitPadding: 64;
+};
+export declare function clampScale(scale: number, bounds?: ScaleBounds): number;
+/** Screen point → the content point currently sitting under it. */
+export declare function toContentPoint(camera: CameraState, screenPoint: Point): Point;
+/** Content point → where it currently sits on screen. */
+export declare function toScreenPoint(camera: CameraState, contentPoint: Point): Point;
+/**
+ * Zoom by `factor`, holding `screenPoint` fixed over the same content point it
+ * covered before — the standard "zoom toward the cursor" behaviour a wheel or
+ * a pinch both want. `factor` > 1 zooms in.
+ */
+export declare function zoomAtPoint(camera: CameraState, screenPoint: Point, factor: number, bounds?: ScaleBounds): CameraState;
+/** A camera that puts `target`'s centre in the middle of `viewport`, at `scale`. */
+export declare function centerOn(target: Box | Point, viewport: Size, scale: number): CameraState;
+export interface FitOptions extends ScaleBounds {
+    /** @default CAMERA_DEFAULTS.fitPadding */
+    padding?: number;
+    /** @default CAMERA_DEFAULTS.fitMaxScale — never zoom IN past this to fit a small box. */
+    maxScale?: number;
+}
+/** A camera that fits the whole of `box` inside `viewport`, centred, padded. */
+export declare function fitBox(box: Box, viewport: Size, options?: FitOptions): CameraState;

package/dist/types/components/graph-explorer/index.d.ts

@@ -0,0 +1,5 @@
+export { GraphExplorer, type GraphExplorerProps } from "./GraphExplorer";
+export { layoutExplorerTree, neighbourhoodTree, edgePath } from "./tree-layout";
+export { CAMERA_DEFAULTS, centerOn, clampScale, fitBox, toContentPoint, toScreenPoint, zoomAtPoint } from "./camera-math";
+export type { Box, CameraState, FitOptions, Point, ScaleBounds, Size } from "./camera-math";
+export type { CrossLink, ExplorerLayout, ExplorerNodeRenderContext, ExplorerNodeRenderer, ExplorerTree, GraphExplorerVariant, TreeNode, } from "./types";

package/dist/types/components/graph-explorer/tree-layout.d.ts

@@ -0,0 +1,29 @@
+import { edgePath } from "../node-canvas/layout";
+import type { LayoutOptions } from "../node-canvas/types";
+import type { CrossLink, ExplorerLayout, ExplorerTree } from "./types";
+/** Re-exported for a consumer drawing `edges`/`crossLinks` into an SVG. */
+export { edgePath };
+/**
+ * Lay out a tree, left to right, from a parent backbone alone.
+ *
+ * `crossLinks` are resolved against the ALREADY-FIXED node positions and
+ * returned separately (`ExplorerLayout.crossLinks`) — they never reach
+ * `layoutGraph`, so they can never move a node and can never close a cycle
+ * for the layout engine to condense. A cross-link naming an id not in the
+ * tree, or naming a node as linked to itself, draws nothing — the same
+ * "dangling edge draws nothing" rule `node-canvas/layout.ts#resolveScope`
+ * uses for a group boundary.
+ */
+export declare function layoutExplorerTree<Extra>(tree: ExplorerTree<Extra>, crossLinks?: readonly CrossLink[], options?: LayoutOptions): ExplorerLayout<Extra>;
+/**
+ * The subtree a minimap draws: `focusId`'s ancestor chain up to its root,
+ * `focusId`'s immediate siblings, and `focusId`'s immediate children — "the
+ * focused node's ancestors, siblings and children" the card asks for, kept
+ * small enough to read at the minimap's compact size. `focusId` itself is
+ * always included. Parent links are REWRITTEN to stay inside this subset: the
+ * topmost ancestor kept becomes a root (`parentId: null`) here even if its
+ * real parent exists outside the shown set, so `layoutExplorerTree` never
+ * sees a dangling parent reference. Returns `null` when `focusId` is not in
+ * `tree` at all — nothing sensible to show.
+ */
+export declare function neighbourhoodTree<Extra>(tree: ExplorerTree<Extra>, focusId: string): ExplorerTree<Extra> | null;

package/dist/types/components/graph-explorer/types.d.ts

@@ -0,0 +1,62 @@
+import type { ReactNode } from "react";
+import type { CanvasEdge, CanvasNode, CanvasPlacedEdge, LayoutOptions, PlacedNode } from "../node-canvas/types";
+/**
+ * One node of the tree. Same `Extra`-carrying shape as `CanvasNode` — a
+ * consumer's own fields come back untouched through `renderNode` — plus the
+ * one thing a tree node has that a general graph node does not: its parent.
+ */
+export type TreeNode<Extra = unknown> = CanvasNode<Extra> & {
+    /** The node this one hangs from. `null` for a root — a tree may have more than one. */
+    parentId: string | null;
+};
+/**
+ * A secondary relationship drawn OVER the fixed tree layout — never fed to
+ * the layout engine, so it can never move a node and can never close a cycle
+ * for dagre to condense. `kind` carries no meaning the library assigns, same
+ * rule as `CanvasEdge.kind`.
+ */
+export interface CrossLink {
+    from: string;
+    to: string;
+    kind?: string;
+}
+/** The whole tree. Never mutated by the component. */
+export interface ExplorerTree<Extra = unknown> {
+    nodes: readonly TreeNode<Extra>[];
+}
+/** What `layoutExplorerTree` hands back: the fixed layout, ready to draw. */
+export interface ExplorerLayout<Extra = unknown> {
+    nodes: PlacedNode<Extra>[];
+    /** The parent → child backbone, drawn as the primary edges. */
+    edges: CanvasPlacedEdge[];
+    /** `CrossLink`s resolved to drawn curves. Never affects `nodes`' positions. */
+    crossLinks: CanvasPlacedEdge[];
+    /** Extent of the laid-out tree — the plane the camera's `fitAll` fits to. */
+    width: number;
+    height: number;
+}
+export type { CanvasEdge, CanvasNode, LayoutOptions, PlacedNode, CanvasPlacedEdge };
+/** Which surface this render is: the full pannable explorer, or the compact strip. */
+export type GraphExplorerVariant = "explorer" | "minimap";
+/**
+ * What `renderNode` is told about the node it is drawing — the explorer's own
+ * facts (camera focus, visited, hover neighbourhood), analogous to
+ * `NodeRenderContext` in `node-canvas/types.ts` but keyed on the camera's
+ * `focusId` rather than a drilled-into scope.
+ */
+export interface ExplorerNodeRenderContext {
+    /** This node carries the canvas's single roving tab stop. */
+    isTabStop: boolean;
+    /** This IS the controlled `focusId` — the "you are here" node. */
+    isFocused: boolean;
+    /** In the caller-supplied `visitedIds`. */
+    isVisited: boolean;
+    /**
+     * Hops from whichever node is currently the reference point — the hovered
+     * node while one is hovered, else the focused node — along either edge
+     * direction (backbone or cross-link). `null` when nothing is being
+     * referenced, or this node is further away than the explorer tracks.
+     */
+    distance: number | null;
+}
+export type ExplorerNodeRenderer<Extra = unknown> = (node: CanvasNode<Extra>, context: ExplorerNodeRenderContext) => ReactNode;

package/dist/types/components/graph-explorer/use-camera.d.ts

@@ -0,0 +1,31 @@
+import { type Box, type CameraState } from "./camera-math";
+export interface CameraClickEvent {
+    /** Client coordinates, for the caller to hit-test against its own elements. */
+    target: HTMLElement;
+}
+export interface UseCameraOptions {
+    /** Content-space bounding box of the whole drawing. Drives `fitAll`. */
+    contentBox: Box;
+    /** A node's content-space box, for `flyTo`. `null` for an id not laid out. */
+    boxOf: (id: string) => Box | null;
+    /** A press that released without travelling past `CLICK_DISTANCE`. */
+    onClick?: (event: CameraClickEvent) => void;
+    /** Nothing pans, zooms or clicks. Reading the plane still works. */
+    disabled?: boolean;
+    /** Changing this value re-fits the camera to `contentBox` — a new tree. */
+    resetKey?: unknown;
+}
+export interface UseCameraResult {
+    camera: CameraState;
+    /** A pointer is actively panning or pinching right now. */
+    panning: boolean;
+    /** True for the duration of a programmatic move — see the module doc. */
+    animating: boolean;
+    bindViewport: (node: HTMLDivElement | null) => void;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    fitAll: () => void;
+    /** Animate the camera to centre node `id`. No-op if `id` isn't laid out yet. */
+    flyTo: (id: string, scale?: number) => void;
+}
+export declare function useCamera(options: UseCameraOptions): UseCameraResult;

package/dist/types/icons/data.d.ts

@@ -630,6 +630,31 @@ export declare const coreIcons: {
     }], readonly ["path", {
         readonly d: "M15 3v18";
     }]];
+    readonly crosshair: readonly [readonly ["circle", {
+        readonly cx: "12";
+        readonly cy: "12";
+        readonly r: "10";
+    }], readonly ["line", {
+        readonly x1: "22";
+        readonly x2: "18";
+        readonly y1: "12";
+        readonly y2: "12";
+    }], readonly ["line", {
+        readonly x1: "6";
+        readonly x2: "2";
+        readonly y1: "12";
+        readonly y2: "12";
+    }], readonly ["line", {
+        readonly x1: "12";
+        readonly x2: "12";
+        readonly y1: "6";
+        readonly y2: "2";
+    }], readonly ["line", {
+        readonly x1: "12";
+        readonly x2: "12";
+        readonly y1: "22";
+        readonly y2: "18";
+    }]];
     readonly "delete-column": readonly [readonly ["path", {
         readonly d: "M2 12h6";
     }], readonly ["path", {

package/dist/types/index.d.ts

@@ -129,6 +129,7 @@ export { ProvenanceDisclosure, ProvenanceDetail, ProvenanceBadge, ConfidenceRead
 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, 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 { GraphExplorer, layoutExplorerTree, neighbourhoodTree, CAMERA_DEFAULTS, centerOn, clampScale, fitBox, toContentPoint, toScreenPoint, zoomAtPoint, type GraphExplorerProps, type Box, type CameraState, type FitOptions, type Point, type ScaleBounds, type Size, type CrossLink, type ExplorerLayout, type ExplorerNodeRenderContext, type ExplorerNodeRenderer, type ExplorerTree, type GraphExplorerVariant, type TreeNode as ExplorerTreeNode, } from "./components/graph-explorer";
 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": "12.0.0",
+  "version": "12.1.0",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",