npm package: @ixo/editor
Description: A custom BlockNote editor wrapper for IXO team
Author: IXO Team
Latest version: 3.6.0

# IXO Editor

A custom BlockNote editor wrapper built specifically for the IXO team's needs. This package provides a highly customized rich text editing experience built on top of [BlockNote](https://www.blocknotejs.org/) with support for both **Shadcn UI** and **Mantine UI**.

> **Note**: This package is designed for internal IXO team use and is not intended for public consumption, though it is hosted publicly.

## Features

- 🎨 **Multi-UI Support**: Choose between Shadcn UI or Mantine UI components
- 🔧 **Simplified API**: Wrapped BlockNote functionality with sensible defaults
- 📝 **Rich Text Editing**: Full support for headings, lists, code blocks, tables, and more
- 🔗 **Custom Blocks**: Built-in custom blocks including dynamic List block for DID data
- 🖼️ **Media Support**: Image and file upload handling
- 🎯 **TypeScript**: Full TypeScript support with exported types
- 🤝 **Collaboration Ready**: Built-in Matrix-based collaborative editing with real-time synchronization
- 📱 **Responsive**: Mobile-friendly editor experience
- 💎 **Complete CSS Bundles**: Self-contained CSS with all dependencies included

## Installation

```bash
npm install @ixo/editor
# or
yarn add @ixo/editor
# or
pnpm add @ixo/editor
```

## Quick Start

### Shadcn UI Version (Default)

```tsx
import React from 'react';
import { useCreateIxoEditor, IxoEditor } from '@ixo/editor/shadcn';
import '@ixo/editor/style-shadcn.css'; // Complete CSS bundle - no other imports needed!

function MyEditor() {
  const editor = useCreateIxoEditor({
    theme: 'light',
    initialContent: [
      {
        type: 'heading',
        content: 'Welcome to IXO Editor',
        props: { level: 1 },
      },
      {
        type: 'paragraph',
        content: 'Start typing to create amazing content!',
      },
    ],
  });

  return <IxoEditor editor={editor} onChange={() => console.log('Content changed')} />;
}
```

### Mantine UI Version

```tsx
import React from 'react';
import { MantineProvider } from '@mantine/core';
import { useCreateIxoEditor, IxoEditor } from '@ixo/editor/mantine';
import '@ixo/editor/style-mantine.css'; // Complete CSS bundle - no other imports needed!

function MyEditor() {
  const editor = useCreateIxoEditor({
    theme: 'light',
    initialContent: [
      {
        type: 'heading',
        content: 'Welcome to IXO Editor',
        props: { level: 1 },
      },
    ],
  });

  return (
    <MantineProvider>
      <IxoEditor editor={editor} onChange={() => console.log('Content changed')} />
    </MantineProvider>
  );
}
```

## Import Options

The package provides flexible import patterns to suit your needs:

### Option 1: UI-Specific Imports (Recommended)

```tsx
// Shadcn version with complete CSS bundle
import { IxoEditor, useCreateIxoEditor } from '@ixo/editor/shadcn';
import '@ixo/editor/style-shadcn.css';

// Mantine version with complete CSS bundle
import { IxoEditor, useCreateIxoEditor } from '@ixo/editor/mantine';
import '@ixo/editor/style-mantine.css';
```

### Option 2: Default Import (Shadcn)

```tsx
// Uses Shadcn version by default for backward compatibility
import { IxoEditor, useCreateIxoEditor } from '@ixo/editor';
import '@ixo/editor/style.css';
```

### CSS Bundle Options

- `@ixo/editor/style-shadcn.css` - Complete bundle: Inter fonts + Shadcn + IXO styles
- `@ixo/editor/style-mantine.css` - Complete bundle: Inter fonts + Mantine + IXO styles
- `@ixo/editor/style.css` - Default bundle (same as shadcn)
- `@ixo/editor/style-core.css` - Only IXO custom styles (for advanced users)

## API Reference

### `useCreateIxoEditor`

The main hook for creating an IXO editor instance. Available in both UI versions.

```tsx
const editor = useCreateIxoEditor(options?: IxoEditorOptions);
```

#### Options

