Modulo editor

A powerful, modern React-based Modulo editor that transforms content creation into an intuitive, visual experience. Built with flexibility and extensibility in mind, Modulo editor provides a comprehensive solution for building rich content editors with Universal JSON Output format.

✨ Features

🏗️ Block-Based Architecture

Unlike traditional text editors, Modulo editor operates on a block-based architecture where each piece of content is represented as a structured block, providing better content structure, easier manipulation, and enhanced user experience.

🎨 Rich Built-in Tools

Out of the box, Modulo editor comes with a comprehensive set of tools:

• Text Tools: Paragraph, Heading with rich formatting
• Media Tools: Image, Gallery, Attachment with upload handling
• Structure Tools: List, Table, Quote, Delimiter
• Interactive Tools: Link, Embed for external content
• Advanced Tools: Raw HTML for custom content

🔧 Highly Customizable

• Custom Tools: Build your own block tools with the provided API
• Theming: Full theme customization with light/dark mode support
• Internationalization: Built-in i18n support for multiple languages
• Event System: Comprehensive event system for tracking user interactions

📱 Modern React Integration

• React 18+ Compatible: Built for modern React applications
• TypeScript First: Comprehensive type safety throughout

💾 Smart File Handling

• Upload Management: Built-in file upload with progress tracking
• Multiple Upload Modes: Immediate or batch upload on save
• File Validation: Size limits, type restrictions, and error handling
• Pending Operations: Track and manage file operations

🔄 Undo/Redo System

• History Management: Full undo/redo functionality with action tracking
• Keyboard Shortcuts: Standard keyboard shortcuts (Ctrl+Z, Ctrl+Y)
• History Viewer: Optional history panel for advanced users

🚀 Quick Start

Installation

npm install modulo-editor
# or
yarn add modulo-editor
# or
pnpm add modulo-editor

Requirements

• Node.js: 16.0 or higher
• React: 18.0 or higher
• TypeScript: 4.5+ (optional but recommended)

Basic Usage

import React, { useState } from 'react';
import {
  Editor,
  ParagraphTool,
  HeadingTool,
  ImageTool,
  type EditorContent,
} from 'modulo-editor';
import {
  DocumentTextIcon,
  HashtagIcon,
  PhotoIcon,
} from '@heroicons/react/24/outline';

function MyEditor() {
  const [content, setContent] = useState<EditorContent>({
    version: "1.0",
    time: Date.now(),
    blocks: []
  });

  const tools = {
    paragraph: {
      component: ParagraphTool,
      toolbox: {
        title: "Paragraph",
        icon: DocumentTextIcon,
      },
      type: "paragraph",
    },
    heading: {
      component: HeadingTool,
      toolbox: {
        title: "Heading",
        icon: HashtagIcon,
      },
      type: "heading",
    },
    image: {
      component: ImageTool,
      toolbox: {
        title: "Image",
        icon: PhotoIcon,
      },
      type: "image",
      config: {
        uploadMode: "immediate",
        onUpload: async (file: File) => {
          // Your upload logic here
          const formData = new FormData();
          formData.append('file', file);
          
          const response = await fetch('/api/upload', {
            method: 'POST',
            body: formData,
          });
          
          const result = await response.json();
          return {
            url: result.fileUrl,
            id: result.fileId,
          };
        },
      },
    },
  };

  return (
    <div>
      <Editor
        tools={tools}
        initialContent={content}
        onChange={setContent}
        theme={{ mode: 'light' }}
        showUndoRedoInToolbar={true}
        showSaveButton={true}
      />
    </div>
  );
}

export default MyEditor;

📋 Universal JSON Output

All content is represented in a universal JSON format that works across platforms:

{
  "version": "1.0",
  "time": 1640995200,
  "blocks": [
    {
      "id": "unique-block-id",
      "type": "paragraph", 
      "data": {
        "text": "Hello World",
      }
    },
    {
      "id": "another-block-id",
      "type": "heading",
      "data": {
        "text": "My Heading",
      }
    }
  ]
}

🛠️ Use Cases

Modulo editor is perfect for a wide range of applications:

