@chromvoid/uikit 0.1.0

package/specs/components/date-picker.md

@@ -0,0 +1,290 @@
+# cv-date-picker
+
+Date-time control with an editable combobox trigger and a popup calendar dialog.
+
+**Headless:** [`createDatePicker`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/date-picker.md)
+
+## Cross-Spec Consistency
+
+This document is the UIKit surface contract for `cv-date-picker`.
+
+- Headless `createDatePicker` is the source of truth for state, transitions, keyboard, and ARIA contracts.
+- UIKit reflects headless state into DOM attributes and spreads contract props.
+- UIKit adds only layout, styling, slots, and event adaptation.
+
+## Anatomy
+
+```
+<cv-date-picker> (host)
+└── <div part="base">
+    ├── <div part="input-wrap">
+    │   ├── <span part="prefix">
+    │   │   └── <slot name="prefix">
+    │   ├── <span part="label">
+    │   │   └── <input part="input">
+    │   ├── <span part="suffix">
+    │   │   └── <slot name="suffix">
+    │   └── <button part="clear-button">
+    └── <div part="dialog" hidden>
+        ├── <div part="calendar-shell">
+        │   ├── <button part="year-nav-button" data-dir="prev">
+        │   ├── <button part="month-nav-button" data-dir="prev">
+        │   ├── <span part="month-label">
+        │   ├── <button part="month-nav-button" data-dir="next">
+        │   └── <button part="year-nav-button" data-dir="next">
+        ├── <div part="calendar-grid">
+        │   └── <button part="calendar-day"> ...42 cells from contracts.getVisibleDays()...</button>
+        ├── <div part="time-row">
+        │   ├── <input part="hour-input" inputmode="numeric" maxlength="2">
+        │   ├── <span part="time-separator">:</span>
+        │   └── <input part="minute-input" inputmode="numeric" maxlength="2">
+        ├── <div part="actions">
+        │   ├── <button part="apply-button">
+        │   └── <button part="cancel-button">
+        └── <span part="dialog-caption">Apply/CANCEL + keyboard hints</span>
+```
+
+## Attributes
+
+| Attribute         | Type    | Default                  | Description                                                   |
+| ----------------- | ------- | ------------------------ | ------------------------------------------------------------- |
+| `value`           | String  | `""`                     | Current committed ISO value (`YYYY-MM-DDTHH:mm`) when present |
+| `open`            | Boolean | `false`                  | Popup dialog open state                                       |
+| `disabled`        | Boolean | `false`                  | Blocks all interaction                                        |
+| `readonly`        | Boolean | `false`                  | Input editing blocked; calendar/time actions blocked          |
+| `required`        | Boolean | `false`                  | Required marker for form/validation                           |
+| `placeholder`     | String  | `"Select date and time"` | Placeholder shown in the input                                |
+| `size`            | String  | `"medium"`               | Size: `small` \| `medium` \| `large`                          |
+| `locale`          | String  | `"en-US"`                | Locale for formatting/parsing hook context                    |
+| `time-zone`       | String  | `"local"`                | Time basis: `local` \| `utc`                                  |
+| `min`             | String  | `""`                     | Minimum accepted date-time (ISO)                              |
+| `max`             | String  | `""`                     | Maximum accepted date-time (ISO)                              |
+| `minute-step`     | Number  | `1`                      | Minute granularity for draft editing                          |
+| `hour-cycle`      | Number  | `24`                     | Time input style: `12` \| `24`                                |
+| `close-on-escape` | Boolean | `true`                   | Closes dialog on `Escape`                                     |
+| `aria-label`      | String  | `""`                     | Input and dialog accessible label                             |
+| `input-invalid`   | Boolean | `false`                  | Read-only derived state: input parse/validation failed        |
+| `has-value`       | Boolean | `false`                  | Read-only derived state: committed value present              |
+
+## Sizes
+
+| Size     | `--cv-date-picker-input-min-height` | `--cv-date-picker-input-padding-inline` | `--cv-date-picker-input-padding-block` |
+| -------- | ----------------------------------- | --------------------------------------- | -------------------------------------- |
+| `small`  | `30px`                              | `var(--cv-space-2, 8px)`                | `var(--cv-space-1, 4px)`               |
+| `medium` | `36px`                              | `var(--cv-space-3, 12px)`               | `var(--cv-space-2, 8px)`               |
+| `large`  | `42px`                              | `var(--cv-space-4, 16px)`               | `var(--cv-space-2, 8px)`               |
+
+## Slots
+
+| Slot     | Description                  |
+| -------- | ---------------------------- |
+| `prefix` | Icon or element before input |
+| `suffix` | Icon or element after input  |
+
+## CSS Parts
+
+| Part               | Element    | Description                              |
+| ------------------ | ---------- | ---------------------------------------- |
+| `base`             | `<div>`    | Root layout wrapper                      |
+| `input-wrap`       | `<div>`    | Input + optional action row container    |
+| `prefix`           | `<span>`   | Prefix icon/element wrapper              |
+| `label`            | `<span>`   | Main text wrapper around the input value |
+| `cv-input`         | `<input>`  | Editable combobox input                  |
+| `suffix`           | `<span>`   | Suffix icon/element wrapper              |
+| `clear-button`     | `<button>` | Clear committed value                    |
+| `dialog`           | `<div>`    | Popup shell for calendar/time panel      |
+| `calendar-shell`   | `<div>`    | Calendar header + grid wrapper           |
+| `month-label`      | `<span>`   | Visible month/year label                 |
+| `month-nav-button` | `<button>` | Previous/next month navigation button    |
+| `year-nav-button`  | `<button>` | Previous/next year navigation button     |
+| `calendar-grid`    | `<div>`    | Calendar grid surface                    |
+| `calendar-day`     | `<button>` | Day cell for each visible calendar day   |
+| `time-row`         | `<div>`    | Time editing row                         |
+| `hour-input`       | `<input>`  | Hour segment editor                      |
+| `minute-input`     | `<input>`  | Minute segment editor                    |
+| `time-separator`   | `<span>`   | Time separator between segments          |
+| `actions`          | `<div>`    | Footer actions area                      |
+| `apply-button`     | `<button>` | Commit draft selection                   |
+| `cancel-button`    | `<button>` | Discard draft selection                  |
+| `dialog-caption`   | `<span>`   | Optional helper text/status label        |
+
+## CSS Custom Properties
+
+| Property                                | Default                          | Description                      |
+| --------------------------------------- | -------------------------------- | -------------------------------- |
+| `--cv-date-picker-min-width`            | `260px`                          | Host minimum width               |
+| `--cv-date-picker-input-min-height`     | `36px`                           | Input control minimum block size |
+| `--cv-date-picker-input-padding-inline` | `var(--cv-space-3, 12px)`        | Horizontal input padding         |
+| `--cv-date-picker-input-padding-block`  | `var(--cv-space-2, 8px)`         | Vertical input padding           |
+| `--cv-date-picker-dialog-width`         | `min(560px, calc(100vw - 32px))` | Dialog inline size               |
+| `--cv-date-picker-calendar-size`        | `304px`                          | Calendar body block size         |
+| `--cv-date-picker-day-size`             | `34px`                           | Calendar cell size               |
+| `--cv-date-picker-day-gap`              | `var(--cv-space-1, 4px)`         | Calendar grid gap                |
+| `--cv-date-picker-font-size`            | `inherit`                        | Component font size              |
+| `--cv-date-picker-border-radius`        | `var(--cv-radius-md, 10px)`      | Dialog/calendar border radius    |
+| `--cv-date-picker-button-gap`           | `var(--cv-space-2, 8px)`         | Spacing between footer actions   |
+
+Additionally, styles may rely on theme tokens (no separate listing required here if already defined globally):
+`--cv-color-border`, `--cv-color-surface`, `--cv-color-text`, `--cv-color-text-muted`, `--cv-color-primary`, `--cv-color-danger`, `--cv-space-2`, `--cv-space-3`, `--cv-space-4`, `--cv-duration-fast`, `--cv-easing-standard`, `--cv-radius-sm`, `--cv-radius-md`.
+
+## Visual States
+
+| Host selector            | Description               |
+| ------------------------ | ------------------------- |
+| `:host([disabled])`      | Disabled, non-interactive |
+| `:host([readonly])`      | Read-only input mode      |
+| `:host([required])`      | Required marker active    |
+| `:host([open])`          | Popup dialog visible      |
+| `:host([size="small"])`  | Small size tokens used    |
+| `:host([size="large"])`  | Large size tokens used    |
+| `:host([input-invalid])` | Input value invalid state |
+| `:host([has-value])`     | Committed value present   |
+
+## ARIA Contract
+
+| Element          | Attribute               | Value                                              |
+| ---------------- | ----------------------- | -------------------------------------------------- |
+| Input            | `role`                  | `combobox`                                         |
+| Input            | `aria-haspopup`         | `dialog`                                           |
+| Input            | `aria-expanded`         | `true` / `false`                                   |
+| Input            | `aria-controls`         | Dialog id                                          |
+| Input            | `aria-activedescendant` | Focused day id when dialog is open                 |
+| Input            | `aria-invalid`          | `true` when input cannot be parsed or out of range |
+| Input            | `aria-required`         | `true` when `required`                             |
+| Input            | `aria-label`            | Provided `aria-label` string                       |
+| Dialog           | `role`                  | `dialog`                                           |
+| Dialog           | `aria-modal`            | `true`                                             |
+| Dialog           | `aria-label`            | Provided `aria-label` or default text              |
+| Calendar grid    | `role`                  | `grid`                                             |
+| Calendar day     | `role`                  | `gridcell`                                         |
+| Calendar day     | `tabindex`              | `0` / `-1`                                         |
+| Calendar day     | `aria-selected`         | `true` / `false`                                   |
+| Calendar day     | `aria-disabled`         | `true` when out of range / blocked                 |
+| Calendar day     | `aria-current`          | `date` when current day                            |
+| Month nav button | `role`                  | `button`                                           |
+| Year nav button  | `role`                  | `button`                                           |
+| Time inputs      | `type`                  | `text`                                             |
+| Time inputs      | `inputmode`             | `numeric`                                          |
+| Action buttons   | `role`                  | `button`                                           |
+
+## Events
+
+| Event       | Detail                                                                   | Description                                |
+| ----------- | ------------------------------------------------------------------------ | ------------------------------------------ |
+| `cv-input`  | `{ value: string, inputValue: string, open: boolean, invalid: boolean }` | Fires when the user changes the input text |
+| `cv-change` | `{ value: string, previousValue: string, source: "input" \| "dialog" }`  | Fires when committed value changes         |
+
+`cv-input` and `cv-change` are only emitted for user-modifiable state updates.
+
+## Reactive State Mapping
+
+`cv-date-picker` is a visual adapter over headless `createDatePicker`.
+
+### UIKit properties to headless actions/options
+
+| UIKit Property    | Direction          | Headless Binding                                               |
+| ----------------- | ------------------ | -------------------------------------------------------------- | --- | ------ |
+| `value`           | attr → action      | `actions.setInputValue(value)` then `actions.commitInput()`    |
+| `open`            | attr → action      | `actions.open()` / `actions.close()`                           |
+| `disabled`        | attr → action      | `actions.setDisabled(value)`                                   |
+| `readonly`        | attr → action      | `actions.setReadonly(value)`                                   |
+| `required`        | attr → action      | `actions.setRequired(value)`                                   |
+| `placeholder`     | attr → action      | `actions.setPlaceholder(value)`                                |
+| `locale`          | attr → action      | `actions.setLocale(value)`                                     |
+| `time-zone`       | attr → action      | `actions.setTimeZone(value)`                                   |
+| `min`             | attr → action      | `actions.setMin(value                                          |     | null)` |
+| `max`             | attr → action      | `actions.setMax(value                                          |     | null)` |
+| `minute-step`     | attr → action      | `actions.setMinuteStep(value)`                                 |
+| `hour-cycle`      | attr → action      | `actions.setHourCycle(value as 12 \/ 24)`                      |
+| `close-on-escape` | attr → option      | Passed as `closeOnEscape` during `createDatePicker(...)` setup |
+| `aria-label`      | attr → option      | Passed as `ariaLabel` during `createDatePicker(...)` setup     |
+| `size`            | attr → DOM/styling | Local styling tokens only                                      |
+
+### Headless state to DOM reflection
+
+| Headless State                                                                                                | Direction      | DOM Reflection                                              |
+| ------------------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------- |
+| `state.committedValue()`                                                                                      | state → attr   | `[value]` and input value text                              |
+| `state.isOpen()`                                                                                              | state → attr   | `[open]`                                                    |
+| `state.disabled()`                                                                                            | state → attr   | `[disabled]`                                                |
+| `state.readonly()`                                                                                            | state → attr   | `[readonly]`                                                |
+| `state.required()`                                                                                            | state → attr   | `[required]`                                                |
+| `state.hasCommittedSelection()`                                                                               | state → attr   | `[has-value]`                                               |
+| `state.inputInvalid()`                                                                                        | state → attr   | `[input-invalid]`                                           |
+| `state.min()`, `state.max()`, `state.locale()`, `state.timeZone()`, `state.hourCycle()`, `state.minuteStep()` | state → render | Applied to internal dialog/time controls and contract props |
+| `state.visibleDays()`                                                                                         | state → render | Drives `[part="calendar-day"]` list                         |
+| `state.focusedDate()`, `state.displayedMonth()`, `state.displayedYear()`                                      | state → render | Calendar focus/visible range rendering                      |
+
+### Contract props spreading
+
+- `contracts.getInputProps()` is spread onto `[part="input"]`.
+- `contracts.getDialogProps()` is spread onto `[part="dialog"]`.
+- `contracts.getCalendarGridProps()` is spread onto `[part="calendar-grid"]`.
+- `contracts.getMonthNavButtonProps()` and `contracts.getYearNavButtonProps()` are spread onto corresponding nav buttons.
+- `contracts.getCalendarDayProps(date)` is spread onto each `[part="calendar-day"]`.
+- `contracts.getHourInputProps()` / `contracts.getMinuteInputProps()` are spread onto `[part="hour-input"]` / `[part="minute-input"]`.
+- `contracts.getApplyButtonProps()` and `contracts.getCancelButtonProps()` are spread onto `[part="apply-button"]` / `[part="cancel-button"]`.
+- `contracts.getClearButtonProps()` is spread onto `[part="clear-button"]`.
+- `contracts.getVisibleDays()` provides the day matrix for rendering.
+
+### UIKit-only concerns
+
+UIKit owns rendering and animation only.
+
+- Layout and spacing between input, calendar, and footer.
+- Visual-only styling (`:host` states and CSS parts).
+- Optional `dialog-caption` content text.
+
+## Behavioral Contract
+
+### Combobox + Dialog pattern
+
+- Input opens/closes popup dialog with `ArrowDown`, `ArrowUp`, or `Space`.
+- Dialog remains a separate popup surface bound via `aria-controls` / `aria-expanded`.
+- Calendar selection updates draft state only while dialog is open.
+- `Apply` commits draft, `Cancel` restores committed state.
+
+### Dual Commit (editable input + calendar)
+
+- `commitInput()` and `commitDraft()` are the only ways to mutate committed value.
+- Typing and `Enter` in closed state only affects input text until input commit succeeds.
+- Calendar/time edits while open are isolated draft updates and are not committed until explicit `Apply`.
+- `clear-button` clears committed value and input text via headless `clear()` action.
+
+### Keyboard in open dialog
+
+- `Escape` closes dialog (respecting `close-on-escape`).
+- Calendar arrows/page keys use grid navigation as provided by headless contracts.
+- `Enter`/`Space` on calendar day selects draft day.
+- `Enter` in minute/hour inputs commits draft.
+
+### Disabled / read-only
+
+- `disabled` and `readonly` block all mutating actions and interactions.
+
+## Usage
+
+```html
+<cv-date-picker
+  aria-label="Flight date"
+  placeholder="Select departure date and time"
+  locale="en-US"
+  minute-step="15"
+  open
+>
+  <icon-calendar slot="prefix"></icon-calendar>
+  <icon-clock slot="suffix"></icon-clock>
+</cv-date-picker>
+
+<cv-date-picker
+  time-zone="utc"
+  hour-cycle="24"
+  min="2026-01-01T00:00"
+  max="2026-12-31T23:59"
+  disabled
+></cv-date-picker>
+
+<cv-date-picker locale="ru-RU" size="large">
+  <icon-schedule slot="suffix"></icon-schedule>
+</cv-date-picker>
+```

