diff --git a/packages/docs/docs/guides/create-custom-blocks/fields/anatomy-of-a-field.mdx b/packages/docs/docs/guides/create-custom-blocks/fields/anatomy-of-a-field.mdx index 31e8b580f..3f60822b9 100644 --- a/packages/docs/docs/guides/create-custom-blocks/fields/anatomy-of-a-field.mdx +++ b/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 diff --git a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/checkbox.mdx b/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/checkbox.mdx index 49e5c749b..be488a6ec 100644 --- a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/checkbox.mdx +++ b/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. + +## 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: `. + ## Customization ### Checkmark character diff --git a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/dropdown.mdx b/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/dropdown.mdx index a28dbc1af..98f4473da 100644 --- a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/dropdown.mdx +++ b/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. +## Accessibility + +A dropdown field's ARIA label is `dropdown: `. + +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 diff --git a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/image.mdx b/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/image.mdx index 2edc5da93..579ba0203 100644 --- a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/image.mdx +++ b/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,7 +68,7 @@ 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. | @@ -75,6 +76,16 @@ The image constructor takes in: Image fields are not serializable. +## Accessibility +An image field's ARIA label is `image: `. 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 diff --git a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/label-serializable.mdx b/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/label-serializable.mdx index d29109f27..ece2a1222 100644 --- a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/label-serializable.mdx +++ b/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. + + +## 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 diff --git a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/label.mdx b/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/label.mdx index 4551b9c67..e01c56a05 100644 --- a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/label.mdx +++ b/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. diff --git a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/number.mdx b/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/number.mdx index 95daae5b5..c6d443afb 100644 --- a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/number.mdx +++ b/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. + +## Accessibility + +A number field's ARIA label is `number: `. 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 `` element is `spinbutton`. +[...] With ``, 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 diff --git a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/text-input.mdx b/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/text-input.mdx index 6a40aec49..c9c133748 100644 --- a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/text-input.mdx +++ b/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. + +## Accessibility + +A text input field's ARIA label is `text: `. The on-block display +has the ARIA role `button`. Activating the field overlays and focuses an HTML +text input. + ## Customization ### Spellcheck diff --git a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/variable.mdx b/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/variable.mdx index 88a5eb04f..052352890 100644 --- a/packages/docs/docs/guides/create-custom-blocks/fields/built-in-fields/variable.mdx +++ b/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. + +## Accessibility + +A variable field's ARIA label is `variable: ''`, 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