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.
bpmn-io · Feb 20, 2024 · c3725a6 · c3725a6
1 parent 9384369
commit c3725a6
Show file tree

Hide file tree

Showing 16 changed files with 87 additions and 54 deletions.
diff --git a/packages/form-js-viewer/src/render/components/Description.js b/packages/form-js-viewer/src/render/components/Description.js
@@ -2,13 +2,13 @@ import { useSingleLineTemplateEvaluation } from '../hooks';
 
 
 export function Description(props) {
-  const { description } = props;
+  const { description, id } = props;
 
   const evaluatedDescription = useSingleLineTemplateEvaluation(description || '', { debug: true });
 
   if (!evaluatedDescription) {
     return null;
   }
 
-  return <div class="fjs-form-field-description">{ evaluatedDescription }</div>;
+  return <div id={ id } class="fjs-form-field-description">{ evaluatedDescription }</div>;
 }
diff --git a/packages/form-js-viewer/src/render/components/FormField.js b/packages/form-js-viewer/src/render/components/FormField.js
@@ -130,7 +130,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) }>
@@ -139,7 +138,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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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>;
 }