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

package/src/index.js

@@ -1,9 +0,0 @@
-export * from './constants';
-export * from './extensions';
-export * from './kit';
-export * from './migrations';
-export * from './models';
-export * from './nodes';
-export * from './types';
-export * from './utils';
-export * from './views';

package/src/kit/default-extensions.js

@@ -1,86 +0,0 @@
-import Blockquote from '@tiptap/extension-blockquote';
-import Bold from '@tiptap/extension-bold';
-import Code from '@tiptap/extension-code';
-import CodeBlock from '@tiptap/extension-code-block';
-import { Document } from '@tiptap/extension-document';
-import { HardBreak } from '@tiptap/extension-hard-break';
-import { HorizontalRule } from '@tiptap/extension-horizontal-rule';
-import { Image } from '@tiptap/extension-image';
-import Italic from '@tiptap/extension-italic';
-import Link from '@tiptap/extension-link';
-import { BulletList, ListItem } from '@tiptap/extension-list';
-import { Paragraph } from '@tiptap/extension-paragraph';
-import Strike from '@tiptap/extension-strike';
-import { Subscript } from '@tiptap/extension-subscript';
-import { Superscript } from '@tiptap/extension-superscript';
-import { Text } from '@tiptap/extension-text';
-import { TextAlign } from '@tiptap/extension-text-align';
-import { TextStyleKit } from '@tiptap/extension-text-style';
-import Underline from '@tiptap/extension-underline';
-import { CustomOrderedList } from '../extensions/ordered-list.extension';
-import { StyledTableKit } from '../extensions/table-style.extension';
-import { DynamicField } from '../nodes/dynamic-field.node';
-import { NotumHeading } from '../nodes/heading.node';
-import { ImageRef } from '../nodes/image-ref.node';
-import { PageBreak } from '../nodes/page-break.node';
-/**
- * Canonical default extension list for headless (Node-safe) serialization.
- *
- * This is the schema half of the editor's runtime kit (`DocumentEngineKit` in
- * the Angular wrapper): every node, mark, and HTML-affecting attribute the
- * editor can persist, so {@link generateHTML} can turn stored document JSON back
- * into HTML without a browser.
- *
- * It deliberately omits editing-only plugins (history/undo-redo, drop/gap
- * cursors, placeholder, character count, list keymaps, trailing node). Those
- * shape the live editing experience but contribute nothing to serialized
- * output, and some attach view-level behavior that has no meaning headless.
- *
- * Only `renderHTML` is exercised during serialization — node views (which touch
- * the DOM, e.g. `DynamicField.addNodeView`) are never invoked here, so this list
- * is safe to import and run in Node.
- *
- * Callers needing a different schema (e.g. restricted-editing regions, or a
- * trimmed set) should pass their own array to {@link generateHTML} instead.
- */ export const defaultExtensions = [
-    // Structure
-    Document,
-    Paragraph,
-    Text,
-    NotumHeading,
-    HardBreak,
-    HorizontalRule,
-    Blockquote,
-    CodeBlock,
-    // Lists
-    BulletList,
-    ListItem,
-    CustomOrderedList,
-    // Marks
-    Bold,
-    Italic,
-    Underline,
-    Strike,
-    Code,
-    Link,
-    Subscript,
-    Superscript,
-    TextStyleKit,
-    // Block-level alignment (emits `text-align` only when explicitly set).
-    // NOTE: `Indent` is intentionally excluded — its `renderHTML` emits an empty
-    // `style=""` on every block even when unset, which pollutes otherwise-semantic
-    // output. Consumers that persist indentation can pass a custom extension array.
-    TextAlign.configure({
-        types: [
-            'paragraph',
-            'heading'
-        ]
-    }),
-    // Content nodes
-    Image,
-    ImageRef,
-    PageBreak,
-    DynamicField,
-    // Tables (table / row / header / cell nodes)
-    StyledTableKit
-];

package/src/kit/generate-html.js

