first commit

docs/ui/forms/react-forms/src/locales/augmentation.md

@@ -0,0 +1,72 @@
+# `augmentation` — `ContributedTranslationKeys` registration
+
+## Purpose
+
+Side-effect-only TypeScript module that augments
+`@suaveplan/react-i18n`'s `ContributedTranslationKeys` interface with
+every key shipped by `@suaveplan/react-forms`. The augmentation runs
+purely in TypeScript's type space — there is no runtime value to
+import — but the file is included as a side-effect import from
+`src/locales/locales.ts` so consumers' `tsconfig` picks up the
+declaration when they `import "@suaveplan/react-forms"`.
+
+The augmentation widens the branded `TranslationKey` union so a
+recipe's `next` button label is statically known to be a registered
+key. Misuse (`labels: { next: "typo" }`) is a TypeScript error before
+the form ever mounts.
+
+## Features
+
+- Pure type-space augmentation — zero bytes of JavaScript runtime cost.
+- Mirrors the keys in the generated `augmentation.d.ts` exactly so
+  side-effect import paths and declaration paths stay consistent.
+- Imported as a side effect from `src/locales/locales.ts` so the
+  package barrel carries the augmentation transitively.
+- Empty runtime export keeps tooling that strips type-only files from
+  side-effect chains honest.
+
+## Usage: Basic Example
+
+The augmentation is automatically applied when the package is imported.
+No explicit usage is required.
+
+```ts
+import "@suaveplan/react-forms";
+import type { TranslationKey } from "@suaveplan/react-i18n";
+
+const k: TranslationKey = "react-forms.wizard.next"; // ✅ typechecks
+```
+
+## Usage: Advanced Example
+
+If the consumer is building a server-side helper that does not import
+the package barrel but still wants the augmentation widened, pull the
+augmentation alone:
+
+```ts
+import "@suaveplan/react-forms/locales/augmentation";
+import type { TranslationKey } from "@suaveplan/react-i18n";
+
+declare const fromConfig: string;
+const key = fromConfig as TranslationKey;
+```
+
+## API Reference
+
+This module exports a single empty object literal (`export {}`) so the
+TypeScript compiler treats it as a module and applies the
+`declare module` augmentation. There are no runtime exports.
+
+## Implementation Notes
+
+- The file MUST stay in sync with `augmentation.d.ts`; both are
+  generated from `en-GB.json` by `bun
+  packages/react/react-i18n/scripts/generate-translation-types.ts
+  packages/react/react-forms --package-name @suaveplan/react-forms`.
+- Two files exist (one `.ts`, one `.d.ts`) so consumers' bundlers do
+  not strip the runtime side-effect even when declaration-only files
+  are filtered out by aggressive tree-shaking.
+- The unique-symbol brand on `ContributedTranslationKeys` ensures the
+  augmentation surface stays mergeable across packages — never declare
+  a `type ContributedTranslationKeys = { ... }`; it MUST stay an
+  `interface`.