@dxtmisha/wiki 0.25.1 → 0.39.2

package/src/media/functional/functional/composables/useLoadingRef/useLoadingRef.vi.mdx

@@ -0,0 +1,20 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Composables/useLoadingRef - Trạng thái tải'/>
+
+# `useLoadingRef`
+
+Composable để lấy trạng thái tải toàn cục.
+
+**Trả về:**
+- `ShallowRef<boolean>` — một tham chiếu phản ứng đến trạng thái tải hiện tại.
+
+## Ví dụ sử dụng
+
+```typescript
+import { useLoadingRef } from '@dxtmisha/functional'
+
+const isLoading = useLoadingRef()
+
+// Sử dụng isLoading.value trong template hoặc logic của bạn
+```

package/src/media/functional/functional/composables/useMeta/useMeta.en.mdx

@@ -0,0 +1,31 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Composables/useMeta - Meta tags management'/>
+
+# `useMeta`
+
+Composable for reactive management of meta tags (HTML, Open Graph, Twitter Card) with automatic DOM synchronization. Uses a singleton pattern where all components share the same meta state.
+
+**Returns:**
+- `title: Ref<string>` — reactive page title (without suffix).
+- `description: Ref<string>` — reactive description meta tag.
+- `keyword: Ref<string>` — reactive keywords meta tag.
+- `image: Ref<string>` — reactive image URL for Open Graph / Twitter Card.
+- `canonical: Ref<string>` — reactive canonical URL.
+- `robots: Ref<MetaRobots>` — reactive robots directive.
+- `author: Ref<string>` — reactive author meta tag.
+- `siteName: Ref<string>` — reactive site name.
+- `getHtmlMeta(): string` — generates an HTML string for all meta tags (useful for SSR).
+- `setSuffix(suffix: string): void` — sets the suffix for the page title.
+- `meta: Meta` — the underlying `Meta` instance.
+
+## Usage Example
+
+```typescript
+import { useMeta } from '@dxtmisha/functional'
+
+const { title, description } = useMeta()
+
+title.value = 'My Page Title'
+description.value = 'Description of my cool page'
+```

package/src/media/functional/functional/composables/useMeta/useMeta.ru.mdx

@@ -0,0 +1,31 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Composables/useMeta - Управление мета-тегами'/>
+
+# `useMeta`
+
+Composable для реактивного управления мета-тегами (HTML, Open Graph, Twitter Card) с автоматической синхронизацией DOM. Использует паттерн singleton — все компоненты используют одно состояние мета-тегов.
+
+**Возвращает:**
+- `title: Ref<string>` — реактивный заголовок страницы (без суффикса).
+- `description: Ref<string>` — реактивный мета-тег description.
+- `keyword: Ref<string>` — реактивный мета-тег keywords.
+- `image: Ref<string>` — реактивный URL изображения для Open Graph / Twitter Card.
+- `canonical: Ref<string>` — реактивный канонический URL.
+- `robots: Ref<MetaRobots>` — реактивная директива robots.
+- `author: Ref<string>` — реактивный мета-тег author.
+- `siteName: Ref<string>` — реактивное название сайта.
+- `getHtmlMeta(): string` — генерирует HTML-строку для всех мета-тегов (полезно для SSR).
+- `setSuffix(suffix: string): void` — устанавливает суффикс для заголовка страницы.
+- `meta: Meta` — базовый экземпляр `Meta`.
+
+## Пример использования
+
+```typescript
+import { useMeta } from '@dxtmisha/functional'
+
+const { title, description } = useMeta()
+
+title.value = 'Заголовок страницы'
+description.value = 'Описание моей крутой страницы'
+```

package/src/media/functional/functional/composables/useMeta/useMeta.vi.mdx

