@nodius/layouting 0.1.0 → 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,155 @@
+/** Position on a node where a handle can be placed */
+export type HandleSide = 'top' | 'right' | 'bottom' | 'left';
+/** Handle type - input receives connections, output sends connections */
+export type HandleType = 'input' | 'output';
+/** Layout direction. 'TB' or 'LR' are the supported strict reading axes. */
+export type LayoutDirection = 'TB' | 'LR' | 'BT' | 'RL';
+/**
+ * Edge kind drives the layout weight:
+ * - `control`: full strength; defines the execution rail (layer count).
+ * - `data`: light weight; values are pulled onto the same layer as their consumer
+ *   instead of extending the rail.
+ */
+export type EdgeKind = 'control' | 'data';
+/** A 2D point */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** Handle definition on a node */
+export interface HandleInput {
+    id: string;
+    type: HandleType;
+    position: HandleSide;
+    /** Position along the side (0 = start, 1 = end). Default: 0.5 */
+    offset?: number;
+}
+/** Node input definition */
+export interface NodeInput {
+    id: string;
+    width: number;
+    height: number;
+    handles: HandleInput[];
+    /** Parent node id for compound (nested) layouts. */
+    parentId?: string;
+}
+/** Edge input definition */
+export interface EdgeInput {
+    id: string;
+    from: string;
+    to: string;
+    fromHandle: string;
+    toHandle: string;
+    /** Default: 'control' */
+    kind?: EdgeKind;
+    /** Explicit weight override. Defaults: 1 (control), 0.25 (data). */
+    weight?: number;
+}
+/** Complete layout input */
+export interface LayoutInput {
+    nodes: NodeInput[];
+    edges: EdgeInput[];
+}
+/** Per-kind default weight overrides. */
+export interface EdgeWeights {
+    control?: number;
+    data?: number;
+}
+/**
+ * A proposal the layout engine emits to the calling application during a pass.
+ * The app inspects it and decides whether to accept it, modify it, or reject it
+ * by returning either the (possibly tweaked) proposed node or `null`/`undefined`
+ * to keep the original.
+ */
+export interface RotateProposal {
+    type: 'rotate';
+    /** The node being analyzed. */
+    nodeId: string;
+    /** Same node as provided in the input. */
+    current: NodeInput;
+    /** The engine's proposed version after rotating handles. */
+    proposed: NodeInput;
+    /** Rotation in degrees (CW = positive). */
+    rotation: 90 | -90 | 180;
+    /** Reason this proposal was emitted (handle layout mismatches direction, etc.). */
+    reason: string;
+}
+export type LayoutProposal = RotateProposal;
+export type ProposalCallback = (proposal: LayoutProposal) => NodeInput | null | undefined | void;
+/** Layout configuration options */
+export interface LayoutOptions {
+    /** Layout direction. Default: 'TB' */
+    direction?: LayoutDirection;
+    /** Minimum spacing between nodes in the same layer. Default: 40 */
+    nodeSpacing?: number;
+    /** Minimum spacing between layers. Default: 60 */
+    layerSpacing?: number;
+    /** Number of iterations for crossing minimization. Default: 24 */
+    crossingMinimizationIterations?: number;
+    /** Number of iterations for coordinate optimization. Default: 8 */
+    coordinateOptimizationIterations?: number;
+    /** Margin for edge routing (distance from node before turning). Default: 20 */
+    edgeMargin?: number;
+    /** Override default per-kind weights. */
+    edgeWeights?: EdgeWeights;
+    /** When true, disjoint components are packed side-by-side. Default: true */
+    packComponents?: boolean;
+    /** Padding around compound (parent) bounding boxes. Default: 24 */
+    compoundPadding?: number;
+    /**
+     * Called once per node when the engine thinks a rotation of the node's
+     * handles would suit the chosen direction better. Return the (possibly
+     * tweaked) proposed node to accept, or `null`/nothing to keep the original.
+     */
+    onProposal?: ProposalCallback;
+}
+/** Resolved options with all defaults applied */
+export interface ResolvedOptions {
+    direction: LayoutDirection;
+    nodeSpacing: number;
+    layerSpacing: number;
+    crossingMinimizationIterations: number;
+    coordinateOptimizationIterations: number;
+    edgeMargin: number;
+    controlWeight: number;
+    dataWeight: number;
+    packComponents: boolean;
+    compoundPadding: number;
+    onProposal?: ProposalCallback;
+}
+export declare function resolveOptions(options?: LayoutOptions): ResolvedOptions;
+/** Positioned handle in the output */
+export interface HandleOutput {
+    id: string;
+    type: HandleType;
+    position: HandleSide;
+    x: number;
+    y: number;
+}
+/** Positioned node in the output */
+export interface NodeOutput {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    handles: HandleOutput[];
+    /** Echoed back so consumers can reconstruct the hierarchy. */
+    parentId?: string;
+}
+/** Routed edge in the output */
+export interface EdgeOutput {
+    id: string;
+    from: string;
+    to: string;
+    fromHandle: string;
+    toHandle: string;
+    points: Point[];
+    kind: EdgeKind;
+}
+/** Complete layout result */
+export interface LayoutResult {
+    nodes: NodeOutput[];
+    edges: EdgeOutput[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodius/layouting",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Zero-dependency, optimized graph layouting algorithm for node-based technical diagrams with incremental layout support",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -19,8 +19,9 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsc --emitDeclarationOnly",
     "dev": "tsup --watch",
+    "dev:types": "tsc --emitDeclarationOnly --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -42,7 +43,7 @@
   "license": "ISC",
   "devDependencies": {
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
   }
 }

package/dist/index.d.mts

@@ -1,176 +0,0 @@
-/** Position on a node where a handle can be placed */
-type HandleSide = 'top' | 'right' | 'bottom' | 'left';
-/** Handle type - input receives connections, output sends connections */
-type HandleType = 'input' | 'output';
-/** Layout direction */
-type LayoutDirection = 'TB' | 'LR' | 'BT' | 'RL';
-/** A 2D point */
-interface Point {
-    x: number;
-    y: number;
-}
-/** Handle definition on a node */
-interface HandleInput {
-    id: string;
-    type: HandleType;
-    position: HandleSide;
-    /** Position along the side (0 = start, 1 = end). Default: 0.5 */
-    offset?: number;
-}
-/** Node input definition */
-interface NodeInput {
-    id: string;
-    width: number;
-    height: number;
-    handles: HandleInput[];
-}
-/** Edge input definition */
-interface EdgeInput {
-    id: string;
-    from: string;
-    to: string;
-    fromHandle: string;
-    toHandle: string;
-}
-/** Complete layout input */
-interface LayoutInput {
-    nodes: NodeInput[];
-    edges: EdgeInput[];
-}
-/** Layout configuration options */
-interface LayoutOptions {
-    /** Layout direction. Default: 'TB' */
-    direction?: LayoutDirection;
-    /** Minimum spacing between nodes in the same layer. Default: 40 */
-    nodeSpacing?: number;
-    /** Minimum spacing between layers. Default: 60 */
-    layerSpacing?: number;
-    /** Number of iterations for crossing minimization. Default: 24 */
-    crossingMinimizationIterations?: number;
-    /** Number of iterations for coordinate optimization. Default: 8 */
-    coordinateOptimizationIterations?: number;
-    /** Margin for edge routing (distance from node before turning). Default: 20 */
-    edgeMargin?: number;
-}
-/** Positioned handle in the output */
-interface HandleOutput {
-    id: string;
-    type: HandleType;
-    position: HandleSide;
-    x: number;
-    y: number;
-}
-/** Positioned node in the output */
-interface NodeOutput {
-    id: string;
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    handles: HandleOutput[];
-}
-/** Routed edge in the output */
-interface EdgeOutput {
-    id: string;
-    from: string;
-    to: string;
-    fromHandle: string;
-    toHandle: string;
-    points: Point[];
-}
-/** Complete layout result */
-interface LayoutResult {
-    nodes: NodeOutput[];
-    edges: EdgeOutput[];
-}
-
-interface InternalNode {
-    id: string;
-    width: number;
-    height: number;
-    handles: HandleInput[];
-    isDummy: boolean;
-    layer: number;
-    order: number;
-    x: number;
-    y: number;
-}
-interface InternalEdge {
-    id: string;
-    from: string;
-    to: string;
-    fromHandle: string;
-    toHandle: string;
-    reversed: boolean;
-    originalId: string;
-}
-declare class Graph {
-    nodes: Map<string, InternalNode>;
-    edges: Map<string, InternalEdge>;
-    outEdges: Map<string, Set<string>>;
-    inEdges: Map<string, Set<string>>;
-    addNode(node: InternalNode): void;
-    addEdge(edge: InternalEdge): void;
-    removeEdge(edgeId: string): void;
-    removeNode(nodeId: string): void;
-    predecessors(nodeId: string): string[];
-    successors(nodeId: string): string[];
-}
-
-/**
- * Compute a complete layout for the given graph.
- * This is the main entry point for one-shot layout computation.
- */
-declare function layout(input: LayoutInput, options?: LayoutOptions): LayoutResult;
-
-/**
- * Incremental layout engine.
- * Maintains layout state and supports adding/removing nodes
- * without full recomputation.
- */
-declare class IncrementalLayout {
-    private options;
-    private inputNodes;
-    private inputEdges;
-    private lastResult;
-    private nodePositions;
-    constructor(options?: LayoutOptions);
-    /**
-     * Set the full graph and compute a complete layout.
-     */
-    setGraph(input: LayoutInput): LayoutResult;
-    /**
-     * Add nodes and edges incrementally.
-     * Attempts to minimize layout changes for existing nodes.
-     */
-    addNodes(nodes: NodeInput[], edges?: EdgeInput[]): LayoutResult;
-    /**
-     * Remove nodes (and their connected edges) from the layout.
-     */
-    removeNodes(nodeIds: string[]): LayoutResult;
-    /**
-     * Add edges between existing nodes.
-     */
-    addEdges(edges: EdgeInput[]): LayoutResult;
-    /**
-     * Remove edges from the layout.
-     */
-    removeEdges(edgeIds: string[]): LayoutResult;
-    /**
-     * Get the current layout result.
-     */
-    getResult(): LayoutResult | null;
-    private recompute;
-    private recomputeIncremental;
-    /**
-     * Apply stability: blend new positions with old positions for existing nodes.
-     * This reduces visual disruption when adding new nodes.
-     */
-    private applyStability;
-    private cachePositions;
-    private buildResult;
-}
-
-declare function countAllCrossings(graph: Graph, layers: string[][]): number;
-
-export { type EdgeInput, type EdgeOutput, type HandleInput, type HandleOutput, type HandleSide, type HandleType, IncrementalLayout, type LayoutDirection, type LayoutInput, type LayoutOptions, type LayoutResult, type NodeInput, type NodeOutput, type Point, countAllCrossings, layout };