@flowscape-ui/core-sdk 1.0.1 → 1.0.3

package/README.md

@@ -1,29 +1,48 @@
-<div align="center">
-
 # 🎨 @flowscape-ui/core-sdk
 
-**Powerful 2D canvas engine built on Konva**
+**Powerful 2D canvas engine built on Konva.js**
 
 [![npm version](https://img.shields.io/npm/v/@flowscape-ui/core-sdk.svg)](https://www.npmjs.com/package/@flowscape-ui/core-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![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)
-[Documentation](https://github.com/Flowscape-UI/core-sdk#readme) • [Examples](https://github.com/Flowscape-UI/core-sdk/tree/main/playground) • [Changelog](./CHANGELOG.md)
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/@flowscape-ui/core-sdk)](https://bundlephobia.com/package/@flowscape-ui/core-sdk)
 
+[![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)
+
 </div>
 
 ---
 
+## 📖 Documentation
+
+### What's New in 1.0.3
+
+- ✨ **History System** — Full undo/redo support (Ctrl+Z / Ctrl+Shift+Z)
+- 📏 **Alignment Guides** — Smart guides appear during movement and resizing
+- ✏️ **Inline Text Editing** — Double-click text nodes to edit directly
+- 🔧 **Addons API** — Attach custom functionality to any component
+- 📐 **Canvas Auto-Resize** — Automatically adjusts to window size changes
+- ⚡ **Performance** — Optimized to handle 1000+ nodes smoothly
+- 🎨 **New Layer Shortcuts** — Ctrl+Shift+[ / ] for send to back/bring to front
+- 📦 **Full TypeScript** — Complete type coverage across all components
+- 🎮 **Storybook Demo** — Interactive playground to test all features
+
 ## ✨ 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
-- ⌨️ **Hotkeys** — Ctrl+C/V/X, Delete, Ctrl+G for grouping
+- 📐 **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
-- 🚀 **Optimized** — tree-shaking, ESM + CJS, source maps
+- 🚀 **High performance** — handles 1000+ nodes without FPS drops
+- 🎨 **Addons API** — extend any component with custom functionality
+
+---
 
 ## 📦 Installation
 
@@ -35,13 +54,15 @@ yarn add @flowscape-ui/core-sdk
 bun add @flowscape-ui/core-sdk
 ```
 
+---
+
 ## 🚀 Quick Start
 
 ```typescript
 import { CoreEngine, GridPlugin, SelectionPlugin, NodeHotkeysPlugin } from '@flowscape-ui/core-sdk';
 
 // Create engine with plugins
-const core = new CoreEngine({
+const engine = new CoreEngine({
   container: document.getElementById('canvas-container')!,
   width: 1200,
   height: 800,
@@ -53,7 +74,7 @@ const core = new CoreEngine({
 });
 
 // Add shapes
-const rect = core.nodes.addShape({
+const rect = engine.nodes.addShape({
   x: 100,
   y: 100,
   width: 200,
@@ -62,7 +83,7 @@ const rect = core.nodes.addShape({
   cornerRadius: 8,
 });
 
-const text = core.nodes.addText({
+const text = engine.nodes.addText({
   x: 120,
   y: 140,
   text: 'Hello Flowscape!',
@@ -71,7 +92,7 @@ const text = core.nodes.addText({
 });
 
 // Grouping
-const group = core.nodes.addGroup({
+const group = engine.nodes.addGroup({
   x: 400,
   y: 200,
 });
@@ -79,6 +100,12 @@ 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
 
 ### Core Components
@@ -103,7 +130,6 @@ text.getNode().moveTo(group.getNode());
 │  ┌──────────────────────────────┐   │
 │  │     Camera Manager           │   │
 │  │  - Zoom (Ctrl+Wheel)         │   │
-│  │  - Pan (Space+Drag)          │   │
 │  └──────────────────────────────┘   │
 └─────────────────────────────────────┘
 ```
@@ -113,7 +139,7 @@ text.getNode().moveTo(group.getNode());
 Plugins extend engine functionality without modifying the core:
 
 ```typescript
-import { Plugin } from '@flowscape-ui/core-sdk';
+import { Plugin, CoreEngine } from '@flowscape-ui/core-sdk';
 
 class CustomPlugin extends Plugin {
   protected onAttach(core: CoreEngine): void {
@@ -130,13 +156,13 @@ class CustomPlugin extends Plugin {
 }
 
 // Usage
-const core = new CoreEngine({
+const engine = new CoreEngine({
   container: element,
   plugins: [new CustomPlugin()],
 });
 ```
 
-### Built-in Plugins
+---
 
 | Plugin                 | Description                                      |
 | ---------------------- | ------------------------------------------------ |
@@ -149,49 +175,76 @@ const core = new CoreEngine({
 | `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                         |
 
-### ⌨️ Keyboard Shortcuts
+| Plugin                   | Description                                           |
+| ------------------------ | ----------------------------------------------------- |
+| **GridPlugin**           | Adaptive grid with automatic scaling and snap-to-grid |
+| **SelectionPlugin**      | Selection, transformation, drag & drop, grouping      |
+| **AreaSelectionPlugin**  | Area selection with frame (Shift+Drag)                |
+| **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                       |
+| **LogoPlugin**           | Watermark/logo on canvas                              |
+
+---
 
-#### Node Operations (NodeHotkeysPlugin)
+## ⌨️ Keyboard Shortcuts
 
-| 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) |
-
-#### Grouping (SelectionPlugin)
-
-| Shortcut       | Action                            |
-| -------------- | --------------------------------- |
-| `Ctrl+G`       | Group selected nodes              |
-| `Ctrl+Shift+G` | Ungroup selected group            |
-| `Shift+Click`  | Add/remove node to/from selection |
-| `Shift`        | Lock aspect ratio during resize   |
+### 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 forward (z-index)  |
+| `Ctrl+[`               | Move node backward (z-index) |
+| `Ctrl+Shift+]`         | Bring to front               |
+| `Ctrl+Shift+[`         | Send to back                 |
+
+### Grouping (SelectionPlugin)
+
+| Shortcut                | Action                            |
+| ----------------------- | --------------------------------- |
+| `Ctrl+G`                | Group selected nodes              |
+| `Ctrl+Shift+G`          | Ungroup selected group            |
+| `Shift+Click`           | Add/remove node to/from selection |
+| `Shift` (during resize) | Lock aspect ratio                 |
+
+#### History (HistoryPlugin)
+
+| Shortcut       | Action |
+| -------------- | ------ |
+| `Ctrl+Z`       | Undo   |
+| `Ctrl+Shift+Z` | Redo   |
 
 #### Camera Controls (CameraHotkeysPlugin)
 
-| Shortcut            | Action             |
-| ------------------- | ------------------ |
-| `Ctrl+Wheel`        | Zoom in/out        |
-| `+` / `=`           | Zoom in            |
-| `-`                 | Zoom out           |
-| `Arrow Keys`        | Pan camera         |
-| `Space+Drag`        | Pan camera (mouse) |
-| `Middle Mouse+Drag` | Pan camera         |
-| `Right Mouse+Drag`  | Pan camera         |
+| Shortcut            | Action      |
+| ------------------- | ----------- |
+| `Ctrl+Wheel`        | Zoom in/out |
+| `+` / `=`           | Zoom in     |
+| `-`                 | Zoom out    |
+| `Arrow Keys`        | Pan camera  |
+| `Middle Mouse+Drag` | Pan camera  |
+| `Right Mouse+Drag`  | Pan camera  |
 
-#### Ruler Controls (RulerManagerPlugin)
+### Ruler Controls (RulerManagerPlugin)
 
 | Shortcut               | Action                   |
 | ---------------------- | ------------------------ |
 | `Shift+R`              | Toggle rulers visibility |
 | `Delete` / `Backspace` | Delete active guide      |
-| `Drag from ruler`      | Create guide line        |
+| Drag from ruler        | Create guide line        |
+
+---
 
 ## 📚 Usage Examples
 
@@ -199,7 +252,7 @@ const core = new CoreEngine({
 
 ```typescript
 // Rectangle with rounded corners
-const rect = core.nodes.addShape({
+const rect = engine.nodes.addShape({
   x: 50,
   y: 50,
   width: 200,
@@ -209,7 +262,7 @@ const rect = core.nodes.addShape({
 });
 
 // Circle
-const circle = core.nodes.addCircle({
+const circle = engine.nodes.addCircle({
   x: 300,
   y: 100,
   radius: 50,
@@ -219,7 +272,7 @@ const circle = core.nodes.addCircle({
 });
 
 // Text
-const text = core.nodes.addText({
+const text = engine.nodes.addText({
   x: 400,
   y: 50,
   text: 'Flowscape UI',
@@ -229,7 +282,7 @@ const text = core.nodes.addText({
 });
 
 // Image
-const image = core.nodes.addImage({
+const image = engine.nodes.addImage({
   x: 100,
   y: 200,
   width: 200,
@@ -242,33 +295,33 @@ const image = core.nodes.addImage({
 
 ```typescript
 // Subscribe to events
-core.eventBus.on('node:created', (node) => {
+engine.eventBus.on('node:created', (node) => {
   console.log('Node created:', node);
 });
 
-core.eventBus.on('node:selected', (node) => {
+engine.eventBus.on('node:selected', (node) => {
   console.log('Node selected:', node);
 });
 
-core.eventBus.on('camera:zoom', ({ scale }) => {
+engine.eventBus.on('camera:zoom', ({ scale }) => {
   console.log('Zoom changed:', scale);
 });
 
 // Unsubscribe
 const handler = (node) => console.log(node);
-core.eventBus.on('node:created', handler);
-core.eventBus.off('node:created', handler);
+engine.eventBus.on('node:created', handler);
+engine.eventBus.off('node:created', handler);
 ```
 
 ### Grouping and Management
 
 ```typescript
 // Create group
-const group = core.nodes.addGroup({ x: 0, y: 0 });
+const group = engine.nodes.addGroup({ x: 0, y: 0 });
 
 // Add nodes to group
-const rect1 = core.nodes.addShape({ x: 10, y: 10, width: 50, height: 50 });
-const rect2 = core.nodes.addShape({ x: 70, y: 10, width: 50, height: 50 });
+const rect1 = engine.nodes.addShape({ x: 10, y: 10, width: 50, height: 50 });
+const rect2 = engine.nodes.addShape({ x: 70, y: 10, width: 50, height: 50 });
 
 rect1.getNode().moveTo(group.getNode());
 rect2.getNode().moveTo(group.getNode());
@@ -283,21 +336,23 @@ rect1.getNode().moveToTop(); // Move to top
 
 ```typescript
 // Programmatic zoom
-core.camera.zoomIn(); // Zoom in
-core.camera.zoomOut(); // Zoom out
-core.camera.setZoom(1.5); // Set specific scale
+engine.camera.zoomIn(); // Zoom in
+engine.camera.zoomOut(); // Zoom out
+engine.camera.setZoom(1.5); // Set specific scale
 
 // Panning
-core.camera.pan(100, 50); // Pan by dx, dy
+engine.camera.pan(100, 50); // Pan by dx, dy
 
 // Center on node
-const node = core.nodes.addShape({ x: 500, y: 500, width: 100, height: 100 });
-core.camera.centerOn(node);
+const node = engine.nodes.addShape({ x: 500, y: 500, width: 100, height: 100 });
+engine.camera.centerOn(node);
 
 // Reset camera
-core.camera.reset();
+engine.camera.reset();
 ```
 
+---
+
 ## 🔧 Development
 
 ```bash
@@ -321,18 +376,14 @@ bun run lint:ts       # TypeScript check
 bun run lint:fix      # Auto-fix
 ```
 
-## 📖 Documentation
-
-Coming soon
-
 ## 📄 License
 
-MIT © [Flowscape UI Team](https://github.com/Flowscape-UI)
+MIT © Flowscape UI Team
 
 ---
 
 <div align="center">
 
-**[⭐ 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)**
+⭐ [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)
 
 </div>