@dxtmisha/wiki 0.57.3 → 0.57.6

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

@@ -0,0 +1,41 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Composables/useApiManagementAsyncRef - Khởi tạo quản lý API bất đồng bộ'/>
+
+# `useApiManagementAsyncRef`
+
+`useApiManagementAsyncRef` là một wrapper bất đồng bộ cho [`useApiManagementRef`](./useApiManagementRef.vi.mdx), thực hiện khởi tạo yêu cầu ngay lập tức.
+
+Khác với `useApiManagementRef` tiêu chuẩn, vốn khởi tạo "lười" (khi truy cập danh sách hoặc dữ liệu lần đầu), phương thức này gọi `initSsr()` ngay lập tức khi được tạo. Điều này làm cho nó trở thành lựa chọn lý tưởng để sử dụng trong môi trường SSR.
+
+## Các tính năng chính
+- **Khởi tạo ngay lập tức** — bắt đầu quá trình khởi tạo GET request ngay khi hook được gọi.
+- **Hỗ trợ SSR** — đảm bảo dữ liệu được tải trên máy chủ trước khi trang được gửi đến máy khách.
+- **Đầy đủ chức năng quản lý** — giữ lại tất cả các tính năng của `useApiManagementRef`, bao gồm formatter, tìm kiếm và mutation.
+
+## Tham số
+Các tham số giống hệt với [`useApiManagementRef`](./useApiManagementRef.vi.mdx):
+
+- `propsGet: ApiManagementGet<Return, Type>` — cài đặt GET request chính.
+- `formattersOptions?: FormattersOptions` — quy tắc định dạng.
+- `searchOptions?: ApiManagementSearch<Item, Columns>` — cài đặt tìm kiếm.
+- `postRequest / putRequest / deleteRequest` — cài đặt mutation.
+- `action?: function` — callback sau mutation.
+- `apiInstance?: ApiInstance` — instance của API.
+
+## Giá trị trả về
+Trả về một đối tượng quản lý API. Cấu trúc đối tượng trả về giống hệt với [`useApiManagementRef`](./useApiManagementRef.vi.mdx).
+
+## Ví dụ
+
+```typescript
+import { useApiManagementAsyncRef } from '@dxtmisha/functional'
+
+// Khởi tạo (và chuẩn bị dữ liệu SSR) bắt đầu ngay lập tức
+const { list, loading } = useApiManagementAsyncRef(
+  { 
+    path: 'api/products',
+    skeleton: () => Array(3).fill({ id: 0, title: 'Đang tải...' })
+  }
+)
+```

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

