@canvus/react 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +135 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
# @canvus/react
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@canvus/react)
|
|
4
|
+
[](../../LICENSE)
|
|
5
|
+
|
|
6
|
+
> ⚠️ **Beta Release (v0.1.0)**: `@canvus/react` is currently in active development (public beta). APIs and configuration options may evolve before the v1.0.0 stable release.
|
|
7
|
+
|
|
8
|
+
React bindings for the [Canvus SDK](https://github.com/balfaro01/canvus) — a headless, framework-agnostic vanilla TypeScript engine for building visual layout editing workspaces (page builders, A/B testing editors, visual IDEs).
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## 🚀 Key Features
|
|
13
|
+
|
|
14
|
+
* **Native React Node Mounting**: Render live, stateful React components inside the isolated canvas Shadow DOM with a simple `addReactNode` API call.
|
|
15
|
+
* **Declarative Prop Updates**: Seamlessly update component props and trigger in-place re-renders using `updateReactNode`, avoiding remounts or visual flickers.
|
|
16
|
+
* **Structured Commits**: Listen to `onReactNodeCommit` to receive structured component states (updated props, dimensions, and canvas coordinates) instead of raw HTML markup.
|
|
17
|
+
* **Coexistence Mode**: Mix and match live React nodes and vanilla HTML nodes on the same visual canvas.
|
|
18
|
+
* **Context-Driven Hooks**: Control the workspace, manage selections, trigger history operations (Undo/Redo), and add/remove components from any child component via the `useCanvus()` hook.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 🛠️ Installation
|
|
23
|
+
|
|
24
|
+
Install the React bindings alongside the core SDK:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
npm install @canvus/react @canvus/core
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## 💻 Quick Start
|
|
33
|
+
|
|
34
|
+
### 1. Create the Workspace
|
|
35
|
+
|
|
36
|
+
Wrap your editor interface with the `<Canvus />` component. This sets up the Shadow DOM, event bindings, and initializes the workspace core engine:
|
|
37
|
+
|
|
38
|
+
```tsx
|
|
39
|
+
import { Canvus } from "@canvus/react";
|
|
40
|
+
|
|
41
|
+
function Editor() {
|
|
42
|
+
return (
|
|
43
|
+
<Canvus
|
|
44
|
+
config={{ snapThreshold: 8 }}
|
|
45
|
+
style={{ width: "100vw", height: "100vh" }}
|
|
46
|
+
onReactNodeCommit={(id, snapshot) => {
|
|
47
|
+
console.log(`Node "${id}" updated:`, snapshot.props, snapshot.rect);
|
|
48
|
+
// Save the updated layout and props to your database
|
|
49
|
+
}}
|
|
50
|
+
>
|
|
51
|
+
<Toolbar />
|
|
52
|
+
</Canvus>
|
|
53
|
+
);
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### 2. Define Your Canvas Components
|
|
58
|
+
|
|
59
|
+
Create standard React components to render on the canvas. The wrapper frame handles positioning, margins, and resizing:
|
|
60
|
+
|
|
61
|
+
```tsx
|
|
62
|
+
interface CardProps {
|
|
63
|
+
title: string;
|
|
64
|
+
value: string;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
function DashboardCard({ title, value }: CardProps) {
|
|
68
|
+
return (
|
|
69
|
+
<div style={{
|
|
70
|
+
padding: 24,
|
|
71
|
+
background: "#1e293b",
|
|
72
|
+
color: "#f8fafc",
|
|
73
|
+
borderRadius: 8,
|
|
74
|
+
height: "100%"
|
|
75
|
+
}}>
|
|
76
|
+
<h3>{title}</h3>
|
|
77
|
+
<p style={{ fontSize: 24, fontWeight: 700 }}>{value}</p>
|
|
78
|
+
</div>
|
|
79
|
+
);
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### 3. Add and Manage Nodes
|
|
84
|
+
|
|
85
|
+
Use the `useCanvus` hook inside any component nested within `<Canvus />` to interact with the workspace:
|
|
86
|
+
|
|
87
|
+
```tsx
|
|
88
|
+
import { useCanvus } from "@canvus/react";
|
|
89
|
+
|
|
90
|
+
function Toolbar() {
|
|
91
|
+
const { addReactNode, updateReactNode, removeReactNode } = useCanvus();
|
|
92
|
+
|
|
93
|
+
const handleAdd = () => {
|
|
94
|
+
addReactNode({
|
|
95
|
+
id: "revenue-card",
|
|
96
|
+
component: DashboardCard,
|
|
97
|
+
props: { title: "Revenue", value: "$42,000" },
|
|
98
|
+
currentRect: { x: 100, y: 100, width: 300, height: 200 }
|
|
99
|
+
});
|
|
100
|
+
};
|
|
101
|
+
|
|
102
|
+
const handleUpdate = () => {
|
|
103
|
+
updateReactNode("revenue-card", { value: "$58,000" });
|
|
104
|
+
};
|
|
105
|
+
|
|
106
|
+
return (
|
|
107
|
+
<div style={{ position: "absolute", top: 16, left: 16, zIndex: 100 }}>
|
|
108
|
+
<button onClick={handleAdd}>Add Card</button>
|
|
109
|
+
<button onClick={handleUpdate}>Update Value</button>
|
|
110
|
+
<button onClick={() => removeReactNode("revenue-card")}>Remove</button>
|
|
111
|
+
</div>
|
|
112
|
+
);
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## 📖 API Reference
|
|
119
|
+
|
|
120
|
+
### `<Canvus />`
|
|
121
|
+
Mounts a relative-positioned container div and initializes the Canvus workspace.
|
|
122
|
+
|
|
123
|
+
#### Props
|
|
124
|
+
* `config?: WorkspaceConfig`: Configuration settings for snapping, selection overlays, spacing adjusters, etc.
|
|
125
|
+
* `style?: CSSProperties`: Style object for the wrapper div.
|
|
126
|
+
* `className?: string`: Custom CSS class.
|
|
127
|
+
* `onReactNodeCommit?: (id: string, snapshot: ReactNodeSnapshot) => void`: Triggered when a React-managed node is resized, dragged, or modified.
|
|
128
|
+
* `onSelectionChange?: (selectedIds: ReadonlySet<string>) => void`: Triggered when the selected nodes change.
|
|
129
|
+
* `onViewportChange?: (viewport: ViewportMatrix) => void`: Triggered when panning or zooming occurs.
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## 📄 License
|
|
134
|
+
|
|
135
|
+
MIT.
|