@dxtmisha/wiki 0.57.1 → 0.57.4

package/src/media/functional/figma-code/classes/FigmaPluginMessenger/FigmaPluginMessenger.ru.mdx

@@ -1,63 +1,33 @@
-import {Meta} from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/ru/figma-code/Classes/FigmaPluginMessenger - Мессенджер плагина'/>
+<Meta title='@dxtmisha/ru/figma-code/Classes/FigmaPluginMessenger - Мессенджер плагина (Backend)'/>
 
-# Класс FigmaPluginMessenger
+# Класс `FigmaPluginMessenger`
 
-Мессенджер для стороны плагина Figma (backend). Обрабатывает отправку сообщений в UI Figma и прослушивание сообщений из UI, используя внутренний API Figma `figma.ui`.
+Специализированный мессенджер для фоновой части (backend) плагина Figma. Он расширяет `FigmaPostAbstract`, обеспечивая надежный уровень связи между основной логикой плагина (сторона кода) и его пользовательским интерфейсом (UI).
+
+## Ключевые особенности
+
+- **Архитектура Синглтон** — Используйте `getInstance()`, чтобы гарантировать, что все части плагина используют один и тот же центр связи.
+- **Упрощенный API** — Оборачивает стандартные методы `figma.ui.postMessage` и `figma.ui.onmessage` в более удобный интерфейс.
+- **Типобезопасность** — Поддерживает генерики для сообщений, обеспечивая согласованность данных.
 
 ## Инициализация
 
-Наследует `FigmaPostAbstract`.
+Доступ к единственному экземпляру осуществляется через статический метод `getInstance()`.
 
 ```typescript
 import { FigmaPluginMessenger } from '@dxtmisha/figma-code'
 
-const messenger = new FigmaPluginMessenger()
-  .make()
-  .add('hello-ui', (msg) => console.log('UI:', msg))
-```
-
-## Публичные методы
-
-### `make`
-
-Инициализирует слушатель сообщений, используя API `figma.ui.onmessage`. Должен быть вызван один раз для начала приема сообщений из UI.
-
-**Возвращает:** `this`
-
-```javascript
-messenger.make()
+const messenger = FigmaPluginMessenger.getInstance()
 ```
 
-### `add`
+## Методы
 
-Регистрирует слушатель для определенного типа сообщения, поступающего из UI.
+### Связь
 
-**Параметры:**
-- `type: string` — Уникальный идентификатор типа сообщения для прослушивания.
-- `callback: (message: Message) => void` — функция, которую необходимо выполнить при получении соответствующего сообщения.
+Методы для отправки и получения сообщений.
 
-**Возвращает:** `this`
-
-```javascript
-messenger.add('resize-ui', (data) => {
-  figma.ui.resize(data.width, data.height)
-})
-```
-
-### `post`
-
-Отправляет сообщение в UI Figma.
-
-**Параметры:**
-- `type: string` — Идентификатор сообщения (тип).
-- `message: Message` — (Опционально) Полезные данные для отправки в UI.
-
-**Возвращает:** `void`
-
-```javascript
-messenger.post('selection-data', { 
-  ids: figma.currentPage.selection.map(node => node.id) 
-})
-```
+- `post<Message>(type: string, message?: Message): void` — Отправляет сообщение определенного типа в UI Figma.
+- `add(type: string, callback: (data: any) => void): this` — (Наследуется) Регистрирует слушателя для сообщений из UI.
+- `remove(type: string): this` — (Наследуется) Удаляет слушателя.

package/src/media/functional/figma-code/classes/FigmaPluginMessenger/FigmaPluginMessenger.vi.mdx

@@ -1,63 +1,33 @@
-import {Meta} from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/vi/figma-code/Classes/FigmaPluginMessenger - Trình nhắn tin Backend'/>
+<Meta title='@dxtmisha/vi/figma-code/Classes/FigmaPluginMessenger - Trình nhắn tin plugin (Backend)'/>
 
-# Lớp FigmaPluginMessenger
+# Lớp `FigmaPluginMessenger`
 
