@dxtmisha/wiki 0.57.1 → 0.57.4

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

@@ -1,61 +1,194 @@
-import {Meta} from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/en/figma-code/Classes/FigmaFrame - Frame Manager'/>
+<Meta title='@dxtmisha/en/figma-code/Classes/FigmaFrame - Analyzing Figma structure'/>
 
-# FigmaFrame Class
+# Class `FigmaFrame`
 
-A comprehensive utility for navigating and extracting data from Figma frames and sections. It supports recursive node analysis and grouping for both entire pages and active selections.
+A utility class for analyzing and interacting with the structure of Figma pages or selections. It recursively scans node trees, filters elements by type, and provides helper methods for text extraction and screenshot generation.
 
 ## Key Features
 
-- **Context Sensitivity** — Automatically handles logic differences between full page analysis and active selection.
-- **Node Filtering** — Specialized methods to retrieve only frames, sections, or text nodes from the hierarchy.
-- **Text Aggregation** — Grouping of text nodes by content for easier translation and analysis.
-- **Bulk Export** — Streamlined asynchronous screenshotting for all main items in the context.
+- **Recursive Scanning** — Automatically indexes all nested elements within the provided context (page or selection).
+- **Selection Support** — Can be initialized to target either the entire document page or only the user's current selection.
+- **Text Aggregation** — The `getTexts()` method groups identical text strings together, providing a list of unique values and their associated node IDs.
+- **Automated Export** — Simplifies the process of generating screenshots for main elements within the frame.
 
 ## Initialization
 
-To initialize the object, call the `FigmaFrame(page, selection)` constructor.
-
-**Parameters:**
-- `page: UiFigmaNode` — The root node (usually `figma.currentPage` or a `PageNode`) for analysis.
-- `selection: boolean = false` — If `true`, the instance will only process nodes within the current selection instead of the entire page.
+Create a new instance by providing a starting node (usually a page) and specifying if it should focus on the selection.
 
 ```typescript
 import { FigmaFrame } from '@dxtmisha/figma-code'
 
-// 1. Initialize for the entire page
-const pageManager = new FigmaFrame(figma.currentPage)
+// Analyze the entire current page
+const frameAnalyzer = new FigmaFrame(figma.currentPage)
+
+// Analyze only the selected items
+const selectionAnalyzer = new FigmaFrame(figma.currentPage, true)
+```
+
+## Methods
+
+### State and Navigation
+
+- `isSelection(): boolean` — Checks if the analyzer was initialized to work with the user's current selection.
+- `getMainFrames(): FigmaItem[]` — Extracts the main frames or sections from the root of the current context.
+
+### Filtering and Selection
+
+- `getItemsFrame(): FigmaItem<FrameNode>[]` — Returns a list of all nested nodes that are frames.
+- `getItemsSection(): FigmaItem<SectionNode>[]` — Returns a list of all nested nodes that are sections.
+- `getItemsText(): FigmaItem<TextNode>[]` — Returns a list of all nested text nodes.
+
+### Content and Information
+
+#### `getItemsInfo`
+
+Asynchronously collects detailed information (name, ID, screenshot) for all items in the frame.
+
+**Returns:** `Promise<UiFigmaFramesList>` — A promise with a list of item information.
+
+```typescript
+const infoList: UiFigmaFramesList = await frame.getItemsInfo()
+/*
+[
+  { id: '1:10', name: 'Button', image: Uint8Array[...] },
+  { id: '1:25', name: 'Card', image: 'data:image/png;base64...' }
+]
+*/
+```
+
+#### `getMainItemsInfo`
+
+Asynchronously collects detailed information only for the main (top-level) elements.
+
+**Returns:** `Promise<UiFigmaFramesList>` — A promise with a list of main item information.
+
+```typescript
+const mainInfoList: UiFigmaFramesList = await frame.getMainItemsInfo()
+/*
+[
+  { id: '1:10', name: 'Login Screen', image: Uint8Array[...] }
+]
+*/
+```
+
+#### `getTexts`
 
