@visualli/react 0.1.1 → 0.1.2

package/README.md

@@ -1,20 +1,18 @@
 # @visualli/react
 
-React canvas rendering for Visualli — powered by Konva. Drop-in component that displays a `VisualliDocument` as an interactive, zoomable, navigable mind-map.
+React canvas rendering for Visualli — powered by Konva. A high-performance component suite that displays `.visualli` documents as interactive, zoomable, and navigable mind-maps.
 
 ## Features
 
-- **GPU-accelerated canvas** via `react-konva` — handles thousands of nodes at 60 fps
-- **Organic blob nodes** — 6 quadratic-bezier blob shapes that cycle by level
-- **Layer navigation** — double-click any node to drill into its child layer, breadcrumb back
-- **Animated transitions** — rAF-driven zoom-into-layer / zoom-out-to-parent with color crossfade
-- **Zoom controls** — +/− buttons, %, fit-to-screen
-- **Viewport culling** — RBush spatial index keeps only visible nodes on the canvas
-- **Zustand stores** — fine-grained subscriptions for nodes, viewport, selection, render config
-- **Light / dark theme** — single `isDark` prop
-- **🆕 Extension system** — inject custom parser middlewares and UI components at runtime
-- **🆕 Stream fetching** — `useVisualliStream` hook for backend JSONL streams
-- **🆕 Context provider** — `VisualliProvider` for dependency injection
+- **High-Performance Canvas** — GPU-accelerated rendering via `react-konva` capable of handling thousands of nodes at 60fps
+- **Organic Visuals** — Dynamic blob-based node shapes that cycle by hierarchy level
+- **Layer Navigation** — Drill down into child layers and navigate back via breadcrumb UI
+- **Smooth Transitions** — Animated zoom effects with color crossfading during layer changes
+- **Chromatic Immersion** — Optional background effects that adapt to the current layer's context
+- **Viewport Culling** — Spatial indexing ensures only visible elements are rendered
+- **Worker-based Parsing** — Parse large documents off the main thread to prevent UI blocking
+- **Flexible Theming** — Light, Dark, and System-aware (auto) theme support
+- **State Management** — Fine-grained control via Zustand stores for viewport, nodes, and selection
 
 ## Installation
 
@@ -22,293 +20,151 @@ React canvas rendering for Visualli — powered by Konva. Drop-in component that
 npm install @visualli/react @visualli/core konva react-konva zustand
 ```
 
-Peer dependencies: `react@^18`, `react-dom@^18`
+**Peer dependencies:** `react@^18`, `react-dom@^18`
 
 ## Quick Start
 
-```tsx
-import { VisualliCanvas } from '@visualli/react';
-
-// Option A — pass a pre-parsed VisualliDocument
-import { parseVisualliFile } from '@visualli/core';
-
-const doc = parseVisualliFile(rawJsonlString);
+Use `VisualliRenderer` for the simplest integration — it handles loading, parsing, error states, and responsive sizing automatically.
 
-export default function App() {
-  return (
-    <div style={{ width: '100vw', height: '100vh' }}>
-      <VisualliCanvas document={doc} isDark={false} />
-    </div>
-  );
-}
+```tsx
+import { VisualliRenderer } from '@visualli/react';
 
-// Option B — pass the raw JSONL string directly
 export default function App() {
   return (
-    <div style={{ width: '100vw', height: '100vh' }}>
-      <VisualliCanvas visualliString={rawJsonlString} isDark={true} />
-    </div>
+    <VisualliRenderer 
+      visualliFile="/data/mindmap.visualli" 
+      theme="auto"
+      width="100%"
+      height="100vh"
+    />
   );
 }
 ```
 
