@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/command.tsx

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { Command as CommandPrimitive } from "cmdk";
+import { Command as CommandPrimitive, useCommandState } from "cmdk";
 import { SearchIcon } from "lucide-react";
 
 import { cn } from "@/lib/utils";
@@ -11,6 +11,186 @@ import {
   DialogTitle,
 } from "@/components/ui/dialog";
 
+// ============================================================================
+// CMDK HOOK EXPORTS
+// ============================================================================
+
+// useCommandState is now imported directly from 'cmdk' and available for use
+
+// ============================================================================
+// DOCUMENTATION-ONLY PROP TYPES (Internal - not exported)
+// ============================================================================
+
+/**
+ * Props for Command component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace CMDK inferred types
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type CommandDocsProps = {
+  /** Accessibility label for the command menu - helps identify the menu purpose for screen readers */
+  label?: string;
+  /** Whether to filter and sort items automatically based on search input @default true */
+  shouldFilter?: boolean;
+  /** Custom filter function for ranking items based on search relevance - return 0 to hide, 1+ to show and rank */
+  filter?: (value: string, search: string, keywords?: string[]) => number;
+  /** Current selected item value for controlled usage - useful for managing selection state externally */
+  value?: string;
+  /** Callback fired when the selected item changes - receives the new selected value */
+  onValueChange?: (value: string) => void;
+  /** Whether to enable circular navigation with arrow keys through all items @default false */
+  loop?: boolean;
+  /** Whether to disable mouse/pointer selection and only allow keyboard navigation @default true */
+  disablePointerSelection?: boolean;
+  /** Whether to enable Vim-style keybindings for navigation (j/k for up/down) @default false */
+  vimBindings?: boolean;
+  /** Additional CSS classes for styling customization */
+  className?: string;
+  /** Child components - typically CommandInput, CommandList with CommandItems */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for CommandDialog component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Dialog + Command inferred types
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type CommandDialogDocsProps = {
+  /** Whether the dialog is open - controls visibility state */
+  open?: boolean;
+  /** Callback when dialog open state changes - useful for managing dialog state */
+  onOpenChange?: (open: boolean) => void;
+  /** The title announced to screen readers for accessibility @default "Command Palette" */
+  title?: string;
+  /** The description announced to screen readers explaining dialog purpose @default "Search for a command to run..." */
+  description?: string;
+  /** Whether to show the X close button in the dialog header @default true */
+  showCloseButton?: boolean;
+  /** Portal container element for rendering the dialog - allows custom positioning */
+  container?: HTMLElement | null;
+  /** Additional CSS classes for dialog content styling */
+  className?: string;
+  /** Child components - typically Command with CommandInput and CommandList */
+  children?: React.ReactNode;
+};
+
+/**
+ * Props for CommandInput component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace CMDK inferred types
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type CommandInputDocsProps = {
+  /** Current search input value for controlled input behavior */
+  value?: string;
+  /** Callback fired when input value changes during typing - receives the new search string */
+  onValueChange?: (search: string) => void;
+  /** Placeholder text displayed when input is empty - helps users understand purpose */
+  placeholder?: string;
+  /** Whether the input is disabled and cannot receive focus @default false */
+  disabled?: boolean;
+  /** Whether to automatically focus the input when rendered @default false */
+  autoFocus?: boolean;
+  /** Additional CSS classes for input styling */
+  className?: string;
+} & Omit<React.InputHTMLAttributes<HTMLInputElement>, "value" | "onChange">;
+
+/**
+ * Props for CommandList component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace CMDK inferred types
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type CommandListDocsProps = {
+  /** Additional CSS classes for list container styling - useful for height and scroll behavior */
+  className?: string;
+  /** Child components - typically CommandEmpty, CommandGroup, and CommandItem components */
+  children?: React.ReactNode;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "role">;
+
+/**
+ * Props for CommandEmpty component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace CMDK inferred types
+ */
+type CommandEmptyDocsProps = {
+  /** Additional CSS classes for empty state styling */
+  className?: string;
+  /** Content to display when no items match the search - can be text or custom components */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for CommandGroup component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace CMDK inferred types
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type CommandGroupDocsProps = {
+  /** The group heading displayed above items - can be text or a React component */
+  heading?: React.ReactNode;
+  /** Group value identifier for programmatic control and filtering */
+  value?: string;
+  /** Whether to always render the group even when all items are filtered out @default false */
+  forceMount?: boolean;
+  /** Additional CSS classes for group styling */
+  className?: string;
+  /** Child components - typically CommandItem components */
+  children?: React.ReactNode;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "role">;
+
+/**
+ * Props for CommandSeparator component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace CMDK inferred types
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type CommandSeparatorDocsProps = {
+  /** Whether to always render the separator regardless of surrounding content visibility @default false */
+  alwaysRender?: boolean;
+  /** Additional CSS classes for separator styling */
+  className?: string;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for CommandItem component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace CMDK inferred types
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type CommandItemDocsProps = {
+  /** Unique item value used for filtering and selection - defaults to text content if not provided */
+  value?: string;
+  /** Additional keywords for improved search matching without affecting display */
+  keywords?: string[];
+  /** Whether the item is disabled and cannot be selected @default false */
+  disabled?: boolean;
+  /** Callback fired when item is selected via Enter key or mouse click - receives the item value */
+  onSelect?: (value: string) => void;
+  /** Whether to always render the item even when it doesn't match the search filter @default false */
+  forceMount?: boolean;
+  /** Additional CSS classes for item styling */
+  className?: string;
+  /** Child content - typically text, icons, and CommandShortcut components */
+  children?: React.ReactNode;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "onSelect">;
+
+/**
+ * Props for CommandShortcut component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace standard span props
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type CommandShortcutDocsProps = {
+  /** Additional CSS classes for shortcut styling */
+  className?: string;
+  /** Keyboard shortcut text content - typically key combinations like "⌘K" or "Ctrl+N" */
+  children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLSpanElement>;
+
+/**
+ * Props for CommandLoading component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and extend CommandEmpty props
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type CommandLoadingDocsProps = CommandEmptyDocsProps;
+
+// ============================================================================
+// COMPONENTS
+// ============================================================================
+
 /**
  * Command - A fast, composable command menu for search and navigation
  *
@@ -18,11 +198,23 @@ import {
  * interface with search, filtering, and keyboard navigation. Perfect for creating
  * search interfaces, command palettes, and action menus with full accessibility support.
  *
- * @component
+ * Features advanced filtering with fuzzy search, keyboard shortcuts, nested navigation,
+ * asynchronous loading states, and comprehensive accessibility patterns.
+ *
+ * @param label - Accessibility label for screen readers and assistive technology
+ * @param shouldFilter - Controls automatic filtering and sorting @default true
+ * @param filter - Custom filter function for ranking items based on search
+ * @param value - Currently selected item value for controlled usage
+ * @param onValueChange - Callback fired when selected item changes
+ * @param loop - Enables circular navigation through items @default false
+ * @param disablePointerSelection - Prevents mouse selection behavior @default true
+ * @param vimBindings - Enables Vim-style navigation keybindings @default false
+ * @param className - Additional CSS classes
+ *
  * @example
  * ```tsx
  * // Basic command menu
- * <Command>
+ * <Command label="Main Menu">
  *   <CommandInput placeholder="Type a command or search..." />
  *   <CommandList>
  *     <CommandEmpty>No results found.</CommandEmpty>
@@ -37,6 +229,34 @@ import {
  *
  * @example
  * ```tsx
+ * // Controlled command menu with custom filtering
+ * const [value, setValue] = useState('');
+ * const [search, setSearch] = useState('');
+ *
+ * <Command
+ *   value={value}
+ *   onValueChange={setValue}
+ *   filter={(value, search, keywords) => {
+ *     const extended = value + ' ' + (keywords?.join(' ') || '');
+ *     return extended.toLowerCase().includes(search.toLowerCase()) ? 1 : 0;
+ *   }}
+ *   loop
+ * >
+ *   <CommandInput
+ *     value={search}
+ *     onValueChange={setSearch}
+ *     placeholder="Search..."
+ *   />
+ *   <CommandList>
+ *     <CommandItem value="apple" keywords={['fruit', 'red']}>
+ *       Apple
+ *     </CommandItem>
+ *   </CommandList>
+ * </Command>
+ * ```
+ *
+ * @example
+ * ```tsx
  * // Command dialog with keyboard shortcut
  * const [open, setOpen] = useState(false);
  *
@@ -65,17 +285,20 @@ import {
  * ```
  *
  * @accessibility
- * - Full keyboard navigation with arrow keys and Home/End
- * - Type-ahead search and filtering
+ * - Full keyboard navigation with Arrow keys, Home/End, Page Up/Down
+ * - Type-ahead search with live region announcements
  * - Enter key to select items, Escape to close dialogs
- * - Screen reader announcements for filtered results
- * - ARIA roles following command palette pattern
- * - Focus management and trapping in dialog mode
+ * - Screen reader announcements for filtered results and state changes
+ * - ARIA roles following WAI-ARIA command palette patterns
+ * - Focus management with proper tab trapping in dialog mode
+ * - Support for disabled items and groups
  *
+ * @see {@link https://cmdk.paco.me} Official CMDK documentation
  * @see {@link https://ui.shadcn.com/docs/components/command} for design patterns
  * @see {@link CommandDialog} - For modal command palette
  * @see {@link CommandInput} - Search input component
  * @see {@link CommandList} - Scrollable results container
+ * @see {@link useCommandState} - Hook for accessing command state
  * @since 1.0.0
  */
 function Command({
@@ -98,10 +321,20 @@ function Command({
  * CommandDialog - Modal dialog wrapper for command menu
  *
  * Presents the command menu in a modal dialog overlay, perfect for application-wide
- * command palettes triggered by keyboard shortcuts like Cmd+K. Includes proper
- * focus management and accessibility features.
+ * command palettes triggered by keyboard shortcuts like Cmd+K or Ctrl+K. Built on
+ * Radix UI Dialog with proper focus management, portal rendering, and accessibility.
+ *
+ * The dialog automatically handles focus trapping, scroll locking, and provides
+ * screen reader announcements. Use `container` prop to specify custom portal target.
+ *
+ * @param open - Controls dialog visibility state
+ * @param onOpenChange - Callback when dialog open state changes
+ * @param title - Screen reader accessible title @default "Command Palette"
+ * @param description - Screen reader description @default "Search for a command to run..."
+ * @param showCloseButton - Whether to show the X close button @default true
+ * @param container - Custom portal container element for rendering
+ * @param className - Additional CSS classes for dialog content
  *
- * @component
  * @example
  * ```tsx
  * // Command palette dialog with keyboard shortcut
@@ -129,16 +362,38 @@ function Command({
  * </CommandDialog>
  * ```
  *
- * @param title - Screen reader title for the dialog
- * @param description - Screen reader description for the dialog
- * @param showCloseButton - Whether to show the close button
+ * @example
+ * ```tsx
+ * // Custom portal container
+ * const containerRef = useRef<HTMLDivElement>(null);
+ *
+ * <>
+ *   <CommandDialog
+ *     open={open}
+ *     onOpenChange={setOpen}
+ *     container={containerRef.current}
+ *     title="Quick Actions"
+ *     description="Find and run commands quickly"
+ *   >
+ *     <CommandInput />
+ *     <CommandList>
+ *       <CommandItem>Action 1</CommandItem>
+ *     </CommandList>
+ *   </CommandDialog>
+ *   <div ref={containerRef} />
+ * </>
+ * ```
  *
  * @accessibility
- * - Focus trapped within dialog when open
+ * - Focus trapped within dialog when open with proper restoration
  * - Escape key closes the dialog
+ * - Click outside or close button dismisses dialog
  * - Screen reader announcements with title and description
  * - Preserves all command menu keyboard navigation
+ * - Modal backdrop prevents interaction with background content
  *
+ * @see {@link Dialog} - Base dialog component
+ * @see {@link Command} - Command menu component
  * @since 1.0.0
  */
 function CommandDialog({
@@ -148,27 +403,13 @@ function CommandDialog({
   className,
   showCloseButton = true,
   ...props
-}: React.ComponentProps<typeof Dialog> & {
-  /**
-   * The title for screen readers
-   * @default "Command Palette"
-   */
+}: {
   title?: string;
-  /**
-   * The description for screen readers
-   * @default "Search for a command to run..."
-   */
   description?: string;
-  /**
-   * Additional CSS classes
-   */
+  children?: React.ReactNode;
   className?: string;
-  /**
-   * Whether to show the close button
-   * @default true
-   */
   showCloseButton?: boolean;
-}) {
+} & React.ComponentProps<typeof Dialog>) {
   return (
     <Dialog {...props}>
       <DialogHeader className="sr-only">
@@ -179,7 +420,7 @@ function CommandDialog({
         className={cn("overflow-hidden p-0", className)}
         showCloseButton={showCloseButton}
       >
-        <Command className="[&_[cmdk-group-heading]]:text-muted-foreground **:data-[slot=command-input-wrapper]:h-12 [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group]]:px-2 [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5">
+        <Command className="[&_[cmdk-group-heading]]:text-muted-foreground [&_[data-slot=command-input-wrapper]]:h-12 [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group]]:px-2 [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5">
           {children}
         </Command>
       </DialogContent>
@@ -191,11 +432,23 @@ function CommandDialog({
  * CommandInput - Search input for command menu filtering
  *
  * Provides a search input with search icon for filtering command menu items.
- * Automatically filters items as the user types and handles focus management.
+ * Automatically filters items as the user types and triggers live region announcements
+ * for screen readers. Supports both controlled and uncontrolled usage patterns.
+ *
+ * The input integrates with the Command context to provide real-time filtering,
+ * search highlighting, and result announcements. Includes built-in search icon
+ * and proper focus management.
+ *
+ * @param value - Controlled input value for managing search state externally
+ * @param onValueChange - Callback fired when input value changes
+ * @param placeholder - Placeholder text displayed when input is empty
+ * @param disabled - Disables the input and prevents interaction @default false
+ * @param autoFocus - Auto-focus the input when rendered @default false
+ * @param className - Additional CSS classes
  *
- * @component
  * @example
  * ```tsx
+ * // Basic uncontrolled input
  * <Command>
  *   <CommandInput placeholder="Search commands..." />
  *   <CommandList>...</CommandList>
@@ -204,18 +457,32 @@ function CommandDialog({
  *
  * @example
  * ```tsx
- * // Controlled input with state
+ * // Controlled input with external state
+ * const [search, setSearch] = useState('');
+ *
  * <CommandInput
+ *   value={search}
+ *   onValueChange={setSearch}
  *   placeholder="Type a command or search..."
- *   value={searchValue}
- *   onValueChange={setSearchValue}
+ *   autoFocus
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With disabled state
+ * <CommandInput
+ *   placeholder="Loading..."
+ *   disabled={isLoading}
  * />
  * ```
  *
  * @accessibility
- * - Auto-focuses when command menu opens
- * - Live region announces result count to screen readers
+ * - Auto-focuses when command menu opens (if autoFocus is true)
+ * - Live region announces result count changes to screen readers
  * - Supports all standard input accessibility features
+ * - Proper labeling and description associations
+ * - Keyboard navigation integration with command list
  *
  * @since 1.0.0
  */
@@ -244,10 +511,15 @@ function CommandInput({
 /**
  * CommandList - Scrollable container for command items
  *
- * Contains and manages the list of command items with automatic scrolling
- * and overflow handling. Manages keyboard navigation and selection state.
+ * Contains and manages the list of command items with automatic scrolling,
+ * overflow handling, and dynamic height calculation. Provides the scrollable
+ * viewport for command items and groups with proper keyboard navigation.
+ *
+ * Uses CSS custom property `--cmdk-list-height` for smooth height transitions
+ * when items are filtered. Supports scroll padding for better item visibility.
+ *
+ * @param className - Additional CSS classes
  *
- * @component
  * @example
  * ```tsx
  * <CommandList>
@@ -259,10 +531,25 @@ function CommandInput({
  * </CommandList>
  * ```
  *
+ * @example
+ * ```tsx
+ * // With custom height and scroll behavior
+ * <CommandList className="max-h-[400px] scroll-py-2">
+ *   {items.map((item) => (
+ *     <CommandItem key={item.id} value={item.id}>
+ *       {item.name}
+ *     </CommandItem>
+ *   ))}
+ * </CommandList>
+ * ```
+ *
  * @accessibility
  * - Scrollable with keyboard arrow navigation
  * - Maintains focus within list boundaries
- * - Supports Home/End key navigation
+ * - Supports Home/End key navigation to first/last items
+ * - Page Up/Page Down for faster scrolling
+ * - Proper ARIA role as listbox
+ * - Screen reader announcements for list changes
  *
  * @since 1.0.0
  */
@@ -286,9 +573,14 @@ function CommandList({
  * CommandEmpty - Empty state message for command menu
  *
  * Displays when no command items match the current search query.
- * Can contain custom content beyond simple text messages.
+ * Can contain custom content beyond simple text messages. Automatically
+ * shows/hides based on filtered results and announces changes to screen readers.
+ *
+ * Supports dynamic content using the `useCommandState` hook to access current
+ * search term and create contextual empty messages.
+ *
+ * @param className - Additional CSS classes
  *
- * @component
  * @example
  * ```tsx
  * <CommandList>
@@ -310,10 +602,26 @@ function CommandList({
  * </CommandEmpty>
  * ```
  *
+ * @example
+ * ```tsx
+ * // Dynamic empty message with search term
+ * function DynamicEmpty() {
+ *   const search = useCommandState((state) => state.search);
+ *   return (
+ *     <CommandEmpty>
+ *       {search ? `No results found for "${search}".` : 'Start typing to search...'}
+ *     </CommandEmpty>
+ *   );
+ * }
+ * ```
+ *
  * @accessibility
  * - Announced to screen readers when no results are found
- * - Content is properly focusable if interactive
+ * - Content is properly focusable if interactive elements are included
+ * - Live region updates when search state changes
+ * - Proper semantic markup for empty state content
  *
+ * @see {@link useCommandState} - Hook for accessing search state
  * @since 1.0.0
  */
 function CommandEmpty({
@@ -331,10 +639,18 @@ function CommandEmpty({
 /**
  * CommandGroup - Groups related command items under a heading
  *
- * Organizes command items into labeled sections for better organization
- * and navigation. Groups provide semantic structure for screen readers.
+ * Organizes command items into labeled sections with optional headings for better
+ * organization and navigation. Groups provide semantic structure for screen readers
+ * and can be hidden/shown based on whether they contain matching items.
+ *
+ * Groups automatically manage their visibility - if all contained items are filtered
+ * out, the entire group is hidden. Use `forceMount` to override this behavior.
+ *
+ * @param heading - The group heading text or component displayed above items
+ * @param value - Group identifier for programmatic control
+ * @param forceMount - Whether to always render the group even when hidden @default false
+ * @param className - Additional CSS classes
  *
- * @component
  * @example
  * ```tsx
  * <CommandGroup heading="Recent Files">
@@ -347,12 +663,35 @@ function CommandEmpty({
  * </CommandGroup>
  * ```
  *
- * @param heading - The group heading text displayed above items
+ * @example
+ * ```tsx
+ * // Group with custom heading component
+ * <CommandGroup
+ *   heading={
+ *     <div className="flex items-center gap-2">
+ *       <FolderIcon className="h-4 w-4" />
+ *       <span>Projects</span>
+ *     </div>
+ *   }
+ * >
+ *   <CommandItem>Project A</CommandItem>
+ *   <CommandItem>Project B</CommandItem>
+ * </CommandGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Group that always shows even when filtered
+ * <CommandGroup heading="Important" forceMount>
+ *   <CommandItem>Critical Action</CommandItem>
+ * </CommandGroup>
+ * ```
  *
  * @accessibility
  * - Group headings are announced to screen readers
- * - Provides semantic grouping for better navigation
+ * - Provides semantic grouping with proper ARIA roles
  * - Maintains keyboard navigation flow between groups
+ * - Groups are properly labeled for assistive technology
  *
  * @since 1.0.0
  */
@@ -376,9 +715,15 @@ function CommandGroup({
  * CommandSeparator - Visual separator between command groups
  *
  * Provides visual separation between different sections of commands.
- * Purely decorative element that improves visual organization.
+ * Purely decorative element that improves visual organization and hierarchy.
+ * Automatically hides when adjacent groups are filtered out.
+ *
+ * The separator will only render when it has visible content before and after it,
+ * unless `alwaysRender` is true.
+ *
+ * @param alwaysRender - Whether to always show separator regardless of context @default false
+ * @param className - Additional CSS classes
  *
- * @component
  * @example
  * ```tsx
  * <CommandGroup heading="Recent">...</CommandGroup>
@@ -386,9 +731,18 @@ function CommandGroup({
  * <CommandGroup heading="Actions">...</CommandGroup>
  * ```
  *
+ * @example
+ * ```tsx
+ * // Separator that always renders
+ * <CommandGroup heading="Primary">...</CommandGroup>
+ * <CommandSeparator alwaysRender />
+ * <CommandGroup heading="Secondary">...</CommandGroup>
+ * ```
+ *
  * @accessibility
- * - Decorative element, properly hidden from screen readers
+ * - Decorative element, properly hidden from screen readers with aria-hidden
  * - Does not interfere with keyboard navigation
+ * - No focusable content or semantic meaning
  *
  * @since 1.0.0
  */
@@ -408,10 +762,20 @@ function CommandSeparator({
 /**
  * CommandItem - Individual selectable command item
  *
- * Represents a single command or action that can be selected via
- * keyboard or mouse interaction. Supports icons, text, and shortcuts.
+ * Represents a single command or action that can be selected via keyboard or mouse
+ * interaction. Supports icons, text, shortcuts, and advanced filtering with keywords.
+ * Items can be disabled, have custom values for filtering, and trigger callbacks on selection.
+ *
+ * The item's value is used for filtering - if not provided, it defaults to the text content.
+ * Keywords can be added to improve search matching without affecting the display.
+ *
+ * @param value - Unique identifier for filtering and selection (defaults to text content)
+ * @param keywords - Additional search terms for improved filtering
+ * @param disabled - Disables interaction and selection @default false
+ * @param onSelect - Callback fired when item is selected with Enter or click
+ * @param forceMount - Always render even when filtered out @default false
+ * @param className - Additional CSS classes
  *
- * @component
  * @example
  * ```tsx
  * // Basic command item
@@ -430,15 +794,33 @@ function CommandSeparator({
  * </CommandItem>
  * ```
  *
- * @param value - Unique identifier for the item (used for filtering)
- * @param onSelect - Callback when item is selected
- * @param disabled - Whether the item is disabled
+ * @example
+ * ```tsx
+ * // Item with keywords for better search
+ * <CommandItem
+ *   value="apple"
+ *   keywords={['fruit', 'red', 'healthy']}
+ *   onSelect={() => selectFruit('apple')}
+ * >
+ *   🍎 Apple
+ * </CommandItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled item that shows but cannot be selected
+ * <CommandItem disabled>
+ *   <LockIcon className="mr-2 h-4 w-4" />
+ *   Premium Feature
+ * </CommandItem>
+ * ```
  *
  * @accessibility
  * - Keyboard selectable with Enter key and arrow navigation
- * - Visual highlight on focus and hover states
+ * - Visual highlight on focus and hover states with proper contrast
  * - Supports disabled state with proper ARIA attributes
- * - Screen reader announces item content and state
+ * - Screen reader announces item content, state, and shortcuts
+ * - Maintains focus within list boundaries
  *
  * @since 1.0.0
  */
@@ -461,10 +843,15 @@ function CommandItem({
 /**
  * CommandShortcut - Displays keyboard shortcut for command items
  *
- * Shows the keyboard shortcut associated with a command item,
- * typically displayed on the right side. Supports platform-specific shortcuts.
+ * Shows the keyboard shortcut associated with a command item, typically displayed
+ * on the right side with proper spacing. Supports platform-specific shortcuts and
+ * complex key combinations with consistent formatting.
+ *
+ * The component uses monospace-style formatting with appropriate opacity and spacing
+ * to clearly indicate keyboard shortcuts without overwhelming the item content.
+ *
+ * @param className - Additional CSS classes
  *
- * @component
  * @example
  * ```tsx
  * <CommandItem>
@@ -482,10 +869,29 @@ function CommandItem({
  * </CommandItem>
  * ```
  *
+ * @example
+ * ```tsx
+ * // Platform-specific shortcuts
+ * <CommandItem>
+ *   Copy
+ *   <CommandShortcut>{isMac ? '⌘C' : 'Ctrl+C'}</CommandShortcut>
+ * </CommandItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Complex shortcuts with modifiers
+ * <CommandItem>
+ *   Open Command Palette
+ *   <CommandShortcut>⌘⇧P</CommandShortcut>
+ * </CommandItem>
+ * ```
+ *
  * @accessibility
  * - Semantically associated with its command item
  * - Announced to screen readers as part of item description
- * - Uses proper keyboard shortcut formatting
+ * - Uses proper keyboard shortcut formatting and labeling
+ * - Maintains readability with appropriate contrast
  *
  * @since 1.0.0
  */
@@ -505,6 +911,58 @@ function CommandShortcut({
   );
 }
 
+/**
+ * CommandLoading - Loading state indicator for command menu
+ *
+ * Displays a loading message while command items are being fetched asynchronously.
+ * Should be conditionally rendered based on loading state. Shares the same styling
+ * and behavior as CommandEmpty but indicates active loading rather than empty state.
+ *
+ * @param className - Additional CSS classes
+ *
+ * @example
+ * ```tsx
+ * const [loading, setLoading] = useState(false);
+ * const [items, setItems] = useState([]);
+ *
+ * <CommandList>
+ *   {loading && <CommandLoading>Fetching commands...</CommandLoading>}
+ *   {items.map(item => (
+ *     <CommandItem key={item.id} value={item.id}>
+ *       {item.name}
+ *     </CommandItem>
+ *   ))}
+ * </CommandList>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom loading indicator
+ * <CommandLoading>
+ *   <div className="flex items-center justify-center py-6">
+ *     <Spinner className="mr-2 h-4 w-4" />
+ *     <span>Loading commands...</span>
+ *   </div>
+ * </CommandLoading>
+ * ```
+ *
+ * @accessibility
+ * - Announced to screen readers as loading state
+ * - Uses appropriate ARIA live region for status updates
+ * - Provides context for users while waiting for results
+ *
+ * @since 1.0.0
+ */
+function CommandLoading({ ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="command-loading"
+      className="py-6 text-center text-sm"
+      {...props}
+    />
+  );
+}
+
 export {
   Command,
   CommandDialog,
@@ -515,4 +973,6 @@ export {
   CommandItem,
   CommandShortcut,
   CommandSeparator,
+  CommandLoading,
+  useCommandState,
 };