@pharos-ds/core 0.1.9

package/src/hooks/useTypeahead.ts

@@ -0,0 +1,183 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useTypeahead.ts
+ * @input Uses React useCallback/useRef
+ * @output Exports useTypeahead hook for first-character (type-to-focus) search
+ * @position Core hook; adds APG typeahead to menus, listboxes, and other
+ *   collections. Composes with useListFocus/useGridFocus (or any collection)
+ *   via a caller-supplied getItemLabels + onMatch.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ */
+
+import {useCallback, useRef} from 'react';
+
+export interface UseTypeaheadOptions {
+  /**
+   * Returns the current, in-DOM-order list of item labels to match against.
+   * An entry may be `null`/empty to mark a non-matchable slot (its index is
+   * preserved so it maps 1:1 to the caller's items).
+   */
+  getItemLabels: () => ReadonlyArray<string | null | undefined>;
+
+  /**
+   * Called with the index of the matched item so the caller can focus/select
+   * it (e.g. `useListFocus`'s `focusItem`).
+   */
+  onMatch: (index: number) => void;
+
+  /**
+   * The index to start searching from — typically the currently focused item,
+   * so repeated presses of the same letter cycle through matches. Defaults to
+   * -1 (search from the top).
+   */
+  getCurrentIndex?: () => number;
+
+  /**
+   * Milliseconds of inactivity after which the typed buffer resets.
+   * @default 750
+   */
+  resetMs?: number;
+
+  /**
+   * Whether an index should be skipped (e.g. disabled items).
+   */
+  isDisabled?: (index: number) => boolean;
+}
+
+export interface UseTypeaheadReturn {
+  /**
+   * Keydown handler. Call it (or let it fall through) from the collection's
+   * own key handler. Returns `true` when it handled a printable character (so
+   * the caller can `preventDefault`/stop further handling), `false` otherwise.
+   */
+  onKeyDown: (e: React.KeyboardEvent | KeyboardEvent) => boolean;
+  /** Clear the pending buffer (e.g. on close). */
+  reset: () => void;
+}
+
+/**
+ * Whether a key event represents a single printable character (a type-to-focus
+ * candidate) rather than a control/navigation key or a shortcut chord.
+ */
+function isPrintableCharacter(e: React.KeyboardEvent | KeyboardEvent): boolean {
+  return (
+    e.key.length === 1 &&
+    !e.ctrlKey &&
+    !e.metaKey &&
+    !e.altKey &&
+    // A lone space is used for activation in menus, not typeahead-from-empty.
+    e.key !== ' '
+  );
+}
+
+/**
+ * First-character ("type-ahead") search for a collection.
+ *
+ * Buffers printable keystrokes (resetting after `resetMs` of inactivity),
+ * matches items whose label starts with the buffer, and cycles from the
+ * current index — so pressing "s" repeatedly walks through the "s" items
+ * instead of sticking on the first. Space is reserved for activation and is
+ * only treated as typeahead while a buffer is already active.
+ *
+ * Additive and collection-agnostic: it does not move focus itself; the caller
+ * wires `onMatch` to its own focus/selection (e.g. `useListFocus.focusItem`).
+ *
+ * @example
+ * ```
+ * const {listRef, handleKeyDown, focusItem, getItems} = useListFocus(...);
+ * const typeahead = useTypeahead({
+ *   getItemLabels: () => getItems().map(el => el.textContent),
+ *   onMatch: focusItem,
+ *   getCurrentIndex: () => getItems().findIndex(el => el === document.activeElement),
+ * });
+ * const onKeyDown = (e) => { if (!typeahead.onKeyDown(e)) handleKeyDown(e); };
+ * ```
+ */
+export function useTypeahead(options: UseTypeaheadOptions): UseTypeaheadReturn {
+  const {
+    getItemLabels,
+    onMatch,
+    getCurrentIndex,
+    resetMs = 750,
+    isDisabled,
+  } = options;
+
+  const bufferRef = useRef('');
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(
+    undefined,
+  );
+
+  const reset = useCallback(() => {
+    bufferRef.current = '';
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = undefined;
+    }
+  }, []);
+
+  const scheduleReset = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+    timeoutRef.current = setTimeout(() => {
+      bufferRef.current = '';
+      timeoutRef.current = undefined;
+    }, resetMs);
+  }, [resetMs]);
+
+  const onKeyDown = useCallback(
+    (e: React.KeyboardEvent | KeyboardEvent): boolean => {
+      // A bare Space with no active buffer is not typeahead (menus activate on
+      // Space); once the user is mid-typing, Space extends the query.
+      const isSpaceMidType = e.key === ' ' && bufferRef.current.length > 0;
+      if (!isPrintableCharacter(e) && !isSpaceMidType) {
+        return false;
+      }
+
+      const labels = getItemLabels();
+      if (labels.length === 0) {
+        return false;
+      }
+
+      // Pressing the SAME single character repeatedly cycles to the next match
+      // rather than filtering deeper (APG behavior).
+      const char = e.key.toLowerCase();
+      const isRepeatSameChar =
+        bufferRef.current.length > 0 &&
+        bufferRef.current.split('').every(c => c === char);
+      const nextBuffer = isRepeatSameChar ? char : bufferRef.current + char;
+      bufferRef.current = nextBuffer;
+      scheduleReset();
+
+      const start = getCurrentIndex?.() ?? -1;
+      const count = labels.length;
+      // When repeating a single char, start the search AFTER the current item
+      // so we advance; otherwise include the current item.
+      const offset = isRepeatSameChar ? 1 : 0;
+
+      for (let i = 0; i < count; i++) {
+        const index = (start + offset + i + count) % count;
+        if (isDisabled?.(index)) {
+          continue;
+        }
+        const label = labels[index];
+        if (
+          label != null &&
+          label.trim().toLowerCase().startsWith(nextBuffer)
+        ) {
+          onMatch(index);
+          return true;
+        }
+      }
+      return true;
+    },
+    [getItemLabels, onMatch, getCurrentIndex, scheduleReset, isDisabled],
+  );
+
+  return {onKeyDown, reset};
+}

