@bloklabs/angular 1.8.0 → 1.10.0

package/fesm2022/bloklabs-angular.mjs

@@ -420,6 +420,39 @@ const generateId = (prefix = '') => {
     return `${prefix}${(Math.floor(Math.random() * ID_RANDOM_MULTIPLIER)).toString(HEXADECIMAL_RADIX)}`;
 };
 
+/**
+ * Whether a spec node is a pre-flat run (`{ blocks: [...] }`) rather than a
+ * tree node. Keyed on the `blocks` array, the only field the two shapes cannot
+ * share.
+ * @param node - spec node to classify
+ */
+const isRunSpec = (node) => {
+    return Array.isArray(node.blocks);
+};
+/**
+ * Wire-tolerant id read: `null` and `''` mean "absent", as everywhere else a
+ * loaded document is normalized.
+ * @param id - id as it arrived on a saved block
+ */
+const nonEmptyId = (id) => {
+    return typeof id === 'string' && id !== '' ? id : undefined;
+};
+/**
+ * Reject an already-flat block passed where a TREE node is expected. A spec
+ * node has no `parent`/`content` fields, so such a block would be flattened
+ * with its links silently DROPPED — the structure it described is gone and
+ * nothing reports it. Pre-flat blocks belong in a run node instead.
+ * @param node - tree node about to be flattened
+ * @throws if the node carries link information a tree node cannot express
+ */
+const assertNotPreFlat = (node) => {
+    const asFlat = node;
+    const carriesParent = typeof asFlat.parent === 'string' && asFlat.parent !== '';
+    const carriesContent = Array.isArray(asFlat.content) && asFlat.content.length > 0;
+    if (carriesParent || carriesContent) {
+        throw new Error(`flattenTree: block "${node.id ?? '(no id)'}" carries \`parent\`/\`content\` links, which a tree node cannot express — pass pre-flat blocks as a run node: { blocks: [...] }.`);
+    }
+};
 /**
  * Flatten a hierarchical block spec (nodes with `children`) into the flat DFS
  * pre-order `OutputBlockData[]` Blok stores, wiring every node's `parent` and
@@ -441,29 +474,82 @@ const generateId = (prefix = '') => {
  *   },
  * });
  *
- * @param spec - a single root node or an array of root nodes.
+ * Content that is not tree-shaped to begin with — an already-flat saved
+ * document a migration is splicing into a page — goes in as a RUN node,
+ * `{ blocks: [...] }`, at the root or as a child. A run is spliced verbatim:
+ * ids, `data`, `tunes` and existing `parent`/`content` links are kept, and only
+ * the blocks it left un-parented are re-parented onto the enclosing node.
+ *
+ * @example
+ * flattenTree({ type: 'column', children: [{ blocks: saved.blocks }] });
+ *
+ * @param spec - a single root node or an array of root nodes; each is either a
+ *   tree node or a pre-flat run.
  * @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.
+ *   corrupt every id-keyed lookup, so it is surfaced loudly rather than encoded
+ *   — or if a TREE node carries `parent`/`content` links, which it cannot
+ *   express (that is a pre-flat block; wrap it in a run node).
  */
 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();
