# RazorConsole — Встроенные компоненты

Полный справочник по 25+ компонентам, поставляемым с `RazorConsole.Core`.  
Каждый компонент транслируется в `IRenderable` Spectre.Console во время рендеринга.

> Параметры, отмеченные ⚠️, являются обязательными.

---

## Макет (Layout)

### Align

Выравнивает дочерний контент горизонтально и вертикально.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `ChildContent` | `RenderFragment?` | — | Вложенный контент |
| `Horizontal` | `HorizontalAlignment` | `Left` | `Left`, `Center`, `Right` |
| `Vertical` | `VerticalAlignment` | `Top` | `Top`, `Middle`, `Bottom` |
| `Width` | `int?` | `null` | Фиксированная ширина в символах |
| `Height` | `int?` | `null` | Фиксированная высота в строках |

---

### Columns

Располагает дочерние элементы горизонтально (колонками).

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `ChildContent` | `RenderFragment?` | — | Элементы колонок |
| `Expand` | `bool` | `false` | Растянуть на всю ширину консоли |

---

### Rows

Стекует дочерние элементы вертикально.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `ChildContent` | `RenderFragment?` | — | Элементы строк |
| `Expand` | `bool` | `false` | Растянуть на всю высоту |

---

### FlexBox

CSS-подобный flexbox-макет с настройкой направления, выравнивания и переноса.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `ChildContent` | `RenderFragment?` | — | Элементы контейнера |
| `Direction` | `FlexDirection` | `Row` | `Row` (горизонталь) или `Column` (вертикаль) |
| `Justify` | `FlexJustify` | `Start` | `Start`, `End`, `Center`, `SpaceBetween`, `SpaceAround`, `SpaceEvenly` |
| `Align` | `FlexAlign` | `Start` | `Start`, `End`, `Center`, `Stretch` |
| `Wrap` | `FlexWrap` | `NoWrap` | `NoWrap`, `Wrap` |
| `Gap` | `int` | `0` | Отступ между элементами (символы / строки) |
| `Width` | `int?` | `null` | Явное ограничение ширины |
| `Height` | `int?` | `null` | Явное ограничение высоты |

---

### Grid

Многострочный многоколоночный макет с точным управлением ячейками.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `ChildContent` | `RenderFragment?` | — | Строки и ячейки сетки |
| `Columns` | `int` | `2` | Количество колонок |
| `Expand` | `bool` | `false` | Растянуть на доступную ширину |
| `Width` | `int?` | `null` | Фиксированная ширина |

---

### Padder

Добавляет внешние отступы вокруг дочернего контента.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `ChildContent` | `RenderFragment?` | — | Внутренний контент |
| `Padding` | `Padding` | `new(0,0,0,0)` | Отступы (left, top, right, bottom) |

---

### Scrollable

Постраничный скроллинг для типизированных коллекций с поддержкой клавиатуры.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `Items` | `IReadOnlyList<TItem>` | `Array.Empty<TItem>()` | Источник данных |
| `PageSize` | `int` | `1` | Элементов на странице |
| `ChildContent` | `RenderFragment<ScrollContext<TItem>>` | — | Разметка видимой страницы |
| `ScrollOffset` | `int` | `0` | Двусторонний: индекс начала страницы |
| `ScrollOffsetChanged` | `EventCallback<int>` | — | Срабатывает при смене offset |
| `IsScrollbarEmbedded` | `bool` | `true` | Встроить скроллбар внутрь `Table`/`Panel`/`Border` |

#### ScrollContext\<TItem\>

| Член | Тип | Описание |
|---|---|---|
| `this[int i]` | `TItem` | Видимый элемент по индексу |
| `Count` | `int` | Количество видимых элементов |
| `KeyDownEventHandler` | `Func<KeyboardEventArgs,Task>` | Привязать через `@onkeydown` |
| `CurrentOffset` | `int` | Текущий scroll offset |
| `PagesCount` | `int` | Всего страниц |

---

### ViewHeightScrollable

Постраничный скроллинг произвольного `RenderFragment` по строкам (без типизированных данных).

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `ChildContent` | `RenderFragment<ScrollContext>` | — | ⚠️ Контент вьюпорта |
| `LinesToRender` | `int` | `10` | Высота вьюпорта в строках |
| `ScrollOffset` | `int` | `0` | Двусторонний: индекс первой видимой строки |
| `ScrollOffsetChanged` | `EventCallback<int>` | — | Срабатывает при скролле |
| `Scrollbar` | `ScrollbarSettings?` | `null` | Настройки скроллбара |
| `IsScrollbarEmbedded` | `bool` | `true` | Встроить скроллбар внутрь border-компонента |

**Горячие клавиши:** `↑`/`↓` — одна строка, `PageUp`/`PageDown`/`Space` — страница, `Home`/`End` — границы.

