@cascivo/mcp 0.2.0 → 0.3.3

package/dist/context/data-table.md

@@ -0,0 +1,149 @@
+# DataTable
+
+**Category:** display  
+**Description:** Signal-driven data table with client/server sort, filter, pagination, multi-selection, expandable rows, and CSS content-visibility row containment for large datasets
+
+## When to use
+
+- Displaying tabular data with columns the user sorts, filters, or pages through
+- Selecting rows for batch actions across a dataset
+- Rendering large datasets that benefit from row containment and server-side sort/paging
+
+## When NOT to use
+
+- A simple static list of items — use List
+- Layout grids of cards or media — use a Card grid, not a data table
+
+## Anti-patterns
+
+### The full table machinery (sort, paging, selection) is overhead when there is no dataset to operate on
+
+**Bad:** `Using DataTable for two columns of label/value pairs`  
+**Good:** `A description list or a small Card with Stat/Text`  
+**Why:** The full table machinery (sort, paging, selection) is overhead when there is no dataset to operate on
+
+## Related components
+
+- **Pagination** (contains): DataTable embeds pagination controls for paged data
+- **EmptyState** (pairs-with): Render an EmptyState via the emptyState prop when there are no rows
+
+## Accessibility rationale
+
+Built on a native <table> with proper header semantics; sortable headers expose sort state, selection uses real checkboxes, and arrow-key navigation follows the grid pattern so keyboard users can traverse cells
+
+## Props
+
+| Name                | Type                                                                                     | Required | Default  | Description                                                                     |
+| ------------------- | ---------------------------------------------------------------------------------------- | -------- | -------- | ------------------------------------------------------------------------------- |
+| `columns`           | `Column<Row>[]`                                                                          | Yes      | —        | The column definitions describing each table column.                            |
+| `rows`              | `Row[]`                                                                                  | Yes      | —        | Number of visible text rows.                                                    |
+| `getRowId`          | `(row: Row) => string`                                                                   | No       | —        | Returns a stable unique id for a row.                                           |
+| `sort`              | `SortState`                                                                              | No       | —        | The controlled sort state.                                                      |
+| `defaultSort`       | `SortState`                                                                              | No       | —        | The initial sort state when uncontrolled.                                       |
+| `sortMode`          | `'client' \| 'server'`                                                                   | No       | 'client' | Whether sorting is handled client-side or by the server ('client' \| 'server'). |
+| `onSortChange`      | `(sort: SortState \| undefined) => void`                                                 | No       | —        | Called with the new sort state when it changes.                                 |
+| `searchable`        | `boolean`                                                                                | No       | false    | When true, shows a search/filter input.                                         |
+| `pagination`        | `{ pageSize: number; pageSizeOptions?: number[] }`                                       | No       | —        | Pagination configuration (page size and options).                               |
+| `selection`         | `{ mode: 'single' \| 'multi'; selected?: string[]; onChange?: (ids: string[]) => void }` | No       | —        | Row-selection configuration (mode and selected ids).                            |
+| `batchActions`      | `{ label: string; onClick: (selectedIds: string[]) => void }[]`                          | No       | —        | Actions applied to the currently selected rows.                                 |
+| `renderExpandedRow` | `(row: Row) => ReactNode`                                                                | No       | —        | Renders the expanded content for a row.                                         |
+| `density`           | `'compact' \| 'normal' \| 'relaxed'`                                                     | No       | 'normal' | Row density — 'compact', 'normal', or 'relaxed'.                                |
+| `zebra`             | `boolean`                                                                                | No       | false    | When true, applies alternating row striping.                                    |
+| `stickyHeader`      | `boolean`                                                                                | No       | false    | When true, the header stays fixed while the body scrolls.                       |
+| `loading`           | `boolean`                                                                                | No       | false    | When true, shows a loading state.                                               |
+| `emptyState`        | `ReactNode`                                                                              | No       | —        | Content shown when there are no rows.                                           |
+| `title`             | `string`                                                                                 | No       | —        | Title text for the component.                                                   |
+| `description`       | `string`                                                                                 | No       | —        | Supporting description text.                                                    |
+| `labels`            | `DataTableLabels`                                                                        | No       | —        | Overrides for the component’s user-visible strings (i18n).                      |
+| `className`         | `string`                                                                                 | No       | —        | Additional CSS class names merged onto the root element.                        |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-border`
+- `--cascivo-color-border-strong`
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-accent`
+- `--cascivo-font-sans`
+- `--cascivo-text-sm`
+- `--cascivo-text-xs`
+- `--cascivo-font-semibold`
+- `--cascivo-font-medium`
+- `--cascivo-radius-lg`
+- `--cascivo-radius-sm`
+- `--cascivo-space-2`
+- `--cascivo-space-3`
+- `--cascivo-space-4`
+- `--cascivo-data-table-max-height`
+- `--cascivo-duration-150`
+- `--cascivo-duration-500`
+- `--cascivo-ease-out`
+- `--cascivo-ease-in-out`
+
+## Examples
+
+### Basic table
+
+```jsx
+<DataTable
+  columns={[
+    { key: 'name', header: 'Name', sortable: true },
+    { key: 'role', header: 'Role' },
+  ]}
+  rows={[
+    { name: 'Alice', role: 'Engineer' },
+    { name: 'Bob', role: 'Designer' },
+  ]}
+  getRowId={(r) => r.name}
+/>
+```
+
+### Full-featured: selection, pagination, search
+
+```jsx
+<DataTable
+  columns={columns}
+  rows={rows}
+  getRowId={(r) => r.id}
+  searchable
+  pagination={{ pageSize: 10, pageSizeOptions: [10, 25, 50] }}
+  selection={{ mode: 'multi', onChange: setSelected }}
+  batchActions={[{ label: 'Delete', onClick: deleteRows }]}
+  stickyHeader
+  zebra
+/>
+```
+
+## Boundaries
+
+| Area                 | Level    | Note                                                                   |
+| -------------------- | -------- | ---------------------------------------------------------------------- |
+| sortMode and density | flexible | Choose client/server sort and density to fit data size and layout      |
+| token names          | strict   | All surfaces, borders, and spacing must resolve to --cascivo-\* tokens |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo DataTable component (display). Signal-driven data table with client/server sort, filter, pagination, multi-selection, expandable rows, and CSS content-visibility row containment for large datasets
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+DataTable is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-bg-subtle, --cascivo-color-border, --cascivo-color-border-strong, --cascivo-color-text, --cascivo-color-text-muted, --cascivo-color-accent, --cascivo-font-sans, --cascivo-text-sm, --cascivo-text-xs, --cascivo-font-semibold, --cascivo-font-medium, --cascivo-radius-lg, --cascivo-radius-sm, --cascivo-space-2, --cascivo-space-3, --cascivo-space-4, --cascivo-data-table-max-height, --cascivo-duration-150, --cascivo-duration-500, --cascivo-ease-out, --cascivo-ease-in-out
+
+Accessibility: role "table", WCAG 2.2-AA, keyboard: Tab/ArrowUp/ArrowDown/ArrowLeft/ArrowRight/Enter/Space. Keep it AA.
+
+Do not change (strict): token names — All surfaces, borders, and spacing must resolve to --cascivo-* tokens
+Flexible: sortMode and density.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/date-picker.md

