@incodiy/cavator

v5.0.0

Published

13 days ago

Enterprise-grade React WYSIWYG document editor built on Tiptap v2 and ProseMirror by Incodiy

0High
0Medium
0Low

react nextjs editor wysiwyg document-editor tiptap prosemirror rich-text incodiy cavator enterprise-editor headless markdown collaboration

Incodiy Editor

(@incodiy/cavator)

Enterprise-grade, dual-mode WYSIWYG document editor built on Tiptap v2 and ProseMirror for React and Next.js by Incodiy.

📚 Official Documentation

Comprehensive guides, API specifications, and interactive code examples are available in the docs/ directory:

📖 User Guides — Non-technical operational guides for end users.
🛠️ Developer Guides — Architecture, TypeScript interfaces, and integration patterns.

✨ Features

🎯 Core Editing Engine

Headless Tiptap v2 & ProseMirror Power: Rock-solid, extensible document state management with zero UI-engine coupling.
Dual Render Modes:
- 🖥️ Classic Ribbon Mode: Familiar, full-featured Microsoft Word / Google Docs style top toolbar.
- ⚡ Notion-Style Block Mode: Distraction-free editing canvas with / slash commands and floating selection bubble.
Dual HTML & JSON Payload Output: Emits both clean sanitized HTML string and structured ProseMirror JSON tree.
Next.js App Router & SSR Safe: Guaranteed client-side hydration safety with automatic CSS injection.
Pluggable Zero-Dependency Ecosystem Adapters: First-class optional bridges (adapters) for Incodiy companion suites (Media, Location, Forms) with clean standalone fallbacks.

🎨 Rich Typography & Theming

Heading Levels: H1, H2, H3, H4, H5, H6, Paragraph, and Blockquote.
Inline Styling: Bold, Italic, Underline, Strikethrough, Subscript, Superscript, and Inline Code.
Typography Controls: Font family switcher, font sizes (px/rem), line height tuning, text alignment (Left, Center, Right, Justify), and text direction (LTR / RTL).
Color Palette & Format Painter: Rich text and background highlight color pickers with one-click format painter brush.
5 Enterprise Theme Presets: Seamless switching between Classic, Nord, Emerald, Midnight, and Sepia palettes.

📊 Tables, Media, Map & Math

Dynamic Interactive Tables: Insert grid tables with column/row additions, cell merging/splitting, header toggles, and deletion controls.
First-Class HTML5 Video & YouTube: Embed responsive native HTML5 <video> (.mp4, .webm, .mov) and YouTube embeds without schema stripping.
Interactive GIS Map Node: Direct interactive OpenStreetMap card embeds with coordinates, pin labels, and direct external navigation.
Scientific KaTeX Equations: Full LaTeX mathematical formula rendering ($E = mc^2$, matrices, integrals) via KaTeX nodes.
Task & Checklist Nodes: Interactive checkboxes with status persistence.

📥 Document Import & Export Suite

Client-Safe Word (.docx) Import: Direct browser-side Word document parsing into native editor nodes via mammoth.browser.js.
Multi-Format Document Exporter: 1-click export to PDF, Word (.docx), HTML, and Markdown.
Smart Clean Paste: Automatic normalization and sanitization of pasted content from Microsoft Word, Google Docs, and web pages.

🛠️ Productivity, Search & Shortcuts

Find & Replace: Regex-supported in-document search and batch replace dialog.
Table of Contents Generator: Auto-generated live navigation outline based on heading structure.
Keyboard Shortcuts Suite (Ctrl + /): Full modal cheatsheet and hotkey bindings for rapid non-mouse editing.
Accessibility (a11y) Checker: Automatic alt-text validation, contrast warnings, and semantic heading sequence inspection.
Source View & Visual Blocks: Raw HTML source code editor tab and visual block border inspector.
Live Preview & Fullscreen Focus Mode: Distraction-free full viewport editing with optimized z-index layering for host modals.

🎯 Feature Tier Breakdown

✅ BASIC TIER (FREE - MIT License)

Always available in all tiers:

Core Document Editing & History (Undo / Redo)
Headings (H1–H6), Paragraphs, and Blockquotes
Standard Text Styles: Bold, Italic, Underline, Strikethrough
Ordered & Unordered Bullet Lists
Hyperlink Manager with Title & Target
Standard Tables (Insert, Add/Delete Rows & Columns)
Inline Code & Fenced Code Blocks
Character & Word Counters
Native Dark & Light Mode Support

💎 PREMIUM TIER (Commercial License)

Unlock professional publishing tools:

Notion-Style Block Mode with / Slash Command Menu (enableBlockMode)
Floating Text Selection Formatting Bubble (enableSelectionBubble)
Word (.docx) Document Import (enableWordImport)
Multi-Format Export: PDF, Word (.docx), HTML (enablePdfExport, enableWordExport)
Format Painter Style Copy-Paste Brush (enableFormatPainter)
Responsive YouTube Video Embeds (enableVideoEmbeds)
Custom Font Family & Font Size Switchers (enableFontFamily, enableFontSize)
Special Characters & Native Emoji Picker (enableSpecialChars, enableEmojiPicker)
Line Height & Text Direction (LTR/RTL) Controls (enableLineHeight, enableTextDirection)

🚀 ENTERPRISE TIER (Commercial License)

Full-featured powerhouse for enterprise CMS & document management:

Scientific KaTeX Mathematical Equations & Formula Nodes (enableKatexMath)
Interactive Checklist & Task List Blocks (enableTaskLists)
Find & Replace Modal with Batch Operations (enableFindReplace)
Table of Contents Auto-Generator (enableTableOfContents)
Accessibility (a11y) Standards Compliance Checker (enableA11yChecker)
Raw HTML Source Code View Editor (enableSourceView)
Visual Block Structure Inspector (enableVisualBlocks)
Document Page Breaks for Print Layouts (enablePageBreaks)
Live Preview Portal & Fullscreen Focus Mode (enablePreview, enableFullscreen)
Advanced Dual Payload Output (HTML + ProseMirror JSON Tree)

📦 Installation

Install directly from GitHub repository or NPM:

# Using npm
npm install @incodiy/cavator

# Using pnpm
pnpm add @incodiy/cavator

# Using yarn
yarn add @incodiy/cavator

# From GitHub (always latest)
npm install git+https://github.com/incodiy/cavator.git

🚀 Quick Start Examples

1. Form Integration (React & Next.js App Router)

"use client";

import { useState } from "react";
import { Cavator } from "@incodiy/cavator";

export function ArticleEditor() {
  const [content, setContent] = useState("<p>Tulis artikel berita di sini...</p>");

  return (
    <div className="max-w-4xl mx-auto p-6 bg-card border border-border rounded-3xl">
      <h2 className="text-lg font-bold mb-4">Editor Artikel Berita</h2>
      <Cavator
        initialContent={content}
        height={550}
        onChange={({ html }) => setContent(html)}
      />
    </div>
  );
}

2. Dual Payload Output (HTML & JSON AST)

"use client";

import { Cavator } from "@incodiy/cavator";

export function DualOutputEditor() {
  return (
    <Cavator
      initialContent="<h1>Judul Dokumen</h1><p>Paragraf isi...</p>"
      onChange={({ html, json }) => {
        console.log("HTML String:", html);
        console.log("ProseMirror JSON:", json);
      }}
    />
  );
}

3. Custom Mode Switcher (Classic ⇄ Notion Block Mode)

"use client";

import { CnvtrProvider, CavatorShell, ModeSwitcher } from "@incodiy/cavator";

export function CustomEditorLayout() {
  return (
    <CnvtrProvider initialContent="<p>Tekan '/' untuk menambahkan blok...</p>">
      <div className="flex justify-between items-center mb-3">
        <h3 className="font-bold">Mode Editor</h3>
        <ModeSwitcher />
      </div>
      <CavatorShell height={600} />
    </CnvtrProvider>
  );
}

🧩 Component & Hook API Reference

Exported Components

<Cavator /> — Complete plug-and-play WYSIWYG document editor.
<CavatorShell /> — Headless shell container with toolbar, canvas, and modals.
<ModeSwitcher /> — Toggle button between Classic Ribbon and Block Notion-like modes.
<Toolbar /> — Classic multi-group formatting toolbar.
<Canvas /> — Contenteditable ProseMirror rendering canvas.
<StatusBar /> — Document statistics bar (Word count, character count, theme).
<SelectionBubble /> — Floating text formatting bubble for highlighted selections.
<SlashMenu /> — Notion-style / block insertion popup menu.

Exported Modals

<LinkModal /> — Hyperlink insertion and editing dialog.
<ImageModal /> — Image URL and file upload dialog.
<VideoModal /> — YouTube and MP4 video embedding dialog.
<MathModal /> — KaTeX LaTeX equation editor dialog.
<WordImportModal /> — Word (.docx) file importer.
<FindReplaceModal /> — In-document search & replace modal.
<A11yModal /> — Accessibility standards report.
<TocModal /> — Auto-generated Table of Contents drawer.

Exported Hooks & Context

useCnvtr() — Access Tiptap editor instance, commands, modal states, and settings.
useCavatorFeatures() — Access resolved feature flags configuration.
useCavatorTier() — Returns the active tier ("basic" | "premium" | "enterprise").