# Component Decision Guide — Xertica UI

Use this file when you need to choose between components that serve similar purposes. Each tree ends in a ✅ recommendation.

---

## Overlays & Modals

**"I need to show content over the current page"**

```
Does the user MUST confirm or cancel before proceeding?
├── YES → Use AlertDialog
│         (blocking, cannot dismiss by clicking outside)
│
└── NO → Is it a destructive action without a form?
    ├── YES → Use AlertDialog (always confirm destructive actions)
    │
    └── NO → Does it need to be wide / have a scrollable form?
        ├── YES (wide form, detail view) → Use Sheet (side-anchored)
        │         variant="right" for editing, variant="left" for nav drawers
        │
        ├── YES (mobile, bottom action) → Use Drawer
        │         (slides from bottom, mobile-optimized)
        │
        └── NO (compact modal) → Use Dialog
                  (centered, dismissible, for forms and confirmations)
```

**Quick rule:**
| Scenario | Component |
|---|---|
| "Are you sure you want to delete?" | `AlertDialog` |
| Edit form in overlay | `Dialog` (small) or `Sheet` (large) |
| Filter panel on mobile | `Drawer` |
| Settings panel from the right | `Sheet variant="right"` |
| File upload modal | `Dialog` |

---

## Floating Panels

**"I need something to appear anchored to an element"**

```
Is the content SHORT (1–2 lines, text-only)?
├── YES → Does it appear on hover (no interaction needed)?
│   ├── YES → Use Tooltip
│   │         (for icon buttons, abbreviated labels)
│   └── NO → Use Tooltip (still — if it's just a label)
│
└── NO → Does it contain interactive elements (forms, buttons, links)?
    ├── YES → Use Popover
    │         (date pickers, filter panels, color pickers)
    └── NO → Does it appear on hover (read-only rich content)?
        ├── YES → Use HoverCard
        │         (user profile previews, link previews, image thumbnails)
        └── NO (triggered by click, read-only) → Use Popover
```

**Quick rule:**
| Scenario | Component |
|---|---|
| "Open settings" icon button label | `Tooltip` |
| User avatar → show profile card on hover | `HoverCard` |
| Date picker | `Calendar` inside `Popover` |
| Filter options panel | `Popover` |
| Search suggestions | `Command` inside `Popover` |

---

## Feedback & Notifications

**"I need to communicate something to the user"**

```
Is the message EPHEMERAL (auto-dismisses after a few seconds)?
├── YES → Use toast() from sonner
│         toast.success() / toast.error() / toast.info() / toast.warning()
│
└── NO → Is it BLOCKING (user must act before continuing)?
    ├── YES + DESTRUCTIVE → Use AlertDialog
    ├── YES + INFORMATIONAL → Use Dialog
    │
    └── NO (persistent, inline, part of the page) → Use Alert
              variant="default" / "destructive" / "warning" / "info" / "success"
```

**Quick rule:**
| Scenario | Component |
|---|---|
| "Saved successfully" | `toast.success()` |
| "Error: server unavailable" | `toast.error()` |
| "This action will delete 50 records" | `AlertDialog` |
| "Your trial expires in 3 days" (in-page) | `Alert variant="warning"` |
| "Complete your profile" banner | `Alert variant="info"` |

---

## Navigation

**"I need navigation controls"**

```
Is this the PRIMARY app navigation (always visible, vertical)?
├── YES → Use Sidebar
│         (supports routes, groups, assistant mode)
│
└── NO → Is it showing the user's LOCATION in the hierarchy?
    ├── YES → Use Breadcrumb (inside Header via breadcrumbs prop)
    │
    └── NO → Is it HORIZONTAL top-level navigation?
        ├── YES (marketing / top sections) → Use NavigationMenu
        │
        └── NO → Is it switching between CONTENT SECTIONS on the same page?
            ├── YES → Use Tabs
            └── NO (step-by-step flow) → Use Stepper
```

**Quick rule:**
| Scenario | Component |
|---|---|
| App sidebar (Home, Settings, Users) | `Sidebar` |
| Home / Users / João Silva (where am I?) | `Breadcrumb` via `Header` |
| Dashboard / Analytics / Reports (page tabs) | `Tabs` |
| Step 1 → Step 2 → Step 3 (wizard) | `Stepper` |
| Marketing nav (Features, Pricing, Docs) | `NavigationMenu` |

---

## Form Inputs

**"I need the user to enter data"**

```
Single line of text?
├── YES → Is it specifically a search query with clear/icon?
│   ├── YES → Use Search
│   └── NO → Use Input
│
└── NO → Multiple lines / longer content?
    ├── YES → Needs rich formatting (bold, lists)?
    │   ├── YES → Use RichTextEditor
    │   └── NO → Use Textarea
    │
    └── NO → Choosing from a list of options?
        ├── 1 of many (short list, all visible) → Use RadioGroup
        ├── 1 of many (long list, searchable) → Use Select or Command
        ├── Multiple of many → Use Checkbox group
        └── ON/OFF single option → Use Switch (prominent) or Checkbox (subtle)
```

