@studiometa/js-toolkit 3.9.0-beta.0 → 3.9.0-beta.2

package/dist/helpers/defineFeatures.js

@@ -0,0 +1,21 @@
+import { features } from "../Base/features.js";
+import { isBoolean, isObject, isString } from "../utils/is.js";
+function defineFeatures(options) {
+  const { breakpoints, blocking, prefix, attributes } = options;
+  if (isObject(breakpoints)) {
+    features.set("breakpoints", breakpoints);
+  }
+  if (isBoolean(blocking)) {
+    features.set("blocking", blocking);
+  }
+  if (isString(prefix)) {
+    features.set("prefix", prefix);
+  }
+  if (isObject(attributes)) {
+    features.set("attributes", attributes);
+  }
+}
+export {
+  defineFeatures
+};
+//# sourceMappingURL=defineFeatures.js.map

package/dist/helpers/defineFeatures.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/helpers/defineFeatures.ts"],
+  "sourcesContent": ["import { features, type Features } from '../Base/features.js';\nimport { isBoolean, isObject, isString } from '../utils/is.js';\n\n/**\n * Configure global features outside of `createApp`.\n * Useful when using `registerComponent` instead of `createApp`.\n * @link https://js-toolkit.studiometa.dev/api/helpers/defineFeatures.html\n */\nexport function defineFeatures(options: Partial<Features>): void {\n  const { breakpoints, blocking, prefix, attributes } = options;\n\n  if (isObject(breakpoints)) {\n    features.set('breakpoints', breakpoints);\n  }\n\n  if (isBoolean(blocking)) {\n    features.set('blocking', blocking);\n  }\n\n  if (isString(prefix)) {\n    features.set('prefix', prefix);\n  }\n\n  if (isObject(attributes)) {\n    features.set('attributes', attributes);\n  }\n}\n"],
+  "mappings": "AAAA,SAAS,gBAA+B;AACxC,SAAS,WAAW,UAAU,gBAAgB;AAOvC,SAAS,eAAe,SAAkC;AAC/D,QAAM,EAAE,aAAa,UAAU,QAAQ,WAAW,IAAI;AAEtD,MAAI,SAAS,WAAW,GAAG;AACzB,aAAS,IAAI,eAAe,WAAW;AAAA,EACzC;AAEA,MAAI,UAAU,QAAQ,GAAG;AACvB,aAAS,IAAI,YAAY,QAAQ;AAAA,EACnC;AAEA,MAAI,SAAS,MAAM,GAAG;AACpB,aAAS,IAAI,UAAU,MAAM;AAAA,EAC/B;AAEA,MAAI,SAAS,UAAU,GAAG;AACxB,aAAS,IAAI,cAAc,UAAU;AAAA,EACvC;AACF;",
+  "names": []
+}

package/dist/helpers/getClosestParent.d.ts

@@ -0,0 +1,6 @@
+import type { Base, BaseConstructor } from '../Base/Base.js';
+/**
+ * Get the closest parent of a component.
+ * @link https://js-toolkit.studiometa.dev/api/helpers/getClosestParent.html
+ */
+export declare function getClosestParent<T extends BaseConstructor>(childInstance: Base, ParentConstructor: T): InstanceType<T>;

package/dist/helpers/getClosestParent.js

@@ -0,0 +1,13 @@
+import { getAncestorWhere } from "../utils/dom/ancestors.js";
+import { getInstanceFromElement } from "./getInstanceFromElement.js";
+function getClosestParent(childInstance, ParentConstructor) {
+  const parentEl = getAncestorWhere(
+    childInstance.$el,
+    (element) => element && getInstanceFromElement(element, ParentConstructor) !== null
+  );
+  return parentEl ? getInstanceFromElement(parentEl, ParentConstructor) : null;
+}
+export {
+  getClosestParent
+};
+//# sourceMappingURL=getClosestParent.js.map

package/dist/helpers/getClosestParent.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/helpers/getClosestParent.ts"],
+  "sourcesContent": ["import type { Base, BaseConstructor } from '../Base/Base.js';\nimport { getAncestorWhere } from '../utils/dom/ancestors.js';\nimport { getInstanceFromElement } from './getInstanceFromElement.js';\n\n/**\n * Get the closest parent of a component.\n * @link https://js-toolkit.studiometa.dev/api/helpers/getClosestParent.html\n */\nexport function getClosestParent<T extends BaseConstructor>(\n  childInstance: Base,\n  ParentConstructor: T,\n) {\n  const parentEl = getAncestorWhere(\n    childInstance.$el,\n    (element) => element && getInstanceFromElement(element, ParentConstructor) !== null,\n  );\n\n  return parentEl ? getInstanceFromElement(parentEl, ParentConstructor) : null;\n}\n"],
+  "mappings": "AACA,SAAS,wBAAwB;AACjC,SAAS,8BAA8B;AAMhC,SAAS,iBACd,eACA,mBACA;AACA,QAAM,WAAW;AAAA,IACf,cAAc;AAAA,IACd,CAAC,YAAY,WAAW,uBAAuB,SAAS,iBAAiB,MAAM;AAAA,EACjF;AAEA,SAAO,WAAW,uBAAuB,UAAU,iBAAiB,IAAI;AAC1E;",
+  "names": []
+}

package/dist/helpers/getDirectChildren.d.ts

@@ -0,0 +1,23 @@
+import { Base } from '../Base/Base.js';
+/**
+ * Get direct children from a parent when working with nested components.
+ *
+ * @template {Base} T
+ * @param  {Base} parentInstance
+ * @param  {string} parentName
+ * @param  {string} childrenName
+ * @return {T[]}
+ * @link https://js-toolkit.studiometa.dev/api/helpers/getDirectChildren.html
+ */
+export declare function getDirectChildren<T extends Base = Base>(parentInstance: Base, parentName: string, childrenName: string): T[];
+/**
+ * Test if a component instance is a direct child from the given component.
+ *
+ * @param  {Base}    parentInstance
+ * @param  {string}  parentName
+ * @param  {string}  childrenName
+ * @param  {Base}    childInstance
+ * @return {boolean}
+ * @link https://js-toolkit.studiometa.dev/api/helpers/isDirectChild.html
+ */
+export declare function isDirectChild(parentInstance: any, parentName: any, childrenName: any, childInstance: any): boolean;

package/dist/helpers/getDirectChildren.js

@@ -0,0 +1,31 @@
+import { isArray } from "../utils/is.js";
+function getDirectChildren(parentInstance, parentName, childrenName) {
+  const allChildren = parentInstance.__children.props;
+  const children = allChildren[childrenName];
+  const nestedParents = allChildren[parentName];
+  if (!isArray(children)) {
+    return [];
+  }
+  if (!isArray(nestedParents) || nestedParents.length <= 0) {
+    return children;
+  }
+  const directChildren = [];
+  for (const child of children) {
+    for (const nestedParent of nestedParents) {
+      const nestedChildren = nestedParent.__children.props[childrenName];
+      if (isArray(nestedChildren) && nestedChildren.includes(child)) {
+        continue;
+      }
+      directChildren.push(child);
+    }
+  }
+  return directChildren;
+}
+function isDirectChild(parentInstance, parentName, childrenName, childInstance) {
+  return getDirectChildren(parentInstance, parentName, childrenName).includes(childInstance);
+}
+export {
+  getDirectChildren,
+  isDirectChild
+};
+//# sourceMappingURL=getDirectChildren.js.map

