@cascivo/mcp 0.2.0 → 0.3.4

package/dist/context/comparison.md

@@ -0,0 +1,117 @@
+# Comparison
+
+**Category:** display  
+**Description:** Reveals the difference between two layers with a draggable divider
+
+## When to use
+
+- Showing the difference between two versions of similar content (before/after edits, original vs processed)
+- Letting users interactively reveal one image or panel over another
+- Side-by-side visual demos where a draggable divider is clearer than two static images
+
+## When NOT to use
+
+- Comparing more than two items — use a layout or table instead
+- Non-visual data comparison — use a table or chart
+- Static side-by-side images with no need for an interactive reveal
+
+## Anti-patterns
+
+### The divider is a slider; without a label assistive tech announces an unnamed control
+
+**Bad:** `<Comparison before={<Before />} after={<After />} /> with no label`  
+**Good:** `<Comparison label="Reveal edited photo" before={<Before />} after={<After />} />`  
+**Why:** The divider is a slider; without a label assistive tech announces an unnamed control
+
+## Related components
+
+- **Slider** (alternative): Use Slider for selecting a numeric value rather than revealing layered content
+- **Carousel** (alternative): Use Carousel to step through more than two pieces of content
+
+## Accessibility rationale
+
+The divider is a role="slider" with aria-valuemin/max/now and full keyboard support (Arrow/Home/End/PageUp/PageDown); aria-orientation reflects the axis so the value and direction are conveyed without sight
+
+## Props
+
+| Name               | Type                         | Required | Default    | Description                                             |
+| ------------------ | ---------------------------- | -------- | ---------- | ------------------------------------------------------- |
+| `after`            | `ReactNode`                  | Yes      | —          | Base layer shown underneath                             |
+| `before`           | `ReactNode`                  | Yes      | —          | Top layer revealed up to the divider                    |
+| `position`         | `number`                     | No       | —          | Divider position 0–100 (controlled)                     |
+| `defaultPosition`  | `number`                     | No       | 50         | The initial divider position (0–100) when uncontrolled. |
+| `onPositionChange` | `(position: number) => void` | No       | —          | Called with the new divider position when it changes.   |
+| `orientation`      | `'horizontal' \| 'vertical'` | No       | horizontal | Layout orientation of the component.                    |
+| `keyboardStep`     | `number`                     | No       | 5          | How far the divider moves per arrow-key press.          |
+| `label`            | `string`                     | No       | —          | Text label for the control.                             |
+
+## Tokens
+
+- `--cascivo-radius-md`
+- `--cascivo-radius-full`
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-focus-ring`
+- `--cascivo-shadow-sm`
+- `--cascivo-target-min-coarse`
+
+## Examples
+
+### Image before/after
+
+```jsx
+<Comparison
+  before={<img src="/edited.jpg" alt="" />}
+  after={<img src="/original.jpg" alt="Original" />}
+  label="Reveal edited image"
+/>
+```
+
+### Vertical
+
+```jsx
+<Comparison orientation="vertical" before={<Before />} after={<After />} />
+```
+
+### Controlled
+
+```jsx
+<Comparison
+  position={position}
+  onPositionChange={setPosition}
+  before={<Before />}
+  after={<After />}
+/>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                 |
+| ----------- | -------- | -------------------------------------------------------------------- |
+| orientation | flexible | Horizontal or vertical depending on the content                      |
+| label       | strict   | Provide a label (or rely on the i18n default) so the slider is named |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Comparison component (display). Reveals the difference between two layers with a draggable divider
+
+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).
+
+Comparison is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-radius-md, --cascivo-radius-full, --cascivo-color-surface, --cascivo-color-border, --cascivo-color-focus-ring, --cascivo-shadow-sm, --cascivo-target-min-coarse
+
+Accessibility: role "slider", WCAG 2.2-AA, keyboard: ArrowLeft/ArrowRight/ArrowUp/ArrowDown/Home/End/PageUp/PageDown. Keep it AA.
+
+Do not change (strict): label — Provide a label (or rely on the i18n default) so the slider is named
+Flexible: orientation.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/contained-list.md

