OmarchyClockBar/README.md

# Clock bar

A second bar along the bottom edge of every screen, carrying world clocks laid
out as **one timeline**: furthest behind your local time at the far left,
furthest ahead at the far right, your own time dead centre.

```
 LA 08:24   NYC 11:24   LDN 16:24            17:24            SG 23:24   TOK 00:24 +1   AUS 01:24 +1   NZ 03:24 +1
```

An Omarchy 4 shell plugin (Quickshell). It reserves its own space, so Hyprland
tiles windows above it exactly as it does for the top bar.

## What it does

- **Timeline layout.** Side and position are derived from each zone's live UTC
  offset, not from config order. Reading left to right always moves forward in
  time, and a DST shift re-sorts the bar on its own.
- **24-hour times**, with `+1` / `-1` against clocks on a different date to you.
- **Labels** to the left of each time. The centre clock is your local time and
  carries no label.
- **Dimmed outside working hours**, evaluated in each clock's *own* timezone
  (weekends included), so a glance tells you who is actually around.
- **Seconds per clock.** Any clock can show `HH:MM:SS` on its own, including
  your local one. The bar only drops to a per-second tick when something is
  actually displaying seconds.
- **Themed.** Colours, fonts, spacing and bar height all come from the active
  Omarchy theme; it follows a theme switch with no restart. Set your own bar
  height and the type and spacing scale with it.

## Install

On any Omarchy 4 machine:

```bash
omarchy plugin add https://git.nerdnation.co.za/NerdNation/OmarchyClockBar.git --enable --yes
```

The plugin lands in `~/.config/omarchy/plugins/nerdnation.clockbar/`, and
`~/.config/omarchy/clockbar.json` is seeded on first run.

To update it later, and to remove it:

```bash
omarchy plugin update nerdnation.clockbar && omarchy restart shell
omarchy plugin remove nerdnation.clockbar
```

**The `omarchy restart shell` is not optional.** `omarchy plugin update` pulls
the new files and calls `rescanPlugins`, but that does not reload a
`keepLoaded` panel plugin: the shell holds the compiled QML it started with, so
the files on disk change and the bar carries on running the old build. It looks
exactly like the update silently failing. Restarting the shell is what actually
applies it.

> Plugins run as unsandboxed QML inside `omarchy-shell`, so `omarchy plugin add`
> clones disabled by default and wants you to read the code first. `--enable`
> skips that.

## Configuring it

Two routes, one source of truth — both read and write
`~/.config/omarchy/clockbar.json`, and the bar reloads from the file either way.

**Click the bar.** Opens an editor with a searchable timezone picker: add,
rename, retime and remove clocks, set seconds per clock, and set the
working-hours window and bar height. Each row shows that zone's current offset
so you can see the effect before saving.

The picker searches **country names as well as zone names**, so you can find a
zone without knowing it is named after a city — typing `Ghana` finds
`Africa/Accra`. Country data is tzdata's own (`zone1970.tab`, `zone.tab`,
`iso3166.tab`); the legacy alias zones tzdata ships as hard links inherit the
countries of the canonical zone they point at.

**Edit the file.** It hot-reloads on save, no restart:

```json
{
  "version": 1,
  "clocks": [
    { "label": "LA",  "timezone": "America/Los_Angeles" },
    { "label": "NYC", "timezone": "America/New_York" },
    { "label": "SG",  "timezone": "Asia/Singapore" },
    { "label": "AUS", "timezone": "Australia/Sydney" },
    { "label": "NZ",  "timezone": "Pacific/Auckland", "showSeconds": true }
  ],
  "workingHours": { "start": 8, "end": 18, "workdays": [1, 2, 3, 4, 5] },
  "dimOutsideWorkingHours": true,
  "showSeconds": false,
  "local": { "showSeconds": false },
  "barSize": 0
}
```

| Key | Meaning |
|---|---|
| `clocks[].label` | Shown left of the time. Defaults to the last part of the zone name. |
| `clocks[].timezone` | Any IANA zone (`timedatectl list-timezones`). |
| `clocks[].showSeconds` | Seconds on this clock. Omit it to inherit the bar-wide default below. |
| `workingHours.start` / `.end` | Hours, 0–24, in each clock's own zone. A window that wraps midnight (`22`–`6`) is understood. |
| `workingHours.workdays` | Days counted as working. `0` = Sunday. |
| `dimOutsideWorkingHours` | Mute clocks outside that window. |
| `showSeconds` | The bar-wide default for seconds, for clocks that do not set their own. |
| `local.showSeconds` | Seconds on your local clock, which has no entry in `clocks[]`. |
| `barSize` | Bar height in px. `0` follows the theme's. Otherwise 12–120; text and spacing scale with it. |

Seconds resolve per clock: a clock's own `showSeconds` wins, otherwise the
bar-wide default applies. An explicit `false` on a clock beats a `true`
default. The bar ticks once a minute unless something on it is showing
seconds — nothing pays for a per-second redraw it does not use.

There is no `left` / `right` setting: which side a clock lands on is a fact
about its offset, not a preference.

**When something is wrong**, the bar says so rather than lying. A zone tzdata
cannot resolve renders as `LABEL --:--` in the theme's urgent colour instead of
silently falling back to UTC. A `clockbar.json` that will not parse turns the
bar's top hairline red and puts `config error` beside your local time, while
the last good config keeps ticking — and the broken file is never overwritten.

## IPC

```bash
omarchy-shell nerdnation.clockbar edit      # open the editor
omarchy-shell nerdnation.clockbar toggle
omarchy-shell nerdnation.clockbar refresh   # re-probe timezone offsets
omarchy-shell nerdnation.clockbar reload    # re-read clockbar.json
```

Bind the editor to a key in `~/.config/hypr/bindings.lua` if you want one.

## How it works, and why

Qt's QML engine ships **no `Intl`**, so there is no way to render an IANA
timezone from inside QML — the usual `Intl.DateTimeFormat({ timeZone })` route
does not exist. Rather than bundle a copy of the tz database, the plugin asks
the system's own tzdata for each zone's current UTC offset (`TZ=<zone> date +%z`)
and then does the arithmetic itself. That keeps it correct across DST changes
and tzdata updates without knowing any of the rules.

The probe is one short-lived shell, and its answer stays valid until a
transition, so it runs on a slow timer — every ten minutes, on each hour
boundary (where transitions land), and whenever the config changes. In between,
the clocks advance by arithmetic on the minute tick.

`ClockModel.js` holds all of that logic and touches no QML types, so it runs
unchanged under node:

```bash
node tests/model.test.js
```

## Layout

| File | Role |
|---|---|
| `manifest.json` | Plugin manifest — `kind: panel`, `keepLoaded` |
| `Clockbar.qml` | Entry point: the bottom layer-shell surface, one per screen |
| `Editor.qml` | The click-to-edit popup |
| `Config.qml` | `clockbar.json` — read, watch, write |
| `Zones.qml` | Timezone offset probe and the zone list for the picker |
| `ClockModel.js` | Ordering, formatting, day offsets, working hours (pure JS) |
| `tests/model.test.js` | Unit tests for the above |