# All Components

This file provides a comprehensive list of all components in the component library.

## Complete Component List

### ButtonGroup

**Import**: `import { ButtonGroup } from '@glide/glide-ui/button-group';`
**Props**: `actions, size?, variant?, className?`
**Description**: A flexible button group component where actions are automatically assigned roles based on position: first action becomes primary, second becomes secondary, and rest go into a dropdown menu. Supports two sizes (sm, md) and three variants with distinct styling behaviors: default (1st primary, rest secondary), accent (all primary), muted (all secondary). Menu actions are displayed in a dropdown using Radix UI's DropdownMenu. Each action can have a label, onClick handler, icon, and disabled state. Responsive by default with full-width buttons on mobile and natural width on desktop.

### AudioPlayer

**Import**: `import { AudioPlayer } from '@glide/glide-ui/audio-player';`
**Description**: A comprehensive and accessible audio player component with play/pause controls, seeking, volume control, playback rate adjustment, and keyboard shortcuts. Features three variants (default, compact, minimal), metadata display with cover art, loading/buffering states, and both controlled/uncontrolled modes. Built with full keyboard navigation and screen reader support for playing audio files, podcasts, and music.

### AppIcon

**Import**: `import { AppIcon } from '@glide/glide-ui/app-icon';`
**Props**: `icon?, size?, alt?, background?, variant?, color?`
**Description**: A flexible app icon component that supports emojis, image URLs, and text fallbacks. Designed to be used across different contexts from small navbar icons to large splash screen icons.

### Avatar

**Import**: `import { Avatar, AvatarImage, AvatarFallback } from '@glide/glide-ui/avatar';`
**Props**: Avatar (container), AvatarImage (src, alt), AvatarFallback (color variant, children)
**Description**: A composable avatar component following Shadcn's pattern for displaying user profile pictures with automatic fallback to initials. Features three components: Avatar (root container), AvatarImage (handles image loading), and AvatarFallback (shows initials with 9 color variants). Built on Radix UI Avatar for reliable image loading, automatic fallback handling, and full accessibility support. The composable pattern ensures LLM agents can correctly understand and implement the component based on standard Shadcn documentation.

### Button

**Import**: `import { Button } from '@glide/glide-ui/button';`
**Props**: `variant?, mood?, size?, leftIcon?, rightIcon?, icon?, loadingText?, ...HTML button attributes`
**Description**: A versatile button component with multiple variants, sizes, loading states, and icon support.

### Input

**Import**: `import { Input } from '@glide/glide-ui/input';`
**Props**: `label?, description?, error?, hint?, ...HTML input attributes`
**Description**: A fully accessible form input component with optional labels, descriptions, hints, error states, and various input types.

### Label

**Import**: `import { Label } from '@glide/glide-ui/label';`
**Props**: `htmlFor?, ...HTML label attributes`
**Description**: A semantic and accessible label component for associating text with form controls. Built on Radix UI Label primitive with proper accessibility, cursor styling, and disabled state support. Perfect for labeling inputs, textareas, checkboxes, radio buttons, switches, and any form element requiring descriptive text.

### NumberInput

**Import**: `import { NumberInput } from '@glide/glide-ui/number-input';`
**Props**: `label?, description?, min?, max?, step?, ...Input props`
**Description**: A specialized input component for numeric values that extends the base Input component with number-specific attributes (min, max, step) and validation. Provides HTML5 number input features including spinner controls, keyboard navigation, built-in validation, and optional label and description for consistent form field styling.

### Dialog ⚠️ MANDATORY FOR ALL DIALOGS

**Import**: `import { Dialog, DialogContent, DialogDescription, DialogBody, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from '@glide/glide-ui/dialog';`
**Props**: DialogContent: `variant?` ('modal' | 'sheet'), `position?` ('right' | 'left' | 'top' | 'bottom'), plus Radix UI Dialog props
**Description**: **ALL dialogs in the application MUST use this component.** Supports two variants: Modal (centered, fullscreen on mobile) and Sheet (slides in from side on desktop, bottom on mobile with gap). Sheet position can be customized on desktop. Never create custom dialogs or use third-party libraries.

