1 +#
CalDAV Calendar Popup — Design Spec 4 +**Status:** Approved (brainstorming complete)
5 +**Goal:** Replace the crude clock popup calendar with a modern, minimal month-grid + today-agenda that renders the user's real CalDAV (Nextcloud) calendars read-only.
11 +The clock popout (`PopoutHost.qml` `clockContent`) currently shows a clock, a date line, a bare 7×6 rectangle grid, and one hardcoded agenda line. This replaces it with:
13 +- A month grid (6 weeks) showing real events as **dots** (timed single-day), **pills** (all-day single-day), and **spanning bands** (multi-day).
14 +- A **today agenda** listing today's events and due tasks.
15 +- Data pulled from Nextcloud CalDAV via `curl` (a new `CalDav.qml` service), parsed by an embedded Python script into JSON.
16 +- A **first-run setup popup** that captures server URL + username + app-password, persists the non-secret parts to a config file and the password to the system keyring.
17 +- Graceful degradation when the network, keyring, or `secret-tool` is unavailable.
19 +Read-only throughout: only `PROPFIND`, `REPORT`, `GET` are issued.
23 +##
2. Decisions (locked) 27 +| HTTP transport | `curl` via `Process` (Qt QML `XMLHttpRequest` rejects the `REPORT` verb — proven; see §11) |
28 +| Recurrence | Server-side `<C:expand>` in the `REPORT` — no client recurrence engine |
29 +| Service boundary | New `CalDav.qml` (network IO), separate from `Time.qml` (local clock) |
30 +| Calendars | All event calendars + Reminders (VTODO), color-coded per Nextcloud `calendar-color`; auto-discovered via PROPFIND (not hardcoded) |
31 +| Tasks (VTODO) | Shown: dot on due day + agenda row marked `○` (read-only) |
32 +| Config store | `Quickshell.statePath("caldav.json")` via `FileView` + `JsonAdapter` (matches `Usage.qml`/`Clipboard.qml`) |
33 +| Secret store | System keyring via `secret-tool` (gnome-keyring); key attributes `service=caldav host=<host-from-url>` |
34 +| Setup popup | Captures URL + username + app-password on first run / missing secret |
35 +| Layout | Stacked: month grid on top, today agenda below |
36 +| Weekday header | Single letter `M D M D F S S`, weekend dimmed (user override of two-letter recommendation) |
37 +| Event indicator (timed single-day) | Up to 2 colored dots (distinct calendars) + `+` overflow |
38 +| All-day single-day | Filled pill under the number, calendar color, label if it fits |
39 +| Multi-day | Translucent band + border across covered cells; per-week-row segmentation; lane stacking |
40 +| Failure UX | Graceful: clock+grid always render; keep last-good data; subtle stale indicator near date line; empty agenda → `Keine Termine` |
41 +| Refresh | Initial load + on popout open + periodic 15 min |
42 +| Timezone | Python emits UTC epoch ms (timed) / plain date string (all-day, task due); QML `new Date(ms)` localizes; never apply TZ math to all-day dates |
46 +##
3. Architecture & Data Flow 49 +gnome-keyring ──secret-tool lookup──┐
50 + │ (password, via stdin only)
51 +config (statePath caldav.json) ─────┤
52 + {url, username, calendars[]} ▼
53 + CalDav.qml (new service, DI from shell.qml)
54 + • Process: sh -c "curl REPORT… | python3 parse"
55 + • StdioCollector → JSON.parse → events[] / tasks[]
56 + • Timer(15min) + refresh() on popout open + initial
57 + • status: ok | offline | needs-setup
58 + • stateJson() (additive IPC contract)
59 + │ injected via shell.qml
61 + PopoutHost.qml clockContent (redesigned)
62 + • month grid (dots / pills / bands)
63 + • today agenda (events + tasks)
65 + PopoutHost setup popup (URL/user/password) ──writes──> config + keyring
68 +**Components & responsibilities**
70 +- **`CalDav.qml`** — owns all network IO and credential access. Discovers calendars (PROPFIND), fetches events/tasks (REPORT+expand), exposes parsed data and a status enum. No UI.
71 +- **`shell.qml`** — instantiates `CalDav`, injects it into `PopoutHost` (DI per [[nuguland-di-no-singleton]]); adds an IPC handler returning `caldav.stateJson()`.
72 +- **`PopoutHost.qml` `clockContent`** — pure view over `caldav` props; renders grid + agenda.
73 +- **`PopoutHost.qml` setup popup** — credential capture; writes config + stores secret; triggers `caldav.discoverAndFetch()`.
74 +- **Embedded Python parser** — string constant in `CalDav.qml` (mirrors the `desktopScanCode()` pattern in `Launcher.qml:511`), run as `python3 -c`.
78 +##
4. Config & Credentials 80 +###
4.1 Config file — `Quickshell.statePath("caldav.json")` 84 + "url":
"https://box.bugabinga.net/cloud/remote.php/dav",
85 + "username":
"oliver@bugabinga.net",
87 + {
"href":
"/cloud/remote.php/dav/calendars/oliver@bugabinga.net/personal/",
88 + "displayName":
"Oliver's Kalender",
"color":
"#5b8cff",
89 + "components": [
"VEVENT"],
"enabled":
true }
95 +- `url` is the CalDAV root (the `…/dav` base). Host for the keyring lookup is parsed from it.
96 +- `calendars[]` is populated by discovery (§5.1) and cached so the UI has colors before the first fetch returns. `enabled` lets a calendar be hidden by hand-editing.
97 +- `inbox`/`outbox`/`trashbin` (no `displayname`) are excluded at discovery.
99 +###
4.2 Secret — keyring via `secret-tool` 101 +- **Lookup:** `secret-tool lookup service caldav host <host>`
102 +- **Store (from setup popup):** `secret-tool store --label="Nuguland CalDAV" service caldav host <host> account <username>` — password written to the process **stdin** (no echo, never in argv).
103 +- **Host** derived from `url` (e.g. `box.bugabinga.net`).
107 +Trigger when **any** of: config missing `url`/`username`, or keyring lookup returns empty/fails. Reachable from the clock popout (a "Connect calendar" affordance in the agenda area when status is `needs-setup`).
109 +Fields: **Server URL**, **Username**, **App-password** (`TextField`, `echoMode: TextInput.Password`). Helper text: *"Use a Nextcloud app-password, not your main password."*
112 +1. Write `url`, `username` to config.
113 +2. `secret-tool store …` with password piped to stdin.
114 +3. Call `caldav.discoverAndFetch()`.
115 +4. On `secret-tool` failure (missing binary / `not activatable` service) → show inline error in the popup (see §8), do not crash.
119 +##
5. Network requests 121 +All requests authenticate via a curl config read from **stdin** so the password never enters argv/disk:
124 +curl -sS -K - "<url>" -X <METHOD> -H "Depth: 1" -H "Content-Type: application/xml" --data "<body>"
126 +with the heredoc on stdin:
128 +user = "<username>:<password>"
131 +The `Process` runs `sh -c` so the password can be substituted inside the shell (never an argv of the Process). Non-secret values (URL, username, request body) are passed as **environment variables** to the `Process`; the password is fetched inside the script:
134 +PW
="$(secret-tool lookup service caldav host "$CALDAV_HOST")" || {
echo '__NO_SECRET__'; exit 0
; }
135 +[ -z
"$PW" ] && {
echo '__NO_SECRET__'; exit 0
; }
139 +If `secret-tool` is not installed, `sh` reports `command not found` → script prints `__NO_SECRET__` (caught by §8). The marker tokens (`__NO_SECRET__`) are how the QML side distinguishes "needs setup" from "network error" from valid JSON.
141 +###
5.1 Discovery — PROPFIND (Depth 1) 143 +`PROPFIND` on `<url>/calendars/<username>/` requesting `resourcetype`, `displayname`, `calendar-color` (`xmlns="http://apple.com/ns/ical/"`), and `supported-calendar-component-set`. Parse → `calendars[]` (skip collections with no `displayname` and no calendar `resourcetype`). Persist to config.
145 +###
5.2 Events — REPORT calendar-query + expand (per VEVENT calendar) 147 +Body (window from §6):
149 +<
c:calendar-query xmlns:d=
"DAV:" xmlns:c=
"urn:ietf:params:xml:ns:caldav">
150 + <
d:prop><
c:calendar-data><
c:expand start=
"START" end=
"END"/></
c:calendar-data></
d:prop>
151 + <
c:filter><
c:comp-filter name=
"VCALENDAR">
152 + <
c:comp-filter name=
"VEVENT"><
c:time-range start=
"START" end=
"END"/></
c:comp-filter>
153 + </
c:comp-filter></
c:filter>
156 +`<c:expand>` MUST be inside `<c:calendar-data>`. Avoid `<d:allprop>` (Nextcloud expand bug). Returns one VEVENT per occurrence, all UTC, no RRULE/VTIMEZONE.
158 +###
5.3 Tasks — REPORT calendar-query (per VTODO calendar) 160 +Same shape with `<c:comp-filter name="VTODO">`. No `<c:expand>` (tasks rarely recur). Time-range on VTODO is unreliable across servers, so fetch the calendar's VTODOs and filter client-side by `DUE`/`DTSTART` within the window; tasks with no date are dropped (cannot be placed on the grid).
162 +###
5.4 One Process, all calendars 164 +A single `Process` runs a loop over enabled calendar hrefs (passed as a newline-delimited env var), concatenating raw responses with a delimiter line `@@CAL <href>\t<color>\t<kind>`; the Python parser splits on it and tags each event with its calendar color/kind. One `StdioCollector` → one `JSON.parse`.
168 +##
6. Fetch window (resolves the §11 contradiction) 170 +The window covers the **entire visible 6-week grid**, week-aligned to Monday (locale `firstDayOfWeek`), so every visible cell — including spillover days from adjacent months — can show events.
173 +gridStart = Monday on-or-before the 1st of the displayed month, at 00:00 local
174 +gridEnd = gridStart + 42 days, 00:00 local
175 +START/END = gridStart/gridEnd converted to UTC, formatted yyyyMMddTHHmmssZ
178 +Display is the current month only (no navigation). The agenda filters this same dataset to "today". No second request.
182 +##
7. ICS parsing (Python, embedded) 184 +Input: the XML `REPORT`/`PROPFIND` responses (calendar-data is XML-text-encoded). Steps, in order — all required (the sample has 116 folded lines and `"`/` ` entities):
186 +1. **Extract** each `<c:calendar-data>` text node (per `@@CAL` block).
187 +2. **XML-entity-decode** the text (`html.unescape` handles ` `, `"`, `&`, …).
188 +3. **Split** into `BEGIN:VEVENT`/`BEGIN:VTODO` … `END:` blocks.
189 +4. **Unfold** continuation lines: a line beginning with space or tab is appended to the previous line (CRLF already normalized).
190 +5. For each property, **unescape ICS text**: `\\n`→newline, `\\,`→`,`, `\\;`→`;`, `\\\\`→`\\`.
191 +6. Read `SUMMARY`, `UID`, and:
192 + - **Timed** (`DTSTART:…Z`): emit `startMs`/`endMs` as **UTC epoch milliseconds**; `allDay=false`.
193 + - **All-day** (`DTSTART;VALUE=DATE:yyyymmdd`): emit `date` (and `endDate`, the iCal **exclusive** end → covered days are `date … endDate-1`); `allDay=true`. No timezone math.
194 + - **Task** (VTODO): `kind="task"`, `date` from `DUE` (or `DTSTART`); `done` from `STATUS:COMPLETED`/`PERCENT-COMPLETE:100`.
195 +7. Emit JSON array. Per-event fields:
198 +{
"uid":
"...",
"summary":
"...",
"cal":
"personal",
"color":
"#5b8cff",
199 + "kind":
"event"|
"task",
"allDay":
false,
200 + "startMs":
1781888100000,
"endMs":
1781891700000,
201 + "date":
null,
"endDate":
null,
"done":
false }
204 +QML side: timed → `new Date(startMs)` (auto-localizes); all-day/task → parse `date` as a plain local calendar date. Multi-day detection: `allDay && endDate` spanning >1 day, or timed event whose local start/end dates differ.
206 +Parser must be defensive: unknown/garbage blocks are skipped, never throw (a parse error must not blank the whole calendar).
210 +##
8. Status & error handling 212 +`CalDav.status`: `"ok" | "loading" | "offline" | "needs-setup"`.
214 +| Condition | status | UI |
215 +|-----------|--------|----|
216 +| Valid JSON parsed | `ok` | dots/pills/bands + agenda; clear stale flag |
217 +| Output `__NO_SECRET__` or config incomplete | `needs-setup` | grid renders (no events); agenda shows "Connect calendar" affordance → opens setup popup |
218 +| curl non-zero / empty / network error / parse failure | `offline` | **keep last-good events**; show subtle stale indicator (muted `·`) next to date line; agenda from last-good data |
219 +| `secret-tool` missing / keyring `not activatable` | `needs-setup` | setup popup shows inline error: "System keyring unavailable" |
221 +The clock and month grid **always** render; network state never breaks them.
225 +##
9. UI spec — `clockContent` 227 +Width ~320px. Top to bottom:
229 +1. **Clock** (existing large time) + **date line** (`Sonntag, 28. Juni 2026`); stale `·` appended when `status==offline`.
230 +2. **Weekday header** — single letters `M D M D F S S`, weekend (`S S`) dimmed.
231 +3. **Month grid** — 6 weeks × 7, week starts Monday. Each cell:
232 + - **Number**: today = filled accent circle; out-of-month = dimmed.
233 + - **Timed single-day events** → up to 2 calendar-colored dots under the number, `+` if more distinct calendars.
234 + - **All-day single-day** → filled pill under the number (calendar color), label if width allows.
235 + - **Multi-day** → translucent band (calendar color @ ~30% + 1px inset border) across covered cells; see §10.
236 +4. **Today agenda** — header `Heute`; rows = `time | color-bar | title`:
237 + - timed → `HH:mm`; all-day → `ganztg`; task → `○` glyph, title; completed task → strikethrough/dimmed.
238 + - sorted: all-day/tasks first, then timed by start.
239 + - empty → italic `Keine Termine`.
241 +Borderless (whitespace, not gridlines); one accent color; per-calendar color only on event marks; no animation/gradients/shadows. Fixed 6-row height (no jump month-to-month).
245 +##
10. Multi-day band algorithm (the hard part) 247 +Goal: render spanning events as continuous bands that segment at week-row boundaries and stack without overlap.
249 +1. **Collect** multi-day events overlapping the visible window. For each, clamp `[start,end]` to `[gridStart,gridEnd]`.
250 +2. **Lane assignment** (per the whole grid): sort by start asc, then duration desc. Greedily assign each event the lowest lane index whose time range doesn't overlap an already-placed event in that lane. Lane = vertical slot index within a cell.
251 +3. **Per-week segmentation**: for each of the 6 week rows, for each event covering any day in that row, emit a segment spanning `[max(eventStart,rowStart) … min(eventEnd,rowEnd)]`. Round the **left** edge only if the segment's first day is the event's true start; round the **right** edge only if its last day is the event's true end (clamped end uses the iCal exclusive rule for all-day). A Sun→Mon event yields two segments (one per row).
252 +4. **Cell height**: reserve vertical space for `numberRow + maxLanes*bandHeight + dotsRow`. Compute `maxLanes` across the visible grid so all rows share a height (no jump). Cap lanes (e.g. 3) and add a `+N` overflow marker on days exceeding the cap.
253 +5. Implementation: render bands as an overlay `Item` positioned by `(weekRow, dayCol, lane)` using the grid's cell geometry, above the cell background but below the number. (QML `Repeater` over a precomputed `segments[]` model.)
255 +This is the one genuinely complex unit; isolate it (a `buildSegments(events, gridStart)` pure function returning `segments[]` + `laneCount`) so it's testable independently of rendering.
259 +##
11. Background: why curl, not XHR (verified) 261 +Qt QML `XMLHttpRequest.open()` enforces a method whitelist. Empirically (deterministic across runs): `GET` and `PROPFIND` reach the server; **`REPORT` and `MKCALENDAR` are rejected locally** (`open()` throws). `REPORT` is the verb that performs `calendar-query` + server-side `<C:expand>`. Therefore event fetch cannot use XHR; `curl` via `Process` is required. A `Process` is needed regardless (no Quickshell keyring API → `secret-tool` runs via `Process`). Live validation against the real server confirmed the full flow: PROPFIND discovered 6 calendars; REPORT+expand returned 113 expanded VEVENTs with zero leaked RRULEs.
267 +`CalDav.stateJson()` returns the serialized state (status, calendars, today's agenda, counts) and is wired into `shell.qml`'s `IpcHandlers` — additive only, per [[nuguland-statejson-is-ipc-contract]]. Existing clock/date/agenda IPC in `Time.qml` is unchanged.
271 +##
13. File structure 273 +- **Create** `quickshell/nuguland/CalDav.qml` — service: config (FileView+JsonAdapter), discovery + fetch Process, embedded Python parser string, status, `discoverAndFetch()`, `refresh()`, `stateJson()`, `buildSegments()` pure helper (or a sibling JS file `caldav.js` if it keeps `CalDav.qml` focused).
274 +- **Modify** `quickshell/nuguland/shell.qml` — instantiate `CalDav`, inject into `PopoutHost`, add IPC handler.
275 +- **Modify** `quickshell/nuguland/PopoutHost.qml` — rewrite `clockContent` (grid + agenda + band overlay + stale indicator); add setup popup; trigger `caldav.refresh()` on clock popout open.
276 +- `quickshell/nuguland/Time.qml` — unchanged (local clock/date stays its own concern).
280 +##
14. Out of scope (YAGNI) 282 +- Month navigation / day selection (static current month).
283 +- Event creation/editing/deletion (read-only).
284 +- Multiple accounts/servers.
285 +- Client-side recurrence (server expand covers it).
286 +- Caching events to disk across restarts (refetch on launch is fast enough).
287 +- VTODO without a date; sub-tasks; alarms/notifications.
291 +##
15. Security posture 293 +- Read-only DAV verbs only (PROPFIND/REPORT/GET).
294 +- App-password (not main password); guidance shown in setup popup.
295 +- Password only ever in keyring + transient shell variable on stdin; never in argv, config file, or QML memory beyond the store call.
296 +- Config file (URL/username, non-secret) in statePath; `caldav.json` is state, gitignored by location.