Default semantic properties for Custom Elements

1. Defining custom element semantics

1.1. Introduction

This section is non-normative.

Authors may potentially provide semantics for custom elements in two ways:

as part of the custom element definition
via an object provided to each instance of the custom element.

1.1.1. Defining custom element semantics as part of the custom element definition

Authors may provide immutable default semantics for a custom element by setting properties via the ElementDefinitionOptions object passed in to the CustomElementRegistry.define() method.

The properties set on the ElementDefinitionOptions object become the default values to be used when mapping the custom element to an accessible object.

Note: this is analogous to creating an "immutable class variable" - these semantic properties are associated with the custom element definition, not with each custom element instance. The semantics they define apply to all instances of the custom element.

For example, an author creating a custom tab control may define three custom elements for the individual tabs, the tab list and the tab panel:

class TabListElement extends HTMLElement { ... }
customElements.define("custom-tablist", TabListElement,
                      { role: "tablist", ariaOrientation: "horizontal" });

class TabElement extends HTMLElement { ... }
customElements.define("custom-tab", TabElement,
                      { role: "tab" });

class TabPanelElement extends HTMLElement { ... }
customElements.define("custom-tabpanel", TabPanelElement,
                      { role: "tabpanel" });

When a <custom-tab> element is mapped into the accessibility tree, by default it will have a mapped role of tab.

This is analogous to how a <button> element is, by default, mapped to an accessible object with a role of button.

1.1.2. Defining per-instance custom element semantics

Note: see Web Components issue #758 for up to date information on ElementInternals.

A custom element author may use the ElementInternals object, created via createInternals(), to modify the semantic state of an instance of a custom element in response to user interaction.

The properties set on the ElementInternals object are used when mapping the element to an accessible object.

Note: this is analogous to setting an "instance variable" - a copy of these semantic properties is created for each instance of the custom element. The semantics defined in each apply only to their associated custom element instance object.

For example, the author creating the <custom-tab> and related elements may use the ElementInternals object to modify the semantic details for the elements as they change in response to user interaction.

class CustomTab extends HTMLElement {
  #internals = null;
  #tablist = null;
  #tabpanel = null;

  constructor() {
    super();
    this.#internals = customElements.createInternals(this);
    this.#internals.role = "tab";
  }

  // Observe the custom "active" attribute.
  static get observedAttributes() { return ["active"]; }

  connectedCallback() {
    this.#tablist = this.parentElement;
  }

  setTabPanel(tabpanel) {
    if (tabpanel.localName !== "custom-tabpanel" || tabPanel.id === "")
      return;  // fail silently

    this.#tabpanel = tabpanel;
    tabpanel.setTab(this);
    this.#internals.ariaControls = tabPanel;    // does not reflect
  }

  // ... setters/getters for custom properties which reflect to attributes

  attributeChangedCallback(name, oldValue, newValue) {
    switch(name) {
      case "active":
        let active = (newValue != null);
        this.#tabpanel.shown = active;

        // When the custom "active" attribute changes,
        // keep the accessible "selected" state in sync.
        this.#internals.ariaSelected = (newValue !== null);

        if (selected)
          this.#tablist.setSelectedTab(this);  // ensure no other tab has "active" set
        break;
    }
  }
}

customElements.define("custom-tab", CustomTab, { role: "tab", needsElementInternals: true });

Authors using these elements may override the default semantics using ARIA attributes as normal - see §2 ARIA semantic precedence between ElementDefinitionOptions, ElementInternals and ARIA properties.

For example, an author may modify the appearance of a <custom-tablist> element to appear as a vertical list. They could add an aria-orientation attribute to indicate this, overriding the default semantics set in the custom element definition.

<custom-tablist aria-orientation="vertical" class="vertical-tablist">
  <custom-tab selected>Tab 1</custom-tab>
  <custom-tab>Tab 2</custom-tab>
  <custom-tab>Tab 3</custom-tab>
</div>

Because the author-provided role overrides the default role, the mapped role will be based on the author-provided role in each case.

1.2. Changes to custom element definition

This section represents changes which should be made to HTML Standard §custom-elements-core-concepts, HTML Standard §custom-element-definition, HTML Standard §custom-elements-api, HTML Standard §element-definition, HTML Standard §upgrades and HTML Standard §custom-element-reactions.

[...]

A custom element may have semantics defined when the custom element is defined. Otherwise, an autonomous custom element does not have any special meaning: it represents its children. A customized built-in element inherits the semantics of the element that it extends.

[...]

A custom element definition [includes]:

A set of default values for semantic properties (optional): A map, whose keys are each an attribute in either the AccessibilityRole or AriaAttributes interface mixin. The corresponding values are DOMString.

[...]

// Existing IDL
/*
[Exposed=Window]
interface CustomElementRegistry {
  [CEReactions] void define(DOMString name, CustomElementConstructor constructor, optional ElementDefinitionOptions options);
  // ...
};

dictionary ElementDefinitionOptions {
  DOMString extends;
};
*/
ElementDefinitionOptions includes AccessibilityRole;
ElementDefinitionOptions includes AriaAttributes;

