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>

package.json

@@ -61,7 +61,9 @@
     "drizzle-orm": "^0.38.0",
     "imapflow": "^1.2.13",
     "ioredis": "^5.4.0",
+    "iso-3166-2": "^1.0.0",
     "jose": "^6.2.1",
+    "libphonenumber-js": "^1.12.42",
     "lucide-react": "^0.460.0",
     "mailparser": "^3.9.4",
     "minio": "^8.0.0",
@@ -89,6 +91,7 @@
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.5",
     "@playwright/test": "^1.58.2",
+    "@types/iso-3166-2": "^1.0.4",
     "@types/mailparser": "^3.4.6",
     "@types/node": "^22.0.0",
     "@types/nodemailer": "^6.4.0",

pnpm-lock.yaml

@@ -128,9 +128,15 @@ importers:
       ioredis:
         specifier: ^5.4.0
         version: 5.10.0
+      iso-3166-2:
+        specifier: ^1.0.0
+        version: 1.0.0
       jose:
         specifier: ^6.2.1
         version: 6.2.1
+      libphonenumber-js:
+        specifier: ^1.12.42
+        version: 1.12.42
       lucide-react:
         specifier: ^0.460.0
         version: 0.460.0(react@19.2.4)
@@ -207,6 +213,9 @@ importers:
       '@playwright/test':
         specifier: ^1.58.2
         version: 1.58.2
+      '@types/iso-3166-2':
+        specifier: ^1.0.4
+        version: 1.0.4
       '@types/mailparser':
         specifier: ^3.4.6
         version: 3.4.6
@@ -2264,6 +2273,9 @@ packages:
   '@types/estree@1.0.8':
     resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}
 
+  '@types/iso-3166-2@1.0.4':
+    resolution: {integrity: sha512-tXaeT4FDobC8rAy6LoFvbGA4vhOQQNIdSRC5DAoYfT3D9ohnKHkDFxHzSln6WqTKVeKLrnMiMQubM8m3fqNp/w==}
+
   '@types/js-cookie@3.0.6':
     resolution: {integrity: sha512-wkw9yd1kEXOPnvEeEV1Go1MmxtBJL0RR79aOTAApecWFVu7w0NNXNqhcWgvw2YgZDYadliXkl14pa3WXw5jlCQ==}
 
@@ -3887,6 +3899,9 @@ packages:
     resolution: {integrity: sha512-6B3tLtFqtQS4ekarvLVMZ+X+VlvQekbe4taUkf/rhVO3d/h0M2rfARm/pXLcPEsjjMsFgrFgSrhQIxcSVrBz8w==}
     engines: {node: '>=18'}
 
+  iso-3166-2@1.0.0:
+    resolution: {integrity: sha512-xLAazfKZzwlsg/Zz/GQGQk3jJez5/2ORrjD3TjSuqz/arMht/xTK49c0GOE3afO/gEd9tHtBVVlfBla01unUng==}
+
   istanbul-lib-coverage@3.2.2:
     resolution: {integrity: sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==}
     engines: {node: '>=8'}
@@ -3975,6 +3990,9 @@ packages:
   libmime@5.3.7:
     resolution: {integrity: sha512-FlDb3Wtha8P01kTL3P9M+ZDNDWPKPmKHWaU/cG/lg5pfuAwdflVpZE+wm9m7pKmC5ww6s+zTxBKS1p6yl3KpSw==}
 
+  libphonenumber-js@1.12.42:
+    resolution: {integrity: sha512-oKQFPTibqQwZZkChCDVMFVJXMZdyJNqDWZWYNn8BgyAaK/6yFJEowxCY0RVFirRyWP63hMRuKlkSEd9qlvbWXg==}
+
   libqp@2.1.1:
     resolution: {integrity: sha512-0Wd+GPz1O134cP62YU2GTOPNA7Qgl09XwCqM5zpBv87ERCXdfDtyKXvV7c9U22yWJh44QZqBocFnXN11K96qow==}
 
@@ -7311,6 +7329,8 @@ snapshots:
 
   '@types/estree@1.0.8': {}
 
+  '@types/iso-3166-2@1.0.4': {}
+
   '@types/js-cookie@3.0.6': {}
 
   '@types/json-schema@7.0.15': {}
@@ -9172,6 +9192,8 @@ snapshots:
 
   isexe@3.1.5: {}
 
+  iso-3166-2@1.0.0: {}
+
   istanbul-lib-coverage@3.2.2: {}
 
   istanbul-lib-report@3.0.1:
@@ -9259,6 +9281,8 @@ snapshots:
       libbase64: 1.3.0
       libqp: 2.1.1
 
+  libphonenumber-js@1.12.42: {}
+
   libqp@2.1.1: {}
 
   lightningcss-android-arm64@1.32.0:

src/app/api/public/residential-inquiries/route.ts

@@ -16,6 +16,8 @@ import { errorResponse, RateLimitError, ValidationError } from '@/lib/errors';
 import { logger } from '@/lib/logger';
 import { publicResidentialInquirySchema } from '@/lib/validators/residential';
 import { emitToRoom } from '@/lib/socket/server';
+import { parsePhone } from '@/lib/i18n/phone';
+import type { CountryCode } from '@/lib/i18n/countries';
 
 // ─── Rate limiter (5 per hour per IP) ────────────────────────────────────────
 
@@ -61,6 +63,16 @@ export async function POST(req: NextRequest) {
       throw new ValidationError('Unknown port');
     }
 
