@dxtmisha/wiki 0.39.1 → 0.39.3

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

@@ -0,0 +1,58 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PackageInit - Package Initializer'/>
+
+# PackageInit Class
+
+The `PackageInit` class is responsible for bootstrapping new package structures within the design system. It handles directory scanning and delegates individual file initialization to the `PackageInitItem` class, ensuring consistent environment setup based on provided templates and types.
+
+## Key Features
+
+- **Automated Structure Bootstrapping** — Automatically creates the necessary folder hierarchy for new packages.
+- **Template-Based Initialization** — Supports different package types and template sets for flexible environment setup.
+- **Recursive Directory Handling** — Identifies and processes empty or new directories within the package root.
+- **Lifecycle Management** — Provides a single entry point for triggering the entire initialization sequence.
+
+## Initialization
+
+To initialize the object, call the `PackageInit(type, templates, dir)` constructor.
+
+**Parameters:**
+- `type: string` — The package type identifier (e.g., `'functional'`, `'ui'`).
+- `templates?: string` — Optional comma-separated list of templates to be applied.
+- `dir: string` — The base directory where packages are located (defaults to `UI_DIR_PACKAGES`).
+
+```typescript
+import { PackageInit } from '@dxtmisha/scripts'
+
+// Initialize for a 'functional' package with default templates
+const initializer = new PackageInit('functional', 'basic,test')
+```
+
+## Methods
+
+### Control
+
+- `make(): void` — Starts the initialization process for all identified directories within the target path.
+
+## Operations
+
+### Detailed Initialization Flow
+
+The `make()` method follows a specific sequence to ensure a clean package setup:
+
+1. **Scanning**: It scans the target `dir` to identify subdirectories that require initialization (typically empty ones).
+2. **Delegation**: For each identified directory, it creates an instance of `PackageInitItem`.
+3. **Execution**: It triggers the `make()` method on each `PackageInitItem`, which handles the actual file creation and template application.
+
+### Identifying Target Directories
+
+The class uses the `getDirs()` internal method to find directories that are "empty" (contain no subdirectories), which are then treated as the roots for new package components.
+```typescript
+protected getDirs(): string[] {
+  return PropertiesFile.readDir(this.dir)
+    .filter(
+      path => PropertiesFile.readDir([this.dir, path]).length === 0
+    )
+}
+```

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

@@ -0,0 +1,58 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PackageInit - Инициализатор пакета'/>
+
+# Класс PackageInit
+
+Класс `PackageInit` отвечает за базовую настройку структуры новых пакетов внутри дизайн-системы. Он управляет сканированием директорий и делегирует инициализацию отдельных файлов классу `PackageInitItem`, обеспечивая согласованную настройку окружения на основе предоставленных шаблонов и типов.
+
+## Ключевые особенности
+
+- **Автоматическое развертывание структуры** — автоматически создает необходимую иерархию папок для новых пакетов.
+- **Инициализация на основе шаблонов** — поддерживает различные типы пакетов и наборы шаблонов для гибкой настройки окружения.
+- **Рекурсивная работа с директориями** — идентифицирует и обрабатывает пустые или новые директории в корне пакета.
+- **Управление жизненным циклом** — предоставляет единую точку входа для запуска всей последовательности инициализации.
+
+## Инициализация
+
+Для инициализации объекта вызовите конструктор `PackageInit(type, templates, dir)`.
+
+**Параметры:**
+- `type: string` — идентификатор типа пакета (например, `'functional'`, `'ui'`).
+- `templates?: string` — необязательный список шаблонов (через запятую) для применения.
+- `dir: string` — базовая директория, где расположены пакеты (по умолчанию `UI_DIR_PACKAGES`).
+
+```typescript
+import { PackageInit } from '@dxtmisha/scripts'
+
+// Инициализация для 'functional' пакета с набором шаблонов
+const initializer = new PackageInit('functional', 'basic,test')
+```
+
+## Методы
+
+### Управление
+
+- `make(): void` — запускает процесс инициализации для всех идентифицированных директорий по целевому пути.
+
+## Операции
+
+### Подробный процесс инициализации
+
+Метод `make()` следует определенной последовательности для обеспечения чистой настройки пакета:
+
+1. **Сканирование**: сканирует целевую директорию `dir` для поиска подпапок, требующих инициализации (обычно пустых).
+2. **Делегирование**: для каждой найденной директории создает экземпляр `PackageInitItem`.
+3. **Выполнение**: запускает метод `make()` у каждого `PackageInitItem`, который отвечает за фактическое создание файлов и применение шаблонов.
+
+### Поиск целевых директорий
+
+Класс использует внутренний метод `getDirs()` для поиска директорий, которые являются "пустыми" (не содержат подпапок), и которые затем обрабатываются как корни новых компонентов пакета.
+```typescript
+protected getDirs(): string[] {
+  return PropertiesFile.readDir(this.dir)
+    .filter(
+      path => PropertiesFile.readDir([this.dir, path]).length === 0
+    )
+}
+```

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

