@brightspace-ui/core 3.72.3 → 3.73.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (6) hide show
  1. package/components/backdrop/README.md +9 -2
  2. package/components/backdrop/backdrop.js +26 -7
  3. package/components/breadcrumbs/README.md +54 -58
  4. package/components/breadcrumbs/breadcrumb.js +2 -2
  5. package/custom-elements.json +5 -5
  6. package/package.json +1 -1
package/components/backdrop/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Backdrops
2
2
 
3
- The `d2l-backdrop` element is a web component to display a semi-transparent backdrop behind a specified sibling element. It also hides elements other than the target from assistive technologies by applying `role="presentation"` and `aria-hidden="true"`.
3
+ The `d2l-backdrop` element displays a semi-transparent backdrop behind a specified sibling target element. It also hides elements other than the target from assistive technologies by applying `aria-hidden="true"`.
4
4
 
5
5
  ## Backdrop [d2l-backdrop]
6
6
 
@@ -9,7 +9,6 @@ The `d2l-backdrop` element is a web component to display a semi-transparent back
9
9
  <script type="module">
10
10
  import '@brightspace-ui/core/components/button/button.js';
11
11
  import '@brightspace-ui/core/components/backdrop/backdrop.js';
12
- import '@brightspace-ui/core/components/switch/switch.js';
13
12
 
14
13
  const backdrop = document.querySelector('d2l-backdrop');
