first commit

2026-05-29 08:20:56 +01:00
commit 949299f58d
6368 changed files with 527176 additions and 0 deletions
--- a/docs/localization/i18n/i18n-formatter-collator/README.md
+++ b/docs/localization/i18n/i18n-formatter-collator/README.md
@@ -0,0 +1,104 @@
+# @suaveplan/i18n-formatter-collator - Intl.Collator wrapper for the @suaveplan/i18n family — locale-aware string comparison and sorting (sensitivity, numeric-aware natural sort, case-first, ignorePunctuation, custom collation). Per-(locale, options-hash) cache, Zod-validated options, OTel histogram + cache-hit counter, structured I18nError mapping. Brand-new formatter — closes the gap from the original i18n-formatters change scope. Universal leaf package.
+
+## Summary
+
+Wrapper around `Intl.Collator` for the `@suaveplan/i18n` family —
+locale-aware string comparison and sorting (sensitivity, numeric-aware
+natural sort, case-first, ignorePunctuation, custom collation).
+
+This is a **brand-new formatter** in the i18n family — `Intl.Collator`
+was listed in the original `i18n-formatters` change scope but was
+never implemented in the monolith. This package closes that gap.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [formatter](./src/formatter/formatter.md) — `CollatorFormatter` and the `compareStrings` / `formatCollation` standalone helpers expose `Intl.Collator` for the `@su…
+  - [formatter](./src/formatter/formatter.md) — `CollatorFormatter` and the `compareStrings` / `formatCollation` standalone helpers expose `Intl.Collator` for the `@su…
+- [helpers](./src/helpers/helpers.md) — The three ergonomic helpers (`compareCaseInsensitive`, `compareNumericAware`, `sortStrings`) pre-bind `compareStrings`…
+  - [helpers](./src/helpers/helpers.md) — The three ergonomic helpers (`compareCaseInsensitive`, `compareNumericAware`, `sortStrings`) pre-bind `compareStrings`…
+- [observability](./src/observability/observability.md) — The Collator formatter exports two OpenTelemetry instruments and a small in-memory state ring so spec-conformance tests…
+  - [observability](./src/observability/observability.md) — The Collator formatter exports two OpenTelemetry instruments and a small in-memory state ring so spec-conformance tests…
+<!-- end:auto-docs -->
+
+## Why this exists
+
+The 14-package i18n modular split (cross-cutting design
+`2026-05-05-i18n-modular-split.md`) lifts each `Intl.*` wrapper into
+its own sibling package and adds the two formatters
+(`Collator` + `Segmenter`) that the original change scope listed but
+never shipped. Locale-aware comparison is the right primitive for
+sorting names and substring search, and is required by downstream
+consumers like `@suaveplan/dedup` and `@suaveplan/react-data-table`.
+
+## Install
+
+```bash
+bun add @suaveplan/i18n-formatter-collator
+```
+
+## Quick Start
+
+```ts
+import {
+    CollatorFormatter,
+    compareStrings,
+    formatCollation,
+    sortStrings,
+    compareCaseInsensitive,
+    compareNumericAware,
+} from "@suaveplan/i18n-formatter-collator";
+
+compareStrings("apple", "banana", "en-GB"); // -1
+sortStrings(["c", "a", "b"], "en-GB"); // ["a", "b", "c"]
+
+compareCaseInsensitive("a", "A", "en-GB"); // 0
+compareNumericAware("file2", "file10", "en-GB"); // -1
+
+const f = new CollatorFormatter({ numeric: true });
+f.sort(["log10.txt", "log2.txt", "log1.txt"], "en-GB");
+// ["log1.txt", "log2.txt", "log10.txt"]
+```
+
+## Modules
+
+| Subpath | Description |
+|---|---|
+| `@suaveplan/i18n-formatter-collator` | Root barrel — class + standalones + helpers + observability |
+| `@suaveplan/i18n-formatter-collator/formatter` | `CollatorFormatter`, `compareStrings`, `formatCollation`, types, schema |
+| `@suaveplan/i18n-formatter-collator/helpers` | `compareCaseInsensitive`, `compareNumericAware`, `sortStrings` |
+
+## Modules Documentation
+
+- [formatter.md](src/formatter.md) — `CollatorFormatter`, `compareStrings`, `formatCollation`, `clearCollatorCache`
+- [helpers.md](src/helpers.md) — three ergonomic helpers
+- [observability.md](src/observability.md) — OTel histogram + cache-hit counter
+
+## Public Surface (snapshot)
+
+| Export | Kind | Origin |
+|---|---|---|
+| `CollatorFormatter` | class | `formatter.ts` |
+| `compareStrings` | function | `formatter.ts` |
+| `formatCollation` | function | `formatter.ts` |
+| `clearCollatorCache` | function | `formatter.ts` |
+| `CollatorFormatterOptionsSchema` | Zod schema | `formatter.schemas.ts` |
+| `CollatorFormatterOptions` | type | `formatter.types.ts` |
+| `CollatorUsage` | type | `formatter.types.ts` |
+| `CollatorSensitivity` | type | `formatter.types.ts` |
+| `CollatorCaseFirst` | type | `formatter.types.ts` |
+| `CollatorNumeric` | type | `formatter.types.ts` |
+| `CollatorFormatterCacheKey` | type | `formatter.types.ts` |
+| `compareCaseInsensitive` | function | `helpers.ts` |
+| `compareNumericAware` | function | `helpers.ts` |
+| `sortStrings` | function | `helpers.ts` |
+| `recordCollatorFormat` | function | `observability.ts` |
+| `recordCollatorCacheHit` | function | `observability.ts` |
+| `getCollatorMetricsState` | function | `observability.ts` |
+| `resetCollatorMetricsState` | function | `observability.ts` |
+
+## Versioning
+
+Part of the 14-package i18n modular-split rollout. Stays at `0.1.0`
+until the slim core (Wave 6) cuts the family `1.0.0` release.
+