@brightspace-ui/core 3.5.1 → 3.5.2

package/components/table/README.md

@@ -132,7 +132,9 @@ For long tables, the header row can be made to "stick" in place as the user scro
 
 ## Sortable Column Buttons [d2l-table-col-sort-button]
 
-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.
+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.
 
 <!-- docs: demo -->
 ```html
@@ -210,15 +212,17 @@ When tabular data can be sorted, the `<d2l-table-col-sort-button>` can be used t
 ```
 
 ```html
-<table class="d2l-table">
-  <thead>
-    <tr>
-      <th><d2l-table-col-sort-button>Ascending</d2l-table-col-sort-button></th>
-      <th><d2l-table-col-sort-button desc>Descending</d2l-table-col-sort-button></th>
-      <th><d2l-table-col-sort-button nosort>Not Sorted</d2l-table-col-sort-button></th>
-    </tr>
-  </thead>
-</table>
+<d2l-table-wrapper>
+  <table class="d2l-table">
+    <thead>
+      <tr>
+        <th><d2l-table-col-sort-button>Ascending</d2l-table-col-sort-button></th>
+        <th><d2l-table-col-sort-button desc>Descending</d2l-table-col-sort-button></th>
+        <th><d2l-table-col-sort-button nosort>Not Sorted</d2l-table-col-sort-button></th>
+      </tr>
+    </thead>
+  </table>
+</d2l-table-wrapper>
 ```
 
 ### Properties
@@ -228,7 +232,134 @@ When tabular data can be sorted, the `<d2l-table-col-sort-button>` can be used t
 | `desc` | boolean | Whether sort direction is descending | false |
 | `nosort` | boolean | Column is not currently sorted. Hides the ascending/descending sort icon. | false |
 | `position` | string | Position of the button content. Accepted values are 'start', 'center', and 'end'. | 'start' |