#### ScrollbarSettings

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `TrackChar` | `char` | `'│'` | Символ дорожки |
| `ThumbChar` | `char` | `'█'` | Символ ползунка |
| `TrackColor` | `Color` | `Color.Grey` | Цвет дорожки |
| `ThumbColor` | `Color` | `Color.White` | Цвет ползунка |
| `TrackFocusedColor` | `Color` | `Color.Grey74` | Цвет дорожки при фокусе |
| `ThumbFocusedColor` | `Color` | `Color.DeepSkyBlue1` | Цвет ползунка при фокусе |
| `MinThumbHeight` | `int` | `1` | Минимальная высота ползунка |

---

## Ввод (Input)

### TextInput

Поле ввода текста с placeholder, маскированием и управлением фокусом.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `Value` | `string?` | `null` | Двустороннее связывание текста |
| `ValueChanged` | `EventCallback<string?>` | — | Срабатывает при изменении |
| `OnInput` | `EventCallback<string?>` | — | Срабатывает при каждом нажатии |
| `Placeholder` | `string?` | `null` | Текст-подсказка |
| `MaskInput` | `bool` | `false` | Маскирование символов (пароли) |
| `FocusOrder` | `int?` | `null` | Порядок фокуса |

---

### TextButton

Кликабельная кнопка с изменением цвета при фокусе.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `Content` | `string` | `string.Empty` | Текст кнопки |
| `BackgroundColor` | `Color` | `Color.Default` | Фон в нормальном состоянии |
| `FocusedColor` | `Color` | `Color.DeepSkyBlue1` | Фон при фокусе |
| `OnClick` | `EventCallback` | — | Срабатывает при нажатии |
| `FocusOrder` | `int?` | `null` | Порядок фокуса |

---

### Select

Интерактивный выпадающий список с клавиатурной навигацией.

**Основные параметры:**

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `Options` | `string[]` | `Array.Empty<string>()` | Доступные варианты |
| `Value` | `string?` | `null` | Текущий выбор |
| `ValueChanged` | `EventCallback<string>` | — | Срабатывает при смене |
| `OnSelected` | `EventCallback<string?>` | — | Срабатывает при подтверждении |
| `OnClear` | `EventCallback` | — | Срабатывает при очистке |
| `Placeholder` | `string` | `"Select an option"` | Текст при отсутствии выбора |
| `Expand` | `bool` | `false` | Растянуть горизонтально |
| `FocusOrder` | `int?` | `null` | Порядок фокуса |
| `BorderStyle` | `BoxBorder` | `Rounded` | Стиль рамки |

**Клавиатура:** стрелки, `Space` для переключения, `Enter` для подтверждения, `Escape` для отмены, буквы для быстрого перехода.

---

## Отображение (Display)

### Markup

Стилизованный текст с тегами разметки Spectre.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `Content` ⚠️ | `string` | — | Текст (автоматически экранируется) |
| `Foreground` | `Color` | `Style.Plain.Foreground` | Цвет текста |
| `Background` | `Color` | `Style.Plain.Background` | Цвет фона |
| `Decoration` | `Decoration` | `None` | `Bold`, `Italic`, `Underline` и др. |
| `link` | `string?` | `null` | Гиперссылка |

---

### Markdown

Рендеринг markdown-строки в консоль.

| Параметр | Тип | Описание |
|---|---|---|
| `Content` ⚠️ | `string` | Markdown-текст для отображения |

---

### Panel

Обёртка Spectre.Console Panel с заголовком и рамкой.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `ChildContent` | `RenderFragment?` | — | Содержимое панели |
| `Title` | `string?` | `null` | Заголовок панели |
| `TitleColor` | `Color?` | `null` | Цвет заголовка |
| `BorderColor` | `Color?` | `null` | Цвет рамки |
| `Border` | `BoxBorder?` | `null` | Стиль рамки |
| `Height` | `int?` | `null` | Фиксированная высота |
| `Width` | `int?` | `null` | Фиксированная ширина |
| `Padding` | `Padding?` | `null` | Внутренние отступы |
| `Expand` | `bool` | `false` | Растянуть на ширину |

---

### Border

Рамка вокруг дочернего контента (без заголовка).

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `ChildContent` | `RenderFragment?` | — | Контент внутри рамки |
| `BorderColor` | `Color?` | `null` | Цвет рамки |
| `BoxBorder` | `BoxBorder` | `Rounded` | Стиль рамки |
| `Padding` | `Padding` | `new(0,0,0,0)` | Внутренние отступы |

---

### Table

HTML-подобная таблица, транслируемая в Spectre.Console `Table`.

> Ключевая идея: используйте стандартные `<table>`, `<thead>`, `<tbody>`, `<tfoot>`, `<tr>`, `<th>`, `<td>`.

| Атрибут | Тип | По умолчанию | Описание |
|---|---|---|---|
| `class="table"` ⚠️ | — | — | Обязательный хук для транслятора |
| `data-expand` | `bool` | `false` | Растянуть на ширину консоли |
| `data-width` | `int?` | `null` | Фиксированная ширина |
| `data-title` | `string?` | `null` | Подпись таблицы |
| `data-border` | `TableBorderStyle` | `None` | Стиль рамки |
| `data-show-headers` | `bool` | `true` | Показывать заголовки |

