# Zenbu UI component contracts

Zenbu UI provides first-party component concepts and composition patterns.
Every component uses light DOM and keeps the corresponding native HTML control
visible.

## Inventory

| Component concept | Zenbu UI element |
| --- | --- |
| Accordion | `zen-accordion` |
| Alert | `zen-alert` |
| Alert Dialog | `zen-alert-dialog` |
| Aspect Ratio | `zen-aspect-ratio` |
| Attachment | `zen-attachment` |
| Avatar | `zen-avatar` |
| Badge | `zen-badge` |
| Breadcrumb | `zen-breadcrumb` |
| Bubble | `zen-bubble` |
| Box | `zen-box` |
| Button | `zen-button` |
| Button Group | `zen-button-group` |
| Calendar | `zen-calendar` |
| Card | `zen-card` |
| Carousel | `zen-carousel` |
| Chart | `zen-chart` |
| Checkbox | `zen-checkbox` |
| Collapsible | `zen-collapsible` |
| Combobox | `zen-combobox` |
| Command | `zen-command` |
| Context Menu | `zen-context-menu` |
| Data Table | `zen-data-table` |
| Date Picker | `zen-date-picker` |
| Dialog | `zen-dialog` |
| Direction | `zen-direction` |
| Drawer | `zen-drawer` |
| Dropdown Menu | `zen-dropdown-menu` |
| Empty | `zen-empty` |
| Field | `zen-field` |
| Form | `zen-form` |
| Hover Card | `zen-hover-card` |
| Heading | `zen-heading` |
| Input | `zen-input` |
| Input Group | `zen-input-group` |
| Input OTP | `zen-input-otp` |
| Item | `zen-item` |
| Kbd | `zen-kbd` |
| Label | `zen-label` |
| Link | `zen-link` |
| Marker | `zen-marker` |
| Menubar | `zen-menubar` |
| Message | `zen-message` |
| Message Scroller | `zen-message-scroller` |
| Native Select | `zen-native-select` |
| Navigation Menu | `zen-navigation-menu` |
| Pagination | `zen-pagination` |
| Popover | `zen-popover` |
| Progress | `zen-progress` |
| Radio Group | `zen-radio-group` |
| Resizable | `zen-resizable` |
| Scroll Area | `zen-scroll-area` |
| Select | `zen-select` |
| Separator | `zen-separator` |
| Sheet | `zen-sheet` |
| Sidebar | `zen-sidebar` |
| Skeleton | `zen-skeleton` |
| Slider | `zen-slider` |
| Notifications | `zen-notifications` |
| Spinner | `zen-spinner` |
| Switch | `zen-switch` |
| Table | `zen-table` |
| Tabs | `zen-tabs` |
| Textarea | `zen-textarea` |
| Text | `zen-text` |
| Toast (deprecated) | `zen-notifications` |
| Toggle | `zen-toggle` |
| Toggle Group | `zen-toggle-group` |
| Tooltip | `zen-tooltip` |
| Typography | `zen-typography` |

`zen-stack` remains a Zenbu-specific layout primitive in addition to this
catalog.

## Native HTML rules

- Dialog, alert dialog, sheet, and drawer contain a real `dialog`.
- Accordion and collapsible contain `details` and `summary`.
- Input, textarea, select, checkbox, radio, switch, and slider contain their
  corresponding native form controls.
- Calendar and date picker keep a native date value for form submission while
  rendering the first-party keyboard month grid. The browser date-picker chrome
  is not exposed.
- Table and data table contain a real `table`; pagination and breadcrumbs use
  native links in a `nav`.
- Button-like components contain native `button` or `a` elements.
- Components do not own application data, network requests, routing, or
  persistence.

## Interactive hooks

| Elements | Required light-DOM hooks | Emitted event |
| --- | --- | --- |
| `zen-dialog`, `zen-alert-dialog`, `zen-sheet`, `zen-drawer` | `zen-button > button[data-zen-trigger]`, `dialog`, optional `zen-button > button[data-zen-close]` | native `close` |
| `zen-popover`, `zen-tooltip` | `zen-button > button[data-zen-trigger]`, `[data-zen-content]` | native toggle/focus events |
| `zen-hover-card` | interactive `[data-zen-trigger]`, `[data-zen-content]` | native toggle/focus events |
| Menu elements | `[data-zen-trigger]`, `[role="menu"]`, `[role="menuitem"]` | native click |
| `zen-tabs` | `[role="tablist"]`, `[role="tab"]`, `[role="tabpanel"]` | `zen-change` with `{ value }` |
| `zen-toggle` | direct `button` | `zen-change` with `{ pressed }` |
| `zen-toggle-group` | direct buttons with `value` | `zen-change` with `{ values }` |
| `zen-link` | direct native anchor; optional `effect="paw"` | native link events |
| `zen-sidebar` | `[data-zen-sidebar-trigger]`, `[data-zen-sidebar-panel]` | `zen-change` with `{ open }` |
| `zen-combobox` | `input`, `[role="listbox"]`, `[role="option"]` | native `input`/`change` and `zen-change` |
| `zen-command` | `input`, `[role="menu"]`, `[role="menuitem"]` | `zen-command` with `{ value }` |
| `zen-input-otp` | one native input, optional `[data-zen-otp-slots]` | `zen-complete` with `{ value }` |
| `zen-calendar`, `zen-date-picker` | native date input plus generated month grid | native `input`/`change` and `zen-change` |
| `zen-carousel` | `[data-zen-viewport]`, `[data-zen-prev]`, `[data-zen-next]` | `zen-change` with `{ index }` |
| `zen-resizable` | two `[data-zen-panel]` elements and `[data-zen-handle]` | `zen-resize` with `{ percent }` |
| `zen-data-table` | `button[data-zen-sort]` and matching cell `data-key` values | `zen-sort` |

All custom events bubble but remain inside their current DOM tree unless a
component-specific document says otherwise. Application code should listen at
the nearest owning feature boundary.

## Catalog

Every inventory row has a route at `/components/<name>`, a rendered example,
and copyable HTML source in the Seobeo-backed catalog:

```bash
bazel run //design_system:dev
```