Forem: Lee White

Accessibility for Web Components

Lee White — Mon, 03 Aug 2020 19:38:13 +0000

Accessibility Concerns

In part one, we covered what web components are and how to build one. Now, we can look at how this new technology currently affects accessibility. It is important to note that these considerations are for web components and extend to Lightning Web Components as well.

Direct Descendancy

In HTML, you can define what an element is with a role (see: the ARIA Roles Model). This helps give users context on how to interact with the element.

There are explicit roles, which can be set with the role attribute. In this example, the <div> has role=”alert” so assistive technologies (AT) know to read it immediately when it appears on the page.

<div role="alert">
  This is an alert!
</div>

There are also implicit roles (see: complete list of implicit roles). Some HTML elements don’t need the role attribute because it is already understood to have a role, like <ul> and <li> elements.

<ul> is implied to have role=”list”, and <li> has role=”listitem”. Browsers and AT know how to announce these based on this common understanding of what these elements are.

<ul>  // implied role="list"
  <li>content</li> // implied role="listitem"`
  ...
</ul>

The roles, however, can be brittle. If an element with an implicit role is not the direct child of the correct element, the browser may not understand the relationship between these elements anymore.

<ul>  // implied role="list"
  <li>content</li>  // implied role="listitem"
  ...
</ul>

Now, the <li> elements in the <ul> are inside of a custom list item component. Browsers will no longer recognize this as a list with X number of items. Instead, it sees a list whose children have role=”presentation” (which means ‘no role’).

To fix this, you need to add the explicit roles instead. I have switched my list to use a <div> with role=”list”. For the list items, I can either make the inner HTML of my component a <div> with role=”listitem” or just add role=”listitem” to the custom element. Now that the roles are explicit, the browser understands the list and AT will read it correctly.

<div role="list">
  <custom-list-item>
    <div role="listitem"<content>/div>
  </custom-list-item>
  ...
</div>

// OR
<div role="list">
  <custom-list-item role="listitem">
    content
  </custom-list-item>
  ...
</div>

Global HTML attributes and properties on custom elements

When you are making a custom element, what properties and attributes do is not implemented by default.

If you set a global HTML attribute or property on your custom element and don’t add the proper Javascript, it will stay on the custom element unless otherwise specified. If the attribute is meant to be on the custom element, this is fine, but if the attribute needs to be passed to a child of the custom element things get more complicated.

It is definitely not recommended to pass information to a child element with a global attribute or property name, but if for some reason it is required it needs the following to work:

A setter function that takes the value from the custom element and puts it on the correct element.
A getter function that returns the value from the correct element (not the one passed to the custom element)
A function that checks if the value is on the custom element and removes it so that the browser isn’t confused.

This can be a lot to maintain because you will need to constantly be sure that the value doesn’t exist on both the custom element and the child element.

Using the customButton example, if I were to pass the aria-pressed value like this:

<custom-button aria-pressed="true"></custom-button>

It would not work because the attribute would stay on the custom element, which has role=”presentation”, and not go to the actual button. The browser and assistive technology know what aria-pressed does on an element with role=”presentation”.

So, when a developer puts (or updates) aria-pressed on the customButton, the component needs to take the attribute off the custom-button tag and put it on the button inside instead.

// in the HTML 
<custom-button aria-pressed="true"></custom-button>
// rendered in the browser
<custom-button>
  <button aria-pressed="true"> // contents of button </button>
</custom-button>

This is not an ideal way to code because it seems redundant to continually check if the attribute is in both places and is prone to regressions. It is simpler to call the attribute on custom element something else that won’t be confused for a global attribute and pass that value to the child element.

ID referencing + Shadow DOM

ID referencing is critical for accessibility. Many HTML attributes (aria-labelledby, aria-describedby, aria-controls, etc.) take an ID to another element to establish a connection between the two. Developers also use DOM queries to set focus with document.getElementById.

When you can’t

If there is a shadow boundary, even if it’s open, referencing IDs from outside the component is impossible because the web component’s DOM is separate.

