# Card

## Overview

The primary structural container for all content blocks in the application. `Card` provides elevation (via box shadow), background/border tokens, and a consistent internal padding system. It is the single correct way to create content panels — never recreate it with raw `<div>` utility classes.

---

## When to Use

- Containing any discrete content section: forms, tables, stat widgets, settings panels, activity feeds, list items with context.
- As the outer wrapper for any isolated content area within a page.
- As the widget container in dashboards (KPI cards, chart panels, event feeds).

## When NOT to Use

- Not needed as a full-page wrapper — pages use direct background color (`bg-muted`, `bg-background`).
- Do not stack cards inside cards unless there is a clear visual hierarchy reason.

---

## Anatomy

```
<Card>
  <CardHeader>
    <CardTitle />
    <CardDescription />
    <CardAction />       ← optional right-aligned slot
  </CardHeader>
  <CardContent />
  <CardFooter />
</Card>
```

All sub-components are optional — use only what the design requires.

---

## Sub-Components

| Component         | Description                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------- |
| `Card`            | Root container with background, border, shadow, and border-radius                           |
| `CardHeader`      | Top section with consistent padding (`p-6 pb-0`). Uses CSS grid to accommodate `CardAction` |
| `CardTitle`       | Main heading — renders as `<h3>`                                                            |
| `CardDescription` | Subtitle or description — muted text below the title                                        |
| `CardAction`      | Right-aligned slot inside `CardHeader` — auto-positioned by the grid layout                 |
| `CardContent`     | Main content area with consistent padding (`p-6 pt-0`)                                      |
| `CardFooter`      | Bottom section with action buttons                                                          |

---

## Props

All sub-components accept `className` and forward all HTML div attributes.

| Component         | Key Prop    | Description                                           |
| ----------------- | ----------- | ----------------------------------------------------- |
| `Card`            | `className` | Extend with additional classes                        |
| `CardHeader`      | `className` | Override header layout                                |
| `CardTitle`       | `className` | Override title styles                                 |
| `CardDescription` | `className` | Override description styles                           |
| `CardAction`      | `className` | Override action slot positioning                      |
| `CardContent`     | `className` | Extend content padding/layout                         |
| `CardFooter`      | `className` | Override footer layout (default: `flex items-center`) |

---

## Examples

### Full Anatomy

```tsx
import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
  Button,
} from 'xertica-ui/ui';

<Card className="w-[350px]">
  <CardHeader>
    <CardTitle>Detalhes do Projeto</CardTitle>
    <CardDescription>Gerencie as configurações do seu workspace.</CardDescription>
  </CardHeader>
  <CardContent>
    <p>Internal content goes here.</p>
  </CardContent>
  <CardFooter className="flex justify-between">
    <Button variant="outline">Descartar</Button>
    <Button>Salvar</Button>
  </CardFooter>
</Card>;
```

### With CardAction (right-aligned header slot)

`CardAction` is placed inside `CardHeader` and is automatically positioned to the far right using CSS grid. Use it for icon buttons, badges, or secondary controls that belong to the card header.

```tsx
import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardAction,
  Button,
} from 'xertica-ui/ui';
import { MoreHorizontal } from 'lucide-react';

<Card>
  <CardHeader>
    <CardTitle>Notificações</CardTitle>
    <CardDescription>Gerencie suas preferências de alerta.</CardDescription>
    <CardAction>
      <Button variant="ghost" size="icon">
        <MoreHorizontal className="size-4" />
      </Button>
    </CardAction>
  </CardHeader>
  <CardContent>{/* content */}</CardContent>
</Card>;
```

### Stats / KPI Card

```tsx
import { Card, CardHeader, CardTitle, CardContent, CardAction } from 'xertica-ui/ui';
import { DollarSign } from 'lucide-react';

<Card>
  <CardHeader>
    <CardTitle className="text-sm font-medium">Receita Total</CardTitle>
    <CardAction>
      <DollarSign className="size-4 text-muted-foreground" />
    </CardAction>
  </CardHeader>
  <CardContent>
    <p className="text-2xl font-bold">R$ 45.231</p>
    <p className="text-xs text-muted-foreground">+20.1% vs mês anterior</p>
  </CardContent>
</Card>;
```

