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

npm install @ixo/editor
# or
yarn add @ixo/editor
# or
pnpm add @ixo/editor

Quick Start

Shadcn UI Version (Default)

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

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)

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

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

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.

<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

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:

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

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

Read-Only Mode

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

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

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

import { IxoEditor } from '@ixo/editor';
import '@blocknote/shadcn/style.css';
import '@ixo/editor/style.css';

After (v2.x) - Recommended:

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

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