Widget Functionality

What it does

The clock widget renders a responsive grid of clock cards based on the configured list of timezones. Each card shows:

  • The configured identifier (IANA timezone or LST token) exactly as configured.

  • The UTC offset, plus an optional day label for the local timezone (weekday, day, month).

  • The current time (24-hour format with seconds).

  • For IANA timezone cards, compact sunrise and sunset chips with simple up/down arrows. These always reflect the local time in that timezone; hovering a chip shows a tooltip that reiterates the label (Sunrise/Sunset) and clarifies that the value is local.

Text sizing behavior

  • The widget always auto-fits card content to the available widget size.

  • Card spacing is also configurable with clockGap (in pixels).

  • Optional configuration caps are available for each text zone:

    • topTextMaxSize caps the top row text.

    • middleTextMaxSize caps the main time text.

    • bottomTextMaxSize caps solar row text.

  • When any of these values are left unset, that section remains fully auto-sized.

  • When set, the value is used as a maximum; the widget still attempts to fill space, but it will not exceed the configured cap.

Data sources & updates

  • IANA wall-clock time / date come from the browser via Intl.DateTimeFormat, refreshed once per second with a lightweight setInterval.

  • Sidereal tokens (LST, LST@<longitude>) are computed in-widget each second using a local sidereal time approximation.

  • In addition, for IANA entries, the widget performs two GraphQL lookups via the Octopus host:

    • locationsByTimezone(timezones: [String!]!) resolves each configured timezone to a canonical location record (lat/lon, offset, etc.).

    • solarCycle(latitude, longitude, timezone, date) returns sunrise, sunset, dawn, and dusk values for the resolved coordinates.

  • Both queries are polled using the dashboard-provided refresh cadence so solar data stays current alongside the clocks.

Understanding LST

LST means Local Sidereal Time, which is different from normal solar time (UTC, local civil time, etc.).

  • Solar time is based on the Sun and the ~24-hour solar day.

  • Sidereal time is based on Earth’s rotation relative to distant stars (~23h 56m).

  • A sidereal day is therefore about 4 minutes shorter than a solar day, which is why stars appear roughly 4 minutes earlier each night.

LST answers this question:

  • Which Right Ascension (RA) is on the local meridian (highest in the sky) right now?

Example:

  • If LST = 10h, objects with RA = 10h are crossing the local meridian.

This is why LST is useful for astronomical observing windows and scheduling.

LST vs LST@116.7

  • LST uses Greenwich longitude (0°).

  • LST@116.7 uses longitude 116.7°.

Longitude matters because Earth rotates 360° in 24 hours (15° per hour), so changing longitude shifts local sidereal time.

Simplified formula

Start from Greenwich Sidereal Time (GST) and apply longitude:

LST = GST + (longitude / 15)

Longitude is in degrees and converted to sidereal hours by dividing by 15.

Why LST cards do not show sunrise/sunset

  • Sunrise and sunset are solar events.

  • LST is not based on the Sun; it is based on stellar reference.

  • Therefore, LST cards intentionally hide sunrise/sunset chips.

Shortcut:

  • Solar time asks: “Where is the Sun?”

  • Sidereal time asks: “Which RA is overhead now?”

Notes and limitations

  • Sunrise/sunset strings are normalised to 24-hour HH:mm for IANA cards. If the upstream API omits an explicit timezone offset, the widget preserves the provided local value instead of assuming UTC.

  • If an invalid timezone identifier is provided, the corresponding card shows an error state so you can correct the input quickly.

  • The widget assumes the hosting environment (browser) supports the specified IANA identifiers. Older browsers with limited timezone data may not show some regional names.