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`.
