@commercetools/nimbus-mcp 0.1.0 → 2.10.0

package/data/docs/routes/components-inputs-search-input.json

@@ -0,0 +1,588 @@
+{
+  "meta": {
+    "id": "Components-SearchInput",
+    "title": "Search input",
+    "exportName": "SearchInput",
+    "description": "Allows users to discover and filter content by entering text to help users find relevant information efficiently.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/search-input/search-input.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "Search input"
+    ],
+    "route": "components/inputs/search-input",
+    "tags": [
+      "component",
+      "search",
+      "input"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Visual Options",
+        "href": "#visual-options",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Appearance",
+        "href": "#appearance",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nSearch inputs provide a dedicated text field for users to enter keywords or phrases to query and retrieve matching data or content. They are essential for navigating large amounts of information.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria SearchField](https://react-spectrum.adobe.com/react-aria/SearchField.html)\n[Figma Library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=6005-17482&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual Options\n\n#### Size\n\nThe medium size of the SearchInput is default, the small size is meant for more compact uses.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <SearchInput size=\"md\" placeholder=\"Search...\" />\n    <SearchInput size=\"sm\" placeholder=\"Search...\" />\n  </Stack>\n)\n```\n\n### Appearance\n\nAllows switching the visual style between solid and ghost appearance.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <SearchInput variant=\"solid\" placeholder=\"Search...\" />\n    <SearchInput variant=\"ghost\" placeholder=\"Search...\" />\n  </Stack>\n)\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nSearch inputs provide a dedicated text field for users to enter keywords or phrases to query and retrieve matching data or content. They are essential for navigating large amounts of information.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria SearchField](https://react-spectrum.adobe.com/react-aria/SearchField.html)\n[Figma Library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=6005-17482&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual Options\n\n#### Size\n\nThe medium size of the SearchInput is default, the small size is meant for more compact uses.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <SearchInput size=\"md\" placeholder=\"Search...\" />\n    <SearchInput size=\"sm\" placeholder=\"Search...\" />\n  </Stack>\n)\n```\n\n### Appearance\n\nAllows switching the visual style between solid and ghost appearance.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <SearchInput variant=\"solid\" placeholder=\"Search...\" />\n    <SearchInput variant=\"ghost\" placeholder=\"Search...\" />\n  </Stack>\n)\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual Options",
+          "href": "#visual-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Appearance",
+          "href": "#appearance",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => (\n  <SearchInput\n    placeholder=\"Search products...\"\n    aria-label=\"Search\"\n  />\n);\n```\n\n### Accessibility standards\n\n- Always provide a visible label or clear `aria-label` for the search input.\n- Use `type=\"search\"` or `role=\"search\"` to identify the search functionality to\n  assistive technologies.\n- Ensure sufficient color contrast for all elements (text, borders, icons, focus\n  indicators).\n- Clearly indicate the focused state with visible focus indicators.\n- Support keyboard navigation using Tab to focus and Enter to submit search.\n- Provide clear feedback when search results are loading or no results are\n  found.\n- Announce search results and status changes to screen readers using ARIA live\n  regions.\n- Include a clear button to reset or clear the search input.\n- If search suggestions appear, ensure they are keyboard accessible and properly\n  announced.\n\n### Resources\n\n- [W3C ARIA Authoring Practices Guide (APG) - Search](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/search.html)\n- [Adobe Spectrum Design System](https://spectrum.adobe.com/page/search/)\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { SearchInput, type SearchInputProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation uses uncontrolled mode:\n\n```jsx live-dev\nconst App = () => (\n  <SearchInput placeholder=\"Search...\" />\n)\n```\n\n## Usage examples\n\n### Size options\n\nThe `sm` and `md` size variants are available to match your interface density:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <SearchInput size=\"sm\" placeholder=\"Small search\" />\n    <SearchInput size=\"md\" placeholder=\"Medium search (default)\" />\n  </Stack>\n)\n```\n\n### Visual variants\n\nChoose between `solid` and `ghost` variants to match your design context:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <SearchInput variant=\"solid\" placeholder=\"Solid variant (default)\" />\n    <SearchInput variant=\"ghost\" placeholder=\"Ghost variant\" />\n  </Stack>\n)\n```\n\n### Clear button behavior\n\nSearchInput includes a built-in clear button that automatically appears when the input has a value:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <SearchInput\n        value={value}\n        onChange={setValue}\n        placeholder=\"Type to see clear button...\"\n      />\n      <Text fontSize=\"sm\">\n        Current value: {value || '(empty)'}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n**Behavioral notes:**\n- Clear button is always present in the DOM but hidden when input is empty\n- Clear button has `opacity: 0` and `pointerEvents: none` when hidden\n- Clear button automatically transitions when value changes\n- Clear button is disabled when input is disabled or read-only\n- Clear button has an internationalized aria-label (\"Clear search input\")\n\n### Disabled state\n\nDisable input interaction with the `isDisabled` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <SearchInput placeholder=\"Enabled search\" />\n    <SearchInput placeholder=\"Disabled search\" isDisabled />\n    <SearchInput\n      value=\"Disabled with value\"\n      isDisabled\n      onChange={() => {}}\n    />\n  </Stack>\n)\n```\n\n### Invalid state\n\nMark inputs as invalid for validation feedback:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <SearchInput\n      placeholder=\"Valid search\"\n      value=\"valid query\"\n      onChange={() => {}}\n    />\n    <SearchInput\n      placeholder=\"Invalid search\"\n      value=\"error\"\n      isInvalid\n      onChange={() => {}}\n    />\n  </Stack>\n)\n```\n\n### Read-only state\n\nUse `isReadOnly` to display values without allowing editing:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <SearchInput\n      value=\"Editable search\"\n      onChange={() => {}}\n    />\n    <SearchInput\n      value=\"Read-only search\"\n      isReadOnly\n      onChange={() => {}}\n    />\n  </Stack>\n)\n```\n\n### Event handlers\n\nSearchInput supports three event handlers for different interaction patterns:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('');\n  const [submitted, setSubmitted] = useState<string>('');\n  const [clearCount, setClearCount] = useState<number>(0);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <SearchInput\n        value={value}\n        onChange={(newValue) => {\n          setValue(newValue);\n        }}\n        onSubmit={(submittedValue) => {\n          setSubmitted(submittedValue);\n        }}\n        onClear={() => {\n          setClearCount((count) => count + 1);\n        }}\n        placeholder=\"Type and press Enter...\"\n      />\n      <Stack direction=\"column\" gap=\"200\" fontSize=\"sm\">\n        <Text>Current: {value || '(empty)'}</Text>\n        <Text>Submitted: {submitted || '(none)'}</Text>\n        <Text>Clear count: {clearCount}</Text>\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n**Event handler details:**\n- `onChange`: Called when input value changes (on every keystroke)\n- `onSubmit`: Called when user presses Enter\n- `onClear`: Called when user clicks the clear button or presses Escape\n\n### Uncontrolled mode\n\nFor simpler use cases, use uncontrolled mode with `defaultValue` and `onChange`:\n\n```jsx live-dev\nconst App = () => {\n  const [displayValue, setDisplayValue] = useState<string>('');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <SearchInput\n        placeholder=\"Type something...\"\n        defaultValue=\"\"\n        onChange={(value) => {\n          setDisplayValue(value);\n        }}\n      />\n      <Text fontSize=\"sm\">Current value: {displayValue || '(empty)'}</Text>\n    </Stack>\n  );\n}\n```\n\nUse uncontrolled mode when you need to capture the input value without managing state yourself.\n\n**Note:** SearchInput's `onChange` receives the string value directly, not an event object.\n\n### Controlled mode\n\nFor scenarios requiring programmatic control or coordination with other components, use controlled mode:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string>('');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <SearchInput\n        value={value}\n        onChange={(value) => setValue(value)}\n        placeholder=\"Controlled search\"\n      />\n      <Text fontSize=\"sm\">\n        {value ? `Searching for: ${value}` : 'Start typing...'}\n      </Text>\n      <Button onClick={() => setValue('')}>\n        Clear programmatically\n      </Button>\n    </Stack>\n  );\n}\n```\n\nUse controlled mode when you need to:\n- Synchronize the value with external state\n- Validate or transform search queries\n- Clear or programmatically set the value\n- React to changes in real-time\n- Coordinate with other components (like displaying search results)\n\n## Component requirements\n\n## Accessibility\n\nThe SearchInput handles most accessibility requirements internally. However, you must always associate an internationalized label with the component. Visual labels are preferable, and can be set by:\n\n- Using the `SearchInputField` pattern component (if available, recommended)\n- Associating a `<label>` element with the `SearchInput` using `aria-labelledby`:\n\n```tsx\n<label id=\"search-label\">\n  {msg.format(searchMessage)}\n</label>\n<SearchInput aria-labelledby=\"search-label\" />\n```\n\n- Associating a `<label>` element with the `SearchInput` using `htmlFor`:\n\n```tsx\n<label htmlFor=\"search-input\">\n  {msg.format(searchMessage)}\n</label>\n<SearchInput id=\"search-input\" />\n```\n\nIf your design requires that the label should not be visible, the label should be set using the `aria-label` prop:\n\n```tsx\n<SearchInput aria-label={msg.format(searchMessage)} />\n```\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"product-search-input\";\n\nexport const ProductSearch = () => (\n  <SearchInput id={PERSISTENT_ID} placeholder=\"Search products...\" />\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab` / `Shift+Tab`: Navigate to/from the search field\n- `Arrow keys`: Move cursor within the text (Left/Right)\n- `Home` / `End`: Move cursor to start/end of text\n- `Ctrl+A` / `Cmd+A`: Select all text\n- `Enter`: Submit search (triggers `onSubmit` handler)\n- `Escape`: Clear the search input (triggers `onClear` handler)\n- Standard text editing shortcuts: Cut, Copy, Paste, Undo, Redo\n\n#### Click-to-focus behavior\n\nClicking anywhere within the input container (including the search icon area) will focus the input field, providing a larger interactive target for better usability.\n\n## API reference\n\n<PropsTable id=\"SearchInput\" />\n\n## Common patterns\n\n### Search with live filtering\n\nDisplay results that update as the user types:\n\n```jsx live-dev\nconst App = () => {\n  const [query, setQuery] = useState<string>('');\n\n  const products = [\n    'Laptop', 'Phone', 'Tablet', 'Monitor', 'Keyboard',\n    'Mouse', 'Headphones', 'Camera', 'Printer', 'Scanner'\n  ];\n\n  const filteredProducts = products.filter(product =>\n    product.toLowerCase().includes(query.toLowerCase())\n  );\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <SearchInput\n        value={query}\n        onChange={setQuery}\n        placeholder=\"Search products...\"\n      />\n      <Stack direction=\"column\" gap=\"200\">\n        {query && filteredProducts.length === 0 && (\n          <Text fontSize=\"sm\" color=\"neutral.11\">\n            No results found for \"{query}\"\n          </Text>\n        )}\n        {query && filteredProducts.length > 0 && (\n          <Text fontSize=\"sm\" fontWeight=\"medium\">\n            Found {filteredProducts.length} result{filteredProducts.length !== 1 ? 's' : ''}:\n          </Text>\n        )}\n        {query && filteredProducts.map(product => (\n          <Text key={product} fontSize=\"sm\">\n            • {product}\n          </Text>\n        ))}\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n### Search with submit action\n\nHandle search submission with Enter key or button click:\n\n```jsx live-dev\nconst App = () => {\n  const [query, setQuery] = useState<string>('');\n  const [results, setResults] = useState<string[]>([]);\n  const [isSearching, setIsSearching] = useState<boolean>(false);\n\n  const performSearch = (searchQuery: string) => {\n    if (!searchQuery.trim()) {\n      setResults([]);\n      return;\n    }\n\n    setIsSearching(true);\n\n    // Simulate API call delay\n    setTimeout(() => {\n      const mockResults = [\n        `Result 1 for \"${searchQuery}\"`,\n        `Result 2 for \"${searchQuery}\"`,\n        `Result 3 for \"${searchQuery}\"`,\n      ];\n      setResults(mockResults);\n      setIsSearching(false);\n    }, 500);\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"row\" gap=\"200\" alignItems=\"center\">\n        <SearchInput\n          value={query}\n          onChange={setQuery}\n          onSubmit={performSearch}\n          placeholder=\"Type and press Enter...\"\n        />\n        <Button\n          onClick={() => performSearch(query)}\n          size=\"md\"\n        >\n          Search\n        </Button>\n      </Stack>\n\n      {isSearching && (\n        <Text fontSize=\"sm\" color=\"neutral.11\">\n          Searching...\n        </Text>\n      )}\n\n      {!isSearching && results.length > 0 && (\n        <Stack direction=\"column\" gap=\"200\">\n          <Text fontSize=\"sm\" fontWeight=\"medium\">\n            Search Results:\n          </Text>\n          {results.map((result, index) => (\n            <Text key={index} fontSize=\"sm\">\n              • {result}\n            </Text>\n          ))}\n        </Stack>\n      )}\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using SearchInput within your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-specific logic.\n\n### Basic Rendering Tests\n\nVerify the component renders with expected elements\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { SearchInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"SearchInput - Basic rendering\", () => {\n  it(\"renders search input with search icon\", () => {\n    render(\n      <NimbusProvider>\n        <SearchInput placeholder=\"Search...\" aria-label=\"Search\" />\n      </NimbusProvider>\n    );\n\n    const searchBox = screen.getByRole(\"searchbox\");\n    expect(searchBox).toBeInTheDocument();\n    expect(searchBox).toHaveAttribute(\"type\", \"search\");\n    expect(searchBox).toHaveAttribute(\"placeholder\", \"Search...\");\n  });\n\n  it(\"renders with clear button (hidden when empty)\", () => {\n    render(\n      <NimbusProvider>\n        <SearchInput placeholder=\"Search...\" aria-label=\"Search\" />\n      </NimbusProvider>\n    );\n\n    // Clear button is always in DOM\n    const clearButton = screen.getByRole(\"button\", { hidden: true });\n    expect(clearButton).toBeInTheDocument();\n\n    // But hidden visually when empty\n    const computedStyle = window.getComputedStyle(clearButton);\n    expect(computedStyle.opacity).toBe(\"0\");\n    expect(computedStyle.pointerEvents).toBe(\"none\");\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with the search input\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { SearchInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"SearchInput - Interactions\", () => {\n  it(\"handles typing in search input\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <SearchInput placeholder=\"Search...\" aria-label=\"Search\" />\n      </NimbusProvider>\n    );\n\n    const searchBox = screen.getByRole(\"searchbox\");\n    await user.type(searchBox, \"test query\");\n\n    expect(searchBox).toHaveValue(\"test query\");\n  });\n\n  it(\"calls onChange with string value on input\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <SearchInput\n          onChange={handleChange}\n          placeholder=\"Search...\"\n          aria-label=\"Search\"\n        />\n      </NimbusProvider>\n    );\n\n    const searchBox = screen.getByRole(\"searchbox\");\n    await user.type(searchBox, \"test\");\n\n    // onChange receives string, not event\n    expect(handleChange).toHaveBeenCalledWith(\"test\");\n  });\n\n  it(\"shows clear button when input has value\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <SearchInput placeholder=\"Search...\" aria-label=\"Search\" />\n      </NimbusProvider>\n    );\n\n    const searchBox = screen.getByRole(\"searchbox\");\n    await user.type(searchBox, \"test\");\n\n    const clearButton = screen.getByRole(\"button\");\n\n    await waitFor(() => {\n      const computedStyle = window.getComputedStyle(clearButton);\n      expect(computedStyle.opacity).toBe(\"1\");\n      expect(computedStyle.pointerEvents).toBe(\"auto\");\n    });\n  });\n\n  it(\"clears input when clear button is clicked\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <SearchInput placeholder=\"Search...\" aria-label=\"Search\" />\n      </NimbusProvider>\n    );\n\n    const searchBox = screen.getByRole(\"searchbox\");\n    await user.type(searchBox, \"test query\");\n    expect(searchBox).toHaveValue(\"test query\");\n\n    const clearButton = screen.getByRole(\"button\");\n    await user.click(clearButton);\n\n    expect(searchBox).toHaveValue(\"\");\n  });\n\n  it(\"calls onClear when clear button is clicked\", async () => {\n    const user = userEvent.setup();\n    const handleClear = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <SearchInput\n          defaultValue=\"test\"\n          onClear={handleClear}\n          placeholder=\"Search...\"\n          aria-label=\"Search\"\n        />\n      </NimbusProvider>\n    );\n\n    const clearButton = screen.getByRole(\"button\");\n    await user.click(clearButton);\n\n    expect(handleClear).toHaveBeenCalled();\n  });\n});\n```\n\n### Keyboard Navigation Tests\n\nTest keyboard interactions and shortcuts\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { SearchInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"SearchInput - Keyboard navigation\", () => {\n  it(\"focuses on tab key\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <SearchInput placeholder=\"Search...\" aria-label=\"Search\" />\n      </NimbusProvider>\n    );\n\n    const searchBox = screen.getByRole(\"searchbox\");\n    expect(searchBox).not.toHaveFocus();\n\n    await user.tab();\n    expect(searchBox).toHaveFocus();\n  });\n\n  it(\"clears input on Escape key\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <SearchInput placeholder=\"Search...\" aria-label=\"Search\" />\n      </NimbusProvider>\n    );\n\n    const searchBox = screen.getByRole(\"searchbox\");\n    await user.type(searchBox, \"test query\");\n    expect(searchBox).toHaveValue(\"test query\");\n\n    await user.keyboard(\"{Escape}\");\n    expect(searchBox).toHaveValue(\"\");\n  });\n\n  it(\"calls onSubmit on Enter key\", async () => {\n    const user = userEvent.setup();\n    const handleSubmit = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <SearchInput\n          onSubmit={handleSubmit}\n          placeholder=\"Search...\"\n          aria-label=\"Search\"\n        />\n      </NimbusProvider>\n    );\n\n    const searchBox = screen.getByRole(\"searchbox\");\n    await user.type(searchBox, \"test query\");\n    await user.keyboard(\"{Enter}\");\n\n    expect(handleSubmit).toHaveBeenCalledWith(\"test query\");\n  });\n});\n```\n\n### Controlled Mode Tests\n\nTest controlled component behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { SearchInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"SearchInput - Controlled mode\", () => {\n  it(\"updates controlled value via onChange\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    const { rerender } = render(\n      <NimbusProvider>\n        <SearchInput\n          value=\"\"\n          onChange={handleChange}\n          placeholder=\"Search...\"\n          aria-label=\"Search\"\n        />\n      </NimbusProvider>\n    );\n\n    const searchBox = screen.getByRole(\"searchbox\");\n    await user.type(searchBox, \"test\");\n\n    // onChange called once per character - receives strings\n    expect(handleChange).toHaveBeenCalledTimes(4);\n\n    // Verify all calls receive strings\n    for (const call of handleChange.mock.calls) {\n      expect(typeof call[0]).toBe(\"string\");\n    }\n\n    // Rerender with new value\n    rerender(\n      <NimbusProvider>\n        <SearchInput\n          value=\"test\"\n          onChange={handleChange}\n          placeholder=\"Search...\"\n          aria-label=\"Search\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(searchBox).toHaveValue(\"test\");\n  });\n\n  it(\"can be programmatically cleared\", async () => {\n    let value = \"initial value\";\n    const handleChange = vi.fn((newValue: string) => {\n      value = newValue;\n    });\n\n    const { rerender } = render(\n      <NimbusProvider>\n        <SearchInput\n          value={value}\n          onChange={handleChange}\n          placeholder=\"Search...\"\n          aria-label=\"Search\"\n        />\n      </NimbusProvider>\n    );\n\n    const searchBox = screen.getByRole(\"searchbox\");\n    expect(searchBox).toHaveValue(\"initial value\");\n\n    // Programmatically clear\n    value = \"\";\n    rerender(\n      <NimbusProvider>\n        <SearchInput\n          value={value}\n          onChange={handleChange}\n          placeholder=\"Search...\"\n          aria-label=\"Search\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(searchBox).toHaveValue(\"\");\n  });\n});\n```\n\n### State Tests\n\nTest disabled, invalid, and read-only states\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { SearchInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"SearchInput - States\", () => {\n  it(\"disables input when isDisabled is true\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <SearchInput isDisabled placeholder=\"Search...\" aria-label=\"Search\" />\n      </NimbusProvider>\n    );\n\n    const searchBox = screen.getByRole(\"searchbox\");\n    expect(searchBox).toBeDisabled();\n\n    // Cannot type when disabled\n    await user.type(searchBox, \"test\");\n    expect(searchBox).toHaveValue(\"\");\n  });\n\n  it(\"marks input as invalid when isInvalid is true\", () => {\n    render(\n      <NimbusProvider>\n        <SearchInput isInvalid placeholder=\"Search...\" aria-label=\"Search\" />\n      </NimbusProvider>\n    );\n\n    const searchBox = screen.getByRole(\"searchbox\");\n    // Check parent container for data-invalid attribute\n    const container = searchBox.closest(\"[data-invalid]\");\n    expect(container).toHaveAttribute(\"data-invalid\", \"true\");\n  });\n\n  it(\"prevents editing when isReadOnly is true\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <SearchInput\n          isReadOnly\n          defaultValue=\"read-only value\"\n          placeholder=\"Search...\"\n          aria-label=\"Search\"\n        />\n      </NimbusProvider>\n    );\n\n    const searchBox = screen.getByRole(\"searchbox\");\n    expect(searchBox).toHaveAttribute(\"readonly\");\n    expect(searchBox).toHaveValue(\"read-only value\");\n\n    // Cannot type when read-only\n    await user.click(searchBox);\n    await user.type(searchBox, \"test\");\n    expect(searchBox).toHaveValue(\"read-only value\");\n  });\n\n  it(\"disables clear button when input is disabled\", () => {\n    render(\n      <NimbusProvider>\n        <SearchInput\n          isDisabled\n          defaultValue=\"test\"\n          placeholder=\"Search...\"\n          aria-label=\"Search\"\n        />\n      </NimbusProvider>\n    );\n\n    const clearButton = screen.getByRole(\"button\", { hidden: true });\n    expect(clearButton).toBeDisabled();\n  });\n\n  it(\"disables clear button when input is read-only\", () => {\n    render(\n      <NimbusProvider>\n        <SearchInput\n          isReadOnly\n          defaultValue=\"test\"\n          placeholder=\"Search...\"\n          aria-label=\"Search\"\n        />\n      </NimbusProvider>\n    );\n\n    const clearButton = screen.getByRole(\"button\");\n    expect(clearButton).toBeDisabled();\n  });\n});\n```\n\n### Event Handler Tests\n\nTest onChange, onSubmit, and onClear event handlers\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { SearchInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"SearchInput - Event handlers\", () => {\n  it(\"calls all event handlers appropriately\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    const handleSubmit = vi.fn();\n    const handleClear = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <SearchInput\n          onChange={handleChange}\n          onSubmit={handleSubmit}\n          onClear={handleClear}\n          placeholder=\"Search...\"\n          aria-label=\"Search\"\n        />\n      </NimbusProvider>\n    );\n\n    const searchBox = screen.getByRole(\"searchbox\");\n\n    // Type to trigger onChange\n    await user.type(searchBox, \"test\");\n    expect(handleChange).toHaveBeenCalled();\n    expect(handleChange).toHaveBeenLastCalledWith(\"test\");\n\n    // Press Enter to trigger onSubmit\n    await user.keyboard(\"{Enter}\");\n    expect(handleSubmit).toHaveBeenCalledWith(\"test\");\n\n    // Click clear button to trigger onClear\n    const clearButton = screen.getByRole(\"button\");\n    await user.click(clearButton);\n    expect(handleClear).toHaveBeenCalled();\n  });\n\n  it(\"clears value on Escape key when focused\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <SearchInput\n          defaultValue=\"test value\"\n          placeholder=\"Search...\"\n          aria-label=\"Search\"\n        />\n      </NimbusProvider>\n    );\n\n    const searchBox = screen.getByRole(\"searchbox\");\n    expect(searchBox).toHaveValue(\"test value\");\n\n    // Focus the input first\n    await user.click(searchBox);\n    await user.keyboard(\"{Escape}\");\n\n    expect(searchBox).toHaveValue(\"\");\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-searchinput--docs)\n- [React Aria SearchField](https://react-spectrum.adobe.com/react-aria/SearchField.html)\n- [ARIA Search Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/search.html)\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual variants",
+          "href": "#visual-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Clear button behavior",
+          "href": "#clear-button-behavior",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Invalid state",
+          "href": "#invalid-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Read-only state",
+          "href": "#read-only-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Event handlers",
+          "href": "#event-handlers",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Click-to-focus behavior",
+          "href": "#click-to-focus-behavior",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Search with live filtering",
+          "href": "#search-with-live-filtering",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Search with submit action",
+          "href": "#search-with-submit-action",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interaction Tests",
+          "href": "#interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard Navigation Tests",
+          "href": "#keyboard-navigation-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled Mode Tests",
+          "href": "#controlled-mode-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "State Tests",
+          "href": "#state-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Event Handler Tests",
+          "href": "#event-handler-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nSearchInput guidelines focus on creating clear, accessible, and user-friendly\nsearch experiences by emphasizing proper placeholder text, clear visual\nfeedback, and keyboard accessibility.\n\n### Best practices\n\n- **Provide clear placeholder text:** Use brief, descriptive text inside the\n  field (e.g., \"Search products,\" \"Find a customer\") to indicate what can be\n  searched.\n- **Offer suggestions:** Implement type-ahead or autocomplete to offer relevant\n  suggestions as the user types, improving speed and accuracy.\n- **Include a clear button:** Provide a control, often an \"X\" icon, to quickly\n  clear the search query. This is typically placed on the right side of the\n  field.\n- **Maintain consistency:** Place the search input in a predictable,\n  easy-to-find location, such as the primary navigation bar or near the content\n  being searched.\n- **Support keyboard interaction:** Ensure the input field and its associated\n  suggestions are fully navigable using the keyboard (e.g., Tab, Enter, Arrow\n  keys).\n- **Live Search:** The core function should be to trigger search or filtering\n  logic on every value change (onChange), enabling an instantaneous search\n  experience (live-search or auto-complete).\n- **Loading states:** Consider showing loading indicators when search is in\n  progress.\n- **Immediate feedback:** Show search results as users type (debounced) or on\n  submission.\n- **Error handling:** Display clear error messages when searches fail.\n\n### Usage\n\n> [!TIP]\\\n> When to use\n\n- **Live search:** You need to narrow down a visible list, table, or grid of\n  items instantly as the user types. The search results update in real-time on\n  the same screen.\n- **Autocomplete/Suggestions:** You need to provide a set of contextual\n  suggestions that appear in a dropdown while the user is typing, leading to a\n  final selection or submission.\n- **Global/Site-wide search:** The input serves as the primary entry point for\n  finding content across the entire application or website.\n\n> [!CAUTION]\\\n> When not to use\n\n- **Simple filtering**: If filtering is better handled by dropdowns or\n  checkboxes.\n- **Form submission**: Don't use for general text inputs that aren't\n  search-related.\n- **Complex queries**: When users need advanced search features like boolean\n  operators or multiple fields.\n\n### Do's and Don'ts\n\n> [!TIP]\\\n> **Do**\n>\n> - Provide clear placeholder text\n\n```jsx live\nconst App = () => (\n  <SearchInput placeholder=\"Search by name...\" />\n)\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Avoid long descriptive placeholders\n\n```jsx live\nconst App = () => (\n  <SearchInput width=\"md\" placeholder=\"Please enter the name you are searching for\" />\n)\n```\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Do's and Don'ts",
+          "href": "#dos-and-donts",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}