@dxtmisha/wiki 0.25.1 → 0.39.2

package/src/media/functional/functional/functions/setRef/setRef.ru.mdx

@@ -0,0 +1,27 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Functions/setRef - Обновление значения'/>
+
+# `setRef`
+
+Утилитарная функция, которая обновляет значение реактивной переменной `Ref`. Она включает встроенную проверку, гарантирующую, что обновление происходит только в том случае, если новое значение отличается от текущего, что предотвращает лишние срабатывания реактивности.
+
+**Параметры:**
+- `item: Ref<T>` — Реактивный элемент (`Ref`) для обновления.
+- `value: T` — Новое значение для присвоения `Ref`.
+
+**Возвращает:**
+`void`
+
+```typescript
+import { ref } from 'vue'
+import { setRef } from '@dxtmisha/functional'
+
+const status = ref('idle')
+
+// Обновляет значение на 'loading'
+setRef(status, 'loading')
+
+// Этот вызов будет проигнорирован, так как значение уже 'loading'
+setRef(status, 'loading')
+```

package/src/media/functional/functional/functions/setRef/setRef.vi.mdx

@@ -0,0 +1,27 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Functions/setRef - Cập nhật giá trị'/>
+
+# `setRef`
+
+Một hàm tiện ích cập nhật giá trị của một `Ref` phản ứng. Nó bao gồm một kiểm tra tích hợp để đảm bảo rằng việc cập nhật chỉ xảy ra nếu giá trị mới khác với giá trị hiện tại, ngăn chặn các kích hoạt phản ứng không cần thiết.
+
+**Tham số:**
+- `item: Ref<T>` — Phần tử `Ref` phản ứng cần được cập nhật.
+- `value: T` — Giá trị mới để gán cho `Ref`.
+
+**Trả về:**
+`void`
+
+```typescript
+import { ref } from 'vue'
+import { setRef } from '@dxtmisha/functional'
+
+const status = ref('idle')
+
+// Cập nhật giá trị thành 'loading'
+setRef(status, 'loading')
+
+// Cuộc gọi này sẽ bị bỏ qua vì giá trị đã là 'loading'
+setRef(status, 'loading')
+```

package/src/media/functional/functional/functions/toBind/toBind.en.mdx

@@ -0,0 +1,38 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Functions/toBind - Deep Property Merging'/>
+
+# `toBind`
+
+Merges two property objects while intelligently handling `class` and `style` properties. If both objects contain classes or styles, they are combined into an array to prevent overwriting. Other properties from the second object (`value`) will overwrite those in the first object (`extra`).
+
+### How it works (Merging Mechanism)
+
+The function takes two objects and returns a new object by merging their properties according to the following rules:
+
+1. **Standard Properties:** Properties from the second object (`value`) will overwrite properties with the same name from the first object (`extra`). This is the standard behavior of the spread operator (`...`).
+2. **`class` Property:** If the `class` property is present in **only one** of the objects, it is kept as is. However, if a class is specified in **both** objects, the function does not overwrite them; instead, it combines them into an array `[extra.class, value.class]`. This ensures all classes passed to the component are preserved.
+3. **`style` Property:** Works similarly to classes. The presence of styles in both objects will result in them being combined into an array `[extra.style, value.style]`, which is necessary for correct style application in Vue.
+
+**Parameters:**
+- `extra: ItemList` — The base property object (e.g., default or internal properties).
+- `value: ItemList` — The property object to be merged into the base (e.g., user-provided properties).
+
+**Returns:**
+`ConstrBind<R>` — The merged properties object.
+
+```typescript
+import { toBind } from '@dxtmisha/functional'
+
+const base = { class: 'btn', style: { color: 'red' }, id: 'my-btn' }
+const mod = { class: 'btn--large', style: { margin: '10px' }, id: 'primary-btn' }
+
+const result = toBind(base, mod)
+/* 
+Result: { 
+  id: 'primary-btn', 
+  class: ['btn', 'btn--large'], 
+  style: [{ color: 'red' }, { margin: '10px' }] 
+}
+*/
+```

package/src/media/functional/functional/functions/toBind/toBind.ru.mdx

