@d3plus/format 3.0.0-alpha.0

package/README.md

@@ -0,0 +1,83 @@
+# @d3plus/format
+  
+JavaScript formatters for localized numbers and dates.
+
+## Installing
+
+If using npm, `npm install @d3plus/format`. Otherwise, you can download the [latest release from GitHub](https://github.com/d3plus/d3plus/releases/latest) or load from a [CDN](https://cdn.jsdelivr.net/npm/@d3plus/format@3.0.0-alpha.0/+esm).
+
+```js
+import modules from "@d3plus/format";
+```
+
+In vanilla JavaScript, a `d3plus` global is exported from the pre-bundled version:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@d3plus/format@3.0.0-alpha.0"></script>
+<script>
+  console.log(d3plus);
+</script>
+```
+
+## Examples
+
+Live examples can be found on [d3plus.org](https://d3plus.org/), which includes a collection of example visualizations using @d3plus/react.
+
+## API Reference
+
+##### 
+* [format](#format) - An extension to d3's [format](https://github.com/d3/d3-format#api-reference) function that adds more string formatting types and localizations.
+
+The new specifier strings added by d3plus-format are:
+ - `.3~a` - abbreviated decimal notation with a numeric suffix (ie. "k", "M", "B", etc). This is an alias of the `formatAbbreviate` function.
+* [formatAbbreviate](#formatAbbreviate) - Formats a number to an appropriate number of decimal places and rounding, adding suffixes if applicable (ie. `1200000` to `"1.2M"`).
+* [formatDate](#formatDate) - A default set of date formatters, which takes into account both the interval in between in each data point but also the start/end data points.
+* [formatDefaultLocale](#formatDefaultLocale) - An extension to d3's [formatDefaultLocale](https://github.com/d3/d3-format#api-reference) function that allows setting the locale globally for formatters.
+
+---
+
+<a name="format"></a>
+#### d3plus.**format**(specifier) [<>](https://github.com/d3plus/d3plus/blob/main/packages/format/src/format.js#L4)
+
+An extension to d3's [format](https://github.com/d3/d3-format#api-reference) function that adds more string formatting types and localizations.
+
+The new specifier strings added by d3plus-format are:
+ - `.3~a` - abbreviated decimal notation with a numeric suffix (ie. "k", "M", "B", etc). This is an alias of the `formatAbbreviate` function.
+
+
+This is a global function
+
+---
+
+<a name="formatAbbreviate"></a>
+#### d3plus.**formatAbbreviate**(n, locale) [<>](https://github.com/d3plus/d3plus/blob/main/packages/format/src/formatAbbreviate.js#L38)
+
+Formats a number to an appropriate number of decimal places and rounding, adding suffixes if applicable (ie. `1200000` to `"1.2M"`).
+
+
+This is a global function
+
+---
+
+<a name="formatDate"></a>
+#### d3plus.**formatDate**(d, dataArray, [formatter]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/format/src/formatDate.js#L4)
+
+A default set of date formatters, which takes into account both the interval in between in each data point but also the start/end data points.
+
+
+This is a global function
+
+---
+
+<a name="formatDefaultLocale"></a>
+#### d3plus.**formatDefaultLocale**(definition) [<>](https://github.com/d3plus/d3plus/blob/main/packages/format/src/formatDefaultLocale.js#L4)
+
+An extension to d3's [formatDefaultLocale](https://github.com/d3/d3-format#api-reference) function that allows setting the locale globally for formatters.
+
+
+This is a global function
+
+---
+
+
+###### <sub>Documentation generated on Thu, 13 Mar 2025 19:58:29 GMT</sub>

package/es/index.js

@@ -0,0 +1,4 @@
+export { default as format } from "./src/format.js";
+export { default as formatDefaultLocale } from "./src/formatDefaultLocale.js";
+export { default as formatAbbreviate } from "./src/formatAbbreviate.js";
+export { default as formatDate } from "./src/formatDate.js";

package/es/src/format.js

@@ -0,0 +1,14 @@
+import abbreviate from "./formatAbbreviate.js";
+import { format } from "d3-format";
+/**
+    @function format
+    @desc An extension to d3's [format](https://github.com/d3/d3-format#api-reference) function that adds more string formatting types and localizations.
+
+The new specifier strings added by d3plus-format are:
+ - `.3~a` - abbreviated decimal notation with a numeric suffix (ie. "k", "M", "B", etc). This is an alias of the `formatAbbreviate` function.
+    @param {String} specifier The string specifier used by the format function.
+    @returns {Function}
+*/ export default function(specifier) {
+    if (specifier === ".3~a") return abbreviate;
+    return format(specifier);
+};

package/es/src/formatAbbreviate.js

@@ -0,0 +1,77 @@
+function _type_of(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+import { formatLocale } from "d3-format";
+import { formatLocale as defaultLocale } from "@d3plus/locales";
+var round = function(x, n) {
+    return parseFloat(Math.round(x * Math.pow(10, n)) / Math.pow(10, n)).toFixed(n);
+};
+/**
+ * @private
+*/ function formatSuffix(str, precision, suffixes) {
+    var i = 0;
+    var value = parseFloat(str.replace("−", "-"), 10);
+    if (value) {
+        if (value < 0) value *= -1;
+        i = 1 + Math.floor(1e-12 + Math.log(value) / Math.LN10);
+        i = Math.max(-24, Math.min(24, Math.floor((i - 1) / 3) * 3));
+    }
+    var d = suffixes[8 + i / 3];
+    return {
+        number: round(d.scale(value), precision),
+        symbol: d.symbol
+    };
+}
+/**
+ * @private
+*/ function parseSuffixes(d, i) {
+    var k = Math.pow(10, Math.abs(8 - i) * 3);
+    return {
+        scale: i > 8 ? function(d) {
+            return d / k;
+        } : function(d) {
+            return d * k;
+        },
+        symbol: d
+    };
+}
+/**
+    @function formatAbbreviate
+    @desc Formats a number to an appropriate number of decimal places and rounding, adding suffixes if applicable (ie. `1200000` to `"1.2M"`).
+    @param {Number|String} n The number to be formatted.
+    @param {Object|String} locale The locale config to be used. If *value* is an object, the function will format the numbers according the object. The object must include `suffixes`, `delimiter` and `currency` properties.
+    @returns {String}
+*/ export default function(n) {
+    var locale = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : "en-US", precision = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : undefined;
+    if (isFinite(n)) n *= 1;
+    else return "N/A";
+    var negative = n < 0;
+    var length = n.toString().split(".")[0].replace("-", "").length, localeConfig = (typeof locale === "undefined" ? "undefined" : _type_of(locale)) === "object" ? locale : defaultLocale[locale] || defaultLocale["en-US"], suffixes = localeConfig.suffixes.map(parseSuffixes);
+    var decimal = localeConfig.delimiters.decimal || ".", separator = localeConfig.separator || "", thousands = localeConfig.delimiters.thousands || ",";
+    var d3plusFormatLocale = formatLocale({
+        currency: localeConfig.currency || [
+            "$",
+            ""
+        ],
+        decimal: decimal,
+        grouping: localeConfig.grouping || [
+            3
+        ],
+        thousands: thousands
+    });
+    var val;
+    if (precision) val = d3plusFormatLocale.format(precision)(n);
+    else if (n === 0) val = "0";
+    else if (length >= 3) {
+        var f = formatSuffix(d3plusFormatLocale.format(".3r")(n), 2, suffixes);
+        var num = parseFloat(f.number).toString().replace(".", decimal);
+        var char = f.symbol;
+        val = "".concat(num).concat(separator).concat(char);
+    } else if (length === 3) val = d3plusFormatLocale.format(",f")(n);
+    else if (n < 1 && n > -1) val = d3plusFormatLocale.format(".2g")(n);
+    else val = d3plusFormatLocale.format(".3g")(n);
+    return "".concat(negative && val.charAt(0) !== "−" ? "−" : "").concat(val).replace(/−/g, "-") // replace new d3 default minus sign (−) to hyphen-minus (-)
+    .replace(/(\.[0]*[1-9]*)[0]*$/g, "$1") // removes any trailing zeros
+    .replace(/\.[0]*$/g, ""); // removes any trailing decimal point
+}

package/es/src/formatDate.js

@@ -0,0 +1,108 @@
+function _array_like_to_array(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_with_holes(arr) {
+    if (Array.isArray(arr)) return arr;
+}
+function _iterable_to_array_limit(arr, i) {
+    var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
+    if (_i == null) return;
+    var _arr = [];
+    var _n = true;
+    var _d = false;
+    var _s, _e;
+    try {
+        for(_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true){
+            _arr.push(_s.value);
+            if (i && _arr.length === i) break;
+        }
+    } catch (err) {
+        _d = true;
+        _e = err;
+    } finally{
+        try {
+            if (!_n && _i["return"] != null) _i["return"]();
+        } finally{
+            if (_d) throw _e;
+        }
+    }
+    return _arr;
+}
+function _non_iterable_rest() {
+    throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _sliced_to_array(arr, i) {
+    return _array_with_holes(arr) || _iterable_to_array_limit(arr, i) || _unsupported_iterable_to_array(arr, i) || _non_iterable_rest();
+}
+function _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
+import { timeYear, timeMonth, timeHour, timeMinute, timeSecond } from "d3-time";
+import { timeFormat } from "d3-time-format";
+/**
+    @function formatDate
+    @desc A default set of date formatters, which takes into account both the interval in between in each data point but also the start/end data points.
+    @param {Date} d The date string to be formatted.
+    @param {Array} dataArray The full array of ordered Date Objects.
+    @param {Function} [formatter = d3.timeFormat] An optional instance of d3.timeFormat to be used for localization.
+    @returns {String}
+*/ export default function(d, dataArray) {
+    var formatter = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : timeFormat;
+    var formatHour = formatter("%I %p"), formatMillisecond = formatter(".%L"), formatMinute = formatter("%I:%M"), formatMonth = formatter("%b"), formatMonthDay = formatter("%b %-d"), formatMonthDayYear = formatter("%b %-d, %Y"), formatMonthYear = formatter("%b %Y"), formatQuarter = formatter("Q%q"), formatQuarterYear = formatter("Q%q %Y"), formatSecond = formatter(":%S"), formatYear = formatter("%Y");
+    var labelIndex = dataArray.findIndex(function(a) {
+        return +a === +d;
+    });
+    var firstOrLast = labelIndex === 0 || labelIndex === dataArray.length - 1;
+    var smallArray = dataArray.length <= 5;
+    var _dataArray_reduce = _sliced_to_array(dataArray.reduce(function(arr, d, i) {
+        if (i) {
+            arr[0].push(d.getFullYear() - dataArray[i - 1].getFullYear());
+            arr[1].push(monthDiff(dataArray[i - 1], d));
+            arr[2].push(Math.round((d - dataArray[i - 1]) / (1000 * 60 * 60 * 24)));
+            arr[3].push(Math.round((d - dataArray[i - 1]) / (1000 * 60 * 60)));
+        }
+        return arr;
+    }, [
+        [],
+        [],
+        [],
+        []
+    ]), 4), yearlySteps = _dataArray_reduce[0], monthlySteps = _dataArray_reduce[1], dailySteps = _dataArray_reduce[2], hourlySteps = _dataArray_reduce[3];
+    return (yearlySteps.every(function(s) {
+        return s >= 1 && !(s % 1);
+    }) // Yearly Data 
+     ? formatYear : monthlySteps.every(function(s) {
+        return s >= 3 && !(s % 3);
+    }) // Quarterly Data
+     ? +timeYear(d) === d || firstOrLast || smallArray ? formatQuarterYear : formatQuarter : monthlySteps.every(function(s) {
+        return s >= 1 && !(s % 1);
+    }) // Monthly Data
+     ? +timeYear(d) === d || firstOrLast || smallArray ? formatMonthYear : formatMonth : dailySteps.every(function(s) {
+        return s >= 1 && !(s % 1);
+    }) // Daily Data
+     ? +timeYear(d) === d || firstOrLast || smallArray ? formatMonthDayYear : formatMonthDay : hourlySteps.every(function(s) {
+        return s >= 1 && !(s % 1);
+    }) // Hourly Data
+     ? firstOrLast || smallArray ? formatMonthDayYear : +timeMonth(d) === d ? formatMonthDay : formatHour : timeSecond(d) < d ? formatMillisecond : timeMinute(d) < d ? formatSecond : timeHour(d) < d ? formatMinute : d)(d);
+}
+/**
+    @function monthDiff
+    @desc Returns the number of months between two Date objects
+    @param {*} d1
+    @param {*} d2
+    @returns {Number} the number of months between the two Date objects
+    @private
+*/ function monthDiff(d1, d2) {
+    var months;
+    months = (d2.getFullYear() - d1.getFullYear()) * 12;
+    months -= d1.getMonth();
+    months += d2.getMonth();
+    return months <= 0 ? 0 : months;
+}

package/es/src/formatDefaultLocale.js

@@ -0,0 +1,12 @@
+import format from "./format.js";
+import { formatDefaultLocale } from "d3-format";
+/**
+    @function formatDefaultLocale
+    @desc An extension to d3's [formatDefaultLocale](https://github.com/d3/d3-format#api-reference) function that allows setting the locale globally for formatters.
+    @param {Object} definition The localization definition.
+    @returns {Object}
+*/ export default function(definition) {
+    var locale = formatDefaultLocale(definition);
+    locale.format = format;
+    return locale;
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@d3plus/format",
+  "version": "3.0.0-alpha.0",
+  "description": "JavaScript formatters for localized numbers and dates.",
+  "license": "MIT",
+  "type": "module",
+  "exports": "./es/index.js",
+  "browser": "./umd/d3plus-format.full.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "files": [
+    "umd",
+    "es"
+  ],
+  "homepage": "https://d3plus.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/d3plus/d3plus.git",
+    "directory": "packages/format"
+  },
+  "keywords": [
+    "format",
+    "d3",
+    "d3plus",
+    "data",
+    "visualization"
+  ],
+  "scripts": {
+    "build:esm": "node ../../scripts/build-esm.js",
+    "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": {
+    "@d3plus/locales": "3.0.0-alpha.0",
+    "d3-format": "^3.1.0",
+    "d3-time": "^3.1.0",
+    "d3-time-format": "^4.1.0"
+  }
+}