@dxtmisha/wiki 0.39.7 → 0.56.0

package/src/media/functional/functional-basic/classes/Formatters/Formatters.vi.mdx

@@ -4,34 +4,34 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 # Lớp Formatters
 
-Một lớp chuyên dụng để định dạng danh sách dữ liệu dựa trên cấu hình được cung cấp. Nó đóng vai trò như một cầu nối giữa dữ liệu thô và các chuỗi văn bản đã được địa phương hóa, dễ đọc, tận dụng cơ chế singleton `GeoIntl` để đảm bảo tính nhất quán trong định dạng trên các ngôn ngữ khác nhau.
+Một lớp chuyên dụng để định dạng danh sách dữ liệu dựa trên cấu hình được cung cấp. Nó đóng vai trò là cầu nối giữa dữ liệu thô và các chuỗi đã được bản địa hóa, dễ đọc, sử dụng singleton `GeoIntl` để định dạng nhất quán trên các ngôn ngữ khác nhau.
 
-## Tính năng chính
+## Các tính năng chính
 
-- **Cấu hình khai báo** — Định nghĩa các quy tắc định dạng một lần và áp dụng chúng cho toàn bộ tập dữ liệu.
-- **Hỗ trợ nhiều kiểu dữ liệu** — Hỗ trợ tích hợp cho tiền tệ, ngày tháng, tên, số, số nhiều và các đơn vị đo lường.
-- **Biến đổi tùy chỉnh** — Khả năng cung cấp các hàm riêng cho các nhu cầu định dạng đặc thù.
-- **An toàn kiểu dữ liệu (Type Safety)** — Hỗ trợ đầy đủ TypeScript cho các mục dữ liệu, các tùy chọn và danh sách kết quả đã được định dạng.
-- **Tự động tạo khóa (Key Generation)** — Tự động thêm các giá trị đã định dạng vào các mục với hậu tố `Format` (ví dụ: `price` trở thành `priceFormat`).
+- **Cấu hình khai báo** — Xác định các quy tắc định dạng một lần và áp dụng chúng cho toàn bộ tập dữ liệu.
+- **Hỗ trợ nhiều loại** — Hỗ trợ tích hợp cho tiền tệ, ngày tháng, tên, số, số nhiều và đơn vị đo lường.
+- **Chuyển đổi tùy chỉnh** — Khả năng cung cấp các hàm riêng của bạn cho các nhu cầu định dạng duy nhất.
+- **Typing** — Hỗ trợ TypeScript đầy đủ cho các mục, tham số và danh sách đã định dạng kết quả.
+- **Tự động tạo khóa** — Tự động thêm các giá trị đã định dạng vào các mục với hậu tố `Format` (ví dụ: `price` trở thành `priceFormat`).
 
 ## Khởi tạo
 
-Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `Formatters(options, list)`.
+Để khởi tạo đối tượng, hãy gọi constructor `Formatters(options, list)`.
 
-### Ràng buộc Generic (Generic Constraints)
+### Các ràng buộc Generic (Generic Constraints)
 
-- `Options extends FormattersOptionsList` — kiểu của các tùy chọn định dạng.
-- `List extends FormattersList<FormattersListItem> | FormattersListItem` — kiểu dữ liệu đầu vào (mảng hoặc một mục duy nhất).
-- `Item extends (List extends any[] ? List[number] : List)` — kiểu của một mục duy nhất trong danh sách.
+- `Options extends FormattersOptionsList` — kiểu tham số định dạng.
+- `List extends FormattersListProp` — kiểu dữ liệu đầu vào (mảng hoặc một mục).
+- `Item extends FormattersItemProp<List>` — kiểu của một mục duy nhất trong danh sách.
 
 **Tham số:**
