mount-observer 0.1.14 → 0.1.16

package/handlers/emitEvents.js

@@ -0,0 +1,187 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitMountedElementEvents = emitMountedElementEvents;
+/**
+ * Emits events from a mounted element based on the mountedElemEmits configuration.
+ * This module is dynamically loaded only when mountedElemEmits is configured.
+ */
+function emitMountedElementEvents(element, MountConfig, processedEventsForElement) {
+    return __awaiter(this, void 0, void 0, function () {
+        var configs, _i, configs_1, config;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    configs = Array.isArray(MountConfig.mountedElemEmits)
+                        ? MountConfig.mountedElemEmits
+                        : [MountConfig.mountedElemEmits];
+                    _i = 0, configs_1 = configs;
+                    _a.label = 1;
+                case 1:
+                    if (!(_i < configs_1.length)) return [3 /*break*/, 4];
+                    config = configs_1[_i];
+                    return [4 /*yield*/, emitSingleEvent(element, MountConfig, config, processedEventsForElement)];
+                case 2:
+                    _a.sent();
+                    _a.label = 3;
+                case 3:
+                    _i++;
+                    return [3 /*break*/, 1];
+                case 4: return [2 /*return*/];
+            }
+        });
+    });
+}
+function emitSingleEvent(element, MountConfig, config, processedEventsForElement) {
+    return __awaiter(this, void 0, void 0, function () {
+        var eventId, processedEvents, EventCtor, processedArgs, event, options, assignGingerly, processedProps;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    // Check if this event should only fire once per element
+                    if (config.oncePerMountedElement) {
+                        eventId = getEventId(config);
+                        processedEvents = processedEventsForElement.get(element);
+                        if (!processedEvents) {
+                            processedEvents = new Set();
+                            processedEventsForElement.set(element, processedEvents);
+                        }
+                        if (processedEvents.has(eventId)) {
+                            return [2 /*return*/]; // Already emitted for this element
+                        }
+                        processedEvents.add(eventId);
+                    }
+                    EventCtor = resolveEventConstructor(config.event);
+                    processedArgs = config.args !== undefined
+                        ? processMagicStrings(config.args, element, MountConfig)
+                        : undefined;
+                    if (processedArgs === undefined) {
+                        event = new EventCtor();
+                    }
+                    else if (Array.isArray(processedArgs)) {
+                        // For array args, ensure bubbles is set if second arg is an options object
+                        if (processedArgs.length === 2 && typeof processedArgs[0] === 'string' && typeof processedArgs[1] === 'object' && processedArgs[1] !== null) {
+                            options = __assign({ bubbles: true }, processedArgs[1]);
+                            event = new EventCtor(processedArgs[0], options);
+                        }
+                        else {
+                            event = new (EventCtor.bind.apply(EventCtor, __spreadArray([void 0], processedArgs, false)))();
+                        }
+                    }
+                    else {
+                        // Single arg - if it's a string (event name), add bubbles: true by default
+                        if (typeof processedArgs === 'string') {
+                            event = new EventCtor(processedArgs, { bubbles: true });
+                        }
+                        else {
+                            event = new EventCtor(processedArgs);
+                        }
+                    }
+                    if (!config.eventProps) return [3 /*break*/, 2];
+                    return [4 /*yield*/, Promise.resolve().then(function () { return require('assign-gingerly/assignGingerly.js'); })];
+                case 1:
+                    assignGingerly = (_a.sent()).assignGingerly;
+                    processedProps = processMagicStrings(config.eventProps, element, MountConfig);
+                    assignGingerly(event, processedProps);
+                    _a.label = 2;
+                case 2:
+                    // Dispatch the event from the mounted element
+                    element.dispatchEvent(event);
+                    return [2 /*return*/];
+            }
+        });
+    });
+}
+function resolveEventConstructor(event) {
+    if (typeof event === 'string') {
+        var EventCtor = globalThis[event];
+        if (!EventCtor || typeof EventCtor !== 'function') {
+            throw new Error("Event constructor \"".concat(event, "\" not found in globalThis"));
+        }
+        return EventCtor;
+    }
+    return event;
+}
+function getEventId(config) {
+    var eventName = typeof config.event === 'string' ? config.event : config.event.name;
+    var argsStr = JSON.stringify(config.args || '');
+    return "".concat(eventName, ":").concat(argsStr);
+}
+function processMagicStrings(value, element, MountConfig) {
+    if (typeof value === 'string') {
+        if (value === '{{mountedElement}}') {
+            return element;
+        }
+        if (value === '{{MountConfig}}') {
+            return MountConfig;
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(function (item) { return processMagicStrings(item, element, MountConfig); });
+    }
+    if (value && typeof value === 'object') {
+        var processed = {};
+        for (var _i = 0, _a = Object.entries(value); _i < _a.length; _i++) {
+            var _b = _a[_i], key = _b[0], val = _b[1];
+            processed[key] = processMagicStrings(val, element, MountConfig);
+        }
+        return processed;
+    }
+    return value;
+}

package/handlers/getRegistryRoot.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRegistryRoot = getRegistryRoot;
+/**
+ * Recursively traverses up the DOM tree to find the highest node
+ * that shares the same customElementRegistry as the passed in node.
+ * This is useful for scoped custom element registries where we want to observe within the correct scope.
+ *
+ * @param node - The starting node to check
+ * @returns The highest node with matching customElementRegistry, or null if node is invalid
+ */
+function getRegistryRoot(node) {
+    if (!node) {
+        return null;
+    }
+    // Quick check: if root node has the same registry, return it immediately
+    var rn = node.getRootNode();
+    var customElementRegistry = node.customElementRegistry;
+    if (rn.customElementRegistry === customElementRegistry) {
+        return rn;
+    }
+    var startRegistry = node.customElementRegistry;
+    var currentNode = node;
+    var highestMatch = node;
+    while (currentNode) {
+        // Check if current node has matching customElementRegistry
+        if (currentNode.customElementRegistry === startRegistry) {
+            highestMatch = currentNode;
+        }
+        // Try to get parent element first
+        var parent_1 = currentNode.parentElement;
+        if (parent_1) {
+            currentNode = parent_1;
+            continue;
+        }
+        // If no parent element, check for rootNode (shadow root case)
+        var root = currentNode.getRootNode();
+        if (root && root !== currentNode) {
+            // If it's a shadow root (not document), return it
+            if (root !== document) {
+                return root;
+            }
+            // If it's the document, check if it has the same registry
+            if (root.customElementRegistry === startRegistry) {
+                return root;
+            }
+        }
+        // Reached the top
+        break;
+    }
+    return highestMatch;
+}

package/handlers/loadImports.js

@@ -0,0 +1,129 @@
+"use strict";
+// Dynamic import loading utilities
+// Only loaded when MountConfig.import is specified
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadImports = loadImports;
+var arr_js_1 = require("./arr.js");
+function loadImports(imports) {
+    return __awaiter(this, void 0, void 0, function () {
+        var importArray, promises;
+        return __generator(this, function (_a) {
+            importArray = (0, arr_js_1.arr)(imports);
+            promises = importArray.map(function (imp) { return loadSingleImport(imp); });
+            return [2 /*return*/, Promise.all(promises)];
+        });
+    });
+}
+function loadSingleImport(imp) {
+    return __awaiter(this, void 0, void 0, function () {
+        var url, type;
+        var _a;
+        return __generator(this, function (_b) {
+            type = 'js';
+            if (typeof imp === 'string') {
+                url = imp;
+            }
+            else if (Array.isArray(imp)) {
+                url = imp[0];
+                type = ((_a = imp[1]) === null || _a === void 0 ? void 0 : _a.type) || 'js';
+            }
+            else {
+                url = imp.url;
+                type = imp.type || 'js';
+            }
+            switch (type) {
+                case 'css':
+                    return [2 /*return*/, loadCSS(url)];
+                case 'json':
+                    return [2 /*return*/, loadJSON(url)];
+                case 'html':
+                    return [2 /*return*/, loadHTML(url)];
+                default:
+                    return [2 /*return*/, Promise.resolve("".concat(url)).then(function (s) { return require(s); })];
+            }
+            return [2 /*return*/];
+        });
+    });
+}
+function loadCSS(url) {
+    return __awaiter(this, void 0, void 0, function () {
+        var response, text, sheet;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, fetch(url)];
+                case 1:
+                    response = _a.sent();
+                    return [4 /*yield*/, response.text()];
+                case 2:
+                    text = _a.sent();
+                    sheet = new CSSStyleSheet();
+                    return [4 /*yield*/, sheet.replace(text)];
+                case 3:
+                    _a.sent();
+                    return [2 /*return*/, sheet];
+            }
+        });
+    });
+}
+function loadJSON(url) {
+    return __awaiter(this, void 0, void 0, function () {
+        var response;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, fetch(url)];
+                case 1:
+                    response = _a.sent();
+                    return [2 /*return*/, response.json()];
+            }
+        });
+    });
+}
+function loadHTML(url) {
+    return __awaiter(this, void 0, void 0, function () {
+        var response;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, fetch(url)];
+                case 1:
+                    response = _a.sent();
+                    return [2 /*return*/, response.text()];
+            }
+        });
+    });
+}

