suaveplan/openspec/archive/2026-05-10-react-i18n-plugin-registry-and-ui-primitives/tasks.md

Tasks — react-i18n plugin registry & react-ui first-class i18n surface

Phased so each phase ends with a green pre-publish gate. Each task is a single concrete unit of work; check off when the implementation, sibling .md, test file, and (where applicable) story file are all complete and the corresponding gate is green.

Phase 1 — @suaveplan/react-i18n plugin registry foundation

• 1.1 Add new error codes (PLUGIN_DUPLICATE_ID, PLUGIN_INVALID, REGISTRY_NOT_PROVIDED, FORMATTER_NOT_REGISTERED, DETECTOR_PLUGIN_DUPLICATE_ID, DETECTOR_PLUGIN_INVALID) to src/errors/error-codes.ts. Update the registry test.
• 1.2 Author src/registry/registry.types.ts — DetectorPlugin, FormatterPlugin<TArgs, TResult>, PostProcessorPlugin, PostProcessorContext, ReactI18nRegistry interfaces. No nested object literals; every shape named.
• 1.3 Author src/registry/schemas/registry.schemas.ts — DetectorPluginSchema, FormatterPluginSchema, PostProcessorPluginSchema. Strict-object Zod schemas. Export both schemas and RegistryConfigSchema (the union container shape <RegistryProvider> accepts).
• 1.4 Implement src/registry/registry.ts — createReactI18nRegistry() returning a fresh ReactI18nRegistry. Idempotent re-registration, duplicate-id throw, OTel observability (react_i18n.registry.plugins_total{kind,outcome}), disposable handles.
• 1.5 Author src/registry/registry.test.ts — registration / duplicate / dispose / schema-rejection / OTel-emit scenarios. Property test for register-then-dispose-N-times → empty registry.
• 1.6 Sibling .md for registry.ts (≥200 words, all six required sections).

Phase 2 — <RegistryProvider> and useReactI18nRegistry

• 2.1 Implement src/registry/registry-context.ts — context with null default and a brand symbol for safe cross-bundle identity.
• 2.2 Implement src/registry/registry-context.tsx — <RegistryProvider plugins? disableBuiltInFormatters? children>. Mounts a fresh registry on first render, registers built-in formatters unless disabled, registers user-provided plugins, disposes the registry on unmount.
• 2.3 Implement src/registry/use-registry.ts — useReactI18nRegistry(). Throws REACT_I18N.REGISTRY_NOT_PROVIDED outside a provider.
• 2.4 Tests for the provider — registry-context.test.tsx. Verify context isolation, dispose-on-unmount, built-in registration, user-plugin registration, disabled built-ins.
• 2.5 Sibling .md files for both registry-context.tsx and use-registry.ts.

Phase 3 — Detector plugin spliced into chain

• 3.1 Modify src/detector/default-chain/default-chain.ts — accept an optional registry?: ReactI18nRegistry argument; when provided, splice plugins by priority between built-ins.
• 3.2 Modify src/hooks/use-locale-detection/use-locale-detection.ts — read registry from context (when available) and feed it into defaultDetectorChain.
• 3.3 Update default-chain.test.ts — coverage for plugin splice, deterministic tie-break, environment gating, no-registry fallback to current behavior.
• 3.4 Update sibling default-chain.md to document the new optional parameter.

Phase 4 — Formatter plugins + useFormatter hook

• 4.1 Author src/registry/formatters/built-in/ — six files (number.ts, date.ts, currency.ts, list.ts, relative-time.ts, plural.ts), each exporting a FormatterPlugin whose format calls the existing per-package implementation.
• 4.2 Implement src/hooks/use-formatter/use-formatter.ts — looks up plugin by id from registry, returns format result, memoizes on (locale, id, JSON.stringify(args)).
• 4.3 Modify each existing formatter hook (use-number, use-date, use-currency, use-list, use-relative-time, use-plural) to delegate through useFormatter when a registry is available; fall back to direct call when not.
• 4.4 Tests — use-formatter.test.tsx (built-in resolution, custom override, missing-id throw, memoization), updated tests for each modified hook (no behavior change without a registry, override works with a registry).
• 4.5 Sibling .md for use-formatter.ts and updates to each modified hook's .md documenting the registry-override path.

Phase 4b — Locale-adapter plugin slot