-Trình nhắn tin cho phía plugin Figma (backend). Nó xử lý việc gửi tin nhắn đến UI Figma và lắng nghe tin nhắn từ UI bằng API nội bộ của Figma `figma.ui`.
+Một trình nhắn tin chuyên dụng cho phía backend của plugin Figma. Nó mở rộng `FigmaPostAbstract` để cung cấp một lớp giao tiếp mạnh mẽ giữa logic chính của plugin (phía mã) và giao diện người dùng (UI).
+
+## Các tính năng chính
+
+- **Kiến trúc Singleton** — Sử dụng `getInstance()` để đảm bảo tất cả các phần của plugin đều sử dụng cùng một trung tâm giao tiếp.
+- **API đơn giản hóa** — Bọc các tiêu chuẩn `figma.ui.postMessage` và `figma.ui.onmessage` vào một giao diện dễ quản lý hơn.
+- **An toàn kiểu dữ liệu** — Hỗ trợ các kiểu generic cho tin nhắn để đảm bảo tính nhất quán của dữ liệu.
 
 ## Khởi tạo
 
-Kế thừa từ `FigmaPostAbstract`.
+Truy cập thực thể singleton bằng phương thức tĩnh `getInstance()`.
 
 ```typescript
 import { FigmaPluginMessenger } from '@dxtmisha/figma-code'
 
-const messenger = new FigmaPluginMessenger()
-  .make()
-  .add('hello-ui', (msg) => console.log('UI:', msg))
-```
-
-## Các phương thức công khai
-
-### `make`
-
-Khởi tạo trình lắng nghe tin nhắn bằng API `figma.ui.onmessage`. Nên được gọi một lần để bắt đầu nhận tin nhắn từ UI.
-
-**Trả về:** `this`
-
-```javascript
-messenger.make()
+const messenger = FigmaPluginMessenger.getInstance()
 ```
 
-### `add`
+## Các phương thức
 
-Đăng ký một trình lắng nghe cho một loại tin nhắn cụ thể đến từ UI.
+### Giao tiếp (Communication)
 
-**Tham số:**
-- `type: string` — Mã định danh duy nhất cho loại tin nhắn cần lắng nghe.
-- `callback: (message: Message) => void` — hàm sẽ thực thi khi có một tin nhắn phù hợp đến.
+Các phương thức để gửi và nhận tin nhắn.
 
-**Trả về:** `this`
-
-```javascript
-messenger.add('resize-ui', (data) => {
-  figma.ui.resize(data.width, data.height)
-})
-```
-
-### `post`
-
-Gửi một tin nhắn đến phía UI Figma.
-
-**Tham số:**
-- `type: string` — Mã định danh của tin nhắn (loại).
-- `message: Message` — (Tùy chọn) Dữ liệu payload để gửi đến UI.
-
-**Trả về:** `void`
-
-```javascript
-messenger.post('selection-data', { 
-  ids: figma.currentPage.selection.map(node => node.id) 
-})
-```
+- `post<Message>(type: string, message?: Message): void` — Gửi tin nhắn thuộc một loại cụ thể đến UI của Figma.
+- `add(type: string, callback: (data: any) => void): this` — (Kế thừa) Đăng ký một trình lắng nghe cho các tin nhắn từ UI.
+- `remove(type: string): this` — (Kế thừa) Xóa một trình lắng nghe.

package/src/media/functional/figma-code/classes/FigmaStorage/FigmaStorage.en.mdx

@@ -1,90 +1,45 @@
-import {Meta} from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/en/figma-code/Classes/FigmaStorage - Storage Manager'/>
+<Meta title='@dxtmisha/en/figma-code/Classes/FigmaStorage - Working with document storage'/>
 
-# FigmaStorage Class
+# Class `FigmaStorage`
 
-A class for robust management of Figma's `PluginData`. It provides a high-level API for storing, retrieving, and expiring data on Figma nodes (defaulting to the root node), with support for in-memory caching and default values.
+A high-level wrapper for Figma's `setPluginData` and `getPluginData` APIs. It allows for storing structured data directly within the Figma document, either globally (`figma.root`) or attached to specific nodes. These data are shared among all users collaborating on the file.
 
 ## Key Features
 
