@cascivo/mcp 0.1.8 → 0.3.3

package/dist/context/toc.md

@@ -0,0 +1,110 @@
+# Toc
+
+**Category:** navigation  
+**Description:** Table of contents with scroll-spy highlighting of the active section
+
+## When to use
+
+- Long-form pages (docs, articles) that benefit from in-page jump links
+- Highlighting which section is currently in view as the reader scrolls
+
+## When NOT to use
+
+- Top-level site navigation between pages — use NavigationMenu or SideNav
+- Showing hierarchy depth of the current page — use Breadcrumb
+
+## Anti-patterns
+
+### Toc links to sections within the current document, not to other pages
+
+**Bad:** `Using Toc as the primary site navigation between routes`  
+**Good:** `<NavigationMenu> / <SideNav> for cross-page navigation`  
+**Why:** Toc links to sections within the current document, not to other pages
+
+## Related components
+
+- **SideNav** (alternative): SideNav navigates between pages; Toc navigates within one page
+- **Breadcrumb** (alternative): Breadcrumb shows ancestor hierarchy; Toc shows in-page sections
+
+## Accessibility rationale
+
+Rendered as a <nav> landmark with a label; entries are real anchor links and the active one is marked aria-current="location" so assistive tech announces the current section
+
+## Props
+
+| Name             | Type                                              | Required | Default | Description                                                      |
+| ---------------- | ------------------------------------------------- | -------- | ------- | ---------------------------------------------------------------- |
+| `items`          | `{ id: string; label: string; level?: number }[]` | Yes      | —       | The items to render.                                             |
+| `activeId`       | `string`                                          | No       | —       | Controlled active item id; disables built-in scroll-spy when set |
+| `onActiveChange` | `(id: string) => void`                            | No       | —       | Called with the id of the active section when it changes.        |
+| `labels`         | `{ nav?: 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-font-sans`
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-accent`
+- `--cascivo-focus-ring`
+- `--cascivo-target-min-coarse`
+
+## Examples
+
+### Basic
+
+```jsx
+<Toc
+  items={[
+    { id: 'intro', label: 'Introduction' },
+    { id: 'usage', label: 'Usage' },
+    { id: 'api', label: 'API', level: 3 },
+  ]}
+/>
+```
+
+### Controlled active item
+
+Pass activeId to drive the highlight yourself; scroll-spy is disabled.
+
+```jsx
+<Toc
+  activeId="usage"
+  items={[
+    { id: 'intro', label: 'Introduction' },
+    { id: 'usage', label: 'Usage' },
+  ]}
+/>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                     |
+| ----------- | -------- | ------------------------------------------------------------------------ |
+| activeId    | flexible | Control the highlight externally, or omit it for built-in scroll-spy     |
+| token names | strict   | Colors, focus ring, and touch target 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 Toc component (navigation). Table of contents with scroll-spy highlighting of the active section
+
+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).
+
+Toc is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-font-sans, --cascivo-color-text, --cascivo-color-text-muted, --cascivo-color-accent, --cascivo-focus-ring, --cascivo-target-min-coarse
+
+Accessibility: role "navigation", WCAG 2.2-AA, keyboard: Tab/Enter. Keep it AA.
+
+Do not change (strict): token names — Colors, focus ring, and touch target must resolve to --cascivo-* tokens
+Flexible: activeId.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/toggle-group.md