package/handlers/mediaQuery.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupMediaQuery = setupMediaQuery;
+var Events_js_1 = require("./Events.js");
+function setupMediaQuery(init, rootNodeRef, mountedElements, modules, observer, processNode) {
+    var withMediaMatching = init.withMediaMatching;
+    // Create or use MediaQueryList
+    var mediaQueryList;
+    if (typeof withMediaMatching === 'string') {
+        mediaQueryList = window.matchMedia(withMediaMatching);
+    }
+    else {
+        mediaQueryList = withMediaMatching;
+    }
+    // Track current state
+    var mediaMatches = mediaQueryList.matches;
+    // Set up change listener
+    var mediaChangeHandler = function (e) {
+        var previousMatches = mediaMatches;
+        mediaMatches = e.matches;
+        if (e.matches && !previousMatches) {
+            // Media query now matches - wake up and process elements
+            handleMediaMatch();
+        }
+        else if (!e.matches && previousMatches) {
+            // Media query no longer matches - dismount all elements
+            handleMediaUnmatch();
+        }
+    };
+    function handleMediaMatch() {
+        // Dispatch mediamatch event if requested
+        if (init.getPlayByPlay) {
+            observer.dispatchEvent(new Events_js_1.MediaMatchEvent(init));
+        }
+        // Process all elements in the observed node
+        var rootNode = rootNodeRef.deref();
+        if (rootNode) {
+            processNode(rootNode);
+        }
+    }
+    function handleMediaUnmatch() {
+        // Dispatch mediaunmatch event if requested
+        if (init.getPlayByPlay) {
+            observer.dispatchEvent(new Events_js_1.MediaUnmatchEvent(init));
+        }
+        // Dismount all currently mounted elements
+        var rootNode = rootNodeRef.deref();
+        if (!rootNode) {
+            return;
+        }
+        var context = {
+            modules: modules,
+            observer: observer,
+            rootNode: rootNode,
+            mountConfig: init
+        };
+        // Get all mounted elements from the WeakDual setWeak
+        var mountedElementsList = [];
+        for (var _i = 0, _a = mountedElements.setWeak; _i < _a.length; _i++) {
+            var ref = _a[_i];
+            var element = ref.deref();
+            if (element) {
+                mountedElementsList.push(element);
+            }
+        }
+        // Dismount each element
+        for (var _b = 0, mountedElementsList_1 = mountedElementsList; _b < mountedElementsList_1.length; _b++) {
+            var element = mountedElementsList_1[_b];
+            // Remove from both structures
+            mountedElements.weakSet.delete(element);
+            for (var _c = 0, _d = mountedElements.setWeak; _c < _d.length; _c++) {
+                var ref = _d[_c];
+                if (ref.deref() === element) {
+                    mountedElements.setWeak.delete(ref);
+                    break;
+                }
+            }
+            // Dispatch dismount event with reason
+            observer.dispatchEvent(new Events_js_1.DismountEvent(element, 'media-query-failed', init));
+        }
+    }
+    mediaQueryList.addEventListener('change', mediaChangeHandler);
+    return {
+        mediaQueryList: mediaQueryList,
+        mediaMatches: mediaMatches,
+        cleanup: function () {
+            mediaQueryList.removeEventListener('change', mediaChangeHandler);
+        }
+    };
+}

