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.
Weekday labels are lowercase m d m d 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 keine termine.
The grid has a fixed six-row height and remains borderless, without gradients, shadows, or animation.
Setup, refresh, and failure
Initial setup collects a server URL, username, and app-password.
Setup explicitly says to use an app-password, not the main password.
Non-secret configuration and discovered metadata persist across restarts.
Data refreshes on initial load, when the popup opens, and every 15 minutes.
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.
Additive IPC exposes status, non-secret account identity, counts, and setup booleans, never credentials.
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.
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.
---
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.
- Weekday labels are lowercase `m d m d 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 `keine termine`.
- The grid has a fixed six-row height and remains borderless, without gradients, shadows, or animation.
## Setup, refresh, and failure
- Initial setup collects a server URL, username, and app-password.
- Setup explicitly says to use an app-password, not the main password.
- Non-secret configuration and discovered metadata persist across restarts.
- Data refreshes on initial load, when the popup opens, and every 15 minutes.
- 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.
- Additive IPC exposes status, non-secret account identity, counts, and setup booleans, never credentials.
## 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.
- 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.