@expertrees/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,428 @@
+import { SimulationLinkDatum } from 'd3-force';
+import { SimulationNodeDatum } from 'd3-force';
+
+export declare const BUBBLE_WORLD_RADIUS = 40;
+
+export declare class CanvasRenderer {
+    private _canvas;
+    private _ctx;
+    private _theme;
+    private _dpr;
+    private _bgStars;
+    private _burst;
+    private readonly _burstDuration;
+    private _implode;
+    private readonly _implodeDuration;
+    constructor(canvas: HTMLCanvasElement, theme?: ThemeInput);
+    get canvas(): HTMLCanvasElement;
+    get isBurstActive(): boolean;
+    /** Sync canvas physical pixel size to its CSS size. Call when the container resizes. */
+    resize(): void;
+    /** Returns the resolved fill color for a node (used for burst color matching). */
+    resolveNodeColor(node: SkillNode): string;
+    updateTheme(theme: ThemeInput): void;
+    triggerBurst(centerCanvas: Position, color: string): void;
+    triggerImplode(centerCanvas: Position): void;
+    render(nodes: SkillNode[], edges: SkillEdge[], state: RenderState): void;
+    private _renderBgStars;
+    private _drawNode;
+    private _drawBubble;
+    private _drawStar;
+    private _renderEdgeParticles;
+    private _renderBurst;
+    private _renderImplode;
+    private _resolveStyle;
+    private _drawShape;
+    private _polygon;
+    private _star;
+    private _drawEdge;
+    private _resize;
+    dispose(): void;
+}
+
+export declare const defaultTheme: Theme;
+
+export declare interface EdgeStyle {
+    color: string;
+    width: number;
+    opacity: number;
+    dashPattern?: number[];
+    animated: boolean;
+}
+
+declare type EventListener_2<T> = T extends void ? () => void : (payload: T) => void;
+
+export declare interface Evidence {
+    id: string;
+    type: EvidenceType;
+    label: string;
+    url?: string;
+    description?: string;
+    date?: string;
+    tags?: string[];
+    thumbnail?: string;
+    meta?: Record<string, unknown>;
+}
+
+export declare type EvidenceType = 'link' | 'text' | 'image' | 'video' | 'file';
+
+export declare class ForceLayout {
+    private _simulation;
+    run(nodes: SkillNode[], edges: SkillEdge[], options: ForceLayoutOptions): void;
+    stop(): void;
+    reheat(): void;
+    private _collectPositions;
+}
+
+export declare interface ForceLayoutOptions {
+    width: number;
+    height: number;
+    /** Charge strength — negative = repulsion */
+    chargeStrength?: number;
+    /** Collision radius multiplier relative to node size */
+    collisionPadding?: number;
+    alphaDecay?: number;
+    onTick?: (positions: Map<string, Position>) => void;
+    onEnd?: (positions: Map<string, Position>) => void;
+}
+
+declare type GraphEvents = {
+    nodeStateChanged: {
+        nodeId: string;
+        state: NodeState;
+    };
+    nodeAdded: {
+        node: SkillNode;
+    };
+    nodeRemoved: {
+        nodeId: string;
+    };
+    edgeAdded: {
+        edge: SkillEdge;
+    };
+    edgeRemoved: {
+        edgeId: string;
+    };
+    evidenceAdded: {
+        nodeId: string;
+        evidence: Evidence;
+    };
+    evidenceRemoved: {
+        nodeId: string;
+        evidenceId: string;
+    };
+    changed: void;
+};
+
+export declare class InteractionController {
+    private _canvas;
+    private _state;
+    private _isPanning;
+    private _lastPan;
+    private _listeners;
+    private _nodes;
+    private _positions;
+    private _nodeSize;
+    private _dpr;
+    private _targetZoom;
+    private _zoomAnchor;
+    private readonly _zoomLerpAlpha;
+    private _timedZoom;
+    private _activePointers;
+    private _lastPinchDist;
+    private _pointerDownPos;
+    private _onPointerDown;
+    private _onPointerMove;
+    private _onPointerUp;
+    private _onPointerCancel;
+    private _onWheel;
+    constructor(canvas: HTMLCanvasElement);
+    get state(): Readonly<InteractionState>;
+    get targetZoom(): number;
+    get zoomAnchor(): Position | null;
+    setTargetZoom(value: number, anchor?: Position): void;
+    /**
+     * Animate zoom to `target` over `duration` ms.
+     * `easing: 'in'`  — cubic ease-in  (slow start, accelerates toward target).
+     * `easing: 'out'` — cubic ease-out (fast start, decelerates toward target).
+     */
+    startTimedZoom(target: number, duration: number, anchor?: Position, easing?: 'in' | 'out'): void;
+    /** Instantly snap zoom and pan to a new center — used on navigation transitions. */
+    resetToCenter(zoom: number, cx: number, cy: number): void;
+    updateNodes(nodes: SkillNode[], positions: Map<string, Position>, nodeSize: number): void;
+    onChange(listener: (event: InteractionEvent) => void): () => void;
+    /**
+     * Advance zoom animation one frame. Called every RAF frame by the engine.
+     * Returns true while the animation is still in progress.
+     */
+    tick(): boolean;
+    dispose(): void;
+    canvasToWorld(canvasX: number, canvasY: number): Position;
+    private _getCanvasPos;
+    private _hitTest;
+    private _emit;
+    private _handlePointerDown;
+    private _handlePointerMove;
+    private _handlePointerUp;
+    private _handlePointerCancel;
+    private _handleWheel;
+}
+
+export declare type InteractionEvent = {
+    type: 'node:click';
+    nodeId: string;
+} | {
+    type: 'node:hover';
+    nodeId: string;
+} | {
+    type: 'node:blur';
+    nodeId: string;
+} | {
+    type: 'canvas:click';
+} | {
+    type: 'zoom:change';
+    zoom: number;
+} | {
+    type: 'pan:change';
+    pan: Position;
+};
+
+export declare interface InteractionState {
+    pan: Position;
+    zoom: number;
+    hoveredNodeId: string | null;
+    selectedNodeId: string | null;
+}
+
+export declare type InternalNodeState = 'idle' | 'hovered' | 'selected' | 'expanded';
+
+export declare interface LayoutLink extends SimulationLinkDatum<LayoutNode> {
+    id: string;
+}
+
+export declare interface LayoutNode extends SimulationNodeDatum {
+    id: string;
+    depth: number;
+    x: number;
+    y: number;
+}
+
+export declare class LodController {
+    private _thresholds;
+    private _zoom;
+    private _listeners;
+    constructor(thresholds?: LodThreshold[]);
+    get zoom(): number;
+    get thresholds(): readonly LodThreshold[];
+    setZoom(zoom: number): void;
+    onChange(listener: (zoom: number) => void): () => void;
+    private _notify;
+}
+
+export declare interface LodThreshold {
+    depth: number;
+    minZoom: number;
+    maxZoom: number;
+}
+
+export declare function mergeTheme(overrides?: ThemeInput): Theme;
+
+export declare class NavigationController {
+    private _stack;
+    private _listeners;
+    constructor(root?: NavigationFrame);
+    get current(): NavigationFrame;
+    get stack(): readonly NavigationFrame[];
+    get canGoBack(): boolean;
+    push(frame: NavigationFrame): void;
+    pop(): NavigationFrame | undefined;
+    reset(): void;
+    onChange(listener: (stack: readonly NavigationFrame[]) => void): () => void;
+    private _notify;
+}
+
+export declare interface NavigationFrame {
+    nodeId: string | null;
+    label: string;
+}
+
+export declare type NodeShape = 'circle' | 'star' | 'hexagon' | 'diamond';
+
+export declare type NodeState = 'default' | 'active' | 'locked' | 'unlocked' | 'highlighted';
+
+export declare interface NodeStyle {
+    color: string;
+    glowColor: string;
+    glowRadius: number;
+    size: number;
+    shape: NodeShape;
+    opacity: number;
+    labelColor: string;
+    labelSize: number;
+    labelFont: string;
+}
+
+export declare interface Position {
+    x: number;
+    y: number;
+}
+
+export declare interface RenderState {
+    positions: Map<string, Position>;
+    internalStates: Map<string, InternalNodeState>;
+    contextFadeAlpha: number;
+    pan: Position;
+    zoom: number;
+}
+
+export declare interface SkillEdge {
+    id: string;
+    source: string;
+    target: string;
+    directed: boolean;
+    label?: string;
+    style?: Partial<EdgeStyle>;
+    meta?: Record<string, unknown>;
+}
+
+export declare interface SkillGraph {
+    id: string;
+    label: string;
+    nodes: SkillNode[];
+    edges: SkillEdge[];
+    theme?: ThemeInput;
+    meta?: Record<string, unknown>;
+}
+
+export declare class SkillGraphModel {
+    private _graph;
+    private _meta;
+    private _label;
+    private _id;
+    private _listeners;
+    constructor(data: SkillGraph);
+    get id(): string;
+    get label(): string;
+    get meta(): Record<string, unknown> | undefined;
+    getNode(id: string): SkillNode | undefined;
+    getEdge(id: string): SkillEdge | undefined;
+    getNodes(): SkillNode[];
+    getEdges(): SkillEdge[];
+    getChildren(nodeId: string): SkillNode[];
+    getNodesAtDepth(depth: number): SkillNode[];
+    getNodesUpToDepth(depth: number): SkillNode[];
+    setNodeState(nodeId: string, state: NodeState): void;
+    addNode(node: SkillNode): void;
+    removeNode(nodeId: string): void;
+    addEdge(edge: SkillEdge): void;
+    removeEdge(edgeId: string): void;
+    addEvidence(nodeId: string, evidence: Evidence): void;
+    removeEvidence(nodeId: string, evidenceId: string): void;
+    toJSON(): SkillGraph;
+    static fromJSON(data: SkillGraph): SkillGraphModel;
+    on<K extends keyof GraphEvents>(event: K, listener: EventListener_2<GraphEvents[K]>): () => void;
+    private _emit;
+}
+
+export declare interface SkillNode {
+    id: string;
+    label: string;
+    description?: string;
+    depth: number;
+    parentId?: string;
+    childIds?: string[];
+    position?: Position;
+    state?: NodeState;
+    evidence?: Evidence[];
+    style?: Partial<NodeStyle>;
+    meta?: Record<string, unknown>;
+}
+
+export declare class SkillTreeEngine {
+    private _model;
+    private _nav;
+    private _lod;
+    private _layout;
+    private _renderer;
+    private _interaction;
+    private _positions;
+    private _internalStates;
+    private _eventHandlers;
+    private _rafId;
+    private _pendingEnter;
+    private _pendingExit;
+    private _unsubscribers;
+    private _resizeObserver;
+    private _visibleNodes;
+    private _visibleEdges;
+    private _contextFadeAlpha;
+    private _contextFadeStart;
+    private readonly _contextFadeDuration;
+    private _navCooldownUntil;
+    constructor(options: SkillTreeEngineOptions);
+    setNodeState(nodeId: string, state: NodeState): void;
+    addEvidence(nodeId: string, evidence: Evidence): void;
+    removeEvidence(nodeId: string, evidenceId: string): void;
+    updateTheme(theme: ThemeInput): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    goBack(): void;
+    /**
+     * Atomically jump to a specific nav stack depth, firing a single animation.
+     * `targetLength` is the desired `stack.length` after the jump.
+     * Silently pops intermediate frames; plays one implode + fade transition.
+     */
+    jumpToNavDepth(targetLength: number): void;
+    private _exitWithAnimation;
+    enterContext(nodeId: string): void;
+    getGraph(): SkillGraph;
+    getNavigationStack(): readonly NavigationFrame[];
+    dispose(): void;
+    private _rebuildVisibleCache;
+    private _isBubble;
+    private _enterContext;
+    private _exitContext;
+    private _checkNavigation;
+    private _findBubbleAtCanvas;
+    private _wireEvents;
+    private _runLayout;
+    private _startRenderLoop;
+    private _draw;
+}
+
+export declare interface SkillTreeEngineOptions {
+    canvas: HTMLCanvasElement;
+    data: SkillGraph;
+    theme?: ThemeInput;
+    lod?: LodThreshold[];
+    on?: Partial<SkillTreeEvents>;
+    /** Silently start inside this bubble node's context — no burst or fade animation */
+    initialContextNodeId?: string;
+}
+
+export declare interface SkillTreeEvents {
+    'node:click': (node: SkillNode) => void;
+    'node:hover': (node: SkillNode) => void;
+    'node:blur': (node: SkillNode) => void;
+    'canvas:click': () => void;
+    'zoom:change': (zoom: number) => void;
+    'context:enter': (node: SkillNode, stack: readonly NavigationFrame[]) => void;
+    'context:exit': (frame: NavigationFrame, stack: readonly NavigationFrame[]) => void;
+    'graph:ready': (graph: SkillGraph) => void;
+}
+
+export declare interface Theme {
+    background: string;
+    node: NodeStyle;
+    edge: EdgeStyle;
+    states: Record<NodeState, Partial<NodeStyle>>;
+}
+
+export declare interface ThemeInput {
+    background?: string;
+    node?: Partial<NodeStyle>;
+    edge?: Partial<EdgeStyle>;
+    states?: Partial<Record<NodeState, Partial<NodeStyle>>>;
+}
+
+export { }