-// 2. Initialize specifically for the active selection
-const selectionManager = new FigmaFrame(figma.currentPage, true)
+Groups text nodes by their content, returning unique strings and a list of corresponding node IDs.
+
+**Returns:** `UiFigmaItemText[]` — An array of grouped text items.
+
+```typescript
+const groupedTexts: UiFigmaItemText[] = frame.getTexts()
+/*
+[
+  { id: ['1:10', '1:15'], text: 'Submit' },
+  { id: ['1:20'], text: 'Cancel' }
+]
+*/
+```
+
+### Styles Analysis
+
+#### `getItemsCss`
+
+Generates a map of CSS styles for all items in the frame.
+
+**Returns:** `Promise<UiFigmaFrameStylesCssList>` — A promise with a style map indexed by node ID.
+
+```typescript
+const cssStyles: UiFigmaFrameStylesCssList = await frame.getItemsCss()
+/*
+{
+  '1:10': { 'color': '#ff0000', 'font-size': '14px' },
+  '1:12': { 'background': '#ffffff', 'padding': '10px' }
+}
+*/
+```
+
+#### `getItemsStyles`
+
+Extracts full style data (document JSON structure, text, CSS) for all items.
+
+**Returns:** `Promise<UiFigmaFrameStylesList>` — A promise with a list of extended style data.
+
+```typescript
+const stylesList: UiFigmaFrameStylesList = await frame.getItemsStyles()
+/*
+[
+  { 
+    id: '1:10', 
+    name: 'Label', 
+    text: 'Username', 
+    styles: { 'color': '#333' },
+    json: { document: {...}, styles: {...} }
+  }
+]
+*/
+```
+
+#### `getMainItemsStyles`
+
+Extracts full style data only for the main elements, including styles of their children.
+
+**Returns:** `Promise<UiFigmaFrameStylesList>` — A promise with a list of extended style data for main elements.
+
+```typescript
+const mainStylesList: UiFigmaFrameStylesList = await frame.getMainItemsStyles()
+/*
+[
+  { 
+    id: '1:10', 
+    name: 'Login Form', 
+    childrenStyles: {
+       '1:11': { 'color': '#000' },
+       '1:12': { 'margin-top': '20px' }
+    }
+  }
+]
+*/
 ```
 
-## Context & Analysis
+### Actions and Export
 
-- `isSelection(): boolean` — Checks if work is limited to the active selection. Example: `frameManager.isSelection()`
-- `getMainFrames(): FigmaItem[]` — Returns top-level frames/sections from the root. Example: `const roots = frameManager.getMainFrames()`
+- `screenshot(): Promise<Uint8Array[]>` — Creates screenshots in JPG format for all main elements.
 
-## Hierarchy Filtering
+## Data Types
 
-- `getItemsFrame(): FigmaItem<FrameNode>[]` — Filters hierarchy for FRAME nodes. Example: `const frames = frameManager.getItemsFrame()`
-- `getItemsSection(): FigmaItem<SectionNode>[]` — Filters hierarchy for SECTION nodes. Example: `const sections = frameManager.getItemsSection()`
-- `getItemsText(): FigmaItem<TextNode>[]` — Filters hierarchy for TEXT nodes. Example: `const textNodes = frameManager.getItemsText()`
+#### `UiFigmaNode`
+The base type for Figma nodes. It represents a union of nodes (`SceneNode | DocumentNode | PageNode | FrameNode`, etc.) that support nesting and standard Figma API properties.
 
-## Data & Capture
+#### `UiFigmaItemText`
+The result of grouping text layers by their content.
+- `id: string[]` — An array of unique node identifiers that have the same text.
+- `text: string` — The actual text string.
 
-- `getTexts(): UiFigmaItemText[]` — Aggregates all text nodes grouped by content. Example: `const groups = frameManager.getTexts()`
-- `screenshot(): Promise<Uint8Array[]>` — Captures JPG screenshots of all main items. Example: `const images = await frameManager.screenshot()`
+#### `UiFigmaMessageTexts`
+A data structure for transmitting text analysis results.
+- `frame: FigmaFrame` — An instance of the analyzer class.
+- `texts: UiFigmaItemText[]` — A list of found and grouped text items.
+- `screenshot: Uint8Array[]` — An array of screenshots for the main elements.
 
-## Types
+#### `UiFigmaFramesItem`
+Simplified information about an element for display in the interface.
+- `name: string` — The name of the element in Figma.
+- `id: string` — The unique identifier of the node.
+- `image?: Uint8Array | string` — A screenshot of the element (binary data or base64).
 
