calendar-plugin/requirements/editor.md

Calendar Editor Requirements

Purpose

Define implemented requirements for the authenticated calendar editor used from the /calendar UI.

Scope

This document covers:

• Event CRUD in the modal editor
• Supported event fields and validation
• Implemented recurrence options
• Recurrence preview and single-occurrence deletion UX

Access Model

• Public users are read-only.
• Plugin users in active status can create, update, and delete events.
• WordPress users with edit_posts capability can also perform write actions.

CRUD Requirements

The editor must support:

• Create event
• Edit event
• Delete event
• Delete one occurrence from a recurring event (exception-based, no series split)

Behavior requirements:

• Create/edit use modal overlay forms.
• Save/update/delete actions show status feedback.
• Delete event requires explicit user confirmation.
• Single-occurrence delete requires selecting a specific occurrence key.

Event Fields

Supported fields:

• title (required)
• visibility (public or private; default public)
• description
• location
• category
• all_day_event
• start_datetime (required)
• end_datetime (required, must be on/after start)
• repeat_type
• repeat_interval
• repeat_range_mode
• repeat_count
• repeat_until
• Monthly pattern fields: repeat_nth_mode, repeat_nth_day, repeat_nth_pos, repeat_nth_weekday

UI behavior requirements:

• Start and end use separate date and time controls.
• Date controls use date-picker inputs.
• Time controls hide when all_day_event is selected.
• Floating/persistent labels keep field purpose visible.
• Internal event ID is hidden from users.
• Editor must provide a control to mark events as public or private.

Recurrence Model

Supported repeat_type values:

• none
• daily
• weekly
• monthly
• yearly

Supported monthly modes:

• day_of_month (nth day)
• weekday_of_month (nth weekday, including last via negative position)

Supported range modes:

• none
• count
• until

Recurrence Preview and Occurrence Selection

• For recurring events, editor shows a 3-month occurrence chooser grid.
• Grid supports previous/next month paging.
• Selecting an occurrence sets the occurrence key used by Delete Occurrence.
• Deselect/reselect behavior must be supported.
• For repeat_type=none, occurrence controls remain hidden and delete-occurrence is disabled.

Verification Requirements

Acceptance should verify:

• Approved/authenticated users can complete full CRUD.
• Recurring events render selectable occurrences in preview grid.
• Deleting one occurrence creates an exception while preserving the series.
• Monthly ordinal patterns save and reload correctly.
• Validation blocks invalid start/end ranges.
• Privacy visibility setting saves and reloads correctly.