journeys today list - fahadahmed/jamaal-app GitHub Wiki

Today List

Status: reconciled with master summary v2 β€” draft, needs review. Layout grouped by primitive is kept; v2's guidance highlight, capacity filtering, deferral gestures and habit strip are folded in.

The single unified list spanning every category β€” the app's home screen ("One list. Just today. Beautifully ordered."). Replaces bouncing between separate reminder/task/calendar apps.

Today, as designed
Designed (TD-01)
Today, as built
Built

More screens are in the Screen gallery; how adding a task works is drawn in Diagrams.

Layout

Top to bottom:

  1. Capacity slider β€” today's low / medium / high.
  2. Companion card (when there is one) β€” at most one guidance card per day, inline-dismissible.
  3. Anchors β€” today's Anchors (those whose occurrenceDate is today: generated from rules, plus any one-offs), sorted by windowStart. Titles: a plain row shows the rule's title plus the slot label when it differs ("School run Β· Drop-off"); a grouped row is titled with the rule and lists members by slot label. Each shows its window state (upcoming / open / closing soon / closed) as a window bar, plus its outcome. Tapping marks attended β€” only while the window is open; while upcoming the control is disabled and says when it opens. "Not today" marks skipped and "Someone else did it" marks delegated, both any time before the window closes and neither a miss. missed is set automatically once the window closes with the Anchor still pending, and a missed Anchor offers "Mark as done after all" until the end of that day. An afterLast Anchor (plants) has a multi-day window and shows on every day it is open. Anchors are always shown, at every capacity level.
    • Grouped row per rule. A rule that yields more than one Anchor today (five prayers, drop-off and pick-up) shows as one collapsed row β€” the rule's title, a count of attended out of those still counting (skipped and delegated excluded, e.g. "Salah 3/5"), and the next pending window ("Asr Β· until 17:58"). Tapping expands it into the individual Anchors, each tappable as above. A rule with a single Anchor today, and every one-off, is a plain row. Grouping is display-only, like a habit group: no state of its own, and everything else (load, wellbeing, Night Planning review) reads the individual instances. Groups sort by their earliest window start; when everything in a group is decided, the row shows a quiet done state.
  4. Habits β€” today's due HabitTimeWindow occurrences (no streak counters β€” density lives on the habit detail), ordered groups first (as pills), then ungrouped habits by window start (all-day last), then title; a weekly-target habit shows every day until its week's target is met. Groups appear as a pill with proportional ring, name and count ("4/5"); tapping opens the group. Counted habits use an increment/decrement stepper in place of a single check; timed habits show minutes so far ("12 of 20 min") with Begin (the same ambient chip as a task) or a way to add minutes by hand; avoid habits show a quiet Log a slip action and a Held today tap, with no fill until the day resolves. Paused habits are hidden.
  5. Tasks β€” due today or overdue, plus a collapsed backlog. Tapping toggles complete; the row opens the task detail sheet. Each row shows its category as a coloured label.
  6. Also today β€” collapsed section for anything the current capacity hides, with a count.
  7. Plan tomorrow β€” a toolbar action (after Add) that opens Night Planning; after the planning time, if tonight is neither planned nor skipped, a quiet row for it appears too, and the all-done state carries the action.
  8. Add β€” opens the add sheet, which starts on Task and has a small Task | Anchor switch at the top (the One-off Anchor side takes a title, date, window start/end and optional duration). There is no separate chooser screen, so capturing a task is one tap. Recurring Anchors are created and managed in the Habits tab's Anchors segment.

Tasks are grouped by primitive, not by category. Within Tasks, order comes from the rules engine: hidden Eisenhower quadrant, then due date, which puts low tasks after medium/high β€” see rules-engine.md, module 1. The quadrant is never displayed. When the list has five or more tasks and fewer than two are medium/high, the companion may suggest picking one or two that matter most.

An optional category filter narrows the Tasks section to one category; Anchors and habits (which have no category) are always shown, the meter and load stay whole-day, and Start here is chosen from the visible tasks. It is local to the device, clears at the rollover and on relaunch, and never creates sections. An empty result reads "Nothing in Family today." with Show all.

Capacity slider

Sets today's capacity; the engine uses it to decide visibility (module 7):

  • low β€” Anchors, urgent-and-important tasks, and habits whose window is closing and not yet done. Everything else is under "also today".
  • medium β€” everything due except the least important, least urgent tasks.
  • high β€” everything due today.

Nothing disappears silently: hidden items sit under a collapsed "N more at higher capacity" affordance.