@@ -0,0 +1,31 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Composables/useMeta - Quản lý thẻ meta'/>
+
+# `useMeta`
+
+Composable để quản lý phản ứng các thẻ meta (HTML, Open Graph, Twitter Card) với khả năng tự động đồng bộ hóa DOM. Sử dụng pattern singleton - tất cả các component đều chia sẻ cùng một trạng thái meta.
+
+**Trả về:**
+- `title: Ref<string>` — tiêu đề trang phản ứng (không có hậu tố).
+- `description: Ref<string>` — thẻ meta description phản ứng.
+- `keyword: Ref<string>` — thẻ meta keywords phản ứng.
+- `image: Ref<string>` — URL hình ảnh phản ứng cho Open Graph / Twitter Card.
+- `canonical: Ref<string>` — URL canonical phản ứng.
+- `robots: Ref<MetaRobots>` — chỉ thị robots phản ứng.
+- `author: Ref<string>` — thẻ meta author phản ứng.
+- `siteName: Ref<string>` — tên trang web phản ứng.
+- `getHtmlMeta(): string` — tạo chuỗi HTML cho tất cả các thẻ meta (hữu ích cho SSR).
+- `setSuffix(suffix: string): void` — thiết lập hậu tố cho tiêu đề trang.
+- `meta: Meta` — thực thể `Meta` cơ sở.
+
+## Ví dụ sử dụng
+
+```typescript
+import { useMeta } from '@dxtmisha/functional'
+
+const { title, description } = useMeta()
+
+title.value = 'Tiêu đề trang của tôi'
+description.value = 'Mô tả về trang web tuyệt vời của tôi'
+```

package/src/media/functional/functional/composables/useRouterList/useRouterList.en.mdx

@@ -0,0 +1,40 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Composables/useRouterList - Managing a list of links'/>
+
+# `useRouterList`
+
+Managing a list of links for the router. Allows creating navigation menus based on data lists, automatically handling active states and transitions.
+
+**Parameters:**
+- `list: RefType<ConstrBind<T>[] | undefined>` — list of navigation items. Each item must contain `value` and `label`.
+- `selected?: Ref<string> | string` — initially selected item or its value. If not specified, the first item in the list is selected.
+- `hasTo?: boolean` — automatically adds the `to` property to list items for navigation (default is `false`).
+
+**Returns:**
+An object with reactive properties and control methods:
+- `item: ComputedRef<T | undefined>` — A computed property that returns the current active item object based on `selected`.
+- `selected: Ref<string>` — A reactive reference to the value of the selected item. Allows both getting and setting the current selection.
+- `label: ComputedRef<NumberOrString>` — A computed property that returns the label of the current selected item.
+- `list: ComputedRef<ConstrBind<T>[]>` — A computed list of items. If `hasTo` is `true`, each item is automatically augmented with a `to` property for routing integration.
+- `to(name?: string): void` — A method for programmatic navigation to an item by its name (`value`). Updates `selected` and performs `router.push`.
+- `toMain(): void` — A method for quick navigation to the first ("main") item in the `list`.
+
+```typescript
+import { ref } from 'vue'
+import { useRouterList } from '@dxtmisha/functional'
+
+const menuItems = ref([
+  { value: 'dashboard', label: 'Dashboard' },
+  { value: 'settings', label: 'Settings' }
+])
+
+// Initialize with 'dashboard' selected and automatic 'to' property creation
+const { list, selected, to } = useRouterList(menuItems, 'dashboard', true)
+
+// The list will contain objects with a 'to' field, for example:
+// { value: 'dashboard', label: 'Dashboard', to: { name: 'dashboard' } }
+
+// Programmatic navigation
+to('settings')
+```

package/src/media/functional/functional/composables/useRouterList/useRouterList.ru.mdx

