xertica-ui 2.2.1 → 2.4.0

package/docs/components/xertica-xlogo.md

@@ -1,35 +1,35 @@
-# XerticaXLogo
-
-A compact, square variant of the Xertica logo featuring the stylized "X" mark. Ideal for favicons, collapsed sidebars, and small profile badges.
-
----
-
-## Import
-
-```tsx
-import { XerticaXLogo } from 'xertica-ui/brand';
-```
-
----
-
-## Usage
-
-```tsx
-<XerticaXLogo className="size-10" />
-```
-
----
-
-## Props
-
-| Prop        | Type     | Default | Description                                   |
-| ----------- | -------- | ------- | --------------------------------------------- |
-| `className` | `string` | —       | Standard CSS classes for sizing and coloring. |
-
----
-
-## AI Rules
-
-> [!IMPORTANT]
->
-> - **Collapsed Sidebar**: This is the mandatory logo component to use when the `Sidebar` is in its collapsed state (`80px` width).
+# XerticaXLogo
+
+A compact, square variant of the Xertica logo featuring the stylized "X" mark. Ideal for favicons, collapsed sidebars, and small profile badges.
+
+---
+
+## Import
+
+```tsx
+import { XerticaXLogo } from 'xertica-ui/brand';
+```
+
+---
+
+## Usage
+
+```tsx
+<XerticaXLogo className="size-10" />
+```
+
+---
+
+## Props
+
+| Prop        | Type     | Default | Description                                   |
+| ----------- | -------- | ------- | --------------------------------------------- |
+| `className` | `string` | —       | Standard CSS classes for sizing and coloring. |
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+>
+> - **Collapsed Sidebar**: This is the mandatory logo component to use when the `Sidebar` is in its collapsed state (`80px` width).

package/docs/decision-tree.md

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