Merge pull request #1958 from ilandikov/feat-next-recurrence-on-line-below

feat: Optionally put next recurrence below current task

Author: claremacrae

docs/Getting Started/Recurring Tasks.md

@@ -12,7 +12,11 @@ For example: `🔁 every weekday` means the task will repeat every week on Monda
 Every recurrence rule has to start with the word `every`.
 
 When you toggle the status of a recurring task to anything but "todo" (i.e. "done"), the original task that you wanted to toggle will be marked as done and get the done date appended to it, like any other task.
-In addition, _a new task will be put one line above the original task._
+
+In addition, _a new task will be put one line above the original task_ by default.
+
+See [[#Location of the new task]] below, for how to change this behaviour and make the new task appear _on the line below the original task_.
+
 The new task will have updated dates based off the original task.
 
 ### Basic Example
@@ -70,6 +74,17 @@ You can validate that tasks understands your rule by using the `Tasks: Create or
 
 ---
 
+## Location of the new task
+
+Use this setting to control where the recurring task is inserted. The default is to put the new task before the original one.
+
+![Setting for next recurrence appearance](../../images/settings-recurrence-location.png)
+
+> [!released]
+> Control of the location of the new task was introduced in Tasks X.Y.Z
+
+---
+
 ## Repeating a Task Based on the Original Due Date or the Completion Date
 
 When you create a recurring task, you can decide whether the next occurrence should be based on the original dates or the date when you completed the task.

docs/Getting Started/Settings.md

@@ -26,5 +26,6 @@ For convenience, here is a list of all those documentation pages (in the order t
 - [[Global Query]]
 - [[Status Settings]]
 - [[Dates#Date-tracking settings]]
+- [[Recurring Tasks#Location of the new task]]
 - [[Auto-Suggest]]
 - [[Create or edit Task#Turning off keyboard shortcuts]]

docs/images/settings-recurrence-location.png

@@ -72,7 +72,7 @@ export const toggleLine = (line: string, path: string): EditorInsertion => {
         fallbackDate: null, // We don't need this to toggle it here in the editor.
     });
     if (task !== null) {
-        const lines = task.toggle().map((t) => t.toFileLineString());
+        const lines = task.toggleWithRecurrenceInUsersOrder().map((t) => t.toFileLineString());
         return { text: lines.join('\n'), moveTo: { line: lines.length - 1 } };
     } else {
         // If the task is null this means that we have one of:

src/Commands/ToggleDone.ts

@@ -62,6 +62,7 @@ export interface Settings {
     provideAccessKeys: boolean;
     useFilenameAsScheduledDate: boolean;
     filenameAsDateFolders: string[];
+    recurrenceOnNextLine: boolean;
 
     // The custom status states.
     statusSettings: StatusSettings;
@@ -91,6 +92,7 @@ const defaultSettings: Settings = {
     provideAccessKeys: true,
     useFilenameAsScheduledDate: false,
     filenameAsDateFolders: [],
+    recurrenceOnNextLine: false,
     statusSettings: new StatusSettings(),
     features: Feature.settingsFlags,
     generalSettings: {

src/Config/Settings.ts

@@ -223,6 +223,23 @@ export class SettingsTab extends PluginSettingTab {
                     });
             });
 
+        // ---------------------------------------------------------------------------
+        containerEl.createEl('h4', { text: 'Recurring task Settings' });
+        // ---------------------------------------------------------------------------
+
+        new Setting(containerEl)
+            .setName('Next recurrence appears on the line below')
+            .setDesc(
+                'Enabling this will make the next recurrence of a task appear on the line below the completed task. Otherwise the next recurrence will appear before the completed one.',
+            )
+            .addToggle((toggle) => {
+                const { recurrenceOnNextLine: recurrenceOnNextLine } = getSettings();
+                toggle.setValue(recurrenceOnNextLine).onChange(async (value) => {
+                    updateSettings({ recurrenceOnNextLine: value });
+                    await this.plugin.saveSettings();
+                });
+            });
+
         // ---------------------------------------------------------------------------
         containerEl.createEl('h4', { text: 'Auto-suggest Settings' });
         // ---------------------------------------------------------------------------

src/Config/SettingsTab.ts

@@ -75,7 +75,7 @@ class LivePreviewExtension implements PluginValue {
         event.preventDefault();
 
         // Clicked on a task's checkbox. Toggle the task and set it.
-        const toggled = task.toggle();
+        const toggled = task.toggleWithRecurrenceInUsersOrder();
         const toggledString = toggled.map((t) => t.toFileLineString()).join(state.lineBreak);
 
         // Creates a CodeMirror transaction in order to update the document.

src/LivePreviewExtension.ts

@@ -291,12 +291,20 @@ export class Task {
     }
 
     /**
-     * Toggles this task and returns the resulting tasks.
+     * Toggles this task and returns the resulting task(s).
+     *
+     * Use this method if you need to know which is the original (completed)
+     * task and which is the new recurrence.
+     *
+     * If the task is not recurring, it will return `[toggled]`.
      *
      * Toggling can result in more than one returned task in the case of
-     * recurrence. If it is a recurring task, the toggled task will be returned
-     * together with the next occurrence in the order `[next, toggled]`. If the
-     * task is not recurring, it will return `[toggled]`.
+     * recurrence. In this case, the toggled task will be returned
+     * together with the next occurrence in the order `[next, toggled]`.
+     *
+     * There is a possibility to use user set order `[next, toggled]`
+     * or `[toggled, next]` - {@link toggleWithRecurrenceInUsersOrder}.
+     *
      */
     public toggle(): Task[] {
         const newStatus = StatusRegistry.getInstance().getNextStatusOrCreate(this.status);
@@ -356,6 +364,30 @@ export class Task {
         return newTasks;
     }
 
+    /**
+     * Toggles this task and returns the resulting task(s).
+     *
+     * Use this method if the updated task(s) are to be saved,
+     * as this honours the user setting to control the order
+     * the tasks should be saved in.
+     *
+     * If the task is not recurring, it will return `[toggled]`.
+     *
+     * Toggling can result in more than one returned task in the case of
+     * recurrence. In this case, the toggled task will be returned in
+     * user set order `[next, toggled]` or `[toggled, next]` depending
+     * on {@link Settings}.
+     *
+     * If there is no need to consider user settings call {@link toggle}.
+     *
+     */
+    public toggleWithRecurrenceInUsersOrder(): Task[] {
+        const newTasks = this.toggle();
+
+        const { recurrenceOnNextLine: recurrenceOnNextLine } = getSettings();
+        return recurrenceOnNextLine ? newTasks.reverse() : newTasks;
+    }
+
     public get urgency(): number {
         if (this._urgency === null) {
             this._urgency = Urgency.calculate(this);

src/Task.ts

@@ -89,7 +89,7 @@ export async function renderTaskLine(
 
         // Should be re-rendered as enabled after update in file.
         checkbox.disabled = true;
-        const toggledTasks = task.toggle();
+        const toggledTasks = task.toggleWithRecurrenceInUsersOrder();
         replaceTaskWithTasks({
             originalTask: task,
             newTasks: toggledTasks,

src/TaskLineRenderer.ts

@@ -1122,6 +1122,60 @@ describe('set correct created date on reccurence task', () => {
     });
 });
 
+describe('next task recurrence appearance', () => {
+    beforeAll(() => {
+        jest.useFakeTimers();
+        jest.setSystemTime(new Date(2023, 5 - 1, 16));
+        resetSettings();
+    });
+
+    afterAll(() => {
+        jest.useRealTimers();
+        resetSettings();
+    });
+
+    it('new task shall appear on previous line by default', () => {
+        // Arrange
+        const task = fromLine({ line: '- [ ] this is a recurring task 🔁 every day' });
+
+        // Act
+        const lines = task.toggleWithRecurrenceInUsersOrder().map((t) => t.toFileLineString());
+
+        // Assert
+        expect(lines.length).toEqual(2);
+        expect(lines[0]).toMatchInlineSnapshot('"- [ ] this is a recurring task 🔁 every day"');
+        expect(lines[1]).toMatchInlineSnapshot('"- [x] this is a recurring task 🔁 every day ✅ 2023-05-16"');
+    });
+
+    it('new task shall appear on next line with the setting set to false', () => {
+        // Arrange
+        const task = fromLine({ line: '- [ ] this is a recurring task 🔁 every day' });
+        updateSettings({ recurrenceOnNextLine: false });
+
+        // Act
+        const lines = task.toggleWithRecurrenceInUsersOrder().map((t) => t.toFileLineString());
+
+        // Assert
+        expect(lines.length).toEqual(2);
+        expect(lines[0]).toMatchInlineSnapshot('"- [ ] this is a recurring task 🔁 every day"');
+        expect(lines[1]).toMatchInlineSnapshot('"- [x] this is a recurring task 🔁 every day ✅ 2023-05-16"');
+    });
+
+    it('new task shall appear on next line with the setting set to true', () => {
+        // Arrange
+        const task = fromLine({ line: '- [ ] this is a recurring task 🔁 every day' });
+        updateSettings({ recurrenceOnNextLine: true });
+
+        // Act
+        const lines = task.toggleWithRecurrenceInUsersOrder().map((t) => t.toFileLineString());
+
+        // Assert
+        expect(lines.length).toEqual(2);
+        expect(lines[0]).toMatchInlineSnapshot('"- [x] this is a recurring task 🔁 every day ✅ 2023-05-16"');
+        expect(lines[1]).toMatchInlineSnapshot('"- [ ] this is a recurring task 🔁 every day"');
+    });
+});
+
 declare global {
     namespace jest {
         interface Matchers<R> {