feat: add custom date-range leaderboard across Jinja and React

Introduce custom start/end leaderboard ranges in both server-rendered and SPA flows while fixing monthly end-date consistency.

- Add /report/range (Jinja) and /json/report/range endpoints with YYYY-MM-DD validation and max-range guard
- Add shared date-range parser utility with tests
- Wire React Rankings to /json/report/range via /rankings/range UI and API client updates
- Add explore-page entry for custom ranges
- Fix monthly report end-date calculation using last_day_of_calendar_month for HTML and JSON parity

Author: Dev-JoyA

frontend/src/features/call.js

@@ -63,7 +63,14 @@ export const callUnit = createApi({
       providesTags: (result, error, category) => [{ type: "Category", id: category }],
     }),
     retrieveRankings: builder.query({
-      query: ({ y, w, m, d, begin = 0, limit = 200 } = {}) => {
+      query: ({ y, w, m, d, start, end, begin = 0, limit = 200 } = {}) => {
+        if (start && end) {
+          return {
+            url: "report/range",
+            method: "GET",
+            params: { start, end, begin, limit },
+          };
+        }
         let link = "report";
         if (y) {
           link += `/y/${y}`;

frontend/src/main.jsx

@@ -42,6 +42,7 @@ createRoot(document.getElementById("root")).render(
             <Route element={<Recently />} path="recently" />
             <Route path="rankings">
               <Route element={<Rankings />} index />
+              <Route element={<Rankings />} path="range" />
               <Route path="y/:y">
                 <Route element={<Rankings />} index />
                 <Route path="m/:m">

frontend/src/routes/rankings.jsx

@@ -1,9 +1,9 @@
 import { mdiCalendarCheck, mdiCalendarHeart, mdiCalendarMonth, mdiCalendarRange, mdiCalendarWeek } from "@mdi/js";
 import Icon from "@mdi/react";
-import { useEffect } from "react";
+import { useEffect, useState } from "react";
 import { Badge, Button, Card, Form, ListGroup } from "react-bootstrap";
 import { useDispatch, useSelector } from "react-redux";
-import { Link, useLocation, useNavigate, useParams } from "react-router";
+import { Link, useLocation, useNavigate, useParams, useSearchParams } from "react-router";
 
 import VertItem from "../components/vertitem.jsx";
 import { useRetrieveRankingsQuery } from "../features/call.js";
@@ -18,9 +18,20 @@ export default function Rankings() {
   const thisdate = new Date();
   const { y, m, d } = useParams();
   const isweekly = location.pathname.endsWith("/week");
+  const isCustomRange = location.pathname === "/rankings/range";
+  const [searchParams, setSearchParams] = useSearchParams();
+  const rangeStart = searchParams.get("start");
+  const rangeEnd = searchParams.get("end");
+  const [startField, setStartField] = useState(rangeStart || "");
+  const [endField, setEndField] = useState(rangeEnd || "");
   const pickdate = useSelector((state) => state.area.date);
   const vibe = useSelector((data) => data.area.vibe);
 
+  useEffect(() => {
+    setStartField(rangeStart || "");
+    setEndField(rangeEnd || "");
+  }, [rangeStart, rangeEnd]);
+
   const readDate = () => {
     if (y && m && d) {
       return `${y}-${m.toString().padStart(2, "0")}-${d.toString().padStart(2, "0")}`;
@@ -41,14 +52,21 @@ export default function Rankings() {
     }
   };
 
-  const params = {
+  const stdParams = {
     ...(y && { y: parseInt(y) }),
     ...(m && { m: parseInt(m) }),
     ...(d && { d: parseInt(d) }),
     ...(isweekly && { w: true }),
   };
 
-  const { data: dict, isLoading, error } = useRetrieveRankingsQuery(params, { skip: false });
+  const apiParams =
+    isCustomRange && rangeStart && rangeEnd
+      ? { start: rangeStart, end: rangeEnd }
+      : stdParams;
+
+  const skipRetrieve = isCustomRange && (!rangeStart || !rangeEnd);
+
+  const { data: dict, isLoading, error } = useRetrieveRankingsQuery(apiParams, { skip: skipRetrieve });
 
   // Show or Hide LoadNote
   useEffect(() => {
@@ -63,32 +81,41 @@ export default function Rankings() {
     return <Mistaken />;
   }
 
-  if (isLoading || !dict) {
+  const loadingBlocked =
+    (!isCustomRange && (isLoading || !dict)) ||
+    (isCustomRange && rangeStart && rangeEnd && (isLoading || !dict));
+
+  if (loadingBlocked) {
     return null;
   }
 
   const showDate = () => {
-    if (Object.keys(params).length === 0) return "All time";
+    if (isCustomRange) {
+      if (rangeStart && rangeEnd) return `${rangeStart} to ${rangeEnd}`;
+      return "Pick start and end dates";
+    }
+    if (Object.keys(stdParams).length === 0) return "All time";
 
     const date = new Date();
-    if (params.y) date.setFullYear(params.y);
-    if (params.m) date.setMonth(params.m - 1);
-    if (params.d) date.setDate(params.d);
+    if (stdParams.y) date.setFullYear(stdParams.y);
+    if (stdParams.m) date.setMonth(stdParams.m - 1);
+    if (stdParams.d) date.setDate(stdParams.d);
 
     const option = {};
-    if (params.y) option.year = "numeric";
-    if (params.m) option.month = "long";
-    if (params.d) option.day = "numeric";
+    if (stdParams.y) option.year = "numeric";
+    if (stdParams.m) option.month = "long";
+    if (stdParams.d) option.day = "numeric";
 
     return date.toLocaleDateString("en-US", option);
   };
 
   const showHead = () => {
+    if (isCustomRange) return "Custom range";
     let name = "";
-    if (params.w) name = "Weekly";
-    else if (params.d) name = "Daily";
-    else if (params.m) name = "Monthly";
-    else if (params.y) name = "Yearly";
+    if (stdParams.w) name = "Weekly";
+    else if (stdParams.d) name = "Daily";
+    else if (stdParams.m) name = "Monthly";
+    else if (stdParams.y) name = "Yearly";
     else name = "All time";
     return name;
   };
@@ -108,27 +135,27 @@ export default function Rankings() {
   const scanDate = (conf = "") => {
     if (conf === "d")
       return (
-        params.y &&
-        params.m &&
-        params.d &&
-        (params.y !== thisdate.getFullYear() ||
-          params.m !== thisdate.getMonth() + 1 ||
-          params.d !== thisdate.getDate()) &&
+        stdParams.y &&
+        stdParams.m &&
+        stdParams.d &&
+        (stdParams.y !== thisdate.getFullYear() ||
+          stdParams.m !== thisdate.getMonth() + 1 ||
+          stdParams.d !== thisdate.getDate()) &&
         isweekly
       );
     else if (conf === "w")
       return (
-        params.y &&
-        params.m &&
-        params.d &&
-        (params.y !== thisdate.getFullYear() ||
-          params.m !== thisdate.getMonth() + 1 ||
-          params.d !== thisdate.getDate()) &&
+        stdParams.y &&
+        stdParams.m &&
+        stdParams.d &&
+        (stdParams.y !== thisdate.getFullYear() ||
+          stdParams.m !== thisdate.getMonth() + 1 ||
+          stdParams.d !== thisdate.getDate()) &&
         !isweekly
       );
     else if (conf === "m")
-      return params.y && params.m && (params.y !== thisdate.getFullYear() || params.m !== thisdate.getMonth() + 1);
-    else if (conf === "y") return params.y && params.y !== thisdate.getFullYear();
+      return stdParams.y && stdParams.m && (stdParams.y !== thisdate.getFullYear() || stdParams.m !== thisdate.getMonth() + 1);
+    else if (conf === "y") return stdParams.y && stdParams.y !== thisdate.getFullYear();
     return false;
   };
 
@@ -139,9 +166,43 @@ export default function Rankings() {
           <Card.Body className="p-2">
             <Card.Title className="dataelem text-truncate">Rankings</Card.Title>
             <Card.Text className="small">{showDate()}</Card.Text>
-            <Card.Text>
-              <Form.Control type="date" value={readDate()} onChange={handleChange} size="sm" autoComplete="off" />
-            </Card.Text>
+            {isCustomRange ? (
+              <Card.Text>
+                <Form
+                  onSubmit={(e) => {
+                    e.preventDefault();
+                    if (!startField || !endField) return;
+                    setSearchParams({ start: startField, end: endField });
+                  }}
+                >
+                  <Form.Label className="small mb-0">Start</Form.Label>
+                  <Form.Control
+                    type="date"
+                    value={startField}
+                    onChange={(e) => setStartField(e.target.value)}
+                    className="mb-2"
+                    size="sm"
+                    autoComplete="off"
+                  />
+                  <Form.Label className="small mb-0">End</Form.Label>
+                  <Form.Control
+                    type="date"
+                    value={endField}
+                    onChange={(e) => setEndField(e.target.value)}
+                    className="mb-2"
+                    size="sm"
+                    autoComplete="off"
+                  />
+                  <Button type="submit" size="sm" variant="outline-secondary" className="w-100 vibe-border" style={{ "--vibe": vibe }}>
+                    Show rankings
+                  </Button>
+                </Form>
+              </Card.Text>
+            ) : (
+              <Card.Text>
+                <Form.Control type="date" value={readDate()} onChange={handleChange} size="sm" autoComplete="off" />
+              </Card.Text>
+            )}
           </Card.Body>
         </Card>
         <div className="d-grid gap-2">
@@ -200,11 +261,22 @@ export default function Rankings() {
             <Icon path={mdiCalendarHeart} size={0.875} className="me-1" />
             All time
           </Button>
+          <Button
+            as={Link}
+            to="/rankings/range"
+            variant="outline-secondary"
+            className="d-grid d-inline-flex align-items-center ps-1 vibe-border"
+            size="sm"
+            style={{ "--vibe": vibe }}
+          >
+            <Icon path={mdiCalendarRange} size={0.875} className="me-1" />
+            Custom date range
+          </Button>
           {scanDate("y") || scanDate("m") || scanDate("w") || scanDate("d") ? <hr className="m-0" /> : null}
           {scanDate("w") ? (
             <Button
               as={Link}
-              to={`/rankings/y/${params.y}/m/${params.m}/d/${params.d}/week`}
+              to={`/rankings/y/${stdParams.y}/m/${stdParams.m}/d/${stdParams.d}/week`}
               variant="outline-secondary"
               className="d-grid d-inline-flex align-items-center ps-1 vibe-border"
               size="sm"
@@ -217,7 +289,7 @@ export default function Rankings() {
           {scanDate("d") ? (
             <Button
               as={Link}
-              to={`/rankings/y/${params.y}/m/${params.m}/d/${params.d}`}
+              to={`/rankings/y/${stdParams.y}/m/${stdParams.m}/d/${stdParams.d}`}
               variant="outline-secondary"
               className="d-grid d-inline-flex align-items-center ps-1 vibe-border"
               size="sm"
@@ -230,27 +302,27 @@ export default function Rankings() {
           {scanDate("m") ? (
             <Button
               as={Link}
-              to={`/rankings/y/${params.y}/m/${params.m}`}
+              to={`/rankings/y/${stdParams.y}/m/${stdParams.m}`}
               variant="outline-secondary"
               className="d-grid d-inline-flex align-items-center ps-1 vibe-border"
               size="sm"
               style={{ "--vibe": vibe }}
             >
               <Icon path={mdiCalendarMonth} size={0.875} className="me-1" />
-              For {new Date(params.y, params.m - 1).toLocaleDateString("en-US", { month: "long" })}
+              For {new Date(stdParams.y, stdParams.m - 1).toLocaleDateString("en-US", { month: "long" })}
             </Button>
           ) : null}
           {scanDate("y") ? (
             <Button
               as={Link}
-              to={`/rankings/y/${params.y}`}
+              to={`/rankings/y/${stdParams.y}`}
               variant="outline-secondary"
               className="d-grid d-inline-flex align-items-center ps-1 vibe-border"
               size="sm"
               style={{ "--vibe": vibe }}
             >
               <Icon path={mdiCalendarCheck} size={0.875} className="me-1" />
-              For {params.y}
+              For {stdParams.y}
             </Button>
           ) : null}
         </div>
@@ -271,7 +343,7 @@ export default function Rankings() {
                     link={`/identity/${item.nickname}`}
                     shot={portraitProvider(item.mail)}
                     head={item.nickname}
-                    body={`Collected ${item.badges} badge(s) ${y || m || d || isweekly ? `during this period • Global rank #${item.rank.global}` : ""}`}
+                    body={`Collected ${item.badges} badge(s) ${y || m || d || isweekly || (isCustomRange && rangeStart && rangeEnd) ? `during this period • Global rank #${item.rank.global}` : ""}`}
                     hand={
                       <Badge className="monoelem vibe-badge" style={{ "--vibe": vibe }}>
                         #{item.rank.period}

tahrir/templates/explore.html

@@ -156,6 +156,7 @@ <h1 class="section-header">Reports</h1>
           <li>Top badge earners <a href="{{ url_for(".report_year_month_day", year=example_date.year, month=example_date.month, day=example_date.day) }}">for just the {{ example_date.strftime("%x") }}</a></li>
           <li>Top badge earners <a href="{{ url_for(".report_year_week", year=example_date.year, week=example_date.isocalendar().week) }}">for week {{ example_date.strftime("%W") }} of {{ example_date.year }}</a></li>
           <li>Top badge earners <a href="{{ url_for(".report") }}">for just this week</a></li>
+          <li>Top badge earners for a <a href="{{ url_for(".report_custom_range") }}">custom date range</a> (start and end, calendar picker)</li>
         </ul>
       </div> <!-- End padded content. -->
     </div> <!-- End shadow. -->

tahrir/templates/report_range.html

@@ -0,0 +1,54 @@
+{% from '_functions.html' import avatar_thumbnail, pluralize with context %}
+{% extends '_base.html' %}
+
+{% block body %}
+<div class="page">
+  <div class="grid-100">
+    <div class="shadow">
+      <h1 class="section-header">Rising stars: custom period</h1>
+      <div class="report-range padded-content">
+        <p>Pick a start and end date (inclusive). Dates use the ISO form <strong>YYYY-MM-DD</strong> in the picker.</p>
+        <p>Looking for the <a href="{{ url_for('tahrir.leaderboard') }}">all-time leaderboard</a> or <a href="{{ url_for('tahrir.explore') }}">other report links</a>?</p>
+
+        {% if error %}
+        <p><strong style="color: #a40000;">{{ error }}</strong></p>
+        {% endif %}
+
+        <form method="get" action="{{ url_for('tahrir.report_custom_range') }}">
+          <label>Start
+            <input type="date" name="start" value="{{ start_value }}" required>
+          </label>
+          <label>End
+            <input type="date" name="end" value="{{ end_value }}" required>
+          </label>
+          <input type="submit" value="Show leaderboard">
+        </form>
+
+        {% if user_to_rank is not none %}
+        <p>Showing results for <strong>{{ start_date }}</strong> through <strong>{{ stop_date }}</strong> (inclusive).</p>
+        <table>
+          {% for person, stats in (user_to_rank.items()|list)[:25] %}
+            <tr>
+              <td style="width: 20px;">
+                  <span class="big-text">#{{ stats['rank'] }}</span>
+              </td>
+              <td style="width: 100px;">
+                <small>(#{{ person.rank }} all time)</small>
+              </td>
+              <td style="width: 64px;">{{ avatar_thumbnail(person, 64, 33) }}</td>
+              <td>
+                <a href="{{ url_for('tahrir.user', user_id=person.nickname or person.id) }}">{{ person.nickname }}</a>
+                earned <strong>{{ user_to_rank[person]['badges'] }}</strong>
+                {{ pluralize("badge", user_to_rank[person]['badges']) }}
+                during this period.
+              </td>
+            </tr>
+          {% endfor %}
+        </table>
+        {% endif %}
+      </div>
+    </div>
+  </div>
+  <div class="clear spacer"></div>
+</div>
+{% endblock %}

tahrir/utils/date_time.py

@@ -4,6 +4,17 @@
 import dateutil.relativedelta
 
 
+def last_day_of_calendar_month(year: int, month: int) -> date:
+    """Return the last calendar day of the given month.
+
+    Used for monthly leaderboard/report ranges so HTML and JSON paths stay consistent.
+    """
+    first = date(year, month, 1)
+    nudge = first + timedelta(days=32)
+    first_next_month = nudge.replace(day=1)
+    return first_next_month - timedelta(days=1)
+
+
 def get_start_week(year=None, month=None, day=None):
     """For a given date, retrieve the day the week started