assign-gingerly 0.0.63 → 0.0.65

package/assignGingerly.js

@@ -1,3 +1,4 @@
+import { normalizeAliasOptions } from './getValues.js';
 /**
  * GUID for global instance map storage to ensure uniqueness across package versions
  */
@@ -561,29 +562,14 @@ export function assignGingerly(target, source, options, permissions) {
     if (!target || typeof target !== 'object') {
         return target;
     }
-    // Convert withMethods array to Set for O(1) lookup
-    const withMethodsSet = options?.withMethods
-        ? options.withMethods instanceof Set
-            ? options.withMethods
-            : new Set(options.withMethods)
-        : undefined;
+    //TODO
+    const { aliasMap, withMethods: withMethodsSet } = normalizeAliasOptions(options);
     // Convert withAsyncMethods array to Set for O(1) lookup
     const withAsyncMethodsSet = options?.withAsyncMethods
         ? options.withAsyncMethods instanceof Set
             ? options.withAsyncMethods
             : new Set(options.withAsyncMethods)
         : undefined;
-    // Convert aka object to Map for O(1) lookup and validate aliases
-    const aliasMap = new Map();
-    if (options?.aka) {
-        for (const [alias, target] of Object.entries(options.aka)) {
-            // Validate: disallow space and backtick in aliases
-            if (alias.includes(' ') || alias.includes('`')) {
-                throw new Error(`Invalid alias '${alias}': aliases cannot contain space or backtick characters`);
-            }
-            aliasMap.set(alias, target);
-        }
-    }
     const registry = options?.registry instanceof EnhancementRegistry
         ? options.registry
         : options?.registry

package/assignGingerly.ts

@@ -3,6 +3,7 @@
 import { EnhancementConfig } from "./types/assign-gingerly/types";
 import type { FeatureConfigsMap } from "./types/assign-gingerly/types";
 import type { AssignPermissions } from "./isAllowedImportPath.js";
+import { normalizeAliasOptions } from './getValues.js';
 
 /**
  * Constructor signature for ItemScope Manager classes
@@ -82,6 +83,13 @@ export interface IAssignGingerlyOptions {
    * // Equivalent to: element.querySelector('my-element').classList.add('highlighted')
    */
   aka?: 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
+   * the existing withMethods + aka behavior.
+   */
+  akaMethods?: Record<string, string>;
   
   /**
    * AbortSignal for cleaning up reactive subscriptions (@eachTime)
@@ -759,13 +767,9 @@ export function assignGingerly(
   if (!target || typeof target !== 'object') {
     return target;
   }
+  //TODO
 
-  // Convert withMethods array to Set for O(1) lookup
-  const withMethodsSet = options?.withMethods
-    ? options.withMethods instanceof Set
-      ? options.withMethods
-      : new Set(options.withMethods)
-    : undefined;
+  const { aliasMap, withMethods: withMethodsSet } = normalizeAliasOptions(options);
 
   // Convert withAsyncMethods array to Set for O(1) lookup
   const withAsyncMethodsSet = options?.withAsyncMethods
@@ -774,18 +778,6 @@ export function assignGingerly(
       : new Set(options.withAsyncMethods)
     : undefined;
 
-  // Convert aka object to Map for O(1) lookup and validate aliases
-  const aliasMap = new Map<string, string>();
-  if (options?.aka) {
-    for (const [alias, target] of Object.entries(options.aka)) {
-      // Validate: disallow space and backtick in aliases
-      if (alias.includes(' ') || alias.includes('`')) {
-        throw new Error(`Invalid alias '${alias}': aliases cannot contain space or backtick characters`);
-      }
-      aliasMap.set(alias, target);
-    }
-  }
-
   const registry = options?.registry instanceof EnhancementRegistry
     ? options.registry
     : options?.registry

package/assignTentatively.ts

@@ -1,9 +1,8 @@
 /**
- * Interface for assignTentatively options with reversal tracking
+ * assignTentatively — reversible assignment with change tracking.
  */
-export interface IAssignTentativelyOptions {
-  reversal?: Record<string | symbol, any>;
-}
+import type { IAssignTentativelyOptions } from './types/assign-gingerly/types.js';
+export type { IAssignTentativelyOptions };
 
 /**
  * Helper function to check if a string key represents an += command

package/getValues.js

@@ -16,6 +16,39 @@
  *     count: 42
  * }, source, { withMethods: ['querySelector'], aka: { q: 'querySelector' } });
  */
+//TODO
+export function normalizeAliasOptions(options) {
+    const aliasMap = new Map();
+    if (options?.aka) {
+        for (const [alias, target] of Object.entries(options.aka)) {
+            if (alias.includes(' ') || alias.includes('`')) {
+                throw new Error(`Invalid alias '${alias}': aliases cannot contain space or backtick characters`);
+            }
+            aliasMap.set(alias, target);
+        }
+    }
+    if (options?.akaMethods) {
+        for (const [alias, target] of Object.entries(options.akaMethods)) {
+            if (alias.includes(' ') || alias.includes('`')) {
+                throw new Error(`Invalid alias '${alias}': aliases cannot contain space or backtick characters`);
+            }
+            aliasMap.set(alias, target);
+        }
+    }
+    const withMethods = options?.withMethods
+        ? options.withMethods instanceof Set
+            ? new Set(options.withMethods)
+            : new Set(options.withMethods)
+        : options?.akaMethods
+            ? new Set()
+            : undefined;
+    if (options?.akaMethods) {
+        for (const target of Object.values(options.akaMethods)) {
+            withMethods?.add(target);
+        }
+    }
+    return { aliasMap, withMethods };
+}
 /**
  * Apply alias substitutions to a path string.
  * Replaces complete tokens between `?.` delimiters with their aliased values.
@@ -27,6 +60,17 @@ function applyAliases(path, aliasMap) {
     const substituted = parts.map(part => aliasMap.get(part) ?? part);
     return substituted.join('?.');
 }
+/**
+ * Resolve a special root-reference token at the start of a string.
+ * '$0' refers to the first argument passed to assignFrom / resolveValues.
+ */
+function resolveRootReference(path, source, root) {
+    if (path === '$0')
+        return { source: root ?? source, path: '' };
+    if (path.startsWith('$0?.'))
+        return { source: root ?? source, path: path.substring(4) };
+    return null;
+}
 /**
  * Path cache for parsed path strings.
  * Avoids re-splitting the same path on repeated calls.
@@ -116,6 +160,18 @@ function getArray(arr, source, aliasMap, withMethods, protocols, options) {
             const parts = parseCachedPath(aliased);
             result.push(parts.length === 0 ? source : navigatePath(source, parts, withMethods));
         }
+        else if (typeof item === 'string' && item.startsWith('$0')) {
+            const rootRef = resolveRootReference(item, source, options?.root);
+            if (rootRef === null) {
+                result.push(source);
+            }
+            else {
+                const aliased = applyAliases(rootRef.path, aliasMap);
+                const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
+                const parts = parseCachedPath(normalizedPath);
+                result.push(parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods));
+            }
+        }
         else if (typeof item === 'string' && protocols && hasProtocol(item)) {
             result.push(getProtocolValue(item, protocols, options));
         }
@@ -150,19 +206,7 @@ function getArray(arr, source, aliasMap, withMethods, protocols, options) {
  * @returns New object with path strings replaced by resolved values
  */
 export function getValues(pattern, source, options) {
-    // Build alias map
-    const aliasMap = new Map();
-    if (options?.aka) {
-        for (const [alias, target] of Object.entries(options.aka)) {
-            aliasMap.set(alias, target);
-        }
-    }
-    // Build methods set
-    const withMethods = options?.withMethods
-        ? options.withMethods instanceof Set
-            ? options.withMethods
-            : new Set(options.withMethods)
-        : undefined;
+    const { aliasMap, withMethods } = normalizeAliasOptions(options);
     const protocols = options?.protocols;
     const result = {};
     for (const [key, value] of Object.entries(pattern)) {
@@ -171,6 +215,18 @@ export function getValues(pattern, source, options) {
             const parts = parseCachedPath(aliased);
             result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods);
         }
+        else if (typeof value === 'string' && value.startsWith('$0')) {
+            const rootRef = resolveRootReference(value, source, options?.root);
+            if (rootRef === null) {
+                result[key] = source;
+            }
+            else {
+                const aliased = applyAliases(rootRef.path, aliasMap);
+                const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
+                const parts = parseCachedPath(normalizedPath);
+                result[key] = parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods);
+            }
+        }
         else if (typeof value === 'string' && protocols && hasProtocol(value)) {
             result[key] = getProtocolValue(value, protocols, options);
         }
@@ -201,23 +257,23 @@ export function getValues(pattern, source, options) {
  * @returns The resolved value, or undefined if any segment is nullish
  */
 export function getValue(path, source, options) {
-    if (!path.startsWith('?.'))
+    const rootRef = resolveRootReference(path, source, options?.root);
+    if (rootRef) {
+        path = rootRef.path;
+        source = rootRef.source;
+    }
+    else if (!path.startsWith('?.')) {
         return path;
+    }
     let aliased = path;
-    if (options?.aka) {
-        const aliasMap = new Map();
-        for (const [alias, target] of Object.entries(options.aka)) {
-            aliasMap.set(alias, target);
-        }
+    const { aliasMap } = normalizeAliasOptions(options);
+    if (aliasMap.size > 0) {
         aliased = applyAliases(path, aliasMap);
     }
-    const parts = parseCachedPath(aliased);
+    const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
+    const parts = parseCachedPath(normalizedPath);
     if (parts.length === 0)
         return source;
-    const withMethods = options?.withMethods
-        ? options.withMethods instanceof Set
-            ? options.withMethods
-            : new Set(options.withMethods)
-        : undefined;
+    const { withMethods } = normalizeAliasOptions(options);
     return navigatePath(source, parts, withMethods);
 }

package/getValues.ts

@@ -18,6 +18,48 @@
  */
 
 import type { GetValuesOptions } from './types/assign-gingerly/types.js';
+//TODO
+export function normalizeAliasOptions(options?: {
+    aka?: Record<string, string>;
+    akaMethods?: Record<string, string>;
+    withMethods?: string[] | Set<string>;
+}): { aliasMap: Map<string, string>; withMethods: Set<string> | undefined } {
+    const aliasMap = new Map<string, string>();
+
+    if (options?.aka) {
+        for (const [alias, target] of Object.entries(options.aka)) {
+            if (alias.includes(' ') || alias.includes('`')) {
+                throw new Error(`Invalid alias '${alias}': aliases cannot contain space or backtick characters`);
+            }
+            aliasMap.set(alias, target);
+        }
+    }
+
+    if (options?.akaMethods) {
+        for (const [alias, target] of Object.entries(options.akaMethods)) {
+            if (alias.includes(' ') || alias.includes('`')) {
+                throw new Error(`Invalid alias '${alias}': aliases cannot contain space or backtick characters`);
+            }
+            aliasMap.set(alias, target);
+        }
+    }
+
+    const withMethods = options?.withMethods
+        ? options.withMethods instanceof Set
+            ? new Set(options.withMethods)
+            : new Set(options.withMethods)
+        : options?.akaMethods
+            ? new Set<string>()
+            : undefined;
+
+    if (options?.akaMethods) {
+        for (const target of Object.values(options.akaMethods)) {
+            withMethods?.add(target);
+        }
+    }
+
+    return { aliasMap, withMethods };
+}
 
 /**
  * Apply alias substitutions to a path string.
@@ -30,6 +72,16 @@ function applyAliases(path: string, aliasMap: Map<string, string>): string {
     return substituted.join('?.');
 }
 
+/**
+ * Resolve a special root-reference token at the start of a string.
+ * '$0' refers to the first argument passed to assignFrom / resolveValues.
+ */
+function resolveRootReference(path: string, source: any, root: any): { source: any; path: string } | null {
+    if (path === '$0') return { source: root ?? source, path: '' };
+    if (path.startsWith('$0?.')) return { source: root ?? source, path: path.substring(4) };
+    return null;
+}
+
 /**
  * Path cache for parsed path strings.
  * Avoids re-splitting the same path on repeated calls.
@@ -142,6 +194,16 @@ function getArray(
             const aliased = applyAliases(item, aliasMap);
             const parts = parseCachedPath(aliased);
             result.push(parts.length === 0 ? source : navigatePath(source, parts, withMethods));
+        } else if (typeof item === 'string' && item.startsWith('$0')) {
+            const rootRef = resolveRootReference(item, source, options?.root);
+            if (rootRef === null) {
+                result.push(source);
+            } else {
+                const aliased = applyAliases(rootRef.path, aliasMap);
+                const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
+                const parts = parseCachedPath(normalizedPath);
+                result.push(parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods));
+            }
         } else if (typeof item === 'string' && protocols && hasProtocol(item)) {
             result.push(getProtocolValue(item, protocols, options));
         } else if (Array.isArray(item)) {
@@ -177,20 +239,7 @@ export function getValues(
     source: any,
     options?: GetValuesOptions
 ): Record<string, any> {
-    // Build alias map
-    const aliasMap = new Map<string, string>();
-    if (options?.aka) {
-        for (const [alias, target] of Object.entries(options.aka)) {
-            aliasMap.set(alias, target);
-        }
-    }
-
-    // Build methods set
-    const withMethods = options?.withMethods
-        ? options.withMethods instanceof Set
-            ? options.withMethods
-            : new Set(options.withMethods)
-        : undefined;
+    const { aliasMap, withMethods } = normalizeAliasOptions(options);
 
     const protocols = options?.protocols;
 
@@ -200,6 +249,16 @@ export function getValues(
             const aliased = applyAliases(value, aliasMap);
             const parts = parseCachedPath(aliased);
             result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods);
+        } else if (typeof value === 'string' && value.startsWith('$0')) {
+            const rootRef = resolveRootReference(value, source, options?.root);
+            if (rootRef === null) {
+                result[key] = source;
+            } else {
+                const aliased = applyAliases(rootRef.path, aliasMap);
+                const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
+                const parts = parseCachedPath(normalizedPath);
+                result[key] = parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods);
+            }
         } else if (typeof value === 'string' && protocols && hasProtocol(value)) {
             result[key] = getProtocolValue(value, protocols, options);
         } else if (Array.isArray(value)) {
@@ -231,25 +290,25 @@ export function getValue(
     source: any,
     options?: GetValuesOptions
 ): any {
-    if (!path.startsWith('?.')) return path;
+    const rootRef = resolveRootReference(path, source, options?.root);
+    if (rootRef) {
+        path = rootRef.path;
+        source = rootRef.source;
+    } else if (!path.startsWith('?.')) {
+        return path;
+    }
 
     let aliased = path;
-    if (options?.aka) {
-        const aliasMap = new Map<string, string>();
-        for (const [alias, target] of Object.entries(options.aka)) {
-            aliasMap.set(alias, target);
-        }
+    const { aliasMap } = normalizeAliasOptions(options);
+    if (aliasMap.size > 0) {
         aliased = applyAliases(path, aliasMap);
     }
 
-    const parts = parseCachedPath(aliased);
+    const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
+    const parts = parseCachedPath(normalizedPath);
     if (parts.length === 0) return source;
 
-    const withMethods = options?.withMethods
-        ? options.withMethods instanceof Set
-            ? options.withMethods
-            : new Set(options.withMethods)
-        : undefined;
+    const { withMethods } = normalizeAliasOptions(options);
 
     return navigatePath(source, parts, withMethods);
 }

package/handlers/arr.js

@@ -0,0 +1,13 @@
+/**
+ * Utility function to normalize a value to an array.
+ * - If undefined, returns empty array
+ * - If already an array, returns as-is
+ * - Otherwise, wraps the value in an array
+ *
+ * @param inp - Value to normalize to array
+ * @returns Array containing the value(s)
+ */
+export function arr(inp) {
+    return inp === undefined ? []
+        : Array.isArray(inp) ? inp : [inp];
+}

package/handlers/arr.ts

@@ -0,0 +1,13 @@
+/**
+ * Utility function to normalize a value to an array.
+ * - If undefined, returns empty array
+ * - If already an array, returns as-is
+ * - Otherwise, wraps the value in an array
+ * 
+ * @param inp - Value to normalize to array
+ * @returns Array containing the value(s)
+ */
+export function arr<T = any>(inp: T | T[] | undefined): T[] {
+    return inp === undefined ? []
+        : Array.isArray(inp) ? inp : [inp];
+}

package/handlers/manageTemplateList.js

@@ -149,7 +149,7 @@ export class ManageTemplateListHandler {
                 // New item — clone template
                 let content;
                 if (instantiate instanceof HTMLTemplateElement) {
-                    content = instantiate.content.cloneNode(true);
+                    content = (instantiate.remoteContent || instantiate.content).cloneNode(true);
                 }
                 else if (instantiate instanceof DocumentFragment) {
                     content = instantiate.cloneNode(true);

package/handlers/manageTemplateList.ts

@@ -182,7 +182,7 @@ export class ManageTemplateListHandler implements AssignFromHandler {
                 // New item — clone template
                 let content: DocumentFragment;
                 if (instantiate instanceof HTMLTemplateElement) {
-                    content = instantiate.content.cloneNode(true) as DocumentFragment;
+                    content = (instantiate.remoteContent ||instantiate.content).cloneNode(true) as DocumentFragment;
                 } else if (instantiate instanceof DocumentFragment) {
                     content = instantiate.cloneNode(true) as DocumentFragment;
                 } else {

package/handlers/nudge.js

@@ -0,0 +1,23 @@
+import { arr } from './arr.js';
+/**
+ * Decrement "disabled" counter, remove when reaches 0
+ * @param el
+ * Optional select the attribute or attributes to remove or decrement
+ * @param attr
+ */
+export function nudge(el, attr = 'disabled') {
+    const attrs = arr(attr);
+    for (const attr of attrs) {
+        const da = el.getAttribute(attr);
+        if (da !== null) {
+            if (da.length === 0 || da === "1") {
+                el.removeAttribute(attr);
+                if (attr === 'disabled')
+                    el.disabled = false;
+            }
+            else {
+                el.setAttribute(attr, (parseInt(da) - 1).toString());
+            }
+        }
+    }
+}

package/handlers/nudge.ts

@@ -0,0 +1,23 @@
+import {arr} from './arr.js';
+/**
+ * Decrement "disabled" counter, remove when reaches 0
+ * @param el
+ * Optional select the attribute or attributes to remove or decrement
+ * @param attr 
+ */
+ export function nudge(el: Element, attr: string | Array<string> = 'disabled') { //TODO:  Share with be-observant
+    const attrs = arr(attr);
+    for(const attr of attrs){
+        const da = el.getAttribute(attr);
+        if (da !== null) {
+            if (da.length === 0 || da === "1") {
+                el.removeAttribute(attr);
+                if(attr === 'disabled') (<any>el).disabled = false;
+            }
+            else {
+                el.setAttribute(attr, (parseInt(da) - 1).toString());
+            }
+        }
+    }
+
+}

package/index.js

@@ -14,4 +14,6 @@ export { assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag,
 export { installForwarding } from './installForwarding.js';
 export { defineWithFeatures } from './defineWithFeatures.js';
 export { resolveAndAssignFeatures } from './resolveAndAssignFeatures.js';
+export { nudge } from './handlers/nudge.js';
+export { arr } from './handlers/arr.js';
 import './object-extension.js';

package/index.ts

@@ -14,5 +14,7 @@ export {assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag, s
 export {installForwarding} from './installForwarding.js';
 export {defineWithFeatures} from './defineWithFeatures.js';
 export {resolveAndAssignFeatures} from './resolveAndAssignFeatures.js';
+export {nudge} from './handlers/nudge.js';
+export {arr} from './handlers/arr.js';
 export {} from './handlers/manageTemplateList.js';
 import './object-extension.js';