@dxtmisha/wiki 0.39.1 → 0.39.3

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

@@ -0,0 +1,56 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesCache - Bộ điều phối bộ nhớ đệm vĩnh viễn'/>
+
+# Lớp PropertiesCache
+
+Lớp `PropertiesCache` là một tiện ích tĩnh hiệu suất cao được thiết kế để quản lý việc lưu trữ bộ nhớ đệm (caching) dựa trên tệp vĩnh viễn cho bộ công cụ hệ thống thiết kế. Nó đảm bảo rằng các biến đổi token phức tạp chỉ được thực hiện khi cần thiết, giúp giảm đáng kể thời gian xây dựng cho các dự án quy mô lớn bằng cách theo dõi các phụ thuộc tệp và duy trì một cấu trúc phân cấp bộ nhớ đệm chặt chẽ.
+
+## Các tính năng chính
+
+- **Theo dõi phụ thuộc** — Tự động giám sát các thay đổi của tệp nguồn và vô hiệu hóa bộ nhớ đệm nếu bất kỳ phụ thuộc nào bị sửa đổi.
+- **Lưu trữ phân cấp** — Tổ chức dữ liệu đã lưu vào thư mục ẩn `.cache` với các thư mục con chuyên biệt cho các bước xử lý khác nhau.
+- **Xây dựng tăng dần** — Cho phép tính toán lại một phần bằng cách lưu trữ kết quả biến đổi trung gian.
+- **Tính toàn vẹn hệ thống** — Duy trì sổ đăng ký `system.json` để theo dõi dấu thời gian của bộ nhớ đệm và siêu dữ liệu tệp.
+- **Hỗ trợ Generic** — Cung cấp hỗ trợ TypeScript đầy đủ để truy xuất các cấu trúc dữ liệu đã lưu một cách an toàn về kiểu.
+
+## Khởi tạo
+
+Là một lớp tĩnh, `PropertiesCache` không yêu cầu khởi tạo instance. Các phương thức của nó được truy cập trực tiếp.
+
+```typescript
+import { PropertiesCache } from '@dxtmisha/scripts'
+
+// Truy xuất dữ liệu với quản lý bộ nhớ đệm tự động
+const data = PropertiesCache.get(
+  ['tokens', 'color'], 
+  'palette-cache', 
+  () => transformPaletteLogic()
+)
+
+// Xóa tất cả dữ liệu đã lưu
+PropertiesCache.clear()
+```
+
+## Các phương thức
+
+### Các thao tác bộ nhớ đệm
+
+- `get<T>(path, name, callback, extension): T` — Truy xuất dữ liệu từ bộ nhớ đệm hoặc tạo lại dữ liệu đó thông qua hàm callback.
+- `read<R>(path): R | undefined` — Đọc một tệp và đăng ký nó như một phụ thuộc của bộ nhớ đệm.
+- `write<T>(name, value): void` — Lưu kết quả xử lý trung gian vào bộ nhớ đệm tạm thời.
+- `clear(): void` — Xóa đệ quy toàn bộ thư mục bộ nhớ đệm.
+
+## Các thao tác (Operations)
+
+### Luồng đồng bộ hóa bộ nhớ đệm (The Cache Synchronization Flow)
+
+`PropertiesCache` hoạt động thông qua một vòng đời nội bộ tinh vi để đảm bảo tính nhất quán của dữ liệu:
+1. **Yêu cầu (`get`)**: Khi dữ liệu được yêu cầu, lớp trước tiên sẽ kiểm tra sự tồn tại của tệp bộ nhớ đệm vật lý.
+2. **Xác thực hệ thống**: Nó tham khảo sổ đăng ký `system` nội bộ để so sánh dấu thời gian tạo của bộ nhớ đệm với thời gian sửa đổi của tất cả các tệp phụ thuộc đã đăng ký.
+3. **Tạo lại**: Nếu tệp bị thiếu hoặc lỗi thời:
+    - Nó đẩy `name` bộ nhớ đệm hiện tại vào một ngăn xếp `listenerName` nội bộ.
+    - Bất kỳ lần đọc tệp tiếp theo nào thông qua `PropertiesCache.read()` trong khi thực thi callback sẽ tự động được ghi lại như một phụ thuộc cho mục bộ nhớ đệm cụ thể này.
+    - Kết quả callback được ghi vào đĩa.
+4. **Hoàn tất**: Sau khi callback hoàn tất, nó cập nhật `system.json` với dấu thời gian và danh sách phụ thuộc mới, đảm bảo yêu cầu tiếp theo vẫn hợp lệ trừ khi tệp nguồn thay đổi.
+

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