@@ -0,0 +1,40 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Composables/useRouterList - Управление списком ссылок'/>
+
+# `useRouterList`
+
+Управление списком ссылок для роутера. Позволяет создавать навигационные меню на основе списка данных, автоматически обрабатывая активное состояние и переходы.
+
+**Параметры:**
+- `list: RefType<ConstrBind<T>[] | undefined>` — список элементов навигации. Каждый элемент должен содержать `value` и `label`.
+- `selected?: Ref<string> | string` — изначально выбранный элемент или его значение. Если не указан, выбирается первый элемент списка.
+- `hasTo?: boolean` — автоматическое добавление свойства `to` к элементам списка для навигации (по умолчанию `false`).
+
+**Возвращает:**
+Объект с реактивными свойствами и методами управления:
+- `item: ComputedRef<T | undefined>` — Вычисляемое свойство, возвращающее объект текущего активного элемента на основе `selected`.
+- `selected: Ref<string>` — Реактивная ссылка на значение (`value`) выбранного элемента. Позволяет как получать, так и устанавливать текущий выбор.
+- `label: ComputedRef<NumberOrString>` — Вычисляемое свойство, возвращающее текстовую метку (`label`) текущего выбранного элемента.
+- `list: ComputedRef<ConstrBind<T>[]>` — Вычисляемый список элементов. Если `hasTo` установлен в `true`, каждый элемент автоматически дополняется свойством `to` для интеграции с маршрутизацией.
+- `to(name?: string): void` — Метод для программного перехода к элементу по его имени (`value`). Обновляет `selected` и выполняет `router.push`.
+- `toMain(): void` — Метод для быстрого перехода к первому ("главному") элементу в списке `list`.
+
+```typescript
+import { ref } from 'vue'
+import { useRouterList } from '@dxtmisha/functional'
+
+const menuItems = ref([
+  { value: 'dashboard', label: 'Дашборд' },
+  { value: 'settings', label: 'Настройки' }
+])
+
+// Инициализация с выбором 'dashboard' и автоматическим созданием свойства 'to'
+const { list, selected, to } = useRouterList(menuItems, 'dashboard', true)
+
+// Список будет содержать объекты с полем 'to', например:
+// { value: 'dashboard', label: 'Дашборд', to: { name: 'dashboard' } }
+
+// Программный переход
+to('settings')
+```

package/src/media/functional/functional/composables/useRouterList/useRouterList.vi.mdx

@@ -0,0 +1,40 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Composables/useRouterList - Quản lý danh sách liên kết'/>
+
+# `useRouterList`
+
+Quản lý danh sách liên kết cho router. Cho phép tạo menu điều hướng dựa trên danh sách dữ liệu, tự động xử lý trạng thái hoạt động và chuyển đổi.
+
+**Tham số:**
+- `list: RefType<ConstrBind<T>[] | undefined>` — danh sách các mục điều hướng. Mỗi mục phải chứa `value` và `label`.
+- `selected?: Ref<string> | string` — mục được chọn ban đầu hoặc giá trị của nó. Nếu không được chỉ định, mục đầu tiên trong danh sách sẽ được chọn.
+- `hasTo?: boolean` — tự động thêm thuộc tính `to` vào các mục danh sách để điều hướng (mặc định là `false`).
+
+**Trả về:**
+Một đối tượng với các thuộc tính phản ứng và phương thức điều khiển:
+- `item: ComputedRef<T | undefined>` — Thuộc tính được tính toán trả về đối tượng mục hiện đang hoạt động dựa trên `selected`.
+- `selected: Ref<string>` — Tham chiếu phản ứng (`ref`) đến giá trị của mục được chọn. Cho phép cả lấy và thiết lập lựa chọn hiện tại.
+- `label: ComputedRef<NumberOrString>` — Thuộc tính được tính toán trả về nhãn (`label`) của mục hiện được chọn.
+- `list: ComputedRef<ConstrBind<T>[]>` — Danh sách các mục được tính toán. Nếu `hasTo` là `true`, mỗi mục được tự động bổ sung thuộc tính `to` để tích hợp điều hướng.
+- `to(name?: string): void` — Phương thức điều hướng lập trình đến một mục theo tên (`value`) của nó. Cập nhật `selected` và thực hiện `router.push`.
+- `toMain(): void` — Phương thức điều hướng nhanh đến mục đầu tiên ("mục chính") trong danh sách `list`.
+
+```typescript
+import { ref } from 'vue'
+import { useRouterList } from '@dxtmisha/functional'
+
+const menuItems = ref([
+  { value: 'dashboard', label: 'Bảng điều khiển' },
+  { value: 'settings', label: 'Cài đặt' }
+])
+
+// Khởi tạo với 'dashboard' được chọn và tự động tạo thuộc tính 'to'
+const { list, selected, to } = useRouterList(menuItems, 'dashboard', true)
+
+// Danh sách sẽ chứa các đối tượng có trường 'to', ví dụ:
+// { value: 'dashboard', label: 'Bảng điều khiển', to: { name: 'dashboard' } }
+
+// Điều hướng bằng lập trình
+to('settings')
+```

