@dxtmisha/wiki 0.39.1 → 0.39.3

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

@@ -0,0 +1,93 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesSeparator - Разделение свойств'/>
+
+# Класс PropertiesSeparator
+
+Класс `PropertiesSeparator` предназначен для автоматического преобразования плоской структуры токенов с составными именами (использующими разделители) в иерархическую структуру вложенных объектов. Это позволяет организовывать свойства логически, например, превращая `button.primary.background` в `{ button: { primary: { background: ... } } }`.
+
+## Ключевые особенности
+
+- **Автоматическая вложенность** — преобразует плоские ключи с разделителями (по умолчанию `.`) во вложенные объекты.
+- **Рекурсивная обработка** — поддерживает неограниченную глубину вложенности (с возможностью ограничения через конфигурацию).
+- **Умное слияние** — корректно объединяет новые под-свойства с уже существующими объектами, используя рекурсивное замещение.
+- **Очистка имен** — автоматически удаляет технические префиксы и суффиксы (например, базовые имена разделителей) перед обработкой.
+
+## Инициализация
+
+Класс предоставляет статические методы, поэтому его не нужно инициализировать через `new`.
+
+```typescript
+import { PropertiesSeparator } from '@dxtmisha/scripts'
+
+// Использование статических методов
+const results = PropertiesSeparator.to(rawProperties)
+```
+
+## Методы
+
+### `is`
+Статический метод для быстрой проверки, содержит ли предоставленный список свойств ключи, требующие разделения. Он сканирует верхний уровень (и вложенные уровни до предела `limit`) на наличие символов-разделителей в именах.
+
+**Параметры:**
+- `properties: PropertyList` — список свойств для анализа.
+- `limit: number` — максимальная глубина проверки (по умолчанию берется из `PropertiesConfig`).
+
+**Возвращает:** `boolean` — `true`, если хотя бы один ключ содержит разделитель.
+
+```typescript
+const needsSplitting = PropertiesSeparator.is(myProperties);
+// Результат: true, если есть ключи типа "color.blue.50"
+```
+
+### `to`
+Статический метод, который выполняет фактическую трансформацию плоского списка свойств во вложенную структуру. Метод рекурсивно обходит все элементы и, если находит ключ с разделителем, «оборачивает» свойство в цепочку вложенных объектов согласно сегментам имени.
+
+**Параметры:**
+- `properties: PropertyList` — список свойств для трансформации.
+
+**Возвращает:** `PropertyList` — новый список свойств с иерархической структурой.
+
+```typescript
+const nestedProperties = PropertiesSeparator.to({
+  'palette.blue.50': { value: '#e3f2fd' }
+});
+/* Результат:
+{
+  palette: {
+    value: {
+      blue: {
+        value: {
+          '50': { value: '#e3f2fd', __wrap: true }
+        }
+      }
+    }
+  }
+}
+*/
+```
+
+## Операции
+
+### Механизм разделения имен
+
+Процесс трансформации в `PropertiesSeparator` проходит следующие этапы:
+1. **Обнаружение разделителя**: Метод `to` проверяет имя каждого свойства через `PropertiesKeys.isSeparator`.
+2. **Сегментация**: Если разделитель найден, имя разбивается на части (например, `a.b.c` -> `['a', 'b', 'c']`). Перед этим удаляются лишние технические символы через `removeBasicName`.
+3. **Обертывание (Wrapping)**: Метод `wrap` рекурсивно создает вложенные объекты `value`, помещая оригинальный элемент свойства в самый глубокий уровень. При этом промежуточным объектам добавляется флаг `__wrap: true`, указывающий на их служебный характер.
+4. **Рекурсивное слияние**: Полученная «ветка» объединяется с основным объектом `data` через `replaceRecursive`, что позволяет нескольким свойствам с одной базой (например, `blue.50` и `blue.100`) корректно собраться в одном объекте `blue`.
+
+## Примеры
+
+### Группировка цветов палитры
+```typescript
+import { PropertiesSeparator } from '@dxtmisha/scripts'
+
+const flatPalette = {
+  'blue.50': { value: '#eef' },
+  'blue.100': { value: '#ccf' }
+}
+
+const tree = PropertiesSeparator.to(flatPalette)
+// Свойства теперь сгруппированы в объекте tree.blue.value
+```

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

