editor-ts 0.0.1 → 0.0.12

package/README.md

@@ -1,401 +1,280 @@
-
 # EditorTs
 
-DO NOT USE THIS IN PRODUCTION YET IT IS A WORK IN PROGRESS - EARLY DEVELOPMENT
-
-A powerful TypeScript library for editing HTML content while maintaining its structure in a JSON representation. EditorTs provides a simple `init()` function to create a fully-functional WYSIWYG editor with minimal configuration.
-
-## Features
+DO NOT USE THIS IN PRODUCTION YET. Early development.
 
-- **One-Line Setup**: Initialize a complete editor with `init()`
-- **WYSIWYG Editing**: Click-to-edit interface with context toolbars
-- **Runtime Configuration**: Toolbars configured in JavaScript, not stored in JSON
-- **Iframe Sandboxing**: Template runs in isolated iframe for proper CSS/JS scoping
-- **Event System**: Hook into component selection, editing, deletion, etc.
-- **Type-Safe**: Full TypeScript support
-- **Clean JSON**: Only stores component metadata and styles, no behavioral config
+EditorTs is a TypeScript library for editing HTML content while keeping the source of truth in clean, portable JSON (components/styles/assets). The editor runtime (toolbars, permissions, UI layout, event handlers) stays in JavaScript.
 
-## Quick Start
+## Quickstart (run the demo)
 
 ```bash
 bun install
 bun run dev
 ```
 
-Open http://localhost:5021 to see the editor!
+Open `http://localhost:5021`.
+
+The demo UI is `index.html` and is wired by `examples/quickstart.ts`.
+
+## Core concepts
+
+### Data vs runtime config
+
+- JSON (“data”): components, styles/CSS, assets.
+- JS (“runtime”): toolbars, UI wiring, event handlers, editor behaviors.
+
+This separation is intentional: the same JSON can be used in different apps with different editor experiences.
+
+### Components-first rendering
+
+When both are present:
+- `components` are the source of truth.
+- `Page.getHTML()` renders from components.
 
-## Simple Usage with `init()`
+When only HTML is present:
+- HTML can be converted to components when DOM is available.
 
-```typescript
-import { init } from 'editorts';
-import pageData from './page.json';
+## Usage
+
+### Minimal init
+
+```ts
+import { init, type PageData } from 'editorts'
 
-// Initialize editor with one function call
 const editor = init({
-  containerId: 'root',
-  data: pageData,
-  
-  // Configure toolbars (runtime only, not saved to JSON)
-  toolbars: {
-    byId: {
-      'header': { 
-        enabled: true,
-        actions: [
-          { id: 'edit', label: 'Edit', icon: '✏️', enabled: true },
-          { id: 'duplicate', label: 'Duplicate', icon: '📋', enabled: true }
-        ]
-      }
-    },
-    byType: {
-      'custom-code': {
-        actions: [
-          { id: 'editJS', label: 'Edit Code', icon: '📜', enabled: true }
-        ]
-      }
-    }
-  },
-  
-  // Optional callbacks
-  onComponentSelect: (component) => {
-    console.log('Selected:', component.attributes?.id);
-  }
-});
-
-// Access the Page API
-editor.page.components.findById('header');
-editor.page.styles.updateStyle('#header', { 'color': 'red' });
-
-// Add event listeners
-editor.on('componentEdit', (component) => {
-  console.log('Editing:', component);
-});
-
-// Save the page (clean JSON, no toolbar configs)
-const json = editor.save();
+  iframeId: 'preview-iframe',
+  data: pageData satisfies PageData,
+})
 ```
 
-## Architecture: Runtime vs. Stored Data
+### Storage adapters
 
-EditorTs follows a clean separation between **data** (stored in JSON) and **behavior** (configured in JavaScript).
+Local storage is the default, but we recommend SQLocal for persistent, browser-native SQLite storage. SQLocal requires cross-origin isolation headers, so the easiest way is to use the Vite examples in `examples/localsql` or `examples/solid`.
 
-**See [AGENTS.md](./AGENTS.md) for full architecture principles.**
+```ts
+import { init } from 'editorts'
+import { SQLocal } from 'sqlocal'
 
-### What's Stored in JSON (Database)
-- Component metadata (type, attributes, tagName)
-- Styling (CSS, inline styles)
-- Content (text, HTML, assets)
-- Component structure
+const sqlocalClient = new SQLocal('editorts.sqlite')
 
