{/* Header */}

AI Assistant

{/* Messages */}

{mensagens.map(msg => (

{msg.content}

))}

{/* Input */}

setMensagem(e.target.value)} onKeyDown={e => e.key === 'Enter' && handleEnviarMensagem()} placeholder="Type a message..." className="flex-1 border rounded px-3 py-2 text-sm" />

); } ``` --- ## AI Rules - Use `demoMode={true}` for development without API key - Use `responseGenerator` for custom AI integration - In fullPage mode, welcome message shows "Olá, {userName}" (not "Assistente Xertica") - Tab switching (chat/historico/favoritos) hides navigation tabs in fullPage mode - Feature flags are independent and can be combined freely; all default to `true` - When `showHistory` or `showFavorites` is `false`, both the collapsed icon and expanded tab are removed - When both `showHistory` and `showFavorites` are `false`, the entire tab navigation bar is hidden (including the Chat tab) — there is no point showing a single tab with no alternatives - ALWAYS use `useAssistant()` when building a custom assistant UI — never re-implement message state or response generation manually - The `messagesEndRef` from the hook MUST be attached to a div at the bottom of the message list for auto-scroll to work - `handleEnviarMensagem()` handles both demo mode responses and `responseGenerator` — do not call `responseGenerator` directly - `handleEnviarMensagem` accepts `arg?: string | ActionType` — pass a string to send a specific message, pass an `ActionType` (`'document'`, `'podcast'`, `'search'`) to trigger an action, or pass nothing to send the current `mensagem` input value - `initialMessages` is hydrated **once** (one-shot) — passing a new array after mount does not reset the conversation. To reset, call `setMensagens([])` directly - Auto-scroll is conditional: `messagesEndRef.scrollIntoView` is only called when the user is within 120px of the bottom of the chat container — preserves scroll position during history review - **`suggestions`, `richSuggestions`, and `feedbackOptions` should come from `useAssistantConfig()` (React Query)** — never hardcode them in the page component. Use the fallback factory functions from `features/assistant/data/mock.ts` while the query loads ## Dynamic Configuration with React Query In projects using the `features/` architecture, assistant configuration (suggestions, feedback options) is fetched via `useAssistantConfig()`: ```tsx import { useAssistantConfig, getMockRichSuggestions, getMockFeedbackOptions } from '../features/assistant'; function MyPage() { const { data: assistantConfig } = useAssistantConfig(); return ( ); } ``` To connect to a real configuration API, replace `fetchAssistantConfig` in `features/assistant/data/mock.ts`: ```ts // features/assistant/data/mock.ts export async function fetchAssistantConfig(): Promise { // Replace with real endpoint: return fetch('/api/assistant/config').then(r => r.json()); } ``` --- END COMPONENT: ASSISTANT --- --- START COMPONENT: AUDIO-PLAYER --- # AudioPlayer A unified, premium media player designed for both quick audio previews and long-form podcasts. It supports embedded (Card) and global (Bar) layouts, featuring fluid transitions and intelligent responsiveness. --- ## Import ```tsx import { AudioPlayer } from 'xertica-ui/media'; ``` --- ## Basic Usage ### Embedded with Auto-Float (Card) Ideal for in-page content. The player automatically "floats" if the user scrolls away while listening. ```tsx ``` ### Global Bar (Bar) Ideal for continuous playback across the entire application. ```tsx setOpen(false)} /> ``` --- ## Props | Prop | Type | Default | Description | | ----------------- | ------------------------ | ----------- | ------------------------------------------------------------- | | `variant` | `'card' \| 'bar'` | `'card'` | Determines if the player is an embedded card or a fixed bar. | | `colorVariant` | `'default' \| 'primary'` | `'default'` | Visual style (`primary` is ideal for brand-focused podcasts). | | `isOpen` | `boolean` | `true` | (Bar only) Whether the player bar is open or closed. | | `enableAutoFloat` | `boolean` | `true` | (Card only) Whether to float when scrolling out of viewport. | | `title` | `string` | — | Track title. | | `artist` | `string` | — | Author or subtitle. | | `src` | `string` | — | Audio file URL. | | `duration` | `number` | — | Total duration in seconds. | --- ## Features and Behaviors ### Dynamic Responsiveness The `AudioPlayer` doesn't just hide elements—it **reallocates** them. Depending on available screen space: - **Large Screens (Desktop)**: All controls (volume, speed, download) are visible on the bar. - **Medium/Small Screens**: Controls like volume and speed automatically move to the secondary options menu (`...`) to prevent visual clutter. ### Playback Speed Supports speed adjustments: `0.5x`, `1x`, `1.5x`, and `2x`. The control adapts dynamically to the screen width. ### Layout Integration The `bar` variant automatically detects the state of the **Sidebar** and **AI Assistant** via `LayoutContext`, adjusting its margins to ensure it never covers vital system elements. --- ## Headless Hook: `useAudioPlayer` For advanced use cases where you need a fully custom player UI, use the `useAudioPlayer` headless hook directly: ```tsx import { useAudioPlayer } from 'xertica-ui/hooks'; function MyCustomPlayer({ src }: { src: string }) { const { audioRef, containerRef, isPlaying, togglePlay, currentTime, duration, formatTime, onPlay, onPause, onEnded, onTimeUpdate, onLoadedMetadata, } = useAudioPlayer({ src, variant: 'card' }); return (

); } ``` See [`hooks.md`](./hooks.md#useaudioplayer) for the complete `useAudioPlayer` API reference. --- ## Implementation Notes (v2.1.9+) ### Latest-Ref Pattern in mode-switch effect The hook uses the **latest-ref pattern** to avoid stale closure problems when switching between floating and embedded modes: ```ts const currentTimeRef = useRef(currentTime); const isPlayingRef = useRef(isPlaying); useEffect(() => { currentTimeRef.current = currentTime; }, [currentTime]); useEffect(() => { isPlayingRef.current = isPlaying; }, [isPlaying]); // mode-switch effect — reads from refs, not from state closure useEffect(() => { const audio = audioRef.current; if (audio) { if (Math.abs(audio.currentTime - currentTimeRef.current) > 0.5) audio.currentTime = currentTimeRef.current; if (isPlayingRef.current) audio.play().catch(err => console.log('Playback interrupted:', err)); } }, [isFloating, variant]); ``` This eliminates the need for the `eslint-disable-next-line react-hooks/exhaustive-deps` comment that previously suppressed the stale-closure warning. When building a custom player with `useAudioPlayer`, you do not need to replicate this pattern — it is handled internally. --- ## AI Best Practices > [!IMPORTANT] > > - **Branding Variants**: Use `colorVariant="primary"` for high-relevance or branded content (like Podcasts). Use the default style for utility audios. > - **Manual Floating**: In Card mode, users can click the "Maximize" icon to manually force floating mode. > - **Accessibility**: All buttons have appropriate ARIA labels. Always provide a descriptive `title` for each audio track. > - **Custom UI**: Use `useAudioPlayer` from `xertica-ui/hooks` only when you need a fully custom player interface. For standard playback, always use `` directly. --- END COMPONENT: AUDIO-PLAYER --- --- START COMPONENT: AVATAR --- # Avatar ## Overview Displays a user's identity visually — either as a profile photo or as an initials-based fallback. Used in headers, sidebars, comment threads, and table rows to represent people. --- ## When to Use - User profile representation in headers and sidebars - Author attribution in activity feeds and comment lists - List items that represent people or organizations --- ## Anatomy ``` ← Actual photo ← Shown when image fails or hasn't loaded ``` --- ## Props ### Avatar | Prop | Type | Default | Required | Description | | ----------- | -------- | ------- | -------- | ------------------------------------------------------------ | | `className` | `string` | — | No | Size and shape overrides (default: `h-10 w-10 rounded-full`) | ### AvatarImage | Prop | Type | Required | Description | | ----- | -------- | -------- | --------------------------- | | `src` | `string` | No | Image URL | | `alt` | `string` | No | Accessible alternative text | ### AvatarFallback | Prop | Type | Description | | ----------- | ----------- | -------------------------------------- | | `className` | `string` | Style the fallback background and text | | `children` | `ReactNode` | Initials string or fallback icon | | `delayMs` | `number` | Delay before fallback appears (ms) | --- ## Examples ### With Image + Fallback Initials ```tsx import { Avatar, AvatarImage, AvatarFallback } from 'xertica-ui/ui'; JD ; ``` ### Small (in table rows) ```tsx {user.name.charAt(0).toUpperCase()} ``` ### With Icon Fallback ```tsx import { User } from 'lucide-react'; ; ``` --- ## AI Rules - Always include `` — never render `` alone. If the image fails to load, the component will be blank without a fallback. - The fallback should be initials (`user.name.charAt(0)`) or a `lucide-react` user icon — never an external image. - Size the Avatar using `className="h-8 w-8"` (small) or `className="h-10 w-10"` (default). Do not use Tailwind `w-` and `h-` classes that don't correspond to standard rem multiples. --- ## Related Components - [`Header`](./header.md) — Avatar is used in the user profile dropdown - [`Sidebar`](./sidebar.md) — Avatar in the sidebar footer --- END COMPONENT: AVATAR --- --- START COMPONENT: BADGE --- # Badge ## Overview A compact, inline label used to communicate status, category, or count. Badges are always non-interactive by default — they display information, not trigger actions. --- ## When to Use - Status indicators: "Active", "Inactive", "Pending", "Error" - Category tags in lists and tables - Count indicators (notifications, pending items) - Feature flags or role labels ## When NOT to Use - For clickable filters — use `Toggle` or `Button` instead. - For destructive inline actions — use a `Button variant="destructive"`. --- ## Variants | Variant | Usage | | ------------- | ----------------------------------------- | | `default` | Filled primary color — main labels | | `secondary` | Muted fill — secondary or neutral labels | | `outline` | Bordered, transparent — subtle status | | `destructive` | Red — error or danger status | | `success` | Soft green — positive or completed status | | `info` | Soft blue — informational status | | `warning` | Soft amber — caution or pending status | --- ## Props | Prop | Type | Default | Required | Description | | ----------- | -------------------------------------------------------------------------------------------- | ----------- | -------- | ---------------------------- | | `variant` | `'default' \| 'secondary' \| 'outline' \| 'destructive' \| 'success' \| 'info' \| 'warning'` | `'default'` | No | Visual style | | `asChild` | `boolean` | `false` | No | Renders as the child element | | `className` | `string` | — | No | Additional CSS classes | --- ## Examples ```tsx import { Badge } from 'xertica-ui/ui'; Active Draft Pending Error Completed Info Caution ``` ### In Table Cells ```tsx Active ``` --- ## AI Rules - Status labels in tables and lists must ALWAYS use `` — never plain text or colored ``. - Use semantic variants to convey meaning: `success` for completed/positive, `info` for informational, `warning` for caution, `destructive` for errors. - Never invent a custom variant by styling a badge with raw colors. Use only the 7 documented variants. - When you need a custom color label (e.g., brand-specific), apply `className` with semantic token classes: `className="bg-primary/10 text-primary border-primary/20"`. --- ## Related Components - [`Button`](./button.md) — When the label needs to be clickable - [`NotificationBadge`](./notification-badge.md) — For overlay dot/count indicators on icons - [`Table`](./table.md) — Common context for Badge usage --- END COMPONENT: BADGE --- --- START COMPONENT: BRANDING --- # Branding — Xertica UI The branding system in Xertica UI provides tools for applying, customizing, and switching the visual identity of an application — including color themes, logos, language, and dark/light mode. --- ## Brand Components Overview | Component | Import | Purpose | | ------------------ | ------------------ | ------------------------------------------------------- | | `XerticaProvider` | `xertica-ui/brand` | Root provider for all brand, theme, and layout contexts | | `ThemeToggle` | `xertica-ui/brand` | Self-contained dark/light mode switcher | | `LanguageSelector` | `xertica-ui/brand` | Standalone language dropdown (pt-BR / en / es) | | `XerticaLogo` | `xertica-ui/brand` | Full horizontal Xertica logotype SVG | | `XerticaXLogo` | `xertica-ui/brand` | Compact X-mark logo variant | | `XerticaOrbe` | `xertica-ui/brand` | Animated orb brand mark | --- ## Color Theme System ### How It Works Xertica UI uses CSS custom properties (design tokens) for all colors. The theme is applied by injecting token values at `:root` and `.dark`. Tailwind v4 maps these tokens via `@theme inline`. ``` tokens.css → :root { --primary: ...; --background: ...; } → .dark { --primary: ...; --background: ...; } → @theme inline { --color-primary: var(--primary); } → Tailwind utilities: bg-primary, text-foreground, etc. ``` ### Available Theme Presets The CLI (`npx xertica-ui@latest init` or `npx xertica-ui@latest update-theme`) offers multiple color presets. Each preset defines a complete set of tokens for both light and dark modes. ### Customizing Colors Programmatically Use `useBrandColors` to read and modify brand colors at runtime: ```tsx import { useBrandColors } from 'xertica-ui/hooks'; function BrandCustomizer() { const { colors, setBrandColor } = useBrandColors(); return (

Primary Color setBrandColor('primary', e.target.value)} />

); } ``` Changes are applied immediately as CSS variables on `:root`. --- ## Dark / Light Mode ### `ThemeToggle` A self-contained button that toggles between light and dark mode. Does not require any context provider — it reads and writes `document.documentElement.classList` directly. ```tsx import { ThemeToggle } from 'xertica-ui/brand'; // Place in Header actions or Sidebar footer ; ``` **Props:** | Prop | Type | Default | Description | | ----------- | ---------------------- | ------- | ---------------------- | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size | | `className` | `string` | — | Additional CSS classes | ### `useTheme` Hook For programmatic theme control: ```tsx import { useTheme } from 'xertica-ui/hooks'; function ThemeController() { const { theme, setTheme, toggleTheme } = useTheme(); return ; } ``` > **Note**: `useTheme` requires `` in the tree. `ThemeToggle` works without any provider. --- ## Language Selector ### `LanguageSelector` A standalone dropdown for switching the UI language preference. ```tsx import { LanguageSelector } from 'xertica-ui/brand'; // Typically placed in PageHeader or Sidebar footer ; ``` The selected language is persisted in `localStorage` under `xertica_language`. Access the current value via `useLanguage()`: ```tsx import { useLanguage } from 'xertica-ui/hooks'; function MyComponent() { const { language, availableLanguages, isMonolingual } = useLanguage(); // language is `string` (e.g. 'pt-BR', 'en', 'fr') — the set is runtime-configurable } ``` The set of available languages is configured at runtime via the `availableLanguages` prop on `` (defaults to `pt-BR`, `en`, `es`). See [`docs/i18n.md`](../i18n.md) for the full extension API. When only one language is configured, the `LanguageSelector` auto-hides. --- ## Logo Components ### `XerticaLogo` Full horizontal logotype. Use in the Sidebar header or login page. ```tsx import { XerticaLogo } from 'xertica-ui/brand'; ; ``` ### `XerticaXLogo` Compact X-mark variant. Use when space is limited (collapsed sidebar, favicon-like contexts). ```tsx import { XerticaXLogo } from 'xertica-ui/brand'; ; ``` ### `XerticaOrbe` Animated orb brand mark. Use as a decorative element or loading indicator. ```tsx import { XerticaOrbe } from 'xertica-ui/brand'; ; ``` --- ## `XerticaProvider` The root provider that initializes all brand, theme, layout, and service contexts. Must wrap the entire application once. ```tsx import { XerticaProvider } from 'xertica-ui/brand'; import 'xertica-ui/style.css'; ReactDOM.createRoot(document.getElementById('root')!).render( ); ``` `XerticaProvider` initializes: - `ThemeProvider` — dark/light mode - `LanguageProvider` — language preference - `BrandColorsProvider` — brand color tokens - `LayoutProvider` — sidebar and assistant state - `AssistenteProvider` — AI assistant context - `ApiKeyProvider` — API key management - `GoogleMapsLoaderProvider` — lazy Maps API loading - `TooltipProvider` — Radix tooltip context - `Toaster` — Sonner toast notifications **Props:** | Prop | Type | Default | Description | | --------------------- | ----------- | ------------ | ------------------------------------------- | | `children` | `ReactNode` | _(required)_ | Application content | | `googleMapsApiKey` | `string` | — | Google Maps API key (activates Maps loader) | | `initialApiKey` | `string` | — | Pre-set Xertica API key | | `initialGeminiApiKey` | `string` | — | Pre-set Gemini API key | --- ## CSS Token Structure The complete token set is defined in `tokens.css` (generated by the CLI). Key token groups: ```css :root { /* Colors */ --background: 0 0% 100%; --foreground: 222.2 84% 4.9%; --primary: 221.2 83.2% 53.3%; --primary-foreground: 210 40% 98%; --secondary: 210 40% 96.1%; --muted: 210 40% 96.1%; --muted-foreground: 215.4 16.3% 46.9%; --accent: 210 40% 96.1%; --destructive: 0 84.2% 60.2%; --border: 214.3 31.8% 91.4%; --input: 214.3 31.8% 91.4%; --ring: 221.2 83.2% 53.3%; --card: 0 0% 100%; --card-foreground: 222.2 84% 4.9%; /* Chart colors */ --chart-1: 221.2 83.2% 53.3%; --chart-2: 142.1 76.2% 36.3%; --chart-3: 47.9 95.8% 53.1%; --chart-4: 280.1 65.3% 60%; --chart-5: 24.6 95% 53.1%; /* Sidebar */ --sidebar: 222.2 84% 4.9%; --sidebar-foreground: 210 40% 98%; /* Shape */ --radius: 0.5rem; --radius-button: 0.375rem; } ``` --- ## AI Rules > [!IMPORTANT] > > - **`XerticaProvider` is required once**: Place it at the root of your application. Never nest multiple `XerticaProvider` instances. > - **Never use raw hex/rgb colors**: All colors must use semantic tokens (`bg-primary`, `text-destructive`, `border-border`). Raw values like `#3b82f6` or `rgb(59, 130, 246)` are forbidden. > - **`ThemeToggle` is self-contained**: It does not need `useTheme` or any context. Use it directly in any component without provider requirements. > - **Logo sizing via `className`**: Size logo components using Tailwind height/width classes (`h-8`, `w-8`). Do not use `width`/`height` HTML attributes. > - **Language is preference only**: `LanguageSelector` stores a preference. The library UI renders in Portuguese regardless. Implement your own i18n logic using the `language` value from `useLanguage()`. --- END COMPONENT: BRANDING --- --- START COMPONENT: BREADCRUMB --- # Breadcrumb ## Overview A hierarchical navigation trail showing the user's current position in the application's page structure. Rendered in the `Header` component via the `breadcrumbs` prop. Each item in the chain can optionally be a clickable link. --- ## When to Use - In the application header to show the current page's position in the hierarchy - In pages with deep navigation structures (Dashboard > Reports > Q4 2024) --- ## Anatomy ``` Home Current Page ``` --- ## Sub-Components | Component | Description | | --------------------- | ------------------------------------------------------ | | `Breadcrumb` | Root wrapper (renders `

`) | | `BreadcrumbList` | Ordered list of breadcrumb items | | `BreadcrumbItem` | Individual breadcrumb item | | `BreadcrumbLink` | Clickable link item | | `BreadcrumbPage` | Non-linked current page item | | `BreadcrumbSeparator` | Visual separator between items (default: `/`) | | `BreadcrumbEllipsis` | Collapsed items indicator for long chains | --- ## Examples ### Via Header (Recommended) ```tsx

}, { label: 'Users', href: '/users' }, { label: 'Ariel Santos' }, // No href = current page ]} /> ``` ### Manual Composition ```tsx import { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbSeparator, BreadcrumbPage, } from 'xertica-ui/ui'; Home Settings Profile ; ``` --- ## AI Rules - The **last item** in the breadcrumb is always the current page and must use `` (not ``). - Prefer using the `breadcrumbs` prop on `

` — it automatically handles all the composition for you. - Always add a `` between every two items. --- ## Related Components - [`Header`](./header.md) — Primary context for Breadcrumb usage - [`NavigationMenu`](./navigation-menu.md) — For horizontal top-level navigation --- END COMPONENT: BREADCRUMB --- --- START COMPONENT: BUTTON --- # Button ## Overview The primary interaction trigger. Use `Button` for any user-initiated action: form submission, navigation triggers, dialog openers, and destructive confirmations. It supports multiple visual variants, sizes, icon-only mode, and the `asChild` pattern for composing with router links. --- ## When to Use - Submitting forms (primary action) - Opening dialogs, drawers, or sheets - Triggering secondary or ghost actions (cancel, go back) - Icon-only controls in toolbars and headers ## When NOT to Use - **URL navigation without action intent** — use ` ``` ### With Icon ```tsx import { Plus, Trash2 } from 'lucide-react'; ``` ### Icon Only ```tsx import { Settings } from 'lucide-react'; ; ``` ### Composed with Router Link ```tsx import { Link } from 'react-router-dom'; ; ``` ### Action Pair ```tsx

``` --- ## Accessibility - Has visible focus ring (`ring-ring`) via keyboard navigation. - Use `aria-label` for icon-only buttons to provide screen reader context. - When `disabled`, the button is non-interactive and visually muted. --- ## AI Rules - **Never use ` ; ``` > **Note:** The `size` prop was intentionally kept off the `Calendar` component. Size and border-radius are concerns of the trigger element, not the calendar grid. ### Disable Past Dates ```tsx ``` ### Date Range ```tsx const [range, setRange] = useState<{ from: Date; to?: Date }>(); ; ``` --- ## AI Rules - Always use Calendar inside a `` with ``. - Always pass `initialFocus` when inside a Popover — essential for keyboard/accessibility UX. - Use `date-fns` for date formatting (`format(date, 'PPP')`) — it is a standard peer dependency. - For form integration, use the `selected`/`onSelect` pattern, not `{...field}`. - To control trigger button size and border-radius, apply classes directly on the ` } maxItems={5} />; ``` **Props:** | Prop | Type | Default | Description | | ---------- | ---------------- | --------------------- | --------------------------- | | `title` | `string` | `'Atividade Recente'` | Card title | | `items` | `ActivityItem[]` | — | Feed entries | | `action` | `ReactNode` | — | Right-aligned header action | | `maxItems` | `number` | `5` | Maximum visible items | **`ActivityItem` shape:** ```ts { id: string user: { name: string; initials: string; avatar?: string } action: string // verb: "criou", "atualizou", etc. target: string // object of the action time: string // relative time string type?: 'create' | 'update' | 'delete' | 'comment' | 'deploy' } ``` --- ### ProfileCard User or team member card with avatar, status badge, stat row, and primary/secondary actions. ```tsx import { ProfileCard } from 'xertica-ui'; ; ``` **Props:** | Prop | Type | Default | Description | | ----------------- | ---------------------------------------------- | ------- | -------------------------------- | | `name` | `string` | — | Full name | | `role` | `string` | — | Job title | | `department` | `string` | — | Department or team | | `initials` | `string` | — | Avatar fallback (2 chars) | | `avatar` | `string` | — | Avatar image URL | | `status` | `'online' \| 'offline' \| 'away' \| 'busy'` | — | Presence badge | | `stats` | `{ label: string; value: string \| number }[]` | — | Up to 3 stats in the divider row | | `primaryAction` | `{ label: string; onClick?: () => void }` | — | Primary button | | `secondaryAction` | `{ label: string; onClick?: () => void }` | — | Secondary (outline) button | --- ### ProjectCard Project status widget with title, description, status badge, progress bar, member avatar stack, and due date. ```tsx import { ProjectCard } from 'xertica-ui'; ; ``` **Props:** | Prop | Type | Default | Description | | ------------- | ----------------- | ------- | ----------------------------------------- | | `title` | `string` | — | Project name | | `description` | `string` | — | Short description | | `status` | `ProjectStatus` | — | Controls badge color and progress color | | `progress` | `number` | — | 0–100 completion percentage | | `dueDate` | `string` | — | Due date label string | | `members` | `ProjectMember[]` | `[]` | Avatar stack | | `maxMembers` | `number` | `4` | Max visible avatars before overflow count | | `action` | `ReactNode` | — | Extra action appended to the status badge | **`ProjectStatus` values:** `active` · `review` · `done` · `paused` · `at-risk` --- ### QuickActionCard Action tile with icon in colored box, title, description, optional badge, and a full-width action button. ```tsx import { QuickActionCard } from 'xertica-ui'; import { FileText } from 'lucide-react'; } actionLabel="Criar Relatório" badge="Pro" badgeVariant="warning" onAction={() => openReportModal()} />; ``` **Props:** | Prop | Type | Default | Description | | --------------- | --------------- | ------------- | ------------------------ | | `title` | `string` | — | Tile title | | `description` | `string` | — | Supporting text | | `icon` | `ReactNode` | — | Icon in the colored box | | `badge` | `string` | — | Optional badge | | `badgeVariant` | `BadgeVariant` | `'secondary'` | Badge color variant | | `actionLabel` | `string` | — | Button label | | `actionVariant` | `ButtonVariant` | `'default'` | Button variant | | `onAction` | `() => void` | — | Button click handler | | `disabled` | `boolean` | `false` | Disables the entire card | --- ### NotificationCard Notification list with unread indicator dots, type badges, timestamps, and bulk mark-as-read action. ```tsx import { NotificationCard } from 'xertica-ui'; markAllRead()} onViewAll={() => navigate('/notifications')} maxItems={4} />; ``` **Props:** | Prop | Type | Default | Description | | --------------- | -------------------- | ---------------- | ----------------------------------------------- | | `title` | `string` | `'Notificações'` | Card title | | `items` | `NotificationItem[]` | — | Notification entries | | `unreadCount` | `number` | auto-counted | Override unread count badge | | `onMarkAllRead` | `() => void` | — | Shows "Marcar todas como lidas" button when set | | `onViewAll` | `() => void` | — | Shows "Ver todas" footer button when set | | `maxItems` | `number` | `4` | Maximum visible items | **`NotificationItem` shape:** ```ts { id: string title: string message: string time: string read?: boolean type?: 'info' | 'warning' | 'success' | 'error' | 'default' user?: { name: string; initials: string; avatar?: string } } ``` --- ## Dashboard Layout Example ```tsx import { ActivityCard, ChartCard, NotificationCard, ProfileCard, ProjectCard, QuickActionCard, } from 'xertica-ui'; import { DashboardLineChart } from 'xertica-ui/ui'; import { Briefcase, Users, BarChart2 } from 'lucide-react';

{/* Quick actions row */}

} actionLabel="Criar" /> } actionLabel="Convidar" actionVariant="outline" /> } actionLabel="Abrir" badge="Novo" badgeVariant="success" />

{/* Chart + Notifications */}

{}} />

{/* Activity + Profile + Project */}

; ``` --- ## Loading States — Skeleton Components Every card pattern ships with a matching `*Skeleton` companion that mirrors its layout with pulsing placeholders. Use them while data is loading to avoid layout shift and provide visual feedback. | Card | Skeleton companion | Configurable props | | ------------------ | -------------------------- | ----------------------------------- | | `ActivityCard` | `ActivityCardSkeleton` | `rows` (default `5`) | | `ProfileCard` | `ProfileCardSkeleton` | `showStats`, `showActions` | | `ProjectCard` | `ProjectCardSkeleton` | `memberCount` (default `3`) | | `NotificationCard` | `NotificationCardSkeleton` | `rows` (default `4`), `showViewAll` | | `QuickActionCard` | `QuickActionCardSkeleton` | — | | `FeatureCard` | `FeatureCardSkeleton` | `showAction` | > A matching `StatsCardSkeleton` is also available from `xertica-ui` (lives in `ui/stats-card/`, with props `showIcon` and `showTrend`). ### Usage pattern ```tsx import { useQuery } from '@tanstack/react-query'; import { ActivityCard, ActivityCardSkeleton } from 'xertica-ui'; function ActivityFeed() { const { data: items, isLoading } = useActivityItems(); if (isLoading) return ; return ; } ``` For grids, render one skeleton per expected card: ```tsx { isLoading ? ( <> ) : ( data.map(item => ) ); } ``` ### Examples ```tsx // ActivityCard with 4 row placeholders // ProfileCard without stats grid and without action buttons // ProjectCard with 5 member-avatar placeholders // NotificationCard with footer placeholder // FeatureCard without footer action button ``` > All skeletons use the `Skeleton` primitive from `ui/skeleton`, inheriting the `bg-accent animate-pulse` styling. They render plain `

` placeholders — no real Card/Header/Footer subcomponents — so they're cheap to render at scale. --- ## AI Rules - Import block components from `xertica-ui` — they are included in the root barrel. - Pass all data as props — never embed fetch calls inside block components. - Keep `maxItems` at a sensible limit (4–6) to avoid overflow in fixed-height containers. - For chart panels, use `ChartCard` from `xertica-ui/ui` (not a block component) with any dashboard-ready chart as `children`. - `FeatureCard` badge wraps to a new line when title + badge don't fit — this is intentional; do not constrain the container width to force inline layout. - **Always pair each card with its matching `*Skeleton` for loading states** — do not render a spinner or empty container while data fetches. The skeleton variants mirror the final layout closely, preventing layout shift when data arrives. - **Skeleton row counts should match the expected data count when possible** — pass `rows={maxItems}` to `ActivityCardSkeleton`/`NotificationCardSkeleton` so the placeholder height matches the loaded state. --- ## Related - [`Card`](./card.md) — Primitive used internally by all block components - [`StatsCard`](./stats-card.md) — KPI card (lives in `ui/`, not `blocks/`) — also has `StatsCardSkeleton` - [`Skeleton`](./skeleton.md) — Low-level pulsing placeholder primitive used by every `*Skeleton` here - [`Chart`](./chart.md) — `ChartCard` and dashboard-ready chart wrappers - [Dashboard Pattern](../patterns/dashboard.md) --- END COMPONENT: CARD-PATTERNS --- --- START COMPONENT: 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 `

` 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 ``` ← optional right-aligned slot ``` 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 `

` | | `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'; Detalhes do Projeto Gerencie as configurações do seu workspace.

Internal content goes here.

; ``` ### 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'; Notificações Gerencie suas preferências de alerta. {/* content */} ; ``` ### Stats / KPI Card ```tsx import { Card, CardHeader, CardTitle, CardContent, CardAction } from 'xertica-ui/ui'; import { DollarSign } from 'lucide-react'; Receita Total

R$ 45.231

+20.1% vs mês anterior

