nexus-shell 0.2.4 → 0.2.6

package/README.md

@@ -129,6 +129,12 @@ shell's own frame and keep every registration working.
 | `TerminalPane` | Bottom-docked terminal log and input |
 | `ThemeSwitcher` | Segmented theme control |
 | `TreeWidget` | Virtualised tree for any hierarchy, with drag-to-move and a data-driven menu |
+| `GraphCanvas` | Infinite pannable, zoomable field for node-and-edge editing |
+| `GraphNode` | Positioned, focusable node with edge ports |
+| `GraphEdge` | Directed edge with bezier / smoothstep / straight routing |
+| `GraphMiniMap` | Scaled graph overview with a viewport indicator |
+| `NodePalette` | Drag-to-create and keyboard-to-create node types |
+| `useGraphKeyboard` | Spatial keyboard navigation and editing for a graph |
 | `UserProfile` | Avatar and identity widget |
 
 ## Theming

package/dist/components/graph/GraphCanvas.d.ts

@@ -0,0 +1,110 @@
+import { default as React, ReactNode } from 'react';
+import { IGraphNode, IPoint, IViewport } from '../../lib/graph';
+
+export interface GraphCanvasHandle {
+    /** Current pan and zoom. */
+    getViewport: () => IViewport;
+    /** Jump to a viewport. */
+    setViewport: (viewport: IViewport) => void;
+    /** Frame the given nodes, or clear the viewport when the list is empty. */
+    fitTo: (nodes: IGraphNode[], padding?: number) => void;
+    /** Multiply the zoom about the centre of the element. */
+    zoomBy: (factor: number) => void;
+    /** Convert a client (page) point into graph space. */
+    clientToGraph: (client: IPoint) => IPoint;
+    /** The element's pixel size. A minimap needs this to draw its indicator. */
+    getSize: () => {
+        width: number;
+        height: number;
+    };
+    /** Move keyboard focus to the canvas. */
+    focus: () => void;
+}
+export interface GraphCanvasProps {
+    /**
+     * Content rendered in graph space. Position children with `GraphNode`, or
+     * with your own absolutely-positioned elements in graph coordinates.
+     */
+    children?: ReactNode;
+    /**
+     * Content rendered in screen space, above the graph and unaffected by pan or
+     * zoom — toolbars, a minimap, a legend.
+     */
+    overlay?: ReactNode;
+    /**
+     * Take control of pan and zoom. Omit it and the canvas manages its own,
+     * which is what most callers want: you should not have to own a viewport
+     * just to draw a graph.
+     */
+    viewport?: IViewport;
+    /** Starting viewport when uncontrolled. Defaults to origin at 1× zoom. */
+    defaultViewport?: IViewport;
+    /** Called whenever pan or zoom changes, controlled or not. */
+    onViewportChange?: (viewport: IViewport) => void;
+    /**
+     * Called on mount and whenever the element resizes, with its pixel size.
+     *
+     * Pass this to a {@link GraphMiniMap} as `canvasSize` — the indicator cannot
+     * be drawn without knowing how much of the graph is on screen.
+     */
+    onSizeChange?: (size: {
+        width: number;
+        height: number;
+    }) => void;
+    /**
+     * Called with a graph-space point when empty canvas is clicked. Use it to
+     * clear selection, or to place a node at the click.
+     */
+    onCanvasClick?: (point: IPoint, event: React.MouseEvent) => void;
+    /** Called with a graph-space point when empty canvas is double-clicked. */
+    onCanvasDoubleClick?: (point: IPoint, event: React.MouseEvent) => void;
+    /** Called with a graph-space point on right-click of empty canvas. */
+    onCanvasContextMenu?: (point: IPoint, event: React.MouseEvent) => void;
+    /**
+     * Called when something is dropped on the canvas, with the graph-space point
+     * under the cursor. Pair with `NodePalette` for drag-to-create.
+     */
+    onDrop?: (point: IPoint, event: React.DragEvent) => void;
+    /** Show the dot grid. Defaults to `true`. */
+    grid?: boolean;
+    /** Grid spacing in graph units. Defaults to `24`. */
+    gridSize?: number;
+    /** Smallest allowed zoom. Defaults to `0.1`. */
+    minScale?: number;
+    /** Largest allowed zoom. Defaults to `4`. */
+    maxScale?: number;
+    /** Allow panning by dragging empty canvas. Defaults to `true`. */
+    pannable?: boolean;
+    /** Allow zooming with the wheel or trackpad pinch. Defaults to `true`. */
+    zoomable?: boolean;
+    /** Accessible label for the canvas region. Defaults to `"Graph canvas"`. */
+    'aria-label'?: string;
+    /** Extra classes merged onto the root element. */
+    className?: string;
+}
+/**
+ * An infinite, pannable, zoomable field to draw a graph on.
+ *
+ * The canvas owns exactly one thing: the mapping between screen pixels and
+ * graph space. It knows nothing about nodes, edges, or what any of it means —
+ * children are rendered inside a transformed layer, so anything positioned in
+ * graph coordinates lands in the right place.
+ *
+ * Pan by dragging empty space or with the middle mouse button; zoom with the
+ * wheel or a trackpad pinch, always anchored to the cursor. Space-drag pans
+ * from anywhere, including over a node.
+ *
+ * Viewport state is internal by default. Pass `viewport` to take control.
+ *
+ * @example
+ * ```tsx
+ * <GraphCanvas onDrop={(point) => addNodeAt(point)}>
+ *   {nodes.map((node) => (
+ *     <GraphNode key={node.id} node={node} onMove={move}>
+ *       {node.label}
+ *     </GraphNode>
+ *   ))}
+ * </GraphCanvas>
+ * ```
+ */
+export declare const GraphCanvas: React.ForwardRefExoticComponent<GraphCanvasProps & React.RefAttributes<GraphCanvasHandle>>;

