@lwc/synthetic-shadow 6.2.0 → 6.2.1

package/dist/faux-shadow/events.d.ts

@@ -8,6 +8,7 @@ export declare const eventToContextMap: WeakMap<Event, EventListenerContext>;
  * Events dispatched on shadow roots actually end up being dispatched on their hosts. This means that the event.target
  * property of events dispatched on shadow roots always resolve to their host. This function understands this
  * abstraction and properly returns a reference to the shadow root when appropriate.
+ * @param event
  */
 export declare function getActualTarget(event: Event): EventTarget;
 export declare function addCustomElementEventListener(this: Element, type: string, listener: unknown, _options?: boolean | AddEventListenerOptions): void;

package/dist/faux-shadow/no-patch-utils.d.ts

@@ -1,5 +1,7 @@
 /**
  * This methods filters out elements that are not in the same shadow root of context.
  * It does not enforce shadow dom semantics if $context is not managed by LWC
+ * @param context
+ * @param unfilteredNodes
  */
 export declare function getNonPatchedFilteredArrayOfNodes<T extends Node>(context: Element, unfilteredNodes: Array<T>): Array<T>;

package/dist/faux-shadow/node.d.ts

@@ -3,6 +3,7 @@
  * based on the light-dom slotting mechanism. This applies to synthetic slot elements
  * and elements with shadow dom attached to them. It doesn't apply to native slot elements
  * because we don't want to patch the children getters for those elements.
+ * @param node
  */
 export declare function hasMountedChildren(node: Node): boolean;
 export declare const getInternalChildNodes: (node: Node) => NodeListOf<ChildNode>;

package/dist/index.cjs.js

