Color Timer Clock: add notifications, next-color swatch, per-card refresh, timezone widget

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: RobertAlexanderH

cinnamon-color-timer-clock-desklet@curbsoftware/README.md

@@ -1,34 +1,52 @@
 # Color Timer Clock
 
-A Cinnamon desklet with three cards — **Clock**, **Timer** and **Chronometer** — whose background colors follow a schedule you define. Each card's color ramps between (time, color) stops: the clock by time of day wrapping over midnight, the timer by time remaining, the chronometer by time elapsed.
+A Cinnamon desklet with three cards (**Clock**, **Timer** and **Chronometer**) whose background colors follow a schedule you define. Each card's color ramps between (time, color) stops: the clock by time of day wrapping over midnight, the timer by time remaining, the chronometer by time elapsed.
 
 ![Color Timer Clock desklet](screenshot.png)
 
+## Why this exists
+
+The color is not decoration. It's the signal. Each card has a job:
+
+- The **clock** shows when AI providers run their low-traffic discounts. Set the color stops to match the window, and you know at a glance when it's cheap to run.
+- The **timer** counts down to credit resets, so I know when my API credits come back.
+- The **chronometer** runs sprints. Most of the work happens in the last stretch before a deadline, so the color tells me where I am in the sprint: green for the first half hour, amber sliding to red over the next hour and a half, blue once two hours are up. Blue means take a break.
+
+One glance tells me the state of things. That's the whole idea.
+
 ## Features
 
 - Up to three side-by-side cards; show or hide each one
 - Per-card color schedules with smooth (interpolated) or stepped transitions
 - Clock card with an optional IANA timezone
 - Timer with on-card play/pause, reset and ±60 s buttons; survives restarts and expires correctly even after downtime
+- Optional desktop notification when the timer finishes
+- Optional notifications when the clock or chronometer reaches a schedule stop
 - Chronometer with pause/resume; the accumulated time survives restarts, and an optional hundredths display (20 updates/s while running)
 - Text and border colors adapt to the card background for readability (WCAG contrast ratio)
 - Tooltips on every card control
+- A per-card refresh button to reload settings without interrupting a running timer or chronometer
+- A next-colour swatch on each card that previews the upcoming schedule colour
 - One-click "Reset all schedules to defaults"
 
 ## Configuration
 
 Right-click the desklet → **Configure…**
 
-- **Color schedules** — a list of (time, color) stops per card. Colors are hex (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`) or a name (`red`, `blue`, …). Duplicate times keep the last row; invalid rows are dropped with a log line
-- **Smooth color transitions** — blend gradually between stops, or hold each color and jump at the next stop
-- **Timer minutes / seconds** — the default duration the timer restarts from
-- **Show hundredths of a second** — adds a `.ss` fraction to the chronometer while it runs
-- **Time / date format** — `strftime` patterns for the clock card
-- **Maximum font sizes, card spacing, desklet width / height** — cards shrink text to fit
+- **Color schedules**: a list of (time, color) stops per card. Colors are hex (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`) or a name (`red`, `blue`, …). Duplicate times keep the last row; invalid rows are dropped with a log line
+- **Smooth color transitions**: blend gradually between stops, or hold each color and jump at the next stop
+- **Show a notification when the timer finishes**: pops a desktop notification when the countdown reaches zero
+- **Notify (per schedule row)**: tick a clock or chronometer schedule row's Notify checkbox to pop a notification when that time is reached
+- **Timer minutes / seconds**: the default duration the timer restarts from
+- **Refresh (per card)**: the small button in each card's top-right corner reloads that card's settings without restarting a running timer or chronometer
+- **Next-colour swatch (per card)**: the small circle in each card's bottom-right corner previews the next schedule colour and snaps to it at the breakpoint
+- **Show hundredths of a second**: adds a `.ss` fraction to the chronometer while it runs
+- **Time / date format**: `strftime` patterns for the clock card
+- **Maximum font sizes, card spacing, desklet width / height**: cards shrink text to fit
 
 ## Notes
 
