@dxtmisha/wiki 0.25.1 → 0.39.2

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

@@ -0,0 +1,107 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Composables/useApiRef - API Requests'/>
+
+# `useApiRef`
+
+A composable for working with API requests in Vue components. Returns reactive data, state flags, and load management methods.
+
+## Key Features
+- **Lazy Initialization**: Requests and dependency watchers are only initialized upon the first access to data (`data` or `item`). This allows declaring `useApiRef` without immediate network or CPU overhead.
+- **Global Scope (Eternal)**: If the `unmounted` parameter is set to `false`, reactivity is moved to `EffectScopeGlobal`. This ensures requests continue to update even after the component that created them is unmounted.
+
+**Parameters:**
+- `path?: RefOrNormal<string | undefined>` — endpoint path (can be a reactive `Ref`).
+- `options?: ApiOptions` — request options (`ApiFetch` object or method name string).
+- `reactivity?: boolean` — automatically re-run the request when `path`, `options`, or locale change. Default: `true`.
+- `conditions?: RefType<boolean>` — reactive execution condition. If `false` — the request is not made and data is cleared.
+- `transformation?: (data: T) => ApiData<R>` — response transformation function applied before saving to `data`.
+- `unmounted?: boolean` — if `true` (default), data is cleared and the watcher is stopped when the component unmounts. When `false`, `EffectScopeGlobal` is used for background persistence.
+- `apiInstance?: ApiInstance` — API instance to use for the request. Defaults to `Api.getItem()`.
+
+**Returns (`UseApiRef<R>`):**
+
+Reactive states:
+- `data: ComputedRef<ApiData<R> | undefined>` — A reference to the loaded data (Computed). Initiates **lazy initialization** (request and watcher) on the first access.
+- `item: Ref<ApiData<R> | undefined>` — Direct reference to data (Ref). Also initiates lazy initialization upon access.
+- `starting: ComputedRef<boolean>` — Returns `true` if data has never been requested yet or is in the process of fetching the first portion of data (`data` is still `undefined`).
+- `loading: Ref<boolean>` — Returns `true` if any network request (initial or subsequent `reset`) is currently in progress.
+- `reading: Ref<boolean>` — A flag for an active data reading/processing process.
+
+Methods:
+- `isStarting(): boolean` — A synchronous method that returns the current value of the `starting` flag.
+- `isLoading(): boolean` — A synchronous method that returns the current value of the `loading` flag.
+- `isReading(): boolean` — A synchronous method that returns the current value of the `reading` flag.
+- `getItem(): ApiData<R> | undefined` — Method to get the current value of `data` without creating a reactive dependency.
+- `init(): void` — Method for explicit request and watcher initialization. Triggered automatically on first access to `data`.
+- `reset(): Promise<void>` — An asynchronous method to force re-run the request. Cancels the current active request (if any) and initiates a new one.
+- `stop(): void` — Stops watching reactive dependencies and resets `data` to `undefined`.
+- `abort(): void` — Cancels the current HTTP request via the internal `AbortController`, while keeping already loaded data in `data`.
+
+## Lazy Initialization
+
+Requests and watching mechanisms **are not started** immediately when `useApiRef` is called. They are activated only when accessing `data`, `item`, or calling `init()`. This optimizes the performance of setup scripts.
+
+## Global Conditions
+
+`setApiRefGlobalConditions(conditions)` — sets a global condition for all `useApiRef` instances. Only works on the first call.
+
+## ApiOptions Object
+
+`ApiOptions` — can accept a string with the `method` name (e.g., `'GET'`) or an object of type `ApiFetch`. Fields of the `ApiFetch` object:
+
+- `path?: string` — path to the endpoint script relative to the base URL (e.g., `'users/list'`).
+- `pathFull?: string` — full URL of the request. If specified, ignores `api` and `path`.
+- `api?: boolean` — whether to add the base URL before `path`. Default: `true`.
+- `method?: ApiMethod` — HTTP method (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`). Default: `'GET'`.
+- `request?: FormData | Record<string, any> | string` — request body (for POST/PUT) or query parameters (for GET). Passed as JSON or `FormData`.
+- `headers?: Record<string, string> | null` — additional request headers. `null` — disable all headers.
+- `type?: string` — `Content-Type` value. Default: `'application/json;charset=UTF-8'`.
+- `auth?: boolean` — whether to add authentication headers.
+- `toData?: boolean` — if `true`, automatically unwraps `data` from the `{ data: ... }` wrapper. Default: `true`.
+- `hideError?: boolean` — suppresses error output to `console.error` on failure. Default: `false`.
+- `globalPreparation?: boolean` — whether to run the global `setPreparation` hook before this request. Default: `true`.
+- `globalEnd?: boolean` — whether to run the global `setEnd` hook after the response. Default: `true`.
+- `queryReturn?: (query: Response) => Promise<any>` — response handler instead of standard JSON reading.
+- `init?: RequestInit` — additional options for native `fetch()` (CORS, cache mode, etc.).
+- `controller?: AbortController` — controller for canceling the request.
+
+## Example
+
+```typescript
+import { ref } from 'vue'
+import { useApiRef, setApiRefGlobalConditions } from '@dxtmisha/functional'
+
+const userId = ref('123')
+const isAuthenticated = ref(true)
+
+// Global condition (all requests only run if authenticated)
+setApiRefGlobalConditions(isAuthenticated)
+
+const {
+  data: user,
+  starting,
+  loading,
+  reading,
+  getItem,
+  reset,
+  stop,
+  abort
+} = useApiRef(
+  () => `users/${userId.value}`,
+  { method: 'GET' },
+  true // Reactively re-run on userId change
+)
+
+// Check state without reactivity
+console.log(getItem()) // undefined before first access to data
+
+// Force reload
+await reset()
+
+// Cancel request (without clearing data)
+abort()
+
+// Stop watching (clears data)
+stop()
+```

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

@@ -0,0 +1,107 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Composables/useApiRef - Работа с запросами'/>
+
+# `useApiRef`
+
+Composable для удобной работы с API-запросами во Vue-компонентах. Возвращает реактивные данные, флаги состояния и методы управления загрузкой.
+
+## Особенности
+- **Ленивая инициализация**: Запрос и наблюдение за зависимостями (watchers) инициализируются только при первом обращении к данным (`data` или `item`). Это позволяет объявлять `useApiRef` без немедленной нагрузки на сеть и процессор.
+- **Глобальная область видимости (Eternal)**: Если параметр `unmounted` установлен в `false`, реактивность выносится в `EffectScopeGlobal`. Это гарантирует, что запросы продолжат обновляться даже после размонтирования компонента, который их создал.
+
+**Параметры:**
+- `path?: RefOrNormal<string | undefined>` — путь к endpoint (может быть реактивным `Ref`).
+- `options?: ApiOptions` — опции запроса (объект `ApiFetch` или строка с именем метода).
+- `reactivity?: boolean` — автоматически перезапускать запрос при изменении `path`, `options` или локали. По умолчанию: `true`.
+- `conditions?: RefType<boolean>` — реактивное условие выполнения. Если `false` — запрос не выполняется, данные сбрасываются.
+- `transformation?: (data: T) => ApiData<R>` — функция преобразования ответа перед сохранением в `data`.
+- `unmounted?: boolean` — если `true` (по умолчанию), данные сбрасываются и watcher останавливается при размонтировании компонента. При `false` используется `EffectScopeGlobal` для фоновой работы.
+- `apiInstance?: ApiInstance` — Экземпляр API, используемый для выполнения запроса. По умолчанию `Api.getItem()`.
+
+**Возвращает (`UseApiRef<R>`):**
+
+Реактивные состояния:
+- `data: ComputedRef<ApiData<R> | undefined>` — Ссылка на загруженные данные (Computed). Инициирует **ленивую инициализацию** (запрос и watcher) при первом обращении.
+- `item: Ref<ApiData<R> | undefined>` — Прямая ссылка на данные (Ref). Также инициирует ленивую инициализацию при доступе.
+- `starting: ComputedRef<boolean>` — Возвращает `true`, если данные еще ни разу не запрашивались или находятся в процессе получения первой порции данных (`data` еще `undefined`).
+- `loading: Ref<boolean>` — Возвращает `true`, если в данный момент выполняется любой сетевой запрос (первичный или последующий `reset`).
+- `reading: Ref<boolean>` — Флаг активного процесса чтения/обработки данных.
+
+Методы:
+- `isStarting(): boolean` — Синхронный метод, возвращающий текущее значение флага `starting`.
+- `isLoading(): boolean` — Синхронный метод, возвращающий текущее значение флага `loading`.
+- `isReading(): boolean` — Синхронный метод, возвращающий текущее значение флага `reading`.
+- `getItem(): ApiData<R> | undefined` — Метод для получения текущего значения `data` без создания реактивной зависимости.
+- `init(): void` — Метод для явной инициализации запроса и watchers. Вызывается автоматически при первом обращении к `data`.
+- `reset(): Promise<void>` — Асинхронный метод для принудительного перезапуска запроса. Отменяет текущий активный запрос (если есть) и инициирует новый.
+- `stop(): void` — Останавливает наблюдение за реактивными зависимостями и сбрасывает `data` в `undefined`.
+- `abort(): void` — Вызывает отмену текущего HTTP-запроса через внутренний `AbortController`, сохраняя при этом уже загруженные данные в `data`.
+
+## Ленивая инициализация (Lazy Loading)
+
+Запрос и механизмы слежения за изменениями **не запускаются** непосредственно при вызове `useApiRef`. Они активируются только при обращении к `data`, `item` или вызове `init()`. Это позволяет оптимизировать производительность setup-скриптов.
+
+## Глобальные условия
+
+`setApiRefGlobalConditions(conditions)` — устанавливает глобальное условие для всех экземпляров `useApiRef`. Работает только один раз.
+
+## Объект ApiOptions
+
+`ApiOptions` — может принимать строку с названием `method` (например, `'GET'`) или объект типа `ApiFetch`. Поля объекта `ApiFetch`:
+
+- `path?: string` — путь к endpoint-скрипту относительно базового URL (например: `'users/list'`).
+- `pathFull?: string` — полный URL запроса. Если указан, игнорирует `api` и `path`.
+- `api?: boolean` — добавлять ли базовый URL перед `path`. По умолчанию: `true`.
+- `method?: ApiMethod` — HTTP-метод (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`). По умолчанию: `'GET'`.
+- `request?: FormData | Record<string, any> | string` — тело запроса (для POST/PUT) или query-параметры (для GET). Передается как JSON или `FormData`.
+- `headers?: Record<string, string> | null` — дополнительные заголовки запроса. `null` — отключить все заголовки.
+- `type?: string` — значение `Content-Type`. По умолчанию: `'application/json;charset=UTF-8'`.
+- `auth?: boolean` — добавить заголовки аутентификации.
+- `toData?: boolean` — если `true`, автоматически разворачивает `data` из обертки `{ data: ... }`. По умолчанию: `true`.
+- `hideError?: boolean` — подавляет вывод ошибок в `console.error` при сбое. По умолчанию: `false`.
+- `globalPreparation?: boolean` — запускать ли глобальный хук `setPreparation` до этого запроса. По умолчанию: `true`.
+- `globalEnd?: boolean` — запускать ли глобальный хук `setEnd` после ответа. По умолчанию: `true`.
+- `queryReturn?: (query: Response) => Promise<any>` — обработчик ответа вместо стандартного чтения JSON.
+- `init?: RequestInit` — дополнительные опции для нативного `fetch()` (CORS, режим кеша и др.).
+- `controller?: AbortController` — контроллер для отмены запроса.
+
+## Пример
+
+```typescript
+import { ref } from 'vue'
+import { useApiRef, setApiRefGlobalConditions } from '@dxtmisha/functional'
+
+const userId = ref('123')
+const isAuthenticated = ref(true)
+
+// Глобальное условие (все запросы выполняются только если аутентифицированы)
+setApiRefGlobalConditions(isAuthenticated)
+
+const {
+  data: user,
+  starting,
+  loading,
+  reading,
+  getItem,
+  reset,
+  stop,
+  abort
+} = useApiRef(
+  () => `users/${userId.value}`,
+  { method: 'GET' },
+  true // Реактивно перезапускать при изменении userId
+)
+
+// Проверка состояния без реактивности
+console.log(getItem()) // undefined до первого обращения к data
+
+// Принудительная перезагрузка
+await reset()
+
+// Отмена запроса (без сброса данных)
+abort()
+
+// Остановка слежения (сбрасывает данные)
+stop()
+```

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