-### What's Configured in JavaScript (Runtime)
-- Toolbar configurations
-- Editor behaviors
-- UI interactions
-- Event handlers
-- Permissions
+const editor = init({
+  iframeId: 'preview-iframe',
+  data: pageData,
+  storage: {
+    type: 'sqlocal',
+    client: sqlocalClient,
+    // databaseName: 'editorts.sqlite', // when not passing client
+  },
+})
+```
 
-**Example:**
-```typescript
-// JSON stays clean
-const page = new Page(jsonData);
+Run the SQLocal demos (Vite):
 
-// Configure at runtime
-page.toolbars.configureById('header', { ... });
+```bash
+cd examples/localsql
+bun install
+bun run dev
+```
 
-// Export is still clean
-page.toJSON(); // No toolbar property in output
+```bash
+cd examples/solid
+bun install
+bun run dev
 ```
 
-## Toolbar System
+Open `http://localhost:5173`.
+
+### Toolbars (runtime only)
 
-### Configure Toolbars at Runtime
+```ts
+import { init } from 'editorts'
 
-```typescript
 const editor = init({
-  containerId: 'root',
+  iframeId: 'preview-iframe',
   data: pageData,
   toolbars: {
-    // By component ID
     byId: {
-      'header': { enabled: true, actions: [...] },
-      'footer': { enabled: false, actions: [] }
-    },
-    
-    // By component type
-    byType: {
-      'custom-code': { actions: [...] },
-      'box': { actions: [...] }
-    },
-    
-    // By tag name
-    byTag: {
-      'div': { actions: [...] }
+      header: {
+        enabled: true,
+        actions: [
+          { id: 'edit', label: 'Edit', icon: '✏️', enabled: true },
+          { id: 'duplicate', label: 'Duplicate', icon: '📋', enabled: true },
+        ],
+      },
     },
-    
-    // Global default
-    default: { actions: [...] }
-  }
-});
-
-// Or configure after init
-editor.page.toolbars.configureById('sidebar', {
-  enabled: true,
-  actions: [
-    { id: 'edit', label: 'Edit', icon: '✏️', enabled: true },
-    { id: 'delete', label: 'Delete', icon: '🗑️', enabled: false, danger: true }
-  ]
-});
+  },
+})
 ```
 
-### Toolbar Actions
-
-- **Edit (✏️)** - Edit component properties
-- **Edit JS (📜)** - Edit component JavaScript with Monaco editor
-- **Duplicate (📋)** - Create a copy of the component
-- **Delete (🗑️)** - Remove component from page
+### UI containers (you own the layout)
 
-### Toolbar Presets
+EditorTs does not create your sidebar/tabs/layout. You provide containers and `init()` wires them.
 
-```typescript
-import { toolbarPresets } from 'editorts';
-
-// Use presets
-page.toolbars.configureById('header', toolbarPresets.full);
-page.toolbars.configureById('footer', toolbarPresets.editOnly);
-page.toolbars.configureById('banner', toolbarPresets.minimal);
-```
-
-Available presets:
-- `full` - All actions enabled
-- `editOnly` - Edit, Edit JS, Duplicate (no delete)
-- `minimal` - Edit and Delete only
-- `readOnly` - View only
-- `disabled` - No toolbar
-
-## API Reference
-
-### `init(config)` → EditorTsEditor
-
-Initialize the editor with configuration.
-
-**Returns:** EditorTsEditor instance
-
-```typescript
-interface EditorTsEditor {
-  page: Page;                    // Full Page instance
-  on(event, callback): void;     // Add event listener
-  off(event, callback): void;    // Remove event listener
-  refresh(): void;               // Refresh preview
-  save(): string;                // Export JSON
-  destroy(): void;               // Clean up
-  elements: {                    // Access DOM elements
-    container: HTMLElement;
-    sidebar?: HTMLElement;
-    canvas: HTMLElement;
-    iframe: HTMLIFrameElement;
-  }
-}
+```ts
+const editor = init({
+  iframeId: 'preview-iframe',
+  data: pageData,
+  ui: {
+    stats: { containerId: 'stats-container' },
+    layers: { containerId: 'layers-container' },
+    selectedInfo: { containerId: 'selected-info' },
+    viewTabs: {
+      editorButtonId: 'tab-editor',
+      codeButtonId: 'tab-code',
+      defaultView: 'editor',
+    },
+    editors: {
+      js: { containerId: 'js-editor-container' },
+      css: { containerId: 'css-editor-container' },
+      json: { containerId: 'json-editor-container' },
+      jsx: { containerId: 'jsx-editor-container' },
+    },
+  },
+})
 ```
 
