@dxtmisha/wiki 0.25.1 → 0.39.2

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

@@ -0,0 +1,124 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Composables/useApiManagementRef - API Management'/>
+
+# `useApiManagementRef`
+
+A powerful composable for comprehensive API request orchestration. It manages data fetching (GET), list formatting, client-side searching, and mutations (POST, PUT, DELETE) all within a single reactive interface.
+
+## Parameters
+- `propsGet: ApiManagementGet<Return, Type>` — configuration for the main GET request (path, reactivity, skeleton, etc.).
+- `formattersOptions?: FormattersOptions` — optional reactive formatting rules (`useFormattersRef`).
+- `searchOptions?: ApiManagementSearch<Item, Columns>` — optional client-side search configuration (`useSearchRef`).
+- `postRequest?: ApiManagementRequest<Post>` — optional config for a POST creation request.
+- `putRequest?: ApiManagementRequest<Put>` — optional config for a PUT update request.
+- `deleteRequest?: ApiManagementRequest<Delete>` — optional config for a DELETE removal request.
+- `action?: function` — a common callback to perform after any successful mutation.
+- `apiInstance?: ApiInstance` — API instance to use for the request. Defaults to `Api.getItem()`.
+
+## Returns
+- `isValid: ComputedRef<boolean>` — `true` if data matches `typeData` check.
+- `list: ComputedRef` — the processed data array. **Supports Skeleton**: if data is not yet loaded and a `skeleton()` is provided, it returns placeholders. Accounts for search filters and formatters.
+- `data: ComputedRef<ApiData<Return> | undefined>` — the raw reactive data from `useApiRef`.
+- `length: ComputedRef<number>` — current length of the `list` (dynamically updates when searching).
+- `lengthData: ComputedRef<number>` — original length of the data in `data.value`.
+- `starting: ComputedRef<boolean>` — `true` if the request is still in its initial loading phase.
+- `reading: Ref<boolean>` — flag indicating the data is currently being fetched/read from the server.
+- `loading: Ref<boolean>` — loading state of the main GET request.
+- `loadingSearch: Ref<boolean>` — loading state of the search operation.
+- `loadingPost / loadingPut / loadingDelete` — individual loading sub-states for each mutation.
+- `isSearch: ComputedRef<boolean>` — whether a search query is currently active.
+- `search: Ref<string>` — reactive search string (Proxy to the provided `searchOptions.value`).
+- `sendPost / sendPut / sendDelete: (request?: ApiFetch['request']) => Promise<any>` — methods to execute mutations.
+- `reset: () => Promise<void>` — forces a manual restart/refresh of the main GET request.
+- `abort: () => void` — aborts the ongoing network request.
+
+## Generic Constraints
+
+- `Return extends ApiManagementValue` — logic model for data returned by the API.
+- `FormattersOptions extends FormattersOptionsList` — optional formatting rules.
+- `Post / Put / Delete extends Record<string, any>` — data types for the respective mutation requests.
+- `Type extends ApiManagementValue = Return` — the original raw data type (before transformation).
+- `Item extends ArrayToItem<Return>` — the type of a single item in the data list.
+- `ItemFormatters extends FormattersListColumns<Item, FormattersOptions>[number]` — the item type after formatters are applied.
+- `Columns extends SearchColumns<ItemFormatters>` — columns used for searching.
+
+## How to work with it
+
+`useApiManagementRef` is the central hub for data management in CRUD interfaces. It combines network requests, local search, and formatting into a single automated cycle:
+
+1.  **Initialization and Lazy Loading**: The hook does not send the network request immediately. The GET request is queued only when your component first accesses the `list` or `data` property. This saves resources if the data is not always needed on the screen.
+2.  **Instant Response (Skeleton)**: If you provide a `skeleton` function, the `list` property will immediately return an array of "placeholders" when loading starts. This allows you to render the table or list structure before the first byte of data arrives, eliminating UI "jumps".
+3.  **Smart List (`list`)**: This is the primary point of interaction. The `list` property automatically switches between:
+    - Skeleton data (during loading).
+    - Search results (if a search query is entered).
+    - Formatted data (if `formattersOptions` are configured).
+    - Raw data (if none of the above applies).
+4.  **Search and Format Synchronization**: Searching is performed on data that is already loaded and, if necessary, formatted. This ensures that a user can find "John Doe" even if the raw JSON data stores these in separate fields. Searching happens on the client side (Client-side), providing instant results.
+5.  **Mutation Cycle and Auto-Refresh**: 
+    - When calling `sendPost`, `sendPut`, or `sendDelete` methods, the hook tracks the response status. 
+    - If the server returns success (verified via `isApiSuccess`), the hook **automatically** calls `reset()` for the main GET request. 
+    - This triggers a data reload and updates the entire list. Thus, after deleting a row or adding a new one, your list always remains up to date without writing extra code.
+6.  **Parameter Reactivity**: If the `path` or `options` (in `propsGet`) are reactive (Vue Ref) and you set `reactivity: true`, the hook will watch for changes and automatically reload data when the URL or filtering parameters change.
+
+## Core Architecture
+
+`useApiManagementRef` is an orchestrator hook designed to manage standard CRUD views (like data tables). By passing configurations, you get an all-in-one return object that manages loading spinners, searches, formats data for display, handles CRUD actions, and automatically refetches lists.
+
+## Types
+
+### `ApiManagementGet<Return, Type>`
+- `path?: string | Ref<string>` — API path.
+- `options?: ApiOptions` — request options (method, headers, etc.).
+- `reactivity?: boolean` — whether to automatically refetch when `path` or `options` change.
+- `conditions?: Ref<boolean>` — condition under which the request is executed.
+- `transformation?: (data: Type) => ApiData<Return>` — function to transform data after fetching.
+- `typeData?: ((data: Return) => boolean) | any` — data validation function or constructor (e.g., `Array`).
+- `unmounted?: boolean` — whether to clear data after component unmount.
+- `skeleton?: () => Return` — function returning placeholder data during loading.
+
+### `ApiManagementSearch<T, K>`
+- `columns: K` — list of columns for searching.
+- `value?: Ref<string>` — reactive search string.
+- `options?: SearchOptions` — additional search settings.
+
+### `ApiManagementRequest<T, Return>`
+- `path?: string | Ref<string>` — path for the mutation request.
+- `action?: (data: Return | undefined) => Promise<void> | void` — callback after request execution.
+- `transformation?: (data: T) => Return` — data transformation before sending.
+- `toData?: boolean` — whether to send data in the request body (under `data`).
+- `options?: ApiOptions` — additional request options.
+
+## Usage Example
+
+```typescript
+import { ref } from 'vue'
+import { useApiManagementRef } from '@dxtmisha/functional'
+import { FormattersType } from '@dxtmisha/functional-basic'
+
+const searchVal = ref('')
+
+const { 
+  list, 
+  loading, 
+  sendPost, 
+  sendDelete 
+} = useApiManagementRef(
+  // 1. GET Request
+  { path: 'api/users', skeleton: () => [{ id: 0, name: 'Loading...' }] },
+  // 2. Formatters
+  {  price: { type: FormattersType.currency } },
+  // 3. Search
+  { columns: ['name'], value: searchVal },
+  // 4. POST
+  { path: 'api/users/create' },
+  // 5. PUT (not used)
+  undefined,
+  // 6. DELETE
+  { path: 'api/users/delete' }
+)
+
+// To create a user:
+// await sendPost({ data: { name: 'New User' } })
+// This will automatically run request.reset() and fetch latest users!
+```

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