@@ -0,0 +1,58 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PackageInit - Trình khởi tạo gói'/>
+
+# Lớp PackageInit
+
+Lớp `PackageInit` chịu trách nhiệm khởi tạo cấu trúc gói mới trong hệ thống thiết kế. Nó xử lý việc quét danh mục và ủy quyền khởi tạo tệp riêng lẻ cho lớp `PackageInitItem`, đảm bảo thiết lập môi trường nhất quán dựa trên các mẫu và loại được cung cấp.
+
+## Các tính năng chính
+
+- **Tự động triển khai cấu trúc** — Tự động tạo hệ thống phân cấp thư mục cần thiết cho các gói mới.
+- **Khởi tạo dựa trên mẫu** — Hỗ trợ các loại gói và bộ mẫu khác nhau để thiết lập môi trường linh hoạt.
+- **Xử lý thư mục đệ quy** — Xác định và xử lý các thư mục trống hoặc mới trong thư mục gốc của gói.
+- **Quản lý vòng đời** — Cung cấp một điểm nhập duy nhất để kích hoạt toàn bộ chuỗi khởi tạo.
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `PackageInit(type, templates, dir)`.
+
+**Tham số:**
+- `type: string` — Mã định danh loại gói (ví dụ: `'functional'`, `'ui'`).
+- `templates?: string` — Danh sách các mẫu tùy chọn cần áp dụng (cách nhau bởi dấu phẩy).
+- `dir: string` — Thư mục cơ sở nơi đặt các gói (mặc định là `UI_DIR_PACKAGES`).
+
+```typescript
+import { PackageInit } from '@dxtmisha/scripts'
+
+// Khởi tạo cho gói 'functional' với các mẫu mặc định
+const initializer = new PackageInit('functional', 'basic,test')
+```
+
+## Các phương thức
+
+### Điều khiển
+
+- `make(): void` — Bắt đầu quá trình khởi tạo cho tất cả các thư mục được xác định trong đường dẫn mục tiêu.
+
+## Các thao tác (Operations)
+
+### Quy trình khởi tạo chi tiết
+
+Phương thức `make()` tuân theo một trình tự cụ thể để đảm bảo thiết lập gói sạch sẽ:
+
+1. **Quét**: Quét thư mục mục tiêu `dir` để xác định các thư mục con yêu cầu khởi tạo (thường là các thư mục trống).
+2. **Ủy quyền**: Đối với mỗi thư mục được xác định, nó tạo một thực thể của `PackageInitItem`.
+3. **Thực thi**: Kích hoạt phương thức `make()` trên mỗi `PackageInitItem`, phương thức này xử lý việc tạo tệp thực tế và áp dụng mẫu.
+
+### Xác định thư mục mục tiêu
+
+Lớp sử dụng phương thức nội bộ `getDirs()` để tìm các thư mục "trống" (không chứa thư mục con), sau đó được coi là gốc cho các thành phần gói mới.
+```typescript
+protected getDirs(): string[] {
+  return PropertiesFile.readDir(this.dir)
+    .filter(
+      path => PropertiesFile.readDir([this.dir, path]).length === 0
+    )
+}
+```

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

