@dxtmisha/wiki 0.57.1 → 0.57.4

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/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)

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

@@ -0,0 +1,52 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/# UI Figma/! Giới thiệu về thư viện'/>
+
+# Hệ sinh thái UI Figma
+
+Hệ thống `UI Figma` là một cơ sở hạ tầng toàn diện để phát triển các plugin Figma. Nó được thiết kế để xóa bỏ rào cản giữa "phía Mã" (backend của plugin) và "phía UI" (frontend), cung cấp khả năng tương tác liền mạch, quản lý dữ liệu phản hồi và định kiểu dữ liệu đầy đủ.
+
+Hệ sinh thái được xây dựng trên kiến trúc ba tầng, trong đó mỗi lớp xử lý một phần cụ thể trong vòng đời của plugin.
+
+## Ba tầng tương tác
+
+### 1. Cốt lõi giao tiếp (@dxtmisha/figma)
+Gói cơ bản xác định các giao thức tương tác. Nó bao gồm:
+- Các hằng số loại tin nhắn.
+- Các kiểu dữ liệu và giao diện dùng chung.
+- Các lớp trình nhắn tin trừu tượng để tiêu chuẩn hóa việc trao đổi dữ liệu.
+- Các tiện ích để định tuyến tin nhắn giữa UI và sandbox của Figma.
+
+### 2. Logic Plugin (@dxtmisha/figma-code)
+Một gói chạy trong môi trường thực thi của Figma (Sandbox). Đây là "bộ não" của plugin, có quyền truy cập trực tiếp vào Figma API:
+- **Phân tích phần tử**: Các lớp `FigmaItem` và `FigmaFrame` để khám phá sâu cấu trúc tài liệu.
+- **Lưu trữ dữ liệu**: `FigmaStorage` để làm việc với PluginData (lưu trữ dữ liệu trực tiếp trong tệp `.fig`).
+- **Xuất dữ liệu**: Các công cụ để tự động tạo ảnh chụp màn hình và xuất tài sản.
+- **Đồng bộ hóa**: Các lớp `FigmaTopLevelFrames` và `FigmaFramesSelected` để chuyển trạng thái tài liệu hiện tại sang UI.
+
+### 3. Giao diện phản hồi (@dxtmisha/figma-ref)
+Một gói để phát triển giao diện người dùng bằng Vue 3. Nó chuyển đổi các phản hồi bất đồng bộ từ plugin thành các tham chiếu phản hồi (composables) thuận tiện:
+- **Kho lưu trữ phản hồi**: `useFigmaStorage` và `useFigmaClientStorage` để liên kết dữ liệu tức thì giữa UI và bộ nhớ Figma.
+- **Trình quan sát**: `useFigmaUiFrames` để tự động cập nhật danh sách các frame có sẵn.
+- **Quản lý lựa chọn**: `useFigmaUiSelected` để liên kết các phần tử được chọn trong UI với vùng lựa chọn hoạt động trong Figma.
+
+## Các tính năng của hệ thống
+
+**Tương tác liền mạch**
+Các nhà phát triển không còn cần phải quản lý thủ công các lệnh gọi `postMessage` và trình lắng nghe sự kiện. Hệ thống tự động xử lý việc định tuyến và xác thực kiểu dữ liệu.
+
+**Tính phản hồi có sẵn**
+Sử dụng Vue Composition API cho phép bạn xây dựng giao diện plugin dễ dàng như các ứng dụng web tiêu chuẩn, với dữ liệu tự động được lưu trữ bền vững trong tài liệu Figma.
+
+**An toàn kiểu dữ liệu**
+Tất cả các tin nhắn và cấu trúc dữ liệu đều được định kiểu nghiêm ngặt, loại bỏ lỗi khi chuyển dữ liệu giữa các môi trường biệt lập (UI và Sandbox).
+
+## Tại sao nên sử dụng hệ sinh thái này?
+
+- **Tốc độ phát triển**: Nền tảng có sẵn cho các tác vụ điển hình (lựa chọn, cài đặt, ảnh chụp màn hình).
+- **Kiến trúc sạch**: Phân tách rõ ràng các mối quan tâm giữa logic nghiệp vụ và giao diện người dùng.
+- **Khả năng mở rộng**: Dễ dàng thêm các tính năng mới nhờ cấu trúc mô-đun và mô hình Messenger.
+
+## 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/frames/frames.en.mdx

