@kortexya/nodus 0.1.0

package/types/algorithms/hierarchical/sugiyama.d.ts

@@ -0,0 +1,144 @@
+export declare const SENTINEL: -1;
+export declare const SENTINEL_DATA: {
+    id: string;
+    layer: number;
+    sink: boolean;
+    fixed: boolean;
+    siblingIndex: number;
+    parentIds: any[];
+    children: any[];
+    radius: number;
+    ref: any;
+};
+export interface SugNode {
+    id: any;
+    layer: number;
+    data: any;
+    children: SugNode[];
+    ref?: any;
+    x: number;
+    y: number;
+}
+export declare function makeVirtualNode(id: any, layer: number): SugNode;
+export declare function isVirtual(n: SugNode): boolean;
+export declare function isReal(n: SugNode): boolean;
+declare class LNode {
+    data: any;
+    prev: LNode | null;
+    next: LNode | null;
+    constructor(data: any, prev?: LNode | null, next?: LNode | null);
+    toString(): any;
+}
+declare class NodeLinkedList {
+    head: LNode | null;
+    tail: LNode | null;
+    byId: {
+        [id: string]: LNode;
+    };
+    byIndex: {
+        [idx: number]: LNode;
+    };
+    length: number;
+    append(data: any, id: string | number): LNode;
+    forEach(cb: (node: LNode, idx: number) => void): void;
+}
+export declare function insertVirtualNodes(graph: {
+    nodes: SugNode[];
+}): SugNode[][];
+export declare function decrossLayers(layers: SugNode[][], shouldDecross: boolean, sortSiblings: boolean): void;
+export declare class SugiyamaLayout {
+    edges: {
+        source: any;
+        target: any;
+        virtual: boolean;
+        id: number;
+    }[];
+    nodeMap: {
+        [id: string]: SugNode;
+    };
+    nodeIndexTopDown: {
+        [id: string]: number;
+    };
+    nodeToLayer: {
+        [id: string]: number;
+    };
+    longEdges: {
+        [id: string]: string[];
+    };
+    virt: {
+        [id: string]: boolean;
+    };
+    height: {
+        [layer: number]: number;
+    };
+    breadth: {
+        [id: string]: number;
+    };
+    first: SugNode[];
+    totalW: {
+        [id: string]: number;
+    };
+    mDist: {
+        [id: string]: number;
+    };
+    X: {
+        [id: string]: number;
+    };
+    block: {
+        [id: string]: any;
+    };
+    nodeList: NodeLinkedList;
+    nodeDistance: number;
+    layerDistance: number;
+    layers: SugNode[][];
+    N: number;
+    Y: Float32Array;
+    adjacencyList: {
+        [src: string]: any[];
+    };
+    neighbours: {
+        prev: {
+            [id: string]: any[];
+        };
+        next: {
+            [id: string]: any[];
+        };
+    };
+    constructor(layers: SugNode[][], nodeDistance: number, layerDistance: number);
+    computeMinNodeDistances(): void;
+    decrossVirtualEdges(): void;
+    placeLongEdges(): void;
+    sortLongEdges(e: string, t: number, s: {
+        [id: string]: number;
+    }, o: {
+        done: boolean;
+        dist: number;
+    }, c: {
+        [id: string]: number;
+    }, p: {
+        [id: string]: number;
+    }): boolean;
+    placeNonVirtualNodes(): void;
+    placeSequence(e: any, t: any, s: any, o: any, c: number, p?: number): void;
+    calculateBends(e: number, t: number, s: any, o: any, c: any, p: any, At: any, Tt: any): {
+        res: number;
+        bends: {
+            value: number;
+            key: number;
+        }[];
+    };
+    combineSequences(e: any, t: any, s: any, o: any, c: any, p: any, At: any, Tt: number): void;
+    placeNode(e: any, t: any, s: any, o: number, c: number): number;
+    moveLongEdge(e: SugNode, t: number, s: {
+        [id: string]: boolean;
+    }): void;
+    moveLongEdges(): void;
+    computeY(): void;
+    straightenLongEdge(e: SugNode, t: {
+        [id: string]: boolean;
+    }): void;
+    straightenEdges(): void;
+    run(): void;
+}
+export declare function sugiyamaCoordinates(layers: SugNode[][], nodeDistance?: number, layerDistance?: number): SugNode[][];
+export {};

