@visualli/react 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,375 @@
+import React$1 from 'react';
+import { VisualliDocument, FlatNode, VisualliLayer, NodeMap, ViewportState, IRenderConfigStore, ISelectionStore, MindMapConnection } from '@visualli/core';
+export { ACTIVE_BLOB_TYPES, ALL_BLOB_SHAPES, BLOB_LAYER_CONFIG, BLOB_TEXT_OFFSETS, DESCRIPTION_TEXT_BASE_FONT_PX, FitResult, NODE_LAYER_CONFIG, NODE_TEXT_BASE_FONT_PX, calculateFitCenter, calculateFitView, calculateFitZoom, computeEdgeLabelScale, computeNodeTextScreenScale, computeNodeTextWorldScale, computeOverlayScale, drawBlobPath, getBlobTypeForLayer, getChildLayerForNode, getConnectionsForLayer, getLayerForNavigation } from '@visualli/core';
+import * as zustand from 'zustand';
+import Konva from 'konva';
+import * as konva_lib_Stage from 'konva/lib/Stage';
+
+type VisualliTheme = 'dark' | 'light' | 'auto';
+interface VisualliRendererProps {
+    /**
+     * Raw JSONL string — the content of a .visualli file.
+     * Simply pass the string data directly, no preprocessing needed.
+     * Example: visualliString="{\"type\":\"meta\"...}\n{\"type\":\"layer\"...}"
+     */
+    visualliString?: string;
+    /**
+     * A .visualli file — can be:
+     *  - File object (e.g. from <input type="file">)
+     *  - String path to file (e.g. '/data/myfile.visualli' or './src/data/data.visualli')
+     * The renderer automatically fetches, reads, and parses it.
+     * No user code required for conversion or processing.
+     */
+    visualliFile?: File | string;
+    /**
+     * When true, parsing is offloaded to a Web Worker so the main thread never
+     * blocks during JSON.parse. Recommended for large documents (>500 nodes).
+     * Has no effect when `document` is supplied (already parsed).
+     * @default true
+     */
+    useWorker?: boolean;
+    /**
+     * Colour theme.
+     *  - 'dark'  → always dark background
+     *  - 'light' → always light background
+     *  - 'auto'  → follows the OS/browser prefers-color-scheme
+     * @default 'light'
+     */
+    theme?: VisualliTheme;
+    /**
+     * Enable chromatic immersion background effect.
+     * When true:
+     *  - Root layer (level 0) shows base background color
+     *  - Child layers show parent node's color as semi-transparent background
+     * @default false
+     */
+    chromaticImmersion?: boolean;
+    /**
+     * Width of the renderer. Accepts any CSS length string ('100%', '800px', '100vw')
+     * or a plain number treated as pixels.
+     * @default '100%'
+     */
+    width?: string | number;
+    /**
+     * Height of the renderer. Accepts any CSS length string ('100%', '600px', '100vh')
+     * or a plain number treated as pixels.
+     * @default '100%'
+     */
+    height?: string | number;
+    /** Additional CSS class on the root element. */
+    className?: string;
+    /** Additional inline styles merged onto the root element. */
+    style?: React$1.CSSProperties;
+}
+declare function VisualliRenderer({ visualliString, visualliFile, theme, width, height, useWorker, chromaticImmersion, className, style, }: VisualliRendererProps): React$1.JSX.Element;
+
+interface VisualliCanvasProps {
+    preParsedVisualli?: VisualliDocument;
+    /**
+     * Raw JSONL string — just pass the string data directly.
+     * No preprocessing needed by user.
+     */
+    visualliString?: string;
+    /**
+     * A .visualli file — can be:
+     *  - File object (from file input)
+     *  - String path to file (e.g. '/data/file.visualli')
+     * Component handles all fetching and parsing automatically.
+     */
+    visualliFile?: File | string;
+    isDark?: boolean;
+    chromaticImmersion?: boolean;
+    onNodeClick?: (node: FlatNode) => void;
+    onLayerChange?: (layerId: string, layer: VisualliLayer) => void;
+    renderOverlay?: (params: {
+        isDark: boolean;
+        containerWidth: number;
+        containerHeight: number;
+    }) => React$1.ReactNode;
+    renderNodeContent?: (params: {
+        summary: string;
+        nodeId: string;
+        nodeColor?: string;
+        zoom: number;
+    }) => React$1.ReactNode;
+    navigationStackTop?: string;
+    navigationStackLeft?: string;
+    className?: string;
+    style?: React$1.CSSProperties;
+}
+declare function VisualliCanvas(props: VisualliCanvasProps): React$1.JSX.Element;
+
+interface VisualliContextValue {
+}
+interface VisualliProviderProps {
+    children: React$1.ReactNode;
+}
+/**
+ * Provider for Visualli context
+ *
+ * @example
+ * ```tsx
+ * <VisualliProvider>
+ *   <VisualliCanvas document={doc} />
+ * </VisualliProvider>
+ * ```
+ */
+declare function VisualliProvider({ children, }: VisualliProviderProps): React$1.JSX.Element;
+/**
+ * Hook to access Visualli context
+ *
+ * Returns default empty values if used outside of VisualliProvider
+ */
+declare function useVisualli(): VisualliContextValue;
+
+interface INodeStore {
+    nodes: NodeMap;
+    childrenIndex: Map<string | null, Set<string>>;
+    setNodes: (nodes: NodeMap) => void;
+    updateNode: (nodeId: string, updates: Partial<FlatNode>) => void;
+    updateNodePosition: (nodeId: string, x: number, y: number) => void;
+    addNode: (node: FlatNode) => void;
+    removeNode: (nodeId: string) => void;
+    setNodeExpanded: (nodeId: string, expanded: boolean) => void;
+    getNode: (nodeId: string) => FlatNode | undefined;
+    getChildren: (parentId: string | null) => FlatNode[];
+    getChildrenIds: (parentId: string | null) => Set<string>;
+    getAllNodes: () => FlatNode[];
+}
+declare const useNodeStore: zustand.UseBoundStore<zustand.StoreApi<INodeStore>>;
+
+interface IViewportStore extends ViewportState {
+    canvasWidth: number;
+    canvasHeight: number;
+    pan: (deltaX: number, deltaY: number) => void;
+    zoom: (delta: number, pivotX?: number, pivotY?: number) => void;
+    setCenter: (x: number, y: number) => void;
+    setZoom: (level: number) => void;
+    updateCanvasSize: (width: number, height: number) => void;
+    getVisibleBounds: () => ViewportState['visibleBounds'];
+    worldToScreen: (x: number, y: number) => {
+        x: number;
+        y: number;
+    };
+    screenToWorld: (x: number, y: number) => {
+        x: number;
+        y: number;
+    };
+}
+declare const useViewportStore: zustand.UseBoundStore<zustand.StoreApi<IViewportStore>>;
+
+declare const useSelectionStore: zustand.UseBoundStore<zustand.StoreApi<ISelectionStore>>;
+declare const useRenderConfigStore: zustand.UseBoundStore<zustand.StoreApi<IRenderConfigStore>>;
+
+interface UseKonvaRendererOptions {
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    stageRef?: React.RefObject<Konva.Stage | null>;
+    enabled?: boolean;
+}
+interface UseKonvaRendererReturn {
+    handleWheel: (e: Konva.KonvaEventObject<WheelEvent>) => void;
+    handleMouseDown: (e: Konva.KonvaEventObject<MouseEvent>) => void;
+    handleMouseMove: (e: Konva.KonvaEventObject<MouseEvent>) => void;
+    handleMouseUp: (e: Konva.KonvaEventObject<MouseEvent>) => void;
+    canvasWidth: number;
+    canvasHeight: number;
+}
+declare function useKonvaRenderer({ containerRef, stageRef, enabled, }: UseKonvaRendererOptions): UseKonvaRendererReturn;
+
+interface AnimatorViewport {
+    centerX: number;
+    centerY: number;
+    zoomLevel: number;
+}
+interface NodeBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface TransitionCallbacks {
+    onUpdate: (state: {
+        viewport: AnimatorViewport;
+        opacity: number;
+        backgroundColor: string;
+    }) => void;
+    onComplete: () => void;
+    onPhaseChange?: (phase: string) => void;
+}
+declare class KonvaLayerTransitionAnimator {
+    private rafId;
+    private timers;
+    private _active;
+    get active(): boolean;
+    cancel(): void;
+    animateZoomIntoLayer(current: AnimatorViewport, targetNode: NodeBounds, childCenter: {
+        x: number;
+        y: number;
+    }, fromColor: string, toColor: string, cb: TransitionCallbacks, targetZoom?: number, canvasWidth?: number, canvasHeight?: number): void;
+    animateZoomOutToParent(current: AnimatorViewport, parent: AnimatorViewport, fromColor: string, toColor: string, cb: TransitionCallbacks): void;
+    private _complete;
+}
+declare const konvaLayerTransitionAnimator: KonvaLayerTransitionAnimator;
+
+interface LayerTransitionOptions {
+    /** Ref to the Konva Stage for imperative position/scale updates each frame. */
+    stageRef: React.RefObject<Konva.Stage | null>;
+    /** Ref to the wrapping div whose CSS `opacity` is driven during transitions. */
+    canvasWrapperRef: React.RefObject<HTMLDivElement | null>;
+    /** Ref to the background color div. */
+    bgRef?: React.RefObject<HTMLDivElement | null>;
+    /** Called at the content-swap point — use to switch the displayed layer. */
+    onSwapLayer: (newLayerId: string) => void;
+    /** Called when a zoom-out swap happens — use to update the nav stack. */
+    onSwapBack: () => void;
+    /** Called after the transition fully completes. */
+    onComplete: () => void;
+    /**
+     * GPU CSS-transform mode: called each rAF frame instead of applyViewport.
+     * When provided, the caller is responsible for moving the canvas content.
+     */
+    onViewportFrame?: (vp: AnimatorViewport) => void;
+    /**
+     * Called once when the animation reaches its final viewport.
+     * When provided, replaces the default applyViewport call at completion.
+     */
+    onViewportFinal?: (vp: AnimatorViewport) => void;
+    /**
+     * Called at phase-change points ('swap', 'zoom-back') in addition to the
+     * internal content-swap logic. Use to reset CSS transforms before Konva redraws.
+     */
+    onPhaseChange?: (phase: string) => void;
+    /**
+     * Called with 'start' before the animator fires its first frame and with
+     * 'end' after onComplete. Use to set up / tear down GPU hints (willChange, etc.).
+     */
+    onTransitionLifecycle?: (phase: 'start' | 'end') => void;
+}
+interface LayerTransitionHandlers {
+    zoomIntoLayer: (doc: VisualliDocument, targetNode: FlatNode, childLayerId: string, childNodes: FlatNode[], fromColor: string, toColor: string) => void;
+    zoomOutToParent: (parentViewport: AnimatorViewport, fromColor: string, toColor: string) => void;
+    isTransitioning: () => boolean;
+}
+declare function useKonvaLayerTransition(opts: LayerTransitionOptions): LayerTransitionHandlers;
+
+declare function useViewportNodes(nodes: FlatNode[], levelFilter?: number, skipCulling?: boolean, 
+/** When true, skip culling so dragged nodes are always visible and the
+ *  spatial index (keyed on layout positions) is not consulted. */
+isDragging?: boolean): FlatNode[];
+
+interface BlobPoint {
+    x: number;
+    y: number;
+}
+type BlobShape = ReadonlyArray<BlobPoint>;
+declare function buildBlobPathData(_shape: BlobShape, cx: number, cy: number, width: number, height: number): string;
+
+interface KonvaStageProps {
+    children: React$1.ReactNode;
+    onWheel?: (e: Konva.KonvaEventObject<WheelEvent>) => void;
+    onMouseDown?: (e: Konva.KonvaEventObject<MouseEvent>) => void;
+    onMouseMove?: (e: Konva.KonvaEventObject<MouseEvent>) => void;
+    onMouseUp?: (e: Konva.KonvaEventObject<MouseEvent>) => void;
+    onContextMenu?: (e: Konva.KonvaEventObject<MouseEvent>) => void;
+    onTouchStart?: (e: Konva.KonvaEventObject<TouchEvent>) => void;
+    onTouchMove?: (e: Konva.KonvaEventObject<TouchEvent>) => void;
+    onTouchEnd?: (e: Konva.KonvaEventObject<TouchEvent>) => void;
+    onStageReady?: (stage: Konva.Stage) => void;
+}
+declare const KonvaStage: React$1.ForwardRefExoticComponent<KonvaStageProps & React$1.RefAttributes<konva_lib_Stage.Stage>>;
+
+interface KonvaNodeProps {
+    node: FlatNode;
+    zoomLevel: number;
+    /** True when the pointer is currently over this node (stage-level hit test). */
+    isExternallyHovered?: boolean;
+    /** True while this node is being pressed/dragged. */
+    isExternallyPressed?: boolean;
+    /** True while any node is being dragged — disables expensive shadows. */
+    isDragging?: boolean;
+}
+declare const KonvaNode: React$1.NamedExoticComponent<KonvaNodeProps>;
+
+interface KonvaEdgeProps {
+    sourceNode: FlatNode;
+    targetNode: FlatNode;
+    connection?: MindMapConnection;
+    isDark?: boolean;
+    colorOverride?: string;
+    zoomLevel?: number;
+}
+declare const KonvaEdge: React$1.NamedExoticComponent<KonvaEdgeProps>;
+
+interface KonvaNodeLayerProps {
+    nodes?: FlatNode[];
+    isTransitioning?: boolean;
+    isDragging?: boolean;
+    hoveredNodeId?: string | null;
+    pressedNodeId?: string | null;
+}
+declare function KonvaNodeLayer({ nodes: propNodes, isTransitioning, isDragging, hoveredNodeId, pressedNodeId, }: KonvaNodeLayerProps): React$1.JSX.Element;
+
+interface KonvaEdgeLayerProps {
+    nodes: FlatNode[];
+    connections: MindMapConnection[];
+    currentLevel?: number;
+    isDark?: boolean;
+    /** Pass true while a node is being dragged to skip viewport culling. */
+    isDragging?: boolean;
+}
+declare function KonvaEdgeLayer({ nodes, connections, currentLevel, isDark, isDragging, }: KonvaEdgeLayerProps): React$1.JSX.Element;
+
+interface KonvaContainerProps {
+    /** All nodes in this container group (already resolved from nodeMap). */
+    nodes: FlatNode[];
+    /** Label text shown on the pill badge. */
+    label?: string;
+    /** Unused – kept for API compat; stroke is always #747270. */
+    color?: string;
+    isDark?: boolean;
+}
+declare const KonvaContainer: React$1.NamedExoticComponent<KonvaContainerProps>;
+
+interface ContainerGroup {
+    id: string;
+    label?: string;
+    nodeIds: string[];
+    level: number;
+}
+interface KonvaContainerLayerProps {
+    /** Layout-snapshot nodes — used only as a seed for initial IDs. */
+    nodes: FlatNode[];
+    containers: ContainerGroup[];
+    isDark?: boolean;
+}
+declare function KonvaContainerLayer({ nodes, containers, isDark }: KonvaContainerLayerProps): React$1.JSX.Element | null;
+
+interface NavStackEntry {
+    layerId: string;
+    layer: VisualliLayer;
+    label: string;
+}
+interface NavigationStackProps {
+    stack: NavStackEntry[];
+    onNavigateBack: (index: number) => void;
+    isDark?: boolean;
+    top?: string;
+    left?: string;
+}
+declare const NavigationStack: React$1.NamedExoticComponent<NavigationStackProps>;
+
+interface ZoomControlsProps {
+    isDark?: boolean;
+}
+declare const ZoomControls: React$1.NamedExoticComponent<ZoomControlsProps>;
+
+interface SketchyBoxKonvaProps {
+    children: React$1.ReactNode;
+    fill: string;
+    stroke: string;
+    backStroke: string;
+    padding?: string;
+}
+declare const SketchyBoxKonva: React$1.FC<SketchyBoxKonvaProps>;
+
+export { type AnimatorViewport, type ContainerGroup, type INodeStore, type IViewportStore, KonvaContainer, KonvaContainerLayer, KonvaEdge, KonvaEdgeLayer, type KonvaEdgeProps, KonvaLayerTransitionAnimator, KonvaNode, KonvaNodeLayer, type KonvaNodeProps, KonvaStage, type KonvaStageProps, type LayerTransitionHandlers, type NavStackEntry, NavigationStack, SketchyBoxKonva, type TransitionCallbacks, type UseKonvaRendererOptions, type UseKonvaRendererReturn, VisualliCanvas, type VisualliCanvasProps, type VisualliContextValue, VisualliProvider, type VisualliProviderProps, VisualliRenderer, type VisualliRendererProps, type VisualliTheme, ZoomControls, buildBlobPathData, konvaLayerTransitionAnimator, useKonvaLayerTransition, useKonvaRenderer, useNodeStore, useRenderConfigStore, useSelectionStore, useViewportNodes, useViewportStore, useVisualli };