@cascivo/mcp 0.2.0 → 0.3.3

package/dist/context/block/empty-dashboard.md

@@ -0,0 +1,60 @@
+# EmptyDashboard
+
+**Category:** display  
+**Description:** Dashboard page showing an empty state with a call-to-action button.
+
+## When to use
+
+- A first-run or zero-data dashboard with an empty state and primary CTA
+- Guiding users to create their first item
+
+## When NOT to use
+
+- Data already exists — use DashboardCharts or DashboardLayout
+- A generic empty state inside a component — use an inline EmptyState
+
+## Related components
+
+- **DashboardCharts** (alternative): Use once the dashboard has data to display
+
+## Accessibility rationale
+
+Provides a main landmark with a clear heading and actionable CTA.
+
+## Props
+
+| Name           | Type         | Required | Default | Description                |
+| -------------- | ------------ | -------- | ------- | -------------------------- |
+| `onCreateItem` | `() => void` | No       | —       | Create item button handler |
+
+## Examples
+
+### Default
+
+Empty dashboard
+
+```jsx
+<EmptyDashboard />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo EmptyDashboard component (display). Dashboard page showing an empty state with a call-to-action button.
+
+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).
+
+EmptyDashboard is strictly bound to these tokens — use only these, do not invent token names:
+  none declared
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/block/login-page.md

@@ -0,0 +1,60 @@
+# LoginPage
+
+**Category:** display  
+**Description:** Authentication login page with email and password form.
+
+## When to use
+
+- A complete login page with email and password form
+- Standing up authentication quickly with validation built in
+
+## When NOT to use
+
+- You only need the centered auth frame — use AuthLayout
+- A multi-step signup or onboarding flow
+
+## Related components
+
+- **AuthLayout** (contained-by): Renders inside the centered auth layout
+
+## Accessibility rationale
+
+Form fields are labeled and validation messages are associated for screen readers.
+
+## Props
+
+| Name       | Type                            | Required | Default | Description                             |
+| ---------- | ------------------------------- | -------- | ------- | --------------------------------------- |
+| `onSubmit` | `(values: LoginValues) => void` | No       | —       | Called with valid form values on submit |
+
+## Examples
+
+### Default
+
+Login page
+
+```jsx
+<LoginPage />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo LoginPage component (display). Authentication login page with email and password form.
+
+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).
+
+LoginPage is strictly bound to these tokens — use only these, do not invent token names:
+  none declared
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/block/notification-center.md

@@ -0,0 +1,61 @@
+# NotificationCenter
+
+**Category:** display  
+**Description:** A list of notification alerts with a mark-all-read action.
+
+## When to use
+
+- A list of notification alerts with a mark-all-read action
+- An inbox or activity panel surfaced from a header bell
+
+## When NOT to use
+
+- Transient feedback after an action — use a Toast
+- A single inline status message — use an Alert
+
+## Related components
+
+- **Alert** (contains): Each notification is rendered as an alert item
+
+## Accessibility rationale
+
+Notification items use alert semantics so screen readers announce new entries.
+
+## Props
+
+| Name            | Type             | Required | Default | Description                   |
+| --------------- | ---------------- | -------- | ------- | ----------------------------- |
+| `notifications` | `Notification[]` | No       | —       | Notification items to display |
+| `onMarkAllRead` | `() => void`     | No       | —       | Mark all read button handler  |
+
+## Examples
+
+### Default
+
+Notification center
+
+```jsx
+<NotificationCenter />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo NotificationCenter component (display). A list of notification alerts with a mark-all-read action.
+
+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).
+
+NotificationCenter is strictly bound to these tokens — use only these, do not invent token names:
+  none declared
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/block/page-with-breadcrumb.md

@@ -0,0 +1,54 @@
+# PageWithBreadcrumb
+
+**Category:** display  
+**Description:** A centered content page with a breadcrumb navigation and page header.
+
+## When to use
+
+- A centered content page with breadcrumb navigation and a page header
+- Deep pages where users need hierarchical context
+
+## When NOT to use
+
+- Top-level pages with no hierarchy to express
+- You only need the header without breadcrumbs — use PageHeader
+
+## Related components
+
+- **PageHeader** (contains): Uses a page header with a breadcrumb slot
+
+## Accessibility rationale
+
+Breadcrumb renders as a labeled navigation region for screen reader orientation.
+
+## Examples
+
+### Default
+
+Page with breadcrumb
+
+```jsx
+<PageWithBreadcrumb />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo PageWithBreadcrumb component (display). A centered content page with a breadcrumb navigation and page header.
+
+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).
+
+PageWithBreadcrumb is strictly bound to these tokens — use only these, do not invent token names:
+  none declared
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/block/settings-form-page.md

