From bc975008a4495801410b5b4212c3b94b3410850e Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Tue, 26 Mar 2024 14:30:07 +1100 Subject: [PATCH 1/2] Add Element.ariaBrailleLabel and .ariaBrailleRoleDescription --- .../attributes/aria-braillelabel/index.md | 15 ++-- .../aria-brailleroledescription/index.md | 19 ++-- .../web/api/element/ariabraillelabel/index.md | 79 +++++++++++++++++ .../ariabrailleroledescription/index.md | 87 +++++++++++++++++++ files/en-us/web/api/element/index.md | 4 + 5 files changed, 188 insertions(+), 16 deletions(-) create mode 100644 files/en-us/web/api/element/ariabraillelabel/index.md create mode 100644 files/en-us/web/api/element/ariabrailleroledescription/index.md diff --git a/files/en-us/web/accessibility/aria/attributes/aria-braillelabel/index.md b/files/en-us/web/accessibility/aria/attributes/aria-braillelabel/index.md index 110b799eef8488b..6046e876563ac7c 100644 --- a/files/en-us/web/accessibility/aria/attributes/aria-braillelabel/index.md +++ b/files/en-us/web/accessibility/aria/attributes/aria-braillelabel/index.md @@ -5,23 +5,23 @@ page-type: aria-attribute spec-urls: https://w3c.github.io/aria/#aria-braillelabel --- -The global `aria-braillelabel` property defines a string value that labels the current element, which is intended to be converted into Braille. +The global `aria-braillelabel` property defines a string value that labels the current element, which is intended to be converted into braille. ## Description -The global `aria-braillelabel` attribute is similar to the global [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) in that it defines a string value that labels the current element. While `aria-label` is read by the screen reader, the contents of the `aria-braillelabel` attribute are converted into Braille; providing the user with a recognizable name of the object in Braille. +The global `aria-braillelabel` attribute is similar to the global [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) in that it defines a string value that labels the current element. While `aria-label` is read by the screen reader, the contents of the `aria-braillelabel` attribute are converted into Braille; providing the user with a recognizable name of the object in braille. -The purpose of the `aria-braillelabel` property is to override how assistive technologies localize and express the accessible name of an element in Braille and should only be used when accessible name, without this attribute, when converted to Braille, would not be the desired user experience. +The purpose of the `aria-braillelabel` property is to override how assistive technologies localize and express the accessible name of an element in Braille. It should only be used when, without this attribute, the accessible name would not be the desired user experience when converted to Braille. When using `aria-braillelabel`, ensure that: - The element to which `aria-braillelabel` is applied has a valid accessible name. -- The value of aria-braillelabel has actual content and is not empty or only whitespace in unicode or unicode Braille. +- The value of `aria-braillelabel` has actual content and is not empty or only whitespace in unicode or unicode braille. - The value is NOT the same as the accessible name. - The `aria-braillelabel` values are localized to align with the document language. -- Communicate to the user that this attribute is available, especially if the content contains Unicode Braille Patterns, so the user knows to set the settings to apply user specific braille translations +- Communicate to the user that this attribute is available, especially if the content contains unicode braille patterns, so the user knows to set the settings to apply user specific braille translations -> **Note:** Assistive Technologies with braille support can convert the accessible names to Braille. +> **Note:** Assistive technologies with braille support can convert the accessible names to braille. > Therefore, only use `aria-braillelabel` when the accessible name is not the user experience you want. Using only the accessible name, e.g., from content or via `aria-label` is almost always the better user experience, so don't use aria-braillelabel to replicate aria-label. Only use `aria-braillelabel` if the accessible name cannot provide an adequate braille representation. @@ -37,7 +37,7 @@ A braille display may display "btn \*\*\*" in Braille rather than the more verbo ## Values - `` - - : The value is a string, an unconstrained value type, that is intended to be converted into Braille. + - : The value is a string, an unconstrained value type, that is intended to be converted into braille. ## Associated roles @@ -49,6 +49,7 @@ Used in **ALL** roles. ## See also +- {{domxref("Element.ariaBrailleLabel")}} - [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-brailleroledescription) diff --git a/files/en-us/web/accessibility/aria/attributes/aria-brailleroledescription/index.md b/files/en-us/web/accessibility/aria/attributes/aria-brailleroledescription/index.md index abb086e02dd8b17..9f96ebfb621e203 100644 --- a/files/en-us/web/accessibility/aria/attributes/aria-brailleroledescription/index.md +++ b/files/en-us/web/accessibility/aria/attributes/aria-brailleroledescription/index.md @@ -11,7 +11,7 @@ The global `aria-brailleroledescription` attribute defines a human-readable, aut Braille is not a one-to-one transliteration of letters and numbers, but rather it includes various abbreviations, contractions, and characters that represent words (known as logograms). -Instead of converting long role descriptions to Braille, the `aria-brailleroledescription` attribute allows for providing an abbreviated version of the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) value, which is a human-readable, author-localized description for the role of an element, for improved user experience with Braille interfaces. +Instead of converting long role descriptions to Braille, the `aria-brailleroledescription` attribute allows for providing an abbreviated version of the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) value, which is a human-readable, author-localized description for the role of an element, for improved user experience with braille interfaces. Basically, the value of `aria-brailleroledescription` is an abbreviated version of the `aria-roledescription` attribute to be converted into Braille. @@ -25,37 +25,37 @@ Basically, the value of `aria-brailleroledescription` is an abbreviated version ``` -Most assistive technologies, like screen readers, will read the above as "slide, welcome to by talk. Image, Me." Braille assistive technologies will present "sld welcome to my talk gra me" in Braille. The semantic {{HTMLElement('article')}} is given the role of "slide" by the `aria-roledescription` attribute; "slide" being a role not defined in the specification, but is a common role for slides in a presentation. In Braille, the role is presented as "sld". The "gra" is short for "graphic", which is how the "image" role is shortened in Braille. +Most assistive technologies, like screen readers, will read the above as "slide, welcome to my talk. Image, Me." Braille assistive technologies will present "sld welcome to my talk gra me" in braille. The semantic {{HTMLElement('article')}} is given the role of "slide" by the `aria-roledescription` attribute; "slide" being a role not defined in the specification, but is a common role for slides in a presentation. In Braille, the role is presented as "sld". The "gra" is short for "graphic", which is how the "image" role is shortened in braille. The `aria-brailleroledescription` attribute should only be used to clarify the purpose of non-interactive container roles like "group" or "region", or to provide a more specific description of a widget in a braille context. -As the `aria-brailleroledescription` attribute overrides how assistive technologies localize and express the name of a role in Braille, inappropriate values will prevent users from understanding and interacting with an element on braille interfaces. +As the `aria-brailleroledescription` attribute overrides how assistive technologies localize and express the name of a role in braille, inappropriate values will prevent users from understanding and interacting with an element on braille interfaces. -Only use `aria-brailleroledescription` if [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) is present. However, if the `aria-roledescription` value works in Braille, the Braille version of the attribute is not needed. In general, `aria-brailleroledescription` should only be used in the rare case when a `aria-roledescription` is too verbose for Braille. +Only use `aria-brailleroledescription` if [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) is present. However, if the `aria-roledescription` value works in braille, the braille version of the attribute is not needed. In general, `aria-brailleroledescription` should only be used in the rare case when a `aria-roledescription` is too verbose for braille. A few rules to remember: - Only apply `aria-brailleroledescription` to elements with a valid ARIA role or elements with implicit role semantics. - The `aria-brailleroledescription`, if present, must have a non-empty, none null value that is different from the `aria-roledescription` value, which, in turn, is different from the ARIA explicit or role or implicit semantic role. -- Avoid using Unicode Braille Patterns. If they must be used, ensure the `aria-brailleroledescription` value contains content other than Unicode Braille Patterns, whitespace, and Braille Pattern dots-0. +- Avoid using Unicode Braille Patterns. If they must be used, ensure the `aria-brailleroledescription` value contains content other than unicode braille patterns, whitespace, and braille battern dots-0. - Ensure the value is always localized to the document's language. -> **Warning:** If the content is only in Unicode Braille Patterns, the value will not be translated according to the user's preferred translation table. +> **Warning:** If the content is only in unicode braille patterns, the value will not be translated according to the user's preferred translation table. > **Note:** Do NOT use `aria-brailleroledescription` to replicate `aria-roledescription`. Only include this attribute when `aria-roledescription` does not provide an adequate braille representation. The `aria-brailleroledescription` value will not be exposed to the braille user if: -- The value is empty or contains only whitespace characters or the empty Braille pattern: dots-0 (U+2800). +- The value is empty or contains only whitespace characters or the empty braille pattern: dots-0 (U+2800). - The element to which the attribute is applied has an explicit or implicit WAI-ARIA role where `aria-brailleroledescription` is prohibited, including the `generic` role. - The element to which the attribute is applied does not have a valid `aria-roledescription`. -> **Note:** Test your sites and applications with daily users of assistive technologies, including Braille readers, to ensure your content makes sense in Braille. +> **Note:** Test your sites and applications with daily users of assistive technologies, including braille readers, to ensure your content makes sense in braille. ## Values - `` - - : The value is a string, an unconstrained value type, that is intended to be converted into Braille + - : The value is a string, an unconstrained value type, that is intended to be converted into braille ## Associated roles @@ -67,6 +67,7 @@ Used in **ALL** roles (except [`generic`](/en-US/docs/Web/Accessibility/ARIA/Rol ## See also +- {{domxref("Element.ariaBrailleRoleDescription")}} - [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription). - [`Element.ariaRoleDescription`](/en-US/docs/Web/API/Element/ariaRoleDescription) diff --git a/files/en-us/web/api/element/ariabraillelabel/index.md b/files/en-us/web/api/element/ariabraillelabel/index.md new file mode 100644 index 000000000000000..2dcb635db9696ea --- /dev/null +++ b/files/en-us/web/api/element/ariabraillelabel/index.md @@ -0,0 +1,79 @@ +--- +title: "Element: ariaBrailleLabel property" +short-title: ariaBrailleLabel +slug: Web/API/Element/ariaBrailleLabel +page-type: web-api-instance-property +browser-compat: api.Element.ariaBrailleLabel +--- + +{{DefaultAPISidebar("DOM")}} + +The **`ariaBrailleLabel`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-braillelabel`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-braillelabel) attribute, which defines the ARIA braille label of the element. + +This element label may be used by assistive technologies that can present content in braille, but should only be set if a braille-specific label would improve the user experience. +The [`aria-braillelabel`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-braillelabel) contains additional information about when the property should be set. + +## Value + +- `` + - : The value is a string, an unconstrained value type, that is intended to be converted into braille. + +## Examples + +### Getting and setting ariaBrailleLabel + +This example shows how to get and set the `ariaBrailleLabel` property. + +#### HTML + +First we define a button with label text "3 out of 5 stars" and an `aria-braillelabel` attribute with a value of `"\*\*\*"`. +This allows a braille display to show "btn \*\*\*" in braille rather than the more verbose "btn gra 3 out of 5 stars". + +```html + +``` + +```html hidden +

