@cascivo/mcp 0.2.0 → 0.3.4

package/dist/context/relative-time.md

@@ -0,0 +1,90 @@
+# RelativeTime
+
+**Category:** display  
+**Description:** Displays a date as a localized phrase relative to now, auto-updating
+
+## When to use
+
+- Showing how long ago something happened in human terms ("3 minutes ago")
+- Timestamps in feeds, comments, and activity logs where recency matters more than precision
+- Anywhere a self-updating relative time is friendlier than an absolute date
+
+## When NOT to use
+
+- Precise timestamps in tables or audit logs — use formatDate for an exact, sortable value
+- Dates far in the past/future where "2 years ago" is less useful than the actual date
+
+## Anti-patterns
+
+### Relative phrases lose precision; the exact date belongs in records (RelativeTime still exposes it via title/datetime)
+
+**Bad:** `<RelativeTime date={date} /> as the only representation of a legal/audit timestamp`  
+**Good:** `<time>{formatDate(date)}</time> for exact records; RelativeTime for casual recency`  
+**Why:** Relative phrases lose precision; the exact date belongs in records (RelativeTime still exposes it via title/datetime)
+
+## Related components
+
+- **Stat** (pairs-with): Use alongside Stat to timestamp a metric’s last update
+
+## Accessibility rationale
+
+Renders a native <time> element with a machine-readable datetime and the absolute date in the title, so the precise instant is available even though the visible text is relative
+
+## Props
+
+| Name     | Type                             | Required | Default | Description                                             |
+| -------- | -------------------------------- | -------- | ------- | ------------------------------------------------------- |
+| `date`   | `Date \| number \| string`       | Yes      | —       | The date to render relative to now.                     |
+| `sync`   | `boolean`                        | No       | true    | When true, updates the relative time as it elapses.     |
+| `now`    | `number`                         | No       | —       | Override "now" (ms); disables the interval              |
+| `format` | `Intl.RelativeTimeFormatOptions` | No       | —       | Intl.RelativeTimeFormat options controlling the output. |
+
+## Examples
+
+### Basic
+
+```jsx
+<RelativeTime date={post.createdAt} />
+```
+
+### Natural language
+
+```jsx
+<RelativeTime date={date} format={{ numeric: 'auto' }} />
+```
+
+### Static (no ticking)
+
+```jsx
+<RelativeTime date={date} sync={false} />
+```
+
+## Boundaries
+
+| Area   | Level    | Note                                                                            |
+| ------ | -------- | ------------------------------------------------------------------------------- |
+| format | flexible | Pass Intl.RelativeTimeFormat options (e.g. numeric: "auto") to tune the wording |
+| sync   | flexible | Disable ticking for static contexts or long-past dates                          |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo RelativeTime component (display). Displays a date as a localized phrase relative to now, auto-updating
+
+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).
+
+RelativeTime is strictly bound to these tokens — use only these, do not invent token names:
+  none declared
+
+Accessibility: role "time", WCAG 2.2-AA. Keep it AA.
+Flexible: format, sync.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/resizable.md

