@dxtmisha/wiki 0.39.1 → 0.39.3

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

@@ -0,0 +1,257 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Classes/ListDataRef - Quản Lý Danh Sách Dữ Liệu'/>
+
+# Lớp ListDataRef
+
+Một lớp phản ứng (reactive) để quản lý danh sách dữ liệu với bất kỳ độ phức tạp nào. Hỗ trợ lọc, lựa chọn (selection), tiêu điểm (focus) và cấu trúc lồng nhau (nhóm và menu). Lớp này chuyển đổi dữ liệu đầu vào thành định dạng chuẩn hóa và cung cấp một bộ phương thức phong phú để điều hướng, tìm kiếm và quản lý trạng thái của các phần tử.
+
+## Các tính năng chính
+
+- **Tính phản ứng (Reactivity)** — tự động cập nhật các thuộc tính tính toán (computed properties) khi dữ liệu nguồn (Vue ref) hoặc tham số điều khiển thay đổi.
+- **Chuẩn hóa** — chuyển đổi bất kỳ định dạng đầu vào nào (mảng chuỗi, đối tượng) thành một giao diện `ListDataItem` thống nhất.
+- **Lồng nhau sâu** — hỗ trợ cấu trúc dạng cây với việc quản lý danh sách con tự động thông qua `getSubList`.
+- **Điều hướng thông minh** — các phương thức tích hợp sẵn để di chuyển trong danh sách, có tính đến việc lọc và loại phần tử.
+- **Chế độ Lite** — tối ưu hóa việc hiển thị cho danh sách lớn bằng cách sử dụng `liteData`.
+- **Quản lý lựa chọn** — kiểm soát số lượng phần tử được chọn (tối thiểu/tối đa) và trạng thái của chúng.
+
+## Khởi tạo
+
+Tạo một thực thực thể `ListDataRef` mới để quản lý dữ liệu danh sách. Lớp này cung cấp khả năng chuẩn hóa dữ liệu đầu vào, quản lý tiêu điểm, lựa chọn và tìm kiếm. Hỗ trợ cập nhật phản ứng khi danh sách nguồn hoặc các tham số điều khiển thay đổi.
+
+**Tham số:**
+
+- `list: RefOrNormal<ListListInput | undefined>` — danh sách dữ liệu phản ứng hoặc thông thường.
+- `focus?: RefType<ListSelectedItem | undefined>` — mã định danh phần tử đang được lấy tiêu điểm (Vue ref).
+- `highlight?: RefType<string | undefined>` — văn bản tìm kiếm để làm nổi bật (Vue ref).
+- `highlightLengthStart?: RefType<number | undefined>` — số ký tự tối thiểu để bắt đầu tìm kiếm (Vue ref).
+- `filterMode?: RefType<boolean | undefined>` — chế độ lọc (Vue ref).
+- `selected?: RefType<ListSelectedList | undefined>` — danh sách các mã định danh đã chọn (Vue ref).
+- `keyValue?: RefType<string | undefined>` — tên trường cho giá trị (mặc định là `'value'`).
+- `keyLabel?: RefType<string | undefined>` — tên trường cho nhãn (mặc định là `'label'`).
+- `lite?: RefType<number | undefined>` — ngưỡng số lượng phần tử để kích hoạt chế độ Lite (Vue ref).
+- `min: RefOrNormal<number | string | undefined> = 0` — số lượng lựa chọn tối thiểu được phép.
+- `max: RefOrNormal<number | string | undefined> = 9_999_999` — số lượng lựa chọn tối đa được phép.
+- `parent?: string` — mã định danh cha (được sử dụng cho danh sách con).
+
+```typescript
+import { ListDataRef } from '@dxtmisha/functional'
+import { ref } from 'vue'
+
+const list = ref([
+  { label: 'Mục 1', value: 'item-1' },
+  { label: 'Nhóm 1', type: 'group', value: [
+    { label: 'Mục con 1.1', value: 'sub-1.1' }
+  ]}
+])
+
+const focus = ref(undefined)
+const selected = ref(['item-1'])
+
+const listData = new ListDataRef(
+  list, 
+  focus, 
+  undefined, // highlight
+  undefined, // highlightLengthStart
+  undefined, // filterMode
+  selected
+)
+```
+
+## Thuộc tính
+
+### Dữ liệu
+
+- `data: Computed<ListList>` — danh sách dữ liệu chuẩn hóa cốt lõi cho cấp độ hiện tại.
+- `liteData: Computed<ListList>` — phiên bản danh sách đơn giản hóa để hiển thị nhanh (chế độ Lite).
+- `fullData: Computed<ListDataFull>` — danh sách dữ liệu mở rộng với các cờ `focus`, `selected`, `disabled` và `highlight`.
+- `map: Computed<ListList>` — danh sách phẳng của tất cả các phần tử trong cây (bao gồm cả vùng chứa).
+- `mapItems: Computed<ListList>` — danh sách phẳng chỉ chứa các phần tử được chọn cuối cùng (`item`).
+- `items: Computed<ListList>` — danh sách phẳng các phần tử tương tác (`item`, `group`, `menu`).
+
+### Lựa chọn và Trạng thái
+
+- `isSelected: Computed<boolean>` — trả về `true` nếu có ít nhất một mục được chọn trong toàn bộ cây.
+- `isSelectedMin: Computed<boolean>` — `true` nếu số lượng mục được chọn đạt mức tối thiểu `min`.
+- `isSelectedMax: Computed<boolean>` — `true` nếu số lượng mục được chọn đạt ngưỡng `max`.
+- `selectedList: Computed<ListList>` — danh sách tất cả các đối tượng được chọn trên toàn bộ cây.
+- `selectedListInGroup: Computed<ListList>` — danh sách các đối tượng được chọn ở cấp độ hiện tại.
+- `selectedNames: Computed<ListNames>` — mảng các nhãn (`label`) cho tất cả các mục được chọn.
+- `selectedValues: Computed<any[]>` — mảng các giá trị (`value`) cho tất cả các mục được chọn.
+
+### Tìm kiếm
+
+- `highlightFirstItem: Computed<number>` — chỉ số của phần tử đầu tiên khớp với tìm kiếm trong `map`.
+
+## Phương thức
+
+### Trạng thái và Kiểm tra
+
+- `isLite(): boolean` — trả về `true` nếu chế độ tối ưu hóa đang hoạt động.
+- `isFocus(): boolean` — kiểm tra xem có tiêu điểm trong `map` hiện tại hay không.
+- `isHighlight(): boolean` — trả về `true` nếu tìm kiếm thấy kết quả khớp.
+- `isHighlightActive(): boolean` — kiểm tra xem quá trình tìm kiếm có đang hoạt động hay không.
+- `getLength(): number` — tổng số phần tử ở cấp độ hiện tại.
+- `getLengthByMap(): number` — tổng số phần tử trong toàn bộ cây.
+- `getLengthByItems(): number` — số lượng phần tử cuối cùng trong toàn bộ cây.
+
+### Lấy giá trị
+
+- `getFocus(): ListSelectedItem | undefined` — mã định danh đang được lấy tiêu điểm hiện tại.
+- `getHighlight(): string | undefined` — chuỗi tìm kiếm hiện tại.
+- `getHighlightLengthStart(): number` — độ dài chuỗi tối thiểu để kích hoạt tìm kiếm (mặc định là `2`).
+- `getSelected(): ListSelectedList | undefined` — danh sách các mã định danh đã chọn hiện tại.
+
+### Điều hướng và Tìm kiếm
+
+- `getSelectedByStep(step): ListSelectedItem | undefined` — tìm phần tử lân cận so với lựa chọn.
+- `getSelectedNext(): ListSelectedItem | undefined` — tiếp theo từ lựa chọn.
+- `getSelectedPrev(): ListSelectedItem | undefined` — trước đó từ lựa chọn.
+- `getItemByStep(item, step): ListDataItem | undefined` — tìm phần tử lân cận so với phần tử.
+- `getItemNext(item): ListDataItem | undefined` — tiếp theo từ phần tử.
+- `getItemPrev(item): ListDataItem | undefined` — trước đó từ phần tử.
+- `getIndexByStep(index, step): ListDataItem | undefined` — tìm phần tử lân cận so với chỉ số.
+- `getIndexNext(index): ListDataItem | undefined` — tiếp theo từ chỉ số.
+- `getIndexPrev(index): ListDataItem | undefined` — trước đó từ chỉ số.
+- `getItemByIndex(index): { key, item } | undefined` — tìm phần tử theo chỉ số.
+- `getItemByKey(key): ListDataItem | undefined` — trả về phần tử theo khóa trong map.
+- `getFirstItemByParent(parent): ListDataItem | undefined` — phần tử tương tác đầu tiên của cha.
+- `getLastItemByParent(parent): ListDataItem | undefined` — phần tử tương tác cuối cùng của cha.
+- `getSubList(item): ListDataRef` — tạo/trả về thực thể danh sách con.
+
+## Các kiểu dữ liệu
+
+Lớp sử dụng các cấu trúc chuẩn hóa để đảm bảo hành vi có thể dự đoán được với bất kỳ định dạng dữ liệu đầu vào nào.
+
+### `ListType`
+
+Xác định vai trò chức năng của một mục trong danh sách:
+- `item` — phần tử tương tác chính có sẵn để lựa chọn và lấy tiêu điểm.
+- `group` / `menu` — các vùng chứa các danh sách lồng nhau (`value`).
+- `subtitle` — một tiêu đề văn bản trong danh sách.
+- `html` — phần tử để chèn mã HTML tùy ý.
+- `line` / `space` — các vạch ngăn cách và khoảng cách trực quan.
+
+### `ListDataItem`
+
+Đối tượng mà tất cả dữ liệu đầu vào được chuyển đổi sau khi chuẩn hóa:
+- `index: string` — mã định danh duy nhất (tự động tạo nếu không được cung cấp).
+- `type: ListType` — loại mục (mặc định là `item`).
+- `label?: string | number` — văn bản hiển thị trong giao diện.
+- `value?: any` — một giá trị tùy ý được liên kết với mục.
+- `parent?: string` — mã định danh của mục cha.
+
+### `ListDataFullItem`
+
+Phiên bản mở rộng của `ListDataItem` cho `fullData`:
+- `focus: boolean` — `true` nếu mục đang được lấy tiêu điểm.
+- `selected: boolean` — `true` nếu mục được chọn.
+- `disabled: boolean` — `true` nếu mục bị vô hiệu hóa (ví dụ: khi đạt đến giới hạn `max`).
+- `highlight?: string` — chuỗi tìm kiếm hiện tại nếu nó khớp với văn bản của mục.
+
+### `ListListInput`
+
+Các định dạng dữ liệu được hỗ trợ cho hàm khởi tạo:
+- `string[]` — mảng chuỗi đơn giản (nhãn).
+- `Record<string, string>` — đối tượng `value: label`.
+- `ListDataBasic[]` — mảng các đối tượng với các trường như `label`, `value`, `type`, v.v.
+
+
+## Quản lý lựa chọn (Selection)
+
+Lớp cung cấp các công cụ mạnh mẽ để kiểm soát trạng thái lựa chọn trong danh sách, hỗ trợ lựa chọn đơn và nhiều lựa chọn với các ràng buộc.
+
+### Các tham số lựa chọn cốt lõi
+
+- `selected` — biến phản ứng (Vue `ref`) lưu trữ một mảng các mã định danh.
+- `min` / `max` — các ràng buộc về số lượng mục được chọn trên cấp độ hiện tại.
+
+### Lựa chọn Toàn cầu vs Cấp độ Nhóm
+
+- **selectedList** — trả về tất cả các mục đã chọn loại `item` từ toàn bộ cây.
+- **selectedListInGroup** — trả về các mục đã chọn chỉ từ cấp độ hiện tại (`data`). Các ràng buộc `min` và `max` làm việc dựa trên danh sách này.
+
+### Trạng thái disabled tự động
+
+Khi đạt đến giới hạn `max` (`isSelectedMax`), lớp sẽ tự động đánh dấu các mục chưa được chọn còn lại trong `fullData` là `disabled: true`.
+
+## Quản lý tiêu điểm (Focus)
+
+Trạng thái tiêu điểm được triển khai thông qua một biến phản ứng bên ngoài (Vue `ref`).
+
+### Các tính năng chính
+
+- **Trạng thái dùng chung** — các danh sách con sử dụng cùng một `ref` tiêu điểm.
+- **Tính phản ứng** — `fullData` tự động tính toán `focus: true` bằng cách so sánh `index` với biến tiêu điểm.
+- **Điều khiển thủ công** — lớp không tự thay đổi trạng thái tiêu điểm. Các phương thức điều hướng chỉ trả về đối tượng đích.
+
+```javascript
+const next = listData.getItemNext(currentItem)
+if (next) {
+    focus.value = next.index 
+}
+```
+
+## Tìm kiếm và Làm nổi bật (Highlight)
+
+### Các tham số cốt lõi
+
+- `highlight` — chuỗi phản ứng chứa truy vấn tìm kiếm.
+- `highlightLengthStart` — ngưỡng kích hoạt (mặc định là `2`). 
+
+### Cách thức hoạt động
+
+1. **Regex** — tự động tạo biểu thức chính quy khi chuỗi tìm kiếm thay đổi.
+2. **Các trường** — tìm kiếm trên `label`, `index` và trường `search`.
+3. **fullData** — mỗi mục nhận giá trị `highlight` để hiển thị trong UI.
+4. **Kết quả khớp đầu tiên** — `highlightFirstItem` trả về chỉ số của mục đầu tiên tìm thấy trong mảng `map`.
+
+### Kiểm tra trạng thái
+
+- `isHighlight()` — có ít nhất một mục khớp.
+- `isHighlightActive()` — chuỗi tìm kiếm đã đạt đến độ dài yêu cầu.
+
+## Chế độ lọc (filterMode)
+
+Tham số `filterMode` là một cờ trạng thái hướng dẫn UI có nên ẩn các mục không khớp hay không. Cờ này được kế thừa bởi các danh sách con.
+
+## Chế độ Lite (Lite Mode)
+
+Tối ưu hóa hiệu suất cho danh sách lớn. Nếu số lượng phần tử > `lite`, thuộc tính `liteData` với cấu trúc đơn giản sẽ được kích hoạt.
+
+## Ví dụ sử dụng
+
+### Hiển thị cây nhóm
+
+```vue
+<template>
+  <ul>
+    <li v-for="item in listData.data.value" :key="item.index">
+      {{ item.label }}
+      <ul v-if="item.type === 'group'">
+        <li v-for="sub in listData.getSubList(item).data.value" :key="sub.index">
+           {{ sub.label }}
+        </li>
+      </ul>
+    </li>
+  </ul>
+</template>
+
+<script setup>
+const listData = new ListDataRef(props.list)
+</script>
+```
+
+## Làm việc với điều hướng
+
+### Điều hướng phẳng vòng lặp
+
+Các phương thức `getItemNext/Prev` và `getIndexNext/Prev` hoạt động thông qua `mapItems` (chỉ các phần tử loại `item`). Điều hướng xuyên suốt cây dữ liệu và có tính vòng lặp.
+
+### Điều hướng dựa trên lựa chọn
+
+`getSelectedNext/Prev` tìm phần tử lân cận so với phần tử được chọn đầu tiên.
+
+### Điều hướng theo ngữ cảnh (Parent)
+
+`getFirstItemByParent` và `getLastItemByParent` tìm ranh giới của cấp độ lồng nhau hiện tại bằng mã định danh cha.

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