package/specs/components/dialog.md

@@ -0,0 +1,184 @@
+# cv-dialog
+
+Modal or non-modal dialog overlay for presenting focused content, confirmations, or alerts.
+
+**Headless:** [`createDialog`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/dialog.md)
+
+## Anatomy
+
+```
+<cv-dialog> (host)
+├── <button part="trigger">
+│   └── <slot name="trigger">
+└── <div part="overlay"> (hidden when closed)
+    └── <section part="content" role="dialog|alertdialog">
+        ├── <header part="header">
+        │   ├── <h2 part="title" id="...">
+        │   │   └── <slot name="title">
+        │   ├── <p part="description" id="...">
+        │   │   └── <slot name="description">
+        │   └── <button part="header-close" aria-label="Close">
+        │       └── <slot name="header-close">
+        ├── <div part="body">
+        │   └── <slot>
+        └── <footer part="footer">
+            └── <slot name="footer">
+```
+
+## Attributes
+
+| Attribute                  | Type    | Default    | Description                                                |
+| -------------------------- | ------- | ---------- | ---------------------------------------------------------- |
+| `open`                     | Boolean | `false`    | Whether the dialog is visible                              |
+| `modal`                    | Boolean | `true`     | Enables modal behavior (focus trap, scroll lock, backdrop) |
+| `type`                     | String  | `"dialog"` | ARIA role type: `dialog` \| `alertdialog`                  |
+| `close-on-escape`          | Boolean | `true`     | Whether Escape key closes the dialog                       |
+| `close-on-outside-pointer` | Boolean | `true`     | Whether clicking outside closes the dialog                 |
+| `close-on-outside-focus`   | Boolean | `true`     | Whether focusing outside closes the dialog                 |
+| `initial-focus-id`         | String  | —          | Id of element to focus when dialog opens                   |
+| `no-header`                | Boolean | `false`    | Hides the header (title, description, header close button) |
+
+## Slots
+
+| Slot           | Description                                              |
+| -------------- | -------------------------------------------------------- |
+| `(default)`    | Dialog body content                                      |
+| `trigger`      | Content for the trigger button                           |
+| `title`        | Dialog title text                                        |
+| `description`  | Description text below the title                         |
+| `header-close` | Icon content for the header close button (defaults to X) |
+| `footer`       | Footer content (action buttons, etc.)                    |
+
+## CSS Parts
+
+| Part           | Element     | Description                                                       |
+| -------------- | ----------- | ----------------------------------------------------------------- |
+| `trigger`      | `<button>`  | Trigger button that opens the dialog                              |
+| `overlay`      | `<div>`     | Backdrop/overlay container                                        |
+| `content`      | `<section>` | Dialog content panel with `role="dialog"` or `role="alertdialog"` |
+| `header`       | `<header>`  | Header area containing title, description, and close button       |
+| `title`        | `<h2>`      | Dialog title element                                              |
+| `description`  | `<p>`       | Dialog description element                                        |
+| `header-close` | `<button>`  | Header close icon button                                          |
+| `body`         | `<div>`     | Body content area                                                 |
+| `footer`       | `<footer>`  | Footer area for user-provided action buttons                      |
+
+## CSS Custom Properties
+
+| Property                     | Default                                       | Description                         |
+| ---------------------------- | --------------------------------------------- | ----------------------------------- |
+| `--cv-dialog-width`          | `min(560px, calc(100vw - 32px))`              | Preferred dialog inline size        |
+| `--cv-dialog-max-height`     | `calc(100dvh - 32px)`                         | Maximum block size before scrolling |
+| `--cv-dialog-header-spacing` | `var(--cv-space-4, 16px)`                     | Header padding                      |
+| `--cv-dialog-body-spacing`   | `var(--cv-space-4, 16px)`                     | Body padding                        |
+| `--cv-dialog-footer-spacing` | `var(--cv-space-4, 16px)`                     | Footer padding                      |
+| `--cv-dialog-overlay-color`  | `color-mix(in oklab, black 56%, transparent)` | Backdrop overlay color              |
+| `--cv-dialog-border-radius`  | `var(--cv-radius-lg, 14px)`                   | Panel border radius                 |
+
+## Visual States
+
+| Host selector                 | Description                                           |
+| ----------------------------- | ----------------------------------------------------- |
+| `:host([open])`               | Dialog visible, overlay shown                         |
+| `:host([modal])`              | Modal mode active (focus trap, scroll lock, backdrop) |
+| `:host([type="alertdialog"])` | Alert dialog mode with `role="alertdialog"`           |
+| `:host([no-header])`          | Header section hidden                                 |
+
+## Events
+
+| Event           | Detail            | Description                                        |
+| --------------- | ----------------- | -------------------------------------------------- |
+| `cv-input`      | `{open: boolean}` | Fires when open state changes via user interaction |
+| `cv-change`     | `{open: boolean}` | Fires when open state commits                      |
+| `cv-show`       | —                 | Fires when dialog begins to open                   |
+| `cv-after-show` | —                 | Fires after dialog open animation completes        |
+| `cv-hide`       | —                 | Fires when dialog begins to close                  |
+| `cv-after-hide` | —                 | Fires after dialog close animation completes       |
+
+`cv-input` and `cv-change` fire only for user-initiated state changes (trigger click, Escape, outside pointer, outside focus, header close). Programmatic `open` attribute changes do not emit these events.
+
+## Reactive State Mapping
+
+`cv-dialog` is a visual adapter over headless `createDialog`.
+
+| UIKit Property             | Direction     | Headless Binding                                             |
+| -------------------------- | ------------- | ------------------------------------------------------------ |
+| `open`                     | attr → action | `actions.open()` / `actions.close()`                         |
+| `modal`                    | attr → option | passed as `isModal` in `createDialog(options)`               |
+| `type`                     | attr → option | passed as `type` in `createDialog(options)`                  |
+| `close-on-escape`          | attr → option | passed as `closeOnEscape` in `createDialog(options)`         |
+| `close-on-outside-pointer` | attr → option | passed as `closeOnOutsidePointer` in `createDialog(options)` |
+| `close-on-outside-focus`   | attr → option | passed as `closeOnOutsideFocus` in `createDialog(options)`   |
+| `initial-focus-id`         | attr → option | passed as `initialFocusId` in `createDialog(options)`        |
+| `no-header`                | attr → DOM    | controls header visibility (UIKit-only, no headless binding) |
+
+| Headless State                 | Direction      | DOM Reflection                                |
+| ------------------------------ | -------------- | --------------------------------------------- |
+| `state.isOpen()`               | state → attr   | `[open]` host attribute                       |
+| `state.isModal()`              | state → attr   | `[modal]` host attribute                      |
+| `state.type()`                 | state → attr   | `[type]` host attribute                       |
+| `state.isFocusTrapped()`       | state → effect | activates focus trap within the dialog        |
+| `state.shouldLockScroll()`     | state → effect | applies `overflow: hidden` to `document.body` |
+| `state.restoreTargetId()`      | state → effect | focuses the trigger element on close          |
+| `state.initialFocusTargetId()` | state → effect | focuses the specified element on open         |
+
+- `contracts.getTriggerProps()` is spread onto `[part="trigger"]` to apply `role`, `aria-haspopup`, `aria-expanded`, `aria-controls`, `tabindex`, and click/keydown handlers.
+- `contracts.getOverlayProps()` is spread onto `[part="overlay"]` to apply `hidden`, `data-open`, and outside pointer/focus handlers.
+- `contracts.getContentProps()` is spread onto `[part="content"]` to apply `role` (`dialog` or `alertdialog`), `aria-modal`, `aria-labelledby`, `aria-describedby`, `tabindex`, and keydown handler.
+- `contracts.getTitleProps()` is spread onto `[part="title"]` to apply the `id` for `aria-labelledby`.
+- `contracts.getDescriptionProps()` is spread onto `[part="description"]` to apply the `id` for `aria-describedby`.
+- `contracts.getHeaderCloseButtonProps()` is spread onto `[part="header-close"]` to apply `role`, `tabindex`, `aria-label: 'Close'`, and click handler.
+- UIKit dispatches `cv-input` and `cv-change` events by observing `isOpen` changes triggered by user interaction (not by controlled `open` attribute changes).
+- UIKit dispatches `cv-show`/`cv-after-show`/`cv-hide`/`cv-after-hide` lifecycle events to bracket CSS transitions.
+- UIKit owns scroll lock implementation, focus trap implementation, focus restoration, backdrop rendering, and CSS transitions — headless provides signals, UIKit applies side effects.
+
+## Usage
+
+```html
+<!-- Basic dialog -->
+<cv-dialog>
+  <span slot="trigger">Open</span>
+  <span slot="title">Confirm action</span>
+  <span slot="description">Are you sure you want to proceed?</span>
+  <p>This action cannot be undone.</p>
+  <div slot="footer">
+    <cv-button variant="ghost">Cancel</cv-button>
+    <cv-button variant="primary">Confirm</cv-button>
+  </div>
+</cv-dialog>
+
+<!-- Alert dialog -->
+<cv-dialog type="alertdialog">
+  <span slot="trigger">Delete</span>
+  <span slot="title">Delete item?</span>
+  <span slot="description">This will permanently delete the item.</span>
+  <div slot="footer">
+    <cv-button variant="ghost">Cancel</cv-button>
+    <cv-button variant="danger">Delete</cv-button>
+  </div>
+</cv-dialog>
+
+<!-- Non-modal dialog -->
+<cv-dialog modal="false">
+  <span slot="trigger">Show info</span>
+  <span slot="title">Information</span>
+  <p>This dialog does not block the page.</p>
+</cv-dialog>
+
+<!-- Without header -->
+<cv-dialog no-header>
+  <span slot="trigger">Quick action</span>
+  <p>Minimal dialog with body content only.</p>
+  <div slot="footer">
+    <cv-button variant="primary">OK</cv-button>
+  </div>
+</cv-dialog>
+
+<!-- Custom header close icon -->
+<cv-dialog>
+  <span slot="trigger">Open</span>
+  <span slot="title">Settings</span>
+  <icon-close slot="header-close"></icon-close>
+  <p>Dialog content here.</p>
+</cv-dialog>
+```

