How to Enable and Use the @openmaic/editor Package: A Complete Guide

To enable and use the @openmaic/editor package, install it via your package manager, import the CSS bundle from dist/editor.css, wrap your application with the EditorProvider component from @openmaic/editor/react, and render the <Editor> component to create a fully functional ProseMirror-based editing surface.

The @openmaic/editor package provides the core editing infrastructure for the OpenMAIC project, delivering a modular ProseMirror-based editing system with dedicated sub-modules for core schema management, React component bindings, and UI utilities. Located in the packages/@openmaic/editor directory of the THU-MAIC/OpenMAIC repository, this package enables developers to integrate rich text and mathematical content editing into OpenMAIC-based applications through a flexible, extension-ready architecture.

Installing and Enabling the Package

Begin by installing the package into your project. The OpenMAIC repository uses a PNPM workspace, but the package functions with any Node.js package manager:

# Using pnpm (recommended for monorepo development)

pnpm add @openmaic/editor

# Using npm or yarn

npm install @openmaic/editor

After installation, import the required stylesheet to ensure proper rendering of editor UI elements. The package bundles a minimal CSS file at dist/editor.css that must be loaded before rendering any components:

import '@openmaic/editor/dist/editor.css';

Package Architecture and Entry Points

The @openmaic/editor package is organized into three sub-modules that can be imported independently or together, each serving distinct architectural purposes as defined in the package.json manifest:

@openmaic/editor/core – Located in src/core/, this module exposes the low-level ProseMirror schema, transaction handling logic, and document model. It defines the fundamental node types (text, math, images) and the EditorTransaction type for type-safe document manipulation.

@openmaic/editor/react – Found in src/react/, this module provides ready-to-use React components including EditorProvider, Editor, and useEditorContext. These components manage the ProseMirror EditorView lifecycle and expose the transactional API to React child components.

@openmaic/editor/ui – Housed in src/ui/, this module contains UI utilities such as element clipboard handling via useClipboard and DOM helpers. It implements the openmaic/editor-elements clipboard kind used throughout the suite for standardized copy-paste operations.

Basic React Implementation

Wrap your application root with EditorProvider to inject the editor context, then render the Editor component where needed:

import { EditorProvider, Editor } from '@openmaic/editor/react';
import '@openmaic/editor/dist/editor.css';

function App() {
  return (
    <EditorProvider>
      <div className="workspace">
        <Editor placeholder="Start typing…" />
      </div>
    </EditorProvider>
  );
}

The EditorProvider initializes the ProseMirror EditorView instance and maintains the editor state, while the Editor component renders the actual contenteditable surface pre-configured with the OpenMAIC schema.

Working with the Transaction API

For programmatic document manipulation, access the core transaction API through the React context hook:

import { useEditorContext } from '@openmaic/editor/react';
import type { EditorTransaction } from '@openmaic/editor/core';

function InsertMathButton() {
  const { view } = useEditorContext();

  const insertEquation = () => {
    const tr: EditorTransaction = view.state.tr;
    const mathNode = view.state.schema.nodes.math.create({ content: 'E=mc^2' });
    view.dispatch(tr.replaceSelectionWith(mathNode));
  };

  return <button onClick={insertEquation}>Insert Math</button>;
}

The EditorTransaction type provides strong typing for ProseMirror's transaction API, ensuring safe read and write operations against the document model defined in src/core/.

UI Utilities and Clipboard Operations

The UI sub-module exposes specialized hooks for handling complex clipboard operations, particularly for rich content elements:

import { useClipboard } from '@openmaic/editor/ui';

function CopySelectionButton() {
  const { copySelection } = useClipboard();

  return <button onClick={copySelection}>Copy Selection</button>;
}

Implementation details for these utilities reside in src/ui/elementClipboard.ts, which coordinates with the openmaic/editor-elements clipboard kind to preserve formatting during copy-paste cycles.

Extending the Editor Schema

To support custom node types, import the base schema from the core module and extend it before passing to the provider:

import { EditorProvider } from '@openmaic/editor/react';
import { schema as baseSchema } from '@openmaic/editor/core';

const extendedSchema = baseSchema.extend({
  nodes: {
    highlight: {
      group: 'inline',
      inline: true,
      selectable: true,
      toDOM: () => ['span', { class: 'highlight' }, 0],
      parseDOM: [{ tag: 'span.highlight' }],
    },
  },
});

function App() {
  return (
    <EditorProvider schema={extendedSchema}>
      <Editor />
    </EditorProvider>
  );
}

This pattern allows the editor to accommodate domain-specific content types while maintaining compatibility with OpenMAIC's transaction system.

Testing and Verification

The package includes comprehensive validation suites to ensure schema integrity and component reliability. Key test files include:

• tests/packages/editor-manifest.test.ts – Validates the publication manifest and package exports defined in packages/@openmaic/editor/package.json
• tests/edit/surfaces/slide/renderer-editor-architecture.test.ts – Verifies integration between the editor and slide rendering surfaces, ensuring the ProseMirror view coordinates correctly with OpenMAIC's workspace shell

Run these tests using your workspace test runner to confirm proper editor initialization before deployment.

Summary

• Install @openmaic/editor via pnpm, npm, or yarn, then import dist/editor.css to enable styling.
• Structure your application with EditorProvider at the root to establish the ProseMirror context for child components.
• Import from three distinct sub-modules—core for schema/transaction logic, react for UI components, and ui for clipboard utilities—depending on your use case.
• Extend the base schema using the schema.extend() method to add custom node types while preserving type safety.
• Test integrations using the provided manifest and surface architecture tests located in tests/packages/ and tests/edit/surfaces/slide/.

Frequently Asked Questions

What is the difference between @openmaic/editor/core and @openmaic/editor/react?

@openmaic/editor/core exports the underlying ProseMirror schema, transaction types, and document model logic found in src/core/. @openmaic/editor/react provides React bindings including the EditorProvider context wrapper and Editor component from src/react/. Use core for headless document manipulation or non-React environments; use react for standard React application integration.

How do I style the editor components?

Import the base stylesheet import '@openmaic/editor/dist/editor.css' in your application entry file. This CSS bundle ensures proper rendering of ProseMirror elements, node selections, and UI chrome. You can layer additional custom styles on top of these base rules to match your application's design system.

Can I use @openmaic/editor without React?

Yes. While the package provides React bindings for convenience, the core editing engine in @openmaic/editor/core is framework-agnostic ProseMirror code. You can instantiate the schema and transaction API directly from src/core/ and bind the resulting EditorView to any DOM container using vanilla JavaScript or alternative frameworks.

Where are the editor tests located in the repository?

Test coverage includes tests/packages/editor-manifest.test.ts for package configuration validation and tests/edit/surfaces/slide/renderer-editor-architecture.test.ts for integration testing within slide editing surfaces. These files verify that the editor correctly initializes and coordinates with OpenMAIC's workspace infrastructure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}