@@ -30,9 +30,15 @@ A powerful composable for comprehensive API request orchestration. It manages da
 - `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.
+- `init: () => void` — method for explicit manual initialization of request and observation.
+- `initSsr: () => void` — method for server-side initialization (SSR).
 - `reset: () => Promise<void>` — forces a manual restart/refresh of the main GET request.
 - `abort: () => void` — aborts the ongoing network request.
 
+## Async Version
+
+For cases where immediate (non-lazy) initialization is required (e.g., for SSR), use [**`useApiManagementAsyncRef`**](./useApiManagementAsyncRef.en.mdx). It automatically calls `initSsr()` upon creation.
+
 ## Generic Constraints
 
 - `Return extends ApiManagementValue` — logic model for data returned by the API.
@@ -61,6 +67,12 @@ A powerful composable for comprehensive API request orchestration. It manages da
     - 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.
 
+## SSR and Initialization
+
+To ensure correct operation of **Server Side Rendering (SSR)**, it is recommended to use the asynchronous version [**`useApiManagementAsyncRef`**](./useApiManagementAsyncRef.en.mdx). It automatically initializes the GET request for pre-fetching on the server.
+
+If you are using the standard `useApiManagementRef`, you can manually include it in the SSR cycle by calling `initSsr()` in the component's `setup()`. This ensures that the data will be loaded on the server side.
+
 ## 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.

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

@@ -30,9 +30,15 @@ import {Meta} from '@storybook/addon-docs/blocks'
 - `isSearch: ComputedRef<boolean>` — активен ли поиск (есть ли поисковый запрос).
 - `search: Ref<string>` — реактивная строка поиска (Proxy к переданному `searchOptions.value`).
 - `sendPost / sendPut / sendDelete: (request?: ApiFetch['request']) => Promise<any>` — методы для вызова мутаций.
+- `init: () => void` — метод для явной ручной инициализации запроса и наблюдения.
+- `initSsr: () => void` — метод для инициализации на стороне сервера (SSR).
 - `reset: () => Promise<void>` — принудительный перезапуск GET-запроса и очистка текущего состояния.
 - `abort: () => void` — прерывание текущего сетевого запроса.
 
+## Асинхронная версия
+
+Для случаев, когда требуется немедленная (не ленивая) инициализация запроса (например, для SSR), используйте [**`useApiManagementAsyncRef`**](./useApiManagementAsyncRef.ru.mdx). Он автоматически вызывает `initSsr()` при создании.
+
 ## Ограничения дженериков (Generic Constraints)
 
 - `Return extends ApiManagementValue` — тип данных, возвращаемых API.
@@ -61,6 +67,12 @@ import {Meta} from '@storybook/addon-docs/blocks'
     - Это приводит к повторной загрузке данных и обновлению всего списка. Таким образом, после удаления строки или добавления новой, ваш список всегда остается актуальным без написания лишнего кода.
 6.  **Реактивность параметров**: Если `path` или `options` (в `propsGet`) являются реактивными (Vue Ref), и вы установили `reactivity: true`, хук будет следить за их изменением и автоматически перезагружать данные при смене URL или параметров фильтрации.
 
+## SSR и инициализация
+
+Для обеспечения корректной работы **Server Side Rendering (SSR)** рекомендуется использовать асинхронную версию [**`useApiManagementAsyncRef`**](./useApiManagementAsyncRef.ru.mdx). Она автоматически инициализирует запрос для предзагрузки на сервере.
+
+Если вы используете стандартный `useApiManagementRef`, вы можете вручную включить его в цикл SSR, вызвав `initSsr()` в `setup()` компонента. Это гарантирует, что данные будут загружены на стороне сервера.
+
 ## Архитектура
 
 `useApiManagementRef` — это центральный оркестратор для CRUD-задач. Он объединяет четыре независимых хука (`useApiRef`, `useFormattersRef`, `useSearchRef` и мутации) в единую реактивную систему. Вместо управления десятками разрозненных состояний (загрузка, ошибки, данные, фильтры), разработчик описывает конфигурацию, а хук берет на себя синхронизацию их жизненных циклов.

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

@@ -61,6 +61,12 @@ Một composable mạnh mẽ để điều phối toàn diện các request API.
     - 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.
 
+## SSR và Khởi tạo
+
+Để đảm bảo hoạt động chính xác của **Server Side Rendering (SSR)**, bạn nên sử dụng phiên bản bất đồng bộ [**`useApiManagementAsyncRef`**](./useApiManagementAsyncRef.vi.mdx). Nó tự động khởi tạo GET request để tải trước trên máy chủ.
+
+Nếu bạn đang sử dụng `useApiManagementRef` tiêu chuẩn, bạn có thể đưa nó vào chu trình SSR một cách thủ công bằng cách gọi `initSsr()` trong `setup()` của component. Điều này đảm bảo rằng dữ liệu sẽ được tải ở phía máy chủ.
+
 ## 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.

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

@@ -35,6 +35,7 @@ Methods:
 - `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(awaitFetch?: boolean): Promise<void>` — Method for explicit request and watcher initialization. Triggered automatically on first access to `data`. If `awaitFetch` is `true`, it waits for the first request to complete.
+- `initSsr(): void` — Method for server-side initialization. Uses `onServerPrefetch` to fetch data during SSR.
 - `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`.
@@ -47,20 +48,22 @@ Requests and watching mechanisms **are not started** immediately when `useApiRef
 
 `setApiRefGlobalConditions(conditions)` — sets a global condition for all `useApiRef` instances. Only works on the first call.
 
-## SSR and Initialization
+## SSR (Server-Side Rendering)
 
-The `init` method is designed to manage the primary data loading process, which is critical for the correct operation of **Server Side Rendering (SSR)** and ensuring fast interface rendering on the client.
+To ensure correct operation on the server side (SSR), the **`initSsr()`** method must be used.
 
