# @naatchaal/editor — full AI documentation

Product: Naat Editor  
npm: `@naatchaal/editor`  
MCP: `@naatchaal/editor-mcp`  
Home: https://naat.tools/editor  
Privacy: Editing runs in the browser; content leaves the tab only if the host app persists exports.

**North star:** highly customizable to the deep — but simple. Progressive disclosure:

1. **Start here (≈90%)** — few imports/props; create/edit, save, validate
2. **Customize deeply (≈10%)** — theme, toolbar chrome/icons/custom items, layout composition

Same package for both. Do **not** invent TipTap / Lexical / Quill APIs. Styles auto-load with `@naatchaal/editor` (1.0.1+); `styles.css` is optional, never mandatory. Prefer `generate_integration` `style: "simple"`.

## Package surface

| Import | Purpose |
|--------|---------|
| `@naatchaal/editor` | `NaatEditor`, form helpers, types, config helpers, core exports (pulls default styles) |
| `@naatchaal/editor/styles.css` | Optional explicit stylesheet (load order / non-bundlers) |

Important: bundle includes `"use client"` — safe for Next.js App Router Client Components.

---

## Start here

### React API — `<NaatEditor />` (simple)

```ts
type NaatEditorProps = {
  /** Optional. Omit for default toolbar / marks / blocks / theme. */
  config?: Partial<EditorConfig>;
  /** Seed on mount: DocNode | JSON | HTML | plain text. Remount with key= to re-seed. */
  initialContent?: DocNode | string;
  className?: string;
  style?: CSSProperties;
  /** Empty-state hint (like <textarea placeholder>). */
  placeholder?: string;
  /** Presentational validation: true | "message" | omit. App owns the rules. */
  error?: string | boolean;
  /** Show invalid chrome when error is set. Default true. */
  showError?: boolean;
  /** Replace default error message element. */
  renderError?: (message: string) => ReactNode;
  /** Extra class on shell when invalid chrome is shown. */
  invalidClassName?: string;
  /**
   * Hover URL bubble + Open (new tab). Default true.
   * Plain clicks never navigate while editing; Ctrl/Cmd+click opens.
   */
  linkPreview?: boolean;
  /** Replace the default hover bubble. */
  renderLinkPreview?: (props: {
    href: string;
    onOpen: () => void;
    onClose: () => void;
    anchorRect: DOMRect;
  }) => ReactNode;
  showToolbar?: boolean;
  icons?: ToolbarIconMap;
  renderIcon?: RenderToolbarIcon;
  renderLayout?: (parts: { toolbar: ReactNode; surface: ReactNode }) => ReactNode;
  children?: ReactNode;
  onChange?: (payload: {
    doc: DocNode;
    html: string;
    json: string;
    markdown: string;
    plain: string;
  }) => void;
};
```

Minimal embed:

```tsx
"use client";
import { NaatEditor } from "@naatchaal/editor";
// Default styles load with the package import.
// Optional: import "@naatchaal/editor/styles.css" for explicit order / non-bundlers.

<NaatEditor
  initialContent="<p>Hello</p>"
  onChange={({ html, json }) => { /* persist */ }}
/>
```

Server Components: render inside a Client Component (`"use client"` wrapper).

### Initial content / edit-from-DB

1. Pass saved content as `initialContent` (DocNode, JSON string, HTML, or plain text).
2. Uncontrolled after mount. Remount with React `key={recordId}` when the edited row changes.
3. Persist via `onChange` (`html` / `json` / `doc` / …) into form state or your API.
4. No controlled `value` prop — remount instead (avoids contenteditable cursor bugs).

```tsx
<NaatEditor
  key={questionId}
  initialContent={savedHtmlOrJson}
  onChange={({ html, json }) => { /* form / DB */ }}
/>
```

### View saved content

**Path A — `NaatEditorViewer`** (Client Component; matching surface typography):

```tsx
"use client";
import { NaatEditorViewer } from "@naatchaal/editor";
// Styles already load via @naatchaal/editor; optional styles.css import.

<NaatEditorViewer
  content={savedHtmlOrJsonOrDoc}  // ContentInput — same as initialContent
  className="…"
  style={…}
  padding="1.25rem"              // → --ne-viewer-padding
  background="…"                 // → --ne-viewer-bg
  border="1px solid #e2e8f0"     // → --ne-viewer-border
  borderRadius="12px"            // → --ne-viewer-radius
  boxShadow="…"                  // → --ne-viewer-shadow
/>
```