package/dist/helpers/getDirectChildren.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/helpers/getDirectChildren.ts"],
+  "sourcesContent": ["import { Base, BaseProps } from '../Base/Base.js';\nimport { isArray } from '../utils/is.js';\n\n/**\n * Get direct children from a parent when working with nested components.\n *\n * @template {Base} T\n * @param  {Base} parentInstance\n * @param  {string} parentName\n * @param  {string} childrenName\n * @return {T[]}\n * @link https://js-toolkit.studiometa.dev/api/helpers/getDirectChildren.html\n */\nexport function getDirectChildren<T extends Base = Base>(\n  parentInstance: Base,\n  parentName: string,\n  childrenName: string,\n): T[] {\n  const allChildren = parentInstance.__children.props;\n  const children = allChildren[childrenName] as Base<BaseProps>[];\n  const nestedParents = allChildren[parentName] as Base<BaseProps>[];\n\n  if (!isArray(children)) {\n    return [];\n  }\n\n  if (!isArray(nestedParents) || nestedParents.length <= 0) {\n    return children as T[];\n  }\n\n  const directChildren = [];\n\n  for (const child of children) {\n    for (const nestedParent of nestedParents) {\n      const nestedChildren = nestedParent.__children.props[childrenName] as Base<BaseProps>[];\n\n      if (isArray(nestedChildren) && nestedChildren.includes(child)) {\n        continue;\n      }\n\n      directChildren.push(child);\n    }\n  }\n\n  return directChildren;\n}\n\n/**\n * Test if a component instance is a direct child from the given component.\n *\n * @param  {Base}    parentInstance\n * @param  {string}  parentName\n * @param  {string}  childrenName\n * @param  {Base}    childInstance\n * @return {boolean}\n * @link https://js-toolkit.studiometa.dev/api/helpers/isDirectChild.html\n */\nexport function isDirectChild(parentInstance, parentName, childrenName, childInstance) {\n  return getDirectChildren(parentInstance, parentName, childrenName).includes(childInstance);\n}\n"],
+  "mappings": "AACA,SAAS,eAAe;AAYjB,SAAS,kBACd,gBACA,YACA,cACK;AACL,QAAM,cAAc,eAAe,WAAW;AAC9C,QAAM,WAAW,YAAY,YAAY;AACzC,QAAM,gBAAgB,YAAY,UAAU;AAE5C,MAAI,CAAC,QAAQ,QAAQ,GAAG;AACtB,WAAO,CAAC;AAAA,EACV;AAEA,MAAI,CAAC,QAAQ,aAAa,KAAK,cAAc,UAAU,GAAG;AACxD,WAAO;AAAA,EACT;AAEA,QAAM,iBAAiB,CAAC;AAExB,aAAW,SAAS,UAAU;AAC5B,eAAW,gBAAgB,eAAe;AACxC,YAAM,iBAAiB,aAAa,WAAW,MAAM,YAAY;AAEjE,UAAI,QAAQ,cAAc,KAAK,eAAe,SAAS,KAAK,GAAG;AAC7D;AAAA,MACF;AAEA,qBAAe,KAAK,KAAK;AAAA,IAC3B;AAAA,EACF;AAEA,SAAO;AACT;AAYO,SAAS,cAAc,gBAAgB,YAAY,cAAc,eAAe;AACrF,SAAO,kBAAkB,gBAAgB,YAAY,YAAY,EAAE,SAAS,aAAa;AAC3F;",
+  "names": []
+}

package/dist/helpers/getInstanceFromElement.d.ts

@@ -0,0 +1,6 @@
+import type { BaseConstructor, BaseEl } from '../Base/Base.js';
+/**
+ * Get a component instance from a DOM element.
+ * @link https://js-toolkit.studiometa.dev/api/helpers/getInstanceFromElement.html
+ */
+export declare function getInstanceFromElement<T extends BaseConstructor>(element: BaseEl, Constructor: T): InstanceType<T> | null;

package/dist/helpers/getInstanceFromElement.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/helpers/getInstanceFromElement.ts"],
+  "sourcesContent": ["import type { BaseConstructor, BaseEl } from '../Base/Base.js';\n\n/**\n * Get a component instance from a DOM element.\n * @link https://js-toolkit.studiometa.dev/api/helpers/getInstanceFromElement.html\n */\nexport function getInstanceFromElement<T extends BaseConstructor>(\n  element: BaseEl,\n  Constructor: T,\n): InstanceType<T> | null {\n  if (!element || !element.__base__ || !element.__base__.has(Constructor.config.name)) {\n    return null;\n  }\n\n  return element.__base__.get(Constructor.config.name) as InstanceType<T>;\n}\n"],
+  "mappings": "AAMO,SAAS,uBACd,SACA,aACwB;AACxB,MAAI,CAAC,WAAW,CAAC,QAAQ,YAAY,CAAC,QAAQ,SAAS,IAAI,YAAY,OAAO,IAAI,GAAG;AACnF,WAAO;AAAA,EACT;AAEA,SAAO,QAAQ,SAAS,IAAI,YAAY,OAAO,IAAI;AACrD;",
+  "names": []
+}

package/dist/helpers/importOnInteraction.d.ts

@@ -0,0 +1,19 @@
+import type { Base, BaseConstructor } from '../Base/Base.js';
+/**
+ * Import a component on an interaction.
+ *
+ * @template {BaseConstructor} [T=BaseConstructor]
+ * @param {() => Promise<T|{default:T}>} fn
+ *   The import function.
+ * @param {string|HTMLElement|HTMLElement[]} nameOrSelectorOrElement
+ *   The name or selector for the component.
+ * @param {string|string[]} events
+ *   The events to listen to to trigger the import.
+ * @param {Base} [parent]
+ *   The parent component.
+ * @return {Promise<InstanceType<T>>}
+ * @link https://js-toolkit.studiometa.dev/api/helpers/importOnInteraction.html
+ */
+export declare function importOnInteraction<T extends BaseConstructor = BaseConstructor>(fn: () => Promise<T | {
+    default: T;
+}>, nameOrSelectorOrElement: string | HTMLElement | HTMLElement[], events: string | string[], parent?: Base): Promise<T>;

package/dist/helpers/importOnInteraction.js

@@ -0,0 +1,27 @@
+import { getComponentResolver } from "../utils/getComponentResolver.js";
+import { isString } from "../utils/is.js";
+import { getTargetElements } from "./utils.js";
+function importOnInteraction(fn, nameOrSelectorOrElement, events, parent) {
+  const normalizedEvents = isString(events) ? [events] : events;
+  const resolver = getComponentResolver(fn);
+  return new Promise((resolve) => {
+    const elements = getTargetElements(nameOrSelectorOrElement, parent?.$el);
+    const eventListenerOptions = {
+      capture: true,
+      passive: true,
+      once: true
+    };
+    const handler = () => {
+      resolver(resolve);
+    };
+    for (const element of elements) {
+      for (const event of normalizedEvents) {
+        element.addEventListener(event, handler, eventListenerOptions);
+      }
+    }
+  });
+}
+export {
+  importOnInteraction
+};
+//# sourceMappingURL=importOnInteraction.js.map

