xertica-ui 2.2.1 → 2.4.0

package/docs/components/card.md

@@ -1,245 +1,245 @@
-# 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
+# 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