feat(joint-react): update dependencies, refactor components, and enhance performance

- Updated dependencies in yarn.lock, including Babel and added unplugin.
- Refactored GraphProvider and Paper components for improved performance and clarity.
- Removed unused files and hooks to streamline the codebase.
- Enhanced the Storybook setup with a new script for loading react-scan.
- Improved element rendering logic and optimized hooks for better state management.
- Added tests for new functionalities and ensured existing tests are up to date.

Author: samuelgja

packages/joint-react-eslint/eslint.config.mjs

@@ -170,6 +170,7 @@ const config = [
         "error",
         {
           replacements: {
+            dev: false,
             doc: false,
             Props: false,
             props: false,

packages/joint-react/.storybook/preview-head.html

@@ -1,3 +1,58 @@
 <!-- Loads a font from a CDN -->
+<!-- react-scan: Load with delay to avoid freezing Storybook -->
+<script>
+    // Load react-scan UI overlay after Storybook initializes
+    (function () {
+        if (typeof window === 'undefined') return;
+
+        // Wait for DOM and React to be ready
+        function loadReactScan() {
+            if (window.__REACT_SCAN_LOADED) return;
+
+            const script = document.createElement('script');
+            script.src = 'https://unpkg.com/react-scan@latest/dist/auto.global.js';
+            script.async = true;
+            script.onload = function () {
+                window.__REACT_SCAN_LOADED = true;
+
+
+                // Wait a bit for react-scan to initialize, then configure it for iframe
+                setTimeout(function () {
+                    // Access react-scan global API
+                    const reactScan = window.reactScan;
+
+                    if (reactScan && typeof reactScan === 'function') {
+                        // Configure react-scan to work in iframe (Storybook uses iframes)
+                        try {
+                            reactScan({
+                                enabled: false, // Disabled by default - user can enable via toolbar
+                                allowInIframe: true,
+                                showToolbar: true, // Show toolbar so user can toggle it on/off
+                            });
+
+                        } catch (error) {
+                            console.error('❌ Error configuring react-scan:', error);
+                        }
+                    } else {
+                        console.warn('⚠️ react-scan function not found');
+                    }
+                }, 500);
+            };
+            script.onerror = function () {
+                console.error('❌ Failed to load react-scan');
+            };
+            document.head.appendChild(script);
+        }
+
+        // Try loading after a delay
+        if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', function () {
+                setTimeout(loadReactScan, 3000);
+            });
+        } else {
+            setTimeout(loadReactScan, 3000);
+        }
+    })();
+</script>
 <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>
 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0-beta3/css/all.min.css">

packages/joint-react/.storybook/preview.ts

@@ -1,4 +1,3 @@
-import './wdyr';
 import type { Preview } from '@storybook/react';
 import { withPerformance } from 'storybook-addon-performance';
 import { theme } from './theme';

packages/joint-react/.storybook/wdyr.ts

@@ -160,6 +160,8 @@ Subscribe to pointer events on elements/links.
 ### 4) Controlled updates (React state drives the graph)
 Pass `elements/links` + `onElementsChange/onLinksChange` to keep React in charge.
 
+**React-controlled mode** gives you full control over graph state, enabling features like undo/redo, persistence, and integration with other React state management.
+
 ```tsx
 import React, { useState } from 'react'
 import { GraphProvider } from '@joint/react'
@@ -187,7 +189,78 @@ export function Controlled() {
 }
 ```
 