-## `VisualliCanvas` Props
+### Alternative: Pass Raw JSONL String
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `document` | `VisualliDocument` | — | Pre-parsed document |
-| `visualliString` | `string` | — | Raw JSONL — parsed internally |
-| `isDark` | `boolean` | `false` | Light / dark canvas theme |
-| `onNodeClick` | `(node: FlatNode) => void` | — | Single-click callback |
-| `onLayerChange` | `(id: string, layer: VisualliLayer) => void` | — | Fired after navigation |
-| `className` | `string` | `''` | Extra CSS classes on the wrapper div |
-| `style` | `React.CSSProperties` | — | Inline styles on the wrapper div |
-
-> The component fills its parent container — set an explicit `width` / `height` on the wrapper.
-
-## Architecture
-
-```
-VisualliCanvas
-├── KonvaStage              react-konva <Stage>, position/scale from viewport store
-│   ├── KonvaContainerLayer <Layer> — convex-hull outlines (non-interactive)
-│   ├── KonvaEdgeLayer      <Layer> — bezier edges between visible nodes
-│   └── KonvaNodeLayer      <Layer> — blob nodes, handles click/dblclick
-├── NavigationStack         DOM overlay — breadcrumb trail, click to go back
-└── ZoomControls            DOM overlay — +/−/% buttons, fit-to-screen
+```tsx
+<VisualliRenderer 
+  visualliString={rawJsonlString}
+  theme="dark"
+  chromaticImmersion={true}
+/>
 ```
 
-### Stores (Zustand)
-
-Access any store directly for advanced use cases:
-
-```ts
-import { useViewportStore, useNodeStore, useSelectionStore } from '@visualli/react';
-
-// Read viewport
-const { centerX, centerY, zoomLevel } = useViewportStore();
+### Alternative: Load from File Input
 
-// Programmatic zoom
-useViewportStore.getState().setZoom(1.5);
-useViewportStore.getState().setCenter(0, 0);
+```tsx
+function FileUploader() {
+  const [file, setFile] = useState<File | null>(null);
 
-// Read selected node
-const selectedId = useSelectionStore(s => s.selectedId);
+  return (
+    <>
+      <input 
+        type="file" 
+        accept=".visualli"
+        onChange={(e) => setFile(e.target.files?.[0] || null)} 
+      />
+      {file && <VisualliRenderer visualliFile={file} theme="light" />}
+    </>
+  );
+}
 ```
 
-### Hooks
+## API Reference
 
-```ts
-import { useViewportNodes } from '@visualli/react';
+### `VisualliRenderer` (Recommended)
 
-// Get nodes currently visible in the viewport (culled)
-const visible = useViewportNodes(allNodes, /* optional level filter */ 0);
-```
-
-### Navigation Stack
+The primary component for rendering `.visualli` documents. Manages the full document lifecycle including loading, parsing (with optional Web Worker), error handling, and responsive layout.
 
-Layer navigation is fully internal but observable via the `onLayerChange` callback. The breadcrumb UI renders automatically — no props required.
+#### Props
 
-Drill-in: **double-click** a node that has a child layer.  
-Back: click any crumb in the breadcrumb bar, or use `onNavigateBack` exposed by `NavigationStack` directly.
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `visualliFile` | `File \| string` | — | A `.visualli` file as a File object or URL path |
+| `visualliString` | `string` | — | Raw JSONL content as a string |
+| `theme` | `'light' \| 'dark' \| 'auto'` | `'light'` | Color theme. `'auto'` follows system preference |
+| `chromaticImmersion` | `boolean` | `false` | Enable background color effects based on layer context |
+| `useWorker` | `boolean` | `true` | Parse documents in a Web Worker (recommended for large files) |
+| `width` | `string \| number` | `'100%'` | Width as CSS value or pixel number |
+| `height` | `string \| number` | `'100%'` | Height as CSS value or pixel number |
+| `className` | `string` | — | Additional CSS classes |
+| `style` | `React.CSSProperties` | — | Inline styles |
 
-## Extension System 🆕
+> **Note:** Provide either `visualliFile` or `visualliString`, not both.
 
-The extension system allows you to inject custom parser middlewares and UI components at runtime without modifying the SDK.
+### `VisualliCanvas` (Advanced)
 
-### Basic Setup with Provider
+The low-level canvas component used internally by `VisualliRenderer`. Use this if you need direct control over the rendering pipeline or already have a parsed `VisualliDocument`.
 
-```tsx
-import { VisualliProvider, VisualliCanvas } from '@visualli/react';
+#### Props
 
-function App() {
-  return (
-    <VisualliProvider>
-      <VisualliCanvas document={document} />
-    </VisualliProvider>
-  );
-}
+| Prop | Type | Description |
+|------|------|-------------|
+| `preParsedVisualli` | `VisualliDocument` | Pre-parsed document from `@visualli/core` |
+| `visualliString` | `string` | Raw JSONL string (parsed on mount) |
+| `isDark` | `boolean` | Dark mode flag |
+| `chromaticImmersion` | `boolean` | Enable chromatic background |
+| `onNodeClick` | `(node: FlatNode) => void` | Callback fired on node click |
+| `onLayerChange` | `(id: string, layer: VisualliLayer) => void` | Callback fired on layer navigation |
 
-### With Custom Middleware
+#### Example
 
 ```tsx
