feat: Add Hint as component and Label and FieldSet props

packages/css/src/components/blockquote/blockquote.scss

@@ -21,17 +21,17 @@
   line-height: var(--ams-blockquote-line-height);
   quotes: "“" "”";
 
+  @include hyphenation;
+  @include text-rendering;
+  @include reset;
+
   &::before {
     content: open-quote;
   }
 
   &::after {
     content: close-quote;
   }
-
-  @include hyphenation;
-  @include text-rendering;
-  @include reset;
 }
 
 .ams-blockquote--inverse-color {

packages/css/src/components/button/button.scss

@@ -26,13 +26,13 @@
   padding-inline: var(--ams-button-padding-inline);
   touch-action: manipulation;
 
+  @include text-rendering;
+  @include reset-button;
+
   &:disabled,
   &[aria-disabled="true"] {
     cursor: var(--ams-button-disabled-cursor);
   }
-
-  @include text-rendering;
-  @include reset-button;
 }
 
 @mixin ams-button-forced-color-mode {
@@ -46,6 +46,8 @@
   box-shadow: var(--ams-button-primary-box-shadow);
   color: var(--ams-button-primary-color);
 
+  @include ams-button-forced-color-mode;
+
   &:disabled,
   [aria-disabled="true"] {
     background-color: var(--ams-button-primary-disabled-background-color);
@@ -56,15 +58,15 @@
     background-color: var(--ams-button-primary-hover-background-color);
     box-shadow: var(--ams-button-primary-hover-box-shadow);
   }
-
-  @include ams-button-forced-color-mode;
 }
 
 .ams-button--secondary {
   background-color: var(--ams-button-secondary-background-color);
   box-shadow: var(--ams-button-secondary-box-shadow);
   color: var(--ams-button-secondary-color);
 
+  @include ams-button-forced-color-mode;
+
   &:disabled,
   [aria-disabled="true"] {
     background-color: var(--ams-button-secondary-disabled-background-color);
@@ -76,8 +78,6 @@
     box-shadow: var(--ams-button-secondary-hover-box-shadow);
     color: var(--ams-button-secondary-hover-color);
   }
-
-  @include ams-button-forced-color-mode;
 }
 
 .ams-button--tertiary {

packages/css/src/components/checkbox/checkbox.scss

@@ -44,6 +44,8 @@
   line-height: var(--ams-checkbox-line-height);
   outline-offset: var(--ams-checkbox-outline-offset);
 
+  @include text-rendering;
+
   &:hover {
     color: var(--ams-checkbox-hover-color);
     text-decoration-line: underline;
@@ -55,8 +57,6 @@
       border-width: var(--ams-checkbox-checkmark-hover-border-width);
     }
   }
-
-  @include text-rendering;
 }
 
 // Default checked

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

@@ -20,12 +20,12 @@
   gap: var(--ams-description-list-gap);
   line-height: var(--ams-description-list-line-height);
 
+  @include reset;
+  @include text-rendering;
+
   @media screen and (min-width: $ams-breakpoint-medium) {
     grid-template-columns: 1fr 2fr;
   }
-
-  @include reset;
-  @include text-rendering;
 }
 
 .ams-description-list--inverse-color {
@@ -46,10 +46,10 @@
   font-weight: var(--ams-description-list-details-font-weight);
   padding-inline-start: var(--ams-description-list-details-padding-inline-start);
 
+  @include reset-details;
+
   @media screen and (min-width: $ams-breakpoint-medium) {
     grid-column-start: 2;
     padding-inline-start: 0;
   }
-
-  @include reset-details;
 }

packages/css/src/components/field-set/README.md

@@ -7,6 +7,10 @@ A component to group related form inputs.
 ## Guidelines
 
 - Use Field Set when you need to show a relationship between multiple form inputs. For example, you may need to group a set of text inputs into a single Field Set when asking for an address.