package/types/algorithms/hierarchicalFactory.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Hierarchical layout factory.
+ *
+ * Wraps the hierarchical (Sugiyama-style) layout as a layout descriptor
+ * that can be registered with `modules.layouts`.
+ *
+ * The descriptor delegates the heavy lifting to the `sequential` layout
+ * algorithm, which performs layer assignment, crossing reduction,
+ * coordinate assignment, and component packing.
+ */
+interface Nodus {
+    modules: {
+        layouts: {
+            register(descriptor: LayoutDescriptor): void;
+            start(name: string, opts: any): Promise<any>;
+        };
+        graph: any;
+    };
+}
+interface LayoutDescriptor {
+    name: string;
+    imports?: Record<string, any>;
+    configure(opts: any, modules: any): any;
+    context(): any;
+    update(msg: any): any;
+    isRunning(): boolean;
+    onSync(msg: any, modules: any): any;
+}
+declare const DEFAULT_OPTIONS: {
+    direction: "TB";
+    nodeDistance: number;
+    levelDistance: number;
+    componentDistance: number;
+    siblingsDistance: number;
+    compactSiblings: boolean;
+    gapWidth: number;
+    arrangeComponents: "fit";
+    gridDistance: number;
+    layer: string;
+    siblingIndex: string;
+};
+declare const hierarchicalDescriptor: LayoutDescriptor;
+/**
+ * Create and register the hierarchical layout on an Nodus instance.
+ *
+ * @returns A function `(opts?) => Promise<any>` that starts the layout.
+ */
+export default function hierarchicalFactory(nodus: Nodus): (opts?: any) => Promise<any>;
+export { hierarchicalDescriptor, DEFAULT_OPTIONS as HIERARCHICAL_DEFAULT_OPTIONS };

package/types/algorithms/index.d.ts

@@ -0,0 +1,13 @@
+export * from './concentric/index';
+export * from './force/index';
+export * from './grid/index';
+export * from './hierarchical/index';
+export * from './radial/index';
+export * from './sequential/index';
+export { default as forceFactory, forceDescriptor } from './forceFactory';
+export { default as forceLinkFactory, forceLinkDescriptor } from './forceLinkFactory';
+export { default as gridFactory, gridDescriptor } from './gridFactory';
+export { default as hierarchicalFactory, hierarchicalDescriptor } from './hierarchicalFactory';
+export { default as sequentialFactory, sequentialDescriptor } from './sequentialFactory';
+export { default as concentricFactory, concentricDescriptor } from './concentricFactory';
+export { default as radialFactory, radialDescriptor } from './radialFactory';

package/types/algorithms/radial/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Radial layout algorithm.
+ *
+ * Places nodes on concentric circles based on their graph-theoretical
+ * distance (BFS shortest path) from a central node.  Nodes on each
+ * ring are evenly distributed, with optional repulsion sweeps to
+ * reduce overlap.
+ */
+export interface RadialOptions {
+    centralNode: number;
+    centerX?: number;
+    centerY?: number;
+    allowOverlap?: boolean;
+    repulsion?: number;
+    radiusDelta?: number;
+    radiusRatio?: number;
+    nodeGap?: number;
+    maxIterations?: number;
+    iterationsPerRender?: number;
+    renderSteps?: boolean;
+    epsilon?: number;
+}
+export interface RadialInput {
+    nodeCount: number;
+    sources: number[];
+    targets: number[];
+    nodeRadii: number[];
+}
+export interface RadialResult {
+    x: number[];
+    y: number[];
+}
+export declare function radial(input: RadialInput, options: RadialOptions): RadialResult;

