@noseberry/nbd-editor 1.0.0 → 1.0.1

package/README.md

@@ -1,6 +1,64 @@
 # @noseberry/nbd-editor
 
-A framework-agnostic, Gutenberg-style block editor by **Noseberry Private Limited**. Works with vanilla JavaScript, React, and Next.js out of the box.
+> 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**.
+
+Works seamlessly with **vanilla JavaScript**, **React**, and **Next.js**.
+
+### Why NBD Editor?
+
+- **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
+- **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
+- **Lightweight** — ~89 KB minified JS + ~25 KB CSS, zero runtime dependencies
+
+### How It Works
+
+```
+Install → Import → Mount → Done
+
+1. npm install @noseberry/nbd-editor
+2. import { NBDEditor } from '@noseberry/nbd-editor'
+3. new NBDEditor('#editor', { onSave: (data) => save(data) })
+```
+
+The editor manages its own state internally. You interact with it through callbacks (`onChange`, `onSave`) or imperatively via the API (`getData()`, `setData()`, `toHTML()`). In React, use the `ReactNBDEditor` component with or without a ref.
+
+### Usage Flow
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Your App                         │
+│                                                     │
+│   ┌─────────────┐        ┌──────────────────────┐  │
+│   │  Initialize  │───────▶│     NBD Editor        │  │
+│   │  with config │        │                      │  │
+│   └─────────────┘        │  ┌──────────────────┐ │  │
+│                           │  │  User writes     │ │  │
+│   ┌─────────────┐        │  │  content using    │ │  │
+│   │  onChange()  │◀───────│  │  blocks, toolbar, │ │  │
+│   │  callback    │        │  │  slash commands   │ │  │
+│   └─────────────┘        │  └──────────────────┘ │  │
+│                           │                      │  │
+│   ┌─────────────┐        │  ┌──────────────────┐ │  │
+│   │  onSave()   │◀───────│  │  Ctrl+S or       │ │  │
+│   │  callback    │        │  │  save() API call │ │  │
+│   └──────┬──────┘        │  └──────────────────┘ │  │
+│          │                └──────────────────────┘  │
+│          ▼                                          │
+│   ┌─────────────┐                                   │
+│   │  Store in   │   data = { content: '<p>...</p>' }│
+│   │  database   │                                   │
+│   └─────────────┘                                   │
+│                                                     │
+│   To restore: editor.setData({ content: savedHTML })│
+└─────────────────────────────────────────────────────┘
+```
 
 ---
 
@@ -28,31 +86,12 @@ A framework-agnostic, Gutenberg-style block editor by **Noseberry Private Limite
 
 ## Installation
 
-This is a **private** repository. You need GitHub access to install it.
-
-**SSH (recommended):**
-
 ```bash
-npm install git+ssh://git@github.com/Noseberry-Private-Limited/NBD-editor.git
+npm install @noseberry/nbd-editor
 # or
-yarn add git+ssh://git@github.com/Noseberry-Private-Limited/NBD-editor.git
+yarn add @noseberry/nbd-editor
 # or
