feat(VDataTable): add initial-sort-order prop (#22156)

resolves #11117
closes #20615

Author: J-Sek

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

@@ -2,6 +2,7 @@
   "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.",
+    "initialSortOrder": "Specifies the initial sort order when an unsorted column is clicked.",
     "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

@@ -8,6 +8,7 @@
     "footerProps": "See the [`v-data-footer`](/api/v-data-footer) API for more information.",
     "groupBy": "Configures attributes (and sort order) to group items together.",
     "hideDefaultFooter": "Hides default footer.",
+    "initialSortOrder": "Specifies the initial sort order when an **toggleSort** is called for unsorted property.",
     "itemKey": "The property on each item that is used as a unique key.",
     "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.",
     "loading": "If `true` and no items are provided, then a loading text will be shown.",

packages/docs/src/data/new-in.json

@@ -79,13 +79,19 @@
       "hideTitle": "3.10.0"
     }
   },
+  "VDataIterator": {
+    "props": {
+      "initialSortOrder": "3.11.0"
+    }
+  },
   "VDataTable": {
     "props": {
       "collapseIcon": "3.10.0",
       "expandIcon": "3.10.0",
       "groupCollapseIcon": "3.10.0",
       "groupExpandIcon": "3.10.0",
-      "headerProps": "3.5.0"
+      "headerProps": "3.5.0",
+      "initialSortOrder": "3.11.0"
     },
     "slots": {
       "group-summary": "3.10.0"
@@ -96,7 +102,8 @@
       "collapseIcon": "3.10.0",
       "expandIcon": "3.10.0",
       "groupCollapseIcon": "3.10.0",
-      "groupExpandIcon": "3.10.0"
+      "groupExpandIcon": "3.10.0",
+      "initialSortOrder": "3.11.0"
     },
     "slots": {
       "group-summary": "3.10.0"
@@ -107,7 +114,8 @@
       "collapseIcon": "3.10.0",
       "expandIcon": "3.10.0",
       "groupCollapseIcon": "3.10.0",
-      "groupExpandIcon": "3.10.0"
+      "groupExpandIcon": "3.10.0",
+      "initialSortOrder": "3.11.0"
     },
     "slots": {
       "group-summary": "3.10.0"

packages/vuetify/src/components/VDataIterator/VDataIterator.tsx

@@ -113,10 +113,10 @@ export const VDataIterator = genericComponent<new <T> (
     const { items } = useDataIteratorItems(props)
     const { filteredItems } = useFilter(props, items, search, { transform: item => item.raw })
 
-    const { sortBy, multiSort, mustSort } = createSort(props)
+    const { initialSortOrder, sortBy, multiSort, mustSort } = createSort(props)
     const { page, itemsPerPage } = createPagination(props)
 
-    const { toggleSort } = provideSort({ sortBy, multiSort, mustSort, page })
+    const { toggleSort } = provideSort({ initialSortOrder, sortBy, multiSort, mustSort, page })
     const { sortByWithGroups, opened, extractRows, isGroupOpen, toggleGroup } = provideGroupBy({ groupBy, sortBy })
 
     const { sortedItems } = useSortedItems(props, filteredItems, sortByWithGroups, { transform: item => item.raw })

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

@@ -128,7 +128,7 @@ export const VDataTable = genericComponent<new <T extends readonly any[], V>(
 
   setup (props, { attrs, slots }) {
     const { groupBy } = createGroupBy(props)
-    const { sortBy, multiSort, mustSort } = createSort(props)
+    const { initialSortOrder, sortBy, multiSort, mustSort } = createSort(props)
     const { page, itemsPerPage } = createPagination(props)
     const { disableSort } = toRefs(props)
 
@@ -152,7 +152,7 @@ export const VDataTable = genericComponent<new <T extends readonly any[], V>(
       customKeyFilter: filterFunctions,
     })
 
-    const { toggleSort } = provideSort({ sortBy, multiSort, mustSort, page })
+    const { toggleSort } = provideSort({ initialSortOrder, sortBy, multiSort, mustSort, page })
     const { sortByWithGroups, opened, extractRows, isGroupOpen, toggleGroup } = provideGroupBy({ groupBy, sortBy, disableSort })
 
     const { sortedItems } = useSortedItems(props, filteredItems, sortByWithGroups, {

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

@@ -69,7 +69,7 @@ export const VDataTableServer = genericComponent<new <T extends readonly any[],
 
   setup (props, { attrs, slots }) {
     const { groupBy } = createGroupBy(props)
-    const { sortBy, multiSort, mustSort } = createSort(props)
+    const { initialSortOrder, sortBy, multiSort, mustSort } = createSort(props)
     const { page, itemsPerPage } = createPagination(props)
     const { disableSort } = toRefs(props)
     const itemsLength = computed(() => parseInt(props.itemsLength, 10))
@@ -82,7 +82,7 @@ export const VDataTableServer = genericComponent<new <T extends readonly any[],
 
     const { items } = useDataTableItems(props, columns)
 
-    const { toggleSort } = provideSort({ sortBy, multiSort, mustSort, page })
+    const { toggleSort } = provideSort({ initialSortOrder, sortBy, multiSort, mustSort, page })
 
     const { opened, isGroupOpen, toggleGroup, extractRows } = provideGroupBy({ groupBy, sortBy, disableSort })
 

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

@@ -89,7 +89,7 @@ export const VDataTableVirtual = genericComponent<new <T extends readonly any[],
 
   setup (props, { attrs, slots }) {
     const { groupBy } = createGroupBy(props)
-    const { sortBy, multiSort, mustSort } = createSort(props)
+    const { initialSortOrder, sortBy, multiSort, mustSort } = createSort(props)
     const { disableSort } = toRefs(props)
 
     const {
@@ -111,7 +111,7 @@ export const VDataTableVirtual = genericComponent<new <T extends readonly any[],
       customKeyFilter: filterFunctions,
     })
 
-    const { toggleSort } = provideSort({ sortBy, multiSort, mustSort })
+    const { toggleSort } = provideSort({ initialSortOrder, sortBy, multiSort, mustSort })
     const { sortByWithGroups, opened, extractRows, isGroupOpen, toggleGroup } = provideGroupBy({ groupBy, sortBy, disableSort })
 
     const { sortedItems } = useSortedItems(props, filteredItems, sortByWithGroups, {

packages/vuetify/src/components/VDataTable/composables/sort.ts

@@ -12,6 +12,11 @@ import type { DataTableCompareFunction, InternalDataTableHeader } from '../types
 import type { InternalItem } from '@/composables/filter'
 
 export const makeDataTableSortProps = propsFactory({
+  initialSortOrder: {
+    type: String as PropType<'asc' | 'desc'>,
+    default: 'asc',
+    validator: (v: any) => !v || ['asc', 'desc'].includes(v),
+  },
   sortBy: {
     type: Array as PropType<readonly SortItem[]>,
     default: () => ([]),
@@ -40,17 +45,19 @@ export type MultiSortProps = {
 export type MultiSortMode = 'append' | 'prepend'
 
 type SortProps = {
+  initialSortOrder: 'asc' | 'desc'
   sortBy: readonly SortItem[]
   'onUpdate:sortBy': ((value: any) => void) | undefined
   multiSort: boolean | MultiSortProps
   mustSort: boolean
 }
 
 export function createSort (props: SortProps) {
+  const initialSortOrder = toRef(() => props.initialSortOrder)
   const sortBy = useProxiedModel(props, 'sortBy')
   const mustSort = toRef(() => props.mustSort)
   const multiSort = toRef(() => props.multiSort)
-  return { sortBy, mustSort, multiSort }
+  return { initialSortOrder, sortBy, multiSort, mustSort }
 }
 
 function resolveMultiSort (
@@ -75,38 +82,41 @@ function resolveMultiSort (
 }
 
 export function provideSort (options: {
+  initialSortOrder: Ref<'asc' | 'desc'>
   sortBy: Ref<readonly SortItem[]>
-  mustSort: Ref<boolean>
   multiSort: Ref<boolean | MultiSortProps>
+  mustSort: Ref<boolean>
   page?: Ref<number>
 }) {
-  const { sortBy, mustSort, multiSort, page } = options
+  const { initialSortOrder, sortBy, mustSort, multiSort, page } = options
 
   const toggleSort = (column: InternalDataTableHeader, event?: KeyboardEvent | PointerEvent) => {
     if (column.key == null) return
 
     let newSortBy = sortBy.value.map(x => ({ ...x })) ?? []
     const item = newSortBy.find(x => x.key === column.key)
 
+    const initialOrder = initialSortOrder.value
+    const secondaryOrder = initialSortOrder.value === 'desc' ? 'asc' : 'desc'
     if (!item) {
       const { active, mode } = resolveMultiSort(multiSort.value, event)
       if (active) {
         if (mode === 'prepend') {
-          newSortBy.unshift({ key: column.key, order: 'asc' })
+          newSortBy.unshift({ key: column.key, order: initialOrder })
         } else {
-          newSortBy.push({ key: column.key, order: 'asc' })
+          newSortBy.push({ key: column.key, order: initialOrder })
         }
       } else {
-        newSortBy = [{ key: column.key, order: 'asc' }]
+        newSortBy = [{ key: column.key, order: initialOrder }]
       }
-    } else if (item.order === 'desc') {
+    } else if (item.order === secondaryOrder) {
       if (mustSort.value && newSortBy.length === 1) {
-        item.order = 'asc'
+        item.order = initialSortOrder.value
       } else {
         newSortBy = newSortBy.filter(x => x.key !== column.key)
       }
     } else {
-      item.order = 'desc'
+      item.order = secondaryOrder
     }
 
     sortBy.value = newSortBy