@commercetools/nimbus-mcp 3.0.0 → 3.1.0

package/data/docs/routes/components-data-display-draggable-list.json

@@ -185,7 +185,7 @@
       ]
     },
     "dev": {
-      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { DraggableList, type DraggableListRootProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation uses an array of items with `key` and `label` properties. The component automatically handles drag-and-drop reordering:\n\n```jsx live-dev\nconst App = () => {\n  const items = [\n    { key: '1', label: 'First item' },\n    { key: '2', label: 'Second item' },\n    { key: '3', label: 'Third item' },\n  ];\n\n  return (\n    <DraggableList.Root\n      items={items}\n      aria-label=\"Task list\"\n    />\n  );\n}\n```\n\n**Important:** You must provide either an `aria-label` or `aria-labelledby` prop for accessibility. The drag-and-drop functionality requires an accessible label.\n\n## Working with React Aria drag-and-drop\n\nThe DraggableList relies on React Aria Components' GridList and drag-and-drop hooks for accessible drag-and-drop functionality. This integration provides keyboard navigation, screen reader support, and touch-friendly interactions.\n\n### Drag-and-drop behavior\n\nReact Aria's drag-and-drop system provides:\n- **Visual feedback**: Items show grab cursors and drag previews during interactions\n- **Drop indicators**: Visual cues show where items will be placed\n- **Move operations**: Items are moved (not copied) between lists\n- **Keyboard support**: Full keyboard navigation for drag-and-drop\n\n### Data format\n\nItems being dragged use a custom format (`nimbus-draggable-list-item`) that allows items to be dragged between multiple DraggableList instances while preventing drops from external sources.\n\n### State management\n\nThe component uses React Stately's `useListData` hook internally to manage item state and reordering operations. This provides:\n- Efficient list operations (insert, remove, move)\n- Selection state management\n- Synchronization with external state via `onUpdateItems`\n\n> [!TIP]\\\n> See [React Aria Drag and Drop](https://react-spectrum.adobe.com/react-aria/dnd.html) for complete API reference and advanced usage.\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  const [smallItems, setSmallItems] = useState([\n    { key: '1', label: 'Task 1' },\n    { key: '2', label: 'Task 2' },\n  ]);\n\n  const [mediumItems, setMediumItems] = useState([\n    { key: '3', label: 'Task 3' },\n    { key: '4', label: 'Task 4' },\n  ]);\n\n  return (\n    <Stack direction=\"row\" gap=\"400\">\n      <DraggableList.Root\n        items={smallItems}\n        onUpdateItems={setSmallItems}\n        size=\"sm\"\n        aria-label=\"Small list\"\n      />\n      <DraggableList.Root\n        items={mediumItems}\n        onUpdateItems={setMediumItems}\n        size=\"md\"\n        aria-label=\"Medium list\"\n      />\n    </Stack>\n  );\n}\n```\n\n### Item removal\n\nEnable item removal by setting `removableItems={true}`. When items are removed, the `onUpdateItems` callback receives the updated list:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([\n    { key: '1', label: 'Item 1' },\n    { key: '2', label: 'Item 2' },\n    { key: '3', label: 'Item 3' },\n  ]);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DraggableList.Root\n        items={items}\n        removableItems\n        onUpdateItems={setItems}\n        aria-label=\"Removable items\"\n      />\n      <Text fontSize=\"sm\">Items: {items.length}</Text>\n    </Stack>\n  );\n}\n```\n\n### Custom item rendering\n\nFor items without `key` and `label` properties, or when you need custom rendering, provide a render function as children:\n\n```jsx live-dev\nconst App = () => {\n  const items = [\n    { id: 'task-1', title: 'Design mockups', priority: 'High' },\n    { id: 'task-2', title: 'Write tests', priority: 'Medium' },\n    { id: 'task-3', title: 'Review PR', priority: 'Low' },\n  ];\n\n  return (\n    <DraggableList.Root\n      items={items}\n      getKey={(item) => item.id}\n      aria-label=\"Task priorities\"\n    >\n      {(item) => (\n        <DraggableList.Item id={item.id}>\n          <Stack direction=\"column\" gap=\"100\" padding=\"200\">\n            <Text fontWeight=\"500\">{item.title}</Text>\n            <Text fontSize=\"sm\" color=\"fg.muted\">\n              Priority: {item.priority}\n            </Text>\n          </Stack>\n        </DraggableList.Item>\n      )}\n    </DraggableList.Root>\n  );\n}\n```\n\n**Note:** When using custom rendering, you must provide a `getKey` function to extract unique keys from your items. Wrap this function in `useCallback` to prevent unnecessary re-synchronization:\n\n```tsx\nconst getKey = useCallback((item) => item.id, []);\n```\n\n### Controlled updates\n\nUse the `onUpdateItems` callback to track changes when items are reordered or removed:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([\n    { key: '1', label: 'High priority' },\n    { key: '2', label: 'Medium priority' },\n    { key: '3', label: 'Low priority' },\n  ]);\n\n  const [updateCount, setUpdateCount] = useState(0);\n\n  const handleUpdateItems = useCallback((updatedItems) => {\n    setItems(updatedItems);\n    setUpdateCount(prev => prev + 1);\n  }, []);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DraggableList.Root\n        items={items}\n        onUpdateItems={handleUpdateItems}\n        aria-label=\"Priority list\"\n      />\n      <Text fontSize=\"sm\">\n        Order: {items.map(item => item.label).join(', ')}\n      </Text>\n      <Text fontSize=\"sm\">Updates: {updateCount}</Text>\n    </Stack>\n  );\n}\n```\n\n### Custom empty state\n\nCustomize the message displayed when the list is empty:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([]);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DraggableList.Root\n        items={items}\n        onUpdateItems={setItems}\n        renderEmptyState=\"No tasks yet. Add some items!\"\n        aria-label=\"Empty task list\"\n      />\n      <Button\n        size=\"md\"\n        onClick={() => {\n          const newItem = {\n            key: Date.now().toString(),\n            label: `Task ${items.length + 1}`,\n          };\n          setItems([...items, newItem]);\n        }}\n      >\n        Add Task\n      </Button>\n    </Stack>\n  );\n}\n```\n\n### Multiple lists\n\nItems can be dragged between multiple DraggableList instances:\n\n```jsx live-dev\nconst App = () => {\n  const [todoItems, setTodoItems] = useState([\n    { key: '1', label: 'Design homepage' },\n    { key: '2', label: 'Write docs' },\n  ]);\n\n  const [doneItems, setDoneItems] = useState([\n    { key: '3', label: 'Setup project' },\n  ]);\n\n  return (\n    <Stack direction=\"row\" gap=\"400\">\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"500\">To Do</Text>\n        <DraggableList.Root\n          items={todoItems}\n          onUpdateItems={setTodoItems}\n          aria-label=\"Todo list\"\n        />\n      </Stack>\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"500\">Done</Text>\n        <DraggableList.Root\n          items={doneItems}\n          onUpdateItems={setDoneItems}\n          aria-label=\"Done list\"\n        />\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n### TypeScript generics\n\nUse TypeScript generics to ensure type safety with your custom item data:\n\n```jsx live-dev\nconst App = () => {\n  type TaskItem = {\n    key: string;\n    label: string;\n    assignee: string;\n    status: 'pending' | 'active' | 'done';\n  };\n\n  const [tasks, setTasks] = useState<TaskItem[]>([\n    { key: '1', label: 'Review code', assignee: 'Alice', status: 'active' },\n    { key: '2', label: 'Write tests', assignee: 'Bob', status: 'pending' },\n  ]);\n\n  return (\n    <DraggableList.Root<TaskItem>\n      items={tasks}\n      onUpdateItems={setTasks}\n      aria-label=\"Team tasks\"\n    >\n      {(item) => (\n        <DraggableList.Item id={item.key}>\n          <Stack direction=\"column\" gap=\"100\" padding=\"200\">\n            <Text fontWeight=\"500\">{item.label}</Text>\n            <Text fontSize=\"sm\" color=\"fg.muted\">\n              {item.assignee} • {item.status}\n            </Text>\n          </Stack>\n        </DraggableList.Item>\n      )}\n    </DraggableList.Root>\n  );\n}\n```\n\n## Component requirements\n\n## Accessibility\n\nThe DraggableList handles most accessibility requirements internally through React Aria's GridList component. However, you must always provide an accessible label using one of these methods:\n\n**Using DraggableList.Field (recommended):**\n\n```tsx\n<DraggableList.Field\n  label={msg.format(labelMessage)}\n  items={items}\n/>\n```\n\n**Using aria-labelledby:**\n\n```tsx\n<label id=\"list-label\">\n  {msg.format(labelMessage)}\n</label>\n<DraggableList.Root\n  aria-labelledby=\"list-label\"\n  items={items}\n/>\n```\n\n**Using aria-label:**\n\n```tsx\n<DraggableList.Root\n  aria-label={msg.format(labelMessage)}\n  items={items}\n/>\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 = \"example-draggable-list\";\n\nexport const Example = () => (\n  <DraggableList.Root\n    id={PERSISTENT_ID}\n    aria-label=\"Task list\"\n    items={items}\n  />\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab` / `Shift+Tab`: Move focus between items and drag handles\n- `Arrow keys`: Navigate between items in the list\n- `Enter` / `Space`: Activate drag mode for the focused item\n- `Arrow keys` (during drag): Move the item up or down in the list\n- `Enter` / `Space` (during drag): Drop the item at the current position\n- `Escape` (during drag): Cancel the drag operation\n\n## API reference\n\n<PropsTable id=\"DraggableList\" />\n\n## Common patterns\n\n### Form integration with validation\n\nIntegrate DraggableList with form libraries like Formik for validated priority lists:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([\n    { key: '1', label: 'Critical bug' },\n    { key: '2', label: 'Feature request' },\n    { key: '3', label: 'Documentation' },\n  ]);\n\n  const [touched, setTouched] = useState(false);\n  const hasMinimumItems = items.length >= 2;\n\n  const handleUpdateItems = useCallback((updated) => {\n    setItems(updated);\n    setTouched(true);\n  }, []);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DraggableList.Field\n        label=\"Priority Order\"\n        description=\"Drag to reorder by priority\"\n        items={items}\n        onUpdateItems={handleUpdateItems}\n        error={touched && !hasMinimumItems ? 'At least 2 items required' : undefined}\n        isInvalid={touched && !hasMinimumItems}\n        aria-label=\"Priority list\"\n      />\n      <Text fontSize=\"sm\" color={hasMinimumItems ? 'positive.11' : 'critical.11'}>\n        {hasMinimumItems ? '✓ Valid' : '✗ Invalid: Add more items'}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n### Dynamic item management\n\nAllow users to add, remove, and reorder items dynamically:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([\n    { key: '1', label: 'Task 1' },\n    { key: '2', label: 'Task 2' },\n  ]);\n  const [nextId, setNextId] = useState(3);\n\n  const addItem = () => {\n    const newItem = {\n      key: nextId.toString(),\n      label: `Task ${nextId}`,\n    };\n    setItems([...items, newItem]);\n    setNextId(nextId + 1);\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DraggableList.Root\n        items={items}\n        removableItems\n        onUpdateItems={setItems}\n        aria-label=\"Task manager\"\n      />\n      <Button size=\"md\" onClick={addItem}>\n        Add Task\n      </Button>\n    </Stack>\n  );\n}\n```\n\n### Synchronized state with external storage\n\nSync list order with external state management or API:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([\n    { key: '1', label: 'Design system' },\n    { key: '2', label: 'API integration' },\n    { key: '3', label: 'Testing' },\n  ]);\n\n  const [lastSaved, setLastSaved] = useState('Not saved');\n\n  const handleUpdateItems = useCallback((updatedItems) => {\n    setItems(updatedItems);\n\n    // Simulate API save\n    setTimeout(() => {\n      setLastSaved(new Date().toLocaleTimeString());\n    }, 500);\n  }, []);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DraggableList.Root\n        items={items}\n        onUpdateItems={handleUpdateItems}\n        aria-label=\"Project phases\"\n      />\n      <Text fontSize=\"sm\" color=\"fg.muted\">\n        Last saved: {lastSaved}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using DraggableList 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 and items\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList - Basic rendering\", () => {\n  it(\"renders list with items\", () => {\n    render(\n      <NimbusProvider>\n        <DraggableList.Root items={mockItems} aria-label=\"Task list\" />\n      </NimbusProvider>\n    );\n\n    // Verify list renders with grid role\n    expect(\n      screen.getByRole(\"grid\", { name: /task list/i })\n    ).toBeInTheDocument();\n\n    // Verify all items are rendered\n    expect(screen.getAllByRole(\"row\")).toHaveLength(mockItems.length);\n  });\n\n  it(\"renders items with accessible labels\", () => {\n    render(\n      <NimbusProvider>\n        <DraggableList.Root items={mockItems} aria-label=\"Test list\" />\n      </NimbusProvider>\n    );\n\n    mockItems.forEach((item) => {\n      expect(screen.getByLabelText(item.label)).toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Size Variant Tests\n\nVerify different size variants render correctly\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList - Size variants\", () => {\n  it(\"renders with small size\", () => {\n    const items = [{ key: \"1\", label: \"Item 1\" }];\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Root items={items} size=\"sm\" aria-label=\"Small list\" />\n      </NimbusProvider>\n    );\n\n    const grid = screen.getByRole(\"grid\", { name: /small list/i });\n    expect(grid).toBeInTheDocument();\n  });\n\n  it(\"renders with medium size\", () => {\n    const items = [{ key: \"1\", label: \"Item 1\" }];\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Root items={items} size=\"md\" aria-label=\"Medium list\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"grid\")).toBeInTheDocument();\n  });\n});\n```\n\n### Item Removal Tests\n\nTest removable items functionality\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList - Item removal\", () => {\n  it(\"calls onUpdateItems when item is removed\", async () => {\n    const user = userEvent.setup();\n    const handleUpdateItems = vi.fn();\n    const items = [\n      { key: \"1\", label: \"Item 1\" },\n      { key: \"2\", label: \"Item 2\" },\n      { key: \"3\", label: \"Item 3\" },\n    ];\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={items}\n          removableItems\n          onUpdateItems={handleUpdateItems}\n          aria-label=\"Test list\"\n        />\n      </NimbusProvider>\n    );\n\n    // Find and click remove button for first item\n    const removeButtons = screen.getAllByRole(\"button\", {\n      name: /remove/i,\n    });\n    await user.click(removeButtons[0]);\n\n    // Verify callback was called with updated list\n    // Note: The callback receives the updated items array\n    expect(handleUpdateItems).toHaveBeenCalled();\n    const lastCall =\n      handleUpdateItems.mock.calls[handleUpdateItems.mock.calls.length - 1][0];\n    expect(lastCall.length).toBeLessThan(items.length);\n  });\n});\n```\n\n### Controlled Mode Tests\n\nTest controlled state management with onUpdateItems\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList - Controlled mode\", () => {\n  it(\"calls onUpdateItems when items are reordered\", () => {\n    const handleUpdateItems = vi.fn();\n    const items = [\n      { key: \"1\", label: \"Item 1\" },\n      { key: \"2\", label: \"Item 2\" },\n    ];\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={items}\n          onUpdateItems={handleUpdateItems}\n          aria-label=\"Test list\"\n        />\n      </NimbusProvider>\n    );\n\n    // Test that the callback is provided\n    expect(handleUpdateItems).toBeDefined();\n  });\n\n  it(\"calls onUpdateItems when items change\", () => {\n    const handleUpdate = vi.fn();\n    const items = [\n      { key: \"1\", label: \"Item 1\" },\n      { key: \"2\", label: \"Item 2\" },\n    ];\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={items}\n          onUpdateItems={handleUpdate}\n          aria-label=\"Test list\"\n        />\n      </NimbusProvider>\n    );\n\n    // Note: Testing actual drag-and-drop interactions requires browser-based testing\n    // (like Storybook tests). These tests verify your integration patterns.\n    expect(screen.getByRole(\"grid\")).toBeInTheDocument();\n  });\n});\n```\n\n### Custom Rendering Tests\n\nTest custom item rendering with render functions\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList - Custom rendering\", () => {\n  it(\"renders items using custom render function\", () => {\n    const items = [\n      { id: \"1\", title: \"Task 1\", priority: \"High\" },\n      { id: \"2\", title: \"Task 2\", priority: \"Low\" },\n    ];\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={items}\n          getKey={(item) => item.id}\n          aria-label=\"Custom rendered list\"\n        >\n          {(item) => (\n            <DraggableList.Item id={item.id} textValue={item.title}>\n              <div>\n                <div>{item.title}</div>\n                <div>Priority: {item.priority}</div>\n              </div>\n            </DraggableList.Item>\n          )}\n        </DraggableList.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Task 1\")).toBeInTheDocument();\n    expect(screen.getByText(\"Priority: High\")).toBeInTheDocument();\n    expect(screen.getByText(\"Task 2\")).toBeInTheDocument();\n  });\n});\n```\n\n### Controlled Mode Tests\n\nTest controlled updates with onUpdateItems callback\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList - Controlled updates\", () => {\n  it(\"calls onUpdateItems when items are reordered\", async () => {\n    const items = [\n      { key: \"1\", label: \"Item 1\" },\n      { key: \"2\", label: \"Item 2\" },\n    ];\n    const handleUpdate = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={items}\n          onUpdateItems={handleUpdate}\n          aria-label=\"Controlled list\"\n        />\n      </NimbusProvider>\n    );\n\n    // Note: Full drag-and-drop testing requires complex keyboard/mouse simulation\n    // This test verifies the callback is properly connected\n    // The callback may be called on mount for internal state synchronization\n    expect(screen.getByRole(\"grid\")).toBeInTheDocument();\n  });\n\n  it(\"syncs external state changes to list\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={[{ key: \"1\", label: \"Item 1\" }]}\n          aria-label=\"Synced list\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Item 1\")).toBeInTheDocument();\n\n    // Update items prop\n    rerender(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={[\n            { key: \"1\", label: \"Item 1\" },\n            { key: \"2\", label: \"Item 2\" },\n          ]}\n          aria-label=\"Synced list\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Item 2\")).toBeInTheDocument();\n  });\n});\n```\n\n### Empty State Tests\n\nTest empty state rendering and customization\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList - Empty state\", () => {\n  it(\"displays default empty state when list has no items\", () => {\n    render(\n      <NimbusProvider>\n        <DraggableList.Root items={[]} aria-label=\"Empty list\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(/drop items here/i)).toBeInTheDocument();\n  });\n\n  it(\"displays custom empty state message\", () => {\n    render(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={[]}\n          renderEmptyState=\"No tasks available\"\n          aria-label=\"Empty list\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"No tasks available\")).toBeInTheDocument();\n  });\n});\n```\n\n### Field Pattern Tests\n\nTest DraggableList.Field form integration\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList.Field - Form integration\", () => {\n  it(\"renders field with label and description\", () => {\n    const items = [\n      { key: \"1\", label: \"Task 1\" },\n      { key: \"2\", label: \"Task 2\" },\n    ];\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Field\n          label=\"Task Priority\"\n          description=\"Drag to reorder\"\n          items={items}\n          aria-label=\"Priority field\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Task Priority\")).toBeInTheDocument();\n    expect(screen.getByText(\"Drag to reorder\")).toBeInTheDocument();\n  });\n\n  it(\"displays error message when validation fails\", () => {\n    render(\n      <NimbusProvider>\n        <DraggableList.Field\n          label=\"Required List\"\n          items={[]}\n          error=\"This field is required\"\n          isInvalid={true}\n          aria-label=\"Required field\"\n        />\n      </NimbusProvider>\n    );\n\n    // The error is wrapped in FormField.Error component\n    expect(screen.getByText(\"This field is required\")).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-draggablelist--docs)\n- [React Aria Drag and Drop](https://react-spectrum.adobe.com/react-aria/dnd.html)\n",
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { DraggableList, type DraggableListRootProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation uses an array of items with `key` and `label` properties. The component automatically handles drag-and-drop reordering:\n\n```jsx live-dev\nconst App = () => {\n  const items = [\n    { key: '1', label: 'First item' },\n    { key: '2', label: 'Second item' },\n    { key: '3', label: 'Third item' },\n  ];\n\n  return (\n    <DraggableList.Root\n      items={items}\n      aria-label=\"Task list\"\n    />\n  );\n}\n```\n\n**Important:** You must provide either an `aria-label` or `aria-labelledby` prop for accessibility. The drag-and-drop functionality requires an accessible label.\n\n## Working with React Aria drag-and-drop\n\nThe DraggableList relies on React Aria Components' GridList and drag-and-drop hooks for accessible drag-and-drop functionality. This integration provides keyboard navigation, screen reader support, and touch-friendly interactions.\n\n### Drag-and-drop behavior\n\nReact Aria's drag-and-drop system provides:\n- **Visual feedback**: Items show grab cursors and drag previews during interactions\n- **Drop indicators**: Visual cues show where items will be placed\n- **Move operations**: Items are moved (not copied) between lists\n- **Keyboard support**: Full keyboard navigation for drag-and-drop\n\n### Data format\n\nItems being dragged use a custom format (`nimbus-draggable-list-item`) that allows items to be dragged between multiple DraggableList instances while preventing drops from external sources. When the `dragNamespace` prop is set, the format is scoped to that namespace (e.g. `nimbus-draggable-list-item:fruits`), so only lists sharing the same namespace can exchange items.\n\n### State management\n\nThe component uses React Stately's `useListData` hook internally to manage item state and reordering operations. This provides:\n- Efficient list operations (insert, remove, move)\n- Selection state management\n- Synchronization with external state via `onUpdateItems`\n\n> [!TIP]\\\n> See [React Aria Drag and Drop](https://react-spectrum.adobe.com/react-aria/dnd.html) for complete API reference and advanced usage.\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  const [smallItems, setSmallItems] = useState([\n    { key: '1', label: 'Task 1' },\n    { key: '2', label: 'Task 2' },\n  ]);\n\n  const [mediumItems, setMediumItems] = useState([\n    { key: '3', label: 'Task 3' },\n    { key: '4', label: 'Task 4' },\n  ]);\n\n  return (\n    <Stack direction=\"row\" gap=\"400\">\n      <DraggableList.Root\n        items={smallItems}\n        onUpdateItems={setSmallItems}\n        size=\"sm\"\n        aria-label=\"Small list\"\n      />\n      <DraggableList.Root\n        items={mediumItems}\n        onUpdateItems={setMediumItems}\n        size=\"md\"\n        aria-label=\"Medium list\"\n      />\n    </Stack>\n  );\n}\n```\n\n### Single selection\n\nUse `selectionMode=\"single\"` to allow users to select one item at a time. Clicking a row selects it; clicking another row changes the selection. No checkboxes are rendered — the row itself is the click target:\n\n```jsx live-dev\nconst App = () => {\n  const [selected, setSelected] = useState(new Set());\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DraggableList.Root\n        items={[\n          { key: '1', label: 'Option A' },\n          { key: '2', label: 'Option B' },\n          { key: '3', label: 'Option C' },\n        ]}\n        selectionMode=\"single\"\n        selectedKeys={selected}\n        onSelectionChange={setSelected}\n        aria-label=\"Single selection list\"\n      />\n      <Text fontSize=\"sm\">\n        Selected: {[...selected].join(', ') || 'none'}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n### Multiple selection\n\nUse `selectionMode=\"multiple\"` to allow users to select any number of items. Each item renders a checkbox for toggling selection independently:\n\n```jsx live-dev\nconst App = () => {\n  const [selected, setSelected] = useState(new Set());\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DraggableList.Root\n        items={[\n          { key: '1', label: 'Task A' },\n          { key: '2', label: 'Task B' },\n          { key: '3', label: 'Task C' },\n        ]}\n        selectionMode=\"multiple\"\n        selectedKeys={selected}\n        onSelectionChange={setSelected}\n        aria-label=\"Multiple selection list\"\n      />\n      <Text fontSize=\"sm\">\n        Selected: {[...selected].join(', ') || 'none'}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n> [!NOTE]\n> Selection props (`selectionMode`, `selectedKeys`, `onSelectionChange`, `defaultSelectedKeys`, `disallowEmptySelection`) are passed through to the underlying React Aria GridList. See the [React Aria GridList docs](https://react-spectrum.adobe.com/react-aria/GridList.html#selection) for the full selection API.\n\n### Item removal\n\nEnable item removal by setting `removableItems={true}`. When items are removed, the `onUpdateItems` callback receives the updated list:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([\n    { key: '1', label: 'Item 1' },\n    { key: '2', label: 'Item 2' },\n    { key: '3', label: 'Item 3' },\n  ]);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DraggableList.Root\n        items={items}\n        removableItems\n        onUpdateItems={setItems}\n        aria-label=\"Removable items\"\n      />\n      <Text fontSize=\"sm\">Items: {items.length}</Text>\n    </Stack>\n  );\n}\n```\n\n### Custom item rendering\n\nFor items without `key` and `label` properties, or when you need custom rendering, provide a render function as children:\n\n```jsx live-dev\nconst App = () => {\n  const items = [\n    { id: 'task-1', title: 'Design mockups', priority: 'High' },\n    { id: 'task-2', title: 'Write tests', priority: 'Medium' },\n    { id: 'task-3', title: 'Review PR', priority: 'Low' },\n  ];\n\n  return (\n    <DraggableList.Root\n      items={items}\n      getKey={(item) => item.id}\n      aria-label=\"Task priorities\"\n    >\n      {(item) => (\n        <DraggableList.Item id={item.id}>\n          <Stack direction=\"column\" gap=\"100\" padding=\"200\">\n            <Text fontWeight=\"500\">{item.title}</Text>\n            <Text fontSize=\"sm\" color=\"fg.muted\">\n              Priority: {item.priority}\n            </Text>\n          </Stack>\n        </DraggableList.Item>\n      )}\n    </DraggableList.Root>\n  );\n}\n```\n\n**Note:** When using custom rendering, you must provide a `getKey` function to extract unique keys from your items. Wrap this function in `useCallback` to prevent unnecessary re-synchronization:\n\n```tsx\nconst getKey = useCallback((item) => item.id, []);\n```\n\n### Controlled updates\n\nUse the `onUpdateItems` callback to track changes when items are reordered or removed:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([\n    { key: '1', label: 'High priority' },\n    { key: '2', label: 'Medium priority' },\n    { key: '3', label: 'Low priority' },\n  ]);\n\n  const [updateCount, setUpdateCount] = useState(0);\n\n  const handleUpdateItems = useCallback((updatedItems) => {\n    setItems(updatedItems);\n    setUpdateCount(prev => prev + 1);\n  }, []);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DraggableList.Root\n        items={items}\n        onUpdateItems={handleUpdateItems}\n        aria-label=\"Priority list\"\n      />\n      <Text fontSize=\"sm\">\n        Order: {items.map(item => item.label).join(', ')}\n      </Text>\n      <Text fontSize=\"sm\">Updates: {updateCount}</Text>\n    </Stack>\n  );\n}\n```\n\n### Custom empty state\n\nCustomize the message displayed when the list is empty:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([]);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DraggableList.Root\n        items={items}\n        onUpdateItems={setItems}\n        renderEmptyState=\"No tasks yet. Add some items!\"\n        aria-label=\"Empty task list\"\n      />\n      <Button\n        size=\"md\"\n        onClick={() => {\n          const newItem = {\n            key: Date.now().toString(),\n            label: `Task ${items.length + 1}`,\n          };\n          setItems([...items, newItem]);\n        }}\n      >\n        Add Task\n      </Button>\n    </Stack>\n  );\n}\n```\n\n### Multiple lists\n\nItems can be dragged between multiple DraggableList instances:\n\n```jsx live-dev\nconst App = () => {\n  const [todoItems, setTodoItems] = useState([\n    { key: '1', label: 'Design homepage' },\n    { key: '2', label: 'Write docs' },\n  ]);\n\n  const [doneItems, setDoneItems] = useState([\n    { key: '3', label: 'Setup project' },\n  ]);\n\n  return (\n    <Stack direction=\"row\" gap=\"400\">\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"500\">To Do</Text>\n        <DraggableList.Root\n          items={todoItems}\n          onUpdateItems={setTodoItems}\n          aria-label=\"Todo list\"\n        />\n      </Stack>\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"500\">Done</Text>\n        <DraggableList.Root\n          items={doneItems}\n          onUpdateItems={setDoneItems}\n          aria-label=\"Done list\"\n        />\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n### Isolating lists with `dragNamespace`\n\nBy default, all DraggableList instances on a page can exchange items. Use the `dragNamespace` prop to isolate groups of lists so that only lists sharing the same namespace accept each other's items:\n\n```jsx live-dev\nconst App = () => {\n  const [fruitsA, setFruitsA] = useState([\n    { key: '1', label: 'Apple' },\n    { key: '2', label: 'Banana' },\n  ]);\n  const [fruitsB, setFruitsB] = useState([\n    { key: '3', label: 'Cherry' },\n  ]);\n  const [veggies, setVeggies] = useState([\n    { key: '4', label: 'Carrot' },\n    { key: '5', label: 'Broccoli' },\n  ]);\n\n  return (\n    <Stack direction=\"row\" gap=\"400\">\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"500\">Fruits A</Text>\n        <DraggableList.Root\n          items={fruitsA}\n          onUpdateItems={setFruitsA}\n          dragNamespace=\"fruits\"\n          aria-label=\"Fruits list A\"\n        />\n      </Stack>\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"500\">Fruits B</Text>\n        <DraggableList.Root\n          items={fruitsB}\n          onUpdateItems={setFruitsB}\n          dragNamespace=\"fruits\"\n          aria-label=\"Fruits list B\"\n        />\n      </Stack>\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"500\">Vegetables</Text>\n        <DraggableList.Root\n          items={veggies}\n          onUpdateItems={setVeggies}\n          dragNamespace=\"vegetables\"\n          aria-label=\"Vegetables list\"\n        />\n      </Stack>\n    </Stack>\n  );\n}\n```\n\nItems can be dragged between Fruits A and Fruits B (same namespace), but the Vegetables list is isolated and will not accept fruit items or vice versa. Omitting `dragNamespace` preserves the default behavior where all lists interoperate.\n\n### Accepting external drops\n\nUse `onExternalDrop` and `acceptExternalTypes` to accept drops from outside Nimbus. Helper functions are provided for common drop types:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([\n    { key: '1', label: 'Existing item' },\n  ]);\n\n  return (\n    <DraggableList.Root\n      items={items}\n      onUpdateItems={setItems}\n      acceptExternalTypes={['text/plain']}\n      onExternalDrop={async (dropItems) => {\n        const results = [];\n        for (const item of dropItems) {\n          if (item.kind === 'text') {\n            const text = await item.getText('text/plain');\n            results.push({ key: crypto.randomUUID(), label: text });\n          }\n        }\n        return results;\n      }}\n      aria-label=\"Drop text here\"\n    />\n  );\n}\n```\n\nFor file and directory drops, use the composable helpers:\n\n```tsx\nimport {\n  createItemsFromFileDrop,\n  createItemsFromDirectoryDrop,\n} from '@commercetools/nimbus';\n\n<DraggableList.Root\n  items={items}\n  onUpdateItems={setItems}\n  acceptExternalTypes={['image/png', 'application/pdf']}\n  onExternalDrop={async (dropItems) => [\n    ...(await createItemsFromFileDrop(dropItems)),\n    ...(await createItemsFromDirectoryDrop(dropItems)),\n  ]}\n  aria-label=\"Drop files here\"\n/>\n```\n\nSee the [`useDragAndDrop` hook documentation](/hooks/use-drag-and-drop) for the full list of helpers and advanced usage.\n\n### Outgoing drag formats\n\nUse `serializeDragItem` to make items droppable into non-Nimbus targets by providing additional format representations:\n\n```tsx\n<DraggableList.Root\n  items={items}\n  onUpdateItems={setItems}\n  serializeDragItem={(item) => ({\n    'text/plain': item.label,\n    'text/html': `<li>${item.label}</li>`,\n  })}\n  aria-label=\"Drag items out\"\n/>\n```\n\n### TypeScript generics\n\nUse TypeScript generics to ensure type safety with your custom item data:\n\n```jsx live-dev\nconst App = () => {\n  type TaskItem = {\n    key: string;\n    label: string;\n    assignee: string;\n    status: 'pending' | 'active' | 'done';\n  };\n\n  const [tasks, setTasks] = useState<TaskItem[]>([\n    { key: '1', label: 'Review code', assignee: 'Alice', status: 'active' },\n    { key: '2', label: 'Write tests', assignee: 'Bob', status: 'pending' },\n  ]);\n\n  return (\n    <DraggableList.Root<TaskItem>\n      items={tasks}\n      onUpdateItems={setTasks}\n      aria-label=\"Team tasks\"\n    >\n      {(item) => (\n        <DraggableList.Item id={item.key}>\n          <Stack direction=\"column\" gap=\"100\" padding=\"200\">\n            <Text fontWeight=\"500\">{item.label}</Text>\n            <Text fontSize=\"sm\" color=\"fg.muted\">\n              {item.assignee} • {item.status}\n            </Text>\n          </Stack>\n        </DraggableList.Item>\n      )}\n    </DraggableList.Root>\n  );\n}\n```\n\n## Component requirements\n\n## Accessibility\n\nThe DraggableList handles most accessibility requirements internally through React Aria's GridList component. However, you must always provide an accessible label using one of these methods:\n\n**Using DraggableList.Field (recommended):**\n\n```tsx\n<DraggableList.Field\n  label={msg.format(labelMessage)}\n  items={items}\n/>\n```\n\n**Using aria-labelledby:**\n\n```tsx\n<label id=\"list-label\">\n  {msg.format(labelMessage)}\n</label>\n<DraggableList.Root\n  aria-labelledby=\"list-label\"\n  items={items}\n/>\n```\n\n**Using aria-label:**\n\n```tsx\n<DraggableList.Root\n  aria-label={msg.format(labelMessage)}\n  items={items}\n/>\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 = \"example-draggable-list\";\n\nexport const Example = () => (\n  <DraggableList.Root\n    id={PERSISTENT_ID}\n    aria-label=\"Task list\"\n    items={items}\n  />\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab` / `Shift+Tab`: Move focus between items and drag handles\n- `Arrow keys`: Navigate between items in the list\n- `Enter` / `Space`: Activate drag mode for the focused item\n- `Arrow keys` (during drag): Move the item up or down in the list\n- `Enter` / `Space` (during drag): Drop the item at the current position\n- `Escape` (during drag): Cancel the drag operation\n\n## API reference\n\n<PropsTable id=\"DraggableList\" />\n\n## Common patterns\n\n### Form integration with validation\n\nIntegrate DraggableList with form libraries like Formik for validated priority lists:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([\n    { key: '1', label: 'Critical bug' },\n    { key: '2', label: 'Feature request' },\n    { key: '3', label: 'Documentation' },\n  ]);\n\n  const [touched, setTouched] = useState(false);\n  const hasMinimumItems = items.length >= 2;\n\n  const handleUpdateItems = useCallback((updated) => {\n    setItems(updated);\n    setTouched(true);\n  }, []);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DraggableList.Field\n        label=\"Priority Order\"\n        description=\"Drag to reorder by priority\"\n        items={items}\n        onUpdateItems={handleUpdateItems}\n        error={touched && !hasMinimumItems ? 'At least 2 items required' : undefined}\n        isInvalid={touched && !hasMinimumItems}\n        aria-label=\"Priority list\"\n      />\n      <Text fontSize=\"sm\" color={hasMinimumItems ? 'positive.11' : 'critical.11'}>\n        {hasMinimumItems ? '✓ Valid' : '✗ Invalid: Add more items'}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n### Dynamic item management\n\nAllow users to add, remove, and reorder items dynamically:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([\n    { key: '1', label: 'Task 1' },\n    { key: '2', label: 'Task 2' },\n  ]);\n  const [nextId, setNextId] = useState(3);\n\n  const addItem = () => {\n    const newItem = {\n      key: nextId.toString(),\n      label: `Task ${nextId}`,\n    };\n    setItems([...items, newItem]);\n    setNextId(nextId + 1);\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DraggableList.Root\n        items={items}\n        removableItems\n        onUpdateItems={setItems}\n        aria-label=\"Task manager\"\n      />\n      <Button size=\"md\" onClick={addItem}>\n        Add Task\n      </Button>\n    </Stack>\n  );\n}\n```\n\n### Synchronized state with external storage\n\nSync list order with external state management or API:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([\n    { key: '1', label: 'Design system' },\n    { key: '2', label: 'API integration' },\n    { key: '3', label: 'Testing' },\n  ]);\n\n  const [lastSaved, setLastSaved] = useState('Not saved');\n\n  const handleUpdateItems = useCallback((updatedItems) => {\n    setItems(updatedItems);\n\n    // Simulate API save\n    setTimeout(() => {\n      setLastSaved(new Date().toLocaleTimeString());\n    }, 500);\n  }, []);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <DraggableList.Root\n        items={items}\n        onUpdateItems={handleUpdateItems}\n        aria-label=\"Project phases\"\n      />\n      <Text fontSize=\"sm\" color=\"fg.muted\">\n        Last saved: {lastSaved}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using DraggableList 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 and items\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList - Basic rendering\", () => {\n  it(\"renders list with items\", () => {\n    render(\n      <NimbusProvider>\n        <DraggableList.Root items={mockItems} aria-label=\"Task list\" />\n      </NimbusProvider>\n    );\n\n    // Verify list renders with grid role\n    expect(\n      screen.getByRole(\"grid\", { name: /task list/i })\n    ).toBeInTheDocument();\n\n    // Verify all items are rendered\n    expect(screen.getAllByRole(\"row\")).toHaveLength(mockItems.length);\n  });\n\n  it(\"renders items with accessible labels\", () => {\n    render(\n      <NimbusProvider>\n        <DraggableList.Root items={mockItems} aria-label=\"Test list\" />\n      </NimbusProvider>\n    );\n\n    mockItems.forEach((item) => {\n      expect(screen.getByLabelText(item.label)).toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Size Variant Tests\n\nVerify different size variants render correctly\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList - Size variants\", () => {\n  it(\"renders with small size\", () => {\n    const items = [{ key: \"1\", label: \"Item 1\" }];\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Root items={items} size=\"sm\" aria-label=\"Small list\" />\n      </NimbusProvider>\n    );\n\n    const grid = screen.getByRole(\"grid\", { name: /small list/i });\n    expect(grid).toBeInTheDocument();\n  });\n\n  it(\"renders with medium size\", () => {\n    const items = [{ key: \"1\", label: \"Item 1\" }];\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Root items={items} size=\"md\" aria-label=\"Medium list\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"grid\")).toBeInTheDocument();\n  });\n});\n```\n\n### Item Removal Tests\n\nTest removable items functionality\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList - Item removal\", () => {\n  it(\"calls onUpdateItems when item is removed\", async () => {\n    const user = userEvent.setup();\n    const handleUpdateItems = vi.fn();\n    const items = [\n      { key: \"1\", label: \"Item 1\" },\n      { key: \"2\", label: \"Item 2\" },\n      { key: \"3\", label: \"Item 3\" },\n    ];\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={items}\n          removableItems\n          onUpdateItems={handleUpdateItems}\n          aria-label=\"Test list\"\n        />\n      </NimbusProvider>\n    );\n\n    // Find and click remove button for first item\n    const removeButtons = screen.getAllByRole(\"button\", {\n      name: /remove/i,\n    });\n    await user.click(removeButtons[0]);\n\n    // Verify callback was called with updated list\n    // Note: The callback receives the updated items array\n    expect(handleUpdateItems).toHaveBeenCalled();\n    const lastCall =\n      handleUpdateItems.mock.calls[handleUpdateItems.mock.calls.length - 1][0];\n    expect(lastCall.length).toBeLessThan(items.length);\n  });\n});\n```\n\n### Controlled Mode Tests\n\nTest controlled state management with onUpdateItems\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList - Controlled mode\", () => {\n  it(\"calls onUpdateItems when items are reordered\", () => {\n    const handleUpdateItems = vi.fn();\n    const items = [\n      { key: \"1\", label: \"Item 1\" },\n      { key: \"2\", label: \"Item 2\" },\n    ];\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={items}\n          onUpdateItems={handleUpdateItems}\n          aria-label=\"Test list\"\n        />\n      </NimbusProvider>\n    );\n\n    // Test that the callback is provided\n    expect(handleUpdateItems).toBeDefined();\n  });\n\n  it(\"calls onUpdateItems when items change\", () => {\n    const handleUpdate = vi.fn();\n    const items = [\n      { key: \"1\", label: \"Item 1\" },\n      { key: \"2\", label: \"Item 2\" },\n    ];\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={items}\n          onUpdateItems={handleUpdate}\n          aria-label=\"Test list\"\n        />\n      </NimbusProvider>\n    );\n\n    // Note: Testing actual drag-and-drop interactions requires browser-based testing\n    // (like Storybook tests). These tests verify your integration patterns.\n    expect(screen.getByRole(\"grid\")).toBeInTheDocument();\n  });\n});\n```\n\n### Custom Rendering Tests\n\nTest custom item rendering with render functions\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList - Custom rendering\", () => {\n  it(\"renders items using custom render function\", () => {\n    const items = [\n      { id: \"1\", title: \"Task 1\", priority: \"High\" },\n      { id: \"2\", title: \"Task 2\", priority: \"Low\" },\n    ];\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={items}\n          getKey={(item) => item.id}\n          aria-label=\"Custom rendered list\"\n        >\n          {(item) => (\n            <DraggableList.Item id={item.id} textValue={item.title}>\n              <div>\n                <div>{item.title}</div>\n                <div>Priority: {item.priority}</div>\n              </div>\n            </DraggableList.Item>\n          )}\n        </DraggableList.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Task 1\")).toBeInTheDocument();\n    expect(screen.getByText(\"Priority: High\")).toBeInTheDocument();\n    expect(screen.getByText(\"Task 2\")).toBeInTheDocument();\n  });\n});\n```\n\n### Controlled Mode Tests\n\nTest controlled updates with onUpdateItems callback\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList - Controlled updates\", () => {\n  it(\"calls onUpdateItems when items are reordered\", async () => {\n    const items = [\n      { key: \"1\", label: \"Item 1\" },\n      { key: \"2\", label: \"Item 2\" },\n    ];\n    const handleUpdate = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={items}\n          onUpdateItems={handleUpdate}\n          aria-label=\"Controlled list\"\n        />\n      </NimbusProvider>\n    );\n\n    // Note: Full drag-and-drop testing requires complex keyboard/mouse simulation\n    // This test verifies the callback is properly connected\n    // The callback may be called on mount for internal state synchronization\n    expect(screen.getByRole(\"grid\")).toBeInTheDocument();\n  });\n\n  it(\"syncs external state changes to list\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={[{ key: \"1\", label: \"Item 1\" }]}\n          aria-label=\"Synced list\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Item 1\")).toBeInTheDocument();\n\n    // Update items prop\n    rerender(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={[\n            { key: \"1\", label: \"Item 1\" },\n            { key: \"2\", label: \"Item 2\" },\n          ]}\n          aria-label=\"Synced list\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Item 2\")).toBeInTheDocument();\n  });\n});\n```\n\n### Empty State Tests\n\nTest empty state rendering and customization\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList - Empty state\", () => {\n  it(\"displays default empty state when list has no items\", () => {\n    render(\n      <NimbusProvider>\n        <DraggableList.Root items={[]} aria-label=\"Empty list\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(/drop items here/i)).toBeInTheDocument();\n  });\n\n  it(\"displays custom empty state message\", () => {\n    render(\n      <NimbusProvider>\n        <DraggableList.Root\n          items={[]}\n          renderEmptyState=\"No tasks available\"\n          aria-label=\"Empty list\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"No tasks available\")).toBeInTheDocument();\n  });\n});\n```\n\n### Field Pattern Tests\n\nTest DraggableList.Field form integration\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { DraggableList, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"DraggableList.Field - Form integration\", () => {\n  it(\"renders field with label and description\", () => {\n    const items = [\n      { key: \"1\", label: \"Task 1\" },\n      { key: \"2\", label: \"Task 2\" },\n    ];\n\n    render(\n      <NimbusProvider>\n        <DraggableList.Field\n          label=\"Task Priority\"\n          description=\"Drag to reorder\"\n          items={items}\n          aria-label=\"Priority field\"\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Task Priority\")).toBeInTheDocument();\n    expect(screen.getByText(\"Drag to reorder\")).toBeInTheDocument();\n  });\n\n  it(\"displays error message when validation fails\", () => {\n    render(\n      <NimbusProvider>\n        <DraggableList.Field\n          label=\"Required List\"\n          items={[]}\n          error=\"This field is required\"\n          isInvalid={true}\n          aria-label=\"Required field\"\n        />\n      </NimbusProvider>\n    );\n\n    // The error is wrapped in FormField.Error component\n    expect(screen.getByText(\"This field is required\")).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-draggablelist--docs)\n- [React Aria Drag and Drop](https://react-spectrum.adobe.com/react-aria/dnd.html)\n",
       "toc": [
         {
           "value": "Getting started",
@@ -283,6 +283,28 @@
           ],
           "parent": "root"
         },
+        {
+          "value": "Single selection",
+          "href": "#single-selection",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multiple selection",
+          "href": "#multiple-selection",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
         {
           "value": "Item removal",
           "href": "#item-removal",
@@ -290,7 +312,7 @@
           "numbering": [
             1,
             3,
-            2
+            4
           ],
           "parent": "root"
         },
@@ -301,7 +323,7 @@
           "numbering": [
             1,
             3,
-            3
+            5
           ],
           "parent": "root"
         },
@@ -312,7 +334,7 @@
           "numbering": [
             1,
             3,
-            4
+            6
           ],
           "parent": "root"
         },
@@ -323,7 +345,7 @@
           "numbering": [
             1,
             3,
-            5
+            7
           ],
           "parent": "root"
         },
@@ -334,7 +356,40 @@
           "numbering": [
             1,
             3,
-            6
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Isolating lists with dragNamespace",
+          "href": "#isolating-lists-with-dragnamespace",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accepting external drops",
+          "href": "#accepting-external-drops",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            10
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Outgoing drag formats",
+          "href": "#outgoing-drag-formats",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            11
           ],
           "parent": "root"
         },