@@ -0,0 +1,107 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Classes/RouterItemRef - Vue Router Management'/>
+
+# RouterItemRef Class
+
+The static core for working with Vue Router in the functional layer. It provides a single entry point to the router, allowing for link generation, navigation, and path normalization without direct dependency on the component context.
+
+This enables the use of router capabilities in classes and utilities where `useRouter` or `useRoute` hooks are not available.
+
+## Key Features
+
+- **Global Access** — saves the router instance for access from anywhere in the application.
+- **Safe Generation** — methods for creating links by route names with parameters.
+- **Normalization** — converts various path formats into standard `href` properties.
+
+## Usage (Setup)
+
+Since `RouterItemRef` is a static class, it must be initialized once during application creation (usually in `main.ts` or in a plugin).
+
+```typescript
+import { RouterItemRef } from '@dxtmisha/functional'
+import { createRouter, createWebHistory } from 'vue-router'
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [...]
+})
+
+// Set the router for global use
+RouterItemRef.set(router)
+```
+
+## Instance Management
+
+- `static get(): Router | undefined` — Returns the currently set router instance.
+- `static set(router: Router): void` — Sets the router instance.
+- `static setOneTime(router: Router): void` — Sets the router instance only if it hasn't been set yet. Useful for preventing accidental overwrites in plugins.
+
+## Navigation and Links
+
+A group of methods for managing navigation history and URL generation.
+
+### `push`
+
+Performs programmatic navigation to the specified route. It is a safe wrapper over `router.push`. If the router is not yet set, the action will be ignored.
+
+**Parameters:**
+- `to: string | RouteLocationRaw` — target path or route location object.
+
+### `getLink`
+
+Generates and returns a string URL (href) for a route based on its name and parameters. Uses the `router.resolve` method.
+
+**Parameters:**
+- `name: string` — unique route name.
+- `params?: any` — dynamic path parameters (params).
+- `query?: any` — query string parameters (query).
+
+**Returns:** `string | undefined` — the generated URL or `undefined` if the router is not initialized.
+
+### `getHref`
+
+Returns a standardized link properties object. Useful for passing to components expecting `ConstrHrefProps`.
+
+**Parameters:**
+- `name?: string` — route name.
+- `params?: any` — path parameters.
+- `query?: any` — query parameters.
+
+**Returns:** `ConstrHrefProps` — an `{ href: string }` object or `{}` (empty object) if no name is provided.
+
+### `rawToHref`
+
+A special normalization method. Converts a location object (if it contains a `name`) into a link properties object.
+
+**Parameters:**
+- `to?: string | RouteLocationRaw` — raw route data.
+
+**Returns:** `ConstrHrefProps` — the result of `getHref` or `{}`.
+
+## Examples
+
+### Generating a Link in Code
+
+```typescript
+import { RouterItemRef } from '@dxtmisha/functional'
+
+// Get URL for user profile page
+const userUrl = RouterItemRef.getLink('user-profile', { id: 123 })
+// Result: '/user/123' (depending on router configuration)
+
+// Use for component properties
+const linkProps = RouterItemRef.getHref('catalog', undefined, { category: 'electronics' })
+// Result: { href: '/catalog?category=electronics' }
+```
+
+### Programmatic Navigation
+
+```typescript
+import { RouterItemRef } from '@dxtmisha/functional'
+
+const logout = () => {
+    // Navigate to the home page after logout
+    RouterItemRef.push({ name: 'home' })
+}
+```

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

