From 3a2d9779e5ad88730971143e541902d36fba7e4d Mon Sep 17 00:00:00 2001 From: Valerie R Young Date: Thu, 14 Mar 2019 13:52:33 -0400 Subject: [PATCH 01/62] Draft range related properties --- range_related_properties.md | 149 ++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 range_related_properties.md diff --git a/range_related_properties.md b/range_related_properties.md new file mode 100644 index 0000000000..2952320511 --- /dev/null +++ b/range_related_properties.md @@ -0,0 +1,149 @@ +# Range Related Properties + +The range related properties are used to fully present and describe an element whose value can be one of a range of values to assistive technologies. These properties communicate the maximum and minimum values for the element and the element's current value. + +The range properties can also be used to fully present and describe an element whose value can be one of a list of non-numeric values. In this scenario, all possible text values of the element will be programmatically mapped to numbers within the numeric range. + +These attributes are used with the following roles: +* slider +* spinbutton +* progressbar +* meter +* scrollbar + +These proprieties are also used for the separator role, but only if the element is focusable. + +Range Related Property Table + +| Property | Definition | +| --- | --- | +| `aria-valuemin` | Defines the minimum value in the range. | +| `aria-valuemax` | Defines the maximum value in the range. | +| `aria-valuenow` | Defines the value of the element. This value is always a number between `aria-valuemin` and `aria-valuemax`. | +| `aria-valuetext` | Defines a description of the value of the element. | + +## Using `aria-valuemin` and `aria-valuemax` + +When an element's possible values are contained within a known range, the attributes `aria-valuemin` and `aria-valuemax` are used to inform assistive technologies of the minimum and maximum values of the range. When using these properties, always set `aria-valuemin` to the lowest value of the range. + +## Using `aria-valuenow` + +The attribute `aria-valuenow` is used to inform assistive technologies of the current value of an element. When `aria-valuemin` and `aria-valuemax` are specified, set `aria-valuenow` to a numeric value that is within the range define by `aria-valuemin` and `aria-valuemax`. + +## Using `aria-valuetext` + +When the element's values are contained within a range but those values are not numeric (such as "small", "medium" and "large"), `aria-valuetext` is used to surface the text value to assistive technologies. Only use `aria-valuetext` when `aria-valuenow` does not have meaning for the user because using `aria-valuetext` will prevent assistive technologies from communicating `aria-valuenow`. + +## slider Role + +`aria-valuenow`, `aria-valuemin` and `aria-valuemax` are all required attributes for the slider role. `aria-valuetext` can be used when appropriate. Detailed description of the slider role can be found in the slider design pattern and slider (multi-thumb) design pattern. + +### Example with numeric range + +This example is a temperature controller. `aria-valuetext` is not be used as the number value in `aria-valuenow` is meaningful to the user. + +``` +
+
+
+
+ +``` + +The slider example above can be made using the HTML input type=range element. + +``` + +``` + +### Example with `aria-valuetext` + +This example is a fan control. The `aria-valuenow` value is "1", which is not meaningful to the user. The assistive technology will surface the value of `aria-valuetext` ("low") instead. + +``` +
+
+
+
Off
+
Low
+
Medium
+
High
+
+ +``` + +## spinbutton Role + +`aria-valuenow`, `aria-valuemin` and `aria-valuemax` are all required attributes for the spinbutton role. `aria-valuetext` can be used when appropriate. + +This example sets the price of paperclips in cents. + +``` +
+ + + Price per paperclip: $0.50 +
+``` + +The slider example above can be made using the native HTML input type="number" element. + +``` + +Price per paperclip: +$0.50 +``` + +``` + +``` + + +## progressbar Role + +`aria-valuenow`, `aria-valuemin` and `aria-valuemax` are not required attributes for the progressbar role, however, but the attributes might be necessary for communicating the state of a progress bar to assistive technologies. + +### Example: progressbar + +This is an example of a progressbar represent by an SVG. The range properties are necessary to full explain the widget to assistive technologies. + +``` +
Loading: + + + + + + +
+``` + +The progress bar example can be made using the native HTML progress element. + +``` + + +``` + +## scrollbar Role + +`aria-valuenow`, `aria-valuemin` and aria-value max are all required attributes for the scrollbar role. The value of `aria-valuenow` will generally be exposed as a percentage between `aria-valuemin` and `aria-valuemax` calculated by assistive technologies. + +``` +
+3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679 +
+
+
+
+
+``` \ No newline at end of file From 7955203b2c11949052d62867b39280240bce767f Mon Sep 17 00:00:00 2001 From: Valerie R Young Date: Thu, 14 Mar 2019 14:06:55 -0400 Subject: [PATCH 02/62] Minor fixes --- range_related_properties.md | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/range_related_properties.md b/range_related_properties.md index 2952320511..8df4ab85dc 100644 --- a/range_related_properties.md +++ b/range_related_properties.md @@ -5,13 +5,13 @@ The range related properties are used to fully present and describe an element w The range properties can also be used to fully present and describe an element whose value can be one of a list of non-numeric values. In this scenario, all possible text values of the element will be programmatically mapped to numbers within the numeric range. These attributes are used with the following roles: -* slider -* spinbutton -* progressbar -* meter -* scrollbar +* `slider` +* `spinbutton` +* `progressbar` +* `meter` +* `scrollbar` -These proprieties are also used for the separator role, but only if the element is focusable. +These proprieties are also used for the `separator` role, but only if the element is focusable. Range Related Property Table @@ -34,9 +34,9 @@ The attribute `aria-valuenow` is used to inform assistive technologies of the cu When the element's values are contained within a range but those values are not numeric (such as "small", "medium" and "large"), `aria-valuetext` is used to surface the text value to assistive technologies. Only use `aria-valuetext` when `aria-valuenow` does not have meaning for the user because using `aria-valuetext` will prevent assistive technologies from communicating `aria-valuenow`. -## slider Role +## `slider` Role -`aria-valuenow`, `aria-valuemin` and `aria-valuemax` are all required attributes for the slider role. `aria-valuetext` can be used when appropriate. Detailed description of the slider role can be found in the slider design pattern and slider (multi-thumb) design pattern. +`aria-valuenow`, `aria-valuemin` and `aria-valuemax` are all required attributes for the `slider` role. `aria-valuetext` can be used when appropriate. Detailed description of the `slider` role can be found in the [slider design pattern](https://w3c.github.io/aria-practices/#slider) and [slider (multi-thumb) design pattern](https://w3c.github.io/aria-practices/#slidertwothumb). ### Example with numeric range @@ -74,9 +74,9 @@ This example is a fan control. The `aria-valuenow` value is "1", which is not me ``` -## spinbutton Role +## `spinbutton` Role -`aria-valuenow`, `aria-valuemin` and `aria-valuemax` are all required attributes for the spinbutton role. `aria-valuetext` can be used when appropriate. +`aria-valuenow`, `aria-valuemin` and `aria-valuemax` are all required attributes for the `spinbutton` role. `aria-valuetext` can be used when appropriate. This example sets the price of paperclips in cents. @@ -101,13 +101,11 @@ $0.50 ``` -## progressbar Role +## `progressbar` Role -`aria-valuenow`, `aria-valuemin` and `aria-valuemax` are not required attributes for the progressbar role, however, but the attributes might be necessary for communicating the state of a progress bar to assistive technologies. +`aria-valuenow`, `aria-valuemin` and `aria-valuemax` are not required attributes for the `progressbar` role, however, but the attributes might be necessary for communicating the state of a progress bar to assistive technologies. -### Example: progressbar - -This is an example of a progressbar represent by an SVG. The range properties are necessary to full explain the widget to assistive technologies. +This is an example of a progress bar represent by an SVG. The range properties are necessary to full explain the widget to assistive technologies. ```
Loading: @@ -127,9 +125,9 @@ The progress bar example can be made using the native HTML progress element. ``` -## scrollbar Role +## `scrollbar` Role -`aria-valuenow`, `aria-valuemin` and aria-value max are all required attributes for the scrollbar role. The value of `aria-valuenow` will generally be exposed as a percentage between `aria-valuemin` and `aria-valuemax` calculated by assistive technologies. +`aria-valuenow`, `aria-valuemin` and `aria-valuemax` are all required attributes for the `scrollbar` role. The value of `aria-valuenow` will generally be exposed as a percentage between `aria-valuemin` and `aria-valuemax` calculated by assistive technologies. ```
From b382e78318e93e133885a80248160fe82045d3ea Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Tue, 23 Apr 2019 20:02:14 +0200 Subject: [PATCH 03/62] Address feedback --- range_related_properties.md | 45 +++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/range_related_properties.md b/range_related_properties.md index 8df4ab85dc..e2ea9f5a21 100644 --- a/range_related_properties.md +++ b/range_related_properties.md @@ -1,30 +1,36 @@ # Range Related Properties -The range related properties are used to fully present and describe an element whose value can be one of a range of values to assistive technologies. These properties communicate the maximum and minimum values for the element and the element's current value. +ARIA provides the following four properties for communicating on the attributes of a range widget: -The range properties can also be used to fully present and describe an element whose value can be one of a list of non-numeric values. In this scenario, all possible text values of the element will be programmatically mapped to numbers within the numeric range. +| Property | Definition | +| --- | --- | +| `aria-valuemin` | Defines the minimum value in the range. | +| `aria-valuemax` | Defines the maximum value in the range. | +| `aria-valuenow` | Defines the value of the element. This value is a number between `aria-valuemin` and `aria-valuemax` (if they are present). | +| `aria-valuetext` | Defines a description of the value of the element. | + +The range related properties are used to describe an element whose value can be one of a range of values to assistive technologies. These properties communicate the maximum and minimum values for the element and the element's current value. + +The range properties can also be used to describe an element whose value can be one of a list of non-numeric values. In this scenario, all possible text values of the element will be programmatically mapped to numbers within the numeric range by the author. These attributes are used with the following roles: + * `slider` * `spinbutton` * `progressbar` * `meter` * `scrollbar` +* `separator` (if the element is focusable) -These proprieties are also used for the `separator` role, but only if the element is focusable. - -Range Related Property Table +## Using `aria-valuemin` and `aria-valuemax` -| Property | Definition | -| --- | --- | -| `aria-valuemin` | Defines the minimum value in the range. | -| `aria-valuemax` | Defines the maximum value in the range. | -| `aria-valuenow` | Defines the value of the element. This value is always a number between `aria-valuemin` and `aria-valuemax`. | -| `aria-valuetext` | Defines a description of the value of the element. | +When an element's possible values are contained within a known range, the attributes `aria-valuemin` and `aria-valuemax` are used to inform assistive technologies of the minimum and maximum values of the range. When using these properties, set `aria-valuemin` to the lowest value of the range and `aria-valuemax` to the greatest value. -## Using `aria-valuemin` and `aria-valuemax` +When the range is unknown, omit both `aria-valuemin` and `aria-valuemax`. An example of such a widget is an indeterminate progress bar. -When an element's possible values are contained within a known range, the attributes `aria-valuemin` and `aria-valuemax` are used to inform assistive technologies of the minimum and maximum values of the range. When using these properties, always set `aria-valuemin` to the lowest value of the range. +``` +Loading... +``` ## Using `aria-valuenow` @@ -38,9 +44,7 @@ When the element's values are contained within a range but those values are not `aria-valuenow`, `aria-valuemin` and `aria-valuemax` are all required attributes for the `slider` role. `aria-valuetext` can be used when appropriate. Detailed description of the `slider` role can be found in the [slider design pattern](https://w3c.github.io/aria-practices/#slider) and [slider (multi-thumb) design pattern](https://w3c.github.io/aria-practices/#slidertwothumb). -### Example with numeric range - -This example is a temperature controller. `aria-valuetext` is not be used as the number value in `aria-valuenow` is meaningful to the user. +The following example is a temperature controller. `aria-valuetext` is not be used as the number value in `aria-valuenow` is meaningful to the user. ```
@@ -57,9 +61,7 @@ The slider example above can be made using the HTML input type=range element. ``` -### Example with `aria-valuetext` - -This example is a fan control. The `aria-valuenow` value is "1", which is not meaningful to the user. The assistive technology will surface the value of `aria-valuetext` ("low") instead. +The following example is a fan control. The `aria-valuenow` value is "1", which is not meaningful to the user. The assistive technology will surface the value of `aria-valuetext` ("low") instead. ```
@@ -88,7 +90,7 @@ This example sets the price of paperclips in cents.
``` -The slider example above can be made using the native HTML input type="number" element. +The slider example above can be made using the native HTML input type="number" element. ``` @@ -100,7 +102,6 @@ $0.50 ``` - ## `progressbar` Role `aria-valuenow`, `aria-valuemin` and `aria-valuemax` are not required attributes for the `progressbar` role, however, but the attributes might be necessary for communicating the state of a progress bar to assistive technologies. @@ -144,4 +145,4 @@ The progress bar example can be made using the native HTML progress element. aria-valuenow="25">
-``` \ No newline at end of file +``` From 9eefa62d87e27f6163bcadb59413e32b3163e225 Mon Sep 17 00:00:00 2001 From: Valerie R Young Date: Thu, 20 Jun 2019 07:01:11 -0400 Subject: [PATCH 04/62] Review feedback --- range_related_properties.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/range_related_properties.md b/range_related_properties.md index e2ea9f5a21..92ed946744 100644 --- a/range_related_properties.md +++ b/range_related_properties.md @@ -26,11 +26,7 @@ These attributes are used with the following roles: When an element's possible values are contained within a known range, the attributes `aria-valuemin` and `aria-valuemax` are used to inform assistive technologies of the minimum and maximum values of the range. When using these properties, set `aria-valuemin` to the lowest value of the range and `aria-valuemax` to the greatest value. -When the range is unknown, omit both `aria-valuemin` and `aria-valuemax`. An example of such a widget is an indeterminate progress bar. - -``` -Loading... -``` +When the range is unknown, omit both `aria-valuemin` and `aria-valuemax`. See an example of a indeterminate range element [indeterminate progress bar](). ## Using `aria-valuenow` @@ -109,8 +105,8 @@ $0.50 This is an example of a progress bar represent by an SVG. The range properties are necessary to full explain the widget to assistive technologies. ``` -
Loading: - +
Loading: + @@ -119,6 +115,12 @@ This is an example of a progress bar represent by an SVG. The range properties a
``` +To represent an indeterminate progress bar where the value range is unknown, omit the `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` attributes. + +``` +Loading... +``` + The progress bar example can be made using the native HTML progress element. ``` @@ -126,6 +128,7 @@ The progress bar example can be made using the native HTML progress element. ``` + ## `scrollbar` Role `aria-valuenow`, `aria-valuemin` and `aria-valuemax` are all required attributes for the `scrollbar` role. The value of `aria-valuenow` will generally be exposed as a percentage between `aria-valuemin` and `aria-valuemax` calculated by assistive technologies. @@ -146,3 +149,5 @@ The progress bar example can be made using the native HTML progress element.
``` + +If `aria-valuemin` and `aria-valuemax` are omitted, then the browser will use the default values of 0 and 100, respectively. \ No newline at end of file From 8065be095dee00c8120d2e96d1e16e3f9e698fa9 Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Fri, 30 Aug 2019 15:52:37 +0200 Subject: [PATCH 05/62] Move section into aria-practices.html --- aria-practices.html | 131 ++++++++++++++++++++++++++++++ range_related_properties.md | 153 ------------------------------------ 2 files changed, 131 insertions(+), 153 deletions(-) delete mode 100644 range_related_properties.md diff --git a/aria-practices.html b/aria-practices.html index 7a6b53098a..118b6ae315 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -6425,6 +6425,137 @@

