Merge pull request #3528 from justise/edit-modal-api-v2

feat: Add the ability to launch the task modal to edit an existing line

Author: claremacrae

docs/Advanced/Tasks Api.md

@@ -34,6 +34,16 @@ export interface TasksApiV1 {
      */
     createTaskLineModal(): Promise<string>;
 
+    /**
+     * Opens the Tasks UI pre-filled with the provided task line for editing.
+     * Does not edit the task line in the file, but returns the edited task line as a Markdown string.
+     *
+     * @param taskLine The markdown string of the task line to edit
+     * @returns {Promise<string>} A promise that contains the Markdown string for the edited task or
+     * an empty string in the case where the data entry was cancelled.
+     */
+    editTaskLineModal(taskLine: string): Promise<string>;
+
     /**
      * Executes the 'Tasks: Toggle task done' command on the supplied line string
      *
@@ -55,8 +65,6 @@ This method was introduced in Tasks 2.0.0.
 This method opens the Tasks [[Create or edit Task|Create or edit task UI]] and returns the Markdown for the task entered.
 If data entry is cancelled, an empty string is returned.
 
-### Basic usage
-
 ```javascript
 const tasksApi = this.app.plugins.plugins['obsidian-tasks-plugin'].apiV1;
 let taskLine = await tasksApi.createTaskLineModal();
@@ -82,6 +90,26 @@ to automatically add tasks to a specific file.
 
 See [[QuickAdd#Launching the Edit task modal via QuickAdd|Launching the Edit task modal via QuickAdd]] for full details of how to do this.
 
+## `editTaskLineModal(taskLine: string): Promise<string>;`
+
+> [!released]
+This method was introduced in Tasks X.X.X.
+
+This method opens the Tasks [[Create or edit Task|Create or edit task UI]] with the provided task line pre-filled for editing.  
+If data entry is cancelled, an empty string is returned.
+
+```javascript
+const tasksApi = this.app.plugins.plugins['obsidian-tasks-plugin'].apiV1;
+let editedTaskLine = await tasksApi.editTaskLineModal('- [ ] My existing task');
+
+// Do whatever you want with the returned value.
+// It's just a string containing the Markdown for the edited task.
+console.log(editedTaskLine);
+```
+
+> [!warning]
+> This function returns a `Promise` - always `await` the result!
+
 ## `executeToggleTaskDoneCommand: (line: string, path: string) => string;`
 
 > [!released]
@@ -149,8 +177,6 @@ This can be used, for example, to display the Auto-Suggest on non-task lines. [S
 
 ## Limitations of the Tasks API
 
-- Editing tasks:
-  - It is not yet possible to use the API to edit an *existing task line* with Tasks [[Create or edit Task|Create or edit task UI]]. We are tracking this in [issue #1945](https://github.com/obsidian-tasks-group/obsidian-tasks/issues/1945).
 - Auto Suggest:
   - It is not yet possible for [[auto-suggest]] to add [[Task Dependencies|dependencies]] when Auto-Suggest is used in [[Kanban plugin]] cards - or any other plugins that use the [[Tasks Api#Auto-Suggest Integration|Auto-Suggest Integration]]. We are tracking this in [issue #3274](https://github.com/obsidian-tasks-group/obsidian-tasks/issues/3274).
 - Searching tasks:

docs/Other Plugins/QuickAdd.md

@@ -1,14 +1,14 @@
 ---
 publish: true
 aliases:
-  - Advanced/Quickadd
+    - Advanced/Quickadd
 ---
 
 # QuickAdd
 
 <span class="related-pages">#plugin/quickadd</span>
 
-## Launching the Edit task modal via QuickAdd
+## Launching the Create task modal via QuickAdd
 
 This section shows how to use QuickAdd with the [[Create or edit Task]] modal to automatically add tasks to a specific file.
 
@@ -24,7 +24,7 @@ Or if you would like a newline character to be added after your new task line, u
 
 ````markdown
 ```js quickadd
-return await this.app.plugins.plugins['obsidian-tasks-plugin'].apiV1.createTaskLineModal() + '\n';
+return (await this.app.plugins.plugins['obsidian-tasks-plugin'].apiV1.createTaskLineModal()) + '\n';
 ```
 ````
 

resources/sample_vaults/Tasks-Demo/Manual Testing/QuickAdd Tasks API Demo.md

@@ -11,3 +11,43 @@ It's modified to:
 ## New Tasks
 
 - [ ] #task Test task added via the API!
+
+# Smoke Testing the Edit Task API
+
+You can quickly verify that the `editTaskLineModal()` API works as expected using the Obsidian developer console.
+
+You can test the API directly in the Obsidian console
+
+1. Open the developer console in Obsidian (Cmd+Opt+I on Mac).
+2. Get access to the Tasks API by typing `this.app.plugins.plugins['obsidian-tasks-plugin'].apiV1` in the console.
+3. Use the `editTaskLineModal()` method to open the edit task modal with a sample task text.
+
+## Edit Tasks
+
+Edit Task Command:
+
+```js
+const tasksApi = this.app.plugins.plugins['obsidian-tasks-plugin'].apiV1;
+let editedTaskLine = await tasksApi.editTaskLineModal('- [ ] #task Do every day 🔼 🔁 every day ➕ 2025-07-06 ⏳ 2025-07-06');
+console.log(editedTaskLine);
+```
+
+- [ ] #task Test Populated Values in Modal
+
+ 1. Open modal with the sample task text above.
+ 2. Verify that the task properties are populated in the modal.
+ 3. Mark Task Done
+ 4. Expected
+
+> - [ ] #task Do every day 🔼 🔁 every day ⏳ 2025-07-07
+> - [x] #task Do every day 🔼 🔁 every day ➕ 2025-07-06 ⏳ 2025-07-06 ✅ 2025-07-06
+
+- [ ] #task Reverse the order of Recurring tasks in the Tasks settings
+
+ 1. Reverse the order of Recurring tasks in the Tasks settings
+ 2. Open modal with the sample task text above.
+ 3. Change the Status to Done
+ 4. Expected
+
+> - [x] #task Do every day 🔼 🔁 every day ➕ 2025-07-06 ⏳ 2025-07-06 ✅ 2025-07-06
+> - [ ] #task Do every day 🔼 🔁 every day ⏳ 2025-07-07

src/Api/TasksApiV1.ts

@@ -10,6 +10,15 @@ export interface TasksApiV1 {
      */
     createTaskLineModal(): Promise<string>;
 
+    /**
+     * Opens the Tasks UI and returns the Markdown string for the edited
+     * task line. Does not edit the task line in the file.
+     *
+     * @returns {Promise<string>} A promise that contains the Markdown string for the task edited or
+     * an empty string, if data entry was cancelled.
+     */
+    editTaskLineModal(taskLine: string): Promise<string>;
+
     /**
      * Executes the 'Tasks: Toggle task done' command on the supplied line string
      *

src/Api/editTaskLineModal.ts

@@ -0,0 +1,34 @@
+import type { App } from 'obsidian';
+import type { Task } from '../Task/Task';
+import { taskFromLine } from '../Commands/CreateOrEditTaskParser';
+import { TaskModal } from '../Obsidian/TaskModal';
+
+/**
+ * Opens the Tasks UI and returns the Markdown string for the task entered.
+ * If the optional Markdown string for a task is passed, the form will be
+ * populated with that task's properties.
+ *
+ * @param app - The Obsidian App
+ * @param taskLine - Markdown string of the task to edit.
+ * @param allTasks - An array of all tasks, used to populate the modal dependencies fields
+ *
+ * @returns {Promise<string>} A promise that contains the Markdown string for the task entered or
+ * an empty string, if data entry was cancelled.
+ */
+export function editTaskLineModal(app: App, taskLine: string, allTasks: Task[]): Promise<string> {
+    let resolvePromise: (input: string) => void;
+    const waitForClose = new Promise<string>((resolve, _) => {
+        resolvePromise = resolve;
+    });
+
+    const onSubmit = (updatedTasks: Task[]): void => {
+        const line = updatedTasks.map((task: Task) => task.toFileLineString()).join('\n');
+        resolvePromise(line);
+    };
+
+    const task = taskFromLine({ line: taskLine ?? '', path: '' });
+    const taskModal = new TaskModal({ app, task, onSubmit, allTasks });
+
+    taskModal.open();
+    return waitForClose;
+}

src/Api/index.ts

@@ -2,6 +2,7 @@ import type TasksPlugin from '../main';
 import { toggleLine } from '../Commands/ToggleDone';
 import { createTaskLineModal } from './createTaskLineModal';
 import type { TasksApiV1 } from './TasksApiV1';
+import { editTaskLineModal } from './editTaskLineModal';
 
 /**
  * Factory method for API v1
@@ -15,6 +16,9 @@ export const tasksApiV1 = (plugin: TasksPlugin): TasksApiV1 => {
         createTaskLineModal: (): Promise<string> => {
             return createTaskLineModal(app, plugin.getTasks());
         },
+        editTaskLineModal: (taskLine: string): Promise<string> => {
+            return editTaskLineModal(app, taskLine, plugin.getTasks());
+        },
         executeToggleTaskDoneCommand: (line: string, path: string) => toggleLine(line, path).text,
     };
 };

src/Obsidian/TaskModal.ts

@@ -1,26 +1,24 @@
-import { App, Modal } from 'obsidian';
+import type { App } from 'obsidian';
+import { Modal } from 'obsidian';
 
 import EditTask from '../ui/EditTask.svelte';
 import type { Task } from '../Task/Task';
 import { StatusRegistry } from '../Statuses/StatusRegistry';
 import { Status } from '../Statuses/Status';
 
+export interface TaskModalParams {
+    app: App;
+    task: Task;
+    onSubmit: (updatedTasks: Task[]) => void;
+    allTasks: Task[];
+}
+
 export class TaskModal extends Modal {
     public readonly task: Task;
     public readonly onSubmit: (updatedTasks: Task[]) => void;
     public readonly allTasks: Task[];
 
-    constructor({
-        app,
-        task,
-        onSubmit,
-        allTasks,
-    }: {
-        app: App;
-        task: Task;
-        onSubmit: (updatedTasks: Task[]) => void;
-        allTasks: Task[];
-    }) {
+    constructor({ app, task, onSubmit, allTasks }: TaskModalParams) {
         super(app);
 
         this.task = task;

tests/Api/editTaskLineModal.test.ts

@@ -0,0 +1,62 @@
+import type { App } from 'obsidian';
+import type { Task } from '../../src/Task/Task';
+import { editTaskLineModal } from '../../src/Api/editTaskLineModal';
+import { taskFromLine } from '../../src/Commands/CreateOrEditTaskParser';
+import { TaskModal } from '../__mocks__/TaskModal';
+import type { TaskModalParams } from '../../src/Obsidian/TaskModal';
+
+const app = {} as App;
+
+const createNewTask = (line = ''): Task => {
+    return taskFromLine({ line, path: '' });
+};
+
+jest.mock('../../src/Obsidian/TaskModal', () => {
+    return {
+        TaskModal: jest.fn(({ app, task, onSubmit, allTasks }: TaskModalParams) => {
+            return new TaskModal({ app, task, onSubmit, allTasks });
+        }),
+    };
+});
+
+describe('APIv1 - editTaskLineModal', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it('TaskModal.open() should be called', () => {
+        const taskLine = '- [ ] ';
+        editTaskLineModal(app, taskLine, []);
+
+        expect(TaskModal.instance.open).toHaveBeenCalled();
+    });
+
+    it('should return the edited Markdown', async () => {
+        const taskLine = '- [ ] Updated Task';
+        const taskLinePromise = editTaskLineModal(app, '- [ ] Task Name', []);
+
+        TaskModal.instance.onSubmit([createNewTask(taskLine)]);
+
+        const result = await taskLinePromise;
+        expect(result).toEqual('- [ ] Updated Task');
+    });
+
+    it('should return empty string on cancel', async () => {
+        const taskLine = '- [ ] ';
+        const taskLinePromise = editTaskLineModal(app, taskLine, []);
+
+        TaskModal.instance.cancel();
+
+        const result = await taskLinePromise;
+        expect(result).toEqual('');
+    });
+
+    it('should pass allTasks to TaskModal', () => {
+        const taskLine = '- [ ] Task Name';
+        const allTasks = [createNewTask('- [ ] Task 1')];
+
+        editTaskLineModal(app, taskLine, allTasks);
+
+        expect(TaskModal.instance.allTasks).toEqual(allTasks);
+    });
+});

tests/Api/index.test.ts

@@ -2,12 +2,17 @@ import type { App } from 'obsidian';
 import type TasksPlugin from '../../src/main';
 import type { Task } from '../../src/Task/Task';
 import { createTaskLineModal } from '../../src/Api/createTaskLineModal';
+import { editTaskLineModal } from '../../src/Api/editTaskLineModal';
 import { tasksApiV1 } from '../../src/Api/index';
 
 jest.mock('../../src/Api/createTaskLineModal', () => ({
     createTaskLineModal: jest.fn(),
 }));
 
+jest.mock('../../src/Api/editTaskLineModal', () => ({
+    editTaskLineModal: jest.fn(),
+}));
+
 describe('definition of public Api', () => {
     it('should call createTaskLineModal with the app and allTasks', async () => {
         const task = jest.fn();
@@ -23,4 +28,20 @@ describe('definition of public Api', () => {
         await publicApi.createTaskLineModal();
         expect(createTaskLineModal).toHaveBeenCalledWith(app, tasks);
     });
+
+    it('should call editTaskLineModal with the app, taskLine and allTasks', async () => {
+        const task = jest.fn();
+        const app = {} as App; // Mock the app object
+        const tasks = [task as Partial<Task>];
+        const mockPlugin = {
+            getTasks: () => tasks,
+            app,
+        } as Partial<TasksPlugin> as TasksPlugin;
+        const taskLine = '- [ ] Task Name';
+
+        const publicApi = tasksApiV1(mockPlugin);
+
+        await publicApi.editTaskLineModal(taskLine);
+        expect(editTaskLineModal).toHaveBeenCalledWith(app, taskLine, tasks);
+    });
 });

tests/__mocks__/obsidian.ts

@@ -221,3 +221,18 @@ export function prepareSimpleSearch(query: string): (text: string) => SearchResu
 
 type IconName = string;
 export function setIcon(_parent: HTMLElement, _iconId: IconName): void {}
+
+/**
+ * A mock implementation of the Obsidian Modal class.
+ * Without this testing the TaskModal throws an error attempting to extend Modal
+ */
+export class Modal {
+    public open(): void {
+        // Mocked interface, no-op
+    }
+    public close(): void {
+        // Mocked interface, no-op
+    }
+    public onOpen(): void {}
+    public onClose(): void {}
+}