nexus-shell 0.2.5 → 0.2.6

package/README.md

@@ -132,6 +132,7 @@ 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 |
 | `UserProfile` | Avatar and identity widget |

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,5 @@ 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 { NodePalette, readPaletteDrag, GRAPH_NODE_MIME, type NodePaletteProps, type INodePaletteItem, type PaletteOrientation, type ResolvedOrientation, } from './NodePalette';

package/dist/index.d.ts

@@ -57,6 +57,6 @@ 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 { 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;