-- `options: Options` — tùy chọn định dạng cho mỗi cột/thuộc tính.
-- `list?: List` — danh sách hoặc mục dữ liệu ban đầu để định dạng.
+- `options: Options` — tham số định dạng cho mỗi cột/thuộc tính.
+- `list?: List` — danh sách dữ liệu ban đầu để định dạng.
 
 ```typescript
 import { Formatters } from '@dxtmisha/functional-basic'
 
-// 1. Xác định các tùy chọn định dạng
+// 1. Xác định các tham số định dạng
 const options = {
   price: { 
     type: 'currency', 
@@ -44,31 +44,17 @@ const options = {
   user: {
     type: 'name',
     options: { lastPropName: 'surname', firstPropName: 'name' }
-  },
-  weight: { 
-    type: 'unit', 
-    options: { unit: 'kilogram' } 
-  },
-  count: { 
-    type: 'plural', 
-    options: { words: 'quả táo|quả táo' } 
-  },
-  status: {
-    transformation: (value: number) => value === 1 ? 'Đang hoạt động' : 'Ngừng hoạt động'
   }
 }
 
-// 2. Dữ liệu ban đầu (có thể là một mảng hoặc một đối tượng duy nhất)
+// 2. Dữ liệu thô
 const data = [
   {
     price: 100,
     currency: 'VND',
     created: '2024-03-07T12:00:00',
-    name: 'Thanh',
-    surname: 'Nguyễn',
-    weight: 75,
-    count: 5,
-    status: 1
+    name: 'An',
+    surname: 'Nguyễn'
   }
 ]
 
@@ -76,93 +62,95 @@ const data = [
 const formatter = new Formatters(options, data)
 ```
 
-## Xử lý dữ liệu
-
-### `to`
+## Các phương thức
 
-Xử lý dữ liệu và trả về kết quả. Nếu đầu vào là một mảng, nó sẽ trả về một mảng mới gồm các mục đã được bổ sung dữ liệu. Nếu đầu vào là một mục duy nhất, nó sẽ trả về chính mục đó với các trường đã định dạng.
+### Xử lý
+- `to(): FormattersReturn<List, Options>` — Xử lý dữ liệu và trả về kết quả. Nếu đầu vào là một mảng, trả về một mảng mới gồm các mục đã được làm giàu. Nếu là một mục duy nhất — một đối tượng duy nhất. Thêm các thuộc tính với hậu tố `Format`.
 
-**Trả về:** `FormattersListColumns<Item, Options> | FormattersListColumnItem<Item, Options>` — dữ liệu đã được bổ sung các thuộc tính `*Format`.
-
-```javascript
-const result = formatter.to()
-/*
-Kết quả (nếu là mảng): [
-  { 
-    id: 101, 
-    price: 100, 
-    currency: 'VND', 
-    priceFormat: '100.000 ₫', 
-    status: 1, 
-    statusFormat: 'Đang hoạt động',
-    ... 
-  }
-]
+### Cấu hình
+- `setList(list?: List): this` — Cập nhật dữ liệu để định dạng. Hỗ trợ nối chuỗi.
 
-Kết quả (nếu là một mục duy nhất): { 
-  price: 100, 
-  priceFormat: '100.000 ₫', 
-  ... 
-}
-*/
-```
-
-## Truy xuất và quản lý dữ liệu
-
-- `is(): boolean` — Kiểm tra xem danh sách/mục đã được thiết lập chưa.
-- `isArray(): boolean` — Kiểm tra xem dữ liệu hiện tại có phải là một mảng không.
+### Thông tin
+- `is(): boolean` — Kiểm tra xem dữ liệu đã được thiết lập để xử lý hay chưa.
+- `isArray(): boolean` — Liệu dữ liệu hiện tại có phải là một mảng hay không.
 - `length(): number` — Trả về số lượng bản ghi trong danh sách.
-- `getList(): Item[]` — Trả về danh sách dữ liệu hiện tại dưới dạng mảng.
+- `getList(): FormattersList<Item>` — Trả về danh sách hiện tại dưới dạng mảng.
 - `getOptions(): Options` — Trả về cấu hình định dạng hiện tại.
-- `setList(list?: List): this` — Cập nhật dữ liệu cần định dạng và trả về thực thể để gọi chuỗi lệnh.
-
-## Cấu trúc cấu hình
-
-Đối tượng cấu hình được truyền vào hàm khởi tạo là một bản đồ (map), nơi mỗi khóa tương ứng với tên một thuộc tính trong dữ liệu của bạn. Mỗi giá trị phải tuân theo cấu trúc `FormattersOptionsItem`.
-
-### Cấu trúc mục chính
 
