Add hierarchical date column headers with expand/collapse

Author: mayagbarnes

README.md

@@ -275,6 +275,7 @@ Typed `date` and `datetime` fields are treated as hierarchy-capable dimensions w
 - Alternate grouping: `Week` is available from the header menu, but it is not part of the default drill path.
 - Explicit override precedence: explicit `date_grains[field]` beats interactive state, which beats the adaptive auto default.
 - Explicit opt-out: `date_grains[field] = None` preserves the raw/original date values for that field.
+- Hierarchical parent headers with +/- collapse/expand currently render on the **column axis**. Row-side temporal hierarchy parity is planned separately.
 
 ```python
 # Adaptive date hierarchy: grain chosen from the data's date range
@@ -325,6 +326,8 @@ Once a temporal field is active on an axis, open its header menu to:
 - switch directly to `Week`,
 - choose `Original` to persist a raw-date opt-out for that field.
 
+When a temporal field is on `columns`, parent headers such as `2024` or `Q1 2024` can be collapsed with the inline +/- toggle. This is a view-only collapse: the underlying leaf buckets remain the data/export contract.
+
 Grouped buckets export as grouped labels such as `Jan 2024`, `Q1 2024`, or `2024-W03`; they are intentionally not exported as fake raw Excel dates.
 
 ### Number Format Patterns
@@ -500,7 +503,7 @@ st_pivot_table(
 )
 ```
 
-Hover over a parent column header to reveal the collapse toggle.
+Hover over a parent column header to reveal the collapse toggle. Temporal date hierarchies use the same pattern on the column axis, with inline +/- controls on parent date headers.
 
 ### Data Export
 
@@ -512,7 +515,7 @@ Export the pivot table as Excel, CSV, TSV, or copy to clipboard. Available via t
 
 Excel export produces a professionally styled workbook with merged column headers, bold totals/subtotals, number formatting, banded rows, frozen panes (headers stay visible when scrolling), and row dimension merging that matches the rendered table layout. Sort order, active filters, and show-values-as percentages are all preserved. Conditional formatting rules (color scales, data bars, and threshold highlights) are translated to native Excel conditional formatting, so the exported file renders them natively without macros.
 
-Export always outputs the full expanded table regardless of any collapsed row/column groups.
+Export always outputs the full expanded table regardless of any collapsed row/column groups, including collapsed temporal date parents.
 
 ### Drill-Down Detail Panel
 
