<!-- source-hash: 2a8a74c3b98ef6150c8b43768d8c2035 -->
Utility module for working with international phone numbers and country data, combining `libphonenumber-js` metadata with the `Intl.DisplayNames` API to provide country selection, validation, and formatting helpers.

## Key Components

| Export | Type | Description |
|--------|------|-------------|
| `CountryPhoneData` | Interface | Shape of a country entry: ISO code, display name, dial code, and flag emoji |
| `getCountryPhoneData()` | Function | Returns all countries split into `priority` (US, CA, GB, AU) and `others` (alphabetically sorted), lazily cached |
| `getCountryByCode(code)` | Function | Looks up a single `CountryPhoneData` entry by ISO 3166-1 alpha-2 code |
| `validatePhoneNumber(phone, code)` | Function | Returns `true` if the number is valid for the given country (empty strings pass as optional) |
| `formatPhoneE164(phone, code)` | Function | Formats a number to E.164 (e.g., `+14155552671`), falling back to digit-only concatenation on parse failure |

## Usage Example

```typescript
import {
  getCountryPhoneData,
  getCountryByCode,
  validatePhoneNumber,
  formatPhoneE164,
} from './country-phone-utils'

// Populate a country selector
const { priority, others } = getCountryPhoneData()
// priority → [{ code: 'US', name: 'United States', dialCode: '+1', flag: '🇺🇸' }, ...]

// Look up a specific country
const canada = getCountryByCode('CA')
// → { code: 'CA', name: 'Canada', dialCode: '+1', flag: '🇨🇦' }

// Validate user input
const isValid = validatePhoneNumber('(415) 555-2671', 'US') // true

// Normalize to E.164 before storing/sending
const e164 = formatPhoneE164('(415) 555-2671', 'US') // '+14155552671'
```

> **Note:** `getCountryPhoneData()` builds and caches the full country list on first call. Priority countries (US, CA, GB, AU) are always surfaced at the top of the list, making them convenient as default options in phone-number input components.