@dxtmisha/wiki 0.39.1 → 0.39.3

package/src/media/functional/functional/classes/EventRef/EventRef.en.mdx

@@ -0,0 +1,104 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Classes/EventRef - Reactive Event Manager'/>
+
+# EventRef Class
+
+A reactive event listener manager that simplifies attaching and detaching events to DOM elements or the `window` object. It automatically updates subscriptions when the target element (provided as a Vue `Ref`) changes.
+
+Includes automatic re-binding of listeners during dynamic element changes and full integration with the Vue lifecycle.
+
+## Key Features
+
+- **Reactivity** — automatic updates when the element `Ref` changes.
+- **Multi-type Support** — listen to multiple event types simultaneously.
+- **Automatic Cleanup** — efficient memory management via the reactivity system.
+
+## Initialization
+
+Creates a new `EventRef` instance. The class automatically synchronizes event listeners with the state of the passed Vue `ref`. If the target element changes, `DesignConstructorAbstract` automatically rebinds the event.
+
+### Generic Constraints
+
+- `E extends ElementOrWindow` — type of the target element (e.g., `HTMLElement`, `Window`, or `Document`).
+- `O extends Event` — type of the event object (e.g., `MouseEvent`, `KeyboardEvent`).
+- `D extends Record<string, any>` — type of custom data (`detail`) associated with the event.
+
+**Parameters:**
+- `elementSelector?: RefOrNormal<ElementOrString<E> | undefined>` — target element or selector (can be reactive).
+- `elementSelectorControl?: RefOrNormal<ElementOrString<HTMLElement>>` — control element. If it is removed from the DOM, listening stops.
+- `type: string | string[] = ['click']` — event type or array of types.
+- `listener?: EventListenerDetail<O, D>` — handler function.
+- `options?: EventOptions` — listener options (`capture`, `passive`, `once`).
+- `detail?: D` — additional event data.
+
+```typescript
+import { EventRef } from '@dxtmisha/functional'
+import { ref, onMounted, onUnmounted } from 'vue'
+
+// 1. Simple initialization with Ref
+const buttonRef = ref<HTMLButtonElement>()
+const event = new EventRef(buttonRef, undefined, 'click', (e) => {
+  console.log('Button clicked:', e.target)
+})
+
+// 2. Using multiple events and options
+const scrollEvent = new EventRef(
+  window, 
+  undefined, 
+  ['scroll', 'resize'], 
+  () => console.log('Window changed'),
+  { passive: true }
+)
+
+onMounted(() => {
+  event.start()
+  scrollEvent.start()
+})
+
+onUnmounted(() => {
+  event.stop()
+  scrollEvent.stop()
+})
+```
+
+## Lifecycle & Control
+
+Methods for controlling the activity of listeners.
+
+- `start(): this` — Activates event listening. If the target element (`ref`) is not yet mounted, the listeners will be added automatically as soon as it appears.
+- `stop(): this` — Deactivates listening and removes all handlers from the current element.
+- `toggle(activity: boolean): this` — Enables or disables listening based on the provided value.
+- `reset(): this` — Restarts listening. It is automatically called when key parameters (event type, options, etc.) change.
+
+## State & Data Acquisition
+
+Methods for checking the object's current status.
+
+- `isActive(): boolean` — Returns `true` if event listening is currently active.
+- `getElement(): E | undefined` — Returns the current DOM element or object on which the listeners are set.
+
+## Configuration (Setters)
+
+All methods in this group support method chaining and automatically update active listeners.
+
+- `setElement(element: ElementOrString): this` — Dynamically changes the target element. When used in `EventRef`, it also supports reactive `ref`.
+- `setElementControl(element: ElementOrString): this` — Sets a control element. If this element is removed from the DOM, event listening on the main element is automatically stopped (protection against memory leaks).
+- `setType(type: string | string[]): this` — Updates the types of listened events (e.g., changes `click` to `dblclick`).
+- `setListener(listener: Function): this` — Changes the event handler function without restarting the entire cycle.
+- `setOptions(options: EventOptions): this` — Updates the listener options (`capture`, `passive`, `once`).
+- `setDetail(detail: object): this` — Updates the custom data available within the handler.
+
+## Actions
+
+- `dispatch(detail?: object): this` — Programmatically triggers an event on the target element. If data is passed in `detail`, it will take precedence over those set via `setDetail`.
+
+## Special Events
+
+`EventRef` (via the base class `EventItem`) provides enhanced handling for certain event types:
+
+### `resize`
+Unlike the standard `resize` event, which only works on the `window` object, here it uses `ResizeObserver`. This allows tracking dimension changes for any specific DOM element.
+
+### `scroll-sync`
+An optimized version of the scroll event. It uses `requestAnimationFrame` to synchronize the handler call with the screen refresh rate, preventing "lag" during heavy calculations during scrolling.

