# Tasks: Event List Temporal Grouping

**Input**: Design documents from `/specs/010-event-list-grouping/`
**Prerequisites**: plan.md, spec.md, research.md, data-model.md

**Tests**: Included — spec.md references TDD (Constitution II), and research.md explicitly plans unit + E2E test updates.

**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.

## Format: `[ID] [P?] [Story] Description`

- **[P]**: Can run in parallel (different files, no dependencies)
- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
- Include exact file paths in descriptions

---

## Phase 1: Setup

**Purpose**: No new project setup needed — this is a frontend-only enhancement to an existing codebase. Phase 1 is empty.

*(No tasks — existing project structure is sufficient.)*

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Create the core grouping composable and its types — all user stories depend on this logic.

**CRITICAL**: No user story work can begin until this phase is complete.

- [ ] T001 Define `SectionKey`, `EventSection`, and `DateGroup` types in `frontend/src/composables/useEventGrouping.ts`
- [ ] T002 Implement `useEventGrouping` composable with section classification, date grouping, and sorting logic in `frontend/src/composables/useEventGrouping.ts`
- [ ] T003 Write unit tests for `useEventGrouping` covering all four sections, empty-section omission, sort order, and Sunday edge case in `frontend/src/components/__tests__/useEventGrouping.spec.ts`

**Checkpoint**: Grouping logic is fully tested and ready for consumption by UI components.

---

## Phase 3: User Story 1 — Temporal Section Headers (Priority: P1) MVP

**Goal**: Events appear grouped under "Today", "This Week", "Later", and "Past" section headers. Empty sections are hidden.

**Independent Test**: Add events with various dates to localStorage, verify they appear under correct section headers.

### Tests for User Story 1

> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**

- [ ] T004 [P] [US1] Write unit tests for `SectionHeader.vue` rendering section label and emphasis flag in `frontend/src/components/__tests__/SectionHeader.spec.ts`
- [ ] T005 [P] [US1] Update `EventList.spec.ts` tests to expect grouped section structure instead of flat list in `frontend/src/components/__tests__/EventList.spec.ts`

### Implementation for User Story 1

- [ ] T006 [P] [US1] Create `SectionHeader.vue` component with section label (`<h2>`) and `aria-label` in `frontend/src/components/SectionHeader.vue`
- [ ] T007 [US1] Refactor `EventList.vue` template to use `useEventGrouping`, render `<section>` per temporal group with `SectionHeader`, and hide empty sections in `frontend/src/components/EventList.vue`
- [ ] T008 [US1] Update E2E tests in `home-events.spec.ts` to verify section headers appear with correct events distributed across "Today", "This Week", "Later", "Past" in `frontend/e2e/home-events.spec.ts`

**Checkpoint**: Event list shows temporal section headers. All four acceptance scenarios pass.

---

## Phase 4: User Story 2 — Date Subheaders Within Sections (Priority: P2)

**Goal**: Within each section (except "Today"), events are further grouped by date with formatted subheaders like "Wed, 12 Mar".

**Independent Test**: Add multiple events on different days within one section, verify date subheaders appear.

### Tests for User Story 2

> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**

- [ ] T009 [P] [US2] Write unit tests for `DateSubheader.vue` rendering formatted date label in `frontend/src/components/__tests__/DateSubheader.spec.ts`
- [ ] T010 [P] [US2] Add unit tests to `EventList.spec.ts` verifying date subheaders appear within sections and are absent in "Today" in `frontend/src/components/__tests__/EventList.spec.ts`

### Implementation for User Story 2

- [ ] T011 [P] [US2] Create `DateSubheader.vue` component with formatted date (`<h3>`) using `Intl.DateTimeFormat` in `frontend/src/components/DateSubheader.vue`
- [ ] T012 [US2] Update `EventList.vue` template to render `DateSubheader` within each section's date groups, skipping subheader for "Today" section (`showSubheader` flag) in `frontend/src/components/EventList.vue`
- [ ] T013 [US2] Add E2E test scenarios for date subheaders: multiple days within a section, no subheader in "Today" in `frontend/e2e/home-events.spec.ts`

**Checkpoint**: Date subheaders render correctly within sections. "Today" section has no subheader.

---

## Phase 5: User Story 3 — Enhanced Event Card Time Display (Priority: P2)

**Goal**: Event cards show clock time ("18:30") in Today/This Week/Later sections and relative time ("3 days ago") in Past section.

**Independent Test**: Check event cards display the correct time format based on which section they appear in.

### Tests for User Story 3

> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**

- [ ] T014 [P] [US3] Add unit tests to `EventCard.spec.ts` for `timeDisplayMode` prop: `'clock'` renders formatted time, `'relative'` renders relative time in `frontend/src/components/__tests__/EventCard.spec.ts`

