assign-gingerly 0.0.49 → 0.0.51

package/README.md

@@ -4855,6 +4855,7 @@ For full documentation, see [docs/defineWithFeatures.md](docs/defineWithFeatures
 | [face-up](https://www.npmjs.com/package/face-up) | Form Associated Custom Element behavior via ElementInternals | [GitHub](https://github.com/bahrus/face-up) |
 | [roundabout](https://www.npmjs.com/package/roundabout) | Reactive view-model binding with template rendering and computed property orchestration | [GitHub](https://github.com/bahrus/roundabout#using-roundaboutfeature-with-assignfeatures) |
 | [time-ticker](https://www.npmjs.com/package/time-ticker) | Web component that fires events periodically (example of a feature-based component with no code in the class) | [GitHub](https://github.com/bahrus/time-ticker) |
+| [templ-maker](https://www.npmjs.com/package/templ-maker) | Extracts a DOM fragment into a reusable template and clones it per instance (works with cede scripts) | [GitHub](https://github.com/bahrus/templ-maker) |
 
 </details>
 

package/defineWithFeatures.js

@@ -52,7 +52,7 @@ const resolvedSpawnCache = new WeakMap();
  * @param registry - Optional custom element registry (defaults to global `customElements`)
  * @returns The newly created and defined custom element class
  */
-export async function defineWithFeatures(tagName, baseTagName, config, registry) {
+export async function defineWithFeatures(tagName, baseTagName, config, registry, options) {
     const reg = registry || customElements;
     // 1. Resolve base class — wait for it if not yet defined
     let BaseClass = reg.get(baseTagName);
@@ -99,6 +99,10 @@ export async function defineWithFeatures(tagName, baseTagName, config, registry)
     // 3. Create subclass
     const NewClass = class extends BaseClass {
     };
+    // 3b. Call onSubclassCreated callback (before define, before features if needed)
+    if (options?.onSubclassCreated) {
+        options.onSubclassCreated(NewClass);
+    }
     // 4. Build FeatureConfigsMap: resolved spawns + JSON config
     const featuresMap = {};
     for (const [key, jsonConfig] of Object.entries(config.assignFeatures)) {

package/defineWithFeatures.ts

@@ -33,6 +33,14 @@ export interface DefineWithFeaturesConfig {
     }>;
 }
 
+/**
+ * Options for defineWithFeatures.
+ */
+export interface DefineWithFeaturesOptions {
+    /** Called after the subclass is created but before registry.define(). */
+    onSubclassCreated?: (NewCtr: Function) => void;
+}
+
 /**
  * Determines if a function is an async spawner (same heuristic as assignFeatures).
  */
@@ -68,7 +76,8 @@ export async function defineWithFeatures(
     tagName: string,
     baseTagName: string,
     config: DefineWithFeaturesConfig,
-    registry?: CustomElementRegistry
+    registry?: CustomElementRegistry,
+    options?: DefineWithFeaturesOptions
 ): Promise<Function> {
     const reg = registry || customElements;
 
@@ -129,6 +138,11 @@ export async function defineWithFeatures(
     // 3. Create subclass
     const NewClass = class extends (BaseClass as any) {};
 
+    // 3b. Call onSubclassCreated callback (before define, before features if needed)
+    if (options?.onSubclassCreated) {
+        options.onSubclassCreated(NewClass);
+    }
+
     // 4. Build FeatureConfigsMap: resolved spawns + JSON config
     const featuresMap: FeatureConfigsMap = {};
     for (const [key, jsonConfig] of Object.entries(config.assignFeatures)) {

package/index.js

@@ -12,4 +12,5 @@ export { assignFrom } from './assignFrom.js';
 export { assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag, suggestFeatureInfo, getFeatureInfoSuggestions } from './assignFeatures.js';
 export { installForwarding } from './installForwarding.js';
 export { defineWithFeatures } from './defineWithFeatures.js';
+export { resolveAndAssignFeatures } from './resolveAndAssignFeatures.js';
 import './object-extension.js';

package/index.ts

@@ -12,4 +12,5 @@ export {assignFrom} from './assignFrom.js';
 export {assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag, suggestFeatureInfo, getFeatureInfoSuggestions} from './assignFeatures.js';
 export {installForwarding} from './installForwarding.js';
 export {defineWithFeatures} from './defineWithFeatures.js';
+export {resolveAndAssignFeatures} from './resolveAndAssignFeatures.js';
 import './object-extension.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.49",
+  "version": "0.0.51",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -68,6 +68,10 @@
       "default": "./defineWithFeatures.js",
       "types": "./defineWithFeatures.ts"
     },
+    "./resolveAndAssignFeatures.js": {
+      "default": "./resolveAndAssignFeatures.js",
+      "types": "./resolveAndAssignFeatures.ts"
+    },
     "./assignFrom.js": {
       "default": "./assignFrom.js",
       "types": "./assignFrom.ts"

package/resolveAndAssignFeatures.js

@@ -0,0 +1,67 @@
+/**
+ * resolveAndAssignFeatures - Resolves async fallback spawns then calls assignFeatures.
+ *
+ * For each feature in the config that doesn't have an explicit `spawn`, resolves
+ * the async `fallbackSpawn` from the class's `static supportedFeatures` and sets
+ * it as the spawn. Then calls `assignFeatures` with the fully resolved config.
+ *
+ * This eliminates the boilerplate of manually resolving async spawns before
+ * calling assignFeatures.
+ *
+ * @example
+ * import { resolveAndAssignFeatures } from 'assign-gingerly/resolveAndAssignFeatures.js';
+ *
+ * await resolveAndAssignFeatures(MyElement, {
+ *     roundabout: {
+ *         customData: {...},
+ *         withAttrs: {...},
+ *         callbackForwarding: ['connectedCallback']
+ *     },
+ *     faceUp: {
+ *         callbackForwarding: ['connectedCallback', 'disconnectedCallback']
+ *     }
+ * });
+ */
+/**
+ * Determines if a function is an async spawner.
+ */
+function isAsyncSpawn(fn) {
+    if (typeof fn !== 'function')
+        return false;
+    if (fn.constructor.name === 'AsyncFunction')
+        return true;
+    if (fn.prototype === undefined)
+        return true;
+    return false;
+}
+/**
+ * Resolves async fallback spawns for features that don't have an explicit spawn,
+ * then calls assignFeatures on the registry.
+ *
+ * @param ElementClass - The custom element class (must have static supportedFeatures)
+ * @param featuresConfig - Feature configurations (spawn will be resolved from fallbackSpawn if missing)
+ * @param registry - Optional CustomElementRegistry (defaults to global customElements)
+ */
+export async function resolveAndAssignFeatures(ElementClass, featuresConfig, registry) {
+    const supportedFeatures = ElementClass.supportedFeatures;
+    if (!supportedFeatures) {
+        throw new Error(`resolveAndAssignFeatures: ${ElementClass.name || 'constructor'} does not define static supportedFeatures`);
+    }
+    // Resolve async fallback spawns in parallel for features without explicit spawn
+    await Promise.all(Object.entries(featuresConfig).map(async ([key, featureConfig]) => {
+        // Skip if spawn is already provided
+        if (featureConfig.spawn)
+            return;
+        const optIn = supportedFeatures[key];
+        if (!optIn?.fallbackSpawn)
+            return;
+        let spawn = optIn.fallbackSpawn;
+        if (isAsyncSpawn(spawn)) {
+            spawn = await spawn();
+        }
+        featureConfig.spawn = spawn;
+    }));
+    // Call assignFeatures on the registry
+    const reg = registry || customElements;
+    await reg.assignFeatures(ElementClass, featuresConfig);
+}

package/resolveAndAssignFeatures.ts

@@ -0,0 +1,79 @@
+/**
+ * resolveAndAssignFeatures - Resolves async fallback spawns then calls assignFeatures.
+ * 
+ * For each feature in the config that doesn't have an explicit `spawn`, resolves
+ * the async `fallbackSpawn` from the class's `static supportedFeatures` and sets
+ * it as the spawn. Then calls `assignFeatures` with the fully resolved config.
+ * 
+ * This eliminates the boilerplate of manually resolving async spawns before
+ * calling assignFeatures.
+ * 
+ * @example
+ * import { resolveAndAssignFeatures } from 'assign-gingerly/resolveAndAssignFeatures.js';
+ * 
+ * await resolveAndAssignFeatures(MyElement, {
+ *     roundabout: {
+ *         customData: {...},
+ *         withAttrs: {...},
+ *         callbackForwarding: ['connectedCallback']
+ *     },
+ *     faceUp: {
+ *         callbackForwarding: ['connectedCallback', 'disconnectedCallback']
+ *     }
+ * });
+ */
+
+import { FeatureConfigsMap, SupportedFeaturesMap } from './types/assign-gingerly/types.js';
+
+/**
+ * Determines if a function is an async spawner.
+ */
+function isAsyncSpawn(fn: any): boolean {
+    if (typeof fn !== 'function') return false;
+    if (fn.constructor.name === 'AsyncFunction') return true;
+    if (fn.prototype === undefined) return true;
+    return false;
+}
+
+/**
+ * Resolves async fallback spawns for features that don't have an explicit spawn,
+ * then calls assignFeatures on the registry.
+ * 
+ * @param ElementClass - The custom element class (must have static supportedFeatures)
+ * @param featuresConfig - Feature configurations (spawn will be resolved from fallbackSpawn if missing)
+ * @param registry - Optional CustomElementRegistry (defaults to global customElements)
+ */
+export async function resolveAndAssignFeatures(
+    ElementClass: Function,
+    featuresConfig: FeatureConfigsMap,
+    registry?: any
+): Promise<void> {
+    const supportedFeatures: SupportedFeaturesMap | undefined = (ElementClass as any).supportedFeatures;
+
+    if (!supportedFeatures) {
+        throw new Error(
+            `resolveAndAssignFeatures: ${(ElementClass as any).name || 'constructor'} does not define static supportedFeatures`
+        );
+    }
+
+    // Resolve async fallback spawns in parallel for features without explicit spawn
+    await Promise.all(
+        Object.entries(featuresConfig).map(async ([key, featureConfig]) => {
+            // Skip if spawn is already provided
+            if (featureConfig.spawn) return;
+
+            const optIn = supportedFeatures[key];
+            if (!optIn?.fallbackSpawn) return;
+
+            let spawn = optIn.fallbackSpawn;
+            if (isAsyncSpawn(spawn)) {
+                spawn = await (spawn as () => Promise<any>)();
+            }
+            (featureConfig as any).spawn = spawn;
+        })
+    );
+
+    // Call assignFeatures on the registry
+    const reg = registry || customElements;
+    await reg.assignFeatures(ElementClass, featuresConfig);
+}