diff --git a/.changeset/salty-meals-bet.md b/.changeset/salty-meals-bet.md
new file mode 100644
index 000000000..4ce28df81
--- /dev/null
+++ b/.changeset/salty-meals-bet.md
@@ -0,0 +1,7 @@
+---
+"@commercetools/nimbus": minor
+"@commercetools/nimbus-i18n": minor
+---
+
+Update Combobox to new context-based architecture and add missing features,
+update i18n strings.
diff --git a/.claude/agents/nimbus-researcher.md b/.claude/agents/nimbus-researcher.md
index 861fbaf59..65a93b3b5 100644
--- a/.claude/agents/nimbus-researcher.md
+++ b/.claude/agents/nimbus-researcher.md
@@ -1,6 +1,6 @@
 ---
 name: nimbus-researcher
-description: Use this agent when you need to gather information, find documentation, explore technical concepts, or research solutions to problems. This includes searching for library documentation, API references, best practices, code examples, or general web information. The agent will use context7 for library documentation and web search for broader research needs.\n\nExamples:\n<example>\nContext: User needs to understand how to implement a specific React Aria pattern\nuser: "How do I implement an accessible combobox with React Aria?"\nassistant: "I'll use the research-analyst agent to find the React Aria documentation for combobox implementation."\n<commentary>\nSince the user needs documentation about a library feature, use the research-analyst agent to search context7 for React Aria combobox documentation.\n</commentary>\n</example>\n<example>\nContext: User wants to understand a technical concept before implementation\nuser: "What are the best practices for implementing compound components in React?"\nassistant: "Let me use the research-analyst agent to research compound component patterns and best practices."\n<commentary>\nThe user needs research on design patterns and best practices, so the research-analyst agent should gather this information from various sources.\n</commentary>\n</example>\n<example>\nContext: User encounters an error and needs to understand the cause\nuser: "I'm getting a 'Cannot read properties of undefined' error in my Chakra UI recipe"\nassistant: "I'll use the research-analyst agent to research this error in the context of Chakra UI recipes."\n<commentary>\nDebugging requires understanding the error context, so use the research-analyst agent to find relevant documentation and solutions.\n</commentary>\n</example>
+description: Use this agent when you need to gather information, find documentation, explore technical concepts, or research solutions to problems. This includes searching for library documentation, API references, best practices, code examples, or general web information. The agent will use the react-aria-docs mcp for react-aria specific documentation and research needs.  The agent will use context7 for library documentation and web search for broader research needs.  \n\nExamples:\n<example>\nContext: User needs to understand how to implement a specific React Aria pattern\nuser: "How do I implement an accessible combobox with React Aria?"\nassistant: "I'll use the research-analyst agent to find the React Aria documentation for combobox implementation."\n<commentary>\nSince the user needs documentation about a library feature, use the research-analyst agent to search react-aria-docs and context7 for React Aria combobox documentation.\n</commentary>\n</example>\n<example>\nContext: User wants to understand a technical concept before implementation\nuser: "What are the best practices for implementing compound components in React?"\nassistant: "Let me use the research-analyst agent to research compound component patterns and best practices."\n<commentary>\nThe user needs research on design patterns and best practices, so the research-analyst agent should gather this information from various sources.\n</commentary>\n</example>\n<example>\nContext: User encounters an error and needs to understand the cause\nuser: "I'm getting a 'Cannot read properties of undefined' error in my Chakra UI recipe"\nassistant: "I'll use the research-analyst agent to research this error in the context of Chakra UI recipes."\n<commentary>\nDebugging requires understanding the error context, so use the research-analyst agent to find relevant documentation and solutions.\n</commentary>\n</example>
 model: sonnet
 ---
 
@@ -34,6 +34,9 @@ You will:
 
 - Use `mcp__context7__resolve-library-id` to search for specific library
   documentation
+- Prefer `mcp__react-aria-docs__list_pages`,
+  `mcp__react-aria-docs__get_page_info`, and `mcp__react-aria-docs__get_page`
+  when searching for react-aria library documentation
 - Focus on official documentation for React Aria, Chakra UI, React, TypeScript,
   and related libraries
 - Look for code examples, API references, and implementation patterns
diff --git a/.mcp.json b/.mcp.json
index acc321c29..6bbb83b9f 100644
--- a/.mcp.json
+++ b/.mcp.json
@@ -15,6 +15,12 @@
     "time-mcp": {
       "command": "npx",
       "args": ["-y", "time-mcp"]
+    },
+    "react-aria-docs": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@react-spectrum/mcp", "react-aria"],
+      "env": {}
     }
   }
 }
diff --git a/apps/docs/package.json b/apps/docs/package.json
index 224d2f671..7858e486c 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -43,6 +43,7 @@
     "react-dom": "catalog:react",
     "react-intl": "catalog:react",
     "react-live": "^4.1.7",
+    "react-stately": "catalog:react",
     "react-router": "^7.12.0",
     "react-router-dom": "^7.11.0",
     "react-syntax-highlighter": "^15.6.6",
@@ -52,6 +53,7 @@
     "remark-mark-highlight": "^0.1.1",
     "slug": "^11.0.1",
     "to-vfile": "^8.0.0",
+    "use-debounce": "^10.0.0",
     "vite-plugin-markdown": "^2.2.0",
     "vite-tsconfig-paths": "^5.1.3",
     "zod": "^4.1.12"
diff --git a/apps/docs/src/components/document-renderer/components/live-code-editor/live-code-editor.tsx b/apps/docs/src/components/document-renderer/components/live-code-editor/live-code-editor.tsx
index 8a462ab08..940f5a60b 100644
--- a/apps/docs/src/components/document-renderer/components/live-code-editor/live-code-editor.tsx
+++ b/apps/docs/src/components/document-renderer/components/live-code-editor/live-code-editor.tsx
@@ -13,6 +13,8 @@ import {
   getLocalTimeZone,
   today,
 } from "@internationalized/date";
+import { useAsyncList } from "react-stately";
+import { useDebouncedCallback } from "use-debounce";
 
 const baseHooks = {
   useState,
@@ -33,6 +35,8 @@ const scope = {
   parseZonedDateTime,
   getLocalTimeZone,
   today,
+  useAsyncList,
+  useDebouncedCallback,
 };
 
 const removeImportStatements = (code: string) => {
diff --git a/packages/nimbus/package.json b/packages/nimbus/package.json
index 742dd571d..871102996 100644
--- a/packages/nimbus/package.json
+++ b/packages/nimbus/package.json
@@ -59,7 +59,8 @@
     "react-aria-components": "catalog:react",
     "react-hotkeys-hook": "^5.2.1",
     "react-stately": "catalog:react",
-    "react-use": "^17.5.1"
+    "react-use": "^17.5.1",
+    "use-debounce": "^10.0.0"
   },
   "devDependencies": {
     "@chakra-ui/cli": "catalog:react",
@@ -68,6 +69,7 @@
     "@commercetools/nimbus-tokens": "workspace:^",
     "@internationalized/date": "catalog:react",
     "@react-aria/optimize-locales-plugin": "catalog:react",
+    "@react-types/shared": "catalog:tooling",
     "@storybook/addon-a11y": "catalog:tooling",
     "@storybook/addon-docs": "catalog:tooling",
     "@storybook/addon-vitest": "catalog:tooling",
diff --git a/packages/nimbus/src/components/calendar/components/calendar.header.tsx b/packages/nimbus/src/components/calendar/components/calendar.header.tsx
index 5993dc62b..89d8aacc1 100644
--- a/packages/nimbus/src/components/calendar/components/calendar.header.tsx
+++ b/packages/nimbus/src/components/calendar/components/calendar.header.tsx
@@ -32,7 +32,6 @@ export const CalendarHeader = () => {
           <VisuallyHidden>
             <Heading />
           </VisuallyHidden>
-          {/* @ts-expect-error - custom-context will add aria-label via the "slot" prop */}
           <IconButton
             slot={showRangeLabel ? "previous" : "previous-month"}
             size="xs"
@@ -50,7 +49,6 @@ export const CalendarHeader = () => {
             aria-hidden="true"
             slot={showRangeLabel ? "monthRange" : "month"}
           />
-          {/* @ts-expect-error - custom-context will add aria-label via the "slot" prop */}
           <IconButton
             slot={showRangeLabel ? "next" : "next-month"}
             size="xs"
@@ -62,7 +60,6 @@ export const CalendarHeader = () => {
         </Stack>
         <Box flexGrow="1" />
         <Stack direction="row" alignItems="center">
-          {/* @ts-expect-error - custom-context will add aria-label via the "slot" prop */}
           <IconButton
             slot="previous-year"
             size="xs"
@@ -80,7 +77,6 @@ export const CalendarHeader = () => {
             aria-hidden="true"
             slot="year"
           />
-          {/* @ts-expect-error - custom-context will add aria-label via the "slot" prop */}
           <IconButton
             slot="next-year"
             size="xs"
diff --git a/packages/nimbus/src/components/combobox/README.md b/packages/nimbus/src/components/combobox/README.md
new file mode 100644
index 000000000..c346121cd
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/README.md
@@ -0,0 +1,641 @@
+# ComboBox Architecture
+
+## Overview
+
+The ComboBox component is a searchable, filterable selection component built on
+React Aria Components. It supports single and multi-select modes, custom option
+creation, async data loading, custom filtering, sections, and follows WCAG 2.1
+AA accessibility guidelines.
+
+## Key Features
+
+### Core Features
+
+- **Single & Multi-Select**: Toggle between modes via `selectionMode` prop
+  ("single" | "multiple")
+- **Smart Filtering**: Built-in text filtering with customizable filter
+  functions and utilities
+- **Custom Options**: Allow users to create new options on-the-fly
+  (`allowsCustomOptions`)
+- **Async Loading**: Built-in support for async data loading with `useAsyncList`
+  integration
+- **Sections**: Group related options with headers (optgroups)
+- **Keyboard Navigation**: Full keyboard support (arrows, Enter, Escape,
+  Home/End, Backspace)
+- **Accessible**: WCAG 2.1 AA compliant with proper ARIA attributes and virtual
+  focus
+- **Controlled/Uncontrolled**: Supports both patterns for selection, input
+  value, and open state
+- **Form Integration**: Hidden input for native form submission
+- **Leading Elements**: Support for icons or custom elements before the input
+  field
+
+### Visual Features
+
+- **Size Variants**: Small, medium (default), and large sizes
+- **Visual Variants**: Default styling with variant support
+- **States**: Support for `isDisabled`, `isReadOnly`, `isRequired`, `isInvalid`
+- **Loading State**: Built-in loading indicators for async operations
+- **Empty State**: Customizable empty state when no options match
+
+### Filter Utilities
+
+The component exports a comprehensive set of filter utilities via
+`ComboBox.filters`:
+
+- **Basic Filters**: `filterByText`, `filterByStartsWith`,
+  `filterByCaseSensitive`, `filterByWordBoundary`
+- **Advanced Filters**: `filterByFuzzy`, `createRankedFilter`
+- **Multi-Property**: `createMultiPropertyFilter` - search across multiple
+  object properties
+- **Multi-Term**: `createMultiTermFilter` - OR logic for multiple search terms
+- **Section-Aware**: `createSectionAwareFilter` - preserves section structure
+  while filtering
+
+## Architecture
+
+### Component Structure
+
+```
+ComboBox (compound component)
+├── ComboBox.Root          # Root container - provides state and context
+│   ├── ComboBoxRootInner  # Internal: Core logic and state management
+│   └── React Aria Provider # Internal: React Aria integration
+├── ComboBox.Trigger       # Trigger container
+│   ├── Leading Element    # Optional: Icon or custom element
+│   ├── Tag Group          # Internal: Selected tags (multi-select only)
+│   ├── Input              # Internal: Text input field
+│   ├── Toggle Button      # Internal: Open/close dropdown button
+│   ├── Clear Button       # Internal: Clear selection (visible when has selection)
+│   └── Hidden Input       # Internal: Form submission
+├── ComboBox.Popover       # Dropdown container (portal)
+│   └── ComboBox.ListBox   # Options list container
+│       ├── ComboBox.Section   # Optional: Group with heading
+│       │   └── ComboBox.Option # Individual option
+│       └── ComboBox.Option     # Individual option
+└── ComboBox.filters       # Filter utility functions
+```
+
+**Note**: Most child components (Input, Buttons, TagGroup, HiddenInput) are
+internal and render automatically. Users only need to compose Root, Trigger,
+Popover, ListBox, and Option.
+
+### State Management
+
+The component manages three independent pieces of state, each supporting
+controlled/uncontrolled patterns:
+
+#### 1. Selection State
+
+- **Controlled**: `selectedKeys` + `onSelectionChange`
+- **Uncontrolled**: `defaultSelectedKeys` + internal state
+- **Storage**: Normalized as `Set<Key>` internally, exposed as `Key[]` or
+  `"all"`
+- **Behavior**:
+  - Single-select: Replaces selection on click, menu closes after selection
+  - Multi-select: Toggles selection on click, menu stays open, shows removable
+    tags
+
+#### 2. Input Value State
+
+- **Controlled**: `inputValue` + `onInputChange`
+- **Uncontrolled**: `defaultInputValue` + internal state
+- **Sync**: In single-select, input auto-syncs with selected item text
+- **Behavior**: Used for filtering the options list
+
+#### 3. Open State
+
+- **Controlled**: `isOpen` + `onOpenChange`
+- **Uncontrolled**: `defaultOpen` + internal state
+- **Triggers**: Manual toggle button, input focus, typing, keyboard shortcuts
+
+### Data Flow
+
+```
+User Types → Input Change → Filter Collection → Update Menu
+User Clicks Option → Selection Change → Update Input (single) / Add Tag (multi)
+User Presses Arrow → Focus Next/Prev → Scroll Into View
+User Presses Enter → Select Focused / Create Custom → Close Menu (single)
+User Clicks Clear → Clear Selection → Clear Input (single) / Remove All Tags (multi)
+```
+
+### Collection System
+
+React Aria's `CollectionBuilder` parses JSX children into a `Collection` object:
+
+```tsx
+<ComboBox.Root items={items}>
+  {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+</ComboBox.Root>
+```
+
+The Collection provides:
+
+- Navigation methods (`getFirstKey`, `getLastKey`, `getKeyAfter`,
+  `getKeyBefore`)
+- Item lookup (`getItem(key)`)
+- Filtering (`nodes.filter()`) - preserves navigation structure
+- Metadata extraction (textValue, disabled state, etc.)
+
+**Why persist the collection?** The collection is built when the menu is open
+and persisted to avoid rebuilding when the menu closes. This ensures consistent
+behavior and prevents flickering.
+
+### React Aria Integration
+
+The component delegates complex behaviors to React Aria:
+
+#### useListState
+
+- **Purpose**: Handles keyboard navigation, focus tracking, and selection
+  management
+- **Provides**: `state.collection` (navigation) + `state.selectionManager`
+  (selection/focus)
+
+#### Virtual Focus (aria-activedescendant)
+
+- **Purpose**: Keeps browser focus on input while visually focusing options
+- **Benefit**:
+  - Screen readers announce focused options without losing input focus
+  - Typing works immediately without refocusing the input
+  - Keyboard navigation feels natural
+
+#### Context Distribution (Providers)
+
+- **Purpose**: Distributes props to child components without prop drilling
+- **Implementation**: Each context (InputContext, ListBoxContext, etc.)
+  configures a specific child component
+
+## File Structure
+
+### Core Files
+
+```
+combobox/
+├── combobox.tsx                        # Main export with compound component API
+├── combobox.types.ts                   # TypeScript interfaces (400+ lines)
+├── combobox.recipe.ts                  # Chakra UI styling (slot recipe)
+├── combobox.slots.tsx                  # Styled slot components
+├── combobox.i18n.ts                    # Internationalization messages
+├── combobox.stories.tsx                # Storybook stories with interaction tests
+├── combobox.mdx                        # Component documentation
+└── TESTING_PLAN.md                     # Comprehensive testing checklist
+```
+
+### Implementation Files
+
+```
+components/
+├── combobox.root.tsx                   # Root component with state management (900+ lines)
+├── combobox.trigger.tsx                # Trigger container
+├── combobox.input.tsx                  # Text input field (internal)
+├── combobox.leading-element.tsx        # Leading icon/element container (internal)
+├── combobox.tag-group.tsx              # Selected tags for multi-select (internal)
+├── combobox.popover.tsx                # Dropdown popover container
+├── combobox.listbox.tsx                # Options list
+├── combobox.option.tsx                 # Individual option
+├── combobox.hidden-input.tsx           # Form submission (internal)
+└── index.ts                            # Component barrel export
+```
+
+### Utility Files
+
+```
+utils/
+├── collection.ts                       # Collection utilities
+├── collection.spec.ts                  # Collection tests
+├── filters.ts                          # Filter functions and factories
+├── filters.spec.ts                     # Filter tests
+├── selection.ts                        # Selection utilities
+├── selection.spec.ts                   # Selection tests
+└── test-data.ts                        # Shared test data
+```
+
+## Usage Patterns
+
+### Basic Single-Select
+
+```tsx
+<ComboBox.Root items={items}>
+  <ComboBox.Trigger />
+  <ComboBox.Popover>
+    <ComboBox.ListBox>
+      {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+    </ComboBox.ListBox>
+  </ComboBox.Popover>
+</ComboBox.Root>
+```
+
+### Multi-Select with Tags
+
+```tsx
+<ComboBox.Root items={items} selectionMode="multiple">
+  <ComboBox.Trigger />
+  <ComboBox.Popover>
+    <ComboBox.ListBox>
+      {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+    </ComboBox.ListBox>
+  </ComboBox.Popover>
+</ComboBox.Root>
+```
+
+### With Sections
+
+```tsx
+<ComboBox.Root>
+  <ComboBox.Trigger />
+  <ComboBox.Popover>
+    <ComboBox.ListBox>
+      <ComboBox.Section label="Mammals">
+        <ComboBox.Option id="lion">Lion</ComboBox.Option>
+        <ComboBox.Option id="tiger">Tiger</ComboBox.Option>
+      </ComboBox.Section>
+      <ComboBox.Section label="Birds">
+        <ComboBox.Option id="eagle">Eagle</ComboBox.Option>
+        <ComboBox.Option id="hawk">Hawk</ComboBox.Option>
+      </ComboBox.Section>
+    </ComboBox.ListBox>
+  </ComboBox.Popover>
+</ComboBox.Root>
+```
+
+### Custom Filtering
+
+```tsx
+<ComboBox.Root items={items} filter={ComboBox.filters.filterByStartsWith}>
+  <ComboBox.Trigger />
+  <ComboBox.Popover>
+    <ComboBox.ListBox>
+      {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+    </ComboBox.ListBox>
+  </ComboBox.Popover>
+</ComboBox.Root>
+```
+
+### Multi-Property Search
+
+```tsx
+const productFilter = ComboBox.filters.createMultiPropertyFilter<Product>([
+  "name",
+  "category",
+  "description",
+]);
+
+<ComboBox.Root items={products} filter={productFilter}>
+  <ComboBox.Trigger />
+  <ComboBox.Popover>
+    <ComboBox.ListBox>
+      {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+    </ComboBox.ListBox>
+  </ComboBox.Popover>
+</ComboBox.Root>;
+```
+
+### Section-Aware Filtering
+
+```tsx
+const sectionFilter = ComboBox.filters.createSectionAwareFilter(
+  ComboBox.filters.filterByFuzzy
+);
+
+<ComboBox.Root items={sectionsWithItems} filter={sectionFilter}>
+  <ComboBox.Trigger />
+  <ComboBox.Popover>
+    <ComboBox.ListBox>
+      {(section) => (
+        <ComboBox.Section>
+          {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+        </ComboBox.Section>
+      )}
+    </ComboBox.ListBox>
+  </ComboBox.Popover>
+</ComboBox.Root>;
+```
+
+### Custom Options
+
+```tsx
+<ComboBox.Root
+  items={items}
+  allowsCustomOptions
+  getNewOptionData={(textValue) => ({
+    id: generateId(),
+    name: textValue,
+  })}
+  onCreateOption={(item) => {
+    // Save to backend or update parent state
+    api.createItem(item);
+  }}
+>
+  <ComboBox.Trigger />
+  <ComboBox.Popover>
+    <ComboBox.ListBox>
+      {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+    </ComboBox.ListBox>
+  </ComboBox.Popover>
+</ComboBox.Root>
+```
+
+### Async Loading
+
+```tsx
+const [error, setError] = useState<string | null>(null);
+
+<ComboBox.Root
+  items={items}
+  async={{
+    load: async (filterText, signal) => {
+      setError(null);
+
+      if (!filterText || filterText.length < 2) {
+        return [];
+      }
+
+      try {
+        const response = await fetch(
+          `/api/search?q=${encodeURIComponent(filterText)}`,
+          { signal }
+        );
+
+        if (!response.ok) {
+          throw new Error(`HTTP error! status: ${response.status}`);
+        }
+
+        const data = await response.json();
+        return data;
+      } catch (err) {
+        if (err.name === "AbortError") throw err;
+        setError(err.message);
+        return [];
+      }
+    },
+    minSearchLength: 2,
+    debounce: 300,
+    onError: (err) => setError(err.message),
+  }}
+  renderEmptyState={({ isLoading }) =>
+    isLoading ? (
+      <Text>Loading...</Text>
+    ) : error ? (
+      <Text color="critical.11">{error}</Text>
+    ) : (
+      <Text>Start typing to search...</Text>
+    )
+  }
+>
+  <ComboBox.Trigger />
+  <ComboBox.Popover>
+    <ComboBox.ListBox>
+      {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+    </ComboBox.ListBox>
+  </ComboBox.Popover>
+</ComboBox.Root>;
+```
+
+### Controlled State
+
+```tsx
+const [selectedKeys, setSelectedKeys] = useState<Key[]>([]);
+const [inputValue, setInputValue] = useState("");
+const [isOpen, setIsOpen] = useState(false);
+
+<ComboBox.Root
+  items={items}
+  selectedKeys={selectedKeys}
+  onSelectionChange={setSelectedKeys}
+  inputValue={inputValue}
+  onInputChange={setInputValue}
+  isOpen={isOpen}
+  onOpenChange={setIsOpen}
+>
+  <ComboBox.Trigger />
+  <ComboBox.Popover>
+    <ComboBox.ListBox>
+      {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+    </ComboBox.ListBox>
+  </ComboBox.Popover>
+</ComboBox.Root>;
+```
+
+## Behavior Details
+
+### Single-Select Mode
+
+**Selection**:
+
+- Clicking an option **replaces** the selection
+- Input value syncs with selected item text
+- Menu closes after selection (configurable via `shouldCloseOnSelect`)
+- Clear button removes the selection
+
+**Filtering**:
+
+- Typing filters the option list
+- If input exactly matches selected item, shows full list (UX: clicking input
+  shows all options)
+
+**Keyboard**:
+
+- `Enter`: Select focused option and close
+- `Backspace` (empty input): Clear selection
+
+### Multi-Select Mode
+
+**Selection**:
+
+- Clicking an option **toggles** it in/out of selection
+- Selected items shown as removable tags
+- Menu stays open after selection
+- Clear button removes all selections
+
+**Filtering**:
+
+- Typing filters options independently of selection
+- Input value independent of selected items
+- Input clears after each selection
+
+**Keyboard**:
+
+- `Enter`: Toggle focused option
+- `Backspace` (empty input): Remove last tag
+
+### Custom Options
+
+When `allowsCustomOptions=true`:
+
+1. User types text not matching any option
+2. User presses `Enter` (with no option focused)
+3. Validation: Check `isValidNewOption` if provided
+4. Creation: Call `getNewOptionData` to create item object
+5. Add to internal items array
+6. Select the new item
+7. Notify via `onCreateOption` callback
+
+**Duplicate Prevention**: Custom validation can prevent duplicate options
+(case-insensitive check)
+
+## Accessibility
+
+### ARIA Attributes
+
+**Input**:
+
+- `role="combobox"` - Identifies as autocomplete input
+- `aria-autocomplete="list"` - Suggestions in a list
+- `aria-controls="listbox-id"` - References controlled elements
+- `aria-expanded` - Announces menu open/closed
+- `aria-activedescendant` - Announces focused option (virtual focus)
+- `aria-invalid` - Announces invalid state
+- `aria-required` - Announces required state
+- `aria-disabled` - Announces disabled state
+- `aria-readonly` - Announces read-only state
+
+**ListBox**:
+
+- `role="listbox"` - Identifies as option list
+- `id="listbox-id"` - Referenced by input's aria-controls
+
+**Options**:
+
+- `role="option"` - Identifies as selectable option
+- `aria-selected` - Selection state
+- `id="listbox-id-option-{key}"` - Referenced by aria-activedescendant
+
+**Sections**:
+
+- `role="group"` - Identifies as option group
+- `aria-labelledby` - References section heading
+
+### Keyboard Navigation
+
+| Key         | Action                                                     |
+| ----------- | ---------------------------------------------------------- |
+| `Tab`       | Focus input / Move to next focusable element               |
+| `ArrowDown` | Open menu (focus first) or move to next option             |
+| `ArrowUp`   | Open menu (focus last) or move to previous option          |
+| `Enter`     | Select focused option / create custom option / submit form |
+| `Escape`    | Close menu                                                 |
+| `Home`      | Focus first option                                         |
+| `End`       | Focus last option                                          |
+| `Backspace` | Clear/remove selection (when input empty)                  |
+| `Space`     | Type space character (not used for selection)              |
+
+### Screen Reader Support
+
+- Input announces role, state, and value
+- Focused options announced via `aria-activedescendant`
+- Selection changes announced
+- Loading states announced
+- Empty states announced
+- Error states announced
+
+### Focus Management
+
+- **Virtual Focus**: Browser focus stays on input, options receive visual focus
+  via `aria-activedescendant`
+- **Focus Ring**: Visible focus indicators on input and focused options
+- **Focus Trap**: No keyboard traps - user can always Tab out
+- **Focus Restoration**: Focus returns to trigger when menu closes
+
+## Performance Considerations
+
+### Memoization
+
+- **filteredCollection**: Memoized with `useMemo` to avoid re-filtering on every
+  render
+- **selectedItemsFromState**: Memoized to avoid re-extracting selected items
+- **Context Values**: Individual contexts use object literals (React handles
+  efficiently)
+
+### Collection Filtering
+
+Uses `Collection.filter()` instead of array filtering:
+
+- **Why**: Preserves navigation methods (getFirstKey, getLastKey, etc.)
+- **Benefit**: React Aria can navigate filtered collection without re-parsing
+  JSX
+
+### ResizeObserver
+
+Watches trigger width to keep popover width in sync:
+
+- **Why**: Ensures popover aligns with trigger when container resizes
+- **How**: CSS custom property `--nimbus-combobox-trigger-width` set via effect
+- **Cleanup**: Observer cleaned up on unmount
+
+### Virtual Scrolling
+
+Not currently implemented, but can be added for very large datasets (1000+
+items):
+
+- Use React Aria's
+  [virtualizer](https://react-spectrum.adobe.com/react-aria/Virtualizer.html#virtualizer)
+  as the parent of `ComboBox.ListBox`
+
+## Testing
+
+### Test Coverage
+
+The component has comprehensive test coverage across utilities and integration:
+
+**Unit Tests** (utilities):
+
+- `utils/collection.spec.ts` - Collection utilities
+- `utils/filters.spec.ts` - All filter functions
+- `utils/selection.spec.ts` - Selection utilities
+
+**Integration Tests** (Storybook stories with play functions):
+
+- Single-select interaction
+- Multi-select interaction with tags
+- Keyboard navigation
+- Custom option creation
+- Filtering behavior (sections, custom filters)
+- Async loading (with success and error states)
+- Form submission
+- Leading elements
+- Empty states
+- All visual states (size, variant, disabled, readonly, invalid, required)
+
+### Running Tests
+
+```bash
+# Run all tests (unit + Storybook)
+pnpm test
+
+# Run only unit tests
+pnpm test:unit
+
+# Run only Storybook tests
+pnpm test:storybook
+
+# Run specific test file
+pnpm test combobox.stories.tsx
+pnpm test filters.spec.ts
+```
+
+### Test Documentation
+
+See `TESTING_PLAN.md` for a comprehensive testing checklist covering:
+
+- Visual & layout behavior
+- User interaction testing
+- Selection modes
+- Search & filtering
+- Custom option creation
+- Async data loading
+- State management
+- Accessibility
+- Form integration
+- Visual states (size, variant, disabled, readonly, invalid, required)
+- Edge cases & robustness
+- Portal & positioning
+- Regression prevention
+
+## Future Enhancements
+
+- [ ] Infinite scroll/virtualization for very large datasets (1000+ items)
+- [ ] Virtual scrolling with React Aria's `Virtualizer`
+- [ ] Drag-and-drop reordering of selected tags
+- [ ] Copy/paste multiple values
+- [ ] Directly access selected values via callback
diff --git a/packages/nimbus/src/components/combobox/combobox.i18n.ts b/packages/nimbus/src/components/combobox/combobox.i18n.ts
index a53357884..f6bee22d4 100644
--- a/packages/nimbus/src/components/combobox/combobox.i18n.ts
+++ b/packages/nimbus/src/components/combobox/combobox.i18n.ts
@@ -1,34 +1,24 @@
 import { defineMessages } from "react-intl";
 
 export const messages = defineMessages({
-  comboboxDialog: {
-    id: "Nimbus.ComboBox.comboboxDialog",
-    description: "aria-label for the combobox dialog overlay",
-    defaultMessage: "Combobox dialog",
-  },
-  filterOptions: {
-    id: "Nimbus.ComboBox.filterOptions",
-    description: "aria-label for the combobox filter input field",
-    defaultMessage: "Filter combobox options",
+  clearSelection: {
+    id: "Nimbus.ComboBox.clearSelection",
+    description: "aria-label for clear selection button in ComboBox",
+    defaultMessage: "Clear selection",
   },
-  options: {
-    id: "Nimbus.ComboBox.options",
-    description: "aria-label for the combobox options list",
-    defaultMessage: "Combobox options",
+  toggleOptions: {
+    id: "Nimbus.ComboBox.toggleOptions",
+    description: "aria-label for toggle button to open/close options",
+    defaultMessage: "Toggle options",
   },
   selectedValues: {
     id: "Nimbus.ComboBox.selectedValues",
-    description: "aria-label for the selected values tag group in multi-select",
+    description: "aria-label for selected values tag group",
     defaultMessage: "Selected values",
   },
-  clearSelection: {
-    id: "Nimbus.ComboBox.clearSelection",
-    description: "aria-label for the clear selection button",
-    defaultMessage: "Clear selection",
-  },
-  toggleCombobox: {
-    id: "Nimbus.ComboBox.toggleCombobox",
-    description: "aria-label for the combobox toggle button",
-    defaultMessage: "Toggle combobox",
+  options: {
+    id: "Nimbus.ComboBox.options",
+    description: "aria-label for combobox menu options",
+    defaultMessage: "Options menu",
   },
 });
diff --git a/packages/nimbus/src/components/combobox/combobox.mdx b/packages/nimbus/src/components/combobox/combobox.mdx
index c54153cac..a65c931eb 100644
--- a/packages/nimbus/src/components/combobox/combobox.mdx
+++ b/packages/nimbus/src/components/combobox/combobox.mdx
@@ -46,26 +46,36 @@ const App = () => {
 
   return (
     <Stack direction="horizontal" gap="400" alignItems="flex-start">
-      <ComboBox.Root size="md" defaultItems={options} placeholder="Search...">
-        {(item) => (
-          <ComboBox.Option id={item.id} textValue={item.name}>
-            <Stack gap="100">
-              <Text textStyle="sm">{item.name}</Text>
-              <Text textStyle="xs" color="neutral.11">{item.description}</Text>
-            </Stack>
-          </ComboBox.Option>
-        )}
+      <ComboBox.Root size="md" items={options} placeholder="Search...">
+        <ComboBox.Trigger />
+        <ComboBox.Popover>
+          <ComboBox.ListBox>
+            {(item) => (
+              <ComboBox.Option id={item.id} textValue={item.name}>
+                <Stack gap="100">
+                  <Text textStyle="sm">{item.name}</Text>
+                  <Text textStyle="xs" color="neutral.11">{item.description}</Text>
+                </Stack>
+              </ComboBox.Option>
+            )}
+          </ComboBox.ListBox>
+        </ComboBox.Popover>
       </ComboBox.Root>
       
-      <ComboBox.Root size="sm" defaultItems={options} placeholder="Search...">
-        {(item) => (
-          <ComboBox.Option id={item.id} textValue={item.name}>
-            <Stack gap="100">
-              <Text textStyle="sm">{item.name}</Text>
-              <Text textStyle="xs" color="neutral.11">{item.description}</Text>
-            </Stack>
-          </ComboBox.Option>
-        )}
+      <ComboBox.Root size="sm" items={options} placeholder="Search...">
+        <ComboBox.Trigger />
+        <ComboBox.Popover>
+          <ComboBox.ListBox>
+            {(item) => (
+              <ComboBox.Option id={item.id} textValue={item.name}>
+                <Stack gap="100">
+                  <Text textStyle="sm">{item.name}</Text>
+                  <Text textStyle="xs" color="neutral.11">{item.description}</Text>
+                </Stack>
+              </ComboBox.Option>
+            )}
+          </ComboBox.ListBox>
+        </ComboBox.Popover>
       </ComboBox.Root>
     </Stack>
   )
@@ -86,26 +96,36 @@ const App = () => {
 
   return (
     <Stack direction="horizontal" gap="400" alignItems="flex-start">
-      <ComboBox.Root variant="solid" defaultItems={options} placeholder="Search...">
-        {(item) => (
-          <ComboBox.Option id={item.id} textValue={item.name}>
-            <Stack gap="100">
-              <Text textStyle="sm">{item.name}</Text>
-              <Text textStyle="xs" color="neutral.11">{item.description}</Text>
-            </Stack>
-          </ComboBox.Option>
-        )}
+      <ComboBox.Root variant="solid" items={options} placeholder="Search...">
+        <ComboBox.Trigger />
+        <ComboBox.Popover>
+          <ComboBox.ListBox>
+            {(item) => (
+              <ComboBox.Option id={item.id} textValue={item.name}>
+                <Stack gap="100">
+                  <Text textStyle="sm">{item.name}</Text>
+                  <Text textStyle="xs" color="neutral.11">{item.description}</Text>
+                </Stack>
+              </ComboBox.Option>
+            )}
+          </ComboBox.ListBox>
+        </ComboBox.Popover>
       </ComboBox.Root>
       
-      <ComboBox.Root variant="ghost" defaultItems={options} placeholder="Search...">
-        {(item) => (
-          <ComboBox.Option id={item.id} textValue={item.name}>
-            <Stack gap="100">
-              <Text textStyle="sm">{item.name}</Text>
-              <Text textStyle="xs" color="neutral.11">{item.description}</Text>
-            </Stack>
-          </ComboBox.Option>
-        )}
+      <ComboBox.Root variant="ghost" items={options} placeholder="Search...">
+        <ComboBox.Trigger />
+        <ComboBox.Popover>
+          <ComboBox.ListBox>
+            {(item) => (
+              <ComboBox.Option id={item.id} textValue={item.name}>
+                <Stack gap="100">
+                  <Text textStyle="sm">{item.name}</Text>
+                  <Text textStyle="xs" color="neutral.11">{item.description}</Text>
+                </Stack>
+              </ComboBox.Option>
+            )}
+          </ComboBox.ListBox>
+        </ComboBox.Popover>
       </ComboBox.Root>
     </Stack>
   )
@@ -126,24 +146,30 @@ const App = () => {
 
   return (
     <Stack direction="horizontal" gap="400" alignItems="flex-start">
-      <ComboBox.Root defaultItems={options} placeholder="Search...">
-        {(item) => (
-          <ComboBox.Option id={item.id} textValue={item.name}>
-            <Stack gap="100">
-              <Text textStyle="sm">{item.name}</Text>
-              <Text textStyle="xs" color="neutral.11">{item.description}</Text>
-            </Stack>
-          </ComboBox.Option>
-        )}
+      <ComboBox.Root items={options} placeholder="Search...">
+        <ComboBox.Trigger />
+        <ComboBox.Popover>
+        <ComboBox.ListBox>
+          {(item) => (
+            <ComboBox.Option id={item.id} textValue={item.name}>
+              <Stack gap="100">
+                <Text textStyle="sm">{item.name}</Text>
+                <Text textStyle="xs" color="neutral.11">{item.description}</Text>
+              </Stack>
+            </ComboBox.Option>
+              )}
+          </ComboBox.ListBox>
+        </ComboBox.Popover>
       </ComboBox.Root>
-      
-      <ComboBox.Root 
+
+      <ComboBox.Root
         selectionMode="multiple"
-        defaultItems={options} 
+        items={options}
         placeholder="Search..."
-        itemId="id"
-        itemValue="name"
       >
+        <ComboBox.Trigger />
+        <ComboBox.Popover>
+          <ComboBox.ListBox>
         {(item) => (
           <ComboBox.Option id={item.id} textValue={item.name}>
             <Stack gap="100">
@@ -151,13 +177,118 @@ const App = () => {
               <Text textStyle="xs" color="neutral.11">{item.description}</Text>
             </Stack>
           </ComboBox.Option>
-        )}
+            )}
+          </ComboBox.ListBox>
+        </ComboBox.Popover>
       </ComboBox.Root>
     </Stack>
   )
 }
 ```
 
+### Async Loading
+
+ComboBox supports async data loading by managing the async state externally using React Stately's `useAsyncList` hook. This pattern gives you full control over data fetching and works seamlessly with ComboBox's filtering and selection features.
+
+**Use cases:**
+- Loading large datasets on demand
+- Providing search suggestions from a server
+- Fetching filtered results based on user input
+
+```jsx-live
+const App = () => {
+  const [error, setError] = useState(null);
+  const minSearchLength = 2;
+
+  // Manage async data loading with useAsyncList
+  const list = useAsyncList({
+    async load({ signal, filterText }) {
+      setError(null);
+
+      // Don't load if below minimum search length
+      if (!filterText || filterText.length < minSearchLength) {
+        return { items: [] };
+      }
+
+      try {
+        const response = await fetch(
+          `https://swapi.py4e.com/api/people/?search=${encodeURIComponent(filterText)}`,
+          { signal }
+        );
+
+        if (!response.ok) {
+          throw new Error(`HTTP error! status: ${response.status}`);
+        }
+
+        const data = await response.json();
+        return { items: data.results || [] };
+      } catch (err) {
+        if (err.name === "AbortError") {
+          throw err;
+        }
+        setError(err.message);
+        return { items: [] };
+      }
+    }
+  });
+
+  // Add debouncing to reduce API calls while typing
+  const debouncedSetFilterText = useDebouncedCallback(
+    (value) => {
+      list.setFilterText(value);
+    },
+    300
+  );
+
+  return (
+    <FormField.Root invalid={!!error}>
+      <ComboBox.Root
+        label="Search Star Wars Characters"
+        placeholder="Type to search (min 2 characters)..."
+        items={list.items}
+        inputValue={list.filterText}
+        onInputChange={debouncedSetFilterText}
+        isLoading={list.loadingState === "loading"}
+        renderEmptyState={({ isLoading }) => {
+          if (isLoading) {
+            return <Text padding="300">Loading...</Text>;
+          }
+          if (!list.filterText || list.filterText.length < minSearchLength) {
+            return <Text padding="300">Type at least {minSearchLength} characters to search</Text>;
+          }
+          return <Text padding="300">No results found</Text>;
+        }}
+      >
+        <ComboBox.Trigger />
+        <ComboBox.Popover>
+          <ComboBox.ListBox>
+            {(character) => (
+              <ComboBox.Option textValue={character.name}>
+                <Stack gap="100">
+                  <Text textStyle="sm">{character.name}</Text>
+                  <Text textStyle="xs" color="neutral.11">
+                    {character.gender} • Born {character.birth_year}
+                  </Text>
+                </Stack>
+              </ComboBox.Option>
+            )}
+          </ComboBox.ListBox>
+        </ComboBox.Popover>
+      </ComboBox.Root>
+      {error && <FormField.ErrorMessage>{error}</FormField.ErrorMessage>}
+    </FormField.Root>
+  );
+};
+```
+
+**Key features of this pattern:**
+- **External State Management:** Full control over async logic using React Stately's `useAsyncList`
+- **Debouncing:** Use `useDebouncedCallback` from `use-debounce` to reduce API calls while typing
+- **Minimum Search Length:** Implement custom validation in the `load` function
+- **Automatic Cancellation:** `useAsyncList` cancels previous requests via AbortSignal
+- **Loading States:** Access `list.loadingState` to display loading indicators
+- **Error Handling:** Manage errors in your `load` function with full control
+
 ## Guidelines
 
 A combobox combines a text input with a dropdown list, allowing users to type a value or select from predefined options.
@@ -248,25 +379,61 @@ const App = () => {
   return (
     <ComboBox.Root 
       selectionMode="multiple"
-      defaultItems={options} 
+      items={options} 
       placeholder="Search..."
       aria-label="Food category selection"
       isRequired
     >
-      {(item) => (
-        <ComboBox.Option id={item.id} textValue={item.name}>
-          <Stack gap="100">
-            <Text textStyle="sm">{item.name}</Text>
-            <Text textStyle="xs" color="neutral.11">{item.description}</Text>
-          </Stack>
-        </ComboBox.Option>
-      )}
+      <ComboBox.Trigger />
+      <ComboBox.Popover>
+        <ComboBox.ListBox>
+          {(item) => (
+            <ComboBox.Option id={item.id} textValue={item.name}>
+              <Stack gap="100">
+                <Text textStyle="sm">{item.name}</Text>
+                <Text textStyle="xs" color="neutral.11">{item.description}</Text>
+              </Stack>
+            </ComboBox.Option>
+          )}
+        </ComboBox.ListBox>
+      </ComboBox.Popover>
     </ComboBox.Root>
   )
 }
 ```
 
-### Accessibility standards
+## Specs
+
+<PropsTable id="ComboBox" />
+
+## Accessibility
+
+This component is built with React Aria and follows WCAG 2.1 AA guidelines.
+
+### Keyboard Navigation
+
+| Key          | Action                                      |
+| ------------ | ------------------------------------------- |
+| `Tab`        | Move focus to/from combobox                 |
+| `Enter`      | Select highlighted option or create custom option |
+| `Space`      | Toggle popover open/closed when focused     |
+| `ArrowDown`  | Move focus to next option                   |
+| `ArrowUp`    | Move focus to previous option               |
+| `Home`       | Move focus to first option                  |
+| `End`        | Move focus to last option                   |
+| `Escape`     | Close popover and clear focus               |
+| `Backspace`  | Remove last selected tag (multi-select mode) |
+
+### Screen Reader Support
+
+- Properly announces combobox role and state
+- Announces open/closed state of popover
+- Announces selected options
+- Announces filter results count
+- Announces loading state
+- Provides descriptive labels for all interactive elements
+
+### Accessibility Standards
 
 - Always provide a visible label for the input.
 - If a visible label is not used, provide an `aria-label` or `aria-labelledby` for screen readers.
diff --git a/packages/nimbus/src/components/combobox/combobox.recipe.ts b/packages/nimbus/src/components/combobox/combobox.recipe.ts
index f6d92dca7..624922dec 100644
--- a/packages/nimbus/src/components/combobox/combobox.recipe.ts
+++ b/packages/nimbus/src/components/combobox/combobox.recipe.ts
@@ -1,5 +1,4 @@
 import { defineSlotRecipe } from "@chakra-ui/react/styled-system";
-import { selectSlotRecipe } from "../select/select.recipe";
 import { checkboxSlotRecipe } from "../checkbox/checkbox.recipe";
 
 /**
@@ -9,13 +8,14 @@ import { checkboxSlotRecipe } from "../checkbox/checkbox.recipe";
 export const comboBoxSlotRecipe = defineSlotRecipe({
   slots: [
     "root",
-    "value",
+    "trigger",
     "leadingElement",
-    "buttonGroup",
+    "content",
+    "tagGroup",
+    "input",
     "popover",
-    "multiSelectInput",
-    "options",
-    "optionGroup",
+    "listBox",
+    "section",
     "option",
     "optionIndicator",
     "optionContent",
@@ -26,17 +26,12 @@ export const comboBoxSlotRecipe = defineSlotRecipe({
   // Base styles applied to all instances of the component
   base: {
     root: {
-      "--leading-element-width": "sizes.200",
       colorPalette: "primary",
-      focusRing: "outside",
       display: "inline-flex",
       position: "relative",
       alignSelf: "flex-start",
       maxWidth: "100%",
       borderRadius: "200",
-      _hover: {
-        bg: "primary.2",
-      },
       "&[data-disabled='true']": {
         layerStyle: "disabled",
         focusRing: "none",
@@ -47,90 +42,157 @@ export const comboBoxSlotRecipe = defineSlotRecipe({
           pointerEvents: "none!",
         },
       },
-      "& input": {
-        cursor: "text",
-        _hover: {
-          bg: "primary.2",
-        },
-        _placeholder: { opacity: 0.5 },
-      },
       "& [data-placeholder]": {
         opacity: 0.5,
       },
     },
     leadingElement: {
-      position: "absolute",
-      display: "flex",
+      gridArea: "leadingElement",
+      display: "contents",
       alignItems: "center",
+      justifyContent: "center",
       color: "neutral.11",
+      "& svg": {
+        minH: "600",
+        minW: "600",
+        pr: "100",
+      },
     },
-    value: {
-      display: "flex",
+    trigger: {
+      display: "grid",
+      gridTemplateColumns: "auto 1fr auto auto",
+      gridTemplateAreas: '"leadingElement content clear toggle"',
+      alignItems: "center",
+      gap: "100",
+      width: "100%",
       focusRing: "outside",
-      alignItems: "flex-start",
-      pr: "1600",
-      pl: "400",
+      px: "300",
       py: "100",
       borderRadius: "200",
       color: "neutral.12",
-      maxWidth: "100%",
       textAlign: "left",
-      whiteSpace: "nowrap",
-      overflow: "hidden",
-      textOverflow: "ellipsis",
       boxShadow: "inset 0 0 0 var(--border-width) var(--border-color)",
+
+      _focusWithin: {
+        layerStyle: "focusRing",
+      },
       _disabled: { pointerEvents: "none" },
       '[data-invalid="true"] &': {
         "--border-width": "sizes.50",
         "--border-color": "colors.critical.7",
         color: "critical.11",
       },
-      '& button[slot="remove"]': {
+      '& button[slot="toggle"]': {
+        gridArea: "toggle",
+        alignSelf: "center",
+      },
+      '& button[slot="clear"]': {
+        gridArea: "clear",
+        alignSelf: "center",
+        mr: "-100",
         _expanded: {
           bg: "colorPalette.3",
         },
       },
     },
-    buttonGroup: {
-      position: "absolute",
-      display: "inline-flex",
-      top: 0,
-      bottom: 0,
-      right: 300,
-      my: "auto",
+    content: {
+      gridArea: "content",
+      display: "flex",
+      flexWrap: "wrap",
+      alignItems: "center",
+      gap: "100",
+      minWidth: 0,
+      cursor: "text",
+      "[data-disabled='true'] &": {
+        pointerEvents: "none",
+      },
+    },
+    tagGroup: {
+      display: "contents",
+    },
+    input: {
+      flex: "0 0 auto",
+      minWidth: "0",
+      maxWidth: "100%",
+      border: "none",
+      outline: "none",
+      bg: "transparent",
+      padding: 0,
+
+      // If the value & placeholder are falsy, input width should be 1px
+      // so it doesn't cause a blank line in content box
+      '&[data-empty="true"]': {
+        width: "25",
+      },
+      _hover: {
+        bg: "primary.2",
+      },
+      _placeholder: { opacity: 0.5 },
     },
     popover: {
       bg: "bg",
       borderRadius: "200",
       boxShadow: "5",
+      minWidth: "var(--nimbus-combobox-trigger-width)",
+      overflow: "hidden",
+      padding: 0,
     },
-    multiSelectInput: {
-      "& input": {
-        py: "300",
-        px: "400",
-        focusRing: "none",
-        borderBottom: "solid 1px",
-        borderBottomColor: "neutral.3",
-        bg: "transparent",
-        w: "100%",
-        overflow: "hidden",
-        textOverflow: "ellipsis",
-        fontSize: "350",
-        fontWeight: "400",
-        lineHeight: "400",
-        _placeholder: { opacity: 0.5 },
-      },
-    },
-    options: {
-      ...selectSlotRecipe.base?.options,
+    listBox: {
+      "--scrollbar-color": "colors.neutral.8",
+      "--scrollbar-bg": "colors.neutral.3",
       gap: "100",
+      padding: "200",
+      focusRing: "outside",
+
+      maxH: "40svh",
+      overflowY: "auto",
+      scrollbarWidth: "thin",
+      scrollbarColor: "var(--scrollbar-color) var(--scrollbar-bg)",
     },
-    optionGroup: {
-      ...selectSlotRecipe.base?.optionGroup,
+    section: {
+      textStyle: "xs",
+      color: "neutral.11",
+      fontWeight: "600",
+      lineHeight: "350",
+      letterSpacing: "25",
+      textTransform: "uppercase",
+      p: "200",
+      borderBottom: "solid-25",
+      borderColor: "neutral.3",
+      mx: "-200",
+      mt: "200",
+      mb: "300",
     },
     option: {
-      ...selectSlotRecipe.base?.option,
+      focusRing: "outside",
+      cursor: "menuitem",
+      color: "neutral.12",
+      textStyle: "sm",
+      padding: "200",
+      borderRadius: "200",
       whiteSpace: "wrap",
+      overflow: "hidden",
+      textOverflow: "ellipsis",
+
+      '&[aria-selected="true"]': {
+        bg: "primary.3",
+      },
+      '&[data-focused="true"]': {
+        bg: "primary.2",
+      },
+      '& [slot="label"]': {
+        display: "block",
+      },
+
+      '& [slot="description"]': {
+        display: "block",
+        color: "neutral.11",
+        textStyle: "xs",
+      },
+
+      "&[data-disabled='true']": {
+        layerStyle: "disabled",
+      },
     },
     optionIndicator: {
       // make sure option is aligned with the first line of text (using lh units)
@@ -157,26 +219,22 @@ export const comboBoxSlotRecipe = defineSlotRecipe({
     size: {
       // Small
       sm: {
-        value: {
+        trigger: {
           minH: "800",
           textStyle: "sm",
-          pl: "calc(var(--leading-element-width) + {sizes.100})",
         },
         leadingElement: {
           minH: "800",
-          pl: "300",
         },
       },
       // Medium
       md: {
-        value: {
+        trigger: {
           minH: "1000",
           textStyle: "md",
-          pl: "calc(var(--leading-element-width) + {sizes.200})",
         },
         leadingElement: {
           minH: "1000",
-          pl: "400",
         },
       },
     },
@@ -184,22 +242,32 @@ export const comboBoxSlotRecipe = defineSlotRecipe({
     variant: {
       solid: {
         root: {
+          bg: "primary.1",
+          "&:hover:not([data-disabled='true'])": {
+            bg: "primary.2",
+          },
           width: "7200",
         },
-        value: {
-          ...selectSlotRecipe.variants?.variant.outline.trigger,
+        trigger: {
+          "--border-width": "sizes.25",
+          "--border-color": "colors.neutral.7",
+
           width: "100%",
         },
       },
       ghost: {
         root: {
-          ...selectSlotRecipe.variants?.variant.ghost.root,
-          maxW: "7200",
+          bg: "transparent",
+          "&:hover:not([data-disabled='true'])": {
+            bg: "primaryAlpha.2",
+          },
+          width: "7200",
         },
-
-        value: {
-          ...selectSlotRecipe.variants?.variant.ghost.trigger,
+        trigger: {
+          "--border-width": "sizes.25",
+          "--border-color": "transparent",
           bg: "transparent",
+          width: "100%",
         },
       },
     },
@@ -230,7 +298,6 @@ export const comboBoxSlotRecipe = defineSlotRecipe({
             bg: "unset",
           },
           '&[data-focused="true"]': {
-            // TODO: can't use focusRing prop, find other solution (helper, util, etc.)
             outlineWidth: "var(--focus-ring-width)",
             outlineColor: "var(--focus-ring-color)",
             outlineStyle: "var(--focus-ring-style)",
@@ -266,7 +333,7 @@ export const comboBoxSlotRecipe = defineSlotRecipe({
             },
           },
         },
-        options: {
+        listBox: {
           width: "var(--trigger-width)",
         },
       },
@@ -285,13 +352,9 @@ export const comboBoxSlotRecipe = defineSlotRecipe({
       variant: "ghost",
       selectionMode: "single",
       css: {
-        value: {
+        trigger: {
           flex: "1 1 auto",
         },
-        options: {
-          minW: "max(var(--trigger-width), {sizes.2000})",
-          maxW: "max(var(--trigger-width), {sizes.7200})",
-        },
       },
     },
   ],
diff --git a/packages/nimbus/src/components/combobox/combobox.slots.tsx b/packages/nimbus/src/components/combobox/combobox.slots.tsx
index 49d08fec7..e2ba825e1 100644
--- a/packages/nimbus/src/components/combobox/combobox.slots.tsx
+++ b/packages/nimbus/src/components/combobox/combobox.slots.tsx
@@ -1,92 +1,92 @@
-import {
-  createSlotRecipeContext,
-  type HTMLChakraProps,
-} from "@chakra-ui/react";
-import type { SlotComponent } from "@/type-utils";
+import { createSlotRecipeContext } from "@chakra-ui/react";
+
 import type {
-  ComboBoxValueSlotProps,
-  ComboBoxButtonGroupSlotProps,
+  ComboBoxRootSlotProps,
+  ComboBoxTriggerSlotProps,
+  ComboBoxLeadingElementSlotProps,
+  ComboBoxContentSlotProps,
+  ComboBoxTagGroupSlotProps,
+  ComboBoxInputSlotProps,
   ComboBoxPopoverSlotProps,
-  ComboBoxMultiSelectInputSlotProps,
+  ComboBoxListBoxSlotProps,
+  ComboBoxSectionSlotProps,
+  ComboBoxOptionSlotProps,
   ComboBoxOptionIndicatorSlotProps,
   ComboBoxOptionContentSlotProps,
-  ComboBoxMultiSelectRootSlotProps,
-  ComboBoxSingleSelectRootSlotProps,
-  ComboBoxOptionGroupSlotProps,
-  ComboBoxOptionSlotProps,
-  ComboBoxOptionsSlotProps,
 } from "./combobox.types";
 
 const { withProvider, withContext } = createSlotRecipeContext({
   key: "combobox",
 });
 
-// ComboBox Root
-export const ComboBoxRootSlot: SlotComponent<
+// Root slot - container for entire combobox (provides recipe context)
+export const ComboBoxRootSlot = withProvider<
   HTMLDivElement,
-  | ComboBoxMultiSelectRootSlotProps<object>
-  | ComboBoxSingleSelectRootSlotProps<object>
-> = withProvider<
-  HTMLDivElement,
-  | ComboBoxMultiSelectRootSlotProps<object>
-  | ComboBoxSingleSelectRootSlotProps<object>
+  ComboBoxRootSlotProps
 >("div", "root");
 
+// Trigger slot - container for input trigger area (input + tags + buttons)
+export const ComboBoxTriggerSlot = withContext<
+  HTMLDivElement,
+  ComboBoxTriggerSlotProps
+>("div", "trigger");
+
+// LeadingElement slot - wrapper for leading element (icon, etc.)
 export const ComboBoxLeadingElementSlot = withContext<
   HTMLDivElement,
-  HTMLChakraProps<"div">
+  ComboBoxLeadingElementSlotProps
 >("div", "leadingElement");
 
-// Value - Input (single) or TagList (multi)
-export const ComboBoxValueSlot = withContext<
+// Content slot - wrapper for tags and input (flex container within grid)
+export const ComboBoxContentSlot = withContext<
   HTMLDivElement,
-  ComboBoxValueSlotProps
->("div", "value");
+  ComboBoxContentSlotProps
+>("div", "content");
 
-// ButtonGroup - Dropdown Indicator and Clear Button
-export const ComboBoxButtonGroupSlot = withContext<
+// TagGroup slot - container for selected tags (multi-select)
+export const ComboBoxTagGroupSlot = withContext<
   HTMLDivElement,
-  ComboBoxButtonGroupSlotProps
->("div", "buttonGroup");
+  ComboBoxTagGroupSlotProps
+>("div", "tagGroup");
 
-// Popover container (multi-select)
-export const ComboBoxPopoverSlot: SlotComponent<
+// Input slot - wrapper for React Aria Input component
+export const ComboBoxInputSlot = withContext<
   HTMLDivElement,
-  ComboBoxPopoverSlotProps
-> = withContext<HTMLDivElement, ComboBoxPopoverSlotProps>("div", "popover");
+  ComboBoxInputSlotProps
+>("div", "input");
 
-// Multi-select input (in popover)
-export const ComboBoxMultiSelectInputSlot = withContext<
-  HTMLInputElement,
-  ComboBoxMultiSelectInputSlotProps
->("input", "multiSelectInput");
+// Popover slot - wrapper for popover containing listbox
+export const ComboBoxPopoverSlot = withContext<
+  HTMLDivElement,
+  ComboBoxPopoverSlotProps
+>("div", "popover");
 
-// Options - ListBox
-export const ComboBoxOptionsSlot = withContext<
+// ListBox slot - wrapper for React Aria ListBox (used by ComboBox.ListBox component)
+export const ComboBoxListBoxSlot = withContext<
   HTMLDivElement,
-  ComboBoxOptionsSlotProps
->("div", "options");
+  ComboBoxListBoxSlotProps
+>("div", "listBox");
 
-// OptionGroup - ListBoxSection
-export const ComboBoxOptionGroupSlot = withContext<
+// Section slot - section grouping wrapper (wraps React Aria Section)
+export const ComboBoxSectionSlot = withContext<
   HTMLDivElement,
-  ComboBoxOptionGroupSlotProps
->("div", "optionGroup");
+  ComboBoxSectionSlotProps
+>("div", "section");
 
-// Option - ListBoxItem
+// Option slot - individual option wrapper (wraps React Aria ListBoxItem)
 export const ComboBoxOptionSlot = withContext<
   HTMLDivElement,
   ComboBoxOptionSlotProps
 >("div", "option");
 
-// Option indicator (multi) - selected indicator
+// Option indicator slot - checkbox/checkmark indicator for multi-select
 export const ComboBoxOptionIndicatorSlot = withContext<
-  HTMLSpanElement,
+  HTMLDivElement,
   ComboBoxOptionIndicatorSlotProps
->("span", "optionIndicator");
+>("div", "optionIndicator");
 
-// Option content (multi)
+// Option content slot - wrapper for option text content
 export const ComboBoxOptionContentSlot = withContext<
-  HTMLSpanElement,
+  HTMLDivElement,
   ComboBoxOptionContentSlotProps
->("span", "optionContent");
+>("div", "optionContent");
diff --git a/packages/nimbus/src/components/combobox/combobox.stories.tsx b/packages/nimbus/src/components/combobox/combobox.stories.tsx
index 3d1871b37..8d1b50107 100644
--- a/packages/nimbus/src/components/combobox/combobox.stories.tsx
+++ b/packages/nimbus/src/components/combobox/combobox.stories.tsx
@@ -1,160 +1,41 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { useState, useCallback, useMemo, type FormEvent } from "react";
-import { type Key, type Selection } from "react-aria-components";
-import { useAsyncList } from "react-stately";
+import { useState, useCallback } from "react";
+import { userEvent, within, expect, waitFor } from "storybook/test";
+import { Box, Dialog, FormField, Stack, Text } from "@commercetools/nimbus";
+import { Search } from "@commercetools/nimbus-icons";
+import { ComboBox } from "./combobox";
+import { type SimpleOption, simpleOptions } from "./utils/test-data";
 import {
-  userEvent,
-  fireEvent,
-  within,
-  expect,
-  fn,
-  waitFor,
-} from "storybook/test";
-import {
-  Box,
-  Button,
-  ComboBox,
-  type ComboBoxRootProps,
-  Flex,
-  FormField,
-  Icon,
-  RadioInput,
-  Stack,
-  Text,
-} from "@commercetools/nimbus";
-import { AddReaction, Search } from "@commercetools/nimbus-icons";
-
-/**
- * Storybook metadata configuration
- * - title: determines the location in the sidebar
- * - component: references the component being documented
- */
-const meta: Meta<typeof ComboBox.Root> = {
-  title: "Components/ComboBox",
-  component: ComboBox.Root,
-};
-
-export default meta;
-
-/**
- * Story type for TypeScript support
- * StoryObj provides type checking for our story configurations
- */
-type Story = StoryObj<typeof ComboBox.Root>;
+  ComposedComboBox,
+  type Pokemon,
+  PokemonOption,
+} from "./utils/test-utils";
 
-const options = [
-  { id: 1, name: "Koala" },
-  { id: 2, name: "Kangaroo" },
-  { id: 3, name: "Platypus" },
-  { id: 4, name: "Bald Eagle with a very long name hooray" },
-  { id: 5, name: "Bison" },
-  { id: 6, name: "Skunk" },
-];
-
-const sectionedItems = [
-  {
-    name: "Fruits",
-    id: "fruit",
-    children: [
-      { id: 1, name: "Apple" },
-      { id: 2, name: "Banana" },
-      { id: 6, name: "Orange" },
-    ],
-  },
-  {
-    name: "Vegetables",
-    id: "veg",
-    children: [
-      { id: 3, name: "Carrot" },
-      { id: 4, name: "Broccoli" },
-      { id: 5, name: "Avocado" },
-      { id: 7, name: "Cucumber" },
-    ],
-  },
-];
-
-// Type definitions for complex options
-type PlanOption = {
-  uuid: number;
-  type: string;
-  description: string;
-  price: string;
-  features: string[];
-};
-
-type PlanGroup = {
-  name: string;
-  id: string;
-  children: PlanOption[];
-};
-
-const complexOptionsWithGroups: PlanGroup[] = [
-  {
-    name: "Individual Plans",
-    id: "indplans",
-    children: [
-      {
-        uuid: 3,
-        type: "Starter Plan",
-        description: "Great for individuals and small projects",
-        price: "$9/month",
-        features: ["Up to 3 projects", "Community support", "Basic features"],
-      },
-      {
-        uuid: 1,
-        type: "Premium Plan",
-        description: "Full access to all features with priority support",
-        price: "$29/month",
-        features: ["Unlimited projects", "24/7 support", "Advanced analytics"],
-      },
-    ],
-  },
-  {
-    name: "Business Plans",
-    id: "busplans",
-    children: [
-      {
-        uuid: 2,
-        type: "Small Team Plan",
-        description: "Perfect for growing teams and businesses",
-        price: "$19/month",
-        features: ["Up to 10 projects", "Email support", "Basic analytics"],
-      },
-      {
-        uuid: 4,
-        type: "Enterprise Plan",
-        description: "Customized solution for large organizations",
-        price: "Custom pricing",
-        features: [
-          "Unlimited everything",
-          "Dedicated support",
-          "Custom integrations",
-        ],
-      },
-    ],
-  },
-];
+// Helper functions to reduce test verbosity - should be here since storybook has problems with importing RTL methods from other files
 
-// Helper functions to reduce test verbosity
-const getTagList = async (multiSelect: HTMLElement) =>
-  await within(multiSelect).findByLabelText(/selected values/i);
+/** Gets all tags */
+const getTagList = async (comboBox: HTMLElement) =>
+  await within(comboBox).findByLabelText(/selected values/i);
 
-const getFilterInput = () =>
-  document.querySelector(
-    '[aria-label="Filter combobox options"]'
-  ) as HTMLInputElement;
+/**  Gets the listbox - uses document.querySelector since the portal is not in the canvas */
+const getListBox = (document: Document) =>
+  document.querySelector('[role="listbox"]');
 
+/** Gets all options - uses document.querySelectorAll since the portal is not in the canvas */
 const getListboxOptions = () => document.querySelectorAll('[role="option"]');
 
+/** Finds a specific option by its textValue  */
 const findOptionByText = (text: string) =>
   Array.from(getListboxOptions()).find((option) =>
     option.textContent?.includes(text)
   );
 
+/** Returns whether an option is selected */
 const isOptionSelected = (option: Element | undefined) =>
   option?.getAttribute("aria-selected") === "true" ||
   option?.getAttribute("data-selected") === "true";
 
+/** Selects options specified in optionNames array */
 const selectOptionsByName = async (optionNames: string[]) => {
   for (const optionName of optionNames) {
     const option = findOptionByText(optionName);
@@ -165,11 +46,12 @@ const selectOptionsByName = async (optionNames: string[]) => {
   }
 };
 
+/** Verifies that tags in expectedTags array exist - expectedTags should always contain ALL expected tags */
 const verifyTagsExist = async (
-  multiSelect: HTMLElement,
+  comboBox: HTMLElement,
   expectedTags: string[]
 ) => {
-  const tagList = await getTagList(multiSelect);
+  const tagList = await getTagList(comboBox);
   const tags = tagList.childNodes;
   await expect(tags.length).toBe(expectedTags.length);
 
@@ -178,6 +60,7 @@ const verifyTagsExist = async (
   }
 };
 
+/** Verifies whether options in the optionNames array are selected or not based on shouldBeSelected boolean */
 const verifyOptionsSelected = async (
   optionNames: string[],
   shouldBeSelected: boolean
@@ -188,13 +71,23 @@ const verifyOptionsSelected = async (
   }
 };
 
-const closePopover = async () => {
-  await userEvent.keyboard("{escape}");
-  // Wait for preventNextFocusOpen ref to be set to false via timeout
-  await new Promise((resolve) => setTimeout(resolve, 51));
+/**
+ * Storybook metadata configuration
+ * - title: determines the location in the sidebar
+ * - component: references the component being documented
+ */
+const meta: Meta<typeof ComboBox.Root> = {
+  title: "Components/ComboBox",
+  component: ComboBox.Root,
 };
 
-const mockFn = fn();
+export default meta;
+
+/**
+ * Story type for TypeScript support
+ * StoryObj provides type checking for our story configurations
+ */
+type Story = StoryObj<typeof ComboBox.Root>;
 
 /**
  * Base story
@@ -203,2648 +96,5869 @@ const mockFn = fn();
 export const Base: Story = {
   render: () => {
     return (
-      <Stack direction="row" gap="400">
-        <FormField.Root alignSelf={"flex-start"}>
-          <FormField.Label>Single Select ComboBox</FormField.Label>
-          <FormField.Input>
-            <ComboBox.Root
-              defaultItems={options}
-              placeholder="Select an animal..."
-            >
-              {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
-            </ComboBox.Root>
-          </FormField.Input>
-        </FormField.Root>
-        <FormField.Root alignSelf={"flex-start"}>
-          <FormField.Label>Multi-Select ComboBox</FormField.Label>
+      <ComposedComboBox<SimpleOption>
+        aria-label="test"
+        items={simpleOptions}
+        allowsEmptyMenu={true}
+        renderEmptyState={() => "hi"}
+        selectionMode="multiple"
+        selectedKeys={[1, 3]}
+        disabledKeys={[2, 4]}
+        leadingElement={<Search />}
+      />
+    );
+  },
+};
+
+// ============================================================
+// CUSTOM "CREATABLE" OPTIONS
+// ============================================================
+
+/**
+ * Multi-Select Custom Options Story
+ * Tests custom option creation with static data (non-async mode)
+ * Verifies:
+ * - Custom options can be created by typing and pressing Enter
+ * - Custom options persist in the list
+ * - onCreateOption callback is called with the new item
+ * - Custom options can be selected/deselected
+ * - Custom options work alongside static options
+ */
+export const MultiSelectCustomOptions: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([1]);
+    const [createdOptions, setCreatedOptions] = useState<string[]>([]);
+
+    const handleCreateOption = useCallback((newItem: SimpleOption) => {
+      setCreatedOptions((prev) => [...prev, newItem.name]);
+    }, []);
+
+    return (
+      <Stack direction="column" gap="400">
+        <FormField.Root>
+          <FormField.Label>Select or create animals</FormField.Label>
+          <FormField.Description>
+            Type a custom animal name and press Enter to create!
+            {createdOptions.length > 0 &&
+              ` | Created: ${createdOptions.join(", ")}`}
+          </FormField.Description>
           <FormField.Input>
-            <ComboBox.Root
-              defaultItems={options}
+            <ComposedComboBox<SimpleOption>
+              aria-label="Select or create animals"
+              items={simpleOptions}
+              selectedKeys={selectedKeys}
+              onSelectionChange={setSelectedKeys}
               selectionMode="multiple"
-              placeholder="Select multiple animals..."
-            >
-              {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
-            </ComboBox.Root>
+              placeholder="Type to search or create..."
+              allowsCustomOptions
+              getNewOptionData={(inputValue) => ({
+                id: Date.now(),
+                name: inputValue,
+              })}
+              onCreateOption={handleCreateOption}
+            />
           </FormField.Input>
         </FormField.Root>
       </Stack>
     );
   },
+
   play: async ({ canvasElement, step }) => {
     const canvas = within(canvasElement);
-    const singleSelect: HTMLInputElement = await canvas.findByRole("combobox", {
-      name: /single select combobox/i,
+
+    await step("Initial state - one item selected", async () => {
+      // Verify initial selected tag (id: 1 = Koala)
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
     });
-    const multiSelect = await canvas.findByRole("combobox", {
-      name: /multi-select combobox/i,
+
+    await step("Open combobox", async () => {
+      const toggleButton = await within(
+        await canvas.findByRole("group")
+      ).findByRole("button", { name: /toggle options/i });
+      await userEvent.click(toggleButton);
+
+      // Wait for menu to open
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+
+      // Verify Koala is selected in options
+      await verifyOptionsSelected(["Koala"], true);
     });
 
-    await step(
-      "single select input is focusable and opens popover on focus",
-      async () => {
-        await userEvent.tab();
-        await expect(singleSelect).toHaveFocus();
-        // popover is activated when component is focused
-        const listbox = document.querySelector('[role="listbox"]');
-        await expect(listbox).toBeInTheDocument();
-      }
-    );
-    await step(
-      "single select input when user enters text options in popover are filtered",
-      async () => {
-        // Enter 'k'
-        await userEvent.keyboard("{k}");
-        let options = getListboxOptions();
-        // 'k' should show Koala and Kangaroo (and Skunk contains 'k')
-        await expect(options.length).toBe(3);
-        await userEvent.keyboard("{o}");
-        options = getListboxOptions();
-        await expect(options.length).toBe(1);
-      }
-    );
-    await step(
-      "single select input updates value to selected option and closes listbox when option is selected",
-      async () => {
-        const listbox = document.querySelector('[role="listbox"]');
-        const option = document.querySelector('[role="option"]');
-        await userEvent.click(option!);
-        // Click should close listbox and populate input with selected value
-        await expect(listbox).not.toBeInTheDocument();
-        await expect(singleSelect.value).toBe("Koala");
-        // Make sure koala option has selected state
-        await userEvent.keyboard("{ArrowDown}");
-        await verifyOptionsSelected(["Koala"], true);
-        // Close popover for next test
-        await closePopover();
-      }
-    );
-    await step(
-      "single select places cursor at beginning of input on focus when there is a previously selected value displayed",
-      async () => {
-        // Verify that cursor is at end of input while focused
-        await expect(singleSelect).toHaveFocus();
-        await expect(singleSelect.selectionStart).toBe(5);
-        await expect(singleSelect.selectionEnd).toBe(5);
-        // Click the document body to blur single select
-        await userEvent.click(document.body);
-        await expect(singleSelect).not.toHaveFocus();
-        // Focus single select
-        singleSelect.focus();
-        // Wait for render frame to complete
-        await waitFor(async () => {
-          // Check that cursor is at position 0 (start of input)
-          await expect(singleSelect.selectionStart).toBe(0);
-          await expect(singleSelect.selectionEnd).toBe(0);
-        });
-        // Check that input's value is still "Koala"
-        await expect(singleSelect.value).toBe("Koala");
-      }
-    );
-    await step(
-      "single select after focus replaces previous input value with user input, and filters options based input",
-      async () => {
-        // Check that input's value is still "Koala"
-        await expect(singleSelect.value).toBe("Koala");
-        // Type 'u'
-        await userEvent.keyboard("u");
-        // Input value is 'u'
-        await expect(singleSelect.value).toBe("u");
-        // There should be 2 options shown, 'playtypus' and 'skunk'
-        await expect(getListboxOptions().length).toBe(2);
-        await expect(findOptionByText("Platypus")).toBeInTheDocument();
-        await expect(findOptionByText("Skunk")).toBeInTheDocument();
-      }
-    );
-    await step(
-      "single select replaces input value with previously selected value if user blurs input without selecting new value",
-      async () => {
-        // Check that input's value is still "u"
-        await expect(singleSelect.value).toBe("u");
-        // Blur the input
-        await userEvent.tab();
-        // Input value should be selectedKey value: 'Koala'
-        await expect(singleSelect.value).toBe("Koala");
-      }
-    );
-    await step(
-      "single select replaces previously selected value if user selects new value after focus and typing",
-      async () => {
-        singleSelect.focus();
-        // Wait for render frame to complete
-        await waitFor(async () => {
-          // Check that cursor is at position 0 (start of input)
-          await expect(singleSelect.selectionStart).toBe(0);
-          await expect(singleSelect.selectionEnd).toBe(0);
-        });
-        // Check that input's value is still "Koala"
-        await expect(singleSelect.value).toBe("Koala");
-        // Type 'u'
-        await userEvent.keyboard("u");
-        // Input value is 'u'
-        await expect(singleSelect.value).toBe("u");
-        // Select Platypus
-        await selectOptionsByName(["Platypus"]);
-        // Blur input
-        await userEvent.tab();
-        // Input value should be selectedKey value: 'Platypus'
-        await expect(singleSelect.value).toBe("Platypus");
-      }
-    );
-    await step(
-      "single select clear button clears the combobox value",
-      async () => {
-        // Input value should be selectedKey value: 'Platypus'
-        await expect(singleSelect.value).toBe("Platypus");
-        const clearButton = await canvas.findByRole("button", {
-          name: /clear selection/i,
-        });
-        // Click clear button
-        await userEvent.click(clearButton);
-        // Input value should be cleared
-        await expect(singleSelect.value).toBe("");
-        // Clear button should not be in the DOM
-        await expect(clearButton).not.toBeInTheDocument();
-      }
-    );
-    await step(
-      "single select opens popover and focuses first option when user hits down arrow while input is focused",
-      async () => {
-        singleSelect.focus();
-        await userEvent.keyboard("{ArrowDown}");
-        await expect(
-          document.querySelector('[role="listbox"]')
-        ).toBeInTheDocument();
-        const options = getListboxOptions();
-        // first option should be aria-activedescendant
-        await expect(
-          singleSelect.getAttribute("aria-activedescendant")
-        ).toEqual(options[0].getAttribute("id"));
-      }
-    );
-    await step(
-      "single select closes popover and focuses input when esc key is hit",
-      async () => {
-        await expect(
-          document.querySelector('[role="listbox"]')
-        ).toBeInTheDocument();
-        await closePopover();
-        await expect(document.querySelector('[role="listbox"]')).toBeNull();
-        await expect(singleSelect).toHaveFocus();
-      }
-    );
-    await step(
-      "single select opens popover and focuses last option when user hits up arrow while input is focused",
-      async () => {
-        await userEvent.keyboard("{ArrowUp}");
-        await expect(
-          document.querySelector('[role="listbox"]')
-        ).toBeInTheDocument();
-        const options = getListboxOptions();
-        // last option should be aria-activedescendant
-        await expect(
-          singleSelect.getAttribute("aria-activedescendant")
-        ).toEqual(options[options.length - 1].getAttribute("id"));
-        // Close popover for next test
-        await closePopover();
-      }
-    );
-    await step("multi select opens popover on first focus", async () => {
-      // Tab from single to multi select
-      await userEvent.tab();
-      // popover will open on focus if the combobox is not touched and there are no selected values
-      const listbox = document.querySelector('[role="listbox"]');
-      await expect(listbox).toBeInTheDocument();
-      const options = getListboxOptions();
-      await expect(options.length).toBe(6);
-      // input in popover should have focus
-      const multiselectinput = getFilterInput();
-      await expect(multiselectinput).toHaveFocus();
+    await step("Create first custom option", async () => {
+      const combobox = canvas.getByRole("combobox");
+
+      // Type a custom animal name
+      await userEvent.clear(combobox);
+      await userEvent.type(combobox, "Lion");
+
+      // Press Enter to create
+      await userEvent.keyboard("{Enter}");
+
+      // Wait for custom option to be created and selected
+      await verifyOptionsSelected(["Lion"], true);
+      await waitFor(() => {
+        // Check tag was added
+        expect(findOptionByText("Lion")).toBeInTheDocument();
+        // Check description updated
+        expect(canvas.getByText(/Created: Lion/)).toBeInTheDocument();
+      });
+
+      // Verify input was cleared after creation (multi-select behavior)
+      expect(combobox).toHaveValue("");
     });
-    await step(
-      "multi select closes popover and focuses combobox when esc key is hit",
-      async () => {
-        await expect(
-          document.querySelector('[role="listbox"]')
-        ).toBeInTheDocument();
-        await closePopover();
-        await expect(document.querySelector('[role="listbox"]')).toBeNull();
-        await expect(multiSelect).toHaveFocus();
-      }
-    );
-    await step(
-      "multi select opens listbox when focused a second time",
-      async () => {
-        singleSelect.focus();
-        await userEvent.tab();
-        await expect(
-          document.querySelector('[role="listbox"]')
-        ).toBeInTheDocument();
-        // close popover for next test
-        await closePopover();
-      }
-    );
-    await step("multi select toggles popover on click", async () => {
-      // Click the root component
-      await userEvent.click(multiSelect);
-      // Toggle popover to open state
-      await expect(
-        document.querySelector('[role="listbox"]') as HTMLElement
-      ).toBeInTheDocument();
-      await expect(multiSelect.getAttribute("data-open")).toBe("true");
-      // Click root component again
-      // fireEvent used here due to this bug: https://github.com/testing-library/user-event/issues/1075#issuecomment-1948093169
-      await fireEvent.click(multiSelect);
-      // Toggle popover to closed state
-      await expect(document.querySelector('[role="listbox"]')).toBeNull();
-      await expect(multiSelect.getAttribute("data-open")).toBe("false");
+
+    await step("Create second custom option", async () => {
+      const combobox = canvas.getByRole("combobox");
+
+      // Type another custom animal
+      await userEvent.type(combobox, "Tiger");
+      await userEvent.keyboard("{Enter}");
+
+      // Wait for second custom option
+      await verifyOptionsSelected(["Tiger"], true);
+      await waitFor(() => {
+        expect(canvas.getByText(/Created: Lion, Tiger/)).toBeInTheDocument();
+      });
     });
-    await step(
-      "multi select opens popover when focused and popover is closed and user presses enter",
-      async () => {
-        // Focus the multiselect combobox
-        multiSelect.focus();
-        // Close the popover
-        await closePopover();
-        // Ensure no popover is open initially
-        await expect(document.querySelector('[role="listbox"]')).toBeNull();
-        // Ensure multiselect has focus
-        await expect(multiSelect).toHaveFocus();
-        // Press Enter key
-        await userEvent.keyboard("{enter}");
-        // Verify popover opens
-        const listbox = document.querySelector('[role="listbox"]');
-        await expect(listbox).toBeInTheDocument();
-        // Verify options are visible
-        const options = getListboxOptions();
-        await expect(options.length).toBe(6);
-        // Close popover for next test
-        await closePopover();
-      }
-    );
-    await step(
-      "multi select opens popover when focused and popover is closed and user presses down arrow",
-      async () => {
-        // Focus the multiselect combobox
-        multiSelect.focus();
-        // Close the popover
-        await closePopover();
-        // Ensure no popover is open initially
-        await expect(document.querySelector('[role="listbox"]')).toBeNull();
-        // Ensure multiselect has focus
-        await expect(multiSelect).toHaveFocus();
-        // Press ArrowDown key
-        await userEvent.keyboard("{ArrowDown}");
-        // Verify popover opens
-        const listbox = document.querySelector('[role="listbox"]');
-        await expect(listbox).toBeInTheDocument();
-        // Verify options are visible
-        const options = getListboxOptions();
-        await expect(options.length).toBe(6);
-      }
-    );
-    await step("multi select filters options as user types", async () => {
-      // Ensure popover is open from previous test
+
+    await step("Select an existing static option", async () => {
+      const combobox = canvas.getByRole("combobox");
+
+      // Clear input and type to filter
+      await userEvent.clear(combobox);
+      await userEvent.type(combobox, "Kang");
+
+      // Wait for filtered results
+      await waitFor(() => {
+        expect(findOptionByText("Kangaroo")).toBeInTheDocument();
+      });
+
+      // Select Kangaroo option
+      await selectOptionsByName(["Kangaroo"]);
+
+      // Verify Kangaroo tag appears in tag list
+      await verifyTagsExist(canvas.getByRole("group"), [
+        "Koala",
+        "Lion",
+        "Tiger",
+        "Kangaroo",
+      ]);
+    });
+
+    await step("Remove a custom option tag", async () => {
+      // Find and click remove button for Lion
+      const lionTag = await within(await getTagList(canvas.getByRole("group")))
+        .getByText("Lion")
+        .closest('[role="row"]');
+      expect(lionTag).toBeInTheDocument();
+
+      const removeButton = within(lionTag as HTMLElement).getByRole("button", {
+        name: /remove tag lion/i,
+      });
+      await userEvent.click(removeButton);
+
+      // Verify Lion tag is removed
+
       await expect(
-        document.querySelector('[role="listbox"]')
-      ).toBeInTheDocument();
-      // Initially all 6 options should be visible
-      let options = getListboxOptions();
-      await expect(options.length).toBe(6);
-      // Type 'k' to filter options - should show Koala and Kangaroo (and Skunk contains 'k')
-      const filterInput = getFilterInput();
-      await expect(filterInput).toBeInTheDocument();
-      // Clear any existing input and type 'k'
-      await userEvent.clear(filterInput);
-      await userEvent.type(filterInput, "k");
-      // Verify filtered options - should show options containing 'k
-      options = getListboxOptions();
-      await expect(options.length).toBe(3); // Koala, Kangaroo, Skunk
-      // Type 'o' to further filter - should show only Koala
-      await userEvent.type(filterInput, "o");
-      options = getListboxOptions();
-      await expect(options.length).toBe(1); // Only Koala
-      // Verify the remaining option is Koala
-      const remainingOption = options[0];
-      await expect(remainingOption).toHaveTextContent("Koala");
+        await within(await getTagList(canvas.getByRole("group"))).queryByText(
+          "Lion"
+        )
+      ).not.toBeInTheDocument();
+
+      // Other tags should still exist
+      await verifyTagsExist(canvas.getByRole("group"), [
+        "Koala",
+        "Tiger",
+        "Kangaroo",
+      ]);
     });
+
     await step(
-      "multi select allows selecting option with enter key and shows selection in taglist",
-      async () => {
-        // Ensure popover is open and filtered to show only Koala
-        await expect(
-          document.querySelector('[role="listbox"]')
-        ).toBeInTheDocument();
-        let options = getListboxOptions();
-        await expect(options.length).toBe(1);
-        // Ensure filter input has focus
-        const filterInput = getFilterInput();
-        await expect(filterInput).toHaveFocus();
-        // Press Enter to select the focused option (Koala)
-        await userEvent.keyboard("{enter}");
-        // Verify the option is selected by checking for a tag in the taglist
-        let tagList = await getTagList(multiSelect);
-        await expect(tagList).toBeInTheDocument();
-        let tags = tagList.childNodes;
-        // Verify the tag contains "Koala"
-        const koalaTag = tags[0];
-        await expect(koalaTag).toHaveTextContent("Koala");
-        // Clear the filter to show all options again
-        await userEvent.clear(filterInput);
-        // Verify all options are visible again
-        options = getListboxOptions();
-        await expect(options.length).toBe(6);
-        // Select another option using Enter key (navigate to Kangaroo and select it)
-        await userEvent.keyboard("{ArrowDown}{ArrowDown}"); // Navigate to Kangaroo (second option)
-        /**
-         * Apparently this is what is causing the `act` warning in the storybook test
-         * storybook has 3-4 issues about this, which they keep closing, but never seem to fix
-         * most recent issue: https://github.com/storybookjs/storybook/issues/25304
-         */
-        await userEvent.keyboard("{enter}");
-        // Verify we now have 2 tags
-        tagList = await getTagList(multiSelect);
-        tags = tagList.childNodes;
-        await expect(tags.length).toBe(2);
-        // Verify the second tag contains "Kangaroo"
-        const kangarooTag = tags[1];
-        await expect(kangarooTag).toHaveTextContent("Kangaroo");
-        // Close popover for next test
-        await closePopover();
-      }
-    );
-    await step(
-      "multi select clear all button clears all tags and selected options",
-      async () => {
-        // Verify we start with tags from the previous test (should have Koala and Kangaroo selected)
-        let tagList = await getTagList(multiSelect);
-        let tags = tagList.childNodes;
-        await expect(tags.length).toBe(2);
-        // Find and click the clear all button
-        const clearAllButton = await within(multiSelect).findByRole("button", {
-          name: /clear selection/i,
-        });
-        await expect(clearAllButton).toBeInTheDocument();
-        // Click the clear all button
-        await userEvent.click(clearAllButton);
-        // Verify all tags are cleared
-        // After clearing, the taglist will contain a placeholder
-        tagList = await getTagList(multiSelect);
-        tags = tagList.childNodes;
-        await expect(tags.length).toBe(1);
-        // insure that the tagsList child is the placeholder
-        await expect(tags[0]).toHaveTextContent(/Select multiple animals.../i);
-        // Verify popover opens with all options visible (none filtered)
-        const listbox = document.querySelector('[role="listbox"]');
-        await expect(listbox).toBeInTheDocument();
-        const options = getListboxOptions();
-        await expect(options.length).toBe(6);
-        // Verify no options show as selected (check for aria-selected="true" or selected styling)
-        for (const option of Array.from(options)) {
-          // Check that no options are marked as selected
-          const isSelected =
-            option.getAttribute("aria-selected") === "true" ||
-            option.getAttribute("data-selected") === "true";
-          await expect(isSelected).toBe(false);
-        }
-        // Close popover
-        await closePopover();
-      }
-    );
-    await step(
-      "multi select allows removing individual selections by clicking tag remove buttons",
-      async () => {
-        // Setup: Select 3 options
-        multiSelect.focus();
-        await userEvent.keyboard("{enter}");
-        await selectOptionsByName(["Koala", "Kangaroo", "Platypus"]);
-        await closePopover();
-        // Verify initial state
-        await verifyTagsExist(multiSelect, ["Koala", "Kangaroo", "Platypus"]);
-        // Remove middle tag (Kangaroo)
-        const tagList = await getTagList(multiSelect);
-        const kangarooTag = tagList.childNodes[1] as HTMLElement;
-        const removeButton = within(kangarooTag).getByRole("button", {
-          name: /remove tag kangaroo/i,
-        });
-        await userEvent.click(removeButton);
-        // Verify Kangaroo removed
-        await verifyTagsExist(multiSelect, ["Koala", "Platypus"]);
-        // Verify listbox state
-        await userEvent.keyboard("{enter}");
-        await verifyOptionsSelected(["Koala", "Platypus"], true);
-        await verifyOptionsSelected(["Kangaroo"], false);
-        await closePopover();
-        // Remove first tag (Koala)
-        const updatedTagList = await getTagList(multiSelect);
-        const koalaTag = updatedTagList.childNodes[0] as HTMLElement;
-        const koalaRemoveButton = within(koalaTag).getByRole("button", {
-          name: /remove tag koala/i,
-        });
-        await userEvent.click(koalaRemoveButton);
-        // Verify only Platypus remains
-        await verifyTagsExist(multiSelect, ["Platypus"]);
-      }
-    );
-    await step(
-      "multi select allows removing selected options by clicking on them in the listbox",
-      async () => {
-        // Setup: Start with Platypus from previous test, add Koala and Kangaroo
-        multiSelect.focus();
-        await userEvent.keyboard("{enter}");
-        await selectOptionsByName(["Koala", "Kangaroo"]);
-        // Verify 3 tags total
-        await verifyTagsExist(multiSelect, ["Platypus", "Koala", "Kangaroo"]);
-        // Verify all options show as selected
-        await verifyOptionsSelected(["Platypus", "Koala", "Kangaroo"], true);
-        // Click Kangaroo option to deselect
-        const kangarooOption = findOptionByText("Kangaroo");
-        await userEvent.click(kangarooOption!);
-        // Verify Kangaroo deselected
-        await expect(isOptionSelected(kangarooOption)).toBe(false);
-        await verifyTagsExist(multiSelect, ["Platypus", "Koala"]);
-        // Click Koala option to deselect
-        const koalaOption = findOptionByText("Koala");
-        await userEvent.click(koalaOption!);
-        await verifyTagsExist(multiSelect, ["Platypus"]);
-        // Click Platypus option to deselect last item
-        const platypusOption = findOptionByText("Platypus");
-        await userEvent.click(platypusOption!);
-        // Verify all cleared - placeholder shown
-        const tagList = await getTagList(multiSelect);
-        const tags = tagList.childNodes;
-        await expect(tags.length).toBe(1);
-        await expect(tags[0]).toHaveTextContent(/Select multiple animals.../i);
-        // Close popover
-        await closePopover();
-      }
-    );
-    await step(
-      "multi select allows removing last selected item by hitting backspace when filter input is empty",
-      async () => {
-        // Setup: Select 3 options
-        multiSelect.focus();
-        await userEvent.keyboard("{enter}");
-        await selectOptionsByName(["Koala", "Kangaroo", "Platypus"]);
-        await verifyTagsExist(multiSelect, ["Koala", "Kangaroo", "Platypus"]);
-        // Ensure filter input is empty and focused
-        const filterInput = getFilterInput();
-        await userEvent.clear(filterInput);
-        filterInput.focus();
-        // Test backspace removes items in LIFO order
-        await userEvent.keyboard("{Backspace}");
-        await verifyTagsExist(multiSelect, ["Koala", "Kangaroo"]);
-        await userEvent.keyboard("{Backspace}");
-        await verifyTagsExist(multiSelect, ["Koala"]);
-        await userEvent.keyboard("{Backspace}");
-        // Verify placeholder shown when all cleared
-        const tagList = await getTagList(multiSelect);
-        const tags = tagList.childNodes;
-        await expect(tags.length).toBe(1);
-        await expect(tags[0]).toHaveTextContent(/Select multiple animals.../i);
-        // Verify all options deselected
-        await verifyOptionsSelected(["Koala", "Kangaroo", "Platypus"], false);
-        // Test backspace does nothing when no selections
-        await userEvent.keyboard("{Backspace}");
-        await expect(tags[0]).toHaveTextContent(/Select multiple animals.../i);
-        // Close popover
-        await closePopover();
-      }
-    );
-    await step(
-      "multi select does not remove items with backspace when filter input has text",
-      async () => {
-        // Setup: Select 2 options
-        multiSelect.focus();
-        await userEvent.keyboard("{enter}");
-        await selectOptionsByName(["Koala", "Kangaroo"]);
-        await verifyTagsExist(multiSelect, ["Koala", "Kangaroo"]);
-        // Type text in filter input
-        const filterInput = getFilterInput();
-        await userEvent.type(filterInput, "test");
-        await expect(filterInput.value).toBe("test");
-        // Backspace should remove text, not selections
-        await userEvent.keyboard("{Backspace}");
-        await expect(filterInput.value).toBe("tes");
-        await verifyTagsExist(multiSelect, ["Koala", "Kangaroo"]);
-        // Clear input completely, then backspace should remove selection
-        await userEvent.clear(filterInput);
-        await userEvent.keyboard("{Backspace}");
-        await verifyTagsExist(multiSelect, ["Koala"]);
-        // Close popover
-        await closePopover();
-      }
-    );
-    await step(
-      "multi select - when items are selected clicking root component toggles popover",
-      async () => {
-        // Verify popover is closed
-        await expect(document.querySelector('[role="listbox"]')).toBeNull();
-        await expect(multiSelect.getAttribute("data-open")).toBe("false");
-        // Click the root component
-        await userEvent.click(multiSelect);
-        // Verify popover is open
-        await expect(
-          document.querySelector('[role="listbox"]')
-        ).toBeInTheDocument();
-        await expect(multiSelect.getAttribute("data-open")).toBe("true");
-        // Click the root component
-        await fireEvent.click(multiSelect);
-        // Verify popover is closed
-        await expect(document.querySelector('[role="listbox"]')).toBeNull();
-        await expect(multiSelect.getAttribute("data-open")).toBe("false");
-      }
-    );
-    await step(
-      "multi select - when items are selected clicking remove item button expands popover",
-      async () => {
-        // Open popover
-        multiSelect.focus();
-        // Select multiple options
-        await selectOptionsByName(["Koala"]);
-        // Verify options selected
-        await verifyTagsExist(multiSelect, ["Koala"]);
-        // Close popover
-        await closePopover();
-        // Click the remove button
-        const removeButton = await within(multiSelect).findByRole("button", {
-          name: /remove tag koala/i,
-        });
-        await userEvent.click(removeButton);
-        // Check popover is closed
-        await expect(
-          document.querySelector('[role="listbox"]')
-        ).toBeInTheDocument();
-        await expect(multiSelect.getAttribute("data-open")).toBe("true");
-        // Close popover
-        await closePopover();
-      }
-    );
-    await step(
-      "multi select tab order goes from combobox to tag to clear button then outside combobox",
+      "Verify custom option still in list after deselection",
       async () => {
-        // Focus combobox
-        multiSelect.focus();
-        // Select an option so tag exists for next test
-        await userEvent.keyboard("{ArrowDown}{ArrowDown}{Enter}");
-        // Close the popover after selection
-        await userEvent.keyboard("{Escape}");
-        // Focus combobox wrapper again
-        multiSelect.focus();
-        // Tab to tags
-        await userEvent.tab();
-        const tagList =
-          await within(multiSelect).findByLabelText(/selected values/i);
-        await expect(tagList.childNodes[0]).toHaveFocus();
-        // Tab to remove tag button
-        await userEvent.tab();
-        const removeButton = within(
-          tagList.childNodes[0] as HTMLElement
-        ).getByRole("button", {
-          name: /remove tag koala/i,
+        // Open the menu again
+        const combobox = canvas.getByRole("combobox");
+        await userEvent.click(combobox);
+
+        // Clear any text to show all options
+        await userEvent.clear(combobox);
+
+        // Wait for menu to populate
+        await waitFor(() => {
+          expect(getListBox(document)).toBeInTheDocument();
         });
-        await expect(removeButton).toHaveFocus();
-        // Tab to clear button
-        await userEvent.tab();
-        const clearButton =
-          await within(multiSelect).findByLabelText(/clear selection/i);
-        await expect(clearButton).toHaveFocus();
-        // Tab to toggle button
-        await userEvent.tab();
-        await expect(multiSelect).not.toHaveFocus();
+
+        // Lion should still be in the list (just not selected)
+        await verifyOptionsSelected(["Lion"], false);
+
+        // Tiger should be in the list and selected
+        await verifyOptionsSelected(["Tiger"], true);
       }
     );
-  },
-};
 
-/**
- * Controlled State
- * Demonstrates controlled usage patterns for single and multi-select
- */
-export const ControlledState: Story = {
-  args: {
-    selectedKey: 2,
-  },
-  render: (args) => {
-    const [controlledValue, setControlledValue] = useState<Key | null>(
-      // @ts-expect-error - no good way to discriminate union prop from args while following rules of hooks
-      args.selectedKey
-    );
-    const [controlledMultiValue, setControlledMultiValue] = useState<Selection>(
-      new Set([1, 3])
-    );
-    const [singleInputValue, setSingleInputValue] = useState(
-      // @ts-expect-error - no good way to discriminate union prop from args while following rules of hooks
-      args.selectedKey
-        ? // @ts-expect-error - no good way to discriminate union prop from args while following rules of hooks
-          (options.find((o) => o.id === args.selectedKey)?.name ?? "")
-        : ""
-    );
-    const [multiInputValue, setMultiInputValue] = useState("");
+    await step("Attempt to create duplicate option", async () => {
+      const combobox = canvas.getByRole("combobox");
 
-    // Wrapper functions that call both the state setter and mock function
-    const handleSingleSelectionChange = (key: Key | null) => {
-      // If the input is controlled, it is necessary to set the input value to the text value of the selected option
-      const inputValue = options.find((o) => o.id === key)?.name ?? "";
-      setSingleInputValue(inputValue);
-      setControlledValue(key);
-      mockFn(key, inputValue);
-    };
+      // Try to create "Tiger" again (already exists)
+      await userEvent.clear(combobox);
+      await userEvent.type(combobox, "Koala");
+      await userEvent.keyboard("{Enter}");
 
-    const handleMultiSelectionChange = (keys: Selection) => {
-      setControlledMultiValue(keys);
-      mockFn(keys);
-    };
+      // Should not create duplicate - Created list should not change
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      expect(canvas.getByText(/Created: Lion, Tiger$/)).toBeInTheDocument();
 
-    // Input value change handlers
-    const handleSingleInputChange = (value: string) => {
-      setSingleInputValue(value);
-      mockFn(value);
-    };
+      // Tiger should remain selected (was already selected)
+      expect(canvas.getByText("Tiger")).toBeInTheDocument();
+    });
+  },
+};
 
-    const handleMultiInputChange = (value: string) => {
-      setMultiInputValue(value);
-      mockFn(value);
-    };
+// ============================================================
+// ASYNC LOADING
+// ============================================================
 
-    // Helper function to get the display text for single selection
-    const getSingleSelectionDisplay = (selectedKey: Key | null) => {
-      if (!selectedKey) return "None";
-      const selectedOption = options.find(
-        (option) => option.id === selectedKey
-      );
-      return selectedOption
-        ? `${selectedKey} (${selectedOption.name})`
-        : selectedKey.toString();
-    };
-
-    // Helper function to get the display text for multiple selection
-    const getMultiSelectionDisplay = (selectedKeys: Selection) => {
-      if (selectedKeys === "all") return "All items";
-      const selectedArray = Array.from(selectedKeys);
-      if (selectedArray.length === 0) return "None";
-
-      return selectedArray
-        .map((key) => {
-          const selectedOption = options.find((option) => option.id === key);
-          return selectedOption
-            ? `${key} (${selectedOption.name})`
-            : key.toString();
-        })
-        .join(", ");
-    };
+/**
+ * Demonstrates async loading with the built-in async API.
+ * Shows rich Pokemon results with sprites, types, and stats.
+ *
+ * The ComboBox automatically handles:
+ * - Loading state management
+ * - Request debouncing (300ms default)
+ * - Request cancellation on input changes
+ * - Filter bypass (since API handles filtering)
+ * - Empty menu display
+ * - Error handling
+ */
+export const AsyncLoading: Story = {
+  render: () => {
+    const [error, setError] = useState<string | null>(null);
+    const getPokemonValue = useCallback((pokemon: Pokemon) => pokemon.name, []);
 
     return (
-      <Stack direction="column" gap="400">
-        <Stack direction="row" gap="400">
-          <FormField.Root alignSelf={"flex-start"}>
-            <FormField.Label>Controlled Single-Select</FormField.Label>
-            <FormField.Input>
-              <ComboBox.Root
-                aria-label="controlled animals"
-                defaultItems={options}
-                selectedKey={controlledValue}
-                onSelectionChange={handleSingleSelectionChange}
-                inputValue={singleInputValue}
-                onInputChange={handleSingleInputChange}
-                placeholder="Select an animal..."
-                leadingElement={<Icon as={AddReaction} />}
-              >
-                {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
-              </ComboBox.Root>
-            </FormField.Input>
-            <FormField.Description data-testid="single-select-state">
-              Selected: {getSingleSelectionDisplay(controlledValue)}
-            </FormField.Description>
-          </FormField.Root>
-          <FormField.Root alignSelf={"flex-start"}>
-            <FormField.Label>Controlled Multi-Select</FormField.Label>
-            <FormField.Input>
-              <ComboBox.Root
-                aria-label="controlled multi animals"
-                defaultItems={options}
-                selectionMode="multiple"
-                selectedKeys={controlledMultiValue}
-                onSelectionChange={handleMultiSelectionChange}
-                inputValue={multiInputValue}
-                onInputChange={handleMultiInputChange}
-                placeholder="Select multiple animals..."
-              >
-                {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
-              </ComboBox.Root>
-            </FormField.Input>
-            <FormField.Description data-testid="multi-select-state">
-              Selected: {getMultiSelectionDisplay(controlledMultiValue)}
-            </FormField.Description>
-          </FormField.Root>
-        </Stack>
-      </Stack>
+      <ComboBox.Root<Pokemon>
+        aria-label="Asyncachu"
+        placeholder="Type to search for Pokemon..."
+        getKey={getPokemonValue}
+        getTextValue={getPokemonValue}
+        isInvalid={!!error}
+        selectionMode="multiple"
+        async={{
+          load: async (filterText, signal) => {
+            // Pokemon API returns all pokemon, we filter client-side
+            const response = await fetch(
+              `https://pokeapi.co/api/v2/pokemon?limit=1000`,
+              { signal }
+            );
+
+            if (!response.ok) {
+              throw new Error(`HTTP error! status: ${response.status}`);
+            }
+
+            const data = await response.json();
+            // Filter results client-side to match search
+            const filtered = data.results.filter((p: Pokemon) =>
+              p.name.toLowerCase().includes(filterText.toLowerCase())
+            );
+            return filtered.slice(0, 100); // Limit to 100 results for performance
+          },
+          debounce: 300,
+          onError: (err) => {
+            setError(err.message);
+          },
+        }}
+      >
+        <ComboBox.Trigger />
+        <ComboBox.Popover>
+          <ComboBox.ListBox>
+            {(pokemon: Pokemon) => (
+              <ComboBox.Option>
+                <PokemonOption pokemon={pokemon} />
+              </ComboBox.Option>
+            )}
+          </ComboBox.ListBox>
+        </ComboBox.Popover>
+      </ComboBox.Root>
     );
   },
+
   play: async ({ canvasElement, step }) => {
     const canvas = within(canvasElement);
-    const singleSelect: HTMLInputElement = await canvas.findByRole("combobox", {
-      name: /controlled single-select/i,
-    });
-    const singleSelectStateValue = await canvas.findByTestId(
-      "single-select-state"
-    );
-    const multiSelect = await canvas.findByRole("combobox", {
-      name: /controlled multi-select/i,
+
+    await step("Type search query", async () => {
+      const input = canvas.getByRole("combobox");
+      await userEvent.clear(input);
+      await userEvent.type(input, "pika");
+
+      // Verify input has value
+      expect(input).toHaveValue("pika");
     });
-    const multiSelectStateValue =
-      await canvas.findByTestId("multi-select-state");
 
-    await step(
-      "Single select shows text value of selected item in input and items option is selected in popover",
-      async () => {
-        // Focus
-        singleSelect.focus();
-        // Check that input value is text value of selected item from external state (2 - kangaroo)
-        await expect(singleSelect.value).toBe("Kangaroo");
-        // Check that external state in description is correct
-        await expect(singleSelectStateValue.textContent).toBe(
-          "Selected: 2 (Kangaroo)"
-        );
-        // Check that option for selected item from external state is selected in popover
-        await userEvent.keyboard("{ArrowDown}");
-        await verifyOptionsSelected(["Kangaroo"], true);
-        // Close popover for next test
-        await closePopover();
-      }
-    );
-    await step(
-      "Single select updates external state when user selects a different option",
-      async () => {
-        // Focus
-        singleSelect.focus();
-        // Remove text from input, which opens popover
-        await userEvent.clear(singleSelect);
-        // Select koala option
-        await selectOptionsByName(["Koala"]);
-        // Verify that external state handler was called with correct value
-        await expect(mockFn).toHaveBeenCalledWith(1, "Koala");
-        // Verfiy that expected input value is correct
-        await expect(singleSelect.value).toBe("Koala");
-        // Check that external state in description is correct
-        await expect(singleSelectStateValue.textContent).toBe(
-          "Selected: 1 (Koala)"
-        );
-        // Open popover and verify that Koala option is selected and Kangaroo is not
-        await userEvent.keyboard("{ArrowDown}");
-        await verifyOptionsSelected(["Koala"], true);
-        await verifyOptionsSelected(["Kangaroo"], false);
-      }
-    );
-    await step(
-      "Multi select shows text value of selected items from props in tags and options are selected in popover",
-      async () => {
-        // Focus
-        multiSelect.focus();
-        // Check that input value is text value of selected item from external state (2 - kangaroo)
-        await verifyTagsExist(multiSelect, ["Koala", "Platypus"]);
-        // Check that external state in description is correct
-        await expect(multiSelectStateValue.textContent).toBe(
-          "Selected: 1 (Koala), 3 (Platypus)"
-        );
-        // Check that options for selected items from external state are selected in popover
-        await userEvent.keyboard("{ArrowDown}");
-        await verifyOptionsSelected(["Koala", "Platypus"], true);
-        // Close popover for next test
-        await closePopover();
-      }
-    );
-    await step(
-      "Multi select updates external state when user selects a different option",
-      async () => {
-        // Focus
-        multiSelect.focus();
-        // Open popover
-        await userEvent.keyboard("{ArrowDown}");
-        // Select skunk option
-        await selectOptionsByName(["Skunk"]);
-        // Verify that external state handler was called with correct value
-        await expect(mockFn).toHaveBeenCalled();
-        // Verfiy that expected input value is correct
-        await expect(singleSelect.value).toBe("Koala");
-        // Check that external state in description is correct
-        await expect(multiSelectStateValue.textContent).toBe(
-          "Selected: 1 (Koala), 3 (Platypus), 6 (Skunk)"
-        );
-        // Check that options for selected items from external state are selected in popover
-        await userEvent.keyboard("{ArrowDown}");
-        await verifyOptionsSelected(["Koala", "Platypus", "Skunk"], true);
-        // Check that options for unselected items are not selected in popover
-        await verifyOptionsSelected(
-          ["Kangaroo", "Bald Eagle with a very long name hooray", "Bison"],
-          false
-        );
-      }
-    );
-  },
-};
-
-/**
- * All Variants and Sizes
- * Comprehensive display of all available variants and sizes for both single and multi-select
- */
-export const AllVariantsAndSizes: Story = {
-  render: () => {
-    const sizes = ["sm", "md"] as const;
-    const variants = ["solid", "ghost"] as const;
+    await step("Wait for menu to open and results to load", async () => {
+      // Wait for listbox to appear in document.body (portaled)
+      await waitFor(
+        () => {
+          expect(getListBox(document)).not.toBeNull();
+        },
+        { timeout: 5000 }
+      );
 
-    return (
-      <Stack direction="column" gap="600">
-        {variants.map((variant) => (
-          <Stack key={variant} direction="column" gap="400">
-            <Text fontSize="500" fontWeight="600" textTransform="capitalize">
-              {variant} Variant
-            </Text>
-            {sizes.map((size) => (
-              <Stack key={`${variant}-${size}`} direction="column" gap="300">
-                <h4>Size: {size.toUpperCase()}</h4>
-                <Stack direction="row" gap="400">
-                  <FormField.Root alignSelf={"flex-start"}>
-                    <FormField.Label>{`Single Select ${variant} ${size}`}</FormField.Label>
-                    <FormField.Input>
-                      <ComboBox.Root
-                        defaultItems={options}
-                        size={size}
-                        variant={variant}
-                        placeholder={`type to search...`}
-                      >
-                        {(item) => (
-                          <ComboBox.Option>{item.name}</ComboBox.Option>
-                        )}
-                      </ComboBox.Root>
-                    </FormField.Input>
-                  </FormField.Root>
-                  <FormField.Root alignSelf={"flex-start"}>
-                    <FormField.Label>{`Multi-Select ${variant} ${size}`}</FormField.Label>
-                    <FormField.Input>
-                      <ComboBox.Root
-                        defaultItems={options}
-                        selectionMode="multiple"
-                        size={size}
-                        variant={variant}
-                        placeholder={`focus to search...`}
-                      >
-                        {(item) => (
-                          <ComboBox.Option>{item.name}</ComboBox.Option>
-                        )}
-                      </ComboBox.Root>
-                    </FormField.Input>
-                  </FormField.Root>
-                </Stack>
-              </Stack>
-            ))}
-          </Stack>
-        ))}
-      </Stack>
-    );
+      // Wait for Pikachu option to appear
+      await waitFor(
+        () => {
+          expect(findOptionByText("pikachu")).toBeTruthy();
+        },
+        { timeout: 5000 }
+      );
+    });
   },
 };
 
 /**
- * Leading and Trailing Elements
- * Display of ComboBox with leading and trailing elements in various configurations
+ * Demonstrates error handling when async loading fails.
+ * Simulates a failing API to show error states with the built-in async API.
  */
-export const LeadingElements: Story = {
+export const AsyncLoadingWithError: Story = {
   render: () => {
-    const examples: Array<{
-      label: string;
-      props?: Partial<ComboBoxRootProps<{ id: number; name: string }>>;
-      getProps?: (
-        size: "sm" | "md"
-      ) => Partial<ComboBoxRootProps<{ id: number; name: string }>>;
-    }> = [
-      {
-        label: "Without Leading Element",
-        props: {
-          placeholder: "Select items...",
-          "aria-label": "basic-combobox",
-        },
-      },
-      {
-        label: "With Leading Element",
-        props: {
-          placeholder: "Search items...",
-          leadingElement: <Search />,
-          "aria-label": "search-combobox",
-        },
-      },
-    ];
-
-    const inputSize = ["sm", "md"] as const;
-    const inputVariants = ["solid", "ghost"] as const;
-
-    return (
-      <Stack direction="column" gap="600">
-        {inputSize.map((size) => (
-          <Stack key={size as string} direction="column" gap="400">
-            <Text fontWeight="semibold">Size: {size as string}</Text>
-            <Stack direction="column" gap="300">
-              {examples.map((example) => (
-                <Stack
-                  key={`${size as string}-${example.label}`}
-                  direction="column"
-                  gap="200"
-                >
-                  <Text fontSize="sm" color="neutral.11">
-                    {example.label}
-                  </Text>
-                  <Stack direction="row" gap="400" alignItems="center">
-                    {inputVariants.map((variant) => (
-                      <Stack
-                        key={variant as string}
-                        direction="column"
-                        gap="100"
-                      >
-                        <Text fontSize="xs" color="neutral.10">
-                          {variant as string}
-                        </Text>
-                        <ComboBox.Root
-                          defaultItems={options}
-                          {...(example.getProps
-                            ? example.getProps(size)
-                            : example.props)}
-                          size={size}
-                          variant={variant}
-                        >
-                          {(item) => (
-                            <ComboBox.Option>{item.name}</ComboBox.Option>
-                          )}
-                        </ComboBox.Root>
-                      </Stack>
-                    ))}
-                  </Stack>
-                </Stack>
-              ))}
-            </Stack>
-          </Stack>
-        ))}
-
-        <Stack direction="column" gap="400">
-          <Text fontWeight="semibold">Multi-Select Variants</Text>
-          {inputSize.map((size) => (
-            <Stack key={`multi-${size as string}`} direction="column" gap="300">
-              <Text fontSize="sm" color="neutral.11">
-                Size: {size as string}
-              </Text>
-              <Stack direction="column" gap="300">
-                <Stack direction="column" gap="200">
-                  <Text fontSize="sm" color="neutral.11">
-                    With Leading Element
-                  </Text>
-                  <Stack direction="row" gap="400" alignItems="center">
-                    {inputVariants.map((variant) => (
-                      <Stack
-                        key={`multi-with-icon-${variant as string}`}
-                        direction="column"
-                        gap="100"
-                      >
-                        <Text fontSize="xs" color="neutral.10">
-                          {variant as string}
-                        </Text>
-                        <ComboBox.Root
-                          defaultItems={options}
-                          selectionMode="multiple"
-                          size={size}
-                          variant={variant}
-                          placeholder="Search multiple items..."
-                          leadingElement={<Search />}
-                          aria-label={`multi-with-icon-${variant as string}-${size as string}`}
-                        >
-                          {(item) => (
-                            <ComboBox.Option>{item.name}</ComboBox.Option>
-                          )}
-                        </ComboBox.Root>
-                      </Stack>
-                    ))}
-                  </Stack>
-                </Stack>
-                <Stack direction="column" gap="200">
-                  <Text fontSize="sm" color="neutral.11">
-                    Without Leading Element
-                  </Text>
-                  <Stack direction="row" gap="400" alignItems="center">
-                    {inputVariants.map((variant) => (
-                      <Stack
-                        key={`multi-without-icon-${variant as string}`}
-                        direction="column"
-                        gap="100"
-                      >
-                        <Text fontSize="xs" color="neutral.10">
-                          {variant as string}
-                        </Text>
-                        <ComboBox.Root
-                          defaultItems={options}
-                          selectionMode="multiple"
-                          size={size}
-                          variant={variant}
-                          placeholder="Select multiple items..."
-                          aria-label={`multi-without-icon-${variant as string}-${size as string}`}
-                        >
-                          {(item) => (
-                            <ComboBox.Option>{item.name}</ComboBox.Option>
-                          )}
-                        </ComboBox.Root>
-                      </Stack>
-                    ))}
-                  </Stack>
-                </Stack>
-              </Stack>
-            </Stack>
-          ))}
-        </Stack>
-      </Stack>
-    );
-  },
-};
+    const [error, setError] = useState<string | null>(null);
+    const getPokemonValue = useCallback((pokemon: Pokemon) => pokemon.name, []);
 
-export const OptionGroups: Story = {
-  render: () => {
     return (
-      <Stack direction="row" gap="400">
-        <FormField.Root alignSelf={"flex-start"}>
-          <FormField.Label>Single Select with Option Groups</FormField.Label>
+      <Stack direction="column" gap="400" width="500px">
+        <FormField.Root isInvalid={!!error}>
+          <FormField.Label>Search Pokemon (Error Demo)</FormField.Label>
           <FormField.Input>
-            <ComboBox.Root
-              defaultItems={sectionedItems}
-              placeholder="Select a food item..."
+            <ComboBox.Root<Pokemon>
+              placeholder="Type to trigger error..."
+              getKey={getPokemonValue}
+              getTextValue={getPokemonValue}
+              isInvalid={!!error}
+              async={{
+                load: async (_filterText, signal) => {
+                  // Simulate API failure after delay
+                  await new Promise((resolve) => setTimeout(resolve, 500));
+                  if (signal.aborted) {
+                    throw new Error("AbortError");
+                  }
+                  // Always throw an error to demonstrate error handling
+                  throw new Error(
+                    "Failed to load Pokemon. Please try again later."
+                  );
+                },
+                debounce: 300,
+                onError: (err) => {
+                  setError(err.message);
+                },
+              }}
             >
-              {(section) => (
-                <ComboBox.OptionGroup
-                  label={section.name}
-                  items={section.children}
-                >
-                  {(item) => (
-                    <ComboBox.Option textValue={item.name}>
-                      {item.name}
+              <ComboBox.Trigger />
+              <ComboBox.Popover>
+                <ComboBox.ListBox>
+                  {(pokemon: Pokemon) => (
+                    <ComboBox.Option>
+                      <PokemonOption pokemon={pokemon} />
                     </ComboBox.Option>
                   )}
-                </ComboBox.OptionGroup>
-              )}
-            </ComboBox.Root>
-          </FormField.Input>
-        </FormField.Root>
-        <FormField.Root alignSelf={"flex-start"}>
-          <FormField.Label>Multi-Select with Option Groups</FormField.Label>
-          <FormField.Input>
-            <ComboBox.Root
-              defaultItems={sectionedItems}
-              selectionMode="multiple"
-              placeholder="Select multiple food items..."
-            >
-              {(section) => (
-                <ComboBox.OptionGroup
-                  label={section.name}
-                  items={section.children}
-                >
-                  {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
-                </ComboBox.OptionGroup>
-              )}
+                </ComboBox.ListBox>
+              </ComboBox.Popover>
             </ComboBox.Root>
           </FormField.Input>
+          {error && <FormField.Error>{error}</FormField.Error>}
+          <FormField.Description>
+            This demo always fails to demonstrate error handling in async
+            loading
+          </FormField.Description>
         </FormField.Root>
       </Stack>
     );
   },
+
   play: async ({ canvasElement, step }) => {
     const canvas = within(canvasElement);
-    const singleSelect: HTMLInputElement = await canvas.findByRole("combobox", {
-      name: /single select with option groups/i,
+
+    await step("Type search query to trigger error", async () => {
+      const input = canvas.getByRole("combobox");
+      await userEvent.clear(input);
+      await userEvent.type(input, "test");
+
+      // Verify input has value
+      expect(input).toHaveValue("test");
     });
-    const multiSelect = await canvas.findByRole("combobox", {
-      name: /multi-select with option groups/i,
+
+    await step("Wait for error to appear", async () => {
+      await waitFor(
+        () => {
+          const errorMessage = canvas.queryByText(/Failed to load Pokemon/i);
+          expect(errorMessage).toBeInTheDocument();
+        },
+        { timeout: 3000 }
+      );
     });
+  },
+};
 
-    await step(
-      "Single Select option groups are rendered with proper roles",
-      async () => {
-        // Focus combobox
-        singleSelect.focus();
-        // Open popover
-        await userEvent.keyboard("{ArrowDown}");
-        // Find sections
-        const groups = document.querySelectorAll(
-          '[role="listbox"] [role="group"]'
-        );
-        await expect(groups.length).toBe(2);
-        // Check section labels
-        const groupLabels = document.querySelectorAll('[role="presentation"]');
-        await expect(groupLabels[0]).toHaveTextContent("Fruits");
-        await expect(groupLabels[1]).toHaveTextContent("Vegetables");
-        // Close popover for next test
-        await closePopover();
-      }
-    );
-    await step(
-      "Single Select options are filtered correctly when user enters text",
-      async () => {
-        // Focus combobox
-        singleSelect.focus();
-        // Hit 'a' key
-        await userEvent.keyboard("{a}");
-        let options = getListboxOptions();
-        // There are 5 options with 'a' in them
-        await expect(options.length).toBe(5);
-        // There are options with 'a' in both sections
-        let groups = document.querySelectorAll(
-          '[role="listbox"] [role="group"]'
-        );
-        await expect(groups.length).toBe(2);
-        // Hit 'p' key
-        await userEvent.keyboard("{p}");
-        options = getListboxOptions();
-        // There is only one option with 'ap'
-        await expect(options.length).toBe(1);
-        await expect(findOptionByText("Apple")).toBeInTheDocument();
-        // there is only one section displayed
-        groups = document.querySelectorAll('[role="listbox"] [role="group"]');
-        await expect(groups.length).toBe(1);
-        const groupLabels = document.querySelectorAll('[role="presentation"]');
-        await expect(groupLabels[0]).toHaveTextContent("Fruits");
-        // Close popover for next test
-        await closePopover();
-      }
+/**
+ * Demonstrates that selected items persist across searches in async multi-select mode.
+ * Tests that:
+ * 1. Selected items remain visible as tags even when not in current search results
+ * 2. Selected items can be removed from tags
+ * 3. Re-searching for selected items shows them as selected
+ */
+export const AsyncMultiSelectPersistence: Story = {
+  render: () => {
+    const getPokemonValue = useCallback((pokemon: Pokemon) => pokemon.name, []);
+
+    return (
+      <ComboBox.Root<Pokemon>
+        aria-label="multisyncachu"
+        placeholder="Type to search..."
+        getKey={getPokemonValue}
+        getTextValue={getPokemonValue}
+        selectionMode="multiple"
+        async={{
+          load: async (filterText, signal) => {
+            const response = await fetch(
+              `https://pokeapi.co/api/v2/pokemon?limit=1000`,
+              { signal }
+            );
+
+            if (!response.ok) {
+              throw new Error(`HTTP error! status: ${response.status}`);
+            }
+
+            const data = await response.json();
+            const filtered = data.results.filter((p: Pokemon) =>
+              p.name.toLowerCase().includes(filterText.toLowerCase())
+            );
+            return filtered.slice(0, 50);
+          },
+          debounce: 300,
+        }}
+      >
+        <ComboBox.Trigger />
+        <ComboBox.Popover>
+          <ComboBox.ListBox>
+            {(pokemon: Pokemon) => (
+              <ComboBox.Option>
+                <PokemonOption pokemon={pokemon} />
+              </ComboBox.Option>
+            )}
+          </ComboBox.ListBox>
+        </ComboBox.Popover>
+      </ComboBox.Root>
     );
-    await step("Single Select options can be selected", async () => {
-      // Focus combobox
-      singleSelect.focus();
-      // Open popover
-      await userEvent.keyboard("{ArrowDown}");
-      // Select apple option
-      await selectOptionsByName(["Apple"]);
-      // Input value should be 'apple'
-      await expect(singleSelect).toHaveValue("Apple");
-      // Open listbox check that apple option has selected state
-      await userEvent.keyboard("{ArrowDown}");
-      await verifyOptionsSelected(["Apple"], true);
-      // Close popover for next test
-      await closePopover();
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Search for 'pika' and select pikachu", async () => {
+      const input = canvas.getByRole("combobox");
+      await userEvent.clear(input);
+      await userEvent.type(input, "pika");
+
+      // Wait for results
+      await waitFor(
+        () => {
+          expect(findOptionByText("pikachu")).toBeTruthy();
+        },
+        { timeout: 5000 }
+      );
+
+      // Select pikachu
+      await selectOptionsByName(["pikachu"]);
     });
+
+    await step("Verify pikachu tag exists", async () => {
+      await verifyTagsExist(canvas.getByRole("group"), ["pikachu"]);
+    });
+
+    await step("Search for 'char' (which doesn't match pikachu)", async () => {
+      const input = canvas.getByRole("combobox");
+      await userEvent.clear(input);
+      await userEvent.type(input, "char");
+
+      // Wait for new results
+      await waitFor(
+        () => {
+          // charmander should be in results
+          expect(findOptionByText("charmander")).toBeTruthy();
+          // pikachu should not
+          expect(findOptionByText("pikachu")).toBeUndefined();
+        },
+        { timeout: 5000 }
+      );
+    });
+
+    await step("Verify pikachu tag still exists (persisted)", async () => {
+      // The key test: pikachu tag should still be visible
+      // even though it's not in the current search results
+      await verifyTagsExist(canvas.getByRole("group"), ["pikachu"]);
+    });
+
+    await step("Select charmander", async () => {
+      await selectOptionsByName(["charmander"]);
+    });
+
+    await step("Verify both tags exist", async () => {
+      await verifyTagsExist(canvas.getByRole("group"), [
+        "pikachu",
+        "charmander",
+      ]);
+    });
+
+    await step("Search for 'pika' again", async () => {
+      const input = canvas.getByRole("combobox");
+      await userEvent.clear(input);
+      await userEvent.type(input, "pika");
+
+      // Wait for results
+      await waitFor(
+        () => {
+          expect(findOptionByText("pikachu")).toBeTruthy();
+        },
+        { timeout: 5000 }
+      );
+    });
+
     await step(
-      "Multi Select option groups are rendered with proper roles",
-      async () => {
-        // Focus combobox
-        multiSelect.focus();
-        // Open popover
-        await userEvent.keyboard("{ArrowDown}");
-        // Find sections
-        const groups = document.querySelectorAll(
-          '[role="listbox"] [role="group"]'
-        );
-        await expect(groups.length).toBe(2);
-        // Check section labels
-        const groupLabels = document.querySelectorAll('[role="presentation"]');
-        await expect(groupLabels[0]).toHaveTextContent("Fruits");
-        await expect(groupLabels[1]).toHaveTextContent("Vegetables");
-        // Close popover for next test
-        await closePopover();
-      }
-    );
-    await step(
-      "Multi Select options are filtered correctly when user enters text",
-      async () => {
-        // Focus combobox
-        multiSelect.focus();
-        // Open popover
-        await userEvent.keyboard("{ArrowDown}");
-        // Hit 'a' key
-        await userEvent.keyboard("{a}");
-        let options = getListboxOptions();
-        // There are 5 options with 'a' in them
-        await expect(options.length).toBe(5);
-        // There are options with 'a' in both sections
-        let groups = document.querySelectorAll(
-          '[role="listbox"] [role="group"]'
-        );
-        await expect(groups.length).toBe(2);
-        // Hit 'p' key
-        await userEvent.keyboard("{p}");
-        options = getListboxOptions();
-        // There is only one option with 'ap'
-        await expect(options.length).toBe(1);
-        await expect(findOptionByText("Apple")).toBeInTheDocument();
-        // there is only one section displayed
-        groups = document.querySelectorAll('[role="listbox"] [role="group"]');
-        await expect(groups.length).toBe(1);
-        const groupLabels = document.querySelectorAll('[role="presentation"]');
-        await expect(groupLabels[0]).toHaveTextContent("Fruits");
-        // Clear input and close popover for next test
-        const filterInput = getFilterInput();
-        await userEvent.clear(filterInput);
-        await closePopover();
-      }
-    );
-    await step(
-      "Multi Select options can be selected from multiple sections",
-      async () => {
-        // Focus combobox
-        multiSelect.focus();
-        // Open popover
-        await userEvent.keyboard("{ArrowDown}");
-        // Select apple option in fruits section
-        await selectOptionsByName(["Apple"]);
-        // TagList should have apple tag
-        await verifyTagsExist(multiSelect, ["Apple"]);
-        // Apple option should be selected
-        await verifyOptionsSelected(["Apple"], true);
-        // Select carrot option in vegetables section
-        const carrotOption = findOptionByText("Carrot");
-        await userEvent.click(carrotOption!);
-        // TagList should have apple and carrot tag
-        await verifyTagsExist(multiSelect, ["Apple", "Carrot"]);
-        // Apple and carrot options should be selected
-        await verifyOptionsSelected(["Apple", "Carrot"], true);
-        // All other options should not be selected
-        await verifyOptionsSelected(
-          ["Banana", "Orange", "Broccoli", "Avocado", "Cucumber"],
-          false
-        );
-        // Close popover for next test
-        await closePopover();
-      }
-    );
-    await step(
-      "Multi select selected option can be removed by pressing its' tag's remove button",
+      "Verify both tags still exist and selection is maintained",
       async () => {
-        // Focus combobox
-        multiSelect.focus();
-        // Remove carrot tag
-        const tagList = await getTagList(multiSelect);
-        const carrotTag = tagList.childNodes[1] as HTMLElement;
-        const removeButton = within(carrotTag).getByRole("button", {
-          name: /remove tag carrot/i,
-        });
-        await userEvent.click(removeButton);
-        // Verify carrot tag is removed
-        await expect(carrotTag).not.toBeInTheDocument();
-        // Verify apple tag exists
-        await verifyTagsExist(multiSelect, ["Apple"]);
-        // Open popover
-        await userEvent.keyboard("{ArrowDown}");
-        // Verify Apple is selected
-        await verifyOptionsSelected(["Apple"], true);
-        // Verify all other options not selected
-        await verifyOptionsSelected(
-          ["Banana", "Orange", "Carrot", "Broccoli", "Avocado", "Cucumber"],
-          false
-        );
-        // Close popover for next test
-        await closePopover();
+        // Both tags should still be there
+        await verifyTagsExist(canvas.getByRole("group"), [
+          "pikachu",
+          "charmander",
+        ]);
+
+        // Pikachu option should show as selected
+        await verifyOptionsSelected(["pikachu"], true);
       }
     );
+
     await step(
-      "Multi select selected option can be removed by selecting its option",
+      "Verify both options are visible and selection is maintained when there is no input value",
       async () => {
-        // Focus combobox
-        multiSelect.focus();
-        const tagList = await getTagList(multiSelect);
-        const appleTag = tagList.childNodes[0] as HTMLElement;
-        // Verify appleTag exists
-        await expect(appleTag).toBeInTheDocument();
-        // Open popover
-        await userEvent.keyboard("{ArrowDown}");
-        // Select Apple option
-        await selectOptionsByName(["Apple"]);
-        // Verify apple tag is removed
-        await expect(appleTag).not.toBeInTheDocument();
-        // Verify all options not selected
-        await verifyOptionsSelected(
-          [
-            "Apple",
-            "Banana",
-            "Orange",
-            "Carrot",
-            "Broccoli",
-            "Avocado",
-            "Cucumber",
-          ],
-          false
-        );
-        // Close popover for next test
-        await closePopover();
+        const input = canvas.getByRole("combobox");
+        await userEvent.clear(input);
+
+        await verifyOptionsSelected(["pikachu", "charmander"], true);
       }
     );
   },
 };
 
 /**
- * Complex Options with Descriptions Example
- * Demonstrates handling item objects that do not have an `id` key.  An `id` key is necessary to allow the selection of items in the dropdown.
- * When there is no `id` key:
- * - `<ComboBox.Option>` the `id` prop must be set on to the name of the item key that can be used instead
- * - `<ComboBox.Root>` multiselect: the `itemId` prop must be set to match the `id` prop passed to `<ComboBox.Option>`
- *
- * Demonstrates handling item objects that do not have a `name` key.  A `name` key is necessary to allow filtering in the dropdown and displaying selected values in the multi-select.
- * When there is no `name` key:
- * - `<ComboBox.Option>` the `textValue` prop must be set on to the name of the item key that can be used to display the option
- * - `<ComboBox.Root>` multiselect: the `itemValue` prop must be set to match the `textValue` prop passed to `<ComboBox.Option>`
- *
- * Demonstrates options with rich content including descriptions for both single and multi-select
+ * Demonstrates custom option creation in async multi-select mode.
+ * Tests that:
+ * 1. Users can create custom options by pressing Enter on non-matching text
+ * 2. Created options are added to the selection
+ * 3. Created options persist across searches
+ * 4. onCreateOption callback is triggered
  */
-export const ComplexOptions: Story = {
+export const AsyncMultiSelectCustomOptions: Story = {
   render: () => {
-    const PlanOptionComponent = ({ item }: { item: PlanOption }) => (
-      <Flex direction="column" gap="100">
-        <Flex justify="space-between" align="center" fontWeight="bold">
-          <Text slot="label">{item.type}</Text>
-          <Text color="positive.11">{item.price}</Text>
-        </Flex>
-        <Text slot="description" color="neutral.12">
-          {item.description}
-        </Text>
-        <Text textStyle="xs" lineHeight="400" color="neutral.11">
-          {item.features.join(" • ")}
-        </Text>
-      </Flex>
-    );
+    const [createdOptions, setCreatedOptions] = useState<string[]>([]);
+    const getPokemonValue = useCallback((pokemon: Pokemon) => pokemon.name, []);
 
     return (
-      <Stack direction="row" gap="400">
-        <FormField.Root alignSelf={"flex-start"}>
-          <FormField.Label>Single Select Plan</FormField.Label>
-          <FormField.Input>
-            <ComboBox.Root
-              defaultItems={complexOptionsWithGroups}
-              placeholder="Choose a plan..."
-            >
-              {(group) => (
-                <ComboBox.OptionGroup label={group.name} items={group.children}>
-                  {(item) => (
-                    <ComboBox.Option id={item.uuid} textValue={item.type}>
-                      <PlanOptionComponent item={item} />
-                    </ComboBox.Option>
-                  )}
-                </ComboBox.OptionGroup>
-              )}
-            </ComboBox.Root>
-          </FormField.Input>
-          <FormField.Description>
-            <Text as="pre">
-              Combobox.Root: itemId and itemValue not necessary in single-select
-            </Text>
-            <Text as="pre">
-              Combobox.Option: id=item.uuid, textValue=item.type
-            </Text>
-          </FormField.Description>
-        </FormField.Root>
-        <FormField.Root alignSelf={"flex-start"}>
-          <FormField.Label>Multi-Select Plans</FormField.Label>
+      <Stack direction="column" gap="400" width="500px">
+        <FormField.Root>
+          <FormField.Label>
+            Create custom Pokemon (async + custom options)
+          </FormField.Label>
           <FormField.Input>
-            <ComboBox.Root
-              defaultItems={complexOptionsWithGroups}
+            <ComboBox.Root<Pokemon>
+              placeholder="Type to search or create..."
+              getKey={getPokemonValue}
+              getTextValue={getPokemonValue}
               selectionMode="multiple"
-              placeholder="Compare multiple plans..."
-              itemId="uuid"
-              itemValue="type"
+              allowsCustomOptions={true}
+              getNewOptionData={(inputValue) => ({
+                name: inputValue,
+                url: `custom-${inputValue}`,
+              })}
+              onCreateOption={(newOption) => {
+                setCreatedOptions((prev) => [...prev, newOption.name]);
+              }}
+              async={{
+                load: async (filterText, signal) => {
+                  const response = await fetch(
+                    `https://pokeapi.co/api/v2/pokemon?limit=1000`,
+                    { signal }
+                  );
+
+                  if (!response.ok) {
+                    throw new Error(`HTTP error! status: ${response.status}`);
+                  }
+
+                  const data = await response.json();
+                  const filtered = data.results.filter((p: Pokemon) =>
+                    p.name.toLowerCase().includes(filterText.toLowerCase())
+                  );
+                  return filtered.slice(0, 50);
+                },
+                debounce: 300,
+              }}
             >
-              {(group) => (
-                <ComboBox.OptionGroup label={group.name} items={group.children}>
-                  {(item) => (
-                    <ComboBox.Option id={item.uuid} textValue={item.type}>
-                      <PlanOptionComponent item={item} />
+              <ComboBox.Trigger />
+              <ComboBox.Popover>
+                <ComboBox.ListBox>
+                  {(pokemon: Pokemon) => (
+                    <ComboBox.Option>
+                      <PokemonOption pokemon={pokemon} />
                     </ComboBox.Option>
                   )}
-                </ComboBox.OptionGroup>
-              )}
+                </ComboBox.ListBox>
+              </ComboBox.Popover>
             </ComboBox.Root>
           </FormField.Input>
           <FormField.Description>
-            <Text as="pre">Combobox.Root: itemId=uuid itemValue=type</Text>
-            <Text as="pre">
-              Combobox.Option: id=item.uuid, textValue=item.type
-            </Text>
+            Search for existing Pokemon or type a custom name and press Enter to
+            create!
+            {createdOptions.length > 0 &&
+              ` | Created: ${createdOptions.join(", ")}`}
           </FormField.Description>
         </FormField.Root>
       </Stack>
     );
   },
+
   play: async ({ canvasElement, step }) => {
     const canvas = within(canvasElement);
-    const singleSelect: HTMLInputElement = await canvas.findByRole("combobox", {
-      name: /single select plan/i,
+
+    await step("Search for 'pika' and select pikachu", async () => {
+      const input = canvas.getByRole("combobox");
+      await userEvent.clear(input);
+      await userEvent.type(input, "pika");
+
+      // Wait for results
+      await waitFor(
+        () => {
+          expect(findOptionByText("pikachu")).toBeTruthy();
+        },
+        { timeout: 5000 }
+      );
+
+      // Select pikachu
+      await selectOptionsByName(["pikachu"]);
     });
-    const multiSelect = await canvas.findByRole("combobox", {
-      name: /multi-select plans/i,
+
+    await step("Type custom option 'MyCustomMon' and press Enter", async () => {
+      const input = canvas.getByRole("combobox");
+      await userEvent.clear(input);
+      await userEvent.type(input, "MyCustomMon");
+
+      // Wait for async search to complete (no results expected)
+      await waitFor(
+        () => {
+          // Input should have the typed value
+          expect(input).toHaveValue("MyCustomMon");
+        },
+        { timeout: 2000 }
+      );
+
+      // Press Enter to create the custom option
+      await userEvent.keyboard("{Enter}");
     });
-    await step("Options display labels and descriptions", async () => {
-      singleSelect.focus();
-      await userEvent.keyboard("{ArrowDown}");
-      const starterPlanOption = findOptionByText("Starter Plan");
-      await expect(
-        starterPlanOption?.querySelector('[slot="label"]')
-      ).toHaveTextContent("Starter Plan");
-      await expect(
-        starterPlanOption?.querySelector('[slot="description"]')
-      ).toHaveTextContent("Great for individuals and small projects");
-      // Close popover for next test
-      await closePopover();
-    });
-    await step("single select displays options in popover", async () => {
-      // Focus the input
-      singleSelect.focus();
-      // Open the popover
-      await userEvent.keyboard("{ArrowDown}");
-      // Check that there are the expected number of options
-      await expect(getListboxOptions().length).toBe(4);
-      // Close popover for next test
-      await closePopover();
+
+    await step("Verify custom option was created and selected", async () => {
+      // Custom option should appear as a tag
+      await waitFor(() => {
+        const customTag = canvas.queryByText("MyCustomMon");
+        expect(customTag).toBeInTheDocument();
+      });
+
+      // Original pikachu tag should still exist
+      expect(canvas.queryByText("pikachu")).toBeInTheDocument();
+
+      // Description should show the created option
+      await waitFor(() => {
+        const description = canvas.queryByText(/Created:/i);
+        expect(description).toBeInTheDocument();
+        expect(description?.textContent).toContain("MyCustomMon");
+      });
     });
+
     await step(
-      "single select filters options and allows for selection when user enters text in input",
+      "Search for 'char' to verify custom option persists",
       async () => {
-        singleSelect.focus();
-        // Type 's'
-        await userEvent.keyboard("{s}");
-        // 'Premium Plan' option should be filtered out
-        await expect(getListboxOptions().length).toBe(3);
-        // Type 't'
-        await userEvent.keyboard("{t}");
-        // 'Small Team' and 'Enterprise' plans should be filtered out
-        await expect(getListboxOptions().length).toBe(1);
-        // Select 'Stater Plan' option
-        await selectOptionsByName(["Starter Plan"]);
-        // Popover should be closed
-        await expect(document.querySelector('[role="listbox"]')).toBeNull();
-        await expect(singleSelect.getAttribute("aria-expanded")).toBe("false");
-        // Input value should be 'Starter Plan'
-        await expect(singleSelect.value).toBe("Starter Plan");
-        // 'Starter Plan' option should be selected
-        await userEvent.keyboard("{ArrowDown}");
-        await verifyOptionsSelected(["Starter Plan"], true);
-        // Other options should not be selected
-        await verifyOptionsSelected(
-          ["Enterprise Plan", "Small Team Plan", "Premium Plan"],
-          false
+        const input = canvas.getByRole("combobox");
+        await userEvent.clear(input);
+        await userEvent.type(input, "char");
+
+        // Wait for charmander results
+        await waitFor(
+          () => {
+            const charmanderOption = findOptionByText("charmander");
+            expect(charmanderOption).toBeTruthy();
+          },
+          { timeout: 5000 }
         );
-        // Close popover for next test
-        await closePopover();
+
+        // Custom tag should still be visible
+        expect(canvas.queryByText("MyCustomMon")).toBeInTheDocument();
+        expect(canvas.queryByText("pikachu")).toBeInTheDocument();
       }
     );
-    await step("multi select displays options in popover", async () => {
-      // Focus the component
-      multiSelect.focus();
-      // Open the popover
-      await userEvent.keyboard("{ArrowDown}");
-      // Check that there are the expected number of options
-      await expect(getListboxOptions().length).toBe(4);
-      // Close popover for next test
-      await closePopover();
+
+    await step("Create another custom option 'AnotherCustom'", async () => {
+      const input = canvas.getByRole("combobox");
+      await userEvent.clear(input);
+      await userEvent.type(input, "AnotherCustom{Enter}");
+
+      // Verify both custom tags exist
+      await waitFor(() => {
+        expect(canvas.queryByText("MyCustomMon")).toBeInTheDocument();
+        expect(canvas.queryByText("AnotherCustom")).toBeInTheDocument();
+        expect(canvas.queryByText("pikachu")).toBeInTheDocument();
+      });
+
+      // Description should show both created options
+      await waitFor(() => {
+        const description = canvas.queryByText(/Created:/i);
+        expect(description?.textContent).toContain("MyCustomMon");
+        expect(description?.textContent).toContain("AnotherCustom");
+      });
     });
-    await step(
-      "multi select filters options and allows for selection when user enters text in input",
-      async () => {
-        multiSelect.focus();
-        // Open popover
-        await userEvent.keyboard("{ArrowDown}");
-        // Type 's'
-        await userEvent.keyboard("{s}");
-        // 'Premium Plan' option should be filtered out
-        await expect(getListboxOptions().length).toBe(3);
-        // Select  'Starter Plan' option in 'individual plans' section and 'Enterprise Plan' and 'Small Team Plan' in business plans section
-        await selectOptionsByName([
-          "Starter Plan",
-          "Enterprise Plan",
-          "Small Team Plan",
-        ]);
-        // TagsList should include tags for all 3 selected plans
-        await verifyTagsExist(multiSelect, [
-          "Starter Plan",
-          "Enterprise Plan",
-          "Small Team Plan",
-        ]);
-        // Clear filter input
-        await userEvent.clear(getFilterInput());
-        // 3 options should be selected
-        await verifyOptionsSelected(
-          ["Starter Plan", "Enterprise Plan", "Small Team Plan"],
-          true
+
+    await step("Verify all tags can be removed", async () => {
+      // Remove AnotherCustom tag
+      const anotherCustomTag = canvas.queryByText("AnotherCustom");
+      if (anotherCustomTag) {
+        const removeButton = anotherCustomTag.parentElement?.querySelector(
+          '[aria-label*="Remove"]'
         );
-        // Premium plan option should not be selected
-        await verifyOptionsSelected(["Premium Plan"], false);
-        // Close popover for next test
-        await closePopover();
+        if (removeButton) {
+          await userEvent.click(removeButton);
+        }
       }
-    );
-    await step("multi select tags can be removed", async () => {
-      const tagList = await getTagList(multiSelect);
-      const enterpriseTag = tagList.childNodes[1] as HTMLElement;
-      const removeButton = within(enterpriseTag).getByRole("button", {
-        name: /remove tag enterprise plan/i,
+
+      // Verify it's removed
+      await waitFor(() => {
+        expect(canvas.queryByText("AnotherCustom")).not.toBeInTheDocument();
       });
-      await userEvent.click(removeButton);
-      // TagsList should include tags for Starter Plan and Small Team Plan
-      await verifyTagsExist(multiSelect, ["Starter Plan", "Small Team Plan"]);
-      // Open popover
-      await userEvent.keyboard("{ArrowDown}");
-      // 2 options should be selected
-      await verifyOptionsSelected(["Starter Plan", "Small Team Plan"], true);
-      // Premium plan and Enterprise plan should not be selected
-      await verifyOptionsSelected(["Premium Plan", "Enterprise Plan"], false);
-      // Close popover for next test
-      await closePopover();
+
+      // Other tags should still exist
+      expect(canvas.queryByText("MyCustomMon")).toBeInTheDocument();
+      expect(canvas.queryByText("pikachu")).toBeInTheDocument();
     });
   },
 };
 
+// ============================================================
+// LAYOUT STRUCTURE TESTS
+// ============================================================
+
 /**
- * Async Loading Example
- * Demonstrates fetching data from an API with search functionality
- * - for single-select to display options on initial search, the `allowsEmptyCollection` prop must be `true`
-   - when `allowsEmptyCollection` is true, it is advisable to also provide a component to display via the `renderEmptyState` prop
- `
+ * Layout: Leading Element
+ * Tests that leading element (icon) displays correctly when provided
  */
-export const AsyncLoading: Story = {
+export const LayoutLeadingElement: Story = {
   render: () => {
-    const singleSelectState = useAsyncList<{ id: number; name: string }>({
-      async load() {
-        // Add 500ms delay before returning results, so that we can test loading state reliably
-        await new Promise((resolve) => setTimeout(resolve, 500));
-        return { items: options };
-      },
-    });
-    const multiSelectState = useAsyncList<{ id: number; name: string }>({
-      async load() {
-        // Add 500ms delay before returning results, so that we can test loading state reliably
-        await new Promise((resolve) => setTimeout(resolve, 500));
-        return { items: options };
-      },
-    });
     return (
-      <Stack direction="row" gap="400">
-        <FormField.Root alignSelf={"flex-start"}>
-          <FormField.Label>Single Select Async</FormField.Label>
-          <FormField.Input>
-            <ComboBox.Root
-              defaultItems={singleSelectState.items}
-              // Workaround for known combobox bug (single select), allowsEmptyCollection should be set for async loaded items to trigger opening the dropdown on initial load
-              // https://github.com/adobe/react-spectrum/issues/5234
-              allowsEmptyCollection={true}
-              renderEmptyState={() => (
-                <Text color="neutral.11" fontStyle="italic">
-                  {singleSelectState.loadingState === "loading"
-                    ? "loading..."
-                    : "no results"}
-                </Text>
-              )}
-              isLoading={singleSelectState.loadingState === "loading"}
-              placeholder="select a character..."
-            >
-              {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
-            </ComboBox.Root>
-          </FormField.Input>
-        </FormField.Root>
-        <FormField.Root alignSelf={"flex-start"}>
-          <FormField.Label>Multi-Select Async</FormField.Label>
-          <FormField.Input>
-            <ComboBox.Root
-              defaultItems={multiSelectState.items}
-              isLoading={multiSelectState.loadingState === "loading"}
-              selectionMode="multiple"
-              placeholder="select characters..."
-            >
-              {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
-            </ComboBox.Root>
-          </FormField.Input>
-        </FormField.Root>
-      </Stack>
+      <ComposedComboBox
+        aria-label="Combobox with leading icon"
+        items={simpleOptions}
+        leadingElement={<Search aria-hidden="true" />}
+      />
     );
   },
-  play: async ({ canvasElement, step }) => {
-    const canvas = within(canvasElement);
-    const singleSelect: HTMLInputElement = await canvas.findByRole("combobox", {
-      name: /single select async/i,
-    });
-    const multiSelect = await canvas.findByRole("combobox", {
-      name: /multi-select async/i,
-    });
-    await step(
-      "loading spinner is displayed when options are loaded",
-      async () => {
-        await within(singleSelect.parentElement!).findByTestId(
-          "nimbus-combobox-loading"
-        );
-        await within(multiSelect).findByTestId("nimbus-combobox-loading");
-      }
-    );
-    await step(
-      "single select options are displayed when loaded, and are selectable",
-      async () => {
-        singleSelect.focus();
-        await userEvent.keyboard("{k}");
-        // Popover is displayed
-        const listbox = document.querySelector(
-          '[role="listbox"]'
-        ) as HTMLElement;
-        await expect(listbox).toBeInTheDocument();
-        // Options are displayed
-        await within(listbox).findByRole("option", { name: /koala/i });
-        // Options are filtered based on input
-        await expect(getListboxOptions().length).toBe(3);
-        // Select Koala option
-        await selectOptionsByName(["Koala"]);
-        // Input value should be koala
-        await expect(singleSelect.value).toBe("Koala");
-        // Koala option is selected
-        await userEvent.keyboard("{ArrowDown}");
-        await verifyOptionsSelected(["Koala"], true);
-        // Close popover for next test
-        await closePopover();
-      }
-    );
 
-    await step(
-      "multi select options are displayed when loaded, and are selectable",
-      async () => {
-        multiSelect.focus();
-        await userEvent.keyboard("{k}");
-        // Popover is displayed
-        const listbox = document.querySelector(
-          '[role="listbox"]'
-        ) as HTMLElement;
-        await expect(listbox).toBeInTheDocument();
-        // Options are displayed
-        await within(listbox).findByRole("option", { name: /koala/i });
-        // Options are filtered based on input
-        await expect(getListboxOptions().length).toBe(3);
-        // Select Koala option
-        await selectOptionsByName(["Koala"]);
-        // Koala tag is visible
-        await verifyTagsExist(multiSelect, ["Koala"]);
-        // Koala option is selected
-        await verifyOptionsSelected(["Koala"], true);
-        // Close popover for next test
-        await closePopover();
-      }
+  play: async ({ canvasElement }) => {
+    // Verify SVG icon is present (from the Search icon in leadingElement), grabs the first svg
+    const svgIcon = canvasElement.querySelector("svg");
+    expect(svgIcon?.parentElement).toHaveClass(
+      "nimbus-combobox__leadingElement"
     );
   },
 };
+
 /**
- * Create Custom Value Example
- * Demonstrates custom value creation and validation for both single and multi-select
- */
-export const CreateCustomValue: Story = {
-  render: () => {
-    // Single select state
-    const [singleSelectedItem, setSingleSelectedItem] = useState<Key | null>(
-      null
-    );
-    const [singleCustomItems, setSingleCustomItems] = useState<
-      Array<{ id: string; name: string }>
-    >([]);
-    const [singleInputValue, setSingleInputValue] = useState("");
-    // Multi-select state
-    const [multiSelectedItems, setMultiSelectedItems] = useState<Selection>(
-      new Set()
-    );
-    const [multiCustomItems, setMultiCustomItems] = useState<
-      Array<{ id: string; name: string }>
-    >([]);
-    const [multiInputValue, setMultiInputValue] = useState("");
-
-    const singleAllItems = useMemo(
-      () => [...options, ...singleCustomItems],
-      [singleCustomItems]
-    );
-    const multiAllItems = useMemo(
-      () => [...options, ...multiCustomItems],
-      [multiCustomItems]
-    );
-    const handleSingleSelectionChange = (key: Key | null) => {
-      const nextInputValue =
-        singleAllItems.find((o) => o.id === key)?.name ?? "";
-      setSingleSelectedItem(key);
-      setSingleInputValue(nextInputValue);
-    };
-    const handleSingleCustomValue = (value: string) => {
-      mockFn();
-      // Add custom item
-      const newItem = { id: `single-custom-${Date.now()}`, name: value };
-      setSingleCustomItems((prev) => [...prev, newItem]);
-      setSingleSelectedItem(newItem.id);
-    };
-    const handleMultiCustomValue = (value: string) => {
-      mockFn();
-      // Add custom item
-      const newItem = { id: `multi-custom-${Date.now()}`, name: value };
-      setMultiCustomItems((prev) => [...prev, newItem]);
-      setMultiSelectedItems((prev) => {
-        const newSelection = new Set(prev);
-        newSelection.add(newItem.id);
-        return newSelection;
-      });
-    };
-    // Input change handlers
-    const handleSingleInputChange = (value: string) => {
-      setSingleInputValue(value);
-    };
-    const handleMultiInputChange = (value: string) => {
-      setMultiInputValue(value);
-    };
-
-    return (
-      <Stack direction="row" gap="400">
-        <FormField.Root alignSelf={"flex-start"}>
-          <FormField.Label>Single Select with Custom Values</FormField.Label>
-          <FormField.Input>
-            <ComboBox.Root
-              allowsCustomValue
-              onSubmitCustomValue={handleSingleCustomValue}
-              defaultItems={singleAllItems}
-              selectedKey={singleSelectedItem}
-              onSelectionChange={handleSingleSelectionChange}
-              inputValue={singleInputValue}
-              onInputChange={handleSingleInputChange}
-              placeholder="Select or create an item..."
-            >
-              {(item) => (
-                <ComboBox.Option
-                  key={item.id}
-                  id={item.id}
-                  textValue={item.name}
-                >
-                  {item.name}
-                  {singleCustomItems.some((custom) => custom.id === item.id) &&
-                    " (Custom)"}
-                </ComboBox.Option>
-              )}
-            </ComboBox.Root>
-          </FormField.Input>
-        </FormField.Root>
-        <FormField.Root alignSelf={"flex-start"}>
-          <FormField.Label>Multi-Select with Custom Values</FormField.Label>
-          <FormField.Input>
-            <ComboBox.Root
-              allowsCustomValue
-              onSubmitCustomValue={handleMultiCustomValue}
-              defaultItems={multiAllItems}
-              selectionMode="multiple"
-              selectedKeys={multiSelectedItems}
-              onSelectionChange={setMultiSelectedItems}
-              inputValue={multiInputValue}
-              onInputChange={handleMultiInputChange}
-              placeholder="Select or create items..."
-            >
-              {(item) => (
-                <ComboBox.Option
-                  key={item.id}
-                  id={item.id}
-                  textValue={item.name}
-                >
-                  {item.name}
-                  {multiCustomItems.some((custom) => custom.id === item.id) &&
-                    " (Custom)"}
-                </ComboBox.Option>
-              )}
-            </ComboBox.Root>
-          </FormField.Input>
-        </FormField.Root>
-      </Stack>
+ * Layout: Input Field Visibility
+ * Tests that input field is visible and functional
+ */
+export const LayoutInputField: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
     );
   },
-  play: async ({ canvasElement, step }) => {
+
+  play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    const singleSelect: HTMLInputElement = await canvas.findByRole("combobox", {
-      name: /single select with custom values/i,
-    });
-    const multiSelect = await canvas.findByRole("combobox", {
-      name: /multi-select with custom values/i,
-    });
 
-    await step(
-      "single select allows setting a custom value when the submitted value does not match an existing option",
-      async () => {
-        singleSelect.focus();
-        // Type in string that does not match any options
-        await userEvent.keyboard("koa");
-        // Create custom 'koa' option by hitting 'enter'
-        await userEvent.keyboard("{Enter}");
-        // Check that onCreateCustomValue has been called
-        await expect(mockFn).toHaveBeenCalled();
-      }
-    );
-    await step(
-      "single select does not allow setting a custom value when the submitted value matches an existing option",
-      async () => {
-        mockFn.mockClear();
-        singleSelect.focus();
-        // Clear input
-        await userEvent.clear(singleSelect);
-        // Type in string that does matches an option
-        await userEvent.keyboard("koala");
-        // Select 'koala' option by hitting 'enter'
-        await userEvent.keyboard("{Enter}");
-        // Check that onCreateCustomValue has not been called
-        await expect(mockFn).not.toHaveBeenCalled();
-      }
-    );
-    await step(
-      "multi select allows setting a custom value when the submitted value does not match an existing option",
-      async () => {
-        mockFn.mockClear();
-        multiSelect.focus();
-        // Type in string that does not match any options
-        await userEvent.keyboard("koa");
-        // Create custom 'koa' option by hitting 'enter'
-        await userEvent.keyboard("{Enter}");
-        // Check that onCreateCustomValue has been called
-        await expect(mockFn).toHaveBeenCalled();
-      }
+    // Find the input
+    const input = canvas.getByRole("combobox");
+
+    // Input should be visible
+    expect(input).toBeVisible();
+
+    // Input should be enabled (not disabled)
+    expect(input).not.toBeDisabled();
+
+    // Input should accept focus
+    await userEvent.click(input);
+    expect(input).toHaveFocus();
+  },
+};
+
+/**
+ * Layout: Toggle Button
+ * Tests that toggle button displays and is clickable
+ */
+export const LayoutToggleButton: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
     );
-    await step(
-      "single select does not allow setting a custom value when the submitted value matches an existing option",
-      async () => {
-        mockFn.mockClear();
-        // Clear input
-        await userEvent.clear(getFilterInput());
-        // Type in string that does matches an option
-        await userEvent.keyboard("koala");
-        // Select 'koala' option by hitting 'enter'
-        await userEvent.keyboard("{Enter}");
-        // Check that onCreateCustomValue has not been called
-        await expect(mockFn).not.toHaveBeenCalled();
-      }
+  },
+
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Get toggle button
+    const toggleButton = canvas.getByLabelText(/toggle options/i);
+
+    // Toggle button should be visible and enabled
+    expect(toggleButton).toBeVisible();
+    expect(toggleButton).toBeEnabled();
+
+    // Click to open menu
+    await userEvent.click(toggleButton);
+
+    // Menu should appear
+    await waitFor(() => {
+      const listbox = getListBox(document);
+      expect(listbox).toBeInTheDocument();
+    });
+
+    // Click again to close
+    await userEvent.click(toggleButton);
+
+    // Menu should disappear
+    await waitFor(() => {
+      const closedListbox = getListBox(document);
+      expect(closedListbox).not.toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Layout: Clear Button Visibility
+ * Tests that clear button displays when selection exists and hides when cleared
+ */
+export const LayoutClearButton: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([1]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
     );
   },
+
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Clear button should be visible when selection exists
+    const clearButton = canvas.getByLabelText(/clear selection/i);
+    expect(clearButton).toBeVisible();
+    expect(clearButton).toBeEnabled();
+
+    // Click clear button
+    await userEvent.click(clearButton);
+
+    // Clear button should be hidden after clearing (display: none)
+    await waitFor(() => {
+      const computedStyle = window.getComputedStyle(clearButton);
+      expect(computedStyle.display).toBe("none");
+    });
+  },
 };
 
 /**
- * Disabled and Read-Only Comboboxes Example
- * Demonstrates disabled and read-only comboboxes side by side for both single and multi-select modes
- * - Disabled comboboxes do not allow any interaction and have disabled styling
- * - Read-only comboboxes can be focused but do not allow any updates
- */
-export const DisabledAndReadOnlyComboboxes: Story = {
-  render: () => {
-    const [variant, setVariant] = useState<"solid" | "ghost">("solid");
-    return (
-      <Stack direction="column" gap="600">
-        <Stack direction="column" gap="300">
-          <h3>Single Select ComboBoxes</h3>
-          <Stack direction="row" gap="400">
-            <FormField.Root alignSelf={"flex-start"} isDisabled>
-              <FormField.Label>Disabled Single Select</FormField.Label>
-              <FormField.Input>
-                <ComboBox.Root
-                  defaultItems={options}
-                  isDisabled
-                  defaultSelectedKey={2}
-                  variant={variant}
-                  placeholder="This combobox is disabled..."
-                >
-                  {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
-                </ComboBox.Root>
-              </FormField.Input>
-              <FormField.Description>
-                Disabled - cannot interact at all
-              </FormField.Description>
-            </FormField.Root>
-            <FormField.Root alignSelf={"flex-start"} isReadOnly>
-              <FormField.Label>Read-Only Single Select</FormField.Label>
-              <FormField.Input>
-                <ComboBox.Root
-                  defaultItems={options}
-                  isReadOnly
-                  variant={variant}
-                  defaultSelectedKey={2}
-                  placeholder="This combobox is read-only..."
-                >
-                  {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
-                </ComboBox.Root>
-              </FormField.Input>
-              <FormField.Description>
-                Read-only - can focus but not change value
-              </FormField.Description>
-            </FormField.Root>
-          </Stack>
-        </Stack>
-        <Stack direction="column" gap="300">
-          <h3>Multi-Select ComboBoxes</h3>
-          <Stack direction="row" gap="400">
-            <FormField.Root alignSelf={"flex-start"} isDisabled>
-              <FormField.Label>Disabled Multi-Select</FormField.Label>
-              <FormField.Input>
-                <ComboBox.Root
-                  defaultItems={options}
-                  selectionMode="multiple"
-                  isDisabled
-                  variant={variant}
-                  defaultSelectedKeys={new Set([1, 3, 5])}
-                  placeholder="This combobox is disabled..."
-                >
-                  {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
-                </ComboBox.Root>
-              </FormField.Input>
-              <FormField.Description>
-                Disabled - cannot interact at all
-              </FormField.Description>
-            </FormField.Root>
-            <FormField.Root alignSelf={"flex-start"} isReadOnly>
-              <FormField.Label>Read-Only Multi-Select</FormField.Label>
-              <FormField.Input>
-                <ComboBox.Root
-                  defaultItems={options}
-                  selectionMode="multiple"
-                  isReadOnly
-                  variant={variant}
-                  defaultSelectedKeys={new Set([1, 3, 5])}
-                  placeholder="This combobox is read-only..."
-                >
-                  {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
-                </ComboBox.Root>
-              </FormField.Input>
-              <FormField.Description>
-                Read-only - can focus but not change values
-              </FormField.Description>
-            </FormField.Root>
-          </Stack>
-        </Stack>
-        <RadioInput.Root
-          onChange={setVariant as (value: string) => void}
-          value={variant}
-          orientation="horizontal"
-          aria-label="choose variant"
-        >
-          <RadioInput.Option value="solid">Solid</RadioInput.Option>
-          <RadioInput.Option value="ghost">Ghost</RadioInput.Option>
-        </RadioInput.Root>
+ * Layout: Clear Button Hidden Without Selection
+ * Tests that clear button is hidden when no selection exists
+ */
+export const LayoutClearButtonHidden: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Clear button should exist but be hidden (display:none)
+    const clearButton = canvas.getByLabelText(/clear selection/i);
+
+    // Verify it has display:none
+    const computedStyle = window.getComputedStyle(clearButton);
+    expect(computedStyle.display).toBe("none");
+  },
+};
+
+/**
+ * Layout: Full Width Container
+ * Tests that component takes full width of its container
+ */
+export const LayoutFullWidth: Story = {
+  render: () => {
+    return (
+      <Box width="600px">
+        <ComposedComboBox
+          width="full"
+          aria-label="Test combobox in container"
+          items={simpleOptions}
+        />
+      </Box>
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    // Find the combobox root
+    const root = canvasElement.querySelector(
+      ".nimbus-combobox__root"
+    ) as HTMLElement;
+
+    // Verify input exists and is visible
+    expect(root).toBeVisible();
+
+    // Get the computed width of the input element
+    const rootWidth = (root as HTMLElement).offsetWidth;
+
+    expect(rootWidth).toBe(600);
+  },
+};
+
+/**
+ * Layout: Responsive Behavior (Smoke Test)
+ * Tests that layout structure remains intact across different container sizes
+ */
+export const LayoutResponsive: Story = {
+  render: () => {
+    return (
+      <Stack direction="column" gap="400">
+        <Box width="200px">
+          <ComposedComboBox
+            aria-label="Narrow combobox"
+            items={simpleOptions}
+          />
+        </Box>
+        <Box width="400px">
+          <ComposedComboBox
+            aria-label="Medium combobox"
+            items={simpleOptions}
+          />
+        </Box>
+        <Box width="100%">
+          <ComposedComboBox
+            width="full"
+            aria-label="Wide combobox"
+            items={simpleOptions}
+          />
+        </Box>
       </Stack>
     );
   },
-  play: async ({ canvasElement, step }) => {
+
+  play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    const singleSelectDisabled: HTMLInputElement = await canvas.findByRole(
-      "combobox",
-      {
-        name: /disabled single select/i,
-      }
+
+    // This is a smoke test - full responsive testing requires viewport resizing
+    // which is complex in Storybook. This verifies basic structure is intact.
+
+    const inputs = canvas.getAllByRole("combobox");
+
+    // All inputs should be visible and functional regardless of container size
+    for (const input of inputs) {
+      expect(input).toBeVisible();
+      expect(input).not.toBeDisabled();
+    }
+
+    // All toggle buttons should remain accessible
+    const toggleButtons = canvas.getAllByLabelText(/toggle options/i);
+    expect(toggleButtons.length).toBe(3); // One per combobox
+
+    for (const button of toggleButtons) {
+      expect(button).toBeVisible();
+      expect(button).toBeEnabled();
+    }
+  },
+};
+
+// ============================================================
+// MULTI-SELECT TAG DISPLAY TESTS
+// ============================================================
+
+/**
+ * Multi-Select: Tags Display
+ * Tests that selected items display as removable tags in multi-select mode
+ */
+export const MultiSelectTagsDisplay: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([
+      1, 2, 3,
+    ]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Multi-select combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
     );
-    const multiSelectDisabled = await canvas.findByRole("combobox", {
-      name: /disabled multi-select/i,
-    });
-    const singleSelectReadOnly: HTMLInputElement = await canvas.findByRole(
-      "combobox",
-      {
-        name: /read-only single select/i,
-      }
+  },
+
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Verify all three selected items display as tags
+    expect(canvas.getByText("Koala")).toBeInTheDocument();
+    expect(canvas.getByText("Kangaroo")).toBeInTheDocument();
+    expect(canvas.getByText("Platypus")).toBeInTheDocument();
+  },
+};
+
+/**
+ * Multi-Select: Tags Inline With Input
+ * Tests that tags appear inline with the input field
+ */
+export const MultiSelectTagsInline: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([1]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Multi-select combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
     );
-    const multiSelectReadOnly = await canvas.findByRole("combobox", {
-      name: /read-only multi-select/i,
-    });
-    await step(
-      "Disabled comboboxes are not focusable, read-only comboboxes are focusable",
-      async () => {
-        await userEvent.tab();
-        // First tab should skip disabled single select
-        await expect(singleSelectDisabled).not.toHaveFocus();
-        // First tab focuses read only single select
-        await expect(singleSelectReadOnly).toHaveFocus();
-        // Focusing single select does not open listbox
-        await expect(
-          document.querySelector('[role="listbox"]')
-        ).not.toBeInTheDocument();
-        await userEvent.tab();
-        // Second tab skips multi disabled
-        await expect(multiSelectDisabled).not.toHaveFocus();
-        // focusing multi-select does not open listbox
-        await expect(
-          document.querySelector('[role="listbox"]')
-        ).not.toBeInTheDocument();
-      }
+  },
+
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Verify tag is displayed
+    const tag = canvas.getByText("Koala");
+    expect(tag).toBeVisible();
+
+    // Get the input
+    const input = canvas.getByRole("combobox");
+    expect(input).toBeVisible();
+
+    // Input should be focusable even with tags present
+    await userEvent.click(input);
+    expect(input).toHaveFocus();
+  },
+};
+
+/**
+ * Multi-Select: Tags Wrapping
+ * Tests that tags wrap to new lines when space is limited by measuring container height
+ */
+export const MultiSelectTagsWrapping: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([1]);
+
+    return (
+      <Stack direction="column" gap="400">
+        <Box width="300px">
+          <ComposedComboBox
+            aria-label="Single tag combobox"
+            items={simpleOptions}
+            selectionMode="multiple"
+            selectedKeys={selectedKeys}
+            onSelectionChange={setSelectedKeys}
+          />
+        </Box>
+
+        <Box width="300px">
+          <ComposedComboBox
+            aria-label="All tags combobox"
+            items={simpleOptions}
+            selectionMode="multiple"
+            selectedKeys={[1, 2, 3, 4, 5, 6]}
+            onSelectionChange={() => {}}
+          />
+        </Box>
+      </Stack>
     );
-    await step("Disabled single select has disabled attributes", async () => {
-      await expect(singleSelectDisabled).toHaveAttribute("disabled");
-      await expect(singleSelectDisabled).toHaveStyle({
-        pointerEvents: "none",
-      });
-      // the input has the 'combobox' role in the single select, we need to target the wrapper container to check for the not-allowed cursor
-      await expect(singleSelectDisabled.parentElement).toHaveStyle({
-        cursor: "not-allowed",
-      });
-    });
-    await step("Disabled single select cannot be clicked to open", async () => {
-      await userEvent.click(singleSelectDisabled, { pointerEventsCheck: 0 });
-      await expect(getListboxOptions().length).toBe(0);
-      await expect(singleSelectDisabled).toHaveStyle({ pointerEvents: "none" });
-    });
-    await step("Disabled single select buttons are disabled", async () => {
-      const buttons = await within(
-        singleSelectDisabled.parentElement!
-      ).findAllByRole("button");
-      for (let i = 0; i < buttons.length; i++) {
-        await expect(buttons[i]).toHaveStyle({ pointerEvents: "none" });
-        await expect(buttons[i]).toHaveAttribute("disabled");
-      }
+  },
+
+  play: async ({ canvasElement, step }) => {
+    await step("Single tag - baseline height", async () => {
+      // Find the first combobox (single tag)
+      const singleTagRoot = canvasElement.querySelectorAll(
+        ".nimbus-combobox__root"
+      )[0] as HTMLElement;
+
+      expect(singleTagRoot).toBeVisible();
+
+      // Get height with only one tag
+      const singleTagHeight = singleTagRoot.offsetHeight;
+
+      // Store for comparison (should be single line height)
+      expect(singleTagHeight).toBe(40);
     });
-    await step("Disabled multi select has disabled attributes", async () => {
-      await expect(multiSelectDisabled.getAttribute("aria-disabled")).toBe(
-        "true"
-      );
-      await expect(multiSelectDisabled).toHaveStyle({
-        cursor: "not-allowed",
-      });
+
+    await step("All tags - increased height from wrapping", async () => {
+      // Find the second combobox (all 6 tags)
+      const allTagsRoot = canvasElement.querySelectorAll(
+        ".nimbus-combobox__root"
+      )[1] as HTMLElement;
+
+      expect(allTagsRoot).toBeVisible();
+
+      // Get height with all 6 tags
+      const allTagsHeight = allTagsRoot.offsetHeight;
+
+      // With 6 tags in a 300px container, height should be 164px
+      expect(allTagsHeight).toBe(164);
     });
-    await step("Disabled multi select cannot be clicked to open", async () => {
-      await userEvent.click(multiSelectDisabled);
-      await expect(getListboxOptions().length).toBe(0);
+  },
+};
+
+/**
+ * Multi-Select: Tag Remove Button
+ * Tests that each tag shows a remove button and can be removed
+ */
+export const MultiSelectTagRemoval: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([
+      1, 2, 3,
+    ]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Multi-select combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Verify initial tags", async () => {
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Kangaroo")).toBeInTheDocument();
+      expect(canvas.getByText("Platypus")).toBeInTheDocument();
     });
-    await step("Disabled multi select tag group is disabled", async () => {
-      const tagGroup = multiSelectDisabled.childNodes[1] as HTMLElement;
-      await expect(tagGroup.getAttribute("data-disabled")).toBe("true");
-      await expect(tagGroup).toHaveStyle({
-        pointerEvents: "none",
+
+    await step("Each tag has a remove button", async () => {
+      // All three tags should have remove buttons
+      const koalaRemove = canvas.getByRole("button", {
+        name: /remove tag koala/i,
       });
-    });
-    await step("Disabled multi select buttons are disabled", async () => {
-      const buttons = await within(multiSelectDisabled).findAllByRole("button");
-      for (let i = 0; i < buttons.length; i++) {
-        await expect(buttons[i]).toHaveStyle({ pointerEvents: "none" });
-        await expect(buttons[i]).toHaveAttribute("disabled");
-      }
-    });
-    await step("Read Only single select has read-only attributes", async () => {
-      await expect(singleSelectReadOnly).toHaveAttribute("readonly");
-      await expect(singleSelectReadOnly).not.toHaveAttribute("disabled");
-      await expect(singleSelectReadOnly).not.toHaveStyle({
-        pointerEvents: "none",
+      const kangarooRemove = canvas.getByRole("button", {
+        name: /remove tag kangaroo/i,
       });
-      // the input has the 'combobox' role in the single select, we need to target the wrapper container to check for the not-allowed cursor
-      await expect(singleSelectReadOnly.parentElement).not.toHaveStyle({
-        cursor: "not-allowed",
+      const platypusRemove = canvas.getByRole("button", {
+        name: /remove tag platypus/i,
       });
+
+      expect(koalaRemove).toBeVisible();
+      expect(kangarooRemove).toBeVisible();
+      expect(platypusRemove).toBeVisible();
     });
-    await step(
-      "Read Only single select cannot be clicked to open",
-      async () => {
-        await userEvent.click(singleSelectReadOnly);
-        await expect(getListboxOptions().length).toBe(0);
-        await expect(singleSelectReadOnly).not.toHaveStyle({
-          pointerEvents: "none",
-        });
-      }
-    );
-    await step("Read Only single select buttons are disabled", async () => {
-      const buttons = await within(
-        singleSelectReadOnly.parentElement!
-      ).findAllByRole("button");
-      for (let i = 0; i < buttons.length; i++) {
-        await expect(buttons[i]).toHaveStyle({ userSelect: "none" });
-        await expect(buttons[i]).toHaveAttribute("disabled");
-      }
-    });
-    await step("Read Only multi select has readonly attributes", async () => {
-      await expect(multiSelectReadOnly.getAttribute("aria-readonly")).toBe(
-        "true"
-      );
-      await expect(multiSelectReadOnly).not.toHaveAttribute("aria-disabled");
-      await expect(multiSelectReadOnly).not.toHaveStyle({
-        cursor: "not-allowed",
+
+    await step("Remove middle tag (Kangaroo)", async () => {
+      // Find the remove button for Kangaroo tag
+      const removeButton = canvas.getByRole("button", {
+        name: /remove tag kangaroo/i,
       });
-    });
-    await step("Read Only multi select cannot be clicked to open", async () => {
-      await userEvent.click(multiSelectReadOnly);
-      await expect(getListboxOptions().length).toBe(0);
-    });
-    await step("Read Only multi select tag group is not disabled", async () => {
-      const tagGroup = multiSelectReadOnly.childNodes[1] as HTMLElement;
-      await expect(tagGroup).not.toHaveAttribute("data-disabled");
-      await expect(tagGroup).not.toHaveStyle({
-        pointerEvents: "none",
+
+      // Click to remove
+      await userEvent.click(removeButton);
+
+      // Verify Kangaroo is removed
+      await waitFor(() => {
+        expect(canvas.queryByText("Kangaroo")).not.toBeInTheDocument();
       });
-    });
-    await step("Read Only multi select buttons are disabled", async () => {
-      const buttons = await within(multiSelectReadOnly).findAllByRole("button");
-      for (let i = 0; i < buttons.length; i++) {
-        await expect(buttons[i]).toHaveStyle({ userSelect: "none" });
-        await expect(buttons[i]).toHaveAttribute("disabled");
-      }
+
+      // Other tags should still exist
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Platypus")).toBeInTheDocument();
     });
   },
 };
 
 /**
- * Disabled Options Example
- * Demonstrates disabled options in both single and multi-select comboboxes
+ * Multi-Select: Input Accessible After Tags
+ * Tests that input remains accessible and functional after adding multiple tags
  */
-export const DisabledOptions: Story = {
+export const MultiSelectInputAccessible: Story = {
   render: () => {
-    const optionsWithDisabled = [
-      { id: 1, name: "Koala", isDisabled: false },
-      { id: 2, name: "Kangaroo", isDisabled: true },
-      { id: 3, name: "Platypus", isDisabled: false },
-      { id: 4, name: "Bald Eagle", isDisabled: true },
-      { id: 5, name: "Bison", isDisabled: false },
-      { id: 6, name: "Skunk", isDisabled: true },
-    ];
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([
+      1, 2, 3,
+    ]);
 
     return (
-      <Stack direction="row" gap="400">
-        <FormField.Root alignSelf={"flex-start"}>
-          <FormField.Label>Single Select with Disabled Options</FormField.Label>
-          <FormField.Input>
-            <ComboBox.Root
-              defaultItems={optionsWithDisabled}
-              placeholder="Select an animal..."
-            >
-              {(item) => (
-                <ComboBox.Option
-                  key={item.id}
-                  id={item.id}
-                  isDisabled={item.isDisabled}
-                >
-                  {item.name}
-                </ComboBox.Option>
-              )}
-            </ComboBox.Root>
-          </FormField.Input>
-          <FormField.Description>
-            Kangaroo, Bald Eagle, and Skunk are disabled
-          </FormField.Description>
-        </FormField.Root>
-        <FormField.Root alignSelf={"flex-start"}>
-          <FormField.Label>Multi-Select with Disabled Options</FormField.Label>
-          <FormField.Input>
-            <ComboBox.Root
-              defaultItems={optionsWithDisabled}
-              selectionMode="multiple"
-              placeholder="Select multiple animals..."
-            >
-              {(item) => (
-                <ComboBox.Option
-                  key={item.id}
-                  id={item.id}
-                  isDisabled={item.isDisabled}
-                >
-                  {item.name}
-                </ComboBox.Option>
-              )}
-            </ComboBox.Root>
-          </FormField.Input>
-          <FormField.Description>
-            Kangaroo, Bald Eagle, and Skunk are disabled
-          </FormField.Description>
-        </FormField.Root>
-      </Stack>
+      <ComposedComboBox
+        aria-label="Multi-select combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
     );
   },
+
   play: async ({ canvasElement, step }) => {
     const canvas = within(canvasElement);
-    const singleSelect: HTMLInputElement = await canvas.findByRole("combobox", {
-      name: /single select with disabled options/i,
-    });
-    const multiSelect = await canvas.findByRole("combobox", {
-      name: /multi-select with disabled options/i,
-    });
-    const disabledOptions = ["Kangaroo", "Bald Eagle", "Skunk"];
-    await step("Single select can be opened", async () => {
-      singleSelect.focus();
-      await userEvent.keyboard("{ArrowDown}");
-      const listbox = document.querySelector('[role="listbox"]');
-      await expect(listbox).toBeInTheDocument();
-    });
-    await step("Disabled options have aria-disabled attribute", async () => {
-      for (let i = 0; i < disabledOptions.length; i++) {
-        const option = findOptionByText(disabledOptions[i]);
-        await expect(option).toHaveAttribute("aria-disabled", "true");
-      }
-    });
-    await step("Enabled options can be selected", async () => {
-      await selectOptionsByName(["Koala"]);
-      await expect(singleSelect.value).toBe("Koala");
-      await userEvent.keyboard("{ArrowDown}");
-      await verifyOptionsSelected(["Koala"], true);
-    });
-    await step("Disabled options cannot be selected", async () => {
-      await selectOptionsByName(disabledOptions);
-      await expect(singleSelect.value).toBe("Koala");
-      // Close for next test
-      await closePopover();
-    });
-    await step("Disabled options cannot be selected via keyboard", async () => {
-      singleSelect.focus();
-      // Open popover
-      await userEvent.keyboard("{ArrowDown}");
-      // Koala is active option
-      await expect(findOptionByText("Koala")?.getAttribute("id")).toBe(
-        singleSelect.getAttribute("aria-activedescendant")
-      );
-      // Go to next item
-      await userEvent.keyboard("{ArrowDown}");
-      // Kangaroo is skipped
-      await expect(findOptionByText("Kangaroo")?.getAttribute("id")).not.toBe(
-        singleSelect.getAttribute("aria-activedescendant")
-      );
-      // Platypus is active option
-      await expect(findOptionByText("Platypus")?.getAttribute("id")).toBe(
-        singleSelect.getAttribute("aria-activedescendant")
-      );
-      // Close for next test
-      await closePopover();
-    });
-    await step("Multi select can be opened", async () => {
-      multiSelect.focus();
-      await userEvent.keyboard("{ArrowDown}");
-      const listbox = document.querySelector('[role="listbox"]');
-      await expect(listbox).toBeInTheDocument();
-    });
-    await step("Disabled options have aria-disabled attribute", async () => {
-      for (let i = 0; i < disabledOptions.length; i++) {
-        const option = findOptionByText(disabledOptions[i]);
-        await expect(option).toHaveAttribute("aria-disabled", "true");
-      }
+
+    await step("Verify tags are present", async () => {
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Kangaroo")).toBeInTheDocument();
+      expect(canvas.getByText("Platypus")).toBeInTheDocument();
     });
-    await step("Enabled options can be selected", async () => {
-      await selectOptionsByName(["Koala", "Platypus", "Bison"]);
-      await verifyTagsExist(multiSelect, ["Koala", "Platypus", "Bison"]);
-      await verifyOptionsSelected(["Koala", "Platypus", "Bison"], true);
+
+    await step("Input remains focusable", async () => {
+      const input = canvas.getByRole("combobox");
+
+      // Click input
+      await userEvent.click(input);
+      expect(input).toHaveFocus();
     });
-    await step("Disabled options cannot be selected", async () => {
-      await selectOptionsByName(disabledOptions);
-      await verifyOptionsSelected(disabledOptions, false);
-      // Close for next test
-      await closePopover();
+
+    await step("Can type in input with tags present", async () => {
+      const input = canvas.getByRole("combobox");
+
+      // Type to filter
+      await userEvent.type(input, "Bis");
+
+      // Menu should open with filtered results
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+        expect(findOptionByText("Bison")).toBeInTheDocument();
+      });
     });
-    await step("Disabled options cannot be selected via keyboard", async () => {
-      multiSelect.focus();
-      // Open popover
-      await userEvent.keyboard("{ArrowDown}");
-      // Select first option
-      await userEvent.keyboard("{ArrowDown}");
-      // Koala is active option
-      await expect(findOptionByText("Koala")?.getAttribute("id")).toBe(
-        getFilterInput().getAttribute("aria-activedescendant")
-      );
-      // Go to next item
-      await userEvent.keyboard("{ArrowDown}");
-      // Kangaroo is skipped
-      await expect(findOptionByText("Kangaroo")?.getAttribute("id")).not.toBe(
-        getFilterInput().getAttribute("aria-activedescendant")
-      );
-      // Platypus is active option
-      await expect(findOptionByText("Platypus")?.getAttribute("id")).toBe(
-        getFilterInput().getAttribute("aria-activedescendant")
-      );
+
+    await step("Can select additional item", async () => {
+      // Select Bison
+      await selectOptionsByName(["Bison"]);
+
+      // Verify Bison tag appears (all 4 tags should now be present)
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Kangaroo")).toBeInTheDocument();
+      expect(canvas.getByText("Platypus")).toBeInTheDocument();
+      expect(canvas.getByText("Bison")).toBeInTheDocument();
     });
   },
 };
 
+// ============================================================
+// INPUT FIELD BEHAVIOR TESTS
+// ============================================================
+
 /**
- * Form Validation Example
- * Shows advanced validation states and error messaging
+ * Input: Always Visible And Focusable
+ * Tests that input field remains visible and focusable in all states
  */
-export const FormValidation: Story = {
+export const InputAlwaysVisible: Story = {
   render: () => {
-    // Variant state
-    const [variant, setVariant] = useState<"solid" | "ghost">("solid");
-    // Single select state
-    const [selectedValue, setSelectedValue] = useState<Key | null>(null);
-    const [isInvalid, setIsInvalid] = useState(true);
-    const [errorMessage, setErrorMessage] = useState("Please select an option");
-
-    // Multi-select state
-    const [multiSelectedValues, setMultiSelectedValues] = useState<Selection>(
-      new Set()
-    );
-    const [multiIsInvalid, setMultiIsInvalid] = useState(true);
-    const [multiErrorMessage, setMultiErrorMessage] = useState(
-      "Please select at least one option"
-    );
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([
+      1, 2, 3,
+    ]);
 
-    const handleSelectionChange = (key: Key | null) => {
-      setSelectedValue(key);
+    return (
+      <Stack direction="column" gap="400">
+        {/* Empty state */}
+        <ComposedComboBox
+          aria-label="Empty combobox"
+          items={simpleOptions}
+          selectionMode="multiple"
+        />
 
-      // Custom validation logic
-      if (key === null || key === "") {
-        setIsInvalid(true);
-        setErrorMessage("Please select an option");
-      } else if (key === 6) {
-        setIsInvalid(true);
-        setErrorMessage("Skunk is not allowed for safety reasons");
-      } else {
-        setIsInvalid(false);
-        setErrorMessage("");
-      }
-    };
-
-    const handleMultiSelectionChange = (keys: Selection) => {
-      setMultiSelectedValues(keys);
-
-      // Multi-select validation logic
-      if (keys instanceof Set && keys.size === 0) {
-        setMultiIsInvalid(true);
-        setMultiErrorMessage("Please select at least one option");
-      } else if (keys instanceof Set && keys.has(6)) {
-        setMultiIsInvalid(true);
-        setMultiErrorMessage("Skunk is not allowed for safety reasons");
-      } else if (keys instanceof Set && keys.size > 3) {
-        setMultiIsInvalid(true);
-        setMultiErrorMessage("Maximum 3 selections allowed");
-      } else {
-        setMultiIsInvalid(false);
-        setMultiErrorMessage("");
-      }
-    };
-
-    return (
-      <Stack direction="column" gap="600">
-        <Stack direction="row" gap="400">
-          <FormField.Root
-            alignSelf={"flex-start"}
-            isInvalid={isInvalid}
-            isRequired
-          >
-            <FormField.Label>Single Select with Validation</FormField.Label>
-            <FormField.Input>
-              <ComboBox.Root
-                defaultItems={options}
-                selectedKey={selectedValue}
-                onSelectionChange={handleSelectionChange}
-                variant={variant}
-                placeholder="Select an animal..."
-              >
-                {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
-              </ComboBox.Root>
-            </FormField.Input>
-            <FormField.Description>
-              Select 'Skunk' option to trigger invalid selected state
-            </FormField.Description>
-            {errorMessage && <FormField.Error>{errorMessage}</FormField.Error>}
-          </FormField.Root>
-          <FormField.Root
-            alignSelf={"flex-start"}
-            isInvalid={multiIsInvalid}
-            isRequired
-          >
-            <FormField.Label>Multi-Select with Validation</FormField.Label>
-            <FormField.Input>
-              <ComboBox.Root
-                defaultItems={options}
-                selectionMode="multiple"
-                selectedKeys={multiSelectedValues}
-                onSelectionChange={handleMultiSelectionChange}
-                variant={variant}
-                placeholder="Select multiple animals..."
-              >
-                {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
-              </ComboBox.Root>
-            </FormField.Input>
-            <FormField.Description>
-              Select 'Skunk' option to trigger invalid selected state
-            </FormField.Description>
-            {multiErrorMessage && (
-              <FormField.Error>{multiErrorMessage}</FormField.Error>
-            )}
-          </FormField.Root>
-        </Stack>
-        <RadioInput.Root
-          onChange={setVariant as (value: string) => void}
-          value={variant}
-          orientation="horizontal"
-          aria-label="choose variant"
-        >
-          <RadioInput.Option value="solid">Solid</RadioInput.Option>
-          <RadioInput.Option value="ghost">Ghost</RadioInput.Option>
-        </RadioInput.Root>
+        {/* With selections (multi-select) */}
+        <ComposedComboBox
+          aria-label="With tags combobox"
+          items={simpleOptions}
+          selectionMode="multiple"
+          selectedKeys={selectedKeys}
+          onSelectionChange={setSelectedKeys}
+        />
       </Stack>
     );
   },
+
   play: async ({ canvasElement, step }) => {
     const canvas = within(canvasElement);
-    const singleSelect: HTMLInputElement = await canvas.findByRole("combobox", {
-      name: /single select with validation/i,
-    });
-    const multiSelect = await canvas.findByRole("combobox", {
-      name: /multi-select with validation/i,
-    });
 
-    await step("Invalid single select has invalid attributes", async () => {
-      await expect(singleSelect).toHaveAttribute("aria-invalid", "true");
-      await expect(singleSelect).toHaveAttribute("data-invalid", "true");
+    await step("Empty state - input visible and focusable", async () => {
+      const emptyInput = canvas.getByLabelText("Empty combobox");
+
+      expect(emptyInput).toBeVisible();
+      expect(emptyInput).not.toBeDisabled();
+
+      await userEvent.click(emptyInput);
+      expect(emptyInput).toHaveFocus();
     });
-    await step("Invalid single select can be opened and used", async () => {
-      singleSelect.focus();
-      await userEvent.keyboard("{ArrowDown}");
-      await userEvent.keyboard("{Enter}");
-      await expect(singleSelect.value).toBe("Koala");
-      // Close for next test
-      await closePopover();
+
+    await step("With tags - input visible and focusable", async () => {
+      const withTagsInput = canvas.getByLabelText("With tags combobox");
+
+      expect(withTagsInput).toBeVisible();
+      expect(withTagsInput).not.toBeDisabled();
+
+      await userEvent.click(withTagsInput);
+      expect(withTagsInput).toHaveFocus();
     });
-    await step(
-      "Invalid single select updates state when isInvalid is updated",
-      async () => {
-        await expect(singleSelect).not.toHaveAttribute("aria-invalid");
-        await expect(singleSelect).not.toHaveAttribute("data-invalid");
+  },
+};
+
+/**
+ * Input: Wraps to New Line
+ * Tests that input wraps to new line when content area is full (multi-select with many tags)
+ */
+export const InputWrapsToNewLine: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([
+      1, 2, 3, 4, 5, 6,
+    ]);
+
+    return (
+      <Box width="300px">
+        <ComposedComboBox
+          aria-label="Test combobox"
+          items={simpleOptions}
+          selectionMode="multiple"
+          selectedKeys={selectedKeys}
+          onSelectionChange={setSelectedKeys}
+        />
+      </Box>
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Find the root (contains tags and input)
+    const root = canvasElement.querySelector(
+      ".nimbus-combobox__root"
+    ) as HTMLElement;
+
+    expect(root).toBeVisible();
+
+    // Measure trigger height - should be multi-line due to wrapping tags
+    const rootHeight = root.offsetHeight;
+
+    // With 6 tags wrapping, height should be >100px (multiple lines)
+    expect(rootHeight).toBe(164);
+
+    // Input should still be visible and functional
+    const input = canvas.getByRole("combobox");
+    expect(input).toBeVisible();
+    await userEvent.click(input);
+    expect(input).toHaveFocus();
+
+    // Input should be at the bottom of the container
+    const inputHeight = input.offsetHeight;
+    // The offsetTop should be greater than the height in this case
+    expect(input.offsetTop).toBeGreaterThan(inputHeight);
+  },
+};
+
+/**
+ * Input: Placeholder Text Displays
+ * Tests that placeholder text displays when input is empty
+ */
+export const InputPlaceholder: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        placeholder="Search animals..."
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Placeholder visible when empty", async () => {
+      // Input should be empty
+      expect(input.value).toBe("");
+
+      // Placeholder should be set
+      expect(input.placeholder).toBe("Search animals...");
+    });
+
+    await step("Placeholder hidden when typing", async () => {
+      // Type in input
+      await userEvent.type(input, "test");
+
+      // Input should have value
+      expect(input.value).toBe("test");
+
+      // Placeholder is still in the attribute but hidden by browser
+      expect(input.placeholder).toBe("Search animals...");
+    });
+
+    await step("Placeholder visible again after clearing", async () => {
+      // Clear input
+      await userEvent.clear(input);
+
+      // Input should be empty again
+      expect(input.value).toBe("");
+
+      // Placeholder still set
+      expect(input.placeholder).toBe("Search animals...");
+    });
+  },
+};
+
+// ============================================================
+// FOCUS BEHAVIOR TESTS
+// ============================================================
+
+/**
+ * Focus: Click Trigger Area Focuses Input
+ * Tests that clicking anywhere in the trigger area (not on buttons) focuses the input
+ */
+export const FocusClickTriggerArea: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        leadingElement={<Search aria-hidden="true" />}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Click in empty space focuses input", async () => {
+      const input = canvas.getByRole("combobox");
+
+      // Input should not have focus initially
+      expect(input).not.toHaveFocus();
+
+      // Find the trigger container and click it (not the input directly)
+      const trigger = input.parentElement?.parentElement;
+      expect(trigger).toBeTruthy();
+
+      // Click the trigger area (clicks propagate to focus the input)
+      await userEvent.click(trigger as HTMLElement);
+
+      // Input should now have focus
+      expect(input).toHaveFocus();
+    });
+
+    await step("Click near leading element focuses input", async () => {
+      const input = canvas.getByRole("combobox");
+
+      // Clear focus by clicking outside
+      await userEvent.click(canvasElement);
+
+      // Find the SVG (leading element) and click near it
+      const svg = canvasElement.querySelector("svg");
+      expect(svg).toBeInTheDocument();
+
+      // Click the SVG's parent container
+      const leadingContainer = svg?.parentElement;
+      if (leadingContainer) {
+        await userEvent.click(leadingContainer);
+
+        // Input should have focus
+        expect(input).toHaveFocus();
       }
+    });
+  },
+};
+
+/**
+ * Focus: Tab Key Focuses Input
+ * Tests that tabbing to the component focuses the input field
+ */
+export const FocusTabKey: Story = {
+  render: () => {
+    return (
+      <Stack direction="column" gap="400">
+        <ComposedComboBox aria-label="First combobox" items={simpleOptions} />
+        <ComposedComboBox aria-label="Second combobox" items={simpleOptions} />
+      </Stack>
     );
-    await step("Invalid multi select has invalid attributes", async () => {
-      await expect(multiSelect).toHaveAttribute("aria-invalid", "true");
-      await expect(multiSelect).toHaveAttribute("data-invalid", "true");
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Tab focuses first input", async () => {
+      const firstInput = canvas.getByLabelText("First combobox");
+
+      // Tab to focus
+      await userEvent.tab();
+
+      // First input should have focus
+      expect(firstInput).toHaveFocus();
     });
-    await step("Invalid multi select can be opened and used", async () => {
-      multiSelect.focus();
-      await userEvent.keyboard("{ArrowDown}");
-      await userEvent.keyboard("{Enter}");
-      await verifyTagsExist(multiSelect, ["Koala"]);
-      // Close for next test
-      await closePopover();
+
+    await step("Tab moves to second input", async () => {
+      const secondInput = canvas.getByLabelText("Second combobox");
+
+      // Tab again (skipping toggle button which has excludeFromTabOrder)
+      await userEvent.tab();
+
+      // Second input should have focus
+      expect(secondInput).toHaveFocus();
+    });
+  },
+};
+
+/**
+ * Focus: Remains on Input During Option Selection
+ * Tests that focus stays on input when selecting options (virtual focus pattern)
+ */
+export const FocusRemainsOnInputDuringSelection: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Focus input and open menu", async () => {
+      await userEvent.click(input);
+      expect(input).toHaveFocus();
+
+      // Type to open menu
+      await userEvent.type(input, "K");
+
+      // Menu should open
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Select option - focus remains on input", async () => {
+      // Input should still have focus before selection
+      expect(input).toHaveFocus();
+
+      // Select an option
+      await selectOptionsByName(["Koala"]);
+
+      // Focus should REMAIN on input (virtual focus pattern)
+      await waitFor(() => {
+        expect(input).toHaveFocus();
+      });
     });
+
     await step(
-      "Invalid multi select updates state when isInvalid is updated",
+      "Navigate and select another - focus still on input",
       async () => {
-        await expect(multiSelect).toHaveAttribute("aria-invalid", "false");
-        await expect(multiSelect).toHaveAttribute("data-invalid", "false");
+        // Clear input text
+        await userEvent.clear(input);
+
+        // Type to filter again
+        await userEvent.type(input, "P");
+
+        // Select another option
+        await selectOptionsByName(["Platypus"]);
+
+        // Focus should still be on input
+        await waitFor(() => {
+          expect(input).toHaveFocus();
+        });
       }
     );
   },
 };
 
 /**
- * Formik Integration
- * Demonstrates integration with Formik form library and explores multiple
- * approaches to overcome TypeScript union type issues with Selection's 'all' literal.
+ * Focus: Loses Focus on Outside Click
+ * Tests that component loses focus when clicking outside
+ */
+export const FocusLosesOnOutsideClick: Story = {
+  render: () => {
+    return (
+      <Stack direction="column" gap="400">
+        <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
+        <Box padding="400" bg="neutral.3">
+          Click me to remove focus
+        </Box>
+      </Stack>
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Focus input", async () => {
+      const input = canvas.getByRole("combobox");
+
+      await userEvent.click(input);
+      expect(input).toHaveFocus();
+    });
+
+    await step("Click outside loses focus", async () => {
+      const input = canvas.getByRole("combobox");
+
+      // Click the Box below the combobox
+      const outsideBox = canvas.getByText("Click me to remove focus");
+      await userEvent.click(outsideBox);
+
+      // Input should no longer have focus
+      expect(input).not.toHaveFocus();
+    });
+  },
+};
+
+/**
+ * Focus: Indicators Visible During Keyboard Navigation
+ * Tests that focus indicators are visible when navigating with keyboard
  */
-export const FormikIntegration: Story = {
+export const FocusIndicatorsVisible: Story = {
   render: () => {
-    // Simulating Formik pattern - in real implementation you'd import from 'formik'
-    const [formData, setFormData] = useState<{
-      animal: Key | null;
-      animals: Selection;
-    }>({
-      animal: null,
-      animals: new Set(),
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Tab to input - focus ring visible", async () => {
+      // Tab to focus input
+      await userEvent.tab();
+
+      expect(input).toHaveFocus();
+
+      // Input should have focus-visible styling (can't directly test CSS,
+      // but verify the element is focused via keyboard)
+      expect(input).toHaveFocus();
     });
-    const [errors, setErrors] = useState<{
-      animal?: string;
-      animals?: string;
-    }>({});
-    const [touched, setTouched] = useState<{
-      animal?: boolean;
-      animals?: boolean;
-    }>({});
-    const [inputValue, setInputValue] = useState<string>("");
-    // Simulate Formik's validation function
-    const validate = (values: typeof formData) => {
-      const newErrors: typeof errors = {};
-      if (!values.animal) {
-        newErrors.animal = "Please select an animal";
-      }
-      if (values.animals instanceof Set && values.animals.size === 0) {
-        newErrors.animals = "Please select at least one animal";
-      }
-      return newErrors;
-    };
-    // Simulate Formik's handleSubmit
-    const handleSubmit = (e: FormEvent) => {
-      console.log("handling submission");
-      e.preventDefault();
-      // Always clear previous errors before validation
-      setErrors({});
-      const validationErrors = validate(formData);
-      console.log("Validation errors:", validationErrors);
-      if (Object.keys(validationErrors).length === 0) {
-        // Success - reset form and show success message
-        alert(
-          `Form submitted successfully!\n${JSON.stringify(
-            {
-              animal: formData.animal,
-              animals:
-                formData.animals === "all"
-                  ? "all"
-                  : Array.from(formData.animals),
-            },
-            null,
-            2
-          )}`
-        );
-        // Reset form state after successful submission
-        setFormData({ animal: null, animals: new Set() });
-        setInputValue("");
-        setTouched({});
-      } else {
-        // Validation failed - show errors and mark fields as touched
-        setErrors(validationErrors);
-        setTouched({ animal: true, animals: true });
-      }
-    };
-    // Reset form function
-    const resetForm = () => {
-      setFormData({ animal: null, animals: new Set() });
-      setInputValue("");
-      setErrors({});
-      setTouched({});
-    };
-    // Curried handlers - return functions that can be used directly in props
-    const handleSingleValueSelectionChange = useCallback(
-      (fieldName: string) => (selectedId: Key | null) => {
-        const selectedOption = options.find(
-          (option) => option.id === selectedId
-        );
-        setInputValue(selectedOption ? selectedOption.name : "");
-        setFormData((prev) => ({ ...prev, [fieldName]: selectedId }));
-        setTouched((prev) => ({ ...prev, [fieldName]: true }));
 
-        // Clear field-specific error when user makes a change
-        if (errors[fieldName as keyof typeof errors]) {
-          setErrors((prev) => ({ ...prev, [fieldName]: undefined }));
-        }
-      },
-      [errors]
+    await step("Arrow down to navigate options - virtual focus", async () => {
+      // Press arrow down to open menu and focus first option
+      await userEvent.keyboard("{ArrowDown}");
+
+      // Menu should be open
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+
+      // Input should still have browser focus (virtual focus pattern)
+      expect(input).toHaveFocus();
+
+      // First option should be aria-activedescendant (virtual focus)
+      const activeDescendant = input.getAttribute("aria-activedescendant");
+      expect(activeDescendant).toBeTruthy();
+    });
+
+    await step("Navigate options maintains focus indicators", async () => {
+      // Press arrow down again
+      await userEvent.keyboard("{ArrowDown}");
+
+      // Input should still have browser focus
+      expect(input).toHaveFocus();
+
+      // Active descendant should have changed (different option focused)
+      const newActiveDescendant = input.getAttribute("aria-activedescendant");
+      expect(newActiveDescendant).toBeTruthy();
+    });
+  },
+};
+
+// ============================================================
+// KEYBOARD NAVIGATION TESTS
+// ============================================================
+
+/**
+ * Keyboard: Arrow Down Opens Menu and Focuses First Option
+ * Tests that Arrow Down opens the menu and focuses the first option
+ */
+export const KeyboardArrowDownOpensMenu: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
     );
-    const handleMultiValueSelectionChange = useCallback(
-      (fieldName: string) => (value: Selection) => {
-        setFormData((prev) => ({ ...prev, [fieldName]: value }));
-        setTouched((prev) => ({ ...prev, [fieldName]: true }));
+  },
 
-        // Clear field-specific error when user makes a change
-        if (errors[fieldName as keyof typeof errors]) {
-          setErrors((prev) => ({ ...prev, [fieldName]: undefined }));
-        }
-      },
-      [errors]
-    );
-    return (
-      <form onSubmit={handleSubmit}>
-        <Stack direction="column" gap="md">
-          <h3>Formik Integration Pattern</h3>
-          <p>
-            This demonstrates how to integrate ComboBox with Formik&apos;s form
-            handling patterns.
-          </p>
-
-          <FormField.Root isInvalid={!!(errors.animal && touched.animal)}>
-            <FormField.Label>Single Select Animal:</FormField.Label>
-            <FormField.Input>
-              <ComboBox.Root
-                id="animal"
-                name="animal"
-                defaultItems={options}
-                selectedKey={formData.animal}
-                onInputChange={setInputValue}
-                inputValue={inputValue}
-                onSelectionChange={handleSingleValueSelectionChange("animal")}
-              >
-                {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
-              </ComboBox.Root>
-            </FormField.Input>
-            <FormField.Error>{errors.animal}</FormField.Error>
-          </FormField.Root>
-          <FormField.Root isInvalid={!!(errors.animals && touched.animals)}>
-            <FormField.Label>Multi-Select Animals:</FormField.Label>
-            <FormField.Input>
-              <ComboBox.Root
-                id="animals"
-                name="animals"
-                defaultItems={options}
-                selectionMode="multiple"
-                selectedKeys={formData.animals}
-                onSelectionChange={handleMultiValueSelectionChange("animals")}
-              >
-                {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
-              </ComboBox.Root>
-            </FormField.Input>
-            <FormField.Error>{errors.animals}</FormField.Error>
-          </FormField.Root>
-          <Stack direction="row" gap="200" mt="200">
-            <Button colorPalette="primary" type="submit">
-              Submit Form
-            </Button>
-            <Button variant="ghost" onPress={resetForm}>
-              Reset Form
-            </Button>
-          </Stack>
-          <Box mt="400">
-            <Text fontWeight="600" fontSize="400">
-              Form State (Formik-style):
-            </Text>
-            <Box fontSize="350" fontFamily="mono">
-              <Text fontWeight="600">Values:</Text>
-              <Box my="200" p="200" bg="neutral.3" borderRadius="200" as="pre">
-                {JSON.stringify(
-                  {
-                    animal: formData.animal,
-                    animals:
-                      formData.animals === "all"
-                        ? "all"
-                        : Array.from(formData.animals),
-                  },
-                  null,
-                  2
-                )}
-              </Box>
-              <Text fontWeight="600">Errors:</Text>
-              <Box my="200" p="200" bg="neutral.3" borderRadius="200" as="pre">
-                {JSON.stringify(errors, null, 2)}
-              </Box>
-              <Text fontWeight="600">Touched:</Text>
-              <Box my="200" p="200" bg="neutral.3" borderRadius="200" as="pre">
-                {JSON.stringify(touched, null, 2)}
-              </Box>
-            </Box>
-          </Box>
-        </Stack>
-      </form>
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Focus input", async () => {
+      await userEvent.click(input);
+      expect(input).toHaveFocus();
+    });
+
+    await step("Arrow Down opens menu", async () => {
+      await userEvent.keyboard("{ArrowDown}");
+
+      // Menu should open
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("First option is virtually focused", async () => {
+      // aria-activedescendant should point to first option
+      const activeDescendant = input.getAttribute("aria-activedescendant");
+      expect(activeDescendant).toBeTruthy();
+
+      // Find the first option
+      const firstOption = findOptionByText("Koala");
+      expect(firstOption).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Keyboard: Arrow Keys Navigate Options
+ * Tests that Arrow Up/Down navigate through options
+ */
+export const KeyboardArrowKeysNavigate: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Open menu with Arrow Down", async () => {
+      await userEvent.click(input);
+      await userEvent.keyboard("{ArrowDown}");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Arrow Down moves to next option", async () => {
+      // Get initial active descendant
+      const initialActive = input.getAttribute("aria-activedescendant");
+
+      // Press Arrow Down
+      await userEvent.keyboard("{ArrowDown}");
+
+      // Active descendant should change
+      await waitFor(() => {
+        const newActive = input.getAttribute("aria-activedescendant");
+        expect(newActive).not.toBe(initialActive);
+      });
+    });
+
+    await step("Arrow Up moves to previous option", async () => {
+      // Get current active descendant
+      const beforeUp = input.getAttribute("aria-activedescendant");
+
+      // Press Arrow Up
+      await userEvent.keyboard("{ArrowUp}");
+
+      // Active descendant should change
+      await waitFor(() => {
+        const afterUp = input.getAttribute("aria-activedescendant");
+        expect(afterUp).not.toBe(beforeUp);
+      });
+    });
+  },
+};
+
+/**
+ * Keyboard: Enter Selects Option
+ * Tests that Enter key selects the focused option
+ */
+export const KeyboardEnterSelects: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Open menu and navigate to option", async () => {
+      await userEvent.click(input);
+      await userEvent.keyboard("{ArrowDown}"); // Opens and focuses first
+      await userEvent.keyboard("{ArrowDown}"); // Move to second option
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Press Enter to select", async () => {
+      await userEvent.keyboard("{Enter}");
+
+      // Second option (Kangaroo) should be selected
+      await waitFor(() => {
+        expect(input.value).toBe("Kangaroo");
+      });
+    });
+  },
+};
+
+/**
+ * Keyboard: Escape Closes Menu
+ * Tests that Escape key closes the menu
+ */
+export const KeyboardEscapeCloses: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
     );
   },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Open menu", async () => {
+      await userEvent.click(input);
+      await userEvent.keyboard("{ArrowDown}");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Press Escape to close", async () => {
+      await userEvent.keyboard("{Escape}");
+
+      // Menu should close
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).not.toBeInTheDocument();
+      });
+    });
+
+    await step("Input retains focus after Escape", async () => {
+      // Input should still be focused
+      expect(input).toHaveFocus();
+    });
+  },
+};
+
+/**
+ * Keyboard: Backspace Removes Last Tag
+ * Tests that Backspace removes the last tag in multi-select mode when input is empty
+ */
+export const KeyboardBackspaceRemovesTag: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([
+      1, 2, 3,
+    ]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Verify initial tags", async () => {
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Kangaroo")).toBeInTheDocument();
+      expect(canvas.getByText("Platypus")).toBeInTheDocument();
+    });
+
+    await step("Focus input with empty value", async () => {
+      await userEvent.click(input);
+      expect(input).toHaveFocus();
+      expect(input.value).toBe("");
+    });
+
+    await step("Press Backspace to remove last tag", async () => {
+      await userEvent.keyboard("{Backspace}");
+
+      // Last tag (Platypus) should be removed
+      await waitFor(() => {
+        expect(canvas.queryByText("Platypus")).not.toBeInTheDocument();
+      });
+
+      // Other tags should remain
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Kangaroo")).toBeInTheDocument();
+    });
+
+    await step("Press Backspace again to remove next tag", async () => {
+      await userEvent.keyboard("{Backspace}");
+
+      // Kangaroo should be removed
+      await waitFor(() => {
+        expect(canvas.queryByText("Kangaroo")).not.toBeInTheDocument();
+      });
+
+      // Koala should remain
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Keyboard: Navigation Without Mouse
+ * Tests complete keyboard-only workflow (no mouse interaction)
+ */
+export const KeyboardOnlyWorkflow: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Tab to focus input (no mouse)", async () => {
+      await userEvent.tab();
+
+      const input = canvas.getByRole("combobox");
+      expect(input).toHaveFocus();
+    });
+
+    await step("Arrow Down to open menu", async () => {
+      await userEvent.keyboard("{ArrowDown}");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Navigate with arrows", async () => {
+      const input = canvas.getByRole("combobox");
+
+      // Arrow Down to move through options
+      await userEvent.keyboard("{ArrowDown}");
+      await userEvent.keyboard("{ArrowDown}");
+
+      // Input should still have focus
+      expect(input).toHaveFocus();
+    });
+
+    await step("Select with Enter", async () => {
+      const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+      await userEvent.keyboard("{Enter}");
+
+      // Third option (Platypus) should be selected
+      await waitFor(() => {
+        expect(input.value).toBe("Platypus");
+      });
+    });
+
+    await step("Escape closes menu", async () => {
+      // Reopen menu
+      await userEvent.keyboard("{ArrowDown}");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+
+      // Close with Escape
+      await userEvent.keyboard("{Escape}");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).not.toBeInTheDocument();
+      });
+    });
+  },
+};
+
+// ============================================================
+// BUTTON VISIBILITY & BEHAVIOR TESTS
+// ============================================================
+
+/**
+ * Buttons: Accessible When Content Wraps
+ * Tests that toggle and clear buttons remain accessible when tags wrap to multiple lines
+ */
+export const ButtonsAccessibleWhenWrapping: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([
+      1, 2, 3, 4, 5, 6,
+    ]);
+
+    return (
+      <Box width="300px">
+        <ComposedComboBox
+          aria-label="Test combobox"
+          items={simpleOptions}
+          selectionMode="multiple"
+          selectedKeys={selectedKeys}
+          onSelectionChange={setSelectedKeys}
+        />
+      </Box>
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Verify content wrapping occurred", async () => {
+      // Find the input, then navigate to parent structure
+      const input = canvas.getByRole("combobox");
+
+      const trigger = input.parentElement?.parentElement;
+
+      expect(trigger).toBeTruthy();
+      expect(trigger).toBeVisible();
+
+      // Measure trigger height - should be multi-line
+      const triggerHeight = (trigger as HTMLElement).offsetHeight;
+
+      // With 6 tags wrapping, height should be >100px
+      expect(triggerHeight).toBeGreaterThan(100);
+    });
+
+    await step("Toggle button remains accessible", async () => {
+      const toggleButton = canvas.getByLabelText(/toggle options/i);
+
+      // Button should be visible
+      expect(toggleButton).toBeVisible();
+      expect(toggleButton).toBeEnabled();
+
+      // Button should be clickable
+      await userEvent.click(toggleButton);
+
+      // Menu should open
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+
+      // Close menu
+      await userEvent.click(toggleButton);
+    });
+
+    await step("Clear button remains accessible", async () => {
+      const clearButton = canvas.getByLabelText(/clear selection/i);
+
+      // Button should be visible
+      expect(clearButton).toBeVisible();
+      expect(clearButton).toBeEnabled();
+
+      // Button should be clickable
+      await userEvent.click(clearButton);
+
+      // All selections should be cleared
+      await waitFor(() => {
+        expect(canvas.queryByText("Koala")).not.toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Buttons: Click Areas Sufficiently Large
+ * Tests that button click areas are large enough for interaction (min 44x44px for WCAG)
+ */
+export const ButtonsClickAreas: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([1]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Toggle button has sufficient click area", async () => {
+      const toggleButton = canvas.getByLabelText(
+        /toggle options/i
+      ) as HTMLButtonElement;
+
+      // Measure button dimensions
+      const width = toggleButton.offsetWidth;
+      const height = toggleButton.offsetHeight;
+
+      // WCAG 2.5.5 Target Size: minimum 44x44px for touch targets
+      // Note: These are icon buttons (size="2xs") so they may be smaller
+      // but should still be reasonably clickable
+      expect(width).toBeGreaterThan(20);
+      expect(height).toBeGreaterThan(20);
+
+      // Button should be clickable
+      await userEvent.click(toggleButton);
+
+      // Verify click worked
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Clear button has sufficient click area", async () => {
+      const clearButton = canvas.getByLabelText(
+        /clear selection/i
+      ) as HTMLButtonElement;
+
+      // Measure button dimensions
+      const width = clearButton.offsetWidth;
+      const height = clearButton.offsetHeight;
+
+      // Should be reasonably clickable
+      expect(width).toBeGreaterThan(20);
+      expect(height).toBeGreaterThan(20);
+
+      // Button should be clickable
+      await userEvent.click(clearButton);
+
+      // Verify click worked (button should hide after clearing)
+      await waitFor(() => {
+        const computedStyle = window.getComputedStyle(clearButton);
+        expect(computedStyle.display).toBe("none");
+      });
+    });
+  },
+};
+
+// ============================================================
+// MENU OPENING & CLOSING TESTS
+// ============================================================
+
+/**
+ * Menu: Opens When User Types (Default Behavior)
+ * Tests that menu opens automatically when user starts typing (menuTrigger="input")
+ */
+export const MenuOpensOnTyping: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        menuTrigger="input"
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Focus input - menu closed", async () => {
+      await userEvent.click(input);
+      expect(input).toHaveFocus();
+
+      // Menu should NOT be open yet
+      const listbox = getListBox(document);
+      expect(listbox).not.toBeInTheDocument();
+    });
+
+    await step("Type character - menu opens", async () => {
+      await userEvent.type(input, "K");
+
+      // Menu should open
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Menu: Opens on Focus When Configured
+ * Tests that menu opens when input receives focus (menuTrigger="focus")
+ */
+export const MenuOpensOnFocus: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        menuTrigger="focus"
+      />
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    // Click to focus input
+    await userEvent.click(input);
+
+    // Menu should open automatically on focus
+    await waitFor(() => {
+      const listbox = getListBox(document);
+      expect(listbox).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Menu: Opens Only on Button Click (Manual Mode)
+ * Tests that menu only opens via toggle button when menuTrigger="manual"
+ */
+export const MenuOpensManual: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        menuTrigger="manual"
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Focus does not open menu", async () => {
+      await userEvent.click(input);
+      expect(input).toHaveFocus();
+
+      // Menu should NOT open on focus
+      const listbox = getListBox(document);
+      expect(listbox).not.toBeInTheDocument();
+    });
+
+    await step("Typing does not open menu", async () => {
+      await userEvent.type(input, "K");
+
+      // Menu should still NOT open
+      const listbox = getListBox(document);
+      expect(listbox).not.toBeInTheDocument();
+    });
+
+    await step("Toggle button opens menu", async () => {
+      const toggleButton = canvas.getByLabelText(/toggle options/i);
+
+      await userEvent.click(toggleButton);
+
+      // Menu should NOW open
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Menu: Toggle Button Opens and Closes
+ * Tests that toggle button opens and closes the menu
+ */
+export const MenuToggleButton: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const toggleButton = canvas.getByLabelText(/toggle options/i);
+
+    await step("Click toggle to open", async () => {
+      await userEvent.click(toggleButton);
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Click toggle to close", async () => {
+      await userEvent.click(toggleButton);
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).not.toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Menu: Closes After Selection (Single-Select)
+ * Tests that menu closes automatically after selecting an option in single-select mode
+ */
+export const MenuClosesAfterSelectionSingle: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Open menu", async () => {
+      await userEvent.click(input);
+      await userEvent.keyboard("{ArrowDown}");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Select option", async () => {
+      await userEvent.keyboard("{Enter}");
+
+      // Koala should be selected
+      await waitFor(() => {
+        expect(input.value).toBe("Koala");
+      });
+    });
+
+    await step("Menu closes after selection", async () => {
+      // Menu should close automatically in single-select mode
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).not.toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Menu: Stays Open After Selection (Multi-Select)
+ * Tests that menu stays open after selecting an option in multi-select mode
+ */
+export const MenuStaysOpenAfterSelectionMulti: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Open menu and select first option", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+
+      // Select Koala
+      await selectOptionsByName(["Koala"]);
+
+      // Verify selection
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+    });
+
+    await step("Menu stays open after selection", async () => {
+      // Menu should REMAIN open in multi-select mode
+      const listbox = getListBox(document);
+      expect(listbox).toBeInTheDocument();
+    });
+
+    await step("Can select another option", async () => {
+      // Clear input and type again
+      await userEvent.clear(input);
+      await userEvent.type(input, "P");
+
+      // Select Platypus
+      await selectOptionsByName(["Platypus"]);
+
+      // Both tags should exist
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Platypus")).toBeInTheDocument();
+
+      // Menu should STILL be open
+      const listbox = getListBox(document);
+      expect(listbox).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Menu: Closes on Outside Click
+ * Tests that menu closes when clicking outside the component
+ */
+export const MenuClosesOnOutsideClick: Story = {
+  render: () => {
+    return (
+      <Stack direction="column" gap="400">
+        <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
+        <Box padding="400" bg="neutral.3">
+          Click here to close menu
+        </Box>
+      </Stack>
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Open menu", async () => {
+      await userEvent.click(input);
+      await userEvent.keyboard("{ArrowDown}");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Click outside closes menu", async () => {
+      const outsideBox = canvas.getByText("Click here to close menu");
+      await userEvent.click(outsideBox);
+
+      // Menu should close
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).not.toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Menu: Closes on Escape Key
+ * Tests that Escape key closes the menu (covered in KeyboardEscapeCloses but included for completeness)
+ */
+export const MenuClosesOnEscape: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Open menu", async () => {
+      await userEvent.click(input);
+      await userEvent.keyboard("{ArrowDown}");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Press Escape to close", async () => {
+      await userEvent.keyboard("{Escape}");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).not.toBeInTheDocument();
+      });
+    });
+  },
+};
+
+// ============================================================
+// OPTION SELECTION TESTS
+// ============================================================
+
+/**
+ * Option: Clicking Selects Option
+ * Tests that clicking an option with the mouse selects it
+ */
+export const OptionClickingSelects: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Open menu", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Click option to select", async () => {
+      const koalaOption = findOptionByText("Koala");
+      expect(koalaOption).toBeInTheDocument();
+
+      // Click the option
+      await userEvent.click(koalaOption!);
+
+      // Option should be selected
+      await waitFor(() => {
+        expect(input.value).toBe("Koala");
+      });
+    });
+  },
+};
+
+/**
+ * Option: Hovering Shows Visual Feedback
+ * Tests that hovering over options shows visual feedback
+ */
+export const OptionHoverFeedback: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Open menu", async () => {
+      await userEvent.click(input);
+      await userEvent.keyboard("{ArrowDown}");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Hover over option shows feedback", async () => {
+      const kangarooOption = findOptionByText("Kangaroo");
+      expect(kangarooOption).toBeInTheDocument();
+
+      // Hover over the option
+      await userEvent.hover(kangarooOption!);
+
+      // Option should be visible and hoverable (testing-library hover doesn't
+      // always trigger data-focused in headless browser, so verify element exists)
+      expect(kangarooOption).toBeVisible();
+
+      // Verify option is interactable by clicking it
+      await userEvent.click(kangarooOption!);
+
+      // Selection should occur (proving hover made it clickable)
+      await waitFor(() => {
+        expect(input.value).toBe("Kangaroo");
+      });
+    });
+  },
+};
+
+/**
+ * Option: Selected Options Visually Distinguished
+ * Tests that selected options have visual distinction (aria-selected, styling)
+ */
+export const OptionSelectedVisuallyDistinguished: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([
+      1, 3,
+    ]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        menuTrigger="focus"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Open menu", async () => {
+      await userEvent.click(input);
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Selected options have aria-selected", async () => {
+      const koalaOption = findOptionByText("Koala");
+      const platypusOption = findOptionByText("Platypus");
+
+      // Selected options should have aria-selected="true"
+      expect(isOptionSelected(koalaOption)).toBe(true);
+      expect(isOptionSelected(platypusOption)).toBe(true);
+    });
+
+    await step("Unselected options do not have aria-selected", async () => {
+      const kangarooOption = findOptionByText("Kangaroo");
+
+      // Unselected option should not be selected
+      expect(isOptionSelected(kangarooOption)).toBe(false);
+    });
+  },
+};
+
+/**
+ * Option: Keyboard Selection Works
+ * Tests that Enter key selects the focused option
+ */
+export const OptionKeyboardSelection: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Navigate to option with keyboard", async () => {
+      await userEvent.click(input);
+      await userEvent.keyboard("{ArrowDown}"); // Opens and focuses first
+      await userEvent.keyboard("{ArrowDown}"); // Move to second option
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Press Enter to select", async () => {
+      await userEvent.keyboard("{Enter}");
+
+      // Second option (Kangaroo) should be selected
+      await waitFor(() => {
+        expect(input.value).toBe("Kangaroo");
+      });
+    });
+  },
+};
+
+/**
+ * Option: Multiple Selections Work (Multi-Select)
+ * Tests that multiple options can be selected in multi-select mode
+ */
+export const OptionMultipleSelections: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Select first option", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+
+      await selectOptionsByName(["Koala"]);
+
+      // Verify first tag
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+    });
+
+    await step("Select second option", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "P");
+
+      await selectOptionsByName(["Platypus"]);
+
+      // Both tags should exist
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Platypus")).toBeInTheDocument();
+    });
+
+    await step("Select third option", async () => {
+      await userEvent.clear(input);
+      await input.focus();
+
+      await selectOptionsByName(["Bison"]);
+
+      // All three tags should exist
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Platypus")).toBeInTheDocument();
+      expect(canvas.getByText("Bison")).toBeInTheDocument();
+    });
+  },
+};
+
+// ============================================================
+// CLEAR FUNCTIONALITY TESTS
+// ============================================================
+
+/**
+ * Clear: Removes Current Selection (Single-Select)
+ * Tests that clear button removes the selected item in single-select mode
+ */
+export const ClearRemovesSelectionSingle: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Make a selection first", async () => {
+      // Open menu and select an option
+      await userEvent.click(input);
+      await userEvent.keyboard("{ArrowDown}");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+
+      // Select first option (Koala)
+      await userEvent.keyboard("{Enter}");
+
+      await waitFor(() => {
+        expect(input.value).toBe("Koala");
+      });
+    });
+
+    await step("Click clear button to remove selection", async () => {
+      const clearButton = canvas.getByLabelText(/clear selection/i);
+
+      await userEvent.click(clearButton);
+
+      // Selection should be cleared
+      await waitFor(() => {
+        expect(input.value).toBe("");
+      });
+    });
+  },
+};
+
+/**
+ * Clear: Removes All Selections (Multi-Select)
+ * Tests that clear button removes all selected items in multi-select mode
+ */
+export const ClearRemovesAllSelectionsMulti: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([
+      1, 2, 3,
+    ]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Verify initial tags", async () => {
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Kangaroo")).toBeInTheDocument();
+      expect(canvas.getByText("Platypus")).toBeInTheDocument();
+    });
+
+    await step("Click clear button", async () => {
+      const clearButton = canvas.getByLabelText(/clear selection/i);
+
+      await userEvent.click(clearButton);
+
+      // All tags should be removed
+      await waitFor(() => {
+        expect(canvas.queryByText("Koala")).not.toBeInTheDocument();
+        expect(canvas.queryByText("Kangaroo")).not.toBeInTheDocument();
+        expect(canvas.queryByText("Platypus")).not.toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Clear: Does Not Close Menu
+ * Tests that clear button doesn't close the menu (allows continued browsing)
+ */
+export const ClearDoesNotCloseMenu: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Open menu and select item", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+
+      // Select Koala
+      await selectOptionsByName(["Koala"]);
+
+      // Verify tag
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+    });
+
+    await step("Click clear button", async () => {
+      const clearButton = canvas.getByLabelText(/clear selection/i);
+
+      await userEvent.click(clearButton);
+
+      // Selection should be cleared
+      await waitFor(() => {
+        expect(canvas.queryByText("Koala")).not.toBeInTheDocument();
+      });
+    });
+
+    await step("Menu remains open", async () => {
+      // Menu should STILL be open after clearing
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Clear: Accessible via Keyboard (Backspace)
+ * Tests that selections can be cleared via keyboard using Backspace
+ */
+export const ClearAccessibleViaKeyboard: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([
+      1, 2,
+    ]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Verify initial tags", async () => {
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Kangaroo")).toBeInTheDocument();
+    });
+
+    await step("Use Backspace to clear last tag", async () => {
+      await userEvent.click(input);
+      expect(input.value).toBe(""); // Input empty in multi-select
+
+      // Backspace removes last tag
+      await userEvent.keyboard("{Backspace}");
+
+      // Kangaroo (last tag) should be removed
+      await waitFor(() => {
+        expect(canvas.queryByText("Kangaroo")).not.toBeInTheDocument();
+      });
+
+      // Koala should remain
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+    });
+
+    await step("Use Backspace again to clear remaining tag", async () => {
+      await userEvent.keyboard("{Backspace}");
+
+      // Koala should be removed
+      await waitFor(() => {
+        expect(canvas.queryByText("Koala")).not.toBeInTheDocument();
+      });
+    });
+  },
+};
+
+// ============================================================
+// SELECTION MODES TESTS
+// ============================================================
+
+/**
+ * Single-Select: One Option at a Time
+ * Tests that only one option can be selected at a time in single-select mode
+ */
+export const SingleSelectOneAtATime: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Select first option", async () => {
+      await userEvent.click(input);
+      await userEvent.keyboard("{ArrowDown}");
+      await userEvent.keyboard("{Enter}");
+
+      await waitFor(() => {
+        expect(input.value).toBe("Koala");
+      });
+    });
+
+    await step("Select second option - replaces first", async () => {
+      // Open menu again
+      await userEvent.click(input);
+      await userEvent.keyboard("{ArrowDown}");
+      await userEvent.keyboard("{ArrowDown}"); // Navigate to Kangaroo
+      await userEvent.keyboard("{Enter}");
+
+      // Kangaroo should replace Koala
+      await waitFor(() => {
+        expect(input.value).toBe("Kangaroo");
+      });
+    });
+  },
+};
+
+/**
+ * Single-Select: New Selection Replaces Previous
+ * Tests that selecting a new option replaces the previous selection
+ */
+export const SingleSelectReplacesPrevious: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Select Koala", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      // TODO: pull this out into a helper? We do it a lot
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+
+      await selectOptionsByName(["Koala"]);
+
+      await waitFor(() => {
+        expect(input.value).toBe("Koala");
+      });
+    });
+
+    await step("Select Platypus - Koala is replaced", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "P");
+
+      await selectOptionsByName(["Platypus"]);
+
+      // Only Platypus should be selected
+      await waitFor(() => {
+        expect(input.value).toBe("Platypus");
+      });
+    });
+  },
+};
+
+/**
+ * Single-Select: Text Appears in Input
+ * Tests that selected option text syncs to the input field
+ */
+export const SingleSelectTextInInput: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    // Select an option
+    await userEvent.click(input);
+    await userEvent.keyboard("{ArrowDown}");
+    await userEvent.keyboard("{ArrowDown}");
+    await userEvent.keyboard("{ArrowDown}"); // Navigate to Platypus
+    await userEvent.keyboard("{Enter}");
+
+    // Input value should match selected option text
+    await waitFor(() => {
+      expect(input.value).toBe("Platypus");
+    });
+  },
+};
+
+/**
+ * Single-Select: Clear Button Removes Selection
+ * Tests that clear button removes the current selection
+ */
+export const SingleSelectClearRemoves: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Make selection", async () => {
+      await userEvent.click(input);
+      await userEvent.keyboard("{ArrowDown}");
+      await userEvent.keyboard("{Enter}");
+
+      await waitFor(() => {
+        expect(input.value).toBe("Koala");
+      });
+    });
+
+    await step("Clear removes selection", async () => {
+      const clearButton = canvas.getByLabelText(/clear selection/i);
+      await userEvent.click(clearButton);
+
+      await waitFor(() => {
+        expect(input.value).toBe("");
+      });
+    });
+  },
+};
+
+/**
+ * Single-Select: Menu Closes After Selection
+ * Tests that menu closes automatically after selecting an option
+ */
+export const SingleSelectMenuCloses: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Open menu", async () => {
+      await userEvent.click(input);
+      await userEvent.keyboard("{ArrowDown}");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Select option", async () => {
+      await userEvent.keyboard("{Enter}");
+
+      await waitFor(() => {
+        expect(input.value).toBe("Koala");
+      });
+    });
+
+    await step("Menu closes automatically", async () => {
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).not.toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Single-Select: Input Displays Correct Value
+ * Tests that input always displays the correct selected value
+ */
+export const SingleSelectInputDisplaysValue: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Select option with long name", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "Bald");
+
+      await waitFor(() => {
+        const option = findOptionByText(
+          "Bald Eagle with a very long name hooray"
+        );
+        expect(option).toBeInTheDocument();
+      });
+
+      await selectOptionsByName(["Bald Eagle with a very long name hooray"]);
+
+      // Input should display full text
+      await waitFor(() => {
+        expect(input.value).toBe("Bald Eagle with a very long name hooray");
+      });
+    });
+  },
+};
+
+/**
+ * Multi-Select: Multiple Options Selectable
+ * Tests that multiple options can be selected
+ */
+export const MultiSelectMultipleOptions: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Select first option", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      await selectOptionsByName(["Koala"]);
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+    });
+
+    await step("Select second option", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "P");
+
+      await selectOptionsByName(["Platypus"]);
+
+      // Both should exist
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Platypus")).toBeInTheDocument();
+    });
+
+    await step("Select third option", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "B");
+
+      await selectOptionsByName(["Bison"]);
+
+      // All three should exist
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Platypus")).toBeInTheDocument();
+      expect(canvas.getByText("Bison")).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Multi-Select: Options Appear as Tags
+ * Tests that selected options appear as removable tags
+ */
+export const MultiSelectOptionsAppearAsTags: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Select options", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      await selectOptionsByName(["Koala", "Kangaroo"]);
+    });
+
+    await step("Options appear as tags with remove buttons", async () => {
+      // Tags should be visible
+      const koalaTag = canvas.getByText("Koala");
+      const kangarooTag = canvas.getByText("Kangaroo");
+
+      expect(koalaTag).toBeVisible();
+      expect(kangarooTag).toBeVisible();
+
+      // Each tag should have a remove button
+      const koalaRemove = canvas.getByRole("button", {
+        name: /remove tag koala/i,
+      });
+      const kangarooRemove = canvas.getByRole("button", {
+        name: /remove tag kangaroo/i,
+      });
+
+      expect(koalaRemove).toBeVisible();
+      expect(kangarooRemove).toBeVisible();
+    });
+  },
+};
+
+/**
+ * Multi-Select: Tag Remove Button Deselects
+ * Tests that clicking tag remove button deselects the item
+ */
+export const MultiSelectTagRemoveDeselects: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Select two options", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      await selectOptionsByName(["Koala", "Kangaroo"]);
+
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Kangaroo")).toBeInTheDocument();
+    });
+
+    await step("Click remove button on Koala tag", async () => {
+      const removeButton = canvas.getByRole("button", {
+        name: /remove tag koala/i,
+      });
+
+      await userEvent.click(removeButton);
+
+      // Koala should be removed
+      await waitFor(() => {
+        expect(canvas.queryByText("Koala")).not.toBeInTheDocument();
+      });
+
+      // Kangaroo should remain
+      expect(canvas.getByText("Kangaroo")).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Multi-Select: Backspace Removes Last Tag
+ * Tests that Backspace key removes the last selected tag
+ */
+export const MultiSelectBackspaceRemoves: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Select two options", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      await selectOptionsByName(["Koala", "Kangaroo"]);
+
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Kangaroo")).toBeInTheDocument();
+    });
+
+    await step("Backspace removes last tag (Kangaroo)", async () => {
+      // Ensure input is focused and empty
+      await userEvent.clear(input);
+      expect(input.value).toBe("");
+
+      await userEvent.keyboard("{Backspace}");
+
+      // Kangaroo (last tag) should be removed
+      await waitFor(() => {
+        expect(canvas.queryByText("Kangaroo")).not.toBeInTheDocument();
+      });
+
+      // Koala should remain
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Multi-Select: Menu Stays Open After Selections
+ * Tests that menu remains open after each selection
+ */
+export const MultiSelectMenuStaysOpen: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Select first option - menu stays open", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      await selectOptionsByName(["Koala"]);
+
+      // Menu should remain open
+      const listbox = getListBox(document);
+      expect(listbox).toBeInTheDocument();
+    });
+
+    await step("Select second option - menu still open", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "P");
+
+      await selectOptionsByName(["Platypus"]);
+
+      // Menu should still be open
+      const listbox = getListBox(document);
+      expect(listbox).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Multi-Select: Clear Button Removes All
+ * Tests that clear button removes all selections at once
+ */
+export const MultiSelectClearRemovesAll: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Select three options", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      await selectOptionsByName(["Koala", "Kangaroo"]);
+
+      await userEvent.clear(input);
+      await userEvent.type(input, "P");
+
+      await selectOptionsByName(["Platypus"]);
+
+      // All three tags should exist
+      // TODO: should we pull this out into a util somehow?
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Kangaroo")).toBeInTheDocument();
+      expect(canvas.getByText("Platypus")).toBeInTheDocument();
+    });
+
+    await step("Clear button removes all selections", async () => {
+      const clearButton = canvas.getByLabelText(/clear selection/i);
+      await userEvent.click(clearButton);
+
+      // All tags should be removed
+      await waitFor(() => {
+        expect(canvas.queryByText("Koala")).not.toBeInTheDocument();
+        expect(canvas.queryByText("Kangaroo")).not.toBeInTheDocument();
+        expect(canvas.queryByText("Platypus")).not.toBeInTheDocument();
+      });
+    });
+  },
+};
+
+// ============================================================
+// SELECTION PERSISTENCE TESTS
+// ============================================================
+
+/**
+ * Persistence: Items Persist When Filtering Changes
+ * Tests that selected items remain selected even when filter text changes
+ */
+export const PersistenceItemsPersistWhenFilteringChanges: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Select Koala", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      await selectOptionsByName(["Koala"]);
+
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+    });
+
+    await step("Change filter - Koala tag persists", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "P");
+
+      // Koala tag should still be visible even though filter changed to "P"
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+    });
+
+    await step("Select Platypus with different filter", async () => {
+      await selectOptionsByName(["Platypus"]);
+
+      // Both tags should be visible
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Platypus")).toBeInTheDocument();
+    });
+
+    await step("Change filter again - both persist", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "B");
+
+      // Both previously selected tags should still be visible
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Platypus")).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Persistence: Selected Items Remain Visible as Tags
+ * Tests that selected items always visible as tags regardless of current filter
+ */
+export const PersistenceItemsRemainVisibleAsTags: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Select items with 'K' filter", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      await selectOptionsByName(["Koala", "Kangaroo"]);
+
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+      expect(canvas.getByText("Kangaroo")).toBeInTheDocument();
+    });
+
+    await step("Filter by 'B' - K tags still visible", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "B");
+
+      // Tags should remain visible despite filter not matching them
+      expect(canvas.getByText("Koala")).toBeVisible();
+      expect(canvas.getByText("Kangaroo")).toBeVisible();
+    });
+
+    await step("Clear filter - tags still visible", async () => {
+      await userEvent.clear(input);
+
+      // Tags should remain visible with empty filter
+      expect(canvas.getByText("Koala")).toBeVisible();
+      expect(canvas.getByText("Kangaroo")).toBeVisible();
+    });
+  },
+};
+
+// ============================================================
+// BASIC TEXT FILTERING TESTS
+// ============================================================
+
+/**
+ * Filtering: Typing Filters Options List
+ * Tests that typing in the input filters the available options
+ */
+export const FilteringTypingFiltersOptions: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        menuTrigger="focus"
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Open menu - all 6 options visible", async () => {
+      await userEvent.click(input);
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+
+      const options = getListboxOptions();
+      expect(options.length).toBe(6);
+    });
+
+    await step("Type 'K' - filters to 2 options", async () => {
+      await userEvent.type(input, "B");
+
+      // Should show Koala and Kangaroo
+      await waitFor(() => {
+        const options = getListboxOptions();
+        expect(options.length).toBe(2);
+      });
+
+      expect(findOptionByText("Bison")).toBeInTheDocument();
+      expect(
+        findOptionByText("Bald Eagle with a very long name hooray")
+      ).toBeInTheDocument();
+    });
+
+    await step("Type more 'oa' - filters to 1 option", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "oa");
+
+      // Should only show Koala
+      await waitFor(() => {
+        const options = getListboxOptions();
+        expect(options.length).toBe(1);
+      });
+
+      expect(findOptionByText("Koala")).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Filtering: Case Insensitive by Default
+ * Tests that filtering is case-insensitive
+ */
+export const FilteringCaseInsensitive: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Type lowercase 'k' - matches Koala", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "k");
+
+      await waitFor(() => {
+        expect(findOptionByText("Koala")).toBeInTheDocument();
+        expect(findOptionByText("Kangaroo")).toBeInTheDocument();
+      });
+    });
+
+    await step("Clear and type uppercase 'K' - same results", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "K");
+
+      await waitFor(() => {
+        expect(findOptionByText("Koala")).toBeInTheDocument();
+        expect(findOptionByText("Kangaroo")).toBeInTheDocument();
+      });
+    });
+
+    await step("Mixed case 'Ko' - still matches", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "Ko");
+
+      await waitFor(() => {
+        expect(findOptionByText("Koala")).toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Filtering: Partial Text Matches Shown
+ * Tests that partial text matches are included in results
+ */
+export const FilteringPartialMatches: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Type 'al' - matches Koala and Bald Eagle", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "al");
+
+      // Should match "Koala" and "Bald Eagle" (contains "al")
+      await waitFor(() => {
+        expect(findOptionByText("Koala")).toBeInTheDocument();
+        expect(
+          findOptionByText("Bald Eagle with a very long name hooray")
+        ).toBeInTheDocument();
+      });
+    });
+
+    await step("Type 'ng' - matches Kangaroo", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "ng");
+
+      await waitFor(() => {
+        expect(findOptionByText("Kangaroo")).toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Filtering: Clearing Input Shows All Options
+ * Tests that clearing the input shows all options again
+ */
+export const FilteringClearingShowsAll: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Filter to specific items", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      await waitFor(() => {
+        const options = getListboxOptions();
+        expect(options.length).toBe(3); // Koala, Kangaroo, Skunk
+      });
+    });
+
+    await step("Clear input - all options return", async () => {
+      await userEvent.clear(input);
+
+      await waitFor(() => {
+        const options = getListboxOptions();
+        expect(options.length).toBe(6); // All options
+      });
+    });
+  },
+};
+
+/**
+ * Filtering: Filter Resets When Menu Closes
+ * Tests that filter state resets when menu closes and reopens
+ */
+export const FilteringResetsOnMenuClose: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Filter options", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      await waitFor(() => {
+        const options = getListboxOptions();
+        expect(options.length).toBe(3);
+      });
+    });
+
+    await step("Close menu with Escape", async () => {
+      await userEvent.keyboard("{Escape}");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).not.toBeInTheDocument();
+      });
+    });
+
+    await step("Reopen menu - filter maintained", async () => {
+      await userEvent.keyboard("{ArrowDown}");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+
+      // Filter text should still be "K" in input
+      // Options should still be filtered
+      const options = getListboxOptions();
+      expect(options.length).toBe(3);
+    });
+  },
+};
+
+/**
+ * Filtering: No Results State Handled
+ * Tests that filtering with no matches shows empty state
+ */
+export const FilteringNoResultsState: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        allowsEmptyMenu={true}
+        renderEmptyState={() => "No results found"}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Type text with no matches", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "xyz");
+
+      // Menu should remain open (allowsEmptyMenu=true)
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Empty state message displays", async () => {
+      const options = getListboxOptions();
+      const notFoundOption = findOptionByText("No results found");
+
+      expect(options.length).toBe(1);
+      // Empty state should be visible
+      expect(notFoundOption).toBeInTheDocument();
+    });
+
+    await step("Type valid text - options return", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "K");
+
+      // Options should appear
+      await waitFor(() => {
+        const options = getListboxOptions();
+        expect(options.length).toBe(3);
+      });
+    });
+  },
+};
+
+// ============================================================
+// SECTION-AWARE FILTERING TESTS
+// ============================================================
+
+/**
+ * Filtering: With Sections
+ * Tests section-aware filtering behavior with grouped options
+ */
+export const FilteringWithSections: Story = {
+  render: () => {
+    const sectionsData = [
+      {
+        id: "mammals",
+        name: "Mammals",
+        children: [
+          { id: 1, name: "Koala" },
+          { id: 2, name: "Kangaroo" },
+        ],
+      },
+      {
+        id: "birds",
+        name: "Birds",
+        children: [{ id: 4, name: "Bald Eagle" }],
+      },
+      {
+        id: "other",
+        name: "Other",
+        children: [
+          { id: 3, name: "Platypus" },
+          { id: 5, name: "Bison" },
+          { id: 6, name: "Skunk" },
+        ],
+      },
+    ];
+
+    return (
+      <ComboBox.Root
+        items={sectionsData}
+        menuTrigger="focus"
+        aria-label="Test combobox with sections"
+      >
+        <ComboBox.Trigger />
+        <ComboBox.Popover>
+          <ComboBox.ListBox<(typeof sectionsData)[0]>>
+            {(section) => (
+              <ComboBox.Section<(typeof sectionsData)[0]["children"][0]>
+                label={section.name}
+                items={section.children}
+                id={section.id}
+              >
+                {(item) => (
+                  <ComboBox.Option id={item.id} textValue={item.name}>
+                    {item.name}
+                  </ComboBox.Option>
+                )}
+              </ComboBox.Section>
+            )}
+          </ComboBox.ListBox>
+        </ComboBox.Popover>
+      </ComboBox.Root>
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("All sections appear with header labels", async () => {
+      await userEvent.click(input);
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+
+      // Verify section headers (in portal, so use document not canvas)
+      const portal = within(document.body);
+      expect(portal.getByText("Mammals")).toBeInTheDocument();
+      expect(portal.getByText("Birds")).toBeInTheDocument();
+      expect(portal.getByText("Other")).toBeInTheDocument();
+    });
+
+    await step("Items grouped under correct sections", async () => {
+      // Verify items exist
+      expect(findOptionByText("Koala")).toBeInTheDocument();
+      expect(findOptionByText("Bald Eagle")).toBeInTheDocument();
+      expect(findOptionByText("Platypus")).toBeInTheDocument();
+    });
+
+    await step("Filter 'eagle' - only Birds section visible", async () => {
+      await userEvent.type(input, "eagle");
+
+      const portal = within(document.body);
+
+      await waitFor(() => {
+        // Birds section should be visible
+        expect(portal.getByText("Birds")).toBeInTheDocument();
+
+        // Bald Eagle should be visible
+        expect(findOptionByText("Bald Eagle")).toBeInTheDocument();
+      });
+
+      // Other sections should not be visible (no matching items)
+      expect(portal.queryByText("Mammals")).not.toBeInTheDocument();
+      expect(portal.queryByText("Other")).not.toBeInTheDocument();
+    });
+
+    await step("Filter 'ko' - only Mammals section visible", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "ko");
+
+      const portal = within(document.body);
+
+      await waitFor(() => {
+        // Mammals section should be visible
+        expect(portal.getByText("Mammals")).toBeInTheDocument();
+
+        // Koala should be visible
+        expect(findOptionByText("Koala")).toBeInTheDocument();
+      });
+
+      // Other sections should not be visible
+      expect(portal.queryByText("Birds")).not.toBeInTheDocument();
+      expect(portal.queryByText("Other")).not.toBeInTheDocument();
+    });
+
+    await step("Clear filter - all sections visible again", async () => {
+      await userEvent.clear(input);
+
+      const portal = within(document.body);
+
+      await waitFor(() => {
+        // All sections should return
+        expect(portal.getByText("Mammals")).toBeInTheDocument();
+        expect(portal.getByText("Birds")).toBeInTheDocument();
+        expect(portal.getByText("Other")).toBeInTheDocument();
+      });
+    });
+
+    await step("Filter 'a' - multiple sections have matches", async () => {
+      await userEvent.type(input, "a");
+
+      const portal = within(document.body);
+
+      await waitFor(() => {
+        // Mammals section (Koala, Kangaroo contain 'a')
+        expect(portal.getByText("Mammals")).toBeInTheDocument();
+
+        // Birds section (Bald Eagle contains 'a')
+        expect(portal.getByText("Birds")).toBeInTheDocument();
+
+        // Other section (Platypus contains 'a')
+        expect(portal.getByText("Other")).toBeInTheDocument();
+      });
+    });
+  },
+};
+
+// ============================================================
+// CUSTOM FILTER FUNCTIONS TESTS
+// ============================================================
+
+/**
+ * Custom Filter: Start-With Matching
+ * Tests filterByStartsWith - matches only if text starts with search term
+ */
+export const CustomFilterStartsWith: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        filter={ComboBox.filters.filterByStartsWith}
+        menuTrigger="focus"
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step(
+      "Type 'K' - matches Koala and Kangaroo (starts with)",
+      async () => {
+        await userEvent.click(input);
+        await userEvent.type(input, "K");
+
+        const options = Array.from(getListboxOptions());
+        const optionsText = options.map((option) => option.textContent);
+
+        // Should NOT match Skunk (doesn't start with 'K' but contains 'k')
+        expect(optionsText).toMatchObject(["Koala", "Kangaroo"]);
+      }
+    );
+
+    await step("Type 'al' - no matches (none start with 'al')", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "al");
+
+      const options = Array.from(getListboxOptions());
+      const optionsText = options.map((option) => option.textContent);
+
+      // Koala contains 'al' but doesn't start with it
+      expect(optionsText).toMatchObject([]);
+    });
+  },
+};
+
+/**
+ * Custom Filter: Case-Sensitive Matching
+ * Tests filterByCaseSensitive - requires exact case match
+ */
+export const CustomFilterCaseSensitive: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        filter={ComboBox.filters.filterByCaseSensitive}
+        menuTrigger="focus"
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Type 'Ko' - matches Koala (exact case)", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "Ko");
+
+      await waitFor(() => {
+        expect(findOptionByText("Koala")).toBeInTheDocument();
+      });
+    });
+
+    await step("Type 'ko' - no match (case differs)", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "ko");
+
+      await waitFor(() => {
+        const options = getListboxOptions();
+        expect(options.length).toBe(0);
+      });
+    });
+  },
+};
+
+/**
+ * Custom Filter: Word Boundary Matching
+ * Tests filterByWordBoundary - matches whole words
+ */
+export const CustomFilterWordBoundary: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        filter={ComboBox.filters.filterByWordBoundary}
+        menuTrigger="focus"
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step(
+      "Type 'Eagle' - matches 'Bald Eagle' (word boundary)",
+      async () => {
+        await userEvent.click(input);
+        await userEvent.type(input, "Eagle");
+
+        await waitFor(() => {
+          expect(
+            findOptionByText("Bald Eagle with a very long name hooray")
+          ).toBeInTheDocument();
+        });
+      }
+    );
+
+    await step("Type 'ala' - no match (not on word boundary)", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "ala");
+
+      // "Koala" contains "ala" but not at word boundary
+      await waitFor(() => {
+        const options = getListboxOptions();
+        expect(options.length).toBe(0);
+      });
+    });
+  },
+};
+
+/**
+ * Custom Filter: Fuzzy Matching
+ * Tests filterByFuzzy - matches characters in order but not necessarily adjacent
+ */
+export const CustomFilterFuzzy: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        filter={ComboBox.filters.filterByFuzzy}
+        menuTrigger="focus"
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Type 'ldEag' - matches Bald Eagle (fuzzy)", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "ldEag");
+
+      await waitFor(() => {
+        expect(
+          findOptionByText("Bald Eagle with a very long name hooray")
+        ).toBeInTheDocument();
+      });
+    });
+
+    await step("Type 'kng' - matches Kangaroo (K-n-g in order)", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "kng");
+
+      await waitFor(() => {
+        expect(findOptionByText("Kangaroo")).toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Custom Filter: Multi-Property Search
+ * Tests createMultiPropertyFilter - searches across multiple object properties
+ */
+export const CustomFilterMultiProperty: Story = {
+  render: () => {
+    type Product = { id: number; name: string; category: string };
+    const products: Product[] = [
+      { id: 1, name: "Laptop", category: "Electronics" },
+      { id: 2, name: "Desk", category: "Furniture" },
+      { id: 3, name: "Mouse", category: "Electronics" },
+      { id: 4, name: "Chair", category: "Furniture" },
+    ];
+
+    const multiPropertyFilter =
+      ComboBox.filters.createMultiPropertyFilter<Product>(["name", "category"]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={products}
+        filter={multiPropertyFilter}
+        menuTrigger="focus"
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Search by name 'Laptop'", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "Laptop");
+
+      await waitFor(() => {
+        expect(findOptionByText("Laptop")).toBeInTheDocument();
+      });
+    });
+
+    await step("Search by category 'Furniture'", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "Furniture");
+
+      await waitFor(() => {
+        // Should match both Desk and Chair (category: Furniture)
+        expect(findOptionByText("Desk")).toBeInTheDocument();
+        expect(findOptionByText("Chair")).toBeInTheDocument();
+      });
+    });
+
+    await step("Search by category 'Electronics'", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "Electro");
+
+      await waitFor(() => {
+        // Should match Laptop and Mouse
+        expect(findOptionByText("Laptop")).toBeInTheDocument();
+        expect(findOptionByText("Mouse")).toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Custom Filter: Ranked/Scored Results
+ * Tests createRankedFilter - custom scoring logic for ranking results
+ */
+export const CustomFilterRanked: Story = {
+  render: () => {
+    // Rank by: exact match > starts with > contains
+    const rankedFilter = ComboBox.filters.createRankedFilter<SimpleOption>(
+      (node, filterText) => {
+        const text = node.textValue.toLowerCase();
+        const search = filterText.toLowerCase();
+
+        if (text === search) return 100; // Exact match
+        if (text.startsWith(search)) return 50; // Starts with
+        if (text.includes(search)) return 10; // Contains
+        return 0; // No match
+      }
+    );
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        filter={rankedFilter}
+        menuTrigger="focus"
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Search 'ko' - Koala ranked first (starts with)", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "ko");
+
+      await waitFor(() => {
+        const options = getListboxOptions();
+        expect(options.length).toBe(1);
+        expect(findOptionByText("Koala")).toBeInTheDocument();
+      });
+    });
+
+    await step(
+      "Search 'k' - ranked by score (starts with > contains)",
+      async () => {
+        await userEvent.clear(input);
+        await userEvent.type(input, "k");
+
+        await waitFor(() => {
+          const options = getListboxOptions();
+          expect(options.length).toBeGreaterThan(0);
+        });
+
+        const optionsList = Array.from(getListboxOptions());
+
+        // Koala and Kangaroo start with 'k' (score: 50)
+        // Skunk contains 'k' but doesn't start with it (score: 10)
+        // Skunk should appear AFTER Koala and Kangaroo due to lower score
+
+        // Get the index of each option
+        const koalaIndex = optionsList.findIndex((opt) =>
+          opt.textContent?.includes("Koala")
+        );
+        const kangarooIndex = optionsList.findIndex((opt) =>
+          opt.textContent?.includes("Kangaroo")
+        );
+        const skunkIndex = optionsList.findIndex((opt) =>
+          opt.textContent?.includes("Skunk")
+        );
+
+        // Verify all are present and in the correct order
+        expect(koalaIndex).toBe(0);
+        expect(kangarooIndex).toBe(1);
+        expect(skunkIndex).toBe(2);
+
+        // Skunk (contains 'k') should be ranked AFTER Koala and Kangaroo (start with 'k')
+        expect(skunkIndex).toBeGreaterThan(koalaIndex);
+        expect(skunkIndex).toBeGreaterThan(kangarooIndex);
+      }
+    );
+  },
+};
+
+/**
+ * Custom Filter: Multi-Term Search
+ * Tests createMultiTermFilter - OR logic for multiple search terms
+ */
+export const CustomFilterMultiTerm: Story = {
+  render: () => {
+    const multiTermFilter = ComboBox.filters.createMultiTermFilter(
+      ComboBox.filters.filterByText
+    );
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        filter={multiTermFilter}
+        menuTrigger="focus"
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Search 'Koala Bison' - matches both (OR logic)", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "Koala Bison");
+
+      await waitFor(() => {
+        // Should match both Koala OR Bison
+        expect(findOptionByText("Koala")).toBeInTheDocument();
+        expect(findOptionByText("Bison")).toBeInTheDocument();
+      });
+    });
+
+    await step("Search 'Ko Pl' - matches Koala and Platypus", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "Ko Pl");
+
+      await waitFor(() => {
+        expect(findOptionByText("Koala")).toBeInTheDocument();
+        expect(findOptionByText("Platypus")).toBeInTheDocument();
+      });
+    });
+  },
+};
+
+// ============================================================
+// EMPTY STATE HANDLING TESTS
+// ============================================================
+
+/**
+ * Empty State: Menu Closes When No Matches (Default)
+ * Tests that menu closes automatically when no matches found (default behavior)
+ */
+export const EmptyStateMenuClosesDefault: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        // allowsEmptyMenu defaults to false
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Open menu with matches", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "K");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Type text with no matches - menu closes", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "xyz");
+
+      // Menu should close when no matches (default behavior)
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).not.toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Empty State: Custom Message Displays
+ * Tests that custom empty state message renders correctly
+ */
+export const EmptyStateCustomMessage: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        allowsEmptyMenu={true}
+        renderEmptyState={() => (
+          <Stack direction="column" gap="200" padding="400">
+            <Text>No animals match your search</Text>
+            <Text color="neutral.11" fontSize="300">
+              Try a different search term
+            </Text>
+          </Stack>
+        )}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Search with no matches", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "xyz");
+
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Custom empty state renders", async () => {
+      // Custom message should be visible (in portal)
+      const portal = within(document.body);
+      expect(
+        portal.getByText("No animals match your search")
+      ).toBeInTheDocument();
+      expect(
+        portal.getByText("Try a different search term")
+      ).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Empty State: User Can Recover by Clearing Search
+ * Tests that clearing search after no results restores the options
+ */
+export const EmptyStateRecoverByClearingSearch: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        allowsEmptyMenu={true}
+        renderEmptyState={() => "No results found"}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Search with no matches shows empty state", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "xyz");
+
+      const portal = within(document.body);
+
+      await waitFor(() => {
+        expect(portal.getByText("No results found")).toBeInTheDocument();
+      });
+    });
+
+    await step("Clear search - all options return", async () => {
+      await userEvent.clear(input);
+
+      await waitFor(() => {
+        const options = getListboxOptions();
+        expect(options.length).toBe(6); // All options restored
+      });
+
+      // Empty state should be gone
+      const portal = within(document.body);
+      expect(portal.queryByText("No results found")).not.toBeInTheDocument();
+    });
+  },
+};
+
+// ============================================================
+// CUSTOM OPTION CREATION - BASIC CREATION TESTS
+// ============================================================
+
+/**
+ * Creation: User Can Create New Options
+ * Tests that users can create new options when allowsCustomOptions=true
+ */
+export const CreationUserCanCreateOptions: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+        allowsCustomOptions={true}
+        getNewOptionData={(inputValue) => ({
+          id: Date.now(),
+          name: inputValue,
+        })}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Type custom text", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "Lion");
+
+      // No existing match for "Lion"
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Press Enter creates new option", async () => {
+      await userEvent.keyboard("{Enter}");
+
+      // New option should appear as tag
+      await waitFor(() => {
+        expect(canvas.getByText("Lion")).toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Creation: Press Enter on Non-Matching Text Creates Option
+ * Tests that Enter key creates option when text doesn't match any existing option
+ */
+export const CreationEnterOnNonMatchingText: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+        allowsCustomOptions={true}
+        getNewOptionData={(inputValue) => ({
+          id: Date.now(),
+          name: inputValue,
+        })}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Type non-matching text 'Tiger'", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "Tiger");
+    });
+
+    await step("Enter creates new option 'Tiger'", async () => {
+      await userEvent.keyboard("{Enter}");
+
+      await waitFor(() => {
+        expect(canvas.getByText("Tiger")).toBeInTheDocument();
+      });
+    });
+
+    await step("Type another non-matching text 'Bear'", async () => {
+      await userEvent.type(input, "Bear");
+      await userEvent.keyboard("{Enter}");
+
+      await waitFor(() => {
+        expect(canvas.getByText("Bear")).toBeInTheDocument();
+      });
+
+      // Both custom options should exist
+      expect(canvas.getByText("Tiger")).toBeInTheDocument();
+      expect(canvas.getByText("Bear")).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Creation: Empty Input Does Not Create Option
+ * Tests that whitespace-only or empty input doesn't create options
+ */
+export const CreationEmptyInputDoesNotCreate: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+        allowsCustomOptions={true}
+        getNewOptionData={(inputValue) => ({
+          id: Date.now(),
+          name: inputValue,
+        })}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Empty input - Enter does nothing", async () => {
+      await userEvent.click(input);
+      expect(input.value).toBe("");
+
+      await userEvent.keyboard("{Enter}");
+
+      // No tag should be created
+      await waitFor(() => {
+        const tags = canvas.queryAllByRole("button", { name: /remove tag/i });
+        expect(tags.length).toBe(0);
+      });
+    });
+
+    await step("Whitespace-only input - Enter does nothing", async () => {
+      await userEvent.type(input, "   ");
+      await userEvent.keyboard("{Enter}");
+
+      // No tag should be created
+      const tags = canvas.queryAllByRole("button", { name: /remove tag/i });
+      expect(tags.length).toBe(0);
+    });
+  },
+};
+
+/**
+ * Creation: Duplicate Options Are Prevented
+ * Tests that duplicate options cannot be created (case-insensitive check)
+ */
+export const CreationDuplicatesPrevented: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+        allowsCustomOptions={true}
+        getNewOptionData={(inputValue) => ({
+          id: Date.now(),
+          name: inputValue.trim(), // Trim to match validation
+        })}
+        isValidNewOption={(inputValue) => {
+          // Prevent duplicates (case-insensitive)
+          const lowerInput = inputValue.toLowerCase().trim();
+          return (
+            lowerInput.length > 0 &&
+            !simpleOptions.some((opt) => opt.name.toLowerCase() === lowerInput)
+          );
+        }}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Try to create existing option 'Koala'", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "Koala");
+      await userEvent.keyboard("{Enter}");
+
+      // Should NOT create duplicate (Koala exists)
+      await waitFor(() => {
+        const options = getListboxOptions();
+        expect(options.length).toBe(1);
+        expect(findOptionByText("Koala")).toBeInTheDocument();
+      });
+    });
+
+    await step("Try case variation 'koala'", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "koala");
+      await userEvent.keyboard("{Enter}");
+
+      // Should NOT create duplicate
+      await waitFor(() => {
+        const options = getListboxOptions();
+        expect(options.length).toBe(1);
+        expect(findOptionByText("Koala")).toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * Creation: Custom Validation Rules Respected
+ * Tests that isValidNewOption validation is respected
+ */
+export const CreationCustomValidationRespected: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+        allowsCustomOptions={true}
+        getNewOptionData={(inputValue) => ({
+          id: Date.now(),
+          name: inputValue,
+        })}
+        isValidNewOption={(inputValue) => {
+          // Only allow options starting with 'Custom'
+          return inputValue.startsWith("Custom");
+        }}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Invalid option 'Lion' - not created", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "Lion");
+      await userEvent.keyboard("{Enter}");
+
+      // Should NOT create (doesn't start with 'Custom')
+      await waitFor(() => {
+        expect(canvas.queryByText("Lion")).not.toBeInTheDocument();
+      });
+    });
+
+    await step("Valid option 'CustomAnimal' - created", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "CustomAnimal");
+      await userEvent.keyboard("{Enter}");
+
+      // Should create (starts with 'Custom')
+      await waitFor(() => {
+        expect(canvas.getByText("CustomAnimal")).toBeInTheDocument();
+      });
+    });
+
+    await step("Another valid option 'CustomBeast' - created", async () => {
+      await userEvent.type(input, "CustomBeast");
+      await userEvent.keyboard("{Enter}");
+
+      await waitFor(() => {
+        expect(canvas.getByText("CustomBeast")).toBeInTheDocument();
+      });
+
+      // Both custom options should exist
+      expect(canvas.getByText("CustomAnimal")).toBeInTheDocument();
+      expect(canvas.getByText("CustomBeast")).toBeInTheDocument();
+    });
+  },
+};
+
+// ============================================================
+// SINGLE-SELECT CUSTOM OPTIONS TESTS
+// ============================================================
+
+/**
+ * Single-Select Creation: New Option Automatically Selected
+ * Tests that new option is automatically selected in single-select mode
+ */
+export const SingleSelectCreationAutoSelected: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+        allowsCustomOptions={true}
+        getNewOptionData={(inputValue) => ({
+          id: Date.now(),
+          name: inputValue.trim(),
+        })}
+      />
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    // Type custom option
+    await userEvent.click(input);
+    await userEvent.type(input, "Lion");
+    await userEvent.keyboard("{Enter}");
+
+    // New option should be automatically selected in single-select
+    await waitFor(() => {
+      expect(input.value).toBe("Lion");
+    });
+  },
+};
+
+/**
+ * Single-Select Creation: Input Updates to Show New Option Text
+ * Tests that input displays the created option's text
+ */
+export const SingleSelectCreationInputUpdates: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+        allowsCustomOptions={true}
+        getNewOptionData={(inputValue) => ({
+          id: Date.now(),
+          name: inputValue.trim(),
+        })}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Create first custom option", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "Tiger");
+      await userEvent.keyboard("{Enter}");
+
+      // Input should show created option text
+      await waitFor(() => {
+        expect(input.value).toBe("Tiger");
+      });
+    });
+
+    await step("Create second custom option - replaces first", async () => {
+      await userEvent.clear(input);
+      await userEvent.type(input, "Bear");
+      await userEvent.keyboard("{Enter}");
+
+      // Input should show new option text (single-select replacement)
+      await waitFor(() => {
+        expect(input.value).toBe("Bear");
+      });
+    });
+  },
+};
+
+/**
+ * Single-Select Creation: Menu Closes After Creation
+ * Tests that menu closes automatically after creating option in single-select
+ */
+export const SingleSelectCreationMenuCloses: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+        allowsCustomOptions={true}
+        getNewOptionData={(inputValue) => ({
+          id: Date.now(),
+          name: inputValue.trim(),
+        })}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Type to open menu and create custom option", async () => {
+      await userEvent.click(input);
+      await userEvent.type(input, "Wolf");
+
+      // Menu should open when typing
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+
+      // Press Enter to create
+      await userEvent.keyboard("{Enter}");
+
+      // Input should show created option
+      await waitFor(() => {
+        expect(input.value).toBe("Wolf");
+      });
+    });
+
+    await step("Menu closes after creation", async () => {
+      // Menu should close (single-select behavior)
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).not.toBeInTheDocument();
+      });
+    });
+  },
+};
+
+// ============================================================
+// ACCESSIBILITY - KEYBOARD ACCESSIBILITY TESTS
+// ============================================================
+
+/**
+ * A11y Keyboard: All Functionality Available via Keyboard
+ * Tests complete workflow using only keyboard (no mouse)
+ */
+export const AccessibilityKeyboardAllFunctionalityAvailable: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Focus input (then keyboard only)", async () => {
+      const input = canvas.getByRole("combobox");
+      await userEvent.click(input);
+      expect(input).toHaveFocus();
+    });
+
+    await step("Arrow Down opens menu", async () => {
+      await userEvent.keyboard("{ArrowDown}");
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Navigate and select with Enter", async () => {
+      await userEvent.keyboard("{ArrowDown}");
+      await userEvent.keyboard("{Enter}");
+
+      await waitFor(() => {
+        expect(canvas.getByText("Kangaroo")).toBeInTheDocument();
+      });
+    });
+
+    await step("Backspace removes selection", async () => {
+      const input = canvas.getByRole("combobox") as HTMLInputElement;
+      expect(input.value).toBe("");
+      await userEvent.keyboard("{Backspace}");
+
+      await waitFor(() => {
+        expect(canvas.queryByText("Kangaroo")).not.toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * A11y Keyboard: No Keyboard Traps
+ * Tests that user can Tab out of component
+ */
+export const AccessibilityKeyboardNoTraps: Story = {
+  render: () => {
+    return (
+      <Stack direction="column" gap="400">
+        <ComposedComboBox aria-label="First combobox" items={simpleOptions} />
+        <ComposedComboBox aria-label="Second combobox" items={simpleOptions} />
+      </Stack>
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Tab to first input", async () => {
+      await userEvent.tab();
+      const firstInput = canvas.getByLabelText("First combobox");
+      expect(firstInput).toHaveFocus();
+    });
+
+    await step("Open menu with arrow", async () => {
+      await userEvent.keyboard("{ArrowDown}");
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Tab exits component (no trap)", async () => {
+      await userEvent.tab();
+      const secondInput = canvas.getByLabelText("Second combobox");
+      expect(secondInput).toHaveFocus();
+    });
+
+    await step("Menu closes when focus leaves", async () => {
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).not.toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * A11y Keyboard: Focus Management Works Correctly
+ * Tests that focus is managed correctly throughout interactions
+ */
+export const AccessibilityKeyboardFocusManagement: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    await step("Focus input", async () => {
+      await userEvent.click(input);
+      expect(input).toHaveFocus();
+    });
+
+    await step("Arrow navigation maintains input focus", async () => {
+      await userEvent.keyboard("{ArrowDown}");
+      await userEvent.keyboard("{ArrowDown}");
+
+      // Input should still have browser focus (virtual focus pattern)
+      expect(input).toHaveFocus();
+    });
+
+    await step("Selection maintains input focus", async () => {
+      await userEvent.keyboard("{Enter}");
+
+      await waitFor(() => {
+        expect(input.value).toBe("Kangaroo");
+      });
+
+      // Input should still be focused
+      expect(input).toHaveFocus();
+    });
+
+    await step("Escape maintains input focus", async () => {
+      await userEvent.keyboard("{ArrowDown}");
+      await userEvent.keyboard("{Escape}");
+
+      // Input should still be focused
+      expect(input).toHaveFocus();
+    });
+  },
+};
+
+/**
+ * A11y Keyboard: Keyboard Shortcuts Work
+ * Tests all documented keyboard shortcuts
+ */
+export const AccessibilityKeyboardShortcuts: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Test combobox"
+        items={simpleOptions}
+        selectionMode="multiple"
+        selectedKeys={selectedKeys}
+        onSelectionChange={setSelectedKeys}
+      />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("Focus input", async () => {
+      await userEvent.click(input);
+      expect(input).toHaveFocus();
+    });
+
+    await step("ArrowDown - opens and navigates", async () => {
+      await userEvent.keyboard("{ArrowDown}");
+      const activeDesc = input.getAttribute("aria-activedescendant");
+      expect(activeDesc).toBeTruthy();
+    });
+
+    await step("Enter - selects option", async () => {
+      await userEvent.keyboard("{Enter}");
+      expect(canvas.getByText("Koala")).toBeInTheDocument();
+    });
+
+    await step("Backspace - removes tag", async () => {
+      await userEvent.keyboard("{Backspace}");
+      await waitFor(() => {
+        expect(canvas.queryByText("Koala")).not.toBeInTheDocument();
+      });
+    });
+
+    await step("Escape - closes menu", async () => {
+      await userEvent.keyboard("{ArrowDown}");
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+
+      await userEvent.keyboard("{Escape}");
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).not.toBeInTheDocument();
+      });
+    });
+  },
+};
+
+/**
+ * A11y Keyboard: Focus Indicators Visible
+ * Tests that focus indicators are visible during keyboard navigation
+ */
+export const AccessibilityKeyboardFocusIndicators: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    // Tab to focus (keyboard interaction)
+    await userEvent.tab();
+    expect(input).toHaveFocus();
+
+    // Open menu with keyboard
+    await userEvent.keyboard("{ArrowDown}");
+
+    await waitFor(() => {
+      const listbox = getListBox(document);
+      expect(listbox).toBeInTheDocument();
+    });
+
+    // Verify aria-activedescendant (virtual focus indicator)
+    const activeDesc = input.getAttribute("aria-activedescendant");
+    expect(activeDesc).toBeTruthy();
+    expect(activeDesc).toMatch(/option/); // Should reference an option element
+  },
+};
+
+// ============================================================
+// ACCESSIBILITY - ARIA RELATIONSHIPS TESTS
+// ============================================================
+
+/**
+ * A11y ARIA: Input Associated with Listbox
+ * Tests aria-controls relationship between input and listbox
+ */
+export const AccessibilityAriaInputListboxRelationship: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    // Input should have aria-controls pointing to listbox
+    const ariaControls = input.getAttribute("aria-controls");
+    expect(ariaControls).toBeTruthy();
+
+    // Open menu
+    await userEvent.click(input);
+    await userEvent.type(input, "K");
+
+    await waitFor(() => {
+      const listbox = getListBox(document);
+      expect(listbox).toBeInTheDocument();
+
+      // Listbox ID should match aria-controls
+      expect(listbox?.id).toBe(ariaControls);
+    });
+  },
+};
+
+/**
+ * A11y ARIA: Focused Option Identified
+ * Tests aria-activedescendant identifies currently focused option
+ */
+export const AccessibilityAriaFocusedOptionIdentified: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox aria-label="Test combobox" items={simpleOptions} />
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    await step("No activedescendant when menu closed", async () => {
+      await userEvent.click(input);
+      const activeDesc = input.getAttribute("aria-activedescendant");
+      expect(activeDesc).toBeNull();
+    });
+
+    await step("Activedescendant set when option focused", async () => {
+      await userEvent.keyboard("{ArrowDown}");
+
+      await waitFor(() => {
+        const activeDesc = input.getAttribute("aria-activedescendant");
+        expect(activeDesc).toBeTruthy();
+      });
+
+      const activeDesc = input.getAttribute("aria-activedescendant");
+
+      // Verify the ID points to an actual option
+      const focusedOption = document.getElementById(activeDesc!);
+      expect(focusedOption).toBeInTheDocument();
+      expect(focusedOption?.getAttribute("role")).toBe("option");
+    });
+
+    await step("Activedescendant updates when navigating", async () => {
+      const firstActiveDesc = input.getAttribute("aria-activedescendant");
+
+      await userEvent.keyboard("{ArrowDown}");
+
+      await waitFor(() => {
+        const newActiveDesc = input.getAttribute("aria-activedescendant");
+        expect(newActiveDesc).not.toBe(firstActiveDesc);
+      });
+    });
+  },
+};
+
+// ============================================================
+// VISUAL STATES - SIZE VARIANTS TESTS
+// ============================================================
+
+/**
+ * Size: Small Variant Renders Correctly
+ * Tests that sm size renders with correct root container dimensions
+ */
+export const SizeSmallVariant: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Small combobox"
+        items={simpleOptions}
+        size="sm"
+      />
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    // Find the root container
+    const root = canvasElement.querySelector(".nimbus-combobox__root");
+    expect(root).toBeTruthy();
+
+    // Measure dimensions
+    const height = (root as HTMLElement).offsetHeight;
+    const width = (root as HTMLElement).offsetWidth;
+
+    // Small size height
+    expect(height).toBe(32);
+    expect(width).toBeGreaterThan(0);
+  },
+};
+
+/**
+ * Size: Medium Variant Renders Correctly
+ * Tests that md size renders with correct root container dimensions (default)
+ */
+export const SizeMediumVariant: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Medium combobox"
+        items={simpleOptions}
+        size="md"
+      />
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    // Find the root container
+    const root = canvasElement.querySelector(".nimbus-combobox__root");
+    expect(root).toBeTruthy();
+
+    // Measure dimensions
+    const height = (root as HTMLElement).offsetHeight;
+    const width = (root as HTMLElement).offsetWidth;
+
+    // Medium size height
+    expect(height).toBe(40);
+    expect(width).toBeGreaterThan(0);
+  },
+};
+
+// ============================================================
+// VISUAL STATES - VARIANT TESTS
+// ============================================================
+
+/**
+ * Variant: Solid (Default) Displays Correctly
+ * Tests that solid variant renders with correct root container width
+ */
+export const VariantSolid: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Solid combobox"
+        items={simpleOptions}
+        variant="solid"
+      />
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    const root = canvasElement.querySelector(".nimbus-combobox__root");
+    expect(root).toBeTruthy();
+    expect(root).toBeVisible();
+
+    // Solid variant has fixed width
+    const width = (root as HTMLElement).offsetWidth;
+    expect(width).toBe(288);
+
+    // Verify CSS from recipe
+    const styles = window.getComputedStyle(root as HTMLElement);
+
+    // Solid has appropriate background
+    expect(styles.backgroundColor).toBe("rgb(255, 255, 255)");
+
+    // Solid has fixed width in CSS
+    expect(styles.width).toBe("288px");
+  },
+};
+
+/**
+ * Variant: Ghost Displays Correctly
+ * Tests that ghost variant renders with correct root container width
+ */
+export const VariantGhost: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Ghost combobox"
+        items={simpleOptions}
+        variant="ghost"
+      />
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    const root = canvasElement.querySelector(".nimbus-combobox__root");
+    expect(root).toBeTruthy();
+    expect(root).toBeVisible();
+
+    // Ghost variant has fixed width
+    const width = (root as HTMLElement).offsetWidth;
+
+    // Verify CSS from recipe
+    const styles = window.getComputedStyle(root as HTMLElement);
+
+    // Ghost has transparent background
+    expect(styles.backgroundColor).toContain("rgba(0, 0, 0, 0)");
+
+    // Ghost has fixed width in CSS
+    expect(width).toBe(288);
+  },
+};
+
+// ============================================================
+// VISUAL STATES - REQUIRED/READONLY/DISABLED/INVALID TESTS
+// ============================================================
+
+/**
+ * State: isRequired
+ * Tests required state
+ */
+export const StateIsRequired: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Required combobox"
+        items={simpleOptions}
+        isRequired
+      />
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    expect(input).toBeRequired();
+  },
+};
+
+/**
+ * State: isReadOnly
+ * Tests that read-only state prevents typing and interactions
+ */
+export const StateIsReadOnly: Story = {
+  render: () => {
+    const [selectedKeys] = useState<(string | number)[]>([1]);
+
+    return (
+      <ComposedComboBox
+        aria-label="Read-only combobox"
+        items={simpleOptions}
+        selectedKeys={selectedKeys}
+        isReadOnly
+      />
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox") as HTMLInputElement;
+
+    // Typing has no effect
+    await userEvent.click(input);
+    const initialValue = input.value;
+    await userEvent.type(input, "test");
+    expect(input.value).toBe(initialValue);
+  },
+};
+
+/**
+ * State: isDisabled
+ * Tests that disabled state disables all interactive elements
+ */
+export const StateIsDisabled: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Disabled combobox"
+        items={simpleOptions}
+        isDisabled
+      />
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    // Input is disabled
+    expect(input).toBeDisabled();
+  },
+};
+
+/**
+ * State: isInvalid
+ * Tests that invalid state shows error styling
+ */
+export const StateIsInvalid: Story = {
+  render: () => {
+    return (
+      <ComposedComboBox
+        aria-label="Invalid combobox"
+        items={simpleOptions}
+        isInvalid
+      />
+    );
+  },
+
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole("combobox");
+
+    // Container should be invalid
+    const root = canvasElement.querySelector(".nimbus-combobox__root");
+    expect(root).toHaveAttribute("data-invalid", "true");
+
+    // Find the trigger (contains the border styling)
+    const trigger = input.parentElement?.parentElement as HTMLElement;
+    expect(trigger).toBeTruthy();
+
+    // Check CSS custom property for border color
+    const triggerStyles = window.getComputedStyle(trigger);
+    const borderColor = triggerStyles.getPropertyValue("--border-color");
+
+    // Should be styled when invalid
+    expect(borderColor).toContain("hsl(359, 77%, 81%)");
+  },
+};
+
+// ============================================================
+// PORTAL POSITIONING - COMBOBOX IN DIALOG/MODAL
+// ============================================================
+
+/**
+ * Portal Positioning: ComboBox in Dialog
+ * Tests that ComboBox popover maintains proper positioning relative to trigger
+ * when rendered inside a Dialog/Modal portal (regression test for CRAFT-2013)
+ */
+export const PortalPositioningInDialog: Story = {
+  render: () => {
+    const [selectedKeys, setSelectedKeys] = useState<(string | number)[]>([]);
+
+    return (
+      <Stack direction="column" gap="400">
+        {/* Note: Using uncontrolled Dialog to test ComboBox positioning in modals */}
+        <Dialog.Root>
+          <Dialog.Trigger>Open Dialog with ComboBox</Dialog.Trigger>
+          <Dialog.Content>
+            <Dialog.Header>
+              <Dialog.Title>Select Options</Dialog.Title>
+            </Dialog.Header>
+            <Dialog.Body>
+              <Stack direction="column" gap="400">
+                <Text>Select your favorite animals from the list below:</Text>
+                <FormField.Root>
+                  <FormField.Label>Animals</FormField.Label>
+                  <ComposedComboBox
+                    aria-label="Animals in dialog"
+                    items={simpleOptions}
+                    selectionMode="single"
+                    selectedKeys={selectedKeys}
+                    onSelectionChange={setSelectedKeys}
+                  />
+                </FormField.Root>
+              </Stack>
+            </Dialog.Body>
+          </Dialog.Content>
+        </Dialog.Root>
+      </Stack>
+    );
+  },
+
+  play: async ({ canvasElement, step }) => {
+    // Use parentNode to capture both canvas and portal content (Dialog pattern)
+    const canvas = within(
+      (canvasElement.parentNode as HTMLElement) ?? canvasElement
+    );
+
+    await step("Open dialog", async () => {
+      const trigger = canvas.getByRole("button", {
+        name: "Open Dialog with ComboBox",
+      });
+      await userEvent.click(trigger);
+
+      // Wait for dialog to appear in portal
+      await waitFor(() => {
+        expect(canvas.getByRole("dialog")).toBeInTheDocument();
+      });
+    });
+
+    await step("Open ComboBox listbox", async () => {
+      const combobox = canvas.getByRole("combobox", {
+        name: "Animals in dialog",
+      });
+
+      // Focus the combobox first to ensure it's interactive
+      await userEvent.click(combobox);
+      await userEvent.keyboard("{ArrowDown}");
+
+      // Wait for listbox to appear (ComboBox also uses portal)
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).toBeInTheDocument();
+      });
+    });
+
+    await step("Verify listbox positioning relative to trigger", async () => {
+      const combobox = canvas.getByRole("combobox", {
+        name: "Animals in dialog",
+      });
+      const listbox = getListBox(document) as HTMLElement;
+
+      expect(listbox).toBeInTheDocument();
+
+      // Get bounding rectangles
+      const comboboxRect = combobox.getBoundingClientRect();
+      const listboxRect = listbox.getBoundingClientRect();
+
+      // Verify listbox appears above OR below the combobox trigger within tolerance
+      // React Aria will flip the popover based on available space
+      const tolerance = 5;
+      const isBelow = listboxRect.top >= comboboxRect.bottom - tolerance;
+      const isAbove = listboxRect.bottom <= comboboxRect.top + tolerance;
+
+      expect(isBelow || isAbove).toBe(true);
+
+      // Verify horizontal alignment (listbox should be aligned with combobox)
+      // Allow tolerance for borders/padding/scrollbars
+      expect(Math.abs(listboxRect.left - comboboxRect.left)).toBeLessThan(20);
+    });
+
+    await step("Select an option and verify behavior", async () => {
+      // Select "Koala" option
+      await selectOptionsByName(["Koala"]);
+
+      // Wait for listbox to close after selection (single-select closes automatically)
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).not.toBeInTheDocument();
+      });
+
+      // Verify combobox input now shows the selected value
+      const comboboxInput = canvas.getByRole("combobox", {
+        name: "Animals in dialog",
+      }) as HTMLInputElement;
+      await waitFor(() => {
+        expect(comboboxInput.value).toBe("Koala");
+      });
+    });
+
+    await step("Close dialog and verify cleanup", async () => {
+      // Close via Escape key
+      await userEvent.keyboard("{Escape}");
+
+      // Wait for dialog to disappear
+      await waitFor(() => {
+        expect(canvas.queryByRole("dialog")).not.toBeInTheDocument();
+      });
+
+      // Verify listbox is also cleaned up
+      await waitFor(() => {
+        const listbox = getListBox(document);
+        expect(listbox).not.toBeInTheDocument();
+      });
+    });
+  },
 };
diff --git a/packages/nimbus/src/components/combobox/combobox.tsx b/packages/nimbus/src/components/combobox/combobox.tsx
index 30d65df8e..7ecda355e 100644
--- a/packages/nimbus/src/components/combobox/combobox.tsx
+++ b/packages/nimbus/src/components/combobox/combobox.tsx
@@ -1,55 +1,255 @@
+// Export individual components
 import {
   ComboBoxRoot,
-  ComboBoxOptionGroup,
+  ComboBoxTrigger,
+  ComboBoxPopover,
+  ComboBoxListBox,
   ComboBoxOption,
+  ComboBoxSection,
 } from "./components";
 
+// Export filter utilities
+import {
+  filterByText,
+  filterByStartsWith,
+  filterByCaseSensitive,
+  filterByWordBoundary,
+  filterByFuzzy,
+  createMultiPropertyFilter,
+  createRankedFilter,
+  createMultiTermFilter,
+  createSectionAwareFilter,
+} from "./utils/filters";
+
+/**
+ * # ComboBox
+ * ============================================================
+ *
+ * A searchable, filterable selection component with single and multi-select support.
+ * Built with React Aria Components for accessibility and keyboard navigation.
+ *
+ * @see {@link https://nimbus-documentation.vercel.app/components/inputs/combobox}
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root items={items}>
+ *   <ComboBox.Trigger />
+ *   <ComboBox.Popover>
+ *     <ComboBox.ListBox>
+ *       {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+ *     </ComboBox.ListBox>
+ *   </ComboBox.Popover>
+ * </ComboBox.Root>
+ * ```
+ */
 export const ComboBox = {
   /**
    * # ComboBox.Root
    *
-   * The root container for the combobox component. Provides state management and configuration
-   * for all child parts. Supports both single and multiple selection modes.
+   * The root component that provides state management and context for the combobox.
+   * Handles selection state, input filtering, popover open/close, and keyboard navigation.
    *
    * @example
    * ```tsx
-   * <ComboBox.Root>
-   *   <ComboBox.Option>Option 1</ComboBox.Option>
-   *   <ComboBox.Option>Option 2</ComboBox.Option>
+   * <ComboBox.Root items={items}>
+   *   <ComboBox.Trigger />
+   *   <ComboBox.Popover>
+   *     <ComboBox.ListBox>
+   *       {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+   *     </ComboBox.ListBox>
+   *   </ComboBox.Popover>
    * </ComboBox.Root>
    * ```
    */
   Root: ComboBoxRoot,
+
   /**
-   * # ComboBox.OptionGroup
+   * # ComboBox.Trigger
    *
-   * Groups related options together with an optional label. Used to organize options into
-   * logical sections within the combobox dropdown.
+   * The trigger element that contains the input field and controls for the combobox.
+   * Automatically renders tag group (multi-select), input field, toggle button, and clear button.
    *
    * @example
    * ```tsx
-   * <ComboBox.Root>
-   *   <ComboBox.OptionGroup label="Fruits">
-   *     <ComboBox.Option>Apple</ComboBox.Option>
-   *     <ComboBox.Option>Banana</ComboBox.Option>
-   *   </ComboBox.OptionGroup>
+   * <ComboBox.Root items={items}>
+   *   <ComboBox.Trigger />
+   *   <ComboBox.Popover>...</ComboBox.Popover>
    * </ComboBox.Root>
    * ```
    */
-  OptionGroup: ComboBoxOptionGroup,
+  Trigger: ComboBoxTrigger,
+
+  /**
+   * # ComboBox.Popover
+   *
+   * The popover container that displays the dropdown options list.
+   * Renders in a React portal and handles positioning relative to the trigger.
+   *
+   * @example
+   * ```tsx
+   * <ComboBox.Popover>
+   *   <ComboBox.ListBox>
+   *     {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+   *   </ComboBox.ListBox>
+   * </ComboBox.Popover>
+   * ```
+   */
+  Popover: ComboBoxPopover,
+
+  /**
+   * # ComboBox.ListBox
+   *
+   * The container for dropdown options that displays filtered results.
+   *
+   * Use the render prop pattern - do **NOT** manually map over items as this is less performant.
+   *
+   * @example
+   * ```tsx
+   * <ComboBox.ListBox>
+   *   {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+   * </ComboBox.ListBox>
+   * ```
+   */
+  ListBox: ComboBoxListBox,
+
   /**
    * # ComboBox.Option
    *
-   * An individual selectable option within the combobox. Displays a checkbox indicator
-   * in multiple selection mode and supports custom content rendering.
+   * An individual selectable option within the listbox.
+   * Displays a checkmark indicator for selected items in multi-select mode.
    *
    * @example
    * ```tsx
-   * <ComboBox.Root>
-   *   <ComboBox.Option>Option 1</ComboBox.Option>
-   *   <ComboBox.Option>Option 2</ComboBox.Option>
-   * </ComboBox.Root>
+   * <ComboBox.Option>Option text</ComboBox.Option>
+   * ```
+   *
+   * @example Render prop pattern
+   * ```tsx
+   * <ComboBox.Option>
+   *   {({ isSelected }) => (
+   *     <span>Option 1 {isSelected && "✓"}</span>
+   *   )}
+   * </ComboBox.Option>
    * ```
    */
   Option: ComboBoxOption,
+
+  /**
+   * # ComboBox.Section
+   *
+   * Groups related options together with an optional heading.
+   * Supports render prop pattern for dynamic option rendering within sections.
+   *
+   * @example
+   * ```tsx
+   * <ComboBox.Section label="Category Name">
+   *   <ComboBox.Option id="opt-1">Option 1</ComboBox.Option>
+   *   <ComboBox.Option id="opt-2">Option 2</ComboBox.Option>
+   * </ComboBox.Section>
+   * ```
+   *
+   * @example Render prop pattern
+   * ```tsx
+   * <ComboBox.Section items={categoryItems}>
+   *   {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+   * </ComboBox.Section>
+   * ```
+   */
+  Section: ComboBoxSection,
+
+  /**
+   * # ComboBox.filters
+   *
+   * Built-in filter functions and utilities for customizing ComboBox filtering behavior.
+   * These filters can be passed to the `filter` prop on ComboBox.Root to control how options are filtered based on user input.
+   *
+   * **Available Filters:**
+   * - `filterByText`: Default substring matching (case-insensitive)
+   * - `filterByStartsWith`: Prefix matching
+   * - `filterByCaseSensitive`: Exact case substring matching
+   * - `filterByWordBoundary`: Word boundary matching
+   * - `filterByFuzzy`: Fuzzy matching (characters in order)
+   * - `createMultiPropertyFilter`: Search across multiple object properties
+   * - `createRankedFilter`: Custom scoring/ranking logic
+   * - `createMultiTermFilter`: OR logic for multiple search terms
+   * - `createSectionAwareFilter`: Preserves section structure while filtering
+   *
+   * @example Basic filter usage
+   * ```tsx
+   * import { ComboBox } from '@commercetools/nimbus';
+   *
+   * function MyComponent() {
+   *   return (
+   *     <ComboBox.Root
+   *       items={items}
+   *       filter={ComboBox.filters.filterByStartsWith}
+   *     >
+   *       <ComboBox.Trigger />
+   *       <ComboBox.Popover>
+   *         <ComboBox.ListBox>
+   *           {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+   *         </ComboBox.ListBox>
+   *       </ComboBox.Popover>
+   *     </ComboBox.Root>
+   *   );
+   * }
+   * ```
+   *
+   * @example Multi-property search
+   * ```tsx
+   * const productFilter = ComboBox.filters.createMultiPropertyFilter<Product>([
+   *   'name',
+   *   'category',
+   *   'description'
+   * ]);
+   *
+   * function ProductSearch() {
+   *   return (
+   *     <ComboBox.Root items={products} filter={productFilter}>
+   *       <ComboBox.Trigger />
+   *       <ComboBox.Popover>
+   *         <ComboBox.ListBox>
+   *           {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+   *         </ComboBox.ListBox>
+   *       </ComboBox.Popover>
+   *     </ComboBox.Root>
+   *   );
+   * }
+   * ```
+   *
+   * @example Section-aware filtering
+   * ```tsx
+   * const sectionFilter = ComboBox.filters.createSectionAwareFilter(
+   *   ComboBox.filters.filterByFuzzy
+   * );
+   *
+   * function SectionedSearch() {
+   *   return (
+   *     <ComboBox.Root items={sectionsWithItems} filter={sectionFilter}>
+   *       <ComboBox.Trigger />
+   *       <ComboBox.Popover>
+   *         <ComboBox.ListBox>
+   *           {(section) => (
+   *             <ComboBox.Section>
+   *               {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+   *             </ComboBox.Section>
+   *           )}
+   *         </ComboBox.ListBox>
+   *       </ComboBox.Popover>
+   *     </ComboBox.Root>
+   *   );
+   * }
+   * ```
+   */
+  filters: {
+    filterByText,
+    filterByStartsWith,
+    filterByCaseSensitive,
+    filterByWordBoundary,
+    filterByFuzzy,
+    createMultiPropertyFilter,
+    createRankedFilter,
+    createMultiTermFilter,
+    createSectionAwareFilter,
+  },
 };
diff --git a/packages/nimbus/src/components/combobox/combobox.types.ts b/packages/nimbus/src/components/combobox/combobox.types.ts
index 033fa132f..cb7e353db 100644
--- a/packages/nimbus/src/components/combobox/combobox.types.ts
+++ b/packages/nimbus/src/components/combobox/combobox.types.ts
@@ -1,256 +1,865 @@
-import type { ReactNode, Ref, RefObject } from "react";
+import type { ReactNode, Ref } from "react";
+import type { Node, Key, Collection } from "react-stately";
 import type {
-  HTMLChakraProps,
-  RecipeProps,
-  SlotRecipeProps,
-} from "@chakra-ui/react";
-import type {
-  ComboBoxProps as RaComboBoxProps,
-  AutocompleteProps as RaAutoCompleteProps,
+  ComboBoxRenderProps,
+  InputProps as RaInputProps,
   ListBoxProps as RaListBoxProps,
   ListBoxItemProps as RaListBoxItemProps,
   ListBoxSectionProps as RaListBoxSectionProps,
 } from "react-aria-components";
-import type React from "react";
+import type {
+  HTMLChakraProps,
+  SlotRecipeProps,
+  UnstyledProp,
+} from "@chakra-ui/react";
+import type { TagGroupProps as NimbusTagGroupProps } from "../tag-group/tag-group.types";
+import type { PopoverProps as NimbusPopoverProps } from "../popover/popover.types";
 import type { OmitInternalProps } from "../../type-utils/omit-props";
 
 // ============================================================
 // RECIPE PROPS
 // ============================================================
 
-type ComboBoxRecipeVariantProps = {
+type ComboBoxRecipeProps = {
   /**
-   * Size variant of the combobox
+   * Size variant of combobox
    * @default "md"
    */
   size?: SlotRecipeProps<"combobox">["size"];
   /**
-   * Visual style variant of the combobox
+   * Variant of combobox
    * @default "solid"
    */
   variant?: SlotRecipeProps<"combobox">["variant"];
-  /**
-   * Selection mode for the combobox
-   * @default "single"
-   */
-  selectionMode?: SlotRecipeProps<"combobox">["selectionMode"];
-};
+} & UnstyledProp;
 
 // ============================================================
 // SLOT PROPS
 // ============================================================
 
-export type ComboBoxSingleSelectRootSlotProps<T extends object> =
-  HTMLChakraProps<
-    "div",
-    ComboBoxRecipeVariantProps & ComboBoxWithCustomChildren<T>
-  >;
-
-export type ComboBoxMultiSelectRootSlotProps<T extends object> =
-  HTMLChakraProps<"div", ComboBoxRecipeVariantProps & ComboBoxMultiSelect<T>>;
-
-export type ComboBoxValueSlotProps = HTMLChakraProps<
-  "div",
-  RecipeProps<"value">
->;
-
-export type ComboBoxButtonGroupSlotProps = HTMLChakraProps<
-  "div",
-  RecipeProps<"buttonGroup">
->;
-
-export type ComboBoxPopoverSlotProps = HTMLChakraProps<
-  "div",
-  RecipeProps<"popover">
->;
-
-export type ComboBoxMultiSelectInputSlotProps = HTMLChakraProps<
-  "input",
-  RecipeProps<"multiSelectInput">
->;
-
-export type ComboBoxOptionsSlotProps = HTMLChakraProps<
-  "div",
-  RecipeProps<"options">
->;
-
-export type ComboBoxOptionGroupSlotProps = HTMLChakraProps<
-  "div",
-  RecipeProps<"div">
->;
-
-export type ComboBoxOptionSlotProps = HTMLChakraProps<
-  "div",
-  RecipeProps<"div">
->;
-
-export type ComboBoxOptionIndicatorSlotProps = HTMLChakraProps<
-  "span",
-  RecipeProps<"span">
->;
-
-export type ComboBoxOptionContentSlotProps = HTMLChakraProps<
-  "span",
-  RecipeProps<"span">
->;
+export type ComboBoxRootSlotProps = HTMLChakraProps<"div", ComboBoxRecipeProps>;
+export type ComboBoxTriggerSlotProps = HTMLChakraProps<"div">;
+export type ComboBoxLeadingElementSlotProps = HTMLChakraProps<"div">;
+export type ComboBoxContentSlotProps = HTMLChakraProps<"div">; // Flex wrapper for tags and input
+export type ComboBoxTagGroupSlotProps = HTMLChakraProps<"div">;
+export type ComboBoxInputSlotProps = HTMLChakraProps<"div">; // Wraps React Aria Input
+export type ComboBoxPopoverSlotProps = HTMLChakraProps<"div">;
+export type ComboBoxListBoxSlotProps = HTMLChakraProps<"div">; // Will wrap React Aria ListBox
+export type ComboBoxOptionSlotProps = HTMLChakraProps<"div">; // Will wrap React Aria ListBoxItem
+export type ComboBoxOptionIndicatorSlotProps = HTMLChakraProps<"div">; // Indicator for selected state (multi-select)
+export type ComboBoxOptionContentSlotProps = HTMLChakraProps<"div">; // Content wrapper for option text
+export type ComboBoxSectionSlotProps = HTMLChakraProps<"div">; // Will wrap React Aria Section
 
 // ============================================================
 // HELPER TYPES
 // ============================================================
 
 /**
- * ComboBox with overridden children prop based on expected dom structure.
+ * Filter function for collection items
+ *
+ * @param nodes - Collection nodes to filter (includes sections and items)
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes
  */
-type ComboBoxWithCustomChildren<T extends object> = Omit<
-  RaComboBoxProps<T>,
-  "children"
-> & {
-  onSubmitCustomValue?: (value: string) => void;
-  renderEmptyState?: RaListBoxProps<T>["renderEmptyState"];
-  placeholder?: string;
-  isLoading?: boolean;
-  children: ReactNode | ((item: T) => React.ReactNode);
-  ref?: Ref<HTMLDivElement>;
-};
+export type ComboBoxFilter<T extends object> = (
+  nodes: Iterable<Node<T>>,
+  inputValue: string
+) => Iterable<Node<T>>;
 
 /**
- * MultiSelect combobox configuration
+ * Async configuration for ComboBox with built-in useAsyncList integration
+ *
+ * @template T - Type for item data returned by the load function
  */
-export type ComboBoxMultiSelect<T extends object> = Omit<
-  RaAutoCompleteProps,
-  "children" | "filter" | "slot"
-> &
-  Omit<RaListBoxProps<T>, "filter" | "autoFocus" | "style" | "slot"> & {
-    defaultFilter?: (textValue: string, inputValue: string) => boolean;
-    defaultInputValue?: RaComboBoxProps<T>["defaultInputValue"];
-    defaultItems?: RaComboBoxProps<T>["defaultItems"];
-    validate?: RaComboBoxProps<T>["validate"];
-    allowsCustomValue?: boolean;
-    onSubmitCustomValue?: (value: string) => void;
-    onOpenChange?: RaComboBoxProps<T>["onOpenChange"];
-    autoFocus?: boolean;
-    isLoading?: boolean;
-    isDisabled?: boolean;
-    isReadOnly?: boolean;
-    isRequired?: boolean;
-    isInvalid?: boolean;
-    itemId?: string;
-    itemValue?: string;
-    placeholder?: string;
-    ref?: Ref<HTMLDivElement>;
-    leadingElement?: ReactNode;
-    size?: ComboBoxRecipeVariantProps["size"];
-  };
+export type ComboBoxAsyncConfig<T extends object> = {
+  /**
+   * Async function to load items based on filter text.
+   * Automatically receives an AbortSignal for request cancellation.
+   *
+   * @param filterText - Current input value to filter by
+   * @param signal - AbortSignal for cancelling the request
+   * @returns Promise resolving to array of items
+   *
+   * @example
+   * ```tsx
+   * async: {{
+   *   load: async (filterText, signal) => {
+   *     const response = await fetch(
+   *       `/api/search?q=${encodeURIComponent(filterText)}`,
+   *       { signal }
+   *     );
+   *     const data = await response.json();
+   *     return data.results;
+   *   }
+   * }}
+   * ```
+   */
+  load: (filterText: string, signal: AbortSignal) => Promise<T[]>;
+
+  /**
+   * Minimum number of characters required before triggering a load.
+   * Prevents unnecessary API calls for very short queries.
+   *
+   * @default 0
+   *
+   * @example
+   * ```tsx
+   * async: {{ load, minSearchLength: 2 }} // Only search after typing 2+ chars
+   * ```
+   */
+  minSearchLength?: number;
+
+  /**
+   * Debounce delay in milliseconds before triggering load.
+   * Prevents excessive API calls while user is typing.
+   *
+   * @default 300
+   *
+   * @example
+   * ```tsx
+   * async: {{ load, debounce: 500 }} // Wait 500ms after typing stops
+   * ```
+   */
+  debounce?: number;
+
+  /**
+   * Callback when an error occurs during loading.
+   * Receives the error object for custom error handling.
+   *
+   * @param error - The error that occurred
+   *
+   * @example
+   * ```tsx
+   * async: {{
+   *   load,
+   *   onError: (error) => {
+   *     console.error('Failed to load:', error);
+   *     toast.error('Search failed. Please try again.');
+   *   }
+   * }}
+   * ```
+   */
+  onError?: (error: Error) => void;
+};
+
+// ============================================================
+// CONTEXT VALUE
+// ============================================================
+
+export type ComboBoxRootContextValue<T> = {
+  /** Selection mode determines single vs multi-select behavior */
+  selectionMode: "single" | "multiple";
+
+  /** variant size */
+  size?: SlotRecipeProps<"combobox">["size"];
+
+  /** Extract key from item for TagGroup */
+  getKey: (item: T) => Key;
+
+  /** Extract text value from item for TagGroup */
+  getTextValue: (item: T) => string;
+
+  /** Leading visual element (e.g., search icon) rendered before the input */
+  leadingElement?: ReactNode;
+
+  /** Ref to trigger element (for popover positioning) */
+  triggerRef: React.RefObject<HTMLDivElement | null>;
+
+  /** Ref to input element (for programmatic focus) */
+  inputRef: React.RefObject<HTMLInputElement | null>;
+
+  /** Whether component is disabled */
+  isDisabled: boolean;
+
+  /** Whether component is required */
+  isRequired: boolean;
+
+  /** Whether component is invalid */
+  isInvalid: boolean;
+
+  /** Whether component is read-only */
+  isReadOnly: boolean;
+
+  /** Loading state */
+  isLoading?: boolean;
+};
 
 // ============================================================
 // MAIN PROPS
 // ============================================================
 
 /**
- * Props for the ComboBox.Root component in single select mode.
+ * Root component props for unified ComboBox
+ *
+ * @template T - Type for item data displayed in the combobox menu. Items array type is `T[]`.
  */
-export type ComboBoxSingleSelectRootProps<T extends object> =
-  ComboBoxSingleSelectRootSlotProps<T> &
-    ComboBoxWithCustomChildren<T> & {
-      ref?: Ref<HTMLDivElement>;
-      /**
-       * Optional element to display at the start of the input
-       * Will respect text direction (left in LTR, right in RTL)
-       */
-      leadingElement?: ReactNode;
-    };
+export type ComboBoxRootProps<T extends object> = Omit<
+  ComboBoxRootSlotProps,
+  "children"
+> & {
+  /**
+   * Render function for each item, or static JSX children.
+   * Must be React Aria collection elements (Section/Item components).
+   */
+  children?:
+    | ReactNode
+    | ((
+        values: T & {
+          defaultChildren: ReactNode | undefined;
+        } & ComboBoxRenderProps
+      ) => ReactNode);
 
-/**
- * Props for the ComboBox.Root component in multi select mode.
- */
-export type ComboBoxMultiSelectRootProps<T extends object> = Omit<
-  ComboBoxMultiSelectRootSlotProps<T>,
-  "selectionMode"
-> &
-  ComboBoxMultiSelect<T> & {
-    ref?: Ref<HTMLDivElement>;
-  };
+  /**
+   * Selection mode - determines single vs multi-select behavior
+   * @default "single"
+   */
+  selectionMode?: "single" | "multiple";
 
-/**
- * Root element can either be single or multi select.
- */
-export type ComboBoxRootProps<T extends object> =
-  | OmitInternalProps<ComboBoxSingleSelectRootProps<T>>
-  | OmitInternalProps<ComboBoxMultiSelectRootProps<T>>;
+  /**
+   * Collection items to display.
+   * If `children` is not provided, each item will be rendered using `getTextValue`.
+   *
+   * When `allowsCustomOptions` is enabled:
+   * - New items created via Enter key are automatically added to the collection
+   * - Both the items array and selection state are managed internally
+   * - Use `onCreateOption` callback for side effects (API calls, notifications, etc.)
+   */
+  items?: Iterable<T>;
 
-/**
- * Props for the internal ComboBox value display component (multi-select).
- */
-export type ComboBoxMultiSelectValueProps<T extends object> = {
-  items: ComboBoxMultiSelectRootProps<T>["items"];
-  itemId: ComboBoxMultiSelectRootProps<T>["itemId"];
-  itemValue: ComboBoxMultiSelectRootProps<T>["itemValue"];
-  selectedKeys: ComboBoxMultiSelectRootProps<T>["selectedKeys"];
-  onSelectionChange: ComboBoxMultiSelectRootProps<T>["onSelectionChange"];
+  /**
+   * Function to extract unique key from each item when items do not have a `key` or `id` field.
+   * Defaults to using `item.key` or `item.id`.
+   *
+   * **Important:** Wrap this function in `useCallback` to prevent unnecessary
+   * re-synchronization of the list state.
+   *
+   * @param item - The item to extract the key from
+   * @returns The unique key for the item
+   * @default useCallback((item) => (item.key ?? item.id), [])
+   * @example
+   * ```tsx
+   * // ✅ Good: Memoized with useCallback
+   * const getKey = useCallback((item) => item.productId, []);
+   * <ComboBox.Root items={items} getKey={getKey} />
+   *
+   * // ❌ Bad: Inline function creates new identity on every render
+   * <ComboBox.Root items={items} getKey={(item) => item.productId} />
+   * ```
+   */
+  getKey?: (item: T) => Key;
+
+  /**
+   * Function to extract display text from each item when `children` is not provided.
+   * Used for both rendering and filtering.
+   * Defaults to `item.label ?? item.name ?? String(item)`.
+   *
+   * **Important:** Wrap this function in `useCallback` for optimal performance.
+   *
+   * @param item - The item to extract text from
+   * @returns The display text for the item
+   * @default useCallback((item) => item.label ?? item.name ?? String(item), [])
+   * @example
+   * ```tsx
+   * // ✅ Good: Memoized with useCallback
+   * const getTextValue = useCallback((item) => item.displayName, []);
+   * <ComboBox.Root items={items} getTextValue={getTextValue} />
+   *
+   * // ❌ Bad: Inline function creates new identity on every render
+   * <ComboBox.Root items={items} getTextValue={(item) => item.displayName} />
+   * ```
+   */
+  getTextValue?: (item: T) => string;
+
+  /**
+   * Controlled selected keys (unified for single/multi)
+   * Single-select: pass a Key
+   * Multi-select: pass a Key[]
+   *
+   * Internally normalized to Set<Key> for React Stately
+   */
+  selectedKeys?: Key[];
+
+  /**
+   * Callback when selection changes
+   * Always receives an array of keys regardless of selection mode:
+   * - Single-select: `[selectedKey]` or `[]` if nothing selected
+   * - Multi-select: `[key1, key2, ...]` or `[]` if nothing selected
+   */
+  onSelectionChange?: (keys: Key[]) => void;
+
+  /**
+   * Keys of items that should be disabled and not selectable.
+   * Disabled items are still visible but cannot be selected or focused.
+   *
+   * @example
+   * ```tsx
+   * <ComboBox.Root
+   *   items={items}
+   *   disabledKeys={['item-2', 'item-5']}
+   * />
+   * ```
+   */
+  disabledKeys?: Iterable<Key>;
+
+  /**
+   * Input value for controlled mode
+   *
+   * **Controlled Mode:** When `onInputChange` is provided, you manage the input value.
+   * You **MUST** update this prop in response to `onInputChange` for changes to be visible:
+   * - User typing in the input
+   * - Automatic sync on selection changes (single-select mode)
+   * - Input clearing after selection (multi-select mode)
+   *
+   * **Uncontrolled Mode:** When `onInputChange` is NOT provided, the component manages
+   * the input value internally. You can still pass `inputValue` to set the initial value.
+   *
+   * @example
+   * ```tsx
+   * // ✅ Controlled: Update inputValue in response to onInputChange
+   * const [inputValue, setInputValue] = useState("");
+   * <ComboBox.Root
+   *   inputValue={inputValue}
+   *   onInputChange={setInputValue}
+   * />
+   *
+   * // ✅ Uncontrolled: Component manages input internally
+   * <ComboBox.Root
+   *   inputValue="initial search text"
+   *   // No onInputChange - component handles updates
+   * />
+   *
+   * // ❌ Wrong: Controlled prop but never updated
+   * <ComboBox.Root
+   *   inputValue="fixed"
+   *   onInputChange={(v) => console.log(v)} // Input will be frozen
+   * />
+   * ```
+   */
+  inputValue?: string;
+
+  /**
+   * Callback when input value changes
+   *
+   * **When provided:** Enables controlled input mode. You must update `inputValue` prop
+   * in this callback for the input to update.
+   *
+   * **When NOT provided:** Component uses uncontrolled input mode and manages value internally.
+   *
+   * Called when:
+   * - User types in the input
+   * - Selection changes in single-select mode (input syncs to selected item's text)
+   * - Option selected in multi-select mode (input clears)
+   *
+   * @param value - The new input value
+   */
+  onInputChange?: (value: string) => void;
+
+  /**
+   * Custom filter function for collection.
+   * If not provided, uses default text-based filter.
+   *
+   * **Important:** Wrap this function in `useCallback` to prevent
+   * unnecessary re-filtering of the collection on every render.
+   *
+   * @param nodes - Collection nodes to filter (includes sections and items)
+   * @param inputValue - Current filter text from input
+   * @returns Filtered collection nodes
+   *
+   * @example
+   * ```tsx
+   * // ✅ Good: Memoized with useCallback
+   * const customFilter = useCallback((nodes, inputValue) => {
+   *   if (!inputValue) return nodes;
+   *   return Array.from(nodes).filter(node =>
+   *     node.textValue?.toLowerCase().includes(inputValue.toLowerCase())
+   *   );
+   * }, []);
+   *
+   * <ComboBox.Root items={items} filter={customFilter} />
+   *
+   * // ❌ Bad: Inline function creates new identity on every render
+   * <ComboBox.Root
+   *   items={items}
+   *   filter={(nodes, input) => ...}  // Will cause re-filtering on every render
+   * />
+   * ```
+   *
+   * **Built-in Utilities:** For common patterns, use the exported filter utilities:
+   * - `filterByTextWithSections` - Section-aware filtering
+   * - `createSectionAwareFilter` - Factory for custom section-aware filters
+   * - `createMultiPropertyFilter` - Multi-property search filtering
+   */
+  filter?: ComboBoxFilter<T>;
+
+  /**
+   * Placeholder text for input
+   */
   placeholder?: string;
-  isDisabled?: boolean;
-  isReadOnly?: boolean;
-  ref?: Ref<HTMLDivElement>;
-  containerRef?: RefObject<HTMLDivElement | null>;
-  size?: ComboBoxRecipeVariantProps["size"];
+
   /**
-   * Optional element to display at the start of the input
-   * Will respect text direction (left in LTR, right in RTL)
+   * Controls when the menu opens.
+   * - "focus": Opens when input receives focus
+   * - "input": Opens when user types (input value changes)
+   * - "manual": Only opens via button click or arrow down key
+   * @default "input"
    */
-  leadingElement?: ReactNode;
-};
+  menuTrigger?: "focus" | "input" | "manual";
 
-/**
- * Props for the internal ComboBox button group component.
- */
-export type ComboBoxButtonGroupProps = {
-  selectedKeys?: ComboBoxMultiSelectRootProps<object>["selectedKeys"];
-  onSelectionChange?: ComboBoxMultiSelectRootProps<object>["onSelectionChange"];
-  onInputChange?: ComboBoxMultiSelectRootProps<object>["onInputChange"];
-  onOpenChange?: ComboBoxSingleSelectRootProps<object>["onOpenChange"];
-  containerRef?: RefObject<HTMLDivElement | null>;
+  /**
+   * Whether the menu should close when the combobox loses focus.
+   * Set to false to keep menu open when clicking outside.
+   * @default true
+   */
+  shouldCloseOnBlur?: boolean;
+
+  /**
+   * Whether to close the menu after an item is selected (single-select only).
+   * Multi-select always keeps menu open after selection.
+   * @default true
+   */
+  shouldCloseOnSelect?: boolean;
+
+  /**
+   * Controlled open state of the menu
+   */
   isOpen?: boolean;
+
+  /**
+   * Default open state for uncontrolled mode
+   * @default false
+   */
+  defaultOpen?: boolean;
+
+  /**
+   * Callback when menu open state changes
+   */
+  onOpenChange?: (isOpen: boolean) => void;
+
+  /**
+   * Whether to keep the menu open when the filtered collection is empty.
+   * When false (default), the menu automatically closes when no items match the filter.
+   * When true, the menu stays open and can show empty state content.
+   * @default false
+   */
+  allowsEmptyMenu?: boolean;
+
+  /**
+   * Custom render function for empty state when no items match the filter.
+   * Only shown when `allowsEmptyMenu` is true and collection is empty.
+   * Passed through to React Aria's ListBox renderEmptyState prop.
+   * @example
+   * ```tsx
+   * <ComboBox.Root
+   *   allowsEmptyMenu={true}
+   *   renderEmptyState={() => (
+   *     <Box padding="400" textAlign="center">
+   *       <Text color="fg.muted">No results found</Text>
+   *     </Box>
+   *   )}
+   * />
+   * ```
+   */
+  renderEmptyState?: () => ReactNode;
+
+  /**
+   * External loading state for displaying loading indicators.
+   * Useful when managing async data loading externally with React Stately's useAsyncList.
+   *
+   * **Note:** When using the built-in `async` prop, loading state is managed automatically.
+   * This prop is only needed for external async management.
+   *
+   * @example
+   * ```tsx
+   * // External async control with useAsyncList
+   * const asyncList = useAsyncList({
+   *   async load({ filterText, signal }) {
+   *     const res = await fetch(`/api/search?q=${filterText}`, { signal });
+   *     return { items: await res.json() };
+   *   }
+   * });
+   *
+   * <ComboBox.Root
+   *   items={asyncList.items}
+   *   isLoading={asyncList.loadingState === 'loading'}
+   *   inputValue={asyncList.filterText}
+   *   onInputChange={(value) => asyncList.setFilterText(value)}
+   * >
+   *   {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+   * </ComboBox.Root>
+   * ```
+   */
   isLoading?: boolean;
+
+  /**
+   * Built-in async loading configuration with automatic state management.
+   *
+   * When provided, ComboBox automatically handles:
+   * - Loading state management
+   * - Request debouncing (300ms default)
+   * - Request cancellation on input changes
+   * - Automatic filter bypass (since API handles filtering)
+   * - Minimum search length validation
+   * - Error handling with optional callback
+   *
+   * **Important:** When using `async`, do NOT provide `items`, `isLoading`, `inputValue`, or `onInputChange`.
+   * These are managed automatically by the internal useAsyncList integration.
+   *
+   * @example
+   * ```tsx
+   * // Simple async search
+   * <ComboBox.Root
+   *   async={{
+   *     load: async (filterText, signal) => {
+   *       const response = await fetch(
+   *         `/api/search?q=${encodeURIComponent(filterText)}`,
+   *         { signal }
+   *       );
+   *       return response.json();
+   *     }
+   *   }}
+   * >
+   *   {(item: SearchResult) => (
+   *     <ComboBox.Option>{item.name}</ComboBox.Option>
+   *   )}
+   * </ComboBox.Root>
+   *
+   * // With configuration and error handling
+   * <ComboBox.Root
+   *   async={{
+   *     load: async (filterText, signal) => {
+   *       const response = await fetch(`/api/search?q=${filterText}`, { signal });
+   *       const data = await response.json();
+   *       return data.results;
+   *     },
+   *     minSearchLength: 2,
+   *     debounce: 500,
+   *     onError: (error) => {
+   *       console.error('Search failed:', error);
+   *       toast.error('Failed to load results');
+   *     }
+   *   }}
+   * />
+   * ```
+   */
+  async?: ComboBoxAsyncConfig<T>;
+
+  /**
+   * Whether to allow creating custom options that don't exist in the items collection.
+   * When enabled and input doesn't match any existing option, pressing Enter will create
+   * a new option using `getNewOptionData`.
+   *
+   * Requires providing `getNewOptionData` to transform input value into item object.
+   * @default false
+   * @example
+   * ```tsx
+   * <ComboBox.Root
+   *   items={tags}
+   *   allowsCustomOptions={true}
+   *   getNewOptionData={(inputValue) => ({
+   *     id: `tag-${Date.now()}`,
+   *     label: inputValue,
+   *   })}
+   *   onCreateOption={(inputValue) => {
+   *     console.log('Created new tag:', inputValue);
+   *   }}
+   * />
+   * ```
+   */
+  allowsCustomOptions?: boolean;
+
+  /**
+   * Function to validate whether the current input value is valid for creating a new option.
+   * If not provided, any non-empty input that doesn't match an existing option is valid.
+   *
+   * Based on react-select's isValidNewOption API.
+   * @param inputValue - The current input value
+   * @returns True if the input is valid for creating a new option
+   * @example
+   * ```tsx
+   * // Only allow creating tags that start with '#'
+   * isValidNewOption={(inputValue) => {
+   *   return inputValue.startsWith('#') && inputValue.length > 1;
+   * }}
+   *
+   * // Only allow email addresses
+   * isValidNewOption={(inputValue) => {
+   *   return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(inputValue);
+   * }}
+   * ```
+   */
+  isValidNewOption?: (inputValue: string) => boolean;
+
+  /**
+   * Function to transform the input value into a new item object when creating a custom option.
+   * Required when `allowsCustomValue` is true.
+   *
+   * The returned item must be compatible with your items type and have properties
+   * that `getKey` and `getTextValue` can extract.
+   *
+   * Based on react-select's getNewOptionData API.
+   * @param inputValue - The input value to transform
+   * @returns A new item object to add to the collection
+   * @example
+   * ```tsx
+   * // Simple tag creation
+   * getNewOptionData={(inputValue) => ({
+   *   id: `tag-${Date.now()}`,
+   *   label: inputValue,
+   * })}
+   *
+   * // Product creation with additional fields
+   * getNewOptionData={(inputValue) => ({
+   *   id: `product-${Date.now()}`,
+   *   name: inputValue,
+   *   category: 'uncategorized',
+   *   createdAt: new Date(),
+   * })}
+   * ```
+   */
+  getNewOptionData?: (inputValue: string) => T;
+
+  /**
+   * Callback when a new option is created via Enter key on valid input.
+   * Called after the item is added to the collection and selected.
+   *
+   * Use this for side effects like API calls, analytics, or notifications.
+   *
+   * Based on react-select's onCreateOption API.
+   * Note: Unlike react-select, selection changes are still handled by `onSelectionChange`.
+   * @param newOption - The option that was created
+   * @example
+   * ```tsx
+   * onCreateOption={async (newOption) => {
+   *   // Make API call to persist
+   *   await createTagAPI(newOption);
+   *
+   *   // Show notification
+   *   toast.success(`Created tag: ${newOption.value}`);
+   * }}
+   * ```
+   */
+  onCreateOption?: (newOption: T) => void;
+
+  /**
+   * Accessible label for the combobox (when no visible label exists)
+   * @example "Select a product"
+   */
+  "aria-label"?: string;
+
+  /**
+   * ID of external label element (typically from FormField)
+   * Use this when the combobox is wrapped in a FormField component
+   * @example "product-combobox-label"
+   */
+  "aria-labelledby"?: string;
+
+  /**
+   * Leading visual element rendered before the input
+   * Common use cases: search icon, category indicator
+   *
+   * **Accessibility**: Ensure decorative elements have aria-hidden="true".
+   * If the element is functional (clickable), it needs its own aria-label.
+   *
+   * @example
+   * ```tsx
+   * // Decorative icon (recommended)
+   * <ComboBox.Root leadingElement={<Icons.Search aria-hidden="true" />} />
+   *
+   * // Functional element (needs aria-label)
+   * <ComboBox.Root leadingElement={<Button aria-label="Clear search"><Icons.Close /></Button>} />
+   * ```
+   */
+  leadingElement?: ReactNode;
+
+  /**
+   * Whether component is disabled
+   * @default false
+   */
   isDisabled?: boolean;
+
+  /**
+   * Whether component is required
+   * @default false
+   */
+  isRequired?: boolean;
+
+  /**
+   * Whether component is invalid
+   * @default false
+   */
+  isInvalid?: boolean;
+
+  /**
+   * Whether component is read-only
+   * @default false
+   */
   isReadOnly?: boolean;
+
+  /**
+   * Whether keyboard focus should wrap around when navigating through options.
+   * When true, pressing ArrowDown on the last option moves focus to the first option,
+   * and pressing ArrowUp on the first option moves focus to the last option.
+   * @default true
+   */
+  shouldFocusWrap?: boolean;
+
+  /**
+   * Whether to automatically focus the input when the component mounts.
+   * @default false
+   */
+  autoFocus?: boolean;
+
+  /**
+   * The name of the input element, used when submitting an HTML form.
+   * @see https://react-spectrum.adobe.com/react-aria/forms.html
+   */
+  name?: string;
+
+  /**
+   * The current value of the hidden input element for form submission.
+   * By default, the selected key is submitted. Use this to customize the submitted value.
+   * @see https://react-spectrum.adobe.com/react-aria/forms.html
+   */
+  formValue?: "key" | "text";
+
+  /**
+   * Whether to use native HTML form validation to prevent form submission
+   * when the value is missing or invalid, or mark the field as required
+   * or invalid via ARIA.
+   * @default 'aria'
+   */
+  validationBehavior?: "aria" | "native";
+
+  /**
+   * The form element to associate the input with.
+   * Accepts either an HTML form element or the id of a form element.
+   */
+  form?: string | HTMLFormElement;
+
+  /**
+   * A function that validates the current value and returns an error message if invalid.
+   * Called when the value changes and on form submission.
+   * @see https://react-spectrum.adobe.com/react-aria/forms.html#validation
+   */
+  validate?: (value: string | null) => string | string[] | null | undefined;
+
+  /**
+   * Ref to the root element
+   */
+  ref?: Ref<HTMLDivElement>;
 };
 
 /**
- * Props for the internal single select input component.
+ * Props for ComboBox.Trigger component
+ * Wrapper for the input trigger area (contains Input, TagGroup, and IconButtons)
  */
-export type SingleSelectInputProps = {
-  placeholder?: string;
-  inputValue?: string;
-  allowsCustomValue?: boolean;
-  onSubmitCustomValue?: (value: string) => void;
-  onInputChange?: (value: string) => void;
-  ref?: React.Ref<HTMLInputElement>;
+export type ComboBoxTriggerProps = ComboBoxTriggerSlotProps & {
+  /**
+   * Children should be ComboBox.Input, ComboBox.TagGroup, and IconButton components
+   */
+  children?: ReactNode;
 };
 
 /**
- * Props for the ComboBox.Options component.
+ * Props for ComboBox.TagGroup component
+ * Displays selected items as tags (multi-select only)
+ * Gets props from TagGroupContext provided by Nimbus context
  */
-export type ComboBoxOptionsProps<T extends object> = RaListBoxProps<T> &
-  Omit<ComboBoxOptionsSlotProps, keyof RaListBoxProps<T>> & {
-    ref?: Ref<HTMLDivElement>;
-  };
+export type ComboBoxTagGroupProps = ComboBoxTagGroupSlotProps &
+  NimbusTagGroupProps;
+
+/**
+ * Props for ComboBox.Input component
+ * Text input field for filtering and typing
+ * Gets props from InputContext provided by Nimbus context
+ */
+export type ComboBoxInputProps = ComboBoxInputSlotProps & RaInputProps;
+
+/**
+ * Props for ComboBox.Popover component
+ * Popover wrapper for options list
+ * Gets props from PopoverContext provided by Nimbus context
+ */
+export type ComboBoxPopoverProps = NimbusPopoverProps &
+  Omit<ComboBoxPopoverSlotProps, keyof NimbusPopoverProps>;
 
 /**
- * Props for the ComboBox.OptionGroup component.
+ * Props for ComboBox.ListBox component
+ * Container for options
+ * Gets props from ListBoxContext provided by Nimbus context
+ *
+ * @template T - Type for item data displayed in the list. Items array type is `T[]`.
+ *
+ * **Type Inference Limitation:**
+ * Due to TypeScript limitations with generic types in compound components,
+ * the item type cannot be automatically inferred from ComboBox.Root.
+ * When using a render function, you may need to explicitly type the item parameter:
+ *
+ * @example
+ * ```tsx
+ * // ✅ Explicit typing (recommended for type safety)
+ * <ComboBox.ListBox>
+ *   {(item: MyItemType) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+ * </ComboBox.ListBox>
+ *
+ * // ⚠️ Without explicit typing, TypeScript defaults to 'object'
+ * <ComboBox.ListBox>
+ *   {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>} // Type error on item.name
+ * </ComboBox.ListBox>
+ * ```
  */
-export type ComboBoxOptionGroupProps<T extends object> =
-  RaListBoxSectionProps<T> &
-    OmitInternalProps<
-      ComboBoxOptionGroupSlotProps,
-      keyof RaListBoxSectionProps<T>
-    > & {
-      label?: ReactNode;
-    };
+export type ComboBoxListBoxProps<T extends object> = RaListBoxProps<T> &
+  Omit<ComboBoxListBoxSlotProps, keyof RaListBoxProps<T>> & {
+    ref?: Ref<HTMLDivElement>;
+  };
 
 /**
- * Props for the ComboBox.Option component.
+ * Props for ComboBox.Option component
+ * Individual option within the combobox listbox
+ * Supports both static children and render prop pattern
+ *
+ *  @template T - Type for item data displayed in the option. Items array type is `T[]`.
  */
 export type ComboBoxOptionProps<T extends object> = RaListBoxItemProps<T> &
   OmitInternalProps<ComboBoxOptionSlotProps, keyof RaListBoxItemProps<T>> & {
     ref?: Ref<HTMLDivElement>;
   };
+
+/**
+ * Props for ComboBox.Section component
+ * Groups related options together
+ * Supports both static children and collection rendering
+ *
+ *  @template T - Type for item data displayed in the section. Items array type is `T[]`.
+ */
+export type ComboBoxSectionProps<T extends object> = RaListBoxSectionProps<T> &
+  Omit<ComboBoxSectionSlotProps, keyof RaListBoxSectionProps<T>> & {
+    /**
+     * Section label displayed as header
+     */
+    label?: ReactNode;
+
+    ref?: Ref<HTMLDivElement>;
+  };
+
+/**
+ * Props for the ComboBoxHiddenInput component
+ */
+export type ComboBoxHiddenInputProps<T extends object> = {
+  /** Name attribute for form submission */
+  name?: string;
+  /** Form element to associate with */
+  form?: string | HTMLFormElement;
+  /** Selected keys from state */
+  selectedKeys: Set<Key>;
+  /** Selection mode (single or multiple) */
+  selectionMode: "single" | "multiple";
+  /** What to submit: "key" (default) or "text" */
+  formValue?: "key" | "text";
+  /** Whether custom options are allowed (affects default formValue behavior) */
+  allowsCustomOptions?: boolean;
+  /** Collection of items */
+  collection: Collection<Node<T>>;
+  /** Current input value (used as fallback for custom options) */
+  inputValue: string;
+};
diff --git a/packages/nimbus/src/components/combobox/components/combobox.hidden-input.tsx b/packages/nimbus/src/components/combobox/components/combobox.hidden-input.tsx
new file mode 100644
index 000000000..0a8999879
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/components/combobox.hidden-input.tsx
@@ -0,0 +1,86 @@
+import { useMemo } from "react";
+import type { ComboBoxHiddenInputProps } from "../combobox.types";
+
+/**
+ * # ComboBoxHiddenInput (Internal Component)
+ *
+ * Hidden input element for form submission.
+ * Follows React Aria's pattern for ComboBox form integration.
+ *
+ * By default, submits the selected item's key.
+ * When formValue="text" or allowsCustomOptions=true, submits the text value instead.
+ *
+ * @see https://react-spectrum.adobe.com/react-aria/ComboBox.html#html-forms
+ * @internal
+ */
+export const ComboBoxHiddenInput = <T extends object>(
+  props: ComboBoxHiddenInputProps<T>
+) => {
+  const {
+    name,
+    form,
+    selectedKeys,
+    selectionMode,
+    formValue,
+    allowsCustomOptions,
+    collection,
+    inputValue,
+  } = props;
+
+  // Don't render if no name prop provided
+  if (!name) return null;
+
+  // Compute the value for form submission based on formValue prop
+  // Following React Aria's pattern: https://react-spectrum.adobe.com/react-aria/ComboBox.html#html-forms
+  const value = useMemo(() => {
+    if (selectionMode === "single") {
+      const selectedKey = Array.from(selectedKeys)[0];
+      if (!selectedKey) return "";
+
+      // If formValue is "text" or allowsCustomOptions is true, submit the text
+      if (formValue === "text" || allowsCustomOptions) {
+        // Find the selected item and return its text value
+        const selectedItem = Array.from(collection).find(
+          (node) => node.key === selectedKey
+        );
+        return selectedItem?.textValue || inputValue || "";
+      }
+      // Default: return the key
+      return String(selectedKey);
+    } else {
+      // Multi-select: return comma-separated values
+      const keys = Array.from(selectedKeys);
+      if (formValue === "text" || allowsCustomOptions) {
+        return keys
+          .map((key) => {
+            const item = Array.from(collection).find(
+              (node) => node.key === key
+            );
+            return item?.textValue || "";
+          })
+          .filter(Boolean)
+          .join(",");
+      }
+      // Default: return comma-separated keys
+      return keys.join(",");
+    }
+  }, [
+    selectionMode,
+    selectedKeys,
+    formValue,
+    allowsCustomOptions,
+    collection,
+    inputValue,
+  ]);
+
+  return (
+    <input
+      type="hidden"
+      name={name}
+      form={typeof form === "string" ? form : undefined}
+      value={value}
+    />
+  );
+};
+
+ComboBoxHiddenInput.displayName = "ComboBoxHiddenInput";
diff --git a/packages/nimbus/src/components/combobox/components/combobox.input.tsx b/packages/nimbus/src/components/combobox/components/combobox.input.tsx
new file mode 100644
index 000000000..9b40621cf
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/components/combobox.input.tsx
@@ -0,0 +1,58 @@
+import { useContext } from "react";
+import { Input as RaInput, InputContext } from "react-aria-components";
+import { ComboBoxInputSlot } from "../combobox.slots";
+import type { ComboBoxInputProps } from "../combobox.types";
+import { extractStyleProps } from "@/utils";
+import { useComboBoxRootContext } from "./combobox.root-context";
+
+/**
+ * # ComboBox.Input (Internal Component)
+ *
+ * Internal text input field for filtering and typing in the combobox.
+ * Automatically rendered by ComboBox.Trigger - not exposed to consumers.
+ *
+ * Consumes React Aria's InputContext which provides all necessary ARIA attributes
+ * (role, aria-autocomplete, aria-controls, aria-expanded, etc.).
+ *
+ * Input width dynamically adjusts to match the text content or placeholder length,
+ * collapsing to 1px when empty to avoid creating blank lines in multi-select mode.
+ *
+ * @internal
+ * @supportsStyleProps
+ */
+export const ComboBoxInput = (props: ComboBoxInputProps) => {
+  const [styleProps, functionalProps] = extractStyleProps(props);
+  const inputContext = useContext(InputContext);
+  const { inputRef } = useComboBoxRootContext();
+
+  // Get the current value from context (handle both direct and slotted values)
+  let currentValue = "";
+  let placeholder = "";
+
+  if (
+    inputContext &&
+    typeof inputContext === "object" &&
+    "value" in inputContext
+  ) {
+    currentValue = (inputContext.value as string) || "";
+    placeholder = (inputContext.placeholder as string) || "";
+  }
+
+  // Calculate size attribute: length of value or placeholder, with minimum of 1
+  const inputSize = Math.max(currentValue.length || placeholder.length || 1, 1);
+
+  return (
+    <ComboBoxInputSlot asChild {...styleProps}>
+      <RaInput
+        ref={inputRef}
+        {...functionalProps}
+        size={inputSize}
+        // If the value & placeholder are falsy, input width should be 1px
+        // so it doesn't cause a blank line in content box
+        data-empty={!(!!currentValue.length || !!placeholder.length)}
+      />
+    </ComboBoxInputSlot>
+  );
+};
+
+ComboBoxInput.displayName = "ComboBox.Input";
diff --git a/packages/nimbus/src/components/combobox/components/combobox.leading-element.tsx b/packages/nimbus/src/components/combobox/components/combobox.leading-element.tsx
index 6a127fe1c..da7983742 100644
--- a/packages/nimbus/src/components/combobox/components/combobox.leading-element.tsx
+++ b/packages/nimbus/src/components/combobox/components/combobox.leading-element.tsx
@@ -1,14 +1,13 @@
-import { useEffect, useRef } from "react";
 import { ComboBoxLeadingElementSlot } from "../combobox.slots";
 
 /**
- * This component is needed as proxy around the leading element slot.
- * It measures the width of whatever the user hands over via `leadingElement`
- * and provides this width as css variable on the root element.
+ * # ComboBox.LeadingElement (Internal Component)
  *
- * the css variable is then used in the recipe to update the left-padding of the
- * input.
+ * Internal wrapper component that positions the leading element (icon, avatar, etc.)
+ * within the combobox trigger using CSS Grid's named template area.
+ * Automatically rendered by ComboBox.Trigger when leadingElement prop is provided.
  *
+ * @internal
  * @supportsStyleProps
  */
 export const ComboBoxLeadingElement = ({
@@ -16,33 +15,5 @@ export const ComboBoxLeadingElement = ({
 }: {
   children: React.ReactNode;
 }) => {
-  const elementRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    const element = elementRef.current;
-    if (!element) return;
-
-    const updateWidth = () => {
-      const width = element.offsetWidth;
-      const rootElement = element.closest(".nimbus-combobox__root");
-      if (rootElement instanceof HTMLElement) {
-        rootElement.style.setProperty("--leading-element-width", `${width}px`);
-      }
-    };
-
-    updateWidth();
-
-    const resizeObserver = new ResizeObserver(updateWidth);
-    resizeObserver.observe(element);
-
-    return () => {
-      resizeObserver.disconnect();
-    };
-  }, []);
-
-  return (
-    <ComboBoxLeadingElementSlot ref={elementRef}>
-      {children}
-    </ComboBoxLeadingElementSlot>
-  );
+  return <ComboBoxLeadingElementSlot>{children}</ComboBoxLeadingElementSlot>;
 };
diff --git a/packages/nimbus/src/components/combobox/components/combobox.listbox.tsx b/packages/nimbus/src/components/combobox/components/combobox.listbox.tsx
new file mode 100644
index 000000000..6b144dfcc
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/components/combobox.listbox.tsx
@@ -0,0 +1,80 @@
+import { cloneElement, isValidElement, type ReactElement } from "react";
+import { ListBox as RaListBox } from "react-aria-components";
+import { ComboBoxListBoxSlot } from "../combobox.slots";
+import type { ComboBoxListBoxProps } from "../combobox.types";
+import { extractStyleProps } from "@/utils";
+
+/**
+ * # ComboBox.ListBox
+ *
+ * Container for the dropdown options list that displays filtered results.
+ * Use the render prop pattern - do NOT manually map over items as this is less performant.
+ * The item is automatically provided from the items passed to ComboBox.Root.
+ *
+ * Automatically injects `id` and `textValue` props to Option components from item metadata.
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.ListBox>
+ *   {(item) => (
+ *     <ComboBox.Option>
+ *       {item.name}
+ *     </ComboBox.Option>
+ *   )}
+ * </ComboBox.ListBox>
+ * ```
+ *
+ * @supportsStyleProps
+ */
+export function ComboBoxListBox<T extends object>({
+  children,
+  ref,
+  ...restProps
+}: ComboBoxListBoxProps<T>) {
+  const [styleProps, functionalProps] = extractStyleProps(restProps);
+
+  // Wrap children function to automatically inject id and textValue props
+  const wrappedChildren =
+    typeof children === "function"
+      ? (item: T) => {
+          const element = children(item);
+
+          // If item has id or textValue properties, inject them into the Option
+          const itemWithMetadata = item as T & {
+            id?: string;
+            textValue?: string;
+          };
+
+          if (
+            isValidElement(element) &&
+            (itemWithMetadata.id || itemWithMetadata.textValue)
+          ) {
+            // Clone element and inject id/textValue props
+            // Our injected props come AFTER spread to override any existing values
+            return cloneElement(
+              element as ReactElement<{
+                id?: string;
+                textValue?: string;
+              }>,
+              {
+                ...(element.props as object),
+                ...(itemWithMetadata.id ? { id: itemWithMetadata.id } : {}),
+                ...(itemWithMetadata.textValue
+                  ? { textValue: itemWithMetadata.textValue }
+                  : {}),
+              }
+            );
+          }
+
+          return element;
+        }
+      : children;
+
+  return (
+    <ComboBoxListBoxSlot {...styleProps} ref={ref} asChild>
+      <RaListBox {...functionalProps}>{wrappedChildren}</RaListBox>
+    </ComboBoxListBoxSlot>
+  );
+}
+
+ComboBoxListBox.displayName = "ComboBox.ListBox";
diff --git a/packages/nimbus/src/components/combobox/components/combobox.multi-select-button-group.tsx b/packages/nimbus/src/components/combobox/components/combobox.multi-select-button-group.tsx
deleted file mode 100644
index fc8b99bca..000000000
--- a/packages/nimbus/src/components/combobox/components/combobox.multi-select-button-group.tsx
+++ /dev/null
@@ -1,83 +0,0 @@
-import { useCallback } from "react";
-import { useIntl } from "react-intl";
-import {
-  Close as CloseIcon,
-  KeyboardArrowDown as KeyboardArrowDownIcon,
-  Loop as SpinnerIcon,
-} from "@commercetools/nimbus-icons";
-import { ClearPressResponder } from "@react-aria/interactions";
-import { IconButton, Flex, Box } from "@/components";
-import { ComboBoxButtonGroupSlot } from "../combobox.slots";
-import { type ComboBoxButtonGroupProps } from "../combobox.types";
-import { messages } from "../combobox.i18n";
-
-/**
- * Internal button group for multi-select ComboBox (clear and toggle buttons)
- *
- * @supportsStyleProps
- */
-export const ComboBoxButtonGroup = ({
-  selectedKeys,
-  onSelectionChange,
-  onInputChange,
-  containerRef,
-  isDisabled,
-  isReadOnly,
-  isLoading,
-}: ComboBoxButtonGroupProps) => {
-  const intl = useIntl();
-  const handleClearSelection = useCallback(() => {
-    onSelectionChange?.(new Set());
-    onInputChange?.("");
-    if (containerRef?.current) {
-      containerRef.current.focus();
-    }
-  }, []);
-  return (
-    <ComboBoxButtonGroupSlot>
-      {/** Clears PressableContext (instantiated in DialogTrigger context),
-       * which was passing the same id's to all buttons in the combobox */}
-      <ClearPressResponder>
-        {selectedKeys instanceof Set && selectedKeys.size > 0 && (
-          <IconButton
-            pointerEvents="all"
-            slot={null}
-            size="2xs"
-            variant="ghost"
-            colorPalette="primary"
-            aria-label={intl.formatMessage(messages.clearSelection)}
-            isDisabled={isDisabled || isReadOnly}
-            onPress={handleClearSelection}
-            my="auto"
-          >
-            <CloseIcon />
-          </IconButton>
-        )}
-      </ClearPressResponder>
-
-      <Flex
-        my="auto"
-        w="600"
-        h="600"
-        color="neutral.11"
-        opacity={isReadOnly || isDisabled ? "0.5" : undefined}
-        cursor={isReadOnly || isDisabled ? "not-allowed" : undefined}
-      >
-        <Box pointerEvents="none" asChild m="auto" w="400" h="400">
-          {isLoading ? (
-            <Box
-              asChild
-              animation="spin"
-              animationDuration="slowest"
-              data-testid="nimbus-combobox-loading"
-            >
-              <SpinnerIcon />
-            </Box>
-          ) : (
-            <KeyboardArrowDownIcon />
-          )}
-        </Box>
-      </Flex>
-    </ComboBoxButtonGroupSlot>
-  );
-};
diff --git a/packages/nimbus/src/components/combobox/components/combobox.multi-select-root.tsx b/packages/nimbus/src/components/combobox/components/combobox.multi-select-root.tsx
deleted file mode 100644
index c51cb4966..000000000
--- a/packages/nimbus/src/components/combobox/components/combobox.multi-select-root.tsx
+++ /dev/null
@@ -1,345 +0,0 @@
-import {
-  useState,
-  useRef,
-  useCallback,
-  useEffect,
-  type KeyboardEvent,
-} from "react";
-import React from "react";
-import { useIntl } from "react-intl";
-import { mergeRefs } from "@chakra-ui/react";
-import {
-  Popover as RaPopover,
-  Input as RaInput,
-  Autocomplete as RaAutocomplete,
-  DialogTrigger as RaDialogTrigger,
-  Dialog as RaDialog,
-  TextField as RaTextField,
-  Pressable as RaPressable,
-  type Selection,
-  type Key,
-  useFilter,
-} from "react-aria-components";
-import { MultiSelectTagGroup } from "./combobox.multi-select-tag-group";
-import { ComboBoxOptions } from "./combobox.options";
-import { ComboBoxButtonGroup } from "./combobox.multi-select-button-group";
-import {
-  ComboBoxPopoverSlot,
-  ComboBoxMultiSelectInputSlot,
-} from "../combobox.slots";
-import type { ComboBoxMultiSelect } from "../combobox.types";
-import { ComboBoxLeadingElement } from "./combobox.leading-element";
-import { messages } from "../combobox.i18n";
-
-function getLastValueInSet(set: Set<Key>) {
-  let value;
-  for (value of set);
-  return value;
-}
-
-/**
- * Internal multi-select root implementation for ComboBox
- *
- * @supportsStyleProps
- */
-export const MultiSelectRoot = <T extends object>({
-  children,
-  defaultFilter,
-  inputValue: inputValueProp,
-  defaultInputValue,
-  onInputChange: onInputChangeProp,
-  defaultSelectedKeys = new Set(),
-  selectedKeys: selectedKeysProp,
-  onSelectionChange: onSelectionChangeProp,
-  onOpenChange: onOpenChangeProp,
-  disabledKeys,
-  items: itemsProp,
-  defaultItems,
-  itemId = "id",
-  itemValue = "name",
-  isLoading,
-  isDisabled,
-  isReadOnly,
-  isRequired,
-  isInvalid,
-  className,
-  placeholder,
-  size = "md",
-  allowsCustomValue,
-  onSubmitCustomValue,
-  renderEmptyState,
-  ref,
-  leadingElement,
-  ...props
-}: ComboBoxMultiSelect<T>) => {
-  const intl = useIntl();
-  // Internal state for popover, enables opening on first focus
-  const [isOpen, setOpen] = useState(false);
-  const preventNextFocusOpen = useRef(false);
-
-  // Internal state for selected keys
-  const [_selectedKeys, _setSelectedKeys] = useState<Selection>();
-  // Prefer selected keys from props (controlled), otherwise from internal state and falls back to default (uncontrolled)
-  const selectedKeys = selectedKeysProp ?? _selectedKeys ?? defaultSelectedKeys;
-  // Prefer selection handler from props (controlled), otherwise use internal state (uncontrolled)
-  const setSelectedKeys = onSelectionChangeProp ?? _setSelectedKeys;
-
-  // Internal state for input
-  const [_inputValue, _setInputValue] = useState<string>("");
-  // Prefer input value from props (controlled), otherwise from internal state and falls back to default (uncontrolled)
-  const inputValue = inputValueProp ?? _inputValue ?? defaultInputValue;
-  // Prefer input handler from props (controlled), otherwise use internal state (uncontrolled)
-  const setInputValue = onInputChangeProp ?? _setInputValue;
-  // Prefer items (controlled), fallback to defaultItems (uncontrolled)
-  const items = itemsProp ?? defaultItems;
-
-  const filterUtils = useFilter({ sensitivity: "base" });
-  const contains = (...args: Parameters<typeof filterUtils.contains>) =>
-    filterUtils.contains.apply(undefined, args);
-
-  // Handle popover open/close changes
-  const handleOpenChange = useCallback(
-    (open: boolean) => {
-      // The popover should not be able to open if it is disabled or readonly
-      if (isDisabled || isReadOnly) {
-        // Close the dialog if its open
-        if (isOpen) setOpen(false);
-        return;
-      }
-      // Call onOpenChange prop supplied from props
-      if (onOpenChangeProp) {
-        onOpenChangeProp?.(open);
-      }
-      // Set state value
-      setOpen(open);
-      // When popover goes from open to closed, prevent immediate focus from opening it again (eg when esc key hit, or click outside popover)
-      // Use requestAnimationFrame + setTimeout to ensure focus events have completed
-      if (!open) {
-        preventNextFocusOpen.current = true;
-        // Use RAF to wait for the current frame to complete, then add a small buffer
-        requestAnimationFrame(() => {
-          setTimeout(() => {
-            preventNextFocusOpen.current = false;
-          }, 50);
-        });
-      }
-    },
-    [isDisabled, isReadOnly, onOpenChangeProp, isOpen]
-  );
-
-  // if disabled or readonly after mount, update component
-  useEffect(() => {
-    if (isDisabled || isReadOnly) {
-      handleOpenChange(false);
-    }
-  }, [isDisabled, isReadOnly]);
-
-  // Handle focus - open popover unless recently closed by user
-  const handleOpenPopoverOnFocus = useCallback(
-    (e: React.FocusEvent) => {
-      // Don't open if disabled or readonly
-      if (isDisabled || isReadOnly) {
-        return;
-      }
-      // Only open popover if focus is directly on the main container, not on child elements
-      if (e.target !== e.currentTarget) {
-        return;
-      }
-      if (!isOpen && !preventNextFocusOpen.current) {
-        handleOpenChange(true);
-      }
-    },
-    [isOpen]
-  );
-
-  const deleteLastSelectedItem = useCallback(() => {
-    // Only handle if selectedKeys is a Set (not "all")
-    if (selectedKeys !== "all" && selectedKeys instanceof Set) {
-      const lastKey = getLastValueInSet(selectedKeys as Set<Key>);
-      if (lastKey !== null && lastKey !== undefined) {
-        const newSelection = new Set(selectedKeys);
-        newSelection.delete(lastKey);
-        setSelectedKeys(newSelection);
-      }
-    }
-  }, [selectedKeys, setSelectedKeys]);
-
-  // Enhanced keyboard navigation
-  const handleWrapperKeyDown = useCallback((e: KeyboardEvent) => {
-    if (
-      (e.key === "ArrowDown" || e.key === "ArrowUp" || e.key === "Enter") &&
-      e.target === triggerRef.current
-    ) {
-      e.preventDefault();
-      handleOpenChange(true);
-    }
-  }, []);
-
-  const handleInputKeyDown = useCallback(
-    (e: KeyboardEvent) => {
-      if (e.key === "Backspace" && inputValue === "") {
-        deleteLastSelectedItem();
-        return;
-      }
-
-      // Handle Escape key to close popover and return focus
-      if (e.key === "Escape") {
-        handleOpenChange(false);
-        // Focus management - return to trigger after popover closes
-        if (triggerRef.current) {
-          triggerRef.current.focus();
-        }
-        return; // Prevent any other key handling
-      }
-
-      if (
-        e.key === "Enter" &&
-        inputValue.trim() !== "" &&
-        allowsCustomValue &&
-        onSubmitCustomValue
-      ) {
-        e.stopPropagation();
-        // Use items and filter function to check if input matches any existing item
-        if (items) {
-          const inputValueTrimmed = inputValue.trim();
-          // Find the item that matches the input exactly (case insensitive)
-          const matchingItem = Array.from(items).find((item) => {
-            // Get the text value from the item using itemValue prop
-            const itemText =
-              typeof item === "object" && item !== null && itemValue in item
-                ? String((item as Record<string, unknown>)[itemValue])
-                : JSON.stringify(item);
-            return itemText.toLowerCase() === inputValueTrimmed.toLowerCase();
-          });
-          if (matchingItem) {
-            // get the matching item's key
-            const itemKey =
-              typeof matchingItem === "object" &&
-              matchingItem !== null &&
-              itemId in matchingItem
-                ? ((matchingItem as Record<string, unknown>)[itemId] as Key)
-                : (matchingItem as unknown as Key);
-            // add key to previously selected items
-            const nextSelection = new Set(selectedKeys);
-            nextSelection.add(itemKey);
-            setSelectedKeys(nextSelection);
-            setInputValue("");
-          } else {
-            // Only create custom value if no exact match exists
-            onSubmitCustomValue(inputValue);
-            setInputValue("");
-          }
-        } else {
-          // Fallback: if no items, create the custom value
-          onSubmitCustomValue(inputValue);
-          setInputValue("");
-        }
-      }
-    },
-    [
-      inputValue,
-      deleteLastSelectedItem,
-      allowsCustomValue,
-      onSubmitCustomValue,
-      items,
-      itemValue,
-      itemId,
-      selectedKeys,
-      setSelectedKeys,
-      setInputValue,
-    ]
-  );
-
-  const triggerRef = useRef<HTMLDivElement>(null);
-  const rootRef = mergeRefs(ref, triggerRef);
-
-  return (
-    <RaDialogTrigger isOpen={isOpen} onOpenChange={handleOpenChange}>
-      <RaPressable allowTextSelectionOnPress={true}>
-        <div
-          className={className as string}
-          tabIndex={isDisabled ? -1 : 0}
-          ref={rootRef}
-          role="combobox"
-          onKeyDown={handleWrapperKeyDown}
-          onFocus={handleOpenPopoverOnFocus}
-          aria-expanded={isOpen}
-          aria-haspopup="dialog"
-          aria-disabled={isDisabled}
-          aria-readonly={isReadOnly}
-          aria-required={isRequired}
-          aria-invalid={isInvalid}
-          data-disabled={isDisabled}
-          data-invalid={isInvalid}
-          data-required={isRequired}
-          data-open={isOpen}
-          {...props}
-        >
-          {leadingElement && (
-            <ComboBoxLeadingElement>{leadingElement}</ComboBoxLeadingElement>
-          )}
-          <MultiSelectTagGroup
-            items={items}
-            selectedKeys={selectedKeys}
-            onSelectionChange={setSelectedKeys}
-            itemId={itemId}
-            itemValue={itemValue}
-            placeholder={placeholder}
-            size={size}
-            containerRef={triggerRef}
-            isDisabled={isDisabled}
-            isReadOnly={isReadOnly}
-          />
-          <ComboBoxButtonGroup
-            selectedKeys={selectedKeys}
-            onSelectionChange={setSelectedKeys}
-            onInputChange={setInputValue}
-            containerRef={triggerRef}
-            isDisabled={isDisabled}
-            isReadOnly={isReadOnly}
-            isLoading={isLoading}
-          />
-        </div>
-      </RaPressable>
-      <ComboBoxPopoverSlot asChild>
-        <RaPopover triggerRef={triggerRef} placement="bottom start">
-          <RaDialog aria-label={intl.formatMessage(messages.comboboxDialog)}>
-            <RaAutocomplete
-              filter={defaultFilter ?? contains}
-              inputValue={inputValue}
-              onInputChange={setInputValue}
-            >
-              <ComboBoxMultiSelectInputSlot asChild>
-                <RaTextField
-                  autoFocus
-                  isDisabled={isDisabled}
-                  isReadOnly={isReadOnly}
-                  isRequired={isRequired}
-                  aria-label={intl.formatMessage(messages.filterOptions)}
-                >
-                  <RaInput
-                    onKeyDownCapture={handleInputKeyDown}
-                    placeholder={placeholder}
-                  />
-                </RaTextField>
-              </ComboBoxMultiSelectInputSlot>
-              <ComboBoxOptions
-                items={items}
-                selectionMode="multiple"
-                onSelectionChange={setSelectedKeys}
-                selectedKeys={selectedKeys}
-                shouldFocusWrap={true}
-                disabledKeys={isDisabled ? "all" : disabledKeys}
-                escapeKeyBehavior="none"
-                aria-label={intl.formatMessage(messages.options)}
-                renderEmptyState={renderEmptyState}
-              >
-                {children}
-              </ComboBoxOptions>
-            </RaAutocomplete>
-          </RaDialog>
-        </RaPopover>
-      </ComboBoxPopoverSlot>
-    </RaDialogTrigger>
-  );
-};
diff --git a/packages/nimbus/src/components/combobox/components/combobox.multi-select-tag-group.tsx b/packages/nimbus/src/components/combobox/components/combobox.multi-select-tag-group.tsx
deleted file mode 100644
index 1d4e288e6..000000000
--- a/packages/nimbus/src/components/combobox/components/combobox.multi-select-tag-group.tsx
+++ /dev/null
@@ -1,180 +0,0 @@
-import { useMemo, useCallback } from "react";
-import { useIntl } from "react-intl";
-import { type Key, type Selection } from "react-aria-components";
-import { ClearPressResponder } from "@react-aria/interactions";
-import { TagGroup } from "@/components";
-import type { ComboBoxMultiSelectValueProps } from "../combobox.types";
-import { ComboBoxValueSlot } from "../combobox.slots";
-import { messages } from "../combobox.i18n";
-
-// Type guard to check if an item has children array (sectioned data)
-function hasChildrenArray<T extends object>(
-  item: unknown
-): item is { children: T[] } {
-  return (
-    item !== null &&
-    item !== undefined &&
-    typeof item === "object" &&
-    "children" in item &&
-    Array.isArray((item as { children: unknown }).children)
-  );
-}
-
-function checkItemValidity(
-  item: Record<string, unknown>,
-  idKey: string,
-  valueKey: string
-) {
-  if (!item) return;
-  if (!Object.prototype.hasOwnProperty.call(item, "id") && idKey === "id") {
-    throw new Error(
-      "ComboBox: if items do not have an `id` key, you must specify which key uniquely identifies items using the `itemId` prop"
-    );
-  }
-  if (
-    !Object.prototype.hasOwnProperty.call(item, "name") &&
-    valueKey === "name"
-  ) {
-    throw new Error(
-      "ComboBox: if items do not have a `name` key, you must specify which key can be used as a text value using the `itemValue` prop"
-    );
-  }
-}
-
-/**
- * Internal tag group component for multi-select ComboBox
- *
- * @supportsStyleProps
- */
-export const MultiSelectTagGroup =
-  /* eslint-disable @typescript-eslint/no-explicit-any */
-  <T extends Record<string, any>>({
-    selectedKeys = new Set(),
-    items,
-    itemId = "id",
-    itemValue = "name",
-    placeholder,
-    onSelectionChange,
-    isDisabled,
-    isReadOnly,
-    size,
-    containerRef,
-    ref,
-  }: ComboBoxMultiSelectValueProps<T>) => {
-    const intl = useIntl();
-    const selectedItems = useMemo(() => {
-      if (!items) return [];
-
-      const selectedKeysArray = Array.from(selectedKeys);
-      // Handle sectioned data structure
-      if (Array.isArray(items)) {
-        // Check if items are sections (have children property)
-        const firstItem = items[0] as unknown;
-        if (firstItem && hasChildrenArray<T>(firstItem)) {
-          // Flatten sectioned items
-          const allItems: T[] = [];
-          items.forEach((section) => {
-            if (hasChildrenArray<T>(section as unknown)) {
-              allItems.push(...(section as { children: T[] }).children);
-            }
-          });
-          // make sure we have an id and value
-          checkItemValidity(allItems?.[0], itemId, itemValue);
-          return selectedKeysArray
-            .map((key) => allItems.find((item) => item[itemId] === key))
-            .filter((item): item is T => item !== undefined);
-        }
-
-        // Handle flat array - cast to T[] since we know it's not sectioned
-        const flatItems = items as T[];
-        // make sure we have an id and value
-        checkItemValidity(flatItems?.[0], itemId, itemValue);
-        return selectedKeysArray
-          .map((key) => flatItems.find((item) => item[itemId] === key))
-          .filter((item): item is T => item !== undefined);
-      }
-
-      // Handle other iterable types
-      const iterableItems = selectedKeysArray
-        .map((key) => Array.from(items).find((item) => item[itemId] === key))
-        .filter((item): item is T => item !== undefined);
-      // make sure we have an id and value
-      checkItemValidity(iterableItems?.[0], itemId, itemValue);
-      return iterableItems;
-    }, [items, selectedKeys, itemId]);
-
-    const handleRemoveSelectedItem = useCallback(
-      (keys: Set<Key>) => {
-        // Don't allow removal if disabled
-        if (isDisabled || isReadOnly) return;
-
-        if (selectedKeys instanceof Set) {
-          // Create new selection by removing the specified keys
-          const currentKeys = selectedKeys as Set<Key>;
-          const newSelectedKeys: Selection = new Set(
-            [...currentKeys].filter((key) => !keys.has(key))
-          );
-
-          onSelectionChange?.(newSelectedKeys);
-
-          if (containerRef?.current) {
-            containerRef.current.focus();
-          }
-        }
-      },
-      [isDisabled, isReadOnly, selectedKeys, onSelectionChange]
-    );
-
-    return (
-      <ClearPressResponder>
-        <ComboBoxValueSlot
-          asChild
-          alignItems="space-between"
-          justifyContent="center"
-          ref={ref}
-        >
-          <TagGroup.Root
-            size={size}
-            onRemove={handleRemoveSelectedItem}
-            aria-label={intl.formatMessage(messages.selectedValues)}
-            selectionMode="none"
-            disabledKeys={isDisabled || isReadOnly ? selectedKeys : undefined}
-            data-disabled={isDisabled}
-          >
-            <TagGroup.TagList
-              items={selectedItems}
-              dependencies={[itemId]}
-              maxW={"100%"}
-              tabIndex={
-                selectedItems.length === 0 || isDisabled || isReadOnly
-                  ? -1
-                  : undefined
-              }
-              renderEmptyState={() =>
-                placeholder && (
-                  <div
-                    data-placeholder="true"
-                    style={{
-                      maxWidth: "100%",
-                      overflow: "hidden",
-                      textOverflow: "ellipsis",
-                    }}
-                  >
-                    {placeholder}
-                  </div>
-                )
-              }
-            >
-              {(item) => {
-                return (
-                  <TagGroup.Tag id={item[itemId] as string} maxW={"100%"}>
-                    {item[itemValue]}
-                  </TagGroup.Tag>
-                );
-              }}
-            </TagGroup.TagList>
-          </TagGroup.Root>
-        </ComboBoxValueSlot>
-      </ClearPressResponder>
-    );
-  };
diff --git a/packages/nimbus/src/components/combobox/components/combobox.option-group.tsx b/packages/nimbus/src/components/combobox/components/combobox.option-group.tsx
deleted file mode 100644
index ca4e7861f..000000000
--- a/packages/nimbus/src/components/combobox/components/combobox.option-group.tsx
+++ /dev/null
@@ -1,49 +0,0 @@
-import { type RefAttributes, type ReactNode } from "react";
-import {
-  ListBoxSection as RaListBoxSection,
-  Header as RaHeader,
-  Collection,
-} from "react-aria-components";
-import { ComboBoxOptionGroupSlot } from "../combobox.slots";
-import type { ComboBoxOptionGroupProps } from "../combobox.types";
-
-/**
- * ComboBox.OptionGroup - Groups related options with an optional label
- *
- * @supportsStyleProps
- */
-export const ComboBoxOptionGroup = <T extends object>({
-  children,
-  label,
-  items,
-  ref,
-  ...props
-}: ComboBoxOptionGroupProps<T> & RefAttributes<HTMLDivElement>) => {
-  // Validate that children is a function when items is provided
-  if (items && typeof children !== "function") {
-    throw new Error(
-      'ComboBoxOptionGroup: When "items" is provided, "children" must be a function'
-    );
-  }
-  return (
-    <RaListBoxSection ref={ref} {...props}>
-      <ComboBoxOptionGroupSlot asChild>
-        <RaHeader>{label}</RaHeader>
-      </ComboBoxOptionGroupSlot>
-      {items ? (
-        <Collection items={items}>
-          {(item: T) => {
-            if (typeof children === "function") {
-              return children(item);
-            }
-            return null;
-          }}
-        </Collection>
-      ) : (
-        (children as ReactNode)
-      )}
-    </RaListBoxSection>
-  );
-};
-
-ComboBoxOptionGroup.displayName = "ComboBox.OptionGroup";
diff --git a/packages/nimbus/src/components/combobox/components/combobox.option.tsx b/packages/nimbus/src/components/combobox/components/combobox.option.tsx
index eb686e8c3..0bd7d9c63 100644
--- a/packages/nimbus/src/components/combobox/components/combobox.option.tsx
+++ b/packages/nimbus/src/components/combobox/components/combobox.option.tsx
@@ -9,26 +9,45 @@ import type { ComboBoxOptionProps } from "../combobox.types";
 import { extractStyleProps } from "@/utils";
 
 /**
- * ComboBox.Option - An individual selectable option within the combobox
+ * # ComboBox.Option
+ *
+ * Individual option within the combobox listbox.
+ * Wraps React Aria's ListBoxItem for automatic ARIA management.
+ * Displays a checkmark indicator for selected items in multi-select mode.
+ * Supports render prop pattern for custom rendering.
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root>
+ *   <ComboBox.Option id="1">Option 1</ComboBox.Option>
+ *   <ComboBox.Option id="2">Option 2</ComboBox.Option>
+ * </ComboBox.Root>
+ * ```
+ *
+ * @example Render prop pattern
+ * ```tsx
+ * <ComboBox.Option id="1">
+ *   {({ isSelected, isDisabled }) => (
+ *     <div>
+ *       Option 1 {isSelected && "(Selected)"}
+ *     </div>
+ *   )}
+ * </ComboBox.Option>
+ * ```
  *
  * @supportsStyleProps
  */
-export const ComboBoxOption = <T extends object>({
+
+export function ComboBoxOption<T extends object>({
   children,
   ref,
   ...props
-}: ComboBoxOptionProps<T>) => {
+}: ComboBoxOptionProps<T>) {
   const [styleProps, restProps] = extractStyleProps(props);
-  const textValue = typeof children === "string" ? children : undefined;
 
   return (
     <ComboBoxOptionSlot {...styleProps} asChild>
-      <ListBoxItem
-        ref={ref}
-        textValue={props.textValue ?? textValue}
-        aria-label={props.textValue ?? textValue}
-        {...restProps}
-      >
+      <ListBoxItem ref={ref} {...restProps}>
         {(renderProps) => {
           const content =
             typeof children === "function"
@@ -53,6 +72,6 @@ export const ComboBoxOption = <T extends object>({
       </ListBoxItem>
     </ComboBoxOptionSlot>
   );
-};
+}
 
 ComboBoxOption.displayName = "ComboBox.Option";
diff --git a/packages/nimbus/src/components/combobox/components/combobox.options.tsx b/packages/nimbus/src/components/combobox/components/combobox.options.tsx
deleted file mode 100644
index ea5e344ff..000000000
--- a/packages/nimbus/src/components/combobox/components/combobox.options.tsx
+++ /dev/null
@@ -1,26 +0,0 @@
-import { ListBox as RaListBox } from "react-aria-components";
-import { ComboBoxOptionsSlot } from "../combobox.slots";
-import type { ComboBoxOptionsProps } from "../combobox.types";
-import { extractStyleProps } from "@/utils";
-
-/**
- * ComboBox.Options - Container for the list of selectable options
- *
- * @supportsStyleProps
- */
-export const ComboBoxOptions = <T extends object>({
-  children,
-  ref,
-  ...props
-}: ComboBoxOptionsProps<T>) => {
-  const [styleProps, restProps] = extractStyleProps(props);
-  return (
-    <ComboBoxOptionsSlot {...styleProps} asChild>
-      <RaListBox ref={ref} {...restProps}>
-        {children}
-      </RaListBox>
-    </ComboBoxOptionsSlot>
-  );
-};
-
-ComboBoxOptions.displayName = "ComboBox.Options";
diff --git a/packages/nimbus/src/components/combobox/components/combobox.popover.tsx b/packages/nimbus/src/components/combobox/components/combobox.popover.tsx
new file mode 100644
index 000000000..f2571c4b3
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/components/combobox.popover.tsx
@@ -0,0 +1,49 @@
+import { Popover } from "../../popover";
+import { ComboBoxPopoverSlot } from "../combobox.slots";
+import type { ComboBoxPopoverProps } from "../combobox.types";
+import { extractStyleProps } from "@/utils";
+
+/**
+ * # ComboBox.Popover
+ *
+ * Popover wrapper for the options dropdown list.
+ * Uses Nimbus Popover component which reads from PopoverContext provided by the custom context provider.
+ *
+ * The PopoverContext provides:
+ * - open state
+ * - positioning configuration (fixed strategy, bottom-start placement, --nimbus-combobox-trigger-width CSS var)
+ * - positionReference (trigger ref for proper positioning)
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Popover>
+ *   <ComboBox.ListBox>
+ *     {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+ *   </ComboBox.ListBox>
+ * </ComboBox.Popover>
+ * ```
+ *
+ * @supportsStyleProps
+ */
+export const ComboBoxPopover = ({
+  children,
+  ref,
+  ...restProps
+}: ComboBoxPopoverProps) => {
+  const [styleProps, functionalProps] = extractStyleProps(restProps);
+
+  return (
+    <ComboBoxPopoverSlot asChild {...styleProps}>
+      <Popover
+        ref={ref}
+        isNonModal={true}
+        autoFocus={true}
+        {...functionalProps}
+      >
+        {children}
+      </Popover>
+    </ComboBoxPopoverSlot>
+  );
+};
+
+ComboBoxPopover.displayName = "ComboBox.Popover";
diff --git a/packages/nimbus/src/components/combobox/components/combobox.root-context.tsx b/packages/nimbus/src/components/combobox/components/combobox.root-context.tsx
new file mode 100644
index 000000000..a1225ef94
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/components/combobox.root-context.tsx
@@ -0,0 +1,30 @@
+import { createContext, useContext } from "react";
+import type { ComboBoxRootContextValue } from "../combobox.types";
+
+/**
+ * Context for ComboBox state and configuration.
+ * Uses 'object' as the generic type since different ComboBox instances
+ * can have different item types, and TypeScript can't track this through context.
+ */
+export const ComboBoxRootContext =
+  createContext<ComboBoxRootContextValue<object> | null>(null);
+
+/**
+ * Hook to access ComboBox context with proper typing.
+ * The generic type T represents the item type used in the ComboBox.
+ * At runtime, the context contains the correct type from ComboBox.Root.
+ */
+export const useComboBoxRootContext = <
+  T extends object = object,
+>(): ComboBoxRootContextValue<T> => {
+  const context = useContext(ComboBoxRootContext);
+  if (!context) {
+    throw new Error(
+      "Nimbus - ComboBox components must be used within ComboBox.Root"
+    );
+  }
+  // Type assertion is safe: ComboBox.Root provides the context with type T,
+  // but TypeScript can't track generics through context at compile time.
+  // We use 'unknown' as an intermediate step to satisfy TypeScript's strict checking.
+  return context as unknown as ComboBoxRootContextValue<T>;
+};
diff --git a/packages/nimbus/src/components/combobox/components/combobox.root.tsx b/packages/nimbus/src/components/combobox/components/combobox.root.tsx
index 41121f038..d2fc3dffa 100644
--- a/packages/nimbus/src/components/combobox/components/combobox.root.tsx
+++ b/packages/nimbus/src/components/combobox/components/combobox.root.tsx
@@ -1,45 +1,1451 @@
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type RefObject,
+} from "react";
+
 import { useSlotRecipe } from "@chakra-ui/react/styled-system";
-import { comboBoxSlotRecipe } from "../combobox.recipe";
-import { ComboBoxRootSlot } from "../combobox.slots";
-import { SingleSelectRoot } from "./combobox.single-select-root";
-import { MultiSelectRoot } from "./combobox.multi-select-root";
-import type { ComboBoxRootProps } from "../combobox.types";
+import {
+  useListState,
+  useAsyncList,
+  type Node,
+  type Key,
+  type Collection,
+} from "react-stately";
+import { useId } from "react-aria";
+import { useDebouncedCallback } from "use-debounce";
+import {
+  CollectionBuilder,
+  ComboBoxContext,
+  useContextProps,
+  Provider,
+  InputContext,
+  ButtonContext,
+  GroupContext,
+  TextContext,
+  PopoverContext,
+  LabelContext,
+  ListBoxContext,
+  TagGroupContext,
+  ListStateContext,
+  SelectableCollectionContext,
+  type Selection,
+} from "react-aria-components";
+import { useIntl } from "react-intl";
 import { extractStyleProps } from "@/utils";
+import { ComboBoxRootSlot } from "../combobox.slots";
+import type {
+  ComboBoxRootProps,
+  ComboBoxRootContextValue,
+  ComboBoxAsyncConfig,
+} from "../combobox.types";
+import { messages } from "../combobox.i18n";
+import {
+  defaultGetKey,
+  defaultGetTextValue,
+  defaultGetNewOptionData,
+} from "../utils/collection";
+import {
+  normalizeSelectedKeys,
+  denormalizeSelectedKeys,
+} from "../utils/selection";
+import {
+  ComboBoxRootContext,
+  useComboBoxRootContext,
+} from "./combobox.root-context";
+import { ComboBoxHiddenInput } from "./combobox.hidden-input";
 
 /**
- * # ComboBox
+ * # ComboBox.Root
  *
- * A combo box combines a text input with a dropdown list, allowing users to filter a list of options to items matching a query.
+ * Root component for ComboBox that provides state management and context for all child components.
+ * Handles selection state, input filtering, menu open/close, and custom option creation.
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={items}
+ *   getKey={(item) => item.id}
+ *   getTextValue={(item) => item.name}
+ *   onSelectionChange={(keys) => console.log(keys)}
+ * >
+ *   <ComboBox.Trigger>
+ *     <ComboBox.Input />
+ *   </ComboBox.Trigger>
+ *   <ComboBox.Popover>
+ *     <ComboBox.ListBox>
+ *       {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+ *     </ComboBox.ListBox>
+ *   </ComboBox.Popover>
+ * </ComboBox.Root>
+ * ```
  *
  * @supportsStyleProps
  */
-export const ComboBoxRoot = <T extends object>({
-  children,
-  ref,
-  ...props
-}: ComboBoxRootProps<T>) => {
-  const recipe = useSlotRecipe({ recipe: comboBoxSlotRecipe });
+
+export function ComboBoxRoot<T extends object>(props: ComboBoxRootProps<T>) {
+  // Merge props from React Aria's ComboBoxContext if nested in another ComboBox
+  let ref: RefObject<HTMLDivElement | null>;
+  [props, ref] = useContextProps(props, null, ComboBoxContext);
+
+  const {
+    selectionMode = "single",
+    size = "md",
+    getKey = defaultGetKey,
+    getTextValue = defaultGetTextValue,
+    children,
+    leadingElement,
+    inputValue: inputValueFromProps,
+    onInputChange: onInputChangeFromProps,
+    isLoading: isLoadingFromProps,
+    allowsEmptyMenu: allowsEmptyMenuFromProps,
+    renderEmptyState: renderEmptyStateFromProps,
+    async: asyncConfig,
+    filter,
+    allowsCustomOptions = false,
+    isDisabled = false,
+    isInvalid = false,
+    isRequired = false,
+    isReadOnly = false,
+  } = props;
+
+  // Standard pattern: split recipe variants, then extract style props
+  const recipe = useSlotRecipe({ key: "combobox" });
   const [recipeProps, restRecipeProps] = recipe.splitVariantProps(props);
-  const [styleProps, restProps] = extractStyleProps(restRecipeProps);
-  const Component =
-    "selectionMode" in props && props.selectionMode === "multiple"
-      ? MultiSelectRoot
-      : SingleSelectRoot;
-  // TODO: should there be a prop to allow for user control of the menu width? (based on the figma, I think that allowing control of the input/tag/value/rootslot width is enough, but if not we can pass a prop)
-  // TODO: should there be a prop to allow the user to pass in an icon to display on the right of the input other than the down caret (eg search)?
-  // TODO: this should really have its own context, especially for the collection (a top-level collection context would make the tags and inputs a lot more straightforward to reason about, and would potentially allow us to make this into a single component instead of 2 components in a trenchcoat)
+  const [styleProps, functionalProps] = extractStyleProps(restRecipeProps);
+
+  // Refs shared with children via context
+  // - triggerRef: positions popover relative to trigger element
+  // - inputRef: allows trigger to programmatically focus input
+  const triggerRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  // ============================================================
+  // CUSTOM OPTIONS HANDLING
+  // ============================================================
+  // Track custom-created items (when allowsCustomOptions=true)
+  // Managed in outer component to persist across searches/renders
+  const [customCreatedItems, setCustomCreatedItems] = useState<T[]>([]);
+
+  // ============================================================
+  // ASYNC MODE HANDLING
+  // ============================================================
+  // When `async` prop provided: useAsyncList manages loading, debouncing, and fetching
+  // Users provide load function + optional config (minSearchLength, debounce, onError)
+  const asyncList = useAsyncList<T>({
+    getKey,
+    async load({ signal, filterText }) {
+      if (!asyncConfig) return { items: [] };
+
+      // Check minimum search length
+      const minLength = asyncConfig.minSearchLength ?? 0;
+      if (!filterText || filterText.length < minLength) {
+        return { items: [] };
+      }
+
+      try {
+        const items = await asyncConfig.load(filterText, signal);
+        return { items };
+      } catch (err) {
+        // Ignore abort errors (expected when request is cancelled)
+        if ((err as Error).name === "AbortError") {
+          throw err;
+        }
+        // Call user's error handler if provided
+        const error = err as Error;
+        asyncConfig.onError?.(error);
+        return { items: [] };
+      }
+    },
+  });
+
+  // Async mode state
+  const [asyncInputValue, setAsyncInputValue] = useState(inputValueFromProps); // For immediate UI updates
+  const [asyncPending, setAsyncPending] = useState(false); // Tracks debounce wait period
+  const [asyncSelectedItems, setAsyncSelectedItems] = useState<T[]>([]); // Persist selected items across searches
+
+  // Debounced filter text update (triggers load function after delay)
+  const debounceMs = asyncConfig?.debounce ?? 300;
+  const debouncedSetFilterText = useDebouncedCallback((value: string) => {
+    setAsyncPending(false);
+    asyncList.setFilterText(value); // Triggers load function
+  }, debounceMs);
+
+  // Input change handler for async mode
+  const asyncOnInputChange = useCallback(
+    (value: string) => {
+      setAsyncInputValue(value); // Immediate display update
+      setAsyncPending(true); // Show loading during debounce
+      debouncedSetFilterText(value); // Trigger debounced API call
+    },
+    [debouncedSetFilterText]
+  );
+
+  // ============================================================
+  // PROP ALIASING
+  // ============================================================
+  // Route props to async handlers when async mode is enabled
+
+  const inputValue = asyncConfig ? asyncInputValue : inputValueFromProps;
+  const onInputChange = asyncConfig
+    ? asyncOnInputChange
+    : onInputChangeFromProps;
+
+  // Compute loading state from async list or external prop
+  const isLoading = asyncConfig
+    ? asyncPending ||
+      asyncList.loadingState === "loading" ||
+      asyncList.loadingState === "loadingMore" ||
+      asyncList.loadingState === "filtering"
+    : isLoadingFromProps;
+
+  // Keep menu open when empty for async/custom options (required for creating custom options)
+  const allowsEmptyMenu =
+    asyncConfig || allowsCustomOptions ? true : allowsEmptyMenuFromProps;
+
+  // Default empty state messages
+  const asyncDefaultRenderEmptyState = useCallback(() => {
+    // TODO: verify wording and styling for empty states
+    if (isLoading) {
+      return inputValue?.length
+        ? `loading results for "${inputValue}"`
+        : "loading results";
+    }
+    if (
+      inputValue?.length &&
+      asyncConfig?.minSearchLength &&
+      inputValue.length >= asyncConfig.minSearchLength
+    ) {
+      return `no results for "${inputValue}"`;
+    }
+    if (asyncConfig?.minSearchLength) {
+      return `enter at least ${asyncConfig?.minSearchLength} characters`;
+    }
+    return "type to search";
+  }, [asyncConfig?.minSearchLength, isLoading, inputValue]);
+
+  const customDefaultRenderEmptyState = useCallback(() => {
+    // TODO: verify wording and styling for empty states
+    if (isLoading) {
+      return inputValue?.length
+        ? `loading results for "${inputValue}"`
+        : "loading results";
+    }
+    return `hit "enter" to create an option`;
+  }, [isLoading, inputValue]);
+
+  const defaultRenderEmptyState = allowsCustomOptions
+    ? customDefaultRenderEmptyState
+    : asyncConfig
+      ? asyncDefaultRenderEmptyState
+      : undefined;
+
+  const renderEmptyState = defaultRenderEmptyState ?? renderEmptyStateFromProps;
+
+  // ============================================================
+  // ITEMS MERGING
+  // ============================================================
+  // Merge items from all sources: async/static + custom created + selected (async multi-select)
+  const items = useMemo(() => {
+    const baseItems = asyncConfig ? Array.from(asyncList.items) : props.items;
+    const baseItemsArray = baseItems ? Array.from(baseItems) : [];
+
+    // Deduplicate: add custom items not in base
+    const existingKeys = new Set(baseItemsArray.map((item) => getKey(item)));
+    const customItemsToAdd = customCreatedItems.filter(
+      (item) => !existingKeys.has(getKey(item))
+    );
+    let mergedItems = [...customItemsToAdd, ...baseItemsArray];
+
+    // Async multi-select: add selected items not in current results
+    if (
+      asyncConfig &&
+      selectionMode === "multiple" &&
+      asyncSelectedItems.length > 0
+    ) {
+      const mergedKeys = new Set(mergedItems.map((item) => getKey(item)));
+      const selectedItemsToAdd = asyncSelectedItems.filter(
+        (item) => !mergedKeys.has(getKey(item))
+      );
+      mergedItems = [...selectedItemsToAdd, ...mergedItems];
+    }
+
+    return mergedItems;
+  }, [
+    asyncConfig,
+    asyncList.items,
+    props.items,
+    customCreatedItems,
+    asyncSelectedItems,
+    selectionMode,
+    getKey,
+  ]);
+
+  // Context value: static configuration and refs shared with all children
+  const rootContextValue: ComboBoxRootContextValue<T> = useMemo(
+    () => ({
+      selectionMode,
+      size,
+      getKey,
+      getTextValue,
+      leadingElement,
+      triggerRef,
+      inputRef,
+      isLoading,
+      isDisabled,
+      isRequired,
+      isInvalid,
+      isReadOnly,
+    }),
+    [
+      selectionMode,
+      getKey,
+      getTextValue,
+      leadingElement,
+      triggerRef,
+      inputRef,
+      isDisabled,
+      isRequired,
+      isInvalid,
+      isReadOnly,
+    ]
+  );
+
+  // Transform items to add id and textValue properties using getKey and getTextValue
+  // This ensures CollectionBuilder can determine keys and the filter can work properly
+  const itemsWithMetadata = useMemo(() => {
+    if (!items) return undefined;
+    return Array.from(items).map((item) => {
+      const hasId = "id" in item;
+      const hasTextValue = "textValue" in item;
+
+      // If item already has both properties, don't transform it
+      if (hasId && hasTextValue) return item;
+
+      // Add missing properties using getKey and getTextValue
+      return {
+        ...item,
+        ...(hasId ? {} : { id: getKey(item) }),
+        ...(hasTextValue ? {} : { textValue: getTextValue(item) }),
+      };
+    });
+  }, [items, getKey, getTextValue]);
+
+  // Build content for CollectionBuilder
+  //
+  // CRITICAL: This content is built in the OUTER component (ComboBoxRoot) and memoized.
+  // If built in the inner component, the collection would be rebuilt every time the menu
+  // toggles open/closed, causing:
+  // - Loss of virtual focus state when menu reopens
+  // - Performance issues from re-parsing JSX tree on every toggle
+  // - TagGroup losing track of selected items between renders
+  //
+  // By building here and passing the stable collection down, we ensure:
+  // - Collection persists across menu open/close cycles
+  // - Virtual focus state is maintained
+  // - Selected items in TagGroup remain stable
+  //
+  // React Aria's CollectionBuilder parses this JSX tree into a Collection object
+  // that both ListBox (options menu) and TagGroup (selected tags) can consume.
+  const content = useMemo(
+    () => (
+      <ComboBoxRootContext.Provider
+        value={rootContextValue as ComboBoxRootContextValue<object>}
+      >
+        <ListBoxContext.Provider value={{ items: itemsWithMetadata }}>
+          {typeof children === "function"
+            ? children({
+                isOpen: false,
+                isDisabled,
+                isInvalid,
+                isRequired,
+                defaultChildren: null,
+              } as T & {
+                defaultChildren: null;
+                isOpen: boolean;
+                isDisabled: boolean;
+                isInvalid: boolean;
+                isRequired: boolean;
+              })
+            : children}
+        </ListBoxContext.Provider>
+      </ComboBoxRootContext.Provider>
+    ),
+    [
+      children,
+      isDisabled,
+      isInvalid,
+      isRequired,
+      itemsWithMetadata,
+      rootContextValue,
+    ]
+  );
+
   return (
-    <ComboBoxRootSlot
-      asChild
-      selectionMode={props.selectionMode}
-      {...recipeProps}
-      {...styleProps}
+    <Provider
+      // clear child contexts so that parent wrappers do not affect this component
+      values={[
+        [ButtonContext, {}],
+        [InputContext, {}],
+        [TagGroupContext, {}],
+      ]}
     >
-      <Component ref={ref} size={props.size} {...restProps}>
-        {children}
-      </Component>
-    </ComboBoxRootSlot>
+      <ComboBoxRootContext.Provider
+        value={rootContextValue as ComboBoxRootContextValue<object>}
+      >
+        <ComboBoxRootSlot
+          ref={ref}
+          {...recipeProps}
+          {...styleProps}
+          size={size}
+          data-disabled={isDisabled}
+          data-invalid={isInvalid}
+          data-required={isRequired}
+          data-readonly={isReadOnly}
+          data-open={props.isOpen}
+          role="group"
+        >
+          {/* CollectionBuilder parses 'content' JSX into a Collection object */}
+          <CollectionBuilder content={content}>
+            {(collection) => (
+              // Pass the built collection to ComboBoxRootInner which handles all behavior
+              <ComboBoxRootInner<T>
+                {...functionalProps}
+                size={size}
+                filter={filter}
+                selectionMode={selectionMode}
+                inputValue={inputValue}
+                onInputChange={onInputChange}
+                getKey={getKey}
+                getTextValue={getTextValue}
+                allowsEmptyMenu={allowsEmptyMenu}
+                renderEmptyState={renderEmptyState}
+                isDisabled={isDisabled}
+                isRequired={isRequired}
+                isInvalid={isInvalid}
+                isReadOnly={isReadOnly}
+                collection={collection as unknown as Collection<Node<T>>}
+                allowsCustomOptions={allowsCustomOptions}
+                asyncConfig={asyncConfig}
+                onAsyncSelectedItemsChange={
+                  asyncConfig && selectionMode === "multiple"
+                    ? setAsyncSelectedItems
+                    : undefined
+                }
+                onAddCustomItem={setCustomCreatedItems}
+                onAddAsyncSelectedItem={setAsyncSelectedItems}
+              />
+            )}
+          </CollectionBuilder>
+        </ComboBoxRootSlot>
+      </ComboBoxRootContext.Provider>
+    </Provider>
   );
-};
+}
 
 ComboBoxRoot.displayName = "ComboBox.Root";
+
+type ComboBoxRootInnerProps<T extends object> = ComboBoxRootProps<T> & {
+  collection: Collection<Node<T>>;
+  asyncConfig?: ComboBoxAsyncConfig<T>;
+  onAsyncSelectedItemsChange?: (items: T[]) => void;
+  onAddCustomItem?: React.Dispatch<React.SetStateAction<T[]>>;
+  onAddAsyncSelectedItem?: React.Dispatch<React.SetStateAction<T[]>>;
+};
+
+/**
+ * Inner component that receives the built collection and renders the ComboBox
+ */
+const ComboBoxRootInner = <T extends object>(
+  props: ComboBoxRootInnerProps<T> & {}
+) => {
+  const intl = useIntl();
+  const {
+    selectionMode = "single",
+    items,
+    collection,
+    getKey = defaultGetKey,
+    children,
+    selectedKeys: selectedKeysFromProps = [],
+    onSelectionChange,
+    disabledKeys,
+    inputValue: inputValueFromProps = "",
+    onInputChange,
+    filter,
+    placeholder,
+    menuTrigger = "input",
+    shouldCloseOnBlur = true,
+    shouldCloseOnSelect = true,
+    isOpen: controlledIsOpen,
+    defaultOpen = false,
+    onOpenChange,
+    allowsEmptyMenu = false,
+    renderEmptyState,
+    allowsCustomOptions = false,
+    isValidNewOption,
+    getNewOptionData = defaultGetNewOptionData,
+    onCreateOption,
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledBy,
+    "aria-describedby": ariaDescribedBy,
+    isDisabled = false,
+    isRequired = false,
+    isInvalid = false,
+    isReadOnly = false,
+    shouldFocusWrap = true,
+    autoFocus = false,
+    name,
+    formValue,
+    validationBehavior = "aria",
+    form,
+    validate,
+    isLoading,
+    asyncConfig,
+    onAsyncSelectedItemsChange,
+    onAddCustomItem,
+    onAddAsyncSelectedItem,
+  } = props;
+
+  // ============================================================
+  // REFS & IDS
+  // ============================================================
+
+  // Stable IDs for ARIA relationships
+  const listboxId = useId();
+  const tagGroupId = useId();
+
+  // DOM refs for scroll positioning and focus management
+  const listBoxRef = useRef<HTMLDivElement>(null);
+  const popoverRef = useRef<HTMLDivElement>(null);
+
+  // ============================================================
+  // STATE MANAGEMENT
+  // ============================================================
+  // Controlled/uncontrolled pattern:
+  // - Controlled: Parent manages via props (selectedKeys, inputValue, isOpen)
+  // - Uncontrolled: Component manages with internal state + defaults
+
+  // SELECTION STATE
+  // Selection state (normalized to Set<Key> for consistency)
+  const normalizedSelectedKeysFromProps = useMemo(
+    () => normalizeSelectedKeys(selectedKeysFromProps),
+    [selectedKeysFromProps]
+  );
+
+  const isSelectionControlled = Boolean(onSelectionChange);
+  const [internalNormalizedSelectedKeys, setInternalSelectedKeys] = useState(
+    normalizedSelectedKeysFromProps
+  );
+  const normalizedSelectedKeys = isSelectionControlled
+    ? normalizedSelectedKeysFromProps
+    : internalNormalizedSelectedKeys;
+
+  // INPUT VALUE STATE
+  // Items are managed in outer component (see ITEMS MERGING section above)
+
+  // Input value state (controlled/uncontrolled)
+  const isInputControlled = onInputChange !== undefined;
+
+  const computeInitialInputValue = () => {
+    if (inputValueFromProps) return inputValueFromProps;
+    if (isInputControlled || selectionMode !== "single") return "";
+
+    // Uncontrolled single-select: initialize from selected item text
+    const selectedKeysArray = Array.from(normalizedSelectedKeys);
+    if (selectedKeysArray.length === 0) return "";
+
+    const selectedKey = selectedKeysArray[0];
+    const selectedNode = collection.getItem(selectedKey);
+    return selectedNode?.textValue ?? "";
+  };
+
+  const [internalInputValue, setInternalInputValue] = useState(
+    computeInitialInputValue
+  );
+  const inputValue = isInputControlled
+    ? inputValueFromProps
+    : internalInputValue;
+
+  const prevInputValueRef = useRef(inputValue);
+
+  // Menu open/closed state
+  const [internalIsOpen, setInternalIsOpen] = useState(defaultOpen);
+  const isOpen = controlledIsOpen ?? internalIsOpen;
+
+  // Focus strategy for menu opening (ArrowDown→first, ArrowUp→last)
+  const [focusStrategy, setFocusStrategy] = useState<"first" | "last" | null>(
+    null
+  );
+
+  // Unified setter for open state
+  const setIsOpen = useCallback(
+    (open: boolean) => {
+      if (controlledIsOpen === undefined) {
+        setInternalIsOpen(open);
+      }
+      onOpenChange?.(open);
+    },
+    [controlledIsOpen, onOpenChange]
+  );
+
+  // ============================================================
+  // DERIVED STATE & MEMOIZATION
+  // ============================================================
+
+  // Filtered collection based on input value
+  // Uses Collection.filter() to preserve navigation methods (getFirstKey, getLastKey, etc.)
+  const filteredCollection = useMemo(() => {
+    // No input: show all items
+    if (inputValue.trim() === "") {
+      return collection;
+    }
+
+    // Single-select UX: if input matches selected item exactly, show full list
+    // Enables workflow: select item → click input → see all options (not just the selected one)
+    if (selectionMode === "single") {
+      const selectedKeys = Array.from(normalizedSelectedKeys);
+      if (selectedKeys.length > 0) {
+        const selectedKey = selectedKeys[0];
+        const selectedNode = collection.getItem(selectedKey);
+
+        if (selectedNode?.textValue === inputValue) {
+          return collection;
+        }
+      }
+    }
+
+    // Custom filter: adapt user-provided filter to Collection.filter() API
+    if (filter) {
+      const allNodes = Array.from(collection);
+      const filteredNodes = Array.from(filter(allNodes, inputValue));
+      const filteredKeys = new Set(filteredNodes.map((node) => node.key));
+
+      return (
+        collection.filter?.((_nodeValue, node) => {
+          return filteredKeys.has(node.key);
+        }) ?? collection
+      );
+    }
+
+    // Default: case-insensitive substring match
+    const lowerInput = inputValue.toLowerCase();
+    return (
+      collection.filter?.((nodeValue) => {
+        return nodeValue.toLowerCase().includes(lowerInput);
+      }) ?? collection
+    );
+  }, [collection, inputValue, filter, selectionMode, normalizedSelectedKeys]);
+
+  // Selected items for TagGroup (multi-select only)
+  // Extract actual item objects from keys to pass to TagGroup component
+  const selectedItemsFromState = useMemo(
+    () =>
+      selectionMode === "multiple"
+        ? Array.from(normalizedSelectedKeys)
+            .map((key) => collection.getItem(key)?.value)
+            .filter((item): item is T => item !== undefined)
+        : [],
+    [selectionMode, normalizedSelectedKeys, collection]
+  );
+
+  // Menu width state (set via ResizeObserver effect below)
+  const [triggerWidth, setTriggerWidth] = useState<string | null>(null);
+
+  // ============================================================
+  // EVENT HANDLERS
+  // ============================================================
+
+  // Toggle menu open/closed (uses functional update to avoid stale closures)
+  const toggleOpen = useCallback(() => {
+    const willOpen =
+      controlledIsOpen === undefined ? !isOpen : !controlledIsOpen;
+
+    if (controlledIsOpen === undefined) {
+      setInternalIsOpen((prev) => !prev);
+    } else {
+      onOpenChange?.(!controlledIsOpen);
+    }
+
+    // When opening: focus input and set focus to first item
+    if (willOpen) {
+      inputRef.current?.focus();
+      setFocusStrategy("first");
+    }
+  }, [controlledIsOpen, isOpen, onOpenChange]);
+
+  // Input change handler (opens menu when menuTrigger="input")
+  const handleInputChange = useCallback(
+    (value: string) => {
+      if (!isInputControlled) {
+        setInternalInputValue(value);
+      }
+      onInputChange?.(value);
+
+      // Open menu on input change (when menuTrigger="input")
+      if (menuTrigger === "input" && value !== prevInputValueRef.current) {
+        setIsOpen(true);
+      }
+
+      prevInputValueRef.current = value;
+    },
+    [isInputControlled, onInputChange, menuTrigger, setIsOpen]
+  );
+
+  // Selection change handler
+  // Multi-select: toggle behavior (click to add/remove from selection)
+  // Single-select: replace selection and close menu
+  const handleSelectionChange = useCallback(
+    (keys: Selection, previousKeys?: Set<Key>) => {
+      // Convert "all" to actual Set of keys
+      let actualKeys =
+        keys === "all"
+          ? new Set(Array.from(collection).map((node) => node.key))
+          : keys;
+
+      const comparisonKeys = previousKeys ?? normalizedSelectedKeys;
+
+      // Multi-select toggle: React Aria sends single-key Set on click,
+      // we toggle that key in/out instead of replacing entire selection
+      const isProperSubset =
+        actualKeys.size > 0 &&
+        Array.from(actualKeys).every((key) => comparisonKeys.has(key)) &&
+        actualKeys.size < comparisonKeys.size;
+
+      if (
+        selectionMode === "multiple" &&
+        actualKeys.size === 1 &&
+        !isProperSubset
+      ) {
+        const clickedKey = Array.from(actualKeys)[0];
+        const isAlreadySelected = comparisonKeys.has(clickedKey);
+
+        const newSelection = new Set(comparisonKeys);
+        if (!isAlreadySelected) {
+          newSelection.add(clickedKey);
+        } else {
+          newSelection.delete(clickedKey);
+        }
+        actualKeys = newSelection;
+      }
+
+      // Convert Set<Key> back to array for callback
+      const denormalized = denormalizeSelectedKeys(actualKeys);
+
+      if (onSelectionChange) {
+        onSelectionChange(denormalized);
+      } else {
+        setInternalSelectedKeys(actualKeys);
+      }
+
+      // Async multi-select: cache selected items to persist across searches
+      if (
+        asyncConfig &&
+        selectionMode === "multiple" &&
+        onAsyncSelectedItemsChange
+      ) {
+        const selectedItems = Array.from(actualKeys)
+          .map((key) => collection.getItem(key)?.value)
+          .filter((item): item is T => item !== undefined);
+        onAsyncSelectedItemsChange(selectedItems);
+      }
+
+      // Single-select: sync input value with selection and close menu
+      if (selectionMode === "single") {
+        const selectedKey = Array.from(actualKeys)[0];
+
+        if (selectedKey !== null) {
+          const selectedNode = collection.getItem(selectedKey);
+          const textValue = selectedNode?.textValue ?? "";
+
+          // Update input value
+          if (!isInputControlled) {
+            setInternalInputValue(textValue);
+            prevInputValueRef.current = textValue;
+          }
+          onInputChange?.(textValue);
+        }
+
+        // Close menu if shouldCloseOnSelect=true
+        if (shouldCloseOnSelect) {
+          setIsOpen(false);
+        }
+      }
+    },
+    [
+      collection,
+      selectionMode,
+      normalizedSelectedKeys,
+      onSelectionChange,
+      onInputChange,
+      shouldCloseOnSelect,
+      setIsOpen,
+      isInputControlled,
+    ]
+  );
+
+  // React Aria's useListState provides keyboard navigation and selection management
+  const state = useListState<T>({
+    selectionMode,
+    collection: filteredCollection,
+    selectedKeys: normalizedSelectedKeys,
+    onSelectionChange: handleSelectionChange,
+    disabledKeys,
+  });
+
+  // Clear all selections (and input value in single-select)
+  const clearSelection = useCallback(() => {
+    state.selectionManager.setSelectedKeys(new Set());
+
+    if (selectionMode === "single") {
+      if (!isInputControlled) {
+        setInternalInputValue("");
+        prevInputValueRef.current = "";
+      }
+      onInputChange?.("");
+    }
+  }, [state.selectionManager, selectionMode, isInputControlled, onInputChange]);
+
+  // Handle custom option creation (adds item and selects it)
+  const handleCustomOptionCreated = useCallback(
+    (newItem: T) => {
+      // Add to custom items in outer component
+      onAddCustomItem?.((prev) => [...prev, newItem]);
+
+      // Also cache in async multi-select mode
+      if (asyncConfig && selectionMode === "multiple") {
+        onAddAsyncSelectedItem?.((prev) => [...prev, newItem]);
+      }
+
+      // Select the new item
+      const newKey = getKey(newItem);
+      const currentKeys = normalizedSelectedKeys;
+
+      if (selectionMode === "single") {
+        handleSelectionChange(new Set([newKey]), currentKeys);
+      } else {
+        const newSelection = new Set(currentKeys);
+        newSelection.add(newKey);
+        handleSelectionChange(newSelection, currentKeys);
+      }
+    },
+    [
+      onAddCustomItem,
+      asyncConfig,
+      selectionMode,
+      onAddAsyncSelectedItem,
+      getKey,
+      normalizedSelectedKeys,
+      handleSelectionChange,
+    ]
+  );
+
+  // Handle creating a new custom option from input value
+  // Called when user presses Enter with no focused item (allowsCustomOptions=true)
+  // Returns true if option was created successfully
+  const handleCreateOption = useCallback((): boolean => {
+    // Early exit: custom options disabled
+    if (!allowsCustomOptions) return false;
+
+    const trimmedInput = inputValue.trim();
+    // Early exit: empty input
+    if (!trimmedInput) return false;
+
+    // Check if option already exists in the UNFILTERED collection (not state.collection which is filtered)
+    // This prevents duplicates even when the current filter hides the existing option
+    const matchesExisting = Array.from(collection).some(
+      (node) => node.textValue?.toLowerCase() === trimmedInput.toLowerCase()
+    );
+    if (matchesExisting) {
+      return false;
+    }
+
+    // Check custom validation if provided
+    if (isValidNewOption && !isValidNewOption(trimmedInput)) {
+      return false;
+    }
+
+    // Create the new item using user-provided factory function
+    const newItem = getNewOptionData(trimmedInput);
+
+    // Notify outer component to add to custom items and handle selection internally
+    handleCustomOptionCreated(newItem);
+
+    // Clear input for multi-select, set to created text for single-select
+    // Note: Selection happens in handleCustomOptionCreated
+    if (selectionMode === "multiple") {
+      // Multi-select: clear input after creating option
+      if (!isInputControlled) {
+        setInternalInputValue("");
+        prevInputValueRef.current = "";
+      }
+      onInputChange?.("");
+    } else {
+      // Single-select: explicitly set input to the created option's text
+      // We must set it here because handleSelectionChange cannot find the item
+      // in the collection yet (the state update hasn't triggered a re-render,
+      // so the collection hasn't been rebuilt to include the new item)
+      if (!isInputControlled) {
+        setInternalInputValue(trimmedInput);
+        prevInputValueRef.current = trimmedInput;
+      }
+      onInputChange?.(trimmedInput);
+    }
+
+    // Notify parent component
+    onCreateOption?.(newItem);
+
+    return true;
+  }, [
+    allowsCustomOptions,
+    getNewOptionData,
+    isValidNewOption,
+    inputValue,
+    collection,
+    selectionMode,
+    onInputChange,
+    onCreateOption,
+    handleCustomOptionCreated,
+    isInputControlled,
+    setInternalInputValue,
+    prevInputValueRef,
+  ]);
+
+  // Remove keys (for tag removal in multi-select)
+  const removeKey = useCallback(
+    (keysToRemove: Set<Key>) => {
+      if (isDisabled || isReadOnly) return;
+
+      const currentKeys = normalizedSelectedKeys;
+      const newKeys = new Set(currentKeys);
+      keysToRemove.forEach((key) => newKeys.delete(key));
+
+      // Pass currentKeys so handleSelectionChange detects this as removal
+      handleSelectionChange(newKeys, currentKeys);
+
+      // Focus input if all tags removed
+      if (newKeys.size === 0) {
+        inputRef.current?.focus();
+      }
+    },
+    [normalizedSelectedKeys, handleSelectionChange, isDisabled, isReadOnly]
+  );
+
+  // ============================================================
+  // KEYBOARD NAVIGATION
+  // ============================================================
+  // Implements ARIA combobox keyboard interaction pattern
+  // https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+
+  // Handle all keyboard interactions in the input field
+  const handleInputKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLInputElement>) => {
+      switch (e.key) {
+        case "ArrowDown":
+          e.preventDefault();
+          if (!isOpen) {
+            // Menu closed: open and focus first item
+            setIsOpen(true);
+            setFocusStrategy("first");
+          } else {
+            // Menu open: move focus to next item (or first if nothing focused)
+            const currentKey = state.selectionManager.focusedKey;
+            const nextKey = currentKey
+              ? state.collection.getKeyAfter(currentKey)
+              : state.collection.getFirstKey();
+            state.selectionManager.setFocusedKey(
+              nextKey ?? state.collection.getFirstKey()
+            );
+          }
+          break;
+
+        case "ArrowUp":
+          e.preventDefault();
+          if (!isOpen) {
+            // Menu closed: open and focus last item
+            setIsOpen(true);
+            setFocusStrategy("last");
+          } else {
+            // Menu open: move focus to previous item (or last if nothing focused)
+            const currentKey = state.selectionManager.focusedKey;
+            const prevKey = currentKey
+              ? state.collection.getKeyBefore(currentKey)
+              : state.collection.getLastKey();
+            state.selectionManager.setFocusedKey(
+              prevKey ?? state.collection.getLastKey()
+            );
+          }
+          break;
+
+        case "Enter":
+          // Three cases: focused item selection, custom option creation, or form submission
+          if (isOpen && state.selectionManager.focusedKey) {
+            // Case 1: Item is focused - select it
+            e.preventDefault();
+            const focusedKey = state.selectionManager.focusedKey;
+
+            if (selectionMode === "multiple") {
+              // Multi-select: toggle focused item in/out of selection
+              const newSelection = new Set(normalizedSelectedKeys);
+              if (newSelection.has(focusedKey)) {
+                newSelection.delete(focusedKey);
+              } else {
+                newSelection.add(focusedKey);
+              }
+              handleSelectionChange(newSelection);
+              // Keep focus on the same item for further toggling
+            } else {
+              // Single-select: replace selection and clear focus
+              handleSelectionChange(new Set([focusedKey]));
+              state.selectionManager.setFocusedKey(null);
+            }
+          } else if (
+            isOpen &&
+            !state.selectionManager.focusedKey &&
+            allowsCustomOptions
+          ) {
+            // Case 2: No focused item but custom options enabled - create new option
+            const wasCreated = handleCreateOption();
+            if (wasCreated) {
+              e.preventDefault(); // Only prevent default if option was created
+            }
+          }
+          // Case 3: No focused key and no option created - allow form submission (don't preventDefault)
+          break;
+
+        case "Escape":
+          if (isOpen) {
+            // Close menu and clear focus
+            e.preventDefault();
+            setIsOpen(false);
+            state.selectionManager.setFocusedKey(null);
+            // TODO: Revert to last selected value in single-select mode
+          }
+          break;
+
+        case "Home":
+          if (isOpen) {
+            // Jump to first item in list
+            e.preventDefault();
+            const firstKey = state.collection.getFirstKey();
+            state.selectionManager.setFocusedKey(firstKey);
+          }
+          break;
+
+        case "End":
+          if (isOpen) {
+            // Jump to last item in list
+            e.preventDefault();
+            const lastKey = state.collection.getLastKey();
+            state.selectionManager.setFocusedKey(lastKey);
+          }
+          break;
+
+        case "Backspace":
+          // When input is empty, backspace acts as a "delete selection" shortcut
+          if (inputValue === "") {
+            const selectedKeys = Array.from(normalizedSelectedKeys);
+            if (selectedKeys.length > 0) {
+              e.preventDefault();
+              if (selectionMode === "single") {
+                // Single-select: clear the selection
+                handleSelectionChange(new Set());
+              } else {
+                // Multi-select: remove the last selected item
+                const newKeys = new Set(selectedKeys);
+                newKeys.delete(selectedKeys[selectedKeys.length - 1]);
+                handleSelectionChange(newKeys);
+              }
+            }
+          }
+          break;
+
+        default:
+          // Regular typing - handled by onChange
+          break;
+      }
+    },
+    [
+      isOpen,
+      state.selectionManager,
+      state.collection,
+      handleSelectionChange,
+      setIsOpen,
+      setFocusStrategy,
+      selectionMode,
+      inputValue,
+      normalizedSelectedKeys,
+      allowsCustomOptions,
+      handleCreateOption,
+    ]
+  );
+
+  // ============================================================
+  // FOCUS HANDLERS
+  // ============================================================
+
+  // Open menu on focus (when menuTrigger="focus")
+  // In single select mode with existing value, select all text so cursor goes to beginning
+  // and next keypress replaces the value
+  const handleFocus = useCallback(() => {
+    if (menuTrigger === "focus" && !isDisabled && !isReadOnly) {
+      setIsOpen(true);
+    }
+
+    // Single-select with existing value: select all text
+    // This places cursor at beginning and makes next input replace the value
+    if (selectionMode === "single" && inputValue && inputRef.current) {
+      inputRef.current.select();
+    }
+  }, [
+    menuTrigger,
+    isDisabled,
+    isReadOnly,
+    setIsOpen,
+    selectionMode,
+    inputValue,
+  ]);
+
+  // Close menu on blur (with delay to allow option clicks)
+  const handleBlur = useCallback(
+    (e: React.FocusEvent) => {
+      if (!shouldCloseOnBlur) return;
+
+      // Capture currentTarget (React reuses event objects)
+      const comboboxRoot = e.currentTarget;
+
+      // Delay closing to allow option clicks to fire first
+      setTimeout(() => {
+        const currentFocus = document.activeElement;
+        if (!comboboxRoot.contains(currentFocus)) {
+          setIsOpen(false);
+        }
+      }, 150);
+    },
+    [shouldCloseOnBlur, setIsOpen]
+  );
+
+  // ============================================================
+  // EFFECTS
+  // ============================================================
+
+  const lastSelectedKeyRef = useRef<Key | null>(null);
+
+  // Auto-focus input on mount (when autoFocus=true)
+  useEffect(() => {
+    if (autoFocus && inputRef.current && !isDisabled) {
+      inputRef.current.focus();
+    }
+  }, [autoFocus, isDisabled]);
+
+  // Notify parent of open state changes (uncontrolled mode)
+  const prevIsOpenRef = useRef(isOpen);
+  useEffect(() => {
+    if (controlledIsOpen === undefined && prevIsOpenRef.current !== isOpen) {
+      prevIsOpenRef.current = isOpen;
+      onOpenChange?.(isOpen);
+    }
+  }, [isOpen, controlledIsOpen, onOpenChange]);
+
+  // Sync input value with selected item (single-select only)
+  useEffect(() => {
+    if (selectionMode !== "single") return;
+
+    const selectedKeys = Array.from(state.selectionManager.selectedKeys);
+    const currentSelectedKey = selectedKeys.length > 0 ? selectedKeys[0] : null;
+
+    // Only update if selection changed
+    if (currentSelectedKey === lastSelectedKeyRef.current) return;
+    lastSelectedKeyRef.current = currentSelectedKey;
+
+    const selectedNode =
+      currentSelectedKey !== null
+        ? state.collection.getItem(currentSelectedKey)
+        : null;
+
+    // If the selected item is not in the collection yet, it might be a newly created custom option
+    // In that case, keep the current input value instead of clearing it
+    if (currentSelectedKey !== null && !selectedNode) {
+      // Item not in collection yet (likely a just-created custom option)
+      // Don't overwrite the input value - it was already set correctly in handleCreateOption
+      return;
+    }
+
+    const itemText = selectedNode?.textValue ?? "";
+
+    // Update input value (respecting controlled/uncontrolled pattern)
+    if (!isInputControlled) {
+      // Uncontrolled: update internal state directly
+      setInternalInputValue(itemText);
+      prevInputValueRef.current = itemText;
+    } else {
+      // Controlled: notify parent via callback
+      onInputChange?.(itemText);
+    }
+  }, [
+    selectionMode,
+    state.selectionManager.selectedKeys,
+    state.collection,
+    isInputControlled,
+    onInputChange,
+  ]);
+
+  // Effect: Apply focus strategy when menu opens
+  // Focus strategy determines whether to focus first or last item
+  // Set by ArrowDown (first) vs ArrowUp (last) keyboard shortcuts
+  useEffect(() => {
+    if (isOpen && focusStrategy) {
+      const key =
+        focusStrategy === "first"
+          ? state.collection.getFirstKey()
+          : state.collection.getLastKey();
+
+      state.selectionManager.setFocusedKey(key ?? null);
+      setFocusStrategy(null); // Reset strategy after applying
+    }
+  }, [isOpen, focusStrategy, state.collection, state.selectionManager]);
+
+  // Effect: Manage React Aria's focus mode when menu opens/closes
+  // Focus mode enables virtual focus (aria-activedescendant) for keyboard navigation
+  useEffect(() => {
+    if (isOpen) {
+      // Enable focus mode for virtual focus to work
+      state.selectionManager.setFocused(true);
+    } else {
+      // Disable focus mode and clear focused key
+      state.selectionManager.setFocused(false);
+      state.selectionManager.setFocusedKey(null);
+    }
+  }, [isOpen, state.selectionManager]);
+
+  // Track if collection has been populated at least once
+  // Prevents closing menu before initial collection build completes
+  const collectionPopulatedRef = useRef(false);
+  if (state.collection.size > 0) {
+    collectionPopulatedRef.current = true;
+  }
+
+  // Effect: Auto-close menu when no items match filter
+  // Replicates React Aria's useComboBoxState behavior
+  useEffect(() => {
+    // Only close if menu is currently open and allowsEmptyMenu is false
+    if (!isOpen || allowsEmptyMenu) return;
+
+    // Don't close if currently loading async data
+    if (isLoading) return;
+
+    // Only check for empty collection if it has been populated before
+    // This prevents closing the menu before CollectionBuilder finishes parsing children
+    if (!collectionPopulatedRef.current) return;
+
+    // Check if the collection has any items
+    const hasItems = state.collection.size > 0;
+
+    // Close menu if no items match the filter
+    if (!hasItems) {
+      setIsOpen(false);
+    }
+  }, [
+    isOpen,
+    allowsEmptyMenu,
+    isLoading,
+    state.collection.size,
+    setIsOpen,
+    inputValue,
+  ]);
+
+  // Effect: Sync menu width with trigger width using ResizeObserver
+  // Ensures menu stays aligned and properly sized when trigger resizes
+  const { triggerRef, inputRef } = useComboBoxRootContext();
+  useEffect(() => {
+    const triggerElement = triggerRef.current;
+    if (!triggerElement) return;
+
+    // Measure and update trigger width
+    const updateTriggerWidth = () => {
+      const width = triggerElement.offsetWidth;
+      setTriggerWidth(`${width}px`);
+    };
+
+    // Set initial width
+    updateTriggerWidth();
+
+    // Watch for resize events
+    const resizeObserver = new ResizeObserver(updateTriggerWidth);
+    resizeObserver.observe(triggerElement);
+
+    return () => {
+      resizeObserver.disconnect();
+    };
+  }, []);
+
+  // ============================================================
+  // CONTEXT PROVIDERS
+  // ============================================================
+  // React Aria's Provider component distributes props to child components via context
+  // Each context value configures a specific part of the ComboBox (Input, ListBox, Popover, etc.)
+
+  const contextValues = [
+    // InputContext: Props for ComboBox.Input component
+    // Configures the input field with ARIA attributes, event handlers, and validation
+    [
+      InputContext,
+      {
+        ref: inputRef,
+        role: "combobox" as const, // ARIA role for autocomplete input
+        "aria-autocomplete": "list" as const, // Indicates suggestions are in a list
+        "aria-controls":
+          selectionMode === "multiple"
+            ? `${tagGroupId} ${listboxId}` // Multi-select: controls both tags and listbox
+            : listboxId, // Single-select: controls only listbox
+        "aria-expanded": isOpen, // Announces menu open/closed state
+        "aria-activedescendant": state.selectionManager.focusedKey
+          ? `${listboxId}-option-${state.selectionManager.focusedKey}` // Virtual focus: announces focused option
+          : undefined,
+        "aria-describedby":
+          selectionMode === "multiple"
+            ? `${tagGroupId} ${ariaDescribedBy ?? ""}` // Multi-select: references tag group for context
+            : ariaDescribedBy,
+        "aria-label": ariaLabel,
+        "aria-labelledby": ariaLabelledBy,
+        value: inputValue,
+        onChange: (e: React.ChangeEvent<HTMLInputElement>) =>
+          handleInputChange(e.target.value),
+        onKeyDown: handleInputKeyDown,
+        onFocus: handleFocus,
+        onBlur: handleBlur,
+        disabled: isDisabled,
+        readOnly: isReadOnly,
+        required: isRequired,
+        "aria-invalid": isInvalid,
+        placeholder,
+        name,
+        form,
+        validationbehavior: validationBehavior,
+        validate,
+      },
+    ],
+
+    // TagGroupContext: Props for ComboBox.TagGroup component (multi-select only)
+    // Renders selected items as removable tags
+    [
+      TagGroupContext,
+      {
+        id: tagGroupId,
+        "aria-label": intl.formatMessage(messages.selectedValues),
+        items: selectedItemsFromState, // Selected items to display as tags
+        onRemove: removeKey, // Handle tag removal
+      },
+    ],
+
+    // ButtonContext: Props for toggle and clear buttons
+    // Uses "slots" pattern to configure multiple buttons via single context
+    [
+      ButtonContext,
+      {
+        slots: {
+          toggle: {
+            onPress: toggleOpen,
+            "aria-label": intl.formatMessage(messages.toggleOptions),
+            isDisabled: isDisabled || isReadOnly,
+            isPressed: isOpen, // Visual indicator that menu is open
+          },
+          clear: {
+            onPress: clearSelection,
+            "aria-label": intl.formatMessage(messages.clearSelection),
+            style:
+              normalizedSelectedKeys.size > 0 ? undefined : { display: "none" },
+            isDisabled:
+              isDisabled ||
+              isReadOnly ||
+              state.selectionManager.selectedKeys.size === 0, // Disabled when nothing selected
+          },
+        },
+      },
+    ],
+
+    // PopoverContext: Props for ComboBox.Popover component
+    // Controls menu positioning, portal rendering, and open/close behavior
+    [
+      PopoverContext,
+      {
+        isOpen: isOpen,
+        // No-op onOpenChange: We control state internally, prevent React Aria from managing its own state
+        onOpenChange: () => {
+          // Intentionally empty - we manage open state via toggleOpen/setIsOpen
+        },
+        ref: popoverRef,
+        triggerRef: triggerRef, // Popover positions relative to this element
+        scrollRef: listBoxRef, // Enables scroll-into-view for keyboard navigation
+        isNonModal: true, // Non-modal: doesn't trap focus, allows interaction outside
+        trigger: "ComboBox", // Identifies this as a combobox popover (not tooltip, dialog, etc.)
+        placement: "bottom start", // Default placement below trigger, aligned to start
+        style: {
+          "--nimbus-combobox-trigger-width": triggerWidth,
+        } as React.CSSProperties, // CSS custom property for menu width
+        clearContexts: [
+          // Clear these contexts so popover content doesn't inherit combobox contexts
+          LabelContext,
+          ButtonContext,
+          InputContext,
+          GroupContext,
+          TextContext,
+        ],
+      },
+    ],
+
+    // SelectableCollectionContext: Enables virtual focus for keyboard navigation
+    // Virtual focus uses aria-activedescendant instead of moving browser focus
+    [SelectableCollectionContext, { shouldUseVirtualFocus: true }],
+
+    // ListBoxContext: Props for ComboBox.ListBox component
+    // Configures the option list with items, ARIA attributes, and behaviors
+    [
+      ListBoxContext,
+      {
+        items, // Items to render (merged from outer component)
+        id: listboxId, // ID referenced by aria-controls on input
+        ref: listBoxRef, // Ref for scroll positioning
+        renderEmptyState, // Custom empty state renderer
+        shouldFocusWrap, // Whether to wrap focus from last to first item
+        "aria-label": intl.formatMessage(messages.options),
+      },
+    ],
+
+    // ListStateContext: React Aria's collection state for managing selection and focus
+    [ListStateContext, state],
+  ];
+
+  // ============================================================
+  // RENDER
+  // ============================================================
+  // Wrap children in React Aria's Provider to distribute context values
+  // Provider passes each context to matching child components (Input, ListBox, Popover, etc.)
+
+  return (
+    <Provider
+      // TypeScript cannot properly infer the complex heterogeneous tuple type required by Provider.
+      // The runtime behavior is correct - each context receives its properly typed value.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      values={contextValues as any}
+    >
+      {/* Hidden input for form submission */}
+      {/* Serializes selection state as form data when ComboBox is inside a <form> */}
+      <ComboBoxHiddenInput
+        name={name}
+        form={form}
+        selectedKeys={normalizedSelectedKeys}
+        selectionMode={selectionMode}
+        formValue={formValue}
+        allowsCustomOptions={allowsCustomOptions}
+        collection={state.collection}
+        inputValue={inputValue}
+      />
+      {/* Render children (ComboBox.Input, ComboBox.ListBox, etc.) */}
+      {/* Type assertion needed - CollectionChildren<T> is assignable to ReactNode at runtime */}
+      {children as React.ReactNode}
+    </Provider>
+  );
+};
diff --git a/packages/nimbus/src/components/combobox/components/combobox.section.tsx b/packages/nimbus/src/components/combobox/components/combobox.section.tsx
new file mode 100644
index 000000000..cb9d97f92
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/components/combobox.section.tsx
@@ -0,0 +1,73 @@
+import { type RefAttributes, type ReactNode } from "react";
+import {
+  ListBoxSection as RaListBoxSection,
+  Header as RaHeader,
+  Collection,
+} from "react-aria-components";
+import { ComboBoxSectionSlot } from "../combobox.slots";
+import type { ComboBoxSectionProps } from "../combobox.types";
+
+/**
+ * # ComboBox.Section
+ *
+ * Section grouping for options with optional label header.
+ * Wraps React Aria's ListBoxSection component.
+ * Supports both static children and collection rendering with items.
+ *
+ * @example Static children
+ * ```tsx
+ * <ComboBox.ListBox>
+ *   <ComboBox.Section label="Fruits">
+ *     <ComboBox.Option id="apple">Apple</ComboBox.Option>
+ *     <ComboBox.Option id="banana">Banana</ComboBox.Option>
+ *   </ComboBox.Section>
+ * </ComboBox.ListBox>
+ * ```
+ *
+ * @example Collection rendering
+ * ```tsx
+ * <ComboBox.Section label="Fruits" items={fruits}>
+ *   {(item) => <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>}
+ * </ComboBox.Section>
+ * ```
+ *
+ * @supportsStyleProps
+ */
+export function ComboBoxSection<T extends object>({
+  children,
+  label,
+  items,
+  ref,
+  ...props
+}: ComboBoxSectionProps<T> & RefAttributes<HTMLDivElement>) {
+  // Validate that children is a function when items is provided
+  if (items && typeof children !== "function") {
+    throw new Error(
+      'ComboBox.Section: When "items" is provided, "children" must be a function'
+    );
+  }
+
+  return (
+    <RaListBoxSection ref={ref} {...props}>
+      {label && (
+        <ComboBoxSectionSlot asChild>
+          <RaHeader>{label}</RaHeader>
+        </ComboBoxSectionSlot>
+      )}
+      {items ? (
+        <Collection items={items}>
+          {(item: T) => {
+            if (typeof children === "function") {
+              return children(item);
+            }
+            return null;
+          }}
+        </Collection>
+      ) : (
+        (children as ReactNode)
+      )}
+    </RaListBoxSection>
+  );
+}
+
+ComboBoxSection.displayName = "ComboBox.Section";
diff --git a/packages/nimbus/src/components/combobox/components/combobox.single-select-button-group.tsx b/packages/nimbus/src/components/combobox/components/combobox.single-select-button-group.tsx
deleted file mode 100644
index 5206d5c5f..000000000
--- a/packages/nimbus/src/components/combobox/components/combobox.single-select-button-group.tsx
+++ /dev/null
@@ -1,72 +0,0 @@
-import { useContext } from "react";
-import { useIntl } from "react-intl";
-import {
-  Close as CloseIcon,
-  KeyboardArrowDown as KeyboardArrowDownIcon,
-  Loop as SpinnerIcon,
-} from "@commercetools/nimbus-icons";
-import { IconButton, Flex, Box } from "@/components";
-import { ComboBoxStateContext } from "react-aria-components";
-import { ComboBoxButtonGroupSlot } from "../combobox.slots";
-import { type ComboBoxButtonGroupProps } from "../combobox.types";
-import { messages } from "../combobox.i18n";
-
-/**
- * Internal button group for single-select ComboBox (clear and toggle buttons)
- *
- * @supportsStyleProps
- */
-export const ComboBoxSingleSelectButtonGroup = ({
-  isDisabled,
-  isReadOnly,
-  isLoading,
-}: ComboBoxButtonGroupProps) => {
-  const intl = useIntl();
-  const state = useContext(ComboBoxStateContext);
-  return (
-    <ComboBoxButtonGroupSlot>
-      {state?.selectedKey && (
-        <IconButton
-          pointerEvents="all"
-          slot={null}
-          size="2xs"
-          variant="ghost"
-          colorPalette="primary"
-          aria-label={intl.formatMessage(messages.clearSelection)}
-          isDisabled={isDisabled || isReadOnly}
-          _expanded={{ bg: "transparent" }}
-          onPress={() => state?.setSelectedKey(null)}
-          my="auto"
-        >
-          <CloseIcon />
-        </IconButton>
-      )}
-      {isLoading ? (
-        <Flex my="auto" w="600" h="600">
-          <Box color="neutral.11" asChild m="auto" w="400" h="400">
-            <Box
-              asChild
-              animation="spin"
-              animationDuration="slowest"
-              data-testid="nimbus-combobox-loading"
-            >
-              <SpinnerIcon />
-            </Box>
-          </Box>
-        </Flex>
-      ) : (
-        <IconButton
-          size="2xs"
-          variant="ghost"
-          aria-label={intl.formatMessage(messages.toggleCombobox)}
-          colorPalette="neutral"
-          my="auto"
-          isDisabled={isDisabled || isReadOnly}
-          _expanded={{ bg: "transparent" }}
-        >
-          <KeyboardArrowDownIcon />
-        </IconButton>
-      )}
-    </ComboBoxButtonGroupSlot>
-  );
-};
diff --git a/packages/nimbus/src/components/combobox/components/combobox.single-select-input.tsx b/packages/nimbus/src/components/combobox/components/combobox.single-select-input.tsx
deleted file mode 100644
index fbc295773..000000000
--- a/packages/nimbus/src/components/combobox/components/combobox.single-select-input.tsx
+++ /dev/null
@@ -1,96 +0,0 @@
-import { type KeyboardEvent, useContext, useCallback } from "react";
-import {
-  Input as RaInput,
-  ComboBoxStateContext,
-  InputContext,
-  useContextProps,
-} from "react-aria-components";
-import type { SingleSelectInputProps } from "../combobox.types";
-import { ComboBoxValueSlot } from "../combobox.slots";
-
-/**
- * Internal single-select input component for ComboBox
- *
- * @supportsStyleProps
- */
-export const SingleSelectInput = (props: SingleSelectInputProps) => {
-  const {
-    placeholder,
-    inputValue,
-    allowsCustomValue,
-    onSubmitCustomValue,
-    onInputChange,
-    ref,
-  } = props;
-
-  // Get input props from ComboBox InputContext and merge with local props
-  const [inputProps, inputRef] = useContextProps({}, ref || null, InputContext);
-  // This component exists because it has to be a child of the root to get the combobox state
-  const state = useContext(ComboBoxStateContext);
-
-  const handleInputKeyDown = useCallback(
-    // This method clears the input if the user has focused on a pre-populated combobox and starts typing
-    (e: KeyboardEvent) => {
-      if (
-        state?.selectedKey &&
-        inputRef.current &&
-        // cursor is at the beginning of input...
-        inputRef.current.selectionStart === 0 &&
-        inputRef.current.selectionEnd === 0 &&
-        // ...and it has a value, which can only happen on focus
-        inputRef.current.value.length > 0 &&
-        e.key.length === 1 && // Single character key
-        !e.ctrlKey &&
-        !e.metaKey &&
-        !e.altKey
-      ) {
-        e.preventDefault();
-        e.stopPropagation();
-        // Set the input value to the typed key (which clears the previous value)
-        state.setInputValue(e.key);
-        return;
-      }
-      // This method checks the inputValue against the textValue of every item in the collection, and if it doesnt match any items, sets a custom value
-      if (
-        e.key === "Enter" &&
-        inputValue &&
-        inputValue?.trim() !== "" &&
-        onInputChange &&
-        allowsCustomValue &&
-        onSubmitCustomValue &&
-        state
-      ) {
-        // Check if the inputValue matches any textValue in the collection
-        if (state.collection) {
-          const collectionItems = Array.from(state.collection);
-          const matchingItem = collectionItems.find((item) => {
-            return item.textValue.toLowerCase() === inputValue.toLowerCase();
-          });
-
-          if (matchingItem) {
-            // If input value matches an existing item, select that item
-            state.setSelectedKey(matchingItem.key);
-          } else {
-            // Only submit custom value if it doesn't already exist
-            onSubmitCustomValue(inputValue);
-          }
-        } else {
-          // Fallback: if no collection available, submit the custom value
-          onSubmitCustomValue(inputValue);
-        }
-      }
-    },
-    [inputValue, onInputChange, allowsCustomValue, onSubmitCustomValue, state]
-  );
-
-  return (
-    <ComboBoxValueSlot asChild>
-      <RaInput
-        ref={inputRef}
-        {...inputProps}
-        onKeyDown={handleInputKeyDown}
-        placeholder={placeholder}
-      />
-    </ComboBoxValueSlot>
-  );
-};
diff --git a/packages/nimbus/src/components/combobox/components/combobox.single-select-root.tsx b/packages/nimbus/src/components/combobox/components/combobox.single-select-root.tsx
deleted file mode 100644
index 0160def3e..000000000
--- a/packages/nimbus/src/components/combobox/components/combobox.single-select-root.tsx
+++ /dev/null
@@ -1,79 +0,0 @@
-import { useCallback, useRef } from "react";
-import {
-  ComboBox as RaComboBox,
-  Popover as RaPopover,
-} from "react-aria-components";
-import { SingleSelectInput } from "./combobox.single-select-input";
-import { ComboBoxOptions } from "./combobox.options";
-import { ComboBoxSingleSelectButtonGroup } from "./combobox.single-select-button-group";
-import type { ComboBoxSingleSelectRootProps } from "../combobox.types";
-import { ComboBoxLeadingElement } from "./combobox.leading-element";
-
-/**
- * Internal single-select root implementation for ComboBox
- *
- * @supportsStyleProps
- */
-export const SingleSelectRoot = <T extends object>({
-  children,
-  inputValue,
-  onInputChange,
-  placeholder,
-  allowsCustomValue,
-  onSubmitCustomValue,
-  renderEmptyState,
-  shouldFocusWrap = true,
-  isLoading,
-  leadingElement,
-  ref,
-  ...rest
-}: ComboBoxSingleSelectRootProps<T>) => {
-  if (onSubmitCustomValue && (inputValue === undefined || !onInputChange)) {
-    // ComboBox has to be controlled to be able to get the input value when user presses enter
-    throw new Error(
-      'ComboBox: When "onSubmitCustomValue" is provided, "inputValue" must be controlled with "onInputChange"'
-    );
-  }
-  const inputRef = useRef<HTMLInputElement>(null);
-  const handleFocus = useCallback(() => {
-    // If the input has a value on focus, put the cursor to the beginning of the input so that it can be cleared if the user enters text
-    if (inputRef.current && inputRef.current.value) {
-      // Chrome will force the cursor to the end if we don't wait for the rendering frame to complete
-      requestAnimationFrame(() => inputRef.current?.setSelectionRange(0, 0));
-    }
-  }, [inputRef]);
-  return (
-    <RaComboBox
-      inputValue={inputValue}
-      onInputChange={onInputChange}
-      onFocus={handleFocus}
-      allowsCustomValue={allowsCustomValue}
-      menuTrigger="focus"
-      shouldFocusWrap={shouldFocusWrap}
-      {...rest}
-      ref={ref}
-    >
-      {leadingElement && (
-        <ComboBoxLeadingElement>{leadingElement}</ComboBoxLeadingElement>
-      )}
-      <SingleSelectInput
-        ref={inputRef}
-        placeholder={placeholder}
-        inputValue={inputValue}
-        allowsCustomValue={allowsCustomValue}
-        onSubmitCustomValue={onSubmitCustomValue}
-        onInputChange={onInputChange}
-      />
-      <ComboBoxSingleSelectButtonGroup
-        isLoading={isLoading}
-        isDisabled={rest.isDisabled}
-        isReadOnly={rest.isReadOnly}
-      />
-      <RaPopover>
-        <ComboBoxOptions renderEmptyState={renderEmptyState}>
-          {children}
-        </ComboBoxOptions>
-      </RaPopover>
-    </RaComboBox>
-  );
-};
diff --git a/packages/nimbus/src/components/combobox/components/combobox.tag-group.tsx b/packages/nimbus/src/components/combobox/components/combobox.tag-group.tsx
new file mode 100644
index 000000000..68b5d8f54
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/components/combobox.tag-group.tsx
@@ -0,0 +1,80 @@
+import { useContext } from "react";
+import {
+  TagGroupContext,
+  type ContextValue,
+  type TagGroupProps,
+} from "react-aria-components";
+import { TagGroup } from "@/components";
+import { useComboBoxRootContext } from "./combobox.root-context";
+import { ComboBoxTagGroupSlot } from "../combobox.slots";
+import type { ComboBoxTagGroupProps } from "../combobox.types";
+import { extractStyleProps } from "@/utils";
+
+/**
+ * # ComboBox.TagGroup (Internal Component)
+ *
+ * Internal component that displays selected items as tags in multi-select mode.
+ * Automatically rendered by ComboBox.Trigger - not exposed to consumers.
+ *
+ * Consumes React-Aria's TagGroupContext, which is populated by the
+ * TagGroupContextProvider in ComboBox.Root with:
+ * - items: selected items array from collection
+ * - onRemove: handler to remove tags
+ * - size: tag size matching ComboBox size
+ * - aria-label: accessible label for the tag group
+ * - id: generated in ComboBox.Root
+ * - selectionMode: "none" (tags are not selectable)
+ * - disabledKeys: disabled tag keys
+ *
+ * Renders null in single-select mode to avoid unnecessary DOM elements.
+ *
+ * @internal
+ * @supportsStyleProps
+ */
+export const ComboBoxTagGroup = (props: ComboBoxTagGroupProps) => {
+  const { selectionMode, size, getKey, getTextValue, isDisabled, isReadOnly } =
+    useComboBoxRootContext();
+  const [styleProps, functionalProps] = extractStyleProps(props);
+
+  const tagGroupContext =
+    useContext<
+      ContextValue<TagGroupProps & { items?: object[] }, HTMLDivElement>
+    >(TagGroupContext);
+
+  // Extract items from context, handling both direct values and slotted values
+  const items =
+    (tagGroupContext && "items" in tagGroupContext
+      ? tagGroupContext.items
+      : undefined) ?? [];
+
+  // Only render in multi-select mode
+  if (selectionMode !== "multiple") {
+    return null;
+  }
+
+  return (
+    <ComboBoxTagGroupSlot {...styleProps} {...functionalProps} asChild>
+      {/* TagGroup.Root receives id from TagGroupContext set by custom-context */}
+      <TagGroup.Root size={size}>
+        <TagGroup.TagList items={items} display="contents">
+          {(item) => {
+            const itemKey = getKey(item);
+            const itemValue = getTextValue(item);
+            return (
+              <TagGroup.Tag
+                id={itemKey}
+                textValue={itemValue}
+                isDisabled={isDisabled || isReadOnly}
+                maxW="100%"
+              >
+                {itemValue}
+              </TagGroup.Tag>
+            );
+          }}
+        </TagGroup.TagList>
+      </TagGroup.Root>
+    </ComboBoxTagGroupSlot>
+  );
+};
+
+ComboBoxTagGroup.displayName = "ComboBox.TagGroup";
diff --git a/packages/nimbus/src/components/combobox/components/combobox.trigger.tsx b/packages/nimbus/src/components/combobox/components/combobox.trigger.tsx
new file mode 100644
index 000000000..2c40b50c6
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/components/combobox.trigger.tsx
@@ -0,0 +1,87 @@
+import { Close, KeyboardArrowDown } from "@commercetools/nimbus-icons";
+import { IconButton } from "@/components/icon-button/icon-button";
+import { LoadingSpinner } from "@/components/loading-spinner/loading-spinner";
+import { useComboBoxRootContext } from "./combobox.root-context";
+import { ComboBoxTriggerSlot, ComboBoxContentSlot } from "../combobox.slots";
+import type { ComboBoxTriggerProps } from "../combobox.types";
+import { ComboBoxInput } from "./combobox.input";
+import { ComboBoxLeadingElement } from "./combobox.leading-element";
+import { ComboBoxTagGroup } from "./combobox.tag-group";
+
+/**
+ * # ComboBox.Trigger
+ *
+ * The trigger element that contains the input field and controls for the combobox.
+ * Automatically renders the tag group (for multi-select), input field, toggle button, and clear button.
+ * Handles click interactions to focus the input when clicking anywhere on the trigger area.
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root>
+ *   <ComboBox.Trigger />
+ *   <ComboBox.Popover>
+ *     <ComboBox.ListBox>
+ *       <ComboBox.Item value="option1">Option 1</ComboBox.Item>
+ *     </ComboBox.ListBox>
+ *   </ComboBox.Popover>
+ * </ComboBox.Root>
+ * ```
+ *
+ * @supportsStyleProps
+ */
+export const ComboBoxTrigger = ({
+  children,
+  ...restProps
+}: ComboBoxTriggerProps) => {
+  const { triggerRef, leadingElement, inputRef, isLoading, isDisabled } =
+    useComboBoxRootContext();
+
+  const handleClick = (e: React.MouseEvent<HTMLDivElement>) => {
+    // Focus input when clicking anywhere on the trigger, except on buttons
+    if (
+      !isDisabled &&
+      e.target instanceof HTMLElement &&
+      !e.target.closest("button")
+    ) {
+      inputRef.current?.focus();
+    }
+  };
+
+  return (
+    <ComboBoxTriggerSlot ref={triggerRef} onClick={handleClick} {...restProps}>
+      {leadingElement && (
+        <ComboBoxLeadingElement>{leadingElement}</ComboBoxLeadingElement>
+      )}
+      <ComboBoxContentSlot>
+        <ComboBoxTagGroup />
+        <ComboBoxInput />
+      </ComboBoxContentSlot>
+      <IconButton
+        slot="clear"
+        size="2xs"
+        variant="ghost"
+        colorPalette="primary"
+      >
+        <Close />
+      </IconButton>
+
+      <IconButton
+        slot="toggle"
+        size="2xs"
+        variant="ghost"
+        colorPalette="neutral"
+        excludeFromTabOrder
+      >
+        {isLoading ? (
+          <LoadingSpinner size="xs" margin="50" />
+        ) : (
+          <KeyboardArrowDown />
+        )}
+      </IconButton>
+
+      {children}
+    </ComboBoxTriggerSlot>
+  );
+};
+
+ComboBoxTrigger.displayName = "ComboBox.Trigger";
diff --git a/packages/nimbus/src/components/combobox/components/index.ts b/packages/nimbus/src/components/combobox/components/index.ts
index 0d3f4cbf0..a5fe64c87 100644
--- a/packages/nimbus/src/components/combobox/components/index.ts
+++ b/packages/nimbus/src/components/combobox/components/index.ts
@@ -1,11 +1,6 @@
 export { ComboBoxRoot } from "./combobox.root";
-export { ComboBoxOptionGroup } from "./combobox.option-group";
+export { ComboBoxTrigger } from "./combobox.trigger";
+export { ComboBoxPopover } from "./combobox.popover";
+export { ComboBoxListBox } from "./combobox.listbox";
 export { ComboBoxOption } from "./combobox.option";
-export { ComboBoxLeadingElement } from "./combobox.leading-element";
-export { ComboBoxOptions } from "./combobox.options";
-export { SingleSelectRoot } from "./combobox.single-select-root";
-export { SingleSelectInput } from "./combobox.single-select-input";
-export { ComboBoxSingleSelectButtonGroup } from "./combobox.single-select-button-group";
-export { MultiSelectRoot } from "./combobox.multi-select-root";
-export { ComboBoxButtonGroup } from "./combobox.multi-select-button-group";
-export { MultiSelectTagGroup } from "./combobox.multi-select-tag-group";
+export { ComboBoxSection } from "./combobox.section";
diff --git a/packages/nimbus/src/components/combobox/index.ts b/packages/nimbus/src/components/combobox/index.ts
index 788b89817..daaf5a033 100644
--- a/packages/nimbus/src/components/combobox/index.ts
+++ b/packages/nimbus/src/components/combobox/index.ts
@@ -1,2 +1,2 @@
-export * from "./combobox";
+export { ComboBox } from "./combobox";
 export * from "./combobox.types";
diff --git a/packages/nimbus/src/components/combobox/utils/collection.spec.ts b/packages/nimbus/src/components/combobox/utils/collection.spec.ts
new file mode 100644
index 000000000..15f525418
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/utils/collection.spec.ts
@@ -0,0 +1,208 @@
+import { describe, it, expect } from "vitest";
+import {
+  defaultGetKey,
+  defaultGetTextValue,
+  defaultGetNewOptionData,
+} from "./collection";
+
+describe("collection utilities", () => {
+  describe("defaultGetKey", () => {
+    describe("string keys", () => {
+      it("returns the string as-is", () => {
+        expect(defaultGetKey("test-key")).toBe("test-key");
+      });
+
+      it("handles empty string", () => {
+        expect(defaultGetKey("")).toBe("");
+      });
+    });
+
+    describe("number keys", () => {
+      it("returns the number as-is", () => {
+        expect(defaultGetKey(123)).toBe(123);
+      });
+
+      it("handles zero", () => {
+        expect(defaultGetKey(0)).toBe(0);
+      });
+
+      it("handles negative numbers", () => {
+        expect(defaultGetKey(-42)).toBe(-42);
+      });
+    });
+
+    describe("object with id property", () => {
+      it("extracts id from object with string id", () => {
+        const item = { id: "item-1", name: "Item 1" };
+        expect(defaultGetKey(item)).toBe("item-1");
+      });
+
+      it("extracts id from object with number id", () => {
+        const item = { id: 42, name: "Item 42" };
+        expect(defaultGetKey(item)).toBe(42);
+      });
+
+      it("works with objects that have additional properties", () => {
+        const item = { id: "test", name: "Test", value: 123, extra: "data" };
+        expect(defaultGetKey(item)).toBe("test");
+      });
+    });
+
+    describe("error handling", () => {
+      it("throws error for object without id property", () => {
+        const item = { name: "Test" };
+        expect(() => defaultGetKey(item)).toThrow(
+          "Item must have an 'id' property or provide getKey function"
+        );
+      });
+
+      it("throws error for empty object", () => {
+        const item = {};
+        expect(() => defaultGetKey(item)).toThrow(
+          "Item must have an 'id' property or provide getKey function"
+        );
+      });
+    });
+  });
+
+  describe("defaultGetTextValue", () => {
+    describe("string items", () => {
+      it("returns the string as-is", () => {
+        expect(defaultGetTextValue("Test String")).toBe("Test String");
+      });
+
+      it("handles empty string", () => {
+        expect(defaultGetTextValue("")).toBe("");
+      });
+    });
+
+    describe("object with name property", () => {
+      it("extracts name from object", () => {
+        const item = { id: "1", name: "Item Name" };
+        expect(defaultGetTextValue(item)).toBe("Item Name");
+      });
+
+      it("converts non-string name to string", () => {
+        const item = { id: "1", name: 123 };
+        expect(defaultGetTextValue(item)).toBe("123");
+      });
+
+      it("prefers name over label when both exist", () => {
+        const item = { id: "1", name: "Name Value", label: "Label Value" };
+        expect(defaultGetTextValue(item)).toBe("Name Value");
+      });
+    });
+
+    describe("object with label property", () => {
+      it("extracts label when name is not present", () => {
+        const item = { id: "1", label: "Item Label" };
+        expect(defaultGetTextValue(item)).toBe("Item Label");
+      });
+
+      it("converts non-string label to string", () => {
+        const item = { id: "1", label: 456 };
+        expect(defaultGetTextValue(item)).toBe("456");
+      });
+    });
+
+    describe("fallback behavior", () => {
+      it("converts object to string when no name or label", () => {
+        const item = { id: "1", value: "test" };
+        expect(defaultGetTextValue(item)).toBe("[object Object]");
+      });
+
+      it("handles objects with toString method", () => {
+        const item = {
+          id: "1",
+          toString() {
+            return "Custom String";
+          },
+        };
+        expect(defaultGetTextValue(item)).toBe("Custom String");
+      });
+    });
+  });
+
+  describe("defaultGetNewOptionData", () => {
+    describe("basic functionality", () => {
+      it("creates object with id and name from input", () => {
+        const result = defaultGetNewOptionData<{ id: string; name: string }>(
+          "New Option"
+        );
+
+        expect(result).toEqual({
+          id: "New Option",
+          name: "New Option",
+        });
+      });
+
+      it("handles empty string input", () => {
+        const result = defaultGetNewOptionData<{ id: string; name: string }>(
+          ""
+        );
+
+        expect(result).toEqual({
+          id: "",
+          name: "",
+        });
+      });
+
+      it("handles input with special characters", () => {
+        const input = "Special!@#$%^&*()_+-=[]{}|;:',.<>?";
+        const result = defaultGetNewOptionData<{ id: string; name: string }>(
+          input
+        );
+
+        expect(result).toEqual({
+          id: input,
+          name: input,
+        });
+      });
+
+      it("handles input with whitespace", () => {
+        const result = defaultGetNewOptionData<{ id: string; name: string }>(
+          "  Spaced  Option  "
+        );
+
+        expect(result).toEqual({
+          id: "  Spaced  Option  ",
+          name: "  Spaced  Option  ",
+        });
+      });
+
+      it("handles unicode characters", () => {
+        const result = defaultGetNewOptionData<{ id: string; name: string }>(
+          "日本語 🎉"
+        );
+
+        expect(result).toEqual({
+          id: "日本語 🎉",
+          name: "日本語 🎉",
+        });
+      });
+    });
+
+    describe("return type", () => {
+      it("returns object with correct structure", () => {
+        const result = defaultGetNewOptionData<{ id: string; name: string }>(
+          "Test"
+        );
+
+        expect(result).toHaveProperty("id");
+        expect(result).toHaveProperty("name");
+        expect(Object.keys(result)).toHaveLength(2);
+      });
+
+      it("can be cast to different types", () => {
+        // This tests the type casting behavior of the function
+        type CustomType = { id: string; name: string; extra?: string };
+        const result = defaultGetNewOptionData<CustomType>("Test");
+
+        // TypeScript should accept this without error
+        const typed: CustomType = result;
+        expect(typed.id).toBe("Test");
+        expect(typed.name).toBe("Test");
+      });
+    });
+  });
+});
diff --git a/packages/nimbus/src/components/combobox/utils/collection.ts b/packages/nimbus/src/components/combobox/utils/collection.ts
new file mode 100644
index 000000000..f504fe5d2
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/utils/collection.ts
@@ -0,0 +1,50 @@
+import { type Key } from "react-stately";
+/**
+ * Default key extractor - uses string/number id or object with id property
+ */
+export function defaultGetKey<T extends object>(
+  item: T | string | number
+): Key {
+  if (typeof item === "string" || typeof item === "number") {
+    return item as Key;
+  }
+  if ("id" in item) {
+    return (item as { id: Key }).id;
+  }
+  throw new Error(
+    "ComboBox - Item must have an 'id' property or provide getKey function"
+  );
+}
+
+/**
+ * Default text value extractor - uses string item or object with name property
+ */
+export function defaultGetTextValue<T extends object>(
+  item: T | string
+): string {
+  if (typeof item === "string") {
+    return item;
+  }
+  if ("name" in item) {
+    return String((item as { name: unknown }).name);
+  }
+  if ("label" in item) {
+    return String((item as { label: unknown }).label);
+  }
+  console.warn(
+    "ComboBox - Item should have 'name' or 'label' property. Provide a getTextValue function to ensure proper item display and filtering."
+  );
+  return String(item);
+}
+
+/**
+ * Default getNewOptionData - creates an object with id and name
+ */
+export function defaultGetNewOptionData<T extends object>(
+  inputValue: string
+): T {
+  return {
+    id: inputValue,
+    name: inputValue,
+  } as T;
+}
diff --git a/packages/nimbus/src/components/combobox/utils/filters.spec.ts b/packages/nimbus/src/components/combobox/utils/filters.spec.ts
new file mode 100644
index 000000000..89579535a
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/utils/filters.spec.ts
@@ -0,0 +1,783 @@
+import { describe, it, expect } from "vitest";
+import type { Node } from "react-stately";
+import {
+  filterByText,
+  filterByStartsWith,
+  filterByCaseSensitive,
+  filterByWordBoundary,
+  filterByFuzzy,
+  createMultiPropertyFilter,
+  createRankedFilter,
+  createMultiTermFilter,
+  createSectionAwareFilter,
+} from "./filters";
+
+// Helper to create mock nodes
+function createMockNode<T extends object>(
+  key: string,
+  textValue: string,
+  value?: T,
+  type: "item" | "section" = "item"
+): Node<T> {
+  return {
+    key,
+    textValue,
+    value: value as T,
+    type,
+  } as Node<T>;
+}
+
+describe("filter utilities", () => {
+  describe("filterByText", () => {
+    const nodes = [
+      createMockNode("1", "Apple"),
+      createMockNode("2", "Banana"),
+      createMockNode("3", "Cherry"),
+      createMockNode("4", "Date"),
+      createMockNode("5", "Elderberry"),
+    ];
+
+    describe("basic filtering", () => {
+      it("returns all nodes when input is empty", () => {
+        const result = Array.from(filterByText(nodes, ""));
+        expect(result).toHaveLength(5);
+      });
+
+      it("returns all nodes when input is whitespace only", () => {
+        const result = Array.from(filterByText(nodes, "   "));
+        expect(result).toHaveLength(5);
+      });
+
+      it("filters by substring match", () => {
+        const result = Array.from(filterByText(nodes, "an"));
+        expect(result).toHaveLength(1);
+        expect(result[0].textValue).toBe("Banana");
+      });
+
+      it("is case-insensitive", () => {
+        const result = Array.from(filterByText(nodes, "APPLE"));
+        expect(result).toHaveLength(1);
+        expect(result[0].textValue).toBe("Apple");
+      });
+
+      it("matches multiple items", () => {
+        const result = Array.from(filterByText(nodes, "e"));
+        expect(result).toHaveLength(4);
+        expect(result.map((n) => n.textValue)).toEqual([
+          "Apple",
+          "Cherry",
+          "Date",
+          "Elderberry",
+        ]);
+      });
+    });
+
+    describe("edge cases", () => {
+      it("returns empty array when no matches", () => {
+        const result = Array.from(filterByText(nodes, "xyz"));
+        expect(result).toHaveLength(0);
+      });
+
+      it("handles empty node list", () => {
+        const result = Array.from(filterByText([], "test"));
+        expect(result).toHaveLength(0);
+      });
+
+      it("handles special characters in input", () => {
+        const specialNodes = [
+          createMockNode("1", "test@example.com"),
+          createMockNode("2", "user+tag@test.com"),
+        ];
+        const result = Array.from(filterByText(specialNodes, "@"));
+        expect(result).toHaveLength(2);
+      });
+    });
+  });
+
+  describe("filterByStartsWith", () => {
+    const nodes = [
+      createMockNode("1", "Apple"),
+      createMockNode("2", "Apricot"),
+      createMockNode("3", "Banana"),
+      createMockNode("4", "Blueberry"),
+      createMockNode("5", "Cherry"),
+    ];
+
+    describe("basic filtering", () => {
+      it("returns all nodes when input is empty", () => {
+        const result = Array.from(filterByStartsWith(nodes, ""));
+        expect(result).toHaveLength(5);
+      });
+
+      it("filters by prefix match", () => {
+        const result = Array.from(filterByStartsWith(nodes, "Ap"));
+        expect(result).toHaveLength(2);
+        expect(result.map((n) => n.textValue)).toEqual(["Apple", "Apricot"]);
+      });
+
+      it("is case-insensitive", () => {
+        const result = Array.from(filterByStartsWith(nodes, "ap"));
+        expect(result).toHaveLength(2);
+      });
+
+      it("does not match substrings in middle", () => {
+        const result = Array.from(filterByStartsWith(nodes, "berry"));
+        expect(result).toHaveLength(0);
+      });
+    });
+
+    describe("edge cases", () => {
+      it("matches single character prefix", () => {
+        const result = Array.from(filterByStartsWith(nodes, "B"));
+        expect(result).toHaveLength(2);
+        expect(result.map((n) => n.textValue)).toEqual(["Banana", "Blueberry"]);
+      });
+
+      it("returns exact match", () => {
+        const result = Array.from(filterByStartsWith(nodes, "Cherry"));
+        expect(result).toHaveLength(1);
+        expect(result[0].textValue).toBe("Cherry");
+      });
+    });
+  });
+
+  describe("filterByCaseSensitive", () => {
+    const nodes = [
+      createMockNode("1", "Apple"),
+      createMockNode("2", "apple"),
+      createMockNode("3", "APPLE"),
+      createMockNode("4", "Banana"),
+    ];
+
+    describe("case-sensitive matching", () => {
+      it("returns all nodes when input is empty", () => {
+        const result = Array.from(filterByCaseSensitive(nodes, ""));
+        expect(result).toHaveLength(4);
+      });
+
+      it("matches exact case only", () => {
+        const result = Array.from(filterByCaseSensitive(nodes, "Apple"));
+        expect(result).toHaveLength(1);
+        expect(result[0].textValue).toBe("Apple");
+      });
+
+      it("does not match different case", () => {
+        const result = Array.from(filterByCaseSensitive(nodes, "apple"));
+        expect(result).toHaveLength(1);
+        expect(result[0].textValue).toBe("apple");
+      });
+
+      it("matches uppercase", () => {
+        const result = Array.from(filterByCaseSensitive(nodes, "APPLE"));
+        expect(result).toHaveLength(1);
+        expect(result[0].textValue).toBe("APPLE");
+      });
+    });
+
+    describe("substring matching", () => {
+      it("matches case-sensitive substrings", () => {
+        const result = Array.from(filterByCaseSensitive(nodes, "pp"));
+        expect(result).toHaveLength(2);
+        expect(result.map((n) => n.textValue)).toEqual(["Apple", "apple"]);
+      });
+
+      it("does not match wrong case substrings", () => {
+        const result = Array.from(filterByCaseSensitive(nodes, "PP"));
+        expect(result).toHaveLength(1);
+        expect(result[0].textValue).toBe("APPLE");
+      });
+    });
+  });
+
+  describe("filterByWordBoundary", () => {
+    const nodes = [
+      createMockNode("1", "Bald Eagle"),
+      createMockNode("2", "Golden Eagle"),
+      createMockNode("3", "Beagle"),
+      createMockNode("4", "Eagle Mountain"),
+      createMockNode("5", "The Eagle"),
+    ];
+
+    describe("word boundary matching", () => {
+      it("returns all nodes when input is empty", () => {
+        const result = Array.from(filterByWordBoundary(nodes, ""));
+        expect(result).toHaveLength(5);
+      });
+
+      it("matches word at start", () => {
+        const result = Array.from(filterByWordBoundary(nodes, "Eagle"));
+        expect(result).toHaveLength(4);
+        expect(result.map((n) => n.textValue)).toEqual([
+          "Bald Eagle",
+          "Golden Eagle",
+          "Eagle Mountain",
+          "The Eagle",
+        ]);
+      });
+
+      it("does not match partial word", () => {
+        const result = Array.from(filterByWordBoundary(nodes, "eagle"));
+        // Should not match "Beagle" since "eagle" is not at word boundary
+        expect(result).toHaveLength(4);
+        expect(result.some((n) => n.textValue === "Beagle")).toBe(false);
+      });
+
+      it("is case-insensitive", () => {
+        const result = Array.from(filterByWordBoundary(nodes, "bald"));
+        expect(result).toHaveLength(1);
+        expect(result[0].textValue).toBe("Bald Eagle");
+      });
+    });
+
+    describe("special character handling", () => {
+      it("escapes regex special characters", () => {
+        const specialNodes = [
+          createMockNode("1", "test.file"),
+          createMockNode("2", "test+plus"),
+          createMockNode("3", "test[bracket]"),
+        ];
+        const result = Array.from(filterByWordBoundary(specialNodes, "test."));
+        expect(result).toHaveLength(1);
+        expect(result[0].textValue).toBe("test.file");
+      });
+    });
+  });
+
+  describe("filterByFuzzy", () => {
+    const nodes = [
+      createMockNode("1", "Bald Eagle"),
+      createMockNode("2", "Blue Elephant"),
+      createMockNode("3", "Black Bear"),
+      createMockNode("4", "New Jersey"),
+      createMockNode("5", "New York"),
+    ];
+
+    describe("fuzzy matching", () => {
+      it("returns all nodes when input is empty", () => {
+        const result = Array.from(filterByFuzzy(nodes, ""));
+        expect(result).toHaveLength(5);
+      });
+
+      it("matches characters in order with gaps", () => {
+        const result = Array.from(filterByFuzzy(nodes, "ble"));
+        expect(result).toHaveLength(3);
+        expect(result.map((n) => n.textValue)).toEqual([
+          "Bald Eagle",
+          "Blue Elephant",
+          "Black Bear",
+        ]);
+      });
+
+      it("matches abbreviated input", () => {
+        const result = Array.from(filterByFuzzy(nodes, "nj"));
+        expect(result).toHaveLength(1);
+        expect(result[0].textValue).toBe("New Jersey");
+      });
+
+      it("is case-insensitive", () => {
+        const result = Array.from(filterByFuzzy(nodes, "BE"));
+        expect(result).toHaveLength(3);
+        expect(result.map((n) => n.textValue)).toEqual([
+          "Bald Eagle",
+          "Blue Elephant",
+          "Black Bear",
+        ]);
+      });
+
+      it("does not match out of order characters", () => {
+        const result = Array.from(filterByFuzzy(nodes, "elb"));
+        expect(result).toHaveLength(0);
+      });
+    });
+
+    describe("edge cases", () => {
+      it("matches single character", () => {
+        const result = Array.from(filterByFuzzy(nodes, "B"));
+        expect(result).toHaveLength(3);
+      });
+
+      it("requires all characters to match in order", () => {
+        const result = Array.from(filterByFuzzy(nodes, "Bld"));
+        expect(result).toHaveLength(1);
+        expect(result[0].textValue).toBe("Bald Eagle");
+      });
+    });
+  });
+
+  describe("createMultiPropertyFilter", () => {
+    type Product = {
+      id: string;
+      name: string;
+      category: string;
+      description: string;
+    };
+
+    const products: Node<Product>[] = [
+      createMockNode("1", "iPhone", {
+        id: "1",
+        name: "iPhone",
+        category: "Electronics",
+        description: "A smartphone",
+      }),
+      createMockNode("2", "iPad", {
+        id: "2",
+        name: "iPad",
+        category: "Electronics",
+        description: "A tablet device",
+      }),
+      createMockNode("3", "Desk", {
+        id: "3",
+        name: "Desk",
+        category: "Furniture",
+        description: "Office desk",
+      }),
+    ];
+
+    describe("multi-property search", () => {
+      it("returns all nodes when input is empty", () => {
+        const filter = createMultiPropertyFilter<Product>(["name", "category"]);
+        const result = Array.from(filter(products, ""));
+        expect(result).toHaveLength(3);
+      });
+
+      it("searches across specified properties", () => {
+        const filter = createMultiPropertyFilter<Product>([
+          "name",
+          "category",
+          "description",
+        ]);
+        const result = Array.from(filter(products, "tablet"));
+        expect(result).toHaveLength(1);
+        expect(result[0]?.value?.name).toBe("iPad");
+      });
+
+      it("matches if any property contains input", () => {
+        const filter = createMultiPropertyFilter<Product>(["name", "category"]);
+        const result = Array.from(filter(products, "Electronics"));
+        expect(result).toHaveLength(2);
+        expect(result.map((n) => n?.value?.name)).toEqual(["iPhone", "iPad"]);
+      });
+
+      it("is case-insensitive", () => {
+        const filter = createMultiPropertyFilter<Product>(["category"]);
+        const result = Array.from(filter(products, "electronics"));
+        expect(result).toHaveLength(2);
+      });
+    });
+
+    describe("nested property support", () => {
+      type NestedProduct = {
+        id: string;
+        details: {
+          name: string;
+          specs: {
+            brand: string;
+          };
+        };
+      };
+
+      it("supports dot notation for nested properties", () => {
+        const nestedProducts: Node<NestedProduct>[] = [
+          createMockNode("1", "Product 1", {
+            id: "1",
+            details: { name: "iPhone", specs: { brand: "Apple" } },
+          }),
+          createMockNode("2", "Product 2", {
+            id: "2",
+            details: { name: "Galaxy", specs: { brand: "Samsung" } },
+          }),
+        ];
+
+        const filter = createMultiPropertyFilter<NestedProduct>([
+          "details.name",
+          "details.specs.brand",
+        ]);
+        const result = Array.from(filter(nestedProducts, "Apple"));
+        expect(result).toHaveLength(1);
+        expect(result[0]?.value?.details.specs.brand).toBe("Apple");
+      });
+    });
+
+    describe("edge cases", () => {
+      it("handles nodes without value", () => {
+        const nodesWithoutValue: Node<Product>[] = [
+          { key: "1", textValue: "Test", type: "item" } as Node<Product>,
+        ];
+        const filter = createMultiPropertyFilter<Product>(["name"]);
+        const result = Array.from(filter(nodesWithoutValue, "test"));
+        expect(result).toHaveLength(0);
+      });
+
+      it("handles null/undefined property values", () => {
+        const nodesWithNull: Node<Partial<Product>>[] = [
+          createMockNode("1", "Test", {
+            id: "1",
+            name: "Test",
+            category: undefined as unknown as string,
+            description: "",
+          }),
+        ];
+        const filter = createMultiPropertyFilter<Partial<Product>>([
+          "category",
+        ]);
+        const result = Array.from(filter(nodesWithNull, "test"));
+        expect(result).toHaveLength(0);
+      });
+    });
+  });
+
+  describe("createRankedFilter", () => {
+    const nodes = [
+      createMockNode("1", "Apple"),
+      createMockNode("2", "Apricot"),
+      createMockNode("3", "Banana"),
+      createMockNode("4", "Pineapple"),
+    ];
+
+    describe("scoring and ranking", () => {
+      it("returns all nodes when input is empty", () => {
+        const filter = createRankedFilter<object>(() => 1);
+        const result = Array.from(filter(nodes, ""));
+        expect(result).toHaveLength(4);
+      });
+
+      it("filters out items with score <= 0", () => {
+        const filter = createRankedFilter<object>((node) => {
+          return node.textValue.startsWith("A") ? 100 : 0;
+        });
+        const result = Array.from(filter(nodes, "test"));
+        expect(result).toHaveLength(2);
+        expect(result.map((n) => n.textValue)).toEqual(["Apple", "Apricot"]);
+      });
+
+      it("sorts by score descending", () => {
+        const filter = createRankedFilter<object>((node, input) => {
+          const text = node.textValue.toLowerCase();
+          const lowerInput = input.toLowerCase();
+          if (text.startsWith(lowerInput)) return 100;
+          if (text.includes(lowerInput)) return 50;
+          return 0;
+        });
+        const result = Array.from(filter(nodes, "app"));
+        // "Apple" starts with "app" (score 100)
+        // "Pineapple" contains "app" (score 50)
+        // "Apricot" doesn't contain "app" (score 0, filtered out)
+        expect(result.map((n) => n.textValue)).toEqual(["Apple", "Pineapple"]);
+      });
+
+      it("handles equal scores", () => {
+        const filter = createRankedFilter<object>(() => 50);
+        const result = Array.from(filter(nodes, "test"));
+        expect(result).toHaveLength(4);
+      });
+    });
+
+    describe("custom scoring logic", () => {
+      it("can use complex scoring algorithms", () => {
+        const filter = createRankedFilter<object>((node, input) => {
+          const text = node.textValue.toLowerCase();
+          const lowerInput = input.toLowerCase();
+
+          let score = 0;
+          if (text === lowerInput)
+            score = 1000; // Exact match
+          else if (text.startsWith(lowerInput))
+            score = 100; // Prefix
+          else if (text.includes(lowerInput))
+            score = 50; // Substring
+          else return 0;
+
+          // Boost shorter results
+          score += 100 / text.length;
+
+          return score;
+        });
+
+        const result = Array.from(filter(nodes, "apple"));
+        // "Apple" should score highest (exact match + shortest)
+        expect(result[0].textValue).toBe("Apple");
+      });
+    });
+  });
+
+  describe("createMultiTermFilter", () => {
+    const nodes = [
+      createMockNode("1", "Bald Eagle"),
+      createMockNode("2", "Golden Eagle"),
+      createMockNode("3", "Bison"),
+      createMockNode("4", "Black Bear"),
+      createMockNode("5", "Brown Bear"),
+    ];
+
+    describe("multi-term matching", () => {
+      it("returns all nodes when input is empty", () => {
+        const filter = createMultiTermFilter<object>();
+        const result = Array.from(filter(nodes, ""));
+        expect(result).toHaveLength(5);
+      });
+
+      it("matches items containing any term (OR logic)", () => {
+        const filter = createMultiTermFilter<object>();
+        const result = Array.from(filter(nodes, "eagle bison"));
+        expect(result).toHaveLength(3);
+        expect(result.map((n) => n.textValue)).toEqual([
+          "Bald Eagle",
+          "Golden Eagle",
+          "Bison",
+        ]);
+      });
+
+      it("splits input by whitespace", () => {
+        const filter = createMultiTermFilter<object>();
+        const result = Array.from(filter(nodes, "  bald   golden  "));
+        expect(result).toHaveLength(2);
+        expect(result.map((n) => n.textValue)).toEqual([
+          "Bald Eagle",
+          "Golden Eagle",
+        ]);
+      });
+
+      it("removes duplicate matches", () => {
+        const filter = createMultiTermFilter<object>();
+        const result = Array.from(filter(nodes, "bear black brown"));
+        // Should not duplicate "Black Bear" or "Brown Bear"
+        expect(result).toHaveLength(2);
+      });
+    });
+
+    describe("custom base filter", () => {
+      it("uses custom base filter for term matching", () => {
+        const filter = createMultiTermFilter<object>(filterByStartsWith);
+        const result = Array.from(filter(nodes, "bald golden"));
+        expect(result).toHaveLength(2);
+        expect(result.map((n) => n.textValue)).toEqual([
+          "Bald Eagle",
+          "Golden Eagle",
+        ]);
+      });
+
+      it("works with fuzzy filter", () => {
+        const filter = createMultiTermFilter<object>(filterByFuzzy);
+        const result = Array.from(filter(nodes, "ble bbr"));
+        expect(result).toHaveLength(3);
+      });
+    });
+  });
+
+  describe("createSectionAwareFilter", () => {
+    type AnimalItem = { id: string; name: string };
+    type AnimalSection = { id: string; name: string; items: AnimalItem[] };
+
+    describe("section structure preservation", () => {
+      it("returns all nodes when input is empty", () => {
+        const nodes = [
+          createMockNode<AnimalSection>(
+            "mammals",
+            "Mammals",
+            undefined,
+            "section"
+          ),
+          createMockNode<AnimalItem>("1", "Lion"),
+          createMockNode<AnimalItem>("2", "Tiger"),
+          createMockNode<AnimalSection>("birds", "Birds", undefined, "section"),
+          createMockNode<AnimalItem>("3", "Eagle"),
+          createMockNode<AnimalItem>("4", "Hawk"),
+        ];
+
+        const filter = createSectionAwareFilter<AnimalItem | AnimalSection>(
+          filterByText
+        );
+        const result = Array.from(filter(nodes, ""));
+        expect(result).toHaveLength(6);
+      });
+
+      it("preserves sections with matching items", () => {
+        const nodes = [
+          createMockNode<AnimalSection>(
+            "mammals",
+            "Mammals",
+            undefined,
+            "section"
+          ),
+          createMockNode<AnimalItem>("1", "Lion"),
+          createMockNode<AnimalItem>("2", "Tiger"),
+          createMockNode<AnimalSection>("birds", "Birds", undefined, "section"),
+          createMockNode<AnimalItem>("3", "Eagle"),
+          createMockNode<AnimalItem>("4", "Hawk"),
+        ];
+
+        const filter = createSectionAwareFilter<AnimalItem | AnimalSection>(
+          filterByText
+        );
+        const result = Array.from(filter(nodes, "Eagle"));
+
+        // Should include: section "birds" + "Eagle"
+        expect(result).toHaveLength(2);
+        expect(result[0].type).toBe("section");
+        expect(result[0].textValue).toBe("Birds");
+        expect(result[1].textValue).toBe("Eagle");
+      });
+
+      it("hides sections with no matching items", () => {
+        const nodes = [
+          createMockNode<AnimalSection>(
+            "mammals",
+            "Mammals",
+            undefined,
+            "section"
+          ),
+          createMockNode<AnimalItem>("1", "Lion"),
+          createMockNode<AnimalItem>("2", "Tiger"),
+          createMockNode<AnimalSection>("birds", "Birds", undefined, "section"),
+          createMockNode<AnimalItem>("3", "Eagle"),
+          createMockNode<AnimalItem>("4", "Hawk"),
+        ];
+
+        const filter = createSectionAwareFilter<AnimalItem | AnimalSection>(
+          filterByText
+        );
+        const result = Array.from(filter(nodes, "Lion"));
+
+        // Should include: section "mammals" + "Lion" only
+        expect(result).toHaveLength(2);
+        expect(result[0].textValue).toBe("Mammals");
+        expect(result[1].textValue).toBe("Lion");
+      });
+
+      it("handles multiple sections with matches", () => {
+        const nodes = [
+          createMockNode<AnimalSection>(
+            "mammals",
+            "Mammals",
+            undefined,
+            "section"
+          ),
+          createMockNode<AnimalItem>("1", "Bear"),
+          createMockNode<AnimalItem>("2", "Tiger"),
+          createMockNode<AnimalSection>("birds", "Birds", undefined, "section"),
+          createMockNode<AnimalItem>("3", "Eagle"),
+          createMockNode<AnimalItem>("4", "Peacock"),
+        ];
+
+        const filter = createSectionAwareFilter<AnimalItem | AnimalSection>(
+          filterByText
+        );
+        const result = Array.from(filter(nodes, "ea"));
+
+        // Should match: "Bear" in mammals, "Eagle" and "Peacock" in birds
+        expect(result).toHaveLength(5);
+        expect(result[0].textValue).toBe("Mammals");
+        expect(result[1].textValue).toBe("Bear");
+        expect(result[2].textValue).toBe("Birds");
+        expect(result[3].textValue).toBe("Eagle");
+        expect(result[4].textValue).toBe("Peacock");
+      });
+    });
+
+    describe("custom item filters", () => {
+      it("works with starts-with filter", () => {
+        const nodes = [
+          createMockNode<AnimalSection>(
+            "mammals",
+            "Mammals",
+            undefined,
+            "section"
+          ),
+          createMockNode<AnimalItem>("1", "Lion"),
+          createMockNode<AnimalItem>("2", "Tiger"),
+          createMockNode<AnimalSection>("birds", "Birds", undefined, "section"),
+          createMockNode<AnimalItem>("3", "Eagle"),
+          createMockNode<AnimalItem>("4", "Emu"),
+        ];
+
+        const filter = createSectionAwareFilter<AnimalItem | AnimalSection>(
+          filterByStartsWith
+        );
+        const result = Array.from(filter(nodes, "E"));
+
+        expect(result).toHaveLength(3);
+        expect(result[0].textValue).toBe("Birds");
+        expect(result[1].textValue).toBe("Eagle");
+        expect(result[2].textValue).toBe("Emu");
+      });
+
+      it("works with fuzzy filter", () => {
+        const nodes = [
+          createMockNode<AnimalSection>(
+            "mammals",
+            "Mammals",
+            undefined,
+            "section"
+          ),
+          createMockNode<AnimalItem>("1", "Black Bear"),
+          createMockNode<AnimalSection>("birds", "Birds", undefined, "section"),
+          createMockNode<AnimalItem>("2", "Bald Eagle"),
+        ];
+
+        const filter = createSectionAwareFilter<AnimalItem | AnimalSection>(
+          filterByFuzzy
+        );
+        const result = Array.from(filter(nodes, "ble"));
+
+        expect(result).toHaveLength(4);
+        expect(result.map((n) => n.textValue)).toEqual([
+          "Mammals",
+          "Black Bear",
+          "Birds",
+          "Bald Eagle",
+        ]);
+      });
+    });
+
+    describe("edge cases", () => {
+      it("handles empty sections", () => {
+        const nodes = [
+          createMockNode<AnimalSection>(
+            "empty",
+            "Empty Section",
+            undefined,
+            "section"
+          ),
+          createMockNode<AnimalSection>(
+            "mammals",
+            "Mammals",
+            undefined,
+            "section"
+          ),
+          createMockNode<AnimalItem>("1", "Lion"),
+        ];
+
+        const filter = createSectionAwareFilter<AnimalItem | AnimalSection>(
+          filterByText
+        );
+        const result = Array.from(filter(nodes, "Lion"));
+
+        expect(result).toHaveLength(2);
+        expect(result[0].textValue).toBe("Mammals");
+        expect(result[1].textValue).toBe("Lion");
+      });
+
+      it("handles sections at the end", () => {
+        const nodes = [
+          createMockNode<AnimalSection>(
+            "mammals",
+            "Mammals",
+            undefined,
+            "section"
+          ),
+          createMockNode<AnimalItem>("1", "Lion"),
+          createMockNode<AnimalSection>("birds", "Birds", undefined, "section"),
+        ];
+
+        const filter = createSectionAwareFilter<AnimalItem | AnimalSection>(
+          filterByText
+        );
+        const result = Array.from(filter(nodes, "Lion"));
+
+        expect(result).toHaveLength(2);
+        expect(result[0].textValue).toBe("Mammals");
+        expect(result[1].textValue).toBe("Lion");
+      });
+    });
+  });
+});
diff --git a/packages/nimbus/src/components/combobox/utils/filters.ts b/packages/nimbus/src/components/combobox/utils/filters.ts
new file mode 100644
index 000000000..17e35a4bb
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/utils/filters.ts
@@ -0,0 +1,571 @@
+import type { Node } from "react-stately";
+
+/**
+ * Default text-based filter for combobox items
+ * Filters individual items by their text content
+ * Does NOT handle sections - use createSectionAwareFilter for that
+ *
+ * @param nodes - Collection nodes to filter
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes containing only items that match the input
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={filterByText}
+ *   placeholder="Search..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Case-insensitive substring matching
+ * - Returns all nodes when input is empty or whitespace
+ * - Filters based on Node.textValue property
+ * - Does not preserve sections (use section-aware filter for that)
+ *
+ * **Note:** This filter works on individual items only. For filtering with
+ * sections preserved, use `createSectionAwareFilter` to wrap your custom
+ * filter logic.
+ */
+export function filterByText<T extends object>(
+  nodes: Iterable<Node<T>>,
+  inputValue: string
+): Iterable<Node<T>> {
+  if (!inputValue.trim()) return nodes;
+
+  const lowerInput = inputValue.toLowerCase();
+
+  const filtered: Node<T>[] = [];
+  for (const node of nodes) {
+    if (node.textValue.toLowerCase().includes(lowerInput)) {
+      filtered.push(node);
+    }
+  }
+
+  return filtered;
+}
+
+/**
+ * Starts-with filter for combobox items
+ * Matches items where textValue begins with the input
+ *
+ * @param nodes - Collection nodes to filter
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes containing only items that start with the input
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={filterByStartsWith}
+ *   placeholder="Type to filter..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Case-insensitive prefix matching
+ * - More restrictive than substring matching
+ * - Useful for autocomplete-style filtering
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Country/state selection where users type the beginning
+ * - Name lookups where first letters matter
+ * - Command palettes with prefix shortcuts
+ */
+export function filterByStartsWith<T extends object>(
+  nodes: Iterable<Node<T>>,
+  inputValue: string
+): Iterable<Node<T>> {
+  if (!inputValue.trim()) return nodes;
+
+  const lowerInput = inputValue.toLowerCase();
+
+  const filtered: Node<T>[] = [];
+  for (const node of nodes) {
+    if (node.textValue.toLowerCase().startsWith(lowerInput)) {
+      filtered.push(node);
+    }
+  }
+
+  return filtered;
+}
+
+/**
+ * Case-sensitive filter for combobox items
+ * Matches items with exact case matching
+ *
+ * @param nodes - Collection nodes to filter
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes containing only items that match with exact case
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={programmingLanguages}
+ *   filter={filterByCaseSensitive}
+ *   placeholder="Case-sensitive search..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Exact case matching (case-sensitive substring)
+ * - More precise than case-insensitive filtering
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Code/variable name search
+ * - File path filtering
+ * - Technical identifiers that are case-sensitive
+ */
+export function filterByCaseSensitive<T extends object>(
+  nodes: Iterable<Node<T>>,
+  inputValue: string
+): Iterable<Node<T>> {
+  if (!inputValue.trim()) return nodes;
+
+  const filtered: Node<T>[] = [];
+  for (const node of nodes) {
+    if (node.textValue.includes(inputValue)) {
+      filtered.push(node);
+    }
+  }
+
+  return filtered;
+}
+
+/**
+ * Word boundary filter for combobox items
+ * Matches items where input appears at word boundaries
+ *
+ * @param nodes - Collection nodes to filter
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes where input matches at word boundaries
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={filterByWordBoundary}
+ *   placeholder="Search by word..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Matches whole words or word beginnings
+ * - Case-insensitive
+ * - Input "eagle" matches "Bald Eagle" but not "beagle"
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Product search where partial words don't make sense
+ * - Name search with multiple words
+ * - Tag/category filtering
+ */
+export function filterByWordBoundary<T extends object>(
+  nodes: Iterable<Node<T>>,
+  inputValue: string
+): Iterable<Node<T>> {
+  if (!inputValue.trim()) return nodes;
+
+  // Escape special regex characters
+  const escapedInput = inputValue.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const regex = new RegExp(`\\b${escapedInput}`, "i");
+
+  const filtered: Node<T>[] = [];
+  for (const node of nodes) {
+    if (regex.test(node.textValue)) {
+      filtered.push(node);
+    }
+  }
+
+  return filtered;
+}
+
+/**
+ * Fuzzy matching filter for combobox items
+ * Matches items where all input characters appear in order (but not necessarily consecutive)
+ *
+ * @param nodes - Collection nodes to filter
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes that match the fuzzy pattern
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={filterByFuzzy}
+ *   placeholder="Fuzzy search..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Case-insensitive fuzzy matching
+ * - Input "ble" matches "Bald Eagle"
+ * - All characters must appear in order, but can have gaps
+ * - More forgiving than substring matching
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Quick command/action selection
+ * - File/folder navigation
+ * - Large lists where users know approximate spelling
+ * - Abbreviated lookups (e.g., "nj" for "New Jersey")
+ */
+export function filterByFuzzy<T extends object>(
+  nodes: Iterable<Node<T>>,
+  inputValue: string
+): Iterable<Node<T>> {
+  if (!inputValue.trim()) return nodes;
+
+  const lowerInput = inputValue.toLowerCase();
+
+  const filtered: Node<T>[] = [];
+  for (const node of nodes) {
+    const lowerText = node.textValue.toLowerCase();
+    let inputIndex = 0;
+
+    for (
+      let i = 0;
+      i < lowerText.length && inputIndex < lowerInput.length;
+      i++
+    ) {
+      if (lowerText[i] === lowerInput[inputIndex]) {
+        inputIndex++;
+      }
+    }
+
+    if (inputIndex === lowerInput.length) {
+      filtered.push(node);
+    }
+  }
+
+  return filtered;
+}
+
+/**
+ * Creates a filter that searches across multiple object properties
+ * Useful when items have structured data with multiple searchable fields
+ *
+ * @param propertyPaths - Array of property paths to search (e.g., ['name', 'description', 'tags'])
+ * @returns A filter function that searches across specified properties
+ *
+ * @example
+ * ```tsx
+ * type Product = {
+ *   name: string;
+ *   category: string;
+ *   description: string;
+ * };
+ *
+ * const productFilter = createMultiPropertyFilter<Product>(['name', 'category', 'description']);
+ *
+ * <ComboBox.Root
+ *   items={products}
+ *   filter={productFilter}
+ *   placeholder="Search products..."
+ * >
+ *   {(item) => <ComboBox.Option textValue={item.name}>{item.name}</ComboBox.Option>}
+ * </ComboBox.Root>
+ * ```
+ *
+ * **Behavior:**
+ * - Searches all specified properties
+ * - Case-insensitive substring matching
+ * - Matches if ANY property contains the input
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Product catalogs with multiple searchable fields
+ * - User directories (search by name, email, department)
+ * - Document search (title, author, tags, content)
+ * - Complex data structures with nested properties
+ *
+ * **Note:** Uses node.value to access the original item data.
+ * If you need to search nested properties, use dot notation: 'address.city'
+ */
+export function createMultiPropertyFilter<T extends object>(
+  propertyPaths: string[]
+): (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>> {
+  return (nodes: Iterable<Node<T>>, inputValue: string): Iterable<Node<T>> => {
+    if (!inputValue.trim()) return nodes;
+
+    const lowerInput = inputValue.toLowerCase();
+
+    const filtered: Node<T>[] = [];
+    for (const node of nodes) {
+      const item = node.value;
+      if (!item) continue;
+
+      // Check each property path
+      const matches = propertyPaths.some((path) => {
+        // Support nested properties with dot notation
+        const value = path.split(".").reduce<unknown>((obj, key) => {
+          return obj && typeof obj === "object"
+            ? (obj as Record<string, unknown>)[key]
+            : undefined;
+        }, item);
+
+        if (value === null || value === undefined) return false;
+
+        const stringValue = String(value).toLowerCase();
+        return stringValue.includes(lowerInput);
+      });
+
+      if (matches) {
+        filtered.push(node);
+      }
+    }
+
+    return filtered;
+  };
+}
+
+/**
+ * Creates a filter with custom scoring/ranking logic
+ * Returns items sorted by relevance score (highest first)
+ *
+ * @param scoreFn - Function that returns a relevance score for each item (higher = more relevant)
+ * @returns A filter function that sorts results by score
+ *
+ * @example
+ * ```tsx
+ * // Prefer items that start with input, but also include substring matches
+ * const rankedFilter = createRankedFilter<SimpleOption>((node, inputValue) => {
+ *   const text = node.textValue.toLowerCase();
+ *   const input = inputValue.toLowerCase();
+ *
+ *   if (text.startsWith(input)) return 100; // Highest score for prefix match
+ *   if (text.includes(input)) return 50;    // Lower score for substring match
+ *   return 0;                               // No match
+ * });
+ *
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={rankedFilter}
+ *   placeholder="Search..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Applies custom scoring logic to each item
+ * - Filters out items with score <= 0
+ * - Sorts remaining items by score (descending)
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Search with relevance ranking
+ * - Prioritizing certain match types (prefix vs substring)
+ * - Boosting items based on metadata (popularity, recency, etc.)
+ * - Implementing search algorithms like TF-IDF
+ *
+ * **Score Guidelines:**
+ * - Return 0 or negative for non-matches (will be filtered out)
+ * - Higher scores = better matches
+ * - Consider using score ranges (e.g., 0-100) for consistent behavior
+ */
+export function createRankedFilter<T extends object>(
+  scoreFn: (node: Node<T>, inputValue: string) => number
+): (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>> {
+  return (nodes: Iterable<Node<T>>, inputValue: string): Iterable<Node<T>> => {
+    if (!inputValue.trim()) return nodes;
+
+    const scored: Array<{ node: Node<T>; score: number }> = [];
+
+    for (const node of nodes) {
+      const score = scoreFn(node, inputValue);
+      if (score > 0) {
+        scored.push({ node, score });
+      }
+    }
+
+    // Sort by score descending
+    scored.sort((a, b) => b.score - a.score);
+
+    return scored.map((item) => item.node);
+  };
+}
+
+/**
+ * Creates a filter that matches any of multiple input terms (OR logic)
+ * Splits input by spaces and matches if any term matches
+ *
+ * @param baseFilter - The underlying filter to use for each term (defaults to filterByText)
+ * @returns A filter function that matches any term
+ *
+ * @example
+ * ```tsx
+ * const multiTermFilter = createMultiTermFilter();
+ *
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={multiTermFilter}
+ *   placeholder="Search (space-separated terms)..."
+ * />
+ * // Input "eagle bison" matches both "Bald Eagle" and "Bison"
+ * ```
+ *
+ * **Behavior:**
+ * - Splits input by whitespace
+ * - Matches if ANY term matches (OR logic)
+ * - Each term is filtered using the base filter
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Search with multiple keywords
+ * - Tag-based filtering (e.g., "react typescript")
+ * - Alternative spellings or synonyms
+ * - Flexible search where users enter multiple criteria
+ *
+ * **Note:** To require ALL terms to match (AND logic), consider chaining filters
+ * or implementing a custom filter function.
+ */
+export function createMultiTermFilter<T extends object>(
+  baseFilter: (
+    nodes: Iterable<Node<T>>,
+    inputValue: string
+  ) => Iterable<Node<T>> = filterByText
+): (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>> {
+  return (nodes: Iterable<Node<T>>, inputValue: string): Iterable<Node<T>> => {
+    if (!inputValue.trim()) return nodes;
+
+    const terms = inputValue.split(/\s+/).filter((term) => term.length > 0);
+    if (terms.length === 0) return nodes;
+
+    // Collect all matching nodes across all terms
+    const matchingKeys = new Set<React.Key>();
+
+    for (const term of terms) {
+      const filtered = baseFilter(nodes, term);
+      for (const node of filtered) {
+        matchingKeys.add(node.key);
+      }
+    }
+
+    // Return nodes that matched any term
+    const result: Node<T>[] = [];
+    for (const node of nodes) {
+      if (matchingKeys.has(node.key)) {
+        result.push(node);
+      }
+    }
+
+    return result;
+  };
+}
+
+/**
+ * Creates a section-aware filter that preserves section structure
+ * Wraps a custom filter function to work with sections, hiding empty sections
+ *
+ * @param itemFilter - Filter function to apply to individual items
+ * @returns A filter function that preserves sections and hides empty ones
+ *
+ * @example
+ * ```tsx
+ * // Using with built-in filters
+ * const sectionAwareStartsWith = createSectionAwareFilter(
+ *   (nodes, input) => filterByStartsWith(nodes, input)
+ * );
+ *
+ * <ComboBox.Root
+ *   items={sectionsWithItems}
+ *   filter={sectionAwareStartsWith}
+ * >
+ *   {(section) => (
+ *     <ComboBox.Section title={section.name}>
+ *       {section.items.map((item) => (
+ *         <ComboBox.Option key={item.id} textValue={item.name}>
+ *           {item.name}
+ *         </ComboBox.Option>
+ *       ))}
+ *     </ComboBox.Section>
+ *   )}
+ * </ComboBox.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using with custom filter logic
+ * const customSectionFilter = createSectionAwareFilter(
+ *   (nodes, input) => {
+ *     const lowerInput = input.toLowerCase();
+ *     const filtered: Node<T>[] = [];
+ *     for (const node of nodes) {
+ *       // Custom filtering logic
+ *       if (node.textValue.toLowerCase().startsWith(lowerInput)) {
+ *         filtered.push(node);
+ *       }
+ *     }
+ *     return filtered;
+ *   }
+ * );
+ * ```
+ *
+ * **Behavior:**
+ * - Applies the item filter to items within each section
+ * - Preserves section nodes in the output
+ * - Automatically hides sections that have no matching items
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Categorized combobox options (Animals → Mammals, Birds, etc.)
+ * - Grouped data where sections provide context
+ * - Multi-level hierarchies that need filtering
+ * - Search where maintaining visual grouping is important
+ *
+ * **Important Notes:**
+ * - The item filter receives ONLY item nodes (not section nodes)
+ * - Section nodes are detected by checking node.type === "section"
+ * - Empty sections are automatically excluded from results
+ * - Section order is preserved from the original collection
+ *
+ * **Performance:**
+ * - Filters items separately for each section
+ * - More efficient than flat filtering for large datasets with many sections
+ */
+export function createSectionAwareFilter<T extends object>(
+  itemFilter: (
+    nodes: Iterable<Node<T>>,
+    inputValue: string
+  ) => Iterable<Node<T>>
+): (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>> {
+  return (nodes: Iterable<Node<T>>, inputValue: string): Iterable<Node<T>> => {
+    if (!inputValue.trim()) return nodes;
+
+    const result: Node<T>[] = [];
+    let currentSection: Node<T> | null = null;
+    const currentSectionItems: Node<T>[] = [];
+
+    // Helper to flush current section if it has matching items
+    const flushSection = () => {
+      if (currentSection && currentSectionItems.length > 0) {
+        result.push(currentSection);
+        result.push(...currentSectionItems);
+      }
+      currentSectionItems.length = 0;
+    };
+
+    for (const node of nodes) {
+      // Check if this is a section node
+      if (node.type === "section") {
+        // Flush previous section if any
+        flushSection();
+        // Store this section for potential inclusion
+        currentSection = node;
+      } else {
+        // This is an item node - apply filter
+        const filteredItems = Array.from(itemFilter([node], inputValue));
+        if (filteredItems.length > 0) {
+          currentSectionItems.push(...filteredItems);
+        }
+      }
+    }
+
+    // Flush the last section
+    flushSection();
+
+    return result;
+  };
+}
diff --git a/packages/nimbus/src/components/combobox/utils/selection.spec.ts b/packages/nimbus/src/components/combobox/utils/selection.spec.ts
new file mode 100644
index 000000000..26f7c26aa
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/utils/selection.spec.ts
@@ -0,0 +1,374 @@
+import { describe, it, expect } from "vitest";
+import { normalizeSelectedKeys, denormalizeSelectedKeys } from "./selection";
+
+describe("selection utilities", () => {
+  describe("normalizeSelectedKeys", () => {
+    describe("handling undefined/null", () => {
+      it("returns empty Set for undefined", () => {
+        const result = normalizeSelectedKeys(undefined);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(0);
+      });
+
+      it("returns empty Set for null", () => {
+        const result = normalizeSelectedKeys(null);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(0);
+      });
+    });
+
+    describe("type signature validation", () => {
+      it("accepts string key", () => {
+        const result = normalizeSelectedKeys("key1");
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(1);
+      });
+
+      it("accepts number key", () => {
+        const result = normalizeSelectedKeys(42);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(1);
+      });
+
+      it("accepts array of keys", () => {
+        const result = normalizeSelectedKeys(["key1", "key2"]);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(2);
+      });
+
+      it("accepts undefined", () => {
+        const result = normalizeSelectedKeys(undefined);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(0);
+      });
+
+      it("accepts null", () => {
+        const result = normalizeSelectedKeys(null);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(0);
+      });
+    });
+
+    describe("handling single key", () => {
+      it("converts single string key to Set", () => {
+        const result = normalizeSelectedKeys("single-key");
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(1);
+        expect(result.has("single-key")).toBe(true);
+      });
+
+      it("converts single number key to Set", () => {
+        const result = normalizeSelectedKeys(42);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(1);
+        expect(result.has(42)).toBe(true);
+      });
+
+      it("treats zero as falsy (returns empty Set)", () => {
+        // Note: 0 is falsy in JavaScript, so it's treated as "no selection"
+        const result = normalizeSelectedKeys(0);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(0);
+      });
+
+      it("treats empty string as falsy (returns empty Set)", () => {
+        // Note: "" is falsy in JavaScript, so it's treated as "no selection"
+        const result = normalizeSelectedKeys("");
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(0);
+      });
+    });
+
+    describe("handling array of keys", () => {
+      it("converts array of strings to Set", () => {
+        const result = normalizeSelectedKeys(["key1", "key2", "key3"]);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(3);
+        expect(result.has("key1")).toBe(true);
+        expect(result.has("key2")).toBe(true);
+        expect(result.has("key3")).toBe(true);
+      });
+
+      it("converts array of numbers to Set", () => {
+        const result = normalizeSelectedKeys([1, 2, 3]);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(3);
+        expect(result.has(1)).toBe(true);
+        expect(result.has(2)).toBe(true);
+        expect(result.has(3)).toBe(true);
+      });
+
+      it("converts array of mixed types to Set", () => {
+        const result = normalizeSelectedKeys(["key1", 42, "key2"]);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(3);
+        expect(result.has("key1")).toBe(true);
+        expect(result.has(42)).toBe(true);
+        expect(result.has("key2")).toBe(true);
+      });
+
+      it("handles empty array", () => {
+        const result = normalizeSelectedKeys([]);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(0);
+      });
+
+      it("removes duplicates from array", () => {
+        const result = normalizeSelectedKeys(["key1", "key2", "key1"]);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(2);
+        expect(result.has("key1")).toBe(true);
+        expect(result.has("key2")).toBe(true);
+      });
+
+      it("handles array with single element", () => {
+        const result = normalizeSelectedKeys(["single"]);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(1);
+        expect(result.has("single")).toBe(true);
+      });
+    });
+
+    describe("edge cases", () => {
+      it("handles large arrays efficiently", () => {
+        const largeArray = Array.from({ length: 1000 }, (_, i) => `key-${i}`);
+        const result = normalizeSelectedKeys(largeArray);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(1000);
+        expect(result.has("key-0")).toBe(true);
+        expect(result.has("key-999")).toBe(true);
+      });
+
+      it("handles negative numbers", () => {
+        const result = normalizeSelectedKeys([-1, -42]);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(2);
+        expect(result.has(-1)).toBe(true);
+        expect(result.has(-42)).toBe(true);
+      });
+
+      it("handles special string characters", () => {
+        const result = normalizeSelectedKeys([
+          "key@special",
+          "key#hash",
+          "key$dollar",
+        ]);
+        expect(result).toBeInstanceOf(Set);
+        expect(result.size).toBe(3);
+        expect(result.has("key@special")).toBe(true);
+      });
+    });
+  });
+
+  describe("denormalizeSelectedKeys", () => {
+    describe("basic conversion", () => {
+      it("converts empty Set to empty array", () => {
+        const result = denormalizeSelectedKeys(new Set());
+        expect(Array.isArray(result)).toBe(true);
+        expect(result).toHaveLength(0);
+      });
+
+      it("converts Set with single string key to array", () => {
+        const result = denormalizeSelectedKeys(new Set(["key1"]));
+        expect(Array.isArray(result)).toBe(true);
+        expect(result).toHaveLength(1);
+        expect(result[0]).toBe("key1");
+      });
+
+      it("converts Set with single number key to array", () => {
+        const result = denormalizeSelectedKeys(new Set([42]));
+        expect(Array.isArray(result)).toBe(true);
+        expect(result).toHaveLength(1);
+        expect(result[0]).toBe(42);
+      });
+
+      it("converts Set with multiple keys to array", () => {
+        const result = denormalizeSelectedKeys(
+          new Set(["key1", "key2", "key3"])
+        );
+        expect(Array.isArray(result)).toBe(true);
+        expect(result).toHaveLength(3);
+        expect(result).toContain("key1");
+        expect(result).toContain("key2");
+        expect(result).toContain("key3");
+      });
+
+      it("converts Set with mixed key types to array", () => {
+        const result = denormalizeSelectedKeys(new Set(["key1", 42, "key2"]));
+        expect(Array.isArray(result)).toBe(true);
+        expect(result).toHaveLength(3);
+        expect(result).toContain("key1");
+        expect(result).toContain(42);
+        expect(result).toContain("key2");
+      });
+    });
+
+    describe("return value characteristics", () => {
+      it("always returns an array (not single value)", () => {
+        const result = denormalizeSelectedKeys(new Set(["single"]));
+        expect(Array.isArray(result)).toBe(true);
+        expect(result).toEqual(["single"]);
+      });
+
+      it("returns a new array (not a reference)", () => {
+        const inputSet = new Set(["key1"]);
+        const result1 = denormalizeSelectedKeys(inputSet);
+        const result2 = denormalizeSelectedKeys(inputSet);
+        expect(result1).not.toBe(result2);
+        expect(result1).toEqual(result2);
+      });
+
+      it("preserves order from Set iteration", () => {
+        // Sets preserve insertion order
+        const inputSet = new Set(["first", "second", "third"]);
+        const result = denormalizeSelectedKeys(inputSet);
+        expect(result).toEqual(["first", "second", "third"]);
+      });
+    });
+
+    describe("edge cases", () => {
+      it("handles Set with zero as key", () => {
+        const result = denormalizeSelectedKeys(new Set([0]));
+        expect(result).toHaveLength(1);
+        expect(result[0]).toBe(0);
+      });
+
+      it("handles Set with empty string as key", () => {
+        const result = denormalizeSelectedKeys(new Set([""]));
+        expect(result).toHaveLength(1);
+        expect(result[0]).toBe("");
+      });
+
+      it("handles Set with negative numbers", () => {
+        const result = denormalizeSelectedKeys(new Set([-1, -42]));
+        expect(result).toHaveLength(2);
+        expect(result).toContain(-1);
+        expect(result).toContain(-42);
+      });
+
+      it("handles large Sets efficiently", () => {
+        const largeSet = new Set(
+          Array.from({ length: 1000 }, (_, i) => `key-${i}`)
+        );
+        const result = denormalizeSelectedKeys(largeSet);
+        expect(result).toHaveLength(1000);
+        expect(result[0]).toBe("key-0");
+        expect(result[999]).toBe("key-999");
+      });
+    });
+  });
+
+  describe("round-trip conversion", () => {
+    it("normalizing then denormalizing preserves keys", () => {
+      const original = ["key1", "key2", "key3"];
+      const normalized = normalizeSelectedKeys(original);
+      const denormalized = denormalizeSelectedKeys(normalized);
+
+      expect(denormalized).toHaveLength(3);
+      expect(denormalized).toContain("key1");
+      expect(denormalized).toContain("key2");
+      expect(denormalized).toContain("key3");
+    });
+
+    it("handles single key round-trip", () => {
+      const original = "single-key";
+      const normalized = normalizeSelectedKeys(original);
+      const denormalized = denormalizeSelectedKeys(normalized);
+
+      expect(denormalized).toHaveLength(1);
+      expect(denormalized[0]).toBe("single-key");
+    });
+
+    it("handles empty round-trip", () => {
+      const original = undefined;
+      const normalized = normalizeSelectedKeys(original);
+      const denormalized = denormalizeSelectedKeys(normalized);
+
+      expect(denormalized).toHaveLength(0);
+    });
+
+    it("handles array to Set round-trip", () => {
+      const original = ["key1", "key2"];
+      const normalized = normalizeSelectedKeys(original);
+      const denormalized = denormalizeSelectedKeys(normalized);
+
+      expect(denormalized).toHaveLength(2);
+      expect(denormalized).toContain("key1");
+      expect(denormalized).toContain("key2");
+    });
+
+    it("removes duplicates during round-trip", () => {
+      const original = ["key1", "key2", "key1", "key2"];
+      const normalized = normalizeSelectedKeys(original);
+      const denormalized = denormalizeSelectedKeys(normalized);
+
+      expect(denormalized).toHaveLength(2);
+      expect(denormalized).toContain("key1");
+      expect(denormalized).toContain("key2");
+    });
+
+    it("preserves mixed types during round-trip", () => {
+      const original = ["key1", 42, "key2", 0];
+      const normalized = normalizeSelectedKeys(original);
+      const denormalized = denormalizeSelectedKeys(normalized);
+
+      expect(denormalized).toHaveLength(4);
+      expect(denormalized).toContain("key1");
+      expect(denormalized).toContain(42);
+      expect(denormalized).toContain("key2");
+      expect(denormalized).toContain(0);
+    });
+  });
+
+  describe("integration with typical use cases", () => {
+    it("handles single selection mode (one key)", () => {
+      // User selects a single item
+      const selected = "item-1";
+      const normalized = normalizeSelectedKeys(selected);
+
+      expect(normalized.size).toBe(1);
+      expect(normalized.has("item-1")).toBe(true);
+
+      // Convert back for API response
+      const forApi = denormalizeSelectedKeys(normalized);
+      expect(forApi).toEqual(["item-1"]);
+    });
+
+    it("handles multiple selection mode (array of keys)", () => {
+      // User selects multiple items
+      const selected = ["item-1", "item-3", "item-5"];
+      const normalized = normalizeSelectedKeys(selected);
+
+      expect(normalized.size).toBe(3);
+
+      // Convert back for API response
+      const forApi = denormalizeSelectedKeys(normalized);
+      expect(forApi).toHaveLength(3);
+      expect(forApi).toContain("item-1");
+      expect(forApi).toContain("item-3");
+      expect(forApi).toContain("item-5");
+    });
+
+    it("handles no selection (undefined)", () => {
+      const selected = undefined;
+      const normalized = normalizeSelectedKeys(selected);
+
+      expect(normalized.size).toBe(0);
+
+      // Convert back for API response
+      const forApi = denormalizeSelectedKeys(normalized);
+      expect(forApi).toEqual([]);
+    });
+
+    it("converts selection to array for onChange callback", () => {
+      // Component needs to convert internal Set to array for onChange callback
+      const internalSelection = new Set(["item-2", "item-4"]);
+
+      // Convert for onChange callback
+      const forCallback = denormalizeSelectedKeys(internalSelection);
+      expect(forCallback).toHaveLength(2);
+      expect(forCallback).toContain("item-2");
+      expect(forCallback).toContain("item-4");
+    });
+  });
+});
diff --git a/packages/nimbus/src/components/combobox/utils/selection.ts b/packages/nimbus/src/components/combobox/utils/selection.ts
new file mode 100644
index 000000000..967fb6546
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/utils/selection.ts
@@ -0,0 +1,19 @@
+import { type Key } from "react-stately";
+/**
+ * Normalize selectedKeys to Set format
+ */
+export const normalizeSelectedKeys = (
+  keys: Key | Key[] | undefined | null
+): Set<Key> => {
+  if (!keys) return new Set();
+  if (keys instanceof Set) return keys;
+  return new Set(Array.isArray(keys) ? keys : [keys]);
+};
+
+/**
+ * Denormalize selectedKeys from Set to array
+ * Always returns an array regardless of selection mode for simpler API
+ */
+export const denormalizeSelectedKeys = (keys: Set<Key>): Key[] => {
+  return Array.from(keys);
+};
diff --git a/packages/nimbus/src/components/combobox/utils/test-data.ts b/packages/nimbus/src/components/combobox/utils/test-data.ts
new file mode 100644
index 000000000..6117b9918
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/utils/test-data.ts
@@ -0,0 +1,11 @@
+/** most basic option */
+export type SimpleOption = { name: string; id: number };
+
+export const simpleOptions: SimpleOption[] = [
+  { id: 1, name: "Koala" },
+  { id: 2, name: "Kangaroo" },
+  { id: 3, name: "Platypus" },
+  { id: 4, name: "Bald Eagle with a very long name hooray" },
+  { id: 5, name: "Bison" },
+  { id: 6, name: "Skunk" },
+];
diff --git a/packages/nimbus/src/components/combobox/utils/test-utils.tsx b/packages/nimbus/src/components/combobox/utils/test-utils.tsx
new file mode 100644
index 000000000..dd85c241e
--- /dev/null
+++ b/packages/nimbus/src/components/combobox/utils/test-utils.tsx
@@ -0,0 +1,176 @@
+import { useState, useEffect } from "react";
+import { Badge, Box, Image, Stack, Text } from "@commercetools/nimbus";
+import { ComboBox } from "../combobox";
+import type { ComboBoxRootProps } from "../combobox.types";
+import { defaultGetTextValue } from "./collection";
+
+export function ComposedComboBox<T extends object>(
+  props: ComboBoxRootProps<T>
+) {
+  return (
+    <ComboBox.Root {...props}>
+      <ComboBox.Trigger />
+      <ComboBox.Popover>
+        <ComboBox.ListBox>
+          {(item: T) => (
+            <ComboBox.Option>{defaultGetTextValue(item)}</ComboBox.Option>
+          )}
+        </ComboBox.ListBox>
+      </ComboBox.Popover>
+    </ComboBox.Root>
+  );
+}
+
+// ============================================================
+// ASYNC LOADING - Pokemon API types, Utils, and Option Component
+// ============================================================
+/** Initial Pokemomn API return type */
+export type Pokemon = {
+  name: string;
+  url: string;
+};
+/** Pokemon API Details return type */
+export type PokemonDetails = {
+  id: number;
+  name: string;
+  sprites: {
+    front_default: string;
+  };
+  types: Array<{
+    type: {
+      name: string;
+    };
+  }>;
+  height: number;
+  weight: number;
+  base_experience: number;
+};
+
+/**
+ * Reusable Pokemon option component that displays detailed information.
+ * Fetches full Pokemon details on mount and displays sprite, name, types, and stats.
+ */
+export const PokemonOption = ({ pokemon }: { pokemon: Pokemon }) => {
+  const [details, setDetails] = useState<PokemonDetails | null>(null);
+
+  // Fetch detailed Pokemon data
+  useEffect(() => {
+    const fetchDetails = async () => {
+      try {
+        const response = await fetch(pokemon.url);
+        const data = await response.json();
+        setDetails(data);
+      } catch (error) {
+        console.error(`Failed to fetch details for ${pokemon.name}:`, error);
+      }
+    };
+    fetchDetails();
+  }, [pokemon.url]);
+
+  if (!details) {
+    return (
+      <Stack direction="row" gap="300" alignItems="center" padding="200">
+        <Text fontSize="350" textTransform="capitalize">
+          {pokemon.name}
+        </Text>
+      </Stack>
+    );
+  }
+
+  // Get type colors for badges
+  const getTypeColor = (typeName: string) => {
+    const typeColors: Record<string, string> = {
+      normal: "gray",
+      fire: "red",
+      water: "blue",
+      electric: "yellow",
+      grass: "green",
+      ice: "cyan",
+      fighting: "orange",
+      poison: "purple",
+      ground: "amber",
+      flying: "sky",
+      psychic: "pink",
+      bug: "lime",
+      rock: "bronze",
+      ghost: "violet",
+      dragon: "indigo",
+      dark: "blackAlpha",
+      steel: "gray",
+      fairy: "pink",
+    };
+    return typeColors[typeName] || "gray";
+  };
+
+  return (
+    <Stack
+      direction="row"
+      gap="300"
+      alignItems="center"
+      width="100%"
+      flexWrap="wrap"
+    >
+      {/* Pokemon Sprite - Fixed size container ensures consistent dimensions */}
+      {details.sprites.front_default && (
+        <Box
+          width="1100"
+          height="1100"
+          flexShrink={0}
+          display="flex"
+          alignItems="center"
+          justifyContent="center"
+        >
+          <Image
+            width="100%"
+            height="100%"
+            objectFit="contain"
+            src={details.sprites.front_default}
+            alt={details.name}
+          />
+        </Box>
+      )}
+
+      {/* Pokemon Info */}
+      <Stack direction="column" gap="200" flex="1" minWidth={0}>
+        {/* Name and ID */}
+        <Stack direction="row" gap="100" alignItems="center">
+          <Text fontSize="400" fontWeight="600" textTransform="capitalize">
+            {details.name}
+          </Text>
+          <Text fontSize="350" color="fg.muted">
+            #{details.id.toString().padStart(3, "0")}
+          </Text>
+        </Stack>
+
+        {/* Types */}
+        <Stack direction="row" gap="50" flexWrap="wrap">
+          {details.types.map((typeInfo) => (
+            <Badge
+              key={typeInfo.type.name}
+              colorPalette={getTypeColor(typeInfo.type.name)}
+              size="2xs"
+            >
+              {typeInfo.type.name}
+            </Badge>
+          ))}
+        </Stack>
+      </Stack>
+
+      {/* Stats */}
+      <Stack
+        direction="column"
+        justifySelf="flex-end"
+        alignItems="flex-start"
+        gap="0"
+        mt="auto"
+      >
+        <Text fontSize="300" lineHeight="400" color="fg.muted">
+          H: {(details.height / 10).toFixed(1)}m
+        </Text>
+        <Text fontSize="300" lineHeight="400" color="fg.muted">
+          W: {(details.weight / 10).toFixed(1)}kg
+        </Text>
+      </Stack>
+    </Stack>
+  );
+};
diff --git a/packages/nimbus/src/components/date-picker/date-picker.tsx b/packages/nimbus/src/components/date-picker/date-picker.tsx
index 097da0ba5..48ac37ea0 100644
--- a/packages/nimbus/src/components/date-picker/date-picker.tsx
+++ b/packages/nimbus/src/components/date-picker/date-picker.tsx
@@ -64,7 +64,6 @@ export const DatePicker = (props: DatePickerProps) => {
                 hourCycle={hourCycle}
                 trailingElement={
                   <Box>
-                    {/* @ts-expect-error react aria is adding the aria-label prop */}
                     <IconButton
                       variant="ghost"
                       size={overlayButtonSize}
@@ -72,7 +71,6 @@ export const DatePicker = (props: DatePickerProps) => {
                     >
                       <Close />
                     </IconButton>
-                    {/* @ts-expect-error react aria is adding the aria-label prop */}
                     <IconButton
                       variant="ghost"
                       size={overlayButtonSize}
diff --git a/packages/nimbus/src/components/draggable-list/components/draggable-list.item.tsx b/packages/nimbus/src/components/draggable-list/components/draggable-list.item.tsx
index e48c9ea90..ede77d20f 100644
--- a/packages/nimbus/src/components/draggable-list/components/draggable-list.item.tsx
+++ b/packages/nimbus/src/components/draggable-list/components/draggable-list.item.tsx
@@ -41,7 +41,6 @@ export const DraggableListItem = <T extends DraggableListItemData>({
         {({ allowsDragging, selectionBehavior, selectionMode }) => (
           <>
             {allowsDragging && (
-              // @ts-expect-error slot="drag" handles adding the required props
               <IconButton
                 slot="drag"
                 size="2xs"
diff --git a/packages/nimbus/src/components/drawer/index.ts b/packages/nimbus/src/components/drawer/index.ts
index 6acdf7d4f..1b0b7f6d0 100644
--- a/packages/nimbus/src/components/drawer/index.ts
+++ b/packages/nimbus/src/components/drawer/index.ts
@@ -1,4 +1,6 @@
 export * from "./drawer";
+
+// Re-export types for external usage
 export type * from "./drawer.types";
 
 // Re-export slot types for advanced usage
diff --git a/packages/nimbus/src/components/icon-button/icon-button.tsx b/packages/nimbus/src/components/icon-button/icon-button.tsx
index d84ff0c27..84803854d 100644
--- a/packages/nimbus/src/components/icon-button/icon-button.tsx
+++ b/packages/nimbus/src/components/icon-button/icon-button.tsx
@@ -1,4 +1,4 @@
-import { useRef } from "react";
+import { useRef, useEffect } from "react";
 import { useObjectRef } from "react-aria";
 import { mergeRefs } from "@chakra-ui/react";
 import type { IconButtonProps } from "./icon-button.types";
@@ -18,6 +18,34 @@ export const IconButton = (props: IconButtonProps) => {
   const localRef = useRef<HTMLButtonElement>(null);
   const ref = useObjectRef(mergeRefs(localRef, forwardedRef));
 
+  // Runtime accessibility check
+  // Use setTimeout to defer check until after React Aria applies context props
+  useEffect(() => {
+    if (process.env.NODE_ENV !== "production") {
+      const timeoutId = setTimeout(() => {
+        const element = localRef.current;
+        if (element) {
+          const hasAriaLabel =
+            element.hasAttribute("aria-label") ||
+            element.hasAttribute("aria-labelledby");
+
+          // Skip warning if component is using slot-based context (Button will handle it)
+          const isUsingSlot = element.hasAttribute("slot");
+
+          if (!hasAriaLabel && !isUsingSlot) {
+            console.warn(
+              "Nimbus: IconButton requires an accessible label. " +
+                "Either provide an 'aria-label' prop or use within a component that provides it via context (e.g., slot=\"clear\" in ComboBox).",
+              element
+            );
+          }
+        }
+      }, 0);
+
+      return () => clearTimeout(timeoutId);
+    }
+  }, [props["aria-label"], restProps.slot]);
+
   return (
     <Button px={0} py={0} {...restProps} ref={ref}>
       {children}
diff --git a/packages/nimbus/src/components/icon-button/icon-button.types.tsx b/packages/nimbus/src/components/icon-button/icon-button.types.tsx
index c76b8319c..7cbe33f60 100644
--- a/packages/nimbus/src/components/icon-button/icon-button.types.tsx
+++ b/packages/nimbus/src/components/icon-button/icon-button.types.tsx
@@ -6,9 +6,21 @@ import { type ButtonProps } from "../button/button.types";
 
 export type IconButtonProps = ButtonProps & {
   /**
-   * Required accessible label explaining the intended action
+   * Accessible label explaining the intended action.
+   *
+   * Required unless provided via React Aria's ButtonContext (when using `slot` attribute).
+   * A runtime warning will be logged if neither the prop nor context provides an aria-label.
+   *
+   * @example
+   * ```tsx
+   * // Direct usage - aria-label required
+   * <IconButton aria-label="Delete item"><Icons.Delete /></IconButton>
+   *
+   * // With slot - aria-label provided by context
+   * <IconButton slot="clear"><Icons.Close /></IconButton>
+   * ```
    */
-  "aria-label": string;
+  "aria-label"?: string;
   /**
    * Ref forwarding to the button element
    */
diff --git a/packages/nimbus/src/components/popover/popover.slots.tsx b/packages/nimbus/src/components/popover/popover.slots.tsx
index 652c8de72..f9f804d17 100644
--- a/packages/nimbus/src/components/popover/popover.slots.tsx
+++ b/packages/nimbus/src/components/popover/popover.slots.tsx
@@ -1,11 +1,12 @@
 import { createRecipeContext } from "@chakra-ui/react";
 import { Popover as RaPopover } from "react-aria-components";
-import type { SlotComponent } from "@/type-utils";
-import type { PopoverProps } from "./popover.types";
+import type { PopoverProps, PopoverComponent } from "./popover.types";
 
 const { withContext } = createRecipeContext({
   key: "popover",
 });
 
-export const PopoverRootSlot: SlotComponent<typeof RaPopover, PopoverProps> =
-  withContext<typeof RaPopover, PopoverProps>(RaPopover);
+export const PopoverRootSlot: PopoverComponent = withContext<
+  typeof RaPopover,
+  PopoverProps
+>(RaPopover);
diff --git a/packages/nimbus/src/components/popover/popover.tsx b/packages/nimbus/src/components/popover/popover.tsx
index 2e0ad9c3a..2c6b80789 100644
--- a/packages/nimbus/src/components/popover/popover.tsx
+++ b/packages/nimbus/src/components/popover/popover.tsx
@@ -8,10 +8,8 @@ import type { PopoverProps } from "./popover.types";
  *
  * Note this component is only used internally.
  */
-export const Popover = (props: PopoverProps) => {
-  const { children, ...rest } = props;
-
-  return <PopoverRootSlot {...rest}>{children}</PopoverRootSlot>;
+export const Popover = ({ children, ...props }: PopoverProps) => {
+  return <PopoverRootSlot {...props}>{children}</PopoverRootSlot>;
 };
 
 Popover.displayName = "Popover";
diff --git a/packages/nimbus/src/components/popover/popover.types.ts b/packages/nimbus/src/components/popover/popover.types.ts
index 2566be523..a14a97b94 100644
--- a/packages/nimbus/src/components/popover/popover.types.ts
+++ b/packages/nimbus/src/components/popover/popover.types.ts
@@ -1,9 +1,11 @@
 import type { PopoverProps as RaPopoverProps } from "react-aria-components";
+import { Popover as RaPopover } from "react-aria-components";
 import type {
   HTMLChakraProps,
   RecipeProps,
   UnstyledProp,
 } from "@chakra-ui/react";
+import type { FC } from "react";
 
 // ============================================================
 // RECIPE PROPS
@@ -21,4 +23,15 @@ export type PopoverRootSlotProps = HTMLChakraProps<"div", PopoverRecipeProps>;
 // MAIN PROPS
 // ============================================================
 
-export type PopoverProps = RaPopoverProps & PopoverRootSlotProps;
+export type PopoverProps = RaPopoverProps &
+  Omit<PopoverRootSlotProps, keyof RaPopoverProps> & {
+    /**
+     * Reference to the popover element
+     */
+    ref?: React.Ref<typeof RaPopover>;
+  };
+
+/**
+ * Type signature for the Popover component.
+ */
+export type PopoverComponent = FC<PopoverProps>;
diff --git a/packages/nimbus/src/components/range-calendar/components/range-calendar.header.tsx b/packages/nimbus/src/components/range-calendar/components/range-calendar.header.tsx
index 147f50855..e9d89b3bf 100644
--- a/packages/nimbus/src/components/range-calendar/components/range-calendar.header.tsx
+++ b/packages/nimbus/src/components/range-calendar/components/range-calendar.header.tsx
@@ -39,7 +39,6 @@ export const RangeCalendarHeader = () => {
           <VisuallyHidden>
             <Heading />
           </VisuallyHidden>
-          {/* @ts-expect-error - custom-context will add aria-label via the "slot" prop */}
           <IconButton
             slot={showRangeLabel ? "previous" : "previous-month"}
             size="xs"
@@ -57,7 +56,6 @@ export const RangeCalendarHeader = () => {
             aria-hidden="true"
             slot={showRangeLabel ? "monthRange" : "month"}
           />
-          {/* @ts-expect-error - custom-context will add aria-label via the "slot" prop */}
           <IconButton
             slot={showRangeLabel ? "next" : "next-month"}
             size="xs"
@@ -69,7 +67,6 @@ export const RangeCalendarHeader = () => {
         </Stack>
         <Box flexGrow="1" />
         <Stack direction="row" alignItems="center">
-          {/* @ts-expect-error - custom-context will add aria-label via the "slot" prop */}
           <IconButton
             slot="previous-year"
             size="xs"
@@ -87,7 +84,6 @@ export const RangeCalendarHeader = () => {
             aria-hidden="true"
             slot="year"
           />
-          {/* @ts-expect-error - custom-context will add aria-label via the "slot" prop */}
           <IconButton
             slot="next-year"
             size="xs"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e2e1062c5..2f18ba2f8 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -55,6 +55,9 @@ catalogs:
     '@preconstruct/cli':
       specifier: ^2.8.12
       version: 2.8.12
+    '@react-types/shared':
+      specifier: ^3.32.1
+      version: 3.32.1
     '@storybook/addon-a11y':
       specifier: ^10.1.11
       version: 10.1.11
@@ -405,6 +408,9 @@ importers:
       react-router-dom:
         specifier: ^7.11.0
         version: 7.11.0(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
+      react-stately:
+        specifier: 3.42.0
+        version: 3.42.0(react@19.2.0)
       react-syntax-highlighter:
         specifier: ^15.6.6
         version: 15.6.6(react@19.2.0)
@@ -426,6 +432,9 @@ importers:
       to-vfile:
         specifier: ^8.0.0
         version: 8.0.0
+      use-debounce:
+        specifier: ^10.0.0
+        version: 10.0.6(react@19.2.0)
       vite-plugin-markdown:
         specifier: ^2.2.0
         version: 2.2.0(vite@7.3.0(@types/node@24.10.1)(terser@5.44.0)(tsx@4.21.0)(yaml@2.8.1))
@@ -535,6 +544,9 @@ importers:
       react-use:
         specifier: ^17.5.1
         version: 17.6.0(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
+      use-debounce:
+        specifier: ^10.0.0
+        version: 10.0.6(react@19.2.0)
     devDependencies:
       '@chakra-ui/cli':
         specifier: catalog:react
@@ -554,6 +566,9 @@ importers:
       '@react-aria/optimize-locales-plugin':
         specifier: catalog:react
         version: 1.1.5
+      '@react-types/shared':
+        specifier: catalog:tooling
+        version: 3.32.1(react@19.2.0)
       '@storybook/addon-a11y':
         specifier: catalog:tooling
         version: 10.1.11(storybook@10.1.11(@testing-library/dom@10.4.1)(prettier@3.7.4)(react-dom@19.2.0(react@19.2.0))(react@19.2.0))
@@ -6660,6 +6675,12 @@ packages:
     resolution: {integrity: sha512-oCwdVC7mTuWiPyjLUz/COz5TLk6wgp0RCsN+wHZ2Ekneac9w8uuV0njcbbie2ME+Vs+d6duwmYuR3HgQXs1fOg==}
     engines: {node: '>= 0.4'}
 
+  use-debounce@10.0.6:
+    resolution: {integrity: sha512-C5OtPyhAZgVoteO9heXMTdW7v/IbFI+8bSVKYCJrSmiWWCLsbUxiBSp4t9v0hNBTGY97bT72ydDIDyGSFWfwXg==}
+    engines: {node: '>= 16.0.0'}
+    peerDependencies:
+      react: '*'
+
   use-editable@2.3.3:
     resolution: {integrity: sha512-7wVD2JbfAFJ3DK0vITvXBdpd9JAz5BcKAAolsnLBuBn6UDDwBGuCIAGvR3yA2BNKm578vAMVHFCWaOcA+BhhiA==}
     peerDependencies:
@@ -14545,6 +14566,10 @@ snapshots:
       punycode: 1.4.1
       qs: 6.14.0
 
+  use-debounce@10.0.6(react@19.2.0):
+    dependencies:
+      react: 19.2.0
+
   use-editable@2.3.3(react@19.2.0):
     dependencies:
       react: 19.2.0
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 8f939964a..ad41d477c 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -15,6 +15,7 @@ catalogs:
     "@babel/runtime": ^7.28.4
     "@babel/preset-typescript": ^7.28.5
     "@eslint/js": ^9.39.2
+    "@react-types/shared": ^3.32.1
     eslint: ^9.39.2
     eslint-config-prettier: ^10.1.8
     eslint-plugin-prettier: ^5.5.4