@commercetools/nimbus-mcp 3.2.0 → 3.4.0

package/data/docs/routes/components-inputs-drop-zone.json

@@ -0,0 +1,562 @@
+{
+  "meta": {
+    "id": "Components-DropZone",
+    "title": "Drop zone",
+    "exportName": "DropZone",
+    "description": "An accessible drop target for drag-and-drop file and data uploads, with a built-in click-to-upload fallback via FileTrigger.",
+    "lifecycleState": "Beta",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/drop-zone/drop-zone.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "Drop zone"
+    ],
+    "route": "components/inputs/drop-zone",
+    "tags": [
+      "component",
+      "dropzone",
+      "upload",
+      "drag-and-drop"
+    ],
+    "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": "States",
+        "href": "#states",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Default content",
+        "href": "#default-content",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Composing a click-to-upload button",
+        "href": "#composing-a-click-to-upload-button",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Guidelines",
+        "href": "#guidelines",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "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\nA drop zone is a dedicated area users drag files or other data onto to upload\nthem. It renders a dashed-border area that highlights when a valid drag is\nheld over it. DropZone is built for upload flows such as asset managers, CSV\nimporters, and avatar pickers, where a visible, on-brand drop target improves\non a bare button.\n\nDragging is not the only way in: DropZone pairs with `FileTrigger` to add a\nclick-to-upload button inside the zone, so a mouse, keyboard, or screen-reader\nuser can all reach the same upload flow.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria DropZone](https://react-spectrum.adobe.com/react-aria/DropZone.html)\n\n## Variables\n\nGet familiar with the features.\n\n### States\n\nIdle, drag-over, and disabled are the states DropZone styles. Drag a file over\nthe first zone to see the highlight; the second zone shows the disabled\ntreatment.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"flex-start\">\n    <DropZone>\n      <FileTrigger>\n        <Button variant=\"ghost\">Browse files</Button>\n      </FileTrigger>\n    </DropZone>\n    <DropZone isDisabled>\n      <FileTrigger>\n        <Button variant=\"ghost\" isDisabled>\n          Browse files\n        </Button>\n      </FileTrigger>\n    </DropZone>\n  </Stack>\n);\n```\n\n### Default content\n\nWith no children, DropZone shows a default upload icon and instruction label,\nso it never appears as an empty box.\n\n```jsx live\nconst App = () => <DropZone />;\n```\n\n### Composing a click-to-upload button\n\nChildren, when provided, replace the default content entirely. Compose\n`FileTrigger` and `Button` inside DropZone to add a click-to-upload path\nalongside dragging.\n\n```jsx live\nconst App = () => (\n  <DropZone>\n    <FileTrigger allowsMultiple>\n      <Button variant=\"ghost\">Browse files</Button>\n    </FileTrigger>\n  </DropZone>\n);\n```\n\n## Guidelines\n\nSee the Guidelines tab for best practices, and the Accessibility tab for\nkeyboard and screen-reader behavior.\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nA drop zone is a dedicated area users drag files or other data onto to upload\nthem. It renders a dashed-border area that highlights when a valid drag is\nheld over it. DropZone is built for upload flows such as asset managers, CSV\nimporters, and avatar pickers, where a visible, on-brand drop target improves\non a bare button.\n\nDragging is not the only way in: DropZone pairs with `FileTrigger` to add a\nclick-to-upload button inside the zone, so a mouse, keyboard, or screen-reader\nuser can all reach the same upload flow.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria DropZone](https://react-spectrum.adobe.com/react-aria/DropZone.html)\n\n## Variables\n\nGet familiar with the features.\n\n### States\n\nIdle, drag-over, and disabled are the states DropZone styles. Drag a file over\nthe first zone to see the highlight; the second zone shows the disabled\ntreatment.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"flex-start\">\n    <DropZone>\n      <FileTrigger>\n        <Button variant=\"ghost\">Browse files</Button>\n      </FileTrigger>\n    </DropZone>\n    <DropZone isDisabled>\n      <FileTrigger>\n        <Button variant=\"ghost\" isDisabled>\n          Browse files\n        </Button>\n      </FileTrigger>\n    </DropZone>\n  </Stack>\n);\n```\n\n### Default content\n\nWith no children, DropZone shows a default upload icon and instruction label,\nso it never appears as an empty box.\n\n```jsx live\nconst App = () => <DropZone />;\n```\n\n### Composing a click-to-upload button\n\nChildren, when provided, replace the default content entirely. Compose\n`FileTrigger` and `Button` inside DropZone to add a click-to-upload path\nalongside dragging.\n\n```jsx live\nconst App = () => (\n  <DropZone>\n    <FileTrigger allowsMultiple>\n      <Button variant=\"ghost\">Browse files</Button>\n    </FileTrigger>\n  </DropZone>\n);\n```\n\n## Guidelines\n\nSee the Guidelines tab for best practices, and the Accessibility tab for\nkeyboard and screen-reader behavior.\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": "States",
+          "href": "#states",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Default content",
+          "href": "#default-content",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Composing a click-to-upload button",
+          "href": "#composing-a-click-to-upload-button",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nDropZone is keyboard- and screen-reader-accessible by default through React\nAria, without any extra setup. It reaches WCAG 2.1 AA for contrast, focus\nvisibility, and non-color state changes.\n\n```jsx live\nconst App = () => (\n  <DropZone>\n    <FileTrigger>\n      <Button variant=\"ghost\">Browse files</Button>\n    </FileTrigger>\n  </DropZone>\n);\n```\n\n### Accessibility standards\n\n- **Accessible name:** with no children and no explicit label, DropZone\n  supplies a default, localized accessible name automatically — no setup\n  required. An explicit `aria-label` or `aria-labelledby` replaces the default\n  entirely and is forwarded straight to React Aria's `DropZone`, which applies\n  it to its focusable element. For a visible label instead, render a\n  `<Text slot=\"label\">` child — see the Implementation tab.\n- **Not color-only:** The drag-over state changes the border from dashed to\n  solid and switches to a heavier, tinted background — it does not rely on a\n  color shift alone. The dashed idle border and the drag-over highlight both\n  meet WCAG 1.4.11 non-text contrast (at least 3:1 against the surrounding\n  page).\n- **Forced-colors mode:** The border and drag-over outline remain visible when\n  the operating system's forced-colors (high-contrast) mode is active.\n- **Reduced motion:** Drag-over transitions respect `prefers-reduced-motion`\n  and are removed for users who request less motion.\n- **Focus indication:** A keyboard-focused drop target shows a visible focus\n  ring that meets contrast requirements.\n- **Disabled state:** `isDisabled` is conveyed both visually (a lower-emphasis\n  treatment) and to assistive technology, and rejects drops. It has no effect\n  on descendants — set `isDisabled` explicitly on a composed\n  `FileTrigger`/`Button` as well, so both controls stay in sync (see the\n  Implementation tab).\n\n### Keyboard navigation\n\n| Key      | Action                                                          |\n| -------- | ---------------------------------------------------------------- |\n| `Tab`    | Move focus to or from the drop target                           |\n| `Enter`  | While focused, enter drag-and-drop mode; while in that mode on a valid target, drop |\n| `Tab` (in drag mode) | Move between available drop targets                  |\n| `Escape` | Cancel drag-and-drop mode without dropping                       |\n\nThis keyboard drag-and-drop model is built into React Aria's `DropZone` and\nrequires no extra wiring. It only operates **within the browser window** — it\ncannot reach the operating system's file system, so a keyboard or\nscreen-reader user cannot use it alone to upload a file from disk.\n\n> [!NOTE]\\\n> Because keyboard drag-and-drop can't reach OS files, compose a `FileTrigger`\n> inside the drop zone whenever the zone is meant for file uploads. The\n> `FileTrigger`'s button gives keyboard and screen-reader users a direct path\n> to the native file picker, equivalent to what a mouse user gets by dragging\n> a file in from their desktop.\n\n### Screen reader support\n\n- The drop target is announced as a focusable, interactive element with its\n  accessible name (the default instruction label, or an explicit label when\n  one is provided).\n- Entering and exiting drag-and-drop mode, moving between drop targets, and\n  completing or canceling a drop are all announced by React Aria as the user\n  progresses through the keyboard flow.\n- A composed `FileTrigger`'s button is announced independently, using its own\n  accessible name — give it a clear label such as \"Browse files\" or \"Upload\n  file\" rather than a generic \"Choose\".\n\n### ARIA attributes\n\n- **`aria-label` / `aria-labelledby`** — forwarded as-is to React Aria's\n  `DropZone`. DropZone has a default accessible name out of the box; provide\n  one of these, or a `<Text slot=\"label\">` child, to replace it with your own.\n- **`data-drop-target`** — present while a valid drag is held over the zone;\n  drives the drag-over visual treatment described above.\n- **`data-focus-visible`** — present when the zone has keyboard focus; drives\n  the visible focus ring.\n- **`data-disabled`** — present when `isDisabled` is set; drives the disabled\n  visual treatment and is not paired with any active drop or focus state.\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Screen reader support",
+          "href": "#screen-reader-support",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "ARIA attributes",
+          "href": "#aria-attributes",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { DropZone, type DropZoneProps } from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\n`DropZone` wraps React Aria's `DropZone`. With no children, it renders a\ndefault upload icon and localized instruction label, so `<DropZone />` alone\nis never an empty box. Passing any children replaces that default content\nentirely — compose a `FileTrigger` inside the children for a click/keyboard\nupload path (see\n[Composing a click-to-upload path](#composing-a-click-to-upload-path)).\n\n```jsx live-dev\nconst App = () => (\n  <DropZone onDrop={(event) => console.log(event.items)}>\n    <FileTrigger>\n      <Button variant=\"ghost\">Browse files</Button>\n    </FileTrigger>\n  </DropZone>\n);\n```\n\n## Usage examples\n\n### Handling dropped files\n\n`onDrop` receives a React Aria `DropEvent` whose `items` are `DragItem`\nobjects, not `File` objects. For files dragged from the OS, each item has\n`kind === \"file\"` and exposes `getFile()`, which resolves to the native\n`File`. Filter for file items and resolve them before using the result:\n\n```jsx live-dev\nconst App = () => {\n  const [fileNames, setFileNames] = React.useState([]);\n\n  const handleFiles = (files) => {\n    setFileNames(files.map((file) => file.name));\n  };\n\n  const handleDrop = async (event) => {\n    const files = await Promise.all(\n      event.items\n        .filter((item) => item.kind === \"file\")\n        .map((item) => item.getFile())\n    );\n    handleFiles(files);\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"400\" alignItems=\"stretch\">\n      <DropZone onDrop={handleDrop}>\n        <FileTrigger>\n          <Button variant=\"ghost\">Browse files</Button>\n        </FileTrigger>\n      </DropZone>\n      {fileNames.length > 0 && (\n        <Text>Dropped: {fileNames.join(\", \")}</Text>\n      )}\n    </Stack>\n  );\n};\n```\n\n### Composing a click-to-upload path\n\nPassing children replaces DropZone's default icon and label entirely. Compose\nthe existing `FileTrigger` (wrapping a `Button`) to add a click/keyboard\nupload path alongside dragging. Share a single `handleFiles(files: File[])`\nhelper between `onDrop` and the\n`FileTrigger`'s `onSelect` so the file-handling logic exists in one place —\n`FileTrigger`'s `onSelect` hands you a `FileList`, so convert it with\n`Array.from` before passing it to the same helper:\n\n```jsx live-dev\nconst App = () => {\n  const [fileNames, setFileNames] = React.useState([]);\n\n  // Shared by both onDrop and the composed FileTrigger's onSelect, so the\n  // file-handling logic is not duplicated between the drag and click paths.\n  const handleFiles = (files) => {\n    setFileNames(files.map((file) => file.name));\n  };\n\n  const handleDrop = async (event) => {\n    const files = await Promise.all(\n      event.items\n        .filter((item) => item.kind === \"file\")\n        .map((item) => item.getFile())\n    );\n    handleFiles(files);\n  };\n\n  const handleSelect = (fileList) => {\n    handleFiles(fileList ? Array.from(fileList) : []);\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"400\" alignItems=\"stretch\">\n      <DropZone onDrop={handleDrop}>\n        <FileTrigger allowsMultiple onSelect={handleSelect}>\n          <Button variant=\"ghost\">Browse files</Button>\n        </FileTrigger>\n      </DropZone>\n      {fileNames.length > 0 && (\n        <Text>Selected: {fileNames.join(\", \")}</Text>\n      )}\n    </Stack>\n  );\n};\n```\n\n### Restricting accepted drops\n\nPass `getDropOperation` as a type guard that inspects the dragged types and\nreturns `\"cancel\"` for anything the zone doesn't accept. A rejected drag never\nsets the drag-over highlight, so consumers don't need a separate invalid\nstate:\n\n```jsx live-dev\nconst App = () => {\n  const acceptedType = \"image/png\";\n\n  const getDropOperation = (types) =>\n    types.has(acceptedType) ? \"copy\" : \"cancel\";\n\n  return (\n    <DropZone\n      getDropOperation={getDropOperation}\n      onDrop={(event) => console.log(event.items)}\n    >\n      <FileTrigger>\n        <Button variant=\"ghost\">Browse files</Button>\n      </FileTrigger>\n    </DropZone>\n  );\n};\n```\n\n### Disabling the zone and its composed trigger\n\n`isDisabled` disables the drop target itself and rejects drops. It has no\neffect on descendants — set `isDisabled` explicitly on the composed\n`FileTrigger`'s `Button` as well (`FileTrigger` has no `isDisabled` prop of\nits own — disabling is always done on the pressable child):\n\n```jsx live-dev\nconst App = () => {\n  const [disabled, setDisabled] = React.useState(true);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\" alignItems=\"flex-start\">\n      <DropZone isDisabled={disabled}>\n        <FileTrigger>\n          <Button variant=\"ghost\" isDisabled={disabled}>\n            Browse files\n          </Button>\n        </FileTrigger>\n      </DropZone>\n      <Button onClick={() => setDisabled((prev) => !prev)}>\n        {disabled ? \"Enable\" : \"Disable\"}\n      </Button>\n    </Stack>\n  );\n};\n```\n\n### Accessible name\n\nWith no children and no explicit label, DropZone's default content supplies\nits own accessible name automatically — no setup required. An explicit\n`aria-label` or `aria-labelledby` overrides only the accessible name: it is\nforwarded straight to React Aria's `DropZone` and applied to the focusable\nelement, while the default icon and instruction still render (the default's\nvisible text is opted out of the name, so it never conflicts with your\nlabel). Passing children, on the other hand, replaces the default content\nentirely — so you can combine the two: keep the default visual and give it a\nmore descriptive accessible name. For a visible label of your own, render a\n`<Text slot=\"label\">` child — React Aria wires the label association\nautomatically through the `slot` prop, and the presence of this child (like\nany child) replaces the default content:\n\n```jsx live-dev\nconst App = () => (\n  <DropZone aria-label=\"Upload files\">\n    <FileTrigger>\n      <Button variant=\"ghost\">Browse files</Button>\n    </FileTrigger>\n  </DropZone>\n);\n```\n\n### Filled state\n\nDropZone has no controlled `isFilled` prop — express the filled state by\nswapping the children you render once files exist, the same mechanism that\nreplaces the default icon and label as soon as you pass any children at all.\nThis example replaces the `FileTrigger` with a file list after files are\ndropped or selected:\n\n```jsx live-dev\nconst App = () => {\n  const [files, setFiles] = React.useState([]);\n\n  const handleFiles = (newFiles) => {\n    setFiles((prev) => [...prev, ...newFiles]);\n  };\n\n  const handleDrop = async (event) => {\n    const dropped = await Promise.all(\n      event.items\n        .filter((item) => item.kind === \"file\")\n        .map((item) => item.getFile())\n    );\n    handleFiles(dropped);\n  };\n\n  const handleSelect = (fileList) => {\n    handleFiles(fileList ? Array.from(fileList) : []);\n  };\n\n  if (files.length > 0) {\n    return (\n      <DropZone onDrop={handleDrop}>\n        <Stack direction=\"column\" gap=\"200\" alignItems=\"stretch\">\n          {files.map((file, index) => (\n            <Text key={`${file.name}-${index}`}>{file.name}</Text>\n          ))}\n        </Stack>\n        <FileTrigger allowsMultiple onSelect={handleSelect}>\n          <Button variant=\"ghost\">Add more files</Button>\n        </FileTrigger>\n      </DropZone>\n    );\n  }\n\n  return (\n    <DropZone onDrop={handleDrop}>\n      <FileTrigger allowsMultiple onSelect={handleSelect}>\n        <Button variant=\"ghost\">Browse files</Button>\n      </FileTrigger>\n    </DropZone>\n  );\n};\n```\n\n### Multiple files\n\nNothing in DropZone limits a drop to one file — `event.items` already\ncontains every dropped item. Pair it with `allowsMultiple` on the composed\n`FileTrigger` so the click path also accepts more than one file at a time, as\nshown in the examples above. To cap the count, check `files.length` inside\n`handleFiles` and ignore or reject the excess before updating state.\n\n## Working with React Aria drag-and-drop types\n\nDropZone re-exports `DropEvent`, `DropOperation`, and `DragTypes` from\n`@commercetools/nimbus` so `onDrop` and `getDropOperation` handlers can be\ntyped without a direct dependency on `react-aria-components`:\n\n```tsx\nimport type {\n  DropEvent,\n  DropOperation,\n  DragTypes,\n} from \"@commercetools/nimbus\";\n\nconst handleDrop = async (event: DropEvent) => {\n  const files = await Promise.all(\n    event.items\n      .filter((item) => item.kind === \"file\")\n      .map((item) => item.getFile())\n  );\n  // ...\n};\n\nconst getDropOperation = (types: DragTypes): DropOperation =>\n  types.has(\"image/png\") ? \"copy\" : \"cancel\";\n```\n\n## Component requirements\n\n### Accessibility\n\nDropZone handles most accessibility requirements internally via React Aria.\n\n- **Labeling**: with no children and no explicit label, DropZone has a default\n  accessible name out of the box. An explicit `aria-label` / `aria-labelledby`\n  overrides only the accessible name — it is forwarded to React Aria's\n  `DropZone` and applied to its focusable element, while the default icon and\n  instruction still render. Passing children replaces the default visual; for\n  a visible label of your own, render a `<Text slot=\"label\">` child.\n- **Role**: The rendered element is React Aria's `DropZone`, which behaves as\n  a focusable, keyboard-operable drop target with built-in drag-and-drop\n  semantics — see the Accessibility tab for the full keyboard model.\n- **Focus management**: Focus and the drag-over highlight are managed by React\n  Aria; don't override the `data-drop-target` or `data-focus-visible`\n  attributes it sets.\n\nIf your use case requires tracking and analytics for this component, it is\ngood practice to add a **persistent**, **unique** id:\n\n```tsx\nconst PERSISTENT_ID = \"asset-manager-drop-zone\";\n\nexport const Example = () => (\n  <DropZone id={PERSISTENT_ID}>\n    <FileTrigger>\n      <Button variant=\"ghost\">Browse files</Button>\n    </FileTrigger>\n  </DropZone>\n);\n```\n\n#### Keyboard navigation\n\nThe drop target supports full keyboard interaction — see the Accessibility\ntab for the complete key/action table and its limits for OS file uploads.\n\n## API reference\n\n<PropsTable id=\"DropZone\" />\n\n## Notes and limitations\n\n- **Default content vs. accessible name.** With no children, DropZone renders a\n  default upload icon and localized instruction label, which also serves as its\n  accessible name. Passing any children replaces that default visual entirely.\n  An explicit `aria-label` / `aria-labelledby` is independent: it overrides only\n  the accessible name and leaves the default icon and instruction in place — so\n  you can keep the default visual while giving it a more descriptive name.\n  Compose a `FileTrigger` (and any supporting copy) as children for a\n  click-to-upload path.\n- **No file-selection props.** DropZone does not expose `acceptedFileTypes`,\n  `allowsMultiple`, or any other file-picker configuration — that surface\n  belongs to the composed `FileTrigger`.\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using\n`DropZone` within your application. As the component's internal functionality\nis already tested by Nimbus, these patterns help you verify your integration\nand application-specific logic.\n\n### Basic Rendering Tests\n\nVerify the drop zone renders with an accessible name\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport {\n  DropZone,\n  FileTrigger,\n  Button,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\nimport type {\n  DropEvent,\n  DragTypes,\n  DropOperation,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"DropZone - Basic rendering\", () => {\n  it(\"renders with an explicit accessible name\", () => {\n    render(\n      <NimbusProvider>\n        <DropZone aria-label=\"Upload files\" />\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"button\", { name: /upload files/i })\n    ).toBeInTheDocument();\n  });\n});\n```\n\n### Handling Dropped Files\n\nExtract native File objects from a DropEvent and share the result with a composed FileTrigger\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport {\n  DropZone,\n  FileTrigger,\n  Button,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\nimport type {\n  DropEvent,\n  DragTypes,\n  DropOperation,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"DropZone - onDrop file extraction\", () => {\n  it(\"resolves File objects from file drag items via getFile()\", async () => {\n    const handleFiles = vi.fn();\n\n    const handleDrop = async (event: DropEvent) => {\n      const files = await Promise.all(\n        event.items\n          .filter((item) => item.kind === \"file\")\n          .map((item) =>\n            \"getFile\" in item ? item.getFile() : Promise.resolve(null)\n          )\n      );\n      handleFiles(files.filter((file): file is File => file !== null));\n    };\n\n    const fakeFile = new File([\"hello\"], \"report.txt\", {\n      type: \"text/plain\",\n    });\n    const fakeEvent = {\n      items: [\n        {\n          kind: \"file\" as const,\n          type: \"text/plain\",\n          name: \"report.txt\",\n          getFile: () => Promise.resolve(fakeFile),\n        },\n      ],\n    } as unknown as DropEvent;\n\n    await handleDrop(fakeEvent);\n\n    expect(handleFiles).toHaveBeenCalledTimes(1);\n    expect(handleFiles).toHaveBeenCalledWith([fakeFile]);\n  });\n\n  it(\"shares a single handleFiles helper between onDrop and a composed FileTrigger\", async () => {\n    const handleFiles = vi.fn();\n\n    const handleDrop = async (event: DropEvent) => {\n      const files = await Promise.all(\n        event.items\n          .filter((item) => item.kind === \"file\")\n          .map((item) =>\n            \"getFile\" in item ? item.getFile() : Promise.resolve(null)\n          )\n      );\n      handleFiles(files.filter((file): file is File => file !== null));\n    };\n\n    const handleSelect = (fileList: FileList | null) => {\n      handleFiles(fileList ? Array.from(fileList) : []);\n    };\n\n    render(\n      <NimbusProvider>\n        <DropZone onDrop={handleDrop}>\n          <FileTrigger onSelect={handleSelect}>\n            <Button>Browse files</Button>\n          </FileTrigger>\n        </DropZone>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"button\", { name: /browse files/i })\n    ).toBeInTheDocument();\n\n    // Both paths funnel through the same handleFiles helper.\n    handleSelect(null);\n    expect(handleFiles).toHaveBeenCalledWith([]);\n  });\n});\n```\n\n### Restricting Accepted Drop Types\n\nUse getDropOperation as a type guard to reject unsupported drag types\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport {\n  DropZone,\n  FileTrigger,\n  Button,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\nimport type {\n  DropEvent,\n  DragTypes,\n  DropOperation,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"DropZone - getDropOperation guard\", () => {\n  // This case exercises a standalone `getDropOperation` guard to illustrate the\n  // accept/reject shape a consumer would write — it does not drive `DropZone`\n  // itself, so it documents the pattern rather than asserting component\n  // behavior. The following case renders `DropZone` with the guard supplied.\n  it(\"rejects types the zone does not accept\", () => {\n    const acceptedType = \"image/png\";\n    const getDropOperation = (types: DragTypes): DropOperation =>\n      types.has(acceptedType) ? \"copy\" : \"cancel\";\n\n    const rejectingTypes = new Set([\"application/x-msdownload\"]);\n    const acceptingTypes = new Set([acceptedType]);\n\n    expect(getDropOperation(rejectingTypes as unknown as DragTypes)).toBe(\n      \"cancel\"\n    );\n    expect(getDropOperation(acceptingTypes as unknown as DragTypes)).toBe(\n      \"copy\"\n    );\n  });\n\n  it(\"renders with a getDropOperation guard supplied\", () => {\n    const getDropOperation = (types: DragTypes): DropOperation =>\n      types.has(\"image/png\") ? \"copy\" : \"cancel\";\n\n    render(\n      <NimbusProvider>\n        <DropZone getDropOperation={getDropOperation} />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n  });\n});\n```\n\n### Disabling the Zone and Its Composed Trigger\n\nSet isDisabled explicitly on both DropZone and the composed FileTrigger/Button\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport {\n  DropZone,\n  FileTrigger,\n  Button,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\nimport type {\n  DropEvent,\n  DragTypes,\n  DropOperation,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"DropZone - disabled composition\", () => {\n  it(\"disables both the drop target and the composed button\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <DropZone isDisabled data-testid=\"drop-zone-root\">\n          <FileTrigger>\n            <Button isDisabled>Browse files</Button>\n          </FileTrigger>\n        </DropZone>\n      </NimbusProvider>\n    );\n\n    const zone = container.querySelector(\n      \"[data-testid='drop-zone-root']\"\n    ) as HTMLElement;\n    const trigger = screen.getByRole(\"button\", { name: /browse files/i });\n\n    expect(zone).toHaveAttribute(\"data-disabled\", \"true\");\n    expect(trigger).toBeDisabled();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-dropzone--docs)\n- [React Aria DropZone](https://react-spectrum.adobe.com/react-aria/DropZone.html)\n- [FileTrigger](/components/inputs/filetrigger)\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Handling dropped files",
+          "href": "#handling-dropped-files",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Composing a click-to-upload path",
+          "href": "#composing-a-click-to-upload-path",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Restricting accepted drops",
+          "href": "#restricting-accepted-drops",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabling the zone and its composed trigger",
+          "href": "#disabling-the-zone-and-its-composed-trigger",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessible name",
+          "href": "#accessible-name",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Filled state",
+          "href": "#filled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multiple files",
+          "href": "#multiple-files",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Working with React Aria drag-and-drop types",
+          "href": "#working-with-react-aria-drag-and-drop-types",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Notes and limitations",
+          "href": "#notes-and-limitations",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Handling Dropped Files",
+          "href": "#handling-dropped-files-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Restricting Accepted Drop Types",
+          "href": "#restricting-accepted-drop-types",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabling the Zone and Its Composed Trigger",
+          "href": "#disabling-the-zone-and-its-composed-trigger-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nDropZone gives users a visible, on-brand target for dragging in files. It\nworks best as one part of an upload flow, not the whole flow — pair it with a\nclick-to-upload trigger and let the consumer's application own what happens\nonce files arrive.\n\n### Best practices\n\n- **Always pair dragging with a click-to-upload button.** Not every user can\n  drag: compose a `FileTrigger` and `Button` inside the drop zone so keyboard\n  and screen-reader users have an equally direct path to the file picker.\n- **State what the zone accepts.** If the drop zone only takes certain file\n  types or a size limit, say so in nearby text — don't make users find out by\n  trying and failing.\n- **Reserve space for the filled state.** Once files are dropped or selected,\n  swap the zone's content to show what was added (a file list, a thumbnail).\n  Don't leave the empty-state copy showing alongside the result.\n- **Replace the default label when you add your own content.** DropZone has a\n  default icon and accessible name out of the box, but composing children\n  (such as a `FileTrigger`) replaces that default entirely. Once you add\n  children, include a heading, instructional text, or an `aria-label` of your\n  own so the zone keeps a clear accessible name.\n\n### When to use\n\n> [!TIP]\\\n> **Do** — use a drop zone when uploading a file is a primary action on the\n> page, and dragging is a plausible way users will get there.\n\n- A dedicated upload step, such as an asset manager or CSV importer.\n- An avatar or logo picker where the target area is large enough to make\n  dragging comfortable.\n- Any flow where a click-to-upload button alone would leave power users\n  without a faster drag-and-drop option.\n\n> [!CAUTION]\\\n> **Don't** — reach for `FileTrigger` alone instead when a drop target adds\n> more visual weight than the flow needs.\n\n- A single inline \"Attach file\" action next to a text field or in a toolbar.\n- A space-constrained layout where a full drop zone would crowd other\n  content.\n- A flow where files are the only content — DropZone doesn't add upload\n  progress, retries, or a file list; you still build that part yourself.\n\n### Common mistakes\n\n> [!CAUTION]\\\n> **Don't** show a drop zone with no way to reach it by keyboard.\n\n```jsx live\nconst App = () => (\n  // Drag-only: this zone has a default icon and accessible name, but no\n  // click-to-upload path. A keyboard or screen-reader user can't reach the\n  // operating system's file picker from it.\n  <DropZone />\n);\n```\n\n> [!TIP]\\\n> **Do** compose a `FileTrigger` so every user has a path to the same picker.\n\n```jsx live\nconst App = () => (\n  <DropZone>\n    <FileTrigger>\n      <Button variant=\"ghost\">Browse files</Button>\n    </FileTrigger>\n  </DropZone>\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": "When to use",
+          "href": "#when-to-use",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common mistakes",
+          "href": "#common-mistakes",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}