+    /**
+     * Resolve a node's id and reserve it. A duplicate would corrupt every
+     * id-keyed lookup, so it is surfaced loudly rather than encoded.
+     * @param explicitId - id the spec carried, if any
+     */
+    const claimId = (explicitId) => {
+        const id = explicitId ?? generateId();
         if (usedIds.has(id)) {
             throw new Error(`flattenTree: duplicate block id "${id}" — every block id must be unique.`);
         }
         usedIds.add(id);
+        return id;
+    };
+    /**
+     * Splice a pre-flat run in verbatim: every block keeps its id, `data`,
+     * `tunes` and its existing `parent`/`content` links, and only the blocks the
+     * run left un-parented are re-parented onto the enclosing node. Mirrors
+     * `useBlocks.insertMarkdown`, which nests a converted run the same way.
+     * @param run - the run node
+     * @param parent - id of the node the run is spliced into (undefined at root)
+     * @returns ids of the run's top-level blocks, in run order
+     */
+    const visitRun = (run, parent) => {
+        const rootIds = [];
+        for (const block of run.blocks) {
+            const { parent: incomingParent, id: incomingId, content: incomingContent, data, ...rest } = block;
+            const id = claimId(nonEmptyId(incomingId));
+            const incomingParentId = nonEmptyId(incomingParent);
+            const isRunRoot = incomingParentId === undefined;
+            const resolvedParent = isRunRoot ? parent : incomingParentId;
+            flat.push({
+                ...rest,
+                id,
+                data: data ?? {},
+                // `null`/`[]` content means "no children" — omitted, like a tree leaf.
+                ...(Array.isArray(incomingContent) && incomingContent.length > 0 ? { content: incomingContent } : {}),
+                ...(resolvedParent !== undefined ? { parent: resolvedParent } : {}),
+            });
+            if (isRunRoot) {
+                rootIds.push(id);
+            }
+        }
+        return rootIds;
+    };
+    // 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) => {
+        assertNotPreFlat(node);
+        const id = claimId(node.id);
         const childIds = [];
         const flatNode = {
             id,
@@ -476,7 +562,7 @@ function flattenTree(spec, options = {}) {
         };
         flat.push(flatNode);
         for (const child of node.children ?? []) {
-            childIds.push(visit(child, id));
+            childIds.push(...(isRunSpec(child) ? visitRun(child, id) : [visit(child, id)]));
         }
         // Only wire `content` when there are children — leaves stay clean.
         if (childIds.length > 0) {
@@ -486,7 +572,12 @@ function flattenTree(spec, options = {}) {
     };
     const roots = Array.isArray(spec) ? spec : [spec];
     for (const root of roots) {
-        visit(root, rootParent);
+        if (isRunSpec(root)) {
+            visitRun(root, rootParent);
+        }
+        else {
+            visit(root, rootParent);
+        }
     }
     return flat;
 }
@@ -674,6 +765,73 @@ const EMPTY_API = {
     clear: async () => undefined,
     isSyncingFromYjs: () => false,
 };
+/**
+ * Read the changed block's id out of a `block changed` payload, tolerating any
+ * shape that is not core's `{ event: { detail: { target } } }`.
+ * @param payload - whatever the dispatcher handed the listener
+ * @returns the target block id, or null when the payload does not carry one
+ */
+const changedBlockId = (payload) => {
+    const detail = payload
+        ?.event?.detail?.target?.id;
+    return typeof detail === 'string' ? detail : null;
+};
+/**
+ * Does a `block changed` event touch the subtree rooted at `withinId`?
+ *
+ * The reactivity filter behind `useBlocks(editor, { within })` in all three
+ * adapters. Without it every consumer of `useBlocks` re-renders on every change
+ * anywhere in the document — so a container block that only renders its own
+ * children still re-rendered on each keystroke in an unrelated block, and a page
+ * of N such containers turned one keystroke into N re-renders.
+ *
+ * INDETERMINATE READS AS "TOUCHED". The walk resolves ancestry through the LIVE
+ * tree, and a removal commonly emits after the block is already gone, so its
+ * parent chain cannot be read. Answering `false` there would leave a container
+ * rendering a child that no longer exists; answering `true` costs one extra
+ * render pass. Same for a payload with no readable target.
+ *
+ * Ancestry is walked UPWARD one `getById` at a time rather than snapshotted with
+ * `parentMap`: this runs on every emission — i.e. on every keystroke — so it must
+ * cost O(depth), not O(document).
+ * @param editor - the live Blok instance
+ * @param payload - the `block changed` payload
+ * @param withinId - id of the block whose subtree is the scope
+ * @returns true when the change is inside the scope (or cannot be placed)
+ */
+const changeTouchesSubtree = (editor, payload, withinId) => {
+    const targetId = changedBlockId(payload);
+    if (targetId === null) {
+        return true;
+    }
+    /** Ids already visited on this walk — one Set for the whole climb. */
+    const seen = new Set();
+    /**
+     * Walk one link up the parentId chain.
+     * @param id - the block to test, or null once the root is passed
+     * @returns true when `withinId` is `id` or one of its ancestors
+     */
+    const climbs = (id) => {
+        if (id === null) {
+            return false;
+        }
+        if (id === withinId) {
+            return true;
+        }
+        // A parentId cycle is a corrupt tree, not a scope hit — bail rather than spin.
+        if (seen.has(id)) {
+            return false;
+        }
+        seen.add(id);
+        const node = editor.blocks.getById(id);
+        // The target (or one of its ancestors) is no longer in the tree.
+        if (node === null || node === undefined) {
+            return true;
+        }
+        return climbs(node.parentId);
+    };
+    return climbs(targetId);
+};
 /**
  * Build the framework-agnostic, id/parentId-relative block-tree API over a LIVE
  * editor. Mutators route through the editor-level `blocks` API (core's
@@ -2327,6 +2485,23 @@ const DATA_ATTR = {
     /** Element excluded from mutation tracking */
     mutationFree: 'data-blok-mutation-free',
     // ============================================
+    // Keyboard Ownership
+    // ============================================
+    /** Marks a subtree whose keyboard belongs to the Tool that rendered it, not to
+     *  the editor. Blok's block-level keydown/keyup handling stands down entirely
+     *  for events originating inside it — Escape, Tab, the arrows, "/" and the
+     *  Enter/Backspace/Delete structural keys all reach the element untouched.
+     *
+     *  Blok already exempts native `<input>`/`<textarea>` from the STRUCTURAL keys
+     *  (Enter/Backspace/Delete and "/") because those are contenteditable-shaped
+     *  and would splice the document around a form field. Escape/Tab/arrows are
+     *  deliberately NOT exempt — they are how a user leaves a field. That default
+     *  is right for a one-line title input and wrong for a field with its own
+     *  keyboard semantics (Tab between sub-fields, Escape to cancel an edit, arrows
+     *  to walk a suggestion list), which is exactly what this attribute is for.
+     *  Public authoring hook. */
+    keyboardOwner: 'data-blok-keyboard-owner',
+    // ============================================
     // Navigation
     // ============================================
     /** Block has navigation focus */
@@ -2633,6 +2808,101 @@ const mountChildBlocks = (container, children) => {
     }
 };
 