-### Mechanism of Operation (Hydration)
+### The `initSsr()` Method
+When called in a component's `setup()`, it ensures that data is loaded on the server before page rendering and applied instantly on the client.
 
-1.  **Server Side (SSR):**
-    When the page is first opened, `await init()` should be called in `async setup()`. This forces the server to wait for the API response and render the component with ready-made data. The received data is automatically placed in the state cache, which is then passed to the client.
+```typescript
+const { data, initSsr } = useApiRef('path/to/api')
 
-2.  **Client Side (Hydration):**
-    When the browser "hydrates" the page, `useApiRef` first checks for data in the cache. If data is there (received from the server), it is immediately applied to `data`, avoiding a duplicate API request.
+// Call this for SSR support
+initSsr()
+```
 
-3.  **Dynamic Navigation (Client-side Nav):**
-    If the user navigates to the page dynamically (without a page reload), the component renders immediately without waiting for `init()` to complete. This allows for instantly showing a **skeleton** or loading indicator (`loading`) while data is being fetched in the background.
+### Automation via `AsyncRef`
+To avoid calling `initSsr()` manually, you can use the asynchronous version — [**`useApiAsyncRef`**](./useApiAsyncRef.en.mdx). It automatically calls `initSsr()` upon creation.
 ## 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:

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

@@ -37,6 +37,7 @@ Composable для удобной работы с API-запросами во Vue
 - `isReading(): boolean` — Синхронный метод, возвращающий текущее значение флага `reading`.
 - `getItem(): ApiData<R> | undefined` — Метод для получения текущего значения `data` без создания реактивной зависимости.
 - `init(awaitFetch?: boolean): Promise<void>` — Метод для явной инициализации запроса и watchers. Вызывается автоматически при первом обращении к `data`. Если `awaitFetch` передано как `true`, дожидается выполнения первого запроса.
+- `initSsr(): void` — Метод для инициализации на стороне сервера. Использует `onServerPrefetch` для выполнения запроса во время SSR.
 - `reset(): Promise<void>` — Асинхронный метод для принудительного перезапуска запроса. Отменяет текущий активный запрос (если есть) и инициирует новый.
 - `stop(): void` — Останавливает наблюдение за реактивными зависимостями и сбрасывает `data` в `undefined`.
 - `abort(): void` — Вызывает отмену текущего HTTP-запроса через внутренний `AbortController`, сохраняя при этом уже загруженные данные в `data`.
@@ -49,20 +50,22 @@ Composable для удобной работы с API-запросами во Vue
 
 `setApiRefGlobalConditions(conditions)` — устанавливает глобальное условие для всех экземпляров `useApiRef`. Работает только один раз.
 
-## SSR и инициализация
+## SSR (Server-Side Rendering)
 
-Метод `init` предназначен для управления процессом первичной загрузки данных, что критически важно для корректной работы **Server Side Rendering (SSR)** и обеспечения быстрой отрисовки интерфейса на клиенте.
+Для корректной работы на стороне сервера (SSR) необходимо использовать метод **`initSsr()`**.
 
-### Механика работы (Hydration)
+### Метод `initSsr()`
+При вызове в `setup()` компонента гарантирует, что данные будут загружены на сервере перед рендерингом страницы, а на клиенте подставятся мгновенно.
 
-1.  **На стороне сервера (SSR):**
-    При первом открытии страницы необходимо вызвать `await init()` в `async setup()`. Это заставит сервер дождаться ответа от API и отрендерить компонент уже с готовыми данными. Полученные данные автоматически попадают в кэш состояния, который передается клиенту.
+```typescript
+const { data, initSsr } = useApiRef('path/to/api')
 
-2.  **На стороне клиента (Hydration):**
-    Когда браузер "оживляет" (гидрирует) страницу, `useApiRef` первым делом проверяет наличие данных в кэше. Если данные там есть (пришли с сервера), они мгновенно подставляются в `data`, исключая повторный запрос к API.
+// Вызываем для поддержки SSR
+initSsr()
+```
 
