assign-gingerly 0.0.83 → 0.0.85

package/ScopedParserRegistry.js

@@ -9,7 +9,7 @@ export class ScopedParserRegistry {
      * Register a parser with a given name
      * Resolves any pending waiters for this parser
      * @param name - The name to register the parser under
-     * @param parser - The parser function
+     * @param parser - The parser function or class constructor
      */
     register(name, parser) {
         if (this.parsers.has(name)) {
@@ -26,7 +26,7 @@ export class ScopedParserRegistry {
     /**
      * Get a parser by name
      * @param name - The name of the parser
-     * @returns The parser function or undefined if not found
+     * @returns The parser function, class constructor, or undefined if not found
      */
     get(name) {
         return this.parsers.get(name);

package/ScopedParserRegistry.ts

@@ -1,11 +1,11 @@
-import { ParserFunction } from './types/assign-gingerly/types';
+import { ParserFunction, AttrParserConstructor } from './types/assign-gingerly/types';
 
 /**
  * Registry for parsers scoped to a synthesizer element (be-hive, htmx-container, etc.)
  * Enables lazy-loading of complex parsers with Promise-based waiting
  */
 export class ScopedParserRegistry {
-  private parsers = new Map<string, ParserFunction>();
+  private parsers = new Map<string, ParserFunction | AttrParserConstructor>();
   private pendingWaits = new Map<string, Array<{
     resolve: () => void;
     reject: (error: Error) => void;
@@ -15,9 +15,9 @@ export class ScopedParserRegistry {
    * Register a parser with a given name
    * Resolves any pending waiters for this parser
    * @param name - The name to register the parser under
-   * @param parser - The parser function
+   * @param parser - The parser function or class constructor
    */
-  register(name: string, parser: ParserFunction): void {
+  register(name: string, parser: ParserFunction | AttrParserConstructor): void {
     if (this.parsers.has(name)) {
       console.warn(`Parser "${name}" already registered in scoped registry, overwriting`);
     }
@@ -35,9 +35,9 @@ export class ScopedParserRegistry {
   /**
    * Get a parser by name
    * @param name - The name of the parser
-   * @returns The parser function or undefined if not found
+   * @returns The parser function, class constructor, or undefined if not found
    */
-  get(name: string): ParserFunction | undefined {
+  get(name: string): ParserFunction | AttrParserConstructor | undefined {
     return this.parsers.get(name);
   }
   

package/SplitParser.js

@@ -0,0 +1,48 @@
+/**
+ * Escapes regex metacharacters so a string delimiter is treated literally.
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Built-in class parser that splits an attribute value into an array.
+ * Registered under the name 'splitter' in globalParserRegistry.
+ */
+export class SplitParser {
+    delimiter;
+    trim;
+    skipEmpty;
+    dedupe;
+    constructor(options) {
+        const opts = options ?? {};
+        const rawDelimiter = opts.delimiter;
+        if (rawDelimiter === undefined) {
+            this.delimiter = /\s+/;
+        }
+        else if (typeof rawDelimiter === 'string') {
+            this.delimiter = rawDelimiter === '' ? /(?:)/ : new RegExp(escapeRegex(rawDelimiter));
+        }
+        else {
+            this.delimiter = new RegExp(rawDelimiter.pattern, rawDelimiter.flags ?? '');
+        }
+        this.trim = opts.trim ?? true;
+        this.skipEmpty = opts.skipEmpty ?? true;
+        this.dedupe = opts.dedupe ?? false;
+    }
+    parse(v, _context) {
+        if (v === null || v === '') {
+            return [];
+        }
+        let parts = v.split(this.delimiter);
+        if (this.trim) {
+            parts = parts.map((s) => s.trim());
+        }
+        if (this.skipEmpty) {
+            parts = parts.filter((s) => s !== '');
+        }
+        if (this.dedupe) {
+            parts = [...new Set(parts)];
+        }
+        return parts;
+    }
+}

package/SplitParser.ts

@@ -0,0 +1,89 @@
+import { AttrParser, ParserContext } from './types/assign-gingerly/types';
+
+/**
+ * Options for SplitParser
+ */
+export interface SplitParserOptions {
+  /**
+   * Delimiter used to split the attribute value.
+   * - String: treated as a literal separator (regex specials are escaped)
+   * - Object: { pattern: string; flags?: string } builds a RegExp directly
+   * - Default: /\s+/
+   */
+  delimiter?: string | { pattern: string; flags?: string };
+
+  /**
+   * Whether to trim each split part.
+   * Default: true
+   */
+  trim?: boolean;
+
+  /**
+   * Whether to skip empty strings after splitting/trimming.
+   * Default: true
+   */
+  skipEmpty?: boolean;
+
+  /**
+   * Whether to remove duplicate values.
+   * Default: false
+   */
+  dedupe?: boolean;
+}
+
+/**
+ * Escapes regex metacharacters so a string delimiter is treated literally.
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Built-in class parser that splits an attribute value into an array.
+ * Registered under the name 'splitter' in globalParserRegistry.
+ */
+export class SplitParser implements AttrParser {
+  private delimiter: RegExp;
+  private trim: boolean;
+  private skipEmpty: boolean;
+  private dedupe: boolean;
+
+  constructor(options?: SplitParserOptions) {
+    const opts = options ?? {};
+    const rawDelimiter = opts.delimiter;
+
+    if (rawDelimiter === undefined) {
+      this.delimiter = /\s+/;
+    } else if (typeof rawDelimiter === 'string') {
+      this.delimiter = rawDelimiter === '' ? /(?:)/ : new RegExp(escapeRegex(rawDelimiter));
+    } else {
+      this.delimiter = new RegExp(rawDelimiter.pattern, rawDelimiter.flags ?? '');
+    }
+
+    this.trim = opts.trim ?? true;
+    this.skipEmpty = opts.skipEmpty ?? true;
+    this.dedupe = opts.dedupe ?? false;
+  }
+
+  parse(v: string | null, _context?: ParserContext): any {
+    if (v === null || v === '') {
+      return [];
+    }
+
+    let parts = v.split(this.delimiter);
+
+    if (this.trim) {
+      parts = parts.map((s) => s.trim());
+    }
+
+    if (this.skipEmpty) {
+      parts = parts.filter((s) => s !== '');
+    }
+
+    if (this.dedupe) {
+      parts = [...new Set(parts)];
+    }
+
+    return parts;
+  }
+}

package/inferencer/types/NewHTMLFirstCustomElement.md

@@ -7,6 +7,8 @@
 
 - **[plus-minus](https://github.com/bahrus/plus-minus)** -- Expand / Collapse component - More robust examples of dynamic DOM manipulation with the help of roundabout configuration.  Also demonstrates use of the DX libraries to get typing intellisense help.
 
+- **[side-burger](https://github.com/bahrus/side-burger)** -- Side Drawer component with menu.  
+
 ## Step 4
 
 Add the following additional dependencies in package.json:
@@ -379,7 +381,7 @@ Work is underway to improve the DX a bit, but for now:
 
 ```JS
 {
-    delay:10, //milliseconds
+    delay:100, //milliseconds
     ifAllOf: ['expanded'],
     assign: {
         set($.querySelector('a').focus()).to({}),
@@ -387,6 +389,69 @@ Work is underway to improve the DX a bit, but for now:
 },
 ```
 
+## How can I set externally specified elements to inert?
+
+This is implemented with the [side-burger](https://github.com/bahrus/side-burger) custom element, to see the full context.
+
+Suppose we define a property on the custom element, "inertTarget" which allows the developer to specify css matches from the root document to set to inert when the sidebar is open.  
+
+```JS
+
+// kept separate because "smoothOver" destroys typechecking
+/** @type Merges<AP> */
+const merges = [
+    ...
+    {
+        ifAllOf: [props.clone, props.inertTarget, props.open],
+        ...doAssign(
+            set(props.inertTargetElements).to($.ownerDocument.querySelectorAll($.inertTarget)),
+            set($.inertTargetElements.Each.inert).to(true)
+        )
+    },
+    {
+        ifAllOf: [props.clone, props.inertTarget],
+        ifNoneOf: [props.open],
+        ...doAssign(
+            set($.inertTargetElements.Each.inert).to(false)
+        )
+    }
+];
+
+/** @type {AttrPatterns<AP>} */
+const withAttrs = {
+    ...
+    [props.inertTarget]: 'inert-target',
+    [`_${props.inertTarget}`]: {
+        mapsTo: props.inertTarget,
+    }
+}
+
+/**
+ * @type {RoundaboutOptions<AP, Actions, AP, 'click' | 'keydown'>}
+ */
+const raConfig = {
+    weakRef: {
+        ...
+        listProperties: [props.inertTargetElements],
+        ...
+    },
+    
+    assignOptions: {
+        akaMethods: {
+            ...
+            '🧺': m['🧺'], //querySelectorAll
+        },
+        substitutions: {
+            inertTarget: '?.inertTarget'
+        }
+    },
+    ...
+    merges: smoothOver(merges),
+    ...
+};
+```
+
+
 ## 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/roundabout/types.d.ts

@@ -224,7 +224,14 @@ export interface WeakRefConfig<TProps = any> {
     /**
      * Properties to automatically wrap in WeakRef
      */
-    properties: Array<keyof TProps & string>;
+    properties?: Array<keyof TProps & string>;
+
+    /**
+     * Array-valued properties whose elements should be stored as WeakRefs.
+     * When accessed, the getter returns a new array with each WeakRef dereferenced.
+     * Collected elements appear as `undefined` in their original positions.
+     */
+    listProperties?: Array<keyof TProps & string>;
     
     /**
      * Logging behavior when deref returns null/undefined

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.83",
+  "version": "0.0.85",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -51,6 +51,10 @@
     "./parserRegistry.js": {
       "default": "./parserRegistry.js"
     },
+    "./SplitParser.js": {
+      "default": "./SplitParser.js",
+      "types": "./SplitParser.ts"
+    },
     "./parseWithAttrs.js": {
       "default": "./parseWithAttrs.js",
       "types": "./parseWithAttrs.ts"

package/parseWithAttrs.js

@@ -3,19 +3,61 @@ import { resolveTemplate } from './resolve/resolveTemplate.js';
 // Module-level cache for parsed attribute values
 // Structure: Map<configKey, Map<attrValue, parsedValue>>
 const parseCache = new Map();
+/**
+ * Detects whether a value is a class-based parser constructor.
+ * Class parsers must have a `parse` method on their prototype.
+ */
+function isAttrParserConstructor(value) {
+    return typeof value === 'function' && !!value.prototype && 'parse' in value.prototype;
+}
+/**
+ * Instantiates a class parser and returns a wrapper function that calls its parse method.
+ * A new instance is created for each attribute parse (no cross-call caching).
+ */
+function instantiateClassParser(ParserCtor, options) {
+    const instance = new ParserCtor(options);
+    return (attrValue, context) => instance.parse(attrValue, context);
+}
+/**
+ * Looks up a named parser in the scoped (if available) then global registry.
+ */
+function lookupNamedParser(name, synthesizerElement) {
+    // Check scoped registry first (if synthesizerElement provided)
+    if (synthesizerElement) {
+        const scopedRegistry = getParserRegistry(synthesizerElement);
+        const scopedParser = scopedRegistry.get(name);
+        if (scopedParser) {
+            return scopedParser;
+        }
+    }
+    // Fallback to global registry
+    const globalParser = globalParserRegistry.get(name);
+    if (globalParser) {
+        return globalParser;
+    }
+    // Not found in either registry
+    throw new Error(`Parser "${name}" not found. ` +
+        `Checked ${synthesizerElement ? 'scoped registry and ' : ''}global registry.\n` +
+        `Ensure the parser is registered via:\n` +
+        `- <script type="emc-parser" src="..." parser-name="${name}">\n` +
+        `- registerParser(synthesizerElement, "${name}", parserFn)\n` +
+        `- globalParserRegistry.register("${name}", parserFn)`);
+}
 /**
  * Resolves a parser specification to an actual parser function
  * Supports:
  * - Inline functions (direct use)
- * - Named parsers from scoped registry (if synthesizerElement provided)
- * - Named parsers from global registry (fallback)
+ * - Named parser functions or class constructors from scoped/global registry (string form)
+ * - Named class parsers with options from the object form { name, options }
+ * - Custom element static methods via tuple form [elementName, methodName]
  *
- * @param parserSpec - Parser function or string reference
+ * @param parserSpec - Parser function, string reference, tuple, or object reference
  * @param synthesizerElement - Optional synthesizer element for scoped parser lookup
+ * @param parserOptions - Optional constructor options when a string resolves to a class parser
  * @returns The resolved parser function
  * @throws Error if parser cannot be resolved
  */
-function resolveParser(parserSpec, synthesizerElement) {
+function resolveParser(parserSpec, synthesizerElement, parserOptions) {
     // Undefined - no parser specified
     if (parserSpec === undefined) {
         return undefined;
@@ -24,31 +66,61 @@ function resolveParser(parserSpec, synthesizerElement) {
     if (typeof parserSpec === 'function') {
         return parserSpec;
     }
+    // Object form: { name, options }
+    if (parserSpec !== null &&
+        typeof parserSpec === 'object' &&
+        !Array.isArray(parserSpec) &&
+        'name' in parserSpec) {
+        const { name, options } = parserSpec;
+        const registered = lookupNamedParser(name, synthesizerElement);
+        if (isAttrParserConstructor(registered)) {
+            return instantiateClassParser(registered, options);
+        }
+        return registered;
+    }
     // String reference - resolve from scoped or global registry
     if (typeof parserSpec === 'string') {
-        // Check scoped registry first (if synthesizerElement provided)
-        if (synthesizerElement) {
-            const scopedRegistry = getParserRegistry(synthesizerElement);
-            const scopedParser = scopedRegistry.get(parserSpec);
-            if (scopedParser) {
-                return scopedParser;
-            }
+        const registered = lookupNamedParser(parserSpec, synthesizerElement);
+        if (isAttrParserConstructor(registered)) {
+            return instantiateClassParser(registered, parserOptions);
+        }
+        return registered;
+    }
+    // Tuple reference: [elementName, methodName]
+    if (Array.isArray(parserSpec) && parserSpec.length === 2) {
+        const [elementName, methodName] = parserSpec;
+        const Ctr = customElements.get(elementName);
+        if (!Ctr) {
+            throw new Error(`Cannot resolve parser [${elementName}, ${methodName}]: custom element "${elementName}" not found`);
         }
-        // Fallback to global registry
-        const globalParser = globalParserRegistry.get(parserSpec);
-        if (globalParser) {
-            return globalParser;
+        const method = Ctr[methodName];
+        if (typeof method !== 'function') {
+            throw new Error(`Cannot resolve parser [${elementName}, ${methodName}]: static method "${methodName}" not found on custom element "${elementName}"`);
         }
-        // Not found in either registry
-        throw new Error(`Parser "${parserSpec}" not found. ` +
-            `Checked ${synthesizerElement ? 'scoped registry and ' : ''}global registry.\n` +
-            `Ensure the parser is registered via:\n` +
-            `- <script type="emc-parser" src="..." parser-name="${parserSpec}">\n` +
-            `- registerParser(synthesizerElement, "${parserSpec}", parserFn)\n` +
-            `- globalParserRegistry.register("${parserSpec}", parserFn)`);
+        return method.bind(Ctr);
     }
     return undefined;
 }
+/**
+ * Serializes parser options for use in cache keys.
+ * RegExp values are normalized to their string representation.
+ */
+function serializeParserOptions(options) {
+    if (options === undefined || options === null) {
+        return '';
+    }
+    try {
+        return JSON.stringify(options, (_key, value) => {
+            if (value instanceof RegExp) {
+                return value.toString();
+            }
+            return value;
+        });
+    }
+    catch (_e) {
+        return String(options);
+    }
+}
 /**
  * Creates a cache key from an AttrConfig
  * Includes instanceOf and parser identifier to ensure correct cache hits
@@ -63,7 +135,19 @@ function getCacheKey(config) {
         parserStr = 'builtin';
     }
     else if (typeof config.parser === 'string') {
-        parserStr = `named:${config.parser}`;
+        const optionsStr = serializeParserOptions(config.parserOptions);
+        parserStr = `named:${config.parser}|options:${optionsStr}`;
+    }
+    else if (config.parser !== null &&
+        typeof config.parser === 'object' &&
+        !Array.isArray(config.parser) &&
+        'name' in config.parser) {
+        const ref = config.parser;
+        const optionsStr = serializeParserOptions(ref.options);
+        parserStr = `named:${ref.name}|options:${optionsStr}`;
+    }
+    else if (Array.isArray(config.parser)) {
+        parserStr = `tuple:${config.parser[0]},${config.parser[1]}`;
     }
     else {
         parserStr = 'custom';
@@ -328,7 +412,7 @@ export function parseWithAttrs(element, attrPatterns, allowUnprefixed, spawnCont
             }
             // For Boolean without valIfNull, fall through to parser
             else {
-                const parser = resolveParser(config.parser, synthesizerElement) || getDefaultParser(config.instanceOf);
+                const parser = resolveParser(config.parser, synthesizerElement, config.parserOptions) || getDefaultParser(config.instanceOf);
                 const parsedValue = callParser(parser, attrValue, parserContext);
                 const mapsTo = config.mapsTo ?? (key === 'base' ? '.' : key);
                 result[mapsTo] = parsedValue;
@@ -336,7 +420,7 @@ export function parseWithAttrs(element, attrPatterns, allowUnprefixed, spawnCont
             continue;
         }
         // Attribute exists - parse normally
-        const parser = resolveParser(config.parser, synthesizerElement) || getDefaultParser(config.instanceOf);
+        const parser = resolveParser(config.parser, synthesizerElement, config.parserOptions) || getDefaultParser(config.instanceOf);
         // Use cache if parseCache is specified
         const parsedValue = config.parseCache
             ? parseWithCache(attrValue, config, parser, parserContext)