@astryxdesign/core 0.1.6 → 0.1.7-canary.04cd8f7

package/src/docs-types.ts

@@ -616,9 +616,7 @@ export interface SubComponentDoc extends Omit<BaseDoc, 'usage'> {
  * in its own file inside its parent's directory.
  */
 export type ComponentDoc =
-  | SingleComponentDoc
-  | MultiComponentDoc
-  | SubComponentDoc;
+  SingleComponentDoc | MultiComponentDoc | SubComponentDoc;
 
 /**
  * Translation overlay for component documentation.
@@ -781,16 +779,23 @@ export interface ReferenceDoc {
 export interface ReferenceTranslationDoc {
   /** Translated/compressed description. */
   description: string;
-  /** Section overrides. Array indices must match base doc sections. */
+  /** Section overrides, keyed to base sections by `section`. Order does not
+   *  matter, and an overlay may cover any subset — sections it does not name
+   *  keep their base content. (These used to be matched by array index, which
+   *  meant a reordered or partial overlay grafted every title onto the wrong
+   *  body: `docs tokens --dense` printed the colour table under a "Spacing"
+   *  heading. See #2182.) */
   sections: {
-    /** Translated section title. */
+    /** Title of the BASE section this entry overrides, verbatim and in English
+     *  (e.g. 'Spacing Tokens'). Must match a section in the base doc. */
+    section: string;
+    /** Translated/compressed section title, shown in place of the base title. */
     title: string;
-    /** Content block overrides. Only prose and list blocks need entries.
-     *  Use null for blocks that don't change (code, table). */
+    /** Content block overrides, by index within the anchored base section.
+     *  Only prose and list blocks need entries. Use null for blocks that don't
+     *  change (code, table). */
     content: (
-      | {type: 'prose'; text: string}
-      | {type: 'list'; items: string[]}
-      | null
+      {type: 'prose'; text: string} | {type: 'list'; items: string[]} | null
     )[];
   }[];
 }

package/src/i18n/InternationalizationContext.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file InternationalizationContext.ts
+ * @input React createContext, i18n types
+ * @output Exports InternationalizationContext and InternationalizationContextValue
+ * @position Context definition for client-side locale + messages
+ *
+ * Separated from InternationalizationProvider.tsx so components can consume
+ * the context without pulling in the full provider implementation.
+ * Follows the LinkContext.ts / ThemeContext.ts pattern.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/InternationalizationProvider.tsx
+ * - /packages/core/src/i18n/t.client.ts
+ * - /packages/core/src/i18n/index.ts
+ */
+
+import {createContext} from 'react';
+import type {Locale, MessagesByLocale, Overrides} from './types';
+
+export interface InternationalizationContextValue {
+  locale: Locale;
+  messages: MessagesByLocale;
+  overrides?: Overrides;
+}
+
+/**
+ * Default value falls through to the shipped en catalog in resolve().
+ * A consumer that doesn't render a provider still gets English defaults.
+ */
+export const InternationalizationContext =
+  createContext<InternationalizationContextValue>({
+    locale: 'en',
+    messages: {},
+  });
+InternationalizationContext.displayName = 'InternationalizationContext';

package/src/i18n/InternationalizationProvider.doc.mjs

@@ -0,0 +1,72 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'InternationalizationProvider',
+  displayName: 'Internationalization Provider',
+  group: 'Utilities',
+  category: 'Utility',
+  isHiddenFromOverview: true,
+  keywords: [
+    'i18n',
+    'internationalization',
+    'localization',
+    'locale',
+    'translation',
+    'translations',
+    'provider',
+    'language',
+  ],
+  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.",
+  },
+  props: [
+    {
+      name: 'locale',
+      type: 'string',
+      required: true,
+      description:
+        'BCP 47 language tag for the active locale (e.g. "en", "pt", "pt-BR", "zh-Hans"). Regional tags fall back to their base language, then to the shipped "en" catalog.',
+    },
+    {
+      name: 'messages',
+      type: 'MessagesByLocale',
+      required: false,
+      description:
+        'Optional map of BCP 47 tag to translation catalog. The shipped "en" catalog is always available and does not need to be listed here.',
+    },
+    {
+      name: 'overrides',
+      type: 'Overrides',
+      required: false,
+      description:
+        'Sparse per-locale key overrides applied on top of shipped defaults. Overrides are locale-keyed so a runtime locale swap picks up the correct set.',
+    },
+    {
+      name: 'children',
+      type: 'ReactNode',
+      required: true,
+      description: 'Content to render with the internationalization provider.',
+    },
+  ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description:
+    'Wraps app to set active locale and (optionally) merge translation catalogs + per-locale overrides. Astryx components resolve strings against this context; missing keys fall back to shipped English.',
+  usage: {
+    description:
+      'Wraps app to set active locale and (optionally) merge translation catalogs + per-locale overrides. Astryx components resolve strings against this context; missing keys fall back to shipped English.',
+  },
+  propDescriptions: {
+    locale:
+      'BCP 47 language tag (e.g. "en", "pt-BR"); regional tags fall back to base language then "en"',
+    messages:
+      'map of BCP 47 tag to translation catalog; "en" is always available',
+    overrides:
+      'sparse per-locale key overrides applied on top of shipped defaults',
+  },
+};

