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

<Meta title='@dxtmisha/ru/functional/Classes/GeoFlagRef - Реактивное управление флагами стран'/>

# Класс GeoFlagRef

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

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

- **Реактивность** — автоматическое обновление данных при изменении кода страны.
- **Поддержка списка стран** — получение информации о нескольких странах одновременно.
- **Национальные названия** — получение названий стран на их родном языке.

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

Создает новый экземпляр `GeoFlagRef` для работы с флагами стран. Класс является реактивной оберткой над `GeoFlag` и автоматически обновляет данные при изменении переданного кода страны.

**Параметры:**
- `code: RefOrNormal<string>` — код страны (например, `'RU'`, `'US'`). Может быть обычной строкой или реактивным объектом `ref`. По умолчанию используется текущее местоположение через `Geo.getLocation()`.

```typescript
import { GeoFlagRef } from '@dxtmisha/functional'
import { ref } from 'vue'

// 1. Инициализация с реактивным кодом
const code = ref('RU')
const geoFlag = new GeoFlagRef(code)

// 2. Использование данных флага
const flagIcon = geoFlag.getFlag() // ComputedRef с иконкой для 'RU'

// 3. Автоматическое обновление
code.value = 'US' // flagIcon обновится автоматически
```

## Текущее состояние

- `getCode(): Ref<string>` — Возвращает реактивную ссылку на текущий установленный код страны.

## Получение данных

Все методы получения данных возвращают `ComputedRef`, что обеспечивает автоматическую синхронизацию с текущим кодом страны.

- `get(code?: string): ComputedRef<GeoFlagItem | undefined>` — Возвращает полную информацию о стране: название, иконку и другие метаданные. Если `code` не передан, используется текущий код из состояния.
- `getFlag(code?: string): ComputedRef<string | undefined>` — Возвращает путь или идентификатор иконки флага для указанной страны.
- `getList(codes?: string[]): ComputedRef<GeoFlagItem[]>` — Возвращает массив данных о флагах для списка кодов.
- `getNational(codes?: string[]): ComputedRef<GeoFlagNational[]>` — Возвращает список стран с названиями на их национальных языках.

## Работа со списками: getList vs getNational

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

### `getList` (Локальный список)
Возвращает список стран, где все названия и метки переведены на язык **текущего экземпляра** `GeoFlagRef`.
- **Когда использовать:** если вам нужно отобразить список стран в интерфейсе на языке пользователя (например, в селекторе выбора страны).
- **Результат:** если `GeoFlagRef` настроен на русский (`RU`), то для кода `US` вы получите "Соединённые Штаты".

### `getNational` (Национальный список)
Возвращает список, где информация о каждой стране представлена на её **родном (национальном) языке**.
- **Когда использовать:** если вам нужно показать названия стран так, как их называют жители этих стран, или добавить описание на родном языке.
- **Результат:** для кода `US` вы получите "United States" (на английском), для `VN` — "Việt Nam" (на вьетнамском), независимо от того, какой язык установлен в `GeoFlagRef`.

## Типы

### GeoFlagItem
Объект с основной информацией о стране и её флаге.
- `language: string` — Название языка.
- `country: string` — Название страны.
- `standard: string` — Стандартный код локали.
- `icon?: string` — Идентификатор иконки флага.
- `label: string` — Отображаемая метка (обычно название страны).
- `value: string` — Значение для выбора (обычно код страны).

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