@pubwave/editor

A Notion-level block editor built with React and Tiptap.

✨ Features

• 📝 Premium Writing Experience - Fluid, responsive editing with natural Enter-driven writing flow
• ✨ Selection-Only Toolbar - Contextual formatting that appears only when you select text
• 🎯 Block Drag & Drop - Intuitive reordering with clear visual feedback
• 🎨 Theme Tokens - Full styling control via CSS custom properties
• ⚡ SSR Safe - Works with Next.js and other SSR frameworks
• 📦 Lightweight - Only ships what you need (React + Tiptap peer dependencies)
• ⌨️ Slash Commands - Type / to quickly insert blocks and formatting
• 🎨 Text & Background Colors - Rich color picker with recently used colors
• 🔄 Turn Into - Convert blocks between different types (paragraph, headings, lists, etc.)
• 📋 Rich Formatting - Bold, italic, underline, strikethrough, code, links, and text alignment
• 📝 Multiple Block Types - Paragraphs, headings, lists, quotes, code blocks, tables, charts, and more
• 🖼️ Image Support - Upload images via file picker or paste from clipboard, with base64 or custom upload service
• 📊 Chart Support - Interactive charts powered by Chart.js with editable data
• 🌐 Internationalization - Multi-language support with English as default

📦 Installation

Basic Installation (without Chart support)

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

With Chart Support

If you want to use Chart blocks, also install Chart.js:

npm install @pubwave/editor chart.js
# or
yarn add @pubwave/editor chart.js
# or
pnpm add @pubwave/editor chart.js

Note: chart.js is an optional peer dependency. Only install it if you plan to use Chart block functionality.

🚀 Quick Start

import { PubwaveEditor } from '@pubwave/editor';
import '@pubwave/editor/style.css';

function MyEditor() {
  const [content, setContent] = useState({
    type: 'doc',
    content: [
      {
        type: 'paragraph',
        content: [{ type: 'text', text: 'Start writing...' }],
      },
    ],
  });

  return (
    <PubwaveEditor
      content={content}
      onChange={(newContent) => setContent(newContent)}
    />
  );
}

📋 Requirements

React Versions

| React Version | Status | | ------------- | ---------------------- | | 18.x | ✅ Tested, Recommended | | 19.x | ✅ Supported |

Peer Dependencies

• react: ^18.0.0 || ^19.0.0 (required)
• react-dom: ^18.0.0 || ^19.0.0 (required)
• chart.js: ^4.0.0 || ^5.0.0 (optional, required only for Chart block support)

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

📖 API Reference

PubwaveEditor Component

The main React component for rendering the editor.

Component Props

| Prop | Type | Default | Description | | ------------------- | -------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | content | JSONContent | undefined | Initial content in Tiptap JSON format | | editable | boolean | true | Whether the editor is in read-only mode | | placeholder | string | 'Start writing...' | Placeholder text shown when the editor is empty | | theme | EditorTheme | undefined | Theme configuration object (see Theming) | | autofocus | boolean \| 'start' \| 'end' | false | Enable autofocus on mount. true or 'end' focuses at the end, 'start' focuses at the beginning | | imageUpload | ImageUploadConfig | undefined | Image upload configuration (see Image Upload) | | width | string | '100%' | Editor container width. Can be a CSS value like '100%', '1200px', '90vw', etc. Defaults to '100%' (full width of parent container) | | height | string | undefined | Editor container height. Can be a CSS value like '500px', '80vh', 'auto', etc. When set, the editor becomes a fixed-height scrollable container | | minHeight | string | undefined | Editor container minimum height. Can be a CSS value like '200px', '50vh', etc. The editor will expand with content but maintain at least this height | | onChange | (content: JSONContent) => void | undefined | Callback fired when the editor content changes | | onSelectionChange | () => void | undefined | Callback fired when the selection changes | | onFocus | () => void | undefined | Callback fired when the editor gains focus | | onBlur | () => void | undefined | Callback fired when the editor loses focus | | onReady | (api: EditorAPI) => void | undefined | Callback fired when the editor is ready with API access | | className | string | undefined | Additional CSS class for the container | | data-testid | string | 'pubwave-editor' | Test ID for testing purposes |

For complete TypeScript type definitions, see the exported types from @pubwave/editor:

• EditorTheme - Theme configuration
• EditorAPI - Editor API interface
• EditorLocale - Supported locale codes: 'en' | 'zh' | 'zh-CN' | 'ja' | 'ko' | 'fr' | 'de' | 'es' | 'pt'
• ImageUploadConfig - Image upload configuration

