@cascivo/mcp 0.2.0 → 0.3.3

package/dist/context/item.md

@@ -0,0 +1,109 @@
+# Item
+
+**Category:** display  
+**Description:** Generic content row primitive with media, content, and action regions
+
+## When to use
+
+- Composing a single content row with leading media, a text block, and trailing actions
+- Building list, menu, or card rows from a consistent layout primitive
+- Slotting a row onto a real anchor or button via asChild for navigation or selection
+
+## When NOT to use
+
+- A full surface with elevation and padding regions — use Card
+- Key-value metadata pairs — use DataList
+
+## Anti-patterns
+
+### asChild merges row styling onto the real interactive element instead of nesting a non-semantic div
+
+**Bad:** `Wrapping an Item div in an anchor to make the whole row clickable`  
+**Good:** `Use Item asChild with the anchor as the single child so semantics and focus are native`  
+**Why:** asChild merges row styling onto the real interactive element instead of nesting a non-semantic div
+
+## Related components
+
+- **Card** (alternative): Card is a padded surface; Item is a lightweight horizontal row
+- **ContainedListItem** (alternative): ContainedListItem is bound to a contained list; Item is a free-standing row
+
+## Accessibility rationale
+
+Item is presentational by default; the slotted element determines the role and focus behaviour, so wrap it asChild around a button or link when the row is interactive
+
+## Props
+
+| Name      | Type                   | Required | Default | Description                                                                                       |
+| --------- | ---------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `asChild` | `boolean`              | No       | false   | When true, renders the child element as the root via Slot, merging props (polymorphic rendering). |
+| `variant` | `'default' \| 'muted'` | No       | default | Selects the visual style variant.                                                                 |
+| `size`    | `'sm' \| 'md'`         | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg').                                             |
+
+## Tokens
+
+- `--cascivo-color-text`
+- `--cascivo-color-text-subtle`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-radius-item`
+- `--cascivo-space-3`
+
+## Examples
+
+### Item with media, content, and actions
+
+```jsx
+<Item>
+  <ItemMedia>
+    <Avatar />
+  </ItemMedia>
+  <ItemContent>
+    <ItemTitle>Ada Lovelace</ItemTitle>
+    <ItemDescription>Mathematician</ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Button size="sm">Edit</Button>
+  </ItemActions>
+</Item>
+```
+
+### As a link via asChild
+
+```jsx
+<Item asChild>
+  <a href="/profile">
+    <ItemContent>
+      <ItemTitle>Profile</ItemTitle>
+    </ItemContent>
+  </a>
+</Item>
+```
+
+## Boundaries
+
+| Area             | Level    | Note                                                                        |
+| ---------------- | -------- | --------------------------------------------------------------------------- |
+| variant and size | flexible | Tune density and emphasis to match the surrounding list                     |
+| compound parts   | flexible | Media, content, title, description, and actions are optional and composable |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Item component (display). Generic content row primitive with media, content, and action regions
+
+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).
+
+Item is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-text, --cascivo-color-text-subtle, --cascivo-color-bg-subtle, --cascivo-radius-item, --cascivo-space-3
+
+Accessibility: role "none", WCAG 2.2-AA. Keep it AA.
+Flexible: variant and size, compound parts.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/join.md

@@ -0,0 +1,97 @@
+# Join
+
+**Category:** layout  
+**Description:** Groups adjacent children into a seamless joined element by removing interior borders and radii
+
+## When to use
+
+- Input + button search groups where the two controls should appear as one unit
+- Segmented button rows where buttons share borders
+
+## When NOT to use
+
+- Independent adjacent buttons that should remain visually separate
+- SegmentedControl — it has its own built-in grouping and selection semantics
+
+## Related components
+
+- **SegmentedControl** (alternative): SegmentedControl has built-in selection state; Join is purely a layout wrapper
+- **InputGroup** (alternative): InputGroup handles input + addon joining; Join is the general-purpose grouping primitive
+
+## Accessibility rationale
+
+Join is a layout-only container (role="none"). Accessibility semantics belong on the individual child controls — buttons carry their own role, inputs their labels.
+
+## Props
+
+| Name          | Type                         | Required | Default    | Description                                              |
+| ------------- | ---------------------------- | -------- | ---------- | -------------------------------------------------------- |
+| `children`    | `React.ReactNode`            | Yes      | —          | Content rendered inside the component.                   |
+| `orientation` | `'horizontal' \| 'vertical'` | No       | horizontal | Layout orientation of the component.                     |
+| `className`   | `string`                     | No       | —          | Additional CSS class names merged onto the root element. |
+
+## Examples
+
+### Search group
+
+Input and button joined into a single search control
+
+```jsx
+<Join>
+  <Input placeholder="Search…" />
+  <Button>Go</Button>
+</Join>
+```
+
+### Segmented buttons
+
+Segmented button row with no gaps between items
+
+```jsx
+<Join>
+  <Button variant="secondary">Day</Button>
+  <Button variant="secondary">Week</Button>
+  <Button variant="secondary">Month</Button>
+</Join>
+```
+
+### Vertical stack
+
+Vertically joined button group
+
+```jsx
+<Join orientation="vertical">
+  <Button>Top</Button>
+  <Button>Middle</Button>
+  <Button>Bottom</Button>
+</Join>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                         |
+| ----------- | -------- | ---------------------------------------------------------------------------- |
+| orientation | flexible | Horizontal and vertical grouping are both supported via the orientation prop |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Join component (layout). Groups adjacent children into a seamless joined element by removing interior borders and radii
+
+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).
+
+Join is strictly bound to these tokens — use only these, do not invent token names:
+  none declared
+
+Accessibility: role "none", WCAG 2.2-AA. Keep it AA.
+Flexible: orientation.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/kbd.md

