Amsterdam · VincentSmedinga · Sep 6, 2024 · Sep 6, 2024 · Sep 6, 2024 · Sep 6, 2024
diff --git a/packages/css/src/components/field/field.scss b/packages/css/src/components/field/field.scss
@@ -4,6 +4,7 @@
  */
 
 .ams-field {
+  align-items: start;
   break-inside: avoid;
   display: flex;
   flex-direction: column;

diff --git a/storybook/src/components/Checkbox/Checkbox.docs.mdx b/storybook/src/components/Checkbox/Checkbox.docs.mdx
@@ -17,3 +17,24 @@ import README from "../../../../packages/css/src/components/checkbox/README.md?r
 ### Long label
 
 <Canvas of={CheckboxStories.LongLabel} />
+
+### In a Field Set
+
+Use a Field Set to group several Checkboxes with a legend, description and / or an Error Message.
+
+Because of an [NVDA bug](https://github.com/nvaccess/nvda/issues/12718), we add the description text to the Field Set with `aria-labelledby`,
+instead of `aria-describedby`.
+
+If you don’t need the description, remove its Paragraph and the Paragraphs `id` from the Field Set `aria-labelledby`.
+
+Check [the Field Set docs](/docs/components-forms-field-set--docs) for more information on configuring it.
+
+<Canvas of={CheckboxStories.InAFieldSet} />
+
+### In a Field Set with validation
+
+If the Checkbox can become invalid, add an Error Message component and its `id` to the `aria-labelledby` attribute of the Field Set.
+
+Check [the Field Set docs](/docs/components-forms-field-set--docs) for more information on configuring it.
+
+<Canvas of={CheckboxStories.InAFieldSetWithValidation} />
diff --git a/storybook/src/components/Checkbox/Checkbox.stories.tsx b/storybook/src/components/Checkbox/Checkbox.stories.tsx
@@ -3,6 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
+import { Column, ErrorMessage, FieldSet, Paragraph } from '@amsterdam/design-system-react'
 import { Checkbox } from '@amsterdam/design-system-react/src'
 import { useArgs } from '@storybook/preview-api'
 import { Meta, StoryObj } from '@storybook/react'
@@ -56,3 +57,102 @@ export const LongLabel: Story = {
       'Ik heb alle gegevens correct en volledig ingevuld. Ik begrijp dat een verhuizing via internet dezelfde juridische status heeft als een verhuizing met een geschreven geldige handtekening.',
   },
 }
+
+export const InAFieldSet: Story = {
+  argTypes: {
+    checked: {
+      table: { disable: true },
+    },
+    children: {
+      table: { disable: true },
+    },
+    disabled: {
+      table: { disable: true },
+    },
+    indeterminate: {
+      table: { disable: true },
+    },
+  },
+  render: ({ invalid }) => (
+    <FieldSet
+      aria-labelledby={`fieldset1 description1${invalid ? ' error1' : ''}`}
+      id="fieldset1"
+      invalid={invalid}
+      legend="Waar gaat uw melding over?"
+    >
+      <Paragraph className="ams-mb--sm" id="description1" size="small">
+        De laatstgenoemde melding.
+      </Paragraph>
+      {invalid && (
+        <ErrorMessage className="ams-mb--sm" id="error1">
+          Geef aan waar uw laatstgenoemde melding over gaat.
+        </ErrorMessage>
+      )}
+      <Column gap="extra-small">
+        <Checkbox invalid={invalid} name="about" value="horeca">
+          Horecabedrijf
+        </Checkbox>
+        <Checkbox invalid={invalid} name="about" value="ander_bedrijf">
+          Ander soort bedrijf
+        </Checkbox>
+        <Checkbox invalid={invalid} name="about" value="evenement">
+          Evenement
+        </Checkbox>
+        <Checkbox invalid={invalid} name="about" value="anders">
+          Iets anders
+        </Checkbox>
+      </Column>
+    </FieldSet>
+  ),
+}
+
+export const InAFieldSetWithValidation: Story = {
+  args: {
+    invalid: true,
+  },
+  argTypes: {
+    checked: {
+      table: { disable: true },
+    },
+    children: {
+      table: { disable: true },
+    },
+    disabled: {
+      table: { disable: true },
+    },
+    indeterminate: {
+      table: { disable: true },
+    },
+  },
+  render: ({ invalid }) => (
+    <FieldSet
+      aria-labelledby={`fieldset2 description2${invalid ? ' error2' : ''}`}
+      id="fieldset2"
+      invalid={invalid}
+      legend="Waar gaat uw melding over?"
+    >
+      <Paragraph className="ams-mb--sm" id="description2" size="small">
+        De laatstgenoemde melding.
+      </Paragraph>
+      {invalid && (
+        <ErrorMessage className="ams-mb--sm" id="error2">
+          Geef aan waar uw laatstgenoemde melding over gaat.
+        </ErrorMessage>
+      )}
+      <Column gap="extra-small">
+        <Checkbox invalid={invalid} name="about" value="horeca">
+          Horecabedrijf
+        </Checkbox>
+        <Checkbox invalid={invalid} name="about" value="ander_bedrijf">
+          Ander soort bedrijf
+        </Checkbox>
+        <Checkbox invalid={invalid} name="about" value="evenement">
+          Evenement
+        </Checkbox>
+        <Checkbox invalid={invalid} name="about" value="anders">
+          Iets anders
+        </Checkbox>
+      </Column>
+    </FieldSet>
+  ),
+}
diff --git a/storybook/src/components/Radio/Radio.docs.mdx b/storybook/src/components/Radio/Radio.docs.mdx
@@ -16,7 +16,7 @@ import README from "../../../../packages/css/src/components/radio/README.md?raw"
 
 ### In a Field Set
 
-Use a Field Set to group several Radios with a legend, description and / or an error message.
+Use a Field Set to group several Radios with a legend, description and / or an Error Message.
 
 Add `role="radiogroup"` to the Field Set to have it explicitly announced as a radio group (the default role is just ‘group’).
 The ‘radio group’ role also allows using `aria-required` on Field Set; that isn’t allowed for the ‘group’ role.

diff --git a/storybook/src/components/Select/Select.docs.mdx b/storybook/src/components/Select/Select.docs.mdx
@@ -34,3 +34,21 @@ The component requires a `label` attribute.
 ### Disabled
 
 <Canvas of={SelectStories.Disabled} />
+
+### In a Field
+
+Use a Field to group a Select with a Label, description and / or an Error Message.
+
+If you don’t need the description, remove its Paragraph and the `aria-describedby` from the Select.
+
+Check [the Field docs](/docs/components-forms-field--docs) for more information on configuring it.
+
+<Canvas of={SelectStories.InAField} />
+
+### In a Field with validation
+
+If the Select can become invalid, add an Error Message and its `id` to the `aria-describedby` attribute of the Select.
+
+Check [the Field docs](/docs/components-forms-field--docs) for more information on configuring it.
+
+<Canvas of={SelectStories.InAFieldWithValidation} />
diff --git a/storybook/src/components/Select/Select.stories.tsx b/storybook/src/components/Select/Select.stories.tsx
@@ -3,38 +3,41 @@
  * Copyright Gemeente Amsterdam
  */
 
+import { ErrorMessage, Field, Label, Paragraph } from '@amsterdam/design-system-react'
 import { Select } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
+const optionList = [
+  <Select.Option key="1" value="1">
+    Centrum
+  </Select.Option>,
+  <Select.Option key="2" value="2">
+    Noord
+  </Select.Option>,
+  <Select.Option key="3" value="3">
+    West
+  </Select.Option>,
+  <Select.Option key="4" value="4" disabled>
+    Westpoort
+  </Select.Option>,
+  <Select.Option key="6" value="5">
+    Nieuw-West
+  </Select.Option>,
+  <Select.Option key="7" value="6">
+    Zuid
+  </Select.Option>,
+  <Select.Option key="8" value="7">
+    Zuidoost
+  </Select.Option>,
+]
+
 const meta = {
   title: 'Components/Forms/Select',
   component: Select,
   args: {
     invalid: false,
     disabled: false,
-    children: [
-      <Select.Option key="1" value="1">
-        Centrum
-      </Select.Option>,
-      <Select.Option key="2" value="2">
-        Noord
-      </Select.Option>,
-      <Select.Option key="3" value="3">
-        West
-      </Select.Option>,
-      <Select.Option key="4" value="4" disabled>
-        Westpoort
-      </Select.Option>,
-      <Select.Option key="6" value="5">
-        Nieuw-West
-      </Select.Option>,
-      <Select.Option key="7" value="6">
-        Zuid
-      </Select.Option>,
-      <Select.Option key="8" value="7">
-        Zuidoost
-      </Select.Option>,
-    ],
+    children: optionList,
   },
   argTypes: {
     disabled: {
@@ -111,3 +114,36 @@ export const Disabled: Story = {
     disabled: true,
   },
 }
+
+export const InAField: Story = {
+  render: (args) => (
+    <Field invalid={args.invalid}>
+      <Label htmlFor="input1">Label</Label>
+      <Paragraph id="description1" size="small">
+        Omschrijving.
+      </Paragraph>
+      {args.invalid && <ErrorMessage id="error1">Foutmelding.</ErrorMessage>}
+      <Select aria-describedby={`description1${args.invalid ? ' error1' : ''}`} id="input1" {...args}>
+        {optionList}
+      </Select>
+    </Field>
+  ),
+}
+
+export const InAFieldWithValidation: Story = {
+  args: {
+    invalid: true,
+  },
+  render: (args) => (
+    <Field invalid={args.invalid}>
+      <Label htmlFor="input2">Label</Label>
+      <Paragraph id="description2" size="small">
+        Omschrijving.
+      </Paragraph>
+      {args.invalid && <ErrorMessage id="error2">Foutmelding.</ErrorMessage>}
+      <Select aria-describedby={`description2${args.invalid ? ' error2' : ''}`} id="input2" {...args}>
+        {optionList}
+      </Select>
+    </Field>
+  ),
+}
diff --git a/storybook/src/components/TimeInput/TimeInput.docs.mdx b/storybook/src/components/TimeInput/TimeInput.docs.mdx
@@ -21,3 +21,21 @@ import README from "../../../../packages/css/src/components/time-input/README.md
 ### Disabled
 
 <Canvas of={TimeInputStories.Disabled} />
+
+### In a Field
+
+Use a Field to group a Time Input with a Label, description and / or an Error Message.
+
+If you don’t need the description, remove its Paragraph and the `aria-describedby` from the Time Input.
+
+Check [the Field docs](/docs/components-forms-field--docs) for more information on configuring it.
+
+<Canvas of={TimeInputStories.InAField} />
+
+### In a Field with validation
+
+If the Time Input can become invalid, add an Error Message and its `id` to the `aria-describedby` attribute of the Time Input.
+
+Check [the Field docs](/docs/components-forms-field--docs) for more information on configuring it.
+
+<Canvas of={TimeInputStories.InAFieldWithValidation} />
diff --git a/storybook/src/components/TimeInput/TimeInput.stories.tsx b/storybook/src/components/TimeInput/TimeInput.stories.tsx
@@ -3,6 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
+import { ErrorMessage, Field, Label, Paragraph } from '@amsterdam/design-system-react'
 import { TimeInput } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
@@ -37,3 +38,32 @@ export const Disabled: Story = {
     disabled: true,
   },
 }
+
+export const InAField: Story = {
+  render: (args) => (
+    <Field invalid={args.invalid}>
+      <Label htmlFor="input1">Label</Label>
+      <Paragraph id="description1" size="small">
+        Omschrijving.
+      </Paragraph>
+      {args.invalid && <ErrorMessage id="error1">Foutmelding.</ErrorMessage>}
+      <TimeInput aria-describedby={`description1${args.invalid ? ' error1' : ''}`} id="input1" {...args} />
+    </Field>
+  ),
+}
+
+export const InAFieldWithValidation: Story = {
+  args: {
+    invalid: true,
+  },
+  render: (args) => (
+    <Field invalid={args.invalid}>
+      <Label htmlFor="input2">Label</Label>
+      <Paragraph id="description2" size="small">
+        Omschrijving.
+      </Paragraph>
+      {args.invalid && <ErrorMessage id="error2">Foutmelding.</ErrorMessage>}
+      <TimeInput aria-describedby={`description2${args.invalid ? ' error2' : ''}`} id="input2" {...args} />
+    </Field>
+  ),
+}