npm - assign-gingerly - Versions diffs - 0.0.91 → 0.0.93 - Mend

assign-gingerly 0.0.91 → 0.0.93

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/inferencer/inferencer.js +123 -2
package/inferencer/inferencer.ts +122 -3
package/inferencer/types/NewCustomElement.md +12 -0
package/inferencer/types/NewCustomElementFeature.md +28 -4
package/inferencer/types/NewHTMLFirstCustomElement.md +196 -2
package/inferencer/types/NewJSFirstCustomElement.md +11 -3
package/inferencer/types/assign-gingerly/types.d.ts +8 -0
package/inferencer/types/be-intl/types.d.ts +68 -0
package/inferencer/types/chip-away/types.d.ts +71 -0
package/inferencer/types/el-maker/types.d.ts +17 -1
package/inferencer/types/h2o-table/types.d.ts +73 -0
package/inferencer/types/id-referencer/types.d.ts +35 -0
package/inferencer/types/inferencer/types.d.ts +19 -1
package/inferencer/types/nested-regex-groups/types.d.ts +2 -0
package/inferencer/types/swipe-dismiss/types.d.ts +14 -0
package/package.json +1 -1
package/types/assign-gingerly/types.d.ts +8 -0

package/inferencer/inferencer.js CHANGED Viewed