• 4b.1 Author src/registry/locale-adapters/locale-adapters.types.ts — LocaleAdapterPlugin<TLocale> interface.
• 4b.2 Author src/registry/locale-adapters/built-in/date-fns.ts — built-in adapter, dynamic-import the date-fns locales map so non-Calendar consumers do not pay the bundle cost.
• 4b.3 Implement src/hooks/use-locale-adapter/use-locale-adapter.ts + sibling .md.
• 4b.4 Wire <RegistryProvider> to auto-register the date-fns built-in unless disableBuiltInLocaleAdapters is set.
• 4b.5 Tests — built-in resolution, swap-with-luxon-shaped adapter, missing-id throw.
• 4b.6 Add LOCALE_ADAPTER_NOT_REGISTERED to error registry.

Phase 5 — Post-processor pipeline

• 5.1 Author src/registry/post-processors/post-processors.ts — runPostProcessors(message: string, ctx: PostProcessorContext, plugins: PostProcessorPlugin[]): string. Sorts by priority, ties broken lexicographically by id.
• 5.2 Modify src/components/trans/trans.tsx to run the registry's post-processor pipeline after ICU interpolation, before rendering.
• 5.3 Tests — pipeline ordering, identity (no plugins → message unchanged), associativity property test, integration with <Trans> rendering.
• 5.4 Sibling .md for post-processors.ts and update trans.md.

Phase 6 — Subpath exports + barrel

• 6.1 Add subpath exports to react-i18n/package.json::exports: ./registry, ./registry/detectors, ./registry/formatters, ./registry/post-processors.
• 6.2 Add explicit named re-exports to src/registry/index.ts (no export *).
• 6.3 Add the new public surface to src/index.ts root barrel (also explicit named).
• 6.4 Run §13 step 4a barrel-shape scan — zero hits expected.

Phase 7 — Pre-publish gate for react-i18n

• 7.1 bunx turbo lint typecheck test --filter=@suaveplan/react-i18n green.
• 7.2 bunx turbo test:coverage --filter=@suaveplan/react-i18n ≥ 100 / 100 / 100 / 100.
• 7.3 bunx turbo build --filter=@suaveplan/react-i18n green.
• 7.4 §13 banned-pattern scan, missing-.md scan, README check, bare-version check, subpath-export count, security scan — all clean.
• 7.5 bunx turbo test --filter=...@suaveplan/react-i18n (downstream sweep) — green. Includes react-ui, react-forms, every pack/theme.

Phase 8 — @suaveplan/react-ui formatted primitives

• 8.1 src/i18n/formatted-number/formatted-number.tsx + .md + .test.tsx + .stories.tsx.
• 8.2 src/i18n/formatted-currency/formatted-currency.tsx + 3 siblings.
• 8.3 src/i18n/formatted-date/formatted-date.tsx + 3 siblings.
• 8.4 src/i18n/formatted-list/formatted-list.tsx + 3 siblings.
• 8.5 src/i18n/formatted-relative-time/formatted-relative-time.tsx + 3 siblings (auto-mode interval test uses fakeClock from @suaveplan/testing/runner).
• 8.6 src/i18n/plural/plural.tsx + 3 siblings.
• 8.7 src/i18n/formatted-message/formatted-message.tsx (re-export <Trans> with react-ui branding) + 3 siblings.
• 8.8 src/i18n/index.ts explicit-named barrel.
• 8.9 New subpath exports in react-ui/package.json::exports: ./i18n, ./i18n/formatted-number, ./i18n/formatted-currency, etc.

Phase 8b — ReactUiI18nBridge + TanStack collator bridges

• 8b.1 src/i18n/react-ui-i18n-bridge/react-ui-i18n-bridge.tsx + .md + .test.tsx + .stories.tsx. Mounts <DirectionProvider> (Radix), exposes LocaleContext, syncs <html lang>/<html dir> (opt-out), forwards dir to descendant sonner <Toaster>.
• 8b.2 src/i18n/tanstack-bridge/tanstack-bridge.ts — localeAwareSortingFn(locale) and localeAwareFilterFn(locale) backed by Intl.Collator. Plus sibling .md and .test.ts.
• 8b.3 Compose <ReactUiI18nBridge> into the default <ReactUiProvider> so the canonical app-level provider gets it for free; standalone mounting remains supported.
• 8b.4 Subpath exports: ./i18n/react-ui-i18n-bridge, ./i18n/tanstack-bridge.

Phase 9 — Locale-aware behavior wiring on existing components

• 9.1 <Drawer> adds inline-start / inline-end direction values; resolves via useDirection. Update drawer.tsx, drawer.md, drawer.test.tsx, drawer.stories.tsx.
• 9.2 <Sheet> adds inline-start / inline-end side values; same useDirection resolution. Update siblings.
• 9.3 <DataTable> ColumnDef.formatter shortcut. Update data-table.tsx, data-table.md, data-table.test.tsx, data-table.stories.tsx.
• 9.4 <Pagination> page-number rendering switches to <FormattedNumber/>. Verify keys remain stable.
• 9.5 <Calendar> wires useLocale() into react-day-picker's locale prop. Add localeStringToDateFnsLocale helper with a curated map for the five bundled locales + a documented fallback path. Update siblings.

