{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "excalidraw-docs",
  "title": "Excalidraw",
  "description": "Void Excalidraw drawing blocks stored inside Plate values.",
  "files": [
    {
      "path": "../../content/docs/(plugins)/(elements)/excalidraw.mdx",
      "content": "---\ntitle: Excalidraw\ndescription: Void Excalidraw drawing blocks stored inside Plate values.\ndocs:\n  - route: /docs/components/excalidraw-node\n    title: Excalidraw Element\n---\n\nExcalidraw adds a void `excalidraw` element that embeds the Excalidraw canvas in the editor. The node stores Excalidraw `elements` and `state` under `data`. This page covers kit setup, insertion, persistence shape, and the client-only registry UI.\n\n<ComponentPreview name=\"excalidraw-demo\" />\n\n<PackageInfo>\n\n## Features\n\n- Void `excalidraw` block element.\n- Direct `insertExcalidraw(editor, props, options)` helper.\n- Excalidraw `elements` and app `state` stored on the node.\n- Dynamic Excalidraw component loading in the React hook.\n- Change deduplication before writing canvas data back to Slate.\n- Read-only mode through Excalidraw `viewModeEnabled`.\n\n</PackageInfo>\n\n## Fast Path\n\n<Steps>\n\n### Add The Kit\n\n`ExcalidrawKit` installs `ExcalidrawPlugin` with the registry `ExcalidrawElement`.\n\n<ComponentSource name=\"excalidraw-kit\" />\n\n```tsx\nimport { createPlateEditor } from 'platejs/react';\n\nimport { ExcalidrawKit } from '@/components/editor/plugins/excalidraw-kit';\n\nexport const editor = createPlateEditor({\n  plugins: ExcalidrawKit,\n});\n```\n\n### Render The Element\n\n`excalidraw-node` owns the client component, Excalidraw CSS import, fixed canvas frame, and read-only view mode.\n\n<ComponentSource name=\"excalidraw-node\" />\n\n### Add An Insert Action\n\nThe registry insert toolbar maps `KEYS.excalidraw` to `insertExcalidraw(editor, {}, { select: true })`.\n\n```tsx title=\"components/editor/transforms.ts\"\nimport { insertExcalidraw } from '@platejs/excalidraw';\nimport { KEYS } from 'platejs';\n\nexport const insertBlockMap = {\n  [KEYS.excalidraw]: (editor) =>\n    insertExcalidraw(editor, {}, { select: true }),\n};\n```\n\n</Steps>\n\n## Ownership\n\n| Layer | Owner | What It Does |\n|-------|-------|--------------|\n| `@platejs/excalidraw` | Package | Exports `BaseExcalidrawPlugin`, `TExcalidrawElement`, `ExcalidrawDataState`, and `insertExcalidraw`. |\n| `@platejs/excalidraw/react` | Package | Exports `ExcalidrawPlugin`, `useExcalidrawElement`, and React Excalidraw prop types. |\n| `excalidraw-kit` | Registry | Adds `ExcalidrawPlugin.withComponent(ExcalidrawElement)`. |\n| `excalidraw-node` | Registry UI | Dynamically renders `@excalidraw/excalidraw` inside a Plate element. |\n| App persistence | App code | Stores the Plate value that contains Excalidraw element data. |\n\n`ExcalidrawPlugin` does not bind an `editor.tf.insert.excalidraw` transform. Use `insertExcalidraw` directly.\n\n## Manual Setup\n\n<Steps>\n\n### Install Package\n\n```bash\nnpm install @platejs/excalidraw\n```\n\n### Add The Plugin\n\nUse the React plugin when the editor renders the Excalidraw canvas.\n\n```tsx\nimport { ExcalidrawPlugin } from '@platejs/excalidraw/react';\nimport { createPlateEditor } from 'platejs/react';\n\nimport { ExcalidrawElement } from '@/components/ui/excalidraw-node';\n\nexport const editor = createPlateEditor({\n  plugins: [ExcalidrawPlugin.withComponent(ExcalidrawElement)],\n});\n```\n\n### Insert A Drawing\n\n`insertExcalidraw` inserts after the current selection parent with `nextBlock: true`. If the editor has no selection or no selection parent, it returns without inserting.\n\n```tsx\nimport { insertExcalidraw } from '@platejs/excalidraw';\n\ninsertExcalidraw(\n  editor,\n  {\n    data: {\n      elements: [],\n      state: {\n        viewBackgroundColor: '#ffffff',\n      },\n    },\n  },\n  { select: true }\n);\n```\n\n</Steps>\n\n## Value Shape\n\n`TExcalidrawElement` is a void element. The drawing payload lives in `data`, not in text children.\n\n```tsx\nconst value = [\n  {\n    children: [{ text: '' }],\n    data: {\n      elements: [\n        {\n          id: 'shape-1',\n          type: 'rectangle',\n          x: 100,\n          y: 100,\n        },\n      ],\n      state: {\n        viewBackgroundColor: '#ffffff',\n      },\n    },\n    type: 'excalidraw',\n  },\n];\n```\n\n| Field | Type | Notes |\n|-------|------|-------|\n| `type` | `'excalidraw'` | Plugin key and node type from `KEYS.excalidraw`. |\n| `children` | `[{ text: '' }]` | Required Slate child for the void element. |\n| `data.elements` | Excalidraw elements | Stored as partial Excalidraw elements. |\n| `data.state` | Excalidraw app state | Stored as imported Excalidraw app state. |\n\nMarkdown serialization is not owned by `@platejs/excalidraw`. Persist the Plate value when you need to keep drawings.\n\n## UI Behavior\n\n`useExcalidrawElement` bridges the Plate node and the Excalidraw React component.\n\n| Surface | Behavior |\n|---------|----------|\n| Component loading | Dynamically imports `@excalidraw/excalidraw` and returns the loaded component. |\n| Initial data | Deep-clones `element.data.state`, `element.data.elements`, `libraryItems`, and `scrollToContent`. |\n| Editing | `onChange` writes `{ elements, state }` back to the node. |\n| Deduplication | Uses deep equality to skip writes when canvas data did not change. |\n| Read-only mode | Removes the write handler and enables Excalidraw `viewModeEnabled`. |\n| Canvas frame | Registry UI renders a bordered `aspect-video` frame capped at `600px`. |\n\nThe registry element imports `@excalidraw/excalidraw/index.css`, so custom copies need the same stylesheet.\n\n## API Reference\n\n| API | Package | Use |\n|-----|---------|-----|\n| `BaseExcalidrawPlugin` | `@platejs/excalidraw` | Headless void element plugin. |\n| `ExcalidrawPlugin` | `@platejs/excalidraw/react` | React Excalidraw plugin. |\n| `insertExcalidraw(editor, props?, options?)` | `@platejs/excalidraw` | Inserts a void Excalidraw node after the current selection parent. |\n| `useExcalidrawElement(options)` | `@platejs/excalidraw/react` | Returns the dynamically loaded `Excalidraw` component and props for the registry element. |\n| `TExcalidrawElement` | `@platejs/excalidraw` | Element shape with optional `data`. |\n| `ExcalidrawDataState` | `@platejs/excalidraw` | Data shape for stored Excalidraw elements and app state. |\n",
      "type": "registry:file",
      "target": "content/docs/plate/(plugins)/(elements)/excalidraw.mdx"
    }
  ],
  "type": "registry:file"
}