@ethisyscore/core-utils 1.92.1 → 1.94.0

package/dist/number/index.d.cts

@@ -0,0 +1,41 @@
+/**
+ * Framework-agnostic number DISPLAY formatting.
+ *
+ * Pure helpers for rendering plain numeric values and ratios as strings, with a
+ * deterministic `en-GB` fallback locale so output is machine-stable regardless
+ * of the host OS locale - the same principle as the money and date seams.
+ *
+ * It is pure - no React, no host access - so it lives in core-utils behind the
+ * `@ethisyscore/core-utils/number` sub-path.
+ */
+/**
+ * Deterministic fallback locale. Matches the money/date seams so numbers render
+ * consistently when no explicit locale is supplied, and so output does not drift
+ * with the OS locale of whatever host renders it.
+ */
+declare const NUMBER_FALLBACK_LOCALE = "en-GB";
+/**
+ * Formats a numeric value with grouping and a fixed number of decimal places via
+ * `Intl.NumberFormat`. Returns an em-dash (`"—"`) for null/undefined so an
+ * absent value renders as a readable placeholder rather than `"NaN"` or `"null"`.
+ *
+ * Defaults to two decimal places in {@link NUMBER_FALLBACK_LOCALE}.
+ */
+declare function formatNumber(value: number | null | undefined, options?: {
+    decimalPlaces?: number;
+    locale?: string;
+}): string;
+/**
+ * Formats a RATIO as a percentage string with a fixed number of decimal places -
+ * e.g. `0.1234` -> `"12.34%"`. The input is a ratio, not an already-scaled
+ * percentage.
+ *
+ * Uses `toFixed` (no grouping) rather than `Intl` percent style so output is a
+ * plain fixed-decimal percentage, matching what callers expect on compact labels.
+ * Defaults to two decimal places.
+ */
+declare function formatPercent(ratio: number, options?: {
+    decimalPlaces?: number;
+}): string;
+
+export { NUMBER_FALLBACK_LOCALE, formatNumber, formatPercent };

package/dist/number/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Framework-agnostic number DISPLAY formatting.
+ *
+ * Pure helpers for rendering plain numeric values and ratios as strings, with a
+ * deterministic `en-GB` fallback locale so output is machine-stable regardless
+ * of the host OS locale - the same principle as the money and date seams.
+ *
+ * It is pure - no React, no host access - so it lives in core-utils behind the
+ * `@ethisyscore/core-utils/number` sub-path.
+ */
+/**
+ * Deterministic fallback locale. Matches the money/date seams so numbers render
+ * consistently when no explicit locale is supplied, and so output does not drift
+ * with the OS locale of whatever host renders it.
+ */
+declare const NUMBER_FALLBACK_LOCALE = "en-GB";
+/**
+ * Formats a numeric value with grouping and a fixed number of decimal places via
+ * `Intl.NumberFormat`. Returns an em-dash (`"—"`) for null/undefined so an
+ * absent value renders as a readable placeholder rather than `"NaN"` or `"null"`.
+ *
+ * Defaults to two decimal places in {@link NUMBER_FALLBACK_LOCALE}.
+ */
+declare function formatNumber(value: number | null | undefined, options?: {
+    decimalPlaces?: number;
+    locale?: string;
+}): string;
+/**
+ * Formats a RATIO as a percentage string with a fixed number of decimal places -
+ * e.g. `0.1234` -> `"12.34%"`. The input is a ratio, not an already-scaled
+ * percentage.
+ *
+ * Uses `toFixed` (no grouping) rather than `Intl` percent style so output is a
+ * plain fixed-decimal percentage, matching what callers expect on compact labels.
+ * Defaults to two decimal places.
+ */
+declare function formatPercent(ratio: number, options?: {
+    decimalPlaces?: number;
+}): string;
+
+export { NUMBER_FALLBACK_LOCALE, formatNumber, formatPercent };

package/dist/number/index.js

