@ptx-showcase/utils 1.0.0 → 1.1.0

package/README.md

@@ -131,6 +131,35 @@ await downloadBlob(blob, { hash: 12345 })
 
 ---
 
+### Flags
+
+Resolves a flag icon URL for a language/country code, with a three-tier fallback: primary source ([flagcdn.com](https://flagcdn.com)) → secondary source ([flagicons.lipis.dev](https://flagicons.lipis.dev)) → an "unknown flag" placeholder. The placeholder is also returned directly when `languageCode` isn't a usable string at runtime (`null`, `undefined`, `NaN`, an object, an empty/whitespace string, etc.) — the functions never throw.
+
+`FLAG_CODE_ALIASES` maps language codes that differ from their representative country's ISO code (e.g. `en` → `gb`, `ja` → `jp`); codes with no entry are used as-is.
+
+```ts
+// from root
+import { getFlagUrl, handleFlagImageError } from '@ptx-showcase/utils'
+
+// from subpath
+import { getFlagUrl, handleFlagImageError } from '@ptx-showcase/utils/flags'
+
+getFlagUrl('fr') // → 'https://flagcdn.com/fr.svg'
+getFlagUrl('en') // → 'https://flagcdn.com/gb.svg' (resolved via FLAG_CODE_ALIASES)
+getFlagUrl(null as unknown as string) // → unknown-flag placeholder URL
+
+// React — escalates primary → fallback → unknown placeholder on load failure
+<img src={getFlagUrl(code)} onError={(e) => handleFlagImageError(e, code)} />
+
+// Vue
+<img :src="getFlagUrl(code)" @error="(e) => handleFlagImageError(e, code)" />
+
+// Svelte
+<img src={getFlagUrl(code)} on:error={(e) => handleFlagImageError(e, code)} />
+```
+
+---
+
 ### 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.
@@ -270,6 +299,7 @@ truncateDecimals(undefined) // → 'N/A'
 | `@ptx-showcase/utils/cookies`            | `setCookie`, `getCookie`, `deleteCookie`, `defaultCookieOptions`                                                |
 | `@ptx-showcase/utils/currency-symbol`    | `getCurrencySymbol`                                                                                             |
 | `@ptx-showcase/utils/download-file`      | `downloadBlob`                                                                                                  |
+| `@ptx-showcase/utils/flags`              | `getFlagUrl`, `getFlagFallbackUrl`, `getFlagUnknownUrl`, `handleFlagImageError`, `FLAG_CODE_ALIASES`            |
 | `@ptx-showcase/utils/handle-api-error`   | `handleApiError`, `initHandleApiError`                                                                          |
 | `@ptx-showcase/utils/normalize-input`    | `normalizeDecimalInput`, `normalizePhoneNumberInput`                                                            |
 | `@ptx-showcase/utils/truncate-decimals`  | `truncateDecimals`                                                                                              |

package/dist/chunks/flags-BRQ9Jims.cjs

@@ -0,0 +1 @@
+var e={uk:`gb`,en:`gb`,ja:`jp`,zh:`cn`,fr:`fr`,es:`es`,de:`de`,cn:`cn`,ko:`kr`,ar:`sa`,he:`il`,hi:`in`,vi:`vn`,el:`gr`,cs:`cz`,sv:`se`,da:`dk`,fa:`ir`,ur:`pk`,bn:`bd`,ms:`my`,nb:`no`,nn:`no`,ca:`es`,cy:`gb`,ga:`ie`,gd:`gb`,lb:`lu`,eu:`es`,gl:`es`,rm:`ch`,kk:`kz`,hy:`am`,ka:`ge`,sq:`al`,sl:`si`,sr:`rs`,et:`ee`,fil:`ph`,tl:`ph`,sw:`ke`},t=`https://flagcdn.com`,n=`https://flagicons.lipis.dev/flags/4x3`,r=e=>typeof e==`string`&&e.trim().length>0,i=t=>{let n=t.trim().toLowerCase();return Object.hasOwn(e,n)?e[n]:n},a=()=>`${n}/xx.svg`,o=e=>r(e)?`${t}/${i(e)}.svg`:a(),s=e=>r(e)?`${n}/${i(e)}.svg`:a(),c=(e,t)=>{let n=s(t),r=a(),i=e.currentTarget.src;i!==r&&(e.currentTarget.src=i===n?r:n)};Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return c}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return a}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return o}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return s}});

package/dist/chunks/flags-C5E6W9lm.es

