2026-06-12 15:55:07 +02:00

11 KiB

Raw Blame History

GTD Calendar — Project Specification (v1 Draft)

A fork of WeMakeMachines/joplin-plugin-event-calendar (MIT) that inverts the plugin's data model: instead of events living as YAML inside the calendar note, the calendar is populated by real Joplin notes and todos in the surrounding folder tree, with clickable drilldown to the source note.

Working name: joplin-plugin-gtd-calendar Proposed manifest id: com.victorwiebe.joplin.plugin.gtd-calendar (must differ from upstream's id so both plugins can coexist during development)

1. Concept

A note anywhere in a folder contains a ```gtd-calendar fenced block. That block renders as a Day/Week/Month calendar populated by notes and todos in scope. Items opt in (by default) via a ```gtd fenced block in their body. Clicking a calendar event opens the underlying note.

Dateless items are not lost — they collect in an Unscheduled section below the calendar grid, functioning as a GTD next-actions / someday-maybe bucket.

2. Schema Reference

2.1 The `gtd-calendar` block (lives in the calendar note)

```gtd-calendar
view: month            # day | week | month        (default: day, matching upstream)
title: Editorial Schedule
scope: this-folder     # this-folder | children | <integer depth>   (default: this-folder)
notes: gtd-only        # gtd-only | all | none     (default: gtd-only)
todos: gtd-only        # gtd-only | all | none     (default: gtd-only)
sort: asc              # asc | desc                (default: asc)
sort-type: title       # title | modified_date    (default: title)

Key	Values	Default	Notes
`view`	`day`, `week`, `month` (also `d`/`w`/`m`, as upstream)	`day`	Grouping granularity of the grid.
`title`	string	none	Rendered as a heading above the calendar.
`scope`	`this-folder`, `children`, or an integer	`this-folder`	`children` = unlimited recursion into subfolders. An integer n = this folder plus n levels of descendants (`0` ≡ `this-folder`). Documentation will caution that broad scopes scan every note body in the tree.
`notes`	`gtd-only`, `all`, `none`	`gtd-only`	Which plain notes participate. `all` includes notes without a `gtd` block (they receive default styling and are Unscheduled unless... see §3.2).
`todos`	`gtd-only`, `all`, `none`	`gtd-only`	Same semantics for todos.
`sort`	`asc`, `desc`	`asc`	Order of events within each day/week/month grouping and within Unscheduled. Groupings themselves always run chronologically.
`sort-type`	`title`, `modified_date`	`title`	Field used by `sort`. `modified_date` maps to Joplin's `updated_time`.

Unknown keys are ignored with a console warning. A malformed block renders an inline error box rather than failing silently (improvement over upstream, which swallows parse errors into the console).

2.2 The `gtd` block (lives in participating notes/todos)

```gtd
date: 2026-07-04       # required for notes to be scheduled; optional override for todos
bg-colour: teal        # any CSS color value
fg-colour: white
icon: 🦴
title: Override title  # optional; defaults to the note's own title
text: Hover text       # optional; tooltip detail, as upstream

Key	Applies to	Behavior
`date`	notes	Required for the item to appear in the grid; without it the note goes to Unscheduled. Accepts `yyyy-mm-dd` (and `mm-dd-yyyy` for upstream parity).
`date`	todos	Optional. If present, overrides `todo_due` (explicit beats implicit).
`bg-colour` / `bgColor`	both	Event tile background. Both spellings accepted; `bg-colour` is canonical for this fork.
`fg-colour`	both	Event tile text color (new vs. upstream).
`icon`	both	Emoji/short string, as upstream. Defaults: type indicator (see §4).
`title`	both	Overrides the note title on the tile.
`text`	both	Tooltip body.

An empty ```gtd block is valid and meaningful: it is the opt-in signal with all defaults.

3. Data Model Rules

3.1 Date resolution

Todos: todo_due from the Joplin API. A date: in the gtd block overrides it.
Notes: date: from the gtd block only. No fallback to created/updated time — those are not event dates and would produce misleading calendars.
No resolvable date → item is rendered in the Unscheduled section below the grid.

3.2 Inclusion matrix

An item appears on the calendar iff its type's mode admits it:

Mode	Has `gtd` block	No `gtd` block
`gtd-only` (default)	✅ included	❌ excluded
`all`	✅ included	✅ included (default styling)
`none`	❌ excluded	❌ excluded

The calendar note itself is always excluded from results, as is any note whose only gtd-calendar block makes it a calendar (a note may, however, be both an event and contain a calendar if it has both block types — edge case, supported, documented).

3.3 Completed todos

v1 decision: completed todos (todo_completed > 0) render with strikethrough + checked indicator, and a future completed: show | hide calendar option is reserved. (Logged as decision D3 below; cheap to change.)

4. Rendering

Reuses upstream's grouping/renderer architecture (DayGrouping/WeekGrouping/MonthGrouping + DOM renderers + CSS asset), including the empty-grouping placeholders and current-date highlight.
Fixes upstream bug: Calendar/index.ts imports WeekGrouping from Month/MonthGrouping, so the week view silently groups by month. Corrected in the fork.
Type distinction: todos render with a checkbox glyph (☐ / ☑ when completed); notes render with a document glyph. Glyphs are suppressed if the item supplies its own icon. A subtle border-style difference (solid vs. dashed, TBD in CSS) keeps the distinction visible under custom colours.
Unscheduled section: pinned below the grid, with its own header, honoring sort / sort-type.
Drilldown: each tile is clickable and opens the source note.

5. Architecture

Upstream is a single synchronous markdown-it content script with no data API access. The fork becomes a three-part plugin:

┌─────────────────────────────┐
│ 1. Markdown-it content      │  Intercepts ```gtd-calendar fences.
│    script (renderer)        │  Parses YAML config, emits a placeholder
│                             │  <div> carrying the config as data-attrs.
└──────────────┬──────────────┘
               │ (rendered HTML)
┌──────────────▼──────────────┐
│ 2. Webview asset script     │  Finds placeholders, calls
│    (runs in rendered note)  │  webviewApi.postMessage(config).
│                             │  Receives event data, builds the
│                             │  calendar DOM via the (reused)
│                             │  grouping/renderer classes.
│                             │  Click → postMessage({open: noteId}).
└──────────────┬──────────────┘
               │ postMessage / onMessage
┌──────────────▼──────────────┐
│ 3. Main plugin process      │  joplin.contentScripts.onMessage:
│    (index.ts)               │  • resolve current note's folder
│                             │    (joplin.workspace.selectedNote)
│                             │  • build folder tree, apply scope
│                             │  • fetch notes/todos (id, title,
│                             │    is_todo, todo_due, todo_completed,
│                             │    updated_time, body)
│                             │  • parse ```gtd blocks from bodies
│                             │  • apply inclusion matrix, return
│                             │    structured event list
│                             │  • handle open: joplin.commands
│                             │    .execute('openNote', noteId)
└─────────────────────────────┘

Performance notes

Folder tree and note list fetched per render request; paginated API calls (page/has_more).
Body scanning is limited to items in scope. For large scopes, pre-filter with Joplin's search API (body:"```gtd"-style query) before fetching full bodies. Cache by updated_time if needed; not a v1 requirement.
Refresh model: re-render occurs on note switch (Joplin behavior). joplin.workspace.onNoteChange live refresh is a stretch goal, not v1.

Platform caveats

Desktop is the target. Mobile plugin support is partial; openNote behavior there is unverified. The "embed search" pairing remains a documented fallback for mobile users.

6. Implementation Phases

Phase 0 — Scaffolding. Fork, rename (manifest id, plugin name, file names), build pipeline verified (npm install && npm run dist), upstream week-view bug fixed, upstream tests green.
Phase 1 — Plumbing. Placeholder rendering for gtd-calendar fences; webview ⇄ plugin message round-trip proven with a hardcoded payload.
Phase 2 — Data layer. Folder tree + scope resolution; note/todo fetching; gtd block parsing; inclusion matrix; date resolution; unit tests for all of it (the upstream Jest setup carries over).
Phase 3 — Rendering. Wire real data into the reused renderers; Unscheduled section; type glyphs; fg-colour support; sort options.
Phase 4 — Drilldown & polish. Click-to-open; error boxes for malformed YAML; docs/README; scope-performance warnings.

7. Decision Log / Open Items

#	Decision	Status
D1	Defaults: `notes: gtd-only`, `todos: gtd-only`	⚠️ Confirm — earlier discussion said todos are always included (i.e. `todos: all` default); the final message specified `gtd-only` as default for both. Spec follows the final message.
D2	`gtd` `date:` overrides `todo_due` (vs. emitting a warning)	Adopted; revisit if confusing in practice.
D3	Completed todos: shown struck-through in v1; `completed:` option reserved	Proposed, unconfirmed.
D4	`sort`/`sort-type` act within groupings only; grid is always chronological	Confirmed.
D5	Colour key spelling: `bg-colour`/`fg-colour` canonical, `bgColor` accepted for upstream parity	Proposed.
D6	Future options parked: `completed:`, tag-based filtering, week-start day, live refresh	Backlog.

8. Licensing & Attribution

Upstream is MIT (© Franco Speziali / WeMakeMachines). The fork retains the MIT license, preserves the original copyright notice, and credits upstream in the README per standard practice.

11 KiB Raw Blame History