first commit

docs/localization/i18n/i18n-formatter-display-name/src/helpers/helpers.md

@@ -0,0 +1,98 @@
+# Display-name ergonomic helpers
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The five ergonomic helpers (`formatLanguageName`, `formatRegionName`,
+`formatCurrencyName`, `formatScriptName`, `formatCalendarName`)
+pre-bind `formatDisplayName` with the required `type` discriminant so
+consumers don't have to remember the discriminant string. Each helper
+forwards an optional `style` argument to the underlying call.
+
+The helpers exist because `Intl.DisplayNames` requires the caller to
+pass `{ type: "<x>" }` on every call — across a real-world UI codebase
+that adds noise and creates a chance to typo a discriminant. The
+helpers eliminate both.
+
+## Features
+
+- `formatLanguageName(code, locale, style?)` — pre-binds `type: "language"`
+- `formatRegionName(code, locale, style?)` — pre-binds `type: "region"`
+- `formatCurrencyName(code, locale, style?)` — pre-binds `type: "currency"`
+- `formatScriptName(code, locale, style?)` — pre-binds `type: "script"`
+- `formatCalendarName(code, locale, style?)` — pre-binds `type: "calendar"`
+- All accept the optional `style` parameter (`"long" | "short" | "narrow"`); when omitted, the underlying `formatDisplayName` defaults to `"long"`.
+
+## Usage: Basic Example
+
+```ts
+import {
+    formatLanguageName,
+    formatRegionName,
+    formatCurrencyName,
+} from "@suaveplan/i18n-formatter-display-name";
+
+formatLanguageName("fr", "en-GB"); // "French"
+formatRegionName("GB", "en-GB"); // "United Kingdom"
+formatCurrencyName("USD", "en-GB"); // "US Dollar"
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    formatLanguageName,
+    formatRegionName,
+    formatScriptName,
+} from "@suaveplan/i18n-formatter-display-name";
+
+// Build a locale picker — language + region in the user's locale.
+const locales = ["fr-FR", "en-GB", "ja-JP", "zh-Hans-CN"];
+const userLocale = "en-GB";
+
+const labels = locales.map((tag) => {
+    const [lang, ...rest] = tag.split("-");
+    const region = rest[rest.length - 1];
+    const lname = formatLanguageName(lang, userLocale);
+    const rname = region ? formatRegionName(region, userLocale) : "";
+    return rname ? `${lname} (${rname})` : lname;
+});
+// ["French (France)", "English (United Kingdom)", "Japanese (Japan)", "Chinese (China)"]
+
+// Render script name in narrow style for compact UIs.
+const narrow = formatScriptName("Latn", "en-GB", "narrow");
+```
+
+## API Reference
+
+Every helper has the signature
+`(code: string, locale: string, style?: DisplayNameStyle) => string`.
+
+- **`formatLanguageName(code, locale, style?)`** — Returns the language
+  display name. `code` is a BCP-47 language subtag (`"fr"`, `"zh"`,
+  `"en-GB"` is also accepted by the underlying `Intl.DisplayNames`).
+- **`formatRegionName(code, locale, style?)`** — Returns the region
+  display name. `code` is an ISO 3166-1 alpha-2 region code (`"GB"`,
+  `"US"`).
+- **`formatCurrencyName(code, locale, style?)`** — Returns the currency
+  display name. `code` is an ISO 4217 currency code (`"USD"`,
+  `"EUR"`).
+- **`formatScriptName(code, locale, style?)`** — Returns the script
+  display name. `code` is an ISO 15924 script code (`"Latn"`,
+  `"Cyrl"`).
+- **`formatCalendarName(code, locale, style?)`** — Returns the calendar
+  display name. `code` is a Unicode calendar identifier (`"gregory"`,
+  `"buddhist"`, `"islamic"`).
+
+Every helper throws `I18nError(UNSUPPORTED_LOCALE)` on a malformed
+locale tag (matching the standalone semantics).
+
+## Implementation Notes
+
+- Each helper is a one-line wrapper around `formatDisplayName`. There
+  is no separate cache layer — the underlying `formatDisplayName`
+  cache by `(locale, type, style, fallback)` covers all five.
+- The helpers are pure functions with no shared state.