@@ -0,0 +1,107 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Classes/RouterItemRef - Управление Vue Router'/>
+
+# Класс RouterItemRef
+
+Статическое ядро для работы с Vue Router в функциональном слое. Обеспечивает единую точку доступа к роутеру, позволяя генерировать ссылки, выполнять переходы и нормализовать пути без прямой зависимости от контекста компонента.
+
+Это позволяет использовать возможности роутера в классах и утилитах, где недоступны хуки `useRouter` или `useRoute`.
+
+## Ключевые особенности
+
+- **Глобальный доступ** — сохранение экземпляра роутера для доступа из любого места приложения.
+- **Безопасная генерация** — методы для создания ссылок по именам маршрутов с параметрами.
+- **Нормализация** — преобразование различных форматов путей в стандартные свойства `href`.
+
+## Использование (Настройка)
+
+Поскольку `RouterItemRef` является статическим классом, его необходимо инициализировать один раз при создании приложения (обычно в `main.ts` или в плагине).
+
+```typescript
+import { RouterItemRef } from '@dxtmisha/functional'
+import { createRouter, createWebHistory } from 'vue-router'
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [...]
+})
+
+// Установка роутера для глобального использования
+RouterItemRef.set(router)
+```
+
+## Управление экземпляром
+
+- `static get(): Router | undefined` — Возвращает текущий установленный экземпляр роутера.
+- `static set(router: Router): void` — Устанавливает экземпляр роутера.
+- `static setOneTime(router: Router): void` — Устанавливает экземпляр роутера только в том случае, если он еще не был установлен. Полезно для предотвращения случайной перезаписи в плагинах.
+
+## Навигация и Ссылки
+
+Группа методов для управления историей переходов и генерации URL.
+
+### `push`
+
+Выполняет программный переход на указанный маршрут. Является безопасной оберткой над `router.push`. Если роутер еще не установлен, действие будет проигнорировано.
+
+**Параметры:**
+- `to: string | RouteLocationRaw` — целевой путь или объект местоположения маршрута.
+
+### `getLink`
+
+Генерирует и возвращает строковый URL (href) для маршрута на основе его имени и параметров. Использует метод `router.resolve`.
+
+**Параметры:**
+- `name: string` — уникальное имя маршрута.
+- `params?: any` — динамические параметры пути (params).
+- `query?: any` — параметры запроса (query string).
+
+**Возвращает:** `string | undefined` — готовый URL или `undefined`, если роутер не инициализирован.
+
+### `getHref`
+
+Возвращает стандартизированный объект свойств ссылки. Удобно для передачи в компоненты, ожидающие `ConstrHrefProps`.
+
+**Параметры:**
+- `name?: string` — имя маршрута.
+- `params?: any` — параметры пути.
+- `query?: any` — параметры запроса.
+
+**Возвращает:** `ConstrHrefProps` — объект `{ href: string }` или `{}` (пустой объект), если имя не передано.
+
+### `rawToHref`
+
+Специальный метод для нормализации. Преобразует объект местоположения (если в нем указано `name`) в объект свойств ссылки.
+
+**Параметры:**
+- `to?: string | RouteLocationRaw` — необработанные данные маршрута.
+
+**Возвращает:** `ConstrHrefProps` — результат работы `getHref` или `{}`.
+
+## Примеры
+
+### Генерация ссылки в коде
+
+```typescript
+import { RouterItemRef } from '@dxtmisha/functional'
+
+// Получение URL для страницы пользователя
+const userUrl = RouterItemRef.getLink('user-profile', { id: 123 })
+// Результат: '/user/123' (в зависимости от настроек роутера)
+
+// Использование для свойств компонентов
+const linkProps = RouterItemRef.getHref('catalog', undefined, { category: 'electronics' })
+// Результат: { href: '/catalog?category=electronics' }
+```
+
+### Программный переход
+
+```typescript
+import { RouterItemRef } from '@dxtmisha/functional'
+
+const logout = () => {
+    // Выполняем переход на главную страницу после выхода
+    RouterItemRef.push({ name: 'home' })
+}
+```

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