; ``` ### Form Container ```tsx Editar Perfil ``` ### Settings List (divider pattern) ```tsx import { Card, CardHeader, CardTitle, CardContent, CardFooter } from 'xertica-ui/ui'; import { Badge, Separator, Button } from 'xertica-ui/ui'; Preferências da Conta {items.map((item, i, arr) => (

{item.label}

{item.desc}

{item.active ? 'Ativo' : 'Inativo'}

{i < arr.length - 1 && }

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

Ana Souza

Frontend Engineer

Online

; ``` --- ## AI Rules - **Never** create surfaces with raw Tailwind: `

` — use `` 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 `

`. 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 --- END COMPONENT: CARD --- --- START COMPONENT: CAROUSEL --- # Carousel ## Overview A horizontal content slider that lets users navigate through a set of panels or cards one at a time. Built on `embla-carousel-react`. Provides Previous/Next navigation buttons and optional indicator dots. --- ## When to Use - Image galleries or feature showcases - Onboarding step walkthroughs - Product or testimonial carousels - Mobile-friendly horizontal card stacks ## When NOT to Use - For multi-column grids that can all be visible at once — use CSS Grid instead. - Long lists of data — use a `` or paginated list instead. --- ## Anatomy ``` { /* Card or content */ } { /* Card or content */ } ``` --- ## Examples ### Image / Feature Carousel ```tsx import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, Card, CardContent, } from 'xertica-ui/ui'; {Array.from({ length: 5 }).map((_, i) => ( {i + 1} ))} ; ``` ### Partial-Visible Cards ```tsx {items.map(item => ( {item.name} ))} ``` --- ## AI Rules - Set visible card count with `className="md:basis-1/2 lg:basis-1/3"` on `` — not by limiting the array. - `` and `` are positioned absolutely — ensure the parent has `relative` positioning (the `` component handles this). - Never wrap `` in overflow-hidden containers that might clip the navigation buttons. --- ## Related Components - [`Card`](./card.md) — Most common Carousel item content --- END COMPONENT: CAROUSEL --- --- START COMPONENT: CHART --- # Chart ## Overview Xertica UI provides a `ChartContainer` wrapper and related components built on top of **Recharts** for theme-aware, token-driven chart rendering. The chart system uses a `ChartConfig` object to define series labels and colors via CSS variables, ensuring full dark-mode support without hard-coded hex values. The library ships **11 dashboard-ready chart wrappers** that handle loading, empty, and error states automatically, so feature layers only need to pass `data`, `isLoading`, `error`, and `onRetry`. --- ## Exports | Export | Description | | ---------------------------- | ------------------------------------------------------------------------------- | | `ChartContainer` | Root container that injects CSS color variables and wraps `ResponsiveContainer` | | `ChartTooltip` | Re-exported `recharts` `Tooltip` component | | `ChartTooltipContent` | Styled tooltip content using the design system | | `ChartLegend` | Re-exported `recharts` `Legend` component | | `ChartLegendContent` | Styled legend content using the design system | | `ChartStyle` | Internal style injector (used by `ChartContainer`, not used directly) | | `ChartCard` | Card-based shell for dashboard chart panels | | `DashboardBarChart` | Ready-to-use grouped or stacked bar chart | | `DashboardLineChart` | Ready-to-use multi-series line chart | | `HorizontalBarChart` | Ranking/comparison bar chart with horizontal layout | | `InteractiveTimeSeriesChart` | Area time-series chart with metric tabs and period select | | `ComboMetricChart` | Composed bar, line, and area chart for mixed metrics | | `DonutBreakdownChart` | Donut/pie breakdown chart with interactive segment focus | | `SparklineChart` | Compact inline area/line chart for KPI cards | | `RadarMetricChart` | Multi-dimensional radar/spider chart | | `PieMetricChart` | Proportional pie chart with optional donut, labels, and exploded slice | | `RadialBarMetricChart` | Circular progress rings (radial bar chart) | | `GaugeChart` | Semicircle gauge with needle, thresholds, and color zones | | `ChartConfig` | TypeScript type for chart configuration | | `GaugeChartThreshold` | TypeScript type for gauge color zone thresholds | --- ## Required Dependencies ```bash npm install recharts ``` --- ## How It Works 1. Define a `ChartConfig` mapping each data key to a label and color. 2. Wrap your Recharts chart in ``. 3. Reference colors in chart elements using `fill="var(--color-yourKey)"`. 4. The container automatically injects CSS variables for light and dark themes. Dashboard-ready wrappers (`DashboardBarChart`, `RadarMetricChart`, etc.) build the config internally — you only need to pass `data` and `series`/`nameKey`/`valueKey`. --- ## ChartConfig Type ```typescript type ChartConfig = { [key: string]: { label?: string; icon?: React.ComponentType; color?: string; // CSS color or hsl() value theme?: { light: string; dark: string }; // Per-theme colors }; }; ``` --- ## Color Tokens Chart colors use `--chart-1` through `--chart-8` CSS tokens. These are theme-aware and automatically switch between light and dark mode. ```tsx // In ChartConfig { revenue: { label: 'Revenue', color: 'var(--chart-1)' } } // In dashboard-ready wrappers — pass as array or per-key map colors={['var(--chart-1)', 'var(--chart-2)']} colors={{ revenue: 'var(--chart-1)', expenses: 'var(--chart-5)' }} ``` --- ## Examples ### Bar Chart (low-level) ```tsx import { ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent, type ChartConfig, } from 'xertica-ui/ui'; import { BarChart, Bar, XAxis, YAxis, CartesianGrid } from 'recharts'; import { Card, CardHeader, CardTitle, CardContent } from 'xertica-ui/ui'; const chartConfig: ChartConfig = { revenue: { label: 'Revenue', color: 'var(--chart-1)' }, expenses: { label: 'Expenses', color: 'var(--chart-5)' }, }; const data = [ { month: 'Jan', revenue: 4000, expenses: 2400 }, { month: 'Feb', revenue: 3000, expenses: 1398 }, { month: 'Mar', revenue: 6000, expenses: 3200 }, ]; Revenue vs Expenses } /> } /> ; ``` ### Line Chart (low-level) ```tsx const chartConfig: ChartConfig = { users: { label: 'Active Users', color: 'var(--chart-1)' }, }; } /> ; ``` --- ### Dashboard-Ready Charts ```tsx import { ChartCard, DashboardBarChart, DashboardLineChart, HorizontalBarChart, InteractiveTimeSeriesChart, ComboMetricChart, DonutBreakdownChart, type ChartConfig, } from 'xertica-ui/ui'; const config: ChartConfig = { revenue: { label: 'Revenue', color: 'var(--chart-1)' }, pipeline: { label: 'Pipeline', color: 'var(--chart-4)' }, conversion: { label: 'Conversion', color: 'var(--chart-2)' }, }; const data = [ { date: 'Apr 01', revenue: 4200, pipeline: 2600, conversion: 32 }, { date: 'Apr 08', revenue: 5200, pipeline: 3200, conversion: 38 }, ]; ``` --- ### Radar Chart Multi-dimensional comparison across categorical axes. Use a single series for a simple spider chart, or multiple series for side-by-side comparison. ```tsx import { RadarMetricChart, ChartCard } from 'xertica-ui/ui'; const data = [ { skill: 'Speed', frontend: 80, backend: 60 }, { skill: 'Quality', frontend: 90, backend: 85 }, { skill: 'Coverage', frontend: 70, backend: 95 }, { skill: 'Security', frontend: 65, backend: 88 }, { skill: 'Perf', frontend: 75, backend: 72 }, ]; // Single series — filled polygon // Multi-series comparison ``` **Props:** | Prop | Type | Default | Description | | ---------------- | ------------------------ | ------- | --------------------------------------------- | | `data` | `DashboardChartDatum[]` | — | Data array; each item is one axis point | | `labelKey` | `string` | — | Key used as the axis label | | `series` | `DashboardChartSeries[]` | — | Series to render (one `` per entry) | | `colors` | `DashboardChartColors` | auto | Override colors per key or as ordered array | | `filled` | `boolean` | `true` | Fill the radar polygon | | `fillOpacity` | `number` | `0.25` | Fill opacity when `filled` is true | | `showDots` | `boolean` | `false` | Show dots on each axis point | | `showGrid` | `boolean` | `true` | Show polar grid lines | | `showLegend` | `boolean` | auto | Show legend (auto-shown when multiple series) | | `valueFormatter` | `(v: number) => string` | — | Format axis tick and tooltip values | | + state props | — | — | `isLoading`, `error`, `onRetry`, etc. | --- ### Pie Chart Proportional slices. Supports donut mode (`innerRadius > 0`), percentage labels, and an exploded (offset) slice for emphasis. ```tsx import { PieMetricChart, ChartCard } from 'xertica-ui/ui'; const data = [ { segment: 'Enterprise', value: 52 }, { segment: 'Mid-market', value: 31 }, { segment: 'SMB', value: 17 }, ]; // Simple pie // Donut variant // Exploded slice (highlight index 0) ``` **Props:** | Prop | Type | Default | Description | | ---------------- | ----------------------- | ------- | ------------------------------------------------ | | `data` | `DashboardChartDatum[]` | — | Data array; each item is one slice | | `nameKey` | `string` | — | Key used as the slice name/label | | `valueKey` | `string` | — | Key used as the slice value | | `colors` | `DashboardChartColors` | auto | Override colors as ordered array or per-name map | | `outerRadius` | `number \| string` | `"80%"` | Outer radius of the pie | | `innerRadius` | `number \| string` | `0` | Inner radius — set > 0 for donut | | `showLabels` | `boolean` | `false` | Show percentage labels on slices | | `showLegend` | `boolean` | `true` | Show the legend | | `explodeIndex` | `number` | — | Index of the slice to offset outward | | `explodeOffset` | `number` | `12` | Offset distance in px for the exploded slice | | `valueFormatter` | `(v: number) => string` | — | Format tooltip values | | + state props | — | — | `isLoading`, `error`, `onRetry`, etc. | --- ### Radial Bar Chart Circular progress rings. Each data item renders as a concentric arc. Useful for showing multiple metrics as percentage completion. ```tsx import { RadialBarMetricChart, ChartCard } from 'xertica-ui/ui'; const data = [ { name: 'CPU', value: 72 }, { name: 'Memory', value: 58 }, { name: 'Storage', value: 41 }, { name: 'Network', value: 89 }, ]; // Full-circle rings (default) `${v}%`} /> // Semi-circle layout ``` **Props:** | Prop | Type | Default | Description | | ---------------- | ----------------------- | --------- | ------------------------------------------------ | | `data` | `DashboardChartDatum[]` | — | Data array; each item is one ring | | `dataKey` | `string` | `"value"` | Key used as the bar value | | `nameKey` | `string` | `"name"` | Key used as the bar label | | `colors` | `DashboardChartColors` | auto | Override colors as ordered array or per-name map | | `innerRadius` | `number \| string` | `"30%"` | Inner radius of the radial bar | | `outerRadius` | `number \| string` | `"100%"` | Outer radius of the radial bar | | `startAngle` | `number` | `90` | Start angle in degrees (90 = top) | | `endAngle` | `number` | `-270` | End angle in degrees (-270 = full circle) | | `showBackground` | `boolean` | `true` | Show background track behind each bar | | `showLegend` | `boolean` | `true` | Show the legend below the chart | | `valueFormatter` | `(v: number) => string` | — | Format tooltip and legend values | | + state props | — | — | `isLoading`, `error`, `onRetry`, etc. | --- ### Gauge Chart Semicircle gauge with a needle indicator and optional color zones (thresholds). Implemented as pure SVG — no Recharts dependency. ```tsx import { GaugeChart, ChartCard, type GaugeChartThreshold } from 'xertica-ui/ui'; // Simple percentage gauge

// With color thresholds const thresholds: GaugeChartThreshold[] = [ { value: 40, color: 'var(--chart-2)', label: 'Healthy' }, { value: 70, color: 'var(--chart-3)', label: 'Warning' }, { value: 100, color: 'var(--chart-5)', label: 'Critical' }, ];

// Custom range and formatter `${value.toLocaleString()} rps`} showNeedle={false} /> ``` **Props:** | Prop | Type | Default | Description | | ---------------- | -------------------------------------------- | ------- | -------------------------------------------------------------------------- | | `value` | `number` | — | Current value (must be within `[min, max]`) | | `min` | `number` | `0` | Minimum value | | `max` | `number` | `100` | Maximum value | | `thresholds` | `GaugeChartThreshold[]` | — | Color zones evaluated in order; first zone where `value >= current %` wins | | `label` | `React.ReactNode` | — | Label shown below the center value | | `valueFormatter` | `(value: number, percent: number) => string` | — | Format the center value text (default: shows `%`) | | `showNeedle` | `boolean` | `true` | Show the needle indicator | | `className` | `string` | — | Additional CSS classes | **`GaugeChartThreshold` type:** ```typescript interface GaugeChartThreshold { value: number; // Upper bound of this zone (0–100) color: string; // Color for this zone (use CSS var tokens) label?: string; // Optional label shown in the legend } ``` **Infrastructure dashboard example:** ```tsx const metrics = [ { label: 'CPU', value: 72 }, { label: 'Memory', value: 85 }, { label: 'Storage', value: 41 }, ]; const thresholds: GaugeChartThreshold[] = [ { value: 60, color: 'var(--chart-2)', label: 'OK' }, { value: 80, color: 'var(--chart-3)', label: 'Warning' }, { value: 100, color: 'var(--chart-5)', label: 'Critical' }, ];

{metrics.map(m => (

))}

; ``` --- ### Sparkline Chart Compact inline chart for KPI cards and metric summaries. Renders as a minimal area or line chart with no axes or labels. ```tsx import { SparklineChart } from 'xertica-ui/ui'; // Filled area sparkline (default) // Line-only sparkline ``` --- ### Empty and Connection States All dashboard-ready chart wrappers handle loading, empty data, and connection errors without forcing each feature to duplicate presentation logic. In an FSD architecture, keep fetching and error mapping in the feature/model layer, then pass the state into the UI component. ```tsx // State props work on all dashboard-ready wrappers: ``` State props (`isLoading`, `error`, `onRetry`, `retryLabel`, `emptyTitle`, `emptyDescription`, `errorTitle`, `errorDescription`, `loadingLabel`, `stateClassName`) are available on: `DashboardBarChart`, `DashboardLineChart`, `HorizontalBarChart`, `InteractiveTimeSeriesChart`, `ComboMetricChart`, `DonutBreakdownChart`, `RadarMetricChart`, `PieMetricChart`, and `RadialBarMetricChart`. > `GaugeChart` does not extend `ChartStateProps` — it is a pure display component with no async state. --- ### Stacked Bar Chart Pass `stacked` to `DashboardBarChart` to stack series on top of each other. When stacking, only the **topmost series** in the stack receives rounded top corners — intermediate and bottom bars have flat tops to avoid visual gaps between segments. ```tsx const config: ChartConfig = { receita: { label: 'Receita', color: 'var(--chart-1)' }, despesa: { label: 'Despesa', color: 'var(--chart-5)' }, }; ; ``` > The radius logic is automatic — the last `series` entry in each `stackId` group receives `radius={[4,4,0,0]}`; all others receive `radius={[0,0,0,0]}`. You do not need to configure this manually. > **v2.1.9**: The `topOfStack` computation was extracted from an inline IIFE in JSX into a `React.useMemo([stacked, chartSeries])` before the `return`. This is a performance improvement — the bar element array is no longer recalculated on every render when the chart re-renders for unrelated reasons. --- ### Bar Thickness Bar-based dashboard charts support `barSize="sm" | "md" | "lg" | "xl"` or a numeric pixel value. This controls the thickness of each rendered bar, not the chart container width. ```tsx ``` `barSize` is available on `DashboardBarChart`, `HorizontalBarChart`, and the bar series inside `ComboMetricChart`. --- ## AI Rules - **Always** use `` — never use `` directly. - **Never** use hard-coded hex colors on chart elements (`fill="#4F46E5"`). Always use `fill="var(--color-keyName)"` — this references the CSS variable injected by `ChartContainer`. - Define color via `color: 'var(--chart-1)'` in `ChartConfig`, or pass `colors={['var(--chart-1)', 'var(--chart-2)']}` to dashboard-ready chart wrappers. The `--chart-*` tokens are theme-aware. - `ChartContainer` already wraps `ResponsiveContainer width="100%" height="100%"` — do not add another one. - Set height on `ChartContainer` via `className="h-[300px]"` — this sizes the container, not the Recharts elements. - Import all base Recharts components (`BarChart`, `Bar`, `Line`, etc.) directly from `recharts` — they are not re-exported by `xertica-ui`. - For dashboard-ready charts, prefer `ChartCard` plus a dashboard-ready wrapper before hand-assembling Recharts primitives. - In FSD apps, keep data fetching in the feature/model layer and pass `data`, `isLoading`, `error`, and `onRetry` into chart wrappers. - Use `barSize` to control bar thickness. Do not use a chart wrapper prop to control graph width; layout width belongs to the parent grid/container. - When using `stacked`, order your `series` array so the visually topmost series is last — it will automatically receive the rounded top corners. - `RadarMetricChart`, `PieMetricChart`, and `RadialBarMetricChart` build their `ChartConfig` internally from the `series`/`nameKey` data — you do not need to pass a `config` prop. - When passing `stateClassName` to `RadarMetricChart`, `PieMetricChart`, or `RadialBarMetricChart`, it is included in the state object passed to `getChartState` — it does not need to be (and should not be) passed as a second `className` argument separately. - `GaugeChart` is a pure SVG component — it does not use `ChartContainer` or Recharts. Wrap it in a `div` with `flex justify-center` to control its width. - For `GaugeChart` thresholds, use `--chart-*` CSS tokens for colors so they remain theme-aware. Never use raw hex values. - `RadialBarMetricChart` renders its legend as HTML below the chart (not inside the SVG) — this is intentional to avoid Recharts polar chart legend positioning issues. --- ## Related Patterns - [Dashboard Pattern](../patterns/dashboard.md) - [Analytics Pattern](../patterns/analytics.md) --- END COMPONENT: CHART --- --- START COMPONENT: CHECKBOX --- # Checkbox ## Overview A binary toggle that lets users select or deselect a single option, or mark multiple independent options in a list. Built on Radix UI with accessible keyboard behavior and ARIA roles. --- ## When to Use - Multi-select option lists (permissions, feature flags, filter tags) - "Agree to terms" consent fields - Row selection in tables - Individual boolean settings ## When NOT to Use - Mutually exclusive choices (only one can be true) — use `` instead. - A single prominent on/off toggle — use `` instead. --- ## Props | Prop | Type | Default | Required | Description | | ----------------- | ---------------------------- | ------- | -------- | ------------------------------------------------- | | `id` | `string` | — | No | Associates with `` | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | No | Size variant controlling the checkbox dimensions. | | `checked` | `boolean` | — | No | Controlled checked state | | `defaultChecked` | `boolean` | `false` | No | Uncontrolled initial state | | `onCheckedChange` | `(checked: boolean) => void` | — | No | Change handler | | `disabled` | `boolean` | `false` | No | Disables interaction | | `className` | `string` | — | No | Additional CSS classes | --- ## Examples ### Standalone with Label ```tsx import { Checkbox, Label } from 'xertica-ui/ui';

I agree to the{' '} terms of service

; ``` ### Inside react-hook-form ```tsx ( Accept Terms )} /> ``` --- ## AI Rules - **Do not spread `{...field}`** on `` — use `checked={field.value}` and `onCheckedChange={field.onChange}` explicitly. - **Sizing** — Matches the standard form sizing scale (`sm`, `md`, `lg`). Ensure the size matches the surrounding inputs and labels. - Always pair with a `` linked via `htmlFor` for accessibility. - For mutually exclusive choices, use `` instead. --- ## Related Components - [`RadioGroup`](./radio-group.md) — For single-choice selections - [`Switch`](./switch.md) — For prominent on/off toggles - [`Form`](./form.md) --- END COMPONENT: CHECKBOX --- --- START COMPONENT: CODE-BLOCK --- # CodeBlock A syntax-highlighted code display component with a one-click copy button. Designed for use inside AI chat messages and documentation panels. --- ## Import ```tsx import { CodeBlock } from 'xertica-ui/assistant'; ``` --- ## Basic Usage ```tsx ``` --- ## Props | Prop | Type | Default | Description | | ----------- | -------- | ------------ | --------------------------------------------------------------------------------------- | | `code` | `string` | _(required)_ | The source code string to display | | `language` | `string` | `'text'` | Language identifier for syntax highlighting (e.g. `'typescript'`, `'python'`, `'bash'`) | | `className` | `string` | — | Additional CSS classes for the outer container | --- ## Features ### Syntax Highlighting Uses `react-syntax-highlighter` (Prism engine) with a custom theme built on Xertica UI design tokens: - **Keywords / operators**: `var(--chart-1)` (primary accent) - **Strings**: `var(--chart-2)` (green-toned) - **Numbers / booleans**: `var(--chart-5)` (amber-toned) - **Properties / attributes**: `var(--chart-4)` (blue-toned) - **Comments**: `var(--muted-foreground)` (subdued) - **Background**: transparent (inherits from parent card) The theme automatically adapts to light and dark mode via CSS custom properties. ### Copy Button A copy-to-clipboard button appears in the top-right corner of the code block. After clicking: - The icon changes from `Copy` to `Check` for 2 seconds - The code string is written to the clipboard via the Clipboard API ### Supported Languages Any language supported by Prism.js is valid. Common examples: ``` typescript javascript tsx jsx python bash sql json css html yaml markdown ``` --- ## Usage in AI Context `CodeBlock` is used internally by `XerticaAssistant` to render code snippets returned by the AI. When the assistant response contains a fenced code block (` ```language `), it is automatically rendered as a `CodeBlock`. To render code blocks in a standalone context: ```tsx import { CodeBlock } from 'xertica-ui/assistant'; function AiResponse({ content }: { content: string }) { // Parse code blocks from markdown and render them return ; } ``` --- ## Design Notes - The component uses `font-mono` (CSS variable `--font-mono`) for the code font - Font size is fixed at `0.875rem` (14px) for readability in narrow panels - Line height is `1.6` for comfortable reading - Tab size is 2 spaces - Horizontal overflow scrolls within the block (no line wrapping) --- ## AI Rules > [!IMPORTANT] > > - **Always provide `language`**: Without it, syntax highlighting falls back to plain text. Use the correct language identifier (e.g. `'typescript'` not `'ts'`, `'javascript'` not `'js'`). > - **Do not wrap in `

` or ``**: `CodeBlock` renders its own `` via `react-syntax-highlighter`. Wrapping it will break the layout.
> - **Optimized for narrow panels**: This component is designed for the AI Assistant sidebar (~400px). For full-page code display, consider adding `className="w-full"`.

--- END COMPONENT: CODE-BLOCK ---


--- START COMPONENT: COLLAPSIBLE ---
# Collapsible

## Overview

A single expandable/collapsible content section with a trigger header. Unlike ``, `Collapsible` is a standalone element — it has no sibling items and no managed "only one open" behavior.

---

## When to Use

- A single section of additional details that is hidden by default
- "Show more" / "Show less" controls
- Expandable code snippets or technical details
- A configuration section that most users skip

## When NOT to Use

- Multiple related collapsible sections — use `` instead.

---

## Anatomy

```

  
    
    
  
  
    Advanced configuration options appear here.
  
;
```

---

## AI Rules

- For multiple related collapsible sections, use `` instead.
- `` is required when wrapping a `
  
  
    
      Add Team Member
      Enter the new member's details below.
    
    
      
        Full Name
        
      
      
        Email
        
      
    
    
      
    
  
;
```

### Long Content with Pinned Header/Footer

Use `DialogBody` to keep header and footer visible while content scrolls.

```tsx
import {
  Dialog,
  DialogBody,
  DialogContent,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
  Button,
} from 'xertica-ui/ui';


  
    
  
  
    
      Terms of Service
    
    {/* long scrollable content */}
    
      
      
    
  
;
```

### Controlled Dialog

```tsx
const [open, setOpen] = useState(false);


  
    
  
  
    
      Edit Record
    
    {/* Form content */}
    
      
      
    
  
;
```

---

## AI Rules

- Always use `` wrapping a `
      
    
  

```

---

## Props

### Drawer

| Prop           | Type                      | Description           |
| -------------- | ------------------------- | --------------------- |
| `open`         | `boolean`                 | Controlled open state |
| `onOpenChange` | `(open: boolean) => void` | State handler         |

---

## Examples

```tsx
import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
  Button,
} from 'xertica-ui/ui';


  
    
  
  
    
      Filters
      Narrow down your results.
    
    {/* Filter controls */}
    
      
      
        
      
    
  
;
```

---

## AI Rules

- `DrawerTitle` is **required** for accessibility.
- `DrawerClose asChild` wrapping a `
            
          ))}
        
      )}
    
  );
}
```

---

## AI Rules

- Do not use native `` — always use `` or `useFileUpload` from `xertica-ui`.
- `maxSize` is in bytes — calculate using `MB * 1024 * 1024`.
- In forms, use `onFilesChange` to call `field.onChange` — not `{...field}`.
- For avatar uploads, use `accept="image/*"` and `multiple={false}`.
- When using `useFileUpload`, attach `handleDrag` to **all three** drag events: `onDragEnter`, `onDragOver`, and `onDragLeave`.
- Always attach `inputRef` to a hidden `` element — `openFileDialog()` requires it.
- `removeFile(index)` removes by array index, not by file name.

--- END COMPONENT: FILE-UPLOAD ---


--- START COMPONENT: FLOATING-MEDIA-WRAPPER ---
# FloatingMediaWrapper

A higher-level wrapper for media players (audio/video) that manages floating state, positioning, and transitions.

---

## Overview

The `FloatingMediaWrapper` is the engine behind the "auto-float" behavior of Xertica UI media components. It provides a draggable, resizable container that can follow the user across the application via portals, ensuring uninterrupted media consumption.

---

## Features

- **Draggable & Resizable**: Users can move and scale the media window as needed.
- **Persistent State**: Remembers the last position and size in `localStorage` per `playerId`.
- **Portal Rendering**: Mounts to `document.body` when floating to avoid CSS clipping and parent constraints.
- **Responsive Placeholder**: Leaves a placeholder in the original document position when floating.

---

## Props

| Prop            | Type                     | Default     | Description                            |
| --------------- | ------------------------ | ----------- | -------------------------------------- |
| `isFloating`    | `boolean`                | —           | Controls the floating state.           |
| `setIsFloating` | `(v: boolean) => void`   | —           | State setter for floating state.       |
| `title`         | `string`                 | —           | Title shown in the floating header.    |
| `aspectRatio`   | `number`                 | `16 / 9`    | Mantains the ratio during resize.      |
| `minWidth`      | `number`                 | `320`       | Minimum width allowed.                 |
| `colorVariant`  | `'default' \| 'primary'` | `'default'` | Visual style of the header.            |
| `playerId`      | `string`                 | `'default'` | Unique key for storing position state. |

---

## Examples

### Basic Usage

```tsx
import { FloatingMediaWrapper } from 'xertica-ui/media';

function MyPlayer() {
  const [isFloating, setIsFloating] = useState(false);

  return (
    
      
  );
}
```

---

## Related Components

- [`VideoPlayer`](./video-player.md) — Uses this wrapper for its floating mode.
- [`AudioPlayer`](./audio-player.md) — For system-level audio playback.

--- END COMPONENT: FLOATING-MEDIA-WRAPPER ---


--- START COMPONENT: FORM ---
# Form

## Overview

`Form` is the integration layer between `react-hook-form` and Xertica UI components. It provides a context-aware set of wrappers (`FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormMessage`, `FormDescription`) that automatically connect to form state, display validation errors, and manage ARIA attributes.

---

## When to Use

- Any data-entry form that requires validation.
- Always used with `react-hook-form` + `zod`.

## When NOT to Use

- Simple one-field forms without validation — use a plain `` with `onChange` state.
- Server-side rendered read-only data — display with `` and typography.

---

## Required Dependencies

```bash
npm install react-hook-form zod @hookform/resolvers
```

---

## Anatomy

```tsx

  {' '}
  ← Spreads RHF context
  
     (
        
          Label
          
             ← Spread field props here
          
          Helper text
           ← Auto error from zod
        
      )}
    />
    
  

```

---

## Sub-Components

| Component         | Description                                                              |
| ----------------- | ------------------------------------------------------------------------ |
| `Form`            | Wraps the form with react-hook-form context. Spread `{...form}` on it.   |
| `FormField`       | Connects a single field to form state via `control` and `name`.          |
| `FormItem`        | Layout wrapper for label + control + message.                            |
| `FormLabel`       | Accessible label, automatically linked to the control's `id`.            |
| `FormControl`     | Wrapper that applies `aria-invalid` and `aria-describedby` to the child. |
| `FormDescription` | Helper text shown below the control.                                     |
| `FormMessage`     | Renders the zod validation error for this field. Auto-hides when valid.  |

---

## Props

### FormField

| Prop      | Type                       | Required | Description                           |
| --------- | -------------------------- | -------- | ------------------------------------- |
| `control` | `Control`                  | **Yes**  | `form.control` from `useForm()`       |
| `name`    | `string`                   | **Yes**  | Field name, must match schema key     |
| `render`  | `({ field }) => ReactNode` | **Yes**  | Render function receiving field props |

---

## Examples

### Complete Validated Form

```tsx
import { zodResolver } from '@hookform/resolvers/zod';
import { useForm } from 'react-hook-form';
import * as z from 'zod';
import {
  Form,
  FormField,
  FormItem,
  FormLabel,
  FormControl,
  FormMessage,
  Input,
  Button,
  Card,
  CardContent,
  CardFooter,
  CardHeader,
  CardTitle,
} from 'xertica-ui/ui';

const schema = z.object({
  name: z.string().min(2, 'Name must be at least 2 characters'),
  email: z.string().email('Invalid email'),
});

export function MyForm() {
  const form = useForm({ resolver: zodResolver(schema), defaultValues: { name: '', email: '' } });

  return (
    
      
        Create User
      
      
         console.log(data))}>
          
             (
                
                  Full Name
                  
                    
                  
                  
                
              )}
            />
             (
                
                  Email
                  
                    
                  
                  
                
              )}
            />
          
          
            
          
        
      
    
  );
}
```

---

## AI Rules

- **Never implement manual validation state** (`useState` + if blocks). Use `zod` + `react-hook-form`.
- **Never render error `` or `` manually** — `` handles this automatically.
- The `{...field}` spread goes on the **inner input component** (``, ``, etc.), not on `<FormControl>`.
- For `<Select>` fields, use `onValueChange={field.onChange}` and `defaultValue={field.value}` — do not spread `{...field}` on `<Select>`.
- For `<Checkbox>` fields, use `checked={field.value}` and `onCheckedChange={field.onChange}`.
- `<FormControl>` must be the **direct parent** of the input component — wrapping it further breaks the ARIA linking.

---

## Related Components

- [`Input`](./input.md), [`Textarea`](./textarea.md), [`Select`](./select.md), [`Checkbox`](./checkbox.md), [`Switch`](./switch.md)
- [`Dialog`](./dialog.md) — Common container for forms
- [Form Pattern](../patterns/form.md) — Complete real-world usage example

--- END COMPONENT: FORM ---


--- START COMPONENT: FORMATTED-DOCUMENT ---
# FormattedDocument

A lightweight Markdown-to-HTML renderer with a collapsible preview. Designed for displaying AI-generated documents, reports, and structured text inside the assistant panel.

---

## Import

```tsx
import { FormattedDocument } from 'xertica-ui/assistant';
```

---

## Basic Usage

```tsx
<FormattedDocument content="# Report\n\nThis is a **bold** statement.\n\n- Item one\n- Item two" />
```

---

## Props

| Prop               | Type     | Default      | Description                                                |
| ------------------ | -------- | ------------ | ---------------------------------------------------------- |
| `content`          | `string` | _(required)_ | Raw Markdown string to render                              |
| `maxPreviewLength` | `number` | `500`        | Character count shown before the "See more" toggle appears |
| `className`        | `string` | `''`         | Additional CSS classes for the outer container             |

---

## Supported Markdown Syntax

| Syntax              | Output                                     |
| ------------------- | ------------------------------------------ |
| `# Heading 1`       | `<h1>` — `text-xl font-medium`             |
| `## Heading 2`      | `<h2>` — `text-lg font-medium`             |
| `### Heading 3`     | `<h3>` — `text-base font-medium`           |
| `**bold**`          | `<strong>` — `font-medium text-foreground` |
| `*italic*`          | `<em>` — `italic`                          |
| `- item` / `* item` | Unordered list (`<ul>`)                    |
| `1. item`           | Ordered list (`<ol>`)                      |
| `- [ ] task`        | Unchecked checkbox (disabled)              |
| `- [x] task`        | Checked checkbox (disabled)                |
| `---`               | Horizontal rule (`<hr>`)                   |
| `\n\n`              | Paragraph break                            |

> **Note**: This is a simplified renderer. It does not support tables, links, images, inline code, or fenced code blocks. For full Markdown rendering with code highlighting, use `MarkdownMessage` instead.

---

## Collapsible Preview

When the `content` string exceeds `maxPreviewLength` characters, the component renders a truncated preview with a "Ver mais" (See more) button. Clicking it expands the full content. A "Ver menos" (See less) button collapses it again.

```tsx
// Long document — will show preview with toggle
<FormattedDocument content={longAiGeneratedText} maxPreviewLength={300} />
```

---

## Comparison: `FormattedDocument` vs `MarkdownMessage`

| Feature             | `FormattedDocument`   | `MarkdownMessage`    |
| ------------------- | --------------------- | -------------------- |
| Headers             | ✅                    | ✅                   |
| Bold / Italic       | ✅                    | ✅                   |
| Lists               | ✅                    | ✅                   |
| Checkboxes          | ✅                    | ❌                   |
| Code blocks         | ❌                    | ✅ (via `CodeBlock`) |
| Tables              | ❌                    | ✅                   |
| Links               | ❌                    | ✅                   |
| Collapsible preview | ✅                    | ❌                   |
| Best for            | AI documents, reports | AI chat messages     |

---

## Usage in AI Context

`FormattedDocument` is used by `XerticaAssistant` when the AI returns a document-type response (triggered by the "Create document" action in `ModernChatInput`). The document is also editable via the `RichTextEditor` panel.

```tsx
import { FormattedDocument } from 'xertica-ui/assistant';

function DocumentViewer({ aiOutput }: { aiOutput: string }) {
  return (
    <div className="p-4 bg-card rounded-lg border border-border">
      <FormattedDocument content={aiOutput} maxPreviewLength={800} className="text-sm" />
    </div>
  );
}
```

---

## AI Rules