+## Các loại định dạng và Tham số
+
+Cấu hình `FormattersOptionsList` là một từ điển trong đó các khóa tương ứng với tên thuộc tính trong dữ liệu (hỗ trợ ký hiệu chấm `path.to.prop`) và các giá trị là đối tượng `FormattersOptionsItem`.
+
+### Cấu trúc chung của `FormattersOptionsItem`
+- `type?: FormattersType` — Loại định dạng.
+- `transformation?: (value, item, options) => string` — Hàm chuyển đổi tùy chỉnh.
+- `options?: Options` — Đối tượng tham số, cấu trúc phụ thuộc vào `type` đã chọn.
+
+### Mô tả chi tiết các loại
+
+#### 1. Tiền tệ (`currency`)
+Được sử dụng để hiển thị các giá trị tiền tệ đã được bản địa hóa.
+- `currencyPropName?: string` — Tên thuộc tính trong mục chứa mã tiền tệ (mặc định là `currency`).
+- `options?: string | Intl.NumberFormatOptions` — Bạn có thể truyền một mã cố định (ví dụ: `'VND'`) hoặc một đối tượng cài đặt `Intl.NumberFormat`.
+- `numberOnly?: boolean` — Nếu `true`, chỉ trả về số đã định dạng mà không có biểu tượng tiền tệ.
+
+#### 2. Ngày tháng (`date`)
+Định dạng ngày và giờ thông qua `GeoIntl`.
+- `type?: GeoDate` — Định dạng đặt trước:
+    - `full` — Ngày và giờ đầy đủ.
+    - `datetime` — Ngày và giờ (không có giây).
+    - `date` — Chỉ ngày.
+    - `time` — Chỉ giờ.
+    - `year-month`, `year`, `month`, `day`, `day-month`, `hour-minute`.
+- `options?: Intl.DateTimeFormatOptions` — Các tham số `Intl` tiêu chuẩn (ví dụ: `month: 'long'`).
+- `hour24?: boolean` — Nếu `true`, buộc sử dụng chế độ 24 giờ.
+
+#### 3. Tên (`name`)
+Kết hợp các phần của tên đầy đủ theo đúng thứ tự.
+- `lastPropName?: string` — Trường cho họ (mặc định là `lastName`).
+- `firstPropName?: string` — Trường cho tên (mặc định là `firstName`).
+- `surname?: string` — Trường cho tên đệm (mặc định là `surname`).
+- `short?: boolean` — Nếu `true`, xuất họ và chữ cái đầu (ví dụ: "Nguyễn A.").
+
+#### 4. Số (`number`)
+Định dạng số tiêu chuẩn với phân tách chữ số.
+- `options?: Intl.NumberFormatOptions` — Các tham số `Intl` (số chữ số thập phân, kiểu dáng, v.v.).
+
+#### 5. Số nhiều (`plural`)
+Chọn dạng từ đúng tùy thuộc vào số lượng.
+- `words: string` — Các dạng từ thông qua dấu phân cách `|`.
+    - Cho tiếng Việt: `"quả táo|những quả táo"`.
+    - Cho tiếng Anh: `"apple|apples"`.
+- `options?: Intl.PluralRulesOptions` — Cài đặt quy tắc số nhiều.
+- `optionsNumber?: Intl.NumberFormatOptions` — Cài đặt định dạng cho chính con số được xuất trước từ.
+
+#### 6. Đơn vị đo lường (`unit`)
+Thêm các đơn vị đo lường (km, kg, l).
+- `unit: string` — Mã đơn vị đo lường (ví dụ: `'kilometer'`, `'kilogram'`, `'liter'`).
+- `options?: Intl.NumberFormatOptions` — Tham số định dạng cho phần số.
+
+## Ví dụ
+
+### Sử dụng Dot Notation
 ```typescript
-{
-  // 1. Chỉ định kiểu định dạng
-  type: 'currency' | 'date' | 'name' | 'number' | 'plural' | 'unit',
+const options = {
+  'user.profile.age': { type: 'number' }
+}
+const data = { user: { profile: { age: 25 } } }
+const formatter = new Formatters(options, data)
 
-  // 2. Truyền các tham số dành riêng cho kiểu tại đây
-  options: { ... },
+const result = formatter.to()
+// result.userProfileAgeFormat === "25"
+```
 
