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

<Meta title='@dxtmisha/en/functional-basic/Classes/GeoFlag - Country Flags'/>

# GeoFlag Class

A class for working with country flags and geographic information. It provides a convenient interface for retrieving flag icons, localized country names, and languages. It uses the `Geo` and `GeoIntl` singletons to correctly resolve data based on the current locale.

## Key Features

- **Flag Dictionary** — built-in static `flags` list mapping ISO 3166-1 alpha-2 codes to icon names.
- **Localized Data** — automatic translation of country and language names into the current interface language.
- **National Support** — the ability to retrieve country names in their "native" language (e.g., "Japan" and "日本" simultaneously).
- **Scalability** — support for filtering and retrieving full lists for country selectors.

## Initialization

To create an instance, use the `GeoFlag(code)` constructor.

**Parameters:**
- `code?: string` — country or locale code (e.g., `'US'`, `'en-US'`). If not specified, the current locale from the `Geo` system is used.

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

// With current locale
const flag = new GeoFlag()

// For a specific country
const usFlag = new GeoFlag('en-US')
```

## Methods

### Data Retrieval
- `get(code?: string): GeoFlagItem | undefined` — Returns a full data object about a country.
- `getFlag(code?: string): string | undefined` — Returns only the flag icon identifier (e.g., `'f-us'`).

### Lists
- `getList(codes?: string[], sort: boolean = true): GeoFlagItem[]` — Returns an array of country data, sorted alphabetically by default.
- `getNational(codes?: string[], sort: boolean = true): GeoFlagNational[]` — Returns a list of countries with national names, sorted alphabetically by default.

### Configuration
- `setCode(code: string): this` — Changes the base locale for the current instance.

## List Methods

The main difference between the methods lies in the language in which the country and language names are returned:

*   **`getList`** — returns names only in the language set in the class instance (e.g., everything in English).
*   **`getNational`** — returns names in your interface language + adds original names in the country's own language (e.g., "Japan" and "日本").

### Example of the difference in result:

```javascript
const geo = new GeoFlag('en-US') // English language is set

// 1. getList returns only the translation
const list = geo.getList(['JP']) 
/* 
[{ country: 'Japan', ... }] 
*/

// 2. getNational returns the translation + original name
const national = geo.getNational(['JP']) 
/* 
[{ 
  country: 'Japan', 
  nationalCountry: '日本', 
  ... 
}] 
*/
```

## Types

### `GeoFlagItem`
Basic flag information object.
- `country`: string — Localized country name.
- `language`: string — Localized language name.
- `standard`: string — Full locale standard (e.g., `en-US`).
- `icon`: string — Flag icon name (prefix `f-`).
- `label`: string — Display label (matches `country` by default).
- `value`: string — Country code (ISO alpha-2).
- `phoneCode`: string — Country phone code (e.g., `+1`, `+7`).

### `GeoFlagNational`
Extends `GeoFlagItem` with additional fields:
- `nationalCountry`: string — Country name in its native language.
- `nationalLanguage`: string — Language name in its native language.
- `description`: string — Brief description (duplicates `nationalCountry`).

## Examples

### List of Popular Countries with National Names
```javascript
const geo = new GeoFlag('en-US')
const list = geo.getNational(['US', 'CN', 'JP'])

/* 
Result:
[
  { 
    country: 'United States', 
    nationalCountry: 'United States', 
    icon: 'f-us', 
    ... 
  },
  { 
    country: 'China', 
    nationalCountry: '中国', 
    icon: 'f-cn', 
    ... 
  },
  { 
    country: 'Japan', 
    nationalCountry: '日本', 
    icon: 'f-jp', 
    ... 
  }
]
*/
```