@@ -0,0 +1,61 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PackageInitItem - Package Item Initializer'/>
+
+# PackageInitItem Class
+
+The `PackageInitItem` class handles the detailed initialization of an individual component or sub-package. It manages the file lifecycle—from template application to integration with the main library, `package.json`, and Storybook.
+
+## Key Features
+
+- **File Generation** — Automatically creates files based on samples and specialized templates.
+- **Dynamic Content Replacement** — Automatically resolves placeholders like `[name]` and `@packages/library` within generated files.
+- **Library Integration** — Automatically generates entry points and registers the component in the global library.
+- **Dependency Management** — Updates the root `package.json` to include the new package in dependencies, exports, and files list.
+- **Storybook Automation** — Automatically injects new stories into the Storybook configuration.
+
+## Initialization
+
+To initialize the object, call the `PackageInitItem(name, dir, type, templates)` constructor.
+
+**Parameters:**
+- `name: string` — The unique name/path identifier of the component.
+- `dir: string[]` — The absolute path array to the component's target directory.
+- `type: string` — The package type identifier (e.g., `'functional'`, `'ui'`).
+- `templates?: string` — Optional comma-separated list of templates to be applied.
+
+```typescript
+import { PackageInitItem } from '@dxtmisha/scripts'
+
+const item = new PackageInitItem(
+  'button',
+  ['path', 'to', 'button'],
+  'ui'
+)
+```
+
+## Methods
+
+### Control
+
+- `make(): void` — Executes the full initialization sequence: creating files, updating the library, `package.json`, and Storybook.
+
+## Operations
+
+### Initialization Workflow
+
+When `make()` is called, the class performs the following steps in order:
+
+1. **File Scaffolding**: It retrieves sample files from the media/templates directory based on the package `type`.
+2. **Template Application**: If specific `templates` are provided, it fetches and applies them.
+3. **File Writing**: It writes the processed files to the target directory, performing necessary content replacements.
+4. **Integration (Library)**: If a `library.ts` file is created, it triggers the automatic generation of export files in the library root.
+5. **Integration (Package)**: It updates the root `package.json` to register the new package's workspace dependency and exports.
+6. **Integration (Storybook)**: It scans for the Storybook configuration and adds patterns to include the new component's stories.
+
+### Internal Resolution Logic
+
+The class uses several internal helpers to resolve naming conventions:
+- **`getName()`**: Normalizes the component name for use in file content.
+- **`getCode()`**: Converts the name to a hyphenated code for package identifiers.
+- **`getProjectName()`**: Resolves the full NPM package name including the design prefix.

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

@@ -0,0 +1,61 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PackageInitItem - Инициализатор элемента пакета'/>
+
+# Класс PackageInitItem
+
+Класс `PackageInitItem` отвечает за детальную инициализацию отдельного компонента или подпакета. Он управляет жизненным циклом файлов — от применения шаблонов до интеграции с основной библиотекой, `package.json` и Storybook.
+
+## Ключевые особенности
+
+- **Генерация файлов** — автоматически создает файлы на основе базовых образцов и специализированных шаблонов.
+- **Динамическая замена контента** — автоматически разрешает такие плейсхолдеры, как `[name]` и `@packages/library` внутри сгенерированных файлов.
+- **Интеграция с библиотекой** — автоматически генерирует точки входа и регистрирует компонент в глобальной библиотеке.
+- **Управление зависимостями** — обновляет корневой `package.json`, включая новый пакет в зависимости (dependencies), экспорты (exports) и список файлов (files).
+- **Автоматизация Storybook** — автоматически добавляет новые истории в конфигурацию Storybook.
+
+## Инициализация
+
+Для инициализации объекта вызовите конструктор `PackageInitItem(name, dir, type, templates)`.
+
+**Параметры:**
+- `name: string` — уникальное имя или идентификатор пути компонента.
+- `dir: string[]` — массив абсолютного пути к целевой директории компонента.
+- `type: string` — идентификатор типа пакета (например, `'functional'`, `'ui'`).
+- `templates?: string` — необязательный список шаблонов (через запятую) для применения.
+
+```typescript
+import { PackageInitItem } from '@dxtmisha/scripts'
+
+const item = new PackageInitItem(
+  'button',
+  ['path', 'to', 'button'],
+  'ui'
+)
+```
+
+## Методы
+
+### Управление
+
+- `make(): void` — выполняет полный цикл инициализации: создание файлов, обновление библиотеки, `package.json` и Storybook.
+
+## Операции
+
+### Рабочий процесс инициализации
+
+При вызове `make()` класс выполняет следующие шаги по порядку:
+
+1. **Создание структуры файлов**: получает файлы-образцы из директории media/templates на основе типа пакета `type`.
+2. **Применение шаблонов**: если указаны конкретные `templates`, он загружает и применяет их.
+3. **Запись файлов**: записывает обработанные файлы в целевую директорию, выполняя необходимые замены контента.
+4. **Интеграция (Библиотека)**: если создается файл `library.ts`, он запускает автоматическую генерацию файлов экспорта в корне библиотеки.
+5. **Интеграция (Пакет)**: обновляет корневой `package.json` для регистрации зависимости воркспейса и экспортов нового пакета.
+6. **Интеграция (Storybook)**: сканирует конфигурацию Storybook и добавляет шаблоны для включения историй нового компонента.
+
+### Внутренняя логика разрешения имен
+
+Класс использует несколько внутренних помощников для разрешения имен:
+- **`getName()`**: нормализует имя компонента для использования в контенте файлов.
+- **`getCode()`**: преобразует имя в код через дефис для идентификаторов пакетов.
+- **`getProjectName()`**: разрешает полное имя NPM-пакета, включая префикс дизайна.

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

