@open-mercato/shared 0.7.1-develop.7181.1.702cedc42c → 0.7.1-develop.7182.1.789943f937

package/src/lib/i18n/__tests__/__fixtures__/locale-augmentation-ok.ts

@@ -0,0 +1,28 @@
+// Fixture: what a downstream application writes to serve a language the
+// platform does not ship. Compiled by `locale-augmentation.test.ts`, never by
+// the package typecheck (tsconfig excludes `__tests__`), because the
+// augmentation would otherwise widen `Locale` for the whole package.
+import type { Locale } from '../../config'
+
+declare module '../../config' {
+  interface LocaleRegistry {
+    cs: true
+  }
+}
+
+// The new code is now a valid Locale — no patching of node_modules required.
+export const appAddedLocale: Locale = 'cs'
+
+// The shipped ones still are.
+export const shippedLocale: Locale = 'pl'
+
+// And exhaustiveness is preserved over the app's OWN extended set: this map
+// compiles only because it covers all six.
+export const labels: Record<Locale, string> = {
+  en: 'English',
+  pl: 'Polski',
+  es: 'Español',
+  de: 'Deutsch',
+  ko: '한국어',
+  cs: 'čeština',
+}

package/src/lib/i18n/__tests__/__fixtures__/locale-unaugmented.ts

@@ -0,0 +1,5 @@
+// Fixture: with no augmentation in the program, an unshipped code must still be
+// rejected — the zero-config guarantee. Expected to produce a diagnostic.
+import type { Locale } from '../../config'
+
+export const unregistered: Locale = 'cs'

package/src/lib/i18n/__tests__/context-supported-locales.test.tsx