package/types/algorithms/radialFactory.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Radial layout factory.
+ *
+ * Wraps the radial (stress-minimisation on concentric rings) layout as a
+ * layout descriptor. The COMPUTE — Johnson all-pairs shortest paths,
+ * constrained stress minimisation, ring radii, radial overlap removal — runs
+ * ENTIRELY in Rust (`nodus-core::radial_stress`, wasm `RadialStressSim`),
+ * byte-exact with the deleted TS pipeline (radial-live-parity.mjs: 50
+ * layouts, positions + rings + step counts identical; the frozen TS oracle
+ * lives inside that gate). The whole state — including the n×n f32 distance
+ * matrix — stays wasm-resident for the run; each update() tick is one
+ * `step_batch` call (scalars in, positions out).
+ *
+ * wasm is REQUIRED here (no TS fallback — Phase-5 cutover rule): the worker
+ * loads pkg unconditionally before its first tick, and the main thread
+ * hard-requires it via wasmInit's top-level await.
+ *
+ * The public `Nodus.algorithms.{johnson,stressMinimizationStep,…}` utilities
+ * keep their TS bodies in algorithmExports.ts — that is API surface the
+ * reference bundle also ships; this layout no longer touches them.
+ */
+interface Nodus {
+    modules: {
+        layouts: {
+            register(descriptor: LayoutDescriptor): void;
+            start(name: string, opts: any): Promise<any>;
+        };
+        graph: any;
+    };
+}
+interface LayoutDescriptor {
+    name: string;
+    imports?: Record<string, any>;
+    configure(opts: any, modules: any): any;
+    context(): any;
+    update(msg: any, context: any): any;
+    isRunning(ctx: {
+        data: any;
+    }): boolean;
+    onSync(msg: any): any;
+    onEnd?(msg: any): any;
+}
+/**
+ * The radial descriptor: configure() extracts the graph TS-side (protocol),
+ * update() drives the wasm-resident RadialStressSim (compute).
+ */
+declare const radialDescriptor: LayoutDescriptor;
+/**
+ * Create and register the radial layout on an Nodus instance.
+ *
+ * @returns A function `(opts) => Promise<any>` that starts the layout.
+ */
+export default function radialFactory(nodus: Nodus): (opts: any) => Promise<any>;
+export { radialDescriptor };

package/types/algorithms/sequential/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Sequential layout algorithm.
+ *
+ * Similar to the hierarchical layout but forces a constant width
+ * per layer -- each layer contains at most one "lane" of nodes,
+ * producing a long chain-like diagram rather than a wide tree.
+ *
+ * Phases:
+ *  1. Layer assignment (longest-path from roots)
+ *  2. Ordering within each layer (barycenter heuristic, single sweep)
+ *  3. Sequential X placement (constant lane width)
+ *  4. Component packing
+ */
+export interface SequentialOptions {
+    direction?: 'TB' | 'BT' | 'LR' | 'RL';
+    nodeDistance?: number;
+    levelDistance?: number;
+    componentDistance?: number;
+    roots?: number[];
+    sinks?: number[];
+    arrangeComponents?: 'fit' | 'grid' | 'singleLine';
+    gridDistance?: number;
+    decross?: boolean;
+}
+export interface SequentialInput {
+    nodeCount: number;
+    sources: number[];
+    targets: number[];
+    nodeRadii: number[];
+    nodeData?: any[];
+    layerField?: string;
+}
+export interface SequentialResult {
+    x: number[];
+    y: number[];
+}
+export declare function sequential(input: SequentialInput, options?: SequentialOptions): SequentialResult;

