assign-gingerly 0.0.81 → 0.0.83

package/assignFromAsync.js

@@ -35,6 +35,7 @@ export async function assignFromAsync(target, pattern, options, permissionProces
             withMethods: options.withMethods,
             aka: options.aka,
             akaMethods: options.akaMethods,
+            substitutions: options.substitutions,
             protocols: options.protocols,
             root: target,
             permissionProcessor
@@ -47,7 +48,7 @@ export async function assignFromAsync(target, pattern, options, permissionProces
     if (idRefNormalKeys.length > 0 && (options.pin || options.at)) {
         const ids = { ...options.pin, ...options.at };
         const { resolveIdVariable, parseIdRef } = await import('./resolve/resolveIdRef.js');
-        const { withMethods, aka, akaMethods, protocols, from } = options;
+        const { withMethods, aka, akaMethods, protocols, from, substitutions } = options;
         for (const key of idRefNormalKeys) {
             const parsed = parseIdRef(key);
             if (!parsed)
@@ -58,13 +59,13 @@ export async function assignFromAsync(target, pattern, options, permissionProces
             const value = expandedPattern[key];
             if (parsed.remainingPath) {
                 // Resolve the RHS value
-                const resolvedValue = await resolveValues({ __v: value }, from, { withMethods, aka, akaMethods, protocols, root: el, permissionProcessor });
+                const resolvedValue = await resolveValues({ __v: value }, from, { withMethods, aka, akaMethods, substitutions, protocols, root: el, permissionProcessor });
                 // Apply remaining path on the resolved element
                 assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options, permissionProcessor);
             }
             else {
                 // No remaining path — resolve and assign directly to the element
-                const resolvedValue = await resolveValues(typeof value === 'object' && value !== null ? value : { __v: value }, from, { withMethods, aka, akaMethods, protocols, root: el, permissionProcessor });
+                const resolvedValue = await resolveValues(typeof value === 'object' && value !== null ? value : { __v: value }, from, { withMethods, aka, akaMethods, substitutions, protocols, root: el, permissionProcessor });
                 if ('__v' in resolvedValue) {
                     // Single value — can't assign to element root without a path
                 }

package/assignFromAsync.ts

@@ -69,6 +69,7 @@ export async function assignFromAsync(
       withMethods: options.withMethods,
       aka: options.aka,
       akaMethods: options.akaMethods,
+      substitutions: options.substitutions,
       protocols: options.protocols,
       root: target,
       permissionProcessor
@@ -84,7 +85,7 @@ export async function assignFromAsync(
   if (idRefNormalKeys.length > 0 && (options.pin || options.at)) {
     const ids = { ...options.pin, ...options.at };
     const { resolveIdVariable, parseIdRef } = await import('./resolve/resolveIdRef.js');
-    const { withMethods, aka, akaMethods, protocols, from } = options;
+    const { withMethods, aka, akaMethods, protocols, from, substitutions } = options;
     for (const key of idRefNormalKeys) {
       const parsed = parseIdRef(key);
       if (!parsed) continue;
@@ -97,7 +98,7 @@ export async function assignFromAsync(
         // Resolve the RHS value
         const resolvedValue = await resolveValues(
           { __v: value }, from,
-          { withMethods, aka, akaMethods, protocols, root: el, permissionProcessor }
+          { withMethods, aka, akaMethods, substitutions, protocols, root: el, permissionProcessor }
         );
         // Apply remaining path on the resolved element
         assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options, permissionProcessor);
@@ -106,7 +107,7 @@ export async function assignFromAsync(
         const resolvedValue = await resolveValues(
           typeof value === 'object' && value !== null ? value : { __v: value },
           from,
-          { withMethods, aka, akaMethods, protocols, root: el, permissionProcessor }
+          { withMethods, aka, akaMethods, substitutions, protocols, root: el, permissionProcessor }
         );
         if ('__v' in resolvedValue) {
           // Single value — can't assign to element root without a path

package/inferencer/types/NewCustomElement.md

@@ -60,7 +60,7 @@ Create `types/[project-name]/types.d.ts` with the element's property interface:
 /**
  * Properties specific to this custom element
  */
-export interface ElementProps {
+export interface EndUserProps {
     // Properties unique to this element
     myProp: string;
     disabled: boolean;
@@ -69,18 +69,21 @@ export interface ElementProps {
 /**
  * Full property set including internal state
  */
-export interface AllProps extends ElementProps {
+export interface AllProps extends EndUserProps {
     idx: number;
     item: any;
 }
 
-export type T = AllProps;
+export type AP = AllProps;
+
+export interface RunTimeProps extends AllProps, HTMLElement
+
 ```
 
 **Key points:**
-- `ElementProps` — the public API specific to this element
+- `EndUserProps` — the public API specific to this element
 - `AllProps` — includes internal/computed state managed by roundabout
-- Export `T` as a convenience alias for use in `defRef.mjs` type annotations
+- Export `AP` as a convenience alias 
 
 
 ## Step 4: Create imports.html

package/inferencer/types/NewHTMLFirstCustomElement.md

@@ -238,17 +238,17 @@ import { fileURLToPath } from 'url';
 import {akaMethods as m, aka, builtInEmoji} from 'assign-gingerly/DX/emojis.js';
 import {paths, doAssign, set, smoothOver} from 'assign-gingerly/DX/paths.js';
 
-/** @import {EndUserProps, AP} from './types'; */
+/** @import {EndUserProps, AP, RuntimeProps} from './types'; */
 /** @import {RoundaboutOptions} from './types/roundabout/types' */
 /** @import {ElMakerConfig} from './types/el-maker/types' */
 
 const withMethods = [m['🔍']];
 
-const $ = (/** @type {typeof paths<AP>} */ (/** @type {any} */(paths)))({withMethods});
+const $ = (/** @type {typeof paths<RuntimeProps>} */ (/** @type {any} */(paths)))({withMethods});
 
 
 /**
- * @type {RoundaboutOptions<EndUserProps>}
+ * @type {RoundaboutOptions<AP>}
  */
 const raConfig = {
     weakRef: {
@@ -262,30 +262,30 @@ const raConfig = {
     },
     compacts: {
         on_click_of_expandButton_assign: {
-            [$.expandButton.hidden.path]: true,
-            [$.collapseButton.hidden.path]: false,
+            [$.expandButton.hidden.Path]: true,
+            [$.collapseButton.hidden.Path]: false,
             expanded: true,
             
         },
         on_click_of_collapseButton_assign: {
             expanded: false,
-            [$.expandButton.hidden.path]: false,
-            [$.collapseButton.hidden.path]: true,
+            [$.expandButton.hidden.Path]: false,
+            [$.collapseButton.hidden.Path]: true,
         } 
     },
     merges: smoothOver([
         {
             ifKeyIn: ['clone'],
-            assign: {
-                expandButton: $.clone.querySelector('[name=expand]'),
-                collapseButton: $.clone.querySelector('[name=collapse]'),
-            }
+            ...doAssign(
+                set($.expandButton).to($.clone.querySelector('[name=expand]')),
+                set($.collapseButton).to($.clone.querySelector('[name=collapse]')),
+            )
         },
         {
             ifKeyIn: ['expanded'],
             ...doAssign(
                 set($.ariaExpanded).to($.expanded),
-                set(`${$.ariaControlsElements.path}?.@each?.hidden =!`).to($.expanded)
+                set($.ariaControlsElements.Each.hidden.QMEq).to([$.expanded, false, 'until-found'])
             )
         },
         {
@@ -303,13 +303,25 @@ const raConfig = {
     }
 }
 
-/** @type {ElMakerConfig<EndUserProps>} */
+// withAttrs configuration for parsing element attributes
+const withAttrs = {
+    base: 'user-counter',
+    count: '${base}-count',
+    _count: {
+        instanceOf: 'Number',
+        valIfNull: 0,
+    },
+    username: '${base}-username',
+};
+
+/** @type {ElMakerConfig<AP>} */
 const features = {
     assignFeatures: {
         roundabout: {
             customData: {
                 raConfig,
-            }
+            },
+            withAttrs
         },
         templateMaker: {}
     }
@@ -326,6 +338,55 @@ writeFileSync(outputFile, render(), 'utf8');
 
 </details>
 
+Some non obvious scenarios:
+
+### How can I perform an action when the escape key is pressed somewhere on the document?
+
+Answer:
+
+From the side-burger example.
+
+```JS
+const raConfig = {
+    ...
+    compacts: {
+        on_keydown_of_ownerDocument_assignFromEvent: {
+            [$.escapeKeyPressed.QMEq.Path]: [['?.key', 'Escape'], true, false]
+        }
+    },
+    merges: smoothOver([
+        {
+            ifKeyIn: ['expanded'],
+            ...doAssign(
+                ...
+                set($.escapeKeyPressed).to(false)
+            )
+        },
+        ...
+        {
+            ifAllOf: ['escapeKeyPressed'],
+            assign: {
+                expanded: false
+            }
+        }
+    ]),
+};
+```
+
+## How can I set focus after a delay?
+
+Work is underway to improve the DX a bit, but for now:
+
+```JS
+{
+    delay:10, //milliseconds
+    ifAllOf: ['expanded'],
+    assign: {
+        set($.querySelector('a').focus()).to({}),
+    }
+},
+```
+
 ## Step 8
 
 Run `node el-maker.mjs` (or `npm run build-el-maker` if your `package.json` includes a watch script) to regenerate `el-maker.json`.

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

@@ -267,6 +267,17 @@ export interface IAssignGingerlyOptions {
    */
   aka?: Record<string, string>;
 
+  /**
+   * Value substitutions for path segments.
+   * Each key names a placeholder; the value is a `?.`-delimited path resolved
+   * against the source (`from`) object. The resolved string value replaces any
+   * matching whole path segment in RHS path strings before path evaluation.
+   * 
+   * Substitution values must be strings and must not contain the `?.` sequence,
+   * otherwise an error is thrown.
+   */
+  substitutions?: Record<string, string>;
+
   /**
    * Shorthand for binding method aliases from the source object.
    * Each entry maps an alias to a method name and is normalized into
@@ -357,6 +368,16 @@ export interface AssignFromOptions {
   /** Alias mappings for path segments */
   aka?: Record<string, string>;
 
+  /**
+   * Value substitutions for path segments.
+   * Each key names a placeholder; the value is a `?.`-delimited path resolved
+   * against `from`. The resolved string value replaces any matching whole path
+   * segment in RHS path strings before path evaluation.
+   * 
+   * Substitution values must be strings and must not contain `?.`.
+   */
+  substitutions?: Record<string, string>;
+
   /** AbortSignal for cleanup */
   signal?: AbortSignal;
 

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

@@ -2,6 +2,7 @@ import {RAConfig} from '../roundabout/types.js';
 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';
 
 export interface ElMakerConfig<AllProps = any, TActions = AllProps> {
     assignFeatures: {
@@ -10,6 +11,7 @@ export interface ElMakerConfig<AllProps = any, TActions = AllProps> {
             customData: {
                 raConfig: RAConfig<AllProps, TActions, TActions>
             }
+            withAttrs: AttrPatterns<AllProps>
         },
         fontMgr?: {
             spawn?: string,

package/inferencer/types/roundabout/types.d.ts

@@ -54,6 +54,7 @@ export type Compacts<TProps = any, TActions = TProps, TEvents extends string = s
     | Partial<{[key in `on_${TEvents}_of_${keyof TProps & string}_inc_${keyof TProps & string}_by`]: number}>
     | Partial<{[key in `on_${TEvents}_of_${keyof TProps & string}_set_${keyof TProps & string}_to`]: any}>
     | Partial<{[key in `on_${TEvents}_of_${keyof TProps & string}_assign`]: Record<string, any>}>
+    | Partial<{[key in `on_${TEvents}_of_${keyof TProps & string}_assignFromEvent`]: Record<string, any>}>
 ;
 
 export type Hitches<TProps = any, TActions = TProps> = 
@@ -160,7 +161,14 @@ export interface RAConfig<
     initialPropVals?: Partial<{[key in keyof TProps & string]: unknown}>,
 }
 
-export interface RoundaboutOptions<TProps = unknown, TActions = TProps, ETProps = TProps> extends RAConfig<TProps, TActions, ETProps> {
+// export interface RoundaboutFeatureConfig<
+//         TProps = unknown, TActions = TProps, ETProps = TProps, 
+//         TCustomData = unknown, TEvents extends string = string>{
+//             RAConfig: RAConfig<TProps, TActions, ETProps, TCustomData, TEvents>,
+            
+// } 
+
+export interface RoundaboutOptions<TProps = unknown, TActions = TProps, ETProps = TProps, EventTypes extends string = string> extends RAConfig<TProps, TActions, ETProps, unknown, EventTypes> {
     vm?: TProps & TActions & RoundaboutReady,
     //for enhanced elements, pass in the container, referenced via $0.
     container?: EventTarget,

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

@@ -0,0 +1,43 @@
+import { FeatureSpawnContext } from "../assign-gingerly/types";
+
+/**
+ * Public properties of the SwipeDismissFeature.
+ * These can be set directly on the feature instance or initialized via attributes.
+ */
+export interface SwipeDismissProps {
+    /** Axis along which the dismiss gesture is measured. */
+    axis: 'x' | 'y';
+    /**
+     * Direction that counts toward dismissal.
+     * 1 = right/down, -1 = left/up.
+     * Set to 'both' to allow swiping in either direction (e.g. toasts/snackbars).
+     */
+    direction: 1 | -1 | 'both';
+    /** Fraction of the panel size that triggers commit. */
+    distanceThreshold: number;
+    /** Velocity threshold in px/ms; a fast flick commits even under distanceThreshold. */
+    velocityThreshold: number;
+    /** CSS selector for the drag handle. Defaults to the host element. */
+    handleSelector: string | null;
+    /** CSS selector for the panel that visually follows the drag. Defaults to the handle. */
+    panelSelector: string | null;
+    /** Called on every pointermove with the current delta and fraction of the threshold. */
+    onProgress: ((deltaPx: number, fraction: number) => void) | null;
+    /** Called when the gesture crosses the commit threshold. */
+    onCommit: (() => void) | null;
+    /** Called when the gesture is released before the commit threshold. */
+    onCancel: (() => void) | null;
+}
+
+/**
+ * Internal state of the feature.
+ */
+export interface AllProps extends SwipeDismissProps {
+    /** WeakRef to the host custom element. */
+    hostRef: WeakRef<Element>;
+}
+
+export type AP = AllProps;
+export type PAP = Partial<AllProps>;
+
+export { FeatureSpawnContext };

package/package.json

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

package/processHandlerCommands.js

@@ -171,6 +171,7 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
                 resolvedParams = getValues(config.get, options.from, {
                     withMethods: options.withMethods,
                     aka: options.aka,
+                    substitutions: options.substitutions,
                     protocols: options.protocols,
                     root: target
                 });
@@ -180,6 +181,7 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
                 const asyncResolved = await resolveValues(config.resolve, options.from, {
                     withMethods: options.withMethods,
                     aka: options.aka,
+                    substitutions: options.substitutions,
                     protocols: options.protocols,
                     root: target
                 });

package/processHandlerCommands.ts

@@ -192,6 +192,7 @@ export async function processHandlerCommands(
                 resolvedParams = getValues(config.get, options.from, {
                     withMethods: options.withMethods,
                     aka: options.aka,
+                    substitutions: options.substitutions,
                     protocols: options.protocols,
                     root: target
                 });
@@ -201,6 +202,7 @@ export async function processHandlerCommands(
                 const asyncResolved = await resolveValues(config.resolve, options.from, {
                     withMethods: options.withMethods,
                     aka: options.aka,
+                    substitutions: options.substitutions,
                     protocols: options.protocols,
                     root: target
                 });

package/resolve/getValues.js

@@ -67,6 +67,45 @@ function applyAliases(path, aliasMap) {
     const substituted = parts.map(part => aliasMap.get(part) ?? part);
     return substituted.join('?.');
 }
+/**
+ * Apply value substitutions to a path string.
+ * Replaces complete tokens between `?.` delimiters with their resolved values.
+ * Substitutions are applied before aliases.
+ */
+function applySubstitutions(path, substitutionMap) {
+    if (!substitutionMap || substitutionMap.size === 0)
+        return path;
+    const parts = path.split('?.');
+    const substituted = parts.map(part => substitutionMap.get(part) ?? part);
+    return substituted.join('?.');
+}
+/**
+ * Resolve substitution values declared in options.substitutions.
+ * Each substitution path is resolved against the source object without
+ * applying substitutions itself, to avoid infinite recursion.
+ * Resolved values must be strings and must not contain `?.`.
+ */
+function resolveSubstitutions(substitutions, source, options) {
+    const map = new Map();
+    if (!substitutions)
+        return map;
+    for (const [name, path] of Object.entries(substitutions)) {
+        // Resolve the substitution path against the source, but do not apply
+        // substitutions to that path. Root references ($0) are also disabled
+        // for substitution paths so values are sourced from `from` only.
+        const resolved = getValue(path, source, options
+            ? { ...options, substitutions: undefined, root: undefined }
+            : undefined);
+        if (typeof resolved !== 'string') {
+            throw new Error(`Substitution '${name}' must resolve to a string, got ${typeof resolved}`);
+        }
+        if (resolved.includes('?.')) {
+            throw new Error(`Substitution '${name}' resolved to a string containing '?.', which would alter the path structure: '${resolved}'`);
+        }
+        map.set(name, resolved);
+    }
+    return map;
+}
 /**
  * Resolve a special root-reference token at the start of a string.
  * '$0' refers to the first argument passed to assignFrom / resolveValues.
@@ -159,12 +198,13 @@ function getProtocolValue(value, protocols, options) {
  * Resolve path strings and protocols within an array (synchronous).
  * Recurses into nested arrays and plain objects.
  */
-function getArray(arr, source, aliasMap, withMethods, protocols, options) {
+function getArray(arr, source, aliasMap, withMethods, protocols, options, substitutionMap) {
     const permissionProcessor = options?.permissionProcessor;
     const result = [];
     for (const item of arr) {
         if (typeof item === 'string' && item.startsWith('?.')) {
-            const aliased = applyAliases(item, aliasMap);
+            const substituted = applySubstitutions(item, substitutionMap);
+            const aliased = applyAliases(substituted, aliasMap);
             const parts = parseCachedPath(aliased);
             result.push(parts.length === 0 ? source : navigatePath(source, parts, withMethods, permissionProcessor));
         }
@@ -174,7 +214,8 @@ function getArray(arr, source, aliasMap, withMethods, protocols, options) {
                 result.push(source);
             }
             else {
-                const aliased = applyAliases(rootRef.path, aliasMap);
+                const substitutedPath = applySubstitutions(rootRef.path, substitutionMap);
+                const aliased = applyAliases(substitutedPath, aliasMap);
                 const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
                 const parts = parseCachedPath(normalizedPath);
                 result.push(parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods, permissionProcessor));
@@ -184,7 +225,7 @@ function getArray(arr, source, aliasMap, withMethods, protocols, options) {
             result.push(getProtocolValue(item, protocols, options));
         }
         else if (Array.isArray(item)) {
-            result.push(getArray(item, source, aliasMap, withMethods, protocols, options));
+            result.push(getArray(item, source, aliasMap, withMethods, protocols, options, substitutionMap));
         }
         else if (item && typeof item === 'object') {
             const proto = Object.getPrototypeOf(item);
@@ -215,12 +256,14 @@ function getArray(arr, source, aliasMap, withMethods, protocols, options) {
  */
 export function getValues(pattern, source, options) {
     const { aliasMap, withMethods } = normalizeAliasOptions(options);
+    const substitutionMap = resolveSubstitutions(options?.substitutions, source, options);
     const protocols = options?.protocols;
     const permissionProcessor = options?.permissionProcessor;
     const result = {};
     for (const [key, value] of Object.entries(pattern)) {
         if (typeof value === 'string' && value.startsWith('?.')) {
-            const aliased = applyAliases(value, aliasMap);
+            const substituted = applySubstitutions(value, substitutionMap);
+            const aliased = applyAliases(substituted, aliasMap);
             const parts = parseCachedPath(aliased);
             result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods, permissionProcessor);
         }
@@ -230,7 +273,8 @@ export function getValues(pattern, source, options) {
                 result[key] = source;
             }
             else {
-                const aliased = applyAliases(rootRef.path, aliasMap);
+                const substitutedPath = applySubstitutions(rootRef.path, substitutionMap);
+                const aliased = applyAliases(substitutedPath, aliasMap);
                 const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
                 const parts = parseCachedPath(normalizedPath);
                 result[key] = parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods, permissionProcessor);
@@ -240,7 +284,7 @@ export function getValues(pattern, source, options) {
             result[key] = getProtocolValue(value, protocols, options);
         }
         else if (Array.isArray(value)) {
-            result[key] = getArray(value, source, aliasMap, withMethods, protocols, options);
+            result[key] = getArray(value, source, aliasMap, withMethods, protocols, options, substitutionMap);
         }
         else if (typeof value === 'object' && value !== null) {
             const proto = Object.getPrototypeOf(value);
@@ -274,10 +318,12 @@ export function getValue(path, source, options) {
     else if (!path.startsWith('?.')) {
         return path;
     }
-    let aliased = path;
+    const substitutionMap = resolveSubstitutions(options?.substitutions, source, options);
+    const substituted = applySubstitutions(path, substitutionMap);
+    let aliased = substituted;
     const { aliasMap } = normalizeAliasOptions(options);
     if (aliasMap.size > 0) {
-        aliased = applyAliases(path, aliasMap);
+        aliased = applyAliases(substituted, aliasMap);
     }
     const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
     const parts = parseCachedPath(normalizedPath);