package/src/media/functional/functional/classes/EventRef/EventRef.ru.mdx

@@ -0,0 +1,104 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Classes/EventRef - Реактивный менеджер событий'/>
+
+# Класс EventRef
+
+Реактивный менеджер событий, упрощающий управление слушателями для DOM-элементов или объекта `window`. Автоматически обновляет подписки при изменении целевого элемента (переданного как Vue `Ref`).
+
+Включает автоматическую обработку перепривязки слушателей при динамическом изменении элементов и интеграцию с жизненным циклом Vue.
+
+## Ключевые особенности
+
+- **Реактивность** — автоматическое обновление при изменении `Ref` элемента.
+- **Поддержка нескольких типов** — одновременное прослушивание нескольких событий.
+- **Автоматическая очистка** — эффективное управление памятью через систему реактивности.
+
+## Инициализация
+
+Создает новый экземпляр `EventRef`. Класс автоматически синхронизирует слушатели событий с состоянием переданных Vue `ref`. Если целевой элемент изменяется, `EventRef` автоматически перепривязывает событие.
+
+### Ограничения дженериков (Generic Constraints)
+
+- `E extends ElementOrWindow` — тип целевого элемента (например, `HTMLElement`, `Window`, или `Document`).
+- `O extends Event` — тип объекта события (например, `MouseEvent`, `KeyboardEvent`).
+- `D extends Record<string, any>` — тип пользовательских данных (`detail`), связанных с событием.
+
+**Параметры:**
+- `elementSelector?: RefOrNormal<ElementOrString<E> | undefined>` — целевой элемент или селектор (может быть реактивным).
+- `elementSelectorControl?: RefOrNormal<ElementOrString<HTMLElement>>` — контрольный элемент. Если он удален из DOM, прослушивание прекращается.
+- `type: string | string[] = ['click']` — тип события или массив типов.
+- `listener?: EventListenerDetail<O, D>` — функция-обработчик.
+- `options?: EventOptions` — параметры слушателя (`capture`, `passive`, `once`).
+- `detail?: D` — дополнительные данные события.
+
+```typescript
+import { EventRef } from '@dxtmisha/functional'
+import { ref, onMounted, onUnmounted } from 'vue'
+
+// 1. Простая инициализация с Ref
+const buttonRef = ref<HTMLButtonElement>()
+const event = new EventRef(buttonRef, undefined, 'click', (e) => {
+  console.log('Нажата кнопка:', e.target)
+})
+
+// 2. Использование нескольких событий и опций
+const scrollEvent = new EventRef(
+  window, 
+  undefined, 
+  ['scroll', 'resize'], 
+  () => console.log('Изменение окна'),
+  { passive: true }
+)
+
+onMounted(() => {
+  event.start()
+  scrollEvent.start()
+})
+
+onUnmounted(() => {
+  event.stop()
+  scrollEvent.stop()
+})
+```
+
+## Управление жизненным циклом
+
+Методы для контроля активности прослушивателей.
+
+- `start(): this` — Активирует прослушивание событий. Если целевой элемент (`ref`) еще не примонтирован, слушатели будут добавлены автоматически сразу после его появления.
+- `stop(): this` — Деактивирует прослушивание и удаляет все обработчики с текущего элемента.
+- `toggle(activity: boolean): this` — Включает или выключает прослушивание в зависимости от переданного значения.
+- `reset(): this` — Перезапускает прослушивание. Автоматически вызывается при изменении ключевых параметров (типа события, опций и т.д.).
+
+## Состояние и получение данных
+
+Методы для проверки текущего статуса объекта.
+
+- `isActive(): boolean` — Возвращает `true`, если прослушивание событий в данный момент активно.
+- `getElement(): E | undefined` — Возвращает текущий DOM-элемент или объект, на котором установлены слушатели.
+
+## Конфигурация (Сеттеры)
+
+Все методы этой группы поддерживают цепочку вызовов (чейнинг) и автоматически обновляют активные слушатели.
+
+- `setElement(element: ElementOrString): this` — Динамически изменяет целевой элемент. При использовании в `EventRef` также поддерживает реактивные `ref`.
+- `setElementControl(element: ElementOrString): this` — Устанавливает контрольный элемент. Если этот элемент удаляется из DOM, прослушивание событий на основном элементе автоматически прекращается (защита от утечек памяти).
+- `setType(type: string | string[]): this` — Обновляет типы прослушиваемых событий (например, меняет `click` на `dblclick`).
+- `setListener(listener: Function): this` — Изменяет функцию-обработчик события без перезапуска всего цикла.
+- `setOptions(options: EventOptions): this` — Обновляет опции слушателя (`capture`, `passive`, `once`).
+- `setDetail(detail: object): this` — Обновляет пользовательские данные, доступные внутри обработчика.
+
+## Действия
+
+- `dispatch(detail?: object): this` — Программно инициирует событие на целевом элементе. Если переданы данные в `detail`, они будут приоритетнее тех, что установлены через `setDetail`.
+
+## Специальные события
+
+`EventRef` (через базовый класс `EventItem`) предоставляет улучшенную обработку для некоторых типов событий:
+
+### `resize`
+В отличие от стандартного события `resize`, которое работает только на объекте `window`, здесь оно использует `ResizeObserver`. Это позволяет отслеживать изменение размеров любого конкретного DOM-элемента.
+
+### `scroll-sync`
+Оптимизированный вариант события прокрутки. Использует `requestAnimationFrame` для синхронизации вызова обработчика с частотой обновления экрана, что предотвращает "тормоза" при тяжелых вычислениях в процессе скролла.