Phase 10 — <InputNumber>

• 10.1 src/components/input/input-number/input-number.tsx + .md + .test.tsx + .stories.tsx. Locale-aware decimal/grouping parse, focus-state buffer, onValueChange numeric emission.
• 10.2 Subpath export ./components/input/input-number.
• 10.3 Bundle keys for placeholder / aria-label across en-GB, zh-CN, ar-AE, cy-GB, ru-RU.

Phase 11 — Translation bundles + extraction script

• 11.1 Extend src/locales/schema.ts with the new namespaces.
• 11.2 Extend each src/locales/<locale>.json with translations for the new keys (real translations, not English placeholders for non-English bundles — request review from native readers if uncertain, document in proposal).
• 11.3 Update src/locales/augmentation.ts to register the new keys into ContributedTranslationKeys.
• 11.4 Author scripts/extract-translation-keys.ts. AST walk via @babel/parser (or the same parser the rest of the repo uses), diff against the canonical en-GB.json. Document missing-vs-orphan output format.
• 11.5 Add bun run check:i18n-keys to react-ui/package.json::scripts. Wire into bunx turbo lint via the package's turbo.json lint pipeline.

Phase 12 — Validation message bridge

• 12.1 src/i18n/validation-message-bridge/validation-message-bridge.ts + sibling siblings.
• 12.2 Update <Toast>, <Alert>, and <ConfirmDeleteDialog> (the obvious validation-error consumers) to optionally accept a SuaveplanError and render it through the bridge. Existing string props continue to work.
• 12.3 Optional touch on react-forms to import the bridge from @suaveplan/react-ui/i18n/validation-message-bridge instead of its own ad-hoc copy. (Only if the diff stays trivial; otherwise mark as a follow-up.)

Phase 12b — shadcn registry regeneration + ejection gate

• 12b.1 Author / regenerate registry/r/<name>.json for every new primitive (formatted-number, formatted-currency, formatted-date, formatted-list, formatted-relative-time, plural, formatted-message, input-number, react-ui-i18n-bridge, tanstack-bridge, validation-message-bridge). Each lists its @suaveplan/react-i18n dep in registryDependencies.
• 12b.2 Regenerate registry entries for modified components: drawer, sheet, calendar, data-table, pagination — capturing new imports (useDirection, useLocale, useLocaleAdapter, <FormattedNumber/>).
• 12b.3 Author scripts/check-registry-eject.ts — applies the registry transform to each entry's source files, type-checks the transformed result against a synthesized consumer tsconfig.json, asserts @suaveplan/react-i18n imports survive.
• 12b.4 Wire bun run check:registry-eject into package.json::scripts and into bunx turbo lint via turbo.json.
• 12b.5 Test: scripts/check-registry-eject.test.ts — covers happy-path eject, missing-registry-entry diagnostic, transformed-source-fails-tsc diagnostic.

Phase 13 — Pre-publish gate for react-ui

• 13.1 bunx turbo lint typecheck test --filter=@suaveplan/react-ui green.
• 13.2 bunx turbo test:coverage --filter=@suaveplan/react-ui ≥ 100 / 100 / 100 / 100.
• 13.3 bunx turbo build --filter=@suaveplan/react-ui green.
• 13.4 bun run check:i18n-keys zero-defect.
• 13.4b bun run check:registry-eject zero-defect — every registry entry compiles when ejected.
• 13.5 §13 banned-pattern / missing-.md / barrel-shape / runner-import scans — all clean.
• 13.6 bunx turbo test --filter=...@suaveplan/react-ui downstream sweep — green.
• 13.7 Storybook smoke run — every new story renders without console errors / warnings.

Phase 14 — Spec fold + archive

• 14.1 Fold specs/react-i18n/spec.md deltas into openspec/specs/react-i18n/spec.md.
• 14.2 Create openspec/specs/react-ui-i18n/spec.md from the deltas.
• 14.3 Update root docs: MANIFEST.md (auto-generate), MISSING.yml (auto-generate), STATUS.md, SUMMARY.md.
• 14.4 bunx markdownlint-cli2 --fix across touched files; second pass without --fix exits 0.
• 14.5 Move openspec/changes/react-i18n-plugin-registry-and-ui-primitives/ → openspec/archive/2026-MM-DD-react-i18n-plugin-registry-and-ui-primitives/.