@astryxdesign/core 0.7.1 → 0.7.2-canary.b69b2df

package/src/Pagination/Pagination.tsx

@@ -5,9 +5,10 @@
 /**
  * @file Pagination.tsx
  * @input Uses React, StyleX, Button, Icon, Selector, Text; page number buttons delegate to Button.
+ *   Compact first/last buttons cancel the inside control gap with logical token margins.
  *   Prev/next and first/last chevrons mirror under RTL via the shared rtlStyles.mirror
- *   (CSS scaleX), not a JS direction read. The input variant uses the chevronsLeft/chevronsRight
- *   (first/last) icons.
+ *   (CSS scaleX), not a JS direction read. The input and compact variants use the
+ *   chevronsLeft/chevronsRight (first/last) icons.
  * @output Exports Pagination component, PaginationProps, PaginationVariant, PaginationSize types
  * @position Core implementation; consumed by index.ts, tested by Pagination.test.tsx
  *
@@ -105,7 +106,8 @@ export interface PaginationProps extends Omit<
    * Visual variant controlling what appears between prev/next buttons.
    * - pages: Page number buttons with ellipsis (default)
    * - count: "X–Y of Z" text
-   * - compact: "Page X of Y" text
+   * - compact: "Page X of Y" text. First/last buttons are opt-in (see
+   *   hasFirstLast).
    * - dots: Dot indicators
    * - input: An editable number box rendering "Page [ n ] / N". The leading
    *   noun is controlled by `pageLabel`. First/last double-chevron buttons
@@ -122,9 +124,11 @@ export interface PaginationProps extends Omit<
   pageLabel?: string;
   /**
    * Whether to show first/last («/») double-chevron buttons flanking
-   * prev/next. Only applies to the `input` variant; other variants ignore it.
-   * The last button needs a known total — it is omitted when the page count is
-   * unknown (cursor/hasMore pagination). @default true
+   * prev/next. Applies to the `input` variant (shown unless false) and the
+   * `compact` variant (shown only when true); other variants ignore it.
+   * The last button needs a known total — both are omitted when the page count
+   * is unknown (cursor/hasMore pagination).
+   * @default true for `input`, false for `compact`
    */
   hasFirstLast?: boolean;
   /**
@@ -181,6 +185,12 @@ const styles = stylex.create({
     alignItems: 'center',
     gap: spacingVars['--spacing-1'],
   },
+  compactFirst: {
+    marginInlineEnd: `calc(-1 * ${spacingVars['--spacing-1']})`,
+  },
+  compactLast: {
+    marginInlineStart: `calc(-1 * ${spacingVars['--spacing-1']})`,
+  },
   ellipsis: {
     display: 'inline-flex',
     alignItems: 'center',
@@ -369,7 +379,7 @@ export function Pagination({
   onPageSizeChange,
   variant = 'pages',
   pageLabel,
-  hasFirstLast = true,
+  hasFirstLast: hasFirstLastProp,
   step: stepProp = 1,
   siblingCount = 1,
   size = 'md',
@@ -572,10 +582,14 @@ export function Pagination({
   const buttonSize = size === 'sm' ? 'sm' : 'md';
   const isSm = size === 'sm';
 
-  // First/last buttons only exist in the input variant, and only when the page
-  // count is known (they'd have no target otherwise).
-  const showFirstLast =
-    hasFirstLast && variant === 'input' && computedTotalPages != null;
+  // First/last buttons are on by default in the input variant and opt-in for
+  // compact; other variants never render them. They also need a known page
+  // count (the last button would have no target otherwise).
+  const hasFirstLast =
+    variant === 'input'
+      ? (hasFirstLastProp ?? true)
+      : variant === 'compact' && hasFirstLastProp === true;
+  const showFirstLast = hasFirstLast && computedTotalPages != null;
 
   const renderIndicator = () => {
     switch (variant) {
@@ -819,6 +833,7 @@ export function Pagination({
             onClick={handleFirst}
             isDisabled={isDisabled || !hasPrevious}
             isIconOnly
+            xstyle={variant === 'compact' && styles.compactFirst}
           />
         )}
 
@@ -874,6 +889,7 @@ export function Pagination({
             onClick={handleLast}
             isDisabled={isDisabled || !hasNext}
             isIconOnly
+            xstyle={variant === 'compact' && styles.compactLast}
           />
         )}
       </div>

package/src/Switch/Switch.test.tsx

@@ -834,6 +834,34 @@ describe('Switch', () => {
       expect(root).toHaveAttribute('id', 'switch-1');
       expect(root).toHaveAttribute('aria-label', 'Toggle notifications');
     });
+
+    it('composes a caller aria-describedby onto the switch control', () => {
+      const {container} = render(
+        <>
+          <p id="external-hint">Applies to every repository</p>
+          <Switch
+            label="Notifications"
+            description="Sends a daily digest"
+            value={false}
+            onChange={() => {}}
+            data-testid="my-switch"
+            aria-describedby="external-hint"
+          />
+        </>,
+      );
+      const control = screen.getByRole('switch');
+      const description = screen.getByText('Sends a daily digest');
+      expect(control.getAttribute('aria-describedby')?.split(' ')).toEqual([
+        'external-hint',
+        description.id,
+      ]);
+      expect(control).toHaveAccessibleDescription(
+        'Applies to every repository Sends a daily digest',
+      );
+      // The id reference lives on the control only, not on the field wrapper.
+      const root = container.querySelector('[data-testid="my-switch"]');
+      expect(root).not.toHaveAttribute('aria-describedby');
+    });
   });
 
   describe('pressed state', () => {

package/src/Switch/Switch.tsx

@@ -566,6 +566,7 @@ export function Switch({
   className,
   style,
   ref,
+  'aria-describedby': ariaDescribedByProp,
   ...rest
 }: SwitchProps) {
   const t = useTranslator();
@@ -610,7 +611,12 @@ export function Switch({
   // Only include descriptionID when the element actually renders.
   // FieldLabel renders the description (with descriptionID) even when the
   // label is visually hidden — it's sr-only, so keep it linked.
+  // A consumer's own `aria-describedby` describes the control, so it comes
+  // first here rather than landing on the field wrapper via `...rest`.
   const describedByParts: string[] = [];
+  if (ariaDescribedByProp) {
+    describedByParts.push(ariaDescribedByProp);
+  }
   if (description) {
     describedByParts.push(descriptionID);
   }

package/src/i18n/InternationalizationProvider.doc.mjs

@@ -21,6 +21,14 @@ export const docs = {
   usage: {
     description:
       'Wraps your app to set the active locale and (optionally) merge additional translation catalogs + per-locale overrides. Astryx components inside the subtree resolve their strings against this context. If no provider is present, components fall back to the shipped English defaults.',
+    anatomy: [
+      {
+        name: 'Provider boundary',
+        required: true,
+        description:
+          'A nonvisual context boundary that supplies locale, message catalogs, overrides, and direction to descendant Astryx components. It renders no DOM element.',
+      },
+    ],
     bestPractices: [
       {
         guidance: true,

package/src/i18n/InternationalizationProvider.spec.md

@@ -0,0 +1,252 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:InternationalizationProvider
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: nynexman4464
+approved_at: 2026-10-15
+owners: [nynexman4464, cixzhang]
+review_triggers: [public-api, behavior, accessibility]
+verified_by:
+  [
+    packages/core/src/i18n/__tests__/resolve.test.ts,
+    packages/core/src/i18n/__tests__/InternationalizationProvider.test.tsx,
+    packages/core/src/i18n/__tests__/useDirection.test.tsx,
+    packages/core/src/i18n/__tests__/getLocaleDirection.test.ts,
+    packages/core/src/i18n/__tests__/useLocale.test.tsx,
+    packages/core/src/i18n/useTranslator.test.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture: [architecture:internationalization]
+contributing: []
+system_specs: []
+---
+
+# InternationalizationProvider component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `messages` accepts `ProviderMessagesByLocale`: each locale maps to a rich `Catalog` or a generated `RuntimeCatalog` string map. `RuntimeCatalog` and `ProviderMessagesByLocale` are exported from `@astryxdesign/core/i18n`. Existing props and the rich `MessagesByLocale` context shape are unchanged.                                                                                                                                        |
+| Behavior                | Astryx strings resolve override → supplied catalog → shipped English, walking exact → parent locale. Rich and runtime catalogs resolve identically; the context always exposes the rich shape. Changing any provider prop updates the subtree. A nested provider replaces its parent's context. Without a provider: locale `en`, direction `ltr`, shipped English.                                                                              |
+| End-user impact         | People using a translated locale see Astryx interface and assistive text in that locale where a translation exists and meaningful English otherwise; a missing translation never removes an accessible name or announcement.                                                                                                                                                                                                                    |
+| Builder impact          | Optional: import `@astryxdesign/core/locales/<tag>.generated.js` for a smaller bundle; `<tag>.json` keeps working. Render the provider once, supply partial catalogs freely, and keep DOM `dir` aligned with the provider direction.                                                                                                                                                                                                            |
+| Compatibility/readiness | Released default preserved; the provider, subpath, props, hooks, and rich context shape are stable public API; runtime-catalog input is additive. Re-render, nested-provider, and runtime-catalog behavior is covered by focused tests.                                                                                                                                                                                                         |
+| Review checks           | Reject reordering fallback (FR1, ORD1); hiding a key missing from every applicable source, including shipped English (FR2); a nested provider that merges parent context (FR8); the provider setting DOM `lang`/`dir` (FR5) or persisting locale (FR4); non-string translator results (FR7); host-locale output without a provider (FR6); a context value that exposes string-map entries or resolves rich and runtime input differently (FR9). |
+| Governing rules         | `architecture:internationalization` INV2–INV5, INV7, INV12, INV13, INV15.                                                                                                                                                                                                                                                                                                                                                                       |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+InternationalizationProvider binds one subtree to Astryx's active locale,
+translation catalogs, sparse Astryx string overrides, and direction default. It
+lets Astryx components localize their own interface while applications keep
+ownership of product copy and locale persistence.
+
+## Compatibility and migration
+
+- Released default preserved: `yes` — a tree with no provider continues to render
+  shipped English strings with locale `en` and direction `ltr`.
+- Compatibility class: the released provider name, `@astryxdesign/core/i18n`
+  subpath, props, context behavior, and hooks are stable public API.
+- Controlled/uncontrolled behavior: controlled. The caller supplies locale,
+  messages, overrides, and optional direction on every render.
+- Migration decision: a replacement provider or hook requires an accepted
+  compatibility and migration decision under
+  `architecture:internationalization/INV2`.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The active Astryx locale and optional explicit direction for one React subtree.
+- Binding supplied locale catalogs, rich or generated, and sparse overrides to a
+  stable translator function, and exposing them to consumers in the rich shape.
+- Updating provider consumers when any provider input changes.
+- The no-provider English/LTR context defaults exposed by the i18n entry point.
+
+**Does not own / non-goals**
+
+- Application locale selection, routing, persistence, or account preferences —
+  owned by the product.
+- Product-authored strings and application catalogs — owned by product call sites
+  or their chosen i18n runtime.
+- DOM `lang` or `dir` attributes — owned by the application document or region.
+- A server/RSC translation context — unresolved separate API work.
+- Rich React-node/function messages — outside the supported string catalog model.
+
+## Public concepts
+
+| Concept   | Closed values or states                | Meaning                                                                                                                                                                   | Availability by variant/orientation/state | Default                                     | Owner                                    | Stability | Invalid-value behavior                                                                                                                                                                                     |
+| --------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------- | ---------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Locale    | Valid BCP 47 locale string             | Selects lookup, ICU formatting, and provider-aware locale operations                                                                                                      | Every provider subtree                    | Required on provider; `en` without one      | `component:InternationalizationProvider` | stable    | Callers must pass a valid tag; malformed tags may throw when formatting or collating, while static key lookup may still reach English                                                                      |
+| Messages  | locale → `Catalog` or `RuntimeCatalog` | Adds translated or application-supplied catalogs, as rich `{defaultMessage, description?}` entries or as a generated key-to-string map, without replacing shipped English | Every locale                              | `{}`                                        | `component:InternationalizationProvider` | stable    | Missing entries fall back through the active locale's parent chain, then to shipped English; a supplied `en` catalog is read only when that chain includes `en`; mixed shapes within one call are accepted |
+| Overrides | locale → sparse key/string map         | Rewords individual Astryx strings before catalog lookup                                                                                                                   | Every locale                              | none                                        | `component:InternationalizationProvider` | stable    | `null` does not become visible content; unresolved keys continue through fallback                                                                                                                          |
+| Direction | `ltr` or `rtl`                         | Exposes the provider's semantic direction default                                                                                                                         | Every provider subtree                    | derived from locale; `ltr` without provider | `component:InternationalizationProvider` | stable    | Invalid values are rejected by the type contract                                                                                                                                                           |
+
+Consumer prop syntax and examples remain in
+`InternationalizationProvider.doc.mjs` and `astryx docs internationalization`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                                     | Basis                                                                                  | Draft review state |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------ |
+| FR1 | The provider MUST resolve Astryx strings through exact-locale overrides, parent-locale overrides, exact/parent supplied catalogs, then shipped English.                                                                 | Current resolver and focused tests                                                     | settled            |
+| FR2 | A missing translated key MUST fall back silently; a key absent from every applicable source, including shipped English, MUST warn once in development and render the key visibly.                                       | Released resolver and tests                                                            | settled            |
+| FR3 | Re-rendering with changed locale, messages, overrides, or direction MUST update the context value and translator used by descendants.                                                                                   | Released provider and rerender tests                                                   | settled            |
+| FR4 | The provider MUST NOT select, persist, or mutate application locale state.                                                                                                                                              | Released API ownership                                                                 | settled            |
+| FR5 | The provider MUST NOT set DOM `lang` or `dir`. Its direction value and the application's DOM direction are separate inputs the application keeps aligned.                                                               | `architecture:internationalization/INV12`                                              | settled            |
+| FR6 | Without a provider, the public context and hooks MUST expose locale `en`, direction `ltr`, an empty supplied-catalog map, and a translator backed by shipped English.                                                   | Released context and tests                                                             | settled            |
+| FR7 | The provider MUST preserve a string-returning translator suitable for visible and assistive attributes.                                                                                                                 | Released catalog/runtime contract                                                      | settled            |
+| FR8 | A nested provider MUST replace locale, messages, overrides, and direction with values derived solely from the child provider's own props rather than merge parent context.                                              | Released provider and nested-provider tests                                            | settled            |
+| FR9 | The provider MUST accept a `RuntimeCatalog` string map or a rich `Catalog` per locale, resolve both to the same strings, and expose `messages` on the context in the rich `MessagesByLocale` shape regardless of input. | `architecture:internationalization/INV15`; provider and resolver runtime-catalog tests | settled            |
+
+### Allowed variation
+
+- **AV1 — Catalog completeness.** A non-English supplied catalog may contain any
+  subset of English keys; missing entries use fallback. Today that fallback
+  reaches shipped English only, so it covers Astryx keys; see OQ1.
+- **AV2 — Locale specificity.** Callers may provide a regional, script, or base
+  locale. The resolver canonicalizes and walks the corresponding parent chain.
+- **AV3 — Application integration.** Another i18n provider may wrap Astryx inside
+  or outside this provider as long as the application keeps locale state aligned.
+- **AV4 — Catalog form.** A caller may pass the shipped rich JSON, the shipped
+  generated string map, or a local catalog in either shape, per locale.
+
+### Representative states
+
+| State                             | Required invariant | Allowed variation                            |
+| --------------------------------- | ------------------ | -------------------------------------------- |
+| no provider                       | FR6                | none                                         |
+| English provider                  | FR1–FR4, FR7       | messages and overrides may be omitted        |
+| exact translated locale           | FR1–FR4, FR7, FR9  | complete or partial catalog, rich or runtime |
+| regional locale with base catalog | FR1–FR4, FR7       | number of parent tags                        |
+| runtime locale swap               | FR3                | application persistence mechanism            |
+| explicit direction override       | FR3, FR5           | locale may remain LTR for testing            |
+| nested provider                   | FR1–FR8            | child props fully replace parent context     |
+| generated runtime catalog input   | FR9                | mixed rich and runtime locales               |
+
+### Transformation and precedence order
+
+- **ORD1 — Message resolution.** Read exact-locale override → walk parent-locale
+  overrides → read exact-locale supplied catalog → walk parent supplied catalogs
+  → read shipped English → warn and render the key if absent everywhere.
+- **ORD1a — Input normalization.** A `RuntimeCatalog` entry is treated as a rich
+  entry with that string as `defaultMessage` and no description before ORD1 runs;
+  the context receives the normalized rich map.
+- **ORD2 — Direction resolution.** Use explicit `dir` when supplied; otherwise
+  derive direction from locale; outside a provider use `ltr`.
+
+### Performance and resources
+
+- **PR1 — Stable translator identity.** A provider render with referentially
+  unchanged inputs SHOULD preserve its memoized context value and translator.
+- **PR2 — Parsed message reuse.** ICU formatter instances MAY be cached by locale
+  and message while output remains equivalent to fresh formatting.
+
+## Accessibility contract
+
+- **AR1 — Assistive strings use the same resolution contract.** `aria-label`,
+  `title`, live announcements, and other AT-facing Astryx strings MUST use the
+  active translator and remain strings; assembling them from fragments or
+  hand-rolled plurals is a bypass under `architecture:internationalization/INV1a`.
+- **AR2 — Missing translations remain usable.** Expected non-English gaps MUST
+  fall back to meaningful English rather than remove an accessible name or
+  announcement.
+- **AR3 — Direction remains available to browser semantics.** The provider MUST
+  document that applications set DOM `dir`; a context value alone does not fix
+  browser text flow, punctuation, focus order, or platform bidi behavior.
+
+## Design relationships
+
+| Anatomy or state     | Design requirement                                                            | Representation authority            | Hierarchy role | Component contract |
+| -------------------- | ----------------------------------------------------------------------------- | ----------------------------------- | -------------- | ------------------ |
+| Provider subtree     | Product chooses the locale and region direction consistently.                 | application-owned                   | supporting     | FR3–FR5            |
+| Astryx system string | Astryx supplies a localized default; caller content may specialize semantics. | `architecture:internationalization` | supporting     | FR1, FR7, AR1      |
+| Missing translation  | Interface remains understandable through English fallback.                    | `architecture:internationalization` | supporting     | FR2, AR2           |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Provider boundary": {
+    "none": {
+      "reason": "intentional: InternationalizationProvider renders no DOM element and exposes no theming anatomy."
+    }
+  }
+}
+```
+
+## Family and system relationships
+
+- `architecture:internationalization` owns cross-library catalog, locale,
+  formatter, date-calendar, output-type, external-runtime, and generated
+  runtime-catalog delivery boundaries (which files are authored, which are
+  derived, how they are published and resolved).
+- Component contracts own which strings are Astryx-authored and which content is
+  caller-authored.
+
+## Verification map
+
+| Contract       | Verification                                                                            | Representative states                                       | Mutation or failure expectation                                                                    | Audit section                                      |
+| -------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| FR1, FR2, ORD1 | `resolve.test.ts`                                                                       | exact, parent, English, missing source key                  | Reordering fallback or hiding a missing source key fails focused tests                             | `audit:InternationalizationProvider/behavior`      |
+| FR3, PR1       | `useTranslator.test.tsx`, `useLocale.test.tsx`, `InternationalizationProvider.test.tsx` | stable inputs; locale, message, override, and dir swaps     | A stale translator/direction or needless identity churn fails these tests                          | `audit:InternationalizationProvider/performance`   |
+| FR5, ORD2      | `useDirection.test.tsx`, `getLocaleDirection.test.ts`                                   | derived, explicit, invalid locale, no provider              | Setting DOM direction or ignoring explicit override fails source/tests                             | `audit:InternationalizationProvider/rtl`           |
+| FR6            | `useTranslator.test.tsx`, `useLocale.test.tsx`, `useDirection.test.tsx`                 | no provider                                                 | Host locale or missing English output fails                                                        | `audit:InternationalizationProvider/behavior`      |
+| FR7, AR1, AR2  | component translation tests and hardcoded-string lint                                   | visible text, aria label, announcement, missing translation | Non-string output or untranslated owned text fails tests/lint                                      | `audit:InternationalizationProvider/accessibility` |
+| FR8            | `InternationalizationProvider.test.tsx`                                                 | parent plus child provider                                  | Parent messages, overrides, or direction leaking into the child fails                              | `audit:InternationalizationProvider/behavior`      |
+| FR9, ORD1a     | `useTranslator.test.tsx`, `resolve.test.ts` runtime-catalog cases                       | generated string map, rich catalog, mixed                   | A rejected string map, a string-map entry on the context, or divergent output between shapes fails | `audit:InternationalizationProvider/behavior`      |
+
+## Decision log
+
+### DEC-1 — Keep the released Astryx runtime narrow
+
+**Reference:** `component:InternationalizationProvider/DEC-1`
+**Decider:** `nynexman4464`, `2026-09-03`
+
+Astryx keeps `InternationalizationProvider` and the released i18n hooks as its
+canonical runtime. Astryx may support small applications, but it does not absorb
+application-owned rich messages and functions to compete with full i18n
+frameworks. Applications with larger needs use an established application i18n
+runtime alongside Astryx; an adapter remains possible as additive follow-up.
+
+Rejected: a parallel provider/hook runtime that replaces the released surface
+and mixes Astryx string ownership with application rich-message ownership.
+
+## Open questions
+
+- **OQ1 — Supplied `en` as a fallback for non-Astryx keys (known bug).** The
+  shipped English runtime catalog is the only cross-locale fallback and it holds
+  Astryx keys only. An application or library key that is missing from the active
+  locale therefore renders as its raw key even when the caller supplied an `en`
+  catalog. This is a known cross-locale fallback defect. The contract describes
+  the shipped behavior without endorsing the limitation; a supplied-English
+  fallback requires a corresponding FR1/ORD1 amendment and a regression test
+  using a partially translated non-Astryx key. (`human-api`)
+- **OQ2 — Malformed locale behavior.** Decide whether a future release should
+  reject invalid BCP 47 tags at the provider boundary or preserve today's
+  formatter-specific throws. (`human-api`)
+- **OQ3 — External runtime adapter.** Decide the exact additive `Translator`
+  adapter contract, including who owns lookup, fallback, and formatter failures.
+  (`human-api`)
+- **OQ4 — Server translation runtime.** Decide whether the small set of otherwise
+  server-safe consumers justifies a separate RSC translation API and request
+  isolation model. (`human-api`)
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, catalog validation
+implementation, runtime-catalog generation, current translation coverage, or
+cross-library i18n rules. It links to their owners.

package/src/i18n/__tests__/InternationalizationProvider.test.tsx

@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file InternationalizationProvider.test.tsx
+ * @input packages/core/src/i18n/InternationalizationProvider.tsx, useTranslator,
+ *   useDirection, useLocale
+ * @output Unit tests for the provider's update and nesting contract
+ * @position Colocated tests; targets re-rendering when messages, overrides, or
+ *   dir change (locale is covered by useLocale/useTranslator tests) and a nested
+ *   provider replacing rather than merging its parent's context.
+ */
+
+import {describe, expect, test} from 'vitest';
+import {render} from '@testing-library/react';
+import {InternationalizationProvider} from '../InternationalizationProvider';
+import {useDirection} from '../useDirection';
+import {useLocale} from '../useLocale';
+import {useTranslator} from '../useTranslator';
+import type {MessagesByLocale, Overrides} from '../types';
+
+const NEXT = '@astryx.pagination.next';
+const APP_KEY = '@myapp.save';
+
+function Probe() {
+  const t = useTranslator();
+  return (
+    <>
+      <span data-testid="next">{t(NEXT)}</span>
+      <span data-testid="app">{t(APP_KEY)}</span>
+      <span data-testid="locale">{useLocale()}</span>
+      <span data-testid="dir">{useDirection()}</span>
+    </>
+  );
+}
+
+const FR_MESSAGES: MessagesByLocale = {
+  fr: {[APP_KEY]: {defaultMessage: 'Enregistrer'}},
+};
+const FR_MESSAGES_V2: MessagesByLocale = {
+  fr: {[APP_KEY]: {defaultMessage: 'Sauvegarder'}},
+};
+const FR_OVERRIDES: Overrides = {fr: {[NEXT]: 'Suivant'}};
+const FR_OVERRIDES_V2: Overrides = {fr: {[NEXT]: 'Page suivante'}};
+
+describe('InternationalizationProvider — re-rendering', () => {
+  test('re-renders consumers when messages change', () => {
+    const {getByTestId, rerender} = render(
+      <InternationalizationProvider locale="fr" messages={FR_MESSAGES}>
+        <Probe />
+      </InternationalizationProvider>,
+    );
+    expect(getByTestId('app').textContent).toBe('Enregistrer');
+
+    rerender(
+      <InternationalizationProvider locale="fr" messages={FR_MESSAGES_V2}>
+        <Probe />
+      </InternationalizationProvider>,
+    );
+    expect(getByTestId('app').textContent).toBe('Sauvegarder');
+  });
+
+  test('re-renders consumers when overrides change', () => {
+    const {getByTestId, rerender} = render(
+      <InternationalizationProvider locale="fr" overrides={FR_OVERRIDES}>
+        <Probe />
+      </InternationalizationProvider>,
+    );
+    expect(getByTestId('next').textContent).toBe('Suivant');
+
+    rerender(
+      <InternationalizationProvider locale="fr" overrides={FR_OVERRIDES_V2}>
+        <Probe />
+      </InternationalizationProvider>,
+    );
+    expect(getByTestId('next').textContent).toBe('Page suivante');
+  });
+
+  test('re-renders consumers when dir changes', () => {
+    const {getByTestId, rerender} = render(
+      <InternationalizationProvider locale="en" dir="rtl">
+        <Probe />
+      </InternationalizationProvider>,
+    );
+    expect(getByTestId('dir').textContent).toBe('rtl');
+
+    rerender(
+      <InternationalizationProvider locale="en" dir="ltr">
+        <Probe />
+      </InternationalizationProvider>,
+    );
+    expect(getByTestId('dir').textContent).toBe('ltr');
+  });
+});
+
+describe('InternationalizationProvider — nesting', () => {
+  test('a nested provider replaces the parent context instead of merging it', () => {
+    const {getByTestId} = render(
+      <InternationalizationProvider
+        locale="fr"
+        dir="rtl"
+        messages={FR_MESSAGES}
+        overrides={FR_OVERRIDES}>
+        <InternationalizationProvider locale="fr">
+          <Probe />
+        </InternationalizationProvider>
+      </InternationalizationProvider>,
+    );
+    // Locale is the child's own; direction derives from it, not the parent's
+    // explicit rtl; parent overrides and catalogs do not leak into the child.
+    expect(getByTestId('locale').textContent).toBe('fr');
+    expect(getByTestId('dir').textContent).toBe('ltr');
+    expect(getByTestId('next').textContent).toBe('Go to next page');
+    expect(getByTestId('app').textContent).toBe(APP_KEY);
+  });
+
+  test('a nested provider can narrow the locale for one subtree', () => {
+    const {getByTestId} = render(
+      <InternationalizationProvider locale="fr" overrides={FR_OVERRIDES}>
+        <InternationalizationProvider locale="de">
+          <Probe />
+        </InternationalizationProvider>
+      </InternationalizationProvider>,
+    );
+    expect(getByTestId('locale').textContent).toBe('de');
+    // No de override or catalog: shipped English wins.
+    expect(getByTestId('next').textContent).toBe('Go to next page');
+  });
+});

