@astryxdesign/core 0.1.6-canary.1b61ba6 → 0.1.6-canary.1d64659

package/src/i18n/__tests__/resolve.test.ts

@@ -1,284 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file resolve.test.ts
- * @input packages/core/src/i18n/resolve.ts
- * @output Unit tests for the shared i18n lookup + format core
- * @position Colocated tests; targets locale-chain fallback, ICU formatting,
- *   overrides, and missing-key behavior.
- */
-
-import {describe, expect, test, beforeEach, vi} from 'vitest';
-import {__resetForTests, resolve, resolveLocaleChain} from '../resolve';
-import type {Catalog, MessagesByLocale, Overrides} from '../types';
-
-// Reset caches between tests so warn-once and formatter cache don't bleed.
-beforeEach(() => {
-  __resetForTests();
-});
-
-describe('resolveLocaleChain', () => {
-  test('single-part tag returns single-item chain', () => {
-    expect(resolveLocaleChain('en')).toEqual(['en']);
-  });
-
-  test('regional tag walks to base language', () => {
-    expect(resolveLocaleChain('pt-BR')).toEqual(['pt-BR', 'pt']);
-  });
-
-  test('script-tagged locale walks to script and then base', () => {
-    expect(resolveLocaleChain('zh-Hans-CN')).toEqual([
-      'zh-Hans-CN',
-      'zh-Hans',
-      'zh',
-    ]);
-  });
-
-  test('canonicalizes casing via Intl.Locale', () => {
-    // Consumers who pass "en-us" (lowercase region) should get the canonical
-    // BCP 47 form back so lookups match spec-canonical catalog keys.
-    expect(resolveLocaleChain('en-us')).toEqual(['en-US', 'en']);
-    expect(resolveLocaleChain('PT-br')).toEqual(['pt-BR', 'pt']);
-  });
-
-  test('malformed input falls back to the raw string chain', () => {
-    // Intl.Locale throws on invalid input; we don't want the whole render to
-    // die because a consumer passed a bad tag.
-    expect(resolveLocaleChain('not_a_locale')).toEqual(['not_a_locale']);
-  });
-});
-
-describe('resolve — basic lookup', () => {
-  test('falls back to shipped en catalog when locale is en and no messages passed', () => {
-    // The shipped en.json is imported at module load; Pagination keys should
-    // resolve. This asserts the module wiring works end-to-end.
-    const out = resolve(
-      '@astryx.pagination.next',
-      undefined,
-      'en',
-      {},
-      undefined,
-    );
-    expect(out).toBe('Go to next page');
-  });
-
-  test('returns the key itself and warns for unknown key', () => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const out = resolve(
-      '@astryx.does.not.exist',
-      undefined,
-      'en',
-      {},
-      undefined,
-    );
-    expect(out).toBe('@astryx.does.not.exist');
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining('missing key'));
-    warn.mockRestore();
-  });
-});
-
-describe('resolve — provider messages', () => {
-  const catalog: Catalog = {
-    '@astryx.pagination.next': {defaultMessage: 'Suivant'},
-  };
-  const messages: MessagesByLocale = {fr: catalog};
-
-  test('uses provider messages for the current locale', () => {
-    const out = resolve(
-      '@astryx.pagination.next',
-      undefined,
-      'fr',
-      messages,
-      undefined,
-    );
-    expect(out).toBe('Suivant');
-  });
-
-  test('falls back to en for keys not in the provider catalog, silently', () => {
-    // pagination.previous is only in en; fr catalog has only .next.
-    // Missing translations for a locale are expected during rollout — the
-    // fallback should be silent (matches i18next / FormatJS default). We
-    // reserve console.warn for real bugs (key missing even from en).
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const out = resolve(
-      '@astryx.pagination.previous',
-      undefined,
-      'fr',
-      messages,
-      undefined,
-    );
-    expect(out).toBe('Go to previous page');
-    expect(warn).not.toHaveBeenCalled();
-    warn.mockRestore();
-  });
-});
-
-describe('resolve — locale-chain fallback (regional → language)', () => {
-  const messages: MessagesByLocale = {
-    'pt-BR': {
-      '@astryx.pagination.next': {defaultMessage: 'Próxima (BR)'},
-    },
-    pt: {
-      '@astryx.pagination.next': {defaultMessage: 'Próxima'},
-      '@astryx.pagination.previous': {defaultMessage: 'Anterior'},
-    },
-  };
-
-  test('exact regional match wins', () => {
-    const out = resolve(
-      '@astryx.pagination.next',
-      undefined,
-      'pt-BR',
-      messages,
-      undefined,
-    );
-    expect(out).toBe('Próxima (BR)');
-  });
-
-  test('falls back to base language when regional entry missing', () => {
-    // pt-BR catalog has no .previous — should walk pt-BR → pt
-    const out = resolve(
-      '@astryx.pagination.previous',
-      undefined,
-      'pt-BR',
-      messages,
-      undefined,
-    );
-    expect(out).toBe('Anterior');
-  });
-
-  test('falls back to en when neither regional nor base has the key', () => {
-    // pt-BR nor pt has .label — walk to en
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const out = resolve(
-      '@astryx.pagination.label',
-      undefined,
-      'pt-BR',
-      messages,
-      undefined,
-    );
-    expect(out).toBe('Pagination');
-    warn.mockRestore();
-  });
-});
-
-describe('resolve — overrides', () => {
-  test('per-locale override wins over shipped catalog', () => {
-    const messages: MessagesByLocale = {
-      fr: {'@astryx.pagination.next': {defaultMessage: 'Suivant'}},
-    };
-    const overrides: Overrides = {
-      fr: {'@astryx.pagination.next': 'Suiv.'},
-    };
-    const out = resolve(
-      '@astryx.pagination.next',
-      undefined,
-      'fr',
-      messages,
-      overrides,
-    );
-    expect(out).toBe('Suiv.');
-  });
-
-  test('overrides respect the locale chain (pt-BR → pt)', () => {
-    // Override defined at pt level, current locale is pt-BR
-    const overrides: Overrides = {
-      pt: {'@astryx.pagination.next': 'Próxima (pt override)'},
-    };
-    const out = resolve(
-      '@astryx.pagination.next',
-      undefined,
-      'pt-BR',
-      {},
-      overrides,
-    );
-    expect(out).toBe('Próxima (pt override)');
-  });
-
-  test('override for a different locale does not apply', () => {
-    const overrides: Overrides = {
-      es: {'@astryx.pagination.next': 'Siguiente'},
-    };
-    const out = resolve(
-      '@astryx.pagination.next',
-      undefined,
-      'fr',
-      {},
-      overrides,
-    );
-    // Should fall through to en since fr has no messages and es override doesn't apply
-    expect(out).toBe('Go to next page');
-  });
-});
-
-describe('resolve — ICU MessageFormat', () => {
-  test('interpolates simple named placeholders', () => {
-    const out = resolve(
-      '@astryx.pagination.goToPage',
-      {page: 5},
-      'en',
-      {},
-      undefined,
-    );
-    expect(out).toContain('5');
-    expect(out).toMatch(/Go to page/);
-  });
-
-  test('formats numbers using Intl.NumberFormat for the locale', () => {
-    // Pagination.count uses {from, number}, {to, number}, {total, number}
-    // In en-US, 1000 formats as "1,000"
-    const out = resolve(
-      '@astryx.pagination.count',
-      {from: 1, to: 10, total: 1000},
-      'en-US',
-      {},
-      undefined,
-    );
-    expect(out).toContain('1,000');
-  });
-
-  test('formats numbers for locales with different separators', () => {
-    // In de-DE, 1000 formats as "1.000"
-    const out = resolve(
-      '@astryx.pagination.count',
-      {from: 1, to: 10, total: 1000},
-      'de-DE',
-      {},
-      undefined,
-    );
-    // We don't have a de catalog so falls back to en's PATTERN, but the
-    // number formatting uses the locale passed to IntlMessageFormat.
-    expect(out).toContain('1.000');
-  });
-
-  test('handles plural forms with ICU {n, plural, one {} other {}} pattern', () => {
-    const catalog: Catalog = {
-      'test.items': {
-        defaultMessage:
-          '{count, plural, =0 {no items} one {# item} other {# items}}',
-      },
-    };
-    const messages = {en: catalog};
-
-    expect(resolve('test.items', {count: 0}, 'en', messages, undefined)).toBe(
-      'no items',
-    );
-    expect(resolve('test.items', {count: 1}, 'en', messages, undefined)).toBe(
-      '1 item',
-    );
-    expect(resolve('test.items', {count: 5}, 'en', messages, undefined)).toBe(
-      '5 items',
-    );
-  });
-});
-
-describe('resolve — warn-once behavior', () => {
-  test('duplicate missing-key warnings are suppressed', () => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    resolve('@astryx.does.not.exist', undefined, 'en', {}, undefined);
-    resolve('@astryx.does.not.exist', undefined, 'en', {}, undefined);
-    resolve('@astryx.does.not.exist', undefined, 'en', {}, undefined);
-    expect(warn).toHaveBeenCalledTimes(1);
-    warn.mockRestore();
-  });
-});

