@uxf/localize 11.122.2 → 11.122.4

package/README.md

@@ -1,53 +1,90 @@
 # @uxf/localize
+
 [![npm](https://img.shields.io/npm/v/@uxf/localize)](https://www.npmjs.com/package/@uxf/localize)
 [![size](https://img.shields.io/bundlephobia/min/@uxf/localize)](https://www.npmjs.com/package/@uxf/localize)
 [![quality](https://img.shields.io/npms-io/quality-score/@uxf/localize)](https://www.npmjs.com/package/@uxf/localize)
 [![license](https://img.shields.io/npm/l/@uxf/localize)](https://www.npmjs.com/package/@uxf/localize)
 
+Locale-aware formatting of numbers, currency amounts, percentages, dates and times, driven by per-locale config objects. Date/time handling is built on [dayjs](https://day.js.org/) (UTC + timezone plugins); number/currency formatting on [currency.js](https://currency.js.org/).
+
+## When to use
+
+Reach for `@uxf/localize` when an app needs consistent, config-driven formatting across locales. You call `createLocalize` once with your locale map and get back a provider, hooks, components and standalone functions — all sharing a single locale context.
+
+`@uxf/ui` uses the same context internally: its `UiContextProvider` mounts the shared provider with the app locale, so if you already wrap your app in `@uxf/ui`'s provider you do **not** need to mount `LocalizeProvider` again — the formatters from your `createLocalize` will read the locale set by `@uxf/ui`. Mount `LocalizeProvider` yourself only when using `@uxf/localize` standalone.
+
 ## Installation
 
 ```bash
 yarn add @uxf/localize
 ```
 
-```bash
-npm install @uxf/localize
-```
+Peer dependencies (must be installed by the consumer):
 
-## Initialize and configure package
+- `@uxf/core`, `@uxf/core-react`
+- `dayjs` `^1.11.19`
+- `react` / `react-dom` `>=18.2.0`
 
-### Configure package
+`currency.js` ships as a direct dependency.
+
+## Quick start
+
+Create the localize instance once, re-export its members, then use them across the app.
 
 ```ts
 // localize.ts
 import { createLocalize } from "@uxf/localize";
-import cs from "@uxf/localize/locale/cs"; // LocalizeConfig
-import en from "@uxf/localize/locale/en"; // LocalizeConfig
+import cs from "@uxf/localize/locale/cs";
+import en from "@uxf/localize/locale/en";
 
-export const { 
+export const {
     LocalizeProvider,
-    formatDateTime,
-    formatTime,
-    formatMoney,
+    useLocaleConfig,
     formatNumber,
+    formatMoney,
     formatPercentage,
-    useFormatDateTime,
-    useFormatTime,
-    useFormatMoney,
+    formatDateTime,
+    formatTime,
     useFormatNumber,
+    useFormatMoney,
     useFormatPercentage,
-    FormatDateTime,
-    FormatTime,
+    useFormatDateTime,
+    useFormatTime,
     FormatNumber,
     FormatMoney,
     FormatPercentage,
-} = createLocale({ cs, en });
+    FormatDateTime,
+    FormatTime,
+} = createLocalize({ cs, en });
+```
+
+`LocalizeProvider` is a plain React context provider whose `value` is the active locale key:
+
+```tsx
+// _app.tsx
+import { LocalizeProvider } from "./localize";
+
+<LocalizeProvider value="cs">{props.children}</LocalizeProvider>;
+```
+
+Use the hooks (they read the locale from context):
+
+```tsx
+import { useFormatMoney } from "./localize";
+
+function Price() {
+    const formatMoney = useFormatMoney();
+
+    return <>{formatMoney({ amount: "2000.78", currency: "CZK" })}</>; // 2 001 Kč
+}
 ```
 
-### Localize config examples
+## Configuration
+
+Each locale is a `LocalizeConfig` describing number/currency separators, currency patterns, and dayjs format strings. Seven ready-made configs ship with the package and can be imported by locale key: `cs`, `de`, `en`, `es`, `fr`, `pl`, `sk` (e.g. `import cs from "@uxf/localize/locale/cs"`). Spread a bundled config to extend or override it.
 
 ```ts
-import {DateTimes, Times, LocalizeConfig} from "@uxf/localize";
+import { DateTimes, LocalizeConfig, Times } from "@uxf/localize";
 
 const en: LocalizeConfig<DateTimes, Times> = {
     number: {
@@ -57,6 +94,7 @@ const en: LocalizeConfig<DateTimes, Times> = {
     currency: {
         thousandsSeparator: ",",
         decimalSeparator: ".",
+        // per-currency override; `#` = amount, `!` = symbol (see Gotchas)
         specialCases: {
             USD: {
                 pattern: "#\xa0$",
@@ -65,16 +103,16 @@ const en: LocalizeConfig<DateTimes, Times> = {
         },
     },
     dateTime: {
-        timeShort: "H:mm A",
-        timeFull: "H:mm:ss A",
+        timeShort: "h:mm A",
+        timeFull: "h:mm:ss A",
         dateShort: "M/D/YY",
         dateMedium: "M/D/YYYY",
         dateLong: "MMMM D. YYYY",
         dateShortNoYear: "M/D",
         dateLongNoYear: "MMMM D.",
-        dateTimeShort: "M/D/YY H:mm A",
-        dateTimeMedium: "M/D/YYYY H:mm A",
-        dateTimeLong: "MMMM D. YYYY H:mm:ss A",
+        dateTimeShort: "M/D/YY h:mm A",
+        dateTimeMedium: "M/D/YYYY h:mm A",
+        dateTimeLong: "MMMM D. YYYY h:mm:ss A",
     },
     time: {
         short: "h:mm A",
@@ -112,93 +150,164 @@ const cs: LocalizeConfig<DateTimes, Times> = {
     time: {
         short: "H:mm",
         long: "H:mm:ss",
-    }
+    },
 };
 ```
 
-### Add LocalizeProvider to _app.tsx
+Custom `dateTime` / `time` keys are supported by widening the generics: `createLocalize<DateTimes | "custom", Times>({ ... })`.
 
-```tsx
-// _app.tsx
+## Formatters
 
-<LocalizeProvider locale="cs">{props.children}</LocalizeProvider>
-```
+All examples below assume the `cs` locale is active (via the provider). Outputs use a non-breaking space as the thousands separator, shown here as a normal space.
+
+### Number
 
-## Format number
 ```tsx
-const { useFormatNumber, FormatNumber } from "./localize";
+import { useFormatNumber, FormatNumber } from "./localize";
 
 const formatNumber = useFormatNumber();
 
-formatNumber(1000.23); // 1 000
-formatNumber(1000.23, { precision: 2 }); // 1 000,23
+formatNumber(2000.78); // 2 001         (default precision 0)
+formatNumber(2000.78, { precision: 2 }); // 2 000,78
 
-<FormatNumber value={1000.23}/>
+<FormatNumber value={2000.78} />;
 ```
 
-## Format datetime
+### Date and time
+
 ```tsx
-const { useFormatDateTime, FormatDateTime } from "./localize";
+import { useFormatDateTime, FormatDateTime } from "./localize";
 
 const formatDateTime = useFormatDateTime();
+const date = new Date("2023-07-21T07:58:35+02:00");
 
-formatDateTime(new Date('2000-01-01'), "dateShort"); // 1. 1. 20
-formatDateTime(new Date('2000-01-01'), "dateTimeMedium"); // 1. 1. 2000 00:00
-formatDateTime(new Date('2000-01-01'), "timeFull"); // 00:00:00
+formatDateTime(date, "dateShort"); // 21. 7. 23
+formatDateTime(date, "dateTimeMedium"); // 21. 7. 2023, 7:58
+formatDateTime(date, "timeFull"); // 7:58:35
 
-<FormatDateTime value={new Date('2000-01-01')} format="dateShort"/>
+<FormatDateTime format="dateShort" value={date} />;
+// the component (and the standalone function) also accept a `timeZone` prop/arg
+<FormatDateTime format="dateTimeShort" timeZone="America/New_York" value={date} />;
 ```
 
-## Format time
+### Time
+
+Formats a `TimeString` (`"HH:mm:ss"`).
+
 ```tsx
-const { useFormatTime, FormatTime } from "./localize";
+import { useFormatTime, FormatTime } from "./localize";
 
 const formatTime = useFormatTime();
 
 formatTime("07:58:35", "short"); // 7:58
-formatTime("07:58:35", "short"); // 7:58:35
+formatTime("07:58:35", "long"); // 7:58:35
 
-<FormatTime value="07:58:35" format="short"/>
+<FormatTime format="short" value="07:58:35" />;
 ```
 
-## Format money
+### Money
+
+Takes a `Money` object (`{ amount: string; currency: Currency }`).
+
 ```tsx
-const { useFormatMoney, FormatMoney } from "./localize";
+import { useFormatMoney, FormatMoney } from "./localize";
 
 const formatMoney = useFormatMoney();
 
-formatMoney({amount: 1000, currency: "CZK"}); // 1 000 Kč
-formatMoney({amount: 1000, currency: "USD"}); // 1 000 $
-formatMoney({amount: 1000.23, currency: "CZK"}, { precision: 1 }); // 1 000,2 Kč
-formatMoney({amount: 1000.23, currency: "CZK"}, { preferIsoCode: true }); // 1 000,23 CZK
-formatMoney({amount: 1000.23, currency: "CZK"}, { hideSymbol: true }); // 1 000,23
+formatMoney({ amount: "2000.78", currency: "CZK" }); // 2 001 Kč      (default precision 0)
+formatMoney({ amount: "2000.78", currency: "USD" }); // 2 001 $
+formatMoney({ amount: "2000.78", currency: "CZK" }, { precision: 1 }); // 2 000,8 Kč
+formatMoney({ amount: "2000.78", currency: "CZK" }, { precision: 1, preferIsoCode: true }); // 2 000,8 CZK
+formatMoney({ amount: "2000.78", currency: "CZK" }, { precision: 1, hideSymbol: true }); // 2 000,8
 
-<FormatMoney money={{amount: 1000, currency: "CZK"}}/>
+<FormatMoney money={{ amount: "2000.78", currency: "CZK" }} />;
 ```
 
-## Format percentage
+### Percentage
+
+Expects a ratio and multiplies it by 100. An optional `roundingType` rounds to a whole percent (`"nearest"` → `Math.round`, `"up"` → `Math.ceil`, `"down"` → `Math.floor`); pass `null` to skip rounding and control precision via options.
 
 ```tsx
-const { useFormatPercentage, FormatPercentage } from "./localize";
+import { useFormatPercentage, FormatPercentage } from "./localize";
 
 const formatPercentage = useFormatPercentage();
 
-formatPercentage(0.782); // 78,2 %
-formatPercentage(0.782, "nearest"); // 78,2 %
-formatPercentage(0.782, "up"); // 78,2 %
-formatPercentage(0.782, "down"); // 78,2 %
+formatPercentage(0.782); // 78 %          (default precision 0)
+formatPercentage(0.782, null, { precision: 2 }); // 78,20 %
+formatPercentage(0.782, "up"); // 79 %
+formatPercentage(0.788, "down"); // 78 %
 
-<FormatPercentage value={0.782} roundingType="up" />
+<FormatPercentage roundingType="up" value={0.782} />;
 ```
 
-## Format another locale
+## Formatting for an explicit locale
+
+The standalone functions take the locale as their first argument and ignore the provider context. Use them for server-side or multi-locale output.
 
 ```tsx
-const { formatNumber, formatDateTime, formatMoney, formatPercentage } from "./localize";
+import { formatNumber, formatDateTime, formatMoney, formatPercentage, formatTime } from "./localize";
+
+formatNumber("cs", 2000.78); // 2 001
+formatDateTime("cs", new Date("2023-07-21T07:58:35+02:00"), "dateMedium"); // 21. 7. 2023
+formatMoney("cs", { amount: "2000.78", currency: "CZK" }); // 2 001 Kč
+formatPercentage("cs", 0.782); // 78 %
+formatTime("cs", "07:58:35", "short"); // 7:58
+```
+
+## API
 
-formatNumber("cs", 1000.23); // 1 000
-formatDateTime("cs", new Date('2000-01-01'), "dateMedium") // 1. 1. 2000
-formatMoney("cs", 1000, "CZK") // 1 000 Kč
-formatPercentage("cs", 0.782) // 78,2 %
+Import everything from the package root: `import { createLocalize } from "@uxf/localize"`. Locale configs are deep imports: `import cs from "@uxf/localize/locale/<code>"`.
+
+### `createLocalize(config)`
+
+```ts
+createLocalize<DT extends string = DateTimes, T extends string = Times, Locales extends string = string>(
+    config: LocalizeConfigMap<DT, T, Locales>,
+): CreateLocalizeReturn<DT, T, Locales>;
 ```
 
+Returns an object with the following members:
+
+| Member | Signature | Notes |
+| --- | --- | --- |
+| `LocalizeProvider` | `Provider<string>` | React context provider; `value` is the active locale key. |
+| `useLocaleConfig` | `() => LocalizeConfig<DT, T>` | Returns the config for the current locale. |
+| `formatNumber` | `(locale, value, options?) => string` | `options: { precision? }`. |
+| `useFormatNumber` | `() => (value, options?) => string` | Locale from context. |
+| `FormatNumber` | `FC<{ value; options? }>` | |
+| `formatMoney` | `(locale, money, options?) => string` | `options: { hideSymbol?, precision?, preferIsoCode? }`. |
+| `useFormatMoney` | `() => (money, options?) => string` | Locale from context. |
+| `FormatMoney` | `FC<{ money; options? }>` | |
+| `formatPercentage` | `(locale, value, roundingType?, options?) => string` | `roundingType: "nearest" \| "up" \| "down" \| null`. |
+| `useFormatPercentage` | `() => (value, roundingType?, options?) => string` | Locale from context. |
+| `FormatPercentage` | `FC<{ value; roundingType?; options? }>` | |
+| `formatDateTime` | `(locale, value, format, timeZone?) => string` | `value: DateValue`; default `timeZone` is `Europe/Prague`. |
+| `useFormatDateTime` | `() => (value, format) => string` | No `timeZone` param (fixed to default). |
+| `FormatDateTime` | `FC<{ value; format; timeZone? }>` | |
+| `formatTime` | `(locale, value, format) => string` | `value: TimeString`. |
+| `useFormatTime` | `() => (value, format) => string` | Locale from context. |
+| `FormatTime` | `FC<{ value; format }>` | |
+
+### Exported types
+
+`export type * from "./src/types"` exposes, among others: `LocalizeConfig`, `LocalizeConfigMap`, `CreateLocalizeReturn`, `DateTimes`, `Times`, `Currency`, `Money`, `TimeZone`, `RoundingType`, `FormatMoneyPattern`, and the per-formatter `*Options` / `*Function` / `*Component` types.
+
+### `_LocalizeProvider` (internal)
+
+`_LocalizeProvider` is exported from the package root but is **internal** — it is the shared global locale context, consumed by `@uxf/ui`'s `UiContextProvider`. Application code should use the `LocalizeProvider` returned by `createLocalize` (it is the same context object). The two provide into the same context, so mounting either sets the locale for all formatters.
+
+## Gotchas
+
+- **Provider prop is `value`, not `locale`** — `LocalizeProvider` is a raw React context provider: `<LocalizeProvider value="cs">`.
+- **Default precision is `0`** for number, money and percentage. Pass `{ precision }` to show decimals; values are rounded (via currency.js), not truncated.
+- **`Money.amount` is a string** (`{ amount: "2000.78", currency: "CZK" }`), not a number.
+- **`formatPercentage` takes a ratio** (`0.782` → `78 %`); it multiplies by 100. A `roundingType` rounds to a whole percent before formatting, so decimals only appear when `roundingType` is `null`/omitted and `precision` is set.
+- **Time zone defaults to `Europe/Prague`** for date/time formatting. The `useFormatDateTime` hook is fixed to that default; to override, use the standalone `formatDateTime(locale, value, format, timeZone)` or the `FormatDateTime` component's `timeZone` prop.
+- **Date-only strings** (`"YYYY-MM-DD"`) are parsed as midnight in the target time zone, while `Date` instances represent a concrete instant and are shifted into that zone — the same wall-clock string can render differently depending on the input form.
+- **Currency patterns** use currency.js placeholders: `#` = amount, `!` = symbol. Built-in defaults exist for `EUR` and `USD`; `specialCases` in the config override per currency; otherwise a plain `# <symbol>` pattern is used, and `preferIsoCode` forces the ISO code instead of the symbol.
+- **Separators are non-breaking spaces** in some locales (e.g. `cs`), so `"2 001"` contains ` `, not a regular space.
+
+## Links
+
+- [npm package](https://www.npmjs.com/package/@uxf/localize)
+- Related: `@uxf/core` (`Money`, `Currency`, date types), `@uxf/core-react` (global context), `@uxf/ui` (mounts the shared locale provider).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@uxf/localize",
-    "version": "11.122.2",
+    "version": "11.122.4",
     "description": "",
     "main": "index.js",
     "scripts": {