refactor: enhance TimerPage layout and functionality; update theme and tokens for improved design consistency

- Refactored TimerPage component to improve layout and user experience. - Updated theme configuration to utilize design tokens for better maintainability. - Introduced new tokens for colors and typography to align with design principles. - Simplified state management and improved timer functionality. - Enhanced accessibility and responsiveness of UI elements.
2026-10-18 23:57:36 +03:00
1 parent 17a0a3c4c9
commit 77b26757bf
@@ -7,7 +7,9 @@ system package `python-pyqt6`; everything else — HTTP, config, process scannin
 is the Python standard library.

 It is also the piece that *enforces* things, because it is the only part running
-on your machine.
+on your machine. The interface is the same warm, hairline-ruled design as the
+web app — the `Theme` singleton in `qml/` holds the same tokens as the web
+app's `tokens.ts`.

 ```bash
 sudo pacman -S --needed python-pyqt6 qt6-declarative     # Arch
@@ -24,6 +26,9 @@ Run it straight from the checkout instead: `python3 -m kadence_desktop`.

 | Feature | How |
 | --- | --- |
+| **A floating mini timer** | A small pill with the countdown, the task you are on, and the controls — *Pause / Resume / Finish / +5*, or *Start focus / Break* when idle — all on their own rows and all visible without hovering. Open it with **Ctrl+M**, the tray menu, or `kadence-desktop --mini`; it also appears by itself while an interval runs and the main window is away. Dragging moves it (through the compositor, so it works on Wayland) and double-clicking opens the main window. It is **not** a `Qt.Tool` window — Qt hides those whenever the application is deactivated, which made it vanish on every click in another app — and it refuses keyboard focus instead. |
+| **Where it appears** | Settings → *Mini timer appears*: any of the four corners, the top/bottom edge centres, the centre of the screen, or *where I last dragged it*, with a configurable gap from the edges. It is placed on the screen the app is on, inside the usable area (panels excluded), and it returns to that spot every time it comes up. On X11 the app positions the window; on Wayland — where a client may not — the point is written into the same KWin rule. |
+| **Above everything, on Wayland** | Wayland gives an application no way to ask for "always on top", so on KDE the app installs a **KWin window rule** (keep above, skip task bar, skip switcher, skip pager) and asks KWin to re-read its config over D-Bus. The rule matches the window title as a **substring**: Qt appends the application's display name, so KWin sees `Kadence mini — Kadence`, and an exact match silently never fires. The app backs the file up first, leaves your other rules alone, re-writes the rule when an upgrade changes it, and *Settings → Keep the mini timer above everything* removes it. Verify with `busctl --user call org.kde.KWin /Scripting org.kde.kwin.Scripting loadScript …` or simply: the mini timer should stay on top of a maximised window. |
 | **Tray icon that *is* the timer** | `QSystemTrayIcon` (a StatusNotifierItem on KDE). The icon is painted at runtime: a ring that drains as the interval runs, tinted by focus / break / idle, with a pause glyph when held. Middle-click toggles the timer. |
 | **Real notifications with buttons** | `org.freedesktop.Notifications` over D-Bus, with actions: *Start break* · *Another pomodoro* · *+5 min*. Replaced in place, so a day of pomodoros never stacks a column of toasts. |
 | **Scriptable over D-Bus** | `org.kadence.Desktop` exports `StartWork`, `Toggle`, `Pause`, `Complete`, `Extend`, `Interrupt`, `Status`, `SendReport`, `Raise`. Bind any of them to a global shortcut in System Settings — no key-grabbing hacks. |
@@ -52,6 +57,8 @@ edit them and a second machine obeys the same list. This app enforces them:
 * **Applications** — `/proc` is scanned every few seconds for your own processes
  matching the list; they are terminated (SIGTERM, then SIGKILL) or merely
  reported, and every attempt is sent to the backend for the evening report.
+  List entries may be globs — `steam*`, `*discord*`, `telegram-?` — matched
+  against both the process name and its command line.
 * Everything is released when the interval ends — and on exit, including a crash,
  because `shutdown()` clears the block and the inhibits.

@@ -76,6 +83,45 @@ sudo ./helper/install.sh --uninstall      # unblocks first, then removes itself

 ---

+## Application menu and rofi
+
+```bash
+./packaging/install-desktop.sh
+```
+
+That writes `~/.local/share/applications/kadence.desktop`, the icon, and a
+`~/.local/bin/kadence-desktop` launcher, then refreshes the caches each
+launcher keeps (`update-desktop-database`, `gtk-update-icon-cache`,
+`kbuildsycoca6` for KDE's menu).
+
+Two details that decide whether an entry shows up at all:
+
+* **`Exec`/`TryExec` are written as absolute paths.** Launchers run with the
+  *session* PATH, which usually does not include `~/.local/bin`; an entry whose
+  `TryExec` cannot be resolved is silently hidden. Absolute paths cannot be.
+* **One main category.** `Categories=Office;ProjectManagement;` — listing both
+  `Utility` and `Office` makes the app appear twice in some menus.
+
+It then shows up in KDE's launcher under *Office* and in `rofi -show drun`
+(search for *pomodoro*, *timer* or *focus*), with the right-click actions
+*Start a pomodoro* / *Start a break* / *Start / pause* / *Send today's report*.
+
+If your rofi runs in **`run` mode** rather than `drun`, it lists binaries from
+`PATH`, so `~/.local/bin` has to be on the session PATH:
+
+```bash
+printf 'PATH=$HOME/.local/bin:$PATH\n' > ~/.config/environment.d/10-local-bin.conf
+# for the session you are already in:
+systemctl --user set-environment PATH="$HOME/.local/bin:$PATH"
+dbus-update-activation-environment --systemd PATH
+```
+
+To see the entry (and its actions) in rofi with its icon instead, add `drun`:
+`modes: "drun,run";` in `~/.config/rofi/config.rasi`, plus
+`drun-show-actions: true;` if you want the actions listed too.
+
+---
+
 ## Global shortcuts

 System Settings → Shortcuts → Custom Shortcuts → New → D-Bus command:
@@ -94,13 +140,35 @@ kadence-desktop --toggle      # start → pause → resume
 kadence-desktop --start       # start a focus interval
 kadence-desktop --break
 kadence-desktop --complete
+kadence-desktop --mini        # show/hide the floating mini timer
 kadence-desktop --status      # "Focus 18:42 · Write the docs · 3/8 today"
 kadence-desktop --report      # send today's report to Telegram
 ```