@@ -0,0 +1,103 @@
+# ContainedList
+
+**Category:** display  
+**Description:** Labelled list of rows inside a bordered container
+
+## When to use
+
+- Grouping a short set of related rows under a visible heading in a bordered surface
+- Presenting selectable or navigable rows (settings groups, member lists)
+- Separating a labelled cluster of items from surrounding page content
+
+## When NOT to use
+
+- A long, virtualised data set — use a Table or DataList instead
+- Plain bulleted prose where the container border adds no meaning — use List
+
+## Anti-patterns
+
+### A non-interactive div gives no focus or role semantics to assistive tech
+
+**Bad:** `Putting interactive controls on a plain ContainedListItem div`  
+**Good:** `Use ContainedListItem asChild with a <button> or <a> so the row is keyboard-focusable`  
+**Why:** A non-interactive div gives no focus or role semantics to assistive tech
+
+## Related components
+
+- **List** (alternative): List is for unbordered prose lists; ContainedList adds a labelled surface
+- **ContainedListItem** (contains): Each row is a ContainedListItem
+
+## Accessibility rationale
+
+The container heading labels the ul/li structure; interactive rows must slot a real button or link via asChild so role and focus are native, not faked on a div
+
+## Props
+
+| Name     | Type                       | Required | Default | Description                                  |
+| -------- | -------------------------- | -------- | ------- | -------------------------------------------- |
+| `label`  | `ReactNode`                | Yes      | —       | Text label for the control.                  |
+| `kind`   | `'on-page' \| 'disclosed'` | No       | on-page | Visual treatment — 'on-page' or 'disclosed'. |
+| `action` | `ReactNode`                | No       | —       | Primary action shown in the component.       |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-radius-surface`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic contained list
+
+```jsx
+<ContainedList label="Members">
+  <ContainedListItem>Ada Lovelace</ContainedListItem>
+  <ContainedListItem>Alan Turing</ContainedListItem>
+</ContainedList>
+```
+
+### Interactive rows
+
+```jsx
+<ContainedList label="Settings" kind="disclosed">
+  <ContainedListItem asChild>
+    <button type="button" onClick={open}>
+      Profile
+    </button>
+  </ContainedListItem>
+</ContainedList>
+```
+
+## Boundaries
+
+| Area           | Level    | Note                                                                     |
+| -------------- | -------- | ------------------------------------------------------------------------ |
+| kind           | flexible | on-page sits inline; disclosed adds a header band for menus and popovers |
+| list semantics | strict   | Rows are always ul/li; do not replace with generic divs                  |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo ContainedList component (display). Labelled list of rows inside a bordered container
+
+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).
+
+ContainedList is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border, --cascivo-color-bg-subtle, --cascivo-radius-surface, --cascivo-focus-ring
+
+Accessibility: role "list", WCAG 2.2-AA, keyboard: Tab/Enter/Space. Keep it AA.
+
+Do not change (strict): list semantics — Rows are always ul/li; do not replace with generic divs
+Flexible: kind.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/context-menu.md

@@ -0,0 +1,103 @@
+# ContextMenu
+
+**Category:** overlay  
+**Description:** Right-click context menu anchored at pointer coordinates via CSS custom properties
+
+## When to use
+
+- Offering actions contextual to an element via right-click (rename, delete, copy on a row or canvas item)
+- Power-user surfaces where the desktop right-click affordance is expected
+
+## When NOT to use
+
+- Primary actions that must be discoverable by all users — right-click is hidden; use a visible Button or Dropdown
+- Selecting a value or filtering a list — use Combobox/Select
+
+## Anti-patterns
+
+### Right-click is undiscoverable and unavailable on touch, so critical actions become unreachable for many users
+
+**Bad:** `Putting the only path to an action behind a right-click ContextMenu`  
+**Good:** `Also expose it via a visible Dropdown or Button; treat the context menu as a shortcut`  
+**Why:** Right-click is undiscoverable and unavailable on touch, so critical actions become unreachable for many users
+
+## Related components
+
+- **Dropdown** (alternative): Use a button-triggered menu when actions must be visible and touch-accessible
+- **Menu** (alternative): Use a general menu when the trigger is not a right-click gesture
+
+## Accessibility rationale
+
+The menu container is role="menu" and items are role="menuitem" with tabIndex management and aria-disabled, and it uses popover="auto" so it light-dismisses on Escape or outside click; the toggle event syncs that dismissal back into state so focus and open state stay consistent
+
+## Props
+
+| Name       | Type              | Required | Default | Description                                                         |
+| ---------- | ----------------- | -------- | ------- | ------------------------------------------------------------------- |
+| `children` | `React.ReactNode` | Yes      | —       | The right-click target first, followed by ContextMenuItem children. |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-radius-md`
+- `--cascivo-shadow-md`
+- `--cascivo-motion-enter`
+- `--cascivo-motion-exit`
+- `--cascivo-color-bg-subtle`
+
+## Examples
+
+### Basic
+
+```jsx
+<ContextMenu>
+  <div>Right-click me</div>
+  <ContextMenuItem onSelect={rename}>Rename</ContextMenuItem>
+  <ContextMenuItem onSelect={remove}>Delete</ContextMenuItem>
+</ContextMenu>
+```
+
+### Disabled item
+
+```jsx
+<ContextMenu>
+  <FileRow file={file} />
+  <ContextMenuItem onSelect={copy}>Copy</ContextMenuItem>
+  <ContextMenuItem onSelect={paste} disabled>
+    Paste
+  </ContextMenuItem>
+</ContextMenu>
+```
+
+## Boundaries
+
+| Area            | Level    | Note                                                                                           |
+| --------------- | -------- | ---------------------------------------------------------------------------------------------- |
+| menu contents   | flexible | Accepts arbitrary ContextMenuItem children after the trigger child                             |
+| anchor position | strict   | Anchored at pointer coordinates via --cascivo-context-x/y custom properties set on right-click |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo ContextMenu component (overlay). Right-click context menu anchored at pointer coordinates via CSS custom properties
+
+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).
+
+ContextMenu is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border, --cascivo-radius-md, --cascivo-shadow-md, --cascivo-motion-enter, --cascivo-motion-exit, --cascivo-color-bg-subtle
+
+Accessibility: role "menu", WCAG 2.2-AA, keyboard: ArrowDown/ArrowUp/Enter/Space/Escape. Keep it AA.
+
+Do not change (strict): anchor position — Anchored at pointer coordinates via --cascivo-context-x/y custom properties set on right-click
+Flexible: menu contents.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/copy-button.md

