@brightspace-ui/core 3.72.3 → 3.73.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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",