From 6aa5c2f2b9a3661e32ed31dad024706cf001bd7d Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Mon, 16 Nov 2026 12:43:01 +0100 Subject: docs: design receiving invitations, split sending to 216 A native invitation bar in the message pane shows a text/calendar part as plain text and offers Accept, Tentative and Decline, sent through the existing countdown or a composer with a note. The calendar is written only after the reply sends, into a collection mapped per account, and an organiser's update or cancellation waits for a button. Sending invitations and applying their replies becomes item 216. Item 207. Co-Authored-By: Claude Opus 5.5 --- .../plans/2026-08-03-post-0.1.0-usability.md | 23 +++- .../2026-11-16-receiving-invitations-design.md | 129 +++++++++++++++++++++ 2 files changed, 151 insertions(+), 1 deletion(-) create mode 100644 docs/superpowers/specs/2026-11-16-receiving-invitations-design.md (limited to 'docs/superpowers') diff --git a/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md b/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md index cc74be9..323af39 100644 --- a/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md +++ b/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md @@ -144,7 +144,7 @@ taking that too literally. | 204 | No recipient completion, in the composer or the query bar | workflow | S | **done** 2026-09-24, shipped, built via subagent-driven-development, `3303c78..7454096`. `ContactStore` over the vdirsyncer vCard 3.0 directory feeds one shared `QCompleter` for the composer's To/Cc/Bcc and the query bar's `from:`/`to:`. Hand-tested and confirmed. One review fix (control-character/RFC 5322 sanitisation of `FN`) landed and was re-reviewed clean. Section in the closed file | | 205 | Contacts can be read but not edited from the app | workflow | M | open, 2026-09-18, from 72's split, **asked for by the user** while settling 204. Writing a vdir, so it shares the write-during-sync question with 206 and the fold/escape rules with 204's parser. Its write-during-sync question is answered by 206's spec, ยง Writing: the same writer and stale check serve a vCard. Needs a brainstorm of its own | | 206 | No calendar: events cannot be viewed, added or edited | workflow | L | **done** 2026-09-29, shipped in 0.30.0, built via subagent-driven-development on branch calendar and merged. Month and Agenda views, a side pane that edits, undoable create/edit/delete over the vdirsyncer vdir. Hand-tested and confirmed; three hand-test fixes (cell colour flood, pane hidden while empty, Escape closes it). Writing a `VALARM` from the edit form was raised and deferred by the user. Section in the closed file | -| 207 | An invitation cannot be accepted, refused or sent | workflow | M | open, 2026-09-18, from 72's split, **asked for by the user**: "as it is today I don't have a way of accepting an invitation." `text/calendar` in the pane, an iMIP reply through the existing `send_command`. **Blocked on 206**, which owns the calendar it writes to | +| 207 | An invitation cannot be accepted or refused | workflow | M | open, designed 2026-11-16: `specs/2026-11-16-receiving-invitations-design.md`. RECEIVING only, split from the original 207 at the user's choice; sending is 216. A native invitation bar in `MessageView`, the target calendar mapped per account, Accept/Tentative/Decline sent through the countdown with a "...with note" composer route, the calendar written only after the reply sends, organiser updates and cancels applied by a button | | 208 | No way to add a new correspondent to the contacts | workflow | ? | open, 2026-09-18, **asked for by the user** while settling 204: an "add to contacts" button on mail from someone not in the store. Writes a vcard, so it lands on 205's writer rather than 204's reader. **Needs a brainstorm when picked up** | | 209 | The calendar has no Week view | presentation | M | open, from 206's brainstorm. The occurrence list is the seam: a new painter over CalendarItem, no store change | | 210 | A repeating event cannot be edited "this and following" | workflow | S-M | open, from 206's brainstorm. Splits a series into two files, divides EXDATEs and overrides, shifts moved RECURRENCE-IDs, converts COUNT; see the spec's Out of scope | @@ -153,6 +153,7 @@ taking that too literally. | 213 | A rule removing `inbox` is skipped whole by the hook, so promo mail arrives untagged | defect | S-M | open, designed: same spec, Part B. Optional per-rule `allow_archive`, both readers, no version bump; `unread` stays refused; the dialog warns about rules the hook will skip | | 214 | A rule can tag mail spam but cannot move it to the spam or trash folder | workflow | M | **done** 2026-11-16, unreleased, on `rule-move`. Spec: `specs/2026-11-16-rule-move-design.md`. The nesting assumption held: `notmuch new --no-hooks` runs inside `post-new`. Review fixes: a bad `move` is kept raw rather than dropped (the rule-id lesson), a nested account without the role resolves to itself, and `_quote` doubles quotes (it never matched an id holding one, on the carve-out path too). Section in the closed file. Original note: Optional `move` field, `spam` or `trash` (an account role, never a folder name), both readers, no version bump; the hook moves on arrival, strips `inbox`, keeps `unread`; Apply (212) inherits it later. First task: verify `notmuch new` can run inside `post-new` | | 215 | Archive, Restore and the Inbox filter lost their icons, and three icon tests fail | defect | S | open, 2026-11-16, found by the full suite while building 214. The icon names (`mail-archive`, `edit-undelete`, `mail-inbox`) exist in no installed theme: not candy-icons, and not breeze-dark, breeze, Adwaita or hicolor, which it inherits. Breeze was last updated 2026-11-05/11. Needs fallback names, the second slot `kThemeIcons` already has; the tests also read the DESKTOP theme, so the suite's result depends on the machine | +| 216 | An invitation cannot be sent, and replies to one are not applied | workflow | M | open, 2026-11-16, split from 207. Editing an event's attendee list, sending `METHOD:REQUEST` through `MessageBuilder`, and applying the `METHOD:REPLY`s that come back to the stored event's `PARTSTAT`s. Builds on 207's `Invitation` parsing and calendar-part support | | 73 | This backlog is past four thousand lines | maintenance | S | **done** 2026-08-13; 5056 lines to 578, closed sections moved to `2026-08-03-post-0.1.0-usability-closed.md` | | 74 | "Searching..." keeps claiming a query is running while rows are already arriving | feedback | XS | **done** 2026-08-15, unreleased. The status-bar half only: the bar now counts threads per batch. The cold-cache delay itself was measured in 2026-08-11 and is not fixable here | | 75 | The tagging rules window forgets its size and its column widths | persistence | S | **done** 2026-08-13, shipped in 0.17.0. The window-kind question is left open, see the closed-items file | @@ -1764,3 +1765,23 @@ packages, which is how a system update broke them with no code change. Item 199 (ship our own icon set) would remove that dependency for the panes, but the chrome deliberately stays on the system theme, so this item stands on its own. +## 216. An invitation cannot be sent, and replies to one are not applied + +**Observed.** Split from 207 on 2026-11-16, when the user chose to design the +receiving half first. The original 207 note covered both: "Sending an invite +is the same builder with a `METHOD:REQUEST` and an attendee list." + +**Cause.** The calendar's attendee list is read-only (206's decision 6) and +nothing builds or reads `METHOD:REQUEST` / `METHOD:REPLY`. + +**Approach.** Three parts: an attendee editor in `EventPane` for events the +user organises; a send of `METHOD:REQUEST` to every attendee on save, through +the per-account `send_command`; and an invitation-bar state for an incoming +`REPLY` that updates that attendee's `PARTSTAT` in the stored event. Builds on +207's parsing and on `OutgoingMessage::calendarPart`. + +**Constraints.** Adding an attendee is inviting them, so a save that sends +mail needs the countdown, like a reply. A `REPLY` comes from a stranger and +may name an attendee the event does not have: apply only to an existing +attendee, never add one. + diff --git a/docs/superpowers/specs/2026-11-16-receiving-invitations-design.md b/docs/superpowers/specs/2026-11-16-receiving-invitations-design.md new file mode 100644 index 0000000..7d403e8 --- /dev/null +++ b/docs/superpowers/specs/2026-11-16-receiving-invitations-design.md @@ -0,0 +1,129 @@ +# Receiving invitations + +Item 207, receiving half. Designed 2026-11-16. Sending invitations is item 216. + +## Problem + +"As it is today I don't have a way of accepting an invitation." `MimeParser` +has no branch for `text/calendar`, so an invitation reaches the pane as an +attachment chip or as nothing. The calendar (item 206) can store events but +nothing connects a message to it. + +## Decisions made with the user + +1. **Receiving first.** Sending invites (attendee editing, `METHOD:REQUEST`, + applying the `REPLY`s that come back) is item 216. +2. **The target calendar is mapped per account.** An optional + `calendar = ` key in `[account.]`. Unset: the first write + asks for a collection from a list. +3. **A reply goes both ways.** Accept / Tentative / Decline send at once + through the existing send countdown; each also has a "...with note" entry + that opens a composer carrying the calendar part. +4. **Decline writes nothing**, and removes the event if an earlier Accept + stored it. +5. **Organiser updates and cancellations wait for a button.** Opening the + message changes nothing. + +## Approach + +A native **invitation bar** in `MessageView`, between the message bar and the +web view, in the same family as the blocked-content and stale bars. Labels +are `Qt::PlainText`, buttons are `QPushButton`s. Rejected: rendering it in +the HTML body, which needs the interceptor to admit `qtmaildir:` actions and +loosens the most security-sensitive area for a convenience; and a dialog from +the attachment chip, which hides the invitation. + +## Parsing + +- `MimeParser` keeps the FIRST `text/calendar` part's decoded bytes on + `ParsedMessage` (`calendarPart`), whether it arrived inline in a + `multipart/alternative` or as an attachment. It stays an attachment chip too, + as today. +- `CalendarStore` gains pure functions over bytes, so the logic is tested with + no widget, the `CardLayout` rule: + - `parseInvitation(bytes)` returns an `Invitation` value (`caltypes.h`): + method, uid, sequence, recurrence-id, summary, location, start, end, + all-day, organizer, attendees. A part that does not parse, has no `METHOD`, + or has no `VEVENT` returns an invalid one. + - `storedText(inviteBytes, myAddress, partstat)`: the event file to write. + `METHOD` removed (a stored object carries none), my `ATTENDEE`'s + `PARTSTAT` set, `RSVP` cleared, everything else as the organiser sent it, + including `TZID` parameters (the 120-files rule from 206: never convert). + - `replyText(inviteBytes, myAddress, partstat)`: a `METHOD:REPLY` calendar + holding the `VEVENT` with `UID`, `SEQUENCE`, `DTSTAMP`, `ORGANIZER`, + `RECURRENCE-ID` when present, and ONLY my `ATTENDEE` line, per RFC 5546. + - `findByUid(events, uid)`: the stored event, if any. +- **"Me"** is the attendee whose address matches the `address` of the account + the message arrived on (case-insensitive, `mailto:` stripped). No match: the + bar says so and offers no reply. + +## Bar states + +A pure function `invitationState(invitation, storedEvent, meFound)` picks one, +returning an enum; the widget only renders it. + +| State | Shown | Buttons | +|---|---|---| +| New request | title, time, place, organiser, attendee count | Accept, Tentative, Decline, each with "...with note" | +| Update (stored, higher `SEQUENCE`) | the same, plus what changed: time, place | Update calendar, and the reply buttons | +| Already answered (stored, same `SEQUENCE`) | the same, plus "In your calendar: " | the reply buttons, to change the answer | +| Cancel, stored | "Cancelled by the organiser" | Remove from calendar | +| Cancel, not stored | "Cancelled; not in your calendar" | none. Normal, not an error | +| Out of date (lower `SEQUENCE` than stored) | "Out of date: your calendar holds a newer version" | none | +| One occurrence (`RECURRENCE-ID`) | details | none: "Changes to a single occurrence aren't supported yet" | +| Not invited | details | none: "You are not on the attendee list" | +| Other method (`REPLY`, `PUBLISH`, ...) | no bar | | + +No calendar configured (`calendarsDir()` empty): details only, no buttons. + +## Reply and write + +- `OutgoingMessage` gains `calendarPart` (bytes) and `calendarMethod`. + `MessageBuilder` adds it as a `text/calendar; method=; charset=utf-8` + part beside the text body. Subject: `Accepted: ` / + `Tentative: ...` / `Declined: ...`, translated. To: the organiser. + From: the account the invitation arrived on. +- One click hands the built message to the existing `SendDialog` countdown. + "...with note" opens a `ComposeWindow` with the part attached and the subject + and recipient filled; the user's text is the body. +- **The calendar write happens only when the send SUCCEEDS.** An aborted + countdown or a failed send leaves the calendar untouched, so the calendar + never claims an answer the organiser never received. Accept and Tentative + write `storedText`; Decline removes a stored event; a change of answer + rewrites it. +- Update calendar and Remove from calendar send nothing and write at once. +- Every write goes through `CalendarWriter::replace` with the stored event's + bytes as `expected` (a new file expects absent), and a `Stale` result is + reported in the status bar rather than retried. A new event is written as + `/.ics`, the name sanitised as an attachment + filename is. A `CalendarSync` runs after. +- An open `CalendarWindow` reloads after any such write. + +## Safety + +- Every value in the bar comes from a stranger: `Qt::PlainText`, no `URL`, + no `ATTACH`, no `DESCRIPTION` (it can be long and is in the body anyway). +- A button acts on the `Invitation` the bar is displaying, captured with it, + never on a re-read of the message. +- The `UID` reaches a filename: sanitised, and the resolved path must stay + inside the collection directory, compared as paths (the attachment rule). + +## Tests + +- `CalendarStore`: fixture `.ics` for a request, a cancel, an update, an older + sequence, a recurrence-id, and an invite without me. `storedText` keeps + `TZID`, drops `METHOD`, sets only my `PARTSTAT`; `replyText` carries only my + attendee and the right method. +- `invitationState`: one case per row of the table. +- `MimeParser`: the part is found inline and as an attachment. +- `MessageBuilder`: the part is present with its `method` parameter. +- The write-after-send rule: an aborted send writes nothing. +- How the bar looks is the user's hand test. + +## Out of scope + +- Single-occurrence updates (`RECURRENCE-ID`). +- Showing or applying replies to the user's own invitations, item 216. +- Editing attendees and sending invitations, item 216. +- Alarms on accepted events: kept if the organiser sent them, never fired, + as in 206. -- cgit v1.2.3