@adres/mgda-ui 0.0.0-stage → 0.0.2

package/knowledge/dialog.md

@@ -0,0 +1,249 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: dialog
+  sourceFile: packages/design-system/src/components/dialog.tsx
+  client: true
+  category: web-app-overlays
+  categoryFromBarrel: web-app-overlays
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Dialog
+      kind: component
+      radixSource: "@radix-ui/react-dialog#Root"
+      typeText: "FC<DialogProps>"
+    - name: DialogClose
+      kind: component
+      radixSource: "@radix-ui/react-dialog#Close"
+      typeText: "ForwardRefExoticComponent<DialogCloseProps & RefAttributes<HTMLButtonElement>>"
+    - name: DialogContent
+      kind: component
+      typeText: "ForwardRefExoticComponent<DialogContentProps & RefAttributes<HTMLDivElement>>"
+    - name: DialogContentProps
+      kind: type
+    - name: DialogDescription
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<DialogDescriptionProps & RefAttributes<HTMLParagraphElement>, \"ref\"> & RefAttributes<HTMLParagraphElement>>"
+    - name: DialogFooter
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>>"
+    - name: DialogHeader
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>>"
+    - name: DialogOverlay
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<DialogOverlayProps & RefAttributes<HTMLDivElement>, \"ref\"> & RefAttributes<HTMLDivElement>>"
+    - name: DialogPortal
+      kind: component
+      radixSource: "@radix-ui/react-dialog#Portal"
+      typeText: "FC<DialogPortalProps>"
+    - name: DialogSize
+      kind: type
+    - name: DialogTitle
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<DialogTitleProps & RefAttributes<HTMLHeadingElement>, \"ref\"> & RefAttributes<HTMLHeadingElement>>"
+    - name: DialogTrigger
+      kind: component
+      radixSource: "@radix-ui/react-dialog#Trigger"
+      typeText: "ForwardRefExoticComponent<DialogTriggerProps & RefAttributes<HTMLButtonElement>>"
+  primaryExport: Dialog
+  subcomponents:
+    - DialogClose
+    - DialogContent
+    - DialogDescription
+    - DialogFooter
+    - DialogHeader
+    - DialogOverlay
+    - DialogPortal
+    - DialogTitle
+    - DialogTrigger
+  props:
+    DialogContent:
+      - name: size
+        type: DialogSize
+        required: false
+        declaredIn: self
+  extendsProps: []
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: DialogContent
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - CLOSE_ICON
+    - DESCRIPTION_SIZE
+    - FOOTER_MT
+    - GAP
+    - MAX_WIDTH
+    - PADDING
+    - TITLE_SIZE
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-dialog"
+      - lucide-react
+      - react
+  contexts:
+    - name: DialogSizeContext
+      type: DialogSize
+      default: md
+  stories:
+    - exportName: Default
+      id: components-dialog--default
+  storybookTitle: Components/Dialog
+  docsId: components-dialog--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "033e8fe255cf"
+  factsHash: "7355195a3254"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A modal overlay for a focused task the user must finish or dismiss."
+useWhen:
+  - "confirming a destructive action before it happens"
+  - "a short form that should not lose the page behind it"
+  - "the user must decide something before continuing"
+useInstead:
+  - id: drawer
+    when: "the content is long or form-heavy, especially on mobile, where a side or bottom sheet gives more room"
+  - id: popover
+    when: "the content is a small non-blocking detail anchored to the trigger"
+  - id: dropdown-menu
+    when: "you are offering a list of actions rather than a task"
+  - id: toaster
+    when: "you are reporting a result and the user does not need to respond"
+related:
+  - drawer
+  - popover
+  - dropdown-menu
+  - button
+composesWith:
+  - button
+  - input
+  - select
+tokens:
+  - "--card"
+  - "--border"
+  - "--foreground"
+  - "--ring"
+  - "--motion-base"
+  - "--motion-ease-out"
+a11y:
+  notes:
+    - "Radix supplies the whole modal contract: focus trap, focus restore to the trigger, Escape to close, click-outside, scroll lock, and aria-modal."
+    - "A DialogTitle is required. Radix warns when Content has no accessible name, and screen reader users get an unnamed dialog."
+    - "The built-in close button already carries an sr-only \"Close\" label, so it does not need one adding."
+    - "Entry animation is suppressed under prefers-reduced-motion via motion-reduce:animate-none."
+  requiredProps:
+    - "DialogTitle inside DialogContent, even if you visually hide it"
+  keyboard:
+    - "Escape closes. Tab cycles within the dialog only. Focus returns to the trigger on close."
+    - "DialogClose can wrap any button to make it dismiss the dialog, which is preferable to wiring onClick to setOpen yourself."
+  radixHandles: true
+pitfalls:
+  - "DialogContent already renders DialogPortal and DialogOverlay internally. Wrapping it in your own DialogPortal or rendering a sibling DialogOverlay produces a double portal or two stacked scrims that darken twice. Both are exported for escape hatches, not for normal composition."
+  - "DialogContent also injects its own close button in the top corner. Adding another icon button there gives the user two X controls."
+  - "size lives only on DialogContent and reaches DialogTitle, DialogDescription and DialogFooter through context. Passing size to Dialog, DialogHeader, or the title itself does nothing and is silently ignored."
+  - "DialogFooter is flex-col-reverse below the sm breakpoint. The primary action should be last in the DOM so it lands on top on mobile and right-most on desktop. Putting it first inverts on small screens."
+  - "DialogHeader is the one part that does not read the size context, so its internal gap stays fixed while the rest of the dialog scales."
+subcomponentNotes:
+  DialogContent: "Owns size, and is the only place to set it. Renders its own portal, overlay and close button."
+  DialogFooter: "Reads size from context for its top margin. Reverses order on mobile, so DOM order matters."
+  DialogHeader: "Plain flex column. Does not scale with size."
+  DialogOverlay: "Exported for escape hatches only. DialogContent already renders one."
+  DialogPortal: "Exported for escape hatches only. DialogContent already renders one."
+rtl: "Safe. Positioning is centred with transforms and the close button uses logical right-md, which mirrors correctly."
+brandNotes: "The scrim uses --foreground at 40 percent in light and switches to black in dark, because --foreground inverts and would otherwise tint the scrim whitish. A brand changing --foreground affects the scrim in light mode only."
+canonicalSnippet: |
+  import {
+    Dialog,
+    DialogTrigger,
+    DialogContent,
+    DialogHeader,
+    DialogTitle,
+    DialogDescription,
+    DialogFooter,
+    DialogClose,
+    Button,
+  } from "@adres/mgda-ui"
+
+  <Dialog>
+    <DialogTrigger asChild>
+      <Button variant="destructive">Delete project</Button>
+    </DialogTrigger>
+    <DialogContent size="sm">
+      <DialogHeader>
+        <DialogTitle>Delete this project?</DialogTitle>
+        <DialogDescription>
+          This removes every file in it. The action cannot be undone.
+        </DialogDescription>
+      </DialogHeader>
+      <DialogFooter>
+        <DialogClose asChild>
+          <Button variant="outline">Cancel</Button>
+        </DialogClose>
+        <Button variant="destructive">Delete</Button>
+      </DialogFooter>
+    </DialogContent>
+  </Dialog>
+reviewedAt: 2026-08-19
+reviewedAgainstContractHash: 033e8fe255cf
+---
+
+## Usage
+
+Dialog blocks the page, so it is the most expensive interruption in the system. Use it
+when the user genuinely cannot continue without deciding, and prefer `Drawer` whenever
+the content is long enough to scroll.
+
+Radix owns all the modal behaviour, which means the accessibility work is already done
+and should not be re-implemented. What this component adds on top is a size scale and
+the brand-bound surface.
+
+`size` is the only variant, and it does more than set a width. It selects the max
+width, interior padding, content gap, title and description type scale, close icon
+size, and footer top margin, all from parallel maps keyed on the same value. That is
+why adding a new size means touching seven maps in one file, which `sizeMaps` in the
+derived facts records.
+
+### Sizes
+
+| Size | Max width | Intended for |
+| --- | --- | --- |
+| `sm` | 320px | compact confirmations and alerts |
+| `md` | 448px, the default | typical form dialogs |
+| `lg` | 768px | wide or multi-column content |
+
+## Anatomy
+
+`Dialog` is a compound component. Four parts are bare Radix re-exports, and six are
+styled wrappers.
+
+| Part | Role |
+| --- | --- |
+| `Dialog` | Radix `Root`. Holds open state. |
+| `DialogTrigger` | Radix `Trigger`. Use `asChild` to wrap your own Button. |
+| `DialogContent` | The panel. **Sets `size`**, and renders its own portal, overlay and close button. |
+| `DialogHeader` | Groups title and description. |
+| `DialogTitle` | Required for an accessible name. Scales with `size`. |
+| `DialogDescription` | Supporting text. Scales with `size`. |
+| `DialogFooter` | The action row. Reverses order on mobile. |
+| `DialogClose` | Radix `Close`. Wrap a Button with `asChild` to dismiss. |
+| `DialogPortal` | Escape hatch. Already rendered by `DialogContent`. |
+| `DialogOverlay` | Escape hatch. Already rendered by `DialogContent`. |
+
+The nesting that matters: `size` on `DialogContent` flows through
+`DialogSizeContext` to the title, description and footer. Nothing else in the file
+surfaces that relationship, which is why it is worth stating here.

