assign-gingerly 0.0.14 → 0.0.16

package/README.md

@@ -1400,14 +1400,48 @@ console.log(instance.count);  // 42 (parsed from attribute)
 console.log(instance.theme);  // 'dark' (parsed from attribute)
 ```
 
+**Example without enhKey:**
+
+```TypeScript
+// withAttrs works even without enhKey
+class SimpleEnhancement {
+  element;
+  ctx;
+  value = null;
+  
+  constructor(oElement, ctx, initVals) {
+    this.element = oElement;
+    this.ctx = ctx;
+    if (initVals) {
+      Object.assign(this, initVals);
+    }
+  }
+}
+
+const element = document.createElement('div');
+element.setAttribute('data-value', 'test123');
+
+const config = {
+  spawn: SimpleEnhancement,
+  // No enhKey - attributes still parsed!
+  withAttrs: {
+    base: 'data-',
+    value: '${base}value'
+  }
+};
+
+const instance = element.enh.get(config);
+console.log(instance.value);  // 'test123' (parsed from attribute)
+```
+
 **How it works:**
 1. When an enhancement is spawned via `enh.get()`, `enh.set`, or `assignGingerly()`
 2. If the registry item has a `withAttrs` property defined
 3. `parseWithAttrs(element, registryItem.withAttrs)` is automatically called
-4. The parsed attributes are merged into `initVals` (along with any existing values from `element.enh[enhKey]`)
-5. The merged `initVals` is passed to the enhancement constructor
+4. The parsed attributes are passed to the enhancement constructor as `initVals`
+5. If the registry item also has an `enhKey`, the parsed attributes are merged with any existing values from `element.enh[enhKey]` (existing values take precedence)
 
-**Precedence**: If both parsed attributes and existing `element.enh[enhKey]` values exist, the existing values take precedence over parsed attributes.
+**Note**: `withAttrs` works with or without `enhKey`. When there's no `enhKey`, the parsed attributes are passed directly to the constructor. When there is an `enhKey`, they're merged with any pre-existing values on the enh container.
 
 
 
@@ -2146,6 +2180,187 @@ assignGingerly(element, attrs);
 
 </details>
 
+## Building CSS Queries with `buildCSSQuery`
+
+The `buildCSSQuery` function generates CSS selector strings that match elements with attributes defined in an enhancement configuration's `withAttrs`. This is particularly useful for libraries like mount-observer that need to find elements that should be enhanced.
+
+### Basic Usage
+
+```TypeScript
+import { buildCSSQuery } from 'assign-gingerly';
+
+const config = {
+  spawn: MyEnhancement,
+  withAttrs: {
+    base: 'my-component',
+    theme: '${base}-theme'
+  }
+};
+
+const query = buildCSSQuery(config, 'div, span');
+console.log(query);
+// 'div[my-component], span[my-component], div[enh-my-component], span[enh-my-component], 
+//  div[my-component-theme], span[my-component-theme], div[enh-my-component-theme], span[enh-my-component-theme]'
+
+// Use with querySelector
+const elements = document.querySelectorAll(query);
+```
+
+### How It Works
+
+`buildCSSQuery` creates a cross-product of:
+1. **Selectors**: The CSS selectors you provide (e.g., `'div, span'`)
+2. **Attributes**: All attribute names from `withAttrs` (resolving template variables)
+3. **Prefixes**: Both unprefixed and `enh-` prefixed versions
+
+This ensures you find all elements that might be enhanced, regardless of whether they use the `enh-` prefix or not.
+
+### Template Variable Resolution
+
+Template variables in `withAttrs` are automatically resolved:
+
+```TypeScript
+const config = {
+  spawn: BeABeacon,
+  withAttrs: {
+    base: 'be-a-beacon',
+    theme: '${base}-theme',
+    size: '${base}-size'
+  }
+};
+
+buildCSSQuery(config, 'template, script');
+// Returns selectors for: be-a-beacon, be-a-beacon-theme, be-a-beacon-size
+// Each with both prefixed and unprefixed versions
+```
+
+### Complex Selectors
+
+The function supports any valid CSS selector:
+
+```TypeScript
+const config = {
+  spawn: MyEnhancement,
+  withAttrs: {
+    base: 'data-enhanced'
+  }
+};
+
+// Classes and IDs
+buildCSSQuery(config, 'div.highlight, span#special');
+// 'div.highlight[data-enhanced], span#special[data-enhanced], ...'
+
+// Combinators
+buildCSSQuery(config, 'div > span, ul li');
+// 'div > span[data-enhanced], ul li[data-enhanced], ...'
+
+// Pseudo-classes
+buildCSSQuery(config, 'div:hover, span:first-child');
+// 'div:hover[data-enhanced], span:first-child[data-enhanced], ...'
+
+// Attribute selectors
+buildCSSQuery(config, 'div[existing-attr]');
+// 'div[existing-attr][data-enhanced], ...'
+```
+
+### Underscore-Prefixed Keys Excluded
+
+Configuration keys starting with `_` are excluded from the query:
+
+```TypeScript
+const config = {
+  spawn: MyEnhancement,
+  withAttrs: {
+    base: 'my-attr',
+    _base: {
+      mapsTo: 'something'  // Config only, not an attribute
+    },
+    theme: '${base}-theme',
+    _theme: {
+      instanceOf: 'String'  // Config only
+    }
+  }
+};
+
+buildCSSQuery(config, 'div');
+// Only includes: my-attr and my-attr-theme
+// Does NOT include: _base or _theme
+```
+
+### Edge Cases
+
+**Empty inputs return empty string:**
+```TypeScript
+buildCSSQuery({ spawn: MyClass }, 'div');  // '' (no withAttrs)
+buildCSSQuery({ spawn: MyClass, withAttrs: {} }, 'div');  // '' (empty withAttrs)
+buildCSSQuery({ spawn: MyClass, withAttrs: { base: 'x' } }, '');  // '' (empty selectors)
+```
+
+**Deduplication:**
+```TypeScript
+buildCSSQuery(config, 'div, div, div');
+// Duplicates are removed automatically
+```
+
+**Whitespace handling:**
+```TypeScript
+buildCSSQuery(config, '  div  ,  span  ,  p  ');
+// Whitespace is trimmed automatically
+```
+
+### Use Cases
+
+1. **Mount Observer Integration**: Find elements that need enhancement
+   ```TypeScript
+   const query = buildCSSQuery(enhancementConfig, '*');
+   const observer = new MutationObserver(() => {
+     const elements = document.querySelectorAll(query);
+     elements.forEach(el => enhance(el));
+   });
+   ```
+
+2. **Batch Enhancement**: Enhance all matching elements at once
+   ```TypeScript
+   const query = buildCSSQuery(config, 'template, script');
+   document.querySelectorAll(query).forEach(el => {
+     const instance = el.enh.get(config);
+   });
+   ```
+
+3. **Conditional Enhancement**: Find elements in specific contexts
+   ```TypeScript
+   const query = buildCSSQuery(config, '.container > div');
+   const elements = document.querySelectorAll(query);
+   ```
+
+### API Reference
+
+```TypeScript
+function buildCSSQuery(
+  config: EnhancementConfig,
+  selectors: string
+): string
+```
+
+**Parameters:**
+- `config`: Enhancement configuration with `withAttrs` property
+- `selectors`: Comma-separated CSS selectors (e.g., `'div, span'`)
+
+**Returns:**
+- CSS query string with cross-product of selectors and attributes
+- Empty string if `withAttrs` is missing or empty
+
+**Throws:**
+- Error if template variables have circular references
+- Error if template variables reference undefined keys
+
+### Performance Notes
+
+- The function is synchronous and fast
+- Resulting queries can be long with many attributes, but CSS engines handle this efficiently
+- Queries are deduplicated automatically
+- Consider caching the result if calling repeatedly with the same config
+
 <!--
 
 ### Complete Example

package/buildCSSQuery.js

@@ -0,0 +1,114 @@
+/**
+ * Resolves template variables in a string recursively
+ * @param template - Template string with ${var} placeholders
+ * @param patterns - The patterns object containing variable values
+ * @param resolvedCache - Cache of already resolved values
+ * @param visitedKeys - Set of keys being resolved (for cycle detection)
+ * @returns Resolved string
+ */
+function resolveTemplate(template, patterns, resolvedCache, visitedKeys = new Set()) {
+    return template.replace(/\$\{(\w+)\}/g, (match, varName) => {
+        // Check if already resolved
+        if (resolvedCache.has(varName)) {
+            return resolvedCache.get(varName);
+        }
+        // Check for circular reference
+        if (visitedKeys.has(varName)) {
+            throw new Error(`Circular reference detected in template variable: ${varName}`);
+        }
+        const value = patterns[varName];
+        if (value === undefined) {
+            throw new Error(`Undefined template variable: ${varName}`);
+        }
+        if (typeof value === 'string') {
+            // Recursively resolve
+            visitedKeys.add(varName);
+            const resolved = resolveTemplate(value, patterns, resolvedCache, visitedKeys);
+            visitedKeys.delete(varName);
+            resolvedCache.set(varName, resolved);
+            return resolved;
+        }
+        // Non-string value, return as-is
+        return String(value);
+    });
+}
+/**
+ * Extracts attribute names from withAttrs configuration
+ * Resolves template variables and excludes underscore-prefixed config keys
+ * @param withAttrs - The attribute patterns configuration
+ * @returns Array of resolved attribute names
+ */
+function extractAttributeNames(withAttrs) {
+    const names = [];
+    const resolvedCache = new Map();
+    // Add base if present
+    if ('base' in withAttrs && typeof withAttrs.base === 'string') {
+        names.push(withAttrs.base);
+    }
+    // Add other attributes (skip underscore-prefixed config keys)
+    for (const key in withAttrs) {
+        if (key === 'base' || key.startsWith('_')) {
+            continue;
+        }
+        const value = withAttrs[key];
+        if (typeof value === 'string') {
+            // Resolve template variables
+            const resolved = resolveTemplate(value, withAttrs, resolvedCache);
+            names.push(resolved);
+        }
+    }
+    return names;
+}
+/**
+ * Builds a CSS query selector that matches elements with attributes from withAttrs
+ * Creates a cross-product of selectors and attribute names (both prefixed and unprefixed)
+ *
+ * @param config - Enhancement configuration with withAttrs
+ * @param selectors - Comma-separated CSS selectors to match (e.g., 'template, script')
+ * @returns CSS query string with cross-product of selectors and attributes
+ *
+ * @example
+ * const config = {
+ *   spawn: MyClass,
+ *   withAttrs: {
+ *     base: 'my-attr',
+ *     theme: '${base}-theme'
+ *   }
+ * };
+ *
+ * buildCSSQuery(config, 'div, span');
+ * // Returns: 'div[my-attr], span[my-attr], div[enh-my-attr], span[enh-my-attr],
+ * //           div[my-attr-theme], span[my-attr-theme], div[enh-my-attr-theme], span[enh-my-attr-theme]'
+ */
+export function buildCSSQuery(config, selectors) {
+    // Validate inputs
+    if (!config.withAttrs || !selectors) {
+        return '';
+    }
+    // Parse and normalize selectors
+    const selectorList = selectors
+        .split(',')
+        .map(s => s.trim())
+        .filter(s => s.length > 0);
+    if (selectorList.length === 0) {
+        return '';
+    }
+    // Extract and resolve attribute names
+    const attrNames = extractAttributeNames(config.withAttrs);
+    if (attrNames.length === 0) {
+        return '';
+    }
+    // Build cross-product of selectors × attributes × prefixes
+    const queries = [];
+    for (const selector of selectorList) {
+        for (const attrName of attrNames) {
+            // Unprefixed version
+            queries.push(`${selector}[${attrName}]`);
+            // enh- prefixed version
+            queries.push(`${selector}[enh-${attrName}]`);
+        }
+    }
+    // Deduplicate and join
+    const uniqueQueries = [...new Set(queries)];
+    return uniqueQueries.join(', ');
+}

package/buildCSSQuery.ts

@@ -0,0 +1,142 @@
+import { EnhancementConfig, AttrPatterns } from './types/assign-gingerly/types';
+
+/**
+ * Resolves template variables in a string recursively
+ * @param template - Template string with ${var} placeholders
+ * @param patterns - The patterns object containing variable values
+ * @param resolvedCache - Cache of already resolved values
+ * @param visitedKeys - Set of keys being resolved (for cycle detection)
+ * @returns Resolved string
+ */
+function resolveTemplate(
+    template: string,
+    patterns: Record<string, any>,
+    resolvedCache: Map<string, string>,
+    visitedKeys: Set<string> = new Set()
+): string {
+    return template.replace(/\$\{(\w+)\}/g, (match, varName) => {
+        // Check if already resolved
+        if (resolvedCache.has(varName)) {
+            return resolvedCache.get(varName)!;
+        }
+        
+        // Check for circular reference
+        if (visitedKeys.has(varName)) {
+            throw new Error(`Circular reference detected in template variable: ${varName}`);
+        }
+        
+        const value = patterns[varName];
+        
+        if (value === undefined) {
+            throw new Error(`Undefined template variable: ${varName}`);
+        }
+        
+        if (typeof value === 'string') {
+            // Recursively resolve
+            visitedKeys.add(varName);
+            const resolved = resolveTemplate(value, patterns, resolvedCache, visitedKeys);
+            visitedKeys.delete(varName);
+            resolvedCache.set(varName, resolved);
+            return resolved;
+        }
+        
+        // Non-string value, return as-is
+        return String(value);
+    });
+}
+
+/**
+ * Extracts attribute names from withAttrs configuration
+ * Resolves template variables and excludes underscore-prefixed config keys
+ * @param withAttrs - The attribute patterns configuration
+ * @returns Array of resolved attribute names
+ */
+function extractAttributeNames(withAttrs: AttrPatterns<any>): string[] {
+    const names: string[] = [];
+    const resolvedCache = new Map<string, string>();
+    
+    // Add base if present
+    if ('base' in withAttrs && typeof withAttrs.base === 'string') {
+        names.push(withAttrs.base);
+    }
+    
+    // Add other attributes (skip underscore-prefixed config keys)
+    for (const key in withAttrs) {
+        if (key === 'base' || key.startsWith('_')) {
+            continue;
+        }
+        
+        const value = withAttrs[key];
+        if (typeof value === 'string') {
+            // Resolve template variables
+            const resolved = resolveTemplate(value, withAttrs, resolvedCache);
+            names.push(resolved);
+        }
+    }
+    
+    return names;
+}
+
+/**
+ * Builds a CSS query selector that matches elements with attributes from withAttrs
+ * Creates a cross-product of selectors and attribute names (both prefixed and unprefixed)
+ * 
+ * @param config - Enhancement configuration with withAttrs
+ * @param selectors - Comma-separated CSS selectors to match (e.g., 'template, script')
+ * @returns CSS query string with cross-product of selectors and attributes
+ * 
+ * @example
+ * const config = {
+ *   spawn: MyClass,
+ *   withAttrs: {
+ *     base: 'my-attr',
+ *     theme: '${base}-theme'
+ *   }
+ * };
+ * 
+ * buildCSSQuery(config, 'div, span');
+ * // Returns: 'div[my-attr], span[my-attr], div[enh-my-attr], span[enh-my-attr], 
+ * //           div[my-attr-theme], span[my-attr-theme], div[enh-my-attr-theme], span[enh-my-attr-theme]'
+ */
+export function buildCSSQuery(
+    config: EnhancementConfig,
+    selectors: string
+): string {
+    // Validate inputs
+    if (!config.withAttrs || !selectors) {
+        return '';
+    }
+    
+    // Parse and normalize selectors
+    const selectorList = selectors
+        .split(',')
+        .map(s => s.trim())
+        .filter(s => s.length > 0);
+    
+    if (selectorList.length === 0) {
+        return '';
+    }
+    
+    // Extract and resolve attribute names
+    const attrNames = extractAttributeNames(config.withAttrs);
+    
+    if (attrNames.length === 0) {
+        return '';
+    }
+    
+    // Build cross-product of selectors × attributes × prefixes
+    const queries: string[] = [];
+    
+    for (const selector of selectorList) {
+        for (const attrName of attrNames) {
+            // Unprefixed version
+            queries.push(`${selector}[${attrName}]`);
+            // enh- prefixed version
+            queries.push(`${selector}[enh-${attrName}]`);
+        }
+    }
+    
+    // Deduplicate and join
+    const uniqueQueries = [...new Set(queries)];
+    return uniqueQueries.join(', ');
+}

package/index.js

@@ -4,4 +4,5 @@ export { BaseRegistry } from './assignGingerly.js';
 export { waitForEvent } from './waitForEvent.js';
 export { ParserRegistry, globalParserRegistry } from './parserRegistry.js';
 export { parseWithAttrs } from './parseWithAttrs.js';
+export { buildCSSQuery } from './buildCSSQuery.js';
 import './object-extension.js';

package/index.ts

@@ -4,4 +4,5 @@ export {BaseRegistry} from './assignGingerly.js';
 export {waitForEvent} from './waitForEvent.js';
 export {ParserRegistry, globalParserRegistry} from './parserRegistry.js';
 export {parseWithAttrs} from './parseWithAttrs.js';
+export {buildCSSQuery} from './buildCSSQuery.js';
 import './object-extension.js';

package/object-extension.js

@@ -82,21 +82,21 @@ class ElementEnhancementContainer {
                     return undefined;
                 }
             }
+            // Parse attributes if withAttrs is defined (regardless of enhKey)
+            let attrInitVals = undefined;
+            if (registryItem.withAttrs && element) {
+                try {
+                    attrInitVals = parseWithAttrs(element, registryItem.withAttrs, registryItem.allowUnprefixed || false);
+                }
+                catch (e) {
+                    console.error('Error parsing attributes:', e);
+                    throw e;
+                }
+            }
             // Check if there's an enhKey
             if (registryItem.enhKey) {
                 const ctx = { config: registryItem, mountCtx };
                 const self = this;
-                // Parse attributes if withAttrs is defined
-                let attrInitVals = undefined;
-                if (registryItem.withAttrs && element) {
-                    try {
-                        attrInitVals = parseWithAttrs(element, registryItem.withAttrs, registryItem.allowUnprefixed || false);
-                    }
-                    catch (e) {
-                        console.error('Error parsing attributes:', e);
-                        throw e;
-                    }
-                }
                 // Get existing initVals from enhKey
                 const existingInitVals = self[registryItem.enhKey] &&
                     !(self[registryItem.enhKey] instanceof SpawnClass)
@@ -111,9 +111,9 @@ class ElementEnhancementContainer {
                 self[registryItem.enhKey] = instance;
             }
             else {
-                // No enhKey, just spawn with element
+                // No enhKey, still pass attrInitVals
                 const ctx = { config: registryItem, mountCtx };
-                instance = new SpawnClass(element, ctx);
+                instance = new SpawnClass(element, ctx, attrInitVals);
             }
             // Store in global instance map
             instances.set(registryItem, instance);

package/object-extension.ts

@@ -156,26 +156,26 @@ class ElementEnhancementContainer {
         }
       }
       
+      // Parse attributes if withAttrs is defined (regardless of enhKey)
+      let attrInitVals: any = undefined;
+      if (registryItem.withAttrs && element) {
+        try {
+          attrInitVals = parseWithAttrs(
+            element, 
+            registryItem.withAttrs,
+            registryItem.allowUnprefixed || false
+          );
+        } catch (e) {
+          console.error('Error parsing attributes:', e);
+          throw e;
+        }
+      }
+      
       // Check if there's an enhKey
       if (registryItem.enhKey) {
         const ctx = { config: registryItem, mountCtx };
         const self = this as any;
         
-        // Parse attributes if withAttrs is defined
-        let attrInitVals: any = undefined;
-        if (registryItem.withAttrs && element) {
-          try {
-            attrInitVals = parseWithAttrs(
-              element, 
-              registryItem.withAttrs,
-              registryItem.allowUnprefixed || false
-            );
-          } catch (e) {
-            console.error('Error parsing attributes:', e);
-            throw e;
-          }
-        }
-        
         // Get existing initVals from enhKey
         const existingInitVals = self[registryItem.enhKey] && 
                         !(self[registryItem.enhKey] instanceof SpawnClass)
@@ -192,9 +192,9 @@ class ElementEnhancementContainer {
         // Store on enh container
         self[registryItem.enhKey] = instance;
       } else {
-        // No enhKey, just spawn with element
+        // No enhKey, still pass attrInitVals
         const ctx = { config: registryItem, mountCtx };
-        instance = new SpawnClass(element, ctx);
+        instance = new SpawnClass(element, ctx, attrInitVals);
       }
       
       // Store in global instance map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -43,6 +43,10 @@
     "./parseWithAttrs.js": {
       "default": "./parseWithAttrs.js",
       "types": "./parseWithAttrs.ts"
+    },
+    "./buildCSSQuery.js": {
+      "default": "./buildCSSQuery.js",
+      "types": "./buildCSSQuery.ts"
     }
   },
   "main": "index.js",
@@ -54,8 +58,8 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.58.2",
-    "spa-ssi": "0.0.26",
-    "@types/node": "^25.2.3",
+    "spa-ssi": "0.0.27",
+    "@types/node": "^25.3.0",
     "typescript": "^5.9.3"
   }
 }