@dxtmisha/wiki 0.25.1 → 0.39.2

package/src/media/functional/scripts/classes/DesignFlags/DesignFlags.vi.mdx

@@ -0,0 +1,59 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/DesignFlags - Trình tạo Sprite cờ'/>
+
+# Lớp DesignFlags
+
+Lớp `DesignFlags` cung cấp một giải pháp tự động để tạo các sprite hình ảnh được tối ưu hóa từ một bộ sưu tập các biểu tượng cờ SVG. Nó xử lý việc hiển thị dựa trên canvas, tính toán bố cục lưới và tạo các tệp ánh xạ CSS để hiển thị biểu tượng hiệu quả bằng cách sử dụng định vị nền (background positioning).
+
+## Các tính năng chính
+
+- **Tự động đóng gói Sprite** — Kết hợp nhiều tệp SVG riêng lẻ thành một sprite `.webp` duy nhất được tối ưu hóa.
+- **Tạo CSS động** — Tự động tạo các lớp tiện ích với các giá trị `background-position` chính xác cho mỗi lá cờ.
+- **Bố cục lưới có thể cấu hình** — Cho phép tùy chỉnh kích thước cờ và số lượng cột trong hình ảnh kết quả.
+- **Hiển thị bằng Canvas** — Sử dụng xử lý hình ảnh hiệu suất cao để chuyển đổi và thu phóng mượt mà.
+- **Duy trì tỷ lệ khung hình** — Đảm bảo cờ được căn giữa trong các ô lưới của chúng trong khi vẫn duy trì tỷ lệ thiết kế ban đầu.
+
+## Khởi tạo
+
+Để khởi tạo trình tạo, hãy chỉ định thư mục nguồn và tỷ lệ đầu ra mong muốn.
+
+**Tham số:**
+- `dir: string` — Đường dẫn thư mục nơi đặt các biểu tượng cờ `.svg` nguồn.
+- `width: number` — Chiều rộng mục tiêu của một lá cờ trong sprite được tạo (mặc định: 96).
+- `height: number` — Chiều cao mục tiêu của một lá cờ trong sprite được tạo (mặc định: 72).
+- `columns: number` — Số lượng cột biểu tượng cần sắp xếp trong lưới sprite (mặc định: 12).
+
+```typescript
+import { DesignFlags } from '@dxtmisha/scripts'
+
+const generator = new DesignFlags('assets/flags', 64, 48)
+generator.make()
+```
+
+## Các phương thức
+
+### Điều khiển
+
+- `make(): Promise<void>` — Điều phối toàn bộ quy trình: đọc tệp, vẽ lên canvas, lưu hình ảnh và ghi tệp CSS.
+
+### Thông tin
+
+- `getLines(): number` — Tính toán tổng số hàng cần thiết trong lưới sprite dựa trên số lượng tệp và giới hạn cột.
+
+## Các thao tác (Operations)
+
+### Quy trình tạo
+
+Khi `make()` được thực thi, lớp sẽ thực hiện các bước sau:
+1. **Khám phá**: Quét thư mục nguồn để tìm các tệp `.svg` và khởi tạo kích thước lưới.
+2. **Tính toán bố cục**: Xác định khoảng cách lát gạch (tiling) và lề căn giữa cho các kích thước cờ cụ thể.
+3. **Vẽ Canvas**: Tải từng hình ảnh theo chu kỳ và vẽ nó lên canvas sprite tại tọa độ lưới đã tính toán.
+4. **Thu thập dữ liệu**: Ghi lại tên và tọa độ của mỗi lá cờ để xây dựng dữ liệu ánh xạ.
+5. **Xuất tài nguyên**: 
+    - Lưu nội dung canvas dưới dạng hình ảnh `webp` trong thư mục `assets`.
+    - Tạo tệp `flags.css` với các định nghĩa biến gốc và các lớp sửa đổi `--[name]` riêng lẻ.
+
+### Triển khai kiểu dáng (Style Implementation)
+
+CSS được tạo sử dụng một lớp tập trung `.ui-sys-flags` lưu trữ các biến kích thước và liên kết hình ảnh nền. Các bộ sửa đổi riêng lẻ (ví dụ: `.ui-sys-flags--vn`) sau đó cập nhật `background-position` để tách biệt các biểu tượng cụ thể, giảm thiểu các lệnh vẽ lại của trình duyệt và các yêu cầu HTTP.

package/src/media/functional/scripts/classes/DesignReplace/DesignReplace.en.mdx