@@ -0,0 +1,38 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Functions/toBind - Глубокое объединение свойств'/>
+
+# `toBind`
+
+Объединяет два объекта свойств, интеллектуально обрабатывая свойства `class` и `style`. Если оба объекта содержат классы или стили, они объединяются в массив для предотвращения перезаписи. Другие свойства из второго объекта (`value`) перезапишут свойства в первом объекте (`extra`).
+
+### Как это работает (Механизм слияния)
+
+Функция принимает два объекта и возвращает новый объект, объединяя их свойства по следующим правилам:
+
+1. **Обычные свойства:** Свойства из второго объекта (`value`) заменяют свойства с таким же именем из первого объекта (`extra`). Это стандартное поведение оператора spread (`...`).
+2. **Свойство `class`:** Если свойство `class` присутствует **только в одном** из объектов, оно переносится как есть. Если же класс указан **в обоих** объектах, функция не перезаписывает их, а объединяет в массив `[extra.class, value.class]`. Это позволяет сохранить все классы, переданные в компонент.
+3. **Свойство `style`:** Работает аналогично классам. Присутствие стилей в обоих объектах приведет к их объединению в массив `[extra.style, value.style]`, что необходимо для корректного применения всех стилей средствами Vue.
+
+**Параметры:**
+- `extra: ItemList` — Базовый объект свойств (например, свойства по умолчанию или внутренние).
+- `value: ItemList` — Объект свойств для объединения с базовым (например, пользовательские свойства).
+
+**Возвращает:**
+`ConstrBind<R>` — Объединенный объект свойств.
+
+```typescript
+import { toBind } from '@dxtmisha/functional'
+
+const base = { class: 'btn', style: { color: 'red' }, id: 'my-btn' }
+const mod = { class: 'btn--large', style: { margin: '10px' }, id: 'primary-btn' }
+
+const result = toBind(base, mod)
+/* 
+Результат: { 
+  id: 'primary-btn', 
+  class: ['btn', 'btn--large'], 
+  style: [{ color: 'red' }, { margin: '10px' }] 
+}
+*/
+```

package/src/media/functional/functional/functions/toBind/toBind.vi.mdx

@@ -0,0 +1,38 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Functions/toBind - Hợp nhất thuộc tính sâu'/>
+
+# `toBind`
+
+Hợp nhất hai đối tượng thuộc tính trong khi xử lý thông minh các thuộc tính `class` và `style`. Nếu cả hai đối tượng đều chứa class hoặc style, chúng sẽ được kết hợp thành một mảng để tránh bị ghi đè. Các thuộc tính khác từ đối tượng thứ hai (`value`) sẽ ghi đè lên các thuộc tính trong đối tượng thứ nhất (`extra`).
+
+### Cơ chế hoạt động (Cơ chế hợp nhất)
+
+Hàm nhận hai đối tượng và trả về một đối tượng mới bằng cách hợp nhất các thuộc tính của chúng theo các quy tắc sau:
+
+1. **Thuộc tính tiêu chuẩn:** Các thuộc tính từ đối tượng thứ hai (`value`) sẽ ghi đè các thuộc tính có cùng tên từ đối tượng thứ nhất (`extra`). Đây là hành vi tiêu chuẩn của toán tử spread (`...`).
+2. **Thuộc tính `class`:** Nếu thuộc tính `class` chỉ có mặt trong **một** trong các đối tượng, nó sẽ được giữ nguyên. Tuy nhiên, nếu class được chỉ định ở **cả hai** đối tượng, hàm sẽ không ghi đè chúng; thay vào đó, nó kết hợp chúng thành một mảng `[extra.class, value.class]`. Điều này giúp đảm bảo tất cả các class được truyền vào thành phần đều được giữ lại.
+3. **Thuộc tính `style`:** Hoạt động tương tự như các class. Sự hiện diện của style trong cả hai đối tượng sẽ dẫn đến việc chúng được kết hợp thành một mảng `[extra.style, value.style]`, điều này cần thiết để áp dụng style chính xác trong Vue.
+
+**Tham số:**
+- `extra: ItemList` — Đối tượng thuộc tính cơ sở (ví dụ: thuộc tính mặc định hoặc nội bộ).
+- `value: ItemList` — Đối tượng thuộc tính cần hợp nhất vào cơ sở (ví dụ: thuộc tính do người dùng cung cấp).
+
+**Trả về:**
+`ConstrBind<R>` — Đối tượng thuộc tính đã được hợp nhất.
+
+```typescript
+import { toBind } from '@dxtmisha/functional'
+
+const base = { class: 'btn', style: { color: 'red' }, id: 'my-btn' }
+const mod = { class: 'btn--large', style: { margin: '10px' }, id: 'primary-btn' }
+
+const result = toBind(base, mod)
+/* 
+Kết quả: { 
+  id: 'primary-btn', 
+  class: ['btn', 'btn--large'], 
+  style: [{ color: 'red' }, { margin: '10px' }] 
+}
+*/
+```