Let’s say I have a custom-input component with a unique ID and I try to associate it with a label in that label’s HTML for attribute, like this:

<label for="my-input">City</label>
<custom-input>
  #shadow-root (open)
    <input id="my-input" type="text" />
</custom-input>

It will not work because when it is rendered, the input is in a separate DOM tree from the label, which means the browser can no longer link them together.

<label for={NOT A REF}>City</label>
<custom-input>
  #shadow-root (open)
    <input id={NOT A REF} type="text" />
</custom-input>

If there are any attributes that require IDs, they need to be within the same shadow boundary. So, for this custom-input example, I would pass a label attribute to the component instead of having it outside:

<custom-input label="City">
  #shadow-root (open)
    <label for="my-input">City</label>
    <input id="my-input" type="text" />
</custom-input>

When you can

If your component has a slot that is inside of the shadow boundary, it might seem like you cannot reference IDs within the slot, but you actually can! This is because the contents of slots are actually in the light DOM, not the component’s shadow DOM (even if the slot is within the shadow boundary!).

This is the form-element-container wrapper component that I can pass an input to, it standardizes the CSS for each of my form elements. In this component, the input element goes into a slot and I leave the label outside the component.

<label for="another-input">Country</label>
<form-element-container>
  <input id="another-input" type="text" slot="input-slot"/>
</form-element-container>

The browser will display the DOM like this:

<label for="another-input">Country</label>
<form-element-container>
  #shadow-root (open)
    <slot name="input-slot">
      #input
    </slot>
  <input id="another-input" type="text" />
</form-element-container>

The main drawback to the slots is that since they are in the light DOM, all styles and JavaScript on the page will affect the content in the slots so you can’t expect them to look or behave the same everywhere.

tabindex=”-1” and Custom Elements

tabindex=”-1” is a great tool! It is used to make something focusable and clickable, but not in the tab order. An example use case for it could be a toast: when the toast appears, you can focus the whole thing and then a user can tab to the close button.

Currently, if you put tabindex=”-1” on a custom element with shadow DOM enabled, it makes all of the child elements non-tabbable. This is unexpected, since tabindex usually does not propagate, and makes it so only people using a mouse can click the elements. So, for the toast example: if the toast is a custom element, putting tabindex=”-1” will prevent users from ever being able to tab to the close button within the toast container.

The way around this is to be careful about what elements you put tabindex=”-1” on and to be sure to architect your component so that it will never need to be on the custom element itself.

Accessibility Object Model

The Accessibility Object Model (AOM) project will theoretically fix the current accessibility issues with web components. The project is currently being developed, but there is no timeline on when it will be officially released and working on all browsers.

What the AOM project aims to do is make all the attributes properties, so that developers can directly manipulate the browser’s accessibility tree with JavaScript. This would fix the issues related to shadow DOM, direct descendancy, and id referencing.

So instead of doing:

<div id="weird-label">Very weird button</div>
<div role="button" tabindex="0" aria-labelledby="weird-label"></div>

You could add all of that with Javascript instead and not have to worry about shadow boundaries.

// HTML
<div id="weird-label">Very weird button</div>
<div role="button" tabindex="0" aria-labelledby="weird-label"></div>

// JavaScript
let weirdButton = document.getElementbyId('weird-button');
weirdButton.role = 'button';
weirdButton.tabIndex = 0;
weirdButton.ariaLabelledBy = document.getElementById('weird-label');

Conclusion

Given that the Accessibility Object Model is not finished or fully adopted by browsers, it is important to still make web components accessible built today. When you are architecting your new web components, be sure to include these considerations so everyone can use your components.

Resources

W3C: The Roles Model
W3C: List of all Implicit Roles
[GitHub Issue] ShadowDOM: tabindex=”-1” Makes Shadow Tree non-focusable
AOM Github Repository
AOM Browser Test (shows which AOM features your browser supports)
Web Components and the AOM by Léonie Watson

