[
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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/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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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 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."
  },
  {
    "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."
  },
  {
    "name": "chart",
    "docPath": "docs/components/chart.md",
    "sourcePath": "components/ui/chart/index.ts",
    "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."
  },
  {
    "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."
  },
  {
    "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`."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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": "evidence-map",
    "docPath": "docs/components/evidence-map.md",
    "sourcePath": "components/ui/evidence-map/index.ts",
    "description": "`EvidenceMap` is a read-only preset for a single captured coordinate: no controls, no dragging, no zooming, with the coordinate printed in monospace beside an integrity seal. The point of the component is that the position belongs to the **record**, not to the viewer."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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`."
  },
  {
    "name": "graph-node-list",
    "docPath": "docs/components/graph-node-list.md",
    "sourcePath": "components/ui/graph-node-list.tsx",
    "description": "`GraphNodeList` renders a `NetworkGraph`'s content as an operable list. A canvas is one opaque element to a screen reader: it can carry a label, but not the nodes and relationships inside it. This gives the same information and the same actions through plain keyboard and screen-reader navigation."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "name": "kanban",
    "docPath": "docs/components/kanban.md",
    "sourcePath": "components/ui/kanban/index.ts",
    "description": "`Kanban` renders a board of columns holding draggable cards, with work-in-progress limits as a first-class concept. It is controlled: the board reports a move and the consumer applies it, so card ordering lives with the data rather than inside a widget."
  },
  {
    "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."
  },
  {
    "name": "language-selector",
    "docPath": "docs/components/language-selector.md",
    "sourcePath": "components/brand/language-selector/index.ts",
    "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-basemap-control",
    "docPath": "docs/components/map-basemap-control.md",
    "sourcePath": "components/ui/map-basemap-control/index.ts",
    "description": "`MapBasemapControl` switches between the six base maps: roads, grayscale, high contrast, night, satellite and terrain. `high-contrast` is also the accessibility route for the map itself, not just a stylistic option."
  },
  {
    "name": "map-draw-toolbar",
    "docPath": "docs/components/map-draw-toolbar.md",
    "sourcePath": "components/ui/map-draw-toolbar/index.ts",
    "description": "`MapDrawToolbar` arms and disarms the geofence drawing tool. Paired with `<Map drawing>` and the `pointsInShape` utility, it answers \"who was inside this area\" with no extra Maps call — the `drawing` and `geometry` libraries were already being loaded."
  },
  {
    "name": "map-feature-list",
    "docPath": "docs/components/map-feature-list.md",
    "sourcePath": "components/ui/map-feature-list/index.ts",
    "description": "`MapFeatureList` renders the map's content as an operable list. A map is a spatial control, and a spatial control alone is not reachable by everyone. Pairing it with a list that shares `selectedId` in both directions gives the same information and the same actions through plain keyboard and screen-reader navigation."
  },
  {
    "name": "map-layer-panel",
    "docPath": "docs/components/map-layer-panel.md",
    "sourcePath": "components/ui/map-layer-panel/index.ts",
    "description": "`MapLayerPanel` shows and hides the named layers of a map. With four overlays on screen at once — heat underneath, areas, lines, points on top — the stack stops being an implementation detail and becomes the thing the user operates. Each row carries the layer's label, its color swatch and a switch, grouped by `group`."
  },
  {
    "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-legend",
    "docPath": "docs/components/map-legend.md",
    "sourcePath": "components/ui/map-legend/index.ts",
    "description": "`MapLegend` reads the color and size encodings of a map. It renders two independent keys: a **color key** (one entry per series or choropleth class) and a **size key** (what the radius of a proportional symbol means). Both derive from the same sources as the map itself, so the legend cannot drift out of step with the symbols it describes."
  },
  {
    "name": "map-locate-control",
    "docPath": "docs/components/map-locate-control.md",
    "sourcePath": "components/ui/map-locate-control/index.ts",
    "description": "`MapLocateControl` centres the map on the device's position and reports the accuracy alongside it. Every failure mode is classified rather than swallowed: a denied permission, a timeout and an absent provider are three different situations for the user."
  },
  {
    "name": "map-notice",
    "docPath": "docs/components/map-notice.md",
    "sourcePath": "components/ui/map-notice/index.ts",
    "description": "`MapNotice` is a persistent badge over the map for provenance, caveats, and attribution. It covers the two notices that must stay on screen permanently: the \"demonstrative data\" seal and any cartographic credit a tile license requires. Its surfaces are built from semantic tokens, so it stays legible in light and dark without consumer intervention."
  },
  {
    "name": "map-overlay",
    "docPath": "docs/components/map-overlay.md",
    "sourcePath": "components/ui/map-overlay/index.ts",
    "description": "`MapOverlay` anchors React content over the map surface. Nine anchors on one consistent stacking layer, so a legend does not end up underneath a notice on one screen and above it on the next."
  },
  {
    "name": "map-scale-bar",
    "docPath": "docs/components/map-scale-bar.md",
    "sourcePath": "components/ui/map-scale-bar/index.ts",
    "description": "`MapScaleBar` renders a graphic scale bar, recalculated on every zoom change. Reports and dossiers circulate off screen, and a static map with no scale cannot support a claim about distance."
  },
  {
    "name": "map-timeline",
    "docPath": "docs/components/map-timeline.md",
    "sourcePath": "components/ui/map-timeline/index.ts",
    "description": "`MapTimeline` is a time ruler bound to the map: a sliding window, playback at several speeds, and filtering of features by their timestamp. It is what turns plotted points into a space-time reconstruction, and the same mechanism serves an inspection-date filter or a day's schedule."
  },
  {
    "name": "map-view-control",
    "docPath": "docs/components/map-view-control.md",
    "sourcePath": "components/ui/map-view-control/index.ts",
    "description": "`MapViewControl` switches between named map views and exposes the reframe action. It is presentational: it reports the user's choice, and `<Map>` moves the camera. Hand the same `views` / `activeViewId` / `onViewChange` triple to both components."
  },
  {
    "name": "map",
    "docPath": "docs/components/map.md",
    "sourcePath": "components/ui/map/index.ts",
    "description": "`Map` renders an interactive Google Map with advanced markers, proportional symbology, per-feature selection and hover, theme-aware colors, content-driven framing, rich info windows, circles, polygons, and native overlay layers. It uses the built-in Xertica Google Maps loader and renders explicit container states when data is missing, restricted, or still loading."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "name": "network-graph",
    "docPath": "docs/components/network-graph.md",
    "sourcePath": "components/ui/network-graph/index.ts",
    "description": "`NetworkGraph` renders a three-dimensional, force-directed graph for ontology mapping and any other information with relationships and connections. Nodes and edges are typed, the layout is deterministic, and the whole thing draws to a canvas with **no runtime dependency** — no three.js, no d3, no graph library."
  },
  {
    "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)."
  },
  {
    "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\")."
  },
  {
    "name": "pages",
    "docPath": "docs/components/pages.md",
    "sourcePath": "components/ui/pages.tsx",
    "description": "Xertica UI ships 9 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."
  },
  {
    "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."
  },
  {
    "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>`."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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)."
  },
  {
    "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. 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>`."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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."
  },
  {
    "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. 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/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."
  },
  {
    "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."
  },
  {
    "name": "xertica-provider",
    "docPath": "docs/components/xertica-provider.md",
    "sourcePath": "components/brand/xertica-provider/index.ts",
    "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."
  }
]