@@ -0,0 +1,56 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesConfig - Global Configuration Orchestrator'/>
+
+# PropertiesConfig Class
+
+The `PropertiesConfig` class is a centralized static utility responsible for managing the design system's operational parameters. It handles the discovery and recursive merging of `design-ui.json` configuration files, providing a consistent API for accessing naming conventions, AI integration keys, and documentation routing rules across the entire library.
+
+## Key Features
+
+- **Recursive Extension** — Supports an `extends` mechanism, allowing configurations to inherit and override settings from parent directories.
+- **Auto-Discovery** — Searches up the directory tree to find the nearest `design-ui.json` entry point.
+- **Centralized Settings** — Provides unified access to project identifiers, design names, and path separators.
+- **AI Integration** — Manages credentials and model parameters for AI-driven documentation and code generation.
+- **Documentation Routing** — Configures target directories and Storybook paths for the automated wiki system.
+
+## Initialization
+
+As a static class, `PropertiesConfig` initializes itself automatically upon the first import. You don't need to call a constructor.
+
+```typescript
+import { PropertiesConfig } from '@dxtmisha/scripts'
+
+// Access global settings
+const designName = PropertiesConfig.getDesignName()
+const separator = PropertiesConfig.getSeparator()
+```
+
+## Methods
+
+### General Configuration
+
+- `getProjectName(): string` — Retrieves the project's root identifier.
+- `getDesignName(): string` — Returns the primary design system identifier.
+- `getDesignAlternativeName(): string[]` — Returns alternative aliases for the design.
+- `getSeparator(): string` — Returns the path separator used in token definitions.
+- `getWikiLanguage(): string` — Returns the target language code for documentation.
+
+### AI & Documentation
+
+- `getAiType(): AiType` — Returns the configured AI provider (e.g., 'gemini').
+- `getAiModel(): string` — Returns the specific AI model name.
+- `getAiDocDirectory(): string[]` — Returns directories targeted for doc generation.
+- `getAiDocStorybookPath(): string` — Returns the export destination for Storybook MDX files.
+
+## Operations
+
+### The Configuration Resolution Flow
+
+`PropertiesConfig` uses a robust strategy to resolve system settings:
+1. **File Discovery**: Upon loading, it attempts to find `design-ui.json` by traversing upwards from the current working directory (up to 32 levels).
+2. **Recursive Merging**: If the discovered file contains an `extends` property:
+    - It recursively loads the referenced parent configuration.
+    - It intelligently merges settings, where local properties override inherited ones.
+3. **Static Availability**: The final merged configuration is stored in a private static field, making all settings immediately available through public getters.
+

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

@@ -0,0 +1,56 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesConfig - Оркестратор глобальной конфигурации'/>
+
+# Класс PropertiesConfig
+
+Класс `PropertiesConfig` — это централизованная статическая утилита, отвечающая за управление рабочими параметрами дизайн-системы. Он управляет поиском и рекурсивным слиянием файлов конфигурации `design-ui.json`, предоставляя единый API для доступа к соглашениям об именовании, ключам интеграции ИИ и правилам маршрутизации документации во всей библиотеке.
+
+## Ключевые особенности
+
+- **Рекурсивное расширение** — поддерживает механизм `extends`, позволяя конфигурациям наследовать и переопределять настройки из родительских директорий.
+- **Автоматическое обнаружение** — выполняет поиск вверх по дереву каталогов для нахождения ближайшей точки входа `design-ui.json`.
+- **Централизованные настройки** — обеспечивает унифицированный доступ к идентификаторам проекта, названиям дизайна и разделителям путей.
+- **Интеграция с ИИ** — управляет учетными данными и параметрами моделей для генерации документации и кода на базе ИИ.
+- **Маршрутизация документации** — настраивает целевые директории и пути Storybook для автоматизированной системы вики.
+
+## Инициализация
+
+Являясь статическим классом, `PropertiesConfig` инициализируется автоматически при первом импорте. Вам не нужно вызывать конструктор.
+
+```typescript
+import { PropertiesConfig } from '@dxtmisha/scripts'
+
+// Доступ к глобальным настройкам
+const designName = PropertiesConfig.getDesignName()
+const separator = PropertiesConfig.getSeparator()
+```
+
+## Методы
+
+### Общая конфигурация
+
+- `getProjectName(): string` — получает корневой идентификатор проекта.
+- `getDesignName(): string` — возвращает основной идентификатор дизайн-системы.
+- `getDesignAlternativeName(): string[]` — возвращает альтернативные алиасы для дизайна.
+- `getSeparator(): string` — возвращает символ-разделитель путей в токенах.
+- `getWikiLanguage(): string` — возвращает код целевого языка для документации.
+
+### ИИ и Документация
+
+- `getAiType(): AiType` — возвращает настроенного ИИ-провайдера (например, 'gemini').
+- `getAiModel(): string` — возвращает название конкретной модели ИИ.
+- `getAiDocDirectory(): string[]` — возвращает директории, предназначенные для генерации документации.
+- `getAiDocStorybookPath(): string` — возвращает путь экспорта для MDX-файлов Storybook.
+
+## Операции
+
+### Поток разрешения конфигурации
+
+`PropertiesConfig` использует надежную стратегию для разрешения системных настроек:
+1. **Поиск файла**: При загрузке класс пытается найти `design-ui.json`, поднимаясь вверх от текущей рабочей директории (до 32 уровней).
+2. **Рекурсивное слияние**: Если найденный файл содержит свойство `extends`:
+    - Он рекурсивно загружает указанную родительскую конфигурацию.
+    - Интеллектуально объединяет настройки, где локальные свойства переопределяют унаследованные.
+3. **Статическая готовность**: Итоговая объединенная конфигурация сохраняется в приватном статическом поле, делая все настройки немедленно доступными через публичные геттеры.
+

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