@@ -0,0 +1,76 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/DesignReplace - Template Transformation Engine'/>
+
+# DesignReplace Class
+
+The `DesignReplace` class is the core engine for transforming raw file templates into project-ready source code. It uses a specialized marking system to identify sections of text that should be dynamically replaced with component names, property definitions, types, or styling logic derived from the component's `DesignStructure`.
+
+## Key Features
+
+- **Smart Label Resolution** — Identifies and replaces text blocks bounded by specific comments (e.g., `// :type` or `<!-- :props -->`).
+- **Context-Aware Naming** — Automatically transforms generic placeholders like `[project]`, `[design]`, and `[component]` based on configuration.
+- **Type Injection** — Generates complex TypeScript type unions and interfaces directly from property metadata.
+- **Default Value Mapping** — Resolves and injects default values for properties into object literals or constructor arguments.
+- **Conditional Class Generation** — Produces optimized Vue/TS class binding objects and CSS selector mappings.
+- **Path Normalization** — Automatically resolves relative import paths based on the target file's location in the project tree.
+
+## Initialization
+
+To initialize a replacement engine, pass the component's data structure, the target mark identifier, and the template string.
+
+**Parameters:**
+- `structure: DesignStructure` — The source of truth for component metadata and structural rules.
+- `mark: string` — The primary label used in templates to identify components (e.g., `'button'`).
+- `sample: string` — The text content of the template to be modified.
+
+```typescript
+import { DesignReplace } from '@dxtmisha/scripts'
+
+const engine = new DesignReplace(structure, 'button', templateContent)
+engine.replaceName().replaceType()
+const output = engine.get()
+```
+
+## Methods
+
+### Control
+
+- `get(): string` — Returns the final version of the template after all transformations.
+- `getNameFile(name: string): string` — Processes a filename or string to replace project-level placeholders.
+- `replaceName(): this` — Replaces the primary component name marks throughout the template.
+- `replacePath(): this` — Fixes relative paths (`../../../`) to point to the correct project root location.
+- `replaceMark(name: string, data: string[], end = ''): this` — Performs block replacement for a specific label by injecting an array of strings.
+- `replaceOnce(name?: string, removeReplacement?: boolean | Function): this` — Handles single-use replacement markers (`.once`).
+
+### Property & Type Automation
+
+- `replaceType(constructor?: string): this` — Generates and injects TypeScript types for all component properties.
+- `replaceDefault(): this` — Injects default values for properties into the template.
+- `replaceProps(): this` — Generates Vue-style property definition objects.
+- `replacePropsValues(): this` — Creates arrays of allowed values for properties (enums/unions).
+
+### Styling & Classes
+
+- `replaceClasses(template?: Function, end = ''): this` — Generates a list of available CSS classes based on the structure.
+- `replaceClassesValues(): this` — Produces dynamic class binding logic for logic implementation files.
+- `replaceStylesValues(): this` — Maps component properties to CSS custom variables (CSS Variables).
+- `replaceConstructorClasses(): this` — Specialized class generator for component constructors.
+
+## Operations
+
+### The Marking System
+
+The engine scans for specific comment patterns to identify where to inject code. It supports multiple comment styles:
+
+1. **Inline Logic**: `// :label data` or `/* :label */ content /* :label.end */`
+2. **Template Comments**: `<!-- :label --> content <!-- :label.end -->`
+3. **Property Specificity**: `:label.propertyName.none` (used to exclude specific properties from a block).
+
+### Transformation Flow
+
+When a replacement method like `replaceType()` is called, the class:
+1. **Scans**: Locates the start and end markers for the `type` label.
+2. **Consults Structure**: Iterates over the properties in the provided `DesignStructure`.
+3. **Resolves Logic**: Determines the correct TypeScript syntax for each property based on its value type (boolean, string, or union).
+4. **Injects**: Replaces the content between the markers with the new generated code, maintaining original indentation.

package/src/media/functional/scripts/classes/DesignReplace/DesignReplace.ru.mdx

