feat: add default_sort option to sortable fields (#7665)

martinjagodic · web-flow · commit 5e782ee33ab7 · 2025-12-04T14:51:44.000Z
diff --git a/dev-test/config.yml b/dev-test/config.yml
@@ -19,6 +19,10 @@ collections: # A list of collections the CMS should be able to edit
     create: true # Allow users to create new documents in this collection
     editor:
       visualEditing: true
+    sortable_fields:
+      - title
+      - { field: date, default_sort: desc }
+      - draft
     view_filters:
       - label: Posts With Index
         field: title
diff --git a/dev-test/index.html b/dev-test/index.html
@@ -50,11 +50,17 @@
   }
 
   var ONE_DAY = 60 * 60 * 24 * 1000;
+  var ONE_WEEK = ONE_DAY * 7;
 
   for (var i=1; i<=20; i++) {
     var date = new Date();
 
-    date.setTime(date.getTime() + ONE_DAY);
+    if (i % 2 === 0) {
+      date.setTime(date.getTime() + ONE_DAY);
+    } else {
+      date.setTime(date.getTime() - ONE_WEEK);
+    }
+
     var month = ('0' + (date.getMonth()+1)).slice(-2)
     var day = ('0' + (date.getDate())).slice(-2)
     var dateString = '' + date.getFullYear() + '-' + month + '-' + day;
diff --git a/packages/decap-cms-core/index.d.ts b/packages/decap-cms-core/index.d.ts
@@ -292,6 +292,12 @@ declare module 'decap-cms-core' {
     pattern?: string;
   }
 
+  export interface SortableField {
+    field: string;
+    label?: string;
+    default_sort?: boolean | 'asc' | 'desc';
+  }
+
   export interface CmsCollection {
     name: string;
     label: string;
@@ -332,15 +338,15 @@ declare module 'decap-cms-core' {
     path?: string;
     media_folder?: string;
     public_folder?: string;
-    sortable_fields?: string[];
+    sortable_fields?: (string | SortableField)[];
     view_filters?: ViewFilter[];
     view_groups?: ViewGroup[];
     i18n?: boolean | CmsI18nConfig;
 
     /**
      * @deprecated Use sortable_fields instead
      */
-    sortableFields?: string[];
+    sortableFields?: (string | SortableField)[];
   }
 
   export interface CmsBackend {
diff --git a/packages/decap-cms-core/src/actions/__tests__/config.spec.js b/packages/decap-cms-core/src/actions/__tests__/config.spec.js
@@ -480,7 +480,7 @@ describe('config', () => {
       ).toEqual({
         collections: [
           {
-            sortable_fields: ['title'],
+            sortable_fields: [{ field: 'title', default_sort: undefined }],
             folder: 'src',
             type: 'folder_based_collection',
             view_filters: [],
diff --git a/packages/decap-cms-core/src/actions/config.ts b/packages/decap-cms-core/src/actions/config.ts
@@ -171,6 +171,20 @@ function hasIntegration(config: CmsConfig, collection: CmsCollection) {
   return !!integration;
 }
 
+function normalizeSortableFields(
+  sortableFields: (
+    | string
+    | { field: string; label?: string; default_sort?: boolean | 'asc' | 'desc' }
+  )[],
+) {
+  return sortableFields.map(field => {
+    if (typeof field === 'string') {
+      return { field, default_sort: undefined };
+    }
+    return field;
+  });
+}
+
 export function normalizeConfig(config: CmsConfig) {
   const { collections = [] } = config;
 
@@ -200,6 +214,14 @@ export function normalizeConfig(config: CmsConfig) {
       );
     }
 
+    // Normalize sortable_fields to consistent object format
+    if (normalizedCollection.sortable_fields) {
+      normalizedCollection = {
+        ...normalizedCollection,
+        sortable_fields: normalizeSortableFields(normalizedCollection.sortable_fields),
+      };
+    }
+
     return normalizedCollection;
   });
 
diff --git a/packages/decap-cms-core/src/actions/entries.ts b/packages/decap-cms-core/src/actions/entries.ts
@@ -3,7 +3,7 @@ import isEqual from 'lodash/isEqual';
 import { Cursor } from 'decap-cms-lib-util';
 
 import { selectCollectionEntriesCursor } from '../reducers/cursors';
-import { selectFields, updateFieldByKey } from '../reducers/collections';
+import { selectFields, updateFieldByKey, selectDefaultSortField } from '../reducers/collections';
 import { selectIntegration, selectPublishedSlugs } from '../reducers';
 import { getIntegrationProvider } from '../integrations';
 import { currentBackend } from '../backend';
@@ -579,11 +579,21 @@ export function loadEntries(collection: Collection, page = 0) {
     }
     const state = getState();
     const sortFields = selectEntriesSortFields(state.entries, collection.get('name'));
+
+    // If user has already set a sort, use it
     if (sortFields && sortFields.length > 0) {
       const field = sortFields[0];
       return dispatch(sortByField(collection, field.get('key'), field.get('direction')));
     }
 
+    // Otherwise, check for a default sort field in the collection configuration
+    const defaultSort = selectDefaultSortField(collection);
+    if (defaultSort) {
+      const direction =
+        defaultSort.direction === 'desc' ? SortDirection.Descending : SortDirection.Ascending;
+      return dispatch(sortByField(collection, defaultSort.field, direction));
+    }
+
     const backend = currentBackend(state.config);
     const integration = selectIntegration(state, collection.get('name'), 'listEntries');
     const provider = integration
diff --git a/packages/decap-cms-core/src/constants/__tests__/configSchema.spec.js b/packages/decap-cms-core/src/constants/__tests__/configSchema.spec.js
@@ -216,6 +216,90 @@ describe('config', () => {
       }).toThrowError("'collections[0]' must NOT be valid");
     });
 
+    it('should allow sortable_fields to have object format with field property', () => {
+      expect(() => {
+        validateConfig(
+          merge({}, validConfig, {
+            collections: [{ sortable_fields: [{ field: 'title' }] }],
+          }),
+        );
+      }).not.toThrow();
+    });
+
+    it('should allow sortable_fields with default_sort as boolean', () => {
+      expect(() => {
+        validateConfig(
+          merge({}, validConfig, {
+            collections: [{ sortable_fields: [{ field: 'title', default_sort: true }] }],
+          }),
+        );
+      }).not.toThrow();
+    });
+
+    it('should allow sortable_fields with default_sort as asc/desc', () => {
+      expect(() => {
+        validateConfig(
+          merge({}, validConfig, {
+            collections: [{ sortable_fields: ['title', { field: 'date', default_sort: 'desc' }] }],
+          }),
+        );
+      }).not.toThrow();
+    });
+
+    it('should allow sortable_fields with custom label', () => {
+      expect(() => {
+        validateConfig(
+          merge({}, validConfig, {
+            collections: [{ sortable_fields: [{ field: 'date', label: 'Publish Date' }] }],
+          }),
+        );
+      }).not.toThrow();
+    });
+
+    it('should allow sortable_fields with label and default_sort', () => {
+      expect(() => {
+        validateConfig(
+          merge({}, validConfig, {
+            collections: [
+              {
+                sortable_fields: [
+                  'title',
+                  { field: 'date', label: 'Publish Date', default_sort: 'desc' },
+                ],
+              },
+            ],
+          }),
+        );
+      }).not.toThrow();
+    });
+
+    it('should allow mixed string and object format in sortable_fields', () => {
+      expect(() => {
+        validateConfig(
+          merge({}, validConfig, {
+            collections: [{ sortable_fields: ['title', { field: 'date', default_sort: true }] }],
+          }),
+        );
+      }).not.toThrow();
+    });
+
+    it('should throw if more than one sortable field has default_sort property', () => {
+      expect(() => {
+        validateConfig(
+          merge({}, validConfig, {
+            collections: [
+              {
+                sortable_fields: [
+                  { field: 'title', default_sort: true },
+                  { field: 'date', default_sort: true },
+                ],
+              },
+            ],
+          }),
+        );
+      }).toThrowError('only one sortable field can have the default_sort property');
+    });
+
     it('should throw if collection names are not unique', () => {
       expect(() => {
         validateConfig(
diff --git a/packages/decap-cms-core/src/constants/configSchema.js b/packages/decap-cms-core/src/constants/configSchema.js
@@ -253,7 +253,21 @@ function getConfigSchema() {
             sortable_fields: {
               type: 'array',
               items: {
-                type: 'string',
+                oneOf: [
+                  { type: 'string' },
+                  {
+                    type: 'object',
+                    properties: {
+                      field: { type: 'string' },
+                      label: { type: 'string' },
+                      default_sort: {
+                        oneOf: [{ type: 'boolean' }, { type: 'string', enum: ['asc', 'desc'] }],
+                      },
+                    },
+                    required: ['field'],
+                    additionalProperties: false,
+                  },
+                ],
               },
             },
             sortableFields: {
@@ -405,4 +419,23 @@ export function validateConfig(config) {
     console.error('Config Errors', errors);
     throw new ConfigError(errors);
   }
+
+  // Custom validation: only one sortable field can have default_sort property
+  if (config.collections) {
+    config.collections.forEach((collection, index) => {
+      if (collection.sortable_fields) {
+        const defaultFields = collection.sortable_fields.filter(
+          field => typeof field === 'object' && field.default_sort !== undefined,
+        );
+        if (defaultFields.length > 1) {
+          const error = {
+            instancePath: `/collections/${index}/sortable_fields`,
+            message: 'only one sortable field can have the default_sort property',
+          };
+          console.error('Config Errors', [error]);
+          throw new ConfigError([error]);
+        }
+      }
+    });
+  }
 }
diff --git a/packages/decap-cms-core/src/reducers/collections.ts b/packages/decap-cms-core/src/reducers/collections.ts
@@ -412,30 +412,77 @@ export function selectDefaultSortableFields(
     defaultSortable = [COMMIT_DATE, ...defaultSortable];
   }
 
-  return defaultSortable as string[];
+  // Return as objects with field property
+  return defaultSortable.map(field => ({ field })) as {
+    field: string;
+    label?: string;
+    default_sort?: boolean | 'asc' | 'desc';
+  }[];
 }
 
 export function selectSortableFields(collection: Collection, t: (key: string) => string) {
   const fields = collection
     .get('sortable_fields')
     .toArray()
-    .map(key => {
+    .map(sortableField => {
+      // Extract the field name and custom label from the sortable field object
+      const key = sortableField.get('field');
+      const customLabel = sortableField.get('label');
+
       if (key === COMMIT_DATE) {
-        return { key, field: { name: key, label: t('collection.defaultFields.updatedOn.label') } };
+        const label = customLabel || t('collection.defaultFields.updatedOn.label');
+        return { key, field: { name: key, label } };
       }
       const field = selectField(collection, key);
       if (key === COMMIT_AUTHOR && !field) {
-        return { key, field: { name: key, label: t('collection.defaultFields.author.label') } };
+        const label = customLabel || t('collection.defaultFields.author.label');
+        return { key, field: { name: key, label } };
+      }
+
+      let fieldObj: Record<string, unknown> | undefined = field?.toJS();
+
+      // If custom label is provided, override the field's label
+      if (fieldObj && customLabel) {
+        fieldObj = { ...fieldObj, label: customLabel };
       }
 
-      return { key, field: field?.toJS() };
+      // If no label exists at all, use the field name
+      if (fieldObj && !fieldObj.label) {
+        fieldObj = { ...fieldObj, label: (fieldObj.name as string) || key };
+      }
+
+      return { key, field: fieldObj };
     })
     .filter(item => !!item.field)
     .map(item => ({ ...item.field, key: item.key }));
 
   return fields;
 }
 
+export function selectDefaultSortField(collection: Collection) {
+  const sortableFields = collection.get('sortable_fields').toArray();
+  const defaultField = sortableFields.find(field => field.get('default_sort') !== undefined);
+
+  if (!defaultField) {
+    return null;
+  }
+
+  const fieldName = defaultField.get('field');
+  const defaultSortValue = defaultField.get('default_sort');
+
+  // Determine direction based on default_sort value
+  let direction;
+  if (defaultSortValue === true || defaultSortValue === 'asc') {
+    direction = 'asc';
+  } else if (defaultSortValue === 'desc') {
+    direction = 'desc';
+  } else {
+    direction = 'asc'; // fallback
+  }
+
+  return { field: fieldName, direction };
+}
+
 export function selectSortDataPath(collection: Collection, key: string) {
   if (key === COMMIT_DATE) {
     return 'updatedOn';
diff --git a/packages/decap-cms-core/src/types/redux.ts b/packages/decap-cms-core/src/types/redux.ts
@@ -309,6 +309,12 @@ export interface ViewGroup {
   id: string;
 }
 
+export interface SortableField {
+  field: string;
+  label?: string;
+  default_sort?: boolean | 'asc' | 'desc';
+}
+
 export interface CmsCollection {
   name: string;
   label: string;
@@ -348,15 +354,15 @@ export interface CmsCollection {
   path?: string;
   media_folder?: string;
   public_folder?: string;
-  sortable_fields?: string[];
+  sortable_fields?: (string | SortableField)[];
   view_filters?: ViewFilter[];
   view_groups?: ViewGroup[];
   i18n?: boolean | CmsI18nConfig;
 
   /**
    * @deprecated Use sortable_fields instead
    */
-  sortableFields?: string[];
+  sortableFields?: (string | SortableField)[];
 }
 
 export interface CmsBackend {
@@ -635,7 +641,7 @@ type CollectionObject = {
   slug?: string;
   label_singular?: string;
   label: string;
-  sortable_fields: List<string>;
+  sortable_fields: List<StaticallyTypedRecord<SortableField>>;
   view_filters: List<StaticallyTypedRecord<ViewFilter>>;
   view_groups: List<StaticallyTypedRecord<ViewGroup>>;
   nested?: Nested;

Original file line number	Diff line number	Diff line change
`@@ -480,7 +480,7 @@ describe('config', () => {`
`480`	`480`	`).toEqual({`
`481`	`481`	`collections: [`
`482`	`482`	`{`
`483`		`- sortable_fields: ['title'],`
	`483`	`+ sortable_fields: [{ field: 'title', default_sort: undefined }],`
`484`	`484`	`folder: 'src',`
`485`	`485`	`type: 'folder_based_collection',`
`486`	`486`	`view_filters: [],`