PhoenixKitDashboards.Widgets.ClockWidget (PhoenixKitDashboards v0.1.0)

Copy Markdown View Source

Built-in "Clock" widget — the current time, ticking live, in one of three views, with a per-instance timezone.

This is the worked example for the richer parts of the widget contract:

  • Views with per-view minimums — "normal" (time + date), "digital" (large LCD-style digits) and "analog" (an SVG face) each declare their own min_size: the analog face needs a squarer box (2×2) than a line of digits (3×1). Resize limits, the settings modal, and view switching all honour the selected view's floor.
  • Per-instance settings — every placed clock has its own "timezone" and a "show_timezone" toggle (hide the label when a single local clock doesn't need it), so one dashboard can carry a world-clock row.
  • Live refresh — the catalog entry declares refresh_interval: 1000; the host send_update/2s the component every second and update/2 re-reads the time.

Timezones

"UTC" and fixed offsets ("UTC+2", "UTC-7", …) always work — the offset is plain arithmetic, no timezone database needed. IANA city zones ("Europe/Tallinn", …) are offered only when the HOST app configured a real time zone database (e.g. tzdata + config :elixir, :time_zone_database); a stored city zone that can't be resolved degrades to UTC rather than crashing the dashboard.

Summary

Functions

resolve_time(tz)

Resolve a timezone setting to {now, zone_label} — the shifted time plus the label to show. Fixed offsets are pure arithmetic; IANA zones go through DateTime.shift_zone/2 and degrade to UTC when no database can resolve them.

timezone_options()

The timezone choices for the settings select: UTC, IANA city zones when the host has a timezone database (checked live, so adding tzdata to the host lights them up after a registry refresh), and fixed UTC offsets — which are always correct by construction (they claim an offset, not a place).

Functions

resolve_time(tz)

@spec resolve_time(term()) :: {DateTime.t(), String.t()}

Resolve a timezone setting to {now, zone_label} — the shifted time plus the label to show. Fixed offsets are pure arithmetic; IANA zones go through DateTime.shift_zone/2 and degrade to UTC when no database can resolve them.

timezone_options()

@spec timezone_options() :: [String.t()]

The timezone choices for the settings select: UTC, IANA city zones when the host has a timezone database (checked live, so adding tzdata to the host lights them up after a registry refresh), and fixed UTC offsets — which are always correct by construction (they claim an offset, not a place).