@adobe-commerce/elsie 2.1.0-beta.3 → 2.1.0-beta.5

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @adobe-commerce/elsie
 
+## 2.1.0-beta.5
+
+### Patch Changes
+
+- 4cc7219: Fix a memory leak in `Slot`'s VNode cache (added to fix repeated
+  `insertBefore` crashes from replay churn): entries were never pruned, so a
+  `slot` callback that keeps calling `replaceWith`/`appendChild`/`prependChild`
+  with newly constructed elements over time (rather than mutating one element in
+  place) would pin every historical element in memory for the Slot's whole
+  lifetime. Entries are now evicted via the grafted element's `ref` callback
+  firing with `null`, which Preact does precisely when that VNode is detached
+  (superseded by a different element, or the Slot unmounting).
+
+  See `docs/slot-dom-graft-race.md` for the full trace, including a
+  pre-existing, unrelated gap this surfaced: calling `replaceWith` a second time
+  with a different element doesn't remove the first one.
+
+- ba3bbe7: Fix a recurring `insertBefore` crash in `Slot` when content grafted
+  via `replaceWith`/`appendChild`/`prependChild` is re-applied on unrelated
+  re-renders. `Slot` replays its registered methods on every render pass (by
+  design, so `onRender`/`onChange` can react to fresh state), but the grafted
+  content's wrapper VNode was rebuilt from scratch on every replay, handing
+  Preact a brand new `ref` closure for a DOM node that was already grafted. That
+  churn corrupted Preact's internal DOM bookkeeping for the grafted subtree over
+  repeated re-renders, especially in components with ongoing state changes. The
+  wrapper VNode is now cached per element, so repeated replays reuse the same
+  VNode instance and Preact's diff bails out instead of re-touching the subtree.
+
+  See `docs/slot-dom-graft-race.md` for the full trace, including why an earlier
+  attempt at this fix (making `replaceWith` a no-op after its first run) was
+  wrong.
+
+## 2.1.0-beta.4
+
+### Patch Changes
+
+- 8fc53e5: Fix `Slot` silently dropping
+  `replaceWith`/`appendChild`/`prependChild`/
+  `appendSibling`/`prependSibling`/`remove` calls made from a `slot` callback
+  that doesn't `return`/`await` its own async work (e.g. a non-`async` callback
+  that calls an `async` helper as a bare statement). Previously, nothing was
+  left to trigger the render that would have picked up the queued method once
+  the slot's normal init-triggered render pass had already completed. `Slot` now
+  detects that case and flushes the pending update itself. Existing callers that
+  already `return`/`await` their `slot` callback are unaffected.
+
+  See `docs/slot-dom-graft-race.md` for the full trace.
+
 ## 2.1.0-beta.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe-commerce/elsie",
-  "version": "2.1.0-beta.3",
+  "version": "2.1.0-beta.5",
   "license": "SEE LICENSE IN LICENSE.md",
   "description": "Domain Package SDK",
   "engines": {

package/src/lib/slot.tsx

@@ -146,9 +146,21 @@ export function useSlot<K, V extends HTMLElement>(
     });
   };
 
+  const handleLifeCycleRenderRef = useRef<() => Promise<void>>();
+
   const _registerMethod = useCallback((cb: Function) => {
     if (typeof cb === 'function') {
       methodsRef.current.push(cb);
+
+      // If the slot already finished its normal init-triggered render pass
+      // (status is back to 'ready'), nothing else will flush this method.
+      // This happens when an async `slot` callback doesn't `return`/`await`
+      // its own async work before calling replaceWith/appendChild/etc. --
+      // `handleLifeCycleInit` moves on before this method gets registered.
+      // Flush it ourselves rather than silently dropping it.
+      if (status.current === 'ready') {
+        handleLifeCycleRenderRef.current?.();
+      }
     } else {
       console.warn('Skipped: Invalid _registerMethod', cb);
     }
@@ -157,20 +169,59 @@ export function useSlot<K, V extends HTMLElement>(
   // @ts-ignore
   context._registerMethod = _registerMethod;
 
+  // `onRender`-style registered methods are replayed on every
+  // `handleLifeCycleRender` pass (see `_registerMethod`/`methodsRef` above),
+  // and `handleLifeCycleRender` always resets `children` to the fallback
+  // before replaying them -- so `replaceWith`/`appendChild`/`prependChild`
+  // must genuinely re-apply their VNode on every replay, not just once.
+  // Without caching, each replay would call `createElement` fresh, handing
+  // Preact a brand new VNode (and new `ref` identity) for content that's
+  // already grafted, forcing it to detach/reattach the `ref` for no reason.
+  // Caching per `elem` means repeat calls return the *same* VNode object;
+  // Preact's diff treats `oldVNode === newVNode` as an explicit "unchanged,
+  // skip" signal, so it never re-touches the grafted subtree. See
+  // docs/slot-dom-graft-race.md.
+  const htmlElementVNodeCache = useMemo(
+    () => new Map<HTMLElement, VNode<any>>(),
+    // `contentTag` isn't read by the factory -- it's a deliberate cache-bust
+    // key, so a `contentTag` change starts a fresh cache instead of handing
+    // out VNodes built for the old wrapper tag.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [contentTag],
+  );
+
   const _htmlElementToVNode = useCallback(
     (elem: HTMLElement) => {
-      return createElement(
+      const cached = htmlElementVNodeCache.get(elem);
+      if (cached) return cached;
+
+      const vnode = createElement(
         contentTag,
         {
           'data-slot-html-element': elem.tagName.toLowerCase(),
           ref: (refElem: HTMLElement | null): void => {
-            refElem?.appendChild(elem);
+            if (refElem) {
+              refElem.appendChild(elem);
+              return;
+            }
+
+            // Preact calls `ref` with `null` when this specific VNode is
+            // detached -- either superseded by a different element at the
+            // same position (a later replaceWith/appendChild/prependChild
+            // call) or because the Slot unmounted entirely. Either way,
+            // `elem` is no longer part of the tree, so drop it from the
+            // cache now instead of holding onto it (and the DOM node it
+            // wraps) for the Slot's remaining lifetime.
+            htmlElementVNodeCache.delete(elem);
           },
         },
         null,
       );
+
+      htmlElementVNodeCache.set(elem, vnode);
+      return vnode;
     },
-    [contentTag],
+    [contentTag, htmlElementVNodeCache],
   );
 
   // @ts-ignore
@@ -337,6 +388,8 @@ export function useSlot<K, V extends HTMLElement>(
     status.current = 'ready';
   }, [children, context, name, props, render, state]);
 
+  handleLifeCycleRenderRef.current = handleLifeCycleRender;
+
   // Initialization
   const handleLifeCycleInit = useCallback(async () => {
     if (!callback) return;