-  // 3. Hoặc sử dụng một hàm tùy chỉnh (ghi đè logic của kiểu)
-  transformation: (value, item, options) => string
+### Chuyển đổi tùy chỉnh
+```typescript
+const options = {
+  status: {
+    // Hàm tùy chỉnh có ưu tiên cao hơn type
+    transformation: (value, item) => {
+       return value === 'active' ? `✅ ${item.name} đang trực tuyến` : '❌ Ngoại tuyến'
+    }
+  }
 }
 ```
-
-## Các tham số cụ thể
-
-Dưới đây là các tham số có sẵn bên trong thuộc tính **`options`** cho từng kiểu.
-
-### Tiền tệ (`currency`)
-- `currencyPropName?: string` — Thuộc tính trong mục chứa mã tiền tệ (mặc định là `item.currency`).
-- `options?: string | Intl.NumberFormatOptions` — Mã tiền tệ cố định hoặc các tùy chọn `Intl` đầy đủ.
-- `numberOnly?: boolean` — Nếu là `true`, chỉ trả về số đã định dạng mà không có ký hiệu tiền tệ.
-
-### Ngày tháng (`date`)
-- `type?: GeoDate` — Kiểu thiết lập sẵn: `full`, `datetime`, `date`, `year-month`, `year`, `month`, `day`, `day-month`, `time`, `hour-minute`, `hour`, `minute`, `second`.
-- `options?: Intl.DateTimeFormatOptions['month'] | Intl.DateTimeFormatOptions` — Các tùy chọn ngày tháng tiêu chuẩn của `Intl` hoặc kiểu tháng.
-- `hour24?: boolean` — Kết quả định dạng bắt buộc sử dụng định dạng 24 giờ nếu là `true`.
-
-### Tên (`name`)
-- `lastPropName?: string` — Trường cho họ (mặc định: `lastName`).
-- `firstPropName?: string` — Trường cho tên (mặc định: `firstName`).
-- `surname?: string` — Trường cho tên đệm (mặc định: `surname`).
-- `short?: boolean` — Có sử dụng định dạng rút gọn (viết tắt) hay không.
-
-### Số (`number`)
-- `options?: Intl.NumberFormatOptions` — Các tùy chọn số tiêu chuẩn của `Intl`.
-
-### Số nhiều (`plural`)
-- `words: string` — Các dạng từ cách nhau bởi `|` (ví dụ: `"quả táo|quả táo"`).
-- `options?: Intl.PluralRulesOptions` — Các thiết lập quy tắc số nhiều.
-- `optionsNumber?: Intl.NumberFormatOptions` — Định dạng cho chính con số đó.
-
-### Đơn vị (`unit`)
-- `unit: string | Intl.NumberFormatOptions` — Đơn vị cần hiển thị (ví dụ: `'kilometer'`, `'kilogram'`).
-

package/src/media/functional/functional-basic/classes/Geo/Geo.en.mdx

@@ -8,11 +8,11 @@ A static utility class for centralized management of the application's geographi
 
 ## Key Features
 
-- **Auto-Detection** — intelligently identifies the user's locale via `navigator.language` or HTML attributes if not explicitly defined.
+- **Auto-Detection** — intelligently identifies the user's locale via storage or environment defaults.
 - **Persistence** — utilizes `DataStorage` to save and restore user-selected language and country preferences.
 - **Media Database Integration** — provides access to a comprehensive database of countries and languages from the `@dxtmisha/media` library.
-- **Global Time Management** — centralized setting and retrieval of time zone offsets for correct date handling.
-- **Static Access** — all methods are static, eliminating the need for instantiation (`new Geo()`).
+- **Global Time Management** — centralized setting and retrieval of time zone offsets.
+- **Static Access** — all methods are static, providing a convenient global interface without manual instantiation.
 
 ## Basic Usage
 

package/src/media/functional/functional-basic/classes/Geo/Geo.ru.mdx