package/src/media/functional/functional/composables/useSearchRef/useSearchRef.en.mdx

@@ -0,0 +1,61 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Composables/useSearchRef - List Search'/>
+
+# `useSearchRef`
+
+A composable for implementing search and filtering logic on a list of data with reactivity support and match highlighting.
+
+**Parameters:**
+- `list: SearchListInput<T>` — source data list (Array, Ref, or a function returning an array).
+- `columns: K` — list of columns (object keys) to search in.
+- `value?: Ref<string>` — external reactive search string ref. Created internally if not provided.
+- `options?: SearchOptions` — search settings:
+    - `limit?: number` — minimum character limit to activate search. Default: `2`.
+    - `delay?: number` — delay (debounce) before searching in ms. Default: `0`.
+    - `findExactMatch?: boolean` — if `true`, performs literal phrase match. If `false` (default), finds items containing all words in any order.
+    - `returnEverything?: boolean` — if `true`, returns all items (non-matching items have `searchActive: false`). If `false`, returns only matches.
+    - `classSearchName?: string` — CSS class for match highlighting. Default: `sys-search-selection`.
+
+**Returns:**
+- `isSearch: ComputedRef<boolean>` — whether the search is currently active (checks minimum character limit).
+- `search: Ref<string>` — current search string.
+- `loading: Ref<boolean>` — loading status (active during `delay`).
+- `listSearch: ComputedRef<SearchFormatList<T, K>>` — filtered and formatted results list. Each item gets `{column}Search` fields with HTML highlighting and a `searchActive` flag.
+
+## Architecture: Lazy `computed` (Dynamic Getters)
+
+This composable is specifically designed to return `isSearch` and `listSearch` as native JS getters.
+This allows you to call `useSearchRef()` **outside the lifecycle of a Vue component** (for example, globally in a service or in a Store).
+The actual `ComputedRef` objects are created (and bound to the component) exactly at the moment when the component accesses them during destructuring:
+
+```typescript
+// Getters will trigger once during destructuring in setup(), Vue will cache the ComputedRef
+const { search, listSearch, isSearch } = useSearchRef(items, ['name'])
+```
+
+> **Important**: Because of this architecture, avoid accessing getters "via dot notation" multiple times. Always destructure the result once at the `setup` level to avoid creating multiple duplicate `computed` instances.
+
+## Usage Example
+
+```typescript
+import { useSearchRef } from '@dxtmisha/functional'
+
+const items = [
+  { id: 1, name: 'Apple', category: 'Fruit' },
+  { id: 2, name: 'Banana', category: 'Fruit' },
+  { id: 3, name: 'Carrot', category: 'Vegetable' }
+]
+
+const { 
+  search, 
+  listSearch, 
+  loading 
+} = useSearchRef(items, ['name', 'category'], undefined, {
+  delay: 300,
+  limit: 2
+})
+
+// When "app" is entered into search.value:
+// listSearch.value will contain { ..., nameSearch: '<span...>App</span>le', searchActive: true }
+```

package/src/media/functional/functional/composables/useSearchRef/useSearchRef.ru.mdx

