@phuong-tran-redoc/document-engine-core 0.0.12

package/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2025 Realestatedoc (Redoc).
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# 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.
+
+---
+
+## 🎯 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.).
+
+### 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
+
+---
+
+## 📦 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
+```
+
+### Peer Dependencies
+
+```json
+{
+  "@tiptap/core": "^2.x.x",
+  "@tiptap/pm": "^2.x.x"
+}
+```
+
+---
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```typescript
+import { Editor } from '@tiptap/core';
+import { DocumentEngineExtensions } 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],
+  content: '<p>Hello World!</p>',
+});
+```
+
+### Working with 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',
+});
+
+// Get all dynamic fields in the document
+const fields = editor.commands.getDynamicFields();
+
+// Replace field values
+editor.commands.replaceDynamicFields({
+  customer_name: 'John Doe',
+  loan_amount: '50000',
+});
+```
+
+### Restricted Editing
+
+```typescript
+import { RestrictedEditingExtension } from '@phuong-tran-redoc/document-engine-core';
+
+// Mark a region as editable
+editor.commands.setEditableRegion();
+
+// Lock the document (only editable regions can be modified)
+editor.commands.lockDocument();
+
+// Unlock the document
+editor.commands.unlockDocument();
+```
+
+---
+
+## 🏗️ Architecture
+
+```
+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
+```
+
+---
+
+## 📚 Core Extensions
+
+### Dynamic Fields Extension
+
+Allows inserting placeholder fields that can be replaced with real data.
+
+**Features:**
+
+- Insert fields: `{{field_name}}`
+- List all fields in document
+- Batch replace field values
+- Custom field styling
+
+### Restricted Editing Extension
+
+Controls which parts of the document can be edited.
+
+**Features:**
+
+- Mark editable regions
+- Lock/unlock document
+- Visual indicators for editable areas
+- Keyboard navigation between editable regions
+
+### Custom Table Extension
+
+Enhanced table support for business documents.
+
+**Features:**
+
+- Merge/split cells
+- Add/remove rows and columns
+- Table headers
+- Cell styling
+
+_(More extensions to be documented)_
+
+---
+
+## 🔧 Development
+
+### Building
+
+Build the library:
+
+```bash
+nx build document-engine-core
+```
+
+### Testing
+
+Run unit tests:
+
+```bash
+nx test document-engine-core
+```
+
+### Linting
+
+Lint the code:
+
+```bash
+nx lint document-engine-core
+```
+
+---
+
+## 🎨 Framework Wrappers
+
+This core library is designed to be wrapped by framework-specific libraries:
+
+- **Angular:** [`@phuong-tran-redoc/document-engine-angular`](../document-engine-angular)
+
+---
+
+## 📖 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
+
+- [Tiptap Documentation](https://tiptap.dev)
+- [ProseMirror Documentation](https://prosemirror.net)
+- [Main Project Repository](#)
+
+---
+
+## 👤 Author
+
+Developed by **Duc Phuong (Jack)**
+
+- 💼 [LinkedIn](https://www.linkedin.com/in/tdp1999/)
+- 🐙 [GitHub](https://github.com/tdp1999)
+- 📧 [Email](mailto:tdp99.business@gmail.com)
+
+---
+
+## 📄 License
+
+**MIT License**
+
+See [LICENSE.md](./LICENSE.md) for full license text.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@phuong-tran-redoc/document-engine-core",
+  "version": "0.0.12",
+  "type": "commonjs",
+  "license": "MIT",
+  "author": "Duc Phuong (Jack) <tdp99.business@gmail.com>",
+  "description": "Framework-agnostic core library for Document Engine",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/phuong-tran-redoc/document-engine"
+  },
+  "publishConfig": {
+    "directory": "../../dist/libs/document-engine-core",
+    "access": "public"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0",
+    "@tiptap/core": "^3.10.5",
+    "@tiptap/extension-heading": "^3.10.5",
+    "@tiptap/extension-table": "^3.10.5",
+    "@tiptap/pm": "^3.10.5",
+    "@tiptap/extension-list": "^3.10.5",
+    "@tiptap/extension-paragraph": "^3.10.5"
+  },
+  "peerDependencies": {
+    "lodash-es": "^4.17.10"
+  }
+}

package/src/constants/indent.constant.d.ts

@@ -0,0 +1 @@
+export declare const INDENT_DEFAULT = 40;

package/src/constants/indent.constant.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "INDENT_DEFAULT", {
+    enumerable: true,
+    get: function() {
+        return INDENT_DEFAULT;
+    }
+});
+const INDENT_DEFAULT = 40; // in pixels

package/src/constants/index.d.ts

@@ -0,0 +1 @@
+export * from './indent.constant';

package/src/constants/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./indent.constant"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}

package/src/constants/table.constant.d.ts

@@ -0,0 +1 @@
+export declare const MIN_NEW_COL_WIDTH = 5;

package/src/constants/table.constant.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "MIN_NEW_COL_WIDTH", {
+    enumerable: true,
+    get: function() {
+        return MIN_NEW_COL_WIDTH;
+    }
+});
+const MIN_NEW_COL_WIDTH = 5.0;

package/src/extensions/clear-content.extension.d.ts

@@ -0,0 +1,9 @@
+import { Extension } from '@tiptap/core';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        clear: {
+            clear: () => ReturnType;
+        };
+    }
+}
+export declare const ClearContent: Extension<any, any>;

