repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(nuguland): CalDAV calendar popup design spec

28fb7d8b85ecf0aa12c8d7bafbf365db67e0ad4c

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Read-only Nextcloud CalDAV in the clock popout: month grid (dots/pills/
multi-day bands) + today agenda incl. VTODO tasks. curl+REPORT+expand via
Process (Qt XHR rejects REPORT, proven), embedded Python ICS parser,
keyring creds with first-run setup popup, graceful offline degradation.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Changed files (2)

.gitignore

Modified
40 40 # Quickshell LSP scratch/config generated by qs.
41 41 **/.qmlls.ini
42 +.superpowers/

quickshell/nuguland/docs/superpowers/specs/2026-06-28-caldav-calendar-design.md

Added
new file mode 100644
1 +# CalDAV Calendar Popup — Design Spec
3 +**Date:** 2026-06-28
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.
7 +---
9 +## 1. Summary
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.
21 +---
23 +## 2. Decisions (locked)
25 +| Topic | Decision |
26 +|-------|----------|
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 |
44 +---
46 +## 3. Architecture & Data Flow
48 +```
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
60 + ▼
61 + PopoutHost.qml clockContent (redesigned)
62 + • month grid (dots / pills / bands)
63 + • today agenda (events + tasks)
64 + • stale indicator
65 + PopoutHost setup popup (URL/user/password) ──writes──> config + keyring
66 +```
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`.
76 +---
78 +## 4. Config & Credentials
80 +### 4.1 Config file — `Quickshell.statePath("caldav.json")`
82 +```json
84 + "url": "https://box.bugabinga.net/cloud/remote.php/dav",
85 + "username": "oliver@bugabinga.net",
86 + "calendars": [
87 + { "href": "/cloud/remote.php/dav/calendars/oliver@bugabinga.net/personal/",
88 + "displayName": "Oliver's Kalender", "color": "#5b8cff",
89 + "components": ["VEVENT"], "enabled": true }
90 + ],
91 + "lastFetchOk": true
93 +```
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`).
105 +### 4.3 Setup popup
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."*
111 +On submit:
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.
117 +---
119 +## 5. Network requests
121 +All requests authenticate via a curl config read from **stdin** so the password never enters argv/disk:
123 +```
124 +curl -sS -K - "<url>" -X <METHOD> -H "Depth: 1" -H "Content-Type: application/xml" --data "<body>"
125 +```
126 +with the heredoc on stdin:
127 +```
128 +user = "<username>:<password>"
129 +```
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:
133 +```sh
134 +PW="$(secret-tool lookup service caldav host "$CALDAV_HOST")" || { echo '__NO_SECRET__'; exit 0; }
135 +[ -z "$PW" ] && { echo '__NO_SECRET__'; exit 0; }
136 +# …curl using -K - heredoc with user="$CALDAV_USER:$PW" … | python3 -c "$PARSE"
137 +```
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):
148 +```xml
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>
154 +</c:calendar-query>
155 +```
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`.
166 +---
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.
172 +```
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
176 +```
178 +Display is the current month only (no navigation). The agenda filters this same dataset to "today". No second request.
180 +---
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 `&quot;`/`&#13;` entities):
186 +1. **Extract** each `<c:calendar-data>` text node (per `@@CAL` block).
187 +2. **XML-entity-decode** the text (`html.unescape` handles `&#13;`, `&quot;`, `&amp;`, …).
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:
197 +```json
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 }
202 +```
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).
208 +---
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.
223 +---
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).
243 +---
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.
257 +---
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.
263 +---
265 +## 12. IPC contract
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.
269 +---
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).
278 +---
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.
289 +---
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.