From 1cd29d8315fa41121a9956c66605c3a588ef09f9 Mon Sep 17 00:00:00 2001
From: Douglas Bouttell
 <155977861+douglasbouttell-camunda@users.noreply.github.com>
Date: Thu, 15 Feb 2024 11:36:38 +0000
Subject: [PATCH] feat(a11y): fields announce their descriptions and labels
 properly (#1043)

* Include all description blocks in `aria-describedby`.
* Add `required` property to inputs that can be required.
* Add `aria-invalid` property to input which have validation errors.
* Do not announce the asterisk/star which denotes a required field.
* Have components generate their own error ID.
* Remove confusing use of `id` in Label. It now has an `id` and an `htmlFor` prop.
* Update groups `aria-labelledby` to point to an actual label.
---
 .../src/render/components/Description.js           |  4 ++--
 .../src/render/components/FormField.js             |  2 --
 .../form-js-viewer/src/render/components/Label.js  |  8 +++++---
 .../src/render/components/form-fields/Checkbox.js  | 14 +++++++++-----
 .../src/render/components/form-fields/Checklist.js | 14 +++++++++-----
 .../src/render/components/form-fields/Datetime.js  |  7 ++++---
 .../src/render/components/form-fields/IFrame.js    |  2 +-
 .../src/render/components/form-fields/Number.js    | 14 +++++++++-----
 .../src/render/components/form-fields/Radio.js     | 14 +++++++++-----
 .../src/render/components/form-fields/Select.js    | 14 +++++++++-----
 .../src/render/components/form-fields/Table.js     |  2 +-
 .../src/render/components/form-fields/Taglist.js   | 14 +++++++++-----
 .../src/render/components/form-fields/Textarea.js  | 14 +++++++++-----
 .../src/render/components/form-fields/Textfield.js | 14 +++++++++-----
 .../components/form-fields/parts/Datepicker.js     |  2 +-
 .../components/form-fields/parts/Timepicker.js     |  2 +-
 16 files changed, 87 insertions(+), 54 deletions(-)

diff --git a/packages/form-js-viewer/src/render/components/Description.js b/packages/form-js-viewer/src/render/components/Description.js
index 3a6d40d3c..7dc6d1ac1 100644
--- a/packages/form-js-viewer/src/render/components/Description.js
+++ b/packages/form-js-viewer/src/render/components/Description.js
@@ -2,7 +2,7 @@ import { useSingleLineTemplateEvaluation } from '../hooks';
 
 
 export function Description(props) {
-  const { description } = props;
+  const { description, id } = props;
 
   const evaluatedDescription = useSingleLineTemplateEvaluation(description || '', { debug: true });
 
@@ -10,5 +10,5 @@ export function Description(props) {
     return null;
   }
 
-  return <div class="fjs-form-field-description">{ evaluatedDescription }</div>;
+  return <div id={ id } class="fjs-form-field-description">{ evaluatedDescription }</div>;
 }
\ No newline at end of file
diff --git a/packages/form-js-viewer/src/render/components/FormField.js b/packages/form-js-viewer/src/render/components/FormField.js
index c4d0741bd..27e38c47b 100644
--- a/packages/form-js-viewer/src/render/components/FormField.js
+++ b/packages/form-js-viewer/src/render/components/FormField.js
@@ -128,7 +128,6 @@ export function FormField(props) {
 
   const domId = `${prefixId(field.id, formId, indexes)}`;
   const fieldErrors = get(errors, [ field.id, ...Object.values(indexes || {}) ]) || [];
-  const errorMessageId = errors.length === 0 ? undefined : `${domId}-error-message`;
 
   return (
     <Column field={ field } class={ gridColumnClasses(field) }>
@@ -137,7 +136,6 @@ export function FormField(props) {
           { ...props }
           disabled={ disabled }
           errors={ fieldErrors }
-          errorMessageId={ errorMessageId }
           domId={ domId }
           onChange={ disabled || readonly ? noop : onChangeIndexed }
           onBlur={ disabled || readonly ? noop : onBlur }
diff --git a/packages/form-js-viewer/src/render/components/Label.js b/packages/form-js-viewer/src/render/components/Label.js
index 971195375..81292a879 100644
--- a/packages/form-js-viewer/src/render/components/Label.js
+++ b/packages/form-js-viewer/src/render/components/Label.js
@@ -5,7 +5,8 @@ import { useSingleLineTemplateEvaluation } from '../hooks';
 
 /**
  * @typedef Props
- * @property {string} [id]
+ * @property {string|undefined} [id]
+ * @property {string|undefined} [htmlFor]
  * @property {string|undefined} label
  * @property {string} [class]
  * @property {boolean} [collapseOnEmpty]
@@ -18,6 +19,7 @@ import { useSingleLineTemplateEvaluation } from '../hooks';
 export function Label(props) {
   const {
     id,
+    htmlFor,
     label,
     collapseOnEmpty = true,
     required = false
@@ -26,11 +28,11 @@ export function Label(props) {
   const evaluatedLabel = useSingleLineTemplateEvaluation(label || '', { debug: true });
 
   return (
-    <label for={ id } class={ classNames('fjs-form-field-label', { 'fjs-incollapsible-label': !collapseOnEmpty }, props['class']) }>
+    <label id={ id } for={ htmlFor } class={ classNames('fjs-form-field-label', { 'fjs-incollapsible-label': !collapseOnEmpty }, props['class']) }>
       { props.children }
       { evaluatedLabel }
       {
-        required && <span class="fjs-asterix">*</span>
+        required && <span class="fjs-asterix" aria-hidden>*</span>
       }
     </label>
   );
diff --git a/packages/form-js-viewer/src/render/components/form-fields/Checkbox.js b/packages/form-js-viewer/src/render/components/form-fields/Checkbox.js
index 849a335a5..0fd5e5848 100644
--- a/packages/form-js-viewer/src/render/components/form-fields/Checkbox.js
+++ b/packages/form-js-viewer/src/render/components/form-fields/Checkbox.js
@@ -14,7 +14,6 @@ export function Checkbox(props) {
   const {
     disabled,
     errors = [],
-    errorMessageId,
     domId,
     onBlur,
     onFocus,
@@ -38,9 +37,12 @@ export function Checkbox(props) {
     });
   };
 
+  const descriptionId = `${domId}-description`;
+  const errorMessageId = `${domId}-error-message`;
+
   return <div class={ classNames(formFieldClasses(type, { errors, disabled, readonly }), { 'fjs-checked': value }) }>
     <Label
-      id={ domId }
+      htmlFor={ domId }
       label={ label }
       required={ required }>
       <input
@@ -53,10 +55,12 @@ export function Checkbox(props) {
         onChange={ onChange }
         onBlur={ () => onBlur && onBlur() }
         onFocus={ () => onFocus && onFocus() }
-        aria-describedby={ errorMessageId } />
+        required={ required }
+        aria-invalid={ errors.length > 0 }
+        aria-describedby={ [ descriptionId, errorMessageId ].join(' ') } />
     </Label>
-    <Description description={ description } />
-    <Errors errors={ errors } id={ errorMessageId } />
+    <Description id={ descriptionId } description={ description } />
+    <Errors id={ errorMessageId } errors={ errors } />
   </div>;
 }
 
diff --git a/packages/form-js-viewer/src/render/components/form-fields/Checklist.js b/packages/form-js-viewer/src/render/components/form-fields/Checklist.js
index 7f0f89e7e..b594f94ec 100644
--- a/packages/form-js-viewer/src/render/components/form-fields/Checklist.js
+++ b/packages/form-js-viewer/src/render/components/form-fields/Checklist.js
@@ -23,7 +23,6 @@ export function Checklist(props) {
   const {
     disabled,
     errors = [],
-    errorMessageId,
     domId,
     onBlur,
     onFocus,
@@ -85,6 +84,9 @@ export function Checklist(props) {
     onChange: props.onChange
   });
 
+  const descriptionId = `${domId}-description`;
+  const errorMessageId = `${domId}-error-message`;
+
   return <div class={ classNames(formFieldClasses(type, { errors, disabled, readonly })) } ref={ outerDivRef }>
     <Label
       label={ label }
@@ -97,7 +99,7 @@ export function Checklist(props) {
 
         return (
           <Label
-            id={ itemDomId }
+            htmlFor={ itemDomId }
             label={ o.label }
             class={ classNames({
               'fjs-checked': isChecked
@@ -113,13 +115,15 @@ export function Checklist(props) {
               onClick={ () => toggleCheckbox(o.value) }
               onBlur={ onCheckboxBlur }
               onFocus={ onCheckboxFocus }
-              aria-describedby={ errorMessageId } />
+              required={ required }
+              aria-invalid={ errors.length > 0 }
+              aria-describedby={ [ descriptionId, errorMessageId ].join(' ') } />
           </Label>
         );
       })
     }
-    <Description description={ description } />
-    <Errors errors={ errors } id={ errorMessageId } />
+    <Description id={ descriptionId } description={ description } />
+    <Errors id={ errorMessageId } errors={ errors } />
   </div>;
 }
 
diff --git a/packages/form-js-viewer/src/render/components/form-fields/Datetime.js b/packages/form-js-viewer/src/render/components/form-fields/Datetime.js
index 861b19b28..f92b5ef41 100644
--- a/packages/form-js-viewer/src/render/components/form-fields/Datetime.js
+++ b/packages/form-js-viewer/src/render/components/form-fields/Datetime.js
@@ -150,6 +150,7 @@ export function Datetime(props) {
   }, []);
 
   const errorMessageId = allErrors.length === 0 ? undefined : `${prefixId(id, formId)}-error-message`;
+  const descriptionId = `${prefixId(id, formId)}-description`;
 
   const datePickerProps = {
     label: dateLabel,
@@ -163,7 +164,7 @@ export function Datetime(props) {
     date: dateTime.date,
     readonly,
     setDate,
-    'aria-describedby': errorMessageId
+    'aria-describedby': [ descriptionId, errorMessageId ].join(' ')
   };
 
   const timePickerProps = {
@@ -179,7 +180,7 @@ export function Datetime(props) {
     timeInterval,
     time: dateTime.time,
     setTime,
-    'aria-describedby': errorMessageId
+    'aria-describedby': [ descriptionId, errorMessageId ].join(' ')
   };
 
   return <div class={ formFieldClasses(type, { errors: allErrors, disabled, readonly }) }>
@@ -188,7 +189,7 @@ export function Datetime(props) {
       { useTimePicker && useDatePicker && <div class="fjs-datetime-separator" /> }
       { useTimePicker && <Timepicker { ...timePickerProps } /> }
     </div>
-    <Description description={ description } />
+    <Description id={ descriptionId } description={ description } />
     <Errors errors={ allErrors } id={ errorMessageId } />
   </div>;
 }
diff --git a/packages/form-js-viewer/src/render/components/form-fields/IFrame.js b/packages/form-js-viewer/src/render/components/form-fields/IFrame.js
index e3495c8c3..93b3d779d 100644
--- a/packages/form-js-viewer/src/render/components/form-fields/IFrame.js
+++ b/packages/form-js-viewer/src/render/components/form-fields/IFrame.js
@@ -43,7 +43,7 @@ export function IFrame(props) {
   }, [ sandbox, allow ]);
 
   return <div class={ formFieldClasses(type, { disabled, readonly }) }>
-    <Label id={ domId } label={ evaluatedLabel } />
+    <Label htmlFor={ domId } label={ evaluatedLabel } />
     {
       !evaluatedUrl && <IFramePlaceholder text="No content to show." />
     }
diff --git a/packages/form-js-viewer/src/render/components/form-fields/Number.js b/packages/form-js-viewer/src/render/components/form-fields/Number.js
index 3e837ed5d..581876dab 100644
--- a/packages/form-js-viewer/src/render/components/form-fields/Number.js
+++ b/packages/form-js-viewer/src/render/components/form-fields/Number.js
@@ -27,7 +27,6 @@ export function Numberfield(props) {
   const {
     disabled,
     errors = [],
-    errorMessageId,
     domId,
     onBlur,
     onFocus,
@@ -190,9 +189,12 @@ export function Numberfield(props) {
     }
   };
 
+  const descriptionId = `${domId}-description`;
+  const errorMessageId = `${domId}-error-message`;
+
   return <div class={ formFieldClasses(type, { errors, disabled, readonly }) }>
     <Label
-      id={ domId }
+      htmlFor={ domId }
       label={ label }
       required={ required } />
     <TemplatedInputAdorner disabled={ disabled } readonly={ readonly } pre={ prefixAdorner } post={ suffixAdorner }>
@@ -215,7 +217,9 @@ export function Numberfield(props) {
           autoComplete="off"
           step={ incrementAmount }
           value={ displayValue }
-          aria-describedby={ errorMessageId } />
+          aria-describedby={ [ descriptionId, errorMessageId ].join(' ') }
+          required={ required }
+          aria-invalid={ errors.length > 0 } />
         <div class={ classNames('fjs-number-arrow-container', { 'fjs-disabled': disabled, 'fjs-readonly': readonly }) }>
           { /* we're disabling tab navigation on both buttons to imitate the native browser behavior of input[type='number'] increment arrows */ }
           <button
@@ -234,8 +238,8 @@ export function Numberfield(props) {
         </div>
       </div>
     </TemplatedInputAdorner>
-    <Description description={ description } />
-    <Errors errors={ errors } id={ errorMessageId } />
+    <Description id={ descriptionId } description={ description } />
+    <Errors id={ errorMessageId } errors={ errors } />
   </div>;
 }
 
diff --git a/packages/form-js-viewer/src/render/components/form-fields/Radio.js b/packages/form-js-viewer/src/render/components/form-fields/Radio.js
index e4f6f8dc8..3041f407f 100644
--- a/packages/form-js-viewer/src/render/components/form-fields/Radio.js
+++ b/packages/form-js-viewer/src/render/components/form-fields/Radio.js
@@ -23,7 +23,6 @@ export function Radio(props) {
   const {
     disabled,
     errors = [],
-    errorMessageId,
     domId,
     onBlur,
     onFocus,
@@ -78,6 +77,9 @@ export function Radio(props) {
     onChange: props.onChange
   });
 
+  const descriptionId = `${domId}-description`;
+  const errorMessageId = `${domId}-error-message`;
+
   return <div class={ formFieldClasses(type, { errors, disabled, readonly }) } ref={ outerDivRef }>
     <Label
       label={ label }
@@ -90,7 +92,7 @@ export function Radio(props) {
 
         return (
           <Label
-            id={ itemDomId }
+            htmlFor={ itemDomId }
             key={ index }
             label={ option.label }
             class={ classNames({ 'fjs-checked': isChecked }) }
@@ -105,13 +107,15 @@ export function Radio(props) {
               onClick={ () => onChange(option.value) }
               onBlur={ onRadioBlur }
               onFocus={ onRadioFocus }
-              aria-describedby={ errorMessageId } />
+              aria-describedby={ [ descriptionId, errorMessageId ].join(' ') }
+              required={ required }
+              aria-invalid={ errors.length > 0 } />
           </Label>
         );
       })
     }
-    <Description description={ description } />
-    <Errors errors={ errors } id={ errorMessageId } />
+    <Description id={ descriptionId } description={ description } />
+    <Errors id={ errorMessageId } errors={ errors } />
   </div>;
 }
 
diff --git a/packages/form-js-viewer/src/render/components/form-fields/Select.js b/packages/form-js-viewer/src/render/components/form-fields/Select.js
index 61864a9f9..7282aadfa 100644
--- a/packages/form-js-viewer/src/render/components/form-fields/Select.js
+++ b/packages/form-js-viewer/src/render/components/form-fields/Select.js
@@ -14,7 +14,6 @@ export function Select(props) {
   const {
     disabled,
     errors = [],
-    errorMessageId,
     domId,
     onBlur,
     onFocus,
@@ -33,6 +32,9 @@ export function Select(props) {
 
   const { required } = validate;
 
+  const descriptionId = `${domId}-description`;
+  const errorMessageId = `${domId}-error-message`;
+
   const selectProps = {
     domId,
     disabled,
@@ -43,7 +45,9 @@ export function Select(props) {
     value,
     onChange,
     readonly,
-    'aria-describedby': errorMessageId,
+    required,
+    'aria-invalid': errors.length > 0,
+    'aria-describedby': [ descriptionId, errorMessageId ].join(' '),
   };
 
   return <div
@@ -58,12 +62,12 @@ export function Select(props) {
     }
   >
     <Label
-      id={ domId }
+      htmlFor={ domId }
       label={ label }
       required={ required } />
     { searchable ? <SearchableSelect { ...selectProps } /> : <SimpleSelect { ...selectProps } /> }
-    <Description description={ description } />
-    <Errors errors={ errors } id={ errorMessageId } />
+    <Description id={ descriptionId } description={ description } />
+    <Errors id={ errorMessageId } errors={ errors } />
   </div>;
 }
 
diff --git a/packages/form-js-viewer/src/render/components/form-fields/Table.js b/packages/form-js-viewer/src/render/components/form-fields/Table.js
index 2d35b0e6a..dc1449785 100644
--- a/packages/form-js-viewer/src/render/components/form-fields/Table.js
+++ b/packages/form-js-viewer/src/render/components/form-fields/Table.js
@@ -96,7 +96,7 @@ export function Table(props) {
 
   return (
     <div class={ formFieldClasses(type) }>
-      <Label id={ prefixId(id) } label={ label } />
+      <Label htmlFor={ prefixId(id) } label={ label } />
       <div
         class={ classNames('fjs-table-middle-container', {
           'fjs-table-empty': evaluatedColumns.length === 0,
diff --git a/packages/form-js-viewer/src/render/components/form-fields/Taglist.js b/packages/form-js-viewer/src/render/components/form-fields/Taglist.js
index a8bc5f8a6..5afdb8e8e 100644
--- a/packages/form-js-viewer/src/render/components/form-fields/Taglist.js
+++ b/packages/form-js-viewer/src/render/components/form-fields/Taglist.js
@@ -28,7 +28,6 @@ export function Taglist(props) {
   const {
     disabled,
     errors = [],
-    errorMessageId,
     onFocus,
     domId,
     onBlur,
@@ -177,6 +176,9 @@ export function Taglist(props) {
 
   const shouldDisplayDropdown = useMemo(() => !disabled && loadState === LOAD_STATES.LOADED && isDropdownExpanded && !isEscapeClosed, [ disabled, isDropdownExpanded, isEscapeClosed, loadState ]);
 
+  const descriptionId = `${domId}-description`;
+  const errorMessageId = `${domId}-error-message`;
+
   return <div
     ref={ focusScopeRef }
     class={ formFieldClasses(type, { errors, disabled, readonly }) }
@@ -192,7 +194,7 @@ export function Taglist(props) {
     <Label
       label={ label }
       required={ required }
-      id={ domId } />
+      htmlFor={ domId } />
     { (!disabled && !readonly && !!values.length) && <SkipLink className="fjs-taglist-skip-link" label="Skip to search" onSkip={ onSkipToSearch } /> }
     <div class={ classNames('fjs-taglist', { 'fjs-disabled': disabled, 'fjs-readonly': readonly }) }>
       { loadState === LOAD_STATES.LOADED &&
@@ -235,7 +237,9 @@ export function Taglist(props) {
         onMouseDown={ () => setIsEscapeClose(false) }
         onFocus={ onInputFocus }
         onBlur={ onInputBlur }
-        aria-describedby={ errorMessageId } />
+        aria-describedby={ [ descriptionId, errorMessageId ].join(' ') }
+        required={ required }
+        aria-invalid={ errors.length > 0 } />
     </div>
     <div class="fjs-taglist-anchor">
       { shouldDisplayDropdown && <DropdownList
@@ -245,8 +249,8 @@ export function Taglist(props) {
         emptyListMessage={ hasOptionsLeft ? 'No results' : 'All values selected' }
         listenerElement={ inputRef.current } /> }
     </div>
-    <Description description={ description } />
-    <Errors errors={ errors } id={ errorMessageId } />
+    <Description id={ descriptionId } description={ description } />
+    <Errors id={ errorMessageId } errors={ errors } />
   </div>;
 }
 
diff --git a/packages/form-js-viewer/src/render/components/form-fields/Textarea.js b/packages/form-js-viewer/src/render/components/form-fields/Textarea.js
index 204d6215b..07e93d78d 100644
--- a/packages/form-js-viewer/src/render/components/form-fields/Textarea.js
+++ b/packages/form-js-viewer/src/render/components/form-fields/Textarea.js
@@ -15,7 +15,6 @@ export function Textarea(props) {
   const {
     disabled,
     errors = [],
-    errorMessageId,
     domId,
     onBlur,
     onFocus,
@@ -62,9 +61,12 @@ export function Textarea(props) {
     autoSizeTextarea(textareaRef.current);
   }, []);
 
+  const descriptionId = `${domId}-description`;
+  const errorMessageId = `${domId}-error-message`;
+
   return <div class={ formFieldClasses(type, { errors, disabled, readonly }) }>
     <Label
-      id={ domId }
+      htmlFor={ domId }
       label={ label }
       required={ required } />
     <textarea class="fjs-textarea"
@@ -76,9 +78,11 @@ export function Textarea(props) {
       onFocus={ onInputFocus }
       value={ value }
       ref={ textareaRef }
-      aria-describedby={ errorMessageId } />
-    <Description description={ description } />
-    <Errors errors={ errors } id={ errorMessageId } />
+      aria-describedby={ [ descriptionId, errorMessageId ].join(' ') }
+      required={ required }
+      aria-invalid={ errors.length > 0 } />
+    <Description id={ descriptionId } description={ description } />
+    <Errors id={ errorMessageId } errors={ errors } />
   </div>;
 }
 
diff --git a/packages/form-js-viewer/src/render/components/form-fields/Textfield.js b/packages/form-js-viewer/src/render/components/form-fields/Textfield.js
index 5a553ff59..143d1057b 100644
--- a/packages/form-js-viewer/src/render/components/form-fields/Textfield.js
+++ b/packages/form-js-viewer/src/render/components/form-fields/Textfield.js
@@ -14,7 +14,6 @@ export function Textfield(props) {
   const {
     disabled,
     errors = [],
-    errorMessageId,
     domId,
     onBlur,
     onFocus,
@@ -53,9 +52,12 @@ export function Textfield(props) {
     onFocus && onFocus();
   };
 
+  const descriptionId = `${domId}-description`;
+  const errorMessageId = `${domId}-error-message`;
+
   return <div class={ formFieldClasses(type, { errors, disabled, readonly }) }>
     <Label
-      id={ domId }
+      htmlFor={ domId }
       label={ label }
       required={ required } />
     <TemplatedInputAdorner disabled={ disabled } readonly={ readonly } pre={ prefixAdorner } post={ suffixAdorner }>
@@ -69,10 +71,12 @@ export function Textfield(props) {
         onFocus={ onInputFocus }
         type="text"
         value={ value }
-        aria-describedby={ errorMessageId } />
+        aria-describedby={ [ descriptionId, errorMessageId ].join(' ') }
+        required={ required }
+        aria-invalid={ errors.length > 0 } />
     </TemplatedInputAdorner>
-    <Description description={ description } />
-    <Errors errors={ errors } id={ errorMessageId } />
+    <Description id={ descriptionId } description={ description } />
+    <Errors id={ errorMessageId } errors={ errors } />
   </div>;
 }
 
diff --git a/packages/form-js-viewer/src/render/components/form-fields/parts/Datepicker.js b/packages/form-js-viewer/src/render/components/form-fields/parts/Datepicker.js
index 5f027b23a..2746a9688 100644
--- a/packages/form-js-viewer/src/render/components/form-fields/parts/Datepicker.js
+++ b/packages/form-js-viewer/src/render/components/form-fields/parts/Datepicker.js
@@ -170,7 +170,7 @@ export function Datepicker(props) {
 
   return <div class="fjs-datetime-subsection">
     <Label
-      id={ domId }
+      htmlFor={ domId }
       label={ label }
       collapseOnEmpty={ collapseLabelOnEmpty }
       required={ required } />
diff --git a/packages/form-js-viewer/src/render/components/form-fields/parts/Timepicker.js b/packages/form-js-viewer/src/render/components/form-fields/parts/Timepicker.js
index 4544b9796..22db982c6 100644
--- a/packages/form-js-viewer/src/render/components/form-fields/parts/Timepicker.js
+++ b/packages/form-js-viewer/src/render/components/form-fields/parts/Timepicker.js
@@ -151,7 +151,7 @@ export function Timepicker(props) {
 
   return <div class="fjs-datetime-subsection">
     <Label
-      id={ domId }
+      htmlFor={ domId }
       label={ label }
       collapseOnEmpty={ collapseLabelOnEmpty }
       required={ required } />