Screen readers do not read radio/checkbox group labels correctly

[buttle]

Hi!

First of all, thank you! formBuilder works great! :)

We've received an issue from one of our users that we think is important enough for you to know about.

Resumed here:

Current formBuilder render output

<div class="formbuilder-radio-group form-group field-radio-group-1631271361249">
  <label for="radio-group-1631271361249">
    Rate the quality of content
  </label>
  <div class="radio-group">
    <div class="formbuilder-radio-inline">
      <input name="radio-group-1631271361249" id="radio-group-1631271361249-0" value="1" type="radio">
      <label for="radio-group-1631271361249-0">1</label>
    </div>
    <div class="formbuilder-radio-inline">
      <input name="radio-group-1631271361249" id="radio-group-1631271361249-1" value="2" type="radio">
      <label for="radio-group-1631271361249-1">2</label>
    </div>
    ...
  </div>
</div>

Our user observes that: The use of the for the overarching legend is incorrect, and does NOT result in screen readers announcing/associating that with the group. As a result, navigating with a screen reader, if you TAB to a radio button there you just hear its label (e.g. "1") without any further context.

This would be solve by explicitly define the roles/relationships using ARIA

<div role="group" aria-labelledby="radio-group-1631271361249-legend" class="...">
  <label id="radio-group-1631271361249-legend">
    Rate the quality of content
  </label>
  ...
</div>

I looked through the docs and READMEs in the code and I can't see a way for me to add aria-labelledby to the outer div

If you find time, could you look into this please?

Thanks again!

[lucasnetau]

Thank you for the detailed report. I'll take a look.

[lucasnetau]

This can possibly be solved with a new template in Layout which can be used by controls like radio-group and checkbox-group. I need to read up a bit more about the semantics of the aria labelled by and described by. POC below:

diff --git a/src/js/control/select.js b/src/js/control/select.js
index 450f15d..373b94a 100644
--- a/src/js/control/select.js
+++ b/src/js/control/select.js
@@ -141,12 +141,16 @@ export default class controlSelect extends control {
     }
 
     // build & return the DOM elements
-    if (type == 'select') {
+    if (type === 'select') {
       this.dom = this.markup(optionType, options, trimObj(data, true))
+      return this.dom
     } else {
       this.dom = this.markup('div', options, { className: type })
+      return {
+        field: this.dom,
+        layout: 'group'
+      }
     }
-    return this.dom
   }
 
   /**
diff --git a/src/js/layout.js b/src/js/layout.js
index 93baf18..709a99d 100644
--- a/src/js/layout.js
+++ b/src/js/layout.js
@@ -68,6 +68,29 @@ export default class layout {
           className: processClassName(data, field),
         })
       },
+      group: (field, label, help, data) => {
+        const elements = [label]
+        label.removeAttribute('for')
+        // append help into the label
+        if (help) {
+          if (help.tagName === 'SPAN') {
+            label.appendChild(help)
+          } else {
+            elements.push(help)
+          }
+        }
+        elements.push(field)
+
+        const group = this.markup('div', elements, {
+          className: processClassName(data, field),
+          role: 'group',
+          'aria-labelledby': label.id,
+        })
+        if (help) {
+          group.setAttribute('aria-describedby', help.id)
+        }
+        return group
+      },
       noLabel: (field, label, help, data) => {
         return this.markup('div', field, {
           className: processClassName(data, field),
@@ -175,6 +198,7 @@ export default class layout {
 
     // generate a label element
     return this.markup('label', labelContents, {
+      id: `formbuilder-${this.data.id}-label`,
       for: this.data.id,
       className: `formbuilder-${this.data.type}-label`,
     })
@@ -196,6 +220,7 @@ export default class layout {
 
     // generate the default help element
     return this.markup('span', '?', {
+      id: `formbuilder-${this.data.id}-help`,
       className: 'tooltip-element',
       tooltip: this.data.description,
     })

produced:

<div class="formbuilder-radio-group form-group field-radio-group-1761645733706-0" role="group" aria-labelledby="formbuilder-radio-group-1761645733706-0-label" aria-describedby="formbuilder-radio-group-1761645733706-0-help">
  <label id="formbuilder-radio-group-1761645733706-0-label" class="formbuilder-radio-group-label">Radio Group
    <span id="formbuilder-radio-group-1761645733706-0-help" class="tooltip-element" tooltip="Radio group">?</span>
  </label>
  <div class="radio-group">
    <div class="formbuilder-radio">
      <input name="radio-group-1761645733706-0" id="radio-group-1761645733706-0-0" value="option-1"  type="radio">
      <label for="radio-group-1761645733706-0-0">Option 1</label>
    </div>
...

[lucasnetau]

@kevinchappell thoughts on this one? Having a special "group" template means we reduce the risk of any BC breaks. Still working on the best way to split label and help as they are passed to two different aria-* attributes and I believe need to be semantically two seperate elements (help not contained within label)

[kevinchappell]

@lucasnetau i see what you mean about needing a group template. That's probably safest to prevent breaking existing forms if they need to be separated.

[lucasnetau]

I'm also going to explore using fieldset/legend, however I have been using those for my Section plugin so need to see how nesting works.

The tooltip is technically incorrect for describedby since it's text content is ?, the actual text is stored in tooltip attribute. We would need to also render a screen reader hidden div for describedby