feat!: Add Action Group component, e.g. to wrap Dialog buttons in

packages/css/src/components/dialog/dialog.scss

@@ -30,23 +30,22 @@ so do not apply these styles without an `open` attribute. */
   }
 }
 
-.ams-dialog__body {
-  overflow-y: auto;
-  overscroll-behavior-y: contain;
-}
-
 .ams-dialog__header {
   align-items: flex-start;
   display: flex;
   gap: var(--ams-dialog-header-gap);
   justify-content: space-between;
 }
 
-.ams-dialog__footer {
-  display: flex;
+.ams-dialog__body {
+  overflow-y: auto;
+  overscroll-behavior-y: contain;
+}
+
+.ams-dialog__action-group {
+  display: inline-flex;
   flex-wrap: wrap; // [1]
-  gap: var(--ams-dialog-footer-gap);
-  margin-inline-end: auto; // [1]
+  gap: var(--ams-dialog-action-group-gap);
 
   > * {
     flex: auto; // [1]

packages/react/src/Dialog/Dialog.tsx

@@ -8,11 +8,12 @@ import { forwardRef, MouseEvent } from 'react'
 import type { DialogHTMLAttributes, ForwardedRef, PropsWithChildren, ReactNode } from 'react'
 import { Heading } from '../Heading'
 import { IconButton } from '../IconButton'
+import { DialogActionGroup } from './DialogActionGroup'
 
 export type DialogProps = {
   /** The label for the button that dismisses the Dialog. */
   closeButtonLabel?: string
-  /** The button(s) in the footer. Start with a primary button. */
+  /** Content for the footer, often an Action Group with one or more buttons. */
   footer?: ReactNode
   /** The text for the Heading. */
   heading: string
@@ -40,6 +41,7 @@ const DialogRoot = forwardRef(
 DialogRoot.displayName = 'Dialog'
 
 export const Dialog = Object.assign(DialogRoot, {
+  ActionGroup: DialogActionGroup,
   close: closeDialog,
   open: openDialog,
 })

packages/react/src/Dialog/DialogActionGroup.test.tsx

@@ -0,0 +1,41 @@
+import { render } from '@testing-library/react'
+import { createRef } from 'react'
+import '@testing-library/jest-dom'
+import { Dialog } from './Dialog'
+
+describe('Dialog Action Group', () => {
+  it('renders', () => {
+    const { container } = render(<Dialog.ActionGroup />)
+
+    const component = container.querySelector(':only-child')
+
+    expect(component).toBeInTheDocument()
+    expect(component).toBeVisible()
+  })
+
+  it('renders a design system BEM class name', () => {
+    const { container } = render(<Dialog.ActionGroup />)
+
+    const component = container.querySelector(':only-child')
+
+    expect(component).toHaveClass('ams-dialog__action-group')
+  })
+
+  it('renders an additional class name', () => {
+    const { container } = render(<Dialog.ActionGroup className="extra" />)
+
+    const component = container.querySelector(':only-child')
+
+    expect(component).toHaveClass('ams-dialog__action-group extra')
+  })
+
+  it('supports ForwardRef in React', () => {
+    const ref = createRef<HTMLDivElement>()
+
+    const { container } = render(<Dialog.ActionGroup ref={ref} />)
+
+    const component = container.querySelector(':only-child')
+
+    expect(ref.current).toBe(component)
+  })
+})

packages/react/src/Dialog/DialogActionGroup.tsx

@@ -0,0 +1,20 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+import clsx from 'clsx'
+import { forwardRef } from 'react'
+import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
+
+export type DialogActionGroupProps = PropsWithChildren<HTMLAttributes<HTMLDivElement>>
+
+export const DialogActionGroup = forwardRef(
+  ({ children, className, ...restProps }: DialogActionGroupProps, ref: ForwardedRef<HTMLDivElement>) => (
+    <div {...restProps} ref={ref} className={clsx('ams-dialog__action-group', className)}>
+      {children}
+    </div>
+  ),
+)
+
+DialogActionGroup.displayName = 'DialogActionGroup'

proprietary/tokens/src/components/ams/dialog.tokens.json

@@ -12,7 +12,7 @@
       "header": {
         "gap": { "value": "{ams.space.md}" }
       },
-      "footer": {
+      "action-group": {
         "gap": { "value": "{ams.space.md}" }
       }
     }

storybook/src/components/Dialog/Dialog.docs.mdx

@@ -14,34 +14,35 @@ import README from "../../../../packages/css/src/components/dialog/README.md?raw
 
 ## Examples
 
-### Form in a Dialog
+### Open and close
 
-Set `method="dialog"` when using a form in Dialog.
-This closes the Dialog when submitting the form.
-Pass the submit Button to the `footer` prop,
-and link it to the form by passing its `id` to the Buttons `form` attribute.
-The Dialog returns the value of the submit Button, so you can check which Button was clicked.
-For more information, see [Handling the return value from the dialog (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog#handling_the_return_value_from_the_dialog).
+To open the Dialog, use `Dialog.open(dialogId)` from the React package.
+To close the Dialog, use either `Dialog.close`, or a `<form>` as in the following example.
 
-<Canvas of={DialogStories.FormDialog} />
+<Canvas of={DialogStories.OpenAndClose} />
 
-### With scrollbar
+### Asking to confirm
 
-Content taller than the dialog itself will scroll.
+Use a `<form>` when asking to confirm an action, e.g. through ‘OK’ and ‘Cancel’ buttons.
+Add `method="dialog"` to let the browser close the Dialog automatically when the form is submitted.
 
-<Canvas of={DialogStories.WithScrollbar} />
+Wrap one or more buttons in an Action Group and place it in the `footer`.
+This ensures correct whitespace and scrolling behaviour.
+At the same time, it positions the buttons outside the `form` element.
+Create an `id` for the form and add it to the submit Button’s `form` attribute to connect the two.
 
-### Trigger Button
+If the Action Group needs to live inside of the `form`, add a medium bottom margin (`ams-mb--md`) to the element before it and make scrolling work correctly.
 
-Click or tap this Button to open the Dialog.
+The form returns the `value` of the submit Button, which allows inferring which Button the user clicked.
+For more information, see [Handling the return value from the dialog (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog#handling_the_return_value_from_the_dialog).
 
-<Canvas of={DialogStories.TriggerButton} />
+<Canvas of={DialogStories.AskingToConfirm} />
 
-#### Utility functions
+### Tall content will scroll
 
-To open the Dialog, use `Dialog.open(id)` from the React package.
-Pass the Dialog’s `id` to the function to select it.
-To close the Dialog, use `Dialog.close`.
+Content that doesn’t fit entirely in the Dialog will scroll.
+
+<Canvas of={DialogStories.WithScrollbar} />
 
 ### Vertically stacked Buttons