@@ -8,11 +8,11 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 ## Ключевые особенности
 
-- **Автоматическое определение** — интеллектуально определяет локаль пользователя через `navigator.language` или настройки HTML, если они не заданы явно.
-- **Персистентность** — использует `DataStorage` для сохранения и восстановления выбранных пользователем предпочтений языка и страны.
-- **Интеграция с медиа-базой** — предоставляет доступ к полной базе данных стран и языков из библиотеки `@dxtmisha/media`.
-- **Глобальное управление временем** — централизованная установка и получение смещения часового пояса для корректной работы с датами.
-- **Статический доступ** — все методы класса статические, что исключает необходимость создания экземпляров (`new Geo()`).
+- **Автоматическое определение** — интеллектуально определяет локаль через хранилище или настройки окружения.
+- **Персистентность** — использует `DataStorage` для сохранения и восстановления предпочтений пользователя.
+- **Интеграция с медиа-базой** — предоставляет доступ к базе данных стран и языков из библиотеки `@dxtmisha/media`.
+- **Глобальное управление временем** — централизованная установка и получение смещения часового пояса.
+- **Статический доступ** — удобный глобальный интерфейс без необходимости ручного создания экземпляров.
 
 ## Базовое использование
 

package/src/media/functional/functional-basic/classes/Geo/Geo.vi.mdx

@@ -8,11 +8,11 @@ Một lớp tiện ích tĩnh (static class) để quản lý tập trung dữ l
 
 ## Tính năng chính
 
-- **Tự động phát hiện** — xác định thông minh địa phương (locale) của người dùng thông qua `navigator.language` hoặc các thuộc tính HTML nếu không được xác định rõ rà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 ngôn ngữ và quốc gia do người dùng chọn.
-- **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 toàn diện về các 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ờ để xử lý ngày tháng chính xác.
-- **Truy cập tĩnh** — tất cả các phương thức đều là tĩnh, loại bỏ nhu cầu khởi tạo (`new Geo()`).
+- **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
 

package/src/media/functional/functional-basic/classes/GeoFlag/GeoFlag.en.mdx

@@ -4,76 +4,119 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 # GeoFlag Class
 
-A class for working with country flags. Provides a convenient interface for retrieving flag icons, localized country and language names based on a country code or locale. It uses `Geo` and `GeoIntl` to resolve localized names.
+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** — A built-in static `flags` dictionary mapping ISO 3166-1 alpha-2 country codes to icon names.
-- **Localized Names** — Returns country and language names according to the current UI locale.
-- **National Names** — A dedicated `getNational` method returns country names in their own language.
-- **Flexible Filtering** — List methods support filtering by an array of codes.
+- **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
 
-Creates a new `GeoFlag` instance with an optional country or locale code.
+To create an instance, use the `GeoFlag(code)` constructor.
 
 **Parameters:**
-- `code?: string` — Country or locale code (e.g., `'US'`, `'en-US'`). Defaults to the current locale from `Geo`.
+- `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'
 
-// Create with the current locale
+// With current locale
 const flag = new GeoFlag()
 
-// Create for a specific country
+// 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'`).
 
-- `get(code?: string): GeoFlagItem | undefined` — Returns a full data object for a country: language, country code, standard, and flag icon name. If no code is specified, uses the constructor's code.
-- `getFlag(code?: string): string | undefined` — Returns only the icon name for a given country's flag.
-- `getList(codes?: string[]): GeoFlagItem[]` — Returns an array of flag data objects. If `codes` is not provided, returns all countries from the dictionary.
-- `getNational(codes?: string[]): GeoFlagNational[]` — Similar to `getList`, but additionally contains country names in the country's own language.
+### Lists
+- `getList(codes?: string[]): GeoFlagItem[]` — Returns an array of country data.
+- `getNational(codes?: string[]): GeoFlagNational[]` — Returns a list of countries with national names.
 
-### Data Mutation
+### Configuration
+- `setCode(code: string): this` — Changes the base locale for the current instance.
 
-- `setCode(code: string): this` — Changes the country code for the current instance.
+## List Methods
 
-## Examples
+The main difference between the methods lies in the language in which the country and language names are returned:
 