package/src/i18n/index.ts

@@ -1,32 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file index.ts
- * @input Imports from InternationalizationProvider, InternationalizationContext,
- *   useTranslator, translator, types
- * @output Public surface for the i18n subpackage
- * @position Component entry point; re-exported by /packages/core/src/index.ts
- *
- * The public API is deliberately small:
- *   - InternationalizationProvider — provider component
- *   - useTranslator               — hook returning a translator function
- *   - Translator                  — interface for consumer-injected runtimes
- *
- * SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/index.ts
- */
-
-export {InternationalizationProvider} from './InternationalizationProvider';
-export type {InternationalizationProviderProps} from './InternationalizationProvider';
-export {InternationalizationContext} from './InternationalizationContext';
-export type {InternationalizationContextValue} from './InternationalizationContext';
-export {useTranslator} from './useTranslator';
-export type {TranslatorFn} from './useTranslator';
-export type {Translator} from './translator';
-export type {
-  Locale,
-  Catalog,
-  MessageEntry,
-  MessagesByLocale,
-  Overrides,
-} from './types';

package/src/i18n/resolve.ts

@@ -1,165 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file resolve.ts
- * @input Key + values + locale + catalog + overrides
- * @output Formatted message string
- * @position Shared lookup + ICU formatting core, used by useTranslator().
- *
- * Lookup order:
- *   1. Per-locale override for the exact locale
- *   2. Per-locale override for a parent locale (pt-BR → pt)
- *   3. Shipped catalog entry for the exact locale
- *   4. Shipped catalog entry for a parent locale (pt-BR → pt)
- *   5. Shipped en catalog (the source of truth, always present)
- *   6. The key itself (dev-visible fallback, warns once)
- *
- * SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/i18n/useTranslator.ts
- * - /packages/core/src/i18n/__tests__/resolve.test.ts
- */
-
-import IntlMessageFormat from 'intl-messageformat';
-import type {Catalog, Locale, MessagesByLocale, Overrides} from './types';
-import enSource from '../../locales/en.json' with {type: 'json'};
-
-const EN_CATALOG = enSource as Catalog;
-
-/**
- * Cache of parsed ICU MessageFormat objects keyed by `${locale}::${message}`.
- * IntlMessageFormat parsing is non-trivial; caching avoids reparsing on every
- * render. The cache is unbounded in principle but bounded in practice by the
- * static set of astryx keys.
- */
-const formatterCache = new Map<string, IntlMessageFormat>();
-
-function getFormatter(message: string, locale: Locale): IntlMessageFormat {
-  const cacheKey = `${locale}::${message}`;
-  let f = formatterCache.get(cacheKey);
-  if (f === undefined) {
-    f = new IntlMessageFormat(message, locale);
-    formatterCache.set(cacheKey, f);
-  }
-  return f;
-}
-
-/**
- * Walk a BCP 47 tag from most-specific to least-specific.
- * Input is canonicalized via `Intl.Locale.baseName` so `pt-br` and `PT-BR`
- * both produce `['pt-BR', 'pt']`.
- *
- * Examples:
- *   'pt-BR'      → ['pt-BR', 'pt']
- *   'zh-Hans-CN' → ['zh-Hans-CN', 'zh-Hans', 'zh']
- *   'en'         → ['en']
- *
- * `en` is intentionally NOT appended here — the caller falls back to the
- * shipped en catalog separately as the final source-of-truth.
- */
-export function resolveLocaleChain(locale: Locale): Locale[] {
-  let canonical: string;
-  try {
-    canonical = new Intl.Locale(locale).baseName;
-  } catch {
-    // Malformed input — fall back to the raw string so callers still get a chain.
-    canonical = locale;
-  }
-  const parts = canonical.split('-');
-  const chain: Locale[] = [];
-  for (let i = parts.length; i > 0; i--) {
-    chain.push(parts.slice(0, i).join('-'));
-  }
-  return chain;
-}
-
-/**
- * Missing-key warn-once tracking. Fires ONLY when a key is missing from
- * every source including the shipped `en` catalog — that's a real bug
- * (typo, stale catalog, deleted key). Fallback to `en` from a non-en
- * locale is expected and silent, matching the FormatJS / i18next default
- * of not spamming the console when a translation simply hasn't been
- * written yet.
- */
-const warnedMissing = new Set<string>();
-
-function warnOnce(bucket: Set<string>, key: string, message: string): void {
-  if (!bucket.has(key)) {
-    bucket.add(key);
-    console.warn(message);
-  }
-}
-
-function lookup(
-  key: string,
-  locale: Locale,
-  messages: MessagesByLocale,
-  overrides: Overrides | undefined,
-): string | null {
-  const chain = resolveLocaleChain(locale);
-
-  // 1 + 2. Overrides (most specific to least specific in the chain)
-  if (overrides !== undefined) {
-    for (const tag of chain) {
-      const value = overrides[tag]?.[key];
-      if (value !== undefined) {
-        return value;
-      }
-    }
-  }
-
-  // 3 + 4. Shipped catalogs (most specific to least specific)
-  for (const tag of chain) {
-    const entry = messages[tag]?.[key];
-    if (entry !== undefined) {
-      return entry.defaultMessage;
-    }
-  }
-
-  // 5. Shipped en catalog — always present
-  const enEntry = EN_CATALOG[key];
-  if (enEntry !== undefined) {
-    return enEntry.defaultMessage;
-  }
-
-  // 6. Nothing found
-  return null;
-}
-
-export function resolve(
-  key: string,
-  values: Record<string, unknown> | undefined,
-  locale: Locale,
-  messages: MessagesByLocale,
-  overrides: Overrides | undefined,
-): string {
-  const result = lookup(key, locale, messages, overrides);
-
-  if (result === null) {
-    warnOnce(
-      warnedMissing,
-      `${locale}::${key}`,
-      `[astryx-i18n] missing key: ${key} (locale: ${locale})`,
-    );
-    return key;
-  }
-
-  if (values === undefined) {
-    // Static string — skip the parser entirely for the common case
-    return result;
-  }
-
-  const formatted = getFormatter(result, locale).format(values);
-  // IntlMessageFormat.format returns string | (string | React elements) — we
-  // only ever pass string values so it will be a string; assert for the type
-  // system.
-  return formatted as string;
-}
-
-/**
- * Reset internal caches. Test-only.
- * @internal
- */
-export function __resetForTests(): void {
-  formatterCache.clear();
-  warnedMissing.clear();
-}