@@ -0,0 +1,76 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/DesignReplace - Движок трансформации шаблонов'/>
+
+# Класс DesignReplace
+
+Класс `DesignReplace` — это основное ядро для преобразования необработанных шаблонов файлов в готовый к использованию исходный код проекта. Он использует специализированную систему меток для идентификации участков текста, которые должны быть динамически заменены именами компонентов, определениями свойств, типами или логикой стилизации, полученными из `DesignStructure` компонента.
+
+## Ключевые особенности
+
+- **Интеллектуальное разрешение меток** — идентифицирует и заменяет блоки текста, ограниченные специфическими комментариями (например, `// :type` или `<!-- :props -->`).
+- **Контекстное именование** — автоматически преобразует универсальные плейсхолдеры, такие как `[project]`, `[design]` и `[component]`, на основе конфигурации.
+- **Внедрение типов** — генерирует сложные объединения типов TypeScript и интерфейсы непосредственно из метаданных свойств.
+- **Маппинг значений по умолчанию** — разрешает и внедряет значения по умолчанию для свойств в объектные литералы или аргументы конструктора.
+- **Условная генерация классов** — создает оптимизированные объекты привязки классов Vue/TS и маппинги селекторов CSS.
+- **Нормализация путей** — автоматически разрешает относительные пути импорта в зависимости от расположения целевого файла в дереве проекта.
+
+## Инициализация
+
+Для инициализации движка замены передайте структуру данных компонента, идентификатор целевой метки и строку шаблона.
+
+**Параметры:**
+- `structure: DesignStructure` — источник истины для метаданных компонента и структурных правил.
+- `mark: string` — основная метка, используемая в шаблонах для идентификации компонентов (например, `'button'`).
+- `sample: string` — текстовое содержимое шаблона для модификации.
+
+```typescript
+import { DesignReplace } from '@dxtmisha/scripts'
+
+const engine = new DesignReplace(structure, 'button', templateContent)
+engine.replaceName().replaceType()
+const output = engine.get()
+```
+
+## Методы
+
+### Управление
+
+- `get(): string` — возвращает финальную версию шаблона после всех преобразований.
+- `getNameFile(name: string): string` — обрабатывает имя файла или строку для замены плейсхолдеров уровня проекта.
+- `replaceName(): this` — заменяет основные метки имени компонента во всем шаблоне.
+- `replacePath(): this` — исправляет относительные пути (`../../../`), чтобы они указывали на правильное корневое расположение проекта.
+- `replaceMark(name: string, data: string[], end = ''): this` — выполняет блочную замену для конкретной метки, внедряя массив строк.
+- `replaceOnce(name?: string, removeReplacement?: boolean | Function): this` — обрабатывает одноразовые маркеры замены (`.once`).
+
+### Автоматизация свойств и типов
+
+- `replaceType(constructor?: string): this` — генерирует и внедряет типы TypeScript для всех свойств компонента.
+- `replaceDefault(): this` — внедряет значения по умолчанию для свойств в шаблон.
+- `replaceProps(): this` — генерирует объекты определения свойств в стиле Vue.
+- `replacePropsValues(): this` — создает массивы допустимых значений для свойств (enums/unions).
+
+### Стилизация и классы
+
+- `replaceClasses(template?: Function, end = ''): this` — генерирует список доступных CSS-классов на основе структуры.
+- `replaceClassesValues(): this` — создает логику динамической привязки классов для файлов реализации логики.
+- `replaceStylesValues(): this` — сопоставляет свойства компонента с пользовательскими переменными CSS (CSS Variables).
+- `replaceConstructorClasses(): this` — специализированный генератор классов для конструкторов компонентов.
+
+## Операции
+
+### Система меток
+
+Движок сканирует специфические паттерны комментариев, чтобы определить, куда внедрять код. Поддерживаются несколько стилей комментариев:
+
+1. **Инлайн логика**: `// :label data` или `/* :label */ content /* :label.end */`
+2. **Комментарии шаблонов**: `<!-- :label --> content <!-- :label.end -->`
+3. **Специфичность свойств**: `:label.propertyName.none` (используется для исключения конкретных свойств из блока).
+
+### Поток трансформации
+
+При вызове метода замены, такого как `replaceType()`, класс:
+1. **Сканирует**: находит начальный и конечный маркеры для метки `type`.
+2. **Обращается к структуре**: итерирует по свойствам в предоставленной `DesignStructure`.
+3. **Разрешает логику**: определяет правильный синтаксис TypeScript для каждого свойства на основе типа его значения (boolean, string или union).
+4. **Внедряет**: заменяет содержимое между маркерами новым сгенерированным кодом, сохраняя исходные отступы.

package/src/media/functional/scripts/classes/DesignReplace/DesignReplace.vi.mdx