dictionary ElementInternals {};

ElementInternals includes AccessibilityRole;
ElementInternals includes AriaAttributes;

Element definition is a process of adding a custom element definition to the CustomElementRegistry. This is accomplished by the define() method. When invoked, the define(name, constructor, options) method must run these steps:

[...]

Run the following substeps:
1. Let semantics be an empty map.
2. For each key defined in AccessibilityRole and AriaAttributes:
  1. If the key exists in options, add an entry to semantics with that key and the value provided in options.
3. If semantics is empty, set it to null.
Let definition be a new custom element definition with name name, local name local name, constructor constructor, observed attributes observedAttributes, lifecycle callbacks lifecycleCallbacks, and, if semantics is non-null, semantic properties semantics.
Add definition to this CustomElementRegistry.

[...]

2. ARIA semantic precedence between `ElementDefinitionOptions`, `ElementInternals` and ARIA properties

2.1. Introduction

This section is non-normative

In general, the precedence of semantic properties is that any ARIA property set directly on the Element (either via setting an attribute or via the associated reflected property) overrides a value for the same property on the Element's ElementInternals object, and any ARIA property set either on the Element or the ElementInternals object will override a value set via the CustomElementRegistry.define() method.

Suppose an author had created a custom checkbox element:

class CustomCheckbox extends HTMLElement { /* ... */ }
customElements.define("custom-checkbox", CustomCheckbox,
                      { role: "checkbox", ariaChecked: "false" });

An author using a <custom-checkbox> element could use the reflected ARIA properties/content attributes to override the default values, just as they would when using a native element:

<-- ARIA role overrides implicit role -->
<input type="checkbox" role="radio">

<-- ARIA role overrides custom element role -->
<custom-checkbox role="radio">

In the implementation of the <custom-tab> element, if the author explicitly defined the default value for ariaSelected in the custom element definition, then the value set on the ElementInternals object in the attributeChangedCallback() method would override that default value:

class TabElement extends HTMLElement {
  // ... many details omitted

  // When the custom "active" attribute changes,
  // keep the accessible checked state in sync.
  attributeChangedCallback(name, oldValue, newValue) {
    switch(name) {
      case "active":
        let selected = (newValue != null);
        this.#tabpanel.shown = selected;

        // Note: overrides value set in custom element definition.
        this.#internals.ariaSelected = selected;

        // ensure no other tab has "selected" set
        if (selected)
          this.#tablist.setSelectedTab(this);
        break;
    }
  }
}

// ariaSelected value defined here is overridden in attributeChanged callback
customElements.define("custom-tab", CustomTab,
                      { role: "tab", ariaSelected: "false" });

Then authors using the <custom-tablist> and <custom-tab> elements as a listbox could still override any semantic properties, including those set on the ElementInternals object, but no semantic implementation details would leak out:

<custom-tablist aria-orientation="vertical">
  <-- You would probably never want to do this, but it would work -->
  <custom-tab selected aria-selected="false">Option 1</custom-tab>
  <custom-tab>Option 2</custom-tab>
  <custom-tab>Option 3</custom-tab>
</custom-tablist>

2.2. Mapping semantics to the accessibility tree

This section represents changes which should be made to [[html-aam-1.0#mapping-html-to-accessibility-apis]].

2.2.1. Rules for exposing semantics of custom elements

If an element is custom, for each key in the element’s ElementInternals object, the associated value must be mapped to accessibility APIs as if they were a property set on the element.

If the element’s custom element definition includes semantics, the value of each property in semantics must be mapped to accessibility APIs as if they were set on the element, unless there is a conflicting value for the same property in the element’s ElementInternals object, or in a property set on the element.

Default semantic properties for Custom Elements

Unofficial Proposal Draft, 25 October 2018

Abstract

Status of this document

1. Defining custom element semantics

1.1. Introduction

1.1.1. Defining custom element semantics as part of the custom element definition

1.1.2. Defining per-instance custom element semantics

1.2. Changes to custom element definition

2. ARIA semantic precedence between `ElementDefinitionOptions`, `ElementInternals` and ARIA properties

2.1. Introduction

2.2. Mapping semantics to the accessibility tree

2.2.1. Rules for exposing semantics of custom elements

Conformance

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

Informative References

IDL Index

Default semantic properties for Custom Elements

Unofficial Proposal Draft, 25 October 2018

Abstract

Status of this document

1. Defining custom element semantics

1.1. Introduction

1.1.1. Defining custom element semantics as part of the custom element definition

1.1.2. Defining per-instance custom element semantics

1.2. Changes to custom element definition

2. ARIA semantic precedence between ElementDefinitionOptions, ElementInternals and ARIA properties

2.1. Introduction

2.2. Mapping semantics to the accessibility tree

2.2.1. Rules for exposing semantics of custom elements

Conformance

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

Informative References

IDL Index

2. ARIA semantic precedence between `ElementDefinitionOptions`, `ElementInternals` and ARIA properties