@@ -0,0 +1,116 @@
+# DatePicker
+
+**Category:** inputs  
+**Description:** An accessible date-picker with a calendar popover.
+
+## When to use
+
+- Picking a single calendar date in a form where a visual month grid helps (due dates, bookings)
+- Date entry that benefits from min/max constraints and locale-aware formatting and week start
+
+## When NOT to use
+
+- Selecting a time of day — use TimePicker
+- Free-form or approximate dates where a plain Input is faster, or a date already known by typing
+
+## Anti-patterns
+
+### The component parses and compares ISO dates; non-ISO values break selection, constraints, and onChange
+
+**Bad:** `Passing a localized display string as value`  
+**Good:** `value/defaultValue/min/max are ISO YYYY-MM-DD; display formatting is handled internally`  
+**Why:** The component parses and compares ISO dates; non-ISO values break selection, constraints, and onChange
+
+## Related components
+
+- **TimePicker** (pairs-with): Combine when both a date and a time are needed
+- **Input** (alternative): Use a plain input when a calendar grid is unnecessary
+- **Form** (contained-by): Typically a field within a form with label/hint/error
+
+## Accessibility rationale
+
+The trigger is role="combobox" with aria-haspopup="dialog"/aria-expanded; the calendar is a role="dialog" containing a role="grid" with roving tabindex so arrow keys move a single focusable day, days expose aria-pressed for selection, aria-current="date" for today, and aria-disabled past min/max, and errors are wired via aria-invalid + aria-describedby with role="alert"
+
+## Props
+
+| Name           | Type                                   | Required | Default | Description                            |
+| -------------- | -------------------------------------- | -------- | ------- | -------------------------------------- |
+| `value`        | `string`                               | No       | —       | Controlled ISO date value (YYYY-MM-DD) |
+| `defaultValue` | `string`                               | No       | —       | Uncontrolled default value             |
+| `onChange`     | `(value: string \| undefined) => void` | No       | —       | Called on date selection or clear      |
+| `min`          | `string`                               | No       | —       | Minimum ISO date                       |
+| `max`          | `string`                               | No       | —       | Maximum ISO date                       |
+| `clearable`    | `boolean`                              | No       | —       | Shows a clear button                   |
+| `label`        | `string`                               | No       | —       | Field label                            |
+| `hint`         | `string`                               | No       | —       | Hint text                              |
+| `error`        | `string`                               | No       | —       | Error message                          |
+| `size`         | `'sm' \| 'md' \| 'lg'`                 | No       | —       | Field size                             |
+| `disabled`     | `boolean`                              | No       | —       | Disables the picker                    |
+| `labels`       | `DatePickerLabels`                     | No       | —       | i18n label overrides                   |
+
+## Tokens
+
+- `--cascivo-date-picker-bg`
+- `--cascivo-date-picker-border`
+- `--cascivo-date-picker-radius`
+- `--cascivo-date-picker-day-selected-bg`
+- `--cascivo-date-picker-day-today-color`
+
+## Examples
+
+### Basic
+
+Uncontrolled date picker
+
+```jsx
+<DatePicker label="Date" />
+```
+
+### Clearable
+
+With clear button
+
+```jsx
+<DatePicker label="Date" clearable />
+```
+
+### With constraints
+
+Date range constraint
+
+```jsx
+<DatePicker min="2024-01-01" max="2024-12-31" />
+```
+
+## Boundaries
+
+| Area              | Level    | Note                                                                                 |
+| ----------------- | -------- | ------------------------------------------------------------------------------------ |
+| value format      | strict   | All date props are ISO YYYY-MM-DD strings                                            |
+| locale formatting | flexible | Display, weekday labels, and week start derive from the current i18n locale via Intl |
+| token names       | strict   | Styling resolves to --cascivo-date-picker-\* component tokens                        |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo DatePicker component (inputs). An accessible date-picker with a calendar popover.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+DatePicker is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-date-picker-bg, --cascivo-date-picker-border, --cascivo-date-picker-radius, --cascivo-date-picker-day-selected-bg, --cascivo-date-picker-day-today-color
+
+Accessibility: role "combobox", WCAG 2.2-AA, keyboard: Enter/Space/Escape/ArrowUp/ArrowDown/ArrowLeft/ArrowRight. Keep it AA.
+
+Do not change (strict): value format — All date props are ISO YYYY-MM-DD strings; token names — Styling resolves to --cascivo-date-picker-* component tokens
+Flexible: locale formatting.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/date-range-picker.md

