@commercetools/nimbus-mcp 0.1.0 → 2.11.0

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

@@ -0,0 +1,596 @@
+{
+  "meta": {
+    "id": "Components-DraggableList",
+    "title": "Draggable list",
+    "exportName": "DraggableList",
+    "description": "The draggable list allows users to easily reorder or manage a sequence of items via a direct drag-and-drop interaction.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/draggable-list/draggable-list.mdx",
+    "menu": [
+      "Components",
+      "Data Display",
+      "Draggable list"
+    ],
+    "route": "components/data-display/draggable-list",
+    "tags": [
+      "component",
+      "lists",
+      "drag and drop",
+      "interactive"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Interactions",
+        "href": "#interactions",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nThe draggable list component presents structured, ordered content where the\nsequence itself is meaningful. It uses visual and functional cues to enable\nusers to physically manipulate the list order by dragging an item to a new\ninsertion point, providing immediate visual feedback throughout the process.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?m=auto&node-id=8571-40126)\n[Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-draggablelist--docs)\n[React Aria Docs](https://react-spectrum.adobe.com/react-aria/dnd.html)\n\n## Variables\n\nGet familiar with the features.\n\n### Interactions\n\n**Drag, drop and remove**\n\nItems within draggable lists can be lifted and reordered, with an option to have\nitems removable or disabled.\n\n```jsx live\nconst App = () => {\n  const items = [\n    { key: \"1\", label: \"Food\" },\n    { key: \"2\", label: \"Cosmetics\" },\n    { key: \"3\", label: \"Furniture\" },\n    { key: \"4\", label: \"Electronics\" },\n    { key: \"5\", label: \"Clothing\" },\n  ];\n\n  return (\n    <DraggableList.Root\n      aria-label=\"Task list\"\n      items={items}\n      removableItems\n    />\n  );\n}\n```\n\n**Cross list drag and drop**\n\nWith two sections allowing users to pass items between and allowing for\nreordering. While dragging the new location will highlight conveying to the user\nthat they can drop this item in that section.\n\n```jsx live\nconst App = () => {\n  const [leftItems, setLeftItems] = useState([\n    { key: \"1\", label: \"Food\" },\n    { key: \"2\", label: \"Cosmetics\" },\n    { key: \"3\", label: \"Furniture\" },\n    { key: \"4\", label: \"Electronics\" },\n    { key: \"5\", label: \"Clothing\" },\n  ]);\n\n  const [rightItems, setRightItems] = useState([\n    { key: \"6\", label: \"Sport\" },\n    { key: \"7\", label: \"Home\" },\n  ]);\n\n  return (\n    <Flex gap=\"400\">\n      <DraggableList.Root\n        aria-label=\"Left column\"\n        items={leftItems}\n        removableItems\n        onUpdateItems={setLeftItems}\n      />\n      <DraggableList.Root\n        aria-label=\"Right column\"\n        items={rightItems}\n        removableItems\n        onUpdateItems={setRightItems}\n      />\n    </Flex>\n  );\n}\n```\n\n### Size\n\n**Size variants**\n\nDraggable list supports two sizes. Use the smaller size to show a more compact\nexperience.\n\n```jsx live\nconst App = () => {\n  const items = [\n    { key: \"1\", label: \"Small food\" },\n  ];\n\n  const mediumItems = [\n    { key: \"1\", label: \"Medium food\" },\n  ];\n\n  return (\n    <Stack direction=\"horizontal\" gap=\"800\">\n      <DraggableList.Root\n        aria-label=\"Small food list\"\n        items={items}\n        size=\"sm\"\n      />\n      <DraggableList.Root\n        aria-label=\"Medium food list\"\n        items={mediumItems}\n        size=\"md\"\n      />\n    </Stack>\n  );\n}\n```\n\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nThe draggable list component presents structured, ordered content where the\nsequence itself is meaningful. It uses visual and functional cues to enable\nusers to physically manipulate the list order by dragging an item to a new\ninsertion point, providing immediate visual feedback throughout the process.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?m=auto&node-id=8571-40126)\n[Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-draggablelist--docs)\n[React Aria Docs](https://react-spectrum.adobe.com/react-aria/dnd.html)\n\n## Variables\n\nGet familiar with the features.\n\n### Interactions\n\n**Drag, drop and remove**\n\nItems within draggable lists can be lifted and reordered, with an option to have\nitems removable or disabled.\n\n```jsx live\nconst App = () => {\n  const items = [\n    { key: \"1\", label: \"Food\" },\n    { key: \"2\", label: \"Cosmetics\" },\n    { key: \"3\", label: \"Furniture\" },\n    { key: \"4\", label: \"Electronics\" },\n    { key: \"5\", label: \"Clothing\" },\n  ];\n\n  return (\n    <DraggableList.Root\n      aria-label=\"Task list\"\n      items={items}\n      removableItems\n    />\n  );\n}\n```\n\n**Cross list drag and drop**\n\nWith two sections allowing users to pass items between and allowing for\nreordering. While dragging the new location will highlight conveying to the user\nthat they can drop this item in that section.\n\n```jsx live\nconst App = () => {\n  const [leftItems, setLeftItems] = useState([\n    { key: \"1\", label: \"Food\" },\n    { key: \"2\", label: \"Cosmetics\" },\n    { key: \"3\", label: \"Furniture\" },\n    { key: \"4\", label: \"Electronics\" },\n    { key: \"5\", label: \"Clothing\" },\n  ]);\n\n  const [rightItems, setRightItems] = useState([\n    { key: \"6\", label: \"Sport\" },\n    { key: \"7\", label: \"Home\" },\n  ]);\n\n  return (\n    <Flex gap=\"400\">\n      <DraggableList.Root\n        aria-label=\"Left column\"\n        items={leftItems}\n        removableItems\n        onUpdateItems={setLeftItems}\n      />\n      <DraggableList.Root\n        aria-label=\"Right column\"\n        items={rightItems}\n        removableItems\n        onUpdateItems={setRightItems}\n      />\n    </Flex>\n  );\n}\n```\n\n### Size\n\n**Size variants**\n\nDraggable list supports two sizes. Use the smaller size to show a more compact\nexperience.\n\n```jsx live\nconst App = () => {\n  const items = [\n    { key: \"1\", label: \"Small food\" },\n  ];\n\n  const mediumItems = [\n    { key: \"1\", label: \"Medium food\" },\n  ];\n\n  return (\n    <Stack direction=\"horizontal\" gap=\"800\">\n      <DraggableList.Root\n        aria-label=\"Small food list\"\n        items={items}\n        size=\"sm\"\n      />\n      <DraggableList.Root\n        aria-label=\"Medium food list\"\n        items={mediumItems}\n        size=\"md\"\n      />\n    </Stack>\n  );\n}\n```\n\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interactions",
+          "href": "#interactions",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => {\n  const [leftItems, setLeftItems] = useState([\n    { key: \"1\", label: \"Food\" },\n    { key: \"2\", label: \"Cosmetics\" },\n    { key: \"3\", label: \"Furniture\" },\n    { key: \"4\", label: \"Electronics\" },\n    { key: \"5\", label: \"Clothing\" },\n  ]);\n\n  const [rightItems, setRightItems] = useState([\n    { key: \"6\", label: \"Sport\" },\n    { key: \"7\", label: \"Home\" },\n  ]);\n\n  return (\n    <Flex gap=\"400\">\n      <DraggableList.Root\n        aria-label=\"Left column\"\n        items={leftItems}\n        onUpdateItems={setLeftItems}\n      />\n      <DraggableList.Root\n        aria-label=\"Right column\"\n        items={rightItems}\n        onUpdateItems={setRightItems}\n      />\n    </Flex>\n  );\n}\n```\n\n### Accessibility standards\n\n- **Keyboard reordering is essential:** Since drag-and-drop is a complex pointer\n  gesture, a keyboard-accessible method for reordering is mandatory (WCAG 2.5.1\n  Pointer Gestures). This usually involves providing \"Move Up\" and \"Move Down\"\n  buttons or a position input field next to the list item.\n- **ARIA roles:** Use appropriate ARIA roles to convey the list and item\n  structure to screen readers. For interactive lists, `role=\"listbox\"` for the\n  container and `role=\"option\"` for items might be suitable, or use standard\n  semantic lists (`<ul>`, `<li>`) enhanced with ARIA attributes.\n- **Focus management:** Ensure the drag handle or the dedicated keyboard buttons\n  are included in the Tab order and have clear focus indicators.\n- **Status updates:** Announce the result of the reordering to screen reader\n  users using an `aria-live` region (e.g., \"Item moved to position 4\").\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "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",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Working with React Aria drag-and-drop",
+          "href": "#working-with-react-aria-drag-and-drop",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Drag-and-drop behavior",
+          "href": "#drag-and-drop-behavior",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Data format",
+          "href": "#data-format",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "State management",
+          "href": "#state-management",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Item removal",
+          "href": "#item-removal",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom item rendering",
+          "href": "#custom-item-rendering",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled updates",
+          "href": "#controlled-updates",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom empty state",
+          "href": "#custom-empty-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multiple lists",
+          "href": "#multiple-lists",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "TypeScript generics",
+          "href": "#typescript-generics",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            5,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Form integration with validation",
+          "href": "#form-integration-with-validation",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Dynamic item management",
+          "href": "#dynamic-item-management",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Synchronized state with external storage",
+          "href": "#synchronized-state-with-external-storage",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size Variant Tests",
+          "href": "#size-variant-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Item Removal Tests",
+          "href": "#item-removal-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled Mode Tests",
+          "href": "#controlled-mode-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom Rendering Tests",
+          "href": "#custom-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled Mode Tests",
+          "href": "#controlled-mode-tests-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Empty State Tests",
+          "href": "#empty-state-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Field Pattern Tests",
+          "href": "#field-pattern-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            9
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nDraggable list guidelines ensure that reordering is intuitive and accessible by\nproviding a clear drag handle, visual feedback on the insertion point, and a\nnecessary keyboard alternative for manipulation.\n\n### Best practices\n\n- **Clear drag handle:** the distinct drag handle icon on each list item will\n  explicitly communicate that the item is movable and defines the primary target\n  for the drag action.\n- **Show insertion point:** As the user drags the item, clearly indicate the\n  exact target position where the item will be dropped. This is often done by\n  visually highlighting the gap or line where the item will be inserted.\n- **Maintain performance:** Ensure the drag-and-drop animation is smooth and\n  responsive without lag, especially in long lists.\n- **Limited scope:** Only allow items to be dragged within the confines of the\n  current list; do not allow dragging to other unrelated sections unless\n  explicitly necessary for the application's core function.\n- **Use the right cursor:** The mouse cursor will change to a hand or grab\n  cursor when hovering over the drag handle to visually reinforce interactivity.\n- **Lift the item (visual pickup):** When the user clicks the handle to start\n  dragging, the appearance will immediately change to separate it visually from\n  the rest of the list.\n- **Maintain stability:** Keep the other list items stable while one is being\n  dragged. Do not introduce excessive animations or visual clutter that makes it\n  hard to see the remaining order.\n- **Provide an accessible alternative:** Always include keyboard-operable \"Move\n  Up\" and \"Move Down\" buttons for each list item, as drag-and-drop actions are\n  inaccessible to many keyboard-only and assistive technology users.\n\n### Usage\n\nThe draggable list component is used when the explicit, user-defined order of\nitems directly impacts the application's logic or user outcome, such as\nsequencing workflow steps or organizing a custom list.\n\n> [!TIP]\\\n> When to use\n\n- **User-defined order:** When the order of items directly impacts the\n  application's logic or user outcome.\n- **Short to medium lists:** For lists that are manageable without extensive\n  scrolling where dragging is quick.\n- **Spatial relationship is key:** When the user benefits from seeing the new\n  sequence immediately take effect visually.\n\n> [!CAUTION]\\\n> When not to use\n\n- **Simple filtering/sorting:** If the only goal is to change the list's view\n  (e.g., sort alphabetically, filter by date), use standard sort/filter controls\n  instead.\n- **Very long lists:** Dragging items across many screen heights or dozens of\n  items is tedious and inefficient.\n- **Actions are primary:** If the main interaction is performing an action on\n  the item (e.g., edit, delete) rather than changing its position. Use a\n  standard list component with action buttons.\n\n### Draggable list in use\n\n> [!TIP]\\\n> **Do**\n>\n> - Do save the new order instantly or provide a clear \"Save Order\" button after\n>   the drop action is completed.\n> - Do ensure all relevant metadata (e.g., numbering) updates automatically\n>   after a successful drop.\n\n```jsx live\nconst App = () => {\n  const [leftItems, setLeftItems] = useState([\n    { key: \"1\", label: \"Food\" },\n    { key: \"2\", label: \"Cosmetics\" },\n    { key: \"3\", label: \"Furniture\" },\n    { key: \"4\", label: \"Electronics\" },\n    { key: \"5\", label: \"Clothing\" },\n  ]);\n\n  const [rightItems, setRightItems] = useState([\n    { key: \"6\", label: \"Sport\" },\n    { key: \"7\", label: \"Home\" },\n  ]);\n\n  return (\n    <Flex gap=\"400\">\n      <DraggableList.Root\n        aria-label=\"Left column\"\n        items={leftItems}\n        onUpdateItems={setLeftItems}\n      />\n      <DraggableList.Root\n        aria-label=\"Right column\"\n        items={rightItems}\n        onUpdateItems={setRightItems}\n      />\n    </Flex>\n  );\n}\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't make the entire list item the draggable area; this interferes with\n>   clicking links, checkboxes, or actions within the item.\n> - Don't interrupt the drag action with tooltips, modals, or sudden page\n>   refreshes.\n> - Don't forget to provide accessible alternatives for reordering (see\n>   Accessibility).\n\n```jsx live\nconst App = () => {\n  const initialLeft = [\n    { key: \"1\", label: \"Food\" },\n    { key: \"2\", label: \"Cosmetics\" },\n    { key: \"3\", label: \"Furniture\" },\n    { key: \"4\", label: \"Electronics\" },\n    { key: \"5\", label: \"Clothing\" },\n  ];\n\n  const initialRight = [\n    { key: \"6\", label: \"Sport\" },\n    { key: \"7\", label: \"Home\" },\n  ];\n\n  const [leftItems, setLeftItems] = useState(initialLeft);\n  const [rightItems, setRightItems] = useState(initialRight);\n\n  const handleLeftUpdate = (items) => {\n    setLeftItems(items);\n    setTimeout(() => {\n      setLeftItems(initialLeft);\n      setRightItems(initialRight);\n    }, 500);\n  };\n\n  const handleRightUpdate = (items) => {\n    setRightItems(items);\n    setTimeout(() => {\n      setLeftItems(initialLeft);\n      setRightItems(initialRight);\n    }, 500);\n  };\n\n  return (\n    <Flex gap=\"400\">\n      <DraggableList.Root\n        aria-label=\"Left column\"\n        items={leftItems}\n        onUpdateItems={handleLeftUpdate}\n      />\n      <DraggableList.Root\n        aria-label=\"Right column\"\n        items={rightItems}\n        onUpdateItems={handleRightUpdate}\n      />\n    </Flex>\n  );\n}\n```\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Draggable list in use",
+          "href": "#draggable-list-in-use",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}