-**Events:**
-- `componentSelect` - When component is clicked
-- `componentEdit` - When edit action is triggered
-- `componentDuplicate` - When component is duplicated
-- `componentDelete` - When component is deleted
-- `componentEditJS` - When Edit JS is triggered
+## Built-in code editors
 
-### Page Class
+EditorTs can render editors into your containers:
 
-Direct API for programmatic manipulation:
+- Default: `textarea` (zero deps)
+- Optional: `modern-monaco` (syntax highlighting)
 
-```typescript
-import { Page } from 'editorts';
+```ts
+const editor = init({
+  iframeId: 'preview-iframe',
+  data: pageData,
+  codeEditor: { provider: 'modern-monaco' },
+})
+```
 
-const page = new Page(jsonData);
+Notes:
+- `modern-monaco` is an optional peer dependency.
+- `typescript` is an optional peer dependency (used for TSX/JSX parsing).
 
-// Page methods
-page.getTitle();
-page.setTitle(title);
-page.getHTML();
-page.getCSS();
-page.toJSON();
-page.clone();
+## Component conversions
 
-// Managers
-page.components.findById(id);
-page.components.updateComponent(id, updates);
-page.styles.updateStyle(selector, properties);
-page.assets.getImages();
-page.toolbars.configureById(id, config);
-```
+### Components → HTML
 
-### ComponentManager
-
-```typescript
-page.components.find(query);
-page.components.findById(id);
-page.components.findByType(type);
-page.components.addComponent(component);
-page.components.removeComponent(id);
-page.components.updateComponent(id, updates);
-page.components.getAll();
-page.components.count();
+```ts
+const html = editor.page.components.toHTML()
 ```
 
-### StyleManager
+### HTML → Components
 
-```typescript
-page.styles.findBySelector(selector);
-page.styles.findByMedia(mediaText);
-page.styles.addStyle(style);
-page.styles.updateStyle(selector, properties);
-page.styles.removeBySelector(selector);
-page.styles.compileToCSS();
-page.styles.getAll();
+```ts
+// Requires DOM (browser). Server-side: inject an adapter or it will warn and no-op.
+editor.page.components.setFromHTML('<body><div id="root">Hello</div></body>')
 ```
 
-### AssetManager
+### Components → JSX/TSX
 
-```typescript
-page.assets.findByType(type);
-page.assets.getImages();
-page.assets.addAsset(asset);
-page.assets.removeAsset(src);
-page.assets.updateAsset(src, updates);
-page.assets.getAll();
+```ts
+const jsxSource = editor.page.components.toJSX({ pretty: true })
 ```
 
-### ToolbarManager
+`toJSX()` outputs React-style function components named from `attributes.id` when possible.
 
-```typescript
-page.toolbars.configureById(id, config);
-page.toolbars.configureByType(type, config);
-page.toolbars.configureByTag(tagName, config);
-page.toolbars.configureCustom(matcher, config);
-page.toolbars.getToolbarForComponent(component);
-page.toolbars.setGlobalDefault(config);
-```
+### JSX/TSX → Components
 
-## Examples
+```ts
+// Uses optional peer dependency `typescript`.
+await editor.page.components.setFromJSX(`
+export function Header() {
+  return <div id="header">Hello</div>
+}
+`)
+```
 
-### Basic Editor Setup
+## Server sync (Bun + Cloudflare)
 
-```typescript
-import { init } from 'editorts';
+EditorTs ships lightweight websocket utilities for server-side sync.
 
-const editor = init({
-  containerId: 'root',
-  data: pageData
-});
+### Bun server
 
-console.log('Components:', editor.page.components.count());
-```
+```ts
+import { createBunSyncServer, createSyncMessage } from 'editorts'
 
-### With Toolbar Configuration
+const server = createBunSyncServer({
+  port: 8787,
+  onSync: async (message) => {
+    console.log('received', message.payload)
+  },
+})
 
-```typescript
-const editor = init({
-  containerId: 'root',
-  data: pageData,
-  toolbars: {
-    byType: {
-      'custom-code': {
-        actions: [
-          { id: 'editJS', label: 'Edit Code', icon: '📜', enabled: true }
-        ]
-      }
-    }
-  }
-});
+// elsewhere, send a message
+const payload = createSyncMessage(pageData)
 ```
 