> [!IMPORTANT]
>
> - **Use for AI-generated documents, not chat messages**: For chat message rendering, use `MarkdownMessage`. `FormattedDocument` is optimized for longer structured content (reports, summaries, plans).
> - **No code block support**: If the AI response contains fenced code blocks (` ``` `), use `MarkdownMessage` or `CodeBlock` instead — `FormattedDocument` will render them as plain text.
> - **Checkboxes are read-only**: The rendered checkboxes have `disabled` attribute. They are for display only. For interactive task lists, build a custom component.
> - **`maxPreviewLength` is character-based**: It counts raw Markdown characters, not rendered text length. Set it higher than you think you need to avoid cutting off mid-sentence.

--- END COMPONENT: FORMATTED-DOCUMENT ---


--- START COMPONENT: GOOGLE-MAPS-LOADER ---
# GoogleMapsLoader

The utility provider and hook responsible for the lazy-loading and initialization of the Google Maps JavaScript API. It is automatically managed by the `XerticaProvider`.

---

## Hook Usage

If you need to check the loading status or access the raw maps library in a custom component:

```tsx
import { useGoogleMapsLoader } from 'xertica-ui';

function MyCustomMap() {
  const { isLoaded, loadError } = useGoogleMapsLoader();

  if (loadError) return <div>Error loading maps</div>;
  if (!isLoaded) return <div>Loading maps...</div>;

  return <div>Maps API is ready!</div>;
}
```

---

## Integration

The loader is part of the `XerticaProvider` ecosystem. You do not need to wrap your components in it manually unless you are building a sub-application that doesn't use the full library provider.

```tsx
<XerticaProvider>
   {/* GoogleMapsLoader is already here */}
   <Map ... />
</XerticaProvider>
```

---

## AI Rules

> [!IMPORTANT]
>
> - **Conditional Rendering**: Always check `isLoaded` before attempting to render any component that requires `window.google`.
> - **Singleton**: Never instantiate multiple loaders. The `XerticaProvider` ensures only one instance manages the script injection.

--- END COMPONENT: GOOGLE-MAPS-LOADER ---


--- START COMPONENT: HEADER ---
# Header

## Overview

The `Header` is the global application top bar — a fixed-height strip (`64px`) rendered at the top of the application shell. It provides a standardized navigation trail (breadcrumbs) and universal system controls.

It is part of the application's "Global Shell" and is designed to work in tandem with the `Sidebar` via the `LayoutContext`.

---

## Key Features

- **Breadcrumb Navigation**: The primary pattern. Supports unlimited depth levels for complex navigation hierarchies.
- **Title Fallback**: Exception pattern for standalone pages with no navigation hierarchy — renders a plain text label.
- **Breadcrumb Slot**: Custom element rendered immediately after the breadcrumb area (badges, buttons, chips, etc.).
- **Responsive Navigation**: Includes a mobile hamburger toggle that synchronizes with the `Sidebar` state.
- **Unified Controls**: Centralizes language selection, theme switching, and user profile management.
- **Universal Actions**: Supports a custom set of sticky action buttons (like Notifications or Search) next to the user profile.

---

## When to Use

- **Always** included in the main application layout (`LayoutContent` or equivalent).
- **Always prefer breadcrumbs** — they are the primary and recommended navigation pattern.
- Use `title` **only** for standalone top-level pages with no parent/navigation context.

---

## Anatomy

```
┌──────────────────────────────────────────────────────────────────────────┐
│ [☰] Home > Settings  [BreadcrumbSlot]     [Actions] [Language] [☀] [User] │
└──────────────────────────────────────────────────────────────────────────┘
```

- **Left Section**: Mobile menu trigger, Breadcrumb trail (or title), and optional `breadcrumbSlot`.
- **Right Section**: Configurable action buttons, system toggles, and the User Profile dropdown.

---

## Props

| Prop                   | Type                                                                              | Default | Description                                                                                                                |
| ---------------------- | --------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `title`                | `string`                                                                          | —       | Page title for standalone pages with **no** navigation hierarchy. Exception pattern — prefer `breadcrumbs`.                |
| `breadcrumbs`          | `BreadcrumbType[]`                                                                | —       | **Primary pattern.** Navigation breadcrumb trail. Supports unlimited levels. Last item without `href` is the current page. |
| `breadcrumbSlot`       | `ReactNode`                                                                       | —       | Custom element rendered immediately after the breadcrumb/title. Accepts any ReactNode — badges, buttons, chips.            |
| `renderLink`           | `(href: string, props: { className?: string; children: ReactNode }) => ReactNode` | —       | Custom link renderer for SPA navigation (React Router, Next.js). When omitted, uses standard `<a>` tags.                   |
| `showLanguageSelector` | `boolean`                                                                         | `true`  | Whether to show the standard language switcher.                                                                            |
| `showThemeToggle`      | `boolean`                                                                         | `true`  | Whether to show the light/dark mode toggle button.                                                                         |
| `user`                 | `HeaderUser`                                                                      | —       | User information and custom profile dropdown menu configuration.                                                           |
| `actions`              | `HeaderAction[]`                                                                  | —       | Custom global action buttons (e.g., Notifications, Help).                                                                  |
| `showSettings`         | `boolean`                                                                         | `false` | Quick access settings icon (renders before the user profile).                                                              |
| `showLogout`           | `boolean`                                                                         | `false` | Quick logout icon (renders as the absolute last item).                                                                     |
| `className`            | `string`                                                                          | —       | Additional CSS classes for the header container.                                                                           |

---

## Navigation Modes

### Breadcrumbs (Default — Recommended)

The primary and recommended pattern. Use for any page with a navigation hierarchy.

```tsx
<Header
  breadcrumbs={[
    { label: 'Home', href: '/', icon: <Home className="size-4" /> },
    { label: 'Settings', href: '/settings' },
    { label: 'Team Management' },
  ]}
/>
```

### Deep Navigation (Unlimited Levels)

Breadcrumbs support any depth — do not artificially limit to 2 or 3 items.

```tsx
<Header
  breadcrumbs={[
    { label: 'Home', href: '/', icon: <Home className="size-4" /> },
    { label: 'Settings', href: '/settings', icon: <Settings className="size-4" /> },
    { label: 'Organization', href: '/settings/org', icon: <FolderOpen className="size-4" /> },
    { label: 'Teams', href: '/settings/org/teams', icon: <Users className="size-4" /> },
    { label: 'Engineering', href: '/settings/org/teams/engineering' },
    { label: 'Access Policies' },
  ]}
/>
```

### Title Only (Exception)

Use **only** for standalone pages with no navigation hierarchy.

```tsx
<Header title="Dashboard" />
```

### With Breadcrumb Slot

Render badges, buttons, or status chips immediately after the breadcrumb.

```tsx
import { Badge, Button } from 'xertica-ui/ui';

<Header
  breadcrumbs={[{ label: 'Home', href: '/' }, { label: 'Deployments' }]}
  breadcrumbSlot={
    <div className="flex items-center gap-2">
      <Badge variant="warning">Beta</Badge>
      <Button variant="outline" size="sm">
        Sync
      </Button>
    </div>
  }
/>;
```

---

## Fallback Logic

The `Header` ensures a navigation area is **never empty**:

1. **Breadcrumbs**: If provided, renders the full navigation trail.
2. **Title**: If provided (without breadcrumbs), renders a simple standalone text label.
3. **Default**: If neither is provided, falls back to `Xertica.ai`.

---

## SPA Navigation (renderLink)

By default, breadcrumb links render as standard `<a>` tags causing full-page reloads. Use `renderLink` to integrate with client-side routers:

### React Router

```tsx
import { Link } from 'react-router-dom';

<Header
  breadcrumbs={[...]}
  renderLink={(href, props) => <Link to={href} {...props} />}
/>
```

### Next.js

```tsx
import NextLink from 'next/link';

<Header
  breadcrumbs={[...]}
  renderLink={(href, props) => <NextLink href={href} {...props} />}
/>
```

---

## AI Rules

- **Breadcrumbs First** — Always prefer `breadcrumbs` for pages with navigation context. Use `title` only for standalone pages.
- **Unlimited Levels** — Breadcrumbs support any depth. Do not artificially limit to 2–3 items.
- **SPA Navigation** — Always use `renderLink` in React Router or Next.js projects to prevent full-page reloads.
- **breadcrumbSlot** — Use for contextual page-level indicators (environment badge, sync button, status chip) that belong visually next to the page title.
- **Integration** — Must be placed at the top of the application shell. Do not use multiple `Header` components in the same layout.
- **Mobile** — The component automatically handles the `LayoutContext` toggle. Do not wrap it in another button for mobile sidebar control.

---

## Related Components

- [`PageHeader`](./page-header.md) — Local content header (used INSIDE the page for titles and local actions).
- [`Sidebar`](./sidebar.md) — The vertical navigation panel.
- [`Breadcrumb`](./breadcrumb.md) — The underlying UI primitive.

--- END COMPONENT: HEADER ---


--- START COMPONENT: HOOKS ---
# Hooks — Xertica UI

Xertica UI exposes a set of React hooks via the `xertica-ui/hooks` subpath. These hooks provide access to global contexts (theme, language, layout, assistant, API keys, brand colors) and utility behaviors (audio player, keyboard shortcuts, mobile detection).

---

## Import

```tsx
import {
  useTheme,
  useLanguage,
  useBrandColors,
  useAssistente,
  useApiKey,
  useLayout,
  useAudioPlayer,
  useLayoutShortcuts,
  useIsMobile,
} from 'xertica-ui/hooks';
```

All hooks are also available from the root barrel:

```tsx
import { useTheme, useLayout } from 'xertica-ui';
```

---

## `useTheme`

Accesses and controls the current color theme (light/dark).

**Source**: `contexts/ThemeContext.tsx`

### Return Value

| Property      | Type                            | Description                    |
| ------------- | ------------------------------- | ------------------------------ |
| `theme`       | `'light' \| 'dark' \| 'system'` | Current active theme           |
| `setTheme`    | `(theme: Theme) => void`        | Sets the theme explicitly      |
| `toggleTheme` | `() => void`                    | Toggles between light and dark |

### Usage

```tsx
import { useTheme } from 'xertica-ui/hooks';

function ThemeButton() {
  const { theme, toggleTheme } = useTheme();
  return <button onClick={toggleTheme}>Current: {theme}</button>;
}
```

> **Note**: `useTheme` must be used inside `<XerticaProvider>` (which includes `ThemeProvider`). For a self-contained toggle that does not require context, use the `<ThemeToggle>` component instead.

---

## `useLanguage`

Accesses and controls the current UI language preference, plus the list of available languages.

**Source**: `contexts/LanguageContext.tsx`

### Return Value

| Property             | Type                           | Description                                                                                                    |
| -------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `language`           | `string`                       | Current language code (e.g. `'pt-BR'`, `'en'`, `'fr'`)                                                         |
| `setLanguage`        | `(language: Language) => void` | Changes the language: persists to localStorage, calls `i18n.changeLanguage`, and invalidates React Query cache |
| `availableLanguages` | `LanguageDefinition[]`         | The full list of languages configured via `availableLanguages` prop on `<XerticaProvider>`                     |
| `isMonolingual`      | `boolean`                      | `true` when only one language is configured. The `LanguageSelector` uses this to auto-hide                     |

### Usage

```tsx
import { useLanguage } from 'xertica-ui/hooks';

function LanguageDisplay() {
  const { language, setLanguage, availableLanguages } = useLanguage();
  // The dropdown is fully data-driven — works with any number of languages
  return (
    <select value={language} onChange={e => setLanguage(e.target.value)}>
      {availableLanguages.map(lang => (
        <option key={lang.code} value={lang.code}>
          {lang.label}
        </option>
      ))}
    </select>
  );
}
```

> **Note**: The language preference is persisted in `localStorage` under the key `xertica_language`. Calling `setLanguage(lang)` also (1) calls `i18n.changeLanguage(lang)` from `i18next` — all components that use `useTranslation()` re-render immediately, and (2) invalidates the React Query cache — data-layer strings (like mock API responses) are refetched in the new language. The `LanguageSelector` component wires this automatically — you only need to call `setLanguage` directly when changing the language programmatically (e.g., from a settings page).

> **Type note**: `Language` is `string`, not a strict union, to support runtime-added locales. Use `availableLanguages` from this hook to discover valid codes.

---

## `useBrandColors`

Accesses and modifies the brand color palette applied as CSS custom properties.

**Source**: `contexts/BrandColorsContext.tsx`

### Return Value

| Property        | Type                                              | Description                           |
| --------------- | ------------------------------------------------- | ------------------------------------- |
| `colors`        | `BrandColors`                                     | Current brand color values            |
| `setBrandColor` | `(key: keyof BrandColors, value: string) => void` | Updates a single brand color          |
| `currentTheme`  | `string`                                          | Name of the active color theme preset |

### Usage

```tsx
import { useBrandColors } from 'xertica-ui/hooks';

function BrandCustomizer() {
  const { colors, setBrandColor } = useBrandColors();
  return (
    <input
      type="color"
      value={colors.primary}
      onChange={e => setBrandColor('primary', e.target.value)}
    />
  );
}
```

> **Note**: Color changes are applied immediately as CSS variables on `:root`. They persist across re-renders but are not saved to `localStorage` by default.

---

## `useAssistente`

Accesses the global AI Assistant context — conversation list, current conversation, and navigation helpers.

**Source**: `contexts/AssistenteContext.tsx`

### Return Value

| Property           | Type                           | Description                                    |
| ------------------ | ------------------------------ | ---------------------------------------------- |
| `conversas`        | `Conversation[]`               | List of all conversations                      |
| `conversaAtual`    | `string \| null`               | ID of the currently active conversation        |
| `setConversaAtual` | `(id: string \| null) => void` | Selects a conversation                         |
| `sugestoes`        | `Suggestion[]`                 | Quick-reply suggestions for the welcome screen |
| `setSugestoes`     | `(s: Suggestion[]) => void`    | Replaces the suggestion list                   |

### Usage

```tsx
import { useAssistente } from 'xertica-ui/hooks';

function ConversationCount() {
  const { conversas } = useAssistente();
  return <span>{conversas.length} conversations</span>;
}
```

> **Note**: This hook must be used inside `<XerticaProvider>` (which includes `AssistenteProvider`). It is primarily used internally by `XerticaAssistant`.

---

## `useApiKey`

Accesses and manages API keys for Xertica services, Gemini AI, and Google Maps.

**Source**: `contexts/ApiKeyContext.tsx`

### Return Value

| Property               | Type                    | Description                              |
| ---------------------- | ----------------------- | ---------------------------------------- |
| `apiKey`               | `string`                | Xertica platform API key                 |
| `setApiKey`            | `(key: string) => void` | Updates the Xertica API key              |
| `geminiApiKey`         | `string`                | Google Gemini API key                    |
| `setGeminiApiKey`      | `(key: string) => void` | Updates the Gemini API key               |
| `isApiKeyValid`        | `boolean`               | Whether the Xertica API key is non-empty |
| `googleMapsApiKey`     | `string`                | Google Maps API key                      |
| `setGoogleMapsApiKey`  | `(key: string) => void` | Updates the Maps API key                 |
| `isGoogleMapsKeyValid` | `boolean`               | Whether the Maps key is non-empty        |
| `reloadMapsApi`        | `() => Promise<void>`   | Reloads the Maps script after key change |

### Usage

```tsx
import { useApiKey } from 'xertica-ui/hooks';

function ApiKeySettings() {
  const { geminiApiKey, setGeminiApiKey, isApiKeyValid } = useApiKey();
  return (
    <input
      type="password"
      value={geminiApiKey}
      onChange={e => setGeminiApiKey(e.target.value)}
      placeholder="Enter Gemini API key"
    />
  );
}
```

> **Note**: API keys are persisted in `localStorage`. The `XerticaAssistant` component reads `geminiApiKey` automatically when `demoMode={false}` (real AI mode). When `demoMode={true}` (default), no API key is required.

---

## `useLayout`

Accesses and controls the global layout state — sidebar expansion, assistant panel, and width values.

**Source**: `contexts/LayoutContext.tsx`

### Return Value

| Property                  | Type                      | Description                            |
| ------------------------- | ------------------------- | -------------------------------------- |
| `sidebarExpanded`         | `boolean`                 | Whether the sidebar is expanded        |
| `sidebarWidth`            | `number`                  | Current sidebar width in pixels        |
| `setSidebarWidth`         | `(width: number) => void` | Updates the sidebar width              |
| `toggleSidebar`           | `() => void`              | Toggles sidebar expanded state         |
| `assistenteExpanded`      | `boolean`                 | Whether the AI assistant panel is open |
| `toggleAssistente`        | `() => void`              | Toggles the assistant panel            |
| `toggleAssistenteWithTab` | `(tab: string) => void`   | Opens the assistant on a specific tab  |

### Usage

```tsx
import { useLayout } from 'xertica-ui/hooks';

function ContentArea() {
  const { sidebarExpanded, sidebarWidth } = useLayout();
  return <main style={{ marginLeft: sidebarWidth }}>{/* content */}</main>;
}
```

> **See also**: `docs/layout.md` for the complete layout system reference.

---

## `useAudioPlayer`

Headless hook that encapsulates all state and side effects for audio playback. Use this to build a fully custom audio player UI while reusing the library's playback logic.

**Source**: `components/media/audio-player/use-audio-player.ts`

### Props (`UseAudioPlayerProps`)

| Prop              | Type              | Default  | Description                                          |
| ----------------- | ----------------- | -------- | ---------------------------------------------------- |
| `src`             | `string`          | —        | Audio file URL                                       |
| `autoPlay`        | `boolean`         | `false`  | Start playing on mount                               |
| `initialTime`     | `number`          | `0`      | Initial seek position in seconds                     |
| `initialDuration` | `number`          | —        | Pre-known duration (loaded from metadata if omitted) |
| `variant`         | `'card' \| 'bar'` | `'card'` | Layout variant (affects floating behavior)           |
| `isOpen`          | `boolean`         | `true`   | Whether the bar variant is visible                   |
| `enableAutoFloat` | `boolean`         | `true`   | Auto-float when scrolled out of view (card only)     |
| `onCloseFloating` | `() => void`      | —        | Called when user closes the floating player          |

### Return Value (`UseAudioPlayerReturn`)

**Refs**

| Property       | Type                          | Description                                         |
| -------------- | ----------------------------- | --------------------------------------------------- |
| `audioRef`     | `RefObject<HTMLAudioElement>` | Attach to `<audio>` element                         |
| `containerRef` | `RefObject<HTMLDivElement>`   | Attach to the player container for scroll detection |

**Playback State**

| Property        | Type      | Description                             |
| --------------- | --------- | --------------------------------------- |
| `isPlaying`     | `boolean` | Whether audio is currently playing      |
| `currentTime`   | `number`  | Current playback position in seconds    |
| `duration`      | `number`  | Total duration in seconds               |
| `volume`        | `number`  | Volume level (0–1)                      |
| `isMuted`       | `boolean` | Whether audio is muted                  |
| `playbackSpeed` | `number`  | Current playback speed (0.5, 1, 1.5, 2) |

**UI State**

| Property               | Type      | Description                              |
| ---------------------- | --------- | ---------------------------------------- |
| `isFloating`           | `boolean` | Whether the player is in floating mode   |
| `isManualFloating`     | `boolean` | Whether floating was triggered manually  |
| `isVisible`            | `boolean` | Whether the container is in the viewport |
| `isMobile`             | `boolean` | Whether the viewport is mobile-sized     |
| `enableAutoFloatLocal` | `boolean` | Current auto-float setting               |

**Layout Context**

| Property             | Type      | Description                         |
| -------------------- | --------- | ----------------------------------- |
| `sidebarExpanded`    | `boolean` | Sidebar state (for bar positioning) |
| `sidebarWidth`       | `number`  | Sidebar width in pixels             |
| `assistenteExpanded` | `boolean` | Assistant panel state               |

**Handlers**

| Property                  | Type                          | Description                          |
| ------------------------- | ----------------------------- | ------------------------------------ |
| `togglePlay`              | `() => void`                  | Play/pause toggle                    |
| `toggleMute`              | `() => void`                  | Mute/unmute toggle                   |
| `handleSeek`              | `(value: number[]) => void`   | Seek to position (Slider-compatible) |
| `handleVolumeChange`      | `(value: number[]) => void`   | Change volume (Slider-compatible)    |
| `handleSetFloating`       | `(floating: boolean) => void` | Set floating state                   |
| `handleEnableManualFloat` | `() => void`                  | Trigger manual float                 |
| `setPlaybackSpeed`        | `(speed: number) => void`     | Change playback speed                |
| `resetAudio`              | `() => void`                  | Reset to beginning                   |

**Audio Element Event Handlers**

| Property           | Type          | Description                          |
| ------------------ | ------------- | ------------------------------------ |
| `onPlay`           | `() => void`  | Attach to `<audio onPlay>`           |
| `onPause`          | `() => void`  | Attach to `<audio onPause>`          |
| `onEnded`          | `() => void`  | Attach to `<audio onEnded>`          |
| `onTimeUpdate`     | `(e) => void` | Attach to `<audio onTimeUpdate>`     |
| `onLoadedMetadata` | `(e) => void` | Attach to `<audio onLoadedMetadata>` |

**Utilities**

| Property     | Type                       | Description                |
| ------------ | -------------------------- | -------------------------- |
| `formatTime` | `(time: number) => string` | Formats seconds as `MM:SS` |

### Usage

```tsx
import { useAudioPlayer } from 'xertica-ui/hooks';

function MyCustomPlayer({ src }: { src: string }) {
  const {
    audioRef,
    containerRef,
    isPlaying,
    togglePlay,
    currentTime,
    duration,
    formatTime,
    onPlay,
    onPause,
    onEnded,
    onTimeUpdate,
    onLoadedMetadata,
  } = useAudioPlayer({ src });

  return (
    <div ref={containerRef}>
      <audio
        ref={audioRef}
        src={src}
        onPlay={onPlay}
        onPause={onPause}
        onEnded={onEnded}
        onTimeUpdate={onTimeUpdate}
        onLoadedMetadata={onLoadedMetadata}
      />
      <button onClick={togglePlay}>{isPlaying ? 'Pause' : 'Play'}</button>
      <span>
        {formatTime(currentTime)} / {formatTime(duration)}
      </span>
    </div>
  );
}
```

> **Note**: For most use cases, use the `<AudioPlayer>` component directly. Use `useAudioPlayer` only when you need a fully custom player UI.

---

## `useLayoutShortcuts`

Registers global keyboard shortcuts for layout control. Must be called **once** in the root layout component.

**Source**: `components/hooks/use-layout-shortcuts.ts`

### Registered Shortcuts

| Shortcut           | Action         |
| ------------------ | -------------- |
| `Ctrl+B` / `Cmd+B` | Toggle sidebar |

### Usage

```tsx
import { useLayoutShortcuts } from 'xertica-ui/hooks';

function AppLayout({ children }: { children: React.ReactNode }) {
  useLayoutShortcuts(); // registers Ctrl+B for sidebar toggle
  return <div>{children}</div>;
}
```

> **Important**: Call this hook only once in your application. Calling it in multiple components will register duplicate event listeners.

---

## `useIsMobile` / `useMobile`

Detects whether the current viewport is mobile-sized (< 768px).

**Source**: `components/shared/use-mobile.ts`

### Return Value

Returns `boolean` — `true` if the viewport width is below the mobile breakpoint.

### Usage

```tsx
import { useIsMobile } from 'xertica-ui/hooks';

function ResponsiveComponent() {
  const isMobile = useIsMobile();
  return isMobile ? <MobileView /> : <DesktopView />;
}
```

> **Note**: Both `useIsMobile` and `useMobile` are exported and are identical. `useIsMobile` is the preferred name. See [`use-mobile.md`](./use-mobile.md) for the full reference.

---

## AI Rules

> [!IMPORTANT]
>
> - **Always use hooks inside providers**: All context hooks (`useTheme`, `useLanguage`, `useBrandColors`, `useAssistente`, `useApiKey`, `useLayout`) require `<XerticaProvider>` in the component tree. Calling them outside a provider throws an error.
> - **`useLayoutShortcuts` is singleton**: Call it exactly once in your root layout component, never in page-level or feature components.
> - **Prefer `<AudioPlayer>` over `useAudioPlayer`**: The headless hook is for advanced custom UIs only. For standard playback, use the component.
> - **`useLayout` for sidebar state**: Never manage sidebar width or expansion state manually. Always read from `useLayout()`.

--- END COMPONENT: HOOKS ---


--- START COMPONENT: HOVER-CARD ---
# HoverCard

## Overview

A floating content panel that appears when hovering over a trigger element — designed for previewing additional information without navigating away. Unlike `Tooltip` (short text hints), `HoverCard` can contain rich content: user profiles, link previews, image thumbnails.

---

## When to Use

- Author profile previews in comment threads or author lists
- Link previews (URL cards)
- Contextual information about a referenced entity

## When NOT to Use

- Short labels or hints — use `<Tooltip>` instead.
- Interactive controls — use `<Popover>` instead.

---

## Anatomy

```
<HoverCard>
  <HoverCardTrigger asChild>
    <Button variant="link">@username</Button>
  </HoverCardTrigger>
  <HoverCardContent>
    {/* Rich preview content */}
  </HoverCardContent>
</HoverCard>
```

---

## Examples

### User Profile Preview

```tsx
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
  Avatar,
  AvatarFallback,
  AvatarImage,
  Button,
} from 'xertica-ui/ui';

<HoverCard>
  <HoverCardTrigger asChild>
    <Button variant="link" className="p-0 h-auto">
      @ariel
    </Button>
  </HoverCardTrigger>
  <HoverCardContent className="w-80">
    <div className="flex gap-4">
      <Avatar>
        <AvatarImage src="https://github.com/ariel.png" />
        <AvatarFallback>AS</AvatarFallback>
      </Avatar>
      <div className="space-y-1">
        <h4 className="text-sm font-semibold">Ariel Santos</h4>
        <p className="text-sm text-muted-foreground">Design system architect at Xertica AI.</p>
      </div>
    </div>
  </HoverCardContent>
</HoverCard>;
```

---

## AI Rules

- `HoverCard` opens on hover — never render interactive controls that require clicking inside it (use `Popover` for those).
- Use `asChild` on `<HoverCardTrigger>` when the trigger is a styled element.
- Set `className="w-80"` on `<HoverCardContent>` for rich content panels — the default is too narrow.

---

## Related Components

- [`Tooltip`](./tooltip.md) — For short text hints
- [`Popover`](./popover.md) — For interactive floating panels

--- END COMPONENT: HOVER-CARD ---


--- START COMPONENT: IMAGE-WITH-FALLBACK ---
# ImageWithFallback

A drop-in replacement for the native `<img>` element that gracefully handles broken or missing image URLs by displaying a placeholder SVG instead of a broken image icon.

---

## Import

```tsx
import { ImageWithFallback } from 'xertica-ui';
// or from the figma subpath (internal)
import { ImageWithFallback } from 'xertica-ui/ui';
```

---

## Basic Usage

```tsx
<ImageWithFallback
  src="https://example.com/photo.jpg"
  alt="User profile photo"
  className="w-32 h-32 rounded-lg object-cover"
/>
```

---

## Props

`ImageWithFallback` accepts all standard HTML `<img>` attributes:

| Prop        | Type                | Description                                                                |
| ----------- | ------------------- | -------------------------------------------------------------------------- |
| `src`       | `string`            | Image URL. If this fails to load, the fallback placeholder is shown.       |
| `alt`       | `string`            | Accessible alternative text (required for accessibility)                   |
| `className` | `string`            | CSS classes applied to both the `<img>` and the fallback container         |
| `style`     | `CSSProperties`     | Inline styles applied to both states                                       |
| `...rest`   | `ImgHTMLAttributes` | All other standard `<img>` attributes (`width`, `height`, `loading`, etc.) |

---

## Behavior

1. **Normal state**: Renders a standard `<img>` element with the provided `src`.
2. **Error state**: When the image fails to load (`onError` fires), the component switches to a fallback `<div>` containing a centered placeholder SVG (a simple broken-image icon).
3. **Fallback container**: The fallback `<div>` uses `bg-gray-100` and inherits the same `className` and `style` as the original image, so it maintains the same dimensions and shape.
4. **Original URL preserved**: The fallback `<img>` stores the original URL in `data-original-url` for debugging purposes.

---

## Usage Examples

### Hero Image with Fallback

```tsx
<ImageWithFallback
  src={article.heroImageUrl}
  alt={article.title}
  className="w-full h-48 object-cover rounded-t-lg"
/>
```

### User Avatar with Fallback

```tsx
<ImageWithFallback
  src={user.avatarUrl}
  alt={`${user.name} avatar`}
  className="w-10 h-10 rounded-full object-cover"
/>
```

> **Note**: For user avatars, prefer the `<Avatar>` component which has built-in fallback support via `<AvatarFallback>` (shows initials). Use `ImageWithFallback` for non-avatar images.

### Lazy Loading

```tsx
<ImageWithFallback
  src={product.imageUrl}
  alt={product.name}
  loading="lazy"
  className="w-full aspect-square object-contain"
/>
```

---

## Comparison: `ImageWithFallback` vs `Avatar`

| Feature       | `ImageWithFallback`                     | `Avatar`              |
| ------------- | --------------------------------------- | --------------------- |
| Fallback type | SVG placeholder icon                    | Text initials         |
| Use case      | General images, hero images, thumbnails | User profile pictures |
| Shape         | Any (controlled by `className`)         | Circle (default)      |
| Import        | `xertica-ui/ui`                         | `xertica-ui/ui`       |

---

## AI Rules

> [!IMPORTANT]
>
> - **Always provide `alt`**: The `alt` attribute is required for accessibility. Never omit it. Use an empty string (`alt=""`) only for purely decorative images.
> - **Use for external images**: Use `ImageWithFallback` whenever the image URL comes from an external source (API, user upload, CMS) that may be unavailable. For static local assets, a regular `<img>` is acceptable.
> - **Do not use for avatars**: For user profile pictures, use the `<Avatar>` + `<AvatarFallback>` pattern instead — it shows initials which is more informative than a broken-image icon.
> - **Maintain dimensions in fallback**: The fallback container inherits `className` and `style`, so always set explicit dimensions (via Tailwind classes like `w-32 h-32` or inline styles) to prevent layout shift when the fallback renders.

--- END COMPONENT: IMAGE-WITH-FALLBACK ---


--- START COMPONENT: INPUT-OTP ---
# InputOTP

## Overview

A one-time password / PIN code input that renders a segmented grid of individual character slots. Designed for MFA flows, email verification codes, and any numeric code entry.

---

## When to Use

- 2FA / MFA authentication code entry
- Email or phone verification
- PIN code inputs

---

## Anatomy

```
<InputOTP maxLength={6}>
  <InputOTPGroup>
    <InputOTPSlot index={0} />
    <InputOTPSlot index={1} />
    <InputOTPSlot index={2} />
  </InputOTPGroup>
  <InputOTPSeparator />
  <InputOTPGroup>
    <InputOTPSlot index={3} />
    <InputOTPSlot index={4} />
    <InputOTPSlot index={5} />
  </InputOTPGroup>
</InputOTP>
```

---

## Props

### InputOTP

| Prop        | Type                      | Required | Description                      |
| ----------- | ------------------------- | -------- | -------------------------------- |
| `maxLength` | `number`                  | **Yes**  | Total number of characters       |
| `value`     | `string`                  | No       | Controlled value                 |
| `onChange`  | `(value: string) => void` | No       | Change handler                   |
| `pattern`   | `string`                  | No       | Allowed characters regex pattern |

### InputOTPSlot

| Prop    | Type                   | Required | Default | Description                                   |
| ------- | ---------------------- | -------- | ------- | --------------------------------------------- |
| `index` | `number`               | **Yes**  | —       | Position of this slot (0-indexed)             |
| `size`  | `'sm' \| 'md' \| 'lg'` | No       | `'md'`  | Size variant controlling the slot dimensions. |

---

## Examples

### 6-Digit Code

```tsx
import { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot } from 'xertica-ui/ui';
import { useState } from 'react';

const [code, setCode] = useState('');

<div className="space-y-4">
  <InputOTP maxLength={6} value={code} onChange={setCode}>
    <InputOTPGroup>
      <InputOTPSlot index={0} />
      <InputOTPSlot index={1} />
      <InputOTPSlot index={2} />
    </InputOTPGroup>
    <InputOTPSeparator />
    <InputOTPGroup>
      <InputOTPSlot index={3} />
      <InputOTPSlot index={4} />
      <InputOTPSlot index={5} />
    </InputOTPGroup>
  </InputOTP>
  <Button onClick={() => verify(code)} disabled={code.length < 6}>
    Verify
  </Button>
</div>;
```

---

## AI Rules

- `maxLength` must match the total number of `InputOTPSlot` elements.
- **Sizing** — Each `InputOTPSlot` supports `sm`, `md`, and `lg`. Use the same size for all slots in the group.
- Each `InputOTPSlot` requires its zero-indexed `index` prop.
- For numeric-only codes, set `pattern="[0-9]*"` on `InputOTP`.
- Disable the verify button when `value.length < maxLength`.

--- END COMPONENT: INPUT-OTP ---


--- START COMPONENT: INPUT ---
# Input

## Overview

The standard text field component. Use it for all single-line text inputs: names, emails, search queries, codes. Integrates seamlessly with `react-hook-form` via the `{...field}` spread pattern.

---

## When to Use

- Single-line text input in forms
- Search bars (pair with the `relative`/absolute icon pattern)
- Inline editing fields

## When NOT to Use

- Multi-line text entry — use `<Textarea>` instead.
- Numeric ranges — use `<Slider>` instead.
- Date selection — use `<Calendar>` instead.
- Never use native `<input>` — always use `<Input>` from `xertica-ui`.

---

## Props

All native `<input>` HTML attributes are forwarded.

| Prop          | Type                   | Default  | Description                                                       |
| ------------- | ---------------------- | -------- | ----------------------------------------------------------------- |
| `type`        | `string`               | `'text'` | Input type: `text`, `email`, `password`, `number`, `search`, etc. |
| `size`        | `'sm' \| 'md' \| 'lg'` | `'md'`   | Size variant controlling height, padding, and font size.          |
| `placeholder` | `string`               | —        | Placeholder text                                                  |
| `disabled`    | `boolean`              | `false`  | Disables interaction                                              |
| `className`   | `string`               | —        | Additional CSS classes                                            |

### Standardized Sizing Scale

All form input components (`Input`, `SelectTrigger`, `Textarea`, `Search`) share the same sizing scale:

| Size | Height        | Padding     | Font        |
| ---- | ------------- | ----------- | ----------- |
| `sm` | `h-8` (32px)  | `px-2 py-1` | `text-sm`   |
| `md` | `h-10` (40px) | `px-3 py-2` | `text-base` |
| `lg` | `h-12` (48px) | `px-4 py-3` | `text-base` |

This ensures all form elements align perfectly when placed side-by-side in grid layouts.

---

## Examples

### Basic Text Input

```tsx
import { Input } from 'xertica-ui/ui';

<Input placeholder="Enter your name" />;
```

### With Label (standalone)

```tsx
import { Input, Label } from 'xertica-ui/ui';

<div className="grid gap-2">
  <Label htmlFor="email">Email</Label>
  <Input id="email" type="email" placeholder="you@example.com" />
</div>;
```

### Search Input with Icon

```tsx
import { Search } from 'lucide-react';

<div className="relative w-full max-w-sm">
  <Search className="absolute left-2.5 top-2.5 size-4 text-muted-foreground" />
  <Input placeholder="Search..." className="pl-8" />
</div>;
```

### Inside react-hook-form

```tsx
<FormField
  control={form.control}
  name="email"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Email</FormLabel>
      <FormControl>
        <Input type="email" placeholder="you@example.com" {...field} />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>
```

---

## Accessibility

- Always pair with a `<Label>` component. Use the `htmlFor` prop on the label and `id` on the input to link them.
- If a visual label is not possible (e.g., search bars), **you must provide an `aria-label`** prop:
  ```tsx
  <Input aria-label="Search items" placeholder="Search..." />
  ```
- Use the `disabled` prop to indicate non-interactive fields correctly to assistive technologies.
- Maintain a minimum 1.5:1 contrast for placeholder text (handled by design system defaults).

---

## AI Rules

- **Never** use native `<input>` — always use `<Input>` from `xertica-ui`.
- **Sizing** — The default size is `md` (h-10, 40px). Use the same `size` prop across `Input`, `SelectTrigger`, `Textarea`, and `Search` to ensure consistent alignment.
- **Accessibility Requirement**: Always provide a `<Label>` or an explicit `aria-label`. Placeholder text is NOT an accessible name.
- When in a form with `react-hook-form`, **always spread `{...field}`** on the `<Input>` inside `<FormControl>`.
- Search inputs always use the `relative` + `absolute icon` + `pl-8` pattern — never place the icon outside the input container.
- Do not add `border`, `rounded`, or `bg-` classes to override the input style — it already inherits from the design system tokens.

---

## Related Components

- [`Textarea`](./textarea.md) — Multi-line text input
- [`Form`](./form.md) — Form integration context
- [`Label`](./label.md) — Always pair with a Label for accessibility
- [`Search`](./search.md) — Pre-built search input component

--- END COMPONENT: INPUT ---


--- START COMPONENT: LABEL ---
# Label

## Overview

An accessible form field label that is always associated with a specific input via `htmlFor`. Automatically applies styling that visually communicates field relationships and disabled states. Used in every form — standalone or via `<FormLabel>` inside the `Form` system.

---

## When to Use

- Above or beside every form input (`<Input>`, `<Textarea>`, `<Select>`, `<Checkbox>`)
- As a visual pointer for non-form groups (settings toggles with `<Switch>`)

## When NOT to Use

- As generic body text — use a `<p>` or `<span>` instead.
- Do not omit labels from forms for aesthetic reasons — accessibility requires them.

---

## Props

| Prop        | Type                   | Required             | Default | Description                         |
| ----------- | ---------------------- | -------------------- | ------- | ----------------------------------- |
| `htmlFor`   | `string`               | **Yes** (standalone) | —       | ID of the associated input element  |
| `size`      | `'sm' \| 'md' \| 'lg'` | No                   | `'md'`  | Size variant controlling font size. |
| `className` | `string"               | No                   | —       | Additional CSS classes              |

---

## Examples

### Standalone Label + Input

```tsx
import { Label, Input } from 'xertica-ui/ui';

<div className="grid gap-2">
  <Label htmlFor="username">Username</Label>
  <Input id="username" placeholder="johndoe" />
</div>;
```

### With Switch

```tsx
import { Label, Switch } from 'xertica-ui/ui';

<div className="flex items-center space-x-2">
  <Switch id="notifications" />
  <Label htmlFor="notifications">Enable notifications</Label>
</div>;
```

---

## AI Rules

- Every standalone `<Input>`, `<Textarea>`, or `<Select>` must have a `<Label htmlFor="...">`. No exceptions.
- **Sizing** — Matches the standard scale (`sm`, `md`, `lg`). Always set the same `size` as the associated input component.
- When using inside `<FormField>` from `react-hook-form`, use `<FormLabel>` instead — it auto-links to the field.
- `htmlFor` must match the `id` prop on the associated input exactly.

---

## Related Components

- [`Form`](./form.md) — Uses `<FormLabel>` which wraps `<Label>` with automatic `htmlFor` linking
- [`Input`](./input.md), [`Textarea`](./textarea.md), [`Select`](./select.md)