-### 5) Imperative access (ref) for one‑off actions
+### 5) External store integration (Redux, Zustand, etc.)
+Use `externalStore` prop to integrate with external state management libraries.
+
+```tsx
+import { GraphProvider } from '@joint/react'
+import { createStore } from 'zustand'
+
+// Create a store compatible with ExternalStoreLike interface
+const useGraphStore = createStore((set) => ({
+  elements: [],
+  links: [],
+  setState: (updater) => set(updater),
+  getSnapshot: () => useGraphStore.getState(),
+  subscribe: (listener) => {
+    const unsubscribe = useGraphStore.subscribe(listener)
+    return unsubscribe
+  }
+}))
+
+export function ExternalStoreExample() {
+  const store = useGraphStore()
+  
+  return (
+    <GraphProvider externalStore={store}>
+      <Paper height={320} />
+    </GraphProvider>
+  )
+}
+```
+
+### 6) Programmatic cell manipulation
+Use the `useCellActions` hook to programmatically add, update, and remove cells.
+
+```tsx
+import { useCellActions } from '@joint/react'
+
+function MyComponent() {
+  const { set, remove } = useCellActions()
+
+  const addNode = () => {
+    set({
+      id: 'new-node',
+      x: 100,
+      y: 100,
+      width: 120,
+      height: 60,
+      label: 'New Node'
+    })
+  }
+
+  const updateNode = () => {
+    set('new-node', (prev) => ({
+      ...prev,
+      label: 'Updated'
+    }))
+  }
+
+  const deleteNode = () => {
+    remove('new-node')
+  }
+
+  return (
+    <div>
+      <button onClick={addNode}>Add</button>
+      <button onClick={updateNode}>Update</button>
+      <button onClick={deleteNode}>Delete</button>
+    </div>
+  )
+}
+```
+
+### 7) Imperative access (ref) for one‑off actions
 Useful for `fitToContent`, scaling, exporting.
 
 ```tsx
@@ -221,24 +294,36 @@ export function FitOnMount() {
 - **Prefer declarative first**: Reach for hooks/props; use imperative APIs (refs/graph methods) for targeted operations only.
 - **Test in Safari early** when using `<foreignObject>`; fall back to `useHTMLOverlay` if needed.
 - **Accessing component instances via refs**: Any component that accepts a `ref` (such as `Paper` or `GraphProvider`) exposes its instance/context via the ref. For `Paper`, the instance (including the underlying JointJS Paper) can be accessed via the `paperCtx` property on the ref object.
+- **Choose the right mode**: Use uncontrolled mode for simple cases, React-controlled for full state control, and external-store for integration with Redux/Zustand.
+- **Use selectors efficiently**: When using `useElements` or `useLinks`, provide custom selectors and equality functions to minimize re-renders.
+- **Batch updates**: The library automatically batches updates, but be mindful of rapid state changes in controlled mode.
 
 ---
 
 ## ⚙️ API Surface (at a glance)
 
 - **Components**
-  - `GraphProvider` — provides the shared graph
-  - `Paper` — renders the graph (Paper)
+  - `GraphProvider` — provides the shared graph context
+  - `Paper` — renders the graph (Paper view)
 
 - **Hooks**
-  - `useElements()` / `useLinks()` — subscribe to data
-  - `useGraph()` — low-level graph access
-  - `usePaper()` — access the underlying Paper (from within a view)
+  - `useElements()` / `useLinks()` — subscribe to elements/links with optional selectors
+  - `useGraph()` — access the underlying JointJS graph instance
+  - `usePaper()` — access the underlying Paper instance (from within a Paper view)
+  - `useCellActions()` — programmatically add, update, and remove cells
+
+- **Controlled mode props** (React-controlled)
+  - `elements`, `links` — current state
+  - `onElementsChange`, `onLinksChange` — state update callbacks
+
+- **External store mode**
+  - `externalStore` — external state management store (Redux, Zustand, etc.)
 
-- **Controlled mode props**
-  - `elements`, `links`, `onElementsChange`, `onLinksChange`
+- **Uncontrolled mode** (default)
+  - `initialElements`, `initialLinks` — initial values only
+  - Graph manages its own state internally
 
-> Tip: You can pass an existing JointJS `dia.Graph` into `GraphProvider` if you need to integrate with external data lifecycles.
+> **Tip:** You can pass an existing JointJS `dia.Graph` into `GraphProvider` if you need to integrate with external data lifecycles or share a graph across multiple providers.
 
 ---
 

packages/joint-react/README.md

@@ -1,4 +1,3 @@
-/** @type {import('ts-jest').JestConfigWithTsJest} **/
 export default {
   testEnvironment: 'jsdom',
   testPathIgnorePatterns: ['/node_modules/', '/dist/'],

packages/joint-react/jest.config.js

@@ -73,23 +73,27 @@
     "@types/react": "19.1.12",
     "@types/react-dom": "19.1.9",
     "@types/react-test-renderer": "19.1.0",
+    "@types/scheduler": "^0",
     "@types/use-sync-external-store": "1.5.0",
     "@vitejs/plugin-react": "^5.0.2",
-    "@welldone-software/why-did-you-render": "10.0.1",
     "canvas": "^3.1.0",
     "eslint": "9.33.0",
     "glob": "^11.0.1",
     "jest": "30.1.2",
     "jest-environment-jsdom": "30.1.2",
+    "jotai": "^2.15.2",
     "knip": "5.63.0",
+    "peerjs": "^1.5.5",
     "prettier": "3.3.3",
     "prettier-plugin-tailwindcss": "^0.6.5",
     "react": "^19.1.1",
     "react-docgen-typescript-plugin": "^1.0.8",
     "react-dom": "^19.1.1",
     "react-redux": "^9.2.0",
+    "react-scan": "^0.4.3",
     "react-test-renderer": "^19.1.1",
     "redux": "^5.0.1",
+    "redux-undo": "1.1.0",
     "storybook": "^8.6.14",
     "storybook-addon-performance": "0.17.3",
     "storybook-multilevel-sort": "2.1.0",
@@ -104,10 +108,12 @@
     "vite-plugin-md": "0.22.5",
     "vite-plugin-node-polyfills": "^0.24.0",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^3.0.4"
+    "vitest": "^3.0.4",
+    "zustand": "^5.0.9"
   },
   "dependencies": {
     "@joint/core": "workspace:*",
+    "scheduler": "^0.27.0",
     "use-sync-external-store": "^1.4.0"
   },
   "peerDependencies": {

packages/joint-react/package.json

@@ -121,11 +121,7 @@ function Component() {
       setIsReady(true);
     }, 1000);
   }, []);
-  return (
-    isReady && (
-      <Paper interactive={false} className={PAPER_CLASSNAME} renderElement={RenderHTMLElement} />
-    )
-  );
+  return isReady && <Paper className={PAPER_CLASSNAME} renderElement={RenderHTMLElement} />;
 }
 
 export const ConditionalRender: Story = {