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

<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesStandard - Стандартизация свойств'/>

# Класс PropertiesStandard

Класс `PropertiesStandard` является центральным механизмом нормализации данных в дизайн-системе. Его основная задача — преобразовывать «сырые» входные данные токенов (которые могут быть представлены строками, числами или упрощенными объектами) в строго типизированную структуру `PropertyItem`, с которой могут работать остальные инструменты системы.

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

- **Нормализация данных** — гарантирует, что каждое свойство имеет стандартизированный набор полей (`value`, `type`, `index` и др.).
- **Рекурсивная обработка** — автоматически стандартизирует вложенные структуры объектов.
- **Автоматическое определение типов** — пытается определить тип свойства на основе его имени (через `PropertiesTypes`).
- **Интеллектуальный парсинг** — различает обычные значения и специальные мета-свойства (начинающиеся с `__`).
- **Слияние данных** — корректно объединяет новые данные с существующими, сохраняя целостность структуры.

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

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

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

// Вызов статического метода
const standardized = PropertiesStandard.to(rawInput)
```

## Методы

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

**Параметры:**
- `properties: PropertyListOrData` — входные данные свойств в любом поддерживаемом формате.

**Возвращает:** `PropertyList` — объект, в котором каждый элемент приведен к стандарту `PropertyItem`.

```typescript
const result = PropertiesStandard.to({
  'primary-color': '#007bff',
  'padding': { value: 16, type: 'size' }
});

/* Результат:
{
  'primary-color': { 
    value: '#007bff', 
    type: 'color', 
    index: 'primary-color' 
  },
  'padding': { 
    value: '16px', 
    type: 'size', 
    index: 'padding' 
  }
}
*/
```

## Операции

### Алгоритм стандартизации (getItem)

При обработке каждого элемента выполняются следующие шаги:
1. **Преобразование в объект**: Метод `toItem` проверяет тип входного значения. Если это строка или массив, они оборачиваются в объект `{ value: ... }`.
2. **Разделение мета-данных**: Метод `getValueAndSpecial` отделяет полезное значение (`value`) от специальных ключей управления (например, `__custom`).
3. **Определение типа**: Если тип не указан явно, метод `addType` пытается вычислить его по имени ключа.
4. **Проверка на финальность**: Метод `addFull` добавляет метки `fullName` или `fullValue`, если данные не требуют дальнейшей обработки (например, для уже разрешенных ссылок).
5. **Преобразование значений**: Через `addValue` все числовые значения переводятся в строки с добавлением единиц измерения там, где это необходимо.
6. **Регистрация индекса**: Каждому элементу присваивается очищенный `index` для быстрой обратной связи.

## Примеры

### Стандартизация сложной структуры
```typescript
import { PropertiesStandard } from '@dxtmisha/scripts'

const data = {
  header: {
    height: 60,
    background: '{color.white}'
  }
}

const standardData = PropertiesStandard.to(data)
// Теперь все поля в standardData.header.value имеют правильную структуру PropertyItem
```
