@kortexya/nodus 0.1.0

package/types/internals/attributes/flexArrayFactories.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Factory functions that create the typed FlexArray collections for edge and
+ * node visual attributes.
+ *
+ * Each function returns a nested object whose leaves are graph `Attribute`
+ * instances (FlexArrays). The structure mirrors the attribute path hierarchy
+ * (e.g. `stroke.color`, `badges.topLeft.text.content`).
+ */
+import type { Graph } from '../Graph';
+/**
+ * A `FlexArray` (or `Attribute`) is the graph engine's typed sparse array.
+ * The exact implementation lives in Graph / FlexArray modules — here we only
+ * use the factory method `graph.createAttribute(isNode, params, original)`.
+ */
+type Attribute = any;
+interface FlexArrayOptions {
+    /** Whether to create the attribute as an original (source-of-truth) copy */
+    original: boolean;
+    /** Whether to populate with default values (true on first creation) */
+    useDefaultValues: boolean;
+}
+/** The shape of the object returned by `createEdgeFlexArrays`. */
+export interface EdgeFlexArrays {
+    width: Attribute;
+    scalingMethod: Attribute;
+    color: Attribute;
+    opacity: Attribute;
+    minVisibleSize: Attribute;
+    layer: Attribute;
+    detectable: Attribute;
+    curvature: Attribute;
+    adjustAnchors: Attribute;
+    shape: {
+        body: Attribute;
+        head: Attribute;
+        tail: Attribute;
+        style: Attribute;
+    };
+    stroke: {
+        color: Attribute;
+        width: Attribute;
+        scalingMethod: Attribute;
+        minVisibleSize: Attribute;
+    };
+    halo: {
+        color: Attribute;
+        width: Attribute;
+        scalingMethod: Attribute;
+    };
+    badge: EdgeBadgeFlexArrays;
+    pulse: PulseFlexArrays;
+    outline: OutlineFlexArrays;
+    text: EdgeTextFlexArrays;
+}
+interface EdgeBadgeFlexArrays {
+    color: Attribute;
+    size: Attribute;
+    position: Attribute;
+    marginBottom: Attribute;
+    marginToText: Attribute;
+    minVisibleSize: Attribute;
+    scalingMethod: Attribute;
+    image: {
+        url: Attribute;
+        scale: Attribute;
+    };
+    stroke: {
+        color: Attribute;
+        width: Attribute;
+        scalingMethod: Attribute;
+    };
+    text: {
+        content: Attribute;
+        color: Attribute;
+        font: Attribute;
+        style: Attribute;
+        scale: Attribute;
+        paddingLeft: Attribute;
+        paddingTop: Attribute;
+    };
+    rotateWithEdge: Attribute;
+}
+interface PulseFlexArrays {
+    enabled: Attribute;
+    duration: Attribute;
+    interval: Attribute;
+    startColor: Attribute;
+    endColor: Attribute;
+    width: Attribute;
+    startRatio: Attribute;
+    endRatio: Attribute;
+}
+interface OutlineFlexArrays {
+    enabled: Attribute;
+    color: Attribute;
+    minVisibleSize: Attribute;
+}
+interface EdgeTextFlexArrays {
+    content: Attribute;
+    font: Attribute;
+    color: Attribute;
+    size: Attribute;
+    scale: Attribute;
+    style: Attribute;
+    align: Attribute;
+    margin: Attribute;
+    padding: Attribute;
+    position: Attribute;
+    backgroundColor: Attribute;
+    minVisibleSize: Attribute;
+    adjustAngle: Attribute;
+    scaling: Attribute;
+    maxLineLength: Attribute;
+    outline: {
+        color: Attribute;
+        width: Attribute;
+    };
+    secondary: EdgeSecondaryTextFlexArrays;
+}
+interface EdgeSecondaryTextFlexArrays {
+    content: Attribute;
+    font: Attribute;
+    color: Attribute;
+    size: Attribute;
+    scale: Attribute;
+    style: Attribute;
+    align: Attribute;
+    margin: Attribute;
+    padding: Attribute;
+    backgroundColor: Attribute;
+    minVisibleSize: Attribute;
+    outline: {
+        color: Attribute;
+        width: Attribute;
+    };
+}
+/** The shape of the object returned by `createNodeFlexArrays`. */
+export interface NodeFlexArrays {
+    x: Attribute;
+    y: Attribute;
+    radius: Attribute;
+    scalingMethod: Attribute;
+    color: Attribute;
+    opacity: Attribute;
+    shape: Attribute;
+    layer: Attribute;
+    detectable: Attribute;
+    draggable: Attribute;
+    layoutable: Attribute;
+    innerStroke: {
+        width: Attribute;
+        scalingMethod: Attribute;
+        color: Attribute;
+        minVisibleSize: Attribute;
+    };
+    outerStroke: {
+        width: Attribute;
+        scalingMethod: Attribute;
+        color: Attribute;
+        minVisibleSize: Attribute;
+    };
+    badges: {
+        topLeft: NodeBadgeFlexArrays;
+        topRight: NodeBadgeFlexArrays;
+        bottomLeft: NodeBadgeFlexArrays;
+        bottomRight: NodeBadgeFlexArrays;
+    };
+    halo: {
+        color: Attribute;
+        width: Attribute;
+        scalingMethod: Attribute;
+        strokeColor: Attribute;
+        strokeWidth: Attribute;
+        clustering: Attribute;
+        hideNonAdjacentEdges: Attribute;
+    };
+    pulse: PulseFlexArrays;
+    icon: {
+        content: Attribute;
+        font: Attribute;
+        color: Attribute;
+        scale: Attribute;
+        style: Attribute;
+        minVisibleSize: Attribute;
+    };
+    image: {
+        url: Attribute;
+        scale: Attribute;
+        fit: Attribute;
+        tile: Attribute;
+        minVisibleSize: Attribute;
+    };
+    outline: OutlineFlexArrays;
+    text: NodeTextFlexArrays;
+}
+interface NodeBadgeFlexArrays {
+    color: Attribute;
+    scale: Attribute;
+    positionScale: Attribute;
+    minVisibleSize: Attribute;
+    scalingMethod: Attribute;
+    image: {
+        url: Attribute;
+        scale: Attribute;
+    };
+    stroke: {
+        color: Attribute;
+        width: Attribute;
+        scalingMethod: Attribute;
+    };
+    text: {
+        content: Attribute;
+        color: Attribute;
+        font: Attribute;
+        style: Attribute;
+        scale: Attribute;
+        paddingLeft: Attribute;
+        paddingTop: Attribute;
+    };
+}
+interface NodeTextFlexArrays {
+    content: Attribute;
+    font: Attribute;
+    color: Attribute;
+    size: Attribute;
+    scale: Attribute;
+    style: Attribute;
+    align: Attribute;
+    margin: Attribute;
+    padding: Attribute;
+    backgroundColor: Attribute;
+    tip: Attribute;
+    minVisibleSize: Attribute;
+    scaling: Attribute;
+    position: Attribute;
+    maxLineLength: Attribute;
+    truncateLength: Attribute;
+    outline: {
+        color: Attribute;
+        width: Attribute;
+    };
+    secondary: NodeSecondaryTextFlexArrays;
+}
+interface NodeSecondaryTextFlexArrays {
+    content: Attribute;
+    font: Attribute;
+    color: Attribute;
+    size: Attribute;
+    scale: Attribute;
+    style: Attribute;
+    align: Attribute;
+    margin: Attribute;
+    padding: Attribute;
+    backgroundColor: Attribute;
+    minVisibleSize: Attribute;
+    outline: {
+        color: Attribute;
+        width: Attribute;
+    };
+}
+/**
+ * Creates the full set of typed FlexArray attributes for **edges**.
+ *
+ * @param graph  - The internal graph instance (provides `createAttribute`).
+ * @param opts   - Whether to create original attributes and whether to set
+ *                 default values.
+ */
+export declare function createEdgeFlexArrays(graph: Graph, { original, useDefaultValues }: FlexArrayOptions): EdgeFlexArrays;
+/**
+ * Creates the full set of typed FlexArray attributes for **nodes**.
+ *
+ * @param graph  - The internal graph instance (provides `createAttribute`).
+ * @param opts   - Whether to create original attributes and whether to set
+ *                 default values.
+ */
+export declare function createNodeFlexArrays(graph: Graph, { original, useDefaultValues }: FlexArrayOptions): NodeFlexArrays;
+export {};