### Link and NavLink

**Import**: `import { Link, NavLink } from '@glide/glide-ui/link';`
**Props**: `href, dontAnimate?` for Link, `href` for NavLink
**Description**: Enhanced navigation components that automatically determine transition animations based on URL hierarchy. Link provides intelligent, zero-configuration page transitions, while NavLink adds active state management.

### Form

**Import**: `import { Form } from '@glide/glide-ui/form';`
**Props**: `nested?, ...HTML form attributes`
**Description**: A flexible, accessible form wrapper component that provides consistent spacing and behavior for forms. Supports nested forms, validation, and all HTML5 form attributes.

### Stepper

**Import**: `import { Stepper } from '@glide/glide-ui/stepper';`
**Props**: `steps, currentStep, variant?, orientation?, size?, clickable?, allowFutureSteps?, onStepClick?, hideDescriptionOnMobile?`
**Description**: A versatile stepper component for multi-step processes with multiple display styles including default numbered steps, progress bar, and checkpoint variations. Fully accessible with optional interactive navigation.

### ComboBox

**Import**: `import { Combobox, ComboboxTrigger, ComboboxContent, ComboboxInput, ComboboxList, ComboboxEmpty, ComboboxGroup, ComboboxItem, ComboboxSeparator, ComboboxCreateNew } from '@glide/glide-ui/combobox';`
**Props**: `data, type, label?, description?, defaultValue?, value?, onValueChange?, open?, onOpenChange?`
**Description**: A flexible and accessible combobox (autocomplete select) component with searchable dropdown functionality, grouping support, and custom item creation. Built with Radix UI primitives for full keyboard navigation and screen reader support. Features optional label and description for consistent form field styling.

### Status

**Import**: `import { Status } from '@glide/glide-ui/status';`
**Props**: `variant?, label, pulse?`
**Description**: A clean status indicator component that extends Badge with a colored dot indicator and label with optional pulsing animation. Uses semantic color variants (success, warning, destructive, info) for consistent status display across system health, user presence, build status, inventory levels, and more. Features outline badge styling with required label and pulse animation for states needing attention.

### Badge

**Import**: `import { Badge } from '@glide/glide-ui/badge';`
**Props**: `variant?, asChild?, removable?, onRemove?`
**Description**: A flexible badge component with semantic color variants (default, secondary, success, warning, destructive, info). Features removable functionality, icon support, and can be rendered as interactive elements via Radix Slot. Perfect for status indicators, notifications, tags, and labels.

### Breadcrumb

**Import**: `import { Breadcrumb } from '@glide/glide-ui/breadcrumb';`
**Props**: `items, showBackButton?, backButtonHref?, onBackClick?`
**Description**: A responsive breadcrumb navigation component with integrated back button that adapts between desktop and mobile views. Displays full breadcrumb trail on desktop and a simplified back button on mobile with fixed overlay header.

### Card

**Import**: `import { Card, CardContent, CardFooter } from '@glide/glide-ui/card';`
**Props**: `className?, children`
**Description**: A flexible and composable card component for displaying content in a contained, elevated surface. Follows a simplified compound component pattern with CardContent for main content and CardFooter for actions. Features responsive padding and semantic styling that adapts to light/dark themes.

### FilterToolbar