@@ -0,0 +1,60 @@
+# SettingsFormPage
+
+**Category:** display  
+**Description:** Settings page with profile form inside a two-column settings layout.
+
+## When to use
+
+- A settings page with a profile form inside a two-column settings layout
+- Account or preferences pages with a save action
+
+## When NOT to use
+
+- You only need the layout frame — use SettingsLayout
+- A focused single-field edit — use an inline form
+
+## Related components
+
+- **SettingsLayout** (contained-by): Composes the two-column settings layout
+
+## Accessibility rationale
+
+Form fields are labeled and validation messages are associated for screen readers.
+
+## Props
+
+| Name     | Type                               | Required | Default | Description                             |
+| -------- | ---------------------------------- | -------- | ------- | --------------------------------------- |
+| `onSave` | `(values: SettingsValues) => void` | No       | —       | Called with valid form values on submit |
+
+## Examples
+
+### Default
+
+Settings form page
+
+```jsx
+<SettingsFormPage />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo SettingsFormPage component (display). Settings page with profile form inside a two-column settings layout.
+
+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).
+
+SettingsFormPage is strictly bound to these tokens — use only these, do not invent token names:
+  none declared
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/block/sidebar-app.md

@@ -0,0 +1,55 @@
+# SidebarApp
+
+**Category:** display  
+**Description:** Full app shell with collapsible side navigation and top header.
+
+## When to use
+
+- A ready-made app shell with opinionated collapsible sidebar and top header
+- Standing up an authenticated app frame quickly
+
+## When NOT to use
+
+- You want a bare shell to compose your own nav — use AppShell
+- A dashboard-specific layout — use DashboardLayout
+
+## Related components
+
+- **AppShell** (alternative): Use the bare layout primitive for custom navigation
+- **ConsoleApp** (alternative): Use the Carbon-parity console shell for icon-rail navigation
+
+## Accessibility rationale
+
+Provides header and navigation landmarks for screen reader orientation.
+
+## Examples
+
+### Default
+
+App with sidebar navigation
+
+```jsx
+<SidebarApp />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo SidebarApp component (display). Full app shell with collapsible side navigation and top header.
+
+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).
+
+SidebarApp is strictly bound to these tokens — use only these, do not invent token names:
+  none declared
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/block/stats-cards.md