-| `source-type` | string | The type of data in the column. Used to set the title. Accepted values are 'words', 'numbers', and 'dates'. | 'unknown' |
+| `source-type` | string | The type of data in the column. Used to set the title. Accepted values are 'words', 'numbers', and 'dates'. This is only applicable to cases that are not using the multi-faceted dropdown. | 'unknown' |
+
+### Slots
+| Name | Description |
+|---|---|
+| `Default` | Column header text |
+| `items` | Multi-facted sort items. Generally assigned to the `slot` attribute on a nested `d2l-table-col-sort-button-item`. |
+
+### Slotted Item [d2l-table-col-sort-button-item]
+
+This is a radio menu item to be used within the `d2l-table-col-sort-button` component for a [multi-faceted sort](#multi-faceted-sort-button).
+
+<!-- docs: demo code properties autoSize:false align:start name:d2l-table-col-sort-button-item -->
+```html
+<script type="module">
+  import '@brightspace-ui/core/components/table/table-col-sort-button.js';
+  import '@brightspace-ui/core/components/table/table-col-sort-button-item.js';
+</script>
+<!-- docs: start hidden content -->
+<style>
+  d2l-table-col-sort-button {
+    --d2l-table-cell-padding: 10px;
+  }
+</style>
+<!-- docs: end hidden content -->
+<d2l-table-col-sort-button desc>
+  Items
+  <d2l-table-col-sort-button-item text="Item 1" slot="items" value="item1"></d2l-table-col-sort-button-item>
+  <d2l-table-col-sort-button-item text="Item 2" slot="items" value="item2"></d2l-table-col-sort-button-item>
+</d2l-table-col-sort-button>
+```
+
+### Multi-Faceted Sort Button
+
+When a single column is responsible for sorting in multiple facets (e.g., first name and last name), it is recommended to use the dropdown menu approach by slotting `d2l-table-col-sort-button-item` components within the `d2l-table-col-sort-button`. Please note that the consumer is responsible for all sort logic, including when `desc` and `nosort` are set on `d2l-table-col-sort-button`.
+
+**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 -->
+```html
+<script type="module">
+  import '@brightspace-ui/core/components/table/table-col-sort-button.js';
+  import '@brightspace-ui/core/components/table/table-col-sort-button-item.js';
+  import { html, LitElement } from 'lit';
+  import { tableStyles } from '@brightspace-ui/core/components/table/table-wrapper.js';
+  const data = () => [
+    { firstname: 'John', lastname: 'Smith', grade: 85 },
+    { firstname: 'Emily', lastname: 'Jones', grade: 92 },
+    { firstname: 'Michael', lastname: 'Davis', grade: 78 },
+    { firstname: 'Sarah', lastname: 'Brown', grade: 90 },
+    { firstname: 'David', lastname: 'Wilson', grade: 88 },
+    { firstname: 'Jessica', lastname: 'Taylor', grade: 95 },
+    { firstname: 'Christopher', lastname: 'Martinez', grade: 83 }
+  ];
+  class MyComplexSortableTableElem extends LitElement {
+    static get properties() {
+      return {
+        _desc: { state: true },
+        _field: { state: true }
+      };
+    }
+    static get styles() {
+      return tableStyles;
+    }
+    constructor() {
+      super();
+      this._data = data();
+      this._desc = false;
+    }
+    render() {
+      const rowData = this._field ? this._data.sort((a, b) => {
+        if (this._desc) {
+          if (a[this._field] > b[this._field]) return -1;
+          if (a[this._field] < b[this._field]) return 1;
+        } else {
+          if (a[this._field] < b[this._field]) return -1;
+          if (a[this._field] > b[this._field]) return 1;
+        }
+        return 0;
+      }) : this._data;
+      const rows = rowData.map(i => {
+        return html`<tr>
+            <td>${i.firstname} ${i.lastname}</td>
+            <td>${i.grade}</td>
+          </tr>
+        `;
+      });
+      return html`
+        <d2l-table-wrapper>
+          <table class="d2l-table">
+            <thead>
+              <tr>
+                <th>
+                  <d2l-table-col-sort-button ?desc="${this._desc}" ?nosort="${this._field !== 'firstname' && this._field !== 'lastname'}">
+                    Learner
+                    <d2l-table-col-sort-button-item slot="items" text="First Name, A to Z" data-field="firstname" @d2l-table-col-sort-button-item-change="${this._handleSortComplex}" value="1"></d2l-table-col-sort-button-item>
+                    <d2l-table-col-sort-button-item slot="items" text="First Name, Z to A" data-field="firstname" data-desc @d2l-table-col-sort-button-item-change="${this._handleSortComplex}" value="2"></d2l-table-col-sort-button-item>
+                    <d2l-table-col-sort-button-item slot="items" text="Last Name, A to Z" data-field="lastname" @d2l-table-col-sort-button-item-change="${this._handleSortComplex}" value="3"></d2l-table-col-sort-button-item>
+                    <d2l-table-col-sort-button-item slot="items" text="Last Name, Z to A" data-field="lastname" data-desc @d2l-table-col-sort-button-item-change="${this._handleSortComplex}" value="4"></d2l-table-col-sort-button-item>
+                  </d2l-table-col-sort-button>
+                </th>
+                <th>
+                  <d2l-table-col-sort-button ?desc="${this._desc}" data-field="grade" @click="${this._handleSort}" ?nosort="${this._field !== 'grade'}">Grade</d2l-table-col-sort-button>
+                </th>
+              </tr>
+            </thead>
+            <tbody>
+              ${rows}
+            </tbody>
+          </table>
+        </d2l-table-wrapper>
+      `;
+    }
+    _handleSort(e) {
+      const field = e.target.getAttribute('data-field');
+      const desc = e.target.hasAttribute('desc');
+      this._desc = field === this._field ? !desc : false;
+      this._field = field;
+    }
+    _handleSortComplex(e) {
+      this._field = e.target.getAttribute('data-field');
+      this._desc = e.target.hasAttribute('data-desc');
+    }
+  }
+  customElements.define('d2l-my-complex-sortable-table-elem', MyComplexSortableTableElem);
+</script>
+<d2l-my-complex-sortable-table-elem></d2l-my-complex-sortable-table-elem>
+```
 
 ## Selection
 

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

@@ -6,6 +6,9 @@ import { RtlMixin } from '../../mixins/rtl/rtl-mixin.js';
 
 /**
  * A radio menu item to be used within the d2l-table-col-sort-button component for a multi-faceted sort.
+ * @fires d2l-menu-item-change - Internal event
+ * @fires d2l-menu-item-select - Internal event
+ * @fires d2l-menu-item-visibility-change - Internal event
  */
 class TableColSortButtonItem extends RtlMixin(MenuItemRadioMixin(LitElement)) {
 

package/custom-elements.json

@@ -12118,21 +12118,21 @@
         }
       ],
       "events": [
-        {
-          "name": "d2l-table-col-sort-button-item-change",
-          "description": "Dispatched when the selected multi-faceted sort option changes"
-        },
         {
           "name": "d2l-menu-item-change",
-          "description": "Dispatched when the selected menu item changes"
+          "description": "Internal event"
         },
         {
           "name": "d2l-menu-item-select",
-          "description": "Dispatched when the menu item is selected"
+          "description": "Internal event"
         },
         {
           "name": "d2l-menu-item-visibility-change",
-          "description": "Dispatched when the visibility of the menu item changes"
+          "description": "Internal event"
+        },
+        {
+          "name": "d2l-table-col-sort-button-item-change",
+          "description": "Dispatched when the selected multi-faceted sort option changes"
         }
       ]
     },

package/package.json

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