xertica-ui 2.5.2 → 2.6.0

package/llms-compact.txt

@@ -1,444 +1,444 @@
-# Xertica UI — Compact Reference
-
-> 97-component React design system. Tailwind CSS v4 + Radix UI + Lucide Icons. v2.5.2
-> Full docs: llms-full.txt | Component index: llms.txt | Decision guide: docs/decision-tree.md
-
----
-
-## CRITICAL RULES
-
-```
-NEVER  raw <button>/<input>/<select>  → use <Button>/<Input>/<Select>
-NEVER  raw colors bg-blue-500         → use bg-primary, bg-muted, bg-destructive
-NEVER  hardcoded radius rounded-lg    → use rounded-[var(--radius)]
-NEVER  <h1>/<h2> for page headers    → use <PageHeader><PageHeaderHeading>
-NEVER  manage sidebar state locally  → use useLayout() from xertica-ui/hooks
-NEVER  render <Toaster> manually     → auto-injected by XerticaProvider
-NEVER  icons from xertica-ui         → use lucide-react exclusively
-NEVER  pass user/onLogout as props   → consume useAuth() from AuthContext
-NEVER  useState+useEffect+fetch      → use useQuery (React Query) for server data
-NEVER  hardcode UI strings in JSX    → use t('key') from useTranslation()
-ALWAYS wrap full apps in <XerticaProvider> → shared theme, toasts, tooltips, layout
-ALWAYS wrap <Routes> in <PageErrorBoundary> → prevents blank screen on chunk failures
-ALWAYS wrap data sections in <SectionErrorBoundary> → tables/charts/assistant
-ALWAYS import style.css at root      → import 'xertica-ui/style.css'
-ALWAYS confirm destructive actions   → pair with <AlertDialog> before executing
-```
-
----
-
-## IMPORTS
-
-```tsx
-import { Button, Card, Input, Badge, Table,
-         Dialog, AlertDialog, Select, Checkbox,
-         Tabs, Sheet, Popover, Tooltip, Toast,
-         PageHeader, PageHeaderHeading,
-         Progress, Skeleton, Empty, ScrollArea,
-         Separator, Form, Label, Textarea }      from 'xertica-ui/ui';
-
-import { Sidebar, Header }                       from 'xertica-ui/layout';
-import { XerticaProvider, XerticaLogo,
-         ThemeToggle, LanguageSelector }         from 'xertica-ui/brand';
-import { XerticaAssistant,
-         generateDemoResponse }                  from 'xertica-ui/assistant';
-import { VideoPlayer, AudioPlayer }              from 'xertica-ui/media';
-import { useLayout, useTheme }                   from 'xertica-ui/hooks';
-import 'xertica-ui/style.css';                   // once, at root only
-```
-
----
-
-## DESIGN TOKENS (always use these, never raw colors)
-
-```
-bg-background / text-foreground        page bg + body text
-bg-card / text-card-foreground         card surface
-bg-muted / text-muted-foreground       subdued bg + secondary text
-bg-primary / text-primary-foreground   brand primary
-bg-destructive                         danger/error
-bg-accent / text-accent-foreground     hover states
-bg-success / bg-info / bg-warning      semantic states
-border-border                          standard borders
-border-input                           form borders
---mobile-content-padding               horizontal padding on mobile < 768px (default 1.25rem)
-```
-
-## COLOR THEMES
-
-```tsx
-// Full preset — sets primary, sidebar, charts AND dark-mode surface hues
-<XerticaProvider defaultColorTheme="blue">      // blue dark bg: #03050f
-<XerticaProvider defaultColorTheme="violet">   // violet dark bg: #07040f
-<XerticaProvider defaultColorTheme="rose">     // rose dark bg: #0f0305
-<XerticaProvider defaultColorTheme="emerald">  // emerald dark bg: #030f08
-<XerticaProvider defaultColorTheme="amber">    // amber dark bg: #0f0a03
-<XerticaProvider defaultColorTheme="orange">   // orange dark bg: #0f0703
-<XerticaProvider defaultColorTheme="xertica-original"> // indigo dark bg: #05050d (default)
-
-// Custom hex primary only (dark surfaces stay neutral indigo)
-<XerticaProvider primaryColor="#7C3AED">
-```
-
----
-
-## APP STRUCTURE
-
-```tsx
-// main.tsx
-import './i18n';                      // initialize i18next BEFORE any component
-import 'xertica-ui/style.css';
-
-// App.tsx — canonical provider stack
-import { AppErrorBoundary, PageErrorBoundary } from './shared/error-boundary';
-import { QueryClient, QueryClientProvider }    from '@tanstack/react-query';
-import { XerticaProvider }                     from 'xertica-ui/brand';
-import { BrowserRouter as Router }             from 'react-router-dom';
-import { AuthProvider }                        from './app/context/AuthContext';
-
-const queryClient = new QueryClient({
-  defaultOptions: { queries: { retry: 1, refetchOnWindowFocus: false } },
-});
-
-export default function App() {
-  return (
-    <AppErrorBoundary>                   {/* catches provider/context crashes  */}
-      <QueryClientProvider client={queryClient}>
-        <XerticaProvider>
-          <Router>
-            <AuthProvider>              {/* must be inside Router              */}
-              <PageErrorBoundary>       {/* catches lazy-chunk + page errors   */}
-                <YourRoutes />
-              </PageErrorBoundary>
-            </AuthProvider>
-          </Router>
-        </XerticaProvider>
-      </QueryClientProvider>
-    </AppErrorBoundary>
-  );
-}
-```
-
-## AUTH
-
-```tsx
-// Inside <AuthProvider> — no props needed on page components
-import { useAuth } from './app/context/AuthContext';
-
-const { user, isLoading, login, logout } = useAuth();
-// isLoading: true while localStorage is being read (prevents flash redirects)
-// login(email, password): boolean — returns false on empty credentials
-// logout(): clears session + navigates to /login
-```
-
-## STATE MANAGEMENT
-
-```tsx
-// Server state → React Query (features/*/hooks/)
-import { useTeamMembers } from '../features/home';
-const { data: members = [], isLoading } = useTeamMembers();
-
-// Client UI state → Zustand (features/*/store/)
-import { useDashboardStore } from '../features/home';
-const progress = useDashboardStore(s => s.progress);
-
-// To connect to a real API — edit ONLY the fetch function in features/*/data/mock.ts:
-export async function fetchTeamMembers() {
-  return fetch('/api/team/members').then(r => r.json()); // ← swap this line
-}
-```
-
-## I18N
-
-```tsx
-import { useTranslation } from 'react-i18next';
-const { t } = useTranslation();
-return <h1>{t('home.welcome')}</h1>;   // keys in locales/pt-BR/pages/home.json (and matching en/, es/ folders)
-
-// Change language (also persists to localStorage):
-import { useLanguage } from 'xertica-ui/hooks';
-const { setLanguage } = useLanguage();
-setLanguage('en');   // → i18n.changeLanguage('en') + localStorage
-```
-
-## ERROR BOUNDARIES
-
-```tsx
-import { AppErrorBoundary, PageErrorBoundary, SectionErrorBoundary }
-  from './shared/error-boundary';
-
-// Root (catches provider crashes — inline-styled, no Tailwind needed):
-<AppErrorBoundary onError={Sentry.captureException}>…</AppErrorBoundary>
-
-// Route (catches lazy-chunk failures):
-<PageErrorBoundary resetKeys={[location.pathname]}>
-  <Suspense fallback={null}><Routes>…</Routes></Suspense>
-</PageErrorBoundary>
-
-// Section (isolates table/chart/assistant errors):
-<SectionErrorBoundary><TeamDataTable /></SectionErrorBoundary>
-```
-
----
-
-## PAGE STRUCTURE (every page must follow this)
-
-```tsx
-import { PageHeader, PageHeaderHeading, Button } from 'xertica-ui/ui';
-
-export function MyPage() {
-  return (
-    <>
-      <PageHeader>
-        <PageHeaderHeading>Title</PageHeaderHeading>
-        <Button>Primary Action</Button>
-      </PageHeader>
-      <div className="p-6 space-y-6">{/* content */}</div>
-    </>
-  );
-}
-```
-
----
-
-## LAYOUT SYSTEM
-
-```tsx
-import { useLayout } from 'xertica-ui/hooks';
-
-const { sidebarExpanded, sidebarWidth, toggleSidebar,
-        assistenteExpanded, toggleAssistente } = useLayout();
-
-// Content container must offset for sidebar:
-<div style={{ paddingLeft: sidebarExpanded ? `${sidebarWidth}px` : '80px' }}>
-```
-
----
-
-## MOST-USED COMPONENTS
-
-### Button — 9 variants
-```tsx
-<Button variant="default">Save</Button>
-<Button variant="destructive">Delete</Button>   // always pair with AlertDialog
-<Button variant="outline">Cancel</Button>
-<Button variant="ghost" size="icon" aria-label="Settings"><Settings /></Button>
-<Button asChild><Link to="/page">Go</Link></Button>  // router navigation
-```
-
-### Card
-```tsx
-<Card>
-  <CardHeader><CardTitle>Title</CardTitle></CardHeader>
-  <CardContent>Content</CardContent>
-  <CardFooter><Button>Action</Button></CardFooter>
-</Card>
-```
-
-### Input + Label (form field)
-```tsx
-<div className="space-y-2">
-  <Label htmlFor="email">Email</Label>
-  <Input id="email" type="email" placeholder="you@company.com" />
-</div>
-```
-
-### Dialog
-```tsx
-<Dialog>
-  <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
-  <DialogContent>
-    <DialogHeader><DialogTitle>Title</DialogTitle></DialogHeader>
-    <DialogBody>Content</DialogBody>  {/* scrollable */}
-    <DialogFooter><Button type="submit">Save</Button></DialogFooter>
-  </DialogContent>
-</Dialog>
-```
-
-### AlertDialog (destructive confirmation)
-```tsx
-<AlertDialog>
-  <AlertDialogTrigger asChild>
-    <Button variant="destructive">Delete</Button>
-  </AlertDialogTrigger>
-  <AlertDialogContent>
-    <AlertDialogHeader>
-      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
-      <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
-    </AlertDialogHeader>
-    <AlertDialogFooter>
-      <AlertDialogCancel>Cancel</AlertDialogCancel>
-      <AlertDialogAction onClick={handleDelete}>Delete</AlertDialogAction>
-    </AlertDialogFooter>
-  </AlertDialogContent>
-</AlertDialog>
-```
-
-### Table (CRUD list)
-```tsx
-<Table>
-  <TableHeader>
-    <TableRow><TableHead>Name</TableHead><TableHead>Status</TableHead></TableRow>
-  </TableHeader>
-  <TableBody>
-    {items.map(item => (
-      <TableRow key={item.id}>
-        <TableCell>{item.name}</TableCell>
-        <TableCell><Badge variant="success">{item.status}</Badge></TableCell>
-      </TableRow>
-    ))}
-  </TableBody>
-</Table>
-```
-
-### Toast (via sonner)
-```tsx
-import { toast } from 'sonner';
-
-toast.success('Saved!');
-toast.error('Failed to save');
-toast.info('Processing...');
-// Never render <Toaster> — auto-injected by XerticaProvider
-```
-
-### Select
-```tsx
-<Select onValueChange={setValue}>
-  <SelectTrigger><SelectValue placeholder="Choose..." /></SelectTrigger>
-  <SelectContent>
-    <SelectItem value="a">Option A</SelectItem>
-    <SelectItem value="b">Option B</SelectItem>
-  </SelectContent>
-</Select>
-```
-
-### Sidebar
-```tsx
-import { Sidebar }   from 'xertica-ui/layout';
-import { useLayout } from 'xertica-ui/hooks';
-import { useNavigate, useLocation } from 'react-router-dom';
-
-function AppSidebar({ user, onLogout }) {
-  const { sidebarExpanded, sidebarWidth, toggleSidebar } = useLayout();
-  return (
-    <Sidebar
-      expanded={sidebarExpanded}
-      onToggle={toggleSidebar}
-      width={sidebarWidth}
-      navigate={useNavigate()}
-      location={useLocation()}
-      routes={[
-        { path: '/home', label: 'Home', icon: Home },
-        { path: '/settings', label: 'Settings', icon: Settings },
-      ]}
-      user={user}
-      onLogout={onLogout}
-    />
-  );
-}
-
-// Sub-items (children) — desktop: ChevronRight opens a lateral DropdownMenu
-//                       mobile:  ChevronRight expands items inline (accordion)
-navigationGroups={[{
-  id: 'main', label: 'Principal',
-  items: [{
-    path: '/dashboard', label: 'Dashboard', icon: BarChart,
-    children: [
-      { path: '/dashboard/overview', label: 'Visão Geral', icon: BarChart },
-      { path: '/dashboard/reports',  label: 'Relatórios',  icon: FileEdit },
-    ],
-  }],
-}]}
-```
-
-### Header
-```tsx
-import { Header } from 'xertica-ui/layout';
-
-<Header
-  breadcrumbs={[{ label: 'Home', href: '/home' }, { label: 'Settings' }]}
-  user={user}
-  onLogout={onLogout}
-/>
-```
-
-### Empty state
-```tsx
-<Empty>
-  <EmptyIcon><FileX className="size-12 text-muted-foreground" /></EmptyIcon>
-  <EmptyTitle>No results</EmptyTitle>
-  <EmptyDescription>Try adjusting your filters.</EmptyDescription>
-  <EmptyAction><Button>Clear filters</Button></EmptyAction>
-</Empty>
-```
-
-### StatsCard (dashboard KPI)
-```tsx
-<StatsCard
-  title="Total Users"
-  value="12,430"
-  trend={8.2}
-  icon={<Users className="size-4" />}
-/>
-```
-
----
-
-## QUICK COMPONENT SELECTION
-
-| Need | Use |
-|---|---|
-| User must confirm before proceeding | `AlertDialog` |
-| Form or detail view in overlay | `Dialog` |
-| Wide form from the side | `Sheet` |
-| Mobile overlay from bottom | `Drawer` |
-| Anchored interactive panel | `Popover` |
-| Short hover hint | `Tooltip` |
-| Rich hover preview | `HoverCard` |
-| Ephemeral message | `toast()` (sonner) |
-| Persistent inline message | `Alert` |
-| Loading state | `Skeleton` |
-| No data | `Empty` |
-| Multi-step flow | `Stepper` |
-| Tab switching | `Tabs` |
-| Collapsible FAQ/list | `Accordion` |
-| Single expandable | `Collapsible` |
-| Date input | `Calendar` + `Popover` |
-| Numeric range | `Slider` |
-| One of many options | `RadioGroup` or `Select` |
-| On/off setting | `Switch` |
-| Multi-select list | `Checkbox` group |
-| Search/filter | `Search` or `Command` |
-| Row actions | `DropdownMenu` |
-| Right-click actions | `ContextMenu` |
-
----
-
-## FORM PATTERN (react-hook-form + zod)
-
-```tsx
-import { useForm } from 'react-hook-form';
-import { zodResolver } from '@hookform/resolvers/zod';
-import { z } from 'zod';
-import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from 'xertica-ui/ui';
-
-const schema = z.object({ name: z.string().min(2) });
-
-function MyForm() {
-  const form = useForm({ resolver: zodResolver(schema) });
-  return (
-    <Form {...form}>
-      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
-        <FormField control={form.control} name="name" render={({ field }) => (
-          <FormItem>
-            <FormLabel>Name</FormLabel>
-            <FormControl><Input {...field} /></FormControl>
-            <FormMessage />
-          </FormItem>
-        )} />
-        <Button type="submit">Submit</Button>
-      </form>
-    </Form>
-  );
-}
-```
+# Xertica UI — Compact Reference
+
+> 97-component React design system. Tailwind CSS v4 + Radix UI + Lucide Icons. v2.5.3
+> Full docs: llms-full.txt | Component index: llms.txt | Decision guide: docs/decision-tree.md
+
+---
+
+## CRITICAL RULES
+
+```
+NEVER  raw <button>/<input>/<select>  → use <Button>/<Input>/<Select>
+NEVER  raw colors bg-blue-500         → use bg-primary, bg-muted, bg-destructive
+NEVER  hardcoded radius rounded-lg    → use rounded-[var(--radius)]
+NEVER  <h1>/<h2> for page headers    → use <PageHeader><PageHeaderHeading>
+NEVER  manage sidebar state locally  → use useLayout() from xertica-ui/hooks
+NEVER  render <Toaster> manually     → auto-injected by XerticaProvider
+NEVER  icons from xertica-ui         → use lucide-react exclusively
+NEVER  pass user/onLogout as props   → consume useAuth() from AuthContext
+NEVER  useState+useEffect+fetch      → use useQuery (React Query) for server data
+NEVER  hardcode UI strings in JSX    → use t('key') from useTranslation()
+ALWAYS wrap full apps in <XerticaProvider> → shared theme, toasts, tooltips, layout
+ALWAYS wrap <Routes> in <PageErrorBoundary> → prevents blank screen on chunk failures
+ALWAYS wrap data sections in <SectionErrorBoundary> → tables/charts/assistant
+ALWAYS import style.css at root      → import 'xertica-ui/style.css'
+ALWAYS confirm destructive actions   → pair with <AlertDialog> before executing
+```
+
+---
+
+## IMPORTS
+
+```tsx
+import { Button, Card, Input, Badge, Table,
+         Dialog, AlertDialog, Select, Checkbox,
+         Tabs, Sheet, Popover, Tooltip, Toast,
+         PageHeader, PageHeaderHeading,
+         Progress, Skeleton, Empty, ScrollArea,
+         Separator, Form, Label, Textarea }      from 'xertica-ui/ui';
+
+import { Sidebar, Header }                       from 'xertica-ui/layout';
+import { XerticaProvider, XerticaLogo,
+         ThemeToggle, LanguageSelector }         from 'xertica-ui/brand';
+import { XerticaAssistant,
+         generateDemoResponse }                  from 'xertica-ui/assistant';
+import { VideoPlayer, AudioPlayer }              from 'xertica-ui/media';
+import { useLayout, useTheme }                   from 'xertica-ui/hooks';
+import 'xertica-ui/style.css';                   // once, at root only
+```
+
+---
+
+## DESIGN TOKENS (always use these, never raw colors)
+
+```
+bg-background / text-foreground        page bg + body text
+bg-card / text-card-foreground         card surface
+bg-muted / text-muted-foreground       subdued bg + secondary text
+bg-primary / text-primary-foreground   brand primary
+bg-destructive                         danger/error
+bg-accent / text-accent-foreground     hover states
+bg-success / bg-info / bg-warning      semantic states
+border-border                          standard borders
+border-input                           form borders
+--mobile-content-padding               horizontal padding on mobile < 768px (default 1.25rem)
+```
+
+## COLOR THEMES
+
+```tsx
+// Full preset — sets primary, sidebar, charts AND dark-mode surface hues
+<XerticaProvider defaultColorTheme="blue">      // blue dark bg: #03050f
+<XerticaProvider defaultColorTheme="violet">   // violet dark bg: #07040f
+<XerticaProvider defaultColorTheme="rose">     // rose dark bg: #0f0305
+<XerticaProvider defaultColorTheme="emerald">  // emerald dark bg: #030f08
+<XerticaProvider defaultColorTheme="amber">    // amber dark bg: #0f0a03
+<XerticaProvider defaultColorTheme="orange">   // orange dark bg: #0f0703
+<XerticaProvider defaultColorTheme="xertica-original"> // indigo dark bg: #05050d (default)
+
+// Custom hex primary only (dark surfaces stay neutral indigo)
+<XerticaProvider primaryColor="#7C3AED">
+```
+
+---
+
+## APP STRUCTURE
+
+```tsx
+// main.tsx
+import './i18n';                      // initialize i18next BEFORE any component
+import 'xertica-ui/style.css';
+
+// App.tsx — canonical provider stack
+import { AppErrorBoundary, PageErrorBoundary } from './shared/error-boundary';
+import { QueryClient, QueryClientProvider }    from '@tanstack/react-query';
+import { XerticaProvider }                     from 'xertica-ui/brand';
+import { BrowserRouter as Router }             from 'react-router-dom';
+import { AuthProvider }                        from './app/context/AuthContext';
+
+const queryClient = new QueryClient({
+  defaultOptions: { queries: { retry: 1, refetchOnWindowFocus: false } },
+});
+
+export default function App() {
+  return (
+    <AppErrorBoundary>                   {/* catches provider/context crashes  */}
+      <QueryClientProvider client={queryClient}>
+        <XerticaProvider>
+          <Router>
+            <AuthProvider>              {/* must be inside Router              */}
+              <PageErrorBoundary>       {/* catches lazy-chunk + page errors   */}
+                <YourRoutes />
+              </PageErrorBoundary>
+            </AuthProvider>
+          </Router>
+        </XerticaProvider>
+      </QueryClientProvider>
+    </AppErrorBoundary>
+  );
+}
+```
+
+## AUTH
+
+```tsx
+// Inside <AuthProvider> — no props needed on page components
+import { useAuth } from './app/context/AuthContext';
+
+const { user, isLoading, login, logout } = useAuth();
+// isLoading: true while localStorage is being read (prevents flash redirects)
+// login(email, password): boolean — returns false on empty credentials
+// logout(): clears session + navigates to /login
+```
+
+## STATE MANAGEMENT
+
+```tsx
+// Server state → React Query (features/*/hooks/)
+import { useTeamMembers } from '../features/home';
+const { data: members = [], isLoading } = useTeamMembers();
+
+// Client UI state → Zustand (features/*/store/)
+import { useDashboardStore } from '../features/home';
+const progress = useDashboardStore(s => s.progress);
+
+// To connect to a real API — edit ONLY the fetch function in features/*/data/mock.ts:
+export async function fetchTeamMembers() {
+  return fetch('/api/team/members').then(r => r.json()); // ← swap this line
+}
+```
+
+## I18N
+
+```tsx
+import { useTranslation } from 'react-i18next';
+const { t } = useTranslation();
+return <h1>{t('home.welcome')}</h1>;   // keys in locales/pt-BR/pages/home.json (and matching en/, es/ folders)
+
+// Change language (also persists to localStorage):
+import { useLanguage } from 'xertica-ui/hooks';
+const { setLanguage } = useLanguage();
+setLanguage('en');   // → i18n.changeLanguage('en') + localStorage
+```
+
+## ERROR BOUNDARIES
+
+```tsx
+import { AppErrorBoundary, PageErrorBoundary, SectionErrorBoundary }
+  from './shared/error-boundary';
+
+// Root (catches provider crashes — inline-styled, no Tailwind needed):
+<AppErrorBoundary onError={Sentry.captureException}>…</AppErrorBoundary>
+
+// Route (catches lazy-chunk failures):
+<PageErrorBoundary resetKeys={[location.pathname]}>
+  <Suspense fallback={null}><Routes>…</Routes></Suspense>
+</PageErrorBoundary>
+
+// Section (isolates table/chart/assistant errors):
+<SectionErrorBoundary><TeamDataTable /></SectionErrorBoundary>
+```
+
+---
+
+## PAGE STRUCTURE (every page must follow this)
+
+```tsx
+import { PageHeader, PageHeaderHeading, Button } from 'xertica-ui/ui';
+
+export function MyPage() {
+  return (
+    <>
+      <PageHeader>
+        <PageHeaderHeading>Title</PageHeaderHeading>
+        <Button>Primary Action</Button>
+      </PageHeader>
+      <div className="p-6 space-y-6">{/* content */}</div>
+    </>
+  );
+}
+```
+
+---
+
+## LAYOUT SYSTEM
+
+```tsx
+import { useLayout } from 'xertica-ui/hooks';
+
+const { sidebarExpanded, sidebarWidth, toggleSidebar,
+        assistenteExpanded, toggleAssistente } = useLayout();
+
+// Content container must offset for sidebar:
+<div style={{ paddingLeft: sidebarExpanded ? `${sidebarWidth}px` : '80px' }}>
+```
+
+---
+
+## MOST-USED COMPONENTS
+
+### Button — 9 variants
+```tsx
+<Button variant="default">Save</Button>
+<Button variant="destructive">Delete</Button>   // always pair with AlertDialog
+<Button variant="outline">Cancel</Button>
+<Button variant="ghost" size="icon" aria-label="Settings"><Settings /></Button>
+<Button asChild><Link to="/page">Go</Link></Button>  // router navigation
+```
+
+### Card
+```tsx
+<Card>
+  <CardHeader><CardTitle>Title</CardTitle></CardHeader>
+  <CardContent>Content</CardContent>
+  <CardFooter><Button>Action</Button></CardFooter>
+</Card>
+```
+
+### Input + Label (form field)
+```tsx
+<div className="space-y-2">
+  <Label htmlFor="email">Email</Label>
+  <Input id="email" type="email" placeholder="you@company.com" />
+</div>
+```
+
+### Dialog
+```tsx
+<Dialog>
+  <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
+  <DialogContent>
+    <DialogHeader><DialogTitle>Title</DialogTitle></DialogHeader>
+    <DialogBody>Content</DialogBody>  {/* scrollable */}
+    <DialogFooter><Button type="submit">Save</Button></DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### AlertDialog (destructive confirmation)
+```tsx
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="destructive">Delete</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+      <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction onClick={handleDelete}>Delete</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+### Table (CRUD list)
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow><TableHead>Name</TableHead><TableHead>Status</TableHead></TableRow>
+  </TableHeader>
+  <TableBody>
+    {items.map(item => (
+      <TableRow key={item.id}>
+        <TableCell>{item.name}</TableCell>
+        <TableCell><Badge variant="success">{item.status}</Badge></TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+### Toast (via sonner)
+```tsx
+import { toast } from 'sonner';
+
+toast.success('Saved!');
+toast.error('Failed to save');
+toast.info('Processing...');
+// Never render <Toaster> — auto-injected by XerticaProvider
+```
+
+### Select
+```tsx
+<Select onValueChange={setValue}>
+  <SelectTrigger><SelectValue placeholder="Choose..." /></SelectTrigger>
+  <SelectContent>
+    <SelectItem value="a">Option A</SelectItem>
+    <SelectItem value="b">Option B</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Sidebar
+```tsx
+import { Sidebar }   from 'xertica-ui/layout';
+import { useLayout } from 'xertica-ui/hooks';
+import { useNavigate, useLocation } from 'react-router-dom';
+
+function AppSidebar({ user, onLogout }) {
+  const { sidebarExpanded, sidebarWidth, toggleSidebar } = useLayout();
+  return (
+    <Sidebar
+      expanded={sidebarExpanded}
+      onToggle={toggleSidebar}
+      width={sidebarWidth}
+      navigate={useNavigate()}
+      location={useLocation()}
+      routes={[
+        { path: '/home', label: 'Home', icon: Home },
+        { path: '/settings', label: 'Settings', icon: Settings },
+      ]}
+      user={user}
+      onLogout={onLogout}
+    />
+  );
+}
+
+// Sub-items (children) — desktop: ChevronRight opens a lateral DropdownMenu
+//                       mobile:  ChevronRight expands items inline (accordion)
+navigationGroups={[{
+  id: 'main', label: 'Principal',
+  items: [{
+    path: '/dashboard', label: 'Dashboard', icon: BarChart,
+    children: [
+      { path: '/dashboard/overview', label: 'Visão Geral', icon: BarChart },
+      { path: '/dashboard/reports',  label: 'Relatórios',  icon: FileEdit },
+    ],
+  }],
+}]}
+```
+
+### Header
+```tsx
+import { Header } from 'xertica-ui/layout';
+
+<Header
+  breadcrumbs={[{ label: 'Home', href: '/home' }, { label: 'Settings' }]}
+  user={user}
+  onLogout={onLogout}
+/>
+```
+
+### Empty state
+```tsx
+<Empty>
+  <EmptyIcon><FileX className="size-12 text-muted-foreground" /></EmptyIcon>
+  <EmptyTitle>No results</EmptyTitle>
+  <EmptyDescription>Try adjusting your filters.</EmptyDescription>
+  <EmptyAction><Button>Clear filters</Button></EmptyAction>
+</Empty>
+```
+
+### StatsCard (dashboard KPI)
+```tsx
+<StatsCard
+  title="Total Users"
+  value="12,430"
+  trend={8.2}
+  icon={<Users className="size-4" />}
+/>
+```
+
+---
+
+## QUICK COMPONENT SELECTION
+
+| Need | Use |
+|---|---|
+| User must confirm before proceeding | `AlertDialog` |
+| Form or detail view in overlay | `Dialog` |
+| Wide form from the side | `Sheet` |
+| Mobile overlay from bottom | `Drawer` |
+| Anchored interactive panel | `Popover` |
+| Short hover hint | `Tooltip` |
+| Rich hover preview | `HoverCard` |
+| Ephemeral message | `toast()` (sonner) |
+| Persistent inline message | `Alert` |
+| Loading state | `Skeleton` |
+| No data | `Empty` |
+| Multi-step flow | `Stepper` |
+| Tab switching | `Tabs` |
+| Collapsible FAQ/list | `Accordion` |
+| Single expandable | `Collapsible` |
+| Date input | `Calendar` + `Popover` |
+| Numeric range | `Slider` |
+| One of many options | `RadioGroup` or `Select` |
+| On/off setting | `Switch` |
+| Multi-select list | `Checkbox` group |
+| Search/filter | `Search` or `Command` |
+| Row actions | `DropdownMenu` |
+| Right-click actions | `ContextMenu` |
+
+---
+
+## FORM PATTERN (react-hook-form + zod)
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from 'xertica-ui/ui';
+
+const schema = z.object({ name: z.string().min(2) });
+
+function MyForm() {
+  const form = useForm({ resolver: zodResolver(schema) });
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+        <FormField control={form.control} name="name" render={({ field }) => (
+          <FormItem>
+            <FormLabel>Name</FormLabel>
+            <FormControl><Input {...field} /></FormControl>
+            <FormMessage />
+          </FormItem>
+        )} />
+        <Button type="submit">Submit</Button>
+      </form>
+    </Form>
+  );
+}
+```