xertica-ui 2.4.0 → 2.5.0

package/components.json

@@ -3,890 +3,510 @@
     "name": "accordion",
     "docPath": "docs/components/accordion.md",
     "sourcePath": "components/ui/accordion/index.ts",
-    "description": "A vertically stacked set of collapsible sections. Each section has a clickable trigger header that reveals or hides its content. Ideal for FAQs, configuration settings, and dense navigation trees where only one (or a few) section needs to be visible at a time.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["collapse", "expand", "faq", "collapsible-list"],
-    "relatedComponents": ["collapsible", "tabs"]
+    "description": "A vertically stacked set of collapsible sections. Each section has a clickable trigger header that reveals or hides its content. Ideal for FAQs, configuration settings, and dense navigation trees where only one (or a few) section needs to be visible at a time."
   },
   {
     "name": "alert-dialog",
     "docPath": "docs/components/alert-dialog.md",
     "sourcePath": "components/ui/alert-dialog/index.ts",
-    "description": "A specialized modal for **irreversible destructive actions** — delete, revoke, reset, permanently disable. Unlike `Dialog`, `AlertDialog` enforces that the user must explicitly confirm or cancel; clicking outside does not dismiss it.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["confirm", "confirmation", "destructive", "delete-confirm"],
-    "relatedComponents": ["dialog", "button"]
+    "description": "A specialized modal for **irreversible destructive actions** — delete, revoke, reset, permanently disable. Unlike `Dialog`, `AlertDialog` enforces that the user must explicitly confirm or cancel; clicking outside does not dismiss it."
   },
   {
     "name": "alert",
     "docPath": "docs/components/alert.md",
     "sourcePath": "components/ui/alert/index.ts",
-    "description": "An inline message banner used to communicate status, feedback, or important contextual information directly within the page content — without interrupting the user flow. Unlike `Sonner` (toast notifications), alerts are persistent and visible at all times.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["banner", "info-banner", "warning-banner", "inline-message"],
-    "relatedComponents": ["sonner", "alert-dialog"]
+    "description": "An inline message banner used to communicate status, feedback, or important contextual information directly within the page content — without interrupting the user flow. Unlike `Sonner` (toast notifications), alerts are persistent and visible at all times."
   },
   {
     "name": "aspect-ratio",
     "docPath": "docs/components/aspect-ratio.md",
     "sourcePath": "components/ui/aspect-ratio/index.ts",
-    "description": "A container that maintains a fixed width-to-height ratio regardless of the available space. Prevents layout shifts when loading images, videos, or charts. Use when content must always fill a specific shape.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["ratio", "media-ratio", "image-container", "16-9"],
-    "relatedComponents": ["video-player", "card"]
+    "description": "A container that maintains a fixed width-to-height ratio regardless of the available space. Prevents layout shifts when loading images, videos, or charts. Use when content must always fill a specific shape."
   },
   {
     "name": "assistant-chart",
     "docPath": "docs/components/assistant-chart.md",
     "sourcePath": "components/ui/assistant-chart/index.ts",
-    "description": "A specialized data visualization component optimized for display within the AI Assistant panel. It provides a pre-configured responsive BarChart using the library's design system tokens.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["ai-chart", "assistant-visualization", "chat-chart"],
-    "relatedComponents": ["chart", "xertica-assistant"]
+    "description": "A specialized data visualization component optimized for display within the AI Assistant panel. It provides a pre-configured responsive BarChart using the library's design system tokens."
+  },
+  {
+    "name": "assistant",
+    "docPath": "docs/components/assistant.md",
+    "sourcePath": "components/ui/assistant.tsx",
+    "description": "Full-featured AI chat assistant with support for:"
   },
   {
     "name": "audio-player",
     "docPath": "docs/components/audio-player.md",
-    "sourcePath": "components/media/audio-player/index.ts",
-    "description": "A global, floating audio playback bar designed for process tracking and podcast consumption. It features a responsive layout that automatically adjusts to the state of the sidebar and AI assistant.",
-    "category": "media",
-    "import": "xertica-ui/media",
-    "keywords": ["audio", "podcast", "music", "sound", "playback"],
-    "relatedComponents": ["video-player", "floating-media-wrapper"]
+    "sourcePath": "components/ui/audio-player.tsx",
+    "description": "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."
   },
   {
     "name": "avatar",
     "docPath": "docs/components/avatar.md",
     "sourcePath": "components/ui/avatar/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["profile-picture", "user-image", "initials"],
-    "relatedComponents": ["header", "table"]
+    "description": "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."
   },
   {
     "name": "badge",
     "docPath": "docs/components/badge.md",
     "sourcePath": "components/ui/badge/index.ts",
-    "description": "A compact, inline label used to communicate status, category, or count. Badges are always non-interactive by default — they display information, not trigger actions.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["tag", "label", "status", "chip", "pill"],
-    "relatedComponents": ["notification-badge", "table", "card"]
+    "description": "A compact, inline label used to communicate status, category, or count. Badges are always non-interactive by default — they display information, not trigger actions."
+  },
+  {
+    "name": "branding",
+    "docPath": "docs/components/branding.md",
+    "sourcePath": "components/ui/branding.tsx",
+    "description": "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."
   },
   {
     "name": "breadcrumb",
     "docPath": "docs/components/breadcrumb.md",
     "sourcePath": "components/ui/breadcrumb/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["breadcrumbs", "navigation-path", "location-trail"],
-    "relatedComponents": ["header", "page-header"]
+    "description": "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."
   },
   {
     "name": "button",
     "docPath": "docs/components/button.md",
     "sourcePath": "components/ui/button/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["btn", "action", "click", "submit", "trigger", "cta"],
-    "relatedComponents": ["alert-dialog", "dialog", "form", "dropdown-menu"]
+    "description": "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."
   },
   {
     "name": "calendar",
     "docPath": "docs/components/calendar.md",
     "sourcePath": "components/ui/calendar/index.ts",
-    "description": "A date picker calendar that renders a monthly grid of selectable days. Built on `react-day-picker`. Almost always used inside a `<Popover>` to provide an accessible, accessible date input. Supports single date selection, multiple dates, and date ranges.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["date-picker", "datepicker", "date-input"],
-    "relatedComponents": ["popover", "input"]
+    "description": "A date picker calendar that renders a monthly grid of selectable days. Built on `react-day-picker`. Almost always used inside a `<Popover>` to provide an accessible date input. Supports single date selection, multiple dates, and date ranges. When `captionLayout=\"dropdown\"` is used, the month/year header renders as interactive selectors with input-styled visuals."
+  },
+  {
+    "name": "card-patterns",
+    "docPath": "docs/components/card-patterns.md",
+    "sourcePath": "components/blocks/card-patterns/index.ts",
+    "description": "Pre-composed card blocks for dashboards, project management, and feature pages. Each component is built exclusively from `ui/` primitives — no external dependencies. They live in `components/blocks/card-patterns/` and are available from the root `xertica-ui` import."
   },
   {
     "name": "card",
     "docPath": "docs/components/card.md",
     "sourcePath": "components/ui/card/index.ts",
-    "description": "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 `<div>` utility classes.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["container", "panel", "surface", "box"],
-    "relatedComponents": ["stats-card", "scroll-area", "separator"]
+    "description": "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 `<div>` utility classes."
   },
   {
     "name": "carousel",
     "docPath": "docs/components/carousel.md",
     "sourcePath": "components/ui/carousel/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["slider", "slides", "horizontal-scroll", "embla"],
-    "relatedComponents": ["card"]
+    "description": "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."
   },
   {
     "name": "chart",
     "docPath": "docs/components/chart.md",
     "sourcePath": "components/ui/chart/index.ts",
-    "description": "Xertica UI provides a `ChartContainer` wrapper and dashboard-ready chart components built on top of **Recharts** for theme-aware, token-driven 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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": [
-      "graph",
-      "visualization",
-      "recharts",
-      "bar-chart",
-      "line-chart",
-      "horizontal-bar-chart",
-      "dashboard-chart",
-      "donut-chart",
-      "combo-chart"
-    ],
-    "relatedComponents": ["card", "stats-card"]
+    "description": "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."
   },
   {
     "name": "checkbox",
     "docPath": "docs/components/checkbox.md",
     "sourcePath": "components/ui/checkbox/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["check", "boolean", "tick", "multi-select"],
-    "relatedComponents": ["switch", "radio-group", "toggle"]
+    "description": "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."
+  },
+  {
+    "name": "code-block",
+    "docPath": "docs/components/code-block.md",
+    "sourcePath": "components/assistant/code-block/index.ts",
+    "description": "A syntax-highlighted code display component with a one-click copy button. Designed for use inside AI chat messages and documentation panels."
   },
   {
     "name": "collapsible",
     "docPath": "docs/components/collapsible.md",
     "sourcePath": "components/ui/collapsible/index.ts",
-    "description": "A single expandable/collapsible content section with a trigger header. Unlike `<Accordion>`, `Collapsible` is a standalone element — it has no sibling items and no managed \"only one open\" behavior.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["expand", "collapse", "toggle-section"],
-    "relatedComponents": ["accordion"]
+    "description": "A single expandable/collapsible content section with a trigger header. Unlike `<Accordion>`, `Collapsible` is a standalone element — it has no sibling items and no managed \"only one open\" behavior."
   },
   {
     "name": "command",
     "docPath": "docs/components/command.md",
     "sourcePath": "components/ui/command/index.ts",
-    "description": "A command palette for searching and executing actions via keyboard — triggered by `⌘K` / `Ctrl+K`. Provides a searchable, filterable list of commands, navigation items, and quick actions. Built on `cmdk`.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["command-palette", "cmd-k", "spotlight", "keyboard-shortcut"],
-    "relatedComponents": ["search", "dialog"]
+    "description": "A command palette for searching and executing actions via keyboard — triggered by `⌘K` / `Ctrl+K`. Provides a searchable, filterable list of commands, navigation items, and quick actions. Built on `cmdk`."
   },
   {
     "name": "context-menu",
     "docPath": "docs/components/context-menu.md",
     "sourcePath": "components/ui/context-menu/index.ts",
-    "description": "A menu that appears when the user right-clicks (or long-presses on mobile) a trigger area. Provides a familiar OS-native contextual menu pattern for power-user interactions. Built on Radix UI.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["right-click", "contextmenu", "right-click-menu"],
-    "relatedComponents": ["dropdown-menu", "menubar"]
+    "description": "A menu that appears when the user right-clicks (or long-presses on mobile) a trigger area. Provides a familiar OS-native contextual menu pattern for power-user interactions. Built on Radix UI."
   },
   {
     "name": "dialog",
     "docPath": "docs/components/dialog.md",
     "sourcePath": "components/ui/dialog/index.ts",
-    "description": "A modal overlay that interrupts the page flow to capture user attention for critical confirmations, data entry, or detailed views. Built on Radix UI Dialog with managed focus trapping, keyboard escape, and backdrop click-to-dismiss.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["modal", "popup", "overlay", "lightbox"],
-    "relatedComponents": ["alert-dialog", "sheet", "drawer", "popover"]
+    "description": "A modal overlay that interrupts the page flow to capture user attention for critical confirmations, data entry, or detailed views. Built on Radix UI Dialog with managed focus trapping, keyboard escape, and backdrop click-to-dismiss."
   },
   {
     "name": "drawer",
     "docPath": "docs/components/drawer.md",
     "sourcePath": "components/ui/drawer/index.ts",
-    "description": "A panel that slides in from the bottom edge of the screen — the mobile-optimized equivalent of `<Sheet>`. Drawers are the standard interaction pattern for panels on mobile, providing a more natural bottom-to-top gesture feel.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["bottom-sheet", "mobile-panel", "slide-up"],
-    "relatedComponents": ["sheet", "dialog"]
+    "description": "A panel that slides in from the bottom edge of the screen — the mobile-optimized equivalent of `<Sheet>`. Drawers are the standard interaction pattern for panels on mobile, providing a more natural bottom-to-top gesture feel."
   },
   {
     "name": "dropdown-menu",
     "docPath": "docs/components/dropdown-menu.md",
     "sourcePath": "components/ui/dropdown-menu/index.ts",
-    "description": "A triggered contextual menu that appears anchored below (or beside) a trigger element. Used for row actions in tables, secondary navigation options, and grouped control menus. Built on Radix UI with full keyboard navigation.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["action-menu", "options-menu", "kebab-menu"],
-    "relatedComponents": ["context-menu", "button", "table"]
+    "description": "A triggered contextual menu that appears anchored below (or beside) a trigger element. Used for row actions in tables, secondary navigation options, and grouped control menus. Built on Radix UI with full keyboard navigation."
   },
   {
     "name": "empty",
     "docPath": "docs/components/empty.md",
     "sourcePath": "components/ui/empty/index.ts",
-    "description": "A structured zero-state container rendered when a list, table, or search returns no results. Uses a composable primitive pattern (`Empty + EmptyIcon + EmptyTitle + EmptyDescription + EmptyAction`) to provide a flexible, consistent empty-state experience.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["empty-state", "zero-state", "no-results", "no-data"],
-    "relatedComponents": ["skeleton", "table"]
+    "description": "A structured zero-state container rendered when a list, table, or search returns no results. Uses a composable primitive pattern (`Empty + EmptyIcon + EmptyTitle + EmptyDescription + EmptyAction`) to provide a flexible, consistent empty-state experience."
+  },
+  {
+    "name": "error-boundary",
+    "docPath": "docs/components/error-boundary.md",
+    "sourcePath": "components/ui/error-boundary.tsx",
+    "description": "React Error Boundaries catch JavaScript errors in the component tree, log them, and render a fallback UI instead of crashing the application. Xertica UI ships a single reusable `ErrorBoundary` class with **three pre-configured wrapper variants** covering every granularity of protection."
   },
   {
     "name": "file-upload",
     "docPath": "docs/components/file-upload.md",
     "sourcePath": "components/ui/file-upload/index.ts",
-    "description": "A drag-and-drop file input component that accepts one or multiple files. Renders a dropzone area with visual feedback on drag, displays selected file names, and validates against allowed MIME types and file size limits.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["drop-zone", "file-input", "drag-drop", "upload"],
-    "relatedComponents": ["input", "form", "button"]
+    "description": "A drag-and-drop file input component that accepts one or multiple files. Renders a dropzone area with visual feedback on drag, displays selected file names, and validates against allowed MIME types and file size limits."
+  },
+  {
+    "name": "floating-media-wrapper",
+    "docPath": "docs/components/floating-media-wrapper.md",
+    "sourcePath": "components/ui/floating-media-wrapper.tsx",
+    "description": "A higher-level wrapper for media players (audio/video) that manages floating state, positioning, and transitions."
   },
   {
     "name": "form",
     "docPath": "docs/components/form.md",
     "sourcePath": "components/ui/form/index.ts",
-    "description": "`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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["react-hook-form", "form-validation", "zod", "form-fields"],
-    "relatedComponents": ["input", "select", "checkbox", "button", "label"]
+    "description": "`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."
+  },
+  {
+    "name": "formatted-document",
+    "docPath": "docs/components/formatted-document.md",
+    "sourcePath": "components/assistant/formatted-document/index.ts",
+    "description": "A lightweight Markdown-to-HTML renderer with a collapsible preview. Designed for displaying AI-generated documents, reports, and structured text inside the assistant panel."
   },
   {
     "name": "google-maps-loader",
     "docPath": "docs/components/google-maps-loader.md",
     "sourcePath": "components/ui/google-maps-loader/index.ts",
-    "description": "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`.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["maps-api", "google-maps-api", "maps-provider"],
-    "relatedComponents": ["map", "xertica-provider"]
+    "description": "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`."
   },
   {
     "name": "header",
     "docPath": "docs/components/header.md",
     "sourcePath": "components/layout/header/index.ts",
-    "description": "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.",
-    "category": "layout",
-    "import": "xertica-ui/layout",
-    "keywords": ["top-bar", "app-bar", "navbar", "topnav"],
-    "relatedComponents": ["sidebar", "breadcrumb", "page-header"]
+    "description": "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."
+  },
+  {
+    "name": "hooks",
+    "docPath": "docs/components/hooks.md",
+    "sourcePath": "components/ui/hooks.tsx",
+    "description": "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)."
   },
   {
     "name": "hover-card",
     "docPath": "docs/components/hover-card.md",
     "sourcePath": "components/ui/hover-card/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["preview-card", "rich-hover", "link-preview"],
-    "relatedComponents": ["tooltip", "popover"]
+    "description": "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."
+  },
+  {
+    "name": "image-with-fallback",
+    "docPath": "docs/components/image-with-fallback.md",
+    "sourcePath": "components/ui/image-with-fallback.tsx",
+    "description": "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."
   },
   {
     "name": "input-otp",
     "docPath": "docs/components/input-otp.md",
     "sourcePath": "components/ui/input-otp/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["otp", "pin", "mfa", "verification-code"],
-    "relatedComponents": ["input", "form"]
+    "description": "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."
   },
   {
     "name": "input",
     "docPath": "docs/components/input.md",
     "sourcePath": "components/ui/input/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["text-field", "form-field", "text-input"],
-    "relatedComponents": ["label", "form", "search", "textarea"]
+    "description": "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."
   },
   {
     "name": "label",
     "docPath": "docs/components/label.md",
     "sourcePath": "components/ui/label/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["form-label", "field-label", "input-label"],
-    "relatedComponents": ["input", "form", "checkbox"]
+    "description": "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."
   },
   {
     "name": "language-selector",
     "docPath": "docs/components/language-selector.md",
     "sourcePath": "components/brand/language-selector/index.ts",
-    "description": "A self-contained dropdown for switching the interface language. Wired to `LanguageContext` and `i18next`: changing the selection persists to localStorage, calls `i18n.changeLanguage`, and invalidates the React Query cache. Auto-hides when only one language is configured. The list of languages is runtime-configurable via the `availableLanguages` prop on `<XerticaProvider>`.",
-    "category": "brand",
-    "import": "xertica-ui/brand",
-    "keywords": ["i18n", "locale", "language", "internationalization"],
-    "relatedComponents": ["header", "theme-toggle"]
+    "description": "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."
+  },
+  {
+    "name": "map-layers",
+    "docPath": "docs/components/map-layers.md",
+    "sourcePath": "components/ui/map-layers/index.ts",
+    "description": "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."
   },
   {
     "name": "map",
     "docPath": "docs/components/map.md",
     "sourcePath": "components/ui/map/index.ts",
-    "description": "A Google Maps integration component that renders an interactive map with markers, polygons, and custom controls. Powered by the Google Maps JavaScript API via `@vis.gl/react-google-maps`.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["google-maps", "map-view", "geolocation", "markers"],
-    "relatedComponents": ["route-map", "simple-map"]
+    "description": "`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."
   },
   {
     "name": "markdown-message",
     "docPath": "docs/components/markdown-message.md",
     "sourcePath": "components/assistant/markdown-message/index.ts",
-    "description": "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.",
-    "category": "assistant",
-    "import": "xertica-ui/assistant",
-    "keywords": ["markdown", "md-renderer", "ai-message", "chat-message"],
-    "relatedComponents": ["xertica-assistant", "code-block"]
+    "description": "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."
   },
   {
     "name": "menubar",
     "docPath": "docs/components/menubar.md",
     "sourcePath": "components/ui/menubar/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["application-menu", "horizontal-menu", "file-edit-view"],
-    "relatedComponents": ["navigation-menu", "dropdown-menu"]
+    "description": "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."
+  },
+  {
+    "name": "modern-chat-input",
+    "docPath": "docs/components/modern-chat-input.md",
+    "sourcePath": "components/assistant/modern-chat-input/index.ts",
+    "description": "An advanced floating chat input with rich action chips, voice recording simulation, and file attachment support. Used as the primary input interface inside `XerticaAssistant`."
   },
   {
     "name": "navigation-menu",
     "docPath": "docs/components/navigation-menu.md",
     "sourcePath": "components/ui/navigation-menu/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["top-nav", "horizontal-nav", "mega-menu"],
-    "relatedComponents": ["sidebar", "tabs", "breadcrumb"]
+    "description": "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."
   },
   {
     "name": "notification-badge",
     "docPath": "docs/components/notification-badge.md",
     "sourcePath": "components/ui/notification-badge/index.ts",
-    "description": "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).",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["dot", "counter", "unread", "overlay-badge"],
-    "relatedComponents": ["badge", "button"]
+    "description": "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)."
   },
   {
     "name": "page-header",
     "docPath": "docs/components/page-header.md",
     "sourcePath": "components/ui/page-header/index.ts",
-    "description": "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\").",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["page-title", "heading", "section-header"],
-    "relatedComponents": ["breadcrumb", "header", "button"]
+    "description": "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\")."
+  },
+  {
+    "name": "pages",
+    "docPath": "docs/components/pages.md",
+    "sourcePath": "components/ui/pages.tsx",
+    "description": "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`."
   },
   {
     "name": "pagination",
     "docPath": "docs/components/pagination.md",
     "sourcePath": "components/ui/pagination/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["pages", "paging", "page-navigation", "next-prev"],
-    "relatedComponents": ["table"]
+    "description": "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."
   },
   {
     "name": "popover",
     "docPath": "docs/components/popover.md",
     "sourcePath": "components/ui/popover/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["floating-panel", "anchored-panel", "overlay-panel"],
-    "relatedComponents": ["tooltip", "hover-card", "sheet", "dialog"]
+    "description": "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."
   },
   {
     "name": "progress",
     "docPath": "docs/components/progress.md",
     "sourcePath": "components/ui/progress/index.ts",
-    "description": "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>`.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["loading-bar", "completion", "percentage"],
-    "relatedComponents": ["skeleton", "slider"]
+    "description": "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>`."
   },
   {
     "name": "radio-group",
     "docPath": "docs/components/radio-group.md",
     "sourcePath": "components/ui/radio-group/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["radio", "single-select", "exclusive-choice"],
-    "relatedComponents": ["select", "checkbox"]
+    "description": "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."
   },
   {
     "name": "rating",
     "docPath": "docs/components/rating.md",
     "sourcePath": "components/ui/rating/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["stars", "star-rating", "review-score"],
-    "relatedComponents": ["input"]
+    "description": "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."
   },
   {
     "name": "resizable",
     "docPath": "docs/components/resizable.md",
     "sourcePath": "components/ui/resizable/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["split-panel", "resize", "drag-handle", "panel-splitter"],
-    "relatedComponents": ["sidebar"]
+    "description": "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."
   },
   {
     "name": "rich-text-editor",
     "docPath": "docs/components/rich-text-editor.md",
     "sourcePath": "components/ui/rich-text-editor/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["wysiwyg", "editor", "text-editor"],
-    "relatedComponents": ["textarea", "form"]
+    "description": "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."
   },
   {
     "name": "route-map",
     "docPath": "docs/components/route-map.md",
     "sourcePath": "components/ui/route-map/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["directions", "route", "navigation-map", "waypoints"],
-    "relatedComponents": ["map", "simple-map"]
+    "description": "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."
   },
   {
     "name": "scroll-area",
     "docPath": "docs/components/scroll-area.md",
     "sourcePath": "components/ui/scroll-area/index.ts",
-    "description": "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).",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["scrollbar", "overflow", "custom-scroll"],
-    "relatedComponents": ["card", "sidebar"]
+    "description": "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)."
   },
   {
     "name": "search",
     "docPath": "docs/components/search.md",
     "sourcePath": "components/ui/search/index.ts",
-    "description": "A pre-built search input with a built-in search icon and clear button. Supports `sm`, `md`, `lg` size variants matching the Input scale. Handles Escape-to-clear and exposes `onSearch` for simple string callbacks.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["search-input", "filter", "query", "find"],
-    "relatedComponents": ["input", "command", "table"]
+    "description": "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."
   },
   {
     "name": "select",
     "docPath": "docs/components/select.md",
     "sourcePath": "components/ui/select/index.ts",
-    "description": "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>`.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["dropdown", "combobox", "picker", "chooser"],
-    "relatedComponents": ["radio-group", "command", "input"]
+    "description": "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>`."
   },
   {
     "name": "separator",
     "docPath": "docs/components/separator.md",
     "sourcePath": "components/ui/separator/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["divider", "hr", "horizontal-rule", "line"],
-    "relatedComponents": ["card"]
+    "description": "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."
   },
   {
     "name": "sheet",
     "docPath": "docs/components/sheet.md",
     "sourcePath": "components/ui/sheet/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["side-panel", "slide-in", "panel"],
-    "relatedComponents": ["dialog", "drawer", "popover"]
+    "description": "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."
   },
   {
     "name": "sidebar",
     "docPath": "docs/components/sidebar.md",
     "sourcePath": "components/layout/sidebar/index.ts",
-    "description": "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.",
-    "category": "layout",
-    "import": "xertica-ui/layout",
-    "keywords": ["nav", "navigation", "menu", "side-nav", "vertical-nav"],
-    "relatedComponents": ["header", "navigation-menu"]
+    "description": "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."
   },
   {
     "name": "simple-map",
     "docPath": "docs/components/simple-map.md",
     "sourcePath": "components/ui/simple-map/index.ts",
-    "description": "A simplified wrapper for common map use cases where you only need a single marker and basic configuration.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["basic-map", "single-marker", "map-pin"],
-    "relatedComponents": ["map", "route-map"]
+    "description": "A simplified wrapper for common map use cases where you only need a single marker and basic configuration."
   },
   {
     "name": "skeleton",
     "docPath": "docs/components/skeleton.md",
     "sourcePath": "components/ui/skeleton/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["loading-placeholder", "shimmer", "placeholder"],
-    "relatedComponents": ["progress", "empty"]
+    "description": "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."
   },
   {
     "name": "slider",
     "docPath": "docs/components/slider.md",
     "sourcePath": "components/ui/slider/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["range", "range-input", "volume", "scrubber"],
-    "relatedComponents": ["progress", "input"]
+    "description": "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."
   },
   {
     "name": "sonner",
     "docPath": "docs/components/sonner.md",
     "sourcePath": "components/ui/sonner/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["toast", "notification", "snackbar", "alert-message"],
-    "relatedComponents": ["alert", "dialog"]
+    "description": "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."
   },
   {
     "name": "stats-card",
     "docPath": "docs/components/stats-card.md",
     "sourcePath": "components/ui/stats-card/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["kpi", "metric", "counter", "dashboard-card"],
-    "relatedComponents": ["card", "chart"]
+    "description": "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."
   },
   {
     "name": "stepper",
     "docPath": "docs/components/stepper.md",
     "sourcePath": "components/ui/stepper/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["wizard", "multi-step", "progress-steps", "onboarding"],
-    "relatedComponents": ["progress", "tabs"]
+    "description": "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."
   },
   {
     "name": "switch",
     "docPath": "docs/components/switch.md",
     "sourcePath": "components/ui/switch/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["toggle", "on-off", "boolean", "feature-flag"],
-    "relatedComponents": ["checkbox", "toggle"]
+    "description": "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."
   },
   {
     "name": "table",
     "docPath": "docs/components/table.md",
     "sourcePath": "components/ui/table/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["data-table", "grid", "list", "rows", "columns", "crud"],
-    "relatedComponents": ["pagination", "badge", "dropdown-menu", "empty"]
+    "description": "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."
   },
   {
     "name": "tabs",
     "docPath": "docs/components/tabs.md",
     "sourcePath": "components/ui/tabs/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["tab-bar", "tab-panel", "switcher", "tabbed-content"],
-    "relatedComponents": ["navigation-menu", "accordion"]
+    "description": "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."
   },
   {
     "name": "textarea",
     "docPath": "docs/components/textarea.md",
     "sourcePath": "components/ui/textarea/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["multi-line", "text-area", "description-field", "notes"],
-    "relatedComponents": ["input", "form", "rich-text-editor"]
+    "description": "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."
   },
   {
     "name": "theme-toggle",
     "docPath": "docs/components/theme-toggle.md",
     "sourcePath": "components/brand/theme-toggle/index.ts",
-    "description": "A self-contained light/dark mode toggle button that operates directly on the `document.documentElement` class list.",
-    "category": "brand",
-    "import": "xertica-ui/brand",
-    "keywords": ["dark-mode", "light-mode", "color-scheme"],
-    "relatedComponents": ["header", "sidebar"]
+    "description": "A self-contained light/dark mode toggle button that operates directly on the `document.documentElement` class list."
   },
   {
     "name": "timeline",
     "docPath": "docs/components/timeline.md",
     "sourcePath": "components/ui/timeline/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["activity-log", "history", "event-log", "audit-trail"],
-    "relatedComponents": ["table", "card"]
+    "description": "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."
   },
   {
     "name": "toggle-group",
     "docPath": "docs/components/toggle-group.md",
     "sourcePath": "components/ui/toggle-group/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["segmented-control", "exclusive-toggle", "multi-toggle"],
-    "relatedComponents": ["toggle", "tabs"]
+    "description": "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."
   },
   {
     "name": "toggle",
     "docPath": "docs/components/toggle.md",
     "sourcePath": "components/ui/toggle/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["pressable", "pressed-state", "toolbar-toggle"],
-    "relatedComponents": ["switch", "checkbox", "toggle-group"]
+    "description": "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."
   },
   {
     "name": "tooltip",
     "docPath": "docs/components/tooltip.md",
     "sourcePath": "components/ui/tooltip/index.ts",
-    "description": "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.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["hint", "title", "help-text", "hover-text"],
-    "relatedComponents": ["hover-card", "popover"]
+    "description": "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."
   },
   {
     "name": "tree-view",
     "docPath": "docs/components/tree-view.md",
     "sourcePath": "components/ui/tree-view/index.ts",
-    "description": "An interactive hierarchical tree component for displaying and navigating nested data structures — file systems, organizational charts, category trees, and recursive navigation menus.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["tree", "hierarchy", "nested-list", "file-tree"],
-    "relatedComponents": ["accordion", "sidebar"]
+    "description": "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."
   },
   {
     "name": "use-mobile",
     "docPath": "docs/components/use-mobile.md",
-    "sourcePath": "components/shared/use-mobile.ts",
-    "description": "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.",
-    "category": "hooks",
-    "import": "xertica-ui/hooks",
-    "keywords": ["responsive", "mobile-detection", "breakpoint", "isMobile"],
-    "relatedComponents": []
+    "sourcePath": "components/ui/use-mobile.tsx",
+    "description": "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."
+  },
+  {
+    "name": "video-player",
+    "docPath": "docs/components/video-player.md",
+    "sourcePath": "components/ui/video-player.tsx",
+    "description": "A feature-rich video player component with floating mode support, custom controls, and automatic state management."
   },
   {
     "name": "xertica-logo",
     "docPath": "docs/components/xertica-logo.md",
     "sourcePath": "components/brand/xertica-logo/index.ts",
-    "description": "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.",
-    "category": "brand",
-    "import": "xertica-ui/brand",
-    "keywords": ["logo", "brand", "logotype"],
-    "relatedComponents": ["xertica-xlogo", "xertica-orbe"]
+    "description": "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."
   },
   {
     "name": "xertica-orbe",
     "docPath": "docs/components/xertica-orbe.md",
     "sourcePath": "components/brand/xertica-orbe/index.ts",
-    "description": "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.",
-    "category": "brand",
-    "import": "xertica-ui/brand",
-    "keywords": ["orb", "animated-logo", "brand-animation"],
-    "relatedComponents": ["xertica-logo"]
+    "description": "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."
   },
   {
     "name": "xertica-provider",
     "docPath": "docs/components/xertica-provider.md",
     "sourcePath": "components/brand/xertica-provider/index.ts",
-    "description": "The mandatory root wrapper for all Xertica UI applications. It synchronizes global configurations and injects essential context providers for layout, tooltips, maps, and notifications.",
-    "category": "brand",
-    "import": "xertica-ui/brand",
-    "keywords": ["provider", "root", "context", "app-wrapper"],
-    "relatedComponents": []
+    "description": "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."
   },
   {
     "name": "xertica-xlogo",
     "docPath": "docs/components/xertica-xlogo.md",
     "sourcePath": "components/brand/xertica-xlogo/index.ts",
-    "description": "A compact, square variant of the Xertica logo featuring the stylized \"X\" mark. Ideal for favicons, collapsed sidebars, and small profile badges.",
-    "category": "brand",
-    "import": "xertica-ui/brand",
-    "keywords": ["x-logo", "compact-logo", "icon-logo", "favicon"],
-    "relatedComponents": ["xertica-logo", "sidebar"]
-  },
-  {
-    "name": "video-player",
-    "docPath": "docs/components/video-player.md",
-    "sourcePath": "components/media/video-player/index.ts",
-    "description": "A feature-rich video player with custom controls, progress bar, volume, and floating mode support. Built on HTML5 video with React state management.",
-    "category": "media",
-    "import": "xertica-ui/media",
-    "keywords": ["video", "player", "media", "playback"],
-    "relatedComponents": ["audio-player", "floating-media-wrapper"]
-  },
-  {
-    "name": "code-block",
-    "docPath": "docs/components/assistant.md",
-    "sourcePath": "components/assistant/code-block/index.ts",
-    "description": "A syntax-highlighted code block component for the Xertica Assistant. It renders code snippets with language detection and copy-to-clipboard functionality.",
-    "category": "assistant",
-    "import": "xertica-ui/assistant",
-    "keywords": ["syntax-highlight", "code", "snippet", "copy-code"],
-    "relatedComponents": ["markdown-message", "xertica-assistant"]
-  },
-  {
-    "name": "formatted-document",
-    "docPath": "docs/components/assistant.md",
-    "sourcePath": "components/assistant/formatted-document/index.ts",
-    "description": "A structured document renderer for displaying AI-generated content with headings, paragraphs, lists, and rich formatting support.",
-    "category": "assistant",
-    "import": "xertica-ui/assistant",
-    "keywords": ["formatted document"],
-    "relatedComponents": []
-  },
-  {
-    "name": "modern-chat-input",
-    "docPath": "docs/components/assistant.md",
-    "sourcePath": "components/assistant/modern-chat-input/index.ts",
-    "description": "A chat input component for the AI Assistant with multi-line support, auto-resize, and keyboard shortcuts. Used as the primary input in the assistant interface.",
-    "category": "assistant",
-    "import": "xertica-ui/assistant",
-    "keywords": ["modern chat input"],
-    "relatedComponents": []
-  },
-  {
-    "name": "xertica-assistant",
-    "docPath": "docs/components/assistant.md",
-    "sourcePath": "components/assistant/xertica-assistant/index.ts",
-    "description": "A conversational AI assistant panel that integrates with the application. Provides chat interface, message rendering, suggestions, and file attachments.",
-    "category": "assistant",
-    "import": "xertica-ui/assistant",
-    "keywords": ["ai-chat", "chatbot", "ai-panel", "assistant", "llm-chat"],
-    "relatedComponents": ["markdown-message", "code-block"]
-  },
-  {
-    "name": "login-page",
-    "docPath": "docs/getting-started.md",
-    "sourcePath": "components/pages/login-page/index.ts",
-    "description": "A complete login page template with email/password fields, theme toggle, and language selector integration.",
-    "category": "pages",
-    "import": "xertica-ui",
-    "keywords": ["login page"],
-    "relatedComponents": []
-  },
-  {
-    "name": "forgot-password-page",
-    "docPath": "docs/getting-started.md",
-    "sourcePath": "components/pages/forgot-password-page/index.ts",
-    "description": "A forgot password page template with email input and reset flow integration.",
-    "category": "pages",
-    "import": "xertica-ui",
-    "keywords": ["forgot password page"],
-    "relatedComponents": []
-  },
-  {
-    "name": "reset-password-page",
-    "docPath": "docs/getting-started.md",
-    "sourcePath": "components/pages/reset-password-page/index.ts",
-    "description": "A reset password page template with new password and confirmation fields.",
-    "category": "pages",
-    "import": "xertica-ui",
-    "keywords": ["reset password page"],
-    "relatedComponents": []
-  },
-  {
-    "name": "verify-email-page",
-    "docPath": "docs/getting-started.md",
-    "sourcePath": "components/pages/verify-email-page/index.ts",
-    "description": "A verify email page template with OTP code input for email verification.",
-    "category": "pages",
-    "import": "xertica-ui",
-    "keywords": ["verify email page"],
-    "relatedComponents": []
-  },
-  {
-    "name": "home-page",
-    "docPath": "docs/getting-started.md",
-    "sourcePath": "components/pages/home-page/index.ts",
-    "description": "A home page template with sidebar navigation, header, and content area. The base layout for application pages.",
-    "category": "pages",
-    "import": "xertica-ui",
-    "keywords": ["home page"],
-    "relatedComponents": []
-  },
-  {
-    "name": "home-content",
-    "docPath": "docs/getting-started.md",
-    "sourcePath": "components/pages/home-content/index.ts",
-    "description": "The content area component for home pages, providing a flexible container for page-specific content.",
-    "category": "pages",
-    "import": "xertica-ui",
-    "keywords": ["home content"],
-    "relatedComponents": []
-  },
-  {
-    "name": "template-page",
-    "docPath": "docs/getting-started.md",
-    "sourcePath": "components/pages/template-page/index.ts",
-    "description": "A flexible page template component that wraps the layout system with configurable header, sidebar, and content areas.",
-    "category": "pages",
-    "import": "xertica-ui",
-    "keywords": ["template page"],
-    "relatedComponents": []
-  },
-  {
-    "name": "template-content",
-    "docPath": "docs/getting-started.md",
-    "sourcePath": "components/pages/template-content/index.ts",
-    "description": "A content wrapper component for template pages, providing consistent padding and layout behavior.",
-    "category": "pages",
-    "import": "xertica-ui",
-    "keywords": ["template content"],
-    "relatedComponents": []
-  },
-  {
-    "name": "map-layers",
-    "docPath": "docs/components/map.md",
-    "sourcePath": "components/ui/map-layers/index.ts",
-    "description": "A utility for managing Google Maps layers including traffic, transit, bicycling, and weather layers with theme-aware styling.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["map layers"],
-    "relatedComponents": []
-  },
-  {
-    "name": "map-config",
-    "docPath": "docs/components/map.md",
-    "sourcePath": "components/ui/map-config/index.ts",
-    "description": "Configuration utility for Google Maps shared settings and theme-based styling.",
-    "category": "ui",
-    "import": "xertica-ui/ui",
-    "keywords": ["map config"],
-    "relatedComponents": []
-  },
-  {
-    "name": "floating-media-wrapper",
-    "docPath": "docs/components/floating-media-wrapper.md",
-    "sourcePath": "components/media/FloatingMediaWrapper.tsx",
-    "description": "A higher-level wrapper for media players (audio/video) that manages floating state, positioning, and transitions.",
-    "category": "media",
-    "import": "xertica-ui/media",
-    "keywords": ["floating", "draggable", "portal", "picture-in-picture"],
-    "relatedComponents": ["video-player", "audio-player"]
+    "description": "A compact, square variant of the Xertica logo featuring the stylized \"X\" mark. Ideal for favicons, collapsed sidebars, and small profile badges."
   }
-]
+]