+    // If the website didn't pre-normalize, parse server-side. International
+    // strings parse without a hint; national-format submissions need a country.
+    let phoneE164 = data.phoneE164 ?? null;
+    let phoneCountry: CountryCode | null = (data.phoneCountry as CountryCode | null) ?? null;
+    if (!phoneE164) {
+      const parsed = parsePhone(data.phone, phoneCountry ?? undefined);
+      phoneE164 = parsed.e164;
+      phoneCountry = parsed.country ?? phoneCountry;
+    }
+
     const result = await withTransaction(async (tx) => {
       const [client] = await tx
         .insert(residentialClients)
@@ -69,7 +81,13 @@ export async function POST(req: NextRequest) {
           fullName: `${data.firstName.trim()} ${data.lastName.trim()}`.trim(),
           email: data.email,
           phone: data.phone,
+          phoneE164,
+          phoneCountry,
+          nationalityIso: data.nationalityIso ?? null,
+          timezone: data.timezone ?? null,
           placeOfResidence: data.placeOfResidence,
+          placeOfResidenceCountryIso: data.placeOfResidenceCountryIso ?? null,
+          subdivisionIso: data.subdivisionIso ?? null,
           preferredContactMethod: data.preferredContactMethod,
           source: 'website',
           status: 'prospect',

src/app/api/v1/clients/[id]/contacts/[contactId]/route.ts

@@ -5,10 +5,13 @@ import { withAuth, withPermission } from '@/lib/api/helpers';
 import { parseBody } from '@/lib/api/route-helpers';
 import { errorResponse } from '@/lib/errors';
 import { updateContact, removeContact } from '@/lib/services/clients.service';
+import { optionalCountryIsoSchema, optionalPhoneE164Schema } from '@/lib/validators/i18n';
 
 const updateContactSchema = z.object({
   channel: z.enum(['email', 'phone', 'whatsapp', 'other']).optional(),
   value: z.string().min(1).optional(),
+  valueE164: optionalPhoneE164Schema.optional(),
+  valueCountry: optionalCountryIsoSchema.optional(),
   label: z.string().optional(),
   isPrimary: z.boolean().optional(),
   notes: z.string().optional(),
@@ -18,18 +21,12 @@ export const PATCH = withAuth(
   withPermission('clients', 'edit', async (req, ctx, params) => {
     try {
       const body = await parseBody(req, updateContactSchema);
-      const contact = await updateContact(
+      const contact = await updateContact(params.contactId!, params.id!, ctx.portId, body, {
-        params.contactId!,
+        userId: ctx.userId,
-        params.id!,
+        portId: ctx.portId,
-        ctx.portId,
+        ipAddress: ctx.ipAddress,
-        body,
+        userAgent: ctx.userAgent,
-        {
+      });
-          userId: ctx.userId,
-          portId: ctx.portId,
-          ipAddress: ctx.ipAddress,
-          userAgent: ctx.userAgent,
-        },
-      );
       return NextResponse.json({ data: contact });
     } catch (error) {
       return errorResponse(error);

src/app/api/v1/clients/[id]/contacts/route.ts

@@ -5,10 +5,13 @@ import { withAuth, withPermission } from '@/lib/api/helpers';
 import { parseBody } from '@/lib/api/route-helpers';
 import { errorResponse } from '@/lib/errors';
 import { listContacts, addContact } from '@/lib/services/clients.service';
+import { optionalCountryIsoSchema, optionalPhoneE164Schema } from '@/lib/validators/i18n';
 
 const addContactSchema = z.object({
   channel: z.enum(['email', 'phone', 'whatsapp', 'other']),
   value: z.string().min(1),
+  valueE164: optionalPhoneE164Schema.optional(),
+  valueCountry: optionalCountryIsoSchema.optional(),
   label: z.string().optional(),
   isPrimary: z.boolean().optional().default(false),
   notes: z.string().optional(),

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`)}
+                      const channel = watch(`contacts.${index}.channel`);
-                      className="h-8"
+                      if (channel === 'phone' || channel === 'whatsapp') {
-                      placeholder="email@example.com"
+                        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>

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

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
+          {contact.channel === 'phone' || contact.channel === 'whatsapp' ? (
-            value={contact.value}
+            <InlinePhoneField
-            onSave={async (v) => {
+              e164={contact.valueE164 ?? null}
-              if (!v) {
+              country={contact.valueCountry ?? null}
-                toast.error('Value is required');
+              onSave={async ({ e164, country }) => {
-                return;
+                if (!e164) {
-              }
+                  toast.error('Phone number is required');
-              await onUpdate({ value: v });
+                  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
+      {isPhoneChannel ? (
-        value={value}
+        <div className="flex-1 min-w-0">
-        onChange={(e) => setValue(e.target.value)}
+          <PhoneInput
-        placeholder={channel === 'email' ? 'name@example.com' : '+1 555 0100'}
+            value={phoneValue}
-        className="h-7 text-sm flex-1 min-w-0"
+            onChange={(v) => setPhoneValue(v)}
-        autoFocus
+            data-testid="new-contact-phone"
-        disabled={saving}
+          />
-        onKeyDown={(e) => {
+        </div>
-          if (e.key === 'Enter') {
+      ) : (
-            e.preventDefault();
+        <Input
-            void submit();
+          value={value}
-          }
+          onChange={(e) => setValue(e.target.value)}
-          if (e.key === 'Escape') onCancel();
+          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}>

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;

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,

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;

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>

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,

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
+            <InlineCountryField
-              value={company.incorporationCountry}
+              value={company.incorporationCountryIso}
-              onSave={save('incorporationCountry')}
+              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">

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">

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('');
+      reset();
-      setEmail('');
-      setPhone('');
-      setPlaceOfResidence('');
-      setNotes('');
       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)} />

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>
+  );
+}

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);
+}

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>
+  );
+}

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>
+  );
+}

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>
+  );
+}

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>
+  );
+}

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>
+  );
+}

src/lib/db/migrations/0015_i18n_columns.sql

@@ -0,0 +1,16 @@
+ALTER TABLE "client_addresses" ADD COLUMN "subdivision_iso" text;--> statement-breakpoint
+ALTER TABLE "client_addresses" ADD COLUMN "country_iso" text;--> statement-breakpoint
+ALTER TABLE "client_contacts" ADD COLUMN "value_e164" text;--> statement-breakpoint
+ALTER TABLE "client_contacts" ADD COLUMN "value_country" text;--> statement-breakpoint
+ALTER TABLE "clients" ADD COLUMN "nationality_iso" text;--> statement-breakpoint
+ALTER TABLE "companies" ADD COLUMN "incorporation_country_iso" text;--> statement-breakpoint
+ALTER TABLE "companies" ADD COLUMN "incorporation_subdivision_iso" text;--> statement-breakpoint
+ALTER TABLE "company_addresses" ADD COLUMN "subdivision_iso" text;--> statement-breakpoint
+ALTER TABLE "company_addresses" ADD COLUMN "country_iso" text;--> statement-breakpoint
+ALTER TABLE "residential_clients" ADD COLUMN "phone_e164" text;--> statement-breakpoint
+ALTER TABLE "residential_clients" ADD COLUMN "phone_country" text;--> statement-breakpoint
+ALTER TABLE "residential_clients" ADD COLUMN "nationality_iso" text;--> statement-breakpoint
+ALTER TABLE "residential_clients" ADD COLUMN "timezone" text;--> statement-breakpoint
+ALTER TABLE "residential_clients" ADD COLUMN "place_of_residence_country_iso" text;--> statement-breakpoint
+ALTER TABLE "residential_clients" ADD COLUMN "subdivision_iso" text;--> statement-breakpoint
+CREATE INDEX "idx_clients_nationality_iso" ON "clients" USING btree ("nationality_iso");

src/lib/db/migrations/meta/_journal.json

@@ -106,6 +106,13 @@
       "when": 1777379952283,
       "tag": "0014_black_banshee",
       "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "7",
+      "when": 1777391373291,
+      "tag": "0015_i18n_columns",
+      "breakpoints": true
     }
   ]
 }

src/lib/db/schema/clients.ts

@@ -22,8 +22,12 @@ export const clients = pgTable(
       .references(() => ports.id),
     fullName: text('full_name').notNull(),
     nationality: text('nationality'),
+    /** ISO-3166-1 alpha-2 nationality code. Supersedes `nationality`
+     *  after the i18n backfill (PR10) drops the legacy column. */
+    nationalityIso: text('nationality_iso'),
     preferredContactMethod: text('preferred_contact_method'), // email, phone, whatsapp
     preferredLanguage: text('preferred_language'),
+    /** IANA timezone, e.g. 'Europe/Warsaw'. Validated client + server. */
     timezone: text('timezone'),
     source: text('source'), // website, manual, referral, broker
     sourceDetails: text('source_details'),
@@ -35,6 +39,7 @@ export const clients = pgTable(
     index('idx_clients_port').on(table.portId),
     index('idx_clients_name').on(table.portId, table.fullName),
     index('idx_clients_archived').on(table.portId, table.archivedAt),
+    index('idx_clients_nationality_iso').on(table.nationalityIso),
   ],
 );
 
@@ -49,6 +54,10 @@ export const clientContacts = pgTable(
       .references(() => clients.id, { onDelete: 'cascade' }),
     channel: text('channel').notNull(), // email, phone, whatsapp, other
     value: text('value').notNull(),
+    /** E.164-normalized phone number (only set when channel='phone'/'whatsapp'). */
+    valueE164: text('value_e164'),
+    /** ISO-3166-1 alpha-2 of the country this number was parsed against. */
+    valueCountry: text('value_country'),
     label: text('label'), // primary, secondary, work, personal, broker, assistant
     isPrimary: boolean('is_primary').notNull().default(false),
     notes: text('notes'),
@@ -154,8 +163,12 @@ export const clientAddresses = pgTable(
     streetAddress: text('street_address'),
     city: text('city'),
     stateProvince: text('state_province'),
+    /** ISO 3166-2 subdivision code (e.g. 'PL-MZ', 'US-CA'). Optional. */
+    subdivisionIso: text('subdivision_iso'),
     postalCode: text('postal_code'),
     country: text('country'),
+    /** ISO-3166-1 alpha-2 country code. Supersedes `country` after backfill. */
+    countryIso: text('country_iso'),
     isPrimary: boolean('is_primary').notNull().default(true),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),

src/lib/db/schema/companies.ts

@@ -25,6 +25,11 @@ export const companies = pgTable(
     taxId: text('tax_id'),
     registrationNumber: text('registration_number'),
     incorporationCountry: text('incorporation_country'),
+    /** ISO-3166-1 alpha-2 country of incorporation. Replaces the
+     *  free-text `incorporation_country` after the i18n backfill. */
+    incorporationCountryIso: text('incorporation_country_iso'),
+    /** ISO 3166-2 subdivision (state/province) of incorporation. Optional. */
+    incorporationSubdivisionIso: text('incorporation_subdivision_iso'),
     incorporationDate: timestamp('incorporation_date', { withTimezone: true, mode: 'date' }),
     status: text('status').notNull().default('active'), // 'active' | 'dissolved'
     billingEmail: text('billing_email'),
@@ -89,8 +94,12 @@ export const companyAddresses = pgTable(
     streetAddress: text('street_address'),
     city: text('city'),
     stateProvince: text('state_province'),
+    /** ISO 3166-2 subdivision code. Optional. */
+    subdivisionIso: text('subdivision_iso'),
     postalCode: text('postal_code'),
     country: text('country'),
+    /** ISO-3166-1 alpha-2 country code. Supersedes `country` after backfill. */
+    countryIso: text('country_iso'),
     isPrimary: boolean('is_primary').notNull().default(true),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),

src/lib/db/schema/residential.ts

@@ -20,7 +20,21 @@ export const residentialClients = pgTable(
     fullName: text('full_name').notNull(),
     email: text('email'),
     phone: text('phone'),
+    /** E.164-normalized phone, populated alongside `phone` once the i18n
+     *  PhoneInput component lands. The free-text `phone` column stays
+     *  for one release as a fallback for unparseable rows. */
+    phoneE164: text('phone_e164'),
+    /** ISO-3166-1 alpha-2 — country the phone was parsed against. */
+    phoneCountry: text('phone_country'),
+    /** ISO-3166-1 alpha-2 nationality. */
+    nationalityIso: text('nationality_iso'),
+    /** IANA timezone for scheduling/reminders. */
+    timezone: text('timezone'),
     placeOfResidence: text('place_of_residence'),
+    /** ISO-3166-1 alpha-2 country of residence. */
+    placeOfResidenceCountryIso: text('place_of_residence_country_iso'),
+    /** ISO 3166-2 subdivision code for place of residence. Optional. */
+    subdivisionIso: text('subdivision_iso'),
     preferredContactMethod: text('preferred_contact_method'), // email | phone
     /**
      * Lifecycle: prospect | active | inactive. Distinct from

src/lib/i18n/countries.ts

@@ -0,0 +1,311 @@
+/**
+ * ISO-3166-1 alpha-2 country list.
+ *
+ * Source: full ISO 3166-1 list as of 2026-04 (250 codes incl. UN
+ * member states + recognized territories). Country *names* are
+ * resolved at render time via `Intl.DisplayNames` so we don't ship
+ * a localized name table — the browser already has it.
+ *
+ * Validation uses the `ISO_COUNTRIES` Set; render uses
+ * `getCountryName(iso, locale)`.
+ */
+
+export const ALL_COUNTRY_CODES = [
+  'AD',
+  'AE',
+  'AF',
+  'AG',
+  'AI',
+  'AL',
+  'AM',
+  'AO',
+  'AQ',
+  'AR',
+  'AS',
+  'AT',
+  'AU',
+  'AW',
+  'AX',
+  'AZ',
+  'BA',
+  'BB',
+  'BD',
+  'BE',
+  'BF',
+  'BG',
+  'BH',
+  'BI',
+  'BJ',
+  'BL',
+  'BM',
+  'BN',
+  'BO',
+  'BQ',
+  'BR',
+  'BS',
+  'BT',
+  'BV',
+  'BW',
+  'BY',
+  'BZ',
+  'CA',
+  'CC',
+  'CD',
+  'CF',
+  'CG',
+  'CH',
+  'CI',
+  'CK',
+  'CL',
+  'CM',
+  'CN',
+  'CO',
+  'CR',
+  'CU',
+  'CV',
+  'CW',
+  'CX',
+  'CY',
+  'CZ',
+  'DE',
+  'DJ',
+  'DK',
+  'DM',
+  'DO',
+  'DZ',
+  'EC',
+  'EE',
+  'EG',
+  'EH',
+  'ER',
+  'ES',
+  'ET',
+  'FI',
+  'FJ',
+  'FK',
+  'FM',
+  'FO',
+  'FR',
+  'GA',
+  'GB',
+  'GD',
+  'GE',
+  'GF',
+  'GG',
+  'GH',
+  'GI',
+  'GL',
+  'GM',
+  'GN',
+  'GP',
+  'GQ',
+  'GR',
+  'GS',
+  'GT',
+  'GU',
+  'GW',
+  'GY',
+  'HK',
+  'HM',
+  'HN',
+  'HR',
+  'HT',
+  'HU',
+  'ID',
+  'IE',
+  'IL',
+  'IM',
+  'IN',
+  'IO',
+  'IQ',
+  'IR',
+  'IS',
+  'IT',
+  'JE',
+  'JM',
+  'JO',
+  'JP',
+  'KE',
+  'KG',
+  'KH',
+  'KI',
+  'KM',
+  'KN',
+  'KP',
+  'KR',
+  'KW',
+  'KY',
+  'KZ',
+  'LA',
+  'LB',
+  'LC',
+  'LI',
+  'LK',
+  'LR',
+  'LS',
+  'LT',
+  'LU',
+  'LV',
+  'LY',
+  'MA',
+  'MC',
+  'MD',
+  'ME',
+  'MF',
+  'MG',
+  'MH',
+  'MK',
+  'ML',
+  'MM',
+  'MN',
+  'MO',
+  'MP',
+  'MQ',
+  'MR',
+  'MS',
+  'MT',
+  'MU',
+  'MV',
+  'MW',
+  'MX',
+  'MY',
+  'MZ',
+  'NA',
+  'NC',
+  'NE',
+  'NF',
+  'NG',
+  'NI',
+  'NL',
+  'NO',
+  'NP',
+  'NR',
+  'NU',
+  'NZ',
+  'OM',
+  'PA',
+  'PE',
+  'PF',
+  'PG',
+  'PH',
+  'PK',
+  'PL',
+  'PM',
+  'PN',
+  'PR',
+  'PS',
+  'PT',
+  'PW',
+  'PY',
+  'QA',
+  'RE',
+  'RO',
+  'RS',
+  'RU',
+  'RW',
+  'SA',
+  'SB',
+  'SC',
+  'SD',
+  'SE',
+  'SG',
+  'SH',
+  'SI',
+  'SJ',
+  'SK',
+  'SL',
+  'SM',
+  'SN',
+  'SO',
+  'SR',
+  'SS',
+  'ST',
+  'SV',
+  'SX',
+  'SY',
+  'SZ',
+  'TC',
+  'TD',
+  'TF',
+  'TG',
+  'TH',
+  'TJ',
+  'TK',
+  'TL',
+  'TM',
+  'TN',
+  'TO',
+  'TR',
+  'TT',
+  'TV',
+  'TW',
+  'TZ',
+  'UA',
+  'UG',
+  'UM',
+  'US',
+  'UY',
+  'UZ',
+  'VA',
+  'VC',
+  'VE',
+  'VG',
+  'VI',
+  'VN',
+  'VU',
+  'WF',
+  'WS',
+  'YE',
+  'YT',
+  'ZA',
+  'ZM',
+  'ZW',
+] as const;
+
+export type CountryCode = (typeof ALL_COUNTRY_CODES)[number];
+
+export const ISO_COUNTRIES: ReadonlySet<string> = new Set(ALL_COUNTRY_CODES);
+
+export function isValidCountryCode(code: string): code is CountryCode {
+  return ISO_COUNTRIES.has(code);
+}
+
+/**
+ * Browser-localized display name for a country code.
+ * Caches `Intl.DisplayNames` instances by locale to avoid repeated allocation.
+ */
+const displayNameCache = new Map<string, Intl.DisplayNames>();
+
+function getDisplay(locale: string): Intl.DisplayNames {
+  let dn = displayNameCache.get(locale);
+  if (!dn) {
+    dn = new Intl.DisplayNames([locale], { type: 'region' });
+    displayNameCache.set(locale, dn);
+  }
+  return dn;
+}
+
+export function getCountryName(code: string, locale = 'en'): string {
+  if (!isValidCountryCode(code)) return code;
+  try {
+    return getDisplay(locale).of(code) ?? code;
+  } catch {
+    return code;
+  }
+}
+
+/**
+ * Detect a sensible default country from the runtime context.
+ * Browser path: navigator.language (`'en-GB'` → `'GB'`).
+ * Server / unknown path: falls back to the provided default (`'US'` per spec).
+ */
+export function detectDefaultCountry(fallback: CountryCode = 'US'): CountryCode {
+  if (typeof navigator === 'undefined') return fallback;
+  const lang = navigator.language;
+  if (!lang) return fallback;
+  // Locale tags look like 'en', 'en-US', 'pl-PL'. Take the region part.
+  const parts = lang.split('-');
+  const region = parts.length > 1 ? parts[parts.length - 1]?.toUpperCase() : '';
+  if (region && isValidCountryCode(region)) return region;
+  return fallback;
+}

src/lib/i18n/phone.ts

@@ -0,0 +1,80 @@
+/**
+ * Phone-number helpers built on libphonenumber-js.
+ *
+ * Uses the default `min` build (~110 KB gz). The `/mobile` build
+ * rejects landlines and reserved-range numbers, which is wrong for
+ * a marina CRM where clients commonly give office numbers.
+ * The `/max` build adds carrier/geocoding we don't need.
+ */
+
+import {
+  AsYouType,
+  parsePhoneNumberFromString,
+  isValidPhoneNumber as libIsValid,
+  getCountryCallingCode,
+  type CountryCode as LibCountryCode,
+} from 'libphonenumber-js';
+
+import type { CountryCode } from './countries';
+
+export interface ParsedPhone {
+  /** E.164 form, e.g. '+442079460958'. Null when the input isn't parseable. */
+  e164: string | null;
+  /** ISO alpha-2 of the country the number was parsed against. */
+  country: CountryCode | null;
+  /** Display-friendly national format, e.g. '020 7946 0958'. */
+  national: string | null;
+  /** Display-friendly international format, e.g. '+44 20 7946 0958'. */
+  international: string | null;
+  isValid: boolean;
+}
+
+const EMPTY: ParsedPhone = {
+  e164: null,
+  country: null,
+  national: null,
+  international: null,
+  isValid: false,
+};
+
+/**
+ * Parse a raw user-typed phone string into a normalized record.
+ * `defaultCountry` provides context when the input lacks a +country prefix.
+ */
+export function parsePhone(raw: string, defaultCountry?: CountryCode): ParsedPhone {
+  const trimmed = raw.trim();
+  if (!trimmed) return EMPTY;
+  try {
+    const parsed = parsePhoneNumberFromString(trimmed, defaultCountry as LibCountryCode);
+    if (!parsed) return EMPTY;
+    return {
+      e164: parsed.number,
+      country: (parsed.country ?? null) as CountryCode | null,
+      national: parsed.formatNational(),
+      international: parsed.formatInternational(),
+      isValid: parsed.isValid(),
+    };
+  } catch {
+    return EMPTY;
+  }
+}
+
+/**
+ * Format the in-progress digits with `AsYouType` for live typing.
+ * Returns the formatted string in the country's national style.
+ */
+export function formatAsYouType(raw: string, country: CountryCode): string {
+  const formatter = new AsYouType(country as LibCountryCode);
+  return formatter.input(raw);
+}
+
+/**
+ * Strict validation for zod / form layer. Accepts E.164 only.
+ */
+export function isValidE164(value: string): boolean {
+  return libIsValid(value);
+}
+
+export function callingCodeFor(country: CountryCode): string {
+  return `+${getCountryCallingCode(country as LibCountryCode)}`;
+}

src/lib/i18n/subdivisions.ts

@@ -0,0 +1,79 @@
+/**
+ * Country → ISO 3166-2 subdivision (state/province/region) catalog.
+ *
+ * Backed by the `iso-3166-2` npm package which ships the full ISO
+ * 3166-2 dataset (~5000 entries across every country). We expose a
+ * thin wrapper so the combobox doesn't have to know the library
+ * shape, and so we can normalize the records into a uniform
+ * `{ code, name }` pair.
+ *
+ * Subdivisions are an OPTIONAL field per the v1 spec. Countries
+ * without recognized subdivisions return an empty array; the
+ * combobox renders an empty state in that case.
+ */
+
+import isoCountries from 'iso-3166-2';
+
+import type { CountryCode } from './countries';
+
+export interface Subdivision {
+  /** ISO 3166-2 code, e.g. 'PL-MZ', 'US-CA', 'GB-SCT'. */
+  code: string;
+  /** Display name (English baseline from the iso-3166-2 dataset). */
+  name: string;
+  /** Subdivision type — 'State', 'Province', 'Region', etc. */
+  type?: string;
+}
+
+interface IsoCountryRecord {
+  name: string;
+  sub: Record<string, { type: string; name: string }>;
+}
+
+const cache = new Map<string, readonly Subdivision[]>();
+
+function loadFor(country: CountryCode): readonly Subdivision[] {
+  const hit = cache.get(country);
+  if (hit) return hit;
+  // The `iso-3166-2` package exposes a `country` lookup. Defensive
+  // because some country codes (e.g. obscure territories) lack subs.
+  const lookup = (isoCountries as unknown as { country: (c: string) => IsoCountryRecord | null })
+    .country;
+  const record = lookup ? lookup(country) : null;
+  if (!record?.sub) {
+    cache.set(country, []);
+    return [];
+  }
+  const list: Subdivision[] = Object.entries(record.sub)
+    .map(([code, { name, type }]) => ({ code, name, type }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  cache.set(country, list);
+  return list;
+}
+
+/**
+ * Returns the subdivision list for a country. Empty array when none
+ * are recognized — caller can use this to hide the field.
+ */
+export function subdivisionsForCountry(country: CountryCode): readonly Subdivision[] {
+  return loadFor(country);
+}
+
+export function hasSubdivisions(country: CountryCode): boolean {
+  return loadFor(country).length > 0;
+}
+
+export function isValidSubdivisionCode(code: string): boolean {
+  // ISO 3166-2 codes follow `XX-YYY` — derive the country from the prefix.
+  const country = code.split('-')[0];
+  if (!country || country.length !== 2) return false;
+  const list = loadFor(country as CountryCode);
+  return list.some((s) => s.code === code);
+}
+
+export function getSubdivisionName(code: string): string {
+  const country = code.split('-')[0];
+  if (!country) return code;
+  const list = loadFor(country as CountryCode);
+  return list.find((s) => s.code === code)?.name ?? code;
+}

src/lib/i18n/timezones.ts

@@ -0,0 +1,411 @@
+/**
+ * Country → IANA timezone mapping.
+ *
+ * For single-zone countries, value is one IANA string.
+ * For multi-zone countries, value is the primary IANA string followed
+ * by all valid alternates. Source: IANA tzdb (current as of 2026-04).
+ *
+ * The full ~600-entry IANA list comes from `Intl.supportedValuesOf('timeZone')`
+ * at runtime; this map only handles the country→default lookup.
+ */
+
+import type { CountryCode } from './countries';
+
+type TimezoneList = readonly [primary: string, ...alternates: string[]];
+
+// Multi-zone countries — list every IANA zone.
+const MULTI_ZONE: Partial<Record<CountryCode, TimezoneList>> = {
+  AU: [
+    'Australia/Sydney',
+    'Australia/Melbourne',
+    'Australia/Brisbane',
+    'Australia/Adelaide',
+    'Australia/Perth',
+    'Australia/Hobart',
+    'Australia/Darwin',
+  ],
+  BR: [
+    'America/Sao_Paulo',
+    'America/Manaus',
+    'America/Rio_Branco',
+    'America/Belem',
+    'America/Recife',
+    'America/Cuiaba',
+    'America/Fortaleza',
+    'America/Bahia',
+    'America/Noronha',
+  ],
+  CA: [
+    'America/Toronto',
+    'America/Vancouver',
+    'America/Edmonton',
+    'America/Winnipeg',
+    'America/Halifax',
+    'America/St_Johns',
+    'America/Regina',
+    'America/Whitehorse',
+  ],
+  CD: ['Africa/Kinshasa', 'Africa/Lubumbashi'],
+  ID: ['Asia/Jakarta', 'Asia/Pontianak', 'Asia/Makassar', 'Asia/Jayapura'],
+  KZ: [
+    'Asia/Almaty',
+    'Asia/Atyrau',
+    'Asia/Aqtau',
+    'Asia/Aqtobe',
+    'Asia/Oral',
+    'Asia/Qostanay',
+    'Asia/Qyzylorda',
+  ],
+  MN: ['Asia/Ulaanbaatar', 'Asia/Hovd', 'Asia/Choibalsan'],
+  MX: [
+    'America/Mexico_City',
+    'America/Cancun',
+    'America/Merida',
+    'America/Monterrey',
+    'America/Mazatlan',
+    'America/Chihuahua',
+    'America/Hermosillo',
+    'America/Tijuana',
+  ],
+  RU: [
+    'Europe/Moscow',
+    'Europe/Kaliningrad',
+    'Europe/Samara',
+    'Asia/Yekaterinburg',
+    'Asia/Omsk',
+    'Asia/Novosibirsk',
+    'Asia/Krasnoyarsk',
+    'Asia/Irkutsk',
+    'Asia/Yakutsk',
+    'Asia/Vladivostok',
+    'Asia/Magadan',
+    'Asia/Kamchatka',
+  ],
+  US: [
+    'America/New_York',
+    'America/Chicago',
+    'America/Denver',
+    'America/Los_Angeles',
+    'America/Phoenix',
+    'America/Anchorage',
+    'America/Honolulu',
+    'America/Indianapolis',
+    'America/Detroit',
+    'America/Boise',
+    'America/Adak',
+    'America/Juneau',
+    'America/Nome',
+    'Pacific/Guam',
+    'America/Puerto_Rico',
+  ],
+};
+
+// Single-zone primary lookup. Sourced from IANA tzdb's zone1970.tab.
+const SINGLE_ZONE: Partial<Record<CountryCode, string>> = {
+  AD: 'Europe/Andorra',
+  AE: 'Asia/Dubai',
+  AF: 'Asia/Kabul',
+  AG: 'America/Antigua',
+  AI: 'America/Anguilla',
+  AL: 'Europe/Tirane',
+  AM: 'Asia/Yerevan',
+  AO: 'Africa/Luanda',
+  AQ: 'Antarctica/McMurdo',
+  AR: 'America/Argentina/Buenos_Aires',
+  AS: 'Pacific/Pago_Pago',
+  AT: 'Europe/Vienna',
+  AW: 'America/Aruba',
+  AX: 'Europe/Mariehamn',
+  AZ: 'Asia/Baku',
+  BA: 'Europe/Sarajevo',
+  BB: 'America/Barbados',
+  BD: 'Asia/Dhaka',
+  BE: 'Europe/Brussels',
+  BF: 'Africa/Ouagadougou',
+  BG: 'Europe/Sofia',
+  BH: 'Asia/Bahrain',
+  BI: 'Africa/Bujumbura',
+  BJ: 'Africa/Porto-Novo',
+  BL: 'America/St_Barthelemy',
+  BM: 'Atlantic/Bermuda',
+  BN: 'Asia/Brunei',
+  BO: 'America/La_Paz',
+  BQ: 'America/Kralendijk',
+  BS: 'America/Nassau',
+  BT: 'Asia/Thimphu',
+  BV: 'Antarctica/Syowa',
+  BW: 'Africa/Gaborone',
+  BY: 'Europe/Minsk',
+  BZ: 'America/Belize',
+  CC: 'Indian/Cocos',
+  CF: 'Africa/Bangui',
+  CG: 'Africa/Brazzaville',
+  CH: 'Europe/Zurich',
+  CI: 'Africa/Abidjan',
+  CK: 'Pacific/Rarotonga',
+  CL: 'America/Santiago',
+  CM: 'Africa/Douala',
+  CN: 'Asia/Shanghai',
+  CO: 'America/Bogota',
+  CR: 'America/Costa_Rica',
+  CU: 'America/Havana',
+  CV: 'Atlantic/Cape_Verde',
+  CW: 'America/Curacao',
+  CX: 'Indian/Christmas',
+  CY: 'Asia/Nicosia',
+  CZ: 'Europe/Prague',
+  DE: 'Europe/Berlin',
+  DJ: 'Africa/Djibouti',
+  DK: 'Europe/Copenhagen',
+  DM: 'America/Dominica',
+  DO: 'America/Santo_Domingo',
+  DZ: 'Africa/Algiers',
+  EC: 'America/Guayaquil',
+  EE: 'Europe/Tallinn',
+  EG: 'Africa/Cairo',
+  EH: 'Africa/El_Aaiun',
+  ER: 'Africa/Asmara',
+  ES: 'Europe/Madrid',
+  ET: 'Africa/Addis_Ababa',
+  FI: 'Europe/Helsinki',
+  FJ: 'Pacific/Fiji',
+  FK: 'Atlantic/Stanley',
+  FM: 'Pacific/Pohnpei',
+  FO: 'Atlantic/Faroe',
+  FR: 'Europe/Paris',
+  GA: 'Africa/Libreville',
+  GB: 'Europe/London',
+  GD: 'America/Grenada',
+  GE: 'Asia/Tbilisi',
+  GF: 'America/Cayenne',
+  GG: 'Europe/Guernsey',
+  GH: 'Africa/Accra',
+  GI: 'Europe/Gibraltar',
+  GL: 'America/Godthab',
+  GM: 'Africa/Banjul',
+  GN: 'Africa/Conakry',
+  GP: 'America/Guadeloupe',
+  GQ: 'Africa/Malabo',
+  GR: 'Europe/Athens',
+  GS: 'Atlantic/South_Georgia',
+  GT: 'America/Guatemala',
+  GU: 'Pacific/Guam',
+  GW: 'Africa/Bissau',
+  GY: 'America/Guyana',
+  HK: 'Asia/Hong_Kong',
+  HM: 'Antarctica/Mawson',
+  HN: 'America/Tegucigalpa',
+  HR: 'Europe/Zagreb',
+  HT: 'America/Port-au-Prince',
+  HU: 'Europe/Budapest',
+  IE: 'Europe/Dublin',
+  IL: 'Asia/Jerusalem',
+  IM: 'Europe/Isle_of_Man',
+  IN: 'Asia/Kolkata',
+  IO: 'Indian/Chagos',
+  IQ: 'Asia/Baghdad',
+  IR: 'Asia/Tehran',
+  IS: 'Atlantic/Reykjavik',
+  IT: 'Europe/Rome',
+  JE: 'Europe/Jersey',
+  JM: 'America/Jamaica',
+  JO: 'Asia/Amman',
+  JP: 'Asia/Tokyo',
+  KE: 'Africa/Nairobi',
+  KG: 'Asia/Bishkek',
+  KH: 'Asia/Phnom_Penh',
+  KI: 'Pacific/Tarawa',
+  KM: 'Indian/Comoro',
+  KN: 'America/St_Kitts',
+  KP: 'Asia/Pyongyang',
+  KR: 'Asia/Seoul',
+  KW: 'Asia/Kuwait',
+  KY: 'America/Cayman',
+  LA: 'Asia/Vientiane',
+  LB: 'Asia/Beirut',
+  LC: 'America/St_Lucia',
+  LI: 'Europe/Vaduz',
+  LK: 'Asia/Colombo',
+  LR: 'Africa/Monrovia',
+  LS: 'Africa/Maseru',
+  LT: 'Europe/Vilnius',
+  LU: 'Europe/Luxembourg',
+  LV: 'Europe/Riga',
+  LY: 'Africa/Tripoli',
+  MA: 'Africa/Casablanca',
+  MC: 'Europe/Monaco',
+  MD: 'Europe/Chisinau',
+  ME: 'Europe/Podgorica',
+  MF: 'America/Marigot',
+  MG: 'Indian/Antananarivo',
+  MH: 'Pacific/Majuro',
+  MK: 'Europe/Skopje',
+  ML: 'Africa/Bamako',
+  MM: 'Asia/Yangon',
+  MO: 'Asia/Macau',
+  MP: 'Pacific/Saipan',
+  MQ: 'America/Martinique',
+  MR: 'Africa/Nouakchott',
+  MS: 'America/Montserrat',
+  MT: 'Europe/Malta',
+  MU: 'Indian/Mauritius',
+  MV: 'Indian/Maldives',
+  MW: 'Africa/Blantyre',
+  MY: 'Asia/Kuala_Lumpur',
+  MZ: 'Africa/Maputo',
+  NA: 'Africa/Windhoek',
+  NC: 'Pacific/Noumea',
+  NE: 'Africa/Niamey',
+  NF: 'Pacific/Norfolk',
+  NG: 'Africa/Lagos',
+  NI: 'America/Managua',
+  NL: 'Europe/Amsterdam',
+  NO: 'Europe/Oslo',
+  NP: 'Asia/Kathmandu',
+  NR: 'Pacific/Nauru',
+  NU: 'Pacific/Niue',
+  NZ: 'Pacific/Auckland',
+  OM: 'Asia/Muscat',
+  PA: 'America/Panama',
+  PE: 'America/Lima',
+  PF: 'Pacific/Tahiti',
+  PG: 'Pacific/Port_Moresby',
+  PH: 'Asia/Manila',
+  PK: 'Asia/Karachi',
+  PL: 'Europe/Warsaw',
+  PM: 'America/Miquelon',
+  PN: 'Pacific/Pitcairn',
+  PR: 'America/Puerto_Rico',
+  PS: 'Asia/Gaza',
+  PT: 'Europe/Lisbon',
+  PW: 'Pacific/Palau',
+  PY: 'America/Asuncion',
+  QA: 'Asia/Qatar',
+  RE: 'Indian/Reunion',
+  RO: 'Europe/Bucharest',
+  RS: 'Europe/Belgrade',
+  RW: 'Africa/Kigali',
+  SA: 'Asia/Riyadh',
+  SB: 'Pacific/Guadalcanal',
+  SC: 'Indian/Mahe',
+  SD: 'Africa/Khartoum',
+  SE: 'Europe/Stockholm',
+  SG: 'Asia/Singapore',
+  SH: 'Atlantic/St_Helena',
+  SI: 'Europe/Ljubljana',
+  SJ: 'Arctic/Longyearbyen',
+  SK: 'Europe/Bratislava',
+  SL: 'Africa/Freetown',
+  SM: 'Europe/San_Marino',
+  SN: 'Africa/Dakar',
+  SO: 'Africa/Mogadishu',
+  SR: 'America/Paramaribo',
+  SS: 'Africa/Juba',
+  ST: 'Africa/Sao_Tome',
+  SV: 'America/El_Salvador',
+  SX: 'America/Lower_Princes',
+  SY: 'Asia/Damascus',
+  SZ: 'Africa/Mbabane',
+  TC: 'America/Grand_Turk',
+  TD: 'Africa/Ndjamena',
+  TF: 'Indian/Kerguelen',
+  TG: 'Africa/Lome',
+  TH: 'Asia/Bangkok',
+  TJ: 'Asia/Dushanbe',
+  TK: 'Pacific/Fakaofo',
+  TL: 'Asia/Dili',
+  TM: 'Asia/Ashgabat',
+  TN: 'Africa/Tunis',
+  TO: 'Pacific/Tongatapu',
+  TR: 'Europe/Istanbul',
+  TT: 'America/Port_of_Spain',
+  TV: 'Pacific/Funafuti',
+  TW: 'Asia/Taipei',
+  TZ: 'Africa/Dar_es_Salaam',
+  UA: 'Europe/Kyiv',
+  UG: 'Africa/Kampala',
+  UM: 'Pacific/Wake',
+  UY: 'America/Montevideo',
+  UZ: 'Asia/Tashkent',
+  VA: 'Europe/Vatican',
+  VC: 'America/St_Vincent',
+  VE: 'America/Caracas',
+  VG: 'America/Tortola',
+  VI: 'America/St_Thomas',
+  VN: 'Asia/Ho_Chi_Minh',
+  VU: 'Pacific/Efate',
+  WF: 'Pacific/Wallis',
+  WS: 'Pacific/Apia',
+  YE: 'Asia/Aden',
+  YT: 'Indian/Mayotte',
+  ZA: 'Africa/Johannesburg',
+  ZM: 'Africa/Lusaka',
+  ZW: 'Africa/Harare',
+};
+
+/**
+ * Returns the IANA zone(s) for a country. Always returns at least one
+ * entry; the first entry is the primary/most-populous zone.
+ */
+export function timezonesForCountry(country: CountryCode): readonly string[] {
+  const multi = MULTI_ZONE[country];
+  if (multi) return multi;
+  const single = SINGLE_ZONE[country];
+  return single ? [single] : [];
+}
+
+/**
+ * Returns the single best-default IANA timezone for a country, or null
+ * when the dataset has no entry (caller should fall back to a generic
+ * default like 'UTC').
+ */
+export function primaryTimezoneFor(country: CountryCode): string | null {
+  const list = timezonesForCountry(country);
+  return list[0] ?? null;
+}
+
+/** True when the country has more than one valid zone (UI shows a sub-select). */
+export function isMultiZone(country: CountryCode): boolean {
+  const list = timezonesForCountry(country);
+  return list.length > 1;
+}
+
+/**
+ * Master IANA timezone list — uses Intl when available (modern browsers
+ * + Node 21+). Falls back to a small bundled list when missing.
+ */
+export function listAllTimezones(): readonly string[] {
+  if (typeof Intl !== 'undefined' && 'supportedValuesOf' in Intl) {
+    try {
+      const supported = Intl.supportedValuesOf('timeZone') as string[];
+      if (Array.isArray(supported) && supported.length > 0) return supported;
+    } catch {
+      // fall through
+    }
+  }
+  // Tiny fallback drawn from our country map — covers ~250 entries and
+  // never less than the timezones we'd otherwise reference.
+  const set = new Set<string>();
+  for (const tz of Object.values(SINGLE_ZONE)) set.add(tz!);
+  for (const list of Object.values(MULTI_ZONE)) {
+    for (const tz of list ?? []) set.add(tz);
+  }
+  return Array.from(set).sort();
+}
+
+/**
+ * Pretty-format a timezone for display: `'Europe/London (UTC+1)'`.
+ * The offset is computed against `now` so it follows DST.
+ */
+export function formatTimezoneLabel(tz: string, now: Date = new Date()): string {
+  try {
+    const parts = new Intl.DateTimeFormat('en', {
+      timeZone: tz,
+      timeZoneName: 'shortOffset',
+    }).formatToParts(now);
+    const offset = parts.find((p) => p.type === 'timeZoneName')?.value ?? '';
+    return offset ? `${tz} (${offset})` : tz;
+  } catch {
+    return tz;
+  }
+}

src/lib/services/clients.service.ts

@@ -372,7 +372,15 @@ export async function listContacts(clientId: string, portId: string) {
 export async function addContact(
   clientId: string,
   portId: string,
-  data: { channel: string; value: string; label?: string; isPrimary?: boolean; notes?: string },
+  data: {
+    channel: string;
+    value: string;
+    valueE164?: string | null;
+    valueCountry?: string | null;
+    label?: string;
+    isPrimary?: boolean;
+    notes?: string;
+  },
   meta: AuditMeta,
 ) {
   const client = await db.query.clients.findFirst({
@@ -408,6 +416,8 @@ export async function updateContact(
   data: Partial<{
     channel: string;
     value: string;
+    valueE164: string | null;
+    valueCountry: string | null;
     label: string;
     isPrimary: boolean;
     notes: string;

src/lib/validators/clients.ts

@@ -1,12 +1,21 @@
 import { z } from 'zod';
 
 import { baseListQuerySchema } from '@/lib/api/route-helpers';
+import {
+  optionalCountryIsoSchema,
+  optionalIanaTimezoneSchema,
+  optionalPhoneE164Schema,
+} from '@/lib/validators/i18n';
 
 // ─── Contact sub-schema ──────────────────────────────────────────────────────
 
 export const contactSchema = z.object({
   channel: z.enum(['email', 'phone', 'whatsapp', 'other']),
   value: z.string().min(1),
+  /** E.164-normalized number; required when channel is phone/whatsapp. */
+  valueE164: optionalPhoneE164Schema.optional(),
+  /** ISO-3166-1 alpha-2 country the number was parsed against. */
+  valueCountry: optionalCountryIsoSchema.optional(),
   label: z.string().optional(),
   isPrimary: z.boolean().optional().default(false),
   notes: z.string().optional(),
@@ -17,10 +26,14 @@ export const contactSchema = z.object({
 export const createClientSchema = z.object({
   fullName: z.string().min(1).max(200),
   contacts: z.array(contactSchema).min(1, 'At least one contact is required'),
+  /** Legacy free-text nationality. Kept for backfill only — new edits write `nationalityIso`. */
   nationality: z.string().optional(),
+  /** ISO-3166-1 alpha-2 nationality code. */
+  nationalityIso: optionalCountryIsoSchema.optional(),
   preferredContactMethod: z.enum(['email', 'phone', 'whatsapp']).optional(),
   preferredLanguage: z.string().optional(),
-  timezone: z.string().optional(),
+  /** IANA timezone (e.g. 'Europe/Warsaw'). */
+  timezone: optionalIanaTimezoneSchema.optional(),
   source: z.enum(['website', 'manual', 'referral', 'broker']).optional(),
   sourceDetails: z.string().optional(),
   tagIds: z.array(z.string()).optional().default([]),

src/lib/validators/companies.ts

@@ -1,12 +1,18 @@
 import { z } from 'zod';
 import { baseListQuerySchema } from '@/lib/api/route-helpers';
+import { optionalCountryIsoSchema, optionalSubdivisionIsoSchema } from '@/lib/validators/i18n';
 
 export const createCompanySchema = z.object({
   name: z.string().min(1).max(200),
   legalName: z.string().optional(),
   taxId: z.string().optional(),
   registrationNumber: z.string().optional(),
+  /** Legacy free-text. New writes use `incorporationCountryIso`. */
   incorporationCountry: z.string().optional(),
+  /** ISO-3166-1 alpha-2 country of incorporation. */
+  incorporationCountryIso: optionalCountryIsoSchema.optional(),
+  /** ISO 3166-2 state/province of incorporation. */
+  incorporationSubdivisionIso: optionalSubdivisionIsoSchema.optional(),
   incorporationDate: z.coerce.date().optional(),
   status: z.enum(['active', 'dissolved']).optional().default('active'),
   billingEmail: z.string().email().optional(),

src/lib/validators/i18n.ts

@@ -0,0 +1,78 @@
+/**
+ * Zod schemas wrapping the i18n primitives. Used by route handlers
+ * and form-level validation so the same rules run client + server.
+ */
+
+import { z } from 'zod';
+
+import { ISO_COUNTRIES } from '@/lib/i18n/countries';
+import { isValidE164 } from '@/lib/i18n/phone';
+import { isValidSubdivisionCode } from '@/lib/i18n/subdivisions';
+
+// ─── Country ──────────────────────────────────────────────────────────────────
+
+/** ISO-3166-1 alpha-2, uppercase. */
+export const countryIsoSchema = z
+  .string()
+  .length(2)
+  .toUpperCase()
+  .refine((c) => ISO_COUNTRIES.has(c), 'Unknown country code');
+
+// ─── Phone ────────────────────────────────────────────────────────────────────
+
+/** E.164 form, e.g. '+442079460958'. */
+export const phoneE164Schema = z
+  .string()
+  .min(1)
+  .refine((v) => isValidE164(v), 'Invalid phone number');
+
+// ─── Timezone ─────────────────────────────────────────────────────────────────
+
+/**
+ * IANA timezone (e.g. 'Europe/Warsaw'). Validates against
+ * `Intl.supportedValuesOf('timeZone')` when available. Older Node
+ * runtimes that lack the API fall back to a permissive shape check
+ * (`Region/City`) so the validator never blocks the path.
+ */
+export const ianaTimezoneSchema = z
+  .string()
+  .min(1)
+  .refine((tz) => {
+    if (typeof Intl !== 'undefined' && 'supportedValuesOf' in Intl) {
+      try {
+        const supported = Intl.supportedValuesOf('timeZone') as string[];
+        if (supported.length > 0) return supported.includes(tz);
+      } catch {
+        // fall through
+      }
+    }
+    return /^[A-Z][A-Za-z_+-]+\/[A-Za-z_+-]+/.test(tz);
+  }, 'Unknown timezone');
+
+// ─── Subdivision ──────────────────────────────────────────────────────────────
+
+/** ISO 3166-2 code, e.g. 'PL-MZ'. */
+export const subdivisionIsoSchema = z
+  .string()
+  .min(2)
+  .refine((code) => isValidSubdivisionCode(code), 'Unknown subdivision code');
+
+// ─── Optional variants ────────────────────────────────────────────────────────
+// Inline forms most callers will use — empty strings normalize to null
+// so the user clearing a field doesn't fail validation.
+
+export const optionalCountryIsoSchema = z
+  .union([z.literal(''), z.null(), countryIsoSchema])
+  .transform((v) => (v === '' || v === null ? null : v));
+
+export const optionalPhoneE164Schema = z
+  .union([z.literal(''), z.null(), phoneE164Schema])
+  .transform((v) => (v === '' || v === null ? null : v));
+
+export const optionalIanaTimezoneSchema = z
+  .union([z.literal(''), z.null(), ianaTimezoneSchema])
+  .transform((v) => (v === '' || v === null ? null : v));
+
+export const optionalSubdivisionIsoSchema = z
+  .union([z.literal(''), z.null(), subdivisionIsoSchema])
+  .transform((v) => (v === '' || v === null ? null : v));

src/lib/validators/residential.ts

@@ -1,6 +1,12 @@
 import { z } from 'zod';
 
 import { baseListQuerySchema } from '@/lib/api/route-helpers';
+import {
+  optionalCountryIsoSchema,
+  optionalIanaTimezoneSchema,
+  optionalPhoneE164Schema,
+  optionalSubdivisionIsoSchema,
+} from '@/lib/validators/i18n';
 
 // ─── Residential client ──────────────────────────────────────────────────────
 
@@ -12,7 +18,19 @@ export const createResidentialClientSchema = z.object({
     .optional()
     .or(z.literal('').transform(() => undefined)),
   phone: z.string().optional(),
+  /** E.164-normalized phone alongside the legacy free-text `phone`. */
+  phoneE164: optionalPhoneE164Schema.optional(),
+  /** ISO-3166-1 alpha-2 the phone was parsed against. */
+  phoneCountry: optionalCountryIsoSchema.optional(),
+  /** ISO-3166-1 alpha-2 nationality. */
+  nationalityIso: optionalCountryIsoSchema.optional(),
+  /** IANA timezone. */
+  timezone: optionalIanaTimezoneSchema.optional(),
   placeOfResidence: z.string().optional(),
+  /** ISO-3166-1 alpha-2 country of residence. */
+  placeOfResidenceCountryIso: optionalCountryIsoSchema.optional(),
+  /** ISO 3166-2 subdivision code for place of residence. */
+  subdivisionIso: optionalSubdivisionIsoSchema.optional(),
   preferredContactMethod: z.enum(['email', 'phone']).optional(),
   status: z.enum(['prospect', 'active', 'inactive']).optional().default('prospect'),
   source: z.enum(['website', 'manual', 'referral', 'broker']).optional(),
@@ -62,13 +80,30 @@ export const listResidentialInterestsSchema = baseListQuerySchema.extend({
 /**
  * Shape posted by the public website's residential interest form. Coerces
  * to internal create-shapes inside the public route.
+ *
+ * The legacy `phone` field stays free-text — older website builds may post
+ * raw international strings ('+44 7700 900123'). The route handler parses
+ * it server-side into `phoneE164` + `phoneCountry`. Newer website builds
+ * can post normalized values directly.
  */
 export const publicResidentialInquirySchema = z.object({
   firstName: z.string().min(1),
   lastName: z.string().min(1),
   email: z.string().email(),
   phone: z.string().min(1),
+  /** Pre-normalized E.164 form, optional for backwards compat. */
+  phoneE164: optionalPhoneE164Schema.optional(),
+  /** ISO-3166-1 alpha-2 the phone was parsed against. */
+  phoneCountry: optionalCountryIsoSchema.optional(),
+  /** ISO-3166-1 alpha-2 nationality. */
+  nationalityIso: optionalCountryIsoSchema.optional(),
+  /** IANA timezone. */
+  timezone: optionalIanaTimezoneSchema.optional(),
   placeOfResidence: z.string().optional(),
+  /** ISO-3166-1 alpha-2 country of residence. */
+  placeOfResidenceCountryIso: optionalCountryIsoSchema.optional(),
+  /** ISO 3166-2 subdivision code for place of residence. */
+  subdivisionIso: optionalSubdivisionIsoSchema.optional(),
   preferredContactMethod: z.enum(['email', 'phone']).optional(),
   notes: z.string().optional(),
   preferences: z.string().optional(),

tests/e2e/smoke/31-i18n-form-fields.spec.ts

@@ -0,0 +1,65 @@
+/**
+ * i18n PR11 — combobox surfaces.
+ *
+ * Proves the new country / timezone / phone / subdivision combobox triggers
+ * actually render in the create sheets we wired in PR6–8. Doesn't exercise
+ * the full data round-trip (covered by integration tests + form-spec
+ * coverage); this spec just guards the wiring against regression.
+ */
+
+import { test, expect } from '@playwright/test';
+
+import { login, navigateTo, waitForSheet } from './helpers';
+
+test.describe('i18n combobox wiring', () => {
+  test.beforeEach(async ({ page }) => {
+    await login(page, 'super_admin');
+  });
+
+  test('new residential client form exposes phone, country, timezone, subdivision pickers', async ({
+    page,
+  }) => {
+    await navigateTo(page, '/residential/clients');
+    await page.locator('main').getByRole('button', { name: /^new$/i }).first().click();
+    await waitForSheet(page);
+
+    const sheet = page.locator('[role="dialog"]');
+    // PhoneInput renders a flag dropdown + national-format input.
+    await expect(sheet.locator('[data-testid="rc-phone-country"]')).toBeVisible();
+    // Country / timezone combobox triggers.
+    await expect(sheet.locator('[data-testid="rc-nationality"]')).toBeVisible();
+    await expect(sheet.locator('[data-testid="rc-timezone"]')).toBeVisible();
+    // Country of residence + subdivision (subdivision is disabled until country picked).
+    await expect(sheet.locator('[data-testid="rc-residence-country"]')).toBeVisible();
+    await expect(sheet.locator('[data-testid="rc-residence-subdivision"]')).toBeVisible();
+  });
+
+  test('new client form swaps nationality input for CountryCombobox', async ({ page }) => {
+    await navigateTo(page, '/clients');
+    // Sheet trigger label varies by tenant — stick to the topbar action.
+    await page
+      .locator('main')
+      .getByRole('button', { name: /^new client$/i })
+      .first()
+      .click();
+    await waitForSheet(page);
+
+    const sheet = page.locator('[role="dialog"]');
+    await expect(sheet.locator('[data-testid="client-nationality"]')).toBeVisible();
+    await expect(sheet.locator('[data-testid="client-timezone"]')).toBeVisible();
+  });
+
+  test('new company form exposes incorporation country + subdivision pickers', async ({ page }) => {
+    await navigateTo(page, '/companies');
+    await page
+      .locator('main')
+      .getByRole('button', { name: /^new company$/i })
+      .first()
+      .click();
+    await waitForSheet(page);
+
+    const sheet = page.locator('[role="dialog"]');
+    await expect(sheet.locator('[data-testid="company-incorp-country"]')).toBeVisible();
+    await expect(sheet.locator('[data-testid="company-incorp-subdivision"]')).toBeVisible();
+  });
+});

tests/integration/public-residential-inquiry.test.ts

@@ -0,0 +1,138 @@
+/**
+ * i18n PR9–10 — public residential inquiry endpoint.
+ *
+ * Validates the server-side phone normalization that the public inquiry
+ * route runs when the website posts a raw international format (older
+ * Nuxt builds), and that pre-normalized payloads pass through unchanged.
+ */
+
+import { describe, it, expect, vi, beforeAll } from 'vitest';
+import { eq } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { residentialClients } from '@/lib/db/schema/residential';
+import { makePort } from '../helpers/factories';
+import { makeMockRequest } from '../helpers/route-tester';
+
+vi.mock('@/lib/socket/server', () => ({ emitToRoom: vi.fn() }));
+vi.mock('@/lib/email', () => ({ sendEmail: vi.fn().mockResolvedValue(undefined) }));
+
+let ipCounter = 1;
+function uniqueIp(): string {
+  ipCounter += 1;
+  return `10.50.${Math.floor(ipCounter / 255) % 255}.${ipCounter % 255}`;
+}
+
+describe('POST /api/public/residential-inquiries', () => {
+  let POST: typeof import('@/app/api/public/residential-inquiries/route').POST;
+
+  beforeAll(async () => {
+    const mod = await import('@/app/api/public/residential-inquiries/route');
+    POST = mod.POST;
+  });
+
+  it('parses a raw international phone string into E.164 + country', async () => {
+    const port = await makePort();
+    const email = `res-${Math.random().toString(36).slice(2, 8)}@test.local`;
+
+    const req = makeMockRequest(
+      'POST',
+      `http://localhost/api/public/residential-inquiries?portId=${port.id}`,
+      {
+        headers: { 'x-forwarded-for': uniqueIp() },
+        body: {
+          firstName: 'Anna',
+          lastName: 'Nowak',
+          email,
+          // Raw international format — server should normalize.
+          phone: '+44 20 7946 0958',
+          placeOfResidence: 'Warsaw',
+        },
+      },
+    );
+
+    const res = await POST(req);
+    expect(res.status).toBe(201);
+
+    const [row] = await db
+      .select()
+      .from(residentialClients)
+      .where(eq(residentialClients.email, email));
+
+    expect(row).toBeDefined();
+    expect(row?.phoneE164).toBe('+442079460958');
+    expect(row?.phoneCountry).toBe('GB');
+    // Free-text legacy column preserved verbatim for backfill.
+    expect(row?.phone).toBe('+44 20 7946 0958');
+  });
+
+  it('passes pre-normalized E.164 + country through unchanged', async () => {
+    const port = await makePort();
+    const email = `res-${Math.random().toString(36).slice(2, 8)}@test.local`;
+
+    const req = makeMockRequest(
+      'POST',
+      `http://localhost/api/public/residential-inquiries?portId=${port.id}`,
+      {
+        headers: { 'x-forwarded-for': uniqueIp() },
+        body: {
+          firstName: 'Jan',
+          lastName: 'Kowalski',
+          email,
+          phone: '+48 22 555 0100',
+          phoneE164: '+48225550100',
+          phoneCountry: 'PL',
+          nationalityIso: 'PL',
+          timezone: 'Europe/Warsaw',
+          placeOfResidence: 'Warsaw',
+          placeOfResidenceCountryIso: 'PL',
+        },
+      },
+    );
+
+    const res = await POST(req);
+    expect(res.status).toBe(201);
+
+    const [row] = await db
+      .select()
+      .from(residentialClients)
+      .where(eq(residentialClients.email, email));
+
+    expect(row?.phoneE164).toBe('+48225550100');
+    expect(row?.phoneCountry).toBe('PL');
+    expect(row?.nationalityIso).toBe('PL');
+    expect(row?.timezone).toBe('Europe/Warsaw');
+    expect(row?.placeOfResidenceCountryIso).toBe('PL');
+  });
+
+  it('persists a national-format phone when the website only sends a country hint', async () => {
+    const port = await makePort();
+    const email = `res-${Math.random().toString(36).slice(2, 8)}@test.local`;
+
+    const req = makeMockRequest(
+      'POST',
+      `http://localhost/api/public/residential-inquiries?portId=${port.id}`,
+      {
+        headers: { 'x-forwarded-for': uniqueIp() },
+        body: {
+          firstName: 'Marta',
+          lastName: 'Lewandowska',
+          email,
+          phone: '22 555 0200', // National-format
+          phoneCountry: 'PL', // Hint only — no E.164 yet.
+        },
+      },
+    );
+
+    const res = await POST(req);
+    expect(res.status).toBe(201);
+
+    const [row] = await db
+      .select()
+      .from(residentialClients)
+      .where(eq(residentialClients.email, email));
+
+    expect(row?.phoneE164).toBe('+48225550200');
+    expect(row?.phoneCountry).toBe('PL');
+  });
+});

tests/unit/i18n-countries.test.ts

@@ -0,0 +1,87 @@
+/**
+ * i18n PR1 — country dataset.
+ *
+ * Validates:
+ *  1. The dataset includes every common ISO-3166-1 alpha-2 code we'd
+ *     reasonably want (sanity sample, not exhaustive)
+ *  2. `isValidCountryCode` rejects bogus inputs
+ *  3. `getCountryName` returns localized names; falls back to the code
+ *  4. `detectDefaultCountry` returns the fallback in non-browser envs
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  ALL_COUNTRY_CODES,
+  ISO_COUNTRIES,
+  isValidCountryCode,
+  getCountryName,
+  detectDefaultCountry,
+} from '@/lib/i18n/countries';
+
+describe('i18n countries', () => {
+  it('includes core anglophone, EU, MENA, APAC, and Americas codes', () => {
+    const sample = ['US', 'GB', 'PL', 'DE', 'FR', 'AU', 'JP', 'BR', 'AE', 'NG', 'AI'];
+    for (const code of sample) {
+      expect(ISO_COUNTRIES.has(code)).toBe(true);
+    }
+  });
+
+  it('has at least 240 codes and is unique', () => {
+    expect(ALL_COUNTRY_CODES.length).toBeGreaterThanOrEqual(240);
+    expect(new Set(ALL_COUNTRY_CODES).size).toBe(ALL_COUNTRY_CODES.length);
+  });
+
+  it('isValidCountryCode rejects unknown / lowercased / 3-letter codes', () => {
+    expect(isValidCountryCode('US')).toBe(true);
+    expect(isValidCountryCode('us')).toBe(false);
+    expect(isValidCountryCode('USA')).toBe(false);
+    expect(isValidCountryCode('XX')).toBe(false);
+    expect(isValidCountryCode('')).toBe(false);
+  });
+
+  it('getCountryName returns localized names and falls back to the code on error', () => {
+    expect(getCountryName('US', 'en')).toMatch(/United States/);
+    expect(getCountryName('GB', 'en')).toMatch(/United Kingdom/);
+    expect(getCountryName('PL', 'pl')).toMatch(/Polska/i);
+    // Unknown code -> code itself.
+    expect(getCountryName('ZZ', 'en')).toBe('ZZ');
+  });
+
+  it('detectDefaultCountry returns the navigator region when valid', () => {
+    const original = globalThis.navigator;
+    Object.defineProperty(globalThis, 'navigator', {
+      value: { language: 'en-GB' },
+      configurable: true,
+    });
+    expect(detectDefaultCountry()).toBe('GB');
+    Object.defineProperty(globalThis, 'navigator', {
+      value: original,
+      configurable: true,
+    });
+  });
+
+  it('detectDefaultCountry uses the fallback when navigator is unset', () => {
+    const original = globalThis.navigator;
+    // @ts-expect-error force navigator to undefined for the duration of this test
+    delete globalThis.navigator;
+    expect(detectDefaultCountry()).toBe('US');
+    expect(detectDefaultCountry('GB')).toBe('GB');
+    Object.defineProperty(globalThis, 'navigator', {
+      value: original,
+      configurable: true,
+    });
+  });
+
+  it('detectDefaultCountry falls back when the navigator region is unknown', () => {
+    const original = globalThis.navigator;
+    Object.defineProperty(globalThis, 'navigator', {
+      value: { language: 'xx-ZZ' },
+      configurable: true,
+    });
+    expect(detectDefaultCountry()).toBe('US');
+    Object.defineProperty(globalThis, 'navigator', {
+      value: original,
+      configurable: true,
+    });
+  });
+});

tests/unit/i18n-phone.test.ts

@@ -0,0 +1,60 @@
+/**
+ * i18n PR2 — phone helpers.
+ *
+ * Validates:
+ *  1. parsePhone yields E.164 + country + display formats
+ *  2. parsePhone returns the empty record for unparseable input
+ *  3. AsYouType formats digits in the country's national style
+ *  4. isValidE164 accepts only E.164 form
+ *  5. callingCodeFor returns the dial prefix
+ *  6. International-format paste detects country
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parsePhone, formatAsYouType, isValidE164, callingCodeFor } from '@/lib/i18n/phone';
+
+describe('i18n phone', () => {
+  it('parses an international-format input regardless of defaultCountry', () => {
+    const r = parsePhone('+44 20 7946 0958');
+    expect(r.e164).toBe('+442079460958');
+    expect(r.country).toBe('GB');
+    expect(r.isValid).toBe(true);
+    expect(r.national).toMatch(/020 7946 0958/);
+    expect(r.international).toMatch(/\+44 20 7946 0958/);
+  });
+
+  it('parses a national-format input against the defaultCountry', () => {
+    const r = parsePhone('020 7946 0958', 'GB');
+    expect(r.e164).toBe('+442079460958');
+    expect(r.country).toBe('GB');
+    expect(r.isValid).toBe(true);
+  });
+
+  it('returns the empty record for empty / nonsense input', () => {
+    expect(parsePhone('').isValid).toBe(false);
+    expect(parsePhone('abc').isValid).toBe(false);
+    expect(parsePhone('').e164).toBeNull();
+  });
+
+  it('formatAsYouType produces national-format output', () => {
+    // GB national-format breaks 020 7946 0958.
+    const out = formatAsYouType('2079460958', 'GB');
+    expect(out.length).toBeGreaterThan(0);
+    // US national-format breaks (415) 555-1234.
+    const us = formatAsYouType('4155551234', 'US');
+    expect(us).toContain('415');
+  });
+
+  it('isValidE164 accepts only E.164', () => {
+    expect(isValidE164('+442079460958')).toBe(true);
+    expect(isValidE164('+1 415 555 1234')).toBe(true); // libphonenumber tolerates spaces
+    expect(isValidE164('020 7946 0958')).toBe(false); // missing +country prefix
+    expect(isValidE164('not a phone')).toBe(false);
+  });
+
+  it('callingCodeFor returns the dial prefix', () => {
+    expect(callingCodeFor('US')).toBe('+1');
+    expect(callingCodeFor('GB')).toBe('+44');
+    expect(callingCodeFor('PL')).toBe('+48');
+  });
+});

tests/unit/i18n-subdivisions.test.ts

@@ -0,0 +1,57 @@
+/**
+ * i18n PR4 — subdivisions.
+ *
+ * Validates:
+ *  1. Major countries (PL, US, CA, GB, AU) return non-empty lists
+ *  2. Sample known codes resolve to expected names
+ *  3. hasSubdivisions correctly classifies micro-states with no subs
+ *  4. Validation rejects garbage codes
+ *  5. getSubdivisionName returns the human name
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  subdivisionsForCountry,
+  hasSubdivisions,
+  isValidSubdivisionCode,
+  getSubdivisionName,
+} from '@/lib/i18n/subdivisions';
+
+describe('i18n subdivisions', () => {
+  it('major countries return populated subdivision lists', () => {
+    expect(subdivisionsForCountry('PL').length).toBeGreaterThanOrEqual(16);
+    expect(subdivisionsForCountry('US').length).toBeGreaterThanOrEqual(50);
+    expect(subdivisionsForCountry('CA').length).toBeGreaterThanOrEqual(13);
+    expect(subdivisionsForCountry('GB').length).toBeGreaterThan(4); // GB has constituent + 200+ admin areas
+    expect(subdivisionsForCountry('AU').length).toBeGreaterThanOrEqual(8);
+  });
+
+  it('returns sorted-by-name results', () => {
+    const us = subdivisionsForCountry('US');
+    const names = us.map((s) => s.name);
+    const sortedCopy = [...names].sort((a, b) => a.localeCompare(b));
+    expect(names).toEqual(sortedCopy);
+  });
+
+  it('hasSubdivisions is true for known countries', () => {
+    expect(hasSubdivisions('US')).toBe(true);
+    expect(hasSubdivisions('PL')).toBe(true);
+    expect(hasSubdivisions('GB')).toBe(true);
+  });
+
+  it('isValidSubdivisionCode accepts known codes and rejects junk', () => {
+    expect(isValidSubdivisionCode('US-CA')).toBe(true);
+    expect(isValidSubdivisionCode('PL-MZ')).toBe(true);
+    expect(isValidSubdivisionCode('US-XX')).toBe(false);
+    expect(isValidSubdivisionCode('GARBAGE')).toBe(false);
+    expect(isValidSubdivisionCode('')).toBe(false);
+  });
+
+  it('getSubdivisionName returns the human name', () => {
+    expect(getSubdivisionName('US-CA')).toMatch(/California/);
+    expect(getSubdivisionName('PL-MZ')).toMatch(/Mazowieckie|Masovian/);
+    expect(getSubdivisionName('AU-NSW')).toMatch(/New South Wales/);
+    // Unknown -> code itself
+    expect(getSubdivisionName('XX-YY')).toBe('XX-YY');
+  });
+});

tests/unit/i18n-timezones.test.ts

@@ -0,0 +1,71 @@
+/**
+ * i18n PR3 — timezone helpers.
+ *
+ * Validates:
+ *  1. Single-zone countries return one IANA string
+ *  2. Multi-zone countries return >1 zones with the most-populous first
+ *  3. primaryTimezoneFor returns the first entry
+ *  4. isMultiZone correctly classifies a sample of single + multi countries
+ *  5. listAllTimezones returns at least our bundled set
+ *  6. formatTimezoneLabel renders an offset for known zones
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  timezonesForCountry,
+  primaryTimezoneFor,
+  isMultiZone,
+  listAllTimezones,
+  formatTimezoneLabel,
+} from '@/lib/i18n/timezones';
+
+describe('i18n timezones', () => {
+  it('single-zone countries map to one IANA zone', () => {
+    expect(timezonesForCountry('PL')).toEqual(['Europe/Warsaw']);
+    expect(timezonesForCountry('GB')).toEqual(['Europe/London']);
+    expect(timezonesForCountry('JP')).toEqual(['Asia/Tokyo']);
+    expect(timezonesForCountry('AE')).toEqual(['Asia/Dubai']);
+  });
+
+  it('multi-zone countries return ordered lists with the primary first', () => {
+    const us = timezonesForCountry('US');
+    expect(us[0]).toBe('America/New_York');
+    expect(us.length).toBeGreaterThan(5);
+    const ru = timezonesForCountry('RU');
+    expect(ru[0]).toBe('Europe/Moscow');
+    expect(ru.length).toBeGreaterThan(5);
+  });
+
+  it('primaryTimezoneFor returns the first entry or null', () => {
+    expect(primaryTimezoneFor('FR')).toBe('Europe/Paris');
+    expect(primaryTimezoneFor('US')).toBe('America/New_York');
+    // 'AQ' is in our map; Antarctica/McMurdo
+    expect(primaryTimezoneFor('AQ')).toBe('Antarctica/McMurdo');
+  });
+
+  it('isMultiZone discriminates correctly', () => {
+    expect(isMultiZone('US')).toBe(true);
+    expect(isMultiZone('RU')).toBe(true);
+    expect(isMultiZone('AU')).toBe(true);
+    expect(isMultiZone('PL')).toBe(false);
+    expect(isMultiZone('JP')).toBe(false);
+  });
+
+  it('listAllTimezones returns at minimum the entries from the country map', () => {
+    const all = listAllTimezones();
+    expect(all.length).toBeGreaterThanOrEqual(200);
+    expect(all).toContain('Europe/Warsaw');
+    expect(all).toContain('America/New_York');
+    expect(all).toContain('Asia/Tokyo');
+  });
+
+  it('formatTimezoneLabel includes an offset for known zones', () => {
+    const label = formatTimezoneLabel('Europe/London');
+    expect(label).toMatch(/Europe\/London/);
+    expect(label).toMatch(/UTC|GMT/);
+  });
+
+  it('formatTimezoneLabel falls back to the bare zone for unknown input', () => {
+    expect(formatTimezoneLabel('Not/A_Zone')).toBe('Not/A_Zone');
+  });
+});