@@ -1,40 +0,0 @@
-import { defaultExtensions } from './default-extensions';
-/**
- * Serialize a Tiptap/ProseMirror document (JSON) to an HTML string.
- *
- * Environment-aware and Node-safe. Tiptap ships two serializers and the wrong
- * one throws:
- * - `@tiptap/html` needs a real `document` (browser / jsdom).
- * - `@tiptap/html/server` is backed by happy-dom and runs headlessly in Node.
- *
- * The serializer is chosen at call time from whether a DOM is present, and
- * imported lazily — so the heavy happy-dom build is never pulled into a browser
- * editor bundle that only ever edits (and never serializes server-side), and
- * Node backends never touch the browser-only build. This is why the function is
- * async.
- *
- * @param doc        The document as ProseMirror JSON (a `doc` node).
- * @param extensions Schema to serialize against. Defaults to
- *                   {@link defaultExtensions} (the editor's canonical kit). Pass
- *                   a custom array when your documents use a different schema.
- * @returns Semantic HTML. Presentation styling and sanitization (e.g. DOMPurify)
- *          are the consumer's responsibility — this helper does neither.
- */ export async function generateHTML(doc, extensions = defaultExtensions) {
-    if (typeof document !== 'undefined') {
-        // browser / jsdom: uses the ambient DOM
-        const serializer = await import('@tiptap/html');
-        return serializer.generateHTML(doc, extensions);
-    }
-    // Node: happy-dom backed, no real DOM needed. The specifier is built at runtime
-    // (not a static string literal) and flagged for webpack/vite so browser
-    // bundlers (esbuild/webpack/vite) can't statically resolve it and therefore
-    // never pull happy-dom — and its Node built-ins — into a client bundle. The
-    // `typeof document` guard means this branch never executes in a browser anyway.
-    const serverEntry = [
-        '@tiptap',
-        'html',
-        'server'
-    ].join('/');
-    const serializer = await import(/* webpackIgnore: true */ /* @vite-ignore */ serverEntry);
-    return serializer.generateHTML(doc, extensions);
-}

package/src/kit/index.js

@@ -1,2 +0,0 @@
-export * from './default-extensions';
-export * from './generate-html';

package/src/migrations/doc-migrations.js

@@ -1,24 +0,0 @@
-/**
- * The current schema version. `EditorDocument`s authored by this build of the
- * editor carry this value, and {@link migrateDoc} upgrades older documents up to
- * it.
- *
- * Bump this by exactly one whenever a schema change requires transforming stored
- * content, and add the matching entry (keyed by the previous version) to
- * {@link docMigrations}.
- */ export const LATEST_SCHEMA_VERSION = 1;
-/**
- * Ordered migration steps, keyed by the source version they upgrade from.
- *
- * v0.1.0 ships an identity (empty) set: there is nothing to migrate yet, but the
- * registry, walker ({@link migrateDoc}), and version field exist so future
- * schema bumps are non-breaking. To add one, e.g. for the 1 -> 2 bump:
- *
- * ```ts
- * export const docMigrations: DocMigrationRegistry = {
- *   1: (doc) => ({ schemaVersion: 2, content: transformV1ToV2(doc.content) }),
- * };
- * ```
- *
- * Each entry must be pure (no mutation, no browser APIs).
- */ export const docMigrations = {};

package/src/migrations/index.js

@@ -1,3 +0,0 @@
-export * from './types';
-export * from './doc-migrations';
-export * from './migrate-doc';

package/src/migrations/migrate-doc.js

@@ -1,32 +0,0 @@
-import { docMigrations, LATEST_SCHEMA_VERSION } from './doc-migrations';
-/**
- * Upgrade a stored document to {@link LATEST_SCHEMA_VERSION} by applying each
- * registered migration in order.
- *
- * Pure and idempotent: a document already at the latest version is returned
- * unchanged (a re-stamped copy), so batch runs are safe to re-run. A document
- * with a missing/invalid `schemaVersion` is treated as version 1 (the earliest).
- *
- * @param doc        The document to migrate.
- * @param migrations Registry to apply. Defaults to {@link docMigrations}; the
- *                   override exists for testing the walker in isolation.
- * @param latest     Target version. Defaults to {@link LATEST_SCHEMA_VERSION}.
- * @returns A new `EditorDocument` at `latest`.
- */ export function migrateDoc(doc, migrations = docMigrations, latest = LATEST_SCHEMA_VERSION) {
-    let current = {
-        ...doc,
-        schemaVersion: Number.isInteger(doc.schemaVersion) && doc.schemaVersion >= 1 ? doc.schemaVersion : 1
-    };
-    while(current.schemaVersion < latest){
-        const migrate = migrations[current.schemaVersion];
-        if (!migrate) {
-            throw new Error(`[migrateDoc] No migration registered for schema version ${current.schemaVersion} ` + `(target ${latest}).`);
-        }
-        const next = migrate(current);
-        if (next.schemaVersion <= current.schemaVersion) {
-            throw new Error(`[migrateDoc] Migration from version ${current.schemaVersion} did not advance the ` + `version (got ${next.schemaVersion}); migrations must be strictly increasing.`);
-        }
-        current = next;
-    }
-    return current;
-}

