<!-- source-hash: 8f44dd654f7205b5e41cde63c6ee32dd -->
A composite phone number input component combining a country selector dropdown with a phone number text field, featuring debounced validation using `libphonenumber-js`.

## Key Components

### `PhoneInput` (main export)
A controlled input component that renders a country code selector and phone number field side-by-side.

**Props (`PhoneInputProps`):**

| Prop | Type | Description |
|------|------|-------------|
| `value` | `string` | Current phone number value |
| `countryCode` | `CountryCode` | Selected country (ISO code) |
| `onPhoneChange` | `(phone: string) => void` | Called on phone input change |
| `onCountryChange` | `(country: CountryCode) => void` | Called on country selection |
| `onValidationChange` | `(isInvalid: boolean) => void` | Optional validation state callback |
| `disabled` | `boolean` | Disables both inputs |
| `placeholder` | `string` | Input placeholder text |
| `onKeyDown` | `React.KeyboardEvent handler` | Key event passthrough |

### `CountryOption` (internal)
Renders a single country row inside the dropdown showing flag, dial code, and country name.

### Validation Behavior
- Input is restricted to digits, spaces, hyphens, and parentheses
- Validation triggers via debounce (300ms) after 4+ digits are entered
- Immediate validation fires on input blur
- Empty input clears any invalid state without triggering validation

## Usage Example

```typescript
import { PhoneInput } from './phone-input'
import { useState } from 'react'
import type { CountryCode } from 'libphonenumber-js'

function ContactForm() {
  const [phone, setPhone] = useState('')
  const [country, setCountry] = useState<CountryCode>('US')
  const [hasError, setHasError] = useState(false)

  return (
    <PhoneInput
      value={phone}
      countryCode={country}
      onPhoneChange={setPhone}
      onCountryChange={setCountry}
      onValidationChange={setHasError}
      placeholder="Phone Number (optional)"
    />
  )
}
```