@@ -0,0 +1,58 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/# UI Figma/# Working with Frames'/>
+
+# Working with Frames
+
+The library provides tools for managing the list of frames on the current Figma page and tracking selected elements. This allows you to build complex navigation interfaces and bulk selection systems within your plugin.
+
+## Backend (Backend / plugin/code.ts)
+
+For automatic frame data synchronization, the corresponding handlers must be initialized on the plugin side.
+
+### Initialization
+```typescript
+import { FigmaTopLevelFrames, FigmaFramesSelected } from '@dxtmisha/figma-code'
+
+// Activate listeners for frame list and selection management
+FigmaTopLevelFrames.send()
+FigmaFramesSelected.send()
+```
+
+## Interface (UI / Iframe)
+
+Data about all frames on the page and tools for managing the plugin's internal selection list are available in the interface.
+
+### Page Frame List (Vue)
+Allows you to retrieve a list of all frames and sections at the root of the current page with screenshots.
+
+```typescript
+import { useFigmaUiFrames } from '@dxtmisha/figma-ref'
+
+const { frames, loading } = useFigmaUiFrames()
+
+/* frames.value contains a list of objects:
+  {
+    id: string,
+    name: string,
+    image: Uint8Array | string // JPG screenshot
+  }
+*/
+```
+
+### Plugin Selected Elements (Vue)
+A mechanism for tracking and modifying the list of "selected" elements within the plugin's interface. This state is preserved globally at the plugin session level.
+
+```typescript
+import { useFigmaUiSelected } from '@dxtmisha/figma-ref'
+
+const { 
+  selected,       // List of selected frame IDs
+  isSelected,     // Check function: isSelected(id)
+  toggleSelected, // Toggle function: toggleSelected(id, boolean)
+} = useFigmaUiSelected()
+
+// Example usage:
+const active = isSelected('1:123')
+const toggle = () => toggleSelected('1:123', !active.value)
+```

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

@@ -0,0 +1,58 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/# UI Figma/# Работа с фреймами'/>
+
+# Работа с фреймами
+
+Библиотека предоставляет инструменты для управления списком фреймов на текущей странице Figma и отслеживания выбранных элементов. Это позволяет строить сложные интерфейсы навигации и системы массового выбора внутри плагина.
+
+## Бэкенд (Backend / plugin/code.ts)
+
+Для автоматической синхронизации данных о фреймах необходимо инициализировать соответствующие обработчики на стороне плагина.
+
+### Инициализация
+```typescript
+import { FigmaTopLevelFrames, FigmaFramesSelected } from '@dxtmisha/figma-code'
+
+// Активация слушателей списка фреймов и управления выбором
+FigmaTopLevelFrames.send()
+FigmaFramesSelected.send()
+```
+
+## Интерфейс (UI / Iframe)
+
+В интерфейсе доступны данные о всех фреймах страницы и инструменты для управления внутренним списком выбора плагина.
+
+### Список фреймов страницы (Vue)
+Позволяет получить список всех фреймов и секций в корне текущей страницы со скриншотами.
+
+```typescript
+import { useFigmaUiFrames } from '@dxtmisha/figma-ref'
+
+const { frames, loading } = useFigmaUiFrames()
+
+/* frames.value содержит список объектов:
+  {
+    id: string,
+    name: string,
+    image: Uint8Array | string // Скриншот JPG
+  }
+*/
+```
+
+### Выбранные элементы плагина (Vue)
+Механизм для отслеживания и изменения списка «выбранных» элементов внутри интерфейса плагина. Это состояние сохраняется глобально на уровне сессии плагина.
+
+```typescript
+import { useFigmaUiSelected } from '@dxtmisha/figma-ref'
+
+const { 
+  selected,       // Список ID выбранных фреймов
+  isSelected,     // Функция проверки: isSelected(id)
+  toggleSelected, // Функция переключения: toggleSelected(id, boolean)
+} = useFigmaUiSelected()
+
+// Пример использования:
+const active = isSelected('1:123')
+const toggle = () => toggleSelected('1:123', !active.value)
+```