import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesPath - Резолвер путей и окружения'/>

# Класс PropertiesPath

Класс `PropertiesPath` — это основная утилита, отвечающая за преобразование абстрактных идентификаторов дизайна в конкретные физические пути файловой системы. Он управляет сопоставлением директорий как для глобальных токенов дизайна, так и для специфических переопределений компонентов, гарантируя согласованность обнаружения путей на разных платформах. Предоставляя кэшированные методы обхода, такие как `to` и `toAll`, он координирует последовательность загрузки данных для многотемных проектов, выступая в качестве основного источника информации об окружении для движка свойств.

## Ключевые особенности

- **Сопоставление нескольких дизайнов** — автоматически сопоставляет массив названий дизайнов с соответствующими директориями токенов и компонентов.
- **Кроссплатформенное обнаружение корня** — использует `PropertiesFile` для обеспечения абсолютности путей и их правильного разрешения в различных операционных системах.
- **Внутренняя оптимизация (кэширование)** — интегрирован с `PropertiesCache` для минимизации избыточных обращений к файловой системе во время сложных конвейеров трансформации токенов.
- **Определение режима конструктора** — идентифицирует и обрабатывает специальный дизайн `_constructor`, который служит общей базой для всех тем.
- **Гибкий обход данных** — предоставляет высокоуровневые обратные вызовы для обработки файлов дизайна без раскрытия деталей работы с файловой системой.

## Инициализация

Для инициализации объекта вызовите конструктор `PropertiesPath(designs)`.

**Параметры:**
- `designs: string[]` — список названий дизайнов, соответствующих именам папок в структуре проекта.

```typescript
import { PropertiesPath } from '@dxtmisha/scripts'

// 1. Определение дизайнов для управления
const activeDesigns = ['basic', 'constructor', 'premium']

// 2. Создание экземпляра резолвера путей
const pathResolver = new PropertiesPath(activeDesigns)

// 3. Получение путей для конкретного дизайна
const basicPaths = pathResolver.getPath('basic')
```

## Методы

- `isConstructor(): boolean` — проверяет, включает ли текущее окружение базовый дизайн конструктора.
- `getDesigns(): string[]` — возвращает список названий дизайнов, зарегистрированных в экземпляре.
- `getPath(name): PropertiesPathItem` — извлекает специфические пути (глобальные и компоненты) для данного дизайна.
- `getPaths(): PropertiesPathList` — возвращает полный реестр сопоставлений дизайнов и путей.
- `to(name, design, callback): T` — выполняет кэшированный обратный вызов трансформации для конкретного дизайна.
- `toAll(name, callback): T` — координирует глобальную кэшированную трансформацию для всех зарегистрированных дизайнов.

## Операции

### Поток обнаружения окружения и кэширования

`PropertiesPath` управляет сопоставлением между высокоуровневой логикой и физическим хранилищем:
1. **Агрегация директорий**: При создании экземпляра класс нормализует названия дизайнов в kebab-case и использует внутреннюю логику `getDir` для синтеза абсолютных путей к `UI_DIRS_TOKENS` и `UI_DIRS_COMPONENTS`.
2. **Изоляция дизайна**: Класс различает стандартные темы и `_constructor`. Если дизайн помечен как конструктор, стандартное обнаружение директорий обходится для обеспечения специализированной обработки базового слоя.
3. **Кэшированная трансформация**: При вызове `to()` или `toAll()` класс не просто возвращает пути — он пытается получить ранее обработанные данные из `PropertiesCache`. Если данные в кэше отсутствуют, выполняется предоставленный callback с разрешенными путями, а новый результат прозрачно сохраняется.
4. **Синтез унифицированной иерархии**: Через `toAll()` класс реализует паттерн «слияния вверх», когда токены из нескольких дизайнов (например, `constructor` + `basic` + `local-theme`) извлекаются последовательно и объединяются в единую иерархическую структуру с помощью `replaceRecursive`.