@@ -0,0 +1,134 @@
+import * as React from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { I18nProvider, useLocaleLocked, useSupportedLocales } from '../context'
+import { clearRegisteredLocales, registerLocales } from '../locale-registry'
+import type { Locale } from '../config'
+
+function LocaleList() {
+  const supported = useSupportedLocales()
+  return React.createElement('span', null, supported.join(','))
+}
+
+function LocaleLockedFlag() {
+  return React.createElement('span', null, String(useLocaleLocked()))
+}
+
+function render(props: { locale: Locale; dict: {}; supportedLocales?: readonly Locale[] }) {
+  return renderToStaticMarkup(
+    React.createElement(I18nProvider, props, React.createElement(LocaleList)),
+  )
+}
+
+describe('useSupportedLocales', () => {
+  afterEach(() => {
+    clearRegisteredLocales()
+  })
+
+  it('falls back to the shipped set when the provider is given no prop', () => {
+    // Every existing test mounts `<I18nProvider locale dict />` with no
+    // `supportedLocales`; that must keep working and keep today's list.
+    expect(render({ locale: 'en', dict: {} })).toContain('en,pl,es,de,ko')
+  })
+
+  it('reflects locales the app registered at runtime', () => {
+    registerLocales(['cs'])
+
+    expect(render({ locale: 'en', dict: {} })).toContain('en,pl,es,de,ko,cs')
+  })
+
+  it('prefers the server-resolved prop over the process-local registry', () => {
+    // This is the whole point of the prop: a client bundle cannot read tenant
+    // configuration, so the server narrows the set and hands it down.
+    registerLocales(['cs'])
+
+    const markup = render({
+      locale: 'en',
+      dict: {},
+      supportedLocales: ['en', 'pl'] as readonly Locale[],
+    })
+
+    expect(markup).toContain('en,pl')
+    expect(markup).not.toContain('cs')
+  })
+
+  it('carries a locale the platform does not ship down to the client', () => {
+    const markup = render({
+      locale: 'cs' as Locale,
+      dict: {},
+      supportedLocales: ['en', 'cs'] as readonly Locale[],
+    })
+
+    expect(markup).toContain('en,cs')
+  })
+
+  it('returns the shipped set outside any provider', () => {
+    expect(renderToStaticMarkup(React.createElement(LocaleList))).toContain('en,pl,es,de,ko')
+  })
+
+  it('inherits the served set from an enclosing provider when the prop is omitted', () => {
+    // The backend layout mounts a second provider inside the root layout's. An
+    // omitted prop there must mean "unchanged", not "reset to the registry",
+    // or the whole admin subtree silently loses the tenant narrowing.
+    const markup = renderToStaticMarkup(
+      React.createElement(
+        I18nProvider,
+        { locale: 'en' as Locale, dict: {}, supportedLocales: ['en', 'pl'] as readonly Locale[] },
+        React.createElement(
+          I18nProvider,
+          { locale: 'en' as Locale, dict: {} },
+          React.createElement(LocaleList),
+        ),
+      ),
+    )
+
+    expect(markup).toContain('en,pl')
+    expect(markup).not.toContain('es')
+  })
+
+  it('lets an inner provider override the inherited set', () => {
+    const markup = renderToStaticMarkup(
+      React.createElement(
+        I18nProvider,
+        { locale: 'en' as Locale, dict: {}, supportedLocales: ['en', 'pl'] as readonly Locale[] },
+        React.createElement(
+          I18nProvider,
+          { locale: 'en' as Locale, dict: {}, supportedLocales: ['en', 'de'] as readonly Locale[] },
+          React.createElement(LocaleList),
+        ),
+      ),
+    )
+
+    expect(markup).toContain('en,de')
+  })
+})
+
+describe('useLocaleLocked', () => {
+  it('inherits the locked flag from an enclosing provider when the prop is omitted', () => {
+    const markup = renderToStaticMarkup(
+      React.createElement(
+        I18nProvider,
+        { locale: 'en' as Locale, dict: {}, localeLocked: true },
+        React.createElement(
+          I18nProvider,
+          { locale: 'en' as Locale, dict: {} },
+          React.createElement(LocaleLockedFlag),
+        ),
+      ),
+    )
+
+    expect(markup).toContain('true')
+  })
+
+  it('is false outside any provider and for a provider that sets nothing', () => {
+    expect(renderToStaticMarkup(React.createElement(LocaleLockedFlag))).toContain('false')
+    expect(
+      renderToStaticMarkup(
+        React.createElement(
+          I18nProvider,
+          { locale: 'en' as Locale, dict: {} },
+          React.createElement(LocaleLockedFlag),
+        ),
+      ),
+    ).toContain('false')
+  })
+})

package/src/lib/i18n/__tests__/detect-locale-narrowed.test.ts