+```
+
+```css hidden
+#log {
+  height: 100px;
+  overflow: scroll;
+  padding: 0.5rem;
+  border: 1px solid black;
+}
+```
+
+#### JavaScript
+
+```js hidden
+const logElement = document.querySelector("#log");
+function log(text) {
+  logElement.innerText = `${logElement.innerText}${text}\n`;
+  logElement.scrollTop = logElement.scrollHeight;
+}
+```
+
+The code then uses the button's `ariaBrailleLabel` property to first get and log the braille label.
+It then sets the braille label to "3\*" and logs the value again.
+
+```js
+const button = document.getElementById("button");
+log(button.ariaBrailleLabel);
+button.ariaBrailleLabel = "3*";
+log(button.ariaBrailleLabel);
+```
+
+#### Result
+
+{{EmbedLiveSample("Getting and setting ariaBrailleLabel")}}
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
diff --git a/files/en-us/web/api/element/ariabrailleroledescription/index.md b/files/en-us/web/api/element/ariabrailleroledescription/index.md
new file mode 100644
index 000000000000000..f1c38092aa76b32
--- /dev/null
+++ b/files/en-us/web/api/element/ariabrailleroledescription/index.md
@@ -0,0 +1,87 @@
+---
+title: "Element: ariaBrailleRoleDescription property"
+short-title: ariaBrailleRoleDescription
+slug: Web/API/Element/ariaBrailleRoleDescription
+page-type: web-api-instance-property
+browser-compat: api.Element.ariaBrailleRoleDescription
+---
+
+{{DefaultAPISidebar("DOM")}}
+
+The **`ariaBrailleRoleDescription`** property of the {{domxref("Element")}} interface reflects the value of the [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-brailleroledescription) attribute, which defines the ARIA braille role description of the element.
+
+This property may be used to provide an abbreviated version of the [`aria-roledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) value.
+It should only be used if `aria-roledescription` is present and in the rare case where it is is too verbose for braille.
+The [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-brailleroledescription) contains additional information about when the property should be set.
+
+## Value
+
+- ``
+  - : The value is a string, an unconstrained value type, that is intended to be converted into braille.
+
+## Examples
+
+### Getting and setting ariaBrailleRoleDescription
+
+This example shows how you can get and set the `ariaBrailleRoleDescription` property.
+
+#### HTML
+
+First we define an `
` element that would be use as a slide in a slideshow.
+We set the `aria-roledescription` attribute to "slide", and its braille contraction in `aria-brailleroledescription` to "sld".
+
+```html
+

+  
Welcome to my talk

+

+```
+
+```html hidden
+

+```
+
+```css hidden
+#log {
+  height: 70px;
+  overflow: scroll;
+  padding: 0.5rem;
+  border: 1px solid black;
+}
+```
+
+#### JavaScript
+
+```js hidden
+const logElement = document.querySelector("#log");
+function log(text) {
+  logElement.innerText = `${logElement.innerText}${text}\n`;
+  logElement.scrollTop = logElement.scrollHeight;
+}
+```
+
+To get the element's role description we use the `ariaBrailleRoleDescription` property.
+The code below first gets and then logs the value.
+It then sets the braille role description to "sd" and logs the value again (for illustration only — in production code you would not set this value).
+
+```js
+const article = document.getElementById("article");
+log(article.ariaBrailleRoleDescription);
+article.ariaBrailleRoleDescription = "sd";
+log(article.ariaBrailleRoleDescription);
+```
+
+#### Result
+
+{{EmbedLiveSample("Getting and setting ariaBrailleRoleDescription")}}
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
diff --git a/files/en-us/web/api/element/index.md b/files/en-us/web/api/element/index.md
index 7f73359cdce935e..60e2f84c0463518 100644
--- a/files/en-us/web/api/element/index.md
+++ b/files/en-us/web/api/element/index.md
@@ -94,6 +94,10 @@ _The `Element` interface also includes the following properties._
   - : A string reflecting the [`aria-atomic`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) attribute, which indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the [`aria-relevant`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-relevant) attribute.
 - {{domxref("Element.ariaAutoComplete")}}
   - : A string reflecting the [`aria-autocomplete`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-autocomplete) attribute, which indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made.