package/src/i18n/translator.ts

@@ -1,31 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file translator.ts
- * @input Translator interface for consumer i18n runtime injection
- * @output Type surface for pluggable translators
- * @position Public API for i18n adapter integration
- *
- * Consumers who already run an i18n runtime (react-intl, Lingui, i18next, etc.)
- * can inject their own Translator instead of using the default provider. The
- * interface is deliberately small so any real i18n library can satisfy it in a
- * few lines.
- *
- * SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/i18n/index.ts
- */
-
-/**
- * A Translator formats ICU MessageFormat strings for a given locale.
- * Consumers can supply their own to reuse their existing i18n runtime.
- */
-export interface Translator {
-  /**
-   * Format an ICU MessageFormat message with values in the given locale.
-   */
-  format(
-    message: string,
-    values?: Record<string, unknown>,
-    locale?: string,
-  ): string;
-}

package/src/i18n/types.ts

@@ -1,53 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file types.ts
- * @input None
- * @output Shared types for the i18n subpackage
- * @position Type-only module; used across client + server t() implementations
- *
- * SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/i18n/InternationalizationContext.ts
- * - /packages/core/src/i18n/InternationalizationProvider.tsx
- * - /packages/core/src/i18n/serverStore.ts
- * - /packages/core/src/i18n/resolve.ts
- */
-
-/**
- * A BCP 47 language tag. Examples: `'en'`, `'pt'`, `'pt-BR'`, `'zh-Hans'`.
- *
- * Regional tags are meaningful — `pt-BR` and `pt` are different catalogs.
- * When resolving a message, the runtime walks the tag from most-specific
- * to least-specific and falls back to `en` if nothing matches
- * (see `resolveLocaleChain` in `resolve.ts`).
- */
-export type Locale = string;
-
-/**
- * A single entry in a translation catalog. The `defaultMessage` is an ICU
- * MessageFormat string; `description` is optional context for translators
- * (surfaced by Crowdin's `react_intl` file type parser).
- */
-export interface MessageEntry {
-  defaultMessage: string;
-  description?: string;
-}
-
-/**
- * A translation catalog — a map of stable message keys to entries.
- * Astryx's own keys are namespaced under `@astryx.<component>.<name>`.
- */
-export type Catalog = Record<string, MessageEntry>;
-
-/**
- * A map of BCP 47 tags to catalogs. Passed as `messages` on
- * `<InternationalizationProvider>`.
- */
-export type MessagesByLocale = Record<Locale, Catalog>;
-
-/**
- * Sparse per-locale overrides applied on top of the shipped defaults.
- * Only the keys the consumer cares to override need to be listed.
- * Overrides are locale-keyed so a runtime locale swap picks up the right ones.
- */
-export type Overrides = Partial<Record<Locale, Record<string, string>>>;

