@dxtmisha/figma-code 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-05-10
+
+### Added
+- **Recursive AI Prompt Generator**: Implemented a recursive AI prompt generator for advanced automation and design-to-code workflows.
+- **Figma Styles Synchronization**: Added functionality to synchronize Figma styles with the project codebase.
+- **Zip Export**: Integrated Zip archiving for exporting styles and assets directly from Figma.
+- **Figma Frame & Item Management**: Implemented `FigmaFrame` and `FigmaItem` classes for comprehensive management of Figma elements.
+- **Figma Storage**: Added `FigmaStorage`, `FigmaStorageData`, and `FigmaClientStorage` for robust data persistence within the Figma environment.
+- **Figma Plugin Messaging**: Implemented `FigmaPluginMessenger` for standardized, type-safe communication between the plugin and Figma.
+- **Selection Support**: Added `FigmaFramesSelected` and `useFigmaUiSelected` for efficient management of selected Figma elements.
+- **DesignWikiStorm Support**: Added support for events and slots in `DesignWikiStorm`.
+- **Unit Testing**: Added a comprehensive unit testing suite for core logic and classes.
+- **AI-Assisted Documentation**: Integrated AI-assisted documentation metadata to improve developer experience.
+
+### Changed / Improved
+- **Checkbox Design Refactor**: Refactored Checkbox design integration to align with the new design system.
+- **Selection Logic**: Consolidated and standardized frame selection logic and messengers across the package.
+- **Storage Mechanics**: Refined data storage mechanics and callback handling for better reliability.
+- **Internal Architecture**: Improved class hierarchy and modularity for Figma-related logic.
+
+### Fixed
+- **Selection Issues**: Fixed various bugs related to frame selection and event propagation.
+- **Type Definitions**: Addressed TypeScript type definition errors and improved overall type safety.
+- **Event Handling**: Fixed issues with event and slot support in `DesignWikiStorm`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dxtmisha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @dxtmisha/figma-code
+
+[![npm version](https://badge.fury.io/js/@dxtmisha%2Ffigma-code.svg)](https://www.npmjs.com/package/@dxtmisha/figma-code)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`@dxtmisha/figma-code` is a structured TypeScript abstraction layer for Figma Plugin backend development. It provides high-level tools for node manipulation, persistent storage, and bidirectional communication between the plugin's logic and its UI.
+
+## Why this library?
+
+Developing Figma plugins often involves repetitive tasks like traversing complex node trees, managing character data in text nodes, and handling persistent state through `clientStorage` or `pluginData`.
+
+The native Figma API is powerful but low-level. `figma-code` wraps these APIs into intuitive, type-safe classes and functions that handle common patterns automatically—such as caching storage values, traversing parent-child relationships, and managing message exchange between the sandbox and the iframe.
+
+## What does it do?
+
+For **node manipulation (DOM-like API)** — the `FigmaItem` class and its specialized derivatives (like `FigmaFrame`) provide a convenient way to interact with Figma nodes. They offer methods for type checking (`isText`, `isFrame`), accessing parent/page context, and extracting CSS or JSON representations of nodes.
+
+For **persistent storage** — robust wrappers for Figma's storage systems. `FigmaStorage` handles `setPluginData` (node-level storage) with built-in caching and aging logic, while `FigmaClientStorage` provides a similar interface for `figma.clientStorage` (plugin-level storage).
+
+For **bidirectional messaging** — `FigmaPluginMessenger` simplifies communication between the plugin backend and the UI. It provides a standardized way to send messages (`post`) and handle incoming ones, ensuring type safety across the boundary.
+
+For **selection and navigation** — utilities like `FigmaFramesSelected` and `FigmaTopLevelFrames` allow developers to easily track and manipulate user selections or find specific elements within the document without manual recursion.
+
+For **content processing** — specialized modules like `FigmaAiText` facilitate text analysis and manipulation, which is essential for building AI-driven translation or design-to-code tools.
+
+## Installation
+
+```bash
+npm install @dxtmisha/figma-code
+```
+
+## Quick Start
+
+```typescript
+import { FigmaItem, FigmaStorage, FigmaPluginMessenger } from '@dxtmisha/figma-code'
+
+// 1. Working with nodes
+const selectedNode = figma.currentPage.selection[0]
+if (selectedNode) {
+  const item = new FigmaItem(selectedNode)
+  console.log('Node Name:', item.getName())
+  if (item.isText()) {
+    console.log('Text Content:', item.getText())
+  }
+}
+
+// 2. Persistent storage with caching
+const userSettings = FigmaStorage.getInstance('settings')
+const theme = userSettings.get({ theme: 'light' })
+userSettings.set({ ...theme, theme: 'dark' })
+
+// 3. Messaging to UI
+const messenger = FigmaPluginMessenger.getInstance()
+messenger.post('UPDATE_STATUS', { status: 'ready' })
+```
+
+## Principles
+
+- **Structured Abstraction** — moves beyond raw Figma nodes to a more object-oriented approach that is easier to reason about.
+- **Type Safety** — built from the ground up with TypeScript, ensuring that your plugin logic is robust and predictable.
+- **Performance Optimized** — includes caching mechanisms for data-heavy operations like reading storage or processing complex node trees.
+- **Developer Experience** — focuses on reducing boilerplate code for common plugin tasks, letting you focus on the core features of your plugin.
+
+## Documentation
+
+Full API reference and guides:
+
+**[📖 https://dxtmisha.github.io/dxt-ui/?path=/docs/dxtmisha-en-figma-code-about-library--docs](https://dxtmisha.github.io/dxt-ui/?path=/docs/dxtmisha-en-figma-code-about-library--docs)**
+
+## License
+
+[MIT](LICENSE)
+

package/ai-description.txt

@@ -0,0 +1 @@
+This library is a structured TypeScript abstraction layer for Figma Plugin backend development, specifically designed to automate node manipulation, data persistence, and bidirectional messaging. Its core purpose is to provide high-level wrappers around the native Figma API for node traversal (FigmaItem), frame-specific metadata extraction (FigmaFrame), and persistent state management using both figma.clientStorage and node-level PluginData with built-in caching and aging logic. AI coding assistants should study this library when implementing features for automated CSS/style extraction, programmatic selection management, screenshot generation, or text content processing for translation and key-value mapping. The integration context bridges the Figma backend to the UI via FigmaPluginMessenger and includes specialized modules for AI-driven text analysis, relying on a shared type system for Figma nodes and message payloads.

package/ai-doc.ru.txt

@@ -0,0 +1,12 @@
+ПАКЕТ ЛОГИКИ ПЛАГИНА FIGMA (BACKEND):
+Данная библиотека предназначена для работы на стороне основного процесса плагина (Code side). Она обеспечивает прямой доступ к Figma API и реализует логику обработки запросов от UI.
+
+1. ПРЕДНАЗНАЧЕНИЕ: Реализация фоновой логики плагина. Отвечает за манипуляцию объектами Figma (фреймы, текст, стили), управление хранилищем (`FigmaStorage`) и отправку данных обратно в UI через `FigmaPluginMessenger`.
+2. ВЗАИМОДЕЙСТВИЕ: Работает в связке с пакетом `@dxtmisha/figma`. Получает сообщения от UI, выполняет операции через Figma API и отправляет результат обратно.
+3. КЛЮЧЕВЫЕ КЛАССЫ:
+   - `FigmaPluginMessenger`: Синглтон для управления сообщениями на стороне Backend.
+   - `FigmaFrame`, `FigmaItem`: Обертки для удобной работы с узлами (nodes) Figma.
+   - `setup...` функции: Слушатели, которые автоматически обрабатывают стандартные запросы от UI (например, `setupFrameSelection`).
+
+Используй этот пакет только в коде, который выполняется в основном процессе плагина Figma (main thread).
+

package/ai-doc.txt

@@ -0,0 +1,12 @@
+FIGMA PLUGIN LOGIC PACKAGE (BACKEND):
+This library is intended for use on the main process side of a Figma plugin (Code side). It provides direct access to the Figma API and implements the logic for handling requests from the UI.
+
+1. PURPOSE: Implementing the background logic of the plugin. It is responsible for manipulating Figma objects (frames, text, styles), managing storage (`FigmaStorage`), and sending data back to the UI via `FigmaPluginMessenger`.
+2. INTERACTION: Works in conjunction with the `@dxtmisha/figma` package. It receives messages from the UI, performs operations via the Figma API, and sends results back.
+3. KEY CLASSES:
+   - `FigmaPluginMessenger`: A singleton for managing messages on the Backend side.
+   - `FigmaFrame`, `FigmaItem`: Wrappers for convenient handling of Figma nodes.
+   - `setup...` functions: Listeners that automatically process standard UI requests (e.g., `setupFrameSelection`).
+
+Use this package only in code that executes in the main process of the Figma plugin (main thread).
+

package/ai-types.txt

@@ -0,0 +1,288 @@
+1) All these methods are in the @dxtmisha/figma-code library.
+2) Everything that is exported can be used.
+3) Use what is in this library if it exists; do not use other libraries if there is an analogue here. Do not create new ones if an analogue already exists here.
+
+The following is the content of "exports" from package.json:
+{
+  ".": {
+    "import": "./dist/library.js",
+    "types": "./dist/library.d.ts"
+  },
+  "./style.css": "./dist/style.css",
+  "./types/*": "./dist/*",
+  "./types/**/*.d.ts": "./dist/**/*.d.ts"
+}
+
+// File: classes/FigmaAiText.d.ts
+export declare class FigmaAiText {
+    constructor(ai: AiAbstract, data: UiFigmaMessageTexts);
+    make(): Promise<this>;
+}
+
+// File: classes/FigmaClientStorage.d.ts
+/** Figma client storage wrapper. */
+export declare class FigmaClientStorage<T> {
+    /**
+     * Get class instance.
+     * @param name value name
+     * @returns current instance
+     */
+    static getInstance<T>(name: string): FigmaClientStorage<T>;
+    constructor(name: string, cache?: number | undefined);
+    /**
+     * Get data from storage.
+     * @param defaultValue default value
+     */
+    get(defaultValue?: T | (() => T | Promise<T>)): Promise<T | undefined>;
+    /**
+     * Set data in storage.
+     * @param value new values
+     * @returns current value
+     */
+    set(value?: T | (() => T | Promise<T>)): Promise<T | undefined>;
+    /** Remove data from storage. */
+    remove(): Promise<this>;
+}
+
+// File: classes/FigmaFrame.d.ts
+/** Figma frames and elements manager. */
+export declare class FigmaFrame {
+    /**
+     * @param page Figma page or node
+     * @param selection use selection or entire page
+     */
+    constructor(page: UiFigmaNode, selection?: boolean);
+    /** Check if context is a selection. */
+    isSelection(): this is {
+        page: PageNode;
+    };
+    /** Get all frame items. */
+    getItemsFrame(): FigmaItem<FrameNode>[];
+    /** Get all section items. */
+    getItemsSection(): FigmaItem<SectionNode>[];
+    /** Get all text items. */
+    getItemsText(): FigmaItem<TextNode>[];
+    /** Get frames info (names, IDs, screenshots). */
+    getItemsInfo(): Promise<UiFigmaFramesList>;
+    /** Get CSS styles for all items. */
+    getItemsCss(): Promise<UiFigmaFrameStylesCssList>;
+    /** Get frames with styles. */
+    getItemsStyles(): Promise<UiFigmaFrameStylesList>;
+    /** Get main frames from root. */
+    getMainFrames(): FigmaItem[];
+    /** Get main items info. */
+    getMainItemsInfo(): Promise<UiFigmaFramesList>;
+    /** Get main frames with styles. */
+    getMainItemsStyles(): Promise<UiFigmaFrameStylesList>;
+    /** Get text nodes grouped by content. */
+    getTexts(): UiFigmaItemText[];
+    /** Screenshot main items. */
+    screenshot(): Promise<Uint8Array<ArrayBufferLike>[]>;
+}
+
+// File: classes/FigmaFramesSelected.d.ts
+/** Manages selected frames in plugin. */
+export declare class FigmaFramesSelected {
+    /**
+     * Check if frame ID is selected.
+     * @param id Frame ID
+     */
+    static has(id: string): boolean;
+    /** Get current selected frame IDs. */
+    static get(): string[];
+    /** Add frame ID to selection. */
+    static add(id: string): void;
+    /** Remove frame ID from selection. */
+    static remove(id: string): void;
+    /**
+     * Toggle frame selection state.
+     * @param id Frame ID
+     * @param selected selection state
+     */
+    static toggle(id: string, selected: boolean): void;
+    /** Sync selection state via messenger. */
+    static send(): void;
+}
+
+// File: classes/FigmaItem.d.ts
+/** Figma node wrapper. */
+export declare class FigmaItem<T extends UiFigmaNode = UiFigmaNode> {
+    constructor(item: T);
+    isDocument(): this is {
+        item: DocumentNode;
+    };
+    isFrame(): this is {
+        item: FrameNode;
+    };
+    isSection(): this is {
+        item: SectionNode;
+    };
+    isText(): this is {
+        item: TextNode;
+    };
+    isTextNoValue(): this is {
+        item: TextNode;
+    };
+    inCurrentPage(): boolean;
+    /** Get Figma node. */
+    get(): T;
+    getType(): "SLICE" | "FRAME" | "GROUP" | "COMPONENT_SET" | "COMPONENT" | "INSTANCE" | "BOOLEAN_OPERATION" | "VECTOR" | "STAR" | "LINE" | "ELLIPSE" | "POLYGON" | "RECTANGLE" | "TEXT" | "TEXT_PATH" | "TRANSFORM_GROUP" | "STICKY" | "CONNECTOR" | "SHAPE_WITH_TEXT" | "CODE_BLOCK" | "STAMP" | "WIDGET" | "EMBED" | "LINK_UNFURL" | "MEDIA" | "SECTION" | "HIGHLIGHT" | "WASHI_TAPE" | "TABLE" | "SLIDE" | "SLIDE_ROW" | "SLIDE_GRID" | "SLOT" | "INTERACTIVE_SLIDE_ELEMENT" | "DOCUMENT" | "PAGE" | undefined;
+    getParent(): (BaseNode & ChildrenMixin) | undefined;
+    getParentItem(): FigmaItem | undefined;
+    getParentPage(): PageNode | undefined;
+    getParentPageItem(): FigmaItem | undefined;
+    getChildren(): UiFigmaNode[];
+    getChildrenItems(): FigmaItem[];
+    getId(): string;
+    getName(): string;
+    getText(): string;
+    getCss(): Promise<Record<string, string>>;
+    getInfo(): Promise<UiFigmaFramesItem>;
+    getStyles(): Promise<UiFigmaFrameStylesItem>;
+    exportJpg(): Promise<Uint8Array<ArrayBufferLike> | "">;
+    exportJson(): Promise<Uint8Array<ArrayBufferLike> | "">;
+    exportJsonCompact(): Promise<UiFigmaFrameStylesData | undefined>;
+    /** Select node. */
+    toSelection(): void;
+    /** Move to page and select node. */
+    toPageAndSelection(): Promise<void>;
+}
+
+// File: classes/FigmaPluginMessenger.d.ts
+/** Figma plugin backend messenger. */
+export declare class FigmaPluginMessenger extends FigmaPostAbstract {
+    static getInstance(): FigmaPluginMessenger;
+    /** Send message to UI. */
+    post<Message>(type: string, message?: Message): void;
+}
+
+// File: classes/FigmaStorage.d.ts
+/** Figma PluginData storage wrapper. */
+export declare class FigmaStorage<T> {
+    /**
+     * Get instance.
+     * @param name value name
+     * @param item data container
+     */
+    static getInstance<T>(name: string, item?: UiFigmaNode): FigmaStorage<T>;
+    /**
+     * Get instance by ID.
+     * @param id object id
+     */
+    static getInstanceById<T>(name: string, id?: string): Promise<FigmaStorage<T>>;
+    constructor(name: string, item?: PluginDataMixin, cache?: number | undefined);
+    get(defaultValue?: T | (() => T)): T | undefined;
+    set(value?: T | (() => T)): T | undefined;
+    remove(): this;
+}
+
+// File: classes/FigmaStorageData.d.ts
+export type FigmaStorageDataValue<T> = {
+    value: T;
+    age: number;
+};
+/** Figma storage data manager. */
+export declare class FigmaStorageData<T> {
+    constructor(name: string, cache?: number | undefined);
+    isNull(): boolean;
+    isCache(): boolean;
+    isValue(): boolean;
+    get(): T | undefined;
+    getAge(): number | undefined;
+    getName(): string;
+    getCache(): number | undefined;
+    set(value?: T, age?: number): this;
+    setByObject(value?: FigmaStorageDataValue<T>): this;
+    setValue(value?: T): this;
+    setAge(age?: number): this;
+    update(value?: T): this;
+    remove(): this;
+    toValue(): FigmaStorageDataValue<T>;
+}
+
+// File: classes/FigmaTopLevelFrames.d.ts
+/** Manages top-level frames list. */
+export declare class FigmaTopLevelFrames {
+    /** Get cached list of top-level frames. */
+    static get(): Promise<UiFigmaFramesList>;
+    /** Listen for frame requests and send data. */
+    static send(): void;
+}
+
+// File: config.d.ts
+export declare const FIGMA_IMAGE_TYPE = "image/jpeg";
+export declare const FIGMA_MESSAGE_TEXTS = "texts";
+
+// File: functions/getFigmaFrameById.d.ts
+/** Get FigmaFrame by ID. */
+export declare function getFigmaFrameById(id: string): Promise<FigmaFrame | undefined>;
+
+// File: functions/getFigmaItemById.d.ts
+/** Get Figma item wrapper by ID. */
+export declare function getFigmaItemById<T extends UiFigmaNode = UiFigmaNode>(id: string): Promise<FigmaItem<T> | undefined>;
+
+// File: functions/getFigmaItemByIdOrRoot.d.ts
+/** Get Figma node by ID or figma.root. */
+export declare function getFigmaItemByIdOrRoot<T extends UiFigmaNode = UiFigmaNode>(id?: string): Promise<T>;
+
+// File: functions/makeFigmaFrameSelection.d.ts
+/** Sync Figma selection changes to UI. */
+export declare const makeFigmaFrameSelection: () => void;
+
+// File: functions/makeFigmaTexts.d.ts
+/** Sync Figma text selection to UI. */
+export declare const makeFigmaTexts: () => void;
+
+// File: functions/setupClientStorage.d.ts
+/** Init client storage listeners. */
+export declare function setupClientStorage(): void;
+
+// File: functions/setupFrameSelection.d.ts
+/** Init bidirectional frame selection management. */
+export declare function setupFrameSelection(): void;
+
+// File: functions/setupFrameStyles.d.ts
+/** Listen for style update messages. */
+export declare function setupFrameStyles(): void;
+
+// File: functions/setupStorage.d.ts
+/** Init storage listeners. */
+export declare function setupStorage(): void;
+
+// File: functions/toFrameSelection.d.ts
+/** Focus and select item by ID. */
+export declare function toFrameSelection(id?: string): Promise<void>;
+
+// File: library.d.ts
+export * from './classes/FigmaClientStorage';
+export * from './classes/FigmaFrame';
+export * from './classes/FigmaFramesSelected';
+export * from './classes/FigmaItem';
+export * from './classes/FigmaPluginMessenger';
+export * from './classes/FigmaStorage';
+export * from './classes/FigmaStorageData';
+export * from './classes/FigmaTopLevelFrames';
+export * from './functions/getFigmaFrameById';
+export * from './functions/getFigmaItemById';
+export * from './functions/getFigmaItemByIdOrRoot';
+export * from './functions/makeFigmaFrameSelection';
+export * from './functions/makeFigmaTexts';
+export * from './functions/setupClientStorage';
+export * from './functions/setupFrameSelection';
+export * from './functions/setupFrameStyles';
+export * from './functions/setupStorage';
+export * from './functions/toFrameSelection';
+export * from './types/figmaTypes';
+
+// File: types/figmaTypes.d.ts
+export type UiFigmaNode = ChildrenMixin | SceneNode | DefaultShapeMixin | DocumentNode | PageNode | FrameNode | SectionNode | TextNode | BaseNode;
+export type UiFigmaItemText = {
+    id: string[];
+    text: string;
+};
+export type UiFigmaExportFormat = 'PNG' | 'JPG' | 'SVG' | 'PDF' | 'JSON_REST_V1';
+export type UiFigmaMessageTexts = {
+    frame: FigmaFrame;
+    texts: UiFigmaItemText[];
+    screenshot: Uint8Array[];
+};

