@commercetools/nimbus-mcp 2.11.0 → 3.1.0

package/data/docs/routes/home-getting-started-bundler-plugins.json

@@ -0,0 +1,248 @@
+{
+  "meta": {
+    "id": "Home-BundlerPlugins-1749667200000",
+    "title": "Bundler Plugins",
+    "description": "Webpack and Vite plugins for optional Nimbus dependency resolution",
+    "order": 7,
+    "repoPath": "packages/nimbus/src/docs/home-bundler-plugins.mdx",
+    "menu": [
+      "Home",
+      "Getting Started",
+      "Bundler Plugins"
+    ],
+    "route": "home/getting-started/bundler-plugins",
+    "tags": [
+      "guide",
+      "plugins",
+      "webpack",
+      "vite",
+      "build",
+      "optional-dependency"
+    ],
+    "toc": [
+      {
+        "value": "When to use",
+        "href": "#when-to-use",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Entry points",
+        "href": "#entry-points",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Vite",
+        "href": "#vite",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Webpack",
+        "href": "#webpack",
+        "depth": 2,
+        "numbering": [
+          1,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "How detection works",
+        "href": "#how-detection-works",
+        "depth": 2,
+        "numbering": [
+          1,
+          5
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "What gets stubbed",
+        "href": "#what-gets-stubbed",
+        "depth": 2,
+        "numbering": [
+          1,
+          6
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Writing safe shared code",
+        "href": "#writing-safe-shared-code",
+        "depth": 2,
+        "numbering": [
+          1,
+          7
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Guard with a runtime check",
+        "href": "#guard-with-a-runtime-check",
+        "depth": 3,
+        "numbering": [
+          1,
+          7,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Guard with lazy imports",
+        "href": "#guard-with-lazy-imports",
+        "depth": 3,
+        "numbering": [
+          1,
+          7,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Feature flags",
+        "href": "#feature-flags",
+        "depth": 3,
+        "numbering": [
+          1,
+          7,
+          3
+        ],
+        "parent": "root"
+      }
+    ],
+    "icon": "Extension",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      }
+    ]
+  },
+  "mdx": "\n# Bundler Plugins\n\nNimbus ships Vite and webpack plugins that let build tools treat\n`@commercetools/nimbus` as an **optional dependency**. When Nimbus is installed,\nthe plugins are no-ops. When it is not installed, they stub every Nimbus import\nso the build succeeds and zero Nimbus code lands in the bundle.\n\n**The plugins solve build errors, not runtime errors.** Stubbed imports resolve\nto `undefined` — any code that renders a Nimbus component or calls a Nimbus\nfunction will fail at runtime unless it is guarded. See\n[Writing safe shared code](#writing-safe-shared-code) for patterns.\n\n## When to use\n\nUse these plugins in **shared build tooling** that produces bundles for\napplications that may or may not depend on Nimbus. Without the plugins, any\n`import … from '@commercetools/nimbus'` in shared code causes a build failure\nfor apps that haven't installed Nimbus.\n\nThe typical scenario: a shared package imports Nimbus components but is consumed\nby both Nimbus-enabled apps and non-Nimbus apps. The plugins let the shared\npackage compile in both environments. The shared code itself is responsible for\nchecking whether Nimbus is available before rendering anything from it.\n\n## Entry points\n\n| Entry point                             | Export                           |\n| --------------------------------------- | -------------------------------- |\n| `@commercetools/nimbus/plugins/vite`    | `UNSAFE_nimbusOptionalDependency`       |\n| `@commercetools/nimbus/plugins/webpack` | `UNSAFE_NimbusOptionalDependencyPlugin` |\n| `@commercetools/nimbus/plugins/stub`    | _(empty CJS module)_             |\n\nAll entry points are standalone — they do **not** import the Nimbus runtime.\n\n## Vite\n\n```ts\n// vite.config.ts\nimport { UNSAFE_nimbusOptionalDependency } from \"@commercetools/nimbus/plugins/vite\";\n\nexport default defineConfig({\n  plugins: [UNSAFE_nimbusOptionalDependency()],\n});\n```\n\nThe plugin runs with `enforce: \"pre\"` so its `resolveId` hook fires before\nVite's default resolver (required in monorepos where Vite would otherwise follow\nthe workspace symlink). Matching imports are redirected via `resolveId` + `load`\nto a virtual CJS module (`module.exports = {}`). The `.cjs` extension on the\nvirtual ID triggers Rolldown's CJS-to-ESM interop, allowing named imports to\nresolve to `undefined` at runtime instead of failing with `MISSING_EXPORT`. No\nphysical file is written to disk.\n\n## Webpack\n\n```js\n// webpack.config.js\nconst {\n  UNSAFE_NimbusOptionalDependencyPlugin,\n} = require(\"@commercetools/nimbus/plugins/webpack\");\n\nmodule.exports = {\n  plugins: [new UNSAFE_NimbusOptionalDependencyPlugin()],\n};\n```\n\nThe plugin accesses webpack's built-in `NormalModuleReplacementPlugin` via\n`compiler.webpack` (webpack 5+). It redirects matching imports to the physical\n`@commercetools/nimbus/plugins/stub` entry point (`module.exports = {}`).\nWebpack's CJS-to-ESM interop is natively lenient — unmatched named imports\nresolve to `undefined` at runtime without a build error.\n\n## How detection works\n\nAt build startup, the plugin calls:\n\n```js\nrequire.resolve(\"@commercetools/nimbus\", { paths: [process.cwd()] });\n```\n\n- **Resolves** → Nimbus is installed. The plugin becomes a **no-op**.\n- **Throws** → Nimbus is not installed. The plugin activates and stubs all\n  matching imports.\n\n`{ paths: [process.cwd()] }` checks from the **application root**, not the\nplugin's own `node_modules`. This matters in monorepos where the build tool may\nhave Nimbus while the app being built does not.\n\nBoth plugins accept a `{ cwd }` option to override detection, and\n`{ UNSAFE_forceStub: true }` to bypass detection entirely — useful when\ndependency hoisting causes Nimbus to resolve from a parent `node_modules` even\nthough the app never declared it.\n\n## What gets stubbed\n\n| Import                                        | Stubbed? |\n| --------------------------------------------- | -------- |\n| `@commercetools/nimbus`                       | Yes      |\n| `@commercetools/nimbus/components/Button`     | Yes      |\n| `@commercetools/nimbus/setup-jsdom-polyfills` | Yes      |\n| `@commercetools/nimbus/plugins/webpack`       | No       |\n| `@commercetools/nimbus/plugins/vite`          | No       |\n| `@commercetools/nimbus/plugins/stub`          | No       |\n| `@commercetools/nimbus/plugins`               | No       |\n| `@commercetools/nimbus-icons`                 | No       |\n| `@commercetools/nimbus-tokens`                | No       |\n\nThe `/plugins` and `/plugins/*` subpaths are excluded to avoid circular\nreplacement.\n\n## Writing safe shared code\n\nWhen stubbing is active, every named import from `@commercetools/nimbus`\n(`Button`, `NimbusProvider`, etc.) is `undefined`. Default and namespace imports\n(`import Nimbus from …` or `import * as Nimbus from …`) resolve to the truthy\n`{}` stub object — guard with individual named imports, not `if (!Nimbus)`.\n\nCode that uses these values without a guard will crash at runtime. The build will not warn you — from the\nbundler's perspective, the import succeeded.\n\n### Guard with a runtime check\n\n```tsx\nimport { Button } from \"@commercetools/nimbus\";\n\nfunction MyAction({ label, onClick }) {\n  // Button is undefined when Nimbus is stubbed out\n  if (!Button) {\n    return <button onClick={onClick}>{label}</button>;\n  }\n  return <Button onPress={onClick}>{label}</Button>;\n}\n```\n\n### Guard with lazy imports\n\n```tsx\nconst NimbusButton = lazy(() =>\n  import(\"@commercetools/nimbus\").then((m) => ({ default: m.Button }))\n);\n\nfunction MyAction({ label, onClick }) {\n  return (\n    <Suspense fallback={<button onClick={onClick}>{label}</button>}>\n      <NimbusButton onPress={onClick}>{label}</NimbusButton>\n    </Suspense>\n  );\n}\n```\n\n### Feature flags\n\nIf your app already has a feature-flag system, gate the entire Nimbus code path\nbehind a flag rather than checking individual imports:\n\n```tsx\nif (flags.nimbusEnabled) {\n  return <NimbusButton onPress={onClick}>{label}</NimbusButton>;\n}\nreturn <button onClick={onClick}>{label}</button>;\n```\n\nThe key principle: **the plugins make the build pass, your code makes the app\nwork.** Any path that touches a Nimbus import must handle the possibility that\nit resolved to `undefined`.\n",
+  "views": {
+    "overview": {
+      "mdx": "\n# Bundler Plugins\n\nNimbus ships Vite and webpack plugins that let build tools treat\n`@commercetools/nimbus` as an **optional dependency**. When Nimbus is installed,\nthe plugins are no-ops. When it is not installed, they stub every Nimbus import\nso the build succeeds and zero Nimbus code lands in the bundle.\n\n**The plugins solve build errors, not runtime errors.** Stubbed imports resolve\nto `undefined` — any code that renders a Nimbus component or calls a Nimbus\nfunction will fail at runtime unless it is guarded. See\n[Writing safe shared code](#writing-safe-shared-code) for patterns.\n\n## When to use\n\nUse these plugins in **shared build tooling** that produces bundles for\napplications that may or may not depend on Nimbus. Without the plugins, any\n`import … from '@commercetools/nimbus'` in shared code causes a build failure\nfor apps that haven't installed Nimbus.\n\nThe typical scenario: a shared package imports Nimbus components but is consumed\nby both Nimbus-enabled apps and non-Nimbus apps. The plugins let the shared\npackage compile in both environments. The shared code itself is responsible for\nchecking whether Nimbus is available before rendering anything from it.\n\n## Entry points\n\n| Entry point                             | Export                           |\n| --------------------------------------- | -------------------------------- |\n| `@commercetools/nimbus/plugins/vite`    | `UNSAFE_nimbusOptionalDependency`       |\n| `@commercetools/nimbus/plugins/webpack` | `UNSAFE_NimbusOptionalDependencyPlugin` |\n| `@commercetools/nimbus/plugins/stub`    | _(empty CJS module)_             |\n\nAll entry points are standalone — they do **not** import the Nimbus runtime.\n\n## Vite\n\n```ts\n// vite.config.ts\nimport { UNSAFE_nimbusOptionalDependency } from \"@commercetools/nimbus/plugins/vite\";\n\nexport default defineConfig({\n  plugins: [UNSAFE_nimbusOptionalDependency()],\n});\n```\n\nThe plugin runs with `enforce: \"pre\"` so its `resolveId` hook fires before\nVite's default resolver (required in monorepos where Vite would otherwise follow\nthe workspace symlink). Matching imports are redirected via `resolveId` + `load`\nto a virtual CJS module (`module.exports = {}`). The `.cjs` extension on the\nvirtual ID triggers Rolldown's CJS-to-ESM interop, allowing named imports to\nresolve to `undefined` at runtime instead of failing with `MISSING_EXPORT`. No\nphysical file is written to disk.\n\n## Webpack\n\n```js\n// webpack.config.js\nconst {\n  UNSAFE_NimbusOptionalDependencyPlugin,\n} = require(\"@commercetools/nimbus/plugins/webpack\");\n\nmodule.exports = {\n  plugins: [new UNSAFE_NimbusOptionalDependencyPlugin()],\n};\n```\n\nThe plugin accesses webpack's built-in `NormalModuleReplacementPlugin` via\n`compiler.webpack` (webpack 5+). It redirects matching imports to the physical\n`@commercetools/nimbus/plugins/stub` entry point (`module.exports = {}`).\nWebpack's CJS-to-ESM interop is natively lenient — unmatched named imports\nresolve to `undefined` at runtime without a build error.\n\n## How detection works\n\nAt build startup, the plugin calls:\n\n```js\nrequire.resolve(\"@commercetools/nimbus\", { paths: [process.cwd()] });\n```\n\n- **Resolves** → Nimbus is installed. The plugin becomes a **no-op**.\n- **Throws** → Nimbus is not installed. The plugin activates and stubs all\n  matching imports.\n\n`{ paths: [process.cwd()] }` checks from the **application root**, not the\nplugin's own `node_modules`. This matters in monorepos where the build tool may\nhave Nimbus while the app being built does not.\n\nBoth plugins accept a `{ cwd }` option to override detection, and\n`{ UNSAFE_forceStub: true }` to bypass detection entirely — useful when\ndependency hoisting causes Nimbus to resolve from a parent `node_modules` even\nthough the app never declared it.\n\n## What gets stubbed\n\n| Import                                        | Stubbed? |\n| --------------------------------------------- | -------- |\n| `@commercetools/nimbus`                       | Yes      |\n| `@commercetools/nimbus/components/Button`     | Yes      |\n| `@commercetools/nimbus/setup-jsdom-polyfills` | Yes      |\n| `@commercetools/nimbus/plugins/webpack`       | No       |\n| `@commercetools/nimbus/plugins/vite`          | No       |\n| `@commercetools/nimbus/plugins/stub`          | No       |\n| `@commercetools/nimbus/plugins`               | No       |\n| `@commercetools/nimbus-icons`                 | No       |\n| `@commercetools/nimbus-tokens`                | No       |\n\nThe `/plugins` and `/plugins/*` subpaths are excluded to avoid circular\nreplacement.\n\n## Writing safe shared code\n\nWhen stubbing is active, every named import from `@commercetools/nimbus`\n(`Button`, `NimbusProvider`, etc.) is `undefined`. Default and namespace imports\n(`import Nimbus from …` or `import * as Nimbus from …`) resolve to the truthy\n`{}` stub object — guard with individual named imports, not `if (!Nimbus)`.\n\nCode that uses these values without a guard will crash at runtime. The build will not warn you — from the\nbundler's perspective, the import succeeded.\n\n### Guard with a runtime check\n\n```tsx\nimport { Button } from \"@commercetools/nimbus\";\n\nfunction MyAction({ label, onClick }) {\n  // Button is undefined when Nimbus is stubbed out\n  if (!Button) {\n    return <button onClick={onClick}>{label}</button>;\n  }\n  return <Button onPress={onClick}>{label}</Button>;\n}\n```\n\n### Guard with lazy imports\n\n```tsx\nconst NimbusButton = lazy(() =>\n  import(\"@commercetools/nimbus\").then((m) => ({ default: m.Button }))\n);\n\nfunction MyAction({ label, onClick }) {\n  return (\n    <Suspense fallback={<button onClick={onClick}>{label}</button>}>\n      <NimbusButton onPress={onClick}>{label}</NimbusButton>\n    </Suspense>\n  );\n}\n```\n\n### Feature flags\n\nIf your app already has a feature-flag system, gate the entire Nimbus code path\nbehind a flag rather than checking individual imports:\n\n```tsx\nif (flags.nimbusEnabled) {\n  return <NimbusButton onPress={onClick}>{label}</NimbusButton>;\n}\nreturn <button onClick={onClick}>{label}</button>;\n```\n\nThe key principle: **the plugins make the build pass, your code makes the app\nwork.** Any path that touches a Nimbus import must handle the possibility that\nit resolved to `undefined`.\n",
+      "toc": [
+        {
+          "value": "When to use",
+          "href": "#when-to-use",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Entry points",
+          "href": "#entry-points",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Vite",
+          "href": "#vite",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Webpack",
+          "href": "#webpack",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "How detection works",
+          "href": "#how-detection-works",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "What gets stubbed",
+          "href": "#what-gets-stubbed",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Writing safe shared code",
+          "href": "#writing-safe-shared-code",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Guard with a runtime check",
+          "href": "#guard-with-a-runtime-check",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Guard with lazy imports",
+          "href": "#guard-with-lazy-imports",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Feature flags",
+          "href": "#feature-flags",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}

package/data/docs/routes/hooks-usedraganddrop.json

@@ -0,0 +1,310 @@
+{
+  "meta": {
+    "id": "useDragAndDrop",
+    "title": "useDragAndDrop",
+    "description": "shared drag-and-drop hook for Nimbus collection components",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/hooks/use-drag-and-drop/use-drag-and-drop.mdx",
+    "menu": [
+      "Hooks",
+      "useDragAndDrop"
+    ],
+    "route": "hooks/usedraganddrop",
+    "tags": [
+      "drag",
+      "drop",
+      "reorder",
+      "dnd"
+    ],
+    "toc": [
+      {
+        "value": "Getting started",
+        "href": "#getting-started",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Basic reorderable DataTable",
+        "href": "#basic-reorderable-datatable",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Namespace isolation",
+        "href": "#namespace-isolation",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "External drops",
+        "href": "#external-drops",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Helper functions",
+        "href": "#helper-functions",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Outgoing formats",
+        "href": "#outgoing-formats",
+        "depth": 2,
+        "numbering": [
+          1,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "State handler factories",
+        "href": "#state-handler-factories",
+        "depth": 2,
+        "numbering": [
+          1,
+          5
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "createListDataHandlers(list)",
+        "href": "#createlistdatahandlerslist",
+        "depth": 3,
+        "numbering": [
+          1,
+          5,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "createArrayHandlers(setItems, getKey?)",
+        "href": "#createarrayhandlerssetitems-getkey",
+        "depth": 3,
+        "numbering": [
+          1,
+          5,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Using with DataTable",
+        "href": "#using-with-datatable",
+        "depth": 2,
+        "numbering": [
+          1,
+          6
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "API reference",
+        "href": "#api-reference",
+        "depth": 2,
+        "numbering": [
+          1,
+          7
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "DragAndDropProps<T>",
+        "href": "#draganddroppropst",
+        "depth": 3,
+        "numbering": [
+          1,
+          7,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "UseDragAndDropOptions<T>",
+        "href": "#usedraganddropoptionst",
+        "depth": 3,
+        "numbering": [
+          1,
+          7,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      }
+    ]
+  },
+  "mdx": "\n# useDragAndDrop\n\nA shared hook that wraps React Aria's drag-and-drop system with namespace isolation,\nexternal drop support, outgoing format serialization, and state handler factories.\nReturns `{ dragAndDropHooks }` to pass to any supported React Aria collection component.\n\n## Getting started\n\n```tsx\nimport { useDragAndDrop, createArrayHandlers } from \"@commercetools/nimbus\";\n```\n\n### Basic reorderable DataTable\n\n```tsx\nimport { DataTable, useDragAndDrop, createArrayHandlers } from \"@commercetools/nimbus\";\n\nconst [rows, setRows] = useState([\n  { id: \"1\", name: \"Alice\", role: \"Admin\" },\n  { id: \"2\", name: \"Bob\", role: \"User\" },\n  { id: \"3\", name: \"Carol\", role: \"Manager\" },\n]);\n\nconst columns = [\n  { id: \"name\", header: \"Name\", accessor: (row) => row.name },\n  { id: \"role\", header: \"Role\", accessor: (row) => row.role },\n];\n\nconst { dragAndDropHooks } = useDragAndDrop({\n  ...createArrayHandlers(setRows, (row) => row.id),\n});\n\n<DataTable columns={columns} rows={rows} dragAndDropHooks={dragAndDropHooks} />\n```\n\n> [!NOTE]\n> DraggableList uses `useDragAndDrop` internally — you don't need to call it yourself.\n> Use the hook directly when adding drag-and-drop to other components like DataTable.\n\n## Namespace isolation\n\nUse `dragNamespace` to prevent drag-and-drop between unrelated lists on the same page:\n\n```tsx\nconst { dragAndDropHooks: fruitHooks } = useDragAndDrop({\n  dragNamespace: \"fruits\",\n  ...createArrayHandlers(setFruits),\n});\n\nconst { dragAndDropHooks: veggieHooks } = useDragAndDrop({\n  dragNamespace: \"vegetables\",\n  ...createArrayHandlers(setVeggies),\n});\n```\n\nLists sharing a namespace can exchange items. Lists with different namespaces (or one\nnamespaced and one not) reject each other's drops. Omitting `dragNamespace` preserves\nthe default behavior where all lists interoperate.\n\n## External drops\n\nAccept drops from outside Nimbus (plain text, files, directories) using `onExternalDrop`\nand `acceptExternalTypes`:\n\n```tsx\nimport { useDragAndDrop, createItemsFromFileDrop } from \"@commercetools/nimbus\";\nimport { DIRECTORY_DRAG_TYPE } from \"react-aria-components\";\n\nconst { dragAndDropHooks } = useDragAndDrop({\n  onExternalDrop: createItemsFromFileDrop,\n  acceptExternalTypes: [\"image/png\", \"image/jpeg\", \"application/pdf\"],\n  ...createArrayHandlers(setItems),\n});\n```\n\n### Helper functions\n\nSix composable helpers for common `onExternalDrop` patterns:\n\n| Helper | Accepts | Returns |\n|--------|---------|---------|\n| `createItemsFromTextDrop(items, type?)` | `TextDropItem` | `{ key, label }` |\n| `createItemsFromFileDrop(items)` | `FileDropItem` | `{ key, label, fileName, fileType, file }` |\n| `createItemsFromDirectoryDrop(items)` | `DirectoryDropItem` | `{ key, label, fileName, fileType, file, directory }` |\n| `createItemsFromJsonDrop(items)` | `TextDropItem` with `application/json` | `{ key, label, data }` |\n| `createItemsFromImageDrop(items)` | `FileDropItem` with `image/*` | `{ key, label, fileName, fileType, file, objectUrl }` |\n| `createItemsFromCsvDrop(items)` | `TextDropItem` with `text/csv` | `{ key, label, row, headers }` |\n\nCompose multiple helpers for mixed drop types:\n\n```tsx\nonExternalDrop={async (items) => [\n  ...(await createItemsFromTextDrop(items)),\n  ...(await createItemsFromFileDrop(items)),\n  ...(await createItemsFromDirectoryDrop(items)),\n]}\n```\n\n> [!NOTE]\n> Avoid combining `createItemsFromFileDrop` with `createItemsFromImageDrop` — file drop\n> processes all files including images, so image files would appear twice. Use one or the other.\n\n> [!WARNING]\n> `createItemsFromImageDrop` creates object URLs via `URL.createObjectURL()`.\n> Consumers must call `URL.revokeObjectURL(item.objectUrl)` when items are removed.\n\n## Outgoing formats\n\nUse `serializeDragItem` to make items droppable into non-Nimbus targets:\n\n```tsx\nconst { dragAndDropHooks } = useDragAndDrop({\n  serializeDragItem: (item) => ({\n    \"text/plain\": item.label,\n    \"text/html\": `<li>${item.label}</li>`,\n  }),\n  ...createArrayHandlers(setItems),\n});\n```\n\n## State handler factories\n\nTwo factories that return all four state mutation callbacks (`onInsertItems`,\n`onAppendItems`, `onReorder`, `onRemoveItems`):\n\n### `createListDataHandlers(list)`\n\nFor React Aria's `useListData`:\n\n```tsx\nimport { useListData } from \"react-stately\";\n\nconst list = useListData({ initialItems: items, getKey });\nconst { dragAndDropHooks } = useDragAndDrop({\n  ...createListDataHandlers(list),\n});\n```\n\n### `createArrayHandlers(setItems, getKey?)`\n\nFor plain `useState` arrays:\n\n```tsx\nconst [items, setItems] = useState(initialItems);\nconst { dragAndDropHooks } = useDragAndDrop({\n  ...createArrayHandlers(setItems, (item) => item.key),\n});\n```\n\nIf you need to customize state handling beyond what these factories provide — for example,\npersisting the new list order to an API or combining drag-and-drop with undo/redo — see the\n[React Aria drag and drop documentation](https://react-aria.adobe.com/dnd) for guidance on\nbuilding custom state handlers.\n\n## Using with DataTable\n\nDataTable accepts `dragAndDropHooks` as an optional passthrough prop:\n\n```tsx\nimport { DataTable, useDragAndDrop, createArrayHandlers } from \"@commercetools/nimbus\";\n\nconst [rows, setRows] = useState(initialRows);\nconst { dragAndDropHooks } = useDragAndDrop({\n  dragNamespace: \"my-table\",\n  ...createArrayHandlers(setRows, (row) => row.id),\n});\n\n<DataTable columns={columns} rows={rows} dragAndDropHooks={dragAndDropHooks} />\n```\n\nThe `dragAndDropHooks` prop is also available on `DataTable.Table` for the compound component API.\n\n## API reference\n\n### `DragAndDropProps<T>`\n\nConsumer-facing props, intended to be intersected into component prop types:\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `dragNamespace` | `string` | — | Isolate DnD to collections sharing the same namespace |\n| `onExternalDrop` | `(items: DropItem[]) => T[] \\| Promise<T[]>` | — | Convert external drops into collection items |\n| `acceptExternalTypes` | `Array<string \\| symbol>` | — | Drag types to accept from external sources |\n| `externalDropOperation` | `\"copy\" \\| \"move\" \\| \"link\"` | `\"copy\"` | Drop operation for external items |\n| `serializeDragItem` | `(item: T) => Record<string, string>` | — | Additional format representations for outgoing drags |\n\n### `UseDragAndDropOptions<T>`\n\nFull hook configuration, extends `DragAndDropProps<T>`:\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `dataFormatBase` | `string` | `\"nimbus-collection-item\"` | Override the base data format string |\n| `onInsertItems` | `(items: T[], target: ItemDropTarget) => void` | — | Insert items before/after a target |\n| `onAppendItems` | `(items: T[]) => void` | — | Append items (drop on root) |\n| `onReorder` | `(keys: Set<Key>, target: ItemDropTarget) => void` | — | Reorder items within the collection |\n| `onRemoveItems` | `(keys: Set<Key>) => void` | — | Remove items after external move |\n",
+  "views": {
+    "overview": {
+      "mdx": "\n# useDragAndDrop\n\nA shared hook that wraps React Aria's drag-and-drop system with namespace isolation,\nexternal drop support, outgoing format serialization, and state handler factories.\nReturns `{ dragAndDropHooks }` to pass to any supported React Aria collection component.\n\n## Getting started\n\n```tsx\nimport { useDragAndDrop, createArrayHandlers } from \"@commercetools/nimbus\";\n```\n\n### Basic reorderable DataTable\n\n```tsx\nimport { DataTable, useDragAndDrop, createArrayHandlers } from \"@commercetools/nimbus\";\n\nconst [rows, setRows] = useState([\n  { id: \"1\", name: \"Alice\", role: \"Admin\" },\n  { id: \"2\", name: \"Bob\", role: \"User\" },\n  { id: \"3\", name: \"Carol\", role: \"Manager\" },\n]);\n\nconst columns = [\n  { id: \"name\", header: \"Name\", accessor: (row) => row.name },\n  { id: \"role\", header: \"Role\", accessor: (row) => row.role },\n];\n\nconst { dragAndDropHooks } = useDragAndDrop({\n  ...createArrayHandlers(setRows, (row) => row.id),\n});\n\n<DataTable columns={columns} rows={rows} dragAndDropHooks={dragAndDropHooks} />\n```\n\n> [!NOTE]\n> DraggableList uses `useDragAndDrop` internally — you don't need to call it yourself.\n> Use the hook directly when adding drag-and-drop to other components like DataTable.\n\n## Namespace isolation\n\nUse `dragNamespace` to prevent drag-and-drop between unrelated lists on the same page:\n\n```tsx\nconst { dragAndDropHooks: fruitHooks } = useDragAndDrop({\n  dragNamespace: \"fruits\",\n  ...createArrayHandlers(setFruits),\n});\n\nconst { dragAndDropHooks: veggieHooks } = useDragAndDrop({\n  dragNamespace: \"vegetables\",\n  ...createArrayHandlers(setVeggies),\n});\n```\n\nLists sharing a namespace can exchange items. Lists with different namespaces (or one\nnamespaced and one not) reject each other's drops. Omitting `dragNamespace` preserves\nthe default behavior where all lists interoperate.\n\n## External drops\n\nAccept drops from outside Nimbus (plain text, files, directories) using `onExternalDrop`\nand `acceptExternalTypes`:\n\n```tsx\nimport { useDragAndDrop, createItemsFromFileDrop } from \"@commercetools/nimbus\";\nimport { DIRECTORY_DRAG_TYPE } from \"react-aria-components\";\n\nconst { dragAndDropHooks } = useDragAndDrop({\n  onExternalDrop: createItemsFromFileDrop,\n  acceptExternalTypes: [\"image/png\", \"image/jpeg\", \"application/pdf\"],\n  ...createArrayHandlers(setItems),\n});\n```\n\n### Helper functions\n\nSix composable helpers for common `onExternalDrop` patterns:\n\n| Helper | Accepts | Returns |\n|--------|---------|---------|\n| `createItemsFromTextDrop(items, type?)` | `TextDropItem` | `{ key, label }` |\n| `createItemsFromFileDrop(items)` | `FileDropItem` | `{ key, label, fileName, fileType, file }` |\n| `createItemsFromDirectoryDrop(items)` | `DirectoryDropItem` | `{ key, label, fileName, fileType, file, directory }` |\n| `createItemsFromJsonDrop(items)` | `TextDropItem` with `application/json` | `{ key, label, data }` |\n| `createItemsFromImageDrop(items)` | `FileDropItem` with `image/*` | `{ key, label, fileName, fileType, file, objectUrl }` |\n| `createItemsFromCsvDrop(items)` | `TextDropItem` with `text/csv` | `{ key, label, row, headers }` |\n\nCompose multiple helpers for mixed drop types:\n\n```tsx\nonExternalDrop={async (items) => [\n  ...(await createItemsFromTextDrop(items)),\n  ...(await createItemsFromFileDrop(items)),\n  ...(await createItemsFromDirectoryDrop(items)),\n]}\n```\n\n> [!NOTE]\n> Avoid combining `createItemsFromFileDrop` with `createItemsFromImageDrop` — file drop\n> processes all files including images, so image files would appear twice. Use one or the other.\n\n> [!WARNING]\n> `createItemsFromImageDrop` creates object URLs via `URL.createObjectURL()`.\n> Consumers must call `URL.revokeObjectURL(item.objectUrl)` when items are removed.\n\n## Outgoing formats\n\nUse `serializeDragItem` to make items droppable into non-Nimbus targets:\n\n```tsx\nconst { dragAndDropHooks } = useDragAndDrop({\n  serializeDragItem: (item) => ({\n    \"text/plain\": item.label,\n    \"text/html\": `<li>${item.label}</li>`,\n  }),\n  ...createArrayHandlers(setItems),\n});\n```\n\n## State handler factories\n\nTwo factories that return all four state mutation callbacks (`onInsertItems`,\n`onAppendItems`, `onReorder`, `onRemoveItems`):\n\n### `createListDataHandlers(list)`\n\nFor React Aria's `useListData`:\n\n```tsx\nimport { useListData } from \"react-stately\";\n\nconst list = useListData({ initialItems: items, getKey });\nconst { dragAndDropHooks } = useDragAndDrop({\n  ...createListDataHandlers(list),\n});\n```\n\n### `createArrayHandlers(setItems, getKey?)`\n\nFor plain `useState` arrays:\n\n```tsx\nconst [items, setItems] = useState(initialItems);\nconst { dragAndDropHooks } = useDragAndDrop({\n  ...createArrayHandlers(setItems, (item) => item.key),\n});\n```\n\nIf you need to customize state handling beyond what these factories provide — for example,\npersisting the new list order to an API or combining drag-and-drop with undo/redo — see the\n[React Aria drag and drop documentation](https://react-aria.adobe.com/dnd) for guidance on\nbuilding custom state handlers.\n\n## Using with DataTable\n\nDataTable accepts `dragAndDropHooks` as an optional passthrough prop:\n\n```tsx\nimport { DataTable, useDragAndDrop, createArrayHandlers } from \"@commercetools/nimbus\";\n\nconst [rows, setRows] = useState(initialRows);\nconst { dragAndDropHooks } = useDragAndDrop({\n  dragNamespace: \"my-table\",\n  ...createArrayHandlers(setRows, (row) => row.id),\n});\n\n<DataTable columns={columns} rows={rows} dragAndDropHooks={dragAndDropHooks} />\n```\n\nThe `dragAndDropHooks` prop is also available on `DataTable.Table` for the compound component API.\n\n## API reference\n\n### `DragAndDropProps<T>`\n\nConsumer-facing props, intended to be intersected into component prop types:\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `dragNamespace` | `string` | — | Isolate DnD to collections sharing the same namespace |\n| `onExternalDrop` | `(items: DropItem[]) => T[] \\| Promise<T[]>` | — | Convert external drops into collection items |\n| `acceptExternalTypes` | `Array<string \\| symbol>` | — | Drag types to accept from external sources |\n| `externalDropOperation` | `\"copy\" \\| \"move\" \\| \"link\"` | `\"copy\"` | Drop operation for external items |\n| `serializeDragItem` | `(item: T) => Record<string, string>` | — | Additional format representations for outgoing drags |\n\n### `UseDragAndDropOptions<T>`\n\nFull hook configuration, extends `DragAndDropProps<T>`:\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `dataFormatBase` | `string` | `\"nimbus-collection-item\"` | Override the base data format string |\n| `onInsertItems` | `(items: T[], target: ItemDropTarget) => void` | — | Insert items before/after a target |\n| `onAppendItems` | `(items: T[]) => void` | — | Append items (drop on root) |\n| `onReorder` | `(keys: Set<Key>, target: ItemDropTarget) => void` | — | Reorder items within the collection |\n| `onRemoveItems` | `(keys: Set<Key>) => void` | — | Remove items after external move |\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic reorderable DataTable",
+          "href": "#basic-reorderable-datatable",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Namespace isolation",
+          "href": "#namespace-isolation",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "External drops",
+          "href": "#external-drops",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Helper functions",
+          "href": "#helper-functions",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Outgoing formats",
+          "href": "#outgoing-formats",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "State handler factories",
+          "href": "#state-handler-factories",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "createListDataHandlers(list)",
+          "href": "#createlistdatahandlerslist",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "createArrayHandlers(setItems, getKey?)",
+          "href": "#createarrayhandlerssetitems-getkey",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Using with DataTable",
+          "href": "#using-with-datatable",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "DragAndDropProps<T>",
+          "href": "#draganddroppropst",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "UseDragAndDropOptions<T>",
+          "href": "#usedraganddropoptionst",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}