--- END COMPONENT: LABEL ---


--- START COMPONENT: LANGUAGE-SELECTOR ---
# LanguageSelector — Xertica UI

A dropdown component for switching the interface language. It reads the current language from `LanguageContext` and calls `i18n.changeLanguage()` when the user selects a new option — all `useTranslation()` consumers in the app re-render immediately, and the React Query cache is invalidated so data-layer strings refresh too.

---

## Import

```tsx
import { LanguageSelector } from 'xertica-ui/brand';
// or
import { LanguageSelector } from 'xertica-ui';
```

---

## Requirements

`LanguageSelector` calls `useLanguage()` internally and **must** be rendered inside `<LanguageProvider>`. This is satisfied automatically when using `<XerticaProvider>`, which includes `LanguageProvider`.

---

## Usage

### Basic (no props needed)

```tsx
// Language is read from LanguageContext automatically
<LanguageSelector />
```

### In the Header

```tsx
import { Header } from 'xertica-ui/layout';

<Header
  showLanguageSelector={true}
  {/* ...other props */}
/>
```

The `Header` component accepts `showLanguageSelector` and renders `<LanguageSelector />` in its actions area — no manual placement needed.

### Minimal variant (short code only)

```tsx
<LanguageSelector variant="minimal" showIcon={false} />;
{
  /* Trigger displays "PT", "EN", "ES" (or the LanguageDefinition.shortLabel of custom locales) */
}
```

---

## Props

| Prop                  | Type                     | Default     | Description                                                                               |
| --------------------- | ------------------------ | ----------- | ----------------------------------------------------------------------------------------- |
| `variant`             | `'default' \| 'minimal'` | `'default'` | `minimal` shows the short label (`PT`, `EN`, …); `default` shows the full label           |
| `showIcon`            | `boolean`                | `true`      | Show the Globe icon in the trigger                                                        |
| `showLabel`           | `boolean`                | `false`     | Reserved — currently has no visual effect                                                 |
| `className`           | `string`                 | `''`        | Additional CSS classes applied to the `SelectTrigger`                                     |
| `showWhenMonolingual` | `boolean`                | `false`     | Render the selector even when only one language is configured (would otherwise auto-hide) |

> **Removed props**: `initialLanguage` and `onLanguageChange` no longer exist. The component reads from `LanguageContext` and drives language changes through `i18n.changeLanguage()` internally.

---

## Supported Languages

By default the library ships with three languages (`DEFAULT_LANGUAGES`):

| Code      | Display        | Short label |
| --------- | -------------- | ----------- |
| `'pt-BR'` | Português (BR) | PT          |
| `'en'`    | English        | EN          |
| `'es'`    | Español        | ES          |

**The list is fully runtime-configurable.** Pass `availableLanguages` on `<XerticaProvider>` to add, remove, or restrict the set of languages exposed by the selector — no source-file edits required. See [`docs/i18n.md`](../i18n.md#configuring-available-languages) for the full API.

### Adding a custom language

```tsx
import { XerticaProvider, DEFAULT_LANGUAGES } from 'xertica-ui';
import fr from './locales/fr.json';

<XerticaProvider
  availableLanguages={[
    ...DEFAULT_LANGUAGES,
    { code: 'fr', label: 'Français', shortLabel: 'FR', resources: fr },
  ]}
>
  <LanguageSelector />
  {/* French appears in the dropdown; bundle auto-registered with i18next */}
</XerticaProvider>;
```

### Monolingual app — selector auto-hides

```tsx
<XerticaProvider availableLanguages={[{ code: 'en', label: 'English' }]}>
  <LanguageSelector />
  {/* Renders nothing — there is nothing to switch to */}
</XerticaProvider>
```

To force the selector to render anyway (e.g. as a future-proof placeholder):

```tsx
<LanguageSelector showWhenMonolingual />
```

---

## Behavior

- Reads `language`, `availableLanguages`, and `isMonolingual` from `useLanguage()`
- On selection: calls `setLanguage(lang)` which:
  1. Updates `LanguageContext` state
  2. Writes the new code to `localStorage` (key: `xertica_language`)
  3. Calls `i18n.changeLanguage(lang)` — all `useTranslation()` consumers re-render
  4. Invalidates the React Query cache — mock/API responses translated via `i18n.t()` are refetched in the new language
- **Auto-hides** when `isMonolingual === true` (single-language apps). Pass `showWhenMonolingual` to override.
- The `aria-label` and label text are themselves translated via `useTranslation()` — they change with the active language. Custom language codes fall back to the `label` passed in their `LanguageDefinition`.
- `variant="minimal"` uses `LanguageDefinition.shortLabel` when present, else `code.slice(0, 2).toUpperCase()`.

---

## Placement Guidelines

- **Header actions** — right side, adjacent to `ThemeToggle` and the user avatar (use `Header showLanguageSelector`)
- **Sidebar footer** — when persistent language switching is needed outside the header
- **Login / onboarding screens** — standalone usage before the main layout is mounted

---

## Manual Language Control

If you need to change the language programmatically (e.g., from user profile settings) without rendering `LanguageSelector`:

```tsx
import { useLanguage } from 'xertica-ui/hooks';

function ProfileSettings() {
  const { language, setLanguage, availableLanguages } = useLanguage();

  // Fully data-driven — works with any number of languages
  return (
    <select value={language} onChange={e => setLanguage(e.target.value)}>
      {availableLanguages.map(lang => (
        <option key={lang.code} value={lang.code}>
          {lang.label}
        </option>
      ))}
    </select>
  );
}
```

> Avoid hardcoding the `<option>` list — using `availableLanguages` keeps your settings UI in sync with whatever the consumer configured on `<XerticaProvider>`.

---

## AI Rules

> [!IMPORTANT]
>
> - **`<LanguageProvider>` is required**: `LanguageSelector` uses `useLanguage()` — it will throw if rendered outside a `LanguageProvider`. `<XerticaProvider>` includes this automatically.
> - **Do NOT pass `onLanguageChange` or `initialLanguage`** — these props no longer exist. Language state lives in `LanguageContext`; use `useLanguage()` to read or change it.
> - **Do NOT conditionally render this component** for monolingual apps — it self-hides via `isMonolingual`. Only use `showWhenMonolingual` if you explicitly need it visible.
> - **One per layout shell**: Avoid rendering multiple `LanguageSelector` instances — they all share the same context and the UI does not need duplication.
> - **Use `Header showLanguageSelector`** in page shells instead of placing `<LanguageSelector>` manually — it handles positioning and responsive visibility.
> - **`i18next` must be initialized**: `import './i18n'` must appear in `main.tsx` before any component renders; otherwise `useTranslation()` inside `LanguageSelector` will return raw keys.
> - **To support a new language**, pass it via `availableLanguages` on `<XerticaProvider>` — do not modify `LanguageSelector.tsx` or `LanguageContext.tsx`.
> - **In settings/profile pages**, use `availableLanguages` from `useLanguage()` to build the language picker — never hardcode the `<option>` list.

--- END COMPONENT: LANGUAGE-SELECTOR ---


--- START COMPONENT: MAP-LAYERS ---
# MapLayers / useMapLayers

A hook for managing Google Maps native overlay layers (traffic, transit, bicycling) on a map instance. Used internally by the `Map` component via its `layers` prop.

---

## Import

```tsx
import { useMapLayers } from 'xertica-ui/ui';
// or
import { useMapLayers, MapLayersConfig } from 'xertica-ui';
```

---

## `useMapLayers`

A React hook that attaches and detaches Google Maps overlay layers reactively based on a configuration object.

### Signature

```tsx
function useMapLayers(map: google.maps.Map | null, layers: MapLayersConfig): void;
```

### Parameters

| Parameter | Type                      | Description                                                                                  |
| --------- | ------------------------- | -------------------------------------------------------------------------------------------- |
| `map`     | `google.maps.Map \| null` | The Google Maps instance to attach layers to. Pass `null` to skip (layers are not rendered). |
| `layers`  | `MapLayersConfig`         | Configuration object specifying which layers to display                                      |

### `MapLayersConfig`

```tsx
interface MapLayersConfig {
  traffic?: boolean; // Real-time traffic overlay
  transit?: boolean; // Public transit routes overlay
  bicycling?: boolean; // Bicycle route overlay
}
```

---

## Available Layers

| Layer     | Key         | Description                                                 |
| --------- | ----------- | ----------------------------------------------------------- |
| Traffic   | `traffic`   | Real-time traffic conditions with color-coded road segments |
| Transit   | `transit`   | Public transit routes (bus, metro, train)                   |
| Bicycling | `bicycling` | Dedicated bicycle lanes and paths                           |

---

## Usage

### Standalone Hook

```tsx
import { useMapLayers } from 'xertica-ui/ui';

function MapWithLayers() {
  const [mapInstance, setMapInstance] = useState<google.maps.Map | null>(null);
  const [showTraffic, setShowTraffic] = useState(false);
  const [showTransit, setShowTransit] = useState(false);

  useMapLayers(mapInstance, {
    traffic: showTraffic,
    transit: showTransit,
  });

  return (
    <div>
      <label>
        <input
          type="checkbox"
          checked={showTraffic}
          onChange={e => setShowTraffic(e.target.checked)}
        />
        Traffic
      </label>
      {/* map container */}
    </div>
  );
}
```

### Via `Map` Component (Recommended)

The `Map` component accepts a `layers` prop that internally uses `useMapLayers`:

```tsx
import { Map } from 'xertica-ui/ui';

<Map
  center={{ lat: -23.5505, lng: -46.6333 }}
  zoom={12}
  layers={{
    traffic: true,
    transit: false,
    bicycling: false,
  }}
/>;
```

---

## Behavior

- **Reactive**: Layers are added or removed automatically when the `layers` config changes.
- **Cleanup**: Each layer is removed from the map on component unmount (via `useEffect` cleanup).
- **Null-safe**: If `map` is `null`, the hook does nothing. This is safe to use before the map instance is ready.
- **Singleton layers**: Each layer type is created once and reused (stored in refs). Toggling a layer on/off does not create new instances.

---

## Prerequisites

The Google Maps JavaScript API must be loaded before using this hook. Use `GoogleMapsLoader` or `XerticaProvider` with a `googleMapsApiKey`:

```tsx
import { XerticaProvider } from 'xertica-ui/brand';

<XerticaProvider googleMapsApiKey="YOUR_API_KEY">
  <App />
</XerticaProvider>;
```

---

## AI Rules

> [!IMPORTANT]
>
> - **Use via `Map` component when possible**: The `Map` component's `layers` prop is the recommended way to enable overlays. Use `useMapLayers` directly only when building a custom map integration.
> - **Requires Google Maps API**: This hook uses `google.maps.TrafficLayer`, `google.maps.TransitLayer`, and `google.maps.BicyclingLayer`. These are only available after the Maps JavaScript API is loaded.
> - **Pass `null` safely**: If the map instance is not yet available, pass `null` as the first argument. The hook will skip all operations until a valid map is provided.

--- END COMPONENT: MAP-LAYERS ---


--- START COMPONENT: MAP ---
# Map

## Overview

`Map` renders an interactive Google Map with advanced markers, optional rich info windows, circles, polygons, and native overlay layers. It uses the built-in Xertica Google Maps loader and renders a safe configuration state when no API key is available.

---

## Import

```tsx
import {
  Map,
  GoogleMapsLoaderProvider,
  useGoogleMapsLoader,
  useMapLayers,
  GOOGLE_MAPS_ID,
  GOOGLE_MAPS_LIBRARIES,
  type MapLayersConfig,
} from 'xertica-ui/ui';
```

---

## Prerequisites

- Import `xertica-ui/style.css` once at the app root.
- Provide a Google Maps JavaScript API key through `apiKey`, `VITE_GOOGLE_MAPS_API_KEY`, storage, or `<XerticaProvider googleMapsApiKey="...">`.
- If no key is configured, the component renders a non-crashing setup prompt.

---

## Props

| Prop        | Type                             | Default   | Description                                               |
| ----------- | -------------------------------- | --------- | --------------------------------------------------------- |
| `center`    | `{ lat: number; lng: number }`   | Sao Paulo | Initial map center coordinates.                           |
| `zoom`      | `number`                         | `12`      | Initial zoom level.                                       |
| `markers`   | `MapMarker[]`                    | `[]`      | Markers to display.                                       |
| `circle`    | `object`                         | -         | Optional circle overlay.                                  |
| `polygon`   | `object`                         | -         | Optional polygon overlay.                                 |
| `layers`    | `MapLayersConfig`                | `{}`      | Native layer toggles for traffic, transit, and bicycling. |
| `height`    | `string`                         | `"400px"` | Container height.                                         |
| `apiKey`    | `string`                         | -         | Per-component Google Maps API key override.               |
| `onMapLoad` | `(map: google.maps.Map) => void` | -         | Receives the underlying map instance.                     |

---

## Public Utilities

`useMapLayers(map, layers)` is public for advanced integrations that already own a `google.maps.Map` instance.

`GOOGLE_MAPS_ID` and `GOOGLE_MAPS_LIBRARIES` are public constants for integrations that need to inspect or align with the built-in loader.

---

## Example

```tsx
import { Map } from 'xertica-ui/ui';

<Map
  center={{ lat: -23.5505, lng: -46.6333 }}
  zoom={12}
  height="420px"
  markers={[
    {
      position: { lat: -23.5505, lng: -46.6333 },
      title: 'Xertica',
      info: 'Main office',
    },
  ]}
  layers={{ traffic: true }}
/>;
```

---

## AI Rules

- Always set visible height through `height` or layout constraints.
- Do not install another Google Maps script loader; use `GoogleMapsLoaderProvider` or `XerticaProvider`.
- Use `{ lat, lng }` coordinates, never `{ latitude, longitude }`.
- For standalone usage, pass `apiKey` directly or rely on `VITE_GOOGLE_MAPS_API_KEY`.

--- END COMPONENT: MAP ---


--- START COMPONENT: MARKDOWN-MESSAGE ---
# MarkdownMessage

The primary renderer for AI-generated text content within the Xertica Assistant. It converts raw Markdown into themed React components with support for syntax highlighting, lists, and tables.

---

## Import

```tsx
import { MarkdownMessage } from 'xertica-ui/assistant';
```

---

## Usage

```tsx
<MarkdownMessage content="# Hello\nThis is **bold** text and [a link](https://xertica.com)." />
```

---

## Props

| Prop        | Type     | Default      | Description                             |
| ----------- | -------- | ------------ | --------------------------------------- |
| `content`   | `string` | _(required)_ | The raw markdown string to render.      |
| `className` | `string` | —            | Optional CSS classes for the container. |

---

## Features

- **Syntax Highlighting**: Automatically uses `CodeBlock` for triple-backtick code segments.
- **Themed Typography**: Maps Markdown headers (`h1`-`h4`), blockquotes, and lists to the Xertica UI design system tokens.
- **GFM Tables**: Renders GitHub Flavored Markdown tables (`| col | col |`) as styled `<table>` elements using design system tokens (`border-border`, `hover:bg-muted/50`, `rounded-[var(--radius)]`). Wraps in `overflow-x-auto` for responsive behavior. Cell content supports inline formatting (bold, italic, code).
- **Link Safety**: Automatically adds `target="_blank"` and `rel="noopener noreferrer"` to external links.
- **Scroll Optimized**: Designed to be used inside the messaging list of the `XerticaAssistant`.

---

## AI Rules

> [!IMPORTANT]
>
> - **Streaming Support**: This component can be updated incrementally as a stream of text arrives from an LLM.
> - **Escape HTML**: Ensure the content passed here is sanitized or comes from a trusted AI source, as it renders HTML-like structures via markdown.

--- END COMPONENT: MARKDOWN-MESSAGE ---


--- START COMPONENT: MENUBAR ---
# Menubar

## Overview

An application-style horizontal menu bar with multiple dropdown menus — similar to the menu bars in desktop applications (File, Edit, View…). Less common in web apps but useful for power-user tools and editors.

---

## When to Use

- Rich text editors, code editors, or complex tools
- Applications targeting power users who expect desktop application conventions

## When NOT to Use

- Standard management dashboards — use `<Sidebar>` for navigation.
- Single-level navigation — use `<NavigationMenu>` or `<Tabs>`.

---

## Anatomy

```
<Menubar>
  <MenubarMenu>
    <MenubarTrigger>File</MenubarTrigger>
    <MenubarContent>
      <MenubarItem>New</MenubarItem>
      <MenubarItem>Open</MenubarItem>
      <MenubarSeparator />
      <MenubarItem>Export</MenubarItem>
    </MenubarContent>
  </MenubarMenu>
</Menubar>
```

---

## Examples

```tsx
import {
  Menubar,
  MenubarContent,
  MenubarItem,
  MenubarMenu,
  MenubarSeparator,
  MenubarShortcut,
  MenubarTrigger,
} from 'xertica-ui/ui';

<Menubar>
  <MenubarMenu>
    <MenubarTrigger>File</MenubarTrigger>
    <MenubarContent>
      <MenubarItem>
        New Tab <MenubarShortcut>⌘T</MenubarShortcut>
      </MenubarItem>
      <MenubarItem>
        New Window <MenubarShortcut>⌘N</MenubarShortcut>
      </MenubarItem>
      <MenubarSeparator />
      <MenubarItem>Export...</MenubarItem>
    </MenubarContent>
  </MenubarMenu>
  <MenubarMenu>
    <MenubarTrigger>Edit</MenubarTrigger>
    <MenubarContent>
      <MenubarItem>
        Cut <MenubarShortcut>⌘X</MenubarShortcut>
      </MenubarItem>
      <MenubarItem>
        Copy <MenubarShortcut>⌘C</MenubarShortcut>
      </MenubarItem>
      <MenubarItem>
        Paste <MenubarShortcut>⌘V</MenubarShortcut>
      </MenubarItem>
    </MenubarContent>
  </MenubarMenu>
</Menubar>;
```

---

## AI Rules

- Use `<MenubarShortcut>` for keyboard shortcut labels — always inside the item, right-aligned.
- Destructive items use `className="text-destructive"`.
- `Menubar` is rarely used in management dashboards — `Sidebar` + `DropdownMenu` are the standard substitutes.

--- END COMPONENT: MENUBAR ---


--- START COMPONENT: MODERN-CHAT-INPUT ---
# ModernChatInput

An advanced floating chat input with rich action chips, voice recording simulation, and file attachment support. Used as the primary input interface inside `XerticaAssistant`.

---

## Import

```tsx
import { ModernChatInput } from 'xertica-ui/assistant';
```

---

## Basic Usage

```tsx
const [message, setMessage] = useState('');

<ModernChatInput
  value={message}
  onChange={setMessage}
  onSubmit={() => {
    console.log('Sending:', message);
    setMessage('');
  }}
/>;
```

---

## Props

| Prop                      | Type                            | Default                               | Description                                                 |
| ------------------------- | ------------------------------- | ------------------------------------- | ----------------------------------------------------------- |
| `value`                   | `string`                        | _(required)_                          | Current input text value                                    |
| `onChange`                | `(value: string) => void`       | _(required)_                          | Callback fired on every keystroke                           |
| `onSubmit`                | `(action?: ActionType) => void` | _(required)_                          | Callback fired when user submits (Enter key or send button) |
| `placeholder`             | `string`                        | `'Mande uma mensagem para o Xertica'` | Input placeholder text                                      |
| `disabled`                | `boolean`                       | `false`                               | Disables the input and all action buttons                   |
| `onFileUpload`            | `() => void`                    | —                                     | Callback for the file attachment button                     |
| `onAudioUpload`           | `() => void`                    | —                                     | Callback for the audio upload button                        |
| `onVoiceRecording`        | `(transcript: string) => void`  | —                                     | Callback fired when voice recording finishes                |
| `isFullPage`              | `boolean`                       | `false`                               | Adjusts layout for full-page assistant view                 |
| `enableAudioInput`        | `boolean`                       | `true`                                | Shows/hides the voice recording button                      |
| `enableFileAttachment`    | `boolean`                       | `true`                                | Shows/hides the file attachment button                      |
| `enableDocumentCreation`  | `boolean`                       | `true`                                | Shows/hides the "Create document" action chip               |
| `enablePodcastGeneration` | `boolean`                       | `true`                                | Shows/hides the "Generate podcast" action chip              |
| `enableSearch`            | `boolean`                       | `true`                                | Shows/hides the "Search" action chip                        |

---

## `ActionType`

The `onSubmit` callback receives an optional `ActionType` parameter indicating which special action was triggered:

```tsx
type ActionType = 'document' | 'podcast' | 'search' | null;
```

| Value        | Trigger                  | Description                           |
| ------------ | ------------------------ | ------------------------------------- |
| `null`       | Enter key or send button | Standard text message                 |
| `'document'` | "Create document" chip   | Triggers document generation workflow |
| `'podcast'`  | "Generate podcast" chip  | Triggers audio podcast generation     |
| `'search'`   | "Search" chip            | Triggers knowledge base search        |

### Handling Actions

```tsx
<ModernChatInput
  value={message}
  onChange={setMessage}
  onSubmit={action => {
    if (action === 'document') {
      // trigger document generation
    } else if (action === 'podcast') {
      // trigger podcast generation
    } else if (action === 'search') {
      // trigger search
    } else {
      // send regular message
    }
    setMessage('');
  }}
/>
```

---

## Features

### Auto-Resizing Textarea

The input grows vertically as the user types, up to a maximum height of 100px. Beyond that, it becomes scrollable.

### Action Chips

A `+` button opens a popover with quick-action chips:

- **Document** (`FileText` icon) — triggers `onSubmit('document')`
- **Podcast** (`Radio` icon) — triggers `onSubmit('podcast')`
- **Search** (`Search` icon) — triggers `onSubmit('search')`

Each chip can be individually disabled via props.

### Voice Recording (Simulated)

When `enableAudioInput={true}`, a microphone button is shown. Clicking it:

1. Shows a recording indicator with a pulsing animation
2. After 3 seconds, calls `onVoiceRecording` with a simulated transcript string
3. Returns to idle state

> **Note**: Voice recording is simulated — it does not use the browser's MediaRecorder API. The transcript returned is a placeholder string for UI demonstration purposes.

### Keyboard Shortcuts

- **Enter** — submits the message
- **Shift+Enter** — inserts a newline (multi-line input)

---

## Usage with XerticaAssistant

`ModernChatInput` is used internally by `XerticaAssistant`. You typically do not need to use it directly unless building a custom chat interface:

```tsx
import { ModernChatInput } from 'xertica-ui/assistant';
import { useAssistant } from 'xertica-ui/assistant'; // internal hook

function CustomChatInterface() {
  const [message, setMessage] = useState('');

  const handleSubmit = (action?: ActionType) => {
    // handle message or action
    setMessage('');
  };

  return (
    <div className="flex flex-col h-screen">
      <div className="flex-1 overflow-y-auto">{/* messages */}</div>
      <ModernChatInput
        value={message}
        onChange={setMessage}
        onSubmit={handleSubmit}
        isFullPage={true}
      />
    </div>
  );
}
```

---

## AI Rules

> [!IMPORTANT]
>
> - **Controlled component**: Always provide both `value` and `onChange`. This is a controlled input — do not use it uncontrolled.
> - **Clear after submit**: Call `setMessage('')` (or equivalent) inside `onSubmit` to reset the input after sending.
> - **`isFullPage` for page layouts**: Set `isFullPage={true}` when using the input in a full-page assistant view (not the sidebar panel). This adjusts padding and max-width.
> - **Voice recording is simulated**: Do not rely on `onVoiceRecording` for real speech-to-text. Integrate a real STT service and pass the transcript via `onChange` instead.
> - **Disable unused actions**: If your application does not support document generation or podcasts, set `enableDocumentCreation={false}` and `enablePodcastGeneration={false}` to avoid confusing users.

--- END COMPONENT: MODERN-CHAT-INPUT ---


--- START COMPONENT: NAVIGATION-MENU ---
# Navigation Menu

## Overview

A horizontal navigation bar designed for top-level application sections. Supports dropdown sub-menus with rich content panels. Use it as a secondary top navigation when the primary navigation is in the `<Sidebar>`. Built on Radix UI NavigationMenu.

---

## When to Use

- Horizontal navigation between top-level sections in a webapp or marketing site
- When combined with the Sidebar for secondary navigation categories

## When NOT to Use

- Primary app navigation — use `<Sidebar>` for that.
- Simple links — use plain `<a>` or `<Button>` with `asChild`.

---

## Anatomy

```
<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Getting Started</NavigationMenuTrigger>
      <NavigationMenuContent>
        {/* Rich dropdown content */}
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuLink href="/docs">Docs</NavigationMenuLink>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>
```

---

## Examples

```tsx
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
} from 'xertica-ui/ui';

<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Products</NavigationMenuTrigger>
      <NavigationMenuContent>
        <div className="grid gap-3 p-4 w-[300px]">
          <div className="space-y-1">
            <h4 className="text-sm font-medium">Analytics</h4>
            <p className="text-xs text-muted-foreground">Real-time data insights</p>
          </div>
          <div className="space-y-1">
            <h4 className="text-sm font-medium">AI Assistant</h4>
            <p className="text-xs text-muted-foreground">Integrated AI workflows</p>
          </div>
        </div>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuLink href="/pricing">Pricing</NavigationMenuLink>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>;
```

---

## AI Rules

- `NavigationMenu` is for **horizontal marketing/secondary navigation** — not for dashboard left-rail navigation (use `Sidebar`).
- `NavigationMenuContent` renders in a portal — ensure `XerticaProvider` wraps the app.
- Use `NavigationMenuLink` for simple links; use `NavigationMenuTrigger` + `NavigationMenuContent` for dropdown sub-menus.

--- END COMPONENT: NAVIGATION-MENU ---


--- START COMPONENT: NOTIFICATION-BADGE ---
# Notification Badge

## Overview

A small overlay indicator that appears on top of another element (typically an icon button) to communicate an unread count or attention cue. Appears as a colored dot (attention) or a numbered badge (count).

---

## When to Use

- Notification bell icons in the header with unread count
- Navigation items with pending action counts
- Tab indicators with item counts

---

## Props

| Prop        | Type                                                                                         | Default         | Required | Description                                             |
| ----------- | -------------------------------------------------------------------------------------------- | --------------- | -------- | ------------------------------------------------------- |
| `count`     | `number`                                                                                     | `0`             | No       | Number to display                                       |
| `max`       | `number`                                                                                     | `99`            | No       | Maximum count to display (shows `{max}+` when exceeded) |
| `dot`       | `boolean`                                                                                    | `false`         | No       | Renders a dot indicator instead of a count badge        |
| `showZero`  | `boolean`                                                                                    | `false`         | No       | Show the badge even when count is 0                     |
| `variant`   | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'success' \| 'info' \| 'warning'` | `'destructive'` | No       | Color variant                                           |
| `className` | `string`                                                                                     | —               | No       | Additional classes                                      |

---

## Examples

### Notification Bell with Count

```tsx
import { NotificationBadge, Button } from 'xertica-ui/ui';
import { Bell } from 'lucide-react';

<NotificationBadge count={3} variant="destructive">
  <Button variant="ghost" size="icon" aria-label="Notifications">
    <Bell className="size-4" />
  </Button>
</NotificationBadge>;
```

### Dot Indicator

```tsx
import { Mail } from 'lucide-react';

<NotificationBadge dot variant="success">
  <Button variant="ghost" size="icon" aria-label="Messages">
    <Mail className="size-4" />
  </Button>
</NotificationBadge>;
```

### Status Variants

```tsx
<NotificationBadge count={5} variant="info">...</NotificationBadge>
<NotificationBadge count={2} variant="warning">...</NotificationBadge>
<NotificationBadge count={1} variant="success">...</NotificationBadge>
```

---

## AI Rules

- Always wrap the target element as a child — the badge positions itself automatically in the top-right corner.
- When count is `0`, prefer not rendering the badge at all rather than showing `0` (use `showZero` to override).
- Maximum display value defaults to `99` — showing `99+` instead of large numbers.
- For standalone status labels (not overlays), use `<Badge>` instead.

---

## Related Components

- [`Badge`](./badge.md) — For standalone inline status labels

--- END COMPONENT: NOTIFICATION-BADGE ---


--- START COMPONENT: PAGE-HEADER ---
# PageHeader

## Overview

The `PageHeader` is a content-level component used to provide immediate context for a specific page or section. It focuses on the page title, subtitle, back navigation, and primary local actions (like "Create" or "Edit").

**Important:** This is NOT the global Top Bar. For the global application header with profile and system breadcrumbs, use the [`Header`](./header.md) component.

---

## Key Features

- **Primary Heading**: Standardized `h1` styling with optional subtitle.
- **Back Navigation**: Built-in back button with support for standard links (`backHref`) or programmatic handlers (`onBack`).
- **Local Actions**: Dedicated area on the right for primary page controls (Buttons, Dropdowns, etc.).
- **Typography Primitives**: Exports `PageHeaderHeading` and `PageHeaderDescription` for building custom header layouts.

---

## When to Use

- Use at the top of the **content area** of every main page.
- Perfect for detail pages, forms, or any view that requires a clear title and a "Back" button.

---

## Props

| Prop        | Type              | Default | Required | Description                                                             |
| ----------- | ----------------- | ------- | -------- | ----------------------------------------------------------------------- |
| `title`     | `string`          | —       | **Yes**  | The primary H1 title for the page.                                      |
| `subtitle`  | `string`          | —       | No       | Secondary description or context text.                                  |
| `backHref`  | `string`          | —       | No       | Relative URL for the back button. If provided, renders as an `<a>` tag. |
| `onBack`    | `() => void`      | —       | No       | Click handler for the back button.                                      |
| `actions`   | `React.ReactNode` | —       | No       | Buttons or controls to render on the right side.                        |
| `className` | `string`          | —       | No       | Additional CSS classes for the container.                               |

---

## Examples

### Standard Usage

```tsx
import { PageHeader, Button } from 'xertica-ui/ui';
import { Plus } from 'lucide-react';

<PageHeader
  title="Users"
  subtitle="Manage and invite members to your workspace."
  actions={
    <Button size="sm">
      <Plus className="mr-2 size-4" /> Add User
    </Button>
  }
/>;
```

### With Back Navigation

```tsx
import { PageHeader } from 'xertica-ui/ui';

<PageHeader title="Edit Profile" backHref="/settings" />;
```

### Custom Typography

```tsx
import { PageHeaderHeading, PageHeaderDescription } from 'xertica-ui/ui';

<section>
  <PageHeaderHeading>Analytics Overview</PageHeaderHeading>
  <PageHeaderDescription>Detailed metrics for your current project.</PageHeaderDescription>
</section>;
```

---

## AI Rules

- **SEO** — Always provide a meaningful `title`. This component renders the page's primary `h1`.
- **Navigation** — If the page is a sub-view, always provide `backHref` or `onBack` to maintain intuitive UX.
- **Hierarchy** — Place the `PageHeader` immediately after the global `Header` within the main content container.
- **Actions** — Keep the number of `actions` limited (ideally 1-3 buttons) to prevent crowding on mobile.

---

## Related Components

- [`Header`](./header.md) — The global application toolbar.
- [`Button`](./button.md) — Commonly used within the `actions` prop.
- [`Breadcrumb`](./breadcrumb.md) — Should be used in the global `Header`, not here.

--- END COMPONENT: PAGE-HEADER ---


--- START COMPONENT: PAGES ---
# Page Templates — Xertica UI

Xertica UI ships 8 ready-to-use page templates covering authentication flows, the main dashboard shell, and a fully-featured component showcase. All templates are exported from `xertica-ui/pages`.

---

## Import

```tsx
import {
  LoginPage,
  ForgotPasswordPage,
  ResetPasswordPage,
  VerifyEmailPage,
  HomePage,
  HomeContent,
  TemplatePage,
  TemplateContent,
} from 'xertica-ui/pages';
```

---

## Authentication Pages

### `LoginPage`

A complete, responsive login screen with a hero image side-panel (desktop) and a focused authentication form.

**Features:**

- Email + password form with validation
- Loading state during submission
- Error message display
- Social/SSO provider placeholders (Google, MT Login, gov.br)
- Language selector (`LanguageSelector`)
- Xertica logo
- Link to forgot-password flow (via `react-router-dom`)

**Props:**

| Prop      | Type                                           | Description                                                                 |
| --------- | ---------------------------------------------- | --------------------------------------------------------------------------- |
| `onLogin` | `(email: string, password: string) => boolean` | Authentication handler. Return `true` on success, `false` to show an error. |

**Usage:**

```tsx
import { LoginPage } from 'xertica-ui/pages';
import { useNavigate } from 'react-router-dom';

function AuthRoute() {
  const navigate = useNavigate();

  const handleLogin = (email: string, password: string): boolean => {
    if (!email || !password) return false;
    // call your auth API here
    navigate('/home');
    return true;
  };

  return <LoginPage onLogin={handleLogin} />;
}
```

---

### `ForgotPasswordPage`

A password recovery form where users enter their email to receive a reset link.

**Features:**

- Email input with validation
- Success state (shows confirmation message after submission)
- Back-to-login navigation link
- Xertica logo + hero image

**Props:**

| Prop       | Type                      | Description                                    |
| ---------- | ------------------------- | ---------------------------------------------- |
| `onSubmit` | `(email: string) => void` | Called when the user submits the recovery form |

**Usage:**

```tsx
import { ForgotPasswordPage } from 'xertica-ui/pages';

<ForgotPasswordPage
  onSubmit={email => {
    // send password reset email
    console.log('Reset requested for:', email);
  }}
/>;
```

---

### `ResetPasswordPage`

A new-password form for users arriving via a password reset link.

**Features:**

- New password + confirm password fields
- Password match validation
- Success state after reset

**Props:**

| Prop      | Type                         | Description                                             |
| --------- | ---------------------------- | ------------------------------------------------------- |
| `onReset` | `(password: string) => void` | Called with the new password when the form is submitted |

**Usage:**

```tsx
import { ResetPasswordPage } from 'xertica-ui/pages';

<ResetPasswordPage
  onReset={newPassword => {
    // call your reset API with the token from the URL
    console.log('New password:', newPassword);
  }}
/>;
```

---

### `VerifyEmailPage`

An email verification confirmation screen shown after registration.

**Features:**

- Confirmation message with email address display
- "Resend email" action
- Back-to-login link

**Props:**

| Prop       | Type         | Description                                              |
| ---------- | ------------ | -------------------------------------------------------- |
| `email`    | `string`     | The email address to display in the confirmation message |
| `onResend` | `() => void` | Called when the user clicks "Resend verification email"  |

**Usage:**

```tsx
import { VerifyEmailPage } from 'xertica-ui/pages';

<VerifyEmailPage
  email="user@example.com"
  onResend={() => {
    // resend verification email
  }}
/>;
```

---

## Dashboard Pages

### `HomePage`

The root dashboard page. Assembles `Sidebar`, `HomeContent`, and `XerticaAssistant` into a full-screen layout.

**Features:**

- Full-screen `h-screen` layout with sidebar + main content + assistant
- Integrates `LayoutContext` for synchronized sidebar/assistant state
- Auth state from `useAuth()` — **no `user` or `onLogout` props needed**
- `XerticaAssistant` config (suggestions, feedback options) fetched via `useAssistantConfig()` (React Query)

**Props:** none — all state consumed from `AuthContext` and React Query.

**Usage:**

```tsx
import { HomePage } from 'xertica-ui/pages';

// Inside <AuthProvider> and <QueryClientProvider>
<Route
  path="/home"
  element={
    <ProtectedRoute>
      <HomePage />
    </ProtectedRoute>
  }
/>;
```

> **Note**: `HomePage` uses `react-router-dom` hooks internally. It must be rendered inside a `<BrowserRouter>` (or equivalent) and inside `<AuthProvider>`.

---

### `HomeContent`

The main content area of the dashboard. Feature cards are fetched via `useFeatureCards()` (React Query) — no hardcoded data.

**Features:**

- `Header` with breadcrumbs, theme toggle, and language selector
- Feature card grid — data from `features/home/hooks/useFeatureCards.ts`
- Skeleton loading state while query is in-flight

**Props:** none — layout from `useLayout()`, data from React Query.

**Usage:**

```tsx
import { HomeContent } from 'xertica-ui/pages';

// Self-contained — no props required
<HomeContent />;
```

---

### `TemplatePage`

A complete layout shell identical to `HomePage` but with `TemplateContent` as the main area. Use this as the **primary reference** for building new pages.

**Features:**

- Full-screen layout: Sidebar + TemplateContent + XerticaAssistant
- Auth state from `useAuth()` — **no props needed**
- Synchronized layout state via `LayoutContext`

**Props:** none.

**Usage:**

```tsx
import { TemplatePage } from 'xertica-ui/pages';

<Route
  path="/template"
  element={
    <ProtectedRoute>
      <TemplatePage />
    </ProtectedRoute>
  }
/>;
```

---

### `TemplateContent`

The main content area of `TemplatePage`. Contains a comprehensive showcase of all Xertica UI components.

**Features:**

- `Header` with full breadcrumb, user menu, and action buttons
- All form elements (Input, Select, Checkbox, Switch, Slider, etc.)
- Data display: Table with team members from `useTeamMembers()` (React Query)
- UI toggles (progress, slider, switch) from `useDashboardStore` (Zustand)
- Overlay components (Dialog, Sheet, Drawer, Popover, Tooltip)
- Media components (AudioPlayer, VideoPlayer)
- AI components (XerticaAssistant in full-page mode)

**Props:** none — all state from React Query hooks and Zustand store.

---

## Page Architecture Pattern

All dashboard pages follow the same three-column layout pattern:

```
┌─────────────────────────────────────────────────────┐
│  Sidebar  │         Main Content          │Assistant │
│  (fixed)  │  Header + scrollable body     │ (fixed)  │
└─────────────────────────────────────────────────────┘
```

```tsx
// Standard page shell — auth from context, data from React Query
function MyPage() {
  const { user, logout } = useAuth(); // ← no prop drilling
  const { data: myData } = useMyFeatureQuery(); // ← React Query
  const { sidebarExpanded, sidebarWidth, assistenteExpanded, toggleSidebar, toggleAssistente } =
    useLayout();
  const location = useLocation();
  const navigate = useNavigate();

  return (
    <div className="h-screen flex bg-muted overflow-hidden relative">
      <Sidebar
        expanded={sidebarExpanded}
        width={sidebarWidth}
        onToggle={toggleSidebar}
        user={{ ...user, name: 'Display Name', avatar: '...' }}
        onLogout={logout}
        location={location}
        navigate={navigate}
        routes={routes}
      />
      <MyContent data={myData} />
      <XerticaAssistant isExpanded={assistenteExpanded} onToggle={toggleAssistente} demoMode />
    </div>
  );
}
```

---

## AI Rules

> [!IMPORTANT]
>
> - **`user` and `onLogout` are NOT props on `HomePage` or `TemplatePage`**: They are consumed via `useAuth()` from `AuthContext`. Never pass `user` or `onLogout` as props to these components.
> - **Use `TemplatePage` as the reference**: When building a new page, copy the structure from `TemplatePage` — it demonstrates the correct three-column layout with synchronized state.
> - **Router dependency**: All dashboard pages use `useLocation` and `useNavigate` from `react-router-dom`. They must be rendered inside a `<BrowserRouter>`.
> - **`LayoutContext` is optional**: Pages use `useOptionalLayout()` and fall back to local state if the context is not available. This allows standalone usage in Storybook or tests.
> - **Authentication pages are standalone**: `LoginPage`, `ForgotPasswordPage`, `ResetPasswordPage`, and `VerifyEmailPage` do not use `LayoutContext` and can be rendered without `XerticaProvider`.
> - **Data comes from `features/`**: All server data (team members, stats, feature cards, assistant config) is fetched via React Query hooks in `features/*/hooks/`. Never hardcode this data in components.
> - **Do not add business logic to page shells**: Page components (`HomePage`, `TemplatePage`) are thin layout containers. Business logic and data fetching belong in `features/*/hooks/` or content components.
> - **`LoginPage` still accepts `onLogin` prop**: It is a reusable library component decoupled from `AuthContext`. Use a bridge wrapper (e.g., `LoginPageWithAuth`) that reads `useAuth().login` and passes it as `onLogin`.
> - **Wrap route entries in `<PageErrorBoundary>`**: Place `<PageErrorBoundary>` around `<Routes>` / `<AuthGuard>` so that lazy-chunk load failures and page render errors show a recoverable fallback instead of a blank screen.
> - **Wrap data-heavy sections in `<SectionErrorBoundary>`**: Any section that renders server data (tables, charts, the assistant panel) must be wrapped in `<SectionErrorBoundary>`. An error in one section must not crash the entire page.

--- END COMPONENT: PAGES ---


--- START COMPONENT: PAGINATION ---
# Pagination

## Overview

A navigation control for moving through pages of a large dataset. Renders Previous/Next buttons, numbered page buttons, and ellipsis for large page counts. Use it below data tables to control which page of records is displayed.

The package also exports a **headless `usePagination` hook** that computes the full page item list (numbers + ellipsis) and exposes navigation helpers — use it when you need full control over the pagination UI.

---

## Exports

| Export                | Description                                    |
| --------------------- | ---------------------------------------------- |
| `Pagination`          | Root nav wrapper                               |
| `PaginationContent`   | Flex container for all items                   |
| `PaginationItem`      | Individual item wrapper                        |
| `PaginationLink`      | Numbered page button                           |
| `PaginationPrevious`  | "Previous" button with left arrow              |
| `PaginationNext`      | "Next" button with right arrow                 |
| `PaginationEllipsis`  | "..." indicator for skipped pages              |
| `usePagination`       | Headless hook — all logic, no UI               |
| `UsePaginationProps`  | TypeScript props type for the hook             |
| `UsePaginationReturn` | TypeScript return type for the hook            |
| `PaginationPageItem`  | Union type for page items returned by the hook |

---

## When to Use

- Below tables with more records than fit on one page
- Any paginated list or grid of content

---

## Anatomy

```
<Pagination>
  <PaginationContent>
    <PaginationItem><PaginationPrevious href="#" /></PaginationItem>
    <PaginationItem><PaginationLink href="#">1</PaginationLink></PaginationItem>
    <PaginationItem><PaginationEllipsis /></PaginationItem>
    <PaginationItem><PaginationLink href="#" isActive>5</PaginationLink></PaginationItem>
    <PaginationItem><PaginationNext href="#" /></PaginationItem>
  </PaginationContent>
</Pagination>
```

---

## Sub-Components

| Component            | Description                       |
| -------------------- | --------------------------------- |
| `Pagination`         | Root nav wrapper                  |
| `PaginationContent`  | Flex container for all items      |
| `PaginationItem`     | Individual item wrapper           |
| `PaginationLink`     | Numbered page button              |
| `PaginationPrevious` | "Previous" button with left arrow |
| `PaginationNext`     | "Next" button with right arrow    |
| `PaginationEllipsis` | "..." indicator for skipped pages |

---

## Props

### PaginationLink

| Prop       | Type         | Description                                                                                                                          |
| ---------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `href`     | `string`     | URL for the page                                                                                                                     |
| `isActive` | `boolean`    | When `true`, renders as the active page                                                                                              |
| `disabled` | `boolean`    | When `true`, renders as non-interactive: removes `href`, sets `aria-disabled`, `tabIndex={-1}`, and `pointer-events-none opacity-50` |
| `onClick`  | `() => void` | Click handler (for controlled pagination)                                                                                            |

### PaginationPrevious / PaginationNext

Both components accept and forward a `disabled` prop to `PaginationLink`. Pass `disabled={!canGoPrev}` / `disabled={!canGoNext}` to disable the controls when at the first or last page — this is the preferred pattern over `aria-disabled` alone.

---

## Examples

### Controlled Pagination

```tsx
import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
  PaginationEllipsis,
} from 'xertica-ui/ui';
import { useState } from 'react';