**Import**: `import { FilterToolbar, FilterToolbarTitle, FilterToolbarSearch, FilterGroup, Filter, FilterToolbarButtons, FilterToolbarButton } from '@glide/glide-ui/filter-toolbar';`
**Props**: FilterToolbar: `variant?` ("horizontal" | "vertical" | "compact") | FilterToolbarTitle: `count?` | FilterToolbarSearch: `onSearch?, debounceMs?` | Filter: `label, options, value, onChange, multiple?, displayVariant?, maxVisibleOptions?, defaultOpen?` | FilterGroup: `activeCount?, onClearAll?` | FilterToolbarButton: `priority?, leftIcon?, rightIcon?`
**Description**: **CRITICAL: FilterToolbar has THREE variants - actively consider VERTICAL and COMPACT for better UX.** (1) **HORIZONTAL**: Only for 1-3 filters on simple lists. Basic inline layout. (2) **VERTICAL** (RECOMMENDED for complex filtering): Use for 4+ filters, Dialog sheets, or when you want superior UX with collapsible sections, toggle buttons, pill selectors, and "show more" functionality. Provides the best user experience for complex filtering. Pairs perfectly with Dialog variant="sheet" for professional slide-in filter panels. (3) **COMPACT** (RECOMMENDED for 4+ filters): Use when you have 4+ filters or space is limited. Much cleaner than horizontal with many filters - all filters in elegant single dropdown with active count badge. **Decision rules:** 4+ filters → VERTICAL or COMPACT (never horizontal). Dialog sheet → VERTICAL. Need toggle/pills → VERTICAL. Space limited → COMPACT. Only 1-3 simple filters → horizontal. Features debounced search, multi-select, and action buttons. Perfect for product listings, data tables, employee directories, and any collection with search/filter/actions. For main page headers without filtering, use ScreenTitle instead.

### Command

**Import**: `import { Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandShortcut, CommandSeparator } from '@glide/glide-ui/command';`
**Props**: Command: `value?, onValueChange?` | CommandInput: `placeholder?` | CommandItem: `value, onSelect?, disabled?` | CommandGroup: `heading`
**Description**: Always use this component set to build any menu in the application.
This includes command palettes, dropdown menus, context menus, search interfaces, and any list-based selection UI.
These components provide a flexible, accessible, and keyboard-friendly menu framework with built-in support for search/filtering, grouping, keyboard navigation, and dialog integration.

### Popover

**Import**: `import { Popover, PopoverTrigger, PopoverContent, PopoverAnchor } from '@glide/glide-ui/popover';`
**Props**: Various Radix UI Popover props
**Description**: A floating overlay component that displays rich content relative to a trigger element. Built on Radix UI primitives with smart positioning, collision detection, and full accessibility support. Ideal for contextual menus and rich tooltips.

### Select

**Import**: `import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@glide/glide-ui/select';`
**Props**: SelectTrigger: `label?, description?, required?`, plus various Radix UI Select props
**Description**: A comprehensive and accessible select dropdown component built on Radix UI primitives with full keyboard navigation, screen reader support, and customizable styling. Supports multiple sizes, grouping, separators, and scrollable content with smart positioning. Features optional label and description on SelectTrigger for consistent form field styling.

### Textarea

**Import**: `import { Textarea } from '@glide/glide-ui/textarea';`
**Props**: `label?, description?, ...HTML textarea attributes`
**Description**: A customizable multi-line text input component with automatic height adjustment and consistent styling. Features modern CSS auto-sizing, responsive text sizing, optional label and description for consistent form field styling, and comprehensive form integration support.

### Checkbox

**Import**: `import { Checkbox } from '@glide/glide-ui/checkbox';`
**Props**: `label?, description?, checked?, defaultChecked?, onCheckedChange?, disabled?`
**Description**: A fully accessible checkbox component built on Radix UI primitives with support for three states (checked, unchecked, indeterminate). Features optional label and description, proper keyboard navigation, screen reader support, and form integration capabilities. **Best Practice**: Always use the built-in `label` prop instead of wrapping the component with an external `<label>` or `<Label>` element for proper accessibility and consistent UI patterns. When no label is provided, the component renders as a standalone checkbox element.

### Checklist

**Import**: `import { Checklist } from '@glide/glide-ui/checklist';`
**Props**: `items, onItemChange?, onSelectAll?, showSelectAll?, selectAllLabel?, disabled?`
**Description**: A multi-select checkbox list component that displays a collection of checkable items with optional "select all" functionality. Perfect for filters, preferences, bulk selections, and any scenario requiring multiple selections from a list.

### RadioGroup

**Import**: `import { RadioGroup, RadioGroupItem } from '@glide/glide-ui/radio-group';`
**Props**: RadioGroup: `value?, defaultValue?, onValueChange?, orientation?, disabled?` | RadioGroupItem: `value, label, description?`
**Description**: A fully accessible radio group component for mutually exclusive selections. Built on Radix UI primitives with required labels for each option, optional descriptions, horizontal/vertical layouts, and comprehensive form integration. Provides proper keyboard navigation and screen reader support.