No toolbar / focus trap / editor provider. Links: `target=_blank` + `rel=noopener noreferrer` (hrefs sanitized via `sanitizeLinkHref`). Class: `.naat-editor-viewer` (+ `.naat-editor-surface` typography). Async fetch: pass `loading={isPending}` (optional `renderLoading`); empty `content` alone does not imply loading. Deep customize with CSS / Tailwind / `className`.

**Security:** `NaatEditorViewer` / `contentToViewerHtml` never inject raw HTML. DocNode/JSON/plain → `parseContent` → `docToHtml`. HTML strings → `sanitizeHtmlForView` (strips `<script>`, `on*` handlers, `javascript:`/`data:` URLs, untrusted iframes; keeps YouTube/Vimeo). Prefer Path A. Multi-tenant UGC: also sanitize server-side before storage.

**Path B — render HTML yourself:**

```tsx
<div dangerouslySetInnerHTML={{ __html: sanitizeHtmlForView(savedHtml) }} />
```

Path B is app-owned — call `sanitizeHtmlForView` (exported) or equivalent before `dangerouslySetInnerHTML`. Do not inject raw UGC.

### Form essentials

```ts
import {
  parseContent,
  isEmptyContent,
  getPlainText,
  getTextLength,
  validateContent,
  type ContentInput,
} from "@naatchaal/editor";

parseContent(input)           // DocNode | string → DocNode
isEmptyContent(input)         // empty paragraphs / whitespace-only (media counts as content)
getPlainText(input)           // plain text string
getTextLength(input)          // trimmed character length
validateContent(input, { required?, minLength?, maxLength? }) // { ok, errors }

// Zod
z.string().refine((html) => !isEmptyContent(html), "Required")
z.string().refine((html) => getTextLength(html) >= 10, "Too short")
```

Prefer `parseContent` in app code (clearer name for `resolveInitialContent`).

### Placeholder + height (textarea knobs)

```tsx
{/* Default: grows with content from minHeight */}
<NaatEditor
  placeholder="Write something…"
  config={{ theme: { surface: { minHeight: "12rem" } } }}
/>

{/* Cap + scroll inside */}
<NaatEditor
  config={{ theme: { surface: { minHeight: "12rem", maxHeight: "20rem" } } }}
/>
```

**Editor height** (writing surface; toolbar uncapped): `theme.surface.minHeight` (default CSS `16rem` → `--ne-surface-min-height`) and optional `maxHeight` (`--ne-surface-max-height` + `overflow-y: auto`). Unset `maxHeight` → grow with content. Tailwind: `min-h-*` / `max-h-*` / `overflow-y-auto` on the surface. Placeholder CSS: `--ne-placeholder-color`.

### Drafts

No built-in `localStorage` / `sessionStorage`. Own drafts in the app: read into `initialContent` (pair with `key`), write from `onChange`. Client / after mount only.

### Validation UI (presentation)

Philosophy: **default → toggle → customize**. App owns validation logic; editor shows state.

```tsx
const v = validateContent(html, { required: true, minLength: 10 });

// Default: red shell outline + message when `error` is set
<NaatEditor error={v.ok ? undefined : v.errors[0]} />
<NaatEditor error />                        // invalid, no message text
<NaatEditor error="…" showError={false} />  // aria-invalid only (no chrome)
<NaatEditor
  error="Max 500 characters"
  renderError={(msg) => <p className="hint">{msg}</p>}
  invalidClassName="my-invalid"
  config={{ theme: { error: { border: "#b91c1c", color: "#b91c1c" } } }}
/>
```

CSS tokens: `--ne-error-border`, `--ne-error-focus-ring`, `--ne-error-color`, `--ne-error-message-font-size`, `--ne-error-message-margin-top`.

### Link hover preview

Philosophy: **default → toggle → customize**. While editing, plain clicks on links do **not** navigate (preserves caret). Hover shows URL + Open (`target=_blank`, `rel=noopener noreferrer`). Ctrl/Cmd+click opens immediately.

```tsx
// Default: on
<NaatEditor />
<NaatEditor linkPreview={false} />
<NaatEditor
  renderLinkPreview={({ href, onOpen, onClose, anchorRect }) => (
    <div>
      <button type="button" onClick={onOpen}>{href}</button>
      <button type="button" onClick={onClose}>Close</button>
    </div>
  )}
/>
```

Style: `.naat-editor-link-preview`, `--ne-link-preview-*`. Helpers: `sanitizeLinkHref`, `openLinkInNewTab`.

### Form helpers (hooks) — optional

You do **not** need hooks. `NaatEditor` + `validateContent` is enough. No generic UI hooks (`useDisclosure`, …).