package/dist/helpers/importOnInteraction.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/helpers/importOnInteraction.ts"],
+  "sourcesContent": ["import type { Base, BaseConstructor } from '../Base/Base.js';\nimport { getComponentResolver } from '../utils/getComponentResolver.js';\nimport { isString } from '../utils/is.js';\nimport { getTargetElements } from './utils.js';\n\n/**\n * Import a component on an interaction.\n *\n * @template {BaseConstructor} [T=BaseConstructor]\n * @param {() => Promise<T|{default:T}>} fn\n *   The import function.\n * @param {string|HTMLElement|HTMLElement[]} nameOrSelectorOrElement\n *   The name or selector for the component.\n * @param {string|string[]} events\n *   The events to listen to to trigger the import.\n * @param {Base} [parent]\n *   The parent component.\n * @return {Promise<InstanceType<T>>}\n * @link https://js-toolkit.studiometa.dev/api/helpers/importOnInteraction.html\n */\nexport function importOnInteraction<T extends BaseConstructor = BaseConstructor>(\n  fn: () => Promise<T | { default: T }>,\n  nameOrSelectorOrElement: string | HTMLElement | HTMLElement[],\n  events: string | string[],\n  parent?: Base,\n): Promise<T> {\n  const normalizedEvents = isString(events) ? [events] : events;\n\n  const resolver = getComponentResolver(fn);\n\n  return new Promise((resolve) => {\n    const elements = getTargetElements(nameOrSelectorOrElement, parent?.$el);\n    const eventListenerOptions = {\n      capture: true,\n      passive: true,\n      once: true,\n    };\n    const handler = () => {\n      resolver(resolve);\n    };\n\n    for (const element of elements) {\n      for (const event of normalizedEvents) {\n        element.addEventListener(event, handler, eventListenerOptions);\n      }\n    }\n  });\n}\n"],
+  "mappings": "AACA,SAAS,4BAA4B;AACrC,SAAS,gBAAgB;AACzB,SAAS,yBAAyB;AAiB3B,SAAS,oBACd,IACA,yBACA,QACA,QACY;AACZ,QAAM,mBAAmB,SAAS,MAAM,IAAI,CAAC,MAAM,IAAI;AAEvD,QAAM,WAAW,qBAAqB,EAAE;AAExC,SAAO,IAAI,QAAQ,CAAC,YAAY;AAC9B,UAAM,WAAW,kBAAkB,yBAAyB,QAAQ,GAAG;AACvE,UAAM,uBAAuB;AAAA,MAC3B,SAAS;AAAA,MACT,SAAS;AAAA,MACT,MAAM;AAAA,IACR;AACA,UAAM,UAAU,MAAM;AACpB,eAAS,OAAO;AAAA,IAClB;AAEA,eAAW,WAAW,UAAU;AAC9B,iBAAW,SAAS,kBAAkB;AACpC,gBAAQ,iBAAiB,OAAO,SAAS,oBAAoB;AAAA,MAC/D;AAAA,IACF;AAAA,EACF,CAAC;AACH;",
+  "names": []
+}

package/dist/helpers/importOnMediaQuery.d.ts

@@ -0,0 +1,15 @@
+import type { BaseConstructor } from '../Base/Base.js';
+/**
+ * Import a component when given media query is true.
+ *
+ * @template {BaseConstructor} T
+ * @param {() => Promise<T|{default:T}>} fn
+ *   The import function.
+ * @param {string} media
+ *   The media query name and value (see https://developer.mozilla.org/en-US/docs/Web/CSS/@media#media_features)
+ * @return {Promise<T>}
+ * @link https://js-toolkit.studiometa.dev/api/helpers/importOnMediaQuery.html
+ */
+export declare function importOnMediaQuery<T extends BaseConstructor = BaseConstructor>(fn: () => Promise<T | {
+    default: T;
+}>, media: string): Promise<T>;

package/dist/helpers/importOnMediaQuery.js

@@ -0,0 +1,22 @@
+import { getComponentResolver } from "../utils/getComponentResolver.js";
+function importOnMediaQuery(fn, media) {
+  const resolver = getComponentResolver(fn);
+  return new Promise((resolve) => {
+    const mediaQueryList = window.matchMedia(media);
+    if (mediaQueryList.matches) {
+      resolver(resolve);
+    }
+    const changeHandler = (event) => {
+      if (event.matches) {
+        setTimeout(() => {
+          resolver(resolve, () => mediaQueryList.removeEventListener("change", changeHandler));
+        }, 0);
+      }
+    };
+    mediaQueryList.addEventListener("change", changeHandler);
+  });
+}
+export {
+  importOnMediaQuery
+};
+//# sourceMappingURL=importOnMediaQuery.js.map

package/dist/helpers/importOnMediaQuery.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/helpers/importOnMediaQuery.ts"],
+  "sourcesContent": ["import type { BaseConstructor } from '../Base/Base.js';\nimport { getComponentResolver } from '../utils/getComponentResolver.js';\n\n/**\n * Import a component when given media query is true.\n *\n * @template {BaseConstructor} T\n * @param {() => Promise<T|{default:T}>} fn\n *   The import function.\n * @param {string} media\n *   The media query name and value (see https://developer.mozilla.org/en-US/docs/Web/CSS/@media#media_features)\n * @return {Promise<T>}\n * @link https://js-toolkit.studiometa.dev/api/helpers/importOnMediaQuery.html\n */\nexport function importOnMediaQuery<T extends BaseConstructor = BaseConstructor>(\n  fn: () => Promise<T | { default: T }>,\n  media: string,\n): Promise<T> {\n  const resolver = getComponentResolver(fn);\n\n  return new Promise((resolve) => {\n    const mediaQueryList = window.matchMedia(media);\n\n    if (mediaQueryList.matches) {\n      resolver(resolve);\n    }\n\n    const changeHandler = (event: MediaQueryListEvent) => {\n      if (event.matches) {\n        setTimeout(() => {\n          // Remove listener and mount the component\n          resolver(resolve, () => mediaQueryList.removeEventListener('change', changeHandler));\n        }, 0);\n      }\n    };\n\n    // Start listening for changes\n    mediaQueryList.addEventListener('change', changeHandler);\n  });\n}\n"],
+  "mappings": "AACA,SAAS,4BAA4B;AAa9B,SAAS,mBACd,IACA,OACY;AACZ,QAAM,WAAW,qBAAqB,EAAE;AAExC,SAAO,IAAI,QAAQ,CAAC,YAAY;AAC9B,UAAM,iBAAiB,OAAO,WAAW,KAAK;AAE9C,QAAI,eAAe,SAAS;AAC1B,eAAS,OAAO;AAAA,IAClB;AAEA,UAAM,gBAAgB,CAAC,UAA+B;AACpD,UAAI,MAAM,SAAS;AACjB,mBAAW,MAAM;AAEf,mBAAS,SAAS,MAAM,eAAe,oBAAoB,UAAU,aAAa,CAAC;AAAA,QACrF,GAAG,CAAC;AAAA,MACN;AAAA,IACF;AAGA,mBAAe,iBAAiB,UAAU,aAAa;AAAA,EACzD,CAAC;AACH;",
+  "names": []
+}

package/dist/helpers/importWhenIdle.d.ts

@@ -0,0 +1,19 @@
+import type { BaseConstructor } from '../Base/Base.js';
+type ImportWhenIdleOptions = {
+    timeout?: number;
+};
+/**
+ * Import a component when user is idle.
+ *
+ * @template {BaseConstructor} T
+ * @param {() => Promise<T|{default:T}>} fn
+ *   The import function.
+ * @param {ImportWhenIdleOptions} [options]
+ *   The time to wait before triggering the callback if never idle.
+ * @return {Promise<T>}
+ * @link https://js-toolkit.studiometa.dev/api/helpers/importWhenIdle.html
+ */
+export declare function importWhenIdle<T extends BaseConstructor = BaseConstructor>(fn: () => Promise<T | {
+    default: T;
+}>, { timeout }?: ImportWhenIdleOptions): Promise<T>;
+export {};

package/dist/helpers/importWhenIdle.js

@@ -0,0 +1,24 @@
+import { getComponentResolver } from "../utils/getComponentResolver.js";
+function importWhenIdle(fn, { timeout = 1 } = {}) {
+  const resolver = getComponentResolver(fn);
+  return new Promise((resolve) => {
+    if (!("requestIdleCallback" in window)) {
+      setTimeout(() => {
+        resolver(resolve);
+      }, timeout);
+    } else {
+      window.requestIdleCallback(
+        () => {
+          setTimeout(() => {
+            resolver(resolve);
+          }, 0);
+        },
+        { timeout }
+      );
+    }
+  });
+}
+export {
+  importWhenIdle
+};
+//# sourceMappingURL=importWhenIdle.js.map

