Initial Commit

packages/localization/i18n/i18n-formatter-number/src/helpers/helpers.md

@@ -0,0 +1,70 @@
+# Number Helper Formatters
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Pre-bound shortcuts over `formatNumber` and `Intl.NumberFormat` for the three most-asked number-formatting shapes: percentages, compact notation ("1.2K"), and units of measurement ("12 km/h"). Saves callers from spelling out the full options bag every time.
+
+The percent and compact helpers route through `formatNumber`, so they benefit from its Zod validation and per-(locale, options-hash) cache. `formatUnit` calls `Intl.NumberFormat` directly because `style: 'unit'` is intentionally outside the narrow `NumberFormatterStyle` union.
+
+## Features
+
+- `formatPercent(value, locale, options?)` — `style: 'percent'` shortcut
+- `formatCompact(value, locale, options?)` — `notation: 'compact'` shortcut ("1.2K", "1.2M")
+- `formatUnit(value, unit, locale, options?)` — `style: 'unit'` shortcut for measurement units
+- `unit` is any `Intl.NumberFormat` unit identifier (`'kilometer-per-hour'`, `'celsius'`, `'megabyte'`, ...)
+- `formatUnit` style is `'short' | 'long' | 'narrow'` (default `'short'`)
+
+## Usage: Basic Example
+
+```typescript
+import {
+  formatCompact,
+  formatPercent,
+  formatUnit,
+} from "@suaveplan/i18n-formatter-number/helpers";
+
+formatPercent(0.255, "en-US", { maximumFractionDigits: 1 }); // → "25.5%"
+formatCompact(1234, "en-US");                                // → "1.2K"
+formatUnit(12, "kilometer-per-hour", "en-US");               // → "12 km/h"
+formatUnit(20, "celsius", "en-US", { style: "long" });       // → "20 degrees Celsius"
+```
+
+## Usage: Advanced Example — Stat Block
+
+```typescript
+import {
+  formatCompact,
+  formatPercent,
+  formatUnit,
+} from "@suaveplan/i18n-formatter-number/helpers";
+
+const stats = {
+  cpuLoad: formatPercent(load, locale),
+  memUsed: formatUnit(memBytes, "megabyte", locale, { style: "long" }),
+  reqsPerMinute: formatCompact(reqs, locale),
+};
+```
+
+## API Reference
+
+### `formatPercent(value, locale, options?)`
+
+Pre-bound `formatNumber({ style: 'percent', ...options })`. Note that `value` is the proportion (0.25 → "25%"), not the percentage (25).
+
+### `formatCompact(value, locale, options?)`
+
+Pre-bound `formatNumber({ notation: 'compact', ...options })`. Defaults to `compactDisplay: 'short'` from `Intl.NumberFormat`. Override via `options.compactDisplay`.
+
+### `formatUnit(value, unit, locale, options?)`
+
+Locale-aware unit formatting. The `unit` is one of `Intl.NumberFormat`'s sanctioned units; the [Intl.NumberFormat units list](https://tc39.es/ecma402/#table-sanctioned-single-unit-identifiers) is authoritative. Composite units use `-per-` joiner (`'meter-per-second'`).
+
+## Implementation Notes
+
+`formatUnit` does NOT route through `formatNumber` because adding `style: 'unit'` would require widening `NumberFormatterStyle` and `NumberFormatterOptions` to include the unit-specific options. Keeping `formatUnit` as a thin direct wrapper preserves the `formatNumber` surface's stability.
+
+Compact notation uses the runtime's locale-specific compact patterns. For en-US that's `'1.2K'`, `'1.2M'`, `'1.2B'`; other locales use locale-correct abbreviations (e.g. `'1,2 万'` for ja-JP).