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

<Meta title='@dxtmisha/ru/scripts/Classes/DesignReplace - Движок трансформации шаблонов'/>

# Класс DesignReplace

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

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

- **Интеллектуальное разрешение меток** — идентифицирует и заменяет блоки текста, ограниченные специфическими комментариями (например, `// :type` или `<!-- :props -->`).
- **Контекстное именование** — автоматически преобразует универсальные плейсхолдеры, такие как `[project]`, `[design]` и `[component]`, на основе конфигурации.
- **Внедрение типов** — генерирует сложные объединения типов TypeScript и интерфейсы непосредственно из метаданных свойств.
- **Маппинг значений по умолчанию** — разрешает и внедряет значения по умолчанию для свойств в объектные литералы или аргументы конструктора.
- **Условная генерация классов** — создает оптимизированные объекты привязки классов Vue/TS и маппинги селекторов CSS.
- **Нормализация путей** — автоматически разрешает относительные пути импорта в зависимости от расположения целевого файла в дереве проекта.

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

Для инициализации движка замены передайте структуру данных компонента, идентификатор целевой метки и строку шаблона.

**Параметры:**
- `structure: DesignStructure` — источник истины для метаданных компонента и структурных правил.
- `mark: string` — основная метка, используемая в шаблонах для идентификации компонентов (например, `'button'`).
- `sample: string` — текстовое содержимое шаблона для модификации.

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

const engine = new DesignReplace(structure, 'button', templateContent)
engine.replaceName().replaceType()
const output = engine.get()
```

## Методы

### Управление

- `get(): string` — возвращает финальную версию шаблона после всех преобразований.
- `getNameFile(name: string): string` — обрабатывает имя файла или строку для замены плейсхолдеров уровня проекта.
- `replaceName(): this` — заменяет основные метки имени компонента во всем шаблоне.
- `replacePath(): this` — исправляет относительные пути (`../../../`), чтобы они указывали на правильное корневое расположение проекта.
- `replaceMark(name: string, data: string[], end = ''): this` — выполняет блочную замену для конкретной метки, внедряя массив строк.
- `replaceOnce(name?: string, removeReplacement?: boolean | Function): this` — обрабатывает одноразовые маркеры замены (`.once`).

### Автоматизация свойств и типов

- `replaceType(constructor?: string): this` — генерирует и внедряет типы TypeScript для всех свойств компонента.
- `replaceDefault(): this` — внедряет значения по умолчанию для свойств в шаблон.
- `replaceProps(): this` — генерирует объекты определения свойств в стиле Vue.
- `replacePropsValues(): this` — создает массивы допустимых значений для свойств (enums/unions).

### Стилизация и классы

- `replaceClasses(template?: Function, end = ''): this` — генерирует список доступных CSS-классов на основе структуры.
- `replaceClassesValues(): this` — создает логику динамической привязки классов для файлов реализации логики.
- `replaceStylesValues(): this` — сопоставляет свойства компонента с пользовательскими переменными CSS (CSS Variables).
- `replaceConstructorClasses(): this` — специализированный генератор классов для конструкторов компонентов.

## Операции

### Система меток

Движок сканирует специфические паттерны комментариев, чтобы определить, куда внедрять код. Поддерживаются несколько стилей комментариев:

1. **Инлайн логика**: `// :label data` или `/* :label */ content /* :label.end */`
2. **Комментарии шаблонов**: `<!-- :label --> content <!-- :label.end -->`
3. **Специфичность свойств**: `:label.propertyName.none` (используется для исключения конкретных свойств из блока).

### Поток трансформации

При вызове метода замены, такого как `replaceType()`, класс:
1. **Сканирует**: находит начальный и конечный маркеры для метки `type`.
2. **Обращается к структуре**: итерирует по свойствам в предоставленной `DesignStructure`.
3. **Разрешает логику**: определяет правильный синтаксис TypeScript для каждого свойства на основе типа его значения (boolean, string или union).
4. **Внедряет**: заменяет содержимое между маркерами новым сгенерированным кодом, сохраняя исходные отступы.