-- **Persistence** — Wraps `getPluginData` and `setPluginData` for seamless data storage.
-- **In-Memory Caching** — Stores values in the instance for fast access during the current execution context.
-- **Expiration Logic** — Supports age-based caching to invalidate stale data.
-- **Functional Values** — Supports passing functions as values or default values for dynamic data generation.
+- **Node-Specific Storage** — Data can be bound to any Figma node (Frame, Group, etc.) or the document root.
+- **Shared Access** — Unlike client storage, plugin data is saved inside the `.fig` file and is synchronized across all users.
+- **Instance Management** — The class uses internal caching to ensure that multiple calls for the same key on the same node return the same instance.
+- **Automatic Serialization** — Handles JSON conversion for complex data structures transparently.
 
 ## Initialization
 
-To initialize the object, call the `FigmaStorage(name, item, cache)` constructor.
-
-### Generic Parameters
-
-The class supports a generic parameter for typed data management:
-- `T` — The type of the value being stored and retrieved.
-
-**Parameters:**
-- `name: string` — The unique key name for the storage item.
-- `item: PluginDataMixin = figma.root` — The Figma node where the data will be stored. Defaults to `figma.root`.
-- `cache: number` — (Optional) TTL in seconds for the stored data.
+Access an instance using static methods. You can provide a raw node or a node ID.
 
 ```typescript
 import { FigmaStorage } from '@dxtmisha/figma-code'
 
-// 1. Initialize with implicit typing
-const settings = new FigmaStorage('plugin-settings')
+// Get instance for the entire document
+const globalStorage = FigmaStorage.getInstance<object>('app-settings')
 
-// 2. Initialize with explicit generic for strict typing
-interface MyData { theme: string; version: number }
-const typedSettings = new FigmaStorage<MyData>('app-data')
-
-// 3. Initialize with a 1-hour cache
-const cacheSettings = new FigmaStorage('cache', figma.root, 3600)
+// Get instance for a specific node by ID
+const nodeStorage = await FigmaStorage.getInstanceById<string>('element-name', '1:123')
 ```
 
 ## Methods
 
-### `get`
-
-Retrieves data from storage with support for default values and cache validation.
-
-**Parameters:**
-- `defaultValue: T | (() => T)` — (Optional) Value returned (and saved) if storage is empty or expired.
-
-**Returns:** `T | undefined`
-
-```javascript
-const val = settings.get('default_val')
-```
-
-### `set`
+### Data Access
 
-Updates the data in both the in-memory cache and the Figma node's `PluginData`.
+Methods for managing data stored in the document.
 
-**Parameters:**
-- `value: T | (() => T)` — (Optional) New value or a function that returns the new value.
+- `get(defaultValue?: T | (() => T)): T | undefined` — Retrieves data from the node. Sets a default value if the storage is empty.
+- `set(value?: T | (() => T)): T | undefined` — Updates the data for the node and returns the new value.
+- `remove(): this` — Clears the plugin data for the specified key on the node.
 
-**Returns:** `T | undefined`
+### Instance Management (Static)
 
-```javascript
-settings.set({ theme: 'dark' })
-```
-
-### `remove`
-
-Clears the data from both the in-memory cache and the Figma node's `PluginData`.
-
-**Returns:** `this`
-
-```javascript
-settings.remove()
-```
-
-### `getName`
-
-Returns the key name used for this storage instance.
+Methods for retrieving class instances.
 
-**Returns:** `string`
-
-```javascript
-console.log(settings.getName())
-```
+- `static getInstance<T>(name: string, item: UiFigmaNode): FigmaStorage<T>` — Returns an instance for a specific node.
+- `static getInstanceById<T>(name: string, id?: string): Promise<FigmaStorage<T>>` — Asynchronously retrieves an instance using a node ID.

package/src/media/functional/figma-code/classes/FigmaStorage/FigmaStorage.ru.mdx

@@ -1,90 +1,45 @@
-import {Meta} from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/ru/figma-code/Classes/FigmaStorage - Менеджер хранилища'/>
+<Meta title='@dxtmisha/ru/figma-code/Classes/FigmaStorage - Работа с хранилищем документа'/>
 
-# Класс FigmaStorage
+# Класс `FigmaStorage`
 