-3.  **Динамическая навигация (Client-side Nav):**
-    Если пользователь переходит на страницу динамически (без перезагрузки), компонент рендерится сразу, не дожидаясь завершения `init()`. Это позволяет мгновенно показать **скелетон (skeleton)** или индикатор загрузки (`loading`), пока данные подгружаются в фоновом режиме.
+### Автоматизация через `AsyncRef`
+Чтобы не вызывать `initSsr()` вручную, можно использовать асинхронную версию композабла — [**`useApiAsyncRef`**](./useApiAsyncRef.ru.mdx). Он автоматически вызывает `initSsr()` при создании.
 ## Объект ApiOptions
 
 `ApiOptions` — может принимать строку с названием `method` (например, `'GET'`) или объект типа `ApiFetch`. Поля объекта `ApiFetch`:

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

@@ -49,20 +49,22 @@ Yêu cầu và cơ chế theo dõi thay đổi **không được bắt đầu**
 
 `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.
 
-## SSR và Khởi tạo
+## SSR (Server-Side Rendering)
 
-Phương thức `init` được thiết kế để quản lý quá trình tải dữ liệu ban đầu, điều này cực kỳ quan trọng đối với hoạt động chính xác của **Server Side Rendering (SSR)** và đảm bảo giao diện được hiển thị nhanh chóng trên client.
+Để đảm bảo hoạt động chính xác ở phía máy chủ (SSR), phương thức **`initSsr()`** phải được sử dụng.
 
-### Cơ chế hoạt động (Hydration)
+### Phương thức `initSsr()`
+Khi được gọi trong `setup()` của một component, nó đảm bảo dữ liệu được tải trên máy chủ trước khi render trang và được áp dụng ngay lập tức ở phía máy khách.
 
-1.  **Phía Máy chủ (SSR):**
-    Khi trang được mở lần đầu tiên, hãy gọi `await init()` trong `async setup()`. Điều này buộc máy chủ phải đợi phản hồi từ API và render component với dữ liệu đã sẵn sàng. Dữ liệu nhận được sẽ tự động được đưa vào bộ nhớ đệm trạng thái (cache), sau đó được chuyển đến client.
+```typescript
+const { data, initSsr } = useApiRef('path/to/api')
 
-2.  **Phía Máy khách (Hydration):**
-    Khi trình duyệt "kích hoạt" (hydrate) trang, `useApiRef` trước tiên sẽ kiểm tra dữ liệu trong bộ nhớ đệm. Nếu dữ liệu có ở đó (được nhận từ máy chủ), chúng sẽ được áp dụng ngay lập tức vào `data`, tránh việc lặp lại yêu cầu API.
+// Gọi phương thức này để hỗ trợ SSR
+initSsr()
+```
 
-3.  **Điều hướng Động (Client-side Nav):**
-    Nếu người dùng điều hướng đến trang một cách linh hoạt (không tải lại trang), component sẽ render ngay lập tức mà không cần đợi `init()` hoàn thành. Điều này cho phép hiển thị ngay lập tức **skeleton** hoặc chỉ báo đang tải (`loading`) trong khi dữ liệu đang được tải ở chế độ nền.
+### Tự động hóa qua `AsyncRef`
+Để tránh việc gọi `initSsr()` thủ công, bạn có thể sử dụng phiên bản bất đồng bộ — [**`useApiAsyncRef`**](./useApiAsyncRef.vi.mdx). Nó tự động gọi `initSsr()` khi được tạo.
 ## Đố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`:

package/src/media/functional/functional-basic/api/api.en.mdx

@@ -10,11 +10,12 @@ The `Api` class is a central utility for making HTTP requests. It provides a sim
 
 The class provides a comprehensive set of tools for managing network communication:
 - **CRUD Methods** — execution of `GET`, `POST`, `PUT`, `PATCH`, `DELETE` requests.
-- **Global Configuration** — setting up base URLs, headers, and parameters.
+- **Global Configuration** — setting up base URLs, origins, headers, and parameters.
 - **Lifecycle Hooks** — handling events before and after the request (e.g., for Refresh Token).
 - **Hydration (SSR)** — transferring data from server to client to prevent duplicate requests.
 - **Caching** — saving responses in memory or external storage (LocalStorage).
 - **Response Emulation** — creating mock data for development and testing.
+- **Automatic Localization** — replacement of `{locale}`, `{country}`, and `{language}` markers in request paths.
 - **Loading and Error Management** — integration with global indicator components and error centers.
 
 ## Basic Usage
