@neynar/ui 0.4.0 → 0.5.0

package/src/components/ui/command.tsx

@@ -1,6 +1,7 @@
+"use client";
+
 import * as React from "react";
-import { Command as CommandPrimitive, useCommandState } from "cmdk";
-import { SearchIcon } from "lucide-react";
+import { Command as CommandPrimitive } from "cmdk";
 
 import { cn } from "@/lib/utils";
 import {
@@ -10,306 +11,21 @@ import {
   DialogHeader,
   DialogTitle,
 } from "@/components/ui/dialog";
+import { InputGroup, InputGroupAddon } from "@/components/ui/input-group";
+import { SearchIcon, CheckIcon } from "lucide-react";
 
-// ============================================================================
-// 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
-// ============================================================================
+type CommandProps = React.ComponentProps<typeof CommandPrimitive>;
 
 /**
- * Command - A fast, composable command menu for search and navigation
- *
- * Built on the cmdk primitive, this component provides a powerful command palette
- * interface with search, filtering, and keyboard navigation. Perfect for creating
- * search interfaces, command palettes, and action menus with full accessibility support.
- *
- * 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 label="Main Menu">
- *   <CommandInput placeholder="Type a command or search..." />
- *   <CommandList>
- *     <CommandEmpty>No results found.</CommandEmpty>
- *     <CommandGroup heading="Suggestions">
- *       <CommandItem>Calendar</CommandItem>
- *       <CommandItem>Search Emoji</CommandItem>
- *       <CommandItem>Calculator</CommandItem>
- *     </CommandGroup>
- *   </CommandList>
- * </Command>
- * ```
- *
- * @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);
- *
- * useEffect(() => {
- *   const down = (e: KeyboardEvent) => {
- *     if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
- *       e.preventDefault();
- *       setOpen((open) => !open);
- *     }
- *   };
- *   document.addEventListener("keydown", down);
- *   return () => document.removeEventListener("keydown", down);
- * }, []);
- *
- * <CommandDialog open={open} onOpenChange={setOpen}>
- *   <CommandInput placeholder="Type a command..." />
- *   <CommandList>
- *     <CommandGroup heading="Actions">
- *       <CommandItem onSelect={() => console.log("New file")}>
- *         New File
- *         <CommandShortcut>⌘N</CommandShortcut>
- *       </CommandItem>
- *     </CommandGroup>
- *   </CommandList>
- * </CommandDialog>
- * ```
- *
- * @accessibility
- * - 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 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
+ * Root command menu container with keyboard navigation and fuzzy search.
+ * Typically used within CommandDialog for command palettes.
  */
-function Command({
-  className,
-  ...props
-}: React.ComponentProps<typeof CommandPrimitive>) {
+function Command({ className, ...props }: CommandProps) {
   return (
     <CommandPrimitive
       data-slot="command"
       className={cn(
-        "bg-popover text-popover-foreground flex h-full w-full flex-col overflow-hidden rounded-md",
+        "bg-popover text-popover-foreground rounded-xl! p-1 flex size-full flex-col overflow-hidden",
         className,
       )}
       {...props}
@@ -317,99 +33,32 @@ function Command({
   );
 }
 
+type CommandDialogProps = Omit<
+  React.ComponentProps<typeof Dialog>,
+  "children"
+> & {
+  /** Dialog title for screen readers. @default "Command Palette" */
+  title?: string;
+  /** Dialog description for screen readers. @default "Search for a command to run..." */
+  description?: string;
+  className?: string;
+  /** Show close button (X) in top-right corner. @default false */
+  showCloseButton?: boolean;
+  children: React.ReactNode;
+};
+
 /**
- * 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 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
- *
- * @example
- * ```tsx
- * // Command palette dialog with keyboard shortcut
- * const [open, setOpen] = useState(false);
- *
- * useEffect(() => {
- *   const down = (e: KeyboardEvent) => {
- *     if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
- *       e.preventDefault();
- *       setOpen((open) => !open);
- *     }
- *   };
- *   document.addEventListener("keydown", down);
- *   return () => document.removeEventListener("keydown", down);
- * }, []);
- *
- * <CommandDialog open={open} onOpenChange={setOpen}>
- *   <CommandInput placeholder="Type a command..." />
- *   <CommandList>
- *     <CommandGroup heading="Actions">
- *       <CommandItem>Create New File</CommandItem>
- *       <CommandItem>Open Settings</CommandItem>
- *     </CommandGroup>
- *   </CommandList>
- * </CommandDialog>
- * ```
- *
- * @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 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
+ * Command menu wrapped in a dialog for modal command palettes.
+ * Automatically includes portal and overlay. Triggered with ⌘K or Ctrl+K.
  */
 function CommandDialog({
   title = "Command Palette",
   description = "Search for a command to run...",
   children,
   className,
-  showCloseButton = true,
+  showCloseButton = false,
   ...props
-}: {
-  title?: string;
-  description?: string;
-  children?: React.ReactNode;
-  className?: string;
-  showCloseButton?: boolean;
-} & React.ComponentProps<typeof Dialog>) {
+}: CommandDialogProps) {
   return (
     <Dialog {...props}>
       <DialogHeader className="sr-only">
@@ -417,151 +66,51 @@ function CommandDialog({
         <DialogDescription>{description}</DialogDescription>
       </DialogHeader>
       <DialogContent
-        className={cn("overflow-hidden p-0", className)}
+        className={cn("rounded-xl! 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">
-          {children}
-        </Command>
+        {children}
       </DialogContent>
     </Dialog>
   );
 }
 
+type CommandInputProps = React.ComponentProps<typeof CommandPrimitive.Input>;
+
 /**
- * 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 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
- *
- * @example
- * ```tsx
- * // Basic uncontrolled input
- * <Command>
- *   <CommandInput placeholder="Search commands..." />
- *   <CommandList>...</CommandList>
- * </Command>
- * ```
- *
- * @example
- * ```tsx
- * // Controlled input with external state
- * const [search, setSearch] = useState('');
- *
- * <CommandInput
- *   value={search}
- *   onValueChange={setSearch}
- *   placeholder="Type a command or search..."
- *   autoFocus
- * />
- * ```
- *
- * @example
- * ```tsx
- * // With disabled state
- * <CommandInput
- *   placeholder="Loading..."
- *   disabled={isLoading}
- * />
- * ```
- *
- * @accessibility
- * - 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
+ * Search input with integrated search icon. Automatically filters command items.
  */
-function CommandInput({
-  className,
-  ...props
-}: React.ComponentProps<typeof CommandPrimitive.Input>) {
+function CommandInput({ className, ...props }: CommandInputProps) {
   return (
-    <div
-      data-slot="command-input-wrapper"
-      className="flex h-9 items-center gap-2 border-b px-3"
-    >
-      <SearchIcon className="size-4 shrink-0 opacity-50" />
-      <CommandPrimitive.Input
-        data-slot="command-input"
-        className={cn(
-          "placeholder:text-muted-foreground flex h-10 w-full rounded-md bg-transparent py-3 text-sm outline-hidden disabled:cursor-not-allowed disabled:opacity-50",
-          className,
-        )}
-        {...props}
-      />
+    <div data-slot="command-input-wrapper" className="p-1 pb-0">
+      <InputGroup className="bg-input/30 border-input/30 h-8! rounded-lg! shadow-none! *:data-[slot=input-group-addon]:pl-2!">
+        <CommandPrimitive.Input
+          data-slot="command-input"
+          className={cn(
+            "w-full text-sm outline-hidden disabled:cursor-not-allowed disabled:opacity-50",
+            className,
+          )}
+          {...props}
+        />
+        <InputGroupAddon>
+          <SearchIcon className="size-4 shrink-0 opacity-50" />
+        </InputGroupAddon>
+      </InputGroup>
     </div>
   );
 }
 
+type CommandListProps = React.ComponentProps<typeof CommandPrimitive.List>;
+
 /**
- * CommandList - Scrollable container for command items
- *
- * 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
- *
- * @example
- * ```tsx
- * <CommandList>
- *   <CommandEmpty>No results found</CommandEmpty>
- *   <CommandGroup heading="Actions">
- *     <CommandItem>New File</CommandItem>
- *     <CommandItem>Open File</CommandItem>
- *   </CommandGroup>
- * </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 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
+ * Scrollable container for command groups and items. Max height 72 (18rem).
  */
-function CommandList({
-  className,
-  ...props
-}: React.ComponentProps<typeof CommandPrimitive.List>) {
+function CommandList({ className, ...props }: CommandListProps) {
   return (
     <CommandPrimitive.List
       data-slot="command-list"
       className={cn(
-        "max-h-[300px] scroll-py-1 overflow-x-hidden overflow-y-auto",
+        "no-scrollbar max-h-72 scroll-py-1 outline-none overflow-x-hidden overflow-y-auto",
         className,
       )}
       {...props}
@@ -569,136 +118,27 @@ function CommandList({
   );
 }
 
+type CommandEmptyProps = React.ComponentProps<typeof CommandPrimitive.Empty>;
+
 /**
- * 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. 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
- *
- * @example
- * ```tsx
- * <CommandList>
- *   <CommandEmpty>No commands found.</CommandEmpty>
- * </CommandList>
- * ```
- *
- * @example
- * ```tsx
- * // Custom empty state with icon and helpful text
- * <CommandEmpty>
- *   <div className="py-6 text-center">
- *     <SearchIcon className="mx-auto h-10 w-10 text-muted-foreground/50" />
- *     <h3 className="mt-2 text-sm font-medium">No results found</h3>
- *     <p className="mt-1 text-sm text-muted-foreground">
- *       Try adjusting your search terms.
- *     </p>
- *   </div>
- * </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 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
+ * Displayed when search returns no results. Defaults to centered text.
  */
-function CommandEmpty({
-  ...props
-}: React.ComponentProps<typeof CommandPrimitive.Empty>) {
+function CommandEmpty({ className, ...props }: CommandEmptyProps) {
   return (
     <CommandPrimitive.Empty
       data-slot="command-empty"
-      className="py-6 text-center text-sm"
+      className={cn("py-6 text-center text-sm", className)}
       {...props}
     />
   );
 }
 
+type CommandGroupProps = React.ComponentProps<typeof CommandPrimitive.Group>;
+
 /**
- * CommandGroup - Groups related command items under a heading
- *
- * 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
- *
- * @example
- * ```tsx
- * <CommandGroup heading="Recent Files">
- *   <CommandItem>document.pdf</CommandItem>
- *   <CommandItem>presentation.pptx</CommandItem>
- * </CommandGroup>
- * <CommandGroup heading="Actions">
- *   <CommandItem>New File</CommandItem>
- *   <CommandItem>Open File</CommandItem>
- * </CommandGroup>
- * ```
- *
- * @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 with proper ARIA roles
- * - Maintains keyboard navigation flow between groups
- * - Groups are properly labeled for assistive technology
- *
- * @since 1.0.0
+ * Groups related command items with optional heading. Use heading prop for labels.
  */
-function CommandGroup({
-  className,
-  ...props
-}: React.ComponentProps<typeof CommandPrimitive.Group>) {
+function CommandGroup({ className, ...props }: CommandGroupProps) {
   return (
     <CommandPrimitive.Group
       data-slot="command-group"
@@ -711,199 +151,57 @@ function CommandGroup({
   );
 }
 
+type CommandSeparatorProps = React.ComponentProps<
+  typeof CommandPrimitive.Separator
+>;
+
 /**
- * CommandSeparator - Visual separator between command groups
- *
- * Provides visual separation between different sections of commands.
- * 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
- *
- * @example
- * ```tsx
- * <CommandGroup heading="Recent">...</CommandGroup>
- * <CommandSeparator />
- * <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 with aria-hidden
- * - Does not interfere with keyboard navigation
- * - No focusable content or semantic meaning
- *
- * @since 1.0.0
+ * Visual divider between command groups or items.
  */
-function CommandSeparator({
-  className,
-  ...props
-}: React.ComponentProps<typeof CommandPrimitive.Separator>) {
+function CommandSeparator({ className, ...props }: CommandSeparatorProps) {
   return (
     <CommandPrimitive.Separator
       data-slot="command-separator"
-      className={cn("bg-border -mx-1 h-px", className)}
+      className={cn("bg-border -mx-1 h-px w-auto", className)}
       {...props}
     />
   );
 }
 
+type CommandItemProps = React.ComponentProps<typeof CommandPrimitive.Item>;
+
 /**
- * CommandItem - Individual selectable command item
- *
- * 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
- *
- * @example
- * ```tsx
- * // Basic command item
- * <CommandItem onSelect={() => console.log("File opened")}>
- *   Open File
- * </CommandItem>
- * ```
- *
- * @example
- * ```tsx
- * // Command item with icon and shortcut
- * <CommandItem value="new-document" onSelect={handleCreateDocument}>
- *   <FileIcon className="mr-2 h-4 w-4" />
- *   New Document
- *   <CommandShortcut>⌘N</CommandShortcut>
- * </CommandItem>
- * ```
- *
- * @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 with proper contrast
- * - Supports disabled state with proper ARIA attributes
- * - Screen reader announces item content, state, and shortcuts
- * - Maintains focus within list boundaries
- *
- * @since 1.0.0
+ * Selectable command item with automatic check icon. Use onSelect prop for actions.
+ * Automatically shows check icon when selected (hidden if CommandShortcut is present).
  */
-function CommandItem({
-  className,
-  ...props
-}: React.ComponentProps<typeof CommandPrimitive.Item>) {
+function CommandItem({ className, children, ...props }: CommandItemProps) {
   return (
     <CommandPrimitive.Item
       data-slot="command-item"
       className={cn(
-        "data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "data-selected:bg-muted data-selected:text-foreground data-selected:**:[svg]:text-foreground relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none [&_svg:not([class*='size-'])]:size-4 [[data-slot=dialog-content]_&]:rounded-lg! group/command-item data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0",
         className,
       )}
       {...props}
-    />
+    >
+      {children}
+      <CheckIcon className="ml-auto opacity-0 group-has-[[data-slot=command-shortcut]]/command-item:hidden group-data-[checked=true]/command-item:opacity-100" />
+    </CommandPrimitive.Item>
   );
 }
 
+type CommandShortcutProps = React.ComponentProps<"span">;
+
 /**
- * CommandShortcut - Displays keyboard shortcut for command items
- *
- * 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
- *
- * @example
- * ```tsx
- * <CommandItem>
- *   Save File
- *   <CommandShortcut>⌘S</CommandShortcut>
- * </CommandItem>
- * ```
- *
- * @example
- * ```tsx
- * // Multi-key shortcuts
- * <CommandItem>
- *   Redo
- *   <CommandShortcut>⇧⌘Z</CommandShortcut>
- * </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 and labeling
- * - Maintains readability with appropriate contrast
- *
- * @since 1.0.0
+ * Keyboard shortcut label displayed at the end of a command item.
+ * Automatically aligned to the right and hides the check icon.
  */
-function CommandShortcut({
-  className,
-  ...props
-}: React.ComponentProps<"span">) {
+function CommandShortcut({ className, ...props }: CommandShortcutProps) {
   return (
     <span
       data-slot="command-shortcut"
       className={cn(
-        "text-muted-foreground ml-auto text-xs tracking-widest",
+        "text-muted-foreground group-data-selected/command-item:text-foreground ml-auto text-xs tracking-widest",
         className,
       )}
       {...props}
@@ -911,58 +209,6 @@ 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,
@@ -973,6 +219,13 @@ export {
   CommandItem,
   CommandShortcut,
   CommandSeparator,
-  CommandLoading,
-  useCommandState,
+  type CommandProps,
+  type CommandDialogProps,
+  type CommandInputProps,
+  type CommandListProps,
+  type CommandEmptyProps,
+  type CommandGroupProps,
+  type CommandItemProps,
+  type CommandShortcutProps,
+  type CommandSeparatorProps,
 };