@ptx-showcase/utils 0.4.0 → 0.6.0

package/README.md

@@ -126,6 +126,30 @@ await downloadBlob(blob, { hash: 12345 })
 
 ---
 
+### getCurrencySymbol
+
+Resolves the symbol for an ISO 4217 currency code via `Intl`. A handful of currencies (`AUD`, `CAD`, `NZD`, `CHF`, etc.) are overridden where the `Intl` narrow symbol would be ambiguous.
+
+```ts
+// from root
+import { getCurrencySymbol } from '@ptx-showcase/utils'
+
+// from subpath
+import { getCurrencySymbol } from '@ptx-showcase/utils/currency-symbol'
+
+getCurrencySymbol('EUR') // → '€'
+getCurrencySymbol('USD') // → '$'
+getCurrencySymbol('AUD') // → 'A$' (override)
+getCurrencySymbol('CHF') // → '₣' (override)
+getCurrencySymbol('ZZZ') // → 'ZZZ' (well-formed but unknown code)
+getCurrencySymbol('EURO') // → 'N/A' (not a 3-letter code)
+
+// custom locale
+getCurrencySymbol('EUR', 'de-DE') // → '€'
+```
+
+---
+
 ### handleApiError
 
 Parses backend error responses (including `ky`'s `HTTPError`) and reports human-readable messages through whatever notification system your project uses (`vue-sonner`, `react-hot-toast`, `console.error`, etc).
@@ -159,6 +183,57 @@ try {
 
 ---
 
+### normalizeDecimalInput / normalizePhoneNumberInput
+
+In-place `input`/`change` event handlers that sanitize a text input's value as the user types.
+
+- `normalizeDecimalInput` — keeps only digits and a single dot, converts a comma to a dot, prefixes a leading dot with `0`, and truncates the decimal part to `decimals` digits (default `2`).
+- `normalizePhoneNumberInput` — keeps only digits, truncates to `maxDigits` (default `15`, the E.164 limit), and prefixes the result with `+`.
+
+```ts
+// from root
+import { normalizeDecimalInput, normalizePhoneNumberInput } from '@ptx-showcase/utils'
+
+// from subpath
+import { normalizeDecimalInput, normalizePhoneNumberInput } from '@ptx-showcase/utils/normalize-input'
+
+// Vue
+<input type="text" inputmode="decimal" @input="normalizeDecimalInput" />
+<input type="text" inputmode="tel" @input="normalizePhoneNumberInput" />
+
+// React (wrap to access the native event)
+<input type="text" inputMode="decimal" onChange={(e) => normalizeDecimalInput(e.nativeEvent, 4)} />
+<input type="text" inputMode="tel" onChange={(e) => normalizePhoneNumberInput(e.nativeEvent, 11)} />
+```
+
+---
+
+### truncateDecimals
+
+Formats a number (or numeric string) to a fixed number of decimal places by cutting the extra digits off, **without rounding**. Accepts a string too, so values more precise than a JS `number` can hold (e.g. amounts from an API) can be truncated without a lossy float conversion first. Returns `'N/A'` for anything that isn't a finite number or a well-formed numeric string.
+
+```ts
+// from root
+import { truncateDecimals } from '@ptx-showcase/utils'
+
+// from subpath
+import { truncateDecimals } from '@ptx-showcase/utils/truncate-decimals'
+
+truncateDecimals(4.21312312) // → '4.21'
+truncateDecimals(4.995) // → '4.99' (not rounded to 5.00)
+truncateDecimals(4.2) // → '4.2' (fewer decimals than requested — left untouched)
+truncateDecimals(4.219, 0) // → '4'
+
+// numeric string input — no float precision loss
+truncateDecimals('4.219999999999999999999999', 2) // → '4.21'
+
+// invalid input
+truncateDecimals('not a number') // → 'N/A'
+truncateDecimals(undefined) // → 'N/A'
+```
+
+---
+
 ## Available modules
 
 | Subpath                                  | Exports                                                          |
@@ -167,8 +242,11 @@ try {
 | `@ptx-showcase/utils/build-query-params` | `buildQueryParams`                                               |
 | `@ptx-showcase/utils/build-sort-param`   | `buildSortParam`                                                 |
 | `@ptx-showcase/utils/cookies`            | `setCookie`, `getCookie`, `deleteCookie`, `defaultCookieOptions` |
+| `@ptx-showcase/utils/currency-symbol`    | `getCurrencySymbol`                                              |
 | `@ptx-showcase/utils/download-file`      | `downloadBlob`                                                   |
 | `@ptx-showcase/utils/handle-api-error`   | `handleApiError`, `initHandleApiError`                           |
+| `@ptx-showcase/utils/normalize-input`    | `normalizeDecimalInput`, `normalizePhoneNumberInput`             |
+| `@ptx-showcase/utils/truncate-decimals`  | `truncateDecimals`                                               |
 | `@ptx-showcase/utils/types`              | `TableColumnConfig`, `PaginatedList`                             |
 
 ---

package/dist/chunks/currency-symbol-CBowgXv-.es

@@ -0,0 +1,26 @@
+//#region src/currency-symbol/constants/currency-symbol.constant.ts
+var e = {
+	CHF: "₣",
+	AUD: "A$",
+	CAD: "CA$",
+	NZD: "NZ$",
+	HKD: "HK$",
+	MXN: "MX$",
+	SGD: "S$"
+}, t = (t, n = "en-US") => {
+	if (typeof t != "string" || t == null || t === "" || t === " " || t.length !== 3) return "N/A";
+	let r = e[t.toUpperCase()];
+	if (r !== void 0) return r;
+	try {
+		let e = new Intl.NumberFormat(n, {
+			style: "currency",
+			currency: t,
+			currencyDisplay: "narrowSymbol"
+		}).formatToParts(0).find((e) => e.type === "currency");
+		return e === void 0 ? t : e.value;
+	} catch {
+		return t;
+	}
+};
+//#endregion
+export { t };

package/dist/chunks/currency-symbol-gb63Q_9Q.cjs

@@ -0,0 +1 @@
+var e={CHF:`₣`,AUD:`A$`,CAD:`CA$`,NZD:`NZ$`,HKD:`HK$`,MXN:`MX$`,SGD:`S$`},t=(t,n=`en-US`)=>{if(typeof t!=`string`||t==null||t===``||t===` `||t.length!==3)return`N/A`;let r=e[t.toUpperCase()];if(r!==void 0)return r;try{let e=new Intl.NumberFormat(n,{style:`currency`,currency:t,currencyDisplay:`narrowSymbol`}).formatToParts(0).find(e=>e.type===`currency`);return e===void 0?t:e.value}catch{return t}};Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return t}});