@@ -0,0 +1,61 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PackageInitItem - Trình khởi tạo mục gói'/>
+
+# Lớp PackageInitItem
+
+Lớp `PackageInitItem` xử lý quá trình khởi tạo chi tiết của một thành phần riêng lẻ hoặc gói con. Nó quản lý vòng đời của tệp — từ việc áp dụng mẫu đến tích hợp với thư viện chính, `package.json` và Storybook.
+
+## Các tính năng chính
+
+- **Tạo tệp** — Tự động tạo các tệp dựa trên các mẫu có sẵn và các mẫu chuyên dụng.
+- **Thay thế nội dung động** — Tự động phân giải các trình giữ chỗ như `[name]` và `@packages/library` bên trong các tệp được tạo.
+- **Tích hợp thư viện** — Tự động tạo các điểm nhập và đăng ký thành phần trong thư viện toàn cục.
+- **Quản lý phụ thuộc** — Cập nhật `package.json` gốc để bao gồm gói mới trong các phần phụ thuộc, xuất bản (exports) và danh sách tệp.
+- **Tự động hóa Storybook** — Tự động chèn các câu chuyện (stories) mới vào cấu hình Storybook.
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `PackageInitItem(name, dir, type, templates)`.
+
+**Tham số:**
+- `name: string` — Tên hoặc định danh đường dẫn duy nhất của thành phần.
+- `dir: string[]` — Mảng đường dẫn tuyệt đối đến thư mục mục tiêu của thành phần.
+- `type: string` — Mã định danh loại gói (ví dụ: `'functional'`, `'ui'`).
+- `templates?: string` — Danh sách các mẫu tùy chọn cần áp dụng (cách nhau bởi dấu phẩy).
+
+```typescript
+import { PackageInitItem } from '@dxtmisha/scripts'
+
+const item = new PackageInitItem(
+  'button',
+  ['path', 'to', 'button'],
+  'ui'
+)
+```
+
+## Các phương thức
+
+### Điều khiển
+
+- `make(): void` — Thực hiện chu trình khởi tạo đầy đủ: tạo tệp, cập nhật thư viện, `package.json` và Storybook.
+
+## Các thao tác (Operations)
+
+### Quy trình khởi tạo
+
+Khi `make()` được gọi, lớp sẽ thực hiện các bước sau theo thứ tự:
+
+1. **Chuẩn bị file**: Nó lấy các tệp mẫu từ thư mục media/templates dựa trên loại gói `type`.
+2. **Áp dụng mẫu**: Nếu các `templates` cụ thể được cung cấp, nó sẽ lấy và áp dụng chúng.
+3. **Ghi tệp**: Nó ghi các tệp đã xử lý vào thư mục mục tiêu, thực hiện các thay thế nội dung cần thiết.
+4. **Tích hợp (Thư viện)**: Nếu tệp `library.ts` được tạo, nó sẽ kích hoạt việc tự động tạo các tệp xuất bản (export) trong thư mục gốc của thư viện.
+5. **Tích hợp (Gói)**: Nó cập nhật `package.json` gốc để đăng ký phụ thuộc workspace và xuất bản của gói mới.
+6. **Tích hợp (Storybook)**: Nó quét cấu hình Storybook và thêm các mẫu để bao gồm các câu chuyện của thành phần mới.
+
+### Logic phân giải nội bộ
+
+Lớp sử dụng một số hàm hỗ trợ nội bộ để phân giải các quy ước đặt tên:
+- **`getName()`**: Bình thường hóa tên thành phần để sử dụng trong nội dung tệp.
+- **`getCode()`**: Chuyển đổi tên thành mã có gạch nối cho các định danh gói.
+- **`getProjectName()`**: Phân giải tên gói NPM đầy đủ bao gồm cả tiền tố thiết kế.

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

