feat(i18n): country/phone/timezone/subdivision primitives + form wiring

Cross-cutting i18n polish for forms across the marina + residential + company domains. Introduces a single source of truth for country/phone/timezone/ subdivision data and replaces every nationality-as-free-text and timezone- as-string Input with a dedicated combobox. PR1 Countries — ALL_COUNTRY_CODES (~250 ISO-3166-1 alpha-2), Intl.DisplayNames for localized labels, detectDefaultCountry() with navigator-region fallback to US, CountryCombobox with regional-indicator flag glyphs + compact mode for inline use. PR2 Phone — libphonenumber-js wrapper (parsePhone / formatAsYouType / callingCodeFor), PhoneInput with flag dropdown + national-format AsYouType + paste-detect that flips the country dropdown for pasted international strings. PR3 Timezones — country->IANA map (250 entries, multi-zone for AU/BR/CA/CD/ ID/KZ/MN/MX/RU/US), formatTimezoneLabel ("Europe/London (UTC+1)"), TimezoneCombobox with Suggested/All grouping driven by countryHint. PR4 Subdivisions — wraps the iso-3166-2 npm package (~5000 ISO 3166-2 codes for every country), per-country cache, SubdivisionCombobox with "Pick a country first" / "No regions available" empty states. PR5 Schema deltas (migration 0015) — clients.nationality_iso, clientContacts {value_e164, value_country}, clientAddresses {country_iso, subdivision_iso}, residentialClients {phone_e164, phone_country, nationality_iso, timezone, place_of_residence_country_iso, subdivision_iso}, companies {incorporation_ country_iso, incorporation_subdivision_iso}, companyAddresses {country_iso, subdivision_iso}. Plus shared zod validators (validators/i18n.ts) used by every entity validator + route handler. PR6 ClientForm + ClientDetail — CountryCombobox replaces nationality Input, TimezoneCombobox replaces timezone Input (driven by nationalityIso hint), PhoneInput conditionally rendered for phone/whatsapp contacts. Inline editors (InlineCountryField / InlineTimezoneField / InlinePhoneField) for the detail-page overview rows + ContactsEditor. PR7 Residential client form + detail — phone -> PhoneInput, nationality/ timezone/place-of-residence-country/subdivision rows in both create sheet and inline-editable detail view. Subdivision wipes when country flips since codes are country-scoped. PR8 Company form + detail — incorporation country -> CountryCombobox, incorporation region -> SubdivisionCombobox in both modes. PR9 Public inquiry endpoint — accepts pre-normalized phoneE164/phoneCountry and i18n fields from newer website builds, server-side parsePhone() fallback for legacy raw-international submissions. Old Nuxt builds keep working unchanged. Tests: 4 unit suites for the primitives (25 tests), 1 integration spec for the public phone-normalization path (3 tests), 1 smoke spec asserting the combobox triggers render in all three create sheets. Test totals: vitest 713 -> 741 (+28). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-28 18:13:08 +02:00
parent f52d21df83
commit 16d98d630e
44 changed files with 12768 additions and 67 deletions
--- a/src/components/clients/client-form.tsx
+++ b/src/components/clients/client-form.tsx
@@ -20,8 +20,12 @@ import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetFooter } from '@/com
 import { Checkbox } from '@/components/ui/checkbox';
 import { Separator } from '@/components/ui/separator';
 import { TagPicker } from '@/components/shared/tag-picker';
+import { CountryCombobox } from '@/components/shared/country-combobox';
+import { TimezoneCombobox } from '@/components/shared/timezone-combobox';
+import { PhoneInput } from '@/components/shared/phone-input';
 import { apiFetch } from '@/lib/api/client';
 import { createClientSchema, type CreateClientInput } from '@/lib/validators/clients';
