assign-gingerly 0.0.42 → 0.0.44

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**
 
@@ -4779,6 +4782,19 @@ 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) |
+| [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) |
+
+</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,
@@ -476,6 +479,86 @@ export function captureFeatureInitVals(instance) {
         }
     }
 }
+/**
+ * Global store for inter-feature suggestions.
+ * Structure: Map<targetSymbol, Map<targetClass, Array<FeatureInfoSuggestion>>>
+ * Scoped per target class to prevent leaking between different custom elements.
+ */
+const featureInfoSuggestions = new Map();
+/**
+ * Suggest configuration to another feature during registration.
+ *
+ * Call this in a feature's `static onAssigned` to provide config fragments
+ * (withAttrs, customData) that another feature should merge into its own config.
+ *
+ * The target feature is identified by a Symbol (stable across versions and mocks).
+ * Suggestions are scoped per target class to prevent leaking between different
+ * custom elements that use the same features.
+ *
+ * @param fromFeatureCtr - The feature class making the suggestion (for tracing)
+ * @param toFeatureSymbol - Symbol identifying the target feature
+ * @param featureInfo - Config fragments to suggest (withAttrs, customData)
+ * @param targetClass - The custom element class being configured
+ *
+ * @example
+ * import { suggestFeatureInfo } from 'assign-gingerly/assignFeatures.js';
+ * import { ROUNDABOUT_FEATURE } from 'roundabout/symbols.js';
+ *
+ * class FaceUp {
+ *     static onAssigned(ctr, featureConfig) {
+ *         suggestFeatureInfo(FaceUp, ROUNDABOUT_FEATURE, {
+ *             customData: { formBindings: { value: 'value' } }
+ *         }, ctr);
+ *     }
+ * }
+ */
+export function suggestFeatureInfo(fromFeatureCtr, toFeatureSymbol, featureInfo, targetClass) {
+    let symbolMap = featureInfoSuggestions.get(toFeatureSymbol);
+    if (!symbolMap) {
+        symbolMap = new Map();
+        featureInfoSuggestions.set(toFeatureSymbol, symbolMap);
+    }
+    let suggestions = symbolMap.get(targetClass);
+    if (!suggestions) {
+        suggestions = [];
+        symbolMap.set(targetClass, suggestions);
+    }
+    suggestions.push({
+        from: fromFeatureCtr,
+        ...featureInfo
+    });
+}
+/**
+ * Retrieve suggestions made to a feature by other features.
+ *
+ * Call this in a feature's `static onAssigned` to read config fragments
+ * suggested by other features that were processed earlier.
+ *
+ * @param toFeatureSymbol - Symbol identifying this feature (the target)
+ * @param targetClass - The custom element class being configured
+ * @returns Array of suggestions (empty if none)
+ *
+ * @example
+ * import { getFeatureInfoSuggestions } from 'assign-gingerly/assignFeatures.js';
+ * import { ROUNDABOUT_FEATURE } from './symbols.js';
+ *
+ * class RoundaboutFeature {
+ *     static onAssigned(ctr, featureConfig) {
+ *         const suggestions = getFeatureInfoSuggestions(ROUNDABOUT_FEATURE, ctr);
+ *         for (const suggestion of suggestions) {
+ *             if (suggestion.customData) {
+ *                 featureConfig.customData = { ...featureConfig.customData, ...suggestion.customData };
+ *             }
+ *         }
+ *     }
+ * }
+ */
+export function getFeatureInfoSuggestions(toFeatureSymbol, targetClass) {
+    const symbolMap = featureInfoSuggestions.get(toFeatureSymbol);
+    if (!symbolMap)
+        return [];
+    return symbolMap.get(targetClass) || [];
+}
 // =============================================================================
 // PropertyBag — base class for nested feature containers
 // =============================================================================

package/assignFeatures.ts