@@ -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() {
@@ -80,6 +89,16 @@ export class Infer {
     get valueProperty() {
         return inferValueProperty(this.enhancedElement);
     }
+    /**
+     * The effective language for this element, honoring `lang` / `xml:lang`
+     * inheritance up through ancestors and shadow-root hosts, then
+     * `<html lang>` and finally `navigator.language`.
+     * @returns a BCP-47 tag, or undefined if nothing is resolvable
+     */
+    get lang() {
+        const el = this.#weakRef.deref();
+        return el === undefined ? undefined : resolveLang(el);
+    }
     ['|'](itempropAttr, scopeBoundary = '[itemscope]') {
         return this.#queryScoped(`[itemprop="${itempropAttr}"]`, itempropAttr, scopeBoundary);
     }
@@ -166,6 +185,108 @@ 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;
+}
+/**
+ * Resolve the effective language ("computed lang") for an element.
+ *
+ * There is no DOM accessor for this, so we walk: nearest ancestor element with a
+ * `lang` / `xml:lang` attribute, crossing shadow-root boundaries via the host
+ * (matching how `:lang()` behaves in modern browsers), then `<html lang>`, then
+ * `navigator.language`. Slot reprojection is intentionally not followed — HTML
+ * language inheritance is defined over the real node tree, not the flat tree.
+ *
+ * @returns a BCP-47 tag, or undefined if nothing is resolvable
+ */
+export function resolveLang(element) {
+    let node = element;
+    while (node != null) {
+        if (node.nodeType === 1 /* ELEMENT_NODE */) {
+            const el = node;
+            const lang = el.getAttribute('lang') || el.getAttribute('xml:lang');
+            if (lang)
+                return lang;
+            node = node.parentNode;
+        }
+        else if (node.nodeType === 11 /* DOCUMENT_FRAGMENT_NODE, incl. ShadowRoot */) {
+            node = node.host ?? null;
+        }
+        else {
+            node = null; // Document (9) or detached — stop
+        }
+    }
+    if (typeof document !== 'undefined' && document.documentElement.lang) {
+        return document.documentElement.lang;
+    }
+    return (typeof navigator !== 'undefined' && navigator.language) || undefined;
+}
 /**
  * Infer the most appropriate display property for an element
  * @param element - The element to infer the property for

package/inferencer/inferencer.ts CHANGED Viewed

@@ -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;
@@ -102,6 +110,17 @@ export class Infer<TValue = any, TDisplay = any> {
         return inferValueProperty(this.enhancedElement);
     }
+    /**
+     * The effective language for this element, honoring `lang` / `xml:lang`
+     * inheritance up through ancestors and shadow-root hosts, then
+     * `<html lang>` and finally `navigator.language`.
+     * @returns a BCP-47 tag, or undefined if nothing is resolvable
+     */
+    get lang(): string | undefined {
+        const el = this.#weakRef.deref();
+        return el === undefined ? undefined : resolveLang(el);
+    }
     ['|'](itempropAttr: string, scopeBoundary: string = '[itemscope]'){
         return this.#queryScoped(`[itemprop="${itempropAttr}"]`, itempropAttr, scopeBoundary);
     }
@@ -200,6 +219,106 @@ 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;
+}
+/**
+ * Resolve the effective language ("computed lang") for an element.
+ *
+ * There is no DOM accessor for this, so we walk: nearest ancestor element with a
+ * `lang` / `xml:lang` attribute, crossing shadow-root boundaries via the host
+ * (matching how `:lang()` behaves in modern browsers), then `<html lang>`, then
+ * `navigator.language`. Slot reprojection is intentionally not followed — HTML
+ * language inheritance is defined over the real node tree, not the flat tree.
+ *
+ * @returns a BCP-47 tag, or undefined if nothing is resolvable
+ */
+export function resolveLang(element: Element): string | undefined {
+    let node: Node | null = element;
+    while (node != null) {
+        if (node.nodeType === 1 /* ELEMENT_NODE */) {
+            const el = node as Element;
+            const lang = el.getAttribute('lang') || el.getAttribute('xml:lang');
+            if (lang) return lang;
+            node = node.parentNode;
+        } else if (node.nodeType === 11 /* DOCUMENT_FRAGMENT_NODE, incl. ShadowRoot */) {
+            node = (node as ShadowRoot).host ?? null;
+        } else {
+            node = null; // Document (9) or detached — stop
+        }
+    }
+    if (typeof document !== 'undefined' && document.documentElement.lang) {
+        return document.documentElement.lang;
+    }
+    return (typeof navigator !== 'undefined' && navigator.language) || undefined;
+}
 /**
  * Infer the most appropriate display property for an element
  * @param element - The element to infer the property for

package/inferencer/types/NewCustomElement.md CHANGED Viewed

@@ -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 CHANGED Viewed

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

package/inferencer/types/NewHTMLFirstCustomElement.md CHANGED Viewed

@@ -7,7 +7,12 @@
 - **[plus-minus](https://github.com/bahrus/plus-minus)** -- Expand / Collapse component - More robust examples of dynamic DOM manipulation with the help of roundabout configuration.  Also demonstrates use of the DX libraries to get typing intellisense help.
-- **[side-burger](https://github.com/bahrus/side-burger)** -- Side Drawer component with menu.
+- **[side-burger](https://github.com/bahrus/side-burger)** -- Side Drawer component with menu. Shows integration with many features, including swipe-dismiss, focus-trap-feature, others
+- **[up-down-counter](https://github.com/bahrus/up-down-counter)** -- Shows use of toLocaleString() formatting.
+- **[css-charts](https://github.com/bahrus/css-charts)** -- Wrapper around [charts.css](https://chartscss.org/). Demonstrates: reflecting boolean props onto a child element as CSS classes with the multi-invoke (`=*`) operator (see [Step 7 → "toggle a CSS class from a boolean property"](#how-can-i-toggle-a-css-class-from-a-boolean-property)); list rendering with `manageTemplateList`; and **"penciling in"** a package-local feature subclass (`CSSChartsH2OTable extends H2OTable`) via a string `spawn` when a shared feature needs element-specific logic (see [Step 7 → "give a shared feature element-specific logic"](#how-do-i-give-a-shared-feature-element-specific-logic-penciling-in)). Its `Chats/Conversion.md` is a blow-by-blow log of the trans-render → assign-gingerly conversion.
 ## Step 4
@@ -453,6 +458,176 @@ const raConfig = {
 [Please fully digest all the attribute parsing tha assign-gingerly provides before configuring the attributes.](https://github.com/bahrus/assign-gingerly/blob/baseline/docs/withAttrs.md)
+### How can I display a number with local formatting?
+**Goal:** the legacy `xtal-element` transform `"% count": "localize"` wrote
+`count.toLocaleString()` (e.g. `30000` → `"30,000"`) into the display element.
+Reproduce it declaratively by calling `toLocaleString` from inside the RHS path
+string of a `merge`.
+**How it works:** the `assign-gingerly` path evaluator normally *reads* each
+segment as a property. If a segment names a method that you listed in
+`withMethods`, it is *invoked* instead. When that method is the **last** segment,
+has **no `|` suffix**, and is **not followed by an argument segment**, it is
+called with zero arguments and its **return value becomes the resolved value**.
+So `'?.count?.toLocaleString'` resolves to `count.toLocaleString()` → `"30,000"`.
+> Contrast with the `|` suffix (e.g. `'?.deref|'`): that also calls the method
+> with no arguments but **discards** the return value — use `|` for side effects,
+> omit it when you want the result.
+**Wiring (in `el-maker.mjs`):**
+```JS
+import { akaMethods as m } from 'assign-gingerly/DX/emojis.js';
+// 1. Register toLocaleString as a callable method for the path evaluator.
+//    m['🌐'] is the DX alias for the string 'toLocaleString'.
+const withMethods = [m['🔍'], m['🌐']];
+const $ = (/** @type {typeof paths<RuntimeProps>} */ (/** @type {any} */(paths)))({ withMethods });
+const raConfig = {
+    assignOptions: {
+        akaMethods: {
+            '🔍': m['🔍'],   // querySelector
+            '🌐': m['🌐'],   // toLocaleString
+        },
+    },
+    merges: [
+        {
+            ifKeyIn: ['count'],
+            assign: {
+                // '?.count?.🌐' works too — the emoji is just an alias for the
+                // 'toLocaleString' segment. Both serialize to a plain string.
+                '?.countData?.textContent': '?.count?.toLocaleString',
+                value: '?.count',
+            },
+        },
+    ],
+    defaultPropVals: {
+        count: 30000,
+        name: '',
+    },
+};
+```
+**Passing a locale or options:** append the argument as the next segment, e.g.
+`'?.count?.toLocaleString?.en-US'` → `count.toLocaleString('en-US')`.
+**Serialization:** `render()` emits the segment as a literal string
+(`"?.count?.toLocaleString"`), so the generated `el-maker.json` stays fully
+JSON-serializable — no function is ever embedded.
+### How can I toggle a CSS class from a boolean property?
+**Goal:** the legacy `trans-render` transform `{sa: '.show-primary-axis', o: 'showPrimaryAxis'}`
+means "add class `show-primary-axis` when `showPrimaryAxis` is truthy, remove it
+otherwise." Reproduce it with the assign-gingerly **multi-invoke** (`=*`)
+operator, which calls one `withMethods` method **once per argument-list** on the RHS.
+**How it works:** `'?.el?.classList?.toggle =*'` calls `el.classList.toggle(...)`
+once for each entry in the RHS array. Each entry is `[className, condition]`. The
+`!!` prefix coerces the condition to a real boolean, so a missing / falsy source
+*removes* the class instead of flipping it — the whole merge is idempotent.
+`toggle` must be listed in `withMethods`.
+**Wiring (in `el-maker.mjs`):**
+```JS
+const raConfig = {
+    assignOptions: {
+        withMethods: ['querySelector', 'toggle'],
+    },
+    merges: smoothOver([
+        {
+            // capture the child once…
+            ifAllOf: ['clone'],
+            ...doAssign(set($.tableEl).to($.clone.querySelector('table'))),
+        },
+        {
+            // …then (re)run the toggles when the ref appears or any input flips
+            ifAllOf: ['tableEl'],
+            ifKeyIn: ['tableEl', 'isBar', 'isColumn', 'showLabels', 'showPrimaryAxis'],
+            assign: {
+                '?.tableEl?.classList?.toggle =*': [
+                    ['bar',               '!!?.isBar'],
+                    ['column',            '!!?.isColumn'],
+                    ['show-labels',       '!!?.showLabels'],
+                    ['show-primary-axis', '!!?.showPrimaryAxis'],
+                ],
+            },
+        },
+    ]),
+};
+```
+There is no DX (`$` / `set`) token for `=*` yet — write the key and the
+`[class, '!!?.prop']` pairs as plain strings inside `assign`. `smoothOver` leaves
+them untouched and they serialize straight to JSON.
+See [multi-invoke.md](https://github.com/bahrus/assign-gingerly/blob/baseline/docs/multi-invoke.md)
+and [css-charts](https://github.com/bahrus/css-charts) (a 10-class example) for more.
+### How do I give a shared feature element-specific logic? ("penciling in")
+Sometimes a reusable el-maker feature does *most* of what you need but not the
+last mile. Example: the `h2o-table` feature scrapes a slotted `<table>` into
+`[{ key, value }, …]`, but [css-charts](https://github.com/bahrus/css-charts) also
+has to scale those values per `chart-type` (`Math.max`, cumulative sums) —
+genuinely imperative code that can't be expressed as a merge.
+Rather than fork the feature or drop back to a full custom-element class, **pencil
+in a subclass defined inside your package and inject it by string `spawn`:**
+1. `MyH2OTable.js` at your package root — override just the hook the base exposes:
+   ```JS
+   import { H2OTable } from 'h2o-table/H2OTable.js';   // the generic base
+   export default class MyH2OTable extends H2OTable {
+       massageData(rows) {
+           const { chartType } = /** @type {any} */ (this.hostElement);
+           /* …element-specific transform… */
+           return rows;
+       }
+   }
+   ```
+2. Point the feature at it in `el-maker.mjs`:
+   ```JS
+   const features = {
+       assignFeatures: {
+           roundabout: { customData: { raConfig }, withAttrs },
+           templateMaker: {},
+           h2oTable: {
+               spawn: 'my-element/MyH2OTable.js',   // resolved via the import map
+               customData: { itemprops: ['key', 'value'] },
+           },
+       },
+   };
+   ```
+Why it works:
+- `assignFeatures` uses `featureConfig.spawn` when present and only falls back to
+  the catalog `fallbackSpawn` otherwise — so your subclass wins.
+- A string `spawn` is dynamically `import()`ed through the page's import map
+  (`"my-element/": "/"`), and the module's `default` export (or first exported
+  class) is used. `el-maker.json` stays pure JSON — the string is all that's stored.
+- The base must expose the hook (`massageData()` here) and any state the subclass
+  needs as **public** getters — `#private` fields are invisible across the
+  subclass boundary.
+- Pull the feature's output into the reactive graph with a merge, gated on
+  whatever changes its inputs:
+  `{ ifKeyIn: ['slotChangeCount', 'chartType'], assign: { data: '?.h2oTable?.data' } }`.
+  The feature re-computes lazily on read; the merge is what makes roundabout
+  re-read it.
+This keeps the generic feature reusable while the element-specific bit lives where
+it belongs. Once the pattern proves out, that logic can be promoted into the
+feature itself (config-driven) or published as its own feature.
 ## Step 8
