Add time-based offsets to the new sun event triggers

[MartinHjelmare]

Background

In 2026.7 we introduced a set of modern, class-based triggers for the sun domain: sun.sunrise, sun.sunset, sun.solar_noon, sun.solar_midnight, sun.dawn, and sun.dusk. These fire exactly at the computed solar event time.

See #1394 for that discussion.

When we designed them, we deliberately left out time-based offsets, for two reasons:

• The new event triggers themselves were expected to absorb most offset use cases. A large share of historical offsets were people approximating a specific solar moment that we now expose directly — most commonly a negative offset on sunrise/sunset used to stand in for dawn/dusk (e.g. "sunset minus 30 minutes" as a rough civil dusk). With dedicated sun.dawn / sun.dusk triggers (and their civil/nautical/astronomical phases), plus solar_noon and solar_midnight, those approximations became first-class events, so we assumed the offset was no longer needed to reach them.
• The elevation-based triggers were expected to cover the rest — and more correctly. For the remaining "some amount of light before/after an event" cases, an elevation threshold is a better tool than a fixed time offset, since a fixed offset from sunrise/sunset drifts with latitude and season while an elevation threshold does not.

Since release, community feedback has been consistent and clear that time-based offsets are still wanted, for reasons neither the new event triggers nor the elevation triggers address:

• Triggering before an event is otherwise impossible without templates. Triggering after an event can be approximated with a delay in the action, but there is no built-in way to fire before a future event. Today users must fall back to templates or a helper binary_sensor.
• Users think in "N minutes before sunset", not in degrees. Multiple users report that a fixed offset (e.g. 15 minutes before sunset, 1 hour before sunset) matches their lived experience of when it gets dark in their home, and they tune it empirically. Telling them the equivalent elevation angle is not a usable substitute.
• Some use cases are inherently time-relative. One user sends a "it's 15 minutes before sunset, get ready" reminder for events timed to sunset. An elevation-based reminder cannot state a fixed number of minutes, because the time-to-sunset for a given elevation varies through the year.
• Feature parity / discoverability. The legacy platform: sun trigger has always supported an offset, and the calendar.event_started / calendar.event_ended triggers already offer a before/after offset for precomputable events. Users reasonably expect the modern sun triggers to be at least as capable as the trigger they replace.

Crucially, unlike state-based triggers such as light.turned_on, sun events are known in advance — we already compute the next occurrence to schedule the trigger. This means an offset (including a negative "before" offset) is cheap and exact to apply: we simply shift the scheduled point in time. This is the same property that makes offsets sensible for calendar events.

Proposal

Add an optional time-based offset to the six precomputable sun event triggers (sunrise, sunset, solar_noon, solar_midnight, dawn, dusk), mirroring the existing calendar.event_started trigger for both UI and YAML.

Two options are added to each trigger:

• offset — a duration (duration selector in the UI).
• offset_type — before or after (select selector), defaulting to before.

Internally, a before offset is applied as a negative timedelta and an after offset as a positive one, then passed to the solar-event scheduler we already use. No new scheduling machinery is required; the underlying get_astral_event_next / get_observer_astral_event_next helpers already accept an offset argument, and this is the exact path the legacy trigger has always used.

Example:

trigger: sun.sunrise
options:
  offset:
    hours: 1
  offset_type: before

The elevation-based triggers (elevation_changed, elevation_crossed_threshold) are not in scope — they are state-based, not point-in-time events, so a time offset has no meaning for them.

Consequences

• Closes a real gap. Users can trigger before a sun event without templates or helper entities, and express "N minutes before/after" directly.
• Parity with the legacy trigger and with calendar. The modern triggers become a complete replacement for the legacy platform: sun offset behavior, and the offset UX matches calendar.event_started, so users encounter one consistent pattern.
• Consistent before/after UX. Following the calendar trigger, the sign of the offset is expressed through an explicit offset_type field rather than a negative number, which is clearer in the UI.
• No behavior change for existing automations. offset defaults to zero, so automations created before this change continue to fire at the exact event time.
• We accept the drift trade-off, by user choice. A fixed offset from sunrise/sunset varies in "elevation terms" across seasons and latitudes. This is a known limitation of time offsets and is exactly why we initially favored elevation triggers. The feedback shows that for many users a time offset is the intended behavior — they want a fixed clock offset, not a fixed sun angle — so we treat this as an explicit user choice rather than a defect. Both options remain available.
• Minor surface-area increase. Two extra fields on six triggers, documented and translated. Low maintenance cost given the shared schema fragment.

Alternatives

• Do nothing / point users at the new event and elevation triggers. This was the original design intent: dawn/dusk (and noon/midnight) would absorb the common approximations, and elevation triggers would cover the rest. Rejected because neither can express "before" a future event for reminders, neither can be tuned in intuitive time units, and the modern triggers remain less capable than the legacy trigger they replace. The feedback indicates this gap is not adequately covered.
• Signed offset without an offset_type field (negative duration means "before", as the legacy trigger does). Rejected for the modern triggers because a separate before/after selector is clearer in the UI and is the established pattern set by calendar.event_started; we prefer consistency.

[AJediIAm]

Not sure of it makes any sense, but I was thinking about an event helper which is pointed at a datetime entity to generate an event at that time or at an offset time. An event helper would allow users to work more easily with multiple events based on a single point in time.

Having an offset build into all triggers is probably better but this is (to my knowledge) not yet applied consistently.

[MartinHjelmare]

I don't understand how such an event helper is related to this proposal which is about sun triggers.

[AJediIAm]

Since release, community feedback has been consistent and clear that time-based offsets are still wanted`

Helpers could be an alternative way to satisfy the need for time-based offsets genetically instead of solving it fun sun only.

[MartinHjelmare]

Ah, ok. Thanks for the clarification. I think this can be investigated separately as desired.

[MaJerle]

Since release, community feedback has been consistent and clear that time-based offsets are still wanted`

Helpers could be an alternative way to satisfy the need for time-based offsets genetically instead of solving it fun sun only.

Wouldn't this imply a something like binary template sensor that will get on at sun event with offset, and we get back to the same underlying setup?

[abb848]

Discussed in Core meeting this morning (28th July) - we have agreed to approve this

[MartinHjelmare]

Core PR that implements the proposal:
home-assistant/core#176967