@@ -0,0 +1,61 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Composables/useSearchRef - Поиск по списку'/>
+
+# `useSearchRef`
+
+Composable для реализации логики поиска и фильтрации по списку данных с поддержкой реактивности и подсветки совпадений.
+
+**Параметры:**
+- `list: SearchListInput<T>` — исходный список данных (массив, Ref или функция, возвращающая массив).
+- `columns: K` — список колонок (ключей объекта), по которым необходимо выполнять поиск.
+- `value?: Ref<string>` — внешняя реактивная ссылка на строку поиска. Если не передана, создается внутренняя.
+- `options?: SearchOptions` — настройки поиска:
+    - `limit?: number` — минимальное количество символов для активации поиска. По умолчанию: `2`.
+    - `delay?: number` — задержка (debounce) перед выполнением поиска в мс. По умолчанию: `0`.
+    - `findExactMatch?: boolean` — если `true`, выполняется поиск по точной фразе. Если `false` (по умолчанию), поиск находит элементы, содержащие все введенные слова в любом порядке.
+    - `returnEverything?: boolean` — если `true`, возвращает все элементы списка (неподходящие пометки `searchActive: false`). Если `false`, возвращает только найденные.
+    - `classSearchName?: string` — CSS класс для подсветки совпадений. По умолчанию: `sys-search-selection`.
+
+**Возвращает:**
+- `isSearch: ComputedRef<boolean>` — активен ли поиск в данный момент (проверка лимита символов).
+- `search: Ref<string>` — текущая строка поиска.
+- `loading: Ref<boolean>` — статус загрузки (активен во время задержки `delay`).
+- `listSearch: ComputedRef<SearchFormatList<T, K>>` — отфильтрованный и отформатированный список результатов. Каждому элементу добавляются поля вида `{column}Search` с HTML-подсветкой и флаг `searchActive`.
+
+## Архитектура: ленивые `computed` (Динамические геттеры)
+
+Композибл специально спроектирован так, чтобы возвращать `isSearch` и `listSearch` как нативные JS-геттеры.
+Это позволяет вызывать `useSearchRef()` **вне жизненного цикла компонента Vue** (например, глобально в сервисе или в Store).
+Настоящие объекты `ComputedRef` создаются (и привязываются к компоненту) ровно в тот момент, когда компонент обращается к ним при деструктуризации:
+
+```typescript
+// Геттеры сработают 1 раз при деструктуризации в setup(), Vue закэширует ComputedRef
+const { search, listSearch, isSearch } = useSearchRef(items, ['name'])
+```
+
+> **Важно**: Из-за этой архитектуры избегайте обращения к геттерам "через точку" множество раз. Всегда деструктурируйте результат один раз на уровне `setup`, чтобы избежать создания множества дублирующих `computed` экземпляров.
+
+## Пример использования
+
+```typescript
+import { useSearchRef } from '@dxtmisha/functional'
+
+const items = [
+  { id: 1, name: 'Apple', category: 'Fruit' },
+  { id: 2, name: 'Banana', category: 'Fruit' },
+  { id: 3, name: 'Carrot', category: 'Vegetable' }
+]
+
+const { 
+  search, 
+  listSearch, 
+  loading 
+} = useSearchRef(items, ['name', 'category'], undefined, {
+  delay: 300,
+  limit: 2
+})
+
+// При вводе "app" в search.value:
+// listSearch.value будет содержать { ..., nameSearch: '<span...>App</span>le', searchActive: true }
+```

package/src/media/functional/functional/composables/useSearchRef/useSearchRef.vi.mdx