@@ -469,7 +644,20 @@ Create a build instruction in package.json:
 ## Create the Demo Page
-For example:
+**Only the first instance of the custom element on the page carries the `imp-h`
+attribute and the `<script type=precede>`.** That first instance does the
+one-time global setup:
+- `imp-h="<name>/root.html"` imports the declarative shadow-DOM template once.
+- `<script type=precede data-extends=el-maker src="<name>/el-maker.json">`
+  registers the element (extends `ElementMaker`, applies the feature JSON) via
+  `customElements.define`.
+Once the element is defined, **every other instance is just the bare tag** —
+repeating `imp-h` or the `precede` script is unnecessary (and wasteful: it
+re-imports and re-registers). Subsequent instances upgrade automatically and
+reuse the same template and configuration; they can still set their own
+attributes.
 ```html
 <!DOCTYPE html>
@@ -488,10 +676,16 @@ For example:
 </head>
 <body>
     <be-hive></be-hive>
+    <!-- FIRST instance: imp-h + precede => imports the template and defines the element -->
     <plus-minus imp-h="plus-minus/root.html">
         <script type=precede data-extends=el-maker src="plus-minus/el-maker.json"></script>
     </plus-minus>
+    <!-- Every later instance is just the bare tag; attributes still work -->
+    <plus-minus></plus-minus>
+    <plus-minus expanded></plus-minus>
 </body>
 </html>
 ```