+/**
+ * A fresh pair of ledgers for one container's child slot.
+ * @returns empty holder/content ledgers
+ */
+const createChildDecorationLedger = () => ({
+    holders: new Map(),
+    contents: new Map(),
+});
+/**
+ * The child's OWN content wrapper, or null when its DOM has not committed yet.
+ *
+ * The first `[data-blok-element-content]` in document order under a holder is
+ * always that block's own: a descendant block's wrapper necessarily sits INSIDE
+ * it. Not `firstElementChild` — block tunes wrap the content node, so it is not
+ * reliably a direct child (this is the same lookup core's own
+ * `refreshToolRootElement` uses).
+ * @param holder - the child block's holder
+ * @returns the content wrapper, or null
+ */
+const contentWrapperOf = (holder) => holder.querySelector(`[${DATA_ATTR.elementContent}]`);
+/**
+ * Apply one decoration pass and clear the previous pass's leftovers — including
+ * on a child that has since left the container, which would otherwise keep a
+ * dead index forever.
+ * @param ledger - what the last pass wrote (mutated)
+ * @param children - the container's model children, in model order
+ * @param decorate - the per-child decorator for the child HOLDERS, if any
+ * @param resolveTarget - which element of a child this pass writes to
+ */
+const applyPass = (ledger, children, decorate, resolveTarget) => {
+    const next = new Map();
+    children.forEach((child, index) => {
+        const target = resolveTarget(child.holder);
+        /**
+         * A portal-rendered child commits its DOM a frame after core inserts it, so
+         * its content wrapper can legitimately be missing on this pass. Skipping
+         * (rather than throwing) leaves the next pass to stamp it.
+         */
+        if (target === null) {
+            return;
+        }
+        const names = [];
+        for (const [name, value] of Object.entries(decorate?.(child, index) ?? {})) {
+            if (value === null || value === undefined) {
+                target.removeAttribute(name);
+                continue;
+            }
+            target.setAttribute(name, String(value));
+            names.push(name);
+        }
+        next.set(child.id, { target, names });
+    });
+    for (const [id, previous] of ledger) {
+        const current = next.get(id);
+        previous.names
+            .filter(name => current === undefined || !current.names.includes(name))
+            .forEach(name => previous.target.removeAttribute(name));
+    }
+    ledger.clear();
+    next.forEach((entry, id) => ledger.set(id, entry));
+};
+/**
+ * Decorate a container's children: named attributes on each child's HOLDER and,
+ * separately, on each child's `[data-blok-element-content]` wrapper.
+ *
+ * The single implementation behind the React, Vue and Angular per-child
+ * decoration channels, so the three cannot drift on which element a hook lands
+ * on or on when a dropped hook is cleaned up.
+ *
+ * BOTH levels exist because core's child-holder decoration law blesses both, and
+ * a container needs both: the holder is the child's outer box (rails, indices,
+ * hover states), while the content wrapper is where the child's own text box
+ * begins — which is what a numbered rail or a connector line has to align to.
+ * With only the holder reachable, a container had to encode core's wrapper chain
+ * in its own CSS (`[data-step] > [data-blok-element-content] > …`) and broke
+ * whenever that chain changed. Neither hook may introduce an element: holders
+ * stay DIRECT children of the slot because core's reparenting and caret
+ * sibling checks compare `holder.parentElement` by identity.
+ *
+ * Both are inert with respect to change tracking: core's mutation filter drops a
+ * holder- or content-targeted attribute record for the CHILD block (both are
+ * ancestors of the child's tool element, not descendants) and scores it
+ * mutation-free for the CONTAINER (whose own `data-blok-mutation-free` host is
+ * the nearest such ancestor).
+ * @param ledger - the slot's ledgers from {@link createChildDecorationLedger}
+ * @param children - the container's model children, in model order
+ * @param decorators - the authored per-child decorators
+ * @param decorators.childAttributes - written on each child's holder
+ * @param decorators.childContentAttributes - written on each child's content wrapper
+ */
+const applyChildDecoration = (ledger, children, decorators) => {
+    applyPass(ledger.holders, children, decorators.childAttributes, holder => holder);
+    applyPass(ledger.contents, children, decorators.childContentAttributes, contentWrapperOf);
+};
+
 /**
  * Fired when a CONTAINER block's child holders have been mounted into its
  * child slot — the moment the child DOM has settled and a caret set into a
@@ -3370,37 +3640,6 @@ const CREATION_ORIGINS = new Set([
     'api',
     'convert',
 ]);
-/**
- * Apply one pass of per-child holder attributes and clear the previous pass's
- * leftovers — including on a child that has since left the container, which
- * would otherwise keep a dead index forever.
- * @param stamped - the container's ledger of what the last pass wrote (mutated)
- * @param children - the container's model children, in model order
- * @param decorate - the authored per-child decorator, if any
- */
-const applyChildAttributes = (stamped, children, decorate) => {
-    const next = new Map();
-    children.forEach((child, index) => {
-        const names = [];
-        for (const [name, value] of Object.entries(decorate?.(child, index) ?? {})) {
-            if (value === null || value === undefined) {
-                child.holder.removeAttribute(name);
-                continue;
-            }
-            child.holder.setAttribute(name, String(value));
-            names.push(name);
-        }
-        next.set(child.id, { holder: child.holder, names });
-    });
-    for (const [id, previous] of stamped) {
-        const current = next.get(id);
-        previous.names
-            .filter(name => current === undefined || !current.names.includes(name))
-            .forEach(name => previous.holder.removeAttribute(name));
-    }
-    stamped.clear();
-    next.forEach((entry, id) => stamped.set(id, entry));
-};
 /**
  * Announce that a container's child holders have settled in its slot — the
  * signal a host waits on before putting the caret into a freshly inserted
@@ -3465,10 +3704,17 @@ function createAngularBlock(spec) {
         hostEl = null;
         /** Last host passed to ctx.mountChildren, re-mounted on each data change. */
         childHost = null;