package/src/i18n/InternationalizationProvider.tsx

@@ -0,0 +1,82 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file InternationalizationProvider.tsx
+ * @input React, InternationalizationContext, i18n types
+ * @output Exports InternationalizationProvider component and props type
+ * @position Provider component for astryx i18n locale + messages
+ *
+ * Wraps a subtree with a locale and (optional) additional message catalogs +
+ * overrides. Astryx components inside the subtree resolve their strings via
+ * this context. If a consumer never renders a provider, astryx components
+ * still work — they use the shipped en catalog directly.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/InternationalizationContext.ts
+ * - /packages/core/src/i18n/index.ts
+ * - /packages/core/src/i18n/InternationalizationProvider.doc.mjs
+ */
+
+import {useMemo, type ReactNode} from 'react';
+import {InternationalizationContext} from './InternationalizationContext';
+import type {Locale, MessagesByLocale, Overrides} from './types';
+
+export interface InternationalizationProviderProps {
+  /**
+   * BCP 47 language tag. Examples: `'en'`, `'pt'`, `'pt-BR'`, `'zh-Hans'`.
+   *
+   * Regional tags are respected — resolving a message walks the tag from
+   * most-specific to least-specific (`pt-BR` → `pt`), then falls back to
+   * the shipped `en` catalog.
+   */
+  locale: Locale;
+  /**
+   * Additional shipped catalogs to make available for the selected locale.
+   * `en` is bundled with astryx and never needs to be listed here.
+   *
+   * @example
+   * ```
+   * import {fr} from '@astryxdesign/core/locales/fr.json';
+   * <InternationalizationProvider locale="fr" messages={{fr}}>
+   * ```
+   */
+  messages?: MessagesByLocale;
+  /**
+   * Sparse per-locale overrides applied on top of shipped defaults.
+   * Only the keys you want to override need to be listed.
+   *
+   * @example
+   * ```
+   * <InternationalizationProvider
+   *   locale="fr"
+   *   overrides={{fr: {'@astryx.pagination.next': 'Suivant'}}}>
+   * ```
+   */
+  overrides?: Overrides;
+  children: ReactNode;
+}
+
+/**
+ * Provides locale + additional messages + overrides to all astryx
+ * components in the subtree.
+ */
+export function InternationalizationProvider({
+  locale,
+  messages,
+  overrides,
+  children,
+}: InternationalizationProviderProps) {
+  const value = useMemo(
+    () => ({locale, messages: messages ?? {}, overrides}),
+    [locale, messages, overrides],
+  );
+  return (
+    <InternationalizationContext value={value}>
+      {children}
+    </InternationalizationContext>
+  );
+}
+
+InternationalizationProvider.displayName = 'InternationalizationProvider';

package/src/i18n/__tests__/e2e-pagination.test.tsx

