import { Meta, Source } from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/ru/figma-code/Classes/FigmaStorage - Работа с хранилищем документа'/>

# Класс `FigmaStorage`

Высокоуровневая обертка над API `setPluginData` и `getPluginData` в Figma. Позволяет сохранять структурированные данные непосредственно внутри документа Figma — либо глобально (`figma.root`), либо с привязкой к конкретным узлам. Эти данные синхронизируются между всеми пользователями, работающими с файлом.

## Ключевые особенности

- **Привязка к узлам** — Данные могут быть привязаны к любому узлу Figma (фрейму, группе и т.д.) или к корню документа.
- **Общий доступ** — В отличие от клиентского хранилища, данные плагина сохраняются внутри файла `.fig` и доступны всем пользователям.
- **Управление экземплярами** — Класс использует внутреннее кэширование, гарантируя, что повторные вызовы для одного и того же ключа на одном узле вернут один и тот же экземпляр.
- **Автоматическая сериализация** — Прозрачно обрабатывает преобразование сложных структур данных в JSON и обратно.

## Инициализация

Доступ к экземпляру осуществляется через статические методы. Можно передать сам узел или его ID.

```typescript
import { FigmaStorage } from '@dxtmisha/figma-code'

// Получение экземпляра для всего документа
const globalStorage = FigmaStorage.getInstance<object>('app-settings')

// Получение экземпляра для конкретного узла по его ID
const nodeStorage = await FigmaStorage.getInstanceById<string>('element-name', '1:123')
```

## Методы

### Доступ к данным

Методы для управления данными, хранящимися в документе.

- `get(defaultValue?: T | (() => T)): T | undefined` — Извлекает данные. Устанавливает значение по умолчанию, если хранилище пустое.
- `set(value?: T | (() => T)): T | undefined` — Обновляет данные и возвращает новое значение.
- `remove(): this` — Очищает данные плагина для указанного ключа на узле.

### Управление экземплярами (Статические)

Методы для получения экземпляров класса.

- `static getInstance<T>(name: string, item: UiFigmaNode): FigmaStorage<T>` — Возвращает экземпляр для конкретного узла.
- `static getInstanceById<T>(name: string, id?: string): Promise<FigmaStorage<T>>` — Асинхронно получает экземпляр, используя ID узла.
