Merge pull request #3440 from obsidian-tasks-group/status-report-sample-tasks

Status report sample tasks

Author: claremacrae

docs/Getting Started/Statuses/Check your Statuses.md

@@ -33,10 +33,28 @@ The sections are:
 - **Loaded Settings**
   - This has a **Mermaid diagram** showing transitions between your statuses.
   - View the report in Live Preview or Reading Mode, to see the diagram.
+- **Sample Tasks**
+  - This has sample task lines for each valid status.
+  - View the report in Live Preview or Reading Mode, to check they work with your Theme or CSS snippets.
+- **Search the Sample Tasks**
+  - This has a Tasks search showing all the tasks in this file, grouped by their status type and status name.
 
 ## Example statuses report
 
+### Table and diagram sections
+
 Here is an example report, that is generated from the problem statuses shown in [[Recurring Tasks and Custom Statuses#When DONE is not followed by TODO or IN_PROGRESS|When DONE is not followed by TODO or IN_PROGRESS]]:
 
 ![Example statuses report](../../images/settings-statuses-report.png)<br>
 *Example statuses report*
+
+### Sample tasks sections
+
+Since Tasks X.Y.Z, there will also be **Sample Tasks** and **Search the Sample Tasks** sections.
+
+Their appearance depends on your choice of Theme or CSS snippet.
+
+Here is what it might look like with the **Minimal theme**, and **Colorful Headings** enabled in the **Minimal Theme Settings plugin**:
+
+![Example statuses report samples](../../images/settings-statuses-report-samples.png)<br>
+*Example statuses report samples*

docs/What is New/Changelog.md

@@ -12,6 +12,8 @@ _In recent [Tasks releases](https://github.com/obsidian-tasks-group/obsidian-tas
 
 ## 7.x releases
 
+- X.Y.Z:
+  - [[Check your Statuses]] report now contains samples of each status, and a convenient search to test them.
 - 7.19.0:
   - New setting to [[Recurring Tasks#Remove scheduled date on recurrence|remove scheduled date on recurrence]].
 - 7.16.0:

docs/images/settings-statuses-report-samples.png

@@ -1,7 +1,7 @@
 import type { StatusSettings } from '../Config/StatusSettings';
 import { i18n } from '../i18n/i18n';
 import type { StatusRegistry } from './StatusRegistry';
-import { tabulateStatusSettings } from './StatusSettingsReport';
+import { sampleTaskLinesForValidStatuses, tabulateStatusSettings } from './StatusSettingsReport';
 
 export function createStatusRegistryReport(
     statusSettings: StatusSettings,
@@ -17,6 +17,7 @@ export function createStatusRegistryReport(
     const detailed = true;
     const settingsTable = tabulateStatusSettings(statusSettings);
     const mermaidText = statusRegistry.mermaidDiagram(detailed);
+    const sampleTasksText = sampleTaskLinesForValidStatuses(statusSettings);
     return `# ${buttonName}
 
 ## ${i18n.t('reports.statusRegistry.about.title')}
@@ -46,5 +47,34 @@ ${settingsTable}
 <!-- ${i18n.t('reports.statusRegistry.loadedSettings.switchToLivePreview')} -->
 
 ${i18n.t('reports.statusRegistry.loadedSettings.settingsActuallyUsed')}
-${mermaidText}`;
+${mermaidText}
+
+## ${i18n.t('reports.statusRegistry.sampleTasks.title')}
+
+${i18n.t('reports.statusRegistry.sampleTasks.line1')}
+
+${i18n.t('reports.statusRegistry.sampleTasks.line2')}
+
+${i18n.t('reports.statusRegistry.sampleTasks.line3')}
+
+> [!Tip] ${i18n.t('reports.statusRegistry.sampleTasks.tip.line1')}
+> ${i18n.t('reports.statusRegistry.sampleTasks.tip.line2', {
+        url: 'https://publish.obsidian.md/tasks/How+To/Style+custom+statuses',
+    })}
+
+${sampleTasksText.join('\n')}
+
+## ${i18n.t('reports.statusRegistry.searchSampleTasks.title')}
+
+${i18n.t('reports.statusRegistry.searchSampleTasks.line1')}
+
+\`\`\`tasks
+path includes {{query.file.path}}
+group by status.type
+group by status.name
+sort by function task.lineNumber
+hide postpone button
+short mode
+\`\`\`
+`;
 }

src/Statuses/StatusRegistryReport.ts

@@ -1,9 +1,10 @@
 import { StatusSettings } from '../Config/StatusSettings';
 import { MarkdownTable } from '../lib/MarkdownTable';
 import { i18n } from '../i18n/i18n';
-import type { StatusConfiguration } from './StatusConfiguration';
-import { StatusType } from './StatusConfiguration';
+import { GlobalFilter } from '../Config/GlobalFilter';
+import { type StatusConfiguration, StatusType } from './StatusConfiguration';
 import { Status } from './Status';
+import { StatusRegistry } from './StatusRegistry';
 
 function getFirstIndex(statusConfigurations: StatusConfiguration[], wantedSymbol: string) {
     return statusConfigurations.findIndex((s) => s.symbol === wantedSymbol);
@@ -114,3 +115,28 @@ export function tabulateStatusSettings(statusSettings: StatusSettings) {
     });
     return table.markdown;
 }
+
+/**
+ * Generates a list of Markdown lines, containing sample tasks based on the given status settings.
+ *
+ * @param {StatusSettings} statusSettings - The settings object containing custom and core statuses.
+ *
+ * @returns {string[]} An array of markdown strings representing sample tasks.
+ * Each task includes a symbol, an introductory text, and the name of the status.
+ * Only the actually registered symbols are used; duplicate and empty symbols are ignored.
+ * The Global Filter will be added, if it is non-empty.
+ */
+export function sampleTaskLinesForValidStatuses(statusSettings: StatusSettings) {
+    const statusRegistry = new StatusRegistry();
+    StatusSettings.applyToStatusRegistry(statusSettings, statusRegistry);
+    const registeredStatuses: StatusConfiguration[] = statusRegistry.registeredStatuses;
+
+    return registeredStatuses.map((status, index) => {
+        const globalFilter = GlobalFilter.getInstance();
+        const globalFilterIfSet = globalFilter.isEmpty() ? '' : globalFilter.get() + ' ';
+        const intro = `Sample task ${index + 1}`;
+        const symbol = `status symbol=${getPrintableSymbol(status.symbol)}`;
+        const name = `status name='${status.name}'`;
+        return `- [${status.symbol}] ${globalFilterIfSet}${intro}: ${symbol} ${name}`;
+    });
+}

src/Statuses/StatusSettingsReport.ts

@@ -64,6 +64,20 @@
           "line3": "Глядзіце [Recurring Tasks and Custom Statuses]({{helpURL}})."
         }
       },
+      "sampleTasks": {
+        "line1": "",
+        "line2": "",
+        "line3": "",
+        "tip": {
+          "line1": "",
+          "line2": ""
+        },
+        "title": ""
+      },
+      "searchSampleTasks": {
+        "line1": "",
+        "title": ""
+      },
       "statusSettings": {
         "comment": {
           "line1": "Пераключыцеся ў рэжым папярэдняга прагляду ў рэальным часе або рэжым чытання, каб убачыць табліцу.",

src/i18n/locales/be.json

@@ -64,6 +64,20 @@
           "line3": "See [Recurring Tasks and Custom Statuses]({{helpURL}})."
         }
       },
+      "sampleTasks": {
+        "line1": "Here is one example task line for each of the statuses actually used by tasks, for you to experiment with.",
+        "line2": "The status symbols and names in the task descriptions were correct when this file was created.",
+        "line3": "If you have modified the sample tasks since they were created, you can see the current status types and names in the group headings in the Tasks search below.",
+        "tip": {
+          "line1": "Tip: If all your checkboxes look the same...",
+          "line2": "If all the checkboxes look the same in Reading Mode or Live Preview, see [Style custom statuses]({{url}}) for how to select a theme or CSS snippet to style your statuses."
+        },
+        "title": "Sample Tasks"
+      },
+      "searchSampleTasks": {
+        "line1": "This Tasks search shows all the tasks in this file, grouped by their status type and status name.",
+        "title": "Search the Sample Tasks"
+      },
       "statusSettings": {
         "comment": {
           "line1": "Switch to Live Preview or Reading Mode to see the table.",

src/i18n/locales/en.json

@@ -64,6 +64,20 @@
           "line3": "См. [Recurring Tasks and Custom Statuses]({{helpURL}})."
         }
       },
+      "sampleTasks": {
+        "line1": "",
+        "line2": "",
+        "line3": "",
+        "tip": {
+          "line1": "",
+          "line2": ""
+        },
+        "title": ""
+      },
+      "searchSampleTasks": {
+        "line1": "",
+        "title": ""
+      },
       "statusSettings": {
         "comment": {
           "line1": "Переключитесь в режим Live Preview или Reading Mode, чтобы увидеть таблицу.",

src/i18n/locales/ru.json

@@ -64,6 +64,20 @@
           "line3": "Див. [Повторювані задачі та користувацькі статуси]({{helpURL}})."
         }
       },
+      "sampleTasks": {
+        "line1": "",
+        "line2": "",
+        "line3": "",
+        "tip": {
+          "line1": "",
+          "line2": ""
+        },
+        "title": ""
+      },
+      "searchSampleTasks": {
+        "line1": "",
+        "title": ""
+      },
       "statusSettings": {
         "comment": {
           "line1": "Перейдіть у режим Live Preview або режим читання, щоб побачити таблицю.",

src/i18n/locales/uk.json

@@ -64,6 +64,20 @@
           "line3": "请参阅[重复任务和自定义状态]({{helpURL}})。"
         }
       },
+      "sampleTasks": {
+        "line1": "",
+        "line2": "",
+        "line3": "",
+        "tip": {
+          "line1": "",
+          "line2": ""
+        },
+        "title": ""
+      },
+      "searchSampleTasks": {
+        "line1": "",
+        "title": ""
+      },
       "statusSettings": {
         "comment": {
           "line1": "切换到实时预览或阅读模式以查看表格.",
@@ -242,4 +256,4 @@
       "heading": "任务状态"
     }
   }
-}
+}

src/i18n/locales/zh_cn.json

@@ -61,3 +61,35 @@ classDef NON_TASK    stroke:#99e,stroke-width:3px;
 
 linkStyle default stroke:gray
 ```
+
+
+## Sample Tasks
+
+Here is one example task line for each of the statuses actually used by tasks, for you to experiment with.
+
+The status symbols and names in the task descriptions were correct when this file was created.
+
+If you have modified the sample tasks since they were created, you can see the current status types and names in the group headings in the Tasks search below.
+
+> [!Tip] Tip: If all your checkboxes look the same...
+> If all the checkboxes look the same in Reading Mode or Live Preview, see [Style custom statuses](https://publish.obsidian.md/tasks/How+To/Style+custom+statuses) for how to select a theme or CSS snippet to style your statuses.
+
+- [ ] Sample task 1: status symbol=`space` status name='Todo'
+- [x] Sample task 2: status symbol=`x` status name='Done'
+- [/] Sample task 3: status symbol=`/` status name='In Progress'
+- [-] Sample task 4: status symbol=`-` status name='Cancelled'
+- [Q] Sample task 5: status symbol=`Q` status name='Question'
+- [A] Sample task 6: status symbol=`A` status name='Answer'
+
+## Search the Sample Tasks
+
+This Tasks search shows all the tasks in this file, grouped by their status type and status name.
+
+```tasks
+path includes {{query.file.path}}
+group by status.type
+group by status.name
+sort by function task.lineNumber
+hide postpone button
+short mode
+```

tests/Statuses/StatusRegistryReport.test.StatusRegistryReport_should_create_a_report.approved.md

@@ -0,0 +1,4 @@
+- [ ] Sample task 1: status symbol=`space` status name='Todo'
+- [x] Sample task 2: status symbol=`x` status name='Done'
+- [/] Sample task 3: status symbol=`/` status name='A slash'
+- [p] Sample task 4: status symbol=`p` status name='A p'

tests/Statuses/StatusSettingsReport.test.StatusSettingsReport_should_create_set_of_sample_task_lines,_excluding_duplicate_and_empty_symbols.approved.md

@@ -0,0 +1,4 @@
+- [ ] #task Sample task 1: status symbol=`space` status name='Todo'
+- [x] #task Sample task 2: status symbol=`x` status name='Done'
+- [/] #task Sample task 3: status symbol=`/` status name='A slash'
+- [p] #task Sample task 4: status symbol=`p` status name='A p'

tests/Statuses/StatusSettingsReport.test.StatusSettingsReport_should_create_set_of_sample_task_lines_include_global_filter.approved.md

@@ -1,14 +1,19 @@
 import { StatusSettings } from '../../src/Config/StatusSettings';
-import { tabulateStatusSettings } from '../../src/Statuses/StatusSettingsReport';
+import { sampleTaskLinesForValidStatuses, tabulateStatusSettings } from '../../src/Statuses/StatusSettingsReport';
 import type { StatusCollection } from '../../src/Statuses/StatusCollection';
 import { verifyWithFileExtension } from '../TestingTools/ApprovalTestHelpers';
 import { coreStatusesData, createStatuses } from '../TestingTools/StatusesTestHelpers';
 import { initializeI18n } from '../../src/i18n/i18n';
+import { GlobalFilter } from '../../src/Config/GlobalFilter';
 
 beforeAll(async () => {
     await initializeI18n();
 });
 
+afterEach(() => {
+    GlobalFilter.getInstance().reset();
+});
+
 describe('StatusSettingsReport', () => {
     it('should tabulate StatusSettings', () => {
         const statusSettings = new StatusSettings();
@@ -36,4 +41,26 @@ describe('StatusSettingsReport', () => {
         const markdown = tabulateStatusSettings(statusSettings);
         verifyWithFileExtension(markdown, '.md');
     });
+
+    const customStatusesDataForSampleLines: StatusCollection = [
+        ['/', 'A slash', 'x', 'IN_PROGRESS'],
+        ['/', 'In Progress DUPLICATE - SHOULD NOT BE IN SAMPLE TASK LINES', 'x', 'IN_PROGRESS'],
+        ['', 'EMPTY STATUS SYMBOL - SHOULD NOT BE IN SAMPLE TASK LINES', '', 'TODO'],
+        ['p', 'A p', 'q', 'TODO'],
+    ];
+
+    it('should create set of sample task lines, excluding duplicate and empty symbols', () => {
+        const { statusSettings } = createStatuses(coreStatusesData, customStatusesDataForSampleLines);
+
+        const taskLines = sampleTaskLinesForValidStatuses(statusSettings);
+        verifyWithFileExtension(taskLines.join('\n'), '.md');
+    });
+
+    it('should create set of sample task lines include global filter', () => {
+        GlobalFilter.getInstance().set('#task');
+        const { statusSettings } = createStatuses(coreStatusesData, customStatusesDataForSampleLines);
+
+        const taskLines = sampleTaskLinesForValidStatuses(statusSettings);
+        verifyWithFileExtension(taskLines.join('\n'), '.md');
+    });
 });