package/src/migrations/types.js

@@ -1,4 +0,0 @@
-/**
- * Ordered registry of migration steps, keyed by the *source* version each step
- * upgrades from. Entry `N` takes a v`N` document and returns a v`N + 1` one.
- */ export { };

package/src/models/color.model.js

@@ -1,30 +0,0 @@
-import { normalizeColor } from '../utils';
-export class Color {
-    static from(value, name, type) {
-        return new Color(value, name, type);
-    }
-    static fromArray(colors) {
-        return colors.map((color)=>{
-            if (typeof color === 'string') {
-                return new Color(color);
-            }
-            return new Color(color.value, color.name, color.type);
-        });
-    }
-    equals(color) {
-        return this.value === color.value;
-    }
-    is(color) {
-        return this.value === normalizeColor(color);
-    }
-    constructor(value, name, type){
-        const normalizedColor = normalizeColor(value);
-        if (!normalizedColor) {
-            throw new Error('Invalid or unsupported color.');
-        }
-        this.value = normalizedColor;
-        this.name = name ?? normalizedColor;
-        this.type = type;
-        Object.freeze(this);
-    }
-}

package/src/models/index.js

@@ -1 +0,0 @@
-export * from './color.model';

package/src/nodes/dynamic-field.node.js

@@ -1,141 +0,0 @@
-import { Node, mergeAttributes } from '@tiptap/core';
-/**
- * Dynamic Field Node Extension
- *
- * This extension creates atomic, non-editable inline nodes that represent
- * dynamic fields (e.g., {{customer_name}}) in document templates.
- * These fields can be programmatically replaced with actual data later.
- */ export const DynamicField = Node.create({
-    name: 'dynamicField',
-    /**
-   * Node group configuration
-   * - 'inline': Makes the node behave as inline content
-   * - 'atom': true is critical for non-editable, atomic behavior
-   * - 'selectable': true allows users to select the entire node
-   * - 'draggable': false prevents users from dragging the node
-   */ group: 'inline',
-    inline: true,
-    atom: true,
-    selectable: true,
-    draggable: false,
-    /**
-   * Define the attributes that this node can store
-   */ addAttributes () {
-        return {
-            fieldId: {
-                default: null,
-                parseHTML: (element)=>element.getAttribute('data-field-id'),
-                renderHTML: (attributes)=>{
-                    if (!attributes['fieldId']) return {};
-                    return {
-                        'data-field-id': attributes['fieldId']
-                    };
-                }
-            },
-            label: {
-                default: null,
-                parseHTML: (element)=>element.getAttribute('data-label'),
-                renderHTML: (attributes)=>{
-                    if (!attributes['label']) return {};
-                    return {
-                        'data-label': attributes['label']
-                    };
-                }
-            }
-        };
-    },
-    /**
-   * Parse HTML to recognize dynamic field spans when loading/pasting content
-   */ parseHTML () {
-        return [
-            // ----------------------------------------------------------
-            // RULE 1: Standard Tiptap Format (Ưu tiên cao nhất)
-            // ----------------------------------------------------------
-            {
-                tag: 'span[data-field-id]'
-            },
-            // ----------------------------------------------------------
-            // RULE 2: Legacy CKEditor Format (Migration Layer)
-            // ----------------------------------------------------------
-            {
-                // Selector CSS để nhận diện node của CKEditor
-                tag: 'span.red-dynamic-field',
-                // Hàm này chạy khi Tiptap tìm thấy tag trên
-                getAttrs: (node)=>{
-                    if (typeof node === 'string') return false;
-                    const element = node;
-                    // 1. Trích xuất ID từ nội dung text: "{{ref}}" -> "ref"
-                    const rawText = element.innerText || element.textContent || '';
-                    // Regex để xóa dấu {{ và }} và khoảng trắng thừa
-                    const id = rawText.replace(/{{|}}/g, '').trim();
-                    // 2. Trích xuất Label từ attribute cũ
-                    // CKEditor dùng 'value', 'dynamicfieldname' hoặc 'name'
-                    const label = element.getAttribute('value') || element.getAttribute('dynamicfieldname') || element.getAttribute('name') || id; // Fallback nếu không tìm thấy label
-                    // Trả về object khớp với cấu trúc 'addAttributes' ở trên
-                    return {
-                        fieldId: id,
-                        label: label
-                    };
-                }
-            }
-        ];
-    },
-    /**
-   * Render the node as HTML
-   * Creates a span element with Tailwind classes for styling
-   * and stores attributes in data-* attributes for robustness
-   */ renderHTML ({ HTMLAttributes, node }) {
-        const { fieldId, label } = node.attrs;
-        return [
-            'span',
-            mergeAttributes(HTMLAttributes, {
-                class: 'dynamic-field red-dynamic-field',
-                'data-field-id': fieldId,
-                'data-label': label
-            }),
-            // label || '',
-            fieldId ? `{{${fieldId}}}` : ''
-        ];
-    },
-    /**
-   * NODE VIEW: Đây là phần giúp hiển thị giao diện giống CKEditor Widget
-   * Thay vì render ra text thuần, ta render ra một DOM element được style sẵn
-   */ addNodeView () {
-        return ({ node })=>{
-            // 1. Tạo thẻ bao bọc (Wrapper)
-            const dom = document.createElement('span');
-            // 2. Thêm class để style (Dùng Tailwind như techstack của bạn )
-            // Bạn có thể thêm class 'ck-widget' nếu muốn dùng lại CSS cũ
-            dom.classList.add('dynamic-field', 'red-dynamic-field');
-            // 3. Gán dữ liệu label vào nội dung hiển thị
-            const { label, fieldId } = node.attrs;
-            dom.textContent = label || fieldId || 'Unknown Field';
-            return {
-                dom
-            };
-        };
-    },
-    /**
-   * Add custom commands for inserting dynamic fields
-   */ addCommands () {
-        return {
-            insertDynamicField: (attributes)=>({ chain })=>{
-                    if (!attributes.fieldId || !attributes.label) {
-                        console.error('[DynamicField] Both fieldId and label are required.');
-                        return false;
-                    }
-                    return chain().insertContent({
-                        type: this.name,
-                        attrs: attributes
-                    }).run();
-                }
-        };
-    },
-    /**
-   * Default options
-   */ addOptions () {
-        return {
-            HTMLAttributes: {}
-        };
-    }
-});