package/inferencer/types/NewJSFirstCustomElement.md CHANGED Viewed

@@ -30,11 +30,19 @@ export class MyElementElement extends ElementMaker {
 ## Optional Step 6: Create the Element-Specific Feature (if any)
-If your element has unique behavior beyond what the inherited features provide, but the functionality is more than trivial in implementing, consider creating a custom element feature for that functionality, following [NewCustomElementFeature.md](./NewCustomElementFeature.md).
+Most element-specific behavior can and should live directly in the element class (see Step 5). Reserve the custom element feature pattern for behavior that is genuinely reusable across multiple custom element projects.
-For example, `time-ticker` has a `TimeTicker.js` feature that provides precise drift-correcting ticking.
+Consider creating a custom element feature **only** when:
-If the feature proves useful beyond that one component, it is probably a good idea to move that feature into the el-maker package.
+- The behavior is non-trivial to implement, **and**
+- There is a significant chance that other custom element libraries would want to reuse it, **and**
+- Extracting it into a separate module improves testability or dependency management without adding unnecessary indirection.
+If the behavior is unique to a single element — for example, rendering chips for a specific `<select multiple>` UI pattern — keep the logic in the element class instead. Follow [NewCustomElementFeature.md](./NewCustomElementFeature.md) when a separate feature is warranted.
+`time-ticker`, for example, defines a `TimeTicker.js` feature because precise drift-correcting ticking is a generally useful capability.
+If a feature proves useful beyond the element that first introduced it, consider moving it into the `el-maker` catalog or publishing it as a standalone package.
 ## Step 7: Create defRef.mjs (Roundabout Configuration)

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

@@ -360,6 +360,14 @@ export interface IAssignGingerlyOptions {
    * ]
    */
   enhance?: Array<{ emc: string; matching?: string; parse?: boolean }>;
+  /**
+   * Handler implementations scoped to this call, forwarded to `assignFrom` when
+   * these options are reused by higher-level features (e.g. roundabout merges).
+   * Key: the `do` name referenced in handler configs. Value: a class
+   * constructor, an import path, or a `builtIns.*` alias string.
+   */
+  handlers?: Record<string, AssignFromHandlerConstructor | string>;
 }
 /**

package/inferencer/types/be-intl/types.d.ts ADDED Viewed

@@ -0,0 +1,68 @@
+import { ElementEnhancementGateway, SpawnContext } from "../assign-gingerly/types";
+export interface EndUserProps {
+    /**
+     * Intl.NumberFormatOptions / Intl.DateTimeFormatOptions, parsed as JSON from
+     * the base attribute (`be-intl='{ ... }'`). The semantic sub-attributes below
+     * are folded into a copy of this object by `onFormattingChange`; explicit JSON
+     * keys win over the semantic equivalents.
+     */
+    format?: Intl.NumberFormatOptions | Intl.DateTimeFormatOptions;
+    /** `be-intl-style` — e.g. "currency", "decimal", "percent". */
+    style?: string;
+    /** `be-intl-currency` — ISO 4217 code, e.g. "EUR". */
+    currency?: string;
+    /** `be-intl-weekday` — e.g. "long", "short", "narrow". */
+    weekday?: string;
+    /** `be-intl-year` — e.g. "numeric", "2-digit". */
+    year?: string;
+    /** `be-intl-month` — e.g. "long", "short", "numeric". */
+    month?: string;
+    /** `be-intl-day` — e.g. "numeric", "2-digit". */
+    day?: string;
+    /**
+     * BCP-47 locale tag. When not supplied explicitly it is derived from the
+     * enhanced element's `lang` attribute, falling back to the runtime default locale.
+     */
+    locale?: string;
+    /**
+     * When true, re-derive `locale` whenever the enhanced element's `lang` attribute changes.
+     * Off by default (the legacy `observeAttr` behavior).
+     */
+    observeLang?: boolean;
+}
+export interface AllProps extends EndUserProps {
+    enhancedElement: Element & ElementEnhancementGateway;
+    /**
+     * The raw value pulled off the enhanced element:
+     * a number for `<data>` / `<output>`, a Date for `<time>`.
+     */
+    value?: number | Date | string;
+    intlDateFormat?: Intl.DateTimeFormat;
+    intlNumberFormat?: Intl.NumberFormat;
+    resolved?: boolean;
+    /** Flipped true once `roundabout()` has finished its initial attribute-read pass. */
+    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;
+    onFormattingChange(self: AP): PAP;
+    formatNumber(self: AP): void;
+    formatDate(self: AP): void;
+}