package/dist/helpers/importWhenIdle.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/helpers/importWhenIdle.ts"],
+  "sourcesContent": ["import type { BaseConstructor } from '../Base/Base.js';\nimport { getComponentResolver } from '../utils/getComponentResolver.js';\n\ntype ImportWhenIdleOptions = {\n  timeout?: number;\n};\n\n/**\n * Import a component when user is idle.\n *\n * @template {BaseConstructor} T\n * @param {() => Promise<T|{default:T}>} fn\n *   The import function.\n * @param {ImportWhenIdleOptions} [options]\n *   The time to wait before triggering the callback if never idle.\n * @return {Promise<T>}\n * @link https://js-toolkit.studiometa.dev/api/helpers/importWhenIdle.html\n */\nexport function importWhenIdle<T extends BaseConstructor = BaseConstructor>(\n  fn: () => Promise<T | { default: T }>,\n  { timeout = 1 }: ImportWhenIdleOptions = {},\n): Promise<T> {\n  const resolver = getComponentResolver(fn);\n\n  return new Promise((resolve) => {\n    if (!('requestIdleCallback' in window)) {\n      setTimeout(() => {\n        resolver(resolve);\n      }, timeout);\n    } else {\n      window.requestIdleCallback(\n        () => {\n          setTimeout(() => {\n            resolver(resolve);\n          }, 0);\n        },\n        { timeout },\n      );\n    }\n  });\n}\n"],
+  "mappings": "AACA,SAAS,4BAA4B;AAiB9B,SAAS,eACd,IACA,EAAE,UAAU,EAAE,IAA2B,CAAC,GAC9B;AACZ,QAAM,WAAW,qBAAqB,EAAE;AAExC,SAAO,IAAI,QAAQ,CAAC,YAAY;AAC9B,QAAI,EAAE,yBAAyB,SAAS;AACtC,iBAAW,MAAM;AACf,iBAAS,OAAO;AAAA,MAClB,GAAG,OAAO;AAAA,IACZ,OAAO;AACL,aAAO;AAAA,QACL,MAAM;AACJ,qBAAW,MAAM;AACf,qBAAS,OAAO;AAAA,UAClB,GAAG,CAAC;AAAA,QACN;AAAA,QACA,EAAE,QAAQ;AAAA,MACZ;AAAA,IACF;AAAA,EACF,CAAC;AACH;",
+  "names": []
+}

package/dist/helpers/importWhenPrefersMotion.d.ts

@@ -0,0 +1,12 @@
+import type { BaseConstructor } from '../Base/Base.js';
+/**
+ * Import a component if user does not reduce motion.
+ *
+ * @template {BaseConstructor} T
+ * @param {() => Promise<T|{default:T}>} fn
+ * @return {Promise<T>}
+ * @link https://js-toolkit.studiometa.dev/api/helpers/importWhenPrefersMotion.html
+ */
+export declare function importWhenPrefersMotion<T extends BaseConstructor = BaseConstructor>(fn: () => Promise<T | {
+    default: T;
+}>): Promise<T>;

package/dist/helpers/importWhenPrefersMotion.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/helpers/importWhenPrefersMotion.ts"],
+  "sourcesContent": ["import type { BaseConstructor } from '../Base/Base.js';\nimport { importOnMediaQuery } from './importOnMediaQuery.js';\n\n/**\n * Import a component if user does not reduce motion.\n *\n * @template {BaseConstructor} T\n * @param {() => Promise<T|{default:T}>} fn\n * @return {Promise<T>}\n * @link https://js-toolkit.studiometa.dev/api/helpers/importWhenPrefersMotion.html\n */\nexport function importWhenPrefersMotion<T extends BaseConstructor = BaseConstructor>(\n  fn: () => Promise<T | { default: T }>,\n): Promise<T> {\n  return importOnMediaQuery(fn, 'not (prefers-reduced-motion)');\n}\n"],
+  "mappings": "AACA,SAAS,0BAA0B;AAU5B,SAAS,wBACd,IACY;AACZ,SAAO,mBAAmB,IAAI,8BAA8B;AAC9D;",
+  "names": []
+}

package/dist/helpers/importWhenVisible.d.ts

@@ -0,0 +1,19 @@
+import type { Base, BaseConstructor } from '../Base/Base.js';
+/**
+ * Import a component when it is visible.
+ *
+ * @template {BaseConstructor} T
+ * @param {() => Promise<T|{default:T}>} fn
+ *   The import function.
+ * @param {string|HTMLElement|HTMLElement[]} nameOrSelectorOrElement
+ *   The name or selector for the component.
+ * @param {Base} [parent]
+ *   The parent component.
+ * @param {IntersectionObserverInit} [observerOptions]
+ *   Options for the `IntersectionObserver` instance.
+ * @return {Promise<T>}
+ * @link https://js-toolkit.studiometa.dev/api/helpers/importWhenVisible.html
+ */
+export declare function importWhenVisible<T extends BaseConstructor = BaseConstructor>(fn: () => Promise<T | {
+    default: T;
+}>, nameOrSelectorOrElement: string | HTMLElement | HTMLElement[], parent?: Base, observerOptions?: IntersectionObserverInit): Promise<T>;

package/dist/helpers/importWhenVisible.js

@@ -0,0 +1,21 @@
+import { getComponentResolver } from "../utils/getComponentResolver.js";
+import { getTargetElements } from "./utils.js";
+function importWhenVisible(fn, nameOrSelectorOrElement, parent, observerOptions = {}) {
+  const resolver = getComponentResolver(fn);
+  return new Promise((resolve) => {
+    const observer = new IntersectionObserver((entries) => {
+      const someEntriesAreVisible = entries.some((entry) => entry.isIntersecting);
+      if (someEntriesAreVisible) {
+        setTimeout(() => {
+          resolver(resolve, () => observer.disconnect());
+        }, 0);
+      }
+    }, observerOptions);
+    const elements = getTargetElements(nameOrSelectorOrElement, parent?.$el);
+    for (const element of elements) observer.observe(element);
+  });
+}
+export {
+  importWhenVisible
+};
+//# sourceMappingURL=importWhenVisible.js.map

package/dist/helpers/importWhenVisible.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/helpers/importWhenVisible.ts"],
+  "sourcesContent": ["import type { Base, BaseConstructor } from '../Base/Base.js';\nimport { getComponentResolver } from '../utils/getComponentResolver.js';\nimport { getTargetElements } from './utils.js';\n\n/**\n * Import a component when it is visible.\n *\n * @template {BaseConstructor} T\n * @param {() => Promise<T|{default:T}>} fn\n *   The import function.\n * @param {string|HTMLElement|HTMLElement[]} nameOrSelectorOrElement\n *   The name or selector for the component.\n * @param {Base} [parent]\n *   The parent component.\n * @param {IntersectionObserverInit} [observerOptions]\n *   Options for the `IntersectionObserver` instance.\n * @return {Promise<T>}\n * @link https://js-toolkit.studiometa.dev/api/helpers/importWhenVisible.html\n */\nexport function importWhenVisible<T extends BaseConstructor = BaseConstructor>(\n  fn: () => Promise<T | { default: T }>,\n  nameOrSelectorOrElement: string | HTMLElement | HTMLElement[],\n  parent?: Base,\n  observerOptions: IntersectionObserverInit = {},\n): Promise<T> {\n  const resolver = getComponentResolver(fn);\n\n  return new Promise((resolve) => {\n    const observer = new IntersectionObserver((entries) => {\n      const someEntriesAreVisible = entries.some((entry) => entry.isIntersecting);\n      if (someEntriesAreVisible) {\n        setTimeout(() => {\n          resolver(resolve, () => observer.disconnect());\n        }, 0);\n      }\n    }, observerOptions);\n\n    const elements = getTargetElements(nameOrSelectorOrElement, parent?.$el);\n    for (const element of elements) observer.observe(element);\n  });\n}\n"],
+  "mappings": "AACA,SAAS,4BAA4B;AACrC,SAAS,yBAAyB;AAiB3B,SAAS,kBACd,IACA,yBACA,QACA,kBAA4C,CAAC,GACjC;AACZ,QAAM,WAAW,qBAAqB,EAAE;AAExC,SAAO,IAAI,QAAQ,CAAC,YAAY;AAC9B,UAAM,WAAW,IAAI,qBAAqB,CAAC,YAAY;AACrD,YAAM,wBAAwB,QAAQ,KAAK,CAAC,UAAU,MAAM,cAAc;AAC1E,UAAI,uBAAuB;AACzB,mBAAW,MAAM;AACf,mBAAS,SAAS,MAAM,SAAS,WAAW,CAAC;AAAA,QAC/C,GAAG,CAAC;AAAA,MACN;AAAA,IACF,GAAG,eAAe;AAElB,UAAM,WAAW,kBAAkB,yBAAyB,QAAQ,GAAG;AACvE,eAAW,WAAW,SAAU,UAAS,QAAQ,OAAO;AAAA,EAC1D,CAAC;AACH;",
+  "names": []
+}