@@ -0,0 +1,113 @@
+# DateRangePicker
+
+**Category:** inputs  
+**Description:** A dual-calendar picker for selecting a contiguous date range.
+
+## When to use
+
+- Selecting a contiguous start–end date range (reporting windows, bookings, filters)
+- When two months visible at once and hover-preview of the in-between span aid selection
+
+## When NOT to use
+
+- Picking a single date — use DatePicker or Calendar
+- Selecting many non-contiguous dates — a range picker only models one continuous span
+
+## Anti-patterns
+
+### Consumers expect range.start <= range.end; an unsorted range breaks downstream comparisons and queries
+
+**Bad:** `Emitting the range in click order, so onValueChange can fire with end before start`  
+**Good:** `The two clicked dates are sorted before emitting, so start is always <= end`  
+**Why:** Consumers expect range.start <= range.end; an unsorted range breaks downstream comparisons and queries
+
+## Related components
+
+- **Calendar** (contains): Renders two Calendar instances side-by-side with synced navigation
+- **DatePicker** (alternative): Use the single-date picker when only one date is needed
+
+## Accessibility rationale
+
+The trigger is role="combobox" with aria-haspopup="dialog"/aria-expanded; the popover is a role="dialog" containing two Calendar grids, each an APG role="grid" with roving tabindex; selection is two clicks (first sets the pending start, second emits the sorted range; clicking the same day twice clears), and the hover/keyboard preview marks in-between cells with data-in-range; Escape and outside-click close the panel
+
+## Props
+
+| Name            | Type                                                     | Required | Default | Description                                        |
+| --------------- | -------------------------------------------------------- | -------- | ------- | -------------------------------------------------- |
+| `value`         | `{ start: Date; end: Date } \| null`                     | No       | —       | Controlled selected range                          |
+| `defaultValue`  | `{ start: Date; end: Date }`                             | No       | —       | Uncontrolled initial range                         |
+| `onValueChange` | `(range: { start: Date; end: Date }) => void`            | No       | —       | Called when a complete range is selected           |
+| `min`           | `Date`                                                   | No       | —       | Earliest selectable date                           |
+| `max`           | `Date`                                                   | No       | —       | Latest selectable date                             |
+| `disabled`      | `(date: Date) => boolean`                                | No       | —       | Predicate to disable individual days               |
+| `presets`       | `{ label: string; range: { start: Date; end: Date } }[]` | No       | —       | Quick-select preset ranges shown in a side column  |
+| `locale`        | `string`                                                 | No       | —       | BCP-47 locale; defaults to the current i18n locale |
+| `placeholder`   | `string`                                                 | No       | —       | Empty-state trigger text                           |
+| `size`          | `'sm' \| 'md' \| 'lg'`                                   | No       | —       | Field/grid size                                    |
+| `labels`        | `DateRangePickerLabels`                                  | No       | —       | i18n label overrides                               |
+
+## Tokens
+
+- `--cascivo-calendar-bg`
+- `--cascivo-calendar-day-selected-bg`
+- `--cascivo-calendar-day-selected-fg`
+- `--cascivo-calendar-range-bg`
+
+## Examples
+
+### Basic
+
+Uncontrolled dual-calendar range picker
+
+```jsx
+<DateRangePicker />
+```
+
+### With presets
+
+Quick-select common ranges
+
+```jsx
+<DateRangePicker presets={[{ label: 'Last 7 days', range: last7 }]} />
+```
+
+### Constrained
+
+Limits the selectable dates
+
+```jsx
+<DateRangePicker min={new Date(Date.UTC(2024, 0, 1))} max={new Date(Date.UTC(2024, 11, 31))} />
+```
+
+## Boundaries
+
+| Area       | Level    | Note                                                                                       |
+| ---------- | -------- | ------------------------------------------------------------------------------------------ |
+| range type | strict   | value/defaultValue are { start: Date; end: Date } with native Date objects compared in UTC |
+| presets    | flexible | Optional preset ranges render as quick-select buttons in a side column                     |
+| locale     | flexible | Display, weekday labels, and week start derive from the locale via Intl                    |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo DateRangePicker component (inputs). A dual-calendar picker for selecting a contiguous date range.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+DateRangePicker is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-calendar-bg, --cascivo-calendar-day-selected-bg, --cascivo-calendar-day-selected-fg, --cascivo-calendar-range-bg
+
+Accessibility: role "combobox", WCAG 2.2-AA, keyboard: Enter/Space/Escape/ArrowUp/ArrowDown/ArrowLeft/ArrowRight/Home/End/PageUp/PageDown. Keep it AA.
+
+Do not change (strict): range type — value/defaultValue are { start: Date; end: Date } with native Date objects compared in UTC
+Flexible: presets, locale.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/dock.md