package/src/i18n/useTranslator.doc.mjs

@@ -1,46 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('../docs-types').HookDoc} */
-export const docs = {
-  name: 'useTranslator',
-  displayName: 'useTranslator',
-  group: 'Utilities',
-  keywords: [
-    'i18n',
-    'internationalization',
-    'localization',
-    'translation',
-    'translate',
-    'locale',
-    'hook',
-  ],
-  params: [],
-  returns: [
-    {
-      name: 'value',
-      type: '(key: string, values?: Record<string, string | number | Date>) => string',
-      description:
-        'A stable translator function bound to the current InternationalizationProvider context. Call it with a message key and optional ICU MessageFormat values to get the formatted string in the active locale. Safe to use in render, event handlers, effects, or any code that runs during the parent component\'s lifecycle.',
-    },
-  ],
-  usage: {
-    description:
-      'Returns a translator function that resolves keys against the current locale, provider overrides, and the shipped English fallback catalog. Call inside a component; the returned function can be used anywhere within that component\'s scope.',
-  },
-  relatedComponents: ['InternationalizationProvider'],
-  importPath: '@astryxdesign/core',
-};
-
-/** @type {import('../docs-types').HookTranslationDoc} */
-export const docsDense = {
-  description:
-    'Hook returning a translator function bound to the current InternationalizationProvider context. Call with an ICU MessageFormat key and values to get the formatted string for the active locale.',
-  usage: {
-    description:
-      'Returns a translator function that resolves keys against the current locale, provider overrides, and the shipped English fallback catalog.',
-  },
-  returnDescriptions: {
-    value:
-      'translator function bound to current InternationalizationProvider context. Call with message key + optional ICU MessageFormat values; returns formatted string in active locale. Safe in render, event handlers, effects.',
-  },
-};