package/dist/helpers/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/helpers/index.ts"],
+  "sourcesContent": ["export { createApp, type CreateAppOptions } from './createApp.js';\nexport { defineFeatures } from './defineFeatures.js';\nexport { getClosestParent } from './getClosestParent.js';\nexport { getDirectChildren, isDirectChild } from './getDirectChildren.js';\nexport { getInstanceFromElement } from './getInstanceFromElement.js';\nexport { importOnInteraction } from './importOnInteraction.js';\nexport { importOnMediaQuery } from './importOnMediaQuery.js';\nexport { importWhenIdle } from './importWhenIdle.js';\nexport { importWhenPrefersMotion } from './importWhenPrefersMotion.js';\nexport { importWhenVisible } from './importWhenVisible.js';\nexport { logTree } from './logTree.js';\nexport { registerComponent } from './registerComponent.js';\nexport { registerComponents } from './registerComponents.js';\nexport {\n  type QueryOptions,\n  queryComponent,\n  queryComponentAll,\n  closestComponent,\n} from './queryComponent.js';\n"],
+  "mappings": "AAAA,SAAS,iBAAwC;AACjD,SAAS,sBAAsB;AAC/B,SAAS,wBAAwB;AACjC,SAAS,mBAAmB,qBAAqB;AACjD,SAAS,8BAA8B;AACvC,SAAS,2BAA2B;AACpC,SAAS,0BAA0B;AACnC,SAAS,sBAAsB;AAC/B,SAAS,+BAA+B;AACxC,SAAS,yBAAyB;AAClC,SAAS,eAAe;AACxB,SAAS,yBAAyB;AAClC,SAAS,0BAA0B;AACnC;AAAA,EAEE;AAAA,EACA;AAAA,EACA;AAAA,OACK;",
+  "names": []
+}

package/dist/helpers/logTree.js

@@ -0,0 +1,59 @@
+import { getInstances } from "../Base/utils.js";
+function buildTree(root) {
+  const allInstances = getInstances();
+  const rootNode = { instance: root, children: [] };
+  const descendants = [];
+  for (const instance of allInstances) {
+    if (instance !== root && root.$el.contains(instance.$el)) {
+      descendants.push(instance);
+    }
+  }
+  descendants.sort((a, b) => {
+    const position = a.$el.compareDocumentPosition(b.$el);
+    if (position & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
+    if (position & Node.DOCUMENT_POSITION_PRECEDING) return 1;
+    return 0;
+  });
+  const nodeMap = /* @__PURE__ */ new Map();
+  nodeMap.set(root, rootNode);
+  for (const instance of descendants) {
+    const node = { instance, children: [] };
+    nodeMap.set(instance, node);
+    let parentNode = rootNode;
+    for (const [candidate, candidateNode] of nodeMap) {
+      if (candidate !== instance && candidate.$el.contains(instance.$el) && // Pick the most specific (deepest) container
+      parentNode.instance.$el.contains(candidate.$el)) {
+        parentNode = candidateNode;
+      }
+    }
+    parentNode.children.push(node);
+  }
+  return rootNode;
+}
+function logNode(node) {
+  const { instance } = node;
+  const mounted = instance.$isMounted;
+  const status = mounted ? "\u25CF" : "\u25CB";
+  const label = `${status} ${instance.$id}`;
+  if (node.children.length > 0) {
+    console.groupCollapsed(label, instance.$el);
+    for (const child of node.children) {
+      logNode(child);
+    }
+    console.groupEnd();
+  } else {
+    console.log(label, instance.$el);
+  }
+}
+function logTree(instance) {
+  const tree = buildTree(instance);
+  console.group(`\u{1F333} ${instance.$config.name}`);
+  for (const child of tree.children) {
+    logNode(child);
+  }
+  console.groupEnd();
+}
+export {
+  logTree
+};
+//# sourceMappingURL=logTree.js.map

package/dist/helpers/logTree.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/helpers/logTree.ts"],
+  "sourcesContent": ["import type { Base } from '../Base/Base.js';\nimport { getInstances } from '../Base/utils.js';\n\n/**\n * Build a tree structure from a flat set of instances using DOM containment.\n */\nfunction buildTree(root: Base): TreeNode {\n  const allInstances = getInstances();\n  const rootNode: TreeNode = { instance: root, children: [] };\n\n  // Collect all instances that are descendants of root (excluding root itself)\n  const descendants: Base[] = [];\n  for (const instance of allInstances) {\n    if (instance !== root && root.$el.contains(instance.$el)) {\n      descendants.push(instance);\n    }\n  }\n\n  // Sort by DOM order (depth-first)\n  descendants.sort((a, b) => {\n    const position = a.$el.compareDocumentPosition(b.$el);\n    if (position & Node.DOCUMENT_POSITION_FOLLOWING) return -1;\n    if (position & Node.DOCUMENT_POSITION_PRECEDING) return 1;\n    return 0;\n  });\n\n  // Build tree: assign each instance to its closest ancestor in the tree\n  const nodeMap = new Map<Base, TreeNode>();\n  nodeMap.set(root, rootNode);\n\n  for (const instance of descendants) {\n    const node: TreeNode = { instance, children: [] };\n    nodeMap.set(instance, node);\n\n    // Find the closest ancestor that is already in the tree\n    let parentNode = rootNode;\n    for (const [candidate, candidateNode] of nodeMap) {\n      if (\n        candidate !== instance &&\n        candidate.$el.contains(instance.$el) &&\n        // Pick the most specific (deepest) container\n        parentNode.instance.$el.contains(candidate.$el)\n      ) {\n        parentNode = candidateNode;\n      }\n    }\n\n    parentNode.children.push(node);\n  }\n\n  return rootNode;\n}\n\ninterface TreeNode {\n  instance: Base;\n  children: TreeNode[];\n}\n\n/**\n * Log a tree node and its children using console groups.\n */\nfunction logNode(node: TreeNode): void {\n  const { instance } = node;\n  const mounted = instance.$isMounted;\n  const status = mounted ? '\u25CF' : '\u25CB';\n  const label = `${status} ${instance.$id}`;\n\n  if (node.children.length > 0) {\n    console.groupCollapsed(label, instance.$el);\n    for (const child of node.children) {\n      logNode(child);\n    }\n    console.groupEnd();\n  } else {\n    console.log(label, instance.$el);\n  }\n}\n\n/**\n * Log the component tree starting from the given instance.\n *\n * Uses the global instance registry and DOM containment to build the tree,\n * without relying on the deprecated `$children` API.\n *\n * @param   {Base} instance The root component instance.\n * @example\n * ```js\n * import { createApp, logTree } from '@studiometa/js-toolkit';\n *\n * const useApp = createApp(App);\n * useApp().then((app) => logTree(app));\n * ```\n */\nexport function logTree(instance: Base): void {\n  const tree = buildTree(instance);\n  console.group(`\uD83C\uDF33 ${instance.$config.name}`);\n  for (const child of tree.children) {\n    logNode(child);\n  }\n  console.groupEnd();\n}\n"],
+  "mappings": "AACA,SAAS,oBAAoB;AAK7B,SAAS,UAAU,MAAsB;AACvC,QAAM,eAAe,aAAa;AAClC,QAAM,WAAqB,EAAE,UAAU,MAAM,UAAU,CAAC,EAAE;AAG1D,QAAM,cAAsB,CAAC;AAC7B,aAAW,YAAY,cAAc;AACnC,QAAI,aAAa,QAAQ,KAAK,IAAI,SAAS,SAAS,GAAG,GAAG;AACxD,kBAAY,KAAK,QAAQ;AAAA,IAC3B;AAAA,EACF;AAGA,cAAY,KAAK,CAAC,GAAG,MAAM;AACzB,UAAM,WAAW,EAAE,IAAI,wBAAwB,EAAE,GAAG;AACpD,QAAI,WAAW,KAAK,4BAA6B,QAAO;AACxD,QAAI,WAAW,KAAK,4BAA6B,QAAO;AACxD,WAAO;AAAA,EACT,CAAC;AAGD,QAAM,UAAU,oBAAI,IAAoB;AACxC,UAAQ,IAAI,MAAM,QAAQ;AAE1B,aAAW,YAAY,aAAa;AAClC,UAAM,OAAiB,EAAE,UAAU,UAAU,CAAC,EAAE;AAChD,YAAQ,IAAI,UAAU,IAAI;AAG1B,QAAI,aAAa;AACjB,eAAW,CAAC,WAAW,aAAa,KAAK,SAAS;AAChD,UACE,cAAc,YACd,UAAU,IAAI,SAAS,SAAS,GAAG;AAAA,MAEnC,WAAW,SAAS,IAAI,SAAS,UAAU,GAAG,GAC9C;AACA,qBAAa;AAAA,MACf;AAAA,IACF;AAEA,eAAW,SAAS,KAAK,IAAI;AAAA,EAC/B;AAEA,SAAO;AACT;AAUA,SAAS,QAAQ,MAAsB;AACrC,QAAM,EAAE,SAAS,IAAI;AACrB,QAAM,UAAU,SAAS;AACzB,QAAM,SAAS,UAAU,WAAM;AAC/B,QAAM,QAAQ,GAAG,MAAM,IAAI,SAAS,GAAG;AAEvC,MAAI,KAAK,SAAS,SAAS,GAAG;AAC5B,YAAQ,eAAe,OAAO,SAAS,GAAG;AAC1C,eAAW,SAAS,KAAK,UAAU;AACjC,cAAQ,KAAK;AAAA,IACf;AACA,YAAQ,SAAS;AAAA,EACnB,OAAO;AACL,YAAQ,IAAI,OAAO,SAAS,GAAG;AAAA,EACjC;AACF;AAiBO,SAAS,QAAQ,UAAsB;AAC5C,QAAM,OAAO,UAAU,QAAQ;AAC/B,UAAQ,MAAM,aAAM,SAAS,QAAQ,IAAI,EAAE;AAC3C,aAAW,SAAS,KAAK,UAAU;AACjC,YAAQ,KAAK;AAAA,EACf;AACA,UAAQ,SAAS;AACnB;",
+  "names": []
+}

