feat!: Support various column widths for Description List

packages/css/src/components/description-list/README.md

@@ -6,9 +6,11 @@ A collection of terms and their descriptions.
 
 ## Design
 
-On a narrow screen, descriptions appear indented below their term.
-From the medium breakpoint, terms and descriptions appear next to each other.
-The column for the descriptions is twice as wide as the one for the term.
+In a narrow window, descriptions appear indented below their term.
+After that, they display in a two-column layout.
+The column for the terms is as wide as the longest term, without wrapping.
+Its width can be adjusted to be ‘large’ (50%), ‘medium’ (33%), or ‘small’ (20%), which also allows the terms to wrap.
+
 The term is set in bold text.
 
 ## References

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

@@ -13,18 +13,33 @@
 
 .ams-description-list {
   color: var(--ams-description-list-color);
+  column-gap: var(--ams-description-list-column-gap);
   display: grid;
   font-family: var(--ams-description-list-font-family);
   font-size: var(--ams-description-list-font-size);
-  gap: var(--ams-description-list-gap);
   line-height: var(--ams-description-list-line-height);
+  row-gap: var(--ams-description-list-row-gap);
 
   @include reset;
   @include text-rendering;
+}
 
-  @media screen and (min-width: $ams-breakpoint-medium) {
+@media screen and (min-width: $ams-breakpoint-medium) {
+  .ams-description-list {
+    grid-template-columns: auto 1fr;
+  }
+
+  .ams-description-list--terms-width-sm {
+    grid-template-columns: 1fr 4fr;
+  }
+
+  .ams-description-list--terms-width-md {
     grid-template-columns: 1fr 2fr;
   }
+
+  .ams-description-list--terms-width-lg {
+    grid-template-columns: 1fr 1fr;
+  }
 }
 
 .ams-description-list--inverse-color {

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

@@ -1,6 +1,6 @@
 import { render } from '@testing-library/react'
 import { createRef } from 'react'
-import { DescriptionList } from './DescriptionList'
+import { DescriptionList, descriptionListTermsWidths } from './DescriptionList'
 import '@testing-library/jest-dom'
 
 describe('Description List', () => {
@@ -29,6 +29,16 @@ describe('Description List', () => {
     expect(component).toHaveClass('ams-description-list extra')
   })
 
+  descriptionListTermsWidths.map((width) =>
+    it(`renders the class name for the ‘${width}’ terms column width`, () => {
+      const { container } = render(<DescriptionList termsWidth={width} />)
+
+      const component = container.querySelector(':only-child')
+
+      expect(component).toHaveClass(`ams-description-list--terms-width-${width}`)
+    }),
+  )
+
   it('supports ForwardRef in React', () => {
     const ref = createRef<HTMLDListElement>()
 

packages/react/src/DescriptionList/DescriptionList.tsx

@@ -9,17 +9,30 @@ import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
 import { DescriptionListDetails } from './DescriptionListDetails'
 import { DescriptionListTerm } from './DescriptionListTerm'
 
+export const descriptionListTermsWidths = ['sm', 'md', 'lg'] as const
+type DescriptionListTermsWidth = (typeof descriptionListTermsWidths)[number]
+
 export type DescriptionListProps = {
   /** Changes the text colour for readability on a dark background. */
   inverseColor?: boolean
+  /* The width of the column containing the terms. */
+  termsWidth?: DescriptionListTermsWidth
 } & PropsWithChildren<HTMLAttributes<HTMLDListElement>>
 
 const DescriptionListRoot = forwardRef(
-  ({ children, className, inverseColor, ...restProps }: DescriptionListProps, ref: ForwardedRef<HTMLDListElement>) => (
+  (
+    { children, className, inverseColor, termsWidth, ...restProps }: DescriptionListProps,
+    ref: ForwardedRef<HTMLDListElement>,
+  ) => (
     <dl
       {...restProps}
       ref={ref}
-      className={clsx('ams-description-list', inverseColor && 'ams-description-list--inverse-color', className)}
+      className={clsx(
+        'ams-description-list',
+        `ams-description-list--terms-width-${termsWidth}`,
+        inverseColor && 'ams-description-list--inverse-color',
+        className,
+      )}
     >
       {children}
     </dl>

proprietary/tokens/src/components/ams/description-list.tokens.json

@@ -2,14 +2,12 @@
   "ams": {
     "description-list": {
       "color": { "value": "{ams.color.primary-black}" },
+      "column-gap": { "value": "{ams.space.lg}" },
       "font-family": { "value": "{ams.text.font-family}" },
       "font-size": { "value": "{ams.text.level.5.font-size}" },
-      "gap": { "value": "{ams.space.sm}" },
       "inverse-color": { "value": "{ams.color.primary-white}" },
       "line-height": { "value": "{ams.text.level.5.line-height}" },
-      "row": {
-        "gap": { "value": "{ams.space.sm}" }
-      },
+      "row-gap": { "value": "{ams.space.sm}" },
       "term": {
         "font-weight": { "value": "{ams.text.font-weight.bold}" }
       },

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

@@ -27,6 +27,15 @@ const meta = {
     ],
     inverseColor: false,
   },
+  argTypes: {
+    termsWidth: {
+      control: {
+        type: 'radio',
+        labels: { undefined: 'auto', sm: 'small', md: 'medium', lg: 'large' },
+      },
+      options: [undefined, 'sm', 'md', 'lg'],
+    },
+  },
 } satisfies Meta<typeof DescriptionList>
 
 export default meta
@@ -48,25 +57,29 @@ export const MultipleDescriptions: Story = {
 }
 
 export const RichDescription: Story = {
-  args: {
-    children: [
-      <DescriptionList.Term key={1}>Amsterdam Light Festival</DescriptionList.Term>,
+  render: (args) => (
+    <DescriptionList {...args}>
+      <DescriptionList.Term key={1}>Amsterdam Light Festival</DescriptionList.Term>
       <DescriptionList.Details key={2}>
-        <Paragraph className="ams-mb--sm">
+        <Paragraph className="ams-mb--sm" inverseColor={args.inverseColor}>
           Een jaarlijks evenement waarbij kunstenaars van over de hele wereld hun{' '}
           <strong>creatieve lichtinstallaties</strong> tonen. De kunstwerken zijn verspreid over de stad en zijn zowel
           vanaf het water als vanaf de kant te bewonderen.
         </Paragraph>
-        <UnorderedList>
+        <UnorderedList inverseColor={args.inverseColor}>
           <UnorderedList.Item>Kleed je warm aan, want de meeste exposities zijn buiten.</UnorderedList.Item>
           <UnorderedList.Item>Er zijn begeleide boottochten en wandelroutes beschikbaar.</UnorderedList.Item>
           <UnorderedList.Item>
-            Voor de volledige lijst met exposities kun je <Link href="#">de festivalbrochure downloaden</Link>.
+            Voor de volledige lijst met exposities kun je{' '}
+            <Link href="#" inverseColor={args.inverseColor}>
+              de festivalbrochure downloaden
+            </Link>
+            .
           </UnorderedList.Item>
         </UnorderedList>
-      </DescriptionList.Details>,
-    ],
-  },
+      </DescriptionList.Details>
+    </DescriptionList>
+  ),
 }
 
 export const MultipleTerms: Story = {