first commit

docs/localization/i18n/i18n-formatter-list/README.md

@@ -0,0 +1,107 @@
+# @suaveplan/i18n-formatter-list - Locale-aware list joining backed by Intl.ListFormat. Class wrapper + standalone helper + ergonomic helpers (formatConjunction, formatDisjunction), Zod-validated options, per-(locale, style, type) cache, OTel histogram + cache-hit counter. Wave 3 of the @suaveplan/i18n modular split.
+
+## Summary
+
+Locale-aware list joining backed by `Intl.ListFormat`. Wave 3 of the
+14-package i18n modular split. Provides both a class
+(`ListFormatter`) and a standalone helper (`formatList`) plus
+ergonomic shortcuts (`formatConjunction`, `formatDisjunction`) on
+top of a per-`(locale, style, type)` cache, Zod-validated options,
+and the canonical OTel histogram + cache-hit counter that every
+Wave 3 formatter package emits.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [formatter](./src/formatter/formatter.md) — Locale-aware list joining backed by `Intl.ListFormat`. Joins an array of strings with the locale-correct connector (`"a…
+  - [formatter](./src/formatter/formatter.md) — Locale-aware list joining backed by `Intl.ListFormat`. Joins an array of strings with the locale-correct connector (`"a…
+- [helpers](./src/helpers/helpers.md) — Pre-bound shortcuts over `formatList` for the two most common list-formatting shapes: conjunction joining ("a, b, and c…
+  - [helpers](./src/helpers/helpers.md) — Pre-bound shortcuts over `formatList` for the two most common list-formatting shapes: conjunction joining ("a, b, and c…
+- [observability](./src/observability/observability.md) — Per-package OpenTelemetry instruments for `@suaveplan/i18n-formatter-list`. Exposes a histogram (`i18n.format.list.dura…
+  - [observability](./src/observability/observability.md) — Per-package OpenTelemetry instruments for `@suaveplan/i18n-formatter-list`. Exposes a histogram (`i18n.format.list.dura…
+<!-- end:auto-docs -->
+
+## Why this exists
+
+Each `Intl.*` wrapper lives in its own sibling package so consumers
+can pull only the formatters they actually use. This package is the
+list-formatter slice of Wave 3. The monolith ships only a thin
+standalone helper and per-cache module — this package brings the
+canonical Wave 3 shape on top: class wrapper for symmetry with
+`NumberFormatter`, Zod schema validating options at the boundary,
+mapping of Zod failure to `INVALID_FORMATTER_OPTIONS`, and OTel
+emission for parity with the rest of the family.
+
+## Install
+
+```bash
+bun add @suaveplan/i18n-formatter-list
+```
+
+## Quick Start
+
+```ts
+import {
+    formatConjunction,
+    formatDisjunction,
+    formatList,
+    ListFormatter,
+} from "@suaveplan/i18n-formatter-list";
+
+formatList(["apples", "oranges", "bananas"], "en-US");
+// → "apples, oranges, and bananas"
+
+formatList(["apples", "oranges"], "en-US", { type: "disjunction" });
+// → "apples or oranges"
+
+formatConjunction(["a", "b", "c"], "en-GB");  // → "a, b, and c"
+formatDisjunction(["x", "y"], "en-GB");       // → "x or y"
+
+const compact = new ListFormatter({ style: "short", type: "unit" });
+compact.format(["mon", "tue", "wed"], "en-US"); // → "mon, tue, wed"
+```
+
+## Modules
+
+| Subpath | Description |
+|---|---|
+| `@suaveplan/i18n-formatter-list` | Root barrel — class + standalone + helpers + observability |
+| `@suaveplan/i18n-formatter-list/formatter` | `ListFormatter`, `formatList`, `clearListFormatterCache`, types, schema |
+| `@suaveplan/i18n-formatter-list/helpers` | `formatConjunction`, `formatDisjunction` only |
+
+## Modules Documentation
+
+- [formatter.md](src/formatter.md) — `ListFormatter` class + `formatList`
+- [helpers.md](src/helpers.md) — `formatConjunction`, `formatDisjunction`
+- [observability.md](src/observability.md) — OTel histogram + cache-hit counter
+
+## Public Surface (snapshot)
+
+| Export | Kind | Origin |
+|---|---|---|
+| `ListFormatter` | class | `formatter.ts` |
+| `formatList` | function | `formatter.ts` |
+| `clearListFormatterCache` | function | `formatter.ts` |
+| `ListFormatterOptionsSchema` | const | `formatter.ts` |
+| `ListFormatStyle` | type | `formatter.types.ts` |
+| `ListFormatType` | type | `formatter.types.ts` |
+| `ListFormatterOptions` | type | `formatter.types.ts` |
+| `ListFormatterCacheKey` | type | `formatter.types.ts` |
+| `formatConjunction` | function | `helpers.ts` |
+| `formatDisjunction` | function | `helpers.ts` |
+| `recordListFormat` | function | `observability.ts` |
+| `recordListCacheHit` | function | `observability.ts` |
+| `getListFormatMetricsState` | function | `observability.ts` |
+| `resetListFormatMetricsState` | function | `observability.ts` |
+
+## Versioning
+
+This package is part of the i18n modular-split rollout. Stays at
+`0.1.0` until the slim core (Wave 6) cuts the family `1.0.0` release.
+
+## Wave 3 Scope
+
+This package is one of eight Wave 3 formatter packages. Pure
+addition — `packages/i18n/i18n/src/formatting/list/` is preserved
+in the monolith until Wave 6 deletes it.
+