@@ -0,0 +1,172 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file e2e-pagination.test.tsx
+ * @input packages/core/src/Pagination, packages/core/src/i18n
+ * @output End-to-end tests proving the i18n framework actually swaps
+ *   strings in real component output.
+ * @position Integration test: real component + real provider + real catalog.
+ *   Not a unit test of resolve() — that's covered in resolve.test.ts.
+ *
+ * These assertions render <Pagination> and check that:
+ *   1. Default (no provider): English strings appear
+ *   2. With pseudo locale: accented+bracketed strings appear
+ *   3. With sparse override: only the overridden key changes
+ *   4. Regional locale fallback: pt-BR falls back to pt then en
+ *   5. Number formatting respects the locale (en-US vs de-DE separators)
+ */
+
+import {describe, test, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {Pagination} from '../../Pagination';
+import {InternationalizationProvider} from '../InternationalizationProvider';
+import pseudoCatalog from '../../../locales/pseudo.json';
+
+describe('Pagination × i18n — end to end', () => {
+  test('renders English strings by default (no provider)', () => {
+    render(
+      <Pagination
+        page={2}
+        totalItems={100}
+        pageSize={10}
+        onChange={() => {}}
+        variant="count"
+      />,
+    );
+
+    // The nav landmark uses the default label "Pagination"
+    expect(
+      screen.getByRole('navigation', {name: 'Pagination'}),
+    ).toBeInTheDocument();
+
+    // Prev/Next buttons carry English aria-labels
+    expect(
+      screen.getByRole('button', {name: 'Go to previous page'}),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', {name: 'Go to next page'}),
+    ).toBeInTheDocument();
+
+    // The visible count text is "11–20 of 100"
+    expect(screen.getByText(/11.20 of 100/)).toBeInTheDocument();
+  });
+
+  test('renders pseudo strings when provider locale is pseudo', () => {
+    render(
+      <InternationalizationProvider
+        locale="pseudo"
+        messages={{pseudo: pseudoCatalog}}>
+        <Pagination
+          page={2}
+          totalItems={100}
+          pageSize={10}
+          onChange={() => {}}
+          variant="count"
+        />
+      </InternationalizationProvider>,
+    );
+
+    // Nav landmark shows pseudo-translated label
+    expect(
+      screen.getByRole('navigation', {name: /Þàĝíñàţíóñ/}),
+    ).toBeInTheDocument();
+
+    // Prev/Next aria-labels are pseudo-translated
+    expect(
+      screen.getByRole('button', {name: /Ĝó ţó þřéṽíóúš/}),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', {name: /Ĝó ţó ñéẋţ/}),
+    ).toBeInTheDocument();
+
+    // Visible count is pseudo-wrapped; numbers still format
+    expect(screen.getByText(/⟦11.20 óƒ 100⟧/)).toBeInTheDocument();
+  });
+
+  test('sparse override changes only the overridden key', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {'@astryx.pagination.next': 'Suivant'},
+        }}>
+        <Pagination
+          page={2}
+          totalItems={100}
+          pageSize={10}
+          onChange={() => {}}
+        />
+      </InternationalizationProvider>,
+    );
+
+    // Overridden key: French
+    expect(screen.getByRole('button', {name: 'Suivant'})).toBeInTheDocument();
+
+    // NON-overridden keys fall through to English (fr has no other catalog)
+    expect(
+      screen.getByRole('navigation', {name: 'Pagination'}),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', {name: 'Go to previous page'}),
+    ).toBeInTheDocument();
+  });
+
+  test('regional locale (pt-BR) falls back to base language (pt)', () => {
+    // pt-BR has one key, pt has another, en fills in the rest.
+    // Tests the resolveLocaleChain walking through resolve() end to end.
+    render(
+      <InternationalizationProvider
+        locale="pt-BR"
+        messages={{
+          'pt-BR': {
+            '@astryx.pagination.next': {defaultMessage: 'Próxima (BR)'},
+          },
+          pt: {
+            '@astryx.pagination.previous': {defaultMessage: 'Anterior'},
+          },
+        }}>
+        <Pagination
+          page={2}
+          totalItems={100}
+          pageSize={10}
+          onChange={() => {}}
+        />
+      </InternationalizationProvider>,
+    );
+
+    // next: from pt-BR
+    expect(
+      screen.getByRole('button', {name: 'Próxima (BR)'}),
+    ).toBeInTheDocument();
+
+    // previous: from pt (fallback pt-BR → pt)
+    expect(screen.getByRole('button', {name: 'Anterior'})).toBeInTheDocument();
+
+    // label: neither pt-BR nor pt has it — falls back to en
+    expect(
+      screen.getByRole('navigation', {name: 'Pagination'}),
+    ).toBeInTheDocument();
+  });
+
+  test('ICU number formatting respects the locale', () => {
+    // In de-DE, 1000 formats with "." as the thousands separator.
+    render(
+      <InternationalizationProvider locale="de-DE">
+        <Pagination
+          page={2}
+          totalItems={10000}
+          pageSize={10}
+          onChange={() => {}}
+          variant="count"
+        />
+      </InternationalizationProvider>,
+    );
+
+    // We didn't provide a de-DE catalog — the string is en's pattern but
+    // numbers format under the de-DE locale, so "10000" becomes "10.000".
+    // Text is: "11–20 of 10.000"
+    // The dash between 11 and 20 is unicode en-dash (\u2013), match loosely
+    // by asserting the presence of the German-formatted 10.000.
+    expect(screen.getByText(/10\.000/)).toBeInTheDocument();
+  });
+});

package/src/i18n/__tests__/e2e-powersearch.test.tsx

