Luigit
repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

quickshell/nuguland/.system/specs/NL-SPEC-9D4A99C2-read-only-caldav-calendar/index.md

Raw
Rendered preview

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.
---
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.