@@ -0,0 +1,93 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesSeparator - Phân tách thuộc tính'/>
+
+# Lớp PropertiesSeparator
+
+Lớp `PropertiesSeparator` được thiết kế để tự động chuyển đổi cấu trúc phẳng của các token có tên phức hợp (sử dụng dấu phân cách) thành cấu trúc phân cấp của các đối tượng lồng nhau. Điều này cho phép tổ chức thuộc tính một cách logic, ví dụ: biến `button.primary.background` thành `{ button: { primary: { background: ... } } }`.
+
+## Các tính năng chính
+
+- **Lồng ghép tự động** — chuyển đổi các khóa phẳng với dấu phân cách (mặc định là `.`) thành các đối tượng lồng nhau.
+- **Xử lý đệ quy** — hỗ trợ độ sâu lồng nhau không giới hạn (với khả năng giới hạn thông qua cấu hình).
+- **Hợp nhất thông minh** — hợp nhất chính xác các thuộc tính con mới với các đối tượng hiện có bằng cách thay thế đệ quy.
+- **Làm sạch tên** — tự động loại bỏ các tiền tố và hậu tố kỹ thuật (ví dụ: tên cơ bản của dấu phân cách) trước khi xử lý.
+
+## Khởi tạo
+
+Lớp này cung cấp các phương thức tĩnh, vì vậy không cần phải khởi tạo thông qua `new`.
+
+```typescript
+import { PropertiesSeparator } from '@dxtmisha/scripts'
+
+// Sử dụng các phương thức tĩnh
+const results = PropertiesSeparator.to(rawProperties)
+```
+
+## Các phương thức
+
+### `is`
+Một phương thức tĩnh để kiểm tra nhanh xem danh sách thuộc tính được cung cấp có chứa bất kỳ khóa nào yêu cầu phân tách hay không. Nó quét cấp độ cao nhất (và các cấp độ lồng nhau lên đến giới hạn `limit`) để tìm các ký tự phân cách trong tên.
+
+**Tham số:**
+- `properties: PropertyList` — danh sách các thuộc tính cần phân tích.
+- `limit: number` — độ sâu tối đa của việc kiểm tra (mặc định được lấy từ `PropertiesConfig`).
+
+**Trả về:** `boolean` — `true` nếu có ít nhất một khóa chứa dấu phân cách.
+
+```typescript
+const needsSplitting = PropertiesSeparator.is(myProperties);
+// Kết quả: true nếu tồn tại các khóa như "color.blue.50"
+```
+
+### `to`
+Một phương thức tĩnh thực hiện quá trình chuyển đổi thực tế từ danh sách thuộc tính phẳng thành cấu trúc lồng nhau. Phương thức lặp lại đệ quy qua tất cả các phần tử và nếu tìm thấy một khóa có dấu phân cách, nó sẽ "bao bọc" thuộc tính vào một chuỗi các đối tượng lồng nhau theo các phân đoạn tên.
+
+**Tham số:**
+- `properties: PropertyList` — danh sách các thuộc tính cần chuyển đổi.
+
+**Trả về:** `PropertyList` — một danh sách thuộc tính mới với cấu trúc phân cấp.
+
+```typescript
+const nestedProperties = PropertiesSeparator.to({
+  'palette.blue.50': { value: '#e3f2fd' }
+});
+/* Kết quả:
+{
+  palette: {
+    value: {
+      blue: {
+        value: {
+          '50': { value: '#e3f2fd', __wrap: true }
+        }
+      }
+    }
+  }
+}
+*/
+```
+
+## Các thao tác (Operations)
+
+### Cơ chế phân tách tên (The Name Splitting Mechanism)
+
+Quá trình chuyển đổi trong `PropertiesSeparator` bao gồm các bước sau:
+1. **Phát hiện dấu phân cách**: Phương thức `to` kiểm tra từng tên thuộc tính thông qua `PropertiesKeys.isSeparator`.
+2. **Phân đoạn**: Nếu tìm thấy dấu phân cách, tên sẽ được chia thành các phần (ví dụ: `a.b.c` -> `['a', 'b', 'c']`). Các ký tự kỹ thuật sẽ được loại bỏ trước đó thông qua `removeBasicName`.
+3. **Bao bọc (Wrapping)**: Phương thức `wrap` tạo đệ quy các đối tượng `value` lồng nhau, đặt phần tử thuộc tính ban đầu ở cấp sâu nhất. Các đối tượng trung gian được đánh dấu bằng `__wrap: true` để chỉ định bản chất cấu trúc của chúng.
+4. **Hợp nhất đệ quy**: "Nhánh" kết quả được hợp nhất với đối tượng `data` chính thông qua `replaceRecursive`, cho phép nhiều thuộc tính có cùng gốc (ví dụ: `blue.50` và `blue.100`) tập hợp chính xác dưới một đối tượng `blue` duy nhất.
+
+## Ví dụ (Examples)
+
+### Nhóm các màu sắc bảng màu (Palette)
+```typescript
+import { PropertiesSeparator } from '@dxtmisha/scripts'
+
+const flatPalette = {
+  'blue.50': { value: '#eef' },
+  'blue.100': { value: '#ccf' }
+}
+
+const tree = PropertiesSeparator.to(flatPalette)
+// Các thuộc tính hiện được nhóm trong đối tượng tree.blue.value
+```

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