| Option              | Type                              | Default            | Description                               |
| ------------------- | --------------------------------- | ------------------ | ----------------------------------------- |
| `theme`             | `'light' \| 'dark'`               | `'light'`          | Editor color theme                        |
| `uploadFile`        | `(file: File) => Promise<string>` | Data URL converter | File upload handler                       |
| `initialContent`    | `PartialBlock[]`                  | `undefined`        | Initial editor content                    |
| `editable`          | `boolean`                         | `true`             | Whether editor is editable                |
| `sideMenu`          | `boolean`                         | `true`             | Show side menu (drag handle, plus button) |
| `slashMenu`         | `boolean`                         | `true`             | Enable slash commands menu                |
| `formattingToolbar` | `boolean`                         | `true`             | Show formatting toolbar                   |
| `linkToolbar`       | `boolean`                         | `true`             | Show link toolbar                         |
| `filePanel`         | `boolean`                         | `true`             | Show file panel                           |
| `tableHandles`      | `boolean`                         | `true`             | Show table manipulation handles           |

### `IxoEditor` Component

The main editor component. Available in both UI versions with identical APIs.

```tsx
<IxoEditor
  editor={editor}
  className="my-custom-class"
  onChange={() => {}}
  onSelectionChange={() => {}}
/>
```

#### Props

| Prop                | Type                           | Description                               |
| ------------------- | ------------------------------ | ----------------------------------------- |
| `editor`            | `BlockNoteEditor \| undefined` | Editor instance from `useCreateIxoEditor` |
| `className`         | `string`                       | Additional CSS classes                    |
| `onChange`          | `() => void`                   | Callback when content changes             |
| `onSelectionChange` | `() => void`                   | Callback when selection changes           |
| `children`          | `React.ReactNode`              | Custom child components                   |

## Advanced Usage

### Custom File Upload

```tsx
const editor = useCreateIxoEditor({
  uploadFile: async (file: File) => {
    const formData = new FormData();
    formData.append('file', file);

    const response = await fetch('/api/upload', {
      method: 'POST',
      body: formData,
    });

    const { url } = await response.json();
    return url;
  },
});
```

### Collaborative Editing

For real-time collaborative editing, use the `useCreateCollaborativeIxoEditor` hook with Matrix protocol:

```tsx
import { useCreateCollaborativeIxoEditor, IxoEditor } from '@ixo/editor/shadcn';

function CollaborativeEditor() {
  const { editor, connectionStatus } = useCreateCollaborativeIxoEditor({
    theme: 'light',
    user: {
      id: 'user-123',
      name: 'John Doe',
      color: '#FF5733',
      accessToken: 'your-matrix-access-token',
      address: 'your-user-address',
    },
    matrixClient: matrixClient,
    roomId: '!roomId:matrix.org',
  });

  return (
    <div>
      <div>Connection: {connectionStatus}</div>
      <IxoEditor editor={editor} />
    </div>
  );
}
```

### Dark Theme

```tsx
const editor = useCreateIxoEditor({
  theme: 'dark',
});
```

### Read-Only Mode

```tsx
const editor = useCreateIxoEditor({
  editable: false,
  sideMenu: false,
  slashMenu: false,
  formattingToolbar: false,
});
```

## Custom Blocks

The IXO Editor includes custom blocks for working with IXO ecosystem data, available in both UI versions:

### List Block

The List block displays dynamic data from DID and fragment identifiers, perfect for displaying data from your GraphQL API.

### Overview Block

The Overview block provides a comprehensive view of entity data from DID identifiers.

#### Usage

Both blocks can be inserted using the slash menu:

**List Block:**

1. Type `/list` in the editor
2. Or type `/` and search for "List", "data", or "dynamic"
3. Configure the DID and fragment identifier in the settings

**Overview Block:**

1. Type `/overview` in the editor
2. Or type `/` and search for "Overview", "overview-block", or "data-overview"
3. Configure the DID in the settings

#### Programmatic Usage

```tsx
// Insert a list block programmatically
editor.insertBlocks(
  [
    {
      type: 'list',
      props: {
        title: 'My Data List',
        did: 'did:ixo:entity123',
        fragmentIdentifier: 'claims-data',
      },
    },
  ],
  editor.getTextCursorPosition().block,
  'after'
);

// Insert an overview block programmatically
editor.insertBlocks(
  [
    {
      type: 'overview',
      props: {
        did: 'did:ixo:entity123',
      },
    },
  ],
  editor.getTextCursorPosition().block,
  'after'
);
```

