@cfasim-ui/shared 0.4.6 → 0.4.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfasim-ui/shared",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "type": "module",
   "description": "Shared utilities for cfasim-ui",
   "license": "Apache-2.0",
@@ -22,8 +22,12 @@
     "vue": "^3.5.0"
   },
   "devDependencies": {
+    "@types/sprintf-js": "^1.1.4",
     "@vue/test-utils": "^2.4.6",
     "happy-dom": "^20.8.9",
     "vitest": "^4.1.0"
+  },
+  "dependencies": {
+    "sprintf-js": "^1.1.3"
   }
 }

package/src/formatNumber.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from "vitest";
+import { formatNumber, isNumberFormat } from "./formatNumber.js";
+
+describe("formatNumber", () => {
+  it("returns String(value) when no format is given", () => {
+    expect(formatNumber(42)).toBe("42");
+    expect(formatNumber(1.5)).toBe("1.5");
+  });
+
+  it("passes non-finite values through unchanged", () => {
+    expect(formatNumber(NaN, "percent")).toBe("NaN");
+    expect(formatNumber(Infinity, "%.2f")).toBe("Infinity");
+    expect(formatNumber(-Infinity, (v) => `x=${v}`)).toBe("-Infinity");
+  });
+
+  it("invokes a custom function formatter", () => {
+    expect(formatNumber(3, (v) => `n=${v * 2}`)).toBe("n=6");
+  });
+
+  describe("presets", () => {
+    it("plain returns String(value)", () => {
+      expect(formatNumber(1234.5, "plain")).toBe("1234.5");
+    });
+
+    it("localized groups thousands", () => {
+      // Locale-dependent grouping char; just check there's a separator.
+      const out = formatNumber(1234567, "localized");
+      expect(out).toMatch(/1.234.567/);
+    });
+
+    it("percent multiplies by 100 and appends %", () => {
+      expect(formatNumber(0.5, "percent")).toBe("50%");
+      expect(formatNumber(0.1234, "percent")).toBe("12.34%");
+    });
+
+    it("presets preserve raw precision when no :N is given", () => {
+      // Without a digit suffix, these used to round at Intl defaults (~3
+      // significant digits). Now they preserve the raw value.
+      expect(formatNumber(1234.5678, "localized")).toMatch(/1.234[.,]5678$/);
+      expect(formatNumber(0.123456, "percent")).toBe("12.3456%");
+      expect(formatNumber(12345, "scientific")).toBe("1.2345E4");
+      expect(formatNumber(12345, "engineering")).toBe("12.345E3");
+    });
+
+    it("compact uses short forms", () => {
+      expect(formatNumber(1500, "compact")).toBe("1.5K");
+      expect(formatNumber(2_500_000, "compact")).toBe("2.5M");
+    });
+
+    it("scientific uses scientific notation", () => {
+      expect(formatNumber(12345, "scientific")).toMatch(/^1\.\d+E4$/);
+      expect(formatNumber(0.001, "scientific")).toBe("1E-3");
+    });
+
+    it("engineering uses powers of 1000", () => {
+      expect(formatNumber(12345, "engineering")).toMatch(/^12\.\d+E3$/);
+    });
+  });
+
+  describe("preset:digits suffix", () => {
+    it("plain:N rounds to N decimal places", () => {
+      expect(formatNumber(1.2345, "plain:2")).toBe("1.23");
+      expect(formatNumber(1, "plain:0")).toBe("1");
+    });
+
+    it("localized:N pads/truncates fractional digits", () => {
+      expect(formatNumber(1234.5, "localized:2")).toBe("1,234.50");
+      expect(formatNumber(1234.567, "localized:0")).toBe("1,235");
+    });
+
+    it("percent:N controls fraction digits", () => {
+      expect(formatNumber(0.1234, "percent:1")).toBe("12.3%");
+      expect(formatNumber(0.5, "percent:0")).toBe("50%");
+      expect(formatNumber(0.5, "percent:2")).toBe("50.00%");
+    });
+
+    it("compact:N controls fraction digits", () => {
+      expect(formatNumber(1500, "compact:2")).toBe("1.50K");
+      expect(formatNumber(1500, "compact:0")).toBe("2K");
+    });
+
+    it("scientific:N controls fraction digits", () => {
+      expect(formatNumber(12345, "scientific:2")).toBe("1.23E4");
+    });
+
+    it("engineering:N controls fraction digits", () => {
+      expect(formatNumber(12345, "engineering:1")).toBe("12.3E3");
+    });
+
+    it("throws on malformed :suffix", () => {
+      expect(() => formatNumber(42, "percent:abc")).toThrow(/invalid format/);
+      expect(() => formatNumber(42, "compact:")).toThrow(/invalid format/);
+      expect(() => formatNumber(42, "percent:1.5")).toThrow(/invalid format/);
+    });
+
+    it("throws on unknown preset names", () => {
+      expect(() => formatNumber(42, "bogus")).toThrow(/invalid format/);
+    });
+  });
+
+  describe("printf strings", () => {
+    it("formats with %f", () => {
+      expect(formatNumber(3.14159, "%.2f")).toBe("3.14");
+    });
+
+    it("formats with %d", () => {
+      expect(formatNumber(42, "%05d")).toBe("00042");
+    });
+
+    it("supports compound printf strings", () => {
+      expect(formatNumber(0.42, "rate: %.1f")).toBe("rate: 0.4");
+    });
+
+    it("treats any string with % as printf (skips preset parsing)", () => {
+      // Even though "percent" is a preset name, a `%` placeholder anywhere
+      // routes through sprintf instead.
+      expect(formatNumber(42, "percent %d")).toBe("percent 42");
+    });
+  });
+});
+
+describe("isNumberFormat", () => {
+  it("accepts strings and functions", () => {
+    expect(isNumberFormat("percent")).toBe(true);
+    expect(isNumberFormat("%.2f")).toBe(true);
+    expect(isNumberFormat((v: number) => String(v))).toBe(true);
+  });
+
+  it("rejects other types", () => {
+    expect(isNumberFormat(undefined)).toBe(false);
+    expect(isNumberFormat(null)).toBe(false);
+    expect(isNumberFormat(42)).toBe(false);
+    expect(isNumberFormat({})).toBe(false);
+  });
+});