-### With Event Handlers
+### Cloudflare worker
 
-```typescript
-const editor = init({
-  containerId: 'root',
-  data: pageData,
-  onComponentSelect: (comp) => console.log('Selected:', comp),
-  onComponentDelete: (comp) => console.log('Deleted:', comp)
-});
-
-// Add more listeners after init
-editor.on('componentEdit', (component) => {
-  // Custom edit logic
-});
+```ts
+import { createCfSyncWorker } from 'editorts'
+
+export default createCfSyncWorker({
+  onSync: async (message) => {
+    console.log('received', message.payload)
+  },
+})
 ```
 
-### Programmatic Page Manipulation
+### Message helpers
 
-```typescript
-import { Page } from 'editorts';
+```ts
+import { createSyncMessage, parseSyncEnvelope } from 'editorts'
 
-const page = new Page(jsonData);
+const message = createSyncMessage(pageData)
+const parsed = parseSyncEnvelope(JSON.stringify(message))
+```
 
-// Find components
-const header = page.components.findById('header');
-const boxes = page.components.findByType('box');
+## AI provider (OpenCode)
 
-// Update styles
-page.styles.updateStyle('#header', {
-  'background-color': '#333',
-  'padding': '2rem'
-});
+Optional integration via `@opencode-ai/sdk`.
 
-// Manage assets
-const images = page.assets.getImages();
+```ts
+import { createOpencodeClient } from '@opencode-ai/sdk'
 
-// Export clean JSON
-const json = page.toJSON();
-```
+const editor = init({
+  iframeId: 'preview-iframe',
+  data: pageData,
+  aiProvider: {
+    provider: 'opencode',
+    mode: 'client',
+    baseUrl: 'http://localhost:4096',
 
-## Project Structure
+    // Optional: pass your own client
+    client: createOpencodeClient({ baseUrl: 'http://localhost:4096' }),
+  },
+})
 
-```
-editorts/
-├── src/
-│   ├── core/
-│   │   ├── init.ts              # Editor initialization
-│   │   ├── Page.ts              # Main Page class
-│   │   ├── ComponentManager.ts  # Component operations
-│   │   ├── StyleManager.ts      # Style operations
-│   │   ├── AssetManager.ts      # Asset operations
-│   │   └── ToolbarManager.ts    # Runtime toolbar config
-│   ├── styles/
-│   │   └── branding.css         # Editor branding
-│   ├── utils/
-│   │   ├── helpers.ts           # Utility functions
-│   │   └── toolbar.ts           # Toolbar utilities
-│   └── types.ts                 # Type definitions
-├── examples/
-│   ├── quickstart.ts            # Simple editor example
-│   ├── basic-usage.ts           # Library API examples
-│   └── toolbar-example.ts       # Toolbar configuration examples
-├── samples/
-│   └── page_template.json       # Sample page data
-├── index.html                   # Editor HTML template
-├── local-server.ts              # Simple Bun dev server
-├── index.ts                     # Main library exports
-└── AGENTS.md                    # Architecture principles
+// Later
+const client = await editor.ai?.getClient()
 ```
 
-## Development
+## Events
 
-```bash
-# Run the editor
-bun run dev
+The editor emits typed events:
 
-# Run examples
-bun run examples/basic-usage.ts
-bun run examples/toolbar-example.ts
+- `componentSelect`
+- `componentEdit`, `componentEditJS`
+- `componentDuplicate`, `componentDelete`
+- `componentReorder`
+- `pageEditCSS`, `pageEditJSON`
+- `pageSaved`, `pageLoaded`
 
-# Build
-bun build index.ts --outdir=dist
-```
+See `src/types.ts` for the full event map.
 
-## License
+## Development
 
-MIT
+```bash
+bun run build
+bun run test
+```
 
-## Contributing
+## Project map
 
-Contributions are welcome! Please read [AGENTS.md](./AGENTS.md) for architecture guidelines.
+- Core entry: `src/core/init.ts`
+- Page model: `src/core/Page.ts`
+- Data managers: `src/core/ComponentManager.ts`, `src/core/StyleManager.ts`, `src/core/AssetManager.ts`
+- Storage: `src/core/StorageManager.ts`
+- Demo: `index.html` + `examples/quickstart.ts`
+- Architecture + workflow: `AGENTS.md`