### Rating

**Import**: `import { Rating, RatingButton } from '@glide/glide-ui/rating';`
**Props**: `value?, defaultValue?, onChange?, onValueChange?, readOnly?, className?, children?`
**Description**: A flexible star rating component that supports interactive rating selection, read-only display, custom icons, and keyboard navigation. Features accent color theming for active states, hover effects, controllable state management, and full accessibility support. Perfect for product reviews, feedback forms, and quality ratings.

### Switch

**Import**: `import { Switch } from '@glide/glide-ui/switch';`
**Props**: `label?, description?, size?, checked?, defaultChecked?, onCheckedChange?, disabled?`
**Description**: A fully accessible toggle switch component for binary on/off states. Features optional label and description, and three size variants (default, small, xs) to fit different UI contexts. Built on Radix UI primitives with proper keyboard navigation, screen reader support, and form integration capabilities. **Best Practice**: Always use the built-in `label` prop instead of wrapping the component with an external `<label>` or `<Label>` element for proper accessibility and consistent UI patterns. When no label is provided, the component renders as a standalone switch element. Perfect for settings panels and feature toggles.

### Signature & SignaturePad ✅ UPDATED

**Import**: `import { Signature, SignaturePad, SignatureRef } from '@glide/glide-ui/signature';`
**Props**: `value?, onChange?, onClear?, width?, height?, penColor?, penWidth?, disabled?, placeholder?, className?, canvasClassName?`
**Description**: Two signature components for different use cases. **Signature**: High-level component with preview display and dialog-based editing - shows existing signature or placeholder, opens SignaturePad in modal dialog when clicked, provides Cancel/Clear/Done controls with **fixed dialog shrinking issues**. **SignaturePad**: Low-level canvas-based signature drawing component for direct signature input with **enhanced saving reliability**. Both built on signature_pad library with controlled/uncontrolled modes, export functionality (PNG/SVG), **optimized resize handling**, and full accessibility support. Recent improvements include stable canvas dimensions in dialogs, enhanced onChange callbacks, and better performance. Perfect for legal documents, contracts, consent forms, approval workflows, and any application requiring digital signature capture.
**Documentation**: [Signature README](./signature/README.md)

### Tabs

**Import**: `import { Tabs, TabsList, TabsTrigger, TabsContent } from '@glide/glide-ui/tabs';`
**Description**: A set of layered sections of content controlled by a list of tabs. Built on Radix UI Tabs primitive with full accessibility, keyboard navigation, and screen reader support. Features compound component architecture, controlled and uncontrolled modes, flexible layouts (grid-based and auto-fit), icon and badge support, and seamless theme integration. Perfect for settings panels, data views, content categories, multi-step forms, and dashboard interfaces.

### Text

**Import**: `import { Text } from '@glide/glide-ui/text';`
**Props**: `variant?, as?, className?, children?`
**Description**: A flexible typography component that separates visual styling from semantic HTML markup. Features three size variants (large, medium, small) for consistent visual hierarchy, with a polymorphic `as` prop to control the actual HTML element rendered. This separation allows visual styling (variant) to be independent of semantic markup (as prop). Supports full TypeScript type safety with polymorphic component patterns and seamless integration with the design system. Perfect for maintaining consistent typography across headings, body text, labels, and any text content while preserving proper semantic HTML structure.
**Documentation**: [Text README](./text/README.md)

### Calendar

**Import**: `import { Calendar } from '@glide/glide-ui/calendar';`
**Description**: A comprehensive calendar component for displaying and managing events with multiple view modes (month, week, day, agenda). Built on react-big-calendar with full TypeScript support, event management, customizable styling, and responsive design. Perfect for scheduling applications, event planning, resource booking, and any application requiring calendar functionality with event display.

### Carousel

