chore(docs): ARIA roles and labels for built-in fields (#9788)

* chore(docs): add information about ARIA for built-in fields

* chore: tweak dropdown wording

* chore: add accessibility information to Anatomy of a Field

* chore(format): line length

* chore: update section on focusability

* chore: fix phrasing

Author: rachel-fenichel

packages/docs/docs/guides/create-custom-blocks/fields/anatomy-of-a-field.mdx

@@ -27,7 +27,8 @@ and may optionally be part of the [on-block display](#on-block-display).
 
 In general, editable fields allow the user to make changes to the code, while
 non-editable fields display information to the user about the block.
-Editable fields may show a rich editor when clicked.
+Editable fields may show a rich editor when clicked or activated with the
+keyboard.
 
 Editable fields include:
 
@@ -43,6 +44,25 @@ Non-editable fields include:
 - [Label Serializable](/guides/create-custom-blocks/fields/built-in-fields/label-serializable)
 - [Image](/guides/create-custom-blocks/fields/built-in-fields/image)
 
+## Focusable vs non-focusable fields
+
+Focusable fields can be navigated to and acted on with the keyboard. A field is
+focusable if it is visible and clickable or currently editable. Some
+non-editable fields are focusable, such as images with click handlers. If a
+field is focusable it must specify a single focusable element to be visited when
+traversing blocks. Blockly ensures that the focusable element is in the
+accessibility tree in an appropriate location. 
+
+Non-focusable fields such as labels cannot be navigated to with the keyboard.
+
+## ARIA label
+
+All fields have an ARIA label, which is a string containing human-readable
+information about the field's type and value. Blockly exposes the ARIA label to
+screen readers by attaching it to the field's focusable element or including it
+in the parent block's ARIA label. All built-in fields compute their ARIA labels
+automatically.
+
 ## Serialization
 
 A serializable field's value gets encoded in the save format (JSON or XML). All
@@ -93,6 +113,19 @@ complexity.
 | Angle      | Contains a background rect, text element, and a degree symbol.                                        |
 | Turtle     | Contains a background rect, text element, and many SVG elements used to construct the turtle graphic. |
 
+Focusable fields must designate a focusable DOM element with a unique ID for 
+their on-block display. Blockly places this element in the accessibility tree
+and moves focus to it through keyboard navigation. When the field is focused its
+focusable DOM element will have the `blocklyActiveFocus` or
+`blocklyPassiveFocus` CSS class added. Blockly's built-in fields show focus
+with a yellow outline.
+
+The focusable element must have the correct ARIA role. Most focusable fields
+have an ARIA role of `button` to indicate that they can be clicked or activated
+with the keyboard. An exception is the checkbox field, which has an ARIA role
+of `checkbox`. Non-focusable fields should be removed from the accessibility
+tree by applying `aria-hidden` to the root of the field.
+
 ## Editor display
 
 When a user clicks on an editable field, the field may display an
@@ -107,6 +140,10 @@ complexity.
 | Number input | Text editor overlaid above the on-block display. Users can type; the editor may change color to indicate bad values. |
 | Angle picker | The angle picker has both a text editor for typing numbers and a draggable editor for selecting angles visually.     |
 
+Blockly automatically moves focus into the field editor when activated. The
+developer is responsible for the accessibility of their field editor, including
+setting appropriate [ARIA role and properties](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques).
+
 ## Other display modes
 
 Collapsed mode: the user collapses the block.The block displays a text representation
@@ -115,7 +152,4 @@ fields.
 
 ![Turtle field block collapsing](/images/fields/yertle_collapsing.gif)
 
-Accessibility mode: users may be using a screenreader or similar technology to
-interact with Blockly. The text of the field may be read out to the user.
-
 [field-generator]: /guides/create-custom-blocks/code-generation/block-code#get-field-values

packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/checkbox.mdx

@@ -9,7 +9,7 @@ import TabItem from '@theme/TabItem';
 
 # Checkbox fields
 
-A checkbox field stores a string as its value, and a string as its text. Its
+A checkbox field stores a string as its value and a string as its text. Its
 value is either `'TRUE'` or `'FALSE'`, and its text is either `'true'` or
 `'false'`.
 
@@ -99,6 +99,13 @@ The checkbox constructor takes in an optional value and an optional
   when diffing workspaces.
   </TabItem>
 </Tabs>
+
+## Accessibility
+
+A checkbox field's on-block display has the ARIA role `checkbox`. There is 
+no editor: the on-block display simply toggles when clicked. Its ARIA value 
+is either `'checked'` or `'unchecked'`. The ARIA label is `checkbox: <ARIA value>`.
+
 ## Customization
 
 ### Checkmark character

packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/dropdown.mdx

@@ -34,10 +34,12 @@ collapsed.](/images/fields/dropdown/collapsed.png)
 
 The dropdown constructor takes in a menu generator and an optional
 [validator](#creating-a-dropdown-validator). The menu generator is either an
-array of options (where each option contains a human-readable part and a
-language-neutral string) or a function that generates an array of options. The
-human-readable part of each option can be a string, an image, or an HTML element
-and the array can contain a mixture of options of different types.
+array of options or a function that generates an array of options. A dropdown 
+can contain a mixture of options of different types. Each option
+contains:
+- A human-readable part which may be a string, image, or HTML element
+- A language-neutral string
+- An optional ARIA label
 
 ### Simple text dropdowns
 
@@ -402,6 +404,25 @@ text should be a valid language-neutral option key.
 </TabItem>
 </Tabs>
 
+## Accessibility
+
+A dropdown field's ARIA label is `dropdown: <ARIA value>`.
+
+The ARIA value is computed based on the type of the selected option. 
+- Simple text dropdowns use the human-readable string directly.
+- Image dropdowns use the `ariaLabel` of the selected image or fall back to the
+alt text for the selected image.
+- HTML dropdowns use the computed `aria-label` of the `HTMLElement`. You are
+responsible for making sure that your element either uses appropriate
+[semantic HTML](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Accessibility/HTML) 
+or sets its [ARIA role and properties](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques) appropriately.
+- Providing an ARIA value in the option definition overrides the automatic 
+label computation. 
+
+A dropdown field’s on-block display has the ARIA role `button`. Activating the
+field opens a dropdown menu with the role `listbox`. If you use an HTML dropdown
+you are responsible for ensuring that the contents are accessible.
+
 ## Customization
 
 ### Dropdown arrow

packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/image.mdx

@@ -9,9 +9,10 @@ import TabItem from '@theme/TabItem';
 
 # Image fields
 
-An image field stores a string as its value, and a string as its text. Its
+An image field stores a string as its value and a string as its text. Its
 value is the src of the image, while its text is an alt string
-describing/representing the image.
+describing/representing the image. The alt text is also displayed when the
+parent block is collapsed.
 
 #### Image field
 
@@ -67,14 +68,24 @@ The image constructor takes in:
 | `src`         | A string that points to a [raster image](https://developer.mozilla.org/en-US/docs/Glossary/raster_image) file.                                                                                  |
 | `width`       | Must cast to a non-zero number.                                                                                                                                                                 |
 | `height`      | Must cast to a non-zero number.                                                                                                                                                                 |
-| `opt_alt`     | (Optional) A string that accurately describes/represents the image. This is used instead of the image when the block is collapsed. If it is `null` or `undefined` an empty string will be used. |
+| `opt_alt`     | (Optional) A string that accurately describes/represents the image. If it is `null` or `undefined` an empty string will be used. |
 | `opt_onClick` | (Optional) A function to call when the field is clicked.                                                                                                                                        |
 | `opt_flipRtl` | (Optional) A boolean. If `true`, the image is flipped across the vertical axis when in right-to-left mode. Defaults to `false`. Useful for "turn left" and "turn right" icons.                  |
 
 ## Serialization
 
 Image fields are not serializable.
 
+## Accessibility
+An image field's  ARIA label is `image: <alt text>`. The alt text is also
+displayed when the parent block is collapsed.
+
+Clickable images have an ARIA role of `button`. Image fields that do not have
+click handlers have an ARIA role of `none`.
+
+Follow [AFB guidelines](https://afb.org/digital-inclusion/accessibility-resources/writing-effective-image-descriptions)
+for writing good alt text. Return `null` or `undefined` to indicate a purely decorative image.
+
 ## Click handler
 
 :::note

packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/label-serializable.mdx

@@ -86,6 +86,14 @@ class string. Both default to an empty string.
   label field, and the node's inner text is the value to apply to the field.
   </TabItem>
 </Tabs>
+
+
+## Accessibility
+
+Serializable label fields cannot be focused directly with keyboard navigation.
+The on-block display has the ARIA role `generic`. There is no editor display.
+The label's text is used to construct the parent block's ARIA label.
+
 ## Validators
 
 Serializable label fields do not support validators, because they are not

packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/label.mdx

@@ -89,6 +89,12 @@ If you would like your label to be serialized, because it is being changed
 programmatically, see the [Serializable Label](/guides/create-custom-blocks/fields/built-in-fields/label-serializable)
 field.
 
+## Accessibility
+
+Label fields cannot be focused directly with keyboard navigation. The on-block
+display has the ARIA role `generic`. There is no editor display. The label's
+text is used to construct the parent block's ARIA label.
+
 ## Validators
 
 Label fields do not support validators, because they are not editable.

packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/number.mdx

@@ -102,6 +102,25 @@ The `value` should cast to a number. If it does not 0 will be used.
   inner text value follows the same rules as the constructor value.
   </TabItem>
 </Tabs>
+
+## Accessibility
+
+A number field's ARIA label is `number: <ARIA value>`. A number fields's 
+on-block display has the ARIA role `button`. Activating the field overlays and
+focuses an HTML text input.
+
+:::note
+The HTML input type is `text` rather than `number` because the semantics of
+an HTML `number` input do not match Blockly's behaviour. Blockly number fields
+provide feedback for invalid values and handle the value `Infinity`.
+[According to MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/number#accessibility)
+“the implicit role for the `<input type="number">` element is `spinbutton`. 
+[...] With `<input type="number">`, there is a risk of users accidentally 
+incrementing a number when they're trying to do something else. Additionally, 
+if users try to enter something that's not a number, there's no explicit 
+feedback about what they're doing wrong.”
+:::
+
 ## Constraints
 
 Constraints can be set in the field definition, or by using the
@@ -127,9 +146,7 @@ used to make the field only accept multiples of .01, 10, 42, etc.
 
 ### Positive numbers
 
-To force your field to only accept positive numbers, set the `min` value to
-
-1.
+To force your field to only accept positive numbers, set the `min` value to 1.
 
 ### Integers
 

packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/text-input.mdx

@@ -97,6 +97,13 @@ The JSON definition also allows you to set the [spellcheck](#spellcheck) option.
   text value follows the same rules as the constructor value.
   </TabItem>
 </Tabs>
+
+## Accessibility
+
+A text input field's ARIA label is `text: <ARIA value>`. The on-block display
+has the ARIA role `button`. Activating the field overlays and focuses an HTML
+text input.
+
 ## Customization
 
 ### Spellcheck

packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/variable.mdx

@@ -169,6 +169,14 @@ types, and an optional default type.
       follows the same rules as the constructor's variable name parameter.
   </TabItem>
 </Tabs>
+
+## Accessibility
+
+A variable field's ARIA label is `variable: '<ARIA value>'`, where the ARIA 
+value is the name of the variable. A variable field's on-block display has the 
+ARIA role `button`. Activating the field opens a dropdown menu with the role 
+`listbox`.
+
 ## Creating a variable validator
 
 :::note