Color Timer Clock: update

Author: RobertAlexanderH

cinnamon-color-timer-clock-desklet@curbsoftware/LICENSE

@@ -1,12 +1,12 @@
-World Clock Desklet is free software: you can redistribute it and/or modify it
+Color Timer Clock Desklet is free software: you can redistribute it and/or modify it
 under the terms of the GNU General Public License as published by the
 Free Software Foundation, either version 2 of the License, or (at your
 option) any later version.
 
 Copyright (C) 2026 CurbSoftware
 
-World Clock Desklet is derived from TimeAndDate@nightflame, which is
-distributed under the GNU General Public License version 2.
+Its responsive sizing helpers are derived from World Clock Desklet and remain
+under the GNU General Public License version 2 or later.
 
 The complete text of the GNU General Public License version 2 follows.
 

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

@@ -2,7 +2,11 @@
 
 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)
+![Color Timer Clock desklet](screenshots/color-timer-clock-desklet.webp)
+
+The settings window:
+
+![Color Timer Clock settings](screenshots/color-timer-clock-config.webp)
 
 ## Why this exists
 
@@ -16,37 +20,38 @@ 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
+- Up to three responsive cards. Narrow widths wrap cards onto centered rows and add enough height instead of hiding or clipping cards
 - 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
+- Keyboard focus, pressed states, accessible names and tooltips on every card control
+- One **Reload color schedules** desklet menu action that does not interrupt a running timer or chronometer
+- A labelled **Next** preview chip on each card, with a 20 px double-ring colour sample and the upcoming stop details in its tooltip
+- A clear setup message when every card is disabled
 - One-click "Reset all schedules to defaults"
 
 ## Configuration
 
-Right-click the desklet → **Configure…**
+Right-click the desklet and choose **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
+- **Color schedules**: a list of (time, color) stops per card. Colors are hex (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`) or a name such as `red` or `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
+- **Reload color schedules**: the desklet menu action reloads all three schedules without restarting a running timer or chronometer
+- **Next colour (per card)**: the labelled footer chip previews the next schedule colour. Hover its colour sample for the stop time and exact colour value
 - **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 to 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 wrap onto more rows when each card would otherwise become too narrow. Enabled cards never disappear because of desklet width.
 
 UUID: `cinnamon-color-timer-clock-desklet@curbsoftware`
 

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

@@ -261,19 +261,17 @@ function thresholdsCrossed(prev, cur, times, wrap) {
 }
 
 /**
- * nextColor:
+ * nextStop:
  * @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.
+ * Returns (object): a fresh {t, rgba} for the next stop in the direction of
+ * travel, or null when no stop remains. Wrapped schedules always have a next
+ * stop. This gives the desklet both the preview colour and its schedule time.
  */
-function nextColor(stops, pos, opts) {
+function nextStop(stops, pos, opts) {
     opts = opts || {};
 
     let list = [];
@@ -294,24 +292,27 @@ function nextColor(stops, pos, opts) {
     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 { t: list[i].t, rgba: list[i].rgba.slice() };
         }
-        return list[0].rgba.slice();
+        return null;
     }
 
     for (let i = 0; i < list.length; i++) {
         if (list[i].t > q)
-            return list[i].rgba.slice();
+            return { t: list[i].t, rgba: list[i].rgba.slice() };
     }
     if (opts.wrap)
-        return list[0].rgba.slice();
-    return list[list.length - 1].rgba.slice();
+        return { t: list[0].t, rgba: list[0].rgba.slice() };
+    return null;
+}
+
+/* Compatibility helper for callers that only need the preview colour. */
+function nextColor(stops, pos, opts) {
+    let stop = nextStop(stops, pos, opts);
+    return stop ? stop.rgba : null;
 }
 
 /* ------------------------------------------------------------------ *
@@ -571,37 +572,59 @@ var CARD_LAYOUT = {
     dateEm: 0.58,
     labelEm: 0.56,
     addMaxPt: 16,
-    /* A card cannot shrink below its control pill; fitKinds() hides cards
-     * rather than let the grid overflow the container below this. */
-    minCardWidth: 120
+    /* Timer controls and the labelled next-colour chip share one footer. */
+    minCardWidth: 250,
+    /* Title, value, subtitle and control row need this much card height. */
+    minCardHeight: 124
 };
 
 /**
- * fitKinds:
- * @kinds (array): visible card kinds from the settings checkboxes, in
- *   build order (clock, timer, chrono)
+ * computeResponsiveGrid:
+ * @cardCount (number): count of enabled cards
  * @width (number): desklet width setting (px)
  * @spacing (number): card spacing setting (px, used as per-card margin)
  *
- * Returns (array): the kinds that fit. Cards drop from the end - the
- * chronometer first, then the timer - because the clock is the anchor;
- * one card always survives so the desklet never renders empty. Widening
- * restores the hidden cards on the next rebuild; the settings checkboxes
- * remain the source of truth.
+ * Returns (object): { rows, cols }. Every enabled card gets a cell. Narrow
+ * widths reduce the column count and add rows instead of hiding cards.
  */
-function fitKinds(kinds, width, spacing) {
-    let list = Array.isArray(kinds) ? kinds.slice() : [];
+function computeResponsiveGrid(cardCount, width, spacing) {
+    let count = parseInt(cardCount, 10);
+    if (!Number.isFinite(count) || count < 1)
+        return { rows: 0, cols: 0 };
     let w = Number(width);
     if (!Number.isFinite(w) || w <= 0)
         w = 840;
     let gap = Number(spacing);
     if (!Number.isFinite(gap) || gap < 0)
         gap = 0;
+    const available = Math.max(1, w - 2 * CARD_LAYOUT.containerPad);
     const min = CARD_LAYOUT.minCardWidth + 2 * gap;
-    while (list.length > 1 &&
-        list.length * min + 2 * CARD_LAYOUT.containerPad > w)
-        list.pop();
-    return list;
+    const cols = Math.max(1, Math.min(count, Math.floor(available / min)));
+    return { rows: Math.ceil(count / cols), cols: cols };
+}
+
+/**
+ * computeResponsiveHeight:
+ * @rows (number): responsive row count
+ * @height (number): configured desklet height
+ * @spacing (number): per-card margin
+ *
+ * Returns (number): configured height or safe row-dependent minimum,
+ * whichever is larger.
+ */
+function computeResponsiveHeight(rows, height, spacing) {
+    let count = parseInt(rows, 10);
+    if (!Number.isFinite(count) || count < 1)
+        count = 1;
+    let base = Number(height);
+    if (!Number.isFinite(base) || base <= 0)
+        base = 260;
+    let gap = Number(spacing);
+    if (!Number.isFinite(gap) || gap < 0)
+        gap = 0;
+    const safe = count * (CARD_LAYOUT.minCardHeight + 2 * gap) +
+        2 * CARD_LAYOUT.containerPad;
+    return Math.max(base, safe);
 }
 
 function _toPositiveInt(value, fallback) {