oneuxi-editor 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,521 @@
+# oneuxi-editor
+
+A production-ready rich text editor for React applications, built on the Lexical engine. Designed for SaaS products, internal tools, and content platforms that need a dependable editor without the weight of legacy alternatives.
+
+[![npm version](https://img.shields.io/npm/v/oneuxi-editor.svg)](https://www.npmjs.com/package/oneuxi-editor)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Telegram](https://img.shields.io/badge/Telegram-Join%20Community-2CA5E0?logo=telegram)](https://t.me/thedebuglab)
+
+---
+
+## Why oneuxi-editor
+
+Most rich text solutions either carry significant legacy weight or are overly opinionated about their design system. `oneuxi-editor` is built to be dropped into any React project with a single import, minimal configuration, and a clean public API. It is SSR-safe, fully tree-shakeable, and ships without any bundled peer dependencies beyond Lexical itself.
+
+It works independently of the `oneuxi` UI component library. If you use `oneuxi` elsewhere, they share a consistent design language. If you do not, `oneuxi-editor` stands entirely on its own.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+- [Controlled and Uncontrolled Modes](#controlled-and-uncontrolled-modes)
+- [Output Formats](#output-formats)
+- [Toolbar Configuration](#toolbar-configuration)
+- [Themes](#themes)
+- [Editor Height](#editor-height)
+- [Bubble Toolbar](#bubble-toolbar)
+- [HTML Source Mode](#html-source-mode)
+- [Images and File Uploads](#images-and-file-uploads)
+- [Tables](#tables)
+- [Code Blocks](#code-blocks)
+- [Mentions](#mentions)
+- [Slash Commands](#slash-commands)
+- [Paste Cleanup](#paste-cleanup)
+- [Security and Sanitization](#security-and-sanitization)
+- [SSR and Next.js](#ssr-and-nextjs)
+- [Imperative API](#imperative-api)
+- [Props Reference](#props-reference)
+- [Accessibility](#accessibility)
+- [Browser Support](#browser-support)
+- [Bundle Size](#bundle-size)
+- [AI Features — Coming Soon](#ai-features--coming-soon)
+- [Community & Support](#community--support)
+
+---
+
+## Installation
+
+```bash
+npm install oneuxi-editor
+```
+
+Import the stylesheet once at your application root:
+
+```tsx
+import "oneuxi-editor/styles.css"
+```
+
+---
+
+## Basic Usage
+
+The simplest form of the editor requires no configuration. It renders with a default toolbar and outputs HTML on every change.
+
+```tsx
+import { Editor } from "oneuxi-editor"
+import "oneuxi-editor/styles.css"
+
+export default function App() {
+  return (
+    <Editor
+      placeholder="Start writing..."
+      onChange={(html) => console.log(html)}
+    />
+  )
+}
+```
+
+---
+
+## Controlled and Uncontrolled Modes
+
+**Controlled** — pass `value` and `onChange` to keep the content in sync with your state. Useful for forms, autosave, and live preview panels.
+
+```tsx
+import { useState } from "react"
+import { Editor } from "oneuxi-editor"
+
+export default function ControlledEditor() {
+  const [html, setHtml] = useState("<p>Initial content</p>")
+
+  return <Editor value={html} onChange={setHtml} />
+}
+```
+
+**Uncontrolled** — pass `defaultValue` to set initial content without managing state. Useful for simple forms where you only need the final value on submit.
+
+```tsx
+import { useRef } from "react"
+import { Editor } from "oneuxi-editor"
+import type { EditorRef } from "oneuxi-editor"
+
+export default function UncontrolledForm() {
+  const editorRef = useRef<EditorRef>(null)
+
+  const handleSubmit = () => {
+    const html = editorRef.current?.getHTML()
+    console.log(html)
+  }
+
+  return (
+    <>
+      <Editor ref={editorRef} defaultValue="<p>Draft</p>" />
+      <button onClick={handleSubmit}>Submit</button>
+    </>
+  )
+}
+```
+
+---
+
+## Output Formats
+
+The editor supports three output formats, controlled by the `output` prop.
+
+**HTML** (default) — returns sanitized HTML as a string.
+
+```tsx
+<Editor output="html" onChange={(html) => console.log(html)} />
+```
+
+**JSON** — returns the Lexical editor state as a JSON string. Useful for round-trip serialization.
+
+```tsx
+<Editor
+  output="json"
+  onChange={(json) => {
+    const state = JSON.parse(json)
+    console.log(state)
+  }}
+/>
+```
+
+**Text** — returns plain text with all markup stripped.
+
+```tsx
+<Editor output="text" onChange={(text) => console.log(text)} />
+```
+
+---
+
+## Toolbar Configuration
+
+Pass an array of toolbar item names to control which controls are shown and in what order. Use `"|"` as a separator.
+
+```tsx
+<Editor
+  toolbar={[
+    "undo", "redo", "|",
+    "heading", "|",
+    "bold", "italic", "underline", "strike", "|",
+    "align", "|",
+    "bulletList", "orderedList", "checkList", "|",
+    "link", "image", "table", "codeBlock", "blockquote", "hr", "|",
+    "sourceMode", "findReplace", "fullscreen"
+  ]}
+/>
+```
+
+Available items: `undo`, `redo`, `heading`, `bold`, `italic`, `underline`, `strike`, `code`, `subscript`, `superscript`, `clearFormatting`, `align`, `bulletList`, `orderedList`, `checkList`, `indent`, `outdent`, `link`, `image`, `table`, `codeBlock`, `blockquote`, `hr`, `sourceMode`, `findReplace`, `fullscreen`.
+
+To render without any toolbar (headless mode):
+
+```tsx
+<Editor toolbar={false} bubbleToolbar={false} />
+```
+
+You can also insert custom React components directly into the toolbar array:
+
+```tsx
+import { WordCountDisplay } from "./WordCountDisplay"
+
+<Editor toolbar={["bold", "italic", WordCountDisplay]} />
+```
+
+---
+
+## Themes
+
+Three built-in theme modes are available. The editor respects your OS preference when set to `"system"`.
+
+```tsx
+<Editor theme="light" />
+<Editor theme="dark" />
+<Editor theme="system" />  {/* follows OS dark mode setting */}
+```
+
+For brand-specific styling, pass a theme object with any combination of CSS custom property overrides:
+
+```tsx
+<Editor
+  theme={{
+    mode: "dark",
+    primary: "#7c3aed",
+    background: "#0f172a",
+    surface: "#1e293b",
+    border: "#334155",
+    radius: "12px",
+    fontFamily: "'Inter', sans-serif",
+    fontSize: "15px"
+  }}
+/>
+```
+
+All theme values map to scoped CSS custom properties (`--oue-*`) applied inline on the editor container. This means multiple editors on the same page can have different themes without conflicting.
+
+---
+
+## Editor Height
+
+By default, the editor grows with its content. To constrain the height and enable scrolling within the content area, pass a `height` prop. The toolbar remains pinned at the top while the content area scrolls independently.
+
+```tsx
+{/* Fixed pixel height */}
+<Editor height={400} />
+
+{/* CSS string value */}
+<Editor height="50vh" />
+
+{/* Minimum height with auto-grow */}
+<Editor minHeight={200} />
+```
+
+Both `height` and `minHeight` accept numbers (interpreted as pixels) or any valid CSS length string.
+
+---
+
+## Bubble Toolbar
+
+A contextual toolbar that appears above selected text. Configure the items it shows:
+
+```tsx
+<Editor bubbleToolbar={["bold", "italic", "underline", "strike", "link"]} />
+```
+
+Disable it entirely:
+
+```tsx
+<Editor bubbleToolbar={false} />
+```
+
+---
+
+## HTML Source Mode
+
+Toggle between the visual editor and raw HTML source:
+
+```tsx
+<Editor sourceMode />
+```
+
+The `sourceMode` toolbar button can also be included in the toolbar config to let users switch at runtime. Changes in either view stay in sync.
+
+---
+
+## Images and File Uploads
+
+Images can be inserted via URL or through a custom upload handler. The upload handler receives a `File` object and must return a Promise resolving to `{ src, alt?, width?, height? }`.
+
+```tsx
+import { Editor, ImageExtension } from "oneuxi-editor"
+
+const imageExtension = ImageExtension.configure({
+  upload: async (file: File) => {
+    const form = new FormData()
+    form.append("file", file)
+    const res = await fetch("/api/upload", { method: "POST", body: form })
+    const data = await res.json()
+    return { src: data.url, alt: file.name }
+  },
+  maxSize: 5 * 1024 * 1024,
+  allowedTypes: ["image/jpeg", "image/png", "image/webp", "image/gif"]
+})
+
+<Editor extensions={[imageExtension]} />
+```
+
+---
+
+## Tables
+
+Insert and edit HTML tables. Cells support all standard formatting (bold, links, lists).
+
+```tsx
+import { Editor } from "oneuxi-editor"
+
+{/* Tables are included in the default editor — use the toolbar button */}
+<Editor toolbar={["table"]} />
+```
+
+---
+
+## Code Blocks
+
+Syntax-highlighted code blocks are included out of the box. Use the `codeBlock` toolbar item to insert one, or type a fenced code block in source mode.
+
+```tsx
+<Editor toolbar={["codeBlock"]} />
+```
+
+---
+
+## Mentions
+
+Trigger user mentions with `@`. Provide a search function that returns a list of users.
+
+```tsx
+import { Editor, MentionExtension } from "oneuxi-editor"
+
+const mentionExt = MentionExtension.configure({
+  trigger: "@",
+  search: async (query: string) => {
+    const res = await fetch(`/api/users?q=${query}`)
+    return res.json() // [{ id, name, username, avatar? }]
+  }
+})
+
+<Editor extensions={[mentionExt]} />
+```
+
+---
+
+## Slash Commands
+
+Type `/` to open a command menu. Register custom commands or use the built-in set.
+
+```tsx
+import { Editor, SlashCommandExtension } from "oneuxi-editor"
+
+<Editor extensions={[SlashCommandExtension]} />
+```
+
+---
+
+## Paste Cleanup
+
+Pasting from external office suites or rich document sources is handled automatically. The editor strips proprietary markup (`MsoNormal`, `mso-*`, inline styled wrapper spans) while preserving the semantic structure: headings, lists, bold, italic, links, and tables come through intact.
+
+No configuration is required. Paste cleanup runs silently on every paste event.
+
+---
+
+## Security and Sanitization
+
+All HTML imported or pasted into the editor is sanitized by DOMPurify before parsing. The following are blocked unconditionally:
+
+- `<script>` tags and inline event handlers (`onerror`, `onload`, etc.)
+- `javascript:` URLs in `<a href>` attributes
+- `<iframe>`, `<object>`, `<embed>`, and similar embeds
+
+You can extend or restrict the allowed tag set via the `html` prop:
+
+```tsx
+<Editor
+  html={{
+    allowedTags: ["p", "strong", "em", "a", "ul", "ol", "li", "h1", "h2", "h3"],
+    allowedAttributes: {
+      "a": ["href", "target", "rel"]
+    }
+  }}
+/>
+```
+
+---
+
+## SSR and Next.js
+
+The editor is SSR-safe. It does not access `window`, `document`, or the DOM at module import time. System theme detection uses `useSyncExternalStore` with a stable server snapshot to prevent hydration mismatches in Next.js App Router and Pages Router.
+
+No dynamic import wrappers or `ssr: false` configuration is needed.
+
+---
+
+## Imperative API
+
+Use a `ref` to call editor methods programmatically from outside the component.
+
+```tsx
+import { useRef } from "react"
+import { Editor } from "oneuxi-editor"
+import type { EditorRef } from "oneuxi-editor"
+
+function MyPage() {
+  const editorRef = useRef<EditorRef>(null)
+
+  return (
+    <>
+      <Editor ref={editorRef} />
+      <button onClick={() => editorRef.current?.clear()}>Clear</button>
+      <button onClick={() => console.log(editorRef.current?.getHTML())}>
+        Get HTML
+      </button>
+    </>
+  )
+}
+```
+
+Available methods:
+
+| Method | Description |
+|--------|-------------|
+| `focus()` | Focus the editor |
+| `blur()` | Remove focus from the editor |
+| `clear()` | Clear all content |
+| `getHTML()` | Return current content as HTML string |
+| `setHTML(html)` | Replace content with the provided HTML |
+| `getText()` | Return plain text content |
+| `getJSON()` | Return Lexical editor state as a JSON object |
+| `setJSON(json)` | Replace content from a Lexical state object |
+| `isEmpty()` | Return true if the editor has no content |
+| `isDirty()` | Return true if content has changed since last clean mark |
+| `markClean()` | Reset the dirty state |
+| `undo()` | Undo the last change |
+| `redo()` | Redo the last undone change |
+
+---
+
+## Props Reference
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | — | Controlled HTML content |
+| `defaultValue` | `string` | — | Initial uncontrolled content |
+| `output` | `"html" \| "json" \| "text"` | `"html"` | Format of onChange output |
+| `placeholder` | `string` | `"Start writing..."` | Placeholder text |
+| `readOnly` | `boolean` | `false` | Disable all editing |
+| `disabled` | `boolean` | `false` | Disable and apply disabled styling |
+| `theme` | `"light" \| "dark" \| "system" \| ThemeObject` | `"system"` | Editor color theme |
+| `height` | `string \| number` | — | Fixed editor height; enables scrolling |
+| `minHeight` | `string \| number` | — | Minimum editor height |
+| `toolbar` | `ToolbarItem[] \| false` | default set | Toolbar items or false to hide |
+| `bubbleToolbar` | `ToolbarItem[] \| false` | default set | Bubble toolbar items |
+| `sourceMode` | `boolean` | `false` | Start in HTML source mode |
+| `fullscreen` | `boolean` | `false` | Start in fullscreen mode |
+| `characterCount` | `boolean` | `false` | Show character count in footer |
+| `wordCount` | `boolean` | `false` | Show word count in footer |
+| `maxLength` | `number` | — | Maximum character limit |
+| `extensions` | `EditorExtension[]` | — | Custom or built-in extensions |
+| `preset` | `"basic" \| "full"` | — | Load a predefined extension set |
+| `html` | `HTMLPolicy` | — | DOMPurify allow-list configuration |
+| `autosave` | `AutosaveConfig` | — | Autosave callback and debounce delay |
+| `icons` | `CustomIconMap` | — | Override default toolbar icons |
+| `onChange` | `(output: string) => void` | — | Fires on every content change |
+| `onUpdate` | `(update: EditorUpdate) => void` | — | Full update object with html, text, json |
+| `onError` | `(error: Error) => void` | — | Lexical runtime error handler |
+| `onDirtyChange` | `(isDirty: boolean) => void` | — | Fires when dirty state changes |
+| `onCharacterCountChange` | `(count: number) => void` | — | Fires on character count change |
+
+---
+
+## Accessibility
+
+The toolbar renders with `role="toolbar"` and `aria-label` attributes on every control. Interactive elements have unique, descriptive `aria-label` values for screen reader compatibility. Keyboard navigation within the editor follows standard `contenteditable` conventions.
+
+---
+
+## Browser Support
+
+The editor targets the last two stable releases of:
+
+- Chrome and Edge
+- Firefox
+- Safari
+- Mobile Chrome and Safari
+
+---
+
+## Bundle Size
+
+The editor ships as separate ESM and CJS builds with full source maps. Lexical itself is a peer dependency and is not included in these figures.
+
+| Output | Raw | Gzipped |
+|--------|-----|---------|
+| ESM (`index.mjs`) | 75.9 KB | 15.2 KB |
+| CJS (`index.js`) | 85.0 KB | 15.8 KB |
+| CSS (`styles.css`) | 10.0 KB | 2.4 KB |
+
+Extensions that are not imported are not included in your production bundle.
+
+---
+
+## AI Features — Coming Soon
+
+The next phase of `oneuxi-editor` introduces a set of AI-assisted writing capabilities designed to integrate directly into the editing experience. These features will work with any OpenAI-compatible API endpoint and will require no changes to your existing editor integration.
+
+Planned capabilities include:
+
+**Inline completions** — The editor will offer sentence and paragraph completions as you type, accepting them with a single key.
+
+**Selection-based actions** — Selecting text will expose actions to rephrase, expand, summarize, simplify, or change tone, inline without opening a separate panel.
+
+**Content generation** — A prompt bar for generating drafts, outlines, and structured content from a short description.
+
+**Grammar and clarity suggestions** — Passive, non-intrusive suggestions that highlight improvements without interrupting the writing flow.
+
+**Custom AI commands** — Register your own AI actions tied to your backend, using the same extension API as other oneuxi-editor features.
+
+The AI module will be optional and tree-shakeable. It will not add to your bundle size unless explicitly imported.
+
+---
+
+## Community & Support
+
+Join our Telegram channel for updates, discussions, and support: [https://t.me/thedebuglab](https://t.me/thedebuglab)
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oneuxi-editor",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A production-ready, lightweight, modular rich text and HTML editor for React applications built on Lexical",
   "author": "thedebuglab",
   "license": "MIT",
@@ -39,7 +39,8 @@
     "./styles.css": "./dist/styles.css"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "build": "tsup",
@@ -49,7 +50,10 @@
     "test:watch": "vitest",
     "test:e2e": "playwright test",
     "prepublishOnly": "npm run build && npm run typecheck && npm run test",
-    "release": "npm publish --access public"
+    "release": "npm publish --access public",
+    "release:patch": "npm version patch && npm publish --access public",
+    "release:minor": "npm version minor && npm publish --access public",
+    "release:major": "npm version major && npm publish --access public"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",