calendar-plugin/requirements/web-ui.md

# Web UI Requirements

## Purpose
Define requirements for the public-facing calendar web UI rendered by the plugin.

## Scope
This document covers:

- Shortcode-based rendering of calendar UI content
- View modes for event presentation
- Interactive event create/edit flows in the web UI for authorized users
- Public ICS subscription/export link behavior
- User login/registration/verification entry points used by the calendar page

## Shortcode Integration
The plugin must export a shortcode that renders the calendar web UI into page/post content.

Requirements:

- A plugin shortcode is registered and publicly documented (see `requirements/settings.md`).
- Rendering the shortcode generates HTML output representing calendar data.
- Shortcode output is safe for inclusion in standard WordPress pages/posts.
- Shortcode rendering must gracefully handle empty/no-event states.

## UI Views
The web UI must support selectable calendar views:

- Event list view
- Day view
- Week view
- Month view
- Year view

Behavior requirements:

- Users can switch between supported views from within the UI.
- View selection updates displayed event data accordingly.
- Current view state is visually clear.
- If no events match the current window/filter, show a clear empty-state message.

### Graphical View Requirements
- `week` view must render seven day columns.
- Timed events in `week` view must be positioned vertically by start/end time.
- All-day events in `week` view must appear at the top of each day column.
- `week` view must include a visible time scale on the left.
- Overlapping timed events in `week` view must remain readable (side-by-side or equivalent non-obscuring layout).
- `month` view must render a day-of-week grid where each cell represents one date in the month window.
- `month` view cells must list that day’s events in start-time order.
- `year` view must render twelve month blocks in a grid.
- Each year-view month block must render day cells in day-of-week order.
- In `year` view, day numbers with one or more events must be visually emphasized (for example bold text).
- Clicking a day in `year` view must switch to `week` view anchored to a week that includes the selected date.
- In `week` and `month` views, event display text must include start time before title for timed events.

### Display Filters
- UI must provide a `future dates only` filter control that limits display to today or later.
- In the current UX model, `future dates only` is visible and active only in list mode.

### Theme Selector
- UI must provide a theme selector with predefined visual themes.
- Theme switching updates shell/panel/list styling without reloading the page.

### Date Navigation Controls
- UI must provide previous and next navigation controls (left/right arrows) around a `today` control/icon.
- Previous/next controls shift the anchor date by one unit based on current view mode:
- Day/List: +/- 1 day
- Week: +/- 1 week
- Month: +/- 1 month
- Year: +/- 1 year
- UI must expose a single `Date` picker control.
- Arrow and `today` actions update `Date` to the first date of the current period for the selected view.
- Choosing a date must select the enclosing week/month/year period for those views, or the exact day in day view.

## Data Display Requirements
For each displayed event, UI should present core event information suitable for end users.

Minimum display requirements:

- Title
- Start date/time (or all-day presentation)
- End date/time where applicable
- Location (if provided)
- Category (if provided)
- Description excerpt/summary (if configured for display)

List-view formatting requirements:

- In `list` view, each row headline must present date, time range (or all-day marker), then title in readable natural-language order.
- Date formatting in `list` view should use long-form style (for example `5 April 2026`) rather than compact numeric-only format.
- Time range formatting in `list` view should be compact and human-readable (for example `9–10am`).
- Title must be sourced from event title data and must not be replaced by description text.
- If description is shown in `list` view, it should appear as secondary text below the headline.
- `list` view rows must not display default browser list bullets.

Privacy display rules:

- Public events render full details per normal display rules.
- Private events remain visible in chronological position for all viewers.
- In public (not logged-in) UI and sidebar rendering, private events must display:
  - Title as `Private Event`
  - Date/time fields as normal
  - No location/category/description content
- In logged-in write-capable UI, private events display full details.

## Web Event Editing UX (Authorized Users)
Where the viewer has write permission, the web UI must support event creation/editing.