+import type { CountryCode } from '@/lib/i18n/countries';

 interface ClientFormProps {
  open: boolean;
@@ -31,6 +35,7 @@ interface ClientFormProps {
    id: string;
    fullName: string;
    nationality?: string | null;
+    nationalityIso?: string | null;
    preferredContactMethod?: string | null;
    preferredLanguage?: string | null;
    timezone?: string | null;
@@ -39,6 +44,8 @@ interface ClientFormProps {
    contacts?: Array<{
      channel: string;
      value: string;
+      valueE164?: string | null;
+      valueCountry?: string | null;
      label?: string | null;
      isPrimary?: boolean;
      notes?: string | null;
@@ -77,6 +84,7 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
      reset({
        fullName: client.fullName,
        nationality: client.nationality ?? undefined,
+        nationalityIso: client.nationalityIso ?? undefined,
        preferredContactMethod:
          (client.preferredContactMethod as CreateClientInput['preferredContactMethod']) ??
          undefined,
@@ -89,6 +97,8 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
            ? client.contacts.map((c) => ({
                channel: c.channel as 'email' | 'phone' | 'whatsapp' | 'other',
                value: c.value,
+                valueE164: c.valueE164 ?? undefined,
+                valueCountry: c.valueCountry ?? undefined,
                label: c.label ?? undefined,
                isPrimary: c.isPrimary ?? false,
                notes: c.notes ?? undefined,
@@ -152,7 +162,11 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {

              <div className="space-y-1">
                <Label>Nationality</Label>
-                <Input {...register('nationality')} placeholder="British" />
+                <CountryCombobox
+                  value={watch('nationalityIso')}
+                  onChange={(iso) => setValue('nationalityIso', iso ?? undefined)}
+                  data-testid="client-nationality"
+                />
              </div>
            </div>
          </div>
@@ -211,11 +225,40 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {

                  <div className="col-span-5 space-y-1">
                    <Label className="text-xs">Value</Label>
-                    <Input
-                      {...register(`contacts.${index}.value`)}
-                      className="h-8"
-                      placeholder="email@example.com"
-                    />
+                    {(() => {
+                      const channel = watch(`contacts.${index}.channel`);
+                      if (channel === 'phone' || channel === 'whatsapp') {
+                        const e164 = watch(`contacts.${index}.valueE164`) ?? null;
+                        const country =
+                          (watch(`contacts.${index}.valueCountry`) as CountryCode | undefined) ??
+                          undefined;
+                        return (
+                          <PhoneInput
+                            value={
+                              e164 || country
+                                ? {
+                                    e164: e164 ?? null,
+                                    country: country ?? 'US',
+                                  }
+                                : null
+                            }
+                            onChange={(v) => {
+                              setValue(`contacts.${index}.value`, v.e164 ?? '');
+                              setValue(`contacts.${index}.valueE164`, v.e164 ?? undefined);
+                              setValue(`contacts.${index}.valueCountry`, v.country);
+                            }}
+                            data-testid={`contact-${index}-phone`}
+                          />
+                        );
+                      }
+                      return (
+                        <Input
+                          {...register(`contacts.${index}.value`)}
+                          className="h-8"
+                          placeholder={channel === 'email' ? 'email@example.com' : 'value'}
+                        />
+                      );
+                    })()}
                  </div>

                  <div className="col-span-2 space-y-1">
@@ -304,7 +347,12 @@ export function ClientForm({ open, onOpenChange, client }: ClientFormProps) {
              </div>
              <div className="space-y-1">
                <Label>Timezone</Label>
-                <Input {...register('timezone')} placeholder="UTC+0" />
+                <TimezoneCombobox
+                  value={watch('timezone')}
+                  onChange={(tz) => setValue('timezone', tz ?? undefined)}
+                  countryHint={(watch('nationalityIso') as CountryCode | undefined) ?? undefined}
+                  data-testid="client-timezone"
+                />
              </div>
              <div className="col-span-2 space-y-1">
                <Label>Source Details</Label>
--- a/src/components/clients/client-tabs.tsx
+++ b/src/components/clients/client-tabs.tsx
@@ -4,8 +4,11 @@ import { useMutation, useQueryClient } from '@tanstack/react-query';

 import type { DetailTab } from '@/components/shared/detail-layout';
 import { InlineEditableField } from '@/components/shared/inline-editable-field';
+import { InlineCountryField } from '@/components/shared/inline-country-field';
+import { InlineTimezoneField } from '@/components/shared/inline-timezone-field';
 import { InlineTagEditor } from '@/components/shared/inline-tag-editor';
 import { NotesList } from '@/components/shared/notes-list';
+import type { CountryCode } from '@/lib/i18n/countries';
 import { ClientYachtsTab } from '@/components/clients/client-yachts-tab';
 import { ClientCompaniesTab } from '@/components/clients/client-companies-tab';
 import { ClientReservationsTab } from '@/components/clients/client-reservations-tab';
@@ -15,6 +18,7 @@ import { apiFetch } from '@/lib/api/client';
 type ClientPatchField =
  | 'fullName'
  | 'nationality'
+  | 'nationalityIso'
  | 'preferredContactMethod'
  | 'preferredLanguage'
  | 'timezone'
@@ -64,6 +68,7 @@ interface ClientTabsOptions {
  client: {
    fullName: string;
    nationality?: string | null;
+    nationalityIso?: string | null;
    preferredContactMethod?: string | null;
    preferredLanguage?: string | null;
    timezone?: string | null;
@@ -73,6 +78,8 @@ interface ClientTabsOptions {
      id: string;
      channel: string;
      value: string;
+      valueE164?: string | null;
+      valueCountry?: string | null;
      label?: string | null;
      isPrimary: boolean;
    }>;
@@ -131,7 +138,13 @@ function OverviewTab({
            <InlineEditableField value={client.fullName} onSave={save('fullName')} />
          </EditableRow>
          <EditableRow label="Nationality">
-            <InlineEditableField value={client.nationality} onSave={save('nationality')} />
+            <InlineCountryField
+              value={client.nationalityIso ?? null}
+              onSave={async (iso) => {
+                await mutation.mutateAsync({ nationalityIso: iso });
+              }}
+              data-testid="client-nationality-inline"
+            />
          </EditableRow>
          <EditableRow label="Preferred Language">
            <InlineEditableField
@@ -140,7 +153,14 @@ function OverviewTab({
            />
          </EditableRow>
          <EditableRow label="Timezone">
-            <InlineEditableField value={client.timezone} onSave={save('timezone')} />
+            <InlineTimezoneField
+              value={client.timezone}
+              countryHint={(client.nationalityIso as CountryCode | null) ?? null}
+              onSave={async (tz) => {
+                await mutation.mutateAsync({ timezone: tz });
+              }}
+              data-testid="client-timezone-inline"
+            />
          </EditableRow>
          <EditableRow label="Preferred Contact">
            <InlineEditableField
--- a/src/components/clients/contacts-editor.tsx
+++ b/src/components/clients/contacts-editor.tsx
@@ -24,6 +24,8 @@ import {
  SelectValue,
 } from '@/components/ui/select';
 import { InlineEditableField } from '@/components/shared/inline-editable-field';
+import { InlinePhoneField } from '@/components/shared/inline-phone-field';
+import { PhoneInput, type PhoneInputValue } from '@/components/shared/phone-input';
 import { apiFetch } from '@/lib/api/client';
 import { cn } from '@/lib/utils';

@@ -31,6 +33,8 @@ interface Contact {
  id: string;
  channel: string;
  value: string;
+  valueE164?: string | null;
+  valueCountry?: string | null;
  label?: string | null;
  isPrimary: boolean;
 }
@@ -63,7 +67,9 @@ export function ContactsEditor({ clientId, contacts }: { clientId: string; conta
      patch,
    }: {
      contactId: string;
-      patch: Partial<Pick<Contact, 'channel' | 'value' | 'label' | 'isPrimary'>>;
+      patch: Partial<
+        Pick<Contact, 'channel' | 'value' | 'valueE164' | 'valueCountry' | 'label' | 'isPrimary'>
+      >;
    }) =>
      apiFetch(`/api/v1/clients/${clientId}/contacts/${contactId}`, {
        method: 'PATCH',
@@ -73,7 +79,13 @@ export function ContactsEditor({ clientId, contacts }: { clientId: string; conta
  });

  const addMutation = useMutation({
-    mutationFn: async (data: { channel: string; value: string; label?: string }) =>
+    mutationFn: async (data: {
+      channel: string;
+      value: string;
+      valueE164?: string | null;
+      valueCountry?: string | null;
+      label?: string;
+    }) =>
      apiFetch(`/api/v1/clients/${clientId}/contacts`, {
        method: 'POST',
        body: { ...data, isPrimary: false },
@@ -136,7 +148,9 @@ function ContactRow({
 }: {
  contact: Contact;
  onUpdate: (
-    patch: Partial<Pick<Contact, 'channel' | 'value' | 'label' | 'isPrimary'>>,
+    patch: Partial<
+      Pick<Contact, 'channel' | 'value' | 'valueE164' | 'valueCountry' | 'label' | 'isPrimary'>
+    >,
  ) => Promise<unknown>;
  onRemove: () => void;
 }) {
@@ -167,16 +181,30 @@ function ContactRow({
          <Icon className="h-3.5 w-3.5 text-muted-foreground" />
        </ChannelPicker>
        <div className="min-w-0">
-          <InlineEditableField
-            value={contact.value}
-            onSave={async (v) => {
-              if (!v) {
-                toast.error('Value is required');
-                return;
-              }
-              await onUpdate({ value: v });
-            }}
-          />
+          {contact.channel === 'phone' || contact.channel === 'whatsapp' ? (
+            <InlinePhoneField
+              e164={contact.valueE164 ?? null}
+              country={contact.valueCountry ?? null}
+              onSave={async ({ e164, country }) => {
+                if (!e164) {
+                  toast.error('Phone number is required');
+                  return;
+                }
+                await onUpdate({ value: e164, valueE164: e164, valueCountry: country });
+              }}
+            />
+          ) : (
+            <InlineEditableField
+              value={contact.value}
+              onSave={async (v) => {
+                if (!v) {
+                  toast.error('Value is required');
+                  return;
+                }
+                await onUpdate({ value: v });
+              }}
+            />
+          )}
        </div>
      </div>

@@ -252,15 +280,42 @@ function NewContactForm({
  onSave,
  onCancel,
 }: {
-  onSave: (data: { channel: string; value: string; label?: string }) => Promise<void>;
+  onSave: (data: {
+    channel: string;
+    value: string;
+    valueE164?: string | null;
+    valueCountry?: string | null;
+    label?: string;
+  }) => Promise<void>;
  onCancel: () => void;
 }) {
  const [channel, setChannel] = useState('email');
  const [value, setValue] = useState('');
+  const [phoneValue, setPhoneValue] = useState<PhoneInputValue | null>(null);
  const [label, setLabel] = useState('');
  const [saving, setSaving] = useState(false);

+  const isPhoneChannel = channel === 'phone' || channel === 'whatsapp';
+
  async function submit() {
+    if (isPhoneChannel) {
+      if (!phoneValue?.e164) return;
+      setSaving(true);
+      try {
+        await onSave({
+          channel,
+          value: phoneValue.e164,
+          valueE164: phoneValue.e164,
+          valueCountry: phoneValue.country,
+          label: label.trim() || undefined,
+        });
+      } catch (err) {
+        toast.error(err instanceof Error ? err.message : 'Failed to add contact');
+      } finally {
+        setSaving(false);
+      }
+      return;
+    }
    if (!value.trim()) return;
    setSaving(true);
    try {
@@ -272,9 +327,19 @@ function NewContactForm({
    }
  }

+  const submitDisabled = saving || (isPhoneChannel ? !phoneValue?.e164 : !value.trim());
+
  return (
    <div className="flex items-center gap-2 p-2 rounded-lg border bg-muted/30 text-sm">
-      <Select value={channel} onValueChange={setChannel}>
+      <Select
+        value={channel}
+        onValueChange={(next) => {
+          setChannel(next);
+          // Reset cross-mode state so a stale email doesn't ride along on a phone submit.
+          if (next === 'phone' || next === 'whatsapp') setValue('');
+          else setPhoneValue(null);
+        }}
+      >
        <SelectTrigger className="h-7 w-28 text-xs">
          <SelectValue />
        </SelectTrigger>
@@ -287,21 +352,31 @@ function NewContactForm({
        </SelectContent>
      </Select>

-      <Input
-        value={value}
-        onChange={(e) => setValue(e.target.value)}
-        placeholder={channel === 'email' ? 'name@example.com' : '+1 555 0100'}
-        className="h-7 text-sm flex-1 min-w-0"
-        autoFocus
-        disabled={saving}
-        onKeyDown={(e) => {
-          if (e.key === 'Enter') {
-            e.preventDefault();
-            void submit();
-          }
-          if (e.key === 'Escape') onCancel();
-        }}
-      />
+      {isPhoneChannel ? (
+        <div className="flex-1 min-w-0">
+          <PhoneInput
+            value={phoneValue}
+            onChange={(v) => setPhoneValue(v)}
+            data-testid="new-contact-phone"
+          />
+        </div>
+      ) : (
+        <Input
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          placeholder={channel === 'email' ? 'name@example.com' : 'value'}
+          className="h-7 text-sm flex-1 min-w-0"
+          autoFocus
+          disabled={saving}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') {
+              e.preventDefault();
+              void submit();
+            }
+            if (e.key === 'Escape') onCancel();
+          }}
+        />
+      )}

      <Input
        value={label}
@@ -318,7 +393,7 @@ function NewContactForm({
        }}
      />

-      <Button type="button" size="sm" onClick={submit} disabled={!value.trim() || saving}>
+      <Button type="button" size="sm" onClick={submit} disabled={submitDisabled}>
        {saving ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : 'Save'}
      </Button>
      <Button type="button" size="sm" variant="ghost" onClick={onCancel} disabled={saving}>
--- a/src/components/companies/company-columns.tsx
+++ b/src/components/companies/company-columns.tsx
@@ -20,6 +20,8 @@ export interface CompanyRow {
  taxId: string | null;
  registrationNumber: string | null;
  incorporationCountry: string | null;
+  incorporationCountryIso: string | null;
+  incorporationSubdivisionIso: string | null;
  incorporationDate: string | null;
  status: string;
  billingEmail: string | null;
--- a/src/components/companies/company-detail-header.tsx
+++ b/src/components/companies/company-detail-header.tsx
@@ -21,6 +21,8 @@ interface CompanyDetailHeaderCompany {
  taxId: string | null;
  registrationNumber: string | null;
  incorporationCountry: string | null;
+  incorporationCountryIso: string | null;
+  incorporationSubdivisionIso: string | null;
  incorporationDate: string | null;
  status: string;
  billingEmail: string | null;
@@ -131,6 +133,8 @@ export function CompanyDetailHeader({ company }: CompanyDetailHeaderProps) {
          taxId: company.taxId,
          registrationNumber: company.registrationNumber,
          incorporationCountry: company.incorporationCountry,
+          incorporationCountryIso: company.incorporationCountryIso,
+          incorporationSubdivisionIso: company.incorporationSubdivisionIso,
          incorporationDate: company.incorporationDate,
          status: company.status,
          billingEmail: company.billingEmail,
--- a/src/components/companies/company-detail.tsx
+++ b/src/components/companies/company-detail.tsx
@@ -17,6 +17,8 @@ export interface CompanyData {
  taxId: string | null;
  registrationNumber: string | null;
  incorporationCountry: string | null;
+  incorporationCountryIso: string | null;
+  incorporationSubdivisionIso: string | null;
  incorporationDate: string | null;
  status: string;
  billingEmail: string | null;
--- a/src/components/companies/company-form.tsx
+++ b/src/components/companies/company-form.tsx
@@ -21,8 +21,11 @@ import {
 import { Sheet, SheetContent, SheetFooter, SheetHeader, SheetTitle } from '@/components/ui/sheet';
 import { Separator } from '@/components/ui/separator';
 import { TagPicker } from '@/components/shared/tag-picker';
+import { CountryCombobox } from '@/components/shared/country-combobox';
+import { SubdivisionCombobox } from '@/components/shared/subdivision-combobox';
 import { apiFetch } from '@/lib/api/client';
 import { createCompanySchema, type CreateCompanyInput } from '@/lib/validators/companies';
+import type { CountryCode } from '@/lib/i18n/countries';

 type CompanyStatus = 'active' | 'dissolved';

@@ -39,6 +42,8 @@ interface CompanyFormProps {
    taxId: string | null;
    registrationNumber: string | null;
    incorporationCountry: string | null;
+    incorporationCountryIso: string | null;
+    incorporationSubdivisionIso: string | null;
    incorporationDate: string | null;
    status: string;
    billingEmail: string | null;
@@ -79,6 +84,8 @@ export function CompanyForm({ open, onOpenChange, company }: CompanyFormProps) {
        taxId: company.taxId ?? undefined,
        registrationNumber: company.registrationNumber ?? undefined,
        incorporationCountry: company.incorporationCountry ?? undefined,
+        incorporationCountryIso: company.incorporationCountryIso ?? undefined,
+        incorporationSubdivisionIso: company.incorporationSubdivisionIso ?? undefined,
        incorporationDate: company.incorporationDate
          ? new Date(company.incorporationDate)
          : undefined,
@@ -169,7 +176,24 @@ export function CompanyForm({ open, onOpenChange, company }: CompanyFormProps) {
              </div>
              <div className="space-y-1">
                <Label>Incorporation Country</Label>
-                <Input {...register('incorporationCountry')} placeholder="e.g. MT" />
+                <CountryCombobox
+                  value={watch('incorporationCountryIso')}
+                  onChange={(iso) => {
+                    setValue('incorporationCountryIso', iso ?? undefined);
+                    // Wipe subdivision when country flips — codes are country-scoped.
+                    setValue('incorporationSubdivisionIso', undefined);
+                  }}
+                  data-testid="company-incorp-country"
+                />
+              </div>
+              <div className="space-y-1">
+                <Label>Incorporation Region</Label>
+                <SubdivisionCombobox
+                  value={watch('incorporationSubdivisionIso')}
+                  onChange={(code) => setValue('incorporationSubdivisionIso', code ?? undefined)}
+                  country={(watch('incorporationCountryIso') as CountryCode | undefined) ?? null}
+                  data-testid="company-incorp-subdivision"
+                />
              </div>
              <div className="space-y-1">
                <Label>Incorporation Date</Label>
--- a/src/components/companies/company-list.tsx
+++ b/src/components/companies/company-list.tsx
@@ -146,6 +146,8 @@ export function CompanyList() {
            taxId: editCompany.taxId,
            registrationNumber: editCompany.registrationNumber,
            incorporationCountry: editCompany.incorporationCountry,
+            incorporationCountryIso: editCompany.incorporationCountryIso,
+            incorporationSubdivisionIso: editCompany.incorporationSubdivisionIso,
            incorporationDate: editCompany.incorporationDate,
            status: editCompany.status,
            billingEmail: editCompany.billingEmail,
--- a/src/components/companies/company-tabs.tsx
+++ b/src/components/companies/company-tabs.tsx
@@ -5,11 +5,14 @@ import { useMutation, useQueryClient } from '@tanstack/react-query';
 import type { DetailTab } from '@/components/shared/detail-layout';
 import { EmptyState } from '@/components/shared/empty-state';
 import { InlineEditableField } from '@/components/shared/inline-editable-field';
+import { InlineCountryField } from '@/components/shared/inline-country-field';
+import { SubdivisionCombobox } from '@/components/shared/subdivision-combobox';
 import { InlineTagEditor } from '@/components/shared/inline-tag-editor';
 import { NotesList } from '@/components/shared/notes-list';
 import { CompanyMembersTab } from '@/components/companies/company-members-tab';
 import { CompanyOwnedYachtsTab } from '@/components/companies/company-owned-yachts-tab';
 import { apiFetch } from '@/lib/api/client';
+import type { CountryCode } from '@/lib/i18n/countries';

 type CompanyPatchField =
  | 'name'
@@ -17,6 +20,8 @@ type CompanyPatchField =
  | 'taxId'
  | 'registrationNumber'
  | 'incorporationCountry'
+  | 'incorporationCountryIso'
+  | 'incorporationSubdivisionIso'
  | 'incorporationDate'
  | 'status'
  | 'billingEmail'
@@ -34,6 +39,8 @@ interface CompanyTabsCompany {
  taxId: string | null;
  registrationNumber: string | null;
  incorporationCountry: string | null;
+  incorporationCountryIso: string | null;
+  incorporationSubdivisionIso: string | null;
  incorporationDate: string | null;
  status: string;
  billingEmail: string | null;
@@ -114,9 +121,26 @@ function OverviewTab({ companyId, company }: { companyId: string; company: Compa
            />
          </EditableRow>
          <EditableRow label="Incorporation Country">
-            <InlineEditableField
-              value={company.incorporationCountry}
-              onSave={save('incorporationCountry')}
+            <InlineCountryField
+              value={company.incorporationCountryIso}
+              onSave={async (iso) => {
+                // Wipe subdivision when country flips — codes are country-scoped.
+                await mutation.mutateAsync({
+                  incorporationCountryIso: iso,
+                  incorporationSubdivisionIso: null,
+                });
+              }}
+              data-testid="company-incorp-country-inline"
+            />
+          </EditableRow>
+          <EditableRow label="Incorporation Region">
+            <SubdivisionCombobox
+              value={company.incorporationSubdivisionIso}
+              onChange={(code) => {
+                void mutation.mutateAsync({ incorporationSubdivisionIso: code });
+              }}
+              country={(company.incorporationCountryIso as CountryCode | null) ?? null}
+              data-testid="company-incorp-subdivision-inline"
            />
          </EditableRow>
          <EditableRow label="Incorporation Date">
--- a/src/components/residential/residential-client-detail.tsx
+++ b/src/components/residential/residential-client-detail.tsx
@@ -12,8 +12,13 @@ import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { Sheet, SheetContent, SheetFooter, SheetHeader, SheetTitle } from '@/components/ui/sheet';
 import { InlineEditableField } from '@/components/shared/inline-editable-field';
+import { InlineCountryField } from '@/components/shared/inline-country-field';
+import { InlineTimezoneField } from '@/components/shared/inline-timezone-field';
+import { InlinePhoneField } from '@/components/shared/inline-phone-field';
+import { SubdivisionCombobox } from '@/components/shared/subdivision-combobox';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
 import { apiFetch } from '@/lib/api/client';
+import type { CountryCode } from '@/lib/i18n/countries';

 interface ResidentialInterestSummary {
  id: string;
@@ -29,7 +34,13 @@ interface ResidentialClientDetail {
  fullName: string;
  email: string | null;
  phone: string | null;
+  phoneE164: string | null;
+  phoneCountry: string | null;
+  nationalityIso: string | null;
+  timezone: string | null;
  placeOfResidence: string | null;
+  placeOfResidenceCountryIso: string | null;
+  subdivisionIso: string | null;
  preferredContactMethod: string | null;
  status: string;
  source: string | null;
@@ -130,7 +141,17 @@ export function ResidentialClientDetail({ clientId }: { clientId: string }) {
              <InlineEditableField value={client.email} onSave={save('email')} />
            </Row>
            <Row label="Phone">
-              <InlineEditableField value={client.phone} onSave={save('phone')} />
+              <InlinePhoneField
+                e164={client.phoneE164}
+                country={client.phoneCountry}
+                onSave={async ({ e164, country }) => {
+                  await update.mutateAsync({
+                    phone: e164,
+                    phoneE164: e164,
+                    phoneCountry: country,
+                  });
+                }}
+              />
            </Row>
            <Row label="Preferred contact">
              <InlineEditableField
@@ -140,12 +161,50 @@ export function ResidentialClientDetail({ clientId }: { clientId: string }) {
                onSave={save('preferredContactMethod')}
              />
            </Row>
+            <Row label="Nationality">
+              <InlineCountryField
+                value={client.nationalityIso}
+                onSave={async (iso) => {
+                  await update.mutateAsync({ nationalityIso: iso });
+                }}
+              />
+            </Row>
+            <Row label="Timezone">
+              <InlineTimezoneField
+                value={client.timezone}
+                countryHint={(client.nationalityIso as CountryCode | null) ?? null}
+                onSave={async (tz) => {
+                  await update.mutateAsync({ timezone: tz });
+                }}
+              />
+            </Row>
            <Row label="Place of residence">
              <InlineEditableField
                value={client.placeOfResidence}
                onSave={save('placeOfResidence')}
              />
            </Row>
+            <Row label="Country of residence">
+              <InlineCountryField
+                value={client.placeOfResidenceCountryIso}
+                onSave={async (iso) => {
+                  // When country flips, clear the subdivision — codes are country-scoped.
+                  await update.mutateAsync({
+                    placeOfResidenceCountryIso: iso,
+                    subdivisionIso: null,
+                  });
+                }}
+              />
+            </Row>
+            <Row label="Region">
+              <SubdivisionCombobox
+                value={client.subdivisionIso}
+                onChange={(code) => {
+                  void update.mutateAsync({ subdivisionIso: code });
+                }}
+                country={(client.placeOfResidenceCountryIso as CountryCode | null) ?? null}
+              />
+            </Row>
          </div>

          <div className="space-y-1">
--- a/src/components/residential/residential-clients-list.tsx
+++ b/src/components/residential/residential-clients-list.tsx
@@ -12,8 +12,13 @@ import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { Sheet, SheetContent, SheetFooter, SheetHeader, SheetTitle } from '@/components/ui/sheet';
 import { PageHeader } from '@/components/shared/page-header';
+import { CountryCombobox } from '@/components/shared/country-combobox';
+import { TimezoneCombobox } from '@/components/shared/timezone-combobox';
+import { SubdivisionCombobox } from '@/components/shared/subdivision-combobox';
+import { PhoneInput, type PhoneInputValue } from '@/components/shared/phone-input';
 import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
 import { apiFetch } from '@/lib/api/client';
+import type { CountryCode } from '@/lib/i18n/countries';

 interface ResidentialClientRow {
  id: string;
@@ -147,10 +152,26 @@ function NewResidentialClientSheet({
  const qc = useQueryClient();
  const [fullName, setFullName] = useState('');
  const [email, setEmail] = useState('');
-  const [phone, setPhone] = useState('');
+  const [phone, setPhone] = useState<PhoneInputValue | null>(null);
+  const [nationalityIso, setNationalityIso] = useState<CountryCode | null>(null);
+  const [timezone, setTimezone] = useState<string | null>(null);
  const [placeOfResidence, setPlaceOfResidence] = useState('');
+  const [residenceCountry, setResidenceCountry] = useState<CountryCode | null>(null);
+  const [residenceSubdivision, setResidenceSubdivision] = useState<string | null>(null);
  const [notes, setNotes] = useState('');

+  function reset() {
+    setFullName('');
+    setEmail('');
+    setPhone(null);
+    setNationalityIso(null);
+    setTimezone(null);
+    setPlaceOfResidence('');
+    setResidenceCountry(null);
+    setResidenceSubdivision(null);
+    setNotes('');
+  }
+
  const create = useMutation({
    mutationFn: () =>
      apiFetch('/api/v1/residential/clients', {
@@ -158,8 +179,14 @@ function NewResidentialClientSheet({
        body: {
          fullName,
          email: email || undefined,
-          phone: phone || undefined,
+          phone: phone?.e164 ?? undefined,
+          phoneE164: phone?.e164 ?? undefined,
+          phoneCountry: phone?.country ?? undefined,
+          nationalityIso: nationalityIso ?? undefined,
+          timezone: timezone ?? undefined,
          placeOfResidence: placeOfResidence || undefined,
+          placeOfResidenceCountryIso: residenceCountry ?? undefined,
+          subdivisionIso: residenceSubdivision ?? undefined,
          notes: notes || undefined,
          source: 'manual',
        },
@@ -167,11 +194,7 @@ function NewResidentialClientSheet({
    onSuccess: () => {
      qc.invalidateQueries({ queryKey: ['residential-clients'] });
      onOpenChange(false);
-      setFullName('');
-      setEmail('');
-      setPhone('');
-      setPlaceOfResidence('');
-      setNotes('');
+      reset();
      toast.success('Residential client added');
    },
    onError: (err) => {
@@ -212,7 +235,28 @@ function NewResidentialClientSheet({
          </div>
          <div className="space-y-1.5">
            <Label htmlFor="rc-phone">Phone</Label>
-            <Input id="rc-phone" value={phone} onChange={(e) => setPhone(e.target.value)} />
+            <PhoneInput id="rc-phone" value={phone} onChange={setPhone} data-testid="rc-phone" />
+          </div>
+          <div className="grid grid-cols-2 gap-3">
+            <div className="space-y-1.5">
+              <Label htmlFor="rc-nationality">Nationality</Label>
+              <CountryCombobox
+                id="rc-nationality"
+                value={nationalityIso}
+                onChange={setNationalityIso}
+                data-testid="rc-nationality"
+              />
+            </div>
+            <div className="space-y-1.5">
+              <Label htmlFor="rc-timezone">Timezone</Label>
+              <TimezoneCombobox
+                id="rc-timezone"
+                value={timezone}
+                onChange={setTimezone}
+                countryHint={nationalityIso ?? undefined}
+                data-testid="rc-timezone"
+              />
+            </div>
          </div>
          <div className="space-y-1.5">
            <Label htmlFor="rc-residence">Place of residence</Label>
@@ -220,8 +264,34 @@ function NewResidentialClientSheet({
              id="rc-residence"
              value={placeOfResidence}
              onChange={(e) => setPlaceOfResidence(e.target.value)}
+              placeholder="City or area"
            />
          </div>
+          <div className="grid grid-cols-2 gap-3">
+            <div className="space-y-1.5">
+              <Label htmlFor="rc-residence-country">Country</Label>
+              <CountryCombobox
+                id="rc-residence-country"
+                value={residenceCountry}
+                onChange={(iso) => {
+                  setResidenceCountry(iso);
+                  // Wipe subdivision when country flips — codes are scoped per country.
+                  setResidenceSubdivision(null);
+                }}
+                data-testid="rc-residence-country"
+              />
+            </div>
+            <div className="space-y-1.5">
+              <Label htmlFor="rc-residence-subdivision">Region</Label>
+              <SubdivisionCombobox
+                id="rc-residence-subdivision"
+                value={residenceSubdivision}
+                onChange={setResidenceSubdivision}
+                country={residenceCountry}
+                data-testid="rc-residence-subdivision"
+              />
+            </div>
+          </div>
          <div className="space-y-1.5">
            <Label htmlFor="rc-notes">Notes</Label>
            <Input id="rc-notes" value={notes} onChange={(e) => setNotes(e.target.value)} />
--- a/src/components/shared/country-combobox.tsx
+++ b/src/components/shared/country-combobox.tsx
@@ -0,0 +1,153 @@
+'use client';
+
+import { useMemo, useState } from 'react';
+import { Check, ChevronsUpDown } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '@/components/ui/command';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
+import { cn } from '@/lib/utils';
+import { ALL_COUNTRY_CODES, getCountryName, type CountryCode } from '@/lib/i18n/countries';
+
+interface CountryComboboxProps {
+  value: string | null | undefined;
+  onChange: (iso: CountryCode | null) => void;
+  /** Display locale; defaults to navigator.language so country names follow the user. */
+  locale?: string;
+  /** When true, renders just the flag/code (compact 24×24 trigger). */
+  compact?: boolean;
+  placeholder?: string;
+  disabled?: boolean;
+  className?: string;
+  /** Allow clearing the selection. */
+  clearable?: boolean;
+  id?: string;
+  'data-testid'?: string;
+}
+
+/**
+ * Returns the regional-indicator emoji flag for an ISO alpha-2 code.
+ * E.g. 'GB' → 🇬🇧. Avoids shipping a flag-image asset and respects the
+ * platform's emoji rendering (iOS/macOS render real flags; Windows
+ * shows the country code on a flag rectangle).
+ */
+function flagEmoji(code: string): string {
+  if (code.length !== 2) return '';
+  const A = 0x1f1e6;
+  const a = 'A'.charCodeAt(0);
+  const cp1 = A + code.charCodeAt(0) - a;
+  const cp2 = A + code.charCodeAt(1) - a;
+  return String.fromCodePoint(cp1, cp2);
+}
+
+export function CountryCombobox({
+  value,
+  onChange,
+  locale,
+  compact = false,
+  placeholder = 'Select country…',
+  disabled,
+  className,
+  clearable = true,
+  id,
+  'data-testid': testId,
+}: CountryComboboxProps) {
+  const [open, setOpen] = useState(false);
+  const effectiveLocale = locale ?? (typeof navigator !== 'undefined' ? navigator.language : 'en');
+
+  // Pre-build the options list once per locale change so the cmdk filter
+  // can search by both code + localized name without re-allocating.
+  const options = useMemo(() => {
+    return ALL_COUNTRY_CODES.map((code) => ({
+      code,
+      name: getCountryName(code, effectiveLocale),
+      flag: flagEmoji(code),
+    })).sort((a, b) => a.name.localeCompare(b.name, effectiveLocale));
+  }, [effectiveLocale]);
+
+  const selected = value ? options.find((o) => o.code === value) : undefined;
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          id={id}
+          variant="outline"
+          role="combobox"
+          aria-expanded={open}
+          disabled={disabled}
+          className={cn(
+            'justify-between',
+            compact ? 'w-20 px-2' : 'w-full',
+            !selected && 'text-muted-foreground',
+            className,
+          )}
+          data-testid={testId}
+        >
+          {selected ? (
+            <span className="flex min-w-0 items-center gap-2">
+              <span className="text-base leading-none">{selected.flag}</span>
+              {!compact ? (
+                <span className="truncate text-sm">{selected.name}</span>
+              ) : (
+                <span className="text-xs font-medium">{selected.code}</span>
+              )}
+            </span>
+          ) : (
+            <span className="truncate">{placeholder}</span>
+          )}
+          <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-[280px] p-0" align="start">
+        <Command>
+          <CommandInput placeholder="Search country or code…" />
+          <CommandList>
+            <CommandEmpty>No country found.</CommandEmpty>
+            {clearable && value ? (
+              <CommandGroup>
+                <CommandItem
+                  value="__clear__"
+                  onSelect={() => {
+                    onChange(null);
+                    setOpen(false);
+                  }}
+                  className="text-muted-foreground"
+                >
+                  Clear selection
+                </CommandItem>
+              </CommandGroup>
+            ) : null}
+            <CommandGroup>
+              {options.map((opt) => (
+                <CommandItem
+                  key={opt.code}
+                  // cmdk filters by `value` — include both code + name.
+                  value={`${opt.name} ${opt.code}`}
+                  onSelect={() => {
+                    onChange(opt.code);
+                    setOpen(false);
+                  }}
+                >
+                  <Check
+                    className={cn('mr-2 h-4 w-4', value === opt.code ? 'opacity-100' : 'opacity-0')}
+                  />
+                  <span className="mr-2 text-base leading-none">{opt.flag}</span>
+                  <span className="flex-1 truncate text-sm">{opt.name}</span>
+                  <span className="text-xs text-muted-foreground">{opt.code}</span>
+                </CommandItem>
+              ))}
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  );
+}
--- a/src/components/shared/inline-country-field.tsx
+++ b/src/components/shared/inline-country-field.tsx
@@ -0,0 +1,92 @@
+'use client';
+
+import { useState } from 'react';
+import { Loader2, Pencil } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { CountryCombobox } from '@/components/shared/country-combobox';
+import { getCountryName, type CountryCode } from '@/lib/i18n/countries';
+import { cn } from '@/lib/utils';
+
+interface InlineCountryFieldProps {
+  value: string | null | undefined;
+  onSave: (next: CountryCode | null) => Promise<void>;
+  emptyText?: string;
+  disabled?: boolean;
+  className?: string;
+  'data-testid'?: string;
+}
+
+/**
+ * Click-to-edit country picker. Renders the localized country name with a
+ * regional-indicator flag glyph; opens a CountryCombobox on click.
+ */
+export function InlineCountryField({
+  value,
+  onSave,
+  emptyText = '—',
+  disabled,
+  className,
+  'data-testid': testId,
+}: InlineCountryFieldProps) {
+  const [editing, setEditing] = useState(false);
+  const [saving, setSaving] = useState(false);
+
+  async function commit(next: CountryCode | null) {
+    if (next === (value ?? null)) {
+      setEditing(false);
+      return;
+    }
+    setSaving(true);
+    try {
+      await onSave(next);
+      setEditing(false);
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : 'Failed to save');
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  if (editing) {
+    return (
+      <div className={cn('flex items-center gap-1', className)}>
+        <CountryCombobox value={value} onChange={(iso) => void commit(iso)} data-testid={testId} />
+        {saving && <Loader2 className="h-3 w-3 animate-spin text-muted-foreground" />}
+      </div>
+    );
+  }
+
+  const display = value
+    ? `${flagEmoji(value)} ${getCountryName(value, typeof navigator !== 'undefined' ? navigator.language : 'en')}`
+    : null;
+
+  return (
+    <button
+      type="button"
+      disabled={disabled}
+      onClick={() => setEditing(true)}
+      data-testid={testId}
+      className={cn(
+        'group inline-flex items-center gap-1.5 rounded px-1 -mx-1 py-0.5 text-left text-sm',
+        'hover:bg-muted/60 focus-visible:bg-muted/60 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+        disabled && 'cursor-not-allowed opacity-60 hover:bg-transparent',
+        className,
+      )}
+    >
+      <span className={cn('flex-1', !display && 'text-muted-foreground')}>
+        {display ?? emptyText}
+      </span>
+      {!disabled && (
+        <Pencil className="h-3 w-3 opacity-0 transition-opacity group-hover:opacity-50" />
+      )}
+    </button>
+  );
+}
+
+function flagEmoji(code: string): string {
+  if (code.length !== 2) return '';
+  const A = 0x1f1e6;
+  const a = 'A'.charCodeAt(0);
+  return String.fromCodePoint(A + code.charCodeAt(0) - a, A + code.charCodeAt(1) - a);
+}
--- a/src/components/shared/inline-phone-field.tsx
+++ b/src/components/shared/inline-phone-field.tsx
@@ -0,0 +1,130 @@
+'use client';
+
+import { useState } from 'react';
+import { Loader2, Pencil } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { PhoneInput, type PhoneInputValue } from '@/components/shared/phone-input';
+import { parsePhone } from '@/lib/i18n/phone';
+import type { CountryCode } from '@/lib/i18n/countries';
+import { cn } from '@/lib/utils';
+
+interface InlinePhoneFieldProps {
+  /** E.164 form ('+442079460958'), null when unset. */
+  e164: string | null | undefined;
+  /** ISO-3166-1 alpha-2 the number was parsed against. */
+  country: string | null | undefined;
+  /** Falls back to this country if `country` isn't set. */
+  defaultCountry?: CountryCode;
+  onSave: (next: { e164: string | null; country: CountryCode }) => Promise<void>;
+  emptyText?: string;
+  disabled?: boolean;
+  className?: string;
+  'data-testid'?: string;
+}
+
+export function InlinePhoneField({
+  e164,
+  country,
+  defaultCountry,
+  onSave,
+  emptyText = '—',
+  disabled,
+  className,
+  'data-testid': testId,
+}: InlinePhoneFieldProps) {
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState<PhoneInputValue | null>(() => {
+    if (!e164 && !country) return null;
+    return {
+      e164: e164 ?? null,
+      country: (country as CountryCode | null) ?? defaultCountry ?? 'US',
+    };
+  });
+  const [saving, setSaving] = useState(false);
+
+  async function commit() {
+    const next = draft ?? { e164: null, country: defaultCountry ?? 'US' };
+    if (next.e164 === (e164 ?? null) && next.country === (country ?? null)) {
+      setEditing(false);
+      return;
+    }
+    setSaving(true);
+    try {
+      await onSave(next);
+      setEditing(false);
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : 'Failed to save');
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  if (editing) {
+    return (
+      <div className={cn('flex items-center gap-1', className)}>
+        <PhoneInput
+          value={draft}
+          onChange={(v) => setDraft(v)}
+          defaultCountry={defaultCountry}
+          data-testid={testId}
+        />
+        <button
+          type="button"
+          onClick={() => void commit()}
+          disabled={saving}
+          className="rounded px-2 py-1 text-xs font-medium hover:bg-muted disabled:opacity-50"
+        >
+          {saving ? <Loader2 className="h-3 w-3 animate-spin" /> : 'Save'}
+        </button>
+        <button
+          type="button"
+          onClick={() => {
+            setDraft(
+              e164 || country
+                ? {
+                    e164: e164 ?? null,
+                    country: (country as CountryCode | null) ?? defaultCountry ?? 'US',
+                  }
+                : null,
+            );
+            setEditing(false);
+          }}
+          disabled={saving}
+          className="rounded px-2 py-1 text-xs text-muted-foreground hover:bg-muted disabled:opacity-50"
+        >
+          Cancel
+        </button>
+      </div>
+    );
+  }
+
+  // Display: prefer the parsed national format (more readable than raw E.164).
+  let display: string | null = null;
+  if (e164) {
+    const parsed = parsePhone(e164, (country as CountryCode | undefined) ?? defaultCountry);
+    display = parsed.national ?? e164;
+  }
+
+  return (
+    <button
+      type="button"
+      disabled={disabled}
+      onClick={() => setEditing(true)}
+      data-testid={testId}
+      className={cn(
+        'group inline-flex items-center gap-1.5 rounded px-1 -mx-1 py-0.5 text-left text-sm',
+        'hover:bg-muted/60 focus-visible:bg-muted/60 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+        disabled && 'cursor-not-allowed opacity-60 hover:bg-transparent',
+        className,
+      )}
+    >
+      <span className={cn('flex-1', !display && 'text-muted-foreground')}>
+        {display ?? emptyText}
+      </span>
+      {!disabled && (
+        <Pencil className="h-3 w-3 opacity-0 transition-opacity group-hover:opacity-50" />
+      )}
+    </button>
+  );
+}
--- a/src/components/shared/inline-timezone-field.tsx
+++ b/src/components/shared/inline-timezone-field.tsx
@@ -0,0 +1,88 @@
+'use client';
+
+import { useState } from 'react';
+import { Loader2, Pencil } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { TimezoneCombobox } from '@/components/shared/timezone-combobox';
+import { formatTimezoneLabel } from '@/lib/i18n/timezones';
+import type { CountryCode } from '@/lib/i18n/countries';
+import { cn } from '@/lib/utils';
+
+interface InlineTimezoneFieldProps {
+  value: string | null | undefined;
+  onSave: (next: string | null) => Promise<void>;
+  /** Optional country to surface "Suggested" zones in the picker. */
+  countryHint?: CountryCode | null;
+  emptyText?: string;
+  disabled?: boolean;
+  className?: string;
+  'data-testid'?: string;
+}
+
+export function InlineTimezoneField({
+  value,
+  onSave,
+  countryHint,
+  emptyText = '—',
+  disabled,
+  className,
+  'data-testid': testId,
+}: InlineTimezoneFieldProps) {
+  const [editing, setEditing] = useState(false);
+  const [saving, setSaving] = useState(false);
+
+  async function commit(next: string | null) {
+    if (next === (value ?? null)) {
+      setEditing(false);
+      return;
+    }
+    setSaving(true);
+    try {
+      await onSave(next);
+      setEditing(false);
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : 'Failed to save');
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  if (editing) {
+    return (
+      <div className={cn('flex items-center gap-1', className)}>
+        <TimezoneCombobox
+          value={value}
+          onChange={(tz) => void commit(tz)}
+          countryHint={countryHint ?? undefined}
+          data-testid={testId}
+        />
+        {saving && <Loader2 className="h-3 w-3 animate-spin text-muted-foreground" />}
+      </div>
+    );
+  }
+
+  const display = value ? formatTimezoneLabel(value) : null;
+
+  return (
+    <button
+      type="button"
+      disabled={disabled}
+      onClick={() => setEditing(true)}
+      data-testid={testId}
+      className={cn(
+        'group inline-flex items-center gap-1.5 rounded px-1 -mx-1 py-0.5 text-left text-sm',
+        'hover:bg-muted/60 focus-visible:bg-muted/60 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+        disabled && 'cursor-not-allowed opacity-60 hover:bg-transparent',
+        className,
+      )}
+    >
+      <span className={cn('flex-1', !display && 'text-muted-foreground')}>
+        {display ?? emptyText}
+      </span>
+      {!disabled && (
+        <Pencil className="h-3 w-3 opacity-0 transition-opacity group-hover:opacity-50" />
+      )}
+    </button>
+  );
+}
--- a/src/components/shared/phone-input.tsx
+++ b/src/components/shared/phone-input.tsx
@@ -0,0 +1,144 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+import { Input } from '@/components/ui/input';
+import { CountryCombobox } from '@/components/shared/country-combobox';
+import { cn } from '@/lib/utils';
+import { callingCodeFor, formatAsYouType, parsePhone } from '@/lib/i18n/phone';
+import { detectDefaultCountry, type CountryCode } from '@/lib/i18n/countries';
+
+export interface PhoneInputValue {
+  /** E.164 form ('+442079460958'). Null when empty or unparseable. */
+  e164: string | null;
+  /** Country selected in the dropdown — drives the AsYouType formatter. */
+  country: CountryCode;
+}
+
+interface PhoneInputProps {
+  value: PhoneInputValue | null | undefined;
+  onChange: (next: PhoneInputValue) => void;
+  /** Pre-selects the dropdown when `value.country` isn't supplied. */
+  defaultCountry?: CountryCode;
+  placeholder?: string;
+  disabled?: boolean;
+  required?: boolean;
+  invalid?: boolean;
+  id?: string;
+  'data-testid'?: string;
+}
+
+/**
+ * Phone input with a country flag dropdown + format-as-you-type.
+ *
+ * Wire shape: emits `{ e164, country }` on every change. E.164 is null
+ * while the input is too short to parse — that's a form-validation
+ * concern, not an input concern. Pasting an international number
+ * (`+1 415…`) auto-switches the country dropdown to match.
+ *
+ * Implementation notes:
+ *   - The visible string is always the AsYouType national-format,
+ *     so users see e.g. "020 7946 0958" while typing GB digits.
+ *   - The `country` prop drives the AsYouType context; flipping
+ *     countries reformats the same digits against the new country
+ *     (matches what users expect when they fix a wrong country pick).
+ */
+export function PhoneInput({
+  value,
+  onChange,
+  defaultCountry,
+  placeholder = 'Phone number',
+  disabled,
+  required,
+  invalid,
+  id,
+  'data-testid': testId,
+}: PhoneInputProps) {
+  const [country, setCountry] = useState<CountryCode>(
+    () => value?.country ?? defaultCountry ?? detectDefaultCountry('US'),
+  );
+  const [display, setDisplay] = useState(() => {
+    if (!value?.e164) return '';
+    const parsed = parsePhone(value.e164, value.country);
+    return parsed.national ?? '';
+  });
+  // Track whether the user has typed since mount — keeps a controlled-from-props
+  // value sync on first render only.
+  const initialized = useRef(false);
+
+  useEffect(() => {
+    if (initialized.current) return;
+    initialized.current = true;
+  }, []);
+
+  function emit(rawDigits: string, currentCountry: CountryCode) {
+    const parsed = parsePhone(rawDigits, currentCountry);
+    onChange({ e164: parsed.e164, country: currentCountry });
+  }
+
+  function handleInput(raw: string) {
+    // Paste-detect: if user pasted an international format, parse it
+    // and flip the country dropdown to match — better UX than asking
+    // them to also click the dropdown.
+    if (raw.startsWith('+')) {
+      const parsed = parsePhone(raw);
+      if (parsed.country) {
+        setCountry(parsed.country);
+        const reformatted = formatAsYouType(raw, parsed.country);
+        setDisplay(reformatted);
+        emit(raw, parsed.country);
+        return;
+      }
+    }
+    const formatted = formatAsYouType(raw, country);
+    setDisplay(formatted);
+    emit(formatted, country);
+  }
+
+  function handleCountryChange(next: CountryCode | null) {
+    if (!next) return;
+    setCountry(next);
+    // Re-run the formatter against the new country so the visible
+    // string stays consistent with the dropdown.
+    const reformatted = formatAsYouType(display, next);
+    setDisplay(reformatted);
+    emit(reformatted, next);
+  }
+
+  return (
+    <div
+      className={cn(
+        'flex items-stretch gap-1.5',
+        invalid && '[&_input]:border-destructive [&_button[role=combobox]]:border-destructive',
+      )}
+    >
+      <CountryCombobox
+        value={country}
+        onChange={handleCountryChange}
+        compact
+        clearable={false}
+        disabled={disabled}
+        data-testid={testId ? `${testId}-country` : undefined}
+      />
+      <div className="flex flex-1 items-stretch overflow-hidden rounded-md border border-input focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2 focus-within:ring-offset-background">
+        <span className="flex select-none items-center bg-muted/40 px-2 text-sm tabular-nums text-muted-foreground">
+          {callingCodeFor(country)}
+        </span>
+        <Input
+          id={id}
+          type="tel"
+          inputMode="tel"
+          autoComplete="tel"
+          placeholder={placeholder}
+          value={display}
+          disabled={disabled}
+          required={required}
+          onChange={(e) => handleInput(e.target.value)}
+          // Strip the inner Input's own border so it sits flush with the country prefix.
+          className="flex-1 border-0 shadow-none focus-visible:ring-0 focus-visible:ring-offset-0"
+          data-testid={testId}
+        />
+      </div>
+    </div>
+  );
+}
--- a/src/components/shared/subdivision-combobox.tsx
+++ b/src/components/shared/subdivision-combobox.tsx
@@ -0,0 +1,124 @@
+'use client';
+
+import { useMemo, useState } from 'react';
+import { Check, ChevronsUpDown } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '@/components/ui/command';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
+import { cn } from '@/lib/utils';
+import { subdivisionsForCountry } from '@/lib/i18n/subdivisions';
+import type { CountryCode } from '@/lib/i18n/countries';
+
+interface SubdivisionComboboxProps {
+  value: string | null | undefined;
+  onChange: (code: string | null) => void;
+  /**
+   * Country whose subdivisions populate the dropdown. When the country
+   * has no recognized subdivisions, the trigger renders disabled with
+   * an empty-state hint so the form still lays out.
+   */
+  country: CountryCode | null | undefined;
+  placeholder?: string;
+  disabled?: boolean;
+  className?: string;
+  clearable?: boolean;
+  id?: string;
+  'data-testid'?: string;
+}
+
+export function SubdivisionCombobox({
+  value,
+  onChange,
+  country,
+  placeholder = 'Select region…',
+  disabled,
+  className,
+  clearable = true,
+  id,
+  'data-testid': testId,
+}: SubdivisionComboboxProps) {
+  const [open, setOpen] = useState(false);
+
+  const options = useMemo(() => {
+    if (!country) return [];
+    return subdivisionsForCountry(country);
+  }, [country]);
+
+  const selected = value ? options.find((o) => o.code === value) : undefined;
+  const noCountry = !country;
+  const noSubdivisions = !noCountry && options.length === 0;
+  const isDisabled = disabled || noCountry || noSubdivisions;
+
+  let triggerLabel: string;
+  if (selected) triggerLabel = selected.name;
+  else if (noCountry) triggerLabel = 'Pick a country first';
+  else if (noSubdivisions) triggerLabel = 'No regions available';
+  else triggerLabel = placeholder;
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          id={id}
+          variant="outline"
+          role="combobox"
+          aria-expanded={open}
+          disabled={isDisabled}
+          className={cn('w-full justify-between', !selected && 'text-muted-foreground', className)}
+          data-testid={testId}
+        >
+          <span className="truncate text-sm">{triggerLabel}</span>
+          <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-[320px] p-0" align="start">
+        <Command>
+          <CommandInput placeholder={`Search ${country ?? 'regions'}…`} />
+          <CommandList>
+            <CommandEmpty>No region found.</CommandEmpty>
+            {clearable && value ? (
+              <CommandGroup>
+                <CommandItem
+                  value="__clear__"
+                  onSelect={() => {
+                    onChange(null);
+                    setOpen(false);
+                  }}
+                  className="text-muted-foreground"
+                >
+                  Clear selection
+                </CommandItem>
+              </CommandGroup>
+            ) : null}
+            <CommandGroup>
+              {options.map((opt) => (
+                <CommandItem
+                  key={opt.code}
+                  value={`${opt.name} ${opt.code}`}
+                  onSelect={() => {
+                    onChange(opt.code);
+                    setOpen(false);
+                  }}
+                >
+                  <Check
+                    className={cn('mr-2 h-4 w-4', value === opt.code ? 'opacity-100' : 'opacity-0')}
+                  />
+                  <span className="flex-1 truncate text-sm">{opt.name}</span>
+                  <span className="text-xs text-muted-foreground">{opt.code}</span>
+                </CommandItem>
+              ))}
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  );
+}
--- a/src/components/shared/timezone-combobox.tsx
+++ b/src/components/shared/timezone-combobox.tsx
@@ -0,0 +1,150 @@
+'use client';
+
+import { useMemo, useState } from 'react';
+import { Check, ChevronsUpDown } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandSeparator,
+} from '@/components/ui/command';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
+import { cn } from '@/lib/utils';
+import { formatTimezoneLabel, listAllTimezones, timezonesForCountry } from '@/lib/i18n/timezones';
+import type { CountryCode } from '@/lib/i18n/countries';
+
+interface TimezoneComboboxProps {
+  value: string | null | undefined;
+  onChange: (iana: string | null) => void;
+  /** When set, the dropdown surfaces matching zones first under a "Suggested" group. */
+  countryHint?: CountryCode;
+  placeholder?: string;
+  disabled?: boolean;
+  className?: string;
+  clearable?: boolean;
+  id?: string;
+  'data-testid'?: string;
+}
+
+export function TimezoneCombobox({
+  value,
+  onChange,
+  countryHint,
+  placeholder = 'Select timezone…',
+  disabled,
+  className,
+  clearable = true,
+  id,
+  'data-testid': testId,
+}: TimezoneComboboxProps) {
+  const [open, setOpen] = useState(false);
+
+  const allOptions = useMemo(() => {
+    return listAllTimezones().map((tz) => ({
+      tz,
+      label: formatTimezoneLabel(tz),
+    }));
+  }, []);
+
+  const suggested = useMemo(() => {
+    if (!countryHint) return [];
+    const set = new Set(timezonesForCountry(countryHint));
+    return allOptions.filter((o) => set.has(o.tz));
+  }, [allOptions, countryHint]);
+
+  const rest = useMemo(() => {
+    if (!suggested.length) return allOptions;
+    const suggestedSet = new Set(suggested.map((s) => s.tz));
+    return allOptions.filter((o) => !suggestedSet.has(o.tz));
+  }, [allOptions, suggested]);
+
+  const selectedLabel = value ? formatTimezoneLabel(value) : placeholder;
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          id={id}
+          variant="outline"
+          role="combobox"
+          aria-expanded={open}
+          disabled={disabled}
+          className={cn('w-full justify-between', !value && 'text-muted-foreground', className)}
+          data-testid={testId}
+        >
+          <span className="truncate text-sm">{selectedLabel}</span>
+          <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-[360px] p-0" align="start">
+        <Command>
+          <CommandInput placeholder="Search timezones…" />
+          <CommandList>
+            <CommandEmpty>No timezone found.</CommandEmpty>
+            {clearable && value ? (
+              <CommandGroup>
+                <CommandItem
+                  value="__clear__"
+                  onSelect={() => {
+                    onChange(null);
+                    setOpen(false);
+                  }}
+                  className="text-muted-foreground"
+                >
+                  Clear selection
+                </CommandItem>
+              </CommandGroup>
+            ) : null}
+            {suggested.length > 0 ? (
+              <>
+                <CommandGroup heading="Suggested">
+                  {suggested.map((opt) => (
+                    <CommandItem
+                      key={opt.tz}
+                      value={opt.tz}
+                      onSelect={() => {
+                        onChange(opt.tz);
+                        setOpen(false);
+                      }}
+                    >
+                      <Check
+                        className={cn(
+                          'mr-2 h-4 w-4',
+                          value === opt.tz ? 'opacity-100' : 'opacity-0',
+                        )}
+                      />
+                      <span className="truncate text-sm">{opt.label}</span>
+                    </CommandItem>
+                  ))}
+                </CommandGroup>
+                <CommandSeparator />
+              </>
+            ) : null}
+            <CommandGroup heading={suggested.length > 0 ? 'All zones' : undefined}>
+              {rest.map((opt) => (
+                <CommandItem
+                  key={opt.tz}
+                  value={opt.tz}
+                  onSelect={() => {
+                    onChange(opt.tz);
+                    setOpen(false);
+                  }}
+                >
+                  <Check
+                    className={cn('mr-2 h-4 w-4', value === opt.tz ? 'opacity-100' : 'opacity-0')}
+                  />
+                  <span className="truncate text-sm">{opt.label}</span>
+                </CommandItem>
+              ))}
+            </CommandGroup>
+          </CommandList>
+        </Command>
+      </PopoverContent>
+    </Popover>
+  );
+}