menologion/README.md

# horologion

Desktop front ends for [`typikon`](https://git.pumpin.online/funkpower/typikon)
— the Orthodox liturgical day on your desktop, in Hyprland (Quickshell),
waybar or eww.

Everything is computed locally by `typikon`, so none of this touches the
network, and the widget re-reads only when the date rolls over — the answer
changes at midnight and at no other moment.

![The widget during the Nativity Fast](docs/nativity-fast.png)

## Install

`typikon` first, since all three front ends shell out to it:

```console
$ pip install typikon
$ typikon --set-default rocor     # or antiochian, oca, greece, ...
```

Then:

```console
$ git clone https://git.pumpin.online/funkpower/horologion
$ cd horologion && ./bin/horologion-install
```

That links rather than copies, so `git pull` updates what you are running. Pass
`quickshell`, `waybar`, `eww` or `bin` to do just one.

## Quickshell

A desktop widget for Hyprland and anything else Quickshell runs on.

```console
$ quickshell -p ~/.config/quickshell/horologion/shell.qml
```

It sits on the background layer, so it behaves like part of the wallpaper —
always under your windows, never stealing a click.

To drop it into a shell you already have:

```qml
import qs.horologion.modules

Horologion {}
```

Three pieces, each usable on its own:

| | |
|---|---|
| `services/Typikon.qml` | a singleton wrapping the CLI — bind to it from anything |
| `services/Theme.qml` | colours, from JSON, with defaults for every key |
| `modules/Horologion.qml` | the widget |

Set a jurisdiction per-widget if you want one different from your default:

```qml
Horologion {
    Component.onCompleted: Typikon.jurisdiction = "moscow"
}
```

### Colours

`Theme.qml` reads `~/.config/horologion/colors.json`, or whatever
`HOROLOGION_COLORS` points at, and watches it for changes. Every key has a
default, so the widget is legible with no file at all. See
`quickshell/colors.example.json` — the flat shape most theme generators
already emit.

## waybar

```jsonc
"custom/typikon": {
    "exec": "horologion-waybar",
    "return-type": "json",
    "interval": 1800,
    "on-click": "typikon --days 7"
}
```

The module's CSS class is the fast level — `.xerophagy`, `.wine_oil`, `.fish`
— so a day's discipline reads off the colour without reading the text.
`.obligatory` is added only where a particular law actually binds, which under
the Typikon is never: the Orthodox Church keeps the fast as tradition, not as
precept. `waybar/style.css` has a starting palette.

Change what the text says with `--format`:

```console
$ horologion-waybar --format '{emoji} {fastLabel}'
$ horologion-waybar -j moscow --format '{emoji} {churchDate}'
```

## eww

```lisp
(include "horologion/horologion.yuck")
```

Then `(horologion)` for the full panel or `(horologion-bar)` for one line.
`horologion.scss` carries the styling; its colours are `!default` variables, so
set your own before the `@import`.

## What it shows

The feast or the day's principal commemoration, the fast and why, the season,
the week ahead, and Pascha.

**The church date is always in the corner.** On the new calendar it echoes the
wall calendar; on the old it is the answer you came for. Below, ROCOR on 7
January — which is 25 December, and the Nativity.

![The Nativity on the old calendar](docs/old-calendar.png)

**Forefeasts, afterfeasts and leave-takings** get their own quiet line rather
than crowding out the commemoration that makes the day itself. They repeat for
days at a time, and a widget that leads with "Post-festive Day of the
Exaltation" for a week has told you nothing.

**The legend is built from the week in view**, not hardcoded, because the
levels a tradition uses are its own — six under the Typikon, three under
Ruthenian particular law — and the words for them differ too. Great Week uses
nearly all of them:

![Great and Holy Week](docs/great-week.png)

## Licence

GPL-2.0-only — see [LICENSE](LICENSE).