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)

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

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.