package/knowledge/drawer.md

@@ -0,0 +1,236 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: drawer
+  sourceFile: packages/design-system/src/components/drawer.tsx
+  client: true
+  category: web-app-overlays
+  categoryFromBarrel: web-app-overlays
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Drawer
+      kind: component
+      typeText: "({ open: controlledOpen, onOpenChange, defaultOpen, children, ...props }: DrawerProps) => Element"
+    - name: DrawerBody
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>>"
+    - name: DrawerClose
+      kind: component
+      radixSource: "@radix-ui/react-dialog#Close"
+      typeText: "ForwardRefExoticComponent<DialogCloseProps & RefAttributes<HTMLButtonElement>>"
+    - name: DrawerContent
+      kind: component
+      typeText: "ForwardRefExoticComponent<DrawerContentProps & RefAttributes<HTMLDivElement>>"
+    - name: DrawerContentProps
+      kind: type
+    - name: DrawerDescription
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<DialogDescriptionProps & RefAttributes<HTMLParagraphElement>, \"ref\"> & RefAttributes<HTMLParagraphElement>>"
+    - name: DrawerFooter
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>>"
+    - name: DrawerHeader
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>>"
+    - name: DrawerProps
+      kind: type
+    - name: DrawerSide
+      kind: type
+    - name: DrawerSize
+      kind: type
+    - name: DrawerTitle
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<DialogTitleProps & RefAttributes<HTMLHeadingElement>, \"ref\"> & RefAttributes<HTMLHeadingElement>>"
+    - name: DrawerTrigger
+      kind: component
+      radixSource: "@radix-ui/react-dialog#Trigger"
+      typeText: "ForwardRefExoticComponent<DialogTriggerProps & RefAttributes<HTMLButtonElement>>"
+  primaryExport: Drawer
+  subcomponents:
+    - DrawerBody
+    - DrawerClose
+    - DrawerContent
+    - DrawerDescription
+    - DrawerFooter
+    - DrawerHeader
+    - DrawerTitle
+    - DrawerTrigger
+  props:
+    DrawerContent:
+      - name: backdrop
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Show the translucent backdrop. Default: true."
+      - name: side
+        type: DrawerSide
+        required: false
+        declaredIn: self
+      - name: size
+        type: DrawerSize
+        required: false
+        declaredIn: self
+  extendsProps:
+    - "React.ComponentPropsWithoutRef<typeof DialogPrimitive.Root>"
+  variants:
+    side:
+      kind: enum
+      options:
+        - left
+        - right
+        - bottom
+        - top
+      default: right
+      on: DrawerContent
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: DrawerContent
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - DESCRIPTION_SIZE
+    - DRAG_BY_SIDE
+    - END_HEIGHT
+    - SIDE_WIDTH
+    - TITLE_SIZE
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+      - motion
+    hooks:
+      - use-reduced-motion
+    external:
+      - "@radix-ui/react-dialog"
+      - lucide-react
+      - motion/react
+      - react
+  contexts:
+    - name: DrawerSizeContext
+      type: DrawerSize
+      default: md
+    - name: DrawerOpenContext
+      type: DrawerOpenContextValue
+      default: null
+  stories:
+    - exportName: Default
+      id: components-drawer--default
+  storybookTitle: Components/Drawer
+  docsId: components-drawer--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "6af2f793ca6c"
+  factsHash: c4fc32424690
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A side-anchored (or bottom/top) sliding panel built on Radix Dialog, with drag-to-dismiss and independent enter/exit motion."
+useWhen:
+  - "showing a detail panel, filter set, or form alongside the page rather than fully blocking it, especially content long enough to scroll"
+  - "a mobile-style bottom sheet is the right pattern (side=\"bottom\")"
+useInstead:
+  - id: dialog
+    when: "the content is a compact, blocking decision that does not need to slide in from an edge or scroll at length"
+  - id: popover
+    when: "the content is small and anchored to a specific trigger element, not a full edge-to-edge panel"
+related:
+  - dialog
+  - popover
+tokens:
+  - "--card"
+  - "--border"
+  - "--foreground"
+  - "--muted-foreground"
+  - "--ring"
+a11y:
+  notes:
+    - "Built on Radix Dialog, so it inherits accessible dialog semantics (focus trap, Escape to close, focus restore on close) even though it looks and animates like a custom sheet."
+    - "DrawerTitle is required for an accessible name, the same as Dialog - there is no visual-only alternative that also satisfies screen readers."
+    - "The built-in close button already includes a visually-hidden \"Close\" label - it does not need (or use) an aria-label passed to DrawerContent."
+  keyboard:
+    - "Escape closes, same as the underlying Radix Dialog. Drag-to-dismiss is a pointer/touch-only affordance with no keyboard equivalent - Escape remains the way to close via keyboard."
+  radixHandles: true
+pitfalls:
+  - "DrawerContent forces its own mount/unmount via forceMount plus AnimatePresence to run motion/react's exit animation - fighting that mounting model (e.g. conditionally rendering DrawerContent yourself) breaks the slide-out animation."
+  - "The drag handle affordance only renders for side=\"bottom\"/\"top\" - left/right panels support the same drag-to-close gesture functionally but show no visible handle, since an edge-swipe is the expected gesture there instead."
+  - "size drives four separate maps at once (width or height, drag behavior, title scale, description scale) - adding a new size means touching all of them, the same pattern Dialog's size maps use."
+  - "Reduced-motion does not just shorten the animation, it also disables drag-to-dismiss entirely - a reduced-motion user closes exclusively via the close button, backdrop click, or Escape."
+canonicalSnippet: |
+  import {
+    Button,
+    Drawer,
+    DrawerBody,
+    DrawerClose,
+    DrawerContent,
+    DrawerFooter,
+    DrawerHeader,
+    DrawerTitle,
+    DrawerTrigger,
+  } from "@adres/mgda-ui"
+
+  <Drawer>
+    <DrawerTrigger asChild>
+      <Button>Open filters</Button>
+    </DrawerTrigger>
+    <DrawerContent side="right" size="md">
+      <DrawerHeader>
+        <DrawerTitle>Filters</DrawerTitle>
+      </DrawerHeader>
+      <DrawerBody>
+        <p>Drawer content goes here.</p>
+      </DrawerBody>
+      <DrawerFooter>
+        <DrawerClose asChild>
+          <Button variant="outline">Close</Button>
+        </DrawerClose>
+      </DrawerFooter>
+    </DrawerContent>
+  </Drawer>
+reviewedAt: 2026-09-29
+reviewedAgainstContractHash: "6af2f793ca6c"
+---
+
+## Usage
+
+`Drawer` slides a panel in from an edge (`side="right"` by default, or
+`"left"`/`"top"`/`"bottom"`) rather than blocking the page in place - reach for
+it over `Dialog` when the content is long enough to scroll, or needs the extra
+room a full-height/width panel gives. `side="bottom"` is the mobile-style
+bottom-sheet pattern, and shows a drag handle affordance that `left`/`right`
+panels intentionally omit (they rely on an edge-swipe gesture instead).
+
+Every side supports drag-to-dismiss automatically - a user can drag the panel
+back off-screen past a distance or velocity threshold. `size` (`sm`/`md`/`lg`)
+scales width (for `left`/`right`) or max-height (for `top`/`bottom`) together
+with the title and description type scale, mirroring how `Dialog`'s `size`
+works.
+
+Set `backdrop={false}` on `DrawerContent` to suppress the translucent scrim
+when the drawer should not visually block the rest of the page.
+
+## Anatomy
+
+`Drawer` is a compound component built directly on Radix Dialog's parts.
+
+| Part | Role |
+| --- | --- |
+| `Drawer` | Root. Wraps Radix `Dialog.Root` and mirrors open state into its own context so `DrawerContent` can run independent `motion/react` exit animations. |
+| `DrawerTrigger` | Opens the drawer. Use `asChild` to wrap a real `Button`. |
+| `DrawerContent` | The sliding panel. Sets `side`, `size`, and `backdrop`; renders its own portal, backdrop, drag handling, and close button. |
+| `DrawerHeader` | Groups the title and description, reserving space for the close button. |
+| `DrawerTitle` | Required for an accessible name. Scales with `size`. |
+| `DrawerDescription` | Supporting text. Scales with `size`. |
+| `DrawerBody` | The scrollable content area between header and footer. |
+| `DrawerFooter` | The action row. |
+| `DrawerClose` | Radix `Close`. Wrap a `Button` with `asChild` to dismiss. |
+
+The nesting that matters: `size` on `DrawerContent` flows through
+`DrawerSizeContext` to the title and description, the same pattern `Dialog`
+uses for its own size-driven type scale.