@@ -0,0 +1,76 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/DesignReplace - Động cơ chuyển đổi mẫu'/>
+
+# Lớp DesignReplace
+
+Lớp `DesignReplace` là động cơ cốt lõi để chuyển đổi các tệp mẫu (templates) thô thành mã nguồn sẵn sàng cho dự án. Nó sử dụng một hệ thống đánh dấu chuyên biệt để xác định các phần văn bản cần được thay thế linh hoạt bằng tên thành phần, định nghĩa thuộc tính, kiểu dữ liệu hoặc logic tạo kiểu dáng được lấy từ `DesignStructure` của thành phần.
+
+## Các tính năng chính
+
+- **Phân giải nhãn thông minh** — Xác định và thay thế các khối văn bản được giới hạn bởi các nhận xét cụ thể (ví dụ: `// :type` hoặc `<!-- :props -->`).
+- **Đặt tên theo ngữ cảnh** — Tự động chuyển đổi các trình giữ chỗ (placeholders) chung như `[project]`, `[design]`, và `[component]` dựa trên cấu hình.
+- **Tiêm kiểu dữ liệu (Type Injection)** — Tạo các liên hợp kiểu (type unions) và giao diện TypeScript phức tạp trực tiếp từ siêu dữ liệu thuộc tính.
+- **Ánh xạ giá trị mặc định** — Phân giải và tiêm các giá trị mặc định cho các thuộc tính vào các đối tượng hoặc đối số constructor.
+- **Tạo lớp có điều kiện** — Tạo các đối tượng liên kết lớp Vue/TS và ánh xạ bộ chọn CSS được tối ưu hóa.
+- **Chuẩn hóa đường dẫn** — Tự động phân giải các đường dẫn nhập (import) tương đối dựa trên vị trí của tệp mục tiêu trong cây dự án.
+
+## Khởi tạo
+
+Để khởi tạo một động cơ thay thế, hãy truyền vào cấu trúc dữ liệu của thành phần, mã định danh nhãn mục tiêu và chuỗi mẫu.
+
+**Tham số:**
+- `structure: DesignStructure` — Nguồn sự thật cho siêu dữ liệu và các quy tắc cấu trúc của thành phần.
+- `mark: string` — Nhãn chính được sử dụng trong các mẫu để xác định các thành phần (ví dụ: `'button'`).
+- `sample: string` — Nội dung văn bản của mẫu cần được sửa đổi.
+
+```typescript
+import { DesignReplace } from '@dxtmisha/scripts'
+
+const engine = new DesignReplace(structure, 'button', templateContent)
+engine.replaceName().replaceType()
+const output = engine.get()
+```
+
+## Các phương thức
+
+### Điều khiển
+
+- `get(): string` — Trả về phiên bản cuối cùng của mẫu sau tất cả các chuyển đổi.
+- `getNameFile(name: string): string` — Xử lý tên tệp hoặc chuỗi để thay thế các trình giữ chỗ cấp dự án.
+- `replaceName(): this` — Thay thế các nhãn tên thành phần chính trong toàn bộ mẫu.
+- `replacePath(): this` — Sửa các đường dẫn tương đối (`../../../`) để trỏ đến đúng vị trí gốc của dự án.
+- `replaceMark(name: string, data: string[], end = ''): this` — Thực hiện thay thế khối cho một nhãn cụ thể bằng cách tiêm một mảng các chuỗi.
+- `replaceOnce(name?: string, removeReplacement?: boolean | Function): this` — Xử lý các dấu thay thế một lần (`.once`).
+
+### Tự động hóa thuộc tính & kiểu dữ liệu
+
+- `replaceType(constructor?: string): this` — Tạo và tiêm các kiểu TypeScript cho tất cả các thuộc tính thành phần.
+- `replaceDefault(): this` — Tiêm các giá trị mặc định cho các thuộc tính vào mẫu.
+- `replaceProps(): this` — Tạo các đối tượng định nghĩa thuộc tính kiểu Vue.
+- `replacePropsValues(): this` — Tạo các mảng giá trị được phép cho các thuộc tính (enums/unions).
+
+### Kiểu dáng & Lớp (Classes)
+
+- `replaceClasses(template?: Function, end = ''): this` — Tạo danh sách các lớp CSS có sẵn dựa trên cấu trúc.
+- `replaceClassesValues(): this` — Tạo logic liên kết lớp động cho các tệp triển khai logic.
+- `replaceStylesValues(): this` — Ánh xạ các thuộc tính thành phần với các biến tùy chỉnh CSS (CSS Variables).
+- `replaceConstructorClasses(): this` — Trình tạo lớp chuyên biệt cho các constructor của thành phần.
+
+## Các thao tác (Operations)
+
+### Hệ thống đánh dấu (Marking System)
+
+Động cơ quét các mẫu nhận xét cụ thể để xác định nơi tiêm mã. Nó hỗ trợ nhiều kiểu nhận xét:
+
+1. **Logic nội dòng**: `// :label data` hoặc `/* :label */ content /* :label.end */`
+2. **Nhận xét mẫu**: `<!-- :label --> content <!-- :label.end -->`
+3. **Tính đặc hiệu của thuộc tính**: `:label.propertyName.none` (được sử dụng để loại trừ các thuộc tính cụ thể khỏi một khối).
+
+### Quy trình chuyển đổi
+
+Khi một phương thức thay thế như `replaceType()` được gọi, lớp sẽ:
+1. **Quét**: Xác định vị trí các dấu bắt đầu và kết thúc cho nhãn `type`.
+2. **Tham chiếu cấu trúc**: Lặp qua các thuộc tính trong `DesignStructure` được cung cấp.
+3. **Phân giải logic**: Xác định cú pháp TypeScript chính xác cho mỗi thuộc tính dựa trên kiểu giá trị của nó (boolean, string, hoặc union).
+4. **Tiêm mã**: Thay thế nội dung giữa các dấu bằng mã mới được tạo, duy trì lề (indentation) ban đầu.

