Week View API Specification

Overview

This document specifies the API endpoints and data structures needed to support the week view dashboard.

Endpoints

GET /week

Returns the full week view page (week_view.html template).

GET /api/week-view

Returns the HTMX partial for the week view content.

Query Parameters:
- offset (optional): Number of weeks to offset from current week (e.g., -1, 0, 1)

Response: Renders partials/week_view_content.html with context:

{
  "week_range": "Apr 28 - May 4",  // Display text for current week
  "prev_week": -1,                  // Offset for previous week button
  "next_week": 1,                   // Offset for next week button
  "days": [
    {
      "day_name": "Mon",
      "day_number": "28",
      "is_today": false,
      "events": [
        {
          "id": "event-123",
          "title": "Soccer Practice",
          "time": "4:00 PM",        // null for all-day events
          "is_all_day": false,
          "member_class": "member-sullivan",  // member-matt, member-aundrea, member-sullivan, member-harper, member-family, member-multi
          "has_conflict": false
        }
      ]
    }
  ]
}

GET /api/event/{id}/detail

Returns event detail modal content.

Response: Renders partials/event_detail.html with context:

{
  "event": {
    "id": "event-123",
    "title": "Soccer Practice",
    "date": "Monday, April 28",
    "time": "4:00 PM - 5:30 PM",
    "location": "Green Bay Sports Complex",
    "members": "Sullivan",
    "description": "Bring water bottle and shin guards",
    "status": "Confirmed",           // Display text
    "status_class": "confirmed",     // CSS class: confirmed, pending, needs_confirmation
    "needs_action": false,           // Show Confirm/Decline buttons
    "has_conflict": false,
    "can_modify": true               // Show Edit button
  }
}

POST /api/event/{id}/confirm

Confirms attendance for an event.

Response: HTMX redirect or updated event detail partial.

POST /api/event/{id}/decline

Declines attendance for an event.

Response: HTMX redirect or updated event detail partial.

GET /api/event/{id}/reschedule-form

Returns reschedule form HTML.

GET /api/event/{id}/edit

Returns edit form HTML.

Family Member Color Classes

Conflict Detection

Events with has_conflict: true will show:
- Red left border
- ⚡ indicator
- Warning in event detail modal

Conflicts should be detected when:
1. Two events overlap in time for the same family member
2. Transportation conflicts (can't be in two places at once)
3. Parent availability conflicts

Responsive Breakpoints

• Desktop (>1024px): Full 7-column grid
• Tablet (641px-1024px): 7-column grid, smaller text
• Mobile (≤640px): Horizontal scroll, 85vw per day

Dark Mode

All colors use CSS variables that adapt via prefers-color-scheme: dark.
Background colors become semi-transparent overlays in dark mode.

HTMX Integration

The week view uses HTMX for:
1. Initial load: hx-get="/api/week-view" hx-trigger="load"
2. Week navigation: hx-get="/api/week-view?offset=N"
3. Event clicks: Open modal with event detail
4. Actions: Confirm/Decline/Reschedule with server updates
5. Live updates: Consider adding hx-trigger="every 30s" for polling

Implementation Notes

1. Week Calculation: Monday-Sunday week, with "today" highlighted
2. All-day Events: Render at top of day column, show 📌 prefix
3. Multi-day Events: Can span multiple day columns
4. Touch Targets: Minimum 44px on mobile/iPad
5. Accessibility: Consider adding ARIA labels for screen readers