@@ -0,0 +1,107 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Composables/useApiRef - Yêu cầu API'/>
+
+# `useApiRef`
+
+Composable để làm việc với các yêu cầu API trong Vue component. Trả về dữ liệu phản ứng, cờ trạng thái và các phương thức quản lý tải.
+
+## Các tính năng chính
+- **Khởi tạo lười (Lazy)**: Các yêu cầu và watcher phụ thuộc chỉ được khởi tạo khi truy cập lần đầu vào dữ liệu (`data` hoặc `item`). Điều này cho phép khai báo `useApiRef` mà không gây ra tải mạng hoặc CPU ngay lập tức.
+- **Phạm vi toàn cục (Eternal)**: Nếu tham số `unmounted` được đặt thành `false`, tính phản ứng sẽ được chuyển sang `EffectScopeGlobal`. Điều này đảm bảo các yêu cầu tiếp tục cập nhật ngay cả sau khi component tạo ra chúng bị unmount.
+
+**Tham số:**
+- `path?: RefOrNormal<string | undefined>` — đường dẫn endpoint (có thể là `Ref` phản ứng).
+- `options?: ApiOptions` — tùy chọn yêu cầu (đối tượng `ApiFetch` hoặc chuỗi tên phương thức).
+- `reactivity?: boolean` — tự động chạy lại yêu cầu khi `path`, `options` hoặc ngôn ngữ thay đổi. Mặc định: `true`.
+- `conditions?: RefType<boolean>` — điều kiện thực thi phản ứng. Nếu `false` — yêu cầu không được thực hiện và dữ liệu bị xóa.
+- `transformation?: (data: T) => ApiData<R>` — hàm chuyển đổi phản hồi trước khi lưu vào `data`.
+- `unmounted?: boolean` — nếu `true` (mặc định), dữ liệu bị xóa và watcher dừng lại khi component unmount. Khi `false`, `EffectScopeGlobal` được sử dụng để duy trì chạy nền.
+- `apiInstance?: ApiInstance` — Phiên bản API sử dụng cho yêu cầu. Mặc định là `Api.getItem()`.
+
+**Trả về (`UseApiRef<R>`):**
+
+Trạng thái phản ứng:
+- `data: ComputedRef<ApiData<R> | undefined>` — Tham chiếu đến dữ liệu đã tải (Computed). Bắt đầu **khởi tạo lười** (yêu cầu và watcher) khi truy cập lần đầu.
+- `item: Ref<ApiData<R> | undefined>` — Tham chiếu trực tiếp đến dữ liệu (Ref). Cũng bắt đầu khởi tạo lười khi truy cập.
+- `starting: ComputedRef<boolean>` — Trả về `true` nếu dữ liệu chưa bao giờ được yêu cầu hoặc đang trong quá trình lấy phần dữ liệu đầu tiên (`data` vẫn là `undefined`).
+- `loading: Ref<boolean>` — Trả về `true` nếu bất kỳ yêu cầu mạng nào (ban đầu hoặc `reset` sau đó) hiện đang được thực hiện.
+- `reading: Ref<boolean>` — Cờ cho quá trình đọc/xử lý dữ liệu đang hoạt động.
+
+Phương thức:
+- `isStarting(): boolean` — Phương thức đồng bộ trả về giá trị hiện tại của cờ `starting`.
+- `isLoading(): boolean` — Phương thức đồng bộ trả về giá trị hiện tại của cờ `loading`.
+- `isReading(): boolean` — Phương thức đồng bộ trả về giá trị hiện tại của cờ `reading`.
+- `getItem(): ApiData<R> | undefined` — Phương thức để lấy giá trị hiện tại của `data` mà không tạo ra phụ thuộc phản ứng.
+- `init(): void` — Phương thức để khởi tạo yêu cầu và watcher một cách rõ ràng. Tự động kích hoạt khi truy cập `data` lần đầu.
+- `reset(): Promise<void>` — Phương thức bất đồng bộ để buộc chạy lại yêu cầu. Hủy yêu cầu hiện tại (nếu có) và bắt đầu một yêu cầu mới.
+- `stop(): void` — Dừng việc theo dõi các phụ thuộc phản ứng và đặt lại `data` thành `undefined`.
+- `abort(): void` — Hủy yêu cầu HTTP hiện tại thông qua `AbortController` nội bộ, trong khi vẫn giữ lại dữ liệu đã tải trong `data`.
+
+## Khởi tạo lười (Lazy Initialization)
+
+Yêu cầu và cơ chế theo dõi thay đổi **không được bắt đầu** ngay lập tức khi gọi `useApiRef`. Chúng chỉ được kích hoạt khi truy cập `data`, `item` hoặc gọi `init()`. Điều này tối ưu hóa hiệu suất của các script setup.
+
+## Điều kiện toàn cục
+
+`setApiRefGlobalConditions(conditions)` — thiết lập điều kiện toàn cục cho tất cả các instance `useApiRef`. Chỉ có hiệu lực một lần.
+
+## Đối tượng ApiOptions
+
+`ApiOptions` — có thể nhận một chuỗi tên `method` (ví dụ: `'GET'`) hoặc một đối tượng kiểu `ApiFetch`. Các trường của đối tượng `ApiFetch`:
+
+- `path?: string` — đường dẫn đến endpoint script tương đối so với URL cơ bản (ví dụ: `'users/list'`).
+- `pathFull?: string` — URL đầy đủ của yêu cầu. Nếu được chỉ định, sẽ bỏ qua `api` và `path`.
+- `api?: boolean` — có thêm URL cơ bản trước `path` hay không. Mặc định: `true`.
+- `method?: ApiMethod` — phương thức HTTP (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`). Mặc định: `'GET'`.
+- `request?: FormData | Record<string, any> | string` — thân yêu cầu (cho POST/PUT) hoặc các tham số truy vấn (cho GET). Được truyền dưới dạng JSON hoặc `FormData`.
+- `headers?: Record<string, string> | null` — các tiêu đề yêu cầu bổ sung. `null` — vô hiệu hóa tất cả các tiêu đề.
+- `type?: string` — giá trị `Content-Type`. Mặc định: `'application/json;charset=UTF-8'`.
+- `auth?: boolean` — có thêm các tiêu đề xác thực hay không.
+- `toData?: boolean` — nếu `true`, tự động giải nén `data` từ vỏ bọc `{ data: ... }`. Mặc định: `true`.
+- `hideError?: boolean` — ngăn chặn việc xuất lỗi ra `console.error` khi thất bại. Mặc định: `false`.
+- `globalPreparation?: boolean` — có chạy hook toàn cục `setPreparation` trước yêu cầu này hay không. Mặc định: `true`.
+- `globalEnd?: boolean` — có chạy hook toàn cục `setEnd` sau phản hồi hay không. Mặc định: `true`.
+- `queryReturn?: (query: Response) => Promise<any>` — trình xử lý phản hồi thay vì đọc JSON tiêu chuẩn.
+- `init?: RequestInit` — các tùy chọn bổ sung cho `fetch()` gốc (CORS, chế độ cache, v.v.).
+- `controller?: AbortController` — bộ điều khiển để hủy yêu cầu.
+
+## Ví dụ
+
+```typescript
+import { ref } from 'vue'
+import { useApiRef, setApiRefGlobalConditions } from '@dxtmisha/functional'
+
+const userId = ref('123')
+const isAuthenticated = ref(true)
+
+// Điều kiện toàn cục (tất cả yêu cầu chỉ chạy nếu đã xác thực)
+setApiRefGlobalConditions(isAuthenticated)
+
+const {
+  data: user,
+  starting,
+  loading,
+  reading,
+  getItem,
+  reset,
+  stop,
+  abort
+} = useApiRef(
+  () => `users/${userId.value}`,
+  { method: 'GET' },
+  true // Tự động chạy lại khi userId thay đổi
+)
+
+// Kiểm tra trạng thái không có tính phản ứng
+console.log(getItem()) // undefined trước khi truy cập data lần đầu
+
+// Tải lại bắt buộc
+await reset()
+
+// Hủy yêu cầu (không xóa dữ liệu)
+abort()
+
+// Dừng theo dõi (xóa dữ liệu)
+stop()
+```

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

@@ -0,0 +1,60 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Composables/useApiRequest - API Request Execution'/>
+
+# `useApiRequest`
+
+Returns an object with a loading state and a `send` method for executing API requests.
+
+**Parameters:**
+- `path?: RefOrNormal<string | undefined>` — Path to the API endpoint (can be reactive).
+- `method: ApiMethodItem = ApiMethodItem.post` — HTTP method to use for the request.
+- `action?: (data: Return | undefined) => Promise<void> | void` — Callback action to perform after the request completes successfully.
+- `transformation?: (data: T) => Return` — Function to transform the response data before it is returned or passed to the `action`.
+- `toData: boolean = true` — Whether to extract the `data` field from the response.
+- `options?: ApiOptions` — Additional request options (`ApiFetch` object parameter).
+- `apiInstance?: ApiInstance` — API instance to use for the request. Defaults to `Api.getItem()`.
+
+**Returns:**
+An object with the following properties:
+- `loading: Ref<boolean>` — Reactive loading state. It becomes `true` while the request is in progress and `false` after it completes or fails.
+- `send(request?: Request): Promise<Return | undefined>` — An asynchronous method for sending the request. It automatically manages the `loading` state, applies the transformation function to the response, executes the `action` callback on success, and handles errors safely by logging them to the console.
+
+## ApiOptions Object
+
+`ApiOptions` — can accept a string with the `method` name (e.g., `'GET'`) or an object of type `ApiFetch`. Fields of the `ApiFetch` object:
+
+- `path?: string` — path to the endpoint script relative to the base URL (e.g., `'users/list'`).
+- `pathFull?: string` — full URL of the request. If specified, ignores `api` and `path`.
+- `api?: boolean` — whether to add the base URL before `path`. Default: `true`.
+- `method?: ApiMethod` — HTTP method (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`). Default: `'GET'`.
+- `request?: FormData | Record<string, any> | string` — request body (for POST/PUT) or query parameters (for GET). Passed as JSON or `FormData`.
+- `headers?: Record<string, string> | null` — additional request headers. `null` — disable all headers.
+- `type?: string` — `Content-Type` value. Default: `'application/json;charset=UTF-8'`.
+- `auth?: boolean` — whether to add authentication headers.
+- `toData?: boolean` — if `true`, automatically unwraps `data` from the `{ data: ... }` wrapper. Default: `true`.
+- `hideError?: boolean` — suppresses error output to `console.error` on failure. Default: `false`.
+- `globalPreparation?: boolean` — whether to run the global `setPreparation` hook before this request. Default: `true`.
+- `globalEnd?: boolean` — whether to run the global `setEnd` hook after the response. Default: `true`.
+- `queryReturn?: (query: Response) => Promise<any>` — response handler instead of standard JSON reading.
+- `init?: RequestInit` — additional options for native `fetch()` (CORS, cache mode, etc.).
+- `controller?: AbortController` — controller for canceling the request.
+
+```typescript
+import { useApiRequest } from '@dxtmisha/functional'
+import { ApiMethodItem } from '@dxtmisha/functional-basic'
+
+const { loading, send } = useApiRequest(
+  '/api/submit',
+  ApiMethodItem.post,
+  (data) => console.log('Action complete:', data),
+  (raw) => ({ ...raw, processed: true }),
+  true,
+  { cache: false }
+)
+
+const handleSubmit = async () => {
+  const result = await send({ name: 'User' })
+  console.log('Final Result:', result)
+}
+```

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