@@ -0,0 +1,124 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Composables/useApiManagementRef - Управление API'/>
+
+# `useApiManagementRef`
+
+Мощный композабл для комплексной оркестрации API-запросов. Он централизованно управляет загрузкой данных (GET), форматированием списков, клиентским поиском и мутациями (POST, PUT, DELETE) через единый реактивный интерфейс.
+
+## Параметры
+- `propsGet: ApiManagementGet<Return, Type>` — настройки главного GET-запроса (path, reactivity, skeleton и т.д.).
+- `formattersOptions?: FormattersOptions` — опциональные правила для реактивного форматирования данных (`useFormattersRef`).
+- `searchOptions?: ApiManagementSearch<Item, Columns>` — опциональные настройки для клиентского поиска по списку (`useSearchRef`).
+- `postRequest?: ApiManagementRequest<Post>` — опциональные настройки для POST-запроса создания.
+- `putRequest?: ApiManagementRequest<Put>` — опциональные настройки для PUT-запроса обновления.
+- `deleteRequest?: ApiManagementRequest<Delete>` — опциональные настройки для DELETE-запроса удаления.
+- `action?: function` — общий коллбэк для выполнения после любой успешной мутации.
+- `apiInstance?: ApiInstance` — Экземпляр API, используемый для выполнения запроса. По умолчанию `Api.getItem()`.
+
+## Возвращает
+- `isValid: ComputedRef<boolean>` — `true`, если данные прошли проверку `typeData`.
+- `list: ComputedRef` — обработанный массив данных. **Поддерживает Skeleton**: если данные ещё не загружены и передан `skeleton()`, вернет заглушки. Учитывает фильтры поиска и форматтеры.
+- `data: ComputedRef<ApiData<Return> | undefined>` — «сырые» реактивные данные из `useApiRef`.
+- `length: ComputedRef<number>` — текущее количество элементов в `list` (динамически меняется при поиске).
+- `lengthData: ComputedRef<number>` — общее количество элементов в исходном `data`.
+- `starting: ComputedRef<boolean>` — флаг первичной загрузки (когда данных еще нет).
+- `reading: Ref<boolean>` — флаг активного процесса чтения данных.
+- `loading: Ref<boolean>` — общее состояние загрузки главного GET-запроса.
+- `loadingSearch: Ref<boolean>` — состояние загрузки в процессе поиска.
+- `loadingPost / loadingPut / loadingDelete` — состояния загрузки для каждой мутации.
+- `isSearch: ComputedRef<boolean>` — активен ли поиск (есть ли поисковый запрос).
+- `search: Ref<string>` — реактивная строка поиска (Proxy к переданному `searchOptions.value`).
+- `sendPost / sendPut / sendDelete: (request?: ApiFetch['request']) => Promise<any>` — методы для вызова мутаций.
+- `reset: () => Promise<void>` — принудительный перезапуск GET-запроса и очистка текущего состояния.
+- `abort: () => void` — прерывание текущего сетевого запроса.
+
+## Ограничения дженериков (Generic Constraints)
+
+- `Return extends ApiManagementValue` — тип данных, возвращаемых API.
+- `FormattersOptions extends FormattersOptionsList` — опциональные правила форматирования.
+- `Post / Put / Delete extends Record<string, any>` — типы данных для соответствующих запросов мутации.
+- `Type extends ApiManagementValue = Return` — тип исходных данных (до трансформации).
+- `Item extends ArrayToItem<Return>` — тип одного элемента из списка данных.
+- `ItemFormatters extends FormattersListColumns<Item, FormattersOptions>[number]` — тип элемента после применения форматировщиков.
+- `Columns extends SearchColumns<ItemFormatters>` — колонки, по которым производится поиск.
+
+## Как с ним работать
+
+`useApiManagementRef` — это центральный хаб для управления данными в CRUD-интерфейсах. Он объединяет сетевые запросы, локальный поиск и форматирование в единый автоматизированный цикл:
+
+1.  **Инициализация и Ленивость (Lazy Loading)**: Хук не отправляет сетевой запрос немедленно. GET-запрос ставится в очередь только тогда, когда ваш компонент впервые обращается к свойству `list` или `data`. Это экономит ресурсы, если данные не всегда нужны на экране.
+2.  **Мгновенный отклик (Skeleton)**: Если вы передали функцию `skeleton`, то в момент начала загрузки `list` сразу вернет массив "заглушек". Это позволяет отрисовать структуру таблицы или списка до того, как придет первый байт данных, исключая "прыжки" интерфейса.
+3.  **Умный список (`list`)**: Это основная точка взаимодействия. Свойство `list` автоматически переключается между:
+    - Данными-скелетонами (при загрузке).
+    - Результатами поиска (если введен поисковый запрос).
+    - Отформатированными данными (если настроены `formattersOptions`).
+    - Исходными данными (если ничего из вышеперечисленного не применимо).
+4.  **Синхронизация Поиска и Форматов**: Поиск выполняется по уже загруженным и, если необходимо, отформатированным данным. Это гарантирует, что пользователь найдет "Иванов Иван", даже если в исходном JSON эти данные пришли в разных полях. Поиск происходит на стороне клиента (Client-side), что дает мгновенный результат.
+5.  **Цикл Мутаций и Авто-обновление**: 
+    - При вызове методов `sendPost`, `sendPut` или `sendDelete` хук отслеживает статус ответа. 
+    - Если сервер вернул успех (проверка через `isApiSuccess`), хук **автоматически** вызывает `reset()` для основного GET-запроса. 
+    - Это приводит к повторной загрузке данных и обновлению всего списка. Таким образом, после удаления строки или добавления новой, ваш список всегда остается актуальным без написания лишнего кода.
+6.  **Реактивность параметров**: Если `path` или `options` (в `propsGet`) являются реактивными (Vue Ref), и вы установили `reactivity: true`, хук будет следить за их изменением и автоматически перезагружать данные при смене URL или параметров фильтрации.
+
+## Архитектура
+
+`useApiManagementRef` — это центральный оркестратор для CRUD-задач. Он объединяет четыре независимых хука (`useApiRef`, `useFormattersRef`, `useSearchRef` и мутации) в единую реактивную систему. Вместо управления десятками разрозненных состояний (загрузка, ошибки, данные, фильтры), разработчик описывает конфигурацию, а хук берет на себя синхронизацию их жизненных циклов.
+
+## Типы (Types)
+
+### `ApiManagementGet<Return, Type>`
+- `path?: string | Ref<string>` — путь к API.
+- `options?: ApiOptions` — параметры запроса (метод, заголовки и т.д.).
+- `reactivity?: boolean` — включить ли автоматическое обновление при изменении `path` или `options`.
+- `conditions?: Ref<boolean>` — условие, при котором выполняется запрос.
+- `transformation?: (data: Type) => ApiData<Return>` — функция для трансформации данных после получения.
+- `typeData?: ((data: Return) => boolean) | any` — функция проверки данных или конструктор (например, `Array`).
+- `unmounted?: boolean` — удалять ли данные после размонтирования компонента.
+- `skeleton?: () => Return` — функция, возвращающая данные-заглушки во время загрузки.
+
+### `ApiManagementSearch<T, K>`
+- `columns: K` — список колонок для поиска.
+- `value?: Ref<string>` — реактивная строка поиска.
+- `options?: SearchOptions` — дополнительные настройки поиска.
+
+### `ApiManagementRequest<T, Return>`
+- `path?: string | Ref<string>` — путь для запроса мутации.
+- `action?: (data: Return | undefined) => Promise<void> | void` — коллбэк, вызываемый после выполнения запроса.
+- `transformation?: (data: T) => Return` — трансформация данных перед отправкой.
+- `toData?: boolean` — отправлять ли данные в теле запроса (в свойстве `data`).
+- `options?: ApiOptions` — дополнительные параметры запроса.
+
+## Пример использования
+
+```typescript
+import { ref } from 'vue'
+import { useApiManagementRef } from '@dxtmisha/functional'
+import { FormattersType } from '@dxtmisha/functional-basic'
+
+const searchVal = ref('')
+
+const { 
+  list, 
+  loading, 
+  sendPost, 
+  sendDelete 
+} = useApiManagementRef(
+  // 1. GET Запрос
+  { path: 'api/users', skeleton: () => [{ id: 0, name: 'Загрузка...' }] },
+  // 2. Форматтеры
+  {  price: { type: FormattersType.currency } },
+  // 3. Поиск
+  { columns: ['name'], value: searchVal },
+  // 4. POST
+  { path: 'api/users/create' },
+  // 5. PUT (не используется)
+  undefined,
+  // 6. DELETE
+  { path: 'api/users/delete' }
+)
+
+// Для создания пользователя:
+// await sendPost({ data: { name: 'Новый' } })
+// Будет вызван POST запрос, а затем таблица пользователей обновится автоматически!
+```

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