@@ -0,0 +1,19 @@
+// src/number/format.ts
+var NUMBER_FALLBACK_LOCALE = "en-GB";
+function formatNumber(value, options) {
+  if (value == null) {
+    return "\u2014";
+  }
+  const dp = options?.decimalPlaces ?? 2;
+  return new Intl.NumberFormat(options?.locale ?? NUMBER_FALLBACK_LOCALE, {
+    minimumFractionDigits: dp,
+    maximumFractionDigits: dp
+  }).format(value);
+}
+function formatPercent(ratio, options) {
+  return `${(ratio * 100).toFixed(options?.decimalPlaces ?? 2)}%`;
+}
+
+export { NUMBER_FALLBACK_LOCALE, formatNumber, formatPercent };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/number/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/number/format.ts"],"names":[],"mappings":";AAgBO,IAAM,sBAAA,GAAyB;AAS/B,SAAS,YAAA,CACd,OACA,OAAA,EACQ;AACR,EAAA,IAAI,SAAS,IAAA,EAAM;AACjB,IAAA,OAAO,QAAA;AAAA,EACT;AAEA,EAAA,MAAM,EAAA,GAAK,SAAS,aAAA,IAAiB,CAAA;AACrC,EAAA,OAAO,IAAI,IAAA,CAAK,YAAA,CAAa,OAAA,EAAS,UAAU,sBAAA,EAAwB;AAAA,IACtE,qBAAA,EAAuB,EAAA;AAAA,IACvB,qBAAA,EAAuB;AAAA,GACxB,CAAA,CAAE,MAAA,CAAO,KAAK,CAAA;AACjB;AAWO,SAAS,aAAA,CAAc,OAAe,OAAA,EAA8C;AACzF,EAAA,OAAO,IAAI,KAAA,GAAQ,GAAA,EAAK,QAAQ,OAAA,EAAS,aAAA,IAAiB,CAAC,CAAC,CAAA,CAAA,CAAA;AAC9D","file":"index.js","sourcesContent":["/**\n * Framework-agnostic number DISPLAY formatting.\n *\n * Pure helpers for rendering plain numeric values and ratios as strings, with a\n * deterministic `en-GB` fallback locale so output is machine-stable regardless\n * of the host OS locale - the same principle as the money and date seams.\n *\n * It is pure - no React, no host access - so it lives in core-utils behind the\n * `@ethisyscore/core-utils/number` sub-path.\n */\n\n/**\n * Deterministic fallback locale. Matches the money/date seams so numbers render\n * consistently when no explicit locale is supplied, and so output does not drift\n * with the OS locale of whatever host renders it.\n */\nexport const NUMBER_FALLBACK_LOCALE = \"en-GB\";\n\n/**\n * Formats a numeric value with grouping and a fixed number of decimal places via\n * `Intl.NumberFormat`. Returns an em-dash (`\"—\"`) for null/undefined so an\n * absent value renders as a readable placeholder rather than `\"NaN\"` or `\"null\"`.\n *\n * Defaults to two decimal places in {@link NUMBER_FALLBACK_LOCALE}.\n */\nexport function formatNumber(\n  value: number | null | undefined,\n  options?: { decimalPlaces?: number; locale?: string },\n): string {\n  if (value == null) {\n    return \"—\";\n  }\n\n  const dp = options?.decimalPlaces ?? 2;\n  return new Intl.NumberFormat(options?.locale ?? NUMBER_FALLBACK_LOCALE, {\n    minimumFractionDigits: dp,\n    maximumFractionDigits: dp,\n  }).format(value);\n}\n\n/**\n * Formats a RATIO as a percentage string with a fixed number of decimal places -\n * e.g. `0.1234` -> `\"12.34%\"`. The input is a ratio, not an already-scaled\n * percentage.\n *\n * Uses `toFixed` (no grouping) rather than `Intl` percent style so output is a\n * plain fixed-decimal percentage, matching what callers expect on compact labels.\n * Defaults to two decimal places.\n */\nexport function formatPercent(ratio: number, options?: { decimalPlaces?: number }): string {\n  return `${(ratio * 100).toFixed(options?.decimalPlaces ?? 2)}%`;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethisyscore/core-utils",
-  "version": "1.92.1",
+  "version": "1.94.0",
   "description": "Framework-agnostic utilities shared by the EthisysCore monolith and plugins: date/time/duration helpers (over date-fns), RFC 6902 JSON Patch generate/apply (over mutative), and list-response envelope normalisation. Pure TypeScript; no React or MUI. The dayjs-backed picker helper lives behind the ./date/dayjs sub-path so the core entry stays dayjs-free.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -41,6 +41,11 @@
       "types": "./dist/money/index.d.ts",
       "import": "./dist/money/index.js",
       "require": "./dist/money/index.cjs"
+    },
+    "./number": {
+      "types": "./dist/number/index.d.ts",
+      "import": "./dist/number/index.js",
+      "require": "./dist/number/index.cjs"
     }
   },
   "files": [