@noseberry/nbd-editor 1.0.1 → 1.1.0

package/README.md

@@ -1,8 +1,8 @@
-# @noseberry/nbd-editor
+# NBD Editor
 
 > We'd love to hear from you! If you run into any bugs, have feature requests, or just want to share how you're using NBD Editor, please [open an issue](https://github.com/Noseberry-Private-Limited/NBD-editor/issues). Your feedback helps us make NBD Editor better for everyone.
 
-A powerful, framework-agnostic block editor built by **Noseberry Private Limited**. Inspired by WordPress Gutenberg, NBD Editor gives you a clean, modern content editing experience with drag-and-drop blocks, rich text formatting, media uploads, and a slash command menu — all in a single lightweight package with **zero production dependencies**.
+A powerful, framework-agnostic block editor. NBD Editor gives you a clean, modern content editing experience with drag-and-drop blocks, rich text formatting, media uploads, and a slash command menu — all in a single lightweight package with **zero production dependencies**.
 
 Works seamlessly with **vanilla JavaScript**, **React**, and **Next.js**.
 
@@ -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,6 +77,7 @@ 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)
 - [Build from Source](#build-from-source)
@@ -253,21 +254,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>');
 
-// GOOD — use content only for initial value or external resets
-const [initialContent] = useState('<p>Hello</p>');
-<ReactNBDEditor content={initialContent} onChange={(d) => console.log(d)} />
+  return (
+    <ReactNBDEditor
+      content={content}
+      onChange={(data) => setContent(data.content)}
+      siteName="My App"
+      authorName="Harshit"
+    />
+  );
+}
 ```
 
-If you need to update the editor's content programmatically from the parent, use the ref:
+For heavy content or frequent updates, use `debounceMs` to limit how often `onChange` fires:
+
+```jsx
+<ReactNBDEditor
+  content={content}
+  onChange={(data) => setContent(data.content)}
+  debounceMs={300}  // fires onChange at most every 300ms
+/>
+```
+
+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 +430,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 +541,47 @@ 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-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 |
@@ -557,8 +619,6 @@ editor.on('input', (block) => { });     // Block content input
 ## Build from Source
 
 ```bash
-git clone git@github.com:Noseberry-Private-Limited/NBD-editor.git
-cd NBD-editor
 npm install
 npm run build
 ```