**Import**: `import { Carousel, CarouselSlide } from '@glide/glide-ui/carousel';`
**Props**: `slideIndex?, onSlideChange?, showArrows?, showDots?, loop?, autoplay?, duration?, height?, slidesToShow?, slideGap?, className?`
**Description**: A flexible and accessible carousel component inspired by Mantine, supporting both images and HTML content. Features navigation controls, indicators/dots, keyboard navigation, touch/mouse dragging, autoplay with pause on hover, multiple slides display, customizable gaps and transitions, responsive design, and full accessibility support. Perfect for image galleries, product showcases, testimonials, hero banners, content sliders, and any scrollable content presentation. Built with compound component pattern using Carousel and CarouselSlide for maximum flexibility.

### CalendarPicker

**Import**: `import { CalendarPicker, CalendarDayButton } from '@glide/glide-ui/calendar-picker';`
**Description**: A flexible and fully accessible calendar picker component built on react-day-picker with comprehensive date selection capabilities. Supports single date, multiple dates, and date range selection with customizable styling, keyboard navigation, month/year dropdowns, and full internationalization support.

### DatePicker

**Import**: `import { DatePicker } from '@glide/glide-ui/date-picker';`
**Props**: `label?, description?, value?, onChange?, placeholder?, showTime?, showDate?, is24Hour?, className?`
**Description**: A unified date picker component that supports date-only, date-time, and time-only selection modes. Features optional label and description for consistent form field styling, optional time selection via `showTime` prop, optional date selection via `showDate` prop, dual time format support (12-hour with AM/PM and 24-hour via `is24Hour`), controlled component behavior, input-styled appearance, and comprehensive accessibility. Use for simple date selection, complete date-time input, or time-only selection. Perfect for scheduling, event planning, appointment booking, daily schedules, opening hours, and any application requiring date, time, or date-time selection.

### Editor

**Import**: `import { Editor, EditorProvider } from '@glide/glide-ui/editor';`
**Props**: `className?, limit?, placeholder?, ...TipTap EditorProvider props`
**Description**: A rich text editor component built with TipTap, featuring formatting controls, slash commands, structured content support, and comprehensive keyboard shortcuts. Includes toolbar for text formatting, support for headings, lists, code blocks, and tables. Perfect for content creation, documentation, and any rich text editing needs.

### Hint

**Import**: `import { Hint } from '@glide/glide-ui/hint';`
**Props**: `mood?, icon?, title?, dismissible?, onDismiss?`
**Description**: A flexible hint component for displaying informational messages, warnings, errors, and success states with optional dismissal functionality. Supports multiple moods (default, danger, warning, success, neutral) with appropriate styling and icons. Features keyboard dismissal with Escape key and fully accessible design.

### Slider

**Import**: `import { Slider } from '@glide/glide-ui/slider';`
**Props**: `label?, description?, value?, defaultValue?, onValueChange?, min?, max?, step?, disabled?, orientation?`
**Description**: A customizable range slider component for selecting numeric values within a defined range. Built on Radix UI Slider primitive with full accessibility support, multiple handle capability for range selection, both horizontal and vertical orientations, and optional label and description for consistent form field styling.

### Spinner

**Location**: `src/components/spinner/`
**Import**: `import { Spinner } from '@glide/glide-ui/spinner';`
**Props**: `size?, className?`
**Description**: A simple and lightweight loading spinner component that uses the Lucide `LoaderIcon` with a CSS spin animation. Perfect for indicating loading states and ongoing processes with customizable size, color theming, full accessibility support, and optimal performance. Supports all Lucide React icon props for maximum flexibility.
**Documentation**: [Spinner README](./spinner/README.md)

### Accordion

**Import**: `import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@glide/glide-ui/accordion';`
**Props**: `multiple?, value?, defaultValue?, onValueChange?, disabled?`
**Description**: A collapsible content component that allows users to show and hide sections of related content. Built on Radix UI Accordion primitive with smooth animations, full keyboard navigation, and screen reader support. Supports single mode (only one item open) and multiple mode (multiple items can be open).

### ProgressBar

