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

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

# Класс Geo

Статический класс для работы с географическими данными. Предоставляет методы для определения текущего местоположения, работы с кодами стран и языков, и управления часовыми поясами с автоматическим определением через браузер и кешированием в localStorage.

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

- **Автоматическое определение местоположения** — определяет текущую страну и язык на основе данных браузера
- **Обработка кодов стран и языков** — поддерживает формат `язык-страна` (например, `ru-RU`, `en-US`)
- **Управление часовыми поясами** — получение и установка часовых поясов
- **Кеширование в localStorage** — сохраняет выбранное пользователем местоположение
- **Поддержка альтернативных кодов** — работает с различными вариантами кодов стран и языков
- **Полная база данных стран** — доступ к полному списку стран с их данными
- **Гибкий парсинг кодов** — обрабатывает полные коды, коды стран или языков отдельно

## Методы получения данных

### `get`

Возвращает полную информацию о текущей стране.

**Возвращает:** `GeoItemFull` — объект с полными географическими данными

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

const currentGeo = Geo.get()
console.log(currentGeo)
// {
//   country: 'RU',
//   language: 'ru',
//   standard: 'ru-RU',
//   firstDay: 'Mo',
//   countryAlternative: ['Россия', 'Russia'],
//   languageAlternative: ['русский', 'russian']
// }
```

### `getCountry`

Возвращает код текущей страны.

**Возвращает:** `string` — ISO код страны (например, 'RU', 'US', 'GB')

```javascript
const country = Geo.getCountry()
console.log(country) // 'RU'
```

### `getLanguage`

Возвращает код текущего языка.

**Возвращает:** `string` — ISO код языка (например, 'ru', 'en', 'fr')

```javascript
const language = Geo.getLanguage()
console.log(language) // 'ru'
```

### `getStandard`

Возвращает полный формат согласно стандарту (язык-страна).

**Возвращает:** `string` — стандартный формат локали

```javascript
const standard = Geo.getStandard()
console.log(standard) // 'ru-RU'
```

### `getFirstDay`

Возвращает первый день недели для текущего местоположения.

**Возвращает:** `string` — код первого дня ('Su' для воскресенья, 'Mo' для понедельника)

```javascript
const firstDay = Geo.getFirstDay()
console.log(firstDay) // 'Mo' (Россия/Европа) или 'Su' (США)
```

### `getLocation`

Возвращает полный формат текущего местоположения.

**Возвращает:** `string` — текущее местоположение в формате язык-страна

```javascript
const location = Geo.getLocation()
console.log(location) // 'ru-RU'
```

### `getItem`

Возвращает обработанные данные с включённым текущим языком.

**Возвращает:** `GeoItemFull` — географические данные с актуальным языком

```javascript
const item = Geo.getItem()
console.log(item)
// Включает все данные плюс актуальный язык из браузера/настроек
```

### `getList`

Возвращает полный список доступных стран.

**Возвращает:** `GeoItem[]` — массив всех поддерживаемых стран

```javascript
const allCountries = Geo.getList()
console.log(allCountries.length) // 200+ стран
console.log(allCountries[0])
// { country: 'AD', language: 'ca', standard: 'ca-AD', firstDay: 'Mo', ... }
```

## Методы поиска данных

### `getByCode`

Возвращает данные страны по её коду (полному, стране или языку).

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

**Возвращает:** `GeoItemFull` — географические данные для указанного кода

```javascript
// Полный код
const dataFull = Geo.getByCode('ru-RU')
console.log(dataFull.country) // 'RU'

// Только код страны
const dataCountry = Geo.getByCode('GB')
console.log(dataCountry.language) // 'en'

// Только код языка
const dataLanguage = Geo.getByCode('fr')
console.log(dataLanguage.country) // 'FR'

// Запасной вариант при неверном коде
const dataDefault = Geo.getByCode('invalid')
console.log(dataDefault) // Первая страна из списка
```

### `getByCodeFull`

Возвращает данные страны по полному коду язык-страна.

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

**Возвращает:** `GeoItem | undefined` — данные страны или undefined если не найдено

```javascript
const data = Geo.getByCodeFull('ru-RU')
if (data) {
  console.log(data.country) // 'RU'
  console.log(data.language) // 'ru'
}

