document-engine-angular

Angular wrapper for @phuong-tran-redoc/document-engine-core. Provides the <document-engine-editor> component, a ControlValueAccessor directive for Angular Forms, a configurable toolbar/footer, and supporting UI primitives.

🎯 Overview

document-engine-angular makes the framework-agnostic core usable in Angular apps. You drive features with a single config object, project a tiptap-editor directive for two-way binding, and get a toolbar, footer, and character count out of the box.

Key Features

• Editor component: <document-engine-editor [config]="…"> with content projection.
• Angular Forms: the inner tiptap-editor directive implements ControlValueAccessor — works with ngModel and formControl (HTML or JSON output).
• Config-driven features: toggle bold/italic/underline, lists, headings, tables, indent, text-case, dynamic fields, restricted editing, … via DocumentEngineConfig.
• UI building blocks: toolbar, footer, character count, color picker, select, icon, buttons — all themeable.
• SCSS design system: import one stylesheet entry to get the editor styling.

📦 Installation

npm install @phuong-tran-redoc/document-engine-angular
# or
pnpm add @phuong-tran-redoc/document-engine-angular

Published publicly on npm under the MIT license. The core package is installed automatically as a dependency.

Peer Dependencies

{
  "@angular/core": ">=16.0.0 <22.0.0",
  "@angular/common": ">=16.0.0 <22.0.0",
  "@angular/forms": ">=16.0.0 <22.0.0",
  "@angular/platform-browser": ">=16.0.0 <22.0.0",
  "rxjs": "^7.5.0"
}

Supports Angular 16 → 21. Built against @tiptap/* ^3.26.0 (pulled in via the core dependency).

Importing Styles

Add the SCSS entry to your global styles (or angular.json styles array):

// styles.scss
@import '@phuong-tran-redoc/document-engine-angular/styles';

🚀 Quick Start

The editor uses content projection: <document-engine-editor> owns the config + toolbar/footer and exposes the live editor instance; you project a tiptap-editor directive that binds the editor and provides Forms support.

Basic usage (ngModel)

import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
  DocumentEditorModule,
  DocumentEngineConfig,
  Editor,
} from '@phuong-tran-redoc/document-engine-angular';

@Component({
  selector: 'app-my-editor',
  imports: [FormsModule, DocumentEditorModule],
  template: `
    <document-engine-editor #docEditor [config]="config" (editorReady)="onEditorReady($event)">
      <tiptap-editor [editor]="docEditor.editor" [(ngModel)]="value"></tiptap-editor>
    </document-engine-editor>
  `,
})
export class MyEditorComponent {
  value = '<p>Hello World!</p>';

  config: Partial<DocumentEngineConfig> = {
    bold: true,
    italic: true,
    underline: true,
    list: true,
    heading: true,
    textAlign: true,
    showFooter: true,
    characterCount: true,
  };

  onEditorReady(editor: Editor) {
    // `editor` is the Tiptap instance — read/write content via its API
    console.log('HTML:', editor.getHTML());
    console.log('JSON:', editor.getJSON());
  }
}

DocumentEditorComponent is not a standalone component — import DocumentEditorModule (which also exports TiptapEditorDirective).

Reactive Forms (formControl)

import { Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { DocumentEditorModule, DocumentEngineConfig } from '@phuong-tran-redoc/document-engine-angular';

@Component({
  selector: 'app-reactive-editor',
  imports: [ReactiveFormsModule, DocumentEditorModule],
  template: `
    <document-engine-editor #docEditor [config]="config">
      <tiptap-editor [editor]="docEditor.editor" [formControl]="control" outputFormat="json"></tiptap-editor>
    </document-engine-editor>
  `,
})
export class ReactiveEditorComponent {
  control = new FormControl('<p>Content</p>');
  config: Partial<DocumentEngineConfig> = { bold: true, italic: true, list: true };
}

outputFormat accepts 'html' (default) or 'json'.

🧩 Public API

DocumentEditorComponent

The wrapper that hosts config, toolbar, and footer.

• Selector: document-engine-editor
• Input: config?: Partial<DocumentEngineConfig>
• Output: editorReady: EventEmitter<Editor> — fires once the Tiptap editor is constructed
• Exposed property: editor: Editor (project into tiptap-editor and read content via the Tiptap API: getHTML(), getJSON(), getText())

TiptapEditorDirective

The Forms-aware directive you project inside the wrapper.

• Selector: tiptap[editor], [tiptap][editor], tiptap-editor[editor], [tiptapEditor][editor]
• Inputs: editor: Editor, outputFormat: 'json' | 'html' (default 'html')
• Implements ControlValueAccessor → ngModel / formControl support.

DocumentEditorModule

Declares DocumentEditorComponent; exports DocumentEditorComponent + TiptapEditorDirective (imports the toolbar/footer internally).

UI components & directives (standalone)

ToolbarComponent (document-engine-toolbar), FooterComponent (document-engine-footer), CharacterCountComponent (document-engine-character-count), ColorPickerComponent (document-engine-color-picker), SelectComponent (document-engine-select), IconComponent (document-engine-icon), ToggleGroupComponent, CheckboxComponent, plus directives ButtonDirective (button[documentEngineButton]), InputDirective, TiptapFloatingMenuDirective, TiptapDraggableDirective, PopoverDirective.

Services & tokens

• FocusTrapService, EventManager (both providedIn: 'root').
• DI tokens: EDITOR_CONTENT_WRAPPER_CLASS, EDITOR_HTML_PREPROCESSOR.

DocumentEngineConfig

The feature-toggle object passed to [config]. Each key is a boolean or an options object — e.g. undoRedo, bold, italic, underline, strike, subscript, superscript, code, codeBlock, blockquote, link, heading, fontSize, lineHeight, textCase, textAlign, indent, list, textStyleKit, resetFormat, image, showFooter, characterCount, and more.

The package entry index.ts is the public contract — additive changes only between minor versions.

🎨 Styling

Import the SCSS entry (see Installation). The editor ships a Tailwind + SCSS design system; theme it through your global stylesheet alongside your app's design tokens.

🔧 Development

nx build @phuong-tran-redoc/document-engine-angular   # build the library
nx test @phuong-tran-redoc/document-engine-angular    # unit tests
nx lint @phuong-tran-redoc/document-engine-angular    # lint

🔗 Related

• Core library: @phuong-tran-redoc/document-engine-core
• 📦 npm package
• 📝 Changelog
• 🐙 Repository
• ▶️ Demo app — clone the repo and run pnpm start (http://localhost:4200)

🤝 Compatibility

| Angular | Package | | --- | --- | | 16.x – 21.x | 0.x |

👤 Author

Developed by Duc Phuong (Jack)

• 💼 LinkedIn
• 🐙 GitHub
• 📧 Email

📄 License

MIT License — see LICENSE.md.