const [currentPage, setCurrentPage] = useState(1);
const totalPages = 10;

<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious onClick={() => setCurrentPage(p => Math.max(1, p - 1))} />
    </PaginationItem>
    {[1, 2, 3].map(page => (
      <PaginationItem key={page}>
        <PaginationLink isActive={currentPage === page} onClick={() => setCurrentPage(page)}>
          {page}
        </PaginationLink>
      </PaginationItem>
    ))}
    <PaginationItem>
      <PaginationEllipsis />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink onClick={() => setCurrentPage(totalPages)}>{totalPages}</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationNext onClick={() => setCurrentPage(p => Math.min(totalPages, p + 1))} />
    </PaginationItem>
  </PaginationContent>
</Pagination>;
```

---

## `usePagination` Hook

A headless hook that computes the full page item list (page numbers + ellipsis markers) and exposes navigation helpers. Supports both **uncontrolled** (internal state) and **controlled** (external `page` prop) modes.

### Props

| Prop           | Type                     | Default | Description                                                                                 |
| -------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------- |
| `totalItems`   | `number`                 | —       | **Required.** Total number of items across all pages                                        |
| `pageSize`     | `number`                 | `10`    | Number of items per page                                                                    |
| `initialPage`  | `number`                 | `1`     | Initial page (uncontrolled mode only)                                                       |
| `page`         | `number`                 | —       | Controlled current page — when provided, the hook uses this value instead of internal state |
| `onPageChange` | `(page: number) => void` | —       | Called whenever the page changes                                                            |
| `siblingCount` | `number`                 | `1`     | Number of page buttons to show on each side of the current page                             |

### Return Value

| Property      | Type                     | Description                                                       |
| ------------- | ------------------------ | ----------------------------------------------------------------- |
| `currentPage` | `number`                 | The currently active page (1-indexed)                             |
| `totalPages`  | `number`                 | Total number of pages                                             |
| `startIndex`  | `number`                 | Zero-based index of the first item on the current page            |
| `endIndex`    | `number`                 | Zero-based index of the last item on the current page (exclusive) |
| `canGoPrev`   | `boolean`                | Whether navigating to the previous page is possible               |
| `canGoNext`   | `boolean`                | Whether navigating to the next page is possible                   |
| `isFirstPage` | `boolean`                | Whether the current page is the first page                        |
| `isLastPage`  | `boolean`                | Whether the current page is the last page                         |
| `items`       | `PaginationPageItem[]`   | Ordered list of page items to render (see below)                  |
| `goTo`        | `(page: number) => void` | Navigate to a specific page number                                |
| `next`        | `() => void`             | Navigate to the next page                                         |
| `prev`        | `() => void`             | Navigate to the previous page                                     |
| `first`       | `() => void`             | Navigate to the first page                                        |
| `last`        | `() => void`             | Navigate to the last page                                         |

### `PaginationPageItem` Type

```typescript
type PaginationPageItem = { type: 'page'; page: number } | { type: 'ellipsis'; key: string };
```

The `items` array is ready to render directly — map over it and render `<PaginationLink>` for `type: 'page'` items and `<PaginationEllipsis>` for `type: 'ellipsis'` items.

### Uncontrolled Example

```tsx
import {
  usePagination,
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationPrevious,
  PaginationNext,
  PaginationEllipsis,
} from 'xertica-ui/ui';

function MyTable({ data }: { data: Record<string, unknown>[] }) {
  const { currentPage, startIndex, endIndex, canGoPrev, canGoNext, items, next, prev, goTo } =
    usePagination({ totalItems: data.length, pageSize: 10 });

  const pageData = data.slice(startIndex, endIndex);

  return (
    <div className="space-y-4">
      <table>{/* render pageData rows */}</table>

      <Pagination>
        <PaginationContent>
          <PaginationItem>
            {/* Use disabled prop — not aria-disabled — for full a11y (removes href, tabIndex, pointer-events) */}
            <PaginationPrevious
              href="#"
              onClick={e => {
                e.preventDefault();
                prev();
              }}
              disabled={!canGoPrev}
            />
          </PaginationItem>

          {items.map(item =>
            item.type === 'ellipsis' ? (
              <PaginationItem key={item.key}>
                <PaginationEllipsis />
              </PaginationItem>
            ) : (
              <PaginationItem key={item.page}>
                <PaginationLink
                  href="#"
                  isActive={item.page === currentPage}
                  onClick={e => {
                    e.preventDefault();
                    goTo(item.page);
                  }}
                >
                  {item.page}
                </PaginationLink>
              </PaginationItem>
            )
          )}

          <PaginationItem>
            <PaginationNext
              href="#"
              onClick={e => {
                e.preventDefault();
                next();
              }}
              disabled={!canGoNext}
            />
          </PaginationItem>
        </PaginationContent>
      </Pagination>
    </div>
  );
}
```

> **Page item algorithm (v2.1.9+)**: The `items` array is computed with a `Set`-based deduplication algorithm. Each page number appears exactly once regardless of `siblingCount` and total pages. Ellipsis keys are unique (`ellipsis-{page}`).

### Controlled Example (API-driven pagination)

```tsx
import { usePagination } from 'xertica-ui/ui';
import { useState } from 'react';

function ServerPaginatedTable({ totalItems }: { totalItems: number }) {
  const [page, setPage] = useState(1);

  const { items, canGoPrev, canGoNext, next, prev, goTo, currentPage } = usePagination({
    totalItems,
    pageSize: 20,
    page, // controlled
    onPageChange: setPage,
  });

  // fetch data for `page` from your API...

  return (
    <Pagination>
      <PaginationContent>
        <PaginationItem>
          <PaginationPrevious
            href="#"
            onClick={e => {
              e.preventDefault();
              prev();
            }}
            disabled={!canGoPrev}
          />
        </PaginationItem>
        {items.map(item =>
          item.type === 'ellipsis' ? (
            <PaginationItem key={item.key}>
              <PaginationEllipsis />
            </PaginationItem>
          ) : (
            <PaginationItem key={item.page}>
              <PaginationLink
                href="#"
                isActive={item.page === currentPage}
                onClick={e => {
                  e.preventDefault();
                  goTo(item.page);
                }}
              >
                {item.page}
              </PaginationLink>
            </PaginationItem>
          )
        )}
        <PaginationItem>
          <PaginationNext
            href="#"
            onClick={e => {
              e.preventDefault();
              next();
            }}
            disabled={!canGoNext}
          />
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  );
}
```

---

## AI Rules

- Place Pagination below the `<Table>` inside the same `<Card>` wrapping both.
- Use `isActive` on the currently selected page link.
- **Use `disabled` prop (not `aria-disabled` alone)** on `PaginationPrevious` and `PaginationNext` — `disabled={!canGoPrev}` / `disabled={!canGoNext}`. The `disabled` prop removes `href`, sets `tabIndex={-1}`, `aria-disabled`, and `pointer-events-none opacity-50` simultaneously for full accessibility.
- For controlled pagination (API-driven), use `onClick` with `e.preventDefault()` on `PaginationLink` instead of letting `href="#"` cause a scroll-to-top.
- When using `usePagination`, use `startIndex` and `endIndex` to slice client-side data arrays: `data.slice(startIndex, endIndex)`.
- For server-side pagination, pass `page` and `onPageChange` to `usePagination` to use controlled mode — the hook will not manage internal state.
- Always render `PaginationEllipsis` for `item.type === 'ellipsis'` items from the `items` array — never skip them. Ellipsis keys are unique strings in the form `ellipsis-{page}`.
- `totalItems` is the count of **all** records, not just the current page.
- Pages are **1-indexed** — the first page is `1`, not `0`.

---

## Related Components

- [`Table`](./table.md) — Primary context where Pagination is used

--- END COMPONENT: PAGINATION ---


--- START COMPONENT: POPOVER ---
# Popover

## Overview

A floating panel anchored to a trigger element that presents additional information or controls without navigating away from the current context. Unlike `Tooltip`, Popover content can be interactive — forms, date pickers, settings panels, filter controls.

---

## When to Use

- Inline date pickers (Calendar inside Popover)
- Compact filter panels triggered by a button
- Contextual settings or configuration controls
- Preview panels for complex data that don't need a full Sheet

## When NOT to Use

- Simple text descriptions — use `<Tooltip>` instead.
- Long forms or large content areas — use `<Sheet>` or `<Dialog>` instead.
- Persistent content visible at all times — place inline in the page.

---

## Anatomy

```
<Popover>
  <PopoverTrigger asChild>
    <Button />
  </PopoverTrigger>
  <PopoverContent>
    {/* Interactive content */}
  </PopoverContent>
</Popover>
```

---

## Props

### Popover

| Prop           | Type                      | Description           |
| -------------- | ------------------------- | --------------------- |
| `open`         | `boolean`                 | Controlled open state |
| `onOpenChange` | `(open: boolean) => void` | State handler         |

### PopoverContent

| Prop         | Type                                     | Default    | Description               |
| ------------ | ---------------------------------------- | ---------- | ------------------------- |
| `align`      | `'start' \| 'center' \| 'end'`           | `'center'` | Horizontal alignment      |
| `side`       | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Positioning side          |
| `sideOffset` | `number`                                 | `4`        | Distance from trigger     |
| `className`  | `string`                                 | —          | Width and style overrides |

---

## Examples

### Date Picker Popover

```tsx
import { Popover, PopoverContent, PopoverTrigger, Button, Calendar } from 'xertica-ui/ui';
import { CalendarIcon } from 'lucide-react';
import { useState } from 'react';

const [date, setDate] = useState<Date>();

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline" className="gap-2">
      <CalendarIcon className="size-4" />
      {date ? format(date, 'PPP') : 'Pick a date'}
    </Button>
  </PopoverTrigger>
  <PopoverContent className="w-auto p-0" align="start">
    <Calendar mode="single" selected={date} onSelect={setDate} initialFocus />
  </PopoverContent>
</Popover>;
```

### Filter Panel

```tsx
<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline" className="gap-2">
      <Filter className="size-4" /> Filters
    </Button>
  </PopoverTrigger>
  <PopoverContent className="w-64 p-4">
    <div className="space-y-4">
      <h4 className="font-medium">Filter by Status</h4>
      {/* Filter controls */}
    </div>
  </PopoverContent>
</Popover>
```

---

## AI Rules

- `<PopoverTrigger asChild>` is **required** when the trigger is a `<Button>`.
- For date pickers, always set `className="w-auto p-0"` on `<PopoverContent>` to let the `<Calendar>` define its own size.
- Popover content is lazy-rendered — don't rely on it being in the DOM when the popover is closed.

---

## Related Components

- [`Tooltip`](./tooltip.md) — For non-interactive hover hints
- [`HoverCard`](./hover-card.md) — For hover-triggered rich previews
- [`Calendar`](./calendar.md) — The most common Popover content
- [`Sheet`](./sheet.md) — For larger panel content

--- END COMPONENT: POPOVER ---


--- START COMPONENT: PROGRESS ---
# Progress

## Overview

A visual indicator of completion or percentage. Renders a horizontal bar filled to a given percentage. It is purely display-only — for interactive value selection, use `<Slider>`.

---

## When to Use

- Upload or download completion
- Onboarding completion percentage
- Task or project progress indicators
- Step completion within a multi-step form

## When NOT to Use

- Interactive range selection — use `<Slider>`.
- Step-by-step processes — use `<Stepper>`.

---

## Variants

| Variant       | Color   | Usage                    |
| ------------- | ------- | ------------------------ |
| `default`     | Primary | General progress         |
| `success`     | Green   | Completed or successful  |
| `info`        | Blue    | Informational progress   |
| `warning`     | Amber   | Nearing limit or caution |
| `destructive` | Red     | Critical or failed state |

---

## Props

| Prop        | Type                                                             | Default     | Required | Description            |
| ----------- | ---------------------------------------------------------------- | ----------- | -------- | ---------------------- |
| `value`     | `number`                                                         | —           | **Yes**  | Progress value (0–100) |
| `variant`   | `'default' \| 'success' \| 'info' \| 'warning' \| 'destructive'` | `'default'` | No       | Semantic color variant |
| `className` | `string`                                                         | —           | No       | Additional CSS classes |

---

## Examples

### Basic Progress Bar

```tsx
import { Progress } from 'xertica-ui/ui';

<Progress value={65} />;
```

### With Label

```tsx
<div className="space-y-2">
  <div className="flex justify-between text-sm">
    <span>Upload Progress</span>
    <span>65%</span>
  </div>
  <Progress value={65} />
</div>
```

### Semantic Variants

```tsx
<Progress value={100} variant="success" />
<Progress value={60} variant="info" />
<Progress value={75} variant="warning" />
<Progress value={30} variant="destructive" />
```

### Animated (within a useEffect)

```tsx
const [value, setValue] = useState(0);

useEffect(() => {
  const timer = setTimeout(() => setValue(66), 500);
  return () => clearTimeout(timer);
}, []);

<Progress value={value} />;
```

---

## AI Rules

- `value` must be between 0 and 100.
- Always pair with a visible label showing the percentage — the bar alone is difficult to interpret.
- Use `variant` to communicate semantic state: `success` when complete, `warning` when nearing a limit, `destructive` for failures.
- The `Progress` bar does not have an interactive thumb — never confuse it with `Slider`.

---

## Related Components

- [`Slider`](./slider.md) — For interactive range selection
- [`Stepper`](./stepper.md) — For multi-step process indication

--- END COMPONENT: PROGRESS ---


--- START COMPONENT: RADIO-GROUP ---
# RadioGroup

## Overview

A set of mutually exclusive options where selecting one automatically deselects all others. Built on Radix UI with full keyboard navigation (arrow keys cycle through options). Use when only one choice from a defined set is valid.

---

## When to Use

- Mutually exclusive configuration options (2–6 items)
- Plan selection (Basic / Pro / Enterprise)
- Response type selection in forms
- Gender, salutation, or category selectors when options are few and fixed

## When NOT to Use

- More than 6 options — use `<Select>` instead.
- Multiple simultaneous selections — use `<Checkbox>` instead.

---

## Anatomy

```
<RadioGroup>
  <div className="flex items-center space-x-2">
    <RadioGroupItem value="option-a" id="option-a" />
    <Label htmlFor="option-a">Option A</Label>
  </div>
</RadioGroup>
```

---

## Props

### RadioGroup

| Prop            | Type                         | Default      | Description                |
| --------------- | ---------------------------- | ------------ | -------------------------- |
| `value`         | `string`                     | —            | Controlled selected value  |
| `defaultValue`  | `string`                     | —            | Uncontrolled initial value |
| `onValueChange` | `(value: string) => void`    | —            | Change handler             |
| `disabled`      | `boolean`                    | `false`      | Disables all items         |
| `orientation`   | `'horizontal' \| 'vertical'` | `'vertical'` | Layout direction           |

### RadioGroupItem

| Prop       | Type                   | Required | Default | Description                                           |
| ---------- | ---------------------- | -------- | ------- | ----------------------------------------------------- |
| `value`    | `string`               | **Yes**  | —       | The option value                                      |
| `id`       | `string`               | **Yes**  | —       | Associates with `<Label htmlFor="...">`               |
| `size`     | `'sm' \| 'md' \| 'lg'` | No       | `'md'`  | Size variant controlling the radio circle dimensions. |
| `disabled` | `boolean`              | No       | `false` | Disables this specific item                           |

---

## Examples

### Vertical List

```tsx
import { RadioGroup, RadioGroupItem, Label } from 'xertica-ui/ui';

<RadioGroup defaultValue="editor">
  <div className="flex items-center space-x-2">
    <RadioGroupItem value="admin" id="admin" />
    <Label htmlFor="admin">Administrator</Label>
  </div>
  <div className="flex items-center space-x-2">
    <RadioGroupItem value="editor" id="editor" />
    <Label htmlFor="editor">Editor</Label>
  </div>
  <div className="flex items-center space-x-2">
    <RadioGroupItem value="viewer" id="viewer" />
    <Label htmlFor="viewer">Viewer</Label>
  </div>
</RadioGroup>;
```

### Inside react-hook-form

```tsx
<FormField
  control={form.control}
  name="role"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Role</FormLabel>
      <FormControl>
        <RadioGroup
          onValueChange={field.onChange}
          defaultValue={field.value}
          className="flex flex-col space-y-1"
        >
          <FormItem className="flex items-center space-x-2 space-y-0">
            <FormControl>
              <RadioGroupItem value="admin" />
            </FormControl>
            <FormLabel>Administrator</FormLabel>
          </FormItem>
          <FormItem className="flex items-center space-x-2 space-y-0">
            <FormControl>
              <RadioGroupItem value="editor" />
            </FormControl>
            <FormLabel>Editor</FormLabel>
          </FormItem>
        </RadioGroup>
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>
```

---

## AI Rules

- Each `RadioGroupItem` requires both `value` and `id`.
- **Sizing** — `RadioGroupItem` supports `sm`, `md`, and `lg`. Ensure the size matches the associated `Label` size.
- The `Label` `htmlFor` must match the `RadioGroupItem` `id`.
- In forms, use `onValueChange={field.onChange}` and `defaultValue={field.value}` — **not** `{...field}`.
- For more than 6 options, switch to `<Select>` instead.

---

## Related Components

- [`Checkbox`](./checkbox.md) — For multi-select lists
- [`Select`](./select.md) — For large option sets
- [`Form`](./form.md)

--- END COMPONENT: RADIO-GROUP ---


--- START COMPONENT: RATING ---
# Rating

## Overview

A star-based rating input that allows users to rate items on a 1–5 (or custom range) scale. Supports both interactive rating input and read-only display modes.

---

## When to Use

- Product or service reviews
- Satisfaction ratings in feedback forms
- Read-only quality scores in lists and tables

---

## Props

| Prop           | Type                      | Default | Required | Description                                 |
| -------------- | ------------------------- | ------- | -------- | ------------------------------------------- |
| `value`        | `number`                  | —       | No       | Current rating value                        |
| `defaultValue` | `number`                  | `0`     | No       | Uncontrolled initial value                  |
| `onChange`     | `(value: number) => void` | —       | No       | Change handler                              |
| `max`          | `number`                  | `5`     | No       | Maximum rating                              |
| `readonly`     | `boolean`                 | `false` | No       | Disables interaction, shows read-only stars |
| `size`         | `'sm' \| 'md' \| 'lg'`    | `'md'`  | No       | Star size                                   |
| `className`    | `string`                  | —       | No       | Additional CSS classes                      |

---

## Examples

### Interactive Rating

```tsx
import { Rating } from 'xertica-ui/ui';
import { useState } from 'react';

const [rating, setRating] = useState(0);

<div className="space-y-2">
  <Rating value={rating} onChange={setRating} />
  <p className="text-sm text-muted-foreground">{rating} out of 5 stars</p>
</div>;
```

### Read-Only (in a card or table)

```tsx
<Rating value={4.5} readonly size="sm" />
```

### In a Form

```tsx
<FormField
  control={form.control}
  name="rating"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Your Rating</FormLabel>
      <FormControl>
        <Rating value={field.value} onChange={field.onChange} />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>
```

---

## AI Rules

- Use `readonly` (lowercase) for display-only contexts — never add `pointer-events-none` manually.
- Do not use `{...field}` spread — use `value={field.value}` and `onChange={field.onChange}`.
- For half-star display values (e.g., `4.5`), only use in `readonly` mode.

--- END COMPONENT: RATING ---


--- START COMPONENT: RESIZABLE ---
# Resizable

## Overview

A panel splitter that lets users resize adjacent panels by dragging a handle. Used in IDE-style layouts, split-view editors, and any interface where two panels need to share space dynamically.

---

## When to Use

- Split-panel views (code editor + preview, list + detail)
- Dashboard panels that users want to resize
- Complex tool interfaces

---

## Anatomy

```
<ResizablePanelGroup direction="horizontal">
  <ResizablePanel defaultSize={50}>
    {/* Left panel */}
  </ResizablePanel>
  <ResizableHandle />
  <ResizablePanel defaultSize={50}>
    {/* Right panel */}
  </ResizablePanel>
</ResizablePanelGroup>
```

---

## Props

### ResizablePanelGroup

| Prop        | Type                         | Default | Description                    |
| ----------- | ---------------------------- | ------- | ------------------------------ |
| `direction` | `'horizontal' \| 'vertical'` | —       | **Required**. Split direction. |
| `className` | `string`                     | —       | Applied to the container       |

### ResizablePanel

| Prop          | Type     | Default | Description                     |
| ------------- | -------- | ------- | ------------------------------- |
| `defaultSize` | `number` | —       | Initial percentage size (0–100) |
| `minSize`     | `number` | `10`    | Minimum percentage size         |
| `maxSize`     | `number` | `90`    | Maximum percentage size         |

### ResizableHandle

| Prop         | Type      | Description                             |
| ------------ | --------- | --------------------------------------- |
| `withHandle` | `boolean` | Shows a visible grip icon on the handle |

---

## Examples

```tsx
import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from 'xertica-ui/ui';

<ResizablePanelGroup direction="horizontal" className="min-h-[400px] rounded-lg border">
  <ResizablePanel defaultSize={30} minSize={20}>
    <div className="p-4">
      <h3 className="font-semibold">Side Panel</h3>
    </div>
  </ResizablePanel>
  <ResizableHandle withHandle />
  <ResizablePanel defaultSize={70}>
    <div className="p-4">
      <h3 className="font-semibold">Main Panel</h3>
    </div>
  </ResizablePanel>
</ResizablePanelGroup>;
```

---

## AI Rules

- `direction` is **required** — always specify `"horizontal"` or `"vertical"`.
- `defaultSize` values across all panels must sum to `100`.
- The parent container must have a defined height (`min-h-[400px]` or `h-full`) — without a bounded height the vertical split will collapse.

--- END COMPONENT: RESIZABLE ---


--- START COMPONENT: RICH-TEXT-EDITOR ---
# RichTextEditor

## Overview

A lightweight, native WYSIWYG (What You See Is What You Get) document text editor built into the Xertica UI framework. It utilizes the browser's native `contentEditable` architecture and `document.execCommand` under the hood to provide essential text formatting without the overhead of massive third-party rendering engines.

The component ships in **two usage patterns**:

| Pattern               | When to use                                                                 |
| --------------------- | --------------------------------------------------------------------------- |
| `<RichTextEditor />`  | Drop-in editor with full toolbar and status bar — zero configuration needed |
| `useRichTextEditor()` | Headless hook — bring your own toolbar, layout, and styling                 |

---

## Features

- **Text Formatting:** Bold, Italic, Underline, and Unordered Lists.
- **Headings & Paragraphs:** Integrated Radix Dropdown for structured block conversion (`P`, `H1`, `H2`, `H3`), specially configured not to trap focus and lose text selection.
- **Alignment:** Left, Center, and Right text justification blocks.
- **Links:** Insert and remove hyperlinks with automatic `target="_blank"` configuration for external security.
- **Search:** Built-in "Find in Text" functionality with a dedicated search bar, supporting Next/Previous navigation and keyboard shortcuts (`Enter`, `Shift+Enter`, `Esc`).
- **Extensive Configuration:** Toggle virtually every toolbar feature on or off via boolean properties (`allowUndoRedo`, `allowHeadings`, etc.).
- **Live Metrics:** Word and character count natively supported and toggleable in the status bar (`showWordCount`, `showCharacterCount`).
- **Action Extensibility:** Supports custom `actionButton` property for injecting dynamic trailing actions into the toolbar (e.g., Save, Submit).
- **Responsive:** Scales correctly and uses built-in localized Tailwind typography (`prose` substitute).

---

## Props

| Prop                 | Type                      | Default | Required | Description                                                                          |
| -------------------- | ------------------------- | ------- | -------- | ------------------------------------------------------------------------------------ |
| `value`              | `string`                  | —       | Yes      | Initial raw HTML string content to mount the editor.                                 |
| `onChange`           | `(value: string) => void` | —       | No       | Fired whenever the editable content changes, emitting raw HTML.                      |
| `placeholder`        | `string`                  | —       | No       | Hint text rendered using CSS pseudo-elements when empty.                             |
| `className`          | `string`                  | —       | No       | Additional classes applied to the root container.                                    |
| `actionButton`       | `React.ReactNode`         | —       | No       | A custom DOM element rendered flush-right against the toolbar.                       |
| `allowSearch`        | `boolean`                 | `true`  | No       | Whether to show the search functionality in the toolbar.                             |
| `allowLinks`         | `boolean`                 | `true`  | No       | Whether to show the link insertion functionality in the toolbar.                     |
| `allowUndoRedo`      | `boolean`                 | `true`  | No       | Whether to show the undo/redo functionality in the toolbar.                          |
| `allowHeadings`      | `boolean`                 | `true`  | No       | Whether to show the headings functionality in the toolbar.                           |
| `allowFormatting`    | `boolean`                 | `true`  | No       | Whether to show text formatting (bold, italic, etc) functionality in the toolbar.    |
| `allowAlignment`     | `boolean`                 | `true`  | No       | Whether to show alignment functionality in the toolbar.                              |
| `allowLists`         | `boolean`                 | `true`  | No       | Whether to show list functionality in the toolbar.                                   |
| `showWordCount`      | `boolean`                 | `true`  | No       | Whether to show the word count in the footer.                                        |
| `showCharacterCount` | `boolean`                 | `true`  | No       | Whether to show the character count in the footer.                                   |
| `disabled`           | `boolean`                 | `false` | No       | Disables all editing and applies opacity-50. Hides the toolbar.                      |
| `readOnly`           | `boolean`                 | `false` | No       | Makes the editor non-editable while keeping full visual fidelity. Hides the toolbar. |
| `onFocus`            | `() => void`              | —       | No       | Called when the editor area receives focus.                                          |
| `onBlur`             | `() => void`              | —       | No       | Called when the editor area loses focus.                                             |
| `minHeight`          | `string`                  | —       | No       | Minimum height of the editable area (CSS value, e.g. `"200px"`).                     |
| `maxHeight`          | `string`                  | —       | No       | Maximum height of the editable area (CSS value, e.g. `"600px"`).                     |

---

## Examples

### Basic Implementation

```tsx
import { useState } from 'react';
import { RichTextEditor } from 'xertica-ui';
import { Button } from 'xertica-ui/button';

