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

package/README.md

@@ -112,6 +112,19 @@ const saved = toCkHtml(editor.getHTML(), { wrapperClass: wrapperClass ?? false }
 verifyCkRoundTrip(storedHtml, saved); // before editing: is the document reproduced exactly?
 ```
 
+CKEditor restricted-editing exceptions (`<span class="restricted-editing-exception">`) load as editable
+regions when `EditableRegion` and `RestrictedEditing` are registered, and are saved back in that markup. In
+restricted mode, set content with `editor.chain().setMeta('restrictedEditing', { allow: true }).setContent(html).run()`
+— otherwise the restriction blocks the change once the document is not empty.
+
+A document stored as several CKEditor wrappers side by side (sections joined after CKEditor saved them) loads
+as one document. `wrapperClass` is the first wrapper's class; the block that opens each later section records
+its wrapper (and the whitespace stored before it), and `toCkHtml` splits the document there again. Deleting that
+block merges its section into the one before; a section whose content is all deleted loses its wrapper, so when
+that is the first section the saved document starts with the next section's wrapper class. A pasted or dropped
+copy of an opening block does not open a section. A section that opens with a numbered list cannot be split
+again, so such a document keeps the wrappers it had (and does not round-trip).
+
 On a backend (no DOM) pass a parser. `createCkDomParser()` uses happy-dom, which `@tiptap/html` already installs:
 
 ```typescript

package/index.esm.js

@@ -1,11 +1,11 @@
 import { Extension, Node, mergeAttributes } from '@tiptap/core';
+import { Slice, Fragment, DOMSerializer } from '@tiptap/pm/model';
+import { Plugin, PluginKey, TextSelection, NodeSelection } from '@tiptap/pm/state';
 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';
 import { selectionCell, findTable, TableMap, CellSelection, tableNodeTypes, deleteColumn, addColumnBefore, addColumnAfter } from '@tiptap/pm/tables';
 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';
@@ -61,10 +61,14 @@ function absoluteLengthToPx(value) {
  *   `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
+ *   `<colgroup>`, bare text in single-paragraph cells, `<i>`, page breaks, dynamic fields,
+ *   restricted-editing exceptions and the wrapper. Anything the user changed is taken from the editor; anything the editor does
  *   not model is kept verbatim.
  *
+ * A document stored as several wrappers side by side (sections joined after CKEditor saved them) loads
+ * as one document; the first block of each later section records its wrapper, and saving splits the
+ * document there again.
+ *
  * 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}:
  *
@@ -87,11 +91,17 @@ const CK_UNSUPPORTED_CONTENT = {
     dynamicImage: '.redr-dynamic-image',
     dealTable: '.redr-deal-table',
     editorColumn: '.redr-editor-column',
+    /** @deprecated Supported since 0.1.8 (loads as an editable region); no longer reported. */
     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';
+/**
+ * Top-level blocks that can carry the record of the wrapper they open. Not `ol`: the numbered list
+ * rewrites its markup and does not keep its record.
+ */
+const SECTION_START_SELECTOR = 'p,h1,h2,h3,h4,h5,h6,table,blockquote,ul,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 = {
@@ -122,6 +132,8 @@ const DEFAULT_CELL_VERTICAL_ALIGN = 'middle';
 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';
+/** Markup of CKEditor's restricted-editing exception (an editable region). */
+const EDITABLE_REGION_CK_CLASS = 'restricted-editing-exception';
 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') {
@@ -214,6 +226,16 @@ function readOrigin(el) {
             return null;
         origin.c = c;
     }
+    if (record['w'] !== undefined) {
+        if (typeof record['w'] !== 'string')
+            return null;
+        origin.w = record['w'];
+    }
+    if (record['s'] !== undefined) {
+        if (typeof record['s'] !== 'string' || !WHITESPACE.test(record['s']))
+            return null;
+        origin.s = record['s'];
+    }
     return origin;
 }
 function writeOrigin(el, origin) {
@@ -229,11 +251,27 @@ function writeOrigin(el, origin) {
 function fromCkHtml(html, options = {}) {
     const body = parse(html !== null && html !== void 0 ? html : '', options.domParser);
     let wrapperClass = null;
+    // The block that opens each wrapper after the first, with that wrapper's class list.
+    const sectionStarts = [];
     const only = body.children.length === 1 ? body.firstElementChild : null;
-    if (only && only.tagName === 'DIV' && only.classList.contains('ck-content') && only.classList.contains('ck')) {
+    const sections = only ? null : sideBySideWrappers(body);
+    if (only && isCkWrapper(only)) {
         wrapperClass = only.getAttribute('class');
         only.replaceWith(...Array.from(only.childNodes));
     }
+    else if (sections) {
+        wrapperClass = sections[0].wrapper.getAttribute('class');
+        sections.forEach(({ wrapper, separator }, i) => {
+            var _a;
+            const start = wrapper.firstElementChild;
+            const block = start.matches('figure.table') ? start.querySelector(':scope > table') : start;
+            if (i > 0)
+                sectionStarts.push([block, { cls: (_a = wrapper.getAttribute('class')) !== null && _a !== void 0 ? _a : '', separator }]);
+            wrapper.replaceWith(...Array.from(wrapper.childNodes));
+        });
+        // The whitespace between the wrappers is in the records; between blocks it is not content.
+        Array.from(body.childNodes).forEach((node) => isWhitespaceText(node) && node.remove());
+    }
     body.querySelectorAll(TRACKED_SELECTOR).forEach((el) => {
         // Dynamic-field spans keep their attributes in their own record (see DynamicField export).
         writeOrigin(el, { a: attrsOf(el) });
@@ -257,9 +295,56 @@ function fromCkHtml(html, options = {}) {
         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]));
+    sectionStarts.forEach(([block, { cls, separator }]) => {
+        var _a;
+        const origin = (_a = readOrigin(block)) !== null && _a !== void 0 ? _a : { a: attrsOf(block) };
+        origin.w = cls;
+        if (separator)
+            origin.s = separator;
+        writeOrigin(block, origin);
+    });
+    const unsupported = Object.keys(CK_UNSUPPORTED_CONTENT).filter((key) => key !== 'restrictedEditingException' && body.querySelector(CK_UNSUPPORTED_CONTENT[key]));
     return { html: body.innerHTML, wrapperClass, unsupported };
 }
+function isCkWrapper(el) {
+    return el.tagName === 'DIV' && el.classList.contains('ck-content') && el.classList.contains('ck');
+}
+/** Whitespace only (no `&nbsp;`): what an HTML serializer or a string join puts between documents. */
+const WHITESPACE = /^[ \t\n\r\f]*$/;
+const isWhitespaceText = (node) => { var _a; return node.nodeType === 3 && WHITESPACE.test((_a = node.nodeValue) !== null && _a !== void 0 ? _a : ''); };
+/**
+ * The wrappers of a document stored as several CKEditor documents side by side, with the whitespace
+ * between each one and the one before it, or `null` when the body is anything else. Whitespace around
+ * the wrappers is allowed (as with a single wrapper). Each wrapper must open with a block that can
+ * carry its record, so that saving can split the document at the same places.
+ */
+function sideBySideWrappers(body) {
+    const sections = [];
+    let separator = '';
+    for (const node of Array.from(body.childNodes)) {
+        if (isWhitespaceText(node)) {
+            separator += node.nodeValue;
+            continue;
+        }
+        if (node.nodeType !== 1 || !isCkWrapper(node))
+            return null;
+        const block = node.firstElementChild;
+        if (!block || Array.from(node.childNodes).indexOf(block) !== leadingWhitespace(node))
+            return null;
+        const opensWithTable = block.matches('figure.table') && !!block.querySelector(':scope > table');
+        if (!opensWithTable && !block.matches(SECTION_START_SELECTOR))
+            return null;
+        sections.push({ wrapper: node, separator });
+        separator = '';
+    }
+    return sections.length > 1 ? sections : null;
+}
+/** Number of whitespace-only text nodes at the start of an element. */
+function leadingWhitespace(el) {
+    const nodes = Array.from(el.childNodes);
+    const first = nodes.findIndex((n) => !isWhitespaceText(n));
+    return first < 0 ? nodes.length : first;
+}
 /**
  * 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
@@ -480,6 +565,33 @@ function exportDynamicFields(body) {
         el.replaceWith(span);
     });
 }
+/**
+ * Write editable regions as CKEditor restricted-editing exceptions. The editor fills a region it
+ * creates empty with a zero-width space (and refills one emptied in restricted mode with a space);
+ * a region left without text is written as `&nbsp;` so it stays in the document (CKEditor's
+ * empty-content convention). The exception class is always kept, whatever the record says: it is
+ * what identifies the region in stored HTML.
+ */
+function exportEditableRegions(body) {
+    body.querySelectorAll('span[data-editable-region]').forEach((el) => {
+        var _a, _b, _c;
+        const span = el.ownerDocument.createElement('span');
+        setAttributesInOrder(span, (_b = (_a = readOrigin(el)) === null || _a === void 0 ? void 0 : _a.a) !== null && _b !== void 0 ? _b : [['class', EDITABLE_REGION_CK_CLASS]]);
+        if (!span.classList.contains(EDITABLE_REGION_CK_CLASS))
+            span.classList.add(EDITABLE_REGION_CK_CLASS);
+        span.append(...Array.from(el.childNodes));
+        stripZeroWidthSpaces(span);
+        if (!((_c = span.textContent) === null || _c === void 0 ? void 0 : _c.trim()))
+            span.textContent = '\u00a0';
+        el.replaceWith(span);
+    });
+}
+function stripZeroWidthSpaces(node) {
+    var _a;
+    if (node.nodeType === 3)
+        node.nodeValue = ((_a = node.nodeValue) !== null && _a !== void 0 ? _a : '').replace(/\u200b/g, '');
+    node.childNodes.forEach(stripZeroWidthSpaces);
+}
 /**
  * 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.
@@ -553,14 +665,19 @@ function toCkHtml(html, options = {}) {
     var _a;
     const body = parse(html !== null && html !== void 0 ? html : '', options.domParser);
     const probe = body.ownerDocument.createElement('span');
+    // Marked first: the export passes below replace some blocks, and their records with them.
+    const sections = markSections(body);
     exportDynamicFields(body);
     exportPageBreaks(body);
+    exportEditableRegions(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;
+        if (el.matches(`span.${EDITABLE_REGION_CK_CLASS}`))
+            return;
         reconcileElement(el, (_b = (_a = readOrigin(el)) === null || _a === void 0 ? void 0 : _a.a) !== null && _b !== void 0 ? _b : null, probe);
     });
     dropTrailingNode(body);
@@ -580,13 +697,53 @@ function toCkHtml(html, options = {}) {
     });
     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)
+    if (wrapperClass === false) {
+        sections.forEach((_, marker) => marker.remove());
         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;
+    }
+    return wrapSections(body, wrapperClass, sections);
+}
+/**
+ * Put a marker before each top-level block that opens a wrapper of its own (see {@link fromCkHtml}),
+ * mapped to that wrapper.
+ */
+function markSections(body) {
+    const sections = new Map();
+    Array.from(body.children).forEach((block) => {
+        var _a;
+        const origin = readOrigin(block);
+        if ((origin === null || origin === void 0 ? void 0 : origin.w) === undefined)
+            return;
+        const marker = body.ownerDocument.createComment('ck-section');
+        block.before(marker);
+        sections.set(marker, { cls: origin.w, separator: (_a = origin.s) !== null && _a !== void 0 ? _a : '' });
+    });
+    return sections;
+}
+/**
+ * Wrap the document, starting a new wrapper at each section marker. A wrapper left empty (its
+ * section was deleted) is dropped, with the whitespace stored before it.
+ */
+function wrapSections(body, firstClass, sections) {
+    const doc = body.ownerDocument;
+    // Built as elements so a class read from stored HTML is escaped like any attribute value.
+    const open = ({ cls, separator }) => {
+        const wrapper = doc.createElement('div');
+        wrapper.setAttribute('class', cls);
+        return { wrapper, separator };
+    };
+    const wrappers = [open({ cls: firstClass, separator: '' })];
+    Array.from(body.childNodes).forEach((node) => {
+        const boundary = sections.get(node);
+        if (boundary === undefined)
+            wrappers[wrappers.length - 1].wrapper.append(node);
+        else
+            wrappers.push(open(boundary));
+    });
+    const kept = wrappers.filter((w) => w.wrapper.childNodes.length);
+    if (!kept.length)
+        return wrappers[0].wrapper.outerHTML;
+    return kept.map((w, i) => (i ? w.separator : '') + w.wrapper.outerHTML).join('');
 }
 
 /** Node and mark types whose original CKEditor attributes are carried through editing. */
@@ -605,6 +762,7 @@ const CK_COMPAT_TYPES = [
     'link',
     'dynamicField',
     'pageBreak',
+    'editableRegion',
 ];
 const ckOrigin = (fallback) => ({
     default: null,
@@ -624,6 +782,36 @@ function recordPastedDynamicField(element) {
     const a = Array.from(element.attributes).map((attr) => [attr.name, attr.value]);
     return JSON.stringify({ a });
 }
+/**
+ * A pasted or dropped copy of the block that opens a stored section must not open another one: drop
+ * the section keys (`w`, `s`) from the records of pasted content. The block left in place keeps them.
+ */
+function withoutSectionRecords(fragment) {
+    const nodes = [];
+    fragment.forEach((node) => {
+        if (node.isText) {
+            nodes.push(node);
+            return;
+        }
+        const origin = node.attrs['ckOrigin'];
+        const attrs = typeof origin === 'string' ? Object.assign(Object.assign({}, node.attrs), { ckOrigin: dropSectionKeys(origin) }) : node.attrs;
+        nodes.push(node.type.create(attrs, withoutSectionRecords(node.content), node.marks));
+    });
+    return Fragment.fromArray(nodes);
+}
+function dropSectionKeys(origin) {
+    try {
+        const record = JSON.parse(origin);
+        if (!record || typeof record !== 'object' || (!('w' in record) && !('s' in record)))
+            return origin;
+        delete record.w;
+        delete record.s;
+        return JSON.stringify(record);
+    }
+    catch (_a) {
+        return origin;
+    }
+}
 /**
  * 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
@@ -637,6 +825,16 @@ const CkCompat = Extension.create({
             { types: ['dynamicField'], attributes: { ckOrigin: ckOrigin(recordPastedDynamicField) } },
         ];
     },
+    addProseMirrorPlugins() {
+        return [
+            new Plugin({
+                key: new PluginKey('ckCompatPaste'),
+                props: {
+                    transformPasted: (slice) => new Slice(withoutSectionRecords(slice.content), slice.openStart, slice.openEnd),
+                },
+            }),
+        ];
+    },
 });
 
 const INDENT_DEFAULT = 40; // in pixels

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phuong-tran-redoc/document-engine-core",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "type": "module",
   "license": "MIT",
   "author": "Realestatedoc (Redoc)",

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

@@ -9,10 +9,14 @@
  *   `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
+ *   `<colgroup>`, bare text in single-paragraph cells, `<i>`, page breaks, dynamic fields,
+ *   restricted-editing exceptions and the wrapper. Anything the user changed is taken from the editor; anything the editor does
  *   not model is kept verbatim.
  *
+ * A document stored as several wrappers side by side (sections joined after CKEditor saved them) loads
+ * as one document; the first block of each later section records its wrapper, and saving splits the
+ * document there again.
+ *
  * 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}:
  *
@@ -43,7 +47,10 @@ export interface CkHtmlOptions extends CkDomOptions {
 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. */
+    /**
+     * Class list of the wrapper that was stripped (the first one, when the document is several wrappers
+     * side by side), 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
@@ -61,6 +68,7 @@ export declare const CK_UNSUPPORTED_CONTENT: {
     readonly dynamicImage: ".redr-dynamic-image";
     readonly dealTable: ".redr-deal-table";
     readonly editorColumn: ".redr-editor-column";
+    /** @deprecated Supported since 0.1.8 (loads as an editable region); no longer reported. */
     readonly restrictedEditingException: ".restricted-editing-exception";
     readonly image: "img, figure.image";
 };