assign-gingerly 0.0.66 → 0.0.68

package/DX/IterableMixin.js

@@ -0,0 +1,49 @@
+/**
+ * IterableMixin
+ * -------------
+ * Adds a private `TItem[]` list to the *instance* (storage has to live
+ * somewhere), but exposes all the behavior — getItems/setItems/assignTo
+ * — as STATIC methods on the resulting constructor, matching the
+ * original `static getItems(instance)` style. No instance methods are
+ * added.
+ *
+ * Because private fields are only reachable from code written inside
+ * the class body, the static methods have to be declared right next
+ * to the `#myList` field — that's what makes `instance.#myList` legal
+ * from a `static` method.
+ *
+ * Works on HTMLElement subclasses (dispatches an event if the instance
+ * supports it) and on plain classes (skips the dispatch silently).
+ */
+export function IterableMixin() {
+    return function (Base) {
+        class WithIterableStatics extends Base {
+            #myList = [];
+            static getItems(instance) {
+                return instance.#myList;
+            }
+            static setItems(instance, items) {
+                instance.#myList = items;
+                WithIterableStatics.#notifyChange(instance);
+            }
+            static assignTo(instance, rhs) {
+                if (Array.isArray(rhs)) {
+                    WithIterableStatics.setItems(instance, rhs);
+                }
+                else if (typeof rhs === 'object' && rhs !== null) {
+                    Object.assign(instance, rhs);
+                }
+            }
+            static #notifyChange(instance) {
+                // Only dispatch if this instance actually supports it
+                // (i.e. it's an HTMLElement / EventTarget). Plain classes
+                // just skip this silently.
+                const maybeTarget = instance;
+                if (typeof maybeTarget.dispatchEvent === 'function') {
+                    maybeTarget.dispatchEvent(new Event('items-changed'));
+                }
+            }
+        }
+        return WithIterableStatics;
+    };
+}

package/DX/IterableMixin.ts

@@ -0,0 +1,62 @@
+/**
+ * A constructor type — anything `new`-able. Required so the mixin
+ * can be applied on top of an arbitrary base class.
+ */
+type Constructor<T = {}> = new (...args: any[]) => T;
+
+/**
+ * IterableMixin
+ * -------------
+ * Adds a private `TItem[]` list to the *instance* (storage has to live
+ * somewhere), but exposes all the behavior — getItems/setItems/assignTo
+ * — as STATIC methods on the resulting constructor, matching the
+ * original `static getItems(instance)` style. No instance methods are
+ * added.
+ *
+ * Because private fields are only reachable from code written inside
+ * the class body, the static methods have to be declared right next
+ * to the `#myList` field — that's what makes `instance.#myList` legal
+ * from a `static` method.
+ *
+ * Works on HTMLElement subclasses (dispatches an event if the instance
+ * supports it) and on plain classes (skips the dispatch silently).
+ */
+export function IterableMixin<TItem>() {
+  return function <TBase extends Constructor>(Base: TBase) {
+    class WithIterableStatics extends Base {
+      #myList: TItem[] = [];
+
+      static getItems(instance: WithIterableStatics): TItem[] {
+        return instance.#myList;
+      }
+
+      static setItems(instance: WithIterableStatics, items: TItem[]): void {
+        instance.#myList = items;
+        WithIterableStatics.#notifyChange(instance);
+      }
+
+      static assignTo(
+        instance: WithIterableStatics,
+        rhs: TItem[] | Record<string, unknown>
+      ): void {
+        if (Array.isArray(rhs)) {
+          WithIterableStatics.setItems(instance, rhs);
+        } else if (typeof rhs === 'object' && rhs !== null) {
+          Object.assign(instance, rhs);
+        }
+      }
+
+      static #notifyChange(instance: WithIterableStatics): void {
+        // Only dispatch if this instance actually supports it
+        // (i.e. it's an HTMLElement / EventTarget). Plain classes
+        // just skip this silently.
+        const maybeTarget = instance as unknown as { dispatchEvent?: (e: Event) => boolean };
+        if (typeof maybeTarget.dispatchEvent === 'function') {
+          maybeTarget.dispatchEvent(new Event('items-changed'));
+        }
+      }
+    }
+
+    return WithIterableStatics;
+  };
+}

package/{emojis.js → DX/emojis.js}

