assign-gingerly 0.0.96 → 0.0.97

package/README.md

@@ -1594,7 +1594,83 @@ When you access `element.enh.set.enhKey.property`, the proxy:
    - If a non-matching object already exists at `element.enh[enhKey]`, it's passed as `initVals`
    - Stores the spawned instance at `element.enh[enhKey]`
 3. **Reuses existing instances**: If the enhancement already exists and is the correct type, it reuses it
-4. **Falls back to plain objects**: If no registry item is found, creates a plain object at `element.enh[enhKey]`
+4. **Falls back to plain objects, and waits for registration**: If no registry item is found yet, creates a plain object at `element.enh[enhKey]` and calls `registry.whenDefined(enhKey)` to spawn the real instance automatically once the registry item eventually arrives — see [Setting Properties Before the Registry Item Exists](#setting-properties-before-the-registry-item-exists) below
+
+</details>
+
+### Setting Properties Before the Registry Item Exists
+
+Code doesn't always run in the order you'd like — a module might set
+properties on an enhancement before whatever registers that enhancement's
+config has had a chance to run. `enh.set` handles this automatically, the
+same way `element.enh.set.enhKey.property = value` does when the registry
+item is already there:
+
+```TypeScript
+import 'assign-gingerly/object-extension.js';
+
+const myElement = document.createElement('div');
+
+// Nothing has called `registry.push(...)` for 'myEnh' yet.
+myElement.enh.set.myEnh.myProp = 'hello';        // plain placeholder, collected as pending initVals
+myElement.enh.myEnh.anotherProp = 'world';        // direct property access works too, same placeholder
+
+console.log(myElement.enh.myEnh instanceof MyEnhancement); // false -- still a plain object
+
+// ...later, whenever the registry item shows up...
+const registry = myElement.customElementRegistry.enhancementRegistry;
+registry.push({ spawn: MyEnhancement, enhKey: 'myEnh' });
+
+// The spawn happens automatically once `whenDefined` resolves -- no need to
+// touch `myElement.enh.myEnh` again yourself.
+await registry.whenDefined('myEnh');
+console.log(myElement.enh.myEnh instanceof MyEnhancement); // true
+console.log(myElement.enh.myEnh.myProp);                   // 'hello' -- both properties
+console.log(myElement.enh.myEnh.anotherProp);               // 'world' -- survived as initVals
+```
+
+<details>
+<summary>How it works</summary>
+
+1. The first `enh.set.enhKey.property = value` assignment for an
+   unregistered `enhKey` creates a plain object at `element.enh[enhKey]` (as
+   always) and, in addition, calls
+   `registry.whenDefined(enhKey).then(() => element.enh.get(enhKey))`.
+2. Because that call only happens inside the `if (self[prop] === undefined)`
+   branch, it fires exactly once per element/`enhKey` pair — further property
+   assignments before registration just add to the same placeholder object,
+   they don't queue additional spawn attempts.
+3. `registry.whenDefined(enhKey)` resolves once a matching `enhKey` is
+   `push`ed into the registry (see below).
+4. Once it resolves, `enh.get(enhKey)` runs — the same method used everywhere
+   else in this library. It finds the plain placeholder already sitting at
+   `element.enh[enhKey]`, treats it as `initVals` (this is the same
+   "non-matching object passed as `initVals`" behavior described in step 2 of
+   [How It Works](#basic-usage) above — nothing new here), constructs the real
+   instance, and overwrites the placeholder with it.
+
+**`EnhancementRegistry.whenDefined(enhKey)`** — mirrors
+[`customElements.whenDefined(name)`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/whenDefined):
+
+- If `enhKey` is already registered, resolves once any of its pending
+  [Custom Element Features](#custom-element-features) setup has settled (see
+  `features` on `EnhancementConfig`).
+- If `enhKey` isn't registered yet, first waits for a future `registry.push(...)`
+  call whose config (a single item, or an array) includes a matching `enhKey`,
+  then does the same features-setup wait.
+- **If `enhKey` is never registered, this promise never resolves** — same
+  tradeoff `customElements.whenDefined` makes. Don't `await` it unconditionally
+  in code paths where registration isn't guaranteed to eventually happen.
+
+**Limitations while waiting:**
+- The placeholder is a plain object — no reactivity, no defaults, no
+  validation. Reading a property other than the ones you've explicitly set
+  (e.g. checking `resolved`) just returns `undefined`, since nothing has
+  spawned yet.
+- `mountCtx` still isn't available through this path (same restriction as
+  `enh.set` generally — see the note in
+  [Passing Custom Context](#constructor-signature) above); the eventual
+  `enh.get(enhKey)` call is made with no `mountCtx`.
 
 </details>
 

package/assignGingerly.js

@@ -63,10 +63,27 @@ export class EnhancementRegistry extends EventTarget {
         }
     }
     /**
-     * Wait for all pending setups for a given enhancement key to complete.
+     * Resolves once `enhKey` is defined -- i.e. registered via `push` -- and
+     * ready (any pending `features` setup for it has settled). Mirrors
+     * `customElements.whenDefined(name)`: if the key isn't registered yet, waits
+     * for a future `push` that registers it; if it's never registered, this
+     * never resolves (same tradeoff as the platform method).
      * @param enhKey - Enhancement key to wait for
      */
     async whenDefined(enhKey) {
+        if (!this.findByEnhKey(enhKey)) {
+            await new Promise((resolve) => {
+                const handler = (event) => {
+                    const config = event.config;
+                    const items = Array.isArray(config) ? config : [config];
+                    if (items.some(item => item.enhKey === enhKey)) {
+                        this.removeEventListener(EnhancementRegisteredEvent.eventName, handler);
+                        resolve();
+                    }
+                };
+                this.addEventListener(EnhancementRegisteredEvent.eventName, handler);
+            });
+        }
         const pending = this.#pendingSetups.get(enhKey);
         if (pending && pending.length > 0) {
             await Promise.all(pending);

package/assignGingerly.ts

@@ -106,10 +106,27 @@ export class EnhancementRegistry extends EventTarget {
   }
 
   /**
-   * Wait for all pending setups for a given enhancement key to complete.
+   * Resolves once `enhKey` is defined -- i.e. registered via `push` -- and
+   * ready (any pending `features` setup for it has settled). Mirrors
+   * `customElements.whenDefined(name)`: if the key isn't registered yet, waits
+   * for a future `push` that registers it; if it's never registered, this
+   * never resolves (same tradeoff as the platform method).
    * @param enhKey - Enhancement key to wait for
    */
   async whenDefined(enhKey: EnhKey): Promise<void> {
+    if (!this.findByEnhKey(enhKey)) {
+      await new Promise<void>((resolve) => {
+        const handler = (event: Event) => {
+          const config = (event as EnhancementRegisteredEvent).config;
+          const items = Array.isArray(config) ? config : [config];
+          if (items.some(item => item.enhKey === enhKey)) {
+            this.removeEventListener(EnhancementRegisteredEvent.eventName, handler);
+            resolve();
+          }
+        };
+        this.addEventListener(EnhancementRegisteredEvent.eventName, handler);
+      });
+    }
     const pending = this.#pendingSetups.get(enhKey);
     if (pending && pending.length > 0) {
       await Promise.all(pending);

package/inferencer/types/EnhancementConversionInstructions.md

@@ -107,7 +107,7 @@ Update the package.json to use the modern architecture's dependencies and build
      "nested-regex-groups": "*"
    }
    ```
-   - Drop the legacy dependencies (`be-enhanced`, `trans-render`, etc.). Keep a legacy dependency **only** if a converted action still imports from it and the modern stack has no replacement (e.g. `trans-render/XV/set.js` for the Uniform Storage Path protocol) — note any such carry-over in your conversion notes.
+   - Drop the legacy dependencies (`be-enhanced`, `trans-render`, etc.). There is a modern replacement for most legacy utilities — e.g. Uniform Storage Path writes move from `trans-render/XV/set.js` to [`fifteenth`](https://github.com/bahrus/fifteenth) (`fifteenth/set.js`, see Step 9). Keep a legacy dependency **only** if a converted action still imports from it and no replacement exists — and note any such carry-over in your conversion notes.
    - `mount-observer` is listed as a direct dependency so it lands at the root `node_modules/` level, accessible via the import map. `nested-regex-groups` is optional but recommended if your enhancement needs custom attribute parsing (Step 7a).
    - The exact version strings do not matter here — the next step replaces them all with the latest published versions.
 
@@ -969,6 +969,14 @@ export interface Actions{
 7. **Update utility imports**:
    - Replace `trans-render/lib/findAdjacentElement.js` with `be-hive/findAdjacentElement.js`
    - The be-hive package provides common utilities that were previously in trans-render
+   - **Uniform Storage Path (USL) writes** — if a legacy action wrote values to `indexedDB://…`, `localStorage://…`, etc. via `trans-render/XV/set.js`, use [`fifteenth`](https://github.com/bahrus/fifteenth) instead:
+     ```javascript
+     const { set } = await import('fifteenth/set.js');
+     await set('indexedDB://myDB/myStore/myKey', value);   // same (usl, val, ctx?) signature as XV/set
+     ```
+     - Add `"fifteenth"` to `dependencies` and a `"fifteenth/": "/node_modules/fifteenth/"` entry to the import map.
+     - `fifteenth` imports `parseProtocolRef` from `assign-gingerly@0.0.96`+. `roundabout-lib` / `mount-observer` may still pin an older `assign-gingerly` exactly, and the flat import map can only serve one copy — so also add `"assign-gingerly": "<the version fifteenth needs>"` to `dependencies` to hoist a single root copy. Verify the be-hive/mount-observer/roundabout read path still works against that version.
+     - **Behavior change to note in your conversion notes:** `fifteenth`'s `set` broadcasts `window.postMessage([usp])` (or `[usp, usl]` when the USL has a `?.` accessor chain) — a plain `Array` of path strings, *not* the `Set` (protocol + store-root + full-path) that `trans-render/XV` posted. Update any `message` listeners accordingly.
 
 **CRITICAL - Avoid Compact/Action Conflicts:**
 

package/inferencer/types/ImportantEnhancementAddendum.md

@@ -0,0 +1,46 @@
+# Clarify Programmatic Way to Add Enhancements
+
+When we define an enhancement, it is easiest to demonstrate what it does and how it works by providing simple HTML examples with the attributes used to trigger the enhancement.
+
+These examples are skewed towards an important use case -- progressive enhancement of server rendered content.
+
+However, currently, only a small fraction of web development centers around that paradigm.  Rather, it tends to revolve around client-side rendering, using a framework.
+
+In such a context, putting so much emphasis on the attribute way of hooking things up is problematic.  
+
+1.  Such frameworks are clumsy when it comes to setting attributes.
+2.  The amount of object stringifying and parsing is inefficient.
+
+So we should make an effort to showcase how to integrate with these enhancements efficiently and ergonomically in such settings.  Basically programmatically without the use of attributes.
+
+I think we should showcase two ways to do so.
+
+So for example, currently the README.md for be-persistent shows the example:
+
+```html
+<input be-persistent="of value@input via sessionStorage://{autoGenId}.">
+```
+
+We should also show:
+
+## Imperative Enhancement Attachment:
+
+```JS
+import {emc} from 'be-persistent/emc.json' with {type: 'json'};
+import {BePersistent} from 'be-persistent/be-persistent.js';
+emc.spawn = BePersistent;
+const persistenceEnhancement = oInput.enh.get(emc);
+persistenceEnhancement.store = 
+    {
+        localProp: 'value', //default
+        localEvent: 'input', //default
+        usl: 'sessionStorage://{autoGenId}'
+    };
+```
+
+## Declarative Enhancement Attachment:
+
+```JS
+import 'be-persistent/.js';
+
+```

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

@@ -72,6 +72,8 @@ export interface EnhancementConfig<T = any, Obj = Element> extends EnhancementCo
    * Calls assignFeatures(spawn, features) automatically on registration.
    */
   features?: FeatureConfigsMap;
+
+  customData?: any;
     
 }
 
@@ -406,7 +408,7 @@ export interface AssignFromOptions {
   from: any;
 
   /** Protocol handlers (sync or async) */
-  protocols?: Record<string, (key: string) => any | Promise<any>>;
+  protocols?: ProtocolHandlers;
 
   /** Method names to call during path evaluation (append `|` to a path segment for a zero-argument call) */
   withMethods?: string[] | Set<string>;
@@ -480,6 +482,37 @@ export interface AssignFromOptions {
   [key: string]: any;
 }
 
+/**
+ * A protocol handler resolves the key portion of a protocol-prefixed value
+ * (the text between `://` and the first `?.`) to a value. May be sync or async.
+ */
+export type ProtocolHandler = (key: string) => any | Promise<any>;
+
+/**
+ * A synchronous-only protocol handler, as accepted by getValues / getValue /
+ * assignFrom. For handlers that may return a Promise, use ProtocolHandler.
+ */
+export type SyncProtocolHandler = (key: string) => any;
+
+/** Map of protocol name (the text before `://`) to a handler (sync or async). */
+export type ProtocolHandlers = Record<string, ProtocolHandler>;
+
+/** Map of protocol name to a synchronous handler. */
+export type SyncProtocolHandlers = Record<string, SyncProtocolHandler>;
+
+/**
+ * The outer grammar of a protocol-prefixed value string,
+ * `‹protocol›://‹key›?.‹path›`, as produced by `parseProtocolRef`.
+ */
+export interface ParsedProtocolRef {
+    /** Text before `://`; `''` when the value contains no `://`. */
+    protocol: string;
+    /** Text between `://` and the first `?.` (or the end of the string). */
+    key: string;
+    /** Text from the first `?.` onward (always starts with `?.`), or `null`. */
+    path: string | null;
+}
+
 /**
  * Options for synchronous value resolution (getValues / getValue).
  * Extends IAssignGingerlyOptions with synchronous protocol handlers.
@@ -507,7 +540,7 @@ export interface GetValuesOptions extends IAssignGingerlyOptions {
    *     localStorage: (key) => JSON.parse(localStorage.getItem(key) || 'null')
    * }
    */
-  protocols?: Record<string, (key: string) => any>;
+  protocols?: SyncProtocolHandlers;
 }
 
 /**
@@ -530,7 +563,7 @@ export interface ResolveValuesOptions extends IAssignGingerlyOptions {
    * Protocol handlers for resolving protocol-prefixed values (e.g., 'globalThis://key').
    * Each handler receives the key portion and returns the resolved value (sync or async).
    */
-  protocols?: Record<string, (key: string) => any | Promise<any>>;
+  protocols?: ProtocolHandlers;
 }
 
 /**

package/inferencer/types/be-literate/types.d.ts

@@ -1,6 +1,6 @@
 /**
  * Uniform Storage Path string (e.g. "indexedDB://myDB/myFiles/{file.name}").
- * Inlined here (was imported from trans-render/XV/types) to keep this file standalone.
+ * Consumed by `fifteenth`'s `set`. Kept as a local alias so this file stays standalone.
  */
 export type USL = string;
 

package/inferencer/types/be-persistent/types.d.ts

@@ -0,0 +1,81 @@
+import { ElementEnhancementGateway, SpawnContext } from "../assign-gingerly/types";
+import { StatementsResult } from "../nested-regex-groups/types";
+
+/**
+ * The programmatic shape of `store`: a bare USL string (shorthand for
+ * `{usl}`, i.e. `localProp`/`localEvent` take their defaults), a single
+ * {@link PersistenceRule}, or an array of them (one binder per entry).
+ * This is the property JS callers set directly — e.g.
+ * `persistenceEnhancement.store = 'sessionStorage://{autoGenId}'` — without
+ * ever going through attribute parsing.
+ */
+export type PersistenceRuleConfig = string | PersistenceRule | PersistenceRule[];
+
+export interface EndUserProps {
+    /**
+     * What to persist and where. Accepts a USL string, a single
+     * {@link PersistenceRule}, or an array of rules — see
+     * {@link PersistenceRuleConfig}. This is the property `hydrate` reads and
+     * the one programmatic (attribute-free) callers should assign.
+     */
+    store?: PersistenceRuleConfig;
+    /**
+     * Opt-in flag set by the boolean `be-persistent-nudge` / `💾-nudge`
+     * attribute.  When present, `hydrate` waits for every rule to finish its
+     * initial storage reconciliation and then calls `assign-gingerly`'s
+     * `nudge` on the enhanced element — decrementing its `disabled` counter so
+     * an element that was disabled only to block edits before its persisted
+     * value loaded becomes interactive.
+     */
+    nudge?: boolean;
+}
+
+export interface AllProps extends EndUserProps {
+    enhancedElement: Element & ElementEnhancementGateway;
+    resolved?: boolean;
+    /**
+     * Flipped to `true` at the end of `init`, once `roundabout` has finished
+     * assigning every attribute-derived prop.  `hydrate` is gated on it so it
+     * never runs against a half-populated view model.
+     */
+    initialized?: boolean;
+    /**
+     * Raw parse result of the base attribute (`be-persistent` / `💾`), via the
+     * `parse-grouped-capture-statements` built-in parser. Exists **only** to be
+     * transferred into `store` by `onPersistenceRulesChange` — nothing else
+     * reads it. Programmatic callers should assign `store` directly instead of
+     * this property.
+     */
+    persistenceRules?: StatementsResult<PersistenceRule>;
+}
+
+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>;
+    /**
+     * Compact-invoked (`when_persistenceRules_changes_call_onPersistenceRulesChange`),
+     * not an action — normalizes `persistenceRules.statements` into `store`.
+     */
+    onPersistenceRulesChange(self: AP): PAP;
+    hydrate(self: AP): ProPAP;
+}
+
+export interface PersistenceRule {
+    /** Element property to read/write (e.g. `value`, `checked`, `innerHTML`). Defaults to `value`. */
+    localProp?: string;
+    /** DOM event that triggers a save. Defaults to `input`. */
+    localEvent?: string;
+    /**
+     * Uniform Storage Locator describing where the value lives, e.g.
+     * `sessionStorage://{autoGenId}`, `indexedDB://myDB/myStore/{autoGenId}`,
+     * `cookie://{autoGenId}`, `locationHash://{autoGenId}`.
+     * `{autoGenId}` is expanded at runtime to a location-independent DOM path.
+     * Defaults to `sessionStorage://{autoGenId}`.
+     */
+    usl?: string;
+}

package/inferencer/types/gist-in/types.d.ts

@@ -0,0 +1,59 @@
+import { ElementEnhancementGateway, SpawnContext } from "../assign-gingerly/types";
+
+export interface EndUserProps {
+    /**
+     * Where to fetch the replacement content from — either a literal URL
+     * (typically a `gist.githubusercontent.com/.../raw/.../<file>` URL) or a
+     * `fifteenth` `gist://` USL (`gist://<owner>/<id>/raw[/<sha>]/<file>`,
+     * or an alias/`=<id>` form once `configureGist()` has registered the
+     * `gist` protocol).
+     */
+    url: string;
+    /** The `<?marker name="…">` this template's content replaces. */
+    markerName: string;
+    /**
+     * CSS selector naming the parent(s) of the marker(s), so the search
+     * doesn't have to `TreeWalker` the whole subtree. Optional.
+     */
+    forHint: string | undefined;
+    /**
+     * Show a link to edit the gist on GitHub right after the template.
+     * Also triggered page-wide by `?gist-in-show-edit-link=true` in the URL.
+     */
+    showEditLink: boolean;
+    /**
+     * Custom Sanitizer configuration (JSON object, e.g.
+     * `{"elements":["option","optgroup"]}`), same shape as pipe-in's
+     * `[base]-sanitizer`. The platform's *default* sanitizer strips elements
+     * like `<option>` entirely — this is the escape hatch for patching them.
+     * Gated the same way pipe-in gates it: only honored when `url` is a
+     * same-origin path, an import-map-resolved bare specifier, or a
+     * `gist://` USL (whose real destination is always the fixed
+     * `gist.githubusercontent.com` host, not attacker-steerable).
+     */
+    sanitizer: object | undefined;
+    /**
+     * `'setHTML'` (default, sanitized) or `'setHTMLUnsafe'` (no sanitizing at
+     * all) — named after, and selecting between, the two real underlying
+     * methods, the same way pipe-in's `[base]-method` selects one of its own
+     * `streamHTML`/`streamHTMLUnsafe`/etc. `'setHTMLUnsafe'` is gated the same
+     * as a custom `sanitizer` (see above). Never runs embedded `<script>`s
+     * either way — `setHTML`/`setHTMLUnsafe` parse, they don't execute
+     * (verified; same as plain `innerHTML`).
+     */
+    method: 'setHTML' | 'setHTMLUnsafe';
+}
+
+export interface AllProps extends EndUserProps {
+    enhancedElement: Element & ElementEnhancementGateway;
+    resolved: boolean;
+}
+
+export type AP = AllProps;
+export type PAP = Partial<AP>;
+export type ProPAP = Promise<PAP>;
+
+export interface Actions {
+    init(self: AP, enhancedElement: Element, ctx: SpawnContext, initVals: PAP): Promise<void>;
+    hydrate(self: AP): ProPAP;
+}

package/object-extension.js

@@ -317,6 +317,16 @@ class ElementEnhancementContainer {
                     // No registry item found - create plain object if needed
                     if (self[prop] === undefined) {
                         self[prop] = {};
+                        // Declarative-out-of-sequence: `prop`'s enhancement config hasn't
+                        // been registered yet. Once it is, hand the plain object we just
+                        // created off to `get()` as pending initVals and let it spawn
+                        // normally -- `get()` already treats a non-instance value sitting
+                        // in this slot as initVals to merge in (see the `existingInitVals`
+                        // check above). If `prop` is never registered, this never
+                        // resolves (same tradeoff as `customElements.whenDefined`).
+                        const laterRegistry = registry
+                            ?? (typeof customElements !== 'undefined' ? customElements.enhancementRegistry : undefined);
+                        laterRegistry?.whenDefined(prop).then(() => self.get(prop));
                     }
                     return self[prop];
                 }

package/object-extension.ts

@@ -443,8 +443,19 @@ class ElementEnhancementContainer {
           // No registry item found - create plain object if needed
           if (self[prop] === undefined) {
             self[prop] = {};
+
+            // Declarative-out-of-sequence: `prop`'s enhancement config hasn't
+            // been registered yet. Once it is, hand the plain object we just
+            // created off to `get()` as pending initVals and let it spawn
+            // normally -- `get()` already treats a non-instance value sitting
+            // in this slot as initVals to merge in (see the `existingInitVals`
+            // check above). If `prop` is never registered, this never
+            // resolves (same tradeoff as `customElements.whenDefined`).
+            const laterRegistry = registry
+              ?? (typeof customElements !== 'undefined' ? (customElements as any).enhancementRegistry : undefined);
+            laterRegistry?.whenDefined(prop).then(() => self.get(prop));
           }
-          
+
           return self[prop];
         }
       }) as any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.96",
+  "version": "0.0.97",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -228,7 +228,7 @@
     "chrome": "npx playwright cr http://localhost:8000"
   },
   "devDependencies": {
-    "@playwright/test": "1.62.1",
-    "spa-ssi": "0.0.27"
+    "@playwright/test": "1.63.0",
+    "spa-ssi": "0.0.28"
   }
 }

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

@@ -72,6 +72,8 @@ export interface EnhancementConfig<T = any, Obj = Element> extends EnhancementCo
    * Calls assignFeatures(spawn, features) automatically on registration.
    */
   features?: FeatureConfigsMap;
+
+  customData?: any;
     
 }