```ts
useNaatEditor() // context — inside provider
useNaatEditorField({ initialContent?, storageFormat?: "html"|"json"|"doc" })
// → { value, setValue, reset, editorProps }  // remount via key on setValue/reset
useNaatEditorValidation({ content, required?, minLength?, maxLength?, validateOn?: "change"|"submit" })
// → { error, ok, errors, validate, reset }
```

---

## Customize deeply

### EditorConfig

```ts
type EditorConfig = {
  toolbar: {
    display?: "icon" | "label" | "icon-label";
    items: ToolbarItem[];
  };
  theme: EditorTheme; // accent, radius, + nested shell/toolbar/button/menu/surface/error tokens
  enabledMarks: MarkType[];
  enabledBlocks: Array<
    | "paragraph"
    | "heading"
    | "bulletList"
    | "orderedList"
    | "codeBlock"
    | "blockquote"
    | "image"
    | "video"
    | "horizontalRule"
  >;
};
```

Defaults (approx): accent `#22C55E`, radius `12px`, all built-in marks/blocks enabled, full toolbar. Omit `config` to use them.

### Toolbar items

`toolbar.items` accepts:

1. Buttons: `{ type: "button", id: ToolbarActionId }`
2. Dropdowns: `{ type: "dropdown", id: string, label: string, items: string[] | option objects }`
3. Separators: `{ type: "separator" }`
4. Custom React: `{ type: "custom", id: string, render: (ctx) => ReactNode }`

`fontSize` / `textColor` / `highlight` as buttons auto-expand into default dropdowns.

#### ToolbarActionId

`bold`, `italic`, `underline`, `strike`, `code`, `link`, `unlink`, `clearFormatting`,
`fontSize`, `textColor`, `highlight`,
`heading1`, `heading2`, `heading3`, `paragraph`, `blockquote`,
`bulletList`, `orderedList`, `codeBlock`, `image`, `video`, `horizontalRule`,
`preview`, `undo`, `redo`

**Content preview:** toolbar `preview` opens a read-only HTML modal (same export as `onChange`). Omit from `toolbar.items` to disable. Optional `previewTitle` (default `"Preview"`). CSS: `.naat-editor-preview-*` / `--ne-preview-*`.

#### Value dropdown defaults

- fontSize items: `sm`, `base`, `lg`, `xl` (or raw CSS like `14px`; bare numbers / `"14"` coerce to px)
- textColor items: hex colors
- highlight items: hex colors or `transparent`
- textColor / highlight menus always append a native color picker (Custom) that runs the same action with `attrs.color`

#### Helpers (from package)

- `createEditorConfig(partial?)`
- `buildFlatToolbar(actions: ToolbarActionId[])`
- `buildGroupedToolbar(actions: ToolbarActionId[])` — groups headings + value marks into dropdowns
- `normalizeToolbarItems(items)`
- `flattenToolbarActionIds(items)`
- `configToSnippet(config)` — copy-paste Next snippet
- `ALL_TOOLBAR_ACTIONS` — `{ id, label }[]`

### Theme, icons, layout composition

Naat Editor splits into **Toolbar** + **Surface** (editable). Theme tokens cover shell / toolbar / button / menu / surface (bg, border, padding, radius, shadows, colors, fonts). Use `renderLayout` or compose `NaatEditorProvider` + `NaatToolbar` + `NaatSurface` yourself.

**Input area height:** `config.theme.surface.minHeight` → `--ne-surface-min-height` (CSS default `16rem`); optional `maxHeight` → `--ne-surface-max-height` + scroll inside. Unset `maxHeight` → grow with content.

```tsx
import {
  NaatEditor,
  NaatEditorProvider,
  NaatToolbar,
  NaatSurface,
} from "@naatchaal/editor";

<NaatEditor
  config={{ theme: { accent: "#16a34a", radius: "16px" } }}
  renderLayout={({ toolbar, surface }) => (
    <>
      {surface}
      {toolbar}
    </>
  )}
/>

<NaatEditorProvider config={...}>
  <div className="naat-editor">
    <NaatToolbar />
    <NaatSurface />
  </div>
</NaatEditorProvider>
```

#### Swap toolbar icons (defaults are built-in SVGs)

```tsx
import { NaatEditor, BoldIcon } from "@naatchaal/editor";
import { Bold as LucideBold } from "lucide-react"; // optional — only if YOU choose Lucide

// Partial map
<NaatEditor icons={{ bold: LucideBold, image: MyImageIcon }} />

// Full control (return null to keep default)
<NaatEditor
  renderIcon={(id, props) =>
    id === "bold" ? <span {...props}>B</span> : null
  }
/>
```

`DEFAULT_TOOLBAR_ICONS` and individual icons (`BoldIcon`, `ImageIcon`, …) are exported for reuse.