@@ -0,0 +1,109 @@
+import type { Locale } from '../config'
+
+// `detectLocale` reaches for `next/headers` through a dynamic import, so the
+// mock has to be in place before the module under test is loaded.
+const cookieStore = { value: undefined as string | undefined }
+const headerStore = { acceptLanguage: '' }
+
+jest.mock(
+  'next/headers',
+  () => ({
+    cookies: async () => ({
+      get: (name: string) =>
+        name === 'locale' && cookieStore.value ? { value: cookieStore.value } : undefined,
+    }),
+    headers: async () => ({
+      get: (name: string) =>
+        name.toLowerCase() === 'accept-language' ? headerStore.acceptLanguage : null,
+    }),
+  }),
+  { virtual: true },
+)
+
+import { detectLocale } from '../server'
+import { clearRegisteredLocales, registerLocales } from '../locale-registry'
+
+const NARROWED: readonly Locale[] = ['pl', 'de']
+
+describe('detectLocale with a narrowed supported set', () => {
+  beforeEach(() => {
+    cookieStore.value = undefined
+    headerStore.acceptLanguage = ''
+    delete process.env.OM_FORCE_LOCALE
+  })
+
+  afterEach(() => {
+    clearRegisteredLocales()
+  })
+
+  it('honours a cookie that is inside the narrowed set', async () => {
+    cookieStore.value = 'de'
+
+    await expect(detectLocale({ supportedLocales: NARROWED })).resolves.toBe('de')
+  })
+
+  it('ignores a cookie that the tenant has since deselected', async () => {
+    cookieStore.value = 'es'
+    headerStore.acceptLanguage = 'pl-PL,pl;q=0.9'
+
+    await expect(detectLocale({ supportedLocales: NARROWED })).resolves.toBe('pl')
+  })
+
+  it('ignores an Accept-Language match outside the narrowed set', async () => {
+    headerStore.acceptLanguage = 'es-ES,es;q=0.9'
+
+    // `es` is a shipped locale, so `resolveLocaleFromAcceptLanguage` matches it;
+    // the narrowed set is what rejects it.
+    await expect(detectLocale({ supportedLocales: NARROWED })).resolves.not.toBe('es')
+  })
+
+  it('falls through to a lower-ranked header entry that is inside the set', async () => {
+    // Header ranks `es` first, but the tenant does not serve it. Matching the
+    // header against the process-wide set and re-checking afterwards would
+    // discard the whole header on the `es` match and land on the default; the
+    // narrowed set has to reach the matcher itself for `de` to win.
+    headerStore.acceptLanguage = 'es-ES,es;q=0.9,de;q=0.8'
+
+    await expect(detectLocale({ supportedLocales: NARROWED })).resolves.toBe('de')
+  })
+
+  it('never returns a locale outside the set it was given', async () => {
+    // The regression this guards: the fallback used to be an unconditional
+    // `return defaultLocale`, which rendered an English page under a switcher
+    // offering only Polish and German.
+    headerStore.acceptLanguage = 'en-US,en;q=0.9'
+
+    const detected = await detectLocale({ supportedLocales: NARROWED })
+
+    expect(NARROWED).toContain(detected)
+  })
+
+  it('falls back to the default locale when it is in the set', async () => {
+    headerStore.acceptLanguage = 'fr-FR,fr;q=0.9'
+
+    await expect(detectLocale({ supportedLocales: ['en', 'pl'] })).resolves.toBe('en')
+  })
+
+  it('keeps the previous behaviour when no set is passed', async () => {
+    headerStore.acceptLanguage = 'es-ES,es;q=0.9'
+
+    await expect(detectLocale()).resolves.toBe('es')
+  })
+
+  it('still lets OM_FORCE_LOCALE win over the narrowed set', async () => {
+    process.env.OM_FORCE_LOCALE = 'ko'
+
+    try {
+      await expect(detectLocale({ supportedLocales: NARROWED })).resolves.toBe('ko')
+    } finally {
+      delete process.env.OM_FORCE_LOCALE
+    }
+  })
+
+  it('detects a locale the app registered but the platform does not ship', async () => {
+    registerLocales(['cs'])
+    cookieStore.value = 'cs'
+
+    await expect(detectLocale({ supportedLocales: ['en', 'cs'] as readonly Locale[] })).resolves.toBe('cs')
+  })
+})

package/src/lib/i18n/__tests__/dictionary-locale-fallback.test.ts