@@ -0,0 +1,124 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Composables/useApiManagementRef - Quản lý API'/>
+
+# `useApiManagementRef`
+
+Một composable mạnh mẽ để điều phối toàn diện các request API. Nó quản lý việc fetching dữ liệu (GET), format danh sách, tìm kiếm trên client và các đột biến (POST, PUT, DELETE) đều được tích hợp trong một giao diện phản ứng (reactive interface) duy nhất.
+
+## Tham số
+- `propsGet: ApiManagementGet<Return, Type>` — cấu hình cho GET request chính (path, reactivity, skeleton, v.v.).
+- `formattersOptions?: FormattersOptions` — các quy tắc định dạng reactive tùy chọn (`useFormattersRef`).
+- `searchOptions?: ApiManagementSearch<Item, Columns>` — cấu hình tìm kiếm phía client tùy chọn (`useSearchRef`).
+- `postRequest?: ApiManagementRequest<Post>` — cấu hình tùy chọn cho yêu cầu tạo (POST).
+- `putRequest?: ApiManagementRequest<Put>` — cấu hình tùy chọn cho yêu cầu cập nhật (PUT).
+- `deleteRequest?: ApiManagementRequest<Delete>` — cấu hình tùy chọn cho yêu cầu xóa (DELETE).
+- `action?: function` — callback chung để thực thi sau bất kỳ mutation nào thành công.
+- `apiInstance?: ApiInstance` — Phiên bản API sử dụng cho yêu cầu. Mặc định là `Api.getItem()`.
+
+## Giá trị trả về
+- `isValid: ComputedRef<boolean>` — `true` nếu dữ liệu khớp với kiểm tra `typeData`.
+- `list: ComputedRef` — mảng dữ liệu đã qua xử lý. **Hỗ trợ Skeleton**: nếu dữ liệu chưa được tải và `skeleton()` được cung cấp, nó sẽ trả về các giá trị giả. Tính toán dựa trên bộ lọc tìm kiếm và formatter.
+- `data: ComputedRef<ApiData<Return> | undefined>` — dữ liệu reactive thô từ `useApiRef`.
+- `length: ComputedRef<number>` — độ dài hiện tại của `list` (cập nhật động khi tìm kiếm).
+- `lengthData: ComputedRef<number>` — độ dài gốc của dữ liệu trong `data.value`.
+- `starting: ComputedRef<boolean>` — `true` nếu yêu cầu vẫn đang trong giai đoạn tải ban đầu.
+- `reading: Ref<boolean>` — cờ chỉ định rằng dữ liệu hiện đang được tải/đọc từ server.
+- `loading: Ref<boolean>` — trạng thái loading của GET request chính.
+- `loadingSearch: Ref<boolean>` — trạng thái loading của thao tác tìm kiếm.
+- `loadingPost / loadingPut / loadingDelete` — trạng thái loading độc lập cho từng thao tác đột biến.
+- `isSearch: ComputedRef<boolean>` — cho biết truy vấn tìm kiếm hiện có đang hoạt động hay không.
+- `search: Ref<string>` — chuỗi tìm kiếm reactive (Proxy đến `searchOptions.value` đã cung cấp).
+- `sendPost / sendPut / sendDelete: (request?: ApiFetch['request']) => Promise<any>` — các phương thức để thực thi mutation.
+- `reset: () => Promise<void>` — buộc khởi động lại/làm mới GET request chính thủ công.
+- `abort: () => void` — hủy bỏ yêu cầu mạng đang diễn ra.
+
+## Ràng buộc Generic (Generic Constraints)
+
+- `Return extends ApiManagementValue` — kiểu dữ liệu trả về từ API.
+- `FormattersOptions extends FormattersOptionsList` — kiểu cho các tùy chọn format.
+- `Post / Put / Delete extends Record<string, any>` — kiểu dữ liệu cho các mutation request tương ứng.
+- `Type extends ApiManagementValue = Return` — kiểu dữ liệu thô ban đầu (trước khi transform).
+- `Item extends ArrayToItem<Return>` — kiểu cho một phần tử trong danh sách dữ liệu.
+- `ItemFormatters extends FormattersListColumns<Item, FormattersOptions>[number]` — kiểu phần tử sau khi áp dụng formatter.
+- `Columns extends SearchColumns<ItemFormatters>` — các cột được sử dụng để tìm kiếm.
+
+## Cách làm việc
+
+`useApiManagementRef` là trung tâm điều phối quản lý dữ liệu cho các giao diện CRUD. Nó kết hợp các yêu cầu mạng, tìm kiếm cục bộ và định dạng dữ liệu vào một chu kỳ tự động duy nhất:
+
+1.  **Khởi tạo và Cơ chế Lazy Loading**: Hook không gửi yêu cầu mạng ngay lập tức. GET request chỉ được đưa vào hàng đợi khi component của bạn truy cập lần đầu vào thuộc tính `list` hoặc `data`. Điều này giúp tiết kiệm tài nguyên nếu dữ liệu không phải lúc nào cũng cần hiển thị.
+2.  **Phản hồi tức thì (Skeleton)**: Nếu bạn cung cấp hàm `skeleton`, thuộc tính `list` sẽ trả về ngay một mảng các "dữ liệu giả" khi bắt đầu tải. Điều này cho phép bạn dựng cấu trúc bảng hoặc danh sách trước khi byte dữ liệu đầu tiên được tải về, loại bỏ tình trạng giao diện bị "nhảy".
+3.  **Danh sách thông minh (`list`)**: Đây là điểm tương tác chính. Thuộc tính `list` tự động chuyển đổi giữa:
+    - Dữ liệu Skeleton (trong khi đang tải).
+    - Kết quả tìm kiếm (nếu có chuỗi tìm kiếm được nhập).
+    - Dữ liệu đã định dạng (nếu `formattersOptions` được cấu hình).
+    - Dữ liệu thô (nếu không có trường hợp nào ở trên áp dụng).
+4.  **Đồng bộ hóa Tìm kiếm và Định dạng**: Việc tìm kiếm được thực hiện trên dữ liệu đã tải và đã được định dạng (nếu cần). Điều này đảm bảo người dùng có thể tìm thấy "Nguyễn Văn A" ngay cả khi dữ liệu JSON gốc lưu họ và tên ở các trường riêng biệt. Tìm kiếm diễn ra ở phía client (Client-side), mang lại kết quả tức thì.
+5.  **Chu kỳ Mutation và Tự động làm mới**: 
+    - Khi gọi các phương thức `sendPost`, `sendPut` hoặc `sendDelete`, hook sẽ theo dõi trạng thái phản hồi. 
+    - Nếu server trả về thành công (được xác nhận qua `isApiSuccess`), hook sẽ **tự động** gọi `reset()` cho GET request chính. 
+    - Việc này kích hoạt tải lại dữ liệu và cập nhật toàn bộ danh sách. Do đó, sau khi xóa một dòng hoặc thêm mới, danh sách của bạn luôn được cập nhật mà không cần viết thêm mã xử lý thủ công.
+6.  **Tính phản xạ của tham số**: Nếu `path` hoặc `options` (trong `propsGet`) là các biến reactive (Vue Ref) và bạn thiết lập `reactivity: true`, hook sẽ theo dõi sự thay đổi của chúng và tự động tải lại dữ liệu khi URL hoặc tham số lọc thay đổi.
+
+## Kiến trúc phần lõi
+
+`useApiManagementRef` là một hook điều hướng được thiết kế chuyên biệt để quản lý các mẫu màn hình CRUD tiêu chuẩn (ví dụ như data tables). Thông qua cấu hình tham số, bạn sẽ nhận được một đối tượng "tất cả trong một" để quản lý loading spinners, bộ tìm kiếm, chuẩn hóa dữ liệu cho UI, điều khiển thao tác CRUD và tự động tải lại danh sách.
+
+## Các kiểu dữ liệu (Types)
+
+### `ApiManagementGet<Return, Type>`
+- `path?: string | Ref<string>` — đường dẫn API.
+- `options?: ApiOptions` — các tùy chọn request (method, headers, v.v.).
+- `reactivity?: boolean` — có tự động refetch khi `path` hoặc `options` thay đổi hay không.
+- `conditions?: Ref<boolean>` — điều kiện để thực thi request.
+- `transformation?: (data: Type) => ApiData<Return>` — hàm transform dữ liệu sau khi fetch.
+- `typeData?: ((data: Return) => boolean) | any` — hàm kiểm tra dữ liệu hoặc constructor (ví dụ: `Array`).
+- `unmounted?: boolean` — có xóa dữ liệu khi component bị unmount hay không.
+- `skeleton?: () => Return` — hàm trả về dữ liệu giả (placeholder) trong khi loading.
+
+### `ApiManagementSearch<T, K>`
+- `columns: K` — danh sách các cột để tìm kiếm.
+- `value?: Ref<string>` — chuỗi tìm kiếm reactive.
+- `options?: SearchOptions` — các tùy chọn tìm kiếm bổ sung.
+
+### `ApiManagementRequest<T, Return>`
+- `path?: string | Ref<string>` — đường dẫn cho mutation request.
+- `action?: (data: Return | undefined) => Promise<void> | void` — callback sau khi thực thi request.
+- `transformation?: (data: T) => Return` — hàm transform dữ liệu trước khi gửi.
+- `toData?: boolean` — có gửi dữ liệu trong body của request (dưới thuộc tính `data`) hay không.
+- `options?: ApiOptions` — các tùy chọn request bổ sung.
+
+## Ví dụ sử dụng
+
+```typescript
+import { ref } from 'vue'
+import { useApiManagementRef } from '@dxtmisha/functional'
+import { FormattersType } from '@dxtmisha/functional-basic'
+
+const searchVal = ref('')
+
+const { 
+  list, 
+  loading, 
+  sendPost, 
+  sendDelete 
+} = useApiManagementRef(
+  // 1. GET Request
+  { path: 'api/users', skeleton: () => [{ id: 0, name: 'Đang tải...' }] },
+  // 2. Formatters
+  {  price: { type: FormattersType.currency } },
+  // 3. Tiềm kiếm
+  { columns: ['name'], value: searchVal },
+  // 4. POST
+  { path: 'api/users/create' },
+  // 5. PUT (không dùng)
+  undefined,
+  // 6. DELETE
+  { path: 'api/users/delete' }
+)
+
+// Tạo một người dùng mới:
+// await sendPost({ data: { name: 'Người Dùng Mới' } })
+// Thao tác này sẽ tự gọi request.reset() để làm mới bảng dữ liệu!
+```

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