@@ -16,21 +16,40 @@ if (!lwcRuntimeFlags.ENABLE_FORCE_SHADOW_MIGRATE_MODE) {
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
  */
+/**
+ *
+ * @param value
+ * @param msg
+ */
 function invariant(value, msg) {
     if (!value) {
         throw new Error(`Invariant Violation: ${msg}`);
     }
 }
+/**
+ *
+ * @param value
+ * @param msg
+ */
 function isTrue$1(value, msg) {
     if (!value) {
         throw new Error(`Assert Violation: ${msg}`);
     }
 }
+/**
+ *
+ * @param value
+ * @param msg
+ */
 function isFalse$1(value, msg) {
     if (value) {
         throw new Error(`Assert Violation: ${msg}`);
     }
 }
+/**
+ *
+ * @param msg
+ */
 function fail(msg) {
     throw new Error(msg);
 }
@@ -44,50 +63,132 @@ var assert = /*#__PURE__*/Object.freeze({
 });
 
 /*
- * Copyright (c) 2018, salesforce.com, inc.
+ * Copyright (c) 2024, Salesforce, Inc.
  * All rights reserved.
  * SPDX-License-Identifier: MIT
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
  */
-const { assign, create, defineProperties, defineProperty, entries, freeze, getOwnPropertyDescriptor, getOwnPropertyDescriptors, getOwnPropertyNames, getPrototypeOf, hasOwnProperty, isFrozen, keys, seal, setPrototypeOf, } = Object;
+const { 
+/** Detached {@linkcode Object.assign}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign MDN Reference}. */
+assign, 
+/** Detached {@linkcode Object.create}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/create MDN Reference}. */
+create, 
+/** Detached {@linkcode Object.defineProperties}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperties MDN Reference}. */
+defineProperties, 
+/** Detached {@linkcode Object.defineProperty}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty MDN Reference}. */
+defineProperty, 
+/** Detached {@linkcode Object.entries}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries MDN Reference}. */
+entries, 
+/** Detached {@linkcode Object.freeze}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze MDN Reference}. */
+freeze, 
+/** Detached {@linkcode Object.getOwnPropertyDescriptor}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor MDN Reference}. */
+getOwnPropertyDescriptor, 
+/** Detached {@linkcode Object.getOwnPropertyDescriptors}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptors MDN Reference}. */
+getOwnPropertyDescriptors, 
+/** Detached {@linkcode Object.getOwnPropertyNames}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyNames MDN Reference}. */
+getOwnPropertyNames, 
+/** Detached {@linkcode Object.getPrototypeOf}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getPrototypeOf MDN Reference}. */
+getPrototypeOf, 
+/** Detached {@linkcode Object.hasOwnProperty}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwnProperty MDN Reference}. */
+hasOwnProperty, 
+/** Detached {@linkcode Object.isFrozen}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/isFrozen MDN Reference}. */
+isFrozen, 
+/** Detached {@linkcode Object.keys}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys MDN Reference}. */
+keys, 
+/** Detached {@linkcode Object.seal}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/seal MDN Reference}. */
+seal, 
+/** Detached {@linkcode Object.setPrototypeOf}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/setPrototypeOf MDN Reference}. */
+setPrototypeOf, } = Object;
+/** Detached {@linkcode Array.isArray}; see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray MDN Reference}. */
 const { isArray } = Array;
-const { concat: ArrayConcat, copyWithin: ArrayCopyWithin, every: ArrayEvery, fill: ArrayFill, filter: ArrayFilter, find: ArrayFind, findIndex: ArrayFindIndex, includes: ArrayIncludes, indexOf: ArrayIndexOf, join: ArrayJoin, map: ArrayMap, pop: ArrayPop, push: ArrayPush, reduce: ArrayReduce, reverse: ArrayReverse, shift: ArrayShift, slice: ArraySlice, some: ArraySome, sort: ArraySort, splice: ArraySplice, unshift: ArrayUnshift, forEach, } = Array.prototype;
+// For some reason, JSDoc don't get picked up for multiple renamed destructured constants (even
+// though it works fine for one, e.g. isArray), so comments for these are added to the export
+// statement, rather than this declaration.
+const { concat: ArrayConcat, copyWithin: ArrayCopyWithin, every: ArrayEvery, fill: ArrayFill, filter: ArrayFilter, find: ArrayFind, findIndex: ArrayFindIndex, includes: ArrayIncludes, indexOf: ArrayIndexOf, join: ArrayJoin, map: ArrayMap, pop: ArrayPop, push: ArrayPush, reduce: ArrayReduce, reverse: ArrayReverse, shift: ArrayShift, slice: ArraySlice, some: ArraySome, sort: ArraySort, splice: ArraySplice, unshift: ArrayUnshift, forEach, // Weird anomaly!
+ } = Array.prototype;
+/**
+ * Determines whether the argument is `undefined`.
+ * @param obj Value to test
+ * @returns `true` if the value is `undefined`.
+ */
 function isUndefined(obj) {
     return obj === undefined;
 }
+/**
+ * Determines whether the argument is `null`.
+ * @param obj Value to test
+ * @returns `true` if the value is `null`.
+ */
 function isNull(obj) {
     return obj === null;
 }
+/**
+ * Determines whether the argument is `true`.
+ * @param obj Value to test
+ * @returns `true` if the value is `true`.
+ */
 function isTrue(obj) {
     return obj === true;
 }
+/**
+ * Determines whether the argument is `false`.
+ * @param obj Value to test
+ * @returns `true` if the value is `false`.
+ */
 function isFalse(obj) {
     return obj === false;
 }
+/**
+ * Determines whether the argument is a function.
+ * @param obj Value to test
+ * @returns `true` if the value is a function.
+ */
 // Replacing `Function` with a narrower type that works for all our use cases is tricky...
 // eslint-disable-next-line @typescript-eslint/ban-types
 function isFunction(obj) {
     return typeof obj === 'function';
 }
+/**
+ * Determines whether the argument is an object or null.
+ * @param obj Value to test
+ * @returns `true` if the value is an object or null.
+ */
 function isObject(obj) {
     return typeof obj === 'object';
 }
 const OtS = {}.toString;
+/**
+ * Converts the argument to a string, safely accounting for objects with "null" prototype.
+ * Note that `toString(null)` returns `"[object Null]"` rather than `"null"`.
+ * @param obj Value to convert to a string.
+ * @returns String representation of the value.
+ */
 function toString(obj) {
-    if (obj && obj.toString) {
+    if (obj?.toString) {
         // Arrays might hold objects with "null" prototype So using
         // Array.prototype.toString directly will cause an error Iterate through
         // all the items and handle individually.
         if (isArray(obj)) {
+            // This behavior is slightly different from Array#toString:
+            // 1. Array#toString calls `this.join`, rather than Array#join
+            // Ex: arr = []; arr.join = () => 1; arr.toString() === 1; toString(arr) === ''
+            // 2. Array#toString delegates to Object#toString if `this.join` is not a function
+            // Ex: arr = []; arr.join = 'no'; arr.toString() === '[object Array]; toString(arr) = ''
+            // 3. Array#toString converts null/undefined to ''
+            // Ex: arr = [null, undefined]; arr.toString() === ','; toString(arr) === '[object Null],undefined'
+            // 4. Array#toString converts recursive references to arrays to ''
+            // Ex: arr = [1]; arr.push(arr, 2); arr.toString() === '1,,2'; toString(arr) throws
+            // Ref: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString
             return ArrayJoin.call(ArrayMap.call(obj, toString), ',');
         }
         return obj.toString();
     }
     else if (typeof obj === 'object') {
+        // This catches null and returns "[object Null]". Weird, but kept for backwards compatibility.
         return OtS.call(obj);
     }
     else {
-        return obj + '';
+        return String(obj);
     }
 }
 
@@ -109,7 +210,7 @@ const KEY__LEGACY_SHADOW_TOKEN_PRIVATE = '$$LegacyShadowTokenKey$$';
 const KEY__SYNTHETIC_MODE = '$$lwc-synthetic-mode';
 const KEY__NATIVE_GET_ELEMENT_BY_ID = '$nativeGetElementById$';
 const KEY__NATIVE_QUERY_SELECTOR_ALL = '$nativeQuerySelectorAll$';
-/** version: 6.2.0 */
+/** version: 6.2.1 */
 
 /**
  * Copyright (c) 2024 Salesforce, Inc.
@@ -117,7 +218,7 @@ const KEY__NATIVE_QUERY_SELECTOR_ALL = '$nativeQuerySelectorAll$';
 if (!globalThis.lwcRuntimeFlags) {
     Object.defineProperty(globalThis, 'lwcRuntimeFlags', { value: create(null) });
 }
-/** version: 6.2.0 */
+/** version: 6.2.1 */
 
 /*
  * Copyright (c) 2018, salesforce.com, inc.
@@ -386,6 +487,7 @@ function getNodeKey(node) {
  * This function does not traverse up for performance reasons, but is sufficient for most use
  * cases. If we need to traverse up and verify those nodes that don't have owner key, use
  * isNodeDeepShadowed instead.
+ * @param node
  */
 function isNodeShadowed(node) {
     return !isUndefined(getNodeOwnerKey(node));
@@ -442,7 +544,7 @@ function isNodeSlotted(host, node) {
             // have different owner key. for slotted elements, this is possible
             // if the parent happens to be a slot.
             if (isSlotElement(parent)) {
-                /**
+                /*
                  * the slot parent might be allocated inside another slot, think of:
                  * <x-root> (<--- root element)
                  *    <x-parent> (<--- own by x-root)
@@ -1066,6 +1168,7 @@ function createStaticHTMLCollection(items) {
  * based on the light-dom slotting mechanism. This applies to synthetic slot elements
  * and elements with shadow dom attached to them. It doesn't apply to native slot elements
  * because we don't want to patch the children getters for those elements.
+ * @param node
  */
 function hasMountedChildren(node) {
     return isSyntheticSlotElement(node) || isSyntheticShadowHost(node);
@@ -1200,10 +1303,10 @@ const getDocumentOrRootNode = !isUndefined(nativeGetRootNode)
  * Get the shadow root
  * getNodeOwner() returns the host element that owns the given node
  * Note: getNodeOwner() returns null when running in native-shadow mode.
- *  Fallback to using the native getRootNode() to discover the root node.
- *  This is because, it is not possible to inspect the node and decide if it is part
- *  of a native shadow or the synthetic shadow.
- * @param {Node} node
+ * Fallback to using the native getRootNode() to discover the root node.
+ * This is because, it is not possible to inspect the node and decide if it is part
+ * of a native shadow or the synthetic shadow.
+ * @param node
  */
 function getNearestRoot(node) {
     const ownerNode = getNodeOwner(node);
@@ -1221,17 +1324,17 @@ function getNearestRoot(node) {
  *
  * If looking for a shadow root of a node by calling `node.getRootNode({composed: false})` or `node.getRootNode()`,
  *
- *  1. Try to identify the host element that owns the give node.
- *     i. Identify the shadow tree that the node belongs to
- *     ii. If the node belongs to a shadow tree created by engine, return the shadowRoot of the host element that owns the shadow tree
- *  2. The host identification logic returns null in two cases:
- *     i. The node does not belong to a shadow tree created by engine
- *     ii. The engine is running in native shadow dom mode
- *     If so, use the original Node.prototype.getRootNode to fetch the root node(or manually climb up the dom tree where getRootNode() is unsupported)
+ * 1. Try to identify the host element that owns the give node.
+ * i. Identify the shadow tree that the node belongs to
+ * ii. If the node belongs to a shadow tree created by engine, return the shadowRoot of the host element that owns the shadow tree
+ * 2. The host identification logic returns null in two cases:
+ * i. The node does not belong to a shadow tree created by engine
+ * ii. The engine is running in native shadow dom mode
+ * If so, use the original Node.prototype.getRootNode to fetch the root node(or manually climb up the dom tree where getRootNode() is unsupported)
  *
  * _Spec_: https://dom.spec.whatwg.org/#dom-node-getrootnode
- *
- **/
+ * @param options
+ */
 function getRootNodePatched(options) {
     const composed = isUndefined(options) ? false : !!options.composed;
     return isTrue(composed) ? getDocumentOrRootNode.call(this, options) : getNearestRoot(this);
@@ -1483,6 +1586,7 @@ function getEventMap(elm) {
  * Events dispatched on shadow roots actually end up being dispatched on their hosts. This means that the event.target
  * property of events dispatched on shadow roots always resolve to their host. This function understands this
  * abstraction and properly returns a reference to the shadow root when appropriate.
+ * @param event
  */
 function getActualTarget(event) {
     return eventToShadowRootMap.get(event) ?? eventTargetGetter.call(event);
@@ -2290,7 +2394,7 @@ function retarget(refNode, path) {
             rootIdx = refNodePath.indexOf(root);
             lastRoot = root;
         }
-        if (!isSyntheticShadowRoot(root) || (!isUndefined(rootIdx) && rootIdx > -1)) {
+        if (!isUndefined(rootIdx) && rootIdx > -1) {
             return ancestor;
         }
     }
@@ -2536,7 +2640,7 @@ function setNodeObservers(node, observers) {
 }
 /**
  * Retarget the mutation record's target value to its shadowRoot
- * @param {MutationRecord} originalRecord
+ * @param originalRecord
  */
 function retargetMutationRecord(originalRecord) {
     const { addedNodes, removedNodes, target, type } = originalRecord;
@@ -2576,8 +2680,8 @@ function retargetMutationRecord(originalRecord) {
 /**
  * Utility to identify if a target node is being observed by the given observer
  * Start at the current node, if the observer is registered to observe the current node, the mutation qualifies
- * @param {MutationObserver} observer
- * @param {Node} target
+ * @param observer
+ * @param target
  */
 function isQualifiedObserver(observer, target) {
     let parentNode = target;
@@ -2598,8 +2702,8 @@ function isQualifiedObserver(observer, target) {
  * The key logic here is to determine if a given observer has been registered to observe any nodes
  * between the target node of a mutation record to the target's root node.
  * This function also retargets records when mutations occur directly under the shadow root
- * @param {MutationRecords[]} mutations
- * @param {MutationObserver} observer
+ * @param mutations
+ * @param observer
  */
 function filterMutationRecords(mutations, observer) {
     const result = [];
@@ -2681,7 +2785,7 @@ function getWrappedCallback(callback) {
  * Patched MutationObserver constructor.
  * 1. Wrap the callback to filter out MutationRecords based on dom ownership
  * 2. Add a property field to track all observed targets of the observer instance
- * @param {MutationCallback} callback
+ * @param callback
  */
 function PatchedMutationObserver(callback) {
     const wrappedCallback = getWrappedCallback(callback);
@@ -2708,8 +2812,8 @@ function patchedDisconnect() {
 /**
  * A single mutation observer can observe multiple nodes(target).
  * Maintain a list of all targets that the observer chooses to observe
- * @param {Node} target
- * @param {Object} options
+ * @param target
+ * @param options
  */
 function patchedObserve(target, options) {
     let targetObservers = getNodeObservers(target);
@@ -3047,9 +3151,8 @@ function assignedSlotGetterPatched() {
     }
     /**
      * The node is assigned to a slot if:
-     *  - it has a parent and its parent is a slot element
-     *  - and if the slot owner key is different than the node owner key.
-     *
+     * - it has a parent and its parent is a slot element
+     * - and if the slot owner key is different than the node owner key.
      * When the slot and the slotted node are 2 different shadow trees, the owner keys will be
      * different. When the slot is in a shadow tree and the slotted content is a light DOM node,
      * the light DOM node doesn't have an owner key and therefor the slot owner key will be
@@ -3164,6 +3267,8 @@ defineProperties(Text.prototype, {
 /**
  * This methods filters out elements that are not in the same shadow root of context.
  * It does not enforce shadow dom semantics if $context is not managed by LWC
+ * @param context
+ * @param unfilteredNodes
  */
 function getNonPatchedFilteredArrayOfNodes(context, unfilteredNodes) {
     let filtered;
@@ -3872,6 +3977,7 @@ function tabIndexGetterPatched() {
 }
 /**
  * This method only applies to elements with a shadow attached to them
+ * @param value
  */
 function tabIndexSetterPatched(value) {
     // This tabIndex setter might be confusing unless it is understood that HTML
@@ -4052,13 +4158,10 @@ function setShadowToken(node, shadowToken) {
 }
 /**
  * Patching Element.prototype.$shadowToken$ to mark elements a portal:
- *
- *  - we use a property to allow engines to set a custom attribute that should be
- *    placed into the element to sandbox the css rules defined for the template.
- *
- *  - this custom attribute must be unique.
- *
- **/
+ * - we use a property to allow engines to set a custom attribute that should be
+ * placed into the element to sandbox the css rules defined for the template.
+ * - this custom attribute must be unique.
+ */
 defineProperty(Element.prototype, KEY__SHADOW_TOKEN, {
     set(shadowToken) {
         const oldShadowToken = this[KEY__SHADOW_TOKEN_PRIVATE];
@@ -4113,7 +4216,7 @@ function setLegacyShadowToken(node, shadowToken) {
 /**
  * Patching Element.prototype.$legacyShadowToken$ to mark elements a portal:
  * Same as $shadowToken$ but for legacy CSS scope tokens.
- **/
+ */
 defineProperty(Element.prototype, KEY__LEGACY_SHADOW_TOKEN, {
     set(shadowToken) {
         const oldShadowToken = this[KEY__LEGACY_SHADOW_TOKEN_PRIVATE];
@@ -4227,18 +4330,14 @@ function markElementAsPortal(elm) {
 }
 /**
  * Patching Element.prototype.$domManual$ to mark elements as portal:
- *
- *  - we use a property to allow engines to signal that a particular element in
- *    a shadow supports manual insertion of child nodes.
- *
- *  - this signal comes as a boolean value, and we use it to install the MO instance
- *    onto the element, to propagate the $ownerKey$ and $shadowToken$ to all new
- *    child nodes.
- *
- *  - at the moment, there is no way to undo this operation, once the element is
- *    marked as $domManual$, setting it to false does nothing.
- *
- **/
+ * - we use a property to allow engines to signal that a particular element in
+ * a shadow supports manual insertion of child nodes.
+ * - this signal comes as a boolean value, and we use it to install the MO instance
+ * onto the element, to propagate the $ownerKey$ and $shadowToken$ to all new
+ * child nodes.
+ * - at the moment, there is no way to undo this operation, once the element is
+ * marked as $domManual$, setting it to false does nothing.
+ */
 // TODO [#1306]: rename this to $observerConnection$
 defineProperty(Element.prototype, '$domManual$', {
     set(v) {
@@ -4252,6 +4351,6 @@ defineProperty(Element.prototype, '$domManual$', {
     },
     configurable: true,
 });
-/** version: 6.2.0 */
+/** version: 6.2.1 */
 }
 //# sourceMappingURL=index.cjs.js.map