assign-gingerly 0.0.42 → 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**
 
@@ -4779,6 +4782,18 @@ 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,

package/assignFeatures.ts

@@ -515,7 +515,10 @@ const VALID_CALLBACKS = new Set([
     'connectedCallback',
     'disconnectedCallback',
     'attributeChangedCallback',
-    'adoptedCallback'
+    'adoptedCallback',
+    'formDisabledCallback',
+    'formResetCallback',
+    'formStateRestoreCallback'
 ]);
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.42",
+  "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
-): Promise<void> | undefined;