-Класс для управления `PluginData` в Figma. Предоставляет высокоуровневый API для сохранения, получения и контроля срока жизни данных на узлах Figma (по умолчанию — корень документа), с поддержкой кэширования в памяти и значений по умолчанию.
+Высокоуровневая обертка над API `setPluginData` и `getPluginData` в Figma. Позволяет сохранять структурированные данные непосредственно внутри документа Figma — либо глобально (`figma.root`), либо с привязкой к конкретным узлам. Эти данные синхронизируются между всеми пользователями, работающими с файлом.
 
 ## Ключевые особенности
 
-- **Персистентность** — Обертка над `getPluginData` и `setPluginData` для удобного хранения данных.
-- **Кэширование в памяти** — Сохраняет значения в экземпляре для быстрого доступа во время выполнения.
-- **Логика истечения срока** — Поддержка кэширования на основе времени для инвалидации устаревших данных.
-- **Функциональные значения** — Поддержка передачи функций в качестве значений или значений по умолчанию для динамической генерации данных.
+- **Привязка к узлам** — Данные могут быть привязаны к любому узлу Figma (фрейму, группе и т.д.) или к корню документа.
+- **Общий доступ** — В отличие от клиентского хранилища, данные плагина сохраняются внутри файла `.fig` и доступны всем пользователям.
+- **Управление экземплярами** — Класс использует внутреннее кэширование, гарантируя, что повторные вызовы для одного и того же ключа на одном узле вернут один и тот же экземпляр.
+- **Автоматическая сериализация** — Прозрачно обрабатывает преобразование сложных структур данных в JSON и обратно.
 
 ## Инициализация
 
-Для инициализации объекта вызовите конструктор `FigmaStorage(name, item, cache)`.
-
-### Параметры универсального типа (Generics)
-
-Класс поддерживает параметр универсального типа для типизированного управления данными:
-- `T` — Тип сохраняемого и получаемого значения.
-
-**Параметры:**
-- `name: string` — Уникальное имя ключа для элемента хранилища.
-- `item: PluginDataMixin = figma.root` — Узел Figma, в котором будут храниться данные. По умолчанию — `figma.root`.
-- `cache: number` — (Опционально) Время жизни (TTL) данных в секундах.
+Доступ к экземпляру осуществляется через статические методы. Можно передать сам узел или его ID.
 
 ```typescript
 import { FigmaStorage } from '@dxtmisha/figma-code'
 
-// 1. Инициализация с неявной типизацией
-const settings = new FigmaStorage('plugin-settings')
+// Получение экземпляра для всего документа
+const globalStorage = FigmaStorage.getInstance<object>('app-settings')
 
-// 2. Использование дженериков для строгой типизации
-interface MyData { theme: string; version: number }
-const typedSettings = new FigmaStorage<MyData>('app-data')
-
-// 3. Инициализация с кэшированием на 1 час
-const cacheSettings = new FigmaStorage('cache', figma.root, 3600)
+// Получение экземпляра для конкретного узла по его ID
+const nodeStorage = await FigmaStorage.getInstanceById<string>('element-name', '1:123')
 ```
 
 ## Методы
 
-### `get`
-
-Получает данные из хранилища с поддержкой значений по умолчанию и проверки кэша.
-
-**Параметры:**
-- `defaultValue: T | (() => T)` — (Опционально) Значение, которое возвращается (и сохраняется), если хранилище пустое или срок действия данных истек.
-
-**Возвращает:** `T | undefined`
-
-```javascript
-const val = settings.get('default_val')
-```
-
-### `set`
+### Доступ к данным
 
-Обновляет данные как в кэше в памяти, так и в `PluginData` узла Figma.
+Методы для управления данными, хранящимися в документе.
 
-**Параметры:**
-- `value: T | (() => T)` — (Опционально) Новое значение или функция, возвращающая новое значение.
+- `get(defaultValue?: T | (() => T)): T | undefined` — Извлекает данные. Устанавливает значение по умолчанию, если хранилище пустое.
+- `set(value?: T | (() => T)): T | undefined` — Обновляет данные и возвращает новое значение.
+- `remove(): this` — Очищает данные плагина для указанного ключа на узле.
 
-**Возвращает:** `T | undefined`
+### Управление экземплярами (Статические)
 
