@deckedout/visual-editor 1.0.7 → 1.0.8

package/README.md

@@ -8,6 +8,31 @@
 
 A flexible, drag-and-drop visual editor built with React and Konva for creating interactive canvases with customizable elements.
 
+## 🚀 Try It Online
+
+The app example is published at: [https://deckedout.fr/dev/visual-editor/playground/](https://deckedout.fr/dev/visual-editor/playground/)
+
+You can check app example codebase: [https://github.com/EIP-DeckedOut-Orga/eip-visual-editor-example-vite/](https://github.com/EIP-DeckedOut-Orga/eip-visual-editor-example-vite/)
+
+> 💡 **Tip**: Fork the demo and start customizing immediately!
+
+## Preview
+
+**Basic Editor Interface:**
+
+![Basic Editor](./src/doc-assets/examples-preview/basic_editor_preview.png)
+*Full editor with toolbar, canvas, inspector, and layers panel*
+
+**Custom Mode - Card Designer:**
+
+![Custom Mode](./src/doc-assets/examples-preview/custom_mode_preview.png)
+*Custom canvas size (750×1050) with custom toolbar and topbar*
+
+**Asset Picker with Background Selector:**
+
+![Asset Picker](./src/doc-assets/examples-preview/with_background_assets_preview.png)
+*Asset management with background color*
+
 ## Features
 
 - 🎨 **Visual Canvas Editor**: Drag, resize, and rotate elements on a canvas
@@ -62,25 +87,24 @@ import '@deckedout/visual-editor/styles';
 
 ```tsx
 import { VisualEditorWorkspace } from '@deckedout/visual-editor';
-import { useState } from 'react';
 
 function App() {
-  const [mode, setMode] = useState('edit');
-
   return (
     <div style={{ width: '100vw', height: '100vh' }}>
       <VisualEditorWorkspace
-        canvasWidth={800}
-        canvasHeight={600}
-        mode={mode}
+        showToolbar={true}
+        showTopbar={true}
         showInspector={true}
         showLayers={true}
+        enableSnapGuides={true}
       />
     </div>
   );
 }
 ```
 
+**Want to see it in action?** Check out the [live Vite example](#-live-examples) with three interactive demos!
+
 ## Core Components
 
 ### VisualEditorWorkspace
@@ -186,7 +210,59 @@ globalElementRegistry.register(customElementRenderer);
 - `globalElementRegistry`: Global registry for element types
 - Built-in elements: `textElementRenderer`, `imageElementRenderer`
 
-## Examples
+## 🎯 Live Examples
+
+A complete **Vite + React example project** with three interactive demos:
+
+### [📁 example-vite/](./example-vite) - Full Application
+
+**[Try in StackBlitz →](https://stackblitz.com/github/EIP-DeckedOut-Orga/eip-visual-editor-package/tree/main/example-vite?file=src/App.tsx)**
+
+**Or run locally:**
+
+```bash
+cd example-vite
+npm install
+npm run dev
+```
+
+**Included Demos:**
+
+1. **[Basic Editor](./example-vite/src/pages/BasicEditor.tsx)** (`/`)
+
+   - Simple integration with all default features
+   - All panels enabled (toolbar, topbar, inspector, layers)
+   - Snap guides and alignment helpers
+   - Perfect starting point for new projects
+2. **[Custom Mode](./example-vite/src/pages/CustomMode.tsx)** (`/custom-mode`)
+
+   - Card designer with 750×1050 custom canvas
+   - Custom toolbar with "Load Template" action
+   - Custom topbar with "Export PNG" button
+   - Auto-save functionality with visual indicator
+   - Background color and grid configuration
+   - Shows advanced editor customization
+3. **[Asset Picker](./example-vite/src/pages/WithAssets.tsx)** (`/with-assets`)
+
+   - Asset management integration
+   - Mock game assets (sprites, backgrounds, items)
+   - **Background upload** - Upload custom images via file picker
+   - Dynamic background selector - Uploaded images added to dropdown
+   - 1200×800 canvas with dark theme
+   - Grid overlay for precise positioning
+
+**Features demonstrated:**
+
+- 🎨 Custom canvas sizes and layouts
+- 🔧 Toolbar and topbar customization
+- 📦 Asset picker integration
+- 💾 State persistence and auto-save
+- 🎭 Different editor modes
+- 🌙 Dark mode theming
+
+See the [example-vite/README.md](./example-vite/README.md) for full setup instructions and customization guide.
+
+## 📘 Code Examples
 
 ### Basic Editor
 
@@ -197,8 +273,11 @@ function BasicEditor() {
   return (
     <div style={{ width: '100%', height: '600px' }}>
       <VisualEditorWorkspace
-        canvasWidth={800}
-        canvasHeight={600}
+        showToolbar={true}
+        showTopbar={true}
+        showInspector={true}
+        showLayers={true}
+        enableSnapGuides={true}
       />
     </div>
   );
@@ -222,10 +301,76 @@ globalElementRegistry.register(imageElementRenderer);
 globalElementRegistry.register(myCustomElement);
 
 function EditorWithCustomElements() {
-  return <VisualEditorWorkspace canvasWidth={800} canvasHeight={600} />;
+  return <VisualEditorWorkspace />;
+}
+```
+
+### With Asset Picker
+
+```tsx
+import { VisualEditorWorkspace } from '@deckedout/visual-editor';
+
+const assets = [
+  { name: 'Character', path: '/assets/character.png', type: 'sprite' },
+  { name: 'Background', path: '/assets/bg.png', type: 'background' }
+];
+
+function EditorWithAssets() {
+  return (
+    <VisualEditorWorkspace
+      showAssetPicker={true}
+      mode={{
+        name: 'Asset Editor',
+        assetPickerProps: { assets }
+      }}
+    />
+  );
 }
 ```
 
+## 📚 Documentation
+
+### Full API Documentation
+
+Available at: [https://deckedout.fr/dev/docs/editor/](https://deckedout.fr/dev/docs/editor/)
+
+### TypeScript Examples (`/examples`)
+
+Comprehensive standalone examples showing specific features:
+
+- **[01-basic-usage.tsx](./examples/01-basic-usage.tsx)** - Quickstart with minimal configuration
+- **[02-controlled-mode.tsx](./examples/02-controlled-mode.tsx)** - External state management and persistence
+- **[03-custom-elements.tsx](./examples/03-custom-elements.tsx)** - Creating custom element types
+- **[04-programmatic-api.tsx](./examples/04-programmatic-api.tsx)** - Using the editor API programmatically
+- **[05-editor-modes.tsx](./examples/05-editor-modes.tsx)** - Configuring different editor modes
+- **[06-asset-picker.tsx](./examples/06-asset-picker.tsx)** - Integrating asset management
+
+See the [examples README](./examples/README.md) for detailed documentation and usage patterns.
+
+### Runnable Vite Example (`/example-vite`)
+
+Complete working application with React Router and three interactive demos:
+
+- **[BasicEditor.tsx](./example-vite/src/pages/BasicEditor.tsx)** - Simple integration
+- **[CustomMode.tsx](./example-vite/src/pages/CustomMode.tsx)** - Card designer with custom toolbar/topbar
+- **[WithAssets.tsx](./example-vite/src/pages/WithAssets.tsx)** - Asset picker and background selector
+
+Run it locally: `cd example-vite && npm install && npm run dev`
+
+Full guide: [example-vite/README.md](./example-vite/README.md)
+
+### Generating Documentation Locally
+
+```bash
+# Generate documentation
+npm run docs
+
+# Watch mode (regenerates on file changes)
+npm run docs:watch
+```
+
+Documentation is automatically generated and deployed to the server on every push to the main branch.
+
 ## Development
 
 ### Running Tests
@@ -257,16 +402,26 @@ npm run lint
 ### Testing Coverage
 
 This package maintains high test coverage:
+
 - **95.26%** statements
-- **94.2%** branches  
+- **94.2%** branches
 - **93.05%** functions
 - **95.77%** lines
 
 See [TESTING.md](./TESTING.md) for detailed testing documentation.
 
+## Documentation
+
+- **[API Reference](./API_REFERENCE.md)** - Complete API documentation
+- **[Quick Reference](./QUICK_REFERENCE.md)** - Quick start guide
+- **[Testing Guide](./TESTING.md)** - Testing documentation and coverage
+- **[Changelog](./CHANGELOG.md)** - Version history and changes
+- **[Architecture Decision Records](./adr/)** - Design decisions and rationale
+
 ## Contributing
 
 Contributions are welcome! Please ensure:
+
 1. All tests pass (`npm test`)
 2. Code coverage remains above 90%
 3. Code is properly linted (`npm run lint`)
@@ -275,7 +430,3 @@ Contributions are welcome! Please ensure:
 ## License
 
 MIT
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/index.d.mts

@@ -317,6 +317,7 @@ interface CustomEditorSeparator {
 type CustomEditorAction = CustomEditorButtonAction | CustomEditorDropdownAction | CustomEditorInputAction | CustomEditorColorAction | CustomEditorToggleAction | CustomEditorSeparator;
 /**
  * Configuration for topbar controls visibility
+ * @public
  */
 interface TopbarConfig {
     /** Show undo button */
@@ -352,6 +353,7 @@ interface TopbarConfig {
 }
 /**
  * Configuration for toolbar controls visibility
+ * @public
  */
 interface ToolbarConfig {
     /** Show element creation tools */
@@ -546,6 +548,10 @@ declare const VisualEditor: React$1.FC<VisualEditorProps>;
  * Dynamically renders fields based on the element's inspectorSchema.
  */
 
+/**
+ * Props for the Inspector component
+ * @public
+ */
 interface InspectorProps {
     /** Currently selected element */
     selectedElement: EditorElement | null;
@@ -583,6 +589,10 @@ declare function renderField(field: InspectorFieldSchema, props: any, editingVal
  * reorder, and delete elements.
  */
 
+/**
+ * Props for the LayersPanel component
+ * @public
+ */
 interface LayersPanelProps {
     /** All elements in the canvas */
     elements: EditorElement[];
@@ -609,6 +619,10 @@ declare const LayersPanel: React$1.FC<LayersPanelProps>;
  * This component creates a complete editor experience by coordinating all three parts.
  */
 
+/**
+ * Props for the VisualEditorWorkspace component
+ * @public
+ */
 interface VisualEditorWorkspaceProps {
     /** Editor mode configuration */
     mode?: EditorMode;
@@ -694,7 +708,37 @@ declare const AssetPicker: React$1.FC<AssetPickerProps>;
  */
 
 /**
- * Custom hook for managing editor state
+ * Custom hook for managing visual editor state.
+ *
+ * Provides a complete state management solution for the visual editor, including:
+ * - Element CRUD operations
+ * - Selection management
+ * - Undo/redo functionality
+ * - Canvas operations (zoom, pan)
+ * - History tracking
+ * - Import/export capabilities
+ *
+ * @param initialMode - Optional initial editor mode configuration
+ * @returns Object containing editor state, API methods, and utility functions
+ *
+ * @example
+ * ```tsx
+ * function MyEditor() {
+ *   const { state, api, undo, redo, canUndo, canRedo } = useEditorState();
+ *
+ *   const handleAddText = () => {
+ *     api.addElement(createElement('text', { content: 'Hello' }));
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleAddText}>Add Text</button>
+ *       <button onClick={undo} disabled={!canUndo}>Undo</button>
+ *       <button onClick={redo} disabled={!canRedo}>Redo</button>
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 declare const useEditorState: (initialMode?: EditorMode | null) => {
     state: EditorState;
@@ -765,6 +809,30 @@ declare class ElementRegistry {
  * Create a global singleton registry (can be used across the app)
  */
 declare const globalElementRegistry: ElementRegistry;
+/**
+ * React hook for creating and managing an element registry instance.
+ *
+ * The registry is memoized and will only re-initialize if initialRenderers changes.
+ * This ensures stable registry instances across re-renders.
+ *
+ * @param initialRenderers - Optional array of element renderers to register on initialization
+ * @returns ElementRegistry instance with registered renderers
+ *
+ * @example
+ * ```tsx
+ * import { useElementRegistry } from '@/core/ElementRegistry';
+ * import { TextElement, ImageElement } from '@/elements';
+ *
+ * function MyEditor() {
+ *   const registry = useElementRegistry([TextElement, ImageElement]);
+ *
+ *   // Use registry to look up renderers
+ *   const renderer = registry.get('text');
+ *
+ *   return <Canvas registry={registry} />;
+ * }
+ * ```
+ */
 declare const useElementRegistry: (initialRenderers?: ElementRenderer[]) => ElementRegistry;
 
 /**

package/dist/index.d.ts

@@ -317,6 +317,7 @@ interface CustomEditorSeparator {
 type CustomEditorAction = CustomEditorButtonAction | CustomEditorDropdownAction | CustomEditorInputAction | CustomEditorColorAction | CustomEditorToggleAction | CustomEditorSeparator;
 /**
  * Configuration for topbar controls visibility
+ * @public
  */
 interface TopbarConfig {
     /** Show undo button */
@@ -352,6 +353,7 @@ interface TopbarConfig {
 }
 /**
  * Configuration for toolbar controls visibility
+ * @public
  */
 interface ToolbarConfig {
     /** Show element creation tools */
@@ -546,6 +548,10 @@ declare const VisualEditor: React$1.FC<VisualEditorProps>;
  * Dynamically renders fields based on the element's inspectorSchema.
  */
 
+/**
+ * Props for the Inspector component
+ * @public
+ */
 interface InspectorProps {
     /** Currently selected element */
     selectedElement: EditorElement | null;
@@ -583,6 +589,10 @@ declare function renderField(field: InspectorFieldSchema, props: any, editingVal
  * reorder, and delete elements.
  */
 
+/**
+ * Props for the LayersPanel component
+ * @public
+ */
 interface LayersPanelProps {
     /** All elements in the canvas */
     elements: EditorElement[];
@@ -609,6 +619,10 @@ declare const LayersPanel: React$1.FC<LayersPanelProps>;
  * This component creates a complete editor experience by coordinating all three parts.
  */
 
+/**
+ * Props for the VisualEditorWorkspace component
+ * @public
+ */
 interface VisualEditorWorkspaceProps {
     /** Editor mode configuration */
     mode?: EditorMode;
@@ -694,7 +708,37 @@ declare const AssetPicker: React$1.FC<AssetPickerProps>;
  */
 
 /**
- * Custom hook for managing editor state
+ * Custom hook for managing visual editor state.
+ *
+ * Provides a complete state management solution for the visual editor, including:
+ * - Element CRUD operations
+ * - Selection management
+ * - Undo/redo functionality
+ * - Canvas operations (zoom, pan)
+ * - History tracking
+ * - Import/export capabilities
+ *
+ * @param initialMode - Optional initial editor mode configuration
+ * @returns Object containing editor state, API methods, and utility functions
+ *
+ * @example
+ * ```tsx
+ * function MyEditor() {
+ *   const { state, api, undo, redo, canUndo, canRedo } = useEditorState();
+ *
+ *   const handleAddText = () => {
+ *     api.addElement(createElement('text', { content: 'Hello' }));
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleAddText}>Add Text</button>
+ *       <button onClick={undo} disabled={!canUndo}>Undo</button>
+ *       <button onClick={redo} disabled={!canRedo}>Redo</button>
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 declare const useEditorState: (initialMode?: EditorMode | null) => {
     state: EditorState;
@@ -765,6 +809,30 @@ declare class ElementRegistry {
  * Create a global singleton registry (can be used across the app)
  */
 declare const globalElementRegistry: ElementRegistry;
+/**
+ * React hook for creating and managing an element registry instance.
+ *
+ * The registry is memoized and will only re-initialize if initialRenderers changes.
+ * This ensures stable registry instances across re-renders.
+ *
+ * @param initialRenderers - Optional array of element renderers to register on initialization
+ * @returns ElementRegistry instance with registered renderers
+ *
+ * @example
+ * ```tsx
+ * import { useElementRegistry } from '@/core/ElementRegistry';
+ * import { TextElement, ImageElement } from '@/elements';
+ *
+ * function MyEditor() {
+ *   const registry = useElementRegistry([TextElement, ImageElement]);
+ *
+ *   // Use registry to look up renderers
+ *   const renderer = registry.get('text');
+ *
+ *   return <Canvas registry={registry} />;
+ * }
+ * ```
+ */
 declare const useElementRegistry: (initialRenderers?: ElementRenderer[]) => ElementRegistry;
 
 /**