assign-gingerly 0.0.59 → 0.0.61

package/README.md

@@ -19,6 +19,21 @@ has the "side effect" of enhancing the platform API in a way that this proposal
 
 One can achieve the same functionality with a little more work, and "playing nicer" with the platform by importing assign-gingerly.js, assign-tentatively.js, and/or assignFrom.js, which has no such side effects.
 
+For `assignFrom` method chaining on objects, separate extension modules are available — import only what you need:
+
+```JavaScript
+import 'assign-gingerly/assignFrom-extension.js';       // adds obj.assignFrom() — sync
+import 'assign-gingerly/assignFromAsync-extension.js';  // adds obj.assignFromAsync() — async
+```
+
+This enables fluent patterns like:
+
+```JavaScript
+oElement
+    .assignFrom({ '?.textContent': '?.greeting' }, { from: vm1 })
+    .assignFrom({ '?.style Y=': { width: '?.w' } }, { from: vm2 });
+```
+
 ## Object Extension Pattern
 
 Not only does this polyfill package allow merging data properties onto objects that are expecting them, this polyfill also provides the ability to merge *augmented behavior* onto run-time objects without sub classing all such objects of the same type. This includes the ability to spawn an instance of a class and "merge" it into the API of the original object in an elegant way that is easy to wrap one's brain around, without ever blocking access to the original object or breaking it.
@@ -285,7 +300,7 @@ In real-world use cases, you often need to replace one object with another of a
 
 **Exception: classes with `static assignTo`**
 