package/types/algorithms/sequentialFactory.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Sequential layout factory.
+ *
+ * The sequential layout reuses the hierarchical layout descriptor
+ * (same configure / update / onSync logic) but forces
+ * `evenDistribution: true`, producing a chain-like arrangement
+ * instead of a wide tree.
+ */
+interface Nodus {
+    modules: {
+        layouts: {
+            register(descriptor: any): void;
+            start(name: string, opts: any): Promise<any>;
+        };
+    };
+}
+/**
+ * The sequential descriptor is a shallow copy of the hierarchical one
+ * with only the `name` changed. All configure / update / onSync behaviour
+ * is inherited; the distinct name lets it register and start independently.
+ */
+declare const sequentialDescriptor: {
+    name: string;
+    imports?: Record<string, any>;
+    configure(opts: any, modules: any): any;
+    context(): any;
+    update(msg: any): any;
+    isRunning(): boolean;
+    onSync(msg: any, modules: any): any;
+};
+/**
+ * Create and register the sequential layout on an Nodus instance.
+ *
+ * @returns A function `(opts?) => Promise<any>` that starts the layout.
+ */
+export default function sequentialFactory(nodus: Nodus): (opts?: any) => Promise<any>;
+export { sequentialDescriptor };

package/types/core/Edge.d.ts

@@ -0,0 +1,67 @@
+export declare class Edge<ED = any, ND = any> {
+    readonly size = 1;
+    readonly isNode = false;
+    readonly isList = false;
+    readonly _index: number;
+    private readonly _nodus;
+    constructor(index: number, nodus: any);
+    get _indexes(): Uint32Array;
+    setAttributes(attrs: any, opts?: any): Promise<void>;
+    setAttribute(name: string, value: any, opts?: any): Promise<void>;
+    getAttributes(names?: any): any;
+    getAttribute(name: string): any;
+    resetAttributes(names?: any, opts?: any): Promise<void>;
+    replaceOriginalAttributes(attrs: any, opts?: any): Promise<void>;
+    getPreviousAttributes(names?: any): any;
+    getSource(): any;
+    getTarget(): any;
+    getExtremities(): any;
+    setSource(node: any): void;
+    setTarget(node: any): void;
+    getParallelEdges(opts?: any): any;
+    hasParallelEdges(): boolean;
+    fastGetAdjacentElements(): {
+        nodes: any;
+        edges: any;
+    };
+    getAdjacentElements(): {
+        nodes: any;
+        edges: any;
+    };
+    isVisible(): boolean;
+    isExcluded(): boolean;
+    setExcluded(value: boolean): void;
+    setVisible(value: boolean): void;
+    toList(): any;
+    slice(): any;
+    get(index: number): this | undefined;
+    getId(): string | number;
+    toJSON(opts?: any): any;
+    setSelected(value: boolean): void;
+    isSelected(): boolean;
+    setDisabled(value: boolean): void;
+    isDisabled(): boolean;
+    setData(pathOrData: any, value?: any): this;
+    getData(path?: any): any;
+    addClass(className: string, opts?: any): Promise<void>;
+    addClasses(classNames: string[], opts?: any): Promise<void>;
+    removeClass(className: string, opts?: any): Promise<void>;
+    removeClasses(classNames: string[], opts?: any): Promise<void>;
+    hasClass(className: string): boolean;
+    getClassList(): string[];
+    isVirtual(): boolean;
+    getTransformation(): any;
+    getMetaEdge(): any;
+    getSubEdges(): any;
+    getAnimationInformation(): any;
+    pulse(opts?: any): Promise<void>;
+    getStyle(name?: string): any;
+    setStyle(attrs: any, opts?: any): Promise<void>;
+    resetStyle(opts?: any): Promise<void>;
+    locate(opts?: any): Promise<void>;
+    getBoundingBox(opts?: {
+        includeTexts?: boolean;
+        ignoreCurvature?: boolean;
+    }): any;
+    isInView(opts?: any): boolean;
+}

package/types/core/EdgeList.d.ts