Requirements:

- Create and edit actions open in an overlay/modal form.
- Start and end are entered with separate date and time controls.
- Date controls must use date-picker inputs.
- Irrelevant recurrence fields must be hidden based on current recurrence selections.
- Form controls use persistent inline/floating labels so field purpose remains visible after input.
- Event ID must not be shown in the UI.
- Create/edit panel must show current privacy (`public`/`private`) and allow changing it before save.
- `location` and `category` should be rendered on one row.
- `start date/time` and `end date/time` should be rendered on one row.
- `repeat type` and `every` interval should be rendered on one row.
- `range mode` and `repeat until` should be rendered on one row.
- Recurrence interval label text uses `Every` and includes a readable interval summary (for example `1 week`, `2 weeks`).
- The readable interval unit text should be integrated into the same interval control rather than a separate display-only field.
- Monthly recurrence must support both `nth day of month` and `nth weekday of month` patterns.
- A `Delete a Single Occurrence` action must be available when editing recurring events.
- `Delete Occurrence` may be shown inline with main modal action buttons.
- Single-occurrence controls appear whenever repeat type is not `none`.
- Single-occurrence controls must remain hidden when repeat type is `none`.
- Single-occurrence selection must be user-friendly via a date list or compact calendar selection.
- The compact selection mode should support a 3-month grid with previous/next navigation.
- The compact selection grid must remain readable in modal layout.
- Login, Event Details, and Event Editor overlays must render above site/theme chrome (for example header/banner artwork) and remain interactable without requiring page scroll workarounds.
- Login overlay should be centered within the viewport on desktop and mobile.
- Event click interactions must use in-page overlays and must not fall back to browser-native dialog boxes.

## Login and Access Modes
- `/calendar` must support two user modes: public (not logged in) and logged-in.
- Public mode is read-only.
- In public mode, private events are redacted (title `Private Event`; time preserved; non-time fields hidden).
- A `Login` action must open an in-page dialog.
- Login dialog must support credential login.
- Login dialog must support registration (registration is a request for approval/write access).
- Login dialog must support email verification token submission.
- Login dialog must support password-reset request initiation.
- Logged-in but non-approved users remain read-only.
- Approved users can perform event CRUD.
- Event-click behavior must be consistent between normal and private/incognito browser sessions.
- In public mode, clicking an event must open the Event Details overlay (not the Event Editor overlay).

## ICS Link in Web UI
The UI must include a user-visible link to an ICS representation of calendar data.

Requirements:

- A link/button is presented in the web UI for calendar subscription/export.
- Link target returns `text/calendar` output suitable for device calendar subscription/import.
- Link should be stable enough for user bookmarking/subscription where feasible.
- Canonical endpoint path and access policy must follow `requirements/ics_endpoint.md`.
- Link behavior is documented for users/admins in project docs.

## Accessibility and UX
- Controls for view selection must be keyboard-accessible.
- Output should be readable across desktop and mobile screen sizes.
- Time/date presentation should follow site locale/timezone behavior defined by plugin settings.
- Action buttons should be disabled (visibly greyed) when required input/permissions are not present.

## Security and Performance
- Shortcode rendering must sanitize/escape output appropriately.
- Querying calendar data for UI views should be efficient for expected dataset sizes.
- Public UI endpoints and ICS link handling must avoid leaking non-public admin-only data.

## Verification Requirements
Acceptance should verify:

- Shortcode renders without errors on standard WordPress pages.
- All five view modes are selectable and render expected event windows.
- Empty-state behavior is clear and user-friendly.
- ICS link is present and returns valid calendar payload.
- Privacy redaction behavior is correct in public views, sidebar, and logged-in views.
- In both normal and private/incognito sessions, clicking an event in public mode opens the same Event Details overlay.
- Login/Event Details/Event Editor overlays remain above site header/banner layers and are fully usable without scrolling to bypass theme artwork.