@adres/mgda-ui 0.0.0-stage → 0.0.1

package/knowledge/number-stepper.md

@@ -0,0 +1,159 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: number-stepper
+  sourceFile: packages/design-system/src/components/number-stepper.tsx
+  client: true
+  category: web-app-patterns
+  categoryFromBarrel: web-app-patterns
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: NumberStepper
+      kind: component
+      typeText: "ForwardRefExoticComponent<NumberStepperProps & RefAttributes<HTMLDivElement>>"
+    - name: NumberStepperProps
+      kind: type
+    - name: NumberStepperSize
+      kind: type
+  primaryExport: NumberStepper
+  subcomponents: []
+  props:
+    NumberStepper:
+      - name: ariaLabel
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Accessible label for the wrapper. Set this when context isn't obvious from the surrounding label element."
+      - name: disabled
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Disables the whole control (both buttons + input). Per-bound disabling of the +/- buttons still happens automatically at min/max."
+      - name: id
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Pass-through id for the central <input>, so a sibling <label htmlFor> binds correctly."
+      - name: max
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Largest value the stepper allows. Defaults to 999."
+      - name: min
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Smallest value the stepper allows. Defaults to 1."
+      - name: onChange
+        type: "(next: number) => void"
+        required: true
+        declaredIn: self
+      - name: size
+        type: NumberStepperSize
+        required: false
+        declaredIn: self
+        doc: "Visual density. Matches Button / Input size scale."
+      - name: step
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Increment / decrement amount. Defaults to 1."
+      - name: value
+        type: number
+        required: true
+        declaredIn: self
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLDivElement>, \"onChange\">"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: NumberStepper
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - HEIGHT
+    - ICON_SIZE
+  dataSlots: []
+  dependsOn:
+    internal:
+      - button
+      - input
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-numberstepper--default
+  storybookTitle: Components/NumberStepper
+  docsId: components-numberstepper--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "7fa157843630"
+  factsHash: e16e9641c8c8
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A joined +/-/input control for a bounded integer value, combining Button and Input into one visual unit."
+useWhen:
+  - "a bounded integer input where direct typing should stay possible alongside +/- buttons - seat counts, quantity selectors"
+useInstead:
+  - id: input
+    when: "a plain number input is enough and the +/- buttons are not needed"
+  - id: slider
+    when: "picking a value by dragging is more natural than typing or clicking, especially for a wide range"
+related:
+  - input
+  - slider
+a11y:
+  notes:
+    - "Sets role=\"group\" with ariaLabel (default \"Number\") on the wrapper - override ariaLabel with something specific, e.g. \"Number of seats\", whenever a sibling label does not already make the control's purpose obvious."
+    - "The +/- buttons disable automatically at min/max and stay in sync as the user types - there is no need to compute or pass that disabled state separately."
+  keyboard:
+    - "The central Input is a real number input, so native increment/decrement via arrow keys works there in addition to clicking the +/- buttons; Tab moves through the decrement button, the input, and the increment button as three separate stops."
+  radixHandles: false
+pitfalls:
+  - "value must round-trip through onChange like any controlled input - the component maintains an internal typing draft so the field does not fight the user mid-edit, but value/onChange still need to update normally between renders."
+  - "Typed input only commits live when it parses to a clean, in-bounds integer - an out-of-range or partial value stays as an uncommitted draft until blur, when it is clamped to [min, max] and always committed, even replacing an unparseable string with min."
+  - "The wrapper is w-full by default and the three segments split evenly - constrain the parent (e.g. max-w-sm) for a traditional compact stepper, or it stretches to fill its row."
+  - "disabled disables the whole control, but the individual +/- buttons already disable themselves independently at min/max regardless of disabled - the two disabling mechanisms are separate and both apply."
+canonicalSnippet: |
+  import { NumberStepper } from "@adres/mgda-ui"
+
+  const seatsLabel = "Number of seats"
+
+  <NumberStepper value={count} onChange={setCount} min={1} max={10} ariaLabel={seatsLabel} />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: "7fa157843630"
+---
+
+## Usage
+
+`NumberStepper` is a bounded integer input that joins a decrement button, a
+central number field, and an increment button into one visual unit - seat
+counts, quantity selectors, anywhere direct typing should stay possible
+alongside +/- clicks. Reach for `Input` alone when the buttons are not
+needed, and `Slider` when dragging suits the range better than typing or
+clicking.
+
+The wrapper is `w-full` and its three segments split evenly - constrain the
+parent (e.g. `max-w-sm`) for a compact stepper rather than one that stretches
+to fill its row.
+
+Typed input commits live only when it parses to a clean, in-bounds integer;
+an out-of-range or mid-edit value stays as a draft until blur, when it is
+always clamped to `[min, max]` and committed - an unparseable string resolves
+to `min`.
+
+`disabled` turns off the whole control, but the +/- buttons already disable
+themselves independently at `min`/`max` regardless of `disabled` - both
+mechanisms apply at once, not one or the other.

