feat: Add custom grouping, with 'group by function' option

[claremacrae]

Description

A powerful, flexible mechanism to give users a lot of control over custom grouping rules.

Credit: This work was only made possible by @hauntedhost, who kindly taught me how to evaluate user-supplied functions in TypeScript.

Examples (taken from the docs)

group by function task.due?.format("YYYY-MM-DD dddd") || ""  

• Like "group by task.due", except it does not write "No due date" if there is no due date. The question mark (?) and || "" are needed because the due date value may be null.

group by function task.due?.format("dddd") || ""  

• Group by day of the week (Monday, Tuesday, etc).

group by function task.due?.format("YYYY MM MMM") || "no due date"  

• Group by month, for example "2023 05 May". The month number is also displayed, to control the sort order of headings.

group by function task.description.replace('short', '==short==')  

• Highlight the word "short" in any group descriptions.

group by function task.tags.filter( (t) => t.includes("#context/"))  

• Only create headings for tags that contain "#context/".

group by function task.tags.filter( (t) => ! t.includes("#tag"))  

• Create headings for all tags that do not contain "#tag".

New Features

• Add major new group by function feature, for custom grouping by many of the properties of tasks
• This adds the ability to group by some fields that it was not previously possible to group by:
  • task.description
  • task.status.symbol
  • task.status.nextStatusSymbol
• It enables custom-formatting of date headings, when grouping by date fields
  • So for example, grouping by week or month.
  • See the group by due docs for examples

New Documentation

• New top-level section Scripting
• Note the documentation will be finalised in later commits - I need a break from this now and just want to merge it, so I can pick up later improvements in smaller chunks of work.

Enabling changes

• Add some getters to Task whose names match the corresponding query instructions:
  • created
  • done
  • due
  • scheduled
  • start
  • happens (and also happensDates)
  • recurring (for future use)

TODO

Not all fields are exposed yet, as some will require refactoring to avoid them in a way that is consistent with the current filter instructions.

Notable omissions:

• task.priority
• task.file.path
• task.file.fileName
• task.file.root
• task.file.folder
• task.heading

---

Motivation and Context

There have been quite a few requests for variations on existing grouping options. This enables many of those to be done in one single step.

How has this been tested?

• Lots of manual testing in Obsidian.
• Lots of tests added.
• All the documentation examples are machined-generated, so if the sample group by function instructions ever break, we will know.

Screenshots (if appropriate)

Types of changes

Changes visible to users:

• New feature (prefix: feat - non-breaking change which adds functionality)
• Documentation (prefix: docs - improvements to any documentation content for users)
• Sample vault (prefix: vault - improvements to the Tasks-Demo sample vault)

Internal changes:

• Refactor (prefix: refactor - non-breaking change which only improves the design or structure of existing code, and making no changes to its external behaviour)
• Tests (prefix: test - additions and improvements to unit tests and the smoke tests)

Checklist

• My code follows the code style of this project and passes yarn run lint.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• My change has adequate Unit Test coverage.

Terms

• My contribution follow this project's contributing guide
• I agree to follow this project's Code of Conduct