package/src/media/functional/functional/functions/toBinds/toBinds.en.mdx

@@ -0,0 +1,32 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Functions/toBinds - Multi-Object Property Merging'/>
+
+# `toBinds`
+
+Merges multiple property objects sequentially using `toBind`. This function is useful for combining multiple layers of properties (e.g., defaults, component props, and state-driven modifiers) while ensuring `class` and `style` properties are correctly combined rather than overwritten.
+
+**Parameters:**
+- `...values: (ItemList | undefined)[]` — A list of property objects to merge.
+
+**Returns:**
+`ConstrBind<R>` — The final merged properties object.
+
+```typescript
+import { toBinds } from '@dxtmisha/functional'
+
+const defaults = { class: 'btn', id: 'gen-id' }
+const props = { class: 'btn--primary', title: 'Click me' }
+const state = { class: 'is-loading', style: { opacity: 0.5 } }
+
+const finalBind = toBinds(defaults, props, state)
+/* 
+Result: { 
+  id: 'gen-id', 
+  title: 'Click me',
+  class: [['btn', 'btn--primary'], 'is-loading'], 
+  style: { opacity: 0.5 } 
+}
+Note: nesting depth of classes depends on implementation of toBind.
+*/
+```

package/src/media/functional/functional/functions/toBinds/toBinds.ru.mdx

@@ -0,0 +1,31 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Functions/toBinds - Объединение нескольких объектов свойств'/>
+
+# `toBinds`
+
+Последовательно объединяет несколько объектов свойств с помощью `toBind`. Эта функция полезна для объединения нескольких уровней свойств (например, значений по умолчанию, свойств компонентов и модификаторов состояния), гарантируя правильное объединение свойств `class` и `style`, а не их перезапись.
+
+**Параметры:**
+- `...values: (ItemList | undefined)[]` — Список объектов свойств для объединения.
+
+**Возвращает:**
+`ConstrBind<R>` — Конечный объединенный объект свойств.
+
+```typescript
+import { toBinds } from '@dxtmisha/functional'
+
+const defaults = { class: 'btn', id: 'gen-id' }
+const props = { class: 'btn--primary', title: 'Нажми меня' }
+const state = { class: 'is-loading', style: { opacity: 0.5 } }
+
+const finalBind = toBinds(defaults, props, state)
+/* 
+Результат: { 
+  id: 'gen-id', 
+  title: 'Нажми меня',
+  class: [['btn', 'btn--primary'], 'is-loading'], 
+  style: { opacity: 0.5 } 
+}
+*/
+```

package/src/media/functional/functional/functions/toBinds/toBinds.vi.mdx

@@ -0,0 +1,31 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Functions/toBinds - Hợp nhất nhiều đối tượng thuộc tính'/>
+
+# `toBinds`
+
+Hợp nhất tuần tự nhiều đối tượng thuộc tính bằng cách sử dụng `toBind`. Hàm này hữu ích để kết hợp nhiều lớp thuộc tính (ví dụ: mặc định, props của thành phần và các modifier dựa trên trạng thái) trong khi đảm bảo các thuộc tính `class` và `style` được kết hợp chính xác thay vì bị ghi đè.
+
+**Tham số:**
+- `...values: (ItemList | undefined)[]` — Danh sách các đối tượng thuộc tính cần hợp nhất.
+
+**Trả về:**
+`ConstrBind<R>` — Đối tượng thuộc tính đã hợp nhất cuối cùng.
+
+```typescript
+import { toBinds } from '@dxtmisha/functional'
+
+const defaults = { class: 'btn', id: 'gen-id' }
+const props = { class: 'btn--primary', title: 'Nhấp vào tôi' }
+const state = { class: 'is-loading', style: { opacity: 0.5 } }
+
+const finalBind = toBinds(defaults, props, state)
+/* 
+Kết quả: { 
+  id: 'gen-id', 
+  title: 'Nhấp vào tôi',
+  class: [['btn', 'btn--primary'], 'is-loading'], 
+  style: { opacity: 0.5 } 
+}
+*/
+```