package/types/internals/easing.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Standard easing functions for animation timing.
+ *
+ * Each function maps a normalized time value `t` in the range [0, 1] to an
+ * eased progress value, providing linear, quadratic, and cubic curves with
+ * in/out/in-out variants.
+ */
+export declare const linear: (t: number) => number;
+export declare const quadraticIn: (t: number) => number;
+export declare const quadraticOut: (t: number) => number;
+export declare const quadraticInOut: (t: number) => number;
+export declare const cubicIn: (t: number) => number;
+export declare const cubicOut: (t: number) => number;
+export declare const cubicInOut: (t: number) => number;
+export declare const easingFunctions: Record<string, (t: number) => number>;

package/types/internals/helpers.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared internal helper functions used across multiple Nodus modules.
+ * These are standalone utility functions with no cross-module dependencies.
+ */
+/** Flatten a nested object to dot-separated keys. */
+export declare function flatten(obj: any, leafTest?: (v: any) => boolean, sep?: string): Record<string, any>;
+/** Unflatten a dot-keyed object back to nested object. */
+export declare function unflatten(obj: Record<string, any>): any;
+/** Set a nested property by dot-path string or array of keys. */
+export declare function setProperty(obj: any, path: string | string[] | null, value: any): void;
+/** Get a nested property by dot-path. */
+export declare function getProperty(obj: any, path: string | string[]): any;
+/** Convert a property path specification to array of keys or null. */
+export declare function toPropertyPath2(path: any): string[] | null;
+/** Get or create a property change entry in the changes array. */
+export declare function findPropertyChange(changes: any[], path: string[] | null): any;
+/** Flatten array (one level). */
+export declare function flattenArray<T>(arr: (T | T[])[]): T[];
+export declare function requestAnimFrame(cb: FrameRequestCallback, ctx?: any): number;
+export declare function cancelAnimFrame(id: number): void;
+export declare function getCurrentTime(): number;
+export declare const isWindowAvailable: boolean;
+export declare const isDocumentAvailable: boolean;
+export declare const isRealBrowser: boolean;
+export declare const isRealBrowserMainThread: boolean;
+export declare function getPixelRatio(): number;
+export declare function resizeElement(el: HTMLElement | HTMLCanvasElement, w: number, h: number, ratio?: number): void;
+export declare function getStyle(el: HTMLElement, prop: string): string | null;
+export declare function requestFullScreen(el: HTMLElement): Promise<void>;
+export declare function cancelFullScreen(): Promise<void>;
+export declare function isFullScreenFn(): boolean;
+/** Cross-browser ResizeObserver. */
+export declare function getResizeObserver(cb: (entries?: any) => void): ResizeObserver;
+export declare function forEach(obj: any, fn: (value: any, key: any) => void, ctx?: any): void;
+/** Math helpers for Camera. */
+export declare function irrelevant(v: number): boolean;
+export declare function screenToGraphOffset(pt: {
+    x: number;
+    y: number;
+}, zoom: number, sinAngle: number, cosAngle: number): {
+    x: number;
+    y: number;
+};
+export declare function rotatePoint(px: number, py: number, cx: number, cy: number, angle: number, out?: {
+    x: number;
+    y: number;
+}): {
+    x: number;
+    y: number;
+};
+/** Zoom transition that follows a smooth interpolated path between two view states. */
+export declare function zoomInterpolate(p0: [number, number, number], p1: [number, number, number]): (t: number) => [number, number, number];
+export declare const IS_POINTER: boolean;
+export declare const BUTTON_MAPPING: Record<number, 'left' | 'middle' | 'right'>;
+export declare const DRAG_TOLERANCE = 6;
+export declare const TOUCH_CONSTANTS: {
+    readonly doubleTapTimer: 500;
+    readonly touchEventRate: 15;
+};
+export declare function addPointerStart(addEvent: any, el: any, handler: (evt: any) => void): any;
+export declare function addPointerMove(addWinEvent: any, el: any, handler: (evt: any) => void): any;
+export declare function addPointerEnd(addWinEvent: any, el: any, handler: (evt: any) => void): any;
+export declare function addPointerCancel(addWinEvent: any, el: any, handler: (evt: any) => void): any;
+export declare function removePointerListener(removeWinEvent: any, el: any, type: string, handler: any): void;
+export declare function getDocument(): Document | {
+    createElementNS: () => null;
+    createElement: () => null;
+    implementation: {
+        createDocument: () => never;
+    };
+};
+export declare function getWheelDelta(event: any): number;
+export declare function initPointerEvents(): void;
+export declare function clearPointerEvents(): void;
+export declare function noop(): void;
+export declare const DOM_LAYERS: readonly ["graphics", "legend", "brand"];
+export declare const DEFAULT_MIN_WIDTH = 300;
+export declare const DEFAULT_MIN_HEIGHT = 300;
+export declare const FULLSCREEN_DELAY = 200;