@@ -0,0 +1,110 @@
+import {
+  loadDictionary,
+  registerModules,
+  registerAppDictionaryLoader,
+  invalidateDictionaryCache,
+} from '../server'
+import { clearRegisteredLocales, registerLocales } from '../locale-registry'
+import type { Locale } from '../config'
+
+// Dictionaries keyed by locale, standing in for the app's `i18n/<locale>.json`
+// files. `cs` deliberately has no entry, which is the situation an operator
+// creates by enabling a language nobody has translated yet.
+const APP_DICTIONARIES: Record<string, Record<string, unknown>> = {
+  en: { greeting: 'Hello', onlyInEnglish: 'English only' },
+  pl: { greeting: 'Cześć' },
+}
+
+describe('dictionary fallback for locales the platform does not ship', () => {
+  beforeEach(() => {
+    clearRegisteredLocales()
+    registerModules([] as any)
+    registerAppDictionaryLoader(async (locale: Locale) => APP_DICTIONARIES[locale] ?? {})
+    invalidateDictionaryCache()
+  })
+
+  afterEach(() => {
+    clearRegisteredLocales()
+    invalidateDictionaryCache()
+  })
+
+  describe('shipped locales keep their exact previous behaviour', () => {
+    it('does not layer English underneath another shipped locale', async () => {
+      const pl = await loadDictionary('pl')
+
+      expect(pl).toEqual({ greeting: 'Cześć' })
+      // The key that exists only in English must NOT leak into Polish — that
+      // would be a behaviour change for locales that ship today.
+      expect(pl).not.toHaveProperty('onlyInEnglish')
+    })
+
+    it('leaves the default locale itself untouched', async () => {
+      await expect(loadDictionary('en')).resolves.toEqual({
+        greeting: 'Hello',
+        onlyInEnglish: 'English only',
+      })
+    })
+
+    it('returns an empty dictionary for a shipped locale with no strings', async () => {
+      await expect(loadDictionary('de')).resolves.toEqual({})
+    })
+  })
+
+  describe('an app-registered locale', () => {
+    it('falls back to the default locale instead of rendering raw keys', async () => {
+      registerLocales(['cs'])
+
+      await expect(loadDictionary('cs' as Locale)).resolves.toEqual({
+        greeting: 'Hello',
+        onlyInEnglish: 'English only',
+      })
+    })
+
+    it('overlays its own translations on top of the default ones', async () => {
+      registerLocales(['cs'])
+      APP_DICTIONARIES.cs = { greeting: 'Ahoj' }
+
+      try {
+        await expect(loadDictionary('cs' as Locale)).resolves.toEqual({
+          greeting: 'Ahoj',
+          onlyInEnglish: 'English only',
+        })
+      } finally {
+        delete APP_DICTIONARIES.cs
+      }
+    })
+
+    it('lets module translations win over the default-locale base layer', async () => {
+      registerLocales(['cs'])
+      registerModules([{ translations: { cs: { greeting: 'Ahoj z modulu' } } }] as any)
+
+      const cs = await loadDictionary('cs' as Locale)
+
+      expect(cs.greeting).toBe('Ahoj z modulu')
+      expect(cs.onlyInEnglish).toBe('English only')
+    })
+
+    it('is still memoized per locale', async () => {
+      registerLocales(['cs'])
+
+      const first = await loadDictionary('cs' as Locale)
+      const second = await loadDictionary('cs' as Locale)
+
+      expect(first).toBe(second)
+    })
+
+    it('does not mutate the default-locale dictionary it copies from', async () => {
+      registerLocales(['cs'])
+      APP_DICTIONARIES.cs = { greeting: 'Ahoj' }
+
+      try {
+        await loadDictionary('cs' as Locale)
+        const en = await loadDictionary('en')
+
+        expect(en.greeting).toBe('Hello')
+      } finally {
+        delete APP_DICTIONARIES.cs
+      }
+    })
+  })
+})

package/src/lib/i18n/__tests__/locale-augmentation.test.ts

