first commit

plugins/library-navigator/skills/sp-i18n-formatter-display-name/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: sp-i18n-formatter-display-name
+description: Intl.DisplayNames wrapper for locale-aware language, region, script, currency, and calendar display names.
+---
+
+| Class / Function | Responsibility |
+| --- | --- |
+| `DisplayNameFormatter` | Class wrapper around `Intl.DisplayNames` with bound type, style, and fallback options |
+| `formatDisplayName` | Standalone helper for locale-aware display name formatting |
+| `formatLanguageName` / `formatRegionName` / `formatCurrencyName` / `formatScriptName` / `formatCalendarName` | Five ergonomic helpers pre-bound with canonical `type` values |
+| `clearDisplayNameCache` | Clears the per-(locale, type, style, fallback) formatter cache |
+| `recordDisplayNameFormat` / `recordDisplayNameCacheHit` / `getDisplayNameMetricsState` | OTel histogram + cache-hit counter + state accessors |
+
+**File Structure:** `packages/localization/i18n/i18n-formatter-display-name/src/{formatter,helpers,observability}/`
+
+**Sibling packages:**
+- `@suaveplan/i18n` — slim core that can wire this formatter into `defaultFormatBridge`
+- `@suaveplan/i18n-icu-parser` — consumes this formatter through the `FormatBridge` seam for ICU display-name placeholders
+- `@suaveplan/i18n-shared` — `I18N_CODES` and locale constants
+- `@suaveplan/locale-data` — provides ISO data consumed by display-name helpers
+- `@suaveplan/error` — `defineCodes` + `SuaveplanError` base
+
+**Patterns**
+
+Quick Start:
+```ts
+import { DisplayNameFormatter, formatDisplayName, formatLanguageName, formatRegionName, formatCurrencyName } from "@suaveplan/i18n-formatter-display-name";
+formatDisplayName("GB", "en-GB", { type: "region" }); // "United Kingdom"
+formatLanguageName("fr", "en-GB"); // "French"
+formatRegionName("US", "en-GB"); // "United States"
+formatCurrencyName("USD", "en-GB"); // "US Dollar"
+const f = new DisplayNameFormatter({ type: "region", style: "short" });
+f.format("DE", "en-GB"); // "Germany"
+```
+
+- **Per-locale cache:** `Intl.DisplayNames` instances cached per `(locale, type, style, fallback)` key.
+- **Subpath imports:** Deep imports via exports map (`./formatter`, `./helpers`).
+
+**Constraints**
+- Universal leaf package — depends only on `@suaveplan/i18n-shared`, `@suaveplan/error`, `@suaveplan/types`, `@opentelemetry/api`, and `zod`.
+- Zod-validated options (`DisplayNameFormatterOptionsSchema`).
+- OTel histogram (`i18n.format.display_name.duration_ms`) and cache-hit counter.
+
+**Checklist**
+- [ ] Read `src/formatter/formatter.md` for `DisplayNameFormatter` class and cache behavior
+- [ ] Read `src/helpers/helpers.md` for ergonomic helper functions
+- [ ] Verify `package.json` exports map