@@ -0,0 +1,100 @@
+# Kbd
+
+**Category:** display  
+**Description:** Displays a keyboard key or shortcut
+
+## When to use
+
+- Showing a keyboard key or shortcut the user should press
+- Documenting hotkeys in menus, tooltips, or help text
+
+## When NOT to use
+
+- Inline code, commands, or identifiers — use Code
+- A short label that is not a key press — use Badge or Text
+
+## Anti-patterns
+
+### Kbd is for keys to press, not shell commands or code
+
+**Bad:** `<Kbd>npm install</Kbd>`  
+**Good:** `<Code>npm install</Code>`  
+**Why:** Kbd is for keys to press, not shell commands or code
+
+## Related components
+
+- **Code** (alternative): Code marks literal code; Kbd marks keys to press
+
+## Accessibility rationale
+
+Renders a native <kbd> element so assistive tech identifies the content as keyboard input; compose multiple <kbd> for a chord rather than encoding the combination in one string
+
+## Props
+
+| Name   | Type           | Required | Default | Description                                           |
+| ------ | -------------- | -------- | ------- | ----------------------------------------------------- |
+| `size` | `'sm' \| 'md'` | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
+
+## Tokens
+
+- `--cascivo-color-text-subtle`
+- `--cascivo-color-surface-raised`
+- `--cascivo-color-border`
+- `--cascivo-color-border-strong`
+- `--cascivo-radius-sm`
+
+## Examples
+
+### Single key
+
+```jsx
+<Kbd>⌘</Kbd>
+```
+
+### Shortcut
+
+Compose multiple keys to show a shortcut
+
+```jsx
+<span>
+  <Kbd>⌘</Kbd> + <Kbd>K</Kbd>
+</span>
+```
+
+### Small
+
+```jsx
+<Kbd size="sm">Esc</Kbd>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                   |
+| ----------- | -------- | ------------------------------------------------------ |
+| size        | flexible | sm fits inline help; md matches body text              |
+| token names | strict   | Surface and border 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 Kbd component (display). Displays a keyboard key or shortcut
+
+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).
+
+Kbd is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-text-subtle, --cascivo-color-surface-raised, --cascivo-color-border, --cascivo-color-border-strong, --cascivo-radius-sm
+
+Accessibility: role "kbd", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Surface and border must resolve to --cascivo-* tokens
+Flexible: size.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/label.md

@@ -0,0 +1,117 @@
+# Label
+
+**Category:** inputs  
+**Description:** Accessible caption for a form control
+
+## When to use
+
+- Naming a single form control (input, select, checkbox) so clicking the text focuses it
+- Marking a field as required with a visible and screen-reader-announced indicator
+
+## When NOT to use
+
+- Labeling a group of controls — use a <fieldset>/<legend> instead
+- Static body copy that is not associated with a control — use a plain text element
+
+## Anti-patterns
+
+### Without htmlFor the label is not programmatically associated, so click-to-focus and screen-reader naming break
+
+**Bad:** `<Label>Email</Label><input id="email" />`  
+**Good:** `<Label htmlFor="email">Email</Label><input id="email" />`  
+**Why:** Without htmlFor the label is not programmatically associated, so click-to-focus and screen-reader naming break
+
+### The required marker is rendered for you with an accessible text alternative; a hand-added asterisk is silent to screen readers
+
+**Bad:** `<Label required>Email <span>*</span></Label>`  
+**Good:** `<Label required>Email</Label>`  
+**Why:** The required marker is rendered for you with an accessible text alternative; a hand-added asterisk is silent to screen readers
+
+## Related components
+
+- **Field** (contained-by): Field composes Label with a control, description, and error and wires the ids automatically
+- **Input** (pairs-with): A label names the input it points at via htmlFor
+
+## Accessibility rationale
+
+Renders a native <label> so the platform handles click-to-focus and accessible naming; the required marker pairs an aria-hidden asterisk with visually-hidden localized text so the requirement is both seen and announced
+
+## Props
+
+| Name       | Type                    | Required | Default | Description                                                                                       |
+| ---------- | ----------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `htmlFor`  | `string`                | No       | —       | Id of the form control this label is associated with.                                             |
+| `asChild`  | `boolean`               | No       | false   | When true, renders the child element as the root via Slot, merging props (polymorphic rendering). |
+| `required` | `boolean`               | No       | false   | When true, marks the field as required.                                                           |
+| `disabled` | `boolean`               | No       | false   | When true, disables the control and removes it from the tab order.                                |
+| `children` | `ReactNode`             | Yes      | —       | Content rendered inside the component.                                                            |
+| `labels`   | `{ required?: string }` | No       | —       | Overrides for the component’s user-visible strings (i18n).                                        |
+
+## Tokens
+
+- `--cascivo-space-1`
+- `--cascivo-font-sans`
+- `--cascivo-text-sm`
+- `--cascivo-font-medium`
+- `--cascivo-leading-snug`
+- `--cascivo-leading-none`
+- `--cascivo-color-text`
+- `--cascivo-color-destructive`
+
+## Examples
+
+### Basic
+
+```jsx
+<Label htmlFor="email">Email</Label>
+```
+
+### Required
+
+```jsx
+<Label htmlFor="email" required>
+  Email
+</Label>
+```
+
+### asChild
+
+Render the label semantics onto a custom element via Slot.
+
+```jsx
+<Label asChild htmlFor="email">
+  <span>Email</span>
+</Label>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                         |
+| ----------- | -------- | ------------------------------------------------------------ |
+| token names | strict   | Colors and type must resolve to --cascivo-\* semantic tokens |
+| label copy  | flexible | Free, within tone guidance                                   |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Label component (inputs). Accessible caption for a form control
+
+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).
+
+Label is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-space-1, --cascivo-font-sans, --cascivo-text-sm, --cascivo-font-medium, --cascivo-leading-snug, --cascivo-leading-none, --cascivo-color-text, --cascivo-color-destructive
+
+Accessibility: role "label", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Colors and type must resolve to --cascivo-* semantic tokens
+Flexible: label copy.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/layout/app-shell.md

