NODEDC_DESIGN_GUIDELINE/docs/COMPONENTS.md

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

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