-```javascript
-settings.set({ theme: 'dark' })
-```
-
-### `remove`
-
-Очищает данные как из кэша в памяти, так и из `PluginData` узла Figma.
-
-**Возвращает:** `this`
-
-```javascript
-settings.remove()
-```
-
-### `getName`
-
-Возвращает имя ключа, используемое этим экземпляром хранилища.
+Методы для получения экземпляров класса.
 
-**Возвращает:** `string`
-
-```javascript
-console.log(settings.getName())
-```
+- `static getInstance<T>(name: string, item: UiFigmaNode): FigmaStorage<T>` — Возвращает экземпляр для конкретного узла.
+- `static getInstanceById<T>(name: string, id?: string): Promise<FigmaStorage<T>>` — Асинхронно получает экземпляр, используя ID узла.

package/src/media/functional/figma-code/classes/FigmaStorage/FigmaStorage.vi.mdx

@@ -1,90 +1,45 @@
-import {Meta} from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/vi/figma-code/Classes/FigmaStorage - Quản lý Lưu trữ'/>
+<Meta title='@dxtmisha/vi/figma-code/Classes/FigmaStorage - Làm việc với bộ nhớ tài liệu'/>
 
-# Lớp FigmaStorage
+# Lớp `FigmaStorage`
 
-Một lớp để quản lý `PluginData` trong Figma một cách mạnh mẽ. Nó cung cấp một API cấp cao để lưu trữ, truy xuất và kiểm soát thời hạn của dữ liệu trên các node Figma (mặc định là node gốc của tài liệu), hỗ trợ bộ nhớ đệm (caching) và các giá trị mặc định.
+Một lớp bọc cấp cao cho các API `setPluginData` và `getPluginData` của Figma. Nó cho phép lưu trữ dữ liệu có cấu trúc trực tiếp trong tài liệu Figma, theo cách toàn cục (`figma.root`) hoặc đính kèm với các node cụ thể. Dữ liệu này được chia sẻ giữa tất cả người dùng cộng tác trên tệp.
 
 ## Các tính năng chính
 
-- **Tính kiên trì (Persistence)** — Bao bọc `getPluginData` và `setPluginData` để lưu trữ dữ liệu liền mạch.
-- **Bộ nhớ đệm (In-Memory Caching)** — Lưu trữ các giá trị trong thực thể để truy cập nhanh trong ngữ cảnh thực thi hiện tại.
-- **Logic hết hạn** — Hỗ trợ lưu trữ dựa trên thời gian để vô hiệu hóa dữ liệu lỗi thời.
-- **Giá trị chức năng** — Hỗ trợ truyền các hàm dưới dạng giá trị hoặc giá trị mặc định để tạo dữ liệu động.
+- **Lưu trữ theo node cụ thể** — Dữ liệu có thể được liên kết với bất kỳ node Figma nào (Frame, Group, v.v.) hoặc gốc của tài liệu.
+- **Truy cập chung** — Không giống như bộ nhớ client, dữ liệu plugin được lưu bên trong tệp `.fig` và được đồng bộ hóa giữa tất cả người dùng.
+- **Quản lý thực thể** — Lớp sử dụng cơ chế lưu tạm nội bộ để đảm bảo rằng các lệnh gọi lặp lại cho cùng một khóa trên cùng một node sẽ trả về cùng một thực thể.
+- **Tự động tuần tự hóa** — Xử lý việc chuyển đổi JSON cho các cấu trúc dữ liệu phức tạp một cách minh bạch.
 
 ## Khởi tạo
 
