jackboxpartypack-gamepicker/docs/superpowers/specs/2026-03-23-pagination-day-grouping-design.md

Pagination & Day Grouping — Design Spec

Date: 2026-03-23 Status: Approved

Overview

Two enhancements to the session History page:

1. Pagination — When "Show X" is set to a value other than "All", add Prev/Next navigation to access older sessions.
2. Day Grouping — Group sessions that occurred on the same calendar day under a shared header bar.

Backend Changes

GET /api/sessions — New offset parameter

Add an offset query parameter (default 0) to the existing endpoint. Works with the existing limit, filter, X-Total-Count, and X-Absolute-Total headers.

GET /api/sessions?filter=default&limit=5&offset=10

Offset validation: Non-numeric or negative values are clamped to 0. An offset past the end returns an empty array (the pagination bar will show "Page X of Y" and the user can navigate back).

New response header:

• X-Prev-Last-Date — When offset > 0, the raw SQLite created_at timestamp (same format as created_at in response body, e.g. "2026-03-23 19:30:00") of the session immediately before the current page (the session at position offset - 1). Used by the frontend to detect whether the first day group on the current page is a continuation from the previous page. Omitted when offset is 0. The frontend parses this with the existing parseUTCTimestamp utility.

SQL changes: Add OFFSET clause to the existing query. For X-Prev-Last-Date, run a small secondary query to fetch the created_at of the session at position offset - 1 (same filter/ordering).

No other backend changes required.

Frontend Changes

State

• page (number, default 1) — current page number. Derived from offset: offset = (page - 1) * limit. Not persisted in localStorage; resets to 1 on navigation.
• prevLastDate (string|null) — from X-Prev-Last-Date header. Used for "(continued)" detection.

Page math

totalPages = Math.ceil(totalCount / limitNum)
offset = (page - 1) * limitNum

When limit is "all", pagination is disabled (no offset, no pagination bar).

loadSessions changes

Pass offset as a query parameter alongside filter and limit. Read X-Prev-Last-Date from response headers.

Page reset triggers

Changing filter, limit, or entering/exiting selectMode resets page to 1.

Day Grouping (render-time only)

Group the flat session array by local calendar date at render time. For each group:

1. Day header bar — Styled with bg-[#1e2a3a] (dark) / bg-gray-100 (light), left border accent (border-l-[3px] border-indigo-500), contains:
   • Full date: "Sunday, Mar 23, 2026"
   • Right side: session count ("2 sessions") and, if Sunday, "🎲 Game Night"
2. Session cards — Indented slightly (ml-3) beneath their day header. Display time only (e.g., "7:30 PM") since the full date is in the header. Remove the per-card "· Sunday" text and per-card "🎲 Game Night" badge since that information is now on the day header.

"(continued)" detection

When page > 1 and prevLastDate is set:

• Parse the previous page's last session date to a local calendar date string
• If it matches the first day group's date, append an italic "(continued)" tag to that day header (no session count shown for continued groups since the count would be incomplete)

Pagination bar

Rendered below the session list, above the multi-select action bar (if active). Only shown when limit !== "all" and totalPages > 1.

Layout: ← Prev button | "Page X of Y" text | Next → button

• Prev button disabled (grayed out) on page 1
• Next button disabled on last page
• Active buttons use indigo (bg-indigo-600)
• Disabled buttons use gray (bg-gray-600/700 with cursor-not-allowed)

Multi-select interaction

Day header bars are not selectable. Only session cards participate in multi-select. Checkboxes render inside the indented card area as they do today. Changing pages clears selected IDs but keeps select mode active.

Polling behavior

The existing 3-second polling interval refetches the current page (same offset/limit/filter). If sessions are deleted while the user is on a later page and the page becomes empty, the next poll cycle detects sessions.length === 0 && page > 1 and resets to page 1.

"Visible" count update

The existing "X visible (Y total)" label continues to work as-is. sessions.length reflects the current page's sessions.

Scope

• No changes to SessionDetail.jsx
• No changes to bulk endpoints
• No new dependencies
• The dateUtils.js gains a formatDayHeader helper (e.g., "Sunday, Mar 23, 2026") and a getLocalDateKey helper for grouping
• Existing tests for GET /sessions updated to cover offset parameter; new tests for X-Prev-Last-Date header