package/src/media/functional/functional/classes/EventRef/EventRef.vi.mdx

@@ -0,0 +1,104 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Classes/EventRef - Trình quản lý sự kiện phản ứng'/>
+
+# Lớp EventRef
+
+Trình quản lý trình nghe sự kiện có tính phản ứng, giúp đơn giản hóa việc gắn và gỡ bỏ các sự kiện cho các thành phần DOM hoặc đối tượng `window`. Nó tự động cập nhật các đăng ký khi thành phần mục tiêu (được cung cấp dưới dạng Vue `Ref`) thay đổi.
+
+Bao gồm việc tự động liên kết lại các trình nghe trong quá trình thay đổi thành phần động và tích hợp hoàn toàn với vòng đời của Vue.
+
+## Các tính năng chính
+
+- **Tính phản ứng** — tự động cập nhật khi thành phần `Ref` thay đổi.
+- **Hỗ trợ đa loại** — nghe nhiều loại sự kiện cùng một lúc.
+- **Tự động dọn dẹp** — quản lý bộ nhớ hiệu quả thông qua hệ thống phản ứng.
+
+## Khởi tạo
+
+Tạo một thực thể `EventRef` mới. Lớp này tự động đồng bộ hóa các trình lắng nghe sự kiện với trạng thái của Vue `ref` được truyền vào. Nếu phần tử đích thay đổi, `EventRef` sẽ tự động liên kết lại sự kiện.
+
+### Ràng buộc Generic (Generic Constraints)
+
+- `E extends ElementOrWindow` — kiểu của phần tử đích (ví dụ: `HTMLElement`, `Window`, hoặc `Document`).
+- `O extends Event` — kiểu của đối tượng sự kiện (ví dụ: `MouseEvent`, `KeyboardEvent`).
+- `D extends Record<string, any>` — kiểu dữ liệu tùy chỉnh (`detail`) gắn liền với sự kiện.
+
+**Tham số:**
+- `elementSelector?: RefOrNormal<ElementOrString<E> | undefined>` — phần tử đích hoặc bộ chọn (có thể ở dạng phản ứng).
+- `elementSelectorControl?: RefOrNormal<ElementOrString<HTMLElement>>` — phần tử điều khiển. Nếu phần tử này bị xóa khỏi DOM, việc lắng nghe sẽ dừng lại.
+- `type: string | string[] = ['click']` — loại sự kiện hoặc mảng các loại sự kiện.
+- `listener?: EventListenerDetail<O, D>` — hàm xử lý.
+- `options?: EventOptions` — các tùy chọn trình lắng nghe (`capture`, `passive`, `once`).
+- `detail?: D` — dữ liệu bổ sung của sự kiện.
+
+```typescript
+import { EventRef } from '@dxtmisha/functional'
+import { ref, onMounted, onUnmounted } from 'vue'
+
+// 1. Khởi tạo đơn giản với Ref
+const buttonRef = ref<HTMLButtonElement>()
+const event = new EventRef(buttonRef, undefined, 'click', (e) => {
+  console.log('Nút đã được nhấn:', e.target)
+})
+
+// 2. Sử dụng nhiều sự kiện và tùy chọn
+const scrollEvent = new EventRef(
+  window, 
+  undefined, 
+  ['scroll', 'resize'], 
+  () => console.log('Cửa sổ đã thay đổi'),
+  { passive: true }
+)
+
+onMounted(() => {
+  event.start()
+  scrollEvent.start()
+})
+
+onUnmounted(() => {
+  event.stop()
+  scrollEvent.stop()
+})
+```
+
+## Vòng đời & Điều khiển
+
+Các phương thức để kiểm soát hoạt động của trình lắng nghe.
+
+- `start(): this` — Kích hoạt lắng nghe sự kiện. Nếu phần tử đích (`ref`) chưa được gắn kết (mount), các trình lắng nghe sẽ được thêm tự động ngay khi nó xuất hiện.
+- `stop(): this` — Hủy kích hoạt lắng nghe và xóa tất cả các hàm xử lý khỏi phần tử hiện tại.
+- `toggle(activity: boolean): this` — Bật hoặc tắt tính năng lắng nghe dựa trên giá trị được cung cấp.
+- `reset(): this` — Khởi động lại quá trình lắng nghe. Nó được gọi tự động khi các tham số chính (loại sự kiện, tùy chọn, v.v.) thay đổi.
+
+## Trạng thái & Truy xuất dữ liệu
+
+Các phương thức để kiểm tra trạng thái hiện tại của đối tượng.
+
+- `isActive(): boolean` — Trả về `true` nếu việc lắng nghe sự kiện hiện đang hoạt động.
+- `getElement(): E | undefined` — Trả về phần tử DOM hoặc đối tượng hiện tại mà các trình lắng nghe được thiết lập.
+
+## Cấu hình (Setters)
+
+Tất cả các phương thức trong nhóm này đều hỗ trợ chuỗi phương thức (chaining) và tự động cập nhật các trình lắng nghe đang hoạt động.
+
+- `setElement(element: ElementOrString): this` — Thay đổi động phần tử đích. Khi được sử dụng trong `EventRef`, nó cũng hỗ trợ `ref` phản ứng.
+- `setElementControl(element: ElementOrString): this` — Thiết lập một phần tử điều khiển. Nếu phần tử này bị xóa khỏi DOM, việc lắng nghe sự kiện trên phần tử chính sẽ tự động dừng lại (bảo vệ chống rò rỉ bộ nhớ).
+- `setType(type: string | string[]): this` — Cập nhật các loại sự kiện được lắng nghe (ví dụ: thay đổi từ `click` thành `dblclick`).
+- `setListener(listener: Function): this` — Thay đổi hàm xử lý sự kiện mà không cần khởi động lại toàn bộ chu kỳ.
+- `setOptions(options: EventOptions): this` — Cập nhật các tùy chọn của trình lắng nghe (`capture`, `passive`, `once`).
+- `setDetail(detail: object): this` — Cập nhật dữ liệu tùy chỉnh có sẵn bên trong trình xử lý.
+
+## Hành động
+
+- `dispatch(detail?: object): this` — Kích hoạt sự kiện trên phần tử đích bằng lập trình. Nếu dữ liệu được truyền trong `detail`, nó sẽ được ưu tiên hơn dữ liệu được thiết lập thông qua `setDetail`.
+
+## Các sự kiện đặc biệt
+
+`EventRef` (thông qua lớp cơ sở `EventItem`) cung cấp khả năng xử lý nâng cao cho một số loại sự kiện nhất định:
+
+### `resize`
+Không giống như sự kiện `resize` tiêu chuẩn chỉ hoạt động trên đối tượng `window`, ở đây nó sử dụng `ResizeObserver`. Điều này cho phép theo dõi các thay đổi kích thước cho bất kỳ phần tử DOM cụ thể nào.
+
+### `scroll-sync`
+Phiên bản tối ưu hóa của sự kiện cuộn. Nó sử dụng `requestAnimationFrame` để đồng bộ hóa việc gọi hàm xử lý với tốc độ làm mới màn hình, ngăn chặn hiện tượng "giật" trong các tính toán nặng trong quá trình cuộn.