package/src/media/functional/scripts/classes/DesignStructure/DesignStructure.en.mdx

@@ -0,0 +1,63 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/DesignStructure - Component Data Resolution Engine'/>
+
+# DesignStructure Class
+
+The `DesignStructure` class is the foundational data resolver for design system components. It orchestrates the reading, caching, and processing of structured component data, including properties, CSS class hierarchies, and style tokens. It acts as an abstraction layer between raw configuration files and the template transformation engines.
+
+## Key Features
+
+- **Unified Data Access** — Provides a centralized API to retrieve all metadata associated with a specific component.
+- **Intelligent Caching** — Utilizes `PropertiesCache` to avoid redundant file system operations and speed up multi-component processing.
+- **Subclass Mapping** — Resolves complex CSS class hierarchies for recursive component structures.
+- **Style Token Exposure** — Extracts and formats design tokens into a format ready for SCSS generation.
+- **Naming Convention Orchestration** — Standardizes component, design, and file naming across the entire building process.
+
+## Initialization
+
+To initialize a structure resolver, provide the component's identifier. The class will automatically link it to the current project's design configuration.
+
+**Parameters:**
+- `component?: string` — The identifier for the component (e.g., `'button'`, `'list'`). Defaults to `'component'`.
+
+```typescript
+import { DesignStructure } from '@dxtmisha/scripts'
+
+const structure = new DesignStructure('button')
+const properties = structure.get()
+```
+
+## Methods
+
+### Data Acquisition
+
+- `get(): DesignStructureList` — Retrieves the full list of component properties and metadata, with caching.
+- `getClasses(): DesignStructureClassesList` — Resolves the hierarchy of CSS classes for the component.
+- `getStyles(): string[]` — Returns the formatted style tokens derived from the component's structure.
+
+### Naming & Identity
+
+- `getDesign(): string` — Returns the current design system identifier (e.g., `'misha'`).
+- `getDesignFirst(): string` — Returns the design identifier formatted with an uppercase first letter.
+- `getComponentName(): string` — Returns the raw component name.
+- `getComponentNameFirst(): string` — Returns the component name with an uppercase first letter.
+- `getFullComponentName(): string` — Combines design and component names (e.g., `'MishaButton'`).
+- `getFileName(): string` — Returns the standardized filename for the component's implementation.
+- `getPathName(): string` — Returns the unique identifier for cache keys and system paths.
+
+## Operations
+
+### The Resolution Pipeline
+
+When data is requested (e.g., via `get()` or `getClasses()`), the class triggers a modular resolution process:
+1. **Cache Validation**: It first checks if the processed data already exists in the `PropertiesCache` under a key generated by `getPathName()`.
+2. **Modular Delegation**: If data is missing from cache, it delegates the heavy lifting to specialized "Read" classes:
+    - **DesignStructureRead**: Handles the extraction of properties and values.
+    - **DesignStructureClasses**: Manages the construction of class trees.
+    - **DesignStructureStyles**: Processes tokens into style strings.
+3. **Persistance**: The resolved data is stored back into the cache to enhance performance for subsequent calls during the same build cycle.
+
+### Integration with Template Engines
+
+`DesignStructure` provides the "Source of Truth" for classes like `DesignReplace`. By standardizing how names and paths are resolved, it ensures that every generated file (Vue, TS, SCSS) uses consistent identifiers and maintains correct relative path references across the workspace.

package/src/media/functional/scripts/classes/DesignStructure/DesignStructure.ru.mdx

