feat(VDataTable): multi-sort mode and keyboard modifiers (#22133)

resolves #22132

Author: J-Sek

packages/api-generator/src/locale/en/DataTable-sort.json

@@ -1,8 +1,9 @@
 {
   "props": {
     "customKeySort": "Function used on specific keys within the item object. `customSort` is skipped for columns with `customKeySort` specified.",
+    "disableSort": "Toggles rendering of sort button.",
+    "multiSort": "Let user sort by multiple properties/columns.\n\n- **key**: (optional) when set to `ctrl`, user is required to hold a keyboard key (Ctrl on PC and Command on Mac)\n- **mode**: when user selects a new column to sort by, it will be set first (`prepend`) or last (`append`) in the sort priority. Defaults to `append`\n- **modifier**: (optional) allows user to use both multi-sort modes (`append` and `prepend`) simultaneously\n\n**Note**: object notation requires at least **v3.11.0**",
     "mustSort": "Forces sorting on the column(s).",
     "sortBy": "Array of column keys and sort orders that determines the sort order of the table."
-
   }
 }

packages/api-generator/src/locale/en/VDataIterator.json

@@ -2,10 +2,8 @@
   "props": {
     "customFilter": "Function to filter items.",
     "customGroup": "Function used to group items.",
-    "customSort": "Function used to sort items.",
     "disableFiltering": "Disables filtering completely.",
     "disablePagination": "Disables pagination completely.",
-    "disableSort": "Disables sorting completely.",
     "expanded": "Array of expanded items. Can be bound to external variable using **v-model:expanded**.",
     "footerProps": "See the [`v-data-footer`](/api/v-data-footer) API for more information.",
     "groupBy": "Configures attributes (and sort order) to group items together.",
@@ -16,15 +14,12 @@
     "loadingText": "Text shown when `loading` is true and no items are provided.",
     "locale": "Sets the locale used for sorting. This is passed into [`Intl.Collator()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator) in the default `customSort` function.",
     "mobileBreakpoint": "Used to set when to toggle between regular table and mobile view.",
-    "multiSort": "If `true` then one can sort on multiple properties.",
-    "mustSort": "If `true` then one can not disable sorting, it will always switch between ascending and descending.",
     "noResultsText": "Text shown when `search` prop is used and there are no results.",
     "search": "Text input used to filter items.",
     "selectableKey": "The property on each item that is used to determine if it is selectable or not.",
     "serverItemsLength": "Used only when data is provided by a server. Should be set to the total amount of items available on server so that pagination works correctly.",
     "singleExpand": "Changes expansion mode to single expand.",
     "singleSelect": "Changes selection mode to single select.",
-    "sortBy": "Changes which item property (or properties) should be used for sort order. Can be bound to external variable using **v-model:sortBy**.",
     "value": "Used for controlling selected rows."
   },
   "slots": {

packages/api-generator/src/locale/en/VDataTable.json

@@ -8,7 +8,6 @@
     "density": "Adjusts the vertical height of the table rows.",
     "disableFiltering": "Disables filtering completely.",
     "disablePagination": "Disables pagination completely.",
-    "disableSort": "Disables sorting completely.",
     "expandIcon": "Icon to display when the expandable row is collapsed.",
     "fixedHeader": "Fixed header to top of table.",
     "groupBy": "Configures attributes (and sort order) to group items together. Can be customized further with `group-header` and `group-summary` slots.",
@@ -22,8 +21,6 @@
     "itemClass": "Property on supplied `items` that contains item's row class or function that takes an item as an argument and returns the class of corresponding row.",
     "itemsPerPage": "Changes how many items per page should be visible. Can be bound to external variable using **v-model:itemsPerPage**.. Setting this prop to `-1` will display all items on the page.",
     "locale": "Sets the locale used for sorting. This is passed into [`Intl.Collator()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator) in the default `customSort` function.",
-    "multiSort": "If `true` then one can sort on multiple properties.",
-    "mustSort": "If `true` then one can not disable sorting, it will always switch between ascending and descending.",
     "page": "The current displayed page number (1-indexed).",
     "serverItemsLength": "Used only when data is provided by a server. Should be set to the total amount of items available on server so that pagination works correctly.",
     "showSelect": "Shows the select checkboxes in both the header and rows (if using default rows).",

packages/api-generator/src/locale/en/VDataTableHeaders.json

@@ -1,14 +1,12 @@
 {
   "props": {
     "color": "Applies a color to sort badges in the table header.",
-    "disableSort": "Toggles rendering of sort button.",
     "sortAscIcon": "Icon used for ascending sort button.",
     "sortDescIcon": "Icon used for descending sort button.",
     "sticky": "Deprecated, use `fixed-header` instead.",
     "fixedHeader": "Sticks the header to the top of the table.",
     "lastFixed": "**FOR INTERNAL USE ONLY** Applies right border to the last column fixed to the left.",
     "firstFixedEnd": "**FOR INTERNAL USE ONLY** Applies left border to the first column fixed to the right.",
-    "multiSort": "Sort on multiple columns at the same time.",
     "headerProps": "Additional props to be be passed to the default header"
   },
   "slots": {

packages/api-generator/src/locale/en/VDataTableRows.json

@@ -3,7 +3,6 @@
     "cellProps": "An object of additional props to be passed to each `<td>` in the table body. Also accepts a function that will be called for each cell. If the same prop is defined both here and in `cellProps` in a headers object, the value from the headers object will be used.",
     "loading": "Displays `loading` slot if set to `true`",
     "loadingText": "Text shown when the data is loading.",
-    "multiSort": "Allows sorting by multiple columns.",
     "rowProps": "An object of additional props to be passed to each `<tr>` in the table body. Also accepts a function that will be called for each row."
   },
   "events": {

packages/api-generator/src/locale/en/VDataTableServer.json

@@ -18,7 +18,6 @@
     "column.data-table-select": "Slot to replace the default `v-checkbox-btn` used when selecting rows.",
     "dataTableGroup": "Slot for custom rendering of a group.",
     "data-table-select": "Slot for custom rendering of a header cell with the select checkbox.",
-    "disableSort": "Disables sorting completely.",
     "expanded-row": "Slot for custom rendering of an expanded row.",
     "footer.prepend": "Adds content to the empty space in the footer.",
     "group-header": "Slot for custom rendering of a group header.",

packages/api-generator/src/locale/en/VDataTableVirtual.json

@@ -18,7 +18,6 @@
     "column.data-table-select": "Slot to replace the default `v-checkbox-btn` used when selecting rows.",
     "data-table-group": "Slot for custom rendering of a group.",
     "data-table-select": "Slot for custom rendering of a header cell with the select checkbox.",
-    "disableSort": "Disables sorting completely.",
     "expanded-row": "Slot for custom rendering of an expanded row.",
     "group-header": "Slot for custom rendering of a group header.",
     "group-summary": "Slot for custom rendering of a group summary.",

packages/docs/src/examples/v-data-table/prop-multi-sort.vue

@@ -1,10 +1,15 @@
 <template>
-  <v-data-table
-    :headers="headers"
-    :items="desserts"
-    :sort-by="[{ key: 'calories', order: 'asc' }, { key: 'fat', order: 'desc' }]"
-    multi-sort
-  ></v-data-table>
+  <div>
+    <v-alert class="mb-2" density="compact" variant="outlined">
+      <strong>Hint:</strong> Hold  <v-kbd>Alt</v-kbd> to prepend new columns to <v-code>sort-by</v-code> array
+    </v-alert>
+    <v-data-table
+      :headers="headers"
+      :items="desserts"
+      :multi-sort="{ mode: 'append', modifier: 'alt' }"
+      :sort-by="[{ key: 'calories', order: 'asc' }, { key: 'fat', order: 'desc' }]"
+    ></v-data-table>
+  </div>
 </template>
 
 <script setup>
@@ -22,86 +27,16 @@
     { title: 'Iron (%)', key: 'iron' },
   ]
   const desserts = [
-    {
-      name: 'Frozen Yogurt',
-      calories: 200,
-      fat: 6,
-      carbs: 24,
-      protein: 4,
-      iron: 1,
-    },
-    {
-      name: 'Ice cream sandwich',
-      calories: 200,
-      fat: 9,
-      carbs: 37,
-      protein: 4.3,
-      iron: 1,
-    },
-    {
-      name: 'Eclair',
-      calories: 300,
-      fat: 16,
-      carbs: 23,
-      protein: 6,
-      iron: 7,
-    },
-    {
-      name: 'Cupcake',
-      calories: 300,
-      fat: 3.7,
-      carbs: 67,
-      protein: 4.3,
-      iron: 8,
-    },
-    {
-      name: 'Gingerbread',
-      calories: 400,
-      fat: 16,
-      carbs: 49,
-      protein: 3.9,
-      iron: 16,
-    },
-    {
-      name: 'Jelly bean',
-      calories: 400,
-      fat: 0,
-      carbs: 94,
-      protein: 0,
-      iron: 0,
-    },
-    {
-      name: 'Lollipop',
-      calories: 400,
-      fat: 0.2,
-      carbs: 98,
-      protein: 0,
-      iron: 2,
-    },
-    {
-      name: 'Honeycomb',
-      calories: 400,
-      fat: 3.2,
-      carbs: 87,
-      protein: 6.5,
-      iron: 45,
-    },
-    {
-      name: 'Donut',
-      calories: 500,
-      fat: 25,
-      carbs: 51,
-      protein: 4.9,
-      iron: 22,
-    },
-    {
-      name: 'KitKat',
-      calories: 500,
-      fat: 26,
-      carbs: 65,
-      protein: 7,
-      iron: 6,
-    },
+    { name: 'Frozen Yogurt', calories: 200, fat: 6, carbs: 24, protein: 4, iron: 1 },
+    { name: 'Ice cream sandwich', calories: 200, fat: 9, carbs: 37, protein: 4.3, iron: 1 },
+    { name: 'Eclair', calories: 300, fat: 16, carbs: 23, protein: 6, iron: 7 },
+    { name: 'Cupcake', calories: 300, fat: 3.7, carbs: 67, protein: 4.3, iron: 8 },
+    { name: 'Gingerbread', calories: 400, fat: 16, carbs: 49, protein: 3.9, iron: 16 },
+    { name: 'Jelly bean', calories: 400, fat: 0, carbs: 94, protein: 0, iron: 0 },
+    { name: 'Lollipop', calories: 400, fat: 0.2, carbs: 98, protein: 0, iron: 2 },
+    { name: 'Honeycomb', calories: 400, fat: 3.2, carbs: 87, protein: 6.5, iron: 45 },
+    { name: 'Donut', calories: 500, fat: 25, carbs: 51, protein: 4.9, iron: 22 },
+    { name: 'KitKat', calories: 500, fat: 26, carbs: 65, protein: 7, iron: 6 },
   ]
 </script>
 
@@ -123,86 +58,16 @@
           { title: 'Iron (%)', key: 'iron' },
         ],
         desserts: [
-          {
-            name: 'Frozen Yogurt',
-            calories: 200,
-            fat: 6.0,
-            carbs: 24,
-            protein: 4.0,
-            iron: 1,
-          },
-          {
-            name: 'Ice cream sandwich',
-            calories: 200,
-            fat: 9.0,
-            carbs: 37,
-            protein: 4.3,
-            iron: 1,
-          },
-          {
-            name: 'Eclair',
-            calories: 300,
-            fat: 16.0,
-            carbs: 23,
-            protein: 6.0,
-            iron: 7,
-          },
-          {
-            name: 'Cupcake',
-            calories: 300,
-            fat: 3.7,
-            carbs: 67,
-            protein: 4.3,
-            iron: 8,
-          },
-          {
-            name: 'Gingerbread',
-            calories: 400,
-            fat: 16.0,
-            carbs: 49,
-            protein: 3.9,
-            iron: 16,
-          },
-          {
-            name: 'Jelly bean',
-            calories: 400,
-            fat: 0.0,
-            carbs: 94,
-            protein: 0.0,
-            iron: 0,
-          },
-          {
-            name: 'Lollipop',
-            calories: 400,
-            fat: 0.2,
-            carbs: 98,
-            protein: 0,
-            iron: 2,
-          },
-          {
-            name: 'Honeycomb',
-            calories: 400,
-            fat: 3.2,
-            carbs: 87,
-            protein: 6.5,
-            iron: 45,
-          },
-          {
-            name: 'Donut',
-            calories: 500,
-            fat: 25.0,
-            carbs: 51,
-            protein: 4.9,
-            iron: 22,
-          },
-          {
-            name: 'KitKat',
-            calories: 500,
-            fat: 26.0,
-            carbs: 65,
-            protein: 7,
-            iron: 6,
-          },
+          { name: 'Frozen Yogurt', calories: 200, fat: 6.0, carbs: 24, protein: 4.0, iron: 1 },
+          { name: 'Ice cream sandwich', calories: 200, fat: 9.0, carbs: 37, protein: 4.3, iron: 1 },
+          { name: 'Eclair', calories: 300, fat: 16.0, carbs: 23, protein: 6.0, iron: 7 },
+          { name: 'Cupcake', calories: 300, fat: 3.7, carbs: 67, protein: 4.3, iron: 8 },
+          { name: 'Gingerbread', calories: 400, fat: 16.0, carbs: 49, protein: 3.9, iron: 16 },
+          { name: 'Jelly bean', calories: 400, fat: 0.0, carbs: 94, protein: 0.0, iron: 0 },
+          { name: 'Lollipop', calories: 400, fat: 0.2, carbs: 98, protein: 0, iron: 2 },
+          { name: 'Honeycomb', calories: 400, fat: 3.2, carbs: 87, protein: 6.5, iron: 45 },
+          { name: 'Donut', calories: 500, fat: 25.0, carbs: 51, protein: 4.9, iron: 22 },
+          { name: 'KitKat', calories: 500, fat: 26.0, carbs: 65, protein: 7, iron: 6 },
         ],
       }
     },

