@dxtmisha/wiki 0.39.1 → 0.39.2

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

@@ -0,0 +1,42 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Classes/EffectScopeGlobal - Global Reactive Scope'/>
+
+# EffectScopeGlobal Class
+
+A utility class that provides a global, detached Vue `effectScope`. This allows running reactive effects (watchers, computed properties) that are not tied to any specific component lifecycle, ensuring they aren't automatically disposed of when a component unmounts.
+
+The scope is initialized lazily upon the first call to `run`, and it is created as a "detached" scope (`effectScope(true)`), meaning it will not be captured by any parent scope.
+
+## Key Features
+
+- **Global Persistence** — effects live as long as the application does.
+- **Detached Scope** — created with `effectScope(true)`, preventing accidental disposal by parent scopes.
+- **Lazy Initialization** — the internal scope is created only when first needed.
+- **Scope Management** — groups global reactive effects together for organized disposal if needed (via the internal scope).
+- **Ease of Use** — simple static method to run any reactive function.
+
+## Actions
+
+### `run`
+
+Executes the provided function within the global effect scope.
+
+**Parameters:**
+- `fn: () => T` — the function to execute (typically containing reactive logic like `watch` or `computed`).
+
+**Returns:** `T | undefined`
+
+```typescript
+import { EffectScopeGlobal } from '@dxtmisha/functional'
+import { watch, ref } from 'vue'
+
+const globalState = ref(0)
+
+// This watcher will persist even if the component that created it is unmounted
+EffectScopeGlobal.run(() => {
+  watch(globalState, (val) => {
+    console.log('Global state changed:', val)
+  })
+})
+```

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

@@ -0,0 +1,42 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Classes/EffectScopeGlobal - Глобальная реактивная область'/>
+
+# Класс EffectScopeGlobal
+
+Утилитарный класс, предоставляющий глобальную, отсоединенную (detached) область `effectScope` Vue. Это позволяет запускать реактивные эффекты (watchers, computed properties), которые не привязаны к жизненному циклу конкретного компонента, гарантируя, что они не будут автоматически удалены при размонтировании компонента.
+
+Область инициализируется лениво при первом вызове `run` и создается как «отсоединенная» (`effectScope(true)`), что означает, что она не будет захвачена никакой родительской областью.
+
+## Ключевые особенности
+
+- **Глобальная устойчивость** — эффекты живут столько же, сколько и приложение.
+- **Отсоединенная область** — создается с помощью `effectScope(true)`, что предотвращает случайное удаление родительскими областями.
+- **Ленивая инициализация** — внутренняя область создается только при первой необходимости.
+- **Управление областью** — группирует глобальные реактивные эффекты вместе для организованного управления.
+- **Простота использования** — простой статический метод для запуска любой реактивной функции.
+
+## Действия
+
+### `run`
+
+Запускает переданную функцию в глобальной области действия эффекта.
+
+**Параметры:**
+- `fn: () => T` — выполняемая функция (обычно содержащая реактивную логику, такую как `watch` или `computed`).
+
+**Возвращает:** `T | undefined`
+
+```typescript
+import { EffectScopeGlobal } from '@dxtmisha/functional'
+import { watch, ref } from 'vue'
+
+const globalState = ref(0)
+
+// Этот watcher будет сохраняться, даже если создавший его компонент будет размонтирован
+EffectScopeGlobal.run(() => {
+  watch(globalState, (val) => {
+    console.log('Глобальное состояние изменилось:', val)
+  })
+})
+```

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

@@ -0,0 +1,42 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Classes/EffectScopeGlobal - Phạm vi hiệu ứng toàn cục'/>
+
+# Lớp EffectScopeGlobal
+
+Một lớp tiện ích cung cấp `effectScope` Vue toàn cục và tách biệt (detached). Điều này cho phép chạy các hiệu ứng phản ứng (watchers, computed properties) không bị ràng buộc vào vòng đời của bất kỳ thành phần cụ thể nào, đảm bảo chúng không tự động bị hủy khi một thành phần bị gỡ bỏ (unmount).
+
+Phạm vi được khởi tạo lười biếng (lazy) khi gọi `run` lần đầu tiên và được tạo dưới dạng phạm vi "tách biệt" (`effectScope(true)`), có nghĩa là nó sẽ không bị nắm giữ bởi bất kỳ phạm vi cha nào.
+
+## Các tính năng chính
+
+- **Sự tồn tại toàn cục** — các hiệu ứng tồn tại cùng với ứng dụng.
+- **Phạm vi tách biệt** — được tạo với `effectScope(true)`, ngăn chặn việc bị hủy vô tình bởi các phạm vi cha.
+- **Khởi tạo lười biếng** — phạm vi nội bộ chỉ được tạo khi cần thiết lần đầu tiên.
+- **Quản lý phạm vi** — nhóm các hiệu ứng phản ứng toàn cục lại với nhau để quản lý có tổ chức.
+- **Dễ sử dụng** — phương thức tĩnh đơn giản để chạy bất kỳ hàm phản ứng nào.
+
+## Hành động
+
+### `run`
+
+Thực thi hàm được cung cấp trong phạm vi hiệu ứng toàn cục.
+
+**Tham số:**
+- `fn: () => T` — hàm cần thực thi (thường chứa logic phản ứng như `watch` hoặc `computed`).
+
+**Giá trị trả về:** `T | undefined`
+
+```typescript
+import { EffectScopeGlobal } from '@dxtmisha/functional'
+import { watch, ref } from 'vue'
+
+const globalState = ref(0)
+
+// Trình theo dõi (watcher) này sẽ tồn tại ngay cả khi thành phần tạo ra nó được gỡ bỏ
+EffectScopeGlobal.run(() => {
+  watch(globalState, (val) => {
+    console.log('Trạng thái toàn cục thay đổi:', val)
+  })
+})
+```

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` — Название страны на национальном языке.