-pnpm add git+ssh://git@github.com/Noseberry-Private-Limited/NBD-editor.git
-```
-
-> Requires an SSH key linked to your GitHub account.
-
-**HTTPS with personal access token:**
-
-```bash
-npm install git+https://<YOUR_GITHUB_TOKEN>@github.com/Noseberry-Private-Limited/NBD-editor.git
-```
-
-**Pin a specific branch or tag:**
-
-```bash
-npm install git+ssh://git@github.com/Noseberry-Private-Limited/NBD-editor.git#main
-npm install git+ssh://git@github.com/Noseberry-Private-Limited/NBD-editor.git#v1.0.0
+pnpm add @noseberry/nbd-editor
 ```
 
 **Important — always import the CSS:**

package/dist/nbd-editor.d.ts

@@ -0,0 +1,223 @@
+// Type definitions for @noseberry/nbd-editor
+// Noseberry Private Limited
+
+import * as React from 'react';
+
+/* ===== EventEmitter ===== */
+
+export class EventEmitter {
+  on(event: string, fn: (...args: any[]) => void): () => void;
+  off(event: string, fn: (...args: any[]) => void): void;
+  emit(event: string, ...args: any[]): void;
+  once(event: string, fn: (...args: any[]) => void): void;
+}
+
+/* ===== Editor Data ===== */
+
+export interface EditorData {
+  content: string;
+}
+
+export interface Block {
+  id: string;
+  type: string;
+  content: string;
+  attrs: Record<string, any>;
+}
+
+export interface UploadResult {
+  url: string;
+  id?: string;
+}
+
+/* ===== NBDEditor Options ===== */
+
+export interface NBDEditorOptions {
+  /** Site name displayed in the header. Default: `'My Site'` */
+  siteName?: string;
+  /** Author name displayed in the editor. Default: `'Admin'` */
+  authorName?: string;
+  /** Initial HTML content to load. */
+  content?: string | null;
+  /** Placeholder text for empty blocks. Default: `'Start writing...'` */
+  placeholder?: string;
+  /** Show/hide the bottom status bar. Default: `true` */
+  showStatusBar?: boolean;
+  /** Show/hide the right settings panel. Default: `false` */
+  showSettingsPanel?: boolean;
+  /** Show/hide header action buttons. Default: `false` */
+  showHeaderActions?: boolean;
+  /** Auto-save interval in milliseconds. Set `0` to disable. Default: `30000` */
+  autoSaveInterval?: number;
+  /** Custom file upload handler. Return `{ url, id? }`. */
+  uploadHandler?: ((file: File) => Promise<UploadResult>) | null;
+  /** Max upload file size in bytes. Default: `10485760` (10 MB) */
+  maxFileSize?: number;
+  /** Controls video/audio source chooser. Return `'url'` or `'upload'`. */
+  onChooseMediaSource?: ((type: 'video' | 'audio') => 'url' | 'upload') | null;
+  /** Called on every content change. */
+  onChange?: ((data: EditorData) => void) | null;
+  /** Called when save is triggered. */
+  onSave?: ((data: EditorData) => void) | null;
+  /** Called when publish is triggered. */
+  onPublish?: ((data: EditorData) => void) | null;
+}
+
+/* ===== NBDEditor ===== */
+
+export class NBDEditor extends EventEmitter {
+  constructor(selector: string | HTMLElement, options?: NBDEditorOptions);
+
+  /** Get the full editor content. */
+  getData(): EditorData;
+  /** Set editor content. Accepts `{ content: '...' }` or a plain string. */
+  setData(data: EditorData | string): void;
+  /** Export all blocks as a merged HTML string. */
+  toHTML(): string;
+  /** Trigger save — fires `onSave` callback and `'save'` event. */
+  save(): void;
+  /** Trigger publish — fires `onPublish` callback and `'publish'` event. */
+  publish(): void;
+  /** Undo the last action. Returns `true` if undo was performed. */
+  undo(opts?: { preferNative?: boolean }): boolean;
+  /** Redo the last undone action. Returns `true` if redo was performed. */
+  redo(opts?: { preferNative?: boolean }): boolean;
+  /** Tear down the editor and clean up listeners. */
+  destroy(): void;
+  /** Get the current title value. */
+  getTitle(): string;
+  /** Set the title. */
+  setTitle(title: string): void;
+  /** Select a block by its ID. */
+  selectBlock(id: string): void;
+  /** Select and focus a block. */
+  focusBlock(id: string): void;
+  /** Insert a new block after the selected block. */
+  insertBlockAtSelection(type: string, data?: Partial<Block>): Block;
+  /** Append a new block at the end. */
+  insertBlockAtEnd(type: string, data?: Partial<Block>): Block;
+  /** Toggle a block between visual and raw HTML mode. */
+  toggleBlockHtmlMode(blockId?: string): void;
+  /** Open the HTML editor modal for a block. */
+  openBlockHtmlEditor(blockId?: string): void;
+}
+
+/* ===== ReactNBDEditor ===== */
+
+export interface ReactNBDEditorProps extends NBDEditorOptions {
+  /** CSS class for the wrapper div. */
+  className?: string;
+  /** Inline styles for the wrapper div. */
+  style?: React.CSSProperties;
+  /** Called once the editor instance is initialized. */
+  onReady?: (editor: NBDEditor) => void;
+}
+
+export interface ReactNBDEditorRef {
+  /** Returns the underlying NBDEditor instance. */
+  getInstance(): NBDEditor | null;
+  /** Returns `{ content: '<p>...</p>' }`. */
+  getData(): EditorData | undefined;
+  /** Sets content — accepts `{ content: '...' }`. */
+  setData(data: EditorData): void;
+  /** Returns the raw HTML string. */
+  toHTML(): string | undefined;
+  /** Triggers save (fires `onSave` callback). */
+  save(): void;
+  /** Triggers publish (fires `onPublish` callback). */
+  publish(): void;
+  /** Undo last action. */
+  undo(opts?: { preferNative?: boolean }): void;
+  /** Redo last undone action. */
+  redo(opts?: { preferNative?: boolean }): void;
+  /** Destroys the editor instance and cleans up. */
+  destroy(): void;
+}
+
+export const ReactNBDEditor: React.ForwardRefExoticComponent<
+  ReactNBDEditorProps & React.RefAttributes<ReactNBDEditorRef>
+> | null;
+
+/* ===== BlockManager ===== */
+
+export class BlockManager extends EventEmitter {
+  blocks: Block[];
+  addBlock(type: string, data?: Partial<Block>, afterId?: string | null): Block;
+  removeBlock(id: string): Block | undefined;
+  updateBlock(id: string, patch: Partial<Block>): void;
+  changeBlockType(id: string, newType: string): void;
+  moveBlock(id: string, direction: number): void;
+  duplicateBlock(id: string): Block | undefined;
+  getBlock(id: string): Block | null;
+  getIndex(id: string): number;
+  getPrevBlock(id: string): Block | null;
+  getNextBlock(id: string): Block | null;
+  toJSON(): Block[];
+  fromJSON(data: Block[]): void;
+  toHTML(): string;
+  blockToHTML(block: Block): string;
+  saveSnapshot(): void;
+  undo(): boolean;
+  redo(): boolean;
+  getWordCount(): number;
+  getCharCount(): number;
+}
+
+/* ===== MediaUploader ===== */
+
+export interface MediaUploaderOptions {
+  uploadHandler?: ((file: File) => Promise<UploadResult>) | null;
+  maxFileSize?: number;
+  allowedImageTypes?: string[];
+  allowedVideoTypes?: string[];
+  allowedAudioTypes?: string[];
+}
+
+export interface ProcessedFile {
+  localUrl?: string;
+  remoteUrl?: string;
+  file: File;
+  id?: string;
+  error?: string;
+}
+
+export class MediaUploader extends EventEmitter {
+  constructor(options?: MediaUploaderOptions);
+  openFilePicker(accept?: string, multiple?: boolean): Promise<File[]>;
+  processFile(file: File): Promise<ProcessedFile>;
+  processFiles(files: File[]): Promise<ProcessedFile[]>;
+  handlePaste(clipboardData: DataTransfer): Promise<ProcessedFile[] | null>;
+  handleDrop(dataTransfer: DataTransfer): Promise<ProcessedFile[] | null>;
+  getMediaType(file: File): 'image' | 'video' | 'audio' | 'file';
+}
+
+/* ===== DragDrop ===== */
+
+export class DragDrop extends EventEmitter {
+  constructor(container: HTMLElement);
+  enable(): void;
+  disable(): void;
+  initDrag(handleEl: HTMLElement, wrapperEl: HTMLElement, blockId: string): void;
+}
+
+/* ===== Block Registry ===== */
+
+export interface BlockTypeDefinition {
+  label: string;
+  description: string;
+  icon: string;
+  category: string;
+  hasContent: boolean;
+  contentTag?: string;
+  placeholder?: string;
+  className?: string;
+  isMedia?: boolean;
+}
+
+export const BLOCK_TYPES: Record<string, BlockTypeDefinition>;
+
+export const CATEGORIES: Array<{ id: string; label: string }>;
+
+export function getBlocksByCategory(catId: string): Array<{ type: string } & BlockTypeDefinition>;
+
+export function searchBlocks(query: string): Array<{ type: string } & BlockTypeDefinition>;

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@noseberry/nbd-editor",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Nbd Editor: a framework-agnostic rich content editor by Noseberry Private Limited.",
   "main": "dist/nbd-editor.cjs.js",
   "module": "dist/nbd-editor.esm.js",
   "browser": "dist/nbd-editor.umd.js",
+  "types": "dist/nbd-editor.d.ts",
   "style": "dist/nbd-editor.css",
   "exports": {
     ".": {
+      "types": "./dist/nbd-editor.d.ts",
       "import": "./dist/nbd-editor.esm.js",
       "require": "./dist/nbd-editor.cjs.js",
       "default": "./dist/nbd-editor.cjs.js"