Add adaptive default date grains

Author: mayagbarnes

README.md

@@ -57,6 +57,8 @@ Returns a `PivotTableResult` dict containing the current `config` state.
 | `values` | `list[str] \| None` | `None` | Column names to aggregate as measures. |
 | `synthetic_measures` | `list[dict] \| None` | `None` | Derived measures computed from source-field sums (for example, ratio of sums). See [Synthetic Measures](#synthetic-measures-v1). |
 | `aggregation` | `str \| dict[str, str]` | `"sum"` | Aggregation setting for raw value fields. A single string applies to every raw measure; a dict enables per-measure aggregation. See [Aggregation Functions](#aggregation-functions). |
+| `auto_date_hierarchy` | `bool` | `True` | Auto-group typed date/datetime fields placed on rows or columns. Default grain is adaptive based on the source data's date range (year for >2 years, quarter for >1 year, month for >2 months, day for shorter ranges). |
+| `date_grains` | `dict[str, str \| None] \| None` | `None` | Per-field temporal overrides. Use `"year"`, `"quarter"`, `"month"`, `"week"`, or `"day"`. Use `None` for an explicit `Original` opt-out. |
 | `interactive` | `bool` | `True` | Enable end-user config controls. When `False`, the toolbar is hidden and header-menu sort/filter/show-values-as actions are disabled. |
 
 #### Totals and Subtotals
@@ -240,6 +242,10 @@ Display measures as percentages instead of raw numbers.
 | % of Grand Total | `"pct_of_total"` | Cell / Grand Total |
 | % of Row Total | `"pct_of_row"` | Cell / Row Total |
 | % of Column Total | `"pct_of_col"` | Cell / Column Total |
+| Diff vs Previous Period | `"diff_from_prev"` | Current bucket minus previous bucket on the active temporal hierarchy |
+| % Diff vs Previous Period | `"pct_diff_from_prev"` | Percent change vs previous bucket |
+| Diff vs Previous Year | `"diff_from_prev_year"` | Current bucket minus same bucket in the prior year |
+| % Diff vs Previous Year | `"pct_diff_from_prev_year"` | Percent change vs same bucket in the prior year |
 
 ```python
 st_pivot_table(
@@ -254,6 +260,72 @@ st_pivot_table(
 
 Users can also change this interactively via the value header menu (**⋮** icon on a value label header).
 Synthetic measures are always rendered as raw derived values (`show_values_as` does not apply to them).
+Period-comparison modes appear only when there is an active grouped temporal axis, whether that grouping came from auto hierarchy or an explicit `date_grains` override.
+
+### Date Hierarchy and Time Comparisons
+
+Typed `date` and `datetime` fields are treated as hierarchy-capable dimensions when they are placed on `rows` or `columns`.
+
+- **Adaptive default grain**: with `auto_date_hierarchy=True`, temporal axis fields auto-group based on the date range of the source data (after `source_filters`):
+  - **>2 years** → `year`
+  - **>1 year** → `quarter`
+  - **>2 months** → `month`
+  - **≤2 months** → `day`
+- Default drill ladder: `Year -> Quarter -> Month -> Day`.
+- 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.
+
+```python
+# Adaptive date hierarchy: grain chosen from the data's date range
+st_pivot_table(
+    df,
+    key="date_auto",
+    rows=["region"],
+    columns=["order_date"],
+    values=["Revenue"],
+    show_values_as={"Revenue": "diff_from_prev"},
+)
+
+# Deterministic starting grain from Python
+st_pivot_table(
+    df,
+    key="date_quarter",
+    rows=["region"],
+    columns=["order_date"],
+    values=["Revenue"],
+    date_grains={"order_date": "quarter"},
+    show_values_as={"Revenue": "diff_from_prev_year"},
+)
+
+# Disable auto hierarchy globally
+st_pivot_table(
+    df,
+    key="date_off",
+    rows=["region"],
+    columns=["order_date"],
+    values=["Revenue"],
+    auto_date_hierarchy=False,
+)
+
+# Explicit Original/raw opt-out for one field
+st_pivot_table(
+    df,
+    key="date_original",
+    rows=["region"],
+    columns=["ship_date"],
+    values=["Revenue"],
+    date_grains={"ship_date": None},
+)
+```
+
+Once a temporal field is active on an axis, open its header menu to:
+
+- drill up or down through the default hierarchy,
+- switch directly to `Week`,
+- choose `Original` to persist a raw-date opt-out for that field.
+
+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
 

e2e_playwright/e2e_utils.py

@@ -87,6 +87,9 @@
     "test_pivot",
     "test_pivot_subtotals",
     "test_pivot_cond_fmt",
+    "test_pivot_date_hierarchy",
+    "test_pivot_adaptive_year",
+    "test_pivot_adaptive_month",
     "test_pivot_locked",
     "test_pivot_locked_groups",
     "test_pivot_readonly",

e2e_playwright/pivot_table_interactions_app.py

@@ -17,7 +17,7 @@
 
 from __future__ import annotations
 
-import pandas as pd
+import pandas as pd  # type: ignore[import-untyped]
 import streamlit as st
 
 from streamlit_pivot import st_pivot_table
@@ -43,6 +43,28 @@ def _make_drilldown_pagination_data() -> pd.DataFrame:
     return pd.DataFrame(rows)
 
 
+def _make_date_hierarchy_data() -> pd.DataFrame:
+    return pd.DataFrame(
+        {
+            "region": ["US", "US", "US", "US", "EU", "EU", "EU", "EU"],
+            "order_date": pd.to_datetime(
+                [
+                    "2024-01-03",
+                    "2024-01-10",
+                    "2024-02-12",
+                    "2025-01-09",
+                    "2024-01-04",
+                    "2024-01-17",
+                    "2024-02-14",
+                    "2025-01-10",
+                ]
+            ),
+            "revenue": [100, 30, 150, 130, 80, 20, 95, 90],
+            "profit": [40, 10, 55, 45, 30, 8, 34, 32],
+        }
+    )
+
+
 def render_app(data):
     df = data["df"]
 
@@ -229,6 +251,59 @@ def render_app(data):
         on_config_change=noop,
     )
 
+    st.subheader("Date Hierarchy Pivot")
+    st_pivot_table(
+        _make_date_hierarchy_data(),
+        key="test_pivot_date_hierarchy",
+        rows=["region"],
+        columns=["order_date"],
+        values=["revenue", "profit"],
+        aggregation="sum",
+        show_values_as={"revenue": "diff_from_prev"},
+        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(
+        {
+            "order_date": pd.to_datetime(
+                ["2019-03-01", "2020-06-15", "2021-09-10", "2023-01-20", "2024-11-05"]
+            ),
+            "revenue": [100, 200, 300, 400, 500],
+        }
+    )
+    st_pivot_table(
+        adaptive_year_df,
+        key="test_pivot_adaptive_year",
+        rows=["order_date"],
+        values=["revenue"],
+        aggregation="sum",
+        interactive=True,
+        on_config_change=noop,
+    )
+
+    # Adaptive date grain: 3-month dataset -> auto-defaults to "month"
+    st.subheader("Adaptive Grain (3 Month)")
+    adaptive_month_df = pd.DataFrame(
+        {
+            "order_date": pd.to_datetime(
+                ["2024-06-01", "2024-06-15", "2024-07-10", "2024-08-05", "2024-08-28"]
+            ),
+            "revenue": [10, 20, 30, 40, 50],
+        }
+    )
+    st_pivot_table(
+        adaptive_month_df,
+        key="test_pivot_adaptive_month",
+        rows=["order_date"],
+        values=["revenue"],
+        aggregation="sum",
+        interactive=True,
+        on_config_change=noop,
+    )
+
     drill_df = _make_drilldown_pagination_data()
 
     st.subheader("Drilldown Pagination (Client)")

e2e_playwright/pivot_table_interactions_test.py

@@ -239,6 +239,87 @@ def test_header_menu_show_values_as_pct(page_at_app: Page):
     expect(revenue_totals.first).to_contain_text("%", timeout=10000)
 
 
+def test_date_hierarchy_uses_adaptive_default_and_enables_comparisons(
+    page_at_app: Page,
+):
+    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)
+
+    expect(container.get_by_text("order_date (Quarter)")).to_be_visible(timeout=5000)
+    expect(container.get_by_text("Q1 2024")).to_be_visible(timeout=5000)
+    expect(container.get_by_text("Q1 2025")).to_be_visible(timeout=5000)
+
+    menu = open_header_menu(
+        page,
+        container.get_by_test_id("header-menu-trigger-revenue").first,
+        "header-menu-revenue",
+    )
+    expect(menu.get_by_test_id("header-display-diff_from_prev")).to_be_visible(
+        timeout=5000
+    )
+    expect(menu.get_by_test_id("header-display-diff_from_prev_year")).to_be_visible(
+        timeout=5000
+    )
+    close_header_menu(page, "header-menu-revenue")
+
+
+def test_date_hierarchy_supports_drill_week_and_original(page_at_app: Page):
+    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)
+
+    menu = open_header_menu(
+        page,
+        container.get_by_test_id("header-menu-trigger-order_date").first,
+        "header-menu-order_date",
+    )
+    grain_select = menu.get_by_test_id("header-date-grain")
+    expect(grain_select).to_have_value("quarter")
+
+    click_menu_item(menu.get_by_test_id("header-date-drill-up"))
+    close_header_menu(page, "header-menu-order_date")
+    expect(container.get_by_text("order_date (Year)")).to_be_visible(timeout=5000)
+    expect(container.get_by_text("2024")).to_be_visible(timeout=5000)
+
+    menu = open_header_menu(
+        page,
+        container.get_by_test_id("header-menu-trigger-order_date").first,
+        "header-menu-order_date",
+    )
+    grain_select = menu.get_by_test_id("header-date-grain")
+    grain_select.select_option("week")
+    close_header_menu(page, "header-menu-order_date")
+    expect(container.get_by_text("order_date (Week)")).to_be_visible(timeout=5000)
+    expect(container.get_by_text("2024-W01")).to_be_visible(timeout=5000)
+
+    menu = open_header_menu(
+        page,
+        container.get_by_test_id("header-menu-trigger-order_date").first,
+        "header-menu-order_date",
+    )
+    grain_select = menu.get_by_test_id("header-date-grain")
+    grain_select.select_option("")
+    close_header_menu(page, "header-menu-order_date")
+    expect(container.get_by_text("order_date")).to_be_visible(timeout=5000)
+
+    menu = open_header_menu(
+        page,
+        container.get_by_test_id("header-menu-trigger-revenue").first,
+        "header-menu-revenue",
+    )
+    expect(menu.get_by_test_id("header-display-diff_from_prev")).to_have_count(0)
+    close_header_menu(page, "header-menu-revenue")
+
+
 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
@@ -901,3 +982,34 @@ def test_drilldown_hybrid_pagination_navigates(page_at_app: Page):
     panel = page.get_by_test_id("drilldown-panel")
     expect(panel).to_be_visible(timeout=30000)
     expect(panel.locator("text=Page 1 of 2")).to_be_visible(timeout=30000)
+
+
+# ---------------------------------------------------------------------------
+# Adaptive date grain e2e tests
+# ---------------------------------------------------------------------------
+
+
+def test_adaptive_grain_multi_year_defaults_to_year(page_at_app: Page):
+    """Multi-year dataset auto-defaults to year-level bucketing."""
+    page = page_at_app
+    container = (
+        page.locator(".st-key-test_pivot_adaptive_year")
+        .get_by_test_id("pivot-container")
+        .first
+    )
+    expect(container.get_by_test_id("pivot-table")).to_be_visible(timeout=15000)
+    header = container.locator("th").filter(has_text="order_date (Year)")
+    expect(header).to_be_visible(timeout=10000)
+
+
+def test_adaptive_grain_3month_defaults_to_month(page_at_app: Page):
+    """3-month dataset auto-defaults to month-level bucketing."""
+    page = page_at_app
+    container = (
+        page.locator(".st-key-test_pivot_adaptive_month")
+        .get_by_test_id("pivot-container")
+        .first
+    )
+    expect(container.get_by_test_id("pivot-table")).to_be_visible(timeout=15000)
+    header = container.locator("th").filter(has_text="order_date (Month)")
+    expect(header).to_be_visible(timeout=10000)