assign-gingerly 0.0.48 → 0.0.50

package/README.md

@@ -4792,11 +4792,25 @@ customElements.define('my-element', MyElement);
 **How it works:**
 
 - `assignFeatures` checks if the spawn class defines `static onAssigned` (via `Object.hasOwn`).
-- If found, calls `SpawnClass.onAssigned(ctr, featureConfig)` after installing the getter.
-- If `onAssigned` returns a Promise, `assignFeatures` returns a `Promise<void>` that resolves when all async hooks complete.
-- If no `onAssigned` hooks are async (or none exist), `assignFeatures` returns `undefined` (backward compatible — existing code that doesn't `await` still works).
+- If found, calls `SpawnClass.onAssigned(ctr, featureConfig, key)` after installing the getter.
+- If `onAssigned` returns a Promise, it is **awaited sequentially** before processing the next feature. This guarantees that features declared earlier complete their setup before later features run.
+- This sequential ordering enables inter-feature communication: Feature A can post configuration (via `suggestFeatureInfo`) that Feature B reads in its own `onAssigned`.
+- If no features have `onAssigned`, `assignFeatures` runs synchronously and returns `undefined` (backward compatible).
 - Only applies to synchronous spawners (the class must be available at registration time). Async spawners can't define `onAssigned` since the class isn't loaded yet.
 
+**Sequential ordering guarantee:**
+
+```JavaScript
+await customElements.assignFeatures(MyElement, {
+    featureA: { spawn: FeatureA },  // FeatureA.onAssigned runs first, completes
+    featureB: { spawn: FeatureB }   // FeatureB.onAssigned runs second, can read A's output
+});
+```
+
+Features are processed in declaration order. If Feature A's `onAssigned` is async, it fully completes before Feature B's `onAssigned` starts. This makes it safe for features to communicate via `suggestFeatureInfo` / `getFeatureInfoSuggestions`.
+
+For full documentation on inter-feature communication, see [docs/inter-feature-communication.md](docs/inter-feature-communication.md).
+
 **`await` is always safe:**
 
 ```JavaScript
@@ -4806,6 +4820,31 @@ await customElements.assignFeatures(MyElement, { feature: { spawn: SyncFeature }
 // Both work — await on undefined is a no-op
 ```
 
+### Declarative element definition with `defineWithFeatures`
+
+`defineWithFeatures` enables defining custom elements from JSON-serializable configuration — no class authoring needed for derived elements:
+
+```JavaScript
+import { defineWithFeatures } from 'assign-gingerly/defineWithFeatures.js';
+
+await defineWithFeatures('time-ticker', 'el-maker', {
+    assignFeatures: {
+        roundabout: {
+            customData: { template: myTemplate },
+            withAttrs: { base: 'ra', mode: '${base}-mode' },
+            callbackForwarding: ['connectedCallback']
+        },
+        truthSourcer: {
+            callbackForwarding: ['connectedCallback', 'attributeChangedCallback']
+        }
+    }
+});
+```
+
+It resolves async `fallbackSpawn` implementations from the base class, creates a subclass, wires up features, and defines the element. Designed for use with [mount-observer cede scripts](https://github.com/bahrus/mount-observer#custom-element-definition-cede-scripts) but works standalone.
+
+For full documentation, see [docs/defineWithFeatures.md](docs/defineWithFeatures.md).
+
 <details>
 <summary>Catalog of Published Custom Element Features</summary>
 

package/defineWithFeatures.js

@@ -0,0 +1,118 @@
+/**
+ * defineWithFeatures - Declaratively define a custom element with features from JSON config.
+ *
+ * Resolves async fallback spawns from the base class's `static supportedFeatures`,
+ * creates a subclass, registers features with resolved spawns + JSON config,
+ * and defines the custom element.
+ *
+ * Designed to support cede scripts and other declarative custom element definition patterns.
+ *
+ * @example
+ * await defineWithFeatures('time-ticker', 'el-maker', {
+ *     assignFeatures: {
+ *         timeTicker: {},
+ *         roundabout: {
+ *             customData: {...},
+ *             withAttrs: {...},
+ *             callbackForwarding: ['connectedCallback']
+ *         }
+ *     }
+ * });
+ */
+import { assignFeatures } from './assignFeatures.js';
+/**
+ * Determines if a function is an async spawner (same heuristic as assignFeatures).
+ */
+function isAsyncSpawn(fn) {
+    if (typeof fn !== 'function')
+        return false;
+    if (fn.constructor.name === 'AsyncFunction')
+        return true;
+    if (fn.prototype === undefined)
+        return true;
+    return false;
+}
+/**
+ * Cache for resolved fallback spawns.
+ * Key: BaseClass, Value: Map<featureKey, resolvedConstructor>
+ */
+const resolvedSpawnCache = new WeakMap();
+/**
+ * Declaratively define a custom element with features.
+ *
+ * 1. Waits for the base class to be defined (if not already).
+ * 2. Resolves all async fallback spawns from `static supportedFeatures`.
+ * 3. Creates a subclass extending the base class.
+ * 4. Calls `assignFeatures` with resolved spawns + the JSON config.
+ * 5. Defines the new custom element in the registry.
+ *
+ * @param tagName - The custom element tag name to define (e.g., 'time-ticker')
+ * @param baseTagName - The tag name of the base class to extend (e.g., 'el-maker')
+ * @param config - JSON-serializable configuration specifying which features to activate
+ * @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, options) {
+    const reg = registry || customElements;
+    // 1. Resolve base class — wait for it if not yet defined
+    let BaseClass = reg.get(baseTagName);
+    if (!BaseClass) {
+        await reg.whenDefined(baseTagName);
+        BaseClass = reg.get(baseTagName);
+    }
+    if (!BaseClass) {
+        throw new Error(`defineWithFeatures: base class "${baseTagName}" could not be resolved`);
+    }
+    const supportedFeatures = BaseClass.supportedFeatures;
+    if (!supportedFeatures) {
+        throw new Error(`defineWithFeatures: "${baseTagName}" does not define static supportedFeatures`);
+    }
+    // 2. Resolve all async fallback spawns (with caching)
+    let classCache = resolvedSpawnCache.get(BaseClass);
+    if (!classCache) {
+        classCache = new Map();
+        resolvedSpawnCache.set(BaseClass, classCache);
+    }
+    const featureKeys = Object.keys(config.assignFeatures);
+    const resolvedSpawns = new Map();
+    await Promise.all(featureKeys.map(async (key) => {
+        const optIn = supportedFeatures[key];
+        if (!optIn) {
+            throw new Error(`defineWithFeatures: feature "${key}" not found in ${baseTagName}.supportedFeatures`);
+        }
+        // Check cache first
+        if (classCache.has(key)) {
+            resolvedSpawns.set(key, classCache.get(key));
+            return;
+        }
+        let spawn = optIn.fallbackSpawn;
+        if (spawn && isAsyncSpawn(spawn)) {
+            // Resolve the async spawner
+            spawn = await spawn();
+        }
+        // Cache the resolved spawn
+        if (spawn) {
+            classCache.set(key, spawn);
+        }
+        resolvedSpawns.set(key, spawn);
+    }));
+    // 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)) {
+        featuresMap[key] = {
+            spawn: resolvedSpawns.get(key),
+            ...jsonConfig
+        };
+    }
+    // 5. assignFeatures (sequential onAssigned) + define
+    await assignFeatures(NewClass, featuresMap, reg.featuresRegistry);
+    reg.define(tagName, NewClass);
+    return NewClass;
+}

package/defineWithFeatures.ts

@@ -0,0 +1,160 @@
+/**
+ * defineWithFeatures - Declaratively define a custom element with features from JSON config.
+ * 
+ * Resolves async fallback spawns from the base class's `static supportedFeatures`,
+ * creates a subclass, registers features with resolved spawns + JSON config,
+ * and defines the custom element.
+ * 
+ * Designed to support cede scripts and other declarative custom element definition patterns.
+ * 
+ * @example
+ * await defineWithFeatures('time-ticker', 'el-maker', {
+ *     assignFeatures: {
+ *         timeTicker: {},
+ *         roundabout: {
+ *             customData: {...},
+ *             withAttrs: {...},
+ *             callbackForwarding: ['connectedCallback']
+ *         }
+ *     }
+ * });
+ */
+
+import { assignFeatures, FeatureConfigsMap, SupportedFeaturesMap } from './assignFeatures.js';
+
+/**
+ * Configuration passed to defineWithFeatures (JSON-serializable).
+ */
+export interface DefineWithFeaturesConfig {
+    assignFeatures: Record<string, {
+        customData?: any;
+        withAttrs?: any;
+        callbackForwarding?: string[];
+    }>;
+}
+
+/**
+ * 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).
+ */
+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;
+}
+
+/**
+ * Cache for resolved fallback spawns.
+ * Key: BaseClass, Value: Map<featureKey, resolvedConstructor>
+ */
+const resolvedSpawnCache = new WeakMap<Function, Map<string, any>>();
+
+/**
+ * Declaratively define a custom element with features.
+ * 
+ * 1. Waits for the base class to be defined (if not already).
+ * 2. Resolves all async fallback spawns from `static supportedFeatures`.
+ * 3. Creates a subclass extending the base class.
+ * 4. Calls `assignFeatures` with resolved spawns + the JSON config.
+ * 5. Defines the new custom element in the registry.
+ * 
+ * @param tagName - The custom element tag name to define (e.g., 'time-ticker')
+ * @param baseTagName - The tag name of the base class to extend (e.g., 'el-maker')
+ * @param config - JSON-serializable configuration specifying which features to activate
+ * @param registry - Optional custom element registry (defaults to global `customElements`)
+ * @returns The newly created and defined custom element class
+ */
+export async function defineWithFeatures(
+    tagName: string,
+    baseTagName: string,
+    config: DefineWithFeaturesConfig,
+    registry?: CustomElementRegistry,
+    options?: DefineWithFeaturesOptions
+): Promise<Function> {
+    const reg = registry || customElements;
+
+    // 1. Resolve base class — wait for it if not yet defined
+    let BaseClass = (reg as any).get(baseTagName);
+    if (!BaseClass) {
+        await (reg as any).whenDefined(baseTagName);
+        BaseClass = (reg as any).get(baseTagName);
+    }
+    if (!BaseClass) {
+        throw new Error(`defineWithFeatures: base class "${baseTagName}" could not be resolved`);
+    }
+
+    const supportedFeatures: SupportedFeaturesMap | undefined = BaseClass.supportedFeatures;
+    if (!supportedFeatures) {
+        throw new Error(
+            `defineWithFeatures: "${baseTagName}" does not define static supportedFeatures`
+        );
+    }
+
+    // 2. Resolve all async fallback spawns (with caching)
+    let classCache = resolvedSpawnCache.get(BaseClass);
+    if (!classCache) {
+        classCache = new Map();
+        resolvedSpawnCache.set(BaseClass, classCache);
+    }
+
+    const featureKeys = Object.keys(config.assignFeatures);
+    const resolvedSpawns = new Map<string, any>();
+
+    await Promise.all(featureKeys.map(async (key) => {
+        const optIn = supportedFeatures[key];
+        if (!optIn) {
+            throw new Error(
+                `defineWithFeatures: feature "${key}" not found in ${baseTagName}.supportedFeatures`
+            );
+        }
+
+        // Check cache first
+        if (classCache!.has(key)) {
+            resolvedSpawns.set(key, classCache!.get(key));
+            return;
+        }
+
+        let spawn = optIn.fallbackSpawn;
+        if (spawn && isAsyncSpawn(spawn)) {
+            // Resolve the async spawner
+            spawn = await (spawn as () => Promise<any>)();
+        }
+
+        // Cache the resolved spawn
+        if (spawn) {
+            classCache!.set(key, spawn);
+        }
+        resolvedSpawns.set(key, spawn);
+    }));
+
+    // 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)) {
+        featuresMap[key] = {
+            spawn: resolvedSpawns.get(key),
+            ...jsonConfig
+        };
+    }
+
+    // 5. assignFeatures (sequential onAssigned) + define
+    await assignFeatures(NewClass, featuresMap, (reg as any).featuresRegistry);
+    (reg as any).define(tagName, NewClass);
+
+    return NewClass;
+}

package/index.js

@@ -11,4 +11,5 @@ export { resolveValues, resolveValue } from './resolveValues.js';
 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';
 import './object-extension.js';

package/index.ts

@@ -11,4 +11,5 @@ export {resolveValues, resolveValue} from './resolveValues.js';
 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';
 import './object-extension.js';

package/package.json

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