@@ -0,0 +1,85 @@
+# AppShell
+
+**Category:** layout  
+**Description:** Full-page application shell with persisted collapsible sidebar. Includes a signal-driven top progress bar with determinate progress, error state, and dismissible error strip.
+
+## When to use
+
+- A full-page application frame with header, collapsible sidebar, and content
+- You need a bare shell to compose your own navigation into
+
+## When NOT to use
+
+- You want opinionated, prewired sidebar navigation — use SidebarApp
+- A simple centered content page — use Section or Center
+- You just need a drop-in header + toggleable nav with no persistence — use the published `AppShell` from @cascivo/react (a `nav` prop, no copy-paste), not this richer copy-paste shell.
+
+## Related components
+
+- **AppShell (@cascivo/react)** (alternative): The published, self-contained AppShell: header + a single `nav` slot with an animated accessible drawer, no persistence/progress/aside. Same name, simpler prop surface (`nav` vs this shell’s `sideNav`/`aside`/`persistKey`/`state`). Use it for a quick drop-in; use this copy-paste shell when you need persisted collapse, a progress bar, or a right aside.
+- **SidebarApp** (alternative): Use the opinionated block when you want prewired sidebar nav
+- **DashboardLayout** (alternative): Use for a stats-strip dashboard page rather than a bare shell
+
+## Accessibility rationale
+
+Provides landmark structure with header and navigation regions for screen reader orientation.
+
+## Props
+
+| Name         | Type              | Required | Default | Description                                                                    |
+| ------------ | ----------------- | -------- | ------- | ------------------------------------------------------------------------------ |
+| `header`     | `ReactNode`       | Yes      | —       | Top header slot                                                                |
+| `sideNav`    | `ReactNode`       | No       | —       | Side navigation slot                                                           |
+| `aside`      | `ReactNode`       | No       | —       | Right aside slot                                                               |
+| `children`   | `ReactNode`       | Yes      | —       | Main content                                                                   |
+| `persistKey` | `string \| false` | No       | —       | localStorage key prefix. Pass false to disable persistence.                    |
+| `state`      | `ShellState`      | No       | —       | External shell state from createShellState(). Created internally when omitted. |
+
+## Tokens
+
+- `--cascivo-space-3`
+- `--cascivo-space-4`
+- `--cascivo-space-6`
+- `--cascivo-duration-200`
+- `--cascivo-ease-out`
+- `--cascivo-color-border`
+- `--cascivo-color-surface`
+- `--cascivo-font-size-xs`
+- `--cascivo-color-accent`
+- `--cascivo-color-destructive`
+- `--cascivo-color-destructive-subtle`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic
+
+App shell with collapsible nav
+
+```jsx
+<AppShell header={<Header />} sideNav={<Nav />}>
+  content
+</AppShell>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo AppShell component (layout). Full-page application shell with persisted collapsible sidebar. Includes a signal-driven top progress bar with determinate progress, error state, and dismissible error strip.
+
+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).
+
+AppShell is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-space-3, --cascivo-space-4, --cascivo-space-6, --cascivo-duration-200, --cascivo-ease-out, --cascivo-color-border, --cascivo-color-surface, --cascivo-font-size-xs, --cascivo-color-accent, --cascivo-color-destructive, --cascivo-color-destructive-subtle, --cascivo-focus-ring
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/layout/auth-layout.md

@@ -0,0 +1,74 @@
+# AuthLayout
+
+**Category:** layout  
+**Description:** Centered card layout for authentication pages (login, register, forgot password).
+
+## When to use
+
+- Centered card layout for authentication pages — login, register, reset
+- Focused single-task pages with an optional logo and minimal chrome
+
+## When NOT to use
+
+- General centered content — use Center
+- A full app frame after sign-in — use AppShell or SidebarApp
+
+## Related components
+
+- **LoginPage** (contains): The login page block renders inside this layout
+- **Center** (alternative): Use for plain centering without the auth card framing
+
+## Accessibility rationale
+
+Provides a main landmark wrapping the focused auth content.
+
+## Props
+
+| Name       | Type        | Required | Default | Description                            |
+| ---------- | ----------- | -------- | ------- | -------------------------------------- |
+| `children` | `ReactNode` | Yes      | —       | Auth form content                      |
+| `logo`     | `ReactNode` | No       | —       | Optional logo displayed above the form |
+
+## Tokens
+
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-radius-lg`
+- `--cascivo-space-4`
+- `--cascivo-space-6`
+- `--cascivo-space-8`
+
+## Examples
+
+### Login
+
+Centered auth card with logo
+
+```jsx
+<AuthLayout logo={<img src="/logo.svg" alt="Logo" />}>
+  <form>...</form>
+</AuthLayout>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo AuthLayout component (layout). Centered card layout for authentication pages (login, register, forgot password).
+
+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).
+
+AuthLayout is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-bg-subtle, --cascivo-color-surface, --cascivo-color-border, --cascivo-radius-lg, --cascivo-space-4, --cascivo-space-6, --cascivo-space-8
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/layout/auto-grid.md

@@ -0,0 +1,69 @@
+# AutoGrid
+
+**Category:** layout  
+**Description:** Media-query-free responsive grid — columns auto-fill based on available space.
+
+## When to use
+
+- Responsive card or tile grids that auto-fit columns to available width
+- Avoiding media queries — tracks wrap based on a minimum track width
+
+## When NOT to use
+
+- A fixed, known column count — use Grid
+- Single-direction stacking — use Stack
+
+## Related components
+
+- **Grid** (alternative): Use when an explicit column count is required
+
+## Accessibility rationale
+
+Pure layout primitive with no semantic role; does not affect the accessibility tree.
+
+## Props
+
+| Name  | Type                          | Required | Default | Description                                            |
+| ----- | ----------------------------- | -------- | ------- | ------------------------------------------------------ |
+| `min` | `string`                      | No       | "16rem" | Minimum track width before items wrap to fewer columns |
+| `gap` | `1\|2\|3\|4\|5\|6\|8\|10\|12` | No       | 4       | Spacing token step                                     |
+
+## Tokens
+
+- `--cascivo-space-*`
+
+## Examples
+
+### Auto-filling grid
+
+Items fill available space and wrap when narrower than 12rem
+
+```jsx
+<AutoGrid min="12rem" gap={4}>
+  <div>Card 1</div>
+  <div>Card 2</div>
+  <div>Card 3</div>
+</AutoGrid>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo AutoGrid component (layout). Media-query-free responsive grid — columns auto-fill based on available space.
+
+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).
+
+AutoGrid is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-space-*
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```