nexus-shell 0.2.4 → 0.2.5

package/README.md

@@ -129,6 +129,11 @@ 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 |
+| `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,95 @@
+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;
+    /** 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 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/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,76 @@
+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";
+/** 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;
+    /** Stack vertically instead of wrapping horizontally. Defaults to `false`. */
+    vertical?: 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.
+ *
+ * @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, vertical, 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,16 @@
+/**
+ * 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 { NodePalette, readPaletteDrag, GRAPH_NODE_MIME, type NodePaletteProps, type INodePaletteItem, } 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, 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';

package/dist/lib/graph.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The graph domain model and its geometry.
+ *
+ * Kept deliberately small and domain-neutral: the library knows about
+ * positioned nodes, edges between them, and a viewport. What a node *means* —
+ * an argument, a task, a service, a scene object — belongs to the application,
+ * exactly as with {@link ITreeNode}.
+ *
+ * This lives in `lib/` rather than `core/services/` so the presentational graph
+ * components can use it; they are barred from importing stores.
+ */
+/** A point in graph space. Graph space is unbounded in every direction. */
+export interface IPoint {
+    x: number;
+    y: number;
+}
+/** A rectangle in graph space, anchored at its top-left corner. */
+export interface IRect extends IPoint {
+    width: number;
+    height: number;
+}
+/**
+ * The four sides a node exposes for edge attachment.
+ *
+ * Ports are sides rather than discrete handles: an edge picks whichever side
+ * faces its counterpart, which keeps the model small and means a node needs no
+ * per-handle configuration to be connectable.
+ */
+export type GraphPort = 'top' | 'right' | 'bottom' | 'left';
+/** A node in the graph. */
+export interface IGraphNode {
+    /** Stable identifier, unique across the graph. */
+    id: string;
+    /** Top-left corner in graph space. */
+    position: IPoint;
+    /** Rendered size. Defaults to {@link DEFAULT_NODE_SIZE} when omitted. */
+    size?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Your own classification, e.g. `"question"`, `"service"`, `"task"`. Never
+     * interpreted by the library — it exists so you can render and validate by
+     * type, and so palette entries and edge rules can target it.
+     */
+    kind?: string;
+    /** Free-form payload. The library passes it through untouched. */
+    data?: unknown;
+}
+/** A directed edge between two nodes. */
+export interface IGraphEdge {
+    /** Stable identifier, unique across the graph. */
+    id: string;
+    /** Id of the node the edge leaves. */
+    source: string;
+    /** Id of the node the edge enters. */
+    target: string;
+    /** Your own classification, e.g. `"supports"`, `"depends-on"`. */
+    kind?: string;
+    /** Text rendered at the edge's midpoint. */
+    label?: string;
+    /** Free-form payload. */
+    data?: unknown;
+}
+/** Pan and zoom. `scale` multiplies graph units to screen pixels. */
+export interface IViewport {
+    x: number;
+    y: number;
+    scale: number;
+}
+export declare const DEFAULT_NODE_SIZE: {
+    readonly width: 180;
+    readonly height: 72;
+};
+export declare const IDENTITY_VIEWPORT: IViewport;
+/** The rectangle a node occupies, filling in the default size. */
+export declare const nodeRect: (node: IGraphNode) => IRect;
+export declare const rectCenter: (rect: IRect) => IPoint;
+/** Convert a screen-space point (relative to the canvas element) to graph space. */
+export declare const toGraphSpace: (point: IPoint, viewport: IViewport) => IPoint;
+/** Convert a graph-space point to screen space (relative to the canvas element). */
+export declare const toScreenSpace: (point: IPoint, viewport: IViewport) => IPoint;
+/**
+ * Zoom about a fixed screen point, so the graph position under the cursor stays
+ * under the cursor. Anything else feels wrong to use.
+ */
+export declare const zoomAt: (viewport: IViewport, screenPoint: IPoint, nextScale: number) => IViewport;
+export declare const clampScale: (scale: number, min?: number, max?: number) => number;
+/** The point on a rectangle's edge for a given side. */
+export declare const portPoint: (rect: IRect, port: GraphPort) => IPoint;
+/**
+ * Choose which sides an edge should leave and enter, based on which direction
+ * dominates. Picking automatically is what lets a node be connectable without
+ * declaring handles.
+ */
+export declare const resolvePorts: (from: IRect, to: IRect) => {
+    source: GraphPort;
+    target: GraphPort;
+};
+/**
+ * The bounding box of a set of nodes, or `null` when there are none.
+ * Used to fit the viewport to the graph.
+ */
+export declare const graphBounds: (nodes: IGraphNode[]) => IRect | null;
+/** A viewport that fits `nodes` inside a element of the given size. */
+export declare const fitViewport: (nodes: IGraphNode[], size: {
+    width: number;
+    height: number;
+}, padding?: number) => IViewport;
+export type Direction = 'up' | 'down' | 'left' | 'right';
+/**
+ * The nearest node in a direction, for arrow-key traversal.
+ *
+ * Scores candidates by distance along the travel axis, penalised by how far
+ * they stray off it. Pure distance would jump to a node that is barely in the
+ * right direction but far to the side; requiring perfect alignment would make
+ * most of the graph unreachable. The 2× penalty on lateral offset is the
+ * compromise, and it matches what feels right when navigating a hand-arranged
+ * diagram.
+ *
+ * Returns `null` when nothing lies in that direction.
+ */
+export declare const findNeighbour: (nodes: IGraphNode[], fromId: string, direction: Direction) => IGraphNode | null;
+/**
+ * A free position for a new node placed relative to an existing one, nudged
+ * along `direction` and then away from anything it would overlap.
+ *
+ * Used when creating a node from the keyboard, where there is no cursor to say
+ * where it should go.
+ */
+export declare const placeRelativeTo: (nodes: IGraphNode[], fromId: string, direction: Direction, gap?: number) => IPoint;
+/** Edges touching a node, in either direction. */
+export declare const edgesOf: (edges: IGraphEdge[], nodeId: string) => IGraphEdge[];
+/** Whether an edge already joins two nodes, in either direction. */
+export declare const isConnected: (edges: IGraphEdge[], a: string, b: string) => boolean;
+/** Remove a node and every edge attached to it. */
+export declare const removeNode: (nodes: IGraphNode[], edges: IGraphEdge[], nodeId: string) => {
+    nodes: IGraphNode[];
+    edges: IGraphEdge[];
+};
+/** Generate an id that is unique within a collection. */
+export declare const nextId: (prefix: string, existing: {
+    id: string;
+}[]) => string;