package/handlers/rootSizeObserver.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupRootSizeObserver = setupRootSizeObserver;
+var Events_js_1 = require("./Events.js");
+function setupRootSizeObserver(init, rootNodeRef, mountedElements, modules, observer, processNode) {
+    var whereObservedRootSizeMatches = init.whereObservedRootSizeMatches;
+    if (!whereObservedRootSizeMatches) {
+        throw new Error('whereObservedRootSizeMatches is required');
+    }
+    var rootNode = rootNodeRef.deref();
+    if (!rootNode) {
+        throw new Error('Root node has been garbage collected');
+    }
+    // Get the element to observe
+    var rootElement = rootNode instanceof Element
+        ? rootNode
+        : rootNode.documentElement;
+    if (!rootElement) {
+        throw new Error('Could not determine root element for whereObservedRootSizeMatches');
+    }
+    // Parse the container query condition
+    // Container queries use the same syntax as media queries: (min-width: 700px)
+    var containerQuery = whereObservedRootSizeMatches;
+    // Check if condition currently matches
+    var conditionMatches = evaluateContainerQuery(rootElement, containerQuery);
+    // Set up ResizeObserver to watch for size changes
+    var resizeObserver = new ResizeObserver(function (entries) {
+        for (var _i = 0, entries_1 = entries; _i < entries_1.length; _i++) {
+            var entry = entries_1[_i];
+            var previousMatches = conditionMatches;
+            conditionMatches = evaluateContainerQuery(entry.target, containerQuery);
+            if (conditionMatches && !previousMatches) {
+                // Condition now matches - process elements
+                handleConditionMatch();
+            }
+            else if (!conditionMatches && previousMatches) {
+                // Condition no longer matches - dismount all elements
+                handleConditionUnmatch();
+            }
+        }
+    });
+    function handleConditionMatch() {
+        // Process all elements in the observed node
+        var rootNode = rootNodeRef.deref();
+        if (rootNode) {
+            processNode(rootNode);
+        }
+    }
+    function handleConditionUnmatch() {
+        // Dismount all currently mounted elements
+        var rootNode = rootNodeRef.deref();
+        if (!rootNode) {
+            return;
+        }
+        var context = {
+            modules: modules,
+            observer: observer,
+            rootNode: rootNode,
+            mountConfig: init
+        };
+        // Get all mounted elements from the WeakDual setWeak
+        var mountedElementsList = [];
+        for (var _i = 0, _a = mountedElements.setWeak; _i < _a.length; _i++) {
+            var ref = _a[_i];
+            var element = ref.deref();
+            if (element) {
+                mountedElementsList.push(element);
+            }
+        }
+        // Dismount each element
+        for (var _b = 0, mountedElementsList_1 = mountedElementsList; _b < mountedElementsList_1.length; _b++) {
+            var element = mountedElementsList_1[_b];
+            // Remove from both structures
+            mountedElements.weakSet.delete(element);
+            for (var _c = 0, _d = mountedElements.setWeak; _c < _d.length; _c++) {
+                var ref = _d[_c];
+                if (ref.deref() === element) {
+                    mountedElements.setWeak.delete(ref);
+                    break;
+                }
+            }
+            // Dispatch dismount event with reason
+            observer.dispatchEvent(new Events_js_1.DismountEvent(element, 'root-size-failed', init));
+        }
+    }
+    // Start observing the root element
+    resizeObserver.observe(rootElement);
+    return {
+        conditionMatches: conditionMatches,
+        cleanup: function () {
+            resizeObserver.disconnect();
+        }
+    };
+}
+/**
+ * Evaluate a container query condition against an element
+ * Supports: min-width, max-width, min-height, max-height
+ */
+function evaluateContainerQuery(element, query) {
+    // Parse container query: (min-width: 700px) or (max-height: 500px)
+    var match = query.match(/\(([^:]+):\s*([^)]+)\)/);
+    if (!match) {
+        console.warn("Invalid container query format: ".concat(query));
+        return false;
+    }
+    var property = match[1], valueStr = match[2];
+    var prop = property.trim();
+    var value = parseFloat(valueStr);
+    if (isNaN(value)) {
+        console.warn("Invalid container query value: ".concat(valueStr));
+        return false;
+    }
+    // Get element dimensions
+    var rect = element.getBoundingClientRect();
+    var width = rect.width;
+    var height = rect.height;
+    // Evaluate condition
+    switch (prop) {
+        case 'min-width':
+            return width >= value;
+        case 'max-width':
+            return width <= value;
+        case 'min-height':
+            return height >= value;
+        case 'max-height':
+            return height <= value;
+        default:
+            console.warn("Unsupported container query property: ".concat(prop));
+            return false;
+    }
+}

