nexus-shell 0.2.6 → 0.2.8

package/README.md

@@ -135,6 +135,9 @@ shell's own frame and keep every registration working.
 | `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/index.d.ts

@@ -14,4 +14,5 @@ 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 { 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 { 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/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>;