Add temporal grouping to event list (Today/This Week/Next Week/Later/Past)

Group events into five temporal sections with section headers, date subheaders,
and context-aware time display (clock time for upcoming, relative for past).
Includes new useEventGrouping composable, SectionHeader and DateSubheader
components, full unit and E2E test coverage.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

specs/010-event-list-grouping/spec.md

@@ -0,0 +1,138 @@
+# Feature Specification: Event List Temporal Grouping
+
+**Feature Branch**: `010-event-list-grouping`
+**Created**: 2026-03-08
+**Status**: Draft
+**Input**: User description: "Extend the event list with temporal grouping so users know if an event is today, this week, or further in the future."
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Temporal Section Headers (Priority: P1)
+
+As a user viewing my event list, I want events grouped under clear date-based section headers so I can instantly see what's happening today, this week, and later without reading individual dates.
+
+The list displays events under these temporal sections (in order):
+
+1. **Today** — events happening today
+2. **This Week** — events from tomorrow through end of current week (Sunday)
+3. **Later** — upcoming events beyond this week
+4. **Past** — events that have already occurred
+
+Each section only appears if it contains at least one event. Empty sections are hidden entirely.
+
+**Why this priority**: The core value of this feature — temporal orientation at a glance. Without section headers, the rest of the feature has no foundation.
+
+**Independent Test**: Can be fully tested by adding events with various dates to localStorage and verifying they appear under the correct section headers.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user has events today, tomorrow, next week, and last week, **When** they view the event list, **Then** they see four sections: "Today", "This Week", "Later", and "Past" with events correctly distributed.
+2. **Given** a user has only events for today, **When** they view the event list, **Then** only the "Today" section is visible — no empty sections appear.
+3. **Given** a user has no events at all, **When** they view the event list, **Then** the empty state is shown (as currently implemented).
+4. **Given** it is Sunday and an event is scheduled for Monday, **When** the user views the list, **Then** the Monday event appears under "Later" (not "This Week"), because the current week ends on Sunday.
+
+---
+
+### User Story 2 - Date Subheaders Within Sections (Priority: P2)
+
+Within each section (except "Today"), events are further grouped by their specific date with a subheader showing the formatted date (e.g., "Sat, 17 Sep"). This mirrors the inspiration layout where individual dates appear as smaller headings under the main temporal section.
+
+Within the "Today" section, no date subheader is needed since all events share the same date.
+
+**Why this priority**: Adds finer-grained orientation within sections — especially important when "This Week" or "Later" contain multiple events across different days.
+
+**Independent Test**: Can be tested by adding multiple events on different days within the same temporal section and verifying date subheaders appear.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user has events on Wednesday and Friday of this week, **When** they view the "This Week" section, **Then** events are grouped under date subheaders like "Wed, 12 Mar" and "Fri, 14 Mar".
+2. **Given** a user has three events today, **When** they view the "Today" section, **Then** no date subheader appears — events are listed directly under the "Today" header.
+3. **Given** two events on the same future date, **When** the user views the list, **Then** both appear under a single date subheader for that day, sorted by time.
+
+---
+
+### User Story 3 - Enhanced Event Card Information (Priority: P2)
+
+Each event card within the grouped list shows time information relevant to its context:
+
+- **Today's events**: Show the time (e.g., "18:30") prominently, since the date is implied by the section.
+- **Future events**: Show the time (e.g., "18:30") — the date is provided by the subheader.
+- **Past events**: Continue showing relative time (e.g., "3 days ago") as currently implemented, since exact time matters less.
+
+The existing role badges (Organizer/Attendee) and event title remain as-is.
+
+**Why this priority**: Completes the information design — users need different time representations depending on temporal context.
+
+**Independent Test**: Can be tested by checking that event cards display the correct time format based on which section they appear in.
+
+**Acceptance Scenarios**:
+
+1. **Given** an event today at 18:30, **When** the user views the "Today" section, **Then** the card shows "18:30" (not "in 3 hours").
+2. **Given** an event on Friday at 10:00, **When** the user views it under "This Week", **Then** the card shows "10:00".
+3. **Given** a past event from 3 days ago, **When** the user views the "Past" section, **Then** the card shows "3 days ago" as it does currently.
+
+---
+
+### User Story 4 - Today Section Visual Emphasis (Priority: P3)
+
+The "Today" section header and its event cards receive subtle visual emphasis to draw the user's attention to what's happening now. This could be a slightly larger section header, bolder typography, or a subtle highlight — consistent with the Electric Dusk design system.
+
+Past events continue to appear visually faded (reduced opacity/saturation) as currently implemented.
+
+**Why this priority**: Nice visual polish that reinforces the temporal hierarchy, but the feature works without it.
+
+**Independent Test**: Can be verified visually by checking that the "Today" section stands out compared to other sections.
+
+**Acceptance Scenarios**:
+
+1. **Given** events exist for today and later, **When** the user views the list, **Then** the "Today" section is visually more prominent than other sections.
+2. **Given** only past events exist, **When** the user views the list, **Then** the "Past" section uses the existing faded treatment without any special emphasis.
+
+---
+
+### Edge Cases
+
+- What happens when the user's device clock is set incorrectly? Events may appear in the wrong section — this is acceptable, no special handling needed.
+- What happens at midnight when "today" changes? The grouping updates on next page load or navigation; real-time re-sorting is not required.
+- What happens with an event at exactly midnight (00:00)? It belongs to the day it falls on — same as any other time.
+- What happens when a section has many events (10+)? All events are shown; no pagination or truncation within sections.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST group events into temporal sections: "Today", "This Week", "Later", and "Past".
+- **FR-002**: System MUST hide sections that contain no events.
+- **FR-003**: System MUST display section headers with the temporal label (e.g., "Today", "This Week").
+- **FR-004**: System MUST display date subheaders within "This Week", "Later", and "Past" sections when events span multiple days.
+- **FR-005**: System MUST NOT display a date subheader within the "Today" section.
+- **FR-006**: System MUST sort events within each section by time ascending (earliest first) for upcoming events and by time descending (most recent first) for past events.
+- **FR-007**: System MUST display clock time (e.g., "18:30") on event cards in "Today", "This Week", and "Later" sections.
+- **FR-008**: System MUST display relative time (e.g., "3 days ago") on event cards in the "Past" section.
+- **FR-009**: System MUST visually emphasize the "Today" section compared to other sections.
+- **FR-010**: System MUST continue to fade past events visually (as currently implemented).
+- **FR-011**: System MUST preserve existing functionality: role badges, swipe-to-delete, delete confirmation, empty state.
+- **FR-012**: "This Week" MUST include events from tomorrow through the end of the current calendar week (Sunday).
+
+### Key Entities
+
+- **Temporal Section**: A grouping label ("Today", "This Week", "Later", "Past") that organizes events by their relationship to the current date.
+- **Date Subheader**: A formatted date label (e.g., "Sat, 17 Sep") that groups events within a temporal section by their specific date.
+- **StoredEvent**: Existing entity — no changes to its structure are required. The `dateTime` field is used for all grouping and sorting logic.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: Users can identify how many events they have today within 2 seconds of viewing the list.
+- **SC-002**: Every event in the list is assigned to exactly one temporal section — no event appears in multiple sections or is missing.
+- **SC-003**: Section ordering is always consistent: Today > This Week > Later > Past.
+- **SC-004**: The feature works entirely client-side with no additional network requests beyond what currently exists.
+- **SC-005**: All existing event list functionality (delete, navigation, role badges) continues to work unchanged.
+
+## Assumptions
+
+- The user's locale and timezone are used for determining "today" and formatting dates/times (via the browser's `Intl` API, consistent with existing approach).
+- "Week" follows ISO convention where Monday is the first day of the week. "This Week" runs from tomorrow through Sunday.
+- The design system (Electric Dusk + Sora) applies to all new visual elements. The inspiration screenshot's color theme is explicitly NOT adopted.
+- No backend changes are needed — this is a purely frontend enhancement to the existing client-side event list.