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

<Meta title='@dxtmisha/en/figma-code/Classes/FigmaTopLevelFrames - Top-Level Frame Management'/>

# FigmaTopLevelFrames Class

A static utility class for managing, caching, and communicating the list of top-level frames within the Figma plugin environment. It bridges the gap between the Figma document structure and the plugin UI via a dedicated messenger.

## Key Features

- **Automated Caching** — Efficiently manages a singleton-like cache of formatted frame data.
- **Messenger Integration** — Simplifies bidirectional communication between the plugin and the UI regarding frame lists.
- **Node Processing** — Leverages `FigmaFrame` to extract and format core node properties (ID, name, JPG export) for UI display.

## Static Methods

### `getListData`

Retrieves and caches the formatted list of top-level frames. It processes each main frame from the current page, extracting its ID, name, and exporting it to a JPG format.

**Returns:** `Promise<UiFigmaFramesList>` — A promise that resolves to the array of formatted frame data.

```typescript
const frames = await FigmaTopLevelFrames.getListData()
```

### `send`

Sets up a listener for frame requests using the plugin messenger. When the `UI_FIGMA_FRAMES_POST_NAME` message is received from the UI, it automatically fetches the latest data and posts it back.

**Returns:** `void`

```typescript
FigmaTopLevelFrames.send()
```

## Types

### `UiFigmaFramesList`

An array of objects representing the processed frame data for the UI.
- `id: string` — Unique Figma node ID.
- `name: string` — Display name of the frame.
- `image: Uint8Array | string` — Exported JPG data.
- `item: FigmaItem` — The wrapped `FigmaItem` instance for further operations.
