assign-gingerly 0.0.85 → 0.0.87

package/inferencer/types/NewCustomElementFeature.md

@@ -224,7 +224,7 @@ Create `.vscode/settings.json`:
 }
 ```
 
-## Step 8: Set Up .kiro Directory
+## Step 8: Set Up .kiro Directory Only if kiro is implementing.
 
 Create `.kiro/steering/project-context.md` to reference the shared types documentation:
 
@@ -350,6 +350,8 @@ customElements.assignFeatures(MyElement, {
 
 The parsed attributes (`{ myProp: 'hello', count: 42 }`) are passed as `initVals` to the constructor.
 
+See [withAttrs](https://github.com/bahrus/assign-gingerly/blob/baseline/docs/withAttrs.md) for an in-depth discussion of all the various configuration options.
+
 ### Async Spawn (Lazy Loading)
 
 Feature implementations can be loaded asynchronously:

package/inferencer/types/NewHTMLFirstCustomElement.md

@@ -451,6 +451,8 @@ 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) 
+
 
 ## Step 8
 

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

@@ -112,6 +112,36 @@ export interface ParserContext<T = any> {
   attrName: string;
 }
 
+/**
+ * Tuple reference for custom element static method parsers
+ * [elementName, methodName]
+ */
+export type ParserTuple = [CustomElementName, CustomElementConstructorStaticMethodName];
+
+/**
+ * Class-based parser interface
+ * Classes registered as named parsers are instantiated per attribute parse
+ * and their parse method is called with the attribute value and context
+ */
+export interface AttrParser<T = any> {
+  parse(attrValue: string | null, context?: ParserContext<T>): any;
+}
+
+/**
+ * Constructor signature for class-based parsers
+ */
+export type AttrParserConstructor<T = any> = {
+  new (options?: any): AttrParser<T>;
+};
+
+/**
+ * Object form for referencing a registered named parser with constructor options
+ */
+export interface NamedParserRef {
+  name: string;
+  options?: any;
+}
+
 /**
  * Parser function signature
  * Can accept just the attribute value (simple form) or value + context (advanced form)
@@ -120,6 +150,15 @@ export type ParserFunction<T = any> =
   | ((attrValue: string | null) => any)
   | ((attrValue: string | null, context?: ParserContext<T>) => any);
 
+/**
+ * Any valid parser specification for AttrConfig.parser
+ */
+export type ParserSpec<T = any> =
+  | ParserFunction<T>
+  | string
+  | ParserTuple
+  | NamedParserRef;
+
 export interface AttrConfig<T = unknown, TParserConfig = unknown> {
   /**
    * Type of the property value (JSON-serializable string format)
@@ -148,7 +187,9 @@ export interface AttrConfig<T = unknown, TParserConfig = unknown> {
    * - Function: Inline parser function (not JSON serializable)
    *   - Simple form: (attrValue: string | null) => any
    *   - Advanced form: (attrValue: string | null, context: ParserContext) => any
-   * - String: Named parser reference (JSON serializable) - looks up in scoped registry (if available) then global parser registry (e.g., 'timestamp', 'csv')
+   * - String: Named parser reference (JSON serializable) - looks up in scoped registry (if available) then global parser registry (e.g., 'timestamp', 'splitter')
+   * - Tuple: [CustomElementName, StaticMethodName] - looks up a static method on a custom element constructor
+   * - Object: { name: string; options?: any } - looks up a registered class parser and instantiates it with the given options
    * 
    * Parser functions can optionally accept a second parameter (ParserContext) which provides:
    * - attrConfig: The full AttrConfig object for this attribute
@@ -156,10 +197,7 @@ export interface AttrConfig<T = unknown, TParserConfig = unknown> {
    * - element: The element being enhanced
    * - attrName: The resolved attribute name
    */
-  parser?: 
-    | ParserFunction<T>
-    | string
-  ;
+  parser?: ParserSpec<T>;
 
   /**
    * configuration information needed by a custom parser to properly

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

@@ -17,16 +17,18 @@ export interface SwipeDismissProps {
     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;
+
+    /** Element used for dragging */
+    handle: Element;
+    /** Element used to open / close */
+    panel: Element;
 }
 
 /**
@@ -35,6 +37,7 @@ export interface SwipeDismissProps {
 export interface AllProps extends SwipeDismissProps {
     /** WeakRef to the host custom element. */
     hostRef: WeakRef<Element>;
+
 }
 
 export type AP = AllProps;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.85",
+  "version": "0.0.87",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -22,6 +22,7 @@
     "handlers/**",
     "inferencer/**",
     "resolve/**",
+    "syncOps/**",
     "utils/**",
     "README.md",
     "LICENSE",
@@ -103,9 +104,13 @@
       "default": "./handlers/lazyLoadSwitch.js",
       "types": "./handlers/lazyLoadSwitch.ts"
     },
-    "./handlers/join.js": {
-      "default": "./handlers/join.js",
-      "types": "./handlers/join.ts"
+    "./syncOps/join.js": {
+      "default": "./syncOps/join.js",
+      "types": "./syncOps/join.ts"
+    },
+    "./syncOps/registry.js": {
+      "default": "./syncOps/registry.js",
+      "types": "./syncOps/registry.ts"
     },
     "./handlers/microDataJoin.js": {
       "default": "./handlers/microDataJoin.js",

package/processHandlerCommands.js

@@ -5,16 +5,18 @@
  */
 import { resolveValues } from './resolve/resolveValues.js';
 import { getValues } from './resolve/getValues.js';
-import { evaluatePathWithMethods } from './assignGingerly.js';
+import { resolveLhsPath } from './utils/resolveLhsPath.js';
 import { findClassPrototypeInPath } from './utils/findClassPrototypeInPath.js';
 /**
  * Map of built-in handler names to their module paths.
  * These are auto-loaded on demand — no explicit import required.
+ *
+ * `join` moved to a synchronous ` =&` op (see syncOps/join.ts) — it never had
+ * side effects or anything to await, so it didn't belong behind this async pipeline.
  */
 const BUILT_IN_MAP = {
     'builtIns.lazyLoad': './handlers/lazyLoad.js',
     'builtIns.lazyLoadSwitch': './handlers/lazyLoadSwitch.js',
-    'builtIns.join': './handlers/join.js',
     'builtIns.microDataJoin': './handlers/microDataJoin.js',
     'builtIns.manageTemplateList': './handlers/manageTemplateList.js',
     'builtIns.rangeSelector': './handlers/rangeSelector.js',
@@ -98,59 +100,7 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
             continue;
         // Resolve the LHS path, preserving parent + key for return-value assignment.
         // lhsParent[lhsKey] === lhsTarget (the current value at the path)
-        let lhsTarget;
-        let lhsParent = undefined;
-        let lhsKey = undefined;
-        if (lhsPath.startsWith('?.')) {
-            const pathParts = lhsPath.split('?.').filter(p => p.length > 0);
-            const withMethodsSet = options.withMethods
-                ? options.withMethods instanceof Set
-                    ? options.withMethods
-                    : new Set(options.withMethods)
-                : undefined;
-            if (withMethodsSet && pathParts.length > 0) {
-                const result = evaluatePathWithMethods(target, pathParts, undefined, withMethodsSet);
-                lhsParent = result.target;
-                lhsKey = result.lastKey;
-                lhsTarget = result.target[result.lastKey];
-                // If last key is a method, call it to get the target
-                if (result.isMethod && typeof result.target[result.lastKey] === 'function') {
-                    lhsTarget = result.target[result.lastKey].call(result.target);
-                    lhsParent = undefined; // Can't assign back to a method call result
-                    lhsKey = undefined;
-                }
-            }
-            else {
-                // Simple path navigation — walk to parent, keep last key
-                if (pathParts.length === 0) {
-                    lhsTarget = target;
-                }
-                else if (pathParts.length === 1) {
-                    lhsParent = target;
-                    lhsKey = pathParts[0];
-                    lhsTarget = target[pathParts[0]];
-                }
-                else {
-                    let current = target;
-                    for (let i = 0; i < pathParts.length - 1; i++) {
-                        if (current == null)
-                            break;
-                        current = current[pathParts[i]];
-                    }
-                    lhsParent = current;
-                    lhsKey = pathParts[pathParts.length - 1];
-                    lhsTarget = current != null ? current[lhsKey] : undefined;
-                }
-            }
-        }
-        else if (lhsPath) {
-            lhsParent = target;
-            lhsKey = lhsPath;
-            lhsTarget = target[lhsPath];
-        }
-        else {
-            lhsTarget = target;
-        }
+        const { lhsTarget, lhsParent, lhsKey } = resolveLhsPath(target, lhsPath, options);
         // Execute handlers sequentially, sharing the same lhsTarget
         for (const config of configs) {
             //return; //1.3ms

package/processHandlerCommands.ts

@@ -6,7 +6,7 @@
 
 import { resolveValues } from './resolve/resolveValues.js';
 import { getValues } from './resolve/getValues.js';
-import { evaluatePathWithMethods } from './assignGingerly.js';
+import { resolveLhsPath } from './utils/resolveLhsPath.js';
 import { findClassPrototypeInPath } from './utils/findClassPrototypeInPath.js';
 import type { PermissionProcessor } from './types/assign-gingerly/types.js';
 import type { AssignFromOptions, AssignFromHandlerConstructor } from './assignFromAsync.js';
@@ -14,11 +14,13 @@ import type { AssignFromOptions, AssignFromHandlerConstructor } from './assignFr
 /**
  * Map of built-in handler names to their module paths.
  * These are auto-loaded on demand — no explicit import required.
+ *
+ * `join` moved to a synchronous ` =&` op (see syncOps/join.ts) — it never had
+ * side effects or anything to await, so it didn't belong behind this async pipeline.
  */
 const BUILT_IN_MAP: Record<string, string> = {
     'builtIns.lazyLoad': './handlers/lazyLoad.js',
     'builtIns.lazyLoadSwitch': './handlers/lazyLoadSwitch.js',
-    'builtIns.join': './handlers/join.js',
     'builtIns.microDataJoin': './handlers/microDataJoin.js',
     'builtIns.manageTemplateList': './handlers/manageTemplateList.js',
     'builtIns.rangeSelector': './handlers/rangeSelector.js',
@@ -121,55 +123,8 @@ export async function processHandlerCommands(
 
         // Resolve the LHS path, preserving parent + key for return-value assignment.
         // lhsParent[lhsKey] === lhsTarget (the current value at the path)
-        let lhsTarget: any;
-        let lhsParent: any = undefined;
-        let lhsKey: string | undefined = undefined;
-
-        if (lhsPath.startsWith('?.')) {
-            const pathParts = lhsPath.split('?.').filter(p => p.length > 0);
-            const withMethodsSet = options.withMethods
-                ? options.withMethods instanceof Set
-                    ? options.withMethods
-                    : new Set(options.withMethods)
-                : undefined;
-
-            if (withMethodsSet && pathParts.length > 0) {
-                const result = evaluatePathWithMethods(target, pathParts, undefined, withMethodsSet);
-                lhsParent = result.target;
-                lhsKey = result.lastKey;
-                lhsTarget = result.target[result.lastKey];
-                // If last key is a method, call it to get the target
-                if (result.isMethod && typeof result.target[result.lastKey] === 'function') {
-                    lhsTarget = result.target[result.lastKey].call(result.target);
-                    lhsParent = undefined; // Can't assign back to a method call result
-                    lhsKey = undefined;
-                }
-            } else {
-                // Simple path navigation — walk to parent, keep last key
-                if (pathParts.length === 0) {
-                    lhsTarget = target;
-                } else if (pathParts.length === 1) {
-                    lhsParent = target;
-                    lhsKey = pathParts[0];
-                    lhsTarget = target[pathParts[0]];
-                } else {
-                    let current = target;
-                    for (let i = 0; i < pathParts.length - 1; i++) {
-                        if (current == null) break;
-                        current = current[pathParts[i]];
-                    }
-                    lhsParent = current;
-                    lhsKey = pathParts[pathParts.length - 1];
-                    lhsTarget = current != null ? current[lhsKey] : undefined;
-                }
-            }
-        } else if (lhsPath) {
-            lhsParent = target;
-            lhsKey = lhsPath;
-            lhsTarget = target[lhsPath];
-        } else {
-            lhsTarget = target;
-        }
+        const { lhsTarget, lhsParent, lhsKey } = resolveLhsPath(target, lhsPath, options);
+
         // Execute handlers sequentially, sharing the same lhsTarget
         for (const config of configs) {
             //return; //1.3ms

package/{handlers → syncOps}/join.js

@@ -1,73 +1,61 @@
-/**
- * builtIns.join handler for assignFrom.
- *
- * Joins a resolved array into a single string. Supports nested sub-arrays
- * with "all-or-nothing" semantics: if any element in a nested sub-array
- * resolves to null/undefined, the entire sub-array is dropped.
- *
- * This handler is auto-loaded by processHandlerCommands when `do: 'builtIns.join'`
- * is encountered — no explicit import is needed.
- *
- * @example
- * assignFrom(oElement, {
- *     '?.textContent =>': {
- *         do: 'builtIns.join',
- *         resolve: {
- *             value: ['?.lastName', ', ', '?.firstName']
- *         }
- *     }
- * }, { from: vm });
- *
- * @example
- * // With optional segment (all-or-nothing):
- * assignFrom(oElement, {
- *     '?.textContent =>': {
- *         do: 'builtIns.join',
- *         resolve: {
- *             value: ['?.lastName', [', ', '?.middleName'], ', ', '?.firstName']
- *         }
- *     }
- * }, { from: vm });
- * // If middleName is undefined, the sub-array [', ', undefined] is dropped entirely.
- */
-/**
- * Process nested arrays with all-or-nothing null semantics.
- * - Top-level null/undefined values are filtered out.
- * - If a nested sub-array contains any null/undefined element, the entire sub-array is dropped.
- * - Nested sub-arrays that pass are flattened into the result.
- */
-function processValue(value) {
-    const result = [];
-    for (const item of value) {
-        if (Array.isArray(item)) {
-            // All-or-nothing: if any element is null/undefined, drop the entire sub-array
-            if (item.some(el => el == null)) {
-                continue;
-            }
-            // Sub-array passes — flatten its elements (recursively process nested arrays)
-            result.push(...processValue(item));
-        }
-        else if (item != null) {
-            result.push(item);
-        }
-        // Top-level null/undefined are silently filtered out
-    }
-    return result;
-}
-/**
- * JoinHandler — built-in handler for composing strings from resolved arrays.
- *
- * Returns the joined string via the return-value protocol, which causes
- * processHandlerCommands to assign it back to the LHS path.
- */
-export class JoinHandler {
-    config;
-    constructor(config) {
-        this.config = config;
-    }
-    async assign(lhsTarget, resolvedParams) {
-        const { value, separator = '' } = resolvedParams;
-        const items = Array.isArray(value) ? processValue(value) : [value];
-        return items.join(separator);
-    }
-}
+/**
+ * join — synchronous compute op for the ` =&` operator.
+ *
+ * Joins a resolved array into a single string. Supports nested sub-arrays
+ * with "all-or-nothing" semantics: if any element in a nested sub-array
+ * resolves to null/undefined, the entire sub-array is dropped.
+ *
+ * This is the sync-op successor to the old `builtIns.join` handler (which lived
+ * behind the async ` =>` pipeline). Unlike a handler, an op is a plain function —
+ * no class, no dynamic import, no await anywhere in its path.
+ *
+ * @example
+ * assignFrom(oElement, {
+ *     '?.textContent =&': {
+ *         join: ['?.lastName', ', ', '?.firstName']
+ *     }
+ * }, { from: vm });
+ *
+ * @example
+ * // With optional segment (all-or-nothing) and a separator:
+ * assignFrom(oElement, {
+ *     '?.textContent =&': {
+ *         join: ['?.lastName', ['?.middleName'], '?.firstName'],
+ *         separator: ', '
+ *     }
+ * }, { from: vm });
+ * // If middleName is undefined, the sub-array ['?.middleName'] is dropped entirely.
+ */
+/**
+ * Process nested arrays with all-or-nothing null semantics.
+ * - Top-level null/undefined values are filtered out.
+ * - If a nested sub-array contains any null/undefined element, the entire sub-array is dropped.
+ * - Nested sub-arrays that pass are flattened into the result.
+ */
+function processValue(value) {
+    const result = [];
+    for (const item of value) {
+        if (Array.isArray(item)) {
+            // All-or-nothing: if any element is null/undefined, drop the entire sub-array
+            if (item.some(el => el == null)) {
+                continue;
+            }
+            // Sub-array passes — flatten its elements (recursively process nested arrays)
+            result.push(...processValue(item));
+        }
+        else if (item != null) {
+            result.push(item);
+        }
+        // Top-level null/undefined are silently filtered out
+    }
+    return result;
+}
+/**
+ * `join` sync op — args is the resolved `join:` array, extra carries sibling
+ * config keys (currently just `separator`, default `''`).
+ */
+export function join(args, extra = {}) {
+    const { separator = '' } = extra;
+    const items = Array.isArray(args) ? processValue(args) : [args];
+    return items.join(separator);
+}

package/syncOps/join.ts

@@ -0,0 +1,62 @@
+/**
+ * join — synchronous compute op for the ` =&` operator.
+ *
+ * Joins a resolved array into a single string. Supports nested sub-arrays
+ * with "all-or-nothing" semantics: if any element in a nested sub-array
+ * resolves to null/undefined, the entire sub-array is dropped.
+ *
+ * This is the sync-op successor to the old `builtIns.join` handler (which lived
+ * behind the async ` =>` pipeline). Unlike a handler, an op is a plain function —
+ * no class, no dynamic import, no await anywhere in its path.
+ *
+ * @example
+ * assignFrom(oElement, {
+ *     '?.textContent =&': {
+ *         join: ['?.lastName', ', ', '?.firstName']
+ *     }
+ * }, { from: vm });
+ *
+ * @example
+ * // With optional segment (all-or-nothing) and a separator:
+ * assignFrom(oElement, {
+ *     '?.textContent =&': {
+ *         join: ['?.lastName', ['?.middleName'], '?.firstName'],
+ *         separator: ', '
+ *     }
+ * }, { from: vm });
+ * // If middleName is undefined, the sub-array ['?.middleName'] is dropped entirely.
+ */
+
+/**
+ * Process nested arrays with all-or-nothing null semantics.
+ * - Top-level null/undefined values are filtered out.
+ * - If a nested sub-array contains any null/undefined element, the entire sub-array is dropped.
+ * - Nested sub-arrays that pass are flattened into the result.
+ */
+function processValue(value: any[]): any[] {
+    const result: any[] = [];
+    for (const item of value) {
+        if (Array.isArray(item)) {
+            // All-or-nothing: if any element is null/undefined, drop the entire sub-array
+            if (item.some(el => el == null)) {
+                continue;
+            }
+            // Sub-array passes — flatten its elements (recursively process nested arrays)
+            result.push(...processValue(item));
+        } else if (item != null) {
+            result.push(item);
+        }
+        // Top-level null/undefined are silently filtered out
+    }
+    return result;
+}
+
+/**
+ * `join` sync op — args is the resolved `join:` array, extra carries sibling
+ * config keys (currently just `separator`, default `''`).
+ */
+export function join(args: any, extra: Record<string, any> = {}): string {
+    const { separator = '' } = extra;
+    const items = Array.isArray(args) ? processValue(args) : [args];
+    return items.join(separator);
+}

package/syncOps/registry.js

@@ -0,0 +1,15 @@
+/**
+ * registry.ts — Registry of ` =&` sync ops.
+ *
+ * Every op is a plain, synchronous, side-effect-free function: (args, extra) => value.
+ * `args` is the resolved value of the key matching the op's own name (e.g. `join:`),
+ * `extra` carries any sibling config keys (e.g. `separator:`). All statically
+ * imported — no dynamic loading, unlike the ` =>` built-in handler map — because
+ * the entire point of ` =&` is to never introduce an await.
+ *
+ * Add new sync ops here as they're written.
+ */
+import { join } from './join.js';
+export const SYNC_OPS = {
+    join,
+};

package/syncOps/registry.ts

@@ -0,0 +1,19 @@
+/**
+ * registry.ts — Registry of ` =&` sync ops.
+ *
+ * Every op is a plain, synchronous, side-effect-free function: (args, extra) => value.
+ * `args` is the resolved value of the key matching the op's own name (e.g. `join:`),
+ * `extra` carries any sibling config keys (e.g. `separator:`). All statically
+ * imported — no dynamic loading, unlike the ` =>` built-in handler map — because
+ * the entire point of ` =&` is to never introduce an await.
+ *
+ * Add new sync ops here as they're written.
+ */
+
+import { join } from './join.js';
+
+export type SyncOp = (args: any, extra: Record<string, any>) => any;
+
+export const SYNC_OPS: Record<string, SyncOp> = {
+    join,
+};

package/utils/resolveLhsPath.js

@@ -0,0 +1,68 @@
+/**
+ * resolveLhsPath.ts — Shared LHS path resolution for operator commands.
+ *
+ * Resolves the `?.`-prefixed path in front of an operator suffix (` =>`, ` =&`, ...)
+ * against a target, preserving the parent object and final key so the caller can
+ * assign a computed/returned value back to that path.
+ *
+ * Shared by processHandlerCommands.ts (` =>`) and the sync-op dispatcher in
+ * assignFrom.ts (` =&`) — the two operators that hand a value back to the LHS
+ * rather than assigning it directly.
+ */
+import { evaluatePathWithMethods } from '../assignGingerly.js';
+export function resolveLhsPath(target, lhsPath, options) {
+    let lhsTarget;
+    let lhsParent = undefined;
+    let lhsKey = undefined;
+    if (lhsPath.startsWith('?.')) {
+        const pathParts = lhsPath.split('?.').filter(p => p.length > 0);
+        const withMethodsSet = options.withMethods
+            ? options.withMethods instanceof Set
+                ? options.withMethods
+                : new Set(options.withMethods)
+            : undefined;
+        if (withMethodsSet && pathParts.length > 0) {
+            const result = evaluatePathWithMethods(target, pathParts, undefined, withMethodsSet);
+            lhsParent = result.target;
+            lhsKey = result.lastKey;
+            lhsTarget = result.target[result.lastKey];
+            // If last key is a method, call it to get the target
+            if (result.isMethod && typeof result.target[result.lastKey] === 'function') {
+                lhsTarget = result.target[result.lastKey].call(result.target);
+                lhsParent = undefined; // Can't assign back to a method call result
+                lhsKey = undefined;
+            }
+        }
+        else {
+            // Simple path navigation — walk to parent, keep last key
+            if (pathParts.length === 0) {
+                lhsTarget = target;
+            }
+            else if (pathParts.length === 1) {
+                lhsParent = target;
+                lhsKey = pathParts[0];
+                lhsTarget = target[pathParts[0]];
+            }
+            else {
+                let current = target;
+                for (let i = 0; i < pathParts.length - 1; i++) {
+                    if (current == null)
+                        break;
+                    current = current[pathParts[i]];
+                }
+                lhsParent = current;
+                lhsKey = pathParts[pathParts.length - 1];
+                lhsTarget = current != null ? current[lhsKey] : undefined;
+            }
+        }
+    }
+    else if (lhsPath) {
+        lhsParent = target;
+        lhsKey = lhsPath;
+        lhsTarget = target[lhsPath];
+    }
+    else {
+        lhsTarget = target;
+    }
+    return { lhsTarget, lhsParent, lhsKey };
+}