@brightspace-ui/core 3.58.0 → 3.60.0

package/components/alert/README.md

@@ -34,33 +34,31 @@ Alerts communicate critical information relating to the state of the system and
 
 <d2l-button id="open" style="align-self:center;display:none;">Show Alerts</d2l-button>
 <d2l-alert id="alert" type="default" button-text="Undo" has-close-button>
-	An inline alert message.
+	Inline Alerts can be placed anywhere in the page content
 </d2l-alert>
 <d2l-alert-toast id="alert-toast" type="success" open no-auto-close>
-	A toast alert message.
+	Toast Alerts appear at the botttom of the viewport
 </d2l-alert-toast>
 ```
 
 ## Inline Alert [d2l-alert]
 
-The `d2l-alert` component can be used to communicate important information relating to the state of the system and the user's work flow.
+Use an inline alert if there is important information a user needs to know while performing a task; the alert remains visible until the user takes action or dismisses it.
 
 ### Best Practices
 
 <!-- docs: start best practices -->
 <!-- docs: start dos -->
-* Do use to let the user know when the system is in a state that will prevent them from completing their action
-* Do highlight information that requires the user’s attention and/or action.
-* Do provide a clear call to action if it can help resolve the alert
-* Do provide a control to dismiss the alert and prevent the message from displaying again, if applicable
-* Do use sentence case for alert text, but avoid unnecessary punctuation by not placing periods at the end of single sentences
+* Use an alert to highlight information that requires the user’s action or attention
+* Provide a clear call to action if it can help resolve the alert
+* Use sentence case for alert text and avoid unnecessary punctuation by not placing periods at the end of single sentences
 <!-- docs: end dos -->
 
 <!-- docs: start donts -->
-* Don’t use an inline alert in isolation for form validation errors – highlight fields with errors in red and ensure that the fields have error tooltips on focus & hover
-* Don't display more than one inline alert at a time
-* Don't display promotional material or information that is not related to the user’s key work flow
-* Don't display more than one paragraph of text in the alert
+* Don't display more than one paragraph of text
+* Avoid overusing them — the more commonly alerts appear, the less effective they will be
+* Don't use them for promotional material or information that is not relevant to the user’s workflow
+* Don’t use them for validation errors – instead, use the [Form](../../components/form) component for a consistent user experience
 <!-- docs: end donts -->
 <!-- docs: end best practices -->
 
@@ -71,7 +69,7 @@ The `d2l-alert` component can be used to communicate important information relat
 </script>
 
 <d2l-alert type="default" button-text="Undo">
-	A message.
+	An inline alert message
 </d2l-alert>
 ```
 <!-- docs: start hidden content -->
@@ -92,20 +90,20 @@ The `d2l-alert` component can be used to communicate important information relat
 
 ## Toast Alert [d2l-alert-toast]
 
-The `d2l-alert-toast` component serves the same purpose as `d2l-alert`; however, it is displayed as
-a pop-up at the bottom of the screen that automatically dismisses itself by default.
+Use a toast alert to provide feedback about an operation the user has just initiated when the result of that operation may not be apparent or obvious to the user. Toast alerts appear at the bottom of the viewport and disappear after 4 seconds by default.
+
 ### Best Practices
 <!-- docs: start best practices -->
 <!-- docs: start dos -->
-* Do make toasts dismissible via the close icon –
-* Do keep text brief – toasts shouldn’t spill onto more than one line at any screen size
-* Do use specific language – “Assignment saved” is more informative than “Successfully saved”
+* Use to convey results of a user's action when the result is not otherwise obvious
+* Keep text brief — toasts should rarely spill onto more than one line at any screen size
+* Use specific language — “Assignment saved” is more informative than “Successfully saved”
 <!-- docs: end dos -->
 <!-- docs: start donts -->
