@phuong-tran-redoc/document-engine-core 0.1.5 → 0.1.7

package/README.md

@@ -96,6 +96,29 @@ import { generateHTML, defaultExtensions } from '@phuong-tran-redoc/document-eng
 const html = await generateHTML(myProseMirrorJSON);
 ```
 
+### CKEditor 5 HTML compatibility
+
+Load HTML stored by the legacy CKEditor 5 build and save it back byte-identical: unchanged parts keep
+their exact markup, only what the user edited changes.
+
+```typescript
+import { CkCompat, fromCkHtml, toCkHtml, verifyCkRoundTrip, defaultExtensions } from '@phuong-tran-redoc/document-engine-core';
+
+const editor = new Editor({ extensions: [...defaultExtensions, CkCompat] });
+const { html, wrapperClass, unsupported } = fromCkHtml(storedHtml); // `unsupported`: CKEditor plugin content with no editor node
+editor.commands.setContent(html, { emitUpdate: false });
+
+const saved = toCkHtml(editor.getHTML(), { wrapperClass: wrapperClass ?? false });
+verifyCkRoundTrip(storedHtml, saved); // before editing: is the document reproduced exactly?
+```
+
+On a backend (no DOM) pass a parser. `createCkDomParser()` uses happy-dom, which `@tiptap/html` already installs:
+
+```typescript
+const domParser = await createCkDomParser();
+const ckHtml = toCkHtml(await generateHTML(json, extensions), { wrapperClass, domParser });
+```
+
 ### Versioned documents + migrations
 
 ```typescript
