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

<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesPalette - Менеджер палитры и оттенков'/>

# Класс PropertiesPalette

Класс `PropertiesPalette` — это специализированный менеджер для работы с токенами дизайна, связанными с цветом. Он фокусируется на двух основных областях: управлении шагами насыщенности цвета (оттенками) и отслеживании фактического использования цветов палитры в функциональных переменных. Анализируя способы использования цветов в системе дизайна, он помогает гарантировать согласованность определений тем и правильность ссылок сгенерированных CSS-переменных на соответствующие записи в палитре.

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

- **Обнаружение насыщенности** — автоматически извлекает доступные уровни оттенков (например, 50, 100, 200) из дерева свойств.
- **Отслеживание использования** — идентифицирует, какие цвета палитры фактически сопоставлены с переменными компонентов, упрощая удаление неиспользуемого кода или проведение аудита.
- **Сопоставление с учетом темы** — разрешает сложные ссылки на цвета, учитывая специфические для темы переопределения (например, `basic` или `dark`).
- **Синтез CSS-переменных** — прозрачно преобразует внутренние ссылки на цвета в стандартизированные имена CSS-переменных (например, `--design-palette-theme-color`).

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

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

**Параметры:**
- `items: PropertiesItems` — экземпляр координационного класса, отвечающего за обход и поиск в дереве свойств.

```typescript
import { PropertiesPalette, PropertiesItems } from '@dxtmisha/scripts'

// 1. Подготовка необходимого координатора
const manager = new PropertiesItems(allTokenData)

// 2. Создание менеджера палитры
const palette = new PropertiesPalette(manager)

// 3. Извлечение активных оттенков или используемых цветов
const shades = palette.getShade()
const usedColors = palette.getUsed()
```

## Методы

### `getShade`
Извлекает список доступных уровней насыщенности (оттенков), сгруппированных по дизайну. Метод сканирует все дерево свойств на наличие элементов, классифицированных именно как 'shade' (оттенок), и возвращает их разрешенные структуры. Эти оттенки обычно представляют числовую шкалу насыщенности цвета (например, 50, 100, 200), используемую в дизайн-системе.

**Возвращает:** `PropertyPaletteList` — специализированный объект, где ключами являются названия дизайнов, а значениями — массивы токенов оттенков цветов.

```typescript
const shades = palette.getShade();
// Результат: { "basic": ["50", "100", ...], "premium": ["50", ...] }
```

### `getUsed`
Генерирует исчерпывающий отчет обо всех цветах палитры, используемых в данный момент в функциональных переменных во всей системе дизайна. Он выполняет итерацию по всем токенам, идентифицируя ссылки на CSS-переменные, которые указывают на записи палитры, и сопоставляет их с сгенерированными именами CSS-переменных. Это необходимо для аудита использования цветов и выявления неиспользуемых записей палитры.

**Возвращает:** `PropertyPaletteUsed[]` — массив объектов, каждый из которых содержит имя функциональной переменной и соответствующее ей имя CSS-переменной, производное от палитры.

```typescript
const report = palette.getUsed();
/* Результат: 
[
  { "name": "primaryBackground", "value": ["--basic-palette-basic-blue-50"] }
] 
*/
```

### `getFocusUsed`
Рекурсивно разрешает конкретное значение свойства для определения его конечного источника в палитре. Этот вспомогательный метод используется для отслеживания ссылок через несколько уровней абстракции (например, переменные компонентов, указывающие на цвета темы, которые, в свою очередь, указывают на оттенки палитры).

**Параметры:**
- `list: PropertyItem['value'][]` — список известных значений палитры для проверки в процессе разрешения.
- `design: string` — название текущей темы дизайна.
- `component: string` — имя контекста компонента, для которого выполняется разрешение.
- `value: string` — необработанное значение или ссылка (например, `{color.primary}`) для отслеживания до палитры.

**Возвращает:** `string | undefined` — конечная разрешенная строка значения, если она ведет к записи в палитре; в противном случае — `undefined`.

```typescript
const source = palette.getFocusUsed(
  paletteList, 
  'basic', 
  'button', 
  '{color.primary}'
);
```

## Операции

### Поток разрешения использования цветов

`PropertiesPalette` выполняет глубокий анализ того, как цвета переходят из палитры к компонентам:
1. **Обход дерева**: Используя `PropertiesItems.each()`, класс посещает каждый узел в системе дизайна.
2. **Фильтрация переменных**: Он нацелен именно на элементы типа `var`, которые сами не классифицируются как `color`, но содержат строковые значения, похожие на ссылки на цвета.
3. **Рекурсивное разрешение ссылок**: При обнаружении кандидата `getFocusUsed()` разрешает любые промежуточные ссылки (например, `primary` -> `theme.brand.main` -> `palette.blue.50`), пока не достигнет необработанного определения палитры или не подтвердит, что ссылка не относится к палитре.
4. **Определение темы**: Он исследует иерархию (`parents`), чтобы определить, принадлежит ли цвет конкретному блоку темы, что позволяет правильно назвать результирующую CSS-переменную (например, добавив имя темы в начало).
5. **Агрегация данных**: Результаты группируются по имени переменной, предоставляя четкую карту того, какие функциональные токены потребляют те или иные цвета палитры.

## Примеры

### Извлечение оттенков и использования
```typescript
import { PropertiesPalette, PropertiesItems } from '@dxtmisha/scripts'

const manager = new PropertiesItems(allTokenData)
const palette = new PropertiesPalette(manager)

// 1. Получение доступных оттенков
const shades = palette.getShade()

// 2. Сканирование используемых цветов в компонентах
const report = palette.getUsed()
```

### Ручное разрешение ссылки
```typescript
const isPaletteValue = palette.getFocusUsed(
  paletteValueList, 
  'basic', 
  'button', 
  '{color.primary}'
)
```