@@ -0,0 +1,56 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesConfig - Bộ điều phối cấu hình toàn cầu'/>
+
+# Lớp PropertiesConfig
+
+Lớp `PropertiesConfig` là một tiện ích tĩnh tập trung chịu trách nhiệm quản lý các tham số vận hành của hệ thống thiết kế. Nó xử lý việc khám phá và hợp nhất đệ quy các tệp cấu hình `design-ui.json`, cung cấp một API nhất quán để truy cập các quy ước đặt tên, khóa tích hợp AI và các quy tắc định tuyến tài liệu trên toàn bộ thư viện.
+
+## Các tính năng chính
+
+- **Mở rộng đệ quy** — Hỗ trợ cơ chế `extends`, cho phép các cấu hình kế thừa và ghi đè các cài đặt từ các thư mục cha.
+- **Tự động khám phá** — Tìm kiếm ngược lên cây thư mục để tìm điểm nhập `design-ui.json` gần nhất.
+- **Cài đặt tập trung** — Cung cấp quyền truy cập thống nhất vào các định danh dự án, tên thiết kế và các ký tự phân tách đường dẫn.
+- **Tích hợp AI** — Quản lý thông tin xác thực và các tham số mô hình cho việc tạo tài liệu và mã nguồn bằng AI.
+- **Định tuyến tài liệu** — Cấu hình các thư mục đích và đường dẫn Storybook cho hệ thống wiki tự động.
+
+## Khởi tạo
+
+Là một lớp tĩnh, `PropertiesConfig` tự động khởi tạo khi được import lần đầu tiên. Bạn không cần phải gọi hàm khởi tạo.
+
+```typescript
+import { PropertiesConfig } from '@dxtmisha/scripts'
+
+// Truy cập các cài đặt toàn cầu
+const designName = PropertiesConfig.getDesignName()
+const separator = PropertiesConfig.getSeparator()
+```
+
+## Các phương thức
+
+### Cấu hình chung
+
+- `getProjectName(): string` — Truy xuất định danh gốc của dự án.
+- `getDesignName(): string` — Trả về định danh chính của hệ thống thiết kế.
+- `getDesignAlternativeName(): string[]` — Trả về các alias thay thế cho thiết kế.
+- `getSeparator(): string` — Trả về ký tự phân tách đường dẫn được sử dụng trong các token.
+- `getWikiLanguage(): string` — Trả về mã ngôn ngữ đích cho tài liệu.
+
+### AI & Tài liệu
+
+- `getAiType(): AiType` — Trả về nhà cung cấp AI đã cấu hình (ví dụ: 'gemini').
+- `getAiModel(): string` — Trả về tên mô hình AI cụ thể.
+- `getAiDocDirectory(): string[]` — Trả về các thư mục mục tiêu để tạo tài liệu.
+- `getAiDocStorybookPath(): string` — Trả về đích xuất cho các tệp MDX của Storybook.
+
+## Các thao tác (Operations)
+
+### Luồng phân giải cấu hình (The Configuration Resolution Flow)
+
+`PropertiesConfig` sử dụng một chiến lược mạnh mẽ để phân giải các cài đặt hệ thống:
+1. **Khám phá tệp**: Khi tải, nó cố gắng tìm `design-ui.json` bằng cách duyệt ngược lên từ thư mục làm việc hiện tại (tối đa 32 cấp).
+2. **Hợp nhất đệ quy**: Nếu tệp được tìm thấy có chứa thuộc tính `extends`:
+    - Nó tải đệ quy cấu hình cha được tham chiếu.
+    - Nó hợp nhất các cài đặt một cách thông minh, trong đó các thuộc tính cục bộ ghi đè các thuộc tính kế thừa.
+3. **Tính sẵn sàng tĩnh**: Cấu hình hợp nhất cuối cùng được lưu trữ trong một trường tĩnh riêng tư, giúp tất cả các cài đặt có sẵn ngay lập tức thông qua các getter công khai.
+

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