@@ -0,0 +1,86 @@
+/**
+ * EdgeList: an ordered collection of edges backed by a Uint32Array of internal
+ * indexes. Operations resolve indexes against the graph's object store on demand,
+ * keeping the list itself compact and cheap to copy.
+ */
+import { Edge } from './Edge';
+export declare class EdgeList<ED = any, ND = any> {
+    readonly isList = true;
+    readonly isNode = false;
+    _indexes: Uint32Array;
+    private _nodus;
+    constructor(indexes: Uint32Array, nodus: any);
+    get size(): number;
+    setAttributes(attrs: any, opts?: any): Promise<void>;
+    setAttribute(name: string, value: any, opts?: any): Promise<void>;
+    getAttributes(names?: any): any[];
+    getAttribute(name: string): any[];
+    resetAttributes(names?: any, opts?: any): Promise<void>;
+    replaceOriginalAttributes(attrs: any, opts?: any): Promise<void>;
+    getPreviousAttributes(names?: any): any[];
+    getPreviousAttribute(name: string): any[];
+    getSource(): any;
+    getTarget(): any;
+    getExtremities(): any;
+    getParallelEdges(opts?: any): any;
+    fastGetAdjacentElements(): {
+        nodes: any;
+        edges: any;
+    };
+    getAdjacentElements(): {
+        nodes: any;
+        edges: any;
+    };
+    isVisible(): boolean[];
+    isExcluded(): boolean[];
+    isVirtual(): boolean[];
+    setExcluded(value: boolean): void;
+    setVisible(value: boolean): void;
+    toList(): this;
+    toArray(): Edge<ED, ND>[];
+    clone(): EdgeList<ED, ND>;
+    getId(): (string | number)[];
+    get(index: number): Edge<ED, ND>;
+    forEach(fn: (edge: Edge<ED, ND>, i: number, list: this) => void): void;
+    find(fn: (edge: Edge<ED, ND>, i: number, list: this) => boolean): Edge<ED, ND> | undefined;
+    some(fn: (edge: Edge<ED, ND>, i: number, list: this) => boolean): boolean;
+    every(fn: (edge: Edge<ED, ND>, i: number, list: this) => boolean): boolean;
+    map<T>(fn: (edge: Edge<ED, ND>, i: number, list: this) => T): T[];
+    filter(fn: (edge: Edge<ED, ND>, i: number, list: this) => boolean): EdgeList<ED, ND>;
+    reduce<T>(fn: (acc: T, edge: Edge<ED, ND>, i: number, list: this) => T, init: T): T;
+    concat(other: EdgeList<ED, ND> | null): EdgeList<ED, ND>;
+    dedupe(): EdgeList<ED, ND>;
+    subtract(other: EdgeList<ED, ND>): EdgeList<ED, ND>;
+    slice(start?: number, end?: number): EdgeList<ED, ND>;
+    indexOf(edge: Edge<ED, ND>): number;
+    includes(edge: Edge<ED, ND>): boolean;
+    sort(compareFn: (a: Edge<ED, ND>, b: Edge<ED, ND>) => number): EdgeList<ED, ND>;
+    inverse(): EdgeList<ED, ND>;
+    [Symbol.iterator](): Iterator<Edge<ED, ND>>;
+    toJSON(opts?: any): any[];
+    setSelected(value: boolean): void;
+    isSelected(): boolean[];
+    setDisabled(value: boolean): void;
+    isDisabled(): boolean[];
+    setData(pathOrData: any, value?: any): this;
+    fillData(pathOrValue: any, value?: any): this;
+    getData(path?: any): any[];
+    addClass(className: string, opts?: any): Promise<void>;
+    addClasses(classNames: string[], opts?: any): Promise<void>;
+    removeClass(className: string, opts?: any): Promise<void>;
+    removeClasses(classNames: string[], opts?: any): Promise<void>;
+    hasClass(className: string): boolean[];
+    getClassList(): string[][];
+    locate(opts?: any): Promise<void>;
+    getBoundingBox(opts?: {
+        includeTexts?: boolean;
+        ignoreCurvature?: boolean;
+    }): any;
+    getMetaEdge(): any[];
+    getSubEdges(): any[];
+    getAnimationInformation(): any[];
+    pulse(opts?: any): Promise<void>;
+    getStyle(name?: string): any[];
+    setStyle(attrs: any, opts?: any): Promise<void>;
+    resetStyle(opts?: any): Promise<void>;
+}