Indicating sort order with aria-sort

+ +

Intentionally Hiding Semantics with the presentation Role

diff --git a/range_related_properties.md b/range_related_properties.md deleted file mode 100644 index 92ed946744..0000000000 --- a/range_related_properties.md +++ /dev/null @@ -1,153 +0,0 @@ -# Range Related Properties - -ARIA provides the following four properties for communicating on the attributes of a range widget: - -| Property | Definition | -| --- | --- | -| `aria-valuemin` | Defines the minimum value in the range. | -| `aria-valuemax` | Defines the maximum value in the range. | -| `aria-valuenow` | Defines the value of the element. This value is a number between `aria-valuemin` and `aria-valuemax` (if they are present). | -| `aria-valuetext` | Defines a description of the value of the element. | - -The range related properties are used to describe an element whose value can be one of a range of values to assistive technologies. These properties communicate the maximum and minimum values for the element and the element's current value. - -The range properties can also be used to describe an element whose value can be one of a list of non-numeric values. In this scenario, all possible text values of the element will be programmatically mapped to numbers within the numeric range by the author. - -These attributes are used with the following roles: - -* `slider` -* `spinbutton` -* `progressbar` -* `meter` -* `scrollbar` -* `separator` (if the element is focusable) - -## Using `aria-valuemin` and `aria-valuemax` - -When an element's possible values are contained within a known range, the attributes `aria-valuemin` and `aria-valuemax` are used to inform assistive technologies of the minimum and maximum values of the range. When using these properties, set `aria-valuemin` to the lowest value of the range and `aria-valuemax` to the greatest value. - -When the range is unknown, omit both `aria-valuemin` and `aria-valuemax`. See an example of a indeterminate range element [indeterminate progress bar](). - -## Using `aria-valuenow` - -The attribute `aria-valuenow` is used to inform assistive technologies of the current value of an element. When `aria-valuemin` and `aria-valuemax` are specified, set `aria-valuenow` to a numeric value that is within the range define by `aria-valuemin` and `aria-valuemax`. - -## Using `aria-valuetext` - -When the element's values are contained within a range but those values are not numeric (such as "small", "medium" and "large"), `aria-valuetext` is used to surface the text value to assistive technologies. Only use `aria-valuetext` when `aria-valuenow` does not have meaning for the user because using `aria-valuetext` will prevent assistive technologies from communicating `aria-valuenow`. - -## `slider` Role - -`aria-valuenow`, `aria-valuemin` and `aria-valuemax` are all required attributes for the `slider` role. `aria-valuetext` can be used when appropriate. Detailed description of the `slider` role can be found in the [slider design pattern](https://w3c.github.io/aria-practices/#slider) and [slider (multi-thumb) design pattern](https://w3c.github.io/aria-practices/#slidertwothumb). - -The following example is a temperature controller. `aria-valuetext` is not be used as the number value in `aria-valuenow` is meaningful to the user. - -``` -

