Skip to content

A platform for community discussion. Free, open, simple.

A11Y: make sure formkit descriptions are included in aria-describedby (#40082)

Krise9c9664b8230
diff --git a/frontend/discourse/app/form-kit/components/fk/control/calendar.gjs b/frontend/discourse/app/form-kit/components/fk/control/calendar.gjs
index 05b795c9dda..2695c2d06ff 100644
--- a/frontend/discourse/app/form-kit/components/fk/control/calendar.gjs
+++ b/frontend/discourse/app/form-kit/components/fk/control/calendar.gjs
@@ -80,7 +80,7 @@ export default class FKControlCalendar extends FKBaseControl {
id={{@field.id}}
name={{@field.name}}
aria-invalid={{if @field.error "true"}}
- aria-describedby={{if @field.error @field.errorId}}
+ aria-describedby={{@field.describedBy}}
class="form-kit__control-calendar"
/>
<div id={{this.containerId}} class="date-picker-container"></div>
@@ -94,7 +94,7 @@ export default class FKControlCalendar extends FKBaseControl {
value={{this.date}}
id={{@field.id}}
name={{@field.name}}
- aria-describedby={{if @field.error @field.errorId}}
+ aria-describedby={{@field.describedBy}}
{{on "change" (withEventValue this.setDate)}}
/>
{{/if}}
diff --git a/frontend/discourse/app/form-kit/components/fk/control/checkbox.gjs b/frontend/discourse/app/form-kit/components/fk/control/checkbox.gjs
index 8dacc215282..237647318c3 100644
--- a/frontend/discourse/app/form-kit/components/fk/control/checkbox.gjs
+++ b/frontend/discourse/app/form-kit/components/fk/control/checkbox.gjs
@@ -27,7 +27,7 @@ export default class FKControlCheckbox extends FKBaseControl {
id={{@field.id}}
name={{@field.name}}
aria-invalid={{if @field.error "true"}}
- aria-describedby={{if @field.error @field.errorId}}
+ aria-describedby={{@field.describedBy}}
...attributes
{{on "change" this.handleInput}}
/>
diff --git a/frontend/discourse/app/form-kit/components/fk/control/code.gjs b/frontend/discourse/app/form-kit/components/fk/control/code.gjs
index db5b7a4560a..f74b21f1874 100644
--- a/frontend/discourse/app/form-kit/components/fk/control/code.gjs
+++ b/frontend/discourse/app/form-kit/components/fk/control/code.gjs
@@ -34,7 +34,7 @@ export default class FKControlCode extends FKBaseControl {
id={{@field.id}}
name={{@field.name}}
aria-invalid={{if @field.error "true"}}
- aria-describedby={{if @field.error @field.errorId}}
+ aria-describedby={{@field.describedBy}}
...attributes
/>
</template>
diff --git a/frontend/discourse/app/form-kit/components/fk/control/color.gjs b/frontend/discourse/app/form-kit/components/fk/control/color.gjs
index 227105e9efe..3b0420b0891 100644
--- a/frontend/discourse/app/form-kit/components/fk/control/color.gjs
+++ b/frontend/discourse/app/form-kit/components/fk/control/color.gjs
@@ -190,7 +190,7 @@ export default class FKControlColor extends FKBaseControl {
id={{@field.id}}
name={{@field.name}}
aria-invalid={{if @field.error "true"}}
- aria-describedby={{if @field.error @field.errorId}}
+ aria-describedby={{@field.describedBy}}
{{on "input" this.handleTextInput}}
{{on "blur" this.handleBlur}}
{{on "paste" this.handlePaste}}
diff --git a/frontend/discourse/app/form-kit/components/fk/control/input.gjs b/frontend/discourse/app/form-kit/components/fk/control/input.gjs
index 4f44c4dae74..9cbe49d9d33 100644
--- a/frontend/discourse/app/form-kit/components/fk/control/input.gjs
+++ b/frontend/discourse/app/form-kit/components/fk/control/input.gjs
@@ -108,7 +108,7 @@ export default class FKControlInput extends FKBaseControl {
id={{@field.id}}
name={{@field.name}}
aria-invalid={{if @field.error "true"}}
- aria-describedby={{if @field.error @field.errorId}}
+ aria-describedby={{@field.describedBy}}
placeholder={{@field.placeholder}}
...attributes
{{on "focus" this.handleFocus}}
diff --git a/frontend/discourse/app/form-kit/components/fk/control/password.gjs b/frontend/discourse/app/form-kit/components/fk/control/password.gjs
index 6c151243f8c..f8a260ebaae 100644
--- a/frontend/discourse/app/form-kit/components/fk/control/password.gjs
+++ b/frontend/discourse/app/form-kit/components/fk/control/password.gjs
@@ -65,7 +65,7 @@ export default class FKControlPassword extends FKBaseControl {
id={{@field.id}}
name={{@field.name}}
aria-invalid={{if @field.error "true"}}
- aria-describedby={{if @field.error @field.errorId}}
+ aria-describedby={{@field.describedBy}}
...attributes
{{on "input" this.handleInput}}
{{this.focusState}}
diff --git a/frontend/discourse/app/form-kit/components/fk/control/question.gjs b/frontend/discourse/app/form-kit/components/fk/control/question.gjs
index da0e861d292..d126d47299a 100644
--- a/frontend/discourse/app/form-kit/components/fk/control/question.gjs
+++ b/frontend/discourse/app/form-kit/components/fk/control/question.gjs
@@ -25,7 +25,7 @@ export default class FKControlQuestion extends FKBaseControl {
checked={{eq @field.value true}}
class="form-kit__control-radio"
disabled={{@field.disabled}}
- aria-describedby={{if @field.error @field.errorId}}
+ aria-describedby={{@field.describedBy}}
...attributes
id={{uuid}}
{{on "change" this.handleInput}}
@@ -48,7 +48,7 @@ export default class FKControlQuestion extends FKBaseControl {
checked={{eq @field.value false}}
class="form-kit__control-radio"
disabled={{@field.disabled}}
- aria-describedby={{if @field.error @field.errorId}}
+ aria-describedby={{@field.describedBy}}
...attributes
id={{uuid}}
{{on "change" this.handleInput}}
diff --git a/frontend/discourse/app/form-kit/components/fk/control/radio-group.gjs b/frontend/discourse/app/form-kit/components/fk/control/radio-group.gjs
index 11b287725a4..6ee652eedee 100644
--- a/frontend/discourse/app/form-kit/components/fk/control/radio-group.gjs
+++ b/frontend/discourse/app/form-kit/components/fk/control/radio-group.gjs
@@ -14,7 +14,7 @@ export default class FKControlRadioGroup extends FKBaseControl {
id={{@field.id}}
name={{@field.name}}
aria-invalid={{if @field.error "true"}}
- aria-describedby={{if @field.error @field.errorId}}
+ aria-describedby={{@field.describedBy}}
...attributes
>
{{yield
diff --git a/frontend/discourse/app/form-kit/components/fk/control/select.gjs b/frontend/discourse/app/form-kit/components/fk/control/select.gjs
index 1d470528a04..23c6eb85b45 100644
--- a/frontend/discourse/app/form-kit/components/fk/control/select.gjs
+++ b/frontend/discourse/app/form-kit/components/fk/control/select.gjs
@@ -37,7 +37,7 @@ export default class FKControlSelect extends FKBaseControl {
id={{@field.id}}
name={{@field.name}}
aria-invalid={{if @field.error "true"}}
- aria-describedby={{if @field.error @field.errorId}}
+ aria-describedby={{@field.describedBy}}
...attributes
>
{{yield (hash Option=(component SelectOption [email protected]))}}
diff --git a/frontend/discourse/app/form-kit/components/fk/control/textarea.gjs b/frontend/discourse/app/form-kit/components/fk/control/textarea.gjs
index 4654fd55387..5841e5f3ea1 100644
--- a/frontend/discourse/app/form-kit/components/fk/control/textarea.gjs
+++ b/frontend/discourse/app/form-kit/components/fk/control/textarea.gjs
@@ -56,7 +56,7 @@ export default class FKControlTextarea extends FKBaseControl {
id={{@field.id}}
name={{@field.name}}
aria-invalid={{if @field.error "true"}}
- aria-describedby={{if @field.error @field.errorId}}
+ aria-describedby={{@field.describedBy}}
class="form-kit__control-textarea"
...attributes
/>
diff --git a/frontend/discourse/app/form-kit/components/fk/field-data.gjs b/frontend/discourse/app/form-kit/components/fk/field-data.gjs
index 2d59ec00a98..963157a18c5 100644
--- a/frontend/discourse/app/form-kit/components/fk/field-data.gjs
+++ b/frontend/discourse/app/form-kit/components/fk/field-data.gjs
@@ -180,6 +180,32 @@ export default class FKFieldData extends Component {
return (this.args.errors ?? {})[this.name];
}
+ get descriptionId() {
+ return `${this.id}-description`;
+ }
+
+ get helpTextId() {
+ return `${this.id}-help-text`;
+ }
+
+ get describedBy() {
+ const ids = [];
+
+ if (this.description) {
+ ids.push(this.descriptionId);
+ }
+
+ if (this.helpText) {
+ ids.push(this.helpTextId);
+ }
+
+ if (this.error) {
+ ids.push(this.errorId);
+ }
+
+ return ids.length ? ids.join(" ") : undefined;
+ }
+
/**
* Indicates whether to show the field's title.
* Defaults to `true`.
diff --git a/frontend/discourse/app/form-kit/components/fk/field.gjs b/frontend/discourse/app/form-kit/components/fk/field.gjs
index ef164ce0153..6d853f3e8fe 100644
--- a/frontend/discourse/app/form-kit/components/fk/field.gjs
+++ b/frontend/discourse/app/form-kit/components/fk/field.gjs
@@ -159,6 +159,7 @@ export default class FKField extends Component {
{{#if field.description}}
<FKText
+ id={{field.descriptionId}}
class={{dConcatClass
"form-kit__container-description"
(if field.labelFormat (concat "--" field.labelFormat))
@@ -175,6 +176,7 @@ export default class FKField extends Component {
{{#if field.helpText}}
<FKText
+ id={{field.helpTextId}}
class="form-kit__container-help-text"
>{{field.helpText}}</FKText>
{{/if}}
diff --git a/frontend/discourse/tests/integration/components/form-kit/field-test.gjs b/frontend/discourse/tests/integration/components/form-kit/field-test.gjs
index 7b55e355b31..add2fa59a8d 100644
--- a/frontend/discourse/tests/integration/components/form-kit/field-test.gjs
+++ b/frontend/discourse/tests/integration/components/form-kit/field-test.gjs
@@ -91,6 +91,49 @@ module("Integration | Component | FormKit | Field", function (hooks) {
assert.form().field("foo").hasDescription("foo foo");
});
+ test("aria-describedby links description, help text, and error", async function (assert) {
+ await render(
+ <template>
+ <Form as |form|>
+ <form.Field
+ @type="input"
+ @name="foo"
+ @title="Foo"
+ @description="A description"
+ @helpText="A help text"
+ @validation="required"
+ as |field|
+ >
+ <field.Control />
+ </form.Field>
+ </Form>
+ </template>
+ );
+
+ const input = document.querySelector("[name='foo']");
+ const descriptionId = document.querySelector(
+ ".form-kit__container-description"
+ ).id;
+ const helpTextId = document.querySelector(
+ ".form-kit__container-help-text"
+ ).id;
+
+ assert.strictEqual(
+ input.getAttribute("aria-describedby"),
+ `${descriptionId} ${helpTextId}`,
+ "joins description and help text ids when no error"
+ );
+
+ await formKit().submit();
+
+ const errorId = document.querySelector(".form-kit__errors").id;
+ assert.strictEqual(
+ input.getAttribute("aria-describedby"),
+ `${descriptionId} ${helpTextId} ${errorId}`,
+ "appends the error id when a validation error is present"
+ );
+ });
+
test("invalid @name", async function (assert) {
setupOnerror((error) => {
assert.deepEqual(error.message, "@name can't include `.` or `-`.");
@@ -451,3 +494,100 @@ module("Integration | Component | FormKit | Field", function (hooks) {
);
});
});
+
+module(
+ "Integration | Component | FormKit | Field | aria-describedby wiring",
+ function (hooks) {
+ setupRenderingTest(hooks);
+
+ const SIMPLE_CONTROLS = [
+ "input",
+ "input-number",
+ "password",
+ "textarea",
+ "checkbox",
+ "color",
+ "calendar",
+ "question",
+ ];
+
+ SIMPLE_CONTROLS.forEach((type) => {
+ test(`@type="${type}" wires aria-describedby to @description`, async function (assert) {
+ await render(
+ <template>
+ <Form as |form|>
+ <form.Field
+ @type={{type}}
+ @name="foo"
+ @title="Foo"
+ @description="A description"
+ as |field|
+ >
+ <field.Control />
+ </form.Field>
+ </Form>
+ </template>
+ );
+
+ const descriptionId = document.querySelector(
+ ".form-kit__container-description"
+ ).id;
+ assert
+ .dom(`[aria-describedby~="${descriptionId}"]`)
+ .exists(
+ `${type} renders a focusable element pointing at the description id`
+ );
+ });
+ });
+
+ test('@type="select" wires aria-describedby to @description', async function (assert) {
+ await render(
+ <template>
+ <Form as |form|>
+ <form.Field
+ @type="select"
+ @name="foo"
+ @title="Foo"
+ @description="A description"
+ as |field|
+ >
+ <field.Control as |select|>
+ <select.Option @value="a">A</select.Option>
+ </field.Control>
+ </form.Field>
+ </Form>
+ </template>
+ );
+
+ const descriptionId = document.querySelector(
+ ".form-kit__container-description"
+ ).id;
+ assert.dom(`[aria-describedby~="${descriptionId}"]`).exists();
+ });
+
+ test('@type="radio-group" wires aria-describedby to @description', async function (assert) {
+ await render(
+ <template>
+ <Form as |form|>
+ <form.Field
+ @type="radio-group"
+ @name="foo"
+ @title="Foo"
+ @description="A description"
+ as |field|
+ >
+ <field.Control as |RadioGroup|>
+ <RadioGroup.Radio @value="a">A</RadioGroup.Radio>
+ </field.Control>
+ </form.Field>
+ </Form>
+ </template>
+ );
+
+ const descriptionId = document.querySelector(
+ ".form-kit__container-description"
+ ).id;
+ assert.dom(`[aria-describedby~="${descriptionId}"]`).exists();
+ });
+ }
+);