package/types/internals/hypergraphWorker.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Hypergraph layout worker entry.
+ *
+ * The L-BFGS optimization (paper §5.3) is a self-contained run-to-
+ * completion computation rather than the per-tick iteration the existing
+ * layoutWorker drives, so we use a different protocol: one `run`
+ * message in, periodic `progress` messages out, one `done` message at
+ * the end. The host (`internals/Hypergraph.ts`) is responsible for
+ * re-applying the worker's final state to the main-thread hypergraph
+ * and refreshing the polygon layer.
+ *
+ * Protocol (postMessage shapes)
+ *
+ *   Main → Worker:
+ *     { type: 'run', id,
+ *       hypergraph: HypergraphData,            // current scale (H_n if simplified)
+ *       operations: AtomicOperationRecord[],   // reversal stack
+ *       originalCardinality: [id, number][],   // serialized Map<HypergraphId, number>
+ *       initialPositions: [id, {x,y}][],       // optional warm-start primal
+ *       initialDualPositions: [id, {x,y}][],   // optional warm-start dual
+ *       options: LayoutOptions }
+ *     { type: 'cancel', id }
+ *
+ *   Worker → Main:
+ *     { type: 'progress', id, info: LayoutProgress }
+ *     { type: 'done', id,
+ *       finalHypergraph: HypergraphData,       // post-reversal (= H_0 if started at H_n)
+ *       vertexPositions: [id, {x,y}][],
+ *       dualPositions: [id, {x,y}][],
+ *       energy: number }
+ *     { type: 'error', id, error: string }
+ *
+ * The worker re-imports the same algorithm core that runs on the main
+ * thread — `Hypergraph`, `optimize`, `reverse` — so there is exactly
+ * one implementation to test.
+ */
+export {};