@@ -719,7 +722,7 @@ uv pip install -e '.[with-streamlit]' --force-reinstall
 uv run streamlit run streamlit_app.py
 ```
 
-The example app (`streamlit_app.py`) contains 17 sections covering the major features and usage patterns with interactive examples and inline documentation.
+The example app (`streamlit_app.py`) contains 18 sections covering the major features and usage patterns with interactive examples and inline documentation.
 
 ### Building the frontend
 

e2e_playwright/e2e_utils.py

@@ -88,6 +88,7 @@
     "test_pivot_subtotals",
     "test_pivot_cond_fmt",
     "test_pivot_date_hierarchy",
+    "test_pivot_date_hierarchy_multidim",
     "test_pivot_adaptive_year",
     "test_pivot_adaptive_month",
     "test_pivot_locked",

e2e_playwright/pivot_table_interactions_app.py

@@ -46,21 +46,34 @@ def _make_drilldown_pagination_data() -> pd.DataFrame:
 def _make_date_hierarchy_data() -> pd.DataFrame:
     return pd.DataFrame(
         {
-            "region": ["US", "US", "US", "US", "EU", "EU", "EU", "EU"],
+            "region": [
+                "US",
+                "US",
+                "US",
+                "US",
+                "US",
+                "EU",
+                "EU",
+                "EU",
+                "EU",
+                "EU",
+            ],
             "order_date": pd.to_datetime(
                 [
                     "2024-01-03",
-                    "2024-01-10",
-                    "2024-02-12",
+                    "2024-04-10",
+                    "2024-07-12",
+                    "2024-10-05",
                     "2025-01-09",
                     "2024-01-04",
-                    "2024-01-17",
-                    "2024-02-14",
+                    "2024-04-17",
+                    "2024-07-14",
+                    "2024-10-08",
                     "2025-01-10",
                 ]
             ),
-            "revenue": [100, 30, 150, 130, 80, 20, 95, 90],
-            "profit": [40, 10, 55, 45, 30, 8, 34, 32],
+            "revenue": [100, 200, 150, 180, 130, 80, 160, 95, 140, 90],
+            "profit": [40, 80, 55, 65, 45, 30, 60, 34, 50, 32],
         }
     )
 
@@ -264,6 +277,18 @@ def render_app(data):
         on_config_change=noop,
     )
 
+    st.subheader("Date Hierarchy Multi-Dim Columns Pivot")
+    st_pivot_table(
+        _make_date_hierarchy_data(),
+        key="test_pivot_date_hierarchy_multidim",
+        rows=["profit"],
+        columns=["region", "order_date"],
+        values=["revenue"],
+        aggregation="sum",
+        interactive=True,
+        on_config_change=noop,
+    )
+
     # Adaptive date grain: multi-year dataset -> auto-defaults to "year"
     st.subheader("Adaptive Grain (Multi-Year)")
     adaptive_year_df = pd.DataFrame(

e2e_playwright/pivot_table_interactions_test.py

@@ -323,6 +323,140 @@ def test_date_hierarchy_supports_drill_week_and_original(page_at_app: Page):
     close_header_menu(page, "header-menu-revenue")
 
 
+def test_temporal_hierarchy_toggle_collapses_and_expands(page_at_app: Page):
+    """Clicking the +/- toggle collapses a year parent and re-expands it."""
+    page = page_at_app
+    container = (
+        page.locator(".st-key-test_pivot_date_hierarchy")
+        .get_by_test_id("pivot-container")
+        .first
+    )
+    expect(container.get_by_test_id("pivot-table")).to_be_visible(timeout=15000)
+
+    # With quarter grain, hierarchy is [year, quarter].
+    # Verify year parent headers are visible.
+    header_2024 = container.get_by_test_id("pivot-temporal-header-order-date-2024")
+    expect(header_2024).to_be_visible(timeout=5000)
+    header_2025 = container.get_by_test_id("pivot-temporal-header-order-date-2025")
+    expect(header_2025).to_be_visible(timeout=5000)
+
+    # Verify leaf quarter headers are visible for 2024.
+    expect(container.get_by_text("Q1 2024")).to_be_visible(timeout=5000)
+    expect(container.get_by_text("Q2 2024")).to_be_visible(timeout=5000)
+    expect(container.get_by_text("Q3 2024")).to_be_visible(timeout=5000)
+    expect(container.get_by_text("Q4 2024")).to_be_visible(timeout=5000)
+
+    # Collapse 2024 by clicking the +/- toggle button.
+    toggle_2024 = container.get_by_test_id("temporal-toggle-order-date-2024")
+    toggle_2024.click()
+
+    # After collapse: quarter leaf headers under 2024 should be hidden,
+    # and a collapsed aggregate cell should appear.
+    expect(container.get_by_text("Q1 2024")).to_be_hidden(timeout=5000)
+    expect(container.get_by_text("Q2 2024")).to_be_hidden(timeout=5000)
+    expect(container.get_by_text("Q3 2024")).to_be_hidden(timeout=5000)
+    expect(container.get_by_text("Q4 2024")).to_be_hidden(timeout=5000)
+    expect(
+        container.get_by_test_id("pivot-temporal-collapse-cell").first
+    ).to_be_visible(timeout=5000)
+
+    # 2025 quarter should still be visible (not collapsed).
+    expect(container.get_by_text("Q1 2025")).to_be_visible(timeout=5000)
+
+    # Re-expand 2024.
+    toggle_2024 = container.get_by_test_id("temporal-toggle-order-date-2024")
+    toggle_2024.click()
+
+    # All quarter columns should be visible again.
+    expect(container.get_by_text("Q1 2024")).to_be_visible(timeout=5000)
+    expect(container.get_by_text("Q2 2024")).to_be_visible(timeout=5000)
+    expect(container.get_by_text("Q3 2024")).to_be_visible(timeout=5000)
+    expect(container.get_by_text("Q4 2024")).to_be_visible(timeout=5000)
+    expect(container.get_by_test_id("pivot-temporal-collapse-cell")).to_have_count(0)
+
+
+def test_temporal_hierarchy_collapsed_cells_suppress_comparison(page_at_app: Page):
+    """Collapsed parent cells render raw aggregates, not period comparisons."""
+    page = page_at_app
+    container = (
+        page.locator(".st-key-test_pivot_date_hierarchy")
+        .get_by_test_id("pivot-container")
+        .first
+    )
+    expect(container.get_by_test_id("pivot-table")).to_be_visible(timeout=15000)
+
+    # The fixture has show_values_as={"revenue": "diff_from_prev"}.
+    # Leaf cells should have comparison indicators (arrows / deltas).
+    data_cells = container.get_by_test_id("pivot-data-cell")
+    expect(data_cells.first).to_be_visible(timeout=5000)
+
+    # Collapse 2024.
+    toggle_2024 = container.get_by_test_id("temporal-toggle-order-date-2024")
+    toggle_2024.click()
+
+    # The collapsed aggregate cells should NOT contain comparison indicators.
+    collapse_cells = container.get_by_test_id("pivot-temporal-collapse-cell")
+    expect(collapse_cells.first).to_be_visible(timeout=5000)
+
+    # Collapsed cells should contain a plain numeric value (the raw sum for
+    # all quarters in 2024), not a comparison arrow/delta.  A comparison
+    # indicator includes an arrow character or "▲"/"▼" or "+" prefix.
+    first_collapse_text = collapse_cells.first.inner_text()
+    assert (
+        "▲" not in first_collapse_text
+    ), f"Collapsed cell should not show comparison indicator, got: {first_collapse_text}"
+    assert (
+        "▼" not in first_collapse_text
+    ), f"Collapsed cell should not show comparison indicator, got: {first_collapse_text}"
+
+    # Re-expand to restore state for other tests.
+    toggle_2024 = container.get_by_test_id("temporal-toggle-order-date-2024")
+    toggle_2024.click()
+    expect(container.get_by_text("Q1 2024")).to_be_visible(timeout=5000)
+
+
+def test_temporal_hierarchy_multidim_per_instance_collapse(page_at_app: Page):
+    """Collapsing one parent instance in a multi-dimension column layout
+    does not collapse its sibling instance."""
+    page = page_at_app
+    container = (
+        page.locator(".st-key-test_pivot_date_hierarchy_multidim")
+        .get_by_test_id("pivot-container")
+        .first
+    )
+    expect(container.get_by_test_id("pivot-table")).to_be_visible(timeout=15000)
+
+    # With columns=["region", "order_date"], the hierarchy has region as an
+    # outer sibling.  Each region gets its own set of year parent headers.
+    # Verify both EU and US 2024 year headers are visible.
+    eu_header = container.get_by_test_id("pivot-temporal-header-order-date-2024").first
+    expect(eu_header).to_be_visible(timeout=5000)
+
+    # Collapse the first 2024 instance (should be one region only).
+    first_toggle = container.get_by_test_id("temporal-toggle-order-date-2024").first
+    first_toggle.click()
+
+    # At least one collapsed cell should appear.
+    expect(
+        container.get_by_test_id("pivot-temporal-collapse-cell").first
+    ).to_be_visible(timeout=5000)
+
+    # The other region's 2024 quarters should still have visible leaf headers.
+    # Since only one instance was collapsed, there should still be visible
+    # quarter headers under the other region's 2024 parent.
+    second_header = container.get_by_test_id(
+        "pivot-temporal-header-order-date-2024"
+    ).nth(1)
+    expect(second_header).to_have_attribute("aria-expanded", "true", timeout=5000)
+
+    # Re-expand.
+    first_toggle = container.get_by_test_id("temporal-toggle-order-date-2024").first
+    first_toggle.click()
+    expect(container.get_by_test_id("pivot-temporal-collapse-cell")).to_have_count(
+        0, timeout=5000
+    )
+
+
 def test_drilldown_opens_on_cell_click(page_at_app: Page):
     """Clicking a data cell opens the drilldown panel with a detail table."""
     page = page_at_app

streamlit_app.py

@@ -1471,9 +1471,14 @@
 available as an alternate grouping. Period-over-period display modes
 (previous-period, previous-year) are unlocked automatically.
 
+For this release, the Excel/Power BI-style parent header collapse/expand UI is
+available on the **column axis**. Exports still keep the full leaf-level date
+columns even when a parent date header is collapsed in the view.
+
 **Try it:**
 - In the first table, notice the adaptive default grain based on the data range.
 - Open the `order_date` header menu to drill up/down, switch to Week, or choose Original.
+- Use the +/- toggle on a parent date header to collapse a year/quarter group on the column axis.
 - Open the `Revenue` value header menu to switch between raw values and period comparisons.
 - Compare the other tables for explicit override, global opt-out, and per-field opt-out.
 
@@ -1523,7 +1528,7 @@
 date_col_3, date_col_4 = st.columns(2)
 
 with date_col_3:
-    st.caption("Explicit override: Month + MoM comparison")
+    st.caption("Explicit override: Month grain (raw sums)")
     st_pivot_table(
         df_dates,
         key="date_hierarchy_quarter",
@@ -1533,7 +1538,6 @@
         aggregation="sum",
         show_totals=True,
         date_grains={"order_date": "month"},
-        show_values_as={"Revenue": "diff_from_prev"},
     )
 
 with date_col_4:
@@ -1585,14 +1589,13 @@
     values=["Revenue"],
 )
 
-# Explicit override: month grain + month-over-month comparison
+# Explicit override: month grain (raw sums)
 st_pivot_table(
     df_dates,
     rows=["region"],
     columns=["order_date"],
     values=["Revenue"],
     date_grains={"order_date": "month"},
-    show_values_as={"Revenue": "diff_from_prev"},
 )
 
 st_pivot_table(