-### `UiFigmaNode`
+#### `UiFigmaFrameStylesItem`
+Extended information about an element, including its styles. Inherits all fields from `UiFigmaFramesItem`.
+- `json?: UiFigmaFrameStylesData` — Node data and styles structure in JSON format.
+- `text?: string` — Text content (if the node is a text node).
+- `styles?: Record<string, string>` — An object with CSS properties of the element itself.
+- `childrenStyles?: Record<string, Record<string, string>>` — A map of CSS styles for all child elements, indexed by their ID.
 
-A union type representing any relevant Figma node that can contain children or be processed by the manager.
-- Includes: `DocumentNode`, `PageNode`, `FrameNode`, `SectionNode`, `TextNode`, and other `SceneNode` variants.
+#### `UiFigmaFrameStylesData`
+- `document: UiFigmaFrameStylesJson` — Node tree in a compact format.
+- `styles: Record<string, any>` — A dictionary of document style definitions.
 
-### `UiFigmaItemText`
+#### `UiFigmaFrameStylesList`
+An array of `UiFigmaFrameStylesItem` objects.
 
-An object structure used for grouping text content across the document.
-- `id: string[]` — A list of unique Figma node IDs where this exact text content is found.
-- `text: string` — The actual trimmed string content.
+#### `UiFigmaFrameStylesCssList`
+An object (`Record<string, Record<string, string>>`) where the key is the node ID and the value is its set of CSS styles.

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

@@ -1,61 +1,194 @@
-import {Meta} from '@storybook/addon-docs/blocks'
+import { Meta, Source } from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/ru/figma-code/Classes/FigmaFrame - Менеджер фреймов'/>
+<Meta title='@dxtmisha/ru/figma-code/Classes/FigmaFrame - Анализ структуры Figma'/>
 
-# Класс FigmaFrame
+# Класс `FigmaFrame`
 
-Комплексная утилита для навигации и извлечения данных из фреймов и секций Figma. Поддерживает рекурсивный анализ и группировку узлов как для целых страниц, так и для активных выделений.
+Утилитарный класс для анализа и взаимодействия со структурой страниц или выделенных областей в Figma. Он рекурсивно сканирует дерево узлов, фильтрует элементы по типу и предоставляет вспомогательные методы для извлечения текста и генерации скриншотов.
 
 ## Ключевые особенности
 
-- **Контекстная зависимость** — Автоматически обрабатывает различия в логике между анализом всей страницы и активным выделением.
-- **Фильтрация узлов** — Специализированные методы для получения только фреймов, секций или текстовых узлов из иерархии.
-- **Агрегация текста** — Группировка текстовых узлов по содержимому для упрощения перевода и анализа.
-- **Массовый экспорт** — Оптимизированное асинхронное создание скриншотов для всех основных элементов в контексте.
+- **Рекурсивное сканирование** — Автоматически индексирует все вложенные элементы внутри предоставленного контекста (страница или выделение).
+- **Поддержка выделения** — Может быть инициализирован для работы как со всей страницей документа, так и только с текущим выделением пользователя.
+- **Агрегация текстов** — Метод `getTexts()` группирует идентичные текстовые строки, возвращая список уникальных значений и связанных с ними ID узлов.
+- **Автоматизированный экспорт** — Упрощает процесс создания скриншотов для основных элементов внутри фрейма.
 
 ## Инициализация
 
