+
+The main component that allows you to draw nodes and edges on the canvas. In *JointJS* terminology, you draw `cells` (`elements` and `links`) on `paper`. The component requires the `` to be its ancestor.
+
+##### Props
+
+| Property | Type | Description |
+|:-----------|:---------------|:-------------|
+| *options?* | `dia.Paper.Options` | The options of the `paper`. It's `async` by default. |
+| *renderElement?* | `(dia.Element) => React.JSX.Element \| null` | A callback to render React components inside the paper element views. The components are rendered using the `React.createPortal()`. |
+| *onReady?* | `(dia.Paper) => void` | A callback that is triggered after the `paper` is mounted and ready (cells may not be rendered). |
+| *onEvent?* | `(dia.Paper, eventName, ...eventArgs) => void` | A callback that allows you to listen to the [dia.Paper events](https://resources.jointjs.com/docs/jointjs/v3.7/joint.html#dia.Paper.events). |
+| *dataAttributes?* | `string[]` | A list of model attributes that, if changed, will cause the `renderElement` function to be triggered. The default is `["data"]`. |
+| *portal?* | `Element \| string \| (dia.ElementView) => string \| Element` | An *HTMLElement* or *SVGElement* (or a string [selector](https://resources.jointjs.com/docs/jointjs/v3.7/joint.html#dia.Cell.markup)) that serves as [portal](https://react.dev/reference/react-dom/createPortal) for rendering element's content. By default, the `portal` is selector `"portal"`. |
+
+##### Rendering React component inside an Element view
+
+By default, the content of the element view is rendered using *JointJS*. However, the content (_SVG_ or _HTML_) can also be rendered using React.
+
+ ```jsx
+import { dia, shapes } from 'jointjs';
+import { GraphProvider, Paper } from '@joint/react';
+
+// Assumes that the `portal` node is a foreign object descendant.
+const renderHTMLElement = (element) => {
+ const { label, value } = element.get('data');
+ return (
+
+
{label}
+ element.prop('data/value', e.target.value)}
+ />
+
+ );
+};
+
+export default function Diagram() {
+ const graph = new dia.Graph({}, { cellNamespace: shapes });
+ const paperProps = { /* ... */ };
+ return (
+
+
+
+ )
+}
+ ```
+
+Currently, the following **drawbacks** are known with this approach:
+
+- content rendered with _React_ cannot be the source/target of any link (it's always a good idea to also render the SVG \ under the `portal` node).
+- `` currently replaces the default `dia.Paper.prototype.options.elementView` with a custom `ElementView` that triggers the `portal:ready` event (`(elementView: dia.ElementView, portalEl: SVGElement | HTMLElement) => void`) when the `portal` node is rendered (`onRender()` method). If you want to use custom views and you want to use `renderElement` with them, make sure you trigger the `portal:ready` event manually.
+
+##### Paper provides context implicitly.
+
+The `` context provides the `paper` context to its descendants implicitly. If you need to use the `paper` context outside of the ``, use the ``.
+
+ ```jsx
+
+
+ {/* component is using JointJS `paper` */}
+
+
+ ```
+#### \
+
+The `` component is a [context provider](https://react.dev/learn/passing-data-deeply-with-context) that makes it possible to access the JointJS [paper](https://resources.jointjs.com/tutorial/graph-and-paper) outside of the `` component. Unlike the `GraphProvider`, the `PaperProvider` is not mandatory.
+
+```jsx
+import { GraphProvider, PaperProvider, Paper } from '@joint/react';
+
+export default function Diagram() {
+ return (
+
+
+
+
+
+
+
+ )
+}
+```
+
+#### \
+
+The `` component is a [context provider](https://react.dev/learn/passing-data-deeply-with-context) that provides JointJS [graph](https://resources.jointjs.com/tutorial/graph-and-paper) to `` components. You need use the `` in order to render the `` component.
+
+Here's an example of a `GraphProvider` providing a `graph` to two `papers`.
+```jsx
+import { dia, shapes } from 'jointjs';
+import { GraphProvider, Paper } from '@joint/react';
+
+export default function Diagram() {
+ const graph = new dia.Graph({}, { cellNamespace: shapes });
+ const paperProps = { /* ... */ };
+ const minimapProps = { /* ... */ };
+ return (
+
+
+
+
+ )
+}
+```
+
+##### Props
+
+| Property | Type | Description |
+|:-----------|:---------------|:-------------|
+| *graph* | `dia.Graph` | A `graph` instance to be provided to the descendants |
+
+### Hooks
+
+The package exposed several custom hooks.
+
+#### usePaper
+
+The `usePaper` is a hook that let you use the JointJS `paper` from your component.
+
+```jsx
+import { usePaper } from '@joint/react';
+
+export default function MyZoomInButton() {
+ const paper = usePaper();
+ const zoomIn = () => {
+ if (!paper) return;
+ const { sx, sy } = paper.scale();
+ paper.scale(sx * 2, sy * 2);
+ }
+ return
+}
+```
+
+#### useGraph
+
+The `useGraph` is a hook that let you use the JointJS `graph` from your component.
+
+```jsx
+import { useGraph } from '@joint/react';
+
+export default function MyDeleteAllButton() {
+ const graph = useGraph();
+ const deleteAll = () => {
+ if (graph && confirm("Are you sure you want to delete all content?")) {
+ graph.clear();
+ }
+ }
+ return
+}
+```
+
+## What's next
+
+The possible tasks ahead of us.
+
+### JointJS+
+
+Define React Components for JointJS+.
+
+```jsx
+// NOTE: This is fictional code
+// It is just an example of possible API.
+import { dia, mvc } from '@joint/core';
+import { CommandManager } from '@joint/command-manager';
+import { Paper } from '@joint/react';
+import DiagramProvider from '@joint/diagram-provider';
+import Toolbar from '@joint/toolbar-react';
+import Stencil from '@joint/stencil-react';
+import Scroller from '@joint/scroller-react';
+import Inspector from '@joint/inspector-react';
+import Selection from '@joint/selection-react';
+import Snaplines from '@joint/snaplines-react';
+import Grid from 'some-ui-lib';
+
+export default function Diagram() {
+ const graph = new dia.Graph();
+ const cmd = new CommandManager({ graph });
+ const selection = new mvc.Collection();
+ return (
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ )
+}
+```
+
+### Higher-level Components
+
+Define user-friendly higher-level components.
+
+```jsx
+// Paper, Scroller, Toolbar, CommandManager as a single component
+
+```
+
+```jsx
+// Domain-specific diagram components
+
+```
+
+## License
+
+[Mozilla Public License 2.0](https://www.mozilla.org/en-US/MPL/2.0/)
+
+Copyright © 2013-2023 client IO
diff --git a/packages/joint-react/package.json b/packages/joint-react/package.json
new file mode 100644
index 000000000..a959693ca
--- /dev/null
+++ b/packages/joint-react/package.json
@@ -0,0 +1,55 @@
+{
+ "name": "@joint/react",
+ "title": "JointJS React",
+ "version": "0.1.1",
+ "description": "React module for JointJS",
+ "main": "build/index.js",
+ "homepage": "https://jointjs.com",
+ "author": {
+ "name": "client IO",
+ "url": "https://client.io"
+ },
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/clientIO/joint.git",
+ "directory": "packages/joint-decorators"
+ },
+ "bugs": {
+ "url": "https://github.com/clientIO/joint/issues"
+ },
+ "license": "MPL-2.0",
+ "publishConfig": {
+ "access": "public"
+ },
+ "files": [
+ "build/",
+ "src/",
+ "README.md"
+ ],
+ "dependencies": {
+ "@joint/core": "workspace:^"
+ },
+ "peerDependencies": {
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0"
+ },
+ "scripts": {
+ "build": "babel src/*.jsx -d build",
+ "dist": "yarn build",
+ "prepublish": "yarn build"
+ },
+ "volta": {
+ "node": "16.18.1",
+ "npm": "8.19.2",
+ "yarn": "3.4.1"
+ },
+ "keywords": [
+ "jointjs",
+ "react"
+ ],
+ "devDependencies": {
+ "@babel/cli": "^7.23.0",
+ "@babel/core": "^7.23.3",
+ "@babel/preset-react": "^7.23.3"
+ }
+}
diff --git a/packages/joint-react/src/GraphContext.jsx b/packages/joint-react/src/GraphContext.jsx
new file mode 100644
index 000000000..ceb86f1d6
--- /dev/null
+++ b/packages/joint-react/src/GraphContext.jsx
@@ -0,0 +1,13 @@
+import React, { useState, createContext, useContext } from 'react';
+
+export const GraphContext = createContext(null);
+
+export function GraphProvider({ children, graph }) {
+ const [graphContext, setGraphContext] = useState(graph);
+ return ({children});
+}
+
+export function useGraph() {
+ const [graph] = useContext(GraphContext);
+ return graph;
+}
diff --git a/packages/joint-react/src/Paper.jsx b/packages/joint-react/src/Paper.jsx
new file mode 100644
index 000000000..872174491
--- /dev/null
+++ b/packages/joint-react/src/Paper.jsx
@@ -0,0 +1,149 @@
+import { dia, mvc } from '@joint/core';
+import React, { useRef, useEffect, useState, useContext } from 'react';
+import { createPortal } from 'react-dom';
+import { GraphContext } from './GraphContext';
+import { PaperContext } from './PaperContext';
+
+export const PORTAL_READY_EVENT = 'portal:ready';
+
+export function Paper({
+ children,
+ options,
+ renderElement,
+ onReady,
+ onEvent,
+ style,
+ dataAttributes = ['data'],
+ portalSelector = 'portal',
+}) {
+
+ const paperWrapperElRef = useRef(null);
+ const paperRef = useRef(null);
+
+ const [graph] = useContext(GraphContext);
+ const [, setPaperContext] = useContext(PaperContext) ?? [];
+
+ const [elements, setElements] = useState({});
+ const setElement = (model, containerEl) => {
+ setElements((prevState) => {
+ const id = model.id;
+ return {
+ ...prevState,
+ [id]: {
+ id,
+ data: model.get('data'),
+ containerEl: containerEl ?? prevState[id]?.containerEl,
+ },
+ };
+ });
+ };
+
+ const resizePaperWrapper = (paper) => {
+ paperWrapperElRef.current.style.width = paper.el.style.width;
+ paperWrapperElRef.current.style.height = paper.el.style.height;
+ };
+
+ const createElementPortal = ({ id, containerEl }) => {
+ if (!containerEl) return null;
+ const element = graph.getCell(id);
+ if (!element) return null;
+ return createPortal(renderElement(element), containerEl);
+ };
+
+ const ElementView = dia.ElementView.extend({
+ onRender() {
+ let portalEl =
+ typeof portalSelector === 'function'
+ ? portalSelector(this)
+ : portalSelector;
+ if (typeof portalEl === 'string') {
+ portalEl = this.findNode(portalEl);
+ }
+ portalEl && this.notify(PORTAL_READY_EVENT, portalEl);
+ },
+ });
+
+ let elementPortals = null;
+ if (renderElement) {
+ elementPortals = Object.values(elements).map(createElementPortal);
+ }
+
+ const bindEvents = (paper) => {
+
+ // An object to keep track of the listeners. It's not exposed, so the users
+ // can't undesirably remove the listeners.
+ const controller = new mvc.Listener();
+
+ // Update the elements state when the graph data changes
+ const attributeChangeEvents = dataAttributes
+ .map((attribute) => `change:${attribute}`)
+ .join(' ');
+
+ controller.listenTo(graph, attributeChangeEvents, (cell) =>
+ setElement(cell)
+ );
+ // Update the portal node reference when the element view is rendered
+ controller.listenTo(
+ paper,
+ PORTAL_READY_EVENT,
+ (elementView, portalEl) => setElement(elementView.model, portalEl)
+ );
+
+ controller.listenTo(paper, 'resize', () => resizeWrapper(paper));
+
+ if (onEvent) {
+ controller.listenTo(paper, 'all', (...args) =>
+ onEvent(paper, ...args)
+ );
+ }
+
+ return () => controller.stopListening();
+ }
+
+ useEffect(() => {
+ const paper = new dia.Paper({
+ width: '100%',
+ height: '100%',
+ async: true,
+ sorting: dia.Paper.sorting.APPROX,
+ preventDefaultBlankAction: false,
+ // TODO: It is possible to override it. We need to instruct
+ // the users to trigger the PORTAL_READY_EVENT event manually
+ // or find a better way to do it (e.g. trigger the event in JointJS)
+ elementView: ElementView,
+ ...options,
+ frozen: true,
+ model: graph,
+ });
+
+ paper.el.style.boxSizing = 'border-box';
+ paperWrapperElRef.current.appendChild(paper.el);
+ resizePaperWrapper(paper);
+ paper.unfreeze();
+
+ paperRef.current = paper;
+ setPaperContext && setPaperContext(paper);
+
+ const unbindEvents = bindEvents(paper);
+ if (onReady) {
+ onReady(paper);
+ }
+
+ return () => {
+ paper.remove();
+ unbindEvents();
+ setPaperContext && setPaperContext(null);
+ };
+
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [graph, setPaperContext]); // options, onReady, onEvent, style
+
+ return (
+
+
+ {elementPortals}
+ {children}
+
+