Skip to content

Latest commit

 

History

History
98 lines (61 loc) · 4.78 KB

disabled.md

File metadata and controls

98 lines (61 loc) · 4.78 KB
Raw
layout tags
doc-api.html
shadow-dom, service, argument-options

ally.maintain.disabled

Disables any type of user interaction - including the ability to focus elements - essentially rendering elements inert.

Description

This allows an application to make sure no element other than the exempted can be focused. This is method is superior to the idea of trapping focus by intercepting Tab, because it allows cycling through the browser UI and is not as prone to break for spatial focus navigation (i.e. any sort of focus navigation that does not use the Tab key). The major benefit of disabling focus of elements is that in turn we do not have to meddle with the user's interaction to actually change focus - we can leave that to the browser.

Elements are disabled by ally.element.disabled and can be identified in the DOM by the attribute [data-ally-disabled="true"] to align with styling of other :disabled elements.

ally.maintain.disabled observes DOM manipulations and automatically disables newly added elements when necessary.

The proposed inert attribute was removed from HTML5, because people thought inert subtrees by way of the <dialog> element would suffice. While we believe it doesn't, the inert attribute would only have solved half of the problem, because there's no way to avoid inheriting the inert state onto children. This behavior can be observed in the Google Chrome Inert Attribute Polyfill.

:::note The WICG (Web Incubater Community Group) is working on reviving the inert attribute (including a polyfill). :::

:::note The WHATWG is discussing a blockElements API that would cover the primary use-case of ally.maintain.disabled in a much better way. :::

Usage

var handle = ally.maintain.disabled({
  context: '.within-filter-selector',
  filter: '.except-filter-selector',
});

handle.disengage();

Arguments

Name Type Default Description
context <selector> documentElement The scope of the DOM in which to search. The first element of a collection is used.
filter <selector> null The significant elements to exclude from being disabled.

Returns

A <service> interface, providing the handle.disengage() method to stop the service.

Throws

Examples

@@@example /api/maintain/disabled.example.html

disabled example

@@@

Changes

  • Since v1.1.0 changing tabindex attribute values are properly handled.
  • Since v1.1.0 the disengage() method reverts elements within ShadowHosts to their previous state.
  • Since v1.1.0 DOM mutations within ShadowRoots are properly observed.
  • Since v1.1.0 initially disabled elements are not accidentally enabled when disengaging the service.
  • Since v1.1.1 ancestors of exempted sub-trees (defined by filter option) are not disabled anymore.

Notes

:::note ShadowHosts are pierced and ShadowRoot content is made inert as well (except for closed shadow trees). :::

:::note Internet Explorer 10 will not update changes made to elements within the inert sub-trees, because it does not support MutationObserver and Mutation Events are too much of a burden. :::

:::warning Any element not identified as focus relevant by ally.is.focusRelevant and not identified as only tabbable by ally.is.onlyTabbable is not made inert either. See the identified elements using strategy: "strict" compatibility table. :::

Related resources

Contributing