import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/functional/en/Classes/GeoFlag'/>

# GeoFlag Class

A class for working with country flags, providing methods to retrieve information about flags, countries, and languages based on geographic codes. Integrates with the geolocation system and supports localized country and language names.

## Key Features

- **Complete flag database** — contains flags for all countries worldwide (200+ countries)
- **Localized names** — retrieves country and language names in the current language
- **National names** — gets names in the country's own language
- **Flexible lists** — creates flag lists based on specific criteria
- **Geo integration** — uses the geographic system to retrieve data
- **Type safety** — full TypeScript support with typed interfaces
- **Icon system** — provides icon names for flags

## Constants

### `GEO_FLAG_ICON_NAME`

Base name for flag icons.

```javascript
import { GEO_FLAG_ICON_NAME } from '@dxtmisha/functional'

console.log(GEO_FLAG_ICON_NAME) // '@flag'
```

## Static Properties

### `flags`

Static object containing country code to flag icon name mappings.

```javascript
import { GeoFlag } from '@dxtmisha/functional'

console.log(GeoFlag.flags.RU) // '@flag-ru'
console.log(GeoFlag.flags.US) // '@flag-us'
console.log(GeoFlag.flags.DE) // '@flag-de'

// Get all available country codes
const countryCodes = Object.keys(GeoFlag.flags)
console.log(countryCodes.length) // 200+ countries
```

## Constructor

### `constructor`

Creates a GeoFlag instance with the specified locale code.

**Parameters:**
- `code?: string` — country and language code (defaults to Geo.getLocation())

```javascript
import { GeoFlag } from '@dxtmisha/functional'

// Create with current locale
const geoFlag = new GeoFlag()

// Create with specific locale
const ruFlag = new GeoFlag('ru-RU')
const usFlag = new GeoFlag('en-US')
const deFlag = new GeoFlag('de-DE')
```

## Instance Methods

### `get`

Returns information about the country and its flag.

**Parameters:**
- `code?: string` — country code (optional, defaults to instance code)

**Returns:** `GeoFlagItem | undefined` — object with flag information or undefined

```javascript
const geoFlag = new GeoFlag('en-US')

// Get information about Russia
const russiaInfo = geoFlag.get('RU')
console.log(russiaInfo)
// {
//   language: 'Russian',
//   country: 'Russia',
//   standard: 'ru-RU',
//   icon: '@flag-ru',
//   label: 'Russia',
//   value: 'RU'
// }

// Get information about Germany in English
const germanyInfo = geoFlag.get('DE')
console.log(germanyInfo)
// {
//   language: 'German',
//   country: 'Germany',
//   standard: 'de-DE',
//   icon: '@flag-de',
//   label: 'Germany',
//   value: 'DE'
// }

// Get information about current locale
const currentInfo = geoFlag.get()
console.log(currentInfo?.country) // Country name in current language
```

### `getFlag`

Gets the flag icon reference.

**Parameters:**
- `code?: string` — country code (optional)

**Returns:** `string | undefined` — flag icon name or undefined

```javascript
const geoFlag = new GeoFlag()

// Get Russia flag icon
const russiaFlag = geoFlag.getFlag('RU')
console.log(russiaFlag) // '@flag-ru'

// Get Germany flag icon
const germanyFlag = geoFlag.getFlag('DE')
console.log(germanyFlag) // '@flag-de'

// Get flag for non-existent country
const unknownFlag = geoFlag.getFlag('XX')
console.log(unknownFlag) // undefined
```

### `getList`

Gets a list of countries by array of codes.

**Parameters:**
- `codes?: string[]` — array of country codes (optional, defaults to all countries)

**Returns:** `GeoFlagItem[]` — array of objects with flag information