@@ -0,0 +1,60 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Composables/useApiRequest - Выполнение запросов'/>
+
+# `useApiRequest`
+
+Возвращает объект с состоянием загрузки и методом `send` для выполнения запросов к API.
+
+**Параметры:**
+- `path?: RefOrNormal<string | undefined>` — Путь к endpoint API (может быть реактивным).
+- `method: ApiMethodItem = ApiMethodItem.post` — HTTP метод для запроса.
+- `action?: (data: Return | undefined) => Promise<void> | void` — Действие (коллбэк), выполняемое после успешного завершения запроса.
+- `transformation?: (data: T) => Return` — Функция трансформации ответа от сервера перед возвращением или передачей в `action`.
+- `toData: boolean = true` — Извлекать ли поле `data` из ответа.
+- `options?: ApiOptions` — Дополнительные опции запроса (объект параметров `ApiFetch`).
+- `apiInstance?: ApiInstance` — Экземпляр API, используемый для выполнения запроса. По умолчанию `Api.getItem()`.
+
+**Возвращает:**
+Объект со следующими свойствами:
+- `loading: Ref<boolean>` — Реактивное состояние загрузки. Принимает значение `true` во время выполнения запроса и `false` после его завершения или ошибки.
+- `send(request?: Request): Promise<Return | undefined>` — Асинхронный метод для отправки запроса. Он автоматически управляет состоянием `loading`, применяет функцию трансформации к ответу, вызывает коллбэк `action` при успехе и безопасно обрабатывает ошибки, выводя их в консоль.
+
+## Объект ApiOptions
+
+`ApiOptions` — может принимать строку с названием `method` (например, `'GET'`) или объект типа `ApiFetch`. Поля объекта `ApiFetch`:
+
+- `path?: string` — путь к endpoint-скрипту относительно базового URL (например: `'users/list'`).
+- `pathFull?: string` — полный URL запроса. Если указан, игнорирует `api` и `path`.
+- `api?: boolean` — добавлять ли базовый URL перед `path`. По умолчанию: `true`.
+- `method?: ApiMethod` — HTTP-метод (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`). По умолчанию: `'GET'`.
+- `request?: FormData | Record<string, any> | string` — тело запроса (для POST/PUT) или query-параметры (для GET). Передается как JSON или `FormData`.
+- `headers?: Record<string, string> | null` — дополнительные заголовки запроса. `null` — отключить все заголовки.
+- `type?: string` — значение `Content-Type`. По умолчанию: `'application/json;charset=UTF-8'`.
+- `auth?: boolean` — добавить заголовки аутентификации.
+- `toData?: boolean` — если `true`, автоматически разворачивает `data` из обертки `{ data: ... }`. По умолчанию: `true`.
+- `hideError?: boolean` — подавляет вывод ошибок в `console.error` при сбое. По умолчанию: `false`.
+- `globalPreparation?: boolean` — запускать ли глобальный хук `setPreparation` до этого запроса. По умолчанию: `true`.
+- `globalEnd?: boolean` — запускать ли глобальный хук `setEnd` после ответа. По умолчанию: `true`.
+- `queryReturn?: (query: Response) => Promise<any>` — обработчик ответа вместо стандартного чтения JSON.
+- `init?: RequestInit` — дополнительные опции для нативного `fetch()` (CORS, режим кеша и др.).
+- `controller?: AbortController` — контроллер для отмены запроса.
+
+```typescript
+import { useApiRequest } from '@dxtmisha/functional'
+import { ApiMethodItem } from '@dxtmisha/functional-basic'
+
+const { loading, send } = useApiRequest(
+  '/api/submit',
+  ApiMethodItem.post,
+  (data) => console.log('Действие завершено:', data),
+  (raw) => ({ ...raw, processed: true }),
+  true,
+  { cache: false }
+)
+
+const handleSubmit = async () => {
+  const result = await send({ name: 'User' })
+  console.log('Итоговый результат:', result)
+}
+```

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

@@ -0,0 +1,60 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Composables/useApiRequest - Thực hiện các yêu cầu'/>
+
+# `useApiRequest`
+
+Trả về một đối tượng với trạng thái tải và phương thức `send` để thực hiện các yêu cầu API.
+
+**Tham số:**
+- `path?: RefOrNormal<string | undefined>` — Đường dẫn đến endpoint API (có thể phản ứng).
+- `method: ApiMethodItem = ApiMethodItem.post` — Phương thức HTTP cho yêu cầu.
+- `action?: (data: Return | undefined) => Promise<void> | void` — Hành động (callback) thực hiện sau khi yêu cầu hoàn tất thành công.
+- `transformation?: (data: T) => Return` — Hàm chuyển đổi dữ liệu phản hồi từ máy chủ trước khi trả về hoặc truyền vào `action`.
+- `toData: boolean = true` — Việc trích xuất trường `data` từ phản hồi hay không.
+- `options?: ApiOptions` — Các tùy chọn bổ sung cho yêu cầu (đối tượng tham số `ApiFetch`).
+- `apiInstance?: ApiInstance` — Phiên bản API sử dụng cho yêu cầu. Mặc định là `Api.getItem()`.
+
+**Giá trị t**Trả về:**
+Một đối tượng với các thuộc tính sau:
+- `loading: Ref<boolean>` — Trạng thái tải phản ứng. Sẽ là `true` trong khi yêu cầu đang thực hiện và `false` sau khi hoàn thành hoặc có lỗi.
+- `send(request?: Request): Promise<Return | undefined>` — Phương thức bất đồng bộ để gửi yêu cầu. Nó tự động quản lý trạng thái `loading`, áp dụng hàm biến đổi cho phản hồi, thực hiện callback `action` khi thành công và xử lý lỗi một cách an toàn bằng cách ghi log ra console.
+
+## Đối tượng ApiOptions
+
+`ApiOptions` — có thể nhận một chuỗi tên `method` (ví dụ: `'GET'`) hoặc một đối tượng kiểu `ApiFetch`. Các trường của đối tượng `ApiFetch`:
+
+- `path?: string` — đường dẫn đến endpoint script tương đối so với URL cơ bản (ví dụ: `'users/list'`).
+- `pathFull?: string` — URL đầy đủ của yêu cầu. Nếu được chỉ định, sẽ bỏ qua `api` và `path`.
+- `api?: boolean` — có thêm URL cơ bản trước `path` hay không. Mặc định: `true`.
+- `method?: ApiMethod` — phương thức HTTP (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`). Mặc định: `'GET'`.
+- `request?: FormData | Record<string, any> | string` — thân yêu cầu (cho POST/PUT) hoặc các tham số truy vấn (cho GET). Được truyền dưới dạng JSON hoặc `FormData`.
+- `headers?: Record<string, string> | null` — các tiêu đề yêu cầu bổ sung. `null` — vô hiệu hóa tất cả các tiêu đề.
+- `type?: string` — giá trị `Content-Type`. Mặc định: `'application/json;charset=UTF-8'`.
+- `auth?: boolean` — có thêm các tiêu đề xác thực hay không.
+- `toData?: boolean` — nếu `true`, tự động giải nén `data` từ vỏ bọc `{ data: ... }`. Mặc định: `true`.
+- `hideError?: boolean` — ngăn chặn việc xuất lỗi ra `console.error` khi thất bại. Mặc định: `false`.
+- `globalPreparation?: boolean` — có chạy hook toàn cục `setPreparation` trước yêu cầu này hay không. Mặc định: `true`.
+- `globalEnd?: boolean` — có chạy hook toàn cục `setEnd` sau phản hồi hay không. Mặc định: `true`.
+- `queryReturn?: (query: Response) => Promise<any>` — trình xử lý phản hồi thay vì đọc JSON tiêu chuẩn.
+- `init?: RequestInit` — các tùy chọn bổ sung cho `fetch()` gốc (CORS, chế độ cache, v.v.).
+- `controller?: AbortController` — bộ điều khiển để hủy yêu cầu.
+
+```typescript
+import { useApiRequest } from '@dxtmisha/functional'
+import { ApiMethodItem } from '@dxtmisha/functional-basic'
+
+const { loading, send } = useApiRequest(
+  '/api/submit',
+  ApiMethodItem.post,
+  (data) => console.log('Hành động hoàn tất:', data),
+  (raw) => ({ ...raw, processed: true }),
+  true,
+  { cache: false }
+)
+
+const handleSubmit = async () => {
+  const result = await send({ name: 'User' })
+  console.log('Kết quả cuối cùng:', result)
+}
+```

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