export function EditorExample() {
  const [content, setContent] = useState('<p>Start typing your document...</p>');

  return (
    <div className="h-[400px]">
      <RichTextEditor
        value={content}
        onChange={setContent}
        placeholder="Escreva algo brilhante..."
        actionButton={
          <Button size="sm" onClick={() => console.log(content)}>
            Save
          </Button>
        }
      />
    </div>
  );
}
```

### Minimal Toolbar

```tsx
<RichTextEditor
  value={content}
  onChange={setContent}
  allowHeadings={false}
  allowAlignment={false}
  allowLists={false}
  allowLinks={false}
  allowSearch={false}
  showWordCount={false}
  showCharacterCount={false}
/>
```

---

## Headless Hook — `useRichTextEditor()`

Use the headless hook when you need full control over the editor's UI — custom toolbar layout, custom styling, or embedding the editor logic inside a larger component.

### Import

```tsx
import { useRichTextEditor } from 'xertica-ui/ui';
```

### Hook Props

| Prop       | Type                      | Required | Description                                |
| ---------- | ------------------------- | -------- | ------------------------------------------ |
| `value`    | `string`                  | Yes      | Current HTML value of the editor           |
| `onChange` | `(value: string) => void` | No       | Called whenever the editor content changes |

### Hook Return Value

| Property                  | Type                                         | Description                                              |
| ------------------------- | -------------------------------------------- | -------------------------------------------------------- |
| `editorRef`               | `RefObject<HTMLDivElement>`                  | Attach to the `contenteditable` div                      |
| `searchInputRef`          | `RefObject<HTMLInputElement>`                | Attach to the search `<input>`                           |
| `linkInputRef`            | `RefObject<HTMLInputElement>`                | Attach to the link URL `<input>`                         |
| `activeFormats`           | `ActiveFormats`                              | Map of currently active formatting commands              |
| `isSearchOpen`            | `boolean`                                    | Whether the inline search bar is open                    |
| `setIsSearchOpen`         | `(open: boolean) => void`                    | Toggle the search bar                                    |
| `searchQuery`             | `string`                                     | Current search query string                              |
| `setSearchQuery`          | `(query: string) => void`                    | Update the search query                                  |
| `linkUrl`                 | `string`                                     | Current link URL being edited                            |
| `setLinkUrl`              | `(url: string) => void`                      | Update the link URL                                      |
| `isLinkOpen`              | `boolean`                                    | Whether the link popover is open                         |
| `wordCount`               | `number`                                     | Word count of the editor content                         |
| `characterCount`          | `number`                                     | Character count of the editor content                    |
| `updateActiveFormats`     | `() => void`                                 | Re-read the current selection and update `activeFormats` |
| `execCommand`             | `(command: string, value?: string) => void`  | Execute a `document.execCommand` and sync state          |
| `handleInput`             | `() => void`                                 | Call on every `input` event of the editor                |
| `performSearch`           | `(text: string, backward?: boolean) => void` | Search forward or backward                               |
| `handleCreateLink`        | `() => void`                                 | Create or update a hyperlink at the current selection    |
| `handleUnlink`            | `() => void`                                 | Remove the hyperlink at the current cursor position      |
| `onLinkPopoverOpenChange` | `(open: boolean) => void`                    | Handle link popover open/close                           |

### `ActiveFormats` Type

```typescript
interface ActiveFormats {
  bold: boolean;
  italic: boolean;
  underline: boolean;
  justifyLeft: boolean;
  justifyCenter: boolean;
  justifyRight: boolean;
  insertUnorderedList: boolean;
  insertOrderedList: boolean;
  link: boolean;
  h1: boolean;
  h2: boolean;
  h3: boolean;
  p: boolean;
}
```

### Headless Hook Example

```tsx
import { useState } from 'react';
import { useRichTextEditor } from 'xertica-ui/ui';

function MyMinimalEditor({ value, onChange }) {
  const { editorRef, activeFormats, execCommand, handleInput, wordCount } = useRichTextEditor({
    value,
    onChange,
  });

  return (
    <div className="border rounded-lg overflow-hidden">
      {/* Custom minimal toolbar */}
      <div className="flex gap-1 p-2 border-b bg-muted/30">
        <button
          onClick={() => execCommand('bold')}
          className={activeFormats.bold ? 'font-bold text-primary' : 'text-muted-foreground'}
        >
          B
        </button>
        <button
          onClick={() => execCommand('italic')}
          className={activeFormats.italic ? 'italic text-primary' : 'text-muted-foreground'}
        >
          I
        </button>
        <button
          onClick={() => execCommand('underline')}
          className={activeFormats.underline ? 'underline text-primary' : 'text-muted-foreground'}
        >
          U
        </button>
      </div>

      {/* Editor area */}
      <div
        ref={editorRef}
        contentEditable
        onInput={handleInput}
        className="p-4 min-h-[200px] focus:outline-none"
        data-placeholder="Start typing..."
      />

      {/* Custom footer */}
      <div className="px-4 py-1 border-t text-xs text-muted-foreground">{wordCount} words</div>
    </div>
  );
}
```

---

## Component Architecture Notes

- **Data Binding:** The editor takes `value` _only for its initial render mount_, then operates autonomously internally. It uses continuous `innerHTML` tracking out to the `onChange` event. Avoid forcefully re-rendering the component from the top-down while typing, as it can cause cursor jump displacement.
- **Radix UI Interaction:** The `DropdownMenu` inside the toolbar is customized with `modal={false}` and intercepts `onPointerDown` events on its MenuItems. This is a critical technical choice that prevents modern React Portals from stealing DOM focus away from the `contentEditable` area when selecting Headings.
- **CSS Encapsulation:** Core semantic elements (`h1`, `h2`, `h3`, `p`, `ul`, `b`, `i`) are uniquely targeted via the internal `.prose-editor` stylesheet, freeing the global scope from collisions.
- **Headless Hook:** All state, refs, and DOM-manipulation logic live in `useRichTextEditor`. The `RichTextEditor` component is a thin presentation layer on top of this hook.

---

## Accessibility

The `contentEditable` area ships with the following ARIA attributes (v2.1.9+):

| Attribute        | Value                              | Description                                                    |
| ---------------- | ---------------------------------- | -------------------------------------------------------------- |
| `role`           | `"textbox"`                        | Identifies the editable area as a text input to screen readers |
| `aria-multiline` | `"true"`                           | Signals that the textbox accepts multiple lines                |
| `aria-label`     | `placeholder \| "Editor de texto"` | Accessible name — uses `placeholder` when provided             |
| `aria-readonly`  | `readOnly` prop                    | Signals non-editable state to AT without hiding the toolbar    |
| `aria-disabled`  | `disabled` prop                    | Signals disabled state to AT                                   |

> **Note**: The footer "Auto-save ativo" label was removed in v2.1.9. Word and character counters are now reactive `useState` values — they update on every keystroke via `handleInput` and re-sync when `value` changes externally.

---

## AI Rules

```
- ALWAYS use `useRichTextEditor()` when building a custom editor UI — never re-implement `execCommand` logic manually.
- The `editorRef` from the hook MUST be attached to the `contenteditable` div.
- Call `handleInput` on every `onInput` event of the editor div to keep `onChange` and `activeFormats` in sync.
- `execCommand` already calls `handleInput` internally — do not call both for the same action.
- `wordCount` and `characterCount` are reactive state values (useState) — they update after `handleInput` is called and re-sync when `value` changes externally. Do NOT try to read them from editorRef.current.innerText directly.
- The `activeFormats` object reflects the formatting state at the current cursor position. Use it to highlight active toolbar buttons.
- The contentEditable div already has ARIA attributes (role, aria-multiline, aria-label, aria-readonly, aria-disabled) — do NOT add them manually when using <RichTextEditor />.
```

--- END COMPONENT: RICH-TEXT-EDITOR ---


--- START COMPONENT: ROUTE-MAP ---
# RouteMap

## Overview

A specialized Google Maps component that calculates and renders a route between an origin and destination point, with support for intermediate waypoints and multiple travel modes. The route is drawn on the map using the Google Directions Service, and optionally returns the calculated distance and duration.

Use `<Map>` for general-purpose map rendering. Use `<RouteMap>` specifically when you need to display a navigable route.

---

## When to Use

- Displaying the route between two locations (delivery tracking, field service, logistics)
- Showing estimated travel time and distance
- Multi-stop itinerary visualization

## When NOT to Use

- General-purpose map without route — use `<Map>` instead.
- Static location marker display — use `<Map markers={...}>` instead.

---

## Prerequisites

- A Google Maps JavaScript API key with the **Directions API** enabled.
- The key must be provided to `<XerticaProvider googleMapsApiKey="YOUR_KEY">`, OR passed directly as the `apiKey` prop.

---

## Props

| Prop                | Type                                                 | Default     | Required | Description                                                         |
| ------------------- | ---------------------------------------------------- | ----------- | -------- | ------------------------------------------------------------------- |
| `origin`            | `{ lat: number; lng: number }`                       | —           | **Yes**  | Route start point                                                   |
| `destination`       | `{ lat: number; lng: number }`                       | —           | **Yes**  | Route end point                                                     |
| `waypoints`         | `{ lat: number; lng: number }[]`                     | `[]`        | No       | Intermediate stops                                                  |
| `travelMode`        | `'DRIVING' \| 'WALKING' \| 'BICYCLING' \| 'TRANSIT'` | `'DRIVING'` | No       | Mode of transport                                                   |
| `height`            | `string`                                             | `'450px'`   | No       | CSS height of the map container                                     |
| `mapId`             | `string`                                             | —           | No       | Google Maps Map ID for custom styling                               |
| `apiKey`            | `string`                                             | —           | No       | Overrides provider API key                                          |
| `onRouteCalculated` | `(distance: string, duration: string) => void`       | —           | No       | Called with formatted distance and duration after route is computed |
| `disableDefaultUI`  | `boolean`                                            | `false`     | No       | Hides all default map UI controls                                   |
| `zoomControl`       | `boolean`                                            | `true`      | No       | Shows/hides zoom control                                            |
| `streetViewControl` | `boolean`                                            | `false`     | No       | Shows/hides Street View control                                     |
| `mapTypeControl`    | `boolean`                                            | `false`     | No       | Shows/hides map type switcher                                       |
| `fullscreenControl` | `boolean`                                            | `true`      | No       | Shows/hides fullscreen button                                       |
| `className`         | `string`                                             | —           | No       | Additional CSS classes for the wrapper div                          |

---

## Examples

### Basic Route

```tsx
import { RouteMap } from 'xertica-ui';

<RouteMap
  origin={{ lat: -12.971, lng: -38.501 }}
  destination={{ lat: -13.025, lng: -38.478 }}
  height="400px"
/>;
```

### With Waypoints and Distance Callback

```tsx
const [routeInfo, setRouteInfo] = useState<{ distance: string; duration: string }>();

<RouteMap
  origin={{ lat: -12.971, lng: -38.501 }}
  destination={{ lat: -13.025, lng: -38.478 }}
  waypoints={[{ lat: -12.99, lng: -38.49 }]}
  travelMode="DRIVING"
  height="500px"
  onRouteCalculated={(distance, duration) => setRouteInfo({ distance, duration })}
/>;

{
  routeInfo && (
    <p className="text-sm text-muted-foreground mt-2">
      {routeInfo.distance} · {routeInfo.duration}
    </p>
  );
}
```

### Walking Mode

```tsx
<RouteMap
  origin={{ lat: -12.971, lng: -38.501 }}
  destination={{ lat: -12.98, lng: -38.51 }}
  travelMode="WALKING"
  height="300px"
/>
```

---

## Return Values from `onRouteCalculated`

| Parameter  | Format                   | Example                    |
| ---------- | ------------------------ | -------------------------- |
| `distance` | `"X.X km"`               | `"12.4 km"`                |
| `duration` | `"Xh Ymin"` or `"Y min"` | `"1h 23min"` or `"45 min"` |

---

## AI Rules

- **Always** set an explicit `height` — without it the map renders with 0 height.
- `origin` and `destination` use `{ lat, lng }` format — **not** `{ latitude, longitude }`.
- The API key requires the **Directions API** enabled, in addition to the Maps JavaScript API. Plain Maps API keys will fail route calculation.
- `onRouteCalculated` receives pre-formatted strings (`"12.4 km"`, `"23 min"`) — not raw numeric values.
- If `waypoints` is empty, simply omit the prop — do not pass an empty array explicitly.

---

## Related Components

- [`Map`](./map.md) — General-purpose map without route
- [Maps Pattern](../patterns/analytics.md) — Location-based analytics usage

--- END COMPONENT: ROUTE-MAP ---


--- START COMPONENT: SCROLL-AREA ---
# Scroll Area

## Overview

A cross-browser, themeable scrollable container with custom scrollbar styling. Use instead of native `overflow-y-auto` when the scrollbar needs to match the application's design system (instead of the OS default scrollbar).

---

## When to Use

- Fixed-height panels that need vertical scrolling
- Sidebar content areas, chat message lists, log viewers
- Any scrollable container where the native scrollbar looks out of place

---

## Props

| Prop        | Type                                        | Default   | Description                           |
| ----------- | ------------------------------------------- | --------- | ------------------------------------- |
| `className` | `string`                                    | —         | Set height and width of the container |
| `type`      | `'auto' \| 'always' \| 'scroll' \| 'hover'` | `'hover'` | When the scrollbar is visible         |

---

## Examples

### Fixed-Height List

```tsx
import { ScrollArea } from 'xertica-ui/ui';

<ScrollArea className="h-[300px] w-full rounded-md border p-4">
  {items.map(item => (
    <div key={item.id} className="py-2 text-sm">
      {item.name}
    </div>
  ))}
</ScrollArea>;
```

### Sidebar Scroll Area

```tsx
<ScrollArea className="flex-1 px-2">
  {routes.map(route => (
    <NavItem key={route.path} route={route} />
  ))}
</ScrollArea>
```

---

## AI Rules

- Always set an explicit height via `className="h-[300px]"` or `h-full` — `ScrollArea` requires a bounded height to scroll.
- Use inside the Sidebar for the scrollable navigation area.
- Do not use for full-page scrolling — the entire page scroll is managed by the CSS `overflow-y-auto` on the main content container.

--- END COMPONENT: SCROLL-AREA ---


--- START COMPONENT: SEARCH ---
# Search

## Overview

A pre-built search input with a built-in search icon and clear button. A convenience component built on top of `<Input>` that handles the common search field pattern with a consistent size scale.

---

## When to Use

- Search fields in headers, sidebar filters, and CRUD filter rows
- When a plain `<Input>` + manual icon positioning is redundant

---

## Props

| Prop                 | Type                                         | Default | Required | Description                                                         |
| -------------------- | -------------------------------------------- | ------- | -------- | ------------------------------------------------------------------- |
| `value`              | `string`                                     | —       | No       | Controlled value                                                    |
| `onChange`           | `React.ChangeEventHandler<HTMLInputElement>` | —       | No       | Native change handler                                               |
| `onSearch`           | `(value: string) => void`                    | —       | No       | Called with the string value on every keystroke                     |
| `onClear`            | `() => void`                                 | —       | No       | Called when the × button is clicked or Escape is pressed            |
| `placeholder`        | `string`                                     | —       | No       | Input placeholder text                                              |
| `size`               | `'sm' \| 'md' \| 'lg'`                       | `'md'`  | No       | Height preset — matches the Input/Select size scale (h-8/h-10/h-12) |
| `containerClassName` | `string`                                     | —       | No       | CSS classes for the outer wrapper div                               |
| `className`          | `string`                                     | —       | No       | CSS classes for the input element                                   |

---

## Examples

### Controlled Search

```tsx
import { Search } from 'xertica-ui/ui';
import { useState } from 'react';

const [query, setQuery] = useState('');

<Search
  value={query}
  onSearch={setQuery}
  onClear={() => setQuery('')}
  placeholder="Search members..."
  className="w-full max-w-sm"
/>;
```

### Size Variants

```tsx
<Search size="sm" placeholder="Small search" />
<Search size="md" placeholder="Default search" />
<Search size="lg" placeholder="Large search" />
```

---

## Alternative: Manual Composition

When `Search` component is not available, use the standard Input pattern:

```tsx
import { Input } from 'xertica-ui/ui';
import { Search as SearchIcon } from 'lucide-react';

<div className="relative w-full max-w-sm">
  <SearchIcon className="absolute left-2.5 top-2.5 size-4 text-muted-foreground" />
  <Input
    value={query}
    onChange={e => setQuery(e.target.value)}
    placeholder="Search..."
    className="pl-8"
  />
</div>;
```

---

## AI Rules

- **Sizing** — Search defaults to `md` (h-10, 40px), matching Input, SelectTrigger, and Textarea. Use the same `size` across all form elements for consistent alignment.
- Use `onSearch` for simple string callbacks; use `onChange` when you need the full event object.
- The clear button (×) only appears when the input has content — it is hidden when empty.
- Pressing `Escape` also triggers `onClear`.
- When using the manual composition pattern (Input + icon), always use `relative` on the wrapper + `absolute` on the icon + `pl-8` on the Input.

--- END COMPONENT: SEARCH ---


--- START COMPONENT: SELECT ---
# Select

## Overview

A styled dropdown for selecting a single option from a list. Built on Radix UI, it provides a fully accessible combobox with keyboard navigation, portaled content, and proper ARIA semantics. Always use `<Select>` from `xertica-ui` — never use native `<select>`.

---

## When to Use

- Choosing a single value from a list of 5+ options
- Role selection, category selection, status filters
- Period selectors in analytics dashboards

## When NOT to Use

- Binary choices — use `<Switch>` or `<RadioGroup>` instead.
- Multiple selection — use `<Checkbox>` groups.
- Fewer than 4 options that should all be visible — use `<RadioGroup>`.

---

## Anatomy

```
<Select>
  <SelectTrigger>
    <SelectValue placeholder="..." />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="...">Label</SelectItem>
    <SelectItem value="...">Label</SelectItem>
  </SelectContent>
</Select>
```

---

## Props

### Select

| Prop            | Type                      | Description                |
| --------------- | ------------------------- | -------------------------- |
| `value`         | `string`                  | Controlled selected value  |
| `defaultValue`  | `string`                  | Uncontrolled default value |
| `onValueChange` | `(value: string) => void` | Change handler             |
| `disabled`      | `boolean`                 | Disables the select        |

### SelectTrigger

| Prop          | Type                   | Default | Description                                                |
| ------------- | ---------------------- | ------- | ---------------------------------------------------------- |
| `size`        | `'sm' \| 'md' \| 'lg'` | `'md'`  | Size variant — matches Input sizing scale (h-8/h-10/h-12). |
| `className`   | `string`               | —       | Add width or style overrides                               |
| `placeholder` | `string`               | —       | Forwarded to `SelectValue`                                 |

### SelectItem

| Prop    | Type     | Required | Description      |
| ------- | -------- | -------- | ---------------- |
| `value` | `string` | **Yes**  | The option value |

---

## Examples

### Standalone

```tsx
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from 'xertica-ui/ui';

<Select>
  <SelectTrigger className="w-[180px]">
    <SelectValue placeholder="Select role" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="admin">Administrator</SelectItem>
    <SelectItem value="editor">Editor</SelectItem>
    <SelectItem value="viewer">Viewer</SelectItem>
  </SelectContent>
</Select>;
```

### Controlled

```tsx
const [role, setRole] = useState('editor');

<Select value={role} onValueChange={setRole}>
  <SelectTrigger className="w-[200px]">
    <SelectValue />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="admin">Administrator</SelectItem>
    <SelectItem value="editor">Editor</SelectItem>
    <SelectItem value="viewer">Viewer</SelectItem>
  </SelectContent>
</Select>;
```

### Inside react-hook-form

```tsx
<FormField
  control={form.control}
  name="role"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Role</FormLabel>
      <Select onValueChange={field.onChange} defaultValue={field.value}>
        <FormControl>
          <SelectTrigger>
            <SelectValue placeholder="Select a role" />
          </SelectTrigger>
        </FormControl>
        <SelectContent>
          <SelectItem value="admin">Administrator</SelectItem>
          <SelectItem value="editor">Editor</SelectItem>
        </SelectContent>
      </Select>
      <FormMessage />
    </FormItem>
  )}
/>
```

---

## AI Rules

- **Never** use native `<select>` — always use the full `<Select>/<SelectTrigger>/<SelectContent>/<SelectItem>` composition.
- **Sizing** — SelectTrigger defaults to `md` (h-10, 40px), matching Input's default. Use the same `size` prop across `Input`, `SelectTrigger`, `Textarea`, and `Search` to ensure consistent alignment in form rows.
- When used inside a form, wrap `<SelectTrigger>` in `<FormControl>` — the `field` spread goes on the `<Select>` (`onValueChange={field.onChange}`), not on the trigger.
- `SelectItem` requires a non-empty string `value` prop — never use empty strings or numbers.
- To set a default selected option, use `defaultValue` on `<Select>` — not on `<SelectItem>`.

---

## Related Components

- [`Form`](./form.md)
- [`RadioGroup`](./radio-group.md) — Alternative for small, always-visible option sets
- [`Checkbox`](./checkbox.md) — For multi-select scenarios

--- END COMPONENT: SELECT ---


--- START COMPONENT: SEPARATOR ---
# Separator

## Overview

A thin horizontal (or vertical) line that visually divides sections of content. Primarily decorative but semantically meaningful as an `<hr>` element. Used to create visual breathing room between logically distinct sections.

---

## When to Use

- Between major content sections within a page
- Between action groups in menus or footers
- Dividing the header from the body in a panel or sidebar

---

## Props

| Prop          | Type                         | Default        | Description                                 |
| ------------- | ---------------------------- | -------------- | ------------------------------------------- |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Line direction                              |
| `decorative`  | `boolean`                    | `true`         | When `true`, hidden from accessibility tree |
| `className`   | `string`                     | —              | Additional CSS classes                      |

---

## Examples

```tsx
import { Separator } from 'xertica-ui/ui';

<div>
  <h3>Section A</h3>
  <p>Content</p>
</div>
<Separator className="my-6" />
<div>
  <h3>Section B</h3>
</div>
```

### Vertical (in a toolbar)

```tsx
<div className="flex items-center gap-2">
  <Button variant="ghost">Bold</Button>
  <Separator orientation="vertical" className="h-6" />
  <Button variant="ghost">Italic</Button>
</div>
```

---

## AI Rules

- Add `className="my-6"` or `my-8` for proper vertical spacing between sections.
- Use `orientation="vertical"` in flex toolbars — remember to set a fixed `h-*` class for the height.
- `decorative` should remain `true` (default) unless the separator conveys structural meaning for screen readers.

--- END COMPONENT: SEPARATOR ---


--- START COMPONENT: SHEET ---
# Sheet

## Overview

An edge-anchored slide-in panel that overlays the current page from one side — top, right, bottom, or left. Like `Dialog` but more suitable for forms or detail views that benefit from more vertical space, or for secondary navigation and controls on mobile.

---

## When to Use

- Wide create/edit forms that need more room than a Dialog
- Detail/preview panels for selected records (record details sidebar)
- Filter panels that slide in from the right
- Mobile navigation drawers (slide from left)

## When NOT to Use

- Simple short confirmations — use `Dialog` instead.
- Destructive confirmations — use `AlertDialog` instead.
- Mobile bottom panels — use `Drawer` instead.

---

## Anatomy

```
<Sheet>
  <SheetTrigger asChild>
    <Button />
  </SheetTrigger>
  <SheetContent side="right">
    <SheetHeader>
      <SheetTitle />
      <SheetDescription />
    </SheetHeader>
    {/* Content */}
    <SheetFooter>
      <SheetClose asChild>
        <Button variant="ghost">Cancel</Button>
      </SheetClose>
      <Button>Save</Button>
    </SheetFooter>
  </SheetContent>
</Sheet>
```

---

## Props

### Sheet

| Prop           | Type                      | Description           |
| -------------- | ------------------------- | --------------------- |
| `open`         | `boolean`                 | Controlled open state |
| `onOpenChange` | `(open: boolean) => void` | State handler         |

### SheetContent

| Prop        | Type                                     | Default   | Description                          |
| ----------- | ---------------------------------------- | --------- | ------------------------------------ |
| `side`      | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | Which edge the panel slides from     |
| `className` | `string`                                 | —         | Width override (e.g., `sm:max-w-md`) |

---

## Examples

### Edit Record Side Panel

```tsx
import {
  Sheet,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
  SheetClose,
  Button,
} from 'xertica-ui/ui';

<Sheet>
  <SheetTrigger asChild>
    <Button variant="ghost" size="sm">
      Edit
    </Button>
  </SheetTrigger>
  <SheetContent className="sm:max-w-md">
    <SheetHeader>
      <SheetTitle>Edit Member</SheetTitle>
      <SheetDescription>Update member information below.</SheetDescription>
    </SheetHeader>
    <div className="py-6">{/* Form fields */}</div>
    <SheetFooter>
      <SheetClose asChild>
        <Button variant="ghost">Cancel</Button>
      </SheetClose>
      <Button onClick={handleSave}>Save Changes</Button>
    </SheetFooter>
  </SheetContent>
</Sheet>;
```

---

## AI Rules

- `SheetTitle` is **required** for accessibility.
- Use `side="right"` for record edit panels and filter drawers. Use `side="left"` for navigation drawers.
- Override width with `className="sm:max-w-md"` or `sm:max-w-lg` on `<SheetContent>` — the default is narrow.
- Use `<SheetClose asChild>` wrapping a `<Button>` for the cancel action — this auto-closes the sheet.
- Always use `<SheetTrigger asChild>` wrapping a `<Button>` — never a raw button element.

---

## Related Components

- [`Dialog`](./dialog.md) — Centered modal alternative
- [`Drawer`](./drawer.md) — Mobile bottom panel
- [`Form`](./form.md) — Commonly rendered inside Sheet

--- END COMPONENT: SHEET ---


--- START COMPONENT: SIDEBAR ---
# Sidebar

## Overview

The `Sidebar` is the primary vertical navigation panel of the application shell. It manages the app's hierarchy, supporting simple lists, grouped items, and an advanced "Assistant" mode for AI-driven or data-rich interfaces.

It is a responsive component that can be expanded or collapsed as an icon-only strip, fully integrated with the `LayoutContext` for state management.

The component ships with **three usage patterns** to cover different levels of customization:

| Pattern                                                        | When to use                                               |
| -------------------------------------------------------------- | --------------------------------------------------------- |
| **Monolithic API** (`<Sidebar />`)                             | Standard usage — pass props, get a fully-featured sidebar |
| **Compound Component API** (`<Sidebar.Root>` + sub-components) | Custom layouts — compose only the parts you need          |
| **Headless Hook** (`useSidebar()`)                             | Full control — manage state yourself, render anything     |

---

## Variants

### 1. Default

A clean, structured navigation list for standard dashboards and settings areas.

- Supports a flat `routes` list OR grouped navigation via `navigationGroups`.
- Each route can have `children` — sub-routes exposed via a contextual `ChevronRight` button at the end of the item.

### 2. Assistant (Advanced)

Designed for complex tools, agents, or multi-context navigation.

- **Search**: Built-in search bar with optional advanced filtering.
- **Groups**: Support for sections with labels, descriptions, and action menus.
- **Fixed Areas**: Pinned top container for persistent actions (like "New Conversation").

---

## When to Use

- Use it to host the primary navigation routes of your platform.
- Choose `variant="assistant"` when building tools that require local search or frequent creation of new items (e.g., GPT-style interfaces).

---

## Props

### `<Sidebar />` (Monolithic API)

| Prop               | Type                       | Default                                   | Description                                                                             |
| ------------------ | -------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------- |
| `expanded`         | `boolean`                  | `auto`                                    | Controlled state. Defaults to `LayoutContext` or local state.                           |
| `onToggle`         | `() => void`               | `auto`                                    | Toggle callback. Defaults to `LayoutContext` or local state.                            |
| `variant`          | `'default' \| 'assistant'` | `'default'`                               | Controls the internal layout and features.                                              |
| `routes`           | `RouteConfig[]`            | —                                         | Flat navigation items (default variant, no groups).                                     |
| `navigationGroups` | `RouteGroup[]`             | —                                         | Grouped navigation items with labels. Works in both `default` and `assistant` variants. |
| `fixedArea`        | `SidebarFixedAreaConfig`   | —                                         | Pinned top button (assistant variant — e.g. "New Conversation").                        |
| `search`           | `SidebarSearchConfig`      | —                                         | Search bar configuration (assistant variant).                                           |
| `logo`             | `ReactNode`                | —                                         | Logo shown when expanded.                                                               |
| `logoCollapsed`    | `ReactNode`                | —                                         | Logo shown when collapsed.                                                              |
| `width`            | `number`                   | `280`                                     | Expanded sidebar width in pixels.                                                       |
| `footer`           | `SidebarFooterConfig`      | —                                         | Footer visibility flags (`showUser`, `showSettings`, `showLogout`).                     |
| `showFooter`       | `boolean`                  | `true` for default, `false` for assistant | Whether to render the footer section.                                                   |

### `<Sidebar.Root />` (Compound Component)

| Prop       | Type                     | Default                | Description                                                                          |
| ---------- | ------------------------ | ---------------------- | ------------------------------------------------------------------------------------ |
| `expanded` | `boolean`                | `auto`                 | Controlled expansion state.                                                          |
| `onToggle` | `() => void`             | `auto`                 | Toggle callback.                                                                     |
| `navigate` | `(path: string) => void` | `window.location.href` | Navigation handler.                                                                  |
| `location` | `{ pathname: string }`   | `window.location`      | Current location for active state.                                                   |
| `width`    | `number`                 | `280`                  | Expanded width in pixels.                                                            |
| `children` | `ReactNode`              | —                      | Sub-components: `Sidebar.Header`, `Sidebar.Nav`, `Sidebar.Footer`, `Sidebar.Search`. |

### `useSidebar()` (Headless Hook)

```ts
import { useSidebar } from 'xertica-ui/layout';

const {
  expanded, // boolean — current expansion state
  setExpanded, // (value: boolean | fn) => void
  toggleExpanded, // () => void
  isMobileViewport, // boolean
  hasOverflow, // boolean — nav items overflow the container
  visibleItems, // RouteGroup[] — items that fit in the nav
  overflowItems, // RouteGroup[] — items that overflow
  openSubmenu, // string | null
  setOpenSubmenu, // (id: string | null) => void
  isFilterOpen, // boolean
  setIsFilterOpen, // (open: boolean) => void
  navRef, // RefObject<HTMLElement> — attach to nav container
  navigationGroups, // RouteGroup[] — the resolved groups passed in
} = useSidebar({
  defaultExpanded: true,
  navigationGroups: myGroups,
});
```

### RouteConfig

| Field         | Type               | Description                                                          |
| ------------- | ------------------ | -------------------------------------------------------------------- |
| `path`        | `string`           | Navigation path                                                      |
| `label`       | `string`           | Display label                                                        |
| `icon`        | `ComponentType`    | Leading icon component                                               |
| `children`    | `RouteConfig[]`    | Sub-routes exposed via contextual menu (ChevronRight button)         |
| `actions`     | `ActionMenuItem[]` | Contextual action menu items (ellipsis button — assistant variant)   |
| `description` | `ReactNode`        | Auxiliary content shown when the route is active (assistant variant) |

### RouteGroup

| Field     | Type               | Description                       |
| --------- | ------------------ | --------------------------------- |
| `id`      | `string`           | Unique identifier                 |
| `label`   | `string`           | Group title                       |
| `icon`    | `ComponentType`    | Group icon                        |
| `items`   | `RouteConfig[]`    | Navigation items in the group     |
| `actions` | `ActionMenuItem[]` | Context menu for the entire group |

---

## Examples

### 1. Monolithic API — Flat Routes

```tsx
import { Sidebar } from 'xertica-ui/layout';
import { useLayout } from 'xertica-ui/hooks';
import { useLocation, useNavigate } from 'react-router-dom';
import { Home, Settings } from 'lucide-react';

export function MySidebar() {
  const { sidebarExpanded, toggleSidebar, sidebarWidth } = useLayout();
  const location = useLocation();
  const navigate = useNavigate();

  return (
    <Sidebar
      expanded={sidebarExpanded}
      onToggle={toggleSidebar}
      width={sidebarWidth}
      location={location}
      navigate={navigate}
      routes={[
        { path: '/', label: 'Home', icon: Home },
        { path: '/settings', label: 'Settings', icon: Settings },
      ]}
    />
  );
}
```

### 2. Monolithic API — Groups with Children

```tsx
import { BarChart, Users, Settings, Home } from 'lucide-react';

<Sidebar
  navigationGroups={[
    {
      id: 'main',
      label: 'Principal',
      items: [
        { path: '/home', label: 'Início', icon: Home },
        {
          path: '/dashboard',
          label: 'Dashboard',
          icon: BarChart,
          children: [
            { path: '/dashboard/overview', label: 'Visão Geral' },
            { path: '/dashboard/reports', label: 'Relatórios' },
          ],
        },
      ],
    },
    {
      id: 'admin',
      label: 'Administração',
      items: [
        { path: '/users', label: 'Usuários', icon: Users },
        { path: '/settings', label: 'Configurações', icon: Settings },
      ],
    },
  ]}
/>;
```

### 3. Compound Component API

Use this when you need to inject custom content between sections or reorder the layout:

```tsx
import { Sidebar } from 'xertica-ui/layout';
import { Home, BarChart } from 'lucide-react';

export function CustomSidebar({ expanded, onToggle }) {
  return (
    <Sidebar.Root
      expanded={expanded}
      onToggle={onToggle}
      width={280}
      location={{ pathname: window.location.pathname }}
      navigate={path => (window.location.href = path)}
    >
      {/* Toggle button + logo */}
      <Sidebar.Header logo={<MyLogo />} logoCollapsed={<MyIcon />} />

      {/* Custom content injected between header and nav */}
      <div className="px-4 py-2">
        <span className="text-xs text-sidebar-foreground/60">v2.0.0</span>
      </div>

      {/* Navigation */}
      <Sidebar.Nav
        navigationGroups={[
          {
            id: 'main',
            items: [
              { path: '/home', label: 'Home', icon: Home },
              { path: '/dashboard', label: 'Dashboard', icon: BarChart },
            ],
          },
        ]}
      />

      {/* Footer */}
      <Sidebar.Footer
        user={{ name: 'Admin', email: 'admin@example.com' }}
        onLogout={() => signOut()}
        showUser
        showSettings
        showLogout
      />
    </Sidebar.Root>
  );
}
```

### 4. Headless Hook — Fully Custom UI

Use `useSidebar` when you need complete control over the rendered output:

```tsx
import { useSidebar } from 'xertica-ui/layout';
import { Home, BarChart } from 'lucide-react';