packages/docs/src/pages/en/components/data-tables/data-and-display.md

@@ -122,7 +122,11 @@ Unless you are using the **multi-sort** prop seen below, this array will almost
 
 ### Multi sort
 
-Using the **multi-sort** prop will enable you to sort on multiple columns at the same time.
+Using the **multi-sort** prop will allow user to sort on multiple columns at the same time. You can specify whether new columns should be added first or last to the **sort-by** array. By specifying optional **modifier** key, you can support both modes.
+
+::: warning
+`multi-sort` with object parameter requires at least [v3.11.0](/getting-started/release-notes/?version=v3.11.0)
+:::
 
 <ExamplesExample file="v-data-table/prop-multi-sort" />
 

packages/vuetify/src/components/VDataTable/VDataTable.tsx

@@ -22,7 +22,7 @@ import { makeFilterProps, useFilter } from '@/composables/filter'
 
 // Utilities
 import { computed, toRef, toRefs } from 'vue'
-import { genericComponent, propsFactory, useRender } from '@/util'
+import { genericComponent, omit, propsFactory, useRender } from '@/util'
 
 // Types
 import type { DeepReadonly, UnwrapRef } from 'vue'
@@ -85,7 +85,7 @@ export const makeDataTableProps = propsFactory({
   ...makeDataTableItemsProps(),
   ...makeDataTableSelectProps(),
   ...makeDataTableSortProps(),
-  ...makeVDataTableHeadersProps(),
+  ...omit(makeVDataTableHeadersProps(), ['multiSort']),
   ...makeVTableProps(),
 }, 'DataTable')
 
@@ -222,7 +222,7 @@ export const VDataTable = genericComponent<new <T extends readonly any[], V>(
 
     useRender(() => {
       const dataTableFooterProps = VDataTableFooter.filterProps(props)
-      const dataTableHeadersProps = VDataTableHeaders.filterProps(props)
+      const dataTableHeadersProps = VDataTableHeaders.filterProps(omit(props, ['multiSort']))
       const dataTableRowsProps = VDataTableRows.filterProps(props)
       const tableProps = VTable.filterProps(props)
 
@@ -249,6 +249,7 @@ export const VDataTable = genericComponent<new <T extends readonly any[], V>(
                   <thead key="thead">
                     <VDataTableHeaders
                       { ...dataTableHeadersProps }
+                      multiSort={ !!props.multiSort }
                       v-slots={ slots }
                     />
                   </thead>