--- id: NL-SPEC-9D4A99C2 type: spec title: Read-only CalDAV calendar --- # Read-only CalDAV calendar ## Outcome The clock popup shows the current six-week month grid and today's agenda from one Nextcloud CalDAV account. It remains useful offline and before setup. ## Data behavior - Event and task calendars are discovered rather than hardcoded; disabled calendars are excluded. - Recurring events arrive expanded by the server. - Task queries are not recurrence-expanded because expansion can drop VTODO data. - The fetched window covers all 42 visible Monday-first cells. - Timed values become local display times from UTC instants. - All-day values remain calendar dates without timezone conversion. - Folded lines, escaped text, exclusive all-day end dates, timed events, and dated tasks parse defensively. - Invalid records are skipped without discarding valid records; undated tasks are ignored. ## Presentation - Timed single-day events render as calendar-colored dots; all-day events render as pills. - Multi-day events render as non-overlapping bands split at week boundaries. - Today is emphasized and adjacent-month days are subdued. - All copy is lowercase English; weekday labels are `m t w t f s s`, with weekends dimmed. - Today's agenda lists all-day items and tasks before timed events. - Open tasks use `○`, completed tasks are subdued, and timed events show local time. - Empty agenda text is `no events today`. - The grid has a fixed six-row height and remains borderless, without gradients, shadows, or animation. ## Setup, refresh, and failure - Config's calendar section collects server URL, username and masked app-password; the calendar popup retains its local grid/events and links to configuration. - CalDav owns drafts, validation and keyring execution; duplicate submission and UI edits reject while storage is pending. - Navigation/dismissal preserves failed-save drafts; successful storage clears only the submitted password revision, never a newer draft. - Saving while the calendar popup is closed does not start discovery/fetch or open its periodic refresh gate. - Setup explicitly says to use an app-password, not the main password. - Non-secret configuration and discovered metadata persist across restarts. - Data refreshes when the popup opens and every 15 minutes while it is open; nothing fetches while closed, because the bar shows only the time (owner decision 2026-11-14). - Missing configuration or credentials presents lowercase setup affordances. - Network, authentication, keyring, or parse failure never breaks the clock or grid. - Failure preserves last-good data and shows a subtle stale marker. - Keyring failure produces an inline, lowercase, actionable error. ## Security and contracts - Calendar access permits DAV discovery and reads only. - The app-password is stored in the system keyring. - The password is never persisted in calendar configuration, written to disk, placed in process arguments, logged, or returned through IPC. - Transient password state is cleared after successful storage. - Functional service state exposes status, non-secret account identity, counts, and setup booleans to panels and isolated tests, never credentials; public IPC follows `NL-SPEC-86A037A0`. ## Acceptance - Parser and layout checks cover unfolding, escaping, dates, tasks, malformed input, week wrapping, and overlapping lanes. - Service checks cover discovery, timezone-independent windows, setup drafts, and state serialization. - Account interaction proof uses actual pointer/keyboard input, retained drafts, pending rejection, failed storage, masked predicates and successful password clearing; raw-secret IPC submission is not UI proof. - A live read discovers calendars and returns events and dated tasks without credential exposure. - Offline and missing-keyring tests preserve the shell and show the specified state. - Screenshots verify grid, bands, agenda ordering, stale state, setup guidance, and lowercase labels. ## Out of scope - Month navigation or day selection. - Calendar mutation, multiple accounts, client-side recurrence, or cross-restart event caching. - Undated tasks, subtasks, and calendar alarms.