assign-gingerly 0.0.45 → 0.0.46

package/assignFeatures.js

@@ -420,7 +420,7 @@ export function assignFeatures(ctr, features, featuresRegistry) {
         if (SpawnClass && !isAsyncSpawn(SpawnClass) &&
             Object.hasOwn(SpawnClass, 'onAssigned') &&
             typeof SpawnClass.onAssigned === 'function') {
-            const result = SpawnClass.onAssigned(ctr, featureConfig);
+            const result = SpawnClass.onAssigned(ctr, featureConfig, key);
             if (result && typeof result.then === 'function') {
                 onAssignedPromises.push(result);
             }

package/assignFeatures.ts

@@ -10,159 +10,9 @@
  */
 
 import { parseWithAttrs } from './parseWithAttrs.js';
+import { FeatureSpawnContext, SupportedFeatureConfig, FeaturesClassConfig, FeatureConfig, SupportedFeaturesMap, FeatureConfigsMap } from './types/assign-gingerly/types.js';
 
-/**
- * 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;
-}
-
-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
-     * because static methods/properties of a class can access private fields
-     * of instances of that class.
-     * 
-     * 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
-     * 
-     * @example
-     * static supportedFeatures = {
-     *     ariaManager: {
-     *         fallbackSpawn: AriaManagerImpl,
-     *         getSharedContext(instance) {
-     *             return { internals: instance.#internals };
-     *         }
-     *     }
-     * }
-     */
-    getSharedContext?: (instance: any) => any;
-
-    /**
-     * Lifecycle callbacks that this feature requires.
-     * Serves as the default — the consumer can add more via FeatureConfig.callbackForwarding
-     * but cannot remove these.
-     * 
-     * Supported: 'connectedCallback', 'disconnectedCallback',
-     *            'attributeChangedCallback', 'adoptedCallback'
-     */
-    callbackForwarding?: string[];
-}
-
-/**
- * Class-level configuration for the features system.
- * Declared as `static featuresConfig` on the class.
- * 
- * @example
- * class ClubMember extends HTMLElement {
- *     static supportedFeatures = { photoTaker: { fallbackSpawn: PhotoTakerImpl } }
- *     static featuresConfig = { lifecycleKeys: true }
- * }
- */
-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'
-     * 
-     * @example
-     * static featuresConfig = { lifecycleKeys: true }
-     * // await el.whenFeatureReady('photoTaker')
-     * 
-     * @example
-     * static featuresConfig = { lifecycleKeys: { whenFeatureReady: 'awaitFeature' } }
-     * // await el.awaitFeature('photoTaker')
-     */
-    lifecycleKeys?: true | {
-        /** Method name for awaiting feature readiness. Defaults to 'whenFeatureReady'. */
-        whenFeatureReady?: string;
-    };
-}
-
-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?: any; // AttrPatterns<any> — imported type from types
-
-    /**
-     * 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;
-
-    /**
-     * Custom element lifecycle callbacks to forward to this feature.
-     * The feature class must implement the listed methods.
-     * 
-     * On first `connectedCallback` forwarding, the getter is triggered (spawning
-     * the feature if needed). For async features, forwarding is skipped until
-     * the real instance is available.
-     * 
-     * Supported values: 'connectedCallback', 'disconnectedCallback',
-     *                   'attributeChangedCallback', 'adoptedCallback'
-     * 
-     * Note: `attributeChangedCallback` only receives events for attributes
-     * listed in the element's `static observedAttributes`.
-     */
-    callbackForwarding?: string[];
-}
-
-export type SupportedFeaturesMap = Record<string, SupportedFeatureConfig>;
-export type FeatureConfigsMap = Record<string, FeatureConfig>;
+export type { FeatureSpawnContext, SupportedFeatureConfig, FeaturesClassConfig, FeatureConfig, SupportedFeaturesMap, FeatureConfigsMap };
 
 /**
  * WeakMap storing per-instance feature caches.
@@ -667,7 +517,7 @@ export function assignFeatures(
         if (SpawnClass && !isAsyncSpawn(SpawnClass) && 
             Object.hasOwn(SpawnClass as any, 'onAssigned') && 
             typeof (SpawnClass as any).onAssigned === 'function') {
-            const result = (SpawnClass as any).onAssigned(ctr, featureConfig);
+            const result = (SpawnClass as any).onAssigned(ctr, featureConfig, key);
             if (result && typeof result.then === 'function') {
                 onAssignedPromises.push(result);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.45",
+  "version": "0.0.46",
   "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

@@ -326,3 +326,151 @@ export interface ElementEnhancement{
   dispose(registryItem: EnhancementConfig | string | symbol): void;
   whenResolved(registryItem: EnhancementConfig | string | symbol, mountCtx?: any): Promise<any>;
 }
+
+// =============================================================================
+// Custom Element Features types
+// =============================================================================
+
+/**
+ * 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.
+     */
+    getSharedContext?: (instance: any) => any;
+
+    /**
+     * Lifecycle callbacks that this feature requires.
+     * Serves as the default — the consumer can add more via FeatureConfig.callbackForwarding.
+     */
+    callbackForwarding?: string[];
+}
+
+/**
+ * Class-level configuration for the features system.
+ * Declared as `static featuresConfig` on the class.
+ */
+export interface FeaturesClassConfig {
+    /**
+     * Lifecycle method configuration.
+     * true = install 'whenFeatureReady' method.
+     * Object = custom method name.
+     */
+    lifecycleKeys?: true | {
+        whenFeatureReady?: string;
+    };
+}
+
+/**
+ * Configuration for a feature passed to assignFeatures.
+ */
+export interface FeatureConfig {
+    /**
+     * The class to instantiate, or an async function returning one.
+     */
+    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. */
+    withAttrs?: AttrPatterns<any>;
+
+    /** Pass-through custom configuration data (accessible via ctx.injection.customData). */
+    customData?: any;
+
+    /** Lifecycle callbacks to forward to this feature. */
+    callbackForwarding?: string[];
+}
+
+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;
+}
+
+/**
+ * A suggestion from one feature to another.
+ */
+export interface FeatureInfoSuggestion {
+    from: Function;
+    withAttrs?: any;
+    customData?: any;
+}
+
+/**
+ * Core assignFeatures function.
+ */
+export declare function assignFeatures(
+    ctr: Function,
+    features: FeatureConfigsMap,
+    featuresRegistry: FeaturesRegistry
+): Promise<void> | undefined;
+
+/**
+ * Captures own-properties that shadow feature getters.
+ */
+export declare function captureFeatureInitVals(instance: any): void;
+
+/**
+ * Suggest configuration to another feature during registration.
+ */
+export declare function suggestFeatureInfo(
+    fromFeatureCtr: Function,
+    toFeatureSymbol: symbol,
+    featureInfo: { withAttrs?: any; customData?: any },
+    targetClass: Function
+): void;
+
+/**
+ * Retrieve suggestions made to a feature by other features.
+ */
+export declare function getFeatureInfoSuggestions(
+    toFeatureSymbol: symbol,
+    targetClass: Function
+): FeatureInfoSuggestion[];
+
+/**
+ * Base class for nested feature containers.
+ */
+export declare class PropertyBag {
+    customElementRegistry: any;
+    constructor(hostElement: any, ctx?: FeatureSpawnContext, initVals?: any);
+}