@d3plus/dom 3.0.16 → 3.1.0

package/es/src/getSize.js

@@ -1,6 +1,6 @@
 import { select } from "d3-selection";
 /**
-  @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;
@@ -11,32 +11,37 @@ import { select } from "d3-selection";
         var val = window["inner".concat(s.charAt(0).toUpperCase() + s.slice(1))];
         var elem = 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 {
-        var val1 = parseFloat(select(element).style(s), 10);
+        var val1 = element.getBoundingClientRect()[s];
         if (typeof val1 === "number" && val1 > 0) {
             if (s === "height") {
-                val1 -= parseFloat(select(element).style("padding-top"), 10);
-                val1 -= parseFloat(select(element).style("padding-bottom"), 10);
+                val1 -= parseFloat(select(element).style("padding-top"));
+                val1 -= parseFloat(select(element).style("padding-bottom"));
+                val1 -= parseFloat(select(element).style("border-top"));
+                val1 -= parseFloat(select(element).style("border-bottom"));
+            } else {
+                val1 -= parseFloat(select(element).style("padding-left"));
+                val1 -= parseFloat(select(element).style("padding-right"));
+                val1 -= parseFloat(select(element).style("border-left"));
+                val1 -= parseFloat(select(element).style("border-right"));
             }
             return val1;
         } 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
 */ export default function(elem) {
     return [

package/es/src/inViewport.js

@@ -1,13 +1,11 @@
 /**
-  @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.
 */ export default function(elem) {
     var buffer = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : 0;
-    var pageX = window.pageXOffset !== undefined ? window.pageXOffset : (document.documentElement || document.body.parentNode || document.body).scrollLeft;
-    var pageY = window.pageYOffset !== undefined ? window.pageYOffset : (document.documentElement || document.body.parentNode || document.body).scrollTop;
+    var pageX = window.scrollX;
+    var pageY = window.scrollY;
     var bounds = elem.getBoundingClientRect();
     var 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;

package/es/src/isObject.js

@@ -1,8 +1,5 @@
-/**
-    @function isObject
-    @desc Detects if a variable is a javascript Object.
-    @param {*} item
-*/ function _instanceof(left, right) {
+function _instanceof(left, right) {
+    "@swc/helpers - instanceof";
     if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
         return !!right[Symbol.hasInstance](left);
     } else {
@@ -13,6 +10,9 @@ function _type_of(obj) {
     "@swc/helpers - typeof";
     return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
 }
-export default function(item) {
+/**
+    Detects if a variable is a javascript Object.
+    @param item The value to test.
+*/ export default function(item) {
     return item && (typeof item === "undefined" ? "undefined" : _type_of(item)) === "object" && (typeof window === "undefined" || item !== window && item !== window.document && !_instanceof(item, Element)) && !Array.isArray(item) ? true : false;
 }

package/es/src/parseSides.js

@@ -1,11 +1,10 @@
 /**
- @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.
  */ export default function(sides) {
     var values;
     if (typeof sides === "number") values = [
-        sides
+        "".concat(sides)
     ];
     else values = sides.split(/\s+/);
     if (values.length === 1) values = [

package/es/src/rtl.js

@@ -1,7 +1,5 @@
-import { select } from "d3-selection";
 /**
-    @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".
+    Returns `true` if the HTML or body element has either the "dir" HTML attribute or the "direction" CSS property set to "rtl".
 */ export default function() {
-    return select("html").attr("dir") === "rtl" || select("body").attr("dir") === "rtl" || select("html").style("direction") === "rtl" || select("body").style("direction") === "rtl";
-};
+    return document.documentElement.dir === "rtl" || document.body.dir === "rtl" || getComputedStyle(document.documentElement).direction === "rtl" || getComputedStyle(document.body).direction === "rtl";
+}

package/es/src/stylize.js

@@ -1,8 +1,7 @@
 /**
-    @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.
 */ export default function(e) {
     var s = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
     for(var k in s)if (({}).hasOwnProperty.call(s, k)) e.style(k, s[k]);

package/es/src/textWidth.js

@@ -1,41 +1,46 @@
-/**
- * Strips HTML and "un-escapes" escape characters.
- * @param {String} input
- */ function _instanceof(left, right) {
+function _instanceof(left, right) {
+    "@swc/helpers - instanceof";
     if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
         return !!right[Symbol.hasInstance](left);
     } else {
         return left instanceof right;
     }
 }
-function htmlDecode(input) {
+import { prepareWithSegments, layoutWithLines } from "@chenglou/pretext";
+/**
+ * Strips HTML and "un-escapes" escape characters.
+ * @param {String} input
+ */ function htmlDecode(input) {
     if (input.replace(/\s+/g, "") === "") return input;
     var doc = new DOMParser().parseFromString(input.replace(/<[^>]+>/g, ""), "text/html");
     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.
-*/ export default function(text, style) {
-    style = Object.assign({
-        "font-size": 10,
-        "font-family": "sans-serif",
-        "font-style": "normal",
-        "font-weight": 400,
-        "font-variant": "normal"
-    }, style);
-    var context = document.createElement("canvas").getContext("2d");
-    var 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"] : "".concat(style["font-size"], "px"));
-    font.push(style["font-family"]);
-    context.font = font.join(" ");
+ * Builds a CSS font shorthand string from a style object.
+ * @param {Object} styleObj
+ */ function buildFont(styleObj) {
+    var style = styleObj["font-style"] || "normal";
+    var variant = styleObj["font-variant"] || "normal";
+    var weight = styleObj["font-weight"] || 400;
+    var size = typeof styleObj["font-size"] === "string" ? styleObj["font-size"] : "".concat(styleObj["font-size"] || 10, "px");
+    var family = styleObj["font-family"] || "sans-serif";
+    return "".concat(style, " ").concat(variant, " ").concat(weight, " ").concat(size, " ").concat(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;
+    var prepared = prepareWithSegments(text, font);
+    var result = layoutWithLines(prepared, Infinity, 20);
+    return result.lines.length ? result.lines[0].width : 0;
+}
+export default function(text) {
+    var style = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
+    var font = buildFont(style);
     if (_instanceof(text, Array)) return text.map(function(t) {
-        return context.measureText(htmlDecode(t)).width;
+        return measureWidth(htmlDecode(t), font);
     });
-    return context.measureText(htmlDecode(text)).width;
+    return measureWidth(htmlDecode(text), font);
 }

package/package.json

@@ -1,18 +1,25 @@
 {
   "name": "@d3plus/dom",
-  "version": "3.0.16",
+  "version": "3.1.0",
   "description": "JavaScript functions for manipulating and analyzing DOM elements.",
   "license": "MIT",
   "type": "module",
-  "exports": "./es/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./es/index.js"
+    }
+  },
   "browser": "./umd/d3plus-dom.full.js",
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "sideEffects": false,
   "files": [
     "umd",
-    "es"
+    "es",
+    "types"
   ],
   "homepage": "https://d3plus.org",
   "repository": {
@@ -27,14 +34,16 @@
     "data",
     "visualization"
   ],
+  "dependencies": {
+    "@chenglou/pretext": "^0.0.3",
+    "d3-selection": "^3.0.0",
+    "d3-transition": "^3.0.1"
+  },
   "scripts": {
     "build:esm": "node ../../scripts/build-esm.js",
+    "build:types": "tsc",
     "build:umd": "node ../../scripts/build-umd.js",
     "dev": "node ../../scripts/dev.js",
-    "test": "eslint index.js src/**/*.js && eslint --global=it test && mocha 'test/**/*-test.js'"
-  },
-  "dependencies": {
-    "d3-selection": "^3.0.0",
-    "d3-transition": "^3.0.1"
+    "test": "eslint index.ts src/**/*.ts && eslint --global=it test && mocha 'test/**/*-test.js'"
   }
 }

package/types/index.d.ts

@@ -0,0 +1,14 @@
+export type { D3Selection } from "./src/D3Selection.js";
+export { default as assign } from "./src/assign.js";
+export { default as backgroundColor } from "./src/backgroundColor.js";
+export { default as attrize } from "./src/attrize.js";
+export { default as date } from "./src/date.js";
+export { default as elem } from "./src/elem.js";
+export { default as fontExists } from "./src/fontExists.js";
+export { default as getSize } from "./src/getSize.js";
+export { default as inViewport } from "./src/inViewport.js";
+export { default as isObject } from "./src/isObject.js";
+export { default as parseSides } from "./src/parseSides.js";
+export { default as rtl } from "./src/rtl.js";
+export { default as stylize } from "./src/stylize.js";
+export { default as textWidth } from "./src/textWidth.js";

package/types/src/D3Selection.d.ts

@@ -0,0 +1,28 @@
+import { select } from "d3-selection";
+import { transition } from "d3-transition";
+/**
+    @type D3Selection
+    A permissive D3 selection type that accepts any generic parameterisation.
+    Uses `any` for the parent/datum generics because d3plus utility functions
+    (attrize, stylize, elem) must work with every combination.
+*/
+export type D3Selection = ReturnType<typeof select<any, any>>;
+/**
+    @type D3Transition
+    A D3 transition type derived from the return type of d3-transition's transition function.
+*/
+export type D3Transition = ReturnType<typeof transition>;
+/**
+    @interface Attrable
+    Anything that supports `.attr(name, value)` — both Selection and Transition.
+*/
+export interface Attrable {
+    attr(name: string, value: string | number | boolean | null): this;
+}
+/**
+    @interface Stylable
+    Anything that supports `.style(name, value)` — both Selection and Transition.
+*/
+export interface Stylable {
+    style(name: string, value: string | number | boolean | null): this;
+}

package/types/src/assign.d.ts

@@ -0,0 +1,11 @@
+/**
+    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.
+*/
+declare function assign(...objects: Record<string, unknown>[]): Record<string, unknown>;
+export default assign;

package/types/src/attrize.d.ts

@@ -0,0 +1,7 @@
+import type { Attrable } from "./D3Selection.js";
+/**
+    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.
+*/
+export default function (e: Attrable, a?: Record<string, string | number | boolean | null>): void;

package/types/src/backgroundColor.d.ts

@@ -0,0 +1,7 @@
+/**
+    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.
+*/
+export default function (elem: Element): string;

package/types/src/date.d.ts

@@ -0,0 +1,5 @@
+/**
+    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).
+*/
+export default function (d: number | string | false | undefined): Date | false | undefined;

package/types/src/elem.d.ts

@@ -0,0 +1,18 @@
+import type { D3Selection } from "./D3Selection.js";
+type AttrMap = Record<string, string | number | boolean | null>;
+export interface ElemParams {
+    condition?: boolean;
+    enter?: AttrMap;
+    exit?: AttrMap;
+    duration?: number;
+    parent?: D3Selection;
+    transition?: D3Selection;
+    update?: AttrMap;
+}
+/**
+    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.
+*/
+export default function (selector: string, p?: ElemParams): D3Selection;
+export {};

package/types/src/fontExists.d.ts

@@ -0,0 +1,6 @@
+/**
+    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.
+*/
+declare const fontExists: (font: string | string[]) => string | false;
+export default fontExists;

package/types/src/getSize.d.ts

@@ -0,0 +1,5 @@
+/**
+    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
+*/
+export default function (elem: HTMLElement): [number | undefined, number | undefined];

package/types/src/inViewport.d.ts

@@ -0,0 +1,6 @@
+/**
+    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.
+*/
+export default function (elem: Element, buffer?: number): boolean;

package/types/src/isObject.d.ts

@@ -0,0 +1,5 @@
+/**
+    Detects if a variable is a javascript Object.
+    @param item The value to test.
+*/
+export default function (item: unknown): boolean;

package/types/src/parseSides.d.ts

@@ -0,0 +1,11 @@
+export interface ParsedSides {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ Converts a string of directional CSS shorthand values into an object with the values expanded.
+ @param sides The CSS shorthand string to expand.
+ */
+export default function (sides: string | number): ParsedSides;

package/types/src/prefix.d.ts

@@ -0,0 +1,5 @@
+/**
+    @function prefix
+    @desc Returns the appropriate CSS vendor prefix, given the current browser.
+*/
+export default function (): string;

package/types/src/rtl.d.ts

@@ -0,0 +1,4 @@
+/**
+    Returns `true` if the HTML or body element has either the "dir" HTML attribute or the "direction" CSS property set to "rtl".
+*/
+export default function (): boolean;

package/types/src/stylize.d.ts

@@ -0,0 +1,7 @@
+import type { Stylable } from "./D3Selection.js";
+/**
+    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.
+*/
+export default function (e: Stylable, s?: Record<string, string | number | boolean | null>): void;

package/types/src/textWidth.d.ts

@@ -0,0 +1,7 @@
+/**
+    Given a text string, returns the predicted pixel width of the string when placed into DOM.
+    @param text The text string to measure.
+    @param style CSS style properties to apply when measuring.
+*/
+export default function (text: string, style?: Record<string, string | number>): number;
+export default function (text: string[], style?: Record<string, string | number>): number[];