@usefragments/ui 1.6.0 → 1.7.0

package/src/components/Combobox/Combobox.contract.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Combobox",
-  "description": "Searchable select input that filters a dropdown list of options as you type. Supports single and multiple selection with chips.",
-  "category": "forms",
+  "description": "Filters a list of options as the user types.",
+  "category": "inputs",
   "tags": ["combobox", "autocomplete", "search", "select", "typeahead", "form", "multiselect"],
   "status": "stable",
   "sourcePath": "src/components/Combobox/index.tsx",
@@ -133,86 +133,85 @@
   },
   "usage": {
     "when": [
-      "Users need to search/filter through many options",
-      "Large option lists where scrolling is impractical",
-      "When users might know what they are looking for",
-      "Autocomplete or typeahead functionality",
-      "Multiple selections from a searchable list"
+      "Lists too long to scan by eye",
+      "The user roughly knows the value they want",
+      "Autocomplete or typeahead",
+      "Multi-select from a searchable list"
     ],
     "whenNot": [
-      "Few options (under 5) - use Select or RadioGroup",
-      "Free-form text with no predefined options - use Input",
-      "Non-searchable single selection - use Select",
-      "Actions, not selection - use Menu"
+      "Under five options (use Select or RadioGroup)",
+      "Free-form text with no known options (use Input)",
+      "Short list nobody needs to search (use Select)",
+      "Actions rather than values (use Menu)"
     ],
     "guidelines": [
-      "Include a placeholder that explains what to search for",
-      "Use label prop for accessible field labeling",
-      "Use helperText for guidance and error for validation messages",
-      "Provide an empty state message when no results match",
-      "Group related options with Combobox.Group for large lists",
-      "Static items may be composed through fragments and groups; filtering preserves wrapper composition",
-      "Keep option text concise and searchable",
-      "Use multiple prop for multi-select with chip display"
+      "Placeholder names what is searchable",
+      "Set label so the field is announced",
+      "helperText for guidance, error for the failure reason",
+      "Override the built-in \"No results found\" with Combobox.Empty when you have better wording",
+      "Group related options with Combobox.Group in long lists",
+      "Filtering keeps wrapper composition, so groups and fragments survive",
+      "Keep option text short and searchable",
+      "multiple turns selections into removable chips"
     ],
     "accessibility": [
-      "Full keyboard navigation support (arrow keys, enter, escape)",
-      "Type-ahead filtering within options",
-      "Proper ARIA combobox roles and attributes",
-      "Screen reader announcements for filtered results",
-      "Chip removal via keyboard in multi-select mode"
+      "Arrow keys, Enter, and Escape all work",
+      "Typing filters the list in place",
+      "Correct ARIA combobox roles and attributes",
+      "Filtered result counts are announced",
+      "Chips can be removed from the keyboard"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Basic searchable select",
+      "description": "Type to narrow the list; unmatched queries show a no-results row.",
       "code": "<StatefulCombobox placeholder=\"Select a fruit\">\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Item value=\"apple\">Apple</Combobox.Item>\n    <Combobox.Item value=\"banana\">Banana</Combobox.Item>\n    <Combobox.Item value=\"orange\">Orange</Combobox.Item>\n    <Combobox.Item value=\"grape\">Grape</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
     },
     {
       "name": "Multiple Selection",
-      "description": "Multi-select with chips",
+      "description": "Each pick becomes a removable chip in the field.",
       "code": "<StatefulCombobox multiple placeholder=\"Select fruits...\">\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Item value=\"apple\">Apple</Combobox.Item>\n    <Combobox.Item value=\"banana\">Banana</Combobox.Item>\n    <Combobox.Item value=\"orange\">Orange</Combobox.Item>\n    <Combobox.Item value=\"grape\">Grape</Combobox.Item>\n    <Combobox.Item value=\"mango\">Mango</Combobox.Item>\n    <Combobox.Item value=\"kiwi\">Kiwi</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
     },
     {
       "name": "With Label and Helper Text",
-      "description": "Combobox with built-in label and helper text",
+      "description": "Helper text tells the user the field is searchable.",
       "code": "<StatefulCombobox\n  label=\"Assignee\"\n  placeholder=\"Search assignees...\"\n  helperText=\"Type to filter the list of available assignees.\"\n>\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Empty>No matches</Combobox.Empty>\n    <Combobox.Item value=\"alice\">Alice Johnson</Combobox.Item>\n    <Combobox.Item value=\"bob\">Bob Chen</Combobox.Item>\n    <Combobox.Item value=\"carol\">Carol Smith</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
     },
     {
       "name": "Error State",
-      "description": "Validation error with message",
-      "code": "<Combobox\n  label=\"Reviewer\"\n  placeholder=\"Search reviewers...\"\n  error=\"Please select a reviewer\"\n  disabled\n>\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Item value=\"alice\">Alice</Combobox.Item>\n  </Combobox.Content>\n</Combobox>"
+      "description": "Red border, and the message replaces helper text.",
+      "code": "<Combobox\n  label=\"Reviewer\"\n  placeholder=\"Search reviewers...\"\n  error=\"Please select a reviewer\"\n>\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Item value=\"alice\">Alice</Combobox.Item>\n  </Combobox.Content>\n</Combobox>"
     },
     {
       "name": "With Groups",
-      "description": "Options organized into groups",
+      "description": "Headed sections stay intact while filtering.",
       "code": "<StatefulCombobox placeholder=\"Search countries...\">\n  <Combobox.Input />\n  <Combobox.Content>\n    <>\n      <Combobox.Group>\n        <Combobox.GroupLabel>North America</Combobox.GroupLabel>\n        <Combobox.Item value=\"us\">United States</Combobox.Item>\n        <Combobox.Item value=\"ca\">Canada</Combobox.Item>\n        <Combobox.Item value=\"mx\">Mexico</Combobox.Item>\n      </Combobox.Group>\n      <Combobox.Group>\n        <Combobox.GroupLabel>Europe</Combobox.GroupLabel>\n        <Combobox.Item value=\"uk\">United Kingdom</Combobox.Item>\n        <Combobox.Item value=\"de\">Germany</Combobox.Item>\n        <Combobox.Item value=\"fr\">France</Combobox.Item>\n      </Combobox.Group>\n      <Combobox.Empty>No matching country</Combobox.Empty>\n    </>\n  </Combobox.Content>\n</StatefulCombobox>"
     },
     {
       "name": "With Empty State",
-      "description": "Shows message when no results match",
-      "code": "<StatefulCombobox placeholder=\"Search programming languages...\">\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Empty>No results found</Combobox.Empty>\n    <Combobox.Item value=\"js\">JavaScript</Combobox.Item>\n    <Combobox.Item value=\"ts\">TypeScript</Combobox.Item>\n    <Combobox.Item value=\"py\">Python</Combobox.Item>\n    <Combobox.Item value=\"rs\">Rust</Combobox.Item>\n    <Combobox.Item value=\"go\">Go</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
+      "description": "Combobox.Empty replaces the default no-results wording.",
+      "code": "<StatefulCombobox placeholder=\"Filter languages...\">\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Empty>No language matches that search</Combobox.Empty>\n    <Combobox.Item value=\"js\">JavaScript</Combobox.Item>\n    <Combobox.Item value=\"ts\">TypeScript</Combobox.Item>\n    <Combobox.Item value=\"py\">Python</Combobox.Item>\n    <Combobox.Item value=\"rs\">Rust</Combobox.Item>\n    <Combobox.Item value=\"go\">Go</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
     },
     {
       "name": "Scrollable List",
-      "description": "Long list with scroll hint — shows 4 items with half-peek of the 5th",
+      "description": "Caps at four rows and half-shows the fifth as a scroll hint.",
       "code": "<StatefulCombobox placeholder=\"Search languages...\">\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Empty>No results found</Combobox.Empty>\n    <Combobox.Item value=\"js\">JavaScript</Combobox.Item>\n    <Combobox.Item value=\"ts\">TypeScript</Combobox.Item>\n    <Combobox.Item value=\"py\">Python</Combobox.Item>\n    <Combobox.Item value=\"rs\">Rust</Combobox.Item>\n    <Combobox.Item value=\"go\">Go</Combobox.Item>\n    <Combobox.Item value=\"rb\">Ruby</Combobox.Item>\n    <Combobox.Item value=\"java\">Java</Combobox.Item>\n    <Combobox.Item value=\"swift\">Swift</Combobox.Item>\n    <Combobox.Item value=\"kt\">Kotlin</Combobox.Item>\n    <Combobox.Item value=\"cpp\">C++</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
     },
     {
       "name": "Custom Max Visible Items",
-      "description": "Show 6 items before scrolling with half-peek scroll hint",
+      "description": "maxVisibleItems raises the cap to six rows.",
       "code": "<StatefulCombobox placeholder=\"Search cities...\">\n  <Combobox.Input />\n  <Combobox.Content maxVisibleItems={6}>\n    <Combobox.Empty>No results found</Combobox.Empty>\n    <Combobox.Item value=\"nyc\">New York</Combobox.Item>\n    <Combobox.Item value=\"lon\">London</Combobox.Item>\n    <Combobox.Item value=\"tok\">Tokyo</Combobox.Item>\n    <Combobox.Item value=\"par\">Paris</Combobox.Item>\n    <Combobox.Item value=\"syd\">Sydney</Combobox.Item>\n    <Combobox.Item value=\"ber\">Berlin</Combobox.Item>\n    <Combobox.Item value=\"tor\">Toronto</Combobox.Item>\n    <Combobox.Item value=\"sin\">Singapore</Combobox.Item>\n    <Combobox.Item value=\"dub\">Dubai</Combobox.Item>\n    <Combobox.Item value=\"sao\">São Paulo</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
     },
     {
       "name": "Disabled",
-      "description": "Disabled combobox",
+      "description": "Dimmed and unfocusable.",
       "code": "<Combobox disabled placeholder=\"Search...\">\n  <Combobox.Input />\n  <Combobox.Content>\n    <Combobox.Item value=\"1\">Option 1</Combobox.Item>\n  </Combobox.Content>\n</Combobox>"
     },
     {
       "name": "Explicit Trigger",
-      "description": "Hide the built-in input trigger when rendering a separate Combobox.Trigger",
-      "code": "<StatefulCombobox placeholder=\"Search assignees...\">\n  <Combobox.Input showTrigger={false} />\n  <Combobox.Trigger aria-label=\"Open assignee list\" />\n  <Combobox.Content>\n    <Combobox.Item value=\"alice\">Alice</Combobox.Item>\n    <Combobox.Item value=\"bob\">Bob</Combobox.Item>\n    <Combobox.Item value=\"carol\">Carol</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
+      "description": "showTrigger={false} hands the open control to your own Combobox.Trigger.",
+      "code": "<StatefulCombobox placeholder=\"Search assignees...\">\n  <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>\n    <Combobox.Input showTrigger={false} />\n    <Combobox.Trigger aria-label=\"Open assignee list\" />\n  </div>\n  <Combobox.Content>\n    <Combobox.Item value=\"alice\">Alice</Combobox.Item>\n    <Combobox.Item value=\"bob\">Bob</Combobox.Item>\n    <Combobox.Item value=\"carol\">Carol</Combobox.Item>\n  </Combobox.Content>\n</StatefulCombobox>"
     }
   ],
   "relations": [

package/src/components/Combobox/Combobox.module.scss

@@ -285,7 +285,7 @@
 
 @media (prefers-contrast: more) {
   .inputWrapper {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
     border-color: var(--fui-text-primary, $fui-text-primary);
 
     &:focus-within {

package/src/components/Combobox/index.tsx

@@ -4,10 +4,7 @@ import * as React from "react";
 import { Combobox as BaseCombobox } from "@base-ui/react/combobox";
 import { useResolvedControlSize } from "../ComponentDefaults";
 import { mergeAriaIds, useFormFieldIds, type FormFieldProps } from "../../utils/aria";
-import {
-  POPUP_OFFSET_PX,
-  resolvePopupViewportRows,
-} from "../../recipes/popup";
+import { POPUP_OFFSET_PX, resolvePopupViewportRows } from "../../recipes/popup";
 import styles from "./Combobox.module.scss";
 
 // ============================================
@@ -293,6 +290,27 @@ function filterStaticChildren(
   };
 }
 
+/**
+ * True when the consumer already supplied a `Combobox.Empty` slot anywhere in
+ * the content. Used to decide whether the built-in "no results" fallback is
+ * needed — without it an unmatched query renders an empty, collapsed popup.
+ */
+function containsEmptySlot(node: React.ReactNode): boolean {
+  let found = false;
+  React.Children.forEach(node, (child) => {
+    if (found || !React.isValidElement(child)) return;
+    if (child.type === ComboboxEmpty) {
+      found = true;
+      return;
+    }
+    const props = child.props as { children?: React.ReactNode };
+    if (props.children !== undefined && containsEmptySlot(props.children)) {
+      found = true;
+    }
+  });
+  return found;
+}
+
 // ============================================
 // Components
 // ============================================
@@ -631,6 +649,14 @@ function ComboboxContent({
     () => filterStaticChildren(children, visibleValues),
     [children, visibleValues]
   );
+  // No matches and no author-supplied empty slot would leave a bare, collapsed
+  // popup, so fall back to a readable "no results" row.
+  const popupChildren =
+    filteredContent.visibleItemCount === 0 && !containsEmptySlot(children) ? (
+      <ComboboxEmpty>No results found</ComboboxEmpty>
+    ) : (
+      filteredContent.children
+    );
 
   const popupStyle =
     maxVisibleItems != null
@@ -650,7 +676,7 @@ function ComboboxContent({
       >
         <BaseCombobox.Popup {...htmlProps} className={popupClasses} style={popupStyle}>
           <ComboboxFilteredItemIndexContext.Provider value={filteredItemIndices}>
-            {filteredContent.children}
+            {popupChildren}
           </ComboboxFilteredItemIndexContext.Provider>
         </BaseCombobox.Popup>
       </BaseCombobox.Positioner>

package/src/components/Command/Command.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Command",
-  "description": "A searchable command palette for quick actions. Combines an input with a filterable, keyboard-navigable list of actions.",
+  "description": "Filters a list of actions as the user types.",
   "category": "navigation",
-  "tags": [
-    "command",
-    "palette",
-    "search",
-    "spotlight",
-    "quick-actions",
-    "cmdk"
-  ],
+  "tags": ["command", "palette", "search", "spotlight", "quick-actions", "cmdk"],
   "status": "stable",
   "sourcePath": "src/components/Command/index.tsx",
   "exportName": "Command",
@@ -58,23 +51,22 @@
   },
   "usage": {
     "when": [
-      "Quick-access command palettes (Ctrl+K)",
-      "Searchable action menus",
-      "Inline command lists with filtering",
-      "Application-wide search interfaces"
+      "A keyboard shortcut that jumps anywhere",
+      "Action lists too long to scan",
+      "Inline lists that need filtering",
+      "Search across everything the app can do"
     ],
     "whenNot": [
-      "Simple dropdown menus (use Menu)",
-      "Form field selection (use Select or Combobox)",
-      "Static navigation (use Sidebar or Tabs)",
-      "Search with complex result types (build custom)"
+      "A handful of actions (use Menu)",
+      "Picking a value for a form (use Select or Combobox)",
+      "Fixed navigation (use Sidebar or Tabs)"
     ],
     "guidelines": [
-      "Compose inside Dialog for modal command palette usage",
-      "Use Command.Group to organize items by category",
-      "Provide Command.Empty for no-results feedback",
-      "Use keywords prop for items that should match on aliases",
-      "Keep item labels short and action-oriented"
+      "Wrap in Dialog for the summon-anywhere palette",
+      "Group by category once the list gets long",
+      "Always supply Command.Empty",
+      "Add keywords so aliases and synonyms match",
+      "Label rows with a verb"
     ],
     "accessibility": [
       "Uses combobox + listbox ARIA pattern",
@@ -86,22 +78,22 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Inline command list with search",
+      "description": "Search field over a flat list.",
       "code": "<div style={{ maxWidth: '400px', width: '100%' }}>\n  <Command>\n    <Command.Input placeholder=\"Type a command...\" />\n    <Command.List>\n      <Command.Item onItemSelect={() => {}}>Open File</Command.Item>\n      <Command.Item onItemSelect={() => {}}>Save Document</Command.Item>\n      <Command.Item onItemSelect={() => {}}>Print</Command.Item>\n      <Command.Empty>No results found.</Command.Empty>\n    </Command.List>\n  </Command>\n</div>"
     },
     {
       "name": "Dialog Command Palette",
-      "description": "Command palette inside a Dialog",
+      "description": "The same list summoned over the page.",
       "code": "<Dialog>\n  <Dialog.Trigger asChild>\n    <Button variant=\"secondary\">Open Command Palette</Button>\n  </Dialog.Trigger>\n  <Dialog.Content size=\"sm\">\n    <Command>\n      <Command.Input placeholder=\"Search commands...\" />\n      <Command.List>\n        <Command.Group heading=\"Actions\">\n          <Command.Item onItemSelect={() => {}}>New File</Command.Item>\n          <Command.Item onItemSelect={() => {}}>Open Recent</Command.Item>\n        </Command.Group>\n        <Command.Separator />\n        <Command.Group heading=\"Settings\">\n          <Command.Item onItemSelect={() => {}}>Preferences</Command.Item>\n          <Command.Item onItemSelect={() => {}}>Keyboard Shortcuts</Command.Item>\n        </Command.Group>\n        <Command.Empty>No results found.</Command.Empty>\n      </Command.List>\n    </Command>\n  </Dialog.Content>\n</Dialog>"
     },
     {
       "name": "With Groups",
-      "description": "Organized by category groups",
+      "description": "Category labels survive filtering.",
       "code": "<div style={{ maxWidth: '400px', width: '100%' }}>\n  <Command>\n    <Command.Input placeholder=\"Search...\" />\n    <Command.List>\n      <Command.Group heading=\"Suggestions\">\n        <Command.Item onItemSelect={() => {}}>Calendar</Command.Item>\n        <Command.Item onItemSelect={() => {}}>Calculator</Command.Item>\n      </Command.Group>\n      <Command.Separator />\n      <Command.Group heading=\"Settings\">\n        <Command.Item onItemSelect={() => {}}>Profile</Command.Item>\n        <Command.Item onItemSelect={() => {}}>Billing</Command.Item>\n        <Command.Item disabled onItemSelect={() => {}}>\n          Team (coming soon)\n        </Command.Item>\n      </Command.Group>\n      <Command.Empty>No results found.</Command.Empty>\n    </Command.List>\n  </Command>\n</div>"
     },
     {
       "name": "With Icons",
-      "description": "Items with leading icons",
+      "description": "Leading glyphs speed up scanning.",
       "code": "<div style={{ maxWidth: '400px', width: '100%' }}>\n  <Command>\n    <Command.Input placeholder=\"What do you need?\" />\n    <Command.List>\n      <Command.Item onItemSelect={() => {}}>\n        <span style={{ marginRight: '0.5rem', fontSize: '1rem' }}>+</span> New Document\n      </Command.Item>\n      <Command.Item onItemSelect={() => {}}>\n        <span style={{ marginRight: '0.5rem', fontSize: '1rem' }}>{'>'}</span> Open Folder\n      </Command.Item>\n      <Command.Item onItemSelect={() => {}}>\n        <span style={{ marginRight: '0.5rem', fontSize: '1rem' }}>?</span> Search\n      </Command.Item>\n      <Command.Empty>No results found.</Command.Empty>\n    </Command.List>\n  </Command>\n</div>"
     }
   ],
@@ -132,26 +124,12 @@
       "Command.Item keywords: string[] - extra filter terms",
       "Command.Item onItemSelect: (value, event) => void - selection handler"
     ],
-    "a11yRules": [
-      "A11Y_COMBOBOX_ROLE",
-      "A11Y_LISTBOX_ROLE",
-      "A11Y_ACTIVE_DESCENDANT"
-    ]
+    "a11yRules": ["A11Y_COMBOBOX_ROLE", "A11Y_LISTBOX_ROLE", "A11Y_ACTIVE_DESCENDANT"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Input",
-      "List",
-      "Item",
-      "Group",
-      "Empty",
-      "Separator"
-    ],
-    "requiredChildren": [
-      "Input",
-      "List"
-    ],
+    "subComponents": ["Input", "List", "Item", "Group", "Empty", "Separator"],
+    "requiredChildren": ["Input", "List"],
     "commonPatterns": [
       "<Dialog><Dialog.Trigger><Button>Open Palette</Button></Dialog.Trigger><Dialog.Content size=\"sm\"><Command><Command.Input placeholder=\"Search...\" /><Command.List><Command.Group heading=\"Actions\"><Command.Item onItemSelect={() => {}}>Action 1</Command.Item></Command.Group><Command.Empty>No results.</Command.Empty></Command.List></Command></Dialog.Content></Dialog>"
     ]

package/src/components/Command/index.tsx

@@ -1,7 +1,7 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import styles from './Command.module.scss';
+import * as React from "react";
+import styles from "./Command.module.scss";
 
 // ============================================
 // Types
@@ -30,7 +30,7 @@ export interface CommandListProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
 }
 
-export interface CommandItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+export interface CommandItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onSelect"> {
   children: React.ReactNode;
   /** Value used for filtering (falls back to text content) */
   value?: string;
@@ -78,13 +78,13 @@ function defaultFilter(value: string, search: string, keywords?: string[]): numb
 }
 
 function getTextContent(node: React.ReactNode): string {
-  if (typeof node === 'string' || typeof node === 'number') return String(node);
-  if (Array.isArray(node)) return node.map(getTextContent).join(' ');
+  if (typeof node === "string" || typeof node === "number") return String(node);
+  if (Array.isArray(node)) return node.map(getTextContent).join(" ");
   if (React.isValidElement(node)) {
     const childProps = node.props as { children?: React.ReactNode };
     return getTextContent(childProps.children);
   }
-  return '';
+  return "";
 }
 
 // ============================================
@@ -115,7 +115,7 @@ const CommandContext = React.createContext<CommandContextValue | null>(null);
 
 function useCommandContext() {
   const ctx = React.useContext(CommandContext);
-  if (!ctx) throw new Error('Command sub-components must be used within <Command>');
+  if (!ctx) throw new Error("Command sub-components must be used within <Command>");
   return ctx;
 }
 
@@ -150,7 +150,7 @@ function SearchIcon() {
 function CommandRoot({
   children,
   search: controlledSearch,
-  defaultSearch = '',
+  defaultSearch = "",
   onSearchChange,
   filter = defaultFilter,
   loop = true,
@@ -231,14 +231,25 @@ function CommandRoot({
       visibleCount,
       listId,
     }),
-    [search, setSearch, filter, scores, registerItem, unregisterItem, activeId, loop, visibleCount, listId]
+    [
+      search,
+      setSearch,
+      filter,
+      scores,
+      registerItem,
+      unregisterItem,
+      activeId,
+      loop,
+      visibleCount,
+      listId,
+    ]
   );
 
   return (
     <CommandContext.Provider value={contextValue}>
       <div
         {...htmlProps}
-        className={[styles.command, className].filter(Boolean).join(' ')}
+        className={[styles.command, className].filter(Boolean).join(" ")}
         role="search"
       >
         {children}
@@ -247,12 +258,7 @@ function CommandRoot({
   );
 }
 
-function CommandInput({
-  className,
-  onChange,
-  onKeyDown,
-  ...htmlProps
-}: CommandInputProps) {
+function CommandInput({ className, onChange, onKeyDown, ...htmlProps }: CommandInputProps) {
   const { search, setSearch, listRef, setActiveId, activeId, loop, listId } = useCommandContext();
   const inputRef = React.useRef<HTMLInputElement>(null);
 
@@ -261,7 +267,7 @@ function CommandInput({
     if (!list) return [];
     return Array.from(
       list.querySelectorAll<HTMLElement>('[data-command-item]:not([data-disabled="true"])')
-    ).filter((el) => el.style.display !== 'none');
+    ).filter((el) => el.style.display !== "none");
   }, [listRef]);
 
   const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
@@ -270,45 +276,48 @@ function CommandInput({
 
     const items = getEnabledItems();
     if (items.length === 0) return;
+    const firstItem = items[0];
+    const lastItem = items.at(-1);
+    if (!firstItem || !lastItem) return;
 
-    const currentIndex = activeId
-      ? items.findIndex((item) => item.id === activeId)
-      : -1;
+    const currentIndex = activeId ? items.findIndex((item) => item.id === activeId) : -1;
 
     switch (event.key) {
-      case 'ArrowDown': {
+      case "ArrowDown": {
         event.preventDefault();
         if (currentIndex < 0) {
-          setActiveId(items[0].id);
+          setActiveId(firstItem.id);
         } else if (currentIndex < items.length - 1) {
-          setActiveId(items[currentIndex + 1].id);
+          const nextItem = items[currentIndex + 1];
+          if (nextItem) setActiveId(nextItem.id);
         } else if (loop) {
-          setActiveId(items[0].id);
+          setActiveId(firstItem.id);
         }
         break;
       }
-      case 'ArrowUp': {
+      case "ArrowUp": {
         event.preventDefault();
         if (currentIndex < 0) {
-          setActiveId(items[items.length - 1].id);
+          setActiveId(lastItem.id);
         } else if (currentIndex > 0) {
-          setActiveId(items[currentIndex - 1].id);
+          const previousItem = items[currentIndex - 1];
+          if (previousItem) setActiveId(previousItem.id);
         } else if (loop) {
-          setActiveId(items[items.length - 1].id);
+          setActiveId(lastItem.id);
         }
         break;
       }
-      case 'Home': {
+      case "Home": {
         event.preventDefault();
-        setActiveId(items[0].id);
+        setActiveId(firstItem.id);
         break;
       }
-      case 'End': {
+      case "End": {
         event.preventDefault();
-        setActiveId(items[items.length - 1].id);
+        setActiveId(lastItem.id);
         break;
       }
-      case 'Enter': {
+      case "Enter": {
         event.preventDefault();
         if (activeId) {
           const activeItem = items.find((item) => item.id === activeId);
@@ -343,7 +352,7 @@ function CommandInput({
           setSearch(e.target.value);
         }}
         onKeyDown={handleKeyDown}
-        className={[styles.input, className].filter(Boolean).join(' ')}
+        className={[styles.input, className].filter(Boolean).join(" ")}
       />
     </div>
   );
@@ -358,7 +367,7 @@ function CommandList({ children, className, ...htmlProps }: CommandListProps) {
       {...htmlProps}
       id={listId}
       role="listbox"
-      className={[styles.list, className].filter(Boolean).join(' ')}
+      className={[styles.list, className].filter(Boolean).join(" ")}
     >
       {children}
     </div>
@@ -402,11 +411,13 @@ function CommandItem({
   // Scroll active item into view
   React.useEffect(() => {
     if (isActive && itemRef.current) {
-      itemRef.current.scrollIntoView({ block: 'nearest' });
+      itemRef.current.scrollIntoView({ block: "nearest" });
     }
   }, [isActive]);
 
-  const activateItem = (event: React.MouseEvent<HTMLDivElement> | React.KeyboardEvent<HTMLDivElement>) => {
+  const activateItem = (
+    event: React.MouseEvent<HTMLDivElement> | React.KeyboardEvent<HTMLDivElement>
+  ) => {
     if (disabled) return;
     onItemSelect?.(textValue, event);
   };
@@ -440,7 +451,7 @@ function CommandItem({
       onKeyDown={(e) => {
         onKeyDown?.(e);
         if (e.defaultPrevented) return;
-        if (e.key === 'Enter' || e.key === ' ') {
+        if (e.key === "Enter" || e.key === " ") {
           e.preventDefault();
           activateItem(e);
         }
@@ -453,8 +464,8 @@ function CommandItem({
         className,
       ]
         .filter(Boolean)
-        .join(' ')}
-      style={{ ...style, display: isVisible ? undefined : 'none' }}
+        .join(" ")}
+      style={{ ...style, display: isVisible ? undefined : "none" }}
     >
       {children}
     </div>
@@ -470,8 +481,8 @@ function CommandGroup({ children, heading, className, ...htmlProps }: CommandGro
   // Check if any children are visible after each score update
   React.useEffect(() => {
     if (!groupRef.current) return;
-    const items = groupRef.current.querySelectorAll<HTMLElement>('[data-command-item]');
-    const anyVisible = Array.from(items).some((item) => item.style.display !== 'none');
+    const items = groupRef.current.querySelectorAll<HTMLElement>("[data-command-item]");
+    const anyVisible = Array.from(items).some((item) => item.style.display !== "none");
     setHasVisibleChildren(anyVisible);
   }, [scores]);
 
@@ -483,8 +494,8 @@ function CommandGroup({ children, heading, className, ...htmlProps }: CommandGro
       {...restHtmlProps}
       role="group"
       aria-labelledby={heading ? labelId : undefined}
-      className={[styles.group, className].filter(Boolean).join(' ')}
-      style={{ ...style, display: hasVisibleChildren ? undefined : 'none' }}
+      className={[styles.group, className].filter(Boolean).join(" ")}
+      style={{ ...style, display: hasVisibleChildren ? undefined : "none" }}
     >
       {heading && (
         <div id={labelId} className={styles.groupHeading}>
@@ -507,7 +518,7 @@ function CommandEmpty({ children, className, ...htmlProps }: CommandEmptyProps)
       role="option"
       aria-disabled="true"
       aria-selected="false"
-      className={[styles.empty, className].filter(Boolean).join(' ')}
+      className={[styles.empty, className].filter(Boolean).join(" ")}
     >
       {children}
     </div>
@@ -519,7 +530,7 @@ function CommandSeparator({ className, ...htmlProps }: CommandSeparatorProps) {
     <div
       {...htmlProps}
       role="separator"
-      className={[styles.separator, className].filter(Boolean).join(' ')}
+      className={[styles.separator, className].filter(Boolean).join(" ")}
     />
   );
 }