Выравнивание колонок: атрибут `data-align="left|center|right"` на `<th>`.

```razor
<table class="table" data-border="Square" data-expand="true" data-title="Build status">
  <thead>
    <tr>
      <th data-align="left">Stage</th>
      <th data-align="right">Result</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Compile</td>
      <td><Markup Content="[green]✔[/]" /></td>
    </tr>
  </tbody>
</table>
```

---

### Figlet

Большой ASCII-арт текст с использованием FIGlet-шрифтов.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `Content` | `string` | `string.Empty` | Текст для рендеринга |
| `Justify` | `Justify` | `Center` | Выравнивание |
| `Color` | `Color` | `Color.Default` | Цвет глифов |

---

### BarChart

Горизонтальная барная диаграмма.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `BarChartItems` ⚠️ | `List<IBarChartItem>` | — | Данные (`Label`, `Value`, `Color`) |
| `Width` | `int?` | `null` | Ширина (по умолчанию — вся консоль) |
| `Label` | `string?` | `null` | Заголовок диаграммы |
| `MaxValue` | `double?` | `null` | Максимальное значение шкалы |
| `ShowValues` | `bool` | `false` | Показывать числа рядом с барами |
| `Culture` | `CultureInfo` | текущая | Культура для форматирования чисел |

---

### BreakdownChart

Диаграмма разбивки (pie-style).

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `BreakdownChartItems` ⚠️ | `List<IBreakdownChartItem>` | — | Данные (`Label`, `Value`, `Color`) |
| `Compact` | `bool` | `false` | Компактный режим |
| `Expand` | `bool` | `false` | Растянуть на всю ширину |
| `Width` | `int?` | `null` | Ширина |
| `ShowTags` | `bool` | `false` | Показывать легенду |
| `ShowTagValues` | `bool` | `false` | Показывать абсолютные значения |
| `ShowTagValuesPercentage` | `bool` | `false` | Показывать проценты |

---

### StepChart

Ступенчатая диаграмма с использованием Unicode box-drawing символов.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `Series` ⚠️ | `List<ChartSeries>` | — | Набор серий данных |
| `Width` | `int` | `60` | Ширина диаграммы |
| `Height` | `int` | `20` | Высота диаграммы |
| `ShowAxes` | `bool` | `true` | Показывать оси |
| `AxesColor` | `Color` | `Color.Grey` | Цвет осей |
| `LabelsColor` | `Color` | `Color.Grey` | Цвет подписей |
| `Title` | `string?` | `null` | Заголовок |
| `TitleColor` | `Color` | `Color.Grey` | Цвет заголовка |

**ChartSeries:**

| Член | Тип | Описание |
|---|---|---|
| `Color` | `Color` | Цвет линии |
| `Points` | `List<(double X, double Y)>` | Точки данных |

---

### SpectreCanvas

Рендеринг массива пикселей с разными цветами.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `Pixels` ⚠️ | `(int x, int y, Color color)[]` | — | Массив пикселей |
| `CanvasWidth` ⚠️ | `int` | — | Ширина холста |
| `CanvasHeight` ⚠️ | `int` | — | Высота холста |
| `MaxWidth` | `int?` | `null` | Максимальная ширина |
| `PixelWidth` | `int` | `2` | Ширина прямоугольника пикселя |
| `Scale` | `bool` | `false` | Масштабировать при рендеринге |

---

### SyntaxHighlighter

Подсветка синтаксиса кода с темами ColorCode.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `Code` | `string` | `string.Empty` | Исходный код |
| `Language` | `string?` | `null` | Язык: `"csharp"`, `"json"`, `"sql"` и др. |
| `Theme` | `string?` | `null` | Тема оформления |
| `ShowLineNumbers` | `bool` | `false` | Показывать номера строк |

**Встроенные языки:** `text/plaintext/plain`, `csharp/cs`, `razor`, `html`, `json`, `xml`, `sql`, `js/javascript`, `ts/typescript`, `css`, `powershell/ps`, `python`, `md/markdown`.

---

### ModalWindow

Модальное окно с автоматическим центрированием через z-index.

---

### ModalWindow

Модальное окно поверх текущего экрана с автоматическим центрированием.

> Визуализация построена на z-index, чтобы окно корректно перекрывало другие элементы.

---

## Утилиты

### Spinner

Анимированный индикатор прогресса.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `SpinnerType` | `Spinner` | `Spinner.Known.Dots` | Тип спиннера |
| `SpinnerName` | `string?` | `null` | Имя спиннера (переопределение) |
| `Message` | `string?` | `null` | Сопроводительный текст |
| `Style` | `string?` | `null` | Markup-стиль Spectre |
| `AutoDismiss` | `bool` | `false` | Скрыть по завершении |

---

### Newline

Вставляет один перенос строки. Параметров нет.