+- {{domxref("Element.ariaBrailleLabel")}}
+  - : A string reflecting the [`aria-braillelabel`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-braillelabel) attribute, which defines the braille label of the element.
+- {{domxref("Element.ariaBrailleRoleDescription")}}
+  - : A string reflecting the [`aria-brailleroledescription`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-brailleroledescription) attribute, which defines the ARIA braille role description of the element.
 - {{domxref("Element.ariaBusy")}}
   - : A string reflecting the [`aria-busy`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-busy) attribute, which indicates whether an element is being modified, as assistive technologies may want to wait until the modifications are complete before exposing them to the user.
 - {{domxref("Element.ariaChecked")}}

From 09783ec14f3e913533ebe7a9d09bf632267aa49b Mon Sep 17 00:00:00 2001
From: sideshowbarker 
Date: Tue, 26 Mar 2024 19:29:13 +0900
Subject: [PATCH 2/2] Update
 files/en-us/web/accessibility/aria/attributes/aria-braillelabel/index.md

---
 .../accessibility/aria/attributes/aria-braillelabel/index.md    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/accessibility/aria/attributes/aria-braillelabel/index.md b/files/en-us/web/accessibility/aria/attributes/aria-braillelabel/index.md
index 6046e876563ac7c..a4b0cdc372f6673 100644
--- a/files/en-us/web/accessibility/aria/attributes/aria-braillelabel/index.md
+++ b/files/en-us/web/accessibility/aria/attributes/aria-braillelabel/index.md
@@ -11,7 +11,7 @@ The global `aria-braillelabel` property defines a string value that labels the c
 
 The global `aria-braillelabel` attribute is similar to the global [`aria-label`](/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) in that it defines a string value that labels the current element. While `aria-label` is read by the screen reader, the contents of the `aria-braillelabel` attribute are converted into Braille; providing the user with a recognizable name of the object in braille.
 
-The purpose of the `aria-braillelabel` property is to override how assistive technologies localize and express the accessible name of an element in Braille. It should only be used when, without this attribute, the accessible name would not be the desired user experience when converted to Braille.
+The purpose of the `aria-braillelabel` property is to override how assistive technologies localize and express the accessible name of an element in Braille. It should only be used when, without this attribute, the accessible name would not be the desired user experience when converted to braille.
 
 When using `aria-braillelabel`, ensure that: