# Event Calendar

## Objective

Month, week, and list views of upcoming events people can browse and open.

A browsable calendar of events with month, week, and list views and linkable dates.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Build three views over one data source: month grid, week grid, and a chronological list. The list view is the mobile and screen-reader path and is not optional.
2. Give every view and date a URL that encodes the view, the anchor date, and any active filter, and reuse the app's existing Shareable Deep Links conventions so a pasted link opens exactly what the sender was looking at.
3. Fetch only the events overlapping the visible range, and prefetch the adjacent period so stepping forward and back feels instant.
4. Distinguish timed events from all-day events in the data model, not just in the rendering. An all-day event is a date, a timed event is an instant, and confusing the two is where the display bugs come from.
5. Do not hide overflow events behind a silent cutoff. If a day has more entries than fit, show an explicit count that opens the full day, so nothing disappears without the reader knowing.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Overlapping events in a week view must all remain visible. Lay them out side by side within the hour column or stack them with an explicit overflow control, but never drop one because two share a start time.
- A multi-day event has to span continuously across a week row and resume correctly at the start of the next row, with the ends marked so a reader can tell it continues rather than restarts.
- All-day events are calendar dates, not instants. Converting them through a time zone moves a holiday to the previous evening for anyone west of the origin, so render them from the date directly.
- Month navigation must stay responsive with hundreds of events in range. Query by overlap with the visible window and index the date columns rather than loading the year and filtering in memory.
- Every view and date needs its own address. Without one, a shared link drops the recipient on today rather than the date being discussed.
- Grid views are difficult to navigate with a keyboard or a screen reader. Provide the list view as an equivalent path and make it reachable, not just a narrow-screen fallback.
- Today must be marked according to the viewer's zone, and must update if the page is left open across midnight.
- A month with no events needs a real empty state pointing at the next period that has any, rather than a blank grid.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Month, week, and list views render from one event source and stay consistent.
- [ ] Overlapping events are all visible or reachable through an explicit overflow control.
- [ ] Multi-day events span week rows correctly with continuation marked at each edge.
- [ ] All-day events show on the same date regardless of the viewer's time zone.
- [ ] Navigating months with hundreds of events queries only the visible range.
- [ ] Every view and date has a shareable URL that reopens the same state.
- [ ] The list view offers full keyboard and screen-reader access to the same events.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.