# FlagPicker Quick Reference Card

## Basic Usage

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

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

## API

### Constructor Options

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `container` | `string\|Element` | ✅ | - | Container selector or element |
| `value` | `string\|null` | ❌ | `null` | Initial flag code (e.g., 'US') |
| `onChange` | `Function` | ❌ | `null` | Callback: `(code) => {}` |
| `placeholder` | `string` | ❌ | `'Search...'` | Search placeholder |
| `disabled` | `boolean` | ❌ | `false` | Initial disabled state |
| `popularFlags` | `Array<string>` | ❌ | `[16 defaults]` | Popular flag codes |

### Methods

```javascript
// Get selected code
picker.getValue()                    // Returns: 'US' or null

// Set code
picker.setValue('FR')                // Set France
picker.setValue(null)                // Clear selection

// State control
picker.disable()                     // Disable interaction
picker.enable()                      // Enable interaction

// Cleanup
picker.destroy()                     // Remove from DOM
```

## Regions

- **Popular** (16): US, GB, ES, FR, DE, IT, PT, BR, RU, CN, JP, KR, IN, MX, CA, AU
- **All** (249): All countries
- **Africa** (54): DZ, AO, BJ, BW, BF, BI, CM, CV, CF, TD, KM, CG, CD, CI, DJ, EG, GQ, ER, ET, GA, GM, GH, GN, GW, KE, LS, LR, LY, MG, MW, ML, MR, MU, YT, MA, MZ, NA, NE, NG, RE, RW, SH, ST, SN, SC, SL, SO, ZA, SS, SD, SZ, TZ, TG, TN, UG, EH, ZM, ZW
- **Americas** (35): AI, AG, AR, AW, BS, BB, BZ, BM, BO, BQ, BR, CA, KY, CL, CO, CR, CU, CW, DM, DO, EC, SV, FK, GF, GL, GD, GP, GT, GY, HT, HN, JM, MQ, MX, MS, NI, PA, PY, PE, PR, BL, KN, LC, MF, PM, VC, SR, TT, TC, US, UY, VE, VG, VI
- **Asia** (48): AF, AM, AZ, BH, BD, BT, BN, KH, CN, CX, CC, GE, HK, IN, ID, IR, IQ, IL, JP, JO, KZ, KP, KR, KW, KG, LA, LB, MO, MY, MV, MN, MM, NP, OM, PK, PS, PH, QA, SA, SG, LK, SY, TW, TJ, TH, TL, TR, TM, AE, UZ, VN, YE
- **Europe** (44): AX, AL, AD, AT, BY, BE, BA, BG, HR, CY, CZ, DK, EE, FO, FI, FR, DE, GI, GR, GG, HU, IS, IE, IM, IT, JE, XK, LV, LI, LT, LU, MK, MT, MD, MC, ME, NL, NO, PL, PT, RO, RU, SM, RS, SK, SI, ES, SJ, SE, CH, UA, GB, VA
- **Oceania** (32+): AS, AQ, AU, BV, IO, CK, FJ, PF, TF, GU, HM, KI, MH, FM, NR, NC, NZ, NU, NF, MP, PW, PG, PN, WS, SB, GS, TK, TO, TV, UM, VU, WF

## Keyboard Shortcuts

| Key | Action |
|-----|--------|
| ↓ | Move focus down (8 flags) |
| ↑ | Move focus up (8 flags) |
| → | Move focus right (1 flag) |
| ← | Move focus left (1 flag) |
| Home | Jump to first flag |
| End | Jump to last flag |
| Enter / Space | Select focused flag |
| Tab | Navigate elements |

## Search Tips

```
"united"     → United States, United Kingdom, UAE
"fr"         → France, French Guiana, French Polynesia
"island"     → Christmas Island, Falkland Islands, etc.
"ko"         → Korea (North), Korea (South), Kosovo
```

## Common Patterns

### With Form

```javascript
const picker = new FlagPicker({
    container: '#flag-picker',
    value: form.flag_code.value,
    onChange: (code) => {
        form.flag_code.value = code;
    }
});
```

### With Language Manager

```javascript
const picker = new FlagPicker({
    container: '#flag-picker',
    value: language.getFlagCode(),
    onChange: async (code) => {
        await languageManager.updateLanguage(id, { flag_code: code });
    }
});
```

### Dynamic Enable/Disable