@@ -0,0 +1,63 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesSettings - Component Settings'/>
+
+# PropertiesSettings Class
+
+The `PropertiesSettings` class is responsible for automatically searching for and loading component configuration files (settings) across all active designs. It scans specialized `settings` directories and merges the identified tokens into a unified registry, which is then used for stylesheet generation and typing.
+
+## Key Features
+
+- **Automated Scanning** — independently discovers all component folders within `components` and `constructor` paths.
+- **Multi-Design Support** — loads settings for each design separately and combines them contextually.
+- **Constructor Integration** — includes specialized logic for collecting component constructor properties (`dxt.constructor`).
+- **Standardization** — automatically transforms raw data from settings files into a standardized property format via `PropertiesStandard`.
+
+## Initialization
+
+To initialize the settings resolver, pass a `PropertiesPath` instance to the constructor.
+
+**Parameters:**
+- `path: PropertiesPath` — the object for working with design system paths.
+
+```typescript
+import { PropertiesPath, PropertiesSettings } from '@dxtmisha/scripts'
+
+const pathHandler = new PropertiesPath()
+const settings = new PropertiesSettings(pathHandler)
+```
+
+## Methods
+
+### `get`
+Returns a unified list of all settings properties found in the system. This includes both the individual component settings for each design and the shared component constructor properties.
+
+**Returns:** `PropertyList` — an object containing all loaded and standardized settings.
+
+```typescript
+const allSettings = settings.get();
+// Result: { basic: { button: { ... } }, 'dxt.constructor': { ... } }
+```
+
+## Operations
+
+### The Settings Collection Process
+
+`PropertiesSettings` performs its data search in several stages:
+1. **Path Determination**: The class retrieves the current paths to `settings` directories for each design via the path manager.
+2. **Directory Scanning**: For each identified path, all subdirectories (component names) are scanned.
+3. **File Reading**: Within each component folder, a token file (settings) is searched for and read via `PropertiesFile`.
+4. **Normalization**: The retrieved data is processed through `PropertiesStandard` to bring it into a uniform format (`PropertyItem`), including converting names to kebab-case.
+5. **Constructor Generation**: Simultaneously, `getConstructorProperties()` is called, which forms meta-data for the component constructor based on the list of identified folders.
+
+## Examples
+
+### Collecting All System Settings
+```typescript
+import { PropertiesSettings, PropertiesPath } from '@dxtmisha/scripts'
+
+const settingsManager = new PropertiesSettings(new PropertiesPath())
+const config = settingsManager.get()
+
+// config now contains all component variables for all themes
+```

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