package/dist/components/graph/GraphEdge.d.ts

@@ -0,0 +1,71 @@
+import { default as React } from 'react';
+import { GraphPort, IGraphEdge, IGraphNode, IPoint } from '../../lib/graph';
+
+/**
+ * How an edge gets from one node to the other.
+ *
+ * - `bezier` — a smooth curve. The default; reads well for dense graphs.
+ * - `smoothstep` — right angles with rounded corners, for flowcharts.
+ * - `straight` — a direct line.
+ */
+export type EdgeRouting = 'bezier' | 'smoothstep' | 'straight';
+export interface GraphEdgeProps {
+    /** The edge to render. */
+    edge: IGraphEdge;
+    /** The node the edge leaves. */
+    source: IGraphNode;
+    /** The node the edge enters. */
+    target: IGraphNode;
+    /** Path shape. Defaults to `"bezier"`. */
+    routing?: EdgeRouting;
+    /** Draw as selected. */
+    selected?: boolean;
+    /** Draw an arrowhead at the target end. Defaults to `true`. */
+    arrow?: boolean;
+    /** Called on click. The wide invisible hit area makes this practical. */
+    onSelect?: (id: string, event: React.MouseEvent) => void;
+    /** Called on right-click, with the client point for a context menu. */
+    onContextMenu?: (id: string, point: IPoint, event: React.MouseEvent) => void;
+    /** Extra classes merged onto the visible path. */
+    className?: string;
+}
+/** The SVG path for a pair of points and the sides they leave from. */
+export declare const edgePath: (from: IPoint, to: IPoint, fromPort: GraphPort, routing: EdgeRouting) => string;
+/**
+ * A directed edge between two nodes, rendered as an SVG path.
+ *
+ * Which sides the edge leaves and enters is worked out from the nodes'
+ * relative positions, so a node needs no handle configuration to be
+ * connectable — move a node and the attachment points follow.
+ *
+ * Render inside {@link GraphEdgeLayer}, which provides the SVG surface and the
+ * arrowhead marker.
+ *
+ * @example
+ * ```tsx
+ * <GraphEdgeLayer>
+ *   {edges.map((edge) => (
+ *     <GraphEdge
+ *       key={edge.id}
+ *       edge={edge}
+ *       source={byId[edge.source]}
+ *       target={byId[edge.target]}
+ *       onSelect={setSelectedEdge}
+ *     />
+ *   ))}
+ * </GraphEdgeLayer>
+ * ```
+ */
+export declare const GraphEdge: ({ edge, source, target, routing, selected, arrow, onSelect, onContextMenu, className, }: GraphEdgeProps) => import("react/jsx-runtime").JSX.Element;
+export interface GraphEdgeLayerProps {
+    children?: React.ReactNode;
+    className?: string;
+}
+/**
+ * The SVG surface edges are drawn on.
+ *
+ * Sits beneath the nodes inside a {@link GraphCanvas}, spanning an effectively
+ * unbounded area so edges remain visible wherever the graph is panned. It also
+ * defines the shared arrowhead marker.
+ */
+export declare const GraphEdgeLayer: ({ children, className }: GraphEdgeLayerProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/graph/GraphMiniMap.d.ts

@@ -0,0 +1,83 @@
+import { IGraphNode, IViewport } from '../../lib/graph';
+
+export interface GraphMiniMapProps {
+    /** The nodes to plot. Only position and size are read. */
+    nodes: IGraphNode[];
+    /** The canvas's current pan and zoom. */
+    viewport: IViewport;
+    /**
+     * Pixel size of the canvas the minimap mirrors. Get it from `GraphCanvas`'s
+     * `onSizeChange`; without it the viewport indicator can't be drawn.
+     */
+    canvasSize: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Called with a viewport that recentres the canvas. Omit it and the minimap
+     * becomes a read-only overview.
+     */
+    onViewportChange?: (viewport: IViewport) => void;
+    /** Minimap width in pixels. Defaults to `180`. */
+    width?: number;
+    /** Minimap height in pixels. Defaults to `120`. */
+    height?: number;
+    /**
+     * Fill colour for a node, as a CSS colour or Tailwind class. Receives the
+     * node, so you can colour by `kind`. Defaults to the muted foreground.
+     */
+    nodeColor?: (node: IGraphNode) => string;
+    /**
+     * Highlight these node ids — a selection, or search results. Drawn in the
+     * primary colour above the rest.
+     */
+    highlightIds?: string[];
+    /** Padding around the plotted content, in minimap pixels. Defaults to `8`. */
+    padding?: number;
+    /** How far an arrow key pans, in graph units. Defaults to `80`. */
+    panDistance?: number;
+    /** Accessible label. Defaults to `"Graph minimap"`. */
+    'aria-label'?: string;
+    /** Extra classes merged onto the root element. */
+    className?: string;
+}
+/**
+ * A scaled overview of the whole graph, with an indicator showing what the
+ * canvas is currently looking at.
+ *
+ * Click anywhere to jump there, drag to pan continuously, or focus it and use
+ * the arrow keys. The zoom level is never changed — a minimap answers "where am
+ * I", and changing scale on a click makes that answer harder to trust.
+ *
+ * The plotted extent is the union of the graph's bounds and the current
+ * viewport, so the indicator stays visible even when you have panned far away
+ * from every node. Without that, panning into empty space makes the minimap
+ * appear broken.
+ *
+ * Fully controlled: it reads `viewport` and reports where you want to go, but
+ * never moves the canvas itself.
+ *
+ * @example
+ * ```tsx
+ * const [viewport, setViewport] = useState(IDENTITY_VIEWPORT);
+ * const [size, setSize] = useState({ width: 0, height: 0 });
+ *
+ * <GraphCanvas
+ *   viewport={viewport}
+ *   onViewportChange={setViewport}
+ *   onSizeChange={setSize}
+ *   overlay={
+ *     <GraphMiniMap
+ *       nodes={nodes}
+ *       viewport={viewport}
+ *       canvasSize={size}
+ *       onViewportChange={setViewport}
+ *       className="absolute bottom-3 right-3"
+ *     />
+ *   }
+ * >
+ *   …
+ * </GraphCanvas>
+ * ```
+ */
+export declare const GraphMiniMap: ({ nodes, viewport, canvasSize, onViewportChange, width, height, nodeColor, highlightIds, padding, panDistance, "aria-label": ariaLabel, className, }: GraphMiniMapProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/graph/GraphNode.d.ts

@@ -0,0 +1,68 @@
+import { default as React, ReactNode } from 'react';
+import { GraphPort, IGraphNode, IPoint } from '../../lib/graph';
+
+export interface GraphNodeProps {
+    /** The node to render. Position and size come from here. */
+    node: IGraphNode;
+    /** Node body. Anything — a label, a form, a chart. */
+    children?: ReactNode;
+    /**
+     * Called with the new top-left position while dragging, and again on
+     * release. The component never mutates the node — you apply the move, which
+     * is what lets you snap, constrain or reject it.
+     */
+    onMove?: (id: string, position: IPoint) => void;
+    /** Called when the drag ends, if the node actually moved. */
+    onMoveEnd?: (id: string, position: IPoint) => void;
+    /** Called on click. */
+    onSelect?: (id: string, event: React.MouseEvent) => void;
+    /** Called on double-click. Conventionally enters edit mode. */
+    onActivate?: (id: string) => void;
+    /** Called on right-click, with the client point for a context menu. */
+    onContextMenu?: (id: string, point: IPoint, event: React.MouseEvent) => void;
+    /**
+     * Called when one of the node's ports is dragged, to begin a connection.
+     * Providing it is what makes the ports appear.
+     */
+    onConnectStart?: (id: string, port: GraphPort) => void;
+    /**
+     * Called when a pointer is released over this node, with its id — the target
+     * end of a connection started elsewhere.
+     */
+    onConnectEnd?: (targetId: string) => void;
+    /** Draw as selected. */
+    selected?: boolean;
+    /**
+     * Draw as focused — the keyboard cursor. Distinct from `selected`: focus is
+     * where the next keystroke lands, selection is what an action applies to.
+     */
+    focused?: boolean;
+    /** Show connection ports on hover and while focused. Defaults to `true`. */
+    ports?: boolean;
+    /** Allow dragging. Defaults to `true`. */
+    draggable?: boolean;
+    /** Extra classes merged onto the node element. */
+    className?: string;
+}
+/**
+ * A positioned, focusable node on a {@link GraphCanvas}.
+ *
+ * Provides placement, dragging, selection and focus affordances, and the four
+ * edge ports. What the node *contains* is entirely yours — pass any children.
+ *
+ * Fully controlled: dragging reports positions through `onMove` but never moves
+ * the node itself, so snapping, constraints and undo stay in your hands.
+ *
+ * @example
+ * ```tsx
+ * <GraphNode
+ *   node={node}
+ *   focused={node.id === focusedId}
+ *   onMove={(id, position) => setNodes(move(nodes, id, position))}
+ *   onActivate={(id) => setEditing(id)}
+ * >
+ *   <p className="text-xs font-medium">{node.data.label}</p>
+ * </GraphNode>
+ * ```
+ */
+export declare const GraphNode: ({ node, children, onMove, onMoveEnd, onSelect, onActivate, onContextMenu, onConnectStart, onConnectEnd, selected, focused, ports, draggable, className, }: GraphNodeProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/graph/NodePalette.d.ts

@@ -0,0 +1,117 @@
+import { default as React, ReactNode } from 'react';
+
+/** The MIME type palette entries put their kind on during a drag. */
+export declare const GRAPH_NODE_MIME = "application/x-nexus-graph-node";
+/**
+ * How the palette lays its items out.
+ *
+ * - `horizontal` — a row, wrapping if it must.
+ * - `vertical` — a column.
+ * - `auto` — whichever fits the space the palette is given. See
+ *   {@link NodePalette} for the rule.
+ */
+export type PaletteOrientation = 'horizontal' | 'vertical' | 'auto';
+/** The orientation actually rendered, once `auto` has been resolved. */
+export type ResolvedOrientation = Exclude<PaletteOrientation, 'auto'>;
+/** An entry in a {@link NodePalette}. */
+export interface INodePaletteItem {
+    /**
+     * The `kind` given to the node this creates. Also the payload carried on the
+     * drag, so the drop handler knows what was dragged.
+     */
+    kind: string;
+    /** Label shown in the palette. */
+    label: string;
+    /** Optional icon or swatch rendered before the label. */
+    icon?: ReactNode;
+    /** One line explaining what the node is, shown as a tooltip. */
+    description?: string;
+}
+export interface NodePaletteProps {
+    /** The node types on offer. */
+    items: INodePaletteItem[];
+    /**
+     * Called when an item is activated by click or Enter, for creating without a
+     * drag. Keyboard users need this — a drag-only palette is unreachable.
+     */
+    onSelect?: (item: INodePaletteItem) => void;
+    /** Called when a drag starts, if you want to show a drop hint. */
+    onDragStart?: (item: INodePaletteItem) => void;
+    /**
+     * Layout axis. Defaults to `"auto"`, which measures the available space and
+     * picks whichever axis fits.
+     */
+    orientation?: PaletteOrientation;
+    /**
+     * Called when `auto` settles on an axis, and whenever it changes. Useful for
+     * adjusting surrounding layout to match.
+     */
+    onOrientationChange?: (orientation: ResolvedOrientation) => void;
+    /**
+     * Hide labels and show icons only. Useful for a narrow rail; items keep their
+     * accessible name, so nothing is lost to a screen reader.
+     */
+    iconOnly?: boolean;
+    /** Extra classes merged onto the root element. */
+    className?: string;
+    /** Accessible label for the group. Defaults to `"Node palette"`. */
+    'aria-label'?: string;
+}
+/**
+ * A palette of node types that can be dragged onto a {@link GraphCanvas}, or
+ * activated with the keyboard.
+ *
+ * The palette carries only the item's `kind` on the drag; what a node of that
+ * kind actually *is* is decided by your drop handler. Pair it with
+ * {@link readPaletteDrag} on the canvas.
+ *
+ * Every item is a real button, so the palette is fully usable without a
+ * pointer — `onSelect` fires on click or Enter.
+ *
+ * ## Orientation
+ *
+ * `auto` (the default) measures the space the palette's container gives it and
+ * picks the axis that fits:
+ *
+ * 1. a row, if the items fit the available width;
+ * 2. otherwise a column, if they fit the available height;
+ * 3. otherwise a row that wraps.
+ *
+ * A container that shrink-wraps its content — an absolutely positioned overlay,
+ * say — offers no information about available space, so the palette measures
+ * the nearest ancestor that has a size of its own. That is what stops a
+ * vertical palette from narrowing its own container and then being unable to
+ * discover it has room to go horizontal again.
+ *
+ * Pass `horizontal` or `vertical` when you already know.
+ *
+ * @example
+ * ```tsx
+ * <GraphCanvas
+ *   onDrop={(point, event) => {
+ *     const kind = readPaletteDrag(event);
+ *     if (kind) addNode({ kind, position: point });
+ *   }}
+ *   overlay={
+ *     <NodePalette
+ *       items={[{ kind: 'task', label: 'Task' }, { kind: 'gate', label: 'Gate' }]}
+ *       onSelect={(item) => addNodeAtCentre(item.kind)}
+ *     />
+ *   }
+ * />
+ * ```
+ */
+export declare const NodePalette: ({ items, onSelect, onDragStart, orientation, onOrientationChange, iconOnly, className, "aria-label": ariaLabel, }: NodePaletteProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Read the node kind from a drop on the canvas, or `null` if the drag did not
+ * come from a {@link NodePalette}.
+ *
+ * @example
+ * ```tsx
+ * <GraphCanvas onDrop={(point, event) => {
+ *   const kind = readPaletteDrag(event);
+ *   if (kind) createNode(kind, point);
+ * }} />
+ * ```
+ */
+export declare const readPaletteDrag: (event: React.DragEvent) => string | null;

package/dist/components/graph/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The graph layer.
+ *
+ * A decomposed set of primitives for building node-and-edge editors, in the
+ * same spirit as the rest of the library: the canvas knows about coordinates,
+ * the node knows about placement and focus, the edge knows about geometry, and
+ * the keyboard hook knows about traversal. None of them know what a node
+ * *means* — that stays in your application.
+ *
+ * Compose them yourself, or reach for whichever piece you need on its own.
+ */
+export { GraphCanvas, type GraphCanvasProps, type GraphCanvasHandle } from './GraphCanvas';
+export { GraphNode, type GraphNodeProps } from './GraphNode';
+export { GraphEdge, GraphEdgeLayer, edgePath, type GraphEdgeProps, type GraphEdgeLayerProps, type EdgeRouting, } from './GraphEdge';
+export { useGraphKeyboard, DEFAULT_GRAPH_KEYS, type UseGraphKeyboardOptions, type UseGraphKeyboardResult, type GraphKeyboardActions, } from './useGraphKeyboard';
+export { GraphMiniMap, type GraphMiniMapProps } from './GraphMiniMap';
+export { NodePalette, readPaletteDrag, GRAPH_NODE_MIME, type NodePaletteProps, type INodePaletteItem, type PaletteOrientation, type ResolvedOrientation, } from './NodePalette';

package/dist/components/graph/useGraphKeyboard.d.ts

@@ -0,0 +1,115 @@
+import { Direction, IGraphEdge, IGraphNode, IPoint } from '../../lib/graph';
+
+/** The default keyboard map. Every binding is overridable. */
+export declare const DEFAULT_GRAPH_KEYS: {
+    /** Move focus to the nearest node in a direction. */
+    readonly moveFocus: readonly ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"];
+    /** Create a connected node in a direction. */
+    readonly createConnected: "Tab";
+    /** Edit the focused node. */
+    readonly edit: "Enter";
+    /** Leave edit mode, cancel a pending connection, or clear focus. */
+    readonly cancel: "Escape";
+    /** Delete the focused node. */
+    readonly delete: readonly ["Delete", "Backspace"];
+    /** Begin connecting from the focused node. */
+    readonly connect: "c";
+    /** Nudge the focused node. Held with the arrow keys. */
+    readonly nudgeModifier: "shiftKey";
+};
+export interface GraphKeyboardActions {
+    /**
+     * Create a node at a position, returning its id so focus can follow it. The
+     * library never invents node content — you decide what a new node is.
+     */
+    onCreateNode?: (position: IPoint, context: {
+        from?: string;
+        direction?: Direction;
+    }) => string | undefined;
+    /** Connect two nodes. */
+    onConnect?: (sourceId: string, targetId: string) => void;
+    /** Delete a node and its edges. */
+    onDeleteNode?: (id: string) => void;
+    /** Move a node, used by nudging. */
+    onMoveNode?: (id: string, position: IPoint) => void;
+    /** Enter edit mode for a node. */
+    onEditNode?: (id: string) => void;
+}
+export interface UseGraphKeyboardOptions extends GraphKeyboardActions {
+    /** The current nodes. Traversal and placement are computed from these. */
+    nodes: IGraphNode[];
+    /** The current edges. Used to reason about existing connections. */
+    edges: IGraphEdge[];
+    /** Take control of which node has keyboard focus. */
+    focusedId?: string | null;
+    /** Starting focus when uncontrolled. */
+    defaultFocusedId?: string | null;
+    /** Called whenever focus moves. */
+    onFocusChange?: (id: string | null) => void;
+    /**
+     * Element the listener attaches to. Bindings only fire while focus is inside
+     * it, so several graphs can coexist on one page.
+     */
+    targetRef: React.RefObject<HTMLElement | null>;
+    /** How far a nudge moves a node, in graph units. Defaults to `16`. */
+    nudgeDistance?: number;
+    /** Turn the whole thing off. */
+    disabled?: boolean;
+}
+export interface UseGraphKeyboardResult {
+    /** The node the next keystroke applies to. */
+    focusedId: string | null;
+    setFocusedId: (id: string | null) => void;
+    /** Node currently being edited, if any. */
+    editingId: string | null;
+    setEditingId: (id: string | null) => void;
+    /** Source of a connection awaiting a target, if any. */
+    connectingFrom: string | null;
+    setConnectingFrom: (id: string | null) => void;
+    /** Move focus as an arrow key would. Exposed for toolbar buttons. */
+    moveFocus: (direction: Direction) => void;
+    /** Create a connected node as Tab would. */
+    createConnected: (direction?: Direction) => void;
+}
+/**
+ * Keyboard-driven graph navigation and editing.
+ *
+ * Headless: it owns the focus, editing and connection cursors and reports what
+ * should happen, but renders nothing and mutates nothing. That means it works
+ * with `GraphNode` or with your own node rendering, and every mutation stays
+ * subject to your validation and undo.
+ *
+ * The default map, all overridable:
+ *
+ * | Key | Action |
+ * | :-- | :-- |
+ * | Arrows | Move focus to the nearest node in that direction |
+ * | Shift + Arrows | Nudge the focused node |
+ * | Tab / Shift+Tab | Create a node connected to the focused one |
+ * | Enter | Edit the focused node |
+ * | `c` then a node | Connect from the focused node |
+ * | Delete / Backspace | Delete the focused node |
+ * | Escape | Leave edit mode, cancel a connection, or clear focus |
+ *
+ * Arrow traversal is spatial rather than by insertion order — it picks the
+ * nearest node in the direction travelled, penalising lateral offset, which is
+ * what makes a hand-arranged diagram navigable without a mouse.
+ *
+ * @example
+ * ```tsx
+ * const canvasRef = useRef<HTMLDivElement>(null);
+ *
+ * const keyboard = useGraphKeyboard({
+ *   nodes, edges, targetRef: canvasRef,
+ *   onCreateNode: (position) => {
+ *     const id = nextId('node', nodes);
+ *     setNodes([...nodes, { id, position, data: { label: 'New' } }]);
+ *     return id;
+ *   },
+ *   onConnect: (source, target) =>
+ *     setEdges([...edges, { id: nextId('edge', edges), source, target }]),
+ *   onDeleteNode: (id) => { … },
+ * });
+ * ```
+ */
+export declare const useGraphKeyboard: ({ nodes, edges, focusedId: controlledFocusedId, defaultFocusedId, onFocusChange, targetRef, nudgeDistance, disabled, onCreateNode, onConnect, onDeleteNode, onMoveNode, onEditNode, }: UseGraphKeyboardOptions) => UseGraphKeyboardResult;

package/dist/index.d.ts

@@ -56,5 +56,7 @@ export { TerminalPane, type TerminalPaneProps } from './components/widgets/Termi
 export { ThemeSwitcher, type ThemeSwitcherProps, type IThemeOption, DEFAULT_THEME_OPTIONS } from './components/widgets/ThemeSwitcher';
 export { TreeWidget, type TreeWidgetProps, type ITreeNode, type ITreeAction, type ITreeContext } from './components/widgets/TreeWidget';
 export { UserProfile, type UserProfileProps, type IUserProfile, type IUserProfileAction } from './components/widgets/UserProfile';
+export * from './components/graph';
+export { DEFAULT_NODE_SIZE, IDENTITY_VIEWPORT, clampScale, edgesOf, findNeighbour, fitViewport, graphBounds, isConnected, nextId, nodeRect, placeRelativeTo, portPoint, rectCenter, removeNode, resolvePorts, toGraphSpace, toScreenSpace, unionRect, viewportRect, centerOn, zoomAt, type Direction, type GraphPort, type IGraphEdge, type IGraphNode, type IPoint, type IRect, type IViewport, } from './lib/graph';
 export { cn } from './lib/cn';
 export { BUNDLED_THEMES, BUNDLED_THEME_CLASSES, themeClass, type IBundledTheme, type BundledThemeId, } from './lib/themes';