assign-gingerly 0.0.44 → 0.0.46

package/README.md

@@ -751,7 +751,31 @@ console.log(obj);
 // }
 ```
 
-The `+=` command syntax is `<path> +=` where the path uses the `?.` nested notation for nested properties, or a plain key for direct properties. The right-hand side value is added to the existing value using `+=`. If the path doesn't exist, it's created and set directly to the value.  If the expression is a string, string concatenation is used.  If the expression can't be "added to", it allows JavaScript to throw its natural error.
+The `+=` command syntax is `<path> +=` where the path uses the `?.` nested notation for nested properties, or a plain key for direct properties. The right-hand side value is added to the existing value using `+=`. If the path doesn't exist, it's created and set directly to the value.
+
+**Behavior by type:**
+
+| LHS type | RHS type | Result |
+|----------|----------|--------|
+| number | number | addition (`2 += 3` → `5`) |
+| string | any | string concatenation (`"hello" += 3` → `"hello3"`) |
+| array | array | array concatenation (`[1,2] += [3,4]` → `[1,2,3,4]`) |
+| array | non-array | push single item (`[1,2] += 3` → `[1,2,3]`) |
+| undefined/missing | any | direct assignment |
+
+```TypeScript
+const obj = {
+    tags: ['a', 'b'],
+    name: 'hello'
+};
+assignGingerly(obj, {
+    '?.tags +=': ['c', 'd'],   // array concat: ['a', 'b', 'c', 'd']
+    '?.name +=': ' world'      // string concat: 'hello world'
+});
+
+// Push a single item
+assignGingerly(obj, { '?.tags +=': 'e' }); // ['a', 'b', 'c', 'd', 'e']
+```
 
 ## Example 5 - Toggling boolean values and negating
 

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/assignGingerly.js

@@ -616,6 +616,11 @@ export function assignGingerly(target, source, options) {
                     if (!(lastKey in parent)) {
                         parent[lastKey] = value;
                     }
+                    else if (Array.isArray(parent[lastKey])) {
+                        parent[lastKey] = Array.isArray(value)
+                            ? [...parent[lastKey], ...value]
+                            : [...parent[lastKey], value];
+                    }
                     else {
                         parent[lastKey] += value;
                     }
@@ -625,6 +630,11 @@ export function assignGingerly(target, source, options) {
                     if (!(path in target)) {
                         target[path] = value;
                     }
+                    else if (Array.isArray(target[path])) {
+                        target[path] = Array.isArray(value)
+                            ? [...target[path], ...value]
+                            : [...target[path], value];
+                    }
                     else {
                         target[path] += value;
                     }

package/assignGingerly.ts

@@ -801,6 +801,10 @@ export function assignGingerly(
           const parent = ensureNestedPath(target, pathParts);
           if (!(lastKey in parent)) {
             parent[lastKey] = value;
+          } else if (Array.isArray(parent[lastKey])) {
+            parent[lastKey] = Array.isArray(value)
+              ? [...parent[lastKey], ...value]
+              : [...parent[lastKey], value];
           } else {
             parent[lastKey] += value;
           }
@@ -808,6 +812,10 @@ export function assignGingerly(
           // Plain key - direct operation on target
           if (!(path in target)) {
             target[path] = value;
+          } else if (Array.isArray(target[path])) {
+            target[path] = Array.isArray(value)
+              ? [...target[path], ...value]
+              : [...target[path], value];
           } else {
             target[path] += value;
           }

package/assignTentatively.js

@@ -124,7 +124,14 @@ export function assignTentatively(target, source, options) {
                         if (!(fullPath in reversal)) {
                             reversal[fullPath] = parent[lastKey];
                         }
-                        parent[lastKey] += value;
+                        if (Array.isArray(parent[lastKey])) {
+                            parent[lastKey] = Array.isArray(value)
+                                ? [...parent[lastKey], ...value]
+                                : [...parent[lastKey], value];
+                        }
+                        else {
+                            parent[lastKey] += value;
+                        }
                     }
                     else {
                         // Property doesn't exist, create it with the value
@@ -137,7 +144,14 @@ export function assignTentatively(target, source, options) {
                         if (!(path in reversal)) {
                             reversal[path] = target[path];
                         }
-                        target[path] += value;
+                        if (Array.isArray(target[path])) {
+                            target[path] = Array.isArray(value)
+                                ? [...target[path], ...value]
+                                : [...target[path], value];
+                        }
+                        else {
+                            target[path] += value;
+                        }
                     }
                     else {
                         target[path] = value;

package/assignTentatively.ts

@@ -152,7 +152,13 @@ export function assignTentatively(
             if (!(fullPath in reversal)) {
               reversal[fullPath] = parent[lastKey];
             }
-            parent[lastKey] += value;
+            if (Array.isArray(parent[lastKey])) {
+              parent[lastKey] = Array.isArray(value)
+                ? [...parent[lastKey], ...value]
+                : [...parent[lastKey], value];
+            } else {
+              parent[lastKey] += value;
+            }
           } else {
             // Property doesn't exist, create it with the value
             parent[lastKey] = value;
@@ -163,7 +169,13 @@ export function assignTentatively(
             if (!(path in reversal)) {
               reversal[path] = target[path];
             }
-            target[path] += value;
+            if (Array.isArray(target[path])) {
+              target[path] = Array.isArray(value)
+                ? [...target[path], ...value]
+                : [...target[path], value];
+            } else {
+              target[path] += value;
+            }
           } else {
             target[path] = value;
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.44",
+  "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);
+}