assign-gingerly 0.0.43 → 0.0.45

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
 
@@ -4790,6 +4814,7 @@ await customElements.assignFeatures(MyElement, { feature: { spawn: SyncFeature }
 | [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>

package/assignFeatures.js

@@ -479,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

@@ -731,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/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/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.43",
+  "version": "0.0.45",
   "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"
   }
 }