package/src/media/functional/functional/classes/GeoFlagRef/GeoFlagRef.en.mdx

@@ -0,0 +1,79 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Classes/GeoFlagRef - Reactive Country Flag Management'/>
+
+# GeoFlagRef Class
+
+A class for working with country flags in a reactive way. Ensures flag data stays synchronized with a reactive country code.
+
+## Key Features
+
+- **Reactivity** — automatic data updates when the country code changes.
+- **Multiple Country Support** — retrieve information for multiple countries at once.
+- **National Names** — get country names in their native language.
+
+## Initialization
+
+Creates a new `GeoFlagRef` instance for working with country flags. The class acts as a reactive wrapper around `GeoFlag` and automatically updates data when the provided country code changes.
+
+**Parameters:**
+- `code: RefOrNormal<string>` — the country code (e.g., `'RU'`, `'US'`). Can be a regular string or a reactive `ref` object. Defaults to the current location via `Geo.getLocation()`.
+
+```typescript
+import { GeoFlagRef } from '@dxtmisha/functional'
+import { ref } from 'vue'
+
+// 1. Initialization with a reactive code
+const code = ref('US')
+const geoFlag = new GeoFlagRef(code)
+
+// 2. Using flag data
+const flagIcon = geoFlag.getFlag() // ComputedRef with the icon for 'US'
+
+// 3. Automatic update
+code.value = 'FR' // flagIcon will update automatically
+```
+
+## State
+
+- `getCode(): Ref<string>` — Returns a reactive reference to the currently set country code.
+
+## Data Retrieval
+
+All data retrieval methods return `ComputedRef`, ensuring automatic synchronization with the current country code.
+
+- `get(code?: string): ComputedRef<GeoFlagItem | undefined>` — Returns comprehensive information about a country: name, icon, and other metadata. If `code` is not provided, the current code from the state is used.
+- `getFlag(code?: string): ComputedRef<string | undefined>` — Returns the flag icon path or identifier for the specified country.
+- `getList(codes?: string[]): ComputedRef<GeoFlagItem[]>` — Returns an array of flag data for a list of codes.
+- `getNational(codes?: string[]): ComputedRef<GeoFlagNational[]>` — Returns a list of countries with names in their national languages.
+
+## Working with Lists: getList vs getNational
+
+The class provides two methods for retrieving country lists, which differ in how the data is localized.
+
+### `getList` (Local List)
+Returns a list of countries where all names and labels are translated into the language of the **current `GeoFlagRef` instance**.
+- **When to use:** when you need to display a list of countries in the UI in the user's language (e.g., in a country selector).
+- **Result:** if `GeoFlagRef` is set to English (`EN`), you will get "Russia" for the code `RU`.
+
+### `getNational` (National List)
+Returns a list where information about each country is presented in its **native (national) language**.
+- **When to use:** when you need to show country names as they are called by the residents of those countries, or add a description in the native language.
+- **Result:** for the code `US`, you will get "United States" (in English), and for `VN`, you will get "Việt Nam" (in Vietnamese), regardless of the language set in `GeoFlagRef`.
+
+## Types
+
+### GeoFlagItem
+An object containing basic information about a country and its flag.
+- `language: string` — Language name.
+- `country: string` — Country name.
+- `standard: string` — Standard locale code.
+- `icon?: string` — Flag icon identifier.
+- `label: string` — Display label (usually the country name).
+- `value: string` — Selection value (usually the country code).
+
+### GeoFlagNational
+An extended object with national language information (inherits all fields from `GeoFlagItem`).
+- `description: string` — Description in the national language.
+- `nationalLanguage: string` — Language name in its native language.
+- `nationalCountry: string` — Country name in its native language.