@@ -0,0 +1,63 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/DesignStructure - Движок разрешения данных компонента'/>
+
+# Класс DesignStructure
+
+Класс `DesignStructure` является фундаментальным разрешителем данных для компонентов дизайн-системы. Он координирует чтение, кэширование и обработку структурированных данных компонента, включая свойства, иерархии CSS-классов и токены стилей. Он выступает в качестве абстрактного слоя между сырыми файлами конфигурации и движками трансформации шаблонов.
+
+## Ключевые особенности
+
+- **Унифицированный доступ к данным** — предоставляет централизованный API для получения всех метаданных, связанных с конкретным компонентом.
+- **Интеллектуальное кэширование** — использует `PropertiesCache` для предотвращения избыточных операций с файловой системой и ускорения обработки нескольких компонентов.
+- **Маппинг подклассов** — разрешает сложные иерархии CSS-классов для рекурсивных структур компонентов.
+- **Предоставление токенов стилей** — извлекает и форматирует токены дизайна в формат, готовый для генерации SCSS.
+- **Оркестрация соглашений об именовании** — стандартизирует именование компонентов, дизайнов и файлов во всем процессе сборки.
+
+## Инициализация
+
+Для инициализации разрешителя структуры укажите идентификатор компонента. Класс автоматически свяжет его с текущей конфигурацией дизайна проекта.
+
+**Параметры:**
+- `component?: string` — идентификатор компонента (например, `'button'`, `'list'`). По умолчанию: `'component'`.
+
+```typescript
+import { DesignStructure } from '@dxtmisha/scripts'
+
+const structure = new DesignStructure('button')
+const properties = structure.get()
+```
+
+## Методы
+
+### Получение данных
+
+- `get(): DesignStructureList` — возвращает полный список свойств и метаданных компонента с использованием кэширования.
+- `getClasses(): DesignStructureClassesList` — разрешает иерархию CSS-классов компонента.
+- `getStyles(): string[]` — возвращает отформатированные токены стилей, полученные из структуры компонента.
+
+### Именование и идентификация
+
+- `getDesign(): string` — возвращает идентификатор текущей дизайн-системы (например, `'misha'`).
+- `getDesignFirst(): string` — возвращает идентификатор дизайна с заглавной буквы.
+- `getComponentName(): string` — возвращает исходное имя компонента.
+- `getComponentNameFirst(): string` — возвращает имя компонента с заглавной буквы.
+- `getFullComponentName(): string` — объединяет названия дизайна и компонента (например, `'MishaButton'`).
+- `getFileName(): string` — возвращает стандартизированное имя файла для реализации компонента.
+- `getPathName(): string` — возвращает уникальный идентификатор для ключей кэша и системных путей.
+
+## Операции
+
+### Конвейер разрешения (Resolution Pipeline)
+
+При запросе данных (например, через `get()` или `getClasses()`) класс запускает модульный процесс разрешения:
+1. **Проверка кэша**: сначала проверяется, существуют ли уже обработанные данные в `PropertiesCache` под ключом, сгенерированным `getPathName()`.
+2. **Модульное делегирование**: если данные в кэше отсутствуют, выполнение «тяжелой» работы делегируется специализированным классам «Read»:
+    - **DesignStructureRead**: управляет извлечением свойств и их значений.
+    - **DesignStructureClasses**: управляет построением деревьев классов.
+    - **DesignStructureStyles**: преобразует токены в строки стилей.
+3. **Сохранение**: разрешенные данные сохраняются обратно в кэш для повышения производительности при последующих вызовах в течение того же цикла сборки.
+
+### Интеграция с движками шаблонов
+
+`DesignStructure` служит «источником истины» для таких классов, как `DesignReplace`. Стандартизируя процесс разрешения имен и путей, он гарантирует, что каждый сгенерированный файл (Vue, TS, SCSS) использует согласованные идентификаторы и поддерживает корректные ссылки по относительным путям в рабочем пространстве.

package/src/media/functional/scripts/classes/DesignStructure/DesignStructure.vi.mdx