package/dist/helpers/queryComponent.d.ts

@@ -0,0 +1,28 @@
+import type { Base } from '../Base/Base.js';
+export interface QueryOptions {
+    from?: HTMLElement | Document;
+}
+export type ParsedQuery = {
+    name: string;
+    cssSelector?: string;
+    state?: string;
+};
+/**
+ * Parse a query string like 'Foo(.css-selector):mounted' into its parts.
+ */
+export declare const parseQuery: (query: string) => ParsedQuery;
+export declare function instanceIsMatching(instance: Base, parsedQuery: ParsedQuery): boolean;
+/**
+ * Get the first instance of component with the given query.
+ */
+export declare function queryComponent<T extends Base = Base>(query: string, options?: QueryOptions): T | undefined;
+/**
+ * Get all instances of component with the given query.
+ */
+export declare function queryComponentAll<T extends Base = Base>(query: string, options?: QueryOptions): T[];
+/**
+ * Get the closest component instance by traversing up the DOM tree.
+ */
+export declare function closestComponent<T extends Base = Base>(query: string, options?: {
+    from: HTMLElement;
+}): T | undefined;

package/dist/helpers/queryComponent.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/helpers/queryComponent.ts"],
+  "sourcesContent": ["import type { Base, BaseEl } from '../Base/Base.js';\nimport { getInstances, hasInstance } from '../Base/utils.js';\nimport { memo } from '../utils/memo.js';\nimport { getAncestorWhere } from '../utils/dom/ancestors.js';\n\nexport interface QueryOptions {\n  from?: HTMLElement | Document;\n}\n\ntype ComponentState = 'mounted' | 'destroyed' | 'terminated';\nexport type ParsedQuery = {\n  name: string;\n  cssSelector?: string;\n  state?: string;\n};\n\nconst REGEX_QUERY = /([a-zA-Z0-9]+)(\\((.*)\\))?(:([a-z]+))?/;\n\n/**\n * Parse a query string like 'Foo(.css-selector):mounted' into its parts.\n */\nexport const parseQuery = memo((query: string): ParsedQuery => {\n  const [, name, , cssSelector, , state] = query.match(REGEX_QUERY) as [\n    string,\n    string,\n    string | undefined,\n    string | undefined,\n    string | undefined,\n    ComponentState | undefined,\n  ];\n\n  return {\n    name,\n    cssSelector,\n    state,\n  };\n});\n\nexport function instanceIsMatching(instance: Base, parsedQuery: ParsedQuery): boolean {\n  if (instance.$config.name !== parsedQuery.name) return false;\n  if (parsedQuery.cssSelector && !instance.$el.matches(parsedQuery.cssSelector)) return false;\n\n  if (parsedQuery.state === 'mounted' && !instance.$isMounted) return false;\n  if (parsedQuery.state === 'destroyed' && instance.$isMounted) return false;\n\n  return true;\n}\n\n/**\n * Resolve the live instance attached to an element under a given name.\n *\n * Reads the element's `__base__` map (the same O(1)-per-element lookup\n * `closestComponent` uses) and applies the single matching gate:\n *   - the entry must exist and not be the literal `'terminated'` string\n *     written by `$terminate` (`Base.ts`);\n *   - the instance must still be \"live\" (registered in the global storage\n *     between `before-mounted` and `after-destroyed`) \u2014 `__base__` keeps\n *     destroyed-but-not-terminated instances that `getInstances()` has already\n *     dropped, so `hasInstance` preserves the historical visibility window;\n *   - it must satisfy `instanceIsMatching` (name, CSS selector, state).\n *\n * The lookup is keyed on `parsedQuery.name` only \u2014 never on a name-derived DOM\n * selector \u2014 because `__base__` membership is independent of whether the element\n * carries a `data-component` attribute or a `w-name` tag.\n */\nfunction resolveMatch<T extends Base>(element: BaseEl, parsedQuery: ParsedQuery): T | undefined {\n  const baseMap = element.__base__;\n  if (!baseMap) return undefined;\n\n  const instance = baseMap.get(parsedQuery.name);\n  if (!instance || instance === 'terminated') return undefined;\n  if (!hasInstance(instance) || !instanceIsMatching(instance, parsedQuery)) return undefined;\n\n  return instance as T;\n}\n\n/**\n * Yield the instances matching the given query within the `from` root.\n *\n * When `from` is the document, there is no containment/attachment constraint, so\n * every live matching instance is returned even if its `$el` is detached from the\n * global document \u2014 the global instance storage is the source of truth here (a\n * `document.querySelectorAll` scan would miss detached elements entirely).\n *\n * When `from` is an element, matches are resolved via a scoped\n * `querySelectorAll('*')` descendant traversal plus an explicit check of `from`\n * itself (which `querySelectorAll` excludes), each resolved through its\n * `__base__` map. This scales with the size of the `from` subtree instead of the\n * global instance count. `'*'` is required \u2014 a name-derived selector would miss\n * components mounted on elements that carry no matching attribute/tag (e.g.\n * `withName(Base, name)` on a plain element, or a component registered under an\n * arbitrary CSS selector).\n */\nfunction* queryMatches<T extends Base>(\n  parsedQuery: ParsedQuery,\n  from: HTMLElement | Document,\n): Generator<T> {\n  if (from === document) {\n    for (const instance of getInstances()) {\n      if (hasInstance(instance) && instanceIsMatching(instance, parsedQuery)) {\n        yield instance as T;\n      }\n    }\n    return;\n  }\n\n  const seen = new Set<T>();\n\n  const selfMatch = resolveMatch<T>(from as BaseEl, parsedQuery);\n  if (selfMatch) {\n    seen.add(selfMatch);\n    yield selfMatch;\n  }\n\n  for (const element of from.querySelectorAll<HTMLElement>('*')) {\n    const match = resolveMatch<T>(element as BaseEl, parsedQuery);\n    if (match && !seen.has(match)) {\n      seen.add(match);\n      yield match;\n    }\n  }\n}\n\n/**\n * Get the first instance of component with the given query.\n */\nexport function queryComponent<T extends Base = Base>(\n  query: string,\n  options: QueryOptions = {},\n): T | undefined {\n  const parsedQuery = parseQuery(query);\n  const { from = document } = options;\n\n  for (const instance of queryMatches<T>(parsedQuery, from)) {\n    return instance;\n  }\n\n  return undefined;\n}\n\n/**\n * Get all instances of component with the given query.\n */\nexport function queryComponentAll<T extends Base = Base>(\n  query: string,\n  options: QueryOptions = {},\n): T[] {\n  const parsedQuery = parseQuery(query);\n  const { from = document } = options;\n\n  return Array.from(queryMatches<T>(parsedQuery, from));\n}\n\n/**\n * Get the closest component instance by traversing up the DOM tree.\n */\nexport function closestComponent<T extends Base = Base>(\n  query: string,\n  options: { from: HTMLElement } = { from: null },\n): T | undefined {\n  const { from } = options;\n  const parsedQuery = parseQuery(query);\n  let closestInstance: T | undefined;\n\n  getAncestorWhere(from, (element) => {\n    if (!element) return false;\n\n    // Use the element's __base__ map for O(1) lookup by component name\n    const baseMap = (element as BaseEl).__base__;\n    if (!baseMap) return false;\n\n    const instance = baseMap.get(parsedQuery.name) as T;\n    if (\n      instance &&\n      instance !== ('terminated' as unknown) &&\n      instanceIsMatching(instance, parsedQuery)\n    ) {\n      closestInstance = instance;\n      return true;\n    }\n\n    return false;\n  });\n\n  return closestInstance;\n}\n"],
+  "mappings": "AACA,SAAS,cAAc,mBAAmB;AAC1C,SAAS,YAAY;AACrB,SAAS,wBAAwB;AAajC,MAAM,cAAc;AAKb,MAAM,aAAa,KAAK,CAAC,UAA+B;AAC7D,QAAM,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,IAAI,MAAM,MAAM,WAAW;AAShE,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF,CAAC;AAEM,SAAS,mBAAmB,UAAgB,aAAmC;AACpF,MAAI,SAAS,QAAQ,SAAS,YAAY,KAAM,QAAO;AACvD,MAAI,YAAY,eAAe,CAAC,SAAS,IAAI,QAAQ,YAAY,WAAW,EAAG,QAAO;AAEtF,MAAI,YAAY,UAAU,aAAa,CAAC,SAAS,WAAY,QAAO;AACpE,MAAI,YAAY,UAAU,eAAe,SAAS,WAAY,QAAO;AAErE,SAAO;AACT;AAmBA,SAAS,aAA6B,SAAiB,aAAyC;AAC9F,QAAM,UAAU,QAAQ;AACxB,MAAI,CAAC,QAAS,QAAO;AAErB,QAAM,WAAW,QAAQ,IAAI,YAAY,IAAI;AAC7C,MAAI,CAAC,YAAY,aAAa,aAAc,QAAO;AACnD,MAAI,CAAC,YAAY,QAAQ,KAAK,CAAC,mBAAmB,UAAU,WAAW,EAAG,QAAO;AAEjF,SAAO;AACT;AAmBA,UAAU,aACR,aACA,MACc;AACd,MAAI,SAAS,UAAU;AACrB,eAAW,YAAY,aAAa,GAAG;AACrC,UAAI,YAAY,QAAQ,KAAK,mBAAmB,UAAU,WAAW,GAAG;AACtE,cAAM;AAAA,MACR;AAAA,IACF;AACA;AAAA,EACF;AAEA,QAAM,OAAO,oBAAI,IAAO;AAExB,QAAM,YAAY,aAAgB,MAAgB,WAAW;AAC7D,MAAI,WAAW;AACb,SAAK,IAAI,SAAS;AAClB,UAAM;AAAA,EACR;AAEA,aAAW,WAAW,KAAK,iBAA8B,GAAG,GAAG;AAC7D,UAAM,QAAQ,aAAgB,SAAmB,WAAW;AAC5D,QAAI,SAAS,CAAC,KAAK,IAAI,KAAK,GAAG;AAC7B,WAAK,IAAI,KAAK;AACd,YAAM;AAAA,IACR;AAAA,EACF;AACF;AAKO,SAAS,eACd,OACA,UAAwB,CAAC,GACV;AACf,QAAM,cAAc,WAAW,KAAK;AACpC,QAAM,EAAE,OAAO,SAAS,IAAI;AAE5B,aAAW,YAAY,aAAgB,aAAa,IAAI,GAAG;AACzD,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAKO,SAAS,kBACd,OACA,UAAwB,CAAC,GACpB;AACL,QAAM,cAAc,WAAW,KAAK;AACpC,QAAM,EAAE,OAAO,SAAS,IAAI;AAE5B,SAAO,MAAM,KAAK,aAAgB,aAAa,IAAI,CAAC;AACtD;AAKO,SAAS,iBACd,OACA,UAAiC,EAAE,MAAM,KAAK,GAC/B;AACf,QAAM,EAAE,KAAK,IAAI;AACjB,QAAM,cAAc,WAAW,KAAK;AACpC,MAAI;AAEJ,mBAAiB,MAAM,CAAC,YAAY;AAClC,QAAI,CAAC,QAAS,QAAO;AAGrB,UAAM,UAAW,QAAmB;AACpC,QAAI,CAAC,QAAS,QAAO;AAErB,UAAM,WAAW,QAAQ,IAAI,YAAY,IAAI;AAC7C,QACE,YACA,aAAc,gBACd,mBAAmB,UAAU,WAAW,GACxC;AACA,wBAAkB;AAClB,aAAO;AAAA,IACT;AAEA,WAAO;AAAA,EACT,CAAC;AAED,SAAO;AACT;",
+  "names": []
+}