-Для инициализации объекта вызовите конструктор `FigmaFrame(page, selection)`.
-
-**Параметры:**
-- `page: UiFigmaNode` — Корневой узел (обычно `figma.currentPage` или `PageNode`) для анализа.
-- `selection: boolean = false` — Если `true`, экземпляр будет обрабатывать только узлы в текущем выделении, а не на всей странице.
+Создайте новый экземпляр, передав начальный узел (обычно страницу) и указав, следует ли фокусироваться на выделении.
 
 ```typescript
 import { FigmaFrame } from '@dxtmisha/figma-code'
 
-// 1. Инициализация для всей страницы
-const pageManager = new FigmaFrame(figma.currentPage)
+// Анализ всей текущей страницы
+const frameAnalyzer = new FigmaFrame(figma.currentPage)
+
+// Анализ только выделенных объектов
+const selectionAnalyzer = new FigmaFrame(figma.currentPage, true)
+```
+
+## Методы
+
+### Состояние и навигация
+
+- `isSelection(): boolean` — Проверяет, является ли текущий контекст выделением.
+- `getMainFrames(): FigmaItem[]` — Извлекает основные фреймы или секции из корня текущего контекста (страницы или выделения).
+
+### Фильтрация и выборка
+
+- `getItemsFrame(): FigmaItem<FrameNode>[]` — Возвращает список всех вложенных узлов, являющихся фреймами.
+- `getItemsSection(): FigmaItem<SectionNode>[]` — Возвращает список всех вложенных узлов, являющихся секциями.
+- `getItemsText(): FigmaItem<TextNode>[]` — Возвращает список всех вложенных текстовых узлов.
+
+### Контент и информация
+
+#### `getItemsInfo`
+
+Асинхронно собирает подробную информацию (имя, ID, скриншот) для всех элементов во фрейме.
+
+**Возвращает:** `Promise<UiFigmaFramesList>` — Промис со списком информации об элементах.
+
+```typescript
+const infoList: UiFigmaFramesList = await frame.getItemsInfo()
+/*
+[
+  { id: '1:10', name: 'Button', image: Uint8Array[...] },
+  { id: '1:25', name: 'Card', image: 'data:image/png;base64...' }
+]
+*/
+```
+
+#### `getMainItemsInfo`
+
+Асинхронно собирает подробную информацию только для основных (верхнеуровневых) элементов.
+
+**Возвращает:** `Promise<UiFigmaFramesList>` — Промис со списком информации об основных элементах.
+
+```typescript
+const mainInfoList: UiFigmaFramesList = await frame.getMainItemsInfo()
+/*
+[
+  { id: '1:10', name: 'Login Screen', image: Uint8Array[...] }
+]
+*/
+```
+
+#### `getTexts`
 
-// 2. Инициализация конкретно для текущего выделения
-const selectionManager = new FigmaFrame(figma.currentPage, true)
+Группирует текстовые узлы по их содержимому, возвращая уникальные строки и список ID соответствующих нод.
+
+**Возвращает:** `UiFigmaItemText[]` — Массив сгруппированных текстовых элементов.
+
+```typescript
+const groupedTexts: UiFigmaItemText[] = frame.getTexts()
+/*
+[
+  { id: ['1:10', '1:15'], text: 'Submit' },
+  { id: ['1:20'], text: 'Cancel' }
+]
+*/
+```
+
+### Анализ стилей
+
+#### `getItemsCss`
+
+Генерирует карту CSS-стилей для всех элементов фрейма.
+
+**Возвращает:** `Promise<UiFigmaFrameStylesCssList>` — Промис с картой стилей, индексированной по ID узла.
+
+```typescript
+const cssStyles: UiFigmaFrameStylesCssList = await frame.getItemsCss()
+/*
+{
+  '1:10': { 'color': '#ff0000', 'font-size': '14px' },
+  '1:12': { 'background': '#ffffff', 'padding': '10px' }
+}
+*/
+```
+
+#### `getItemsStyles`
+
+Извлекает полные данные о стилях (JSON-структуру документа, текст, CSS) для всех элементов.
+
+**Возвращает:** `Promise<UiFigmaFrameStylesList>` — Промис со списком расширенных данных о стилях.
+
+```typescript
+const stylesList: UiFigmaFrameStylesList = await frame.getItemsStyles()
+/*
+[
+  { 
+    id: '1:10', 
+    name: 'Label', 
+    text: 'Username', 
+    styles: { 'color': '#333' },
+    json: { document: {...}, styles: {...} }
+  }
+]
+*/
+```
+
+#### `getMainItemsStyles`
+
+Извлекает полные данные о стилях только для основных элементов, включая стили их дочерних элементов.
+
+**Возвращает:** `Promise<UiFigmaFrameStylesList>` — Промис со списком расширенных данных о стилях основных элементов.
+
+```typescript
+const mainStylesList: UiFigmaFrameStylesList = await frame.getMainItemsStyles()
+/*
+[
+  { 
+    id: '1:10', 
+    name: 'Login Form', 
+    childrenStyles: {
+       '1:11': { 'color': '#000' },
+       '1:12': { 'margin-top': '20px' }
+    }
+  }
+]
+*/
 ```
 