+- If all the child form elements get a `required` attribute with the same value, then add the same property with that value to the Field Set. Also make sure to have an empty string as a value for the `flag` property on all the Label components to avoid many, redundant ‟not required” labels.
+- If the various child form elements have mixed `required` attribute values then do the reverse and leave the `required` property undefined and set the `flag` property to an empty string on the Field Set and set the `required` property on the child labels and inputs as needed.
+- Make sure to set the `optional` prop to `true` if the associated form elements are not required for form submission. The Field Set's legend will then get the descriptive text “(niet verplicht)” if the `hint` prop is not set.
+- If a `hint` is provided its value will be displayed after the legend regardless of the value of `optional`.
 
 ## Relevant WCAG requirements
 

packages/css/src/components/file-input/file-input.scss

@@ -48,13 +48,13 @@
   padding-block: var(--ams-file-input-file-selector-button-padding-block);
   padding-inline: var(--ams-file-input-file-selector-button-padding-inline);
 
+  @include reset-button;
+
   @media screen and (-ms-high-contrast: active), screen and (forced-colors: active) {
     border: var(
       --ams-file-input-file-selector-button-forced-color-mode-border
     ); // add border because forced colors changes box-shadow to none
   }
-
-  @include reset-button;
 }
 
 .ams-file-input:disabled::file-selector-button {

packages/css/src/components/hint/README.md

@@ -0,0 +1,9 @@
+<!-- @license CC0-1.0 -->
+
+# Hint
+
+Provides additional information to an inline element such as a `Label` or `Legend` in a `Field` or `FieldSet` respectively. Typically used to communicate whether a form field is optional or required.
+
+## Class name
+
+`ams-hint`

packages/css/src/components/hint/hint.scss

@@ -0,0 +1,9 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+.ams-hint {
+  color: var(--ams-hint-color);
+  white-space: nowrap;
+}

packages/css/src/components/icon-button/icon-button.scss

@@ -20,6 +20,8 @@
   outline-offset: var(--ams-icon-button-outline-offset);
   touch-action: manipulation;
 
+  @include reset;
+
   &:hover {
     background-color: var(--ams-icon-button-hover-background-color);
     color: var(--ams-icon-button-hover-color);
@@ -30,8 +32,6 @@
     color: var(--ams-icon-button-disabled-color);
     cursor: not-allowed;
   }
-
-  @include reset;
 }
 
 .ams-icon-button--contrast-color {

packages/css/src/components/index.scss

@@ -4,6 +4,7 @@
  */
 
 /* Append here */
+@import "./hint/hint";
 @import "./password-input/password-input";
 @import "./form-error-list/form-error-list";
 @import "./table-of-contents/table-of-contents";

packages/css/src/components/label/README.md

@@ -7,3 +7,5 @@ Describes a form control.
 ## Guidelines
 
 - Always associate a form element (such as an `input` or `textarea`) with a label.
+- Make sure to set the `optional` prop to `true` if the associated form element is not required for form submission. The label will then get the descriptive text “(niet verplicht)” if the `hint` prop is not set.
+- If a `hint` is provided its value will be displayed after the label regardless of the value of `optional`.

packages/css/src/components/link/link.scss

@@ -11,11 +11,11 @@
   font-weight: var(--ams-link-font-weight);
   outline-offset: var(--ams-link-outline-offset);
 
+  @include text-rendering;
+
   &:hover {
     color: var(--ams-link-hover-color);
   }
-
-  @include text-rendering;
 }
 
 .ams-link--standalone {

packages/css/src/components/pagination/pagination.scss

@@ -45,22 +45,22 @@
   text-underline-offset: var(--ams-pagination-button-text-underline-offset);
   touch-action: manipulation;
 
-  &:hover {
-    color: var(--ams-pagination-button-hover-color);
-    text-decoration-line: var(--ams-pagination-button-hover-text-decoration-line);
-  }
+  @include text-rendering;
 
   &:disabled {
     display: none;
   }
 
+  &:hover {
+    color: var(--ams-pagination-button-hover-color);
+    text-decoration-line: var(--ams-pagination-button-hover-text-decoration-line);
+  }
+
   // Override for icon size
   span.ams-icon svg {
     block-size: 1rem;
     inline-size: 1rem;
   }
-
-  @include text-rendering;
 }
 
 .ams-pagination__button--current {

packages/css/src/components/radio/radio.scss

@@ -45,6 +45,8 @@
   line-height: var(--ams-radio-line-height);
   outline-offset: var(--ams-radio-outline-offset);
 
+  @include text-rendering;
+
   &:hover {
     color: var(--ams-radio-hover-color);
     text-decoration-line: underline;
@@ -55,8 +57,6 @@
       border-color: var(--ams-radio-circle-hover-border-color);
     }
   }