EditorAPI Methods

The editor exposes a public API through the ref prop or onReady callback:

import { useRef } from 'react';
import type { EditorAPI } from '@pubwave/editor';

const editorRef = useRef<EditorAPI | null>(null);

<PubwaveEditor
  ref={editorRef}
  onReady={(api) => {
    editorRef.current = api;
  }}
/>;

// Later, use the API
editorRef.current?.setContent(newContent);
editorRef.current?.getJSON();
editorRef.current?.toggleBold();

Available Methods

| Method | Description | Parameters | Returns | | ----------------------- | --------------------------- | ----------------------------- | ------------- | | getState() | Get current editor state | - | EditorState | | getJSON() | Get content as JSON | - | JSONContent | | getHTML() | Get content as HTML | - | string | | getText() | Get content as plain text | - | string | | setContent(content) | Set new content | content: JSONContent | void | | clearContent() | Clear all content | - | void | | setEditable(editable) | Toggle read-only mode | editable: boolean | void | | focus(position?) | Focus the editor | position?: 'start' \| 'end' | void | | blur() | Blur the editor | - | void | | toggleBold() | Toggle bold formatting | - | void | | toggleItalic() | Toggle italic formatting | - | void | | setLink(href) | Set or remove a link | href: string \| null | void | | destroy() | Destroy the editor instance | - | void |

🖼️ Image Upload

The editor supports two image upload modes:

1. Base64 (Default) - Images are converted to base64 data URLs and embedded directly
2. Custom Upload Service - Images are uploaded to your server and URLs are stored

Base64 Mode (Default)

By default, images are converted to base64. No configuration needed:

<PubwaveEditor />

Custom Upload Service

Configure a custom upload handler to upload images to your server:

<PubwaveEditor
  imageUpload={{
    handler: async (file: File) => {
      const formData = new FormData();
      formData.append('image', file);

      const response = await fetch('/api/upload', {
        method: 'POST',
        body: formData,
      });

      const data = await response.json();
      return data.url; // Return the image URL
    },
    maxSize: 5 * 1024 * 1024, // 5MB (optional, default: 10MB)
    accept: ['image/jpeg', 'image/png', 'image/webp'], // Optional, default: ['image/*']
  }}
/>

Image Upload Features

• File Picker: Use /image command in slash menu to open file picker
• Paste Support: Paste images from clipboard (Ctrl/Cmd+V)
• Automatic Fallback: If custom upload fails, automatically falls back to base64
• File Validation: Validates file type and size before upload
• Error Handling: Logs errors to console if upload fails

Custom Upload Service

The handler function receives a File object and should return a Promise that resolves to the image URL. The editor will automatically fall back to base64 if the upload fails.

<PubwaveEditor
  imageUpload={{
    handler: async (file: File) => {
      // Upload to your server (Cloudinary, AWS S3, etc.)
      const formData = new FormData();
      formData.append('image', file);

      const response = await fetch('/api/upload', {
        method: 'POST',
        body: formData,
      });

      const data = await response.json();
      return data.url; // Return the image URL
    },
    maxSize: 10 * 1024 * 1024, // 10MB (optional)
    accept: ['image/jpeg', 'image/png', 'image/webp'], // Optional
  }}
/>

🎨 Theming

Pubwave Editor supports full theme customization through the theme prop. You can customize colors, backgrounds, and more.

Basic Theme Configuration

import { PubwaveEditor } from '@pubwave/editor';
import type { EditorTheme } from '@pubwave/editor';

const theme: EditorTheme = {
  colors: {
    background: '#ffffff',
    text: '#1f2937',
    textMuted: '#6b7280',
    border: '#e5e7eb',
    primary: '#3b82f6',
  },
};

<PubwaveEditor theme={theme} />;

For complete EditorTheme interface definition, see TypeScript definitions. Key properties:

• colors - Color configuration (background, text, border, primary, linkColor)
• locale - Locale code for internationalization
• backgroundImage - Optional background image URL
• backgroundImageOptions - Background image display options (size, position, repeat, attachment)

Predefined Themes

The editor includes several predefined themes:

Light Theme

const lightTheme: EditorTheme = {
  colors: {
    background: 'linear-gradient(135deg, #ffffff 0%, #f8fafc 100%)',
    text: '#1f2937',
    textMuted: '#6b7280',
    border: '#e5e7eb',
    primary: '#3b82f6',
  },
};

Dark Theme