-Khởi tạo đối tượng bằng cách gọi hàm dựng `FigmaStorage(name, item, cache)`.
-
-### Tham số Generics
-
-Lớp hỗ trợ một tham số generic để quản lý dữ liệu có định kiểu:
-- `T` — Kiểu dữ liệu của giá trị được lưu trữ và truy xuất.
-
-**Tham số:**
-- `name: string` — Tên khóa duy nhất cho mục lưu trữ.
-- `item: PluginDataMixin = figma.root` — Node Figma nơi dữ liệu sẽ được lưu trữ. Mặc định là `figma.root`.
-- `cache: number` — (Tùy chọn) Thời gian sống (TTL) tính bằng giây cho dữ liệu được lưu trữ.
+Truy cập một thực thể bằng cách sử dụng các phương thức tĩnh. Bạn có thể cung cấp một node gốc hoặc một ID node.
 
 ```typescript
 import { FigmaStorage } from '@dxtmisha/figma-code'
 
-// 1. Khởi tạo với kiểu dữ liệu ngầm định
-const settings = new FigmaStorage('plugin-settings')
+// Lấy thực thể cho toàn bộ tài liệu
+const globalStorage = FigmaStorage.getInstance<object>('app-settings')
 
-// 2. Sử dụng generics để định kiểu nghiêm ngặt
-interface MyData { theme: string; version: number }
-const typedSettings = new FigmaStorage<MyData>('app-data')
-
-// 3. Khởi tạo với bộ nhớ đệm 1 giờ
-const cacheSettings = new FigmaStorage('cache', figma.root, 3600)
+// Lấy thực thể cho một node cụ thể bằng ID
+const nodeStorage = await FigmaStorage.getInstanceById<string>('element-name', '1:123')
 ```
 
 ## Các phương thức
 
-### `get`
-
-Truy xuất dữ liệu từ bộ lưu trữ với hỗ trợ các giá trị mặc định và xác thực bộ nhớ đệm.
-
-**Tham số:**
-- `defaultValue: T | (() => T)` — (Tùy chọn) Giá trị được trả về (và bộ lưu trữ) nếu bộ lưu trữ trống hoặc hết hạn.
-
-**Trả về:** `T | undefined`
-
-```javascript
-const val = settings.get('default_val')
-```
-
-### `set`
+### Truy cập dữ liệu
 
-Cập nhật dữ liệu trong cả bộ nhớ đệm trong bộ nhớ và `PluginData` của node Figma.
+Các phương thức để quản lý dữ liệu được lưu trữ trong tài liệu.
 
-**Tham số:**
-- `value: T | (() => T)` — (Tùy chọn) Giá trị mới hoặc một hàm trả về giá trị mới.
+- `get(defaultValue?: T | (() => T)): T | undefined` — Truy xuất dữ liệu. Thiết lập giá trị mặc định nếu bộ nhớ đang trống.
+- `set(value?: T | (() => T)): T | undefined` — Cập nhật dữ liệu và trả về giá trị mới.
+- `remove(): this` — Xóa dữ liệu plugin cho khóa đã chỉ định trên node.
 
-**Trả về:** `T | undefined`
+### Quản lý thực thể (Tĩnh)
 
-```javascript
-settings.set({ theme: 'dark' })
-```
-
-### `remove`
-
-Xóa dữ liệu khỏi cả bộ nhớ đệm trong bộ nhớ và `PluginData` của node Figma.
-
-**Trả về:** `this`
-
-```javascript
-settings.remove()
-```
-
-### `getName`
-
-Trả về tên khóa được sử dụng cho thực thể lưu trữ này.
+Các phương thức để truy xuất các thực thể của lớp.
 
-**Trả về:** `string`
-
-```javascript
-console.log(settings.getName())
-```
+- `static getInstance<T>(name: string, item: UiFigmaNode): FigmaStorage<T>` — Trả về một thực thể cho một node cụ thể.
+- `static getInstanceById<T>(name: string, id?: string): Promise<FigmaStorage<T>>` — Lấy một thực thể một cách bất đồng bộ bằng ID node.

package/src/media/functional/figma-code/classes/FigmaStorageData/FigmaStorageData.en.mdx