package/dist/chunks/truncate-decimals-BFMoEzul.es

@@ -0,0 +1,7 @@
+//#region src/truncate-decimals/constants/truncate-decimals.constant.ts
+var e = /^-?\d+(\.\d+)?$/, t = (t, r = 2) => typeof t == "number" ? Number.isFinite(t) ? n(String(t), r) : "N/A" : typeof t == "string" && e.test(t.trim()) ? n(t.trim(), r) : "N/A", n = (e, t) => {
+	let [n, r] = e.split(".");
+	return r === void 0 ? e : t > 0 ? `${n}.${r.slice(0, t)}` : n;
+};
+//#endregion
+export { t };

package/dist/chunks/truncate-decimals-CArL-IeO.cjs

@@ -0,0 +1 @@
+var e=/^-?\d+(\.\d+)?$/,t=(t,r=2)=>typeof t==`number`?Number.isFinite(t)?n(String(t),r):`N/A`:typeof t==`string`&&e.test(t.trim())?n(t.trim(),r):`N/A`,n=(e,t)=>{let[n,r]=e.split(`.`);return r===void 0?e:t>0?`${n}.${r.slice(0,t)}`:n};Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return t}});

package/dist/currency-symbol/constants/currency-symbol.constant.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Explicit code → symbol overrides, checked before falling back to `Intl`.
+ * Use this for symbols `Intl` doesn't resolve the way you want (missing,
+ * wrong, or just not the convention your product uses).
+ */
+export declare const CURRENCY_SYMBOL_OVERRIDES: Record<string, string>;

package/dist/currency-symbol/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../chunks/currency-symbol-gb63Q_9Q.cjs");exports.getCurrencySymbol=e.t;

package/dist/currency-symbol/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns the symbol for a given ISO 4217 currency code.
+ *
+ * Codes listed in `CURRENCY_SYMBOL_OVERRIDES` are returned as-is — this
+ * covers currencies whose `Intl` narrow symbol is ambiguous (e.g. `AUD`,
+ * `CAD`, `NZD` all narrow to a plain `$`) or otherwise not what the product
+ * wants. Everything else is resolved via the runtime's `Intl` data, so all
+ * other currencies are supported without a hardcoded map.
+ *
+ * @param code - ISO 4217 currency code (e.g. `"EUR"`)
+ * @param locale - Locale used to resolve the symbol. Defaults to `"en-US"`.
+ * @returns The currency symbol; `code` itself if it's well-formed but not a
+ * recognized currency; `"N/A"` if `code` isn't a 3-letter string
+ *
+ * @example
+ * ```ts
+ * getCurrencySymbol('EUR') // => '€'
+ * getCurrencySymbol('USD') // => '$'
+ * getCurrencySymbol('AUD') // => 'A$' (override)
+ * getCurrencySymbol('CHF') // => '₣' (override)
+ * ```
+ */
+export declare const getCurrencySymbol: (code: string, locale?: string) => string;