**Import**: `import { ProgressBar } from '@glide/glide-ui/progress-bar';`
**Props**: `value?, max?, indeterminate?, variant?, label?, showValue?`
**Description**: A customizable progress indicator component for displaying completion status or loading states. Built on Radix UI Progress primitive with smooth animations, indeterminate state support, and full accessibility compliance.

### List

**Import**: `import { List, ListItem } from '@glide/glide-ui/list';`
**Props**: List: `pageSize?` | ListItem: `href?, onClick?, disabled?`
**Description**: An interactive-first list component that automatically detects and applies appropriate behavior based on props. With `href` it becomes a navigation list using Link, with `onClick` it renders as actionable buttons. Features automatic dividers, hover states, built-in pagination (enabled by default with 20 items per page), and semantic HTML structure. Pagination is on by default - set `pageSize={0}` to disable and show all items. List handles pagination internally similar to DataTable. No styling needed for common cases.

### Grid

**Import**: `import { Grid, GridItem } from '@glide/glide-ui/grid';`
**Props**: Grid: `loading?, cols?, skeletonCount?` | GridItem: `className?`
**Description**: A minimal grid layout component with responsive defaults (2 columns mobile, 3 columns tablet, 4 columns desktop) and automatic gap sizing (8px mobile, 16px desktop). **Important**: GridItem adds NO visual styling - it's purely a layout wrapper. Add your own card styles only when needed. Includes built-in loading state with skeleton placeholders.

### DataTable

**Import**: `import { DataTable } from '@glide/glide-ui/table';`
**Props**: `columns, data, enableSorting?, enableFiltering?, enablePagination?, enableRowSelection?, onRowClick?, loading?, emptyMessage?`
**Description**: A comprehensive data table component built on TanStack Table (React Table v8) with full-featured functionality. Supports sorting, filtering, pagination, row selection, column visibility controls, loading states, and responsive design. **Row clicking is a common interaction pattern** - use `onRowClick` to handle row clicks for navigation or actions. When provided, rows automatically show hover states and cursor pointer. Use this component for all data table needs - the internal table primitives are not exposed. Features debounced search, skeleton loading, keyboard navigation, and full accessibility support. **IMPORTANT**: DataTable handles pagination internally via `enablePagination` prop - do NOT use the standalone Pagination component with DataTable.

### Pagination

**Import**: `import { Pagination } from '@glide/glide-ui/pagination';`
**Props**: `currentPage, totalPages, onPageChange, variant?`
**Description**: A minimal and clean pagination component designed to work below collection components (like lists and grids). Provides intuitive navigation through paginated content with both numbered and simple previous/next variants. Features responsive design, smart ellipsis handling, and full accessibility support. **IMPORTANT**: Do NOT use this component with DataTable or List - they both handle pagination internally.

### Collection Toolbar (Pattern)

**Import**: `import { Input } from '@glide/glide-ui/input'; import { Select } from '@glide/glide-ui/select'; import { Button } from '@glide/glide-ui/button';`
**Props**: N/A - This is a composition pattern
**Description**: Standard pattern for collection toolbars above List, Grid, or DataTable components. Provides search input on the left, filters and actions on the right. Structure: `<div className="flex items-center justify-between gap-4 mb-4">` with search (`Input type="search"`) and action buttons (`Select`, `Button`). Place above collection component for consistent collection management.

### HoverCard

**Import**: `import { HoverCard, HoverCardContent, HoverCardTrigger } from '@glide/glide-ui/hover-card';`
**Props**: `open?, defaultOpen?, onOpenChange?, openDelay?, closeDelay?`
**Description**: A card that displays rich content when hovering over a trigger element. Built on Radix UI Hover Card with smooth animations, customizable timing delays, and flexible positioning. Perfect for user profiles, product previews, contextual information, and any content that needs detailed preview on hover. Features fade and scale animations with proper transform origins for natural appearance.
**Documentation**: [HoverCard README](./hover-card/README.md)

### Image