@@ -0,0 +1,57 @@
+import { Meta, Source } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/figma-code/Classes/FigmaStorageData - Storage data container'/>
+
+# Class `FigmaStorageData`
+
+A low-level container for managing individual data entries within Figma's storage systems (Client Storage or Plugin Data). It tracks values along with their update time (age) and handles cache expiration logic.
+
+## Key Features
+
+- **Cache Tracking** — Automatically determines if data is still valid based on a configurable Time-To-Live (TTL).
+- **Update Monitoring** — Stores the timestamp of the last update to facilitate data freshness checks.
+- **Serialization Ready** — Provides methods to convert data to and from a standard storage format (`FigmaStorageDataValue`).
+
+## Initialization
+
+Initialize with a key name and an optional cache time in seconds.
+
+```typescript
+import { FigmaStorageData } from '@dxtmisha/figma-code'
+
+// Cache for 1 hour (3600 seconds)
+const dataContainer = new FigmaStorageData<string>('user-name', 3600)
+```
+
+## Methods
+
+### State Checks
+
+- `isNull(): boolean` — Checks if the current value is null or undefined.
+- `isCache(): boolean` — Checks if the data is within its allowed cache lifetime.
+- `isValue(): boolean` — Returns true if the value is defined and the cache is valid.
+
+### Accessors
+
+- `get(): T | undefined` — Returns the current value.
+- `getAge(): number | undefined` — Returns the timestamp of the last update.
+- `getName(): string` — Returns the unique storage key name (prefixed).
+- `getCache(): number | undefined` — Returns the configured cache time.
+
+### Modifiers
+
+- `set(value?: T, age?: number): this` — Manually sets both value and age.
+- `setByObject(value?: FigmaStorageDataValue<T>): this` — Sets data from a storage object.
+- `update(value?: T): this` — Updates the value and sets the age to the current timestamp.
+- `remove(): this` — Clears the value and age.
+
+### Conversion
+
+- `toValue(): FigmaStorageDataValue<T>` — Converts the current state to a storage-compatible object.
+
+## Data Types
+
+#### `FigmaStorageDataValue<T>`
+The structure used for persistent storage.
+- `value: T` — The actual data.
+- `age: number` — The timestamp (ms) of when the data was saved.

package/src/media/functional/figma-code/classes/FigmaStorageData/FigmaStorageData.ru.mdx

@@ -0,0 +1,57 @@
+import { Meta, Source } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/figma-code/Classes/FigmaStorageData - Контейнер данных хранилища'/>
+
+# Класс `FigmaStorageData`
+
+Низкоуровневый контейнер для управления отдельными записями данных в системах хранения Figma (Client Storage или Plugin Data). Он отслеживает значения вместе с временем их обновления (возрастом) и обрабатывает логику истечения срока действия кэша.
+
+## Ключевые особенности
+
+- **Отслеживание кэша** — Автоматически определяет, актуальны ли данные на основе настраиваемого времени жизни (TTL).
+- **Мониторинг обновлений** — Сохраняет метку времени последнего обновления для облегчения проверки свежести данных.
+- **Готовность к сериализации** — Предоставляет методы для преобразования данных в стандартный формат хранения (`FigmaStorageDataValue`) и обратно.
+
+## Инициализация
+
+Инициализируется именем ключа и опциональным временем кэширования в секундах.
+
+```typescript
+import { FigmaStorageData } from '@dxtmisha/figma-code'
+
+// Кэш на 1 час (3600 секунд)
+const dataContainer = new FigmaStorageData<string>('user-name', 3600)
+```
+
+## Методы
+
+### Проверка состояния
+
+- `isNull(): boolean` — Проверяет, является ли текущее значение null или undefined.
+- `isCache(): boolean` — Проверяет, находятся ли данные в пределах разрешенного времени жизни кэша.
+- `isValue(): boolean` — Возвращает true, если значение определено и кэш валиден.
+
+### Аксессоры
+
+- `get(): T | undefined` — Возвращает текущее значение.
+- `getAge(): number | undefined` — Возвращает метку времени последнего обновления.
+- `getName(): string` — Возвращает уникальное имя ключа хранилища (с префиксом).
+- `getCache(): number | undefined` — Возвращает настроенное время кэширования.
+
+### Модификаторы
+
+- `set(value?: T, age?: number): this` — Вручную устанавливает значение и время.
+- `setByObject(value?: FigmaStorageDataValue<T>): this` — Устанавливает данные из объекта хранилища.
+- `update(value?: T): this` — Обновляет значение и устанавливает текущую метку времени.
+- `remove(): this` — Очищает значение и время.
+
+### Преобразование
+
+- `toValue(): FigmaStorageDataValue<T>` — Преобразует текущее состояние в объект, совместимый с хранилищем.
+
+## Типы данных
+
+#### `FigmaStorageDataValue<T>`
+Структура, используемая для постоянного хранения.
+- `value: T` — Фактические данные.
+- `age: number` — Метка времени (мс) момента сохранения данных.