Split availability windows into bookable lesson-length slots with weekly calendar views

Availability windows were stored and served as a single bookable row, so a
9:00 AM-4:00 PM window showed to students as one giant slot and booking it
consumed the whole day; past and multi-day windows also leaked into the
booking page as nonsense entries.

- Split windows into consecutive lesson-length slots on save (REST and admin
  form); each chunk is independently bookable and weekly recurrence creates a
  series per chunk so "reserve this time weekly" holds the same hour each week
- Reject windows spanning multiple days or shorter than the lesson length
  (400 invalid_window)
- Never return slots whose start has passed from GET /availability
- Migrate pre-split rows: Plugin::boot re-runs the Installer on version change
  and AvailabilityRepository::splitOversizedWindows() rewrites unbooked
  same-day oversized windows in place
- Display all times in 12-hour AM/PM form (booking page, wp-admin lists,
  editor previews)
- Add a List | Week view toggle to the student booking page and the
  instructor availability page, with previous/next-week navigation honouring
  the site's start_of_week option (new WeekCalendar helper)

Co-Authored-By: Claude Fable 5 <[email protected]>

docs/features/availability-management.md

@@ -1,7 +1,7 @@
 # Feature: Availability Management
 
 ## Overview
-Instructors define date/time windows during which they are available for private lessons. Students book from these windows. Windows carry a lesson length and may be generated as a weekly-recurring series.
+Instructors define same-day date/time windows during which they are available for private lessons. On save, a window is split into consecutive lesson-length slots (09:00–16:00 with 60-minute lessons becomes seven rows), each independently bookable by students. Windows may be generated as a weekly-recurring series.
 
 ## Data Model — `{prefix}us_availability`
 
@@ -11,31 +11,43 @@ Instructors define date/time windows during which they are available for private
 | `instructor_id`    | BIGINT UNSIGNED  | WordPress user ID                                           |
 | `offering_id`      | BIGINT UNSIGNED  | Nullable FK → `us_offerings.id` (private-lesson type)       |
 | `start_dt`         | DATETIME         | Slot start — stored as `Y-m-d H:i:s`                        |
-| `end_dt`           | DATETIME         | Slot end — stored as `Y-m-d H:i:s`                          |
-| `duration_minutes` | SMALLINT         | Lesson length the window accommodates (e.g. 30, 60)         |
+| `end_dt`           | DATETIME         | Slot end — always `start_dt + duration_minutes`             |
+| `duration_minutes` | SMALLINT         | Lesson length (e.g. 30, 60)                                 |
 | `is_booked`        | TINYINT(1)       | 0 = available, 1 = booked                                  |
 | `recurrence_group` | BIGINT UNSIGNED  | Nullable — weekly-recurring windows share one group id     |
 | `created_at`       | DATETIME         | Insertion time                                             |
 
-A window's `duration_minutes` is matched against the offering a student picks: a
-30-minute private offering can only be booked into a window whose
+A slot's `duration_minutes` is matched against the offering a student picks: a
+30-minute private offering can only be booked into a slot whose
 `duration_minutes` accommodates it.
 
+## Window Splitting
+`AvailabilitySlot::splitByDuration()` chunks a submitted window into consecutive
+`duration_minutes` slots; `AvailabilityRepository::createFromWindow()` persists
+one row per chunk. A trailing remainder shorter than the lesson length is
+dropped. Windows must start and end on the same day and fit at least one lesson
+(REST responds `400 invalid_window` otherwise; the admin form is a no-op).
+`AvailabilityRepository::splitOversizedWindows()` is a data migration (run by
+`Installer` on activation or version change) that rewrites pre-split rows.
+
 ## Weekly-Recurring Windows
-Instructors may generate a window weekly across a date range. Each occurrence is a
-separate row sharing one `recurrence_group` id, so a recurring set can be added or
-removed together while individual occurrences are still booked independently.
+Instructors may generate a window weekly across a date range. Each lesson-length
+chunk becomes its own weekly series: occurrences of the same time-of-day share
+one `recurrence_group` id, so a recurring set can be added or removed together
+while individual occurrences are still booked independently.
 
 ## Admin Interface
 Instructors access **My Availability** in wp-admin (`?page=us-availability`).
-- Add a slot: provide start/end datetime, duration, and (optionally) a linked private-lesson offering
-- Add a weekly series: provide the weekday/time plus a date range
+- Add availability: provide a same-day start/end window, lesson length, and (optionally) a linked private-lesson offering
+- Add a weekly series: tick weekly repeat and choose the number of weeks
 - Delete a slot: only allowed if `is_booked = 0`
+- Current slots can be shown as a **list** or a **weekly calendar** (`usc_view=week`, navigated with `usc_week=Y-m-d`); the grid honours the site's `start_of_week` option via `Availability\WeekCalendar`
 
 ## Public Calendar
-The front-end booking shortcode renders a month/week calendar of open windows,
-populated from `GET /availability`. Students can filter by instructor and by
-offering/duration before selecting a slot to register for.
+The front-end booking shortcode renders open slots from `GET /availability`
+either as an agenda-style list grouped by day or as a **weekly calendar** with
+previous/next-week navigation (toggle rendered by `assets/js/booking.js`; the
+site's `start_of_week` option is passed through the `usScheduler` JS config).
 
 ## REST API
 | Method   | Endpoint                                      | Permission                         |
@@ -45,19 +57,27 @@ offering/duration before selecting a slot to register for.
 | `DELETE` | `/wp-json/us-scheduler/v1/availability/{id}`  | `manage_availability` + slot owner |
 
 `GET` supports query params: `instructor_id`, `offering_id`, `duration_minutes`, `from` (datetime), `to` (datetime).
+Slots whose start has already passed are never returned.
 
 `POST` validates `start_dt`/`end_dt` (admin form and REST alike) via
 `AvailabilitySlot::normalizeDateTime()`: the canonical `Y-m-d H:i[:s]` and HTML
 `datetime-local` (`Y-m-d\TH:i[:s]`) forms are normalised to `Y-m-d H:i:s`;
 anything else — or an end not after the start — is rejected (REST responds
-`400 invalid_datetime`; the admin form is a no-op).
+`400 invalid_datetime`; the admin form is a no-op). A valid window is stored as
+lesson-length slots and `201` returns `{ "ids": [...] }` for every row created.
+
+Times are displayed in 12-hour AM/PM form in the booking calendar and wp-admin
+lists.
 
 ## Implementation
 - Repository: `Unsupervised\Schedular\Availability\AvailabilityRepository`
 - Model: `Unsupervised\Schedular\Availability\AvailabilitySlot`
+- Week bucketing: `Unsupervised\Schedular\Availability\WeekCalendar`
 - Admin controller: `Unsupervised\Schedular\Availability\AvailabilityController`
 - REST endpoint: `Unsupervised\Schedular\Availability\AvailabilityEndpoint`
 
 ## Tests
 - `tests/Unit/Availability/AvailabilityRepositoryTest.php`
 - `tests/Unit/Availability/AvailabilitySlotTest.php`
+- `tests/Unit/Availability/AvailabilityEndpointTest.php`
+- `tests/Unit/Availability/WeekCalendarTest.php`