xertica-ui 2.1.2 → 2.1.3

package/llms-compact.txt

@@ -1,327 +1,327 @@
-# Xertica UI — Compact Reference
-
-> 97-component React design system. Tailwind CSS v4 + Radix UI + Lucide Icons.
-> 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
-ALWAYS wrap full apps in <XerticaProvider> → shared theme, toasts, tooltips, layout
-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
-```
-
----
-
-## APP STRUCTURE
-
-```tsx
-// main.tsx
-import { XerticaProvider } from 'xertica-ui/brand';
-import { BrowserRouter }   from 'react-router-dom';
-import 'xertica-ui/style.css';
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <XerticaProvider>
-    <BrowserRouter><App /></BrowserRouter>
-  </XerticaProvider>
-);
-```
-
----
-
-## 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}
-    />
-  );
-}
-```
-
-### 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.
+> 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
+ALWAYS wrap full apps in <XerticaProvider> → shared theme, toasts, tooltips, layout
+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
+```
+
+---
+
+## APP STRUCTURE
+
+```tsx
+// main.tsx
+import { XerticaProvider } from 'xertica-ui/brand';
+import { BrowserRouter }   from 'react-router-dom';
+import 'xertica-ui/style.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <XerticaProvider>
+    <BrowserRouter><App /></BrowserRouter>
+  </XerticaProvider>
+);
+```
+
+---
+
+## 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}
+    />
+  );
+}
+```
+
+### 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>
+  );
+}
+```