const groups = [
  {
    id: 'main',
    items: [
      { path: '/home', label: 'Home', icon: Home },
      { path: '/dashboard', label: 'Dashboard', icon: BarChart },
    ],
  },
];

export function MyCustomSidebar() {
  const { expanded, toggleExpanded, navigationGroups } = useSidebar({
    defaultExpanded: true,
    navigationGroups: groups,
  });

  return (
    <aside style={{ width: expanded ? 280 : 80 }}>
      <button onClick={toggleExpanded}>Toggle</button>
      <nav>
        {navigationGroups
          .flatMap(g => g.items)
          .map(item => (
            <a key={item.path} href={item.path}>
              {expanded ? item.label : null}
            </a>
          ))}
      </nav>
    </aside>
  );
}
```

---

## Accessibility (v2.1.9+)

The `default` variant sidebar ships with the following ARIA enhancements:

| Element       | Attribute       | Value                   | Description                         |
| ------------- | --------------- | ----------------------- | ----------------------------------- |
| Toggle button | `aria-expanded` | `{expanded}`            | Signals open/closed state to AT     |
| Toggle button | `aria-controls` | `"sidebar-nav"`         | Links button to the nav it controls |
| `<nav>`       | `id`            | `"sidebar-nav"`         | Target of `aria-controls`           |
| `<nav>`       | `aria-label`    | `"Navegação principal"` | Identifies the nav landmark         |

These attributes are applied automatically — no consumer configuration needed.

---

## AI Rules

- **State Management** — Always use `useLayout()` to keep the Sidebar synchronized with the main content padding. Avoid managing `expanded` locally unless using the Headless Hook pattern.
- **Icons** — Pass the icon **component source** (e.g., `HomeIcon`), not a rendered element.
- **Groups** — Use `navigationGroups` in `default` variant for structured navigation with labels. Use `routes` for flat lists.
- **Children** — Add `children` to a `RouteConfig` to expose sub-routes via a ChevronRight button at the end of the item. Do not nest more than 2 levels.
- **Assistant Mode** — Use `fixedArea` to place high-priority "Create" buttons so they remain visible regardless of scrolling.
- **Compound Components** — Use `<Sidebar.Root>` + sub-components when you need to inject custom content between sections or reorder the layout.
- **Headless Hook** — Use `useSidebar()` only when you need a completely custom sidebar UI that shares none of the default rendering.
- **location prop** — Always pass `location={useLocation()}` from `react-router-dom` when using inside a Router. Passing a stale `window.location` reference prevents active-state updates on navigation.

---

## Related Components

- [`Header`](./header.md) — Responsible for the mobile sidebar trigger.
- [`useLayout`](../layout.md) — The context provider managing sidebar state.

--- END COMPONENT: SIDEBAR ---


--- START COMPONENT: SIMPLE-MAP ---
# SimpleMap

A simplified wrapper for common map use cases where you only need a single marker and basic configuration.

---

## Import

```tsx
import { SimpleMap } from 'xertica-ui';
```

---

## Usage

### Map with Marker and Info

```tsx
<SimpleMap
  center={{ lat: -23.5505, lng: -46.6333 }}
  markerTitle="Head Office"
  markerInfo="Paulista Avenue, 1000"
  zoom={15}
/>
```

---

## Props

The `SimpleMap` component extends all non-advanced props from the base `<Map>` component.

| Prop          | Type                           | Default      | Description                                                   |
| ------------- | ------------------------------ | ------------ | ------------------------------------------------------------- |
| `center`      | `{ lat: number, lng: number }` | _(required)_ | The coordinates where the map is centered.                    |
| `address`     | `string`                       | —            | Shortcut for setting both the `markerTitle` and `markerInfo`. |
| `markerTitle` | `string`                       | —            | The title tooltip of the marker pin.                          |
| `markerInfo`  | `string`                       | —            | The HTML-safe string shown in the InfoWindow when clicked.    |
| `showMarker`  | `boolean`                      | `true`       | Whether to display the location marker at the center.         |
| `zoom`        | `number`                       | `15`         | Initial zoom level.                                           |
| `height`      | `string`                       | `"350px"`    | The height of the map container.                              |

---

## AI Rules

> [!IMPORTANT]
>
> - **Center Requirement**: Always provide a valid `center` object with `lat` and `lng`.
> - **Simplicity first**: Use `SimpleMap` for 90% of business use cases (contact pages, single store locations). Use the base `Map` only if you need polygons, circles, or multiple dynamic markers.

--- END COMPONENT: SIMPLE-MAP ---


--- START COMPONENT: SKELETON ---
# Skeleton

## Overview

A loading placeholder that mimics the shape and dimensions of content while it's being fetched. Use it to provide visual continuity and reduce perceived load time — never leave blank white space while content is loading.

---

## When to Use

- While data is being fetched asynchronously
- As a content placeholder in cards, tables, and profile areas
- For any content that takes more than ~300ms to appear

## When NOT to Use

- Full-page loading states — use a page-level skeleton layout instead of a single `Skeleton`.
- For error states — show an `<Alert>` or `<Empty>` after failure.
- Do not use spinner-only indicators when structural content (cards, tables) will appear — use Skeleton instead.

---

## Props

| Prop        | Type     | Description                                                                                     |
| ----------- | -------- | ----------------------------------------------------------------------------------------------- |
| `className` | `string` | **Required** — sets width, height, and shape. The component renders nothing visible without it. |

---

## Examples

### Card Loading Skeleton

```tsx
import { Skeleton, Card, CardContent, CardHeader } from 'xertica-ui/ui';

<Card>
  <CardHeader>
    <Skeleton className="h-5 w-[200px]" />
    <Skeleton className="h-4 w-[150px] mt-2" />
  </CardHeader>
  <CardContent className="space-y-3">
    <Skeleton className="h-4 w-full" />
    <Skeleton className="h-4 w-full" />
    <Skeleton className="h-4 w-4/5" />
  </CardContent>
</Card>;
```

### Profile Skeleton

```tsx
<div className="flex items-center space-x-4">
  <Skeleton className="h-12 w-12 rounded-full" />
  <div className="space-y-2">
    <Skeleton className="h-4 w-[200px]" />
    <Skeleton className="h-4 w-[150px]" />
  </div>
</div>
```

### Table Row Skeletons

```tsx
{
  isLoading
    ? Array.from({ length: 5 }).map((_, i) => (
        <TableRow key={i}>
          <TableCell>
            <Skeleton className="h-4 w-[100px]" />
          </TableCell>
          <TableCell>
            <Skeleton className="h-4 w-[150px]" />
          </TableCell>
          <TableCell>
            <Skeleton className="h-4 w-[80px]" />
          </TableCell>
        </TableRow>
      ))
    : records.map(record => <RecordRow key={record.id} record={record} />);
}
```

---

## AI Rules

- **Always specify dimensions** via `className` — `Skeleton` renders as a pulse animation box sized by what you give it.
- For avatar/circle placeholders: `className="h-12 w-12 rounded-full"`.
- For text lines: `className="h-4 w-full"` or any width fraction (`w-3/4`, `w-1/2`).
- Always match the approximate shape of the content it replaces (same height, similar width).

---

## Related Components

- [`Empty`](./empty.md) — For zero-state views (after loading completes with no results)
- [`Card`](./card.md) — Most common Skeleton context

--- END COMPONENT: SKELETON ---


--- START COMPONENT: SLIDER ---
# Slider

## Overview

A range input control that lets users select a numeric value by dragging a thumb along a track. Used for quantity selectors, volume controls, percentage settings, and any value within a continuous range.

---

## When to Use

- Adjusting numeric values within a range (width, volume, brightness, percentage)
- Budget or price range selectors
- Settings with numeric ranges (font size, zoom level)

## When NOT to Use

- Exact numeric entry — use `<Input type="number">` instead.
- Categorical selections — use `<RadioGroup>` or `<Select>`.

---

## Props

| Prop            | Type                         | Default | Description                           |
| --------------- | ---------------------------- | ------- | ------------------------------------- |
| `value`         | `number[]`                   | —       | Controlled value(s) — always an array |
| `defaultValue`  | `number[]`                   | —       | Uncontrolled default                  |
| `onValueChange` | `(values: number[]) => void` | —       | Change handler                        |
| `min`           | `number`                     | `0`     | Minimum value                         |
| `max`           | `number`                     | `100`   | Maximum value                         |
| `step`          | `number`                     | `1`     | Increment step                        |
| `disabled`      | `boolean`                    | `false` | Disables interaction                  |
| `className`     | `string`                     | —       | Additional CSS classes                |

---

## Examples

### Basic Controlled

```tsx
import { Slider } from 'xertica-ui/ui';
import { useState } from 'react';

const [value, setValue] = useState([50]);

<div className="space-y-2">
  <div className="flex justify-between text-sm">
    <span>Value</span>
    <span>{value[0]}%</span>
  </div>
  <Slider value={value} onValueChange={setValue} min={0} max={100} step={1} />
</div>;
```

### Sidebar Width Adjuster

```tsx
const { sidebarWidth, setSidebarWidth } = useLayout();

<Slider
  value={[sidebarWidth]}
  onValueChange={([v]) => setSidebarWidth(v)}
  min={200}
  max={480}
  step={8}
/>;
```

---

## AI Rules

- The `value` and `defaultValue` props are **always arrays** (`[50]`, not `50`) — even for single-thumb sliders.
- Access the current value as `value[0]` for single-thumb sliders.
- Always display the current value visually alongside the slider using a `<span>`.
- Do not use `onChange` — use `onValueChange`.

---

## Related Components

- [`Input`](./input.md) — For exact numeric entry
- [`Progress`](./progress.md) — For displaying a value without user interaction

--- END COMPONENT: SLIDER ---


--- START COMPONENT: SONNER ---
# Sonner (Toast Notifications)

## Overview

Sonner is the toast notification system. It displays ephemeral feedback messages that appear at a fixed position on screen (top-right by default), auto-dismiss after a few seconds, and can be dismissed manually. `<Toaster>` is auto-injected by `<XerticaProvider>` — you never need to render it manually.

---

## When to Use

- Confirming user actions: "Saved successfully", "Member added"
- Showing errors from API calls: "Failed to save changes"
- Providing undo affordance after non-destructive actions

## When NOT to Use

- Critical, persistent warnings — use inline `<Alert>` instead.
- Destructive confirmations — use `<AlertDialog>` instead.
- Validation errors in forms — use `<FormMessage>` inside `<FormField>`.

---

## Usage

Import the `toast` function from `sonner` directly — it is re-exported alongside the library:

```tsx
import { toast } from 'sonner';
```

---

## Methods

| Method                                                | Description                                |
| ----------------------------------------------------- | ------------------------------------------ |
| `toast(message)`                                      | Default neutral toast                      |
| `toast.success(message)`                              | Green success toast                        |
| `toast.error(message)`                                | Red error toast                            |
| `toast.warning(message)`                              | Amber warning toast                        |
| `toast.info(message)`                                 | Blue info toast                            |
| `toast.loading(message)`                              | Spinner toast (persistent until dismissed) |
| `toast.promise(promise, { loading, success, error })` | Auto-updates toast based on promise state  |

---

## Examples

### Basic Feedback

```tsx
import { toast } from 'sonner';

// In an event handler
toast.success('Member saved successfully');
toast.error('Failed to connect to server');
toast.warning('Your session expires in 5 minutes');
```

### With Description

```tsx
toast.error('Save failed', {
  description: 'Please check your connection and try again.',
});
```

### Promise Toast (API calls)

```tsx
toast.promise(fetch('/api/save', { method: 'POST', body: JSON.stringify(data) }), {
  loading: 'Saving...',
  success: 'Saved successfully!',
  error: 'Failed to save. Please try again.',
});
```

### With Undo Action

```tsx
toast('Member deactivated', {
  action: {
    label: 'Undo',
    onClick: () => handleReactivate(memberId),
  },
});
```

---

## Configuration

The `<Toaster>` is rendered inside `<XerticaProvider>` with `position="top-right" richColors`. You do not need to customize it unless you need a different position or theme:

```tsx
// Inside XerticaProvider — already set up
<Toaster position="top-right" richColors />
```

---

## AI Rules

- **Never add `<Toaster>` manually** — it is injected by `<XerticaProvider>`.
- Always use `toast.error()` for errors — never `toast()` with a modified className.
- For actions that modify data (save, delete, add), **always provide user feedback** via a toast.
- For API operations, use `toast.promise()` — it provides loading + success + error states automatically.
- Do not use toasts for form validation errors — those go in `<FormMessage>`.

---

## Related Components

- [`Alert`](./alert.md) — Persistent inline messages
- [`AlertDialog`](./alert-dialog.md) — Confirmation modals

--- END COMPONENT: SONNER ---


--- START COMPONENT: STATS-CARD ---
# StatsCard

## Overview

A pre-built KPI (Key Performance Indicator) card for dashboard overview pages. Renders a metric title, a large value, an optional trend indicator with automatic up/down/neutral icon, and an optional icon.

Built on top of `<Card>`. Use it for dashboard stat widgets where a consistent metric display is needed.

---

## When to Use

- Dashboard overview pages to show summary metrics (revenue, users, conversion)
- KPI widgets that need to show value + trend direction

## When NOT to Use

- For arbitrary content — use `<Card>` directly.
- When you need to heavily customize layout — compose from `<Card>` primitives instead.

---

## Props

| Prop          | Type                                | Required | Description                                                                                               |
| ------------- | ----------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `title`       | `string`                            | **Yes**  | Metric label (short)                                                                                      |
| `value`       | `string \| number`                  | **Yes**  | The displayed metric value                                                                                |
| `description` | `string`                            | No       | Additional supplementary text below the value                                                             |
| `trend`       | `{ value: number; label?: string }` | No       | Trend object. `value` is a number (positive = up, negative = down). `label` overrides `description` text. |
| `icon`        | `ReactNode`                         | No       | Icon from `lucide-react`                                                                                  |
| `iconColor`   | `string`                            | No       | Tailwind class for the icon text/foreground color (defaults to `text-muted-foreground`)                   |
| `iconBg`      | `string`                            | No       | Tailwind class for the icon background color (defaults to `bg-muted`)                                     |
| `className`   | `string`                            | No       | Additional CSS classes |

### trend

The `trend` prop controls the automatic trend icon and color:

- `trend.value > 0` → shows `TrendingUp` icon in green
- `trend.value < 0` → shows `TrendingDown` icon in red (destructive)
- `trend.value === 0` → shows `Minus` icon in muted

The numeric value is displayed as an absolute percentage: `Math.abs(trend.value)%`.

---

## Examples

### Basic KPI Card

```tsx
import { StatsCard } from 'xertica-ui/ui';
import { DollarSign } from 'lucide-react';

<StatsCard
  title="Total Revenue"
  value="$45,231.89"
  trend={{ value: 20.1, label: 'from last month' }}
  icon={<DollarSign className="size-5" />}
/>;
```

### Custom Icon Colors

```tsx
import { StatsCard } from 'xertica-ui/ui';
import { Users } from 'lucide-react';

<StatsCard
  title="Active Users"
  value="2,350"
  trend={{ value: 8.2, label: 'new this week' }}
  icon={<Users className="size-5" />}
  iconBg="bg-primary/10"
  iconColor="text-primary"
/>;
```

### Negative Trend

```tsx
<StatsCard
  title="Churn Rate"
  value="3.2%"
  trend={{ value: -0.8, label: 'vs last quarter' }}
  icon={<TrendingDown className="size-5" />}
/>
```

### Stats Grid (4 columns)

```tsx
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
  <StatsCard
    title="Revenue"
    value="$45,231"
    trend={{ value: 20.1, label: 'from last month' }}
    icon={<DollarSign className="size-5" />}
  />
  <StatsCard
    title="Active Users"
    value="2,350"
    trend={{ value: 8.2, label: 'new this week' }}
    icon={<Users className="size-5" />}
  />
  <StatsCard
    title="Conversion"
    value="3.6%"
    trend={{ value: -0.4, label: 'vs last month' }}
    icon={<Activity className="size-5" />}
  />
  <StatsCard
    title="Avg. Ticket"
    value="$89.40"
    description="All time average"
    icon={<ShoppingCart className="size-5" />}
  />
</div>
```

---

## AI Rules

- `trend.value` is a **numeric percentage** (e.g., `20.1` for +20.1%) — the component displays `Math.abs(value)%` automatically.
- Do NOT pre-format the trend value as a string — pass the raw number.
- `value` IS pre-formatted as a display string: `"$45,231"`, `"3.6%"`, `"2,350"`.
- Icons render inside a rounded background. By default, background is `bg-muted` and color is `text-muted-foreground`, but they can be customized using `iconBg` and `iconColor` props. Use `size-5` for the icon.
- Always use in a 4-column responsive grid for dashboard overviews.
- `trend.label` takes precedence over `description` for below-value text.

---

## Related Components

- [`Card`](./card.md) — The underlying primitive
- [Dashboard Pattern](../patterns/dashboard.md) — Standard usage context

--- END COMPONENT: STATS-CARD ---


--- START COMPONENT: STEPPER ---
# Stepper

## Overview

A visual multi-step progress indicator that shows the user's current position within a sequential process. Uses a composable primitive pattern: `<Stepper>` wraps one or more `<Step>` children, automatically inferring the total number of steps.

The package also exports a **headless `useStepper` hook** for building fully custom step-navigation UIs — including async validation guards before advancing — while reusing all the step-state logic.

---

## Exports

| Export             | Description                                      |
| ------------------ | ------------------------------------------------ |
| `Stepper`          | Visual step indicator component                  |
| `Step`             | Individual step item                             |
| `useStepper`       | Headless hook — all step navigation logic, no UI |
| `UseStepperProps`  | TypeScript props type for the hook               |
| `UseStepperReturn` | TypeScript return type for the hook              |

---

## When to Use

- Multi-step forms (checkout, registration, onboarding)
- Sequential configuration wizards
- Any process with 2–7 ordered steps

## When NOT to Use

- Processes with more than 7 steps — collapse or restructure.
- Simple 2-step flows — a dialog with "Next"/"Back" is sufficient.

---

## Anatomy

```tsx
<Stepper currentStep={2}>
  <Step step={1} label="Account" description="Create your account" />
  <Step step={2} label="Plan" description="Choose a plan" />
  <Step step={3} label="Confirm" description="Review and confirm" />
</Stepper>
```

- Steps are numbered from `1` (not `0`).
- Steps before `currentStep` render as **completed** (green checkmark).
- The step equal to `currentStep` renders as **active** (filled primary).
- Steps after `currentStep` render as **pending** (muted).

---

## Sub-Components

### `Stepper`

| Prop          | Type                         | Required | Description                                |
| ------------- | ---------------------------- | -------- | ------------------------------------------ |
| `currentStep` | `number`                     | **Yes**  | The currently active step (1-indexed)      |
| `orientation` | `'horizontal' \| 'vertical'` | No       | Layout direction (default: `'horizontal'`) |
| `className`   | `string`                     | No       | Additional CSS classes                     |

The step wrapper div renders with `role="list"` and `aria-label="Progresso: etapa N de M"` automatically.

### `Step`

| Prop          | Type      | Required | Description                                         |
| ------------- | --------- | -------- | --------------------------------------------------- |
| `step`        | `number`  | **Yes**  | Position of this step (1-indexed, must match order) |
| `label`       | `string`  | **Yes**  | Step label text                                     |
| `description` | `string`  | No       | Optional supplementary text below the label         |
| `error`       | `boolean` | No       | When `true`, renders the step in error state (red)  |
| `className`   | `string`  | No       | Additional CSS classes                              |

Each `<Step>` renders with `role="listitem"`, `aria-current="step"` (active step only), and `aria-label="Etapa N: Label[, concluída | , atual]"` automatically — no manual ARIA attributes needed.

---

## Examples

### Basic 3-Step Flow

```tsx
import { Stepper, Step, Button } from 'xertica-ui/ui';
import { useState } from 'react';

const [currentStep, setCurrentStep] = useState(1);

<div className="space-y-8">
  <Stepper currentStep={currentStep}>
    <Step step={1} label="Account" description="Create your account" />
    <Step step={2} label="Plan" description="Choose a plan" />
    <Step step={3} label="Confirm" description="Review and confirm" />
  </Stepper>

  <div className="min-h-[200px] flex items-center justify-center">
    <p className="text-muted-foreground">Content for step {currentStep}</p>
  </div>

  <div className="flex justify-between">
    <Button
      variant="outline"
      onClick={() => setCurrentStep(s => Math.max(1, s - 1))}
      disabled={currentStep === 1}
    >
      Previous
    </Button>
    <Button onClick={() => setCurrentStep(s => Math.min(3, s + 1))} disabled={currentStep === 3}>
      {currentStep === 3 ? 'Finish' : 'Next'}
    </Button>
  </div>
</div>;
```

---

## `useStepper` Hook

A headless hook that manages step navigation state. Supports both **uncontrolled** (internal state) and **controlled** (external `step` prop) modes, plus an optional async `onBeforeNext` guard for validating the current step before advancing.

### Props

| Prop           | Type                                                   | Default | Description                                                                                                       |
| -------------- | ------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `totalSteps`   | `number`                                               | —       | **Required.** Total number of steps in the flow                                                                   |
| `initialStep`  | `number`                                               | `1`     | Starting step (uncontrolled mode only). Automatically clamped to `[1, totalSteps]` — out-of-range values are safe |
| `step`         | `number`                                               | —       | Controlled current step — when provided, the hook uses this value instead of internal state                       |
| `onStepChange` | `(step: number) => void`                               | —       | Called whenever the step changes                                                                                  |
| `onBeforeNext` | `(currentStep: number) => boolean \| Promise<boolean>` | —       | Optional async guard — return `false` (or resolve to `false`) to block advancing to the next step                 |

### Return Value

| Property      | Type                     | Description                                                      |
| ------------- | ------------------------ | ---------------------------------------------------------------- |
| `currentStep` | `number`                 | The currently active step (1-indexed)                            |
| `totalSteps`  | `number`                 | Total number of steps                                            |
| `isFirstStep` | `boolean`                | Whether the current step is the first step                       |
| `isLastStep`  | `boolean`                | Whether the current step is the last step                        |
| `canGoPrev`   | `boolean`                | Whether navigating to the previous step is possible              |
| `canGoNext`   | `boolean`                | Whether navigating to the next step is possible                  |
| `next`        | `() => Promise<void>`    | Advance to the next step (runs `onBeforeNext` guard if provided) |
| `prev`        | `() => void`             | Go back to the previous step                                     |
| `goTo`        | `(step: number) => void` | Jump to a specific step number                                   |
| `reset`       | `() => void`             | Reset to the initial step                                        |

### Uncontrolled Example

```tsx
import { useStepper, Stepper, Step, Button } from 'xertica-ui/ui';

function OnboardingWizard() {
  const { currentStep, isFirstStep, isLastStep, next, prev } = useStepper({
    totalSteps: 3,
  });

  return (
    <div className="space-y-8">
      <Stepper currentStep={currentStep}>
        <Step step={1} label="Account" />
        <Step step={2} label="Plan" />
        <Step step={3} label="Confirm" />
      </Stepper>

      <div className="min-h-[200px]">
        {currentStep === 1 && <AccountForm />}
        {currentStep === 2 && <PlanSelector />}
        {currentStep === 3 && <ConfirmationSummary />}
      </div>

      <div className="flex justify-between">
        <Button variant="outline" onClick={prev} disabled={isFirstStep}>
          Previous
        </Button>
        <Button onClick={next} disabled={isLastStep}>
          {isLastStep ? 'Finish' : 'Next'}
        </Button>
      </div>
    </div>
  );
}
```

### With Async Validation Guard

```tsx
import { useStepper, Stepper, Step, Button } from 'xertica-ui/ui';
import { useForm } from 'react-hook-form';

function ValidatedWizard() {
  const form = useForm();

  const { currentStep, isFirstStep, isLastStep, next, prev } = useStepper({
    totalSteps: 3,
    onBeforeNext: async step => {
      // Validate only the fields relevant to the current step
      const fieldsPerStep: Record<number, string[]> = {
        1: ['email', 'password'],
        2: ['plan'],
      };
      const fields = fieldsPerStep[step];
      if (!fields) return true;
      return form.trigger(fields as never[]);
    },
  });

  return (
    <div className="space-y-8">
      <Stepper currentStep={currentStep}>
        <Step step={1} label="Account" />
        <Step step={2} label="Plan" />
        <Step step={3} label="Confirm" />
      </Stepper>

      <form>{/* step content */}</form>

      <div className="flex justify-between">
        <Button variant="outline" onClick={prev} disabled={isFirstStep}>
          Previous
        </Button>
        <Button onClick={next}>{isLastStep ? 'Submit' : 'Next'}</Button>
      </div>
    </div>
  );
}
```

### Controlled Example

```tsx
import { useStepper } from 'xertica-ui/ui';
import { useState } from 'react';

function ControlledWizard() {
  const [step, setStep] = useState(1);

  const { currentStep, next, prev, isFirstStep, isLastStep } = useStepper({
    totalSteps: 4,
    step,               // controlled
    onStepChange: setStep,
  });

  // currentStep === step at all times
  return (/* ... */);
}
```

---

## AI Rules

- `step` props on `<Step>` are **1-indexed** — the first step is `step={1}`, not `step={0}`.
- Each `<Step>` `step` prop must match its position sequentially: `1, 2, 3, ...`.
- `currentStep` on `<Stepper>` must be a number from `1` to the total number of steps.
- Always render the navigation buttons (Previous/Next) below the Stepper.
- Disable "Previous" on step `1` (`isFirstStep`) and "Next" on the final step (`isLastStep`).
- Use `onBeforeNext` for async form validation — return `false` to block advancing.
- `next()` is **async** — always `await` it or use it as an `onClick` handler directly (React handles the Promise).
- In controlled mode, pass both `step` and `onStepChange` — omitting `onStepChange` makes the hook read-only.
- Use `reset()` to return to step 1 after a successful submission.
- `initialStep` is automatically clamped to `[1, totalSteps]` — passing `0`, negative values, or values beyond `totalSteps` is safe and will not throw.
- Do NOT add `role="list"`, `aria-current`, or `aria-label` manually to `<Stepper>` or `<Step>` — they are applied automatically since v2.1.9.

---

## Related Components

- [`Progress`](./progress.md) — For generic percentage progress display
- [`Form`](./form.md) — Commonly used inside multi-step steppers

--- END COMPONENT: STEPPER ---


--- START COMPONENT: SWITCH ---
# Switch

## Overview

A binary toggle control that represents an on/off state — similar to a physical light switch. More prominent and visually expressive than a `<Checkbox>`. Used for feature toggles, notification settings, accessibility preferences, and any prominent boolean setting.

---

## When to Use

- Enabling/disabling individual features or settings
- Notification preferences
- Theme toggles
- Item visibility controls

## When NOT to Use

- Lists of independent multi-select options — use `<Checkbox>` instead.
- Single-choice from multiple options — use `<RadioGroup>` instead.
- Immediate irreversible destructive toggles — use a `<Button>` with `<AlertDialog>`.

---

## Props

| Prop              | Type                         | Default | Required | Description                                          |
| ----------------- | ---------------------------- | ------- | -------- | ---------------------------------------------------- |
| `id`              | `string`                     | —       | No       | Associates with `<Label htmlFor="...">`              |
| `size`            | `'sm' \| 'md' \| 'lg'`       | `'md'`  | No       | Size variant controlling track and thumb dimensions. |
| `checked`         | `boolean`                    | —       | No       | Controlled checked state                             |
| `defaultChecked`  | `boolean`                    | `false` | No       | Uncontrolled initial state                           |
| `onCheckedChange` | `(checked: boolean) => void` | —       | No       | Change handler                                       |
| `disabled`        | `boolean"                    | `false` | No       | Disables interaction                                 |
| `className`       | `string`                     | —       | No       | Additional CSS classes                               |

---

## Examples

### Standalone with Label

```tsx
import { Switch, Label } from 'xertica-ui/ui';
import { useState } from 'react';

const [enabled, setEnabled] = useState(false);

<div className="flex items-center space-x-2">
  <Switch id="notifications" checked={enabled} onCheckedChange={setEnabled} />
  <Label htmlFor="notifications">Email notifications</Label>
</div>;
```

### Settings List

```tsx
<div className="space-y-4">
  {[
    { id: 'email', label: 'Email Notifications' },
    { id: 'push', label: 'Push Notifications' },
    { id: 'sms', label: 'SMS Alerts' },
  ].map(({ id, label }) => (
    <div key={id} className="flex items-center justify-between">
      <Label htmlFor={id}>{label}</Label>
      <Switch id={id} />
    </div>
  ))}
</div>
```

### Inside react-hook-form

```tsx
<FormField
  control={form.control}
  name="newsletter"
  render={({ field }) => (
    <FormItem className="flex items-center justify-between p-4 border rounded-lg">
      <div>
        <FormLabel>Newsletter</FormLabel>
        <FormDescription>Receive weekly product updates</FormDescription>
      </div>
      <FormControl>
        <Switch checked={field.value} onCheckedChange={field.onChange} />
      </FormControl>
    </FormItem>
  )}
/>
```

---

## AI Rules

- Use `checked={field.value}` + `onCheckedChange={field.onChange}` in forms — **not** `{...field}`.
- **Sizing** — `Switch` supports `sm`, `md`, and `lg`. Ensure the size matches the associated `Label` size.
- Always pair with a `<Label>` for accessibility.
- For a list of settings, use `justify-between` on the row container to push the switch to the right.

---

## Related Components

- [`Checkbox`](./checkbox.md) — For multi-select lists
- [`RadioGroup`](./radio-group.md) — For single-choice selections
- [`Form`](./form.md)

--- END COMPONENT: SWITCH ---


--- START COMPONENT: TABLE ---
# Table

## Overview

Structured tabular data display. Provides semantic HTML table elements wrapped in accessible, styled components. Used in CRUD list pages, reports, and any data-heavy view where rows represent records and columns represent attributes.

---

## When to Use

- Displaying collections of records (users, products, orders)
- Comparison views with consistent attributes per row
- Reports with sortable or filterable columns

## When NOT to Use

- Key-value pairs (profile details) — use a `<Card>` with a definition list instead.
- Simple two-column data without rows — use a `<ScrollArea>` with a styled list.

---

## Anatomy

```
<Table>
  <TableHeader>
    <TableRow>
      <TableHead>Column Name</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Cell Value</TableCell>
    </TableRow>
  </TableBody>
  <TableFooter>  ← optional (totals, summaries)
    <TableRow>
      <TableCell>Total</TableCell>
    </TableRow>
  </TableFooter>
</Table>
```

---

## Sub-Components

| Component      | Description                                        |
| -------------- | -------------------------------------------------- |
| `Table`        | Wraps `<table>` with horizontal scroll on overflow |
| `TableHeader`  | Wraps `<thead>`                                    |
| `TableBody`    | Wraps `<tbody>`                                    |
| `TableFooter`  | Wraps `<tfoot>`                                    |
| `TableRow`     | Wraps `<tr>` with hover state                      |
| `TableHead`    | Wraps `<th>` with muted text                       |
| `TableCell`    | Wraps `<td>`                                       |
| `TableCaption` | Below-table caption text                           |

---

## Common Patterns

### Full CRUD Table

```tsx
import {
  Table,
  TableHeader,
  TableRow,
  TableHead,
  TableBody,
  TableCell,
  Badge,
  Button,
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
} from 'xertica-ui/ui';
import { MoreHorizontal } from 'lucide-react';

<Table>
  <TableHeader>
    <TableRow>
      <TableHead>Name</TableHead>
      <TableHead>Email</TableHead>
      <TableHead className="hidden md:table-cell">Role</TableHead>
      <TableHead>Status</TableHead>
      <TableHead className="text-right">Actions</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    {records.map(record => (
      <TableRow key={record.id}>
        <TableCell className="font-medium">{record.name}</TableCell>
        <TableCell>{record.email}</TableCell>
        <TableCell className="hidden md:table-cell">{record.role}</TableCell>
        <TableCell>
          <Badge variant="outline">{record.status}</Badge>
        </TableCell>
        <TableCell className="text-right">
          <DropdownMenu>
            <DropdownMenuTrigger asChild>
              <Button variant="ghost" size="icon" className="size-8">
                <MoreHorizontal className="size-4" />
              </Button>
            </DropdownMenuTrigger>
            <DropdownMenuContent align="end">
              <DropdownMenuItem>Edit</DropdownMenuItem>
              <DropdownMenuItem className="text-destructive">Delete</DropdownMenuItem>
            </DropdownMenuContent>
          </DropdownMenu>
        </TableCell>
      </TableRow>
    ))}
  </TableBody>
</Table>;
```

---

## AI Rules

- Always wrap the `<Table>` and its filter row (search input, filter dropdowns) inside a single `<Card>` — not separate cards.
- Status values are always `<Badge>` — never plain text.
- The actions column is always the **last column** with `className="text-right"`.
- Actions inside cells always use `<DropdownMenu>` — never standalone inline buttons for more than one action.
- Use `className="hidden md:table-cell"` on less important columns for responsive hiding.
- The primary identifying column (name, title) uses `className="font-medium"`.

---

## Related Components

- [`Badge`](./badge.md) — For status cells
- [`DropdownMenu`](./dropdown-menu.md) — For row action menus
- [`Pagination`](./pagination.md) — For paginating large tables
- [`Card`](./card.md) — Wraps the filter row + table

--- END COMPONENT: TABLE ---


--- START COMPONENT: TABS ---
# Tabs

## Overview

A content switcher that organizes related views under labelled tab triggers. One tab is active at a time. Used for multi-view dashboards, analytics pages, settings sections, and any context where content is segmented but logically related.

---

## When to Use

- Switching between related views on the same page (e.g., "Overview", "Settings", "History")
- Analytics dashboards with multiple metric categories
- Settings pages with distinct sections (General, Security, Notifications)

## When NOT to Use

- Navigating between separate pages — use `<Sidebar>` or `<NavigationMenu>` instead.
- Showing/hiding a single section — use `<Collapsible>` or `<Accordion>`.

---

## Anatomy

```
<Tabs defaultValue="tab1">
  <TabsList>
    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
  </TabsList>
  <TabsContent value="tab1">Content for tab 1</TabsContent>
  <TabsContent value="tab2">Content for tab 2</TabsContent>
</Tabs>
```

---

## Props

### Tabs

| Prop            | Type                         | Default        | Description                       |
| --------------- | ---------------------------- | -------------- | --------------------------------- |
| `defaultValue`  | `string`                     | —              | Initial active tab (uncontrolled) |
| `value`         | `string`                     | —              | Controlled active tab             |
| `onValueChange` | `(value: string) => void`    | —              | Change handler                    |
| `orientation`   | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout orientation                |