@@ -0,0 +1,107 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Classes/RouterItemRef - Quản lý Vue Router'/>
+
+# Lớp RouterItemRef
+
+Lõi tĩnh để làm việc với Vue Router trong lớp chức năng (functional layer). Nó cung cấp một điểm truy cập duy nhất vào router, cho phép tạo liên kết, điều hướng và chuẩn hóa đường dẫn mà không phụ thuộc trực tiếp vào ngữ cảnh của thành phần (component context).
+
+Điều này cho phép sử dụng các khả năng của router trong các lớp và tiện ích nơi các hook `useRouter` hoặc `useRoute` không khả dụng.
+
+## Các tính năng chính
+
+- **Truy cập Toàn cầu** — lưu trữ thực thể router để truy cập từ bất kỳ đâu trong ứng dụng.
+- **Tạo Liên kết An toàn** — các phương thức để tạo liên kết bằng tên route với các tham số.
+- **Chuẩn hóa** — chuyển đổi các định dạng đường dẫn khác nhau thành các thuộc tính `href` tiêu chuẩn.
+
+## Sử dụng (Thiết lập)
+
+Vì `RouterItemRef` là một lớp tĩnh, nó phải được khởi tạo một lần khi tạo ứng dụng (thường là trong `main.ts` hoặc trong một plugin).
+
+```typescript
+import { RouterItemRef } from '@dxtmisha/functional'
+import { createRouter, createWebHistory } from 'vue-router'
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [...]
+})
+
+// Thiết lập router để sử dụng toàn cầu
+RouterItemRef.set(router)
+```
+
+## Quản lý thực thể
+
+- `static get(): Router | undefined` — Trả về thực thể router hiện đang được thiết lập.
+- `static set(router: Router): void` — Thiết lập thực thể router.
+- `static setOneTime(router: Router): void` — Thiết lập thực thể router chỉ khi nó chưa được thiết lập. Hữu ích để ngăn chặn việc ghi đè vô tình trong các plugin.
+
+## Điều hướng và Liên kết
+
+Nhóm các phương thức quản lý lịch sử điều hướng và tạo URL.
+
+### `push`
+
+Thực hiện điều hướng theo lập trình đến route được chỉ định. Đây là một trình bao bọc an toàn cho `router.push`. Nếu router chưa được thiết lập, hành động sẽ bị bỏ qua.
+
+**Tham số:**
+- `to: string | RouteLocationRaw` — đường dẫn đích hoặc đối tượng vị trí route.
+
+### `getLink`
+
+Tạo và trả về một chuỗi URL (href) cho một route dựa trên tên và các tham số của nó. Sử dụng phương thức `router.resolve`.
+
+**Tham số:**
+- `name: string` — tên route duy nhất.
+- `params?: any` — các tham số đường dẫn động (params).
+- `query?: any` — các tham số chuỗi truy vấn (query).
+
+**Trả về:** `string | undefined` — URL được tạo hoặc `undefined` nếu router chưa được khởi tạo.
+
+### `getHref`
+
+Trả về một đối tượng thuộc tính liên kết được chuẩn hóa. Hữu ích để truyền vào các thành phần mong đợi `ConstrHrefProps`.
+
+**Tham số:**
+- `name?: string` — tên route.
+- `params?: any` — tham số đường dẫn.
+- `query?: any` — tham số truy vấn.
+
+**Trả về:** `ConstrHrefProps` — một đối tượng `{ href: string }` hoặc `{}` (đối tượng trống) nếu không có tên nào được cung cấp.
+
+### `rawToHref`
+
+Một phương thức chuẩn hóa đặc biệt. Chuyển đổi một đối tượng vị trí (nếu nó chứa `name`) thành một đối tượng thuộc tính liên kết.
+
+**Tham số:**
+- `to?: string | RouteLocationRaw` — dữ liệu route thô.
+
+**Trả về:** `ConstrHrefProps` — kết quả của `getHref` hoặc `{}`.
+
+## Ví dụ
+
+### Tạo liên kết trong mã
+
+```typescript
+import { RouterItemRef } from '@dxtmisha/functional'
+
+// Lấy URL cho trang hồ sơ người dùng
+const userUrl = RouterItemRef.getLink('user-profile', { id: 123 })
+// Kết quả: '/user/123' (tùy thuộc vào cấu hình router)
+
+// Sử dụng cho các thuộc tính thành phần
+const linkProps = RouterItemRef.getHref('catalog', undefined, { category: 'electronics' })
+// Kết quả: { href: '/catalog?category=electronics' }
+```
+
+### Điều hướng theo lập trình
+
+```typescript
+import { RouterItemRef } from '@dxtmisha/functional'
+
+const logout = () => {
+    // Điều hướng đến trang chủ sau khi đăng xuất
+    RouterItemRef.push({ name: 'home' })
+}
+```

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