package/src/media/functional/functional/functions/toRefItem/toRefItem.en.mdx

@@ -0,0 +1,27 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Functions/toRefItem - Reactive Ref Normalization'/>
+
+# `toRefItem`
+
+A utility function that ensures a value is a reactive `Ref`. If the input is already a `Ref`, it is returned as is. If the input is an ordinary value, it is wrapped in a new `Ref`. This is useful for functions that expect a reactive reference as an argument.
+
+**Parameters:**
+- `item: RefOrNormal<T>` — A reactive variable (`Ref`) or an ordinary value.
+
+**Returns:**
+`Ref<T>` — A reactive `Ref` containing the value.
+
+```typescript
+import { ref } from 'vue'
+import { toRefItem } from '@dxtmisha/functional'
+
+const existingRef = ref(10)
+const ordinaryValue = 20
+
+const normalized1 = toRefItem(existingRef)   // Returns original ref
+const normalized2 = toRefItem(ordinaryValue) // Returns new ref(20)
+
+console.log(normalized1.value) // 10
+console.log(normalized2.value) // 20
+```

package/src/media/functional/functional/functions/toRefItem/toRefItem.ru.mdx

@@ -0,0 +1,27 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Functions/toRefItem - Нормализация реактивной переменной Ref'/>
+
+# `toRefItem`
+
+Утилитарная функция, которая гарантирует, что значение является реактивной переменной `Ref`. Если входное значение уже является `Ref`, оно возвращается как есть. Если входное значение является обычным значением, оно оборачивается в новую переменную `Ref`. Это полезно для функций, которые ожидают реактивную ссылку в качестве аргумента.
+
+**Параметры:**
+- `item: RefOrNormal<T>` — Реактивная переменная (`Ref`) или обычное значение.
+
+**Возвращает:**
+`Ref<T>` — Реактивная переменная `Ref`, содержащая значение.
+
+```typescript
+import { ref } from 'vue'
+import { toRefItem } from '@dxtmisha/functional'
+
+const existingRef = ref(10)
+const ordinaryValue = 20
+
+const normalized1 = toRefItem(existingRef)   // Возвращает исходный ref
+const normalized2 = toRefItem(ordinaryValue) // Возвращает новый ref(20)
+
+console.log(normalized1.value) // 10
+console.log(normalized2.value) // 20
+```

package/src/media/functional/functional/functions/toRefItem/toRefItem.vi.mdx

@@ -0,0 +1,27 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Functions/toRefItem - Chuẩn hóa Ref phản ứng'/>
+
+# `toRefItem`
+
+Một hàm tiện ích đảm bảo một giá trị là một `Ref` phản ứng. Nếu đầu vào đã là một `Ref`, nó sẽ được trả về nguyên trạng. Nếu đầu vào là một giá trị thông thường, nó sẽ được bao bọc trong một `Ref` mới. Điều này hữu ích cho các hàm mong đợi một tham chiếu phản ứng làm đối số.
+
+**Tham số:**
+- `item: RefOrNormal<T>` — Một biến phản ứng (`Ref`) hoặc một giá trị thông thường.
+
+**Trả về:**
+`Ref<T>` — Một `Ref` phản ứng chứa giá trị.
+
+```typescript
+import { ref } from 'vue'
+import { toRefItem } from '@dxtmisha/functional'
+
+const existingRef = ref(10)
+const ordinaryValue = 20
+
+const normalized1 = toRefItem(existingRef)   // Trả về ref gốc
+const normalized2 = toRefItem(ordinaryValue) // Trả về ref(20) mới
+
+console.log(normalized1.value) // 10
+console.log(normalized2.value) // 20
+```

package/src/media/functional/functional/list-data/list-data.en.mdx