package/inferencer/types/chip-away/types.d.ts ADDED Viewed

@@ -0,0 +1,71 @@
+import {IIdRefs} from '../id-referencer/types.d.ts';
+/**
+ * Public API properties for the chip-away custom element
+ */
+export interface EndUserProps {
+    /**
+     * Space-separated list of IDs for the select elements to mirror as chips
+     */
+    for: string;
+    /**
+     * When `true`, collapse each referenced `<select>` to a **single** chip
+     * whose label is a comma-delimited list of the selected option texts,
+     * instead of one chip per selected option. Its delete (✕) clears every
+     * selected option for that `<select>`.
+     *
+     * The boolean `join` attribute seeds the initial value (server-rendered
+     * config); after that, set the `join` property to change it at runtime — a
+     * `when_join_changes_call_hydrate` compact re-renders. Not a `sourceOfTruth`
+     * attribute, so the attribute is not kept in sync with the property.
+     */
+    join: boolean;
+    /**
+     * When `true`, render chips for display only — no per-option delete (✕), no
+     * per-`<select>` "clear all", and no joined-chip delete. The referenced
+     * `<select>` elements are not otherwise touched.
+     *
+     * Same wiring as {@link join}: boolean `readonly` attribute seeds the
+     * initial value, the `readonly` property is authoritative afterward, and a
+     * `when_readonly_changes_call_hydrate` compact re-renders.
+     */
+    readonly: boolean;
+    /**
+     * `join` only: once the number of selected options **exceeds** this, the
+     * single summary chip's label becomes `"<n> Selected"` instead of the
+     * comma-delimited list. Leave unset for no limit.
+     *
+     * Seeded from the numeric `max-join` attribute; the `maxJoin` property is
+     * authoritative afterward, and a `when_maxJoin_changes_call_hydrate` compact
+     * re-renders. See {@link join}.
+     */
+    maxJoin?: number;
+}
+/**
+ * Full property set including internal state managed by the custom element
+ */
+export interface AllProps extends EndUserProps {
+    /** `for` split on whitespace into an id list. */
+    splitFor: string[];
+}
+export type AP = AllProps;
+/**
+ * Runtime type for the custom element instance, including the lazily-spawned
+ * `idRefs` feature.
+ */
+export interface RunTimeProps extends AllProps, HTMLElement {
+    idRefs: IIdRefs
+}
+export interface Actions {
+    hydrate(self: AP): void;
+    temp(self: AP): void;
+}