@@ -0,0 +1,63 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesSettings - Настройки компонентов'/>
+
+# Класс PropertiesSettings
+
+Класс `PropertiesSettings` отвечает за автоматический поиск и загрузку конфигурационных файлов компонентов (настроек) во всех активных дизайнах. Он сканирует специальные директории `settings` и объединяет найденные токены в единый реестр, который затем используется для генерации стилей и типизации.
+
+## Ключевые особенности
+
+- **Автоматическое сканирование** — самостоятельно находит все папки компонентов в путях `components` и `constructor`.
+- **Мульти-дизайнерская поддержка** — загружает настройки для каждого дизайна отдельно и объединяет их с учетом контекста.
+- **Интеграция с конструктором** — содержит специальную логику для сбора свойств конструктора компонентов (`dxt.constructor`).
+- **Стандартизация** — автоматически преобразует сырые данные из файлов настроек в стандартизированный формат свойств через `PropertiesStandard`.
+
+## Инициализация
+
+Для инициализации передайте экземпляр `PropertiesPath` в конструктор.
+
+**Параметры:**
+- `path: PropertiesPath` — объект для работы с путями дизайн-системы.
+
+```typescript
+import { PropertiesPath, PropertiesSettings } from '@dxtmisha/scripts'
+
+const pathHandler = new PropertiesPath()
+const settings = new PropertiesSettings(pathHandler)
+```
+
+## Методы
+
+### `get`
+Возвращает объединенный список всех свойств настроек, найденных в системе. Сюда входят как индивидуальные настройки компонентов каждого дизайна, так и общие свойства конструктора компонентов.
+
+**Возвращает:** `PropertyList` — объект, содержащий все загруженные и стандартизированные настройки.
+
+```typescript
+const allSettings = settings.get();
+// Результат: { basic: { button: { ... } }, 'dxt.constructor': { ... } }
+```
+
+## Операции
+
+### Процесс сбора настроек
+
+`PropertiesSettings` выполняет поиск данных в несколько этапов:
+1. **Определение путей**: Класс получает актуальные пути к директориям `settings` для каждого дизайна через менеджер путей.
+2. **Сканирование директорий**: Для каждого найденного пути сканируются все поддиректории (имена компонентов).
+3. **Чтение файлов**: Внутри каждой папки компонента ищется файл с токенами (настройками), который считывается через `PropertiesFile`.
+4. **Нормализация**: Полученные данные проходят через `PropertiesStandard` для приведения их к единому формату (`PropertyItem`), включая преобразование имен в kebab-case.
+5. **Генерация конструктора**: Параллельно вызывается `getConstructorProperties()`, которая на основе списка найденных папок формирует мета-данные для конструктора компонентов.
+
+## Примеры
+
+### Сбор всех настроек системы
+```typescript
+import { PropertiesSettings, PropertiesPath } from '@dxtmisha/scripts'
+
+const settingsManager = new PropertiesSettings(new PropertiesPath())
+const config = settingsManager.get()
+
+// Теперь config содержит все переменные компонентов для всех тем
+```

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