@@ -0,0 +1,51 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/Properties - Design Token Orchestrator'/>
+
+# Properties Class
+
+The `Properties` class is the core processing engine of the design system's token infrastructure. It acts as a central orchestrator that coordinates the loading, structural merging, and recursive transformation of raw property definitions into a final, resolved state. By abstracting the complexity of dozens of specialized transformation rules, it provides a stable "source of truth" for all components and build tools.
+
+## Key Features
+
+- **Multi-Stage Processing Pipeline** — Executes specialized transformers for replacing, cloning, dragging, and linking design tokens.
+- **Structural Merging** — Intelligently resolves and merges settings, global defaults, and component-specific overrides.
+- **Incremental Cache Management** — Uses `PropertiesCache` to persist processed results, significantly improving build performance.
+- **SCSS Synthesis** — Compiles resolved tokens into a structured SCSS format for direct use in styling layers.
+- **AI-Optimized Metadata** — Prepares property structures that are easily consumable by documentation engines and AI-driven generators.
+
+## Initialization
+
+Initialize the orchestrator to immediately begin processing the tokens defined in the project's configuration.
+
+```typescript
+import { Properties } from '@dxtmisha/scripts'
+
+const engine = new Properties()
+const tokens = engine.get() // Returns the fully processed PropertiesItems
+```
+
+## Methods
+
+### Data Access
+
+- `get(): PropertiesItems` — Returns the core container of all processed design tokens.
+- `getScss(): string` — Returns the compiled SCSS representation of the current token set.
+
+## Operations
+
+### The Token Processing Pipeline
+
+When instantiated, `Properties` coordinates a comprehensive multi-layered transformation flow:
+1. **Source Acquisition**: It reads and merges raw data from `PropertiesSettings`, `PropertiesMain`, and external JSON files.
+2. **Basic Normalization**: Triggers foundational transformations:
+    - **Replacement**: Resolves alias patterns.
+    - **Palette Resolution**: Injects color palette values.
+    - **Cloning & Sub-Property Synthesis**: Handles complex property replications.
+3. **Advanced Transformation**: Executes high-level logic for:
+    - **Component Resolution**: Maps properties to specific component structures.
+    - **State & Class Mapping**: Generates metadata for UI states (hover, active) and BEM classes.
+    - **Media & Animation Synthesis**: Resolves responsive breakpoints and motion tokens.
+4. **Optimization & Cleanup**: Sorts properties, handles duplicates, and purges empty nodes.
+5. **Persistence**: The final result is stored in the `PropertiesCache` using a unique hash based on the current design configuration.
+

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