package/specs/components/disclosure.md

@@ -0,0 +1,151 @@
+# cv-disclosure
+
+Expandable panel that controls the visibility of a content area, with support for exclusive accordion-like grouping via a shared name.
+
+**Headless:** [`createDisclosure`](https://github.com/chromvoid/headless-ui/blob/main/specs/components/disclosure.md)
+
+## Anatomy
+
+```
+<cv-disclosure> (host)
+└── <div part="base">
+    ├── <div part="trigger" role="button">
+    │   ├── <slot name="trigger">
+    │   └── <span part="trigger-icon" aria-hidden="true">
+    └── <div part="panel">
+        └── <slot>
+```
+
+## Attributes
+
+| Attribute  | Type    | Default | Description                                                                                                                   |
+| ---------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `open`     | Boolean | `false` | Whether the panel content is visible                                                                                          |
+| `disabled` | Boolean | `false` | Prevents user interaction with the trigger                                                                                    |
+| `name`     | String  | `""`    | Group name for exclusive accordion-like behavior; when set, opening this disclosure closes all others sharing the same `name` |
+
+## Slots
+
+| Slot        | Description                                         |
+| ----------- | --------------------------------------------------- |
+| `(default)` | Panel content displayed when the disclosure is open |
+| `trigger`   | Label content rendered inside the trigger           |
+
+## CSS Parts
+
+| Part           | Element  | Description                                      |
+| -------------- | -------- | ------------------------------------------------ |
+| `base`         | `<div>`  | Root layout wrapper                              |
+| `trigger`      | `<div>`  | Interactive trigger element with `role="button"` |
+| `trigger-icon` | `<span>` | Chevron/arrow indicator that rotates when open   |
+| `panel`        | `<div>`  | Collapsible content container                    |
+
+## CSS Custom Properties
+
+| Property                   | Default                           | Description                                     |
+| -------------------------- | --------------------------------- | ----------------------------------------------- |
+| `--cv-disclosure-duration` | `var(--cv-duration-fast, 120ms)`  | Duration of expand/collapse transitions         |
+| `--cv-disclosure-easing`   | `var(--cv-easing-standard, ease)` | Easing function for expand/collapse transitions |
+
+Additionally, component styles depend on theme tokens through fallback values:
+
+| Theme Property                | Default   | Description                                                    |
+| ----------------------------- | --------- | -------------------------------------------------------------- |
+| `--cv-color-border`           | `#2a3245` | Border color for trigger and panel                             |
+| `--cv-color-surface`          | `#141923` | Trigger background color                                       |
+| `--cv-color-surface-elevated` | `#1d2432` | Panel background color                                         |
+| `--cv-color-text`             | `#e8ecf6` | Default text color                                             |
+| `--cv-color-text-muted`       | `#9aa6bf` | Trigger icon color                                             |
+| `--cv-color-primary`          | `#65d7ff` | Focus outline color                                            |
+| `--cv-radius-sm`              | `6px`     | Border radius for trigger and panel                            |
+| `--cv-space-2`                | `8px`     | Gap between trigger and panel                                  |
+| `--cv-space-3`                | `12px`    | Inline padding for trigger; block and inline padding for panel |
+
+## Visual States
+
+| Host selector       | Description                                                             |
+| ------------------- | ----------------------------------------------------------------------- |
+| `:host([open])`     | Panel visible; trigger icon rotated 90deg                               |
+| `:host([disabled])` | Trigger has `opacity: 0.55`, `cursor: not-allowed`; interaction blocked |
+
+## Events
+
+| Event       | Detail            | Description                                                    |
+| ----------- | ----------------- | -------------------------------------------------------------- |
+| `cv-input`  | `{open: boolean}` | Fires immediately when user interaction changes the open state |
+| `cv-change` | `{open: boolean}` | Fires when the open state commits after user interaction       |
+
+Events fire only on user-initiated state changes (click, keyboard). Programmatic calls to `show()` / `hide()` or attribute changes do not fire events.
+
+## Imperative API
+
+| Method   | Return | Description                                               |
+| -------- | ------ | --------------------------------------------------------- |
+| `show()` | `void` | Opens the panel; delegates to headless `actions.open()`   |
+| `hide()` | `void` | Closes the panel; delegates to headless `actions.close()` |
+
+## Reactive State Mapping
+
+`cv-disclosure` is a visual adapter over headless `createDisclosure`.
+
+| UIKit Property | Direction      | Headless Binding                                        |
+| -------------- | -------------- | ------------------------------------------------------- |
+| `open`         | attr -> action | `actions.open()` / `actions.close()` depending on value |
+| `disabled`     | attr -> action | `actions.setDisabled(value)`                            |
+| `name`         | attr -> action | `actions.setName(value)`                                |
+
+| Headless State       | Direction     | DOM Reflection              |
+| -------------------- | ------------- | --------------------------- |
+| `state.isOpen()`     | state -> attr | `[open]` host attribute     |
+| `state.isDisabled()` | state -> attr | `[disabled]` host attribute |
+| `state.name()`       | state -> attr | `[name]` host attribute     |
+
+- `contracts.getTriggerProps()` is spread onto the inner `[part="trigger"]` element to apply `role`, `tabindex`, `aria-expanded`, `aria-controls`, `aria-disabled`, and keyboard/click handlers.
+- `contracts.getPanelProps()` is spread onto the inner `[part="panel"]` element to apply `id`, `aria-labelledby`, and `hidden`.
+- `show()` and `hide()` delegate directly to `actions.open()` and `actions.close()` without firing `cv-input`/`cv-change` events.
+- `actions.destroy()` must be called in `disconnectedCallback` to unregister from the name group registry.
+- UIKit does not own toggle, keyboard, or grouping logic; headless state is the source of truth.
+
+## Usage
+
+```html
+<!-- Basic disclosure -->
+<cv-disclosure>
+  <span slot="trigger">More details</span>
+  Hidden content revealed on expand.
+</cv-disclosure>
+
+<!-- Initially open -->
+<cv-disclosure open>
+  <span slot="trigger">Section</span>
+  This content is visible by default.
+</cv-disclosure>
+
+<!-- Disabled -->
+<cv-disclosure disabled>
+  <span slot="trigger">Locked section</span>
+  Cannot be toggled.
+</cv-disclosure>
+
+<!-- Accordion group (exclusive) -->
+<cv-disclosure name="faq">
+  <span slot="trigger">Question 1</span>
+  Answer 1.
+</cv-disclosure>
+
+<cv-disclosure name="faq">
+  <span slot="trigger">Question 2</span>
+  Answer 2.
+</cv-disclosure>
+
+<cv-disclosure name="faq">
+  <span slot="trigger">Question 3</span>
+  Answer 3.
+</cv-disclosure>
+
+<!-- Custom animation timing -->
+<cv-disclosure style="--cv-disclosure-duration: 300ms; --cv-disclosure-easing: cubic-bezier(0.4, 0, 0.2, 1);">
+  <span slot="trigger">Slow reveal</span>
+  Content with custom animation.
+</cv-disclosure>
+```