@spec database() :: module()

The timezone database backing every lookup here.

Passed explicitly to DateTime.shift_zone/3 rather than set as config :elixir, :time_zone_database: this is a library, and a library reaching into the host's Elixir config to swap a global would decide for every other dependency in the app too.

@spec day_start(String.t() | nil, DateTime.t() | nil) :: DateTime.t()

The UTC instant at which the current day began in value.

For "how many X happened today", where today is the operator's day and not UTC's. Getting this wrong is invisible most of the day and then wrong every evening: a site on Europe/Tallinn (UTC+3) counting from UTC midnight loses everything between 21:00 and midnight local, every night.

at overrides "now", for tests and for asking about another moment. Falls back to UTC midnight when the value cannot be resolved.

Examples

iex> PhoenixKit.Utils.TimeZone.day_start("0", ~U[2026-09-05 14:00:00Z])
~U[2026-09-05 00:00:00Z]

iex> PhoenixKit.Utils.TimeZone.day_start("2", ~U[2026-09-05 00:30:00Z])
~U[2026-09-04 22:00:00Z]

@spec effectively_same?(String.t() | nil, String.t() | nil) :: boolean()

Whether a and b render the same wall-clock time right now.

same_group?/2 only ever returns true for two identifiers — a legacy offset is not a group member, so comparing a browser-detected zone against a site's time_zone setting (which is the legacy offset "0" on every install that has never touched that setting) always failed same_group?, even from a browser genuinely on UTC+0. This compares current effective offset instead, which is defined for a legacy offset too.

@spec from_wall(NaiveDateTime.t(), String.t() | nil) :: {:ok, DateTime.t()} | :error

Reads a wall-clock NaiveDateTime as local time in value, returning UTC.

The inverse of shift/2, for a datetime-local input: the person typed 09:00 meaning 09:00 where they are, and it has to be stored as an instant.

Daylight saving makes this genuinely ambiguous twice a year. An hour that happens twice resolves to the first occurrence, and an hour that never happens resolves to the instant the clocks jump to — both deterministic, and both closer to what someone typing a time expects than an error would be.

Returns {:ok, datetime} or :error.

@spec group_for(String.t()) :: String.t() | nil

The representative zone for whichever group zone belongs to, or nil.

@spec identifier?(term()) :: boolean()

Whether value is one of the selectable IANA identifiers.

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

Every selectable IANA identifier, sorted.

@spec label(String.t() | nil) :: String.t()

Human label for a stored value — an IANA id, a legacy offset, or nothing.

Examples

iex> PhoenixKit.Utils.TimeZone.label("Europe/Warsaw") =~ "Europe/Warsaw"
true

iex> PhoenixKit.Utils.TimeZone.label(nil)
"Use System Default"

@spec legacy_offset?(term()) :: boolean()

Whether value is a pre-IANA numeric offset, e.g. "2", "-5", "5.5".

Kept working by shift/2, but the UI should offer to replace it: the number says nothing about where the account holder is, so it cannot follow DST.

@spec offset_seconds(String.t() | nil, DateTime.t() | nil) :: integer()

Offset from UTC in seconds for either kind of stored value.

A legacy offset ("2", "-5", "5.5") is that offset. An IANA id has no single answer — Europe/Warsaw is +1 in January and +2 in August — so it is resolved at an instant, at or now.

That snapshot is the honest limit of this function, and callers doing date arithmetic across a daylight-saving boundary want shift/2 or from_wall/2 instead, which are correct per-instant. It exists because several call sites genuinely need a scalar (a window offset, a comparison), and the alternative they had was Float.parse/1 returning 0 for every named zone — silently computing in UTC on any site that used the picker, which since the move to IANA ids is every site that touched the setting.

Unresolvable values give 0, the same safe default as before.

Examples

iex> PhoenixKit.Utils.TimeZone.offset_seconds("2")
7200

iex> PhoenixKit.Utils.TimeZone.offset_seconds("5.5")
19800

iex> PhoenixKit.Utils.TimeZone.offset_seconds("nonsense")
0

@spec options(keyword()) :: [{String.t(), String.t()}]

Picker options as {label, identifier}, ordered by current UTC offset.

One row per behaviour group — 59, not 447 — so the list stays browsable while every row remains a real zone that follows its own daylight-saving rule. Selecting a row stores that group's representative; everyone in the group behaves identically all year, so the choice is right for all of them.

Offsets are computed now, not baked into the string: the central-European row reads (UTC+01:00) in January and (UTC+02:00) in July. Freezing that number is what made the old list wrong for half the year.

Pass the currently-stored value as :selected. When it is a zone that is not itself a representative — the usual case once detection has stored somewhere precise like Europe/Tallinn — it is prepended as its own row, so the list stays short without ever misreporting what is saved.

@spec representative?(String.t()) :: boolean()

Whether zone is one of the group representatives the picker lists directly.

@spec same_group?(String.t() | nil, String.t() | nil) :: boolean()

Whether two zones behave identically all year — same offset, same DST rule.

Used by the mismatch check: someone detected in Europe/Tallinn whose account says Europe/Helsinki is not misconfigured, because the two never disagree.

@spec shift(DateTime.t(), String.t() | nil) :: DateTime.t()

Moves datetime into the zone named by value.

An identifier goes through DateTime.shift_zone/3, so DST is applied for the instant being shown rather than for the moment the preference was saved. A legacy offset is added as a fixed number of seconds. Anything unusable — including a zone the database cannot resolve — returns datetime untouched, because a page of timestamps is worth more than a crash over a preference.

@spec valid?(term()) :: boolean()

Whether value is storable — an identifier, a legacy offset, or blank.