152 lines
7.1 KiB
Markdown
152 lines
7.1 KiB
Markdown
# 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)
|
||
|
||
## 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.
|
||
- `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.
|
||
- 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.
|