-Colors interpolate piecewise-linearly in RGB, so a red→blue ramp passes through purple. The clock schedule wraps over midnight; timer and chronometer schedules hold the last stop's color beyond it. Cards share the desklet width and each needs about 130 px — when the width cannot fit them all, the chronometer and then the timer hide automatically (a note is logged) and return when the desklet is widened.
+Colors interpolate piecewise-linearly in RGB, so a red→blue ramp passes through purple. The clock schedule wraps over midnight; timer and chronometer schedules hold the last stop's color beyond it. Cards share the desklet width and each needs about 130 px. When the width cannot fit them all, the chronometer and then the timer hide automatically (a note is logged) and return when the desklet is widened.
 
 UUID: `cinnamon-color-timer-clock-desklet@curbsoftware`
 

cinnamon-color-timer-clock-desklet@curbsoftware/files/cinnamon-color-timer-clock-desklet@curbsoftware/cardActions.js

@@ -128,7 +128,7 @@ function rgbaToCss(rgba) {
  * rgbaToKey:
  * @rgba (array): [r, g, b, a] with a in 0..1
  *
- * Returns (string): "#rrggbbaa" (lowercase) — a canonical key for change
+ * Returns (string): "#rrggbbaa" (lowercase), a canonical key for change
  * detection, so a colour that round-trips identically does not trigger a
  * restyle.
  */
@@ -181,7 +181,8 @@ function _rowSeconds(row) {
  * does not parse (counting them), sorts ascending and, when two rows share
  * a time, keeps the later row.
  *
- * Returns (object): { stops: [{t, rgba}], dropped }.
+ * Returns (object): { stops: [{t, rgba, notify?}], dropped }. A stop carries
+ * notify: true only when its row's notify flag was set.
  */
 function normalizeSchedule(rows, maxT) {
     if (!Array.isArray(rows))
@@ -202,11 +203,14 @@ function normalizeSchedule(rows, maxT) {
             dropped++;
             continue;
         }
-        tagged.push({
+        let stop = {
             t: Math.max(0, Math.min(limit, Math.round(t))),
             rgba: parsed.rgba,
             i: i
-        });
+        };
+        if (rows[i] && rows[i].notify)
+            stop.notify = true;
+        tagged.push(stop);
     }
 
     /* Sort by time, then input order, so equal times keep the later row
@@ -219,12 +223,97 @@ function normalizeSchedule(rows, maxT) {
     for (let i = 0; i < tagged.length; i++) {
         if (i + 1 < tagged.length && tagged[i + 1].t === tagged[i].t)
             continue; /* equal time: the later row wins */
-        stops.push({ t: tagged[i].t, rgba: tagged[i].rgba });
+        let stop = { t: tagged[i].t, rgba: tagged[i].rgba };
+        if (tagged[i].notify)
+            stop.notify = true;
+        stops.push(stop);
     }
 
     return { stops: stops, dropped: dropped };
 }
 
