assign-gingerly 0.0.41 → 0.0.43

package/README.md

@@ -4656,6 +4656,9 @@ When the custom element's `connectedCallback` fires, the feature's `connectedCal
 | `disconnectedCallback` | Feature needs cleanup (remove listeners, abort fetches) |
 | `attributeChangedCallback` | Feature reacts to attribute changes (limited to element's `observedAttributes`) |
 | `adoptedCallback` | Feature reacts to document adoption |
+| `formDisabledCallback` | Feature reacts to disabled state changes (form-associated elements) |
+| `formResetCallback` | Feature reacts to form reset (form-associated elements) |
+| `formStateRestoreCallback` | Feature restores state after navigation/session restore (form-associated elements) |
 
 **Example: Feature that reads computed styles on connect**
 
@@ -4723,6 +4726,74 @@ customElements.assignFeatures(MyElement, {
 
 **Note on `attributeChangedCallback`:** The feature only receives callbacks for attributes listed in the element's `static observedAttributes`. Features cannot add to this list after `define()` is called.
 
+### Class-level setup with `static onAssigned`
+
+Some features need one-time class-level setup before any instances are created — for example, installing prototype getter/setters or pre-loading modules. The `static onAssigned` method on the spawn class is called by `assignFeatures` immediately after registration:
+
+```JavaScript
+class RoundaboutFeature {
+    // Called once when assignFeatures processes this feature
+    static async onAssigned(ctr, featureConfig) {
+        // One-time class-level setup: install prototype getter/setters, pre-load modules
+        await makeRoundaboutReady(ctr, featureConfig.customData);
+    }
+
+    constructor(host, ctx, initVals) {
+        // Instance-level setup (runs on first getter access)
+        const [vm, propagator] = roundaboutSync({
+            vm: host,
+            ...ctx.injection.customData,
+        });
+        this._vm = vm;
+        this._propagator = propagator;
+    }
+}
+```
+
+**Usage:**
+
+```JavaScript
+// await is safe — returns undefined if no async onAssigned hooks exist
+await customElements.assignFeatures(MyElement, {
+    roundabout: {
+        spawn: RoundaboutFeature,
+        customData: raConfig
+    }
+});
+
+// Now define — class is fully set up, connectedCallback will be synchronous
+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).
+- 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.
+
+**`await` is always safe:**
+
+```JavaScript
+// These are equivalent for sync features (no onAssigned or sync onAssigned):
+customElements.assignFeatures(MyElement, { feature: { spawn: SyncFeature } });
+await customElements.assignFeatures(MyElement, { feature: { spawn: SyncFeature } });
+// Both work — await on undefined is a no-op
+```
+
+<details>
+<summary>Catalog of Published Custom Element Features</summary>
+
+| Package | Description | Source |
+|---------|-------------|--------|
+| [truth-sourcer](https://www.npmjs.com/package/truth-sourcer) | Attribute/property binding and truth-sourcing for custom elements | [GitHub](https://github.com/bahrus/truth-sourcer) |
+| [be-reflective](https://www.npmjs.com/package/be-reflective) | CSS custom state reflection from computed styles | [GitHub](https://github.com/bahrus/be-reflective) |
+| [face-up](https://www.npmjs.com/package/face-up) | Form Associated Custom Element behavior via ElementInternals | [GitHub](https://github.com/bahrus/face-up) |
+| [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) |
+
+</details>
+
 ### Roadmap (future phases)
 
 - **Nested features**: Support `?.path?.notation` keys directly in `assignFeatures` (without requiring `PropertyBag`).

package/assignFeatures.js

@@ -305,7 +305,10 @@ const VALID_CALLBACKS = new Set([
     'connectedCallback',
     'disconnectedCallback',
     'attributeChangedCallback',
-    'adoptedCallback'
+    'adoptedCallback',
+    'formDisabledCallback',
+    'formResetCallback',
+    'formStateRestoreCallback'
 ]);
 /**
  * WeakMap tracking which callbacks have been patched on which constructors,
@@ -383,6 +386,7 @@ export function assignFeatures(ctr, features, featuresRegistry) {
     if (!supportedFeatures) {
         throw new Error(`assignFeatures: ${ctr.name || 'constructor'} does not define static supportedFeatures`);
     }
+    const onAssignedPromises = [];
     for (const key of Object.keys(features)) {
         // 1. Confirm the key is opted-in via supportedFeatures
         if (!(key in supportedFeatures)) {
@@ -411,8 +415,18 @@ export function assignFeatures(ctr, features, featuresRegistry) {
         if (allCallbacks.length > 0) {
             installCallbackForwarding(ctr, key, allCallbacks);
         }
+        // 7. Call static onAssigned if the spawn class defines it
+        const SpawnClass = featureConfig.spawn;
+        if (SpawnClass && !isAsyncSpawn(SpawnClass) &&
+            Object.hasOwn(SpawnClass, 'onAssigned') &&
+            typeof SpawnClass.onAssigned === 'function') {
+            const result = SpawnClass.onAssigned(ctr, featureConfig);
+            if (result && typeof result.then === 'function') {
+                onAssignedPromises.push(result);
+            }
+        }
     }
-    // 6. Install whenFeatureReady method if featuresConfig.lifecycleKeys is configured
+    // 8. Install whenFeatureReady method if featuresConfig.lifecycleKeys is configured
     const featuresConfig = ctr.featuresConfig;
     if (featuresConfig?.lifecycleKeys) {
         const methodName = resolveWhenFeatureReadyName(featuresConfig.lifecycleKeys);
@@ -420,6 +434,11 @@ export function assignFeatures(ctr, features, featuresRegistry) {
             installWhenFeatureReadyMethod(ctr, methodName);
         }
     }
+    // Return a Promise if any onAssigned hooks are async, otherwise undefined
+    if (onAssignedPromises.length > 0) {
+        return Promise.all(onAssignedPromises).then(() => { });
+    }
+    return undefined;
 }
 /**
  * Captures own-properties that shadow feature getters and stores them as initVals.
@@ -525,7 +544,7 @@ if (typeof CustomElementRegistry !== 'undefined') {
     });
     Object.defineProperty(CustomElementRegistry.prototype, 'assignFeatures', {
         value: function (ctr, features) {
-            assignFeatures(ctr, features, this.featuresRegistry);
+            return assignFeatures(ctr, features, this.featuresRegistry);
         },
         writable: true,
         enumerable: false,

package/assignFeatures.ts

@@ -515,7 +515,10 @@ const VALID_CALLBACKS = new Set([
     'connectedCallback',
     'disconnectedCallback',
     'attributeChangedCallback',
-    'adoptedCallback'
+    'adoptedCallback',
+    'formDisabledCallback',
+    'formResetCallback',
+    'formStateRestoreCallback'
 ]);
 
 /**
@@ -607,7 +610,7 @@ export function assignFeatures(
     ctr: Function,
     features: FeatureConfigsMap,
     featuresRegistry: FeaturesRegistry
-): void {
+): Promise<void> | undefined {
     // Validate that the constructor has static supportedFeatures
     const supportedFeatures: SupportedFeaturesMap | undefined = (ctr as any).supportedFeatures;
 
@@ -617,6 +620,8 @@ export function assignFeatures(
         );
     }
 
+    const onAssignedPromises: Promise<void>[] = [];
+
     for (const key of Object.keys(features)) {
         // 1. Confirm the key is opted-in via supportedFeatures
         if (!(key in supportedFeatures)) {
@@ -656,9 +661,20 @@ export function assignFeatures(
         if (allCallbacks.length > 0) {
             installCallbackForwarding(ctr, key, allCallbacks);
         }
+
+        // 7. Call static onAssigned if the spawn class defines it
+        const SpawnClass = featureConfig.spawn;
+        if (SpawnClass && !isAsyncSpawn(SpawnClass) && 
+            Object.hasOwn(SpawnClass as any, 'onAssigned') && 
+            typeof (SpawnClass as any).onAssigned === 'function') {
+            const result = (SpawnClass as any).onAssigned(ctr, featureConfig);
+            if (result && typeof result.then === 'function') {
+                onAssignedPromises.push(result);
+            }
+        }
     }
 
-    // 6. Install whenFeatureReady method if featuresConfig.lifecycleKeys is configured
+    // 8. Install whenFeatureReady method if featuresConfig.lifecycleKeys is configured
     const featuresConfig: FeaturesClassConfig | undefined = (ctr as any).featuresConfig;
     if (featuresConfig?.lifecycleKeys) {
         const methodName = resolveWhenFeatureReadyName(featuresConfig.lifecycleKeys);
@@ -666,6 +682,12 @@ export function assignFeatures(
             installWhenFeatureReadyMethod(ctr, methodName);
         }
     }
+
+    // Return a Promise if any onAssigned hooks are async, otherwise undefined
+    if (onAssignedPromises.length > 0) {
+        return Promise.all(onAssignedPromises).then(() => {});
+    }
+    return undefined;
 }
 
 /**
@@ -772,7 +794,7 @@ export class PropertyBag {
 declare global {
     interface CustomElementRegistry {
         featuresRegistry: FeaturesRegistry;
-        assignFeatures(ctr: Function, features: FeatureConfigsMap): void;
+        assignFeatures(ctr: Function, features: FeatureConfigsMap): Promise<void> | undefined;
     }
 }
 
@@ -793,8 +815,8 @@ if (typeof CustomElementRegistry !== 'undefined') {
     });
 
     Object.defineProperty(CustomElementRegistry.prototype, 'assignFeatures', {
-        value: function (ctr: Function, features: FeatureConfigsMap): void {
-            assignFeatures(ctr, features, this.featuresRegistry);
+        value: function (ctr: Function, features: FeatureConfigsMap): Promise<void> | undefined {
+            return assignFeatures(ctr, features, this.featuresRegistry);
         },
         writable: true,
         enumerable: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {

package/types/assign-gingerly/types.d.ts

@@ -179,13 +179,18 @@ export interface AttrConfig<T = unknown, TParserConfig = unknown> {
   //  * Defaults to true (initial read only)
   //  */
   // initialOnly?: boolean;
+
+  /**
+   * Should make sure it is added to static observedAttribrutes
+   */
+  sourceOfTruth?: boolean;
 }
 
 export type AttrPatterns<T = any> = {
   /**
    * Base prefix for attribute names
    */
-  base: string;
+  base?: string;
 
   /**
    * Configuration for the base pattern
@@ -241,18 +246,6 @@ export interface IAssignGingerlyOptions {
    * When the signal is aborted, all event listeners are automatically removed
    */
   signal?: AbortSignal;
-
-  /**
-   * List of property names that should be treated as async methods.
-   * Works together with withMethods — async methods are awaited before
-   * continuing the chain.
-   * 
-   * The path evaluation for keys containing async methods is fire-and-forget:
-   * assignGingerly remains synchronous and returns immediately.
-   * 
-   * NOTE: Interaction with @each and @eachTime is not yet implemented.
-   */
-  withAsyncMethods?: string[] | Set<string>;
 }
 
 /**
@@ -333,130 +326,3 @@ export interface ElementEnhancement{
   dispose(registryItem: EnhancementConfig | string | symbol): void;
   whenResolved(registryItem: EnhancementConfig | string | symbol, mountCtx?: any): Promise<any>;
 }
-
-/**
- * Context passed to feature spawn constructors
- */
-export interface FeatureSpawnContext {
-  /** The feature key (e.g., 'photoTaker') */
-  key: string;
-  /** The SupportedFeatureConfig from static supportedFeatures */
-  optIn: SupportedFeatureConfig;
-  /** The FeatureConfig from assignFeatures */
-  injection: FeatureConfig;
-  /** The features registry reference */
-  featuresRegistry: FeaturesRegistry;
-  /** Shared context from the host element (via getSharedContext callback) */
-  shared?: any;
-}
-
-/**
- * Configuration for a supported feature slot declared via static supportedFeatures
- */
-export interface SupportedFeatureConfig {
-  /**
-   * Optional fallback class (or async spawner) to use if no implementation is injected.
-   */
-  fallbackSpawn?: 
-    | { new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }
-    | (() => Promise<{ new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }>);
-
-  /**
-   * Optional runtime shape validation for the spawned instance.
-   * Return true if the instance is valid, false to throw.
-   */
-  validateShape?: (spawnedInstance: any) => boolean;
-
-  /**
-   * Optional callback to provide shared context (e.g., ElementInternals, private state)
-   * to the feature at construction time.
-   * 
-   * Defined in the class body, this callback has access to #private fields.
-   * The returned object is passed to the feature constructor as `ctx.shared`.
-   * 
-   * @param instance - The host element instance
-   * @returns An object containing shared data for the feature
-   */
-  getSharedContext?: (instance: any) => any;
-}
-
-/**
- * Class-level configuration for the features system.
- * Declared as `static featuresConfig` on the class.
- */
-export interface FeaturesClassConfig {
-  /**
-   * Lifecycle method configuration.
-   * 
-   * If set to `true`, installs a method named 'whenFeatureReady' on the prototype.
-   * If set to an object, allows customizing the method name.
-   * 
-   * The installed method accepts a feature key and returns a Promise that resolves
-   * with the feature instance once it's ready (useful for async spawners).
-   * For synchronous spawners, the Promise resolves immediately.
-   * 
-   * Suggested default name: 'whenFeatureReady'
-   */
-  lifecycleKeys?: true | {
-    /** Method name for awaiting feature readiness. Defaults to 'whenFeatureReady'. */
-    whenFeatureReady?: string;
-  };
-}
-
-/**
- * Configuration for a feature passed to assignFeatures.
- * The feature equivalent of EnhancementConfig.
- */
-export interface FeatureConfig {
-  /**
-   * The class to instantiate for this feature, or an async function that
-   * resolves to such a class (for lazy-loading).
-   * 
-   * Synchronous: Constructor receives the host element as its first argument,
-   * a FeatureSpawnContext as second, and optional initVals as third.
-   * 
-   * Asynchronous: A function (arrow or async) that returns a Promise resolving
-   * to a constructor. The getter returns a placeholder object immediately and
-   * instantiates the real class once the Promise resolves.
-   */
-  spawn?: 
-    | { new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }
-    | (() => Promise<{ new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }>);
-
-  /**
-   * Attribute patterns for parsing element attributes into initVals.
-   * Attributes are the "base layer" — programmatic values override them.
-   * Always unprefixed for features (no enh- prefix).
-   */
-  withAttrs?: AttrPatterns<any>;
-
-  /**
-   * Reserved field for custom configuration data.
-   * Not interpreted by the library — available to the feature class
-   * via ctx.injection.customData in the constructor.
-   */
-  customData?: any;
-}
-
-export type SupportedFeaturesMap = Record<string, SupportedFeatureConfig>;
-export type FeatureConfigsMap = Record<string, FeatureConfig>;
-
-/**
- * Registry for feature configs, keyed by constructor
- */
-export declare class FeaturesRegistry {
-  has(ctr: Function): boolean;
-  get(ctr: Function): Map<string, FeatureConfig> | undefined;
-  set(ctr: Function, key: string, config: FeatureConfig): void;
-  hasKey(ctr: Function, key: string): boolean;
-}
-
-/**
- * Core assignFeatures function.
- * Validates inputs, registers feature configs, and installs lazy getters on the class prototype.
- */
-export declare function assignFeatures(
-  ctr: Function,
-  features: FeatureConfigsMap,
-  featuresRegistry: FeaturesRegistry
-): void;