@@ -0,0 +1,61 @@
+# StatsCards
+
+**Category:** display  
+**Description:** Grid of KPI stat cards with trend badges.
+
+## When to use
+
+- A grid of KPI stat cards with trend badges
+- Summarising headline metrics at the top of a dashboard
+
+## When NOT to use
+
+- A full charts dashboard — use DashboardCharts
+- A single metric — use a Kpi card
+
+## Related components
+
+- **Kpi** (contains): Each card displays a KPI metric with a delta
+- **DashboardLayout** (contained-by): Commonly fills the dashboard stats strip
+
+## Accessibility rationale
+
+Each stat card is a labeled figure for screen reader context.
+
+## Props
+
+| Name    | Type     | Required | Default | Description   |
+| ------- | -------- | -------- | ------- | ------------- |
+| `stats` | `Stat[]` | No       | —       | KPI stat data |
+
+## Examples
+
+### Default
+
+Demo KPI stats
+
+```jsx
+<StatsCards />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo StatsCards component (display). Grid of KPI stat cards with trend badges.
+
+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).
+
+StatsCards is strictly bound to these tokens — use only these, do not invent token names:
+  none declared
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/block/users-table-page.md

@@ -0,0 +1,61 @@
+# UsersTablePage
+
+**Category:** display  
+**Description:** Full users management page with table, search, and invite action.
+
+## When to use
+
+- A full user-management page with table, search, and invite action
+- Admin list views over a collection of records
+
+## When NOT to use
+
+- A read-only data display — use a plain Table
+- A dashboard overview — use DashboardCharts
+
+## Related components
+
+- **PageHeader** (contains): Uses a page header with title and invite action
+
+## Accessibility rationale
+
+Table uses proper row/column semantics and the search field is labeled.
+
+## Props
+
+| Name       | Type         | Required | Default | Description           |
+| ---------- | ------------ | -------- | ------- | --------------------- |
+| `users`    | `User[]`     | No       | —       | User data             |
+| `onInvite` | `() => void` | No       | —       | Invite button handler |
+
+## Examples
+
+### Default
+
+Demo users table
+
+```jsx
+<UsersTablePage />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo UsersTablePage component (display). Full users management page with table, search, and invite action.
+
+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).
+
+UsersTablePage is strictly bound to these tokens — use only these, do not invent token names:
+  none declared
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/blockquote.md