package/dist/currency-symbol/index.js

@@ -0,0 +1,2 @@
+import { t as e } from "../chunks/currency-symbol-CBowgXv-.es";
+export { e as getCurrencySymbol };

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./build-query-params/index.cjs"),t=require("./clean-object/index.cjs"),n=require("./cookies/index.cjs"),r=require("./build-sort-param/index.cjs"),i=require("./download-file/index.cjs"),a=require("./chunks/handle-api-error-D714W9rp.cjs"),o=require("./normalize-input/index.cjs");exports.buildQueryParams=e.buildQueryParams,exports.buildSortParam=r.buildSortParam,exports.cleanObject=t.cleanObject,exports.defaultCookieOptions=n.defaultCookieOptions,exports.deleteCookie=n.deleteCookie,exports.downloadBlob=i.downloadBlob,exports.getCookie=n.getCookie,exports.handleApiError=a.t,exports.initHandleApiError=a.n,exports.normalizeDecimalInput=o.normalizeDecimalInput,exports.normalizePhoneNumberInput=o.normalizePhoneNumberInput,exports.setCookie=n.setCookie;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./build-query-params/index.cjs"),t=require("./clean-object/index.cjs"),n=require("./cookies/index.cjs"),r=require("./build-sort-param/index.cjs"),i=require("./chunks/currency-symbol-gb63Q_9Q.cjs"),a=require("./download-file/index.cjs"),o=require("./chunks/handle-api-error-D714W9rp.cjs"),s=require("./normalize-input/index.cjs"),c=require("./chunks/truncate-decimals-CArL-IeO.cjs");exports.buildQueryParams=e.buildQueryParams,exports.buildSortParam=r.buildSortParam,exports.cleanObject=t.cleanObject,exports.defaultCookieOptions=n.defaultCookieOptions,exports.deleteCookie=n.deleteCookie,exports.downloadBlob=a.downloadBlob,exports.getCookie=n.getCookie,exports.getCurrencySymbol=i.t,exports.handleApiError=o.t,exports.initHandleApiError=o.n,exports.normalizeDecimalInput=s.normalizeDecimalInput,exports.normalizePhoneNumberInput=s.normalizePhoneNumberInput,exports.setCookie=n.setCookie,exports.truncateDecimals=c.t;

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export * from './clean-object';
 export * from './cookies';
 export type * from './types';
 export * from './build-sort-param';
+export * from './currency-symbol';
 export * from './download-file';
 export * from './handle-api-error';
 export * from './normalize-input';
+export * from './truncate-decimals';

package/dist/index.js

@@ -2,7 +2,9 @@ import { buildQueryParams as e } from "./build-query-params/index.js";
 import { cleanObject as t } from "./clean-object/index.js";
 import { defaultCookieOptions as n, deleteCookie as r, getCookie as i, setCookie as a } from "./cookies/index.js";
 import { buildSortParam as o } from "./build-sort-param/index.js";
-import { downloadBlob as s } from "./download-file/index.js";
-import { n as c, t as l } from "./chunks/handle-api-error-CMd_LxPS.es";
-import { normalizeDecimalInput as u, normalizePhoneNumberInput as d } from "./normalize-input/index.js";
-export { e as buildQueryParams, o as buildSortParam, t as cleanObject, n as defaultCookieOptions, r as deleteCookie, s as downloadBlob, i as getCookie, l as handleApiError, c as initHandleApiError, u as normalizeDecimalInput, d as normalizePhoneNumberInput, a as setCookie };
+import { t as s } from "./chunks/currency-symbol-CBowgXv-.es";
+import { downloadBlob as c } from "./download-file/index.js";
+import { n as l, t as u } from "./chunks/handle-api-error-CMd_LxPS.es";
+import { normalizeDecimalInput as d, normalizePhoneNumberInput as f } from "./normalize-input/index.js";
+import { t as p } from "./chunks/truncate-decimals-BFMoEzul.es";
+export { e as buildQueryParams, o as buildSortParam, t as cleanObject, n as defaultCookieOptions, r as deleteCookie, c as downloadBlob, i as getCookie, s as getCurrencySymbol, u as handleApiError, l as initHandleApiError, d as normalizeDecimalInput, f as normalizePhoneNumberInput, a as setCookie, p as truncateDecimals };