@@ -0,0 +1,63 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesSettings - Cài đặt thành phần'/>
+
+# Lớp PropertiesSettings
+
+Lớp `PropertiesSettings` chịu trách nhiệm tự động tìm kiếm và tải các tệp cấu hình thành phần (settings) trên tất cả các thiết kế đang hoạt động. Nó quét các thư mục `settings` chuyên biệt và hợp nhất các token tìm thấy vào một kho lưu trữ thống nhất, sau đó được sử dụng để tạo bảng kiểu và định kiểu.
+
+## Các tính năng chính
+
+- **Quét tự động** — tự động phát hiện tất cả các thư mục thành phần trong đường dẫn `components` và `constructor`.
+- **Hỗ trợ đa thiết kế** — tải cài đặt cho từng thiết kế riêng biệt và kết hợp chúng theo ngữ cảnh.
+- **Tích hợp Constructor** — bao gồm logic chuyên biệt để thu thập các thuộc tính trình xây dựng thành phần (`dxt.constructor`).
+- **Chuẩn hóa** — tự động chuyển đổi dữ liệu thô từ các tệp cài đặt thành định dạng thuộc tính tiêu chuẩn thông qua `PropertiesStandard`.
+
+## Khởi tạo
+
+Để khởi tạo bộ giải quyết cài đặt, hãy truyền một thực thể `PropertiesPath` vào hàm khởi tạo.
+
+**Tham số:**
+- `path: PropertiesPath` — đối tượng làm việc với các đường dẫn của hệ thống thiết kế.
+
+```typescript
+import { PropertiesPath, PropertiesSettings } from '@dxtmisha/scripts'
+
+const pathHandler = new PropertiesPath()
+const settings = new PropertiesSettings(pathHandler)
+```
+
+## Các phương thức
+
+### `get`
+Trả về một danh sách thống nhất của tất cả các thuộc tính cài đặt được tìm thấy trong hệ thống. Điều này bao gồm cả các cài đặt thành phần riêng lẻ cho từng thiết kế và các thuộc tính trình xây dựng thành phần chung.
+
+**Trả về:** `PropertyList` — một đối tượng chứa tất cả các cài đặt đã được tải và chuẩn hóa.
+
+```typescript
+const allSettings = settings.get();
+// Kết quả: { basic: { button: { ... } }, 'dxt.constructor': { ... } }
+```
+
+## Các thao tác (Operations)
+
+### Quy trình thu thập cài đặt
+
+`PropertiesSettings` thực hiện tìm kiếm dữ liệu qua nhiều giai đoạn:
+1. **Xác định đường dẫn**: Lớp lấy các đường dẫn hiện tại đến các thư mục `settings` cho từng thiết kế thông qua bộ quản lý đường dẫn.
+2. **Quét thư mục**: Đối với mỗi đường dẫn đã xác định, tất cả các thư mục con (tên thành phần) sẽ được quét.
+3. **Đọc tệp**: Trong mỗi thư mục thành phần, một tệp token (settings) sẽ được tìm kiếm và đọc thông qua `PropertiesFile`.
+4. **Bình thường hóa**: Dữ liệu lấy được được xử lý qua `PropertiesStandard` để đưa về một định dạng thống nhất (`PropertyItem`), bao gồm cả việc chuyển đổi tên sang kebab-case.
+5. **Tạo Constructor**: Đồng thời, `getConstructorProperties()` được gọi để tạo siêu dữ liệu cho trình xây dựng thành phần dựa trên danh sách các thư mục đã xác định.
+
+## Ví dụ (Examples)
+
+### Thu thập tất cả cài đặt hệ thống
+```typescript
+import { PropertiesSettings, PropertiesPath } from '@dxtmisha/scripts'
+
+const settingsManager = new PropertiesSettings(new PropertiesPath())
+const config = settingsManager.get()
+
+// Bây giờ config chứa tất cả các biến thành phần cho tất cả các chủ đề
+```

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

