feat: Implement Task Dependencies

docs/Advanced/Styling.md

@@ -82,6 +82,8 @@ The generic classes are:
 - `task-cancelled`
 - `task-done`
 - `task-recurring`
+- `task-id`
+- `task-blockedBy`
 
 In addition to the generic classes, there are [**data attributes**](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes) that represent the content of the various task components.
 

docs/Getting Started/Task Dependencies.md

@@ -0,0 +1,91 @@
+---
+publish: true
+---
+
+# Task Dependencies
+
+> [!released]
+> Introduced in Tasks X.Y.Z.
+
+## Introduction
+
+At a high level, task dependencies define the order in which you want to work on a set of tasks.
+This can be useful for mapping out projects, where one part needs to be completed before the other.
+By specifying these dependencies, Obsidian Tasks can streamline your workflow by displaying only the tasks that are actionable at any given moment.
+
+> [!NOTE]
+> Obsidian tasks exclusively allows for Finish to start (FS) dependencies, meaning Task A needs to be finished before you start on Task B. You can learn more about this concept [on Wikipedia](https://en.wikipedia.org/wiki/Dependency_(project_management)).
+
+## Example
+
+To illustrate the concept of task dependencies, let's consider a scenario where we are outlining the tasks required to develop an application. Two tasks are identified:
+
+```text
+- [ ] Build a first draft
+- [ ] Test with users
+```
+
+In this scenario, testing with users can only occur after the initial draft is completed. To establish this relationship, you can create a dependency between the two tasks using either of the following methods.
+
+1. Open the 'Build a first draft' task in the Edit Task Modal and specify 'Test with users' as a 'Blocking' task
+2. Alternatively, open the 'Test with users' task in the Edit Task Modal and add 'Build a first draft' as a 'Blocked By' task
+    ![[task-dependencies-blocked-by-example.png]]
+
+By implementing either of these methods, the task list is updated to reflect the dependency relationship:
+
+```text
+- [ ] Build a first draft 🆔 4ijuhy
+- [ ] Test with users ⛔️ 4ijuhy
+```
+
+Then, if the query `is not blocked` is used
+
+    ```tasks
+    is not blocked
+    ```
+
+We only see 'Build a first draft'
+
+```text
+- [ ] Build a first draft 🆔 4ijuhy
+```
+
+Until this task is marked as complete, at which time Obsidian Tasks sees that 'Test with users' is no longer blocked, and displays it as well
+
+```text
+- [x] Build a first draft 🆔 4ijuhy
+- [ ] Test with users ⛔️ 4ijuhyz
+```
+
+## Nomenclature
+
+Fields:
+
+- `blockedBy`
+- `id`
+
+UI:
+
+- Blocked by [implies an id of another task]
+- Blocks
+
+Query
+
+- blocking
+- blocked
+
+## Adding Dependencies
+
+## Searching For Dependencies
+
+`is not blocked`
+
+`is blocking`
+
+![[Pasted image 20231011181837.png]]
+
+## Known Limitations
+
+- It's not yet possible to directly navigate from a task to the tasks it depends on.
+- Outside of the edit task modal, it is not possible to see the descriptions of the blocking tasks.
+- It is not yet possible to visualise the relationships in a graph viewer.

docs/How To/Find tasks with invalid data.md

@@ -32,7 +32,7 @@ The following tasks block lists any tasks that have emoji in the description, wh
 ````text
 ```tasks
 # These description instructions need to be all on one line:
-(description includes 🔺) OR (description includes ⏫) OR (description includes 🔼) OR (description includes 🔽) OR (description includes ⏬) OR (description includes 🛫) OR (description includes ➕) OR (description includes ⏳) OR (description includes 📅) OR (description includes ✅) OR (description includes ❌) OR (description includes 🔁)
+(description includes 🔺) OR (description includes ⏫) OR (description includes 🔼) OR (description includes 🔽) OR (description includes ⏬) OR (description includes 🛫) OR (description includes ➕) OR (description includes ⏳) OR (description includes 📅) OR (description includes ✅) OR (description includes ❌) OR (description includes 🔁) OR (description includes ⛔️) OR (description includes 🆔)
 
 # Optionally, uncomment this line and exclude your templates location
 # path does not include _templates

docs/Reference/Task Formats/Dataview Format.md

@@ -131,6 +131,17 @@ For more information, see [[Priority]].
 
 For more information, see [[Recurring Tasks]].
 
+### Dataview Format for Dependencies
+
+<!-- snippet: DocsSamplesForTaskFormats.test.Serializer_Dependencies_dataview-snippet.approved.md -->
+```md
+- [ ] do this first  [id:: dcf64c]
+- [ ] do this after first and some other task  [blockedBy:: dcf64c,0h17ye]
+```
+<!-- endSnippet -->
+
+For more information, see [[Task Dependencies]].
+
 ## Auto-Suggest and Dataview format
 
 The Dataview format fully supports Tasks' [[Auto-Suggest]] feature, but requires users to manually type out surrounding brackets (`[]` or `()`).  This works best with `Settings > Editor > Autopair Brackets` enabled.

docs/Reference/Task Formats/Tasks Emoji Format.md

@@ -48,6 +48,17 @@ For more information, see [[Priority]].
 
 For more information, see [[Recurring Tasks]].
 
+## Tasks Emoji  Format for Dependencies
+
+<!-- snippet: DocsSamplesForTaskFormats.test.Serializer_Dependencies_tasksPluginEmoji-snippet.approved.md -->
+```md
+- [ ] do this first 🆔 dcf64c
+- [ ] do this after first and some other task ⛔️ dcf64c,0h17ye
+```
+<!-- endSnippet -->
+
+For more information, see [[Task Dependencies]].
+
 ## Limitations of Tasks Emoji Format
 
 ### Non-breaking spaces: NBSP characters

docs/Scripting/Task Properties.md

@@ -113,6 +113,20 @@ For more information, including adding your own customised statuses, see [[Statu
     - The `Invalid date` category was added in Tasks 6.0.0.
 1. The `fromNow` properties were added in Tasks 4.9.0.
 
+## Values for Task Dependencies
+
+<!-- placeholder to force blank line before included text --><!-- include: TaskProperties.test.task_dependency_fields.approved.md -->
+
+| Field | Type 1 | Example 1 | Type 2 | Example 2 |
+| ----- | ----- | ----- | ----- | ----- |
+| `task.id` | `string` | `'abcdef'` | `string` | `''` |
+| `task.blockedBy` | `string[]` | `['123456', 'abc123']` | `any[]` | `[]` |
+
+<!-- placeholder to force blank line after included text --><!-- endInclude -->
+
+1. See the page [[Task Dependencies]], which explains the dependencies facility.
+1. Task Dependencies were released in Tasks X.Y.Z.
+
 ## Values for Other Task Properties
 
 <!-- placeholder to force blank line before included text --><!-- include: TaskProperties.test.task_other_fields.approved.md -->
@@ -128,7 +142,7 @@ For more information, including adding your own customised statuses, see [[Statu
 | `task.isRecurring` | `boolean` | `true` | `boolean` | `false` |
 | `task.recurrenceRule` | `string` | `'every day when done'` | `string` | `''` |
 | `task.tags` | `string[]` | `['#todo', '#health']` | `any[]` | `[]` |
-| `task.originalMarkdown` | `string` | `'  - [ ] Do exercises #todo #health 🔼 🔁 every day when done ➕ 2023-07-01 🛫 2023-07-02 ⏳ 2023-07-03 📅 2023-07-04 ❌ 2023-07-06 ✅ 2023-07-05 ^dcf64c'` | `string` | `'- [/] minimal task'` |
+| `task.originalMarkdown` | `string` | `'  - [ ] Do exercises #todo #health 🔼 🔁 every day when done ➕ 2023-07-01 🛫 2023-07-02 ⏳ 2023-07-03 📅 2023-07-04 ❌ 2023-07-06 ✅ 2023-07-05 ⛔️ 123456,abc123 🆔 abcdef ^dcf64c'` | `string` | `'- [/] minimal task'` |
 
 <!-- placeholder to force blank line after included text --><!-- endInclude -->
 

docs/Support and Help/Known Limitations.md

@@ -31,6 +31,10 @@ This page gathers together all the documentation on known limitations of the plu
 
 ![[Getting Started#Limitations and warnings]]
 
+## Writing Tasks: Dependencies
+
+![[Task Dependencies#Known Limitations]]
+
 ## Writing Tasks: Task Formats
 
 ![[About Task Formats#Limitations of task format support]]

package.json

@@ -63,6 +63,7 @@
     "typescript": "^5.0.4"
   },
   "dependencies": {
+    "@floating-ui/dom": "^1.5.3",
     "boon-js": "^2.0.4",
     "chrono-node": "2.3.9",
     "eventemitter2": "^6.4.5",

resources/sample_vaults/Tasks-Demo/Manual Testing/Dependencies Samples.md

@@ -0,0 +1,87 @@
+# Dependencies Samples
+
+- [ ] #task Choose a topic 🆔 ya44g5
+- [ ] #task Research the subject ⛔️ ya44g5 🆔 g7317o
+- [ ] #task Create an outline ⛔️ g7317o 🆔 rot7gb
+- [ ] #task Develop main points ⛔️ rot7gb 🆔 mvplec
+- [ ] #task Craft a conclusion ⛔️ mvplec 🆔 0wigip
+- [ ] #task Proofread and edit ⛔️ 0wigip 🆔 5ti6bf
+- [ ] #task Publish the article ⛔️ 5ti6bf
+
+---
+
+## Do Next
+
+```tasks
+((is blocking) AND (is not blocked)) OR (is not blocked)
+not done
+
+path includes {{query.file.path}}
+explain
+```
+
+---
+
+## Blocking Tasks
+
+### Blocking Tasks - Any Status
+
+```tasks
+is blocking
+
+path includes {{query.file.path}}
+explain
+```
+
+### Blocking Tasks - Not Done
+
+```tasks
+is blocking
+not done
+
+path includes {{query.file.path}}
+explain
+```
+
+---
+
+## Blocked Tasks
+
+### Blocked Tasks  - Any Status
+
+```tasks
+is not blocked
+
+path includes {{query.file.path}}
+explain
+```
+
+### Blocked Tasks  - Not Done
+
+```tasks
+is not blocked
+not done
+
+path includes {{query.file.path}}
+explain
+```
+
+---
+
+## Show/Hide Instructions
+
+### Hide Id
+
+```tasks
+hide id
+path includes {{query.file.path}}
+explain
+```
+
+### Hide blockedBy
+
+```tasks
+hide depends on
+path includes {{query.file.path}}
+explain
+```

src/Api/createTaskLineModalHelper.ts

@@ -19,5 +19,12 @@ export const defaultTaskModalFactory: taskModalFactory = (
     onSubmit: (updatedTasks: Task[]) => void,
 ): ITaskModal => {
     const task = taskFromLine({ line: '', path: '' });
-    return new TaskModal({ app, task, onSubmit }) as ITaskModal;
+    // TODO This is going to need some thought. It is missing the Cache argument.
+    //      This file is part of the Tasks API that allows users to open the Edit Task modal from JavaScript:
+    //          https://publish.obsidian.md/tasks/Advanced/Tasks+Api
+    //      As a published API, to change the parameters would be a breaking change.
+    //      One option is to make the allTasks parameter to the Edit task modal be optional,
+    //      and if it's not provided, then hide the dependency fields in the modal.
+    //      For now, we pass in an empty list of tasks.
+    return new TaskModal({ app, task, onSubmit, allTasks: [] }) as ITaskModal;
 };

src/Commands/CreateOrEdit.ts

@@ -4,7 +4,7 @@ import type { Task } from '../Task';
 import { DateFallback } from '../DateFallback';
 import { taskFromLine } from './CreateOrEditTaskParser';
 
-export const createOrEdit = (checking: boolean, editor: Editor, view: View, app: App) => {
+export const createOrEdit = (checking: boolean, editor: Editor, view: View, app: App, allTasks: Task[]) => {
     if (checking) {
         return view instanceof MarkdownView;
     }
@@ -36,6 +36,7 @@ export const createOrEdit = (checking: boolean, editor: Editor, view: View, app:
         app,
         task,
         onSubmit,
+        allTasks,
     });
     taskModal.open();
 };

src/Commands/CreateOrEditTaskParser.ts

@@ -89,6 +89,8 @@ export const taskFromLine = ({ line, path }: { line: string; path: string }): Ta
             doneDate: null,
             cancelledDate: null,
             recurrence: null,
+            blockedBy: [],
+            id: '',
             blockLink: '',
             tags: [],
             originalMarkdown: '',
@@ -131,5 +133,7 @@ export const taskFromLine = ({ line, path }: { line: string; path: string }): Ta
         originalMarkdown: '',
         // Not needed since the inferred status is always re-computed after submitting.
         scheduledDateIsInferred: false,
+        id: '',
+        blockedBy: [],
     });
 };

src/Commands/index.ts

@@ -1,24 +1,26 @@
-import type { App, Editor, MarkdownFileInfo, MarkdownView, Plugin, View } from 'obsidian';
+import type { App, Editor, MarkdownFileInfo, MarkdownView, View } from 'obsidian';
+import type TasksPlugin from '../main';
 import { createOrEdit } from './CreateOrEdit';
 
 import { toggleDone } from './ToggleDone';
 
 export class Commands {
-    private readonly plugin: Plugin;
+    private readonly plugin: TasksPlugin;
 
     private get app(): App {
         return this.plugin.app;
     }
 
-    constructor({ plugin }: { plugin: Plugin }) {
+    constructor({ plugin }: { plugin: TasksPlugin }) {
         this.plugin = plugin;
 
         plugin.addCommand({
             id: 'edit-task',
             name: 'Create or edit task',
             icon: 'pencil',
             editorCheckCallback: (checking: boolean, editor: Editor, view: MarkdownView | MarkdownFileInfo) => {
-                return createOrEdit(checking, editor, view as View, this.app);
+                // TODO Need to explore what happens if a tasks code block is rendered before the Cache has been created.
+                return createOrEdit(checking, editor, view as View, this.app, this.plugin.getTasks()!);
             },
         });
 

src/Query/Filter/BlockingField.ts

@@ -0,0 +1,32 @@
+import type { SearchInfo } from '../SearchInfo';
+import { FilterInstructionsBasedField } from './FilterInstructionsBasedField';
+
+export class BlockingField extends FilterInstructionsBasedField {
+    constructor() {
+        super();
+        this._filters.add('is blocking', (task, searchInfo: SearchInfo) => {
+            if (task.id === '') return false;
+
+            return searchInfo.allTasks.some((cacheTask) => {
+                return cacheTask.blockedBy.includes(task.id);
+            });
+        });
+        this._filters.add('is not blocked', (task, searchInfo: SearchInfo) => {
+            if (task.blockedBy.length === 0) return true;
+
+            for (const depId of task.blockedBy) {
+                const depTask = searchInfo.allTasks.find((task) => task.id === depId);
+
+                if (!depTask) continue;
+
+                if (!depTask.status.isCompleted()) return false;
+            }
+
+            return true;
+        });
+    }
+
+    fieldName(): string {
+        return 'blocking';
+    }
+}