# FlagPicker Component

> A comprehensive country flag picker supporting all 249 ISO 3166-1 alpha-2 codes

## Quick Start

```javascript
import FlagPicker from './FlagPicker.js';

const picker = new FlagPicker({
    container: '#flag-picker',
    value: 'US',
    onChange: (code) => console.log('Selected:', code)
});
```

## Features

- **249 Countries**: Complete ISO 3166-1 alpha-2 coverage
- **Regional Filtering**: Browse by continent (Popular, All, Africa, Americas, Asia, Europe, Oceania)
- **Search**: Real-time search by country name or code
- **Keyboard Navigation**: Full keyboard accessibility
- **Preview**: Live preview of selected flag
- **Dark Mode**: Automatic dark mode support
- **Responsive**: Mobile-friendly grid layout
- **Accessible**: WCAG 2.1 AA compliant

## API

```javascript
new FlagPicker({
    container: '#my-container',     // Required: CSS selector or element
    value: 'US',                    // Optional: Initial flag code
    onChange: (code) => {},         // Optional: Selection callback
    placeholder: 'Search...',       // Optional: Search placeholder
    disabled: false,                // Optional: Disabled state
    popularFlags: ['US', 'GB'...]   // Optional: Custom popular flags
})
```

### Methods

```javascript
picker.getValue()           // Get selected code
picker.setValue('FR')       // Set code
picker.disable()            // Disable picker
picker.enable()             // Enable picker
picker.destroy()            // Remove from DOM
```

## Documentation

- **Full Documentation**: See `FlagPicker.md` for complete API reference
- **Quick Reference**: See `FLAGPICKER-QUICK-REFERENCE.md` for developer quick reference
- **Implementation Guide**: See `FLAGPICKER-IMPLEMENTATION.md` for detailed implementation docs
- **Live Demo**: Open `examples/flag-picker-demo.html` in a browser

## Validation

All 249 country codes match `LanguageManager::VALID_COUNTRY_CODES` exactly.

Run verification:
```bash
./scripts/verify-flag-codes.sh
```

## Testing

Run unit tests:
```bash
npm test -- flag-picker.test.js
```

## Compatibility

- **Backend**: Matches LanguageManager validation (100% compatibility)
- **Browsers**: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
- **Mobile**: iOS 14+, Android Chrome 90+

## License

GPL v2 or later (WordPress standard)

Flag icons: CircleFlags (MIT License)

---

**Version**: 1.0.0 | **Author**: Claude Sonnet 4.5 | **Date**: 2026-01-26