+/**
+ * thresholdsCrossed:
+ * @prev (number): previous sampled position
+ * @cur (number): current sampled position
+ * @times (array): sorted threshold times
+ * @wrap (boolean): treat the position as circular (clock, rolls over at 0)
+ *
+ * Returns (array): thresholds crossed moving from @prev to @cur. A monotonic
+ * position crosses prev < t <= cur; a wrapped position that went backwards
+ * (prev > cur) crosses everything above prev and at or below cur.
+ */
+function thresholdsCrossed(prev, cur, times, wrap) {
+    let out = [];
+    if (!Array.isArray(times) || !Number.isFinite(prev) || !Number.isFinite(cur))
+        return out;
+    for (let i = 0; i < times.length; i++) {
+        let t = Number(times[i]);
+        if (!Number.isFinite(t))
+            continue;
+        let crossed = (wrap && prev > cur)
+            ? (t > prev || t <= cur)
+            : (prev < t && t <= cur);
+        if (crossed)
+            out.push(t);
+    }
+    return out;
+}
+
+/**
+ * nextColor:
+ * @stops (array): normalised stops [{t, rgba}], any order
+ * @pos (number): query position in seconds
+ * @opts (object): { wrap, reverse }. wrap treats the position as circular
+ *   (clock); reverse walks the schedule backwards (timer counting down).
+ *
+ * Returns (array): the colour of the next stop in the direction of travel, or
+ * null when there are no stops. A forward schedule returns the first stop
+ * above @pos (wrapping to the first past the end when @opts.wrap, else holding
+ * the last stop); a reverse schedule returns the first stop below @pos,
+ * falling back to the lowest stop at or past the end.
+ */
+function nextColor(stops, pos, opts) {
+    opts = opts || {};
+
+    let list = [];
+    if (Array.isArray(stops)) {
+        for (let i = 0; i < stops.length; i++) {
+            let s = stops[i];
+            if (s && Number.isFinite(s.t) && Array.isArray(s.rgba))
+                list.push({ t: s.t, rgba: s.rgba });
+        }
+    }
+    if (list.length === 0)
+        return null;
+    list.sort(function (a, b) { return a.t - b.t; });
+
+    let q = Number(pos);
+    if (!Number.isFinite(q))
+        q = 0;
+    if (opts.wrap)
+        q = ((q % DAY_SECONDS) + DAY_SECONDS) % DAY_SECONDS;
+
+    if (list.length === 1)
+        return list[0].rgba.slice();
+
+    if (opts.reverse) {
+        for (let i = list.length - 1; i >= 0; i--) {
+            if (list[i].t < q)
+                return list[i].rgba.slice();
+        }
+        return list[0].rgba.slice();
+    }
+
+    for (let i = 0; i < list.length; i++) {
+        if (list[i].t > q)
+            return list[i].rgba.slice();
+    }
+    if (opts.wrap)
+        return list[0].rgba.slice();
+    return list[list.length - 1].rgba.slice();
+}
+
 /* ------------------------------------------------------------------ *
  * Schedule evaluation
  * ------------------------------------------------------------------ */
@@ -575,25 +664,66 @@ function computeCardInnerSize(deskletWidth, deskletHeight, rows, cols, cardSpaci
     };
 }
 
+function _glyphEm(ch, em) {
+    if (ch >= "0" && ch <= "9")
+        return Math.max(em, 0.72);
+    if (ch === ":" || ch === ".")
+        return 0.38;
+    if (ch === " " || ch === ",")
+        return 0.33;
+    return em;
+}
+
+function _textEmUnits(text, em) {
+    let s = String(text || "");
+    let units = 0;
+    for (let i = 0; i < s.length; i++)
+        units += _glyphEm(s[i], em);
+    return units;
+}
+
 function _textWidthPx(text, sizePt, ptToPx, em) {
-    let n = String(text || "").length;
-    if (n === 0)
+    let units = _textEmUnits(text, em);
+    if (units <= 0)
         return 0;
-    return n * sizePt * ptToPx * em;
+    return units * sizePt * ptToPx;
 }
 
 function _maxPtForWidth(text, innerW, ptToPx, em, cap) {
-    let n = String(text || "").length;
-    if (n === 0)
+    let units = _textEmUnits(text, em);
+    if (units <= 0)
         return cap;
-    if (!(innerW > 0) || !(ptToPx > 0) || !(em > 0))
+    if (!(innerW > 0) || !(ptToPx > 0))
         return 1;
-    let pt = innerW / (n * ptToPx * em);
+    let pt = innerW / (units * ptToPx);
     if (!Number.isFinite(pt) || pt <= 0)
         return 1;
     return Math.min(cap, pt);
 }
 
+/**
+ * worstTimeSample:
+ * @format (string): strftime time format
+ * @extras (object): { hundredths } to append a ".99" fraction
+ *
+ * Returns (string): a wide sample used to size the time line before the
+ * live string is known, so enabling seconds or hundredths cannot overflow.
+ */
+function worstTimeSample(format, extras) {
+    extras = extras || {};
+    let fmt = typeof format === "string" ? format : "";
+    let hasSeconds = !fmt || /%[STcT]/.test(fmt);
+    let twelveHour = /%[IilpPr]/.test(fmt);
+    let sample;
+    if (twelveHour)
+        sample = hasSeconds ? "12:59:59 PM" : "12:59 PM";
+    else
+        sample = hasSeconds ? "23:59:59" : "23:59";
+    if (extras.hundredths)
+        sample += ".99";
+    return sample;
+}
+
 /**
  * computeFittedFontSizes:
  * @innerWidth (number): card text box width in px