-### Displaying a Flag for the Current Country
-```javascript
-import { GeoFlag } from '@dxtmisha/functional-basic'
+*   **`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 "日本").
 
-const flag = new GeoFlag()
-const item = flag.get()
+### Example of the difference in result:
 
-console.log(item?.icon)    // 'f-us'
-console.log(item?.country) // 'United States'
+```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: '日本', 
+  ... 
+}] 
+*/
 ```
 
-### List of All Countries with Flags
-```javascript
-const flag = new GeoFlag('en-US')
-const countries = flag.getList()
+## Types
 
-countries.forEach(item => {
-  console.log(`${item.icon}: ${item.country}`)
-})
-// 'f-fr: France', 'f-de: Germany', ...
-```
+### `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).
 
-### List with National Names
-```javascript
-// Returns the country name in both your language and the country's own language
-const national = new GeoFlag('en-US').getNational(['FR', 'JP', 'RU'])
+### `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`).
 
-national.forEach(item => {
-  console.log(`${item.country} (${item.nationalCountry})`)
-})
-// France (France), Japan (日本), Russia (Россия)
+## 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', 
+    ... 
+  }
+]
+*/
 ```

package/src/media/functional/functional-basic/classes/GeoFlag/GeoFlag.ru.mdx

@@ -4,76 +4,119 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 # Класс GeoFlag
 
-Класс для работы с флагами стран. Предоставляет удобный интерфейс для получения иконок флагов, отображаемых имен стран и языков на основе кода страны или локали. Использует `Geo` и `GeoIntl` для разрешения локализованных наименований.
+Класс для работы с флагами стран и географической информацией. Он предоставляет удобный интерфейс для получения иконок флагов, локализованных названий стран и языков. Использует синглтоны `Geo` и `GeoIntl` для корректного разрешения данных в зависимости от текущей локали.
 
 ## Ключевые особенности
 
-- **Словарь флагов** — встроенный статический словарь `flags`, связывающий коды стран (ISO 3166-1 alpha-2) с именами иконок.
-- **Локализованные имена** — возвращает название страны и языка в соответствии с текущей локалью интерфейса.
-- **Национальные имена** — отдельный метод `getNational` возвращает названия стран на их собственном языке.
-- **Гибкая фильтрация** — методы списков поддерживают фильтрацию по массиву кодов.
+- **Словарь флагов** — встроенный статический список `flags`, связывающий коды ISO 3166-1 alpha-2 с именами иконок.
+- **Локализованные данные** — автоматический перевод названий стран и языков на язык текущего интерфейса.
+- **Национальная поддержка** — возможность получения названий стран на их «родном» языке (например, «Япония» и «日本» одновременно).
+- **Масштабируемость** — поддержка фильтрации и получения полных списков для селекторов стран.
 
 ## Инициализация
 
-Создает новый экземпляр `GeoFlag` с опциональным кодом страны или локали.
+Для создания экземпляра используйте конструктор `GeoFlag(code)`.
 
 **Параметры:**
-- `code?: string` — код страны или локали (например, `'RU'`, `'ru-RU'`). По умолчанию используется текущая локаль из `Geo`.
+- `code?: string` — код страны или локали (например, `'RU'`, `'en-US'`). Если не указан, используется текущая локаль из системы `Geo`.
 
 ```javascript
 import { GeoFlag } from '@dxtmisha/functional-basic'
 
-// Создание с текущей локалью
+// С текущей локалью
 const flag = new GeoFlag()
 
-// Создание для конкретной страны
+// Для конкретной страны
 const ruFlag = new GeoFlag('ru-RU')
 ```
 
 ## Методы
 
 ### Получение данных
+- `get(code?: string): GeoFlagItem | undefined` — Возвращает полный объект данных о стране.
+- `getFlag(code?: string): string | undefined` — Возвращает только идентификатор иконки флага (например, `'f-ru'`).
 
