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 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

$3

`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 console.log('Content changed')} />;
}
`

$3

`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 (

console.log('Content changed')} />

);
}
`

Import Options

The package provides flexible import patterns to suit your needs:

$3

`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';
`

$3

`tsx
// Uses Shadcn version by default for backward compatibility
import { IxoEditor, useCreateIxoEditor } from '@ixo/editor';
import '@ixo/editor/style.css';
`

$3

- @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

$3

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 | 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 |

$3

The main editor component. Available in both UI versions with identical APIs.

`tsx
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

$3

`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;
},
});
`

$3

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 (

Connection: {connectionStatus}

);
}
`

$3

`tsx
const editor = useCreateIxoEditor({
theme: 'dark',
});
`

$3

`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:

$3

The List block displays dynamic data from DID and fragment identifiers, perfect for displaying data from your GraphQL API.

$3

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) |

$3

- ✅ You're already using Tailwind CSS
- ✅ You prefer smaller bundle sizes
- ✅ You want the full-featured custom blocks
- ✅ You like CSS variable-based theming

$3

- ✅ 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

$3

`
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
`

$3

`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

$3

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

$3

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.

$3

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)

$3

This is an internal package. All contributions should go through the standard IXO development workflow and review process.