From 81859a1d9d648eab0792f4adfe42649a3062dc8d Mon Sep 17 00:00:00 2001
From: Lea <lea.gardavaud@post.ch>
Date: Wed, 20 Nov 2024 07:55:23 +0100
Subject: [PATCH] feat(styles): component form hint (#3961)

Co-authored-by: Philipp Gfeller <1659006+gfellerph@users.noreply.github.com>
---
 .changeset/wild-bugs-work.md                  |  5 +++
 .../components/dialog/dialog.stories.ts       |  5 ++-
 .../components/forms/input/input.stories.ts   |  3 +-
 .../components/forms/select/select.stories.ts |  5 ++-
 .../forms/slider/slider.snapshot.stories.ts   |  1 +
 .../components/forms/slider/slider.stories.ts | 45 +++++++++----------
 .../forms/textarea/textarea.stories.ts        |  5 ++-
 .../foundation/icons/search-icons.blocks.tsx  |  5 ++-
 .../src/stories/patterns/forms/forms.docs.mdx | 18 ++++----
 .../stories/patterns/forms/forms.stories.ts   |  7 ++-
 packages/styles/src/components/_index.scss    |  1 +
 packages/styles/src/components/form-hint.scss | 16 +++++++
 .../styles/src/components/form-range.scss     |  2 +-
 .../styles/src/components/form-select.scss    |  6 ---
 packages/styles/src/components/forms.scss     | 14 +++---
 .../styles/src/themes/bootstrap/_forms.scss   |  1 -
 .../themes/bootstrap/forms/_form-text.scss    |  2 -
 17 files changed, 78 insertions(+), 63 deletions(-)
 create mode 100644 .changeset/wild-bugs-work.md
 create mode 100644 packages/styles/src/components/form-hint.scss
 delete mode 100644 packages/styles/src/themes/bootstrap/forms/_form-text.scss

diff --git a/.changeset/wild-bugs-work.md b/.changeset/wild-bugs-work.md
new file mode 100644
index 0000000000..a3a23a20bb
--- /dev/null
+++ b/.changeset/wild-bugs-work.md
@@ -0,0 +1,5 @@
+---
+'@swisspost/design-system-styles': major
+---
+
+Changed the class name of assistive text below form fields from `.form-text` to `.form-hint` and improved accessibility by connecting the hint to the form through `aria-describedby`.
diff --git a/packages/documentation/src/stories/components/dialog/dialog.stories.ts b/packages/documentation/src/stories/components/dialog/dialog.stories.ts
index 24569321fe..8f21a73884 100644
--- a/packages/documentation/src/stories/components/dialog/dialog.stories.ts
+++ b/packages/documentation/src/stories/components/dialog/dialog.stories.ts
@@ -185,13 +185,14 @@ const FormTemplate = {
                 type="text"
                 placeholder="Placeholder"
                 name="example-text-field"
+                aria-describedby="example-form-hint"
                 required
               />
               <label class="form-label" for="example-dialog-text-field">Label</label>
-              <div class="form-text">
+              <p class="form-hint" id="example-form-hint">
                 Hintus textus elare volare cantare hendrerit in vulputate velit esse molestie
                 consequat, vel illum dolore eu feugiat nulla facilisis.
-              </div>
+              </p>
             </div>
           </div>
 
diff --git a/packages/documentation/src/stories/components/forms/input/input.stories.ts b/packages/documentation/src/stories/components/forms/input/input.stories.ts
index 173667c2e3..482cb53def 100644
--- a/packages/documentation/src/stories/components/forms/input/input.stories.ts
+++ b/packages/documentation/src/stories/components/forms/input/input.stories.ts
@@ -160,7 +160,7 @@ function render(args: Args, context: StoryContext) {
   const contextual: (TemplateResult | null)[] = [
     args.validation === 'is-valid' ? html` <p class="valid-feedback">Ggranda sukceso!</p> ` : null,
     args.validation === 'is-invalid' ? html` <p class="invalid-feedback">Eraro okazis!</p> ` : null,
-    args.hint !== '' ? html` <div class="form-text">${args.hint}</div> ` : null,
+    args.hint !== '' ? html` <p class="form-hint" id="form-hint-${id}">${args.hint}</p> ` : null,
   ];
 
   const control: TemplateResult = html`
@@ -172,6 +172,7 @@ function render(args: Args, context: StoryContext) {
       ?disabled="${args.disabled}"
       aria-label="${useAriaLabel ? args.label : nothing}"
       ?aria-invalid="${VALIDATION_STATE_MAP[args.validation]}"
+      aria-describedby="${args.hint !== '' ? 'form-hint-' + id : nothing}"
       value="${args.value ? args.value : nothing}"
     />
   `;
diff --git a/packages/documentation/src/stories/components/forms/select/select.stories.ts b/packages/documentation/src/stories/components/forms/select/select.stories.ts
index aead5f98ae..d7bcf900c7 100644
--- a/packages/documentation/src/stories/components/forms/select/select.stories.ts
+++ b/packages/documentation/src/stories/components/forms/select/select.stories.ts
@@ -242,7 +242,9 @@ const Template: Story = {
       args.validation === 'is-invalid'
         ? html` <p class="invalid-feedback">Eraro okazis!</p> `
         : null,
-      args.hint !== '' ? html` <div class="form-text">${args.hint}</div> ` : null,
+      args.hint !== ''
+        ? html` <p class="form-hint" id="form-hint-${context.id}">${args.hint}</p> `
+        : null,
     ];
     const control = html`
       <select
@@ -253,6 +255,7 @@ const Template: Story = {
         ?disabled="${args.disabled}"
         aria-label="${useAriaLabel ? args.label : nothing}"
         aria-invalid="${ifDefined(VALIDATION_STATE_MAP[args.validation])}"
+        aria-describedby="${args.hint !== '' ? 'form-hint-' + context.id : ''}"
         @change="${(e: Event) => {
           updateArgs({ value: (e.target as HTMLSelectElement).value });
         }}"
diff --git a/packages/documentation/src/stories/components/forms/slider/slider.snapshot.stories.ts b/packages/documentation/src/stories/components/forms/slider/slider.snapshot.stories.ts
index 0175dd301d..0aeff5518d 100644
--- a/packages/documentation/src/stories/components/forms/slider/slider.snapshot.stories.ts
+++ b/packages/documentation/src/stories/components/forms/slider/slider.snapshot.stories.ts
@@ -20,6 +20,7 @@ export const Slider: Story = {
           bg => html`
             <div
               class="${bg} d-flex  flex-wrap align-items-start flex-column gap-16 p-16"
+              data-color-scheme=${bg === 'bg-white' ? 'light' : 'dark'}
             >
               ${[
                 ...bombArgs({
diff --git a/packages/documentation/src/stories/components/forms/slider/slider.stories.ts b/packages/documentation/src/stories/components/forms/slider/slider.stories.ts
index 63ec8f29f3..11b80f8019 100644
--- a/packages/documentation/src/stories/components/forms/slider/slider.stories.ts
+++ b/packages/documentation/src/stories/components/forms/slider/slider.stories.ts
@@ -195,46 +195,41 @@ function render(args: Args, context: StoryContext) {
       ?disabled="${args.disabled}"
       aria-label="${useAriaLabel ? args.label : nothing}"
       ?aria-invalid="${VALIDATION_STATE_MAP[args.validation]}"
+      aria-describedby="${args.showValue === 'text' ? 'form-hint-' + id : ''}"
       @input="${(e: MouseEvent) => updateArgs({ value: (e.target as HTMLInputElement).value })}"
     />
   `;
 
-  let valueElement: TemplateResult | TemplateResult[] | null = null;
+  let valueElement: TemplateResult | null = null;
 
-  if (args.showValue === 'text') {
-    valueElement = html` <p class="form-text">${args.value}</p> `;
-  } else if (args.showValue === 'input') {
+  if (args.showValue === 'input') {
     const inputId = context.id
       ? `${context.id}_input`
       : `${context.viewMode}_${context.name.replace(/\s/g, '-')}_ExampleRangeInput`;
 
-    valueElement = [
-      html` <label class="form-label visually-hidden" for="${inputId}">Range controller</label> `,
-      html`
-        <input
-          id="${inputId}"
-          class="form-control mw-giant"
-          type="text"
-          inputmode="decimal"
-          value="${args.value}"
-          .value="${args.value}"
-          ?disabled="${args.disabled}"
-          @input="${(e: Event) => updateArgs({ value: (e.target as HTMLInputElement).value })}"
-        />
-      `,
-    ];
-  }
-
-  if (args.showValue === 'input') {
     return html`
       <div class="row align-items-end">
         <div class="col">${[label, control, ...contextual].filter(el => el !== null)}</div>
-        <div class="col-auto">${valueElement}</div>
+        <div class="col-auto">
+          <label class="form-label visually-hidden" for="${inputId}">Range controller</label>
+          <input
+            id="${inputId}"
+            class="form-control mw-giant"
+            type="text"
+            inputmode="decimal"
+            value="${args.value}"
+            .value="${args.value}"
+            ?disabled="${args.disabled}"
+            @input="${(e: Event) => updateArgs({ value: (e.target as HTMLInputElement).value })}"
+          />
+        </div>
       </div>
     `;
-  } else {
-    return html`${[label, control, valueElement, ...contextual].filter(el => el !== null)}`;
+  } else if (args.showValue === 'text') {
+    valueElement = html`<p class="form-hint" id="form-hint-${id}">${args.value}</p> `;
   }
+
+  return html`${[label, control, valueElement, ...contextual].filter(el => el !== null)}`;
 }
 
 export const Default: Story = {};
diff --git a/packages/documentation/src/stories/components/forms/textarea/textarea.stories.ts b/packages/documentation/src/stories/components/forms/textarea/textarea.stories.ts
index d9e6521b8e..5db16960ff 100644
--- a/packages/documentation/src/stories/components/forms/textarea/textarea.stories.ts
+++ b/packages/documentation/src/stories/components/forms/textarea/textarea.stories.ts
@@ -194,7 +194,9 @@ function renderTextarea(args: Args, context: StoryContext) {
     args.validation === 'is-invalid'
       ? html`<div class="invalid-feedback">Eraro okazis!</div>`
       : null,
-    args.hint !== '' ? html`<div class="form-text">${args.hint}</div>` : null,
+    args.hint !== ''
+      ? html`<p class="form-hint" id="form-hint-${context.id}">${args.hint}</p>`
+      : null,
   ];
   const control = html`
     <textarea
@@ -206,6 +208,7 @@ function renderTextarea(args: Args, context: StoryContext) {
       ?disabled=${args.disabled}
       aria-label=${useAriaLabel ? args.label : nothing}
       aria-invalid=${VALIDATION_STATE_MAP[args.validation] ?? nothing}
+      aria-describedby="${args.hint ? 'form-hint-' + context.id : ''}"
       style=${args.resize ?? nothing}
     >
 ${args.textInside ?? nothing}</textarea
diff --git a/packages/documentation/src/stories/foundation/icons/search-icons.blocks.tsx b/packages/documentation/src/stories/foundation/icons/search-icons.blocks.tsx
index ea23fb2dd7..57ceed733c 100644
--- a/packages/documentation/src/stories/foundation/icons/search-icons.blocks.tsx
+++ b/packages/documentation/src/stories/foundation/icons/search-icons.blocks.tsx
@@ -48,6 +48,7 @@ export class Search extends React.Component {
               id="IconSearchFilter_Freetext"
               type="text"
               className="form-control"
+              aria-describedby="search-icon-form-hint"
               placeholder=""
               value={this.state.freetext}
               onChange={this.searchFreetext.bind(this)}
@@ -60,9 +61,9 @@ export class Search extends React.Component {
                 <span className="visually-hidden">Reset Search</span>
               </button>
             ) : null}
-            <div className="form-text">
+            <p className="form-hint" id="search-icon-form-hint">
               {`Showing ${this.state.icons.length} of ${report.icons.length} icons.`}
-            </div>
+            </p>
           </div>
         </div>
 
diff --git a/packages/documentation/src/stories/patterns/forms/forms.docs.mdx b/packages/documentation/src/stories/patterns/forms/forms.docs.mdx
index 422328226b..2dc4414f77 100644
--- a/packages/documentation/src/stories/patterns/forms/forms.docs.mdx
+++ b/packages/documentation/src/stories/patterns/forms/forms.docs.mdx
@@ -9,10 +9,7 @@ import * as FormPatternsStories from './forms.stories';
 
 All things need to be contained inside a container. The container limits the size of the content and centers it on the page.
 
-<Source
-  code={`<div class="container">...</div>`}
-  language="html"
-/>
+<Source code={`<div class="container">...</div>`} language="html" />
 
 ## Basic input
 
@@ -24,6 +21,7 @@ next to the field.
 <Canvas of={FormPatternsStories.BasicInput} sourceState="shown" />
 
 ## Vertical spacing
+
 To add space between input, you can use [margin utilities](/?path=/docs/facaacfd-18f1-49b4-80f1-a96680730fa0--docs).
 
 <Canvas of={FormPatternsStories.VerticalSpacing} sourceState="shown" />
@@ -74,13 +72,13 @@ Validation messages are placed directly after the `<input>`
 (or after the `<label>` in the case of floating label). Showing and hiding of these messages is typically controlled by
 adding and removing validation classes on the input:
 
-* The message needs the class `.invalid-feedback/.valid-feedback`
-* The form needs the class `.was-validated`. With this class you can manage when to display errors. Usually, errors should not be
-shown on untouched fields.
+- The message needs the class `.invalid-feedback/.valid-feedback`
+- The form needs the class `.was-validated`. With this class you can manage when to display errors. Usually, errors should not be
+  shown on untouched fields.
 
- Or
+Or
 
- The input field needs the class `.is-invalid/.is-valid`
+The input field needs the class `.is-invalid/.is-valid`
 
 <Canvas of={FormPatternsStories.Validation} sourceState="shown" />
 
@@ -90,7 +88,7 @@ Hints can help users better understand the type of information they need to prov
 validation messages, must be placed after the `<input>` (or `<label>`
 in the case of floating label) and after validation messages if there are some.
 
-Hints use the class `.form-text`.
+Hints use the class `.form-hint`.
 
 To enable screen-readers to detect and read your hints, link the `<input>`
 with the aria-describedby attribute to the hint via id.
diff --git a/packages/documentation/src/stories/patterns/forms/forms.stories.ts b/packages/documentation/src/stories/patterns/forms/forms.stories.ts
index 46cb6db6e1..8303ad68c7 100644
--- a/packages/documentation/src/stories/patterns/forms/forms.stories.ts
+++ b/packages/documentation/src/stories/patterns/forms/forms.stories.ts
@@ -346,10 +346,9 @@ export const Hints: Story = {
         placeholder=" "
       />
       <label class="form-label" for="firstname">Firstname</label>
-      <div id="firstname-hint" class="form-text">
-        <i class="pi pi-info" aria-hidden="true"></i>
-        <span>Also provide any middle names in this field</span>
-      </div>
+      <p id="firstname-hint" class="form-hint">
+        Also provide any middle names in this field
+      </p>
     </div>
   `,
 };
diff --git a/packages/styles/src/components/_index.scss b/packages/styles/src/components/_index.scss
index 31ac54c0c8..20fd7f3141 100644
--- a/packages/styles/src/components/_index.scss
+++ b/packages/styles/src/components/_index.scss
@@ -22,6 +22,7 @@
 @use 'datatable';
 @use 'dialog';
 @use 'form-check';
+@use 'form-hint';
 @use 'forms';
 @use 'grid';
 @use 'icon-button';
diff --git a/packages/styles/src/components/form-hint.scss b/packages/styles/src/components/form-hint.scss
new file mode 100644
index 0000000000..263a9d84ef
--- /dev/null
+++ b/packages/styles/src/components/form-hint.scss
@@ -0,0 +1,16 @@
+@use './../functions/tokens';
+@use './../tokens/components';
+
+tokens.$default-map: components.$post-text-input;
+
+.form-hint {
+  color: tokens.get('input-color-enabled-fg');
+  padding-inline: tokens.get('input-padding-inline-assist');
+  padding-block: tokens.get('input-padding-block-assist');
+  font-size: tokens.get('input-assist-font-size');
+  margin-block-start: 0;
+}
+
+.form-control:disabled .form-hint {
+  color: tokens.get('input-color-disabled-fg');
+}
diff --git a/packages/styles/src/components/form-range.scss b/packages/styles/src/components/form-range.scss
index ad2bd646cb..692f4b847a 100644
--- a/packages/styles/src/components/form-range.scss
+++ b/packages/styles/src/components/form-range.scss
@@ -113,7 +113,7 @@ $webkit-thumb-width: 32px;
     }
   }
 
-  + .form-text {
+  + .form-hint {
     margin-top: spacing.$size-regular;
     transform: translateY(#{-0.5 * forms.$form-range-height});
   }
diff --git a/packages/styles/src/components/form-select.scss b/packages/styles/src/components/form-select.scss
index 9169d2ed10..517a1dba6e 100644
--- a/packages/styles/src/components/form-select.scss
+++ b/packages/styles/src/components/form-select.scss
@@ -49,12 +49,6 @@
     }
   }
 
-  @include utilities.disabled-style {
-    ~ .form-text {
-      color: var(--post-gray-60);
-    }
-  }
-
   &:not([multiple]) {
     &:disabled {
       background-image: b.escape-svg(form-select.$form-select-indicator-disabled),
diff --git a/packages/styles/src/components/forms.scss b/packages/styles/src/components/forms.scss
index 5826eca31a..2b66002aa4 100644
--- a/packages/styles/src/components/forms.scss
+++ b/packages/styles/src/components/forms.scss
@@ -56,12 +56,6 @@ tokens.$default-map: components.$post-text-input;
     }
   }
 
-  @include utilities.disabled-style {
-    ~ .form-text {
-      color: tokens.get('input-color-disabled-fg');
-    }
-  }
-
   &[readonly]:not(:disabled) {
     border-color: tokens.get('input-color-enabled-border');
     background-color: tokens.get('input-color-enabled-bg');
@@ -164,7 +158,7 @@ tokens.$default-map: components.$post-text-input;
   }
 
   &::placeholder {
-    color: tokens.get('input-color-helptext-fg');
+    color: tokens.get('input-color-enabled-fg');
     opacity: 1;
   }
 
@@ -172,7 +166,13 @@ tokens.$default-map: components.$post-text-input;
     color: tokens.get('input-color-disabled-fg');
     background-color: tokens.get('input-color-disabled-bg');
     border-color: tokens.get('input-color-disabled-border');
+    border-style: tokens.get('input-border-style-disabled');
     opacity: 1;
+
+    &::placeholder {
+      color: tokens.get('input-color-disabled-fg');
+      opacity: 1;
+    }
   }
 
   &:hover:not(:disabled):not([readonly])::file-selector-button {
diff --git a/packages/styles/src/themes/bootstrap/_forms.scss b/packages/styles/src/themes/bootstrap/_forms.scss
index 9d163b8c5e..41d7db7897 100644
--- a/packages/styles/src/themes/bootstrap/_forms.scss
+++ b/packages/styles/src/themes/bootstrap/_forms.scss
@@ -1,4 +1,3 @@
-@forward './forms/form-text';
 @forward './forms/form-select';
 @forward './forms/form-range';
 @forward './forms/input-group';
diff --git a/packages/styles/src/themes/bootstrap/forms/_form-text.scss b/packages/styles/src/themes/bootstrap/forms/_form-text.scss
deleted file mode 100644
index 27b503aa42..0000000000
--- a/packages/styles/src/themes/bootstrap/forms/_form-text.scss
+++ /dev/null
@@ -1,2 +0,0 @@
-@use './../core' as *;
-@import 'bootstrap/scss/forms/form-text';