@phuong-tran-redoc/document-engine-core 0.1.0 → 0.1.2

package/README.md

@@ -2,210 +2,202 @@
 
 [![npm core](https://img.shields.io/npm/v/@phuong-tran-redoc/document-engine-core?label=@phuong-tran-redoc/document-engine-core&color=red)](https://www.npmjs.com/package/@phuong-tran-redoc/document-engine-core) ![License](https://img.shields.io/npm/l/@phuong-tran-redoc/document-engine-core)
 
-A **framework-agnostic** document editor core library built on top of [Tiptap](https://tiptap.dev/) and [ProseMirror](https://prosemirror.net/). This library provides the foundation for building rich-text editors with custom business logic and extensions.
+A **framework-agnostic** document editor core built on [Tiptap](https://tiptap.dev/) and [ProseMirror](https://prosemirror.net/). It packages the custom extensions, nodes, schema kit, and headless helpers that power the Document Engine, with no framework dependency.
 
 ---
 
 ## 🎯 Overview
 
-`document-engine-core` is the heart of the Document Engine system. It contains all the business logic, custom extensions, and editor functionality in a framework-agnostic manner, making it reusable across different frameworks (Angular, React, Vue, etc.).
+`document-engine-core` is the heart of the Document Engine. It contains the editor schema (the canonical extension/node set), business extensions (dynamic fields, restricted editing, styled tables, indentation, text case), a headless HTML serializer, and a small document-migration system — all as plain ESM TypeScript that runs in the browser or in Node.
 
 ### Key Features
 
-- **Framework-Agnostic:** Pure TypeScript implementation, no framework dependencies
-- **Business-Focused Extensions:**
-  - **Dynamic Fields:** Support for placeholder fields like `{{customer_name}}`
-  - **Restricted Editing:** Control which parts of documents can be edited
-  - **Custom Nodes:** Business-specific document nodes and marks
-- **Built on Proven Technology:** Leverages Tiptap and ProseMirror for robust editing
-- **JSON-based Data Model:** Documents are represented as structured JSON, not raw HTML
-- **TypeScript-First:** Full type safety and IntelliSense support
-- **Extensible Architecture:** Easy to add custom extensions and plugins
+- **Framework-agnostic ESM:** pure TypeScript, usable from Angular, React, Vue, or headless Node.
+- **Ready-made schema kit:** `defaultExtensions` — the canonical node/mark/structure set the editor ships with.
+- **Business extensions:** Dynamic Fields (`{{customer_name}}`), Restricted Editing (editable regions), Styled Tables, Indent, Text Case, custom Ordered List.
+- **Headless serialization:** `generateHTML(doc)` renders a ProseMirror JSON document to HTML on the server (env-aware) or in the browser.
+- **Document migrations:** `EditorDocument` wrapper + `migrateDoc()` to version and upgrade stored content.
+- **JSON-first data model:** documents are ProseMirror JSON, not raw HTML.
 
 ---
 
 ## 📦 Installation
 
-> ⚠️ **This is a private package. Please contact an authorized person to install it.**
-
 ```bash
 npm install @phuong-tran-redoc/document-engine-core
 # or
 pnpm add @phuong-tran-redoc/document-engine-core
 ```
 
+Published publicly on npm under the MIT license.
+
 ### Peer Dependencies
 
+Only one peer dependency — Tiptap/ProseMirror ship as bundled dependencies and are installed automatically:
+
 ```json
 {
-  "@tiptap/core": "^2.x.x",
-  "@tiptap/pm": "^2.x.x"
+  "lodash-es": "^4.17.10"
 }
 ```
 
+> Built against `@tiptap/* ^3.26.0` (bundled). If your app also uses Tiptap directly, align on the same major to share a single ProseMirror instance.
+
 ---
 
 ## 🚀 Quick Start
 
-### Basic Usage
+### Build an editor with the default schema
 
 ```typescript
 import { Editor } from '@tiptap/core';
-import { DocumentEngineExtensions } from '@phuong-tran-redoc/document-engine-core';
+import { defaultExtensions } from '@phuong-tran-redoc/document-engine-core';
 
-// Create an editor instance with Document Engine extensions
 const editor = new Editor({
-  element: document.querySelector('#editor'),
-  extensions: [...DocumentEngineExtensions],
+  element: document.querySelector('#editor')!,
+  extensions: [...defaultExtensions],
   content: '<p>Hello World!</p>',
 });
 ```
 
-### Working with Dynamic Fields
+### Dynamic fields
 
 ```typescript
-import { DynamicFieldExtension } from '@phuong-tran-redoc/document-engine-core';
-
-// Insert a dynamic field
-editor.commands.insertDynamicField({
-  name: 'customer_name',
-  label: 'Customer Name',
-});
+// Insert a {{customer_name}} placeholder
+editor.commands.insertDynamicField({ fieldId: 'customer_name', label: 'Customer Name' });
+// Renders: <span data-field-id="customer_name" data-label="Customer Name" class="dynamic-field">{{customer_name}}</span>
+```
 
-// Get all dynamic fields in the document
-const fields = editor.commands.getDynamicFields();
+### Restricted editing (editable regions)
 
-// Replace field values
-editor.commands.replaceDynamicFields({
-  customer_name: 'John Doe',
-  loan_amount: '50000',
-});
+```typescript
+// Wrap the current selection in an editable region
+editor.commands.wrapSelectionInEditableRegion();
+editor.commands.toggleEditableRegion();
+editor.commands.removeEditableRegion();
 ```
 
-### Restricted Editing
+### Other custom commands
 
 ```typescript
-import { RestrictedEditingExtension } from '@phuong-tran-redoc/document-engine-core';
+editor.commands.insertPageBreak();                      // PageBreak node
+editor.commands.insertImageRef({ imageId: 'logo-01' }); // URL-free image reference
+editor.commands.textCase('uppercase');                  // TextCase: 'uppercase' | 'lowercase' | 'capitalize'
+editor.commands.increaseIndent();                       // Indent
+editor.commands.setListStyle('lower-alpha');            // CustomOrderedList
+```
 
-// Mark a region as editable
-editor.commands.setEditableRegion();
+### Headless HTML (server-side)
 
-// Lock the document (only editable regions can be modified)
-editor.commands.lockDocument();
+```typescript
+import { generateHTML, defaultExtensions } from '@phuong-tran-redoc/document-engine-core';
 
-// Unlock the document
-editor.commands.unlockDocument();
+// generateHTML(doc: JSONContent, extensions = defaultExtensions): Promise<string>
+const html = await generateHTML(myProseMirrorJSON);
 ```
 
----
+### Versioned documents + migrations
 
-## 🏗️ Architecture
+```typescript
+import { migrateDoc, LATEST_SCHEMA_VERSION, type EditorDocument } from '@phuong-tran-redoc/document-engine-core';
 
-```
-document-engine-core/
-├── extensions/          # Custom Tiptap extensions
-│   ├── dynamic-field/   # Dynamic field support
-│   ├── restricted/      # Restricted editing
-│   └── ...
-├── nodes/              # Custom document nodes
-├── marks/              # Custom text marks
-├── plugins/            # ProseMirror plugins
-├── commands/           # Editor commands
-├── utils/              # Utility functions
-└── types/              # TypeScript type definitions
+const stored: EditorDocument = { schemaVersion: 0, content: myProseMirrorJSON };
+const upgraded = migrateDoc(stored); // walks registered migrations up to LATEST_SCHEMA_VERSION
 ```
 
 ---
 
-## 📚 Core Extensions
+## 📦 Public API
 
-### Dynamic Fields Extension
+Everything below is re-exported from the package entry (`@phuong-tran-redoc/document-engine-core`).
 
-Allows inserting placeholder fields that can be replaced with real data.
+### Extensions (`extensions`)
 
-**Features:**
+| Export | Notable commands |
+| --- | --- |
+| `ClearContent` | `clear()` |
+| `Indent` | `increaseIndent()`, `decreaseIndent()` |
+| `CustomOrderedList` | `toggleOrderedList()`, `setListStyle(type)` |
+| `ResetFormat` | `resetFormat()` |
+| `ResetOnEnter` | — (Enter-key behavior) |
+| `RestrictedEditing` (+ `EditableRegion`) | `wrapSelectionInEditableRegion()`, `toggleEditableRegion()`, `removeEditableRegion()` |
+| `StyledTable` / `StyledTableKit` (+ `StyledTableCell`, `StyledTableHeader`) | `insertTable()`, `setTableBorder()`, `setTableBackgroundColor()`, `setCellBackgroundColor()`, `setCellTextAlign()`, … |
+| `TextCase` | `textCase(type)` |
 
-- Insert fields: `{{field_name}}`
-- List all fields in document
-- Batch replace field values
-- Custom field styling
+### Nodes (`nodes`)
 
-### Restricted Editing Extension
+| Export | Renders |
+| --- | --- |
+| `DynamicField` | inline `<span data-field-id …>{{fieldId}}</span>` — `insertDynamicField({ fieldId, label })` |
+| `PageBreak` | `<div data-page-break="true" …>` — `insertPageBreak()` |
+| `ImageRef` | `<figure data-block="image-ref" data-image-id …>` (+ optional `<figcaption>`) — `insertImageRef({ imageId, caption?, captionPosition? })` |
+| `NotumHeading` | extends Tiptap `Heading` — `removeHeading()` |
 
-Controls which parts of the document can be edited.
+### Kit (`kit`)
 
-**Features:**
+- `defaultExtensions: Extensions` — the canonical schema (nodes, marks, structures).
+- `generateHTML(doc, extensions?): Promise<string>` — async, environment-aware headless serializer.
 
-- Mark editable regions
-- Lock/unlock document
-- Visual indicators for editable areas
-- Keyboard navigation between editable regions
+### Migrations (`migrations`)
 
-### Custom Table Extension
+- `EditorDocument` — `{ schemaVersion: number; content: JSONContent }`.
+- `LATEST_SCHEMA_VERSION` — current schema version.
+- `docMigrations` — the migration registry.
+- `migrateDoc(doc, migrations?, latest?)` — pure upgrade walker.
 
-Enhanced table support for business documents.
+### Models, types, utils, views
 
-**Features:**
+- **models:** `Color` (`Color.from()`, `.equals()`, `.is()`).
+- **types:** `ListStyleType`, `TextCaseType`, `ImageRefAttributes`, `DynamicFieldAttributes`, `DynamicFieldItem`, `DynamicFieldCategory`, …
+- **utils:** `normalizeColor` (color), `getClosestDomElement` (dom), `getCursorCellInfo` / `getSelectedCells` (table), `getSelectedText` / `getActiveMarkRange` (text).
+- **views:** `HandleNodeView`, `TableNodeView`, `PageBreakNodeView`, `createTableNodeView`, `createPageBreakNodeView`.
+- **constants:** `INDENT_DEFAULT`.
 
-- Merge/split cells
-- Add/remove rows and columns
-- Table headers
-- Cell styling
-
-_(More extensions to be documented)_
+> The package entry `index.ts` is the public contract — additive changes only between minor versions.
 
 ---
 
-## 🔧 Development
+## 🏗️ Source Layout
 
-### Building
-
-Build the library:
-
-```bash
-nx build document-engine-core
 ```
-
-### Testing
-
-Run unit tests:
-
-```bash
-nx test document-engine-core
+document-engine-core/src/
+├── constants/    # exported constants (e.g. INDENT_DEFAULT)
+├── extensions/   # custom Tiptap extensions
+├── kit/          # defaultExtensions + generateHTML
+├── migrations/   # EditorDocument + migrateDoc
+├── models/       # Color, …
+├── nodes/        # DynamicField, PageBreak, ImageRef, NotumHeading
+├── types/        # shared TypeScript types
+├── utils/        # color / dom / table / text helpers
+└── views/        # ProseMirror node views
 ```
 
-### Linting
+---
 
-Lint the code:
+## 🔧 Development
 
 ```bash
-nx lint document-engine-core
+nx build @phuong-tran-redoc/document-engine-core   # build the library
+nx test @phuong-tran-redoc/document-engine-core    # unit tests
+nx lint @phuong-tran-redoc/document-engine-core    # lint
 ```
 
 ---
 
 ## 🎨 Framework Wrappers
 
-This core library is designed to be wrapped by framework-specific libraries:
-
-- **Angular:** [`@phuong-tran-redoc/document-engine-angular`](../document-engine-angular)
+- **Angular:** [`@phuong-tran-redoc/document-engine-angular`](../document-engine-angular/README.md)
 
 ---
 
-## 📖 Documentation
-
-- **[Live Demo](#)** - See the editor in action
-- **[API Reference](#)** - Detailed API documentation
-- **[Examples](#)** - Code examples and use cases
-- **[Contributing](#)** - How to contribute
-
----
-
-## 🔗 Related Resources
+## 📖 Resources
 
+- 📦 [npm package](https://www.npmjs.com/package/@phuong-tran-redoc/document-engine-core)
+- 📝 [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)
 - [Tiptap Documentation](https://tiptap.dev)
 - [ProseMirror Documentation](https://prosemirror.net)
-- [Main Project Repository](#)
 
 ---
 
@@ -221,6 +213,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
+

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/index";