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