@flowscape-ui/core-sdk 1.0.2 → 1.0.4

package/README.md

@@ -1,24 +1,30 @@
+<div align="center">
+
 # 🎨 @flowscape-ui/core-sdk
 
-**Powerful 2D canvas engine built on Konva.js**
+**Powerful 2D canvas engine built on Konva**
 
 [![npm version](https://img.shields.io/npm/v/@flowscape-ui/core-sdk.svg)](https://www.npmjs.com/package/@flowscape-ui/core-sdk)
-[![Buy Me a Coffee](https://img.shields.io/badge/Donate-Buy%20Me%20a%20Coffee-FFDD00?logo=buymeacoffee&logoColor=000)](https://buymeacoffee.com/flowscape)
-
-[📖 Documentation](https://flowscape-ui.github.io/core-sdk-doc/) • [💡 Examples](https://flowscape-ui.github.io/core-sdk-doc/docs/guides/interactive-demo) • [📝 Changelog](#)
-
----
-
-## ✨ Features
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@flowscape-ui/core-sdk)](https://bundlephobia.com/package/@flowscape-ui/core-sdk)
+[![X (Twitter)](https://img.shields.io/badge/X-@FlowscapeUI-000000?logo=x&logoColor=white)](https://x.com/FlowscapeUI)
+
+[![Documentation](https://img.shields.io/badge/📚_Documentation-FF4785?style=for-the-badge&logo=storybook&logoColor=white)](https://flowscape-ui.github.io/core-sdk/)
+[![Interactive Demo](https://img.shields.io/badge/🎮_Interactive_Demo-FF4785?style=for-the-badge&logo=storybook&logoColor=white)](https://flowscape-ui.github.io/core-sdk/?path=/story/interactive-playground--interactive-playground)
+[![Changelog](https://img.shields.io/badge/📝_Changelog-FF4785?style=for-the-badge&logo=storybook&logoColor=white)](./CHANGELOG.md)
+
+<img 
+    src="./assets/readme/cover-image.png" 
+    alt="Flowscape Canvas Demo" 
+    width="900"
+  />
+<img 
+    src="./assets/readme/preview.gif" 
+    alt="Flowscape Canvas Demo" 
+    width="900"
+  />
 
-- 🎯 **Framework-agnostic** — works with React, Vue, Svelte, Angular or vanilla JS
-- 🧩 **Plugin system** — extensible architecture with ready-to-use plugins
-- 📐 **Complete toolset** — grid, rulers, guides, area selection
-- ⌨️ **Hotkeys** — Ctrl+C/V/X, Delete, Ctrl+G for grouping
-- 🎨 **Rich shapes** — rectangles, circles, text, images, arrows, stars
-- 🔄 **Transformations** — rotation, scaling, movement with aspect ratio lock
-- 📦 **TypeScript-first** — full typing out of the box
-- 🚀 **Optimized** — tree-shaking, ESM + CJS, source maps
+</div>
 
 ---
 
@@ -27,26 +33,35 @@
 ```bash
 npm install @flowscape-ui/core-sdk
 # or
+pnpm add @flowscape-ui/core-sdk
+# or
 yarn add @flowscape-ui/core-sdk
 # or
 bun add @flowscape-ui/core-sdk
 ```
 
----
+## ✨ Features
+
+- 🎯 **Framework-agnostic** - works with React, Vue, Svelte, Angular or vanilla JS
+- 🧩 **Plugin system** - extensible architecture with ready-to-use plugins
+- 📐 **Complete toolset** - grid, rulers, guides, area selection, alignment guides
+- ⌨️ **Hotkeys** - Ctrl+C/V/X, Delete, Ctrl+G for grouping, Ctrl+Z/Shift+Z for undo/redo
+- 🎨 **Rich shapes** - rectangles, circles, text, images, arrows, stars
+- 🔄 **Transformations** - rotation, scaling, movement with aspect ratio lock
+- ✏️ **Inline editing** - double-click text nodes to edit directly on canvas
+- 🕐 **History system** - full undo/redo support with Ctrl+Z
+- 📦 **TypeScript-first** - full typing out of the box
+- 🚀 **High performance** - handles 1000+ nodes without FPS drops
+- 🎨 **Addons API** - extend any component with custom functionality
 
 ## 🚀 Quick Start
 
 ```typescript
-import {
-  CoreEngine,
-  GridPlugin,
-  SelectionPlugin,
-  NodeHotkeysPlugin,
-} from "@flowscape-ui/core-sdk";
+import { CoreEngine, GridPlugin, SelectionPlugin, NodeHotkeysPlugin } from '@flowscape-ui/core-sdk';
 
 // Create engine with plugins
 const engine = new CoreEngine({
-  container: document.getElementById("canvas-container")!,
+  container: document.getElementById('canvas-container')!,
   width: 1200,
   height: 800,
   plugins: [
@@ -62,16 +77,16 @@ const rect = engine.nodes.addShape({
   y: 100,
   width: 200,
   height: 150,
-  fill: "#3b82f6",
+  fill: '#3b82f6',
   cornerRadius: 8,
 });
 
 const text = engine.nodes.addText({
   x: 120,
   y: 140,
-  text: "Hello Flowscape!",
+  text: 'Hello Flowscape!',
   fontSize: 24,
-  fill: "white",
+  fill: 'white',
 });
 
 // Grouping
@@ -83,7 +98,11 @@ rect.getNode().moveTo(group.getNode());
 text.getNode().moveTo(group.getNode());
 ```
 
----
+## 🔒 Public API Policy
+
+- All supported entities are exported only through the root package `@flowscape-ui/core-sdk`.
+- The `src/public-api.ts` file contains the complete list of stable exports; anything outside this file is considered internal API and may change without notice.
+- Do not import files directly via `@flowscape-ui/core-sdk/src/...` — such imports are not supported and may break during updates.
 
 ## 🏗️ Architecture
 
@@ -118,19 +137,19 @@ text.getNode().moveTo(group.getNode());
 Plugins extend engine functionality without modifying the core:
 
 ```typescript
-import { Plugin, CoreEngine } from "@flowscape-ui/core-sdk";
+import { Plugin, CoreEngine } from '@flowscape-ui/core-sdk';
 
 class CustomPlugin extends Plugin {
   protected onAttach(core: CoreEngine): void {
     // Initialize on attach
-    core.eventBus.on("node:created", (node) => {
-      console.log("Node created:", node);
+    core.eventBus.on('node:created', (node) => {
+      console.log('Node created:', node);
     });
   }
 
   protected onDetach(core: CoreEngine): void {
     // Cleanup on detach
-    core.eventBus.off("node:created");
+    core.eventBus.off('node:created');
   }
 }
 
@@ -143,7 +162,20 @@ const engine = new CoreEngine({
 
 ---
 
-## 🧩 Built-in Plugins
+| Plugin                 | Description                                      |
+| ---------------------- | ------------------------------------------------ |
+| `GridPlugin`           | Adaptive grid with automatic scaling             |
+| `SelectionPlugin`      | Selection, transformation, drag & drop, grouping |
+| `NodeHotkeysPlugin`    | Copy/paste/cut nodes, delete, z-index management |
+| `CameraHotkeysPlugin`  | Zoom and pan controls with keyboard              |
+| `RulerPlugin`          | Rulers with measurement units                    |
+| `RulerGuidesPlugin`    | Draggable guide lines from rulers                |
+| `RulerHighlightPlugin` | Ruler highlighting on hover                      |
+| `RulerManagerPlugin`   | Toggle rulers and manage guides                  |
+| `AreaSelectionPlugin`  | Area selection with frame (Shift+Drag)           |
+| `VisualGuidesPlugin`   | Smart alignment guides during movement/resize    |
+| `HistoryPlugin`        | Undo/redo functionality with Ctrl+Z              |
+| `LogoPlugin`           | Watermark/logo on canvas                         |
 
 | Plugin                   | Description                                           |
 | ------------------------ | ----------------------------------------------------- |
@@ -164,14 +196,16 @@ const engine = new CoreEngine({
 
 ### Node Operations (NodeHotkeysPlugin)
 
-| Shortcut               | Action                   |
-| ---------------------- | ------------------------ |
-| `Ctrl+C`               | Copy selected nodes      |
-| `Ctrl+X`               | Cut selected nodes       |
-| `Ctrl+V`               | Paste nodes              |
-| `Delete` / `Backspace` | Delete selected nodes    |
-| `Ctrl+]`               | Move node up (z-index)   |
-| `Ctrl+[`               | Move node down (z-index) |
+| Shortcut               | Action                       |
+| ---------------------- | ---------------------------- |
+| `Ctrl+C`               | Copy selected nodes          |
+| `Ctrl+X`               | Cut selected nodes           |
+| `Ctrl+V`               | Paste nodes                  |
+| `Delete` / `Backspace` | Delete selected nodes        |
+| `Ctrl+]`               | Move node forward (z-index)  |
+| `Ctrl+[`               | Move node backward (z-index) |
+| `Ctrl+Shift+]`         | Bring to front               |
+| `Ctrl+Shift+[`         | Send to back                 |
 
 ### Grouping (SelectionPlugin)
 
@@ -182,7 +216,14 @@ const engine = new CoreEngine({
 | `Shift+Click`           | Add/remove node to/from selection |
 | `Shift` (during resize) | Lock aspect ratio                 |
 
-### Camera Controls (CameraHotkeysPlugin)
+#### History (HistoryPlugin)
+
+| Shortcut       | Action |
+| -------------- | ------ |
+| `Ctrl+Z`       | Undo   |
+| `Ctrl+Shift+Z` | Redo   |
+
+#### Camera Controls (CameraHotkeysPlugin)
 
 | Shortcut            | Action      |
 | ------------------- | ----------- |
@@ -214,7 +255,7 @@ const rect = engine.nodes.addShape({
   y: 50,
   width: 200,
   height: 100,
-  fill: "#10b981",
+  fill: '#10b981',
   cornerRadius: 12,
 });
 
@@ -223,8 +264,8 @@ const circle = engine.nodes.addCircle({
   x: 300,
   y: 100,
   radius: 50,
-  fill: "#f59e0b",
-  stroke: "#d97706",
+  fill: '#f59e0b',
+  stroke: '#d97706',
   strokeWidth: 3,
 });
 
@@ -232,10 +273,10 @@ const circle = engine.nodes.addCircle({
 const text = engine.nodes.addText({
   x: 400,
   y: 50,
-  text: "Flowscape UI",
+  text: 'Flowscape UI',
   fontSize: 32,
-  fontFamily: "Inter",
-  fill: "#1f2937",
+  fontFamily: 'Inter',
+  fill: '#1f2937',
 });
 
 // Image
@@ -244,7 +285,7 @@ const image = engine.nodes.addImage({
   y: 200,
   width: 200,
   height: 150,
-  src: "/path/to/image.jpg",
+  src: '/path/to/image.jpg',
 });
 ```
 
@@ -252,22 +293,22 @@ const image = engine.nodes.addImage({
 
 ```typescript
 // Subscribe to events
-engine.eventBus.on("node:created", (node) => {
-  console.log("Node created:", node);
+engine.eventBus.on('node:created', (node) => {
+  console.log('Node created:', node);
 });
 
-engine.eventBus.on("node:selected", (node) => {
-  console.log("Node selected:", node);
+engine.eventBus.on('node:selected', (node) => {
+  console.log('Node selected:', node);
 });
 
-engine.eventBus.on("camera:zoom", ({ scale }) => {
-  console.log("Zoom changed:", scale);
+engine.eventBus.on('camera:zoom', ({ scale }) => {
+  console.log('Zoom changed:', scale);
 });
 
 // Unsubscribe
 const handler = (node) => console.log(node);
-engine.eventBus.on("node:created", handler);
-engine.eventBus.off("node:created", handler);
+engine.eventBus.on('node:created', handler);
+engine.eventBus.off('node:created', handler);
 ```
 
 ### Grouping and Management
@@ -333,20 +374,6 @@ bun run lint:ts       # TypeScript check
 bun run lint:fix      # Auto-fix
 ```
 
----
-
-## 📖 Documentation
-
-Full documentation is available at [flowscape-ui.github.io/core-sdk-doc/](https://flowscape-ui.github.io/core-sdk-doc/)
-
-- [Getting Started](https://flowscape-ui.github.io/core-sdk-doc/docs/getting-started/installation)
-- [Core Concepts](https://flowscape-ui.github.io/core-sdk-doc/docs/core-concepts/architecture)
-- [Plugins](https://flowscape-ui.github.io/core-sdk-doc/docs/plugins/overview)
-- [API Reference](https://flowscape-ui.github.io/core-sdk-doc/docs/api/reference)
-- [Interactive Demo](https://flowscape-ui.github.io/core-sdk-doc/docs/guides/interactive-demo)
-
----
-
 ## 📄 License
 
 MIT © Flowscape UI Team