@@ -0,0 +1,61 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Composables/useSearchRef - Tìm kiếm danh sách'/>
+
+# `useSearchRef`
+
+Một composable để triển khai logic tìm kiếm và lọc trên danh sách dữ liệu với hỗ trợ tính phản ứng (reactivity) và làm nổi bật kết quả khớp.
+
+**Tham số:**
+- `list: SearchListInput<T>` — danh sách dữ liệu nguồn (Mảng, Ref hoặc một hàm trả về mảng).
+- `columns: K` — danh sách các cột (key của đối tượng) để tìm kiếm.
+- `value?: Ref<string>` — ref chuỗi tìm kiếm phản ứng từ bên ngoài. Sẽ được tạo nội bộ nếu không được cung cấp.
+- `options?: SearchOptions` — cài đặt tìm kiếm:
+    - `limit?: number` — giới hạn ký tự tối thiểu để kích hoạt tìm kiếm. Mặc định: `2`.
+    - `delay?: number` — thời gian chờ (debounce) trước khi tìm kiếm tính bằng ms. Mặc định: `0`.
+    - `findExactMatch?: boolean` — nếu là `true`, thực hiện khớp theo cụm từ chính xác. Nếu là `false` (mặc định), tìm kiếm các mục chứa tất cả các từ theo bất kỳ thứ tự nào.
+    - `returnEverything?: boolean` — nếu là `true`, trả về tất cả các mục (các mục không khớp sẽ có `searchActive: false`). Nếu là `false`, chỉ trả về các mục khớp.
+    - `classSearchName?: string` — lớp CSS để làm nổi bật kết quả khớp. Mặc định: `sys-search-selection`.
+
+**Trả về:**
+- `isSearch: ComputedRef<boolean>` — tìm kiếm có đang hoạt động hay không (kiểm tra giới hạn ký tự tối thiểu).
+- `search: Ref<string>` — chuỗi tìm kiếm hiện tại.
+- `loading: Ref<boolean>` — trạng thái tải (hoạt động trong thời gian `delay`).
+- `listSearch: ComputedRef<SearchFormatList<T, K>>` — danh sách kết quả đã được lọc và định dạng. Mỗi mục sẽ có thêm các trường `{column}Search` với mã HTML làm nổi bật và cờ `searchActive`.
+
+## Kiến trúc: `computed` Lazy (Getter động)
+
+Composable này được thiết kế đặc biệt để trả về `isSearch` và `listSearch` dưới dạng native JS getter.
+Điều này cho phép bạn gọi `useSearchRef()` **bên ngoài vòng đời của component Vue** (ví dụ: toàn cục trong một service hoặc trong Store).
+Các đối tượng `ComputedRef` thực tế được tạo (và liên kết với component) chính xác tại thời điểm mà component truy cập chúng trong quá trình destructuring:
+
+```typescript
+// Các getter sẽ chạy một lần trong quá trình destructuring ở setup(), Vue sẽ cache ComputedRef
+const { search, listSearch, isSearch } = useSearchRef(items, ['name'])
+```
+
+> **Quan trọng**: Vì kiến trúc này, hãy tránh truy cập các getter thông qua "dấu chấm" nhiều lần. Luôn phân rã (destructure) kết quả một lần ở cấp độ `setup` để tránh tạo ra nhiều phiên bản `computed` trùng lặp.
+
+## Ví dụ sử dụng
+
+```typescript
+import { useSearchRef } from '@dxtmisha/functional'
+
+const items = [
+  { id: 1, name: 'Apple', category: 'Fruit' },
+  { id: 2, name: 'Banana', category: 'Fruit' },
+  { id: 3, name: 'Carrot', category: 'Vegetable' }
+]
+
+const { 
+  search, 
+  listSearch, 
+  loading 
+} = useSearchRef(items, ['name', 'category'], undefined, {
+  delay: 300,
+  limit: 2
+})
+
+// Khi "app" được nhập vào search.value:
+// listSearch.value sẽ chứa { ..., nameSearch: '<span...>App</span>le', searchActive: true }
+```

package/src/media/functional/functional/composables/useSearchValueRef/useSearchValueRef.en.mdx

@@ -0,0 +1,43 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Composables/useSearchValueRef - Search State and Logic'/>
+
+# `useSearchValueRef`
+
+A low-level composable for managing search query state, handling debounce delay, and creating regular expressions for matching. It is typically used inside `useSearchRef`.
+
+**Parameters:**
+- `item: SearchList<T, K>` — a configured instance of `SearchList` used for managing options and values.
+- `value?: Ref<string>` — external search reference. If not provided, an internal one is created.
+
+**Returns:**
+- `search: Ref<string>` — current search value (updates immediately).
+- `searchDelay: Ref<string>` — search value with applied delay (if delay is configured).
+- `loading: Ref<boolean>` — `true` during the debounce `delay`.
+
+## How It Works
+
+`useSearchValueRef` isolates the `debounce` delay logic from the actual data filtering. 
+When a user types into `search.value`, the composable:
+1. Immediately sets `loading.value = true`.
+2. Waits for the specified `delay` in milliseconds.
+3. If the user types again within the delay, the timer resets.
+4. Once the timer completes, it copies `search.value` into `searchDelay.value` and sets `loading.value = false`.
+
+By using `searchDelay.value` instead of `search.value` in your filtered lists, you ensure that complex data operations only happen after the user stops typing, significantly improving performance on large datasets.
+
+## Usage Example
+
+```typescript
+import { useSearchValueRef } from '@dxtmisha/functional'
+import { SearchList } from '@dxtmisha/functional-basic'
+import { ref } from 'vue'
+
+const items = [{ id: 1, name: 'Apple' }]
+const list = new SearchList(items, ['name'], undefined, { delay: 300 })
+const { search, searchDelay, loading } = useSearchValueRef(list)
+
+search.value = 'app'
+// loading.value becomes true
+// After 300ms searchDelay.value becomes 'app' and loading.value becomes false
+```

