bitwrench 2.0.15 → 2.0.16

package/dist/bitwrench.es5.js

@@ -1,4 +1,4 @@
-/*! bitwrench v2.0.15 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench v2.0.16 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
   typeof define === 'function' && define.amd ? define(factory) :
@@ -189,14 +189,14 @@
    */
 
   var VERSION_INFO = {
-    version: '2.0.15',
+    version: '2.0.16',
     name: 'bitwrench',
     description: 'A library for javascript UI functions.',
     license: 'BSD-2-Clause',
     homepage: 'https://deftio.github.com/bitwrench/pages',
     repository: 'git+https://github.com/deftio/bitwrench.git',
     author: 'manu a. chatterjee <deftio@deftio.com> (https://deftio.com/)',
-    buildDate: '2026-03-10T09:08:17.015Z'
+    buildDate: '2026-03-12T08:05:52.043Z'
   };
 
   /**
@@ -609,12 +609,11 @@
     var lightBase = config.light || hslToHex([h, 8, 97]);
     var darkBase = config.dark || hslToHex([h, 10, 13]);
 
-    // Background & surface tokens — default to light (white/near-white).
-    // Dark backgrounds require explicit config.background / config.surface.
-    // Primary/secondary colors are accents, not page backgrounds, so
-    // isLightPalette should NOT drive bg/surface defaults.
-    var bgBase = config.background || '#ffffff';
-    var surfBase = config.surface || '#f8f9fa';
+    // Background & surface tokens — tinted with primary hue for theme personality.
+    // Very subtle: bg at L=98/S=6, surface at L=96/S=8.
+    // User can override with config.background / config.surface.
+    var bgBase = config.background || hslToHex([h, 6, 98]);
+    var surfBase = config.surface || hslToHex([h, 8, 96]);
     var palette = {
       primary: deriveShades(config.primary),
       secondary: deriveShades(config.secondary),
@@ -1857,8 +1856,8 @@
       },
       '.bw_container_fluid': {
         'width': '100%',
-        'padding-right': '15px',
-        'padding-left': '15px',
+        'padding-right': '0.75rem',
+        'padding-left': '0.75rem',
         'margin-right': 'auto',
         'margin-left': 'auto'
       },
@@ -2234,7 +2233,9 @@
         'line-height': '1.3',
         'text-align': 'center',
         'white-space': 'nowrap',
-        'vertical-align': 'baseline'
+        'vertical-align': 'baseline',
+        'padding': '0.35rem 0.65rem',
+        'border-radius': '0.25rem'
       },
       '.bw_badge:empty': {
         'display': 'none'
@@ -2699,7 +2700,8 @@
       '.bw_code_pre': {
         'margin': '0',
         'border': 'none',
-        'overflow-x': 'auto'
+        'overflow-x': 'auto',
+        'max-width': '100%'
       },
       '.bw_code_block': {
         'display': 'block',
@@ -2928,7 +2930,7 @@
       },
       '.bw_modal_dialog': {
         'position': 'relative',
-        'width': '100%',
+        'width': 'calc(100% - 1rem)',
         'max-width': '500px',
         'margin': '1.75rem auto',
         'pointer-events': 'none'
@@ -3017,7 +3019,7 @@
       '.bw_toast': {
         'pointer-events': 'auto',
         'width': '350px',
-        'max-width': '100%',
+        'max-width': 'calc(100vw - 2rem)',
         'background-clip': 'padding-box',
         'opacity': '0'
       },
@@ -3224,6 +3226,7 @@
         'z-index': '999',
         'font-size': '0.875rem',
         'white-space': 'nowrap',
+        'max-width': 'min(300px, calc(100vw - 1rem))',
         'pointer-events': 'none',
         'opacity': '0',
         'visibility': 'hidden'
@@ -3282,7 +3285,7 @@
         'position': 'absolute',
         'z-index': '1000',
         'min-width': '200px',
-        'max-width': '320px',
+        'max-width': 'min(320px, calc(100vw - 2rem))',
         'pointer-events': 'none',
         'opacity': '0',
         'visibility': 'hidden'
@@ -3828,6 +3831,45 @@
         },
         '.bw_feature_grid, .bw_feature-grid': {
           'grid-template-columns': '1fr'
+        },
+        '.bw_modal_dialog': {
+          'margin': '0.5rem auto'
+        },
+        '.bw_modal_lg': {
+          'max-width': 'calc(100% - 1rem)'
+        },
+        '.bw_modal_xl': {
+          'max-width': 'calc(100% - 1rem)'
+        },
+        '.bw_navbar': {
+          'padding': '0.5rem 0.75rem'
+        },
+        '.bw_navbar_brand': {
+          'margin-right': '0.5rem',
+          'font-size': '1rem'
+        },
+        '.bw_navbar_nav': {
+          'flex-wrap': 'wrap'
+        },
+        '.bw_tooltip': {
+          'white-space': 'normal'
+        },
+        '.bw_table': {
+          'display': 'block',
+          'overflow-x': 'auto',
+          '-webkit-overflow-scrolling': 'touch'
+        },
+        '.bw_col, .bw_col_1, .bw_col_2, .bw_col_3, .bw_col_4, .bw_col_5, .bw_col_6, .bw_col_7, .bw_col_8, .bw_col_9, .bw_col_10, .bw_col_11, .bw_col_12': {
+          'flex': '0 0 100%',
+          'max-width': '100%'
+        },
+        '.bw_container': {
+          'padding-right': '0.5rem',
+          'padding-left': '0.5rem'
+        },
+        '.bw_container_fluid': {
+          'padding-right': '0.5rem',
+          'padding-left': '0.5rem'
         }
       }
     }
@@ -11711,6 +11753,376 @@
     return true;
   };
 
+  // ===================================================================================
+  // bw.clientApply() / bw.clientConnect() — Server-driven UI protocol
+  // ===================================================================================
+
+  /**
+   * Registry of named functions sent via register messages.
+   * Populated by clientApply({ type: 'register', name, body }).
+   * Invoked by clientApply({ type: 'call', name, args }).
+   * @private
+   */
+  bw._clientFunctions = {};
+
+  /**
+   * Whether exec messages are allowed. Set by clientConnect opts.allowExec.
+   * Default false — exec messages are rejected unless explicitly opted in.
+   * @private
+   */
+  bw._allowExec = false;
+
+  /**
+   * Built-in client functions available via call() without registration.
+   * @private
+   */
+  bw._builtinClientFunctions = {
+    scrollTo: function scrollTo(selector) {
+      var el = bw._el(selector);
+      if (el) el.scrollTop = el.scrollHeight;
+    },
+    focus: function focus(selector) {
+      var el = bw._el(selector);
+      if (el && typeof el.focus === 'function') el.focus();
+    },
+    download: function download(filename, content, mimeType) {
+      if (typeof document === 'undefined') return;
+      var blob = new Blob([content], {
+        type: mimeType || 'text/plain'
+      });
+      var a = document.createElement('a');
+      a.href = URL.createObjectURL(blob);
+      a.download = filename;
+      a.click();
+      URL.revokeObjectURL(a.href);
+    },
+    clipboard: function clipboard(text) {
+      if (typeof navigator !== 'undefined' && navigator.clipboard) {
+        navigator.clipboard.writeText(text);
+      }
+    },
+    redirect: function redirect(url) {
+      if (typeof window !== 'undefined') window.location.href = url;
+    },
+    log: function log() {
+      console.log.apply(console, arguments);
+    }
+  };
+
+  /**
+   * Parse a bwserve protocol message string, supporting both strict JSON
+   * and r-prefixed relaxed JSON (single-quoted strings, trailing commas).
+   *
+   * The r-prefix format is designed for C/C++ string literals where
+   * double-quote escaping is painful. The parser is a state machine
+   * that walks character by character — not a regex replace.
+   *
+   * Escaping: apostrophes inside single-quoted values must be escaped
+   * with backslash: r{'name':'Barry\'s room'}
+   *
+   * @param {string} str - JSON or r-prefixed relaxed JSON string
+   * @returns {Object} Parsed message object
+   * @throws {SyntaxError} If the string is not valid JSON or relaxed JSON
+   * @category Server
+   */
+  bw.clientParse = function (str) {
+    str = (str || '').trim();
+    if (str.charAt(0) !== 'r') return JSON.parse(str);
+    str = str.slice(1);
+    var out = [];
+    var i = 0;
+    var len = str.length;
+    while (i < len) {
+      var ch = str[i];
+      if (ch === "'") {
+        // Single-quoted string → emit as double-quoted
+        out.push('"');
+        i++;
+        while (i < len) {
+          var c = str[i];
+          if (c === '\\' && i + 1 < len) {
+            var next = str[i + 1];
+            if (next === "'") {
+              out.push("'"); // \' in input → ' in output
+            } else {
+              out.push('\\');
+              out.push(next);
+            }
+            i += 2;
+          } else if (c === '"') {
+            out.push('\\"');
+            i++;
+          } else if (c === "'") {
+            break;
+          } else {
+            out.push(c);
+            i++;
+          }
+        }
+        out.push('"');
+        i++; // skip closing '
+      } else if (ch === '"') {
+        // Double-quoted string — pass through verbatim
+        out.push(ch);
+        i++;
+        while (i < len) {
+          var c2 = str[i];
+          if (c2 === '\\' && i + 1 < len) {
+            out.push(c2);
+            out.push(str[i + 1]);
+            i += 2;
+          } else {
+            out.push(c2);
+            i++;
+            if (c2 === '"') break;
+          }
+        }
+      } else if (ch === ',') {
+        // Trailing comma check: skip comma if next non-whitespace is } or ]
+        var j = i + 1;
+        while (j < len && (str[j] === ' ' || str[j] === '\t' || str[j] === '\n' || str[j] === '\r')) j++;
+        if (j < len && (str[j] === '}' || str[j] === ']')) {
+          i++; // skip trailing comma
+        } else {
+          out.push(ch);
+          i++;
+        }
+      } else {
+        out.push(ch);
+        i++;
+      }
+    }
+    return JSON.parse(out.join(''));
+  };
+
+  /**
+   * Apply a bwserve protocol message to the DOM.
+   *
+   * Dispatches one of 9 message types:
+   *   replace  — bw.DOM(target, node)
+   *   append   — target.appendChild(bw.createDOM(node))
+   *   remove   — bw.cleanup(target); target.remove()
+   *   patch    — bw.patch(target, content, attr)
+   *   batch    — iterate ops, call clientApply for each
+   *   message  — bw.message(target, action, data)
+   *   register — store a named function for later call()
+   *   call     — invoke a registered or built-in function
+   *   exec     — execute arbitrary JS (requires allowExec)
+   *
+   * Target resolution:
+   *   Starts with '#' or '.' → CSS selector (querySelector)
+   *   Otherwise → getElementById, then bw._el fallback
+   *
+   * @param {Object} msg - Protocol message
+   * @returns {boolean} true if the message was applied successfully
+   * @category Server
+   */
+  bw.clientApply = function (msg) {
+    if (!msg || !msg.type) return false;
+    var type = msg.type;
+    var target = msg.target;
+    if (type === 'replace') {
+      var el = bw._el(target);
+      if (!el) return false;
+      bw.DOM(el, msg.node);
+      return true;
+    } else if (type === 'patch') {
+      var patched = bw.patch(target, msg.content, msg.attr);
+      return patched !== null;
+    } else if (type === 'append') {
+      var parent = bw._el(target);
+      if (!parent) return false;
+      var child = bw.createDOM(msg.node);
+      parent.appendChild(child);
+      return true;
+    } else if (type === 'remove') {
+      var toRemove = bw._el(target);
+      if (!toRemove) return false;
+      if (typeof bw.cleanup === 'function') bw.cleanup(toRemove);
+      toRemove.remove();
+      return true;
+    } else if (type === 'batch') {
+      if (!Array.isArray(msg.ops)) return false;
+      var allOk = true;
+      msg.ops.forEach(function (op) {
+        if (!bw.clientApply(op)) allOk = false;
+      });
+      return allOk;
+    } else if (type === 'message') {
+      return bw.message(msg.target, msg.action, msg.data);
+    } else if (type === 'register') {
+      if (!msg.name || !msg.body) return false;
+      try {
+        bw._clientFunctions[msg.name] = new Function('return ' + msg.body)();
+        return true;
+      } catch (e) {
+        console.error('[bw] register error:', msg.name, e);
+        return false;
+      }
+    } else if (type === 'call') {
+      if (!msg.name) return false;
+      var fn = bw._clientFunctions[msg.name] || bw._builtinClientFunctions[msg.name];
+      if (typeof fn !== 'function') return false;
+      try {
+        var args = Array.isArray(msg.args) ? msg.args : [];
+        fn.apply(null, args);
+        return true;
+      } catch (e) {
+        console.error('[bw] call error:', msg.name, e);
+        return false;
+      }
+    } else if (type === 'exec') {
+      if (!bw._allowExec) {
+        console.warn('[bw] exec rejected: allowExec is not enabled');
+        return false;
+      }
+      if (!msg.code) return false;
+      try {
+        new Function(msg.code)();
+        return true;
+      } catch (e) {
+        console.error('[bw] exec error:', e);
+        return false;
+      }
+    }
+    return false;
+  };
+
+  /**
+   * Connect to a bwserve SSE endpoint and apply protocol messages automatically.
+   *
+   * Returns a connection object with sendAction(), on(), and close() methods.
+   *
+   * @param {string} url - SSE endpoint URL (e.g., '/__bw/events/client-1')
+   * @param {Object} [opts] - Connection options
+   * @param {string} [opts.transport='sse'] - Transport type: 'sse' (default) or 'poll'
+   * @param {number} [opts.interval=2000] - Poll interval in ms (only for 'poll' transport)
+   * @param {string} [opts.actionUrl] - POST endpoint for actions (default: derived from url)
+   * @param {boolean} [opts.reconnect=true] - Auto-reconnect on disconnect
+   * @param {boolean} [opts.allowExec=false] - Enable exec message type (arbitrary JS execution)
+   * @param {Function} [opts.onStatus] - Status callback: 'connecting'|'connected'|'disconnected'
+   * @param {Function} [opts.onMessage] - Raw message callback (before clientApply)
+   * @returns {Object} Connection object { sendAction, on, close, status }
+   * @category Server
+   */
+  bw.clientConnect = function (url, opts) {
+    opts = opts || {};
+    var transport = opts.transport || 'sse';
+    var actionUrl = opts.actionUrl || url.replace(/\/events\//, '/action/');
+    var reconnect = opts.reconnect !== false;
+    var onStatus = opts.onStatus || function () {};
+    var onMessage = opts.onMessage || null;
+    var handlers = {};
+    // Set the global allowExec flag from connection options
+    bw._allowExec = !!opts.allowExec;
+    var conn = {
+      status: 'connecting',
+      _es: null,
+      _pollTimer: null
+    };
+    function setStatus(s) {
+      conn.status = s;
+      onStatus(s);
+    }
+    function handleMessage(data) {
+      try {
+        var msg = typeof data === 'string' ? bw.clientParse(data) : data;
+        if (onMessage) onMessage(msg);
+        if (handlers.message) handlers.message(msg);
+        bw.clientApply(msg);
+      } catch (e) {
+        if (handlers.error) handlers.error(e);
+      }
+    }
+    if (transport === 'sse' && typeof EventSource !== 'undefined') {
+      setStatus('connecting');
+      var es = new EventSource(url);
+      conn._es = es;
+      es.onopen = function () {
+        setStatus('connected');
+        if (handlers.open) handlers.open();
+      };
+      es.onmessage = function (e) {
+        handleMessage(e.data);
+      };
+      es.onerror = function () {
+        if (conn.status === 'connected') {
+          setStatus('disconnected');
+        }
+        if (handlers.error) handlers.error(new Error('SSE connection error'));
+        if (!reconnect) {
+          es.close();
+        }
+        // EventSource auto-reconnects by default when reconnect=true
+      };
+    } else if (transport === 'poll') {
+      var interval = opts.interval || 2000;
+      setStatus('connected');
+      conn._pollTimer = setInterval(function () {
+        fetch(url).then(function (r) {
+          return r.json();
+        }).then(function (msgs) {
+          if (Array.isArray(msgs)) {
+            msgs.forEach(handleMessage);
+          } else if (msgs && msgs.type) {
+            handleMessage(msgs);
+          }
+        })["catch"](function (e) {
+          if (handlers.error) handlers.error(e);
+        });
+      }, interval);
+    }
+
+    /**
+     * Send an action to the server via POST.
+     * @param {string} action - Action name
+     * @param {Object} [data] - Action payload
+     */
+    conn.sendAction = function (action, data) {
+      var body = JSON.stringify({
+        type: 'action',
+        action: action,
+        data: data || {}
+      });
+      fetch(actionUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: body
+      })["catch"](function (e) {
+        if (handlers.error) handlers.error(e);
+      });
+    };
+
+    /**
+     * Register an event handler.
+     * @param {string} event - 'open'|'message'|'error'|'close'
+     * @param {Function} handler
+     */
+    conn.on = function (event, handler) {
+      handlers[event] = handler;
+      return conn;
+    };
+
+    /**
+     * Close the connection.
+     */
+    conn.close = function () {
+      if (conn._es) {
+        conn._es.close();
+        conn._es = null;
+      }
+      if (conn._pollTimer) {
+        clearInterval(conn._pollTimer);
+        conn._pollTimer = null;
+      }
+      setStatus('disconnected');
+      if (handlers.close) handlers.close();
+    };
+    return conn;
+  };
+
   // ===================================================================================
   // bw.inspect() — Debug utility
   // ===================================================================================