15
14
  document.querySelector('#target > d2l-button').addEventListener('click', () => {
@@ -36,3 +35,11 @@ The `d2l-backdrop` element is a web component to display a semi-transparent back
36
35
  | `shown` | Boolean | Used to control whether the backdrop is shown |
37
36
  | `slow-transition` | Boolean | Increases the fade transition time to 1200ms (default is 200ms) |
38
37
  <!-- docs: end hidden content -->
38
+
39
+ ### Focus Management
40
+
41
+ Elements with `aria-hidden` applied (as well as their descendants) are completely hidden from assistive technologies. It's therefore very important that the element with active focus be within the backdrop target.
42
+
43
+ **When showing a backdrop**: first move focus inside the target, then set the `shown` attribute on the backdrop.
44
+
45
+ **When hiding a backdrop**: first remove the `shown` attribute on the backdrop, then if appropriate move focus outside the target.
package/components/backdrop/backdrop.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import '../colors/colors.js';
2
2
  import { css, html, LitElement } from 'lit';
3
- import { cssEscape, getComposedChildren, getComposedParent, isVisible } from '../../helpers/dom.js';
3
+ import { cssEscape, getComposedChildren, getComposedParent, isComposedAncestor, isVisible } from '../../helpers/dom.js';
4
+ import { getComposedActiveElement } from '../../helpers/focus.js';
4
5
 
5
6
  const BACKDROP_HIDDEN = 'data-d2l-backdrop-hidden';
6
7
  const BACKDROP_ARIA_HIDDEN = 'data-d2l-backdrop-aria-hidden';
@@ -12,7 +13,7 @@ const modals = new Set();
12
13
  let scrollOverflow = null;
13
14
 
14
15
  /**
15
- * A component for displaying a semi-transparent backdrop behind a specified sibling element. It also hides elements other than the target from assistive technologies by applying 'role="presentation"' and 'aria-hidden="true"'.
16
+ * A component for displaying a semi-transparent backdrop behind a specified sibling element. It also hides elements other than the target from assistive technologies by applying 'aria-hidden="true"'.
16
17
  */
17
18
  class Backdrop extends LitElement {
18
19
 
@@ -85,10 +86,8 @@ class Backdrop extends LitElement {
85
86
  disconnectedCallback() {
86
87
  // allow body scrolling, show hidden elements, if backdrop is removed from the DOM
87
88
  allowBodyScroll(this);
88
- if (this._hiddenElements) {
89
- showAccessible(this._hiddenElements);
90
- this._hiddenElements = null;
91
- }
89
+ showAccessible(this._hiddenElements);
90
+ this._hiddenElements = null;
92
91
  this._state = null;
93
92
  super.disconnectedCallback();
94
93
  }
@@ -106,7 +105,12 @@ class Backdrop extends LitElement {
106
105
 
107
106
  if (this._state === null) {
108
107
  preventBodyScroll(this);
109
- this._hiddenElements = hideAccessible(this.parentNode.querySelector(`#${cssEscape(this.forTarget)}`));
108
+ const target = this.parentNode.querySelector(`#${cssEscape(this.forTarget)}`);
109
+ // aria-hidden elements cannot have focus, so wait for focus to be within target
110
+ waitForFocusWithinTarget(target, Date.now() + 200).then(() => {
111
+ if (!this.shown || this._state !== 'showing') return;
112
+ this._hiddenElements = hideAccessible(target);
113
+ });
110
114
  }
111
115
  this._state = 'showing';
112
116
 
@@ -188,6 +192,7 @@ function hideAccessible(target) {
188
192
  }
189
193
 
190
194
  function showAccessible(elems) {
195
+ if (!elems) return;
191
196
  for (let i = 0; i < elems.length; i++) {
192
197
  const elem = elems[i];
193
198
  if (elem.hasAttribute(BACKDROP_ARIA_HIDDEN)) {
@@ -200,4 +205,18 @@ function showAccessible(elems) {
200
205
  }
201
206
  }
202
207
 
208
+ async function waitForFocusWithinTarget(target, expireTime) {
209
+
210
+ if (Date.now() > expireTime) return;
211
+
212
+ const activeElem = getComposedActiveElement();
213
+ const targetIsAncestor = isComposedAncestor(target, activeElem);
214
+
215
+ if (targetIsAncestor) return;
216
+
217
+ await new Promise(resolve => requestAnimationFrame(resolve));
218
+ return waitForFocusWithinTarget(target, expireTime);
219
+
220
+ }
221
+
203
222
  customElements.define('d2l-backdrop', Backdrop);
package/components/breadcrumbs/README.md CHANGED
@@ -28,124 +28,120 @@ Breadcrumbs are a way-finding tool that helps users understand where they are w
28
28
  <!-- docs: end donts -->
29
29
  <!-- docs: end best practices -->
30
30
 
31
- ## Responsive Behavior
32
-
33
- Breadcrumbs that overflow their container will appear to fade at the edge.
31
+ ## Breadcrumbs [d2l-breadcrumbs]
34
32
 
35
- <!-- docs: demo display:block -->
33
+ <!-- docs: demo code properties name:d2l-breadcrumbs sandboxTitle:'Breadcrumbs' display:block -->
36
34
  ```html
37
35
  <script type="module">
38
36
  import '@brightspace-ui/core/components/breadcrumbs/breadcrumbs.js';
39
37
  </script>
40
38
  <d2l-breadcrumbs>
41
- <d2l-breadcrumb text="Table of Contents" href="#"></d2l-breadcrumb>
42
- <d2l-breadcrumb text="Unit 1: Shakespeare" href="#"></d2l-breadcrumb>
43
- <d2l-breadcrumb text="Lesson 1: Introduction" href="#"></d2l-breadcrumb>
44
- <d2l-breadcrumb text="The Comedies, Tragedies, and Histories" href="#"></d2l-breadcrumb>
39
+ <d2l-breadcrumb text="Item 1" href="#"></d2l-breadcrumb>
40
+ <d2l-breadcrumb text="Item 2" href="#"></d2l-breadcrumb>
41
+ <d2l-breadcrumb text="Item 3" href="#"></d2l-breadcrumb>
45
42
  </d2l-breadcrumbs>
46
43
  ```
47
44
 
48
- This works well for mobile or other touch devices but not as well for mouse or keyboard users, so we have two other options for managing width.
45
+ <!-- docs: start hidden content -->
46
+ ### Properties
49
47
 
50
- ### Limited Width
48
+ | Property | Type | Description |
49
+ |--|--|--|
50
+ | `compact` | Boolean | Renders in compact mode, displaying only the last item |
51
+ <!-- docs: end hidden content -->
51
52
 
52
- Set a `max-width` to constrain breadcrumbs to a particular width:
53
+ ## Breadcrumb (child) [d2l-breadcrumb]
53
54
 
54
- <!-- docs: demo code display:block -->
55
+ <!-- docs: demo code properties name:d2l-breadcrumb sandboxTitle:'Breadcrumb' display:block -->
55
56
  ```html
56
57
  <script type="module">
57
58
  import '@brightspace-ui/core/components/breadcrumbs/breadcrumbs.js';
58
59
  </script>
59
- <d2l-breadcrumbs style="max-width: 250px">
60
- <d2l-breadcrumb text="Trucate Basic Item 1" href="#"></d2l-breadcrumb>
61
- <d2l-breadcrumb text="Truncate Basic Item 2" href="#"></d2l-breadcrumb>
60
+ <d2l-breadcrumbs>
61
+ <d2l-breadcrumb text="Item 1" href="#"></d2l-breadcrumb>
62
62
  </d2l-breadcrumbs>
63
63
  ```
64
64
 
65
- ### Compact Mode
65
+ <!-- docs: start hidden content -->
66
+ ### Properties
66
67
 
67
- Alternately, add the `compact` attribute to only display the last breadcrumb. The `d2l-breadcrumb-current-page` will be hidden:
68
+ | Property | Type | Description |
69
+ |--|--|--|
70
+ | `text` | String, required | The text of the breadcrumb link |
71
+ | `aria-label` | String | ARIA label for the breadcrumb, used if `text` does not provide enough context for screen reader users |
72
+ | `href` | String | The Url that breadcrumb is pointing to |
73
+ | `target` | String | Target of the breadcrumb item |
74
+ <!-- docs: end hidden content -->
68
75
 
69
- <!-- docs: demo code display:block -->
76
+ ## Current Page [d2l-breadcrumb-current-page]
77
+
78
+ Only include the current page in the breadcrumb if your page or view does not have a visible heading. You will notice that some older pages or tools in Brightspace still display the current page as the last breadcrumb despite having a visible page heading, but this is now a legacy pattern.
79
+
80
+ <!-- docs: demo code properties name:d2l-breadcrumb-current-page sandboxTitle:'Current Page Breadcrumb' display:block -->
70
81
  ```html
71
82
  <script type="module">
72
83
  import '@brightspace-ui/core/components/breadcrumbs/breadcrumb-current-page.js';
73
84
  import '@brightspace-ui/core/components/breadcrumbs/breadcrumbs.js';
74
85
  </script>
75
- <d2l-breadcrumbs compact>
86
+ <d2l-breadcrumbs>
76
87
  <d2l-breadcrumb text="Item 1" href="#"></d2l-breadcrumb>
77
88
  <d2l-breadcrumb text="Item 2" href="#"></d2l-breadcrumb>
78
89
  <d2l-breadcrumb-current-page text="Current Page"></d2l-breadcrumb-current-page>
79
90
  </d2l-breadcrumbs>
80
91
  ```
81
92
 
82
- ## Breadcrumbs [d2l-breadcrumbs]
93
+ ## Responsive Behavior
83
94
 
84
- <!-- docs: demo code properties name:d2l-breadcrumbs sandboxTitle:'Breadcrumbs' display:block -->
95
+ Breadcrumbs that overflow their container will appear to fade at the edge, as in this example:
96
+
97
+ <!-- docs: demo display:block -->
85
98
  ```html
86
99
  <script type="module">
87
100
  import '@brightspace-ui/core/components/breadcrumbs/breadcrumbs.js';
88
101
  </script>
89
102
  <d2l-breadcrumbs>
90
- <d2l-breadcrumb text="Item 1" href="#"></d2l-breadcrumb>
91
- <d2l-breadcrumb text="Item 2" href="#"></d2l-breadcrumb>
92
- <d2l-breadcrumb text="Item 3" href="#"></d2l-breadcrumb>
103
+ <d2l-breadcrumb text="Table of Contents" href="#"></d2l-breadcrumb>
104
+ <d2l-breadcrumb text="Unit 1: Shakespeare" href="#"></d2l-breadcrumb>
105
+ <d2l-breadcrumb text="Lesson 1: Introduction" href="#"></d2l-breadcrumb>
106
+ <d2l-breadcrumb text="Sub-lesson 3: The Breadth of Shakespearean Literature" href="#"></d2l-breadcrumb>
107
+ <d2l-breadcrumb text="The Comedies, Tragedies, Histories, and Other Long Words" href="#"></d2l-breadcrumb>
93
108
  </d2l-breadcrumbs>
94
109
  ```
95
110
 
96
- <!-- docs: start hidden content -->
97
- ### Properties
98
-
99
- | Property | Type | Description |
100
- |--|--|--|
101
- | `compact` | Boolean | Indicates whether the component should render in compact mode |
102
- <!-- docs: end hidden content -->
111
+ ### Limited Width
103
112
 
104
- ## Breadcrumb (child) [d2l-breadcrumb]
113
+ Set a `max-width` to constrain breadcrumbs to a particular width:
105
114
 
106
- <!-- docs: demo code properties name:d2l-breadcrumb sandboxTitle:'Breadcrumb' display:block -->
115
+ <!-- docs: demo code display:block -->
107
116
  ```html
108
117
  <script type="module">
109
118
  import '@brightspace-ui/core/components/breadcrumbs/breadcrumbs.js';
110
119
  </script>
111
- <d2l-breadcrumbs>
112
- <d2l-breadcrumb text="Item 1" href="#"></d2l-breadcrumb>
120
+ <d2l-breadcrumbs style="max-width: 250px">
121
+ <d2l-breadcrumb text="Trucate Basic Item 1" href="#"></d2l-breadcrumb>
122
+ <d2l-breadcrumb text="Truncate Basic Item 2" href="#"></d2l-breadcrumb>
113
123
  </d2l-breadcrumbs>
114
124
  ```
115
125
 
116
- <!-- docs: start hidden content -->
117
- ### Properties
118
-
119
- | Property | Type | Description |
120
- |--|--|--|
121
- | `text` | String, required | Text of the breadcrumb item |
122
- | `aria-label` | String | AriaLabel of breadcrumb item |
123
- | `href` | String | Href of the breadcrumb item |
124
- | `target` | String | Target of the breadcrumb item |
125
- <!-- docs: end hidden content -->
126
-
127
- ### Accessibility Properties
128
-
129
- To make your usage of `d2l-breadcrumb` (child) accessible, use the following attribute when applicable:
130
-
131
- | Attribute | Description |
132
- |---|---|
133
- | `aria-label` | Acts as a primary label. Use if `text` does not provide enough context. |
134
-
135
- ## Current Page [d2l-breadcrumb-current-page]
126
+ ### Compact Mode
136
127
 
137
- Only include the current page in the breadcrumb if your page or view does not have a visible heading. You will notice that some older pages or tools in Brightspace still display the current page as the last breadcrumb despite having a visible page heading, but this is now a legacy pattern.
128
+ Alternately, add the `compact` attribute to only display the last breadcrumb. The `d2l-breadcrumb-current-page` will be hidden:
138
129
 
139
- <!-- docs: demo code properties name:d2l-breadcrumb-current-page sandboxTitle:'Current Page Breadcrumb' display:block -->
130
+ <!-- docs: demo code display:block -->
140
131
  ```html
141
132
  <script type="module">
142
133
  import '@brightspace-ui/core/components/breadcrumbs/breadcrumb-current-page.js';
143
134
  import '@brightspace-ui/core/components/breadcrumbs/breadcrumbs.js';
144
135
  </script>
145
- <d2l-breadcrumbs>
136
+ <d2l-breadcrumbs compact>
146
137
  <d2l-breadcrumb text="Item 1" href="#"></d2l-breadcrumb>
147
138
  <d2l-breadcrumb text="Item 2" href="#"></d2l-breadcrumb>
148
139
  <d2l-breadcrumb-current-page text="Current Page"></d2l-breadcrumb-current-page>
149
140
  </d2l-breadcrumbs>
150
141
  ```
151
142
 
143
+ ## Accessibility
144
+
145
+ Breadcrumbs adhere to [W3C's Breadcrumbs Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/), so they are contained in a navigation landmark region with proper aria labelling and add `aria-current` to the final breadcrumb if it represents the [Current Page](#d2l-breadcrumb-current-page).
146
+
147
+ Note that we do not apply a `visited` style to breadcrumbs, since they reflect tool hiearchy and are part of the UI rather than part of the page content.
package/components/breadcrumbs/breadcrumb.js CHANGED
@@ -32,12 +32,12 @@ class Breadcrumb extends RtlMixin(FocusMixin(LitElement)) {
32
32
  */
33
33
  target: { type: String, reflect: true },
34
34
  /**
35
- * REQUIRED: text of the breadcrumb link
35
+ * REQUIRED: The text of the breadcrumb link
36
36
  * @type {string}
37
37
  */
38
38
  text: { type: String, reflect: true },
39
39
  /**
40
- * ARIA label of the breadcrumb
40
+ * ACCESSIBILITY: ARIA label for the breadcrumb, used if `text` does not provide enough context for screen reader users
41
41
  * @type {string}
42
42
  */
43
43
  ariaLabel: { attribute: 'aria-label', type: String, reflect: true }
package/custom-elements.json CHANGED
@@ -189,7 +189,7 @@
189
189
  {
190
190
  "name": "d2l-backdrop",
191
191
  "path": "./components/backdrop/backdrop.js",
192
- "description": "A component for displaying a semi-transparent backdrop behind a specified sibling element. It also hides elements other than the target from assistive technologies by applying 'role=\"presentation\"' and 'aria-hidden=\"true\"'.",
192
+ "description": "A component for displaying a semi-transparent backdrop behind a specified sibling element. It also hides elements other than the target from assistive technologies by applying 'aria-hidden=\"true\"'.",
193
193
  "attributes": [
194
194
  {
195
195
  "name": "for-target",
@@ -269,12 +269,12 @@
269
269
  },
270
270
  {
271
271
  "name": "aria-label",
272
- "description": "ARIA label of the breadcrumb",
272
+ "description": "ACCESSIBILITY: ARIA label for the breadcrumb, used if `text` does not provide enough context for screen reader users",
273
273
  "type": "string"
274
274
  },
275
275
  {
276
276
  "name": "text",
277
- "description": "REQUIRED: text of the breadcrumb link",
277
+ "description": "REQUIRED: The text of the breadcrumb link",
278
278
  "type": "string",
279
279
  "default": "\"\""
280
280
  }
@@ -295,13 +295,13 @@
295
295
  {
296
296
  "name": "ariaLabel",
297
297
  "attribute": "aria-label",
298
- "description": "ARIA label of the breadcrumb",
298
+ "description": "ACCESSIBILITY: ARIA label for the breadcrumb, used if `text` does not provide enough context for screen reader users",
299
299
  "type": "string"
300
300
  },
301
301
  {
302
302
  "name": "text",
303
303
  "attribute": "text",
304
- "description": "REQUIRED: text of the breadcrumb link",
304
+ "description": "REQUIRED: The text of the breadcrumb link",
305
305
  "type": "string",
306
306
  "default": "\"\""
307
307
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@brightspace-ui/core",
3
- "version": "3.72.3",
3
+ "version": "3.73.1",
4
4
  "description": "A collection of accessible, free, open-source web components for building Brightspace applications",
5
5
  "type": "module",
6
6
  "repository": "https://github.com/BrightspaceUI/core.git",