package/src/media/functional/functional/classes/GeoFlagRef/GeoFlagRef.ru.mdx

@@ -0,0 +1,79 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Classes/GeoFlagRef - Реактивное управление флагами стран'/>
+
+# Класс GeoFlagRef
+
+Класс для реактивной работы с флагами стран. Обеспечивает синхронизацию данных о флагах с реактивным кодом страны.
+
+## Ключевые особенности
+
+- **Реактивность** — автоматическое обновление данных при изменении кода страны.
+- **Поддержка списка стран** — получение информации о нескольких странах одновременно.
+- **Национальные названия** — получение названий стран на их родном языке.
+
+## Инициализация
+
+Создает новый экземпляр `GeoFlagRef` для работы с флагами стран. Класс является реактивной оберткой над `GeoFlag` и автоматически обновляет данные при изменении переданного кода страны.
+
+**Параметры:**
+- `code: RefOrNormal<string>` — код страны (например, `'RU'`, `'US'`). Может быть обычной строкой или реактивным объектом `ref`. По умолчанию используется текущее местоположение через `Geo.getLocation()`.
+
+```typescript
+import { GeoFlagRef } from '@dxtmisha/functional'
+import { ref } from 'vue'
+
+// 1. Инициализация с реактивным кодом
+const code = ref('RU')
+const geoFlag = new GeoFlagRef(code)
+
+// 2. Использование данных флага
+const flagIcon = geoFlag.getFlag() // ComputedRef с иконкой для 'RU'
+
+// 3. Автоматическое обновление
+code.value = 'US' // flagIcon обновится автоматически
+```
+
+## Текущее состояние
+
+- `getCode(): Ref<string>` — Возвращает реактивную ссылку на текущий установленный код страны.
+
+## Получение данных
+
+Все методы получения данных возвращают `ComputedRef`, что обеспечивает автоматическую синхронизацию с текущим кодом страны.
+
+- `get(code?: string): ComputedRef<GeoFlagItem | undefined>` — Возвращает полную информацию о стране: название, иконку и другие метаданные. Если `code` не передан, используется текущий код из состояния.
+- `getFlag(code?: string): ComputedRef<string | undefined>` — Возвращает путь или идентификатор иконки флага для указанной страны.
+- `getList(codes?: string[]): ComputedRef<GeoFlagItem[]>` — Возвращает массив данных о флагах для списка кодов.
+- `getNational(codes?: string[]): ComputedRef<GeoFlagNational[]>` — Возвращает список стран с названиями на их национальных языках.
+
+## Работа со списками: getList vs getNational
+
+Класс предоставляет два метода для получения списков стран, которые различаются способом локализации данных.
+
+### `getList` (Локальный список)
+Возвращает список стран, где все названия и метки переведены на язык **текущего экземпляра** `GeoFlagRef`.
+- **Когда использовать:** если вам нужно отобразить список стран в интерфейсе на языке пользователя (например, в селекторе выбора страны).
+- **Результат:** если `GeoFlagRef` настроен на русский (`RU`), то для кода `US` вы получите "Соединённые Штаты".
+
+### `getNational` (Национальный список)
+Возвращает список, где информация о каждой стране представлена на её **родном (национальном) языке**.
+- **Когда использовать:** если вам нужно показать названия стран так, как их называют жители этих стран, или добавить описание на родном языке.
+- **Результат:** для кода `US` вы получите "United States" (на английском), для `VN` — "Việt Nam" (на вьетнамском), независимо от того, какой язык установлен в `GeoFlagRef`.
+
+## Типы
+
+### GeoFlagItem
+Объект с основной информацией о стране и её флаге.
+- `language: string` — Название языка.
+- `country: string` — Название страны.
+- `standard: string` — Стандартный код локали.
+- `icon?: string` — Идентификатор иконки флага.
+- `label: string` — Отображаемая метка (обычно название страны).
+- `value: string` — Значение для выбора (обычно код страны).
+
+### GeoFlagNational
+Расширенный объект с информацией на национальном языке (наследует все поля `GeoFlagItem`).
+- `description: string` — Описание на национальном языке.
+- `nationalLanguage: string` — Название языка на национальном языке.
+- `nationalCountry: string` — Название страны на национальном языке.