```javascript
const geoFlag = new GeoFlag('en-US')

// Get list of European countries
const europeanCountries = geoFlag.getList(['RU', 'DE', 'FR', 'IT', 'ES'])
console.log(europeanCountries)
// [
//   { language: 'Russian', country: 'Russia', icon: '@flag-ru', ... },
//   { language: 'German', country: 'Germany', icon: '@flag-de', ... },
//   { language: 'French', country: 'France', icon: '@flag-fr', ... },
//   ...
// ]

// Get all available countries
const allCountries = geoFlag.getList()
console.log(allCountries.length) // 200+ countries

// Get CIS countries
const cisCountries = geoFlag.getList(['RU', 'BY', 'KZ', 'UA', 'UZ', 'KG', 'TJ', 'AM', 'AZ', 'GE', 'MD'])
```

### `getNational`

Gets a list of countries with names in their national languages.

**Parameters:**
- `codes?: string[]` — array of country codes (optional)

**Returns:** `GeoFlagNational[]` — array of objects with national names

```javascript
const geoFlag = new GeoFlag('en-US')

// Get list with national names
const nationalNames = geoFlag.getNational(['RU', 'DE', 'FR', 'JP'])
console.log(nationalNames)
// [
//   {
//     language: 'Russian',           // in English (current language)
//     country: 'Russia',             // in English (current language)
//     standard: 'ru-RU',
//     icon: '@flag-ru',
//     nationalLanguage: 'русский',   // in Russian (national language)
//     nationalCountry: 'Россия',     // in Russian (national language)
//     description: 'Россия'          // national name
//   },
//   {
//     language: 'German',
//     country: 'Germany',
//     standard: 'de-DE',
//     icon: '@flag-de',
//     nationalLanguage: 'Deutsch',
//     nationalCountry: 'Deutschland',
//     description: 'Deutschland'
//   },
//   ...
// ]
```

### `setCode`

Changes the instance locale.

**Parameters:**
- `code: string` — new country and language code

**Returns:** `this` — for method chaining

```javascript
const geoFlag = new GeoFlag('en-US')

// Get information in English
let info = geoFlag.get('RU')
console.log(info?.country) // 'Russia'

// Switch locale to Russian
geoFlag.setCode('ru-RU')

// Get same information in Russian
info = geoFlag.get('RU')
console.log(info?.country) // 'Россия'
```

## Practical Examples

### Country Selector Component

```javascript
class CountrySelector {
  constructor(targetElement, options = {}) {
    this.geoFlag = new GeoFlag(options.locale || 'en-US')
    this.element = targetElement
    this.onSelect = options.onSelect || (() => {})
    this.render()
  }

  render() {
    const countries = this.geoFlag.getList()
    this.element.innerHTML = countries.map(country => `
      <div data-code="${country.value}">${country.country}</div>
    `).join('')

    this.element.addEventListener('click', (e) => {
      const code = e.target.dataset.code
      if (code) this.onSelect(this.geoFlag.get(code))
    })
  }
}

// Usage
new CountrySelector(document.getElementById('selector'), {
  locale: 'en-US',
  onSelect: (country) => console.log('Selected:', country.country)
})
```

### Multilingual Information

```javascript
const guide = {
  getCountryInfo(code) {
    const locales = ['en-US', 'ru-RU', 'de-DE']
    return locales.reduce((acc, locale) => {
      acc[locale] = new GeoFlag(locale).get(code)
      return acc
    }, {})
  }
}

// Usage
const info = guide.getCountryInfo('DE')
console.log(info['en-US'].country) // 'Germany'
console.log(info['ru-RU'].country) // 'Германия'
```

### Country Statistics

```javascript
const stats = {
  getLanguageStats() {
    const countries = new GeoFlag().getList()
    const langStats = {}

    countries.forEach(country => {
      const lang = country.language
      langStats[lang] = (langStats[lang] || 0) + 1
    })

    return Object.entries(langStats)
      .sort(([,a], [,b]) => b - a)
      .slice(0, 10)
  }
}

console.log(stats.getLanguageStats()) // Top 10 languages
```

The GeoFlag class provides a powerful tool for working with flags and country information, supporting localization, type safety, and flexible capabilities for creating international applications.
