From 54cc3eed1d55ace387cf236df22f063c24e4992d Mon Sep 17 00:00:00 2001 From: Michael Prentice Date: Sat, 6 Mar 2021 23:18:22 -0500 Subject: [PATCH] docs(cdk/a11y): fix overview table of contents - while the guides were updated to support a wider set of headers, component docs are still limited to h3 and h4 in the TOC - this fixes a regression to these docs introduced in v6 Fixes #22133 --- src/cdk/a11y/a11y.md | 61 +++++++++++++++++---------- src/cdk/a11y/focus-trap/focus-trap.md | 2 + 2 files changed, 41 insertions(+), 22 deletions(-) diff --git a/src/cdk/a11y/a11y.md b/src/cdk/a11y/a11y.md index c2893b95850b..015484b4c8fa 100644 --- a/src/cdk/a11y/a11y.md +++ b/src/cdk/a11y/a11y.md @@ -1,10 +1,12 @@ The `a11y` package provides a number of tools to improve accessibility, described below. -## ListKeyManager +### ListKeyManager + `ListKeyManager` manages the active option in a list of items based on keyboard interaction. Intended to be used with components that correspond to a `role="menu"` or `role="listbox"` pattern. -### Basic usage +#### Basic usage + Any component that uses a `ListKeyManager` will generally do three things: * Create a `@ViewChildren` query for the options being managed. * Initialize the `ListKeyManager`, passing in the options. @@ -18,16 +20,19 @@ interface ListKeyManagerOption { } ``` -### Wrapping +#### Wrapping + Navigation through options can be made to wrap via the `withWrap` method ```ts this.keyManager = new FocusKeyManager(...).withWrap(); ``` -### Types of key managers +#### Types of key managers + There are two varieties of `ListKeyManager`, `FocusKeyManager` and `ActiveDescendantKeyManager`. -#### FocusKeyManager +##### FocusKeyManager + Used when options will directly receive browser focus. Each item managed must implement the `FocusableOption` interface: ```ts @@ -36,7 +41,8 @@ interface FocusableOption extends ListKeyManagerOption { } ``` -#### ActiveDescendantKeyManager +##### ActiveDescendantKeyManager + Used when options will be marked as active via `aria-activedescendant`. Each item managed must implement the `Highlightable` interface: @@ -50,7 +56,8 @@ interface Highlightable extends ListKeyManagerOption { Each item must also have an ID bound to the listbox's or menu's `aria-activedescendant`. -## FocusTrap +### FocusTrap + The `cdkTrapFocus` directive traps Tab key focus within an element. This is intended to be used to create accessible experience for components like [modal dialogs](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal), where focus must be @@ -58,7 +65,8 @@ constrained. This directive is declared in `A11yModule`. -### Example +#### Example + ```html
@@ -68,7 +76,8 @@ This directive is declared in `A11yModule`. This directive will not prevent focus from moving out of the trapped region due to mouse interaction. -### Regions +#### Regions + Regions can be declared explicitly with an initial focus element by using the `cdkFocusRegionStart`, `cdkFocusRegionEnd` and `cdkFocusInitial` DOM attributes. `cdkFocusInitial` specifies the element that will receive focus upon initialization of the region. @@ -88,18 +97,21 @@ For example: will happen unless you've enabled the `cdkTrapFocusAutoCapture` option as well. This is due to `CdkTrapFocus` not capturing focus on initialization by default. -## InteractivityChecker +### InteractivityChecker + `InteractivityChecker` is used to check the interactivity of an element, capturing disabled, visible, tabbable, and focusable states for accessibility purposes. See the API docs for more details. -## LiveAnnouncer +### LiveAnnouncer + `LiveAnnouncer` is used to announce messages for screen-reader users using an `aria-live` region. See [the W3C's WAI-ARIA](https://www.w3.org/WAI/PF/aria-1.1/states_and_properties#aria-live) for more information on aria-live regions. -### Example +#### Example + ```ts @Component({...}) export class MyComponent { @@ -110,10 +122,11 @@ export class MyComponent { } ``` -## FocusMonitor +### FocusMonitor + The `FocusMonitor` is an injectable service that can be used to listen for changes in the focus state of an element. It's more powerful than just listening for `focus` or `blur` events because it -tells you how the element was focused (via mouse, keyboard, touch, or programmatically). It also +tells you how the element was focused (via the mouse, keyboard, touch, or programmatically). It also allows listening for focus on descendant elements if desired. To listen for focus changes on an element, use the `monitor` method which takes an element to @@ -133,7 +146,7 @@ to the element when focused. It will add `.cdk-focused` if the element is focuse add `.cdk-${origin}-focused` (with `${origin}` being `mouse`, `keyboard`, `touch`, or `program`) to indicate how the element was focused. -Note: currently the `FocusMonitor` emits on the observable _outside_ of the Angular zone. Therefore +Note: currently the `FocusMonitor` emits on the observable _outside_ of the Angular zone. Therefore, if you `markForCheck` in the subscription you must put yourself back in the Angular zone. ```ts @@ -148,12 +161,13 @@ Any element that is monitored by calling `monitor` should eventually be unmonito It is possible to falsify the `FocusOrigin` when setting the focus programmatically by using the `focusVia` method of `FocusMonitor`. This method accepts an element to focus and the `FocusOrigin` to use. If the element being focused is currently being monitored by the `FocusMonitor` it will -report the `FocusOrigin` that was passed in. If the element is not currently being monitored it will -just be focused like normal. +report the `FocusOrigin` that was passed in. If the element is not currently being monitored, it +will just be focused like normal. -### cdkMonitorElementFocus and cdkMonitorSubtreeFocus +#### cdkMonitorElementFocus and cdkMonitorSubtreeFocus + For convenience, the CDK also provides two directives that allow for easily monitoring an element. `cdkMonitorElementFocus` is the equivalent of calling `monitor` on the host element with `checkChildren` set to `false`. `cdkMonitorSubtreeFocus` is the equivalent of calling `monitor` on @@ -162,7 +176,8 @@ the host element with `checkChildren` set to `true`. Each of these directives ha -## Styling utilities +### Styling utilities + The CDK `a11y` package comes with a set of CSS styles that can be used when building accessible components. To take advantage of them, you have to include the styles in your global stylesheet. If you're using Material together with the CDK, these styles have been included for you already. @@ -173,9 +188,10 @@ If you're using Material together with the CDK, these styles have been included @include cdk-a11y(); ``` -### Hiding elements, while keeping them available for screen readers +#### Hiding elements in an accessible way + By default, screen readers and other assistive technology will skip elements that have -`display: none`, `visibility: hidden` etc. In some cases you may need to visually hide an element, +`display: none`, `visibility: hidden`, etc. In some cases you may need to visually hide an element, while keeping it available for assistive technology. You can do so using the `cdk-visually-hidden` class: @@ -185,7 +201,8 @@ class:
``` -### Targeting high contrast users +#### Targeting high contrast users + The `a11y` package offers a mixin that allows you to target users that have the Windows high contrast mode turned on. To target high contrast users, you can wrap your styles with the `cdk-high-contrast` mixin. The mixin works by targeting a CSS class which is added to the `body` diff --git a/src/cdk/a11y/focus-trap/focus-trap.md b/src/cdk/a11y/focus-trap/focus-trap.md index 67eb774e2c6e..6d7784fc2cb7 100644 --- a/src/cdk/a11y/focus-trap/focus-trap.md +++ b/src/cdk/a11y/focus-trap/focus-trap.md @@ -1,4 +1,5 @@ ### FocusTrap + The `cdkTrapFocus` directive traps Tab key focus within an element. This is intended to be used to create accessible experience for components like [modal dialogs](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal), where focus must be @@ -7,6 +8,7 @@ constrained. This directive is declared in `A11yModule`. #### Example + ```html