package/dist/classes/FigmaAiText.d.ts

@@ -0,0 +1,10 @@
+import { AiAbstract } from '@dxtmisha/scripts/ai';
+import { UiFigmaMessageTexts } from '../types/figmaTypes';
+export declare class FigmaAiText {
+    protected readonly ai: AiAbstract;
+    protected readonly data: UiFigmaMessageTexts;
+    constructor(ai: AiAbstract, data: UiFigmaMessageTexts);
+    make(): Promise<this>;
+    protected makeImage(): this;
+    protected initTexts(): string;
+}

package/dist/classes/FigmaClientStorage.d.ts

@@ -0,0 +1,61 @@
+import { FigmaStorageData, FigmaStorageDataValue } from './FigmaStorageData';
+/**
+ * Class for working with Figma client storage (clientStorage).
+ *
+ * Класс для работы с клиентским хранилищем Figma (clientStorage).
+ */
+export declare class FigmaClientStorage<T> {
+    protected readonly name: string;
+    protected readonly cache?: number | undefined;
+    /**
+     * Getting an instance of the class for working with Figma client storage (clientStorage).
+     *
+     * Получение экземпляра класса для работы с клиентским хранилищем Figma (clientStorage).
+     * @param name value name/ название значения
+     * @returns current instance/ текущий экземпляр
+     */
+    static getInstance<T>(name: string): FigmaClientStorage<T>;
+    protected data: FigmaStorageData<T>;
+    /**
+     * Constructor
+     * @param name value name/ название значения
+     * @param cache cache time/ время кэширования
+     */
+    constructor(name: string, cache?: number | undefined);
+    /**
+     * Getting data from storage.
+     *
+     * Получение данных из хранилища.
+     * @param defaultValue default value/ значение по умолчанию
+     */
+    get(defaultValue?: T | (() => T | Promise<T>)): Promise<T | undefined>;
+    /**
+     * Changing data in storage.
+     *
+     * Изменение данных в хранилище.
+     * @param value new values/ новые значения
+     * @returns current value/ текущее значение
+     */
+    set(value?: T | (() => T | Promise<T>)): Promise<T | undefined>;
+    /**
+     * Removing data from storage.
+     *
+     * Удаление данных из хранилища.
+     * @returns current instance/ текущий экземпляр
+     */
+    remove(): Promise<this>;
+    /**
+     * Getting data from storage.
+     *
+     * Получение данных из хранилища.
+     * @returns data from storage/ данные из хранилища
+     */
+    protected getValue(): Promise<FigmaStorageDataValue<T> | undefined>;
+    /**
+     * Making an instance from storage data.
+     *
+     * Создание экземпляра из данных хранилища.
+     * @returns current instance/ текущий экземпляр
+     */
+    protected make(): Promise<this>;
+}