@commercetools/nimbus-mcp 3.2.0 → 3.3.0

package/data/docs/routes/components-inputs-file-trigger.json

@@ -0,0 +1,421 @@
+{
+  "meta": {
+    "id": "Components-FileTrigger",
+    "title": "File trigger",
+    "exportName": "FileTrigger",
+    "description": "Connects a pressable element such as a button to the native file picker, letting users select files without any custom styling of its own.",
+    "lifecycleState": "Experimental",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/file-trigger/file-trigger.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "File trigger"
+    ],
+    "route": "components/inputs/file-trigger",
+    "tags": [
+      "component",
+      "inputs",
+      "file",
+      "upload",
+      "chat"
+    ],
+    "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": "Basic usage",
+        "href": "#basic-usage",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Accepted file types",
+        "href": "#accepted-file-types",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Multiple files",
+        "href": "#multiple-files",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Choose with any trigger",
+        "href": "#choose-with-any-trigger",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Guidelines",
+        "href": "#guidelines",
+        "depth": 2,
+        "numbering": [
+          1,
+          4
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\n`FileTrigger` is a behavior-only building block: it wraps a pressable child —\nusually a `Button` — and opens the operating system's file picker when that\nchild is activated. It contributes no visual styling, so the appearance is\nentirely determined by the child you provide. This keeps file selection\nconsistent with the rest of the system while leaving the trigger's look up to\nyou.\n\nIt is the foundational piece for file-selection flows (for example, attaching\nfiles in chat) and pairs with richer surfaces such as drop zones.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria FileTrigger](https://react-aria.adobe.com/FileTrigger)\n\n## Basic usage\n\nWrap any pressable Nimbus component. The button below opens the file picker; the\nselection is reported to your `onSelect` handler.\n\n```jsx live\nconst App = () => {\n  const [name, setName] = React.useState(\"\");\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <FileTrigger\n        onSelect={(files) => {\n          const list = files ? Array.from(files) : [];\n          setName(list[0]?.name ?? \"\");\n        }}\n      >\n        <Button>Upload file</Button>\n      </FileTrigger>\n      <Text>{name || \"No file selected\"}</Text>\n    </Stack>\n  );\n};\n```\n\n## Variables\n\nGet familiar with the features.\n\n### Accepted file types\n\nLimit selectable files by MIME type or extension.\n\n```jsx live\nconst App = () => (\n  <FileTrigger acceptedFileTypes={[\"image/png\", \"image/jpeg\", \".pdf\"]}>\n    <Button>Upload image or PDF</Button>\n  </FileTrigger>\n);\n```\n\n### Multiple files\n\nAllow selecting more than one file at a time.\n\n```jsx live\nconst App = () => (\n  <FileTrigger allowsMultiple>\n    <Button>Upload files</Button>\n  </FileTrigger>\n);\n```\n\n### Choose with any trigger\n\nBecause the child defines the look, you can use any pressable component — for\nexample an `IconButton`.\n\n```jsx live\nconst App = () => (\n  <FileTrigger>\n    <IconButton aria-label=\"Attach file\" variant=\"ghost\">\n      <Icons.AttachFile />\n    </IconButton>\n  </FileTrigger>\n);\n```\n\n## Guidelines\n\n- Always give the child a clear, descriptive label — the trigger's accessible\n  name comes entirely from the child.\n- Use a concrete verb such as \"Upload\" or \"Attach\" rather than a generic\n  \"Choose\".\n- When you only need an icon, pair an `IconButton` with an `aria-label` (or a\n  tooltip) so the action stays understandable.\n- Communicate accepted file types and size limits near the trigger so users know\n  what to expect before opening the picker.\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\n`FileTrigger` is a behavior-only building block: it wraps a pressable child —\nusually a `Button` — and opens the operating system's file picker when that\nchild is activated. It contributes no visual styling, so the appearance is\nentirely determined by the child you provide. This keeps file selection\nconsistent with the rest of the system while leaving the trigger's look up to\nyou.\n\nIt is the foundational piece for file-selection flows (for example, attaching\nfiles in chat) and pairs with richer surfaces such as drop zones.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria FileTrigger](https://react-aria.adobe.com/FileTrigger)\n\n## Basic usage\n\nWrap any pressable Nimbus component. The button below opens the file picker; the\nselection is reported to your `onSelect` handler.\n\n```jsx live\nconst App = () => {\n  const [name, setName] = React.useState(\"\");\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <FileTrigger\n        onSelect={(files) => {\n          const list = files ? Array.from(files) : [];\n          setName(list[0]?.name ?? \"\");\n        }}\n      >\n        <Button>Upload file</Button>\n      </FileTrigger>\n      <Text>{name || \"No file selected\"}</Text>\n    </Stack>\n  );\n};\n```\n\n## Variables\n\nGet familiar with the features.\n\n### Accepted file types\n\nLimit selectable files by MIME type or extension.\n\n```jsx live\nconst App = () => (\n  <FileTrigger acceptedFileTypes={[\"image/png\", \"image/jpeg\", \".pdf\"]}>\n    <Button>Upload image or PDF</Button>\n  </FileTrigger>\n);\n```\n\n### Multiple files\n\nAllow selecting more than one file at a time.\n\n```jsx live\nconst App = () => (\n  <FileTrigger allowsMultiple>\n    <Button>Upload files</Button>\n  </FileTrigger>\n);\n```\n\n### Choose with any trigger\n\nBecause the child defines the look, you can use any pressable component — for\nexample an `IconButton`.\n\n```jsx live\nconst App = () => (\n  <FileTrigger>\n    <IconButton aria-label=\"Attach file\" variant=\"ghost\">\n      <Icons.AttachFile />\n    </IconButton>\n  </FileTrigger>\n);\n```\n\n## Guidelines\n\n- Always give the child a clear, descriptive label — the trigger's accessible\n  name comes entirely from the child.\n- Use a concrete verb such as \"Upload\" or \"Attach\" rather than a generic\n  \"Choose\".\n- When you only need an icon, pair an `IconButton` with an `aria-label` (or a\n  tooltip) so the action stays understandable.\n- Communicate accepted file types and size limits near the trigger so users know\n  what to expect before opening the picker.\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": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accepted file types",
+          "href": "#accepted-file-types",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multiple files",
+          "href": "#multiple-files",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Choose with any trigger",
+          "href": "#choose-with-any-trigger",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\n`FileTrigger` delegates all interaction semantics to React Aria. The visible,\nfocusable child you provide is the only interactive element: it receives focus,\nis operable with mouse, touch, and keyboard (Enter / Space), and is announced to\nassistive technology. The underlying `<input type=\"file\">` is hidden with\n`display: none` and is clicked programmatically when the child is pressed, so it\nis not a separate tab stop and never competes with the child for focus.\n\n```jsx live\nconst App = () => (\n  <FileTrigger onSelect={(files) => alert(`${files?.length ?? 0} file(s)`)}>\n    <Button>Upload file</Button>\n  </FileTrigger>\n);\n```\n\n### Accessibility standards\n\n- **Accessible name comes from the child:** `FileTrigger` adds no label of its\n  own. Provide visible text, an `aria-label`, or a tooltip on the child so the\n  action is clearly announced (e.g. \"Upload file\", \"Attach image\").\n- **Keyboard operability:** The trigger must be reachable with the Tab key and\n  activatable with Enter or Space. Using a Nimbus `Button` or `IconButton` as\n  the child satisfies this automatically.\n- **Focus indicator:** Ensure the child shows a clear focus ring; Nimbus\n  buttons provide this by default.\n- **Icon-only triggers:** When the child is an `IconButton`, always supply an\n  `aria-label` or a tooltip so the purpose is conveyed to screen reader users.\n- **Disabled state:** Disable the child (not `FileTrigger`) to prevent\n  activation; the disabled state is then communicated to assistive technology by\n  the child.\n- **Set expectations:** Communicate accepted file types, count, and size limits\n  in nearby visible text, not only through the picker, so users understand\n  constraints before opening the dialog.\n- **Target size:** Keep the trigger large enough to activate comfortably; follow\n  the minimum target-size guidance for the chosen button size.\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 { FileTrigger, type FileTriggerProps } from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\n`FileTrigger` wraps a pressable child (typically a `Button`) and opens the\nnative file picker when the child is activated. It renders no styling of its own\n— the child provides the visual treatment. The `onSelect` handler receives the\nnative `FileList` (or `null`).\n\n```jsx live-dev\nconst App = () => {\n  const [name, setName] = React.useState(\"\");\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <FileTrigger\n        onSelect={(files) => {\n          const list = files ? Array.from(files) : [];\n          setName(list[0]?.name ?? \"\");\n        }}\n      >\n        <Button>Upload file</Button>\n      </FileTrigger>\n      <Text>{name || \"No file selected\"}</Text>\n    </Stack>\n  );\n};\n```\n\n## Usage examples\n\n### Restrict accepted file types\n\nPass `acceptedFileTypes` (MIME types or extensions) to limit what the picker\noffers. It maps to the input's `accept` attribute.\n\n```jsx live-dev\nconst App = () => (\n  <FileTrigger acceptedFileTypes={[\"image/png\", \"image/jpeg\", \".pdf\"]}>\n    <Button>Upload image or PDF</Button>\n  </FileTrigger>\n);\n```\n\n### Select multiple files\n\nSet `allowsMultiple` to let the user pick more than one file at a time.\n\n```jsx live-dev\nconst App = () => {\n  const [count, setCount] = React.useState(0);\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <FileTrigger\n        allowsMultiple\n        onSelect={(files) => setCount(files ? files.length : 0)}\n      >\n        <Button>Upload files</Button>\n      </FileTrigger>\n      <Text>{count} file(s) selected</Text>\n    </Stack>\n  );\n};\n```\n\n### Select a directory\n\nSet `acceptDirectory` to let the user choose a whole folder instead of\nindividual files.\n\n```jsx live-dev\nconst App = () => (\n  <FileTrigger acceptDirectory>\n    <Button>Select folder</Button>\n  </FileTrigger>\n);\n```\n\n### Capture from the camera (mobile)\n\n`defaultCamera` hints which camera a mobile device should use (`\"user\"` or\n`\"environment\"`). It maps to the `capture` attribute and is ignored on desktop.\n\n```jsx live-dev\nconst App = () => (\n  <FileTrigger defaultCamera=\"environment\" acceptedFileTypes={[\"image/*\"]}>\n    <Button>Take photo</Button>\n  </FileTrigger>\n);\n```\n\n### Disabling the trigger\n\n`FileTrigger` has no `isDisabled` prop of its own — disable the child instead. A\ndisabled child cannot open the picker.\n\n```jsx live-dev\nconst App = () => (\n  <FileTrigger>\n    <Button isDisabled>Upload file</Button>\n  </FileTrigger>\n);\n```\n\n## Notes and limitations\n\n- **`onSelect` receives a `FileList`, not an array.** Use `Array.from(files)` to\n  map over the selection. `files` is `null` if the selection was cleared.\n- **Re-selecting the same file.** Browsers do not fire a change event when the\n  user picks the identical file again. `FileTrigger` does not expose a reset\n  API; if you need to allow re-selecting the same file, remount the component\n  with a changing `key` prop after handling a selection.\n- **No native form (`name`) integration.** `FileTrigger` does not submit a file\n  via a native `<form>`. Lift the selection into state via `onSelect` and submit\n  it yourself.\n- **Combining `acceptDirectory` and `allowsMultiple`.** How these interact is\n  defined by the browser, not by `FileTrigger` — some browsers honor only the\n  directory selection and ignore `allowsMultiple`. Don't rely on a consistent\n  result across browsers.\n\n## API reference\n\n<PropsTable id=\"FileTrigger\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using\n`FileTrigger` within your application. As the component's internal functionality\nis already tested by Nimbus, these patterns help you verify your integration and\napplication-specific logic.\n\n### Basic Rendering Tests\n\nVerify the FileTrigger renders a pressable child plus a hidden file input\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 { FileTrigger, Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"FileTrigger - Basic rendering\", () => {\n  it(\"renders the child trigger and a hidden file input\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <FileTrigger>\n          <Button aria-label=\"Upload file\">Upload file</Button>\n        </FileTrigger>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"button\", { name: /upload file/i })\n    ).toBeInTheDocument();\n    expect(getFileInput(container)).toHaveAttribute(\"type\", \"file\");\n  });\n\n  it(\"forwards acceptedFileTypes to the input's accept attribute\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <FileTrigger acceptedFileTypes={[\"image/png\", \".pdf\"]}>\n          <Button aria-label=\"Upload\">Upload</Button>\n        </FileTrigger>\n      </NimbusProvider>\n    );\n\n    expect(getFileInput(container)).toHaveAttribute(\"accept\", \"image/png,.pdf\");\n  });\n\n  it(\"forwards allowsMultiple to the input's multiple attribute\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <FileTrigger allowsMultiple>\n          <Button aria-label=\"Upload\">Upload</Button>\n        </FileTrigger>\n      </NimbusProvider>\n    );\n\n    expect(getFileInput(container)).toHaveAttribute(\"multiple\");\n  });\n});\n```\n\n### Interaction Tests\n\nTest selecting files through the FileTrigger\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 { FileTrigger, Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"FileTrigger - Interactions\", () => {\n  it(\"calls onSelect with a FileList when a file is selected\", async () => {\n    const user = userEvent.setup();\n    const handleSelect = vi.fn();\n\n    const { container } = render(\n      <NimbusProvider>\n        <FileTrigger onSelect={handleSelect}>\n          <Button aria-label=\"Upload file\">Upload file</Button>\n        </FileTrigger>\n      </NimbusProvider>\n    );\n\n    const file = new File([\"hello\"], \"report.txt\", { type: \"text/plain\" });\n    await user.upload(getFileInput(container), file);\n\n    expect(handleSelect).toHaveBeenCalledTimes(1);\n    const files = handleSelect.mock.calls[0][0] as FileList;\n    expect(files.length).toBe(1);\n    expect(files[0].name).toBe(\"report.txt\");\n  });\n\n  it(\"reports every file when allowsMultiple is set\", async () => {\n    const user = userEvent.setup();\n    const handleSelect = vi.fn();\n\n    const { container } = render(\n      <NimbusProvider>\n        <FileTrigger allowsMultiple onSelect={handleSelect}>\n          <Button aria-label=\"Upload files\">Upload files</Button>\n        </FileTrigger>\n      </NimbusProvider>\n    );\n\n    await user.upload(getFileInput(container), [\n      new File([\"a\"], \"a.txt\", { type: \"text/plain\" }),\n      new File([\"b\"], \"b.txt\", { type: \"text/plain\" }),\n    ]);\n\n    expect(handleSelect).toHaveBeenCalledTimes(1);\n    expect((handleSelect.mock.calls[0][0] as FileList).length).toBe(2);\n  });\n});\n```\n\n### State Tests\n\nDisabling is delegated to the child trigger\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 { FileTrigger, Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"FileTrigger - States\", () => {\n  it(\"does not select when the child button is disabled\", async () => {\n    const user = userEvent.setup();\n    const handleSelect = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <FileTrigger onSelect={handleSelect}>\n          <Button aria-label=\"Upload file\" isDisabled>\n            Upload file\n          </Button>\n        </FileTrigger>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /upload file/i });\n    expect(button).toBeDisabled();\n\n    await user.click(button);\n    expect(handleSelect).not.toHaveBeenCalled();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-filetrigger--docs)\n- [React Aria FileTrigger](https://react-aria.adobe.com/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": "Restrict accepted file types",
+          "href": "#restrict-accepted-file-types",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Select multiple files",
+          "href": "#select-multiple-files",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Select a directory",
+          "href": "#select-a-directory",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Capture from the camera (mobile)",
+          "href": "#capture-from-the-camera-mobile",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabling the trigger",
+          "href": "#disabling-the-trigger",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Notes and limitations",
+          "href": "#notes-and-limitations",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interaction Tests",
+          "href": "#interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "State Tests",
+          "href": "#state-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}