const darkTheme: EditorTheme = {
  colors: {
    background: 'linear-gradient(135deg, #0f172a 0%, #1e293b 100%)',
    text: '#f1f5f9',
    textMuted: '#94a3b8',
    border: '#334155',
    primary: '#60a5fa',
    linkColor: '#3b82f6',
  },
};

Other themes: Violet, Rose, Sky (gradient themes).

Background Image

You can add a background image to the editor container:

<PubwaveEditor
  theme={{
    colors: {
      background: '#ffffff',
      text: '#1f2937',
    },
    backgroundImage: 'https://example.com/background.jpg',
    backgroundImageOptions: {
      size: 'cover',
      position: 'center',
      repeat: 'no-repeat',
      attachment: 'fixed',
    },
  }}
/>

Background Image Options:

• size: 'cover' (default) | 'contain' | custom CSS value (e.g., '100% 100%')
• position: CSS position value (default: 'center')
• repeat: 'no-repeat' (default) | 'repeat' | 'repeat-x' | 'repeat-y'
• attachment: 'scroll' (default) | 'fixed' | 'local'

Note: The background image will be layered on top of the background color. If you want the image to be the only background, set background: 'transparent' in the colors.

Internationalization (i18n)

Pubwave Editor supports multiple languages through the locale option in the theme configuration. The editor defaults to English ('en').

Supported Locales

The following locale codes are supported:

• 'en' - English (default)
• 'zh' - Chinese
• 'zh-CN' - Simplified Chinese
• 'ja' - Japanese
• 'ko' - Korean
• 'fr' - French
• 'de' - German
• 'es' - Spanish
• 'pt' - Portuguese

Note: Currently, only English translations are fully implemented. Other languages will fall back to English. The framework is ready for future language additions.

Setting the Locale

import { PubwaveEditor } from '@pubwave/editor';
import type { EditorTheme } from '@pubwave/editor';

const theme: EditorTheme = {
  locale: 'en', // Default, can be set to any supported locale
  colors: {
    background: '#ffffff',
    text: '#1f2937',
    primary: '#3b82f6',
  },
};

<PubwaveEditor theme={theme} />;

The locale affects all user-facing text in the editor, including:

• Slash command menu items and descriptions
• Toolbar button labels and tooltips
• Accessibility labels (ARIA)
• Block type labels
• Placeholder text

CSS Custom Properties

The editor also uses CSS custom properties for styling. Define these in your CSS:

:root {
  --pubwave-bg: #ffffff;
  --pubwave-text: #1a1a1a;
  --pubwave-text-muted: #6b7280;
  --pubwave-border: #e5e7eb;
  --pubwave-primary: #3b82f6;
  --pubwave-hover: rgba(0, 0, 0, 0.05);
}

🎯 Core Features

Slash Commands

Type / anywhere in the editor to open the command menu. Filter commands by typing keywords.

Available Commands:

| Command | Aliases | Description | | ----------------------- | ------------------------------------ | -------------------------- | | /text or /paragraph | /p, /text | Plain text block | | /heading1 | /h1, /title | Large section heading | | /heading2 | /h2, /subtitle | Medium section heading | | /heading3 | /h3 | Small section heading | | /bullet | /ul, /bullet, /- | Bulleted list | | /numbered | /ol, /numbered, /1. | Numbered list | | /todo | /task, /checkbox, /[] | To-do list with checkboxes | | /image | /img, /picture, /photo, /pic | Upload or paste an image | | /quote | /blockquote, /> | Quote block | | /code | /pre, /snippet, /``` | Code block | | /divider |/hr, /line, /--- | Horizontal divider | |/table |/grid, /tbl` | Insert a table |

Usage:

1. Type / to open the menu
2. Type to filter (e.g., /h1 for heading 1, /img for image)
3. Press Enter or click to select
4. Use ArrowUp/ArrowDown to navigate
5. Press Escape to close

Selection Toolbar

The toolbar appears automatically when you select text, providing quick access to formatting options.

Available Actions:

• Turn Into - Convert block type (Paragraph, Heading 1-3, Bulleted List, Numbered List)
• Bold (Cmd/Ctrl+B) - Make text bold
• Italic (Cmd/Ctrl+I) - Make text italic
• Underline - Underline text
• Strikethrough - Strikethrough text
• Code - Inline code formatting
• Alignment - Left align, center align, right align (three direct toolbar icons)
• Link - Add or edit link
• Text Color - Change text color (with recently used colors)
• Background Color - Change background color (with recently used colors)

Block Types

The editor supports the following block types:

• Paragraph - Default text block
• Heading 1-3 - Section headings
• Bulleted List - Unordered list with bullets
• Numbered List - Ordered list with numbers
• Task List - Checklist with checkboxes
• Table - Table block (rows/columns with header)
• Image - Image block (supports base64 or URL)
• Chart - Interactive chart powered by Chart.js (bar, line, pie, doughnut, radar, polar area)
• Blockquote - Quote block
• Code Block - Code snippet with syntax highlighting
• Horizontal Rule - Divider line

Keyboard Shortcuts

| Shortcut | Action | | ------------------ | ----------------------- | | Cmd/Ctrl+B | Toggle bold | | Cmd/Ctrl+I | Toggle italic | | Cmd/Ctrl+Z | Undo | | Cmd/Ctrl+Shift+Z | Redo | | Cmd/Ctrl+A | Select all | | Enter | Create new block | | Arrow Up/Down | Navigate between blocks | | Shift+Arrow | Select text | | / | Open slash command menu | | Escape | Close menus/cancel drag |

Drag & Drop

• Drag Handle - Appears on hover at the left edge of blocks
• Visual Feedback - Clear drop indicators show where blocks will be placed
• Cancel - Press Escape to cancel dragging
• Multi-block Selection - Select multiple blocks to drag together

Color Picker

The color picker provides:

• Text Colors - 10 predefined text colors
• Background Colors - 10 predefined background colors
• Recently Used - Global history of recently used colors (persists across sessions)
• Visual Distinction - Background colors shown as solid circles, text colors shown with 'A' icon
• Tooltips - Hover over any color to see its name
• Smart Positioning - Automatically positions above or below based on available space

🔧 Advanced Usage

Setting Editor Width

By default, the editor takes 100% of the parent container width. You can customize the width using the width prop:

// Full width (default)
<PubwaveEditor width="100%" />

// Fixed width
<PubwaveEditor width="1200px" />

// Responsive width
<PubwaveEditor width="90vw" />
<PubwaveEditor width="calc(100% - 40px)" />

The width prop accepts any valid CSS width value. When set, it will override the default max-width constraint.

Setting Editor Height

You can control the editor's height using the height and minHeight props:

// Fixed height with scrollable content
<PubwaveEditor height="500px" />

// Minimum height (expands with content)
<PubwaveEditor minHeight="300px" />

// Combined: fixed height with minimum fallback
<PubwaveEditor
  height="600px"
  minHeight="400px"
/>

// Using viewport units
<PubwaveEditor height="80vh" />

Important Notes:

• The editor has default padding of 96px top and bottom (192px total). Your height value should account for this padding to ensure content is visible.
• For example, height="100px" would leave no space for content (100px - 192px padding = negative space).
• Recommended minimum height: At least 300px for desktop to accommodate padding and content.
• When height is set, the editor becomes a scrollable container - content will scroll vertically when it exceeds the height.
• When only minHeight is set, the editor will grow automatically with content but maintain at least the minimum height.
• Both props accept any valid CSS height value (px, vh, rem, %, etc.).

Programmatic Content Manipulation

const editorRef = useRef<EditorAPI | null>(null);

<PubwaveEditor
  ref={editorRef}
  onReady={(api) => {
    editorRef.current = api;
  }}
/>;

// Set content programmatically
editorRef.current?.setContent({
  type: 'doc',
  content: [
    {
      type: 'heading',
      attrs: { level: 1 },
      content: [{ type: 'text', text: 'Hello World' }],
    },
  ],
});

// Get content
const json = editorRef.current?.getJSON();
const html = editorRef.current?.getHTML();
const text = editorRef.current?.getText();

// Apply formatting
editorRef.current?.toggleBold();
editorRef.current?.setLink('https://example.com');

Event Handling

<PubwaveEditor
  onChange={(content) => {
    // Content changed
    console.log('New content:', content);
  }}
  onSelectionChange={() => {
    // Selection changed (toolbar may appear/disappear)
  }}
  onFocus={() => {
    // Editor gained focus
  }}
  onBlur={() => {
    // Editor lost focus
  }}
  onReady={(api) => {
    // Editor is ready, API is available
    console.log('Editor ready:', api);
  }}
/>

Read-only Mode

<PubwaveEditor editable={false} content={readOnlyContent} />

In read-only mode:

• All editing affordances are hidden
• Toolbar does not appear
• Slash commands are disabled
• Drag handles are hidden
• Content is still selectable and copyable

Custom Slash Commands

You can extend the editor with custom slash commands:

import { PubwaveEditor } from '@pubwave/editor';
import type { SlashCommand } from '@pubwave/editor';