**Import**: `import { Image } from '@glide/glide-ui/image';`
**Props**: `src?, alt?, fallback?, placeholder?, showLoading?, loadingContent?, onError?, onLoad?, containerClassName?, ...HTML img attributes`
**Description**: A robust image component with comprehensive fallback handling and loading states. Displays placeholder content when no src is provided, shows fallback content when image fails to load, and supports custom loading states. Built with accessibility in mind, providing proper ARIA attributes and semantic HTML structure. Features graceful error handling, custom content slots for all states, and full support for standard img element properties. Perfect for user avatars, product images, gallery displays, and any scenario requiring reliable image rendering with fallbacks.

### ImageGallery

**Import**: `import { ImageGallery } from '@glide/glide-ui/image-gallery';`
**Props**: `images, selectedIndex?, defaultSelectedIndex?, onImageChange?, onImageError?, aspectRatio?, thumbnailsPerView?, imageFallback?, disabled?, className?`
**Description**: A streamlined and accessible image gallery component with main image display and thumbnail navigation. Features controlled/uncontrolled modes, configurable aspect ratios, adjustable number of visible thumbnails (defaults to 6), keyboard navigation (arrow keys), touch-friendly interactions, automatic loading states, error handling, and full accessibility support. Built with the Image component for reliable rendering. Perfect for product galleries, photo portfolios, real estate listings, and any scenario requiring interactive image browsing with thumbnail selection.

### Kanban

**Import**: `import { KanbanBoard, KanbanCard, KanbanCards, KanbanHeader, KanbanAddButton } from '@glide/glide-ui/kanban';`
**Props**: KanbanBoard: `children, className?` | KanbanCard: `id, children, ...item props` | KanbanCards: `columnId, items`
**Description**: A drag-and-drop Kanban board component for visual task management and workflow organization. Features column-based layout, card dragging between columns, customizable card rendering, and full keyboard navigation. Perfect for project management, task tracking, workflow visualization, and agile development boards.

### Tooltip

**Import**: `import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from '@glide/glide-ui/tooltip';`
**Props**: Various Radix UI Tooltip props
**Description**: A flexible and accessible tooltip component built on Radix UI primitives for displaying contextual information on hover or focus. Perfect for icon-only buttons, abbreviations, truncated text, and status indicators. Provides informative content without cluttering the interface.

### Charts

**Import**: `import { AreaChart, BarChart, LineChart, ComposedChart, PieChart, RadarChart, RadialBarChart, ScatterChart, FunnelChart, Treemap, SankeyChart } from '@glide/glide-ui/charts';`
**Props**: `data, width?, height?, margin?, ...Recharts props`
**Description**: A comprehensive collection of responsive chart components built with Recharts and styled with shadcn/ui design patterns. All charts use ResponsiveContainer for automatic responsive sizing and support light/dark mode through the existing theme system. Includes 11 chart types: Area, Bar, Line, Composed, Pie, Radar, RadialBar, Scatter, Funnel, Treemap, and Sankey charts.

### Map

**Import**: `import { Map } from '@glide/glide-ui/map';`
**Props**: `accessToken, markers?, mapStyle?, initialLongitude?, initialLatitude?, initialZoom?, height?, onMapLoad?, onMapClick?`
**Description**: A comprehensive, interactive map component built with react-map-gl and Mapbox GL JS. Provides automatic sizing, interactive markers with popups, multiple map styles, event handling, built-in navigation controls, and comprehensive error handling. Requires a Mapbox access token to function. Perfect for displaying supplier locations, store locators, delivery tracking, analytics dashboards, and any geographic data visualization.
**Required**: Mapbox access token via `MAPBOX_KEY` environment variable

### NumberInput

**Import**: `import { NumberInput } from '@glide/glide-ui/number-input';`
**Props**: `label?, description?, min?, max?, step?, ...Input props`
**Description**: A specialized numeric input component that extends the base Input component with number-specific features. Supports min/max values, step increments, and maintains all Input component features like labels, descriptions, hints, error states, and validation.

### Toast

**Import**: `import { Toaster, showToast, dismissToast, dismissAllToasts } from '@glide/glide-ui/toast';`
**Props**: Toaster: `position?, theme?, expand?, richColors?` | showToast: `title?, description?, icon?, variant?, actionButton?, dismissButton?`
**Description**: A powerful toast notification system built on Sonner with automatic theme integration and comprehensive accessibility support. Features two display variants (default and compact), interactive action buttons, flexible content support, and smart positioning. Requires `Toaster` component to be mounted in app root, then use `showToast` function for rich notifications with icons, descriptions, dismissal control, and full TypeScript support.