package/knowledge/page-header.md

@@ -0,0 +1,109 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: page-header
+  sourceFile: packages/design-system/src/components/page-header.tsx
+  client: false
+  category: web-app-layout-navigation
+  categoryFromBarrel: web-app-layout-navigation
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: PageHeader
+      kind: component
+      typeText: "ForwardRefExoticComponent<PageHeaderProps & RefAttributes<HTMLDivElement>>"
+    - name: PageHeaderProps
+      kind: type
+  primaryExport: PageHeader
+  subcomponents: []
+  props:
+    PageHeader:
+      - name: children
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Right-aligned slot - typically `<Button>`s, a search input, a `Select`, or any other action(s) the page exposes at the top. Wraps to a new line on narrow viewports rather than truncating."
+      - name: subtitle
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Optional subtitle / context line shown directly under the title."
+      - name: title
+        type: ReactNode
+        required: true
+        declaredIn: self
+        doc: "Page or section title. Rendered as an `<h1>` with `t-h1` typography."
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLDivElement>, \"title\">"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-pageheader--default
+  storybookTitle: Components/PageHeader
+  docsId: components-pageheader--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: cde2a64fb03f
+  factsHash: "8e2d8b1c8eb3"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "The top-of-content heading row: an h1 title, optional subtitle, and a right-aligned actions slot."
+useWhen:
+  - "the top of a page or major section needs a title plus page-level actions (e.g. \"Import CSV\" / \"Invite students\")"
+  - "you want a consistent title+subtitle+actions layout instead of hand-rolling one per page"
+useInstead:
+  - id: top-nav
+    when: "you need a sticky app-shell bar (breadcrumbs, search, account menu), not an in-content page title"
+related:
+  - top-nav
+composesWith:
+  - button
+tokens:
+  - "--muted-foreground"
+a11y:
+  notes:
+    - "title renders as a real <h1> - a page should have exactly one PageHeader (or otherwise exactly one <h1>), so don't use it more than once per page."
+    - "PageHeader is a server component (no \"use client\") with no interactivity of its own; any focus/keyboard behavior comes entirely from what you put in children."
+  requiredProps:
+    - "title is required; subtitle and children (actions) are optional"
+  keyboard: []
+  radixHandles: false
+pitfalls:
+  - "title's prop type intentionally shadows and omits the native HTML title attribute (via Omit<..., \"title\">) - you cannot pass a native tooltip title string through props; wrap the component if you need one."
+  - "children is the actions slot, not the body content - PageHeader is meant to sit above a page's main content, not wrap it."
+canonicalSnippet: |
+  import { PageHeader, Button } from "@adres/mgda-ui"
+
+  const subtitle = "38 active learners"
+
+  <PageHeader title="Students" subtitle={subtitle}>
+    <Button variant="outline">Import CSV</Button>
+    <Button>Invite students</Button>
+  </PageHeader>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: cde2a64fb03f
+---
+
+## Usage
+
+PageHeader pairs an `<h1>` title with an optional subtitle on the start side
+and a free-form actions slot (`children`) on the end side, baseline-aligned
+so a wrapping multi-line title keeps its actions anchored to the last line.
+Actions wrap onto a new row on narrow viewports rather than truncating or
+overflowing.
+
+Use it once per page or major section - it renders the page's single `<h1>`,
+and stacking more than one breaks that heading hierarchy.

package/knowledge/pagination.md

