feat: Add 'sort by heading' (#1423)

* refactor: Move FilenameField.comparator() down to TextField for re-use.

Derived classes would still need to enable sorting with supportsSorting() returning true
to enable this comparator.

* feat: Add 'sort by heading'

Author: claremacrae

docs/queries/sorting.md

@@ -40,7 +40,9 @@ File locations:
 
 File contents:
 
-None yet.
+1. `sort by heading` (the heading preceding the task; files with empty headings sort before other tasks)
+
+> `sort by heading` was introduced in Tasks 1.21.0.
 
 Task date properties:
 

docs/quick-reference/index.md

@@ -31,7 +31,7 @@ This table summarizes the filters and other options available inside a `tasks` b
 |                                                                                                                                                                                                     |                                             | `group by root`       |                        |
 |                                                                                                                                                                                                     |                                             | `group by folder`     |                        |
 | `filename (includes, does not include) <filename>`<br>`filename (regex matches, regex does not match) /regex/i`                                                                                     | `sort by filename`                          | `group by filename`   |                        |
-| `heading (includes, does not include) <string>`<br>`heading (regex matches, regex does not match) /regex/i`                                                                                         |                                             | `group by heading`    |                        |
+| `heading (includes, does not include) <string>`<br>`heading (regex matches, regex does not match) /regex/i`                                                                                         | `sort by heading`                           | `group by heading`    |                        |
 |                                                                                                                                                                                                     |                                             | `group by backlink`   | `hide backlink`        |
 | `description (includes, does not include) <string>`<br>`description (regex matches, regex does not match) /regex/i`                                                                                 | `sort by description`                       |                       |                        |
 | `tag (includes, does not include) <tag>`<br>`tags (include, do not include) <tag>`<br>`tag (regex matches, regex does not match) /regex/i`<br>`tags (regex matches, regex does not match) /regex/i` | `sort by tag`<br>`sort by tag <tag_number>` | `group by tags`       |                        |

src/Query/Filter/FilenameField.ts

@@ -1,5 +1,4 @@
 import type { Task } from '../../Task';
-import type { Comparator } from '../Sorting';
 import { TextField } from './TextField';
 
 /** Support the 'filename' search instruction.
@@ -29,10 +28,4 @@ export class FilenameField extends TextField {
     supportsSorting(): boolean {
         return true;
     }
-
-    comparator(): Comparator {
-        return (a: Task, b: Task) => {
-            return this.value(a).localeCompare(this.value(b));
-        };
-    }
 }

src/Query/Filter/HeadingField.ts

@@ -21,4 +21,8 @@ export class HeadingField extends TextField {
             return '';
         }
     }
+
+    supportsSorting(): boolean {
+        return true;
+    }
 }

src/Query/Filter/TextField.ts

@@ -3,6 +3,7 @@ import { SubstringMatcher } from '../Matchers/SubstringMatcher';
 import { RegexMatcher } from '../Matchers/RegexMatcher';
 import type { IStringMatcher } from '../Matchers/IStringMatcher';
 import { Explanation } from '../Explain/Explanation';
+import type { Comparator } from '../Sorting';
 import { Field } from './Field';
 import type { FilterFunction } from './Filter';
 import { Filter, FilterOrErrorMessage } from './Filter';
@@ -89,4 +90,17 @@ export abstract class TextField extends Field {
             return negate ? !match : match;
         };
     }
+
+    /**
+     * A default implementation of sorting, for text fields where simple locale-aware sorting is the
+     * desired behaviour.
+     *
+     * Each class that wants to use this will need to override supportsSorting() to return true,
+     * to turn on sorting.
+     */
+    comparator(): Comparator {
+        return (a: Task, b: Task) => {
+            return this.value(a).localeCompare(this.value(b));
+        };
+    }
 }

tests/Query.test.ts

@@ -133,6 +133,7 @@ describe('Query parsing', () => {
             'sort by due',
             'sort by filename',
             'sort by happens',
+            'sort by heading',
             'sort by path reverse',
             'sort by path',
             'sort by priority reverse',

tests/Query/Filter/HeadingField.test.ts

@@ -3,6 +3,7 @@ import type { FilterOrErrorMessage } from '../../../src/Query/Filter/Filter';
 import { TaskBuilder } from '../../TestingTools/TaskBuilder';
 import { testFilter } from '../../TestingTools/FilterTestHelpers';
 import { toBeValid, toMatchTaskWithHeading } from '../../CustomMatchers/CustomMatchersForFilters';
+import * as CustomMatchersForSorting from '../../CustomMatchers/CustomMatchersForSorting';
 
 function testTaskFilterForHeading(filter: FilterOrErrorMessage, precedingHeader: string | null, expected: boolean) {
     const builder = new TaskBuilder();
@@ -64,3 +65,34 @@ describe('heading', () => {
         expect(filter).not.toMatchTaskWithHeading('SoMe InteResting HeaDing');
     });
 });
+
+describe('sorting by heading', () => {
+    it('supports Field sorting methods correctly', () => {
+        const field = new HeadingField();
+        expect(field.supportsSorting()).toEqual(true);
+    });
+
+    // Helper function to create a task with a given path
+    function with_heading(heading: string) {
+        return new TaskBuilder().precedingHeader(heading).build();
+    }
+
+    it('sort by heading', () => {
+        // Arrange
+        const sorter = new HeadingField().createNormalSorter();
+
+        // Assert
+        CustomMatchersForSorting.expectTaskComparesBefore(sorter, with_heading('Heading 1'), with_heading('Heading 2'));
+        CustomMatchersForSorting.expectTaskComparesBefore(sorter, with_heading(''), with_heading('Non-empty heading')); // Empty heading comes first
+        // Beginning with numbers
+        CustomMatchersForSorting.expectTaskComparesBefore(sorter, with_heading('1 Stuff'), with_heading('2 Stuff'));
+        CustomMatchersForSorting.expectTaskComparesBefore(sorter, with_heading('11 Stuff'), with_heading('9 Stuff')); // TODO want 11 to compare after 9
+    });
+
+    it('sort by heading reverse', () => {
+        // Single example just to prove reverse works.
+        // (There's no need to repeat all the examples above)
+        const sorter = new HeadingField().createReverseSorter();
+        CustomMatchersForSorting.expectTaskComparesAfter(sorter, with_heading('Heading 1'), with_heading('Heading 2'));
+    });
+});