@@ -345,7 +400,7 @@
           "numbering": [
             1,
             3,
-            7
+            12
           ],
           "parent": "root"
         },

package/data/docs/routes/components-inputs-checkbox.json

@@ -375,7 +375,7 @@
       ]
     },
     "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 = () => <Checkbox>Test me</Checkbox>\n```\n\n### Accessibility standards\n\n- **Info and relationships:** Programmatically determine or provide information\n  and relationships conveyed through presentation in text. Use the `<label>`\n  element and the `for` attribute to associate every checkbox with a clear,\n  descriptive label. Ensure screen readers can access and interpret the checkbox\n  label.\n- **Group related checkboxes:** Group related checkboxes using `<fieldset>` and\n  `<legend>` to provide context. Label the checkbox group using `<legend>`.\n- **Use of color:** Avoid relying solely on color to convey information or\n  checkbox state. Ensure the checked/unchecked state is programmatically\n  determinable and conveyed through visual appearance (e.g., the checkbox's\n  state).\n- **Keyboard accessibility:** Make all checkbox functionality operable through a\n  keyboard interface. Enable users to navigate to the checkbox using the Tab\n  key. Allow users to change the checkbox state using the Spacebar or Enter key.\n- **Clear purpose:** Make the purpose of the checkbox clear from the surrounding\n  context or its label. Avoid generic labels like \"Option\" or \"Select.\" Provide\n  specific and descriptive labels.\n- **Focus visible:** Provide a visible keyboard focus indicator for checkboxes.\n  Visually indicate when a checkbox has focus (e.g., highlight, outline, change\n  in appearance). Avoid relying solely on color change for focus indication.\n- **Labels or instructions:** Provide clear labels or instructions for\n  checkboxes. Reinforce the information provided by the `<label>` element. Aid\n  users with cognitive disabilities by providing clear instructions.\n",