@@ -0,0 +1,87 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesStandard - Property Standardization'/>
+
+# PropertiesStandard Class
+
+The `PropertiesStandard` class is the central mechanism for data normalization within the design system. Its primary task is to transform "raw" token input data (which may be represented as strings, numbers, or simplified objects) into a strictly typed `PropertyItem` structure that the rest of the system's tools can work with.
+
+## Key Features
+
+- **Data Normalization** — ensures that every property has a standardized set of fields (`value`, `type`, `index`, etc.).
+- **Recursive Processing** — automatically standardizes nested object structures.
+- **Automated Type Detection** — attempts to determine the property type based on its name (via `PropertiesTypes`).
+- **Intelligent Parsing** — distinguishes between regular values and special meta-properties (starting with `__`).
+- **Data Merging** — correctly merges new data with existing data, maintaining structural integrity.
+
+## Initialization
+
+The class provides static methods, so it does not need to be initialized via `new`.
+
+```typescript
+import { PropertiesStandard } from '@dxtmisha/scripts'
+
+// Calling a static method
+const standardized = PropertiesStandard.to(rawInput)
+```
+
+## Methods
+
+### `to`
+A static method that takes raw data or a property list and returns a fully normalized `PropertyList`. The method iterates through all elements, determines their keys, types, and values, and recursively processes nested objects.
+
+**Parameters:**
+- `properties: PropertyListOrData` — input property data in any supported format.
+
+**Returns:** `PropertyList` — an object where every element is brought to the `PropertyItem` standard.
+
+```typescript
+const result = PropertiesStandard.to({
+  'primary-color': '#007bff',
+  'padding': { value: 16, type: 'size' }
+});
+
+/* Result:
+{
+  'primary-color': { 
+    value: '#007bff', 
+    type: 'color', 
+    index: 'primary-color' 
+  },
+  'padding': { 
+    value: '16px', 
+    type: 'size', 
+    index: 'padding' 
+  }
+}
+*/
+```
+
+## Operations
+
+### The Standardization Algorithm (getItem)
+
+When processing each element, the following steps are performed:
+1. **Object Transformation**: The `toItem` method checks the input value type. If it is a string or array, it is wrapped in an `{ value: ... }` object.
+2. **Meta-data Separation**: The `getValueAndSpecial` method separates the useful `value` from special control keys (e.g., `__custom`).
+3. **Type Determination**: If the type is not explicitly specified, the `addType` method attempts to calculate it based on the key name.
+4. **Finality Check**: The `addFull` method adds `fullName` or `fullValue` markers if the data does not require further processing (e.g., for already resolved links).
+5. **Value Transformation**: Through `addValue`, all numeric values are converted to strings, adding units where necessary.
+6. **Index Registration**: Each element is assigned a cleaned `index` for quick backtracking.
+
+## Examples
+
+### Standardizing a Complex Structure
+```typescript
+import { PropertiesStandard } from '@dxtmisha/scripts'
+
+const data = {
+  header: {
+    height: 60,
+    background: '{color.white}'
+  }
+}
+
+const standardData = PropertiesStandard.to(data)
+// All fields in standardData.header.value now have the correct PropertyItem structure
+```

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