package/src/i18n/InternationalizationContext.ts

@@ -0,0 +1,43 @@
+// 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/useDirection.ts
+ * - /packages/core/src/i18n/getLocaleDirection.ts
+ * - /packages/core/src/i18n/index.ts
+ */
+
+import {createContext} from 'react';
+import type {Locale, MessagesByLocale, Overrides} from './types';
+
+export interface InternationalizationContextValue {
+  locale: Locale;
+  direction: 'ltr' | 'rtl';
+  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',
+    direction: 'ltr',
+    messages: {},
+  });
+InternationalizationContext.displayName = 'InternationalizationContext';

package/src/i18n/InternationalizationProvider.doc.mjs

@@ -0,0 +1,169 @@
+// 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. Pharos components inside the subtree resolve their strings against this context. If no provider is present, components fall back to the shipped English defaults.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use shipped Pharos locale catalogs from `@pharos-ds/core/locales/*` when one exists for your target locale.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use a same-shape local catalog only when Pharos has not shipped that locale yet or you are testing in-progress translations.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use real BCP 47 tags such as `fr`, `pt-BR`, or `ar`; regional locales fall back to their base language before English.',
+      },
+      {
+        guidance: false,
+        description:
+          'Cast custom catalog maps to `any`; the i18n package exports `MessagesByLocale` and `Catalog` for local catalog typing.',
+      },
+    ],
+  },
+  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. Import shipped catalogs from `@pharos-ds/core/locales/*`; 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.',
+    },
+  ],
+  examples: [
+    {
+      label: 'Load a shipped Pharos locale catalog',
+      code: `import type {ReactNode} from 'react';
+import {InternationalizationProvider} from '@pharos-ds/core/i18n';
+import frFR from '@pharos-ds/core/locales/fr-FR.json';
+
+export function AppI18n({children}: {children: ReactNode}) {
+  return (
+    <InternationalizationProvider locale="fr-FR" messages={{'fr-FR': frFR}}>
+      {children}
+    </InternationalizationProvider>
+  );
+}`,
+    },
+    {
+      label: 'Override one Pharos string',
+      code: `import type {ReactNode} from 'react';
+import {InternationalizationProvider} from '@pharos-ds/core/i18n';
+
+export function AppI18n({children}: {children: ReactNode}) {
+  return (
+    <InternationalizationProvider
+      locale="en"
+      overrides={{
+        en: {'@pharos.selector.placeholder': 'Choose...'},
+      }}
+    >
+      {children}
+    </InternationalizationProvider>
+  );
+}`,
+    },
+    {
+      label: 'Provide a local fallback catalog',
+      code: `import type {ReactNode} from 'react';
+import {
+  InternationalizationProvider,
+  type MessagesByLocale,
+} from '@pharos-ds/core/i18n';
+import ptBR from './locales/pt-BR.json';
+
+const messages: MessagesByLocale = {'pt-BR': ptBR};
+
+export function AppI18n({children}: {children: ReactNode}) {
+  return (
+    <InternationalizationProvider locale="pt-BR" messages={messages}>
+      {children}
+    </InternationalizationProvider>
+  );
+}`,
+    },
+  ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description:
+    'Wraps app to set active locale and (optionally) merge translation catalogs + per-locale overrides. Pharos 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. Pharos components resolve strings against this context; missing keys fall back to shipped English.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use shipped Pharos locale catalogs from `@pharos-ds/core/locales/*` when one exists for the target locale.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use a same-shape local catalog only when Pharos has not shipped that locale yet or when testing in-progress translations.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use real BCP 47 tags like `fr`, `pt-BR`, or `ar`; regional locales fall back to base language before English.',
+      },
+      {
+        guidance: false,
+        description:
+          'Cast custom catalog maps to `any`; the i18n package exports `MessagesByLocale` and `Catalog` for local catalog typing.',
+      },
+    ],
+  },
+  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,92 @@
+// 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 pharos i18n locale + messages
+ *
+ * Wraps a subtree with a locale and (optional) additional message catalogs +
+ * overrides. Pharos components inside the subtree resolve their strings via
+ * this context. If a consumer never renders a provider, pharos 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 {getLocaleDirection} from './getLocaleDirection';
+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 pharos and never needs to be listed here.
+   *
+   * @example
+   * ```
+   * import {fr} from '@pharos-ds/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: {'@pharos.pagination.next': 'Suivant'}}}>
+   * ```
+   */
+  overrides?: Overrides;
+  /**
+   * Optional explicit text direction override. When omitted, direction is derived
+   * from `locale` via `Intl.Locale.getTextInfo()`. Provide this to force a
+   * direction (e.g. RTL layout testing under an English catalog) or to skip the
+   * derivation when you already know the direction.
+   */
+  dir?: 'ltr' | 'rtl';
+  children: ReactNode;
+}
+
+/**
+ * Provides locale + additional messages + overrides to all pharos
+ * components in the subtree.
+ */
+export function InternationalizationProvider({
+  locale,
+  messages,
+  overrides,
+  dir,
+  children,
+}: InternationalizationProviderProps) {
+  const direction = dir ?? getLocaleDirection(locale);
+  const value = useMemo(
+    () => ({locale, direction, messages: messages ?? {}, overrides}),
+    [locale, direction, 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: {'@pharos.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': {
+            '@pharos.pagination.next': {defaultMessage: 'Próxima (BR)'},
+          },
+          pt: {
+            '@pharos.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();
+  });
+});