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

<Meta title='@dxtmisha/ru/scripts/Classes/StylesTool - Утилиты для обработки стилей'/>

# Класс StylesTool

Класс `StylesTool` представляет собой статическое хранилище утилит высокого уровня, предоставляющее основные функции для конвейера генерации стилей дизайн-системы. Он инкапсулирует логику управления директориями, контроля отступов, создания директив SCSS и преобразований для совместимости с Sass.

Централизуя эти низкоуровневые манипуляции со строками и поиск путей, класс обеспечивает согласованность во всех преобразователях `StylesTo*` и классах-генераторах.

## Ключевые возможности

- **Контроль отступов** — предоставляет стандартную единицу отступа (2 пробела) и методы для её масштабирования в зависимости от уровня вложенности.
- **Построители директив** — стандартизирует синтаксис для операторов SCSS `@use`, `@import` и `@forward`.
- **Определение путей** — интегрируется с глобальной конфигурацией для определения места назначения генерируемых файлов.
- **Совместимость с Sass** — выполняет автоматическое преобразование синтаксиса пользовательских CSS-функций в безопасную интерполяцию Sass.
- **Вертикальное форматирование** — управляет объединением строк с использованием символов CRLF для совместимости между Windows и UNIX.

## Методы работы с файлами и директориями

### `getDir`

Определяет структуру целевой директории для сохранения сгенерированных файлов стилей. Объединяет основной каталог стилей со специфическим именем проекта, определенным в конфигурации свойств.

**Возвращает:** `string[]` — Массив, представляющий сегменты пути целевой директории.

## Методы работы с отступами

### `getSpace`

Возвращает базовую единицу отступа, используемую во всех сгенерированных файлах стилей проекта.

**Возвращает:** `string` — Строка, состоящая из 2 пробелов (`  `).

### `addSpace`

Генерирует строку отступа на основе указанного уровня вложенности. Используется для выравнивания блоков кода внутри вложенных структур, таких как медиа-запросы или блоки селекторов.

**Параметры:**
- `level: number` — Желаемый уровень вложенности (0 — без отступа, 1 — 2 пробела, 2 — 4 пробела и т.д.).

**Возвращает:** `string` — Результирующая строка отступа.

### `increaseSpace`

Добавляет один дополнительный уровень отступа (2 пробела) к существующей строке отступов. Полезно при рекурсивном обходе дерева, где глубина увеличивается постепенно.

**Параметры:**
- `space: string` — Текущая строка отступа, которую необходимо расширить.

**Возвращает:** `string` — Обновленная строка отступа с одним дополнительным уровнем.

## Методы директив SCSS

### `addImport`

Создает стандартную директиву SCSS `@import` для заданного пути к файлу.

**Параметры:**
- `path: string` — Путь к импортируемому файлу.

**Возвращает:** `string` — Отформатированная директива (например, `@import "path/to/file";`).

### `addUse`

Создает современную директиву SCSS `@use`, которая является рекомендуемым способом загрузки функций, миксинов и переменных в современном Sass.

**Параметры:**
- `path: string` — Путь к модулю.

**Возвращает:** `string` — Отформатированная директива (например, `@use "path/to/module";`).

### `addForward`

Создает директиву SCSS `@forward`. Обычно используется в индексных файлах для предоставления доступа к членам подмодуля пользователям пакета.

**Параметры:**
- `path: string` — Путь к пересылаемому модулю.

**Возвращает:** `string` — Отформатированная директива (например, `@forward "path/to/module";`).

### `addImportProperties`

Генерирует специализированную директиву `@use` для основной библиотеки `@dxtmisha/styles`, создавая псевдоним `ui` для использования в сгенерированных блоках свойств.

**Возвращает:** `string` — Всегда возвращает `'@use "@dxtmisha/styles" as ui;'`.

## Форматирование и утилиты

### `join`

Объединяет массив сгенерированных строк кода в одну отформатированную строку. Использует CRLF (`\r\n`) в качестве разделителя строк для обеспечения единообразного форматирования в различных средах.

**Параметры:**
- `data: string[]` — Массив строк, представляющих отдельные строки кода.

**Возвращает:** `string` — Результирующая многострочная строка.

### `toFunctionCss`

Утилита безопасности, которая преобразует вызовы пользовательских функций `@function` внутри значений свойств CSS в синтаксис интерполяции Sass (`#{...}`). Это предотвращает ошибки компиляции Sass, когда пользовательские функции используются в контекстах, требующих чистого вывода CSS.

**Параметры:**
- `value: string` — Строка значения свойства CSS, содержащая потенциальные вызовы пользовательских функций.

**Возвращает:** `string` — Преобразованная строка с интерполированными вызовами функций.

## Пример использования

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

// 1. Получение уровня отступа
const indent = StylesTool.addSpace(2) // "    "

// 2. Создание импорта SCSS
const importLine = StylesTool.addImport('../tokens/colors')

// 3. Преобразование вызова пользовательской функции
const safeValue = StylesTool.toFunctionCss('@getOpacity(0.5)') // "#{getOpacity(0.5)}"

// 4. Объединение строк
const fileContent = StylesTool.join([
  StylesTool.addImportProperties(),
  importLine,
  `.element {`,
  `${indent}color: red;`,
  `}`
])
```