package/inferencer/types/el-maker/types.d.ts CHANGED Viewed

@@ -3,6 +3,7 @@ import {FontFaceFeatureConfig} from '../font-face-feature/types.js';
 import {CustomData as TSCD} from '../truth-sourcer/types.js';
 import {CustomData as FUCD} from '../face-up/types.js';
 import {AttrPatterns} from '../assign-gingerly/types.js';
+import {IdRefsCustomData} from '../id-referencer/types.js';
 export interface ElMakerConfig<AllProps = any, TActions = AllProps> {
     assignFeatures: {
@@ -30,6 +31,21 @@ export interface ElMakerConfig<AllProps = any, TActions = AllProps> {
         truthSourcer?: {
             spawn?: string,
             customData?: TSCD
+        },
+        idRefs?: {
+            spawn?: string,
+            customData?: IdRefsCustomData
+        },
+        focusTrap?: {
+            spawn?: string,
+            customData?: any
+        },
+        h2oTable?: {
+            spawn?: string,
+            customData?: {
+                /** `itemprop` names to scrape from each `[itemscope]` row, in order. */
+                itemprops: string[]
+            }
         }
     }
-}
+}

package/inferencer/types/h2o-table/types.d.ts ADDED Viewed

@@ -0,0 +1,73 @@
+import { FeatureSpawnContext } from "../assign-gingerly/types";
+export { FeatureSpawnContext };
+/**
+ * Configuration for the `H2OTable` ("HTML → Object Table") feature, supplied via
+ * the injection's `customData`.
+ *
+ * ```js
+ * customElements.assignFeatures(MyElement, {
+ *     h2oTable: { customData: { itemprops: ['key', 'value'] } }
+ * });
+ * ```
+ */
+export interface CustomData {
+    /**
+     * The `itemprop` names to read from each light-DOM `[itemscope]` row, in
+     * order. Each one becomes a key on the matching {@link DataRecord}.
+     */
+    itemprops: string[];
+}
+/**
+ * One extracted row: each configured `itemprop` name mapped to the value the
+ * assign-gingerly inferencer reads for that element (`<data>`/`<input type=number>`
+ * → number, `<time>` → date string, form controls → `value`, anything else →
+ * `textContent`). Props whose element is missing from a given row are omitted.
+ */
+export type DataRecord = Record<string, any>;
+/**
+ * The members the feature exposes on `host.h2oTable`.
+ */
+export interface IH2OTable {
+    /**
+     * The host's light-DOM `[itemscope]` rows, projected onto plain objects
+     * using the configured {@link CustomData.itemprops} and then passed through
+     * {@link IH2OTable.massageData}. Re-scraped from the DOM on every read —
+     * there is no caching, so it always reflects the current light DOM.
+     */
+    readonly data: DataRecord[];
+    /**
+     * The configured `itemprop` names, in order.
+     */
+    readonly itemprops: string[];
+    /**
+     * Post-process hook, called by {@link IH2OTable.data} with the freshly
+     * scraped rows. The base class implements this as the identity function;
+     * subclasses override it to add computed columns, filter, sort, etc.
+     */
+    massageData(data: DataRecord[]): DataRecord[];
+}
+/**
+ * Public prop surface — alias kept for parity with the other el-maker feature
+ * type modules (`TemplateMakerProps`, `TruthSourcerProps`, …).
+ */
+export interface H2OTableProps extends IH2OTable {}
+/**
+ * Full internal state of an `H2OTable` instance.
+ */
+export interface AllProps extends H2OTableProps {
+    /** WeakRef back to the host custom element. */
+    hostRef: WeakRef<HTMLElement> | null;
+    /** Resolved copy of {@link CustomData.itemprops}. */
+    itemprops: string[];
+}
+export type AP = AllProps;
+export type PAP = Partial<AP>;