@@ -0,0 +1,118 @@
+# ToggleGroup
+
+**Category:** inputs  
+**Description:** A set of toggle buttons for single or multiple selection
+
+## When to use
+
+- Choosing one value from a small, mutually exclusive set that should stay visible (type="single")
+- Toggling several independent options in a compact segmented control (type="multiple")
+
+## When NOT to use
+
+- The options are independent actions, not a selection — use ButtonGroup
+- There are many options or they need labels and descriptions — use Radio or Checkbox groups
+
+## Anti-patterns
+
+### Single-select used as a controlled value should be driven by value/onValueChange so the source of truth lives with the parent
+
+**Bad:** `<ToggleGroup type="single" items={items} onValueChange={save} />`  
+**Good:** `<ToggleGroup type="single" value={align} onValueChange={setAlign} items={items} />`  
+**Why:** Single-select used as a controlled value should be driven by value/onValueChange so the source of truth lives with the parent
+
+## Related components
+
+- **ButtonGroup** (alternative): Use when the buttons fire independent actions rather than select a value
+- **Toggle** (alternative): Use a single Toggle for one standalone binary option
+
+## Accessibility rationale
+
+Single mode renders role="radiogroup" with role="radio" + aria-checked items; multiple mode uses a plain group of buttons with aria-pressed. Roving tabindex makes the set one tab stop and arrow keys move between items, matching the APG radiogroup/toolbar patterns
+
+## Props
+
+| Name            | Type                                                                              | Required | Default    | Description                                                                    |
+| --------------- | --------------------------------------------------------------------------------- | -------- | ---------- | ------------------------------------------------------------------------------ |
+| `type`          | `'single' \| 'multiple'`                                                          | Yes      | —          | Whether one or multiple items can be pressed at once ('single' \| 'multiple'). |
+| `value`         | `string \| string[]`                                                              | No       | —          | The controlled value.                                                          |
+| `defaultValue`  | `string \| string[]`                                                              | No       | —          | The initial value when uncontrolled.                                           |
+| `onValueChange` | `(value: string \| string[]) => void`                                             | No       | —          | Called with the new value when it changes.                                     |
+| `items`         | `{ value: string; label?: string; icon?: React.ReactNode; disabled?: boolean }[]` | Yes      | —          | The items to render.                                                           |
+| `orientation`   | `'horizontal' \| 'vertical'`                                                      | No       | horizontal | Layout orientation of the component.                                           |
+| `size`          | `'sm' \| 'md' \| 'lg'`                                                            | No       | md         | Visual size of the component (e.g. 'sm', 'md', 'lg').                          |
+| `disabled`      | `boolean`                                                                         | No       | false      | When true, disables the control and removes it from the tab order.             |
+
+## Tokens
+
+- `--cascivo-control-height-sm`
+- `--cascivo-control-height-md`
+- `--cascivo-control-height-lg`
+- `--cascivo-radius-control`
+- `--cascivo-radius-item`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-surface`
+- `--cascivo-color-text`
+- `--cascivo-shadow-sm`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Single selection
+
+```jsx
+<ToggleGroup
+  type="single"
+  defaultValue="left"
+  items={[
+    { value: 'left', label: 'Left' },
+    { value: 'center', label: 'Center' },
+    { value: 'right', label: 'Right' },
+  ]}
+/>
+```
+
+### Multiple selection
+
+```jsx
+<ToggleGroup
+  type="multiple"
+  defaultValue={['bold']}
+  items={[
+    { value: 'bold', label: 'Bold' },
+    { value: 'italic', label: 'Italic' },
+  ]}
+/>
+```
+
+## Boundaries
+
+| Area         | Level    | Note                                                                                 |
+| ------------ | -------- | ------------------------------------------------------------------------------------ |
+| token names  | strict   | Item height must resolve to --cascivo-control-height-\* to align with other controls |
+| item content | flexible | Items may use a text label, an icon, or both; consumer owns the icon set             |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo ToggleGroup component (inputs). A set of toggle buttons for single or multiple selection
+
+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).
+
+ToggleGroup is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-control-height-sm, --cascivo-control-height-md, --cascivo-control-height-lg, --cascivo-radius-control, --cascivo-radius-item, --cascivo-color-bg-subtle, --cascivo-color-surface, --cascivo-color-text, --cascivo-shadow-sm, --cascivo-focus-ring
+
+Accessibility: role "radiogroup", WCAG 2.2-AA, keyboard: ArrowRight/ArrowLeft/ArrowUp/ArrowDown/Home/End/Enter/Space. Keep it AA.
+
+Do not change (strict): token names — Item height must resolve to --cascivo-control-height-* to align with other controls
+Flexible: item content.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/toggle.md

@@ -0,0 +1,103 @@
+# Toggle
+
+**Category:** inputs  
+**Description:** On/off switch built as an accessible button
+
+## When to use
+
+- Flipping a single binary setting that takes effect immediately (e.g. notifications on/off)
+- On/off state where a physical switch metaphor reads better than a checkmark
+- Settings screens where the change applies live without a separate submit
+
+## When NOT to use
+
+- Selecting items in a form that is submitted later — use Checkbox
+- Choosing one option among several mutually exclusive labels — use SegmentedControl or Radio
+
+## Anti-patterns
+
+### A switch implies an instant on/off setting; agreement that is submitted with the form is a checkbox
+
+**Bad:** `<Toggle label="I accept the terms" /> inside a submitted form`  
+**Good:** `<Checkbox label="I accept the terms" />`  
+**Why:** A switch implies an instant on/off setting; agreement that is submitted with the form is a checkbox
+
+### The `label` prop renders visible text and is the accessible name; when a heading already names the control, use aria-label so the name is not shown (and read) twice
+
+**Bad:** `<h3>Dark mode</h3><Toggle label="Dark mode" /> — the label repeats the heading`  
+**Good:** `<h3>Dark mode</h3><Toggle aria-label="Dark mode" />`  
+**Why:** The `label` prop renders visible text and is the accessible name; when a heading already names the control, use aria-label so the name is not shown (and read) twice
+
+## Related components
+
+- **Checkbox** (alternative): Use for form selections submitted later rather than instant settings
+- **SegmentedControl** (alternative): Use when choosing among several exclusive options, not just on/off
+
+## Accessibility rationale
+
+Renders a <button role="switch"> with aria-checked reflecting state, so assistive tech announces it as a switch and Space/Enter toggle it via native button activation.
+
+## Props
+
+| Name             | Type                         | Required | Default | Description                                                                                                                                                                           |
+| ---------------- | ---------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `checked`        | `boolean`                    | No       | —       | Whether the control is checked (controlled).                                                                                                                                          |
+| `defaultChecked` | `boolean`                    | No       | false   | Whether the control is checked on first render (uncontrolled).                                                                                                                        |
+| `onChange`       | `(checked: boolean) => void` | No       | —       | Called when the value changes.                                                                                                                                                        |
+| `label`          | `string`                     | No       | —       | Visible text label beside the switch; it also becomes the accessible name. When a heading already labels the control, omit this and pass aria-label instead to avoid duplicated text. |
+| `size`           | `'sm' \| 'md'`               | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg').                                                                                                                                 |
+| `disabled`       | `boolean`                    | No       | false   | When true, disables the control and removes it from the tab order.                                                                                                                    |
+
+## Tokens
+
+- `--cascivo-color-accent`
+- `--cascivo-color-border-strong`
+- `--cascivo-color-surface`
+- `--cascivo-radius-full`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Uncontrolled
+
+```jsx
+<Toggle label="Notifications" defaultChecked />
+```
+
+### Controlled
+
+```jsx
+<Toggle checked={enabled} onChange={setEnabled} label="Dark mode" />
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                                   |
+| ----------- | -------- | -------------------------------------------------------------------------------------- |
+| token names | strict   | Track and thumb colors must resolve to --cascivo-color-\* / radius / focus-ring tokens |
+| label copy  | flexible | Optional label describing the setting being toggled                                    |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Toggle component (inputs). On/off switch built as an accessible 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).
+
+Toggle is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-accent, --cascivo-color-border-strong, --cascivo-color-surface, --cascivo-radius-full, --cascivo-focus-ring
+
+Accessibility: role "switch", WCAG 2.2-AA, keyboard: Space/Enter. Keep it AA.
+
+Do not change (strict): token names — Track and thumb colors must resolve to --cascivo-color-* / radius / focus-ring tokens
+Flexible: label copy.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/toggletip.md

