feat(alarms): schedule an alarm on a date, pause a repeating one

A one-shot alarm can now ring on a chosen date, and a repeating alarm
can be paused for a range of days. Both are local dates: the date is a
floor and the pause a hole in the occurrence sequence, so DST and zone
changes resolve as for any other alarm. A missed date behaves like a
missed one-shot, and each clears itself once it can no longer change a
candidate. Picking a repeat day clears the date, as in Google Clock;
"skip next" stays the quick version of a pause.

The editor uses the M3 date and date-range pickers, which offer no past
day. The list, the next-alarm widget and the self-check read the
resolver, so they follow. The schema goes to v4 with a migration, and
the backup format to v2, which still imports v1 files. SET_ALARM no
longer re-uses an alarm that carries a date or a pause.

Fixes #21
This commit is contained in:
makiolaj committed 2026-10-21 20:16:34 +02:00
1 parent 3f431a7f32
commit b1a45db54a
43 files changed
+2488 -74

No files matched your search

+19 -5
View File
@@ -11,7 +11,7 @@ written here.
```json
{
"format": "clockula-backup",
"version": 1,
"version": 2,
"exportedAt": 1700000000000,
"alarms": [ … ],
"timers": [ … ],
@@ -21,8 +21,14 @@ written here.
```
- `format`: must be exactly `"clockula-backup"`.
- `version`: must be exactly `1`. Any other value rejects the whole file:
Clockula does not guess at a schema it has not implemented.
- `version`: `2` on export. Import accepts `1` and `2`; any other value
rejects the whole file, since Clockula does not guess at a schema it has not
implemented. Version 2 adds an alarm's `scheduled_date`, `pause_start` and
`pause_end`; a version 1 file is a version 2 file without them, and imports
with every alarm unscheduled and unpaused. The bump is what keeps an older
Clockula from importing a v2 file and silently turning a dated alarm into
tomorrow's, or a paused one back on. The file name stays
`clockula-backup-v1.json` so an existing backup folder keeps working.
- `exportedAt`: epoch milliseconds, informational only (not re-imported).
## Parsing rules
@@ -30,8 +36,8 @@ written here.
- **Tolerant of unknown fields, at any level.** An older or newer client's
extra field is ignored, never an error.
- **Strict about known fields.** A malformed value in a field this schema
defines (`format`, `version`, an alarm's `hour`/`minute`, a world clock's
`zone_id`, a timer's `duration_millis`) rejects the **whole file** with a
defines (`format`, `version`, an alarm's `hour`/`minute` or dates, a world
clock's `zone_id`, a timer's `duration_millis`) rejects the **whole file** with a
specific reason. Nothing is imported half-way.
- Settings values (snooze minutes, volume ramp, …) are
**not** range-checked at parse time; they pass through the same clamps
@@ -92,6 +98,14 @@ One object per row of `alarms`, config only:
| `volume_ramp_seconds` | Int? | `null` = inherit. |
| `dismiss_challenge` | String? | `NONE`/`MATH`/`HOLD`, or `null` = inherit. |
| `delete_after_use` | Boolean | A transient, contract-created alarm. |
| `scheduled_date` | String? | v2. ISO-8601 local date (`2026-10-28`) a one-shot alarm rings on. Ignored on a repeating alarm. |
| `pause_start` | String? | v2. First day of a repeating alarm's pause, ISO-8601. Ignored on a one-shot alarm. |
| `pause_end` | String? | v2. Last day of the pause, inclusive. Present exactly when `pause_start` is. |
A date that does not parse, lies outside 2000-01-01..9999-12-31, a pause with
only one end, or a pause ending before it starts rejects the whole file, like
an out-of-range `hour`. A date on a repeating alarm or a pause on a one-shot is
dropped rather than rejected, which is what the editor would do with it.
**Not exported:** the `alarm_states` ring-state table (snooze/ringing/handled-
occurrence bookkeeping). It is volatile, per-device state, not configuration,