@@ -0,0 +1,80 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/# List Management'/>
+
+# List Management
+
+The **ListDataRef** class is a controller for managing complex data lists, dropdown menus, and trees within the **Vue 3** ecosystem. It automates routine tasks such as filtering, item selection, focus management, and working with nested structures.
+
+## Initialization and Data
+
+The controller takes reactive data sources and provides optimized property sets for rendering components.
+
+```javascript
+import { ref } from 'vue'
+import { ListDataRef } from '@dxtmisha/functional'
+
+const items = ref([{ value: 1, label: 'Item' }, ...])
+const controller = new ListDataRef(items)
+
+// 1. Full data set for rendering (with focus/selected/disabled states)
+const list = controller.fullData 
+
+// 2. Optimized list (liteData)
+// Automatically simplifies structure for very large data volumes
+const fastList = controller.liteData 
+
+// 3. Flat map of all items (including nested ones)
+const flatMap = controller.map
+```
+
+## Selection and State
+
+Automatic management of multiple or single selection, taking into account limits and the current locale state.
+
+```javascript
+const selected = ref([1])
+// Use undefined to skip optional arguments and trigger default values
+const controller = new ListDataRef(items, undefined, undefined, undefined, undefined, selected)
+
+// 1. Retrieving selected values and names
+controller.selectedValues // ComputedRef<[1]>
+controller.selectedNames  // ComputedRef<['Item']>
+
+// 2. Checking limits (min/max)
+controller.isSelectedMax  // True if the maximum allowed quantity is selected
+```
+
+## Navigation and Focus
+
+The controller provides a system of methods for "smart" movement through the list. Navigation automatically skips inactive elements and group headers, working only with items available for selection.
+
+```javascript
+const focus = ref(1)
+const controller = new ListDataRef(items, focus)
+
+// 1. Focus and Search states
+controller.isFocus()        // Verification of current focus correctness
+controller.isHighlight()    // Check if there are search matches
+controller.highlightFirstItem // Index of the first matching item
+
+// 2. Relative navigation (from selected item)
+const next = controller.getSelectedNext() // Index of the next available item
+const prev = controller.getSelectedPrev() // Index of the previous available item
+
+// 3. Free navigation (by steps or objects)
+const item = controller.getItemByStep(currentItem, 2) // Jump 2 items from current
+const firstInGroup = controller.getFirstItemByParent('group-id') // First in group
+```
+
+## Working with Nesting
+
+To handle groups or tree-like structures, the `getSubList()` method is used. It creates a new controller instance for the nested data while maintaining a global link to focus and selection states.
+
+```javascript
+// Inside a group component or dropdown menu:
+const subController = controller.getSubList(groupItem)
+
+// subController will automatically monitor changes in the parent list
+const subItems = subController.fullData
+```

package/src/media/functional/functional/list-data/list-data.ru.mdx

@@ -0,0 +1,80 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/# Управление списками'/>
+
+# Управление списками
+
+Класс **ListDataRef** — это контроллер для управления сложными списками данных, выпадающими меню и деревьями в экосистеме **Vue 3**. Он автоматизирует рутинные задачи по фильтрации, выделению элементов, управлению фокусом и работе со вложенными структурами.
+
+## Инициализация и Данные
+
+Контроллер принимает реактивные источники данных и предоставляет оптимизированные наборы свойств для отрисовки компонентов.
+
+```javascript
+import { ref } from 'vue'
+import { ListDataRef } from '@dxtmisha/functional'
+
+const items = ref([{ value: 1, label: 'Пункт' }, ...])
+const controller = new ListDataRef(items)
+
+// 1. Полный набор данных для отрисовки (с состоянием focus/selected/disabled)
+const list = controller.fullData 
+
+// 2. Оптимизированный список (liteData)
+// Автоматически упрощает структуру при очень больших объемах данных
+const fastList = controller.liteData 
+
+// 3. Плоская карта всех элементов (включая вложенные)
+const flatMap = controller.map
+```
+
+## Выделение и Состояние
+
+Автоматическое управление множественным или одиночным выбором с учетом лимитов и текущего состояния локали.
+
+```javascript
+const selected = ref([1])
+// Чтобы пропустить необязательные аргументы, используйте undefined
+const controller = new ListDataRef(items, undefined, undefined, undefined, undefined, selected)
+
+// 1. Получение выбранных значений и названий
+controller.selectedValues // ComputedRef<[1]>
+controller.selectedNames  // ComputedRef<['Пункт']>
+
+// 2. Проверка лимитов (min/max)
+controller.isSelectedMax  // True, если выбрано максимально допустимое кол-во
+```
+
+## Навигация и Фокус
+
+Контроллер предоставляет систему методов для «умного» перемещения по списку. Навигация автоматически пропускает неактивные элементы и заголовки групп, работая только с доступными для выбора пунктами.
+
+```javascript
+const focus = ref(1)
+const controller = new ListDataRef(items, focus)
+
+// 1. Состояния фокуса и поиска
+controller.isFocus()        // Проверка корректности текущего фокуса
+controller.isHighlight()    // Есть ли совпадения при поиске
+controller.highlightFirstItem // Индекс первого найденного элемента
+
+// 2. Относительная навигация (от выделенного элемента)
+const next = controller.getSelectedNext() // Индекс следующего доступного пункта
+const prev = controller.getSelectedPrev() // Индекс предыдущего доступного пункта
+
+// 3. Свободная навигация (по шагам или объектам)
+const item = controller.getItemByStep(currentItem, 2) // Через 2 пункта от текущего
+const firstInGroup = controller.getFirstItemByParent('group-id') // Первый в группе
+```
+
+## Работа с вложенностью
+
+Для работы с группами или древовидными структурами используется метод `getSubList()`. Он создает новый экземпляр контроллера для вложенных данных, сохраняя общую связь с глобальным состоянием фокуса и выделения.
+
+```javascript
+// Внутри компонента группы или выпадающего меню:
+const subController = controller.getSubList(groupItem)
+
+// subController будет автоматически следить за изменениями в родительском списке
+const subItems = subController.fullData
+```