@@ -0,0 +1,37 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Composables/useApiPost - POST Request Execution'/>
+
+# `useApiPost`
+
+Returns an object with a loading state and a `send` method for executing API `POST` requests.
+
+**Parameters:**
+- `path?: RefOrNormal<string | undefined>` — Path to the API endpoint (can be reactive).
+- `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 `POST` request. It automatically manages the `loading` state, applies the transformation function to the response, executes the `action` callback on success, and safely handles errors by logging them to the console.
+
+```typescript
+import { useApiPost } from '@dxtmisha/functional'
+
+const { loading, send } = useApiPost(
+  '/api/submit',
+  (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/useApiPost/useApiPost.ru.mdx

@@ -0,0 +1,37 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Composables/useApiPost - Выполнение POST-запросов'/>
+
+# `useApiPost`
+
+Возвращает объект с состоянием загрузки и методом `send` для выполнения `POST`-запросов к API.
+
+**Параметры:**
+- `path?: RefOrNormal<string | undefined>` — Путь к endpoint API (может быть реактивным).
+- `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>` — Асинхронный метод для отправки `POST`-запроса. Он автоматически управляет состоянием `loading`, применяет функцию трансформации к ответу, вызывает коллбэк `action` при успехе и безопасно обрабатывает ошибки.
+
+```typescript
+import { useApiPost } from '@dxtmisha/functional'
+
+const { loading, send } = useApiPost(
+  '/api/submit',
+  (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/useApiPost/useApiPost.vi.mdx

@@ -0,0 +1,37 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Composables/useApiPost - Thực hiện yêu cầu POST'/>
+
+# `useApiPost`
+
+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 `POST`.
+
+**Tham số:**
+- `path?: RefOrNormal<string | undefined>` — Đường dẫn đến endpoint API (có thể phản ứng).
+- `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ị 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 `POST`. 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.
+
+```typescript
+import { useApiPost } from '@dxtmisha/functional'
+
+const { loading, send } = useApiPost(
+  '/api/submit',
+  (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/useApiPut/useApiPut.en.mdx

@@ -0,0 +1,37 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Composables/useApiPut - PUT Request Execution'/>
+
+# `useApiPut`
+
+Returns an object with a loading state and a `send` method for executing API `PUT` requests.
+
+**Parameters:**
+- `path?: RefOrNormal<string | undefined>` — Path to the API endpoint (can be reactive).
+- `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 `PUT` request. It automatically manages the `loading` state, applies the transformation function to the response, executes the `action` callback on success, and safely handles errors by logging them to the console.
+
+```typescript
+import { useApiPut } from '@dxtmisha/functional'
+
+const { loading, send } = useApiPut(
+  '/api/update',
+  (data) => console.log('Action complete:', data),
+  (raw) => ({ ...raw, processed: true }),
+  true,
+  { cache: false }
+)
+
+const handleUpdate = async () => {
+  const result = await send({ id: 1, name: 'New Name' })
+  console.log('Final Result:', result)
+}
+```

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

@@ -0,0 +1,37 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Composables/useApiPut - Выполнение PUT-запросов'/>
+
+# `useApiPut`
+
+Возвращает объект с состоянием загрузки и методом `send` для выполнения `PUT`-запросов к API.
+
+**Параметры:**
+- `path?: RefOrNormal<string | undefined>` — Путь к endpoint API (может быть реактивным).
+- `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>` — Асинхронный метод для отправки `PUT`-запроса. Он автоматически управляет состоянием `loading`, применяет функцию трансформации к ответу, вызывает коллбэк `action` при успехе и безопасно обрабатывает ошибки.
+
+```typescript
+import { useApiPut } from '@dxtmisha/functional'
+
+const { loading, send } = useApiPut(
+  '/api/update',
+  (data) => console.log('Действие завершено:', data),
+  (raw) => ({ ...raw, processed: true }),
+  true,
+  { cache: false }
+)
+
+const handleUpdate = async () => {
+  const result = await send({ id: 1, name: 'New Name' })
+  console.log('Итоговый результат:', result)
+}
+```

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

@@ -0,0 +1,37 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Composables/useApiPut - Thực hiện yêu cầu PUT'/>
+
+# `useApiPut`
+
+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 `PUT`.
+
+**Tham số:**
+- `path?: RefOrNormal<string | undefined>` — Đường dẫn đến endpoint API (có thể phản ứng).
+- `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ị 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 `PUT`. 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.
+
+```typescript
+import { useApiPut } from '@dxtmisha/functional'
+
+const { loading, send } = useApiPut(
+  '/api/update',
+  (data) => console.log('Hành động hoàn tất:', data),
+  (raw) => ({ ...raw, processed: true }),
+  true,
+  { cache: false }
+)
+
+const handleUpdate = async () => {
+  const result = await send({ id: 1, name: 'New Name' })
+  console.log('Kết quả cuối cùng:', result)
+}
+```