From 901a88e26b91eb104aa9a837372d35db24f7b6bf Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Tue, 13 Oct 2026 10:35:35 +0200 Subject: docs: the calendar panel and calctl The island README gains the panel. AGENTS.md records why calctl reads the vdir itself, the local-time recurrence rule, the system Python it needs, and two traps the build hit: a QML method named escape fails to load, and a pill expanding for any panel grew beside the calendar. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 20 +++++++++++++++++++- desktop/island/README.md | 19 ++++++++++++++++++- 2 files changed, 37 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 82b73e0..a7b841f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,7 +13,7 @@ modules. desktop/ the drawer: sound, mail, VMs, appearance island/ top-centre pills on DP-1: clock, volume, tray, layout, privacy, - controls panel (SUPER alone) + controls panel (SUPER alone), calendar appearance/ wallpaper picker and colour scheme switcher window-switcher/ open windows as live previews in a grid, on ALT+TAB keybinds/ live keybind reminder, on SUPER+k @@ -155,6 +155,24 @@ changing that component. The ones that generalise: has no mkdir step. `Quickshell.stateDir` is a per-shell hashed directory (`by-shell/`), not `~/.local/state/quickshell`, which is why the preferences path is built from `XDG_STATE_HOME` instead. +- **khal 0.11 has no JSON output**, which is why the calendar reads the vdir + itself through `desktop/island/calendar/calctl` rather than parsing `khal + list -f`. A month list over the 281 live event files measured 0.11s. khal + and cal-notif read the same files and are unaffected by calctl's writes. +- **Recurrence is expanded in naive local time.** A TZID event keeps its + wall-clock time across DST that way, as RFC 5545 asks; `test_calctl.py` + pins a weekly 09:00 on 26 October, the day after the change. +- **Use `/usr/bin/python3` for calctl and its test.** `python3` on PATH is a + pyenv shim without `icalendar`; the system interpreter has it, for + cal-notif. +- **A QML method cannot be named `escape`.** It shadows the global JS + function, and the file fails with `Illegal method name` at load, which a + hot reload reports as the whole island being unavailable. The island's + Escape hooks are `back()`. +- **A pill that expands for "any panel" grows for its neighbour's.** The + status pill once expanded on `panel !== ""`, which was right while it + hosted every panel; the calendar lives in the clock pill, and the status + pill grew into an empty box beside it. Each pill names its own panels. - **Waybar is gone, both bars.** Its DP-3 functions moved to the island. The mail count is drawer-only: `Accounts.qml` watches the xapian directory itself, and `waybar-mail.sh` was deleted. diff --git a/desktop/island/README.md b/desktop/island/README.md index 8f70506..4d21e6e 100644 --- a/desktop/island/README.md +++ b/desktop/island/README.md @@ -42,7 +42,7 @@ reports its initial state as events. The desktop icons come from `Wed 07/10 15:07`, then one dot per VM that is running, paused, suspended, saved or crashed (a plainly shut-off VM gets none). States come from the drawer's `Virsh` service, whose lifecycle event stream runs whether the drawer -is open or not. +is open or not. Click opens the calendar panel. ## Status pill @@ -81,6 +81,23 @@ they change and keeping keys it does not know. A tile added to the code later starts hidden. Pure helpers in `Controls.js`, tested with `node island/test_controls.js`. +## Calendar panel + +The clock pill opens a month grid beside the selected day's agenda. Dots +are one per calendar with something that day, in the khal colours; a bell on +an agenda row means the event carries its own alarm. A click on an event, or +"+ New event", opens the editor; while it is open the grid picks the date +(shift-click for the end). Repeat is none, daily, weekly, monthly or yearly +with an optional until-date; the alarm is none, 10m, 1h or 1d. An event with +something richer shows custom and an edit leaves it alone. Edit and delete +act on the whole series. Escape closes the editor, then the panel. + +Everything goes through `calendar/calctl`, which reads the calendar list +from khal's config, writes the `.ics` files atomically and starts a +`vdirsyncer sync` after each write. The panel watches the calendar +directories, so khal edits and cron syncs show up live. Tests: +`/usr/bin/python3 calendar/test_calctl.py`, `node calendar/test_cal.js`. + ## Privacy `privacy.sh` prints `mic cam loc scr`, each 0 or 1, and `Privacy.qml` polls it -- cgit v1.2.3