@@ -0,0 +1,51 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/Properties - Оркестратор токенов дизайна'/>
+
+# Класс Properties
+
+Класс `Properties` — это основное ядро инфраструктуры токенов дизайн-системы. Он выступает в роли центрального оркестратора, координирующего загрузку, структурное слияние и рекурсивное преобразование необработанных определений свойств в конечное, разрешенное состояние. Абстрагируя сложность десятков специализированных правил трансформации, он предоставляет стабильный «источник истины» для всех компонентов и инструментов сборки.
+
+## Ключевые особенности
+
+- **Многоэтапный конвейер обработки** — выполняет специализированные трансформаторы для замены, клонирования, связывания и перемещения токенов дизайна.
+- **Структурное слияние** — интеллектуально разрешает и объединяет настройки, глобальные значения по умолчанию и переопределения для конкретных компонентов.
+- **Инкрементальное управление кэшем** — использует `PropertiesCache` для сохранения результатов обработки, что значительно повышает производительность сборки.
+- **Синтез SCSS** — компилирует разрешенные токены в структурированный формат SCSS для прямого использования в слоях стилизации.
+- **Оптимизированные для ИИ метаданные** — подготавливает структуры свойств, которые легко потребляются движками документации и генераторами на базе ИИ.
+
+## Инициализация
+
+Инициализируйте оркестратор, чтобы немедленно запустить обработку токенов, определенных в конфигурации проекта.
+
+```typescript
+import { Properties } from '@dxtmisha/scripts'
+
+const engine = new Properties()
+const tokens = engine.get() // Возвращает полностью обработанный PropertiesItems
+```
+
+## Методы
+
+### Доступ к данным
+
+- `get(): PropertiesItems` — Возвращает основной контейнер всех обработанных токенов дизайна.
+- `getScss(): string` — Возвращает скомпилированное представление текущего набора токенов в формате SCSS.
+
+## Операции
+
+### Конвейер обработки токенов
+
+При создании экземпляра `Properties` координирует комплексный многоуровневый поток трансформаций:
+1. **Получение источников**: читает и объединяет необработанные данные из `PropertiesSettings`, `PropertiesMain` и внешних JSON-файлов.
+2. **Базовая нормализация**: запускает фундаментальные преобразования:
+    - **Замена (Replacement)**: разрешает паттерны алиасов.
+    - **Разрешение палитры**: внедряет значения цветовых палитр.
+    - **Клонирование и синтез подсвойств**: обрабатывает сложные репликации свойств.
+3. **Продвинутая трансформация**: выполняет высокоуровневую логику для:
+    - **Разрешения компонентов**: сопоставляет свойства со структурами конкретных компонентов.
+    - **Маппинга состояний и классов**: генерирует метаданные для состояний UI (hover, active) и BEM-классов.
+    - **Синтеза медиа и анимаций**: разрешает адаптивные контрольные точки и токены движения.
+4. **Оптимизация и очистка**: сортирует свойства, обрабатывает дубликаты и удаляет пустые узлы.
+5. **Сохранение**: финальный результат сохраняется в `PropertiesCache` с использованием уникального хеша на основе текущей конфигурации дизайна.
+

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