@@ -0,0 +1,43 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesConvector - Semantic Token Transformer'/>
+
+# PropertiesConvector Class
+
+The `PropertiesConvector` class is a specialized static utility designed to handle complex semantic transformations of design tokens. It acts as a dispatcher for the token processing engine, identifying specific property types (like colors, shadows, or typography) and applying specialized conversion logic to Ensure raw data is normalized into usable design system structures.
+
+## Key Features
+
+- **Semantic Dispatching** — Automatically routes tokens to specialized convectors based on their `type` metadata.
+- **Recursive Traversal** — Deeply traverses nested property objects to ensure all child tokens are processed.
+- **Specialized Converters** — Integrates dedicated logic for `color`, `boxShadow`, `fontFamilies`, and `typography`.
+- **In-Place Transformation** — Modifies property objects directly to maintain structural integrity during the build process.
+
+## Initialization
+
+As a static utility class, `PropertiesConvector` does not require instantiation. Its primary function is accessed directly.
+
+```typescript
+import { PropertiesConvector } from '@dxtmisha/scripts'
+
+// Transform a set of raw properties
+PropertiesConvector.to(rawProperties)
+```
+
+## Methods
+
+### Transformation
+
+- `to(properties): void` — Recursively processes a property list, applying type-specific transformations to each item.
+
+## Operations
+
+### The Conversion Dispatch Flow
+
+`PropertiesConvector` manages the transformation lifecycle through a recursive matching strategy:
+1. **Type Detection**: For each item in the provided property cluster, it checks if a corresponding convector exists in its internal registry (e.g., matching `color` to `convectorColor`).
+2. **Specialized Execution**: If a match is found, the specific convector logic is executed on the item, transforming its raw values into finalized formats.
+3. **Recursive Branching**:
+    - If the item has a `value` that is an object, it recursively calls `to()` on that object.
+    - If the item itself is an object without a recognized type, it continues the traversal to find nested tokens.
+4. **Data Integrity**: The process ensures that complex structures (like typography maps or multi-layered shadows) are fully resolved before the next stage of the pipeline.

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

@@ -0,0 +1,43 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesConvector - Трансформер семантических токенов'/>
+
+# Класс PropertiesConvector
+
+Класс `PropertiesConvector` — это специализированная статическая утилита, предназначенная для выполнения сложных семантических преобразований токенов дизайна. Он выступает в роли диспетчера для движка обработки токенов, определяя специфические типы свойств (такие как цвета, тени или типографика) и применяя специализированную логику преобразования для нормализации необработанных данных в пригодные для использования структуры дизайн-системы.
+
+## Ключевые особенности
+
+- **Семантическая диспетчеризация** — автоматически направляет токены в специализированные конвертеры на основе метаданных их `type`.
+- **Рекурсивный обход** — глубоко обходит вложенные объекты свойств, гарантируя обработку всех дочерних токенов.
+- **Специализированные конвертеры** — интегрирует выделенную логику для `color`, `boxShadow`, `fontFamilies` и `typography`.
+- **Преобразование «на месте»** — напрямую модифицирует объекты свойств для сохранения структурной целостности в процессе сборки.
+
+## Инициализация
+
+Являясь статической утилитой, `PropertiesConvector` не требует создания экземпляра. Доступ к его основной функции осуществляется напрямую.
+
+```typescript
+import { PropertiesConvector } from '@dxtmisha/scripts'
+
+// Преобразование набора необработанных свойств
+PropertiesConvector.to(rawProperties)
+```
+
+## Методы
+
+### Трансформация
+
+- `to(properties): void` — рекурсивно обрабатывает список свойств, применяя специфические для типа преобразования к каждому элементу.
+
+## Операции
+
+### Поток диспетчеризации преобразования
+
+`PropertiesConvector` управляет жизненным циклом трансформации через стратегию рекурсивного сопоставления:
+1. **Определение типа**: Для каждого элемента в предоставленном кластере свойств класс проверяет наличие соответствующего конвертера во внутреннем реестре (например, сопоставление `color` с `convectorColor`).
+2. **Специализированное выполнение**: Если совпадение найдено, на элементе выполняется логика конкретного конвертера, преобразующая необработанные значения в финальные форматы.
+3. **Рекурсивное ветвление**:
+    - Если у элемента есть `value`, являющееся объектом, класс рекурсивно вызывает `to()` для этого объекта.
+    - Если сам элемент является объектом без распознанного типа, он продолжает обход для поиска вложенных токенов.
+4. **Целостность данных**: Процесс гарантирует, что сложные структуры (такие как карты типографики или многослойные тени) будут полностью разрешены перед следующим этапом конвейера.

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