package/src/nodes/heading.node.js

@@ -1,13 +0,0 @@
-import { Heading } from '@tiptap/extension-heading';
-import '@tiptap/extension-paragraph';
-export const NotumHeading = Heading.extend({
-    addCommands () {
-        return {
-            ...this.parent?.(),
-            removeHeading: ()=>({ editor, chain })=>{
-                    if (!editor.isActive('heading')) return false;
-                    return chain().setParagraph().run();
-                }
-        };
-    }
-});

package/src/nodes/image-ref.node.js

@@ -1,138 +0,0 @@
-import { Node, mergeAttributes } from '@tiptap/core';
-/**
- * `image-ref` — a semantic, URL-free reference to a media asset.
- *
- * Renders a `<figure data-block="image-ref" data-image-id="…">` (with an optional
- * `<figcaption>`), decoupling document content from the resolved image URL. The
- * consumer hydrates the figure by attribute (`data-image-id`) at render time —
- * the document itself never embeds a URL or any presentation. In the editor the
- * node shows a placeholder (it has no URL to display); resolving and showing the
- * real image is the consumer's / media-picker's job.
- */ export const ImageRef = Node.create({
-    name: 'imageRef',
-    group: 'block',
-    atom: true,
-    selectable: true,
-    draggable: true,
-    addOptions () {
-        return {
-            HTMLAttributes: {}
-        };
-    },
-    addAttributes () {
-        return {
-            imageId: {
-                default: null,
-                parseHTML: (element)=>element.getAttribute('data-image-id'),
-                renderHTML: (attributes)=>{
-                    if (!attributes['imageId']) return {};
-                    return {
-                        'data-image-id': attributes['imageId']
-                    };
-                }
-            },
-            caption: {
-                default: null,
-                // Caption is rendered as <figcaption> text content (below), not a data
-                // attribute — so parse it back from the figcaption child for round-trip.
-                parseHTML: (element)=>{
-                    const figcaption = element.querySelector(':scope > figcaption');
-                    return figcaption?.textContent?.trim() || null;
-                },
-                renderHTML: ()=>({})
-            },
-            captionPosition: {
-                default: null,
-                // Normalize to the typed union: absent attribute stays `null` (preserves
-                // the byte-identical round-trip), any present-but-unknown value coerces to
-                // `'bottom'` so a non-`'top' | 'bottom'` string can never leak through.
-                parseHTML: (element)=>{
-                    const raw = element.getAttribute('data-caption-position');
-                    if (raw === null) return null;
-                    return raw === 'top' ? 'top' : 'bottom';
-                },
-                renderHTML: (attributes)=>{
-                    if (!attributes['captionPosition']) return {};
-                    return {
-                        'data-caption-position': attributes['captionPosition']
-                    };
-                }
-            }
-        };
-    },
-    parseHTML () {
-        return [
-            {
-                tag: 'figure[data-block="image-ref"]'
-            }
-        ];
-    },
-    renderHTML ({ HTMLAttributes, node }) {
-        const { caption } = node.attrs;
-        const figure = mergeAttributes(this.options.HTMLAttributes, HTMLAttributes, {
-            'data-block': 'image-ref'
-        });
-        // No <img> is emitted — the asset is URL-free. The caption order relative to
-        // the (not-yet-resolved) image is carried by `data-caption-position` for the
-        // consumer to honor at hydration time; the figure itself just holds the text.
-        if (!caption) {
-            return [
-                'figure',
-                figure
-            ];
-        }
-        const figcaption = [
-            'figcaption',
-            {},
-            caption
-        ];
-        return [
-            'figure',
-            figure,
-            figcaption
-        ];
-    },
-    /**
-   * Editor-only placeholder. The DOM here is chrome (never serialized — that is
-   * `renderHTML`'s job); it just shows which media the block references.
-   */ addNodeView () {
-        return ({ node })=>{
-            const { imageId, caption, captionPosition } = node.attrs;
-            const dom = document.createElement('figure');
-            dom.classList.add('image-ref-placeholder');
-            dom.setAttribute('data-block', 'image-ref');
-            if (imageId) dom.setAttribute('data-image-id', imageId);
-            if (captionPosition) dom.setAttribute('data-caption-position', captionPosition);
-            dom.style.cssText = 'margin:1rem 0;display:flex;flex-direction:column;gap:.5rem;';
-            const box = document.createElement('div');
-            box.style.cssText = 'display:flex;align-items:center;gap:.5rem;padding:1rem;border:1px dashed currentColor;' + 'border-radius:.5rem;opacity:.65;font-size:.875rem;justify-content:center;';
-            box.textContent = `🖼  image-ref · id: ${imageId || '—'}`;
-            const figcaption = document.createElement('figcaption');
-            figcaption.style.cssText = 'font-size:.8125rem;opacity:.7;text-align:center;';
-            if (caption) figcaption.textContent = caption;
-            if (caption && captionPosition === 'top') {
-                dom.append(figcaption, box);
-            } else {
-                dom.append(box);
-                if (caption) dom.append(figcaption);
-            }
-            return {
-                dom
-            };
-        };
-    },
-    addCommands () {
-        return {
-            insertImageRef: (attributes)=>({ chain })=>{
-                    if (!attributes.imageId) {
-                        console.error('[ImageRef] imageId is required.');
-                        return false;
-                    }
-                    return chain().insertContent({
-                        type: this.name,
-                        attrs: attributes
-                    }).run();
-                }
-        };
-    }
-});

