@bloklabs/angular 1.9.0 → 1.10.0

package/fesm2022/bloklabs-angular.mjs

@@ -765,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
@@ -2741,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
@@ -3478,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
@@ -3573,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. */
@@ -3608,6 +3746,7 @@ function createAngularBlock(spec) {
                 api: this.api,
                 readOnly: this.readOnlySig.asReadonly(),
                 mountChildren: this.mountChildren,
+                setToolbarAnchor: this.setToolbarAnchor,
             };
         }
         render() {
@@ -3687,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.
@@ -3713,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();
         };
@@ -3725,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);
         }
         /**
@@ -3827,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 */
@@ -3866,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);