package/types/core/Node.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Node: thin wrapper around an internal index. All operations delegate to nodus.modules.*.
+ *
+ * Note: `_indexes` is a shared Uint32Array([_index]) used for uniform handling with NodeList.
+ */
+export declare class Node<ND = any, ED = any> {
+    readonly size = 1;
+    readonly isNode = true;
+    readonly isList = false;
+    readonly _index: number;
+    private readonly _nodus;
+    constructor(index: number, nodus: any);
+    get _indexes(): Uint32Array;
+    setAttributes(attrs: any, opts?: any): Promise<void>;
+    setAttribute(name: string, value: any, opts?: any): Promise<void>;
+    getAttributes(names?: any): any;
+    getAttribute(name: string): any;
+    resetAttributes(names?: any, opts?: any): Promise<void>;
+    replaceOriginalAttributes(attrs: any, opts?: any): Promise<void>;
+    getPreviousAttributes(names?: any): any;
+    getPreviousAttribute(name: string): any;
+    getPosition(): {
+        x: number;
+        y: number;
+    };
+    setPosition(pos: {
+        x: number;
+        y: number;
+    }, opts?: any): Promise<void>;
+    getPositionOnScreen(): {
+        x: number;
+        y: number;
+    };
+    isInScreen(): boolean;
+    getAdjacentNodes(opts?: any): any;
+    getAdjacentEdges(opts?: any): any;
+    getAdjacentElements(opts?: any): {
+        nodes: any;
+        edges: any;
+    };
+    getDegree(opts?: any): number;
+    fastGetAdjacentElements(): {
+        nodes: any;
+        edges: any;
+    };
+    getConnectedComponent(opts?: any): any;
+    isVisible(): boolean;
+    isExcluded(): boolean;
+    setExcluded(value: boolean): void;
+    setVisible(value: boolean): void;
+    toList(): any;
+    getId(): string | number;
+    slice(): any;
+    get(index: number): this | undefined;
+    toJSON(opts?: any): any;
+    setSelected(value: boolean): void;
+    isSelected(): boolean;
+    setDisabled(value: boolean): void;
+    isDisabled(): boolean;
+    setData(pathOrData: any, value?: any): this;
+    getData(path?: any): any;
+    addClass(className: string, opts?: any): Promise<void>;
+    addClasses(classNames: string[], opts?: any): Promise<void>;
+    removeClass(className: string, opts?: any): Promise<void>;
+    removeClasses(classNames: string[], opts?: any): Promise<void>;
+    hasClass(className: string): boolean;
+    getClassList(): string[];
+    getGeoCoordinates(): {
+        latitude?: number;
+        longitude?: number;
+    };
+    setGeoCoordinates(coords: any): Promise<this>;
+    isVirtual(): boolean;
+    getTransformation(): any;
+    getMetaNode(): any;
+    getSubNodes(): any;
+    addSubGraph(nodes: any, opts?: any): Promise<any>;
+    getAnimationInformation(): any;
+    pulse(opts?: any): Promise<void>;
+    getStyle(name?: string): any;
+    setStyle(attrs: any, opts?: any): Promise<void>;
+    resetStyle(opts?: any): Promise<void>;
+    locate(opts?: any): Promise<void>;
+    getBoundingBox(opts?: {
+        includeTexts?: boolean;
+    }): any;
+    isInView(opts?: any): boolean;
+}
+export declare function getElementsId(graph: any, element: any): any;