@@ -0,0 +1,51 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/Properties - Bộ điều phối Token thiết kế'/>
+
+# Lớp Properties
+
+Lớp `Properties` là công cụ xử lý cốt lõi của cơ sở hạ tầng token trong hệ thống thiết kế. Nó đóng vai trò là bộ điều phối trung tâm để phối hợp việc tải, hợp nhất cấu trúc và biến đổi đệ quy các định nghĩa thuộc tính thô thành trạng thái cuối cùng đã được phân giải. Bằng cách trừu tượng hóa sự phức tạp của hàng chục quy tắc biến đổi chuyên biệt, nó cung cấp một "nguồn sự thật" ổn định cho tất cả các thành phần và công cụ xây dựng.
+
+## Các tính năng chính
+
+- **Quy trình xử lý đa giai đoạn** — Thực thi các bộ biến đổi chuyên biệt để thay thế, sao chép, kéo và liên kết các token thiết kế.
+- **Hợp nhất cấu trúc** — Phân giải và hợp nhất một cách thông minh các cài đặt, giá trị mặc định toàn cầu và các ghi đè (overrides) dành riêng cho thành phần.
+- **Quản lý bộ nhớ đệm tăng dần** — Sử dụng `PropertiesCache` để lưu trữ kết quả đã xử lý, cải thiện đáng kể hiệu suất xây dựng.
+- **Tổng hợp SCSS** — Biên dịch các token đã phân giải thành định dạng SCSS có cấu trúc để sử dụng trực tiếp trong các lớp tạo kiểu.
+- **Siêu dữ liệu tối ưu cho AI** — Chuẩn bị các cấu trúc thuộc tính dễ dàng tiêu thụ bởi các công cụ tài liệu và trình tạo dựa trên AI.
+
+## Khởi tạo
+
+Khởi tạo bộ điều phối để bắt đầu xử lý ngay lập tức các token được định nghĩa trong cấu hình dự án.
+
+```typescript
+import { Properties } from '@dxtmisha/scripts'
+
+const engine = new Properties()
+const tokens = engine.get() // Trả về PropertiesItems đã được xử lý đầy đủ
+```
+
+## Các phương thức
+
+### Truy cập dữ liệu
+
+- `get(): PropertiesItems` — Trả về container cốt lõi chứa tất cả các token thiết kế đã xử lý.
+- `getScss(): string` — Trả về biểu diễn SCSS đã biên dịch của bộ token hiện tại.
+
+## Các thao tác (Operations)
+
+### Quy trình xử lý Token (The Token Processing Pipeline)
+
+Khi được khởi tạo, `Properties` điều phối một luồng biến đổi đa lớp toàn diện:
+1. **Thu thập nguồn**: Nó đọc và hợp nhất dữ liệu thô từ `PropertiesSettings`, `PropertiesMain` và các tệp JSON bên ngoài.
+2. **Chuẩn hóa cơ bản**: Kích hoạt các biến đổi nền tảng:
+    - **Thay thế (Replacement)**: Phân giải các mẫu alias.
+    - **Phân giải bảng màu (Palette Resolution)**: Tiêm các giá trị bảng màu.
+    - **Sao chép & Tổng hợp thuộc tính con**: Xử lý các bản sao thuộc tính phức tạp.
+3. **Biến đổi nâng cao**: Thực thi logic cấp cao cho:
+    - **Phân giải thành phần**: Ánh xạ các thuộc tính vào các cấu trúc thành phần cụ thể.
+    - **Ánh xạ Trạng thái & Lớp (State & Class Mapping)**: Tạo siêu dữ liệu cho các trạng thái UI (hover, active) và các lớp BEM.
+    - **Tổng hợp Media & Animation**: Phân giải các điểm dừng (breakpoints) phản hồi và các token chuyển động.
+4. **Tối ưu hóa & Làm sạch**: Sắp xếp các thuộc tính, xử lý các bản trùng lặp và loại bỏ các nút trống.
+5. **Lưu trữ**: Kết quả cuối cùng được lưu vào `PropertiesCache` bằng một mã hash duy nhất dựa trên cấu hình thiết kế hiện tại.
+

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

@@ -0,0 +1,56 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesCache - Persistent Cache Orchestrator'/>
+
+# PropertiesCache Class
+
+The `PropertiesCache` class is a high-performance static utility designed to manage persistent file-based caching for the design system toolchain. It ensures that complex token transformations are only performed when necessary, significantly reducing build times for large-scale projects by tracking file dependencies and maintaining a structured cache hierarchy.
+
+## Key Features
+
+- **Dependency Tracking** — Automatically monitors source file changes and invalidates the cache if any dependency is modified.
+- **Hierarchical Storage** — Organizes cached data into a hidden `.cache` directory with specialized sub-folders for different processing steps.
+- **Incremental Builds** — Enables partial re-computation by storing intermediate transformation results.
+- **System Integrity** — Maintains a `system.json` registry to track cache timestamps and file metadata.
+- **Generic Support** — Provides full TypeScript support for type-safe retrieval of cached data structures.
+
+## Initialization
+
+As a static class, `PropertiesCache` does not require instantiation. Its methods are accessed directly.
+
+```typescript
+import { PropertiesCache } from '@dxtmisha/scripts'
+
+// Retrieve data with automatic cache management
+const data = PropertiesCache.get(
+  ['tokens', 'color'], 
+  'palette-cache', 
+  () => transformPaletteLogic()
+)
+
+// Clear all cached data
+PropertiesCache.clear()
+```
+
+## Methods
+
+### Cache Operations
+
+- `get<T>(path, name, callback, extension): T` — Retrieves data from the cache or regenerates it via the callback.
+- `read<R>(path): R | undefined` — Reads a file and registers it as a cache dependency.
+- `write<T>(name, value): void` — Saves intermediate processing results to the temporary cache.
+- `clear(): void` — Recursively deletes the entire cache directory.
+
+## Operations
+
+### The Cache Synchronization Flow
+
+`PropertiesCache` operates through a sophisticated internal lifecycle to ensure data consistency:
+1. **Request (`get`)**: When data is requested, the class first checks for the existence of the physical cache file.
+2. **System Validation**: It consults the internal `system` registry to compare the cache's creation timestamp against the modification times of all registered dependency files.
+3. **Regeneration**: If the file is missing or outdated:
+    - It pushes the current cache `name` onto an internal `listenerName` stack.
+    - Any subsequent file read via `PropertiesCache.read()` during the callback execution is automatically logged as a dependency for this specific cache entry.
+    - The callback result is written to disk.
+4. **Finalization**: After the callback completes, it updates the `system.json` with the new timestamp and dependency list, ensuring the next request remains valid unless a source file changes.
+

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