package/dist/truncate-decimals/constants/truncate-decimals.constant.d.ts

@@ -0,0 +1 @@
+export declare const NUMERIC_STRING_PATTERN: RegExp;

package/dist/truncate-decimals/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../chunks/truncate-decimals-CArL-IeO.cjs");exports.truncateDecimals=e.t;

package/dist/truncate-decimals/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Formats a number (or numeric string) to a fixed number of decimal places
+ * by cutting the extra digits off, without rounding.
+ *
+ * Unlike `toFixed`, `4.21312312` truncated to 2 decimals stays `4.21`
+ * instead of being rounded to `4.21`/`4.22` depending on the digits that follow.
+ *
+ * Accepts a string as well as a number so that values with more precision
+ * than a JS `number` can hold safely (e.g. amounts coming from an API as
+ * strings) can be truncated without going through a lossy float conversion first.
+ *
+ * Numbers large/small enough to be stringified in exponential notation
+ * (e.g. `1e+21`, `1e-7`) are returned as-is, since there's no decimal part to cut.
+ *
+ * @param value - The number (or numeric string) to truncate
+ * @param decimals - Number of digits to keep after the decimal point.
+ * Pass `0` to drop the decimal part entirely. Defaults to `2`.
+ * @returns The truncated value as a string; `'N/A'` if `value` isn't a finite
+ * number or a well-formed numeric string (e.g. `undefined`, `null`, `NaN`,
+ * `{}`, `[]`, `'not a number'`)
+ *
+ * @example
+ * ```ts
+ * truncateDecimals(4.21312312) // => '4.21'
+ * truncateDecimals(4.2) // => '4.2' (fewer decimals than requested — left untouched)
+ * truncateDecimals(4.219, 0) // => '4'
+ * truncateDecimals('4.219999999999999999999999', 2) // => '4.21' (string input, no float precision loss)
+ * truncateDecimals('not a number') // => 'N/A'
+ * truncateDecimals(undefined as unknown as number) // => 'N/A'
+ * ```
+ */
+export declare const truncateDecimals: (value: number | string, decimals?: number) => string;

package/dist/truncate-decimals/index.js

@@ -0,0 +1,2 @@
+import { t as e } from "../chunks/truncate-decimals-BFMoEzul.es";
+export { e as truncateDecimals };

package/package.json

@@ -2,7 +2,7 @@
 	"name": "@ptx-showcase/utils",
 	"author": "ptx-showcase",
 	"description": "Shared utilities for PTX Showcase projects",
-	"version": "0.4.0",
+	"version": "0.6.0",
 	"private": false,
 	"type": "module",
 	"license": "MIT",
@@ -51,6 +51,11 @@
 			"require": "./dist/clean-object/index.cjs",
 			"types": "./dist/clean-object/index.d.ts"
 		},
+		"./currency-symbol": {
+			"import": "./dist/currency-symbol/index.js",
+			"require": "./dist/currency-symbol/index.cjs",
+			"types": "./dist/currency-symbol/index.d.ts"
+		},
 		"./download-file": {
 			"import": "./dist/download-file/index.js",
 			"require": "./dist/download-file/index.cjs",
@@ -66,6 +71,11 @@
 			"require": "./dist/normalize-input/index.cjs",
 			"types": "./dist/normalize-input/index.d.ts"
 		},
+		"./truncate-decimals": {
+			"import": "./dist/truncate-decimals/index.js",
+			"require": "./dist/truncate-decimals/index.cjs",
+			"types": "./dist/truncate-decimals/index.d.ts"
+		},
 		"./types": {
 			"import": "./dist/types/index.js",
 			"require": "./dist/types/index.cjs",
@@ -87,20 +97,20 @@
 		"access": "public"
 	},
 	"devDependencies": {
-		"@types/node": "^26.1.2",
-		"bumpp": "^12.2.0",
-		"oxfmt": "^0.62.0",
-		"oxlint": "^1.77.0",
+		"@types/node": "^26.4.0",
+		"bumpp": "^12.2.2",
+		"oxfmt": "^0.65.0",
+		"oxlint": "^1.80.0",
 		"typescript": "~6.0.3",
-		"vite": "^8.2.1",
+		"vite": "^8.2.2",
 		"vite-plugin-dts": "^5.0.3",
-		"vitest": "^4.1.10"
+		"vitest": "^4.1.11"
 	},
 	"dependencies": {
 		"@types/file-saver": "^2.0.7",
 		"@types/js-cookie": "^3.0.6",
 		"file-saver": "^2.0.5",
 		"js-cookie": "^3.0.8",
-		"ky": "^2.0.2"
+		"ky": "^2.1.0"
 	}
 }