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

<Meta title='@dxtmisha/ru/functional-basic/Classes/Geo - Глобальные Географические Данные'/>

# Класс Geo

Статический служебный класс для централизованного управления географическими данными приложения. Он отвечает за работу с кодами языков (ISO 639-1), стран (ISO 3166-1 alpha-2), временными зонами и локализацией. Класс автоматически определяет настройки окружения и обеспечивает их согласованное использование во всей системе.

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

- **Автоматическое определение** — интеллектуально определяет локаль через хранилище или настройки окружения.
- **Персистентность** — использует `DataStorage` для сохранения и восстановления предпочтений пользователя.
- **Интеграция с медиа-базой** — предоставляет доступ к базе данных стран и языков из библиотеки `@dxtmisha/media`.
- **Глобальное управление временем** — централизованная установка и получение смещения часового пояса.
- **Статический доступ** — удобный глобальный интерфейс без необходимости ручного создания экземпляров.

## Базовое использование

Поскольку класс статический, его методы можно вызывать напрямую.

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

// Получаем текущий код языка
console.log(Geo.getLanguage()) // например, 'ru'

// Устанавливаем новую локаль и сохраняем её
Geo.set('en-US', true)

// Получаем форматированную временную зону
console.log(Geo.getTimezoneFormat()) // например, '+03:00'
```

## Методы

### Общая информация

- `get(): GeoItemFull` — Возвращает полный объект данных о текущей стране и языке.
- `getCountry(): string` — Возвращает 2-буквенный код текущей страны (в верхнем регистре).
- `getLanguage(): string` — Возвращает 2-буквенный код текущего языка (в нижнем регистре).
- `getStandard(): string` — Возвращает комбинированную строку локали (например, `'ru-RU'`).
- `getFirstDay(): string` — Возвращает код первого дня недели для текущей локали (`'Mo'`, `'Su'` и т.д.).
- `getLocation(): string` — Возвращает текущую установленную локаль в виде строки.
- `getItem(): GeoItemFull` — Возвращает копию объекта текущих настроек с учетом языка.
- `getTimezone(): number` — Возвращает смещение часового пояса в минутах.
- `getTimezoneFormat(): string` — Возвращает смещение часового пояса в строковом формате (например, `'+03:00'`).

### Списки и поиск

- `getList(): GeoItem[]` — Возвращает полный список доступных стран и языков из медиа-базы.
- `getByCode(code?: string): GeoItemFull` — Ищет данные по коду языка или страны (с поддержкой фоллбэков).
- `getByCodeFull(code: string): GeoItem | undefined` — Ищет точное совпадение по полному коду локали (язык-страна).
- `getByCountry(country: string): GeoItem | undefined` — Ищет данные по коду или альтернативному названию страны.
- `getByLanguage(language: string): GeoItem | undefined` — Ищет данные по коду языка.
- `find(code: string): GeoItemFull` — Алиас для метода `getByCode`.

### Изменение данных (Сеттеры)

- `set(code: string, save?: boolean): void` — Глобально устанавливает текущую локаль. Если `save` равен `true`, сохраняет выбор в `localStorage`.
- `setTimezone(timezone: number): void` — Устанавливает кастомное смещение часового пояса в минутах.

### Утилиты

- `toStandard(item: GeoItem): string` — Статический метод для формирования стандартной строки `'язык-страна'` из объекта `GeoItem`.

## Примеры

### Ручная установка локали при запуске приложения
```javascript
import { Geo } from '@dxtmisha/functional-basic'

// Предположим, мы получили настройки пользователя из API
const userLocale = 'vi-VN'

Geo.set(userLocale)
console.log(Geo.getCountry()) // 'VN'
```

### Работа с временными зонами
```javascript
// Установка смещения для Токио (UTC+9)
Geo.setTimezone(-540) // смещение в минутах (9 * 60)

console.log(Geo.getTimezoneFormat()) // '+09:00'
```

### Получение списка стран для селектора
```javascript
const countries = Geo.getList().map(item => ({
  value: item.country,
  label: `${item.language.toUpperCase()} - ${item.country}`
}))
```