@@ -0,0 +1,52 @@
+//#region src/core/flags/constants/flags.constant.ts
+var e = {
+	uk: "gb",
+	en: "gb",
+	ja: "jp",
+	zh: "cn",
+	fr: "fr",
+	es: "es",
+	de: "de",
+	cn: "cn",
+	ko: "kr",
+	ar: "sa",
+	he: "il",
+	hi: "in",
+	vi: "vn",
+	el: "gr",
+	cs: "cz",
+	sv: "se",
+	da: "dk",
+	fa: "ir",
+	ur: "pk",
+	bn: "bd",
+	ms: "my",
+	nb: "no",
+	nn: "no",
+	ca: "es",
+	cy: "gb",
+	ga: "ie",
+	gd: "gb",
+	lb: "lu",
+	eu: "es",
+	gl: "es",
+	rm: "ch",
+	kk: "kz",
+	hy: "am",
+	ka: "ge",
+	sq: "al",
+	sl: "si",
+	sr: "rs",
+	et: "ee",
+	fil: "ph",
+	tl: "ph",
+	sw: "ke"
+}, t = "https://flagcdn.com", n = "https://flagicons.lipis.dev/flags/4x3", r = (e) => typeof e == "string" && e.trim().length > 0, i = (t) => {
+	let n = t.trim().toLowerCase();
+	return Object.hasOwn(e, n) ? e[n] : n;
+}, a = () => `${n}/xx.svg`, o = (e) => r(e) ? `${t}/${i(e)}.svg` : a(), s = (e) => r(e) ? `${n}/${i(e)}.svg` : a(), c = (e, t) => {
+	let n = s(t), r = a(), i = e.currentTarget.src;
+	i !== r && (e.currentTarget.src = i === n ? r : n);
+};
+//#endregion
+export { c as i, a as n, o as r, s as t };

package/dist/core/flags/constants/flags.constant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Maps an ISO 639-1 language code to the ISO 3166-1 country code of the flag
+ * that should represent it, for languages where the two codes differ.
+ *
+ * Some mappings are inherently ambiguous (e.g. Arabic, Swahili are official in
+ * many countries) — the chosen country is the most common default for that case.
+ */
+export declare const FLAG_CODE_ALIASES: Record<string, string>;
+export declare const FLAGS_BASE_URL: "https://flagcdn.com";
+export declare const FLAGS_FALLBACK_URL: "https://flagicons.lipis.dev/flags/4x3";
+/**
+ * Code for the "unknown flag" placeholder (a plain flag with no country emblem),
+ * only available on {@link FLAGS_FALLBACK_URL} — flagcdn.com has no equivalent.
+ */
+export declare const FLAG_UNKNOWN_CODE: "xx";

package/dist/core/flags/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Returns the "unknown flag" placeholder URL, used when both {@link getFlagUrl}
+ * and {@link getFlagFallbackUrl} fail to load, and as the direct result of either
+ * when `languageCode` isn't a usable string (e.g. `null`, `undefined`, `NaN`, an object).
+ */
+export declare const getFlagUnknownUrl: () => string;
+/**
+ * Returns the primary flag icon URL ({@link FLAGS_BASE_URL}) for the given language/country code.
+ * Falls back to {@link getFlagUnknownUrl} if `languageCode` isn't a non-empty string at runtime.
+ *
+ * @param languageCode - Language or country code (e.g. `en`, `uk`, `fr`)
+ */
+export declare const getFlagUrl: (languageCode: string) => string;
+/**
+ * Returns the fallback flag icon URL ({@link FLAGS_FALLBACK_URL}), used when
+ * the image from {@link getFlagUrl} fails to load. Falls back to {@link getFlagUnknownUrl}
+ * if `languageCode` isn't a non-empty string at runtime.
+ *
+ * @param languageCode - Language or country code (e.g. `en`, `uk`, `fr`)
+ */
+export declare const getFlagFallbackUrl: (languageCode: string) => string;
+/**
+ * `onError` handler for an `<img>` displaying a flag from {@link getFlagUrl}. Escalates
+ * through three tiers, stopping once it reaches the last one to avoid an infinite loop:
+ * primary ({@link getFlagUrl}) → fallback ({@link getFlagFallbackUrl}) → unknown-flag
+ * placeholder ({@link getFlagUnknownUrl}).
+ *
+ * @param event - Image error event (DOM `Event` or React's `SyntheticEvent<HTMLImageElement>`)
+ * @param languageCode - Same code that was passed to {@link getFlagUrl}
+ *
+ * @example React
+ * ```tsx
+ * <img src={getFlagUrl(code)} onError={(e) => handleFlagImageError(e, code)} />
+ * ```
+ *
+ * @example Vue
+ * ```vue
+ * <img :src="getFlagUrl(code)" @error="(e) => handleFlagImageError(e, code)" />
+ * ```
+ *
+ * @example Svelte
+ * ```svelte
+ * <img src={getFlagUrl(code)} on:error={(e) => handleFlagImageError(e, code)} />
+ * ```
+ */
+export declare const handleFlagImageError: (event: {
+    currentTarget: HTMLImageElement;
+}, languageCode: string) => void;

