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

<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesSeparator - Разделение свойств'/>

# Класс PropertiesSeparator

Класс `PropertiesSeparator` предназначен для автоматического преобразования плоской структуры токенов с составными именами (использующими разделители) в иерархическую структуру вложенных объектов. Это позволяет организовывать свойства логически, например, превращая `button.primary.background` в `{ button: { primary: { background: ... } } }`.

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

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

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

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

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

// Использование статических методов
const results = PropertiesSeparator.to(rawProperties)
```

## Методы

### `is`
Статический метод для быстрой проверки, содержит ли предоставленный список свойств ключи, требующие разделения. Он сканирует верхний уровень (и вложенные уровни до предела `limit`) на наличие символов-разделителей в именах.

**Параметры:**
- `properties: PropertyList` — список свойств для анализа.
- `limit: number` — максимальная глубина проверки (по умолчанию берется из `PropertiesConfig`).

**Возвращает:** `boolean` — `true`, если хотя бы один ключ содержит разделитель.

```typescript
const needsSplitting = PropertiesSeparator.is(myProperties);
// Результат: true, если есть ключи типа "color.blue.50"
```

### `to`
Статический метод, который выполняет фактическую трансформацию плоского списка свойств во вложенную структуру. Метод рекурсивно обходит все элементы и, если находит ключ с разделителем, «оборачивает» свойство в цепочку вложенных объектов согласно сегментам имени.

**Параметры:**
- `properties: PropertyList` — список свойств для трансформации.

**Возвращает:** `PropertyList` — новый список свойств с иерархической структурой.

```typescript
const nestedProperties = PropertiesSeparator.to({
  'palette.blue.50': { value: '#e3f2fd' }
});
/* Результат:
{
  palette: {
    value: {
      blue: {
        value: {
          '50': { value: '#e3f2fd', __wrap: true }
        }
      }
    }
  }
}
*/
```

## Операции

### Механизм разделения имен

Процесс трансформации в `PropertiesSeparator` проходит следующие этапы:
1. **Обнаружение разделителя**: Метод `to` проверяет имя каждого свойства через `PropertiesKeys.isSeparator`.
2. **Сегментация**: Если разделитель найден, имя разбивается на части (например, `a.b.c` -> `['a', 'b', 'c']`). Перед этим удаляются лишние технические символы через `removeBasicName`.
3. **Обертывание (Wrapping)**: Метод `wrap` рекурсивно создает вложенные объекты `value`, помещая оригинальный элемент свойства в самый глубокий уровень. При этом промежуточным объектам добавляется флаг `__wrap: true`, указывающий на их служебный характер.
4. **Рекурсивное слияние**: Полученная «ветка» объединяется с основным объектом `data` через `replaceRecursive`, что позволяет нескольким свойствам с одной базой (например, `blue.50` и `blue.100`) корректно собраться в одном объекте `blue`.

## Примеры

### Группировка цветов палитры
```typescript
import { PropertiesSeparator } from '@dxtmisha/scripts'

const flatPalette = {
  'blue.50': { value: '#eef' },
  'blue.100': { value: '#ccf' }
}

const tree = PropertiesSeparator.to(flatPalette)
// Свойства теперь сгруппированы в объекте tree.blue.value
```
