@dxtmisha/wiki 0.39.1 → 0.39.2

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

@@ -0,0 +1,310 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesFile - Bộ điều phối đường dẫn hệ thống tệp'/>
+
+# Lớp PropertiesFile
+
+Lớp `PropertiesFile` là một tiện ích tĩnh toàn diện được thiết kế để điều phối tất cả các tác vụ liên quan đến hệ thống tệp trong bộ công cụ hệ thống thiết kế. Nó cung cấp một giao diện không phụ thuộc vào nền tảng để thao tác đường dẫn, IO đồng bộ và quản lý thư mục đệ quy, đảm bảo rằng việc khám phá tệp và lưu trữ dữ liệu luôn nhất quán trên các hệ điều hành và môi trường phát triển khác nhau.
+
+## Các tính năng chính
+
+- **Chuẩn hóa đường dẫn** — Tự động phân giải các ký tự phân tách đường dẫn cụ thể của hệ điều hành và hợp nhất các phân đoạn thành các chuỗi tiêu chuẩn.
+- **Duyệt đệ quy** — Cung cấp các phương thức chuyên biệt để khám phá sâu các cấu trúc thư mục với tính năng lập chỉ mục tùy chọn.
+- **IO đồng bộ** — Xử lý việc đọc tệp (JSON/Văn bản) và ghi tệp với tính năng tự động tổng hợp thư mục.
+- **Khám phá siêu dữ liệu** — Truy xuất dấu thời gian của tệp và dữ liệu thống kê cho logic vô hiệu hóa bộ nhớ đệm (cache invalidation).
+- **Hoạt động an toàn** — Bao gồm các kiểm tra tích hợp về sự tồn tại của mục nhập, loại (tệp so với thư mục) và trạng thái mô-đun.
+
+## Khởi tạo
+
+Là một lớp tĩnh, `PropertiesFile` tự khởi tạo và sẵn sàng sử dụng ngay khi import.
+
+```typescript
+import { PropertiesFile } from '@dxtmisha/scripts'
+
+// Kiểm tra xem cấu hình có tồn tại không
+if (PropertiesFile.is('design-ui.json')) {
+  const config = PropertiesFile.readFile('design-ui.json')
+}
+
+// Hợp nhất các đường dẫn một cách an toàn
+const fullPath = PropertiesFile.joinPath(['src', 'tokens', 'colors.json'])
+```
+
+## Các phương thức kiểm tra
+
+- `is(path): boolean` — Kiểm tra đồng bộ sự tồn tại của tệp hoặc thư mục.
+- `isDir(path): boolean` — Xác định xem đường dẫn có trỏ đến một thư mục hay không.
+- `isModule(): boolean` — Xác định xem gói hiện tại có được kết nối dưới dạng mô-đun ngoài hay không.
+
+## Các phương thức quản lý đường dẫn
+
+### `joinPath`
+
+Hợp nhất nhiều phân đoạn đường dẫn thành một chuỗi đường dẫn chuẩn hóa duy nhất bằng cách sử dụng ký tự phân tách của hệ điều hành hiện tại.
+
+**Tham số:**
+- `path: PropertiesFilePath` — mảng các phân đoạn hoặc chuỗi đường dẫn.
+
+**Ví dụ:**
+```typescript
+const path = PropertiesFile.joinPath(['src', 'styles', 'main.css'])
+// Trả về: "src/styles/main.css" (trên Mac/Linux) hoặc "src\styles\main.css" (trên Windows)
+```
+
+**Trả về:** `string` — đường dẫn đã hợp nhất và chuẩn hóa.
+
+### `joinPathByName`
+
+Tạo đường dẫn đầy đủ đến tệp bằng cách hợp nhất đường dẫn thư mục, tên tệp và phần mở rộng.
+
+**Tham số:**
+- `path: PropertiesFilePath` — đường dẫn thư mục.
+- `name: string` — tên tệp.
+- `extension: string` — phần mở rộng tệp (mặc định là `json`).
+
+**Ví dụ:**
+```typescript
+const filePath = PropertiesFile.joinPathByName('data', 'user-profile', 'json')
+// Trả về: "data/user-profile.json"
+```
+
+**Trả về:** `string`
+
+### `getPathDir`
+
+Trích xuất đường dẫn thư mục từ một đường dẫn đầy đủ. Nếu đường dẫn thư mục được truyền vào, nó sẽ trả về nguyên vẹn.
+
+**Tham số:**
+- `path: PropertiesFilePath` — đường dẫn đến tệp hoặc thư mục.
+
+**Ví dụ:**
+```typescript
+const dirOnly = PropertiesFile.getPathDir('src/classes/App.ts')
+// Trả về: "src/classes"
+```
+
+**Trả về:** `string`
+
+### `getPathFile`
+
+Tạo một mảng các phân đoạn đường dẫn đến tệp.
+
+**Tham số:**
+- `path: PropertiesFilePath` — đường dẫn cơ sở.
+- `name: string` — tên tệp.
+- `extension: string` — phần mở rộng (mặc định là `json`).
+
+**Ví dụ:**
+```typescript
+const segments = PropertiesFile.getPathFile('dist', 'manifest')
+// Trả về: ["dist", "manifest.json"]
+```
+
+**Trả về:** `string[]`
+
+### `getRoot`
+
+Trả về đường dẫn gốc hiện tại của dự án (`process.cwd()`).
+
+**Ví dụ:**
+```typescript
+const root = PropertiesFile.getRoot()
+// Trả về: "/Users/user/project"
+```
+
+**Trả về:** `string`
+
+### `getFileName`
+
+Chuyển đổi tên sang kebab-case và thêm phần mở rộng được chỉ định.
+
+**Tham số:**
+- `name: string` — tên phần tử.
+- `extension: string` — phần mở rộng (mặc định là `json`).
+
+**Ví dụ:**
+```typescript
+const name = PropertiesFile.getFileName('UserProfile', 'ts')
+// Trả về: "user-profile.ts"
+```
+
+**Trả về:** `string`
+
+### `sep`
+
+Trả về ký tự phân tách thư mục cụ thể của hệ thống (`/` hoặc `\`).
+
+**Ví dụ:**
+```typescript
+const s = PropertiesFile.sep()
+// Trả về: "/"
+```
+
+**Trả về:** `string`
+
+## Các phương thức đọc
+
+### `readFile`
+
+Đọc đồng bộ và tự động phân giải nội dung tệp. Trả về một đối tượng nếu là JSON, ngược lại là một chuỗi.
+
+**Tham số:**
+- `path: PropertiesFilePath` — đường dẫn đến tệp.
+
+**Ví dụ:**
+```typescript
+const data = PropertiesFile.readFile<{ name: string }>('config.json')
+// Trả về: { name: "DXT" } (đối tượng)
+```
+
+**Trả về:** `R | undefined` — dữ liệu đã phân giải hoặc `undefined` nếu không tìm thấy tệp.
+
+### `readFileOnly`
+
+Đọc nội dung tệp dưới dạng chuỗi thô mà không có bất kỳ chuyển đổi nào.
+
+**Tham số:**
+- `path: PropertiesFilePath` — đường dẫn đến tệp.
+
+**Ví dụ:**
+```typescript
+const text = PropertiesFile.readFileOnly('README.md')
+// Trả về: "# Project Title..." (chuỗi)
+```
+
+**Trả về:** `string | undefined`
+
+### `readDir`
+
+Đọc nội dung của một thư mục (danh sách tên các mục con).
+
+**Tham số:**
+- `path: PropertiesFilePath` — đường dẫn đến thư mục.
+
+**Ví dụ:**
+```typescript
+const items = PropertiesFile.readDir('src')
+// Trả về: ["index.ts", "classes", "types"]
+```
+
+**Trả về:** `string[]`
+
+### `readDirRecursive`
+
+Đọc đệ quy tất cả các tệp trong một thư mục và các thư mục con của nó.
+
+**Tham số:**
+- `path: PropertiesFilePath` — đường dẫn đến thư mục.
+
+**Ví dụ:**
+```typescript
+const allFiles = PropertiesFile.readDirRecursive('src')
+// Trả về: ["index.ts", "classes/App.ts", "classes/DB.ts", ...]
+```
+
+**Trả về:** `string[]` — danh sách đường dẫn đến tất cả các tệp được tìm thấy.
+
+## Các phương thức chỉnh sửa
+
+### `write`
+
+Lưu dữ liệu vào một tệp, tự động tạo bất kỳ thư mục cha nào còn thiếu.
+
+**Tham số:**
+- `path: PropertiesFilePath` — đường dẫn thư mục.
+- `name: string` — tên tệp.
+- `value: T` — dữ liệu cần ghi.
+- `extension: string` — phần mở rộng (mặc định là `json`).
+
+**Ví dụ:**
+```typescript
+PropertiesFile.write('dist/cache', 'data', { id: 1 })
+// Tạo dist/cache/data.json với nội dung JSON
+```
+
+**Trả về:** `void`
+
+### `writeByPath`
+
+Ghi dữ liệu vào một đường dẫn tệp chính xác.
+
+**Tham số:**
+- `path: PropertiesFilePath` — đường dẫn đầy đủ đến tệp.
+- `value: T` — dữ liệu.
+- `transform: boolean` — có chuyển đổi đối tượng thành JSON hay không (mặc định là `true`).
+
+**Ví dụ:**
+```typescript
+PropertiesFile.writeByPath('logs/error.log', 'Critical error', false)
+// Ghi chuỗi thô vào tệp mà không chuyển đổi JSON
+```
+
+**Trả về:** `void`
+
+### `createDir`
+
+Tạo đệ quy một thư mục nếu nó chưa tồn tại.
+
+**Tham số:**
+- `path: PropertiesFilePath` — đường dẫn cần tạo.
+
+**Ví dụ:**
+```typescript
+PropertiesFile.createDir('storage/images/2024')
+// Tạo toàn bộ cây thư mục
+```
+
+**Trả về:** `void`
+
+### `copy`
+
+Sao chép một tệp từ đường dẫn nguồn đến đường dẫn đích.
+
+**Tham số:**
+- `path: PropertiesFilePath` — đường dẫn đích.
+- `pathsSrc: PropertiesFilePath` — đường dẫn nguồn.
+
+**Ví dụ:**
+```typescript
+PropertiesFile.copy('backup/config.json', 'config.json')
+```
+
+**Trả về:** `void`
+
+### `removeFile`
+
+Xóa tệp được chỉ định.
+
+**Tham số:**
+- `path: PropertiesFilePath` — đường dẫn đến tệp.
+
+**Ví dụ:**
+```typescript
+PropertiesFile.removeFile('temp.tmp')
+```
+
+**Trả về:** `void`
+
+### `removeDir`
+
+Xóa đệ quy một thư mục và tất cả nội dung của nó.
+
+**Tham số:**
+- `path: PropertiesFilePath` — đường dẫn đến thư mục.
+
+**Ví dụ:**
+```typescript
+PropertiesFile.removeDir('dist/old-version')
+```
+
+**Trả về:** `void`
+
+## Các thao tác (Operations)
+
+### Luồng đồng bộ hóa Đường dẫn & IO (The Paths & IO Synchronization Flow)
+
+`PropertiesFile` đóng vai trò là lớp đồng bộ hóa cấp thấp cho toàn bộ thư viện:
+1. **Chuẩn hóa đường dẫn**: Mọi phương thức đều gọi nội bộ `joinPath` и `toSep`, chuyển đổi tất cả các dấu gạch chéo xuôi thành ký tự phân tách cụ thể của hệ điều hành (ví dụ: `\` trên Windows).
+2. **Ghi nguyên tử**: Khi `write()` được gọi, lớp trước tiên sẽ xác định thư mục đích và thực thi `createDir()`, lệnh này sẽ xây dựng đệ quy bất kỳ thư mục nào còn thiếu trước khi ghi nội dung thông qua `fs.writeFileSync`.
+3. **Ngữ cảnh đệ quy**: Các phương thức đệ quy chuyên biệt (`readDirRecursive`, v.v.) cho phép các công cụ tài liệu và token khám phá mọi tệp trong cây thành phần mà không cần quản lý thủ công độ sâu hoặc giới hạn đệ quy.
+4. **Phân giải gốc (Root Resolution)**: Nó duy trì một `root` nội bộ (dựa trên `process.cwd()`) để đảm bảo các phân đoạn đường dẫn tương đối luôn được phân giải từ thư mục gốc của dự án.

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

@@ -0,0 +1,57 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesImport - External Token Resolver'/>
+
+# PropertiesImport Class
+
+The `PropertiesImport` class is a specialized manager for resolving and integrating external file references within design token clusters. It allows developers to modularize property definitions across multiple files or directories, providing powerful mechanisms for deep-linking into specific data structures and recursive merging of independent token sets into a single unified configuration.
+
+## Key Features
+
+- **Modular Resolution** — Transparently includes external `.json` files or entire directories into the property tree.
+- **Deep Deep-Linking** — Supports fragment identifiers (e.g., `#path.to.node`) to import only specific subsets of an external file.
+- **Recursive Directory Import** — Automatically maps folder structures to property namespaces when a directory is referenced.
+- **Context-Aware Resolution** — Tracks the current directory level to resolve relative file paths correctly during deep traversal.
+- **Normalized Merging** — Ensures that imported data is passed through `PropertiesStandard` before being merged into the parent tree.
+
+## Initialization
+
+To initialize the object, call the `PropertiesImport(properties, root)` constructor.
+
+**Parameters:**
+- `properties: PropertyList` — initial property list (token tree) to be processed.
+- `root: string[]` — base path segments for resolving relative file references.
+
+```typescript
+import { PropertiesImport } from '@dxtmisha/scripts'
+
+// 1. Prepare raw data and path context
+const initialProperties = { 
+  button: { type: 'file', value: 'components/button.json' } 
+}
+const rootPath = ['src', 'tokens']
+
+// 2. Create the importer instance
+const importer = new PropertiesImport(initialProperties, rootPath)
+
+// 3. Trigger the resolution of external references
+const resolvedData = importer.to()
+```
+
+## Methods
+
+- `to(properties, root): PropertyList` — resolves and merges all external file references within the property cluster.
+
+## Operations
+
+### The External Resolution Flow
+
+`PropertiesImport` manages a multi-stage resolution pipeline:
+1. **Detection**: As it traverses the tree, it specifically targets items where the `value` is a string and the type metadata matches `PropertyType.file`.
+2. **Link Parsing**: It splits the reference string (e.g., `theme/colors.json#primary`) into a physical file `path` and an optional internal `link` fragment.
+3. **IO Execution**:
+    - **Single File**: Reads the target file via `PropertiesCache`.
+    - **Directory**: Maps all `.json` files in the folder to child properties named after the filenames.
+4. **Deep Extraction**: If a fragment identifier (`#`) was present, it navigates through the read object to return only the requested sub-path.
+5. **Standardization & Recusion**: The extracted data is passed to `PropertiesStandard` for normalization and then recursively passed back to `to()` to resolve any *nested* imports within the newly included file.
+6. **Merging**: The finalized data is recursively merged into the parent structure using `replaceRecursive`.

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

@@ -0,0 +1,57 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesImport - Резолвер внешних токенов'/>
+
+# Класс PropertiesImport
+
+Класс `PropertiesImport` — это специализированный менеджер для разрешения и интеграции ссылок на внешние файлы внутри кластеров токенов дизайна. Он позволяет разработчикам модульно распределять определения свойств по нескольким файлам или директориям, предоставляя мощные механизмы глубокого связывания со специфическими структурами данных и рекурсивного объединения независимых наборов токенов в единую унифицированную конфигурацию.
+
+## Ключевые особенности
+
+- **Модульное разрешение** — прозрачно включает внешние `.json` файлы или целые директории в дерево свойств.
+- **Глубокие ссылки (Deep-Linking)** — поддерживает идентификаторы фрагментов (например, `#path.to.node`) для импорта только определенных подмножеств внешнего файла.
+- **Рекурсивный импорт директорий** — автоматически сопоставляет структуры папок с пространствами имен свойств при ссылке на директорию.
+- **Контекстное разрешение** — отслеживает текущий уровень директории для правильного разрешения относительных путей файлов во время глубокого обхода.
+- **Нормализованное слияние** — гарантирует, что импортированные данные проходят через `PropertiesStandard` перед объединением с родительским деревом.
+
+## Инициализация
+
+Для инициализации объекта вызовите конструктор `PropertiesImport(properties, root)`.
+
+**Параметры:**
+- `properties: PropertyList` — начальный список свойств (дерево токенов) для обработки.
+- `root: string[]` — сегменты базового пути для разрешения относительных ссылок на файлы.
+
+```typescript
+import { PropertiesImport } from '@dxtmisha/scripts'
+
+// 1. Подготовка исходных данных и контекста пути
+const initialProperties = { 
+  button: { type: 'file', value: 'components/button.json' } 
+}
+const rootPath = ['src', 'tokens']
+
+// 2. Создание экземпляра импортера
+const importer = new PropertiesImport(initialProperties, rootPath)
+
+// 3. Запуск процесса разрешения внешних ссылок
+const resolvedData = importer.to()
+```
+
+## Методы
+
+- `to(properties, root): PropertyList` — разрешает и объединяет все внешние ссылки на файлы внутри кластера свойств.
+
+## Операции
+
+### Поток разрешения внешних ссылок
+
+`PropertiesImport` управляет многоэтапным конвейером разрешения:
+1. **Детекция**: При обходе дерева класс ищет элементы, где `value` является строкой, а метаданные типа соответствуют `PropertyType.file`.
+2. **Парсинг ссылки**: Строка ссылки (например, `theme/colors.json#primary`) разделяется на физический `path` файла и опциональный фрагмент внутренней ссылки `link`.
+3. **Выполнение ввода-вывода**:
+    - **Одиночный файл**: Читает целевой файл через `PropertiesCache`.
+    - **Директория**: Сопоставляет все файлы `.json` в папке с дочерними свойствами, названными по имени файлов.
+4. **Глубокое извлечение**: Если присутствует идентификатор фрагмента (`#`), класс проходит по прочитанному объекту, чтобы вернуть только запрошенный подпуть.
+5. **Стандартизация и рекурсия**: Извлеченные данные передаются в `PropertiesStandard` для нормализации, а затем рекурсивно возвраруются в `to()` для разрешения любых *вложенных* импортов внутри только что включенного файла.
+6. **Слияние**: Итоговые данные рекурсивно объединяются с родительской структурой с помощью `replaceRecursive`.

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

@@ -0,0 +1,57 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesImport - Bộ phân giải Token bên ngoài'/>
+
+# Lớp PropertiesImport
+
+Lớp `PropertiesImport` là một trình quản lý chuyên biệt để phân giải và tích hợp các tham chiếu tệp bên ngoài trong các cụm token thiết kế. Nó cho phép các nhà phát triển mô-đun hóa các định nghĩa thuộc tính trên nhiều tệp hoặc thư mục, cung cấp các cơ chế mạnh mẽ để liên kết sâu (deep-linking) vào các cấu trúc dữ liệu cụ thể và hợp nhất đệ quy các tập hợp token độc lập vào một cấu hình thống nhất duy nhất.
+
+## Các tính năng chính
+
+- **Phân giải mô-đun** — Bao gồm các tệp `.json` bên ngoài hoặc toàn bộ thư mục vào cây thuộc tính một cách minh bạch.
+- **Liên kết sâu (Deep-linking)** — Hỗ trợ các định danh phân đoạn (ví dụ: `#path.to.node`) để chỉ nhập các tập hợp con cụ thể của một tệp bên ngoài.
+- **Nhập thư mục đệ quy** — Tự động ánh xạ cấu trúc thư mục tới các không gian tên thuộc tính khi một thư mục được tham chiếu.
+- **Phân giải nhận biết ngữ cảnh** — Theo dõi cấp độ thư mục hiện tại để phân giải chính xác các đường dẫn tệp tương đối trong quá trình duyệt sâu.
+- **Hợp nhất chuẩn hóa** — Đảm bảo rằng dữ liệu đã nhập được truyền qua `PropertiesStandard` trước khi được hợp nhất vào cây cha.
+
+## Khởi tạo
+
+Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `PropertiesImport(properties, root)`.
+
+**Tham số:**
+- `properties: PropertyList` — danh sách thuộc tính ban đầu (cây token) cần xử lý.
+- `root: string[]` — các phân đoạn đường dẫn cơ sở để phân giải các tham chiếu tệp tương đối.
+
+```typescript
+import { PropertiesImport } from '@dxtmisha/scripts'
+
+// 1. Chuẩn bị dữ liệu thô và ngữ cảnh đường dẫn
+const initialProperties = { 
+  button: { type: 'file', value: 'components/button.json' } 
+}
+const rootPath = ['src', 'tokens']
+
+// 2. Tạo thực thể importer
+const importer = new PropertiesImport(initialProperties, rootPath)
+
+// 3. Kích hoạt việc phân giải các tham chiếu bên ngoài
+const resolvedData = importer.to()
+```
+
+## Các phương thức
+
+- `to(properties, root): PropertyList` — phân giải và hợp nhất tất cả các tham chiếu tệp bên ngoài trong cụm thuộc tính.
+
+## Các thao tác (Operations)
+
+### Luồng phân giải bên ngoài (The External Resolution Flow)
+
+`PropertiesImport` quản lý một quy trình phân giải nhiều giai đoạn:
+1. **Phát hiện**: Khi duyệt cây, nó nhắm mục tiêu cụ thể vào các mục có `value` là một chuỗi và siêu dữ liệu loại khớp với `PropertyType.file`.
+2. **Phân tích cú pháp liên kết**: Nó tách chuỗi tham chiếu (ví dụ: `theme/colors.json#primary`) thành `path` tệp vật lý và một phân đoạn `link` nội bộ tùy chọn.
+3. **Thực thi IO**:
+    - **Tệp đơn**: Đọc tệp mục tiêu thông qua `PropertiesCache`.
+    - **Thư mục**: Ánh xạ tất cả các tệp `.json` trong thư mục tới các thuộc tính con được đặt tên theo tên tệp.
+4. **Trích xuất sâu**: Nếu có định danh phân đoạn (`#`), nó sẽ điều hướng qua đối tượng đã đọc để chỉ trả về đường dẫn phụ được yêu cầu.
+5. **Chuẩn hóa & Đệ quy**: Dữ liệu được trích xuất được truyền cho `PropertiesStandard` để chuẩn hóa và sau đó được truyền đệ quy trở lại `to()` để phân giải bất kỳ lượt nhập *lồng nhau* nào bên trong tệp vừa được bao gồm.
+6. **Hợp nhất**: Dữ liệu cuối cùng được hợp nhất đệ quy vào cấu trúc cha bằng `replaceRecursive`.

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

@@ -0,0 +1,58 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/scripts/Classes/PropertiesItems - Property Tree Coordinator'/>
+
+# PropertiesItems Class
+
+The `PropertiesItems` class acts as the central coordinator for navigating and searching through complex design property trees. It provides a high-level abstraction layer that hides the intricacies of tree traversal, index decoding, and design-specific filtering. Whether you need to find a specific token by its dotted path, perform a global search across categories, or execute deep recursive operations, `PropertiesItems` serves as the primary engine for property discovery.
+
+## Key Features
+
+- **Design Focusing** — Allows filtering the entire property interaction scope to a single design theme or component cluster.
+- **Deep Metadata Resolution** — Translates simple index strings (e.g., `theme.colors.primary`) into comprehensive info objects with full parental context.
+- **Unified Traversal Engine** — Provides consistent `each` and `find` mechanisms for both shallow and deep recursive exploration of the token hierarchy.
+- **Path Semantic Translation** — Automatically handles path normalization, kebab-to-camelCase conversion, and support for special link symbols like `?`.
+- **Category & Variable Filtering** — Includes optimized search methods to extract subsets of tokens based on their functional category or variable type.
+
+## Initialization
+
+To initialize the object, call the `PropertiesItems(properties)` constructor.
+
+**Parameters:**
+- `properties: PropertyList` — full property list (token tree) to be managed.
+
+```typescript
+import { PropertiesItems } from '@dxtmisha/scripts'
+
+// 1. Initialize the manager with the token tree
+const manager = new PropertiesItems(allTokenData)
+
+// 2. (Optional) Focus the environment on a specific design
+manager.setFocusDesign('my-theme')
+
+// 3. Retrieve the filtered structure
+const currentTokens = manager.get()
+```
+
+## Methods
+
+- `get(): PropertyList` — returns the current property structure (supports focus filtering).
+- `getDesigns(): string[]` — returns a list of available design names.
+- `getItem(index): PropertyItem` — retrieves a specific property record by its index.
+- `getInfo(index): PropertyItemsItem` — resolves full metadata and parental hierarchy for a given index.
+- `getKeys(index): string[]` — decodes a path string into normalized key segments.
+- `getName(name, item): string` — returns the display name of a property, accounting for renames.
+- `each(callback, property?): T[]` — performs a deep recursive traversal of the tree.
+- `find(callback): PropertyItemsItem[]` — searches for records matching custom conditions.
+- `findCategory(category): PropertyItemsItem[]` — extracts tokens belonging to specific functional categories.
+- `setFocusDesign(design): this` — restricts the operational scope to a specific design.
+
+## Operations
+
+### The Metadata Discovery & Traversal Flow
+
+`PropertiesItems` orchestrates several complex logic flows:
+1. **Index Decoding**: When an index like `theme.button-main.color` is requested, it normalizes segments to camelCase and resolves them against the nested `value` objects of the tree.
+2. **Path Context Management**: During traversal (`each`), the class maintains a `parents` stack, allowing every discovered node to know exactly where it sits in the hierarchy (crucial for generating CSS variables or documentation paths).
+3. **Design Isolation**: By calling `setFocusDesign()`, users can toggle the "view" of the entire tree. Subsequent calls to `get()` or `each()` will automatically ignore designs that are NOT the focused one or the common `_constructor`.
+4. **Link Normalization**: Methods like `getLink()` handle the transformation of legacy path symbols (like `??` and `?`) into absolute, fully-qualified property indices by prepending current design and component contexts.

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

@@ -0,0 +1,58 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesItems - Координатор дерева свойств'/>
+
+# Класс PropertiesItems
+
+Класс `PropertiesItems` выступает в качестве центрального координатора для навигации и поиска по сложным деревьям свойств дизайна. Он предоставляет уровень абстракции, который скрывает сложности обхода дерева, декодирования индексов и фильтрации по конкретным дизайнам. Если вам нужно найти конкретный токен по его пути через точку, выполнить глобальный поиск по категориям или запустить глубокие рекурсивные операции, `PropertiesItems` служит основным движком для обнаружения свойств.
+
+## Ключевые особенности
+
+- **Фокусировка на дизайне** — позволяет фильтровать всю область взаимодействия со свойствами до одной темы дизайна или кластера компонентов.
+- **Глубокое разрешение метаданных** — преобразует простые строки индексов (например, `theme.colors.primary`) в содержательные объекты информации с полным родительским контекстом.
+- **Унифицированный движок обхода** — предоставляет согласованные механизмы `each` и `find` как для поверхностного, так и для глубокого рекурсивного исследования иерархии токенов.
+- **Семантическая трансляция путей** — автоматически обрабатывает нормализацию путей, преобразование kebab-to-camelCase и поддержку специальных символов ссылок, таких как `?`.
+- **Фильтрация по категориям и переменным** — включает оптимизированные методы поиска для извлечения подмножеств токенов на основе их функциональной категории или типа переменной.
+
+## Инициализация
+
+Для инициализации объекта вызовите конструктор `PropertiesItems(properties)`.
+
+**Параметры:**
+- `properties: PropertyList` — полный список свойств (дерево токенов) для управления.
+
+```typescript
+import { PropertiesItems } from '@dxtmisha/scripts'
+
+// 1. Инициализация менеджера с деревом токенов
+const manager = new PropertiesItems(allTokenData)
+
+// 2. (Опционально) Установка фокуса на конкретный дизайн
+manager.setFocusDesign('my-theme')
+
+// 3. Получение отфильтрованной структуры
+const currentTokens = manager.get()
+```
+
+## Методы
+
+- `get(): PropertyList` — возвращает текущую структуру свойств (поддерживает фильтрацию фокуса).
+- `getDesigns(): string[]` — возвращает список доступных названий дизайна.
+- `getItem(index): PropertyItem` — извлекает конкретную запись свойства по её индексу.
+- `getInfo(index): PropertyItemsItem` — разрешает полные метаданные и иерархию родителей для данного индекса.
+- `getKeys(index): string[]` — декодирует строку пути в нормализованные сегменты ключей.
+- `getName(name, item): string` — возвращает отображаемое имя свойства с учетом переименований.
+- `each(callback, property?): T[]` — выполняет глубокий рекурсивный обход дерева.
+- `find(callback): PropertyItemsItem[]` — ищет записи, соответствующие пользовательским условиям.
+- `findCategory(category): PropertyItemsItem[]` — извлекает токены, относящиеся к специфическим функциональным категориям.
+- `setFocusDesign(design): this` — ограничивает область операций конкретным дизайном.
+
+## Операции
+
+### Поток обнаружения метаданных и обхода
+
+`PropertiesItems` координирует несколько сложных логических потоков:
+1. **Декодирование индекса**: При запросе индекса вида `theme.button-main.color` класс нормализует сегменты в camelCase и сопоставляет их с вложенными объектами `value` в дереве.
+2. **Управление контекстом пути**: Во время обхода (`each`) класс поддерживает стек `parents`, позволяя каждому обнаруженному узлу точно знать свое место в иерархии (критично для генерации CSS-переменных или путей документации).
+3. **Изоляция дизайна**: Вызывая `setFocusDesign()`, пользователи могут переключать «вид» всего дерева. Последующие вызовы `get()` или `each()` будут автоматически игнорировать дизайны, которые НЕ являются сфокусированным или общим `_constructor`.
+4. **Нормализация ссылок**: Методы типа `getLink()` обрабатывают трансформацию устаревших символов путей (таких как `??` и `?`) в абсолютные, полные индексы свойств, добавляя текущий контекст дизайна и компонента перед ними.