a11y: add service to add aria-describedby labels #6168

andrewseguin · 2017-07-31T17:57:03Z

Service adds a new element in the document body that contains the message. This is pointed to by the host element using aria-describedby for screenreaders to read out.

Used by tooltip and improved its accessibility. (add show on focus, escape keyboard shortcut)

crisbeto · 2017-07-31T18:04:26Z

src/lib/tooltip/tooltip.ts

+
+    // Remove the a11y message if this was its last unique instance.
+    const a11yMessageElement = a11yMessages.get(message);
+    if (a11yMessageElement && --a11yMessageElement.count == 0) {


This might be a little more readable as if (a11yMessageElement && a11yMessageElement.count === 1) and then doing the decrement separately.

crisbeto · 2017-07-31T18:05:24Z

src/lib/tooltip/tooltip.ts

+
+    // If the global messages container no longer has any children, remove it.
+    if (!this._getA11yMessagesContainer()!.childNodes.length) {
+      document.body.removeChild(this._getA11yMessagesContainer()!);


You can use the Renderer2 to create/add/remove these elements.

crisbeto · 2017-07-31T18:06:15Z

src/lib/tooltip/tooltip.ts

+
+    const messageElement = document.createElement('div');
+    messageElement.id = `md-tooltip-message-${latestA11yMessageId++}`;
+    messageElement.innerHTML = message;


This looks a little dangerous. Perhaps we should use textContent instead since the spec doesn't allow rich text inside tooltips, IIRC?

crisbeto · 2017-07-31T18:06:57Z

src/lib/tooltip/tooltip.ts

+
+    const messageElement = document.createElement('div');
+    messageElement.id = `md-tooltip-message-${latestA11yMessageId++}`;
+    messageElement.innerHTML = message;


This one also needs to be updated if the tooltip text changes.

In the set message function, we'll unregister the old message and register the new one

crisbeto · 2017-07-31T18:09:28Z

src/lib/tooltip/tooltip.ts

+    if (this._message) { this._unregisterA11yMessage(this._message); }
+
+    // If the message is not a string (e.g. number), convert it to a string and trim it.
+    this._message = value ? `${value}`.trim() : '';


Might be a good idea to have a test for this case in particular (passing in a non-string to the message). We have another pending PR that deals with the same issue: #6146

crisbeto · 2017-07-31T18:10:20Z

src/lib/tooltip/tooltip.ts

+  private _createA11yMessagesContainer() {
+    const a11yMessagesContainer = document.createElement('div');
+    a11yMessagesContainer.id = A11Y_MESSAGES_CONTAINER_ID;
+    a11yMessagesContainer.className = 'cdk-visually-hidden';


It's unlikely for this to clobber any classes, but it's still better to use the renderer or classList.

andrewseguin · 2017-07-31T18:29:19Z

Good call on the renderer stuff, wasn't even thinking about it

jelbourn · 2017-07-31T21:16:11Z

src/lib/tooltip/tooltip.ts

+export const A11Y_MESSAGES_CONTAINER_ID = 'md-tooltip-a11y-messages';
+
+/** Global incremental identifier for each registered a11y message. */
+let latestA11yMessageId = 0;


I'd be okay with just calling this nextId (which is what we typically name these).

jelbourn · 2017-07-31T21:18:35Z

src/lib/tooltip/tooltip.ts

+    if (this._message) { this._unregisterA11yMessage(this._message); }
+
+    // If the message is not a string (e.g. number), convert it to a string and trim it.
+    this._message = value ? `${value}`.trim() : '';


this._message = `${value || ''}`.trim();

?

This is done to address an issue where numbers are being used as Input and are throwing an error because they do not have trim(). This converts the input to string and trims it.

My suggestion still stringifies the value but omits the ternary.

jelbourn · 2017-07-31T21:21:09Z

src/lib/tooltip/tooltip.ts

+
+  /** Creates the global container for all tooltip a11y messages. */
+  private _createA11yMessagesContainer() {
+    const a11yMessagesContainer = this._renderer.createElement('div');


This needs aria-hidden as well. Otherwise screen-reader users will run into this content at the end of the document without context

jelbourn · 2017-07-31T21:23:05Z

src/lib/tooltip/tooltip.ts

+   * If an element has already been created for this message, increase that registered message's
+   * reference count.
+   */
+  private _registerA11yMessage() {


What do you think about breaking all the code around this approach into a separate class called something like AriaDescriber? It would be good to capture all of this logic in one place separate from the tooltip and we could potentially re-use it in the future.

jelbourn · 2017-07-31T21:23:56Z

src/lib/tooltip/tooltip.ts

+  }
+
+  /** Returns the global container for tooltip a11y messages. */
+  private _getA11yMessagesContainer() {


Why not just remember the element?

jelbourn · 2017-07-31T21:28:22Z

src/lib/tooltip/tooltip.ts

+  /** Sets the trigger's aria-describedby attribute to the tooltip message element. */
+  private _setAriaDescribedBy() {
+    // Return if an aria-describedby already exists and it is not referencing a tooltip message.
+    const ariaDescribedBy = this._elementRef.nativeElement.getAttribute('aria-describedby');


Something I realized just now is that rather than clobbering an existing aria-describedby, we should augment it with the new ID (the attribute can have multiple, comma-delimited IDs). I talked to @mmalerba about doing the same thing for inputs with md-error and md-hint. We should create a couple utility functions in cdk/a11y to add/remove an ID to an element's aria attribute. Something like...

addAriaReferencedId(element, id, 'aria-describedby'); removeAriaReferencedId(element, id, 'aria-describedby');

(open to coming up with a better name)

andrewseguin · 2017-08-07T18:44:02Z

Updated now so that the majority of the change is by adding aria-describer. Usage from tooltip is still included to show how it is used and its minimal code. Ready for review

jelbourn · 2017-08-08T01:15:07Z

src/cdk/a11y/aria-describer.ts

+ * to the Renderer.
+ */
+@Injectable()
+export class AriaDescriber {


Let's make this @docs-private for now; I don't think this will be a public API before we're out of beta

jelbourn · 2017-08-08T01:23:58Z

src/cdk/a11y/aria-describer.ts

+  constructor(private _platform: Platform,
+              @Optional() private _renderer: Renderer2) {
+    if (!_renderer) {
+      throw Error('AriaDescriber must be provided through a component\'s provider decorator ' +


Can use " or ` for the string instead of escaping the '

jelbourn · 2017-08-08T01:24:49Z

src/cdk/a11y/aria-describer.ts

+let nextId = 0;
+
+/** Global map of all registered message elements that have been placed into the document. */
+const registeredMessages = new Map<string, RegisteredMessage>();


messageRegistry?

jelbourn · 2017-08-08T01:27:15Z

src/cdk/a11y/aria-describer.ts

+ */
+export interface RegisteredMessage {
+  messageElement: HTMLElement;
+  hostElements: HTMLElement[];


Why do you need to keep track of these elements? I'm thinking this may cause a memory leak if references to elements are preserved here when the elements have been removed.

Could you accomplish what you need by adding an attribute to the described element?

jelbourn · 2017-08-08T01:31:06Z

src/cdk/a11y/aria-describer.ts

+   */
+  private _createMessageElement(message: string): HTMLElement {
+    const messageElement = this._renderer.createElement('div');
+    this._renderer.setAttribute(messageElement, 'id', `cdk-aria-describedby-message-${nextId++}`);


How about just cdk-describedby-x?

Went with cdk-describedby-message-## for the messages, and cdk-described-host for the elements that are described.

jelbourn · 2017-08-08T01:37:23Z

src/cdk/a11y/aria-reference.ts

+ */
+
+/** IDs are deliminated by an empty space, as per the spec. */
+const ID_DELIMINATOR = ' ';


We should probably be tolerant of any amount of whitespace between IDs rather than a single space (even though the spec calls for a single space)

jelbourn · 2017-08-08T01:38:12Z

src/cdk/a11y/aria-reference.ts

+const ID_DELIMINATOR = ' ';
+
+/** Adds an aria reference ID to an element's aria property if it is not already present. */
+export function addAriaReferencedId(el: HTMLElement, id: string, attr: string) {


element, attributeName, id feels like a more natural argument order

jelbourn · 2017-08-08T01:40:09Z

src/cdk/a11y/aria-reference.ts

+  el.setAttribute(attr, filteredIds.join(ID_DELIMINATOR));
+}
+
+/** Returns a list of an element's aria reference IDs for the provided aria attribute. */


Gets the list of IDs referenced by the given ARIA attribute on an element. Used for attributes such as aria-labelledby, aria-owns, etc.

jelbourn · 2017-08-08T01:41:31Z

src/cdk/a11y/aria-reference.ts

+  el.setAttribute(attr, ids.join(ID_DELIMINATOR));
+}
+
+/** Removes an aria reference ID from an element's aria property. */


Removes the given ID from the specified ARIA attribute on an element. Used for attributes such as aria-labelledby, aria-owns, etc.

jelbourn · 2017-08-08T01:42:19Z

src/cdk/a11y/aria-reference.ts

+/** IDs are deliminated by an empty space, as per the spec. */
+const ID_DELIMINATOR = ' ';
+
+/** Adds an aria reference ID to an element's aria property if it is not already present. */


Adds the given ID to the specified ARIA attribute on an element. Used for attributes such as aria-labelledby, aria-owns, etc.

mmalerba · 2017-08-08T16:06:25Z

src/cdk/a11y/aria-describer.ts

+    if (!this._platform.isBrowser || !message.trim()) { return; }
+
+    if (!registeredMessages.get(message)) {
+      const messageElement = this._createMessageElement(message);


Is there no way to use existing DOM elements as description messages? For the input we always already have a md-hint or md-error element with the message.

Maybe you could make a directive that uses this service under the hood for existing elements to use?

Something like:

<span [cdkDescribes]="listOfElementsIDescribe">...</span>

Or the other way around:

<span [cdkDescribedBy]="listOfElementsThatDescribeMe">...</span>

crisbeto · 2017-08-08T17:48:56Z

src/cdk/a11y/aria-describer.spec.ts

+function expectMessages(messages: string[]) {
+  const messageElements = getMessageElements();
+  if (!messageElements) {
+    fail(`Expected messages ${messages} but there were no message elements`);


Why not have a regular expect here?

crisbeto · 2017-08-08T17:51:20Z

src/cdk/a11y/aria-describer.spec.ts

+  }
+
+  const messages: string[] = [];
+  ariaDescribedBy.split(' ').forEach(referenceId => {


You can condense this logic with an array map or reduce.

crisbeto · 2017-08-08T17:53:15Z

src/cdk/a11y/aria-describer.ts

+  constructor(private _platform: Platform,
+              @Optional() private _renderer: Renderer2) {
+    if (!_renderer) {
+      throw Error('AriaDescriber must be provided through a component\'s provider decorator ' +


You can get access to a renderer without going through a component. See #5840

crisbeto · 2017-08-08T17:53:48Z

src/cdk/a11y/aria-describer.ts

+   * message element.
+   */
+  addDescription(hostElement: HTMLElement, message: string) {
+    if (!this._platform.isBrowser || !message.trim()) { return; }


The message.trim will fail if the value is not a string.

crisbeto · 2017-08-08T17:54:39Z

src/cdk/a11y/aria-describer.ts

+  addDescription(hostElement: HTMLElement, message: string) {
+    if (!this._platform.isBrowser || !message.trim()) { return; }
+
+    if (!registeredMessages.get(message)) {


It's pretty much the same, but you can use registeredMessages.has(message) here.

crisbeto · 2017-08-08T17:55:07Z

src/cdk/a11y/aria-describer.ts

+   * Removes the host element's aria-describedby reference to the message element.
+   */
+  removeDescription(hostElement: HTMLElement, message: string) {
+    if (!this._platform.isBrowser || !message.trim()) { return; }


This trim has the potential to fail as well.

crisbeto · 2017-08-08T17:55:50Z

src/cdk/a11y/aria-describer.ts

+    registeredMessage.hostElements = registeredMessage.hostElements.filter(el => el != hostElement);
+    removeAriaReferencedId(hostElement, registeredMessage.messageElement.id, 'aria-describedby');
+
+    if (registeredMessage.hostElements.length == 0) {


Either triple equals or !registeredMessage.hostElements.length here and below.

crisbeto · 2017-08-08T17:56:30Z

src/cdk/a11y/aria-describer.ts

+  }
+
+  /** Unregisters all created message elements and removes the message container. */
+  _unregisterAllMessages() {


This one could be renamed to ngOnDestroy which has the advantage of being called by Angular when appropriate.

andrewseguin · 2017-08-09T00:02:17Z

Updated based on the comments, thanks

jelbourn · 2017-08-09T16:13:29Z

src/cdk/a11y/aria-describer.ts

+    }
+
+    const registeredMessage = messageRegistry.get(message)!;
+    registeredMessage.referenceCount++;


Only update the reference count if the element is not already described by the message? (can check the existing IDs)

jelbourn · 2017-08-09T16:26:40Z

src/cdk/a11y/aria-reference.ts

+ * Used for attributes such as aria-labelledby, aria-owns, etc.
+ */
+export function getAriaReferenceIds(el: Element, attr: string): string[] {
+  const idsValue = (el.getAttribute(attr) || '').trim();


attributeValue?

Since you're matching all non-whitespace, do you need the trim?

jelbourn · 2017-08-09T16:27:09Z

src/cdk/a11y/aria-reference.ts

+  const idsValue = (el.getAttribute(attr) || '').trim();
+
+  // Get string array of all individual ids (whitespace deliminated) in the attribute value
+  const idsArray = idsValue.match(/\S+/g) || [];


Just ids?

Since you're matching all non-whitespace, do you need the map to trim?

jelbourn · 2017-08-09T16:30:42Z

src/cdk/a11y/aria-reference.ts

+ */
+export function removeAriaReferencedId(el: Element, attr: string, id: string) {
+  const ids = getAriaReferenceIds(el, attr);
+  const filteredIds = ids.filter(val => val != id.trim());


How would you end up with an empty string here since getAriaReferenceIds only targets non-whitespace?

Looks like this needed to be revisited based on the regex, before the single space deliminator didn't trim up as much as I liked. The regex approach works much nicer

jelbourn · 2017-08-09T16:33:00Z

src/cdk/a11y/aria-reference.spec.ts

+   */
+  function expectIds(ids: string[]) {
+    expect(getAriaReferenceIds(testElement!, 'aria-describedby')).toEqual(ids);
+    expect(testElement!.getAttribute('aria-describedby')).toBe(ids.length ? ids.join(' ') : '');


This is a bit too much logic in the test for my taste. I'd generally prefer to have the assertion on aria-describedby to be hard-coded into each test

Changed it around a bit, kept expectIds but takes in an attr. Removed the helper functions for adding/removing the references

jelbourn · 2017-08-09T16:34:37Z

src/cdk/a11y/aria-describer.ts

+ * @docs-private
+ */
+@Injectable()
+export class AriaDescriber {


Need to add a provider for AriaDescriber similar to LIVE_ANNOUNCER_PROVIDER
(provides the existing instances if there is one)

jelbourn · 2017-08-09T16:35:36Z

src/cdk/a11y/aria-describer.ts

+}
+
+function removeCdkDescribedByReferenceIds(element: Element) {
+  // Remove all aria-describedby reference IDs that are prefixed by CDK_DESCRIBEDBY_ID_PREFIX


Make this a function description?

jelbourn · 2017-08-09T16:36:53Z

src/lib/tooltip/tooltip.ts

+    }
+
+    // If the message is not a string (e.g. number), convert it to a string and trim it.
+    this._message = value ? `${value}`.trim() : '';


Just `${value}`.trim() ?

Wouldn't that end up with the string undefined if value === undefined?

As mentioned by @crisbeto, an undefined message will evaluate `${value}`.trim() as 'undefined'

Ah, right; that's why my original comment was `${value || ''}`.trim()

crisbeto

LGTM

crisbeto · 2017-08-09T17:10:16Z

src/lib/tooltip/tooltip.ts

+    }
+
+    // If the message is not a string (e.g. number), convert it to a string and trim it.
+    this._message = value ? `${value}`.trim() : '';


Wouldn't that end up with the string undefined if value === undefined?

andrewseguin · 2017-08-09T18:33:18Z

Phew, ready found another round

jelbourn

LGTM

kara · 2017-08-21T20:13:19Z

@andrewseguin Rebase?

jelbourn · 2017-09-01T01:27:43Z

@andrewseguin this is failing the prerender task

andrewseguin · 2017-09-06T17:57:08Z

Fixed prerender (the aria describer's ngOnDestroy was referencing the document). Added a11y docs for review as well @tinayuangao

* checkin * changes * a11y(tooltip): add message element for tooltip a11y * comments * remove extra line * add test for tooltip message as number * remove fit * use renderer * always decrement * add aria-describer * add test * tests * md to cdk * Add aria-hidden to container * fix aot * comments * comments * rebase * fix prerender; add a11y docs

angular-automatic-lock-bot · 2019-09-07T20:02:44Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

andrewseguin requested review from jelbourn and crisbeto July 31, 2017 17:57

googlebot added the cla: yes PR author has agreed to Google's Contributor License Agreement label Jul 31, 2017

crisbeto reviewed Jul 31, 2017

View reviewed changes

jelbourn reviewed Jul 31, 2017

View reviewed changes

andrewseguin requested a review from devversion as a code owner August 7, 2017 18:36

andrewseguin force-pushed the tooltip-a11y branch from a775fbe to 70434a3 Compare August 7, 2017 18:43

andrewseguin changed the title ~~a11y(tooltip): add message element for screenreaders~~ a11y: add service to add aria-describedby labels Aug 7, 2017

jelbourn reviewed Aug 8, 2017

View reviewed changes

mmalerba reviewed Aug 8, 2017

View reviewed changes

crisbeto reviewed Aug 8, 2017

View reviewed changes

jelbourn reviewed Aug 9, 2017

View reviewed changes

crisbeto approved these changes Aug 9, 2017

View reviewed changes

andrewseguin force-pushed the tooltip-a11y branch from 1574fbb to bc3ab5b Compare August 9, 2017 18:32

jelbourn approved these changes Aug 9, 2017

View reviewed changes

jelbourn added pr: lgtm action: merge The PR is ready for merge by the caretaker labels Aug 9, 2017

andrewseguin added the pr: needs rebase label Aug 14, 2017

andrewseguin force-pushed the tooltip-a11y branch from bc3ab5b to e709bb6 Compare August 14, 2017 01:19

andrewseguin removed the pr: needs rebase label Aug 14, 2017

kara added pr: needs rebase and removed action: merge The PR is ready for merge by the caretaker labels Aug 21, 2017

kara assigned andrewseguin Aug 21, 2017

andrewseguin added 2 commits August 28, 2017 10:04

checkin

da10928

changes

a965a1e

andrewseguin added 14 commits August 28, 2017 10:05

remove extra line

0bfd0ee

add test for tooltip message as number

d55b78b

remove fit

b7e8e10

use renderer

c7308df

always decrement

fe0756e

add aria-describer

6e6f18b

add test

6d8c7f2

tests

7a928b5

md to cdk

92e2b66

Add aria-hidden to container

3f90703

fix aot

a98066d

comments

3bb5435

comments

31a86d1

rebase

0b63906

andrewseguin force-pushed the tooltip-a11y branch from e709bb6 to 0b63906 Compare August 28, 2017 17:16

andrewseguin added action: merge The PR is ready for merge by the caretaker and removed pr: needs rebase labels Aug 28, 2017

jelbourn removed the action: merge The PR is ready for merge by the caretaker label Sep 1, 2017

andrewseguin added action: merge The PR is ready for merge by the caretaker and removed action: merge The PR is ready for merge by the caretaker labels Sep 6, 2017

fix prerender; add a11y docs

2df1f71

andrewseguin added the action: merge The PR is ready for merge by the caretaker label Sep 6, 2017

andrewseguin requested a review from tinayuangao September 6, 2017 17:56

mmalerba merged commit 3be4da6 into angular:master Sep 11, 2017

andrewseguin deleted the tooltip-a11y branch November 28, 2017 20:40

angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 7, 2019

a11y: add service to add aria-describedby labels #6168

a11y: add service to add aria-describedby labels #6168

Uh oh!

Conversation

andrewseguin commented Jul 31, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andrewseguin commented Jul 31, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andrewseguin commented Aug 7, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andrewseguin Aug 8, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

andrewseguin commented Jul 31, 2017 •

edited

Loading

andrewseguin Aug 8, 2017 •

edited

Loading