@@ -0,0 +1,56 @@
+import * as path from 'node:path'
+import * as ts from 'typescript'
+
+// The extension point is a TYPE-level contract, so the only honest way to test
+// it is to compile a downstream-app fixture and read the diagnostics. Jest runs
+// with `isolatedModules: true` and therefore never type-checks, and the package
+// typecheck cannot cover these fixtures either: a `declare module` augmentation
+// is program-global, so including them would widen `Locale` for every other file
+// in the package (and break `config.typecheck.tsx`). Hence a real, isolated
+// `ts.createProgram` per fixture.
+const FIXTURES_DIR = path.join(__dirname, '__fixtures__')
+
+// Mirrors `tsconfig.base.json`; only the options that affect these diagnostics.
+const COMPILER_OPTIONS: ts.CompilerOptions = {
+  target: ts.ScriptTarget.ES2022,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  strict: true,
+  skipLibCheck: true,
+  noEmit: true,
+  esModuleInterop: true,
+}
+
+function compile(fixture: string): ts.Diagnostic[] {
+  const program = ts.createProgram([path.join(FIXTURES_DIR, fixture)], COMPILER_OPTIONS)
+  return [...program.getSemanticDiagnostics(), ...program.getSyntacticDiagnostics()]
+}
+
+function messages(diagnostics: ts.Diagnostic[]): string[] {
+  return diagnostics.map((d) => ts.flattenDiagnosticMessageText(d.messageText, ' '))
+}
+
+describe('extending Locale from a downstream application', () => {
+  it('lets an app add a locale the platform does not ship, with no patching', () => {
+    const diagnostics = compile('locale-augmentation-ok.ts')
+
+    expect(messages(diagnostics)).toEqual([])
+  })
+
+  it('still rejects an unshipped code when the app has NOT opted in', () => {
+    const diagnostics = compile('locale-unaugmented.ts')
+
+    expect(diagnostics).toHaveLength(1)
+    expect(messages(diagnostics)[0]).toContain('"cs"')
+  })
+
+  it('preserves exhaustiveness over the app’s own extended set', () => {
+    // An app that widens Locale keeps its drift guard: a Record<Locale, …> that
+    // omits the locale it just added must not compile. This is the property that
+    // widening `Locale` to `string` would have silently destroyed.
+    const diagnostics = compile('locale-augmentation-missing-key.ts')
+
+    expect(diagnostics).toHaveLength(1)
+    expect(messages(diagnostics)[0]).toContain('cs')
+  })
+})

package/src/lib/i18n/__tests__/locale-label.test.ts