-import { VisualliProvider } from '@visualli/react';
-import type { ParserMiddleware } from '@visualli/core';
+import { VisualliCanvas } from '@visualli/react';
+import { parseVisualliFile } from '@visualli/core';
 
-const myMiddleware: ParserMiddleware = (data) => {
-  if (data.type === 'extension') {
-    return { ...data, enhanced: true };
-  }
-  return data;
-};
+const document = parseVisualliFile(jsonlString);
 
-<VisualliProvider middlewares={[myMiddleware]}>
-  <App />
-</VisualliProvider>
+<VisualliCanvas 
+  preParsedVisualli={document}
+  isDark={true}
+  onNodeClick={(node) => console.log('Clicked:', node.data.label)}
+/>
 ```
 
-### With Extension Components
+## Customization & Extensions
 
-```tsx
-import type { ExtensionComponentProps } from '@visualli/react';
+The SDK is designed to be extensible. While the core renderer provides a complete visualization experience, you can extend it with custom UI overlays, data processing pipelines, or application-specific behaviors without modifying the core library. This allows developers to build specialized features on top of the base canvas while maintaining upgrade compatibility.
 
-function MyExtension({ extension, document }: ExtensionComponentProps) {
-  return (
-    <div style={{ position: 'absolute', top: 20, right: 20 }}>
-      <p>{extension.data?.message}</p>
-    </div>
-  );
-}
-
-const extensions = {
-  'my-ext-id': MyExtension,
-};
+## State Management
 
-<VisualliProvider extensions={extensions}>
-  <VisualliCanvas document={document} />
-</VisualliProvider>
-```
-
-### Stream Fetching
+The renderer uses Zustand stores for reactive state management. You can access these stores for advanced use cases like programmatic navigation or custom UI controls.
 
 ```tsx
