Add drilldown sort

Author: mayagbarnes

README.md

@@ -535,7 +535,9 @@ result = st_pivot_table(
 )
 ```
 
-- The panel displays up to 500 matching records.
+- The panel displays up to 500 matching records per page with pagination controls when there are more.
+- **Column sorting:** Click any column header to sort the drilldown results. The sort cycles through ascending, descending, and unsorted (original order). Sorting applies to the **full** result set before pagination, so page boundaries reflect the global sort order.
+- In `threshold_hybrid` mode, sorting triggers a server round-trip so the backend sorts the full filtered DataFrame before slicing the requested page.
 - Close with the **×** button or by pressing **Escape**.
 - Set `enable_drilldown=False` to disable (the `on_cell_click` callback still fires).
 
@@ -726,7 +728,7 @@ The component follows WAI-ARIA patterns for all interactive elements:
 - **Export/Import popovers**: Focus is automatically placed on the first interactive element when opened. Tab/Shift+Tab moves between controls; tabbing out closes the popover.
 - **Settings Panel** (pivot icon): Focus moves into the panel on open. Escape closes and discards staged changes. Tab navigates between fields, zones, toggles, and buttons. Aggregation dropdowns support Enter/Space for keyboard selection.
 - **Radio groups** (export format/content): Arrow keys move focus between options. Space/Enter selects.
-- **Drill-down panel**: Focus moves to the close button on open. Escape closes.
+- **Drill-down panel**: Focus moves to the close button on open. Escape closes. Column headers are clickable buttons that cycle sort direction (asc → desc → none).
 - **Data cells**: Focusable via Tab. Space/Enter triggers cell click.
 
 ---

e2e_playwright/pivot_table_interactions_test.py

@@ -1137,6 +1137,26 @@ def _open_drilldown_with_pagination(page: Page, pivot_key: str):
     return container, panel
 
 
+def _first_drilldown_revenue_cell(panel):
+    """Return the first visible Revenue cell in the current drilldown page."""
+    return (
+        panel.get_by_test_id("drilldown-table")
+        .locator("tbody tr")
+        .first.locator("td")
+        .nth(2)
+    )
+
+
+def _drilldown_sort_button(panel, column_name: str):
+    """Return the clickable sort button for a drilldown column header."""
+    return (
+        panel.get_by_test_id("drilldown-table")
+        .locator("th")
+        .filter(has_text=column_name)
+        .locator("button")
+    )
+
+
 def test_drilldown_client_pagination_shows_controls(page_at_app: Page):
     """Client-only: clicking a cell with >500 records shows pagination controls."""
     page = page_at_app
@@ -1163,6 +1183,22 @@ def test_drilldown_client_pagination_navigates(page_at_app: Page):
     expect(panel.locator("text=Page 1 of 2")).to_be_visible(timeout=5000)
 
 
+def test_drilldown_client_sort_orders_full_result_before_pagination(page_at_app: Page):
+    """Client-only drilldown sort reorders the full result set before page slicing."""
+    page = page_at_app
+    _, panel = _open_drilldown_with_pagination(page, "test_pivot_drilldown_pagination")
+
+    _drilldown_sort_button(panel, "Revenue").click()
+    _drilldown_sort_button(panel, "Revenue").click()
+
+    # Fixture values for Alpha/2023 are 10..709 inclusive, so descending page 1
+    # starts at 709 and descending page 2 starts at 209 after the first 500 rows.
+    expect(_first_drilldown_revenue_cell(panel)).to_have_text("709")
+    panel.get_by_test_id("drilldown-next").click()
+    expect(panel.locator("text=Page 2 of 2")).to_be_visible(timeout=5000)
+    expect(_first_drilldown_revenue_cell(panel)).to_have_text("209")
+
+
 def test_drilldown_hybrid_pagination_shows_controls(page_at_app: Page):
     """Hybrid mode: clicking a cell with >500 records shows pagination controls."""
     page = page_at_app
@@ -1199,6 +1235,29 @@ def test_drilldown_hybrid_pagination_navigates(page_at_app: Page):
     expect(panel.locator("text=Page 1 of 2")).to_be_visible(timeout=30000)
 
 
+def test_drilldown_hybrid_sort_orders_full_result_before_pagination(page_at_app: Page):
+    """Hybrid drilldown sort reorders the full result set before server pagination."""
+    page = page_at_app
+    _, panel = _open_drilldown_with_pagination(
+        page, "test_pivot_drilldown_pagination_hybrid"
+    )
+
+    _drilldown_sort_button(panel, "Revenue").click()
+    _drilldown_sort_button(panel, "Revenue").click()
+
+    panel = page.get_by_test_id("drilldown-panel")
+    expect(panel).to_be_visible(timeout=30000)
+    # Fixture values for Alpha/2023 are 10..709 inclusive, so descending page 1
+    # starts at 709 and descending page 2 starts at 209 after the first 500 rows.
+    expect(_first_drilldown_revenue_cell(panel)).to_have_text("709", timeout=30000)
+
+    panel.get_by_test_id("drilldown-next").click()
+    panel = page.get_by_test_id("drilldown-panel")
+    expect(panel).to_be_visible(timeout=30000)
+    expect(panel.locator("text=Page 2 of 2")).to_be_visible(timeout=30000)
+    expect(_first_drilldown_revenue_cell(panel)).to_have_text("209", timeout=30000)
+
+
 # ---------------------------------------------------------------------------
 # Adaptive date grain e2e tests
 # ---------------------------------------------------------------------------

streamlit_app.py

@@ -1007,6 +1007,9 @@ def section_drilldown():
 - A detail panel slides in below the table showing all matching source records.
 - The header shows the dimension filters (e.g. "Region: East, Year: 2023")
   and the record count.
+- **Click any column header** in the drill-down panel to sort the results.
+  Click again to toggle between ascending, descending, and original order.
+  Sorting applies to the **full** result set before pagination.
 - Click the **✕** button or press **Escape** to close the panel.
 - Click a different cell to replace the panel with new records.
 
@@ -1042,6 +1045,7 @@ def section_drilldown():
     on_cell_click=lambda: None,
 )
 # Click any cell to see the contributing source records.
+# Click a column header in the drill-down panel to sort results.
 """,
             language="python",
         )
@@ -1253,6 +1257,10 @@ def section_hybrid():
 - If the cell has more than 500 matching rows, use the **← Prev / Next →**
   buttons at the bottom of the panel to page through all results.
 - The header shows a range like "1–500 of 2,340 records" and the current page.
+- **Click a column header** to sort the drill-down results. In hybrid mode,
+  each sort triggers a server round-trip so the backend sorts the full
+  filtered result before slicing the requested page. Navigate to page 2 to
+  confirm the sort applies globally, not just within the visible page.
 
 **API parameter used:** `execution_mode` (set to `"threshold_hybrid"` here to
 force hybrid mode on a smaller dataset for demonstration purposes)
@@ -1303,6 +1311,7 @@ def section_hybrid():
     execution_mode="threshold_hybrid",
 )
 # Click any cell to see paginated server-side drill-down.
+# Click a column header to sort — sort is applied server-side before pagination.
 """,
             language="python",
         )

streamlit_pivot/__init__.py

@@ -22,7 +22,7 @@
 import warnings
 from datetime import date, datetime
 from math import prod
-from typing import TYPE_CHECKING, Any, TypedDict, cast
+from typing import TYPE_CHECKING, Any, Literal, TypedDict, cast
 
 import pandas as pd
 
@@ -1434,7 +1434,7 @@ def _append_temporal_row_parent_entries(
 
 def _compute_hybrid_drilldown(
     df: Any,
-    drilldown_request: dict[str, Any],
+    drilldown_request: DrilldownRequest,
     null_handling: Any = None,
     dims: list[str] | None = None,
     config_filters: dict[str, dict] | None = None,
@@ -1469,6 +1469,8 @@ def _compute_hybrid_drilldown(
 
     filters: dict[str, str] = drilldown_request.get("filters", {})
     page: int = max(0, int(drilldown_request.get("page", 0)))
+    sort_column = drilldown_request.get("sortColumn")
+    sort_direction = drilldown_request.get("sortDirection")
 
     mask = pd.Series(True, index=working.index)
     for col, val in filters.items():
@@ -1489,6 +1491,47 @@ def _compute_hybrid_drilldown(
         mask &= resolved == str(val)
     filtered = working[mask]
     total_count = len(filtered)
+    if (
+        sort_column
+        and sort_direction in ("asc", "desc")
+        and sort_column in filtered.columns
+    ):
+        sort_key = sort_column
+        temp_sort_column: str | None = None
+        col_type = column_types.get(sort_column) if column_types else None
+        if col_type in ("date", "datetime"):
+            temp_sort_column = "__drilldown_sort_key__"
+            while temp_sort_column in filtered.columns:
+                temp_sort_column += "_"
+            filtered = filtered.assign(
+                **{
+                    temp_sort_column: pd.to_datetime(
+                        filtered[sort_column], errors="coerce"
+                    )
+                }
+            )
+            sort_key = temp_sort_column
+        elif col_type in ("integer", "float"):
+            temp_sort_column = "__drilldown_sort_key__"
+            while temp_sort_column in filtered.columns:
+                temp_sort_column += "_"
+            filtered = filtered.assign(
+                **{
+                    temp_sort_column: pd.to_numeric(
+                        filtered[sort_column], errors="coerce"
+                    )
+                }
+            )
+            sort_key = temp_sort_column
+
+        filtered = filtered.sort_values(
+            by=sort_key,
+            ascending=sort_direction == "asc",
+            kind="mergesort",
+            na_position="last",
+        )
+        if temp_sort_column is not None:
+            filtered = filtered.drop(columns=[temp_sort_column])
     offset = page * page_size
     page_slice = filtered.iloc[offset : offset + page_size]
     records = json.loads(page_slice.to_json(orient="records", date_format="iso"))
@@ -1734,6 +1777,15 @@ class CellClickPayload(TypedDict):
     valueField: str
 
 
+class DrilldownRequest(CellClickPayload, total=False):
+    """Frontend-owned drilldown request state mirrored through session_state."""
+
+    page: int
+    sortColumn: str
+    sortDirection: Literal["asc", "desc"]
+    requestId: str
+
+
 class PerfActionMeasurement(TypedDict, total=False):
     """Payload fired by setStateValue("perf_metrics", ...)."""
 
@@ -2625,6 +2677,7 @@ def st_pivot_table(
             data_payload["drilldown_total_count"] = total
             data_payload["drilldown_page"] = page
             data_payload["drilldown_page_size"] = _DRILLDOWN_PAGE_SIZE
+            data_payload["drilldown_request_id"] = drilldown_request.get("requestId")
 
     mount_kwargs: dict[str, Any] = {
         "key": key,