package/inferencer/types/id-referencer/types.d.ts ADDED Viewed

@@ -0,0 +1,35 @@
+import { FeatureSpawnContext } from "../assign-gingerly/types";
+export { FeatureSpawnContext };
+/**
+ * Configuration for the `IdRefs` feature, supplied via the injection's
+ * `customData`.
+ *
+ * Note: this local variant is handed its id list directly (via
+ * `idRefs.searchFor = string[]`) rather than reading a host attribute, so there is
+ */
+export interface IdRefsCustomData {
+    /**
+     * Event dispatched on the host whenever a DOM-mutation-driven pass changes
+     * the resolved element set. Defaults to `'id-referencer:resolved'`.
+     */
+    eventType?: string;
+}
+/**
+ * `detail` payload of the event named by {@link IdRefsCustomData.eventType}.
+ */
+export interface IdRefsResolvedDetail {
+    /** The ordered id list currently being resolved. */
+    ids: string[];
+    /** The resolved, still-connected elements, in id order. */
+    elements: Element[];
+}
+export interface IIdRefs {
+    searchFor: string[];
+    readonly elements: Element[];
+}

package/inferencer/types/inferencer/types.d.ts CHANGED Viewed

@@ -15,14 +15,32 @@ export declare const display: symbol;
  */
 export declare class Infer<TValue = any, TDisplay = any> {
     get enhancedElement(): Element;
-    constructor(enhancedElement?: Element);
+    constructor(enhancedElement?: Element, propName?: string);
+    /** Live, type-coerced read of the element's inferred value property. */
     get value(): TValue | undefined;
     set value(nv: TValue);
     get display(): TDisplay | undefined;
     set display(nv: TDisplay);
     get eventType(): string;
+    /** The inferred value property name (e.g. 'value', 'checked', 'dateTime'). */
+    get valueProperty(): string;
+    get defaultRemoteBindingPropName(): string;
+    /**
+     * EventTarget that emits an event named after the changed property.
+     * Custom elements with a native propagator return that; otherwise an
+     * InferencedPropagator using best-effort change detection.
+     */
+    getPropagator(): Promise<EventTarget>;
+    setDisplay(vm: any): void;
 }
