docs: update docs for new ids

Author: ynotdraw

docs/components/field/demo/base-demo.md

@@ -1,14 +1,17 @@
 ```hbs template
 <Form::Field as |field|>
-  <field.Label>First name</field.Label>
-  <field.Hint>What should we call you?</field.Hint>
+  <field.Label for={{field.id}}>Label</field.Label>
+  <field.Hint id={{field.hintId}}>Extra information about the field</field.Hint>
   <field.Control>
     <input
-      class='border bg-basement text-titles-and-attributes'
+      class='border bg-basement text-titles-and-attributes p-1 rounded-sm'
+      id={{field.id}}
+      aria-invalid='true'
+      aria-describedby='{{field.hintId}} {{field.errorId}}'
       ...attributes
     />
   </field.Control>
-  <field.Error>error</field.Error>
+  <field.Error id={{field.errorId}}>Error message</field.Error>
 </Form::Field>
 ```
 

docs/components/field/index.md

@@ -1,57 +1,74 @@
 # Field
 
-Field is a component to aid in creating form components. It provides a label, hint sections for things like help text, a control block, and an error section for rendering errors. It allows you to provide your own custom controls with a consistent form-element shell.
+Field is a component to aid in creating form components. It provides a label, hint sections for things like help text, a control block, and an error section for rendering errors. It allows users to provide custom controls with a consistent form-element shell and is not opinionated on what underlying control element is used.
 
-## Yielded Components
+## Yielded Items
 
+- `id`: A unique ID to provide to the control element `id` attribute and the Label component `for` attribute.
+- `hintId`: A unique ID to provide to the control element `aria-describedby` attribute and the Hint component `id` attribute.
+- `errorId`: A unique ID to provide to the control element `aria-describedby` or `aria-errormessage` attribute and the Error component `id` attribute.
 - `Label`: Renders a `<label>` element. Form element label text is normally rendered here.
 - `Hint`: Renders a `<div>` element. Help text or supplemental information is normally rendered here.
-- `Control`: Renders a control of your choosing, for example, you can provide `<input>`, `<textarea>`, etc.
+- `Control`: A control block where a form element is rendered, for example, an `<input>`, `<textarea>`, etc.
 - `Error`: Renders a `<div>` element. Error information is normally rendered here.
 
+## Accessibility
+
+The Field component does not handle accessibility automatically for the label, hint, and error sections of the component; however, it does provide identifiers to assist here. Each code example on this page also shows how to take advantage of these IDs.
+
+- [for](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/for)
+- [aria-describedby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-describedby)
+- [aria-errormessage](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-errormessage)
+- [aria-invalid](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid)
+
 ## Optionally Rendering Components
 
-The yielded components from Field can be optionally rendered by using the `{{if}}` helper. For example, control when helper text or errors may be displayed.
+The yielded components from Field can be optionally rendered by using the `{{#if}}` helper. The below example optionally renders the Hint and Error based on component arguments.
 
 ```hbs
 <Form::Field as |field|>
-  <field.Label>{{@label}}</field.Label>
+  <field.Label for={{field.id}}>{{@label}}</field.Label>
 
   {{#if @helperText}}
-    <field.Hint>{{@helperText}}</field.Hint>
+    <field.Hint id={{field.hintId}}>{{@helperText}}</field.Hint>
   {{/if}}
 
   <field.Control>
-    <input class='border-critical bg-blue' ...attributes />
+    <input id={{field.id}} aria-describedby={{field.hintId}} aria-invalid={{if @error "true"}} aria-errormessage={{if @error field.errorId}}class='border-critical bg-blue' ...attributes />
   </field.Control>
 
   {{#if @error}}
-    <field.Error>{{@error}}</field.Error>
+    <field.Error id={{field.errorId}}>{{@error}}</field.Error>
   {{/if}}
 </Form::Field>
 ```
 
 ### Attributes and Modifiers
 
-We have `...attributes` added to each sub component of the Field, so HTML attributes and Ember modifiers can be added.
+Attributes are spread to each sub component of the Field via `...attributes`, so HTML attributes and Ember modifiers can be added.
 
 ```hbs
 <Form::Field as |field|>
-  <field.Label class='mt-3' {{on 'hover' this.onLabelHover}}>First name</field.Label>
+  <field.Label
+    for={{field.id}}
+    class='mt-3'
+    data-test-label
+    {{on 'hover' this.onLabelHover}}
+  >First name</field.Label>
   {{! other components below ...}}
 </Form::Field>
 ```
 
 ### Ordering of Components
 
-Ordering of the elements can be changed by adjusting the children order. For example, if you'd prefer putting help text below the control:
+Ordering of the elements can be changed by adjusting the order of the children. For example, if it is preferred to put the hint block underneath the control.
 
 ```hbs
 <Form::Field as |field|>
-  <field.Label>First name</field.Label>
+  <field.Label for={{field.id}}>First name</field.Label>
   <field.Control>
-    <input ...attributes />
+    <input id={{field.id}} aria-describedby={{field.hintId}} ...attributes />
   </field.Control>
-  <field.Hint>Hint text below the input</field.Hint>
+  <field.Hint id={{field.hintId}}>Hint text below the input</field.Hint>
 </Form::Field>
 ```