package/dist/core/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("../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;
+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/flags-BRQ9Jims.cjs"),s=require("../chunks/handle-api-error-D714W9rp.cjs"),c=require("../normalize-input/index.cjs"),l=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.getFlagFallbackUrl=o.t,exports.getFlagUnknownUrl=o.n,exports.getFlagUrl=o.r,exports.handleApiError=s.t,exports.handleFlagImageError=o.i,exports.initHandleApiError=s.n,exports.normalizeDecimalInput=c.normalizeDecimalInput,exports.normalizePhoneNumberInput=c.normalizePhoneNumberInput,exports.setCookie=n.setCookie,exports.truncateDecimals=l.t;

package/dist/core/index.d.ts

@@ -4,6 +4,7 @@ export * from './cookies';
 export * from './build-sort-param';
 export * from './currency-symbol';
 export * from './download-file';
+export * from './flags';
 export * from './handle-api-error';
 export * from './normalize-input';
 export * from './truncate-decimals';

package/dist/core/index.js

@@ -4,7 +4,8 @@ import { defaultCookieOptions as n, deleteCookie as r, getCookie as i, setCookie
 import { buildSortParam as o } from "../build-sort-param/index.js";
 import { t as s } from "../chunks/currency-symbol-CJp1EcR5.es";
 import { downloadBlob as c } from "../download-file/index.js";
-import { n as l, t as u } from "../chunks/handle-api-error-BYygTKYM.es";
-import { normalizeDecimalInput as d, normalizePhoneNumberInput as f } from "../normalize-input/index.js";
-import { t as p } from "../chunks/truncate-decimals-BPaTWeHm.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 };
+import { i as l, n as u, r as d, t as f } from "../chunks/flags-C5E6W9lm.es";
+import { n as p, t as m } from "../chunks/handle-api-error-BYygTKYM.es";
+import { normalizeDecimalInput as h, normalizePhoneNumberInput as g } from "../normalize-input/index.js";
+import { t as _ } from "../chunks/truncate-decimals-BPaTWeHm.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, f as getFlagFallbackUrl, u as getFlagUnknownUrl, d as getFlagUrl, m as handleApiError, l as handleFlagImageError, p as initHandleApiError, h as normalizeDecimalInput, g as normalizePhoneNumberInput, a as setCookie, _ as truncateDecimals };

package/dist/flags/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../chunks/flags-BRQ9Jims.cjs");exports.getFlagFallbackUrl=e.t,exports.getFlagUnknownUrl=e.n,exports.getFlagUrl=e.r,exports.handleFlagImageError=e.i;

package/dist/flags/index.js

@@ -0,0 +1,2 @@
+import { i as e, n as t, r as n, t as r } from "../chunks/flags-C5E6W9lm.es";
+export { r as getFlagFallbackUrl, t as getFlagUnknownUrl, n as getFlagUrl, e as handleFlagImageError };

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./chunks/base-DLHy3wps.cjs"),t=require("./chunks/admin-DR1tBkNV.cjs"),n=require("./build-query-params/index.cjs"),r=require("./clean-object/index.cjs"),i=require("./cookies/index.cjs"),a=require("./build-sort-param/index.cjs"),o=require("./chunks/currency-symbol-gb63Q_9Q.cjs"),s=require("./download-file/index.cjs"),c=require("./chunks/handle-api-error-D714W9rp.cjs"),l=require("./normalize-input/index.cjs"),u=require("./chunks/truncate-decimals-CArL-IeO.cjs");require("./core/index.cjs"),exports.ADMIN_QUERY_KEYS=t.n,exports.DISCOUNT_TYPES=e.t,exports.ORDER_STATUSES=e.n,exports.SUPPORT_STATUSES=e.r,exports.buildQueryParams=n.buildQueryParams,exports.buildSortParam=a.buildSortParam,exports.cleanObject=r.cleanObject,exports.defaultCookieOptions=i.defaultCookieOptions,exports.deleteCookie=i.deleteCookie,exports.downloadBlob=s.downloadBlob,exports.getCookie=i.getCookie,exports.getCurrencySymbol=o.t,exports.handleApiError=c.t,exports.initHandleApiError=c.n,exports.isAdminToken=t.t,exports.normalizeDecimalInput=l.normalizeDecimalInput,exports.normalizePhoneNumberInput=l.normalizePhoneNumberInput,exports.setCookie=i.setCookie,exports.truncateDecimals=u.t;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./chunks/base-DLHy3wps.cjs"),t=require("./chunks/admin-DR1tBkNV.cjs"),n=require("./build-query-params/index.cjs"),r=require("./clean-object/index.cjs"),i=require("./cookies/index.cjs"),a=require("./build-sort-param/index.cjs"),o=require("./chunks/currency-symbol-gb63Q_9Q.cjs"),s=require("./download-file/index.cjs"),c=require("./chunks/flags-BRQ9Jims.cjs"),l=require("./chunks/handle-api-error-D714W9rp.cjs"),u=require("./normalize-input/index.cjs"),d=require("./chunks/truncate-decimals-CArL-IeO.cjs");require("./core/index.cjs"),exports.ADMIN_QUERY_KEYS=t.n,exports.DISCOUNT_TYPES=e.t,exports.ORDER_STATUSES=e.n,exports.SUPPORT_STATUSES=e.r,exports.buildQueryParams=n.buildQueryParams,exports.buildSortParam=a.buildSortParam,exports.cleanObject=r.cleanObject,exports.defaultCookieOptions=i.defaultCookieOptions,exports.deleteCookie=i.deleteCookie,exports.downloadBlob=s.downloadBlob,exports.getCookie=i.getCookie,exports.getCurrencySymbol=o.t,exports.getFlagFallbackUrl=c.t,exports.getFlagUnknownUrl=c.n,exports.getFlagUrl=c.r,exports.handleApiError=l.t,exports.handleFlagImageError=c.i,exports.initHandleApiError=l.n,exports.isAdminToken=t.t,exports.normalizeDecimalInput=u.normalizeDecimalInput,exports.normalizePhoneNumberInput=u.normalizePhoneNumberInput,exports.setCookie=i.setCookie,exports.truncateDecimals=d.t;

package/dist/index.js

@@ -6,8 +6,9 @@ import { defaultCookieOptions as s, deleteCookie as c, getCookie as l, setCookie
 import { buildSortParam as d } from "./build-sort-param/index.js";
 import { t as f } from "./chunks/currency-symbol-CJp1EcR5.es";
 import { downloadBlob as p } from "./download-file/index.js";
-import { n as m, t as h } from "./chunks/handle-api-error-BYygTKYM.es";
-import { normalizeDecimalInput as g, normalizePhoneNumberInput as _ } from "./normalize-input/index.js";
-import { t as v } from "./chunks/truncate-decimals-BPaTWeHm.es";
+import { i as m, n as h, r as g, t as _ } from "./chunks/flags-C5E6W9lm.es";
+import { n as v, t as y } from "./chunks/handle-api-error-BYygTKYM.es";
+import { normalizeDecimalInput as b, normalizePhoneNumberInput as x } from "./normalize-input/index.js";
+import { t as S } from "./chunks/truncate-decimals-BPaTWeHm.es";
 import "./core/index.js";
-export { r as ADMIN_QUERY_KEYS, n as DISCOUNT_TYPES, e as ORDER_STATUSES, t as SUPPORT_STATUSES, a as buildQueryParams, d as buildSortParam, o as cleanObject, s as defaultCookieOptions, c as deleteCookie, p as downloadBlob, l as getCookie, f as getCurrencySymbol, h as handleApiError, m as initHandleApiError, i as isAdminToken, g as normalizeDecimalInput, _ as normalizePhoneNumberInput, u as setCookie, v as truncateDecimals };
+export { r as ADMIN_QUERY_KEYS, n as DISCOUNT_TYPES, e as ORDER_STATUSES, t as SUPPORT_STATUSES, a as buildQueryParams, d as buildSortParam, o as cleanObject, s as defaultCookieOptions, c as deleteCookie, p as downloadBlob, l as getCookie, f as getCurrencySymbol, _ as getFlagFallbackUrl, h as getFlagUnknownUrl, g as getFlagUrl, y as handleApiError, m as handleFlagImageError, v as initHandleApiError, i as isAdminToken, b as normalizeDecimalInput, x as normalizePhoneNumberInput, u as setCookie, S as truncateDecimals };

package/package.json

@@ -2,7 +2,7 @@
 	"name": "@ptx-showcase/utils",
 	"author": "ptx-showcase",
 	"description": "Shared utilities for PTX Showcase projects",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"private": false,
 	"type": "module",
 	"license": "MIT",
@@ -77,6 +77,11 @@
 			"require": "./dist/download-file/index.cjs",
 			"types": "./dist/core/download-file/index.d.ts"
 		},
+		"./flags": {
+			"import": "./dist/flags/index.js",
+			"require": "./dist/flags/index.cjs",
+			"types": "./dist/core/flags/index.d.ts"
+		},
 		"./handle-api-error": {
 			"import": "./dist/handle-api-error/index.js",
 			"require": "./dist/handle-api-error/index.cjs",