@doswiftly/storefront-sdk 15.1.0 → 16.0.0

package/dist/core/format.js

@@ -3,47 +3,45 @@
  *
  * Pure functions for formatting prices, dates, numbers.
  * 0 runtime dependencies — works in Node.js, Edge, Deno, Bun.
+ *
+ * Locale handling:
+ * - Every formatter takes an optional `locale: string` argument. When omitted,
+ *   the runtime default (`Intl.NumberFormat().resolvedOptions().locale`) is
+ *   used — in browsers this resolves from `navigator.language`, in Node from
+ *   `LANG` / system settings.
+ * - For deterministic output (typical in a storefront with explicit i18n) the
+ *   caller should pass `locale` explicitly (`useLocale()` in Client Components,
+ *   `getLocale()` in Server Components, `next-intl`).
+ * - For per-shop locale↔currency overrides (e.g. PLN displayed in `'en-PL'`
+ *   for an English-speaking customer of a Polish shop), the storefront reads
+ *   `shop.localeToCurrencyMap` from the API and passes the chosen locale.
+ *
+ * Money precision:
+ * - `Money.amount` is a string (Decimal scalar) — values are forwarded to
+ *   `Intl.NumberFormat.format()` verbatim, without `parseFloat`. This preserves
+ *   decimal precision exactly as returned by the GraphQL API, including
+ *   currencies with non-2-digit subunits (JPY/KRW, BHD/JOD, ISK, etc.).
+ *
+ * Symbol resolution:
+ * - `getCurrencySymbol(code, locale?)` derives the symbol via
+ *   `Intl.NumberFormat.formatToParts()`. The SDK no longer ships a hardcoded
+ *   subset of currencies — every ISO 4217 currency known to the runtime is
+ *   supported, with the locale-correct symbol (`'zł'` in pl-PL, `'PLN'` in
+ *   en-US, `'€'` in de-DE, etc.).
  */
 // ============================================================================
-// CONSTANTS
-// ============================================================================
-/** Currency symbols mapping */
-export const CURRENCY_SYMBOLS = {
-    PLN: 'zł',
-    EUR: '€',
-    USD: '$',
-    GBP: '£',
-    CHF: 'CHF',
-    CZK: 'Kč',
-    SEK: 'kr',
-    NOK: 'kr',
-    DKK: 'kr',
-    JPY: '¥',
-    CNY: '¥',
-    AUD: 'A$',
-    CAD: 'C$',
-};
-/** Currency locale mapping for proper formatting */
-export const CURRENCY_LOCALES = {
-    PLN: 'pl-PL',
-    EUR: 'de-DE',
-    USD: 'en-US',
-    GBP: 'en-GB',
-    CHF: 'de-CH',
-    CZK: 'cs-CZ',
-    SEK: 'sv-SE',
-    NOK: 'nb-NO',
-    DKK: 'da-DK',
-    JPY: 'ja-JP',
-    CNY: 'zh-CN',
-    AUD: 'en-AU',
-    CAD: 'en-CA',
-};
-// ============================================================================
 // FORMATTER CACHE (avoids re-creating Intl objects on every call)
 // ============================================================================
 const numberFormatCache = new Map();
 const dateFormatCache = new Map();
+/** Runtime default locale, resolved once and reused for every `locale?`-less call. */
+let defaultLocaleCache;
+function resolveDefaultLocale() {
+    if (defaultLocaleCache === undefined) {
+        defaultLocaleCache = new Intl.NumberFormat().resolvedOptions().locale;
+    }
+    return defaultLocaleCache;
+}
 function getCurrencyFormatter(locale, currency) {
     const key = `${locale}:${currency}`;
     let fmt = numberFormatCache.get(key);
@@ -75,111 +73,136 @@ function getDateFormatter(locale, options) {
     }
     return fmt;
 }