@@ -0,0 +1,43 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesConvector - Bộ chuyển đổi Token ngữ nghĩa'/>
+
+# Lớp PropertiesConvector
+
+Lớp `PropertiesConvector` là một tiện ích tĩnh chuyên biệt được thiết kế để xử lý các phép biến đổi ngữ nghĩa phức tạp của các token thiết kế. Nó đóng vai trò như một bộ điều phối cho động cơ xử lý token, xác định các loại thuộc tính cụ thể (như màu sắc, bóng đổ hoặc kiểu chữ) và áp dụng logic chuyển đổi chuyên biệt để đảm bảo dữ liệu thô được chuẩn hóa thành các cấu trúc hệ thống thiết kế có thể sử dụng được.
+
+## Các tính năng chính
+
+- **Điều phối ngữ nghĩa** — Tự động định tuyến các token đến các bộ chuyển đổi chuyên biệt dựa trên siêu dữ liệu `type` của chúng.
+- **Duyệt đệ quy** — Duyệt sâu qua các đối tượng thuộc tính lồng nhau để đảm bảo tất cả các token con đều được xử lý.
+- **Bộ chuyển đổi chuyên biệt** — Tích hợp logic dành riêng cho `color`, `boxShadow`, `fontFamilies` và `typography`.
+- **Biến đổi tại chỗ (In-Place)** — Sửa đổi trực tiếp các đối tượng thuộc tính để duy trì tính toàn vẹn của cấu trúc trong quá trình xây dựng.
+
+## Khởi tạo
+
+Là một lớp tiện ích tĩnh, `PropertiesConvector` không yêu cầu khởi tạo instance. Chức năng chính của nó được truy cập trực tiếp.
+
+```typescript
+import { PropertiesConvector } from '@dxtmisha/scripts'
+
+// Biến đổi một tập hợp các thuộc tính thô
+PropertiesConvector.to(rawProperties)
+```
+
+## Các phương thức
+
+### Biến đổi
+
+- `to(properties): void` — Xử lý đệ quy danh sách thuộc tính, áp dụng các phép biến đổi cụ thể theo loại cho từng mục.
+
+## Các thao tác (Operations)
+
+### Luồng điều phối chuyển đổi (The Conversion Dispatch Flow)
+
+`PropertiesConvector` quản lý vòng đời biến đổi thông qua chiến lược khớp đệ quy:
+1. **Phát hiện loại**: Đối với mỗi mục trong cụm thuộc tính được cung cấp, nó kiểm tra xem một bộ chuyển đổi tương ứng có tồn tại trong sổ đăng ký nội bộ hay không (ví dụ: khớp `color` với `convectorColor`).
+2. **Thực thi chuyên biệt**: Nếu tìm thấy kết quả khớp, logic bộ chuyển đổi cụ thể sẽ được thực thi trên mục đó, biến đổi các giá trị thô của nó thành các định dạng cuối cùng.
+3. **Phân nhánh đệ quy**:
+    - Nếu mục có `value` là một đối tượng, nó sẽ gọi đệ quy `to()` trên đối tượng đó.
+    - Nếu bản thân mục đó là một đối tượng không có loại được công nhận, nó sẽ tiếp tục duyệt để tìm các token lồng nhau.
+4. **Tính toàn vẹn dữ liệu**: Quy trình đảm bảo rằng các cấu trúc phức tạp (như bản đồ kiểu chữ hoặc các lớp bóng đổ đa tầng) được phân giải hoàn toàn trước giai đoạn tiếp theo của quy trình.