-
-
-
- -``` - -The slider example above can be made using the HTML input type=range element. - -``` - -``` - -The following example is a fan control. The `aria-valuenow` value is "1", which is not meaningful to the user. The assistive technology will surface the value of `aria-valuetext` ("low") instead. - -``` -
-
-
-
Off
-
Low
-
Medium
-
High
-
- -``` - -## `spinbutton` Role - -`aria-valuenow`, `aria-valuemin` and `aria-valuemax` are all required attributes for the `spinbutton` role. `aria-valuetext` can be used when appropriate. - -This example sets the price of paperclips in cents. - -``` -
- - - Price per paperclip: $0.50 -
-``` - -The slider example above can be made using the native HTML input type="number" element. - -``` - -Price per paperclip: -$0.50 -``` - -``` - -``` - -## `progressbar` Role - -`aria-valuenow`, `aria-valuemin` and `aria-valuemax` are not required attributes for the `progressbar` role, however, but the attributes might be necessary for communicating the state of a progress bar to assistive technologies. - -This is an example of a progress bar represent by an SVG. The range properties are necessary to full explain the widget to assistive technologies. - -``` -
Loading: - - - - - - -
-``` - -To represent an indeterminate progress bar where the value range is unknown, omit the `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` attributes. - -``` -Loading... -``` - -The progress bar example can be made using the native HTML progress element. - -``` - - -``` - - -## `scrollbar` Role - -`aria-valuenow`, `aria-valuemin` and `aria-valuemax` are all required attributes for the `scrollbar` role. The value of `aria-valuenow` will generally be exposed as a percentage between `aria-valuemin` and `aria-valuemax` calculated by assistive technologies. - -``` -
-3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679 -
-
-
-
-
-``` - -If `aria-valuemin` and `aria-valuemax` are omitted, then the browser will use the default values of 0 and 100, respectively. \ No newline at end of file From 2f8d7a1628832c7e1c8b016623afb4f8d846aece Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Tue, 3 Dec 2019 14:45:20 +0100 Subject: [PATCH 06/62] Fix a broken link --- aria-practices.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aria-practices.html b/aria-practices.html index 118b6ae315..99c2622eee 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -6469,7 +6469,7 @@

Range Related Properties

+ + + + @@ -6485,7 +6491,7 @@

slider Role

aria-label="Temperature (F)" tabindex="0"> </div> </div> -

The slider example above can be made using the HTML input type=range element.

+

The slider example above can be made using the HTML <input type="range"> element.

<input type="range" min="50" value="68" max="100" aria-label="Temperature (F)">

The following example is a fan control. The aria-valuenow value is "1", which is not meaningful to the user. The assistive technology will surface the value of aria-valuetext ("low") instead.

<div class="rail">
@@ -6508,7 +6514,7 @@ 
spinbutton Role

   <button id="raise-price">Raise</button>
   Price per paperclip: $<span id="price">0.50</span>
 </div>
-

The slider example above can be made using the native HTML input type="number" element.

+

The slider example above can be made using the native HTML <input type="number"> element.

<input type="number" min="0.01" value="0.5" max="2" aria-labelledby="paperclip-label">
 <span id="paperclip-label">Price per paperclip</span>:
 $<output id="price" aria-labelledby="paperclip-label">0.50</output>
@@ -6529,7 +6535,7 @@

progressbar Role

</div>

To represent an indeterminate progress bar where the value range is unknown, omit the aria-valuemin, aria-valuemax, and aria-valuenow attributes.

<img role="progressbar" src="spinner.gif" alt="Loading...">
-

The progress bar example can be made using the native HTML progress element.

+

The progress bar example can be made using the native HTML progress element.

<label for="loadstatus">Loading:</label>
 <progress id="loadstatus" max="100" value="33"></progress>
From ff195f26d77bb4e487cd3ae14e131c890c09fa2b Mon Sep 17 00:00:00 2001 From: Simon Pieters Date: Tue, 3 Dec 2019 15:35:46 +0100 Subject: [PATCH 08/62] Rename some headings, add a table for valuemin/max --- aria-practices.html | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/aria-practices.html b/aria-practices.html index e2d39c0288..d6026bfb22 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -6426,7 +6426,8 @@

Indicating sort order with aria-sort