

<Preview name="EditorDefaultExample" />

## Overview [#overview]

`Editor` is Cubitt's BlockNote-backed Notion-style editor. It uses BlockNote's
native block JSON as the default content model, and can also operate in a
Markdown-backed mode for consumers that persist Markdown.

Cubitt owns the composable React shell, BlockNote UI adapters, editor layout,
and interaction chrome. Consumers own document persistence, upload storage,
permissions, comment storage, and workflow state.

## Usage [#usage]

```tsx
import { Editor } from "@tilt-legal/cubitt-components/editor";

<Editor.Root
  comments={{
    currentUserId,
    onThreadsChange: ({ content, threads }) =>
      saveEditorState({ blocks: content, threads }),
    resolveUsers,
    threads,
  }}
  content={blocks}
  contentFormat="blocknote"
  onContentChange={({ content }) => saveBlocks(content)}
  uploadFile={uploadFile}
>
  <Editor.View />
  <Editor.CommentsSidebar />
</Editor.Root>;
```

For Markdown-backed consumers, use the same content API with
`contentFormat="markdown"`.

```tsx
<Editor.Root
  content={markdown}
  contentFormat="markdown"
  onContentChange={({ content }) => saveMarkdown(content)}
>
  <Editor.View />
</Editor.Root>
```

## Guides [#guides]

<Cards>
  <Card title="Content Formats" href="./content-formats">
    Use BlockNote JSON or Markdown as the canonical persisted content format.
  </Card>

  <Card title="Comments" href="./comments">
    Configure BlockNote comments, thread storage, simple mode, and Markdown
    range markers.
  </Card>
</Cards>

## Examples [#examples]

### Markdown [#markdown]

<Preview name="EditorMarkdownExample" />

### Comments [#comments]

<Preview name="EditorCommentsExample" />

### Read Only [#read-only]

<Preview name="EditorReadOnlyExample" />

## API Reference [#api-reference]

### Editor.Root [#editorroot]

| Prop              | Type                                        | Default       | Description                                                                                                                    |
| ----------------- | ------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `contentFormat`   | `"blocknote" \| "markdown"`                 | `"blocknote"` | Selects the canonical content format Cubitt receives and emits.                                                                |
| `content`         | `EditorPartialBlock[] \| string`            | -             | Controlled content. The type is derived from `contentFormat`.                                                                  |
| `onContentChange` | `(event: EditorContentChangeEvent) => void` | -             | Emits `{ contentFormat, content }` in the selected canonical format.                                                           |
| `editable`        | `boolean`                                   | `true`        | Enables or disables editing.                                                                                                   |
| `comments`        | `EditorCommentsConfig`                      | -             | Enables comments with consumer-owned thread snapshots and user resolution.                                                     |
| `uploadFile`      | `EditorUploadFile`                          | -             | Consumer-owned upload callback used by BlockNote file and media blocks in `blocknote` mode.                                    |
| `resolveFileUrl`  | `(url: string) => Promise<string>`          | -             | Optional authenticated URL resolver for file blocks in `blocknote` mode.                                                       |
| `editorOptions`   | `EditorOptions`                             | -             | Narrow BlockNote option pass-through. Collaboration, schema, extensions, and controlled content are intentionally not exposed. |
| `className`       | `string`                                    | -             | Class name for the root flex container.                                                                                        |

### Editor.View [#editorview]

Renders BlockNote's shadcn view with the free default UI enabled. In
`blocknote` mode, the full BlockNote UI is available: formatting toolbar,
slash menu, side menu, link toolbar, emoji picker, file panel, and table
handles. In `markdown` mode, Cubitt narrows the UI to Markdown-representable
content plus comments.

`Editor.View` is the full-width scroll container. It owns the default
`w-full`, vertical overflow, and `px-8 py-0` padding. The document wrapper is
centered and constrained, and it targets BlockNote's internal `.bn-editor` so
the editor fills the wrapper with BlockNote's inline padding removed by default.

| Prop                | Type      | Default         | Description                                                                                                                                                                                        |
| ------------------- | --------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `documentClassName` | `string`  | -               | Class name applied to the document wrapper. The default measure is centered, `max-w-2xl`, and targets the internal `.bn-editor` with `w-full`, `max-w-none`, and `px-0`.                           |
| `editable`          | `boolean` | Root `editable` | Overrides editability for this view.                                                                                                                                                               |
| `floatingThread`    | `boolean` | `false`         | Shows a Cubitt floating thread card when a highlighted comment range is selected. Use this when the comments sidebar is closed, such as on narrow layouts.                                         |
| `className`         | `string`  | -               | Class name for the root view and scroll container. The view owns `w-full overflow-y-auto px-8 py-0` by default; override this here when a surface needs different page padding or scroll behavior. |

### Editor.CommentsSidebar [#editorcommentssidebar]

Renders Cubitt-owned comment cards backed by the configured comment thread
snapshot. It returns `null` unless `comments` is configured on `Editor.Root`.

| Prop                        | Type                                          | Default      | Description                                                           |
| --------------------------- | --------------------------------------------- | ------------ | --------------------------------------------------------------------- |
| `filter`                    | `"open" \| "resolved" \| "all"`               | `"all"`      | Filters visible threads.                                              |
| `sort`                      | `"position" \| "recent-activity" \| "oldest"` | `"position"` | Controls thread ordering.                                             |
| `maxCommentsBeforeCollapse` | `number`                                      | `5`          | Collapses long reply chains until the thread is selected or expanded. |
| `className`                 | `string`                                      | -            | Class name for the sidebar wrapper.                                   |