109 lines
6.0 KiB
Markdown
109 lines
6.0 KiB
Markdown
# Канонические компоненты
|
||
|
||
Машинный список находится в `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 продолжает владеть определениями полей, типами нод и сохранением значений.
|
||
|