package/src/nodes/index.js

@@ -1,4 +0,0 @@
-export * from './heading.node';
-export * from './dynamic-field.node';
-export * from './page-break.node';
-export * from './image-ref.node';

package/src/nodes/page-break.node.js

@@ -1,52 +0,0 @@
-import { Node, mergeAttributes } from '@tiptap/core';
-export const PageBreak = Node.create({
-    name: 'pageBreak',
-    group: 'block',
-    atom: true,
-    selectable: true,
-    // addNodeView() {
-    //   return createPageBreakNodeView;
-    // },
-    parseHTML () {
-        return [
-            // ----------------------------------------------------------
-            // RULE 1: Standard Tiptap Format (Ưu tiên cao nhất)
-            // ----------------------------------------------------------
-            {
-                tag: 'div[data-page-break]'
-            },
-            // ----------------------------------------------------------
-            // RULE 2: CKEditor Format (Ưu tiên thấp nhất)
-            // ----------------------------------------------------------
-            {
-                tag: 'div.page-break'
-            }
-        ];
-    },
-    renderHTML ({ HTMLAttributes }) {
-        return [
-            'div',
-            mergeAttributes(HTMLAttributes, {
-                'data-page-break': 'true',
-                class: 'document-engine-page-break',
-                style: 'break-before: page; page-break-before: always;'
-            }),
-            [
-                'span',
-                {
-                    class: 'document-engine-page-break-label'
-                },
-                'Page break'
-            ]
-        ];
-    },
-    addCommands () {
-        return {
-            insertPageBreak: ()=>({ chain })=>{
-                    return chain().insertContent({
-                        type: this.name
-                    }).run();
-                }
-        };
-    }
-});

