@brightspace-ui/core 3.59.0 → 3.60.0

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.59.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",