@@ -40,7 +41,11 @@ You can configure the API behavior globally, for example, during application ini
 
 ```javascript
 // Set the base URL for all relative paths
-Api.setUrl('https://api.example.com/v1/')
+Api.setUrl('/api/')
+
+// Set the origin (protocol and domain) for the base URL
+// If urlRoot starts with '/', the origin will be prepended to it
+Api.setOrigin('https://api.example.com')
 
 // Add common headers (e.g., an authorization token)
 Api.setHeaders({
@@ -51,6 +56,38 @@ Api.setHeaders({
 Api.setRequestDefault({
   app_version: '1.0.0'
 })
+
+// Check if the server is running on localhost
+if (Api.isLocalhost()) {
+  console.log('Running locally')
+}
+```
+
+### setConfig Method
+
+Allows you to set all main settings with a single object.
+
+```javascript
+Api.setConfig({
+  urlRoot: '/api/',
+  origin: 'https://api.example.com',
+  headers: { 'Authorization': 'Bearer ...' },
+  timeout: 5000,
+  devMode: true
+})
+```
+
+## URL Handling
+
+When forming the final URL, the class automatically replaces special markers with current values from the localization settings (`Geo`):
+- `{locale}` — current locale (e.g., `en-US`).
+- `{country}` — current country (e.g., `us`).
+- `{language}` — current language (e.g., `en`).
+
+```javascript
+// If the current locale is 'en-US', the final path will be '/api/en-US/users'
+const data = await Api.get({ path: '{locale}/users' })
+```
 ```
 
 ## Lifecycle Hooks

package/src/media/functional/functional-basic/api/api.ru.mdx

@@ -10,11 +10,12 @@ import {Meta} from '@storybook/addon-docs/blocks'
 
 Класс предоставляет полный набор инструментов для управления сетевым взаимодействием:
 - **CRUD методы** — выполнение `GET`, `POST`, `PUT`, `PATCH`, `DELETE` запросов.
-- **Глобальная конфигурация** — настройка базовых URL, заголовков и параметров.
+- **Глобальная конфигурация** — настройка базовых URL, источников (origin), заголовков и параметров.
 - **Хуки жизненного цикла** — обработка событий до и после запроса (например, для Refresh Token).
 - **Гидратация (SSR)** — передача данных от сервера к клиенту для предотвращения дублирования запросов.
 - **Кэширование** — сохранение ответов в памяти или внешнем хранилище (LocalStorage).
 - **Эмуляция ответов** — создание мок-данных для разработки и тестирования.
+- **Автоматическая локализация** — замена меток `{locale}`, `{country}` и `{language}` в путях запросов.
 - **Управление загрузкой и ошибками** — интеграция с глобальными компонентами индикации и центрами ошибок.
 
 ## Базовое использование
@@ -40,7 +41,11 @@ const newUser = await Api.post<User>({
 
 ```javascript
 // Установка базового URL для всех относительных путей