package/src/media/functional/functional/composables/useSearchValueRef/useSearchValueRef.ru.mdx

@@ -0,0 +1,43 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Composables/useSearchValueRef - Состояние и логика поиска'/>
+
+# `useSearchValueRef`
+
+Низкоуровневый composable для управления состоянием поискового запроса, обработки задержки (debounce) и создания регулярных выражений для сопоставления. Обычно используется внутри `useSearchRef`.
+
+**Параметры:**
+- `item: SearchList<T, K>` — настроенный экземпляр `SearchList`, используемый для управления параметрами и значениями.
+- `value?: Ref<string>` — внешняя реактивная ссылка на строку поиска. Если не передана, создается внутренняя.
+
+**Возвращает:**
+- `search: Ref<string>` — текущее значение поиска (меняется мгновенно).
+- `searchDelay: Ref<string>` — значение поиска с учетом задержки (если задержка настроена).
+- `loading: Ref<boolean>` — `true` во время ожидания задержки `delay`.
+
+## Архитектура и как это работает
+
+`useSearchValueRef` изолирует логику задержки (`debounce delay`) от фактической фильтрации данных.
+Когда пользователь вводит текст в `search.value`, composable:
+1. Немедленно устанавливает `loading.value = true`.
+2. Ожидает указанную задержку (`delay`) в миллисекундах.
+3. Если пользователь продолжает вводить текст в течение задержки, таймер сбрасывается.
+4. По истечении таймера значение `search.value` копируется в `searchDelay.value`, и `loading.value` сбрасывается в `false`.
+
+Использование `searchDelay.value` вместо `search.value` для фильтрации гарантирует, что ресурсоёмкие операции поиска выполняются только после того, как пользователь перестанет печатать, что значительно повышает производительность на больших наборах данных.
+
+## Пример использования
+
+```typescript
+import { useSearchValueRef } from '@dxtmisha/functional'
+import { SearchList } from '@dxtmisha/functional-basic'
+import { ref } from 'vue'
+
+const items = [{ id: 1, name: 'Apple' }]
+const list = new SearchList(items, ['name'], undefined, { delay: 300 })
+const { search, searchDelay, loading } = useSearchValueRef(list)
+
+search.value = 'app'
+// loading.value становится true
+// Через 300мс searchDelay.value станет 'app' и loading.value станет false
+```

package/src/media/functional/functional/composables/useSearchValueRef/useSearchValueRef.vi.mdx

@@ -0,0 +1,43 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Composables/useSearchValueRef - Trạng thái và logic tìm kiếm'/>
+
+# `useSearchValueRef`
+
+Composable cấp thấp để quản lý trạng thái truy vấn tìm kiếm, xử lý độ trễ (debounce) và tạo các biểu thức chính quy (RegExp) để khớp dữ liệu. Thường được sử dụng bên trong `useSearchRef`.
+
+**Tham số:**
+- `item: SearchList<T, K>` — một phiên bản đã được cấu hình của `SearchList`, dùng để quản lý các tùy chọn và giá trị.
+- `value?: Ref<string>` — tham chiếu phản hồi (Ref) tìm kiếm từ bên ngoài. Nếu không được cung cấp, một Ref nội bộ sẽ được tạo.
+
+**Trả về:**
+- `search: Ref<string>` — giá trị tìm kiếm hiện tại (cập nhật ngay lập tức).
+- `searchDelay: Ref<string>` — giá trị tìm kiếm sau khi áp dụng độ trễ (nếu độ trễ được thiết lập).
+- `loading: Ref<boolean>` — `true` trong thời gian chờ độ trễ `delay`.
+
+## Kiến trúc và cách thức hoạt động
+
+`useSearchValueRef` cô lập logic độ trễ (`debounce delay`) khỏi quá trình lọc dữ liệu thực tế.
+Khi người dùng nhập vào `search.value`, composable sẽ:
+1. Ngay lập tức đặt `loading.value = true`.
+2. Chờ trong khoảng thời gian `delay` (tính bằng mili giây) được chỉ định.
+3. Nếu người dùng tiếp tục nhập trong khoảng thời gian chờ, bộ hẹn giờ sẽ đặt lại.
+4. Khi bộ đếm thời gian hoàn thành, nó sao chép `search.value` vào `searchDelay.value` và đặt `loading.value = false`.
+
+Bằng cách sử dụng `searchDelay.value` thay vì `search.value` trong danh sách đã lọc, bạn đảm bảo rằng các thao tác dữ liệu phức tạp chỉ xảy ra sau khi người dùng ngừng nhập, cải thiện đáng kể hiệu suất trên các tập dữ liệu lớn.
+
+## Ví dụ sử dụng
+
+```typescript
+import { useSearchValueRef } from '@dxtmisha/functional'
+import { SearchList } from '@dxtmisha/functional-basic'
+import { ref } from 'vue'
+
+const items = [{ id: 1, name: 'Apple' }]
+const list = new SearchList(items, ['name'], undefined, { delay: 300 })
+const { search, searchDelay, loading } = useSearchValueRef(list)
+
+search.value = 'app'
+// loading.value trở thành true
+// Sau 300ms searchDelay.value sẽ là 'app' và loading.value trở về false
+```

