Hds::Table sort by selected docs updates

website/docs/components/table/index.js

@@ -90,6 +90,10 @@ export default class Index extends Component {
  'badge-color': 'critical',
  },
  ];
+ @tracked demoSortBySelectedData = [...this.model.myDemoData].map((row) => ({
+ ...row,
+ isSelected: false,
+ }));
 
  get model() {
  return { myDemoData: this.demoSourceData };
@@ -189,4 +193,16 @@ export default class Index extends Component {
  }
  });
  }
+
+ @action
+ demoOnSelectionChangeSortBySelected({ selectableRowsStates }) {
+ selectableRowsStates.forEach((row) => {
+ const recordToUpdate = this.demoSortBySelectedData.find(
+ (modelRow) => modelRow.id === row.selectionKey
+ );
+ if (recordToUpdate) {
+ recordToUpdate.isSelected = row.isSelected;
+ }
+ });
+ }
 }

website/docs/components/table/partials/code/component-api.md

@@ -97,6 +97,9 @@ The Table component itself is where most of the options will be applied. However
  <C.Property @name="valign" @type="enum" @values={{array "top" "middle" "baseline" }} @default="top">
  Determines the vertical alignment for content in a table. Does not apply to table headers (`th`). See [MDN reference on vertical-align](https://developer.mozilla.org/en-US/docs/Web/CSS/vertical-align) for more details.
  </C.Property>
+ <C.Property @name="selectableColumnKey" @type="string">
+ If set, this key determines which `@model` item property is used to sort items by selection state. If this argument is not provided, the option to sort by selection state will not be available.
+ </C.Property>
  <C.Property @name="caption" @type="string">
  Adds a (non-visible) caption for users with assistive technology. If set on a sortable table, the provided table caption is paired with the automatically generated sorted message text.
  </C.Property>

website/docs/components/table/partials/code/how-to-use.md

@@ -638,6 +638,42 @@ While it’s technically possible to use the multi-select feature in a table imp
 
 !!!
 
+### Sorting by selected
+
+To enable sorting by selected rows in a table, you need to set `@selectableColumnKey` to the key in each row that tracks its selection state. This allows you to sort the table based on whether rows are selected or not.
+
+In the demo below, we set up a multi-select table that can be sorted based on the selection state of its rows.
+
+```handlebars
+<Hds::Table
+ @isSelectable={{true}}
+ @selectableColumnKey="isSelected"
+ @onSelectionChange={{this.demoOnSelectionChangeSortBySelected}}
+ @model={{this.demoSortBySelectedData}}
+ @columns={{array
+ (hash key="artist" label="Artist" isSortable=true)
+ (hash key="album" label="Album" isSortable=true)
+ (hash key="year" label="Year" isSortable=true)
+ (hash key="selection" label="Selected" isSortable=true)
+ }}
+ @sortBy="selection"
+ @sortOrder="desc"
+>
+ <:body as |B|>
+ <B.Tr
+ @selectionKey={{B.data.id}}
+ @isSelected={{B.data.isSelected}}
+ @selectionAriaLabelSuffix="row {{B.data.artist}} / {{B.data.album}}"
+ >
+ <B.Td>{{B.data.artist}}</B.Td>
+ <B.Td>{{B.data.album}}</B.Td>
+ <B.Td>{{B.data.year}}</B.Td>
+ <B.Td>{{if B.data.isSelected "Yes" "No"}}</B.Td>
+ </B.Tr>
+ </:body>
+</Hds::Table>
+```
+
 #### Multi-select table with pagination and persisted selection status
 
 This is a more complex example, where a table with multi-selection is associated with a [Pagination](/components/pagination) element (a similar use case would apply if a [filter](/patterns/filter-patterns) is applied to the data used to populate the table). In this case, a **subset of rows** is displayed on screen.