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

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

# Класс GeoFlag

Класс для работы с флагами стран, предоставляющий методы для получения информации о флагах, странах и языках на основе географических кодов. Интегрируется с системой геолокации и поддерживает локализованные названия стран и языков.

## Основные возможности

- **Полная база флагов** — содержит флаги для всех стран мира (200+ стран)
- **Локализованные названия** — получение названий стран и языков на текущем языке
- **Национальные названия** — получение названий на языке самой страны
- **Гибкие списки** — создание списков флагов по определённым критериям
- **Интеграция с Geo** — использует географическую систему для получения данных
- **Типобезопасность** — полная поддержка TypeScript с типизированными интерфейсами
- **Иконочная система** — предоставляет имена иконок для флагов

## Константы

### `GEO_FLAG_ICON_NAME`

Базовое имя для иконок флагов.

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

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

## Статические свойства

### `flags`

Статический объект, содержащий соответствие кодов стран именам иконок флагов.

```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'

// Получение всех доступных кодов стран
const countryCodes = Object.keys(GeoFlag.flags)
console.log(countryCodes.length) // 200+ стран
```

## Конструктор

### `constructor`

Создаёт экземпляр GeoFlag с указанным кодом локали.

**Параметры:**
- `code?: string` — код страны и языка (по умолчанию из Geo.getLocation())

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

// Создание с текущей локалью
const geoFlag = new GeoFlag()

// Создание с определённой локалью
const ruFlag = new GeoFlag('ru-RU')
const usFlag = new GeoFlag('en-US')
const deFlag = new GeoFlag('de-DE')
```

## Методы экземпляра

### `get`

Возвращает информацию о стране и её флаге.

**Параметры:**
- `code?: string` — код страны (опционально, по умолчанию используется код экземпляра)

**Возвращает:** `GeoFlagItem | undefined` — объект с информацией о флаге или undefined

```javascript
const geoFlag = new GeoFlag('ru-RU')

// Получение информации о России
const russiaInfo = geoFlag.get('RU')
console.log(russiaInfo)
// {
//   language: 'русский',
//   country: 'Россия',
//   standard: 'ru-RU',
//   icon: '@flag-ru',
//   label: 'Россия',
//   value: 'RU'
// }

// Получение информации о США на русском языке
const usaInfo = geoFlag.get('US')
console.log(usaInfo)
// {
//   language: 'английский',
//   country: 'Соединённые Штаты',
//   standard: 'en-US',
//   icon: '@flag-us',
//   label: 'Соединённые Штаты',
//   value: 'US'
// }

// Получение информации о текущей локали
const currentInfo = geoFlag.get()
console.log(currentInfo?.country) // Название страны на текущем языке
```

### `getFlag`

Получение ссылки на иконку флага.

**Параметры:**
- `code?: string` — код страны (опционально)

**Возвращает:** `string | undefined` — имя иконки флага или undefined

```javascript
const geoFlag = new GeoFlag()

// Получение иконки флага России
const russiaFlag = geoFlag.getFlag('RU')
console.log(russiaFlag) // '@flag-ru'

// Получение иконки флага Германии
const germanyFlag = geoFlag.getFlag('DE')
console.log(germanyFlag) // '@flag-de'

// Получение флага для несуществующей страны
const unknownFlag = geoFlag.getFlag('XX')
console.log(unknownFlag) // undefined
```

### `getList`

Получение списка стран по массиву кодов.

**Параметры:**
- `codes?: string[]` — массив кодов стран (опционально, по умолчанию все страны)

**Возвращает:** `GeoFlagItem[]` — массив объектов с информацией о флагах

```javascript
const geoFlag = new GeoFlag('ru-RU')

// Получение списка европейских стран
const europeanCountries = geoFlag.getList(['RU', 'DE', 'FR', 'IT', 'ES'])
console.log(europeanCountries)
// [
//   { language: 'русский', country: 'Россия', icon: '@flag-ru', ... },
//   { language: 'немецкий', country: 'Германия', icon: '@flag-de', ... },
//   { language: 'французский', country: 'Франция', icon: '@flag-fr', ... },
//   ...
// ]

// Получение всех доступных стран
const allCountries = geoFlag.getList()
console.log(allCountries.length) // 200+ стран

// Получение стран СНГ
const cisCountries = geoFlag.getList(['RU', 'BY', 'KZ', 'UA', 'UZ', 'KG', 'TJ', 'AM', 'AZ', 'GE', 'MD'])
```

### `getNational`

Получение списка стран с названиями на национальных языках.

**Параметры:**
- `codes?: string[]` — массив кодов стран (опционально)

**Возвращает:** `GeoFlagNational[]` — массив объектов с национальными названиями

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

// Получение списка с национальными названиями
const nationalNames = geoFlag.getNational(['RU', 'DE', 'FR', 'JP'])
console.log(nationalNames)
// [
//   {
//     language: 'Russian',           // на английском (текущий язык)
//     country: 'Russia',             // на английском (текущий язык)
//     standard: 'ru-RU',
//     icon: '@flag-ru',
//     nationalLanguage: 'русский',   // на русском (национальный язык)
//     nationalCountry: 'Россия',     // на русском (национальный язык)
//     description: 'Россия'          // национальное название
//   },
//   {
//     language: 'German',
//     country: 'Germany',
//     standard: 'de-DE',
//     icon: '@flag-de',
//     nationalLanguage: 'Deutsch',
//     nationalCountry: 'Deutschland',
//     description: 'Deutschland'
//   },
//   ...
// ]
```

### `setCode`

Изменение локали экземпляра.

**Параметры:**
- `code: string` — новый код страны и языка

**Возвращает:** `this` — для цепочки вызовов

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

// Получение информации на английском
let info = geoFlag.get('RU')
console.log(info?.country) // 'Russia'

// Смена локали на русскую
geoFlag.setCode('ru-RU')

// Получение той же информации на русском
info = geoFlag.get('RU')
console.log(info?.country) // 'Россия'
```

## Практические примеры

### Компонент выбора страны

```javascript
class CountrySelector {
  constructor(targetElement, options = {}) {
    this.geoFlag = new GeoFlag(options.locale || 'ru-RU')
    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))
    })
  }
}

// Использование
new CountrySelector(document.getElementById('selector'), {
  locale: 'ru-RU',
  onSelect: (country) => console.log('Выбрана:', country.country)
})
```

### Многоязычная информация

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

// Использование
const info = guide.getCountryInfo('DE')
console.log(info['ru-RU'].country) // 'Германия'
console.log(info['en-US'].country) // 'Germany'
```

### Статистика по странам

```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()) // Топ-10 языков
```

Класс GeoFlag предоставляет мощный инструмент для работы с флагами и информацией о странах, поддерживая локализацию, типобезопасность и гибкие возможности для создания международных приложений.