@@ -0,0 +1,117 @@
+# Dock
+
+**Category:** navigation  
+**Description:** Fixed bottom navigation bar for mobile app shells with up to 5 items
+
+## When to use
+
+- Mobile app-shell navigation with 3–5 top-level destinations
+- When the primary navigation must be thumb-reachable on small screens
+
+## When NOT to use
+
+- Desktop navigation — the dock hides at the lg breakpoint (64rem)
+- More than 5 items — labels become unreadable and tap targets too small
+- Secondary or contextual navigation — use Tabs or SideNav instead
+
+## Anti-patterns
+
+### Tap targets become too small and labels collide on narrow screens
+
+**Bad:** `Putting more than 5 items in the Dock`  
+**Good:** `Use an overflow menu or drawer for additional destinations`  
+**Why:** Tap targets become too small and labels collide on narrow screens
+
+## Related components
+
+- **SideNav** (alternative): SideNav is the desktop equivalent for primary navigation
+- **Tabs** (alternative): Tabs are for in-page section switching, not app-level navigation
+
+## Accessibility rationale
+
+Wrapped in <nav> with aria-label; active item carries aria-current="page"; renders as <a> for href items and <button> for onClick items to preserve native semantics
+
+## Props
+
+| Name          | Type         | Required | Default | Description                                                             |
+| ------------- | ------------ | -------- | ------- | ----------------------------------------------------------------------- |
+| `items`       | `DockItem[]` | Yes      | —       | Navigation items, each with a label, icon, and optional href or onClick |
+| `activeIndex` | `number`     | No       | —       | Index of the currently active item (0-based)                            |
+| `className`   | `string`     | No       | —       | Additional CSS class names merged onto the root element.                |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-accent`
+- `--cascivo-color-text-muted`
+- `--cascivo-border-subtle`
+- `--cascivo-ring-width`
+- `--cascivo-ring-color`
+- `--cascivo-ease-out`
+- `--cascivo-target-min-coarse`
+- `--cascivo-z-dock`
+
+## Examples
+
+### Basic mobile dock
+
+Fixed bottom navigation for a mobile app shell
+
+```jsx
+<Dock
+  activeIndex={0}
+  items={[
+    { label: 'Home', icon: '🏠', onClick: () => navigate('/') },
+    { label: 'Search', icon: '🔍', onClick: () => navigate('/search') },
+    { label: 'Profile', icon: '👤', onClick: () => navigate('/profile') },
+  ]}
+/>
+```
+
+### With hrefs
+
+Link-based dock items for standard navigation
+
+```jsx
+<Dock
+  activeIndex={1}
+  items={[
+    { label: 'Feed', icon: '📰', href: '/feed' },
+    { label: 'Explore', icon: '🌐', href: '/explore' },
+    { label: 'Notifications', icon: '🔔', href: '/notifications' },
+    { label: 'Profile', icon: '👤', href: '/profile' },
+  ]}
+/>
+```
+
+## Boundaries
+
+| Area         | Level    | Note                                                                                    |
+| ------------ | -------- | --------------------------------------------------------------------------------------- |
+| item element | flexible | Renders <a> when href is provided, <button> otherwise — no wrapper needed               |
+| visibility   | strict   | Hidden at 64rem (lg) via display:none — not configurable to preserve mobile-only intent |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Dock component (navigation). Fixed bottom navigation bar for mobile app shells with up to 5 items
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Dock is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-accent, --cascivo-color-text-muted, --cascivo-border-subtle, --cascivo-ring-width, --cascivo-ring-color, --cascivo-ease-out, --cascivo-target-min-coarse, --cascivo-z-dock
+
+Accessibility: role "navigation", WCAG 2.2-AA, keyboard: Tab/Enter. Keep it AA.
+
+Do not change (strict): visibility — Hidden at 64rem (lg) via display:none — not configurable to preserve mobile-only intent
+Flexible: item element.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/drawer.md

@@ -0,0 +1,111 @@
+# Drawer
+
+**Category:** overlay  
+**Description:** Edge-anchored dialog panel that slides in from a screen edge with CSS-only enter/exit motion
+
+## When to use
+
+- A side or edge panel for navigation, filters, or detail views that needs full-height space
+- A modal surface that slides in and locks the page behind it while open
+- A controllable open/close panel where the parent owns the state via open/onOpenChange
+
+## When NOT to use
+
+- A short yes/no confirmation — use AlertDialog
+- Small content anchored to a trigger element — use Popover
+- A gesture-driven, swipe-to-dismiss sheet — use Sheet
+
+## Anti-patterns
+
+### A full edge panel with focus trap and scroll lock is overkill for a yes/no decision
+
+**Bad:** `<Drawer title="Delete item?">Are you sure?</Drawer>`  
+**Good:** `<AlertDialog title="Delete item?" />`  
+**Why:** A full edge panel with focus trap and scroll lock is overkill for a yes/no decision
+
+## Related components
+
+- **Sheet** (alternative): Use Sheet when swipe/gesture dismissal is wanted; Drawer is a plain dialog panel
+- **Modal** (alternative): Use a centered modal rather than an edge panel for focused decisions
+
+## Accessibility rationale
+
+Renders role="dialog" with aria-modal; the title labels it via aria-labelledby and the description via aria-describedby. FocusScope traps Tab focus and restores it on close; DismissableLayer handles Escape and outside-pointer dismissal.
+
+## Props
+
+| Name             | Type                                    | Required | Default | Description                                                                   |
+| ---------------- | --------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------- |
+| `open`           | `boolean`                               | No       | —       | Whether the component is open (controlled).                                   |
+| `defaultOpen`    | `boolean`                               | No       | —       | Whether the component is open on first render (uncontrolled).                 |
+| `onOpenChange`   | `(open: boolean) => void`               | No       | —       | Called with the next open state when it changes.                              |
+| `side`           | `'start' \| 'end' \| 'top' \| 'bottom'` | No       | end     | Edge the panel is anchored to. Drives the slide direction.                    |
+| `size`           | `string`                                | No       | —       | Panel size along its cross axis (width for start/end, height for top/bottom). |
+| `title`          | `React.ReactNode`                       | No       | —       | Title text for the component.                                                 |
+| `description`    | `React.ReactNode`                       | No       | —       | Supporting description text.                                                  |
+| `children`       | `React.ReactNode`                       | No       | —       | Content rendered inside the component.                                        |
+| `labels`         | `{ close?: string }`                    | No       | —       | Overrides for the component’s user-visible strings (i18n).                    |
+| `className`      | `string`                                | No       | —       | Additional CSS class names merged onto the root element.                      |
+| `swipeToDismiss` | `boolean`                               | No       | false   | Allow dragging the header toward its edge to dismiss (opt-in).                |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-radius-overlay`
+- `--cascivo-shadow-overlay`
+- `--cascivo-motion-enter`
+- `--cascivo-motion-exit`
+
+## Examples
+
+### Basic
+
+```jsx
+<Drawer open={isOpen} onOpenChange={setIsOpen} title="Settings">
+  <SettingsForm />
+</Drawer>
+```
+
+### Bottom drawer with swipe-to-dismiss
+
+Dragging the header past a threshold toward the edge dismisses the panel.
+
+```jsx
+<Drawer defaultOpen side="bottom" size="20rem" swipeToDismiss title="Details">
+  <OrderDetails />
+</Drawer>
+```
+
+## Boundaries
+
+| Area         | Level    | Note                                                                                |
+| ------------ | -------- | ----------------------------------------------------------------------------------- |
+| side         | strict   | Limited to start \| end \| top \| bottom — drives the slide direction and animation |
+| open state   | flexible | Controlled (open/onOpenChange) or uncontrolled (defaultOpen)                        |
+| body content | flexible | Any children; the consumer owns the panel contents                                  |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Drawer component (overlay). Edge-anchored dialog panel that slides in from a screen edge with CSS-only enter/exit motion
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Drawer is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border, --cascivo-radius-overlay, --cascivo-shadow-overlay, --cascivo-motion-enter, --cascivo-motion-exit
+
+Accessibility: role "dialog", WCAG 2.2-AA, keyboard: Escape/Tab/Shift+Tab. Keep it AA.
+
+Do not change (strict): side — Limited to start | end | top | bottom — drives the slide direction and animation
+Flexible: open state, body content.
+
+Do not invent props, tokens, or global viewport media queries.
+```