package/types/internals/hypergraphWorkerHost.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Main-thread host for the hypergraph layout worker.
+ *
+ * Wraps the message-based RPC into a single async function `runLayoutJob`
+ * with the same signature as calling `optimize()` + `reverse()` inline.
+ * Falls back to inline execution when Web Workers aren't available
+ * (SSR, jsdom test envs, browsers with workers disabled).
+ */
+import type { AtomicOperationRecord, HypergraphData, HypergraphId, LayoutOptions, Vec2 } from '../hypergraph/types';
+export interface LayoutJobInput {
+    /** Current hypergraph state (typically H_n if simplified). */
+    hypergraph: HypergraphData;
+    /** Reversal stack from a prior simplification, or empty. */
+    operations: AtomicOperationRecord[];
+    /** H_0 cardinalities for paper §5.3 polygon sizing. */
+    originalCardinality: Map<HypergraphId, number>;
+    /** Optional warm-start positions. */
+    initialPositions?: Map<HypergraphId, Vec2>;
+    initialDualPositions?: Map<HypergraphId, Vec2>;
+    options: LayoutOptions;
+    /** Throttle the worker → main progress stream. Default 25 iters. */
+    progressEvery?: number;
+}
+export interface LayoutJobResult {
+    /** Hypergraph state after optimization + reversal (H_0 in the typical pipeline). */
+    finalHypergraph: HypergraphData;
+    vertexPositions: Map<HypergraphId, Vec2>;
+    dualPositions: Map<HypergraphId, Vec2>;
+    energy: number;
+}
+/**
+ * Run optimize + (optional) reverse in a worker. The host main thread
+ * stays interactive while L-BFGS chews through iterations; progress
+ * events fire via `input.options.onProgress` as they normally would.
+ *
+ * @param useWorker false to force the inline (sync) path even when a
+ *                  worker is available. Useful for tests or for users
+ *                  who want strictly serialized execution.
+ */
+export declare function runLayoutJob(input: LayoutJobInput, useWorker?: boolean): Promise<LayoutJobResult>;