-If the current value is an instance of a class that defines [`static assignTo`](#custom-assignment-with-static-assignto-protocol), that method is called instead of replacing. This allows classes to opt into custom assignment behavior (e.g., reactive models, validated records, iterable collections with private lists):
+If the current value is an instance of a class that defines `static assignTo`, that method is called instead of replacing. This allows classes to opt into custom assignment behavior (e.g., reactive models, validated records, iterable collections with private lists). See the full [Custom Assignment with `static assignTo` Protocol](#custom-assignment-with-static-assignto-protocol) section below for details, examples, and the method signature.
 
 ```TypeScript
 class TodoList {
@@ -754,7 +769,20 @@ assignGingerly(div, {
 - Testing is done in mount-observer package (no tests in assign-gingerly)
 - Single @eachTime per path (nested @eachTime not currently supported)
 
-While we are in the business of passing values of object A into object B, we might as well add some extremely common behavior that allows updating properties of object B based on the current values of object B -- things like incrementing, toggling, and deleting.  Deleting is critical for assignTentatively, but is included with both functions.
+## Common Operation Support
+
+While we are in the business of passing values of object A into object B, we might as well add some extremely common behavior that allows updating properties of object B based on the current values of object B -- things like incrementing, toggling, deleting, and merging into sub-objects.  Deleting is critical for assignTentatively, but is included with both functions.
+
+| Operator | Name | Description | Example |
+|----------|------|-------------|---------|
+| ` +=` | Increment | Add to numeric value, concatenate strings, append to arrays | `'count +=': 5` |
+| ` =!` | Toggle | Negate a boolean (or any value via `!`) | `'visible =!': '.'` |
+| ` -=` | Delete | Remove properties from an object | `'?.data -=': 'key'` |
+| ` Y=` | Merge | Recursively `assignGingerly` into a sub-object | `'style Y=': { width: '100px' }` |
+| ` ?=` | Ternary | Conditional assignment (assignFrom only) — [details](docs/ternary-assignment.md) | `'?.text ?=': ['?.cond', 'yes', 'no']` |
+| ` =>` | Handler | Invoke a handler plugin (assignFrom only) | `'?.el =>': { do: 'builtIns.join', ... }` |
+
+All operators use a space before the suffix to distinguish them from property names. They compose with `?.` nested paths and `withMethods`.
 
 ## Example 4 - Incrementing values with += command
 
@@ -900,7 +928,101 @@ console.log(obj);
 
 
 
-## Example 7 - Reversible assignments with assignTentatively
+## Example 7 - Merging into sub-objects with Y= command
+
+The `Y=` command recursively merges an object into an existing sub-object — like a nested `assignGingerly` call, declared inline:
+
+```TypeScript
+const element = {
+    style: { color: 'blue', display: 'block' },
+    dataset: { userId: '1' }
+};
+
+assignGingerly(element, {
+    'style Y=': {
+        width: '100px',
+        height: '50px'
+    },
+    'dataset Y=': {
+        role: 'admin'
+    }
+});
+
+console.log(element.style);
+// { color: 'blue', display: 'block', width: '100px', height: '50px' }
+
+console.log(element.dataset);
+// { userId: '1', role: 'admin' }
+```
+
+This is equivalent to the more verbose path-per-property approach:
+
+```TypeScript
+assignGingerly(element, {
+    '?.style?.width': '100px',
+    '?.style?.height': '50px',
+    '?.dataset?.role': 'admin'
+});
+```
+
+**With `?.` nested paths:**
+
+```TypeScript
+const app = { config: { database: { host: 'localhost', port: 5432 } } };
+
+assignGingerly(app, {
+    '?.config?.database Y=': {
+        port: 3306,
+        ssl: true
+    }
+});
+// app.config.database = { host: 'localhost', port: 3306, ssl: true }
+```
+
+**Nested `Y=` (recursive composition):**
+
+`Y=` composes — the merged object can itself contain `Y=` keys:
+
+```TypeScript
+const app = {
+    config: {
+        database: { host: 'localhost', port: 5432 },
+        appName: 'OldApp'
+    }
+};
+
+assignGingerly(app, {
+    'config Y=': {
+        'database Y=': {
+            port: 3306,
+            ssl: true
+        },
+        appName: 'NewApp'
+    }
+});
+// config.database = { host: 'localhost', port: 3306, ssl: true }
+// config.appName = 'NewApp'
+```
+
+**Mixing with other operators:**
+
+```TypeScript
+assignGingerly(obj, {
+    'style Y=': { width: '100px' },      // merge into sub-object
+    '?.style?.opacity': '1',              // direct path assignment
+    'counter +=': 1,                      // increment
+    textContent: 'Hello'                  // plain assignment
+});
+```
+
+**Behavior notes:**
+- If the target property doesn't exist or isn't an object, the command is a silent no-op
+- Arrays in the RHS replace the target property (not concatenated) — consistent with normal `assignGingerly` behavior
+- Works with `withMethods` for DOM path evaluation (e.g., `'?.querySelector?..panel?.style Y='`)
+- The name `Y=` evokes a merge sign (Y) — two paths converging into one — combined with `=` to signal an assignment operator
+
+
+## Example 8 - Reversible assignments with assignTentatively
 
 The `assignTentatively` function works like `assignGingerly` but with a powerful addition: **reversibility**. It tracks changes and generates a reversal object that can undo all modifications:
 
@@ -1190,7 +1312,7 @@ obj
 console.log(obj); // { a: 1, b: { c: 2 }, d: 3 }
 ```
 
-**Note**: The `assignTentatively` method on Object.prototype is simply an alias for `assignGingerly` and does **not** provide the reversibility features of the standalone `assignTentatively` function described in Example 7. For reversible assignments, use the standalone function from `assign-gingerly/assignTentatively`.
+**Note**: The `assignTentatively` method on Object.prototype is simply an alias for `assignGingerly` and does **not** provide the reversibility features of the standalone `assignTentatively` function described in Example 8. For reversible assignments, use the standalone function from `assign-gingerly/assignTentatively`.
 
 The prototype extensions are non-enumerable and won't appear in `Object.keys()` or `for...in` loops.
 
@@ -1424,7 +1546,7 @@ interface EnhancementConfig<T, TObj = Element> {
 
 The `withAttrs` property enables automatic attribute parsing when the enhancement is spawned. See the [Parsing Attributes with parseWithAttrs](#parsing-attributes-with-parsewithattrs) section for details.
 
-It also tips off extending polyfills / libraries, in particular mount-observer, to be on te lookout for the attributes specified by withAttrs.  But *assign-gingerly, by itself, performs **no** DOM observing to automatically spawn the class instance*.  It expects consumers of the polyfill to programmatically attach such behavior/enhancements, and/or rely on alternative, higher level packages to be vigilant for enhancement opportunities. 
+It also tips off extending polyfills / libraries, in particular mount-observer, to be on the lookout for the attributes specified by withAttrs.  But *assign-gingerly, by itself, performs **no** DOM observing to automatically spawn the class instance*.  It expects consumers of the polyfill to programmatically attach such behavior/enhancements, and/or rely on alternative, higher level packages to be vigilant for enhancement opportunities. 
 
 The `canSpawn` static method allows enhancement classes to conditionally block spawning based on the target object. See the [Conditional Spawning with canSpawn](#conditional-spawning-with-canspawn) section for details.
 
@@ -3607,6 +3729,23 @@ Import paths must be local (relative, absolute, or bare specifiers — no cross-
 
 Built-in handlers (`builtIns.lazyLoad`, `builtIns.join`, etc.) auto-load without needing to be listed in `handlers`.
 
+**Handler aliases:** The `handlers` option also accepts built-in names as values, allowing you to define short aliases (including emoji) for concise configs:
+
+```JavaScript
+import { builtInEmoji } from 'assign-gingerly/builtInEmoji.js';
+// { '📦': 'builtIns.lazyLoad', '🎚️': 'builtIns.lazyLoadSwitch', '🔗': 'builtIns.join', '🏷️': 'builtIns.microDataJoin', '📋': 'builtIns.manageTemplateList' }
+
+assignFrom(target, {
+    '?.textContent =>': { do: '🔗', get: { value: ['?.first', ' ', '?.last'] } }
+}, { from: vm, handlers: builtInEmoji });
+
+// Or define your own:
+assignFrom(target, pattern, {
+    from: vm,
+    handlers: { 'sw': 'builtIns.lazyLoadSwitch', 'list': 'builtIns.manageTemplateList' }
+});
+```
+
 **How it works:**
 
 1. Keys ending with ` =>` are separated from normal keys.
@@ -3661,16 +3800,72 @@ await assignFromAsync(document.body, {
 | `instantiate` | HTMLTemplateElement | The template to clone (typically resolved via globalThis protocol) |
 | `method` | string | `'appendChild'` (default) or `'prepend'` — where to place markers |
 | `forget` | boolean | If true, removes nodes entirely when `if` is false (default: hides with `hidden` attribute) |
+| `placeholder` | string | Name of a pre-existing marker pair whose content is removed on first activation |
+| `assign` | object | Assignment config applied to cloned content before insertion (see below) |
 
 **Behavior:**
 
-- **First load (`if` = true, no existing content):** Clones the template, inserts content between `<!--?start name="X"-->` / `<!--?end-->` comment markers.
+- **First load (`if` = true, no existing content):** Clones the template, inserts content between `<!--?start name="X"-->` / `<!--?end-->` comment markers. If `placeholder` is specified, its content is removed first.
 - **Show (content exists but hidden):** Removes `hidden` attribute from elements between markers.
 - **Hide (`if` = false, `forget` = false):** Adds `hidden` attribute to elements between markers.
 - **Remove (`if` = false, `forget` = true):** Removes nodes between markers entirely. Markers persist for re-insertion if `if` becomes true again.
 
 This is useful for conditional rendering, routing, and lazy-loading views.
 
+**Placeholder content (SSR/streaming):**
+
+Use `placeholder` to remove pre-rendered "loading" content when real content first activates. The server streams placeholder content inside named markers; once JS runs and the condition is met, the placeholder is cleared and the template is cloned in its place:
+
+```html
+<div class="mainView">
+    <!--?start name="loading"-->
+    <div class="skeleton">Loading...</div>
+    <!--?end-->
+</div>
+```
+
+```JavaScript
+await assignFromAsync(container, {
+    '?.querySelector?..mainView =>': {
+        do: 'builtIns.lazyLoad',
+        get: {
+            if: '?.isReady',
+            instantiate: 'globalThis://mainTemplate',
+            placeholder: 'loading',
+        }
+    }
+}, { withMethods: ['querySelector'], from: vm, protocols: { globalThis: k => globalThis[k] } });
+```
+
+The placeholder is removed only on first activation (one-shot). If `if` later becomes false and then true again, the template is re-shown from its own markers — the placeholder does not reappear.
+
+**Assigning values to cloned content (`assign`):**
+
+Use `assign` to populate the cloned template's elements before they are inserted into the DOM. This uses the same pattern as `manageTemplateList`'s `fromEachItem`:
+
+```JavaScript
+await assignFromAsync(container, {
+    '?.querySelector?..panel =>': {
+        do: 'builtIns.lazyLoad',
+        get: {
+            if: '?.showPanel',
+            instantiate: 'globalThis://panelTemplate',
+            assign: {
+                assignToFragment: {
+                    '#[title]?.textContent': '?.panelTitle',
+                    '#[body]?.textContent': '?.panelContent'
+                },
+                withOptions: {
+                    at: { title: [0], body: [1] }
+                }
+            }
+        }
+    }
+}, { from: vm, withMethods: ['querySelector'], protocols: { globalThis: k => globalThis[k] } });
+```
+
+The `assign.assignToFragment` paths resolve against `options.from` (the same source that drives the `if` condition). For multi-element templates, use `assign.configs` (same zip semantics as `manageTemplateList`).
+
 ### View Transitions
 
 Both `builtIns.lazyLoad` and `builtIns.lazyLoadSwitch` support animated transitions via the [View Transition API](https://developer.mozilla.org/docs/Web/API/View_Transition_API). Enable with `transitional: true` in the resolve map:
@@ -3987,7 +4182,7 @@ assignFrom(document.body, {
         },
         fromEachItem: {
             assignToFragment: { '?.querySelector?.tr?.ish': '?.' },
-            withOptions: { withMethods: ['querySelector'], inferredAssignments: true },
+            withOptions: { withMethods: ['querySelector'], infer: true },
             get: { key: '?.rank' }
         }
     }
@@ -4042,6 +4237,42 @@ get: {
 
 For full details, see [docs/manage-template-list.md](docs/manage-template-list.md).
 
+### Built-in handler: `builtIns.rangeSelector`
+
+Evaluates a value against a series of range conditions and merges the matched case's properties into the target. Converts imperative if/else-if chains into declarative JSON configs.
+
+```JavaScript
+assignFrom(element, {
+    '?. =>': {
+        do: 'builtIns.rangeSelector',
+        get: {
+            value: '?.count',
+            when: [
+                { '<=': 10, merge: { status: 'low', statusMessage: 'Low count' } },
+                { '<': 20, merge: { status: 'medium', statusMessage: 'Medium count' } },
+                { merge: { status: 'high', statusMessage: 'High count!' } }
+            ]
+        }
+    }
+}, { from: vm });
+```
+
+**How it works:**
+
+1. Resolves `value` from the source (e.g., `vm.count`)
+2. Iterates `when` cases in order — first match wins
+3. Each case can have operator keys (`<=`, `<`, `>=`, `>`, `===`, `!==`) as conditions
+4. Multiple operators per case = AND logic (e.g., `{ '>=': 10, '<': 20, merge: {...} }`)
+5. No operator keys = default/catch-all
+6. Merges the matched case's `merge` object into the target via `assignGingerly`
+
+**Supported operators:** `<=`, `<`, `>=`, `>`, `===`, `!==`
+
+**Notes:**
+- Comparison uses JavaScript semantics (`false < true`, strings compare lexicographically)
+- Fully JSON-serializable — no functions, no special types
+- Lazy-loaded on demand like all built-in handlers
+
 ## Typed Path Authoring with `paths`, `sp`, and `md`
 
 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`.
@@ -4177,15 +4408,59 @@ await assignFromAsync(document.body, {
 4. On subsequent calls, the cached `WeakRef.deref()` returns the element in ~10ns.
 5. If the WeakRef is collected (element was GC'd), falls back to `getElementById` (~10-100ns).
 
-**Two forms of `withIds` configuration:**
+**`withIds` — stable references with auto-assigned IDs:**
+
+All forms assign a unique ID to the resolved element (if it doesn't have one). This makes the reference resilient to future DOM mutations — once an element has an ID, it can be found regardless of structural changes.
+
+```TypeScript
+withIds: {
+    x: { qry: '.mainView' },    // querySelector on target, auto-assign ID
+    y: 'existingId',             // element already has an ID, cache via WeakRef
+    z: { path: [0, 1], expect: 'input', fallback: true },  // child index path + auto-ID + validation
+}
+```
+
+| Form | First access | Subsequent | Use case |
+|------|-------------|------------|----------|
+| `'existingId'` | getElementById (~10-100ns) | WeakRef cache (~10ns) | Singleton elements with known IDs |
+| `{ qry: '.x' }` | querySelector (~3,000ns) | — (re-queries each call) | Target-relative elements, stable against mutations |
+| `{ path: [0, 1] }` | children[i] (~2-4ns) | — (re-traverses each call) | Fast + stable (ID protects against future DOM changes) |
+
+**`at` — lightweight positional references (no IDs, no DOM pollution):**
+
+For repeated elements (e.g., per-row in `manageTemplateList`) where you control the template structure and don't want to assign 2,000 IDs to the DOM:
+
+```TypeScript
+at: {
+    a: [0],                                              // target.children[0]
+    b: [1],                                              // target.children[1]
+    c: { path: [0, 2], expect: '.info', fallback: true } // with validation
+}
+```
+
+`at` resolves by child index every call — no IDs assigned, no WeakRef cache, no DOM attributes added. ~2-4ns per index step. Use when:
+- The template structure is stable (you own it)
+- You want a clean DOM (no auto-generated `id` attributes)
+- You're rendering many items (1,000 rows × 2 refs = 2,000 fewer DOM attributes)
+
+Both `withIds` and `at` use the same `#[x]` syntax on LHS and RHS keys.
+
+**Validated paths with `expect` and `fallback`:**
+
+Both `withIds` and `at` support the `{ path, expect, fallback }` form for dev-time validation:
 
 ```TypeScript
 withIds: {
-    x: { qry: '.mainView' },    // Object form: querySelector on target, auto-assign ID
-    y: 'existingId',             // String form: element already has an ID, just cache it
+    nameInput: { path: [1], expect: 'input' },              // warn if [1] isn't an <input>
+    label:     { path: [0], expect: 'label', fallback: true } // warn + recover via querySelector
 }
 ```
 
+- `expect` — a CSS selector checked via `element.matches()` (~50-200ns). If the element at `path` doesn't match, a console warning is logged with the correct coordinates.
+- `fallback: true` — on mismatch, automatically recovers by falling back to `querySelector(expect)`. The corrected element is cached for subsequent access.
+- The correction diagnostic is loaded lazily (fire-and-forget dynamic import) — zero payload in the happy path.
+- Strip `expect`/`fallback` in production builds for maximum performance (or leave them — the overhead is a single `matches()` call).
+
 **Chaining with `?.` paths:**
 
 `#[x]` anchors the start of the path. Further `?.` segments chain from the resolved element:
@@ -4230,6 +4505,24 @@ await assignFromAsync(container, {
 
 The `#[x]` + `withIds` pattern gives you the Map+WeakRef speed tier automatically.
 
+**RHS references (`#[x]` on the value side):**
+
+`#[x]` can also appear on the RHS (value side) to read properties from a cached element. Bare `#[x]` resolves to the element's ID string; append `?.` paths to access other properties:
+
+```TypeScript
+assignFrom(form, {
+    '?.querySelector?.label?.htmlFor': '#[nameInput]',           // → the input's ID string
+    '?.querySelector?.label?.title': '#[nameInput]?.type',       // → 'text', 'email', etc.
+    '?.headerText': '#[info]?.dataset?.user',                    // → nested property access
+}, {
+    from: {},
+    withIds: { nameInput: { qry: 'input' }, info: { qry: '.info' } },
+    withMethods: ['querySelector']
+});
+```
+
+This is useful for accessibility patterns (setting `label[for]` to an auto-generated input ID) and cross-referencing elements declaratively.
+
 **Key behaviors:**
 
 - **Lazy resolution** — elements are resolved on first encounter, not eagerly at the start.
@@ -4251,7 +4544,7 @@ const vm = {
 
 assignFrom(outerDiv, {}, {
     from: vm,
-    inferredAssignments: {
+    infer: {
         byItemprop: ['name', 'email', 'user']
     }
 });
@@ -4272,7 +4565,7 @@ For each key in `byItemprop`, this finds `[itemprop="${key}"]` elements within t
 **Pass `true` to infer all source keys:**
 
 ```TypeScript
-inferredAssignments: { byItemprop: true }
+infer: { byItemprop: true }
 ```
 
 For full details, see [docs/inferred-assignments.md](docs/inferred-assignments.md).
@@ -4338,7 +4631,7 @@ assignGingerly(shadowRoot, {
 
 ## Custom Assignment with `static assignTo` Protocol
 
-Classes can opt into custom assignment behavior by defining a `static assignTo` method. When `assignGingerly` encounters a property whose current value is an instance of such a class, it delegates the assignment to `assignTo` instead of performing the default merge/replace logic.
+As [introduced earlier](#example-3b---class-instances-are-normally-replaced), classes can opt into custom assignment behavior by defining a `static assignTo` method. When `assignGingerly` encounters a property whose current value is an instance of such a class, it delegates the assignment to `assignTo` instead of performing the default merge/replace logic. This section covers the full API, method signature, and advanced use cases.
 
 ```JavaScript
 class ReactiveModel {
@@ -5912,4 +6205,4 @@ Any web server that serves static files with server-side includes will do but...
 7. > git submodule update --init --recursive
 8. > npm install
 9. > npm run serve
-10. Open http://localhost:8000/demo/ in a modern browser
+10. Open http://localhost:8000/demo/ in a modern browser

package/assignFrom-extension.js

@@ -0,0 +1,25 @@
+/**
+ * assignFrom-extension.js — Adds assignFrom to Object.prototype.
+ * 
+ * Import this module for the side effect of extending all objects with
+ * the assignFrom method, enabling fluent method chaining:
+ * 
+ * @example
+ * import 'assign-gingerly/assignFrom-extension.js';
+ * 
+ * oElement
+ *     .assignFrom({ '?.textContent': '?.greeting' }, { from: vm1 })
+ *     .assignFrom({ '?.style Y=': { color: '?.themeColor' } }, { from: vm2 });
+ */
+
+import { assignFrom } from './assignFrom.js';
+
+Object.defineProperty(Object.prototype, 'assignFrom', {
+  value: function (pattern, options) {
+    assignFrom(this, pattern, options);
+    return this;
+  },
+  writable: true,
+  enumerable: false,
+  configurable: true,
+});

package/assignFrom-extension.ts

@@ -0,0 +1,53 @@
+/**
+ * assignFrom-extension.ts — Adds assignFrom to Object.prototype.
+ * 
+ * Import this module for the side effect of extending all objects with
+ * the assignFrom method, enabling fluent method chaining:
+ * 
+ * @example
+ * import 'assign-gingerly/assignFrom-extension.js';
+ * 
+ * oElement
+ *     .assignFrom({ '?.textContent': '?.greeting' }, { from: vm1 })
+ *     .assignFrom({ '?.style Y=': { color: '?.themeColor' } }, { from: vm2 });
+ */
+
+import { assignFrom } from './assignFrom.js';
+import type { AssignFromOptions } from './assignFromAsync.js';
+
+declare global {
+  interface Object {
+    /**
+     * Resolve RHS path strings from a source object and assign into this object.
+     * Synchronous — handlers are fire-and-forget.
+     * 
+     * @param pattern - Object with LHS paths as keys and RHS path strings (or literals) as values
+     * @param options - Configuration including `from` (source object), protocols, withMethods, etc.
+     * @returns This object after assignment
+     * 
+     * @example
+     * oElement.assignFrom({
+     *     '?.textContent': '?.greeting',
+     *     '?.style Y=': { width: '?.width' }
+     * }, { from: viewModel });
+     */
+    assignFrom(
+      pattern: Record<string, any>,
+      options: AssignFromOptions
+    ): this;
+  }
+}
+
+Object.defineProperty(Object.prototype, 'assignFrom', {
+  value: function <T extends object>(
+    this: T,
+    pattern: Record<string, any>,
+    options: AssignFromOptions
+  ): T {
+    assignFrom(this, pattern, options);
+    return this;
+  },
+  writable: true,
+  enumerable: false,
+  configurable: true,
+});