@@ -0,0 +1,102 @@
+# Resizable
+
+**Category:** layout  
+**Description:** Two-pane splitter whose divider can be dragged or keyboard-nudged to reallocate space
+
+## When to use
+
+- Letting users reallocate space between two adjacent regions, e.g. an editor and a preview
+- Side panels or inspectors whose width the user should control
+- Master/detail layouts where one pane may need more room than the default
+
+## When NOT to use
+
+- Fixed layouts where the split should never change — use plain flex/grid
+- More than two siblings need independent resizing — compose nested splitters instead
+
+## Anti-patterns
+
+### A single separator can only mediate one boundary between two panes
+
+**Bad:** `<Resizable> wrapping three panes`  
+**Good:** `Nest two Resizable splitters so each divider controls exactly one boundary`  
+**Why:** A single separator can only mediate one boundary between two panes
+
+## Related components
+
+- **Slider** (alternative): Use a slider when picking a value, not when allocating layout space
+
+## Accessibility rationale
+
+The divider is a focusable role="separator" with aria-orientation and aria-valuenow/min/max reflecting the percentage split; arrow keys nudge the ratio and Home/End snap to the configured bounds, matching the APG window-splitter pattern.
+
+## Props
+
+| Name            | Type                         | Required | Default    | Description                                      |
+| --------------- | ---------------------------- | -------- | ---------- | ------------------------------------------------ |
+| `children`      | `ReactNode`                  | Yes      | —          | Exactly two panes                                |
+| `orientation`   | `'horizontal' \| 'vertical'` | No       | horizontal | Layout orientation of the component.             |
+| `defaultRatio`  | `number`                     | No       | 0.5        | The initial split ratio when uncontrolled.       |
+| `ratio`         | `number`                     | No       | —          | Controlled ratio (0–1)                           |
+| `minRatio`      | `number`                     | No       | 0.1        | Minimum allowed split ratio.                     |
+| `maxRatio`      | `number`                     | No       | 0.9        | Maximum allowed split ratio.                     |
+| `onRatioChange` | `(ratio: number) => void`    | No       | —          | Called with the new split ratio when it changes. |
+
+## Tokens
+
+- `--cascivo-color-border`
+- `--cascivo-color-border-strong`
+- `--cascivo-radius-full`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Horizontal split
+
+```jsx
+<Resizable>
+  <Editor />
+  <Preview />
+</Resizable>
+```
+
+### Vertical with bounds
+
+```jsx
+<Resizable orientation="vertical" defaultRatio={0.3} minRatio={0.2} maxRatio={0.8}>
+  <Toolbar />
+  <Canvas />
+</Resizable>
+```
+
+## Boundaries
+
+| Area          | Level    | Note                                                                               |
+| ------------- | -------- | ---------------------------------------------------------------------------------- |
+| sizing        | strict   | Pane sizes derive from a single --cascivo-resizable-ratio custom property via flex |
+| min/max ratio | flexible | Consumer-defined clamp range                                                       |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Resizable component (layout). Two-pane splitter whose divider can be dragged or keyboard-nudged to reallocate 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).
+
+Resizable is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-border, --cascivo-color-border-strong, --cascivo-radius-full, --cascivo-focus-ring
+
+Accessibility: role "separator", WCAG 2.2-AA, keyboard: ArrowLeft/ArrowRight/ArrowUp/ArrowDown/Home/End. Keep it AA.
+
+Do not change (strict): sizing — Pane sizes derive from a single --cascivo-resizable-ratio custom property via flex
+Flexible: min/max ratio.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/scroll-area.md