-## Контекст и анализ
+### Экспорт и действия
 
-- `isSelection(): boolean` — Проверяет, ограничен ли контекст текущим выделением. Пример: `frameManager.isSelection()`
-- `getMainFrames(): FigmaItem[]` — Возвращает основные фреймы/секции от корня. Пример: `const roots = frameManager.getMainFrames()`
+- `screenshot(): Promise<Uint8Array[]>` — Создает скриншоты в формате JPG для всех основных элементов.
 
-## Фильтрация иерархии
+## Типы данных
 
-- `getItemsFrame(): FigmaItem<FrameNode>[]` — Фильтрует иерархию по узлам FRAME. Пример: `const frames = frameManager.getItemsFrame()`
-- `getItemsSection(): FigmaItem<SectionNode>[]` — Фильтрует иерархию по узлам SECTION. Пример: `const sections = frameManager.getItemsSection()`
-- `getItemsText(): FigmaItem<TextNode>[]` — Фильтрует иерархию по узлам TEXT. Пример: `const textNodes = frameManager.getItemsText()`
+#### `UiFigmaNode`
+Базовый тип для узлов Figma. Представляет собой объединение (`SceneNode | DocumentNode | PageNode | FrameNode` и др.), поддерживающих вложенность и стандартные свойства Figma API.
 
-## Данные и захват (Capture)
+#### `UiFigmaItemText`
+Результат группировки текстовых слоев по их содержимому.
+- `id: string[]` — Массив уникальных идентификаторов узлов, имеющих одинаковый текст.
+- `text: string` — Само текстовое значение.
 
-- `getTexts(): UiFigmaItemText[]` — Агрегирует текстовые узлы, группируя их по контенту. Пример: `const groups = frameManager.getTexts()`
-- `screenshot(): Promise<Uint8Array[]>` — Асинхронно создает JPG-скриншоты элементов. Пример: `const images = await frameManager.screenshot()`
+#### `UiFigmaMessageTexts`
+Структура данных для передачи результатов анализа текстов.
+- `frame: FigmaFrame` — Экземпляр класса анализатора.
+- `texts: UiFigmaItemText[]` — Список найденных и сгруппированных текстов.
+- `screenshot: Uint8Array[]` — Массив скриншотов основных элементов.
 
-## Типы (Types)
+#### `UiFigmaFramesItem`
+Упрощенная информация об элементе для отображения в интерфейсе.
+- `name: string` — Название элемента в Figma.
+- `id: string` — Уникальный идентификатор узла.
+- `image?: Uint8Array | string` — Скриншот элемента (бинарные данные или base64).
 
-### `UiFigmaNode`
+#### `UiFigmaFrameStylesItem`
+Расширенная информация об элементе, включая его стили. Наследует все поля `UiFigmaFramesItem`.
+- `json?: UiFigmaFrameStylesData` — Структура данных узла и стилей в формате JSON.
+- `text?: string` — Текстовое содержимое (если узел является текстовым).
+- `styles?: Record<string, string>` — Объект с CSS-свойствами самого элемента.
+- `childrenStyles?: Record<string, Record<string, string>>` — Карта CSS-стилей для всех дочерних элементов, индексированная по их ID.
 
-Тип-объединение (union), представляющий любой релевантный узел Figma, который может содержать дочерние элементы или обрабатываться менеджером.
-- Включает: `DocumentNode`, `PageNode`, `FrameNode`, `SectionNode`, `TextNode` и другие варианты `SceneNode`.
+#### `UiFigmaFrameStylesData`
+- `document: UiFigmaFrameStylesJson` — Дерево узлов в компактном формате.
+- `styles: Record<string, any>` — Словарь определений стилей документа.
 
-### `UiFigmaItemText`
+#### `UiFigmaFrameStylesList`
+Массив объектов типа `UiFigmaFrameStylesItem`.
 
-Структура объекта, используемая для группировки текстового содержимого по всему документу.
-- `id: string[]` — список уникальных ID узлов Figma, в которых найден этот текст.
-- `text: string` — само текстовое содержимое (очищенное от лишних пробелов).
+#### `UiFigmaFrameStylesCssList`
+Объект (`Record<string, Record<string, string>>`), где ключом является ID узла, а значением — его набор CSS-стилей.