@@ -0,0 +1,32 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Composables/useBroadcastValueRef - Data Syncing Between Tabs'/>
+
+# `useBroadcastValueRef`
+
+A composable for creating a reactive variable whose value is synchronized across all open browser tabs within the same domain. It uses `BroadcastChannel` via the `BroadcastMessage` class.
+
+**Parameters:**
+- `name: string` — a unique name for the value. This will be used to create the communication channel.
+- `defaultValue?: T | string | (() => (T | string))` — default value. Can be static or a function.
+
+**Returns:**
+- `Ref<T | string | undefined>` — a reactive reference to the value. When the value changes in one tab, it automatically updates in all others.
+
+**Key Features:**
+- Uses the **Singleton** pattern: calling it with the same `name` within one application returns the same `Ref` instance.
+- Automatically prefixes the name with `broadcast--`.
+
+## Usage Example
+
+```typescript
+import { useBroadcastValueRef } from '@dxtmisha/functional'
+
+// Tab 1
+const userStatus = useBroadcastValueRef('user-status', 'offline')
+userStatus.value = 'online'
+
+// Tab 2 (same domain)
+const userStatus = useBroadcastValueRef('user-status', 'offline')
+// userStatus.value automatically becomes 'online'
+```

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

@@ -0,0 +1,32 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Composables/useBroadcastValueRef - Синхронизация данных между вкладками'/>
+
+# `useBroadcastValueRef`
+
+Composable для создания реактивной переменной, значение которой синхронизируется между всеми открытыми вкладками браузера в рамках одного домена. Использует `BroadcastChannel` через класс `BroadcastMessage`.
+
+**Параметры:**
+- `name: string` — уникальное имя значения. Будет использовано для создания канала связи.
+- `defaultValue?: T | string | (() => (T | string))` — значение по умолчанию. Может быть статичным или функцией.
+
+**Возвращает:**
+- `Ref<T | string | undefined>` — реактивная ссылка на значение. При изменении значения в одной вкладке, оно автоматически обновится во всех остальных.
+
+**Особенности:**
+- Использует паттерн **Singleton**: при вызове с тем же именем `name` в рамках одного приложения, вернется та же самая ссылка `Ref`.
+- Автоматически оборачивает имя в префикс `broadcast--`.
+
+## Пример использования
+
+```typescript
+import { useBroadcastValueRef } from '@dxtmisha/functional'
+
+// Вкладка 1
+const userStatus = useBroadcastValueRef('user-status', 'offline')
+userStatus.value = 'online'
+
+// Вкладка 2 (тот же домен)
+const userStatus = useBroadcastValueRef('user-status', 'offline')
+// userStatus.value автоматически станет 'online'
+```

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