@@ -0,0 +1,106 @@
+# CopyButton
+
+**Category:** inputs  
+**Description:** Icon button that copies a value to the clipboard with copied feedback
+
+## When to use
+
+- Letting users copy a short value to the clipboard — install commands, API keys, tokens, share links
+- Inline next to code snippets or read-only fields where copying is the primary affordance
+
+## When NOT to use
+
+- Triggering a general action — use Button
+- Copying content the user can already select and edit freely where a copy affordance adds nothing
+
+## Anti-patterns
+
+### Its click handler is fixed to navigator.clipboard.writeText(value) plus copied feedback — overloading it breaks user expectation
+
+**Bad:** `Wiring CopyButton to perform a non-clipboard action via onClick`  
+**Good:** `Use Button for arbitrary actions; CopyButton always writes value to the clipboard`  
+**Why:** Its click handler is fixed to navigator.clipboard.writeText(value) plus copied feedback — overloading it breaks user expectation
+
+## Related components
+
+- **Button** (alternative): Use for actions other than copying to clipboard
+- **Input** (pairs-with): Often placed alongside a read-only field whose value it copies
+
+## Accessibility rationale
+
+Renders a native <button> so Enter/Space, focus, and role come from the platform; the aria-label swaps between copy and copied labels to announce the state change to screen readers since the icon swap alone is silent, and the SVG icons are aria-hidden
+
+## Props
+
+| Name     | Type                                 | Required | Default | Description                                           |
+| -------- | ------------------------------------ | -------- | ------- | ----------------------------------------------------- |
+| `value`  | `string`                             | Yes      | —       | The text written to the clipboard on click            |
+| `size`   | `'sm' \| 'md'`                       | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
+| `labels` | `{ copy?: string; copied?: string }` | No       | —       | Overrides the built-in i18n labels per instance       |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-text-subtle`
+- `--cascivo-color-text`
+- `--cascivo-color-border`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-success`
+- `--cascivo-radius-control`
+- `--cascivo-focus-ring`
+- `--cascivo-control-height-sm`
+- `--cascivo-control-height-md`
+
+## Examples
+
+### Default
+
+```jsx
+<CopyButton value="npx cascivo add button" />
+```
+
+### Small
+
+```jsx
+<CopyButton value="pnpm install" size="sm" />
+```
+
+### Custom labels
+
+Override the built-in copy/copied strings per instance
+
+```jsx
+<CopyButton value="token" labels={{ copy: 'Copy token', copied: 'Token copied' }} />
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                                              |
+| ----------- | -------- | ------------------------------------------------------------------------------------------------- |
+| labels      | flexible | copy/copied strings overridable via labels; default from i18n catalog                             |
+| token names | strict   | Styling resolves to semantic --cascivo-color-\* tokens; copied state uses --cascivo-color-success |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo CopyButton component (inputs). Icon button that copies a value to the clipboard with copied feedback
+
+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).
+
+CopyButton is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-text-subtle, --cascivo-color-text, --cascivo-color-border, --cascivo-color-bg-subtle, --cascivo-color-success, --cascivo-radius-control, --cascivo-focus-ring, --cascivo-control-height-sm, --cascivo-control-height-md
+
+Accessibility: role "button", WCAG 2.2-AA, keyboard: Enter/Space. Keep it AA.
+
+Do not change (strict): token names — Styling resolves to semantic --cascivo-color-* tokens; copied state uses --cascivo-color-success
+Flexible: labels.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/data-list.md

@@ -0,0 +1,99 @@
+# DataList
+
+**Category:** display  
+**Description:** Key-value pairs rendered as a description list
+
+## When to use
+
+- Displaying read-only key-value metadata (profile fields, record summaries)
+- Presenting structured attributes where each value maps to a single label
+- Compact detail panels next to or below a primary subject
+
+## When NOT to use
+
+- Editable fields — use form Inputs, not a DataList
+- Tabular data with many rows and columns — use a Table
+
+## Anti-patterns
+
+### dl/dt/dd conveys the term-to-description relationship to assistive tech for free
+
+**Bad:** `Faking a description list with stacked divs and manual labels`  
+**Good:** `Use the native dl/dt/dd structure DataList emits`  
+**Why:** dl/dt/dd conveys the term-to-description relationship to assistive tech for free
+
+## Related components
+
+- **ContainedList** (alternative): ContainedList shows single-value rows; DataList shows labelled pairs
+
+## Accessibility rationale
+
+Rendered as semantic dl with dt/dd pairs so the label-to-value association is native; no extra ARIA role is added
+
+## Props
+
+| Name          | Type                                                    | Required | Default    | Description                                           |
+| ------------- | ------------------------------------------------------- | -------- | ---------- | ----------------------------------------------------- |
+| `items`       | `{ id?: string; label: ReactNode; value: ReactNode }[]` | Yes      | —          | The items to render.                                  |
+| `orientation` | `'horizontal' \| 'vertical'`                            | No       | horizontal | Layout orientation of the component.                  |
+| `dividers`    | `boolean`                                               | No       | false      | When true, shows dividers between items.              |
+| `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-border`
+- `--cascivo-space-3`
+- `--cascivo-space-4`
+
+## Examples
+
+### Horizontal data list
+
+```jsx
+<DataList
+  items={[
+    { label: 'Name', value: 'Ada Lovelace' },
+    { label: 'Role', value: 'Mathematician' },
+  ]}
+/>
+```
+
+### Vertical with dividers
+
+```jsx
+<DataList orientation="vertical" dividers items={[{ label: 'Email', value: 'ada@example.com' }]} />
+```
+
+## Boundaries
+
+| Area                 | Level    | Note                                                                        |
+| -------------------- | -------- | --------------------------------------------------------------------------- |
+| orientation and size | flexible | horizontal for wide panels, vertical for narrow columns; size tunes density |
+| dl semantics         | strict   | Always renders dl/dt/dd; do not substitute generic elements                 |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo DataList component (display). Key-value pairs rendered as a description list
+
+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).
+
+DataList is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-text, --cascivo-color-text-subtle, --cascivo-color-border, --cascivo-space-3, --cascivo-space-4
+
+Accessibility: role "none", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): dl semantics — Always renders dl/dt/dd; do not substitute generic elements
+Flexible: orientation and size.
+
+Do not invent props, tokens, or global viewport media queries.
+```