+On Qt 6 the command-line D-Bus tool is **`qdbus6`** (plain `qdbus` is the Qt 5
+one and may not be installed):
+
+```bash
+qdbus6 org.kadence.Desktop /Timer org.kadence.Timer.Status
+busctl --user introspect org.kadence.Desktop /Timer   # lists every verb
+```
+
+The verbs live on a `QDBusAbstractAdaptor` carrying
+`pyqtClassInfo("D-Bus Interface", "org.kadence.Timer")`. That detail matters:
+export a plain `QObject` instead and Qt names the interface after the class
+(`local.kadence.TimerDBusService`), so every documented command fails with
+*"No such interface"*.
+
 In-window shortcuts: **Space** start/pause · **Ctrl+Enter** finish ·
-**Ctrl+E** +5 min · **Ctrl+R** refresh sources · **Ctrl+1…5** pages ·
-**Ctrl+W** hide to tray.
+**Ctrl+E** +5 min · **Ctrl+R** refresh sources · **Ctrl+M** mini timer ·
+**Ctrl+1…5** pages · **Ctrl+W** hide to tray.
+
+> **Wayland note.** The mini timer's placement and "always on top" are a KWin rule written to
+> `~/.config/kwinrulesrc` (backed up once as `kwinrulesrc.kadence-backup`); you
+> can see it in System Settings → Window Management → Window Rules as *Kadence
+> mini timer*, and the switch in Settings removes it. Its position is remembered
+> on X11; on Wayland the compositor places it and dragging goes through
+> `startSystemMove()`.

 ---