diff options
Diffstat (limited to 'docs/superpowers/plans/2026-09-24-calendar.md')
| -rw-r--r-- | docs/superpowers/plans/2026-09-24-calendar.md | 5468 |
1 files changed, 5468 insertions, 0 deletions
diff --git a/docs/superpowers/plans/2026-09-24-calendar.md b/docs/superpowers/plans/2026-09-24-calendar.md new file mode 100644 index 0000000..2182e30 --- /dev/null +++ b/docs/superpowers/plans/2026-09-24-calendar.md @@ -0,0 +1,5468 @@ +# Calendar Window Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** A top-level calendar window over the user's vdirsyncer vdir: Month and Agenda views, a side pane that shows and edits the selected event, atomic stale-checked writes with a debounced sync, and undo. + +**Architecture:** Everything runs on the UI thread (the whole vdir parses and expands in about 5 ms). libical is confined to `calendarstore.cpp` behind unique_ptr RAII aliases; every other unit sees plain value structs. `RepeatRule`, `CalendarWriter` and `MonthLayout` are pure and libical-free, so the parts with a right answer are tested without a widget. + +**Tech Stack:** C++17, Qt 6.11 Widgets, libical 3.0.20 (via pkg-config), Qt Test. + +**Spec:** `docs/superpowers/specs/2026-09-24-calendar-design.md`. Read it first; this plan does not repeat its reasoning. + +--- + +## Before starting + +- Work on a branch: `git switch -c calendar`. Merge to master only after the user's hand test (AGENTS.md: substantial UI work is branched so master stays shippable). +- Build and test per AGENTS.md: `cmake --build build && ctest --test-dir build --output-on-failure`. A single binary is ALWAYS run as `QT_QPA_PLATFORM=offscreen ./build/tests/test_<name>`. Never launch `./build/src/qtmaildir`. +- Commits are GPG-signed (`git commit -S`, which `commit.gpgsign=true` already does). Every new source file carries the GPLv2 header used by `src/contactstore.h` lines 1-17. +- **Every code block here is a draft.** AGENTS.md records many defects found in plan code written confidently. Verify each libical call against `/usr/include/libical/*.h` before relying on it, and prefer a failing test to a belief. +- Pre-existing failures, not yours: `test_mainwindow::undoMovesTheMessageBack` fails deterministically on this machine; `aSuccessfulCronSyncDrainsTheEditedAccounts` and `undoingAMarkReadRestoresOnlyWhatWasUnread` are order-dependent flakes that pass alone. + +## Rulings against the spec + +Taken while planning; the spec is amended in Task 16. + +1. **`calendars_dir` absent means OFF**, not a default path. `contacts_dir` (`config.cpp`) set that precedent: an unset key is an ordinary machine, not a misconfiguration. The README documents the usual value. +2. **"Byte for byte" becomes "value for value".** libical re-serialises the whole component on write, so line folding and property order may change. Tests assert that `VALARM`, `ATTENDEE` and `X-*` properties survive with the same VALUES, which is the property that matters, rather than identical bytes. +3. **Views read `CalendarItem`**, an `Occurrence` plus the title and colour to draw. Still no libical and no `CalEvent` in a view. +4. **Expansion does not use `icalrecur_iterator_set_start`.** It is unsupported with `COUNT` rules, and the whole vdir expands from `DTSTART` in milliseconds. A cap of 10 000 iterations per series guards a pathological rule. + +## File structure + +| File | Responsibility | +|---|---| +| `src/icalraii.h` | unique_ptr aliases for libical handles. Included only by `calendarstore.cpp`. | +| `src/caltypes.h` | Plain value structs: `CalCollection`, `CalPerson`, `CalOverride`, `CalEvent`, `Occurrence`, `CalendarItem`, `EventEdit`, `LoadResult`. | +| `src/repeatrule.h/.cpp` | `RepeatRule`: the repeat control's model, `RRULE` value text in and out, and a sentence describing it. No libical. | +| `src/calendarstore.h/.cpp` | The only libical user: load a vdir, parse one file, expand occurrences, apply an edit, build a new event, add an `EXDATE`, compare two texts by meaning, decide editability. | +| `src/calendarwriter.h/.cpp` | One function: replace a file's content (create, edit, delete) atomically, refusing when the file is not what the caller expects. | +| `src/calendarsync.h/.cpp` | QObject owning the debounced `QProcess` for `calendar_sync_command`. | +| `src/monthlayout.h/.cpp` | Pure geometry of the month grid. | +| `src/monthview.h/.cpp` | Paints a `MonthLayout` with `CalendarItem`s; emits clicks. | +| `src/agendaview.h/.cpp` | A `QListWidget` grouped by day. | +| `src/eventpane.h/.cpp` | The side pane: read-only details page and the edit form, including the repeat control. | +| `src/calendarwindow.h/.cpp` | The top-level window: toolbar, views, pane, reload, undo, sync, the edit lock. | +| `src/config.h/.cpp` | Four `[general]` keys. | +| `src/keymap.cpp`, `src/mainwindow.h/.cpp` | The `calendar` action in the five places AGENTS.md lists; single instance. | +| `tests/test_repeatrule.cpp`, `test_calendarstore.cpp`, `test_calendarwriter.cpp`, `test_calendarsync.cpp`, `test_monthlayout.cpp`, `test_calendarwindow.cpp` | One suite per unit. Fixtures are inline strings with example.org addresses. | + +--- + +### Task 1: Build wiring, RAII aliases, value structs, and parsing one event + +**Files:** +- Modify: `CMakeLists.txt` (after the GMime `pkg_check_modules` line) +- Modify: `src/CMakeLists.txt` +- Modify: `tests/CMakeLists.txt` +- Create: `src/icalraii.h`, `src/caltypes.h`, `src/repeatrule.h`, `src/repeatrule.cpp` (stub for now), `src/calendarstore.h`, `src/calendarstore.cpp` +- Test: `tests/test_calendarstore.cpp` + +- [ ] **Step 1: Wire libical into CMake** + +In `CMakeLists.txt`, directly under `pkg_check_modules(GMIME REQUIRED IMPORTED_TARGET gmime-3.0)`: + +```cmake +# libical parses and writes the calendar's iCalendar files (item 206). Unlike +# notmuch it ships a .pc, so pkg-config finds it; unlike GMime it pulls in no +# glib, so its headers may sit anywhere in an include list. +pkg_check_modules(LIBICAL REQUIRED IMPORTED_TARGET libical) +``` + +In `src/CMakeLists.txt`, add to the `qtmaildir_lib` source list after `signatures.cpp`: + +```cmake + repeatrule.cpp + calendarstore.cpp +``` + +and add `PkgConfig::LIBICAL` to `target_link_libraries(qtmaildir_lib PUBLIC ...)` after `PkgConfig::GMIME`. + +In `tests/CMakeLists.txt`, after the `contactstore` block: + +```cmake +add_qtmaildir_test(repeatrule) +add_qtmaildir_test(calendarstore) +``` + +- [ ] **Step 2: Write `src/icalraii.h`** + +```cpp +/* GPLv2 header, as src/contactstore.h lines 1-17 */ + +#pragma once + +#include <libical/ical.h> + +#include <cstdlib> +#include <memory> + +/// Owners for libical handles, the calendar's counterpart to nmraii.h. +/// +/// The same rule as notmuch's: no libical pointer leaves calendarstore.cpp, +/// the one file that includes this header. unique_ptr rather than NmHandle's +/// template because every libical handle here has exactly one destroy +/// function and no aliasing, which is what unique_ptr already expresses. +struct IcalComponentFree { + void operator()(icalcomponent *c) const { icalcomponent_free(c); } +}; +using IcalComponent = std::unique_ptr<icalcomponent, IcalComponentFree>; + +struct IcalRecurFree { + void operator()(icalrecur_iterator *i) const { icalrecur_iterator_free(i); } +}; +using IcalRecurIterator = std::unique_ptr<icalrecur_iterator, IcalRecurFree>; + +/// For strings returned by the `*_r` functions, which the caller must free(). +/// The plain variants return a ring buffer libical reuses, so a pointer kept +/// from one is overwritten by a later call. +struct IcalStringFree { + void operator()(char *s) const { std::free(s); } +}; +using IcalString = std::unique_ptr<char, IcalStringFree>; +``` + +- [ ] **Step 3: Write `src/repeatrule.h` and a stub `src/repeatrule.cpp`** + +The full implementation is Task 3; the type must exist now because `CalEvent` holds one. + +```cpp +/* GPLv2 header */ + +#pragma once + +#include <QDate> +#include <QList> +#include <QString> + +/// The repeat control's model, and its RRULE value text in both directions. +/// +/// No libical: an RRULE value is `KEY=VALUE;KEY=VALUE`, which is simpler to +/// read and write as text than through icalrecurrencetype, and keeping it pure +/// is what lets every row of the spec's repeat table be tested as a string. +struct RepeatRule +{ + enum class Freq { None, Daily, Weekly, Monthly, Yearly }; + /// Monthly and Yearly only: on a day of the month, or on the Nth weekday. + enum class By { MonthDay, Weekday }; + enum class End { Never, Until, Count }; + + Freq freq = Freq::None; + int interval = 1; + /// Weekly: Qt::DayOfWeek values, 1 (Monday) to 7 (Sunday), sorted. + QList<int> weekdays; + By by = By::MonthDay; + int monthDay = 0; ///< Monthly, By::MonthDay: 1 to 31. + int ordinal = 0; ///< By::Weekday: 1 to 4, or -1 for "last". + int weekday = 0; ///< By::Weekday: Qt::DayOfWeek. + int month = 0; ///< Yearly, By::Weekday: 1 to 12. + End end = End::Never; + QDate until; ///< End::Until: the last day an occurrence may fall on. + int count = 0; ///< End::Count. + /// Carried through a rewrite untouched, per the spec: several existing + /// rules carry it and it changes nothing for the modes above. + QString wkst; + + /// A rule outside the control's table. `customText` is the value exactly + /// as read, and an edit never rewrites it. + bool custom = false; + QString customText; + + /// Parses an RRULE value (no "RRULE:" prefix). `start` is the event's + /// first day, which fills in what an RRULE leaves implicit (a weekly rule + /// with no BYDAY repeats on the start's weekday). + static RepeatRule fromRRule(const QString &value, const QDate &start); + + /// The RRULE value, or an empty string for Freq::None. `untilValue` is + /// the whole UNTIL value, `20261231` for an all-day event or + /// `20261231T225959Z` for a timed one, computed by the caller because + /// only it knows the event's zone. Ignored unless end is End::Until. + QString toRRule(const QString &untilValue = QString()) const; + + /// "Monthly, on the last Friday", translated. Custom rules say so. + QString describe() const; + + bool operator==(const RepeatRule &other) const; +}; +``` + +`src/repeatrule.cpp`, stub: + +```cpp +/* GPLv2 header */ + +#include "repeatrule.h" + +RepeatRule RepeatRule::fromRRule(const QString &, const QDate &) { return {}; } +QString RepeatRule::toRRule(const QString &) const { return {}; } +QString RepeatRule::describe() const { return {}; } +bool RepeatRule::operator==(const RepeatRule &) const { return false; } +``` + +Also create an empty `tests/test_repeatrule.cpp` so CMake configures (Task 3 fills it): + +```cpp +/* GPLv2 header */ + +#include <QtTest> + +#include "repeatrule.h" + +class TestRepeatRule : public QObject +{ + Q_OBJECT +}; + +QTEST_MAIN(TestRepeatRule) +#include "test_repeatrule.moc" +``` + +- [ ] **Step 4: Write `src/caltypes.h`** + +```cpp +/* GPLv2 header */ + +#pragma once + +#include "repeatrule.h" + +#include <QByteArray> +#include <QColor> +#include <QDateTime> +#include <QList> +#include <QString> + +/// One vdir collection: a subdirectory of calendars_dir. +struct CalCollection +{ + QString dir; ///< The directory's own name, e.g. "52". + QString path; ///< Absolute path. + /// From the vdir's `displayname` file, which vdirsyncer's metasync fills + /// from the server; the directory name when absent. + QString displayName; + /// From the vdir's `color` file (`#RRGGBB`); a colour hashed from the + /// directory name when absent, so no collection is ever invisible. + QColor color; + bool readOnly = false; ///< The directory is not writable. +}; + +struct CalPerson +{ + QString name; ///< CN, possibly empty. + QString address; ///< The address with "mailto:" removed. + QString partstat; ///< PARTSTAT as written, e.g. "ACCEPTED"; empty if absent. +}; + +/// A RECURRENCE-ID override: one occurrence of a series moved or changed. +struct CalOverride +{ + QDateTime recurrenceId; ///< The original slot it replaces. + QDateTime start; + QDateTime end; + bool allDay = false; + QString summary; + QString location; + QString description; + bool cancelled = false; ///< STATUS:CANCELLED: the slot is removed. +}; + +/// One .ics file's event, as the rest of the application sees it. +struct CalEvent +{ + QString filePath; + QString collectionDir; + QString uid; + QString summary; + QString location; + QString description; + QDateTime start; + QDateTime end; ///< Exclusive. For an all-day event, midnight after the last day. + bool allDay = false; + RepeatRule repeat; ///< Freq::None when the event does not repeat. + QList<QDateTime> exdates; + QList<CalOverride> overrides; + bool hasAlarm = false; + CalPerson organizer; ///< Empty address: no ORGANIZER. + QList<CalPerson> attendees; + int sequence = 0; + QByteArray rawText; ///< The file exactly as read: stale checks and undo. +}; + +/// One expanded occurrence. What a view is built from. +struct Occurrence +{ + int eventIndex = -1; ///< Into LoadResult::events. + QDateTime start; + QDateTime end; + bool allDay = false; + /// The slot this occurrence fills in its series, which is what a + /// RECURRENCE-ID or an EXDATE names. Invalid for a non-repeating event. + QDateTime recurrenceId; + bool isOverride = false; + int overrideIndex = -1; ///< Into CalEvent::overrides when isOverride. +}; + +/// An occurrence plus what a view draws. Views see nothing else. +struct CalendarItem +{ + Occurrence occurrence; + QString title; + QColor color; +}; + +/// What the edit form produces. +struct EventEdit +{ + QString summary; + QString location; + QString description; + QDateTime start; + QDateTime end; + bool allDay = false; + RepeatRule repeat; + QString collectionDir; +}; + +struct LoadResult +{ + QList<CalCollection> collections; + QList<CalEvent> events; + int unparsable = 0; ///< Files skipped because they did not parse. + int unknownZones = 0; ///< Events whose TZID resolved to nothing, shown in local time. +}; +``` + +- [ ] **Step 5: Write the failing test** + +`tests/test_calendarstore.cpp`: + +```cpp +/* GPLv2 header */ + +#include <QtTest> +#include <QDir> +#include <QFile> +#include <QTemporaryDir> +#include <QTimeZone> + +#include "calendarstore.h" + +namespace { + +/// Wraps VEVENT lines (and optional extra components) into a VCALENDAR. +QByteArray ics(const QString &body) +{ + return QStringLiteral("BEGIN:VCALENDAR\r\nVERSION:2.0\r\n" + "PRODID:-//example//test//EN\r\n%1END:VCALENDAR\r\n") + .arg(body).toUtf8(); +} + +QString vevent(const QString &lines) +{ + return QStringLiteral("BEGIN:VEVENT\r\n%1END:VEVENT\r\n").arg(lines); +} + +} // namespace + +class TestCalendarStore : public QObject +{ + Q_OBJECT + +private slots: + void parsesAUtcEvent(); +}; + +void TestCalendarStore::parsesAUtcEvent() +{ + bool unknownZone = true; + const CalEvent event = CalendarStore::parseEvent( + ics(vevent(QStringLiteral( + "UID:utc-1@example.org\r\nDTSTAMP:20260901T000000Z\r\n" + "SUMMARY:Standup\r\nLOCATION:Room 2\r\n" + "DTSTART:20260922T080000Z\r\nDTEND:20260922T081500Z\r\n" + "SEQUENCE:3\r\n"))), + QStringLiteral("/tmp/x/utc-1.ics"), QStringLiteral("x"), &unknownZone); + + QCOMPARE(event.uid, QStringLiteral("utc-1@example.org")); + QCOMPARE(event.summary, QStringLiteral("Standup")); + QCOMPARE(event.location, QStringLiteral("Room 2")); + QCOMPARE(event.start, QDateTime(QDate(2026, 9, 22), QTime(8, 0), QTimeZone::utc())); + QCOMPARE(event.end, QDateTime(QDate(2026, 9, 22), QTime(8, 15), QTimeZone::utc())); + QVERIFY(!event.allDay); + QCOMPARE(event.sequence, 3); + QCOMPARE(event.filePath, QStringLiteral("/tmp/x/utc-1.ics")); + QVERIFY(!unknownZone); + QVERIFY(!event.rawText.isEmpty()); +} + +QTEST_MAIN(TestCalendarStore) +#include "test_calendarstore.moc" +``` + +- [ ] **Step 6: Write `src/calendarstore.h`** + +```cpp +/* GPLv2 header */ + +#pragma once + +#include "caltypes.h" + +#include <QByteArray> +#include <QDateTime> +#include <QList> +#include <QString> +#include <QStringList> + +/// The calendar's iCalendar work, and the only code that includes libical. +/// +/// A namespace of free functions over values, like ContactStore and +/// MimeParser, so every rule with a right answer is testable without a +/// widget. See the spec, docs/superpowers/specs/2026-09-24-calendar-design.md. +namespace CalendarStore { + +enum class Scope { All, ThisOccurrence }; + +/// Parses one file's text. An empty uid in the result means the text held no +/// usable VEVENT. `unknownZone` is set when a TZID resolved to nothing and the +/// times were read as local. +CalEvent parseEvent(const QByteArray &text, const QString &filePath, + const QString &collectionDir, bool *unknownZone); + +/// Reads every collection under `dir` and every *.ics in each. +LoadResult load(const QString &dir); + +/// Every occurrence of every event overlapping [from, to), sorted by start. +QList<Occurrence> occurrences(const QList<CalEvent> &events, + const QDateTime &from, const QDateTime &to); + +/// Whether the user may edit or delete `event`: its collection is writable, +/// and it has no ORGANIZER or the organiser is one of `ownAddresses`. +bool isEditable(const CalEvent &event, const CalCollection &collection, + const QStringList &ownAddresses); + +/// Applies `edit` to the file text and returns the new text; empty when the +/// text does not parse. Scope::ThisOccurrence writes or replaces the override +/// for `recurrenceId`. Properties the form does not own survive. +QByteArray applyEdit(const QByteArray &text, const EventEdit &edit, + Scope scope, const QDateTime &recurrenceId); + +/// A complete new file for `edit`, timed events in the IANA zone `zoneId`. +QByteArray newEvent(const EventEdit &edit, const QByteArray &zoneId); + +/// Removes one occurrence: adds an EXDATE to the master and drops any override +/// for that slot. Empty on a parse failure. +QByteArray deleteOccurrence(const QByteArray &text, const QDateTime &recurrenceId); + +/// Whether two texts describe the same event: summary, times, repeat rule, +/// exceptions. Formatting is ignored, since the server may normalise it. +bool sameMeaning(const QByteArray &a, const QByteArray &b); + +} // namespace CalendarStore +``` + +- [ ] **Step 7: Run the test to verify it fails** + +Run: `cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug && cmake --build build 2>&1 | tail -5` +Expected: link failure, undefined reference to `CalendarStore::parseEvent`. + +- [ ] **Step 8: Write the parsing half of `src/calendarstore.cpp`** + +Only `parseEvent` and the time helper for now, with the remaining functions as stubs so the library links. Later tasks replace each stub. + +```cpp +/* GPLv2 header */ + +#include "calendarstore.h" +#include "icalraii.h" + +#include <QTimeZone> + +namespace { + +QString str(const char *s) { return s ? QString::fromUtf8(s) : QString(); } + +QByteArray tzidOf(icalproperty *prop) +{ + if (!prop) + return {}; + icalparameter *param = icalproperty_get_first_parameter(prop, ICAL_TZID_PARAMETER); + return param ? QByteArray(icalparameter_get_tzid(param)) : QByteArray(); +} + +/// One icaltimetype to a QDateTime, in this order (spec, "Time and +/// recurrence"): a date is local midnight; UTC is UTC; a zone libical resolved +/// (an embedded VTIMEZONE) converts through libical; a TZID libical could not +/// resolve is tried as an IANA name through QTimeZone; anything else is local +/// wall-clock time, and an unresolvable TZID sets *unknownZone. +QDateTime toDateTime(icaltimetype t, const QByteArray &tzid, bool *unknownZone) +{ + if (icaltime_is_null_time(t)) + return {}; + const QDate date(t.year, t.month, t.day); + if (t.is_date) + return QDateTime(date, QTime(0, 0)); + const QTime time(t.hour, t.minute, t.second); + if (icaltime_is_utc(t)) + return QDateTime(date, time, QTimeZone::utc()); + if (t.zone) { + const icaltimetype utc = + icaltime_convert_to_zone(t, icaltimezone_get_utc_timezone()); + return QDateTime(QDate(utc.year, utc.month, utc.day), + QTime(utc.hour, utc.minute, utc.second), QTimeZone::utc()); + } + if (!tzid.isEmpty()) { + const QTimeZone zone(tzid); + if (zone.isValid()) + return QDateTime(date, time, zone); + if (unknownZone) + *unknownZone = true; + } + return QDateTime(date, time); +} + +CalPerson personOf(icalproperty *prop) +{ + CalPerson person; + QString value = str(icalproperty_get_value_as_string(prop)); + if (value.startsWith(QLatin1String("mailto:"), Qt::CaseInsensitive)) + value = value.mid(7); + person.address = value; + person.name = str(icalproperty_get_parameter_as_string(prop, "CN")); + person.partstat = str(icalproperty_get_parameter_as_string(prop, "PARTSTAT")); + return person; +} + +/// The VEVENT without a RECURRENCE-ID, or the first VEVENT if every one has. +icalcomponent *masterOf(icalcomponent *root) +{ + icalcomponent *first = nullptr; + for (icalcomponent *c = icalcomponent_get_first_component(root, ICAL_VEVENT_COMPONENT); + c; c = icalcomponent_get_next_component(root, ICAL_VEVENT_COMPONENT)) { + if (!first) + first = c; + if (!icalcomponent_get_first_property(c, ICAL_RECURRENCEID_PROPERTY)) + return c; + } + return first; +} + +IcalComponent parseRoot(const QByteArray &text) +{ + IcalComponent root(icalparser_parse_string(text.constData())); + if (root && icalcomponent_isa(root.get()) == ICAL_VEVENT_COMPONENT) { + // A bare VEVENT with no VCALENDAR around it: wrap it, so every + // caller walks the same shape. + IcalComponent cal(icalcomponent_new(ICAL_VCALENDAR_COMPONENT)); + icalcomponent_add_component(cal.get(), root.release()); + return cal; + } + return root; +} + +/// The end of a component: DTEND, else DTSTART + DURATION (libical computes +/// both through get_dtend), else one day for a date and the start otherwise. +QDateTime endOf(icalcomponent *c, const QDateTime &start, bool allDay, bool *unknownZone) +{ + icalproperty *endProp = icalcomponent_get_first_property(c, ICAL_DTEND_PROPERTY); + const icaltimetype end = icalcomponent_get_dtend(c); + if (!icaltime_is_null_time(end)) + return toDateTime(end, tzidOf(endProp ? endProp + : icalcomponent_get_first_property(c, ICAL_DTSTART_PROPERTY)), + unknownZone); + return allDay ? start.addDays(1) : start; +} + +} // namespace + +namespace CalendarStore { + +CalEvent parseEvent(const QByteArray &text, const QString &filePath, + const QString &collectionDir, bool *unknownZone) +{ + CalEvent event; + event.filePath = filePath; + event.collectionDir = collectionDir; + event.rawText = text; + if (unknownZone) + *unknownZone = false; + + IcalComponent root = parseRoot(text); + if (!root) + return event; + icalcomponent *master = masterOf(root.get()); + if (!master) + return event; + + event.uid = str(icalcomponent_get_uid(master)); + event.summary = str(icalcomponent_get_summary(master)); + event.location = str(icalcomponent_get_location(master)); + event.description = str(icalcomponent_get_description(master)); + event.sequence = icalcomponent_get_sequence(master); + + icalproperty *startProp = icalcomponent_get_first_property(master, ICAL_DTSTART_PROPERTY); + const icaltimetype start = icalcomponent_get_dtstart(master); + event.allDay = start.is_date; + event.start = toDateTime(start, tzidOf(startProp), unknownZone); + event.end = endOf(master, event.start, event.allDay, unknownZone); + + event.hasAlarm = icalcomponent_get_first_component(master, ICAL_VALARM_COMPONENT); + if (icalproperty *org = icalcomponent_get_first_property(master, ICAL_ORGANIZER_PROPERTY)) + event.organizer = personOf(org); + for (icalproperty *a = icalcomponent_get_first_property(master, ICAL_ATTENDEE_PROPERTY); + a; a = icalcomponent_get_next_property(master, ICAL_ATTENDEE_PROPERTY)) + event.attendees.append(personOf(a)); + + // Recurrence, exceptions and overrides: Task 4. + return event; +} + +LoadResult load(const QString &) { return {}; } +QList<Occurrence> occurrences(const QList<CalEvent> &, const QDateTime &, const QDateTime &) { return {}; } +bool isEditable(const CalEvent &, const CalCollection &, const QStringList &) { return false; } +QByteArray applyEdit(const QByteArray &, const EventEdit &, Scope, const QDateTime &) { return {}; } +QByteArray newEvent(const EventEdit &, const QByteArray &) { return {}; } +QByteArray deleteOccurrence(const QByteArray &, const QDateTime &) { return {}; } +bool sameMeaning(const QByteArray &, const QByteArray &) { return false; } + +} // namespace CalendarStore +``` + +- [ ] **Step 9: Run the test to verify it passes** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_calendarstore` +Expected: `Totals: 3 passed, 0 failed` (initTestCase, parsesAUtcEvent, cleanupTestCase). + +- [ ] **Step 10: Commit** + +```bash +git add CMakeLists.txt src/CMakeLists.txt tests/CMakeLists.txt src/icalraii.h src/caltypes.h \ + src/repeatrule.h src/repeatrule.cpp src/calendarstore.h src/calendarstore.cpp \ + tests/test_calendarstore.cpp tests/test_repeatrule.cpp +git commit -m "feat: parse one calendar event with libical (item 206)" +``` + +--- + +### Task 2: Every time form, and loading a vdir + +**Files:** +- Modify: `src/calendarstore.cpp` (`load`) +- Test: `tests/test_calendarstore.cpp` + +- [ ] **Step 1: Write the failing tests** + +Add to the `private slots:` list and the file: + +```cpp + void readsATzidWithItsVtimezone(); + void readsATzidWithoutAVtimezoneAsIana(); + void readsAnUnknownTzidAsLocalAndSaysSo(); + void readsFloatingTimeAsLocal(); + void readsAnAllDayEventWithAnExclusiveEnd(); + void loadReadsCollectionsAndFallsBack(); + void loadSkipsAndCountsABrokenFile(); +``` + +```cpp +namespace { + +const char *kRomeVtimezone = + "BEGIN:VTIMEZONE\r\nTZID:Europe/Rome\r\n" + "BEGIN:DAYLIGHT\r\nTZOFFSETFROM:+0100\r\nTZOFFSETTO:+0200\r\nTZNAME:CEST\r\n" + "DTSTART:19700329T020000\r\nRRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=-1SU\r\nEND:DAYLIGHT\r\n" + "BEGIN:STANDARD\r\nTZOFFSETFROM:+0200\r\nTZOFFSETTO:+0100\r\nTZNAME:CET\r\n" + "DTSTART:19701025T030000\r\nRRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU\r\nEND:STANDARD\r\n" + "END:VTIMEZONE\r\n"; + +CalEvent parse(const QString &body, bool *unknown = nullptr) +{ + bool ignored = false; + return CalendarStore::parseEvent(ics(body), QStringLiteral("/x/e.ics"), + QStringLiteral("x"), unknown ? unknown : &ignored); +} + +void writeFile(const QString &path, const QByteArray &content) +{ + QDir().mkpath(QFileInfo(path).absolutePath()); + QFile file(path); + QVERIFY2(file.open(QIODevice::WriteOnly | QIODevice::Truncate), + qPrintable(file.errorString())); + file.write(content); +} + +} // namespace + +void TestCalendarStore::readsATzidWithItsVtimezone() +{ + const CalEvent e = parse(QString::fromLatin1(kRomeVtimezone) + vevent(QStringLiteral( + "UID:a@example.org\r\nDTSTART;TZID=Europe/Rome:20260922T100000\r\n" + "DTEND;TZID=Europe/Rome:20260922T110000\r\n"))); + // 10:00 in Rome in September is 08:00 UTC (CEST, +2). + QCOMPARE(e.start.toUTC(), QDateTime(QDate(2026, 9, 22), QTime(8, 0), QTimeZone::utc())); + QCOMPARE(e.end.toUTC(), QDateTime(QDate(2026, 9, 22), QTime(9, 0), QTimeZone::utc())); +} + +void TestCalendarStore::readsATzidWithoutAVtimezoneAsIana() +{ + // 120 of the user's 312 files are shaped like this: RFC 5545 requires the + // VTIMEZONE, and real servers omit it. + bool unknown = true; + const CalEvent e = parse(vevent(QStringLiteral( + "UID:b@example.org\r\nDTSTART;TZID=Europe/Rome:20260922T100000\r\n" + "DTEND;TZID=Europe/Rome:20260922T110000\r\n")), &unknown); + QCOMPARE(e.start.toUTC(), QDateTime(QDate(2026, 9, 22), QTime(8, 0), QTimeZone::utc())); + QVERIFY(!unknown); +} + +void TestCalendarStore::readsAnUnknownTzidAsLocalAndSaysSo() +{ + bool unknown = false; + const CalEvent e = parse(vevent(QStringLiteral( + "UID:c@example.org\r\nDTSTART;TZID=Not A Zone:20260922T100000\r\n" + "DTEND;TZID=Not A Zone:20260922T110000\r\n")), &unknown); + QVERIFY(unknown); + QCOMPARE(e.start, QDateTime(QDate(2026, 9, 22), QTime(10, 0))); +} + +void TestCalendarStore::readsFloatingTimeAsLocal() +{ + const CalEvent e = parse(vevent(QStringLiteral( + "UID:d@example.org\r\nDTSTART:20260922T100000\r\nDTEND:20260922T110000\r\n"))); + QCOMPARE(e.start, QDateTime(QDate(2026, 9, 22), QTime(10, 0))); + QCOMPARE(e.start.timeSpec(), Qt::LocalTime); +} + +void TestCalendarStore::readsAnAllDayEventWithAnExclusiveEnd() +{ + const CalEvent e = parse(vevent(QStringLiteral( + "UID:e@example.org\r\nDTSTART;VALUE=DATE:20260924\r\nDTEND;VALUE=DATE:20260925\r\n"))); + QVERIFY(e.allDay); + QCOMPARE(e.start.date(), QDate(2026, 9, 24)); + // Exclusive: a one-day event on the 24th ends at the START of the 25th. + QCOMPARE(e.end.date(), QDate(2026, 9, 25)); + QCOMPARE(e.end.time(), QTime(0, 0)); +} + +void TestCalendarStore::loadReadsCollectionsAndFallsBack() +{ + QTemporaryDir dir; + const QString root = dir.path(); + writeFile(root + QStringLiteral("/52/displayname"), "Work"); + writeFile(root + QStringLiteral("/52/color"), "#60a5fa\n"); + writeFile(root + QStringLiteral("/52/one.ics"), ics(vevent(QStringLiteral( + "UID:one@example.org\r\nDTSTART:20260922T080000Z\r\n")))); + writeFile(root + QStringLiteral("/31/two.ics"), ics(vevent(QStringLiteral( + "UID:two@example.org\r\nDTSTART:20260923T080000Z\r\n")))); + writeFile(root + QStringLiteral("/31/notes.txt"), "not a calendar file"); + + const LoadResult r = CalendarStore::load(root); + QCOMPARE(r.collections.size(), 2); + QCOMPARE(r.events.size(), 2); + QCOMPARE(r.unparsable, 0); + + // Sorted by display name, so "31" (no displayname) sorts before "Work". + QCOMPARE(r.collections[0].dir, QStringLiteral("31")); + QCOMPARE(r.collections[0].displayName, QStringLiteral("31")); + QVERIFY(r.collections[0].color.isValid()); + QCOMPARE(r.collections[1].displayName, QStringLiteral("Work")); + QCOMPARE(r.collections[1].color, QColor(QStringLiteral("#60a5fa"))); + QVERIFY(!r.collections[1].readOnly); + + // The hashed fallback is stable across loads, or colours would shuffle. + QCOMPARE(CalendarStore::load(root).collections[0].color, r.collections[0].color); +} + +void TestCalendarStore::loadSkipsAndCountsABrokenFile() +{ + QTemporaryDir dir; + writeFile(dir.path() + QStringLiteral("/c/good.ics"), ics(vevent(QStringLiteral( + "UID:good@example.org\r\nDTSTART:20260922T080000Z\r\n")))); + writeFile(dir.path() + QStringLiteral("/c/bad.ics"), "this is not iCalendar"); + const LoadResult r = CalendarStore::load(dir.path()); + QCOMPARE(r.events.size(), 1); + QCOMPARE(r.unparsable, 1); +} +``` + +Add `#include <QFileInfo>` to the test's includes. + +- [ ] **Step 2: Run them to verify they fail** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_calendarstore` +Expected: the five parse tests PASS already (Task 1's `toDateTime` covers them; that is fine, they pin the behaviour), and the two `load*` tests FAIL (`load` is a stub returning nothing). If any parse test fails, fix `toDateTime` before going on. + +- [ ] **Step 3: Implement `load`** + +Replace the `load` stub. Add includes `<QCryptographicHash>`, `<QDir>`, `<QFile>`, `<QFileInfo>` and `<algorithm>` at the top of `calendarstore.cpp`. + +```cpp +namespace { + +QString readTrimmed(const QString &path) +{ + QFile file(path); + if (!file.open(QIODevice::ReadOnly)) + return {}; + return QString::fromUtf8(file.readAll()).trimmed(); +} + +/// A colour for a collection with no `color` file, derived from its directory +/// name so it is the same on every load and on every machine. +QColor hashedColour(const QString &dir) +{ + const QByteArray hash = QCryptographicHash::hash(dir.toUtf8(), QCryptographicHash::Md5); + const int hue = (static_cast<unsigned char>(hash[0]) * 256 + + static_cast<unsigned char>(hash[1])) % 360; + return QColor::fromHsl(hue, 150, 140); +} + +} // namespace +``` + +```cpp +LoadResult load(const QString &dir) +{ + LoadResult result; + const QFileInfoList subdirs = + QDir(dir).entryInfoList(QDir::Dirs | QDir::NoDotAndDotDot, QDir::Name); + for (const QFileInfo &sub : subdirs) { + CalCollection collection; + collection.dir = sub.fileName(); + collection.path = sub.absoluteFilePath(); + collection.displayName = readTrimmed(collection.path + QStringLiteral("/displayname")); + if (collection.displayName.isEmpty()) + collection.displayName = collection.dir; + collection.color = QColor(readTrimmed(collection.path + QStringLiteral("/color"))); + if (!collection.color.isValid()) + collection.color = hashedColour(collection.dir); + collection.readOnly = !sub.isWritable(); + result.collections.append(collection); + + const QFileInfoList files = + QDir(collection.path).entryInfoList({ QStringLiteral("*.ics") }, QDir::Files, QDir::Name); + for (const QFileInfo &file : files) { + QFile f(file.absoluteFilePath()); + if (!f.open(QIODevice::ReadOnly)) { + ++result.unparsable; + continue; + } + bool unknown = false; + CalEvent event = parseEvent(f.readAll(), file.absoluteFilePath(), + collection.dir, &unknown); + if (event.uid.isEmpty() || !event.start.isValid()) { + ++result.unparsable; + continue; + } + if (unknown) + ++result.unknownZones; + result.events.append(event); + } + } + std::sort(result.collections.begin(), result.collections.end(), + [](const CalCollection &a, const CalCollection &b) { + return a.displayName.localeAwareCompare(b.displayName) < 0; + }); + return result; +} +``` + +- [ ] **Step 4: Run the tests to verify they pass** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_calendarstore` +Expected: all PASS. + +- [ ] **Step 5: Commit** + +```bash +git add src/calendarstore.cpp tests/test_calendarstore.cpp +git commit -m "feat: read every time form and load a calendar vdir" +``` + +--- + +### Task 3: `RepeatRule` + +**Files:** +- Modify: `src/repeatrule.cpp` +- Test: `tests/test_repeatrule.cpp` + +- [ ] **Step 1: Write the failing tests** + +Replace `tests/test_repeatrule.cpp`: + +```cpp +/* GPLv2 header */ + +#include <QtTest> + +#include "repeatrule.h" + +class TestRepeatRule : public QObject +{ + Q_OBJECT + +private slots: + void roundTripsEveryRowOfTheTable_data(); + void roundTripsEveryRowOfTheTable(); + void fillsWhatAnRruleLeavesImplicit(); + void recognisesACustomRule_data(); + void recognisesACustomRule(); + void keepsWkst(); + void readsUntilInEveryForm(); + void describesInWords(); +}; + +void TestRepeatRule::roundTripsEveryRowOfTheTable_data() +{ + QTest::addColumn<QString>("rrule"); + // Each row of the spec's repeat table, written the way toRRule writes it. + QTest::newRow("daily") << QStringLiteral("FREQ=DAILY"); + QTest::newRow("every 3 days") << QStringLiteral("FREQ=DAILY;INTERVAL=3"); + QTest::newRow("weekly on days") << QStringLiteral("FREQ=WEEKLY;BYDAY=MO,WE,FR"); + QTest::newRow("monthly on day") << QStringLiteral("FREQ=MONTHLY;BYMONTHDAY=18"); + QTest::newRow("monthly last friday") << QStringLiteral("FREQ=MONTHLY;BYDAY=-1FR"); + QTest::newRow("monthly 2nd tuesday") << QStringLiteral("FREQ=MONTHLY;INTERVAL=2;BYDAY=2TU"); + QTest::newRow("yearly") << QStringLiteral("FREQ=YEARLY"); + QTest::newRow("yearly last fri of sep") << QStringLiteral("FREQ=YEARLY;BYMONTH=9;BYDAY=-1FR"); + QTest::newRow("count") << QStringLiteral("FREQ=MONTHLY;BYMONTHDAY=18;COUNT=12"); + QTest::newRow("until date") << QStringLiteral("FREQ=YEARLY;UNTIL=20301231"); +} + +void TestRepeatRule::roundTripsEveryRowOfTheTable() +{ + QFETCH(QString, rrule); + const QDate start(2026, 9, 18); + const RepeatRule rule = RepeatRule::fromRRule(rrule, start); + QVERIFY2(!rule.custom, qPrintable(rrule)); + // UNTIL in the "until date" row is a DATE, so the all-day form (no suffix). + QCOMPARE(rule.toRRule(rule.end == RepeatRule::End::Until + ? rule.until.toString(QStringLiteral("yyyyMMdd")) + : QString()), + rrule); + QCOMPARE(RepeatRule::fromRRule(rule.toRRule(rule.until.toString(QStringLiteral("yyyyMMdd"))), + start), rule); +} + +void TestRepeatRule::fillsWhatAnRruleLeavesImplicit() +{ + // 2026-09-18 is a Friday. + const RepeatRule weekly = RepeatRule::fromRRule(QStringLiteral("FREQ=WEEKLY"), QDate(2026, 9, 18)); + QCOMPARE(weekly.weekdays, QList<int>{ Qt::Friday }); + const RepeatRule monthly = RepeatRule::fromRRule(QStringLiteral("FREQ=MONTHLY"), QDate(2026, 9, 18)); + QCOMPARE(monthly.by, RepeatRule::By::MonthDay); + QCOMPARE(monthly.monthDay, 18); +} + +void TestRepeatRule::recognisesACustomRule_data() +{ + QTest::addColumn<QString>("rrule"); + QTest::newRow("bysetpos") << QStringLiteral("FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1"); + QTest::newRow("byweekno") << QStringLiteral("FREQ=YEARLY;BYWEEKNO=20"); + QTest::newRow("hourly") << QStringLiteral("FREQ=HOURLY"); + QTest::newRow("two months") << QStringLiteral("FREQ=YEARLY;BYMONTH=3,9;BYDAY=-1FR"); + QTest::newRow("two monthdays") << QStringLiteral("FREQ=MONTHLY;BYMONTHDAY=1,15"); + QTest::newRow("weekly ordinal") << QStringLiteral("FREQ=WEEKLY;BYDAY=1MO"); + QTest::newRow("fifth monday") << QStringLiteral("FREQ=MONTHLY;BYDAY=5MO"); +} + +void TestRepeatRule::recognisesACustomRule() +{ + QFETCH(QString, rrule); + const RepeatRule rule = RepeatRule::fromRRule(rrule, QDate(2026, 9, 18)); + QVERIFY(rule.custom); + // An edit never rewrites a custom rule: it comes back exactly. + QCOMPARE(rule.toRRule(), rrule); +} + +void TestRepeatRule::keepsWkst() +{ + const RepeatRule rule = RepeatRule::fromRRule(QStringLiteral("FREQ=YEARLY;WKST=TU"), QDate(2026, 9, 18)); + QVERIFY(!rule.custom); + QCOMPARE(rule.toRRule(), QStringLiteral("FREQ=YEARLY;WKST=TU")); +} + +void TestRepeatRule::readsUntilInEveryForm() +{ + const QDate start(2026, 9, 18); + QCOMPARE(RepeatRule::fromRRule(QStringLiteral("FREQ=DAILY;UNTIL=20261231"), start).until, + QDate(2026, 12, 31)); + QCOMPARE(RepeatRule::fromRRule(QStringLiteral("FREQ=DAILY;UNTIL=20261231T120000"), start).until, + QDate(2026, 12, 31)); + // A UTC UNTIL keeps its UTC date: the caller writes 23:59:59 local as UTC, + // which in a zone east of UTC is still the same date. + QCOMPARE(RepeatRule::fromRRule(QStringLiteral("FREQ=DAILY;UNTIL=20261231T215959Z"), start).until, + QDate(2026, 12, 31)); + QCOMPARE(RepeatRule::fromRRule(QStringLiteral("FREQ=DAILY;UNTIL=20261231"), start).end, + RepeatRule::End::Until); +} + +void TestRepeatRule::describesInWords() +{ + const QDate start(2026, 9, 18); + QCOMPARE(RepeatRule::fromRRule(QStringLiteral("FREQ=DAILY"), start).describe(), + QStringLiteral("Daily")); + QCOMPARE(RepeatRule::fromRRule(QStringLiteral("FREQ=MONTHLY;BYDAY=-1FR"), start).describe(), + QStringLiteral("Monthly, on the last Friday")); + QCOMPARE(RepeatRule::fromRRule(QStringLiteral("FREQ=MONTHLY;BYMONTHDAY=18;COUNT=12"), start).describe(), + QStringLiteral("Monthly, on day 18, 12 times")); + QCOMPARE(RepeatRule::fromRRule(QStringLiteral("FREQ=YEARLY;BYMONTH=9;BYDAY=-1FR"), start).describe(), + QStringLiteral("Yearly, on the last Friday of September")); + QCOMPARE(RepeatRule::fromRRule(QStringLiteral("FREQ=YEARLY;BYWEEKNO=20"), start).describe(), + QStringLiteral("Custom rule")); +} + +QTEST_MAIN(TestRepeatRule) +#include "test_repeatrule.moc" +``` + +`describesInWords` compares English: the test process installs no translator, and QLocale day and month names come from the C locale under `QTEST_MAIN`'s default. If the machine locale leaks through (`LANG=it_IT` gives "venerdì"), add `QLocale::setDefault(QLocale::c());` at the top of that test; check before assuming. + +- [ ] **Step 2: Run to verify they fail** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_repeatrule` +Expected: FAIL (the stubs return empty rules). + +- [ ] **Step 3: Implement `src/repeatrule.cpp`** + +```cpp +/* GPLv2 header */ + +#include "repeatrule.h" + +#include <QCoreApplication> +#include <QLocale> +#include <QMap> + +#include <algorithm> + +namespace { + +// iCalendar weekday codes, indexed by Qt::DayOfWeek - 1. +const char *const kDays[] = { "MO", "TU", "WE", "TH", "FR", "SA", "SU" }; + +int dayFromCode(const QString &code) +{ + for (int i = 0; i < 7; ++i) + if (code == QLatin1String(kDays[i])) + return i + 1; + return 0; +} + +/// Splits "-1FR" into ordinal -1 and Friday. A plain "FR" gives ordinal 0. +bool splitByDay(const QString &token, int *ordinal, int *day) +{ + if (token.size() < 2) + return false; + *day = dayFromCode(token.right(2)); + const QString head = token.left(token.size() - 2); + bool ok = true; + *ordinal = head.isEmpty() ? 0 : head.toInt(&ok); + return *day != 0 && ok; +} + +// Array literals have no enclosing class, so the context must be named on each +// literal (AGENTS.md: QT_TR_NOOP here compiles and extracts nothing). +const char *const kOrdinals[] = { + QT_TRANSLATE_NOOP("RepeatRule", "first"), + QT_TRANSLATE_NOOP("RepeatRule", "second"), + QT_TRANSLATE_NOOP("RepeatRule", "third"), + QT_TRANSLATE_NOOP("RepeatRule", "fourth"), +}; + +QString tr(const char *text) { return QCoreApplication::translate("RepeatRule", text); } + +QString ordinalWord(int ordinal) +{ + if (ordinal == -1) + return tr("last"); + return (ordinal >= 1 && ordinal <= 4) ? tr(kOrdinals[ordinal - 1]) : QString(); +} + +} // namespace + +RepeatRule RepeatRule::fromRRule(const QString &value, const QDate &start) +{ + RepeatRule rule; + auto markCustom = [&]() { + RepeatRule custom; + custom.custom = true; + custom.customText = value; + return custom; + }; + + QMap<QString, QString> parts; + for (const QString &pair : value.split(QLatin1Char(';'), Qt::SkipEmptyParts)) { + const int eq = pair.indexOf(QLatin1Char('=')); + if (eq <= 0) + return markCustom(); + parts.insert(pair.left(eq).toUpper(), pair.mid(eq + 1).toUpper()); + } + + const QString freq = parts.take(QStringLiteral("FREQ")); + if (freq == QLatin1String("DAILY")) rule.freq = Freq::Daily; + else if (freq == QLatin1String("WEEKLY")) rule.freq = Freq::Weekly; + else if (freq == QLatin1String("MONTHLY")) rule.freq = Freq::Monthly; + else if (freq == QLatin1String("YEARLY")) rule.freq = Freq::Yearly; + else return markCustom(); + + if (parts.contains(QStringLiteral("INTERVAL"))) { + rule.interval = parts.take(QStringLiteral("INTERVAL")).toInt(); + if (rule.interval < 1) + return markCustom(); + } + if (parts.contains(QStringLiteral("COUNT"))) { + rule.end = End::Count; + rule.count = parts.take(QStringLiteral("COUNT")).toInt(); + if (rule.count < 1) + return markCustom(); + } + if (parts.contains(QStringLiteral("UNTIL"))) { + const QString until = parts.take(QStringLiteral("UNTIL")); + rule.end = End::Until; + rule.until = QDate::fromString(until.left(8), QStringLiteral("yyyyMMdd")); + if (!rule.until.isValid()) + return markCustom(); + } + rule.wkst = parts.take(QStringLiteral("WKST")); + + const QStringList byDay = parts.contains(QStringLiteral("BYDAY")) + ? parts.take(QStringLiteral("BYDAY")).split(QLatin1Char(',')) : QStringList(); + const QStringList byMonthDay = parts.contains(QStringLiteral("BYMONTHDAY")) + ? parts.take(QStringLiteral("BYMONTHDAY")).split(QLatin1Char(',')) : QStringList(); + const QStringList byMonth = parts.contains(QStringLiteral("BYMONTH")) + ? parts.take(QStringLiteral("BYMONTH")).split(QLatin1Char(',')) : QStringList(); + + if (!parts.isEmpty()) // BYSETPOS, BYWEEKNO, BYHOUR, ... : outside the table. + return markCustom(); + + switch (rule.freq) { + case Freq::Daily: + if (!byDay.isEmpty() || !byMonthDay.isEmpty() || !byMonth.isEmpty()) + return markCustom(); + break; + case Freq::Weekly: + if (!byMonthDay.isEmpty() || !byMonth.isEmpty()) + return markCustom(); + for (const QString &token : byDay) { + int ordinal = 0, day = 0; + if (!splitByDay(token, &ordinal, &day) || ordinal != 0) + return markCustom(); + rule.weekdays.append(day); + } + if (rule.weekdays.isEmpty()) + rule.weekdays.append(start.dayOfWeek()); + std::sort(rule.weekdays.begin(), rule.weekdays.end()); + break; + case Freq::Monthly: + case Freq::Yearly: { + const bool yearly = rule.freq == Freq::Yearly; + if (!byMonthDay.isEmpty() && !byDay.isEmpty()) + return markCustom(); + if (!byDay.isEmpty()) { + int ordinal = 0, day = 0; + if (byDay.size() != 1 || !splitByDay(byDay.first(), &ordinal, &day) + || !(ordinal == -1 || (ordinal >= 1 && ordinal <= 4))) + return markCustom(); + if (yearly && byMonth.size() != 1) + return markCustom(); + rule.by = By::Weekday; + rule.ordinal = ordinal; + rule.weekday = day; + if (yearly) + rule.month = byMonth.first().toInt(); + } else if (yearly) { + if (!byMonth.isEmpty() || !byMonthDay.isEmpty()) + return markCustom(); // "on the start date" writes neither + } else { + if (!byMonth.isEmpty() || byMonthDay.size() > 1) + return markCustom(); + rule.monthDay = byMonthDay.isEmpty() ? start.day() : byMonthDay.first().toInt(); + if (rule.monthDay < 1 || rule.monthDay > 31) + return markCustom(); + } + break; + } + case Freq::None: + break; + } + return rule; +} + +QString RepeatRule::toRRule(const QString &untilValue) const +{ + if (custom) + return customText; + if (freq == Freq::None) + return {}; + + QStringList parts; + static const char *const kFreq[] = { "", "DAILY", "WEEKLY", "MONTHLY", "YEARLY" }; + parts << QStringLiteral("FREQ=%1").arg(QLatin1String(kFreq[static_cast<int>(freq)])); + if (interval > 1) + parts << QStringLiteral("INTERVAL=%1").arg(interval); + + auto byDayToken = [](int ordinal, int day) { + return (ordinal ? QString::number(ordinal) : QString()) + QLatin1String(kDays[day - 1]); + }; + if (freq == Freq::Weekly && !weekdays.isEmpty()) { + QStringList days; + for (int d : weekdays) + days << QLatin1String(kDays[d - 1]); + parts << QStringLiteral("BYDAY=%1").arg(days.join(QLatin1Char(','))); + } else if (freq == Freq::Monthly) { + if (by == By::Weekday) + parts << QStringLiteral("BYDAY=%1").arg(byDayToken(ordinal, weekday)); + else + parts << QStringLiteral("BYMONTHDAY=%1").arg(monthDay); + } else if (freq == Freq::Yearly && by == By::Weekday) { + parts << QStringLiteral("BYMONTH=%1").arg(month) + << QStringLiteral("BYDAY=%1").arg(byDayToken(ordinal, weekday)); + } + + if (end == End::Count) + parts << QStringLiteral("COUNT=%1").arg(count); + else if (end == End::Until) + parts << QStringLiteral("UNTIL=%1").arg(untilValue); + if (!wkst.isEmpty()) + parts << QStringLiteral("WKST=%1").arg(wkst); + return parts.join(QLatin1Char(';')); +} + +QString RepeatRule::describe() const +{ + if (custom) + return tr("Custom rule"); + if (freq == Freq::None) + return tr("Does not repeat"); + + const QLocale locale; + QString text; + switch (freq) { + case Freq::Daily: + text = interval == 1 ? tr("Daily") : tr("Every %1 days").arg(interval); + break; + case Freq::Weekly: { + QStringList days; + for (int d : weekdays) + days << locale.dayName(d, QLocale::ShortFormat); + text = (interval == 1 ? tr("Weekly") : tr("Every %1 weeks").arg(interval)) + + tr(", on %1").arg(days.join(QStringLiteral(", "))); + break; + } + case Freq::Monthly: + text = interval == 1 ? tr("Monthly") : tr("Every %1 months").arg(interval); + text += by == By::Weekday + ? tr(", on the %1 %2").arg(ordinalWord(ordinal), locale.dayName(weekday)) + : tr(", on day %1").arg(monthDay); + break; + case Freq::Yearly: + text = interval == 1 ? tr("Yearly") : tr("Every %1 years").arg(interval); + if (by == By::Weekday) + text += tr(", on the %1 %2 of %3") + .arg(ordinalWord(ordinal), locale.dayName(weekday), + locale.monthName(month)); + break; + case Freq::None: + break; + } + if (end == End::Count) + text += tr(", %1 times").arg(count); + else if (end == End::Until) + text += tr(", until %1").arg(locale.toString(until, QLocale::ShortFormat)); + return text; +} + +bool RepeatRule::operator==(const RepeatRule &o) const +{ + return freq == o.freq && interval == o.interval && weekdays == o.weekdays + && by == o.by && monthDay == o.monthDay && ordinal == o.ordinal + && weekday == o.weekday && month == o.month && end == o.end + && until == o.until && count == o.count && wkst == o.wkst + && custom == o.custom && customText == o.customText; +} +``` + +A trap to check while implementing: in `roundTripsEveryRowOfTheTable`, the "monthly on day" row is `FREQ=MONTHLY;BYMONTHDAY=18`, and `toRRule` writes `BYMONTHDAY` always for `By::MonthDay`, so the round trip holds. A rule read as `FREQ=MONTHLY` with no `BYMONTHDAY` round-trips to `FREQ=MONTHLY;BYMONTHDAY=18`: the text changes, the meaning does not. That is acceptable and is why that row is not in the table test. + +- [ ] **Step 4: Run to verify they pass** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_repeatrule` +Expected: all PASS. + +- [ ] **Step 5: Commit** + +```bash +git add src/repeatrule.cpp tests/test_repeatrule.cpp +git commit -m "feat: model the calendar's repeat control as RRULE text" +``` + +--- + +### Task 4: Expanding occurrences + +**Files:** +- Modify: `src/calendarstore.cpp` (`parseEvent`'s recurrence half, `occurrences`) +- Test: `tests/test_calendarstore.cpp` + +- [ ] **Step 1: Write the failing tests** + +```cpp + void expandsAWeeklyEventAcrossDstInItsOwnZone(); + void expandsAnAllDayEventOntoOneDay(); + void removesAnExdate(); + void anOverrideReplacesItsSlotAndMovesFreely(); + void anInfiniteSeriesYieldsOnlyTheWindow(); + void honoursCountAndUntil(); + void expandsMonthlyLastFridayAndYearlyByMonth(); + void readsTheRepeatRuleExdatesAndOverrides(); +``` + +```cpp +namespace { + +QList<Occurrence> expand(const QString &body, const QDateTime &from, const QDateTime &to, + CalEvent *out = nullptr) +{ + const CalEvent event = parse(body); + if (out) + *out = event; + return CalendarStore::occurrences({ event }, from, to); +} + +QDateTime utc(int y, int m, int d, int h = 0, int min = 0) +{ + return QDateTime(QDate(y, m, d), QTime(h, min), QTimeZone::utc()); +} + +} // namespace + +void TestCalendarStore::expandsAWeeklyEventAcrossDstInItsOwnZone() +{ + // 2026-10-25 is the last Sunday of October: Rome leaves CEST (+2) for CET + // (+1). A weekly 10:00 meeting must stay at 10:00 in Rome on both sides, + // which means its UTC time MOVES. Expanding in UTC would keep 08:00Z and + // draw the second one at 09:00 local. + const QTimeZone rome("Europe/Rome"); + const QList<Occurrence> occ = expand(vevent(QStringLiteral( + "UID:w@example.org\r\nDTSTART;TZID=Europe/Rome:20261019T100000\r\n" + "DTEND;TZID=Europe/Rome:20261019T110000\r\nRRULE:FREQ=WEEKLY\r\n")), + utc(2026, 10, 18), utc(2026, 11, 1)); + QCOMPARE(occ.size(), 2); + QCOMPARE(occ[0].start.toTimeZone(rome).time(), QTime(10, 0)); + QCOMPARE(occ[1].start.toTimeZone(rome).time(), QTime(10, 0)); + QCOMPARE(occ[0].start.toUTC().time(), QTime(8, 0)); + QCOMPARE(occ[1].start.toUTC().time(), QTime(9, 0)); + QCOMPARE(occ[1].end.toTimeZone(rome).time(), QTime(11, 0)); +} + +void TestCalendarStore::expandsAnAllDayEventOntoOneDay() +{ + const QList<Occurrence> occ = expand(vevent(QStringLiteral( + "UID:ad@example.org\r\nDTSTART;VALUE=DATE:20260924\r\nDTEND;VALUE=DATE:20260925\r\n")), + QDateTime(QDate(2026, 9, 25), QTime(0, 0)), QDateTime(QDate(2026, 9, 26), QTime(0, 0))); + // The window starts on the 25th, where the event has already ENDED: an + // inclusive end would draw it on the 25th too. + QCOMPARE(occ.size(), 0); +} + +void TestCalendarStore::removesAnExdate() +{ + const QList<Occurrence> occ = expand(vevent(QStringLiteral( + "UID:x@example.org\r\nDTSTART:20260921T080000Z\r\nDTEND:20260921T090000Z\r\n" + "RRULE:FREQ=DAILY\r\nEXDATE:20260922T080000Z\r\n")), + utc(2026, 9, 21), utc(2026, 9, 24)); + QCOMPARE(occ.size(), 2); + QCOMPARE(occ[0].start, utc(2026, 9, 21, 8)); + QCOMPARE(occ[1].start, utc(2026, 9, 23, 8)); +} + +void TestCalendarStore::anOverrideReplacesItsSlotAndMovesFreely() +{ + // A five-day series (21st-25th) whose 22nd is moved to the 30th. A window + // over the 21st-23rd must NOT show the 22nd, since its slot is taken; a + // window over the 30th, where the series has no slot at all, MUST show + // the override, since an override is placed by its own start. + const QString body = vevent(QStringLiteral( + "UID:o@example.org\r\nDTSTART:20260921T080000Z\r\nDTEND:20260921T090000Z\r\n" + "RRULE:FREQ=DAILY;COUNT=5\r\nSUMMARY:Series\r\n")) + + vevent(QStringLiteral( + "UID:o@example.org\r\nRECURRENCE-ID:20260922T080000Z\r\n" + "DTSTART:20260930T150000Z\r\nDTEND:20260930T160000Z\r\nSUMMARY:Moved\r\n")); + CalEvent event; + QList<Occurrence> occ = expand(body, utc(2026, 9, 21), utc(2026, 9, 24), &event); + QCOMPARE(occ.size(), 2); // the 21st and 23rd + QCOMPARE(event.overrides.size(), 1); + QCOMPARE(event.overrides[0].summary, QStringLiteral("Moved")); + + occ = expand(body, utc(2026, 9, 30), utc(2026, 10, 1)); + QCOMPARE(occ.size(), 1); // COUNT=5 ends on the 25th; only the override is here + QVERIFY(occ[0].isOverride); + QCOMPARE(occ[0].start, utc(2026, 9, 30, 15)); + QCOMPARE(occ[0].recurrenceId, utc(2026, 9, 22, 8)); +} + +void TestCalendarStore::anInfiniteSeriesYieldsOnlyTheWindow() +{ + const QList<Occurrence> occ = expand(vevent(QStringLiteral( + "UID:inf@example.org\r\nDTSTART:20000101T080000Z\r\nRRULE:FREQ=DAILY\r\n")), + utc(2026, 9, 1), utc(2026, 9, 8)); + QCOMPARE(occ.size(), 7); + QCOMPARE(occ.first().start, utc(2026, 9, 1, 8)); +} + +void TestCalendarStore::honoursCountAndUntil() +{ + QCOMPARE(expand(vevent(QStringLiteral( + "UID:c@example.org\r\nDTSTART:20260901T080000Z\r\nRRULE:FREQ=DAILY;COUNT=3\r\n")), + utc(2026, 9, 1), utc(2026, 10, 1)).size(), 3); + QCOMPARE(expand(vevent(QStringLiteral( + "UID:u@example.org\r\nDTSTART:20260901T080000Z\r\n" + "RRULE:FREQ=DAILY;UNTIL=20260905T080000Z\r\n")), + utc(2026, 9, 1), utc(2026, 10, 1)).size(), 5); +} + +void TestCalendarStore::expandsMonthlyLastFridayAndYearlyByMonth() +{ + // Last Fridays: 2026-09-25, 2026-10-30. + QList<Occurrence> occ = expand(vevent(QStringLiteral( + "UID:lf@example.org\r\nDTSTART:20260925T080000Z\r\nRRULE:FREQ=MONTHLY;BYDAY=-1FR\r\n")), + utc(2026, 9, 1), utc(2026, 11, 1)); + QCOMPARE(occ.size(), 2); + QCOMPARE(occ[1].start.date(), QDate(2026, 10, 30)); + + // Last Friday of September: 2026-09-25, 2027-09-24. + occ = expand(vevent(QStringLiteral( + "UID:ly@example.org\r\nDTSTART:20260925T080000Z\r\n" + "RRULE:FREQ=YEARLY;BYMONTH=9;BYDAY=-1FR\r\n")), + utc(2026, 1, 1), utc(2028, 1, 1)); + QCOMPARE(occ.size(), 2); + QCOMPARE(occ[1].start.date(), QDate(2027, 9, 24)); +} + +void TestCalendarStore::readsTheRepeatRuleExdatesAndOverrides() +{ + CalEvent e; + expand(vevent(QStringLiteral( + "UID:r@example.org\r\nDTSTART:20260921T080000Z\r\n" + "RRULE:FREQ=MONTHLY;BYDAY=-1FR\r\nEXDATE:20261030T080000Z\r\n")), + utc(2026, 9, 1), utc(2026, 9, 2), &e); + QCOMPARE(e.repeat.freq, RepeatRule::Freq::Monthly); + QCOMPARE(e.repeat.ordinal, -1); + QCOMPARE(e.exdates, QList<QDateTime>{ utc(2026, 10, 30, 8) }); +} +``` + +- [ ] **Step 2: Run to verify they fail** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_calendarstore` +Expected: the eight new tests FAIL (no recurrence read, `occurrences` is a stub). + +- [ ] **Step 3: Read recurrence, exceptions and overrides in `parseEvent`** + +Replace the `// Recurrence, exceptions and overrides: Task 4.` line: + +```cpp + if (icalproperty *rrule = icalcomponent_get_first_property(master, ICAL_RRULE_PROPERTY)) { + // The value text rather than icalproperty_get_rrule(): RepeatRule is + // pure text, and libical re-serialising the struct would reorder parts. + IcalString value(icalproperty_get_value_as_string_r(rrule)); + event.repeat = RepeatRule::fromRRule(str(value.get()), event.start.date()); + } + for (icalproperty *ex = icalcomponent_get_first_property(master, ICAL_EXDATE_PROPERTY); + ex; ex = icalcomponent_get_next_property(master, ICAL_EXDATE_PROPERTY)) + event.exdates.append(toDateTime(icalproperty_get_exdate(ex), tzidOf(ex), unknownZone)); + + for (icalcomponent *c = icalcomponent_get_first_component(root.get(), ICAL_VEVENT_COMPONENT); + c; c = icalcomponent_get_next_component(root.get(), ICAL_VEVENT_COMPONENT)) { + icalproperty *rid = icalcomponent_get_first_property(c, ICAL_RECURRENCEID_PROPERTY); + if (c == master || !rid) + continue; + CalOverride ov; + ov.recurrenceId = toDateTime(icalcomponent_get_recurrenceid(c), tzidOf(rid), unknownZone); + icalproperty *sp = icalcomponent_get_first_property(c, ICAL_DTSTART_PROPERTY); + const icaltimetype s = icalcomponent_get_dtstart(c); + ov.allDay = s.is_date; + ov.start = toDateTime(s, tzidOf(sp), unknownZone); + ov.end = endOf(c, ov.start, ov.allDay, unknownZone); + ov.summary = str(icalcomponent_get_summary(c)); + ov.location = str(icalcomponent_get_location(c)); + ov.description = str(icalcomponent_get_description(c)); + ov.cancelled = icalcomponent_get_status(c) == ICAL_STATUS_CANCELLED; + event.overrides.append(ov); + } +``` + +- [ ] **Step 4: Implement `occurrences`** + +Expansion re-parses each repeating event's `rawText` so the iterator gets libical's own `icaltimetype` with its zone; the parse costs microseconds and keeps `CalEvent` free of libical. Add to the anonymous namespace: + +```cpp +/// ponytail: iterates from DTSTART rather than icalrecur_iterator_set_start, +/// which is unsupported with COUNT. Capped per series; raise the cap only if +/// a real rule is measured hitting it. +constexpr int kMaxIterations = 10000; + +bool overlaps(const QDateTime &start, const QDateTime &end, + const QDateTime &from, const QDateTime &to) +{ + // A zero-length event (no DTEND) still shows on its instant. + return start < to && (end > from || (end == start && start >= from)); +} + +/// The occurrence start times of the master in `text`, up to `to`, in the +/// event's own zone and converted after: a weekly 10:00 Rome meeting stays +/// 10:00 in Rome across DST (spec, "Time and recurrence"). +QList<QDateTime> seriesStarts(const QByteArray &text, const QDateTime &to) +{ + QList<QDateTime> starts; + IcalComponent root = parseRoot(text); + icalcomponent *master = root ? masterOf(root.get()) : nullptr; + icalproperty *rrule = master ? icalcomponent_get_first_property(master, ICAL_RRULE_PROPERTY) : nullptr; + if (!rrule) + return starts; + icalproperty *startProp = icalcomponent_get_first_property(master, ICAL_DTSTART_PROPERTY); + const QByteArray tzid = tzidOf(startProp); + const icaltimetype dtstart = icalcomponent_get_dtstart(master); + + IcalRecurIterator it(icalrecur_iterator_new(icalproperty_get_rrule(rrule), dtstart)); + if (!it) + return starts; + for (int i = 0; i < kMaxIterations; ++i) { + icaltimetype t = icalrecur_iterator_next(it.get()); + if (icaltime_is_null_time(t)) + break; + t.zone = dtstart.zone; + t.is_date = dtstart.is_date; + const QDateTime start = toDateTime(t, tzid, nullptr); + if (start >= to) + break; + starts.append(start); + } + return starts; +} + +} // namespace (reopen below if the helpers above were added mid-namespace) +``` + +```cpp +QList<Occurrence> occurrences(const QList<CalEvent> &events, + const QDateTime &from, const QDateTime &to) +{ + QList<Occurrence> result; + for (int i = 0; i < events.size(); ++i) { + const CalEvent &e = events[i]; + const qint64 length = e.start.msecsTo(e.end); + + if (e.repeat.freq == RepeatRule::Freq::None) { + if (overlaps(e.start, e.end, from, to)) + result.append({ i, e.start, e.end, e.allDay, {}, false, -1 }); + continue; + } + + for (const QDateTime &slot : seriesStarts(e.rawText, to)) { + // An EXDATE or an override takes this slot. Compared as instants: + // an EXDATE may be written in UTC while DTSTART carries a TZID. + const auto sameInstant = [&](const QDateTime &d) { return d == slot; }; + if (std::any_of(e.exdates.cbegin(), e.exdates.cend(), sameInstant)) + continue; + if (std::any_of(e.overrides.cbegin(), e.overrides.cend(), + [&](const CalOverride &o) { return o.recurrenceId == slot; })) + continue; + const QDateTime end = e.allDay ? slot.addDays(e.start.daysTo(e.end)) + : slot.addMSecs(length); + if (overlaps(slot, end, from, to)) + result.append({ i, slot, end, e.allDay, slot, false, -1 }); + } + // Placed by their OWN start: an override may move into a window its + // slot is outside of, or out of the window its slot is in. + for (int o = 0; o < e.overrides.size(); ++o) { + const CalOverride &ov = e.overrides[o]; + if (!ov.cancelled && overlaps(ov.start, ov.end, from, to)) + result.append({ i, ov.start, ov.end, ov.allDay, ov.recurrenceId, true, o }); + } + } + std::sort(result.begin(), result.end(), + [](const Occurrence &a, const Occurrence &b) { return a.start < b.start; }); + return result; +} +``` + +Two things to check against the tests rather than trust: all-day slots add whole DAYS (`addDays`), never milliseconds, because a day across a DST change is 23 or 25 hours; and `QDateTime::operator==` compares instants across zones, which is what the EXDATE and override matching needs. + +- [ ] **Step 5: Run to verify they pass** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_calendarstore` +Expected: all PASS. If the DST test fails with both at 08:00Z, the iterator lost the zone: check `t.zone = dtstart.zone` and that `toDateTime` receives the TZID. + +- [ ] **Step 6: Commit** + +```bash +git add src/calendarstore.cpp tests/test_calendarstore.cpp +git commit -m "feat: expand calendar occurrences in each event's own zone" +``` + +--- + +### Task 5: Who may edit an event + +**Files:** +- Modify: `src/calendarstore.cpp` (`isEditable`) +- Test: `tests/test_calendarstore.cpp` + +- [ ] **Step 1: Write the failing test** + +```cpp + void editableOnlyWhenTheUserOrganisesIt(); +``` + +```cpp +void TestCalendarStore::editableOnlyWhenTheUserOrganisesIt() +{ + const QStringList own = { QStringLiteral("me@example.org"), QStringLiteral("alt@example.org") }; + CalCollection writable; + writable.dir = QStringLiteral("x"); + CalCollection readOnly = writable; + readOnly.readOnly = true; + + const CalEvent mine = parse(vevent(QStringLiteral( + "UID:1@example.org\r\nDTSTART:20260922T080000Z\r\n" + "ORGANIZER;CN=Me:mailto:ME@Example.org\r\n" + "ATTENDEE;CN=Other;PARTSTAT=ACCEPTED:mailto:other@example.org\r\n"))); + const CalEvent theirs = parse(vevent(QStringLiteral( + "UID:2@example.org\r\nDTSTART:20260922T080000Z\r\n" + "ORGANIZER;CN=Other:mailto:other@example.org\r\n" + "ATTENDEE:mailto:me@example.org\r\n"))); + const CalEvent nobodys = parse(vevent(QStringLiteral( + "UID:3@example.org\r\nDTSTART:20260922T080000Z\r\n"))); + + // Case-insensitive, and "mailto:" is not part of the address. + QVERIFY(CalendarStore::isEditable(mine, writable, own)); + QVERIFY(!CalendarStore::isEditable(theirs, writable, own)); + QVERIFY(CalendarStore::isEditable(nobodys, writable, own)); + QVERIFY(!CalendarStore::isEditable(nobodys, readOnly, own)); + + QCOMPARE(mine.organizer.name, QStringLiteral("Me")); + QCOMPARE(mine.attendees.size(), 1); + QCOMPARE(mine.attendees[0].partstat, QStringLiteral("ACCEPTED")); + QCOMPARE(mine.attendees[0].address, QStringLiteral("other@example.org")); +} +``` + +- [ ] **Step 2: Run to verify it fails** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_calendarstore` +Expected: FAIL on the first `QVERIFY` (the stub returns false). + +- [ ] **Step 3: Implement** + +```cpp +bool isEditable(const CalEvent &event, const CalCollection &collection, + const QStringList &ownAddresses) +{ + if (collection.readOnly) + return false; + if (event.organizer.address.isEmpty()) + return true; + return ownAddresses.contains(event.organizer.address, Qt::CaseInsensitive); +} +``` + +- [ ] **Step 4: Run to verify it passes** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_calendarstore` +Expected: all PASS. + +- [ ] **Step 5: Commit** + +```bash +git add src/calendarstore.cpp tests/test_calendarstore.cpp +git commit -m "feat: an event is editable only when the user organises it" +``` + +--- + +### Task 6: Editing a whole event, and writing a new one + +**Files:** +- Modify: `src/calendarstore.cpp` (`applyEdit` for `Scope::All`, `newEvent`, `sameMeaning`) +- Test: `tests/test_calendarstore.cpp` + +- [ ] **Step 1: Write the failing tests** + +```cpp + void anEditKeepsWhatTheFormDoesNotOwn(); + void anEditKeepsTheEventsZone(); + void anEditRewritesTheRepeatRuleButNeverACustomOne(); + void anEditCanTurnAnEventAllDayAndBack(); + void aNewEventIsCompleteAndEmbedsItsZone(); + void sameMeaningIgnoresFormatting(); +``` + +```cpp +namespace { + +EventEdit editOf(const CalEvent &e) +{ + EventEdit edit; + edit.summary = e.summary; + edit.location = e.location; + edit.description = e.description; + edit.start = e.start; + edit.end = e.end; + edit.allDay = e.allDay; + edit.repeat = e.repeat; + edit.collectionDir = e.collectionDir; + return edit; +} + +CalEvent reparse(const QByteArray &text) +{ + bool unknown = false; + return CalendarStore::parseEvent(text, QStringLiteral("/x/e.ics"), QStringLiteral("x"), &unknown); +} + +const QString kRichEvent = QStringLiteral( + "UID:rich@example.org\r\nDTSTAMP:20260901T000000Z\r\nSEQUENCE:2\r\n" + "DTSTART;TZID=Europe/Rome:20260922T100000\r\nDTEND;TZID=Europe/Rome:20260922T110000\r\n" + "SUMMARY:Review\r\nORGANIZER;CN=Me:mailto:me@example.org\r\n" + "ATTENDEE;CN=Other;PARTSTAT=ACCEPTED:mailto:other@example.org\r\n" + "X-EXAMPLE-FLAG:keep me\r\n" + "BEGIN:VALARM\r\nACTION:DISPLAY\r\nDESCRIPTION:Reminder\r\nTRIGGER:-PT15M\r\nEND:VALARM\r\n"); + +} // namespace + +void TestCalendarStore::anEditKeepsWhatTheFormDoesNotOwn() +{ + const CalEvent before = parse(vevent(kRichEvent)); + EventEdit edit = editOf(before); + edit.summary = QStringLiteral("Review, moved"); + const QByteArray after = CalendarStore::applyEdit( + before.rawText, edit, CalendarStore::Scope::All, {}); + QVERIFY(!after.isEmpty()); + + const CalEvent e = reparse(after); + QCOMPARE(e.summary, QStringLiteral("Review, moved")); + QCOMPARE(e.uid, before.uid); + QCOMPARE(e.sequence, 3); // bumped + // Value for value, not byte for byte: libical re-serialises (plan ruling 2). + QVERIFY(e.hasAlarm); + QVERIFY(after.contains("TRIGGER:-PT15M")); + QVERIFY(after.contains("X-EXAMPLE-FLAG:keep me")); + QCOMPARE(e.attendees.size(), 1); + QCOMPARE(e.attendees[0].partstat, QStringLiteral("ACCEPTED")); + QVERIFY(after.contains("LAST-MODIFIED:")); +} + +void TestCalendarStore::anEditKeepsTheEventsZone() +{ + // The source has NO VTIMEZONE, as 120 of the user's files do: the TZID + // must still be written back, not converted to UTC or floating. + const CalEvent before = parse(vevent(kRichEvent)); + EventEdit edit = editOf(before); + edit.start = before.start.addSecs(3600); + edit.end = before.end.addSecs(3600); + const QByteArray after = CalendarStore::applyEdit(before.rawText, edit, CalendarStore::Scope::All, {}); + QVERIFY2(after.contains("DTSTART;TZID=Europe/Rome:20260922T110000"), after.constData()); + QCOMPARE(reparse(after).start, edit.start); +} + +void TestCalendarStore::anEditRewritesTheRepeatRuleButNeverACustomOne() +{ + const CalEvent weekly = parse(vevent(QStringLiteral( + "UID:r@example.org\r\nDTSTART:20260921T080000Z\r\nRRULE:FREQ=WEEKLY;WKST=MO\r\n"))); + EventEdit edit = editOf(weekly); + edit.repeat = RepeatRule::fromRRule(QStringLiteral("FREQ=MONTHLY;BYDAY=-1FR"), weekly.start.date()); + QByteArray after = CalendarStore::applyEdit(weekly.rawText, edit, CalendarStore::Scope::All, {}); + QCOMPARE(reparse(after).repeat.toRRule(), QStringLiteral("FREQ=MONTHLY;BYDAY=-1FR")); + QCOMPARE(after.count("RRULE"), 1); + + const CalEvent custom = parse(vevent(QStringLiteral( + "UID:c@example.org\r\nDTSTART:20260921T080000Z\r\n" + "RRULE:FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1\r\n"))); + edit = editOf(custom); + edit.summary = QStringLiteral("Renamed"); + after = CalendarStore::applyEdit(custom.rawText, edit, CalendarStore::Scope::All, {}); + QVERIFY(after.contains("BYSETPOS=-1")); + + edit.repeat = RepeatRule(); // Does not repeat + after = CalendarStore::applyEdit(custom.rawText, edit, CalendarStore::Scope::All, {}); + QVERIFY(!after.contains("RRULE")); +} + +void TestCalendarStore::anEditCanTurnAnEventAllDayAndBack() +{ + const CalEvent timed = parse(vevent(kRichEvent)); + EventEdit edit = editOf(timed); + edit.allDay = true; + edit.start = QDateTime(QDate(2026, 9, 22), QTime(0, 0)); + edit.end = QDateTime(QDate(2026, 9, 23), QTime(0, 0)); + const QByteArray allDay = CalendarStore::applyEdit(timed.rawText, edit, CalendarStore::Scope::All, {}); + QVERIFY(allDay.contains("DTSTART;VALUE=DATE:20260922")); + QVERIFY(allDay.contains("DTEND;VALUE=DATE:20260923")); + + const CalEvent back = reparse(allDay); + edit = editOf(back); + edit.allDay = false; + edit.start = QDateTime(QDate(2026, 9, 22), QTime(9, 0), QTimeZone("Europe/Rome")); + edit.end = edit.start.addSecs(3600); + const QByteArray timedAgain = CalendarStore::applyEdit(allDay, edit, CalendarStore::Scope::All, {}); + const CalEvent e = reparse(timedAgain); + QVERIFY(!e.allDay); + QCOMPARE(e.start, edit.start); +} + +void TestCalendarStore::aNewEventIsCompleteAndEmbedsItsZone() +{ + EventEdit edit; + edit.summary = QStringLiteral("Dentist"); + edit.start = QDateTime(QDate(2026, 9, 24), QTime(15, 0), QTimeZone("Europe/Rome")); + edit.end = edit.start.addSecs(1800); + const QByteArray text = CalendarStore::newEvent(edit, "Europe/Rome"); + QVERIFY(text.contains("BEGIN:VCALENDAR")); + QVERIFY(text.contains("PRODID:-//qtmaildir//EN")); + QVERIFY(text.contains("BEGIN:VTIMEZONE")); + QVERIFY(text.contains("TZID:Europe/Rome")); + QVERIFY(text.contains("SEQUENCE:0")); + QVERIFY(text.contains("DTSTAMP:")); + const CalEvent e = reparse(text); + QVERIFY(!e.uid.isEmpty()); + QCOMPARE(e.summary, QStringLiteral("Dentist")); + QCOMPARE(e.start, edit.start); + QCOMPARE(e.end, edit.end); + + // Two new events never share a UID. + QVERIFY(reparse(CalendarStore::newEvent(edit, "Europe/Rome")).uid != e.uid); +} + +void TestCalendarStore::sameMeaningIgnoresFormatting() +{ + const QByteArray a = ics(vevent(QStringLiteral( + "UID:s@example.org\r\nDTSTART:20260922T080000Z\r\nSUMMARY:Standup\r\n"))); + // Folded, properties reordered, DTSTAMP added: what a server may send back. + const QByteArray b = ics(vevent(QStringLiteral( + "SUMMARY:Stand\r\n up\r\nDTSTAMP:20260930T000000Z\r\n" + "DTSTART:20260922T080000Z\r\nUID:s@example.org\r\n"))); + const QByteArray moved = ics(vevent(QStringLiteral( + "UID:s@example.org\r\nDTSTART:20260922T090000Z\r\nSUMMARY:Standup\r\n"))); + QVERIFY(CalendarStore::sameMeaning(a, b)); + QVERIFY(!CalendarStore::sameMeaning(a, moved)); +} +``` + +- [ ] **Step 2: Run to verify they fail** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_calendarstore` +Expected: the six new tests FAIL. + +- [ ] **Step 3: Implement the write helpers** + +Add `#include <QUuid>` and add to the anonymous namespace in `calendarstore.cpp`: + +```cpp +/// How a component's times are written, read off its DTSTART and reused for +/// every time written back, so an edit keeps the event's zone. +struct TimeForm +{ + enum Kind { Date, Utc, Zoned, Floating } kind = Floating; + QByteArray tzid; + icaltimezone *zone = nullptr; ///< Embedded or built-in; not owned. +}; + +TimeForm formOf(icalcomponent *root, icalcomponent *c) +{ + TimeForm form; + icalproperty *prop = icalcomponent_get_first_property(c, ICAL_DTSTART_PROPERTY); + const icaltimetype t = icalcomponent_get_dtstart(c); + if (t.is_date) { + form.kind = TimeForm::Date; + } else if (icaltime_is_utc(t)) { + form.kind = TimeForm::Utc; + } else if (!tzidOf(prop).isEmpty()) { + form.kind = TimeForm::Zoned; + form.tzid = tzidOf(prop); + form.zone = icalcomponent_get_timezone(root, form.tzid.constData()); + if (!form.zone) + form.zone = icaltimezone_get_builtin_timezone(form.tzid.constData()); + } + return form; +} + +TimeForm zonedForm(const QByteArray &tzid) +{ + TimeForm form; + form.kind = TimeForm::Zoned; + form.tzid = tzid; + form.zone = icaltimezone_get_builtin_timezone(tzid.constData()); + return form; +} + +/// A QDateTime as the wall-clock icaltimetype `form` writes, zone left unset: +/// the TZID travels as a parameter, so the output never depends on whether +/// the file carried a VTIMEZONE. +icaltimetype wallTime(const QDateTime &dt, const TimeForm &form) +{ + if (form.kind == TimeForm::Date) { + icaltimetype t = icaltime_null_date(); + const QDate d = dt.date(); + t.year = d.year(); t.month = d.month(); t.day = d.day(); + return t; + } + QDateTime local; + if (form.kind == TimeForm::Utc) { + local = dt.toUTC(); + } else if (form.kind == TimeForm::Zoned && form.zone) { + icaltimetype t = icaltime_from_timet_with_zone(dt.toSecsSinceEpoch(), 0, form.zone); + t.zone = nullptr; + return t; + } else if (form.kind == TimeForm::Zoned && QTimeZone(form.tzid).isValid()) { + local = dt.toTimeZone(QTimeZone(form.tzid)); + } else { + local = dt.toLocalTime(); + } + icaltimetype t = icaltime_null_time(); + t.is_date = 0; + t.year = local.date().year(); t.month = local.date().month(); t.day = local.date().day(); + t.hour = local.time().hour(); t.minute = local.time().minute(); t.second = local.time().second(); + if (form.kind == TimeForm::Utc) + t = icaltime_convert_to_zone(t, icaltimezone_get_utc_timezone()); + return t; +} +``` + +Check `icaltime_convert_to_zone` on a zone-less time before trusting the UTC branch: if it does not mark the result UTC, set `t.zone = icaltimezone_get_utc_timezone()` directly instead. The test `aNewEventIsCompleteAndEmbedsItsZone` does not cover UTC; `anEditKeepsWhatTheFormDoesNotOwn` edits a zoned event. Add a UTC edit assertion if the branch is changed. + +```cpp +/// Replaces every `kind` property on `c` with one holding `dt` in `form`. +/// DTSTART, DTEND and RECURRENCE-ID only: EXDATE is ADDITIVE, and replacing +/// it would drop every exception but the newest (deleteOccurrence adds its +/// own). +void setTime(icalcomponent *c, icalproperty_kind kind, const QDateTime &dt, const TimeForm &form) +{ + while (icalproperty *old = icalcomponent_get_first_property(c, kind)) { + icalcomponent_remove_property(c, old); + icalproperty_free(old); + } + const icaltimetype t = wallTime(dt, form); + icalproperty *prop = kind == ICAL_DTSTART_PROPERTY ? icalproperty_new_dtstart(t) + : kind == ICAL_DTEND_PROPERTY ? icalproperty_new_dtend(t) + : icalproperty_new_recurrenceid(t); + if (form.kind == TimeForm::Zoned) + icalproperty_add_parameter(prop, icalparameter_new_tzid(form.tzid.constData())); + icalcomponent_add_property(c, prop); +} + +void removeAll(icalcomponent *c, icalproperty_kind kind) +{ + while (icalproperty *p = icalcomponent_get_first_property(c, kind)) { + icalcomponent_remove_property(c, p); + icalproperty_free(p); + } +} + +void setText(icalcomponent *c, icalproperty_kind kind, const QString &value) +{ + removeAll(c, kind); + if (value.isEmpty()) + return; + const QByteArray utf8 = value.toUtf8(); + icalproperty *p = kind == ICAL_SUMMARY_PROPERTY ? icalproperty_new_summary(utf8.constData()) + : kind == ICAL_LOCATION_PROPERTY ? icalproperty_new_location(utf8.constData()) + : icalproperty_new_description(utf8.constData()); + icalcomponent_add_property(c, p); +} + +/// Embeds the VTIMEZONE for `tzid` from libical's built-in database unless +/// the calendar already carries one, so what this application writes is +/// RFC-correct even where what it read was not. +void ensureVtimezone(icalcomponent *root, const QByteArray &tzid) +{ + if (tzid.isEmpty() || icalcomponent_get_timezone(root, tzid.constData())) + return; + icaltimezone *zone = icaltimezone_get_builtin_timezone(tzid.constData()); + if (!zone) + return; + icalcomponent *vtz = icalcomponent_new_clone(icaltimezone_get_component(zone)); + // libical's built-in components carry a "/citadel.org/..." style TZID; + // rewrite it to the plain IANA name the events reference. + removeAll(vtz, ICAL_TZID_PROPERTY); + icalcomponent_add_property(vtz, icalproperty_new_tzid(tzid.constData())); + icalcomponent_add_component(root, vtz); +} + +void stamp(icalcomponent *c, bool bumpSequence) +{ + const icaltimetype now = icaltime_current_time_with_zone(icaltimezone_get_utc_timezone()); + removeAll(c, ICAL_DTSTAMP_PROPERTY); + icalcomponent_add_property(c, icalproperty_new_dtstamp(now)); + removeAll(c, ICAL_LASTMODIFIED_PROPERTY); + icalcomponent_add_property(c, icalproperty_new_lastmodified(now)); + if (bumpSequence) + icalcomponent_set_sequence(c, icalcomponent_get_sequence(c) + 1); +} + +/// The form a written time takes after an edit: all-day is a date; a timed +/// event keeps its zone, or takes the system zone when it was all-day. +TimeForm editedForm(icalcomponent *root, icalcomponent *c, bool allDay) +{ + if (allDay) { + TimeForm date; + date.kind = TimeForm::Date; + return date; + } + TimeForm form = formOf(root, c); + if (form.kind == TimeForm::Date) { + form = zonedForm(QTimeZone::systemTimeZoneId()); + ensureVtimezone(root, form.tzid); + } + return form; +} + +/// Writes the fields the form owns onto `c`. RRULE only for a master. +void writeFields(icalcomponent *root, icalcomponent *c, const EventEdit &edit, bool master) +{ + setText(c, ICAL_SUMMARY_PROPERTY, edit.summary); + setText(c, ICAL_LOCATION_PROPERTY, edit.location); + setText(c, ICAL_DESCRIPTION_PROPERTY, edit.description); + const TimeForm form = editedForm(root, c, edit.allDay); + removeAll(c, ICAL_DURATION_PROPERTY); + setTime(c, ICAL_DTSTART_PROPERTY, edit.start, form); + setTime(c, ICAL_DTEND_PROPERTY, edit.end, form); + + if (!master || edit.repeat.custom) + return; // a custom RRULE is never rewritten (spec, repeat control) + removeAll(c, ICAL_RRULE_PROPERTY); + if (edit.repeat.freq == RepeatRule::Freq::None) + return; + // UNTIL follows DTSTART's type: a DATE for all-day, else UTC (RFC 5545). + QString until; + if (edit.repeat.end == RepeatRule::End::Until) { + until = edit.allDay + ? edit.repeat.until.toString(QStringLiteral("yyyyMMdd")) + : QDateTime(edit.repeat.until, QTime(23, 59, 59), + form.kind == TimeForm::Zoned && QTimeZone(form.tzid).isValid() + ? QTimeZone(form.tzid) : QTimeZone::systemTimeZone()) + .toUTC().toString(QStringLiteral("yyyyMMdd'T'HHmmss'Z'")); + } + const QByteArray rule = "RRULE:" + edit.repeat.toRRule(until).toUtf8(); + icalcomponent_add_property(c, icalproperty_new_from_string(rule.constData())); +} + +QByteArray serialise(icalcomponent *root) +{ + IcalString text(icalcomponent_as_ical_string_r(root)); + return text ? QByteArray(text.get()) : QByteArray(); +} +``` + +- [ ] **Step 4: Implement `applyEdit` (All only for now), `newEvent`, `sameMeaning`** + +```cpp +QByteArray applyEdit(const QByteArray &text, const EventEdit &edit, + Scope scope, const QDateTime &recurrenceId) +{ + IcalComponent root = parseRoot(text); + icalcomponent *master = root ? masterOf(root.get()) : nullptr; + if (!master) + return {}; + icalcomponent *target = master; + if (scope == Scope::ThisOccurrence) + target = overrideFor(root.get(), master, recurrenceId); // Task 7 + writeFields(root.get(), target, edit, target == master); + stamp(target, true); + return serialise(root.get()); +} + +QByteArray newEvent(const EventEdit &edit, const QByteArray &zoneId) +{ + IcalComponent root(icalcomponent_new(ICAL_VCALENDAR_COMPONENT)); + icalcomponent_add_property(root.get(), icalproperty_new_version("2.0")); + icalcomponent_add_property(root.get(), icalproperty_new_prodid("-//qtmaildir//EN")); + icalcomponent *event = icalcomponent_new(ICAL_VEVENT_COMPONENT); + icalcomponent_add_component(root.get(), event); + icalcomponent_set_uid(event, QUuid::createUuid() + .toString(QUuid::WithoutBraces).toUtf8().constData()); + // A DTSTART must exist before editedForm() reads it; a date one makes the + // form fall through to the system zone for a timed event, which is + // exactly the rule for new events, so pass the requested zone instead. + if (!edit.allDay) { + ensureVtimezone(root.get(), zoneId); + setTime(event, ICAL_DTSTART_PROPERTY, edit.start, zonedForm(zoneId)); + } else { + TimeForm date; + date.kind = TimeForm::Date; + setTime(event, ICAL_DTSTART_PROPERTY, edit.start, date); + } + writeFields(root.get(), event, edit, true); + icalcomponent_set_sequence(event, 0); + stamp(event, false); + return serialise(root.get()); +} + +bool sameMeaning(const QByteArray &a, const QByteArray &b) +{ + bool ignored = false; + const CalEvent x = parseEvent(a, {}, {}, &ignored); + const CalEvent y = parseEvent(b, {}, {}, &ignored); + if (x.uid.isEmpty() || y.uid.isEmpty()) + return x.uid.isEmpty() && y.uid.isEmpty(); + if (x.overrides.size() != y.overrides.size()) + return false; + for (int i = 0; i < x.overrides.size(); ++i) { + const CalOverride &p = x.overrides[i], &q = y.overrides[i]; + if (p.recurrenceId != q.recurrenceId || p.start != q.start + || p.end != q.end || p.summary != q.summary || p.cancelled != q.cancelled) + return false; + } + return x.summary == y.summary && x.start == y.start && x.end == y.end + && x.allDay == y.allDay && x.repeat == y.repeat && x.exdates == y.exdates; +} +``` + +`applyEdit` references `overrideFor`, which Task 7 writes. For this task add a placeholder in the anonymous namespace that returns the master, so the library links: + +```cpp +icalcomponent *overrideFor(icalcomponent *, icalcomponent *master, const QDateTime &) +{ + return master; // replaced in Task 7 +} +``` + +- [ ] **Step 5: Run to verify they pass** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_calendarstore` +Expected: all PASS. Likely snags, each a libical API detail to check in `/usr/include/libical/`: the built-in zone's own TZID (the `ensureVtimezone` rewrite); `icalproperty_new_from_string` needing the `RRULE:` prefix; and `icaltime_from_timet_with_zone` producing a date when its second argument is non-zero. + +- [ ] **Step 6: Commit** + +```bash +git add src/calendarstore.cpp tests/test_calendarstore.cpp +git commit -m "feat: edit a calendar event in place and write new ones" +``` + +--- + +### Task 7: One occurrence: override and delete + +**Files:** +- Modify: `src/calendarstore.cpp` (`overrideFor`, `deleteOccurrence`) +- Test: `tests/test_calendarstore.cpp` + +- [ ] **Step 1: Write the failing tests** + +```cpp + void editingOneOccurrenceWritesAnOverride(); + void editingTheSameOccurrenceAgainReplacesItsOverride(); + void deletingOneOccurrenceAddsAnExdateAndDropsItsOverride(); +``` + +```cpp +namespace { + +const QString kDailySeries = QStringLiteral( + "UID:d@example.org\r\nDTSTAMP:20260901T000000Z\r\n" + "DTSTART;TZID=Europe/Rome:20260921T100000\r\nDTEND;TZID=Europe/Rome:20260921T110000\r\n" + "RRULE:FREQ=DAILY;COUNT=5\r\nSUMMARY:Daily\r\n"); + +QDateTime rome(int d, int h) +{ + return QDateTime(QDate(2026, 9, d), QTime(h, 0), QTimeZone("Europe/Rome")); +} + +} // namespace + +void TestCalendarStore::editingOneOccurrenceWritesAnOverride() +{ + const CalEvent series = parse(vevent(kDailySeries)); + EventEdit edit = editOf(series); + edit.summary = QStringLiteral("Just this one"); + edit.start = rome(22, 15); + edit.end = rome(22, 16); + const QByteArray after = CalendarStore::applyEdit( + series.rawText, edit, CalendarStore::Scope::ThisOccurrence, rome(22, 10)); + + const CalEvent e = reparse(after); + QCOMPARE(e.summary, QStringLiteral("Daily")); // master untouched + QCOMPARE(e.repeat.count, 5); + QCOMPARE(e.overrides.size(), 1); + QCOMPARE(e.overrides[0].recurrenceId, rome(22, 10)); + QCOMPARE(e.overrides[0].summary, QStringLiteral("Just this one")); + QCOMPARE(after.count("RRULE"), 1); // the override carries none + + const QList<Occurrence> occ = CalendarStore::occurrences( + { e }, rome(21, 0), rome(26, 0)); + QCOMPARE(occ.size(), 5); // still five, one moved + QVERIFY(std::any_of(occ.cbegin(), occ.cend(), + [](const Occurrence &o) { return o.isOverride && o.start == rome(22, 15); })); +} + +void TestCalendarStore::editingTheSameOccurrenceAgainReplacesItsOverride() +{ + const CalEvent series = parse(vevent(kDailySeries)); + EventEdit edit = editOf(series); + edit.start = rome(22, 15); + edit.end = rome(22, 16); + QByteArray text = CalendarStore::applyEdit( + series.rawText, edit, CalendarStore::Scope::ThisOccurrence, rome(22, 10)); + edit.start = rome(22, 17); + edit.end = rome(22, 18); + text = CalendarStore::applyEdit(text, edit, CalendarStore::Scope::ThisOccurrence, rome(22, 10)); + const CalEvent e = reparse(text); + QCOMPARE(e.overrides.size(), 1); + QCOMPARE(e.overrides[0].start, rome(22, 17)); +} + +void TestCalendarStore::deletingOneOccurrenceAddsAnExdateAndDropsItsOverride() +{ + const CalEvent series = parse(vevent(kDailySeries)); + EventEdit edit = editOf(series); + edit.start = rome(23, 15); + edit.end = rome(23, 16); + const QByteArray withOverride = CalendarStore::applyEdit( + series.rawText, edit, CalendarStore::Scope::ThisOccurrence, rome(23, 10)); + + const QByteArray after = CalendarStore::deleteOccurrence(withOverride, rome(23, 10)); + const CalEvent e = reparse(after); + QCOMPARE(e.overrides.size(), 0); + QCOMPARE(e.exdates, QList<QDateTime>{ rome(23, 10) }); + QVERIFY2(after.contains("EXDATE;TZID=Europe/Rome:20260923T100000"), after.constData()); + QCOMPARE(CalendarStore::occurrences({ e }, rome(21, 0), rome(26, 0)).size(), 4); +} +``` + +Add `#include <algorithm>` to the test's includes. + +- [ ] **Step 2: Run to verify they fail** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_calendarstore` +Expected: the three new tests FAIL (the placeholder edits the master). + +- [ ] **Step 3: Implement `overrideFor` and `deleteOccurrence`** + +Replace the Task 6 placeholder: + +```cpp +/// The override component for `recurrenceId`, created when absent: a copy of +/// the master without RRULE, RDATE or EXDATE, carrying a RECURRENCE-ID in the +/// master's own time form. +icalcomponent *overrideFor(icalcomponent *root, icalcomponent *master, + const QDateTime &recurrenceId) +{ + for (icalcomponent *c = icalcomponent_get_first_component(root, ICAL_VEVENT_COMPONENT); + c; c = icalcomponent_get_next_component(root, ICAL_VEVENT_COMPONENT)) { + icalproperty *rid = icalcomponent_get_first_property(c, ICAL_RECURRENCEID_PROPERTY); + if (c != master && rid + && toDateTime(icalcomponent_get_recurrenceid(c), tzidOf(rid), nullptr) == recurrenceId) + return c; + } + icalcomponent *copy = icalcomponent_new_clone(master); + removeAll(copy, ICAL_RRULE_PROPERTY); + removeAll(copy, ICAL_RDATE_PROPERTY); + removeAll(copy, ICAL_EXDATE_PROPERTY); + setTime(copy, ICAL_RECURRENCEID_PROPERTY, recurrenceId, formOf(root, master)); + icalcomponent_add_component(root, copy); + return copy; +} +``` + +In `deleteOccurrence`, remove the matching override component and add the EXDATE: + +```cpp +QByteArray deleteOccurrence(const QByteArray &text, const QDateTime &recurrenceId) +{ + IcalComponent root = parseRoot(text); + icalcomponent *master = root ? masterOf(root.get()) : nullptr; + if (!master) + return {}; + // Collect first: removing a component mid-walk invalidates the iterator. + QList<icalcomponent *> doomed; + for (icalcomponent *c = icalcomponent_get_first_component(root.get(), ICAL_VEVENT_COMPONENT); + c; c = icalcomponent_get_next_component(root.get(), ICAL_VEVENT_COMPONENT)) { + icalproperty *rid = icalcomponent_get_first_property(c, ICAL_RECURRENCEID_PROPERTY); + if (c != master && rid + && toDateTime(icalcomponent_get_recurrenceid(c), tzidOf(rid), nullptr) == recurrenceId) + doomed.append(c); + } + for (icalcomponent *c : doomed) { + icalcomponent_remove_component(root.get(), c); + icalcomponent_free(c); + } + // setTime replaces every property of its kind, which for EXDATE would + // drop the existing ones: add this one alongside instead. + const TimeForm form = formOf(root.get(), master); + icalproperty *ex = icalproperty_new_exdate(wallTime(recurrenceId, form)); + if (form.kind == TimeForm::Zoned) + icalproperty_add_parameter(ex, icalparameter_new_tzid(form.tzid.constData())); + icalcomponent_add_property(master, ex); + stamp(master, true); + return serialise(root.get()); +} +``` + +- [ ] **Step 4: Run to verify they pass** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_calendarstore` +Expected: all PASS. + +- [ ] **Step 5: Commit** + +```bash +git add src/calendarstore.cpp tests/test_calendarstore.cpp +git commit -m "feat: edit or delete one occurrence of a repeating event" +``` + +--- + +### Task 8: `CalendarWriter` + +**Files:** +- Create: `src/calendarwriter.h`, `src/calendarwriter.cpp` +- Modify: `src/CMakeLists.txt` (add `calendarwriter.cpp`), `tests/CMakeLists.txt` (`add_qtmaildir_test(calendarwriter)`) +- Test: `tests/test_calendarwriter.cpp` + +- [ ] **Step 1: Write the failing tests** + +```cpp +/* GPLv2 header */ + +#include <QtTest> +#include <QDir> +#include <QFile> +#include <QTemporaryDir> + +#include "calendarwriter.h" + +namespace { + +QByteArray read(const QString &path) +{ + QFile f(path); + return f.open(QIODevice::ReadOnly) ? f.readAll() : QByteArray(); +} + +} // namespace + +class TestCalendarWriter : public QObject +{ + Q_OBJECT + +private slots: + void createsAFileThatDidNotExist(); + void refusesToCreateOverAnExistingFile(); + void replacesWhenTheFileIsWhatWasExpected(); + void refusesWhenTheFileChangedUnderneath(); + void deletes(); + void leavesNoTemporaryFileBehind(); +}; + +void TestCalendarWriter::createsAFileThatDidNotExist() +{ + QTemporaryDir dir; + const QString path = dir.filePath(QStringLiteral("a.ics")); + QString error; + QCOMPARE(CalendarWriter::replace(path, std::nullopt, QByteArray("new"), &error), + CalendarWriter::Result::Ok); + QCOMPARE(read(path), QByteArray("new")); +} + +void TestCalendarWriter::refusesToCreateOverAnExistingFile() +{ + QTemporaryDir dir; + const QString path = dir.filePath(QStringLiteral("a.ics")); + QFile f(path); + QVERIFY(f.open(QIODevice::WriteOnly)); + f.write("synced in meanwhile"); + f.close(); + QString error; + QCOMPARE(CalendarWriter::replace(path, std::nullopt, QByteArray("new"), &error), + CalendarWriter::Result::Stale); + QCOMPARE(read(path), QByteArray("synced in meanwhile")); +} + +void TestCalendarWriter::replacesWhenTheFileIsWhatWasExpected() +{ + QTemporaryDir dir; + const QString path = dir.filePath(QStringLiteral("a.ics")); + QString error; + CalendarWriter::replace(path, std::nullopt, QByteArray("one"), &error); + QCOMPARE(CalendarWriter::replace(path, QByteArray("one"), QByteArray("two"), &error), + CalendarWriter::Result::Ok); + QCOMPARE(read(path), QByteArray("two")); +} + +void TestCalendarWriter::refusesWhenTheFileChangedUnderneath() +{ + QTemporaryDir dir; + const QString path = dir.filePath(QStringLiteral("a.ics")); + QString error; + CalendarWriter::replace(path, std::nullopt, QByteArray("synced"), &error); + // The caller loaded "one"; a sync wrote "synced" since. Nothing is clobbered. + QCOMPARE(CalendarWriter::replace(path, QByteArray("one"), QByteArray("two"), &error), + CalendarWriter::Result::Stale); + QCOMPARE(read(path), QByteArray("synced")); + // Also stale: expecting a file that a sync has removed. + QFile::remove(path); + QCOMPARE(CalendarWriter::replace(path, QByteArray("synced"), QByteArray("two"), &error), + CalendarWriter::Result::Stale); + QVERIFY(!QFile::exists(path)); +} + +void TestCalendarWriter::deletes() +{ + QTemporaryDir dir; + const QString path = dir.filePath(QStringLiteral("a.ics")); + QString error; + CalendarWriter::replace(path, std::nullopt, QByteArray("one"), &error); + QCOMPARE(CalendarWriter::replace(path, QByteArray("one"), std::nullopt, &error), + CalendarWriter::Result::Ok); + QVERIFY(!QFile::exists(path)); +} + +void TestCalendarWriter::leavesNoTemporaryFileBehind() +{ + QTemporaryDir dir; + const QString path = dir.filePath(QStringLiteral("a.ics")); + QString error; + CalendarWriter::replace(path, std::nullopt, QByteArray("one"), &error); + CalendarWriter::replace(path, QByteArray("one"), QByteArray("two"), &error); + QCOMPARE(QDir(dir.path()).entryList(QDir::Files | QDir::Hidden), + QStringList{ QStringLiteral("a.ics") }); +} + +QTEST_MAIN(TestCalendarWriter) +#include "test_calendarwriter.moc" +``` + +- [ ] **Step 2: Write the header** + +`src/calendarwriter.h`: + +```cpp +/* GPLv2 header */ + +#pragma once + +#include <QByteArray> +#include <QString> + +#include <optional> + +/// Every write to the calendar vdir goes through here. +/// +/// One function covers create, edit, delete and every undo of those, because +/// each is the same act: the file must currently be X, and must become Y, +/// where either may be "absent". vdirsyncer writes the same files from cron, +/// so "must currently be X" is the stale check that stops a save from +/// silently discarding what a sync just pulled. +namespace CalendarWriter { + +enum class Result { Ok, Stale, IoError }; + +/// `expected` nullopt: the file must not exist. `newText` nullopt: delete it. +/// A write goes to a hidden temporary in the same directory and is renamed +/// into place, so vdirsyncer, which lists only *.ics, never reads half a file. +Result replace(const QString &path, const std::optional<QByteArray> &expected, + const std::optional<QByteArray> &newText, QString *error); + +} // namespace CalendarWriter +``` + +- [ ] **Step 3: Run to verify they fail** + +Run: `cmake --build build 2>&1 | tail -3` +Expected: link failure, undefined `CalendarWriter::replace`. + +- [ ] **Step 4: Implement** + +`src/calendarwriter.cpp`: + +```cpp +/* GPLv2 header */ + +#include "calendarwriter.h" + +#include <QFile> +#include <QFileInfo> +#include <QSaveFile> + +namespace CalendarWriter { + +Result replace(const QString &path, const std::optional<QByteArray> &expected, + const std::optional<QByteArray> &newText, QString *error) +{ + QFile current(path); + const bool exists = current.exists(); + if (expected.has_value() != exists) + return Result::Stale; + if (exists) { + if (!current.open(QIODevice::ReadOnly)) { + *error = current.errorString(); + return Result::IoError; + } + if (current.readAll() != *expected) + return Result::Stale; + current.close(); + } + + if (!newText) { + if (!QFile::remove(path)) { + *error = QFile(path).errorString(); + return Result::IoError; + } + return Result::Ok; + } + + // QSaveFile is the platform's atomic write: a temporary in the same + // directory, renamed on commit(). Its temporary is named "<name>.XXXXXX", + // which does not end in .ics, so vdirsyncer never lists it. + QSaveFile file(path); + if (!file.open(QIODevice::WriteOnly) || file.write(*newText) != newText->size() + || !file.commit()) { + *error = file.errorString(); + return Result::IoError; + } + return Result::Ok; +} + +} // namespace CalendarWriter +``` + +`QSaveFile` replaces the hand-rolled `.<name>.tmp` + `rename()` the spec describes: same guarantee, stdlib-of-Qt, fewer lines (ponytail ladder, rung 2). Record that in Task 16's spec amendment. + +- [ ] **Step 5: Run to verify they pass** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_calendarwriter` +Expected: all PASS. + +- [ ] **Step 6: Commit** + +```bash +git add src/calendarwriter.h src/calendarwriter.cpp src/CMakeLists.txt tests/CMakeLists.txt \ + tests/test_calendarwriter.cpp +git commit -m "feat: write calendar files atomically, refusing stale ones" +``` + +--- + +### Task 9: Config keys + +**Files:** +- Modify: `src/config.h` (accessors beside `contactsDir()`, members beside `m_contactsDir`) +- Modify: `src/config.cpp` (read beside `contacts_dir`) +- Test: `tests/test_config.cpp` + +- [ ] **Step 1: Write the failing tests** + +Add beside the `contactsDir*` slots, following their `writeIni` helper: + +```cpp + void calendarKeysAreOffWithoutThem(); + void calendarKeysAreRead(); + void calendarSyncCommandSurvivesACommaAndDefaults(); +``` + +```cpp +void TestConfig::calendarKeysAreOffWithoutThem() +{ + // Plan ruling 1: absent is OFF, silently, as contacts_dir is. + QTemporaryDir dir; + Config config; + config.load(writeIni(dir, QStringLiteral("[general]\n"))); + QVERIFY(config.calendarsDir().isEmpty()); + QVERIFY(config.problems().isEmpty()); +} + +void TestConfig::calendarKeysAreRead() +{ + QTemporaryDir dir; + const QString cal = dir.filePath(QStringLiteral("calendars")); + QDir().mkpath(cal); + Config config; + config.load(writeIni(dir, QStringLiteral("[general]\n" + "calendars_dir = %1\n" + "default_calendar = 52\n" + "calendar_sync_delay_ms = 500\n").arg(cal))); + QCOMPARE(config.calendarsDir(), cal); + QCOMPARE(config.defaultCalendar(), QStringLiteral("52")); + QCOMPARE(config.calendarSyncDelayMs(), 500); + QVERIFY(config.problems().isEmpty()); +} + +void TestConfig::calendarSyncCommandSurvivesACommaAndDefaults() +{ + QTemporaryDir dir; + Config config; + config.load(writeIni(dir, QStringLiteral("[general]\n"))); + QCOMPARE(config.calendarSyncCommand(), + QStringLiteral("flock -w 60 /tmp/vdirsyncer.lock vdirsyncer sync calendars")); + QCOMPARE(config.calendarSyncDelayMs(), 2000); + + // QSettings splits an unquoted value on commas into a QStringList, and + // toString() on a list is EMPTY: a command holding a comma would silently + // turn syncing off. The reader joins the list back. + Config commas; + commas.load(writeIni(dir, QStringLiteral("[general]\n" + "calendar_sync_command = mysync --only a,b\n"))); + QCOMPARE(commas.calendarSyncCommand(), QStringLiteral("mysync --only a,b")); + + // Written but empty disables, which is different from absent. + Config off; + off.load(writeIni(dir, QStringLiteral("[general]\ncalendar_sync_command = \n"))); + QVERIFY(off.calendarSyncCommand().isEmpty()); +} +``` + +Check that `writeIni` overwrites the same file on a second call in one test; if it creates `qtmaildir.conf` once and refuses, use a fresh `QTemporaryDir` per `Config`. + +- [ ] **Step 2: Run to verify they fail** + +Run: `cmake --build build 2>&1 | tail -3` +Expected: compile error, `calendarsDir` is not a member of `Config`. + +- [ ] **Step 3: Implement** + +`src/config.h`, beside `contactsDir()`: + +```cpp + /// The vdirsyncer calendar root (item 206). Empty: the calendar is off. + QString calendarsDir() const { return m_calendarsDir; } + /// Directory name of the collection new events go to; empty means the + /// first collection by display name. + QString defaultCalendar() const { return m_defaultCalendar; } + /// Run after calendar writes. Empty: no sync. + QString calendarSyncCommand() const { return m_calendarSyncCommand; } + int calendarSyncDelayMs() const { return m_calendarSyncDelayMs; } +``` + +Members beside `m_contactsDir`: + +```cpp + QString m_calendarsDir; + QString m_defaultCalendar; + QString m_calendarSyncCommand = + QStringLiteral("flock -w 60 /tmp/vdirsyncer.lock vdirsyncer sync calendars"); + int m_calendarSyncDelayMs = 2000; +``` + +`src/config.cpp`, directly after the `contacts_dir` block: + +```cpp + // Item 206. The same shape as contacts_dir: absent or blank is the feature + // off, silently; set and missing is reported and kept, since a vdirsyncer + // target may not exist before its first run. + const QString calendarsDir = + settings.value(QStringLiteral("calendars_dir")).toString().trimmed(); + if (!calendarsDir.isEmpty()) { + m_calendarsDir = expandTilde(calendarsDir); + if (!QFileInfo::exists(m_calendarsDir)) { + addProblem(tr("Calendars directory '%1' does not exist; the " + "calendar will be empty.").arg(m_calendarsDir)); + } + } + m_defaultCalendar = + settings.value(QStringLiteral("default_calendar")).toString().trimmed(); + + // An unquoted value holding a comma reaches here as a QStringList, whose + // toString() is empty; join it back rather than silently losing the + // command. Absent keeps the default; present and blank disables. + const QVariant calSync = settings.value(QStringLiteral("calendar_sync_command")); + if (calSync.isValid()) { + m_calendarSyncCommand = calSync.typeId() == QMetaType::QStringList + ? calSync.toStringList().join(QLatin1Char(',')) + : calSync.toString(); + m_calendarSyncCommand = m_calendarSyncCommand.trimmed(); + } + const QVariant calDelay = settings.value(QStringLiteral("calendar_sync_delay_ms")); + if (calDelay.isValid()) { + bool ok = false; + const int value = calDelay.toString().toInt(&ok); + if (ok && value >= 0) + m_calendarSyncDelayMs = value; + else + addProblem(tr("Calendar sync delay '%1' is not a number; using the default.") + .arg(calDelay.toString())); + } +``` + +`QStringList::join` on a list QSettings split at `a,b` rejoins with no spaces, which matches the original only because QSettings split without trimming. Verify with the test before trusting it; if spaces are lost, the documented workaround is quoting the value in the INI, and the test should assert that instead. + +- [ ] **Step 4: Run to verify they pass** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_config` +Expected: all PASS. + +- [ ] **Step 5: Commit** + +```bash +git add src/config.h src/config.cpp tests/test_config.cpp +git commit -m "feat: read the calendar's config keys" +``` + +--- + +### Task 10: `CalendarSync` + +**Files:** +- Create: `src/calendarsync.h`, `src/calendarsync.cpp` +- Modify: `src/CMakeLists.txt`, `tests/CMakeLists.txt` (`add_qtmaildir_test(calendarsync)`) +- Test: `tests/test_calendarsync.cpp` + +- [ ] **Step 1: Write the failing tests** + +The command is a real shell-free process: `sh -c` would defeat `splitCommand`, so the test uses a tiny script written into a temp dir. + +```cpp +/* GPLv2 header */ + +#include <QtTest> +#include <QFile> +#include <QSignalSpy> +#include <QTemporaryDir> + +#include "calendarsync.h" + +namespace { + +/// A script that appends a line to `log` each run and exits with `code`. +QString script(const QTemporaryDir &dir, int code) +{ + const QString path = dir.filePath(QStringLiteral("sync.sh")); + QFile f(path); + f.open(QIODevice::WriteOnly); + f.write(QStringLiteral("#!/bin/sh\necho run >> %1\necho output\nexit %2\n") + .arg(dir.filePath(QStringLiteral("log"))).arg(code).toUtf8()); + f.close(); + f.setPermissions(f.permissions() | QFileDevice::ExeOwner); + return path; +} + +int runs(const QTemporaryDir &dir) +{ + QFile f(dir.filePath(QStringLiteral("log"))); + return f.open(QIODevice::ReadOnly) ? f.readAll().count('\n') : 0; +} + +} // namespace + +class TestCalendarSync : public QObject +{ + Q_OBJECT + +private slots: + void aBurstOfWritesRunsOnce(); + void reportsFailureWithTheOutput(); + void anEmptyCommandNeverRuns(); +}; + +void TestCalendarSync::aBurstOfWritesRunsOnce() +{ + QTemporaryDir dir; + CalendarSync sync(script(dir, 0), 50); + QSignalSpy finished(&sync, &CalendarSync::finished); + sync.schedule(); + sync.schedule(); + sync.schedule(); + QVERIFY(finished.wait(5000)); + QCOMPARE(finished.first().at(0).toBool(), true); + QTest::qWait(200); // nothing else is queued, so nothing else may run + QCOMPARE(runs(dir), 1); +} + +void TestCalendarSync::reportsFailureWithTheOutput() +{ + QTemporaryDir dir; + CalendarSync sync(script(dir, 3), 0); + QSignalSpy finished(&sync, &CalendarSync::finished); + sync.schedule(); + QVERIFY(finished.wait(5000)); + QCOMPARE(finished.first().at(0).toBool(), false); + QVERIFY(finished.first().at(1).toString().contains(QStringLiteral("output"))); +} + +void TestCalendarSync::anEmptyCommandNeverRuns() +{ + CalendarSync sync(QString(), 0); + QSignalSpy started(&sync, &CalendarSync::started); + sync.schedule(); + QTest::qWait(100); + QCOMPARE(started.count(), 0); +} + +QTEST_MAIN(TestCalendarSync) +#include "test_calendarsync.moc" +``` + +`aBurstOfWritesRunsOnce` waits a fixed 200 ms to assert a NEGATIVE, which AGENTS.md warns passes when the thing never arrives. Here that is the assertion's point (no second run) and the positive half is waited on properly first, so it stands; do not copy the pattern for a positive check. + +- [ ] **Step 2: Write the header** + +```cpp +/* GPLv2 header */ + +#pragma once + +#include <QObject> +#include <QProcess> +#include <QTimer> + +/// Runs calendar_sync_command a short delay after the last write. +/// +/// The calendar's counterpart to MailSync, and deliberately smaller: no lock +/// monitoring and no status file, because the command itself takes the +/// flock that cron shares. A write arriving while a run is in progress is not +/// dropped: it queues exactly one more run for when this one finishes, since +/// the running sync may have listed the vdir before the write landed. +class CalendarSync : public QObject +{ + Q_OBJECT + +public: + CalendarSync(const QString &command, int delayMs, QObject *parent = nullptr); + + void schedule(); + bool isRunning() const; + +signals: + void started(); + void finished(bool ok, const QString &output); + +private: + void run(); + + QString m_command; + QTimer m_timer; + QProcess m_process; + QByteArray m_output; + bool m_again = false; +}; +``` + +- [ ] **Step 3: Run to verify they fail** + +Run: `cmake --build build 2>&1 | tail -3` +Expected: link failure for `CalendarSync`. + +- [ ] **Step 4: Implement** + +```cpp +/* GPLv2 header */ + +#include "calendarsync.h" + +CalendarSync::CalendarSync(const QString &command, int delayMs, QObject *parent) + : QObject(parent), m_command(command) +{ + m_timer.setSingleShot(true); + m_timer.setInterval(delayMs); + connect(&m_timer, &QTimer::timeout, this, &CalendarSync::run); + m_process.setProcessChannelMode(QProcess::MergedChannels); + connect(&m_process, &QProcess::readyRead, this, + [this]() { m_output += m_process.readAll(); }); + connect(&m_process, &QProcess::finished, this, + [this](int code, QProcess::ExitStatus status) { + emit finished(status == QProcess::NormalExit && code == 0, + QString::fromLocal8Bit(m_output)); + if (m_again) { + m_again = false; + m_timer.start(); + } + }); + connect(&m_process, &QProcess::errorOccurred, this, + [this](QProcess::ProcessError error) { + if (error == QProcess::FailedToStart) + emit finished(false, m_process.errorString()); + }); +} + +void CalendarSync::schedule() +{ + if (m_command.isEmpty()) + return; + if (isRunning()) + m_again = true; + else + m_timer.start(); // restarting is the debounce +} + +bool CalendarSync::isRunning() const +{ + return m_process.state() != QProcess::NotRunning; +} + +void CalendarSync::run() +{ + // splitCommand, not a shell: quoting works and nothing is interpreted. + QStringList parts = QProcess::splitCommand(m_command); + if (parts.isEmpty()) + return; + const QString program = parts.takeFirst(); + m_output.clear(); + emit started(); + m_process.start(program, parts); +} +``` + +- [ ] **Step 5: Run to verify they pass** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_calendarsync` +Expected: all PASS. + +- [ ] **Step 6: Commit** + +```bash +git add src/calendarsync.h src/calendarsync.cpp src/CMakeLists.txt tests/CMakeLists.txt \ + tests/test_calendarsync.cpp +git commit -m "feat: debounce the calendar sync command after writes" +``` + +--- + +### Task 11: `MonthLayout` + +**Files:** +- Create: `src/monthlayout.h`, `src/monthlayout.cpp` +- Modify: `src/CMakeLists.txt`, `tests/CMakeLists.txt` (`add_qtmaildir_test(monthlayout)`) +- Test: `tests/test_monthlayout.cpp` + +- [ ] **Step 1: Write the failing tests** + +```cpp +/* GPLv2 header */ + +#include <QtTest> + +#include "monthlayout.h" + +class TestMonthLayout : public QObject +{ + Q_OBJECT + +private slots: + void theGridStartsOnTheLocalesFirstDay(); + void cellsTileTheAreaWithNoGapOrOverlap(); + void chipsThatDoNotFitBecomeMore(); + void aPointFindsItsCell(); +}; + +void TestMonthLayout::theGridStartsOnTheLocalesFirstDay() +{ + // 2026-09-01 is a Tuesday. + QCOMPARE(MonthLayout::gridStart(2026, 9, Qt::Monday), QDate(2026, 8, 31)); + QCOMPARE(MonthLayout::gridStart(2026, 9, Qt::Sunday), QDate(2026, 8, 30)); + // A month starting ON the first weekday starts on its own first day. + QCOMPARE(MonthLayout::gridStart(2026, 6, Qt::Monday), QDate(2026, 6, 1)); + const MonthLayout layout(QRect(0, 0, 700, 600), 2026, 9, Qt::Monday, 20, 16); + QCOMPARE(layout.dateAt(0), QDate(2026, 8, 31)); + QCOMPARE(layout.dateAt(41), QDate(2026, 10, 11)); +} + +void TestMonthLayout::cellsTileTheAreaWithNoGapOrOverlap() +{ + // 703 does not divide by 7: the remainder must go somewhere, not vanish + // as a gap down the right edge. + const QRect area(0, 0, 703, 605); + const MonthLayout layout(area, 2026, 9, Qt::Monday, 20, 16); + QCOMPARE(layout.cellRect(0).left(), area.left()); + QCOMPARE(layout.cellRect(6).right(), area.right()); + QCOMPARE(layout.cellRect(41).bottom(), area.bottom()); + for (int i = 0; i < 6; ++i) + QCOMPARE(layout.cellRect(i).right() + 1, layout.cellRect(i + 1).left()); + QCOMPARE(layout.cellRect(0).bottom() + 1, layout.cellRect(7).top()); +} + +void TestMonthLayout::chipsThatDoNotFitBecomeMore() +{ + // 600 / 6 rows = 100 px a cell; 20 px of day number; 16 px chips: 5 fit. + const MonthLayout layout(QRect(0, 0, 700, 600), 2026, 9, Qt::Monday, 20, 16); + QCOMPARE(layout.capacity(), 5); + QCOMPARE(layout.visibleChips(3), 3); + QCOMPARE(layout.visibleChips(5), 5); + // Six do not fit: four chips and a "+2 more" line in the fifth slot. + QCOMPARE(layout.visibleChips(6), 4); + QCOMPARE(layout.chipRect(0, 0).top(), layout.cellRect(0).top() + 20); + QVERIFY(layout.cellRect(0).contains(layout.chipRect(0, 4))); +} + +void TestMonthLayout::aPointFindsItsCell() +{ + const MonthLayout layout(QRect(0, 0, 700, 600), 2026, 9, Qt::Monday, 20, 16); + QCOMPARE(layout.cellAt(layout.cellRect(17).center()), 17); + QCOMPARE(layout.cellAt(QPoint(-5, 10)), -1); +} + +QTEST_MAIN(TestMonthLayout) +#include "test_monthlayout.moc" +``` + +- [ ] **Step 2: Write the header** + +```cpp +/* GPLv2 header */ + +#pragma once + +#include <QDate> +#include <QPoint> +#include <QRect> + +/// Where everything in the month grid goes, with no painter and no widget. +/// +/// The CardLayout precedent: a geometric claim is tested as a function call, +/// because AGENTS.md records how rendering probes lie. Six rows of seven +/// always, so the grid does not jump in height between months. +class MonthLayout +{ +public: + static constexpr int kCells = 42; + + MonthLayout(const QRect &area, int year, int month, Qt::DayOfWeek firstDay, + int dayNumberHeight, int chipHeight); + + static QDate gridStart(int year, int month, Qt::DayOfWeek firstDay); + + QDate dateAt(int cell) const; + int cellOf(const QDate &date) const; ///< -1 when not on the grid. + QRect cellRect(int cell) const; + int cellAt(const QPoint &point) const; ///< -1 outside the grid. + + /// How many chip slots fit under a cell's day number. + int capacity() const; + /// How many of `total` chips are drawn; when fewer than `total`, the + /// next slot holds "+N more". + int visibleChips(int total) const; + QRect chipRect(int cell, int slot) const; + +private: + QRect m_area; + QDate m_start; + int m_dayNumberHeight; + int m_chipHeight; +}; +``` + +- [ ] **Step 3: Run to verify they fail** + +Run: `cmake --build build 2>&1 | tail -3` +Expected: link failure. + +- [ ] **Step 4: Implement** + +```cpp +/* GPLv2 header */ + +#include "monthlayout.h" + +MonthLayout::MonthLayout(const QRect &area, int year, int month, Qt::DayOfWeek firstDay, + int dayNumberHeight, int chipHeight) + : m_area(area), m_start(gridStart(year, month, firstDay)), + m_dayNumberHeight(dayNumberHeight), m_chipHeight(chipHeight) +{ +} + +QDate MonthLayout::gridStart(int year, int month, Qt::DayOfWeek firstDay) +{ + const QDate first(year, month, 1); + const int back = (first.dayOfWeek() - firstDay + 7) % 7; + return first.addDays(-back); +} + +QDate MonthLayout::dateAt(int cell) const { return m_start.addDays(cell); } + +int MonthLayout::cellOf(const QDate &date) const +{ + const qint64 cell = m_start.daysTo(date); + return cell >= 0 && cell < kCells ? int(cell) : -1; +} + +QRect MonthLayout::cellRect(int cell) const +{ + // Edges computed from the area by proportion, so the rounding remainder + // is spread across cells and the last edge lands exactly on the area's. + const int col = cell % 7, row = cell / 7; + const int left = m_area.left() + m_area.width() * col / 7; + const int right = m_area.left() + m_area.width() * (col + 1) / 7; // exclusive + const int top = m_area.top() + m_area.height() * row / 6; + const int bottom = m_area.top() + m_area.height() * (row + 1) / 6; + return QRect(QPoint(left, top), QPoint(right - 1, bottom - 1)); +} + +int MonthLayout::cellAt(const QPoint &point) const +{ + if (!m_area.contains(point)) + return -1; + const int col = (point.x() - m_area.left()) * 7 / m_area.width(); + const int row = (point.y() - m_area.top()) * 6 / m_area.height(); + return row * 7 + col; +} + +int MonthLayout::capacity() const +{ + const int height = m_area.height() / 6 - m_dayNumberHeight; + return m_chipHeight > 0 ? qMax(0, height / m_chipHeight) : 0; +} + +int MonthLayout::visibleChips(int total) const +{ + const int cap = capacity(); + return total <= cap ? total : qMax(0, cap - 1); +} + +QRect MonthLayout::chipRect(int cell, int slot) const +{ + const QRect c = cellRect(cell); + return QRect(c.left() + 2, c.top() + m_dayNumberHeight + slot * m_chipHeight, + c.width() - 4, m_chipHeight - 1); +} +``` + +`QRect::right()` is inclusive (AGENTS.md, CardLayout): the exclusive edge is carried as a local and converted once in `cellRect`, which is what `cellsTileTheAreaWithNoGapOrOverlap` guards. + +- [ ] **Step 5: Run to verify they pass** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_monthlayout` +Expected: all PASS. + +- [ ] **Step 6: Commit** + +```bash +git add src/monthlayout.h src/monthlayout.cpp src/CMakeLists.txt tests/CMakeLists.txt \ + tests/test_monthlayout.cpp +git commit -m "feat: lay out the calendar's month grid without a painter" +``` + +--- + +### Task 12: `MonthView` and `AgendaView` + +These are painting and list widgets: their correctness is the user's hand test (AGENTS.md: a green suite is not evidence a UI design is right). No tests here; the geometry they rely on is Task 11's. + +**Files:** +- Create: `src/monthview.h`, `src/monthview.cpp`, `src/agendaview.h`, `src/agendaview.cpp` +- Modify: `src/CMakeLists.txt` + +- [ ] **Step 1: Write `src/monthview.h`** + +```cpp +/* GPLv2 header */ + +#pragma once + +#include "caltypes.h" +#include "monthlayout.h" + +#include <QWidget> + +/// The month grid. Paints a MonthLayout; knows nothing of libical, files or +/// CalEvent, only the CalendarItems it is handed. +class MonthView : public QWidget +{ + Q_OBJECT + +public: + explicit MonthView(QWidget *parent = nullptr); + + void setMonth(int year, int month); + void setItems(const QList<CalendarItem> &items); + /// Index into the items, or -1. Drawn with an outline. + void setSelected(int item); + + /// The first and one-past-last day on the grid, for the caller's query. + QDate firstDay() const; + QDate lastDay() const; + +signals: + void itemClicked(int item); + void dayDoubleClicked(const QDate &day); + void moreClicked(const QDate &day); + +protected: + void paintEvent(QPaintEvent *event) override; + void mousePressEvent(QMouseEvent *event) override; + void mouseDoubleClickEvent(QMouseEvent *event) override; + +private: + MonthLayout layout() const; + /// Items on each cell, in start order; a multi-day item is on every cell + /// it covers (spec, Month view). + QList<QList<int>> itemsPerCell(const MonthLayout &layout) const; + + int m_year; + int m_month; + QList<CalendarItem> m_items; + int m_selected = -1; +}; +``` + +- [ ] **Step 2: Write `src/monthview.cpp`** + +```cpp +/* GPLv2 header */ + +#include "monthview.h" +#include "monthlayout.h" + +#include <QLocale> +#include <QMouseEvent> +#include <QPainter> + +MonthView::MonthView(QWidget *parent) + : QWidget(parent), + m_year(QDate::currentDate().year()), m_month(QDate::currentDate().month()) +{ + setMinimumSize(420, 320); +} + +void MonthView::setMonth(int year, int month) +{ + m_year = year; + m_month = month; + update(); +} + +void MonthView::setItems(const QList<CalendarItem> &items) +{ + m_items = items; + m_selected = -1; + update(); +} + +void MonthView::setSelected(int item) +{ + m_selected = item; + update(); +} + +MonthLayout MonthView::layout() const +{ + const int line = fontMetrics().height(); + return MonthLayout(rect().adjusted(0, line + 4, 0, 0), m_year, m_month, + QLocale().firstDayOfWeek(), line + 2, line + 2); +} + +QDate MonthView::firstDay() const { return layout().dateAt(0); } +QDate MonthView::lastDay() const { return layout().dateAt(MonthLayout::kCells - 1).addDays(1); } + +QList<QList<int>> MonthView::itemsPerCell(const MonthLayout &l) const +{ + QList<QList<int>> cells(MonthLayout::kCells); + for (int i = 0; i < m_items.size(); ++i) { + const Occurrence &o = m_items[i].occurrence; + QDate day = o.start.toLocalTime().date(); + // The end is exclusive: an event ending at midnight does not touch + // the day that midnight begins. + const QDate last = o.end > o.start ? o.end.toLocalTime().addMSecs(-1).date() : day; + for (; day <= last; day = day.addDays(1)) { + const int cell = l.cellOf(day); + if (cell >= 0) + cells[cell].append(i); + } + } + return cells; +} + +void MonthView::paintEvent(QPaintEvent *) +{ + QPainter p(this); + p.fillRect(rect(), palette().base()); + const MonthLayout l = layout(); + const QLocale locale; + const int line = fontMetrics().height(); + + // Weekday header. + for (int col = 0; col < 7; ++col) { + const QRect cell = l.cellRect(col); + const int dow = (locale.firstDayOfWeek() - 1 + col) % 7 + 1; + p.setPen(palette().color(QPalette::PlaceholderText)); + p.drawText(QRect(cell.left(), 0, cell.width(), line + 4), Qt::AlignCenter, + locale.dayName(dow, QLocale::ShortFormat)); + } + + const QList<QList<int>> cells = itemsPerCell(l); + const QDate today = QDate::currentDate(); + for (int c = 0; c < MonthLayout::kCells; ++c) { + const QRect cell = l.cellRect(c); + const QDate date = l.dateAt(c); + p.setPen(palette().color(QPalette::Mid)); + p.drawRect(cell.adjusted(0, 0, -1, -1)); + + QRect number(cell.left() + 4, cell.top() + 1, fontMetrics().horizontalAdvance(QStringLiteral("00")) + 8, line); + if (date == today) { + p.setPen(Qt::NoPen); + p.setBrush(palette().highlight()); + p.drawRoundedRect(number, line / 2, line / 2); + p.setPen(palette().color(QPalette::HighlightedText)); + } else { + p.setPen(palette().color(date.month() == m_month ? QPalette::Text : QPalette::PlaceholderText)); + } + p.drawText(number, Qt::AlignCenter, QString::number(date.day())); + + const QList<int> &items = cells[c]; + const int shown = l.visibleChips(items.size()); + for (int slot = 0; slot < shown; ++slot) { + const CalendarItem &item = m_items[items[slot]]; + const QRect chip = l.chipRect(c, slot); + if (item.occurrence.allDay) { + p.setPen(Qt::NoPen); + p.setBrush(item.color); + p.drawRoundedRect(chip, 3, 3); + p.setPen(Qt::white); + p.drawText(chip.adjusted(4, 0, -2, 0), Qt::AlignVCenter | Qt::AlignLeft, + fontMetrics().elidedText(item.title, Qt::ElideRight, chip.width() - 6)); + } else { + const int dot = chip.height() / 2; + p.setPen(Qt::NoPen); + p.setBrush(item.color); + p.drawEllipse(QRect(chip.left() + 2, chip.center().y() - dot / 2, dot, dot)); + p.setPen(palette().color(QPalette::Text)); + const QString text = locale.toString(item.occurrence.start.toLocalTime().time(), + QLocale::ShortFormat) + + QLatin1Char(' ') + item.title; + const QRect textRect = chip.adjusted(dot + 6, 0, 0, 0); + p.drawText(textRect, Qt::AlignVCenter | Qt::AlignLeft, + fontMetrics().elidedText(text, Qt::ElideRight, textRect.width())); + } + if (items[slot] == m_selected) { + p.setPen(QPen(palette().color(QPalette::Highlight), 2)); + p.setBrush(Qt::NoBrush); + p.drawRoundedRect(chip, 3, 3); + } + } + if (shown < items.size()) { + p.setPen(palette().color(QPalette::Link)); + p.drawText(l.chipRect(c, shown).adjusted(4, 0, 0, 0), Qt::AlignVCenter | Qt::AlignLeft, + tr("+%n more", nullptr, int(items.size() - shown))); + } + } +} + +void MonthView::mousePressEvent(QMouseEvent *event) +{ + const MonthLayout l = layout(); + const int cell = l.cellAt(event->position().toPoint()); + if (cell < 0) + return; + const QList<int> items = itemsPerCell(l)[cell]; + const int shown = l.visibleChips(items.size()); + for (int slot = 0; slot < shown; ++slot) { + if (l.chipRect(cell, slot).contains(event->position().toPoint())) { + emit itemClicked(items[slot]); + return; + } + } + if (shown < items.size() && l.chipRect(cell, shown).contains(event->position().toPoint())) + emit moreClicked(l.dateAt(cell)); +} + +void MonthView::mouseDoubleClickEvent(QMouseEvent *event) +{ + const MonthLayout l = layout(); + const int cell = l.cellAt(event->position().toPoint()); + if (cell < 0) + return; + // A double-click on a chip is two clicks on the chip, not a new event. + const QList<int> items = itemsPerCell(l)[cell]; + for (int slot = 0; slot < l.visibleChips(items.size()); ++slot) + if (l.chipRect(cell, slot).contains(event->position().toPoint())) + return; + emit dayDoubleClicked(l.dateAt(cell)); +} +``` + +The `tr("+%n more", nullptr, n)` form is the plural-aware one; the Italian `.ts` then needs both plural forms in Task 16. + +- [ ] **Step 3: Write `src/agendaview.h` and `src/agendaview.cpp`** + +```cpp +/* GPLv2 header */ + +#pragma once + +#include "caltypes.h" + +#include <QListWidget> + +/// The agenda: the same items as the month grid, as a list under day headers. +class AgendaView : public QListWidget +{ + Q_OBJECT + +public: + explicit AgendaView(QWidget *parent = nullptr); + + void setItems(const QList<CalendarItem> &items); + void setSelected(int item); + /// Scrolls so `day`'s header, or the first day after it, is at the top. + void scrollToDay(const QDate &day); + +signals: + void itemClicked(int item); +}; +``` + +```cpp +/* GPLv2 header */ + +#include "agendaview.h" + +#include <QLocale> +#include <QPainter> +#include <QPixmap> + +namespace { +constexpr int kItemRole = Qt::UserRole; ///< Index into the items, or -1 for a header. +constexpr int kDayRole = Qt::UserRole + 1; ///< The header's date. +} + +AgendaView::AgendaView(QWidget *parent) : QListWidget(parent) +{ + connect(this, &QListWidget::itemClicked, this, [this](QListWidgetItem *row) { + const int item = row->data(kItemRole).toInt(); + if (item >= 0) + emit itemClicked(item); + }); +} + +void AgendaView::setItems(const QList<CalendarItem> &items) +{ + clear(); + const QLocale locale; + QDate current; + for (int i = 0; i < items.size(); ++i) { + const CalendarItem &item = items[i]; + // A blank item is a placeholder the window leaves so every row's + // index stays the same as the month grid's: skipped, not shown. + if (item.title.isEmpty()) + continue; + const QDate day = item.occurrence.start.toLocalTime().date(); + if (day != current) { + current = day; + auto *header = new QListWidgetItem(locale.toString(day, QLocale::LongFormat), this); + QFont bold = header->font(); + bold.setBold(true); + header->setFont(bold); + header->setFlags(Qt::ItemIsEnabled); // not selectable + header->setData(kItemRole, -1); + header->setData(kDayRole, day); + } + const QString when = item.occurrence.allDay + ? tr("all day") + : tr("%1 - %2").arg(locale.toString(item.occurrence.start.toLocalTime().time(), QLocale::ShortFormat), + locale.toString(item.occurrence.end.toLocalTime().time(), QLocale::ShortFormat)); + QPixmap swatch(10, 10); + swatch.fill(Qt::transparent); + QPainter(&swatch).fillRect(swatch.rect(), item.color); + auto *row = new QListWidgetItem(QIcon(swatch), when + QStringLiteral(" ") + item.title, this); + row->setData(kItemRole, i); + } +} + +void AgendaView::setSelected(int item) +{ + for (int r = 0; r < count(); ++r) { + if (this->item(r)->data(kItemRole).toInt() == item) { + setCurrentRow(r); + return; + } + } + clearSelection(); +} + +void AgendaView::scrollToDay(const QDate &day) +{ + for (int r = 0; r < count(); ++r) { + const QDate header = item(r)->data(kDayRole).toDate(); + if (header.isValid() && header >= day) { + scrollToItem(item(r), QAbstractItemView::PositionAtTop); + return; + } + } +} +``` + +An item's title reaches `QListWidgetItem` as plain text: a list item has no rich-text mode, so the untrusted-text rule holds here by construction. + +- [ ] **Step 4: Build** + +Add `monthview.cpp` and `agendaview.cpp` to `src/CMakeLists.txt`. +Run: `cmake --build build 2>&1 | tail -3` +Expected: builds with no warnings from the new files. + +- [ ] **Step 5: Commit** + +```bash +git add src/monthview.h src/monthview.cpp src/agendaview.h src/agendaview.cpp src/CMakeLists.txt +git commit -m "feat: paint the calendar's month grid and agenda list" +``` + +--- + +### Task 13: `EventPane` + +The side pane's two pages. Its visual layout is the user's hand test; what is tested (Task 14, through the window) is the edit state it reports. + +**Files:** +- Create: `src/eventpane.h`, `src/eventpane.cpp` +- Modify: `src/CMakeLists.txt` + +- [ ] **Step 1: Write `src/eventpane.h`** + +```cpp +/* GPLv2 header */ + +#pragma once + +#include "caltypes.h" + +#include <QStackedWidget> + +class QCheckBox; +class QComboBox; +class QDateEdit; +class QDateTimeEdit; +class QLabel; +class QLineEdit; +class QPlainTextEdit; +class QPushButton; +class QSpinBox; + +/// The calendar window's right-hand pane: a read-only page for the selected +/// event, and the edit form that replaces it (spec decision 11). +/// +/// Every value from a file is shown in a Qt::PlainText label: SUMMARY, +/// DESCRIPTION, LOCATION and attendee names come from strangers once +/// invitations arrive, which is MessageDetailsDialog's rule. +class EventPane : public QStackedWidget +{ + Q_OBJECT + +public: + explicit EventPane(QWidget *parent = nullptr); + + void showNothing(); + void showDetails(const CalEvent &event, const CalCollection &collection, + const Occurrence &occurrence, bool editable); + + /// Opens the form. `collections` are the writable ones, for the Calendar + /// combo; `repeatEditable` is false for a single occurrence, which has no + /// rule of its own; `collectionEditable` is false for the same reason. + void startEdit(const EventEdit &initial, const QList<CalCollection> &collections, + bool repeatEditable, bool collectionEditable, + const QString &reminderText, const QString &attendeesText); + void stopEdit(); + + bool isEditing() const; + bool isDirty() const; + EventEdit edit() const; + +signals: + void editRequested(); + void deleteRequested(); + void saveRequested(); + void cancelRequested(); + +private: + QWidget *buildDetails(); + QWidget *buildForm(); + QWidget *buildRepeat(); + void setRepeat(const RepeatRule &rule); + RepeatRule repeat() const; + void proposeFromStart(); + void refreshRepeatVisibility(); + void refreshAllDay(); + + // Details page. + QLabel *m_title; + QLabel *m_when; + QLabel *m_repeatText; + QLabel *m_calendar; + QLabel *m_location; + QLabel *m_notes; + QLabel *m_reminder; + QLabel *m_people; + QLabel *m_notice; + QPushButton *m_editButton; + QPushButton *m_deleteButton; + + // Form. + QLineEdit *m_titleEdit; + QComboBox *m_calendarBox; + QCheckBox *m_allDay; + QDateTimeEdit *m_startEdit; + QDateTimeEdit *m_endEdit; + QLineEdit *m_locationEdit; + QPlainTextEdit *m_notesEdit; + QLabel *m_formReminder; + QLabel *m_formPeople; + QLabel *m_formNotice; + + // Repeat control. + QWidget *m_repeatBox; + QComboBox *m_freq; ///< None, Daily, Weekly, Monthly, Yearly, [Custom] + QSpinBox *m_interval; + QWidget *m_weekdayRow; + QList<QCheckBox *> m_weekdays; ///< Monday first, index = Qt::DayOfWeek - 1 + QComboBox *m_by; ///< "on day N" / "on the Nth weekday" + QSpinBox *m_monthDay; + QComboBox *m_ordinal; ///< first..fourth, last + QComboBox *m_weekday; + QComboBox *m_month; + QComboBox *m_end; ///< never, on a date, after N times + QDateEdit *m_until; + QSpinBox *m_count; + QLabel *m_customLabel; + + EventEdit m_initial; + RepeatRule m_customRule; ///< Kept when the rule read was custom. + QDateTime m_previousStart; ///< For keeping the duration as the start moves. + bool m_editing = false; +}; +``` + +- [ ] **Step 2: Write `src/eventpane.cpp`** + +```cpp +/* GPLv2 header */ + +#include "eventpane.h" + +#include <QCheckBox> +#include <QComboBox> +#include <QDateEdit> +#include <QDateTimeEdit> +#include <QFormLayout> +#include <QHBoxLayout> +#include <QLabel> +#include <QLineEdit> +#include <QLocale> +#include <QPainter> +#include <QPixmap> +#include <QPlainTextEdit> +#include <QPushButton> +#include <QSpinBox> +#include <QTimeZone> +#include <QVBoxLayout> + +namespace { + +QLabel *plainLabel(QWidget *parent) +{ + auto *label = new QLabel(parent); + label->setTextFormat(Qt::PlainText); // untrusted: never AutoText + label->setWordWrap(true); + label->setTextInteractionFlags(Qt::TextSelectableByMouse); + return label; +} + +QIcon swatch(const QColor &colour) +{ + QPixmap pixmap(12, 12); + pixmap.fill(Qt::transparent); + QPainter(&pixmap).fillRect(pixmap.rect(), colour); + return QIcon(pixmap); +} + +bool sameEdit(const EventEdit &a, const EventEdit &b) +{ + return a.summary == b.summary && a.location == b.location + && a.description == b.description && a.start == b.start && a.end == b.end + && a.allDay == b.allDay && a.repeat == b.repeat && a.collectionDir == b.collectionDir; +} + +constexpr int kCustomIndex = 5; + +} // namespace + +EventPane::EventPane(QWidget *parent) : QStackedWidget(parent) +{ + addWidget(new QWidget(this)); // 0: nothing selected + addWidget(buildDetails()); // 1 + addWidget(buildForm()); // 2 + setMinimumWidth(260); + showNothing(); +} + +QWidget *EventPane::buildDetails() +{ + auto *page = new QWidget(this); + auto *layout = new QVBoxLayout(page); + m_title = plainLabel(page); + QFont big = m_title->font(); + big.setBold(true); + big.setPointSizeF(big.pointSizeF() > 0 ? big.pointSizeF() * 1.3 : big.pointSizeF()); + m_title->setFont(big); + layout->addWidget(m_title); + + auto *form = new QFormLayout; + m_when = plainLabel(page); + m_repeatText = plainLabel(page); + m_calendar = plainLabel(page); + m_location = plainLabel(page); + m_notes = plainLabel(page); + m_reminder = plainLabel(page); + m_people = plainLabel(page); + form->addRow(tr("When"), m_when); + form->addRow(tr("Repeats"), m_repeatText); + form->addRow(tr("Calendar"), m_calendar); + form->addRow(tr("Location"), m_location); + form->addRow(tr("Notes"), m_notes); + form->addRow(tr("Reminder"), m_reminder); + form->addRow(tr("People"), m_people); + layout->addLayout(form); + + m_notice = plainLabel(page); + m_notice->setObjectName(QStringLiteral("eventNotice")); + layout->addWidget(m_notice); + + auto *buttons = new QHBoxLayout; + m_editButton = new QPushButton(tr("&Edit"), page); + m_editButton->setObjectName(QStringLiteral("editEvent")); + m_deleteButton = new QPushButton(tr("&Delete"), page); + m_deleteButton->setObjectName(QStringLiteral("deleteEvent")); + buttons->addWidget(m_editButton); + buttons->addWidget(m_deleteButton); + buttons->addStretch(); + layout->addLayout(buttons); + layout->addStretch(); + + connect(m_editButton, &QPushButton::clicked, this, &EventPane::editRequested); + connect(m_deleteButton, &QPushButton::clicked, this, &EventPane::deleteRequested); + return page; +} + +QWidget *EventPane::buildForm() +{ + auto *page = new QWidget(this); + auto *layout = new QVBoxLayout(page); + auto *form = new QFormLayout; + + m_titleEdit = new QLineEdit(page); + m_titleEdit->setObjectName(QStringLiteral("eventTitle")); + m_calendarBox = new QComboBox(page); + m_calendarBox->setObjectName(QStringLiteral("eventCalendar")); + m_allDay = new QCheckBox(tr("All day"), page); + m_startEdit = new QDateTimeEdit(page); + m_startEdit->setObjectName(QStringLiteral("eventStart")); + m_startEdit->setCalendarPopup(true); + m_endEdit = new QDateTimeEdit(page); + m_endEdit->setObjectName(QStringLiteral("eventEnd")); + m_endEdit->setCalendarPopup(true); + m_locationEdit = new QLineEdit(page); + m_notesEdit = new QPlainTextEdit(page); + m_formReminder = plainLabel(page); + m_formPeople = plainLabel(page); + + form->addRow(tr("Title"), m_titleEdit); + form->addRow(tr("Calendar"), m_calendarBox); + form->addRow(QString(), m_allDay); + form->addRow(tr("Starts"), m_startEdit); + form->addRow(tr("Ends"), m_endEdit); + form->addRow(tr("Repeat"), buildRepeat()); + form->addRow(tr("Location"), m_locationEdit); + form->addRow(tr("Notes"), m_notesEdit); + form->addRow(tr("Reminder"), m_formReminder); + form->addRow(tr("People"), m_formPeople); + layout->addLayout(form); + + m_formNotice = plainLabel(page); + layout->addWidget(m_formNotice); + + auto *buttons = new QHBoxLayout; + auto *save = new QPushButton(tr("&Save"), page); + save->setObjectName(QStringLiteral("saveEvent")); + save->setDefault(true); + auto *cancel = new QPushButton(tr("Cancel"), page); + cancel->setObjectName(QStringLiteral("cancelEvent")); + buttons->addStretch(); + buttons->addWidget(cancel); + buttons->addWidget(save); + layout->addLayout(buttons); + + connect(save, &QPushButton::clicked, this, &EventPane::saveRequested); + connect(cancel, &QPushButton::clicked, this, &EventPane::cancelRequested); + connect(m_allDay, &QCheckBox::toggled, this, &EventPane::refreshAllDay); + // Keep the duration when the start moves, as every calendar does. + connect(m_startEdit, &QDateTimeEdit::dateTimeChanged, this, [this](const QDateTime &start) { + if (m_previousStart.isValid() && m_editing) { + const qint64 length = m_previousStart.secsTo(m_endEdit->dateTime()); + m_endEdit->setDateTime(start.addSecs(qMax<qint64>(0, length))); + } + m_previousStart = start; + proposeFromStart(); + }); + return page; +} +``` + +`m_previousStart` is a member, reset in `startEdit`: a function-local static would carry one edit's start into the next. + +```cpp +QWidget *EventPane::buildRepeat() +{ + m_repeatBox = new QWidget(this); + auto *box = new QVBoxLayout(m_repeatBox); + box->setContentsMargins(0, 0, 0, 0); + const QLocale locale; + + auto *row = new QHBoxLayout; + m_freq = new QComboBox(m_repeatBox); + m_freq->setObjectName(QStringLiteral("eventRepeat")); + m_freq->addItems({ tr("Does not repeat"), tr("Daily"), tr("Weekly"), + tr("Monthly"), tr("Yearly") }); + m_interval = new QSpinBox(m_repeatBox); + m_interval->setRange(1, 99); + m_interval->setPrefix(tr("every ")); + row->addWidget(m_freq); + row->addWidget(m_interval); + box->addLayout(row); + + m_weekdayRow = new QWidget(m_repeatBox); + auto *days = new QHBoxLayout(m_weekdayRow); + days->setContentsMargins(0, 0, 0, 0); + for (int d = 1; d <= 7; ++d) { + auto *check = new QCheckBox(locale.dayName(d, QLocale::NarrowFormat), m_weekdayRow); + m_weekdays.append(check); + days->addWidget(check); + } + box->addWidget(m_weekdayRow); + + auto *byRow = new QHBoxLayout; + m_by = new QComboBox(m_repeatBox); + m_by->addItems({ tr("on day"), tr("on the") }); + m_monthDay = new QSpinBox(m_repeatBox); + m_monthDay->setRange(1, 31); + m_ordinal = new QComboBox(m_repeatBox); + m_ordinal->addItem(tr("first"), 1); + m_ordinal->addItem(tr("second"), 2); + m_ordinal->addItem(tr("third"), 3); + m_ordinal->addItem(tr("fourth"), 4); + m_ordinal->addItem(tr("last"), -1); + m_weekday = new QComboBox(m_repeatBox); + for (int d = 1; d <= 7; ++d) + m_weekday->addItem(locale.dayName(d), d); + m_month = new QComboBox(m_repeatBox); + for (int m = 1; m <= 12; ++m) + m_month->addItem(tr("of %1").arg(locale.monthName(m)), m); + byRow->addWidget(m_by); + byRow->addWidget(m_monthDay); + byRow->addWidget(m_ordinal); + byRow->addWidget(m_weekday); + byRow->addWidget(m_month); + box->addLayout(byRow); + + auto *endRow = new QHBoxLayout; + m_end = new QComboBox(m_repeatBox); + m_end->addItems({ tr("forever"), tr("until"), tr("for") }); + m_until = new QDateEdit(m_repeatBox); + m_until->setCalendarPopup(true); + m_count = new QSpinBox(m_repeatBox); + m_count->setRange(1, 999); + m_count->setSuffix(tr(" times")); + endRow->addWidget(m_end); + endRow->addWidget(m_until); + endRow->addWidget(m_count); + box->addLayout(endRow); + + m_customLabel = new QLabel(tr("Custom rule, kept as is"), m_repeatBox); + box->addWidget(m_customLabel); + + for (QComboBox *combo : { m_freq, m_by, m_end }) + connect(combo, &QComboBox::currentIndexChanged, this, &EventPane::refreshRepeatVisibility); + connect(m_freq, &QComboBox::currentIndexChanged, this, &EventPane::proposeFromStart); + return m_repeatBox; +} + +void EventPane::refreshRepeatVisibility() +{ + const int freq = m_freq->currentIndex(); + const bool custom = freq == kCustomIndex; + const bool repeats = freq > 0 && !custom; + const bool monthly = freq == 3, yearly = freq == 4; + const bool byWeekday = m_by->currentIndex() == 1; + m_interval->setVisible(repeats); + m_weekdayRow->setVisible(freq == 2); + m_by->setVisible(monthly || yearly); + // Yearly "on day" means on the start date, which needs no control. + m_monthDay->setVisible(monthly && !byWeekday); + m_ordinal->setVisible((monthly || yearly) && byWeekday); + m_weekday->setVisible((monthly || yearly) && byWeekday); + m_month->setVisible(yearly && byWeekday); + m_end->setVisible(repeats); + m_until->setVisible(repeats && m_end->currentIndex() == 1); + m_count->setVisible(repeats && m_end->currentIndex() == 2); + m_customLabel->setVisible(custom); +} + +/// Re-proposes the day-dependent defaults from the start date, as Thunderbird +/// does: "on day 24", or "the fourth Thursday" (the fifth becomes "last"). +void EventPane::proposeFromStart() +{ + const QDate start = m_startEdit->date(); + m_monthDay->setValue(start.day()); + const int ordinal = (start.day() - 1) / 7 + 1; + m_ordinal->setCurrentIndex(m_ordinal->findData(ordinal > 4 ? -1 : ordinal)); + m_weekday->setCurrentIndex(m_weekday->findData(start.dayOfWeek())); + m_month->setCurrentIndex(start.month() - 1); + if (m_freq->currentIndex() == 2 + && std::none_of(m_weekdays.cbegin(), m_weekdays.cend(), + [](QCheckBox *c) { return c->isChecked(); })) + m_weekdays[start.dayOfWeek() - 1]->setChecked(true); +} + +void EventPane::setRepeat(const RepeatRule &rule) +{ + if (m_freq->count() > kCustomIndex) + m_freq->removeItem(kCustomIndex); + m_customRule = RepeatRule(); + if (rule.custom) { + m_customRule = rule; + m_freq->addItem(tr("Custom rule")); + m_freq->setCurrentIndex(kCustomIndex); + refreshRepeatVisibility(); + return; + } + m_freq->setCurrentIndex(static_cast<int>(rule.freq)); + proposeFromStart(); + m_interval->setValue(rule.interval); + for (int d = 0; d < 7; ++d) + m_weekdays[d]->setChecked(rule.weekdays.contains(d + 1)); + m_by->setCurrentIndex(rule.by == RepeatRule::By::Weekday ? 1 : 0); + if (rule.monthDay) + m_monthDay->setValue(rule.monthDay); + if (rule.ordinal) + m_ordinal->setCurrentIndex(m_ordinal->findData(rule.ordinal)); + if (rule.weekday) + m_weekday->setCurrentIndex(m_weekday->findData(rule.weekday)); + if (rule.month) + m_month->setCurrentIndex(rule.month - 1); + m_end->setCurrentIndex(static_cast<int>(rule.end)); + m_until->setDate(rule.until.isValid() ? rule.until : m_startEdit->date().addMonths(1)); + m_count->setValue(qMax(1, rule.count)); + refreshRepeatVisibility(); +} + +RepeatRule EventPane::repeat() const +{ + if (m_freq->currentIndex() == kCustomIndex) + return m_customRule; + RepeatRule rule; + rule.freq = static_cast<RepeatRule::Freq>(m_freq->currentIndex()); + if (rule.freq == RepeatRule::Freq::None) + return rule; + rule.interval = m_interval->value(); + rule.wkst = m_initial.repeat.wkst; // carried through, spec + if (rule.freq == RepeatRule::Freq::Weekly) + for (int d = 0; d < 7; ++d) + if (m_weekdays[d]->isChecked()) + rule.weekdays.append(d + 1); + if (rule.freq == RepeatRule::Freq::Monthly || rule.freq == RepeatRule::Freq::Yearly) { + rule.by = m_by->currentIndex() == 1 ? RepeatRule::By::Weekday : RepeatRule::By::MonthDay; + if (rule.by == RepeatRule::By::Weekday) { + rule.ordinal = m_ordinal->currentData().toInt(); + rule.weekday = m_weekday->currentData().toInt(); + if (rule.freq == RepeatRule::Freq::Yearly) + rule.month = m_month->currentData().toInt(); + } else if (rule.freq == RepeatRule::Freq::Monthly) { + rule.monthDay = m_monthDay->value(); + } + } + rule.end = static_cast<RepeatRule::End>(m_end->currentIndex()); + if (rule.end == RepeatRule::End::Until) + rule.until = m_until->date(); + else if (rule.end == RepeatRule::End::Count) + rule.count = m_count->value(); + return rule; +} + +void EventPane::refreshAllDay() +{ + // All-day shows DATES, and the end is the LAST day, inclusive: what a + // person means by "24 to 25 September". edit() converts back to the + // exclusive end iCalendar needs. + const QString format = m_allDay->isChecked() + ? QLocale().dateFormat(QLocale::ShortFormat) + : QLocale().dateTimeFormat(QLocale::ShortFormat); + m_startEdit->setDisplayFormat(format); + m_endEdit->setDisplayFormat(format); +} + +void EventPane::showNothing() +{ + m_editing = false; + setCurrentIndex(0); +} + +void EventPane::showDetails(const CalEvent &event, const CalCollection &collection, + const Occurrence &occurrence, bool editable) +{ + m_editing = false; + const QLocale locale; + const CalOverride *ov = occurrence.isOverride ? &event.overrides[occurrence.overrideIndex] : nullptr; + const QString summary = ov ? ov->summary : event.summary; + m_title->setText(summary.isEmpty() ? tr("(no title)") : summary); + + const QDateTime start = occurrence.start.toLocalTime(), end = occurrence.end.toLocalTime(); + if (occurrence.allDay) { + const QDate last = end.date().addDays(-1); + m_when->setText(last > start.date() + ? tr("%1 to %2, all day").arg(locale.toString(start.date(), QLocale::LongFormat), + locale.toString(last, QLocale::LongFormat)) + : tr("%1, all day").arg(locale.toString(start.date(), QLocale::LongFormat))); + } else { + m_when->setText(tr("%1, %2 - %3").arg(locale.toString(start.date(), QLocale::LongFormat), + locale.toString(start.time(), QLocale::ShortFormat), + locale.toString(end.time(), QLocale::ShortFormat))); + } + m_repeatText->setText(event.repeat.freq == RepeatRule::Freq::None && !event.repeat.custom + ? tr("Does not repeat") : event.repeat.describe()); + m_calendar->setText(collection.displayName); + m_location->setText(ov ? ov->location : event.location); + m_notes->setText(ov ? ov->description : event.description); + m_reminder->setText(event.hasAlarm ? tr("Yes, kept as set elsewhere") : tr("None")); + + QStringList people; + if (!event.organizer.address.isEmpty()) + people << tr("Organiser: %1").arg(event.organizer.name.isEmpty() + ? event.organizer.address : event.organizer.name); + for (const CalPerson &a : event.attendees) + people << QStringLiteral("%1 (%2)").arg(a.name.isEmpty() ? a.address : a.name, + a.partstat.isEmpty() ? tr("no reply") : a.partstat.toLower()); + m_people->setText(people.join(QLatin1Char('\n'))); + + QString notice; + if (collection.readOnly) + notice = tr("Read-only calendar."); + else if (!editable) + notice = tr("Organised by %1: read-only.").arg(event.organizer.name.isEmpty() + ? event.organizer.address : event.organizer.name); + m_notice->setText(notice); + m_notice->setVisible(!notice.isEmpty()); + // Absent, not disabled (AGENTS.md precedent). + m_editButton->setVisible(editable); + m_deleteButton->setVisible(editable); + setCurrentIndex(1); +} + +void EventPane::startEdit(const EventEdit &initial, const QList<CalCollection> &collections, + bool repeatEditable, bool collectionEditable, + const QString &reminderText, const QString &attendeesText) +{ + m_initial = initial; + m_editing = false; // no duration-keeping while the fields are filled + m_calendarBox->clear(); + for (const CalCollection &c : collections) + m_calendarBox->addItem(swatch(c.color), c.displayName, c.dir); + m_calendarBox->setCurrentIndex(qMax(0, m_calendarBox->findData(initial.collectionDir))); + m_calendarBox->setEnabled(collectionEditable); + + m_previousStart = QDateTime(); + m_titleEdit->setText(initial.summary); + m_allDay->setChecked(initial.allDay); + refreshAllDay(); + m_startEdit->setDateTime(initial.start.toLocalTime()); + m_endEdit->setDateTime(initial.allDay ? initial.end.toLocalTime().addDays(-1) + : initial.end.toLocalTime()); + m_locationEdit->setText(initial.location); + m_notesEdit->setPlainText(initial.description); + setRepeat(initial.repeat); + m_repeatBox->setEnabled(repeatEditable); + m_formReminder->setText(reminderText); + m_formPeople->setText(attendeesText); + m_formNotice->setText(attendeesText.isEmpty() ? QString() + : tr("Attendees have not been notified of changes.")); + m_formNotice->setVisible(!attendeesText.isEmpty()); + + // The form rounds what it shows (seconds, the display format), so the + // baseline for isDirty() is what the form PRODUCES, not what came in. + m_initial = edit(); + m_editing = true; + setCurrentIndex(2); + m_titleEdit->setFocus(); +} + +void EventPane::stopEdit() { m_editing = false; } +bool EventPane::isEditing() const { return m_editing; } +bool EventPane::isDirty() const { return m_editing && !sameEdit(edit(), m_initial); } + +EventEdit EventPane::edit() const +{ + EventEdit e; + e.summary = m_titleEdit->text().trimmed(); + e.location = m_locationEdit->text().trimmed(); + e.description = m_notesEdit->toPlainText(); + e.allDay = m_allDay->isChecked(); + e.collectionDir = m_calendarBox->currentData().toString(); + if (e.allDay) { + e.start = QDateTime(m_startEdit->date(), QTime(0, 0)); + e.end = QDateTime(qMax(m_endEdit->date(), m_startEdit->date()).addDays(1), QTime(0, 0)); + } else { + e.start = m_startEdit->dateTime(); + e.end = qMax(m_endEdit->dateTime(), e.start); + } + e.repeat = repeat(); + return e; +} +``` + +Add `#include <algorithm>`. `QDateTimeEdit::dateTime()` returns local time with the edit's time spec; check it is `Qt::LocalTime` so `applyEdit` converts it into the event's zone correctly, and that the test `saveWritesAndUndoRestores` (Task 14) still round-trips the unchanged start. + +- [ ] **Step 3: Build** + +Add `eventpane.cpp` to `src/CMakeLists.txt`. +Run: `cmake --build build 2>&1 | tail -3` +Expected: builds cleanly. + +- [ ] **Step 4: Commit** + +```bash +git add src/eventpane.h src/eventpane.cpp src/CMakeLists.txt +git commit -m "feat: show and edit a calendar event in the side pane" +``` + +--- + +### Task 14: `CalendarWindow` + +**Files:** +- Create: `src/calendarwindow.h`, `src/calendarwindow.cpp` +- Modify: `src/CMakeLists.txt`, `tests/CMakeLists.txt` (`add_qtmaildir_test(calendarwindow)`) +- Test: `tests/test_calendarwindow.cpp` + +- [ ] **Step 1: Write the failing tests** + +```cpp +/* GPLv2 header */ + +#include <QtTest> +#include <QApplication> +#include <QDir> +#include <QFile> +#include <QLineEdit> +#include <QMessageBox> +#include <QPushButton> +#include <QTemporaryDir> +#include <QUndoStack> + +#include "calendarwindow.h" +#include "config.h" + +namespace { + +QByteArray eventText(const QString &uid, const QString &summary, int day) +{ + return QStringLiteral( + "BEGIN:VCALENDAR\r\nVERSION:2.0\r\nPRODID:-//example//test//EN\r\n" + "BEGIN:VEVENT\r\nUID:%1\r\nDTSTAMP:20260901T000000Z\r\n" + "DTSTART:202609%2T080000Z\r\nDTEND:202609%2T090000Z\r\nSUMMARY:%3\r\n" + "END:VEVENT\r\nEND:VCALENDAR\r\n") + .arg(uid).arg(day, 2, 10, QLatin1Char('0')).arg(summary).toUtf8(); +} + +void writeFile(const QString &path, const QByteArray &content) +{ + QDir().mkpath(QFileInfo(path).absolutePath()); + QFile f(path); + QVERIFY(f.open(QIODevice::WriteOnly | QIODevice::Truncate)); + f.write(content); +} + +QByteArray read(const QString &path) +{ + QFile f(path); + return f.open(QIODevice::ReadOnly) ? f.readAll() : QByteArray(); +} + +/// A vdir with collections "a" and "b", two events in "a", and a config +/// pointing at it with syncing off, so no test ever runs vdirsyncer. +struct Fixture +{ + QTemporaryDir dir; + Config config; + QString a() const { return dir.filePath(QStringLiteral("cal/a/one.ics")); } + + Fixture() + { + writeFile(a(), eventText(QStringLiteral("one@example.org"), QStringLiteral("One"), 22)); + writeFile(dir.filePath(QStringLiteral("cal/a/two.ics")), + eventText(QStringLiteral("two@example.org"), QStringLiteral("Two"), 23)); + QDir().mkpath(dir.filePath(QStringLiteral("cal/b"))); + const QString ini = dir.filePath(QStringLiteral("qtmaildir.conf")); + writeFile(ini, QStringLiteral("[general]\ncalendars_dir = %1\n" + "default_calendar = b\ncalendar_sync_command = \n") + .arg(dir.filePath(QStringLiteral("cal"))).toUtf8()); + config.load(ini); + } + + CalendarWindow *window() + { + auto *w = new CalendarWindow(config, { QStringLiteral("me@example.org") }, + dir.filePath(QStringLiteral("uistate.conf"))); + w->showMonth(2026, 9); + w->show(); + return w; + } +}; + +/// Answers the next modal QMessageBox with `button` once it is up. +void answerNextBox(QMessageBox::StandardButton button) +{ + QTimer::singleShot(0, [button]() { + auto *box = qobject_cast<QMessageBox *>(QApplication::activeModalWidget()); + QVERIFY2(box, "no modal message box appeared"); + box->button(button)->click(); + }); +} + +void editTitle(CalendarWindow *w, const QString &title) +{ + w->findChild<QPushButton *>(QStringLiteral("editEvent"))->click(); + w->findChild<QLineEdit *>(QStringLiteral("eventTitle"))->setText(title); +} + +} // namespace + +class TestCalendarWindow : public QObject +{ + Q_OBJECT + +private slots: + void loadsAndSelects(); + void theEditLockRefusesASelectionChange(); + void closingWithUnsavedChangesAsksOnEveryRoute(); + void saveWritesAndUndoRestoresTheOriginalBytes(); + void aNewEventGoesToTheDefaultCalendar(); + void aStaleSaveKeepsTheFormAndTheSyncedFile(); +}; + +void TestCalendarWindow::loadsAndSelects() +{ + Fixture f; + std::unique_ptr<CalendarWindow> w(f.window()); + QVERIFY(w->selectEvent(QStringLiteral("two@example.org"))); + QCOMPARE(w->selectedUid(), QStringLiteral("two@example.org")); + QVERIFY(!w->selectEvent(QStringLiteral("absent@example.org"))); +} + +void TestCalendarWindow::theEditLockRefusesASelectionChange() +{ + Fixture f; + std::unique_ptr<CalendarWindow> w(f.window()); + QVERIFY(w->selectEvent(QStringLiteral("one@example.org"))); + editTitle(w.get(), QStringLiteral("Changed")); + QVERIFY(!w->selectEvent(QStringLiteral("two@example.org"))); + QCOMPARE(w->selectedUid(), QStringLiteral("one@example.org")); +} + +void TestCalendarWindow::closingWithUnsavedChangesAsksOnEveryRoute() +{ + Fixture f; + const QByteArray original = read(f.a()); + + // Cancel keeps the window and the file. Route: close(). + std::unique_ptr<CalendarWindow> w(f.window()); + w->selectEvent(QStringLiteral("one@example.org")); + editTitle(w.get(), QStringLiteral("Changed")); + answerNextBox(QMessageBox::Cancel); + w->close(); + QVERIFY(w->isVisible()); + QCOMPARE(read(f.a()), original); + + // Discard closes and writes nothing. Route: the File menu's Close action. + answerNextBox(QMessageBox::Discard); + w->findChild<QAction *>(QStringLiteral("closeCalendar"))->trigger(); + QVERIFY(!w->isVisible()); + QCOMPARE(read(f.a()), original); + + // Save closes and writes. + std::unique_ptr<CalendarWindow> again(f.window()); + again->selectEvent(QStringLiteral("one@example.org")); + editTitle(again.get(), QStringLiteral("Saved on close")); + answerNextBox(QMessageBox::Save); + again->close(); + QVERIFY(!again->isVisible()); + QVERIFY(read(f.a()).contains("SUMMARY:Saved on close")); +} + +void TestCalendarWindow::saveWritesAndUndoRestoresTheOriginalBytes() +{ + Fixture f; + const QByteArray original = read(f.a()); + std::unique_ptr<CalendarWindow> w(f.window()); + w->selectEvent(QStringLiteral("one@example.org")); + editTitle(w.get(), QStringLiteral("Renamed")); + w->findChild<QPushButton *>(QStringLiteral("saveEvent"))->click(); + QVERIFY(read(f.a()).contains("SUMMARY:Renamed")); + + w->undoStack()->undo(); + QCOMPARE(read(f.a()), original); // exactly the bytes it had: item 176's rule + w->undoStack()->redo(); + QVERIFY(read(f.a()).contains("SUMMARY:Renamed")); +} + +void TestCalendarWindow::aNewEventGoesToTheDefaultCalendar() +{ + Fixture f; + std::unique_ptr<CalendarWindow> w(f.window()); + w->findChild<QAction *>(QStringLiteral("newEvent"))->trigger(); + w->findChild<QLineEdit *>(QStringLiteral("eventTitle"))->setText(QStringLiteral("Fresh")); + w->findChild<QPushButton *>(QStringLiteral("saveEvent"))->click(); + const QStringList created = QDir(f.dir.filePath(QStringLiteral("cal/b"))) + .entryList({ QStringLiteral("*.ics") }, QDir::Files); + QCOMPARE(created.size(), 1); + QVERIFY(read(f.dir.filePath(QStringLiteral("cal/b/")) + created.first()).contains("SUMMARY:Fresh")); + + w->undoStack()->undo(); + QVERIFY(QDir(f.dir.filePath(QStringLiteral("cal/b"))).entryList({ QStringLiteral("*.ics") }).isEmpty()); +} + +void TestCalendarWindow::aStaleSaveKeepsTheFormAndTheSyncedFile() +{ + Fixture f; + std::unique_ptr<CalendarWindow> w(f.window()); + w->selectEvent(QStringLiteral("one@example.org")); + editTitle(w.get(), QStringLiteral("Mine")); + // A sync pulls a server change while the form is open. + const QByteArray synced = eventText(QStringLiteral("one@example.org"), QStringLiteral("Theirs"), 22); + writeFile(f.a(), synced); + w->findChild<QPushButton *>(QStringLiteral("saveEvent"))->click(); + QCOMPARE(read(f.a()), synced); // nothing clobbered + QVERIFY(w->isEditing()); // the user's values are still there + QCOMPARE(w->findChild<QLineEdit *>(QStringLiteral("eventTitle"))->text(), QStringLiteral("Mine")); +} + +QTEST_MAIN(TestCalendarWindow) +#include "test_calendarwindow.moc" +``` + +`std::unique_ptr<CalendarWindow>` requires the window NOT to set `WA_DeleteOnClose` itself; `MainWindow` sets that when it opens one (Task 15), as it does for composers. Add `#include <memory>` and `#include <QTimer>`. + +- [ ] **Step 2: Write `src/calendarwindow.h`** + +```cpp +/* GPLv2 header */ + +#pragma once + +#include "caltypes.h" +#include "config.h" + +#include <QFileSystemWatcher> +#include <QHash> +#include <QMainWindow> +#include <QTimer> +#include <QUndoStack> + +#include <optional> + +class AgendaView; +class CalendarSync; +class EventPane; +class MonthView; +class QComboBox; +class QLabel; +class QSpinBox; +class QStackedWidget; +class QToolButton; + +/// The calendar (item 206): its own top-level window, like ComposeWindow. +/// Spec: docs/superpowers/specs/2026-09-24-calendar-design.md. +class CalendarWindow : public QMainWindow +{ + Q_OBJECT + +public: + CalendarWindow(const Config &config, const QStringList &ownAddresses, + const QString &uiStatePath, QWidget *parent = nullptr); + ~CalendarWindow() override; + + void showMonth(int year, int month); + /// Selects an event's occurrence (the first in view when `start` is + /// invalid). False when not found, or refused by the edit lock. + bool selectEvent(const QString &uid, const QDateTime &start = {}); + QString selectedUid() const; + bool isEditing() const; + QUndoStack *undoStack() { return &m_undo; } + + /// One file's before and after, either absent. What a write and its undo + /// are made of. + struct Change + { + QString path; + std::optional<QByteArray> before; + std::optional<QByteArray> after; + }; + /// Applies `changes` in order through CalendarWriter. On a failure the + /// ones already applied are rolled back and the reason is reported. + bool applyChanges(const QList<Change> &changes, bool reverse); + +protected: + void closeEvent(QCloseEvent *event) override; + +private: + void buildUi(); + void buildActions(); + void reload(); + void rebuildItems(); + void refreshToolbar(); + void select(int item); + void startEdit(); + void startNew(const QDate &day); + QDate defaultNewDay() const; + bool save(); + void cancelEdit(); + void deleteSelected(); + bool writeAndRecord(const QString &label, const QList<Change> &changes); + void checkAfterSync(); + const CalCollection *collection(const QString &dir) const; + QList<CalCollection> writableCollections() const; + QString defaultCollection() const; + void status(const QString &text); + + Config m_config; + QStringList m_ownAddresses; + QString m_uiStatePath; + + LoadResult m_data; + QList<CalendarItem> m_items; + int m_year; + int m_month; + int m_selected = -1; + QString m_selectedUid; ///< survives a reload + QDateTime m_selectedStart; + + // The open edit. m_editPath empty with m_editing: a new event. + QString m_editPath; + QByteArray m_editBase; + bool m_editWholeSeries = true; + QDateTime m_editRecurrenceId; + + QUndoStack m_undo; + CalendarSync *m_sync; + QFileSystemWatcher m_watcher; + QTimer m_reloadTimer; + /// Written since the last sync started: path to the text written, or + /// nullopt for a deletion. Checked by meaning after the next sync. + QHash<QString, std::optional<QByteArray>> m_written; + QHash<QString, std::optional<QByteArray>> m_checking; + + QComboBox *m_collectionBox; + QComboBox *m_monthBox; + QSpinBox *m_yearSpin; + QToolButton *m_monthButton; + QToolButton *m_agendaButton; + QStackedWidget *m_views; + MonthView *m_monthView; + AgendaView *m_agendaView; + EventPane *m_pane; + QLabel *m_dataWarning; +}; +``` + +- [ ] **Step 3: Run to verify the tests fail** + +Run: `cmake --build build 2>&1 | tail -3` +Expected: link failure for `CalendarWindow`. + +- [ ] **Step 4: Write `src/calendarwindow.cpp`** + +The undo command first, then the window. It is long; the reviewer should read it against the spec's "Writing" and "The window" sections line by line. + +```cpp +/* GPLv2 header */ + +#include "calendarwindow.h" +#include "agendaview.h" +#include "calendarstore.h" +#include "calendarsync.h" +#include "calendarwriter.h" +#include "eventpane.h" +#include "monthview.h" + +#include <QButtonGroup> +#include <QCloseEvent> +#include <QComboBox> +#include <QDir> +#include <QFile> +#include <QFileInfo> +#include <QHBoxLayout> +#include <QLabel> +#include <QLocale> +#include <QMenuBar> +#include <QMessageBox> +#include <QPainter> +#include <QPixmap> +#include <QPushButton> +#include <QSettings> +#include <QSpinBox> +#include <QSplitter> +#include <QStackedWidget> +#include <QStatusBar> +#include <QTimeZone> +#include <QToolBar> +#include <QToolButton> +#include <QUndoCommand> + +namespace { + +/// One undoable write. The write itself happened before the push, so the +/// first redo() (which QUndoStack::push calls) does nothing. Undo restores +/// exactly the bytes the write replaced, expecting on disk exactly the bytes +/// it wrote: a sync in between makes it refuse, and the command is dropped. +class FileCommand : public QUndoCommand +{ +public: + FileCommand(const QString &text, const QList<CalendarWindow::Change> &changes, + CalendarWindow *window) + : QUndoCommand(text), m_changes(changes), m_window(window) {} + + void undo() override + { + if (!m_window->applyChanges(m_changes, true)) + setObsolete(true); + } + + void redo() override + { + if (m_first) { + m_first = false; + return; + } + if (!m_window->applyChanges(m_changes, false)) + setObsolete(true); + } + +private: + QList<CalendarWindow::Change> m_changes; + CalendarWindow *m_window; + bool m_first = true; +}; + +QIcon swatch(const QColor &colour) +{ + QPixmap pixmap(12, 12); + pixmap.fill(Qt::transparent); + QPainter(&pixmap).fillRect(pixmap.rect(), colour); + return QIcon(pixmap); +} + +QByteArray readFile(const QString &path) +{ + QFile f(path); + return f.open(QIODevice::ReadOnly) ? f.readAll() : QByteArray(); +} + +} // namespace + +CalendarWindow::CalendarWindow(const Config &config, const QStringList &ownAddresses, + const QString &uiStatePath, QWidget *parent) + : QMainWindow(parent), m_config(config), m_ownAddresses(ownAddresses), + m_uiStatePath(uiStatePath), + m_year(QDate::currentDate().year()), m_month(QDate::currentDate().month()) +{ + setWindowTitle(tr("Calendar")); + m_sync = new CalendarSync(m_config.calendarSyncCommand(), + m_config.calendarSyncDelayMs(), this); + connect(m_sync, &CalendarSync::started, this, [this]() { + status(tr("Syncing calendars...")); + m_checking.insert(m_written); // insert(QHash) merges + m_written.clear(); + }); + connect(m_sync, &CalendarSync::finished, this, [this](bool ok, const QString &output) { + if (!ok) { + QMessageBox::warning(this, tr("Calendar sync failed"), output); + status(tr("Calendar sync failed.")); + } + checkAfterSync(); + }); + + m_reloadTimer.setSingleShot(true); + m_reloadTimer.setInterval(500); + connect(&m_reloadTimer, &QTimer::timeout, this, &CalendarWindow::reload); + connect(&m_watcher, &QFileSystemWatcher::directoryChanged, this, + [this]() { m_reloadTimer.start(); }); + + buildUi(); + buildActions(); + + QSettings state(m_uiStatePath, QSettings::IniFormat); + state.beginGroup(QStringLiteral("calendar")); + restoreGeometry(state.value(QStringLiteral("geometry")).toByteArray()); + const bool agenda = state.value(QStringLiteral("agenda"), false).toBool(); + const QString collectionDir = state.value(QStringLiteral("collection")).toString(); + state.endGroup(); + + reload(); + const int index = m_collectionBox->findData(collectionDir); + if (index >= 0) + m_collectionBox->setCurrentIndex(index); + (agenda ? m_agendaButton : m_monthButton)->click(); +} + +CalendarWindow::~CalendarWindow() = default; + +void CalendarWindow::buildUi() +{ + auto *toolbar = addToolBar(tr("Calendar")); + toolbar->setObjectName(QStringLiteral("calendarToolbar")); + toolbar->setMovable(false); + + m_collectionBox = new QComboBox(this); + m_collectionBox->setObjectName(QStringLiteral("collectionBox")); + toolbar->addWidget(m_collectionBox); + toolbar->addSeparator(); + + auto addButton = [&](const QString &text, auto slot) { + auto *b = new QToolButton(this); + b->setText(text); + connect(b, &QToolButton::clicked, this, slot); + toolbar->addWidget(b); + return b; + }; + addButton(QStringLiteral("‹"), [this]() { + const QDate d = QDate(m_year, m_month, 1).addMonths(-1); + showMonth(d.year(), d.month()); + })->setToolTip(tr("Previous month")); + addButton(tr("Today"), [this]() { + showMonth(QDate::currentDate().year(), QDate::currentDate().month()); + m_agendaView->scrollToDay(QDate::currentDate()); + })->setToolTip(tr("Go to today")); + addButton(QStringLiteral("›"), [this]() { + const QDate d = QDate(m_year, m_month, 1).addMonths(1); + showMonth(d.year(), d.month()); + })->setToolTip(tr("Next month")); + + m_monthBox = new QComboBox(this); + for (int m = 1; m <= 12; ++m) + m_monthBox->addItem(QLocale().standaloneMonthName(m), m); + toolbar->addWidget(m_monthBox); + m_yearSpin = new QSpinBox(this); + m_yearSpin->setRange(1900, 2200); + toolbar->addWidget(m_yearSpin); + connect(m_monthBox, &QComboBox::activated, this, + [this](int index) { showMonth(m_year, index + 1); }); + connect(m_yearSpin, &QSpinBox::valueChanged, this, [this](int year) { + if (year != m_year) + showMonth(year, m_month); + }); + + auto *spacer = new QWidget(this); + spacer->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Preferred); + toolbar->addWidget(spacer); + + m_monthButton = new QToolButton(this); + m_monthButton->setText(tr("Month")); + m_monthButton->setCheckable(true); + m_agendaButton = new QToolButton(this); + m_agendaButton->setText(tr("Agenda")); + m_agendaButton->setCheckable(true); + auto *group = new QButtonGroup(this); + group->addButton(m_monthButton, 0); + group->addButton(m_agendaButton, 1); + toolbar->addWidget(m_monthButton); + toolbar->addWidget(m_agendaButton); + + auto *splitter = new QSplitter(this); + m_views = new QStackedWidget(splitter); + m_monthView = new MonthView(m_views); + m_agendaView = new AgendaView(m_views); + m_views->addWidget(m_monthView); + m_views->addWidget(m_agendaView); + m_pane = new EventPane(splitter); + splitter->addWidget(m_views); + splitter->addWidget(m_pane); + splitter->setStretchFactor(0, 3); + splitter->setStretchFactor(1, 1); + setCentralWidget(splitter); + + m_dataWarning = new QLabel(this); + statusBar()->addPermanentWidget(m_dataWarning); + + connect(group, &QButtonGroup::idClicked, m_views, &QStackedWidget::setCurrentIndex); + connect(m_collectionBox, &QComboBox::currentIndexChanged, this, &CalendarWindow::rebuildItems); + connect(m_monthView, &MonthView::itemClicked, this, &CalendarWindow::select); + connect(m_agendaView, &AgendaView::itemClicked, this, &CalendarWindow::select); + connect(m_monthView, &MonthView::dayDoubleClicked, this, &CalendarWindow::startNew); + connect(m_monthView, &MonthView::moreClicked, this, [this](const QDate &day) { + m_agendaButton->click(); + m_agendaView->scrollToDay(day); + }); + connect(m_pane, &EventPane::editRequested, this, &CalendarWindow::startEdit); + connect(m_pane, &EventPane::deleteRequested, this, &CalendarWindow::deleteSelected); + connect(m_pane, &EventPane::saveRequested, this, &CalendarWindow::save); + connect(m_pane, &EventPane::cancelRequested, this, &CalendarWindow::cancelEdit); +} +``` + +The actions. **The shortcut contexts are load-bearing.** A `QAction` shortcut is dispatched before the focused widget sees the key (AGENTS.md), so a window-wide `Delete` would delete the EVENT while the user deletes a character in the Title field, `Ctrl+Z` would undo a file write instead of a typo, and `PgUp`/`Home` would change month from inside the Notes box. Those actions are therefore added to the views widget with `Qt::WidgetWithChildrenShortcut`, so they fire only when focus is in the grid or the list. The menu entries still work from anywhere, because a menu triggers the action directly. + +```cpp +void CalendarWindow::buildActions() +{ + auto make = [this](const QString &name, const QString &text, const QKeySequence &key, + QWidget *scope, auto slot) { + auto *a = new QAction(text, this); + a->setObjectName(name); + a->setShortcut(key); + if (scope) { + a->setShortcutContext(Qt::WidgetWithChildrenShortcut); + scope->addAction(a); + } else { + addAction(a); + } + connect(a, &QAction::triggered, this, slot); + return a; + }; + + QAction *newEvent = make(QStringLiteral("newEvent"), tr("&New event"), + QKeySequence(Qt::CTRL | Qt::Key_N), nullptr, + [this]() { startNew(defaultNewDay()); }); + QAction *close = make(QStringLiteral("closeCalendar"), tr("&Close"), + QKeySequence(Qt::CTRL | Qt::Key_W), nullptr, [this]() { this->close(); }); + QAction *edit = make(QStringLiteral("editEvent"), tr("&Edit event"), + QKeySequence(Qt::CTRL | Qt::Key_E), nullptr, &CalendarWindow::startEdit); + QAction *del = make(QStringLiteral("deleteEvent"), tr("&Delete event"), + QKeySequence(Qt::Key_Delete), m_views, &CalendarWindow::deleteSelected); + QAction *cancel = make(QStringLiteral("cancelEdit"), tr("Cancel &editing"), + QKeySequence(Qt::Key_Escape), m_pane, &CalendarWindow::cancelEdit); + + QAction *undo = m_undo.createUndoAction(this, tr("&Undo")); + undo->setShortcut(QKeySequence::Undo); + undo->setShortcutContext(Qt::WidgetWithChildrenShortcut); + m_views->addAction(undo); + QAction *redo = m_undo.createRedoAction(this, tr("&Redo")); + redo->setShortcut(QKeySequence(Qt::CTRL | Qt::SHIFT | Qt::Key_Z)); + redo->setShortcutContext(Qt::WidgetWithChildrenShortcut); + m_views->addAction(redo); + + QAction *prev = make(QStringLiteral("previousMonth"), tr("&Previous month"), + QKeySequence(Qt::Key_PageUp), m_views, [this]() { + const QDate d = QDate(m_year, m_month, 1).addMonths(-1); + showMonth(d.year(), d.month()); + }); + QAction *next = make(QStringLiteral("nextMonth"), tr("&Next month"), + QKeySequence(Qt::Key_PageDown), m_views, [this]() { + const QDate d = QDate(m_year, m_month, 1).addMonths(1); + showMonth(d.year(), d.month()); + }); + QAction *today = make(QStringLiteral("today"), tr("&Today"), + QKeySequence(Qt::Key_Home), m_views, [this]() { + showMonth(QDate::currentDate().year(), QDate::currentDate().month()); + }); + QAction *month = make(QStringLiteral("monthView"), tr("&Month"), {}, nullptr, + [this]() { m_monthButton->click(); }); + QAction *agenda = make(QStringLiteral("agendaView"), tr("&Agenda"), {}, nullptr, + [this]() { m_agendaButton->click(); }); + + QMenu *file = menuBar()->addMenu(tr("&File")); + file->addAction(newEvent); + file->addSeparator(); + file->addAction(close); + QMenu *editMenu = menuBar()->addMenu(tr("&Edit")); + editMenu->addAction(undo); + editMenu->addAction(redo); + editMenu->addSeparator(); + editMenu->addAction(edit); + editMenu->addAction(del); + editMenu->addAction(cancel); + QMenu *view = menuBar()->addMenu(tr("&View")); + view->addAction(month); + view->addAction(agenda); + view->addSeparator(); + view->addAction(prev); + view->addAction(next); + view->addAction(today); +} +``` + +```cpp +/// Where + New puts an event: today when today is in the shown month, +/// otherwise the month's first day, so the new event is on screen. +QDate CalendarWindow::defaultNewDay() const +{ + const QDate first(m_year, m_month, 1); + const QDate today = QDate::currentDate(); + return today >= first && today < first.addMonths(1) ? today : first; +} + +void CalendarWindow::showMonth(int year, int month) +{ + m_year = year; + m_month = month; + m_monthView->setMonth(year, month); + refreshToolbar(); + rebuildItems(); +} + +void CalendarWindow::refreshToolbar() +{ + const QSignalBlocker a(m_monthBox), b(m_yearSpin); + m_monthBox->setCurrentIndex(m_month - 1); + m_yearSpin->setValue(m_year); +} + +void CalendarWindow::reload() +{ + m_data = CalendarStore::load(m_config.calendarsDir()); + + if (!m_watcher.directories().isEmpty()) + m_watcher.removePaths(m_watcher.directories()); + QStringList dirs{ m_config.calendarsDir() }; + for (const CalCollection &c : m_data.collections) + dirs << c.path; + m_watcher.addPaths(dirs); + + const QString current = m_collectionBox->currentData().toString(); + { + const QSignalBlocker block(m_collectionBox); + m_collectionBox->clear(); + m_collectionBox->addItem(tr("All calendars"), QString()); + for (const CalCollection &c : m_data.collections) + m_collectionBox->addItem(swatch(c.color), c.displayName, c.dir); + m_collectionBox->setCurrentIndex(qMax(0, m_collectionBox->findData(current))); + } + + QStringList warnings; + if (m_data.unparsable) + warnings << tr("%n file(s) could not be read", nullptr, m_data.unparsable); + if (m_data.unknownZones) + warnings << tr("%n event(s) in an unknown time zone, shown in local time", nullptr, + m_data.unknownZones); + m_dataWarning->setText(warnings.join(QStringLiteral("; "))); + rebuildItems(); +} + +void CalendarWindow::rebuildItems() +{ + const QString filter = m_collectionBox->currentData().toString(); + const QDateTime from(m_monthView->firstDay(), QTime(0, 0)); + const QDateTime to(m_monthView->lastDay(), QTime(0, 0)); + m_items.clear(); + for (const Occurrence &o : CalendarStore::occurrences(m_data.events, from, to)) { + const CalEvent &e = m_data.events[o.eventIndex]; + if (!filter.isEmpty() && e.collectionDir != filter) + continue; + const CalCollection *c = collection(e.collectionDir); + QString title = o.isOverride ? e.overrides[o.overrideIndex].summary : e.summary; + if (title.isEmpty()) + title = tr("(no title)"); + m_items.append({ o, title, c ? c->color : QColor(Qt::gray) }); + } + m_monthView->setItems(m_items); + + // The agenda covers the month the toolbar names, not the grid's + // spill-over. Out-of-month items become blanks, which AgendaView skips, + // so a row's index is the same index the month grid reports. + // ponytail: blanks rather than an index map; add the map if the agenda + // ever needs a range of its own. + const QDate first(m_year, m_month, 1); + QList<CalendarItem> agenda; + for (const CalendarItem &item : m_items) { + const QDate d = item.occurrence.start.toLocalTime().date(); + agenda.append(d >= first && d < first.addMonths(1) ? item : CalendarItem{}); + } + m_agendaView->setItems(agenda); + + // Re-find the selection by identity: a reload renumbers everything. + m_selected = -1; + for (int i = 0; i < m_items.size(); ++i) { + const Occurrence &o = m_items[i].occurrence; + if (m_data.events[o.eventIndex].uid == m_selectedUid + && (!m_selectedStart.isValid() || o.start == m_selectedStart)) { + m_selected = i; + break; + } + } + m_monthView->setSelected(m_selected); + m_agendaView->setSelected(m_selected); + if (!m_pane->isEditing()) { + if (m_selected >= 0) { + const Occurrence &o = m_items[m_selected].occurrence; + const CalEvent &e = m_data.events[o.eventIndex]; + const CalCollection *c = collection(e.collectionDir); + m_pane->showDetails(e, c ? *c : CalCollection{}, o, + c && CalendarStore::isEditable(e, *c, m_ownAddresses)); + } else { + m_pane->showNothing(); + } + } +} +``` + +```cpp +void CalendarWindow::select(int item) +{ + if (m_pane->isEditing()) { + status(tr("Save or cancel the event being edited first.")); + return; + } + if (item < 0 || item >= m_items.size()) + return; + const Occurrence &o = m_items[item].occurrence; + m_selectedUid = m_data.events[o.eventIndex].uid; + m_selectedStart = o.start; + rebuildItems(); +} + +bool CalendarWindow::selectEvent(const QString &uid, const QDateTime &start) +{ + if (m_pane->isEditing()) + return false; + for (int i = 0; i < m_items.size(); ++i) { + const Occurrence &o = m_items[i].occurrence; + if (m_data.events[o.eventIndex].uid == uid && (!start.isValid() || o.start == start)) { + select(i); + return true; + } + } + return false; +} + +QString CalendarWindow::selectedUid() const +{ + return m_selected >= 0 ? m_data.events[m_items[m_selected].occurrence.eventIndex].uid : QString(); +} + +bool CalendarWindow::isEditing() const { return m_pane->isEditing(); } + +const CalCollection *CalendarWindow::collection(const QString &dir) const +{ + for (const CalCollection &c : m_data.collections) + if (c.dir == dir) + return &c; + return nullptr; +} + +QList<CalCollection> CalendarWindow::writableCollections() const +{ + QList<CalCollection> result; + for (const CalCollection &c : m_data.collections) + if (!c.readOnly) + result.append(c); + return result; +} + +QString CalendarWindow::defaultCollection() const +{ + const QList<CalCollection> writable = writableCollections(); + for (const CalCollection &c : writable) + if (c.dir == m_config.defaultCalendar()) + return c.dir; + return writable.isEmpty() ? QString() : writable.first().dir; +} + +void CalendarWindow::startEdit() +{ + if (m_pane->isEditing() || m_selected < 0) + return; + const Occurrence &o = m_items[m_selected].occurrence; + const CalEvent &e = m_data.events[o.eventIndex]; + const CalCollection *c = collection(e.collectionDir); + if (!c || !CalendarStore::isEditable(e, *c, m_ownAddresses)) + return; + + // A repeating event asks its scope when Edit is pressed, never after. + m_editWholeSeries = true; + m_editRecurrenceId = {}; + if (e.repeat.freq != RepeatRule::Freq::None || e.repeat.custom) { + QMessageBox box(QMessageBox::Question, tr("Edit a repeating event"), + tr("Edit only this occurrence, or every occurrence?"), + QMessageBox::Cancel, this); + QPushButton *one = box.addButton(tr("This occurrence"), QMessageBox::AcceptRole); + QPushButton *all = box.addButton(tr("All occurrences"), QMessageBox::AcceptRole); + box.exec(); + if (box.clickedButton() != one && box.clickedButton() != all) + return; + m_editWholeSeries = box.clickedButton() == all; + m_editRecurrenceId = o.recurrenceId; + } + + EventEdit initial; + const CalOverride *ov = o.isOverride ? &e.overrides[o.overrideIndex] : nullptr; + initial.summary = ov ? ov->summary : e.summary; + initial.location = ov ? ov->location : e.location; + initial.description = ov ? ov->description : e.description; + initial.allDay = m_editWholeSeries ? e.allDay : o.allDay; + initial.start = m_editWholeSeries ? e.start : o.start; + initial.end = m_editWholeSeries ? e.end : o.end; + initial.repeat = e.repeat; + initial.collectionDir = e.collectionDir; + + QStringList people; + for (const CalPerson &a : e.attendees) + people << (a.name.isEmpty() ? a.address : a.name); + + m_editPath = e.filePath; + m_editBase = e.rawText; + m_pane->startEdit(initial, writableCollections(), m_editWholeSeries, m_editWholeSeries, + e.hasAlarm ? tr("Kept as set elsewhere") : tr("None"), + people.join(QStringLiteral(", "))); +} + +void CalendarWindow::startNew(const QDate &day) +{ + if (m_pane->isEditing() || defaultCollection().isEmpty()) + return; + EventEdit initial; + initial.start = QDateTime(day, QTime(9, 0)); + initial.end = initial.start.addSecs(3600); + initial.collectionDir = defaultCollection(); + m_editPath.clear(); + m_editBase.clear(); + m_editWholeSeries = true; + m_editRecurrenceId = {}; + m_pane->startEdit(initial, writableCollections(), true, true, tr("None"), QString()); +} + +bool CalendarWindow::save() +{ + const EventEdit edit = m_pane->edit(); + const CalCollection *target = collection(edit.collectionDir); + if (!target) + return false; + QList<Change> changes; + QString label; + + if (m_editPath.isEmpty()) { + const QByteArray text = CalendarStore::newEvent(edit, QTimeZone::systemTimeZoneId()); + bool ignored = false; + const QString uid = CalendarStore::parseEvent(text, {}, {}, &ignored).uid; + changes.append({ target->path + QLatin1Char('/') + uid + QStringLiteral(".ics"), + std::nullopt, text }); + label = tr("New event"); + } else { + const QByteArray text = CalendarStore::applyEdit( + m_editBase, edit, + m_editWholeSeries ? CalendarStore::Scope::All : CalendarStore::Scope::ThisOccurrence, + m_editRecurrenceId); + if (text.isEmpty()) + return false; + const QString newPath = target->path + QLatin1Char('/') + QFileInfo(m_editPath).fileName(); + if (newPath == m_editPath) { + changes.append({ m_editPath, m_editBase, text }); + } else { + // Moving to another calendar: the new file first, then the old + // one removed, so a failure between them duplicates rather than + // loses the event. + changes.append({ newPath, std::nullopt, text }); + changes.append({ m_editPath, m_editBase, std::nullopt }); + } + label = tr("Edit event"); + } + + if (!writeAndRecord(label, changes)) + return false; // the form stays open with the user's values + m_pane->stopEdit(); + bool ignored = false; + m_selectedUid = CalendarStore::parseEvent(*changes.first().after, {}, {}, &ignored).uid; + m_selectedStart = {}; + reload(); + return true; +} + +void CalendarWindow::cancelEdit() +{ + if (!m_pane->isEditing()) + return; + m_pane->stopEdit(); + rebuildItems(); +} + +void CalendarWindow::deleteSelected() +{ + if (m_pane->isEditing() || m_selected < 0) + return; + const Occurrence &o = m_items[m_selected].occurrence; + const CalEvent &e = m_data.events[o.eventIndex]; + const CalCollection *c = collection(e.collectionDir); + if (!c || !CalendarStore::isEditable(e, *c, m_ownAddresses)) + return; + + // No confirmation: the delete is undoable (spec decision 14). A repeating + // event asks its SCOPE, which is a choice, not a confirmation. + std::optional<QByteArray> after = std::nullopt; + if (e.repeat.freq != RepeatRule::Freq::None || e.repeat.custom) { + QMessageBox box(QMessageBox::Question, tr("Delete a repeating event"), + tr("Delete only this occurrence, or every occurrence?"), + QMessageBox::Cancel, this); + QPushButton *one = box.addButton(tr("This occurrence"), QMessageBox::AcceptRole); + QPushButton *all = box.addButton(tr("All occurrences"), QMessageBox::AcceptRole); + box.exec(); + if (box.clickedButton() == one) + after = CalendarStore::deleteOccurrence(e.rawText, o.recurrenceId); + else if (box.clickedButton() != all) + return; + } + if (writeAndRecord(tr("Delete event"), { { e.filePath, e.rawText, after } })) { + m_selectedUid.clear(); + reload(); + } +} + +bool CalendarWindow::applyChanges(const QList<Change> &changes, bool reverse) +{ + QList<Change> done; + for (int i = 0; i < changes.size(); ++i) { + const Change &c = changes[reverse ? changes.size() - 1 - i : i]; + const auto from = reverse ? c.after : c.before; + const auto to = reverse ? c.before : c.after; + QString error; + const CalendarWriter::Result r = CalendarWriter::replace(c.path, from, to, &error); + if (r != CalendarWriter::Result::Ok) { + // Roll back what this call already did, newest first. + // ponytail: best effort; a rollback that itself fails is reported + // by the file being wrong on the next reload, not handled here. + for (int j = done.size() - 1; j >= 0; --j) { + QString ignored; + CalendarWriter::replace(done[j].path, done[j].after, done[j].before, &ignored); + } + status(r == CalendarWriter::Result::Stale + ? tr("The event changed on disk, probably from a sync. Check it and try again.") + : tr("Could not write the calendar: %1").arg(error)); + reload(); + return false; + } + done.append({ c.path, from, to }); + m_written.insert(c.path, to); + } + m_sync->schedule(); + m_reloadTimer.start(); + return true; +} + +bool CalendarWindow::writeAndRecord(const QString &label, const QList<Change> &changes) +{ + if (!applyChanges(changes, false)) + return false; + m_undo.push(new FileCommand(label, changes, this)); + return true; +} + +void CalendarWindow::checkAfterSync() +{ + // Compared by MEANING: the server may normalise the text on the round + // trip, and a byte comparison would warn on every save. + QStringList lost; + for (auto it = m_checking.cbegin(); it != m_checking.cend(); ++it) { + const bool exists = QFile::exists(it.key()); + const bool kept = it.value() + ? exists && CalendarStore::sameMeaning(readFile(it.key()), *it.value()) + : !exists; + if (!kept) { + bool ignored = false; + const QString title = it.value() + ? CalendarStore::parseEvent(*it.value(), {}, {}, &ignored).summary + : QFileInfo(it.key()).completeBaseName(); + lost << title; + } + } + m_checking.clear(); + status(lost.isEmpty() + ? tr("Calendars synced.") + : tr("The server kept a different version of: %1").arg(lost.join(QStringLiteral(", ")))); +} + +void CalendarWindow::status(const QString &text) +{ + statusBar()->showMessage(text, 10000); +} + +void CalendarWindow::closeEvent(QCloseEvent *event) +{ + // A QMainWindow, not a QDialog, so every route out (the title bar, the + // File menu, close()) arrives here; AGENTS.md's QDialog trap does not + // apply, but the test still drives two routes. + if (m_pane->isDirty()) { + const auto answer = QMessageBox::question( + this, tr("Unsaved event"), tr("Save the changes to this event?"), + QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel, QMessageBox::Save); + if (answer == QMessageBox::Cancel || (answer == QMessageBox::Save && !save())) { + event->ignore(); + return; + } + m_pane->stopEdit(); + } + QDir().mkpath(QFileInfo(m_uiStatePath).absolutePath()); + QSettings state(m_uiStatePath, QSettings::IniFormat); + state.beginGroup(QStringLiteral("calendar")); + state.setValue(QStringLiteral("geometry"), saveGeometry()); + state.setValue(QStringLiteral("agenda"), m_views->currentIndex() == 1); + state.setValue(QStringLiteral("collection"), m_collectionBox->currentData().toString()); + state.endGroup(); + QMainWindow::closeEvent(event); +} +``` + +Two things to confirm while implementing rather than trust: `QHash::insert(const QHash &)` exists in Qt 6 (it does from 6.0; otherwise loop), and `QTimeZone::systemTimeZoneId()` returns an IANA id on this system (`Europe/Rome`), which `newEvent` needs for its VTIMEZONE. + +- [ ] **Step 5: Run the tests** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_calendarwindow` +Expected: all PASS. A hang means a message box appeared that no test answered: the scope question for a repeating event, most likely, which none of these fixtures should trigger. + +- [ ] **Step 6: Mutation-check the two data-safety tests** + +Per AGENTS.md, a test that cannot fail proves nothing. Temporarily: +1. In `CalendarWriter::replace`, change `if (current.readAll() != *expected)` to `if (false)`. Run `test_calendarwindow`: `aStaleSaveKeepsTheFormAndTheSyncedFile` must FAIL. Revert. +2. In `FileCommand::undo`, make it return without calling `applyChanges`. `saveWritesAndUndoRestoresTheOriginalBytes` must FAIL. Revert. + +- [ ] **Step 7: Commit** + +```bash +git add src/calendarwindow.h src/calendarwindow.cpp src/CMakeLists.txt \ + tests/CMakeLists.txt tests/test_calendarwindow.cpp +git commit -m "feat: the calendar window, with undo and a stale-safe save" +``` + +--- + +### Task 15: Opening the calendar from the main window + +**Files:** +- Modify: `src/keymap.cpp` (`knownActions`) +- Modify: `src/mainwindow.h`, `src/mainwindow.cpp` (action, icon, View menu, toolbar, open, close) +- Test: `tests/test_mainwindow.cpp` + +- [ ] **Step 1: Write the failing test** + +```cpp + void theCalendarActionWithNoCalendarOpensNothing(); +``` + +```cpp +void TestMainWindow::theCalendarActionWithNoCalendarOpensNothing() +{ + // The default test config sets no calendars_dir: the feature is off. + MainWindow window(Config{}); + QAction *action = window.findChild<QAction *>(QStringLiteral("calendar")); + QVERIFY(action); + action->trigger(); + const QWidgetList tops = QApplication::topLevelWidgets(); + QVERIFY(std::none_of(tops.cbegin(), tops.cend(), [](QWidget *w) { + return qobject_cast<CalendarWindow *>(w) != nullptr; + })); +} +``` + +Check how the other `test_mainwindow` cases build a window (they may use a fixture config rather than `Config{}`) and follow them. Check also how `MainWindow::addAction` names its QActions; if it does not set `objectName`, find the action through the map the tests already use. Add `#include "calendarwindow.h"`. + +- [ ] **Step 2: Run to verify it fails** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_mainwindow theCalendarActionWithNoCalendarOpensNothing` +Expected: FAIL, no `calendar` action. + +- [ ] **Step 3: Register the action in all five places** + +1. `src/keymap.cpp`, `knownActions()`, after `QStringLiteral("tag_rules"),`: + +```cpp + // Item 206. No default chord: the calendar is opened from the View + // menu and the toolbar, and a shortcut is a chosen subset (item 132). + QStringLiteral("calendar"), +``` + +2. `defaultBindings()`: no entry, deliberately. + +3. The icon table in `mainwindow.cpp`, beside `tag_rules`: + +```cpp + { QStringLiteral("calendar"), { QStringLiteral("x-office-calendar"), QString() } }, +``` + +4. `addAction` beside `tag_rules`: + +```cpp + addAction(QStringLiteral("calendar"), tr("&Calendar"), + tr("Open the calendar"), [this]() { + openCalendar(); + }); +``` + +5. The View menu, after `zoom_reset`, and the main toolbar after `mark_all_read`: + +```cpp + viewMenu->addSeparator(); + viewMenu->addAction(m_actions.value(QStringLiteral("calendar"))); +``` + +```cpp + toolBar->addAction(m_actions.value(QStringLiteral("calendar"))); +``` + +- [ ] **Step 4: Open it, once, and close it with the main window** + +`src/mainwindow.h`: forward-declare `class CalendarWindow;`, add `void openCalendar();` to the private functions and `QPointer<CalendarWindow> m_calendar;` beside `m_composers`. + +`src/mainwindow.cpp`: + +```cpp +void MainWindow::openCalendar() +{ + if (m_config.calendarsDir().isEmpty()) { + statusBar()->showMessage( + tr("No calendar is configured: set calendars_dir under [general]."), 10000); + return; + } + if (m_calendar) { + m_calendar->raise(); + m_calendar->activateWindow(); + return; + } + QStringList own; + for (const Account &account : m_config.accounts()) + if (!account.address.isEmpty()) + own << account.address; + // Parentless, like a composer: its own entry in the task switcher. + m_calendar = new CalendarWindow(m_config, own, uiStatePath()); + m_calendar->setAttribute(Qt::WA_DeleteOnClose); + m_calendar->show(); +} +``` + +If the status bar is reached through a member (`m_statusLabel`, AGENTS.md) rather than `statusBar()`, use the same route the neighbouring code uses for a transient message. + +In `MainWindow::closeEvent`, directly after the `m_syncingForExit` guard and BEFORE the first prompt, so a Cancel in the calendar's own prompt stops the quit before anything else is asked: + +```cpp + // The calendar is parentless, so Qt would leave it open with nothing + // behind it (the composer precedent above). Its own closeEvent asks about + // an unsaved event; a Cancel there cancels the quit. + if (m_calendar) { + m_calendar->close(); + if (m_calendar && m_calendar->isVisible()) { + event->ignore(); + return; + } + } +``` + +- [ ] **Step 5: Run the whole main-window suite** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_mainwindow` +Expected: the new test PASSES, and so do `everyActionIsReachableFromAMenu`, the icon-uniqueness test and the `KeyMap` constructor assert, which are the other three of the five places. `undoMovesTheMessageBack` fails as before; nothing else may. + +- [ ] **Step 6: Commit** + +```bash +git add src/keymap.cpp src/mainwindow.h src/mainwindow.cpp tests/test_mainwindow.cpp +git commit -m "feat: open the calendar from the View menu and the toolbar" +``` + +--- + +### Task 16: Translation, documentation, backlog, and the live check + +**Files:** +- Modify: `translations/qtmaildir_it_IT.ts`, `README.md`, `CHANGELOG.md`, `AGENTS.md` +- Modify: `docs/superpowers/specs/2026-09-24-calendar-design.md` (the rulings) +- Modify: `docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md` +- Test: `tests/test_calendarstore.cpp` (the opt-in live check) + +- [ ] **Step 1: The read-only live check** + +Add to `test_calendarstore.cpp`: + +```cpp + void theLiveVdirLoadsCleanly(); +``` + +```cpp +void TestCalendarStore::theLiveVdirLoadsCleanly() +{ + // Opt-in, READ-ONLY: never writes. Run by hand before handing the build + // over: QTMAILDIR_LIVE_CALENDARS=~/.local/share/calendars ./test_calendarstore + const QString dir = qEnvironmentVariable("QTMAILDIR_LIVE_CALENDARS"); + if (dir.isEmpty()) + QSKIP("QTMAILDIR_LIVE_CALENDARS not set"); + const LoadResult r = CalendarStore::load(dir); + qInfo("collections=%lld events=%lld unparsable=%d unknownZones=%d", + qlonglong(r.collections.size()), qlonglong(r.events.size()), + r.unparsable, r.unknownZones); + QCOMPARE(r.unparsable, 0); + const QList<Occurrence> year = CalendarStore::occurrences( + r.events, QDateTime(QDate(2026, 1, 1), QTime(0, 0)), + QDateTime(QDate(2027, 1, 1), QTime(0, 0))); + qInfo("occurrences in 2026=%lld", qlonglong(year.size())); +} +``` + +Run: `QTMAILDIR_LIVE_CALENDARS=$HOME/.local/share/calendars QT_QPA_PLATFORM=offscreen ./build/tests/test_calendarstore theLiveVdirLoadsCleanly` +Expected: PASS with `collections=3 events=312 unparsable=0`. Report the `unknownZones` and occurrence counts to the user; they are real measurements and belong in the hand-off (AGENTS.md: counts are not personal data). + +- [ ] **Step 2: Translate** + +Run: `lupdate-qt6 src/ -ts translations/qtmaildir_it_IT.ts -no-obsolete -locations none` +Expected: zero "tr() cannot be called without context" warnings. Translate every new entry in Italian, including BOTH plural forms of `+%n more`, `%n file(s) could not be read` and `%n event(s) in an unknown time zone...`, and the `RepeatRule` context's ordinals. +Run: `lrelease-qt6 translations/qtmaildir_it_IT.ts` +Expected: `0 unfinished`. +Run: `ctest --test-dir build -R translations --output-on-failure` +Expected: PASS. + +- [ ] **Step 3: README** + +Add a `## Calendar` section after the contact-completion section: what the window does (Month, Agenda, edit in the side pane, undo), that it reads a vdirsyncer vdir and needs no khal, that names and colours come from each collection's `displayname` and `color` files, which `vdirsyncer metasync` fills when the pair has `metadata = ["color", "displayname"]`, and that events organised by someone else are read-only. Document the four keys in the config reference table: + +| Key | Default | Meaning | +|---|---|---| +| `calendars_dir` | unset (off) | The vdir root, e.g. `~/.local/share/calendars/`. | +| `default_calendar` | first collection | Directory name new events go to. | +| `calendar_sync_command` | `flock -w 60 /tmp/vdirsyncer.lock vdirsyncer sync calendars` | Run after writes; empty disables. | +| `calendar_sync_delay_ms` | `2000` | Delay before it runs. | + +And the cron note: prefix the vdirsyncer cron line with the same `flock -w 60 /tmp/vdirsyncer.lock` so the two never run together; append `&& vdirsyncer metasync` to keep names and colours current. + +- [ ] **Step 4: CHANGELOG** + +Under `## [Unreleased]`, `### Added`: a calendar window (item 206) with the one-line summary; and `### Upgrading`: the calendar is off until `calendars_dir` is set, and the cron line wants the `flock` prefix. + +- [ ] **Step 5: AGENTS.md** + +Add `CalendarWindow` and `EventPane` to the list of widget classes; `CalendarStore`, `CalendarWriter` and `MonthLayout` to the namespaces paragraph; the diagram line `CalendarWindow (its own top-level window) ... CalendarStore (the only libical user)`. Then a section of the calendar's traps, each learned in this plan: + +- libical is confined to `calendarstore.cpp` behind `icalraii.h`, the nmraii rule. +- Expansion runs in the event's own zone: a weekly 10:00 Rome event is 10:00 on both sides of DST, so its UTC time moves. +- All-day `DTEND` is exclusive; the form shows the inclusive last day and converts. +- 120 of the user's files name a `TZID` without a `VTIMEZONE`; an edit must write the `TZID` parameter back, never convert. +- The calendar's `Delete`, `Ctrl+Z`, `PgUp`/`PgDn` and `Home` shortcuts are scoped to the views with `Qt::WidgetWithChildrenShortcut`, or they fire while the user types in the form. +- `calendar_sync_command` is read through a QStringList join, because QSettings splits a comma-holding value and `toString()` on the list is empty. + +- [ ] **Step 6: Amend the spec** + +In `docs/superpowers/specs/2026-09-24-calendar-design.md`: `Status: approved, implemented on branch calendar`; the config table's `calendars_dir` default becomes "unset (off)" (ruling 1); "byte for byte" becomes "value for value" in the Testing section (ruling 2); the atomic write names `QSaveFile`; the shortcut scoping is added under "Menus and keys". + +- [ ] **Step 7: Backlog** + +In the status table of `docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md`: +- 206's row: `open, **built on branch calendar** YYYY-MM-DD, awaiting hand test; spec specs/2026-09-24-calendar-design.md, plan plans/2026-09-24-calendar.md`. +- 205's row: append "its write-during-sync question is answered by 206's spec, § Writing: the same writer and stale check serve a vCard". +- New row 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.` +- New row 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.` +- Add sections `## 209.` and `## 210.` with Observed / Cause / Approach / Constraints, citing the spec. + +- [ ] **Step 8: Full suite** + +Run: `ctest --test-dir build --output-on-failure` +Expected: everything passes except the known pre-existing `test_mainwindow::undoMovesTheMessageBack` (and possibly the two order-dependent flakes; rerun those alone before calling anything a regression). + +- [ ] **Step 9: Commit** + +```bash +git add translations/qtmaildir_it_IT.ts README.md CHANGELOG.md AGENTS.md \ + docs/superpowers/specs/2026-09-24-calendar-design.md \ + docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md tests/test_calendarstore.cpp +git commit -m "docs: document the calendar, translate it, file its follow-ups" +``` + +- [ ] **Step 10: Hand over for the hand test** + +Do NOT launch the application (AGENTS.md). Tell the user the branch is ready, give the live-check counts, and say what to look at: +1. View > Calendar opens one window; a second trigger raises it. +2. The collection combo shows your three calendars with their server colours; "All calendars" first. +3. Today's pill; ‹ Today › and the month/year controls; PgUp/PgDn with the grid focused. +4. A birthday (yearly) and the monthly day-18 series fall where they should; a DST-crossing weekly event keeps its hour in late October. +5. Clicking an invitation someone else organised shows "Organised by ...: read-only" and no Edit/Delete. +6. Edit an event you organised: the form replaces the pane; the grid still navigates; clicking another event is refused with a hint; typing Delete or Ctrl+Z in the Title field edits the text, not the calendar. +7. Save; Ctrl+Z (grid focused) restores it; the status bar reports the sync and, after it, "Calendars synced." +8. + New and double-click on an empty day open a form in the default calendar. +9. Close with an unsaved edit: Save / Discard / Cancel. + +Merge `calendar` to master only after the user's verdict (memory: test before commit applies to the merge). |