S280 Handoff: International UxPhoneInputComponent

Executive summary

1. UxPhoneInputComponent (selector: ux-phone-input) is the only shared UI surface for collecting phone numbers for SMS/WhatsApp flows. It still assumes US (+1) and 10-digit national input in practice, which blocks non-US users across login, password reset, and admin phone verification.
2. The platform contract upstream and downstream is unchanged: E.164 strings (+ + country calling code + national digits). API validation already matches ^\+[1-9]\d{6,14}$ in shared DTOs; the gap is UI + normalization, not the wire format.
3. The smart move is to implement country metadata + variable length + paste/intl parsing in the ui-forms library, keep ControlValueAccessor output identical (E.164), and optionally align ValidationUtils.normalizePhoneToE164 so server- and client-side normalization do not diverge.

Why this matters (impact map)

Confidence: Certain for E.164 contract (DTOs + services); likely for Twilio coverage per country (product/ops).

System contract (do not break)

flowchart LR
  subgraph ui["Browser"]
    UX[UxPhoneInputComponent]
  end
  subgraph api["backend-api"]
    DTO["PhoneAuthRequestDto / PhoneAuthVerifyDto\n@IsMatches E.164"]
    ADM["Admin phone verify\n(normalize + uniqueness)"]
  end
  UX -->|"string: +cc…"| DTO
  UX -->|"string: +cc…"| ADM

• Output: onChange / model value must remain a single string, E.164, matching existing validators (e.g. ^\+[1-9]\d{6,14}$).
• Input: writeValue may receive stored E.164 from API — component must round-trip (display national part + correct country).
• Selector: ux-phone-input — unchanged.
• Public inputs: [countryCode] today means “default ITU-T calling code digits without +” (e.g. '1'). After work, it should mean “initial selected country calling code” when no value is set — backward compatible for callers that pass '1'.

Related code (read before coding):

• Component: libs/libs-ui-core/ui-forms/src/lib/phone-input/phone-input.component.ts
• Shared normalization (US-centric): libs/core/utilities/src/lib/validation/validation-utils.ts — ValidationUtils.normalizePhoneToE164
• DTOs: libs/libs-api/api-contracts/src/lib/auth/auth.dto.ts — PhoneAuthRequestDto, PhoneAuthVerifyDto

Current implementation snapshot

Consumers (verify after changes):

Run a quick ripgrep before shipping: ux-phone-input / UxPhoneInputComponent.

Requirements (ranked)

P0 — Must ship

1. Country selection — User can choose calling country (ITU-T country calling code), not only +1.
2. Variable national length — Do not hard-cap at 10 digits; length depends on selected country (and sometimes number type — see P1).
3. Default country — If parent does not bind [countryCode], infer a sensible default from navigator.language / Intl locale (e.g. es-MX → Mexico). Document fallback ('1' or '44') when ambiguous.
4. E.164 emission — On blur/commit (and when pasting full international number), emit one normalized E.164 string; ngModel / formControl unchanged semantically.
5. Paste / typed international — Pasting +44 7911 123456 or 0049… should select correct country and fill national digits when unambiguous.
6. Searchable country list — Filter by country name, ISO 3166-1 alpha-2, and calling code (keyboard and screen-reader friendly).
7. Accessibility — Combobox or listbox pattern: label, aria-expanded, active option, no “flags only” without text.

P1 — Strongly recommended

• Validation: Prefer libphonenumber-js (e.g. parsePhoneNumberFromString + format('E.164')) for validity and leading zero rules (IT, etc.). Tree-shake max or min build per bundle budget.
• As-you-type formatting — Optional display mask per region without changing emitted model until blur (reduces user error).
• Theme — Optional @Input() variant: 'dark' | 'light' | 'inherit' or CSS variables so admin does not need a wrapper hack.

P2 — Nice to have

• Favorites — Pin last-used countries in dropdown.
• Geo-IP hint — Only as a default suggestion, never as security signal.

Out of scope (explicit)

• Replacing Twilio or changing OTP semantics.
• intl-tel-input / jQuery stacks (weight, imperative DOM).
• Changing REST paths or DTO field names.

Design decisions (tradeoff matrix)

Recommendation: Option A — country list can stay a static curated JSON (top N countries + “rest” fallback), validation via libphonenumber-js.

Suggested file layout (library)

libs/libs-ui-core/ui-forms/src/lib/phone-input/
├── phone-input.component.ts       # CVA + template
├── phone-input.component.scss     # move inline styles; support variants
├── country-codes.ts               # ISO2, name, dialCode, priority, optional region
├── phone-country-picker.component.ts  # optional: searchable overlay (same bundle)
└── phone-parse.ts                 # paste + E.164 parse helpers (unit-test heavy)

Export new symbols only from libs/libs-ui-core/ui-forms/src/index.ts if consumers need the picker; otherwise keep private to the module.

Alignment with ValidationUtils

Today ValidationUtils.normalizePhoneToE164 is US-centric (10 digits → +{defaultCountryCode}). After international input ships:

• Either delegate to the same parsing helper used by ux-phone-input, or
• Document that UI is authoritative and utilities are legacy for non-phone flows only.

Avoid two conflicting definitions of “normalized phone” in the monorepo.

Edge cases (minimum test matrix)

Verification checklist (before merge)

• nx / CI: libs-ui-core/ui-forms builds; apps that bundle auth-ui / gograb-space / gograb-admin compile.
• Manual: Login (phone channel), Forgot password (SMS/WhatsApp), Admin user phone request + verify still hit API with E.164.
• Screen reader: country control announces name + dial code.
• Bundle diff: compare main chunk size vs main branch (document delta in PR).

Rollout / risk

Definition of done

1. Non-US users can complete phone-based flows where Twilio supports the destination and the number is valid E.164.
2. No change required in consumer templates unless we intentionally add optional inputs (e.g. variant) — default path should just work.
3. Unit tests cover parse, paste, writeValue round-trip for at least 5 countries on three continents.
4. This document’s P0 list is satisfied or explicitly deferred with a linked issue.

References

• Session context: S280 (2FA, password reset, admin phone verification).
• API shape: libs/libs-api/api-contracts — phone auth DTOs.
• Module path: @libs-ui-core/ui-forms (see repo tsconfig paths; do not edit tsconfig.base.json paths by hand — follow docs/english/Rules/tsconfig-module-paths.md).

Appendix: locale → default country (algorithm sketch)

1. Read navigator.language (e.g. en-GB).
2. Map region subtag (GB) → calling code via static map (GB → 44). If only language (en) with no region, do not guess US — fall back to configured default (product decision: often 1 for current user base).
3. If [countryCode] is set by parent, it wins over locale.

Document the fallback in component JSDoc so future agents do not “fix” it incorrectly.