@commonpub/editor

@commonpub/editor

TipTap block editor extensions and serialization for CommonPub.

Overview

Block-based content editor built on TipTap. Content is stored as BlockTuple arrays, a compact serialization format that maps bidirectionally to TipTap's ProseMirror document structure. Each block type has a Zod schema, a TipTap extension, and a registry entry.

Installation

pnpm add @commonpub/editor

Usage

Creating an Editor

import { createCommonPubEditor } from '@commonpub/editor';

const editor = createCommonPubEditor({
  content: existingBlockTuples, // optional
  onUpdate: (tuples) => {
    // Save block tuples
  },
});

Block Types

20 block types are available, covering rich text, media, and maker-specific content:

Core blocks:

Type	Extension	Description
text	CommonPubText	Rich text paragraph
heading	CommonPubHeading	Heading (h1-h6)
code	CommonPubCodeBlock	Syntax-highlighted code block
image	CommonPubImage	Image with alt text and caption
quote	CommonPubQuote	Block quote with attribution
callout	CommonPubCallout	Callout box (info, warning, tip)

Media & embed blocks:

Type	Extension	Description
gallery	CommonPubGallery	Image gallery with captions
video	CommonPubVideo	Embedded video player
embed	CommonPubEmbed	External embed (iframe)
markdown	CommonPubMarkdown	Raw markdown block
divider	—	Horizontal divider
sectionHeader	—	Section header / separator

Maker-focused blocks:

Type	Extension	Description
partsList	CommonPubPartsList	Bill of materials / parts list
buildStep	CommonPubBuildStep	Step-by-step build instructions
toolList	CommonPubToolList	Required tools list
downloads	CommonPubDownloads	Downloadable files (STL, Gerber, etc.)

Interactive blocks (explainers):

Type	Extension	Description
quiz	CommonPubQuiz	Multiple-choice quiz
interactiveSlider	CommonPubInteractiveSlider	Interactive slider control
checkpoint	CommonPubCheckpoint	Progress checkpoint
mathNotation	CommonPubMathNotation	Mathematical notation

BlockTuple Format

Content is serialized as an array of [type, content] tuples:

type BlockTuple = [string, Record<string, unknown>];

// Example
const blocks: BlockTuple[] = [
  ['heading', { level: 1, text: 'Getting Started' }],
  ['text', { html: '<p>Welcome to the tutorial.</p>' }],
  ['code', { language: 'typescript', code: 'const x = 1;' }],
  ['image', { src: '/uploads/photo.jpg', alt: 'A circuit board' }],
];

Serialization

import { blockTuplesToDoc, docToBlockTuples, validateBlockTuples } from '@commonpub/editor';

// BlockTuples -> ProseMirror document (for TipTap)
const doc = blockTuplesToDoc(tuples, schema);

// ProseMirror document -> BlockTuples (for storage)
const tuples = docToBlockTuples(doc);

// Validate block tuples against registered schemas
const errors = validateBlockTuples(tuples);

Block Registry

Register custom block types or use the built-in ones:

import { registerBlock, lookupBlock, listBlocks, registerCoreBlocks } from '@commonpub/editor';

// Register all 20 built-in block types
registerCoreBlocks();

// Register a custom block type
registerBlock({
  type: 'embed',
  schema: embedContentSchema,
  extension: CommonPubEmbed,
});

// Look up a registered block
const block = lookupBlock('heading');

// List all registered block types
const types = listBlocks(); // ['text', 'heading', 'code', ...]

Individual Extensions

Use extensions directly for custom editor setups:

import { CommonPubText, CommonPubHeading, CommonPubCodeBlock } from '@commonpub/editor';

Content Schemas

Zod schemas for validating block content:

import {
  textContentSchema,
  headingContentSchema,
  codeContentSchema,
  imageContentSchema,
  quoteContentSchema,
  calloutContentSchema,
} from '@commonpub/editor';

Architecture

Editor Factory (createCommonPubEditor)
  -> TipTap Core
       -> Extensions (one per block type)
       -> ProseMirror Schema
            -> Serialization (BlockTuple <-> Doc)
                 -> Block Registry + Zod Schemas

Development

pnpm build        # Compile TypeScript
pnpm test         # Run 69 tests
pnpm typecheck    # Type-check without emitting

Dependencies

• @tiptap/core + extensions: Editor framework
• @tiptap/pm: ProseMirror bindings
• shiki: Syntax highlighting for code blocks
• zod: Block content validation
• @commonpub/config: Feature flags
• @commonpub/schema: Content type definitions