next-formatter 2.0.1 → 2.0.3

package/dist/cjs/client.js

@@ -2,13 +2,206 @@
 'use strict';
 
 var react = require('react');
-var core = require('./core');
 var jsxRuntime = require('react/jsx-runtime');
 
+// src/core.ts
+var DEFAULT_RULES = {
+  compactThreshold: 1e4,
+  minimumFractionDigits: 0,
+  maximumFractionDigits: 2,
+  currencyDisplay: "narrowSymbol",
+  numberFormat: {},
+  dateFormat: { year: "numeric", month: "short", day: "2-digit" },
+  dateTimeFormat: {
+    year: "numeric",
+    month: "short",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: true
+  }
+};
+function createFormatters(config = {}) {
+  const locale = config.locale ?? "en-US";
+  const defaultCurrency = config.currency ?? "USD";
+  const fallback = config.fallback ?? "\u2014";
+  const rules = {
+    ...DEFAULT_RULES,
+    ...config.rules
+  };
+  function toNumber(value) {
+    if (value == null || value === "") return null;
+    const n = typeof value === "number" ? value : Number(value);
+    return Number.isNaN(n) ? null : n;
+  }
+  function toValidDate(value) {
+    if (value == null || value === "") return null;
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+  function isLarge(n) {
+    return Math.abs(n) >= rules.compactThreshold;
+  }
+  function normalizeICU(str) {
+    return str.replace(/\u202f/g, " ").replace(/\u00a0/g, " ").trim();
+  }
+  function alignFractionDigits(opts) {
+    const { minimumFractionDigits, maximumFractionDigits, maximumSignificantDigits, minimumSignificantDigits } = opts;
+    if (minimumFractionDigits !== void 0 && maximumFractionDigits !== void 0 && minimumFractionDigits !== maximumFractionDigits && maximumSignificantDigits === void 0 && minimumSignificantDigits === void 0) {
+      return { ...opts, minimumFractionDigits: maximumFractionDigits };
+    }
+    return opts;
+  }
+  const numberCache = /* @__PURE__ */ new Map();
+  function getNumberFormatter(options) {
+    const key = JSON.stringify({ locale, ...options });
+    if (!numberCache.has(key)) {
+      numberCache.set(key, new Intl.NumberFormat(locale, options));
+    }
+    return numberCache.get(key);
+  }
+  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto", style: "long" });
+  const formatters = {
+    /**
+     * Format a plain number.
+     * @example
+     * fmt.number(1234567)                              // "1.2M"
+     * fmt.number(1234, { notation: "standard" })       // "1,234"
+     * fmt.number(1.5678, { maximumFractionDigits: 1 }) // "1.6"
+     */
+    number(value, options = {}) {
+      const n = toNumber(value);
+      if (n == null) return fallback;
+      return normalizeICU(
+        getNumberFormatter(
+          alignFractionDigits({
+            style: "decimal",
+            notation: isLarge(n) ? "compact" : "standard",
+            minimumFractionDigits: rules.minimumFractionDigits,
+            maximumFractionDigits: rules.maximumFractionDigits,
+            ...rules.numberFormat,
+            ...options
+          })
+        ).format(n)
+      );
+    },
+    /**
+     * Format a currency value.
+     * @example
+     * fmt.currency(49900)                                // "$49.9K"
+     * fmt.currency(1234, { currency: "EUR" })            // "€1,234"
+     * fmt.currency(1234, { currencyDisplay: "code" })    // "USD 1,234"
+     * fmt.currency(1234, { minimumFractionDigits: 2 })   // "$1,234.00"
+     */
+    currency(value, options = {}) {
+      const n = toNumber(value);
+      if (n == null) return fallback;
+      const { currency: overrideCurrency, currencyDisplay, ...rest } = options;
+      return normalizeICU(
+        getNumberFormatter(
+          alignFractionDigits({
+            style: "currency",
+            currency: overrideCurrency ?? defaultCurrency,
+            notation: isLarge(n) ? "compact" : "standard",
+            minimumFractionDigits: rules.minimumFractionDigits,
+            maximumFractionDigits: rules.maximumFractionDigits,
+            currencyDisplay: currencyDisplay ?? rules.currencyDisplay,
+            ...rules.numberFormat,
+            ...rest
+          })
+        ).format(n)
+      );
+    },
+    /**
+     * Format a percentage. Input is treated as a raw percentage (50 → "50%").
+     * Uses minimumFractionDigits and maximumFractionDigits from rules.
+     * For values that would round to zero, maximumSignificantDigits is set to
+     * max(maximumFractionDigits, 4) to preserve meaningful precision.
+     * @example
+     * fmt.percentage(12.5)   // "12.50%" (with default rules min=0, max=2 → aligned to 2)
+     * fmt.percentage(0.001)  // "0.001%" (wouldBeZero → uses significantDigits)
+     * fmt.percentage(12.5, { maximumFractionDigits: 0 }) // "13%"
+     */
+    percentage(value, options = {}) {
+      const n = toNumber(value);
+      if (n == null) return fallback;
+      const normalized = n / 100;
+      const wouldBeZero = parseFloat(normalized.toFixed(3)) === 0;
+      const sigDigits = Math.max(rules.maximumFractionDigits, 4);
+      return getNumberFormatter({
+        style: "percent",
+        ...wouldBeZero ? { maximumSignificantDigits: sigDigits } : alignFractionDigits({
+          minimumFractionDigits: rules.minimumFractionDigits,
+          maximumFractionDigits: rules.maximumFractionDigits
+        }),
+        ...options
+      }).format(normalized);
+    },
+    /**
+     * Format a duration in seconds. Pure math — no Intl, no ICU risk.
+     * @example
+     * fmt.duration(150)  // "2m 30s"
+     * fmt.duration(45)   // "45s"
+     */
+    duration(value) {
+      const n = toNumber(value);
+      if (n == null) return fallback;
+      const mins = Math.floor(n / 60);
+      const secs = n % 60;
+      return mins > 0 ? `${mins}m ${secs}s` : `${secs}s`;
+    },
+    /**
+     * Format a date.
+     * @example
+     * fmt.date("2024-01-15")                        // "Jan 15, 2024"
+     * fmt.date("2024-01-15", { dateStyle: "full" }) // "Monday, January 15, 2024"
+     */
+    date(value, options = {}) {
+      const date = toValidDate(value);
+      if (!date) return fallback;
+      const resolvedOptions = options.dateStyle ? options : { ...rules.dateFormat, ...options };
+      return normalizeICU(new Intl.DateTimeFormat(locale, resolvedOptions).format(date));
+    },
+    dateTime(value, options = {}) {
+      const date = toValidDate(value);
+      if (!date) return fallback;
+      const resolvedOptions = options.dateStyle || options.timeStyle ? options : { ...rules.dateTimeFormat, ...options };
+      return normalizeICU(new Intl.DateTimeFormat(locale, resolvedOptions).format(date));
+    },
+    /**
+     * Format a date as relative time.
+     * Always pass an explicit `now` timestamp — this ensures consistent
+     * output whether called from a server or client component.
+     * @example
+     * const now = Date.now();
+     * fmt.relativeTime("2024-01-15", now) // "3 months ago"
+     */
+    relativeTime(value, now = Date.now()) {
+      const date = toValidDate(value);
+      if (!date) return fallback;
+      const diffSec = Math.round((date.getTime() - now) / 1e3);
+      const abs = Math.abs(diffSec);
+      if (abs < 60) return rtf.format(diffSec, "second");
+      const min = Math.round(diffSec / 60);
+      if (Math.abs(min) < 60) return rtf.format(min, "minute");
+      const hr = Math.round(min / 60);
+      if (Math.abs(hr) < 24) return rtf.format(hr, "hour");
+      const day = Math.round(hr / 24);
+      if (Math.abs(day) < 7) return rtf.format(day, "day");
+      const week = Math.round(day / 7);
+      if (Math.abs(week) < 4) return rtf.format(week, "week");
+      const month = Math.round(day / 30);
+      if (Math.abs(month) < 12) return rtf.format(month, "month");
+      const year = Math.round(day / 365);
+      return rtf.format(year, "year");
+    }
+  };
+  return formatters;
+}
 var FormatterContext = react.createContext(null);
 function FormattersProvider({ config, children }) {
   const formatters = react.useMemo(
-    () => core.createFormatters(config),
+    () => createFormatters(config),
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [config.locale, config.currency, config.fallback, JSON.stringify(config.rules)]
   );

package/dist/cjs/server.js

@@ -1,20 +1,245 @@
 'use strict';
 
-var client = require('./client');
-var core = require('./core');
-var create = require('./create');
+var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 
-// src/server.tsx
+// src/client.tsx
+
+// src/core.ts
+var DEFAULT_RULES = {
+  compactThreshold: 1e4,
+  minimumFractionDigits: 0,
+  maximumFractionDigits: 2,
+  currencyDisplay: "narrowSymbol",
+  numberFormat: {},
+  dateFormat: { year: "numeric", month: "short", day: "2-digit" },
+  dateTimeFormat: {
+    year: "numeric",
+    month: "short",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: true
+  }
+};
+function createFormatters(config = {}) {
+  const locale = config.locale ?? "en-US";
+  const defaultCurrency = config.currency ?? "USD";
+  const fallback = config.fallback ?? "\u2014";
+  const rules = {
+    ...DEFAULT_RULES,
+    ...config.rules
+  };
+  function toNumber(value) {
+    if (value == null || value === "") return null;
+    const n = typeof value === "number" ? value : Number(value);
+    return Number.isNaN(n) ? null : n;
+  }
+  function toValidDate(value) {
+    if (value == null || value === "") return null;
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+  function isLarge(n) {
+    return Math.abs(n) >= rules.compactThreshold;
+  }
+  function normalizeICU(str) {
+    return str.replace(/\u202f/g, " ").replace(/\u00a0/g, " ").trim();
+  }
+  function alignFractionDigits(opts) {
+    const { minimumFractionDigits, maximumFractionDigits, maximumSignificantDigits, minimumSignificantDigits } = opts;
+    if (minimumFractionDigits !== void 0 && maximumFractionDigits !== void 0 && minimumFractionDigits !== maximumFractionDigits && maximumSignificantDigits === void 0 && minimumSignificantDigits === void 0) {
+      return { ...opts, minimumFractionDigits: maximumFractionDigits };
+    }
+    return opts;
+  }
+  const numberCache = /* @__PURE__ */ new Map();
+  function getNumberFormatter(options) {
+    const key = JSON.stringify({ locale, ...options });
+    if (!numberCache.has(key)) {
+      numberCache.set(key, new Intl.NumberFormat(locale, options));
+    }
+    return numberCache.get(key);
+  }
+  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto", style: "long" });
+  const formatters = {
+    /**
+     * Format a plain number.
+     * @example
+     * fmt.number(1234567)                              // "1.2M"
+     * fmt.number(1234, { notation: "standard" })       // "1,234"
+     * fmt.number(1.5678, { maximumFractionDigits: 1 }) // "1.6"
+     */
+    number(value, options = {}) {
+      const n = toNumber(value);
+      if (n == null) return fallback;
+      return normalizeICU(
+        getNumberFormatter(
+          alignFractionDigits({
+            style: "decimal",
+            notation: isLarge(n) ? "compact" : "standard",
+            minimumFractionDigits: rules.minimumFractionDigits,
+            maximumFractionDigits: rules.maximumFractionDigits,
+            ...rules.numberFormat,
+            ...options
+          })
+        ).format(n)
+      );
+    },
+    /**
+     * Format a currency value.
+     * @example
+     * fmt.currency(49900)                                // "$49.9K"
+     * fmt.currency(1234, { currency: "EUR" })            // "€1,234"
+     * fmt.currency(1234, { currencyDisplay: "code" })    // "USD 1,234"
+     * fmt.currency(1234, { minimumFractionDigits: 2 })   // "$1,234.00"
+     */
+    currency(value, options = {}) {
+      const n = toNumber(value);
+      if (n == null) return fallback;
+      const { currency: overrideCurrency, currencyDisplay, ...rest } = options;
+      return normalizeICU(
+        getNumberFormatter(
+          alignFractionDigits({
+            style: "currency",
+            currency: overrideCurrency ?? defaultCurrency,
+            notation: isLarge(n) ? "compact" : "standard",
+            minimumFractionDigits: rules.minimumFractionDigits,
+            maximumFractionDigits: rules.maximumFractionDigits,
+            currencyDisplay: currencyDisplay ?? rules.currencyDisplay,
+            ...rules.numberFormat,
+            ...rest
+          })
+        ).format(n)
+      );
+    },
+    /**
+     * Format a percentage. Input is treated as a raw percentage (50 → "50%").
+     * Uses minimumFractionDigits and maximumFractionDigits from rules.
+     * For values that would round to zero, maximumSignificantDigits is set to
+     * max(maximumFractionDigits, 4) to preserve meaningful precision.
+     * @example
+     * fmt.percentage(12.5)   // "12.50%" (with default rules min=0, max=2 → aligned to 2)
+     * fmt.percentage(0.001)  // "0.001%" (wouldBeZero → uses significantDigits)
+     * fmt.percentage(12.5, { maximumFractionDigits: 0 }) // "13%"
+     */
+    percentage(value, options = {}) {
+      const n = toNumber(value);
+      if (n == null) return fallback;
+      const normalized = n / 100;
+      const wouldBeZero = parseFloat(normalized.toFixed(3)) === 0;
+      const sigDigits = Math.max(rules.maximumFractionDigits, 4);
+      return getNumberFormatter({
+        style: "percent",
+        ...wouldBeZero ? { maximumSignificantDigits: sigDigits } : alignFractionDigits({
+          minimumFractionDigits: rules.minimumFractionDigits,
+          maximumFractionDigits: rules.maximumFractionDigits
+        }),
+        ...options
+      }).format(normalized);
+    },
+    /**
+     * Format a duration in seconds. Pure math — no Intl, no ICU risk.
+     * @example
+     * fmt.duration(150)  // "2m 30s"
+     * fmt.duration(45)   // "45s"
+     */
+    duration(value) {
+      const n = toNumber(value);
+      if (n == null) return fallback;
+      const mins = Math.floor(n / 60);
+      const secs = n % 60;
+      return mins > 0 ? `${mins}m ${secs}s` : `${secs}s`;
+    },
+    /**
+     * Format a date.
+     * @example
+     * fmt.date("2024-01-15")                        // "Jan 15, 2024"
+     * fmt.date("2024-01-15", { dateStyle: "full" }) // "Monday, January 15, 2024"
+     */
+    date(value, options = {}) {
+      const date = toValidDate(value);
+      if (!date) return fallback;
+      const resolvedOptions = options.dateStyle ? options : { ...rules.dateFormat, ...options };
+      return normalizeICU(new Intl.DateTimeFormat(locale, resolvedOptions).format(date));
+    },
+    dateTime(value, options = {}) {
+      const date = toValidDate(value);
+      if (!date) return fallback;
+      const resolvedOptions = options.dateStyle || options.timeStyle ? options : { ...rules.dateTimeFormat, ...options };
+      return normalizeICU(new Intl.DateTimeFormat(locale, resolvedOptions).format(date));
+    },
+    /**
+     * Format a date as relative time.
+     * Always pass an explicit `now` timestamp — this ensures consistent
+     * output whether called from a server or client component.
+     * @example
+     * const now = Date.now();
+     * fmt.relativeTime("2024-01-15", now) // "3 months ago"
+     */
+    relativeTime(value, now = Date.now()) {
+      const date = toValidDate(value);
+      if (!date) return fallback;
+      const diffSec = Math.round((date.getTime() - now) / 1e3);
+      const abs = Math.abs(diffSec);
+      if (abs < 60) return rtf.format(diffSec, "second");
+      const min = Math.round(diffSec / 60);
+      if (Math.abs(min) < 60) return rtf.format(min, "minute");
+      const hr = Math.round(min / 60);
+      if (Math.abs(hr) < 24) return rtf.format(hr, "hour");
+      const day = Math.round(hr / 24);
+      if (Math.abs(day) < 7) return rtf.format(day, "day");
+      const week = Math.round(day / 7);
+      if (Math.abs(week) < 4) return rtf.format(week, "week");
+      const month = Math.round(day / 30);
+      if (Math.abs(month) < 12) return rtf.format(month, "month");
+      const year = Math.round(day / 365);
+      return rtf.format(year, "year");
+    }
+  };
+  return formatters;
+}
+var FormatterContext = react.createContext(null);
+function FormattersProvider({ config, children }) {
+  const formatters = react.useMemo(
+    () => createFormatters(config),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [config.locale, config.currency, config.fallback, JSON.stringify(config.rules)]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(FormatterContext.Provider, { value: formatters, children });
+}
+
+// src/create.ts
+async function resolveLocale(resolver, defaultLocale) {
+  const resolved = await resolver?.();
+  if (resolved) return resolved;
+  if (defaultLocale) return defaultLocale;
+  try {
+    const { headers } = await import('next/headers');
+    const h = await headers();
+    const acceptLanguage = h.get("accept-language");
+    if (acceptLanguage) {
+      const locale = acceptLanguage.split(",")[0]?.trim().split(";")[0]?.trim();
+      if (locale) return locale;
+    }
+  } catch {
+  }
+  return "en-US";
+}
+async function resolveCurrency(resolver, defaultCurrency) {
+  const resolved = await resolver?.();
+  if (resolved) return resolved;
+  return defaultCurrency ?? "USD";
+}
 async function NextFormatterProvider({ config = {}, children }) {
-  const locale = await create.resolveLocale(config.getLocale, config.locale);
-  const currency = await create.resolveCurrency(config.getCurrency, config.currency);
-  return /* @__PURE__ */ jsxRuntime.jsx(client.FormattersProvider, { config: { locale, currency, fallback: config.fallback, rules: config.rules }, children });
+  const locale = await resolveLocale(config.getLocale, config.locale);
+  const currency = await resolveCurrency(config.getCurrency, config.currency);
+  return /* @__PURE__ */ jsxRuntime.jsx(FormattersProvider, { config: { locale, currency, fallback: config.fallback, rules: config.rules }, children });
 }
 async function getFormatter(config = {}) {
-  const locale = await create.resolveLocale(config.getLocale, config.locale);
-  const currency = await create.resolveCurrency(config.getCurrency, config.currency);
-  return core.createFormatters({
+  const locale = await resolveLocale(config.getLocale, config.locale);
+  const currency = await resolveCurrency(config.getCurrency, config.currency);
+  return createFormatters({
     locale,
     currency,
     fallback: config.fallback,

package/dist/esm/client.mjs

@@ -1,8 +1,201 @@
 "use client";
 import { createContext, useMemo, useContext } from 'react';
-import { createFormatters } from './core';
 import { jsx } from 'react/jsx-runtime';
 
+// src/core.ts
+var DEFAULT_RULES = {
+  compactThreshold: 1e4,
+  minimumFractionDigits: 0,
+  maximumFractionDigits: 2,
+  currencyDisplay: "narrowSymbol",
+  numberFormat: {},
+  dateFormat: { year: "numeric", month: "short", day: "2-digit" },
+  dateTimeFormat: {
+    year: "numeric",
+    month: "short",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: true
+  }
+};
+function createFormatters(config = {}) {
+  const locale = config.locale ?? "en-US";
+  const defaultCurrency = config.currency ?? "USD";
+  const fallback = config.fallback ?? "\u2014";
+  const rules = {
+    ...DEFAULT_RULES,
+    ...config.rules
+  };
+  function toNumber(value) {
+    if (value == null || value === "") return null;
+    const n = typeof value === "number" ? value : Number(value);
+    return Number.isNaN(n) ? null : n;
+  }
+  function toValidDate(value) {
+    if (value == null || value === "") return null;
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+  function isLarge(n) {
+    return Math.abs(n) >= rules.compactThreshold;
+  }
+  function normalizeICU(str) {
+    return str.replace(/\u202f/g, " ").replace(/\u00a0/g, " ").trim();
+  }
+  function alignFractionDigits(opts) {
+    const { minimumFractionDigits, maximumFractionDigits, maximumSignificantDigits, minimumSignificantDigits } = opts;
+    if (minimumFractionDigits !== void 0 && maximumFractionDigits !== void 0 && minimumFractionDigits !== maximumFractionDigits && maximumSignificantDigits === void 0 && minimumSignificantDigits === void 0) {
+      return { ...opts, minimumFractionDigits: maximumFractionDigits };
+    }
+    return opts;
+  }
+  const numberCache = /* @__PURE__ */ new Map();
+  function getNumberFormatter(options) {
+    const key = JSON.stringify({ locale, ...options });
+    if (!numberCache.has(key)) {
+      numberCache.set(key, new Intl.NumberFormat(locale, options));
+    }
+    return numberCache.get(key);
+  }
+  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto", style: "long" });
+  const formatters = {
+    /**
+     * Format a plain number.
+     * @example
+     * fmt.number(1234567)                              // "1.2M"
+     * fmt.number(1234, { notation: "standard" })       // "1,234"
+     * fmt.number(1.5678, { maximumFractionDigits: 1 }) // "1.6"
+     */
+    number(value, options = {}) {
+      const n = toNumber(value);
+      if (n == null) return fallback;
+      return normalizeICU(
+        getNumberFormatter(
+          alignFractionDigits({
+            style: "decimal",
+            notation: isLarge(n) ? "compact" : "standard",
+            minimumFractionDigits: rules.minimumFractionDigits,
+            maximumFractionDigits: rules.maximumFractionDigits,
+            ...rules.numberFormat,
+            ...options
+          })
+        ).format(n)
+      );
+    },
+    /**
+     * Format a currency value.
+     * @example
+     * fmt.currency(49900)                                // "$49.9K"
+     * fmt.currency(1234, { currency: "EUR" })            // "€1,234"
+     * fmt.currency(1234, { currencyDisplay: "code" })    // "USD 1,234"
+     * fmt.currency(1234, { minimumFractionDigits: 2 })   // "$1,234.00"
+     */
+    currency(value, options = {}) {
+      const n = toNumber(value);
+      if (n == null) return fallback;
+      const { currency: overrideCurrency, currencyDisplay, ...rest } = options;
+      return normalizeICU(
+        getNumberFormatter(
+          alignFractionDigits({
+            style: "currency",
+            currency: overrideCurrency ?? defaultCurrency,
+            notation: isLarge(n) ? "compact" : "standard",
+            minimumFractionDigits: rules.minimumFractionDigits,
+            maximumFractionDigits: rules.maximumFractionDigits,
+            currencyDisplay: currencyDisplay ?? rules.currencyDisplay,
+            ...rules.numberFormat,
+            ...rest
+          })
+        ).format(n)
+      );
+    },
+    /**
+     * Format a percentage. Input is treated as a raw percentage (50 → "50%").
+     * Uses minimumFractionDigits and maximumFractionDigits from rules.
+     * For values that would round to zero, maximumSignificantDigits is set to
+     * max(maximumFractionDigits, 4) to preserve meaningful precision.
+     * @example
+     * fmt.percentage(12.5)   // "12.50%" (with default rules min=0, max=2 → aligned to 2)
+     * fmt.percentage(0.001)  // "0.001%" (wouldBeZero → uses significantDigits)
+     * fmt.percentage(12.5, { maximumFractionDigits: 0 }) // "13%"
+     */
+    percentage(value, options = {}) {
+      const n = toNumber(value);
+      if (n == null) return fallback;
+      const normalized = n / 100;
+      const wouldBeZero = parseFloat(normalized.toFixed(3)) === 0;
+      const sigDigits = Math.max(rules.maximumFractionDigits, 4);
+      return getNumberFormatter({
+        style: "percent",
+        ...wouldBeZero ? { maximumSignificantDigits: sigDigits } : alignFractionDigits({
+          minimumFractionDigits: rules.minimumFractionDigits,
+          maximumFractionDigits: rules.maximumFractionDigits
+        }),
+        ...options
+      }).format(normalized);
+    },
+    /**
+     * Format a duration in seconds. Pure math — no Intl, no ICU risk.
+     * @example
+     * fmt.duration(150)  // "2m 30s"
+     * fmt.duration(45)   // "45s"
+     */
+    duration(value) {
+      const n = toNumber(value);
+      if (n == null) return fallback;
+      const mins = Math.floor(n / 60);
+      const secs = n % 60;
+      return mins > 0 ? `${mins}m ${secs}s` : `${secs}s`;
+    },
+    /**
+     * Format a date.
+     * @example
+     * fmt.date("2024-01-15")                        // "Jan 15, 2024"
+     * fmt.date("2024-01-15", { dateStyle: "full" }) // "Monday, January 15, 2024"
+     */
+    date(value, options = {}) {
+      const date = toValidDate(value);
+      if (!date) return fallback;
+      const resolvedOptions = options.dateStyle ? options : { ...rules.dateFormat, ...options };
+      return normalizeICU(new Intl.DateTimeFormat(locale, resolvedOptions).format(date));
+    },
+    dateTime(value, options = {}) {
+      const date = toValidDate(value);
+      if (!date) return fallback;
+      const resolvedOptions = options.dateStyle || options.timeStyle ? options : { ...rules.dateTimeFormat, ...options };
+      return normalizeICU(new Intl.DateTimeFormat(locale, resolvedOptions).format(date));
+    },
+    /**
+     * Format a date as relative time.
+     * Always pass an explicit `now` timestamp — this ensures consistent
+     * output whether called from a server or client component.
+     * @example
+     * const now = Date.now();
+     * fmt.relativeTime("2024-01-15", now) // "3 months ago"
+     */
+    relativeTime(value, now = Date.now()) {
+      const date = toValidDate(value);
+      if (!date) return fallback;
+      const diffSec = Math.round((date.getTime() - now) / 1e3);
+      const abs = Math.abs(diffSec);
+      if (abs < 60) return rtf.format(diffSec, "second");
+      const min = Math.round(diffSec / 60);
+      if (Math.abs(min) < 60) return rtf.format(min, "minute");
+      const hr = Math.round(min / 60);
+      if (Math.abs(hr) < 24) return rtf.format(hr, "hour");
+      const day = Math.round(hr / 24);
+      if (Math.abs(day) < 7) return rtf.format(day, "day");
+      const week = Math.round(day / 7);
+      if (Math.abs(week) < 4) return rtf.format(week, "week");
+      const month = Math.round(day / 30);
+      if (Math.abs(month) < 12) return rtf.format(month, "month");
+      const year = Math.round(day / 365);
+      return rtf.format(year, "year");
+    }
+  };
+  return formatters;
+}
 var FormatterContext = createContext(null);
 function FormattersProvider({ config, children }) {
   const formatters = useMemo(