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()` обрабатывают трансформацию устаревших символов путей (таких как `??` и `?`) в абсолютные, полные индексы свойств, добавляя текущий контекст дизайна и компонента перед ними.
