@studiometa/js-toolkit 3.6.2 → 3.8.0

package/decorators/withGroup.d.ts

@@ -8,9 +8,32 @@ export interface WithGroupProps extends BaseProps {
 export interface WithGroupInterface extends BaseInterface {
     get $group(): Set<Base>;
 }
+/**
+ * Options for the `withGroup` decorator.
+ */
+export interface WithGroupOptions<T extends Base = Base, Scope extends object = object> {
+    /**
+     * Resolve the scope an instance belongs to. Return `undefined` to fall back
+     * to the global (unscoped) registry.
+     */
+    getScope?: (instance: T) => Scope | undefined;
+    /**
+     * Resolve the group name of an instance, optionally using its resolved scope.
+     * Defaults to `instance.$options.group`.
+     */
+    getGroup?: (instance: T, scope: Scope | undefined) => string;
+}
+/**
+ * Enumerate the scoped groups registered for a given scope.
+ *
+ * Returns the live `Map` of `${namespace}${group}` keys to their members set
+ * for the given scope, or an empty `Map` for unknown scopes. Unknown scopes are
+ * NOT registered as a side effect of reading.
+ */
+export declare function getScopedGroups(scope: object): Map<string, Set<Base>>;
 /**
  * Add group features to easily bind multiple components together.
  *
  * @link https://js-toolkit.studiometa.dev/api/decorators/withGroup.html
  */
-export declare function withGroup<S extends Base = Base>(BaseClass: typeof Base, namespace?: string): BaseDecorator<WithGroupInterface, S, WithGroupProps>;
+export declare function withGroup<S extends Base = Base, Scope extends object = object>(BaseClass: typeof Base, namespace?: string, options?: WithGroupOptions<S, Scope>): BaseDecorator<WithGroupInterface, S, WithGroupProps>;

package/decorators/withGroup.js

@@ -1,7 +1,30 @@
 function groups() {
   return globalThis.__JS_TOOLKIT_GROUPS__ ??= /* @__PURE__ */ new Map();
 }
-function withGroup(BaseClass, namespace = "") {
+const scopedGroups = /* @__PURE__ */ new WeakMap();
+function getScopedGroups(scope) {
+  return scopedGroups.get(scope) ?? /* @__PURE__ */ new Map();
+}
+function resolveGroupSet(scope, key) {
+  if (scope) {
+    let map = scopedGroups.get(scope);
+    if (!map) {
+      map = /* @__PURE__ */ new Map();
+      scopedGroups.set(scope, map);
+    }
+    let set = map.get(key);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      map.set(key, set);
+    }
+    return set;
+  }
+  const registry = groups();
+  return registry.get(key) ?? registry.set(key, /* @__PURE__ */ new Set()).get(key);
+}
+function withGroup(BaseClass, namespace = "", options = {}) {
+  const getScope = options.getScope;
+  const getGroup = options.getGroup ?? ((instance) => instance.$options.group);
   return class WithGroup extends BaseClass {
     static config = {
       ...BaseClass.config,
@@ -9,12 +32,27 @@ function withGroup(BaseClass, namespace = "") {
         group: String
       }
     };
+    /**
+     * The members set remembered at mount time, if any.
+     *
+     * @private
+     */
+    __groupSnapshot = void 0;
+    /**
+     * Resolve the members set for the current scope and group.
+     *
+     * @private
+     */
+    __resolveGroup() {
+      const scope = getScope?.(this);
+      const group = `${namespace}${getGroup(this, scope)}`;
+      return resolveGroupSet(scope, group);
+    }
     /**
      * Get the group set.
      */
     get $group() {
-      const group = `${namespace}${this.$options.group}`;
-      const instances = groups().get(group) ?? groups().set(group, /* @__PURE__ */ new Set()).get(group);
+      const instances = this.__groupSnapshot ?? this.__resolveGroup();
       for (const instance of instances) {
         if (!instance.$el.isConnected) {
           instances.delete(instance);
@@ -25,15 +63,19 @@ function withGroup(BaseClass, namespace = "") {
     constructor(element) {
       super(element);
       this.$on("mounted", () => {
-        this.$group.add(this);
+        const instances = this.$group;
+        instances.add(this);
+        this.__groupSnapshot = instances;
       });
       this.$on("destroyed", () => {
-        this.$group.delete(this);
+        this.__groupSnapshot?.delete(this);
+        this.__groupSnapshot = void 0;
       });
     }
   };
 }
 export {
+  getScopedGroups,
   withGroup
 };
 //# sourceMappingURL=withGroup.js.map

package/decorators/withGroup.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../packages/js-toolkit/decorators/withGroup.ts"],
-  "sourcesContent": ["import type { BaseDecorator, BaseInterface } from '../Base/types.js';\nimport type { Base, BaseProps, BaseConfig } from '../Base/index.js';\n\nexport interface WithGroupProps extends BaseProps {\n  $options: {\n    group: string;\n  };\n}\n\nexport interface WithGroupInterface extends BaseInterface {\n  get $group(): Set<Base>;\n}\n\n/**\n * Get global groups map.\n */\nfunction groups<T extends Base = Base>(): Map<string, Set<T>> {\n  return (globalThis.__JS_TOOLKIT_GROUPS__ ??= new Map<string, Set<T>>());\n}\n\n/**\n * Add group features to easily bind multiple components together.\n *\n * @link https://js-toolkit.studiometa.dev/api/decorators/withGroup.html\n */\nexport function withGroup<S extends Base = Base>(\n  BaseClass: typeof Base,\n  namespace = '',\n): BaseDecorator<WithGroupInterface, S, WithGroupProps> {\n  // @ts-expect-error Decorators can not be typed.\n  return class WithGroup<T extends BaseProps = BaseProps> extends BaseClass<T & WithGroupProps> {\n    static config: BaseConfig = {\n      ...BaseClass.config,\n      options: {\n        group: String,\n      },\n    };\n\n    /**\n     * Get the group set.\n     */\n    get $group() {\n      const group = `${namespace}${this.$options.group}`;\n      const instances =\n        groups<this>().get(group) ?? groups<this>().set(group, new Set()).get(group);\n\n      for (const instance of instances) {\n        if (!instance.$el.isConnected) {\n          instances.delete(instance);\n        }\n      }\n\n      return instances;\n    }\n\n    constructor(element: HTMLElement) {\n      super(element);\n\n      this.$on('mounted', () => {\n        this.$group.add(this);\n      });\n      this.$on('destroyed', () => {\n        this.$group.delete(this);\n      });\n    }\n  };\n}\n"],
-  "mappings": "AAgBA,SAAS,SAAqD;AAC5D,SAAQ,WAAW,0BAA0B,oBAAI,IAAoB;AACvE;AAOO,SAAS,UACd,WACA,YAAY,IAC0C;AAEtD,SAAO,MAAM,kBAAmD,UAA8B;AAAA,IAC5F,OAAO,SAAqB;AAAA,MAC1B,GAAG,UAAU;AAAA,MACb,SAAS;AAAA,QACP,OAAO;AAAA,MACT;AAAA,IACF;AAAA;AAAA;AAAA;AAAA,IAKA,IAAI,SAAS;AACX,YAAM,QAAQ,GAAG,SAAS,GAAG,KAAK,SAAS,KAAK;AAChD,YAAM,YACJ,OAAa,EAAE,IAAI,KAAK,KAAK,OAAa,EAAE,IAAI,OAAO,oBAAI,IAAI,CAAC,EAAE,IAAI,KAAK;AAE7E,iBAAW,YAAY,WAAW;AAChC,YAAI,CAAC,SAAS,IAAI,aAAa;AAC7B,oBAAU,OAAO,QAAQ;AAAA,QAC3B;AAAA,MACF;AAEA,aAAO;AAAA,IACT;AAAA,IAEA,YAAY,SAAsB;AAChC,YAAM,OAAO;AAEb,WAAK,IAAI,WAAW,MAAM;AACxB,aAAK,OAAO,IAAI,IAAI;AAAA,MACtB,CAAC;AACD,WAAK,IAAI,aAAa,MAAM;AAC1B,aAAK,OAAO,OAAO,IAAI;AAAA,MACzB,CAAC;AAAA,IACH;AAAA,EACF;AACF;",
+  "sourcesContent": ["import type { BaseDecorator, BaseInterface } from '../Base/types.js';\nimport type { Base, BaseProps, BaseConfig } from '../Base/index.js';\n\nexport interface WithGroupProps extends BaseProps {\n  $options: {\n    group: string;\n  };\n}\n\nexport interface WithGroupInterface extends BaseInterface {\n  get $group(): Set<Base>;\n}\n\n/**\n * Options for the `withGroup` decorator.\n */\nexport interface WithGroupOptions<T extends Base = Base, Scope extends object = object> {\n  /**\n   * Resolve the scope an instance belongs to. Return `undefined` to fall back\n   * to the global (unscoped) registry.\n   */\n  getScope?: (instance: T) => Scope | undefined;\n  /**\n   * Resolve the group name of an instance, optionally using its resolved scope.\n   * Defaults to `instance.$options.group`.\n   */\n  getGroup?: (instance: T, scope: Scope | undefined) => string;\n}\n\n/**\n * Get global groups map.\n */\nfunction groups<T extends Base = Base>(): Map<string, Set<T>> {\n  return (globalThis.__JS_TOOLKIT_GROUPS__ ??= new Map<string, Set<T>>());\n}\n\n/**\n * Scoped groups registry, keyed by scope identity. Scopes are stored in a\n * `WeakMap` so they can be garbage-collected once no longer referenced.\n */\nconst scopedGroups = new WeakMap<object, Map<string, Set<Base>>>();\n\n/**\n * Enumerate the scoped groups registered for a given scope.\n *\n * Returns the live `Map` of `${namespace}${group}` keys to their members set\n * for the given scope, or an empty `Map` for unknown scopes. Unknown scopes are\n * NOT registered as a side effect of reading.\n */\nexport function getScopedGroups(scope: object): Map<string, Set<Base>> {\n  return scopedGroups.get(scope) ?? new Map<string, Set<Base>>();\n}\n\n/**\n * Get the members set for a given `(scope, key)` pair, creating it if needed.\n * When `scope` is `undefined`, the global (unscoped) registry is used.\n */\nfunction resolveGroupSet(scope: object | undefined, key: string): Set<Base> {\n  if (scope) {\n    let map = scopedGroups.get(scope);\n    if (!map) {\n      map = new Map<string, Set<Base>>();\n      scopedGroups.set(scope, map);\n    }\n    let set = map.get(key);\n    if (!set) {\n      set = new Set<Base>();\n      map.set(key, set);\n    }\n    return set;\n  }\n\n  const registry = groups();\n  return registry.get(key) ?? registry.set(key, new Set()).get(key)!;\n}\n\n/**\n * Add group features to easily bind multiple components together.\n *\n * @link https://js-toolkit.studiometa.dev/api/decorators/withGroup.html\n */\nexport function withGroup<S extends Base = Base, Scope extends object = object>(\n  BaseClass: typeof Base,\n  namespace = '',\n  options: WithGroupOptions<S, Scope> = {},\n): BaseDecorator<WithGroupInterface, S, WithGroupProps> {\n  const getScope = options.getScope;\n  const getGroup = options.getGroup ?? ((instance: S) => instance.$options.group);\n\n  // @ts-expect-error Decorators can not be typed.\n  return class WithGroup<T extends BaseProps = BaseProps> extends BaseClass<T & WithGroupProps> {\n    static config: BaseConfig = {\n      ...BaseClass.config,\n      options: {\n        group: String,\n      },\n    };\n\n    /**\n     * The members set remembered at mount time, if any.\n     *\n     * @private\n     */\n    __groupSnapshot: Set<Base> | undefined = undefined;\n\n    /**\n     * Resolve the members set for the current scope and group.\n     *\n     * @private\n     */\n    __resolveGroup() {\n      const scope = getScope?.(this as unknown as S);\n      const group = `${namespace}${getGroup(this as unknown as S, scope)}`;\n      return resolveGroupSet(scope, group);\n    }\n\n    /**\n     * Get the group set.\n     */\n    get $group() {\n      const instances = this.__groupSnapshot ?? this.__resolveGroup();\n\n      for (const instance of instances) {\n        if (!instance.$el.isConnected) {\n          instances.delete(instance);\n        }\n      }\n\n      return instances;\n    }\n\n    constructor(element: HTMLElement) {\n      super(element);\n\n      this.$on('mounted', () => {\n        // Resolve the members set through the public `$group` getter so that\n        // subclasses overriding it keep receiving the membership writes. At this\n        // point `__groupSnapshot` is still `undefined`, so the base getter\n        // resolves fresh (identical behaviour for non-overriding classes).\n        // Remember the exact set the instance was added to so that on destroy a\n        // member is always removed from the set it joined, even if the scope or\n        // group would now resolve differently.\n        const instances = this.$group;\n        instances.add(this);\n        this.__groupSnapshot = instances;\n      });\n      this.$on('destroyed', () => {\n        this.__groupSnapshot?.delete(this);\n        this.__groupSnapshot = undefined;\n      });\n    }\n  };\n}\n"],
+  "mappings": "AAgCA,SAAS,SAAqD;AAC5D,SAAQ,WAAW,0BAA0B,oBAAI,IAAoB;AACvE;AAMA,MAAM,eAAe,oBAAI,QAAwC;AAS1D,SAAS,gBAAgB,OAAuC;AACrE,SAAO,aAAa,IAAI,KAAK,KAAK,oBAAI,IAAuB;AAC/D;AAMA,SAAS,gBAAgB,OAA2B,KAAwB;AAC1E,MAAI,OAAO;AACT,QAAI,MAAM,aAAa,IAAI,KAAK;AAChC,QAAI,CAAC,KAAK;AACR,YAAM,oBAAI,IAAuB;AACjC,mBAAa,IAAI,OAAO,GAAG;AAAA,IAC7B;AACA,QAAI,MAAM,IAAI,IAAI,GAAG;AACrB,QAAI,CAAC,KAAK;AACR,YAAM,oBAAI,IAAU;AACpB,UAAI,IAAI,KAAK,GAAG;AAAA,IAClB;AACA,WAAO;AAAA,EACT;AAEA,QAAM,WAAW,OAAO;AACxB,SAAO,SAAS,IAAI,GAAG,KAAK,SAAS,IAAI,KAAK,oBAAI,IAAI,CAAC,EAAE,IAAI,GAAG;AAClE;AAOO,SAAS,UACd,WACA,YAAY,IACZ,UAAsC,CAAC,GACe;AACtD,QAAM,WAAW,QAAQ;AACzB,QAAM,WAAW,QAAQ,aAAa,CAAC,aAAgB,SAAS,SAAS;AAGzE,SAAO,MAAM,kBAAmD,UAA8B;AAAA,IAC5F,OAAO,SAAqB;AAAA,MAC1B,GAAG,UAAU;AAAA,MACb,SAAS;AAAA,QACP,OAAO;AAAA,MACT;AAAA,IACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOA,kBAAyC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAOzC,iBAAiB;AACf,YAAM,QAAQ,WAAW,IAAoB;AAC7C,YAAM,QAAQ,GAAG,SAAS,GAAG,SAAS,MAAsB,KAAK,CAAC;AAClE,aAAO,gBAAgB,OAAO,KAAK;AAAA,IACrC;AAAA;AAAA;AAAA;AAAA,IAKA,IAAI,SAAS;AACX,YAAM,YAAY,KAAK,mBAAmB,KAAK,eAAe;AAE9D,iBAAW,YAAY,WAAW;AAChC,YAAI,CAAC,SAAS,IAAI,aAAa;AAC7B,oBAAU,OAAO,QAAQ;AAAA,QAC3B;AAAA,MACF;AAEA,aAAO;AAAA,IACT;AAAA,IAEA,YAAY,SAAsB;AAChC,YAAM,OAAO;AAEb,WAAK,IAAI,WAAW,MAAM;AAQxB,cAAM,YAAY,KAAK;AACvB,kBAAU,IAAI,IAAI;AAClB,aAAK,kBAAkB;AAAA,MACzB,CAAC;AACD,WAAK,IAAI,aAAa,MAAM;AAC1B,aAAK,iBAAiB,OAAO,IAAI;AACjC,aAAK,kBAAkB;AAAA,MACzB,CAAC;AAAA,IACH;AAAA,EACF;AACF;",
   "names": []
 }

package/helpers/index.d.ts

@@ -10,4 +10,5 @@ export * from './importWhenPrefersMotion.js';
 export * from './importWhenVisible.js';
 export * from './logTree.js';
 export * from './registerComponent.js';
+export * from './registerComponents.js';
 export { type QueryOptions, queryComponent, queryComponentAll, closestComponent, } from './queryComponent.js';

package/helpers/index.js

@@ -10,6 +10,7 @@ export * from "./importWhenPrefersMotion.js";
 export * from "./importWhenVisible.js";
 export * from "./logTree.js";
 export * from "./registerComponent.js";
+export * from "./registerComponents.js";
 import {
   queryComponent,
   queryComponentAll,

package/helpers/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../packages/js-toolkit/helpers/index.ts"],
-  "sourcesContent": ["export * from './createApp.js';\nexport * from './defineFeatures.js';\nexport * from './getClosestParent.js';\nexport * from './getDirectChildren.js';\nexport * from './getInstanceFromElement.js';\nexport * from './importOnInteraction.js';\nexport * from './importOnMediaQuery.js';\nexport * from './importWhenIdle.js';\nexport * from './importWhenPrefersMotion.js';\nexport * from './importWhenVisible.js';\nexport * from './logTree.js';\nexport * from './registerComponent.js';\nexport {\n  type QueryOptions,\n  queryComponent,\n  queryComponentAll,\n  closestComponent,\n} from './queryComponent.js';\n"],
-  "mappings": "AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd;AAAA,EAEE;AAAA,EACA;AAAA,EACA;AAAA,OACK;",
+  "sourcesContent": ["export * from './createApp.js';\nexport * from './defineFeatures.js';\nexport * from './getClosestParent.js';\nexport * from './getDirectChildren.js';\nexport * from './getInstanceFromElement.js';\nexport * from './importOnInteraction.js';\nexport * from './importOnMediaQuery.js';\nexport * from './importWhenIdle.js';\nexport * from './importWhenPrefersMotion.js';\nexport * from './importWhenVisible.js';\nexport * from './logTree.js';\nexport * from './registerComponent.js';\nexport * from './registerComponents.js';\nexport {\n  type QueryOptions,\n  queryComponent,\n  queryComponentAll,\n  closestComponent,\n} from './queryComponent.js';\n"],
+  "mappings": "AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd;AAAA,EAEE;AAAA,EACA;AAAA,EACA;AAAA,OACK;",
   "names": []
 }

package/helpers/registerComponent.d.ts

@@ -1,10 +1,24 @@
 import { BaseConstructor } from '../Base/Base.js';
 /**
- * Register globally and mount a given component, or a promise resolving to a component.
+ * Register globally and mount a given component.
+ *
+ * The component can be provided in any of the forms also accepted for child
+ * components in `config.components`:
+ * - a `Base` constructor;
+ * - a promise resolving to a constructor or a module namespace (`import(...)`);
+ * - a factory function returning such a promise (`() => import(...)`).
+ *
+ * Instances are mounted independently: an element that fails to mount is
+ * skipped (and logged in development) instead of failing the whole call, so
+ * the resolved array contains every instance that mounted successfully.
  *
  * @link https://js-toolkit.studiometa.dev/api/helpers/registerComponent.html
- * @param ctor The component constructor or a promise resolving to it.
+ * @param ctor The component constructor, or a way to resolve it.
  * @param nameOrSelector The name or selector to used for this component.
  * @return A promise resolving to an array of mounted component instances.
  */
-export declare function registerComponent<T extends BaseConstructor = BaseConstructor>(ctor: T | Promise<T>, nameOrSelector?: string): Promise<Awaited<InstanceType<T>>[]>;
+export declare function registerComponent<T extends BaseConstructor = BaseConstructor>(ctor: T | Promise<T | {
+    default: T;
+}> | (() => Promise<T | {
+    default: T;
+}>), nameOrSelector?: string): Promise<Awaited<InstanceType<T>>[]>;

package/helpers/registerComponent.js

@@ -1,9 +1,28 @@
+import { isDev, isFunction } from "../utils/index.js";
 async function registerComponent(ctor, nameOrSelector) {
+  if (isFunction(ctor) && !("$isBase" in ctor)) {
+    ctor = ctor(void 0);
+  }
+  let Ctor;
   if (ctor instanceof Promise) {
-    ctor = await ctor;
+    const module = await ctor;
+    Ctor = "$isBase" in module ? module : module.default;
+  } else {
+    Ctor = ctor;
   }
-  const instances = await Promise.all(ctor.$register(nameOrSelector));
-  return instances;
+  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

package/helpers/registerComponent.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../packages/js-toolkit/helpers/registerComponent.ts"],
-  "sourcesContent": ["import { BaseConstructor } from '../Base/Base.js';\n\n/**\n * Register globally and mount a given component, or a promise resolving to a component.\n *\n * @link https://js-toolkit.studiometa.dev/api/helpers/registerComponent.html\n * @param ctor The component constructor or a promise resolving to 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>,\n  nameOrSelector?: string,\n) {\n  if (ctor instanceof Promise) {\n    ctor = await ctor;\n  }\n\n  const instances = await Promise.all(ctor.$register(nameOrSelector));\n  return instances;\n}\n"],
-  "mappings": "AAUA,eAAsB,kBACpB,MACA,gBACA;AACA,MAAI,gBAAgB,SAAS;AAC3B,WAAO,MAAM;AAAA,EACf;AAEA,QAAM,YAAY,MAAM,QAAQ,IAAI,KAAK,UAAU,cAAc,CAAC;AAClE,SAAO;AACT;",
+  "sourcesContent": ["import { BaseConstructor, BaseAsyncConstructor } from '../Base/Base.js';\nimport { isDev, isFunction } from '../utils/index.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/helpers/registerComponents.d.ts

@@ -0,0 +1,22 @@
+import { BaseConstructor } from '../Base/Base.js';
+/**
+ * Register globally and mount multiple components at once.
+ *
+ * Each component accepts the same forms as {@link registerComponent}: a `Base`
+ * constructor, a promise resolving to a constructor or module namespace, or a
+ * factory function returning such a promise.
+ *
+ * Components are registered independently: a single failure (e.g. a rejected
+ * dynamic import) does not prevent the others from being registered, and the
+ * returned array contains every instance that mounted successfully. Failures
+ * are logged in development.
+ *
+ * @link https://js-toolkit.studiometa.dev/api/helpers/registerComponents.html
+ * @param ctors The components, or ways to resolve them.
+ * @return A promise resolving to a flat array of mounted component instances.
+ */
+export declare function registerComponents<T extends BaseConstructor = BaseConstructor>(...ctors: (T | Promise<T | {
+    default: T;
+}> | (() => Promise<T | {
+    default: T;
+}>))[]): Promise<Awaited<InstanceType<T>>[]>;

package/helpers/registerComponents.js

@@ -0,0 +1,21 @@
+import { isDev } from "../utils/index.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/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/index.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": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studiometa/js-toolkit",
-  "version": "3.6.2",
+  "version": "3.8.0",
   "description": "A set of useful little bits of JavaScript to boost your project! 🚀",
   "publishConfig": {
     "access": "public"

package/utils/math/fold.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Fold a value back and forth in the min and max range.
+ * @link https://js-toolkit.studiometa.dev/utils/math/fold.html
+ */
+export declare function fold(value: number, min: number, max: number): number;

package/utils/math/fold.js

@@ -0,0 +1,14 @@
+import { wrap } from "./wrap.js";
+function fold(value, min, max) {
+  const range = max - min;
+  if (!Number.isFinite(range) || range <= 0) {
+    return min;
+  }
+  const cycle = range * 2;
+  const wrapped = wrap(value, min, min + cycle);
+  return wrapped > max ? 2 * max - wrapped : wrapped;
+}
+export {
+  fold
+};
+//# sourceMappingURL=fold.js.map

package/utils/math/fold.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../packages/js-toolkit/utils/math/fold.ts"],
+  "sourcesContent": ["import { wrap } from './wrap.js';\n\n/**\n * Fold a value back and forth in the min and max range.\n * @link https://js-toolkit.studiometa.dev/utils/math/fold.html\n */\nexport function fold(value: number, min: number, max: number): number {\n  const range = max - min;\n\n  if (!Number.isFinite(range) || range <= 0) {\n    return min;\n  }\n\n  const cycle = range * 2;\n  const wrapped = wrap(value, min, min + cycle);\n\n  return wrapped > max ? 2 * max - wrapped : wrapped;\n}\n"],
+  "mappings": "AAAA,SAAS,YAAY;AAMd,SAAS,KAAK,OAAe,KAAa,KAAqB;AACpE,QAAM,QAAQ,MAAM;AAEpB,MAAI,CAAC,OAAO,SAAS,KAAK,KAAK,SAAS,GAAG;AACzC,WAAO;AAAA,EACT;AAEA,QAAM,QAAQ,QAAQ;AACtB,QAAM,UAAU,KAAK,OAAO,KAAK,MAAM,KAAK;AAE5C,SAAO,UAAU,MAAM,IAAI,MAAM,UAAU;AAC7C;",
+  "names": []
+}

package/utils/math/index.d.ts

@@ -5,6 +5,7 @@ export { createRange } from './createRange.js';
 export { clamp } from './clamp.js';
 export { clamp01 } from './clamp01.js';
 export { damp } from './damp.js';
+export { fold } from './fold.js';
 export { spring } from './spring.js';
 export { inertiaFinalValue } from './inertiaFinalValue.js';
 export { lerp } from './lerp.js';

package/utils/math/index.js

@@ -5,6 +5,7 @@ import { createRange } from "./createRange.js";
 import { clamp } from "./clamp.js";
 import { clamp01 } from "./clamp01.js";
 import { damp } from "./damp.js";
+import { fold } from "./fold.js";
 import { spring } from "./spring.js";
 import { inertiaFinalValue } from "./inertiaFinalValue.js";
 import { lerp } from "./lerp.js";
@@ -19,6 +20,7 @@ export {
   createRange,
   damp,
   ease,
+  fold,
   inertiaFinalValue,
   lerp,
   map,

package/utils/math/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../packages/js-toolkit/utils/math/index.ts"],
-  "sourcesContent": ["export * as ease from './ease.js';\nexport * from './createEases.js';\nexport * from './ease.js';\nexport { createRange } from './createRange.js';\nexport { clamp } from './clamp.js';\nexport { clamp01 } from './clamp01.js';\nexport { damp } from './damp.js';\nexport { spring } from './spring.js';\nexport { inertiaFinalValue } from './inertiaFinalValue.js';\nexport { lerp } from './lerp.js';\nexport { map } from './map.js';\nexport { round } from './round.js';\nexport { mean } from './mean.js';\nexport { smoothTo } from './smoothTo.js';\nexport { wrap } from './wrap.js';\n"],
-  "mappings": "AAAA,YAAY,UAAU;AACtB,cAAc;AACd,cAAc;AACd,SAAS,mBAAmB;AAC5B,SAAS,aAAa;AACtB,SAAS,eAAe;AACxB,SAAS,YAAY;AACrB,SAAS,cAAc;AACvB,SAAS,yBAAyB;AAClC,SAAS,YAAY;AACrB,SAAS,WAAW;AACpB,SAAS,aAAa;AACtB,SAAS,YAAY;AACrB,SAAS,gBAAgB;AACzB,SAAS,YAAY;",
+  "sourcesContent": ["export * as ease from './ease.js';\nexport * from './createEases.js';\nexport * from './ease.js';\nexport { createRange } from './createRange.js';\nexport { clamp } from './clamp.js';\nexport { clamp01 } from './clamp01.js';\nexport { damp } from './damp.js';\nexport { fold } from './fold.js';\nexport { spring } from './spring.js';\nexport { inertiaFinalValue } from './inertiaFinalValue.js';\nexport { lerp } from './lerp.js';\nexport { map } from './map.js';\nexport { round } from './round.js';\nexport { mean } from './mean.js';\nexport { smoothTo } from './smoothTo.js';\nexport { wrap } from './wrap.js';\n"],
+  "mappings": "AAAA,YAAY,UAAU;AACtB,cAAc;AACd,cAAc;AACd,SAAS,mBAAmB;AAC5B,SAAS,aAAa;AACtB,SAAS,eAAe;AACxB,SAAS,YAAY;AACrB,SAAS,YAAY;AACrB,SAAS,cAAc;AACvB,SAAS,yBAAyB;AAClC,SAAS,YAAY;AACrB,SAAS,WAAW;AACpB,SAAS,aAAa;AACtB,SAAS,YAAY;AACrB,SAAS,gBAAgB;AACzB,SAAS,YAAY;",
   "names": []
 }

package/utils/math/wrap.js

@@ -1,5 +1,8 @@
 function wrap(value, min, max) {
   const range = max - min;
+  if (!Number.isFinite(range)) {
+    return value;
+  }
   return min === max ? min : (range + (value - min) % range) % range + min;
 }
 export {

package/utils/math/wrap.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../packages/js-toolkit/utils/math/wrap.ts"],
-  "sourcesContent": ["/**\n * Wrap a value in the min and max range.\n * @link https://js-toolkit.studiometa.dev/utils/math/wrap.html\n */\nexport function wrap(value: number, min: number, max: number): number {\n  const range = max - min;\n  return min === max ? min : ((range + ((value - min) % range)) % range) + min;\n}\n"],
-  "mappings": "AAIO,SAAS,KAAK,OAAe,KAAa,KAAqB;AACpE,QAAM,QAAQ,MAAM;AACpB,SAAO,QAAQ,MAAM,OAAQ,SAAU,QAAQ,OAAO,SAAU,QAAS;AAC3E;",
+  "sourcesContent": ["/**\n * Wrap a value in the min and max range.\n * @link https://js-toolkit.studiometa.dev/utils/math/wrap.html\n */\nexport function wrap(value: number, min: number, max: number): number {\n  const range = max - min;\n\n  if (!Number.isFinite(range)) {\n    return value;\n  }\n\n  return min === max ? min : ((range + ((value - min) % range)) % range) + min;\n}\n"],
+  "mappings": "AAIO,SAAS,KAAK,OAAe,KAAa,KAAqB;AACpE,QAAM,QAAQ,MAAM;AAEpB,MAAI,CAAC,OAAO,SAAS,KAAK,GAAG;AAC3B,WAAO;AAAA,EACT;AAEA,SAAO,QAAQ,MAAM,OAAQ,SAAU,QAAQ,OAAO,SAAU,QAAS;AAC3E;",
   "names": []
 }