@@ -0,0 +1,101 @@
+# ScrollArea
+
+**Category:** layout  
+**Description:** A scroll container with styled, slim scrollbars and overflow shadows
+
+## When to use
+
+- Constraining a region to a fixed height/width with overflow scrolling
+- Giving long lists, tables, or code blocks consistent slim scrollbars across browsers
+- Signalling more content with subtle top/bottom scroll shadows
+
+## When NOT to use
+
+- Whole-page scrolling — let the document scroll naturally
+- Content that should determine its own height — do not cap it
+
+## Anti-patterns
+
+### Nested scroll regions trap focus and confuse pointer and keyboard scrolling
+
+**Bad:** `Nesting many ScrollAreas so the user faces competing scrollbars`  
+**Good:** `Scroll one region; let the rest size to content`  
+**Why:** Nested scroll regions trap focus and confuse pointer and keyboard scrolling
+
+## Related components
+
+- **Separator** (pairs-with): Often divides items inside a scrolled list
+
+## Accessibility rationale
+
+Native overflow keeps the container keyboard-scrollable and focusable per browser defaults; styling never removes the scroll affordance, only restyles it
+
+## Props
+
+| Name          | Type                                   | Required | Default  | Description                                             |
+| ------------- | -------------------------------------- | -------- | -------- | ------------------------------------------------------- |
+| `height`      | `string`                               | No       | —        | Max block size of the container (any CSS length)        |
+| `width`       | `string`                               | No       | —        | Max inline size of the container (any CSS length)       |
+| `orientation` | `'vertical' \| 'horizontal' \| 'both'` | No       | vertical | Which axes may scroll                                   |
+| `edges`       | `'shadow' \| 'mask' \| 'none'`         | No       | shadow   | Edge affordance: box-shadow, a mask-image fade, or none |
+| `children`    | `ReactNode`                            | No       | —        | Scrollable content                                      |
+
+## Tokens
+
+- `--cascivo-color-border`
+- `--cascivo-color-surface`
+- `--cascivo-color-text`
+- `--cascivo-color-text-subtle`
+- `--cascivo-radius-control`
+- `--cascivo-scroll-area-height`
+- `--cascivo-scroll-area-width`
+
+## Examples
+
+### Vertical scroll
+
+```jsx
+<ScrollArea height="12rem">
+  <p>Long content…</p>
+</ScrollArea>
+```
+
+### Both axes
+
+```jsx
+<ScrollArea height="12rem" width="20rem" orientation="both">
+  <table>…</table>
+</ScrollArea>
+```
+
+## Boundaries
+
+| Area             | Level    | Note                                                                  |
+| ---------------- | -------- | --------------------------------------------------------------------- |
+| orientation      | flexible | vertical, horizontal, or both depending on content                    |
+| scroll behaviour | strict   | Relies on native overflow scrolling — never replace with JS scrolling |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo ScrollArea component (layout). A scroll container with styled, slim scrollbars and overflow shadows
+
+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).
+
+ScrollArea is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-border, --cascivo-color-surface, --cascivo-color-text, --cascivo-color-text-subtle, --cascivo-radius-control, --cascivo-scroll-area-height, --cascivo-scroll-area-width
+
+Accessibility: role "none", WCAG 2.2-AA, keyboard: ArrowUp/ArrowDown/PageUp/PageDown/Home/End. Keep it AA.
+
+Do not change (strict): scroll behaviour — Relies on native overflow scrolling — never replace with JS scrolling
+Flexible: orientation.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/search.md

