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

<Meta title='@dxtmisha/vi/functional-basic/Classes/Geo - Dữ liệu Vùng Miền Toàn Cầu'/>

# Lớp Geo

Một lớp tiện ích tĩnh (static class) để quản lý tập trung dữ liệu địa lý của ứng dụng. Nó xử lý các mã ngôn ngữ (ISO 639-1), mã quốc gia (ISO 3166-1 alpha-2), múi giờ và địa phương hóa. Lớp này tự động phát hiện các cài đặt môi trường và đảm bảo việc sử dụng nhất quán trong toàn bộ hệ thống.

## Tính năng chính

- **Tự động phát hiện** — xác định thông minh địa phương (locale) thông qua bộ nhớ hoặc mặc định của môi trường.
- **Lưu trữ lâu dài** — sử dụng `DataStorage` để lưu và khôi phục các tùy chọn của người dùng.
- **Tích hợp cơ sở dữ liệu truyền thông** — cung cấp quyền truy cập vào cơ sở dữ liệu quốc gia và ngôn ngữ từ thư viện `@dxtmisha/media`.
- **Quản lý thời gian toàn cầu** — thiết lập và truy xuất tập trung các độ lệch múi giờ.
- **Truy cập tĩnh** — cung cấp giao diện toàn cầu thuận tiện mà không cần khởi tạo thủ công.

## Cách sử dụng cơ bản

Vì lớp này là tĩnh, các phương thức của nó có thể được gọi trực tiếp.

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

// Lấy mã ngôn ngữ hiện tại
console.log(Geo.getLanguage()) // ví dụ: 'vi'

// Thiết lập một địa phương mới và lưu lại
Geo.set('en-US', true)

// Lấy múi giờ đã định dạng
console.log(Geo.getTimezoneFormat()) // ví dụ: '+07:00'
```

## Phương pháp

### Thông tin chung

- `get(): GeoItemFull` — Trả về đối tượng dữ liệu đầy đủ cho quốc gia và ngôn ngữ hiện tại.
- `getCountry(): string` — Trả về mã 2 chữ cái của quốc gia hiện tại (viết hoa).
- `getLanguage(): string` — Trả về mã 2 chữ cái của ngôn ngữ hiện tại (viết thường).
- `getStandard(): string` — Trả về chuỗi địa phương kết hợp (ví dụ: `'vi-VN'`).
- `getFirstDay(): string` — Trả về mã cho ngày đầu tiên của tuần của địa phương hiện tại (ví dụ: `'Mo'`, `'Su'`).
- `getLocation(): string` — Trả về địa phương hiện đang được thiết lập dưới dạng chuỗi.
- `getItem(): GeoItemFull` — Trả về một bản sao của đối tượng cài đặt hiện tại, có tính đến ngôn ngữ.
- `getTimezone(): number` — Trả về độ lệch múi giờ tính bằng phút.
- `getTimezoneFormat(): string` — Trả về độ lệch múi giờ ở định dạng chuỗi (ví dụ: `'+07:00'`).

### Danh sách và Tìm kiếm

- `getList(): GeoItem[]` — Trả về danh sách đầy đủ các quốc gia và ngôn ngữ có sẵn từ cơ sở dữ liệu truyền thông.
- `getByCode(code?: string): GeoItemFull` — Tìm kiếm dữ liệu theo mã ngôn ngữ hoặc quốc gia (có hỗ trợ dự phòng).
- `getByCodeFull(code: string): GeoItem | undefined` — Tìm kiếm kết quả khớp chính xác theo mã địa phương đầy đủ (ngôn ngữ-quốc gia).
- `getByCountry(country: string): GeoItem | undefined` — Tìm kiếm dữ liệu theo mã quốc gia hoặc tên thay thế.
- `getByLanguage(language: string): GeoItem | undefined` — Tìm kiếm dữ liệu theo mã ngôn ngữ.
- `find(code: string): GeoItemFull` — Một bí danh cho phương thức `getByCode`.

### Thao tác dữ liệu (Setters)

- `set(code: string, save?: boolean): void` — Thiết lập địa phương hiện tại trên toàn cầu. Nếu `save` là `true`, sẽ lưu lựa chọn vào `localStorage`.
- `setTimezone(timezone: number): void` — Thiết lập độ lệch múi giờ tùy chỉnh tính bằng phút.

### Tiện ích

- `toStandard(item: GeoItem): string` — Một phương thức tĩnh để tạo chuỗi `'ngôn ngữ-quốc gia'` tiêu chuẩn từ đối tượng `GeoItem`.

## Ví dụ

### Thiết lập địa phương thủ công khi khởi chạy ứng dụng
```javascript
import { Geo } from '@dxtmisha/functional-basic'

// Giả sử chúng ta đã lấy được cài đặt của người dùng từ một API
const userLocale = 'ja-JP'

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

### Làm việc với múi giờ
```javascript
// Thiết lập độ lệch cho Tokyo (UTC+9)
Geo.setTimezone(-540) // độ lệch tính bằng phút (9 * 60)

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

### Truy xuất danh sách quốc gia cho một bộ chọn (Selector)
```javascript
const countries = Geo.getList().map(item => ({
  value: item.country,
  label: `${item.language.toUpperCase()} - ${item.country}`
}))
```
