RFC 0004: SalahWidgets and SalahUI

[omar-hanafy]

Comments on RFC 0004, the contract of SalahWidgets and SalahUI: shared values, widget timelines the extension builds by itself, signals to a running app, and SwiftUI components with styles you replace. An outside API review of this RFC is still pending.

The RFC stays open to findings from apps that use SalahKit until 1.0 (STANDARD.md, Releases). If an API doesn't fit your app, say what the app does, what it needs and what you tried. Changes to the API follow the RFC process in CONTRIBUTING.md.

[omar-hanafy]

RFC 0004 amendment for SalahKit 0.4.0

Open-issues amendment for 0.4.0 (2026-10-14)

The maintainer waived the one-week comment window for issues #12, #13 and #14, which are
pre-1.0 additions. Later API changes follow CONTRIBUTING's RFC process.

#13: a shared focus. PrayerFocus is a nonisolated, Sendable value with
countdown(PrayerEvent) and countUp(PrayerEvent), event and isCountUp. Its failable
init(state:selection:) centralizes selection. Selection offers nextPrayer (the existing
default), nextEvent (sunrise included), justStartedOrNextPrayer and
justStartedOrNextEvent. The latter two prefer state.justStarted while Core says it is
inside its window. They never infer an event from incomplete coverage.

NextPrayerView accepts the same selection, defaulting to nextPrayer. Its style gets
focus; the existing name, abbreviation and time describe that focus. countdown is set
only for a countdown and the new countUp only for a count-up. Both use the existing
live/static mode; elapsed text is unsigned, so a style supplies its own sign or wording.
justStarted remains the separate just-started name for existing styles. The plain style
shows the count-up in place of the countdown and avoids repeating its name as a caption.

Salah uses justStartedOrNextEvent across its menu and widget; MenuBar uses it in its title,
dropdown and widget. Both remove their own selection branches. Salah retains its last-minute
live timer, reminder phrases and colors: these are presentation choices, not shared policy.

#12: missing rows. PrayerTimesList accepts missing: [PrayerKind: ScheduleGapReason] = [:].
With gaps present it merges known events and missing kinds in canonical order; a known event
wins a conflicting key. The row configuration gains kind and gapReason; event and time
become optional. A missing row has no event, time, status or countdown, a zero day offset and
no offset text. The plain style shows a dash. Existing known-only lists keep their event order.
The public rows view is transparent so a consumer's stack owns its flexible row heights and
focus priority; the list's default body still supplies a vertical stack. CalculatedPhone uses
the API for partial days, and Salah uses it for widget and dropdown rows. Existing styles must
unwrap the event or use kind, and provide a fallback for time.

#14: civil-day entries. PrayerTimelineBuilder adds includeDayBoundaries: Bool = false.
PhoneWidgets, MenuBar and Salah pass true for widgets that list the current day's prayers,
replacing their provider loops. The builder merges each civil day's first instant in the
schedule's time zone with refresh dates, evaluates state there using the same policy and
lookahead derived from the clamped horizon, and removes duplicate dates. Calendar-day starts
honor DST and skipped dates. The entry budget includes these dates and the final expired
entry; validity ends at the first omitted date and reload remains halfway to that cutoff.
A boundary at the first entry or validUntil adds no duplicate schedule entry. Default behavior
is unchanged.

Implementation and verification are tracked in PR #17.