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

<Meta title='@dxtmisha/ru/scripts/Classes/PropertiesTool - Утилиты свойств'/>

# Класс PropertiesTool

Класс `PropertiesTool` предоставляет набор статических утилит для работы с именованием компонентов, путями и чтением файлов конфигурации дизайн-системы. Он служит вспомогательным инструментом для других классов, обеспечивая единообразие в формировании имен и доступ к файловым ресурсам.

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

- **Стандартизация имен** — формирует единообразные названия компонентов и CSS-классов (camelCase).
- **Работа с конструктором** — содержит логику для идентификации и загрузки базовых свойств конструктора.
- **Интеграция с кэшем** — обеспечивает эффективное чтение файлов свойств через систему кэширования.
- **Гибкая конфигурация** — получает список активных дизайнов напрямую из настроек окружения.

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

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

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

// Прямой вызов статических методов
const isConst = PropertiesTool.isConstructor('basic')
```

## Методы

### `isConstructor`
Проверяет, соответствует ли переданное имя дизайна ключу конструктора системы. Это необходимо для отделения базовых мета-свойств от свойств конкретных тем оформления.

**Параметры:**
- `design: string` — проверяемое название дизайна.

**Возвращает:** `boolean` — `true`, если дизайн является конструктором.

```typescript
const result = PropertiesTool.isConstructor('dxt.constructor');
// Результат: true
```

### `getDesigns`
Возвращает список идентификаторов дизайнов, доступных в текущей среде. Список включает как системный конструктор, так и дизайн, указанный в основных настройках проекта.

**Возвращает:** `string[]` — массив названий дизайнов.

```typescript
const list = PropertiesTool.getDesigns();
// Результат: ['dxt.constructor', 'my-project-design']
```

### `getComponentName`
Формирует нормализованную строку имени компонента, объединяя название дизайна и имя самого компонента. Имя компонента автоматически преобразуется в `camelCase`.

**Параметры:**
- `design: string` — название дизайна.
- `component: string` (опционально) — название компонента.

**Возвращает:** `string` — сформированное имя (например, `designName-componentName`).

```typescript
const name = PropertiesTool.getComponentName('basic', 'button-primary');
// Результат: "basic-buttonPrimary"
```

### `getClassName`
Аналогичен `getComponentName`, но возвращает строку в формате CSS-селектора класса (с точкой в начале).

**Параметры:**
- `design: string` — название дизайна.
- `component: string` (опционально) — название компонента.

**Возвращает:** `string` — строка CSS-класса.

```typescript
const selector = PropertiesTool.getClassName('basic', 'button');
// Результат: ".basic-button"
```

### `readFile`
Считывает и возвращает список свойств (tokens) из файловой системы. Для конструктора возвращает копию базовых свойств из `properties.json`, для остальных — считывает файл свойств через системный кэш.

**Параметры:**
- `design: string` — название дизайна.
- `path: string[] | undefined` — путь к директории с файлом.

**Возвращает:** `PropertyList | undefined` — объект со свойствами или `undefined`, если путь не указан.

```typescript
const data = PropertiesTool.readFile('basic', ['src', 'theme', 'settings', 'button']);
```

## Операции

### Механизм разрешения имен

1. **Трансформация регистра**: Все входные имена компонентов перед объединением проходят через `toCamelCase`.
2. **Префиксация**: Публичные методы всегда добавляют имя дизайна в начало, что предотвращает коллизии стилей при использовании нескольких тем одновременно.
3. **Безопасное чтение**: При чтении файлов через `readFile` для конструктора используется глубокое копирование (`copyObject`), что исключает случайную мутацию глобальных базовых настроек в процессе работы других инструментов.

## Примеры

### Формирование CSS-класса для динамического компонента
```typescript
import { PropertiesTool } from '@dxtmisha/scripts'

const design = 'basic'
const component = 'input-field'

const className = PropertiesTool.getClassName(design, component)
// Результат: .basic-inputField
```