@@ -0,0 +1,87 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesStandard - Стандартизация свойств'/>
+
+# Класс PropertiesStandard
+
+Класс `PropertiesStandard` является центральным механизмом нормализации данных в дизайн-системе. Его основная задача — преобразовывать «сырые» входные данные токенов (которые могут быть представлены строками, числами или упрощенными объектами) в строго типизированную структуру `PropertyItem`, с которой могут работать остальные инструменты системы.
+
+## Ключевые особенности
+
+- **Нормализация данных** — гарантирует, что каждое свойство имеет стандартизированный набор полей (`value`, `type`, `index` и др.).
+- **Рекурсивная обработка** — автоматически стандартизирует вложенные структуры объектов.
+- **Автоматическое определение типов** — пытается определить тип свойства на основе его имени (через `PropertiesTypes`).
+- **Интеллектуальный парсинг** — различает обычные значения и специальные мета-свойства (начинающиеся с `__`).
+- **Слияние данных** — корректно объединяет новые данные с существующими, сохраняя целостность структуры.
+
+## Инициализация
+
+Класс предоставляет статические методы, поэтому его не нужно инициализировать через `new`.
+
+```typescript
+import { PropertiesStandard } from '@dxtmisha/scripts'
+
+// Вызов статического метода
+const standardized = PropertiesStandard.to(rawInput)
+```
+
+## Методы
+
+### `to`
+Статический метод, принимающий сырые данные или список свойств и возвращающий полностью нормализованный `PropertyList`. Метод выполняет обход всех элементов, определяет их ключи, типы и значения, а также рекурсивно обрабатывает вложенные объекты.
+
+**Параметры:**
+- `properties: PropertyListOrData` — входные данные свойств в любом поддерживаемом формате.
+
+**Возвращает:** `PropertyList` — объект, в котором каждый элемент приведен к стандарту `PropertyItem`.
+
+```typescript
+const result = PropertiesStandard.to({
+  'primary-color': '#007bff',
+  'padding': { value: 16, type: 'size' }
+});
+
+/* Результат:
+{
+  'primary-color': { 
+    value: '#007bff', 
+    type: 'color', 
+    index: 'primary-color' 
+  },
+  'padding': { 
+    value: '16px', 
+    type: 'size', 
+    index: 'padding' 
+  }
+}
+*/
+```
+
+## Операции
+
+### Алгоритм стандартизации (getItem)
+
+При обработке каждого элемента выполняются следующие шаги:
+1. **Преобразование в объект**: Метод `toItem` проверяет тип входного значения. Если это строка или массив, они оборачиваются в объект `{ value: ... }`.
+2. **Разделение мета-данных**: Метод `getValueAndSpecial` отделяет полезное значение (`value`) от специальных ключей управления (например, `__custom`).
+3. **Определение типа**: Если тип не указан явно, метод `addType` пытается вычислить его по имени ключа.
+4. **Проверка на финальность**: Метод `addFull` добавляет метки `fullName` или `fullValue`, если данные не требуют дальнейшей обработки (например, для уже разрешенных ссылок).
+5. **Преобразование значений**: Через `addValue` все числовые значения переводятся в строки с добавлением единиц измерения там, где это необходимо.
+6. **Регистрация индекса**: Каждому элементу присваивается очищенный `index` для быстрой обратной связи.
+
+## Примеры
+
+### Стандартизация сложной структуры
+```typescript
+import { PropertiesStandard } from '@dxtmisha/scripts'
+
+const data = {
+  header: {
+    height: 60,
+    background: '{color.white}'
+  }
+}
+
+const standardData = PropertiesStandard.to(data)
+// Теперь все поля в standardData.header.value имеют правильную структуру PropertyItem
+```

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