-* Avoid displaying multiple toast alerts - see [Multiple Toast Alerts](#multiple-toast-alerts)
-* Don't allow the close button to be blocked by other elements, the user doesn’t want to have to wait for it to go way on it’s own
-* Don’t use toasts to provide instructions. Change blindness and transience make them ineffective for these use cases
-* Don’t use the thumbnails or two-line variety of inline alert as a toast. Toasts should be super brief!
+* If possible, avoid displaying multiple toasts — see [Multiple Toast Alerts](#multiple-toast-alerts)
+* Don't allow the close button to be blocked by other elements; users shouldn't have to wait for the toast alert to go away on its own
+* Don’t use for instructions or critical information since toast alerts disappear and can be easily missed or ignored — use an [Inline Alert](#d2l-alert) instead
+* Avoid having two lines with `subtext` — toasts should be very brief
 <!-- docs: end donts -->
 <!-- docs: end best practices -->
 
@@ -133,7 +131,7 @@ a pop-up at the bottom of the screen that automatically dismisses itself by defa
 <d2l-button id="open" style="align-self:center;display:none;">Show Alert</d2l-button>
 <!-- docs: end hidden content -->
 <d2l-alert-toast type="default" no-auto-close open>
-  A default toast alert.
+  A default toast alert
 </d2l-alert-toast>
 ```
 
@@ -155,7 +153,7 @@ a pop-up at the bottom of the screen that automatically dismisses itself by defa
 
 ### Multiple Toast Alerts
 
-Displaying more than one toast message at a time should be avoided unless absolutely necessary, since they usually disappear after 4 seconds and can be difficult to read for some users. It's often better to use an [inline alert](#d2l-alert) so that users have time to discover and read the message.
+Avoid displaying more than one toast message at a time unless absolutely necessary, since they disappear after 4 seconds and can be difficult to read for some users. It's often better to use an [inline alert](#d2l-alert) so that users have time to discover and read the message.
 
 For cases where multiple toast alerts are unavoidable, new toast messages will appear at the bottom and push older messages upward.
 
@@ -189,3 +187,9 @@ For cases where multiple toast alerts are unavoidable, new toast messages will a
 	Third toast alert
 </d2l-alert-toast>
 ```
+
+## Accessibility
+
+[Inline Alerts](#d2l-alert) are meant to draw attention without interrupting the user's flow, so they do not use the ARIA `alert` role. This means screen reader users do not hear them until encountering them in the content (as intended).
+
+[Toast Alerts](#d2l-alert-toast) leverage the ARIA `alert` role in alignment with the [W3C Alert Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alert/), so an assertive live region is created which causes the content of the alert to be announced immediately. This can interrupt the user, so it should be used sparingly as per our [Best Practices](#best-practices-1).

package/components/table/README.md

@@ -134,9 +134,11 @@ For long tables, the header row can be made to "stick" in place as the user scro
 
 When tabular data can be sorted, the `<d2l-table-col-sort-button>` can be used to provide an interactive sort button as well as arrows to indicate the ascending/descending sort direction. This is meant to be used within a `d2l-table-wrapper`.
 
-Note that the example below hides much of the implementation. See the code in [Multi-Faceted Sort Button](#multi-faceted-sort-button) for a more detailed implementation example.
+For the example below:
+- The implementation is hidden. See the code in [Multi-Faceted Sort Button](#multi-faceted-sort-button) for a more detailed implementation example.
+- The code itself is handling the `desc` attribute so updating it in the Properties table will not have an impact on the live demo.
 
-<!-- docs: demo -->
+<!-- docs: demo properties name:d2l-table-col-sort-button sandboxTitle:'Table Sortable Column Buttons' -->
 ```html
 <script type="module">
   import '@brightspace-ui/core/components/table/table-col-sort-button.js';
@@ -182,10 +184,7 @@ Note that the example below hides much of the implementation. See the code in [M
             <thead>
               <tr>
                 <th>
-                  <d2l-table-col-sort-button
-                    @click="${this._handleSort}"
-					?desc="${this._sortDesc}"
-					source-type="words">
+                  <d2l-table-col-sort-button @click="${this._handleSort}" ?desc="${this._sortDesc}" source-type="words">
                     Column A
                   </d2l-table-col-sort-button>
                 </th>
@@ -211,6 +210,8 @@ Note that the example below hides much of the implementation. See the code in [M
 <d2l-my-sortable-table-elem></d2l-my-sortable-table-elem>
 ```
 
+The simplified property usage looks like this:
+
 ```html
 <d2l-table-wrapper>
   <table class="d2l-table">
@@ -225,6 +226,7 @@ Note that the example below hides much of the implementation. See the code in [M
 </d2l-table-wrapper>
 ```
 
+<!-- docs: start hidden content -->
 ### Properties
 
 | Property | Type | Description | Default Value |
@@ -239,6 +241,7 @@ Note that the example below hides much of the implementation. See the code in [M
 |---|---|
 | `Default` | Column header text |
 | `items` | Multi-facted sort items. Generally assigned to the `slot` attribute on a nested `d2l-table-col-sort-button-item`. |
+<!-- docs: end hidden content -->
 
 ### Slotted Item [d2l-table-col-sort-button-item]
 
@@ -270,7 +273,7 @@ When a single column is responsible for sorting in multiple facets (e.g., first
 
 **WARNING**: Do NOT use this if the table is using `sticky-headers` AND multiple header rows. It is not currently supported. In that siuation, continue to put multiple `d2l-table-col-sort-button` components in the same column.
 
-<!-- docs: demo code display:block -->
+<!-- docs: demo code display:block sandboxName:table-multi-faceted-sort-button sandboxTitle:'Table Multi-Faceted Sort Button' -->
 ```html
 <script type="module">
   import '@brightspace-ui/core/components/table/table-col-sort-button.js';
@@ -522,3 +525,12 @@ The `d2l-table-controls` component can be placed in the `d2l-table-wrapper`'s `c
 | `no-sticky` | Boolean | Disables sticky positioning for the controls |
 | `select-all-pages-allowed` | Boolean | Whether all pages can be selected |
 <!-- docs: end hidden content -->
+
+## Accessibility
+
+The `d2l-table-wrapper` simply wraps an HTML table in order to add styles and functionality to that table. As such, it is important to use proper table markup. Recommendations are available in [this tutorial](https://www.w3.org/WAI/tutorials/tables/). Make sure to include column and row headings so data is meaningful to screen reader users.
+
+The `d2l-table-col-sort-button` component was built with screen reader users at front-of-mind. Important features include:
+- A `source-type` attribute which lets users specify the type of data in the column (e.g., 'words', 'dates', or 'numbers') in order to provide a more descriptive title to both screen reader and sighted users
+- Changes to sort order and/or sort state are reflected in attributes such that they can be communicated to screen reader users if supported by the screen reader, which they are in most scenarios
+- Usage of our accessible menu component for the multi-faceted sort case

package/components/table/table-col-sort-button.js

@@ -13,7 +13,9 @@ import { LocalizeCoreElement } from '../../helpers/localize-core-element.js';
 
 /**
  * Button for sorting a table column in ascending/descending order.
+ * @fires click - Dispatched when the button is clicked
  * @slot - Text of the sort button
+ * @slot items - Multi-facted sort items. Generally assigned to the slot attribute on a nested d2l-table-col-sort-button-item.
  */
 export class TableColSortButton extends LocalizeCoreElement(FocusMixin(LitElement)) {
 
@@ -44,7 +46,7 @@ export class TableColSortButton extends LocalizeCoreElement(FocusMixin(LitElemen
 				type: String
 			},
 			/**
-			 * The type of data in the column. Used to set the title.
+			 * ACCESSIBILITY: The type of data in the column (e.g., 'words'). Used to set the title.
 			 *  @type {'words'|'numbers'|'dates'|'unknown'}
 			 */
 			sourceType: {

package/custom-elements.json

@@ -12272,7 +12272,7 @@
         },
         {
           "name": "source-type",
-          "description": "The type of data in the column. Used to set the title.",
+          "description": "ACCESSIBILITY: The type of data in the column (e.g., 'words'). Used to set the title.",
           "type": "'words'|'numbers'|'dates'|'unknown'",
           "default": "\"unknown\""
         }
@@ -12302,15 +12302,25 @@
         {
           "name": "sourceType",
           "attribute": "source-type",
-          "description": "The type of data in the column. Used to set the title.",
+          "description": "ACCESSIBILITY: The type of data in the column (e.g., 'words'). Used to set the title.",
           "type": "'words'|'numbers'|'dates'|'unknown'",
           "default": "\"unknown\""
         }
       ],
+      "events": [
+        {
+          "name": "click",
+          "description": "Dispatched when the button is clicked"
+        }
+      ],
       "slots": [
         {
           "name": "",
           "description": "Text of the sort button"
+        },
+        {
+          "name": "items",
+          "description": "Multi-facted sort items. Generally assigned to the slot attribute on a nested d2l-table-col-sort-button-item."
         }
       ]
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brightspace-ui/core",
-  "version": "3.58.0",
+  "version": "3.60.0",
   "description": "A collection of accessible, free, open-source web components for building Brightspace applications",
   "type": "module",
   "repository": "https://github.com/BrightspaceUI/core.git",