@@ -0,0 +1,63 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/DesignStructure - Động cơ phân giải dữ liệu thành phần'/>
+
+# Lớp DesignStructure
+
+Lớp `DesignStructure` là bộ phân giải dữ liệu nền tảng cho các thành phần của hệ thống thiết kế. Nó điều phối việc đọc, lưu trữ (caching) và xử lý dữ liệu thành phần có cấu trúc, bao gồm các thuộc tính, phân cấp lớp CSS và các token kiểu dáng. Nó đóng vai trò là một lớp trừu tượng giữa các tệp cấu hình thô và các động cơ chuyển đổi mẫu.
+
+## Các tính năng chính
+
+- **Truy cập dữ liệu thống nhất** — Cung cấp API tập trung để truy xuất tất cả siêu dữ liệu liên quan đến một thành phần cụ thể.
+- **Bộ nhớ đệm thông minh** — Sử dụng `PropertiesCache` để tránh các thao tác hệ thống tệp dư thừa và tăng tốc độ xử lý nhiều thành phần.
+- **Ánh xạ lớp con (Subclass Mapping)** — Phân giải các phân cấp lớp CSS phức tạp cho các cấu trúc thành phần đệ quy.
+- **Phơi bày Token kiểu dáng** — Trích xuất và định dạng các token thiết kế thành một định dạng sẵn sàng cho việc tạo SCSS.
+- **Điều phối quy ước đặt tên** — Tiêu chuẩn hóa việc đặt tên thành phần, thiết kế và tệp trong toàn bộ quá trình xây dựng.
+
+## Khởi tạo
+
+Để khởi tạo một bộ phân giải cấu trúc, hãy cung cấp mã định danh của thành phần. Lớp sẽ tự động liên kết nó với cấu hình thiết kế của dự án hiện tại.
+
+**Tham số:**
+- `component?: string` — Mã định danh cho thành phần (ví dụ: `'button'`, `'list'`). Mặc định là `'component'`.
+
+```typescript
+import { DesignStructure } from '@dxtmisha/scripts'
+
+const structure = new DesignStructure('button')
+const properties = structure.get()
+```
+
+## Các phương thức
+
+### Thu thập dữ liệu
+
+- `get(): DesignStructureList` — Truy xuất danh sách đầy đủ các thuộc tính và siêu dữ liệu của thành phần, có sử dụng bộ nhớ đệm.
+- `getClasses(): DesignStructureClassesList` — Phân giải phân cấp các lớp CSS cho thành phần.
+- `getStyles(): string[]` — Trả về các token kiểu dáng đã được định dạng được lấy từ cấu trúc của thành phần.
+
+### Đặt tên & Định danh
+
+- `getDesign(): string` — Trả về mã định danh hệ thống thiết kế hiện tại (ví dụ: `'misha'`).
+- `getDesignFirst(): string` — Trả về mã định danh thiết kế được định dạng với chữ cái đầu viết hoa.
+- `getComponentName(): string` — Trả về tên thành phần thô.
+- `getComponentNameFirst(): string` — Trả về tên thành phần với chữ cái đầu viết hoa.
+- `getFullComponentName(): string` — Kết hợp tên thiết kế và tên thành phần (ví dụ: `'MishaButton'`).
+- `getFileName(): string` — Trả về tên tệp tiêu chuẩn cho triển khai của thành phần.
+- `getPathName(): string` — Trả về mã định danh duy nhất cho các khóa bộ nhớ đệm và đường dẫn hệ thống.
+
+## Các thao tác (Operations)
+
+### Quy trình phân giải (The Resolution Pipeline)
+
+Khi dữ liệu được yêu cầu (ví dụ: thông qua `get()` hoặc `getClasses()`), lớp sẽ kích hoạt một quy trình phân giải theo mô-đun:
+1. **Xác thực bộ nhớ đệm**: Đầu tiên, nó kiểm tra xem dữ liệu đã xử lý đã tồn tại trong `PropertiesCache` dưới một khóa được tạo bởi `getPathName()` hay chưa.
+2. **Ủy quyền mô-đun**: Nếu dữ liệu thiếu trong bộ nhớ đệm, nó sẽ ủy quyền công việc nặng nề cho các lớp "Read" chuyên biệt:
+    - **DesignStructureRead**: Xử lý việc trích xuất các thuộc tính và giá trị.
+    - **DesignStructureClasses**: Quản lý việc xây dựng các cây lớp (class trees).
+    - **DesignStructureStyles**: Xử lý các token thành các chuỗi kiểu dáng.
+3. **Lưu trữ lâu dài**: Dữ liệu đã phân giải được lưu ngược trở lại vào bộ nhớ đệm để nâng cao hiệu suất cho các lần gọi tiếp theo trong cùng một chu kỳ xây dựng.
+
+### Tích hợp với các động cơ mẫu
+
+`DesignStructure` cung cấp "Nguồn sự thật" cho các lớp như `DesignReplace`. Bằng cách tiêu chuẩn hóa cách phân giải tên và đường dẫn, nó đảm bảo rằng mọi tệp được tạo (Vue, TS, SCSS) đều sử dụng các mã định danh nhất quán và duy trì các tham chiếu đường dẫn tương đối chính xác trong không gian làm việc.

package/src/media/functional/scripts/classes/DesignStructureClasses/DesignStructureClasses.en.mdx

