fix: Correct layout of Description List if multiple terms share a description

packages/css/src/components/description-list/description-list.scss

@@ -25,19 +25,30 @@
 }
 
 @media screen and (min-width: $ams-breakpoint-medium) {
-  .ams-description-list {
+  .ams-description-list__group {
+    column-gap: var(--ams-description-list-column-gap);
+    display: grid;
+    grid-auto-flow: dense;
+    grid-column: span 2;
+  }
+
+  .ams-description-list,
+  .ams-description-list__group {
     grid-template-columns: auto 1fr;
   }
 
-  .ams-description-list--terms-width-sm {
+  .ams-description-list--terms-width-sm,
+  .ams-description-list--terms-width-sm .ams-description-list__group {
     grid-template-columns: 1fr 4fr;
   }
 
-  .ams-description-list--terms-width-md {
+  .ams-description-list--terms-width-md,
+  .ams-description-list--terms-width-md .ams-description-list__group {
     grid-template-columns: 1fr 2fr;
   }
 
-  .ams-description-list--terms-width-lg {
+  .ams-description-list--terms-width-lg,
+  .ams-description-list--terms-width-lg .ams-description-list__group {
     grid-template-columns: 1fr 1fr;
   }
 }

packages/react/src/DescriptionList/DescriptionList.tsx

@@ -7,6 +7,7 @@ import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
 import { DescriptionListDescription } from './DescriptionListDescription'
+import { DescriptionListGroup } from './DescriptionListGroup'
 import { DescriptionListTerm } from './DescriptionListTerm'
 
 export const descriptionListTermsWidths = ['sm', 'md', 'lg'] as const
@@ -44,4 +45,5 @@ DescriptionListRoot.displayName = 'DescriptionList'
 export const DescriptionList = Object.assign(DescriptionListRoot, {
   Term: DescriptionListTerm,
   Description: DescriptionListDescription,
+  Group: DescriptionListGroup,
 })

packages/react/src/DescriptionList/DescriptionListGroup.test.tsx

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

packages/react/src/DescriptionList/DescriptionListGroup.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 DescriptionListGroupProps = PropsWithChildren<HTMLAttributes<HTMLDivElement>>
+
+export const DescriptionListGroup = forwardRef(
+  ({ children, className, ...restProps }: DescriptionListGroupProps, ref: ForwardedRef<HTMLDivElement>) => (
+    <div {...restProps} ref={ref} className={clsx('ams-description-list__group', className)}>
+      {children}
+    </div>
+  ),
+)
+
+DescriptionListGroup.displayName = 'DescriptionList.Group'

storybook/src/components/DescriptionList/DescriptionList.docs.mdx

@@ -20,6 +20,14 @@ A term may have multiple descriptions.
 
 <Canvas of={DescriptionListStories.MultipleDescriptions} />
 
+### Multiple terms
+
+In the case of multiple consequtive terms for a description you need to
+wrap all `DescriptionList.Term` and `DescriptionList.Description` pairs in `DescriptionList.Group`.
+And it will also require the minWidth property to be set to anything but `auto` to prevent the misalignment of different groups.
+
+<Canvas of={DescriptionListStories.MultipleTerms} />
+
 ### Rich description
 
 A description can include rich content such as inline formatting, links, paragraphs, and even lists.

storybook/src/components/DescriptionList/DescriptionList.stories.tsx

@@ -54,6 +54,32 @@ export const MultipleDescriptions: Story = {
   },
 }
 
+export const MultipleTerms: Story = {
+  args: {
+    termsWidth: 'md',
+    children: [
+      <DescriptionList.Term key={1}>Achternaam</DescriptionList.Term>,
+      <DescriptionList.Description key={2}>
+        De naam die een persoon van zijn of haar ouders krijgt
+      </DescriptionList.Description>,
+      <DescriptionList.Group key={2}>
+        <DescriptionList.Term key={1}>Naam</DescriptionList.Term>
+        <DescriptionList.Term key={2}>Voornaam</DescriptionList.Term>
+        <DescriptionList.Term key={3}>Roepnaam</DescriptionList.Term>
+        <DescriptionList.Term key={4}>Bijnaam</DescriptionList.Term>
+        <DescriptionList.Description key={5}>
+          De naam waarmee een persoon wordt aangesproken
+        </DescriptionList.Description>
+        <DescriptionList.Description key={6}>
+          De naam waarmee een persoon wordt aangesproken
+        </DescriptionList.Description>
+      </DescriptionList.Group>,
+      <DescriptionList.Term key={1}>Geboortedatum</DescriptionList.Term>,
+      <DescriptionList.Description key={2}>De datum waarop een persoon is geboren</DescriptionList.Description>,
+    ],
+  },
+}
+
 export const RichDescription: Story = {
   render: (args) => (
     <DescriptionList {...args}>