-- `get(code?: string): GeoFlagItem | undefined` — Возвращает полный объект данных о стране: языке, коде страны, стандарте, иконке флага. Если код не указан, используется код из конструктора.
-- `getFlag(code?: string): string | undefined` — Возвращает только имя иконки флага для указанной страны.
-- `getList(codes?: string[]): GeoFlagItem[]` — Возвращает массив объектов с данными о флагах. Если `codes` не передан, возвращает все страны из словаря.
-- `getNational(codes?: string[]): GeoFlagNational[]` — Аналог `getList`, но дополнительно содержит названия на национальном языке страны.
+### Списки
+- `getList(codes?: string[]): GeoFlagItem[]` — Возвращает массив данных о странах.
+- `getNational(codes?: string[]): GeoFlagNational[]` — Возвращает список стран с национальными названиями.
 
-### Изменение данных
+### Настройка
+- `setCode(code: string): this` — Изменяет базовую локаль для текущего экземпляра.
 
-- `setCode(code: string): this` — Изменяет код страны для текущего экземпляра.
+## Методы работы со списками
 
-## Примеры
+Основное различие между методами заключается в языке, на котором возвращаются названия стран и языков:
 
-### Отображение флага для текущей страны
-```javascript
-import { GeoFlag } from '@dxtmisha/functional-basic'
+*   **`getList`** — возвращает названия только на том языке, который установлен в экземпляре класса (например, всё на русском).
+*   **`getNational`** — возвращает названия на языке вашего интерфейса + добавляет оригинальные названия на языке самой страны (например, «Япония» и «日本»).
 
-const flag = new GeoFlag()
-const item = flag.get()
+### Пример разницы в результате:
 
-console.log(item?.icon)    // 'f-ru'
-console.log(item?.country) // 'Россия'
+```javascript
+const geo = new GeoFlag('ru-RU') // Установлен русский язык
+
+// 1. getList возвращает только перевод
+const list = geo.getList(['JP']) 
+/* 
+[{ country: 'Япония', ... }] 
+*/
+
+// 2. getNational возвращает перевод + оригинальное название
+const national = geo.getNational(['JP']) 
+/* 
+[{ 
+  country: 'Япония', 
+  nationalCountry: '日本', 
+  ... 
+}] 
+*/
 ```
 
-### Список всех стран с флагами
-```javascript
-const flag = new GeoFlag('ru-RU')
-const countries = flag.getList()
+## Типы
 
-countries.forEach(item => {
-  console.log(`${item.icon}: ${item.country}`)
-})
-// 'f-us: США', 'f-fr: Франция', ...
-```
+### `GeoFlagItem`
+Базовый объект информации о флаге.
+- `country`: string — Локализованное название страны.
+- `language`: string — Локализованное название языка.
+- `standard`: string — Полный стандарт локали (например, `ru-RU`).
+- `icon`: string — Имя иконки флага (префикс `f-`).
+- `label`: string — Метка для отображения (по умолчанию совпадает с `country`).
+- `value`: string — Код страны (ISO alpha-2).
 
-### Список с национальными наименованиями
-```javascript
-// Вернет название страны как на вашем языке, так и на языке самой страны
-const national = new GeoFlag('ru-RU').getNational(['US', 'FR', 'JP'])
+### `GeoFlagNational`
+Расширяет `GeoFlagItem` дополнительными полями:
+- `nationalCountry`: string — Название страны на её родном языке.
+- `nationalLanguage`: string — Название языка на родном языке.
+- `description`: string — Краткое описание (дублирует `nationalCountry`).
 
-national.forEach(item => {
-  console.log(`${item.country} (${item.nationalCountry})`)
-})
-// США (United States), Франция (France), Япония (日本)
+## Примеры
+
+### Список популярных стран с национальными именами
+```javascript
+const geo = new GeoFlag('ru-RU')
+const list = geo.getNational(['RU', 'CN', 'JP'])
+
+/* 
+Результат:
+[
+  { 
+    country: 'Россия', 
+    nationalCountry: 'Россия', 
+    icon: 'f-ru', 
+    ... 
+  },
+  { 
+    country: 'Китай', 
+    nationalCountry: '中国', 
+    icon: 'f-cn', 
+    ... 
+  },
+  { 
+    country: 'Япония', 
+    nationalCountry: '日本', 
+    icon: 'f-jp', 
+    ... 
+  }
+]
+*/
 ```