+// Internal — forwards a Decimal string to the formatter via the string overload
+// added through declaration merging at the top of this file. Centralised here
+// so future precision-sensitive call sites have one place to depend on.
+function formatDecimalString(value, formatter) {
+    return formatter.format(value);
+}
 // ============================================================================
 // UTILITY FUNCTIONS
 // ============================================================================
 /**
- * Get currency symbol
+ * Get the currency symbol for an ISO 4217 code in the requested locale. Derived
+ * from `Intl.NumberFormat.formatToParts()` — every currency known to the
+ * runtime is supported, with the locale-correct symbol.
+ *
+ * @example
+ * getCurrencySymbol('PLN', 'pl-PL')  // => "zł"
+ * getCurrencySymbol('PLN', 'en-US')  // => "PLN" (en-US has no narrow symbol for PLN)
+ * getCurrencySymbol('EUR', 'de-DE')  // => "€"
+ * getCurrencySymbol('USD')           // depends on the runtime locale
  */
-export function getCurrencySymbol(code) {
-    return CURRENCY_SYMBOLS[code] || code;
+export function getCurrencySymbol(code, locale) {
+    const resolvedLocale = locale ?? resolveDefaultLocale();
+    try {
+        const parts = new Intl.NumberFormat(resolvedLocale, {
+            style: 'currency',
+            currency: code,
+            currencyDisplay: 'symbol',
+        }).formatToParts(0);
+        return parts.find((p) => p.type === 'currency')?.value ?? code;
+    }
+    catch {
+        return code;
+    }
 }
 // ============================================================================
 // PRICE FORMATTING
 // ============================================================================
 /**
- * Format price with currency symbol
+ * Format a `Money` value in the requested locale. `amount` is passed to
+ * `Intl.NumberFormat` as a string — no `parseFloat`, so decimal precision is
+ * preserved exactly as returned by the GraphQL API.
  *
  * @example
- * ```typescript
- * formatPrice({ amount: "99.99", currencyCode: "USD" })
- * // => "$99.99"
- * ```
+ * formatPrice({ amount: "99.99", currencyCode: "USD" }, 'en-US')  // => "$99.99"
+ * formatPrice({ amount: "12.50", currencyCode: "PLN" }, 'pl-PL')  // => "12,50 zł"
+ * formatPrice({ amount: "115.20", currencyCode: "EUR" }, 'de-DE') // => "115,20 €"
  */
-export function formatPrice(price) {
+export function formatPrice(price, locale) {
     if (!price)
         return '';
-    const amount = parseFloat(price.amount);
-    const code = price.currencyCode;
-    const locale = CURRENCY_LOCALES[code] || 'en-US';
+    const resolvedLocale = locale ?? resolveDefaultLocale();
     try {
-        return getCurrencyFormatter(locale, code).format(amount);
+        return formatDecimalString(price.amount, getCurrencyFormatter(resolvedLocale, price.currencyCode));
     }
     catch {
-        const symbol = CURRENCY_SYMBOLS[code] || code;
-        return `${amount.toFixed(2)} ${symbol}`;
+        return `${price.amount} ${price.currencyCode}`;
     }
 }
 /**
- * Format price range
+ * Format a price range (`min - max`). Returns a single price when `min` equals
+ * `max` by string comparison (no numeric conversion).
  *
  * @example
- * ```typescript
  * formatPriceRange(
  *   { amount: "10.00", currencyCode: "USD" },
- *   { amount: "50.00", currencyCode: "USD" }
+ *   { amount: "50.00", currencyCode: "USD" },
+ *   'en-US'
  * )
  * // => "$10.00 - $50.00"
- * ```
  */
-export function formatPriceRange(minPrice, maxPrice) {
+export function formatPriceRange(minPrice, maxPrice, locale) {
     if (minPrice.amount === maxPrice.amount) {
-        return formatPrice(minPrice);
+        return formatPrice(minPrice, locale);
     }
-    return `${formatPrice(minPrice)} - ${formatPrice(maxPrice)}`;
+    return `${formatPrice(minPrice, locale)} - ${formatPrice(maxPrice, locale)}`;
 }
 /**
- * Format amount with currency
+ * Format an amount with currency. Accepts a string (recommended — precision
+ * preserved) or a number. String values are forwarded to `Intl.NumberFormat`
+ * verbatim; number values pass through the standard number path.
  *
  * @example
- * ```tsx
- * const formatted = formatAmount("115.20", "EUR");
- * // => "115,20 €"
- * ```
+ * formatAmount("115.20", "EUR", 'de-DE')  // => "115,20 €"
+ * formatAmount(50, "USD", 'en-US')        // => "$50.00"
  */
-export function formatAmount(amount, currencyCode) {
-    const numAmount = typeof amount === 'string' ? parseFloat(amount) : amount;
-    const locale = CURRENCY_LOCALES[currencyCode] || 'en-US';
+export function formatAmount(amount, currencyCode, locale) {
+    const resolvedLocale = locale ?? resolveDefaultLocale();
     try {
-        return getCurrencyFormatter(locale, currencyCode).format(numAmount);
+        const formatter = getCurrencyFormatter(resolvedLocale, currencyCode);
+        return typeof amount === 'string'
+            ? formatDecimalString(amount, formatter)
+            : formatter.format(amount);
     }
     catch {
-        const symbol = CURRENCY_SYMBOLS[currencyCode] || currencyCode;
-        return `${numAmount.toFixed(2)} ${symbol}`;
+        return typeof amount === 'string'
+            ? `${amount} ${currencyCode}`
+            : `${amount.toFixed(2)} ${currencyCode}`;
     }
 }
 // ============================================================================
 // DATE FORMATTING
 // ============================================================================
 /**
- * Format date to locale string
+ * Format a date in the requested locale using a `MMM d, y`-style pattern
+ * (locale-specific month abbreviation and ordering).
  *
  * @example
- * ```typescript
- * formatDate(new Date())
- * // => "Dec 9, 2025"
- * ```
+ * formatDate(new Date(2025, 11, 9), 'en-US')  // => "Dec 9, 2025"
+ * formatDate(new Date(2025, 11, 9), 'pl-PL')  // => "9 gru 2025"
+ * formatDate('2025-12-09T12:00:00Z', 'de-DE') // => "9. Dez. 2025"
  */
-export function formatDate(date) {
+export function formatDate(date, locale) {
     const d = typeof date === 'string' ? new Date(date) : date;
-    return getDateFormatter('en-US', {
+    return getDateFormatter(locale, {
         year: 'numeric',
         month: 'short',
         day: 'numeric',
     }).format(d);
 }
 /**
- * Format date with time
+ * Format a date with time in the requested locale (month-abbreviated date plus
+ * hour and minute, 12- or 24-hour depending on locale convention).
  *
  * @example
- * ```typescript
- * formatDateTime(new Date())
- * // => "Dec 9, 2025, 10:30 PM"
- * ```
+ * formatDateTime(new Date(), 'en-US')  // => "Dec 9, 2025, 10:30 PM"
+ * formatDateTime(new Date(), 'pl-PL')  // => "9 gru 2025, 22:30"
  */
-export function formatDateTime(date) {
+export function formatDateTime(date, locale) {
     const d = typeof date === 'string' ? new Date(date) : date;
-    return getDateFormatter('en-US', {
+    return getDateFormatter(locale, {
         year: 'numeric',
         month: 'short',
         day: 'numeric',
@@ -191,25 +214,24 @@ export function formatDateTime(date) {
 // NUMBER FORMATTING
 // ============================================================================
 /**
- * Format number with thousands separator
+ * Format a number with the locale-appropriate thousands separator and decimal
+ * mark.
  *
  * @example
- * ```typescript
- * formatNumber(1234567)
- * // => "1,234,567"
- * ```
+ * formatNumber(1234567, 'en-US')  // => "1,234,567"
+ * formatNumber(1234567, 'pl-PL')  // => "1 234 567" (NBSP separator)
+ * formatNumber(1234.5, 'de-DE')   // => "1.234,5"
  */
-export function formatNumber(num) {
-    return getNumberFormatter('en-US').format(num);
+export function formatNumber(num, locale) {
+    return getNumberFormatter(locale).format(num);
 }
 /**
- * Format percentage
+ * Format a 0-1 ratio as an integer percentage. Locale-independent — uses
+ * `Math.round` and a literal `%` suffix.
  *
  * @example
- * ```typescript
- * formatPercentage(0.15)
- * // => "15%"
- * ```
+ * formatPercentage(0.15)  // => "15%"
+ * formatPercentage(0.125) // => "13%" (Math.round half-up)
  */
 export function formatPercentage(value) {
     return `${Math.round(value * 100)}%`;