### Form Container

```tsx
<Card className="w-full max-w-2xl mx-auto">
  <CardHeader>
    <CardTitle>Editar Perfil</CardTitle>
  </CardHeader>
  <form onSubmit={handleSubmit}>
    <CardContent className="grid gap-6 md:grid-cols-2">{/* form fields */}</CardContent>
    <CardFooter className="justify-end gap-2">
      <Button variant="ghost">Cancelar</Button>
      <Button type="submit">Salvar</Button>
    </CardFooter>
  </form>
</Card>
```

### Settings List (divider pattern)

```tsx
import { Card, CardHeader, CardTitle, CardContent, CardFooter } from 'xertica-ui/ui';
import { Badge, Separator, Button } from 'xertica-ui/ui';

<Card>
  <CardHeader>
    <CardTitle>Preferências da Conta</CardTitle>
  </CardHeader>
  <CardContent className="space-y-0 p-0">
    {items.map((item, i, arr) => (
      <div key={item.label}>
        <div className="flex items-center justify-between px-6 py-4">
          <div>
            <p className="text-sm font-medium">{item.label}</p>
            <p className="text-xs text-muted-foreground">{item.desc}</p>
          </div>
          <Badge variant={item.active ? 'success' : 'secondary'}>
            {item.active ? 'Ativo' : 'Inativo'}
          </Badge>
        </div>
        {i < arr.length - 1 && <Separator />}
      </div>
    ))}
  </CardContent>
</Card>;
```

### Team Member Card

```tsx
import { Card, CardContent } from 'xertica-ui/ui';
import { Avatar, AvatarFallback, Badge, Button, Separator } from 'xertica-ui/ui';

<Card className="w-52">
  <CardContent className="pt-6 flex flex-col items-center text-center gap-3">
    <Avatar className="size-14">
      <AvatarFallback>AS</AvatarFallback>
    </Avatar>
    <div>
      <p className="font-semibold text-sm">Ana Souza</p>
      <p className="text-xs text-muted-foreground">Frontend Engineer</p>
    </div>
    <Badge variant="success">Online</Badge>
    <Separator />
    <div className="flex gap-2 w-full">
      <Button variant="outline" size="sm" className="flex-1">
        Perfil
      </Button>
      <Button size="sm" className="flex-1">
        Contato
      </Button>
    </div>
  </CardContent>
</Card>;
```

---

## AI Rules

- **Never** create surfaces with raw Tailwind: `<div className="bg-white rounded-lg shadow border">` — use `<Card>` instead.
- **Always** import from `xertica-ui/ui`: `import { Card, CardContent, ... } from 'xertica-ui/ui'`.
- Use `CardAction` (not manual `flex justify-between` on `CardHeader`) when adding a right-aligned control to the header.
- `CardHeader` and `CardFooter` are optional — omit them if only a content area is needed.
- `CardFooter` with two action buttons (cancel + confirm) uses `className="flex justify-between"`. With a single confirm button, use `className="justify-end"`.
- The `CardTitle` renders as `<h3>`. Do not place heading elements (`h1`, `h2`) inside `CardTitle`.
- In compact dashboard stat cards, use `CardTitle` with `className="text-sm font-medium"` and the value in `CardContent` with `className="text-2xl font-bold"`.
- For pre-composed card patterns (ActivityCard, ProjectCard, ProfileCard, etc.), see [`card-patterns`](./card-patterns.md).

---

## Related Components

- [`StatsCard`](./stats-card.md) — Pre-built KPI card built on top of Card
- [`Card Patterns`](./card-patterns.md) — High-level composed cards for dashboards (ActivityCard, ProjectCard, etc.)
- [`Dialog`](./dialog.md) — Often uses Card-like structure internally
- [`Form`](./form.md) — Form pattern that wraps inside a Card