### Implementation for User Story 3

- [ ] T015 [US3] Add `timeDisplayMode` prop (`'clock' | 'relative'`) to `EventCard.vue`, render clock time via `Intl.DateTimeFormat({ hour: '2-digit', minute: '2-digit' })` or existing `formatRelativeTime()` in `frontend/src/components/EventCard.vue`
- [ ] T016 [US3] Update `EventList.vue` to pass `timeDisplayMode="clock"` for today/thisWeek/later sections and `timeDisplayMode="relative"` for past section in `frontend/src/components/EventList.vue`
- [ ] T017 [US3] Add E2E test scenarios verifying clock time in future sections and relative time in past section in `frontend/e2e/home-events.spec.ts`

**Checkpoint**: Time display adapts to section context. All three acceptance scenarios pass.

---

## Phase 6: User Story 4 — Today Section Visual Emphasis (Priority: P3)

**Goal**: The "Today" section header is visually more prominent (bolder, slightly larger, accent border) than other sections.

**Independent Test**: Visual verification that "Today" stands out compared to other section headers.

- [ ] T018 [US4] Add `.section--today` CSS class to `SectionHeader.vue` with `font-weight: 800`, `font-size: 1.1rem`, and left border accent (`#F06292`) — triggered by `emphasized` prop in `frontend/src/components/SectionHeader.vue`
- [ ] T019 [US4] Verify `EventList.vue` passes `emphasized: true` for the "Today" section (already set via `EventSection.emphasized` from data model) in `frontend/src/components/EventList.vue`
- [ ] T020 [US4] Add visual E2E assertion checking that the "Today" section header has the emphasis CSS class applied in `frontend/e2e/home-events.spec.ts`

**Checkpoint**: "Today" section is visually distinct. Past events remain faded.

---

## Phase 7: Polish & Cross-Cutting Concerns

**Purpose**: Final validation and regression checks.

- [ ] T021 Run full unit test suite (`cd frontend && npm run test:unit`) and fix any regressions
- [ ] T022 Run full E2E test suite and verify all existing functionality (swipe-to-delete, role badges, empty state, navigation) still works in `frontend/e2e/home-events.spec.ts`
- [ ] T023 Verify accessibility: section headers are `<h2>`, date subheaders are `<h3>`, sections have `aria-label`, keyboard navigation works

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: Empty — no work needed
- **Foundational (Phase 2)**: No dependencies — can start immediately
- **US1 (Phase 3)**: Depends on Phase 2 (grouping composable)
- **US2 (Phase 4)**: Depends on Phase 3 (needs section structure in EventList)
- **US3 (Phase 5)**: Depends on Phase 3 (needs section context for time mode)
- **US4 (Phase 6)**: Depends on Phase 3 (needs SectionHeader component)
- **Polish (Phase 7)**: Depends on all user stories being complete

### User Story Dependencies

- **US1 (P1)**: Can start after Foundational — no dependencies on other stories
- **US2 (P2)**: Depends on US1 (needs section structure in template to add subheaders)
- **US3 (P2)**: Depends on US1 (needs section context to determine time mode), independent of US2
- **US4 (P3)**: Depends on US1 (needs SectionHeader component), independent of US2/US3

### Parallel Opportunities

- **Phase 2**: T001 must precede T002; T003 can run after T002
- **Phase 3**: T004 and T005 in parallel; T006 in parallel with tests; T007 after T006
- **Phase 4**: T009 and T010 in parallel; T011 in parallel with tests; T012 after T011
- **Phase 5**: T014 can start as soon as US1 is done; T015 after T014; T016 after T015
- **Phase 6**: T018 can run in parallel with Phase 5 (different files)
- **US3 and US4** can run in parallel after US1 completes

---

## Parallel Example: After US1 Completes

```bash
# These can run in parallel (different files, no dependencies):
Task: T009 [US2] Write DateSubheader unit tests
Task: T014 [US3] Write EventCard time mode unit tests
Task: T018 [US4] Add .section--today CSS to SectionHeader.vue
```

---

## Implementation Strategy

### MVP First (User Story 1 Only)

1. Complete Phase 2: Foundational (grouping composable + tests)
2. Complete Phase 3: User Story 1 (section headers in EventList)
3. **STOP and VALIDATE**: Test US1 independently
4. Deploy/demo if ready — list is already grouped with headers

### Incremental Delivery

1. Phase 2 → Grouping logic ready
2. Add US1 → Section headers visible → Deploy/Demo (MVP!)
3. Add US2 → Date subheaders within sections → Deploy/Demo
4. Add US3 → Context-aware time display → Deploy/Demo
5. Add US4 → Visual polish for "Today" → Deploy/Demo
6. Each story adds value without breaking previous stories