@@ -0,0 +1,141 @@
+import { resolveLocaleLabel } from '../locale-label'
+import type { TranslateFn } from '../context'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+// Walks the transitive *value* imports of a module (`import type` excluded, since
+// those vanish at compile time) and returns the module basenames reached. A
+// source scan rather than a `require.cache` diff because Jest's module registry
+// is already warm from this file's own imports by the time any test runs.
+function collectValueImports(entry: string, from = __dirname, seen = new Set<string>()): string[] {
+  const resolved = path.resolve(from, `${entry}.ts`)
+  const basename = path.basename(resolved, '.ts')
+  if (seen.has(basename) || !fs.existsSync(resolved)) return [...seen]
+  seen.add(basename)
+
+  const source = fs.readFileSync(resolved, 'utf8')
+  const importPattern = /^import\s+(?!type\s)(?:[^'"]*?\sfrom\s+)?['"](\.[^'"]+)['"]/gm
+  for (const match of source.matchAll(importPattern)) {
+    collectValueImports(match[1]!, path.dirname(resolved), seen)
+  }
+  return [...seen]
+}
+
+// Mirrors how `LanguageSwitcher` and `PayPage` call it: a real translator that
+// falls back to the inline default when the key is absent from the dictionary.
+function makeTranslator(dict: Record<string, string> = {}): TranslateFn {
+  return ((key: string, fallbackOrParams?: unknown) => {
+    const fallback = typeof fallbackOrParams === 'string' ? fallbackOrParams : undefined
+    return dict[key] ?? fallback ?? key
+  }) as TranslateFn
+}
+
+describe('resolveLocaleLabel', () => {
+  describe('shipped locales without a translator (ProfileDropdown behaviour)', () => {
+    // These are the exact strings `ProfileDropdown` rendered from its hardcoded
+    // `Record<Locale, string>` before it was replaced — a visual regression guard.
+    it.each([
+      ['en', 'English'],
+      ['de', 'Deutsch'],
+      ['es', 'Español'],
+      ['pl', 'Polski'],
+      ['ko', '한국어'],
+    ])('renders %s as the endonym %s', (locale, expected) => {
+      expect(resolveLocaleLabel(locale)).toBe(expected)
+    })
+  })
+
+  describe('shipped locales with a translator (LanguageSwitcher behaviour)', () => {
+    // The exact `t(key, fallback)` pairs the switcher used before the refactor.
+    it.each([
+      ['en', 'common.languages.english', 'English'],
+      ['pl', 'common.languages.polish', 'Polski'],
+      ['es', 'common.languages.spanish', 'Español'],
+      ['de', 'common.languages.german', 'Deutsch'],
+      ['ko', 'common.languages.korean', '한국어'],
+    ])('asks for %s via %s and falls back to %s', (locale, key, fallback) => {
+      const seen: string[] = []
+      const t = ((k: string, f?: unknown) => {
+        seen.push(k)
+        return typeof f === 'string' ? f : k
+      }) as TranslateFn
+
+      expect(resolveLocaleLabel(locale, t)).toBe(fallback)
+      expect(seen).toEqual([key])
+    })
+
+    it('prefers the dictionary value, so a German UI shows localized names', () => {
+      const t = makeTranslator({
+        'common.languages.polish': 'Polnisch',
+        'common.languages.english': 'Englisch',
+      })
+
+      expect(resolveLocaleLabel('pl', t)).toBe('Polnisch')
+      expect(resolveLocaleLabel('en', t)).toBe('Englisch')
+    })
+  })
+
+  describe('locales the platform does not ship', () => {
+    it('falls back to the endonym from Intl', () => {
+      expect(resolveLocaleLabel('cs')).toBe('čeština')
+      expect(resolveLocaleLabel('fr')).toBe('français')
+    })
+
+    it('uses the endonym even when a translator is supplied', () => {
+      // There is no `common.languages.*` key for an app-added locale, so the
+      // translator cannot help and must not produce a raw key.
+      expect(resolveLocaleLabel('cs', makeTranslator())).toBe('čeština')
+    })
+
+    it('never renders blank or a raw key', () => {
+      for (const locale of ['cs', 'fr', 'zh', 'sw', 'zzz']) {
+        const label = resolveLocaleLabel(locale)
+        expect(label.length).toBeGreaterThan(0)
+        expect(label).not.toContain('common.languages')
+      }
+    })
+  })
+
+  describe('degradation ladder', () => {
+    it('falls back to the uppercased code for an unknown code', () => {
+      // `zzz` is neither an ISO 639-1 entry nor known to Intl.
+      expect(resolveLocaleLabel('zzz')).toBe('ZZZ')
+    })
+
+    it('falls back to the uppercased code when Intl has no data', () => {
+      const displayNames = jest
+        .spyOn(Intl, 'DisplayNames')
+        .mockImplementation((() => ({ of: () => undefined })) as unknown as typeof Intl.DisplayNames)
+
+      try {
+        // `za` (Zhuang) is in the ISO 639-1 catalogue, but this module
+        // deliberately does not consult it — see the import-graph test below.
+        expect(resolveLocaleLabel('za')).toBe('ZA')
+      } finally {
+        displayNames.mockRestore()
+      }
+    })
+
+    it('survives Intl throwing on a malformed code', () => {
+      expect(() => resolveLocaleLabel('!!not a tag!!')).not.toThrow()
+      expect(resolveLocaleLabel('!!not a tag!!')).toBe('!!NOT A TAG!!')
+    })
+  })
+
+  describe('client bundle weight', () => {
+    // Every caller of `resolveLocaleLabel` is a client component, including the
+    // public checkout pay page. `iso639.ts` is a 186-entry table with a
+    // module-scope `Set` that no bundler can tree-shake, so pulling it in here
+    // would ship the whole language catalogue to that route.
+    it('does not pull the ISO 639-1 catalogue into its import graph', () => {
+      expect(collectValueImports('../locale-label')).not.toContain('iso639')
+    })
+
+    // Guards the guard: a walker that silently found nothing would pass the
+    // assertion above for the wrong reason. `locale-registry` does import the
+    // catalogue, transitively proving the traversal reaches real edges.
+    it('detects the catalogue where it is genuinely imported', () => {
+      expect(collectValueImports('../locale-registry')).toContain('iso639')
+    })
+  })
+})