@@ -0,0 +1,87 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesStandard - Chuẩn hóa thuộc tính'/>
+
+# Lớp PropertiesStandard
+
+Lớp `PropertiesStandard` là cơ chế trung tâm để chuẩn hóa dữ liệu trong hệ thống thiết kế. Nhiệm vụ chính của nó là chuyển đổi dữ liệu đầu vào token "thô" (có thể được biểu diễn dưới dạng chuỗi, số hoặc đối tượng đơn giản hóa) thành một cấu trúc `PropertyItem` được định kiểu nghiêm ngặt mà các công cụ khác của hệ thống có thể làm việc cùng.
+
+## Các tính năng chính
+
+- **Chuẩn hóa dữ liệu** — đảm bảo rằng mọi thuộc tính đều có một tập hợp các trường tiêu chuẩn (`value`, `type`, `index`, v.v.).
+- **Xử lý đệ quy** — tự động chuẩn hóa các cấu trúc đối tượng lồng nhau.
+- **Tự động phát hiện kiểu** — cố gắng xác định kiểu thuộc tính dựa trên tên của nó (thông qua `PropertiesTypes`).
+- **Phân tích thông minh** — phân biệt giữa các giá trị thông thường và các thuộc tính meta đặc biệt (bắt đầu bằng `__`).
+- **Hợp nhất dữ liệu** — hợp nhất chính xác dữ liệu mới với dữ liệu hiện có, duy trì tính toàn vẹn của cấu trúc.
+
+## Khởi tạo
+
+Lớp này cung cấp các phương thức tĩnh, vì vậy không cần phải khởi tạo thông qua `new`.
+
+```typescript
+import { PropertiesStandard } from '@dxtmisha/scripts'
+
+// Gọi một phương thức tĩnh
+const standardized = PropertiesStandard.to(rawInput)
+```
+
+## Các phương thức
+
+### `to`
+Một phương thức tĩnh nhận dữ liệu thô hoặc danh sách thuộc tính và trả về một `PropertyList` đã được chuẩn hóa hoàn toàn. Phương thức này lặp qua tất cả các phần tử, xác định khóa, kiểu và giá trị của chúng, đồng thời xử lý đệ quy các đối tượng lồng nhau.
+
+**Tham số:**
+- `properties: PropertyListOrData` — dữ liệu thuộc tính đầu vào ở bất kỳ định dạng nào được hỗ trợ.
+
+**Trả về:** `PropertyList` — một đối tượng trong đó mọi phần tử đều được đưa về tiêu chuẩn `PropertyItem`.
+
+```typescript
+const result = PropertiesStandard.to({
+  'primary-color': '#007bff',
+  'padding': { value: 16, type: 'size' }
+});
+
+/* Kết quả:
+{
+  'primary-color': { 
+    value: '#007bff', 
+    type: 'color', 
+    index: 'primary-color' 
+  },
+  'padding': { 
+    value: '16px', 
+    type: 'size', 
+    index: 'padding' 
+  }
+}
+*/
+```
+
+## Các thao tác (Operations)
+
+### Thuật toán chuẩn hóa (getItem)
+
+Khi xử lý từng phần tử, các bước sau được thực hiện:
+1. **Chuyển đổi đối tượng**: Phương thức `toItem` kiểm tra kiểu giá trị đầu vào. Nếu là chuỗi hoặc mảng, nó sẽ được bọc trong một đối tượng `{ value: ... }`.
+2. **Tách dữ liệu meta**: Phương thức `getValueAndSpecial` tách giá trị hữu ích (`value`) khỏi các khóa điều khiển đặc biệt (ví dụ: `__custom`).
+3. **Xác định kiểu**: Nếu kiểu không được chỉ định rõ ràng, phương thức `addType` cố gắng tính toán nó dựa trên tên khóa.
+4. **Kiểm tra tính hoàn tất**: Phương thức `addFull` thêm các thẻ `fullName` hoặc `fullValue` nếu dữ liệu không yêu cầu xử lý thêm (ví dụ: đối với các liên kết đã được phân giải).
+5. **Chuyển đổi giá trị**: Thông qua `addValue`, tất cả các giá trị số được chuyển đổi thành chuỗi, thêm đơn vị khi cần thiết.
+6. **Đăng ký chỉ mục (Index)**: Mỗi phần tử được gán một `index` đã được làm sạch để phục vụ việc truy vết nhanh chóng.
+
+## Ví dụ (Examples)
+
+### Chuẩn hóa một cấu trúc phức tạp
+```typescript
+import { PropertiesStandard } from '@dxtmisha/scripts'
+
+const data = {
+  header: {
+    height: 60,
+    background: '{color.white}'
+  }
+}
+
+const standardData = PropertiesStandard.to(data)
+// Tất cả các trường trong standardData.header.value hiện có cấu trúc PropertyItem chính xác
+```