bitwrench 2.0.7 → 2.0.9

package/dist/bitwrench.es5.js

@@ -1,4 +1,4 @@
-/*! bitwrench v2.0.7 | BSD-2-Clause | http://deftio.com/bitwrench */
+/*! bitwrench v2.0.9 | BSD-2-Clause | http://deftio.com/bitwrench */
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
   typeof define === 'function' && define.amd ? define(factory) :
@@ -203,14 +203,14 @@
    */
 
   var VERSION_INFO = {
-    version: '2.0.7',
+    version: '2.0.9',
     name: 'bitwrench',
     description: 'A library for javascript UI functions.',
     license: 'BSD-2-Clause',
     homepage: 'http://deftio.com/bitwrench',
     repository: 'git+https://github.com/deftio/bitwrench.git',
     author: 'manu a. chatterjee <deftio@deftio.com> (https://deftio.com/)',
-    buildDate: '2026-03-06T09:27:27.033Z'
+    buildDate: '2026-03-07T02:56:20.305Z'
   };
 
   /**
@@ -3683,8 +3683,8 @@
     var props = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
     var children = props.children,
       onsubmit = props.onsubmit,
-      _props$className10 = props.className,
-      className = _props$className10 === void 0 ? '' : _props$className10;
+      _props$className0 = props.className,
+      className = _props$className0 === void 0 ? '' : _props$className0;
     return {
       t: 'form',
       a: {
@@ -3784,8 +3784,8 @@
       readonly = _props$readonly === void 0 ? false : _props$readonly,
       _props$required = props.required,
       required = _props$required === void 0 ? false : _props$required,
-      _props$className11 = props.className,
-      className = _props$className11 === void 0 ? '' : _props$className11,
+      _props$className1 = props.className,
+      className = _props$className1 === void 0 ? '' : _props$className1,
       style = props.style,
       eventHandlers = _objectWithoutProperties(props, _excluded$1);
     return {
@@ -3841,8 +3841,8 @@
       readonly = _props$readonly2 === void 0 ? false : _props$readonly2,
       _props$required2 = props.required,
       required = _props$required2 === void 0 ? false : _props$required2,
-      _props$className12 = props.className,
-      className = _props$className12 === void 0 ? '' : _props$className12,
+      _props$className10 = props.className,
+      className = _props$className10 === void 0 ? '' : _props$className10,
       eventHandlers = _objectWithoutProperties(props, _excluded2);
     return {
       t: 'textarea',
@@ -3896,8 +3896,8 @@
       disabled = _props$disabled4 === void 0 ? false : _props$disabled4,
       _props$required3 = props.required,
       required = _props$required3 === void 0 ? false : _props$required3,
-      _props$className13 = props.className,
-      className = _props$className13 === void 0 ? '' : _props$className13,
+      _props$className11 = props.className,
+      className = _props$className11 === void 0 ? '' : _props$className11,
       eventHandlers = _objectWithoutProperties(props, _excluded3);
     return {
       t: 'select',
@@ -4004,8 +4004,8 @@
       direction = _props$direction === void 0 ? 'vertical' : _props$direction,
       _props$gap = props.gap,
       gap = _props$gap === void 0 ? 3 : _props$gap,
-      _props$className14 = props.className,
-      className = _props$className14 === void 0 ? '' : _props$className14;
+      _props$className12 = props.className,
+      className = _props$className12 === void 0 ? '' : _props$className12;
     return {
       t: 'div',
       a: {
@@ -4096,8 +4096,8 @@
       overlay = _props$overlay === void 0 ? false : _props$overlay,
       backgroundImage = props.backgroundImage,
       actions = props.actions,
-      _props$className15 = props.className,
-      className = _props$className15 === void 0 ? '' : _props$className15;
+      _props$className13 = props.className,
+      className = _props$className13 === void 0 ? '' : _props$className13;
     var sizeClasses = {
       sm: 'bw-py-3',
       md: 'bw-py-4',
@@ -4186,8 +4186,8 @@
       centered = _props$centered2 === void 0 ? true : _props$centered2,
       _props$iconSize = props.iconSize,
       iconSize = _props$iconSize === void 0 ? '3rem' : _props$iconSize,
-      _props$className16 = props.className,
-      className = _props$className16 === void 0 ? '' : _props$className16;
+      _props$className14 = props.className,
+      className = _props$className14 === void 0 ? '' : _props$className14;
     var colClass = "bw-col-md-".concat(12 / columns);
     return {
       t: 'div',
@@ -4267,8 +4267,8 @@
       variant = _props$variant7 === void 0 ? 'light' : _props$variant7,
       _props$centered3 = props.centered,
       centered = _props$centered3 === void 0 ? true : _props$centered3,
-      _props$className17 = props.className,
-      className = _props$className17 === void 0 ? '' : _props$className17;
+      _props$className15 = props.className,
+      className = _props$className15 === void 0 ? '' : _props$className15;
     return {
       t: 'section',
       a: {
@@ -4337,8 +4337,8 @@
       variant = _props$variant8 === void 0 ? 'default' : _props$variant8,
       _props$spacing = props.spacing,
       spacing = _props$spacing === void 0 ? 'md' : _props$spacing,
-      _props$className18 = props.className,
-      className = _props$className18 === void 0 ? '' : _props$className18;
+      _props$className16 = props.className,
+      className = _props$className16 === void 0 ? '' : _props$className16;
     var spacingClasses = {
       sm: 'bw-py-3',
       md: 'bw-py-4',
@@ -4921,6 +4921,26 @@
     _subIdCounter: 0,
     // monotonic ID for subscriptions
 
+    // ── Node reference cache ──────────────────────────────────────────────
+    // Fast O(1) lookup for elements by bw_id, id attribute, or bw_uuid.
+    //
+    // Populated by bw.createDOM() when elements have:
+    //   - data-bw-id attribute (user-declared addressable elements)
+    //   - id attribute (standard HTML id)
+    //   - bw_uuid (internal, for lifecycle-managed elements)
+    //
+    // Cleaned up by bw.cleanup() when elements are destroyed via bitwrench APIs.
+    // On cache miss, falls back to querySelector/getElementById — never fails,
+    // just slower. Stale entries (refs to detached nodes) are removed on miss
+    // via parentNode === null check (IE11-safe, unlike el.isConnected).
+    //
+    // Elements created via bw.createDOM() also get el._bw_refs — a local map of
+    // child bw_id → DOM node ref for fast parent→child access in o.render.
+    // This is the bitwrench equivalent of React's compiled template "holes".
+    //
+    // Contract: if you remove elements outside of bitwrench APIs (raw el.remove()),
+    // map entries may linger until the next lookup attempt cleans them.
+    _nodeMap: {},
     // Monkey patch for testing (same as v1)
     __monkey_patch_is_nodejs__: {
       _value: 'ignore',
@@ -5145,6 +5165,107 @@
     return "".concat(tag).concat(timestamp, "_").concat(counter, "_").concat(random);
   };
 
+  /**
+   * Look up a DOM element by ID string, using the node cache for O(1) access.
+   *
+   * Resolution order:
+   * 1. Check `bw._nodeMap[id]` — if found and still attached (parentNode !== null), return it
+   * 2. If cached ref is detached (parentNode === null), remove stale entry
+   * 3. Fall back to `document.getElementById(id)` then `document.querySelector(...)`
+   * 4. If fallback finds the element, cache it for next time
+   * 5. If not found anywhere, return null
+   *
+   * Accepts a DOM element directly (pass-through) or a string identifier.
+   * String identifiers are tried as: direct map key, getElementById,
+   * querySelector (for CSS selectors starting with . or #), and
+   * data-bw-id attribute selector.
+   *
+   * @param {string|Element} id - Element ID, CSS selector, data-bw-id value, or DOM element
+   * @returns {Element|null} The DOM element, or null if not found
+   * @category Internal
+   */
+  bw._el = function (id) {
+    // Pass-through for DOM elements
+    if (typeof id !== 'string') return id || null;
+    if (!id) return null;
+    if (!bw._isBrowser) return null;
+
+    // 1. Check cache
+    var cached = bw._nodeMap[id];
+    if (cached) {
+      // Verify not detached (parentNode check is IE11-safe)
+      if (cached.parentNode !== null) {
+        return cached;
+      }
+      // Stale — remove and fall through
+      delete bw._nodeMap[id];
+    }
+
+    // 2. DOM fallback: try getElementById first (fastest native lookup)
+    var el = document.getElementById(id);
+
+    // 3. Try querySelector for CSS selectors (starts with # or .)
+    if (!el && (id.charAt(0) === '#' || id.charAt(0) === '.')) {
+      el = document.querySelector(id);
+    }
+
+    // 4. Try data-bw-id attribute (for bw.uuid-generated IDs)
+    if (!el) {
+      el = document.querySelector('[data-bw-id="' + id + '"]');
+    }
+
+    // 5. Cache the result for next time
+    if (el) {
+      bw._nodeMap[id] = el;
+    }
+    return el;
+  };
+
+  /**
+   * Register a DOM element in the node cache under one or more keys.
+   *
+   * Called internally by `bw.createDOM()`. Registers elements that have
+   * id attributes, data-bw-id attributes, or both.
+   *
+   * @param {Element} el - DOM element to register
+   * @param {string} [bwId] - data-bw-id value to register under
+   * @category Internal
+   */
+  bw._registerNode = function (el, bwId) {
+    if (!el) return;
+    // Register under data-bw-id
+    if (bwId) {
+      bw._nodeMap[bwId] = el;
+    }
+    // Register under id attribute
+    var htmlId = el.getAttribute ? el.getAttribute('id') : null;
+    if (htmlId) {
+      bw._nodeMap[htmlId] = el;
+    }
+  };
+
+  /**
+   * Remove a DOM element from the node cache.
+   *
+   * Called internally by `bw.cleanup()` when elements are destroyed
+   * through bitwrench APIs.
+   *
+   * @param {Element} el - DOM element to deregister
+   * @param {string} [bwId] - data-bw-id value to remove
+   * @category Internal
+   */
+  bw._deregisterNode = function (el, bwId) {
+    // Remove data-bw-id entry
+    if (bwId) {
+      delete bw._nodeMap[bwId];
+    }
+    // Remove id attribute entry
+    var htmlId = el && el.getAttribute ? el.getAttribute('id') : null;
+    if (htmlId) {
+      delete bw._nodeMap[htmlId];
+    }
+  };
+
   /**
    * Escape HTML special characters to prevent XSS.
    *
@@ -5381,26 +5502,66 @@
       }
     }
 
-    // Add children
+    // Add children, building _bw_refs for fast parent→child access.
+    // Children with data-bw-id or id attributes get local refs on the parent,
+    // so o.render functions can access them without any DOM lookup.
     if (content != null) {
       if (Array.isArray(content)) {
         content.forEach(function (child) {
           if (child != null) {
-            el.appendChild(bw.createDOM(child, options));
+            var childEl = bw.createDOM(child, options);
+            el.appendChild(childEl);
+            // Build local refs for addressable children
+            var childBwId = child && child.a ? child.a['data-bw-id'] || child.a.id : null;
+            if (childBwId) {
+              if (!el._bw_refs) el._bw_refs = {};
+              el._bw_refs[childBwId] = childEl;
+            }
+            // Bubble up grandchild refs (flatten one level)
+            if (childEl._bw_refs) {
+              if (!el._bw_refs) el._bw_refs = {};
+              for (var rk in childEl._bw_refs) {
+                if (Object.prototype.hasOwnProperty.call(childEl._bw_refs, rk)) {
+                  el._bw_refs[rk] = childEl._bw_refs[rk];
+                }
+              }
+            }
           }
         });
       } else if (_typeof(content) === 'object' && content.t) {
-        el.appendChild(bw.createDOM(content, options));
+        var childEl = bw.createDOM(content, options);
+        el.appendChild(childEl);
+        var childBwId = content.a ? content.a['data-bw-id'] || content.a.id : null;
+        if (childBwId) {
+          if (!el._bw_refs) el._bw_refs = {};
+          el._bw_refs[childBwId] = childEl;
+        }
+        if (childEl._bw_refs) {
+          if (!el._bw_refs) el._bw_refs = {};
+          for (var rk in childEl._bw_refs) {
+            if (Object.prototype.hasOwnProperty.call(childEl._bw_refs, rk)) {
+              el._bw_refs[rk] = childEl._bw_refs[rk];
+            }
+          }
+        }
       } else {
         el.textContent = String(content);
       }
     }
 
+    // Register element in node cache if it has an id attribute
+    if (attrs.id) {
+      bw._registerNode(el, null);
+    }
+
     // Handle lifecycle hooks and state
     if (opts.mounted || opts.unmount || opts.render || opts.state) {
       var id = attrs['data-bw-id'] || bw.uuid();
       el.setAttribute('data-bw-id', id);
 
+      // Register in node cache under data-bw-id
+      bw._registerNode(el, id);
+
       // Store state
       if (opts.state) {
         el._bw_state = opts.state;
@@ -5442,6 +5603,9 @@
           opts.unmount(el, el._bw_state || {});
         });
       }
+    } else if (attrs['data-bw-id']) {
+      // Element has explicit data-bw-id but no lifecycle hooks — still register it
+      bw._registerNode(el, attrs['data-bw-id']);
     }
     return el;
   };
@@ -5476,8 +5640,8 @@
       throw new Error('bw.DOM requires a DOM environment (document/window). Use bw.html() instead.');
     }
 
-    // Get target element
-    var targetEl = typeof target === 'string' ? document.querySelector(target) : target;
+    // Get target element (use cache-backed lookup)
+    var targetEl = bw._el(target);
     if (!targetEl) {
       console.error('bw.DOM: Target element not found:', target);
       return null;
@@ -5498,7 +5662,11 @@
     // Restore the target's own state/render/subs after cleanup
     if (savedState !== undefined) targetEl._bw_state = savedState;
     if (savedRender) targetEl._bw_render = savedRender;
-    if (savedBwId) targetEl.setAttribute('data-bw-id', savedBwId);
+    if (savedBwId) {
+      targetEl.setAttribute('data-bw-id', savedBwId);
+      // Re-register mount point in node cache (cleanup deregistered it)
+      bw._registerNode(targetEl, savedBwId);
+    }
     if (savedSubs) targetEl._bw_subs = savedSubs;
 
     // Clear and mount new content
@@ -5749,6 +5917,9 @@
         bw._unmountCallbacks["delete"](id);
       }
 
+      // Deregister from node cache
+      bw._deregisterNode(el, id);
+
       // Clean up pub/sub subscriptions tied to this element
       if (el._bw_subs) {
         el._bw_subs.forEach(function (unsub) {
@@ -5757,9 +5928,10 @@
         delete el._bw_subs;
       }
 
-      // Clean up state and render
+      // Clean up state, render, and local refs
       delete el._bw_state;
       delete el._bw_render;
+      delete el._bw_refs;
     });
 
     // Check element itself
@@ -5770,6 +5942,10 @@
         callback();
         bw._unmountCallbacks["delete"](id);
       }
+
+      // Deregister from node cache
+      bw._deregisterNode(element, id);
+
       // Clean up pub/sub subscriptions tied to element itself
       if (element._bw_subs) {
         element._bw_subs.forEach(function (unsub) {
@@ -5779,6 +5955,7 @@
       }
       delete element._bw_state;
       delete element._bw_render;
+      delete element._bw_refs;
     }
   };
 
@@ -5793,7 +5970,7 @@
    * Calls `el._bw_render(el, state)` and emits `bw:statechange` so other
    * components can react without tight coupling.
    *
-   * @param {string|Element} target - CSS selector or DOM element with _bw_render
+   * @param {string|Element} target - Element ID, data-bw-id, CSS selector, or DOM element
    * @returns {Element|null} The element, or null if not found / no render function
    * @category State Management
    * @see bw.patch
@@ -5803,7 +5980,7 @@
    * bw.update(el);  // re-renders, emits bw:statechange
    */
   bw.update = function (target) {
-    var el = typeof target === 'string' ? document.querySelector(target) : target;
+    var el = bw._el(target);
     if (el && el._bw_render) {
       el._bw_render(el, el._bw_state || {});
       bw.emit(el, 'statechange', el._bw_state);
@@ -5818,7 +5995,8 @@
    * Use `bw.patch()` for lightweight value updates (scores, labels, counters)
    * and `bw.update()` for full structural re-renders.
    *
-   * @param {string|Element} id - Element ID string or DOM element
+   * @param {string|Element} id - Element ID, data-bw-id, CSS selector, or DOM element.
+   *   Uses node cache for O(1) lookup; falls back to DOM query on cache miss.
    * @param {string|Object} content - New text content, or TACO object to replace children
    * @param {string} [attr] - If provided, sets this attribute instead of content
    * @returns {Element|null} The patched element, or null if not found
@@ -5831,7 +6009,7 @@
    * bw.patch('info', { t: 'em', c: 'new' }); // replace children with TACO
    */
   bw.patch = function (id, content, attr) {
-    var el = typeof id === 'string' ? document.getElementById(id) : id;
+    var el = bw._el(id);
     if (!el) return null;
     if (attr) {
       // Patch an attribute
@@ -5881,7 +6059,8 @@
    * bubble by default so ancestor elements can listen. Use with `bw.on()` for
    * DOM-scoped communication between components.
    *
-   * @param {string|Element} target - CSS selector or DOM element
+   * @param {string|Element} target - Element ID, data-bw-id, CSS selector, or DOM element.
+   *   Uses node cache for O(1) lookup; falls back to DOM query on cache miss.
    * @param {string} eventName - Event name (will be prefixed with 'bw:')
    * @param {*} [detail] - Data to pass with the event
    * @category Events (DOM)
@@ -5891,7 +6070,7 @@
    * // Dispatches CustomEvent 'bw:statechange' on the element
    */
   bw.emit = function (target, eventName, detail) {
-    var el = typeof target === 'string' ? document.querySelector(target) : target;
+    var el = bw._el(target);
     if (el) {
       el.dispatchEvent(new CustomEvent('bw:' + eventName, {
         bubbles: true,
@@ -5907,7 +6086,8 @@
    * is the first argument so you don't need to destructure `e.detail`.
    * Events bubble, so you can listen on an ancestor element.
    *
-   * @param {string|Element} target - CSS selector or DOM element
+   * @param {string|Element} target - Element ID, data-bw-id, CSS selector, or DOM element.
+   *   Uses node cache for O(1) lookup; falls back to DOM query on cache miss.
    * @param {string} eventName - Event name (will be prefixed with 'bw:')
    * @param {Function} handler - Called with (detail, event)
    * @returns {Element|null} The element (for chaining), or null if not found
@@ -5919,7 +6099,7 @@
    * });
    */
   bw.on = function (target, eventName, handler) {
-    var el = typeof target === 'string' ? document.querySelector(target) : target;
+    var el = bw._el(target);
     if (el) {
       el.addEventListener('bw:' + eventName, function (e) {
         handler(e.detail, e);
@@ -6094,9 +6274,9 @@
               value = _ref8[1];
             return value != null;
           }).map(function (_ref9) {
-            var _ref10 = _slicedToArray(_ref9, 2),
-              prop = _ref10[0],
-              value = _ref10[1];
+            var _ref0 = _slicedToArray(_ref9, 2),
+              prop = _ref0[0],
+              value = _ref0[1];
             // Convert camelCase to kebab-case
             var kebabProp = prop.replace(/[A-Z]/g, function (m) {
               return '-' + m.toLowerCase();
@@ -8378,10 +8558,10 @@
   };
 
   // Register all make functions
-  Object.entries(components).forEach(function (_ref11) {
-    var _ref12 = _slicedToArray(_ref11, 2),
-      name = _ref12[0],
-      fn = _ref12[1];
+  Object.entries(components).forEach(function (_ref1) {
+    var _ref10 = _slicedToArray(_ref1, 2),
+      name = _ref10[0],
+      fn = _ref10[1];
     if (name.startsWith('make')) {
       bw[name] = fn;
     }
@@ -8391,10 +8571,10 @@
   bw._componentHandles = componentHandles || {};
 
   // Create functions that return handles
-  Object.entries(components).forEach(function (_ref13) {
-    var _ref14 = _slicedToArray(_ref13, 2),
-      name = _ref14[0],
-      fn = _ref14[1];
+  Object.entries(components).forEach(function (_ref11) {
+    var _ref12 = _slicedToArray(_ref11, 2),
+      name = _ref12[0],
+      fn = _ref12[1];
     if (name.startsWith('make')) {
       var componentType = name.substring(4).toLowerCase(); // Remove 'make' prefix
       var createName = 'create' + name.substring(4); // createCard, createTable, etc.