Intro to Web Components

Lee White — Thu, 11 Jun 2020 23:54:03 +0000

Web components are a new set of APIs built on web standards that are widely adopted by browsers (see browser support at webcomponents.org). They allow developers to make flexible custom components–but with that flexibility comes responsibility. In this two-part blog, we will outline what web components are and the specific accessibility considerations they have, so you can integrate web components into your own products with all users in mind. Stay tuned, we'll be publishing a second blog about accessibility for Web Components soon.

Web Components

Web components allow developers to make their own custom components with native HTML and JavaScript. They are built of three parts:

Custom elements
HTML templates
Shadow DOM

Salesforce’s Lightning Web Components (LWC) component framework is built on top of web components to make it easy to create fast, lightweight components. Let’s explore an example web component to see how we can best leverage them.

Custom Elements

This is the custom tag itself, which extends either an existing tag (like HTMLButton) or the base HTMLElement.

For my example component, I am going to extend the base HTML element. I have to define the custom element for the browser and connect it to the CustomButton class I made (live finished CustomButton).

class CustomButton extends HTMLElement {
  constructor() {
    super();
  }
}

window.customElements.define('custom-button', CustomButton);

Right now, I have this awesome new tag <custom-button></custom-button>, but it doesn’t have anything inside of it and it can’t do anything. There are a couple ways to build this component. I could add functionality directly to the custom tag, but in this example I will use HTML templates.

HTML Templates

There are two ways to create reusable snippets of HTML: <template> and <slot> elements.

Templates

Templates have display=”none” by default and can be referenced with JavaScript, which makes them good for HTML that will be reused in your component.

Looking at the CustomButton, using a template makes sense for now. I don’t need a lot of flexibility since it is just a button that developers can pass a custom string to.

To begin building my component, I add a template tag in the DOM (Document Object Model) and add a button inside of it. Then, in the constructor I append the contents of the template to the custom element itself.

let myTemplate = document.createElement('template');
myTemplate.innerHTML = `
  <button>
    <slot name="icon"></slot>
    <span>Default text</span>
  </button>
`;

class CustomButton extends HTMLElement {
  constructor() {
    super();
    let shadowRoot = this.attachShadow({ 'mode': 'open' });
    shadowRoot.appendChild(myTemplate.content.cloneNode(true));    
  }
}

window.customElements.define('custom-button', CustomButton);

My button template has a span inside of it with default text that the user can then replace by passing a string to the custom element with the text attribute.

I also added a connectedCallback function, which is a web component lifecycle function that happens when the component is connected to the DOM. In that function I set the innerText of the button to the value passed from the custom component.

I can use the CustomButton in my HTML like this:

<custom-button text="Click me!"></custom-button>

So now, if I use my CustomButton component, the browser DOM will look like this:

<custom-button text="Click me!">
  <button>Click me!</button>
</custom-button>

Slots

Slots allow flexibility, since they let you put anything within them. This is especially useful if you need to allow consumers of your component to add custom HTML. One thing to keep in mind is that slots require that shadow DOM is enabled to work correctly.

For my CustomButton component, people might want to add an icon – so I can use a slot! I update the contents of the template to be:

<button>
  <slot name="icon"></slot>
  <span>Default text</span>
</button>

Someone using my button can add any icon in their HTML:

<custom-button>
  <svg slot="icon" aria-hidden="true"> //nifty icon </svg>
</custom-button>

Which, if shadow DOM is enabled, the browser will render as:

<custom-button>
  #shadow-root
    <slot name="icon">
      #svg
    </slot>
    <span>Default text</span>
  <svg slot="icon" aria-hidden="true"> //nifty icon </svg>
</custom-button>

For more on the differences between the two, check out Mozilla’s article on templates and slots.

Since I have to use shadow DOM for the icon slot, the next step is to look into what the shadow DOM is and how it works.

Shadow DOM

Up until this point, when I talk about the DOM, it is the main DOM that the browser generates – which is also called the light DOM. If you view the page source of a site, you can see the light DOM, every HTML element on the page.