-import { useVisualliStream, VisualliCanvas } from '@visualli/react';
-
-function MindMapViewer({ apiUrl }: { apiUrl: string }) {
-  const { document, isLoading, error, progress } = useVisualliStream(apiUrl);
-
-  if (isLoading) return <div>Loading... {progress}%</div>;
-  if (error) return <div>Error: {error.message}</div>;
-  if (!document) return null;
-
-  return <VisualliCanvas document={document} />;
-}
-```
-
-### Complete Example
+import { useViewportStore, useNodeStore, useSelectionStore } from '@visualli/react';
 
-```tsx
-import {
-  VisualliProvider,
-  useVisualliStream,
-  VisualliCanvas
-} from '@visualli/react';
-import type {
-  ParserMiddleware,
-  ExtensionComponentProps
-} from '@visualli/react';
-
-// Middleware
-const middleware: ParserMiddleware = (data) => {
-  if (data.type === 'extension') {
-    return { ...data, processed: true };
-  }
-  return data;
-};
+function CustomControls() {
+  const { zoomLevel, setZoom, setCenter } = useViewportStore();
+  const selectedNode = useSelectionStore(s => s.selectedId);
 
-// Extension Component
-function TooltipExtension({ extension }: ExtensionComponentProps) {
   return (
-    <div style={{
-      position: 'absolute',
-      top: 20,
-      right: 20,
-      background: 'white',
-      padding: '12px',
-      borderRadius: '8px',
-      pointerEvents: 'auto'
-    }}>
-      {extension.data?.message}
+    <div>
+      <button onClick={() => setZoom(zoomLevel * 1.2)}>Zoom In</button>
+      <button onClick={() => setCenter(0, 0)}>Reset View</button>
+      <p>Selected: {selectedNode}</p>
     </div>
   );
 }
-
-// App
-function App() {
-  const { document, isLoading } = useVisualliStream('/api/mindmap');
-
-  return (
-    <VisualliProvider
-      middlewares={[middleware]}
-      extensions={{ 'tooltip': TooltipExtension }}
-    >
-      {isLoading ? <Loading /> : <VisualliCanvas document={document} />}
-    </VisualliProvider>
-  );
-}
-```
-
-📚 **See `EXTENSION_GUIDE.md` for comprehensive documentation and examples.**
-
-## Exports
-
-### Component
-
-```ts
-import { VisualliCanvas } from '@visualli/react';
-```
-
-### Context & Provider 🆕
-
-```ts
-import { VisualliProvider, useVisualli } from '@visualli/react';
-import type {
-  VisualliProviderProps,
-  VisualliContextValue,
-  ExtensionComponentProps,
-  ExtensionRegistry
-} from '@visualli/react';
-```
-
-### Stores
-
-```ts
-import { useNodeStore, useViewportStore, useSelectionStore, useRenderConfigStore } from '@visualli/react';
-```
-
-### Hooks
-
-```ts
-import { useKonvaRenderer, useKonvaLayerTransition, useViewportNodes } from '@visualli/react';
-
-// 🆕 Stream fetching hook
-import { useVisualliStream } from '@visualli/react';
-import type { UseVisualliStreamReturn } from '@visualli/react';
 ```
 
-### Sub-components (composition)
+## Advanced Hooks
 
-```ts
-import {
-  KonvaStage, KonvaNode, KonvaEdge,
-  KonvaNodeLayer, KonvaEdgeLayer,
-  KonvaContainerLayer,
-  NavigationStack, ZoomControls,
-} from '@visualli/react';
-```
-
-### Utilities
+The SDK exports low-level hooks for building custom rendering pipelines:
 
-```ts
-import {
-  getChildLayerForNode, getConnectionsForLayer,
-  calculateFitView, calculateFitZoom, calculateFitCenter,
-} from '@visualli/react';
-```
+- **`useKonvaRenderer`** — Access the Konva stage and rendering loop
+- **`useViewportNodes`** — Get nodes currently visible in the viewport (post-culling)
+- **`useKonvaLayerTransition`** — Control layer transition animations
+- **`useVisualli`** — Access the Visualli context (when wrapped in `VisualliProvider`)
 
-### Config helpers
+## Requirements
 
-```ts
-import {
-  getBlobTypeForLayer, buildBlobPathData, ALL_BLOB_SHAPES,
-  computeNodeTextWorldScale, computeNodeTextScreenScale,
-} from '@visualli/react';
-```
+- Node.js ≥ 22
+- React 18
+- TypeScript 5+ (recommended)
 
-## TypeScript
+## TypeScript Configuration
 
-```jsonc
-// tsconfig.json
+```json
 {
   "compilerOptions": {
     "moduleResolution": "bundler",
@@ -317,19 +173,3 @@ import {
   }
 }
 ```
-
-## Requirements
-
-- Node.js ≥ 22
-- React 18
-- `@visualli/core` must be built (`npm run build` in `sdk-core/`) before typechecking
-
-## Typecheck
-
-```bash
-# Build core first
-cd ../sdk-core && npm run build
-
-# Typecheck react package
-cd ../sdk-react && npx tsc --noEmit
-```

package/dist/index.cjs

@@ -2720,7 +2720,10 @@ function VisualliCanvas(props) {
       setCanvasContextMenu(null);
       return;
     }
-    setCanvasContextMenu({ x: e.evt.clientX, y: e.evt.clientY });
+    const rect = containerRef.current?.getBoundingClientRect();
+    const localX = rect ? e.evt.clientX - rect.left : e.evt.clientX;
+    const localY = rect ? e.evt.clientY - rect.top : e.evt.clientY;
+    setCanvasContextMenu({ x: localX, y: localY });
   }, [navStack.length]);
   const handleStageTouchStart = (0, import_react14.useCallback)((e) => handleStageMouseDown(e), [handleStageMouseDown]);
   const handleStageTouchMove = (0, import_react14.useCallback)((e) => handleStageMouseMove(e), [handleStageMouseMove]);
@@ -2876,7 +2879,7 @@ function VisualliCanvas(props) {
             role: "menu",
             "aria-label": "Canvas options",
             style: {
-              position: "fixed",
+              position: "absolute",
               zIndex: 60,
               pointerEvents: "auto",
               left: `${Math.min(canvasContextMenu.x, Math.max(8, (canvasSizeRef.current.width || 800) - 152))}px`,
@@ -2925,7 +2928,7 @@ function VisualliCanvas(props) {
             {
               "data-node-tooltip": "true",
               style: {
-                position: "fixed",
+                position: "absolute",
                 zIndex: 50,
                 left: safeLeft,
                 top: safeTop,