-        /** Last per-child decorator passed to ctx.mountChildren; re-applied on each remount. */
+        /** Element the component handed to ctx.setToolbarAnchor, if any. */
+        anchorEl = null;
+        /**
+         * Last per-child decorators passed to ctx.mountChildren; BOTH re-applied on
+         * every remount (the author calls mountChildren once, the factory re-runs the
+         * mount on each data change).
+         */
         childAttributes;
+        childContentAttributes;
         /** What the last decoration pass wrote, so a dropped key is cleaned up. */
-        stampedChildren = new Map();
+        childLedger = createChildDecorationLedger();
         /** Why core built this instance — gates `onCreated`, handed to `onMounted`. */
         origin;
         /** True once the post-mount hooks fired; a repeated rendered() must not re-fire them. */
@@ -3500,6 +3746,7 @@ function createAngularBlock(spec) {
                 api: this.api,
                 readOnly: this.readOnlySig.asReadonly(),
                 mountChildren: this.mountChildren,
+                setToolbarAnchor: this.setToolbarAnchor,
             };
         }
         render() {
@@ -3579,12 +3826,30 @@ function createAngularBlock(spec) {
          * exactly what core's default positioning already assumes.
          */
         getToolbarAnchorElement() {
+            /**
+             * An element the component handed over wins — it is the exact node, chosen
+             * from inside the template. `isConnected` is the guard that matters: a
+             * component that re-renders its anchor can leave a detached node here, and
+             * positioning the toolbar against one silently parks it at 0,0.
+             */
+            const declared = this.anchorEl;
+            if (declared !== null && declared.isConnected) {
+                return declared;
+            }
             const host = this.hostEl;
             if (host === null || spec.getToolbarAnchorElement === undefined) {
                 return undefined;
             }
             return spec.getToolbarAnchorElement(host, this.blockApi) ?? undefined;
         }
+        /**
+         * `ctx.setToolbarAnchor`. A bound field so the context object handed through
+         * DI keeps a stable identity.
+         * @param element - the anchor element, or null to fall back to the spec hook
+         */
+        setToolbarAnchor = (element) => {
+            this.anchorEl = element;
+        };
         moved() {
             // No remount: core relocates the host element; the mounted view rides along
             // as its DOM children.
@@ -3605,9 +3870,10 @@ function createAngularBlock(spec) {
          * Container blocks: remember the host (and any per-child decorator) and
          * (re)mount the real child holders.
          */
-        mountChildren = (host, childAttributes) => {
+        mountChildren = (host, childAttributes, childContentAttributes) => {
             this.childHost = host;
             this.childAttributes = childAttributes;
+            this.childContentAttributes = childContentAttributes;
             host.setAttribute(DATA_ATTR.nestedBlocks, '');
             this.remountChildren();
         };
@@ -3617,7 +3883,10 @@ function createAngularBlock(spec) {
             }
             const children = this.blockApi.getChildren();
             mountChildBlocks(this.childHost, children);
-            applyChildAttributes(this.stampedChildren, children, this.childAttributes);
+            applyChildDecoration(this.childLedger, children, {
+                childAttributes: this.childAttributes,
+                childContentAttributes: this.childContentAttributes,
+            });
             emitChildrenMounted(this.api, this.blockApi.id, children);
         }
         /**
@@ -3719,8 +3988,16 @@ const BLOCK_CHANGED_EVENT = 'block changed';
  * `ed === sub.editor` makes it a no-op, so no double-subscription occurs.
  *
  * @param editor - a signal of the Blok instance, or null pre-ready
+ * @param options - reactivity options; see {@link InjectBlocksOptions.within} to
+ *   scope invalidation to one block's subtree
  */
-function injectBlocks(editor) {
+function injectBlocks(editor, options = {}) {
+    /**
+     * The scope, resolved per emission so a signal `within` takes effect with no
+     * re-subscription. A signal is a zero-arg function, which is how it is told
+     * apart from a plain id.
+     */
+    const resolveWithin = () => (typeof options.within === 'function' ? options.within() : options.within) ?? null;
     // Bumped on every `block changed`; the shared API's read methods touch it (via
     // the onRead seam) so template/computed reads stay reactive.
     const version = signal(0, /* @ts-ignore */
@@ -3758,7 +4035,11 @@ function injectBlocks(editor) {
             bound.set(EMPTY_API);
             return;
         }
-        const handler = () => {
+        const handler = (payload) => {
+            const within = resolveWithin();
+            if (within !== null && !changeTouchesSubtree(ed, payload, within)) {
+                return;
+            }
             version.update((v) => v + 1);
         };
         ed.on(BLOCK_CHANGED_EVENT, handler);