@@ -0,0 +1,52 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/DesignStructureClasses - CSS Class Resolver'/>
+
+# DesignStructureClasses Class
+
+The `DesignStructureClasses` class is responsible for transforming a component's structural metadata into a flattened list of CSS class definitions. It identifies specific tokens marked as subclasses and recursively builds class names following BEM (Block Element Modifier) naming conventions, ensuring consistency across the design system's style architecture.
+
+## Key Features
+
+- **Recursive Class Discovery** — Deeply traverses property trees to find nested elements and modifiers.
+- **BEM Name Construction** — Automatically joins parent and child identifiers using double underscores (`__`) for elements.
+- **CamelCase Indexing** — Generates clean, variable-friendly names for use in TypeScript/Vue logic.
+- **Full-Name Support** — Allows specific tokens to ignore parent hierarchies and use global class names when required.
+- **Automated Property Mapping** — Directly integrates with standard property metadata to determine which items contribute to the styling API.
+
+## Initialization
+
+To initialize the class resolver, provide the base component name. The class will automatically load the associated structural metadata via its parent abstraction.
+
+**Parameters:**
+- `component: string` — The identifier of the component to process (e.g., `'button'`).
+
+```typescript
+import { DesignStructureClasses } from '@dxtmisha/scripts'
+
+const resolver = new DesignStructureClasses('button')
+const classes = resolver.get()
+```
+
+## Methods
+
+### Information
+
+- `get(): DesignStructureClassesList` — Returns the fully processed list of class mapping objects.
+
+## Operations
+
+### The Class Resolution Workflow
+
+When initialized, the class automatically executes its resolution logic:
+1. **Property Analysis**: The engine scans the component's `PropertyItem` list for tags indicating a `subclass` type.
+2. **Namespace Building**: It tracks the hierarchy of names. For example, a `label` inside a `button` becomes `button__label`.
+3. **Data Structuring**: For each identified class, it creates an object containing:
+    - **index**: A CamelCase version of the name (e.g., `buttonLabel`) for code references.
+    - **className**: The actual CSS class string (e.g., `button__label`).
+    - **full**: A flag indicating if the name is an absolute global class.
+4. **Flattening**: The recursive tree is flattened into a single array, providing a fast lookup for template engines.
+
+### Integration with Code Generators
+
+This class provides the essential mapping used by `DesignReplace` to inject class definitions into component implementations. By centralizing the naming logic, it ensures that changes to naming conventions can be applied globally across all components without manual file edits.

package/src/media/functional/scripts/classes/DesignStructureClasses/DesignStructureClasses.ru.mdx

@@ -0,0 +1,52 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/DesignStructureClasses - Разрешитель CSS-классов'/>
+
+# Класс DesignStructureClasses
+
+Класс `DesignStructureClasses` отвечает за преобразование структурных метаданных компонента в плоский список определений CSS-классов. Он идентифицирует специфические токены, помеченные как подклассы, и рекурсивно строит имена классов в соответствии с соглашениями об именовании BEM (Block Element Modifier), обеспечивая согласованность архитектуры стилей всей дизайн-системы.
+
+## Ключевые особенности
+
+- **Рекурсивное обнаружение классов** — глубоко обходит деревья свойств для поиска вложенных элементов и модификаторов.
+- **Построение BEM-имен** — автоматически объединяет идентификаторы родителя и потомка, используя двойное подчеркивание (`__`) для элементов.
+- **Индексация в CamelCase** — генерирует чистые, удобные для переменных имена для использования в логике TypeScript/Vue.
+- **Поддержка полных имен** — позволяет специфическим токенам игнорировать родительские иерархии и использовать глобальные имена классов, когда это необходимо.
+- **Автоматизированный маппинг свойств** — напрямую интегрируется со стандартными метаданными свойств для определения того, какие элементы вносят вклад в API стилизации.
+
+## Инициализация
+
+Для инициализации разрешителя классов укажите базовое имя компонента. Класс автоматически загрузит связанные структурные метаданные через свою родительскую абстракцию.
+
+**Параметры:**
+- `component: string` — идентификатор компонента для обработки (например, `'button'`).
+
+```typescript
+import { DesignStructureClasses } from '@dxtmisha/scripts'
+
+const resolver = new DesignStructureClasses('button')
+const classes = resolver.get()
+```
+
+## Методы
+
+### Информация
+
+- `get(): DesignStructureClassesList` — возвращает полностью обработанный список объектов маппинга классов.
+
+## Операции
+
+### Рабочий процесс разрешения классов
+
+При инициализации класс автоматически выполняет логику разрешения:
+1. **Анализ свойств**: движок сканирует список `PropertyItem` компонента на наличие тегов, указывающих на тип `subclass`.
+2. **Построение пространства имен**: он отслеживает иерархию имен. Например, `label` внутри `button` становится `button__label`.
+3. **Структурирование данных**: для каждого идентифицированного класса создается объект, содержащий:
+    - **index**: CamelCase версия имени (например, `buttonLabel`) для ссылок в коде.
+    - **className**: фактическая строка CSS-класса (например, `button__label`).
+    - **full**: флаг, указывающий, является ли имя абсолютным глобальным классом.
+4. **Плоская структура**: рекурсивное дерево преобразуется в одномерный массив, обеспечивая быстрый поиск для движков шаблонов.
+
+### Интеграция с генераторами кода
+
+Этот класс предоставляет важный маппинг, используемый `DesignReplace` для внедрения определений классов в реализации компонентов. Централизуя логику именования, он гарантирует, что изменения в соглашениях об именовании могут быть применены глобально ко всем компонентам без ручного редактирования файлов.