### TabsTrigger

| Prop       | Type      | Required | Description                                      |
| ---------- | --------- | -------- | ------------------------------------------------ |
| `value`    | `string`  | **Yes**  | Must match the corresponding `TabsContent` value |
| `disabled` | `boolean` | No       | Disables this tab                                |

### TabsContent

| Prop    | Type     | Required | Description                                      |
| ------- | -------- | -------- | ------------------------------------------------ |
| `value` | `string` | **Yes**  | Must match the corresponding `TabsTrigger` value |

---

## Examples

### Analytics Tabs

```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from 'xertica-ui/ui';

<Tabs defaultValue="general">
  <TabsList>
    <TabsTrigger value="general">General</TabsTrigger>
    <TabsTrigger value="performance">Performance</TabsTrigger>
    <TabsTrigger value="reports">Reports</TabsTrigger>
  </TabsList>
  <TabsContent value="general" className="mt-6">
    {/* General content */}
  </TabsContent>
  <TabsContent value="performance" className="mt-6">
    {/* Performance charts */}
  </TabsContent>
  <TabsContent value="reports" className="mt-6">
    {/* Reports table */}
  </TabsContent>
</Tabs>;
```

### Controlled

```tsx
const [tab, setTab] = useState('general');

<Tabs value={tab} onValueChange={setTab}>
  <TabsList>
    <TabsTrigger value="general">General</TabsTrigger>
    <TabsTrigger value="security">Security</TabsTrigger>
  </TabsList>
  <TabsContent value="general">...</TabsContent>
  <TabsContent value="security">...</TabsContent>
</Tabs>;
```

---

## AI Rules

- Every `TabsTrigger` must have a `value` that exactly matches a `TabsContent` `value`.
- `TabsContent` should add `className="mt-6"` or `className="mt-4"` for spacing between the tabs and content.
- `TabsList` should not have its width constrained to auto — let it fill the available horizontal space unless the design requires otherwise.
- Do not use Tabs for page-level navigation — use router and `Sidebar` for that.

---

## Related Components

- [`Accordion`](./accordion.md) — For expandable sections instead of tabs
- [`Card`](./card.md) — Tabs content often lives inside a Card

--- END COMPONENT: TABS ---


--- START COMPONENT: TEXTAREA ---
# Textarea

## Overview

A multi-line text input for longer content: descriptions, notes, messages, and rich text fields. Automatically resizable or fixed, depending on the `resize` CSS class applied.

---

## When to Use

- Bio, description, or notes fields in forms
- Message composition in chat or email forms
- Multi-line configuration values

## When NOT to Use

- Single-line inputs — use `<Input>` instead.
- Never use native `<textarea>` — always use `<Textarea>` from `xertica-ui`.

---

## Props

All native `<textarea>` HTML attributes are forwarded.

| Prop          | Type                   | Default | Description                                                                   |
| ------------- | ---------------------- | ------- | ----------------------------------------------------------------------------- |
| `size`        | `'sm' \| 'md' \| 'lg'` | `'md'`  | Size variant controlling padding and font size. Matches Input's sizing scale. |
| `placeholder` | `string`               | —       | Placeholder text                                                              |
| `disabled`    | `boolean`              | `false` | Disables interaction                                                          |
| `className`   | `string`               | —       | Additional CSS classes                                                        |
| `rows`        | `number`               | —       | Initial height in rows                                                        |

> **Note:** The `size` prop controls padding and font size only — not height. Use the `rows` prop to control vertical height.

---

## Examples

### Basic Usage

```tsx
import { Textarea } from 'xertica-ui/ui';

<Textarea placeholder="Write a description..." />;
```

### Non-Resizable (fixed height)

```tsx
<Textarea className="resize-none" rows={4} placeholder="Your message..." />
```

### Inside react-hook-form

```tsx
<FormField
  control={form.control}
  name="bio"
  render={({ field }) => (
    <FormItem className="col-span-full">
      <FormLabel>Bio</FormLabel>
      <FormControl>
        <Textarea placeholder="Tell us about yourself..." className="resize-none" {...field} />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>
```

---

## AI Rules

- **Sizing** — The `size` prop controls padding and font, matching `Input`, `SelectTrigger`, and `Search`. Use the same `size` across all form elements for consistent alignment.
- In form grids, `<Textarea>` fields always use `className="col-span-full"` to span the full width.
- Use `className="resize-none"` in most corporate contexts — free resize can break card/panel layouts.
- Always spread `{...field}` when used inside `react-hook-form` `FormField`.

---

## Related Components

- [`Input`](./input.md) — Single-line text input
- [`Form`](./form.md) — Form integration context

--- END COMPONENT: TEXTAREA ---


--- START COMPONENT: THEME-TOGGLE ---
# ThemeToggle — Xertica UI

A self-contained light/dark mode toggle button that operates directly on the `document.documentElement` class list.

---

## Import

```tsx
import { ThemeToggle } from 'xertica-ui/brand';
```

---

## Usage

### Basic (icon only)

```tsx
<ThemeToggle />
```

### With label text

```tsx
<ThemeToggle showLabel />
```

### Size and variant variants

```tsx
<ThemeToggle size="sm" variant="outline" />
<ThemeToggle size="lg" variant="default" />
```

---

## Props

| Prop        | Type                                | Default   | Description                                       |
| ----------- | ----------------------------------- | --------- | ------------------------------------------------- |
| `size`      | `'sm' \| 'md' \| 'lg'`              | `'md'`    | Controls the button and icon size                 |
| `variant`   | `'default' \| 'outline' \| 'ghost'` | `'ghost'` | Visual style of the underlying `<Button>`         |
| `showLabel` | `boolean`                           | `false`   | Whether to show "Modo Claro" / "Modo Escuro" text |
| `className` | `string`                            | `''`      | Additional CSS classes                            |

---

## Behavior

- On click, the component toggles the `dark` class on `<html>`.
- Initial state is read from `document.documentElement.classList` on mount.
- Does **not** persist to localStorage or any global state — use a shared state or `localStorage` listener at the app root level if persistence is required.
- Fully operates without any context provider.

---

## Placement Guidelines

The component is typically placed in one of two locations:

1. **Sidebar footer** — always visible regardless of current page
2. **Header actions** — adjacent to the user avatar menu

---

## AI Rules

> [!IMPORTANT]
>
> - **Do not create manual dark-mode toggles** — always use `<ThemeToggle>` from the library.
> - **One per layout shell** — do not render multiple instances simultaneously, they will conflict.
> - **No provider needed** — this component is self-contained and works anywhere in the React tree.

--- END COMPONENT: THEME-TOGGLE ---


--- START COMPONENT: TIMELINE ---
# Timeline

## Overview

A vertical sequence of events displayed chronologically, each with a timestamp, title, and optional description. Used in activity logs, audit trails, case histories, and notification feeds.

---

## When to Use

- Activity logs and audit trails
- Event histories on records (status changes, actions)
- Notification feeds on dashboards

---

## Anatomy

```
<Timeline>
  <TimelineItem>
    <TimelineDot variant="success" icon={<CheckCircle />} />
    <TimelineContent>
      <TimelineTime>Today, 09:00</TimelineTime>
      <TimelineHeading>Event Title</TimelineHeading>
      <TimelineDescription>Optional description</TimelineDescription>
    </TimelineContent>
  </TimelineItem>
</Timeline>
```

---

## TimelineDot Variants

| Variant       | Color         | Usage                    |
| ------------- | ------------- | ------------------------ |
| `default`     | Muted         | Neutral events           |
| `primary`     | Primary brand | Highlighted events       |
| `success`     | Green         | Completed actions        |
| `info`        | Blue          | Informational events     |
| `warning`     | Amber         | Caution events           |
| `destructive` | Red           | Errors or failures       |
| `outline`     | Border only   | Pending or future events |

---

## Sub-components

| Component             | Description                                    |
| --------------------- | ---------------------------------------------- |
| `Timeline`            | Root `<ol>` with the left border line          |
| `TimelineItem`        | `<li>` wrapper for a single event              |
| `TimelineDot`         | Colored dot or icon badge on the timeline line |
| `TimelineContent`     | Content area to the right of the dot           |
| `TimelineHeading`     | Event title (`<h3>`)                           |
| `TimelineTime`        | Timestamp (`<time>`)                           |
| `TimelineDescription` | Optional description paragraph                 |

---

## Examples

```tsx
import {
  Timeline,
  TimelineItem,
  TimelineDot,
  TimelineContent,
  TimelineHeading,
  TimelineTime,
  TimelineDescription,
} from 'xertica-ui/ui';
import { CheckCircle, AlertCircle, LogIn, Clock } from 'lucide-react';

<Timeline>
  <TimelineItem>
    <TimelineDot variant="default" icon={<LogIn className="size-4" />} />
    <TimelineContent>
      <TimelineHeading>Login</TimelineHeading>
      <TimelineTime>Today, 09:00</TimelineTime>
      <TimelineDescription>User logged in from Chrome on macOS</TimelineDescription>
    </TimelineContent>
  </TimelineItem>

  <TimelineItem>
    <TimelineDot variant="success" icon={<CheckCircle className="size-4" />} />
    <TimelineContent>
      <TimelineHeading>Password Changed</TimelineHeading>
      <TimelineTime>Yesterday, 16:32</TimelineTime>
    </TimelineContent>
  </TimelineItem>

  <TimelineItem>
    <TimelineDot variant="destructive" icon={<AlertCircle className="size-4" />} />
    <TimelineContent>
      <TimelineHeading>Security Alert</TimelineHeading>
      <TimelineTime>Mon, 10:15</TimelineTime>
      <TimelineDescription>Suspicious login attempt blocked</TimelineDescription>
    </TimelineContent>
  </TimelineItem>

  <TimelineItem>
    <TimelineDot variant="outline" />
    <TimelineContent>
      <TimelineHeading>Pending Review</TimelineHeading>
      <TimelineTime>Scheduled</TimelineTime>
    </TimelineContent>
  </TimelineItem>
</Timeline>;
```

---

## AI Rules

- Always compose: `Timeline > TimelineItem > (TimelineDot + TimelineContent)`.
- `TimelineTime` renders a `<time>` element — pass a pre-formatted display string, not a Date object.
- Use `TimelineDot variant="outline"` for pending or future events.
- Pass `icon` to `TimelineDot` for large icon dots; omit for small colored dots.
- For large timelines, wrap in `<ScrollArea className="h-[400px]">`.

--- END COMPONENT: TIMELINE ---


--- START COMPONENT: TOGGLE-GROUP ---
# ToggleGroup

## Overview

A set of related `<Toggle>` buttons that operate together — either allowing only one selection at a time (`type="single"`) or multiple simultaneous selections (`type="multiple"`). Used for mutually exclusive view modes, filter groups, and formatting toolbars.

---

## When to Use

- View mode switchers (Table / Grid / Kanban)
- Text alignment controls (Left / Center / Right)
- Multi-select filter chips in compact toolbars

---

## Props

### ToggleGroup

| Prop            | Type                     | Default | Required | Description          |
| --------------- | ------------------------ | ------- | -------- | -------------------- |
| `type`          | `'single' \| 'multiple'` | —       | **Yes**  | Selection mode       |
| `value`         | `string \| string[]`     | —       | No       | Controlled value(s)  |
| `defaultValue`  | `string \| string[]`     | —       | No       | Uncontrolled default |
| `onValueChange` | `(value) => void`        | —       | No       | Change handler       |

### ToggleGroupItem

| Prop         | Type     | Required        | Description                       |
| ------------ | -------- | --------------- | --------------------------------- |
| `value`      | `string` | **Yes**         | Unique identifier for this option |
| `aria-label` | `string` | Yes (icon-only) | Accessibility label               |

---

## Examples

### View Mode Switcher

```tsx
import { ToggleGroup, ToggleGroupItem } from 'xertica-ui/ui';
import { LayoutGrid, LayoutList } from 'lucide-react';

<ToggleGroup type="single" defaultValue="list">
  <ToggleGroupItem value="list" aria-label="List view">
    <LayoutList className="size-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="grid" aria-label="Grid view">
    <LayoutGrid className="size-4" />
  </ToggleGroupItem>
</ToggleGroup>;
```

---

## AI Rules

- `type` is **required** — never omit it.
- Always provide `aria-label` for icon-only items.
- For text format toolbars (bold/italic/underline), use `type="multiple"` to allow simultaneous formatting.

---

## Related Components

- [`Toggle`](./toggle.md) — Single standalone toggle
- [`RadioGroup`](./radio-group.md) — Text-heavy single-choice alternatives

--- END COMPONENT: TOGGLE-GROUP ---


--- START COMPONENT: TOGGLE ---
# Toggle

## Overview

A pressable button that maintains an on/off state visually, similar to a keyboard key that stays pressed. Used in toolbars for formatting, view switching, and feature activation.

---

## When to Use

- Text formatting toolbars (Bold, Italic, Underline)
- View mode switches (List view / Grid view)
- Filter activation buttons that remain pressed when active

## When NOT to Use

- Immediate action triggers — use `<Button>` instead.
- Feature settings — use `<Switch>` or `<Checkbox>` for clearer semantics.

---

## Props

| Prop              | Type                         | Default     | Description                        |
| ----------------- | ---------------------------- | ----------- | ---------------------------------- |
| `pressed`         | `boolean`                    | —           | Controlled pressed state           |
| `defaultPressed`  | `boolean`                    | `false`     | Uncontrolled initial state         |
| `onPressedChange` | `(pressed: boolean) => void` | —           | Change handler                     |
| `variant`         | `'default' \| 'outline'`     | `'default'` | Visual style                       |
| `size`            | `'default' \| 'sm' \| 'lg'`  | `'default'` | Size preset                        |
| `disabled`        | `boolean`                    | `false`     | Disables interaction               |
| `aria-label`      | `string`                     | —           | **Required** for icon-only toggles |

---

## Examples

```tsx
import { Toggle } from 'xertica-ui/ui';
import { Bold } from 'lucide-react';

<Toggle aria-label="Bold">
  <Bold className="size-4" />
</Toggle>;
```

### Controlled

```tsx
const [bold, setBold] = useState(false);

<Toggle pressed={bold} onPressedChange={setBold} aria-label="Bold">
  <Bold className="size-4" />
</Toggle>;
```

---

## Related Components

- [`ToggleGroup`](./toggle-group.md) — Multiple related toggles with exclusion
- [`Switch`](./switch.md) — For settings toggles with clearer on/off semantics

--- END COMPONENT: TOGGLE ---


--- START COMPONENT: TOOLTIP ---
# Tooltip

## Overview

A small floating label that appears on hover (or focus) over a trigger element, providing a short contextual explanation — typically for icon-only buttons, abbreviated text, or any element where the visual label alone isn't sufficient.

---

## When to Use

- Icon-only buttons that need a text label for clarity
- Abbreviated data that should show the full value on hover
- Action buttons where the intent isn't immediately obvious

## When NOT to Use

- Rich previews with images or complex content — use `<HoverCard>` instead.
- Persistent contextual information — use `<Popover>` or inline text instead.
- Critical information the user must read — Tooltips are hidden by default; don't put required content there.

---

## Anatomy

```
<TooltipProvider>           ← Provided by XerticaProvider
  <Tooltip>
    <TooltipTrigger asChild>
      <Button />
    </TooltipTrigger>
    <TooltipContent>
      Descriptive label
    </TooltipContent>
  </Tooltip>
</TooltipProvider>
```

> `<TooltipProvider>` is automatically included in `<XerticaProvider>`. You do not need to wrap it manually.

---

## Props

### Tooltip

| Prop            | Type                      | Default | Description           |
| --------------- | ------------------------- | ------- | --------------------- |
| `open`          | `boolean`                 | —       | Controlled open state |
| `defaultOpen`   | `boolean`                 | `false` | Uncontrolled default  |
| `onOpenChange`  | `(open: boolean) => void` | —       | State handler         |
| `delayDuration` | `number`                  | `700`   | Hover delay in ms     |

### TooltipTrigger

| Prop      | Type      | Description              |
| --------- | --------- | ------------------------ |
| `asChild` | `boolean` | Renders as child element |

### TooltipContent

| Prop         | Type                                     | Default | Description           |
| ------------ | ---------------------------------------- | ------- | --------------------- |
| `side`       | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Positioning side      |
| `sideOffset` | `number`                                 | `4`     | Distance from trigger |
| `className`  | `string`                                 | —       | Additional classes    |

---

## Examples

### Icon Button with Tooltip

```tsx
import { Tooltip, TooltipContent, TooltipTrigger, Button } from 'xertica-ui/ui';
import { Settings } from 'lucide-react';

<Tooltip>
  <TooltipTrigger asChild>
    <Button variant="ghost" size="icon" aria-label="Settings">
      <Settings className="size-4" />
    </Button>
  </TooltipTrigger>
  <TooltipContent>
    <p>Settings</p>
  </TooltipContent>
</Tooltip>;
```

### Truncated Text Preview

```tsx
<Tooltip>
  <TooltipTrigger asChild>
    <span className="truncate max-w-[150px] block">{longTitle}</span>
  </TooltipTrigger>
  <TooltipContent>
    <p>{longTitle}</p>
  </TooltipContent>
</Tooltip>
```

---

## AI Rules

- `TooltipProvider` is **not needed** — it's injected by `<XerticaProvider>`. Do not add it manually unless outside provider scope.
- Always use `<TooltipTrigger asChild>` when wrapping a `<Button>` — without `asChild` the DOM renders a button inside a button.
- Tooltip content should be a **short phrase** (2–4 words) — not long descriptions or instructions.
- Add `aria-label` to icon-only trigger buttons as well — tooltips don't replace semantic accessibility.

---

## Related Components

- [`HoverCard`](./hover-card.md) — For rich preview content on hover
- [`Popover`](./popover.md) — For persistent floating content panels

--- END COMPONENT: TOOLTIP ---


--- START COMPONENT: TREE-VIEW ---
# TreeView

## Overview

An interactive hierarchical tree component for displaying and navigating nested data structures — file systems, organizational charts, category trees, and recursive navigation menus. Supports keyboard navigation (Arrow keys, Home, End, Space), expand/collapse, and single-node selection.

The package also exports a **headless `useTreeView` hook** for building fully custom tree UIs while reusing all the expand/collapse, selection, keyboard navigation, and focus management logic.

---

## Exports

| Export              | Description                              |
| ------------------- | ---------------------------------------- |
| `TreeView`          | Ready-to-use hierarchical tree component |
| `useTreeView`       | Headless hook — all logic, no UI         |
| `TreeNode`          | TypeScript type for a single tree node   |
| `UseTreeViewProps`  | TypeScript props type for the hook       |
| `UseTreeViewReturn` | TypeScript return type for the hook      |

---

## When to Use

- File system browsers
- Organizational hierarchy viewers
- Category/tag tree navigation
- Nested menu items in the assistant sidebar variant

---

## Props

### `TreeView`

| Prop              | Type                       | Required | Description                                                                           |
| ----------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------- |
| `data`            | `TreeNode[]`               | **Yes**  | The tree data structure                                                               |
| `defaultExpanded` | `string[]`                 | No       | Node IDs to expand on initial render                                                  |
| `selectedNodeId`  | `string`                   | No       | Controlled selected node ID                                                           |
| `onNodeClick`     | `(node: TreeNode) => void` | No       | Called when any node is clicked                                                       |
| `onNodeSelect`    | `(node: TreeNode) => void` | No       | Called when a node is selected (leaf or branch)                                       |
| `ariaLabel`       | `string`                   | No       | Accessible label for the `role="tree"` container. Defaults to `"Navegação em árvore"` |
| `className`       | `string`                   | No       | Additional CSS classes                                                                |

### `TreeNode`

```typescript
interface TreeNode {
  id: string;
  label: string;
  icon?: ReactNode;
  children?: TreeNode[];
}
```

---

## Examples

### File System Browser

```tsx
import { TreeView } from 'xertica-ui/ui';
import { Folder, File } from 'lucide-react';

const tree = [
  {
    id: 'src',
    label: 'src',
    icon: <Folder className="size-4" />,
    children: [
      {
        id: 'components',
        label: 'components',
        icon: <Folder className="size-4" />,
        children: [
          { id: 'button', label: 'Button.tsx', icon: <File className="size-4" /> },
          { id: 'card', label: 'Card.tsx', icon: <File className="size-4" /> },
        ],
      },
      { id: 'app', label: 'App.tsx', icon: <File className="size-4" /> },
    ],
  },
];

<TreeView data={tree} onNodeSelect={node => console.log('Selected:', node.id)} />;
```

### Pre-expanded Nodes

```tsx
<TreeView
  data={tree}
  defaultExpanded={['src', 'components']}
  onNodeSelect={node => setSelectedFile(node.id)}
/>
```

---

## `useTreeView` Hook

A headless hook that manages expand/collapse state, selection, keyboard navigation, and focus refs for a tree structure. Use it when the `<TreeView>` component's visual design doesn't fit your needs.

### Props

| Prop              | Type                       | Default | Description                                                                                     |
| ----------------- | -------------------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `data`            | `TreeNode[]`               | —       | **Required.** The tree data structure                                                           |
| `defaultExpanded` | `string[]`                 | `[]`    | Node IDs to expand on initial render                                                            |
| `selectedNodeId`  | `string`                   | —       | Controlled selected node ID — when provided, the hook uses this value instead of internal state |
| `onNodeClick`     | `(node: TreeNode) => void` | —       | Called when any node is clicked                                                                 |
| `onNodeSelect`    | `(node: TreeNode) => void` | —       | Called when a node is selected                                                                  |

### Return Value

| Property              | Type                                                          | Description                                                                   |
| --------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `expanded`            | `Set<string>`                                                 | Set of currently expanded node IDs                                            |
| `effectiveSelectedId` | `string \| undefined`                                         | The currently selected node ID (controlled or internal)                       |
| `nodeRefs`            | `Map<string, HTMLButtonElement>`                              | Map of node ID → DOM button element refs                                      |
| `getNodeRef`          | `(nodeId: string) => (el: HTMLButtonElement \| null) => void` | Ref callback factory — attach to each node's button element                   |
| `toggleExpand`        | `(nodeId: string) => void`                                    | Toggle the expand/collapse state of a node                                    |
| `handleSelect`        | `(node: TreeNode) => void`                                    | Handle node selection (updates internal state and calls callbacks)            |
| `handleKeyDown`       | `(e: KeyboardEvent, node: TreeNode) => void`                  | Full keyboard navigation handler — attach to each node's `onKeyDown`          |
| `getVisibleNodes`     | `() => TreeNode[]`                                            | Returns the flat list of currently visible (non-collapsed) nodes in DOM order |

### Keyboard Navigation

The `handleKeyDown` handler implements the WAI-ARIA Tree Pattern 1.2:

| Key          | Action                                                                     |
| ------------ | -------------------------------------------------------------------------- |
| `ArrowDown`  | Move focus to the next visible node                                        |
| `ArrowUp`    | Move focus to the previous visible node                                    |
| `ArrowRight` | Expand a collapsed branch node; or move to first child if already expanded |
| `ArrowLeft`  | Collapse an expanded branch node; or move to parent if already collapsed   |
| `Home`       | Move focus to the first node in the tree                                   |
| `End`        | Move focus to the last visible node in the tree                            |
| `Space`      | **Branch nodes**: toggle expand/collapse. **Leaf nodes**: select           |
| `Enter`      | **All nodes**: toggle expand/collapse (if branch) **and** select           |

> **Space vs Enter (v2.1.9+)**: These keys have distinct behaviors. `Space` on a branch expands/collapses without selecting; on a leaf it selects. `Enter` always selects the node and also toggles expand if it has children. This follows WAI-ARIA Tree Pattern specification.

### Roving Tabindex (v2.1.9+)

The `<TreeView>` component uses a roving tabindex strategy: only one node is in the tab sequence at a time (`tabIndex={0}`), the rest have `tabIndex={-1}`. The focusable node is `effectiveSelectedId ?? data[0]?.id`. This means:

- Arrow keys move focus between nodes without changing tab order
- `Tab` exits the tree entirely — screen reader users navigate with Arrow keys inside the tree

### Custom Tree Example

```tsx
import { useTreeView, TreeNode } from 'xertica-ui/ui';
import { ChevronRight, ChevronDown, Folder, File } from 'lucide-react';
import { cn } from '@/shared/utils';

function CustomTree({ data }: { data: TreeNode[] }) {
  const { expanded, effectiveSelectedId, getNodeRef, toggleExpand, handleSelect, handleKeyDown } =
    useTreeView({
      data,
      defaultExpanded: [],
      onNodeSelect: node => console.log('Selected:', node.id),
    });

  const renderNode = (node: TreeNode, level: number): React.ReactNode => {
    const hasChildren = !!node.children?.length;
    const isExpanded = expanded.has(node.id);
    const isSelected = effectiveSelectedId === node.id;

    return (
      <div key={node.id}>
        <button
          ref={getNodeRef(node.id)}
          role="treeitem"
          aria-expanded={hasChildren ? isExpanded : undefined}
          aria-selected={isSelected}
          onClick={() => {
            if (hasChildren) toggleExpand(node.id);
            handleSelect(node);
          }}
          onKeyDown={e => handleKeyDown(e, node)}
          style={{ paddingLeft: `${level * 16}px` }}
          className={cn(
            'flex w-full items-center gap-2 rounded px-2 py-1 text-sm',
            isSelected ? 'bg-primary text-primary-foreground' : 'hover:bg-accent'
          )}
        >
          {hasChildren ? (
            isExpanded ? (
              <ChevronDown className="size-4 shrink-0" />
            ) : (
              <ChevronRight className="size-4 shrink-0" />
            )
          ) : (
            <span className="size-4 shrink-0" />
          )}
          {node.icon}
          <span>{node.label}</span>
        </button>

        {hasChildren && isExpanded && (
          <div role="group">{node.children!.map(child => renderNode(child, level + 1))}</div>
        )}
      </div>
    );
  };

  return (
    <div role="tree" className="w-full">
      {data.map(node => renderNode(node, 0))}
    </div>
  );
}
```

---

## AI Rules

- Each `TreeNode` must have a unique `id` — the component uses it to track expand/collapse state and selection.
- Leaf nodes (no `children`) do not show expand arrows.
- Use `lucide-react` icons with `className="size-4"` consistently across all tree nodes.
- When using `useTreeView`, attach `getNodeRef(node.id)` as the `ref` on each node's button — keyboard navigation (`handleKeyDown`) requires DOM refs to move focus.
- Attach `handleKeyDown` to `onKeyDown` on every node button — omitting it breaks keyboard accessibility.
- `getVisibleNodes()` returns only nodes that are currently visible (not inside a collapsed branch) — use it to compute `ArrowDown`/`ArrowUp` targets.
- For controlled selection, pass `selectedNodeId` — the hook will use it as `effectiveSelectedId` instead of internal state.
- `expanded` is a `Set<string>` — use `expanded.has(nodeId)` to check if a node is expanded.
- Pass `ariaLabel` to `<TreeView>` to provide a meaningful label for screen readers (e.g., `ariaLabel="File system"`, `ariaLabel="Category navigation"`). The default `"Navegação em árvore"` is in Portuguese — always override it for English-language apps.
- Do NOT manually set `tabIndex` on tree item buttons when using `<TreeView>` — roving tabindex is managed automatically since v2.1.9. When using `useTreeView`, implement roving tabindex: `tabIndex={node.id === focusableId ? 0 : -1}` where `focusableId = effectiveSelectedId ?? data[0]?.id`.

---

## Related Components

- [`Sidebar`](./sidebar.md) — Uses TreeView-style navigation for nested menu items

--- END COMPONENT: TREE-VIEW ---


--- START COMPONENT: USE-MOBILE ---
# useMobile / useIsMobile

## Overview

Two hooks that detect whether the current viewport is a mobile-width screen. Useful for conditionally rendering mobile-specific layouts, swapping components (e.g., `Drawer` vs `Sheet`), or hiding/showing content based on screen size.

---

## When to Use

- Conditionally render mobile vs desktop UI variants in the same component
- Swap between `<Drawer>` (mobile) and `<Sheet>` (desktop) panels
- Show simplified tables or cards on small screens

## When NOT to Use

- For simple layout differences — prefer Tailwind responsive classes (`hidden md:flex`) instead.
- As a replacement for CSS media queries — use these hooks only when the component tree needs to branch in React logic.

---

## Hooks

### `useMobile()`

```typescript
function useMobile(): boolean;
```

Returns `true` when the viewport width is below the mobile breakpoint (`768px` / `md`). Returns `false` on desktop.

### `useIsMobile()`

An alias for `useMobile()` — functionally identical. Use either one based on naming preference.

---

## Examples

### Conditional Sheet vs Drawer

```tsx
import { useMobile, Sheet, SheetContent, Drawer, DrawerContent } from 'xertica-ui/ui';

function FilterPanel({ open, onClose }) {
  const isMobile = useMobile();

  if (isMobile) {
    return (
      <Drawer open={open} onOpenChange={onClose}>
        <DrawerContent>{/* Filter controls */}</DrawerContent>
      </Drawer>
    );
  }

  return (
    <Sheet open={open} onOpenChange={onClose}>
      <SheetContent side="right">{/* Filter controls */}</SheetContent>
    </Sheet>
  );
}
```

### Conditional Column Display

```tsx
const isMobile = useMobile();

<Table>
  <TableHeader>
    <TableRow>
      <TableHead>Name</TableHead>
      <TableHead>Email</TableHead>
      {!isMobile && <TableHead>Role</TableHead>}
      {!isMobile && <TableHead>Created At</TableHead>}
      <TableHead>Actions</TableHead>
    </TableRow>
  </TableHeader>
</Table>;
```

---

## AI Rules

- Prefer Tailwind responsive classes (`className="hidden md:table-cell"`) over this hook for simple CSS-based visibility — reserve these hooks for cases where the React component tree needs to be different.
- The breakpoint is `768px` (`md` in Tailwind). Anything below renders as mobile.
- Both `useMobile` and `useIsMobile` are identical — do not use both in the same component.
- These hooks are reactive — they update automatically when the window is resized.

---

## Related Components

- [`Sheet`](./sheet.md) — Desktop side panel
- [`Drawer`](./drawer.md) — Mobile bottom panel

--- END COMPONENT: USE-MOBILE ---


--- START COMPONENT: VIDEO-PLAYER ---
# VideoPlayer

A feature-rich video player component with floating mode support, custom controls, and automatic state management.

---

## Overview

The `VideoPlayer` is a comprehensive video playback solution designed to deliver a seamless viewing experience across the platform. It features custom playback controls, automatic floating behavior when scrolled out of view, and full integration with the Xertica UI design system.

---

## Features

- **Custom Playback Controls**: Play/Pause, Progress Bar, Volume, Mute, Picture-in-Picture, and Fullscreen.
- **Auto-Floating Mode**: Automatically transforms into a floating window when scrolled out of view.
- **Intelligent Controls Visibility**: Controls hide after 2.5s of inactivity during playback.
- **Responsive Design**: Adapts perfectly to mobile and desktop viewports.

---

## Props

| Prop              | Type      | Default | Description                                                  |
| ----------------- | --------- | ------- | ------------------------------------------------------------ |
| `src`             | `string`  | —       | The source URL of the video.                                 |
| `poster`          | `string`  | —       | URL of an image to be shown before the video starts playing. |
| `title`           | `string`  | —       | Title of the video content.                                  |
| `autoPlay`        | `boolean` | `false` | Whether the video should start playing automatically.        |
| `enableAutoFloat` | `boolean` | `true`  | Whether the video should float when scrolled out of view.    |

---

## Examples

### Basic Video Player

```tsx
import { VideoPlayer } from 'xertica-ui/media';

<VideoPlayer src="https://example.com/video.mp4" title="My Video" />;
```

### Video with Poster Image

```tsx
<VideoPlayer
  src="https://example.com/video.mp4"
  poster="https://example.com/poster.jpg"
  title="Featured Video"
/>
```

---

## AI Rules

> [!TIP]
>
> - **Auto-Float** — The floating behavior is ideal for long-form content where users may want to continue watching while scrolling through other content.
> - **Posters** — Always provide a `poster` image for better UX, especially for videos that may take time to load.

---

## Related Components

- [`FloatingMediaWrapper`](./floating-media-wrapper.md) — The underlying wrapper for floating behavior.
- [`AudioPlayer`](./audio-player.md) — For audio playback.

--- END COMPONENT: VIDEO-PLAYER ---


--- START COMPONENT: XERTICA-LOGO ---
# XerticaLogo

The official full horizontal logotype for Xertica. It is a vector-based SVG component that ensures brand consistency across all application headers and splash screens.

---

## Import

```tsx
import { XerticaLogo } from 'xertica-ui/brand';
```

---

## Usage

```tsx
<XerticaLogo className="h-8 w-auto text-primary" />
```

---

## Props

| Prop        | Type     | Default | Description                                   |
| ----------- | -------- | ------- | --------------------------------------------- |
| `className` | `string` | —       | Standard CSS classes for sizing and coloring. |

---

## AI Rules

> [!IMPORTANT]
>
> - **Sizing**: Use responsive height utilities (e.g., `h-6 md:h-8`) rather than fixed pixel widths to maintain aspect ratio.
> - **Coloring**: The logo uses `currentColor`. Apply `text-primary` or `text-foreground` to the component to control its color.

--- END COMPONENT: XERTICA-LOGO ---


--- START COMPONENT: XERTICA-ORBE ---
# XerticaOrbe

An animated, decorative brand element representing the Xertica "Orbe". It features CSS-based pulse and rotation animations to provide a premium, dynamic feel to hero sections and loading screens.

---

## Import

```tsx
import { XerticaOrbe } from 'xertica-ui/brand';
```

---

## Usage

```tsx
<XerticaOrbe className="size-32" />
```

---

## Props

| Prop        | Type     | Default | Description                      |
| ----------- | -------- | ------- | -------------------------------- |
| `className` | `string` | —       | Standard CSS classes for sizing. |

---

## AI Rules

> [!IMPORTANT]
>
> - **Usage Context**: Do not use the Orbe as a primary logo. It is a secondary decorative element intended for splash screens, deep backgrounds, or "AI is thinking" states.

--- END COMPONENT: XERTICA-ORBE ---


--- START COMPONENT: XERTICA-PROVIDER ---
# 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.

---

## Import

```tsx
import { XerticaProvider } from 'xertica-ui/brand';
```

---

## Usage

```tsx
import { XerticaProvider } from 'xertica-ui/brand';
import 'xertica-ui/style.css';

function Root() {
  return (
    <XerticaProvider>
      <App />
    </XerticaProvider>
  );
}
```

---

## 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. |

---

## 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.

---

## 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.

--- END COMPONENT: XERTICA-PROVIDER ---


--- START COMPONENT: XERTICA-XLOGO ---
# 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).

--- END COMPONENT: XERTICA-XLOGO ---

Advanced Settings