@@ -0,0 +1,32 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Composables/useBroadcastValueRef - Đồng bộ dữ liệu giữa các tab'/>
+
+# `useBroadcastValueRef`
+
+Composable để tạo một biến phản hồi (reactive) mà giá trị của nó được đồng bộ hóa trên tất cả các tab trình duyệt đang mở trong cùng một miền (domain). Nó sử dụng `BroadcastChannel` thông qua lớp `BroadcastMessage`.
+
+**Tham số:**
+- `name: string` — tên duy nhất cho giá trị. Tên này sẽ được sử dụng để tạo kênh giao tiếp.
+- `defaultValue?: T | string | (() => (T | string))` — giá trị mặc định. Có thể là giá trị tĩnh hoặc một hàm.
+
+**Trả về:**
+- `Ref<T | string | undefined>` — một tham chiếu phản hồi (Ref) cho giá trị. Khi giá trị thay đổi trong một tab, nó sẽ tự động cập nhật trong tất cả các tab khác.
+
+**Tính năng chính:**
+- Sử dụng mẫu **Singleton**: gọi nó với cùng một `name` trong cùng một ứng dụng sẽ trả về cùng một phiên bản `Ref`.
+- Tự động thêm tiền tố `broadcast--` vào tên.
+
+## Ví dụ sử dụng
+
+```typescript
+import { useBroadcastValueRef } from '@dxtmisha/functional'
+
+// Tab 1
+const userStatus = useBroadcastValueRef('user-status', 'offline')
+userStatus.value = 'online'
+
+// Tab 2 (cùng domain)
+const userStatus = useBroadcastValueRef('user-status', 'offline')
+// userStatus.value sẽ tự động trở thành 'online'
+```

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

@@ -0,0 +1,29 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Composables/useCookieRef - Cookie Management'/>
+
+# `useCookieRef`
+
+A composable for working with browser cookies. It allows creating reactive variables that automatically synchronize with cookies. It also supports cross-tab synchronization via `BroadcastChannel`.
+
+**Parameters:**
+- `name: string` — Cookie name.
+- `defaultValue?: T | string | (() => (T | string))` — Default value. Can be a static value or a function.
+- `options?: CookieOptions` — Additional parameters for cookie management (expires, path, domain, etc.).
+
+**Returns (`Ref<T | string | undefined>`):**
+- A reactive reference to the cookie value.
+
+## Example
+
+```typescript
+import { useCookieRef } from '@dxtmisha/functional'
+
+// Create a reference to 'theme' cookie with 'light' as default
+const theme = useCookieRef('theme', 'light', { age: 365 * 24 * 60 * 60 })
+
+// Update value (automatically saved to cookie)
+theme.value = 'dark'
+
+// The value will be synchronized across all browser tabs in real-time
+```