@flowscape-ui/core-sdk 1.0.0 → 1.0.2

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.
Files changed (6) hide show
  1. package/README.md +130 -70
  2. package/dist/index.cjs +1 -7347
  3. package/dist/index.js +1 -7314
  4. package/package.json +1 -1
  5. package/dist/index.cjs.map +0 -1
  6. package/dist/index.js.map +0 -1
package/README.md CHANGED
@@ -1,17 +1,11 @@
1
- <div align="center">
2
-
3
1
  # 🎨 @flowscape-ui/core-sdk
4
2
 
5
- **Powerful 2D canvas engine built on Konva**
3
+ **Powerful 2D canvas engine built on Konva.js**
6
4
 
7
5
  [![npm version](https://img.shields.io/npm/v/@flowscape-ui/core-sdk.svg)](https://www.npmjs.com/package/@flowscape-ui/core-sdk)
8
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
9
- [![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue)](https://www.typescriptlang.org/)
10
- [![Bundle Size](https://img.shields.io/bundlephobia/minzip/@flowscape-ui/core-sdk)](https://bundlephobia.com/package/@flowscape-ui/core-sdk)
6
+ [![Buy Me a Coffee](https://img.shields.io/badge/Donate-Buy%20Me%20a%20Coffee-FFDD00?logo=buymeacoffee&logoColor=000)](https://buymeacoffee.com/flowscape)
11
7
 
12
- [Documentation](https://github.com/Flowscape-UI/core-sdk#readme) • [Examples](https://github.com/Flowscape-UI/core-sdk/tree/main/playground) • [Changelog](./CHANGELOG.md)
13
-
14
- </div>
8
+ [📖 Documentation](https://flowscape-ui.github.io/core-sdk-doc/) • [💡 Examples](https://flowscape-ui.github.io/core-sdk-doc/docs/guides/interactive-demo) • [📝 Changelog](#)
15
9
 
16
10
  ---
17
11
 
@@ -26,6 +20,8 @@
26
20
  - 📦 **TypeScript-first** — full typing out of the box
27
21
  - 🚀 **Optimized** — tree-shaking, ESM + CJS, source maps
28
22
 
23
+ ---
24
+
29
25
  ## 📦 Installation
30
26
 
31
27
  ```bash
@@ -36,14 +32,21 @@ yarn add @flowscape-ui/core-sdk
36
32
  bun add @flowscape-ui/core-sdk
37
33
  ```
38
34
 
35
+ ---
36
+
39
37
  ## 🚀 Quick Start
40
38
 
41
39
  ```typescript
42
- import { CoreEngine, GridPlugin, SelectionPlugin, NodeHotkeysPlugin } from '@flowscape-ui/core-sdk';
40
+ import {
41
+ CoreEngine,
42
+ GridPlugin,
43
+ SelectionPlugin,
44
+ NodeHotkeysPlugin,
45
+ } from "@flowscape-ui/core-sdk";
43
46
 
44
47
  // Create engine with plugins
45
- const core = new CoreEngine({
46
- container: document.getElementById('canvas-container')!,
48
+ const engine = new CoreEngine({
49
+ container: document.getElementById("canvas-container")!,
47
50
  width: 1200,
48
51
  height: 800,
49
52
  plugins: [
@@ -54,25 +57,25 @@ const core = new CoreEngine({
54
57
  });
55
58
 
56
59
  // Add shapes
57
- const rect = core.nodes.addShape({
60
+ const rect = engine.nodes.addShape({
58
61
  x: 100,
59
62
  y: 100,
60
63
  width: 200,
61
64
  height: 150,
62
- fill: '#3b82f6',
65
+ fill: "#3b82f6",
63
66
  cornerRadius: 8,
64
67
  });
65
68
 
66
- const text = core.nodes.addText({
69
+ const text = engine.nodes.addText({
67
70
  x: 120,
68
71
  y: 140,
69
- text: 'Hello Flowscape!',
72
+ text: "Hello Flowscape!",
70
73
  fontSize: 24,
71
- fill: 'white',
74
+ fill: "white",
72
75
  });
73
76
 
74
77
  // Grouping
75
- const group = core.nodes.addGroup({
78
+ const group = engine.nodes.addGroup({
76
79
  x: 400,
77
80
  y: 200,
78
81
  });
@@ -80,6 +83,8 @@ rect.getNode().moveTo(group.getNode());
80
83
  text.getNode().moveTo(group.getNode());
81
84
  ```
82
85
 
86
+ ---
87
+
83
88
  ## 🏗️ Architecture
84
89
 
85
90
  ### Core Components
@@ -104,7 +109,6 @@ text.getNode().moveTo(group.getNode());
104
109
  │ ┌──────────────────────────────┐ │
105
110
  │ │ Camera Manager │ │
106
111
  │ │ - Zoom (Ctrl+Wheel) │ │
107
- │ │ - Pan (Space+Drag) │ │
108
112
  │ └──────────────────────────────┘ │
109
113
  └─────────────────────────────────────┘
110
114
  ```
@@ -114,41 +118,90 @@ text.getNode().moveTo(group.getNode());
114
118
  Plugins extend engine functionality without modifying the core:
115
119
 
116
120
  ```typescript
117
- import { Plugin } from '@flowscape-ui/core-sdk';
121
+ import { Plugin, CoreEngine } from "@flowscape-ui/core-sdk";
118
122
 
119
123
  class CustomPlugin extends Plugin {
120
124
  protected onAttach(core: CoreEngine): void {
121
125
  // Initialize on attach
122
- core.eventBus.on('node:created', (node) => {
123
- console.log('Node created:', node);
126
+ core.eventBus.on("node:created", (node) => {
127
+ console.log("Node created:", node);
124
128
  });
125
129
  }
126
130
 
127
131
  protected onDetach(core: CoreEngine): void {
128
132
  // Cleanup on detach
129
- core.eventBus.off('node:created');
133
+ core.eventBus.off("node:created");
130
134
  }
131
135
  }
132
136
 
133
137
  // Usage
134
- const core = new CoreEngine({
138
+ const engine = new CoreEngine({
135
139
  container: element,
136
140
  plugins: [new CustomPlugin()],
137
141
  });
138
142
  ```
139
143
 
140
- ### Built-in Plugins
144
+ ---
145
+
146
+ ## 🧩 Built-in Plugins
147
+
148
+ | Plugin | Description |
149
+ | ------------------------ | ----------------------------------------------------- |
150
+ | **GridPlugin** | Adaptive grid with automatic scaling and snap-to-grid |
151
+ | **SelectionPlugin** | Selection, transformation, drag & drop, grouping |
152
+ | **AreaSelectionPlugin** | Area selection with frame (Shift+Drag) |
153
+ | **NodeHotkeysPlugin** | Copy/paste/cut nodes, delete, z-index management |
154
+ | **CameraHotkeysPlugin** | Zoom and pan controls with keyboard |
155
+ | **RulerPlugin** | Rulers with measurement units |
156
+ | **RulerGuidesPlugin** | Draggable guide lines from rulers |
157
+ | **RulerHighlightPlugin** | Ruler highlighting on hover |
158
+ | **RulerManagerPlugin** | Toggle rulers and manage guides |
159
+ | **LogoPlugin** | Watermark/logo on canvas |
160
+
161
+ ---
162
+
163
+ ## ⌨️ Keyboard Shortcuts
141
164
 
142
- | Plugin | Description |
143
- | --------------------- | ---------------------------------------- |
144
- | `GridPlugin` | Adaptive grid with automatic scaling |
145
- | `SelectionPlugin` | Selection, transformation, drag & drop |
146
- | `NodeHotkeysPlugin` | Ctrl+C/V/X, Delete, Ctrl+[/] for z-index |
147
- | `CameraHotkeysPlugin` | Ctrl+wheel for zoom, arrows for pan |
148
- | `RulerPlugin` | Rulers with measurement units |
149
- | `RulerGuidesPlugin` | Guide lines (drag from rulers) |
150
- | `AreaSelectionPlugin` | Area selection with frame (Shift+Drag) |
151
- | `LogoPlugin` | Watermark/logo on canvas |
165
+ ### Node Operations (NodeHotkeysPlugin)
166
+
167
+ | Shortcut | Action |
168
+ | ---------------------- | ------------------------ |
169
+ | `Ctrl+C` | Copy selected nodes |
170
+ | `Ctrl+X` | Cut selected nodes |
171
+ | `Ctrl+V` | Paste nodes |
172
+ | `Delete` / `Backspace` | Delete selected nodes |
173
+ | `Ctrl+]` | Move node up (z-index) |
174
+ | `Ctrl+[` | Move node down (z-index) |
175
+
176
+ ### Grouping (SelectionPlugin)
177
+
178
+ | Shortcut | Action |
179
+ | ----------------------- | --------------------------------- |
180
+ | `Ctrl+G` | Group selected nodes |
181
+ | `Ctrl+Shift+G` | Ungroup selected group |
182
+ | `Shift+Click` | Add/remove node to/from selection |
183
+ | `Shift` (during resize) | Lock aspect ratio |
184
+
185
+ ### Camera Controls (CameraHotkeysPlugin)
186
+
187
+ | Shortcut | Action |
188
+ | ------------------- | ----------- |
189
+ | `Ctrl+Wheel` | Zoom in/out |
190
+ | `+` / `=` | Zoom in |
191
+ | `-` | Zoom out |
192
+ | `Arrow Keys` | Pan camera |
193
+ | `Middle Mouse+Drag` | Pan camera |
194
+ | `Right Mouse+Drag` | Pan camera |
195
+
196
+ ### Ruler Controls (RulerManagerPlugin)
197
+
198
+ | Shortcut | Action |
199
+ | ---------------------- | ------------------------ |
200
+ | `Shift+R` | Toggle rulers visibility |
201
+ | `Delete` / `Backspace` | Delete active guide |
202
+ | Drag from ruler | Create guide line |
203
+
204
+ ---
152
205
 
153
206
  ## 📚 Usage Examples
154
207
 
@@ -156,42 +209,42 @@ const core = new CoreEngine({
156
209
 
157
210
  ```typescript
158
211
  // Rectangle with rounded corners
159
- const rect = core.nodes.addShape({
212
+ const rect = engine.nodes.addShape({
160
213
  x: 50,
161
214
  y: 50,
162
215
  width: 200,
163
216
  height: 100,
164
- fill: '#10b981',
217
+ fill: "#10b981",
165
218
  cornerRadius: 12,
166
219
  });
167
220
 
168
221
  // Circle
169
- const circle = core.nodes.addCircle({
222
+ const circle = engine.nodes.addCircle({
170
223
  x: 300,
171
224
  y: 100,
172
225
  radius: 50,
173
- fill: '#f59e0b',
174
- stroke: '#d97706',
226
+ fill: "#f59e0b",
227
+ stroke: "#d97706",
175
228
  strokeWidth: 3,
176
229
  });
177
230
 
178
231
  // Text
179
- const text = core.nodes.addText({
232
+ const text = engine.nodes.addText({
180
233
  x: 400,
181
234
  y: 50,
182
- text: 'Flowscape UI',
235
+ text: "Flowscape UI",
183
236
  fontSize: 32,
184
- fontFamily: 'Inter',
185
- fill: '#1f2937',
237
+ fontFamily: "Inter",
238
+ fill: "#1f2937",
186
239
  });
187
240
 
188
241
  // Image
189
- const image = core.nodes.addImage({
242
+ const image = engine.nodes.addImage({
190
243
  x: 100,
191
244
  y: 200,
192
245
  width: 200,
193
246
  height: 150,
194
- src: '/path/to/image.jpg',
247
+ src: "/path/to/image.jpg",
195
248
  });
196
249
  ```
197
250
 
@@ -199,33 +252,33 @@ const image = core.nodes.addImage({
199
252
 
200
253
  ```typescript
201
254
  // Subscribe to events
202
- core.eventBus.on('node:created', (node) => {
203
- console.log('Node created:', node);
255
+ engine.eventBus.on("node:created", (node) => {
256
+ console.log("Node created:", node);
204
257
  });
205
258
 
206
- core.eventBus.on('node:selected', (node) => {
207
- console.log('Node selected:', node);
259
+ engine.eventBus.on("node:selected", (node) => {
260
+ console.log("Node selected:", node);
208
261
  });
209
262
 
210
- core.eventBus.on('camera:zoom', ({ scale }) => {
211
- console.log('Zoom changed:', scale);
263
+ engine.eventBus.on("camera:zoom", ({ scale }) => {
264
+ console.log("Zoom changed:", scale);
212
265
  });
213
266
 
214
267
  // Unsubscribe
215
268
  const handler = (node) => console.log(node);
216
- core.eventBus.on('node:created', handler);
217
- core.eventBus.off('node:created', handler);
269
+ engine.eventBus.on("node:created", handler);
270
+ engine.eventBus.off("node:created", handler);
218
271
  ```
219
272
 
220
273
  ### Grouping and Management
221
274
 
222
275
  ```typescript
223
276
  // Create group
224
- const group = core.nodes.addGroup({ x: 0, y: 0 });
277
+ const group = engine.nodes.addGroup({ x: 0, y: 0 });
225
278
 
226
279
  // Add nodes to group
227
- const rect1 = core.nodes.addShape({ x: 10, y: 10, width: 50, height: 50 });
228
- const rect2 = core.nodes.addShape({ x: 70, y: 10, width: 50, height: 50 });
280
+ const rect1 = engine.nodes.addShape({ x: 10, y: 10, width: 50, height: 50 });
281
+ const rect2 = engine.nodes.addShape({ x: 70, y: 10, width: 50, height: 50 });
229
282
 
230
283
  rect1.getNode().moveTo(group.getNode());
231
284
  rect2.getNode().moveTo(group.getNode());
@@ -240,21 +293,23 @@ rect1.getNode().moveToTop(); // Move to top
240
293
 
241
294
  ```typescript
242
295
  // Programmatic zoom
243
- core.camera.zoomIn(); // Zoom in
244
- core.camera.zoomOut(); // Zoom out
245
- core.camera.setZoom(1.5); // Set specific scale
296
+ engine.camera.zoomIn(); // Zoom in
297
+ engine.camera.zoomOut(); // Zoom out
298
+ engine.camera.setZoom(1.5); // Set specific scale
246
299
 
247
300
  // Panning
248
- core.camera.pan(100, 50); // Pan by dx, dy
301
+ engine.camera.pan(100, 50); // Pan by dx, dy
249
302
 
250
303
  // Center on node
251
- const node = core.nodes.addShape({ x: 500, y: 500, width: 100, height: 100 });
252
- core.camera.centerOn(node);
304
+ const node = engine.nodes.addShape({ x: 500, y: 500, width: 100, height: 100 });
305
+ engine.camera.centerOn(node);
253
306
 
254
307
  // Reset camera
255
- core.camera.reset();
308
+ engine.camera.reset();
256
309
  ```
257
310
 
311
+ ---
312
+
258
313
  ## 🔧 Development
259
314
 
260
315
  ```bash
@@ -278,23 +333,28 @@ bun run lint:ts # TypeScript check
278
333
  bun run lint:fix # Auto-fix
279
334
  ```
280
335
 
336
+ ---
337
+
281
338
  ## 📖 Documentation
282
339
 
283
- Coming soon
340
+ Full documentation is available at [flowscape-ui.github.io/core-sdk-doc/](https://flowscape-ui.github.io/core-sdk-doc/)
284
341
 
285
- ### Branching Strategy
342
+ - [Getting Started](https://flowscape-ui.github.io/core-sdk-doc/docs/getting-started/installation)
343
+ - [Core Concepts](https://flowscape-ui.github.io/core-sdk-doc/docs/core-concepts/architecture)
344
+ - [Plugins](https://flowscape-ui.github.io/core-sdk-doc/docs/plugins/overview)
345
+ - [API Reference](https://flowscape-ui.github.io/core-sdk-doc/docs/api/reference)
346
+ - [Interactive Demo](https://flowscape-ui.github.io/core-sdk-doc/docs/guides/interactive-demo)
286
347
 
287
- - `dev` — active development
288
- - `main` — stable version, auto-publish to npm
348
+ ---
289
349
 
290
350
  ## 📄 License
291
351
 
292
- MIT © [Flowscape UI Team](https://github.com/Flowscape-UI)
352
+ MIT © Flowscape UI Team
293
353
 
294
354
  ---
295
355
 
296
356
  <div align="center">
297
357
 
298
- **[⭐ Star on GitHub](https://github.com/Flowscape-UI/core-sdk)** • **[🐛 Report Bug](https://github.com/Flowscape-UI/core-sdk/issues)** • **[💡 Request Feature](https://github.com/Flowscape-UI/core-sdk/issues/new)**
358
+ ⭐ [Star on GitHub](https://github.com/Flowscape-UI/core-sdk) • 🐛 [Report Bug](https://github.com/Flowscape-UI/core-sdk/issues) • 💡 [Request Feature](https://github.com/Flowscape-UI/core-sdk/issues)
299
359
 
300
360
  </div>