package/types/internals/labels/SpatialGrid.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SpatialGrid: 2D spatial hash grid for fast overlap detection of label bounding boxes.
+ * Uses a cell-based grid to provide O(1) insertion and query for nearby elements,
+ * avoiding O(n²) pairwise collision checks.
+ */
+export declare class SpatialGrid {
+    private grid;
+    private bounds;
+    private cellSize;
+    constructor(bounds: number[], cellSize?: number);
+    /**
+     * Returns all cell keys that a rectangle (centered at x,y with size w×h) overlaps.
+     */
+    private getCellsForRect;
+    /**
+     * Insert an element id into all grid cells that its bounding box overlaps.
+     * @param id - Element identifier (index into the rects array)
+     * @param x - Center X of the bounding box
+     * @param y - Center Y of the bounding box
+     * @param w - Width of the bounding box
+     * @param h - Height of the bounding box
+     */
+    insert(id: number, x: number, y: number, w: number, h: number): void;
+    /**
+     * Query all element ids whose bounding boxes potentially overlap a given rectangle.
+     */
+    getNearbyElements(x: number, y: number, w: number, h: number): Set<number>;
+    clear(): void;
+}

package/types/internals/labels/fillEdgeTexts.d.ts

@@ -0,0 +1,25 @@
+/**
+ * fillEdgeTexts: determines which edge labels to show and their positions.
+ *
+ * Iterates through edge indices in layer order (highest layer first),
+ * computes label geometry for each edge, checks for collisions using the
+ * SpatialGrid, and populates the output structure with bounding boxes
+ * and oriented rects for visible labels.
+ */
+import { SpatialGrid } from './SpatialGrid';
+import { type EdgeAttributes, type NodeAttributes, type FrameData, type LabelOutput, type MeasureTextFn } from './helpers';
+/**
+ * Fill edge text labels into the output structure.
+ *
+ * @param indices - Array of edge indices to process
+ * @param frame - Current frame/camera data (angle, zoom, etc.)
+ * @param edgeAttrs - Edge attribute flex arrays
+ * @param nodeAttrs - Node attribute flex arrays (needed for source/target positions)
+ * @param measureText - Function to measure text dimensions
+ * @param output - Output structure to populate with label bboxes and rects
+ * @param hoveredEdge - Index of currently hovered edge (or null)
+ * @param geoEnabled - Whether geographic mode is enabled
+ * @param grid - SpatialGrid for overlap detection
+ * @returns The populated output structure
+ */
+export declare function fillEdgeTexts(indices: number[], frame: FrameData, edgeAttrs: EdgeAttributes, nodeAttrs: NodeAttributes, measureText: MeasureTextFn, output: LabelOutput, hoveredEdge: number | null, geoEnabled: boolean, grid: SpatialGrid): LabelOutput;

package/types/internals/labels/fillNodeTexts.d.ts

@@ -0,0 +1,24 @@
+/**
+ * fillNodeTexts: determines which node labels to show and their positions.
+ *
+ * Iterates through node indices in layer order (highest layer first),
+ * computes label geometry for each node, checks for collisions using the
+ * SpatialGrid, and populates the output structure with bounding boxes
+ * and oriented rects for visible labels.
+ */
+import { SpatialGrid } from './SpatialGrid';
+import { type NodeAttributes, type FrameData, type LabelOutput } from './helpers';
+/**
+ * Fill node text labels into the output structure.
+ *
+ * @param indices - Array of node indices to process
+ * @param frame - Current frame/camera data (angle, zoom, sin, cos)
+ * @param nodeAttrs - Node attribute flex arrays
+ * @param getDisplacement - Function returning the 10-element displacement tuple for a node index
+ * @param output - Output structure to populate with label bboxes and rects
+ * @param hoveredNode - Index of currently hovered node (or null)
+ * @param grid - SpatialGrid for overlap detection
+ * @param preventOverlap - Whether to perform overlap avoidance
+ * @returns The populated output structure
+ */
+export declare function fillNodeTexts(indices: number[], frame: FrameData, nodeAttrs: NodeAttributes, getDisplacement: (index: number) => [number, number, number, number, number, number, number, number, number, number], output: LabelOutput, hoveredNode: number | null, grid: SpatialGrid, preventOverlap: boolean): LabelOutput;