@@ -0,0 +1,225 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: pagination
+  sourceFile: packages/design-system/src/components/pagination.tsx
+  client: true
+  category: web-app-patterns
+  categoryFromBarrel: web-app-patterns
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Pagination
+      kind: component
+      typeText: "ForwardRefExoticComponent<PaginationProps & RefAttributes<HTMLElement>>"
+    - name: PaginationContent
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<DetailedHTMLProps<HTMLAttributes<HTMLUListElement>, HTMLUListElement>, \"ref\"> & RefAttributes<...>>"
+    - name: PaginationEllipsis
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, \"ref\"> & RefAttributes<...>>"
+    - name: PaginationItem
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<DetailedHTMLProps<LiHTMLAttributes<HTMLLIElement>, HTMLLIElement>, \"ref\"> & RefAttributes<HTMLLIElement>>"
+    - name: PaginationLink
+      kind: component
+      typeText: "ForwardRefExoticComponent<PaginationLinkProps & RefAttributes<HTMLButtonElement>>"
+    - name: PaginationLinkProps
+      kind: type
+    - name: paginationLinkVariants
+      kind: variants
+      typeText: "TVReturnType<{ isActive: { true: \"ax:bg-primary-weaker ax:text-primary-foreground ax:dark:bg-primary-strong ax:dark:text-primary-weaker\"; false: \"ax:bg-transparent ax:text-foreground ax:hover:bg-muted\"; }; size: { ...; }...[truncated]"
+    - name: PaginationNavLinkProps
+      kind: type
+    - name: PaginationNext
+      kind: component
+      typeText: "ForwardRefExoticComponent<PaginationNavLinkProps & RefAttributes<HTMLButtonElement>>"
+    - name: PaginationPrevious
+      kind: component
+      typeText: "ForwardRefExoticComponent<PaginationNavLinkProps & RefAttributes<HTMLButtonElement>>"
+    - name: PaginationProps
+      kind: type
+  primaryExport: Pagination
+  subcomponents:
+    - PaginationContent
+    - PaginationEllipsis
+    - PaginationItem
+    - PaginationLink
+    - PaginationNext
+    - PaginationPrevious
+  props:
+    PaginationLink:
+      - name: asChild
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Render the child element instead of a button (e.g. a router `<Link>`)."
+      - name: isActive
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Marks the current page: sets `aria-current=\"page\"` and the active fill."
+        variantKey: true
+      - name: size
+        type: "\"md\" | \"sm\""
+        required: false
+        declaredIn: self
+        variantKey: true
+    PaginationNext:
+      - name: asChild
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Render the child element instead of a button (e.g. a router `<Link>`)."
+      - name: size
+        type: "\"md\" | \"sm\""
+        required: false
+        declaredIn: self
+        variantKey: true
+    PaginationPrevious:
+      - name: asChild
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Render the child element instead of a button (e.g. a router `<Link>`)."
+      - name: size
+        type: "\"md\" | \"sm\""
+        required: false
+        declaredIn: self
+        variantKey: true
+  extendsProps:
+    - "React.ComponentPropsWithoutRef<\"nav\">"
+  variants:
+    isActive:
+      kind: boolean
+      default: false
+      on: Pagination
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+      default: md
+      on: Pagination
+  variantSource: tv
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-slot"
+      - lucide-react
+      - react
+      - tailwind-variants
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-pagination--default
+    - exportName: WithEllipsis
+      id: components-pagination--with-ellipsis
+    - exportName: Small
+      id: components-pagination--small
+    - exportName: DisabledEdges
+      id: components-pagination--disabled-edges
+  storybookTitle: Components/Pagination
+  docsId: components-pagination--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "85bf65cd1ffe"
+  factsHash: fe8f4aa628e9
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "Page-range navigation - numbered links, Previous/Next, and an ellipsis for skipped ranges."
+useWhen:
+  - "navigating a long, numbered result set (search results, a table, a product grid) where jumping to an arbitrary page is useful"
+  - "the list is paged server-side or client-side and the total page count is known up front"
+useInstead:
+  - id: data-table
+    when: "the paged content already lives inside a DataTable - wire its own pagination footer instead of composing a separate Pagination beside it"
+  - id: button
+    when: "the affordance is a single 'load more', not numbered pages"
+related:
+  - button
+  - data-table
+a11y:
+  notes:
+    - "Pagination sets role=\"navigation\" and aria-label=\"pagination\" on the root nav landmark."
+    - "PaginationLink sets aria-current=\"page\" on the active page - that's the only signal a screen reader gets about which page is current, so isActive must always be passed accurately."
+    - "PaginationEllipsis is aria-hidden - it's decorative, not a real, focusable page."
+  requiredProps:
+    - "Every PaginationLink, PaginationPrevious and PaginationNext needs an accessible name - number links get it from their visible text; an icon-only override needs an explicit aria-label."
+  keyboard:
+    - "Every item is a native button, so Tab moves between them individually - there is no roving tabindex or arrow-key paging like a tablist would provide."
+  radixHandles: false
+tokens:
+  - "--primary-weaker"
+  - "--primary-strong"
+  - "--primary-foreground"
+  - "--muted"
+  - "--foreground"
+  - "--button-radius"
+  - "--ring"
+pitfalls:
+  - "Pagination ships the primitives only, not a page-range calculator - compute which numbers and ellipses to render yourself (see the WithEllipsis story); there is no pageCount prop that does it for you."
+  - "PaginationPrevious/PaginationNext don't disable themselves at the edges - pass disabled explicitly when page is 1 or pageCount."
+  - "size lives on each PaginationLink/PaginationPrevious/PaginationNext individually, not on the Pagination root - unlike ButtonGroup there is no shared context, so a link left without a matching size silently defaults to md next to sm siblings."
+canonicalSnippet: |
+  import {
+    Pagination, PaginationContent, PaginationItem, PaginationLink,
+    PaginationPrevious, PaginationNext,
+  } from "@adres/mgda-ui"
+
+  <Pagination>
+    <PaginationContent>
+      <PaginationItem>
+        <PaginationPrevious disabled={page === 1} onClick={() => setPage(page - 1)} />
+      </PaginationItem>
+      {[1, 2, 3].map((n) => (
+        <PaginationItem key={n}>
+          <PaginationLink isActive={n === page} onClick={() => setPage(n)}>{n}</PaginationLink>
+        </PaginationItem>
+      ))}
+      <PaginationItem>
+        <PaginationNext disabled={page === 3} onClick={() => setPage(page + 1)} />
+      </PaginationItem>
+    </PaginationContent>
+  </Pagination>
+reviewedAt: 2026-10-16
+reviewedAgainstContractHash: "85bf65cd1ffe"
+---
+
+## Usage
+
+`Pagination` is a set of composable parts, not a single opinionated widget:
+`Pagination` (the `nav` landmark), `PaginationContent` (the `ul`), `PaginationItem`
+(each `li`), `PaginationLink` (a page number), `PaginationPrevious`/`PaginationNext`
+(the edge controls), and `PaginationEllipsis` (a decorative truncation marker).
+It follows the shadcn/ui pattern - plain semantic elements styled with design-system
+tokens, no Radix primitive underneath, because page navigation doesn't need
+focus-trapping or portal behaviour, just a nav landmark and native buttons.
+
+The component does not compute a page range for you. For a short list, render every
+page number directly. For a long one, decide which numbers and which
+`PaginationEllipsis` markers to show around the current page yourself (the
+`WithEllipsis` story shows a simple "first, current neighbourhood, last" pattern).
+
+`size` ("sm" | "md", default "md") is set per `PaginationLink`/`PaginationPrevious`/
+`PaginationNext` - keep it consistent across one `Pagination` instance by passing
+the same value to every item, typically from a variable rather than a shared root
+prop.
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `Pagination` | The `nav` root. Sets `role="navigation"` and `aria-label="pagination"`. |
+| `PaginationContent` | The `ul` that lays items out in a row. |
+| `PaginationItem` | A plain `li` wrapper around one link, control, or ellipsis. |
+| `PaginationLink` | A page-number button. `isActive` sets `aria-current="page"` and the active fill; supports `asChild` to render a router `Link` instead of a `button`. |
+| `PaginationPrevious` / `PaginationNext` | `PaginationLink` preconfigured with a chevron icon, a default "Previous"/"Next" label (hidden below `sm`, overridable via `children`), and a default `aria-label`. |
+| `PaginationEllipsis` | A decorative, `aria-hidden` "more pages" marker - not a real page. |

