@astryxdesign/core 0.1.5 → 0.1.6-canary.02f2602

package/src/hooks/useHotkeys.doc.mjs

@@ -10,7 +10,7 @@ export const docs = {
       name: 'hotkeys',
       type: 'Hotkey[]',
       description:
-        'Shortcut registrations. Each entry: `{ keys, onPress, allowInInputs?, isDisabled? }`. `keys` is a "+"-separated combo like "mod+k", "shift+/", "escape" — "mod" is ⌘ on macOS and Ctrl elsewhere. `onPress` receives the KeyboardEvent after preventDefault(). `allowInInputs` (default false) lets the hotkey fire while typing in inputs/textareas/selects/contenteditable. `isDisabled` temporarily disables the entry.',
+        'Shortcut registrations. Each entry: `{ keys, onPress, allowInInputs?, isDisabled? }`. `keys` is a "+"-separated combo like "mod+k", "shift+/", "escape"; "mod" is ⌘ on macOS and Ctrl elsewhere. `onPress` receives the KeyboardEvent after preventDefault(). `allowInInputs` (default false) lets the hotkey fire while typing in inputs/textareas/selects/contenteditable. `isDisabled` temporarily disables the entry.',
       required: true,
     },
   ],
@@ -20,7 +20,7 @@ export const docs = {
       'Registers global keyboard shortcuts with a single window keydown listener per hook instance. Handlers live in a ref, so re-renders never re-subscribe. Skips events from typing targets (input, textarea, select, contenteditable) unless allowInInputs, skips defaultPrevented events, and calls preventDefault() on match. SSR-safe.',
     bestPractices: [
       { guidance: true, description: 'Use for app-level shortcuts like command palettes (mod+k), help overlays (shift+/), and navigation keys.' },
-      { guidance: true, description: 'Pair with the Kbd component to display the same combo you register — both resolve "mod" per platform identically.' },
+      { guidance: true, description: 'Pair with the Kbd component to display the same combo you register; both resolve "mod" per platform identically.' },
       { guidance: true, description: 'Use isDisabled to suspend shortcuts while a modal or wizard owns the keyboard, instead of unmounting the hook.' },
       { guidance: false, description: 'Use for focus-scoped keyboard navigation inside a widget; use useListFocus or useGridFocus instead.' },
     ],
@@ -34,17 +34,17 @@ export const docs = {
 /** @type {import('../docs-types').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'Global keyboard shortcuts w/ one window keydown listener per hook instance. Handlers kept in ref — re-renders never re-subscribe. Skips typing targets (input/textarea/select/contenteditable) unless allowInInputs, skips defaultPrevented, preventDefault() on match. "mod" = ⌘ on macOS, Ctrl elsewhere. SSR-safe.',
+    'Global keyboard shortcuts w/ one window keydown listener per hook instance. Handlers kept in ref; re-renders never re-subscribe. Skips typing targets (input/textarea/select/contenteditable) unless allowInInputs, skips defaultPrevented, preventDefault() on match. "mod" = ⌘ on macOS, Ctrl elsewhere. SSR-safe.',
   paramDescriptions: {
     hotkeys:
       'array of { keys, onPress, allowInInputs?, isDisabled? }. keys = "+"-separated combo ("mod+k", "shift+/", "escape").',
   },
   usage: {
     description:
-      'Global keyboard shortcuts w/ one window keydown listener per hook instance. Handlers kept in ref — re-renders never re-subscribe. Skips typing targets unless allowInInputs, skips defaultPrevented, preventDefault() on match. SSR-safe.',
+      'Global keyboard shortcuts w/ one window keydown listener per hook instance. Handlers kept in ref; re-renders never re-subscribe. Skips typing targets unless allowInInputs, skips defaultPrevented, preventDefault() on match. SSR-safe.',
     bestPractices: [
       { guidance: true, description: 'Use for app-level shortcuts: command palettes (mod+k), help overlays (shift+/), navigation keys.' },
-      { guidance: true, description: 'Pair w/ Kbd component to display same combo registered — both resolve "mod" per platform identically.' },
+      { guidance: true, description: 'Pair w/ Kbd component to display same combo registered; both resolve "mod" per platform identically.' },
       { guidance: true, description: 'Use isDisabled to suspend shortcuts while modal/wizard owns keyboard, instead of unmounting hook.' },
       { guidance: false, description: 'Use for focus-scoped keyboard nav inside widget; use useListFocus / useGridFocus instead.' },
     ],

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,83 @@
+// 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();
+  });
+});