package/handlers/upShadowSearch.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.upShadowSearch = upShadowSearch;
+/**
+ * Searches for an element by ID, traversing up through shadow DOM boundaries.
+ *
+ * This function searches for an element with the specified ID starting from the reference
+ * element's root node and continuing up through shadow DOM boundaries until the element
+ * is found or the document root is reached.
+ *
+ * Registry-aware: Only searches in root nodes that share the same customElementRegistry
+ * as the reference element. This respects scoped custom element registry boundaries.
+ *
+ * Search order:
+ * 1. Check current root node using getElementById (if same registry)
+ * 2. If in shadow root, check host element's properties for the ID
+ * 3. Continue up to parent shadow root or document
+ * 4. Handle disconnected fragments via targetFragment property
+ *
+ * @param ref - The reference element to start searching from
+ * @param id - The ID of the element to find
+ * @returns The found element, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const template = document.querySelector('template[src="#myId"]');
+ * const source = upShadowSearch(template, 'myId');
+ * if (source) {
+ *   const clone = source.cloneNode(true);
+ * }
+ * ```
+ */
+function upShadowSearch(ref, id) {
+    var rn = ref.getRootNode();
+    while (rn) {
+        // Try getElementById on current root, but only if it shares the same registry
+        if ('getElementById' in rn && rn.customElementRegistry === ref.customElementRegistry) {
+            var test = rn.getElementById(id);
+            if (test)
+                return test;
+        }
+        // If in shadow root, check host element
+        if ('host' in rn && rn.host) {
+            // Check if host has a property with this ID
+            var hostProp = rn.host[id];
+            if (hostProp instanceof HTMLElement)
+                return hostProp;
+            // Move up to host's root
+            rn = rn.host.getRootNode();
+        }
+        else if (rn === document) {
+            // Reached document root without finding element
+            return null;
+        }
+        else if (!('isConnected' in rn) || !rn.isConnected) {
+            // Handle disconnected fragments
+            if (rn.targetFragment) {
+                rn = rn.targetFragment;
+            }
+            else {
+                rn = document;
+            }
+        }
+        else {
+            // No more parents to check
+            return null;
+        }
+    }
+    return null;
+}

package/handlers/withScopePerimeter.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withScopePerimeter = withScopePerimeter;
+/**
+ * Check if an element is outside (not inside) any ancestor matching a selector.
+ * This implements "donut hole" scoping.
+ *
+ * @param rootNode - The root node to stop traversal at (not checked against selector)
+ * @param matchCandidate - The element to check
+ * @param outside - CSS selector for excluding ancestors
+ * @returns true if element is outside all matching ancestors, false otherwise
+ */
+function withScopePerimeter(rootNode, matchCandidate, outside) {
+    var current = matchCandidate.parentElement;
+    while (current && current !== rootNode) {
+        if (current.matches(outside)) {
+            return false; // Found an excluding ancestor
+        }
+        current = current.parentElement;
+    }
+    return true; // No excluding ancestors found
+}