+      "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 = () => <Checkbox>Test me</Checkbox>\n```\n\n### Accessibility standards\n\n- **Info and relationships:** Programmatically determine or provide information\n  and relationships conveyed through presentation in text. Use the `<label>`\n  element and the `for` attribute to associate every checkbox with a clear,\n  descriptive label. Ensure screen readers can access and interpret the checkbox\n  label.\n- **Group related checkboxes:** Group related checkboxes using `<fieldset>` and\n  `<legend>` to provide context. Label the checkbox group using `<legend>`.\n- **Use of color:** Avoid relying solely on color to convey information or\n  checkbox state. Ensure the checked/unchecked state is programmatically\n  determinable and conveyed through visual appearance (e.g., the checkbox's\n  state).\n- **Keyboard accessibility:** Make all checkbox functionality operable through a\n  keyboard interface. Enable users to navigate to the checkbox using the Tab\n  key. Allow users to change the checkbox state using the Spacebar.\n- **Clear purpose:** Make the purpose of the checkbox clear from the surrounding\n  context or its label. Avoid generic labels like \"Option\" or \"Select.\" Provide\n  specific and descriptive labels.\n- **Focus visible:** Provide a visible keyboard focus indicator for checkboxes.\n  Visually indicate when a checkbox has focus (e.g., highlight, outline, change\n  in appearance). Avoid relying solely on color change for focus indication.\n- **Labels or instructions:** Provide clear labels or instructions for\n  checkboxes. Reinforce the information provided by the `<label>` element. Aid\n  users with cognitive disabilities by providing clear instructions.\n",
       "toc": [
         {
           "value": "Accessibility",
@@ -401,7 +401,7 @@
       ]
     },
     "dev": {
-      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Checkbox, type CheckboxProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation uses uncontrolled mode:\n\n```jsx live-dev\nconst App = () => (\n  <Checkbox>Accept terms and conditions</Checkbox>\n)\n```\n\n## Usage examples\n\n### Selection states\n\nThe Checkbox supports three selection states: unchecked (default), checked, and indeterminate.\n\n#### Unchecked\n\nThe default state when no selection has been made:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Checkbox>Option 1</Checkbox>\n    <Checkbox>Option 2</Checkbox>\n  </Stack>\n)\n```\n\n#### Checked\n\nUse the `isSelected` prop to indicate a checked state:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Checkbox isSelected>Option 1</Checkbox>\n    <Checkbox isSelected>Option 2</Checkbox>\n  </Stack>\n)\n```\n\n#### Indeterminate\n\nUse the `isIndeterminate` prop to show a partial selection state, commonly used for \"select all\" scenarios:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Checkbox isIndeterminate>Select all</Checkbox>\n    <Checkbox isSelected>Option 1</Checkbox>\n    <Checkbox>Option 2</Checkbox>\n  </Stack>\n)\n```\n\n### Validation and disabled states\n\n#### Invalid state\n\nUse the `isInvalid` prop to indicate validation errors:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Checkbox isInvalid>Required field</Checkbox>\n    <Checkbox isSelected isInvalid>Invalid selection</Checkbox>\n  </Stack>\n)\n```\n\n#### Disabled state\n\nDisable checkbox interaction with the `isDisabled` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Checkbox isDisabled>Disabled checkbox</Checkbox>\n    <Checkbox isSelected isDisabled>Disabled and checked</Checkbox>\n    <Checkbox isIndeterminate isDisabled>Disabled and indeterminate</Checkbox>\n  </Stack>\n)\n```\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<boolean>(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontSize=\"sm\">\n        {displayValue ? 'Notifications enabled' : 'Notifications disabled'}\n      </Text>\n      <Checkbox\n        defaultValue={false}\n        onChange={(isSelected) => {\n          setDisplayValue(isSelected);\n        }}\n      >\n        Enable notifications\n      </Checkbox>\n    </Stack>\n  );\n}\n```\n\nUse uncontrolled mode when you need to capture the selected state without managing state yourself.\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 [isSelected, setIsSelected] = useState<boolean>(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontSize=\"sm\">\n        {isSelected ? 'Terms accepted' : 'Terms not accepted'}\n      </Text>\n      <Checkbox\n        isSelected={isSelected}\n        onChange={setIsSelected}\n      >\n        Accept terms and conditions\n      </Checkbox>\n      <Button\n        size=\"sm\"\n        onClick={() => setIsSelected(!isSelected)}\n      >\n        {isSelected ? 'Uncheck' : 'Check'}\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 selections\n- Clear or programmatically set the value\n- React to changes in real-time\n\n## Component requirements\n\n## Accessibility\n\nThe Checkbox 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 `CheckboxField` pattern component (recommended, if available)\n- Providing label content via the `children` prop:\n\n```tsx\n<Checkbox>\n  {msg.format(checkboxLabelMessage)}\n</Checkbox>\n```\n\n- Associating a `<label>` element with the `Checkbox` using `aria-labelledby`:\n\n```tsx\n<label id=\"checkbox-label\">\n  {msg.format(labelMessage)}\n</label>\n<Checkbox aria-labelledby=\"checkbox-label\" />\n```\n\n- Associating a `<label>` element with the `Checkbox` using `htmlFor`:\n\n```tsx\n<label htmlFor=\"checkbox-id\">\n  {msg.format(labelMessage)}\n</label>\n<Checkbox id=\"checkbox-id\" />\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<Checkbox aria-label={msg.format(labelMessage)} />\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 = \"terms-acceptance-checkbox\";\n\nexport const TermsCheckbox = () => (\n  <Checkbox id={PERSISTENT_ID}>\n    Accept terms and conditions\n  </Checkbox>\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab` / `Shift+Tab`: Navigate to/from the checkbox\n- `Space` / `Enter`: Toggle the checkbox state when focused\n\n## API reference\n\n<PropsTable id=\"Checkbox\" />\n\n## Common patterns\n\n### Checkbox group\n\nGroup related checkboxes together for multiple selections:\n\n```jsx live-dev\nconst App = () => {\n  const [selectedOptions, setSelectedOptions] = useState<string[]>([]);\n\n  const options = [\n    { id: 'option1', label: 'Email notifications' },\n    { id: 'option2', label: 'SMS notifications' },\n    { id: 'option3', label: 'Push notifications' },\n  ];\n\n  const handleToggle = (optionId: string) => {\n    setSelectedOptions((prev) =>\n      prev.includes(optionId)\n        ? prev.filter((id) => id !== optionId)\n        : [...prev, optionId]\n    );\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      {options.map((option) => (\n        <Checkbox\n          key={option.id}\n          isSelected={selectedOptions.includes(option.id)}\n          onChange={() => handleToggle(option.id)}\n        >\n          {option.label}\n        </Checkbox>\n      ))}\n      <Text fontSize=\"sm\">\n        Selected: {selectedOptions.length} of {options.length}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n### Select all pattern\n\nImplement a \"select all\" checkbox with indeterminate state:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([\n    { id: '1', label: 'Item 1', selected: false },\n    { id: '2', label: 'Item 2', selected: true },\n    { id: '3', label: 'Item 3', selected: false },\n  ]);\n\n  const allSelected = items.every((item) => item.selected);\n  const someSelected = items.some((item) => item.selected) && !allSelected;\n\n  const handleSelectAll = (isSelected: boolean) => {\n    setItems((prev) =>\n      prev.map((item) => ({ ...item, selected: isSelected }))\n    );\n  };\n\n  const handleToggleItem = (id: string) => {\n    setItems((prev) =>\n      prev.map((item) =>\n        item.id === id ? { ...item, selected: !item.selected } : item\n      )\n    );\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Checkbox\n        isSelected={allSelected}\n        isIndeterminate={someSelected}\n        onChange={handleSelectAll}\n      >\n        Select all\n      </Checkbox>\n      <Stack direction=\"column\" gap=\"200\" ml=\"600\">\n        {items.map((item) => (\n          <Checkbox\n            key={item.id}\n            isSelected={item.selected}\n            onChange={() => handleToggleItem(item.id)}\n          >\n            {item.label}\n          </Checkbox>\n        ))}\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n### Form integration example\n\nIntegrate checkboxes with form state management:\n\n```jsx live-dev\nconst App = () => {\n  const [formData, setFormData] = useState({\n    acceptTerms: false,\n    subscribeNewsletter: false,\n    shareData: false,\n  });\n\n  const handleChange = (field: string) => (isSelected: boolean) => {\n    setFormData((prev) => ({ ...prev, [field]: isSelected }));\n  };\n\n  const handleSubmit = () => {\n    if (!formData.acceptTerms) {\n      alert('Please accept the terms and conditions');\n      return;\n    }\n    alert('Form submitted!');\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"600\">\n      <Checkbox\n        isSelected={formData.acceptTerms}\n        onChange={handleChange('acceptTerms')}\n        isInvalid={!formData.acceptTerms}\n      >\n        I accept the terms and conditions\n      </Checkbox>\n      <Checkbox\n        isSelected={formData.subscribeNewsletter}\n        onChange={handleChange('subscribeNewsletter')}\n      >\n        Subscribe to newsletter\n      </Checkbox>\n      <Checkbox\n        isSelected={formData.shareData}\n        onChange={handleChange('shareData')}\n      >\n        Allow data sharing for analytics\n      </Checkbox>\n      <Button onClick={handleSubmit}>Submit</Button>\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Checkbox 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 } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Checkbox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Checkbox - Basic rendering\", () => {\n  it(\"renders checkbox element\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox>Test checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    // Verify checkbox is present\n    expect(screen.getByRole(\"checkbox\")).toBeInTheDocument();\n  });\n\n  it(\"renders with label text\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox>Accept terms</Checkbox>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Accept terms\")).toBeInTheDocument();\n  });\n\n  it(\"renders with aria-label when no children provided\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox aria-label=\"Test checkbox\" />\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"checkbox\", { name: /test checkbox/i })\n    ).toBeInTheDocument();\n  });\n\n  it(\"renders unchecked by default\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox>Unchecked checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).not.toBeChecked();\n  });\n});\n```\n\n### Selection State Tests\n\nTest different selection states (checked, unchecked, indeterminate)\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Checkbox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Checkbox - Selection states\", () => {\n  it(\"renders checked state\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isSelected>Checked checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).toBeChecked();\n  });\n\n  it(\"renders indeterminate state\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isIndeterminate>Indeterminate checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    // React Aria sets indeterminate state on the input element, not aria-checked\n    expect(checkbox).toHaveProperty(\"indeterminate\", true);\n  });\n\n  it(\"renders unchecked state explicitly\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isSelected={false}>Unchecked checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).not.toBeChecked();\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with the component\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Checkbox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Checkbox - Interactions\", () => {\n  it(\"toggles when clicked\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Checkbox>Toggle me</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).not.toBeChecked();\n\n    await user.click(checkbox);\n\n    expect(checkbox).toBeChecked();\n  });\n\n  it(\"calls onChange callback when toggled\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <Checkbox onChange={handleChange}>Test checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    await user.click(checkbox);\n\n    expect(handleChange).toHaveBeenCalledWith(true);\n  });\n\n  it(\"toggles with spacebar when focused\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Checkbox>Keyboard toggle</Checkbox>\n      </NimbusProvider>\n    );\n\n    // Use userEvent.tab() instead of element.focus() to avoid act() warnings\n    await user.tab();\n    await user.keyboard(\" \");\n\n    expect(screen.getByRole(\"checkbox\")).toBeChecked();\n  });\n\n  it(\"toggles with enter key when focused\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Checkbox>Enter toggle</Checkbox>\n      </NimbusProvider>\n    );\n\n    // Use userEvent.tab() instead of element.focus() to avoid act() warnings\n    await user.tab();\n    await user.keyboard(\"{Enter}\");\n\n    expect(screen.getByRole(\"checkbox\")).toBeChecked();\n  });\n});\n```\n\n### Testing Controlled Mode\n\nTest controlled component behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Checkbox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Checkbox - Controlled mode\", () => {\n  it(\"displays controlled value\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isSelected={true} onChange={() => {}}>\n          Controlled checkbox\n        </Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).toBeChecked();\n  });\n\n  it(\"updates when controlled value changes\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Checkbox isSelected={false} onChange={() => {}}>\n          Controlled checkbox\n        </Checkbox>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"checkbox\")).not.toBeChecked();\n\n    rerender(\n      <NimbusProvider>\n        <Checkbox isSelected={true} onChange={() => {}}>\n          Controlled checkbox\n        </Checkbox>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"checkbox\")).toBeChecked();\n  });\n\n  it(\"calls onChange when user interacts with controlled checkbox\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <Checkbox isSelected={false} onChange={handleChange}>\n          Controlled checkbox\n        </Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    await user.click(checkbox);\n\n    expect(handleChange).toHaveBeenCalledWith(true);\n  });\n});\n```\n\n### Testing Validation States\n\nTest different validation and state variations\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Checkbox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Checkbox - Validation states\", () => {\n  it(\"renders disabled state\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isDisabled>Disabled checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).toBeDisabled();\n  });\n\n  it(\"does not toggle when disabled\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <Checkbox isDisabled onChange={handleChange}>\n          Disabled checkbox\n        </Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    await user.click(checkbox);\n\n    expect(checkbox).not.toBeChecked();\n    expect(handleChange).not.toHaveBeenCalled();\n  });\n\n  it(\"renders invalid state\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isInvalid>Invalid checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).toHaveAttribute(\"aria-invalid\", \"true\");\n  });\n\n  it(\"renders checked and disabled state\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isSelected isDisabled>\n          Checked and disabled\n        </Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).toBeChecked();\n    expect(checkbox).toBeDisabled();\n  });\n\n  it(\"renders indeterminate and invalid state\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isIndeterminate isInvalid>\n          Indeterminate and invalid\n        </Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    // React Aria sets indeterminate state on the input element, not aria-checked\n    expect(checkbox).toHaveProperty(\"indeterminate\", true);\n    expect(checkbox).toHaveAttribute(\"aria-invalid\", \"true\");\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-checkbox--docs)\n- [React Aria Checkbox](https://react-spectrum.adobe.com/react-aria/Checkbox.html)\n- [ARIA Checkbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)\n\n",
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Checkbox, type CheckboxProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation uses uncontrolled mode:\n\n```jsx live-dev\nconst App = () => (\n  <Checkbox>Accept terms and conditions</Checkbox>\n)\n```\n\n## Usage examples\n\n### Selection states\n\nThe Checkbox supports three selection states: unchecked (default), checked, and indeterminate.\n\n#### Unchecked\n\nThe default state when no selection has been made:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Checkbox>Option 1</Checkbox>\n    <Checkbox>Option 2</Checkbox>\n  </Stack>\n)\n```\n\n#### Checked\n\nUse the `isSelected` prop to indicate a checked state:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Checkbox isSelected>Option 1</Checkbox>\n    <Checkbox isSelected>Option 2</Checkbox>\n  </Stack>\n)\n```\n\n#### Indeterminate\n\nUse the `isIndeterminate` prop to show a partial selection state, commonly used for \"select all\" scenarios:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Checkbox isIndeterminate>Select all</Checkbox>\n    <Checkbox isSelected>Option 1</Checkbox>\n    <Checkbox>Option 2</Checkbox>\n  </Stack>\n)\n```\n\n### Validation and disabled states\n\n#### Invalid state\n\nUse the `isInvalid` prop to indicate validation errors:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Checkbox isInvalid>Required field</Checkbox>\n    <Checkbox isSelected isInvalid>Invalid selection</Checkbox>\n  </Stack>\n)\n```\n\n#### Disabled state\n\nDisable checkbox interaction with the `isDisabled` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Checkbox isDisabled>Disabled checkbox</Checkbox>\n    <Checkbox isSelected isDisabled>Disabled and checked</Checkbox>\n    <Checkbox isIndeterminate isDisabled>Disabled and indeterminate</Checkbox>\n  </Stack>\n)\n```\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<boolean>(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontSize=\"sm\">\n        {displayValue ? 'Notifications enabled' : 'Notifications disabled'}\n      </Text>\n      <Checkbox\n        defaultValue={false}\n        onChange={(isSelected) => {\n          setDisplayValue(isSelected);\n        }}\n      >\n        Enable notifications\n      </Checkbox>\n    </Stack>\n  );\n}\n```\n\nUse uncontrolled mode when you need to capture the selected state without managing state yourself.\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 [isSelected, setIsSelected] = useState<boolean>(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontSize=\"sm\">\n        {isSelected ? 'Terms accepted' : 'Terms not accepted'}\n      </Text>\n      <Checkbox\n        isSelected={isSelected}\n        onChange={setIsSelected}\n      >\n        Accept terms and conditions\n      </Checkbox>\n      <Button\n        size=\"sm\"\n        onClick={() => setIsSelected(!isSelected)}\n      >\n        {isSelected ? 'Uncheck' : 'Check'}\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 selections\n- Clear or programmatically set the value\n- React to changes in real-time\n\n## Component requirements\n\n## Accessibility\n\nThe Checkbox 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 `CheckboxField` pattern component (recommended, if available)\n- Providing label content via the `children` prop:\n\n```tsx\n<Checkbox>\n  {msg.format(checkboxLabelMessage)}\n</Checkbox>\n```\n\n- Associating a `<label>` element with the `Checkbox` using `aria-labelledby`:\n\n```tsx\n<label id=\"checkbox-label\">\n  {msg.format(labelMessage)}\n</label>\n<Checkbox aria-labelledby=\"checkbox-label\" />\n```\n\n- Associating a `<label>` element with the `Checkbox` using `htmlFor`:\n\n```tsx\n<label htmlFor=\"checkbox-id\">\n  {msg.format(labelMessage)}\n</label>\n<Checkbox id=\"checkbox-id\" />\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<Checkbox aria-label={msg.format(labelMessage)} />\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 = \"terms-acceptance-checkbox\";\n\nexport const TermsCheckbox = () => (\n  <Checkbox id={PERSISTENT_ID}>\n    Accept terms and conditions\n  </Checkbox>\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab` / `Shift+Tab`: Navigate to/from the checkbox\n- `Space`: Toggle the checkbox state when focused\n\n## API reference\n\n<PropsTable id=\"Checkbox\" />\n\n## Common patterns\n\n### Checkbox group\n\nGroup related checkboxes together for multiple selections:\n\n```jsx live-dev\nconst App = () => {\n  const [selectedOptions, setSelectedOptions] = useState<string[]>([]);\n\n  const options = [\n    { id: 'option1', label: 'Email notifications' },\n    { id: 'option2', label: 'SMS notifications' },\n    { id: 'option3', label: 'Push notifications' },\n  ];\n\n  const handleToggle = (optionId: string) => {\n    setSelectedOptions((prev) =>\n      prev.includes(optionId)\n        ? prev.filter((id) => id !== optionId)\n        : [...prev, optionId]\n    );\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      {options.map((option) => (\n        <Checkbox\n          key={option.id}\n          isSelected={selectedOptions.includes(option.id)}\n          onChange={() => handleToggle(option.id)}\n        >\n          {option.label}\n        </Checkbox>\n      ))}\n      <Text fontSize=\"sm\">\n        Selected: {selectedOptions.length} of {options.length}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n### Select all pattern\n\nImplement a \"select all\" checkbox with indeterminate state:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([\n    { id: '1', label: 'Item 1', selected: false },\n    { id: '2', label: 'Item 2', selected: true },\n    { id: '3', label: 'Item 3', selected: false },\n  ]);\n\n  const allSelected = items.every((item) => item.selected);\n  const someSelected = items.some((item) => item.selected) && !allSelected;\n\n  const handleSelectAll = (isSelected: boolean) => {\n    setItems((prev) =>\n      prev.map((item) => ({ ...item, selected: isSelected }))\n    );\n  };\n\n  const handleToggleItem = (id: string) => {\n    setItems((prev) =>\n      prev.map((item) =>\n        item.id === id ? { ...item, selected: !item.selected } : item\n      )\n    );\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Checkbox\n        isSelected={allSelected}\n        isIndeterminate={someSelected}\n        onChange={handleSelectAll}\n      >\n        Select all\n      </Checkbox>\n      <Stack direction=\"column\" gap=\"200\" ml=\"600\">\n        {items.map((item) => (\n          <Checkbox\n            key={item.id}\n            isSelected={item.selected}\n            onChange={() => handleToggleItem(item.id)}\n          >\n            {item.label}\n          </Checkbox>\n        ))}\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n### Form integration example\n\nIntegrate checkboxes with form state management:\n\n```jsx live-dev\nconst App = () => {\n  const [formData, setFormData] = useState({\n    acceptTerms: false,\n    subscribeNewsletter: false,\n    shareData: false,\n  });\n\n  const handleChange = (field: string) => (isSelected: boolean) => {\n    setFormData((prev) => ({ ...prev, [field]: isSelected }));\n  };\n\n  const handleSubmit = () => {\n    if (!formData.acceptTerms) {\n      alert('Please accept the terms and conditions');\n      return;\n    }\n    alert('Form submitted!');\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"600\">\n      <Checkbox\n        isSelected={formData.acceptTerms}\n        onChange={handleChange('acceptTerms')}\n        isInvalid={!formData.acceptTerms}\n      >\n        I accept the terms and conditions\n      </Checkbox>\n      <Checkbox\n        isSelected={formData.subscribeNewsletter}\n        onChange={handleChange('subscribeNewsletter')}\n      >\n        Subscribe to newsletter\n      </Checkbox>\n      <Checkbox\n        isSelected={formData.shareData}\n        onChange={handleChange('shareData')}\n      >\n        Allow data sharing for analytics\n      </Checkbox>\n      <Button onClick={handleSubmit}>Submit</Button>\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Checkbox 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 } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Checkbox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Checkbox - Basic rendering\", () => {\n  it(\"renders checkbox element\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox>Test checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    // Verify checkbox is present\n    expect(screen.getByRole(\"checkbox\")).toBeInTheDocument();\n  });\n\n  it(\"renders with label text\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox>Accept terms</Checkbox>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Accept terms\")).toBeInTheDocument();\n  });\n\n  it(\"renders with aria-label when no children provided\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox aria-label=\"Test checkbox\" />\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"checkbox\", { name: /test checkbox/i })\n    ).toBeInTheDocument();\n  });\n\n  it(\"renders unchecked by default\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox>Unchecked checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).not.toBeChecked();\n  });\n});\n```\n\n### Selection State Tests\n\nTest different selection states (checked, unchecked, indeterminate)\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Checkbox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Checkbox - Selection states\", () => {\n  it(\"renders checked state\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isSelected>Checked checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).toBeChecked();\n  });\n\n  it(\"renders indeterminate state\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isIndeterminate>Indeterminate checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    // React Aria sets indeterminate state on the input element, not aria-checked\n    expect(checkbox).toHaveProperty(\"indeterminate\", true);\n  });\n\n  it(\"renders unchecked state explicitly\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isSelected={false}>Unchecked checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).not.toBeChecked();\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with the component\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Checkbox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Checkbox - Interactions\", () => {\n  it(\"toggles when clicked\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Checkbox>Toggle me</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).not.toBeChecked();\n\n    await user.click(checkbox);\n\n    expect(checkbox).toBeChecked();\n  });\n\n  it(\"calls onChange callback when toggled\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <Checkbox onChange={handleChange}>Test checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    await user.click(checkbox);\n\n    expect(handleChange).toHaveBeenCalledWith(true);\n  });\n\n  it(\"toggles with spacebar when focused\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Checkbox>Keyboard toggle</Checkbox>\n      </NimbusProvider>\n    );\n\n    // Use userEvent.tab() instead of element.focus() to avoid act() warnings\n    await user.tab();\n    await user.keyboard(\" \");\n\n    expect(screen.getByRole(\"checkbox\")).toBeChecked();\n  });\n});\n```\n\n### Testing Controlled Mode\n\nTest controlled component behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Checkbox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Checkbox - Controlled mode\", () => {\n  it(\"displays controlled value\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isSelected={true} onChange={() => {}}>\n          Controlled checkbox\n        </Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).toBeChecked();\n  });\n\n  it(\"updates when controlled value changes\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Checkbox isSelected={false} onChange={() => {}}>\n          Controlled checkbox\n        </Checkbox>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"checkbox\")).not.toBeChecked();\n\n    rerender(\n      <NimbusProvider>\n        <Checkbox isSelected={true} onChange={() => {}}>\n          Controlled checkbox\n        </Checkbox>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"checkbox\")).toBeChecked();\n  });\n\n  it(\"calls onChange when user interacts with controlled checkbox\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <Checkbox isSelected={false} onChange={handleChange}>\n          Controlled checkbox\n        </Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    await user.click(checkbox);\n\n    expect(handleChange).toHaveBeenCalledWith(true);\n  });\n});\n```\n\n### Testing Validation States\n\nTest different validation and state variations\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Checkbox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Checkbox - Validation states\", () => {\n  it(\"renders disabled state\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isDisabled>Disabled checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).toBeDisabled();\n  });\n\n  it(\"does not toggle when disabled\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <Checkbox isDisabled onChange={handleChange}>\n          Disabled checkbox\n        </Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    await user.click(checkbox);\n\n    expect(checkbox).not.toBeChecked();\n    expect(handleChange).not.toHaveBeenCalled();\n  });\n\n  it(\"renders invalid state\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isInvalid>Invalid checkbox</Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).toHaveAttribute(\"aria-invalid\", \"true\");\n  });\n\n  it(\"renders checked and disabled state\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isSelected isDisabled>\n          Checked and disabled\n        </Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    expect(checkbox).toBeChecked();\n    expect(checkbox).toBeDisabled();\n  });\n\n  it(\"renders indeterminate and invalid state\", () => {\n    render(\n      <NimbusProvider>\n        <Checkbox isIndeterminate isInvalid>\n          Indeterminate and invalid\n        </Checkbox>\n      </NimbusProvider>\n    );\n\n    const checkbox = screen.getByRole(\"checkbox\");\n    // React Aria sets indeterminate state on the input element, not aria-checked\n    expect(checkbox).toHaveProperty(\"indeterminate\", true);\n    expect(checkbox).toHaveAttribute(\"aria-invalid\", \"true\");\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-checkbox--docs)\n- [React Aria Checkbox](https://react-spectrum.adobe.com/react-aria/Checkbox.html)\n- [ARIA Checkbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)\n\n",
       "toc": [
         {
           "value": "Getting started",