@bloklabs/angular 1.4.2 → 1.4.3

package/fesm2022/bloklabs-angular.mjs

@@ -359,6 +359,77 @@ const generateId = (prefix = '') => {
     return `${prefix}${(Math.floor(Math.random() * ID_RANDOM_MULTIPLIER)).toString(HEXADECIMAL_RADIX)}`;
 };
 
+/**
+ * Flatten a hierarchical block spec (nodes with `children`) into the flat DFS
+ * pre-order `OutputBlockData[]` Blok stores, wiring every node's `parent` and
+ * `content` id links.
+ *
+ * This is the pure counterpart of the live `insertTree` mutation: the same DFS,
+ * without an editor. Use it to seed nested content — columns, tables, a whole
+ * document — without hand-authoring `parent`/`content` arrays:
+ *
+ * @example
+ * new Blok({
+ *   data: {
+ *     blocks: flattenTree([
+ *       { type: 'column_list', children: [
+ *         { type: 'column', children: [{ type: 'paragraph', data: { text: 'L' } }] },
+ *         { type: 'column', children: [{ type: 'paragraph', data: { text: 'R' } }] },
+ *       ] },
+ *     ]),
+ *   },
+ * });
+ *
+ * @param spec - a single root node or an array of root nodes.
+ * @param options - `parentId` sets the `parent` of the root node(s);
+ *   `generateId` overrides id generation for nodes that omit an `id` (default:
+ *   Blok's nanoid scheme).
+ * @returns DFS pre-order blocks with `parent`/`content` wired. Leaves omit the
+ *   empty `content` array, matching the documented `OutputBlockData` shape.
+ * @throws if an explicit `id` is reused within the spec — a duplicate id would
+ *   corrupt every id-keyed lookup, so it is surfaced loudly rather than encoded.
+ */
+function flattenTree(spec, options = {}) {
+    const generateId = options.generateId ?? generateBlockId;
+    const rootParent = options.parentId ?? undefined;
+    const flat = [];
+    const usedIds = new Set();
+    // Pre-order DFS: push self FIRST, then recurse each child, so the flat array
+    // is DFS-contiguous. `content` is filled as each child is visited and returns
+    // its id; it is omitted for leaves.
+    const visit = (node, parent) => {
+        const id = node.id ?? generateId();
+        if (usedIds.has(id)) {
+            throw new Error(`flattenTree: duplicate block id "${id}" — every block id must be unique.`);
+        }
+        usedIds.add(id);
+        const childIds = [];
+        const flatNode = {
+            id,
+            // `type` is OMITTED (not present-with-undefined) when absent so core's
+            // `type || defaultBlock` fallback resolves the default block cleanly.
+            ...(node.type !== undefined ? { type: node.type } : {}),
+            data: node.data ?? {},
+            ...(node.tunes !== undefined ? { tunes: node.tunes } : {}),
+            ...(parent !== undefined ? { parent } : {}),
+        };
+        flat.push(flatNode);
+        for (const child of node.children ?? []) {
+            childIds.push(visit(child, id));
+        }
+        // Only wire `content` when there are children — leaves stay clean.
+        if (childIds.length > 0) {
+            flatNode.content = childIds;
+        }
+        return id;
+    };
+    const roots = Array.isArray(spec) ? spec : [spec];
+    for (const root of roots) {
+        visit(root, rootParent);
+    }
+    return flat;
+}
+
 /**
  * Enumerate the editor's blocks once into BlockNode records, in flat order,
  * deriving each node's contentIds from the children that name it as parent.
@@ -1218,54 +1289,41 @@ const createBlocksApiForEditor = (editor, onRead = () => undefined) => {
                 return null;
             }
         }
-        // Every node needs a stable id BEFORE flattening so parent/content links
-        // can reference siblings/children. Respect an explicit node id; generate
-        // one (core's nanoid scheme) otherwise.
-        const flat = [];
-        // Collision guard: an explicit id that already exists in the tree (or is
-        // reused within this same spec) would create a duplicate-id block,
-        // corrupting every id-keyed lookup (getById, parent/content links). A tree
-        // insert always creates fresh blocks (it is NOT insert-if-absent), so a
-        // collision is rejected up front — nothing is inserted and null is
-        // returned, mirroring insert's null contract. Generated ids never collide.
-        // Mutable property on a const holder (no `let`): flipped from inside the
-        // recursive visit when a colliding explicit id is seen.
-        const usedIds = new Set();
-        const collision = { hit: false };
-        // Pre-order DFS: push self FIRST, then recurse each child, so the flat
-        // array is DFS-contiguous (the invariant core's insertMany + the hook's
-        // getChildren depend on). `content` is the live child-id array, filled as
-        // each child is visited and returns its id. The root's `parent` is the
-        // resolved placement parent (undefined for root level); children's `parent`
-        // is their enclosing node's id.
-        const visit = (node, parent) => {
-            if (node.id !== undefined && (usedIds.has(node.id) || getById(node.id) !== null)) {
-                collision.hit = true;
+        // Flatten the nested spec to a DFS pre-order array with wired
+        // `parent`/`content` links — the same transform used to seed nested data,
+        // shared as the pure `flattenTree` helper. `parentId` becomes the root's
+        // `parent`. flattenTree throws on an id reused WITHIN the spec (a duplicate
+        // would corrupt every id-keyed lookup); a tree insert always creates fresh
+        // blocks (NOT insert-if-absent), so that is rejected up front — null,
+        // mirroring insert's null contract.
+        const flat = (() => {
+            try {
+                return flattenTree(spec, { parentId: parentId ?? undefined });
             }
-            const id = node.id ?? generateBlockId();
-            usedIds.add(id);
-            const content = [];
-            const flatNode = {
-                id,
-                // `type` is OMITTED (not present-with-undefined) when absent so core's
-                // `type || defaultBlock` fallback resolves the default block cleanly.
-                ...(node.type !== undefined ? { type: node.type } : {}),
-                data: node.data ?? {},
-                content,
-                ...(node.tunes !== undefined ? { tunes: node.tunes } : {}),
-                ...(parent !== undefined ? { parent } : {}),
-            };
-            flat.push(flatNode);
-            for (const child of node.children ?? []) {
-                content.push(visit(child, id));
+            catch {
+                return null;
             }
-            return id;
-        };
-        const rootId = visit(spec, parentId ?? undefined);
-        // A colliding explicit id is rejected before any insert (see usedIds doc).
-        if (collision.hit) {
+        })();
+        if (flat === null) {
             return null;
         }
+        // External collision: an explicit id already present in the live tree would
+        // also create a duplicate-id block. Snapshot the existing ids once and
+        // reject if any flat node reuses one. Generated ids never collide.
+        const existingIds = new Set(snapshotNodes(reader).map((n) => n.id));
+        if (flat.some((node) => existingIds.has(node.id))) {
+            return null;
+        }
+        const rootId = flat[0].id;
+        // flattenTree omits `content` on leaves (clean seed-data shape). insertMany
+        // wants every node to carry an explicit child-id array — a leaf's
+        // `contentIds: []` states "no children" rather than leaving it undefined —
+        // so stamp the empty array back on before handing the batch to core.
+        for (const node of flat) {
+            if (node.content === undefined) {
+                node.content = [];
+            }
+        }
         const flatIndex = resolveInsertIndex(reader, parentId, position);
         // ONE transact for the whole subtree → a single atomic undo step. Core's
         // insertMany composes EVERY node before inserting any, so an unknown tool
@@ -1677,6 +1735,226 @@ function deepEqual(a, b) {
     return aKeys.every((key) => Object.prototype.hasOwnProperty.call(bObj, key) && deepEqual(aObj[key], bObj[key]));
 }
 
+/**
+ * Public utilities for working with saved editor documents (`OutputData`).
+ *
+ * Consumers persisting editor content need two recurring predicates that the
+ * editor itself already relies on internally:
+ *
+ * - structural equality, to dedupe the `data → render → onSave → data` echo
+ *   round-trip without clobbering the caret;
+ * - emptiness, to decide whether a document carries any user content
+ *   (placeholder states, "save" button gating, skipping empty submissions).
+ *
+ * Both accept the loose wire shape (`data: null`, `id: null`, nullish
+ * documents) so backend DTOs can be passed as-is.
+ */
+/**
+ * Compares two blocks structurally. The `id` participates only when BOTH
+ * blocks carry one: the editor mints a fresh id whenever content arrives
+ * without one (see {@link normalizeOutputBlocks}), so an id-less origin
+ * document must still compare equal to its saved echo.
+ * @param a - first block to compare
+ * @param b - second block to compare
+ * @returns true when the blocks are structurally equal
+ */
+function equalsOutputBlock(a, b) {
+    const { id: idA, ...restA } = a;
+    const { id: idB, ...restB } = b;
+    const hasIdA = typeof idA === 'string' && idA !== '';
+    const hasIdB = typeof idB === 'string' && idB !== '';
+    if (hasIdA && hasIdB && idA !== idB) {
+        return false;
+    }
+    return deepEqual(restA, restB);
+}
+/**
+ * The tool a pristine editor seeds its first (empty) block with. An empty block
+ * of this type is UI scaffolding, not user content — see
+ * {@link EqualsOutputDataOptions.ignoreEmptyDefaultBlocks}.
+ */
+const DEFAULT_BLOCK_TYPE = 'paragraph';
+/**
+ * True for an empty block of the default paragraph tool — the editor's own
+ * scaffolding, not user content.
+ * @param block - block to inspect
+ * @returns true when the block is an empty default paragraph
+ */
+function isEmptyDefaultBlock(block) {
+    return block.type === DEFAULT_BLOCK_TYPE && isEmptyValue(block.data);
+}
+/**
+ * Resolves the blocks to compare for a document, dropping empty default blocks
+ * when {@link EqualsOutputDataOptions.ignoreEmptyDefaultBlocks} is set.
+ * @param data - document whose blocks are collected
+ * @param options - comparison options
+ * @returns the blocks to compare
+ */
+function comparableBlocks(data, options) {
+    const blocks = data?.blocks ?? [];
+    if (options?.ignoreEmptyDefaultBlocks === true) {
+        return blocks.filter((block) => !isEmptyDefaultBlock(block));
+    }
+    return blocks;
+}
+/**
+ * Structural equality for saved documents. Compares the `blocks` arrays
+ * deeply; the volatile `time` and `version` envelope fields are ignored, so a
+ * document round-tripped through `save()` compares equal to its echo. Block
+ * ids are compared only when both sides carry one — the editor mints fresh
+ * ids for id-less content, so a legacy document still equals its saved echo.
+ * Nullish documents compare equal to `{ blocks: [] }`.
+ *
+ * Pass `{ ignoreEmptyDefaultBlocks: true }` for dirty-vs-baseline checks so a
+ * pristine editor (one empty default paragraph) equals a saved-empty baseline —
+ * see {@link EqualsOutputDataOptions}.
+ * @param a - first document to compare
+ * @param b - second document to compare
+ * @param options - comparison options
+ * @returns true when both documents hold structurally equal blocks
+ */
+function equalsOutputData(a, b, options) {
+    const blocksA = comparableBlocks(a, options);
+    const blocksB = comparableBlocks(b, options);
+    return blocksA.length === blocksB.length && blocksA.every((block, index) => equalsOutputBlock(block, blocksB[index]));
+}
+/**
+ * A bounded window of the editor's recently emitted `onSave` payloads, used by
+ * the framework adapters to recognize controlled-`data` echoes. Deduping
+ * against only the LAST emitted payload is not enough: a host that persists on
+ * save and refetches can hand the adapter a STALE echo — an earlier save
+ * arriving after a newer one already replaced the baseline — and re-rendering
+ * it would clobber the caret and any content typed since. Matching is
+ * structural ({@link equalsOutputData}), so envelopes reshaped in transit
+ * (fresh `time`, stripped ids) still count as echoes.
+ * @param capacity - number of payloads retained before the oldest is evicted
+ * @returns the echo window
+ */
+function createEmittedEchoWindow(capacity = 20) {
+    const emitted = [];
+    return {
+        record(data) {
+            emitted.push(data);
+            if (emitted.length > capacity) {
+                emitted.shift();
+            }
+        },
+        matches(data) {
+            return emitted.some((payload) => equalsOutputData(payload, data));
+        },
+        clear() {
+            emitted.length = 0;
+        },
+    };
+}
+/**
+ * A shared, deeply frozen empty document. Consumers persisting editor content
+ * repeatedly hand-write `{ blocks: [] }` for cleared/pristine baselines; this
+ * is the canonical value to use instead. Frozen (blocks array included) so a
+ * shared reference can never be mutated into a stale non-empty baseline.
+ */
+const EMPTY_OUTPUT_DATA = Object.freeze({
+    // Freeze the array too, so a shared reference can't be mutated. The public
+    // `blocks` type is mutable (`OutputBlockData[]`), so the frozen (readonly)
+    // array is re-widened through `unknown` — runtime stays frozen.
+    blocks: Object.freeze([]),
+});
+/**
+ * Maps a controlled `data` value to something the editor's `render()` accepts.
+ * A whole-document `null` — a controlled "clear to empty" — becomes
+ * `{ blocks: [] }`; any real document passes through untouched.
+ *
+ * The framework adapters (React/Vue/Angular) route their reactive `data` path
+ * through this so a `null` never reaches `render()`, whose strict guard reads
+ * `data.blocks` and would throw on `null`. `undefined` (uncontrolled) is handled
+ * by the adapters before this point, so it is intentionally not an input here.
+ * @param data - a controlled document, or `null` for an empty document
+ * @returns a document `render()` can consume
+ */
+function toRenderableData(data) {
+    return data === null ? { blocks: [] } : data;
+}
+/**
+ * Normalizes blocks from the loose wire shape into the strict saved shape at
+ * the editor's input boundaries: a `null`/missing `data` becomes `{}`, a
+ * `null`/empty `id` is dropped so the block factory generates a fresh one.
+ * Idempotent — strict blocks pass through unchanged (shallow-copied).
+ * @param blocks - blocks in either the strict or the loose wire shape
+ * @returns blocks in the strict saved shape
+ */
+function normalizeOutputBlocks(blocks) {
+    return blocks.map((block) => {
+        const { id, data, ...rest } = block;
+        return {
+            ...rest,
+            ...(typeof id === 'string' && id !== '' ? { id } : {}),
+            data: data ?? {},
+        };
+    });
+}
+/**
+ * Normalizes a whole loose wire document into the strict saved
+ * {@link OutputData} shape at an input boundary. A nullish document becomes
+ * `{ blocks: [] }`; `null` envelope fields (`time`/`version`) are dropped; each
+ * block is passed through {@link normalizeOutputBlocks}, so `null`/missing
+ * `data` becomes `{}` and `null`/empty ids are dropped for regeneration.
+ *
+ * Unlike a hand-written `blocks.map(...)` mapper, this preserves every block
+ * passthrough field — `tunes`, `parent`, `content`, `indent`, edit metadata —
+ * so a backend DTO can be turned into strict `OutputData` without silently
+ * losing hierarchy or tunes. Idempotent: a strict document passes through
+ * unchanged (shallow-copied).
+ * @param data - a document in the strict or loose wire shape, or nullish
+ * @returns the document in the strict saved shape
+ */
+function normalizeOutputData(data) {
+    if (data === null || data === undefined) {
+        return { blocks: [] };
+    }
+    return {
+        ...(typeof data.version === 'string' ? { version: data.version } : {}),
+        ...(typeof data.time === 'number' ? { time: data.time } : {}),
+        blocks: normalizeOutputBlocks(data.blocks),
+    };
+}
+/**
+ * True when the value carries no user content: blank/whitespace-only strings,
+ * empty arrays, plain objects whose values are all empty, and nullish values.
+ * Numbers and booleans are presentation metadata (`level`, `checked`, styles)
+ * and never count as content on their own.
+ * @param value - block data value to inspect
+ * @returns true when the value carries no user content
+ */
+function isEmptyValue(value) {
+    if (value === null || value === undefined) {
+        return true;
+    }
+    if (typeof value === 'string') {
+        return value.trim() === '';
+    }
+    if (Array.isArray(value)) {
+        return value.every(isEmptyValue);
+    }
+    if (typeof value === 'object') {
+        return Object.values(value).every(isEmptyValue);
+    }
+    // Numbers, booleans and other primitives are metadata, not content.
+    return true;
+}
+/**
+ * True when the document carries no user content: it is nullish, has no
+ * blocks, or every block's data holds only empty values (see
+ * {@link isEmptyValue}). Note that content-less visual blocks (e.g. a divider,
+ * whose data is `{}`) count as empty — check `blocks.length` when mere block
+ * presence matters.
+ * @param data - document to inspect
+ * @returns true when the document carries no user content
+ */
+function isEmptyOutputData(data) {
+    const blocks = data?.blocks ?? [];
+    return blocks.every((block) => isEmptyValue(block.data));
+}
+
 // src/shared/prop-schema.ts
 /**
  * Fill a data object against the schema: every schema key present, incoming
@@ -2470,7 +2748,9 @@ class BlokEditorComponent {
                 return;
             }
             this.lastRenderedData = data;
-            this.renderChain = this.renderChain.catch(() => undefined).then(() => editor.render(data));
+            // `data` may be null (a controlled "clear to empty"); render() throws on
+            // null, so normalize null → { blocks: [] } at the boundary.
+            this.renderChain = this.renderChain.catch(() => undefined).then(() => editor.render(toRenderableData(data)));
         });
         // Emit `ready` once per editor, after `instance()` is populated so a consumer
         // reading the component/ref instance inside the handler sees it.