@@ -0,0 +1,119 @@
+# Toggletip
+
+**Category:** overlay  
+**Description:** A click-triggered info popover for supplementary, selectable content
+
+## When to use
+
+- Revealing brief supplementary information on demand when the user clicks an info affordance
+- Content that must be selectable or contain a link, where a hover Tooltip would be unreachable
+- Touch-friendly hint surfaces where hover is unavailable
+
+## When NOT to use
+
+- A passive label that should appear on hover/focus without a click — use Tooltip
+- A blocking, focus-trapping dialog for a task — use Modal
+- Rich forms or pickers anchored to a trigger — use Popover
+- A list of one-shot actions behind a button — use MenuButton
+
+## Anti-patterns
+
+### Hover tooltips disappear on pointer-out and are not keyboard- or touch-reachable for interaction, so interactive or copyable content needs a click-toggled bubble
+
+**Bad:** `Using a hover Tooltip to hold a link or text the user needs to read or copy`  
+**Good:** `Use a Toggletip so the content stays open on click and remains reachable and selectable`  
+**Why:** Hover tooltips disappear on pointer-out and are not keyboard- or touch-reachable for interaction, so interactive or copyable content needs a click-toggled bubble
+
+### An icon-only button with no accessible name cannot be operated by screen-reader or voice users
+
+**Bad:** `Giving the trigger an icon with no text and no labels.label override`  
+**Good:** `Provide labels.label or rely on the built-in i18n accessible name`  
+**Why:** An icon-only button with no accessible name cannot be operated by screen-reader or voice users
+
+## Related components
+
+- **Tooltip** (alternative): Use Tooltip for non-interactive hints shown on hover/focus rather than click
+- **Popover** (alternative): Use Popover for richer interactive content like forms or pickers
+- **MenuButton** (alternative): Use MenuButton when the trigger should reveal a list of actions
+
+## Accessibility rationale
+
+The trigger is a real <button> with aria-expanded reflecting open state and aria-controls pointing at the bubble; an icon-only trigger gets an accessible name from labels.label or the built-in i18n catalog. The bubble is role="status" so its content is announced when it opens, and unlike a hover tooltip the content remains visible and reachable for selection and links. DismissableLayer provides Escape and outside-pointer dismissal, and high-contrast and reduced-motion preferences are honored in CSS.
+
+## Props
+
+| Name           | Type                                                                                                   | Required | Default | Description                                                   |
+| -------------- | ------------------------------------------------------------------------------------------------------ | -------- | ------- | ------------------------------------------------------------- |
+| `trigger`      | `ReactNode`                                                                                            | Yes      | —       | Trigger content, rendered inside a button (e.g. an info icon) |
+| `children`     | `ReactNode`                                                                                            | Yes      | —       | The popover content — interactive and selectable              |
+| `placement`    | `'top' \| 'bottom' \| 'left' \| 'right' \| 'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end'` | No       | 'top'   | Side and alignment of the bubble relative to the trigger      |
+| `defaultOpen`  | `boolean`                                                                                              | No       | false   | Initial open state when uncontrolled                          |
+| `open`         | `boolean`                                                                                              | No       | —       | Controlled open state                                         |
+| `onOpenChange` | `(open: boolean) => void`                                                                              | No       | —       | Called whenever the open state should change                  |
+| `labels`       | `{ label?: string }`                                                                                   | No       | —       | Override the trigger accessible name                          |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-text`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-radius-control`
+- `--cascivo-radius-overlay`
+- `--cascivo-shadow-md`
+- `--cascivo-focus-ring`
+- `--cascivo-motion-enter`
+- `--cascivo-z-tooltip`
+
+## Examples
+
+### Info toggletip
+
+An info button that reveals supplementary text on click
+
+```jsx
+<Toggletip trigger={<InfoIcon />}>Your password must contain at least 12 characters.</Toggletip>
+```
+
+### Controlled
+
+Drive the open state from the parent
+
+```jsx
+<Toggletip trigger={<InfoIcon />} open={open} onOpenChange={setOpen} placement="bottom-start">
+  <a href="/docs">Learn more</a>
+</Toggletip>
+```
+
+## Boundaries
+
+| Area                 | Level    | Note                                                                         |
+| -------------------- | -------- | ---------------------------------------------------------------------------- |
+| token names          | strict   | Trigger and bubble styling must resolve to the listed --cascivo-\* tokens    |
+| content              | flexible | trigger and children accept arbitrary ReactNode supplied by the consumer     |
+| open state ownership | flexible | Use uncontrolled (defaultOpen) or controlled (open + onOpenChange) as needed |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Toggletip component (overlay). A click-triggered info popover for supplementary, selectable content
+
+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).
+
+Toggletip is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border, --cascivo-color-text, --cascivo-color-bg-subtle, --cascivo-radius-control, --cascivo-radius-overlay, --cascivo-shadow-md, --cascivo-focus-ring, --cascivo-motion-enter, --cascivo-z-tooltip
+
+Accessibility: role "status", WCAG 2.2-AA, keyboard: Enter/Space/Escape. Keep it AA.
+
+Do not change (strict): token names — Trigger and bubble styling must resolve to the listed --cascivo-* tokens
+Flexible: content, open state ownership.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/tooltip.md