// Также поддерживает обратный формат
const dataReverse = Geo.getByCodeFull('GB-en')
console.log(dataReverse?.country) // 'GB'
```

### `getByCountry`

Возвращает данные страны по коду страны.

**Параметры:**
- `country: string` — ISO код страны

**Возвращает:** `GeoItem | undefined` — данные страны или undefined если не найдено

```javascript
const data = Geo.getByCountry('DE')
if (data) {
  console.log(data.language) // 'de'
  console.log(data.standard) // 'de-DE'
}
```

### `getByLanguage`

Возвращает данные страны по коду языка.

**Параметры:**
- `language: string` — ISO код языка

**Возвращает:** `GeoItem | undefined` — данные страны или undefined если не найдено

```javascript
const data = Geo.getByLanguage('es')
if (data) {
  console.log(data.country) // 'ES'
  console.log(data.standard) // 'es-ES'
}
```

## Методы конфигурации

### `set`

Устанавливает новое местоположение и сохраняет его в localStorage.

**Параметры:**
- `code?: string` — код местоположения в различных форматах (опционально)

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

```javascript
// Установка полным кодом
Geo.set('fr-FR')

// Установка кодом страны
Geo.set('IT')

// Установка кодом языка
Geo.set('ja')

// Цепочка вызовов
Geo.set('de-DE').setTimezone(-60)
```

### `setTimezone`

Устанавливает смещение часового пояса.

**Параметры:**
- `timezone: number` — смещение часового пояса в минутах

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

```javascript
// Установка UTC+3 (московское время)
Geo.setTimezone(-180)

// Установка UTC-5 (нью-йоркское время)
Geo.setTimezone(300)

// Цепочка вызовов
Geo.setTimezone(-60).set('de-DE')
```

## Утилитарные методы

### `toCountry`

Преобразует код страны в формат верхнего регистра.

**Параметры:**
- `country: string` — код страны в любом регистре

**Возвращает:** `string` — код страны в верхнем регистре

```javascript
const country = Geo.toCountry('ru')
console.log(country) // 'RU'
```

### `toLanguage`

Преобразует код языка в формат нижнего регистра.

**Параметры:**
- `language: string` — код языка в любом регистре

**Возвращает:** `string` — код языка в нижнем регистре

```javascript
const language = Geo.toLanguage('EN')
console.log(language) // 'en'
```

### `toFull`

Преобразует базовый географический элемент в полный формат с дополнительными данными.

**Параметры:**
- `item: GeoItem` — базовый географический элемент

**Возвращает:** `GeoItemFull` — расширенные географические данные

```javascript
const basicItem = { country: 'RU', language: 'ru', standard: 'ru-RU', firstDay: 'Mo' }
const fullItem = Geo.toFull(basicItem)
console.log(fullItem.countryAlternative) // ['Россия', 'Russia', ...]
```

## Примеры

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

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

// Получить информацию о текущем местоположении
console.log('Текущая страна:', Geo.getCountry())
console.log('Текущий язык:', Geo.getLanguage())
console.log('Полное местоположение:', Geo.getLocation())
console.log('Первый день недели:', Geo.getFirstDay())
```

### Установка пользовательского местоположения

```javascript
// Установить местоположение на Германию
Geo.set('de-DE')

console.log('Новая страна:', Geo.getCountry()) // 'DE'
console.log('Новый язык:', Geo.getLanguage()) // 'de'
console.log('Первый день:', Geo.getFirstDay()) // 'Mo'
```

### Работа с данными стран

```javascript
// Найти страну по разным кодам
const russiaByFull = Geo.getByCode('ru-RU')
const russiaByCountry = Geo.getByCode('RU')
const russiaByLanguage = Geo.getByCode('ru')

console.log('Все возвращают Россию:', russiaByFull.country) // 'RU'
```

### Создание селектора стран

```javascript
// Получить все страны для выпадающего списка
const countries = Geo.getList()

const countryOptions = countries.map(country => ({
  value: country.standard,
  label: `${country.language}-${country.country}`,
  country: country.country,
  language: country.language
}))

console.log('Всего стран:', countryOptions.length)
```