-Api.setUrl('https://api.example.com/v1/')
+Api.setUrl('/api/')
+
+// Установка источника (протокола и домена) для базового URL
+// Если urlRoot начинается с '/', к нему будет добавлен origin
+Api.setOrigin('https://api.example.com')
 
 // Добавление общих заголовков (например, токен авторизации)
 Api.setHeaders({
@@ -51,6 +56,38 @@ Api.setHeaders({
 Api.setRequestDefault({
   app_version: '1.0.0'
 })
+
+// Проверка, работает ли сервер на localhost
+if (Api.isLocalhost()) {
+  console.log('Работаем локально')
+}
+```
+
+### Метод setConfig
+
+Позволяет установить все основные настройки одним объектом.
+
+```javascript
+Api.setConfig({
+  urlRoot: '/api/',
+  origin: 'https://api.example.com',
+  headers: { 'Authorization': 'Bearer ...' },
+  timeout: 5000,
+  devMode: true
+})
+```
+
+## Работа с URL
+
+При формировании итогового URL класс автоматически заменяет специальные метки на текущие значения из настроек локализации (`Geo`):
+- `{locale}` — текущая локаль (например, `ru-RU`).
+- `{country}` — текущая страна (например, `ru`).
+- `{language}` — текущий язык (например, `ru`).
+
+```javascript
+// Если текущая локаль 'ru-RU', итоговый путь будет '/api/ru-RU/users'
+const data = await Api.get({ path: '{locale}/users' })
+```
 ```
 
 ## Хуки жизненного цикла

package/src/media/functional/functional-basic/api/api.vi.mdx

@@ -10,11 +10,12 @@ Lớp `Api` là công cụ trung tâm để thực hiện các yêu cầu HTTP.
 
 Lớp cung cấp một bộ công cụ toàn diện để quản lý tương tác mạng:
 - **Các phương thức CRUD** — thực hiện các yêu cầu `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
-- **Cấu hình toàn cục** — thiết lập URL cơ sở, tiêu đề và tham số.
+- **Cấu hình toàn cục** — thiết lập URL cơ sở, nguồn (origin), tiêu đề và tham số.
 - **Hook vòng đời** — xử lý các sự kiện trước và sau yêu cầu (ví dụ: cho Refresh Token).
 - **Hydration (SSR)** — chuyển dữ liệu từ máy chủ sang máy khách để ngăn chặn các yêu cầu trùng lặp.
 - **Bộ nhớ đệm (Caching)** — lưu các phản hồi trong bộ nhớ hoặc bộ nhớ ngoài (LocalStorage).
 - **Giả lập phản hồi** — tạo dữ liệu giả để phát triển và kiểm thử.
+- **Tự động bản địa hóa** — thay thế các nhãn `{locale}`, `{country}` và `{language}` trong đường dẫn yêu cầu.
 - **Quản lý tải và lỗi** — tích hợp với các thành phần chỉ báo toàn cục và trung tâm lỗi.
 
 ## Cách dùng cơ bản
@@ -40,7 +41,11 @@ Bạn có thể cấu hình hành vi của API trên toàn hệ thống, ví d
 
 ```javascript
 // Đặt URL cơ sở cho tất cả các đường dẫn tương đối
-Api.setUrl('https://api.example.com/v1/')
+Api.setUrl('/api/')
+
+// Thiết lập nguồn (giao thức và tên miền) cho URL cơ sở
+// Nếu urlRoot bắt đầu bằng '/', origin sẽ được thêm vào trước nó
+Api.setOrigin('https://api.example.com')
 
 // Thêm các tiêu đề chung (ví dụ: token xác thực)
 Api.setHeaders({
@@ -51,6 +56,38 @@ Api.setHeaders({
 Api.setRequestDefault({
   app_version: '1.0.0'
 })
+
+// Kiểm tra xem máy chủ có đang chạy trên localhost không
+if (Api.isLocalhost()) {
+  console.log('Đang chạy trên máy cục bộ')
+}
+```
+
+### Phương thức setConfig
+
+Cho phép thiết lập tất cả các cài đặt chính bằng một đối tượng duy nhất.
+
+```javascript
+Api.setConfig({
+  urlRoot: '/api/',
+  origin: 'https://api.example.com',
+  headers: { 'Authorization': 'Bearer ...' },
+  timeout: 5000,
+  devMode: true
+})
+```
+
+## Xử lý URL
+
+Khi tạo URL cuối cùng, lớp sẽ tự động thay thế các nhãn đặc biệt bằng các giá trị hiện tại từ cài đặt bản địa hóa (`Geo`):
+- `{locale}` — locale hiện tại (ví dụ: `vi-VN`).
+- `{country}` — quốc gia hiện tại (ví dụ: `vn`).
+- `{language}` — ngôn ngữ hiện tại (ví dụ: `vi`).
+
+```javascript
+// Nếu locale hiện tại là 'vi-VN', đường dẫn cuối cùng sẽ là '/api/vi-VN/users'
+const data = await Api.get({ path: '{locale}/users' })
+```
 ```
 
 ## Hook vòng đời

package/src/media/functional/nitro-basic/functions/getInject.en.mdx

@@ -0,0 +1,27 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/nitro-basic/Functions/getInject - Get Injected Value'/>
+
+# `getInject`
+
+A utility function that safely reads an injected value by name from the current Vue component instance. If there is no active component instance or the value is not provided, it returns `undefined`.
+
+**Parameters:**
+- `name: string` — The injection key name.
+
+**Returns:**
+`T | undefined` — The injected value if it exists, otherwise `undefined`.
+
+```typescript
+import { provide } from 'vue'
+import { getInject } from '@dxtmisha/nitro-basic'
+
+provide('theme', 'dark')
+
+// Returns 'dark'
+const theme = getInject<string>('theme')
+
+// Returns undefined when the key is missing
+const language = getInject<string>('language')
+```
+

package/src/media/functional/nitro-basic/functions/getInject.ru.mdx

@@ -0,0 +1,27 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/nitro-basic/Functions/getInject - Получение внедренного значения'/>
+
+# `getInject`
+
+Утилитарная функция, которая безопасно получает внедренное значение по имени из текущего экземпляра Vue-компонента. Если активного экземпляра компонента нет или значение не было предоставлено, функция возвращает `undefined`.
+
+**Параметры:**
+- `name: string` — Имя ключа внедрения.
+
+**Возвращает:**
+`T | undefined` — Внедренное значение, если оно существует, иначе `undefined`.
+
+```typescript
+import { provide } from 'vue'
+import { getInject } from '@dxtmisha/nitro-basic'
+
+provide('theme', 'dark')
+
+// Возвращает 'dark'
+const theme = getInject<string>('theme')
+
+// Возвращает undefined, если ключ отсутствует
+const language = getInject<string>('language')
+```
+

package/src/media/functional/nitro-basic/functions/getInject.vi.mdx

@@ -0,0 +1,20 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/nitro-basic/Functions/getInject - Lấy giá trị được inject'/>
+
+# `getInject`
+
+Một hàm tiện ích dùng để lấy an toàn giá trị được inject theo tên từ instance Vue hiện tại. Nếu không có instance component đang hoạt động hoặc giá trị chưa được cung cấp, hàm sẽ trả về `undefined`.
+
+**Tham số:**
+- `name: string` — Tên của khóa inject.
+
+**Trả về:**
+`T | undefined` — Giá trị được inject nếu tồn tại, ngược lại trả về `undefined`.
+
+**Ví dụ sử dụng:**
+- Gọi `getInject<string>('theme')` trong `setup()` để lấy giá trị đã được `provide`.
+- Nếu key không tồn tại hoặc không có component instance hiện tại, kết quả sẽ là `undefined`.
+
+
+

package/src/media/functional/ui-figma/about/about.en.mdx

@@ -0,0 +1,52 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/# UI Figma/! About the library'/>
+
+# UI Figma Ecosystem
+
+The `UI Figma` system is a comprehensive infrastructure for developing Figma plugins. It is designed to bridge the gap between the "Code Side" (plugin backend) and the "UI Side" (frontend), providing seamless interaction, reactive data management, and full type safety.
+
+The ecosystem is built on a three-tier architecture, where each layer handles a specific part of the plugin lifecycle.
+
+## Three Layers of Interaction
+
+### 1. Communication Core (@dxtmisha/figma)
+The fundamental package that defines interaction protocols. It contains:
+- Message type constants.
+- Shared data types and interfaces.
+- Abstract messenger classes to standardize data exchange.
+- Utilities for routing messages between the UI and the Figma sandbox.
+
+### 2. Plugin Logic (@dxtmisha/figma-code)
+A package running in the Figma execution environment (Sandbox). This is the "brain" of the plugin, with direct access to the Figma API:
+- **Element Analysis**: `FigmaItem` and `FigmaFrame` classes for deep document structure exploration.
+- **Data Persistence**: `FigmaStorage` for working with PluginData (storing data directly in the `.fig` file).
+- **Exporting**: Tools for automated screenshot creation and asset export.
+- **Synchronization**: `FigmaTopLevelFrames` and `FigmaFramesSelected` classes for passing the current document state to the UI.
+
+### 3. Reactive Interface (@dxtmisha/figma-ref)
+A package for developing the user interface using Vue 3. It transforms asynchronous plugin responses into convenient reactive references (composables):
+- **Reactive Stores**: `useFigmaStorage` and `useFigmaClientStorage` for instant data binding between UI and Figma storage.
+- **Observers**: `useFigmaUiFrames` for automatic updates of the available frame list.
+- **Selection Management**: `useFigmaUiSelected` for linking UI-selected elements with Figma's active selection.
+
+## System Features
+
+**Seamless Interaction**
+Developers no longer need to manually manage `postMessage` calls and event listeners. The system handles routing and type validation automatically.
+
+**Out-of-the-box Reactivity**
+Using the Vue Composition API allows you to build plugin interfaces as easily as standard web applications, with data automatically persisting in the Figma document.
+
+**Type Safety**
+All messages and data structures are strictly typed, eliminating errors when passing data between isolated environments (UI and Sandbox).
+
+## Why Use This Ecosystem?
+
+- **Development Speed**: Ready-made foundation for typical tasks (selection, settings, screenshots).
+- **Clean Architecture**: Clear separation of concerns between business logic and the user interface.
+- **Scalability**: Easy to add new features thanks to the modular structure and the Messenger pattern.
+
+## Git
+
+[https://github.com/dxtmisha/dxt-ui/tree/main/packages/figma](https://github.com/dxtmisha/dxt-ui/tree/main/packages/figma)

package/src/media/functional/ui-figma/about/about.ru.mdx

@@ -0,0 +1,52 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/# UI Figma/! О библиотеке'/>
+
+# Экосистема UI Figma
+
+Система `UI Figma` представляет собой комплексную инфраструктуру для разработки плагинов Figma. Она разработана для устранения барьера между «стороной кода» (backend плагина) и «стороной UI» (frontend), обеспечивая бесшовное взаимодействие, реактивное управление данными и полную типизацию.
+
+В основе системы лежит трехуровневая архитектура, где каждый уровень отвечает за свою часть жизненного цикла плагина.
+
+## Три уровня взаимодействия
+
+### 1. Основа связи (@dxtmisha/figma)
+Фундаментальный пакет, определяющий протоколы взаимодействия. Содержит:
+- Константы типов сообщений.
+- Общие типы данных и интерфейсы.
+- Абстрактные классы мессенджеров для стандартизации обмена данными.
+- Утилиты для маршрутизации сообщений между UI и песочницей Figma.
+
+### 2. Логика плагина (@dxtmisha/figma-code)
+Пакет, работающий в среде выполнения Figma (Sandbox). Это «мозг» плагина, имеющий прямой доступ к Figma API:
+- **Анализ элементов**: Классы `FigmaItem` и `FigmaFrame` для глубокого исследования структуры документа.
+- **Хранение данных**: `FigmaStorage` для работы с PluginData (хранение данных в самом файле документа).
+- **Экспорт**: Инструменты для автоматизированного создания скриншотов и экспорта ресурсов.
+- **Синхронизация**: Классы `FigmaTopLevelFrames` и `FigmaFramesSelected` для передачи актуального состояния документа в UI.
+
+### 3. Реактивный интерфейс (@dxtmisha/figma-ref)
+Пакет для разработки пользовательского интерфейса на Vue 3. Он превращает асинхронные ответы от плагина в удобные реактивные ссылки (composables):
+- **Реактивные хранилища**: `useFigmaStorage` и `useFigmaClientStorage` для мгновенной связи данных UI с хранилищем Figma.
+- **Наблюдатели**: `useFigmaUiFrames` для автоматического обновления списка доступных фреймов.
+- **Управление выбором**: `useFigmaUiSelected` для связи выделенных элементов в UI со списком выбора в плагине.
+
+## Возможности системы
+
+**Бесшовное взаимодействие**
+Разработчику больше не нужно вручную прописывать `postMessage` и слушатели событий. Система берет на себя маршрутизацию и проверку типов.
+
+**Реактивность «из коробки»**
+Использование Vue Composition API позволяет строить интерфейс плагина так же просто, как обычное веб-приложение, при этом данные будут автоматически сохраняться в документе Figma.
+
+**Типобезопасность**
+Все сообщения и структуры данных строго типизированы, что исключает ошибки при передаче данных между изолированными средами (UI и Sandbox).
+
+## Преимущества использования
+
+- **Ускорение разработки**: Готовая база для типичных задач (выделение, чтение настроек, скриншоты).
+- **Чистая архитектура**: Четкое разделение ответственности между бизнес-логикой плагина и его интерфейсом.
+- **Масштабируемость**: Легкое добавление новых функций за счет модульной структуры и использования паттерна Messenger.
+
+## Git
+
+[https://github.com/dxtmisha/dxt-ui/tree/main/packages/figma](https://github.com/dxtmisha/dxt-ui/tree/main/packages/figma)