@@ -0,0 +1,95 @@
+# Blockquote
+
+**Category:** display  
+**Description:** Quoted passage with optional attribution footer
+
+## When to use
+
+- Setting off a quoted passage from another source with visual emphasis
+- Attributing a quote to a person or work via the cite footer
+
+## When NOT to use
+
+- Indenting or emphasizing your own non-quoted text — use Text styling
+- Inline quotations within a sentence — use a <q> element
+
+## Anti-patterns
+
+### blockquote semantics tell assistive tech the content is a quotation; misusing it misleads readers
+
+**Bad:** `Using <Blockquote> purely to indent a callout`  
+**Good:** `A Card or styled Text block for non-quote emphasis`  
+**Why:** blockquote semantics tell assistive tech the content is a quotation; misusing it misleads readers
+
+## Related components
+
+- **Prose** (pairs-with): Prose styles blockquotes among other long-form elements automatically
+
+## Accessibility rationale
+
+Renders a native <blockquote> with the attribution in <footer><cite>, so the quotation and its source are semantically distinct to assistive tech
+
+## Props
+
+| Name   | Type     | Required | Default   | Description                                               |
+| ------ | -------- | -------- | --------- | --------------------------------------------------------- |
+| `cite` | `string` | No       | undefined | URL of the quote’s source (sets the HTML cite attribute). |
+
+## Tokens
+
+- `--cascivo-color-border-strong`
+- `--cascivo-color-text`
+- `--cascivo-color-text-subtle`
+- `--cascivo-font-sans`
+- `--cascivo-font-medium`
+- `--cascivo-leading-relaxed`
+- `--cascivo-text-sm`
+- `--cascivo-text-base`
+
+## Examples
+
+### Default
+
+```jsx
+<Blockquote>Less, but better.</Blockquote>
+```
+
+### With attribution
+
+Attribution renders as <footer><cite>
+
+```jsx
+<Blockquote cite="Dieter Rams">Less, but better.</Blockquote>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                   |
+| ----------- | -------- | ---------------------------------------------------------------------- |
+| attribution | flexible | cite is optional; omit when the source is given in surrounding context |
+| token names | strict   | Border and text colors 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 Blockquote component (display). Quoted passage with optional attribution footer
+
+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).
+
+Blockquote is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-border-strong, --cascivo-color-text, --cascivo-color-text-subtle, --cascivo-font-sans, --cascivo-font-medium, --cascivo-leading-relaxed, --cascivo-text-sm, --cascivo-text-base
+
+Accessibility: role "blockquote", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Border and text colors must resolve to --cascivo-* tokens
+Flexible: attribution.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/bottom-sheet.md

@@ -0,0 +1,112 @@
+# BottomSheet
+
+**Category:** overlay  
+**Description:** Mobile bottom sheet with drag-to-resize detents, velocity-projected snapping, and drag-to-dismiss
+
+## When to use
+
+- A mobile surface that rises from the bottom and can be resized between detents by dragging
+- Showing secondary content, filters, or a form where the user can peek at half height then expand
+- A touch-first overlay that dismisses by flinging or dragging it down past the lowest detent
+
+## When NOT to use
+
+- A short yes/no confirmation — use AlertDialog
+- A non-resizable edge panel without gestures — use Drawer or Sheet
+- A desktop-first side panel for navigation — use Drawer
+
+## Anti-patterns
+
+### A resizable gesture surface is overkill for a focused yes/no decision
+
+**Bad:** `<BottomSheet title="Delete item?">Are you sure?</BottomSheet>`  
+**Good:** `<AlertDialog title="Delete item?" />`  
+**Why:** A resizable gesture surface is overkill for a focused yes/no decision
+
+## Related components
+
+- **Sheet** (alternative): Use Sheet for a fixed-height panel from any edge; BottomSheet adds resize detents
+- **Drawer** (alternative): Use Drawer for a plain edge dialog without resize detents
+
+## 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. The grab handle is a labelled separator and a Close button gives a non-gesture dismissal path so the sheet stays keyboard-operable.
+
+## 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.              |
+| `snapPoints`   | `number[]`                            | No       | [0.5, 0.92] | Detent heights as ascending fractions of the viewport (0–1)   |
+| `activeSnap`   | `number`                              | No       | —           | The controlled snap-point index.                              |
+| `defaultSnap`  | `number`                              | No       | 0           | The initial snap-point index when uncontrolled.               |
+| `onSnapChange` | `(index: number) => void`             | No       | —           | Called with the new snap-point index when it changes.         |
+| `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; handle?: string }` | 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-border`
+- `--cascivo-radius-overlay`
+- `--cascivo-shadow-overlay`
+- `--cascivo-motion-enter`
+- `--cascivo-motion-exit`
+- `--cascivo-target-min-coarse`
+- `--cascivo-z-overlay`
+
+## Examples
+
+### Basic
+
+```jsx
+<BottomSheet open={isOpen} onOpenChange={setIsOpen} title="Filters">
+  <FilterForm />
+</BottomSheet>
+```
+
+### Custom detents
+
+Snaps between three detents by dragging the handle; opens at half height.
+
+```jsx
+<BottomSheet defaultOpen snapPoints={[0.25, 0.5, 0.9]} defaultSnap={1} title="Nearby">
+  <PlacesList />
+</BottomSheet>
+```
+
+## Boundaries
+
+| Area          | Level    | Note                                                                   |
+| ------------- | -------- | ---------------------------------------------------------------------- |
+| snapPoints    | flexible | Any ascending list of viewport fractions; the sheet snaps between them |
+| open state    | flexible | Controlled (open/onOpenChange) or uncontrolled (defaultOpen)           |
+| active detent | flexible | Controlled (activeSnap/onSnapChange) or uncontrolled (defaultSnap)     |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo BottomSheet component (overlay). Mobile bottom sheet with drag-to-resize detents, velocity-projected snapping, and drag-to-dismiss
+
+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).
+
+BottomSheet 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, --cascivo-target-min-coarse, --cascivo-z-overlay
+
+Accessibility: role "dialog", WCAG 2.2-AA, keyboard: Escape/Tab/Shift+Tab. Keep it AA.
+Flexible: snapPoints, open state, active detent.
+
+Do not invent props, tokens, or global viewport media queries.
+```