# Collapsible

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs --> - collapsible.variants — `collapsibleVariants`, `coll…
- [collapsible.variants](./collapsible.variants.md) — `collapsibleVariants`, `collapsibleTriggerVariants`, and `collapsibleContentVariants` are the cva (class-variance-autho…
- collapsible.variants — `collapsibleVariants`, `coll…

- [collapsible.variants](./collapsible.variants.md) — `collapsibleVariants`, `collapsibleTriggerVariants`, and `collapsibleContentVariants` are the cva (class-variance-autho…

- collapsible.variants — `collapsibleVariants`, `coll…

- [collapsible.variants](./collapsible.variants.md) — `collapsibleVariants`, `collapsibleTriggerVariants`, and `collapsibleContentVariants` are the cva (class-variance-autho…

- collapsible.variants — `collapsibleVariants`, `coll…

- [collapsible.variants](./collapsible.variants.md) — `collapsibleVariants`, `collapsibleTriggerVariants`, and `collapsibleContentVariants` are the cva (class-variance-autho…
- [collapsible.variants](./collapsible.variants.md) — `collapsibleVariants`, `collapsibleTriggerVariants`, and `collapsibleContentVariants` are the cva (class-variance-autho…

## Purpose

`<Collapsible>`, `<CollapsibleTrigger>`, and `<CollapsibleContent>` are the chassis single-section disclosure primitives built on `@radix-ui/react-collapsible`. Radix supplies the WAI-ARIA disclosure semantics: the trigger renders a `<button>` with `aria-expanded` reflecting the open state and `aria-controls` referencing the content panel; the content carries `role="region"` (when given an accessible name) and unmounts while closed. The chassis layers a small cva recipe for structural alignment plus a `data-[state=open]:rotate-180` hook so a sibling chevron icon flips when the panel opens.

Use this primitive for ONE open/closed pair (e.g. an "advanced settings" disclosure or an FAQ item that does not belong to a sibling-managed group). For sibling panels with mutual-exclusion (`type="single"`) or multi-open (`type="multiple"`) semantics, use `<Accordion>` instead.

## Features

- WAI-ARIA disclosure semantics auto-managed by Radix (trigger `aria-expanded` / `aria-controls`, content `role="region"` when titled).
- Keyboard activation: Space and Enter both toggle the trigger.
- Controlled (`open` / `onOpenChange`) and uncontrolled (`defaultOpen`) modes.
- `disabled` prop short-circuits the toggle while keeping the trigger focusable for parity with `<button disabled>`.
- Smooth open/close animation via `--radix-collapsible-content-height` (`animate-collapsible-down/up` keyframes); collapses to none under `prefers-reduced-motion: reduce`.
- Theme-driven cva overrides for `Collapsible`, `CollapsibleTrigger`, and `CollapsibleContent`.
- All sub-components forward refs to their underlying Radix elements.
- Trigger cva carries focus-visible ring + hover-bg recipes so the disclosure looks like the chassis Button family without being one.

## Usage: Basic Example

```tsx
import {
    Collapsible,
    CollapsibleContent,
    CollapsibleTrigger,
} from "@suaveplan/react-ui";

export function AdvancedOptions() {
    return (
        <Collapsible>
            <CollapsibleTrigger>Advanced options</CollapsibleTrigger>
            <CollapsibleContent>
                <p>Hidden content revealed when toggled.</p>
            </CollapsibleContent>
        </Collapsible>
    );
}
```

## Usage: Advanced Example

```tsx
import {
    Button,
    Collapsible,
    CollapsibleContent,
    CollapsibleTrigger,
} from "@suaveplan/react-ui";
import { ChevronDownIcon } from "lucide-react";
import { useState } from "react";

export function FilterPanel({ children }: { children: React.ReactNode }) {
    const [open, setOpen] = useState(false);
    return (
        <Collapsible open={open} onOpenChange={setOpen}>
            <CollapsibleTrigger asChild>
                <Button variant="outline" className="w-full justify-between">
                    {open ? "Hide filters" : "Show filters"}
                    <ChevronDownIcon
                        data-icon="chevron"
                        className="size-4 transition-transform data-[state=open]:rotate-180"
                        aria-hidden
                    />
                </Button>
            </CollapsibleTrigger>
            <CollapsibleContent className="mt-3 rounded-md border p-3">
                {children}
            </CollapsibleContent>
        </Collapsible>
    );
}
```

## API Reference

### `<Collapsible>`

Renders the Radix Root that owns the open/closed state machine.

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` | `boolean` | _uncontrolled_ | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial open state for uncontrolled use. |
| `onOpenChange` | `(open: boolean) => void` | _none_ | Fires on every open / close transition. |
| `disabled` | `boolean` | `false` | When true, the trigger no longer toggles state. |

### `<CollapsibleTrigger>`

Wraps the Radix Trigger; renders a `<button>` (or polymorphically the child via `asChild`).

| Prop | Type | Default | Description |
|---|---|---|---|
| `asChild` | `boolean` | `false` | Merge the chassis trigger props onto the rendered child instead of wrapping in a `<button>`. Useful for binding to a `<Button>`. |

### `<CollapsibleContent>`

Wraps the Radix Content. Children unmount while closed (Radix default).

## Implementation Notes

- The chassis NEVER assigns a numeric `z-index` (per the shadcn skill rule); the disclosure stays in flow and stacking is implicit.
- The animation classes (`animate-collapsible-down/up`) require the chassis Tailwind preset to register the corresponding keyframes (shipped in `@suaveplan/react-ui/styles/global.css`).
- Radix unmounts content when closed by default; render a wrapper around the trigger if you need persistent layout (e.g. a `<section>` element that always appears in the DOM).
- The trigger cva matches the chassis `<Button variant="ghost">` recipe so a disclosure used alone looks like a Button without being one. Use `asChild` to literally render a `<Button>` when consistency with the surrounding button cluster matters.
- `disabled` flows through to the underlying `<button>` so screen-readers announce the disabled state correctly via the native attribute.