# 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.