package/src/i18n/useTranslator.ts

@@ -1,50 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-/**
- * @file useTranslator.ts
- * @input InternationalizationContext (via use())
- * @output Exports useTranslator hook returning a stable translator function
- * @position Client-side hook for translating outside of render (event handlers,
- *   effects, non-component code) while still resolving against the current
- *   provider's locale.
- *
- * Prefer `t()` for translations at the callsite during render. When you need
- * to translate inside an event handler or effect, capture a translator during
- * render via useTranslator() and call it later.
- *
- * SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/i18n/index.ts
- * - /packages/core/src/i18n/t.client.ts
- */
-
-import {use, useCallback} from 'react';
-import {InternationalizationContext} from './InternationalizationContext';
-import {resolve} from './resolve';
-
-export type TranslatorFn = (
-  key: string,
-  values?: Record<string, unknown>,
-) => string;
-
-/**
- * Returns a translator function bound to the current provider's locale.
- * Safe to call from event handlers and effects.
- *
- * @example
- * ```
- * function MyComponent() {
- *   const translate = useTranslator();
- *   const onClick = () => announce(translate('@astryx.pagination.pageAnnounce', {current: 1}));
- * }
- * ```
- */
-export function useTranslator(): TranslatorFn {
-  const ctx = use(InternationalizationContext);
-  return useCallback(
-    (key: string, values?: Record<string, unknown>) =>
-      resolve(key, values, ctx.locale, ctx.messages, ctx.overrides),
-    [ctx.locale, ctx.messages, ctx.overrides],
-  );
-}