@open-mercato/ui 0.8.1-develop.7275.1.f772b944d4 → 0.8.1-develop.7294.1.0ef99fc518

package/src/backend/__tests__/DataTable.metaHiddenLateColumns.test.tsx

@@ -6,7 +6,7 @@ import { render, screen, waitFor } from '@testing-library/react'
 import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { I18nProvider } from '@open-mercato/shared/lib/i18n/context'
-import { DataTable } from '../DataTable'
+import { DataTable, type DataTableViewApi } from '../DataTable'
 
 jest.mock('next/navigation', () => ({
   useRouter: () => ({ push: jest.fn(), replace: jest.fn(), prefetch: jest.fn(), refresh: jest.fn() }),
@@ -37,7 +37,11 @@ const COLUMNS_WITH_CUSTOM_FIELDS: ColumnDef<Row>[] = [
   { accessorKey: 'cf_active_note', header: 'Active note' },
 ]
 
-function Harness({ columns, initialSettings }: { columns: ColumnDef<Row>[]; initialSettings?: unknown }) {
+function Harness({ columns, initialSettings, apiRef }: {
+  columns: ColumnDef<Row>[]
+  initialSettings?: unknown
+  apiRef?: React.MutableRefObject<DataTableViewApi | null>
+}) {
   const queryClient = React.useMemo(
     () => new QueryClient({ defaultOptions: { queries: { retry: false, gcTime: 0 } } }),
     [],
@@ -48,6 +52,7 @@ function Harness({ columns, initialSettings }: { columns: ColumnDef<Row>[]; init
         <DataTable
           columns={columns as never}
           data={ROWS as never}
+          viewApiRef={apiRef}
           {...(initialSettings
             ? ({ perspective: { tableId: 'meta-hidden-late-columns', initialState: { initialSettings } } } as never)
             : {})}
@@ -58,6 +63,17 @@ function Harness({ columns, initialSettings }: { columns: ColumnDef<Row>[]; init
 }
 
 describe('DataTable — meta.hidden on columns that arrive after the first render', () => {
+  beforeEach(() => {
+    // DataTable persists the applied view to localStorage and a cookie, and jsdom shares
+    // both across the cases in a file — clear them so a perspective set up by one case
+    // cannot hydrate into the next one and decide its columns.
+    window.localStorage.clear()
+    for (const entry of document.cookie.split(';')) {
+      const name = entry.split('=')[0]?.trim()
+      if (name) document.cookie = `${name}=; Max-Age=0; Path=/`
+    }
+  })
+
   it('hides a meta.hidden column that only appears on a later render', async () => {
     // The regression: the auto-hide pass used to be latched by a single boolean ref, so it
     // ran on the first render — when no `cf_*` column existed yet — found nothing to hide,
@@ -91,8 +107,9 @@ describe('DataTable — meta.hidden on columns that arrive after the first rende
     expect(screen.queryByText('Archived note')).toBeNull()
   })
 
-  it('lets a stored perspective override the meta.hidden defaults', async () => {
-    // A saved perspective seeds columnVisibility at mount and wins outright.
+  it('lets a stored perspective override the meta.hidden default for a column it names', async () => {
+    // A saved perspective wins over the declared default — but only for the columns it
+    // actually names, which is what the two cases below pin down (#5117).
     render(
       <Harness
         columns={COLUMNS_WITH_CUSTOM_FIELDS}
@@ -102,4 +119,77 @@ describe('DataTable — meta.hidden on columns that arrive after the first rende
 
     await waitFor(() => expect(screen.getByText('Archived note')).toBeTruthy())
   })
+
+  it('still applies meta.hidden to a column the stored perspective does not name', async () => {
+    // The regression from #5117: the pass used to be latched on "the stored view carried
+    // *some* visibility", so a view that only spoke about `name` silently suppressed the
+    // declared default of every other column. A view can only decide what it describes.
+    render(
+      <Harness
+        columns={COLUMNS_WITH_CUSTOM_FIELDS}
+        initialSettings={{ columnVisibility: { name: true } }}
+      />,
+    )
+
+    await waitFor(() => expect(screen.getByText('Active note')).toBeTruthy())
+    expect(screen.queryByText('Archived note')).toBeNull()
+  })
+
+  it('applies meta.hidden to a late column that a stored perspective could not have named', async () => {
+    // The reported scenario: the view was saved before the custom-field columns resolved,
+    // so it cannot carry a decision for them. They must still fall back to their declared
+    // default instead of appearing mid-hydration.
+    const { rerender } = render(
+      <Harness columns={BASE_COLUMNS} initialSettings={{ columnVisibility: { name: true } }} />,
+    )
+    await waitFor(() => expect(screen.getByText('Name')).toBeTruthy())
+
+    rerender(
+      <Harness columns={COLUMNS_WITH_CUSTOM_FIELDS} initialSettings={{ columnVisibility: { name: true } }} />,
+    )
+
+    await waitFor(() => expect(screen.getByText('Active note')).toBeTruthy())
+    expect(screen.queryByText('Archived note')).toBeNull()
+  })
+
+  it('honours meta.hidden that a column def only gains on a later render', async () => {
+    // The per-column record must key on "a default was applied", not on "this id has been
+    // seen". Marking a column decided the first time it appears would strand a def whose
+    // `meta` resolves in a later wave — an injected column widget, say — as permanently
+    // undecided, and an undecided column renders visible.
+    const withoutMeta: ColumnDef<Row>[] = [
+      ...BASE_COLUMNS,
+      { accessorKey: 'cf_late_note', header: 'Late note' },
+    ]
+    const withMeta: ColumnDef<Row>[] = [
+      ...BASE_COLUMNS,
+      { accessorKey: 'cf_late_note', header: 'Late note', meta: { hidden: true } },
+    ]
+    const { rerender } = render(<Harness columns={withoutMeta} />)
+    await waitFor(() => expect(screen.getByText('Late note')).toBeTruthy())
+
+    rerender(<Harness columns={withMeta} />)
+
+    await waitFor(() => expect(screen.queryByText('Late note')).toBeNull())
+  })
+
+  it('describes every leaf column in the settings it hands back, including late arrivals', async () => {
+    // Root cause 1 of #5117: `getCurrentSettings` copied the sparse TanStack state, so a
+    // saved view stored no decision for columns that registered after the save and an
+    // absent key renders visible. The serialized map must be self-describing.
+    const apiRef = React.createRef<DataTableViewApi | null>() as React.MutableRefObject<DataTableViewApi | null>
+    const { rerender } = render(<Harness columns={BASE_COLUMNS} apiRef={apiRef} />)
+    await waitFor(() => expect(screen.getByText('Name')).toBeTruthy())
+
+    rerender(<Harness columns={COLUMNS_WITH_CUSTOM_FIELDS} apiRef={apiRef} />)
+    await waitFor(() => expect(screen.getByText('Active note')).toBeTruthy())
+
+    await waitFor(() => {
+      expect(apiRef.current?.getCurrentSettings().columnVisibility).toEqual({
+        name: true,
+        cf_archived_note: false,
+        cf_active_note: true,
+      })
+    })
+  })
 })

package/src/backend/__tests__/DataTable.saveViewApi.test.tsx

@@ -140,6 +140,13 @@ const columns: ColumnDef<Row>[] = [
   { accessorKey: 'id', header: 'Id' },
 ]
 
+// The shape the People / Companies / Deals lists actually render: a module column that
+// declares its own default (`hidden: def.listVisible === false`) next to ordinary ones.
+const COLUMNS_WITH_DECLARED_DEFAULT: ColumnDef<Row>[] = [
+  ...columns,
+  { accessorKey: 'cf_archived', header: 'Archived', meta: { hidden: true } } as ColumnDef<Row>,
+]
+
 type HarnessProps = {
   apiRef?: React.MutableRefObject<DataTableViewApi | null>
   onDirty?: (state: DataTableViewDirtyState) => void
@@ -149,6 +156,7 @@ type HarnessProps = {
   savedViews?: PerspectivesIndexResponse['perspectives']
   roleViews?: PerspectivesIndexResponse['rolePerspectives']
   initialSettings?: PerspectiveSettings
+  tableColumns?: ColumnDef<Row>[]
   /** `'granted'` seeds the permission check, `'denied'` seeds a refusal, `'pending'` leaves it in flight. */
   perspectivesFeature?: 'granted' | 'denied' | 'pending'
 }
@@ -162,6 +170,7 @@ function renderTable({
   savedViews = [],
   roleViews = [],
   initialSettings,
+  tableColumns = columns,
   perspectivesFeature = 'granted',
 }: HarnessProps) {
   const queryClient = new QueryClient({
@@ -183,7 +192,7 @@ function renderTable({
       <QueryClientProvider client={queryClient}>
         <I18nProvider locale="en" dict={{}}>
           <DataTable<Row>
-            columns={columns}
+            columns={tableColumns}
             data={[]}
             searchValue={searchValue}
             onSearchChange={() => {}}
@@ -460,6 +469,125 @@ describe('DataTable public save-view API', () => {
     await waitFor(() => expect(screen.getByTestId('save-view-trigger')).not.toBeDisabled())
   })
 
+  it('describes every column in the settings it serializes, without reporting a change nobody made', async () => {
+    // #5117: the serialized visibility used to be a verbatim copy of the sparse TanStack
+    // state, so a saved view carried no decision for columns the user never toggled and an
+    // absent key renders visible. It is now seeded from the full leaf-column set — and the
+    // dense map must still compare equal to the sparse one the server stored, or every
+    // table with a saved view would report unsaved changes the moment it mounted.
+    const apiRef = React.createRef<DataTableViewApi | null>() as React.MutableRefObject<DataTableViewApi | null>
+    const states: DataTableViewDirtyState[] = []
+    renderTable({
+      apiRef,
+      onDirty: (state) => { states.push(state) },
+      initialSettings: { columnVisibility: { name: false } },
+    })
+
+    await waitFor(() => expect(apiRef.current).not.toBeNull())
+    expect(apiRef.current!.getCurrentSettings().columnVisibility).toEqual({ name: false, id: true })
+
+    await waitFor(() => expect(states.length).toBeGreaterThan(0))
+    expect(states.every((state) => !state.isDirty)).toBe(true)
+  })
+
+  it('stays clean on a table carrying a meta.hidden column the stored view never named', async () => {
+    // The case the density change can break, and the one the assertion above cannot see:
+    // its columns declare no default, so there is nothing for the live state to diverge on.
+    // Once the `meta.hidden` pass is allowed to run underneath a stored view it writes a
+    // `false` the server's sparse map does not carry, and `normalizeVisibility` keeps every
+    // `false` — so without folding the declared default into the baseline as well, every
+    // People / Companies / Deals view would mount showing "1 unsaved change" nobody made.
+    const apiRef = React.createRef<DataTableViewApi | null>() as React.MutableRefObject<DataTableViewApi | null>
+    const states: DataTableViewDirtyState[] = []
+    renderTable({
+      apiRef,
+      onDirty: (state) => { states.push(state) },
+      tableColumns: COLUMNS_WITH_DECLARED_DEFAULT,
+      initialSettings: { columnVisibility: { name: false } },
+    })
+
+    await waitFor(() => expect(apiRef.current).not.toBeNull())
+    await waitFor(() => expect(apiRef.current!.getCurrentSettings().columnVisibility)
+      .toEqual({ name: false, id: true, cf_archived: false }))
+
+    await waitFor(() => expect(states.length).toBeGreaterThan(0))
+    expect(states.every((state) => !state.isDirty)).toBe(true)
+    expect(apiRef.current!.getDirtyState().isDirty).toBe(false)
+  })
+
+  it('stays clean on first mount of a table with a meta.hidden column and no stored view at all', async () => {
+    // The case neither test above can see: with no `initialSettings`, the baseline is not
+    // seeded from `useState`'s initializer — it is seeded later by the mount-time effect
+    // from `currentViewSettings`, which closes over the render that *scheduled* the
+    // meta.hidden hide, not the one where it took effect. `setViewBaseline` must let the
+    // auto-hidden default win over that stale snapshot, or the baseline records the column
+    // visible while the live state (correctly) goes hidden on the next render, reporting a
+    // change nobody made the moment the table mounts.
+    const apiRef = React.createRef<DataTableViewApi | null>() as React.MutableRefObject<DataTableViewApi | null>
+    const states: DataTableViewDirtyState[] = []
+    renderTable({
+      apiRef,
+      onDirty: (state) => { states.push(state) },
+      tableColumns: COLUMNS_WITH_DECLARED_DEFAULT,
+      showSaveViewButton: true,
+    })
+
+    await waitFor(() => expect(apiRef.current).not.toBeNull())
+    await waitFor(() => expect(apiRef.current!.getCurrentSettings().columnVisibility)
+      .toEqual({ name: true, id: true, cf_archived: false }))
+
+    await waitFor(() => expect(states.length).toBeGreaterThan(0))
+    expect(states.every((state) => !state.isDirty)).toBe(true)
+    expect(apiRef.current!.getDirtyState().isDirty).toBe(false)
+  })
+
+  it('keeps a stored visibility decision for a column that has not registered yet', async () => {
+    // Serializing from the live column set alone drops any stored key whose column is not
+    // in the table — every `cf_*` decision, during the whole custom-field hydration window.
+    // Transiently that reports the view dirty; permanently, a save inside that window
+    // writes the user's "hide this custom field" away for good.
+    const apiRef = React.createRef<DataTableViewApi | null>() as React.MutableRefObject<DataTableViewApi | null>
+    const states: DataTableViewDirtyState[] = []
+    renderTable({
+      apiRef,
+      onDirty: (state) => { states.push(state) },
+      initialSettings: { columnVisibility: { name: false, cf_not_loaded_yet: false } },
+    })
+
+    await waitFor(() => expect(apiRef.current).not.toBeNull())
+    expect(apiRef.current!.getCurrentSettings().columnVisibility)
+      .toEqual({ name: false, cf_not_loaded_yet: false, id: true })
+
+    await waitFor(() => expect(states.length).toBeGreaterThan(0))
+    expect(states.every((state) => !state.isDirty)).toBe(true)
+  })
+
+  it('restores a declared default when the view that overrode it is switched away from', async () => {
+    // `applyPerspectiveSettings` re-seeds the per-column record and bumps the pass counter
+    // so the defaults are re-evaluated for the newly applied view. A view with no
+    // visibility of its own is exactly what "— No view —" applies, so this pins the clear
+    // path too: the column must go back to its declared default rather than staying
+    // visible for the rest of the session because an earlier view once un-hid it.
+    const showsHidden = {
+      ...SAVED_VIEW,
+      id: 'persp-shows-hidden',
+      settings: { columnVisibility: { cf_archived: true } },
+    }
+    const saysNothing = { ...SAVED_VIEW, id: 'persp-says-nothing', settings: {} }
+    renderTable({
+      tableColumns: COLUMNS_WITH_DECLARED_DEFAULT,
+      savedViews: [showsHidden, saysNothing],
+    })
+
+    // The first saved view auto-activates on load, so the column starts overridden.
+    await waitFor(() => expect(screen.getByText('Archived')).toBeTruthy())
+
+    const activateSaysNothing = await screen.findByTestId('activate-view-persp-says-nothing')
+    await act(async () => { fireEvent.click(activateSaysNothing) })
+
+    await waitFor(() => expect(screen.queryByText('Archived')).toBeNull())
+  })
+
   it('sends an unnamed save to the sidebar instead of inventing a name', async () => {
     const { setSearchValue } = renderTable({ showSaveViewButton: true })
     const trigger = await screen.findByTestId('save-view-trigger')

package/src/backend/detail/InlineEditors.tsx

@@ -24,7 +24,19 @@ import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('ui')
 
-function resolveInlineErrorMessage(err: unknown, fallbackMessage: string): string {
+// Server validation errors arrive as stable i18n keys (e.g. `customers.people.form.*`), the
+// same contract CrudForm resolves via translateValidationMessage; without this they render
+// raw. `t(msg, msg)` is a no-op for already-localized strings.
+function resolveInlineErrorMessage(
+  err: unknown,
+  fallbackMessage: string,
+  translate: (key: string, fallback: string) => string,
+): string {
+  const raw = resolveRawInlineErrorMessage(err, fallbackMessage)
+  return translate(raw, raw)
+}
+
+function resolveRawInlineErrorMessage(err: unknown, fallbackMessage: string): string {
   const { message, fieldErrors } = mapCrudServerErrorToFormErrors(err)
   const firstFieldError = fieldErrors
     ? Object.values(fieldErrors).find((text) => typeof text === 'string' && text.trim().length)
@@ -223,11 +235,11 @@ export function InlineTextEditor({
       await onSave(trimmed.length ? trimmed : null)
       setEditingSafe(false)
     } catch (err) {
-      setError(resolveInlineErrorMessage(err, fallbackError))
+      setError(resolveInlineErrorMessage(err, fallbackError, t))
     } finally {
       setSaving(false)
     }
-  }, [draft, fallbackError, onSave, setEditingSafe, validator])
+  }, [draft, fallbackError, onSave, setEditingSafe, t, validator])
 
   const interactiveProps: React.HTMLAttributes<HTMLDivElement> =
     activateOnClick && !editing
@@ -363,7 +375,7 @@ export function InlineTextEditor({
                             await onSave(formatted.length ? formatted : null)
                             setEditingSafe(false)
                           } catch (err) {
-                            setError(resolveInlineErrorMessage(err, fallbackError))
+                            setError(resolveInlineErrorMessage(err, fallbackError, t))
                           } finally {
                             setSaving(false)
                           }
@@ -601,11 +613,11 @@ export function InlineMultilineEditor({
       await onSave(trimmed.length ? trimmed : null)
       setEditing(false)
     } catch (err) {
-      setError(resolveInlineErrorMessage(err, fallbackError))
+      setError(resolveInlineErrorMessage(err, fallbackError, t))
     } finally {
       setSaving(false)
     }
-  }, [adjustError, draft, fallbackError, onSave])
+  }, [adjustError, draft, fallbackError, onSave, t])
 
   return (
     <div className={containerClasses} onClick={handleInteractiveClick}>

package/src/backend/detail/__tests__/InlineEditors.test.tsx

@@ -137,3 +137,55 @@ describe('resolveSafeInlineUrlHref', () => {
     },
   )
 })
+
+describe('InlineTextEditor server validation errors are localized (#5925)', () => {
+  const EMAIL_INVALID_KEY = 'customers.people.form.primaryEmail.invalid'
+  const TRANSLATED = 'Wprowadź prawidłowy adres e-mail'
+
+  function renderEditorRejectingWith(err: unknown, dict: Record<string, string>) {
+    renderWithProviders(
+      <InlineTextEditor
+        label="Primary email"
+        value="ada@example.com"
+        emptyLabel="No email"
+        type="email"
+        onSave={jest.fn().mockRejectedValue(err)}
+      />,
+      { dict },
+    )
+
+    const buttons = document.querySelectorAll('[data-slot="button"]')
+    const editToggle = buttons[buttons.length - 1] as HTMLButtonElement
+    act(() => {
+      fireEvent.click(editToggle)
+    })
+  }
+
+  async function submit() {
+    const saveButton = screen.getByRole('button', { name: /Save|⌘/ })
+    await act(async () => {
+      fireEvent.click(saveButton)
+    })
+  }
+
+  it('renders the translation for a server field error carrying an i18n key', async () => {
+    const err = Object.assign(new Error('Invalid input'), {
+      details: [{ path: ['primaryEmail'], message: EMAIL_INVALID_KEY }],
+    })
+    renderEditorRejectingWith(err, { [EMAIL_INVALID_KEY]: TRANSLATED })
+    await submit()
+
+    expect(screen.getByText(TRANSLATED)).toBeInTheDocument()
+    expect(screen.queryByText(EMAIL_INVALID_KEY)).not.toBeInTheDocument()
+  })
+
+  it('leaves an already-localized server message untouched', async () => {
+    const err = Object.assign(new Error('Invalid input'), {
+      details: [{ path: ['primaryEmail'], message: 'Enter a valid email address' }],
+    })
+    renderEditorRejectingWith(err, { [EMAIL_INVALID_KEY]: TRANSLATED })
+    await submit()
+
+    expect(screen.getByText('Enter a valid email address')).toBeInTheDocument()
+  })
+})

package/src/backend/inputs/PhoneNumberField.tsx

@@ -1,7 +1,7 @@
 "use client"
 
 import * as React from 'react'
-import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { useOptionalLocale, useT, type TranslateFn } from '@open-mercato/shared/lib/i18n/context'
 import { extractPhoneDigits, validatePhoneNumber } from '@open-mercato/shared/lib/phone'
 import { cn } from '@open-mercato/shared/lib/utils'
 import {
@@ -23,7 +23,11 @@ export type PhoneCountry = {
   iso2: string
   /** International dial code (with `+`). */
   dialCode: string
-  /** Human-readable country name (English). Override per surface for i18n. */
+  /**
+   * Human-readable country name (English). Used as the last-resort fallback
+   * when neither a locale file nor the platform's region data can name the
+   * country in the active locale.
+   */
   label: string
   /** Emoji flag (no asset dependency). */
   flag: string
@@ -311,6 +315,109 @@ export const PHONE_COUNTRIES: PhoneCountry[] = RAW_PHONE_COUNTRIES
   .map((country) => ({ ...country, flag: iso2ToFlagEmoji(country.iso2) }))
   .sort((a, b) => a.label.localeCompare(b.label, 'en', { sensitivity: 'base' }))
 
+/**
+ * Translation key holding a country's display name, e.g.
+ * `ui.inputs.phoneNumberField.countryName.PL`. Locale files only need entries
+ * for the countries whose platform-provided name a deployment wants to
+ * change. This is a distinct namespace from
+ * `ui.inputs.phoneNumberField.country` (the picker's trigger label) so a
+ * nested locale file can hold both.
+ */
+export function phoneCountryLabelKey(iso2: string): string {
+  return `ui.inputs.phoneNumberField.countryName.${iso2.toUpperCase()}`
+}
+
+const regionDisplayNamesByLocale = new Map<string, Intl.DisplayNames | null>()
+
+function getRegionDisplayNames(locale: string): Intl.DisplayNames | null {
+  const cached = regionDisplayNamesByLocale.get(locale)
+  if (cached !== undefined) return cached
+  let displayNames: Intl.DisplayNames | null = null
+  try {
+    displayNames = new Intl.DisplayNames([locale], { type: 'region' })
+  } catch {
+    displayNames = null
+  }
+  regionDisplayNamesByLocale.set(locale, displayNames)
+  return displayNames
+}
+
+/**
+ * Country name in `locale` from the platform's own region data, or `null` when
+ * the runtime cannot name that region (unknown code, trimmed ICU data).
+ */
+function regionDisplayName(iso2: string, locale: string | undefined): string | null {
+  if (!locale) return null
+  const code = iso2.toUpperCase()
+  if (!/^[A-Z]{2}$/.test(code)) return null
+  const displayNames = getRegionDisplayNames(locale)
+  if (!displayNames) return null
+  try {
+    const name = displayNames.of(code)
+    return name && name !== code ? name : null
+  } catch {
+    return null
+  }
+}
+
+function isEnglishLocale(locale: string | undefined): boolean {
+  return !locale || locale.toLowerCase().split(/[-_]/)[0] === 'en'
+}
+
+/**
+ * Display name for a built-in country in the active locale. A locale-file entry
+ * wins so a deployment can correct or override any name; otherwise the
+ * platform's region data localizes it; the English label is the last resort.
+ *
+ * English deliberately skips the region data: the dictionary already holds
+ * curated English names, and CLDR spells several of them differently
+ * ("Antigua & Barbuda" for "Antigua and Barbuda"), so consulting it would
+ * silently rewrite existing English copy for no gain.
+ */
+export function resolvePhoneCountryLabel(
+  country: PhoneCountry,
+  t: TranslateFn,
+  locale: string | undefined,
+): string {
+  const translated = t(phoneCountryLabelKey(country.iso2), '')
+  if (translated) return translated
+  if (isEnglishLocale(locale)) return country.label
+  return regionDisplayName(country.iso2, locale) ?? country.label
+}
+
+export type PhoneCountryOption = {
+  country: PhoneCountry
+  label: string
+}
+
+/**
+ * Locale safe to hand to `localeCompare`. A tag `Intl` cannot construct would
+ * throw there just as it does in `getRegionDisplayNames`, so both fall back to
+ * English together.
+ */
+function resolveCollationLocale(locale: string | undefined): string {
+  if (!locale) return 'en'
+  return getRegionDisplayNames(locale) ? locale : 'en'
+}
+
+/**
+ * Options rendered in the country dropdown. A caller-supplied list is
+ * authoritative — its labels and its order are preserved verbatim — while the
+ * built-in dictionary is localized and re-sorted for the active locale, since
+ * its module-level ordering is alphabetical by the English name.
+ */
+export function buildPhoneCountryOptions(
+  countries: PhoneCountry[] | undefined,
+  t: TranslateFn,
+  locale: string | undefined,
+): PhoneCountryOption[] {
+  if (countries) return countries.map((country) => ({ country, label: country.label }))
+  const collationLocale = resolveCollationLocale(locale)
+  return PHONE_COUNTRIES
+    .map((country) => ({ country, label: resolvePhoneCountryLabel(country, t, locale) }))
+    .sort((a, b) => a.label.localeCompare(b.label, collationLocale, { sensitivity: 'base' }))
+}
+
 /**
  * Sovereign/primary country that wins auto-detection for a calling code shared
  * by several territories. US vs. Canada is the one irreducible ambiguity — both
@@ -386,7 +493,11 @@ export type PhoneNumberFieldProps = {
   duplicateLinkLabel?: string
   invalidLabel?: string
   onDuplicateLookup?: (normalizedValue: string) => Promise<PhoneDuplicateMatch | null>
-  /** Override the static country list (e.g. limit to specific markets). */
+  /**
+   * Override the static country list (e.g. limit to specific markets, or supply
+   * names already translated by the host). Both the labels and the order of the
+   * supplied list are rendered verbatim.
+   */
   countries?: PhoneCountry[]
   /** Initial country shown when `value` is empty / unparseable. Defaults to US. */
   defaultCountryIso2?: string
@@ -422,6 +533,7 @@ export function PhoneNumberField({
   renderCountryIcon,
 }: PhoneNumberFieldProps) {
   const t = useT()
+  const locale = useOptionalLocale()
   const resolvedInvalidLabel = invalidLabel ?? t(
     'ui.inputs.phoneNumberField.invalid',
     'Enter a valid phone number with country code (e.g. +1 212 555 1234)'
@@ -435,7 +547,10 @@ export function PhoneNumberField({
     'Open record'
   )
   const resolvedPlaceholder = placeholder ?? DEFAULT_PLACEHOLDER
-  const countries = countriesProp ?? PHONE_COUNTRIES
+  const countryOptions = React.useMemo(
+    () => buildPhoneCountryOptions(countriesProp, t, locale),
+    [countriesProp, t, locale],
+  )
   const fallbackCountry = React.useMemo(
     () => (defaultCountryIso2 && findCountryByIso(defaultCountryIso2)) || DEFAULT_COUNTRY,
     [defaultCountryIso2],
@@ -609,12 +724,12 @@ export function PhoneNumberField({
             <span className={cn("text-sm text-foreground tabular-nums", disabled && "text-text-disabled")}>{country.dialCode}</span>
           </SelectTrigger>
           <SelectContent align="start">
-            {countries.map((c) => (
+            {countryOptions.map(({ country: c, label }) => (
               <SelectItem key={`${c.iso2}-${c.dialCode}`} value={c.iso2}>
                 <SelectItemLeading>
                   <span className="text-base leading-none">{c.flag}</span>
                 </SelectItemLeading>
-                <span className="flex-1 truncate">{c.label}</span>
+                <span className="flex-1 truncate">{label}</span>
                 <span className="ml-2 text-xs text-muted-foreground tabular-nums">{c.dialCode}</span>
               </SelectItem>
             ))}