package/src/media/functional/functional/composables/useSessionRef/useSessionRef.en.mdx

@@ -0,0 +1,25 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Composables/useSessionRef - Session storage management'/>
+
+# `useSessionRef`
+
+Composable for managing reactive data in `sessionStorage`. Uses a singleton pattern where elements with the same name share the same reactive state.
+
+**Parameters:**
+- `name: string` — the name of the key in `sessionStorage`.
+- `defaultValue?: T | (() => T)` — the initial value if nothing is found in storage.
+
+**Returns:**
+- `Ref<T | undefined>` — a reactive reference to the session storage value.
+
+## Usage Example
+
+```typescript
+import { useSessionRef } from '@dxtmisha/functional'
+
+const userSession = useSessionRef('user-data', { loggedIn: false })
+
+// Changing the value automatically updates sessionStorage
+userSession.value.loggedIn = true
+```

package/src/media/functional/functional/composables/useSessionRef/useSessionRef.ru.mdx

@@ -0,0 +1,25 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Composables/useSessionRef - Управление сессией хранения'/>
+
+# `useSessionRef`
+
+Composable для управления реактивными данными в `sessionStorage`. Использует паттерн singleton — элементы с одинаковым именем разделяют одно и то же реактивное состояние.
+
+**Параметры:**
+- `name: string` — название ключа в `sessionStorage`.
+- `defaultValue?: T | (() => T)` — значение по умолчанию, если в хранилище ничего не найдено.
+
+**Возвращает:**
+- `Ref<T | undefined>` — реактивная ссылка на значение в сессии хранения.
+
+## Пример использования
+
+```typescript
+import { useSessionRef } from '@dxtmisha/functional'
+
+const userSession = useSessionRef('user-data', { loggedIn: false })
+
+// Изменение значения автоматически обновляет sessionStorage
+userSession.value.loggedIn = true
+```

package/src/media/functional/functional/composables/useSessionRef/useSessionRef.vi.mdx

@@ -0,0 +1,25 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Composables/useSessionRef - Quản lý lưu trữ phiên'/>
+
+# `useSessionRef`
+
+Composable để quản lý dữ liệu phản ứng trong `sessionStorage`. Sử dụng pattern singleton - các phần tử có cùng tên sẽ chia sẻ cùng một trạng thái phản ứng.
+
+**Tham số:**
+- `name: string` — tên của khóa trong `sessionStorage`.
+- `defaultValue?: T | (() => T)` — giá trị mặc định nếu không tìm thấy gì trong bộ nhớ.
+
+**Trả về:**
+- `Ref<T | undefined>` — một tham chiếu phản ứng đến giá trị trong bộ nhớ phiên.
+
+## Ví dụ sử dụng
+
+```typescript
+import { useSessionRef } from '@dxtmisha/functional'
+
+const userSession = useSessionRef('user-data', { loggedIn: false })
+
+// Thay đổi giá trị sẽ tự động cập nhật sessionStorage
+userSession.value.loggedIn = true
+```