feat(table): Selectable rows (fixes #1790) (#2260)

Author: lianee

src/components/table/README.md

@@ -334,14 +334,14 @@ fields: [
 ```html
 <template>
   <div>
-    <b-form-checkbox v-model="striped">Striped</b-form-checkbox>
-    <b-form-checkbox v-model="bordered">Bordered</b-form-checkbox>
-    <b-form-checkbox v-model="outlined">Outlined</b-form-checkbox>
-    <b-form-checkbox v-model="small">Small</b-form-checkbox>
-    <b-form-checkbox v-model="hover">Hover</b-form-checkbox>
-    <b-form-checkbox v-model="dark">Dark</b-form-checkbox>
-    <b-form-checkbox v-model="fixed">Fixed</b-form-checkbox>
-    <b-form-checkbox v-model="footClone">Foot Clone</b-form-checkbox>
+    <b-form-checkbox inline v-model="striped">Striped</b-form-checkbox>
+    <b-form-checkbox inline v-model="bordered">Bordered</b-form-checkbox>
+    <b-form-checkbox inline v-model="outlined">Outlined</b-form-checkbox>
+    <b-form-checkbox inline v-model="small">Small</b-form-checkbox>
+    <b-form-checkbox inline v-model="hover">Hover</b-form-checkbox>
+    <b-form-checkbox inline v-model="dark">Dark</b-form-checkbox>
+    <b-form-checkbox inline v-model="fixed">Fixed</b-form-checkbox>
+    <b-form-checkbox inline v-model="footClone">Foot Clone</b-form-checkbox>
 
     <b-table :striped="striped"
              :bordered="bordered"
@@ -612,7 +612,7 @@ for details and usage of `<colgroup>`
 ## Table busy state
 `<b-table>` provides a `busy` prop that will flag the table as busy, which you can
 set to `true` just before you update your items, and then set it to `false` once you have
-your items. When in hte busy state, the tabe will have the attribute `aria-busy="true"`.
+your items. When in the busy state, the table will have the attribute `aria-busy="true"`.
 
 During the busy state, the table will be rendered in a "muted" look (`opacity: 0.6`), using the
 following custom CSS:
@@ -746,11 +746,12 @@ The slot's scope variable (`data` in the above sample) will have the following p
 | `unformatted` | Any | The raw value for this key in the item record (`null` or `undefined` if a virtual column), before being passed to the field's `formatter` function
 | `detailsShowing` | Boolean | Will be `true` if the row's `row-details` scoped slot is visible. See section [**Row details support**](#row-details-support) below for additional information
 | `toggleDetails` | Function | Can be called to toggle the visibility of the rows `row-details` scoped slot. See section [**Row details support**](#row-details-support) below for additional information
+| `rowSelected` | Boolean | Will be `true` if the row has been selected. See section [**Row select support**](#row-select-support) for additional information 
 
 
 **Notes:**
 - _`index` will not always be the actual row's index number, as it is
-computed after pagination and filtering have been applied to the original
+computed after filtering, sorting and pagination have been applied to the original
 table data. The `index` value will refer to the **displayed row number**. This
 number will align with the indexes from the optional `v-model` bound variable._
 
@@ -901,6 +902,64 @@ event will not be emitted when the input, select, textarea is clicked (unless th
 (even when disabled)
 
 
+## Row select support
+You can make rows selectable, by using the prop `selectable`.
+
+Users can easily change the selecting mode by setting the `select-mode` prop.
+ - `multi`: each click will select/deselect the row (default mode)
+ - `single`: only a single row can be selected at one time
+ - `range`: any row clicked is toggled, any other deselected. the SHIFT key selects a range of
+rows, and CTRL/CMD click will toggle the selected row.
+
+When a table is `selectable` and the user clicks on a row, `<b-table>` will emit the `row-selected`
+event, passing a single argument which is the complete list of selected items.
+**Treat this argument as read-only.**
+
+```html
+<template>
+  <b-form-group
+      label="Selection mode:"
+      horizontal
+      :label-cols="4"
+      breakpoint="md"
+  >
+    <b-form-select v-model="selectMode" :options="modes" class="mb-3" />
+  </b-form-group>
+  <b-table selectable :select-mode="selectMode" selectedVariant="success" :items="items" @row-selected="rowSelected"></b-table>
+  {{ selected }}
+</template>
+
+<script>
+export default {
+  data () {
+    return {
+      modes: ['multi', 'single', 'range'],
+      items: [
+        { isActive: true, age: 40, first_name: 'Dickerson', last_name: 'Macdonald' },
+        { isActive: false, age: 21, first_name: 'Larsen', last_name: 'Shaw' },
+        { isActive: false, age: 89, first_name: 'Geneva', last_name: 'Wilson' },
+        { isActive: true, age: 38, first_name: 'Jami', last_name: 'Carney' }
+      ],
+      selectMode: 'multi',
+      selected: []
+    }
+  },
+  methods: {
+    rowSelected(items) {
+      this.selected = items
+    }
+  }
+}
+</script>
+
+<!-- table-selectable.vue -->
+```
+
+**Notes:** 
+- _Paging, filtering, or sorting will clear the selection. The `row-selected` event will be emitted with an empty array._
+- _Selected rows will have a class of `b-row-selected` added to them._
+- _When the table is in `selectable` mode, all data item `<tr>` elements will be in the document tab sequence (`tabindex="0"`) for accesibility reasons._
+
 ## Row details support
 If you would optionally like to display additional record information (such as
 columns not specified in the fields definition array), you can use the scoped slot
@@ -1404,6 +1463,22 @@ when fetching your data!
 When `b-table` is mounted in the document, it will automatically trigger a provider update call.
 
 
+## Table accessibility notes
+When the table is in `selectable` mode, or if there is a `row-clicked` event listener registered, all
+data item rows (`<tr>` elements) will be placed into the document tab sequence (via `tabindex="0"`) to
+allow keyboard-only and screen reader users the ability to click the rows.
+
+When a column (field) is sortable, the header (and footer) heading cells will also be placed into the
+document tab sequence for accesibility. 
+
+Note the following row based events/actions are not considered accessible, and should only be used if the
+functionality is non critical or can be provided via other means:
+
+- `row-dblclicked`
+- `row-contextmenu`
+- `row-hovered`
+- `row-unhovered`
+
 ## Complete Example
 
 ```html

src/components/table/_table.scss

@@ -155,3 +155,9 @@
     }
   }
 }
+
+/* b-table: selectable rows */
+table.b-table.b-table-selectable > tbody > tr {
+  cursor: pointer;
+  user-select: none;
+}

src/components/table/package.json

@@ -95,6 +95,16 @@
                     }
                 ]
             },
+            {
+                "event": "row-selected",
+                "description": "Emitted when a row or rows have been selected.",
+                "args": [
+                    {
+                        "arg": "rows",
+                        "description": "Array of the row items that are selected."
+                    }
+                ]
+            },
             {
                 "event": "head-clicked",
                 "description": "Emitted when a header or footer cell is clicked.",