```javascript
checkbox.addEventListener('change', (e) => {
    e.target.checked ? picker.enable() : picker.disable();
});
```

### Custom Popular Flags

```javascript
// European languages
new FlagPicker({
    container: '#picker',
    popularFlags: ['DE', 'FR', 'IT', 'ES', 'PT', 'NL', 'BE', 'AT']
});

// Asian languages
new FlagPicker({
    container: '#picker',
    popularFlags: ['CN', 'JP', 'KR', 'IN', 'ID', 'TH', 'VN', 'MY']
});
```

## Styling

### CSS Classes

```scss
.mpz-flag-picker                    // Main container
.mpz-flag-picker--disabled          // Disabled state
.mpz-flag-picker__header            // Header (search + preview)
.mpz-flag-picker__search            // Search input
.mpz-flag-picker__preview           // Selected flag preview
.mpz-flag-picker__preview--empty    // Empty preview
.mpz-flag-picker__tabs              // Region tabs
.mpz-flag-picker__tab               // Individual tab
.mpz-flag-picker__tab--active       // Active tab
.mpz-flag-picker__grid              // Flag grid
.mpz-flag-picker__flag              // Individual flag
.mpz-flag-picker__flag--selected    // Selected flag
.mpz-flag-picker__flag--text        // Text fallback
.mpz-flag-picker__flag-img          // Flag image
.mpz-flag-picker__empty             // Empty state
```

### Dark Mode

```scss
body.dark-mode {
    .mpz-flag-picker {
        background: #2c2c2c;
        border-color: #3c3c3c;
    }
}
```

### Custom Colors

```scss
// Override variables before import
$primary-color: #0073aa;
$flag-size: 48px;
$border-radius-md: 6px;

@import 'components/flag-picker';
```

## Validation

```javascript
// Valid codes (2 letters, uppercase)
'US'  ✅   'GB'  ✅   'FR'  ✅

// Invalid codes
'USA' ❌   'uk'  ❌   'XYZ' ❌

// The component auto-normalizes to uppercase
picker.setValue('us');  // Becomes 'US'
```

## CDN Flags

**Source**: CircleFlags (MIT License)

**URL**: `https://hatscripts.github.io/circle-flags/flags/{code}.svg`

**Format**: SVG (scalable)

**Fallback**: Country code text

### Use Local Flags

```javascript
// Edit createFlagElement() in FlagPicker.js
const flagUrl = `/path/to/flags/${code.toLowerCase()}.svg`;
```

## Browser Support

✅ Chrome 90+
✅ Firefox 88+
✅ Safari 14+
✅ Edge 90+
✅ Mobile (iOS 14+, Android Chrome 90+)

## Accessibility

✅ Keyboard navigation
✅ Screen reader support (ARIA)
✅ Focus indicators
✅ Color contrast AA
✅ Reduced motion support

## Files

```
admin/
├── src/components/FlagPicker.js         # Component (789 lines)
├── src/styles/components/_flag-picker.scss  # Styles (520+ lines)
├── examples/flag-picker-demo.html       # Demo (340 lines)
└── tests/flag-picker.test.js            # Tests (290 lines)
```

## Import

```javascript
// ES6 Module
import FlagPicker from './components/FlagPicker.js';

// With data
import FlagPicker, { COUNTRY_DATA, POPULAR_FLAGS } from './components/FlagPicker.js';
```

## Debugging

```javascript
// Log current state
console.log({
    value: picker.getValue(),
    region: picker.currentRegion,
    search: picker.searchQuery,
    filtered: picker.filteredFlags.length,
    disabled: picker.options.disabled
});

// Check if code is valid
const isValid = !!COUNTRY_DATA[code];

// Get country name
const name = COUNTRY_DATA[code]?.name;

// Get country region
const region = COUNTRY_DATA[code]?.region;
```

## Troubleshooting

### Flags not loading
- Check internet connection
- Verify CDN not blocked
- Check browser console for errors
- Try local flags

### Search not working
- Check debounce is imported
- Verify no JS errors
- Clear browser cache

### Layout broken
- Check parent width
- Verify SCSS compiled
- Check for CSS conflicts

## License

GPL v2 or later (WordPress)

CircleFlags: MIT License

---

**Version**: 1.0.0 | **Date**: 2026-01-26 | **Component**: FlagPicker