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

<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesWrap - Оптимизация структуры'/>

# Класс PropertiesWrap

Класс `PropertiesWrap` предназначен для автоматической оптимизации структуры токенов в дизайн-системе. Его основная задача — находить повторяющиеся значения свойств на одном уровне вложенности и выносить их на родительский уровень. Это позволяет существенно сократить объем JSON/JS конфигов и упростить их поддержку.

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

- **Устранение дубликатов** — автоматически выносит общие свойства группы компонентов выше по иерархии.
- **Рекурсивная оптимизация** — обрабатывает дерево свойств на любую глубину.
- **Умное слияние** — находит свойства с максимальным количеством повторений для наиболее эффективного сжатия структуры.
- **Прозрачность** — использует системный ключ `wrap` для идентификации блоков, требующих оптимизации.

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

Класс предоставляет статические методы и не требует создания экземпляра через `new`.

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

// Оптимизация структуры свойств (мутирует исходный объект)
PropertiesWrap.to(myProperties)
```

## Методы

### `to`
Статический метод, который запускает процесс оптимизации. Он обходит дерево свойств и, если встречает блок с флагом `_wrap`, анализирует его содержимое. Если внутри блока обнаружены идентичные свойства у дочерних элементов, они будут вынесены на уровень текущего блока, а дубликаты у дочерних элементов — удалены.

**Параметры:**
- `properties: PropertyList` — объект со списком свойств, который необходимо оптимизировать.

```typescript
const tokens = {
  button: {
    _wrap: true,
    value: {
      primary: { value: { padding: '10px', color: 'red' } },
      secondary: { value: { padding: '10px', color: 'blue' } }
    }
  }
};

PropertiesWrap.to(tokens);

/* Результат оптимизации:
{
  button: {
    padding: '10px', // Вынесено на уровень выше
    value: {
      primary: { value: { color: 'red' } },
      secondary: { value: { color: 'blue' } }
    }
  }
}
*/
```

## Операции

### Алгоритм оптимизации (How it works)

Процесс сжатия структуры проходит через следующие этапы:
1. **Поиск флага**: Система ищет в объекте свойство `_wrap` (определено в `PropertyKey.wrap`).
2. **Сбор статистики (getSelectors)**: Если флаг найден, класс собирает информацию о всех свойствах дочерних элементов (названия и их значения).
3. **Анализ повторов (getMaxRepeat)**: Определяется свойство, которое чаще всего встречается с одним и тем же значением.
4. **Перенос данных**: Найденное общее свойство добавляется в текущий (родительский) блок.
5. **Очистка (removeProperties)**: Данное свойство удаляется из всех дочерних элементов, где оно имело идентичное значение.
6. **Завершение**: Флаг `_wrap` удаляется из объекта.

## Примеры

### Сжатие конфигурации темы
```typescript
import { PropertiesWrap } from '@dxtmisha/scripts'

const designData = {
  typography: {
    _wrap: true,
    value: {
      h1: { value: { 'font-family': 'Inter', 'font-size': '32px' } },
      h2: { value: { 'font-family': 'Inter', 'font-size': '24px' } },
      p: { value: { 'font-family': 'Inter', 'font-size': '16px' } }
    }
  }
}

PropertiesWrap.to(designData)
// Результат: 'font-family': 'Inter' будет вынесен в корень объекта typography
```
