bitwrench 2.0.15 → 2.0.16

package/dist/bitwrench.cjs.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 */
 'use strict';
 
 /**
@@ -7,14 +7,14 @@
  */
 
 const 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'
 };
 
 /**
@@ -432,12 +432,11 @@ function derivePalette(config) {
   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),
@@ -1570,7 +1569,7 @@ var structuralRules = {
     '@media (min-width: 992px)': { '.bw_container': { 'max-width': '960px' } },
     '@media (min-width: 1200px)': { '.bw_container': { 'max-width': '1140px' } },
     '.bw_container_fluid': {
-      'width': '100%', 'padding-right': '15px', 'padding-left': '15px',
+      'width': '100%', 'padding-right': '0.75rem', 'padding-left': '0.75rem',
       'margin-right': 'auto', 'margin-left': 'auto'
     },
     '.bw_row': {
@@ -1731,7 +1730,8 @@ var structuralRules = {
     '.bw_badge': {
       'display': 'inline-block', 'font-size': '0.875rem',
       'font-weight': '600', 'line-height': '1.3', 'text-align': 'center',
-      'white-space': 'nowrap', 'vertical-align': 'baseline'
+      'white-space': 'nowrap', 'vertical-align': 'baseline',
+      'padding': '0.35rem 0.65rem', 'border-radius': '0.25rem'
     },
     '.bw_badge:empty': { 'display': 'none' },
     '.bw_badge_sm': { 'font-size': '0.75rem', 'padding': '0.25rem 0.5rem' },
@@ -1916,7 +1916,7 @@ var structuralRules = {
   // ---- Code demo ----
   codeDemo: {
     '.bw_code_demo': { 'margin-bottom': '2rem' },
-    '.bw_code_pre': { 'margin': '0', 'border': 'none', 'overflow-x': 'auto' },
+    '.bw_code_pre': { 'margin': '0', 'border': 'none', 'overflow-x': 'auto', 'max-width': '100%' },
     '.bw_code_block': {
       'display': 'block', 'padding': '1.25rem',
       'font-family': '"SF Mono", Monaco, "Cascadia Code", "Roboto Mono", Consolas, "Courier New", monospace',
@@ -2013,7 +2013,7 @@ var structuralRules = {
     },
     '.bw_modal.bw_modal_show': { 'opacity': '1', 'visibility': 'visible', 'pointer-events': 'auto' },
     '.bw_modal_dialog': {
-      'position': 'relative', 'width': '100%', 'max-width': '500px', 'margin': '1.75rem auto',
+      'position': 'relative', 'width': 'calc(100% - 1rem)', 'max-width': '500px', 'margin': '1.75rem auto',
       'pointer-events': 'none'
     },
     '.bw_modal.bw_modal_show .bw_modal_dialog': { 'transform': 'translateY(0)' },
@@ -2043,7 +2043,7 @@ var structuralRules = {
     '.bw_toast_container.bw_toast_top_center': { 'top': '0', 'left': '50%', 'transform': 'translateX(-50%)' },
     '.bw_toast_container.bw_toast_bottom_center': { 'bottom': '0', 'left': '50%', 'transform': 'translateX(-50%)' },
     '.bw_toast': {
-      'pointer-events': 'auto', 'width': '350px', 'max-width': '100%', 'background-clip': 'padding-box',
+      'pointer-events': 'auto', 'width': '350px', 'max-width': 'calc(100vw - 2rem)', 'background-clip': 'padding-box',
       'opacity': '0'
     },
     '.bw_toast.bw_toast_show': { 'opacity': '1', 'transform': 'translateY(0)' },
@@ -2129,7 +2129,7 @@ var structuralRules = {
     '.bw_tooltip_wrapper': { 'position': 'relative', 'display': 'inline-block' },
     '.bw_tooltip': {
       'position': 'absolute', 'z-index': '999',
-      'font-size': '0.875rem', 'white-space': 'nowrap', 'pointer-events': 'none',
+      'font-size': '0.875rem', 'white-space': 'nowrap', 'max-width': 'min(300px, calc(100vw - 1rem))', 'pointer-events': 'none',
       'opacity': '0', 'visibility': 'hidden'
     },
     '.bw_tooltip.bw_tooltip_show': { 'opacity': '1', 'visibility': 'visible' },
@@ -2149,7 +2149,7 @@ var structuralRules = {
     '.bw_popover_trigger': { 'cursor': 'pointer' },
     '.bw_popover': {
       'position': 'absolute', 'z-index': '1000',
-      'min-width': '200px', 'max-width': '320px',
+      'min-width': '200px', 'max-width': 'min(320px, calc(100vw - 2rem))',
       'pointer-events': 'none', 'opacity': '0', 'visibility': 'hidden'
     },
     '.bw_popover.bw_popover_show': { 'opacity': '1', 'visibility': 'visible', 'pointer-events': 'auto' },
@@ -2332,7 +2332,18 @@ var structuralRules = {
       '.bw_hero, .bw_hero': { 'padding': '2rem 1rem' },
       '.bw_cta_actions, .bw_cta-actions': { 'flex-direction': 'column' },
       '.bw_hstack, .bw_hstack': { 'flex-direction': 'column' },
-      '.bw_feature_grid, .bw_feature-grid': { 'grid-template-columns': '1fr' }
+      '.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' }
     }
   }
 };
@@ -9485,6 +9496,391 @@ bw.message = function(target, action, data) {
   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(selector) {
+    var el = bw._el(selector);
+    if (el) el.scrollTop = el.scrollHeight;
+  },
+  focus: function(selector) {
+    var el = bw._el(selector);
+    if (el && typeof el.focus === 'function') el.focus();
+  },
+  download: function(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(text) {
+    if (typeof navigator !== 'undefined' && navigator.clipboard) {
+      navigator.clipboard.writeText(text);
+    }
+  },
+  redirect: function(url) {
+    if (typeof window !== 'undefined') window.location.href = url;
+  },
+  log: function() {
+    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
 // ===================================================================================