@d3plus/dom 3.0.15 → 3.1.0

package/umd/d3plus-dom.js

@@ -1,144 +1,37 @@
 /*
-  @d3plus/dom v3.0.15
+  @d3plus/dom v3.0.16
   JavaScript functions for manipulating and analyzing DOM elements.
   Copyright (c) 2026 D3plus - https://d3plus.org
   @license MIT
 */
-
-(function (factory) {
-  typeof define === 'function' && define.amd ? define(factory) :
-  factory();
-})((function () { 'use strict';
-
-  if (typeof window !== "undefined") {
-    (function () {
-      try {
-        if (typeof SVGElement === 'undefined' || Boolean(SVGElement.prototype.innerHTML)) {
-          return;
-        }
-      } catch (e) {
-          return;
-      }
-
-      function serializeNode (node) {
-        switch (node.nodeType) {
-          case 1:
-            return serializeElementNode(node);
-          case 3:
-            return serializeTextNode(node);
-          case 8:
-            return serializeCommentNode(node);
-        }
-      }
-
-      function serializeTextNode (node) {
-          return node.textContent.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-      }
-
-      function serializeCommentNode (node) {
-          return '<!--' + node.nodeValue + '-->'
-      }
-
-      function serializeElementNode (node) {
-          var output = '';
-
-          output += '<' + node.tagName;
-
-          if (node.hasAttributes()) {
-              [].forEach.call(node.attributes, function(attrNode) {
-                  output += ' ' + attrNode.name + '="' + attrNode.value + '"';
-              });
-          }
-
-          output += '>';
-
-          if (node.hasChildNodes()) {
-              [].forEach.call(node.childNodes, function(childNode) {
-                  output += serializeNode(childNode);
-              });
-          }
-
-          output += '</' + node.tagName + '>';
-
-          return output;
-      }
-
-      Object.defineProperty(SVGElement.prototype, 'innerHTML', {
-        get: function () {
-          var output = '';
-
-          [].forEach.call(this.childNodes, function(childNode) {
-              output += serializeNode(childNode);
-          });
-
-          return output;
-        },
-        set: function (markup) {
-          while (this.firstChild) {
-            this.removeChild(this.firstChild);
-          }
-
-          try {
-            var dXML = new DOMParser();
-            dXML.async = false;
-
-            var sXML = '<svg xmlns=\'http://www.w3.org/2000/svg\' xmlns:xlink=\'http://www.w3.org/1999/xlink\'>' + markup + '</svg>';
-            var svgDocElement = dXML.parseFromString(sXML, 'text/xml').documentElement;
-
-            [].forEach.call(svgDocElement.childNodes, function(childNode) {
-                this.appendChild(this.ownerDocument.importNode(childNode, true));
-            }.bind(this));
-          } catch (e) {
-              throw new Error('Error parsing markup string');
-          }
-        }
-      });
-
-      Object.defineProperty(SVGElement.prototype, 'innerSVG', {
-        get: function () {
-          return this.innerHTML;
-        },
-        set: function (markup) {
-          this.innerHTML = markup;
-        }
-      });
-
-    })();
-  }
-
-}));
-
 (function (global, factory) {
-  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('d3-selection'), require('d3-transition'), require('@d3plus/text')) :
-  typeof define === 'function' && define.amd ? define('@d3plus/dom', ['exports', 'd3-selection', 'd3-transition', '@d3plus/text'], factory) :
-  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.d3plus = {}, global.d3Selection, global.d3Transition, global.text));
-})(this, (function (exports, d3Selection, d3Transition, text) { 'use strict';
+  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('d3-selection'), require('d3-transition'), require('@chenglou/pretext')) :
+  typeof define === 'function' && define.amd ? define('@d3plus/dom', ['exports', 'd3-selection', 'd3-transition', '@chenglou/pretext'], factory) :
+  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.d3plus = {}, global.d3Selection, global.d3Transition, global.pretext));
+})(this, (function (exports, d3Selection, d3Transition, pretext) { 'use strict';
 
   /**
-      @function isObject
-      @desc Detects if a variable is a javascript Object.
-      @param {*} item
+      Detects if a variable is a javascript Object.
+      @param item The value to test.
   */ function isObject(item) {
       return item && typeof item === "object" && (typeof window === "undefined" || item !== window && item !== window.document && !(item instanceof Element)) && !Array.isArray(item) ? true : false;
   }
 
   /**
-      @function validObject
-      @desc Determines if the object passed is the document or window.
-      @param {Object} obj
-      @private
+      Determines if the object passed is the document or window.
+      @param obj @private
   */ function validObject(obj) {
       if (typeof window === "undefined") return true;
       else return obj !== window && obj !== document;
   }
   /**
-      @function assign
-      @desc A deeply recursive version of `Object.assign`.
-      @param {...Object} objects
-      @example <caption>this</caption>
+      A deeply recursive version of `Object.assign`.
+
+  @example <caption>this</caption>
   assign({id: "foo", deep: {group: "A"}}, {id: "bar", deep: {value: 20}}));
       @example <caption>returns this</caption>
   {id: "bar", deep: {group: "A", value: 20}}
+      @param objects The source objects to merge into the target.
   */ function assign(...objects) {
       const target = objects[0];
       for(let i = 1; i < objects.length; i++){
@@ -157,19 +50,31 @@
   }
 
   /**
-      @function attrize
-      @desc Applies each key/value in an object as an attr.
-      @param {D3selection} elem The D3 element to apply the styles to.
-      @param {Object} attrs An object of key/value attr pairs.
+      Given a DOM element, returns its background color by walking up the
+      ancestor chain until a non-transparent background is found. Falls back
+      to "rgb(255, 255, 255)" (white) if every ancestor is transparent.
+      @param elem The DOM element to check.
+  */ function backgroundColor(elem) {
+      let node = elem;
+      while(node){
+          const bg = getComputedStyle(node).backgroundColor;
+          if (bg && bg !== "transparent" && bg !== "rgba(0, 0, 0, 0)") return bg;
+          node = node.parentElement;
+      }
+      return "rgb(255, 255, 255)";
+  }
+
+  /**
+      Applies each key/value in an object as an attr.
+      @param e The d3 selection to apply attributes to.
+      @param a An object of key/value attr pairs.
   */ function attrize(e, a = {}) {
       for(const k in a)if (({}).hasOwnProperty.call(a, k)) e.attr(k, a[k]);
   }
 
   /**
-      @function date
-      @summary Parses numbers and strings to valid Javascript Date objects.
-      @description Returns a javascript Date object for a given a Number (representing either a 4-digit year or milliseconds since epoch), a String representing a Quarter (ie. "Q2 1987", mapping to the last day in that quarter), or a String that is in [valid dateString format](http://dygraphs.com/date-formats.html). Besides the 4-digit year parsing, this function is useful when needing to parse negative (BC) years, which the vanilla Date object cannot parse.
-      @param {Number|String} *date*
+      Parses numbers and strings into valid JavaScript Date objects, supporting years, quarters, months, and ISO 8601 formats.
+      @param d The date value to parse (number, string, or Date).
   */ function date(d) {
       // returns if falsey or already Date object
       if ([
@@ -208,8 +113,8 @@
           return date;
       }
       // tests for monthly formats (ie. "MM-YYYY" and "YYYY-MM")
-      const monthPrefix = new RegExp(/^([-*\d]{1,2})\-(-*\d{1,4})$/g).exec(s);
-      const monthSuffix = new RegExp(/^(-*\d{1,4})\-([-*\d]{1,2})$/g).exec(s);
+      const monthPrefix = new RegExp(/^([-*\d]{1,2})-(-*\d{1,4})$/g).exec(s);
+      const monthSuffix = new RegExp(/^(-*\d{1,4})-([-*\d]{1,2})$/g).exec(s);
       if (monthPrefix || monthSuffix) {
           const month = +(monthPrefix ? monthPrefix[1] : monthSuffix[2]);
           const year = +(monthPrefix ? monthPrefix[2] : monthSuffix[1]);
@@ -230,19 +135,12 @@
   }
 
   /**
-      @function elem
-      @desc Manages the enter/update/exit pattern for a single DOM element.
-      @param {String} selector A D3 selector, which must include the tagname and a class and/or ID.
-      @param {Object} params Additional parameters.
-      @param {Boolean} [params.condition = true] Whether or not the element should be rendered (or removed).
-      @param {Object} [params.enter = {}] A collection of key/value pairs that map to attributes to be given on enter.
-      @param {Object} [params.exit = {}] A collection of key/value pairs that map to attributes to be given on exit.
-      @param {D3Selection} [params.parent = d3.select("body")] The parent element for this new element to be appended to.
-      @param {Number} [params.duration = 0] The duration for the d3 transition.
-      @param {Object} [params.update = {}] A collection of key/value pairs that map to attributes to be given on update.
+      Manages the enter/update/exit pattern for a single DOM element, applying enter, update, and exit attributes with optional transitions.
+      @param selector A CSS selector string for the element tag and classes.
+      @param p Configuration object with enter, exit, update, and parent options.
   */ function elem(selector, p) {
       // overrides default params
-      p = Object.assign({}, {
+      const params = Object.assign({}, {
           condition: true,
           enter: {},
           exit: {},
@@ -250,18 +148,18 @@
           parent: d3Selection.select("body"),
           update: {}
       }, p);
-      const className = /\.([^#]+)/g.exec(selector), id = /#([^.]+)/g.exec(selector), t = d3Transition.transition().duration(p.duration), tag = /^([^.^#]+)/g.exec(selector)[1];
-      const elem = p.parent.selectAll(selector.includes(":") ? selector.split(":")[1] : selector).data(p.condition ? [
+      const className = /\.([^#]+)/g.exec(selector), id = /#([^.]+)/g.exec(selector), t = d3Transition.transition().duration(params.duration), tag = /^([^.^#]+)/g.exec(selector)[1];
+      const elem = params.parent.selectAll(selector.includes(":") ? selector.split(":")[1] : selector).data(params.condition ? [
           null
       ] : []);
-      const enter = elem.enter().append(tag).call(attrize, p.enter);
+      const enter = elem.enter().append(tag).call(attrize, params.enter);
       if (id) enter.attr("id", id[1]);
       if (className) enter.attr("class", className[1]);
-      if (p.duration) elem.exit().transition(t).call(attrize, p.exit).remove();
-      else elem.exit().call(attrize, p.exit).remove();
+      if (params.duration) elem.exit().transition(t).call(attrize, params.exit).remove();
+      else elem.exit().call(attrize, params.exit).remove();
       const update = enter.merge(elem);
-      if (p.duration) update.transition(t).call(attrize, p.update);
-      else update.call(attrize, p.update);
+      if (params.duration) update.transition(t).call(attrize, params.update);
+      else update.call(attrize, params.update);
       return update;
   }
 
@@ -274,36 +172,37 @@
       return doc.documentElement ? doc.documentElement.textContent : input;
   }
   /**
-      @function textWidth
-      @desc Given a text string, returns the predicted pixel width of the string when placed into DOM.
-      @param {String|Array} text Can be either a single string or an array of strings to analyze.
-      @param {Object} [style] An object of CSS font styles to apply. Accepts any of the valid [CSS font property](http://www.w3schools.com/cssref/pr_font_font.asp) values.
-  */ function textWidth(text, style) {
-      style = Object.assign({
-          "font-size": 10,
-          "font-family": "sans-serif",
-          "font-style": "normal",
-          "font-weight": 400,
-          "font-variant": "normal"
-      }, style);
-      const context = document.createElement("canvas").getContext("2d");
-      const font = [];
-      font.push(style["font-style"]);
-      font.push(style["font-variant"]);
-      font.push(style["font-weight"]);
-      font.push(typeof style["font-size"] === "string" ? style["font-size"] : `${style["font-size"]}px`);
-      font.push(style["font-family"]);
-      context.font = font.join(" ");
-      if (text instanceof Array) return text.map((t)=>context.measureText(htmlDecode(t)).width);
-      return context.measureText(htmlDecode(text)).width;
+   * Builds a CSS font shorthand string from a style object.
+   * @param {Object} styleObj
+   */ function buildFont(styleObj) {
+      const style = styleObj["font-style"] || "normal";
+      const variant = styleObj["font-variant"] || "normal";
+      const weight = styleObj["font-weight"] || 400;
+      const size = typeof styleObj["font-size"] === "string" ? styleObj["font-size"] : `${styleObj["font-size"] || 10}px`;
+      const family = styleObj["font-family"] || "sans-serif";
+      return `${style} ${variant} ${weight} ${size} ${family}`;
+  }
+  /**
+   * Measures the width of a single text string using pretext.
+   * @param {String} text
+   * @param {String} font CSS font shorthand
+   */ function measureWidth(text, font) {
+      if (!text) return 0;
+      const prepared = pretext.prepareWithSegments(text, font);
+      const result = pretext.layoutWithLines(prepared, Infinity, 20);
+      return result.lines.length ? result.lines[0].width : 0;
+  }
+  function textWidth(text, style = {}) {
+      const font = buildFont(style);
+      if (text instanceof Array) return text.map((t)=>measureWidth(htmlDecode(t), font));
+      return measureWidth(htmlDecode(text), font);
   }
 
   const alpha = "abcdefghiABCDEFGHI_!@#$%^&*()_+1234567890", checked = {}, height = 32;
   let dejavu, macos, monospace, proportional;
   /**
-      @function fontExists
-      @desc Given either a single font-family or a list of fonts, returns the name of the first font that can be rendered, or `false` if none are installed on the user's machine.
-      @param {String|Array} font Can be either a valid CSS font-family string (single or comma-separated names) or an Array of string names.
+      Given either a single font-family or a list of fonts, returns the name of the first font that can be rendered, or `false` if none are installed on the user's machine.
+      @param font Can be either a valid CSS font-family string (single or comma-separated names) or an Array of string names.
   */ const fontExists = (font)=>{
       if (!dejavu) {
           dejavu = textWidth(alpha, {
@@ -324,7 +223,7 @@
           });
       }
       if (!(font instanceof Array)) font = font.split(",");
-      font = font.map((f)=>text.trim(f));
+      font = font.map((f)=>f.trim());
       for(let i = 0; i < font.length; i++){
           const fam = font[i];
           if (checked[fam] || [
@@ -348,7 +247,7 @@
   };
 
   /**
-    @desc Given an HTMLElement and a "width" or "height" string, this function returns the current calculated size for the DOM element.
+    Given an HTMLElement and a "width" or "height" string, this function returns the current calculated size for the DOM element.
     @private
   */ function _elementSize(element, s) {
       if (!element) return undefined;
@@ -359,32 +258,37 @@
           let val = window[`inner${s.charAt(0).toUpperCase() + s.slice(1)}`];
           const elem = d3Selection.select(element);
           if (s === "width") {
-              val -= parseFloat(elem.style("margin-left"), 10);
-              val -= parseFloat(elem.style("margin-right"), 10);
-              val -= parseFloat(elem.style("padding-left"), 10);
-              val -= parseFloat(elem.style("padding-right"), 10);
+              val -= parseFloat(elem.style("margin-left"));
+              val -= parseFloat(elem.style("margin-right"));
+              val -= parseFloat(elem.style("padding-left"));
+              val -= parseFloat(elem.style("padding-right"));
           } else {
-              val -= parseFloat(elem.style("margin-top"), 10);
-              val -= parseFloat(elem.style("margin-bottom"), 10);
-              val -= parseFloat(elem.style("padding-top"), 10);
-              val -= parseFloat(elem.style("padding-bottom"), 10);
+              val -= parseFloat(elem.style("margin-top"));
+              val -= parseFloat(elem.style("margin-bottom"));
+              val -= parseFloat(elem.style("padding-top"));
+              val -= parseFloat(elem.style("padding-bottom"));
           }
           return val;
       } else {
-          let val = parseFloat(d3Selection.select(element).style(s), 10);
+          let val = element.getBoundingClientRect()[s];
           if (typeof val === "number" && val > 0) {
               if (s === "height") {
-                  val -= parseFloat(d3Selection.select(element).style("padding-top"), 10);
-                  val -= parseFloat(d3Selection.select(element).style("padding-bottom"), 10);
+                  val -= parseFloat(d3Selection.select(element).style("padding-top"));
+                  val -= parseFloat(d3Selection.select(element).style("padding-bottom"));
+                  val -= parseFloat(d3Selection.select(element).style("border-top"));
+                  val -= parseFloat(d3Selection.select(element).style("border-bottom"));
+              } else {
+                  val -= parseFloat(d3Selection.select(element).style("padding-left"));
+                  val -= parseFloat(d3Selection.select(element).style("padding-right"));
+                  val -= parseFloat(d3Selection.select(element).style("border-left"));
+                  val -= parseFloat(d3Selection.select(element).style("border-right"));
               }
               return val;
           } else return _elementSize(element.parentNode, s);
       }
   }
   /**
-      @function getSize
-      @desc Finds the available width and height for a specified HTMLElement, traversing it's parents until it finds something with constrained dimensions. Falls back to the inner dimensions of the browser window if none is found.
-      @param {HTMLElement} elem The HTMLElement to find dimensions for.
+      Finds the available width and height for a specified HTMLElement, traversing it's parents until it finds something with constrained dimensions. Falls back to the inner dimensions of the browser window if none is found.
       @private
   */ function getSize(elem) {
       return [
@@ -394,27 +298,24 @@
   }
 
   /**
-    @module inViewport
-    @desc Returns a *Boolean* denoting whether or not a given DOM element is visible in the current window.
-    @param {DOMElement} elem The DOM element to analyze.
-    @param {Number} [buffer = 0] A pixel offset from the edge of the top and bottom of the screen. If a positive value, the element will be deemed visible when it is that many pixels away from entering the viewport. If negative, the element will have to enter the viewport by that many pixels before being deemed visible.
-    @private
+      Determines whether a given DOM element is visible within the current viewport, with an optional pixel buffer.
+      @param elem The DOM element to check.
+      @param buffer Extra pixel margin around the viewport boundary.
   */ function inViewport(elem, buffer = 0) {
-      const pageX = window.pageXOffset !== undefined ? window.pageXOffset : (document.documentElement || document.body.parentNode || document.body).scrollLeft;
-      const pageY = window.pageYOffset !== undefined ? window.pageYOffset : (document.documentElement || document.body.parentNode || document.body).scrollTop;
+      const pageX = window.scrollX;
+      const pageY = window.scrollY;
       const bounds = elem.getBoundingClientRect();
       const height = bounds.height, left = bounds.left + pageX, top = bounds.top + pageY, width = bounds.width;
       return pageY + window.innerHeight > top + buffer && pageY + buffer < top + height && pageX + window.innerWidth > left + buffer && pageX + buffer < left + width;
   }
 
   /**
-   @function parseSides
-   @desc Converts a string of directional CSS shorthand values into an object with the values expanded.
-   @param {String|Number} sides The CSS shorthand string to expand.
+   Converts a string of directional CSS shorthand values into an object with the values expanded.
+   @param sides The CSS shorthand string to expand.
    */ function parseSides(sides) {
       let values;
       if (typeof sides === "number") values = [
-          sides
+          `${sides}`
       ];
       else values = sides.split(/\s+/);
       if (values.length === 1) values = [
@@ -438,32 +339,22 @@
   }
 
   /**
-      @function prefix
-      @desc Returns the appropriate CSS vendor prefix, given the current browser.
-  */ function prefix() {
-      if ("-webkit-transform" in document.body.style) return "-webkit-";
-      else if ("-moz-transform" in document.body.style) return "-moz-";
-      else if ("-ms-transform" in document.body.style) return "-ms-";
-      else if ("-o-transform" in document.body.style) return "-o-";
-      else return "";
+      Returns `true` if the HTML or body element has either the "dir" HTML attribute or the "direction" CSS property set to "rtl".
+  */ function rtl() {
+      return document.documentElement.dir === "rtl" || document.body.dir === "rtl" || getComputedStyle(document.documentElement).direction === "rtl" || getComputedStyle(document.body).direction === "rtl";
   }
 
   /**
-      @function rtl
-      @desc Returns `true` if the HTML or body element has either the "dir" HTML attribute or the "direction" CSS property set to "rtl".
-  */ var rtl = (()=>d3Selection.select("html").attr("dir") === "rtl" || d3Selection.select("body").attr("dir") === "rtl" || d3Selection.select("html").style("direction") === "rtl" || d3Selection.select("body").style("direction") === "rtl");
-
-  /**
-      @function stylize
-      @desc Applies each key/value in an object as a style.
-      @param {D3selection} elem The D3 element to apply the styles to.
-      @param {Object} styles An object of key/value style pairs.
+      Applies each key/value in an object as a style.
+      @param e The d3 selection to apply styles to.
+      @param s An object of key/value style pairs.
   */ function stylize(e, s = {}) {
       for(const k in s)if (({}).hasOwnProperty.call(s, k)) e.style(k, s[k]);
   }
 
   exports.assign = assign;
   exports.attrize = attrize;
+  exports.backgroundColor = backgroundColor;
   exports.date = date;
   exports.elem = elem;
   exports.fontExists = fontExists;
@@ -471,7 +362,6 @@
   exports.inViewport = inViewport;
   exports.isObject = isObject;
   exports.parseSides = parseSides;
-  exports.prefix = prefix;
   exports.rtl = rtl;
   exports.stylize = stylize;
   exports.textWidth = textWidth;