+/**
+ * Read the inferred value property off an element and coerce it to a natural
+ * JavaScript type (Date for <time>, number/boolean via JSON parse for <data>,
+ * schema.org itemtype hints honored, textContent verbatim).
+ */
+export declare function coerceElementValue(element: Element, propName?: string): any;
 /**
  * Registry item for the Infer enhancement
  */

package/inferencer/types/nested-regex-groups/types.d.ts CHANGED Viewed

@@ -103,6 +103,8 @@ export interface ParserOptions {
    * // With normalizeWhitespace: false -> "  First.   Second.  "
    */
   normalizeWhitespace?: boolean;
+  delimiter?: string;
 }
 /**

package/inferencer/types/swipe-dismiss/types.d.ts CHANGED Viewed

@@ -38,6 +38,20 @@ export interface AllProps extends SwipeDismissProps {
     /** WeakRef to the host custom element. */
     hostRef: WeakRef<Element>;
+    /** Live gesture progress, refreshed on every pointermove and on release. */
+    progressState: {
+        /** Always-positive drag magnitude along the axis, clamped to panel size. */
+        deltaPx: number;
+        /** `deltaPx` as a fraction of panel size (0–1). */
+        fraction: number;
+        /**
+         * `deltaPx` signed for a screen-space `translate`: negative for a
+         * left/up drawer, positive for right/down. Feed this straight into
+         * `translateX()` / `translateY()` so the panel follows the finger
+         * regardless of which edge it is docked to.
+         */
+        translatePx: number;
+    };
 }
 export type AP = AllProps;

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.91",
+  "version": "0.0.93",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {

package/types/assign-gingerly/types.d.ts CHANGED Viewed

@@ -360,6 +360,14 @@ export interface IAssignGingerlyOptions {
    * ]
    */
   enhance?: Array<{ emc: string; matching?: string; parse?: boolean }>;
+  /**
+   * Handler implementations scoped to this call, forwarded to `assignFrom` when
+   * these options are reused by higher-level features (e.g. roundabout merges).
+   * Key: the `do` name referenced in handler configs. Value: a class
+   * constructor, an import path, or a `builtIns.*` alias string.
+   */
+  handlers?: Record<string, AssignFromHandlerConstructor | string>;
 }
 /**