@commercetools/nimbus-mcp 3.5.0 → 3.6.0

package/data/docs/routes/components-feedback-popover.json

@@ -0,0 +1,643 @@
+{
+  "meta": {
+    "id": "Components-Popover",
+    "title": "Popover",
+    "exportName": "Popover",
+    "description": "A positioned overlay for rich, interactive content anchored to a trigger. Built with React Aria Components for accessibility and WCAG 2.1 AA compliance.",
+    "lifecycleState": "Beta",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/popover/popover.mdx",
+    "menu": [
+      "Components",
+      "Feedback",
+      "Popover"
+    ],
+    "route": "components/feedback/popover",
+    "tags": [
+      "component",
+      "overlay",
+      "popover",
+      "dialog",
+      "interactive"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Basic usage",
+        "href": "#basic-usage",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Interactive content",
+        "href": "#interactive-content",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Placement",
+        "href": "#placement",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Spacing",
+        "href": "#spacing",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Width",
+        "href": "#width",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          5
+        ],
+        "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\nPopover shows interactive content in a floating surface anchored to the element\nthat opened it. It sits between Tooltip and Dialog: its content can be focused\nand operated, unlike a tooltip, but it stays tethered to its trigger instead of\ntaking over the page.\n\nVisually it is a single elevated surface — a background, a corner radius and a\nshadow — with no header, footer or arrow. That plainness is deliberate: the\ncontent is authored by the consumer, so the component supplies elevation and\npositioning and stays out of the way.\n\nReach for it when the content is genuinely interactive: a filter panel, a short\nedit form, a set of context-sensitive actions.\n\nUse `Tooltip` instead when the hint is short and non-interactive, and `Dialog`\nor `Drawer` when the task should take over the page. The Guidelines tab compares\nall four side by side.\n\n### Resources\n\n[ARIA dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)\n[React Aria Popover](https://react-spectrum.adobe.com/react-aria/Popover.html)\n\n## Variables\n\nPopover has no size or color variants. One surface treatment covers every use,\nbecause the content decides how much room it needs. What varies is where the\nsurface sits relative to its trigger, and how much space it takes.\n\n### Basic usage\n\nThree parts: a `Root` that owns open state, a `Trigger`, and a `Content` surface.\n\n```jsx live\nconst App = () => (\n  <Popover.Root>\n    <Popover.Trigger>Open popover</Popover.Trigger>\n    <Popover.Content aria-label=\"Example popover\">\n      <Stack gap=\"200\">\n        <Text fontWeight=\"700\">Popover title</Text>\n        <Text>Rich, interactive content lives here.</Text>\n      </Stack>\n    </Popover.Content>\n  </Popover.Root>\n);\n```\n\n### Interactive content\n\nInputs and buttons inside the popover behave normally. Typing does not dismiss\nit.\n\n```jsx live\nconst App = () => (\n  <Popover.Root>\n    <Popover.Trigger>Edit name</Popover.Trigger>\n    <Popover.Content aria-label=\"Edit name\">\n      <Stack gap=\"200\">\n        <TextInput aria-label=\"Name\" />\n        <Button>Save</Button>\n      </Stack>\n    </Popover.Content>\n  </Popover.Root>\n);\n```\n\n### Placement\n\n`placement` takes a side, optionally followed by an alignment. Sides may be\nphysical (`top`, `bottom`, `left`, `right`) or logical (`start`, `end`, which\nfollow the writing direction). The alignment vocabulary depends on the axis:\nvertical sides take `left`, `right`, `start` or `end`, while horizontal and\nlogical sides take `top` or `bottom`. The default is `bottom`.\n\nPlacement is a preference, not a guarantee — the popover flips and shifts to stay\ninside the viewport.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"400\">\n    <Popover.Root placement=\"bottom start\">\n      <Popover.Trigger>Bottom start</Popover.Trigger>\n      <Popover.Content aria-label=\"Bottom start\">\n        <Text>placement=\"bottom start\"</Text>\n      </Popover.Content>\n    </Popover.Root>\n    <Popover.Root placement=\"right top\">\n      <Popover.Trigger>Right top</Popover.Trigger>\n      <Popover.Content aria-label=\"Right top\">\n        <Text>placement=\"right top\"</Text>\n      </Popover.Content>\n    </Popover.Root>\n    <Popover.Root placement=\"top\">\n      <Popover.Trigger>Top</Popover.Trigger>\n      <Popover.Content aria-label=\"Top\">\n        <Text>placement=\"top\"</Text>\n      </Popover.Content>\n    </Popover.Root>\n  </Stack>\n);\n```\n\n### Spacing\n\n`offset` moves the surface along the trigger's axis; `crossOffset` moves it\nalong the perpendicular one. Both take pixels. Use them to fine-tune the gap,\nnot to fake an alignment that `placement` already expresses.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"400\">\n    <Popover.Root>\n      <Popover.Trigger>Default gap</Popover.Trigger>\n      <Popover.Content aria-label=\"Default gap\">\n        <Text>{\"Default offset (8)\"}</Text>\n      </Popover.Content>\n    </Popover.Root>\n    <Popover.Root offset={16}>\n      <Popover.Trigger>Wider gap</Popover.Trigger>\n      <Popover.Content aria-label=\"Wider gap\">\n        <Text>{\"offset={16}\"}</Text>\n      </Popover.Content>\n    </Popover.Root>\n  </Stack>\n);\n```\n\n### Width\n\nContent sizes to itself. Constrain it with the standard style props when the\ncontent would otherwise stretch too wide to read.\n\n```jsx live\nconst App = () => (\n  <Popover.Root>\n    <Popover.Trigger>Constrained width</Popover.Trigger>\n    <Popover.Content maxWidth=\"4800\" aria-label=\"Constrained width\">\n      <Text>\n        A longer passage wraps instead of stretching into one unreadable line.\n      </Text>\n    </Popover.Content>\n  </Popover.Root>\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nPopover shows interactive content in a floating surface anchored to the element\nthat opened it. It sits between Tooltip and Dialog: its content can be focused\nand operated, unlike a tooltip, but it stays tethered to its trigger instead of\ntaking over the page.\n\nVisually it is a single elevated surface — a background, a corner radius and a\nshadow — with no header, footer or arrow. That plainness is deliberate: the\ncontent is authored by the consumer, so the component supplies elevation and\npositioning and stays out of the way.\n\nReach for it when the content is genuinely interactive: a filter panel, a short\nedit form, a set of context-sensitive actions.\n\nUse `Tooltip` instead when the hint is short and non-interactive, and `Dialog`\nor `Drawer` when the task should take over the page. The Guidelines tab compares\nall four side by side.\n\n### Resources\n\n[ARIA dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)\n[React Aria Popover](https://react-spectrum.adobe.com/react-aria/Popover.html)\n\n## Variables\n\nPopover has no size or color variants. One surface treatment covers every use,\nbecause the content decides how much room it needs. What varies is where the\nsurface sits relative to its trigger, and how much space it takes.\n\n### Basic usage\n\nThree parts: a `Root` that owns open state, a `Trigger`, and a `Content` surface.\n\n```jsx live\nconst App = () => (\n  <Popover.Root>\n    <Popover.Trigger>Open popover</Popover.Trigger>\n    <Popover.Content aria-label=\"Example popover\">\n      <Stack gap=\"200\">\n        <Text fontWeight=\"700\">Popover title</Text>\n        <Text>Rich, interactive content lives here.</Text>\n      </Stack>\n    </Popover.Content>\n  </Popover.Root>\n);\n```\n\n### Interactive content\n\nInputs and buttons inside the popover behave normally. Typing does not dismiss\nit.\n\n```jsx live\nconst App = () => (\n  <Popover.Root>\n    <Popover.Trigger>Edit name</Popover.Trigger>\n    <Popover.Content aria-label=\"Edit name\">\n      <Stack gap=\"200\">\n        <TextInput aria-label=\"Name\" />\n        <Button>Save</Button>\n      </Stack>\n    </Popover.Content>\n  </Popover.Root>\n);\n```\n\n### Placement\n\n`placement` takes a side, optionally followed by an alignment. Sides may be\nphysical (`top`, `bottom`, `left`, `right`) or logical (`start`, `end`, which\nfollow the writing direction). The alignment vocabulary depends on the axis:\nvertical sides take `left`, `right`, `start` or `end`, while horizontal and\nlogical sides take `top` or `bottom`. The default is `bottom`.\n\nPlacement is a preference, not a guarantee — the popover flips and shifts to stay\ninside the viewport.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"400\">\n    <Popover.Root placement=\"bottom start\">\n      <Popover.Trigger>Bottom start</Popover.Trigger>\n      <Popover.Content aria-label=\"Bottom start\">\n        <Text>placement=\"bottom start\"</Text>\n      </Popover.Content>\n    </Popover.Root>\n    <Popover.Root placement=\"right top\">\n      <Popover.Trigger>Right top</Popover.Trigger>\n      <Popover.Content aria-label=\"Right top\">\n        <Text>placement=\"right top\"</Text>\n      </Popover.Content>\n    </Popover.Root>\n    <Popover.Root placement=\"top\">\n      <Popover.Trigger>Top</Popover.Trigger>\n      <Popover.Content aria-label=\"Top\">\n        <Text>placement=\"top\"</Text>\n      </Popover.Content>\n    </Popover.Root>\n  </Stack>\n);\n```\n\n### Spacing\n\n`offset` moves the surface along the trigger's axis; `crossOffset` moves it\nalong the perpendicular one. Both take pixels. Use them to fine-tune the gap,\nnot to fake an alignment that `placement` already expresses.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"400\">\n    <Popover.Root>\n      <Popover.Trigger>Default gap</Popover.Trigger>\n      <Popover.Content aria-label=\"Default gap\">\n        <Text>{\"Default offset (8)\"}</Text>\n      </Popover.Content>\n    </Popover.Root>\n    <Popover.Root offset={16}>\n      <Popover.Trigger>Wider gap</Popover.Trigger>\n      <Popover.Content aria-label=\"Wider gap\">\n        <Text>{\"offset={16}\"}</Text>\n      </Popover.Content>\n    </Popover.Root>\n  </Stack>\n);\n```\n\n### Width\n\nContent sizes to itself. Constrain it with the standard style props when the\ncontent would otherwise stretch too wide to read.\n\n```jsx live\nconst App = () => (\n  <Popover.Root>\n    <Popover.Trigger>Constrained width</Popover.Trigger>\n    <Popover.Content maxWidth=\"4800\" aria-label=\"Constrained width\">\n      <Text>\n        A longer passage wraps instead of stretching into one unreadable line.\n      </Text>\n    </Popover.Content>\n  </Popover.Root>\n);\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interactive content",
+          "href": "#interactive-content",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Placement",
+          "href": "#placement",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Spacing",
+          "href": "#spacing",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Width",
+          "href": "#width",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => (\n  <Popover.Root>\n    <Popover.Trigger>Open popover</Popover.Trigger>\n    <Popover.Content aria-label=\"Accessible popover\">\n      <Stack gap=\"200\">\n        <Text>Focus moves here when the popover opens.</Text>\n        <Button>Focusable action</Button>\n      </Stack>\n    </Popover.Content>\n  </Popover.Root>\n);\n```\n\n### Give every popover a name\n\nThis is the one thing a consumer should supply. `Popover.Content` renders a\ndialog, and React Aria falls back to labelling that dialog with the **trigger's**\naccessible name when nothing else names it. That fallback is a floor, not a\nresult: an icon-only trigger announces the dialog as \"Options\", and a trigger\nwhose label describes an action (\"Edit\") names a surface that is not an action.\nNote that a visible heading does not name the dialog by itself — it has to be\nreferenced, as in the second example below.\n\nEither label it directly:\n\n```jsx live\nconst App = () => (\n  <Popover.Root>\n    <Popover.Trigger>Filters</Popover.Trigger>\n    <Popover.Content aria-label=\"Filters\">\n      <Checkbox>Only active</Checkbox>\n    </Popover.Content>\n  </Popover.Root>\n);\n```\n\nOr point at a heading inside it, which is preferable when the heading is visible\nanyway — the name then stays in sync with what is on screen:\n\n```jsx live\nconst App = () => (\n  <Popover.Root>\n    <Popover.Trigger>Filters</Popover.Trigger>\n    <Popover.Content aria-labelledby=\"filters-heading\">\n      <Stack gap=\"200\">\n        <Heading id=\"filters-heading\" size=\"sm\">\n          Filters\n        </Heading>\n        <Checkbox>Only active</Checkbox>\n      </Stack>\n    </Popover.Content>\n  </Popover.Root>\n);\n```\n\n### Keyboard interaction\n\n| Key | Result |\n| --- | --- |\n| `Enter` or `Space` on the trigger | Toggles the popover |\n| `Tab` | Moves focus between focusable elements in the popover |\n| `Escape` | Closes the popover and returns focus to the trigger |\n\n### Focus behavior\n\nFocus moves into the popover's dialog when it opens, and returns to the trigger\nwhen it closes — whether it was closed by Escape, by an outside press, or by a\n`close` callback from inside. The one exception is a dismissing press that lands\non another focusable element: focus stays where the press put it rather than\njumping back to the trigger.\n\nBy default focus is contained within the popover and interaction outside\ndismisses it. This is React Aria's default for a dialog inside a popover, and it\nis the right behavior for almost every case: it keeps the interaction sequence\npredictable for screen reader and keyboard users.\n\n`isNonModal` does not lift that containment — focus still cycles inside the\ndialog and an outside press still dismisses it. React Aria's guidance is that\nmost popovers should not use it, because screen readers can announce the\nsurrounding page in ways that make the popover harder to follow; see the\nImplementation tab for what it does change.\n\n### ARIA attributes\n\nThe trigger exposes `aria-expanded` reflecting the open state, and\n`aria-controls` referencing the overlay while it is open. `Popover.Content`\nrenders an element with `role=\"dialog\"`.\n\nThe trigger does **not** carry `aria-haspopup`. React Aria deliberately sets it\nonly for `menu` and `listbox` overlays, because screen readers often announce\nother values as \"menu\" — which would be actively misleading here. We follow that\ndecision rather than overriding it.\n\n### Accessibility standards\n\n- **WCAG 2.1 AA** — the component meets 2.1.1 Keyboard, 2.4.3 Focus Order,\n  2.4.7 Focus Visible, and 4.1.2 Name, Role, Value, provided the consumer\n  supplies an accessible name\n- **Contrast** — the surface uses design tokens that meet AA contrast for text\n  placed on it; content authored with non-token colors must be checked\n  separately\n- **Target size** — triggers built from Nimbus buttons meet the minimum target\n  size; a custom `asChild` trigger is the consumer's responsibility\n\n### Resources\n\n- [ARIA dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)\n- [React Aria Popover](https://react-spectrum.adobe.com/react-aria/Popover.html)\n- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Give every popover a name",
+          "href": "#give-every-popover-a-name",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard interaction",
+          "href": "#keyboard-interaction",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Focus behavior",
+          "href": "#focus-behavior",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "ARIA attributes",
+          "href": "#aria-attributes",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            6
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport {\n  Popover,\n  type PopoverRootProps,\n  type PopoverTriggerProps,\n  type PopoverContentProps,\n} from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\nPopover is a compound component with three parts. `Root` owns the open state and\nthe styling context, `Trigger` opens it, and `Content` is the positioned surface.\n\n```jsx live-dev\nconst App = () => (\n  <Popover.Root>\n    <Popover.Trigger>Open popover</Popover.Trigger>\n    <Popover.Content aria-label=\"Example popover\">\n      <Text>Content goes here.</Text>\n    </Popover.Content>\n  </Popover.Root>\n);\n```\n\nThree things about this structure are worth knowing up front:\n\n- **`Root` renders no DOM element.** It wraps React Aria's `DialogTrigger`, which\n  is a context provider, so it adds nothing to your layout. A trigger inside a\n  flex row stays where you put it.\n- **`Content` supplies its own dialog.** You do not add `<Dialog>` yourself.\n  React Aria needs a dialog inside a popover for the role, name and Escape\n  handling to work, so `Content` owns it.\n- **`Trigger` renders a bare `button`.** Its slot adds a focus ring and nothing\n  else, so the form above gives you browser default chrome. Reach for `asChild`\n  with a `Button` or `IconButton` when you want Nimbus styling, as the later\n  examples do.\n\n## Usage examples\n\n### Uncontrolled mode\n\n`defaultOpen` sets the initial state and lets the component manage it from\nthere.\n\nThis one is shown as code rather than rendered live: a `defaultOpen` popover is\nmodal from the moment it mounts, so a live example would open over the page,\ncontain focus and hide the surrounding documentation from assistive technology\nas soon as you scrolled to it.\n\n```tsx\n<Popover.Root defaultOpen>\n  <Popover.Trigger>Open popover</Popover.Trigger>\n  <Popover.Content aria-label=\"Initially open\">\n    <Text>Open on mount.</Text>\n  </Popover.Content>\n</Popover.Root>\n```\n\n### Controlled mode\n\nPass `isOpen` and `onOpenChange` to own the state. In controlled mode the popover\ndoes not close itself — it reports the request and waits for `isOpen` to change.\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n\n  return (\n    <Stack gap=\"200\">\n      <Popover.Root isOpen={isOpen} onOpenChange={setIsOpen}>\n        <Popover.Trigger>Toggle popover</Popover.Trigger>\n        <Popover.Content aria-label=\"Controlled popover\">\n          <Text>Controlled by the parent.</Text>\n        </Popover.Content>\n      </Popover.Root>\n      <Text>State: {isOpen ? \"open\" : \"closed\"}</Text>\n    </Stack>\n  );\n};\n```\n\n### Closing from inside the content\n\nBecause `Content` owns the dialog, buttons inside it can use `slot=\"close\"`,\nthe same way they do in `Dialog` and `Drawer`:\n\n```jsx live-dev\nconst App = () => (\n  <Popover.Root>\n    <Popover.Trigger>Discard changes</Popover.Trigger>\n    <Popover.Content aria-label=\"Discard changes\">\n      <Stack gap=\"200\">\n        <Text>Discard your changes?</Text>\n        <Button slot=\"close\">Discard</Button>\n      </Stack>\n    </Popover.Content>\n  </Popover.Root>\n);\n```\n\nReach for a function child instead when the action has to do something *before*\nit dismisses — `Content` forwards React Aria's `close` render prop, so the\ncallback can run inside your own handler. Either way, prefer these over wiring\nup controlled state just to close the popover.\n\n```jsx live-dev\nconst App = () => (\n  <Popover.Root>\n    <Popover.Trigger>Discard changes</Popover.Trigger>\n    <Popover.Content aria-label=\"Discard changes\">\n      {({ close }) => (\n        <Stack gap=\"200\">\n          <Text>Discard your changes?</Text>\n          <Stack direction=\"horizontal\" gap=\"200\">\n            <Button variant=\"outline\" onPress={close}>\n              Cancel\n            </Button>\n            <Button onPress={close}>Discard</Button>\n          </Stack>\n        </Stack>\n      )}\n    </Popover.Content>\n  </Popover.Root>\n);\n```\n\n### Custom triggers\n\nWithout `asChild`, `Trigger` renders its own button. With `asChild`, it applies\ntrigger behavior to the element you supply, which avoids nesting one interactive\nelement inside another.\n\n```jsx live-dev\nconst App = () => (\n  <Popover.Root>\n    <Popover.Trigger asChild>\n      <IconButton aria-label=\"Options\" size=\"xs\" variant=\"ghost\">\n        <Icons.MoreVert />\n      </IconButton>\n    </Popover.Trigger>\n    <Popover.Content aria-label=\"Options\">\n      <Text>Options list</Text>\n    </Popover.Content>\n  </Popover.Root>\n);\n```\n\nThe two modes accept different props. React Aria delivers the trigger contract —\npress handling, `aria-expanded`, `aria-controls` and the trigger ref — to the\nrendered element through context, so with `asChild` there is nothing for\n`Trigger` to forward. Put the element's own props (`id`, `aria-label`,\n`isDisabled`) on the element itself; `Trigger` accepts only style props in this\nmode, and rejects the rest at compile time rather than accepting them and having\nno effect.\n\n### Positioning\n\n`placement` accepts a side, optionally followed by an alignment. The alignment\nvalues depend on the axis — this trips people up, so it is worth stating\nexplicitly:\n\n| Side | Valid alignments |\n| --- | --- |\n| `top`, `bottom` | `left`, `right`, `start`, `end` |\n| `left`, `right`, `start`, `end` | `top`, `bottom` |\n\nSo `bottom start` and `right top` are valid; `right start` is not, and will fail\nto typecheck.\n\n```jsx live-dev\nconst App = () => (\n  <Popover.Root placement=\"right top\" offset={12} crossOffset={4}>\n    <Popover.Trigger>Positioned</Popover.Trigger>\n    <Popover.Content aria-label=\"Positioned popover\">\n      <Text>placement=\"right top\"</Text>\n    </Popover.Content>\n  </Popover.Root>\n);\n```\n\n`offset` adjusts distance along the trigger's axis, `crossOffset` along the\nperpendicular one, both in pixels. `shouldFlip` (default `true`) controls whether\nthe popover may flip to the opposite side to stay in the viewport.\n\n### Dismissal behavior\n\nBy default the popover closes on Escape and on an outside press. Both can be\nadjusted:\n\n```jsx live-dev\nconst App = () => (\n  <Popover.Root isKeyboardDismissDisabled>\n    <Popover.Trigger>Keyboard dismiss disabled</Popover.Trigger>\n    <Popover.Content aria-label=\"No Escape dismissal\">\n      <Text>Escape will not close this. Click outside instead.</Text>\n    </Popover.Content>\n  </Popover.Root>\n);\n```\n\n`shouldCloseOnInteractOutside` takes a predicate receiving the interacted\nelement, so you can exempt specific regions from dismissing the popover.\n\n> [!CAUTION]\\\n> If you set `isKeyboardDismissDisabled`, provide another keyboard route to close\n> the popover. Otherwise keyboard users can open something they cannot dismiss.\n\n`isNonModal` covers the other half of modality, and it lifts less than the name\nsuggests. By default React Aria marks the rest of the page `inert` and locks page\nscroll; `isNonModal` leaves both alone, so assistive technologies can reach the\nsurrounding content. Focus is still contained and an outside press still\ndismisses — that containment comes from the dialog `Popover.Content` renders, not\nfrom modality. React Aria's guidance is that most popovers should not use it; it\nexists for components like combobox, where the trigger must keep focus while the\noverlay is open.\n\n## Component requirements\n\n### Accessibility\n\nThe Popover component handles most accessibility requirements internally via\nReact Aria.\n\n- **Labeling**: `Popover.Content` renders a dialog, so it needs an accessible\n  name. Pass `aria-label`, or `aria-labelledby` pointing at a heading inside the\n  content. This is the one accessibility requirement the component cannot satisfy\n  for you.\n- **Role**: `Content` renders an element with `role=\"dialog\"`.\n- **Focus management**: focus moves into the dialog on open and returns to the\n  trigger on close. The exception is a dismissing press on another focusable\n  element, which leaves focus on that element.\n- **ARIA state**: the trigger carries `aria-expanded`, plus `aria-controls` while\n  open. It deliberately does not carry `aria-haspopup` — React Aria sets that only\n  for `menu` and `listbox` overlays, since screen readers often announce other\n  values as \"menu\".\n- **Modality**: focus is contained and outside interaction dismisses it;\n  `isNonModal` relaxes neither — see [Dismissal behavior](#dismissal-behavior).\n\nIf your use case requires tracking and analytics for this component, it is good\npractice to add a **persistent**, **unique** id:\n\n```tsx\nconst PERSISTENT_ID = \"filters-popover-trigger\";\n\nexport const Example = () => (\n  <Popover.Root>\n    <Popover.Trigger id={PERSISTENT_ID}>Filters</Popover.Trigger>\n    <Popover.Content aria-label=\"Filters\">…</Popover.Content>\n  </Popover.Root>\n);\n```\n\n`Popover.Content` takes an `id` too. It lands on the dialog element, and React\nAria re-points the trigger's `aria-controls` at it, so the trigger-to-overlay\nlink is kept. `data-*` attributes and click handlers on `Popover.Content` reach\nthe same element. `Popover.Root` takes neither — it renders nothing.\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n\n- `Tab`: moves focus between focusable elements inside the popover\n- `Enter` or `Space`: toggles the popover when the trigger is focused\n- `Escape`: closes the popover and returns focus to the trigger\n\n### Composition constraints\n\n- `Popover.Trigger` and `Popover.Content` must be inside a `Popover.Root`.\n- Do not add your own `Dialog` inside `Popover.Content` — it already renders one,\n  and nesting a second breaks the naming and focus contract.\n- Do not nest a Popover inside another Popover.\n\n## Common patterns\n\n### Filter panel\n\n```jsx live-dev\nconst App = () => {\n  const [onlyActive, setOnlyActive] = useState(false);\n\n  return (\n    <Popover.Root>\n      <Popover.Trigger>Filters</Popover.Trigger>\n      <Popover.Content aria-labelledby=\"filters-title\" maxWidth=\"4800\">\n        {({ close }) => (\n          <Stack gap=\"300\">\n            <Heading id=\"filters-title\" size=\"sm\">\n              Filters\n            </Heading>\n            <Checkbox isSelected={onlyActive} onChange={setOnlyActive}>\n              Only active\n            </Checkbox>\n            <Button onPress={close}>Apply filters</Button>\n          </Stack>\n        )}\n      </Popover.Content>\n    </Popover.Root>\n  );\n};\n```\n\n### Inline edit\n\n```jsx live-dev\nconst App = () => {\n  const [name, setName] = useState(\"Ada Lovelace\");\n  const [draft, setDraft] = useState(name);\n\n  return (\n    <Stack direction=\"horizontal\" gap=\"200\" alignItems=\"center\">\n      <Text>{name}</Text>\n      <Popover.Root onOpenChange={(open) => open && setDraft(name)}>\n        <Popover.Trigger asChild>\n          <IconButton aria-label=\"Edit name\" size=\"2xs\" variant=\"ghost\">\n            <Icons.Edit />\n          </IconButton>\n        </Popover.Trigger>\n        <Popover.Content aria-label=\"Edit name\">\n          {({ close }) => (\n            <Stack gap=\"200\">\n              <TextInput\n                aria-label=\"Name\"\n                value={draft}\n                onChange={setDraft}\n              />\n              <Button\n                onPress={() => {\n                  setName(draft);\n                  close();\n                }}\n              >\n                Save\n              </Button>\n            </Stack>\n          )}\n        </Popover.Content>\n      </Popover.Root>\n    </Stack>\n  );\n};\n```\n\n## API reference\n\n<PropsTable id=\"Popover\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Popover within your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-specific logic.\n\n### Form Submission Tests\n\nValidate a form inside a popover and dismiss it only once the input is valid\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport { userEvent } from \"@testing-library/user-event\";\nimport { useState } from \"react\";\nimport {\n  Popover,\n  Button,\n  Checkbox,\n  Stack,\n  Text,\n  TextInput,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"Popover - Form submission\", () => {\n  const RenamePopover = ({ onSave }: { onSave: (name: string) => void }) => {\n    const [draft, setDraft] = useState(\"\");\n    const [error, setError] = useState<string | null>(null);\n\n    return (\n      <NimbusProvider>\n        <Popover.Root>\n          <Popover.Trigger>Rename</Popover.Trigger>\n          <Popover.Content aria-label=\"Rename\">\n            {({ close }) => (\n              <form\n                onSubmit={(event) => {\n                  event.preventDefault();\n                  if (!draft.trim()) {\n                    setError(\"Name is required\");\n                    return;\n                  }\n                  onSave(draft);\n                  close();\n                }}\n              >\n                <Stack gap=\"200\">\n                  <TextInput\n                    aria-label=\"Name\"\n                    value={draft}\n                    onChange={(value) => setDraft(value)}\n                  />\n                  {error && <Text>{error}</Text>}\n                  <Button type=\"submit\">Save</Button>\n                </Stack>\n              </form>\n            )}\n          </Popover.Content>\n        </Popover.Root>\n      </NimbusProvider>\n    );\n  };\n\n  it(\"reports the error and stays open when the input is invalid\", async () => {\n    const user = userEvent.setup();\n    const handleSave = vi.fn();\n\n    render(<RenamePopover onSave={handleSave} />);\n\n    await user.click(screen.getByRole(\"button\", { name: \"Rename\" }));\n    await waitFor(() => {\n      expect(screen.getByRole(\"dialog\")).toBeInTheDocument();\n    });\n\n    await user.click(screen.getByRole(\"button\", { name: \"Save\" }));\n\n    await waitFor(() => {\n      expect(screen.getByText(\"Name is required\")).toBeInTheDocument();\n    });\n    expect(handleSave).not.toHaveBeenCalled();\n    expect(screen.getByRole(\"dialog\")).toBeInTheDocument();\n  });\n\n  it(\"saves and dismisses the popover when the input is valid\", async () => {\n    const user = userEvent.setup();\n    const handleSave = vi.fn();\n\n    render(<RenamePopover onSave={handleSave} />);\n\n    await user.click(screen.getByRole(\"button\", { name: \"Rename\" }));\n    await waitFor(() => {\n      expect(screen.getByRole(\"dialog\")).toBeInTheDocument();\n    });\n\n    await user.type(screen.getByRole(\"textbox\", { name: \"Name\" }), \"Ada\");\n    await user.click(screen.getByRole(\"button\", { name: \"Save\" }));\n\n    expect(handleSave).toHaveBeenCalledWith(\"Ada\");\n    await waitFor(() => {\n      expect(screen.queryByRole(\"dialog\")).not.toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Async Data Loading Tests\n\nFetch the popover's contents when it opens, showing a loading state until the request resolves\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport { userEvent } from \"@testing-library/user-event\";\nimport { useState } from \"react\";\nimport {\n  Popover,\n  Button,\n  Checkbox,\n  Stack,\n  Text,\n  TextInput,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"Popover - Async data loading\", () => {\n  const DetailsPopover = ({ load }: { load: () => Promise<string> }) => {\n    const [detail, setDetail] = useState<string | null>(null);\n\n    return (\n      <NimbusProvider>\n        <Popover.Root\n          onOpenChange={(isOpen) => {\n            if (!isOpen || detail) return;\n            void load().then(setDetail);\n          }}\n        >\n          <Popover.Trigger>Details</Popover.Trigger>\n          <Popover.Content aria-label=\"Details\">\n            <Text>{detail ?? \"Loading…\"}</Text>\n          </Popover.Content>\n        </Popover.Root>\n      </NimbusProvider>\n    );\n  };\n\n  it(\"shows a loading state until the request resolves\", async () => {\n    const user = userEvent.setup();\n    let resolveLoad!: (value: string) => void;\n    const load = vi.fn(\n      () =>\n        new Promise<string>((resolve) => {\n          resolveLoad = resolve;\n        })\n    );\n\n    render(<DetailsPopover load={load} />);\n\n    await user.click(screen.getByRole(\"button\", { name: \"Details\" }));\n    await waitFor(() => {\n      expect(screen.getByText(\"Loading…\")).toBeInTheDocument();\n    });\n\n    resolveLoad(\"Created 3 days ago\");\n\n    await waitFor(() => {\n      expect(screen.getByText(\"Created 3 days ago\")).toBeInTheDocument();\n    });\n    expect(load).toHaveBeenCalledTimes(1);\n  });\n\n  it(\"does not refetch when the popover is reopened\", async () => {\n    const user = userEvent.setup();\n    const load = vi.fn(() => Promise.resolve(\"Created 3 days ago\"));\n\n    render(<DetailsPopover load={load} />);\n\n    const trigger = screen.getByRole(\"button\", { name: \"Details\" });\n    await user.click(trigger);\n    await waitFor(() => {\n      expect(screen.getByText(\"Created 3 days ago\")).toBeInTheDocument();\n    });\n\n    await user.click(trigger);\n    await waitFor(() => {\n      expect(screen.queryByRole(\"dialog\")).not.toBeInTheDocument();\n    });\n    await user.click(trigger);\n\n    await waitFor(() => {\n      expect(screen.getByText(\"Created 3 days ago\")).toBeInTheDocument();\n    });\n    expect(load).toHaveBeenCalledTimes(1);\n  });\n});\n```\n\n### Multi-Component Workflow Tests\n\nApply filters chosen in a popover to a list rendered outside it\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport { userEvent } from \"@testing-library/user-event\";\nimport { useState } from \"react\";\nimport {\n  Popover,\n  Button,\n  Checkbox,\n  Stack,\n  Text,\n  TextInput,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"Popover - Filter workflow\", () => {\n  const ITEMS = [\n    { id: \"1\", name: \"Active item\", isActive: true },\n    { id: \"2\", name: \"Archived item\", isActive: false },\n  ];\n\n  const FilterableList = () => {\n    const [onlyActive, setOnlyActive] = useState(false);\n    const [draft, setDraft] = useState(false);\n    const visible = onlyActive ? ITEMS.filter((item) => item.isActive) : ITEMS;\n\n    return (\n      <NimbusProvider>\n        <Stack gap=\"200\">\n          <Popover.Root\n            onOpenChange={(isOpen) => {\n              // Seed the draft from the applied value each time it opens, so\n              // an abandoned popover does not leak changes into the list.\n              if (isOpen) setDraft(onlyActive);\n            }}\n          >\n            <Popover.Trigger>Filters</Popover.Trigger>\n            <Popover.Content aria-label=\"Filters\">\n              {({ close }) => (\n                <Stack gap=\"200\">\n                  <Checkbox isSelected={draft} onChange={setDraft}>\n                    Only active\n                  </Checkbox>\n                  <Button\n                    onPress={() => {\n                      setOnlyActive(draft);\n                      close();\n                    }}\n                  >\n                    Apply filters\n                  </Button>\n                </Stack>\n              )}\n            </Popover.Content>\n          </Popover.Root>\n          <ul>\n            {visible.map((item) => (\n              <li key={item.id}>{item.name}</li>\n            ))}\n          </ul>\n        </Stack>\n      </NimbusProvider>\n    );\n  };\n\n  it(\"filters the list once the popover applies its selection\", async () => {\n    const user = userEvent.setup();\n\n    render(<FilterableList />);\n\n    expect(screen.getByText(\"Active item\")).toBeInTheDocument();\n    expect(screen.getByText(\"Archived item\")).toBeInTheDocument();\n\n    await user.click(screen.getByRole(\"button\", { name: \"Filters\" }));\n    await waitFor(() => {\n      expect(screen.getByRole(\"dialog\")).toBeInTheDocument();\n    });\n\n    await user.click(screen.getByRole(\"checkbox\", { name: \"Only active\" }));\n    await user.click(screen.getByRole(\"button\", { name: \"Apply filters\" }));\n\n    await waitFor(() => {\n      expect(screen.queryByText(\"Archived item\")).not.toBeInTheDocument();\n    });\n    expect(screen.getByText(\"Active item\")).toBeInTheDocument();\n  });\n\n  it(\"leaves the list untouched when the popover is abandoned\", async () => {\n    const user = userEvent.setup();\n\n    render(<FilterableList />);\n\n    await user.click(screen.getByRole(\"button\", { name: \"Filters\" }));\n    await waitFor(() => {\n      expect(screen.getByRole(\"dialog\")).toBeInTheDocument();\n    });\n\n    await user.click(screen.getByRole(\"checkbox\", { name: \"Only active\" }));\n    await user.keyboard(\"{Escape}\");\n\n    await waitFor(() => {\n      expect(screen.queryByRole(\"dialog\")).not.toBeInTheDocument();\n    });\n    expect(screen.getByText(\"Archived item\")).toBeInTheDocument();\n  });\n});\n```\n\n### Controlled Dismissal Tests\n\nOwn the open state so the popover cannot be dismissed while there are unsaved edits\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport { userEvent } from \"@testing-library/user-event\";\nimport { useState } from \"react\";\nimport {\n  Popover,\n  Button,\n  Checkbox,\n  Stack,\n  Text,\n  TextInput,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"Popover - Guarded dismissal\", () => {\n  const GuardedPopover = () => {\n    const [isOpen, setIsOpen] = useState(false);\n    const [isDirty, setIsDirty] = useState(false);\n\n    return (\n      <NimbusProvider>\n        <Popover.Root\n          isOpen={isOpen}\n          onOpenChange={(next) => {\n            // In controlled mode the popover reports the request rather than\n            // acting on it, so unsaved edits can veto the dismissal.\n            if (!next && isDirty) return;\n            setIsOpen(next);\n          }}\n        >\n          <Popover.Trigger>Edit</Popover.Trigger>\n          <Popover.Content aria-label=\"Edit\">\n            <Stack gap=\"200\">\n              <Button onPress={() => setIsDirty(true)}>Make an edit</Button>\n              <Button\n                onPress={() => {\n                  setIsDirty(false);\n                  setIsOpen(false);\n                }}\n              >\n                Discard\n              </Button>\n            </Stack>\n          </Popover.Content>\n        </Popover.Root>\n      </NimbusProvider>\n    );\n  };\n\n  it(\"dismisses normally while there are no unsaved edits\", async () => {\n    const user = userEvent.setup();\n\n    render(<GuardedPopover />);\n\n    await user.click(screen.getByRole(\"button\", { name: \"Edit\" }));\n    await waitFor(() => {\n      expect(screen.getByRole(\"dialog\")).toBeInTheDocument();\n    });\n\n    await user.keyboard(\"{Escape}\");\n\n    await waitFor(() => {\n      expect(screen.queryByRole(\"dialog\")).not.toBeInTheDocument();\n    });\n  });\n\n  it(\"refuses to dismiss while there are unsaved edits\", async () => {\n    const user = userEvent.setup();\n\n    render(<GuardedPopover />);\n\n    await user.click(screen.getByRole(\"button\", { name: \"Edit\" }));\n    await waitFor(() => {\n      expect(screen.getByRole(\"dialog\")).toBeInTheDocument();\n    });\n\n    await user.click(screen.getByRole(\"button\", { name: \"Make an edit\" }));\n    await user.keyboard(\"{Escape}\");\n\n    expect(screen.getByRole(\"dialog\")).toBeInTheDocument();\n\n    await user.click(screen.getByRole(\"button\", { name: \"Discard\" }));\n\n    await waitFor(() => {\n      expect(screen.queryByRole(\"dialog\")).not.toBeInTheDocument();\n    });\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-popover--docs)\n- [React Aria Popover](https://react-spectrum.adobe.com/react-aria/Popover.html)\n- [ARIA Dialog Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)\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": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Closing from inside the content",
+          "href": "#closing-from-inside-the-content",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom triggers",
+          "href": "#custom-triggers",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Positioning",
+          "href": "#positioning",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Dismissal behavior",
+          "href": "#dismissal-behavior",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Composition constraints",
+          "href": "#composition-constraints",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Filter panel",
+          "href": "#filter-panel",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Inline edit",
+          "href": "#inline-edit",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Form Submission Tests",
+          "href": "#form-submission-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Async Data Loading Tests",
+          "href": "#async-data-loading-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multi-Component Workflow Tests",
+          "href": "#multi-component-workflow-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled Dismissal Tests",
+          "href": "#controlled-dismissal-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nA popover borrows the user's attention without taking the page from them. Use it\nwhen the next step is small enough to finish in place.\n\n### When to use\n\nUse a popover when **all** of these hold:\n\n- The content is interactive — something to press, type in, or choose\n- It belongs to a specific element on the page, and that relationship matters\n- It is short enough to finish without scrolling\n- Losing it to a stray click outside would cost the user nothing important\n\nIf the last point fails, the work deserves a `Dialog`. An outside press\ndismisses a popover with no confirmation.\n\n### Choosing between overlays\n\n| Component | Content | Focus | Anchored |\n| --- | --- | --- | --- |\n| **Tooltip** | Short, non-interactive | Stays on trigger | Yes |\n| **Popover** | Interactive, small | Moves into overlay | Yes |\n| **Dialog** | Interactive, any size | Moves into overlay | No |\n| **Drawer** | Interactive, large | Moves into overlay | No |\n\nThe most common mistake is using a popover for a text hint. Tooltips open on\nhover and focus and leave focus alone; a popover requires a press and pulls focus\nin. For a hint, that is friction with no benefit.\n\nThe second most common is using a popover for a destructive confirmation. It can\nbe dismissed by clicking anywhere else, which is the opposite of what a\nconfirmation needs.\n\n### Best practices\n\n> [!TIP]\\\n> **Do** name every popover. Give `Popover.Content` an `aria-label`, or point\n> `aria-labelledby` at a heading inside it. An unnamed dialog is announced as\n> just that.\n\n> [!TIP]\\\n> **Do** let the trigger describe what opens. \"Filters\" tells the user what to\n> expect; an unlabelled icon does not.\n\n> [!CAUTION]\\\n> **Do not** stack a popover on a popover. Nested overlays are hard to dismiss\n> predictably and hard to follow with a screen reader. Anchor both to the same\n> surface, or promote the second step to a `Dialog`.\n\n> [!CAUTION]\\\n> **Do not** hide the only route to a task inside a popover. Anything a user must\n> be able to find should be reachable without discovering a trigger first.\n\n> [!TIP]\\\n> **Do** constrain the width when the content is prose. Text that stretches the\n> full surface is harder to read than text with a sensible measure.\n\n### Content\n\nKeep the content to one job. A popover that has grown a header, several sections\nand a scrollbar has outgrown the pattern.\n\nOrder the content the way it will be used: what the user came for first, and the\naction that closes the popover last. Where an action dismisses the popover, say\nwhat it does — \"Apply filters\" rather than \"OK\".\n\n### Placement\n\nLet the default `bottom` placement stand unless there is a reason not to. It is\npredictable, and it is where users look after pressing something.\n\nChange it when the trigger sits near an edge and a different side keeps the\ncontent closer to where the user is working. Placement is a preference either\nway: the popover flips and shifts to stay on screen, so it may not honour the\nside you asked for.\n\nUse `offset` to adjust the gap, not to nudge the surface into an alignment that\n`placement` already expresses.\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When to use",
+          "href": "#when-to-use",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Choosing between overlays",
+          "href": "#choosing-between-overlays",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Content",
+          "href": "#content",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Placement",
+          "href": "#placement",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            5
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}