Set two ways: from Night Planning the evening before, or directly here if the day changes. The capacity meter (a thin pill under the slider) shows budget used β€” "2h 15m of 3h" β€” counting tasks only, plus a quiet load state (light / balanced / full / overloaded / exhausting). It turns terracotta when the day is overloaded or runs past the day's end (a user-set time, default 19:00) and then reads "40 min past 19:00", with one tap to move the overflow to tomorrow. Nothing is blocked. If a planned task is longer than the longest free block, a quiet flag says so. Capacity is the user's own call, not computed from the day's contents; the engine only suggests a level. Adding a task that tips the day over shows "Day is full Β· offer tomorrow" and never refuses it.

Task interactions

  • Complete: tap the check.
  • Detail sheet (bottom sheet): title, notes as a tappable markdown checklist, category, effort estimate, importance, due date, deferral history; actions β€” Defer, Drop (for a repeating task, skips only this occurrence), Stop repeating, and Begin, which starts a focus session (see Focus chip and sessions). Begin also appears on the "Start here" guidance card.
  • Defer: 1st and 2nd deferral moves the task to tomorrow instantly; from the 3rd a date picker opens with reason chips.
  • Add task (bottom sheet): title, effort (15 / 30 / 60 / 120 min shortcuts, Other… for any length, 30 preselected, or No estimate), notes, importance (low by default), category, schedule (Today / Tomorrow / Later this week / Next week / Someday / pick a date β€” see quick dates), repeat (Never / Daily / Weekly + days / Monthly β€” needs a date, hides Someday). Choosing medium/high importance makes the date required (pre-filled with today, not clearable) and hides Someday. A low task with no date is a backlog task.

Focus chip and sessions

Beginning a task starts a focus session (task.md). It is ambient, never modal: nothing blocks, and the whole app stays usable.

  • The chip sits above the tab bar and is present on every tab, as global chrome. It shows the task title and a count-up timer (monospaced digits so the numerals don't jitter). It is filled only while a session is live, and it looks the same when overrun β€” no red, no alarm.
  • Tapping the chip opens the focus screen: the timer, the task's note beneath it with tappable checkboxes, and Pause and Finish.
  • Finish opens a sheet showing actual against estimate with one optional note line and two buttons β€” Done (the task is complete) and Stop for now (time logged, task stays) β€” then, for Done, a quiet 5-second undo toast.
  • Timed habits use the same chip: Begin on a timed habit row starts a session against that habit's window; the chip reads the same, and finishing adds the minutes to today's entry.
  • Beginning a second task raises the settle sheet: Done, Stop for now, Defer to tomorrow, or Drop the running one first.
  • Near an Anchor the chip shows one line, never blocking: an open Anchor about to close ("Asr closes in 10 min") takes priority over a fixed Anchor about to open ("Maghrib in 12 min").
  • After the day rolls over (default midnight), a session that was still running was auto-closed at the boundary; tomorrow's list opens with one row offering to pick that task back up.
  • On wide layouts (iPad, Mac, Duo unfolded) the chip lives in the right-hand panel; see app-flow.md.
  • The Lock Screen Live Activity and Dynamic Island version is v1.1.

During-day guidance

At most one card per day. The engine highlights a task with a "Start here" or "Good now" pill and shows a companion card explaining why (heavier tasks in the morning, lighter ones in the early afternoon, open habit windows, remaining time vs. remaining effort). Tapping the card dismisses it inline.

Wellbeing

A compact sparkline near the capacity slider shows the wellbeing score over recent days ("gathering data" until seven active days exist). Tapping it opens the Wellbeing tab. It is fed by the engine's derived signals, not by Today interactions directly.

Empty and edge states

  • Nothing due at all: an encouraging empty state ("Your day is blank"), not a blank screen. When everything is done: a quiet celebration.
  • No plan was confirmed for today (Night Planning skipped or missed): one quiet card at the top, "No plan for today β€” two minutes to pick?", opening a shortened Build tomorrow for today. Shown once; no guilt, no count.
  • Notifications denied: an in-app banner at planning time β€” "Start evening planning β†’".
  • All sections hidden by capacity: a visible "N more at higher capacity" affordance.

Open questions

  • Backlog tasks (no dueDate): always visible in a collapsed "Backlog" section, or surfaced only in Night Planning's plan step?
  • Manual ordering: decided β€” none in v1 (engine order only); a hypothesis to validate in real use.
  • Anchors that end after midnight (Isha in summer): resolved β€” an Anchor belongs to the day its window starts (occurrenceDate). So a pending Isha can still be open when Night Planning runs late; it isn't shown as tomorrow's. With a user-set rollover, "belongs to the day it starts" uses the logical date.
  • Where the category filter lives (Today header vs. filter sheet) is a design-pass decision.
⚠️ **GitHub.com Fallback** ⚠️