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