## UI Library Comparison

| Feature           | Shadcn UI            | Mantine UI            |
| ----------------- | -------------------- | --------------------- |
| **Bundle Size**   | ~46KB CSS            | ~173KB CSS            |
| **Custom Blocks** | Full-featured        | Minimal (expandable)  |
| **Theming**       | Tailwind-based       | CSS-in-JS             |
| **Dependencies**  | Radix UI primitives  | Mantine ecosystem     |
| **Customization** | High (CSS variables) | High (theme provider) |

### When to Choose Shadcn UI

- ✅ You're already using Tailwind CSS
- ✅ You prefer smaller bundle sizes
- ✅ You want the full-featured custom blocks
- ✅ You like CSS variable-based theming

### When to Choose Mantine UI

- ✅ You're already using Mantine in your app
- ✅ You prefer component-based theming
- ✅ You want consistent Mantine design language
- ✅ You plan to enhance the minimal blocks with Mantine components

## Development

### Project Structure

```
ixo-editor/
├── src/
│   ├── core/            # Shared infrastructure
│   │   ├── types.ts     # Shared types
│   │   ├── hooks/       # Matrix provider
│   │   └── lib/         # GraphQL client & utilities
│   ├── shadcn/          # Shadcn UI implementation
│   │   ├── IxoEditor.tsx
│   │   ├── blocks/      # Full-featured custom blocks
│   │   ├── components/  # Shadcn UI components
│   │   ├── hooks/       # Editor hooks
│   │   └── index.ts     # Shadcn exports
│   ├── mantine/         # Mantine UI implementation
│   │   ├── IxoEditor.tsx
│   │   ├── blocks/      # Minimal custom blocks
│   │   ├── hooks/       # Editor hooks
│   │   └── index.ts     # Mantine exports
│   ├── styles/          # Source CSS
│   │   └── ixo-editor.css
│   └── index.ts         # Main entry (defaults to shadcn)
├── fonts/               # Inter font files
├── dist/                # Built JavaScript
│   ├── index.js         # Main bundle
│   ├── shadcn/          # Shadcn bundle
│   └── mantine/         # Mantine bundle
├── style*.css           # CSS bundles
└── package.json
```

### Building the Package

```bash
# Install dependencies
pnpm install

# Build the package (creates all bundles)
pnpm build

# Watch for changes during development
pnpm run dev

# Type checking
pnpm run type-check
```

## Requirements

- React 18.0.0 or higher
- React DOM 18.0.0 or higher
- Modern browser with ES2020 support
- For collaborative editing: Matrix server access

### Additional Requirements by UI Library

**For Mantine version:**

- `@mantine/core` ^8.0.0 (peer dependency)
- `@mantine/hooks` ^8.0.0 (peer dependency)

**For Shadcn version:**

- Works with existing Tailwind CSS setup
- No additional peer dependencies

## Migration Guide

### From v1.x to v2.x (Multi-UI)

**Before (v1.x):**

```tsx
import { IxoEditor } from '@ixo/editor';
import '@blocknote/shadcn/style.css';
import '@ixo/editor/style.css';
```

**After (v2.x) - Recommended:**

```tsx
// Explicit shadcn version with complete CSS bundle
import { IxoEditor } from '@ixo/editor/shadcn';
import '@ixo/editor/style-shadcn.css'; // Single import!
```

**After (v2.x) - Backward compatible:**

```tsx
// Still works! (defaults to shadcn)
import { IxoEditor } from '@ixo/editor';
import '@ixo/editor/style.css'; // Now includes all dependencies
```

## License

MIT © IXO Team

---

## Internal Notes

This package is maintained by the IXO development team. For questions or issues, please contact the team directly through internal channels.

### Version Management

Follow semantic versioning:

- Patch releases (0.0.x): Bug fixes and minor updates
- Minor releases (0.x.0): New features that are backward compatible
- Major releases (x.0.0): Breaking changes (like the multi-UI restructure)

### Contributing

This is an internal package. All contributions should go through the standard IXO development workflow and review process.