package/src/media/functional/functional/classes/GeoFlagRef/GeoFlagRef.vi.mdx

@@ -0,0 +1,79 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Classes/GeoFlagRef - Quản lý cờ quốc gia phản ứng'/>
+
+# Lớp GeoFlagRef
+
+Một lớp để làm việc với cờ quốc gia theo cách phản ứng. Đảm bảo dữ liệu cờ luôn được đồng bộ với mã quốc gia phản ứng.
+
+## Các tính năng chính
+
+- **Tính phản ứng** — tự động cập nhật dữ liệu khi mã quốc gia thay đổi.
+- **Hỗ trợ nhiều quốc gia** — lấy thông tin cho nhiều quốc gia cùng một lúc.
+- **Tên quốc gia bản ngữ** — lấy tên quốc gia bằng ngôn ngữ bản địa của họ.
+
+## Khởi tạo
+
+Tạo một thực thể `GeoFlagRef` mới để làm việc với cờ quốc gia. Lớp này hoạt động như một lớp vỏ bọc phản ứng (reactive wrapper) xung quanh `GeoFlag` và tự động cập nhật dữ liệu khi mã quốc gia được cung cấp thay đổi.
+
+**Tham số:**
+- `code: RefOrNormal<string>` — mã quốc gia (ví dụ: `'VN'`, `'US'`). Có thể là một chuỗi thông thường hoặc một đối tượng `ref` phản ứng. Mặc định là vị trí hiện tại thông qua `Geo.getLocation()`.
+
+```typescript
+import { GeoFlagRef } from '@dxtmisha/functional'
+import { ref } from 'vue'
+
+// 1. Khởi tạo với mã phản ứng
+const code = ref('VN')
+const geoFlag = new GeoFlagRef(code)
+
+// 2. Sử dụng dữ liệu cờ
+const flagIcon = geoFlag.getFlag() // ComputedRef với biểu tượng cho 'VN'
+
+// 3. Tự động cập nhật
+code.value = 'JP' // flagIcon sẽ tự động cập nhật
+```
+
+## Trạng thái
+
+- `getCode(): Ref<string>` — Trả về một tham chiếu phản ứng đến mã quốc gia hiện đang được thiết lập.
+
+## Truy xuất dữ liệu
+
+Tất cả các phương thức truy xuất dữ liệu đều trả về `ComputedRef`, đảm bảo đồng bộ hóa tự động với mã quốc gia hiện tại.
+
+- `get(code?: string): ComputedRef<GeoFlagItem | undefined>` — Trả về thông tin chi tiết về một quốc gia: tên, biểu tượng và các siêu dữ liệu khác. Nếu không cung cấp `code`, mã hiện tại từ trạng thái sẽ được sử dụng.
+- `getFlag(code?: string): ComputedRef<string | undefined>` — Trả về đường dẫn hoặc định danh biểu tượng cờ cho quốc gia được chỉ định.
+- `getList(codes?: string[]): ComputedRef<GeoFlagItem[]>` — Trả về một mảng dữ liệu cờ cho danh sách các mã.
+- `getNational(codes?: string[]): ComputedRef<GeoFlagNational[]>` — Trả về danh sách các quốc gia với tên bằng ngôn ngữ bản địa của họ.
+
+## Làm việc với danh sách: getList vs getNational
+
+Lớp cung cấp hai phương thức để lấy danh sách các quốc gia, chúng khác nhau ở cách bản địa hóa dữ liệu.
+
+### `getList` (Danh sách địa phương)
+Trả về danh sách các quốc gia trong đó tất cả các tên và nhãn được dịch sang ngôn ngữ của **thực thể `GeoFlagRef` hiện tại**.
+- **Khi nào nên sử dụng:** khi bạn cần hiển thị danh sách các quốc gia trong giao diện người dùng bằng ngôn ngữ của người dùng (ví dụ: trong bộ chọn quốc gia).
+- **Kết quả:** nếu `GeoFlagRef` được thiết lập là tiếng Việt (`VN`), bạn sẽ nhận được "Nga" cho mã `RU`.
+
+### `getNational` (Danh sách quốc gia)
+Trả về danh sách trong đó thông tin về mỗi quốc gia được trình bày bằng **ngôn ngữ bản địa (quốc gia) của quốc gia đó**.
+- **Khi nào nên sử dụng:** khi bạn cần hiển thị tên các quốc gia theo cách gọi của cư dân các quốc gia đó, hoặc thêm mô tả bằng ngôn ngữ bản địa.
+- **Kết quả:** cho mã `US`, bạn sẽ nhận được "United States" (bằng tiếng Anh) và cho mã `VN`, bạn sẽ nhận được "Việt Nam" (bằng tiếng Việt), bất kể ngôn ngữ được thiết lập trong `GeoFlagRef`.
+
+## Các kiểu
+
+### GeoFlagItem
+Một đối tượng chứa thông tin cơ bản về một quốc gia và cờ của quốc gia đó.
+- `language: string` — Tên ngôn ngữ.
+- `country: string` — Tên quốc gia.
+- `standard: string` — Mã locale tiêu chuẩn.
+- `icon?: string` — Định danh biểu tượng cờ.
+- `label: string` — Nhãn hiển thị (thường là tên quốc gia).
+- `value: string` — Giá trị để lựa chọn (thường là mã quốc gia).
+
+### GeoFlagNational
+Một đối tượng mở rộng với thông tin ngôn ngữ bản địa (kế thừa tất cả các trường từ `GeoFlagItem`).
+- `description: string` — Mô tả bằng ngôn ngữ bản địa.
+- `nationalLanguage: string` — Tên ngôn ngữ bằng chính ngôn ngữ đó.
+- `nationalCountry: string` — Tên quốc gia bằng chính ngôn ngữ đó.