@@ -0,0 +1,113 @@
+# Search
+
+**Category:** inputs  
+**Description:** Search input with debounced search callback and clear button
+
+## When to use
+
+- A query field that filters or searches content, with a built-in clear button and debounced onSearch
+- Free-text search where results update as the user types (debounced) or on Enter
+
+## When NOT to use
+
+- General non-search text entry — use Input
+- Search that presents an inline list of suggestions/results to pick from — use Combobox
+- A bounded numeric value — use NumberInput
+
+## Anti-patterns
+
+### Search provides type="search" semantics, a magnifier affordance, a clear button, and built-in debouncing so you avoid firing a query on every keystroke
+
+**Bad:** `<Input placeholder="Search" onChange={(e) => runQuery(e.target.value)} />`  
+**Good:** `<Search onSearch={(q) => runQuery(q)} debounceMs={300} />`  
+**Why:** Search provides type="search" semantics, a magnifier affordance, a clear button, and built-in debouncing so you avoid firing a query on every keystroke
+
+## Related components
+
+- **Input** (alternative): Use for general text entry that is not a search query
+- **Combobox** (alternative): Use when the query should surface a selectable list of suggestions
+
+## Accessibility rationale
+
+Renders a native <input type="search"> associated with a <label> (defaulting from the i18n catalog) so the field is announced as a searchbox; the clear control is a labeled <button> and moves focus back to the input after clearing.
+
+## Props
+
+| Name           | Type                      | Required | Default      | Description                                                        |
+| -------------- | ------------------------- | -------- | ------------ | ------------------------------------------------------------------ |
+| `value`        | `string`                  | No       | —            | The controlled value.                                              |
+| `defaultValue` | `string`                  | No       | ''           | The initial value when uncontrolled.                               |
+| `onChange`     | `(value: string) => void` | No       | —            | Called when the value changes.                                     |
+| `onSearch`     | `(value: string) => void` | No       | —            | Called with the query, debounced, as the user types.               |
+| `debounceMs`   | `number`                  | No       | 300          | Debounce delay (ms) before onSearch fires.                         |
+| `placeholder`  | `string`                  | No       | Search       | Placeholder text shown when the field is empty.                    |
+| `size`         | `'sm' \| 'md' \| 'lg'`    | No       | md           | Visual size of the component (e.g. 'sm', 'md', 'lg').              |
+| `label`        | `string`                  | No       | Search       | Text label for the control.                                        |
+| `disabled`     | `boolean`                 | No       | false        | When true, disables the control and removes it from the tab order. |
+| `clearLabel`   | `string`                  | No       | Clear search | Accessible label for the clear button.                             |
+| `id`           | `string`                  | No       | —            | Id applied to the root element (auto-generated when omitted).      |
+| `className`    | `string`                  | No       | —            | Additional CSS class names merged onto the root element.           |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-border-strong`
+- `--cascivo-color-accent`
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-radius-input`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic
+
+```jsx
+<Search onSearch={(q) => runQuery(q)} />
+```
+
+### Controlled
+
+```jsx
+<Search value={query} onChange={setQuery} onSearch={runQuery} debounceMs={500} />
+```
+
+### Large
+
+```jsx
+<Search size="lg" placeholder="Search products…" />
+```
+
+## Boundaries
+
+| Area              | Level    | Note                                                                         |
+| ----------------- | -------- | ---------------------------------------------------------------------------- |
+| token names       | strict   | Field and control styling must resolve to the listed --cascivo-\* tokens     |
+| debounce and copy | flexible | debounceMs and the placeholder/label/clear copy are free to suit the context |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Search component (inputs). Search input with debounced search callback and clear 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).
+
+Search is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border, --cascivo-color-border-strong, --cascivo-color-accent, --cascivo-color-text, --cascivo-color-text-muted, --cascivo-color-bg-subtle, --cascivo-radius-input, --cascivo-focus-ring
+
+Accessibility: role "searchbox", WCAG 2.2-AA, keyboard: Enter. Keep it AA.
+
+Do not change (strict): token names — Field and control styling must resolve to the listed --cascivo-* tokens
+Flexible: debounce and copy.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/section/cta.md