-
-  @include text-rendering;
 }
 
 // Default checked

packages/css/src/components/select/select.scss

@@ -23,6 +23,8 @@
   padding-inline: var(--ams-select-padding-inline);
   touch-action: manipulation;
 
+  @include reset;
+
   &:not([multiple]) {
     background-image: var(--ams-select-background-image);
     background-position: var(--ams-select-background-position);
@@ -33,8 +35,6 @@
   &:hover {
     box-shadow: var(--ams-select-hover-box-shadow);
   }
-
-  @include reset;
 }
 
 .ams-select:invalid,

packages/react/src/FieldSet/FieldSet.test.tsx

@@ -54,4 +54,36 @@ describe('FieldSet', () => {
 
     expect(ref.current).toBe(component)
   })
+
+  it("renders a hint text after the field-set's legend not marked as optional", () => {
+    const { container } = render(<FieldSet legend="Legend" hint="hint text" />)
+
+    const legend = container.querySelector('legend')
+
+    expect(legend).toHaveTextContent('Legend (hint text)')
+  })
+
+  it('renders the default hint text "niet verplicht" after the field-set\'s legend marked as optional', () => {
+    const { container } = render(<FieldSet legend="Legend" optional={true} />)
+
+    const legend = container.querySelector('legend')
+
+    expect(legend).toHaveTextContent('Legend (niet verplicht)')
+  })
+
+  it('renders the provided hint text "optional" after the field-set\'s legend marked as optional', () => {
+    const { container } = render(<FieldSet legend="Legend" optional={true} hint="optional" />)
+
+    const legend = container.querySelector('legend')
+
+    expect(legend).toHaveTextContent('Legend (optional)')
+  })
+
+  it('renders the provided hint text "required" after the field-set\'s legend marked as not optional', () => {
+    const { container } = render(<FieldSet legend="Legend" optional={false} hint="required" />)
+
+    const legend = container.querySelector('legend')
+
+    expect(legend).toHaveTextContent('Legend (required)')
+  })
 })

packages/react/src/FieldSet/FieldSet.tsx

@@ -6,25 +6,43 @@
 import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
+import { Hint, HintProps } from '../Hint'
 
 export type FieldSetProps = PropsWithChildren<HTMLAttributes<HTMLFieldSetElement>> & {
   /** Whether the field set has an input with a validation error */
   invalid?: boolean
   /** The text for the caption. */
   legend: string
-}
+  /** Whether the associated inputs are optional. Will append the text '(niet verplicht)' to the label if no hint is provided. */
+  optional?: boolean
+} & HintProps
 
 export const FieldSet = forwardRef(
-  ({ children, className, invalid, legend, ...restProps }: FieldSetProps, ref: ForwardedRef<HTMLFieldSetElement>) => (
-    <fieldset
-      {...restProps}
-      ref={ref}
-      className={clsx('ams-field-set', invalid && 'ams-field-set--invalid', className)}
-    >
-      <legend className="ams-field-set__legend">{legend}</legend>
-      {children}
-    </fieldset>
-  ),
+  (
+    { children, className, invalid, legend, hint, optional, ...restProps }: FieldSetProps,
+    ref: ForwardedRef<HTMLFieldSetElement>,
+  ) => {
+    let optionalHint = null
+
+    if (optional) {
+      optionalHint = hint ? <Hint hint={hint} /> : <Hint hint="niet verplicht" />
+    } else if (hint) {
+      optionalHint = <Hint hint={hint} />
+    }
+
+    return (
+      <fieldset
+        {...restProps}
+        ref={ref}
+        className={clsx('ams-field-set', invalid && 'ams-field-set--invalid', className)}
+      >
+        <legend className="ams-field-set__legend">
+          {legend} {optionalHint}
+        </legend>
+        {children}
+      </fieldset>
+    )
+  },
 )
 
 FieldSet.displayName = 'FieldSet'