@phuong-tran-redoc/document-engine-angular 0.1.0 → 0.1.1

package/README.md

@@ -2,49 +2,51 @@
 
 [![npm angular](https://img.shields.io/npm/v/@phuong-tran-redoc/document-engine-angular?label=@phuong-tran-redoc/document-engine-angular&color=red)](https://www.npmjs.com/package/@phuong-tran-redoc/document-engine-angular) ![License](https://img.shields.io/npm/l/@phuong-tran-redoc/document-engine-core)
 
-Angular wrapper for [`@phuong-tran-redoc/document-engine-core`](https://www.npmjs.com/package/@phuong-tran-redoc/document-engine-core). This library provides Angular components, directives, and services to integrate the Document Engine into Angular applications.
+Angular wrapper for [`@phuong-tran-redoc/document-engine-core`](https://www.npmjs.com/package/@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` is a comprehensive Angular wrapper that makes it easy to use the Document Engine in Angular applications. It provides pre-built components, reactive state management, and Angular-specific utilities.
+`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
 
-- **Angular Components:** Ready-to-use `<document-editor>` component
-- **Reactive API:** RxJS-based state management
-- **Template-Driven:** Angular template syntax support
-- **Form Integration:** Works with Angular Forms (ngModel, Reactive Forms)
-- **Accessibility:** ARIA-compliant components
-- **Standalone Components:** Works with standalone Angular components
-- **Type Safety:** Full TypeScript support
+- **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
 
-> ⚠️ **This is a private package. Please contact an authorized person to install it.**
-
 ```bash
 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
 
 ```json
 {
-  "@angular/core": "^17.0.0 || ^18.0.0",
-  "@angular/common": "^17.0.0 || ^18.0.0",
-  "@phuong-tran-redoc/document-engine-core": "^1.0.0"
+  "@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 to your `angular.json` or import in your global styles:
+Add the SCSS entry to your global styles (or `angular.json` styles array):
 
 ```scss
 // styles.scss
@@ -55,287 +57,149 @@ Add to your `angular.json` or import in your global styles:
 
 ## 🚀 Quick Start
 
-### Basic Usage
+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.
 
-#### Standalone Component
+### Basic usage (`ngModel`)
 
 ```typescript
 import { Component } from '@angular/core';
-import { DocumentEditorComponent } from '@phuong-tran-redoc/document-engine-angular';
+import { FormsModule } from '@angular/forms';
+import {
+  DocumentEditorModule,
+  DocumentEngineConfig,
+  Editor,
+} from '@phuong-tran-redoc/document-engine-angular';
 
 @Component({
   selector: 'app-my-editor',
-  standalone: true,
-  imports: [DocumentEditorComponent],
-  template: ` <document-editor [content]="content" (contentChange)="onContentChange($event)" /> `,
+  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 {
-  content = '<p>Hello World!</p>';
+  value = '<p>Hello World!</p>';
+
+  config: Partial<DocumentEngineConfig> = {
+    bold: true,
+    italic: true,
+    underline: true,
+    list: true,
+    heading: true,
+    textAlign: true,
+    showFooter: true,
+    characterCount: true,
+  };
 
-  onContentChange(newContent: string) {
-    console.log('Content changed:', newContent);
+  onEditorReady(editor: Editor) {
+    // `editor` is the Tiptap instance — read/write content via its API
+    console.log('HTML:', editor.getHTML());
+    console.log('JSON:', editor.getJSON());
   }
 }
 ```
 
-#### Module-Based
-
-```typescript
-import { NgModule } from '@angular/core';
-import { DocumentEditorModule } from '@phuong-tran-redoc/document-engine-angular';
-
-@NgModule({
-  imports: [DocumentEditorModule],
-  // ...
-})
-export class AppModule {}
-```
-
-### With Angular Forms
-
-#### Template-Driven Forms
-
-```typescript
-import { Component } from '@angular/core';
-import { FormsModule } from '@angular/forms';
-import { DocumentEditorComponent } from '@phuong-tran-redoc/document-engine-angular';
-
-@Component({
-  selector: 'app-form-editor',
-  standalone: true,
-  imports: [FormsModule, DocumentEditorComponent],
-  template: `
-    <document-editor [(ngModel)]="documentContent" />
-    <pre>{{ documentContent }}</pre>
-  `,
-})
-export class FormEditorComponent {
-  documentContent = '<p>Edit me!</p>';
-}
-```
+> `DocumentEditorComponent` is **not** a standalone component — import `DocumentEditorModule` (which also exports `TiptapEditorDirective`).
 
-#### Reactive Forms
+### Reactive Forms (`formControl`)
 
 ```typescript
 import { Component } from '@angular/core';
 import { FormControl, ReactiveFormsModule } from '@angular/forms';
-import { DocumentEditorComponent } from '@phuong-tran-redoc/document-engine-angular';
+import { DocumentEditorModule, DocumentEngineConfig } from '@phuong-tran-redoc/document-engine-angular';
 
 @Component({
   selector: 'app-reactive-editor',
-  standalone: true,
-  imports: [ReactiveFormsModule, DocumentEditorComponent],
-  template: ` <document-editor [formControl]="editorControl" /> `,
-})
-export class ReactiveEditorComponent {
-  editorControl = new FormControl('<p>Content</p>');
-}
-```
-
-### Advanced Configuration
-
-```typescript
-import { Component } from '@angular/core';
-import { DocumentEditorComponent, EditorConfig } from '@phuong-tran-redoc/document-engine-angular';
-
-@Component({
-  selector: 'app-advanced-editor',
-  standalone: true,
-  imports: [DocumentEditorComponent],
+  imports: [ReactiveFormsModule, DocumentEditorModule],
   template: `
-    <document-editor
-      [config]="editorConfig"
-      [readonly]="isReadonly"
-      [showToolbar]="true"
-      (ready)="onEditorReady($event)"
-    />
+    <document-engine-editor #docEditor [config]="config">
+      <tiptap-editor [editor]="docEditor.editor" [formControl]="control" outputFormat="json"></tiptap-editor>
+    </document-engine-editor>
   `,
 })
-export class AdvancedEditorComponent {
-  isReadonly = false;
-
-  editorConfig: EditorConfig = {
-    extensions: ['dynamic-fields', 'restricted-editing', 'tables'],
-    placeholder: 'Start typing...',
-    autoFocus: true,
-  };
-
-  onEditorReady(editor: Editor) {
-    console.log('Editor is ready!', editor);
-  }
+export class ReactiveEditorComponent {
+  control = new FormControl('<p>Content</p>');
+  config: Partial<DocumentEngineConfig> = { bold: true, italic: true, list: true };
 }
 ```
 
----
-
-## 🧩 Components
-
-### DocumentEditorComponent
-
-The main editor component.
-
-**Inputs:**
-
-- `content: string | JSONContent` - Initial content (HTML or JSON)
-- `config: EditorConfig` - Editor configuration
-- `readonly: boolean` - Read-only mode
-- `showToolbar: boolean` - Show/hide toolbar
-- `placeholder: string` - Placeholder text
+`outputFormat` accepts `'html'` (default) or `'json'`.
 
-**Outputs:**
-
-- `contentChange: EventEmitter<string>` - Emits when content changes
-- `ready: EventEmitter<Editor>` - Emits when editor is ready
-- `focus: EventEmitter<void>` - Emits when editor gains focus
-- `blur: EventEmitter<void>` - Emits when editor loses focus
-
-**Methods:**
-
-- `getContent(): string` - Get current content as HTML
-- `getJSON(): JSONContent` - Get current content as JSON
-- `setContent(content: string | JSONContent): void` - Set editor content
-- `focus(): void` - Focus the editor
-
-### DocumentEditorToolbarComponent
-
-Customizable toolbar component.
+---
 
-```typescript
-<document-editor-toolbar [editor]="editor" />
-```
+## 🧩 Public API
 
-### DynamicFieldPickerComponent
+### `DocumentEditorComponent`
 
-UI for inserting dynamic fields.
+The wrapper that hosts config, toolbar, and footer.
 
-```typescript
-<dynamic-field-picker
-  [fields]="availableFields"
-  (fieldSelect)="onFieldSelect($event)"
-/>
-```
+- **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`
 
-## 📚 Services
+The Forms-aware directive you project inside the wrapper.
 
-### DocumentEditorService
+- **Selector:** `tiptap[editor]`, `[tiptap][editor]`, `tiptap-editor[editor]`, `[tiptapEditor][editor]`
+- **Inputs:** `editor: Editor`, `outputFormat: 'json' | 'html'` (default `'html'`)
+- Implements `ControlValueAccessor` → `ngModel` / `formControl` support.
 
-Service for managing editor instances.
+### `DocumentEditorModule`
 
-```typescript
-import { DocumentEditorService } from '@phuong-tran-redoc/document-engine-angular';
+Declares `DocumentEditorComponent`; exports `DocumentEditorComponent` + `TiptapEditorDirective` (imports the toolbar/footer internally).
 
-export class MyComponent {
-  constructor(private editorService: DocumentEditorService) {}
+### UI components & directives (standalone)
 
-  createEditor() {
-    const editor = this.editorService.create({
-      // configuration
-    });
-  }
-}
-```
+`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`.
 
-### DynamicFieldService
+### Services & tokens
 
-Service for managing dynamic fields.
+- `FocusTrapService`, `EventManager` (both `providedIn: 'root'`).
+- DI tokens: `EDITOR_CONTENT_WRAPPER_CLASS`, `EDITOR_HTML_PREPROCESSOR`.
 
-```typescript
-import { DynamicFieldService } from '@phuong-tran-redoc/document-engine-angular';
+### `DocumentEngineConfig`
 
-export class MyComponent {
-  constructor(private fieldService: DynamicFieldService) {}
+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.
 
-  replaceFields() {
-    this.fieldService.replaceFields({
-      customer_name: 'John Doe',
-      loan_amount: '50000',
-    });
-  }
-}
-```
+> The package entry `index.ts` is the public contract — additive changes only between minor versions.
 
 ---
 
 ## 🎨 Styling
 
-### Custom Themes
-
-```scss
-// Override CSS variables
-:root {
-  --doc-editor-bg: #ffffff;
-  --doc-editor-text: #000000;
-  --doc-editor-border: #e0e0e0;
-  --doc-editor-focus: #007bff;
-}
-```
-
-### Custom CSS Classes
-
-```html
-<document-editor class="my-custom-editor" />
-```
-
-```scss
-.my-custom-editor {
-  // Your custom styles
-}
-```
+Import the SCSS entry (see [Installation](#importing-styles)). The editor ships a Tailwind + SCSS design system; theme it through your global stylesheet alongside your app's design tokens.
 
 ---
 
 ## 🔧 Development
 
-### Building
-
-Build the library:
-
 ```bash
-nx build document-engine-angular
-```
-
-### Testing
-
-Run unit tests:
-
-```bash
-nx test document-engine-angular
-```
-
-### Linting
-
-Lint the code:
-
-```bash
-nx lint document-engine-angular
+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
 ```
 
 ---
 
-## 📖 Documentation
+## 🔗 Related
 
-- **[Live Demo](#)** - See the editor in action
-- **[API Reference](#)** - Detailed API documentation
-- **[Examples](#)** - Code examples and use cases
-- **[Migration Guide](#)** - Migrating from other editors
-
----
-
-## 🔗 Related Packages
-
-- **Core Library:** [`@phuong-tran-redoc/document-engine-core`](../document-engine-core)
-- **Demo Application:** [document-engine](../../apps/document-engine)
+- **Core library:** [`@phuong-tran-redoc/document-engine-core`](../document-engine-core/README.md)
+- 📦 [npm package](https://www.npmjs.com/package/@phuong-tran-redoc/document-engine-angular)
+- 📝 [Changelog](../../CHANGELOG.md)
+- 🐙 [Repository](https://github.com/phuong-tran-redoc/document-engine)
+- ▶️ [Demo app](https://github.com/phuong-tran-redoc/document-engine) — clone the repo and run `pnpm start` (http://localhost:4200)
 
 ---
 
 ## 🤝 Compatibility
 
-| Angular Version | Package Version |
-| --------------- | --------------- |
-| 17.x            | 1.x             |
-| 18.x            | 1.x             |
+| Angular | Package |
+| --- | --- |
+| 16.x – 21.x | 0.x |
 
 ---
 
@@ -351,6 +215,4 @@ Developed by **Duc Phuong (Jack)**
 
 ## 📄 License
 
-**MIT License**
-
-See [LICENSE.md](./LICENSE.md) for full license text.
+**MIT License** — see [LICENSE.md](./LICENSE.md).

package/THIRD-PARTY-NOTICES.txt

@@ -0,0 +1,67 @@
+THIRD-PARTY SOFTWARE NOTICES
+
+The Document Engine packages bundle or depend on the third-party software listed
+below (the full production dependency closure). Each is distributed under its own
+license; the full license text ships within each package in node_modules and is
+available at the linked repository.
+
+==============================================================================
+
+@angular/cdk@20.2.12
+  license: MIT
+  repository: https://github.com/angular/components
+
+@angular/common@20.3.10
+  license: MIT
+  repository: https://github.com/angular/angular
+  publisher: angular
+
+@angular/compiler@20.3.10
+  license: MIT
+  repository: https://github.com/angular/angular
+  publisher: angular
+
+@angular/core@20.3.10
+  license: MIT
+  repository: https://github.com/angular/angular
+  publisher: angular
+
+@angular/forms@20.3.10
+  license: MIT
+  repository: https://github.com/angular/angular
+  publisher: angular
+
+@angular/material@20.2.12
+  license: MIT
+  repository: https://github.com/angular/components
+
+@angular/platform-browser-dynamic@20.3.10
+  license: MIT
+  repository: https://github.com/angular/angular
+  publisher: angular
+
+@angular/platform-browser@20.3.10
+  license: MIT
+  repository: https://github.com/angular/angular
+  publisher: angular
+
+@angular/router@20.3.10
+  license: MIT
+  repository: https://github.com/angular/angular
+  publisher: angular
+
+lodash-es@4.17.21
+  license: MIT
+  repository: https://github.com/lodash/lodash
+  publisher: John-David Dalton
+
+rxjs@7.8.2
+  license: Apache-2.0
+  repository: https://github.com/reactivex/rxjs
+  publisher: Ben Lesh
+
+zone.js@0.15.1
+  license: MIT
+  repository: https://github.com/angular/angular
+  publisher: Brian Ford
+