# Канонические компоненты

Машинный список находится в `registry/components.json`. Ниже зафиксирован смысл компонентов и границы их использования.

## GlassSurface

Базовая поверхность для карточки, панели и большого окна. Варианты меняют плотность материала, но не создают отдельный дизайн.

- `default` — обычная карточка/панель;
- `strong` — dropdown, modal и поверхность над сложным фоном;
- `soft` — вложенная или вторичная область.

Material rim допустим только как часть стекла. Жёсткая цветная рамка, случайный browser outline или debug border не являются rim.

## Button и IconButton

Button используется для всех текстовых действий. IconButton — для действия без текста.

- primary/accent — главное действие текущего контекста;
- secondary — обычное действие на glass surface;
- ghost — малозаметное действие без собственной подложки;
- danger — разрушительное действие, обычно в окне подтверждения.

Icon-only action по умолчанию круглый. Квадратная кнопка с маленьким радиусом допустима только как кнопка закрытия окна или плотный инструмент, где это зафиксировано контрактом.

## Field

FieldFrame объединяет label, control, hint и description. TextField/TextAreaField реализуют стандартные текстовые поля.

Приложение не должно вручную собирать label и input, если подходит Field. Ошибка и validation state будут расширением этого контракта, а не локальным классом приложения.

## Checker

Круглый бинарный контрол из нового Engine settings/agent inspector. Он использует checkbox semantics, но не копирует квадратный системный checkbox.

## RangeControl

Pill-range с заполнением акцентным цветом, встроенной подписью и значением. Домен определяет min/max/step и формат числа.

## ColorField

Связка круглого color picker и текстового значения. Валидация конкретного формата остаётся у формы приложения.

## Dropdown

Dropdown владеет floating-layer поведением:

- рендерится в `document.body`;
- позиционируется относительно viewport;
- переворачивается вверх при недостатке места;
- ограничивает размеры viewport;
- обновляется при resize и scroll;
- закрывается по outside pointer и Escape;
- закрывает другой открытый dropdown.

Содержимое меню передаётся приложением. Selection, action menu и filter menu используют один engine.

## Select

Select добавляет к Dropdown контролируемое значение, options и необязательный поиск. Native select не используется как видимый runtime UI, но может использоваться как fallback только в специально оговорённом legacy-контуре.

## Window

Window — единая механика открытия modal и правой panel:

- приложение контролирует `open`;
- библиотека управляет portal, focus entry/trap/restore, Escape, backdrop и scroll lock;
- `center` — modal;
- `end` — inspector/settings/detail panel.

Содержание, сохранение и запросы принадлежат приложению.

## ConfirmationModal

ConfirmationModal оборачивает Window и защищает async-confirm от повторного запуска. До завершения операции закрытие можно заблокировать.

## SegmentedControl

Pill navigation для верхней панели и компактного переключения режимов. Active segment использует активную поверхность темы; это не обязательно основной accent приложения.

## AppHeader

Трёхосевая верхняя панель:

- слева фиксированная область логотипа и optional context;
- по центру workspace/navigation;
- справа actions/profile.

Компонент фиксирует положение логотипа, высоту и выравнивание, но не знает маршруты конкретного приложения.

## StatusBadge

Статус использует semantic tone: neutral, success, warning, danger или accent. Бизнес-статус приложения маппится на tone в самом приложении.

## Inspector и ControlRow

Единая accordion-панель для settings и definition controls. Источник — только новый Environment Settings и NDC Agent Inspector.

Inspector владеет:

- заголовками разделов;
- открытием/закрытием секций;
- active state;
- вертикальным ритмом;
- раскладкой label/control.

Engine продолжает владеть определениями полей, типами нод и сохранением значений.