package/knowledge/popover.md

@@ -0,0 +1,159 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: popover
+  sourceFile: packages/design-system/src/components/popover.tsx
+  client: true
+  category: web-app-overlays
+  categoryFromBarrel: web-app-overlays
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Popover
+      kind: component
+      radixSource: "@radix-ui/react-popover#Root"
+      typeText: "FC<PopoverProps>"
+    - name: PopoverAnchor
+      kind: component
+      radixSource: "@radix-ui/react-popover#Anchor"
+      typeText: "ForwardRefExoticComponent<PopoverAnchorProps & RefAttributes<HTMLDivElement>>"
+    - name: PopoverClose
+      kind: component
+      radixSource: "@radix-ui/react-popover#Close"
+      typeText: "ForwardRefExoticComponent<PopoverCloseProps & RefAttributes<HTMLButtonElement>>"
+    - name: PopoverContent
+      kind: component
+      typeText: "ForwardRefExoticComponent<PopoverContentProps & RefAttributes<HTMLDivElement>>"
+    - name: PopoverContentProps
+      kind: type
+    - name: PopoverSize
+      kind: type
+    - name: PopoverTrigger
+      kind: component
+      radixSource: "@radix-ui/react-popover#Trigger"
+      typeText: "ForwardRefExoticComponent<PopoverTriggerProps & RefAttributes<HTMLButtonElement>>"
+  primaryExport: Popover
+  subcomponents:
+    - PopoverAnchor
+    - PopoverClose
+    - PopoverContent
+    - PopoverTrigger
+  props:
+    PopoverContent:
+      - name: size
+        type: "\"lg\" | \"md\" | \"sm\""
+        required: false
+        declaredIn: self
+        variantKey: true
+  extendsProps: []
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: Popover
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-popover"
+      - class-variance-authority
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-popover--default
+  storybookTitle: Components/Popover
+  docsId: components-popover--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "77fe5ab62468"
+  factsHash: "56a35d049707"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A click-triggered floating panel that can hold interactive content - forms, buttons, richer context - anchored to a trigger element."
+useWhen:
+  - "the trigger needs to reveal interactive content (a form, buttons, custom content) rather than a flat list of actions"
+  - "supplementary content should appear next to a specific element, dismissed by clicking outside or pressing Escape"
+useInstead:
+  - id: dropdown-menu
+    when: "the content is just a list of selectable actions or options"
+  - id: tooltip
+    when: "the content is a short, non-interactive label shown on hover or focus, not click"
+  - id: drawer
+    when: "the content needs a full edge-to-edge panel rather than a small anchored one"
+related:
+  - dropdown-menu
+  - tooltip
+  - drawer
+tokens:
+  - "--popover"
+  - "--popover-foreground"
+  - "--border"
+a11y:
+  notes:
+    - "Wrap the real trigger element with PopoverTrigger asChild so Radix attaches its keyboard and ARIA handling directly to it."
+    - "Unlike DropdownMenu, PopoverContent can hold any interactive content (inputs, buttons), and Radix manages focus trapping and Escape-to-close the same way."
+  keyboard:
+    - "Escape closes the popover and returns focus to the trigger. Tab moves through interactive content inside PopoverContent normally - it is not restricted to a roving-menu pattern the way DropdownMenu is."
+  radixHandles: true
+pitfalls:
+  - "size only sets width and padding - it does not scale nested typography the way Dialog/Drawer's size drives a type ramp, so headings or body text inside PopoverContent still need their own sizing."
+  - "className on PopoverTrigger/PopoverAnchor/PopoverClose cannot be demonstrated in this file's machine-checked canonicalSnippet, because the extractor did not resolve their props from the inlined Radix generics - the same gap as dropdown-menu/drawer. See the fuller example in ## Usage."
+  - "PopoverAnchor lets the popover open away from its trigger (e.g. anchor to a table cell while the trigger is a button elsewhere) - most usages do not need it, since PopoverTrigger already anchors by default."
+canonicalSnippet: |
+  import { Button, Popover, PopoverContent, PopoverTrigger } from "@adres/mgda-ui"
+
+  <Popover>
+    <PopoverTrigger asChild>
+      <Button variant="outline">Open popover</Button>
+    </PopoverTrigger>
+    <PopoverContent size="md">
+      <p>Popover content with helpful context.</p>
+    </PopoverContent>
+  </Popover>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "77fe5ab62468"
+---
+
+## Usage
+
+`Popover` is for interactive or richer content anchored to a trigger element
+- a form, a set of buttons, or custom context - dismissed by clicking outside
+or pressing Escape. Reach for `DropdownMenu` instead when the content is just
+a flat list of selectable actions, and `Tooltip` when it is a short label
+shown on hover rather than click.
+
+`size` (`sm`/`md`/`lg`) sets the panel's width and padding only; it does not
+scale nested typography, unlike `Dialog`/`Drawer`. A common alternative is
+overriding width directly via `className`:
+
+```tsx
+<PopoverContent className="ax:w-64">
+  <p className="ax:t-body-sm">Popover content with helpful context.</p>
+</PopoverContent>
+```
+
+`className` is not in this file's machine-checked `canonicalSnippet` for the
+same extractor-gap reason noted in `dropdown-menu.md`/`drawer.md` - use the
+example above as the real usage reference.
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `Popover` | Root. Holds open state. A direct Radix `Root` re-export. |
+| `PopoverTrigger` | Opens the popover. Use `asChild` to wrap a real `Button`. |
+| `PopoverAnchor` | Optional - anchors the popover to a different element than its trigger. Rarely needed. |
+| `PopoverContent` | The floating panel. Sets `size`, and renders its own portal and positioning. Can hold any interactive content. |
+| `PopoverClose` | Radix `Close`. Wrap a `Button` with `asChild` to dismiss from inside the content. |