xertica-ui 2.1.2 → 2.1.3

package/docs/components/xertica-provider.md

@@ -1,6 +1,6 @@
-# XerticaProvider
-
-The recommended root wrapper for Xertica UI applications. Most components can render independently with local fallbacks, but the provider centralizes app-wide state, theming, maps, tooltips, assistant state, API keys, and notifications.
+# XerticaProvider
+
+The recommended root wrapper for Xertica UI applications. Most components can render independently with local fallbacks, but the provider centralizes app-wide state, theming, maps, tooltips, assistant state, API keys, and notifications.
 
 ---
 
@@ -31,34 +31,34 @@ function Root() {
 
 ## Props
 
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `children`| `ReactNode`| _(required)_ | The entrypoint of your application. |
-| `apiKey` | `string` | - | Initial Gemini/AI key forwarded to `ApiKeyProvider`. |
-| `googleMapsApiKey` | `string` | - | Initial Google Maps JavaScript API key. |
-| `defaultBrandTheme` | `string` | - | Initial brand color theme id. |
-| `primaryColor` | `string` | - | Primary brand color override. |
-| `useCustomTokens` | `boolean` | `false` | Skips runtime brand token injection when the host app owns tokens. |
-| `disableDarkMode` | `boolean` | `false` | Forces light mode and disables dark-mode toggling from the theme provider. |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children`| `ReactNode`| _(required)_ | The entrypoint of your application. |
+| `apiKey` | `string` | - | Initial Gemini/AI key forwarded to `ApiKeyProvider`. |
+| `googleMapsApiKey` | `string` | - | Initial Google Maps JavaScript API key. |
+| `defaultBrandTheme` | `string` | - | Initial brand color theme id. |
+| `primaryColor` | `string` | - | Primary brand color override. |
+| `useCustomTokens` | `boolean` | `false` | Skips runtime brand token injection when the host app owns tokens. |
+| `disableDarkMode` | `boolean` | `false` | Forces light mode and disables dark-mode toggling from the theme provider. |
 
 ---
 
 ## Included Services
 
-- **ThemeProvider**: Manages light/dark mode with browser-safe storage.
-- **BrandColorsProvider**: Applies runtime brand colors when custom tokens are not used.
-- **LanguageProvider**: Stores the selected UI language.
-- **ApiKeyProvider**: Stores AI and Google Maps API keys.
-- **AssistenteProvider**: Provides shared assistant conversation state.
-- **LayoutContext**: Manages `sidebarWidth` and expanded states globally.
-- **TooltipProvider**: Enables Radix-based tooltips with consistent delays.
-- **GoogleMapsLoader**: Manages the lifecycle of the Google Maps JS SDK.
-- **Sonner Toaster**: Injects a high-performance toast notification system.
+- **ThemeProvider**: Manages light/dark mode with browser-safe storage.
+- **BrandColorsProvider**: Applies runtime brand colors when custom tokens are not used.
+- **LanguageProvider**: Stores the selected UI language.
+- **ApiKeyProvider**: Stores AI and Google Maps API keys.
+- **AssistenteProvider**: Provides shared assistant conversation state.
+- **LayoutContext**: Manages `sidebarWidth` and expanded states globally.
+- **TooltipProvider**: Enables Radix-based tooltips with consistent delays.
+- **GoogleMapsLoader**: Manages the lifecycle of the Google Maps JS SDK.
+- **Sonner Toaster**: Injects a high-performance toast notification system.
 
 ---
 
 ## AI Rules
 
-> [!IMPORTANT]
-> - **CSS Requirement**: Always remind users to import `xertica-ui/style.css` alongside the provider to avoid unstyled content.
-> - **Independence Contract**: UI, layout, media, and assistant components should render without this provider when possible. Use the provider at the app root for synchronized state and shared services.
+> [!IMPORTANT]
+> - **CSS Requirement**: Always remind users to import `xertica-ui/style.css` alongside the provider to avoid unstyled content.
+> - **Independence Contract**: UI, layout, media, and assistant components should render without this provider when possible. Use the provider at the app root for synchronized state and shared services.

package/docs/decision-tree.md

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

package/docs/getting-started.md

@@ -121,7 +121,7 @@ The design system is token-driven. All colors, radii, and shadows are controlled
 | `border-border` | Standard borders |
 | `border-input` | Form field borders |
 
-**Always use semantic tokens.** Never use raw hex values or generic Tailwind colors (`bg-blue-500`, `text-gray-700`).
+**Always use semantic tokens for semantic/status contexts.** Never use raw hex values (`#3b82f6`, `rgb(...)`) in any context. For error, warning, success, and status states, always use semantic tokens (`bg-destructive`, `bg-success`, `bg-warning`, `text-muted-foreground`). For layout, spacing, and general non-semantic UI, standard Tailwind color utilities are acceptable.
 
 ### Dark Mode