### Separator

**Import**: `import { Separator } from '@glide/glide-ui/separator';`
**Description**: A visual separator component for creating clear divisions between content sections. Built on Radix UI Separator primitive with full accessibility support, dual orientations (horizontal/vertical), and semantic/decorative modes. Perfect for dividing form sections, navigation menus, inline content, card layouts, and complex dashboard interfaces. Automatically adapts to light/dark themes and provides proper screen reader support when used semantically.

### Skeleton

**Import**: `import { Skeleton } from '@glide/glide-ui/skeleton';`
**Description**: A skeleton component that displays an animated placeholder while content is loading. Features built-in pulse animation, flexible sizing through Tailwind classes, and support for various shapes (circles, rectangles, custom). Perfect for loading states in cards, lists, data tables, avatars, and any content that needs progressive loading indication. Lightweight implementation with CSS-based animations and automatic theme adaptation.
**Documentation**: [Skeleton README](./skeleton/README.md)

### ScreenTitle

**Import**: `import { ScreenTitle } from '@glide/glide-ui/screen-title';`
**Props**: `variant, title, subtitle?, image?, coverImage?, size?, controls?, className?`
**Description**: **DO NOT use with FilterToolbar on the same page.** Use ScreenTitle for main page headers (e.g., "Dashboard", "User Profile"). For collection titles above data lists, use FilterToolbar instead. A versatile screen title component with four distinct styles (Simple, Image, Cover, Profile) for creating rich page headers with optional images, actions, and metadata. The `title` prop requires a string and gets proper h1 styling automatically. The optional `subtitle` prop should **only be used for dynamic content** on detail/item pages (e.g., user role on profile page, product specs on product page, team stats on team page) - do NOT use for static UI text or generic page descriptions. Generic pages like "Dashboard" or "Settings" should NOT have subtitles. When used, `subtitle` accepts either a string (gets default `text-subtle` styling) or ReactNode (for full styling control over dynamic metadata). Features responsive layouts that adapt between mobile and desktop, support for control actions, flexible image display options, and full accessibility. Perfect for user profiles, product details, team pages, and any detail screen that shows specific information about an item.

## Chrome Components (App Structure)

### AppShell, Nav, ScreenWrapper, TabBar

**Import**: `import { AppShell, Nav, ScreenWrapper, TabBar } from '@glide/glide-ui/chrome';`
**Props**: Nav: `title, items` | TabBar: `items` | ScreenWrapper: `className?` | AppShell: `children`
**Description**: Core chrome/structure components for the application shell:

- **AppShell**: Simple wrapper div for app chrome components. Used to contain Nav, ScreenWrapper, and TabBar components together.
- **ScreenWrapper**: Core wrapper container for app screens providing consistent layout with full viewport height, responsive padding, and maximum width constraints. Must be used as the main wrapper for all page content.
- **Nav**: Desktop navigation bar with sticky top positioning. Shows only on desktop (md and up) with title and navigation items. Uses wrapper approach for perfect alignment with Screen content.
- **TabBar**: Mobile bottom navigation bar with fixed positioning. Shows only on mobile with icon and label for each navigation item. Provides platform-appropriate navigation for touch devices.

## Component Guidelines

All components in this library follow these principles:

- **Accessibility First**: WCAG 2.1 AA compliant
- **Mobile Responsive**: Touch-friendly with mobile-first design
- **TypeScript**: Full type safety
- **Tailwind CSS**: Consistent styling with accent color system
- **Testing**: Comprehensive test coverage with Vitest
- **Icons**: Use `@glideapps/icons` stroke versions (starting with "ST") as primary choice, fallback to Lucide only when needed

For detailed development guidelines, see [COMPONENT_DEVELOPMENT_GUIDE.md](./COMPONENT_DEVELOPMENT_GUIDE.md)
