assign-gingerly 0.0.15 → 0.0.16

package/README.md

@@ -2180,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.15",
+  "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",