• Content Management Systems: Build powerful CMS interfaces with structured content editing
• Documentation Platforms: Create rich documentation with tables, code blocks, and interactive elements
• Blog & Publishing Platforms: Enable writers to create engaging content with multimedia support
• E-learning Platforms: Build educational content with interactive elements and rich media
• Collaboration Tools: Create shared content editing experiences

🏗️ Architecture

Modulo editor is built on several key architectural principles:

Store-Based State Management

• Editor State: Content, selected blocks, read-only mode
• History State: Undo/redo operations and history tracking
• File Operations: Upload and removal tracking

Tool-Based System

Each content type is implemented as a "tool" with:

• Component: React component for rendering and editing
• Configuration: Tool-specific settings and options
• Toolbar: Optional toolbar items for advanced functionality

Event-Driven Architecture

Comprehensive event system for:

• Content Changes: Block creation, updates, and removal
• File Operations: Upload progress, success, and errors
• User Interactions: Focus, selection, and navigation

🚢 CI/CD Pipeline

Modulo editor maintains high quality and reliability through automated CI/CD processes:

Continuous Integration

• Automated Testing: Every pull request and push triggers comprehensive test suites
• Build Verification: Packages are built and validated on every change
• Multi-Branch Support: CI runs on both dev and main branches
• Node.js 20: Latest LTS version for optimal performance and security

Continuous Deployment

• Automated Publishing: Successful merges to main trigger automatic npm publishing
• Changesets Integration: Version management and changelog generation
• Release Automation: Seamless package releases with proper versioning
• NPM Registry: Direct publication to the public npm registry

Development Workflow

1. Feature Development: Create feature branches from dev
2. Pull Request: Open PR to dev branch - triggers CI checks
3. Code Review: Team review with automated test validation
4. Merge to Dev: Integration testing and validation
5. Release: Merge dev to main triggers automated release process

Quality Assurance

• Build Verification: Every change must pass build process
• Test Suite: Comprehensive testing before any deployment
• Dependency Management: Frozen lockfile ensures reproducible builds
• Version Control: Proper semantic versioning with automated changelog

📚 Available Tools

| Tool | Description | Features | |------|-------------|----------| | ParagraphTool | Basic text paragraphs | Rich text formatting, inline styles | | HeadingTool | Heading levels 1-6 | Multiple heading levels, rich formatting | | ListTool | Ordered and unordered lists | Nested lists, multiple formats | | ImageTool | Image uploads and display | Upload handling, alt text, captions | | LinkTool | External and internal links | URL validation, title extraction | | QuoteTool | Blockquotes | Rich text formatting, attribution | | TableTool | Data tables | Dynamic rows/columns, cell formatting | | EmbedTool | External content embeds | YouTube, Twitter, etc. | | AttachmentTool | File attachments | Multiple file types, download links | | GalleryTool | Image galleries | Multiple images, captions | | DelimiterTool | Content separators | Visual content breaks | | RawHTMLTool | Custom HTML content | Advanced HTML editing |

🤝 Contributing

We welcome contributions to Modulo editor! Here's how to get involved:

Development Setup

# Clone the repository
git clone https://github.com/yacinebkt/modulo.git
cd modulo

# Install dependencies
pnpm install

# Start development
pnpm dev

# Run tests
pnpm test

# Build packages
pnpm build

Contribution Guidelines

• Branch from dev: All feature branches should be created from the dev branch
• Pull Request Process: Open PRs against dev branch, not main
• Code Quality: All PRs must pass CI checks including tests and build verification
• Commit Messages: Use clear, descriptive commit messages
• Testing: Add tests for new features and ensure existing tests pass

Release Process

The project uses Changesets for version management:

• Add a changeset for your changes: pnpm changeset
• CI/CD automatically handles version bumps and releases
• Releases are triggered on merge to main branch

📖 Documentation

• Installation Guide
• Quick Start
• API Reference
• Custom Tools
• Theming Guide
• File Handling
• Examples

🌐 Browser Compatibility

Modulo editor supports all modern browsers:

• Chrome 88+
• Firefox 85+
• Safari 14+
• Edge 88+

📝 License

This project is licensed under the MIT License -

🔗 Links

• Documentation
• GitHub Repository
• NPM Package
• Issue Tracker
• Discussions

🙏 Acknowledgments

• Built with React and TypeScript
• Icons by Heroicons
• CI/CD powered by GitHub Actions
• Version management with Changesets