package/src/media/functional/functional/list-data/list-data.vi.mdx

@@ -0,0 +1,80 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/# Quản lý danh sách'/>
+
+# Quản lý danh sách
+
+Lớp **ListDataRef** là một trình điều khiển để quản lý các danh sách dữ liệu phức tạp, menu thả xuống và cây trong hệ sinh thái **Vue 3**. Nó tự động hóa các tác vụ định kỳ như lọc, chọn mục, quản lý tiêu điểm và làm việc với các cấu trúc lồng nhau.
+
+## Khởi tạo và Dữ liệu
+
+Trình điều khiển chấp nhận các nguồn dữ liệu phản hồi và cung cấp các bộ thuộc tính được tối ưu hóa để kết xuất các thành phần.
+
+```javascript
+import { ref } from 'vue'
+import { ListDataRef } from '@dxtmisha/functional'
+
+const items = ref([{ value: 1, label: 'Mục' }, ...])
+const controller = new ListDataRef(items)
+
+// 1. Bộ dữ liệu đầy đủ để kết xuất (với các trạng thái focus/selected/disabled)
+const list = controller.fullData 
+
+// 2. Danh sách tối ưu hóa (liteData)
+// Tự động đơn giản hóa cấu trúc cho khối lượng dữ liệu rất lớn
+const fastList = controller.liteData 
+
+// 3. Bản đồ phẳng của tất cả các mục (bao gồm cả các mục lồng nhau)
+const flatMap = controller.map
+```
+
+## Lựa chọn và Trạng thái
+
+Tự động quản lý lựa chọn nhiều hoặc một mục, có tính đến các giới hạn và trạng thái địa phương hiện tại.
+
+```javascript
+const selected = ref([1])
+// Sử dụng undefined để bỏ qua các đối số tùy chọn và kích hoạt các giá trị mặc định
+const controller = new ListDataRef(items, undefined, undefined, undefined, undefined, selected)
+
+// 1. Truy xuất các giá trị và tên đã chọn
+controller.selectedValues // ComputedRef<[1]>
+controller.selectedNames  // ComputedRef<['Mục']>
+
+// 2. Kiểm tra các giới hạn (min/max)
+controller.isSelectedMax  // True nếu số lượng tối đa cho phép được chọn
+```
+
+## Điều hướng và Tiêu điểm
+
+Trình điều khiển cung cấp một hệ thống các phương thức để di chuyển "thông minh" qua danh sách. Điều hướng tự động bỏ qua các phần tử không hoạt động và các tiêu đề nhóm, chỉ làm việc với các mục có sẵn để lựa chọn.
+
+```javascript
+const focus = ref(1)
+const controller = new ListDataRef(items, focus)
+
+// 1. Trạng thái tiêu điểm và tìm kiếm
+controller.isFocus()        // Xác minh tính chính xác của tiêu điểm hiện tại
+controller.isHighlight()    // Kiểm tra xem có kết quả tìm kiếm trùng khớp hay không
+controller.highlightFirstItem // Chỉ số của mục trùng khớp đầu tiên
+
+// 2. Điều hướng tương đối (từ mục đã chọn)
+const next = controller.getSelectedNext() // Chỉ số của mục khả dụng tiếp theo
+const prev = controller.getSelectedPrev() // Chỉ số của mục khả dụng trước đó
+
+// 3. Điều hướng tự do (theo các bước hoặc đối tượng)
+const item = controller.getItemByStep(currentItem, 2) // Nhảy qua 2 mục từ vị trí hiện tại
+const firstInGroup = controller.getFirstItemByParent('group-id') // Mục đầu tiên trong nhóm
+```
+
+## Làm việc với các cấu trúc lồng nhau
+
+Để xử lý các nhóm hoặc cấu trúc dạng cây, phương thức `getSubList()` được sử dụng. Nó tạo ra một phiên bản trình điều khiển mới cho dữ liệu lồng nhau trong khi vẫn duy trì liên kết toàn cầu với các trạng thái tiêu điểm và lựa chọn.
+
+```javascript
+// Bên trong một thành phần nhóm hoặc menu thả xuống:
+const subController = controller.getSubList(groupItem)
+
+// subController sẽ tự động theo dõi các thay đổi trong danh sách cha
+const subItems = subController.fullData
+```

