A Timeline is a collection of entries with a reload policy.
It tells the system: here's all the data you need,
and here's when to ask me for more.

Core Structure

Timeline(entries: [SimpleEntry], policy: ReloadPolicy)

entries → array of SimpleEntry, each with a date
policy  → when should the system call timeline() again

From the Project

func timeline(for configuration: FocusWidgetIntent, in context: Context) async -> Timeline<SimpleEntry> {
    let index = selectedIndex(for: configuration.session)
    let entry = makeEntry(from: FocusState.all[index], index: index, date: Date())
    return Timeline(entries: [entry], policy: .never)
}

One entry → user pinned a specific session via intent
policy: .never → don't auto reload, user controls it

One Entry vs Multiple Entries

One entry:
→ widget shows the same thing until manually refreshed
→ used when user has configured a specific state (like this project)

Multiple entries:
→ widget automatically cycles through states over time
→ used when you want the widget to update itself

Multiple entries example:

// Original version before Intent Configuration was added
for (hourOffset, state) in FocusState.all.enumerated() {
    let entryDate = Calendar.current.date(byAdding: .hour, value: hourOffset, to: currentDate)!
    entries.append(makeEntry(from: state, index: hourOffset, date: entryDate))
}

return Timeline(entries: entries, policy: .atEnd)

Entry 0 → shown at 1:00 PM  (Focus)
Entry 1 → shown at 2:00 PM  (Break)
Entry 2 → shown at 3:00 PM  (Plan)
Entry 3 → shown at 4:00 PM  (Learn)
Entry 4 → shown at 5:00 PM  (Review)
→ at 5:00 PM policy kicks in → system calls timeline() again

Reload Policies

.never      → don't reload automatically
             used when: user controls the state via intent

.atEnd      → reload after the last entry's date passes
             used when: you have a fixed schedule of entries

.after(date)→ reload at a specific date
             used when: you know exactly when new data will be ready

How the System Uses It

timeline() returns Timeline
→ system looks at each entry's date
→ displays entry when its date arrives
→ when last entry passes → checks reload policy
→ policy says what to do next

Mental Model

Timeline     → the full schedule
Entry        → one item on that schedule
Reload Policy → what happens when the schedule runs out

In Production

timeline() would fetch live data from the main app via App Groups
then build entries based on real user activity
not hardcoded states like in this project