xertica-ui 2.5.2 → 2.6.0

package/llms.txt

@@ -1,187 +1,187 @@
-# Xertica UI
-
-> Enterprise-grade React design system — 97 components built on Tailwind CSS v4, Radix UI, and Lucide Icons. Designed to be consumed directly by AI coding agents (LLMs, Cursor, Claude Code, Copilot). v2.5.2
-
-Xertica UI ships with full source, typed declarations, Storybook stories, and structured documentation inside `node_modules/xertica-ui/`. AI agents should read this file first, then follow links for component-specific detail.
-
-## Quick Start
-
-- [Getting Started](docs/getting-started.md): Provider setup, theming, routing integration, and subpath import patterns.
-- [Installation](docs/installation.md): Peer dependencies, CSS import, and provider setup steps.
-- [AI Usage Rules](docs/ai-usage.md): Mandatory rules for AI agents — what is permitted, what is forbidden.
-- [Compact Reference](llms-full.txt): Complete documentation of all 97 components in a single file (large context LLMs).
-- [Compact Quick-Reference](llms-compact.txt): ~4K token summary — import patterns, critical rules, most-used components.
-- [Component Selection Guide](docs/decision-tree.md): Decision trees for Dialog vs Sheet, Tooltip vs HoverCard, etc.
-
-## Critical Rules (read before generating any code)
-
-1. **Never use raw HTML elements** — `<button>`, `<input>`, `<select>` → always use library components.
-2. **Never use raw colors** — `bg-blue-500`, `#3b82f6` → always use semantic tokens (`bg-primary`, `bg-muted`).
-3. **Never use hardcoded radii** — `rounded-lg` → always `rounded-[var(--radius)]`.
-4. **Every page requires `<PageHeader>`** — never use `<h1>` or `<h2>` for page titles.
-5. **Wrap apps in `<XerticaProvider>`** — recommended for synchronized theme, toasts, tooltips, layout, assistant state, maps, and API keys.
-6. **Import `xertica-ui/style.css` once** at the root entry file.
-7. **Icons come from `lucide-react`** — never from `xertica-ui`.
-8. **Layout state from `useLayout()`** — never hardcode sidebar widths.
-9. **Destructive actions require `<AlertDialog>`** — never execute directly on click.
-10. **`<Toaster>` is auto-injected** by `<XerticaProvider>` — never render it manually.
-11. **Wrap `<Routes>` in `<PageErrorBoundary>`** — prevents lazy-chunk failures from showing a blank screen.
-12. **Wrap data sections in `<SectionErrorBoundary>`** — tables, charts, and the assistant must not crash the page.
-13. **Auth state from `useAuth()`** — never pass `user` or `onLogout` as props to page components; consume from `AuthContext`.
-14. **Server data from `useQuery` (React Query)** — never `useState + useEffect + fetch` for API data.
-15. **UI strings from `useTranslation()`** — never hardcode text in JSX; add keys to the appropriate file under `locales/<lang>/` (e.g., `locales/pt-BR/common.json` for shared labels, `locales/pt-BR/pages/home.json` for page strings).
-
-## State Management & Auth
-
-- [State Management Guide](docs/state-management.md): React Query, Zustand, AuthContext, `features/` slice pattern, decision tree.
-- [i18n Guide](docs/i18n.md): i18next setup, `useTranslation`, locale files, language switching.
-- **`useAuth()`** — `{ user, isLoading, login, logout }` from `AuthContext`. Must be inside `<AuthProvider>` (inside `<Router>`).
-- **`useQuery`** — server state. Use hooks in `features/*/hooks/`. Swap `fetch*` in `features/*/data/mock.ts` for real API.
-- **Zustand** — client UI state. Use stores in `features/*/store/`.
-- **Provider stack**: `AppErrorBoundary > QueryClientProvider > XerticaProvider > Router > AuthProvider > PageErrorBoundary > Routes`.
-
-## Error Boundaries
-
-- [ErrorBoundary docs](docs/components/error-boundary.md): Full API, placement guide, AI rules.
-- **`AppErrorBoundary`** — outermost; full-screen inline-styled fallback; catches provider crashes.
-- **`PageErrorBoundary`** — wraps `<Routes>`; catches lazy-chunk failures and page render errors.
-- **`SectionErrorBoundary`** — wraps data sections (table, chart, assistant); compact inline fallback.
-- Import: `import { AppErrorBoundary, PageErrorBoundary, SectionErrorBoundary } from '@/shared/error-boundary';`
-
-## Component Reference — Shared Utilities
-
-- [ErrorBoundary](docs/components/error-boundary.md): `AppErrorBoundary`, `PageErrorBoundary`, `SectionErrorBoundary`, `ErrorBoundary` (base class). Props: `onError`, `resetKeys`.
-
-## Import Patterns
-
-```tsx
-import { Button, Card, Input, Badge, Table, Dialog } from 'xertica-ui/ui';
-import { Sidebar, Header }                           from 'xertica-ui/layout';
-import { XerticaProvider, XerticaLogo, ThemeToggle } 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';
-```
-
-## Component Reference — UI Primitives (`xertica-ui/ui`)
-
-- [Accordion](docs/components/accordion.md): Vertically stacked collapsible sections. Use for FAQs, settings panels, dense trees.
-- [Alert](docs/components/alert.md): Inline persistent status banner. Use when the message must stay visible.
-- [AlertDialog](docs/components/alert-dialog.md): Blocking confirmation modal. Required before any destructive action.
-- [AspectRatio](docs/components/aspect-ratio.md): Fixed-ratio media container. Prevents layout shifts.
-- [Avatar](docs/components/avatar.md): User identity — photo or initials fallback.
-- [Badge](docs/components/badge.md): Compact non-interactive status label or count chip.
-- [Breadcrumb](docs/components/breadcrumb.md): Hierarchical navigation trail. Rendered inside `Header`.
-- [Button](docs/components/button.md): Primary interaction trigger. 9 variants: default, secondary, outline, ghost, destructive, link, success, info, warning.
-- [Calendar](docs/components/calendar.md): Date picker. Almost always wrapped in `Popover`.
-- [Card](docs/components/card.md): Primary content container. Never recreate with raw `<div>`.
-- [Carousel](docs/components/carousel.md): Horizontal content slider. Built on embla-carousel.
-- [Chart](docs/components/chart.md): Token-aware charts built on Recharts. Use `ChartContainer`; 11 dashboard-ready wrappers: `ChartCard`, `DashboardBarChart`, `DashboardLineChart`, `HorizontalBarChart`, `InteractiveTimeSeriesChart`, `ComboMetricChart`, `DonutBreakdownChart`, `SparklineChart`, `RadarMetricChart`, `PieMetricChart`, `RadialBarMetricChart`, and `GaugeChart` (pure SVG semicircle gauge with thresholds).
-- [Checkbox](docs/components/checkbox.md): Boolean toggle or multi-select option.
-- [Collapsible](docs/components/collapsible.md): Single expandable section — no sibling management.
-- [Command](docs/components/command.md): Command palette (⌘K). Searchable action list.
-- [ContextMenu](docs/components/context-menu.md): Right-click menu.
-- [Dialog](docs/components/dialog.md): Modal overlay. Dismissible. Use for forms and detail views.
-- [Drawer](docs/components/drawer.md): Bottom-sliding panel. Mobile-optimized equivalent of Sheet.
-- [DropdownMenu](docs/components/dropdown-menu.md): Triggered contextual action menu.
-- [Empty](docs/components/empty.md): Zero-state container for lists and search results.
-- [FileUpload](docs/components/file-upload.md): Drag-and-drop file input.
-- [Form](docs/components/form.md): react-hook-form integration layer.
-- [HoverCard](docs/components/hover-card.md): Rich floating preview on hover. Use for user profiles, link previews.
-- [Input](docs/components/input.md): Single-line text field.
-- [InputOTP](docs/components/input-otp.md): OTP / PIN code segmented input.
-- [Label](docs/components/label.md): Accessible form field label. Always paired with Input via `htmlFor`.
-- [Menubar](docs/components/menubar.md): Application-style horizontal menu bar.
-- [NavigationMenu](docs/components/navigation-menu.md): Horizontal top-level nav with dropdown sub-menus.
-- [NotificationBadge](docs/components/notification-badge.md): Dot or count overlay on icon buttons.
-- [PageHeader](docs/components/page-header.md): Mandatory page title component. Every page must use it.
-- [Pagination](docs/components/pagination.md): Page navigation controls for data tables.
-- [Popover](docs/components/popover.md): Interactive floating panel anchored to a trigger.
-- [Progress](docs/components/progress.md): Read-only completion bar. 5 semantic variants.
-- [RadioGroup](docs/components/radio-group.md): Mutually exclusive options.
-- [Rating](docs/components/rating.md): Star-based rating input or display.
-- [Resizable](docs/components/resizable.md): Draggable panel splitter.
-- [RichTextEditor](docs/components/rich-text-editor.md): Native WYSIWYG text editor.
-- [ScrollArea](docs/components/scroll-area.md): Custom-styled scrollable container.
-- [Search](docs/components/search.md): Search input with icon and clear button.
-- [Select](docs/components/select.md): Accessible dropdown for single option selection. Never use native `<select>`.
-- [Separator](docs/components/separator.md): Visual divider between sections.
-- [Sheet](docs/components/sheet.md): Edge-anchored slide-in panel (top/right/bottom/left).
-- [Skeleton](docs/components/skeleton.md): Loading placeholder. Use instead of blank space.
-- [Slider](docs/components/slider.md): Range value picker by dragging a thumb.
-- [Sonner](docs/components/sonner.md): Toast notification system. Use `toast()` from `sonner`. Auto-injected by `XerticaProvider`.
-- [StatsCard](docs/components/stats-card.md): KPI metric card with trend indicator.
-- [Stepper](docs/components/stepper.md): Multi-step process indicator / wizard.
-- [Switch](docs/components/switch.md): Prominent on/off toggle. Use for feature flags and settings.
-- [Table](docs/components/table.md): Structured tabular data display.
-- [Tabs](docs/components/tabs.md): Content switcher with tab triggers.
-- [Textarea](docs/components/textarea.md): Multi-line text field.
-- [Timeline](docs/components/timeline.md): Vertical chronological event sequence.
-- [Toggle](docs/components/toggle.md): Pressable on/off button for toolbars.
-- [ToggleGroup](docs/components/toggle-group.md): Set of related toggles — single or multiple selection.
-- [Tooltip](docs/components/tooltip.md): Short hover hint for icon-only buttons and abbreviated text.
-- [TreeView](docs/components/tree-view.md): Hierarchical nested data tree.
-
-## Component Reference — Layout (`xertica-ui/layout`)
-
-- [Header](docs/components/header.md): Global top bar (64px). Breadcrumbs, language, theme, user profile.
-- [Sidebar](docs/components/sidebar.md): Primary vertical navigation. Default and Assistant variants.
-
-## Component Reference — Brand (`xertica-ui/brand`)
-
-- [XerticaProvider](docs/components/xertica-provider.md): Recommended root wrapper. Initializes shared contexts and services.
-- [ThemeToggle](docs/components/theme-toggle.md): Self-contained dark/light mode button. No provider needed.
-- [LanguageSelector](docs/components/language-selector.md): Language dropdown (pt/en/es).
-- [XerticaLogo](docs/components/xertica-logo.md): Full horizontal logotype SVG.
-- [XerticaXLogo](docs/components/xertica-xlogo.md): Compact X-mark logo. Use in collapsed sidebar.
-- [XerticaOrbe](docs/components/xertica-orbe.md): Animated decorative brand orb. For splash screens only.
-
-## Component Reference — AI Assistant (`xertica-ui/assistant`)
-
-- [XerticaAssistant](docs/components/assistant.md): Full AI chat panel with history, favorites, document workspace.
-- [MarkdownMessage](docs/components/markdown-message.md): Markdown renderer for AI responses.
-- [CodeBlock](docs/components/assistant.md): Syntax-highlighted code display with copy button.
-- [ModernChatInput](docs/components/assistant.md): Enhanced AI chat input with drag-and-drop.
-- [FormattedDocument](docs/components/assistant.md): Structured AI-generated document renderer.
-
-## Component Reference — Media (`xertica-ui/media`)
-
-- [VideoPlayer](docs/components/video-player.md): Custom video controls with floating mode.
-- [AudioPlayer](docs/components/audio-player.md): Podcast/audio player — card or global bar variant.
-- [FloatingMediaWrapper](docs/components/floating-media-wrapper.md): Draggable portal wrapper for media players.
-
-## Component Reference — Maps (`xertica-ui`)
-
-- [Map](docs/components/map.md): Google Maps integration with markers, polygons, controls.
-- [RouteMap](docs/components/route-map.md): Route + directions between origin and destination.
-- [SimpleMap](docs/components/simple-map.md): Simplified map for a single marker.
-- [GoogleMapsLoader](docs/components/google-maps-loader.md): Lazy-loads Maps API. Auto-managed by XerticaProvider.
-
-## Design Token Reference
-
-```
-bg-background / text-foreground       page background and body text
-bg-card / text-card-foreground        card surfaces
-bg-muted / text-muted-foreground      subdued areas, secondary text, placeholders
-bg-primary / text-primary-foreground  primary actions, active states
-bg-secondary / text-secondary-fg      secondary actions
-bg-destructive                        danger, delete, error
-bg-accent / text-accent-foreground    hover states
-bg-success / bg-info / bg-warning     semantic state colors
-border-border                         standard borders
-border-input                          form field borders
-ring-ring                             focus rings
---mobile-content-padding              horizontal padding for content on mobile (< 768px), default 1.25rem
-```
-
-## Composition Patterns
-
-- [Form pattern](docs/patterns/form.md): Validated forms with react-hook-form.
-- [CRUD pattern](docs/patterns/crud.md): Table + search + row actions.
-- [Dashboard pattern](docs/patterns/dashboard.md): StatsCard grid + Charts.
-- [Analytics pattern](docs/patterns/analytics.md): Filters + date range + charts.
-
-## Machine-Readable Registry
-
-- [components.json](components.json): All 97 components with name, category, import path, keywords, related components, source path, and doc path.
+# Xertica UI
+
+> Enterprise-grade React design system — 97 components built on Tailwind CSS v4, Radix UI, and Lucide Icons. Designed to be consumed directly by AI coding agents (LLMs, Cursor, Claude Code, Copilot). v2.5.3
+
+Xertica UI ships with full source, typed declarations, Storybook stories, and structured documentation inside `node_modules/xertica-ui/`. AI agents should read this file first, then follow links for component-specific detail.
+
+## Quick Start
+
+- [Getting Started](docs/getting-started.md): Provider setup, theming, routing integration, and subpath import patterns.
+- [Installation](docs/installation.md): Peer dependencies, CSS import, and provider setup steps.
+- [AI Usage Rules](docs/ai-usage.md): Mandatory rules for AI agents — what is permitted, what is forbidden.
+- [Compact Reference](llms-full.txt): Complete documentation of all 97 components in a single file (large context LLMs).
+- [Compact Quick-Reference](llms-compact.txt): ~4K token summary — import patterns, critical rules, most-used components.
+- [Component Selection Guide](docs/decision-tree.md): Decision trees for Dialog vs Sheet, Tooltip vs HoverCard, etc.
+
+## Critical Rules (read before generating any code)
+
+1. **Never use raw HTML elements** — `<button>`, `<input>`, `<select>` → always use library components.
+2. **Never use raw colors** — `bg-blue-500`, `#3b82f6` → always use semantic tokens (`bg-primary`, `bg-muted`).
+3. **Never use hardcoded radii** — `rounded-lg` → always `rounded-[var(--radius)]`.
+4. **Every page requires `<PageHeader>`** — never use `<h1>` or `<h2>` for page titles.
+5. **Wrap apps in `<XerticaProvider>`** — recommended for synchronized theme, toasts, tooltips, layout, assistant state, maps, and API keys.
+6. **Import `xertica-ui/style.css` once** at the root entry file.
+7. **Icons come from `lucide-react`** — never from `xertica-ui`.
+8. **Layout state from `useLayout()`** — never hardcode sidebar widths.
+9. **Destructive actions require `<AlertDialog>`** — never execute directly on click.
+10. **`<Toaster>` is auto-injected** by `<XerticaProvider>` — never render it manually.
+11. **Wrap `<Routes>` in `<PageErrorBoundary>`** — prevents lazy-chunk failures from showing a blank screen.
+12. **Wrap data sections in `<SectionErrorBoundary>`** — tables, charts, and the assistant must not crash the page.
+13. **Auth state from `useAuth()`** — never pass `user` or `onLogout` as props to page components; consume from `AuthContext`.
+14. **Server data from `useQuery` (React Query)** — never `useState + useEffect + fetch` for API data.
+15. **UI strings from `useTranslation()`** — never hardcode text in JSX; add keys to the appropriate file under `locales/<lang>/` (e.g., `locales/pt-BR/common.json` for shared labels, `locales/pt-BR/pages/home.json` for page strings).
+
+## State Management & Auth
+
+- [State Management Guide](docs/state-management.md): React Query, Zustand, AuthContext, `features/` slice pattern, decision tree.
+- [i18n Guide](docs/i18n.md): i18next setup, `useTranslation`, locale files, language switching.
+- **`useAuth()`** — `{ user, isLoading, login, logout }` from `AuthContext`. Must be inside `<AuthProvider>` (inside `<Router>`).
+- **`useQuery`** — server state. Use hooks in `features/*/hooks/`. Swap `fetch*` in `features/*/data/mock.ts` for real API.
+- **Zustand** — client UI state. Use stores in `features/*/store/`.
+- **Provider stack**: `AppErrorBoundary > QueryClientProvider > XerticaProvider > Router > AuthProvider > PageErrorBoundary > Routes`.
+
+## Error Boundaries
+
+- [ErrorBoundary docs](docs/components/error-boundary.md): Full API, placement guide, AI rules.
+- **`AppErrorBoundary`** — outermost; full-screen inline-styled fallback; catches provider crashes.
+- **`PageErrorBoundary`** — wraps `<Routes>`; catches lazy-chunk failures and page render errors.
+- **`SectionErrorBoundary`** — wraps data sections (table, chart, assistant); compact inline fallback.
+- Import: `import { AppErrorBoundary, PageErrorBoundary, SectionErrorBoundary } from '@/shared/error-boundary';`
+
+## Component Reference — Shared Utilities
+
+- [ErrorBoundary](docs/components/error-boundary.md): `AppErrorBoundary`, `PageErrorBoundary`, `SectionErrorBoundary`, `ErrorBoundary` (base class). Props: `onError`, `resetKeys`.
+
+## Import Patterns
+
+```tsx
+import { Button, Card, Input, Badge, Table, Dialog } from 'xertica-ui/ui';
+import { Sidebar, Header }                           from 'xertica-ui/layout';
+import { XerticaProvider, XerticaLogo, ThemeToggle } 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';
+```
+
+## Component Reference — UI Primitives (`xertica-ui/ui`)
+
+- [Accordion](docs/components/accordion.md): Vertically stacked collapsible sections. Use for FAQs, settings panels, dense trees.
+- [Alert](docs/components/alert.md): Inline persistent status banner. Use when the message must stay visible.
+- [AlertDialog](docs/components/alert-dialog.md): Blocking confirmation modal. Required before any destructive action.
+- [AspectRatio](docs/components/aspect-ratio.md): Fixed-ratio media container. Prevents layout shifts.
+- [Avatar](docs/components/avatar.md): User identity — photo or initials fallback.
+- [Badge](docs/components/badge.md): Compact non-interactive status label or count chip.
+- [Breadcrumb](docs/components/breadcrumb.md): Hierarchical navigation trail. Rendered inside `Header`.
+- [Button](docs/components/button.md): Primary interaction trigger. 9 variants: default, secondary, outline, ghost, destructive, link, success, info, warning.
+- [Calendar](docs/components/calendar.md): Date picker. Almost always wrapped in `Popover`.
+- [Card](docs/components/card.md): Primary content container. Never recreate with raw `<div>`.
+- [Carousel](docs/components/carousel.md): Horizontal content slider. Built on embla-carousel.
+- [Chart](docs/components/chart.md): Token-aware charts built on Recharts. Use `ChartContainer`; 11 dashboard-ready wrappers: `ChartCard`, `DashboardBarChart`, `DashboardLineChart`, `HorizontalBarChart`, `InteractiveTimeSeriesChart`, `ComboMetricChart`, `DonutBreakdownChart`, `SparklineChart`, `RadarMetricChart`, `PieMetricChart`, `RadialBarMetricChart`, and `GaugeChart` (pure SVG semicircle gauge with thresholds).
+- [Checkbox](docs/components/checkbox.md): Boolean toggle or multi-select option.
+- [Collapsible](docs/components/collapsible.md): Single expandable section — no sibling management.
+- [Command](docs/components/command.md): Command palette (⌘K). Searchable action list.
+- [ContextMenu](docs/components/context-menu.md): Right-click menu.
+- [Dialog](docs/components/dialog.md): Modal overlay. Dismissible. Use for forms and detail views.
+- [Drawer](docs/components/drawer.md): Bottom-sliding panel. Mobile-optimized equivalent of Sheet.
+- [DropdownMenu](docs/components/dropdown-menu.md): Triggered contextual action menu.
+- [Empty](docs/components/empty.md): Zero-state container for lists and search results.
+- [FileUpload](docs/components/file-upload.md): Drag-and-drop file input.
+- [Form](docs/components/form.md): react-hook-form integration layer.
+- [HoverCard](docs/components/hover-card.md): Rich floating preview on hover. Use for user profiles, link previews.
+- [Input](docs/components/input.md): Single-line text field.
+- [InputOTP](docs/components/input-otp.md): OTP / PIN code segmented input.
+- [Label](docs/components/label.md): Accessible form field label. Always paired with Input via `htmlFor`.
+- [Menubar](docs/components/menubar.md): Application-style horizontal menu bar.
+- [NavigationMenu](docs/components/navigation-menu.md): Horizontal top-level nav with dropdown sub-menus.
+- [NotificationBadge](docs/components/notification-badge.md): Dot or count overlay on icon buttons.
+- [PageHeader](docs/components/page-header.md): Mandatory page title component. Every page must use it.
+- [Pagination](docs/components/pagination.md): Page navigation controls for data tables.
+- [Popover](docs/components/popover.md): Interactive floating panel anchored to a trigger.
+- [Progress](docs/components/progress.md): Read-only completion bar. 5 semantic variants.
+- [RadioGroup](docs/components/radio-group.md): Mutually exclusive options.
+- [Rating](docs/components/rating.md): Star-based rating input or display.
+- [Resizable](docs/components/resizable.md): Draggable panel splitter.
+- [RichTextEditor](docs/components/rich-text-editor.md): Native WYSIWYG text editor.
+- [ScrollArea](docs/components/scroll-area.md): Custom-styled scrollable container.
+- [Search](docs/components/search.md): Search input with icon and clear button.
+- [Select](docs/components/select.md): Accessible dropdown for single option selection. Never use native `<select>`.
+- [Separator](docs/components/separator.md): Visual divider between sections.
+- [Sheet](docs/components/sheet.md): Edge-anchored slide-in panel (top/right/bottom/left).
+- [Skeleton](docs/components/skeleton.md): Loading placeholder. Use instead of blank space.
+- [Slider](docs/components/slider.md): Range value picker by dragging a thumb.
+- [Sonner](docs/components/sonner.md): Toast notification system. Use `toast()` from `sonner`. Auto-injected by `XerticaProvider`.
+- [StatsCard](docs/components/stats-card.md): KPI metric card with trend indicator.
+- [Stepper](docs/components/stepper.md): Multi-step process indicator / wizard.
+- [Switch](docs/components/switch.md): Prominent on/off toggle. Use for feature flags and settings.
+- [Table](docs/components/table.md): Structured tabular data display.
+- [Tabs](docs/components/tabs.md): Content switcher with tab triggers.
+- [Textarea](docs/components/textarea.md): Multi-line text field.
+- [Timeline](docs/components/timeline.md): Vertical chronological event sequence.
+- [Toggle](docs/components/toggle.md): Pressable on/off button for toolbars.
+- [ToggleGroup](docs/components/toggle-group.md): Set of related toggles — single or multiple selection.
+- [Tooltip](docs/components/tooltip.md): Short hover hint for icon-only buttons and abbreviated text.
+- [TreeView](docs/components/tree-view.md): Hierarchical nested data tree.
+
+## Component Reference — Layout (`xertica-ui/layout`)
+
+- [Header](docs/components/header.md): Global top bar (64px). Breadcrumbs, language, theme, user profile.
+- [Sidebar](docs/components/sidebar.md): Primary vertical navigation. Default and Assistant variants.
+
+## Component Reference — Brand (`xertica-ui/brand`)
+
+- [XerticaProvider](docs/components/xertica-provider.md): Recommended root wrapper. Initializes shared contexts and services.
+- [ThemeToggle](docs/components/theme-toggle.md): Self-contained dark/light mode button. No provider needed.
+- [LanguageSelector](docs/components/language-selector.md): Language dropdown (pt/en/es).
+- [XerticaLogo](docs/components/xertica-logo.md): Full horizontal logotype SVG.
+- [XerticaXLogo](docs/components/xertica-xlogo.md): Compact X-mark logo. Use in collapsed sidebar.
+- [XerticaOrbe](docs/components/xertica-orbe.md): Animated decorative brand orb. For splash screens only.
+
+## Component Reference — AI Assistant (`xertica-ui/assistant`)
+
+- [XerticaAssistant](docs/components/assistant.md): Full AI chat panel with history, favorites, document workspace.
+- [MarkdownMessage](docs/components/markdown-message.md): Markdown renderer for AI responses.
+- [CodeBlock](docs/components/assistant.md): Syntax-highlighted code display with copy button.
+- [ModernChatInput](docs/components/assistant.md): Enhanced AI chat input with drag-and-drop.
+- [FormattedDocument](docs/components/assistant.md): Structured AI-generated document renderer.
+
+## Component Reference — Media (`xertica-ui/media`)
+
+- [VideoPlayer](docs/components/video-player.md): Custom video controls with floating mode.
+- [AudioPlayer](docs/components/audio-player.md): Podcast/audio player — card or global bar variant.
+- [FloatingMediaWrapper](docs/components/floating-media-wrapper.md): Draggable portal wrapper for media players.
+
+## Component Reference — Maps (`xertica-ui`)
+
+- [Map](docs/components/map.md): Google Maps integration with markers, polygons, controls.
+- [RouteMap](docs/components/route-map.md): Route + directions between origin and destination.
+- [SimpleMap](docs/components/simple-map.md): Simplified map for a single marker.
+- [GoogleMapsLoader](docs/components/google-maps-loader.md): Lazy-loads Maps API. Auto-managed by XerticaProvider.
+
+## Design Token Reference
+
+```
+bg-background / text-foreground       page background and body text
+bg-card / text-card-foreground        card surfaces
+bg-muted / text-muted-foreground      subdued areas, secondary text, placeholders
+bg-primary / text-primary-foreground  primary actions, active states
+bg-secondary / text-secondary-fg      secondary actions
+bg-destructive                        danger, delete, error
+bg-accent / text-accent-foreground    hover states
+bg-success / bg-info / bg-warning     semantic state colors
+border-border                         standard borders
+border-input                          form field borders
+ring-ring                             focus rings
+--mobile-content-padding              horizontal padding for content on mobile (< 768px), default 1.25rem
+```
+
+## Composition Patterns
+
+- [Form pattern](docs/patterns/form.md): Validated forms with react-hook-form.
+- [CRUD pattern](docs/patterns/crud.md): Table + search + row actions.
+- [Dashboard pattern](docs/patterns/dashboard.md): StatsCard grid + Charts.
+- [Analytics pattern](docs/patterns/analytics.md): Filters + date range + charts.
+
+## Machine-Readable Registry
+
+- [components.json](components.json): All 97 components with name, category, import path, keywords, related components, source path, and doc path.