nexus-shell 0.2.5 → 0.2.7

package/README.md

@@ -132,8 +132,12 @@ shell's own frame and keep every registration working.
 | `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 |
+| `useGraphLayout` | Auto layout engines, with a freeform escape for hand placement |
+| `layeredLayout` | Layered tree layout in four directions; handles cycles |
+| `gridLayout` | Uniform grid, ignoring edges |
 | `UserProfile` | Avatar and identity widget |
 
 ## Theming

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

@@ -12,6 +12,11 @@ export interface GraphCanvasHandle {
     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;
 }
@@ -36,6 +41,16 @@ export interface GraphCanvasProps {
     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.

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/NodePalette.d.ts

@@ -2,6 +2,17 @@ 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 {
     /**
@@ -26,8 +37,21 @@ export interface NodePaletteProps {
     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;
+    /**
+     * 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"`. */
@@ -44,6 +68,23 @@ export interface NodePaletteProps {
  * 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
@@ -60,7 +101,7 @@ export interface NodePaletteProps {
  * />
  * ```
  */
-export declare const NodePalette: ({ items, onSelect, onDragStart, vertical, className, "aria-label": ariaLabel, }: NodePaletteProps) => import("react/jsx-runtime").JSX.Element;
+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}.

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

@@ -13,4 +13,6 @@ export { GraphCanvas, type GraphCanvasProps, type GraphCanvasHandle } from './Gr
 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';
+export { GraphMiniMap, type GraphMiniMapProps } from './GraphMiniMap';
+export { useGraphLayout, FREEFORM, type LayoutMode, type UseGraphLayoutOptions, type UseGraphLayoutResult, } from './useGraphLayout';
+export { NodePalette, readPaletteDrag, GRAPH_NODE_MIME, type NodePaletteProps, type INodePaletteItem, type PaletteOrientation, type ResolvedOrientation, } from './NodePalette';

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

@@ -0,0 +1,111 @@
+import { GraphLayout } from '../../lib/layout';
+import { IGraphEdge, IGraphNode, IPoint } from '../../lib/graph';
+
+/**
+ * The mode in which positions are hand-held rather than computed.
+ *
+ * Reserved: a layout may not be registered under this name.
+ */
+export declare const FREEFORM: "freeform";
+/** The active layout's name, or {@link FREEFORM}. */
+export type LayoutMode = typeof FREEFORM | (string & {});
+export interface UseGraphLayoutOptions {
+    /** Your nodes. Positions here are the hand-placed ones. */
+    nodes: IGraphNode[];
+    /** Your edges. Layouts that ignore structure ignore these. */
+    edges: IGraphEdge[];
+    /**
+     * Named layouts to offer. Defaults to the bundled `vertical`, `horizontal`
+     * and `grid`. Spread it to add your own.
+     */
+    layouts?: Record<string, GraphLayout>;
+    /** Take control of the mode. */
+    mode?: LayoutMode;
+    /** Starting mode when uncontrolled. Defaults to {@link FREEFORM}. */
+    defaultMode?: LayoutMode;
+    /** Called whenever the mode changes, including the escape on drag. */
+    onModeChange?: (mode: LayoutMode) => void;
+    /**
+     * Called when a node is moved by hand, so you can persist the position.
+     *
+     * Without it, a drag under an auto layout still escapes to freeform but the
+     * node snaps back to where it was — the engine no longer places it, and
+     * nothing recorded where the pointer left it.
+     */
+    onNodeMove?: (id: string, position: IPoint) => void;
+    /**
+     * Dragging a node while an auto layout is active switches to freeform,
+     * keeping the arrangement as it stood. Defaults to `true`.
+     *
+     * Turn it off for a graph whose positions are entirely derived — a
+     * visualisation rather than an editor — where a stray drag should be ignored.
+     */
+    escapeOnDrag?: boolean;
+}
+export interface UseGraphLayoutResult {
+    /**
+     * Nodes to render: positioned by the active layout, or exactly your nodes in
+     * freeform. Pass these to `GraphNode`, not your originals.
+     */
+    nodes: IGraphNode[];
+    /** The active mode. */
+    mode: LayoutMode;
+    setMode: (mode: LayoutMode) => void;
+    /** Names of the available layouts, for building a picker. */
+    available: string[];
+    /** Whether a layout is currently placing nodes. */
+    isAuto: boolean;
+    /**
+     * Wire to `GraphNode`'s `onMove`. Records the position and, under an auto
+     * layout, escapes to freeform so the drag actually takes effect.
+     */
+    onMove: (id: string, position: IPoint) => void;
+    /**
+     * Positions from the active layout, applied to your nodes and returned for
+     * you to persist. Use it to "bake in" an arrangement before switching to
+     * freeform, so hand editing starts from the laid-out positions rather than
+     * from wherever the nodes previously sat.
+     */
+    bake: () => IGraphNode[];
+}
+/**
+ * Apply a layout engine to a graph, with an escape hatch to hand placement.
+ *
+ * Two kinds of mode:
+ *
+ * - **An auto layout** — positions come from the engine. Your nodes' own
+ *   positions are ignored while it is active, but never overwritten, so
+ *   switching back to freeform restores the arrangement you had.
+ * - **`freeform`** — positions are yours, exactly as stored.
+ *
+ * Dragging a node under an auto layout escapes to freeform rather than fighting
+ * the engine. That is the behaviour that makes auto layout usable: you can
+ * always grab a node, and the graph stops rearranging itself the moment you do.
+ *
+ * The hook derives positions and reports intent; it owns no node data and
+ * mutates nothing.
+ *
+ * @example
+ * ```tsx
+ * const layout = useGraphLayout({
+ *   nodes,
+ *   edges,
+ *   defaultMode: 'vertical',
+ *   onNodeMove: (id, position) => setNodes(move(nodes, id, position)),
+ * });
+ *
+ * <GraphCanvas>
+ *   {layout.nodes.map((node) => (
+ *     <GraphNode key={node.id} node={node} onMove={layout.onMove}>
+ *       {label(node)}
+ *     </GraphNode>
+ *   ))}
+ * </GraphCanvas>
+ *
+ * // A picker is a few lines of your own UI:
+ * {[FREEFORM, ...layout.available].map((mode) => (
+ *   <button key={mode} onClick={() => layout.setMode(mode)}>{mode}</button>
+ * ))}
+ * ```
+ */
+export declare const useGraphLayout: ({ nodes, edges, layouts, mode: controlledMode, defaultMode, onModeChange, onNodeMove, escapeOnDrag, }: UseGraphLayoutOptions) => UseGraphLayoutResult;

package/dist/index.d.ts

@@ -57,6 +57,7 @@ export { ThemeSwitcher, type ThemeSwitcherProps, type IThemeOption, DEFAULT_THEM
 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 { BUILT_IN_LAYOUTS, gridLayout, layeredLayout, type GraphLayout, type GridLayoutOptions, type LayeredLayoutOptions, type LayoutDirection, } from './lib/layout';
+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';

package/dist/lib/graph.d.ts

@@ -102,6 +102,27 @@ export declare const resolvePorts: (from: IRect, to: IRect) => {
  * Used to fit the viewport to the graph.
  */
 export declare const graphBounds: (nodes: IGraphNode[]) => IRect | null;
+/**
+ * The region of graph space currently visible in an element of the given size.
+ *
+ * This is what a minimap draws as its viewport indicator, and what a culling
+ * pass would test against.
+ */
+export declare const viewportRect: (viewport: IViewport, size: {
+    width: number;
+    height: number;
+}) => IRect;
+/**
+ * A viewport that puts a graph-space point at the centre of the element,
+ * keeping the current zoom. Used for jumping somewhere from a minimap or a
+ * search result.
+ */
+export declare const centerOn: (point: IPoint, size: {
+    width: number;
+    height: number;
+}, scale: number) => IViewport;
+/** The smallest rectangle containing both inputs. */
+export declare const unionRect: (a: IRect, b: IRect) => IRect;
 /** A viewport that fits `nodes` inside a element of the given size. */
 export declare const fitViewport: (nodes: IGraphNode[], size: {
     width: number;

package/dist/lib/layout.d.ts

@@ -0,0 +1,86 @@
+import { IGraphEdge, IGraphNode, IPoint } from './graph';
+
+/**
+ * Graph layout engines.
+ *
+ * A layout is a pure function from a graph to repositioned nodes. It never
+ * mutates, never renders, and knows nothing about React — which makes each one
+ * testable in isolation and lets an application supply its own.
+ *
+ * ```ts
+ * const positioned = layeredLayout({ direction: 'right' })(nodes, edges);
+ * ```
+ *
+ * See {@link useGraphLayout} for applying one to a live graph, including the
+ * freeform mode that lets a hand-placed node escape the engine.
+ */
+/** Repositions a graph. Must be pure: same input, same output, no mutation. */
+export type GraphLayout = (nodes: IGraphNode[], edges: IGraphEdge[]) => IGraphNode[];
+/** Which way a layered layout flows. */
+export type LayoutDirection = 'down' | 'up' | 'right' | 'left';
+export interface LayeredLayoutOptions {
+    /** Flow direction. Defaults to `"down"`. */
+    direction?: LayoutDirection;
+    /** Gap between siblings within a layer, in graph units. Defaults to `48`. */
+    nodeSpacing?: number;
+    /** Gap between layers, in graph units. Defaults to `96`. */
+    layerSpacing?: number;
+    /** Top-left of the laid-out block. Defaults to the origin. */
+    origin?: IPoint;
+    /**
+     * How siblings line up across a layer. `center` reads best for trees;
+     * `start` keeps a ragged left edge, which suits deep hierarchies.
+     * Defaults to `"center"`.
+     */
+    align?: 'center' | 'start';
+}
+/**
+ * A layered (Sugiyama-style) tree layout.
+ *
+ * Nodes are grouped into layers by graph depth, then spread along the
+ * cross-axis within each layer. Real node sizes are used, so mixed-size nodes
+ * don't overlap — a fixed step would.
+ *
+ * Handles cycles and disconnected components without dropping nodes.
+ *
+ * @example
+ * ```ts
+ * const layout = layeredLayout({ direction: 'right', layerSpacing: 140 });
+ * setNodes(layout(nodes, edges));
+ * ```
+ */
+export declare const layeredLayout: ({ direction, nodeSpacing, layerSpacing, origin, align, }?: LayeredLayoutOptions) => GraphLayout;
+export interface GridLayoutOptions {
+    /**
+     * Number of columns. Defaults to a square-ish grid, which keeps a large
+     * unstructured set roughly as wide as it is tall.
+     */
+    columns?: number;
+    /** Horizontal gap between cells. Defaults to `48`. */
+    spacingX?: number;
+    /** Vertical gap between cells. Defaults to `48`. */
+    spacingY?: number;
+    /** Top-left of the grid. Defaults to the origin. */
+    origin?: IPoint;
+}
+/**
+ * A uniform grid, ignoring edges entirely.
+ *
+ * Useful for a set with no meaningful hierarchy, or as a reset before hand
+ * arranging. Column widths and row heights come from the largest node in each,
+ * so mixed sizes stay aligned.
+ *
+ * @example
+ * ```ts
+ * setNodes(gridLayout({ columns: 4 })(nodes, edges));
+ * ```
+ */
+export declare const gridLayout: ({ columns, spacingX, spacingY, origin, }?: GridLayoutOptions) => GraphLayout;
+/**
+ * The layouts bundled with the library, ready to pass to
+ * {@link useGraphLayout}.
+ *
+ * Spread it and add your own, or ignore it and supply a different set —
+ * `useGraphLayout` takes any `Record<string, GraphLayout>`.
+ */
+export declare const BUILT_IN_LAYOUTS: Record<string, GraphLayout>;