@@ -515,7 +515,10 @@ const VALID_CALLBACKS = new Set([
     'connectedCallback',
     'disconnectedCallback',
     'attributeChangedCallback',
-    'adoptedCallback'
+    'adoptedCallback',
+    'formDisabledCallback',
+    'formResetCallback',
+    'formStateRestoreCallback'
 ]);
 
 /**
@@ -728,6 +731,114 @@ export function captureFeatureInitVals(instance: any): void {
     }
 }
 
+// =============================================================================
+// Inter-feature communication: suggestFeatureInfo / getFeatureInfoSuggestions
+// =============================================================================
+
+/**
+ * A suggestion from one feature to another, containing config fragments to merge.
+ */
+export interface FeatureInfoSuggestion {
+    /** The feature class that made the suggestion (for debugging/tracing) */
+    from: Function;
+    /** Attribute patterns to merge into the target feature's withAttrs */
+    withAttrs?: any;
+    /** Custom data to merge into the target feature's customData */
+    customData?: any;
+}
+
+/**
+ * Global store for inter-feature suggestions.
+ * Structure: Map<targetSymbol, Map<targetClass, Array<FeatureInfoSuggestion>>>
+ * Scoped per target class to prevent leaking between different custom elements.
+ */
+const featureInfoSuggestions = new Map<symbol, Map<Function, FeatureInfoSuggestion[]>>();
+
+/**
+ * Suggest configuration to another feature during registration.
+ * 
+ * Call this in a feature's `static onAssigned` to provide config fragments
+ * (withAttrs, customData) that another feature should merge into its own config.
+ * 
+ * The target feature is identified by a Symbol (stable across versions and mocks).
+ * Suggestions are scoped per target class to prevent leaking between different
+ * custom elements that use the same features.
+ * 
+ * @param fromFeatureCtr - The feature class making the suggestion (for tracing)
+ * @param toFeatureSymbol - Symbol identifying the target feature
+ * @param featureInfo - Config fragments to suggest (withAttrs, customData)
+ * @param targetClass - The custom element class being configured
+ * 
+ * @example
+ * import { suggestFeatureInfo } from 'assign-gingerly/assignFeatures.js';
+ * import { ROUNDABOUT_FEATURE } from 'roundabout/symbols.js';
+ * 
+ * class FaceUp {
+ *     static onAssigned(ctr, featureConfig) {
+ *         suggestFeatureInfo(FaceUp, ROUNDABOUT_FEATURE, {
+ *             customData: { formBindings: { value: 'value' } }
+ *         }, ctr);
+ *     }
+ * }
+ */
+export function suggestFeatureInfo(
+    fromFeatureCtr: Function,
+    toFeatureSymbol: symbol,
+    featureInfo: { withAttrs?: any; customData?: any },
+    targetClass: Function
+): void {
+    let symbolMap = featureInfoSuggestions.get(toFeatureSymbol);
+    if (!symbolMap) {
+        symbolMap = new Map();
+        featureInfoSuggestions.set(toFeatureSymbol, symbolMap);
+    }
+
+    let suggestions = symbolMap.get(targetClass);
+    if (!suggestions) {
+        suggestions = [];
+        symbolMap.set(targetClass, suggestions);
+    }
+
+    suggestions.push({
+        from: fromFeatureCtr,
+        ...featureInfo
+    });
+}
+
+/**
+ * Retrieve suggestions made to a feature by other features.
+ * 
+ * Call this in a feature's `static onAssigned` to read config fragments
+ * suggested by other features that were processed earlier.
+ * 
+ * @param toFeatureSymbol - Symbol identifying this feature (the target)
+ * @param targetClass - The custom element class being configured
+ * @returns Array of suggestions (empty if none)
+ * 
+ * @example
+ * import { getFeatureInfoSuggestions } from 'assign-gingerly/assignFeatures.js';
+ * import { ROUNDABOUT_FEATURE } from './symbols.js';
+ * 
+ * class RoundaboutFeature {
+ *     static onAssigned(ctr, featureConfig) {
+ *         const suggestions = getFeatureInfoSuggestions(ROUNDABOUT_FEATURE, ctr);
+ *         for (const suggestion of suggestions) {
+ *             if (suggestion.customData) {
+ *                 featureConfig.customData = { ...featureConfig.customData, ...suggestion.customData };
+ *             }
+ *         }
+ *     }
+ * }
+ */
+export function getFeatureInfoSuggestions(
+    toFeatureSymbol: symbol,
+    targetClass: Function
+): FeatureInfoSuggestion[] {
+    const symbolMap = featureInfoSuggestions.get(toFeatureSymbol);
+    if (!symbolMap) return [];
+    return symbolMap.get(targetClass) || [];
+}
+
 // =============================================================================
 // PropertyBag — base class for nested feature containers
 // =============================================================================

package/index.js

@@ -9,6 +9,6 @@ export { resolveTemplate } from './resolveTemplate.js';
 export { getHost } from './getHost.js';
 export { resolveValues, resolveValue } from './resolveValues.js';
 export { assignFrom } from './assignFrom.js';
-export { assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag } from './assignFeatures.js';
+export { assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag, suggestFeatureInfo, getFeatureInfoSuggestions } from './assignFeatures.js';
 export { installForwarding } from './installForwarding.js';
 import './object-extension.js';

package/index.ts

@@ -9,6 +9,6 @@ export {resolveTemplate} from './resolveTemplate.js';
 export {getHost} from './getHost.js';
 export {resolveValues, resolveValue} from './resolveValues.js';
 export {assignFrom} from './assignFrom.js';
-export {assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag} from './assignFeatures.js';
+export {assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag, suggestFeatureInfo, getFeatureInfoSuggestions} from './assignFeatures.js';
 export {installForwarding} from './installForwarding.js';
 import './object-extension.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.42",
+  "version": "0.0.44",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -89,7 +89,7 @@
   "devDependencies": {
     "@playwright/test": "1.60.0",
     "spa-ssi": "0.0.27",
-    "@types/node": "25.7.0",
+    "@types/node": "25.8.0",
     "typescript": "6.0.3"
   }
 }

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
-): Promise<void> | undefined;