package/src/i18n/generated-locales/en.generated.ts

@@ -158,6 +158,27 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
     '{itemName} dropped at position {position, number} of {total, number}.',
   '@astryx.listInput.announceAlreadyAtBoundary':
     'This {itemName} is already {boundary, select, first {first} last {last} other {}}.',
+  '@astryx.diffViewer.label': 'Diff',
+  '@astryx.diffViewer.renamedPath': '{oldPath} → {newPath}',
+  '@astryx.diffViewer.statusAdded': 'Added',
+  '@astryx.diffViewer.statusDeleted': 'Deleted',
+  '@astryx.diffViewer.statusRenamed': 'Renamed',
+  '@astryx.diffViewer.addedCount': '+{count, number}',
+  '@astryx.diffViewer.removedCount': '−{count, number}',
+  '@astryx.diffViewer.stats':
+    '{added, plural, one {# line added} other {# lines added}}, {removed, plural, one {# line removed} other {# lines removed}}',
+  '@astryx.diffViewer.added': 'Added',
+  '@astryx.diffViewer.removed': 'Removed',
+  '@astryx.diffViewer.lineNumberButton':
+    '{side, select, old {Original line {line, number}} other {Changed line {line, number}}}',
+  '@astryx.diffViewer.columnOldLine': 'Original line number',
+  '@astryx.diffViewer.columnNewLine': 'Changed line number',
+  '@astryx.diffViewer.columnChange': 'Change',
+  '@astryx.diffViewer.columnCode': 'Code',
+  '@astryx.diffViewer.columnOldCode': 'Original code',
+  '@astryx.diffViewer.columnNewCode': 'Changed code',
+  '@astryx.diffViewer.binary': 'Binary file not shown',
+  '@astryx.diffViewer.noChanges': 'No content changes',
   '@astryx.markdownHeadingLinks.copied': 'Link copied',
   '@astryx.markdownHeadingLinks.copy': 'Copy link to {heading}',
   '@astryx.richTextEditor.tabEscapeHint':