@@ -0,0 +1,92 @@
+# Tooltip
+
+**Category:** overlay  
+**Description:** Contextual label shown on hover or focus
+
+## When to use
+
+- Labeling an icon-only control or clarifying a terse element on hover or focus
+- Showing brief, supplementary text that is non-essential to completing the task
+- Progressive disclosure of a short hint anchored to a trigger element
+
+## When NOT to use
+
+- The content is interactive (links, buttons, inputs) — use Popover
+- Richer non-interactive preview content is needed — use HoverCard
+- The information is essential and must always be visible — render it inline instead
+
+## Anti-patterns
+
+### Tooltips are hover/focus hints and cannot reliably hold focusable content; interactive content belongs in a Popover
+
+**Bad:** `<Tooltip content={<button>Undo</button>}><Icon /></Tooltip>`  
+**Good:** `<Popover><button>Undo</button></Popover>`  
+**Why:** Tooltips are hover/focus hints and cannot reliably hold focusable content; interactive content belongs in a Popover
+
+## Related components
+
+- **Popover** (alternative): Use when the floating content is interactive
+- **HoverCard** (alternative): Use for richer non-interactive preview content
+- **Button** (pairs-with): Commonly wraps an icon button to explain its action
+
+## Accessibility rationale
+
+The floating element uses role="tooltip" and is linked to the trigger via aria-describedby only while visible; it shows on both hover and keyboard focus so it is reachable without a pointer.
+
+## Props
+
+| Name        | Type                                     | Required | Default | Description                               |
+| ----------- | ---------------------------------------- | -------- | ------- | ----------------------------------------- |
+| `content`   | `ReactNode`                              | Yes      | —       | The tooltip content shown on hover/focus. |
+| `placement` | `'top' \| 'right' \| 'bottom' \| 'left'` | No       | top     | Placement relative to the trigger.        |
+| `children`  | `ReactElement`                           | Yes      | —       | Content rendered inside the component.    |
+| `delay`     | `number`                                 | No       | 200     | Milliseconds to wait before showing       |
+
+## Tokens
+
+- `--cascivo-color-text`
+- `--cascivo-color-text-on-accent`
+- `--cascivo-radius-sm`
+- `--cascivo-z-tooltip`
+
+## Examples
+
+### Basic
+
+```jsx
+<Tooltip content="Copy to clipboard">
+  <Button>Copy</Button>
+</Tooltip>
+```
+
+## Boundaries
+
+| Area      | Level    | Note                                                                 |
+| --------- | -------- | -------------------------------------------------------------------- |
+| placement | strict   | Limited to top \| right \| bottom \| left, positioned via CSS anchor |
+| delay     | flexible | Consumer can tune the show delay (default 200ms)                     |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Tooltip component (overlay). Contextual label shown on hover or focus
+
+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).
+
+Tooltip is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-text, --cascivo-color-text-on-accent, --cascivo-radius-sm, --cascivo-z-tooltip
+
+Accessibility: role "tooltip", WCAG 2.2-AA, keyboard: Tab/Escape. Keep it AA.
+
+Do not change (strict): placement — Limited to top | right | bottom | left, positioned via CSS anchor
+Flexible: delay.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/tree-view.md