@@ -0,0 +1,87 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Classes/ScrollbarWidthRef - Scrollbar Width'/>
+
+# Class ScrollbarWidthRef
+
+A reactive wrapper around the base utility for determining scrollbar parameters. The class allows for tracking both the presence of a scrollbar (its type) and its actual width in pixels. This is critical for preventing layout shifts when a scrollbar is hidden or shown, such as when opening modal windows.
+
+## Key Features
+
+- **Reactivity** — automatic update of `item` and `width` values when data is received from the browser.
+- **Automatic Calculation** — the class independently initiates a scrollbar width measurement immediately after instance creation.
+- **Readiness State** — the existence of the computed property `is` allows for safe data usage only after initialization.
+- **Cross-platform** — correctly identifies "thin" and auto-hiding scrollbars (macOS, mobile devices).
+
+## Initialization
+
+Creates a new instance of `ScrollbarWidthRef` and starts the asynchronous process of measuring the scrollbar width.
+
+**Parameters:**
+- `None`
+
+```typescript
+import { ScrollbarWidthRef } from '@dxtmisha/functional'
+
+const scrollbar = new ScrollbarWidthRef()
+```
+
+## Properties
+
+### State
+
+- `item: Ref<boolean | undefined>` — Flag determining the result of the `ScrollbarWidth.is()` check. Returns `true` if the scrollbar is considered "special" (e.g., auto-hiding in macOS or mobile, where the width is typically `<= 8px`).
+- `width: Ref<number>` — The actual width of the scrollbar in pixels. Defaults to `0`. Updated asynchronously after measurement.
+- `is: Computed<boolean>` — Returns `true` when the width calculation is complete and the `item` and `width` values are up-to-date.
+
+## Examples
+
+### Dynamic Scroll Compensation in CSS
+
+Using reactive width to create a CSS variable that compensates for offset when scrolling is blocked.
+
+```vue
+<template>
+  <div :style="style" class="container">
+    Content with dynamic offset
+  </div>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+import { ScrollbarWidthRef } from '@dxtmisha/functional'
+
+const scrollbar = new ScrollbarWidthRef()
+
+// Calculate the variable only after the width is determined
+const style = computed(() => ({
+  '--scrollbar-width': scrollbar.is.value ? `${scrollbar.width.value}px` : '0px'
+}))
+</script>
+
+<style scoped>
+.container {
+  /* Example usage for right padding */
+  padding-right: var(--scrollbar-width);
+}
+</style>
+```
+
+### Tracking Scrollbar Type
+
+```typescript
+import { watch } from 'vue'
+import { ScrollbarWidthRef } from '@dxtmisha/functional'
+
+const scrollbar = new ScrollbarWidthRef()
+
+watch(() => scrollbar.is.value, (ready) => {
+  if (ready) {
+    if (scrollbar.item.value) {
+      console.log('System/auto-hiding scrollbar is being used')
+    } else {
+      console.log(`Standard scrollbar with width ${scrollbar.width.value}px`)
+    }
+  }
+})
+```