package/dist/helpers/registerComponent.js

@@ -0,0 +1,30 @@
+import { isDev, isFunction } from "../utils/is.js";
+async function registerComponent(ctor, nameOrSelector) {
+  if (isFunction(ctor) && !("$isBase" in ctor)) {
+    ctor = ctor(void 0);
+  }
+  let Ctor;
+  if (ctor instanceof Promise) {
+    const module = await ctor;
+    Ctor = "$isBase" in module ? module : module.default;
+  } else {
+    Ctor = ctor;
+  }
+  const results = await Promise.allSettled(Ctor.$register(nameOrSelector));
+  return results.flatMap((result) => {
+    if (result.status === "fulfilled") {
+      return [result.value];
+    }
+    if (isDev) {
+      console.error(
+        "[registerComponent] An instance failed to mount and was skipped.",
+        result.reason
+      );
+    }
+    return [];
+  });
+}
+export {
+  registerComponent
+};
+//# sourceMappingURL=registerComponent.js.map

package/dist/helpers/registerComponent.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/helpers/registerComponent.ts"],
+  "sourcesContent": ["import { BaseAsyncConstructor, BaseConstructor } from '../Base/Base.js';\nimport { isDev, isFunction } from '../utils/is.js';\n\n/**\n * Register globally and mount a given component.\n *\n * The component can be provided in any of the forms also accepted for child\n * components in `config.components`:\n * - a `Base` constructor;\n * - a promise resolving to a constructor or a module namespace (`import(...)`);\n * - a factory function returning such a promise (`() => import(...)`).\n *\n * Instances are mounted independently: an element that fails to mount is\n * skipped (and logged in development) instead of failing the whole call, so\n * the resolved array contains every instance that mounted successfully.\n *\n * @link https://js-toolkit.studiometa.dev/api/helpers/registerComponent.html\n * @param ctor The component constructor, or a way to resolve it.\n * @param nameOrSelector The name or selector to used for this component.\n * @return A promise resolving to an array of mounted component instances.\n */\nexport async function registerComponent<T extends BaseConstructor = BaseConstructor>(\n  ctor: T | Promise<T | { default: T }> | (() => Promise<T | { default: T }>),\n  nameOrSelector?: string,\n) {\n  // Resolve factory functions such as `() => import('./Component.js')`, mirroring\n  // how lazy child components are declared. A `Base` constructor is a function too,\n  // so it is distinguished by its `$isBase` marker.\n  if (isFunction(ctor) && !('$isBase' in ctor)) {\n    ctor = (ctor as BaseAsyncConstructor)(undefined as never) as Promise<T | { default: T }>;\n  }\n\n  let Ctor: T;\n  if (ctor instanceof Promise) {\n    const module = await ctor;\n    // A resolved `Base` constructor is used as-is; only a module namespace is\n    // unwrapped. Keying on `$isBase` (like the async child resolution) avoids\n    // mistaking a user-defined static `default` member for a module namespace.\n    Ctor = ('$isBase' in module ? module : (module as { default: T }).default) as T;\n  } else {\n    Ctor = ctor;\n  }\n\n  const results = await Promise.allSettled(Ctor.$register(nameOrSelector));\n\n  return results.flatMap((result) => {\n    if (result.status === 'fulfilled') {\n      return [result.value];\n    }\n\n    if (isDev) {\n      console.error(\n        '[registerComponent] An instance failed to mount and was skipped.',\n        result.reason,\n      );\n    }\n\n    return [];\n  });\n}\n"],
+  "mappings": "AACA,SAAS,OAAO,kBAAkB;AAoBlC,eAAsB,kBACpB,MACA,gBACA;AAIA,MAAI,WAAW,IAAI,KAAK,EAAE,aAAa,OAAO;AAC5C,WAAQ,KAA8B,MAAkB;AAAA,EAC1D;AAEA,MAAI;AACJ,MAAI,gBAAgB,SAAS;AAC3B,UAAM,SAAS,MAAM;AAIrB,WAAQ,aAAa,SAAS,SAAU,OAA0B;AAAA,EACpE,OAAO;AACL,WAAO;AAAA,EACT;AAEA,QAAM,UAAU,MAAM,QAAQ,WAAW,KAAK,UAAU,cAAc,CAAC;AAEvE,SAAO,QAAQ,QAAQ,CAAC,WAAW;AACjC,QAAI,OAAO,WAAW,aAAa;AACjC,aAAO,CAAC,OAAO,KAAK;AAAA,IACtB;AAEA,QAAI,OAAO;AACT,cAAQ;AAAA,QACN;AAAA,QACA,OAAO;AAAA,MACT;AAAA,IACF;AAEA,WAAO,CAAC;AAAA,EACV,CAAC;AACH;",
+  "names": []
+}