@@ -33,7 +33,8 @@ export const akaMethods = {
     '🔍': 'querySelector',
     '🧺': 'querySelectorAll',
     '+': 'add',
-    '🧬': 'cloneNode'
+    '🧬': 'cloneNode',
+    '🔤': 'textContent',
 };
 export const aka = {
     '©️': 'content?.cloneNode?.true',

package/{emojis.ts → DX/emojis.ts}

@@ -35,7 +35,8 @@ export const akaMethods: Record<string, string> = {
     '🔍': 'querySelector',
     '🧺': 'querySelectorAll',
     '+': 'add',
-    '🧬': 'cloneNode'
+    '🧬': 'cloneNode',
+    '🔤': 'textContent',
 };
 
 export const aka: Record<string, string> = {

package/{installForwarding.js → DX/installForwarding.js}

@@ -20,8 +20,8 @@
  * installForwarding(ClubMember);
  * // Now el.command delegates to el.behaviors.commandBehavior.command
  */
-import { resolveValue } from './resolveValues.js';
-import assignGingerly from './assignGingerly.js';
+import { resolveValue } from '../resolveValues.js';
+import assignGingerly from '../assignGingerly.js';
 /**
  * Installs property forwarding on a class prototype based on `static propLinks`.
  *

package/{installForwarding.ts → DX/installForwarding.ts}

@@ -21,8 +21,8 @@
  * // Now el.command delegates to el.behaviors.commandBehavior.command
  */
 
-import { resolveValue, ResolveValuesOptions } from './resolveValues.js';
-import assignGingerly, { IAssignGingerlyOptions } from './assignGingerly.js';
+import { resolveValue, ResolveValuesOptions } from '../resolveValues.js';
+import assignGingerly, { IAssignGingerlyOptions } from '../assignGingerly.js';
 
 export interface InstallForwardingOptions extends ResolveValuesOptions, IAssignGingerlyOptions {}
 

package/DX/paths.js

@@ -0,0 +1,381 @@
+/**
+ * paths.ts — Typed path proxy and template tag for assignFrom authoring.
+ *
+ * Provides compile-time autocomplete and type safety for `?.`-prefixed path strings.
+ *
+ * @example
+ * import { paths, sp } from 'assign-gingerly/DX/paths.js';
+ *
+ * interface Person {
+ *     firstName?: string;
+ *     middleName?: string;
+ *     lastName: string;
+ *     address: { city: string; zip: string };
+ * }
+ *
+ * const $ = paths<Person>();
+ *
+ * // Use sp (split into parts) to create arrays for builtIns.join:
+ * const value = sp`${$.lastName}, ${$.firstName}`;
+ * // ['?.lastName', ', ', '?.firstName']
+ *
+ * // Use .path for raw string contexts (object keys, plain arrays):
+ * const key = $.textContent.path;  // '?.textContent'
+ */
+/**
+ * Symbol used internally to detect path proxy objects.
+ * The sp tag function uses this to auto-extract path strings from proxies.
+ */
+const PATH_SYMBOL = Symbol('assign-gingerly-path');
+/**
+ * Create a proxy for id-ref paths (#[varName]).
+ * After the initial #[varName], further property access chains with ?. from the resolved element.
+ * .path returns the #[varName] prefix (optionally with further ?. path).
+ */
+function createIdRefProxy(idRef, options) {
+    function handler() { }
+    return new Proxy(handler, {
+        get(_, prop) {
+            if (prop === 'path' || prop === PATH_SYMBOL) {
+                return idRef;
+            }
+            if (typeof prop === 'symbol')
+                return undefined;
+            // Chain further path segments after the id ref
+            const chained = `${idRef}?.${String(prop)}`;
+            return createIdRefProxy(chained, options);
+        },
+        apply(_, __, args) {
+            if (args.length > 0) {
+                const arg = args[0];
+                let argStr;
+                if (arg === true)
+                    argStr = 'true';
+                else if (arg === false)
+                    argStr = 'false';
+                else if (arg && typeof arg === 'object' && PATH_SYMBOL in arg) {
+                    const fullPath = arg[PATH_SYMBOL];
+                    argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
+                }
+                else
+                    argStr = String(arg);
+                const chained = `${idRef}?.${argStr}`;
+                return createIdRefProxy(chained, options);
+            }
+            return createIdRefProxy(idRef, options);
+        }
+    });
+}
+/**
+ * Create a recursive proxy that records property access paths.
+ * Supports both property access and method call syntax (via apply trap on function target).
+ *
+ * When `aka` is provided, property names that match an alias *value* are output
+ * using the alias *key* instead (reverse alias).
+ */
+function createPathProxy(prefix, options) {
+    const aliasMap = options?.aka;
+    // Use a function as the target to enable the apply trap
+    function handler() { }
+    return new Proxy(handler, {
+        get(_, prop) {
+            if (prop === 'path' || prop === PATH_SYMBOL) {
+                return prefix.length > 0 ? `?.${prefix}` : '?.';
+            }
+            // Ignore symbol access (Symbol.iterator, Symbol.toPrimitive, etc.)
+            if (typeof prop === 'symbol')
+                return undefined;
+            let segment = String(prop);
+            // #-prefix: $['#firstName'] → '#[firstName]' (cached element ref)
+            if (segment.startsWith('#')) {
+                const varName = segment.substring(1);
+                const idRef = `#[${varName}]`;
+                // Return a proxy that starts from this id ref (can chain further with ?.)
+                return createIdRefProxy(idRef, options);
+            }
+            // Apply reverse alias: if prop matches an alias value, use the alias key
+            if (aliasMap) {
+                for (const [alias, target] of Object.entries(aliasMap)) {
+                    if (target === segment) {
+                        segment = alias;
+                        break;
+                    }
+                }
+            }
+            const newPath = prefix ? `${prefix}?.${segment}` : segment;
+            return createPathProxy(newPath, options);
+        },
+        apply(_, __, args) {
+            // Method call syntax: $.querySelector('.username') → extends path with the argument
+            if (args.length > 0) {
+                const arg = args[0];
+                let argStr;
+                if (arg === true)
+                    argStr = 'true';
+                else if (arg === false)
+                    argStr = 'false';
+                else if (arg && typeof arg === 'object' && PATH_SYMBOL in arg) {
+                    // Proxy arg — extract path without '?.' prefix
+                    const fullPath = arg[PATH_SYMBOL];
+                    argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
+                }
+                else
+                    argStr = String(arg);
+                const newPath = prefix ? `${prefix}?.${argStr}` : argStr;
+                return createPathProxy(newPath, options);
+            }
+            // No args — method called with no arguments, return self
+            return createPathProxy(prefix, options);
+        }
+    });
+}
+/**
+ * Create a typed path proxy for a given interface/type.
+ * Property accesses on the returned proxy produce `?.`-prefixed path strings.
+ * Method calls append their argument to the path.
+ *
+ * @param options - Optional aka aliases and withMethods for path generation
+ *
+ * @example
+ * const $ = paths<Person>();
+ * $.lastName.path          // '?.lastName'
+ * $.address.city.path      // '?.address?.city'
+ *
+ * // With aka (reverse alias applied):
+ * const $ = paths<MyEl>({ aka: { q: 'querySelector' } });
+ * $.querySelector('.user').textContent.path  // '?.q?..user?.textContent'
+ *
+ * // Inside sp template literals, .path is not needed:
+ * sp`${$.lastName}, ${$.firstName}`  // ['?.lastName', ', ', '?.firstName']
+ */
+export function paths(options) {
+    return createPathProxy('', options);
+}
+/**
+ * Create an assignment pair: { [lhs.path]: rhs.path }.
+ * Used to express "set this target to this source value" in a spreadable form.
+ *
+ * @example
+ * set($.clone.querySelector('.username').textContent).to($.username)
+ * // { '?.clone?.q?..username?.textContent': '?.username' }
+ *
+ * // Spread into an assign object:
+ * assign: {
+ *     ...set($.textContent).to($.name),
+ *     ...set($.className).to($.theme),
+ *     count: 1
+ * }
+ */
+export function set(lhs) {
+    const lhsStr = lhs && typeof lhs === 'object' && PATH_SYMBOL in lhs
+        ? lhs[PATH_SYMBOL]
+        : String(lhs);
+    return {
+        to(rhs) {
+            const rhsStr = rhs && typeof rhs === 'object' && PATH_SYMBOL in rhs
+                ? rhs[PATH_SYMBOL]
+                : rhs;
+            return { [lhsStr]: rhsStr };
+        }
+    };
+}
+/**
+ * Recursively walk a value and convert any path proxy objects to their
+ * `?.`-prefixed string representation.
+ *
+ * Use this to wrap entire config objects or arrays that contain proxy values,
+ * extracting all path strings in one pass.
+ *
+ * @example
+ * const $ = paths<MyVM>({ aka: { q: 'querySelector' } });
+ *
+ * const config = smoothOver({
+ *     assign: {
+ *         incrementButton: $.clone.querySelector('.increment'),
+ *         decrementButton: $.clone.querySelector('.decrement'),
+ *     }
+ * });
+ * // { assign: { incrementButton: '?.clone?.q?..increment', ... } }
+ */
+export function smoothOver(value) {
+    if (value && typeof value === 'object' && PATH_SYMBOL in value) {
+        return value[PATH_SYMBOL];
+    }
+    if (Array.isArray(value)) {
+        return value.map(smoothOver);
+    }
+    if (value && typeof value === 'object') {
+        const proto = Object.getPrototypeOf(value);
+        if (proto === Object.prototype || proto === null) {
+            const result = {};
+            for (const [k, v] of Object.entries(value)) {
+                result[k] = smoothOver(v);
+            }
+            return result;
+        }
+    }
+    return value;
+}
+/**
+ * Merge multiple set(...).to(...) pairs (and/or plain objects) into an `{ assign: {...} }` object.
+ * Spread the result into a merge config to avoid repeated `...` per entry.
+ *
+ * @example
+ * {
+ *     ifKeyIn: ['statusClassName', 'statusMessageText'],
+ *     ifAllOf: ['clone'],
+ *     ...doAssign(
+ *         set($.clone.querySelector('.status').className).to($.statusClassName),
+ *         set($.clone.querySelector('.status-text').textContent).to($.statusMessageText),
+ *     )
+ * }
+ * // Equivalent to: { ifKeyIn: [...], ifAllOf: [...], assign: { '?.clone?.q?..status?.className': '?.statusClassName', ... } }
+ *
+ * // Mix with literal values:
+ * ...doAssign(
+ *     set($.clone.querySelector('.count-value').textContent).to($.count),
+ *     { renderCount: 1 },
+ * )
+ */
+export function doAssign(...pairs) {
+    return { assign: Object.assign({}, ...pairs) };
+}
+/**
+ * Compile-time loop expansion: generates one entry per key from a factory function.
+ * Creates a typed proxy internally — the factory receives both the key and the proxy.
+ *
+ * @param keys - Array of property names to iterate (type-checked against T)
+ * @param factory - Function that produces a config entry for each key
+ * @param options - Optional PathsOptions (aka, withMethods) for the internal proxy
+ * @returns Array of factory results (one per key) — spread into merges array
+ *
+ * @example
+ * import { forEachKeyIn, set, doAssign } from 'assign-gingerly/paths.js';
+ *
+ * interface Person extends HTMLElement { firstName: string; lastName: string; }
+ *
+ * const merges = [
+ *     ...forEachKeyIn<Person>(['firstName', 'lastName'], (key, $) => ({
+ *         ifKeyIn: [key],
+ *         assignOptions: { pin: { [key]: { qry: `[name="${key}"]` } } },
+ *         ...doAssign(set($['#' + key]).to($[key]))
+ *     })),
+ * ];
+ */
+export function forEachKeyIn(keys, factory, options) {
+    const $ = paths(options);
+    return keys.map(key => factory(key, $));
+}
+/**
+ * Tagged template literal that splits a template into an array of parts.
+ * Interleaves static string segments with interpolated values.
+ *
+ * Path proxy objects are auto-detected and converted to their `?.`-prefixed
+ * string representation — no `.path` call needed inside sp template literals.
+ *
+ * Arrays passed as interpolations are preserved as nested arrays (for
+ * all-or-nothing optional segments in builtIns.join).
+ *
+ * @example
+ * const $ = paths<Person>();
+ *
+ * // Basic usage:
+ * sp`${$.lastName}, ${$.firstName}`
+ * // ['?.lastName', ', ', '?.firstName']
+ *
+ * // With optional segment (nested array, all-or-nothing in join):
+ * sp`${$.lastName}${[', ', $.middleName]}, ${$.firstName}`
+ * // ['?.lastName', [', ', '?.middleName'], ', ', '?.firstName']
+ */
+export function sp(strings, ...values) {
+    const result = [];
+    for (let i = 0; i < strings.length; i++) {
+        if (strings[i])
+            result.push(strings[i]);
+        if (i < values.length) {
+            const v = values[i];
+            if (v && typeof v === 'object' && PATH_SYMBOL in v) {
+                // Auto-extract path from proxy object
+                result.push(v[PATH_SYMBOL]);
+            }
+            else if (Array.isArray(v)) {
+                // Nested array — recursively extract paths from proxy elements
+                result.push(v.map(el => el && typeof el === 'object' && PATH_SYMBOL in el ? el[PATH_SYMBOL] : el));
+            }
+            else {
+                result.push(v);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Extract the last segment from a `?.`-prefixed path string.
+ * e.g., '?.address?.city' → 'city', '?.firstName' → 'firstName'
+ */
+function extractPropName(pathStr) {
+    const parts = pathStr.split('?.');
+    return parts[parts.length - 1];
+}
+/**
+ * Tagged template literal that produces an array of {prop, val} objects + literal strings.
+ * Designed for `builtIns.microDataJoin` — provides both the property name (for itemprop)
+ * and the path string (for resolution).
+ *
+ * Path proxy objects are auto-detected and converted to `{prop, val}` objects.
+ * Plain objects passed as interpolations are preserved as-is (allows developer overrides
+ * with custom prop, val, format, etc.).
+ * Arrays are preserved as nested arrays (for optional segments).
+ *
+ * @example
+ * const $ = paths<Person>();
+ *
+ * // Basic usage:
+ * md`${$.firstName} ${$.lastName}`
+ * // [{ prop: 'firstName', val: '?.firstName' }, ' ', { prop: 'lastName', val: '?.lastName' }]
+ *
+ * // With developer override (custom prop name, format):
+ * md`${$.firstName} ${{ prop: 'birthDate', val: $.birthDT, format: 'long' }}`
+ * // [{ prop: 'firstName', val: '?.firstName' }, ' ', { prop: 'birthDate', val: '?.birthDT', format: 'long' }]
+ *
+ * // With optional segment:
+ * md`${$.firstName}${[' ', $.middleName]} ${$.lastName}`
+ * // [{ prop: 'firstName', val: '?.firstName' }, [' ', { prop: 'middleName', val: '?.middleName' }], ' ', { prop: 'lastName', val: '?.lastName' }]
+ */
+export function md(strings, ...values) {
+    const result = [];
+    for (let i = 0; i < strings.length; i++) {
+        if (strings[i])
+            result.push(strings[i]);
+        if (i < values.length) {
+            const v = values[i];
+            if (v && typeof v === 'object' && PATH_SYMBOL in v) {
+                // Proxy object → {prop, val}
+                const pathStr = v[PATH_SYMBOL];
+                result.push({ prop: extractPropName(pathStr), val: pathStr });
+            }
+            else if (Array.isArray(v)) {
+                // Nested array — recursively convert proxy elements to {prop, val}
+                result.push(v.map(el => {
+                    if (el && typeof el === 'object' && PATH_SYMBOL in el) {
+                        const pathStr = el[PATH_SYMBOL];
+                        return { prop: extractPropName(pathStr), val: pathStr };
+                    }
+                    return el;
+                }));
+            }
+            else if (v && typeof v === 'object' && 'prop' in v) {
+                // Developer override object — extract val from proxy if present
+                const processed = { ...v };
+                if (processed.val && typeof processed.val === 'object' && PATH_SYMBOL in processed.val) {
+                    processed.val = processed.val[PATH_SYMBOL];
+                }
+                result.push(processed);
+            }
+            else {
+                result.push(v);
+            }
+        }
+    }
+    return result;
+}

package/{paths.ts → DX/paths.ts}

@@ -4,7 +4,7 @@
  * Provides compile-time autocomplete and type safety for `?.`-prefixed path strings.
  * 
  * @example
- * import { paths, sp } from 'assign-gingerly/paths.js';
+ * import { paths, sp } from 'assign-gingerly/DX/paths.js';
  * 
  * interface Person {
  *     firstName?: string;

package/README.md

@@ -4220,7 +4220,7 @@ Uses comment markers (`<!--?start name="microDataJoin"-->` / `<!--?end-->`) to t
 The `md` tagged template literal produces the `{prop, val}` structure from proxy objects — full autocomplete and type safety:
 
 ```TypeScript
-import { paths, md } from 'assign-gingerly/paths.js';
+import { paths, md } from 'assign-gingerly/DX/paths.js';
 
 interface Person { firstName: string; lastName: string; birthDT: Date; age: number; }
 const $ = paths<Person>();
@@ -4345,7 +4345,7 @@ assignFrom(element, {
 For JSON generated config files generated from TypeScript/`.mts`/`mjs` files during a build or server-side rendering, the `paths` utility provides compile-time autocomplete and type safety for `?.`-prefixed path strings. The `sp` tagged template literal ("split into parts") produces arrays suitable for `builtIns.join`. The `md` tagged template literal produces `{prop, val}` objects suitable for `builtIns.microDataJoin`.
 
 ```TypeScript
-import { paths, sp } from 'assign-gingerly/paths.js';
+import { paths, sp } from 'assign-gingerly/DX/paths.js';
 
 interface Person {
     firstName?: string;
@@ -4421,7 +4421,7 @@ const pattern = {
 The `md` tag produces `{prop, val}` objects for `builtIns.microDataJoin`:
 
 ```TypeScript
-import { paths, md } from 'assign-gingerly/paths.js';
+import { paths, md } from 'assign-gingerly/DX/paths.js';
 
 interface Person { firstName: string; lastName: string; birthDT: Date; age: number; }
 const $ = paths<Person>();
@@ -4790,6 +4790,18 @@ console.log(app.todos.title); // 'My Todos'
 console.log([...app.todos]); // ['Buy milk', 'Walk dog'] (list unchanged)
 ```
 
+This pattern seems useful and reusable enough that this package provides a DX utility mixin to add this functionality to any class definition:
+
+```JS
+import {IterableMixin} from 'assign-gingerly/DX/IterableMixin.js';
+
+class PlainList extends IterableMixin<number>()(class {}) {}
+
+class MyIterableCustomElement extends IterableMixin<string>()(HTMLElement) {}
+
+class Combined extends OtherMixin()(IterableMixin<string>()(HTMLElement)) {}
+```
+
 ### Use case: Validation on assignment
 
 ```JavaScript
@@ -4834,7 +4846,7 @@ Only classes that explicitly define their own `assignTo` are affected. The check
 `installForwarding` installs getter/setter pairs on a class prototype that delegate to nested paths on the instance. This is useful for exposing deeply nested properties at the top level of an object — particularly for custom elements that delegate behavior to compositional feature classes.
 
 ```JavaScript
-import { installForwarding } from 'assign-gingerly/installForwarding.js';
+import { installForwarding } from 'assign-gingerly/DX/installForwarding.js';
 ```
 
 ### Basic usage
@@ -5932,7 +5944,7 @@ assignGingerly(el, {
 
 ```JavaScript
 import { PropertyBag, assignFeatures } from 'assign-gingerly/assignFeatures.js';
-import { installForwarding } from 'assign-gingerly/installForwarding.js';
+import { installForwarding } from 'assign-gingerly/DX/installForwarding.js';
 
 // 1. Define a feature container by subclassing PropertyBag
 class ClubMemberBehaviors extends PropertyBag {

package/index.js

@@ -11,7 +11,7 @@ export { resolveValues, resolveValue } from './resolveValues.js';
 export { assignFromAsync } from './assignFromAsync.js';
 export { assignFrom } from './assignFrom.js';
 export { assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag, suggestFeatureInfo, getFeatureInfoSuggestions } from './assignFeatures.js';
-export { installForwarding } from './installForwarding.js';
+export { installForwarding } from './DX/installForwarding.js';
 export { defineWithFeatures } from './defineWithFeatures.js';
 export { resolveAndAssignFeatures } from './resolveAndAssignFeatures.js';
 export { nudge } from './handlers/nudge.js';

package/index.ts

@@ -11,7 +11,7 @@ export {resolveValues, resolveValue} from './resolveValues.js';
 export {assignFromAsync} from './assignFromAsync.js';
 export {assignFrom} from './assignFrom.js';
 export {assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag, suggestFeatureInfo, getFeatureInfoSuggestions} from './assignFeatures.js';
-export {installForwarding} from './installForwarding.js';
+export {installForwarding} from './DX/installForwarding.js';
 export {defineWithFeatures} from './defineWithFeatures.js';
 export {resolveAndAssignFeatures} from './resolveAndAssignFeatures.js';
 export {nudge} from './handlers/nudge.js';

package/inferencer/AGENTS.md

@@ -0,0 +1,10 @@
+# Inferencer Submodule Isolation
+
+The `inferencer/` folder is a git submodule that must remain self-contained and independently publishable.
+
+## Rules
+
+- **No imports from outside the folder.** Code in `inferencer/` must NOT import from any file in the parent project (no `../assignGingerly.js`, no `../paths.js`, etc.).
+- **No references to assign-gingerly internals.** The inferencer module must work as a standalone package with zero dependencies on assign-gingerly runtime code.
+- **Types only exception:** Type-only imports from `../types/` are acceptable IF they are also published as part of the inferencer package's own type declarations. Prefer duplicating small type definitions over creating a dependency.
+- **Test exceptions:** Test files within `inferencer/` MAY reference the parent project for integration testing, but runtime source files must not.

package/inferencer/types/EnhancementConversionInstructions.md

@@ -1383,6 +1383,27 @@ const selectorMatch = prop.match(/^\[(.+?)\](?:\?\.(.+))?$/);
 3. **Wrong parser in HTML** - HTML references `parse-pattern-statements` but emc.mjs uses `parse-grouped-capture-statements`
 4. **Period vs chained accessor** - Using `.` instead of `?.` for selector properties
 5. **Forgetting to rebuild** - After changing emc.mjs or emoji.mjs, always run `npm run build`
+6. **Hydrate fires before all attributes are read** - Attribute props are assigned one at a time during initialization; use the `initialized` flag pattern (see below) when an action must wait for all of them
+
+### Blocking an Action Until All Attributes Are Read
+
+When converting an enhancement whose `hydrate` (or other action) depends on multiple attribute-derived props, it's often predictable that nothing should happen until all relevant attributes have been read. Gating on the props alone doesn't work:
+
+- `ifKeyIn` alone means **at least one** of the listed props is defined, so the action can fire after the first attribute is read with the rest still `undefined`.
+- With `ifKeyIn` and `ifAllOf` combined, roundabout only runs the action when the *changed* property is in `ifKeyIn` — a prop listed only in `ifAllOf` never triggers it.
+
+The proven fix (from three-peat): add `initialized?: boolean` to `AllProps`, set `self.initialized = true` in `init` immediately after `await roundabout(...)`, and gate the action on it in both lists:
+
+```javascript
+actions: {
+    hydrate: {
+        ifKeyIn: ['src', 'listProp', 'initialized'],
+        ifAllOf: ['enhancedElement', 'initialized']
+    }
+}
+```
+
+`initialized` flips only after `roundabout()` returns (all attribute reads complete), and including it in `ifKeyIn` makes its change the trigger. Keep the attribute props in `ifKeyIn` too, so later attribute changes still re-trigger the action. See `NewEnhancementInstructions.md` ("Blocking an Action Until All Attributes Are Read") for the full step-by-step recipe.
 
 ### Debugging Tips
 

package/inferencer/types/NewEnhancementInstructions.md

@@ -681,6 +681,52 @@ import { findAdjacentElement } from 'be-hive/findAdjacentElement.js';
 import { findAdjacentElement } from 'trans-render/lib/findAdjacentElement.js';
 ```
 
+### Blocking an Action Until All Attributes Are Read
+
+**Use this pattern only when it's predictable that an action (typically `hydrate`) must not run until all relevant attributes have been read.** Attribute-derived props are assigned one at a time during `roundabout()`'s initial pass, so gating on the props themselves isn't enough:
+
+- `ifKeyIn` alone means **at least one** of the listed props is defined — the action fires as soon as the first attribute is read, while later ones are still `undefined`.
+- When `ifKeyIn` is combined with `ifAllOf`, the action only executes when the property that *changed* is in `ifKeyIn` (`shouldExecute = conditionsMet && changedIsInKeyIn` in roundabout). A prop listed only in `ifAllOf` can never trigger the action.
+
+The proven solution (from three-peat) is an `initialized` flag set after `roundabout()` returns:
+
+**1. Add `initialized` to `AllProps` in `types/<name>/types.d.ts`:**
+
+```typescript
+export interface AllProps extends EndUserProps{
+    enhancedElement: Element & ElementEnhancementGateway;
+    resolved?: boolean;
+    initialized?: boolean;
+}
+```
+
+**2. Set it at the end of `init`, after the `await roundabout(...)`:**
+
+```javascript
+async init(self, enhancedElement, ctx, initVals){
+    // ...build raOptions...
+    await (await import('roundabout-lib/roundabout.js')).roundabout(raOptions);
+    self.initialized = true;  // all attribute reads are done at this point
+}
+```
+
+**3. Gate the action on `initialized` in `emc.mjs` — in *both* lists:**
+
+```javascript
+actions: {
+    hydrate: {
+        ifKeyIn: ['src', 'listProp', 'initialized'],
+        ifAllOf: ['enhancedElement', 'initialized']
+    }
+}
+```
+
+- `initialized` is the last prop to change, and it only flips after every attribute has been read, so it is the reliable trigger.
+- It must be in `ifKeyIn`, not just `ifAllOf` — otherwise its change event doesn't satisfy `changedIsInKeyIn` and the action never fires (the other props were already assigned during the initial pass and never change again).
+- Keeping the attribute props (`src`, `listProp`) in `ifKeyIn` preserves re-hydration when those attributes change later at runtime.
+
+Reference implementation: three-peat (`emc.mjs`, `three-peat.js`, `types/three-peat/types.d.ts`).
+
 ### Debugging Tips
 
 1. **Check the generated JSON** — Run `node emc.mjs` and verify all sections (especially `customData`) are present
@@ -702,4 +748,4 @@ Don't try to implement all features at once.
 
 ---
 
-*Last updated: June 2026*
+*Last updated: July 2026*

package/inferencer/types/assign-gingerly/types.d.ts

@@ -745,11 +745,11 @@ export interface LazyLoadResolvedParams {
      *  Used for SSR placeholder content (e.g., "Loading..." text) that disappears once real content loads. */
     placeholder?: string;
     /** Assignment config applied to cloned content before insertion.
-     *  Same shape as manageTemplateList's fromEachItem: { assignToFragment, withOptions } or { configs: [...] } */
+     *  Same shape as manageTemplateList's fromEachItem: { toClone, withOptions } or { configs: [...] } */
     assign?: {
-        assignToFragment?: Record<string, any>;
+        toClone?: Record<string, any>;
         withOptions?: Record<string, any>;
-        configs?: Array<{ assignToFragment?: Record<string, any>; withOptions?: Record<string, any> }>;
+        configs?: Array<{ toClone?: Record<string, any>; withOptions?: Record<string, any> }>;
     };
 }
 
@@ -795,7 +795,7 @@ export interface LazyLoadSwitchResolvedParams extends Omit<LazyLoadResolvedParam
 }
 
 export interface FromEachItemConfig {
-    assignToFragment?: Record<string, any>;
+    toClone?: Record<string, any>;
     withOptions?: AssignFromOptions;
     resolve?: {
       key?: string;

package/inferencer/types/three-peat/types.d.ts

@@ -10,9 +10,49 @@ export interface EndUserProps{
     
     /**
      * Specify id of peer element to pull list from.
+     * If not provided, the host is found by searching upwards
+     * for an itemscope-managed element, falling back to the
+     * shadow root host.
      */
     src?: string;
-    each: FromEachItemConfig,
-    target: string,
-    updateOn: string,
-}
+
+    /**
+     * Specifies how each item's values are distributed into the
+     * cloned document fragment.  Parsed from JSON.
+     * If not provided, each item's properties are inferred into
+     * the clone's [itemprop] descendants.
+     */
+    each?: FromEachItemConfig,
+
+    /**
+     * id of an element (within the same root node) into which the
+     * repeating cloned fragments should be placed.
+     * If not provided, the fragments are appended to the children
+     * of the adorned element (or, if the adorned element is a
+     * template, to the template's parent element).
+     */
+    target?: string,
+
+    /**
+     * Name of the event the host dispatches when the list has changed.
+     * If not provided, but listProp is, the host is assumed to have
+     * a propagator (one is created if it doesn't exist), which is
+     * listened to for an event named after listProp.
+     */
+    updateOn?: string,
+}
+
+export interface AllProps extends EndUserProps{
+    enhancedElement: Element & ElementEnhancementGateway;
+    resolved?: boolean;
+    initialized?: boolean;
+}
+
+export type AP = AllProps;
+export type PAP = Partial<AP>;
+export type ProPAP = Promise<PAP>;
+
+export interface Actions {
+    init(self: AP, enhancedElement: Element & ElementEnhancementGateway, ctx: SpawnContext, initVals: PAP): Promise<void>;
+    hydrate(self: AP): ProPAP;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.66",
+  "version": "0.0.68",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -17,6 +17,7 @@
   "files": [
     "*.js",
     "*.ts",
+    "DX/**",
     "handlers/**",
     "inferencer/**",
     "README.md",
@@ -106,9 +107,13 @@
       "default": "./handlers/manageTemplateList.js",
       "types": "./handlers/manageTemplateList.ts"
     },
-    "./paths.js": {
-      "default": "./paths.js",
-      "types": "./paths.ts"
+    "./DX/paths.js": {
+      "default": "./DX/paths.js",
+      "types": "./DX/paths.ts"
+    },
+    "./DX/IterableMixin.js": {
+      "default": "./DX/IterableMixin.js",
+      "types": "./DX/IterableMixin.ts"
     },
     "./enhanceAll.js": {
       "default": "./enhanceAll.js",
@@ -158,9 +163,9 @@
       "default": "./assignFromAsync-extension.js",
       "types": "./assignFromAsync-extension.ts"
     },
-    "./emojis.js": {
-      "default": "./emojis.js",
-      "types": "./emojis.ts"
+    "./DX/emojis.js": {
+      "default": "./DX/emojis.js",
+      "types": "./DX/emojis.ts"
     },
     "./assignFeatures.js": {
       "default": "./assignFeatures.js",

package/resolveIdRef.js

@@ -78,7 +78,7 @@ export function resolveIdVariable(varName, target, pin) {
                 // Fire-and-forget: log correction suggestion
                 const capturedConfig = config;
                 const capturedVarName = varName;
-                import('./pinCorrector.js').then(module => {
+                import('./DX/pinCorrector.js').then(module => {
                     module.logConfigCorrection(target, capturedVarName, capturedConfig);
                 }).catch(() => { });
             }

package/resolveIdRef.ts

@@ -91,7 +91,7 @@ export function resolveIdVariable(
                 // Fire-and-forget: log correction suggestion
                 const capturedConfig = config;
                 const capturedVarName = varName;
-                import('./pinCorrector.js').then(module => {
+                import('./DX/pinCorrector.js').then(module => {
                     module.logConfigCorrection(target, capturedVarName, capturedConfig);
                 }).catch(() => {});
             }

package/paths.js

@@ -1,231 +0,0 @@
-/**
- * paths.js — Typed path proxy and template tags for assignFrom authoring.
- *
- * Provides compile-time autocomplete and type safety for `?.`-prefixed path strings.
- * Supports method call syntax, alias reversal, and batch proxy extraction.
- */
-
-/**
- * Symbol used internally to detect path proxy objects.
- */
-const PATH_SYMBOL = Symbol('assign-gingerly-path');
-
-/**
- * Create a proxy for id-ref paths (#[varName]).
- */
-function createIdRefProxy(idRef, options) {
-    function handler() {}
-    return new Proxy(handler, {
-        get(_, prop) {
-            if (prop === 'path' || prop === PATH_SYMBOL) {
-                return idRef;
-            }
-            if (typeof prop === 'symbol') return undefined;
-            const chained = `${idRef}?.${String(prop)}`;
-            return createIdRefProxy(chained, options);
-        },
-        apply(_, __, args) {
-            if (args.length > 0) {
-                const arg = args[0];
-                let argStr;
-                if (arg === true) argStr = 'true';
-                else if (arg === false) argStr = 'false';
-                else if (arg && typeof arg === 'object' && PATH_SYMBOL in arg) {
-                    const fullPath = arg[PATH_SYMBOL];
-                    argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
-                }
-                else argStr = String(arg);
-                const chained = `${idRef}?.${argStr}`;
-                return createIdRefProxy(chained, options);
-            }
-            return createIdRefProxy(idRef, options);
-        }
-    });
-}
-
-/**
- * Create a recursive proxy that records property access paths.
- */
-function createPathProxy(prefix, options) {
-    const aliasMap = options?.aka;
-
-    function handler() {}
-
-    return new Proxy(handler, {
-        get(_, prop) {
-            if (prop === 'path' || prop === PATH_SYMBOL) {
-                return prefix.length > 0 ? `?.${prefix}` : '?.';
-            }
-            if (typeof prop === 'symbol') return undefined;
-
-            let segment = String(prop);
-
-            // #-prefix: $['#firstName'] → '#[firstName]' (cached element ref)
-            if (segment.startsWith('#')) {
-                const varName = segment.substring(1);
-                const idRef = `#[${varName}]`;
-                return createIdRefProxy(idRef, options);
-            }
-
-            if (aliasMap) {
-                for (const [alias, target] of Object.entries(aliasMap)) {
-                    if (target === segment) { segment = alias; break; }
-                }
-            }
-
-            const newPath = prefix ? `${prefix}?.${segment}` : segment;
-            return createPathProxy(newPath, options);
-        },
-        apply(_, __, args) {
-            if (args.length > 0) {
-                const arg = args[0];
-                let argStr;
-                if (arg === true) argStr = 'true';
-                else if (arg === false) argStr = 'false';
-                else if (arg && typeof arg === 'object' && PATH_SYMBOL in arg) {
-                    const fullPath = arg[PATH_SYMBOL];
-                    argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
-                }
-                else argStr = String(arg);
-
-                const newPath = prefix ? `${prefix}?.${argStr}` : argStr;
-                return createPathProxy(newPath, options);
-            }
-            return createPathProxy(prefix, options);
-        }
-    });
-}
-
-/**
- * Create a typed path proxy.
- */
-export function paths(options) {
-    return createPathProxy('', options);
-}
-
-/**
- * Create an assignment pair: { [lhs.path]: rhs.path }.
- */
-export function set(lhs) {
-    const lhsStr = lhs && typeof lhs === 'object' && PATH_SYMBOL in lhs
-        ? lhs[PATH_SYMBOL]
-        : String(lhs);
-    return {
-        to(rhs) {
-            const rhsStr = rhs && typeof rhs === 'object' && PATH_SYMBOL in rhs
-                ? rhs[PATH_SYMBOL]
-                : rhs;
-            return { [lhsStr]: rhsStr };
-        }
-    };
-}
-
-/**
- * Recursively walk a value and convert any path proxy objects to path strings.
- */
-export function smoothOver(value) {
-    if (value && typeof value === 'object' && PATH_SYMBOL in value) {
-        return value[PATH_SYMBOL];
-    }
-    if (Array.isArray(value)) {
-        return value.map(smoothOver);
-    }
-    if (value && typeof value === 'object') {
-        const proto = Object.getPrototypeOf(value);
-        if (proto === Object.prototype || proto === null) {
-            const result = {};
-            for (const [k, v] of Object.entries(value)) {
-                result[k] = smoothOver(v);
-            }
-            return result;
-        }
-    }
-    return value;
-}
-
-/**
- * Merge multiple set(...).to(...) pairs into an { assign: {...} } object.
- * Spread the result into a merge config.
- */
-export function doAssign(...pairs) {
-    return { assign: Object.assign({}, ...pairs) };
-}
-
-/**
- * Compile-time loop expansion: generates one entry per key from a factory function.
- */
-export function forEachKeyIn(keys, factory, options) {
-    const $ = paths(options);
-    return keys.map(key => factory(key, $));
-}
-
-/**
- * Tagged template literal that splits a template into an array of parts.
- * Path proxy objects are auto-detected and converted to path strings.
- */
-export function sp(strings, ...values) {
-    const result = [];
-    for (let i = 0; i < strings.length; i++) {
-        if (strings[i]) result.push(strings[i]);
-        if (i < values.length) {
-            const v = values[i];
-            if (v && typeof v === 'object' && PATH_SYMBOL in v) {
-                result.push(v[PATH_SYMBOL]);
-            }
-            else if (Array.isArray(v)) {
-                result.push(v.map(el =>
-                    el && typeof el === 'object' && PATH_SYMBOL in el ? el[PATH_SYMBOL] : el
-                ));
-            }
-            else {
-                result.push(v);
-            }
-        }
-    }
-    return result;
-}
-
-/**
- * Extract the last segment from a `?.`-prefixed path string.
- */
-function extractPropName(pathStr) {
-    const parts = pathStr.split('?.');
-    return parts[parts.length - 1];
-}
-
-/**
- * Tagged template literal that produces {prop, val} objects for microDataJoin.
- */
-export function md(strings, ...values) {
-    const result = [];
-    for (let i = 0; i < strings.length; i++) {
-        if (strings[i]) result.push(strings[i]);
-        if (i < values.length) {
-            const v = values[i];
-            if (v && typeof v === 'object' && PATH_SYMBOL in v) {
-                const pathStr = v[PATH_SYMBOL];
-                result.push({ prop: extractPropName(pathStr), val: pathStr });
-            }
-            else if (Array.isArray(v)) {
-                result.push(v.map(el => {
-                    if (el && typeof el === 'object' && PATH_SYMBOL in el) {
-                        const pathStr = el[PATH_SYMBOL];
-                        return { prop: extractPropName(pathStr), val: pathStr };
-                    }
-                    return el;
-                }));
-            }
-            else if (v && typeof v === 'object' && 'prop' in v) {
-                const processed = { ...v };
-                if (processed.val && typeof processed.val === 'object' && PATH_SYMBOL in processed.val) {
-                    processed.val = processed.val[PATH_SYMBOL];
-                }
-                result.push(processed);
-            }
-            else {
-                result.push(v);
-            }
-        }
-    }
-    return result;
-}