ngx-exitus-tiptap-editor

A powerful, feature-rich Tiptap-based Rich Text Editor for Angular 18+, specifically designed for educational and technical content.

✨ Features

• 📐 Scientific Formula Support: Full KaTeX and MathType integration.
• 🖼️ Advanced Image Handling: Responsive images with figures, captions, alignment, and resizing handles.
• 🛠️ Custom Extensions:
  • Indent: Control line indentation.
  • Tab: Custom tab key behavior.
  • ColarQuestao: Specialized tool for pasting educational questions.
• 🎨 Modern UI: Clean toolbar and floating menus for formula and image editing.
• ⚡ Angular 18+ Ready: Built with the latest Angular features (signals, inputs/outputs).

🚀 Installation

To install the library, run:

npm install ngx-exitus-tiptap-editor

Peer Dependencies

This library depends on several Tiptap packages and KaTeX. Ensure you have them installed in your project:

npm install @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extension-subscript @tiptap/extension-superscript @tiptap/extension-text-align @tiptap/extension-bubble-menu katex

⚙️ Configuration

WASM Assets Setup (Required)

To use the MathType features properly, you must configure your Angular application to serve the WebAssembly files. Update your angular.json by adding the following to the assets array (in both build and test targets):

"assets": [
  "src/favicon.ico",
  "src/assets",
  {
    "glob": "**/*.wasm",
    "input": "node_modules/ngx-exitus-tiptap-editor/assets/telemeter-wasm",
    "output": "assets/mathtype/"
  }
]

Important

If this configuration is missing, you will encounter 404 (Not Found) errors for the WebAssembly files when using formulas.

📦 Usage

1. Import the Component

In your component file:

import { ExitusTiptapEditor } from 'ngx-exitus-tiptap-editor';

@Component({
  standalone: true,
  imports: [ExitusTiptapEditor],
  // ...
})
export class MyAppComponent {
  editorContent = '<p>Initial content with <b>formatting</b></p>';

  handleContentChange(html: string) {
    console.log('New content:', html);
  }
}

2. Use in Template

<exitus-tiptap-editor [content]="editorContent" (onContentChange)="handleContentChange($event)">
</exitus-tiptap-editor>

---

🛠️ API Reference

Inputs

Input	Type	Default	Description
content	string	""	The initial HTML content of the editor.

Outputs

Output	Type	Description
onContentChange	EventEmitter<string>	Emits the HTML content whenever the editor is updated.

---

🧪 Extensions Detail

📐 Math & Science

• KaTeX: Write LaTeX formulas directly. Includes a floating menu for quick editing.
• MathType: Advanced formula editor integration via Wiris.

🖼️ Image Management

The editor uses a custom Figure extension that wraps images in a <figure> tag with support for:

• <figcaption> for image descriptions.
• Resizing handles (300px to 700px).
• Alignment options (left, center, right).
• Fullscreen/Wide modes.

Image Proxy

When the browser cannot load images directly from external URLs (CORS, mixed-content, etc.), configure a server-side proxy via extensionsConfig.image.proxyUrl.

Import the helper:

import { ExitusTiptapEditor, ImageProxyBuilders } from 'ngx-exitus-tiptap-editor';

Configure in your component:

extensionsConfig = {
  image: {
    proxyUrl: ImageProxyBuilders.queryParam('https://myserver.com/proxy'),
  },
};

<exitus-tiptap-editor [extensionsConfig]="extensionsConfig" />

Three built-in URL patterns:

Helper	Server receives	Best for
ImageProxyBuilders.queryParam(base)	GET /proxy?imgurl=<encoded>	Proxy simples
ImageProxyBuilders.queryParam(base, 'url')	GET /proxy?url=<encoded>	Nome de param customizado
ImageProxyBuilders.pathEncoded(base)	GET /proxy/<encoded>	REST paths
ImageProxyBuilders.postBody(base)	POST /proxy { "url": "..." }	APIs JSON

Custom function (avançado):

extensionsConfig = {
  image: {
    proxyUrl: (src: string) => `https://myserver.com/img/${btoa(src)}`,
  },
};

Retrocompatibilidade: uma string simples continua funcionando (usa queryParam internamente):

// legado — ainda suportado
extensionsConfig = {
  image: {
    proxyUrl: 'https://myserver.com/proxy',  // → GET /proxy?imgurl=<encoded>
  },
};

Tip

Um servidor de teste mínimo está disponível em tools/proxy_server.py. Basta python3 tools/proxy_server.py (porta 8765) para testar localmente.

• Indent/Outdent: Standard shortcut and toolbar support.
• Tab Handling: Consistent tab behavior within the editor.
• Colar Questão: specialized logic for pasting data into educational templates.

---

🛠 Development

Setup

Run npm install to install dependencies.

Development Server

Run npm run dev to start a development server for both the library and the test application. This command uses concurrently to watch for library changes and serve the app.

Building

Run npm run build:lib to build the library. The build artifacts will be stored in the dist/ngx-exitus-tiptap-editor directory.

---

📜 License

MIT