package/dist/helpers/registerComponents.js

@@ -0,0 +1,21 @@
+import { isDev } from "../utils/is.js";
+import { registerComponent } from "./registerComponent.js";
+async function registerComponents(...ctors) {
+  const results = await Promise.allSettled(ctors.map((ctor) => registerComponent(ctor)));
+  return results.flatMap((result) => {
+    if (result.status === "fulfilled") {
+      return result.value;
+    }
+    if (isDev) {
+      console.error(
+        "[registerComponents] A component failed to register and was skipped.",
+        result.reason
+      );
+    }
+    return [];
+  });
+}
+export {
+  registerComponents
+};
+//# sourceMappingURL=registerComponents.js.map

package/dist/helpers/registerComponents.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/helpers/registerComponents.ts"],
+  "sourcesContent": ["import { BaseConstructor } from '../Base/Base.js';\nimport { isDev } from '../utils/is.js';\nimport { registerComponent } from './registerComponent.js';\n\n/**\n * Register globally and mount multiple components at once.\n *\n * Each component accepts the same forms as {@link registerComponent}: a `Base`\n * constructor, a promise resolving to a constructor or module namespace, or a\n * factory function returning such a promise.\n *\n * Components are registered independently: a single failure (e.g. a rejected\n * dynamic import) does not prevent the others from being registered, and the\n * returned array contains every instance that mounted successfully. Failures\n * are logged in development.\n *\n * @link https://js-toolkit.studiometa.dev/api/helpers/registerComponents.html\n * @param ctors The components, or ways to resolve them.\n * @return A promise resolving to a flat array of mounted component instances.\n */\nexport async function registerComponents<T extends BaseConstructor = BaseConstructor>(\n  ...ctors: (T | Promise<T | { default: T }> | (() => Promise<T | { default: T }>))[]\n) {\n  const results = await Promise.allSettled(ctors.map((ctor) => registerComponent(ctor)));\n\n  return results.flatMap((result) => {\n    if (result.status === 'fulfilled') {\n      return result.value;\n    }\n\n    if (isDev) {\n      console.error(\n        '[registerComponents] A component failed to register and was skipped.',\n        result.reason,\n      );\n    }\n\n    return [];\n  });\n}\n"],
+  "mappings": "AACA,SAAS,aAAa;AACtB,SAAS,yBAAyB;AAkBlC,eAAsB,sBACjB,OACH;AACA,QAAM,UAAU,MAAM,QAAQ,WAAW,MAAM,IAAI,CAAC,SAAS,kBAAkB,IAAI,CAAC,CAAC;AAErF,SAAO,QAAQ,QAAQ,CAAC,WAAW;AACjC,QAAI,OAAO,WAAW,aAAa;AACjC,aAAO,OAAO;AAAA,IAChB;AAEA,QAAI,OAAO;AACT,cAAQ;AAAA,QACN;AAAA,QACA,OAAO;AAAA,MACT;AAAA,IACF;AAEA,WAAO,CAAC;AAAA,EACV,CAAC;AACH;",
+  "names": []
+}