useCalendarEvents

Transforms task instances into CalendarKit event blocks with status-based coloring.

useCalendarEvents

Source: hooks/calendar/useCalendarEvents.ts (78 lines)

The useCalendarEvents hook transforms raw task instances from the Convex backend into CalendarKit-compatible event objects with status-based color coding and flicker-free loading.

---

Data Pipeline

Convex Query (byRange)
    │
    ├── instances[] from server
    │
    ├── Color Assignment (per task_id)
    │       → Deterministic color from TASK_COLORS palette
    │
    ├── Status Resolution
    │       → Checks verification_style + checkpoint statuses
    │       → Overrides color for proceeded/failed/waiver_active
    │
    └── CalendarEvent[] mapping
            → { id, title, start, end, color, originalData }

---

Color Logic

Each task gets a deterministic color from the TASK_COLORS palette, assigned by insertion order. Status overrides change the event color:

Status	Color	Hex
Default (pending/proceeding)	Task-specific palette color	varies
proceeded / waived	Success Green	#4CD964
failed / penalized	Danger Red	#FF3B30
waiver_active	Warning Orange	#FF9F0A

---

Verification Resolution

For “just_show_up” verification style, the hook resolves the effective status by checking if all checkpoint verification statuses are “verified”:

if (style === "just_show_up" && Array.isArray(inst.checkpoints)) {
  const cp = inst.checkpoints[0];
  const statuses = cp.verification_status || {};
  const allVerified = Object.keys(statuses).every(
    key => statuses[key] === "verified"
  );
  if (allVerified) effectiveStatus = "proceeded";
}

---

Flicker Prevention

The hook caches the previous event array in a useRef. When the Convex query is refetching (instances === undefined), it returns the cached events instead of an empty array, preventing visual flicker during tab switches or foreground transitions.

---

Return Value

Field	Type	Purpose
events	CalendarEvent[]	Mapped events for CalendarKit rendering
isLoading	boolean	True while instances are being fetched

Events are returned locally and NOT pushed to the CalendarStore Zustand store. This design prevents cascade re-renders in other components (like EventDetailModal) that previously subscribed to the events array.