@noseberry/nbd-editor 1.0.2 → 1.1.1

package/README.md

@@ -11,7 +11,7 @@ Works seamlessly with **vanilla JavaScript**, **React**, and **Next.js**.
 - **Drop-in ready** — one import, one line of code, and you have a full block editor
 - **Framework agnostic** — works with any frontend stack; optional React wrapper included
 - **20+ block types** — paragraphs, headings, images, video, audio, tables, columns, code, embeds, and more
-- **Rich editing** — inline formatting toolbar, slash commands (`/`), drag-and-drop reordering, undo/redo
+- **Rich editing** — inline formatting toolbar (draggable), slash commands (`/`), drag-and-drop reordering, undo/redo
 - **Media support** — upload images, video, audio, and files with drag-and-drop or file picker
 - **Simple data model** — `getData()` returns `{ content: '<p>...</p>' }` — just store one HTML string
 - **TypeScript support** — full type definitions included for autocomplete and type safety
@@ -77,8 +77,10 @@ The editor manages its own state internally. You interact with it through callba
 - [Data Contract](#data-contract)
 - [Block Types](#block-types)
 - [Media Handling](#media-handling)
+- [Theming](#theming)
 - [Keyboard Shortcuts](#keyboard-shortcuts)
 - [Events](#events)
+- [Changelog](#changelog)
 - [Build from Source](#build-from-source)
 - [License](#license)
 
@@ -253,21 +255,40 @@ export default function EditorPage() {
 | `redo(opts?)` | Redo last undone action |
 | `destroy()` | Destroys the editor instance and cleans up |
 
-### Important: Avoid Re-controlling Content
+### Controlled Mode (like React Quill)
 
-The `content` prop is treated as an **initial/external value**. Do NOT bind it to state that updates on every keystroke:
+NBD Editor supports the controlled component pattern — bind `content` to state and update it via `onChange`:
 
 ```jsx
-// BAD — causes infinite re-render loop
-const [content, setContent] = useState('<p>Hello</p>');
-<ReactNBDEditor content={content} onChange={(d) => setContent(d.content)} />
+import React, { useState } from 'react';
+import { ReactNBDEditor } from '@noseberry/nbd-editor';
+import '@noseberry/nbd-editor/style.css';
+
+export default function EditorPage() {
+  const [content, setContent] = useState('<p>Hello World</p>');
+
+  return (
+    <ReactNBDEditor
+      content={content}
+      onChange={(data) => setContent(data.content)}
+      siteName="My App"
+      authorName="Harshit"
+    />
+  );
+}
+```
+
+For heavy content or frequent updates, use `debounceMs` to limit how often `onChange` fires:
 
-// GOOD — use content only for initial value or external resets
-const [initialContent] = useState('<p>Hello</p>');
-<ReactNBDEditor content={initialContent} onChange={(d) => console.log(d)} />
+```jsx
+<ReactNBDEditor
+  content={content}
+  onChange={(data) => setContent(data.content)}
+  debounceMs={300}  // fires onChange at most every 300ms
+/>
 ```
 
-If you need to update the editor's content programmatically from the parent, use the ref:
+You can also use `content` as a one-time initial value and use the ref for everything else:
 
 ```jsx
 editorRef.current?.setData({ content: '<p>New content from server</p>' });
@@ -410,6 +431,7 @@ Pass these as the second argument to `new NBDEditor(selector, options)` or as pr
 | `className` | `string` | CSS class for the wrapper `div` |
 | `style` | `object` | Inline styles for the wrapper `div` |
 | `onReady` | `(editor) => void` | Called once the editor instance is initialized |
+| `debounceMs` | `number` | Debounce delay (ms) for `onChange` — reduces re-renders in controlled mode |
 
 ---
 
@@ -520,6 +542,49 @@ Files exceeding `maxFileSize` are blocked from uploading. Users can also drag an
 
 ---
 
+## Theming
+
+NBD Editor exposes a set of CSS custom properties on `.fe-root` that you can override to match your brand. Set them on `.fe-root` or any ancestor element:
+
+```css
+.fe-root {
+  --fe-blue: #8b5cf6;          /* accent / primary colour */
+  --fe-blue-hover: #7c3aed;
+  --fe-bg: #fafafa;             /* editor shell background */
+  --fe-canvas-bg: #f9fafb;     /* writing canvas background */
+  --fe-text: #111827;           /* primary text colour */
+  --fe-font: 'Inter', sans-serif;
+  --fe-radius: 8px;             /* border radius */
+  --fe-content-font-size: 16px; /* body text size inside blocks */
+  --fe-content-line-height: 1.7;
+}
+```
+
+All available tokens:
+
+| Variable | Default | Description |
+|---|---|---|
+| `--fe-blue` | `#3b82f6` | Accent / primary colour |
+| `--fe-blue-hover` | `#2563eb` | Accent hover state |
+| `--fe-text` | `#1e1e1e` | Primary text colour |
+| `--fe-light-text` | `#6b7280` | Secondary / muted text |
+| `--fe-bg` | `#f8f9fb` | Editor shell background |
+| `--fe-canvas-bg` | `#ffffff` | Writing canvas background |
+| `--fe-hover-bg` | `#f3f4f6` | Hover / subtle highlight |
+| `--fe-border` | `#e2e4e9` | Border colour |
+| `--fe-success` | `#10b981` | Success state colour |
+| `--fe-danger` | `#ef4444` | Destructive / error colour |
+| `--fe-radius` | `6px` | Border radius |
+| `--fe-font` | system-ui stack | Font family |
+| `--fe-shadow-sm` | subtle shadow | Subtle shadow — used on cards and panels |
+| `--fe-shadow-md` | medium shadow | Medium shadow — used on dropdowns and modals |
+| `--fe-header-height` | `60px` | Height of the sticky header bar |
+| `--fe-status-bar-height` | `32px` | Height of the bottom status bar |
+| `--fe-content-font-size` | `15px` | Body text size inside blocks |
+| `--fe-content-line-height` | `1.65` | Body line height inside blocks |
+
+---
+
 ## Keyboard Shortcuts
 
 | Shortcut | Action |
@@ -554,6 +619,22 @@ editor.on('input', (block) => { });     // Block content input
 
 ---
 
+## Changelog
+
+### v1.1.1
+
+**Bug fixes**
+
+- **List blocks** — bullet and ordered-list blocks now initialize with the correct `<ul><li>` / `<ol><li>` structure. Previously, empty list blocks rendered a bare `<br>`, which caused broken list editing behavior on first interaction.
+- **Focus reliability** — block focus and caret positioning after clicking a block now uses double `requestAnimationFrame` instead of `setTimeout(0)`, preventing occasional cases where the caret landed in the wrong position before the DOM had fully painted.
+
+**Improvements**
+
+- **Click-to-deselect** — clicking anywhere on the editor canvas outside a block now deselects the active block and returns the editor to its idle state.
+- **Theme tokens** — two new elevation CSS variables are available: `--fe-shadow-sm` and `--fe-shadow-md`. All CSS variable defaults have been refreshed to a cleaner, more neutral palette (new accent `#3b82f6`, updated greys, semantic colours, and layout tokens).
+
+---
+
 ## Build from Source
 
 ```bash