@@ -0,0 +1,56 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesCache - Оркестратор постоянного кэша'/>
+
+# Класс PropertiesCache
+
+Класс `PropertiesCache` — это высокопроизводительная статическая утилита, предназначенная для управления постоянным файловым кэшированием в инструментарии дизайн-системы. Он гарантирует, что сложные трансформации токенов выполняются только при необходимости, значительно сокращая время сборки для крупных проектов за счет отслеживания зависимостей файлов и поддержки структурированной иерархии кэша.
+
+## Ключевые особенности
+
+- **Отслеживание зависимостей** — автоматически отслеживает изменения исходных файлов и аннулирует кэш, если любая зависимость была изменена.
+- **Иерархическое хранение** — организует кэшированные данные в скрытой директории `.cache` со специализированными подпапками для различных этапов обработки.
+- **Инкрементальные сборки** — позволяет выполнять частичное перевычисление за счет хранения промежуточных результатов трансформации.
+- **Целостность системы** — ведет реестр `system.json` для отслеживания временных меток кэша и метаданных файлов.
+- **Поддержка Generic** — обеспечивает полную поддержку TypeScript для типобезопасного извлечения кэшированных структур данных.
+
+## Инициализация
+
+Являясь статическим классом, `PropertiesCache` не требует создания экземпляра. Доступ к его методам осуществляется напрямую.
+
+```typescript
+import { PropertiesCache } from '@dxtmisha/scripts'
+
+// Извлечение данных с автоматическим управлением кэшем
+const data = PropertiesCache.get(
+  ['tokens', 'color'], 
+  'palette-cache', 
+  () => transformPaletteLogic()
+)
+
+// Очистка всех кэшированных данных
+PropertiesCache.clear()
+```
+
+## Методы
+
+### Операции с кэшем
+
+- `get<T>(path, name, callback, extension): T` — извлекает данные из кэша или регенерирует их через функцию обратного вызова.
+- `read<R>(path): R | undefined` — читает файл и регистрирует его как зависимость кэша.
+- `write<T>(name, value): void` — сохраняет промежуточные результаты обработки во временный кэш.
+- `clear(): void` — рекурсивно удаляет всю директорию кэша.
+
+## Операции
+
+### Поток синхронизации кэша
+
+`PropertiesCache` работает через сложный внутренний жизненный цикл для обеспечения согласованности данных:
+1. **Запрос (`get`)**: При запросе данных класс сначала проверяет наличие физического файла кэша.
+2. **Системная валидация**: Он обращается к внутреннему реестру `system`, чтобы сравнить временную метку создания кэша с временем изменения всех зарегистрированных файлов зависимостей.
+3. **Регенерация**: Если файл отсутствует или устарел:
+    - Класс помещает текущее имя кэша `name` во внутренний стек `listenerName`.
+    - Любое последующее чтение файла через `PropertiesCache.read()` во время выполнения callback автоматически регистрируется как зависимость для этой конкретной записи кэша.
+    - Результат callback записывается на диск.
+4. **Завершение**: После завершения callback обновляется `system.json` с новой временной меткой и списком зависимостей, гарантируя, что следующий запрос останется валидным, пока не изменится исходный файл.
+