@ixo/editor

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:

• Type /list in the editor
• Or type / and search for "List", "data", or "dynamic"
• Configure the DID and fragment identifier in the settings

Overview Block:

• Type /overview in the editor
• Or type / and search for "Overview", "overview-block", or "data-overview"
• 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.