The shadow DOM is a scoped document object model tree that is only within your custom element. If shadow DOM is enabled in your component, the component’s elements are in a separate tree from the rest of the page.

No Shadow vs Open vs Closed

Web components don’t need to have shadow DOM enabled, but if it is enabled, it can either be open or closed.

If shadow DOM is not enabled: the component is in the main DOM. JavaScript and CSS on the page can affect the contents of the component.

<custom-button>
  <button>Default text</button>
</custom-button>

If the shadow DOM is open: the main DOM can’t access the sub tree in the traditional ways, but you can still access the sub tree with Element.shadowRoot. document.getElementById, other query selectors, and CSS from outside the component will not affect it.

<custom-button>
  #shadow-root (open)
   <button>Default text</button>
</custom-button>

If the shadow DOM is closed: the main DOM cannot access the elements inside of the component at all. JavaScript and CSS from outside the component will not affect it.

<custom-button>
  #shadow-root (closed)
    <button>Default text</button>
</custom-button>

There are very few instances where having a fully closed shadow is necessary and the current industry standard is to use open shadow.

To look at the source code for the CustomButton example, I enable the open shadow DOM like this:

let myTemplate = document.createElement('template');
myTemplate.innerHTML = `
  <button>
    <slot name="icon"></slot>
    <span>Default text</span>
  </button>
`;

class CustomButton extends HTMLElement {
  constructor() {
    super();
    let shadowRoot = this.attachShadow({ 'mode': 'open' });
    shadowRoot.appendChild(myTemplate.content.cloneNode(true));    
  }
}

window.customElements.define('custom-button', CustomButton);

The contents of the template are now added to the shadow root, not directly to the custom element.

Finishing the Custom Button

The HTML is the way I want it to be, so it is time to make the CustomButton interactive. When people click the button, I want to toggle the aria-pressed attribute so users know if it is pressed.

let myTemplate = document.createElement('template');
myTemplate.innerHTML = `
  <button>
    <slot name="icon"></slot>
    <span>Default text</span>
  </button>
`;

class CustomButton extends HTMLElement {
  constructor() {
    super();
    let shadowRoot = this.attachShadow({ 'mode': 'open' });
    shadowRoot.appendChild(myTemplate.content.cloneNode(true));

    this.button = this.shadowRoot.querySelector('button');
    this.handleClick = this.handleClick.bind(this);
    this.updateText = this.updateText.bind(this);
  }

  get ariaPressed() {
    const value = this.button.getAttribute('aria-pressed');
    return (value === 'true');
  }

  set ariaPressed(value) {
    this.button.setAttribute('aria-pressed', value);
  }

  connectedCallback() {
    this.button.addEventListener('click', this.handleClick);
    if (this.hasAttribute('text')) this.updateText();
  }

  handleClick() {
    this.ariaPressed = !this.ariaPressed;
  }

  updateText() {
    let buttonSpan = this.button.querySelector('span');
    buttonSpan.innerText = this.getAttribute('text');
  }
}

window.customElements.define('custom-button', CustomButton);

Live version

This is the final code for my CustomButton, I have added a couple functions:

get ariaPressed: returns the value of the aria-pressed attribute on the button inside the custom-button element
set ariaPressed: sets the value of the aria-pressed attribute on the button inside the custom-button element.
connectedCallback: adds an onClick listener when the component connects to the DOM.
handleClick: toggles the value of ariaPressed when the button is clicked

Now, I can add my custom button to my HTML like this:

<custom-button id="important-button" text="Click me!"></custom-button>

And I can programmatically set the ariaPressed property like this:

document.getElementById('important-button').ariaPressed = true;

Conclusion

We now have a button component with a property called ariaPressed that can be set with JavaScript. The component combines custom elements, HTML templates, and shadow DOM all with plain JavaScript and HTML, no frameworks required! In part two, I will cover the accessibility concerns related to web components.