@dxtmisha/wiki 0.39.1 → 0.39.2

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` для внедрения определений классов в реализации компонентов. Централизуя логику именования, он гарантирует, что изменения в соглашениях об именовании могут быть применены глобально ко всем компонентам без ручного редактирования файлов.

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

@@ -0,0 +1,52 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/DesignStructureClasses - Bộ phân giải CSS Class'/>
+
+# Lớp DesignStructureClasses
+
+Lớp `DesignStructureClasses` chịu trách nhiệm chuyển đổi siêu dữ liệu cấu trúc của thành phần thành một danh sách phẳng các định nghĩa lớp CSS. Nó xác định các token cụ thể được đánh dấu là lớp con (subclasses) và xây dựng các tên lớp một cách đệ quy theo các quy ước đặt tên BEM (Block Element Modifier), đảm bảo tính nhất quán trên toàn bộ kiến trúc kiểu dáng của hệ thống thiết kế.
+
+## Các tính năng chính
+
+- **Khám phá lớp đệ quy** — Duyệt sâu các cây thuộc tính để tìm các phần tử và bộ sửa đổi (modifiers) lồng nhau.
+- **Xây dựng tên BEM** — Tự động kết hợp các mã định danh cha và con bằng cách sử dụng dấu gạch dưới kép (`__`) cho các phần tử.
+- **Lập chỉ mục CamelCase** — Tạo ra các tên sạch, thân thiện với biến để sử dụng trong logic TypeScript/Vue.
+- **Hỗ trợ tên đầy đủ (Full-Name)** — Cho phép các token cụ thể bỏ qua các phân cấp cha và sử dụng tên lớp toàn cục khi cần thiết.
+- **Ánh xạ thuộc tính tự động** — Tích hợp trực tiếp với siêu dữ liệu thuộc tính tiêu chuẩn để xác định các mục nào đóng góp vào API tạo kiểu dáng.
+
+## Khởi tạo
+
+Để khởi tạo bộ phân giải lớp, hãy cung cấp tên thành phần cơ sở. Lớp sẽ tự động tải siêu dữ liệu cấu trúc liên quan thông qua trừu tượng cha của nó.
+
+**Tham số:**
+- `component: string` — Mã định danh của thành phần cần xử lý (ví dụ: `'button'`).
+
+```typescript
+import { DesignStructureClasses } from '@dxtmisha/scripts'
+
+const resolver = new DesignStructureClasses('button')
+const classes = resolver.get()
+```
+
+## Các phương thức
+
+### Thông tin
+
+- `get(): DesignStructureClassesList` — Trả về danh sách đầy đủ các đối tượng ánh xạ lớp đã được xử lý.
+
+## Các thao tác (Operations)
+
+### Quy trình phân giải lớp
+
+Khi được khởi tạo, lớp sẽ tự động thực thi logic phân giải của nó:
+1. **Phân tích thuộc tính**: Động cơ quét danh sách `PropertyItem` của thành phần để tìm các thẻ cho biết kiểu `subclass`.
+2. **Xây dựng không gian tên**: Nó theo dõi phân cấp của các tên. Ví dụ, một `label` bên trong `button` sẽ trở thành `button__label`.
+3. **Cấu trúc dữ liệu**: Đối với mỗi lớp được xác định, nó tạo ra một đối tượng chứa:
+    - **index**: Phiên bản CamelCase của tên (ví dụ: `buttonLabel`) cho các tham chiếu mã.
+    - **className**: Chuỗi lớp CSS thực tế (ví dụ: `button__label`).
+    - **full**: Một cờ cho biết tên đó có phải là một lớp toàn cục tuyệt đối hay không.
+4. **Làm phẳng**: Cây đệ quy được làm phẳng thành một mảng duy nhất, cung cấp khả năng tra cứu nhanh chóng cho các động cơ mẫu.
+
+### Tích hợp với các trình tạo mã
+
+Lớp này cung cấp ánh xạ thiết yếu được `DesignReplace` sử dụng để tiêm các định nghĩa lớp vào các triển khai thành phần. Bằng cách tập trung logic đặt tên, nó đảm bảo rằng các thay đổi đối với quy ước đặt tên có thể được áp dụng chung cho tất cả các thành phần mà không cần chỉnh sửa tệp thủ công.

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

@@ -0,0 +1,49 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/DesignStructureItemAbstract - Base Structural Resolver'/>
+
+# DesignStructureItemAbstract Class
+
+The `DesignStructureItemAbstract` class serves as the fundamental building block for all specialized structural resolvers within the design system. It handles the low-level orchestration of the `Properties` engine, ensuring that every inheriting class has instant access to validated component metadata and design system tokens.
+
+## Key Features
+
+- **Standardized Initialization** — Automatically sets up the `Properties` environment for any inheriting resolver.
+- **Unified Link Generation** — Centralizes the logic for creating internal cross-references within the design system's JSON metadata.
+- **Metadata Fetching** — Automatically retrieves the component-specific slice of structural data during construction.
+- **Contract Enforcement** — Uses abstract properties to ensure all subclasses implement a standardized data-access pattern.
+
+## Initialization
+
+As an abstract class, `DesignStructureItemAbstract` cannot be instantiated directly. Inheriting classes must call `super()` with the component's identifier.
+
+**Parameters:**
+- `component: string` — The identifier of the component whose structure is being analyzed (e.g., `'button'`).
+
+**Internal State:**
+- `properties`: An instance of the global `Properties` manager.
+- `items`: The specific subset of structural data resolved for the given component.
+
+## Methods
+
+### Data Access
+
+- `get(): D` — Implementation-specific method that returns the fully processed data object.
+
+### Internal Logic (Protected)
+
+- `getLink(): string` — Generates the formatted internal link (e.g., `{misha.button}`) used to look up tokens in the global design metadata.
+
+## Operations
+
+### The Resolver Foundation
+
+When a subclass is instantiated (e.g., `DesignStructureClasses`), the abstract parent coordinates the following lifecycle:
+1. **Engine Setup**: A new `Properties` instance is initialized to provide access to the design system's global state.
+2. **Identity Linkage**: The `getLink()` method generates a specialized string identifier that bridges the component name with the current design theme.
+3. **Data Localization**: Using the generated link, the class queries the global property store to isolate only the relevant metadata for the current component, storing it in the `items` property.
+4. **Subclass Extension**: The subclass can then access `this.items` to perform its specific logic (like building class trees or formatting styles) without needing to worry about the underlying file resolution or caching.
+
+### Architecture Role
+
+This abstract class ensures that the "Read" and "Resolver" layers of the script library follow a consistent pattern. By abstracting the property loading logic, it allows developer to create new types of structural analyzers by simply focusing on the transformation logic, rather than the data fetching mechanics.

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

@@ -0,0 +1,49 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/DesignStructureItemAbstract - Базовый структурный разрешитель'/>
+
+# Класс DesignStructureItemAbstract
+
+Класс `DesignStructureItemAbstract` служит фундаментальным строительным блоком для всех специализированных структурных разрешителей в рамках дизайн-системы. Он управляет низкоуровневой оркестрацией движка `Properties`, гарантируя, что каждый наследующий класс имеет мгновенный доступ к валидированным метаданным компонентов и токенам дизайн-системы.
+
+## Ключевые особенности
+
+- **Стандартизированная инициализация** — автоматически настраивает окружение `Properties` для любого наследуемого разрешителя.
+- **Унифицированная генерация ссылок** — централизует логику создания внутренних перекрестных ссылок внутри JSON-метаданных дизайн-системы.
+- **Извлечение метаданных** — автоматически извлекает специфический для компонента срез структурных данных во время конструирования.
+- **Соблюдение контрактов** — использует абстрактные свойства, чтобы гарантировать реализацию стандартизированного паттерна доступа к данным во всех подклассах.
+
+## Инициализация
+
+Являясь абстрактным классом, `DesignStructureItemAbstract` не может быть инстанцирован напрямую. Наследуемые классы должны вызывать `super()` с идентификатором компонента.
+
+**Параметры:**
+- `component: string` — идентификатор компонента, структура которого анализируется (например, `'button'`).
+
+**Внутреннее состояние:**
+- `properties`: экземпляр глобального менеджера `Properties`.
+- `items`: специфический подмножество структурных данных, разрешенных для данного компонента.
+
+## Методы
+
+### Доступ к данным
+
+- `get(): D` — специфичный для реализации метод, который возвращает полностью обработанный объект данных.
+
+### Внутренняя логика (защищенная)
+
+- `getLink(): string` — генерирует отформатированную внутреннюю ссылку (например, `{misha.button}`), используемую для поиска токенов в глобальных метаданных дизайна.
+
+## Операции
+
+### Основа разрешителя
+
+При создании экземпляра подкласса (например, `DesignStructureClasses`), абстрактный родитель координирует следующий жизненный цикл:
+1. **Настройка движка**: инициализируется новый экземпляр `Properties` для обеспечения доступа к глобальному состоянию дизайн-системы.
+2. **Привязка идентификатора**: метод `getLink()` генерирует специализированный строковый идентификатор, который связывает имя компонента с текущей темой дизайна.
+3. **Локализация данных**: используя сгенерированную ссылку, класс опрашивает глобальное хранилище свойств, чтобы изолировать только релевантные метаданные для текущего компонента, сохраняя их в свойстве `items`.
+4. **Расширение в подклассах**: подкласс затем может получить доступ к `this.items` для выполнения своей специфической логики (например, построения деревьев классов или форматирования стилей), не беспокоясь о механизмах разрешения файлов или кэшировании.
+
+### Роль в архитектуре
+
+Этот абстрактный класс гарантирует, что уровни «Read» и «Resolver» библиотеки сценариев следуют единому шаблону. Абстрагируя логику загрузки свойств, он позволяет разработчикам создавать новые типы структурных анализаторов, сосредоточившись исключительно на логике трансформации, а не на механике получения данных.

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

@@ -0,0 +1,49 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/DesignStructureItemAbstract - Bộ phân giải cấu trúc cơ sở'/>
+
+# Lớp DesignStructureItemAbstract
+
+Lớp `DesignStructureItemAbstract` đóng vai trò là khối xây dựng nền tảng cho tất cả các bộ phân giải cấu trúc chuyên biệt trong hệ thống thiết kế. Nó xử lý việc điều phối cấp thấp của động cơ `Properties`, đảm bảo rằng mọi lớp kế thừa đều có quyền truy cập tức thì vào siêu dữ liệu thành phần và các token hệ thống thiết kế đã được xác thực.
+
+## Các tính năng chính
+
+- **Khởi tạo tiêu chuẩn hóa** — Tự động thiết lập môi trường `Properties` cho bất kỳ bộ phân giải kế thừa nào.
+- **Tạo liên kết thống nhất** — Tập trung logic để tạo các tham chiếu chéo nội bộ trong siêu dữ liệu JSON của hệ thống thiết kế.
+- **Lấy siêu dữ liệu** — Tự động truy xuất lát cắt dữ liệu cấu trúc cụ thể của thành phần trong quá trình xây dựng.
+- **Thực thi hợp đồng** — Sử dụng các thuộc tính trừu tượng để đảm bảo tất cả các lớp con đều triển khai một mẫu truy cập dữ liệu tiêu chuẩn hóa.
+
+## Khởi tạo
+
+Là một lớp trừu tượng, `DesignStructureItemAbstract` không thể được khởi tạo trực tiếp. Các lớp kế thừa phải gọi `super()` với mã định danh của thành phần.
+
+**Tham số:**
+- `component: string` — Mã định danh của thành phần có cấu trúc đang được phân tích (ví dụ: `'button'`).
+
+**Trạng thái nội bộ:**
+- `properties`: Một phiên bản của trình quản lý `Properties` toàn cục.
+- `items`: Tập hợp con cụ thể của dữ liệu cấu trúc được phân giải cho thành phần đã cho.
+
+## Các phương thức
+
+### Truy cập dữ liệu
+
+- `get(): D` — Phương thức cụ thể theo triển khai trả về đối tượng dữ liệu đã được xử lý hoàn chỉnh.
+
+### Logic nội bộ (Được bảo vệ)
+
+- `getLink(): string` — Tạo liên kết nội bộ đã được định dạng (ví dụ: `{misha.button}`) được dùng để tra cứu các token trong siêu dữ liệu thiết kế toàn cục.
+
+## Các thao tác (Operations)
+
+### Nền tảng của bộ phân giải
+
+Khi một lớp con được khởi tạo (ví dụ: `DesignStructureClasses`), lớp cha trừu tượng sẽ điều phối vòng đời sau:
+1. **Thiết lập động cơ**: Một thực thể `Properties` mới được khởi tạo để cung cấp quyền truy cập vào trạng thái toàn cục của hệ thống thiết kế.
+2. **Liên kết định danh**: Phương thức `getLink()` tạo ra một mã định danh chuỗi chuyên biệt kết nối tên thành phần với chủ đề thiết kế hiện tại.
+3. **Bản địa hóa dữ liệu**: Sử dụng liên kết đã tạo, lớp sẽ truy vấn kho lưu trữ thuộc tính toàn cục để tách biệt chỉ các siêu dữ liệu liên quan cho thành phần hiện tại, lưu trữ nó trong thuộc tính `items`.
+4. **Mở rộng lớp con**: Lớp con sau đó có thể truy cập `this.items` để thực hiện logic cụ thể của nó (như xây dựng cây lớp hoặc định dạng kiểu dáng) mà không cần lo lắng về việc phân giải tệp hoặc bộ nhớ đệm bên dưới.
+
+### Vai trò kiến trúc
+
+Lớp trừu tượng này đảm bảo rằng các lớp "Read" và "Resolver" của thư viện tập lệnh tuân theo một mẫu nhất quán. Bằng cách trừu tượng hóa logic tải thuộc tính, nó cho phép nhà phát triển tạo ra các loại trình phân tích cấu trúc mới bằng cách chỉ tập trung vào logic chuyển đổi, thay vì cơ chế lấy dữ liệu.