# Implementation Plan: Event List Temporal Grouping

**Branch**: `010-event-list-grouping` | **Date**: 2026-03-08 | **Spec**: `specs/010-event-list-grouping/spec.md`
**Input**: Feature specification from `/specs/010-event-list-grouping/spec.md`

## Summary

Extend the existing flat event list with temporal section grouping (Today, This Week, Later, Past). The feature is purely client-side: the existing `EventList.vue` computed property that separates events into upcoming/past is refactored into a four-section grouping with section headers, date subheaders, and context-aware time formatting. No backend changes, no new dependencies.

## Technical Context

**Language/Version**: TypeScript 5.9 (frontend only)
**Primary Dependencies**: Vue 3, Vue Router 5 (existing — no additions)
**Storage**: localStorage via `useEventStorage.ts` composable (existing — no changes)
**Testing**: Vitest (unit), Playwright + MSW (E2E)
**Target Platform**: PWA, mobile-first, all modern browsers
**Project Type**: Web application (frontend enhancement)
**Performance Goals**: Grouping computation < 1ms for 100 events (trivial — single array pass)
**Constraints**: Client-side only, no additional network requests, offline-capable
**Scale/Scope**: Typically < 50 events per user in localStorage

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

| Principle | Status | Notes |
|-----------|--------|-------|
| I. Privacy by Design | PASS | No new data collection. Grouping uses existing `dateTime` field. No external services. |
| II. Test-Driven Methodology | PASS | Unit tests for grouping logic + E2E tests for all user stories planned. TDD enforced. |
| III. API-First Development | N/A | No API changes — purely frontend enhancement. |
| IV. Simplicity & Quality | PASS | Minimal new code: one composable for grouping, template changes in EventList. No over-engineering. |
| V. Dependency Discipline | PASS | No new dependencies. Uses browser `Intl` API and existing `Date` methods. |
| VI. Accessibility | PASS | Section headers use semantic HTML (`<h2>`/`<h3>`), ARIA landmarks, keyboard navigable. WCAG AA contrast enforced. |

**Gate result: PASS** — no violations.

## Project Structure

### Documentation (this feature)

```text
specs/010-event-list-grouping/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── spec.md              # Feature specification
└── tasks.md             # Phase 2 output (via /speckit.tasks)
```

### Source Code (repository root)

```text
frontend/
├── src/
│   ├── components/
│   │   ├── EventList.vue          # MODIFY — add section grouping to template + computed
│   │   ├── EventCard.vue          # MODIFY — add time format mode prop
│   │   ├── SectionHeader.vue      # NEW — temporal section header component
│   │   └── DateSubheader.vue      # NEW — date subheader component
│   ├── composables/
│   │   ├── useEventGrouping.ts    # NEW — grouping logic (pure function)
│   │   ├── useRelativeTime.ts     # EXISTING — no changes
│   │   └── useEventStorage.ts     # EXISTING — no changes
│   └── components/__tests__/
│       ├── EventList.spec.ts      # MODIFY — update for grouped structure
│       ├── EventCard.spec.ts      # MODIFY — add time format tests
│       └── useEventGrouping.spec.ts # NEW — unit tests for grouping logic
├── e2e/
│   └── home-events.spec.ts       # MODIFY — add temporal grouping E2E tests
```

**Structure Decision**: Frontend-only changes. Two new small components (SectionHeader, DateSubheader) and one new composable (useEventGrouping). Existing components modified minimally.