#### Display + fonts

```ts
toolbar: {
  display: "icon", // or "label" | "icon-label"
  items: [
    { type: "button", id: "bold" },
    { type: "button", id: "link", display: "label", label: "Link" },
  ],
}

theme: {
  toolbar: { fontFamily: "Georgia, serif", fontSize: "0.9rem" },
  button: { fontWeight: "600" },
}
```

### Recipes

#### Minimal toolbar

```ts
config={{
  toolbar: {
    items: [
      { type: "button", id: "bold" },
      { type: "button", id: "italic" },
      { type: "button", id: "link" },
      { type: "button", id: "undo" },
      { type: "button", id: "redo" },
    ],
  },
  enabledMarks: ["bold", "italic", "link"],
  enabledBlocks: ["paragraph"],
}}
```

#### Grouped marketing editor

```ts
import { buildGroupedToolbar, NaatEditor } from "@naatchaal/editor";

const actions = [
  "bold", "italic", "heading1", "heading2", "heading3",
  "fontSize", "textColor", "bulletList", "image", "undo", "redo",
] as const;

<NaatEditor
  config={{
    toolbar: { items: buildGroupedToolbar([...actions]) },
    theme: { accent: "#0B1F3A", radius: "10px" },
  }}
/>
```

#### Persist HTML to backend

```tsx
<NaatEditor
  initialContent={savedHtml}
  onChange={({ html, json }) => {
    void fetch("/api/doc", {
      method: "POST",
      body: JSON.stringify({ html, json }),
    });
  }}
/>
```

#### Edit existing + validate

```tsx
import { NaatEditor, isEmptyContent, getTextLength } from "@naatchaal/editor";

<NaatEditor key={docId} initialContent={serverDoc} onChange={...} />

// form field stores html from onChange
z.string().refine((html) => !isEmptyContent(html), "Required")
z.string().refine((html) => getTextLength(html) >= 10, "Too short")
```

---

## Document model (DocNode)

Immutable JSON tree:

```json
{
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Hello ", "marks": [{ "type": "bold" }] }
      ]
    },
    {
      "type": "heading",
      "attrs": { "level": 1 },
      "content": [{ "type": "text", "text": "Title" }]
    },
    {
      "type": "image",
      "attrs": { "src": "https://example.com/a.jpg", "alt": "demo" }
    },
    {
      "type": "video",
      "attrs": {
        "src": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "provider": "youtube"
      }
    }
  ]
}
```

### Blocks

`paragraph`, `heading` (level 1–3), `codeBlock`, `blockquote`, `bulletList` / `orderedList` (`listItem` → `paragraph`), `image`, `video`, `horizontalRule` (void / atom)

### Marks

`bold`, `italic`, `underline`, `strike`, `code`, `link` (`href`), `fontSize` (`size`), `textColor` (`color`), `highlight` (`color`)

Shortcuts: Mod+B bold, Mod+I italic, Mod+U underline, Mod+Shift+X strike.

Toolbar helpers: `unlink` (remove link mark), `clearFormatting` (remove all marks on selection).

### Media URL rules

- Image / video toolbar prompts for URL.
- Allowed: `https://`, `http://`, `blob:` (local demos).
- Video providers: `youtube`, `vimeo`, `direct`.
- Iframe embeds use safe attributes only.

## Architecture (short)

1. Document model — JSON tree
2. Transactions — pure transforms + selection
3. History — undo/redo snapshots
4. DOM bridge — model ↔ contenteditable via `beforeinput`

## Out of scope (v0.x)

Tables, comments, realtime collab, advanced Word paste, SSR editing (use Client Component boundary).

## MCP tools (@naatchaal/editor-mcp)

Call `get_agent_rules` before coding. Prefer `generate_integration` with `style: "simple"`.

- `get_overview` — llms.txt (hard rules / myths)
- `get_full_docs` — this document
- `get_agent_rules` — AGENTS.md hard rules (MUST)
- `search_docs` — keyword search
- `list_actions` — marks, blocks, toolbar actions
- `build_toolbar` — optional toolbar JSON when customizing (not required for Start here)
- `generate_integration` — drop-in React/Next snippet. Default `style: "simple"` = Start here (no themed `config`). Use `style: "customized"` only for toolbar/theme variants. Read-only: `NaatEditorViewer`.
- `validate_config` — validate partial EditorConfig JSON when customizing (skip if omitting `config`)

## Cursor / Claude skill

See package path `skills/naat-editor/SKILL.md` or site `AGENTS.md`.
Install into a project: copy that folder to `.cursor/skills/naat-editor/`.