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