# 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.