CRAFT-1822 | combobox refactor (#630)

* feat(combobox refactor): generate refactor plan

* feat(combobox refactor): update refactor plan

* feat(combobox refactor): implement refactor of components except for their styling

* feat(combobox refactor): single select selects and filters, context and collection are now being set in a usable way

* feat(combobox): keyboard interactions now work as expected, multiselect is working with tag group, filtering is working - basic functionality using single context achieved

* feat(combobox refactor): at this point, the functionality and styling are looking good, still needs testing, etc tho

* feat(combobox refactor): ensure async and creatable options work correctly and add a few basic tests, add a set of custom filters for use with combobox and test them, update comments and documentation, update testing plan, update readme, etc

* feat(combobox refactor): clear button conditionally renders, and some other stuff

* chore(changeset): add changeset

* feat(combobox context): clear react-aria contexts in combobox so that child components in trigger do not receive external values

* chore(nimbus): `ComboBox` unit tests and bugfixes (#818)

* chore(nimbus): combobox - layout structure tests

* chore(nimbus): combobox - multi-select tag display tests

* chore(nimbus): combobox - input field behavior tests

* chore(nimbus): combobox - button visibility and behavior tests

* chore(nimbus): combobox - focus behavior tests

* chore(nimbus): notes

* chore(nimbus): combobox - keyboard navigation tests

* chore(nimbus): combobox - menu opening and closing tests

* chore(nimbus): combobox - option selection tests

* chore(nimbus): combobox - clear button functionality tests

* chore(nimbus): combobox - multi and single select behavior tests

* chore(nimbus): combobox - selection persistence tests

* chore(nimbus): combobox - basic text filtering tests

* chore(nimbus): combobox - custom filter tests

* chore(nimbus): combobox - empty state handling tests

* chore(nimbus): combobox - basic custom option creation tests

* chore(nimbus): combobox - single select creation tests

* chore(nimbus): combobox - a11y keyboard tests

* chore(nimbus): combobox - a11y relationship tests

* chore(nimbus): combobox - visual variant tests

* chore(nimbus): combobox - state visual tests

* chore(docs): remove temporary testing plan file

* chore(combobox): revisions

* feat(combobox option): options in listbox don't focus on hover

* chore(combobox): add test for modal integration

* chore(dialog): squelch button context for children

* Revert "chore(dialog): squelch button context for children"

This reverts commit af7f799.

* chore(combobox): edit tests after rebase

* chore(combobox): await in test, fix

---------

Co-authored-by: Byron Wall <[email protected]>

* chore(docs): adjust code examples

* chore: update pnpm-lock.yaml after rebase

---------

Co-authored-by: Jai Kamat <[email protected]>
Co-authored-by: Valorie <[email protected]>

Author: 3 people

.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.

.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

.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": {}
     }
   }
 }

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"

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) => {

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",

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"