package/src/extensions/clear-content.extension.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "ClearContent", {
+    enumerable: true,
+    get: function() {
+        return ClearContent;
+    }
+});
+const _core = require("@tiptap/core");
+const ClearContent = _core.Extension.create({
+    name: 'clearContent',
+    addCommands () {
+        return {
+            clear: ()=>({ chain })=>chain().focus().clearContent().run()
+        };
+    }
+});

package/src/extensions/indent.extension.d.ts

@@ -0,0 +1,16 @@
+import { Extension } from '@tiptap/core';
+export interface IndentOptions {
+    types: string[];
+    indent: number;
+}
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        increaseIndent: {
+            increaseIndent: () => ReturnType;
+        };
+        decreaseIndent: {
+            decreaseIndent: () => ReturnType;
+        };
+    }
+}
+export declare const Indent: Extension<IndentOptions, any>;

package/src/extensions/indent.extension.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "Indent", {
+    enumerable: true,
+    get: function() {
+        return Indent;
+    }
+});
+const _core = require("@tiptap/core");
+const _constants = require("../constants");
+const Indent = _core.Extension.create({
+    name: 'indent',
+    addOptions () {
+        return {
+            types: [
+                'paragraph',
+                'heading'
+            ],
+            indent: _constants.INDENT_DEFAULT
+        };
+    },
+    addGlobalAttributes () {
+        return [
+            {
+                types: this.options.types,
+                attributes: {
+                    indent: {
+                        parseHTML: (element)=>{
+                            return Number(element.style.marginLeft.replace('px', ''));
+                        },
+                        renderHTML: (attributes)=>{
+                            return {
+                                style: `margin-left: ${attributes['indent']}px`
+                            };
+                        }
+                    }
+                }
+            }
+        ];
+    },
+    addCommands () {
+        return {
+            increaseIndent: ()=>({ state, chain })=>{
+                    const currentNode = state.selection.$head.parent;
+                    const nodeType = currentNode.type;
+                    if (!this.options.types.includes(nodeType.name)) return false;
+                    const currentIndent = currentNode.attrs['indent'] || 0;
+                    const newIndent = currentIndent + this.options.indent;
+                    return chain().updateAttributes(nodeType, {
+                        indent: newIndent
+                    }).run();
+                },
+            decreaseIndent: ()=>({ state, chain })=>{
+                    const currentNode = state.selection.$head.parent;
+                    const nodeType = currentNode.type;
+                    if (!this.options.types.includes(nodeType.name)) return false;
+                    const currentIndent = currentNode.attrs['indent'] || 0;
+                    const newIndent = currentIndent - this.options.indent;
+                    if (newIndent < 0) return false;
+                    if (newIndent === 0) return chain().resetAttributes(nodeType, 'indent').run();
+                    return chain().updateAttributes(nodeType, {
+                        indent: newIndent
+                    }).run();
+                }
+        };
+    }
+});

package/src/extensions/index.d.ts

@@ -0,0 +1,8 @@
+export * from './clear-content.extension';
+export * from './indent.extension';
+export * from './ordered-list.extension';
+export * from './reset-format.extension';
+export * from './reset-on-enter.extension';
+export * from './restricted-editing.extension';
+export * from './table-style.extension';
+export * from './text-case.extension';

package/src/extensions/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./clear-content.extension"), exports);
+_export_star(require("./indent.extension"), exports);
+_export_star(require("./ordered-list.extension"), exports);
+_export_star(require("./reset-format.extension"), exports);
+_export_star(require("./reset-on-enter.extension"), exports);
+_export_star(require("./restricted-editing.extension"), exports);
+_export_star(require("./table-style.extension"), exports);
+_export_star(require("./text-case.extension"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}

package/src/extensions/ordered-list.extension.d.ts

@@ -0,0 +1,13 @@
+import { ListStyleType } from '../types';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        customOrderedList: {
+            toggleOrderedList: () => ReturnType;
+            setListStyle: (listStyleType: ListStyleType) => ReturnType;
+        };
+    }
+}
+export interface CustomOrderedListOptions {
+    listStyleType?: ListStyleType;
+}
+export declare const CustomOrderedList: import("@tiptap/core").Node<CustomOrderedListOptions, any>;