package/src/formatNumber.ts

@@ -0,0 +1,146 @@
+import { sprintf } from "sprintf-js";
+
+/**
+ * Named number-format presets, modelled on Streamlit's number column formats.
+ * - `plain` — `String(value)` (no grouping)
+ * - `localized` — `Intl.NumberFormat()` with the user's locale
+ * - `percent` — formats as a percent (value `0.5` → `"50%"`)
+ * - `compact` — short form (`1.2K`, `3.4M`)
+ * - `scientific` — scientific notation (`1.23E4`)
+ * - `engineering` — engineering notation (powers of 1000)
+ *
+ * Presets preserve the raw value's precision by default (no rounding).
+ * Append `:N` (a digit) to fix the number of fractional digits, e.g.
+ * `"percent:1"` → `"12.3%"`, `"localized:2"` → `"1,234.50"`.
+ */
+export type NumberFormatPreset =
+  | "plain"
+  | "localized"
+  | "percent"
+  | "compact"
+  | "scientific"
+  | "engineering";
+
+/**
+ * A number format specifier:
+ * - A {@link NumberFormatPreset} name, optionally with `:N` digits suffix
+ *   (e.g. `"percent:1"`, `"compact:2"`)
+ * - A printf-style format string (must contain a `%` placeholder, parsed
+ *   by sprintf-js — e.g. `"%.2f"`, `"%05d"`)
+ * - A function `(value) => string` for full control
+ *
+ * Strings that contain no `%` and don't match a preset throw at format
+ * time, so typos surface immediately instead of silently rendering wrong.
+ */
+export type NumberFormat =
+  | NumberFormatPreset
+  | string
+  | ((value: number) => string);
+
+const PRESET_NAMES = new Set<NumberFormatPreset>([
+  "plain",
+  "localized",
+  "percent",
+  "compact",
+  "scientific",
+  "engineering",
+]);
+
+function isPreset(s: string): s is NumberFormatPreset {
+  return PRESET_NAMES.has(s as NumberFormatPreset);
+}
+
+/**
+ * Parse `"preset"` or `"preset:N"` into a name and optional digit count.
+ * Returns null if the string isn't a recognized preset.
+ */
+function parsePreset(
+  s: string,
+): { preset: NumberFormatPreset; digits: number | undefined } | null {
+  const colon = s.indexOf(":");
+  if (colon === -1) {
+    return isPreset(s) ? { preset: s, digits: undefined } : null;
+  }
+  const name = s.slice(0, colon);
+  const rest = s.slice(colon + 1);
+  if (!isPreset(name)) return null;
+  // Digits must be a non-negative integer (matches Intl's 0..100 range).
+  if (!/^\d+$/.test(rest)) return null;
+  const digits = Number(rest);
+  if (digits > 100) return null;
+  return { preset: name, digits };
+}
+
+// Covers JS double-precision (≤17 significant digits). When the caller
+// hasn't asked for a specific digit count, we use this to preserve the
+// raw value rather than letting Intl round to its default precision.
+const RAW_PRECISION_DIGITS = 20;
+
+function formatPreset(
+  value: number,
+  preset: NumberFormatPreset,
+  digits: number | undefined,
+): string {
+  const fractionOpts: Intl.NumberFormatOptions =
+    digits !== undefined
+      ? { minimumFractionDigits: digits, maximumFractionDigits: digits }
+      : { maximumFractionDigits: RAW_PRECISION_DIGITS };
+  switch (preset) {
+    case "plain":
+      return digits !== undefined ? value.toFixed(digits) : String(value);
+    case "localized":
+      return new Intl.NumberFormat(undefined, fractionOpts).format(value);
+    case "percent":
+      return new Intl.NumberFormat(undefined, {
+        style: "percent",
+        ...fractionOpts,
+      }).format(value);
+    case "compact":
+      return new Intl.NumberFormat(undefined, {
+        notation: "compact",
+        ...fractionOpts,
+      }).format(value);
+    case "scientific":
+      return new Intl.NumberFormat(undefined, {
+        notation: "scientific",
+        ...fractionOpts,
+      }).format(value);
+    case "engineering":
+      return new Intl.NumberFormat(undefined, {
+        notation: "engineering",
+        ...fractionOpts,
+      }).format(value);
+  }
+}
+
+/**
+ * Format a number using a preset name, a printf-style format string, or a
+ * custom function. Non-finite values (NaN, ±Infinity) are returned as
+ * `String(value)`; if `format` is omitted, falls back to `String(value)`.
+ *
+ * Throws if `format` is a string that's neither a recognized preset (with
+ * an optional `:N` digit suffix) nor a printf string containing `%`.
+ */
+export function formatNumber(value: number, format?: NumberFormat): string {
+  if (!Number.isFinite(value)) return String(value);
+  if (format === undefined) return String(value);
+  if (typeof format === "function") return format(value);
+  // printf strings always contain a `%` placeholder; everything else must
+  // be a recognized preset (with an optional `:N` digits suffix).
+  if (format.includes("%")) return sprintf(format, value);
+  const parsed = parsePreset(format);
+  if (!parsed) {
+    const names = [...PRESET_NAMES].join(", ");
+    throw new Error(
+      `formatNumber: invalid format ${JSON.stringify(format)}. ` +
+        `Expected one of ${names} (optionally with ":N" digits), ` +
+        `a printf format string containing "%", or a function.`,
+    );
+  }
+  return formatPreset(value, parsed.preset, parsed.digits);
+}
+
+/** True if `f` is a recognized {@link NumberFormat} value. */
+export function isNumberFormat(f: unknown): f is NumberFormat {
+  return typeof f === "string" || typeof f === "function";
+}

package/src/index.ts

@@ -14,6 +14,8 @@ export type {
   ModelOutputsWire,
 } from "./ModelOutput.js";
 export { modelOutputToCSV } from "./csv.js";
+export { formatNumber, isNumberFormat } from "./formatNumber.js";
+export type { NumberFormat, NumberFormatPreset } from "./formatNumber.js";
 export {
   useUrlParams,
   serialize,