native/CALENDAR_PLAN.md

React Native Calendar — Parity Plan

Bring repos/react-native/ calendar to parity with the webmail calendar at components/calendar/. Webmail totals ~5,940 lines across 19 components plus utility libs; mobile port targets ~2,500 lines with feature parity on the essentials and explicit deferrals for things that don't fit a phone UX.

Current state

• src/screens/CalendarScreenNew.tsx — month grid + agenda-for-selected-day, all rendering MOCK_EVENTS. Doesn't touch the store.
• src/stores/calendar-store.ts — CRUD wiring exists (fetchCalendars, fetchEvents, createEvent, updateEvent, deleteEvent) but no handleStateChange, no per-calendar visibility, no range tracking.
• src/api/calendar.ts — JMAP methods wired (Calendar/get, CalendarEvent/query, CalendarEvent/get, CalendarEvent/set).
• src/api/types.ts — CalendarEvent and Calendar types match webmail.
• No event modal, no detail view, no week/day view, no sidebar, no recurrence.

In scope

Phase 1 — Data layer (foundation for everything else)

src/stores/calendar-store.ts — expand to match webmail's store semantics:

• hiddenCalendarIds: Set<string> persisted via AsyncStorage (matches webmail's CalendarSidebar toggle state).
• loadedRange: { after: string; before: string } | null — track what's fetched so view changes don't re-fetch unnecessarily.
• ensureRange(after, before) — fetch only if the requested window isn't covered by loadedRange; expand the loaded range in place instead of replacing events wholesale, so switching Month → Week doesn't drop data.
• handleStateChange(change) — subscribe to Calendar and CalendarEvent typeState keys; on push, refetch calendars and re-query the current window. Already referenced from App.tsx push handler — this finally implements it.
• toggleCalendarVisibility(id) / setCalendarHidden(id, hidden).
• Selectors: visibleCalendars, visibleEvents (filtered by hidden set).

src/lib/calendar-utils.ts (new) — port from webmail's lib/calendar-utils.ts:

• parseLocalDateTime(iso) — JSCalendar start strings are floating local time (2026-04-20T09:00:00, no Z). Parse without timezone shifts.
• parseDuration(iso8601) — PT1H30M → milliseconds.
• eventTimeRange(event) — returns { start: Date, end: Date, allDay: boolean } handling showWithoutTime.
• eventsOnDay(events, day) — day overlap check (not just start-matches-day).
• getCalendarColor(cal) — fallback to a deterministic palette when color is missing, matching theme/tokens.ts colors.calendar.*.

src/lib/recurrence-expansion.ts (new) — minimal port of webmail's RRULE expander. Webmail's version supports byDay/byMonth/byMonthDay/count/until. Mobile port: same surface, same tests. This is the hard part — allocate ~400 lines. Drives correct rendering of recurring events across the visible window.

Phase 2 — Views

src/screens/CalendarScreenNew.tsx — replace mocks, gain view switching:

• On mount: fetchCalendars(), then ensureRange for visible window.
• View mode toggle → Month / Week / Agenda (Day view folded into Week for phone).
• Header shows month/week label; prev/next shifts by the current view's step.
• "Today" button resets both currentDate and selectedDate.
• FAB opens create modal with start = selectedDate at next half hour.

src/components/calendar/MonthView.tsx (extract from current screen, ~180 lines) — real events, up to 3 colored dots per day, "+N" indicator when more. Tap day → selects + scrolls agenda below. Long-press day → opens create modal with that date.

src/components/calendar/WeekView.tsx (new, ~350 lines) — port of calendar-week-view.tsx (511 lines) trimmed for mobile:

• 7 day columns, hour rows from 6am–10pm scrollable to 0–24.
• All-day strip at top.
• Events positioned absolutely by utcStart/utcEnd, width shared among overlapping events (port webmail's stacking algorithm).
• Tap event → detail modal. Long-press empty slot → create modal pre-filled.
• Horizontal swipe → prev/next week (react-native-gesture-handler already available via react-navigation).
• Deferred: drag-to-reschedule, drag-to-resize. Phone targets are too small for it to be better than tap-edit.

src/components/calendar/AgendaView.tsx (new, ~120 lines) — port of calendar-agenda-view.tsx. Flat list of upcoming events grouped by day, 30 days forward. Taps open detail modal.

Phase 3 — Event interaction

src/components/calendar/EventDetailSheet.tsx (new, ~280 lines) — bottom sheet presenting a single event, port of event-detail-popover.tsx (631 lines on web — phone version drops the hover card chrome and the inline-edit fields):

• Header: calendar color bar, title, date/time range (or "All day"), calendar name.
• Sections: location, description (linkified), participants with RSVP status, recurrence summary (e.g. "Weekly on Mon, Wed — until 2026-06-01"), reminders.
• Actions row: Edit, Delete, Duplicate, "Open in email" if created from invite.
• If recurring: delete/edit prompts via RecurrenceScopeDialog ("This event only" / "This and following" / "All events").

src/components/calendar/EventModal.tsx (new, ~550 lines) — full-screen modal for create + edit, port of event-modal.tsx (1,072 lines on web, trimmed):

• Title, calendar picker (color swatches), all-day toggle.
• Start/end date+time pickers (@react-native-community/datetimepicker — add dep).
• Location, description (multiline).
• Participant input with autocomplete from contacts store (port of participant-input.tsx, ~180 lines).
• Repeat picker: None / Daily / Weekly (weekday chips) / Monthly / Yearly, plus end: Never / After N / On date. Advanced iCal rules (BYSETPOS etc.) are deferred — covers the 95% case.
• Alerts: None / At start / 5m / 15m / 30m / 1h / 1d before, mapping to Alert.trigger.offset.
• Timezone: default to device TZ; optional override picker hidden behind "Advanced" disclosure.
• Save path handles "this instance only" override vs master update for recurring events (write to recurrenceOverrides[recurrenceId]).

src/components/calendar/RecurrenceScopeDialog.tsx (new, ~90 lines) — direct port of recurrence-scope-dialog.tsx. Three-button picker before edit/delete of a recurring instance.

Phase 4 — Multi-calendar

src/components/calendar/CalendarSidebarDrawer.tsx (new, ~200 lines) — port of calendar-sidebar-panel.tsx (273 lines). Slides in from the left (reuses SidebarDrawer.tsx):

• List of calendars with color swatch + visibility toggle + name.
• "My calendars" vs "Subscribed" sections if myRights differs.
• Tap calendar → highlight; long-press → rename/color/hide (optional, phase 4.5).
• Footer: "Add calendar" (deferred to Phase 6).

src/theme/tokens.ts — audit colors.calendar.* palette against webmail's calendar color constants (lib/calendar-utils.ts CALENDAR_COLOR_PALETTE); add any missing shades.

Phase 5 — Polish

• Pull-to-refresh on each view → forces re-fetch of current window.
• Empty states per view (no calendars yet / no events this month).
• Loading skeleton for month grid and week grid.
• Error banner when fetch fails (pattern from EmailListScreen).
• Respect email-store push via handleStateChange so events update live when another client creates one.

Explicitly deferred (out of scope)

These are in the webmail but don't make sense for a first mobile pass:

• iCal import/subscribe modals (ical-import-modal.tsx 455 lines, ical-subscription-modal.tsx 220 lines) — file picker + URL subscription with auth flows. Better as a dedicated settings flow later.
• Tasks module (task-list-view.tsx, task-modal.tsx, task-toolbar.tsx) — JSCalendar @type: 'Task' is a separate surface from events; worth its own screen, not bolted onto calendar.
• Drag to reschedule / resize — mobile tap targets are too small for the fine-grained control the web drag gives; tap-edit is the mobile idiom.
• Quick event input (quick-event-input.tsx) — NLP parser ("Lunch tomorrow at noon"). Neat on desktop, marginal on phone where typing is already slow.
• Event context menu (event-context-menu.tsx) — right-click is desktop- only. Actions move into the detail sheet's action row.
• Mini-calendar (mini-calendar.tsx) — web uses it as a sidebar date picker. Mobile already has the main month view; redundant.
• Birthday calendar auto-derived events — lower priority; leave the contacts-store integration for a follow-up.

Dependencies to add

• @react-native-community/datetimepicker — native date/time pickers.
• react-native-reanimated is already in (via react-navigation); reuse for bottom-sheet animations on EventDetailSheet.
• No new calendar library — reimplement RRULE expansion in ~400 lines rather than pulling in rrule.js (which adds ~180KB and expects browser APIs).

File map (new / modified)

repos/react-native/src/
├── screens/
│   └── CalendarScreenNew.tsx                  [rewrite]
├── components/
│   └── calendar/                              [new directory]
│       ├── MonthView.tsx                      [new]
│       ├── WeekView.tsx                       [new]
│       ├── AgendaView.tsx                     [new]
│       ├── EventCard.tsx                      [new]
│       ├── EventDetailSheet.tsx               [new]
│       ├── EventModal.tsx                     [new]
│       ├── ParticipantInput.tsx               [new]
│       ├── RecurrenceScopeDialog.tsx          [new]
│       ├── CalendarSidebarDrawer.tsx          [new]
│       └── index.ts                           [new]
├── stores/
│   └── calendar-store.ts                      [extend]
├── lib/
│   ├── calendar-utils.ts                      [new]
│   └── recurrence-expansion.ts                [new]
└── theme/
    └── tokens.ts                              [audit calendar palette]

Testing approach

• vitest.config.ts already exists. Unit tests for:
  • recurrence-expansion (daily/weekly/monthly, count+until, byDay).
  • calendar-utils (duration parse, all-day overlap, DST boundary).
  • Store: ensureRange dedup, handleStateChange refetch trigger.
• Manual emulator test matrix:
  • Create event (timed, all-day, recurring), verify server round-trip.
  • Edit recurring event via scope dialog.
  • Delete recurring instance vs series.
  • Toggle calendar visibility, confirm events disappear.
  • Push update from webmail, confirm mobile refreshes.

Build order (suggested)

1. Phase 1 in full — nothing else works without real data.
2. MonthView + EventDetailSheet (read path) — first thing user sees.
3. EventModal create path — unblocks manual testing of write path.
4. AgendaView + CalendarSidebarDrawer — pulls the rest of month together.
5. WeekView — biggest UI, easiest to defer if time runs short.
6. EventModal edit + recurrence scope — finishes the edit surface.
7. Phase 5 polish.

Rough size estimate: ~2,500 lines of new RN code + ~300 lines of store/util changes. Each phase is ship-safe on its own — the app stays functional even if we stop at Phase 2.