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

<Meta title='@dxtmisha/vi/functional-basic/Classes/GeoFlag - Cờ các quốc gia'/>

# Lớp GeoFlag

Một lớp để làm việc với cờ các quốc gia và thông tin địa lý. Nó cung cấp một giao diện thuận tiện để lấy các biểu tượng cờ, tên quốc gia và ngôn ngữ đã được bản địa hóa. Nó sử dụng các singleton `Geo` và `GeoIntl` để giải quyết dữ liệu một cách chính xác dựa trên ngôn ngữ hiện tại.

## Các tính năng chính

- **Từ điển cờ** — danh sách `flags` tĩnh tích hợp ánh xạ mã ISO 3166-1 alpha-2 với tên biểu tượng.
- **Dữ liệu được bản địa hóa** — tự động dịch tên quốc gia và ngôn ngữ sang ngôn ngữ giao diện hiện tại.
- **Hỗ trợ quốc gia** — khả năng lấy tên quốc gia bằng ngôn ngữ "gốc" của họ (ví dụ: "Nhật Bản" và "日本" đồng thời).
- **Khả năng mở rộng** — hỗ trợ lọc và lấy danh sách đầy đủ cho các bộ chọn quốc gia.

## Khởi tạo

Để tạo một thực thể, hãy sử dụng constructor `GeoFlag(code)`.

**Tham số:**
- `code?: string` — mã quốc gia hoặc ngôn ngữ (ví dụ: `'VN'`, `'vi-VN'`). Nếu không được chỉ định, ngôn ngữ hiện tại từ hệ thống `Geo` sẽ được sử dụng.

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

// Với ngôn ngữ hiện tại
const flag = new GeoFlag()

// Cho một quốc gia cụ thể
const vnFlag = new GeoFlag('vi-VN')
```

## Các phương thức

### Lấy dữ liệu
- `get(code?: string): GeoFlagItem | undefined` — Trả về một đối tượng dữ liệu đầy đủ về một quốc gia.
- `getFlag(code?: string): string | undefined` — Trả về chỉ định danh biểu tượng cờ (ví dụ: `'f-vn'`).

### Danh sách
- `getList(codes?: string[], sort: boolean = true): GeoFlagItem[]` — Trả về một mảng dữ liệu quốc gia. Mặc định sắp xếp theo bảng chữ cái.
- `getNational(codes?: string[], sort: boolean = true): GeoFlagNational[]` — Trả về danh sách các quốc gia với tên quốc gia gốc. Mặc định sắp xếp theo bảng chữ cái.

### Cấu hình
- `setCode(code: string): this` — Thay đổi ngôn ngữ cơ sở cho thực thể hiện tại.

## Các phương thức danh sách

Sự khác biệt chính giữa các phương thức nằm ở ngôn ngữ mà tên quốc gia và ngôn ngữ được trả về:

*   **`getList`** — trả về tên chỉ bằng ngôn ngữ được thiết lập trong thực thể lớp (ví dụ: tất cả bằng tiếng Việt).
*   **`getNational`** — trả về tên bằng ngôn ngữ giao diện của bạn + thêm tên gốc bằng ngôn ngữ của chính quốc gia đó (ví dụ: "Nhật Bản" và "日本").

### Ví dụ về sự khác biệt trong kết quả:

```javascript
const geo = new GeoFlag('vi-VN') // Ngôn ngữ tiếng Việt được thiết lập

// 1. getList chỉ trả về bản dịch
const list = geo.getList(['JP']) 
/* 
[{ country: 'Nhật Bản', ... }] 
*/

// 2. getNational trả về bản dịch + tên gốc
const national = geo.getNational(['JP']) 
/* 
[{ 
  country: 'Nhật Bản', 
  nationalCountry: '日本', 
  ... 
}] 
*/
```

## Các kiểu dữ liệu

### `GeoFlagItem`
Đối tượng thông tin cờ cơ bản.
- `country`: string — Tên quốc gia đã được bản địa hóa.
- `language`: string — Tên ngôn ngữ đã được bản địa hóa.
- `standard`: string — Tiêu chuẩn ngôn ngữ đầy đủ (ví dụ: `vi-VN`).
- `icon`: string — Tên biểu tượng cờ (tiền tố `f-`).
- `label`: string — Nhãn hiển thị (mặc định khớp với `country`).
- `value`: string — Mã quốc gia (ISO alpha-2).
- `phoneCode`: string — Mã điện thoại quốc gia (ví dụ: `+1`, `+7`).

### `GeoFlagNational`
Mở rộng `GeoFlagItem` với các trường bổ sung:
- `nationalCountry`: string — Tên quốc gia bằng ngôn ngữ gốc.
- `nationalLanguage`: string — Tên ngôn ngữ bằng ngôn ngữ gốc.
- `description`: string — Mô tả ngắn gọn (sao chép `nationalCountry`).

## Ví dụ

### Danh sách các quốc gia phổ biến với tên quốc gia gốc
```javascript
const geo = new GeoFlag('vi-VN')
const list = geo.getNational(['VN', 'CN', 'JP'])

/* 
Kết quả:
[
  { 
    country: 'Việt Nam', 
    nationalCountry: 'Việt Nam', 
    icon: 'f-vn', 
    ... 
  },
  { 
    country: 'Trung Quốc', 
    nationalCountry: '中国', 
    icon: 'f-cn', 
    ... 
  },
  { 
    country: 'Nhật Bản', 
    nationalCountry: '日本', 
    icon: 'f-jp', 
    ... 
  }
]
*/
```
