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

<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesKeys - Семантический трансформер ключей'/>

# Класс PropertiesKeys

Класс `PropertiesKeys` — это специализированная статическая утилита, предназначенная для парсинга и трансформации семантического значения ключей токенов дизайна. Он выступает в роли «грамматического движка» для имен свойств, различая ключи функциональных данных и ключи архитектурных метаданных. Предоставляя механизмы нормализации, типизированного добавления префиксов и обнаружения специальных символов, он гарантирует, что ключи токенов остаются последовательными и предсказуемыми независимо от их исходного формата (JSON, SCSS или внутреннее состояние).

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

- **Идентификация метаданных** — обнаруживает защищенные системные ключи, такие как `value`, `type`, и внутренние свойства, начинающиеся с подчеркивания.
- **Нормализация префиксов** — автоматически удаляет архитектурные символы (такие как `=` или `|`) для извлечения чистого семантического имени.
- **Оркестрация регистра** — интегрируется с `toCamelCase` для поддержания единых соглашений об именовании во всем дереве токенов.
- **Типизированное переименование (Re-keying)** — динамически преобразует ключи на основе их категории (например, добавляя `media-` к токенам медиа или `container-` к контейнерным запросам).
- **Совместимость с SCSS** — обрабатывает специальное форматирование для ключей, совместимых с SCSS, включая ведущие амперсанды.

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

Являясь статическим сервисным классом, `PropertiesKeys` не требует создания экземпляра и готов к использованию сразу после импорта.

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

// Проверка, является ли ключ полем метаданных
const isReserved = PropertiesKeys.isSpecialKey('type')

// Получение чистого семантического имени
const cleanName = PropertiesKeys.getName('=primary-color')
// Возвращает: "primaryColor"
```

## Методы

- `isSpecialKey(key): boolean` — проверяет, является ли ключ зарезервированным системным полем метаданных.
- `isFull(name): boolean` — определяет, является ли имя абсолютным/полным определением.
- `getName(name, camelCase?): string` — нормализует ключ, удаляя префиксы и опционально применяя camelCase.
- `reKey(key, type?): string` — преобразует ключ на основе его архитектурного типа (media, container, scss и т.д.).

## Операции

### Конвейер трансформации ключей

`PropertiesKeys` управляет логикой перевода между необработанными входными форматами и стандартизированными внутренними токенами:
1. **Семантическое извлечение**: При вызове `getName()` класс использует регулярные выражения `PropertiesTypes` для идентификации и удаления управляющих символов (таких как `=`, означающий неизменяемое значение).
2. **Контекстное добавление префиксов**: В потоке `reKey()` класс проверяет `_type` токена. Если идентифицирован тип `media`, он интеллектуально гарантирует, что ключ отражает эту роль (например, `desktop` становится `mediaDesktop`), избегая избыточных префиксов, если они уже существуют.
3. **Защита внутреннего состояния**: Проверка `isSpecialKey()` критически важна для движков обхода; она предотвращает обработку внутренних механизмов (ключи, начинающиеся с `_`) как если бы они были реальными токенами дизайна, определенными пользователем.
4. **Адаптация под платформы**: Для генерации SCSS класс специально обрабатывает добавление префикса `&`, позволяя использовать токены дизайна напрямую во вложенных объявлениях стилей.