**Quick rule:**
| Scenario | Component |
|---|---|
| Name, email, phone | `Input` |
| Message, description, notes | `Textarea` |
| Status (Active / Inactive / Pending) | `Select` |
| Enable notifications (yes/no) | `Switch` |
| Agree to terms (tick box) | `Checkbox` |
| Choose role (Admin / Editor / Viewer) | `RadioGroup` |
| Date of birth | `Calendar` inside `Popover` |
| OTP / 2FA code | `InputOTP` |
| Attach a file | `FileUpload` |
| Range / volume | `Slider` |
| Search with autocomplete | `Command` |

---

## Toggle Controls

**"I need a button that stays pressed/active"**

```
Is it a persistent setting that applies immediately (on/off)?
├── YES → Is it prominent (its own row in settings)?
│   ├── YES → Use Switch
│   └── NO (subtle, next to a label) → Use Checkbox
│
└── NO → Is it part of a TOOLBAR (formatting, view modes)?
    ├── Single toggle → Use Toggle
    └── Group of related options → Use ToggleGroup
        ├── type="single" (one active at a time, like view mode)
        └── type="multiple" (multi-select, like formatting Bold+Italic)
```

---

## Loading States

**"Data is loading"**

```
Do you know the completion percentage?
├── YES → Use Progress
│
└── NO → Is it the whole page/card loading?
    ├── YES → Use Skeleton (mimic the shape of the content)
    └── NO (small spinner inline) → Use Button loading prop or custom spinner
```

---

## Data Display

**"I need to show a collection of records"**

```
Is it structured tabular data with columns?
├── YES → Use Table + Pagination
│
└── NO → Is it a chronological sequence of events?
    ├── YES → Use Timeline
    │
    └── NO → Is it KPI metrics / numbers?
        ├── YES → Use StatsCard
        │
        └── NO → Is the collection empty?
            └── YES → Use Empty (never show blank space)
```

---

## Media

**"I need to display audio or video"**

```
Is it VIDEO?
├── YES → Use VideoPlayer
│         (custom controls, floating mode, full HTML5 video)
│
└── NO (AUDIO) → Is it a global player (persists across pages)?
    ├── YES → Use AudioPlayer variant="bar"
    └── NO (embedded in a card) → Use AudioPlayer variant="card"

Both players support FloatingMediaWrapper for picture-in-picture.
```

---

## Choosing Between Similar Components

### Dialog vs AlertDialog

|                                    | Dialog                    | AlertDialog           |
| ---------------------------------- | ------------------------- | --------------------- |
| Dismissible by clicking outside    | ✅ yes                    | ❌ no                 |
| Required before destructive action | ❌ optional               | ✅ mandatory          |
| Can contain forms                  | ✅ yes                    | ✅ yes                |
| Use case                           | Edit, detail view, create | Delete, revoke, reset |

### Sheet vs Dialog

|          | Sheet                                  | Dialog                             |
| -------- | -------------------------------------- | ---------------------------------- |
| Position | Edge-anchored (right/left/top/bottom)  | Centered                           |
| Best for | Large forms, detail panels, navigation | Compact confirmations, small forms |
| Mobile   | Less ideal                             | Better                             |

### Tooltip vs HoverCard vs Popover

|           | Tooltip            | HoverCard                         | Popover                    |
| --------- | ------------------ | --------------------------------- | -------------------------- |
| Trigger   | Hover / Focus      | Hover                             | Click                      |
| Content   | Short text         | Rich read-only (profile, preview) | Interactive (form, picker) |
| Dismissal | Auto (mouse leave) | Auto (mouse leave)                | Click outside              |

### Switch vs Checkbox

|               | Switch                                           | Checkbox                            |
| ------------- | ------------------------------------------------ | ----------------------------------- |
| Visual weight | High (prominent)                                 | Low (subtle)                        |
| Best for      | Feature toggles, settings that apply immediately | Multi-select lists, form agreements |
| Has label?    | Usually standalone label in a row                | Always paired with inline label     |

### Sonner (Toast) vs Alert

|          | Sonner                   | Alert                       |
| -------- | ------------------------ | --------------------------- |
| Duration | Ephemeral (auto-dismiss) | Persistent (always visible) |
| Position | Fixed corner of screen   | Inline in page              |
| Use case | Action feedback          | Status banners, warnings    |

### Tabs vs Accordion vs Collapsible

|                       | Tabs                           | Accordion             | Collapsible             |
| --------------------- | ------------------------------ | --------------------- | ----------------------- |
| Shows one at a time   | ✅ yes                         | ✅ yes (default)      | n/a (single)            |
| Content always in DOM | ✅ yes                         | ❌ no                 | ❌ no                   |
| Horizontal trigger    | ✅ yes                         | ❌ vertical           | ❌ vertical             |
| Multiple open         | ❌ no                          | Optional              | n/a                     |
| Best for              | Page sections, analytics views | FAQs, settings groups | Single optional section |