const customCommands: SlashCommand[] = [
  {
    id: 'custom-block',
    title: 'Custom Block',
    description: 'Insert a custom block',
    icon: <CustomIcon />,
    aliases: ['custom', 'cb'],
    group: 'basic',
    action: (editor) => {
      // Your custom action
    },
  },
];

// Note: Custom slash commands require access to internal APIs
// This is an advanced feature - see source code for implementation details

📊 Chart Support

The editor includes support for interactive charts powered by Chart.js. Charts are fully editable and support multiple chart types.

Chart Types

Supported chart types:

• Bar Chart - Vertical/horizontal bars for comparisons
• Line Chart - Data trends over time
• Pie Chart - Proportional data representation
• Doughnut Chart - Variation of pie chart with hollow center
• Radar Chart - Multi-dimensional data comparison
• Polar Area Chart - Circular data visualization

Adding Charts Programmatically

import { PubwaveEditor } from '@pubwave/editor';
import type { JSONContent } from '@tiptap/core';

const contentWithChart: JSONContent = {
  type: 'doc',
  content: [
    {
      type: 'chart',
      attrs: {
        data: {
          type: 'bar',
          data: {
            labels: ['January', 'February', 'March', 'April'],
            datasets: [
              {
                label: 'Sales',
                data: [65, 59, 80, 81],
                backgroundColor: 'rgba(59, 130, 246, 0.7)',
                borderColor: 'rgba(59, 130, 246, 1)',
                borderWidth: 2,
              },
            ],
          },
          options: {
            responsive: true,
            maintainAspectRatio: false,
            plugins: {
              title: {
                display: true,
                text: 'Monthly Sales',
                color: 'var(--pubwave-text, #37352f)',
              },
              legend: {
                display: true,
                position: 'bottom',
              },
            },
          },
        },
      },
    },
  ],
};

<PubwaveEditor content={contentWithChart} />;

Chart Features

• Interactive Editing - Click edit button on hover to modify chart data
• Drag & Drop - Charts can be reordered like other blocks
• Theme Support - Charts use CSS variables for colors that adapt to theme changes
• Responsive - Charts automatically adjust to container size
• Multiple Datasets - Support for comparing multiple data series
• Customizable - Edit title, labels, colors, and chart options

Chart Data Structure

The chart node uses the following data structure:

interface ChartNodeData {
  type: 'bar' | 'line' | 'pie' | 'doughnut' | 'radar' | 'polarArea';
  data: {
    labels: string[];
    datasets: Array<{
      label?: string;
      data: number[];
      backgroundColor?: string | string[];
      borderColor?: string | string[];
      borderWidth?: number;
    }>;
  };
  options?: {
    responsive?: boolean;
    maintainAspectRatio?: boolean;
    plugins?: {
      title?: {
        display?: boolean;
        text?: string;
        color?: string;
        font?: { size?: number; weight?: string };
      };
      legend?: {
        display?: boolean;
        position?: 'top' | 'bottom' | 'left' | 'right';
      };
    };
  };
}

Chart Editing

When in editable mode:

1. Hover over a chart to reveal the edit button
2. Click the edit button to open the chart editor modal
3. Modify chart type, title, labels, datasets, and appearance options
4. Save changes to update the chart

🐛 Troubleshooting

Common Issues

Q: Styles are not applied

• Ensure you've imported the CSS: import '@pubwave/editor/style.css'
• Check that CSS custom properties are defined

Q: Slash commands don't work

• Ensure the editor is in editable mode
• Check that you're typing / in a text block (not in code blocks)

Q: Toolbar doesn't appear

• Toolbar only appears when text is selected
• Make sure you have a non-empty selection

Q: Colors don't persist

• Text and background colors are stored as marks in the content
• Ensure you're saving the full JSON content, not just HTML

Q: Image upload doesn't work

• Check that imageUpload.handler returns a valid URL string
• Verify file size is within maxSize limit
• Check browser console for error messages
• If custom upload fails, editor will automatically fall back to base64

Q: Charts don't render

• Ensure chart.js is installed: npm install chart.js (optional peer dependency)
• Check that Chart.js is compatible (v4.x or v5.x)
• Verify chart data structure is correct
• Check browser console for errors

Q: Chart colors don't match theme

• Charts use CSS variables for colors that adapt to theme changes
• Ensure CSS custom properties are defined: --pubwave-text, --pubwave-text-muted, --pubwave-border
• Chart colors will automatically update when theme changes

📄 License

MIT © Pubwave