@@ -0,0 +1,107 @@
+# TreeView
+
+**Category:** display  
+**Description:** Hierarchical, expandable tree of nodes with keyboard navigation and selection
+
+## When to use
+
+- Showing nested, parent/child data the user expands and collapses (file trees, org charts, nav)
+- Letting the user pick one or several nodes from a hierarchy
+- Navigating deep structures where indentation communicates depth
+
+## When NOT to use
+
+- A flat, non-nested list of choices — use List or StructuredList
+- A small set of mutually exclusive sections of prose — use Accordion
+
+## Anti-patterns
+
+### A tree with no hierarchy adds twisties and ARIA tree semantics for content that is flat
+
+**Bad:** `A single-level TreeView with no children on any node`  
+**Good:** `A List or StructuredList`  
+**Why:** A tree with no hierarchy adds twisties and ARIA tree semantics for content that is flat
+
+## Related components
+
+- **Accordion** (alternative): Accordion stacks a few sequential disclosure sections; TreeView models arbitrary-depth hierarchy
+- **StructuredList** (alternative): StructuredList is flat tabular rows; TreeView is nested with expand/collapse
+
+## Accessibility rationale
+
+Implements the WAI-ARIA TreeView pattern: role=tree on the root, role=treeitem with aria-level/posinset/setsize and aria-expanded on each node, a single roving tabindex, and full APG keyboard support (arrows expand/collapse and move, Home/End, Enter/Space select, printable-character typeahead)
+
+## Props
+
+| Name               | Type                                                                          | Required | Default | Description                                                          |
+| ------------------ | ----------------------------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------- |
+| `items`            | `{ id: string; label: ReactNode; icon?: ReactNode; children?: TreeNode[] }[]` | Yes      | —       | The items to render.                                                 |
+| `selectionMode`    | `'single' \| 'multi'`                                                         | No       | single  | Whether one or multiple nodes can be selected ('single' \| 'multi'). |
+| `selected`         | `string \| string[]`                                                          | No       | —       | The controlled selected node id(s).                                  |
+| `defaultSelected`  | `string \| string[]`                                                          | No       | —       | The initially selected node id(s) when uncontrolled.                 |
+| `onSelectChange`   | `(selected: string \| string[]) => void`                                      | No       | —       | Called with the new selection when it changes.                       |
+| `expanded`         | `string[]`                                                                    | No       | —       | The controlled set of expanded node ids.                             |
+| `defaultExpanded`  | `string[]`                                                                    | No       | —       | The initially expanded node ids when uncontrolled.                   |
+| `onExpandedChange` | `(expanded: string[]) => void`                                                | No       | —       | Called with the new expanded set when it changes.                    |
+
+## Tokens
+
+- `--cascivo-tree-indent`
+- `--cascivo-color-border`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-text`
+- `--cascivo-color-text-subtle`
+- `--cascivo-radius-control`
+- `--cascivo-focus-ring`
+- `--cascivo-duration-200`
+- `--cascivo-ease-out`
+
+## Examples
+
+### Single select
+
+```jsx
+<TreeView
+  defaultExpanded={['src']}
+  items={[{ id: 'src', label: 'src', children: [{ id: 'index', label: 'index.ts' }] }]}
+/>
+```
+
+### Multi select
+
+```jsx
+<TreeView selectionMode="multi" items={nodes} onSelectChange={(ids) => set(ids)} />
+```
+
+## Boundaries
+
+| Area           | Level    | Note                                                                                     |
+| -------------- | -------- | ---------------------------------------------------------------------------------------- |
+| selectionMode  | flexible | single vs multi is the consumer’s choice based on the interaction                        |
+| keyboard model | strict   | Arrow/Home/End/typeahead behavior follows the APG tree pattern and must not be re-mapped |
+| indent token   | flexible | Per-level indent is driven by --cascivo-tree-indent and may be overridden                |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo TreeView component (display). Hierarchical, expandable tree of nodes with keyboard navigation and selection
+
+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).
+
+TreeView is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-tree-indent, --cascivo-color-border, --cascivo-color-bg-subtle, --cascivo-color-text, --cascivo-color-text-subtle, --cascivo-radius-control, --cascivo-focus-ring, --cascivo-duration-200, --cascivo-ease-out
+
+Accessibility: role "tree", WCAG 2.2-AA, keyboard: ArrowDown/ArrowUp/ArrowRight/ArrowLeft/Home/End/Enter/Space/Typeahead. Keep it AA.
+
+Do not change (strict): keyboard model — Arrow/Home/End/typeahead behavior follows the APG tree pattern and must not be re-mapped
+Flexible: selectionMode, indent token.
+
+Do not invent props, tokens, or global viewport media queries.
+```