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

<Meta title='@dxtmisha/ru/functional-basic/Classes/GeoFlag - Флаги Стран'/>

# Класс GeoFlag

Класс для работы с флагами стран и географической информацией. Он предоставляет удобный интерфейс для получения иконок флагов, локализованных названий стран и языков. Использует синглтоны `Geo` и `GeoIntl` для корректного разрешения данных в зависимости от текущей локали.

## Ключевые особенности

- **Словарь флагов** — встроенный статический список `flags`, связывающий коды ISO 3166-1 alpha-2 с именами иконок.
- **Локализованные данные** — автоматический перевод названий стран и языков на язык текущего интерфейса.
- **Национальная поддержка** — возможность получения названий стран на их «родном» языке (например, «Япония» и «日本» одновременно).
- **Масштабируемость** — поддержка фильтрации и получения полных списков для селекторов стран.

## Инициализация

Для создания экземпляра используйте конструктор `GeoFlag(code)`.

**Параметры:**
- `code?: string` — код страны или локали (например, `'RU'`, `'en-US'`). Если не указан, используется текущая локаль из системы `Geo`.

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

// С текущей локалью
const flag = new GeoFlag()

// Для конкретной страны
const ruFlag = new GeoFlag('ru-RU')
```

## Методы

### Получение данных
- `get(code?: string): GeoFlagItem | undefined` — Возвращает полный объект данных о стране.
- `getFlag(code?: string): string | undefined` — Возвращает только идентификатор иконки флага (например, `'f-ru'`).

### Списки
- `getList(codes?: string[]): GeoFlagItem[]` — Возвращает массив данных о странах.
- `getNational(codes?: string[]): GeoFlagNational[]` — Возвращает список стран с национальными названиями.

### Настройка
- `setCode(code: string): this` — Изменяет базовую локаль для текущего экземпляра.

## Методы работы со списками

Основное различие между методами заключается в языке, на котором возвращаются названия стран и языков:

*   **`getList`** — возвращает названия только на том языке, который установлен в экземпляре класса (например, всё на русском).
*   **`getNational`** — возвращает названия на языке вашего интерфейса + добавляет оригинальные названия на языке самой страны (например, «Япония» и «日本»).

### Пример разницы в результате:

```javascript
const geo = new GeoFlag('ru-RU') // Установлен русский язык

// 1. getList возвращает только перевод
const list = geo.getList(['JP']) 
/* 
[{ country: 'Япония', ... }] 
*/

// 2. getNational возвращает перевод + оригинальное название
const national = geo.getNational(['JP']) 
/* 
[{ 
  country: 'Япония', 
  nationalCountry: '日本', 
  ... 
}] 
*/
```

## Типы

### `GeoFlagItem`
Базовый объект информации о флаге.
- `country`: string — Локализованное название страны.
- `language`: string — Локализованное название языка.
- `standard`: string — Полный стандарт локали (например, `ru-RU`).
- `icon`: string — Имя иконки флага (префикс `f-`).
- `label`: string — Метка для отображения (по умолчанию совпадает с `country`).
- `value`: string — Код страны (ISO alpha-2).

### `GeoFlagNational`
Расширяет `GeoFlagItem` дополнительными полями:
- `nationalCountry`: string — Название страны на её родном языке.
- `nationalLanguage`: string — Название языка на родном языке.
- `description`: string — Краткое описание (дублирует `nationalCountry`).

## Примеры

### Список популярных стран с национальными именами
```javascript
const geo = new GeoFlag('ru-RU')
const list = geo.getNational(['RU', 'CN', 'JP'])

/* 
Результат:
[
  { 
    country: 'Россия', 
    nationalCountry: 'Россия', 
    icon: 'f-ru', 
    ... 
  },
  { 
    country: 'Китай', 
    nationalCountry: '中国', 
    icon: 'f-cn', 
    ... 
  },
  { 
    country: 'Япония', 
    nationalCountry: '日本', 
    icon: 'f-jp', 
    ... 
  }
]
*/
```