package/src/extensions/ordered-list.extension.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "CustomOrderedList", {
+    enumerable: true,
+    get: function() {
+        return CustomOrderedList;
+    }
+});
+const _extensionlist = require("@tiptap/extension-list");
+const CustomOrderedList = _extensionlist.OrderedList.extend({
+    name: 'customOrderedList',
+    addOptions () {
+        return {
+            ...this.parent?.(),
+            listStyleType: 'decimal'
+        };
+    },
+    addAttributes () {
+        return {
+            ...this.parent?.(),
+            'data-list-style-type': {
+                default: this.options.listStyleType,
+                parseHTML: (element)=>element.getAttribute('data-list-style-type') || this.options.listStyleType,
+                renderHTML: (attributes)=>{
+                    const styleType = attributes['data-list-style-type'];
+                    if (!styleType || styleType === 'decimal') return {
+                        'data-list-style-type': 'decimal'
+                    };
+                    return {
+                        'data-list-style-type': attributes['data-list-style-type']
+                    };
+                }
+            }
+        };
+    },
+    addCommands () {
+        return {
+            ...this.parent?.(),
+            setListStyle: (listStyleType)=>({ chain })=>{
+                    return chain().focus().updateAttributes('customOrderedList', {
+                        'data-list-style-type': listStyleType
+                    }).run();
+                }
+        };
+    }
+});

package/src/extensions/reset-format.extension.d.ts

@@ -0,0 +1,9 @@
+import { Extension } from '@tiptap/core';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        resetFormat: {
+            resetFormat: () => ReturnType;
+        };
+    }
+}
+export declare const ResetFormat: Extension<any, any>;

package/src/extensions/reset-format.extension.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "ResetFormat", {
+    enumerable: true,
+    get: function() {
+        return ResetFormat;
+    }
+});
+const _core = require("@tiptap/core");
+const ResetFormat = _core.Extension.create({
+    name: 'resetFormat',
+    addCommands () {
+        return {
+            resetFormat: ()=>({ chain })=>chain().focus().unsetAllMarks().clearNodes().run()
+        };
+    }
+});

package/src/extensions/reset-on-enter.extension.d.ts

@@ -0,0 +1,2 @@
+import { Extension } from '@tiptap/core';
+export declare const ResetOnEnter: Extension<any, any>;

package/src/extensions/reset-on-enter.extension.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "ResetOnEnter", {
+    enumerable: true,
+    get: function() {
+        return ResetOnEnter;
+    }
+});
+const _core = require("@tiptap/core");
+const ResetOnEnter = _core.Extension.create({
+    name: 'resetOnEnter',
+    addKeyboardShortcuts () {
+        return {
+            Enter: ()=>{
+                const disabledNodes = [
+                    'listItem',
+                    'blockquote'
+                ];
+                if (disabledNodes.some((type)=>this.editor.isActive(type))) {
+                    return false; //Let the default Enter behavior proceed
+                }
+                // Handle Enter ourselves so we can both clear marks and reset indent on the new line
+                return this.editor.chain().focus().unsetAllMarks().splitBlock({
+                    keepMarks: false
+                }).command(({ state, commands })=>{
+                    const parent = state.selection.$head.parent;
+                    const nodeType = parent.type;
+                    const typesToReset = [
+                        'paragraph',
+                        'heading'
+                    ];
+                    if (typesToReset.includes(nodeType.name)) {
+                        return commands.resetAttributes(nodeType, 'indent');
+                    }
+                    return true;
+                }).run();
+            }
+        };
+    }
+});

package/src/extensions/restricted-editing.extension.d.ts

@@ -0,0 +1,17 @@
+import { Extension, Node } from '@tiptap/core';
+export declare const EditableRegion: Node<any, any>;
+export interface RestrictedEditingOptions {
+    editableRegionNodeName: string;
+    disabledNodeTypes: string[];
+    initialMode: 'standard' | 'restricted';
+}
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        restrictedEditing: {
+            wrapSelectionInEditableRegion: () => ReturnType;
+            removeEditableRegion: () => ReturnType;
+            toggleEditableRegion: () => ReturnType;
+        };
+    }
+}
+export declare const RestrictedEditing: Extension<RestrictedEditingOptions, any>;