@@ -138,6 +161,12 @@ Everything below is re-exported from the package entry (`@phuong-tran-redoc/docu
 - `defaultExtensions: Extensions` — the canonical schema (nodes, marks, structures).
 - `generateHTML(doc, extensions?): Promise<string>` — async, environment-aware headless serializer.
 
+### CKEditor compatibility (`compat`)
+
+- `CkCompat` — extension that carries the original CKEditor attributes through editing.
+- `fromCkHtml(html, { domParser? })` → `{ html, wrapperClass, unsupported }`; `toCkHtml(html, { wrapperClass?, domParser? })`.
+- `verifyCkRoundTrip(original, saved)`, `CK_UNSUPPORTED_CONTENT`, `createCkDomParser()`.
+
 ### Migrations (`migrations`)
 
 - `EditorDocument` — `{ schemaVersion: number; content: JSONContent }`.
@@ -201,13 +230,9 @@ nx lint @phuong-tran-redoc/document-engine-core    # lint
 
 ---
 
-## 👤 Author
-
-Developed by **Duc Phuong (Jack)**
+## 👤 Authors
 
-- 💼 [LinkedIn](https://www.linkedin.com/in/tdp1999/)
-- 🐙 [GitHub](https://github.com/tdp1999)
-- 📧 [Email](mailto:tdp99.business@gmail.com)
+See [AUTHORS.md](https://github.com/phuong-tran-redoc/document-engine/blob/main/AUTHORS.md).
 
 ---
 

package/index.esm.js

@@ -1,4 +1,5 @@
 import { Extension, Node, mergeAttributes } from '@tiptap/core';
+import { __awaiter } from 'tslib';
 import { OrderedList, BulletList, ListItem } from '@tiptap/extension-list';
 import { PluginKey, Plugin, TextSelection, NodeSelection } from '@tiptap/pm/state';
 import { TableCell, TableHeader, Table, TableRow } from '@tiptap/extension-table';
@@ -6,26 +7,637 @@ import { selectionCell, findTable, TableMap, CellSelection, tableNodeTypes, dele
 import { isEqual } from 'lodash-es';
 import { DOMSerializer } from '@tiptap/pm/model';
 import { Decoration, DecorationSet } from '@tiptap/pm/view';
-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 { 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 { Italic } from '@tiptap/extension-italic';
+import { Link } from '@tiptap/extension-link';
 import { Paragraph } from '@tiptap/extension-paragraph';
-import Strike from '@tiptap/extension-strike';
+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 { Underline } from '@tiptap/extension-underline';
 import { Heading } from '@tiptap/extension-heading';
-import { __awaiter } from 'tslib';
+
+/** Pixels per unit for the absolute CSS length units (CSS Values 4: 1in = 96px). */
+const PX_PER_UNIT = {
+    px: 1,
+    pt: 96 / 72,
+    pc: 16,
+    in: 96,
+    cm: 96 / 2.54,
+    mm: 96 / 25.4,
+    q: 96 / 101.6,
+};
+/**
+ * Convert a single absolute CSS length (`36pt`, `1cm`, `40px`) to pixels.
+ * Returns `null` for anything else: relative units (`em`, `%`), keywords, or several values.
+ */
+function absoluteLengthToPx(value) {
+    const match = /^(-?\d*\.?\d+)([a-z]*)$/i.exec((value !== null && value !== void 0 ? value : '').trim());
+    if (!match)
+        return null;
+    const unit = match[2].toLowerCase();
+    const factor = unit === '' ? (Number(match[1]) === 0 ? 1 : undefined) : PX_PER_UNIT[unit];
+    return factor === undefined ? null : Number(match[1]) * factor;
+}
+
+/**
+ * CKEditor 5 HTML compatibility layer.
+ *
+ * Lets the editor load HTML that was produced by the legacy CKEditor 5 build and save it back
+ * in the same shape, so stored documents and the code that reads them keep working.
+ *
+ * - {@link fromCkHtml} runs before content is set into the editor. It strips the CKEditor
+ *   data-processor wrapper and records each element's original attributes, in order, in a
+ *   `data-ck` attribute that the {@link CkCompat} extension carries through editing.
+ * - {@link toCkHtml} runs on `editor.getHTML()`. It rebuilds the CKEditor markup from those
+ *   records: attribute order, `prop:value;` style formatting, `<figure class="table">`,
+ *   `<colgroup>`, bare text in single-paragraph cells, `<i>`, page breaks, dynamic fields and
+ *   the wrapper. Anything the user changed is taken from the editor; anything the editor does
+ *   not model is kept verbatim.
+ *
+ * Both functions need a `DOMParser`. In the browser the global one is used. In Node (no global DOM)
+ * pass one in, e.g. from {@link createCkDomParser}:
+ *
+ * ```ts
+ * const domParser = await createCkDomParser();
+ * const ckHtml = toCkHtml(await generateHTML(json, extensions), { wrapperClass, domParser });
+ * ```
+ */
+/** Attribute that carries the original CKEditor attributes of an element through the editor. */
+const CK_ORIGIN_ATTRIBUTE = 'data-ck';
+/** Class list of the CKEditor data-processor wrapper (`CustomHtmlDataProcessor`). */
+const CK_WRAPPER_BASE_CLASS = 'ck ck-content ck-print';
+/**
+ * Content produced by CKEditor plugins of the legacy build that this editor cannot represent yet,
+ * keyed by name, with the selector that identifies it in stored HTML.
+ */
+const CK_UNSUPPORTED_CONTENT = {
+    signatureField: '.redr-signature-field',
+    inlineField: '.redr-inline-field',
+    dynamicImage: '.redr-dynamic-image',
+    dealTable: '.redr-deal-table',
+    editorColumn: '.redr-editor-column',
+    restrictedEditingException: '.restricted-editing-exception',
+    image: 'img, figure.image',
+};
+/** Elements whose original attributes are recorded on load. */
+const TRACKED_SELECTOR = 'p,h1,h2,h3,h4,h5,h6,span,table,tr,td,th,blockquote,li,ol,ul,a,div.page-break';
+/** Style properties the editor itself writes, per element. A recorded value for one of these
+ * that the editor no longer emits was removed by the user and is dropped. */
+const OWNED_STYLES = {
+    p: ['text-align', 'margin-left'],
+    h: ['text-align', 'margin-left'],
+    span: ['font-size', 'font-family', 'color', 'background-color', 'line-height'],
+    td: ['text-align', 'vertical-align', 'background-color', 'border-color', 'border-style', 'border-width'],
+    table: ['background-color', 'border-color', 'border-style', 'border-width'],
+    col: ['width'],
+};
+/** Attributes the editor itself writes. A recorded one the editor no longer emits is dropped. */
+const OWNED_ATTRIBUTES = new Set(['style', 'colspan', 'rowspan', 'href', 'target', 'rel', 'start', 'type']);
+/** Attributes the editor emits that never belong in CKEditor output. */
+const ENGINE_ONLY_ATTRIBUTES = ['data-colwidths', 'colwidth', 'data-indent'];
+/**
+ * Default cell styles the table extension writes on every cell. On an element that came from
+ * CKEditor they are dropped unless the source had them; a border group is only dropped when all
+ * three parts are still the default, so a border the user set is kept.
+ */
+const DEFAULT_CELL_BORDER = [
+    ['border-style', 'solid'],
+    ['border-color', '#e5e7eb'],
+    ['border-width', '1px'],
+];
+const DEFAULT_TABLE_BORDER = DEFAULT_CELL_BORDER;
+const DEFAULT_CELL_VERTICAL_ALIGN = 'middle';
+/** Declarations the editor emits as a neutral default; dropped unless they were in the source. */
+const NEUTRAL_DECLARATIONS = new Set(['margin-left:0px', 'margin-left:0', 'margin-left:nullpx']);
+const DYNAMIC_FIELD_BASE_CLASSES = ['red-dynamic-field', 'inline-field', 'redr-handlebar-field'];
+const DYNAMIC_FIELD_HAS_VALUE_CLASS = 'red-dynamic-field--has-value';
+const PAGE_BREAK_HTML = '<div class="page-break" style="page-break-after:always;"><span style="display:none;">&nbsp;</span></div>';
+function parse(html, domParser) {
+    if (!domParser && typeof DOMParser === 'undefined') {
+        throw new Error('CKEditor compatibility needs a DOM: pass `domParser` (see createCkDomParser) when there is no global DOMParser.');
+    }
+    const doc = (domParser !== null && domParser !== void 0 ? domParser : new DOMParser()).parseFromString(`<body>${html}</body>`, 'text/html');
+    return doc.body;
+}
+/**
+ * A `DOMParser` for {@link fromCkHtml} / {@link toCkHtml} that works in any environment: the global one
+ * in the browser, otherwise one from happy-dom (already installed with `@tiptap/html`, which
+ * {@link generateHTML} uses for the same reason). Create it once and reuse it.
+ */
+function createCkDomParser() {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (typeof DOMParser !== 'undefined')
+            return new DOMParser();
+        // Built at runtime so browser bundlers never resolve happy-dom (see generateHTML).
+        const specifier = ['happy', 'dom'].join('-');
+        let happyDom;
+        try {
+            happyDom = yield import(/* webpackIgnore: true */ /* @vite-ignore */ specifier);
+        }
+        catch (_a) {
+            throw new Error('No DOM available: install happy-dom, or pass your own `domParser` (e.g. from jsdom).');
+        }
+        return new new happyDom.Window().DOMParser();
+    });
+}
+function attrsOf(el) {
+    return Array.from(el.attributes)
+        .filter((a) => a.name !== CK_ORIGIN_ATTRIBUTE)
+        .map((a) => [a.name, a.value]);
+}
+/** Attribute names a record may restore: no event handlers, nothing a browser would not parse. */
+const SAFE_ATTRIBUTE_NAME = /^(?!on)[a-z_:][a-z0-9_:.-]*$/i;
+const UNSAFE_URL = /^\s*(javascript|vbscript|data:text\/html)/i;
+/**
+ * A record is restored verbatim on save, and it can arrive from pasted HTML, not only from
+ * `fromCkHtml`. Accept only a well-formed one, without script-bearing attributes.
+ */
+/** Browsers ignore control characters inside a URL scheme (`java\tscript:`). */
+function withoutControlChars(value) {
+    return Array.from(value)
+        .filter((c) => c.charCodeAt(0) > 0x1f)
+        .join('');
+}
+function cleanAttrList(value) {
+    if (!Array.isArray(value))
+        return null;
+    const list = [];
+    for (const pair of value) {
+        if (!Array.isArray(pair) || pair.length !== 2 || typeof pair[0] !== 'string' || typeof pair[1] !== 'string')
+            return null;
+        const [name, val] = pair;
+        if (SAFE_ATTRIBUTE_NAME.test(name) && !UNSAFE_URL.test(withoutControlChars(val)))
+            list.push([name, val]);
+    }
+    return list;
+}
+function readOrigin(el) {
+    const raw = el.getAttribute(CK_ORIGIN_ATTRIBUTE);
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (_a) {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const record = parsed;
+    const a = cleanAttrList(record['a']);
+    if (!a)
+        return null;
+    const origin = { a };
+    if (record['f'] !== undefined) {
+        const f = cleanAttrList(record['f']);
+        if (!f)
+            return null;
+        origin.f = f;
+    }
+    if (record['c'] !== undefined) {
+        if (!Array.isArray(record['c']))
+            return null;
+        const c = record['c'].map(cleanAttrList);
+        if (c.some((x) => !x))
+            return null;
+        origin.c = c;
+    }
+    return origin;
+}
+function writeOrigin(el, origin) {
+    el.setAttribute(CK_ORIGIN_ATTRIBUTE, JSON.stringify(origin));
+}
+// ---------------------------------------------------------------------------
+// Load
+// ---------------------------------------------------------------------------
+/**
+ * Prepare CKEditor HTML for the editor. Safe to call on HTML that did not come from
+ * CKEditor: it then only records attributes.
+ */
+function fromCkHtml(html, options = {}) {
+    const body = parse(html !== null && html !== void 0 ? html : '', options.domParser);
+    let wrapperClass = null;
+    const only = body.children.length === 1 ? body.firstElementChild : null;
+    if (only && only.tagName === 'DIV' && only.classList.contains('ck-content') && only.classList.contains('ck')) {
+        wrapperClass = only.getAttribute('class');
+        only.replaceWith(...Array.from(only.childNodes));
+    }
+    body.querySelectorAll(TRACKED_SELECTOR).forEach((el) => {
+        // Dynamic-field spans keep their attributes in their own record (see DynamicField export).
+        writeOrigin(el, { a: attrsOf(el) });
+    });
+    body.querySelectorAll('figure.table').forEach((figure) => {
+        var _a;
+        const table = figure.querySelector(':scope > table');
+        if (!table)
+            return;
+        const origin = (_a = readOrigin(table)) !== null && _a !== void 0 ? _a : { a: attrsOf(table) };
+        origin.f = attrsOf(figure);
+        writeOrigin(table, origin);
+        figure.replaceWith(...Array.from(figure.childNodes));
+    });
+    body.querySelectorAll('table').forEach((table) => {
+        var _a;
+        const cols = table.querySelectorAll(':scope > colgroup > col');
+        if (!cols.length)
+            return;
+        const origin = (_a = readOrigin(table)) !== null && _a !== void 0 ? _a : { a: attrsOf(table) };
+        origin.c = Array.from(cols).map(attrsOf);
+        writeOrigin(table, origin);
+    });
+    const unsupported = Object.keys(CK_UNSUPPORTED_CONTENT).filter((key) => body.querySelector(CK_UNSUPPORTED_CONTENT[key]));
+    return { html: body.innerHTML, wrapperClass, unsupported };
+}
+/**
+ * Compare the stored HTML with what saving the freshly loaded document would write
+ * (`toCkHtml(editor.getHTML())` before any edit). A difference means the editor could not
+ * represent part of the document and saving would change it — open it read-only instead.
+ */
+function verifyCkRoundTrip(original, saved) {
+    if (original === saved)
+        return { identical: true, difference: null };
+    let index = 0;
+    while (index < original.length && index < saved.length && original[index] === saved[index])
+        index++;
+    const excerpt = (text) => text.slice(Math.max(0, index - 40), index + 80);
+    return { identical: false, difference: { index, expected: excerpt(original), actual: excerpt(saved) } };
+}
+// ---------------------------------------------------------------------------
+// Save
+// ---------------------------------------------------------------------------
+function parseStyle(style) {
+    if (!style)
+        return [];
+    return style
+        .split(';')
+        .map((d) => d.trim())
+        .filter(Boolean)
+        .map((d) => {
+        const i = d.indexOf(':');
+        return [d.slice(0, i).trim().toLowerCase(), d.slice(i + 1).trim()];
+    })
+        .filter(([k]) => !!k);
+}
+function formatStyle(decls) {
+    return decls.map(([k, v]) => `${k}:${v};`).join('');
+}
+/** Compare two CSS values the way the browser would compute them. */
+function sameCssValue(prop, a, b, probe) {
+    if (a === b)
+        return true;
+    if (a.replace(/\s+/g, '') === b.replace(/\s+/g, ''))
+        return true;
+    probe.style.setProperty(prop, a);
+    const ca = probe.style.getPropertyValue(prop);
+    probe.style.setProperty(prop, b);
+    const cb = probe.style.getPropertyValue(prop);
+    probe.removeAttribute('style');
+    if (!!ca && ca === cb)
+        return true;
+    // The editor writes lengths in px; `1cm` in the source and `37.8px` from the editor are the same value.
+    const pa = absoluteLengthToPx(a);
+    const pb = absoluteLengthToPx(b);
+    return pa !== null && pb !== null && Math.abs(pa - pb) < 0.01;
+}
+function styleGroup(tag) {
+    if (/^h[1-6]$/.test(tag))
+        return 'h';
+    if (tag === 'th')
+        return 'td';
+    return tag;
+}
+function dropEditorDefaults(group, orig, cur, probe) {
+    const had = (k) => orig.some(([ok]) => ok === k || (k.startsWith('border-') && ok === 'border'));
+    const border = group === 'td' ? DEFAULT_CELL_BORDER : group === 'table' ? DEFAULT_TABLE_BORDER : null;
+    if (border &&
+        border.every(([k]) => !had(k)) &&
+        border.every(([k, v]) => cur.has(k) && sameCssValue(k, v, cur.get(k), probe))) {
+        border.forEach(([k]) => cur.delete(k));
+    }
+    if (group === 'td' && !had('vertical-align') && cur.get('vertical-align') === DEFAULT_CELL_VERTICAL_ALIGN) {
+        cur.delete('vertical-align');
+    }
+}
+/** Keep a source `border` shorthand when the editor's longhands still say the same thing. */
+function shorthandStillHolds(value, cur, probe) {
+    probe.style.setProperty('border', value);
+    const parts = ['border-style', 'border-color', 'border-width'].map((k) => [k, probe.style.getPropertyValue(k)]);
+    probe.removeAttribute('style');
+    return parts.every(([k, v]) => !v || (cur.has(k) && sameCssValue(k, v, cur.get(k), probe)));
+}
+function reconcileStyle(tag, original, current, probe, fromSource = original !== null) {
+    var _a;
+    const group = styleGroup(tag);
+    const owned = (_a = OWNED_STYLES[group]) !== null && _a !== void 0 ? _a : [];
+    const orig = parseStyle(original);
+    // A value the editor could not parse (e.g. `margin-left: NaNpx`) means "unset".
+    const cur = new Map(parseStyle(current).filter(([, v]) => !/NaN|null|undefined/.test(v)));
+    const out = [];
+    if (fromSource)
+        dropEditorDefaults(group, orig, cur, probe);
+    for (const [k, v] of orig) {
+        if (k === 'border' && shorthandStillHolds(v, cur, probe)) {
+            out.push([k, v]);
+            ['border-style', 'border-color', 'border-width'].forEach((l) => cur.delete(l));
+        }
+        else if (cur.has(k)) {
+            const nv = cur.get(k);
+            out.push([k, sameCssValue(k, v, nv, probe) ? v : nv]);
+            cur.delete(k);
+        }
+        else if ((!owned.includes(k) || isZeroLength(v) || notReadable(k, v)) && !isCoveredBy(k, cur)) {
+            // Unmodelled properties are kept verbatim. So is an owned one the editor reads as "no value":
+            // zero in any unit (`margin-left:0in`) or a length it cannot express in px (`margin-left:2em`).
+            out.push([k, v]);
+        }
+    }
+    for (const [k, v] of cur) {
+        if (NEUTRAL_DECLARATIONS.has(`${k}:${v.replace(/\s+/g, '')}`))
+            continue;
+        if (impliedByShorthand(k, v, orig, probe))
+            continue;
+        out.push([k, v]);
+    }
+    return formatStyle(out);
+}
+/** Owned length properties the editor only models in absolute units. */
+const PX_ONLY_STYLES = new Set(['margin-left']);
+function notReadable(prop, value) {
+    return PX_ONLY_STYLES.has(prop) && absoluteLengthToPx(value) === null;
+}
+/**
+ * The editor reads a longhand out of a source shorthand (`margin:0 0 0 36pt` gives an indent of
+ * 48px) and writes it back. While the value is unchanged, the shorthand already says it.
+ */
+function impliedByShorthand(prop, value, orig, probe) {
+    var _a;
+    const shorthand = (_a = /^(margin|padding)-/.exec(prop)) === null || _a === void 0 ? void 0 : _a[1];
+    const source = shorthand && orig.find(([k]) => k === shorthand);
+    if (!source)
+        return false;
+    probe.style.setProperty(shorthand, source[1]);
+    const implied = probe.style.getPropertyValue(prop);
+    probe.removeAttribute('style');
+    return !!implied && sameCssValue(prop, implied, value, probe);
+}
+function isZeroLength(value) {
+    return /^0(\.0+)?([a-z]+|%)?$/i.test(value.trim());
+}
+/** A shorthand such as `border` is superseded when the editor wrote its longhands. */
+function isCoveredBy(prop, current) {
+    if (prop === 'border')
+        return ['border-style', 'border-color', 'border-width'].some((k) => current.has(k));
+    return false;
+}
+function setAttributesInOrder(el, attrs) {
+    Array.from(el.attributes).forEach((a) => el.removeAttribute(a.name));
+    attrs.forEach(([k, v]) => el.setAttribute(k, v));
+}
+/** Rebuild one element's attributes from its recorded origin and what the editor emitted. */
+function reconcileElement(el, origin, probe) {
+    var _a, _b;
+    const tag = el.tagName.toLowerCase();
+    const record = el.getAttribute(CK_ORIGIN_ATTRIBUTE);
+    const current = new Map(attrsOf(el).filter(([k]) => !ENGINE_ONLY_ATTRIBUTES.includes(k)));
+    const result = [];
+    for (const [k, v] of origin !== null && origin !== void 0 ? origin : []) {
+        if (k === 'style') {
+            const style = reconcileStyle(tag, v, (_a = current.get('style')) !== null && _a !== void 0 ? _a : null, probe);
+            if (style)
+                result.push(['style', style]);
+            current.delete('style');
+        }
+        else if (k === 'class') {
+            const classes = ((_b = current.get('class')) !== null && _b !== void 0 ? _b : '').split(/\s+/).filter(Boolean);
+            const merged = [...v.split(/\s+/).filter(Boolean)];
+            classes.forEach((c) => !merged.includes(c) && merged.push(c));
+            result.push(['class', merged.join(' ')]);
+            current.delete('class');
+        }
+        else if (current.has(k)) {
+            result.push([k, current.get(k)]);
+            current.delete(k);
+        }
+        else if (!OWNED_ATTRIBUTES.has(k)) {
+            result.push([k, v]);
+        }
+    }
+    for (const [k, v] of current) {
+        if (k === 'style') {
+            const style = reconcileStyle(tag, null, v, probe, origin !== null);
+            if (style)
+                result.push(['style', style]);
+        }
+        else if ((k === 'colspan' || k === 'rowspan') && v === '1') {
+            continue;
+        }
+        else {
+            result.push([k, v]);
+        }
+    }
+    setAttributesInOrder(el, result);
+    // Keep the record for later passes (tables read it); it is stripped at the very end.
+    if (record)
+        el.setAttribute(CK_ORIGIN_ATTRIBUTE, record);
+}
+function exportDynamicFields(body) {
+    body.querySelectorAll('span[data-field-id]').forEach((el) => {
+        var _a, _b, _c, _d;
+        const key = (_a = el.getAttribute('data-field-id')) !== null && _a !== void 0 ? _a : '';
+        const label = el.getAttribute('data-label') || key;
+        const origin = (_c = (_b = readOrigin(el)) === null || _b === void 0 ? void 0 : _b.a) !== null && _c !== void 0 ? _c : null;
+        const doc = el.ownerDocument;
+        const span = doc.createElement('span');
+        const originKey = origin ? ((_d = el.textContent) !== null && _d !== void 0 ? _d : '').replace(/{{|}}/g, '').trim() : null;
+        if (origin && originKey === key) {
+            setAttributesInOrder(span, origin);
+        }
+        else {
+            // A field inserted (or re-keyed) in this editor: emit the shape the CKEditor plugin writes.
+            setAttributesInOrder(span, [
+                ['class', [...DYNAMIC_FIELD_BASE_CLASSES, DYNAMIC_FIELD_HAS_VALUE_CLASS].join(' ')],
+                ['id', `red-dynamic-field__${key}`],
+                ['name', label],
+                ['background', 'false'],
+                ['dynamicfieldname', label],
+                ['value', label],
+                ['type', 'textbox:text'],
+            ]);
+        }
+        span.textContent = `{{${key}}}`;
+        el.replaceWith(span);
+    });
+}
+/**
+ * Tiptap's `TrailingNode` appends an empty paragraph whenever a document ends in a table or other
+ * non-paragraph block. CKEditor allows that ending, so drop the paragraph unless the source had it.
+ */
+function dropTrailingNode(body) {
+    const last = body.lastElementChild;
+    if (!last || last.tagName !== 'P' || last.attributes.length || last.childNodes.length)
+        return;
+    const previous = last.previousElementSibling;
+    if (previous && previous.tagName !== 'P')
+        last.remove();
+}
+function exportPageBreaks(body) {
+    body.querySelectorAll('div[data-page-break]').forEach((el) => {
+        var _a;
+        const origin = (_a = readOrigin(el)) === null || _a === void 0 ? void 0 : _a.a;
+        const holder = el.ownerDocument.createElement('div');
+        holder.innerHTML = PAGE_BREAK_HTML;
+        const div = holder.firstElementChild;
+        if (origin)
+            setAttributesInOrder(div, origin);
+        el.replaceWith(div);
+    });
+}
+function exportTables(body, probe) {
+    body.querySelectorAll('table').forEach((table) => {
+        var _a, _b;
+        const origin = readOrigin(table);
+        const doc = table.ownerDocument;
+        // <colgroup>: keep the recorded <col> attributes when the column count is unchanged.
+        const cols = Array.from(table.querySelectorAll(':scope > colgroup > col'));
+        cols.forEach((col, i) => {
+            const recorded = (origin === null || origin === void 0 ? void 0 : origin.c) && origin.c.length === cols.length ? origin.c[i] : null;
+            reconcileElement(col, recorded, probe);
+        });
+        table.querySelectorAll(':scope > tbody > tr > td, :scope > tbody > tr > th').forEach(unwrapLoneParagraph);
+        // <figure class="table">: restore the recorded wrapper, or add CKEditor's default.
+        if (((_a = table.parentElement) === null || _a === void 0 ? void 0 : _a.tagName) !== 'FIGURE') {
+            const figure = doc.createElement('figure');
+            setAttributesInOrder(figure, (_b = origin === null || origin === void 0 ? void 0 : origin.f) !== null && _b !== void 0 ? _b : [['class', 'table']]);
+            table.replaceWith(figure);
+            figure.appendChild(table);
+        }
+    });
+}
+/** CKEditor writes a lone, attribute-less paragraph in a table cell or list item as bare content. */
+function unwrapLoneParagraph(container) {
+    const only = container.childNodes.length === 1 ? container.firstElementChild : null;
+    if (only && only === container.firstChild && only.tagName === 'P' && !hasMeaningfulAttributes(only)) {
+        only.replaceWith(...Array.from(only.childNodes));
+    }
+}
+/** True when an element carries attributes CKEditor would keep (ignores the origin record). */
+function hasMeaningfulAttributes(el) {
+    var _a, _b;
+    const origin = (_b = (_a = readOrigin(el)) === null || _a === void 0 ? void 0 : _a.a) !== null && _b !== void 0 ? _b : [];
+    if (origin.length)
+        return true;
+    return attrsOf(el).some(([k, v]) => {
+        if (ENGINE_ONLY_ATTRIBUTES.includes(k))
+            return false;
+        if (k === 'style')
+            return parseStyle(v).some(([p, val]) => !NEUTRAL_DECLARATIONS.has(`${p}:${val.replace(/\s+/g, '')}`));
+        return true;
+    });
+}
+/**
+ * Turn `editor.getHTML()` output back into CKEditor-shaped HTML.
+ */
+function toCkHtml(html, options = {}) {
+    var _a;
+    const body = parse(html !== null && html !== void 0 ? html : '', options.domParser);
+    const probe = body.ownerDocument.createElement('span');
+    exportDynamicFields(body);
+    exportPageBreaks(body);
+    // Reconcile plain elements before tables restructure cells (so `<p>` attributes are final).
+    body.querySelectorAll('*').forEach((el) => {
+        var _a, _b;
+        const tag = el.tagName.toLowerCase();
+        if (tag === 'col' || el.closest('div.page-break') || el.matches('span[id^="red-dynamic-field"]'))
+            return;
+        reconcileElement(el, (_b = (_a = readOrigin(el)) === null || _a === void 0 ? void 0 : _a.a) !== null && _b !== void 0 ? _b : null, probe);
+    });
+    dropTrailingNode(body);
+    // CKEditor writes an empty block as `&nbsp;`.
+    body.querySelectorAll('p,h1,h2,h3,h4,h5,h6').forEach((el) => {
+        if (!el.childNodes.length)
+            el.textContent = '\u00a0';
+    });
+    exportTables(body, probe);
+    body.querySelectorAll('li').forEach(unwrapLoneParagraph);
+    // CKEditor's Italic writes <i>, not <em>.
+    body.querySelectorAll('em').forEach((em) => {
+        const i = em.ownerDocument.createElement('i');
+        Array.from(em.attributes).forEach((a) => i.setAttribute(a.name, a.value));
+        i.append(...Array.from(em.childNodes));
+        em.replaceWith(i);
+    });
+    body.querySelectorAll(`[${CK_ORIGIN_ATTRIBUTE}]`).forEach((el) => el.removeAttribute(CK_ORIGIN_ATTRIBUTE));
+    const wrapperClass = (_a = options.wrapperClass) !== null && _a !== void 0 ? _a : CK_WRAPPER_BASE_CLASS;
+    if (wrapperClass === false)
+        return body.innerHTML;
+    // Built as an element so a class read from stored HTML is escaped like any attribute value.
+    const wrapper = body.ownerDocument.createElement('div');
+    wrapper.setAttribute('class', wrapperClass);
+    wrapper.append(...Array.from(body.childNodes));
+    return wrapper.outerHTML;
+}
+
+/** Node and mark types whose original CKEditor attributes are carried through editing. */
+const CK_COMPAT_TYPES = [
+    'paragraph',
+    'heading',
+    'blockquote',
+    'bulletList',
+    'orderedList',
+    'listItem',
+    'table',
+    'tableRow',
+    'tableCell',
+    'tableHeader',
+    'textStyle',
+    'link',
+    'dynamicField',
+    'pageBreak',
+];
+const ckOrigin = (fallback) => ({
+    default: null,
+    // Splitting a block must not copy the record: the new block is new content.
+    keepOnSplit: false,
+    parseHTML: (element) => { var _a, _b; return (_b = (_a = element.getAttribute(CK_ORIGIN_ATTRIBUTE)) !== null && _a !== void 0 ? _a : fallback === null || fallback === void 0 ? void 0 : fallback(element)) !== null && _b !== void 0 ? _b : null; },
+    renderHTML: (attributes) => attributes['ckOrigin'] ? { [CK_ORIGIN_ATTRIBUTE]: attributes['ckOrigin'] } : {},
+});
+/**
+ * A CKEditor dynamic field pasted into the editor never went through `fromCkHtml()`, so record
+ * its attributes here — otherwise its original id/name/value would be replaced on save.
+ */
+function recordPastedDynamicField(element) {
+    // The editor renders its own fields with this class too; only CKEditor markup lacks `data-field-id`.
+    if (!element.classList.contains('red-dynamic-field') || element.hasAttribute('data-field-id'))
+        return null;
+    const a = Array.from(element.attributes).map((attr) => [attr.name, attr.value]);
+    return JSON.stringify({ a });
+}
+/**
+ * Keeps the `data-ck` record written by `fromCkHtml()` on every supported node and mark, so
+ * `toCkHtml()` can restore the original CKEditor markup on save. Register it together with the
+ * two functions; on its own it only round-trips the attribute.
+ */
+const CkCompat = Extension.create({
+    name: 'ckCompat',
+    addGlobalAttributes() {
+        return [
+            { types: CK_COMPAT_TYPES.filter((t) => t !== 'dynamicField'), attributes: { ckOrigin: ckOrigin() } },
+            { types: ['dynamicField'], attributes: { ckOrigin: ckOrigin(recordPastedDynamicField) } },
+        ];
+    },
+});
 
 const INDENT_DEFAULT = 40; // in pixels
 
@@ -53,7 +665,13 @@ const Indent = Extension.create({
                 attributes: {
                     indent: {
                         parseHTML: (element) => {
-                            return Number(element.style.marginLeft.replace('px', ''));
+                            const marginLeft = element.style.marginLeft;
+                            if (!marginLeft)
+                                return 0;
+                            // Content pasted from Word / CKEditor often indents in pt or cm. Relative values (`em`, `%`)
+                            // cannot be expressed in px and are left unset.
+                            const px = absoluteLengthToPx(marginLeft);
+                            return px === null ? null : Math.round(px * 100) / 100;
                         },
                         renderHTML: (attributes) => {
                             return { style: `margin-left: ${attributes['indent']}px` };
@@ -1273,6 +1891,30 @@ function calculateColumnWidthsForNewColumn(oldColWidths) {
     const reduction = MIN_NEW_COL_WIDTH / oldColWidths.length;
     return oldColWidths.map((w) => w - reduction);
 }
+/**
+ * Read the `border` attrs of the cell the command should merge against.
+ *
+ * `$from.node(-1)` alone is only the cell for a collapsed cursor: with a `CellSelection`
+ * prosemirror-tables resolves `$from` *before* the head cell, so that lookup lands on the
+ * row and reports an empty border — which, now that an omitted field means "leave this
+ * one alone", would clear every field the caller did not pass. `getSelectedCells` covers
+ * the cell-selection and cursor cases; the depth walk covers a text selection inside one
+ * cell, which `getSelectedCells` returns nothing for.
+ */
+function getCurrentCellBorder(state) {
+    var _a, _b, _c, _d;
+    const [firstSelected] = getSelectedCells(state);
+    if (firstSelected)
+        return (_b = (_a = firstSelected.node.attrs) === null || _a === void 0 ? void 0 : _a['border']) !== null && _b !== void 0 ? _b : {};
+    const { $from } = state.selection;
+    for (let depth = $from.depth; depth > 0; depth--) {
+        const node = $from.node(depth);
+        if (node.type.name === 'tableCell' || node.type.name === 'tableHeader') {
+            return (_d = (_c = node.attrs) === null || _c === void 0 ? void 0 : _c['border']) !== null && _d !== void 0 ? _d : {};
+        }
+    }
+    return {};
+}
 const TableDefaultAttributes = {
     border: {
         style: 'double',
@@ -1598,7 +2240,6 @@ const StyledTable = Table.extend({
             }, 
             // Cell
             setCellBorder: (border) => ({ chain, state }) => {
-                var _a;
                 if (!border)
                     return chain()
                         .focus()
@@ -1606,14 +2247,15 @@ const StyledTable = Table.extend({
                         .updateAttributes('tableHeader', { border: null })
                         .run();
                 // Get current border and merge with new values
-                const { selection } = state;
-                const { $from } = selection;
-                const cellPos = $from.node(-1);
-                const currentBorder = ((_a = cellPos === null || cellPos === void 0 ? void 0 : cellPos.attrs) === null || _a === void 0 ? void 0 : _a['border']) || {};
+                const currentBorder = getCurrentCellBorder(state);
+                // `undefined` means "leave this field alone"; an explicit `null` clears it.
+                // A truthiness check conflates the two, so clearing a cell's border colour
+                // fell straight back to the colour being cleared and the UI could never
+                // remove one. Matches `setTableBorder` above.
                 const mergedBorder = {
-                    style: border.style ? border.style : currentBorder.style || null,
-                    color: border.color ? border.color : currentBorder.color || null,
-                    width: border.width ? border.width : currentBorder.width || null,
+                    style: border.style !== undefined ? border.style : currentBorder.style || null,
+                    color: border.color !== undefined ? border.color : currentBorder.color || null,
+                    width: border.width !== undefined ? border.width : currentBorder.width || null,
                 };
                 return chain()
                     .focus()
@@ -2235,4 +2877,4 @@ class Color {
     }
 }
 
-export { ClearContent, Color, CustomOrderedList, DynamicField, EditableRegion, HandleNodeView, INDENT_DEFAULT, ImageRef, Indent, LATEST_SCHEMA_VERSION, NotumHeading, PageBreak, PageBreakNodeView, ResetFormat, ResetOnEnter, RestrictedEditing, StyledTable, StyledTableCell, StyledTableHeader, StyledTableKit, TableDefaultAttributes, TableNodeView, TextCase, createPageBreakNodeView, createTableNodeView, defaultExtensions, docMigrations, generateHTML, getActiveMarkRange, getClosestDomElement, getCombinedCellAttributeValue, getCursorCellInfo, getSelectedCells, getSelectedText, getTableDOMFromView, migrateDoc, normalizeColor };
+export { CK_COMPAT_TYPES, CK_ORIGIN_ATTRIBUTE, CK_UNSUPPORTED_CONTENT, CK_WRAPPER_BASE_CLASS, CkCompat, ClearContent, Color, CustomOrderedList, DynamicField, EditableRegion, HandleNodeView, INDENT_DEFAULT, ImageRef, Indent, LATEST_SCHEMA_VERSION, NotumHeading, PageBreak, PageBreakNodeView, ResetFormat, ResetOnEnter, RestrictedEditing, StyledTable, StyledTableCell, StyledTableHeader, StyledTableKit, TableDefaultAttributes, TableNodeView, TextCase, createCkDomParser, createPageBreakNodeView, createTableNodeView, defaultExtensions, docMigrations, fromCkHtml, generateHTML, getActiveMarkRange, getClosestDomElement, getCombinedCellAttributeValue, getCursorCellInfo, getSelectedCells, getSelectedText, getTableDOMFromView, migrateDoc, normalizeColor, toCkHtml, verifyCkRoundTrip };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phuong-tran-redoc/document-engine-core",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "license": "MIT",
   "author": "Realestatedoc (Redoc)",
@@ -66,6 +66,12 @@
     "tslib": "^2.3.0"
   },
   "peerDependencies": {
-    "lodash-es": "^4.17.10"
+    "lodash-es": "^4.17.10",
+    "happy-dom": "^20.8.9"
+  },
+  "peerDependenciesMeta": {
+    "happy-dom": {
+      "optional": true
+    }
   }
 }

package/src/compat/ckeditor/ck-compat.extension.d.ts

@@ -0,0 +1,9 @@
+import { Extension } from '@tiptap/core';
+/** Node and mark types whose original CKEditor attributes are carried through editing. */
+export declare const CK_COMPAT_TYPES: readonly string[];
+/**
+ * Keeps the `data-ck` record written by `fromCkHtml()` on every supported node and mark, so
+ * `toCkHtml()` can restore the original CKEditor markup on save. Register it together with the
+ * two functions; on its own it only round-trips the attribute.
+ */
+export declare const CkCompat: Extension<any, any>;

package/src/compat/ckeditor/ck-html.d.ts

@@ -0,0 +1,98 @@
+/**
+ * CKEditor 5 HTML compatibility layer.
+ *
+ * Lets the editor load HTML that was produced by the legacy CKEditor 5 build and save it back
+ * in the same shape, so stored documents and the code that reads them keep working.
+ *
+ * - {@link fromCkHtml} runs before content is set into the editor. It strips the CKEditor
+ *   data-processor wrapper and records each element's original attributes, in order, in a
+ *   `data-ck` attribute that the {@link CkCompat} extension carries through editing.
+ * - {@link toCkHtml} runs on `editor.getHTML()`. It rebuilds the CKEditor markup from those
+ *   records: attribute order, `prop:value;` style formatting, `<figure class="table">`,
+ *   `<colgroup>`, bare text in single-paragraph cells, `<i>`, page breaks, dynamic fields and
+ *   the wrapper. Anything the user changed is taken from the editor; anything the editor does
+ *   not model is kept verbatim.
+ *
+ * Both functions need a `DOMParser`. In the browser the global one is used. In Node (no global DOM)
+ * pass one in, e.g. from {@link createCkDomParser}:
+ *
+ * ```ts
+ * const domParser = await createCkDomParser();
+ * const ckHtml = toCkHtml(await generateHTML(json, extensions), { wrapperClass, domParser });
+ * ```
+ */
+/** Attribute that carries the original CKEditor attributes of an element through the editor. */
+export declare const CK_ORIGIN_ATTRIBUTE = "data-ck";
+/** Class list of the CKEditor data-processor wrapper (`CustomHtmlDataProcessor`). */
+export declare const CK_WRAPPER_BASE_CLASS = "ck ck-content ck-print";
+/** The part of the DOM `DOMParser` API the compatibility layer needs. */
+export interface CkDomParser {
+    parseFromString(source: string, type: 'text/html'): Document;
+}
+export interface CkDomOptions {
+    /** Parser to use instead of the global `DOMParser`; required where there is no DOM (Node). */
+    domParser?: CkDomParser;
+}
+export interface CkHtmlOptions extends CkDomOptions {
+    /**
+     * Class list for the outer wrapper `<div>` — pass the `wrapperClass` that {@link fromCkHtml}
+     * returned for this document. Defaults to {@link CK_WRAPPER_BASE_CLASS}; `false` emits no wrapper.
+     */
+    wrapperClass?: string | false;
+}
+export interface CkLoadResult {
+    /** HTML ready to be set into the editor. */
+    html: string;
+    /** Class list of the wrapper that was stripped, or `null` when the input had none. */
+    wrapperClass: string | null;
+    /**
+     * Keys of {@link CK_UNSUPPORTED_CONTENT} found in the input. The editor has no node for these, so
+     * loading the document would drop them: open it read-only (or keep the legacy editor) when non-empty.
+     */
+    unsupported: CkUnsupportedContent[];
+}
+/**
+ * Content produced by CKEditor plugins of the legacy build that this editor cannot represent yet,
+ * keyed by name, with the selector that identifies it in stored HTML.
+ */
+export declare const CK_UNSUPPORTED_CONTENT: {
+    readonly signatureField: ".redr-signature-field";
+    readonly inlineField: ".redr-inline-field";
+    readonly dynamicImage: ".redr-dynamic-image";
+    readonly dealTable: ".redr-deal-table";
+    readonly editorColumn: ".redr-editor-column";
+    readonly restrictedEditingException: ".restricted-editing-exception";
+    readonly image: "img, figure.image";
+};
+export type CkUnsupportedContent = keyof typeof CK_UNSUPPORTED_CONTENT;
+export interface CkRoundTripReport {
+    /** `true` when saving the loaded document unchanged reproduces the input byte-for-byte. */
+    identical: boolean;
+    /** Where the two first differ (a short excerpt of each side), or `null` when identical. */
+    difference: {
+        index: number;
+        expected: string;
+        actual: string;
+    } | null;
+}
+/**
+ * A `DOMParser` for {@link fromCkHtml} / {@link toCkHtml} that works in any environment: the global one
+ * in the browser, otherwise one from happy-dom (already installed with `@tiptap/html`, which
+ * {@link generateHTML} uses for the same reason). Create it once and reuse it.
+ */
+export declare function createCkDomParser(): Promise<CkDomParser>;
+/**
+ * Prepare CKEditor HTML for the editor. Safe to call on HTML that did not come from
+ * CKEditor: it then only records attributes.
+ */
+export declare function fromCkHtml(html: string, options?: CkDomOptions): CkLoadResult;
+/**
+ * Compare the stored HTML with what saving the freshly loaded document would write
+ * (`toCkHtml(editor.getHTML())` before any edit). A difference means the editor could not
+ * represent part of the document and saving would change it — open it read-only instead.
+ */
+export declare function verifyCkRoundTrip(original: string, saved: string): CkRoundTripReport;
+/**
+ * Turn `editor.getHTML()` output back into CKEditor-shaped HTML.
+ */
+export declare function toCkHtml(html: string, options?: CkHtmlOptions): string;

package/src/compat/ckeditor/index.d.ts

@@ -0,0 +1,2 @@
+export * from './ck-compat.extension';
+export * from './ck-html';

package/src/compat/index.d.ts

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

package/src/index.d.ts

@@ -1,3 +1,4 @@
+export * from './compat';
 export * from './constants';
 export * from './extensions';
 export * from './kit';

package/src/internal/css-length.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Convert a single absolute CSS length (`36pt`, `1cm`, `40px`) to pixels.
+ * Returns `null` for anything else: relative units (`em`, `%`), keywords, or several values.
+ */
+export declare function absoluteLengthToPx(value: string | null | undefined): number | null;