package/src/media/functional/functional/ref/ref.en.mdx

@@ -0,0 +1,57 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/# Reactive Classes (Ref)'/>
+
+# Reactive Classes (Ref)
+
+Reactive versions of basic classes are created for seamless integration with the **Vue 3 (Composition API)**.
+
+## Features
+
+The core idea is that the class itself monitors input data changes and provides ready-to-use `ComputedRef` for templates. This eliminates the need to manually recalculate values when the locale or input variables change.
+
+## Available Classes
+
+- `GeoRef` — Management of global locale (country, language) and its reactive state.
+- `DatetimeRef` — Reactive date manipulation, formatting, and time component calculation.
+- `GeoIntlRef` — Reactive formatting of numbers, currencies, lists, and relative time.
+- `EventRef` — Event listener management with automatic binding to reactive elements.
+- `GeoFlagRef` — Reactive retrieval of country flag links and state lists.
+
+## How to Work with Them
+
+Unlike the basic classes from `functional-basic`, which work with direct values, classes with the `Ref` suffix accept both raw data and `ref` as input. Internally, they set up listeners (`watch`) such that any change to the source automatically updates all dependent computed properties.
+
+Global application state is managed via the static `GeoRef` class. Its methods return reactive data about the current country and language, and calling `GeoRef.set()` instantly updates formatting across all other classes, such as `GeoIntlRef` or `DatetimeRef`.
+
+```javascript
+import { ref } from 'vue'
+import { GeoRef, DatetimeRef, GeoIntlRef } from '@dxtmisha/functional'
+
+// 1. Global management (GeoRef)
+const country = GeoRef.getCountry() // Always up-to-date country code
+
+// 2. Reactive date wrapper (DatetimeRef)
+const dateRaw = ref('2024-03-21')
+const date = new DatetimeRef(dateRaw)
+const displayDate = date.locale() // Automatically updates when dateRaw or locale changes
+
+// 3. On-the-fly formatting (GeoIntlRef)
+const price = ref(12500)
+const intl = new GeoIntlRef()
+const displayPrice = intl.currency(price, 'USD')
+```
+
+The same approach is used in `EventRef` for handling events. If the target element (`ref`) changes or temporarily becomes `null`, the class will automatically re-attach listeners once the element reappears in the DOM. You don't need to track element lifecycles manually — just pass a reference to the object.
+
+```javascript
+import { ref } from 'vue'
+import { EventRef } from '@dxtmisha/functional'
+
+const buttonRef = ref(null)
+
+// The listener will find the button itself once Vue binds it to buttonRef
+new EventRef(buttonRef, null, 'click', () => {
+  console.log('Click handled reactively')
+})
+```