@@ -0,0 +1,83 @@
+# Cta
+
+**Category:** layout  
+**Description:** Call-to-action band — quiet hairline-bordered section with title, description, and centered actions. Replace demo content before shipping.
+
+## When to use
+
+- A call-to-action band with title, description, and centered actions
+- Prompting conversion between or after marketing sections
+
+## When NOT to use
+
+- The primary page intro — use Hero
+- General content grouping — use Section
+
+## Related components
+
+- **Hero** (pairs-with): Hero opens the page; CTA reinforces conversion later
+- **Section** (alternative): Use the plain section for non-CTA content
+
+## Accessibility rationale
+
+Renders a section with a heading and clearly labeled action controls.
+
+## Props
+
+| Name           | Type          | Required | Default | Description                                     |
+| -------------- | ------------- | -------- | ------- | ----------------------------------------------- |
+| `title`        | `ReactNode`   | Yes      | —       | Primary heading of the CTA band                 |
+| `description`  | `ReactNode`   | No       | —       | Supporting text below the title                 |
+| `actions`      | `ReactNode`   | No       | —       | Buttons or links centered below the description |
+| `headingLevel` | `1 \| 2 \| 3` | No       | 2       | HTML heading level for document outline control |
+
+## Tokens
+
+- `--cascivo-color-border`
+- `--cascivo-surface-subtle`
+- `--cascivo-text-2xl`
+- `--cascivo-text-base`
+- `--cascivo-font-bold`
+- `--cascivo-text-secondary`
+- `--cascivo-space-*`
+
+## Examples
+
+### CTA band
+
+Quiet bordered band with centered heading, description, and action buttons
+
+```jsx
+<Cta
+  title="Ready to ship?"
+  description="Add Cascade to your project in minutes."
+  actions={
+    <>
+      <Button>Get started</Button>
+      <Button variant="ghost">View on GitHub</Button>
+    </>
+  }
+/>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Cta component (layout). Call-to-action band — quiet hairline-bordered section with title, description, and centered actions. Replace demo content before shipping.
+
+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).
+
+Cta is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-border, --cascivo-surface-subtle, --cascivo-text-2xl, --cascivo-text-base, --cascivo-font-bold, --cascivo-text-secondary, --cascivo-space-*
+
+Accessibility: role "region", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/section/feature-grid.md

@@ -0,0 +1,98 @@
+# FeatureGrid
+
+**Category:** layout  
+**Description:** Feature section — AutoGrid of items with optional title, description, and icon slots. Icons are optional; the grid works text-only. Replace demo content before shipping.
+
+## When to use
+
+- A feature section laying out items in an auto-fitting grid
+- Showcasing product capabilities with optional icons and descriptions
+
+## When NOT to use
+
+- A single hero message — use Hero
+- A bare responsive grid without section framing — use AutoGrid
+
+## Related components
+
+- **AutoGrid** (contains): Uses an auto-fit grid to lay out feature items
+- **Hero** (pairs-with): Often follows the hero on a landing page
+
+## Accessibility rationale
+
+Renders a section with an optional heading grouping the feature items.
+
+## Props
+
+| Name           | Type            | Required | Default | Description                                                             |
+| -------------- | --------------- | -------- | ------- | ----------------------------------------------------------------------- |
+| `items`        | `FeatureItem[]` | Yes      | —       | Array of feature items with title, optional description, icon, and href |
+| `title`        | `ReactNode`     | No       | —       | Section heading above the grid                                          |
+| `description`  | `ReactNode`     | No       | —       | Subheading below the section title                                      |
+| `headingLevel` | `1 \| 2 \| 3`   | No       | 2       | Heading level for the section title (items use headingLevel + 1)        |
+| `min`          | `string`        | No       | "16rem" | Minimum track width forwarded to AutoGrid                               |
+
+## Tokens
+
+- `--cascivo-text-2xl`
+- `--cascivo-text-base`
+- `--cascivo-text-sm`
+- `--cascivo-font-bold`
+- `--cascivo-font-semibold`
+- `--cascivo-text-secondary`
+- `--cascivo-color-border`
+- `--cascivo-surface-subtle`
+- `--cascivo-space-*`
+
+## Examples
+
+### Feature grid (text-only)
+
+Four-item text-only feature grid with section heading
+
+```jsx
+<FeatureGrid
+  title="Built for production"
+  description="Everything you need to ship a polished product."
+  items={[
+    {
+      title: 'Zero config',
+      description: 'Copy a component and it works — no providers, no wrappers.',
+    },
+    {
+      title: 'Token-first',
+      description: 'Every color, size and radius is a CSS custom property you own.',
+    },
+    {
+      title: 'Signal-driven',
+      description: 'Fine-grained reactivity with @preact/signals-react — zero re-renders.',
+    },
+    {
+      title: 'Accessible by default',
+      description: 'WCAG 2.1 AA, keyboard navigable, logical CSS properties for RTL.',
+    },
+  ]}
+/>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo FeatureGrid component (layout). Feature section — AutoGrid of items with optional title, description, and icon slots. Icons are optional; the grid works text-only. Replace demo content before shipping.
+
+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).
+
+FeatureGrid is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-text-2xl, --cascivo-text-base, --cascivo-text-sm, --cascivo-font-bold, --cascivo-font-semibold, --cascivo-text-secondary, --cascivo-color-border, --cascivo-surface-subtle, --cascivo-space-*
+
+Accessibility: role "region", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```