package/src/types/index.js

@@ -1,2 +0,0 @@
-export * from './ordered-list.type';
-export * from './text-case.type';

package/src/types/ordered-list.type.js

@@ -1,2 +0,0 @@
-// TODO CKEditor: Add lower-roman, decimal-leading-zero, upper-roman, lower-latin, upper-latin
-export { };

package/src/types/text-case.type.js

@@ -1 +0,0 @@
-export { };

package/src/types/tiptap-html-server.d.js

@@ -1,10 +0,0 @@
-/**
- * Type shim for the `@tiptap/html/server` subpath.
- *
- * `@tiptap/html` only exposes its Node-safe (`/server`) entry through the
- * package `exports` map. This library compiles under `moduleResolution: node10`,
- * which ignores `exports` for type resolution, so TypeScript cannot find the
- * subpath's declarations on its own. The runtime (Jest/Node) resolves `/server`
- * via the exports map fine — this declaration only satisfies the type checker by
- * pointing it at the same public types as the bare package.
- */ 

package/src/utils/color.util.js

@@ -1,31 +0,0 @@
-/**
- * Normalizes a color value to lowercase hex format
- * Supports hex (#RGB, #RRGGBB) and rgb(r, g, b) formats
- *
- * @param color - Color value to normalize
- * @returns Normalized hex color or null if invalid
- *
- * @example
- * normalizeColor('#FF0000') // '#ff0000'
- * normalizeColor('rgb(255, 0, 0)') // '#ff0000'
- * normalizeColor('#F00') // '#f00'
- * normalizeColor('invalid') // null
- */ export function normalizeColor(color) {
-    if (!color) return null;
-    const trimmed = color.trim().toLowerCase();
-    if (trimmed === 'transparent') return trimmed;
-    // Check if it's a valid hex color
-    if (/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(trimmed)) {
-        return trimmed;
-    }
-    // Try to parse RGB
-    const rgbMatch = trimmed.match(/^rgb\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)$/i);
-    if (rgbMatch) {
-        const r = Math.max(0, Math.min(255, parseInt(rgbMatch[1], 10)));
-        const g = Math.max(0, Math.min(255, parseInt(rgbMatch[2], 10)));
-        const b = Math.max(0, Math.min(255, parseInt(rgbMatch[3], 10)));
-        const toHex = (n)=>n.toString(16).padStart(2, '0');
-        return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
-    }
-    return null;
-}