package/src/i18n/generated-locales/pseudo.generated.ts

@@ -163,6 +163,27 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
     '⟦{itemName} ðřóþþéð àţ þóšíţíóñ {position, number} óƒ {total, number}.⟧',
   '@astryx.listInput.announceAlreadyAtBoundary':
     '⟦Ţĥíš {itemName} íš àłřéàðý {boundary, select, first {first} last {last} other {}}.⟧',
+  '@astryx.diffViewer.label': '⟦Ð탃⟧',
+  '@astryx.diffViewer.renamedPath': '⟦{oldPath} → {newPath}⟧',
+  '@astryx.diffViewer.statusAdded': '⟦Àððéð⟧',
+  '@astryx.diffViewer.statusDeleted': '⟦Ðéłéţéð⟧',
+  '@astryx.diffViewer.statusRenamed': '⟦Řéñàɱéð⟧',
+  '@astryx.diffViewer.addedCount': '⟦+{count, number}⟧',
+  '@astryx.diffViewer.removedCount': '⟦−{count, number}⟧',
+  '@astryx.diffViewer.stats':
+    '⟦{added, plural, one {# line added} other {# lines added}}, {removed, plural, one {# line removed} other {# lines removed}}⟧',
+  '@astryx.diffViewer.added': '⟦Àððéð⟧',
+  '@astryx.diffViewer.removed': '⟦Řéɱóṽéð⟧',
+  '@astryx.diffViewer.lineNumberButton':
+    '⟦{side, select, old {Original line {line, number}} other {Changed line {line, number}}}⟧',
+  '@astryx.diffViewer.columnOldLine': '⟦Óříĝíñàł łíñé ñúɱƀéř⟧',
+  '@astryx.diffViewer.columnNewLine': '⟦Çĥàñĝéð łíñé ñúɱƀéř⟧',
+  '@astryx.diffViewer.columnChange': '⟦Çĥàñĝé⟧',
+  '@astryx.diffViewer.columnCode': '⟦Çóðé⟧',
+  '@astryx.diffViewer.columnOldCode': '⟦Óříĝíñàł çóðé⟧',
+  '@astryx.diffViewer.columnNewCode': '⟦Çĥàñĝéð çóðé⟧',
+  '@astryx.diffViewer.binary': '⟦Ɓíñàřý ƒíłé ñóţ šĥóŵñ⟧',
+  '@astryx.diffViewer.noChanges': '⟦Ñó çóñţéñţ çĥàñĝéš⟧',
   '@astryx.markdownHeadingLinks.copied': '⟦Łíñķ çóþíéð⟧',
   '@astryx.markdownHeadingLinks.copy': '⟦Çóþý łíñķ ţó {heading}⟧',
   '@astryx.richTextEditor.tabEscapeHint':