assign-gingerly 0.0.90 → 0.0.92

package/README.md

@@ -102,6 +102,8 @@ assignFrom adds support for:
 5.  Looped substitution with `where_x_in` / `where_y_in` / `where_z_in` for expanding template patterns into multiple concrete assignments.
 6.  Dynamic substitutions via the `substitutions` option for injecting runtime string values into path segments. See [docs/substitutions.md](docs/substitutions.md).
 7.  Spread merging via the `"..."` key.
+8.  Boolean coercion / negation of a resolved value via a leading `!` marker: `'!!?.isOpen'` resolves `?.isOpen` then coerces to a real boolean, `'!?.isOpen'` negates it (`!!!` negates, and so on). Only honored in front of a `?.` path, `$0` reference, or protocol — a plain literal like `'!important'` is left untouched. Nullish coerces to `false`, which makes `!!` the safe way to feed an optional source value into a boolean sink (`hidden`, `disabled`, `classList.toggle`'s force argument, …).
+9.  Multiple invocations of one `withMethods` method via the ` =*` operator — see [docs/multi-invoke.md](docs/multi-invoke.md).
 
 Example:
 
@@ -853,6 +855,7 @@ While we are in the business of passing values of object A into object B, we mig
 | ` ?=` | Ternary | Conditional assignment (assignFrom only) — [details](docs/ternary-assignment.md) | `'?.text ?=': ['?.cond', 'yes', 'no']` |
 | ` =>` | Handler | Invoke a handler plugin (assignFrom only) | `'?.el =>': { do: 'builtIns.lazyLoad', ... }` |
 | ` =&` | Sync op | Compute a value synchronously and assign it back (assignFrom only) — no dynamic import, no await, ever | `'?.text =&': { join: ['?.first', ' ', '?.last'] }` |
+| ` =*` | Multi-invoke | Call a `withMethods` method once per argument-list (assignFrom only) — [details](docs/multi-invoke.md) | `` '?.classList?.toggle =*': [['a', '!!?.x'], ['b', '!!?.y']] `` |
 
 All operators use a space before the suffix to distinguish them from property names. They compose with `?.` nested paths and `withMethods`.
 
@@ -957,6 +960,45 @@ The `=!` command syntax is `<path> =!` where the path uses the `?.` nested notat
 
 For existing values, the toggle is performed using JavaScript's logical NOT operator (`!value`), regardless of what type it is.
 
+## Example 5a - Conditional class lists with the `!!` marker and `=*` command
+
+The imperative pattern
+
+```JS
+if (vm.isOpen) el.classList.add('isOpenCls');
+else           el.classList.remove('isOpenCls');
+```
+
+is just `el.classList.toggle('isOpenCls', vm.isOpen)`. In `assignFrom` that is a `toggle`
+call in `withMethods` with a resolved force argument — and the `!!` marker coerces the
+resolved value to a real boolean so a missing source value *removes* the class instead of
+flipping it:
+
+```TypeScript
+assignFrom(el, {
+    '?.classList?.toggle': ['isOpenCls', '!!?.isOpen']
+}, { from: vm, withMethods: ['toggle'] });
+```
+
+For several classes at once, the `=*` operator runs the method once per argument-list:
+
+```TypeScript
+const vm = { isOpen: true, isLoading: false, hasError: true };
+
+assignFrom(el, {
+    '?.classList?.toggle =*': [
+        ['isOpenCls',  '!!?.isOpen'],
+        ['loadingCls', '!!?.isLoading'],
+        ['errorCls',   '!!?.hasError'],
+    ]
+}, { from: vm, withMethods: ['toggle'] });
+
+// toggle('isOpenCls', true); toggle('loadingCls', false); toggle('errorCls', true)
+```
+
+See [docs/multi-invoke.md](docs/multi-invoke.md) for the full `=*` semantics, including its
+interaction with `where_x_in`.
+
 ## Example 6 - Deleting properties with -= command
 
 The `-=` command allows us to delete properties from objects:

package/assignFrom.js

@@ -57,6 +57,21 @@ export function parseSyncOpCommand(key) {
         return null;
     return key.substring(0, key.length - 3); // Remove ' =&' suffix
 }
+/**
+ * Check if a key ends with the multi-invoke operator ' =*'.
+ */
+export function isMultiInvokeCommand(key) {
+    return key.endsWith(' =*');
+}
+/**
+ * Parse a =* multi-invoke command and extract the base LHS path — the path a
+ * `withMethods` method sits at, to be called once per argument-list on the RHS.
+ */
+export function parseMultiInvokeCommand(key) {
+    if (!isMultiInvokeCommand(key))
+        return null;
+    return key.substring(0, key.length - 3); // Remove ' =*' suffix
+}
 /**
  * Throws if a resolved sync-op value (or anything nested inside it) is a thenable.
  *
@@ -338,12 +353,19 @@ export function expandSubstitutions(pattern, options) {
     return mergeHandlerDuplicates(entries);
 }
 /**
- * Convert entries to an object, merging duplicate handler (` =>`) keys into arrays.
+ * Convert entries to an object. Duplicate keys — which `where_x_in` expansion can
+ * produce — are collapsed with last-wins, except:
+ *  - ` =>` handler keys merge into the Multiple Handlers array form.
+ *  - ` =*` multi-invoke keys concatenate their argument-list arrays, so an
+ *    expanded pattern still invokes the method once per expansion.
  */
 export function mergeHandlerDuplicates(entries) {
     const result = {};
     for (const [key, value] of entries) {
-        if (key.endsWith(' =>') && key in result) {
+        if (key in result && key.endsWith(' =*') && Array.isArray(result[key]) && Array.isArray(value)) {
+            result[key] = result[key].concat(value);
+        }
+        else if (key.endsWith(' =>') && key in result) {
             const existing = result[key];
             if (Array.isArray(existing)) {
                 existing.push(value);
@@ -389,6 +411,7 @@ export function categorizeKeys(expandedPattern) {
     const idRefHandlerKeys = [];
     const ternaryKeys = [];
     const syncOpKeys = [];
+    const multiInvokeKeys = [];
     for (const key of Object.keys(expandedPattern)) {
         if (isHandlerCommand(key)) {
             if (key.startsWith('#[')) {
@@ -404,6 +427,9 @@ export function categorizeKeys(expandedPattern) {
         else if (isSyncOpCommand(key)) {
             syncOpKeys.push(key);
         }
+        else if (isMultiInvokeCommand(key)) {
+            multiInvokeKeys.push(key);
+        }
         else if (key.startsWith('#[')) {
             idRefNormalKeys.push(key);
         }
@@ -411,7 +437,7 @@ export function categorizeKeys(expandedPattern) {
             normalPattern[key] = expandedPattern[key];
         }
     }
-    return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys };
+    return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys, multiInvokeKeys };
 }
 /**
  * Merge pin and at into a single lookup map for resolveIdVariable.
@@ -469,7 +495,7 @@ export function assignFrom(target, pattern, options, permissionProcessor) {
     // Expand looped substitution variables
     const expandedPattern = expandSubstitutions(pattern, options);
     // Categorize keys
-    const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys } = categorizeKeys(expandedPattern);
+    const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys, multiInvokeKeys } = categorizeKeys(expandedPattern);
     const resolveOptions = { ...options, root: target, permissionProcessor };
     // Process ?= ternary keys (sync)
     if (ternaryKeys.length > 0) {
@@ -517,6 +543,26 @@ export function assignFrom(target, pattern, options, permissionProcessor) {
             }
         }
     }
+    // Process =* multi-invoke keys (sync): call a withMethods method sitting at the
+    // base path once per argument-list on the RHS. Each argument-list is resolved
+    // against `from` (so `?.` paths and `!!` markers work), then delegated to
+    // assignGingerly as a single array-valued key — which spreads it as call args.
+    if (multiInvokeKeys.length > 0) {
+        for (const key of multiInvokeKeys) {
+            const basePath = parseMultiInvokeCommand(key);
+            if (basePath === null)
+                continue;
+            const callList = expandedPattern[key];
+            if (!Array.isArray(callList)) {
+                throw new Error(`assignFrom: multi-invoke command "${key}" requires an array of argument-lists`);
+            }
+            for (const rawArgs of callList) {
+                const argList = Array.isArray(rawArgs) ? rawArgs : [rawArgs];
+                const resolved = getValues({ __args: argList }, options.from, resolveOptions).__args;
+                assignGingerly(target, { [basePath]: resolved }, options, permissionProcessor);
+            }
+        }
+    }
     // Process normal keys via getValues (sync) + assignGingerly
     if (Object.keys(normalPattern).length > 0) {
         // Resolve #[x] references on RHS values before getValues

package/assignFrom.ts

@@ -67,6 +67,22 @@ export function parseSyncOpCommand(key: string): string | null {
     return key.substring(0, key.length - 3); // Remove ' =&' suffix
 }
 
+/**
+ * Check if a key ends with the multi-invoke operator ' =*'.
+ */
+export function isMultiInvokeCommand(key: string): boolean {
+    return key.endsWith(' =*');
+}
+
+/**
+ * Parse a =* multi-invoke command and extract the base LHS path — the path a
+ * `withMethods` method sits at, to be called once per argument-list on the RHS.
+ */
+export function parseMultiInvokeCommand(key: string): string | null {
+    if (!isMultiInvokeCommand(key)) return null;
+    return key.substring(0, key.length - 3); // Remove ' =*' suffix
+}
+
 /**
  * Throws if a resolved sync-op value (or anything nested inside it) is a thenable.
  *
@@ -349,12 +365,18 @@ export function expandSubstitutions(
 }
 
 /**
- * Convert entries to an object, merging duplicate handler (` =>`) keys into arrays.
+ * Convert entries to an object. Duplicate keys — which `where_x_in` expansion can
+ * produce — are collapsed with last-wins, except:
+ *  - ` =>` handler keys merge into the Multiple Handlers array form.
+ *  - ` =*` multi-invoke keys concatenate their argument-list arrays, so an
+ *    expanded pattern still invokes the method once per expansion.
  */
 export function mergeHandlerDuplicates(entries: [string, any][]): Record<string, any> {
   const result: Record<string, any> = {};
   for (const [key, value] of entries) {
-    if (key.endsWith(' =>') && key in result) {
+    if (key in result && key.endsWith(' =*') && Array.isArray(result[key]) && Array.isArray(value)) {
+      result[key] = (result[key] as any[]).concat(value);
+    } else if (key.endsWith(' =>') && key in result) {
       const existing = result[key];
       if (Array.isArray(existing)) {
         existing.push(value);
@@ -400,6 +422,7 @@ export function categorizeKeys(expandedPattern: Record<string, any>) {
   const idRefHandlerKeys: string[] = [];
   const ternaryKeys: string[] = [];
   const syncOpKeys: string[] = [];
+  const multiInvokeKeys: string[] = [];
 
   for (const key of Object.keys(expandedPattern)) {
     if (isHandlerCommand(key)) {
@@ -412,6 +435,8 @@ export function categorizeKeys(expandedPattern: Record<string, any>) {
       ternaryKeys.push(key);
     } else if (isSyncOpCommand(key)) {
       syncOpKeys.push(key);
+    } else if (isMultiInvokeCommand(key)) {
+      multiInvokeKeys.push(key);
     } else if (key.startsWith('#[')) {
       idRefNormalKeys.push(key);
     } else {
@@ -419,7 +444,7 @@ export function categorizeKeys(expandedPattern: Record<string, any>) {
     }
   }
 
-  return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys };
+  return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys, multiInvokeKeys };
 }
 
 /**
@@ -495,7 +520,7 @@ export function assignFrom(
   const expandedPattern = expandSubstitutions(pattern, options);
 
   // Categorize keys
-  const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys } = categorizeKeys(expandedPattern);
+  const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys, syncOpKeys, multiInvokeKeys } = categorizeKeys(expandedPattern);
 
   const resolveOptions = { ...options, root: target, permissionProcessor } as any;
 
@@ -547,6 +572,26 @@ export function assignFrom(
     }
   }
 
+  // Process =* multi-invoke keys (sync): call a withMethods method sitting at the
+  // base path once per argument-list on the RHS. Each argument-list is resolved
+  // against `from` (so `?.` paths and `!!` markers work), then delegated to
+  // assignGingerly as a single array-valued key — which spreads it as call args.
+  if (multiInvokeKeys.length > 0) {
+    for (const key of multiInvokeKeys) {
+      const basePath = parseMultiInvokeCommand(key);
+      if (basePath === null) continue;
+      const callList = expandedPattern[key];
+      if (!Array.isArray(callList)) {
+        throw new Error(`assignFrom: multi-invoke command "${key}" requires an array of argument-lists`);
+      }
+      for (const rawArgs of callList) {
+        const argList = Array.isArray(rawArgs) ? rawArgs : [rawArgs];
+        const resolved = getValues({ __args: argList }, options.from, resolveOptions).__args;
+        assignGingerly(target, { [basePath]: resolved }, options, permissionProcessor);
+      }
+    }
+  }
+
   // Process normal keys via getValues (sync) + assignGingerly
   if (Object.keys(normalPattern).length > 0) {
     // Resolve #[x] references on RHS values before getValues

package/assignFromAsync.js

@@ -21,14 +21,14 @@
  */
 import { resolveValues } from './resolve/resolveValues.js';
 import assignGingerly from './assignGingerly.js';
-import { expandSubstitutions, categorizeKeys, handleSpreads } from './assignFrom.js';
+import { expandSubstitutions, categorizeKeys, handleSpreads, parseMultiInvokeCommand } from './assignFrom.js';
 // Module cache for processHandlerCommands — avoids await on dynamic import after first call
 let _processHandlerCommands;
 export async function assignFromAsync(target, pattern, options, permissionProcessor) {
     // First: expand looped substitution variables (${x}, ${y}, ${z})
     const expandedPattern = expandSubstitutions(pattern, options);
     // Categorize keys
-    const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys } = categorizeKeys(expandedPattern);
+    const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, multiInvokeKeys } = categorizeKeys(expandedPattern);
     // Process normal keys via resolveValues + assignGingerly
     if (Object.keys(normalPattern).length > 0) {
         const resolved = await resolveValues(normalPattern, options.from, {
@@ -44,6 +44,28 @@ export async function assignFromAsync(target, pattern, options, permissionProces
         handleSpreads(resolved);
         assignGingerly(target, resolved, options, permissionProcessor);
     }
+    // Process =* multi-invoke keys: call a withMethods method sitting at the base
+    // path once per argument-list on the RHS (see assignFrom for the sync form).
+    if (multiInvokeKeys && multiInvokeKeys.length > 0) {
+        const { withMethods, aka, akaMethods, substitutions, protocols, from } = options;
+        for (const key of multiInvokeKeys) {
+            const basePath = parseMultiInvokeCommand(key);
+            if (basePath === null)
+                continue;
+            const callList = expandedPattern[key];
+            if (!Array.isArray(callList)) {
+                throw new Error(`assignFrom: multi-invoke command "${key}" requires an array of argument-lists`);
+            }
+            for (const rawArgs of callList) {
+                const argList = Array.isArray(rawArgs) ? rawArgs : [rawArgs];
+                const resolved = await resolveValues({ __args: argList }, from, {
+                    withMethods, aka, akaMethods, substitutions, protocols,
+                    root: target, permissionProcessor
+                });
+                assignGingerly(target, { [basePath]: resolved.__args }, options, permissionProcessor);
+            }
+        }
+    }
     // Process #[x] normal keys — resolve element, then apply remaining path + value
     if (idRefNormalKeys.length > 0 && (options.pin || options.at)) {
         const ids = { ...options.pin, ...options.at };

package/assignFromAsync.ts

@@ -24,7 +24,7 @@ import {IAssignGingerlyOptions} from './types/assign-gingerly/types.js';
 import assignGingerly from './assignGingerly.js';
 import type { PermissionProcessor, AssignFromHandler, AssignFromHandlerConstructor } from './types/assign-gingerly/types.js';
 import {
-  expandSubstitutions, categorizeKeys, handleSpreads, isHandlerCommand
+  expandSubstitutions, categorizeKeys, handleSpreads, isHandlerCommand, parseMultiInvokeCommand
 } from './assignFrom.js';
 
 export interface AssignFromOptions extends IAssignGingerlyOptions {
@@ -61,7 +61,7 @@ export async function assignFromAsync(
   const expandedPattern = expandSubstitutions(pattern, options);
 
   // Categorize keys
-  const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys } = categorizeKeys(expandedPattern);
+  const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, multiInvokeKeys } = categorizeKeys(expandedPattern);
 
   // Process normal keys via resolveValues + assignGingerly
   if (Object.keys(normalPattern).length > 0) {
@@ -81,6 +81,28 @@ export async function assignFromAsync(
     assignGingerly(target, resolved, options, permissionProcessor);
   }
 
+  // Process =* multi-invoke keys: call a withMethods method sitting at the base
+  // path once per argument-list on the RHS (see assignFrom for the sync form).
+  if (multiInvokeKeys && multiInvokeKeys.length > 0) {
+    const { withMethods, aka, akaMethods, substitutions, protocols, from } = options;
+    for (const key of multiInvokeKeys) {
+      const basePath = parseMultiInvokeCommand(key);
+      if (basePath === null) continue;
+      const callList = expandedPattern[key];
+      if (!Array.isArray(callList)) {
+        throw new Error(`assignFrom: multi-invoke command "${key}" requires an array of argument-lists`);
+      }
+      for (const rawArgs of callList) {
+        const argList = Array.isArray(rawArgs) ? rawArgs : [rawArgs];
+        const resolved = await resolveValues({ __args: argList }, from, {
+          withMethods, aka, akaMethods, substitutions, protocols,
+          root: target, permissionProcessor
+        });
+        assignGingerly(target, { [basePath]: resolved.__args }, options, permissionProcessor);
+      }
+    }
+  }
+
   // Process #[x] normal keys — resolve element, then apply remaining path + value
   if (idRefNormalKeys.length > 0 && (options.pin || options.at)) {
     const ids = { ...options.pin, ...options.at };

package/inferencer/inferencer.js

@@ -50,12 +50,21 @@ export class Infer {
     }
     #value;
     get value() {
-        return this.#value;
+        const element = this.#weakRef.deref();
+        if (element === undefined)
+            return this.#value;
+        const propName = typeof this.#propName === 'string'
+            ? this.#propName
+            : inferValueProperty(element);
+        return coerceElementValue(element, propName);
     }
     set value(nv) {
         this.#value = nv;
         const { enhancedElement } = this;
-        enhancedElement[inferValueProperty(enhancedElement)] = nv;
+        const propName = typeof this.#propName === 'string'
+            ? this.#propName
+            : inferValueProperty(enhancedElement);
+        enhancedElement[propName] = serializeForProperty(propName, nv);
     }
     #display;
     get display() {
@@ -166,6 +175,75 @@ export function inferValueProperty(element) {
         }
     }
 }
+/**
+ * Read the inferred value property off an element and coerce it to a natural
+ * JavaScript type, mirroring the legacy be-value-added parsing rules:
+ * - `<time>` (dateTime) -> Date (or undefined when empty)
+ * - `<input type=number|range>` (valueAsNumber) -> number (undefined when NaN)
+ * - `<input type=checkbox|radio>` (checked) -> boolean
+ * - schema.org `itemtype` hints (Number/Integer/Float/Boolean/Date/DateTime) are honored
+ * - `textContent` is returned verbatim
+ * - everything else is JSON-parsed when possible (so `<data value="123">` -> 123,
+ *   `<data value="true">` -> true), falling back to the raw string
+ */
+export function coerceElementValue(element, propName = inferValueProperty(element)) {
+    const raw = element[propName];
+    switch (propName) {
+        case 'valueAsNumber':
+            return Number.isNaN(raw) ? undefined : raw;
+        case 'valueAsDate':
+            return raw ?? undefined;
+        case 'checked':
+        case 'selectedIndex':
+            return raw;
+        case 'dateTime': {
+            const s = raw == null ? '' : String(raw);
+            return s === '' ? undefined : new Date(s);
+        }
+    }
+    if (raw == null)
+        return undefined;
+    if (typeof raw !== 'string')
+        return raw;
+    switch (element.getAttribute('itemtype')) {
+        case 'https://schema.org/Number': return Number(raw);
+        case 'https://schema.org/Integer': return parseInt(raw, 10);
+        case 'https://schema.org/Float': return parseFloat(raw);
+        case 'https://schema.org/Boolean': return raw === 'true' || raw === 'True';
+        case 'https://schema.org/Date':
+        case 'https://schema.org/DateTime': return new Date(raw);
+    }
+    if (propName === 'textContent')
+        return raw;
+    if (raw === '')
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+/**
+ * Serialize a JS value for assignment to a (usually string-typed) DOM value
+ * property, mirroring legacy be-value-added write-back:
+ * - DOM-typed properties (`checked`, `valueAsNumber`, `valueAsDate`) take the raw value
+ * - a `Date` is written as an ISO string (so `<time>.dateTime` round-trips)
+ * - plain objects / arrays are JSON-stringified
+ */
+export function serializeForProperty(propName, nv) {
+    switch (propName) {
+        case 'checked':
+        case 'valueAsNumber':
+        case 'valueAsDate':
+            return nv;
+    }
+    if (nv instanceof Date)
+        return nv.toISOString();
+    if (nv !== null && typeof nv === 'object')
+        return JSON.stringify(nv);
+    return nv;
+}
 /**
  * Infer the most appropriate display property for an element
  * @param element - The element to infer the property for

package/inferencer/inferencer.ts

@@ -65,13 +65,21 @@ export class Infer<TValue = any, TDisplay = any> {
     #value: TValue | undefined;
     
     get value(): TValue | undefined {
-        return this.#value;
+        const element = this.#weakRef.deref();
+        if (element === undefined) return this.#value;
+        const propName = typeof this.#propName === 'string'
+            ? this.#propName
+            : inferValueProperty(element);
+        return coerceElementValue(element, propName) as TValue | undefined;
     }
-    
+
     set value(nv: TValue){
         this.#value = nv;
         const {enhancedElement} = this;
-        (enhancedElement as any)[inferValueProperty(enhancedElement)] = nv;
+        const propName = typeof this.#propName === 'string'
+            ? this.#propName
+            : inferValueProperty(enhancedElement);
+        (enhancedElement as any)[propName] = serializeForProperty(propName, nv);
     }
 
     #display: TDisplay | undefined;
@@ -200,6 +208,75 @@ export function inferValueProperty(element: Element): string {
     }
 }
 
+/**
+ * Read the inferred value property off an element and coerce it to a natural
+ * JavaScript type, mirroring the legacy be-value-added parsing rules:
+ * - `<time>` (dateTime) -> Date (or undefined when empty)
+ * - `<input type=number|range>` (valueAsNumber) -> number (undefined when NaN)
+ * - `<input type=checkbox|radio>` (checked) -> boolean
+ * - schema.org `itemtype` hints (Number/Integer/Float/Boolean/Date/DateTime) are honored
+ * - `textContent` is returned verbatim
+ * - everything else is JSON-parsed when possible (so `<data value="123">` -> 123,
+ *   `<data value="true">` -> true), falling back to the raw string
+ */
+export function coerceElementValue(element: Element, propName: string = inferValueProperty(element)): any {
+    const raw = (element as any)[propName];
+
+    switch (propName) {
+        case 'valueAsNumber':
+            return Number.isNaN(raw) ? undefined : raw;
+        case 'valueAsDate':
+            return raw ?? undefined;
+        case 'checked':
+        case 'selectedIndex':
+            return raw;
+        case 'dateTime': {
+            const s = raw == null ? '' : String(raw);
+            return s === '' ? undefined : new Date(s);
+        }
+    }
+
+    if (raw == null) return undefined;
+    if (typeof raw !== 'string') return raw;
+
+    switch (element.getAttribute('itemtype')) {
+        case 'https://schema.org/Number': return Number(raw);
+        case 'https://schema.org/Integer': return parseInt(raw, 10);
+        case 'https://schema.org/Float': return parseFloat(raw);
+        case 'https://schema.org/Boolean': return raw === 'true' || raw === 'True';
+        case 'https://schema.org/Date':
+        case 'https://schema.org/DateTime': return new Date(raw);
+    }
+
+    if (propName === 'textContent') return raw;
+    if (raw === '') return undefined;
+
+    try {
+        return JSON.parse(raw);
+    } catch {
+        return raw;
+    }
+}
+
+/**
+ * Serialize a JS value for assignment to a (usually string-typed) DOM value
+ * property, mirroring legacy be-value-added write-back:
+ * - DOM-typed properties (`checked`, `valueAsNumber`, `valueAsDate`) take the raw value
+ * - a `Date` is written as an ISO string (so `<time>.dateTime` round-trips)
+ * - plain objects / arrays are JSON-stringified
+ */
+export function serializeForProperty(propName: string, nv: any): any {
+    switch (propName) {
+        case 'checked':
+        case 'valueAsNumber':
+        case 'valueAsDate':
+            return nv;
+    }
+    if (nv instanceof Date) return nv.toISOString();
+    if (nv !== null && typeof nv === 'object') return JSON.stringify(nv);
+    return nv;
+}
+
 /**
  * Infer the most appropriate display property for an element
  * @param element - The element to infer the property for

package/inferencer/types/NewCustomElement.md

@@ -139,6 +139,18 @@ Plus infrastructure:
 - `attachInternals()` called in the constructor
 - Async `fallbackSpawn` for lazy-loading all feature implementations
 
+### Injecting a custom or package-local feature
+
+`assignFeatures` accepts a `spawn` per feature key — a class, an async loader, or
+an **import-path string**. A string `spawn` overrides the catalog `fallbackSpawn`
+and is dynamically `import()`ed through the page's import map, so `el-maker.json`
+stays pure JSON. Use it to add a feature that isn't in the catalog, or to swap in
+a package-local **subclass** of a catalog feature when the generic one needs
+element-specific logic. See
+[NewHTMLFirstCustomElement.md → "give a shared feature element-specific logic"](./NewHTMLFirstCustomElement.md#how-do-i-give-a-shared-feature-element-specific-logic-penciling-in)
+and the [css-charts](https://github.com/bahrus/css-charts) conversion for a
+worked example ("penciling in" `CSSChartsH2OTable extends H2OTable`).
+
 
 
 

package/inferencer/types/NewCustomElementFeature.md

@@ -71,10 +71,14 @@ A custom element feature is a class that:
 
 ## Step 3: Create Type Definitions
 
+**All types for the feature live in `types/[project-name]/types.d.ts` — nothing else.** Do not scatter `@typedef {Object} ...` blocks through the `.js` file. That includes the `customData` / injection-config shape, the `detail` payload of any event the feature dispatches, and every internal helper type. The `.js` file only ever *imports* these via `@import`; it never defines them. A reader (or the package that later adopts the feature) should be able to learn the whole type surface from the one `.d.ts`.
+
 Create `types/[project-name]/types.d.ts` with the feature structure:
 
 ```typescript
-import { SpawnContext } from "../assign-gingerly/types";
+import { SpawnContext, FeatureSpawnContext } from "../assign-gingerly/types";
+
+export { FeatureSpawnContext };
 
 /**
  * Configuration/properties that the feature exposes
@@ -96,9 +100,26 @@ export type AP = AllProps;
 export type PAP = Partial<AP>;
 
 /**
- * Context passed to the feature constructor
+ * The `customData` passed through the injection config — parsed by the
+ * constructor into initial state. Keep every configurable knob here.
+ */
+export interface CustomData {
+    myProp?: string;
+    eventType?: string;
+}
+
+/**
+ * `detail` payload for any CustomEvent the feature dispatches on the host.
  */
-export interface FeatureSpawnContext extends SpawnContext {
+export interface MyFeatureResolvedDetail {
+    // ...
+}
+```
+
+If a project's `types/assign-gingerly/types.d.ts` does not yet export `FeatureSpawnContext`, define it locally in this file instead (as `truth-sourcer` and `face-up` do):
+
+```typescript
+export interface FeatureSpawnContext {
     key: string;
     optIn: any;
     injection: any;
@@ -110,7 +131,9 @@ export interface FeatureSpawnContext extends SpawnContext {
 **Key points:**
 - `FeatureProps` — the public API of the feature
 - `AllProps` — includes internal state like a WeakRef to the host element
+- `CustomData` — the injection-config shape; the constructor reads `ctx.injection.customData` and narrows it to this type
 - The feature class does NOT need to extend any base class
+- The `.js` file imports all of the above with `/** @import {...} from './types/[project-name]/types' */` — it defines no types of its own
 
 ## Step 4: Create the Feature Class
 
@@ -150,7 +173,7 @@ export { MyFeature };
 - Constructor signature: `(hostElement, ctx, initVals)`
 - Store host as a `WeakRef` to avoid preventing garbage collection
 - Apply `initVals` via `Object.assign` in the constructor
-- Use `@ts-check` with JSDoc type imports from the `types/` folder
+- Use `@ts-check` with JSDoc type imports from the `types/` folder — all type definitions live in `types/[project-name]/types.d.ts`, never as inline `@typedef` blocks in the `.js`
 - No compiled TypeScript — ship raw `.js` files
 
 ## Step 5: Create imports.html
@@ -679,6 +702,7 @@ customElements.define('my-element', MyElement);
 
 - **Call `assignFeatures` before `customElements.define()`** — getters must be on the prototype before instances exist
 - **Use `@ts-check`** — catches type errors early in `.js` files
+- **Keep all types in `types/[project-name]/types.d.ts`** — including `customData` and event `detail` shapes; the `.js` only `@import`s them, it never declares `@typedef`s
 - **Store host as WeakRef** — prevents memory leaks
 - **Keep features focused** — one responsibility per feature class
 - **Use `validateShape`** — catches injection errors early in development