@@ -0,0 +1,130 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file e2e-powersearch.test.tsx
+ * @input packages/core/src/PowerSearch, packages/core/src/i18n
+ * @output End-to-end tests proving the i18n framework swaps strings inside
+ *   PowerSearch's shipped-default operators AND UI chrome.
+ * @position Integration test: real PowerSearch + real provider + real catalog.
+ *
+ * The point of these tests is to prove that:
+ *   1. Astryx's default operators (built via `usePowerSearchConfig`) look
+ *      up their labels through `t()` at render time — so an
+ *      InternationalizationProvider swap changes them without touching
+ *      the config object.
+ *   2. Consumer-provided operators with a raw `label` field are used
+ *      verbatim (no lookup).
+ *   3. Consumer-provided operators with an `i18nKey` field are resolved
+ *      against provider `overrides` / `messages`.
+ *   4. ICU plurals in result counts and value formatting swap per locale.
+ */
+
+import {describe, test, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import React, {useMemo} from 'react';
+import {PowerSearch, usePowerSearchConfig} from '../../PowerSearch';
+import type {FieldDefinition, PowerSearchFilter} from '../../PowerSearch';
+import {InternationalizationProvider} from '../InternationalizationProvider';
+import pseudoCatalog from '../../../locales/pseudo.json';
+
+// Small harness — usePowerSearchConfig is a hook, so tests must render it
+// via a component.
+function Harness({
+  fieldDefs,
+  filters,
+}: {
+  fieldDefs: ReadonlyArray<FieldDefinition>;
+  filters: ReadonlyArray<PowerSearchFilter>;
+}) {
+  const {config} = usePowerSearchConfig(fieldDefs);
+  const stableFilters = useMemo(() => filters, [filters]);
+  return (
+    <PowerSearch
+      config={config}
+      filters={stableFilters}
+      onChange={() => {}}
+      resultCount={2}
+    />
+  );
+}
+
+const nameField: FieldDefinition = {
+  key: 'name',
+  type: 'string',
+  label: 'Name',
+};
+
+describe('PowerSearch × i18n — end to end', () => {
+  test('renders English default operator labels with no provider', () => {
+    const filter: PowerSearchFilter = {
+      field: 'name',
+      operator: 'contains',
+      value: {type: 'string', value: 'ada'},
+    };
+    render(<Harness fieldDefs={[nameField]} filters={[filter]} />);
+
+    // The token displays field label + `: <operator label>` + value.
+    // The `contains` default operator should surface its English label.
+    expect(screen.getByText(/Name: contains/i)).toBeInTheDocument();
+  });
+
+  test('resultCount uses ICU plural (2 results → "results")', () => {
+    render(<Harness fieldDefs={[nameField]} filters={[]} />);
+    expect(screen.getByText('2 results')).toBeInTheDocument();
+  });
+
+  test('pseudo locale wraps default operator labels', () => {
+    const filter: PowerSearchFilter = {
+      field: 'name',
+      operator: 'contains',
+      value: {type: 'string', value: 'ada'},
+    };
+    render(
+      <InternationalizationProvider
+        locale="pseudo"
+        messages={{pseudo: pseudoCatalog}}>
+        <Harness fieldDefs={[nameField]} filters={[filter]} />
+      </InternationalizationProvider>,
+    );
+
+    // Pseudo catalog wraps every en value in ⟦...⟧, so the default label
+    // "contains" becomes "⟦çöñţäîñš⟧" — token now shows "Name: ⟦çöñţäîñš⟧ ada"
+    // (the field label "Name" is consumer-provided, not translated).
+    expect(screen.getByText(/Name:.*⟦.*⟧/)).toBeInTheDocument();
+  });
+
+  test('provider overrides translate default operator labels', () => {
+    const filter: PowerSearchFilter = {
+      field: 'name',
+      operator: 'contains',
+      value: {type: 'string', value: 'ada'},
+    };
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {'@astryx.powersearch.operator.contains': 'contient'},
+        }}>
+        <Harness fieldDefs={[nameField]} filters={[filter]} />
+      </InternationalizationProvider>,
+    );
+
+    expect(screen.getByText(/Name: contient/)).toBeInTheDocument();
+  });
+
+  test('resultCount ICU plural swaps under provider overrides', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {
+            '@astryx.powersearch.resultCount':
+              '{count, number} {count, plural, one {résultat} other {résultats}}',
+          },
+        }}>
+        <Harness fieldDefs={[nameField]} filters={[]} />
+      </InternationalizationProvider>,
+    );
+    expect(screen.getByText('2 résultats')).toBeInTheDocument();
+  });
+});