Summary

This PR adds support for default sorting on collection views with enhanced sortable_fields configuration options.

Motivation:

Previously, when users defined sortable_fields for a collection, they would see an unsorted list on the first load. Users had to manually select their preferred sort order every time they opened a collection, or rely on localStorage to remember their previous selection. This PR introduces the ability to define a default sort order that will be applied on the first view of a collection, improving the user experience by showing entries in a meaningful order immediately.

Additionally, this PR enhances sortable_fields to support custom labels, making the sort dropdown more user-friendly when field names don't match what users expect to see in the UI.

What's New:

1. Default Sort Field: You can now specify which field should be used for sorting by default and in which direction (asc or desc)
2. Custom Labels: Define custom display labels for sortable fields instead of showing the raw field name
3. Enhanced Object Format: sortable_fields now supports both the existing string format and a new object format with additional properties
4. Backward Compatible: All existing configurations continue to work without changes

How to Use:

String Format - Existing

collections:
  - name: posts
    sortable_fields: [title, date, author]

Object Format - New

collections:
  - name: posts
    sortable_fields:
      - title      # you can mix string and object formats
      - field: date
        label: 'Publish Date' # Custom label shown in UI
        default_sort: desc.   # Default sort: newest first
      - field: author
        label: 'Author Name'

Object Format Properties

When using the object format, you can specify:

• field (required): The name of the field to sort by
• label (optional): Custom label to display in the sort dropdown
  • If omitted, falls back to the field's label, then the field name
• default_sort (optional): Sets this field as the default sort
  • true or 'asc': Sort ascending (A-Z, oldest first)
  • 'desc': Sort descending (Z-A, newest first)
  • Only ONE field can have the default_sort property per collection

Validation Rules

• Only one default: If you specify default_sort on multiple fields, you'll get a validation error:

  Config Error: only one sortable field can have the default_sort property
  

• User preferences take priority: Once a user manually selects a sort order, their preference is saved in localStorage and will override the default on subsequent visits

Complete Example

collections:
  - name: posts
    label: Blog Posts
    folder: content/posts
    sortable_fields:
      - title
      - field: date
        label: 'Publication Date'
        default_sort: desc  # Show newest posts first by default
      - field: author
        label: 'Author Name'
      - draft
    fields:
      - { label: Title, name: title, widget: string }
      - { label: Date, name: date, widget: datetime }
      - { label: Author, name: author, widget: string }
      - { label: Draft, name: draft, widget: boolean }

With this configuration:

• The collection will show posts sorted by date (newest first) on first load
• The sort dropdown will show "Publication Date" instead of "date"
• The sort dropdown will show "Author Name" instead of "author"
• Users can change the sort order, and their preference will be remembered
• Both sortable_fields and the deprecated sortableFields work with all new features

Test plan

Unit Tests:

• ✅ All existing tests pass
• ✅ Added 5 new schema validation tests:
  • Validates string format (existing functionality)
  • Validates object format with all properties
  • Validates custom labels
  • Validates default_sort boolean and enum values
  • Validates error when multiple fields have default_sort

Manual Testing:

1. Default Sort Behavior:

   # Start dev server
   npm start
   
   # Open http://localhost:8080/
   # Navigate to Posts collection
   # Verify: Entries are sorted by date (newest first) by default

2. Custom Labels:

   • Open sort dropdown in Posts collection
   • Verify: Shows "Publish Date" instead of "date"

3. User Preference Persistence:

   • Change sort to "Title"
   • Refresh the page
   • Verify: Sort remains on "Title" (user preference saved)
   • Clear localStorage and refresh
   • Verify: Sort returns to default (date descending)

4. Validation:

   • Test config with multiple default_sort fields
   • Verify: Validation error is shown with clear message

Example Configuration:

See /dev-test/config.yml for a working example:

sortable_fields:
  - title
  - { field: date, default_sort: desc }
  - draft

Type Safety:

TypeScript definitions updated in:

• /packages/decap-cms-core/index.d.ts - Public API types
• /packages/decap-cms-core/src/types/redux.ts - Internal types

Both sortable_fields and deprecated sortableFields support the full type:

sortable_fields?: (string | SortableField)[];
sortableFields?: (string | SortableField)[];  // deprecated but fully supported

interface SortableField {
  field: string;
  label?: string;
  default_sort?: boolean | 'asc' | 'desc';
}

Checklist

Please add a x inside each checkbox:

• I have read the contribution guidelines.
• All existing tests pass
• New tests added for new functionality
• TypeScript definitions updated
• Backward compatible with existing configurations
• Documentation included in PR description

A picture of a cute animal (not mandatory but encouraged)