Initial pass - hierarchy layout option

Author: mayagbarnes

README.md

@@ -95,6 +95,7 @@ Returns a `PivotTableResult` dict containing the current `config` state.
 | `height` | `int \| None` | `None` | Fixed height in pixels. `None` means auto-size (capped by `max_height`). |
 | `max_height` | `int` | `500` | Maximum auto-size height in pixels. Table becomes scrollable when content exceeds this. Ignored when `height` is set. |
 | `sticky_headers` | `bool` | `True` | Column headers stick to the top of the scroll container. |
+| `row_layout` | `"table" \| "hierarchy"` | `"table"` | Controls how row dimensions are rendered. `"table"` uses separate row-header columns, while `"hierarchy"` renders a single indented tree column with breadcrumb-level controls. |
 
 #### Interactivity and Callbacks
 
@@ -332,6 +333,34 @@ When a temporal field is on `columns`, parent headers such as `2024` or `Q1 2024
 
 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.
 
+### Row Layout Modes
+
+Choose between two row presentation modes:
+
+| Mode | Value | Description |
+|------|-------|-------------|
+| Table | `"table"` | Classic pivot layout with one visible row-header column per row dimension, plus expanded temporal levels as separate row-header columns when applicable. |
+| Hierarchy | `"hierarchy"` | Compact tree layout with a single visible row hierarchy column, indentation by depth, breadcrumb controls, and inline expand/collapse. |
+
+```python
+st_pivot_table(
+    df,
+    key="row_layout_example",
+    rows=["Region", "Category", "Customer"],
+    columns=["Year"],
+    values=["Revenue", "Profit"],
+    row_layout="hierarchy",
+)
+```
+
+Behavior notes:
+
+- `table` preserves the traditional multi-column row-axis layout and works naturally with `repeat_row_labels`.
+- `hierarchy` renders parent groups before their children and uses a single visible row column rather than separate columns per row dimension.
+- Temporal date hierarchies work in both layouts. In `table`, date levels expand into separate row-header columns; in `hierarchy`, those same levels render as nested tree levels within the single hierarchy column.
+- Export parity is preserved. CSV, TSV, clipboard, and XLSX outputs follow the selected row layout, including hierarchy indentation.
+- Execution-mode parity is also preserved. `row_layout` works in both `client_only` and `threshold_hybrid`; the layout mostly affects rendering, not whether hybrid execution is allowed.
+
 ### Number Format Patterns
 
 Patterns follow a lightweight d3-style syntax.
@@ -569,6 +598,8 @@ st_pivot_table(
 **Limitations:**
 - Synthetic measures are not supported in hybrid mode (falls back to client-side).
 
+`row_layout` is supported in both execution paths. Switching between `table` and `hierarchy` does not by itself force a fallback out of `threshold_hybrid`.
+
 ### Locked Mode
 
 Use `locked=True` for a viewer-mode experience with exploration enabled. The Settings Panel and toolbar config controls are locked so end-users cannot change rows, columns, values, or per-measure aggregation. Reset, Swap, and config import/export are hidden, while data export remains available. Expand/Collapse All group controls remain accessible in the toolbar utility menu. Header-menu sorting, filtering, and `Show Values As` remain available, and drill-down still works.
@@ -608,7 +639,9 @@ The panel contains:
 - **Available Fields** — unassigned columns shown as draggable chips. Click a chip's menu to add it to Rows, Columns, or Values. When more than 8 fields are available, a search input appears.
 - **Rows / Columns / Values** drop zones — drag chips to reorder within a zone, drag between zones, or use the `x` button to remove. Value chips show an aggregation picker (click the badge to change).
 - **Synthetic Measures** — click **+ Add measure** to create derived metrics (ratio of sums, difference of sums) with optional format patterns.
-- **Display Toggles** — Row Totals, Column Totals, Subtotals, Repeat Labels, and Sticky Headers.
+- **Display Toggles** — Row Totals, Column Totals, Subtotals, Repeat Labels, Row Layout, and Sticky Headers.
+
+In `hierarchy` row layout, `Repeat Labels` is not applicable because the row axis is rendered as a single hierarchy column rather than repeated across separate row-dimension columns.
 
 External config changes (toolbar DnD, Reset, Swap, config import) while the panel is open will close it and discard uncommitted edits.
 

streamlit_layout_demo.py

@@ -0,0 +1,278 @@
+# Copyright 2025 Snowflake Inc.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Standalone demo app for comparing row layout modes.
+
+Run locally with:
+    streamlit run streamlit_layout_demo.py
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import Literal, cast
+
+import pandas as pd  # type: ignore[import-untyped]
+import streamlit as st
+
+from streamlit_pivot import st_pivot_table
+
+
+def make_sales_demo_data() -> pd.DataFrame:
+    rows: list[dict[str, object]] = []
+    scenarios = [
+        ("BI Tools", "Streamlit", "Enterprise", "Acme Corp", 2024, 420_000, 138_000),
+        ("BI Tools", "Streamlit", "Enterprise", "Globex", 2024, 355_000, 122_000),
+        ("BI Tools", "Sigma", "Enterprise", "Acme Corp", 2024, 390_000, 129_000),
+        ("BI Tools", "Sigma", "Mid Market", "Initech", 2024, 210_000, 71_000),
+        ("BI Tools", "Power BI", "Enterprise", "Umbrella", 2024, 330_000, 111_000),
+        ("BI Tools", "Power BI", "Mid Market", "Soylent", 2024, 180_000, 58_000),
+        (
+            "AI Apps",
+            "Cortex Analyst",
+            "Enterprise",
+            "Acme Corp",
+            2024,
+            510_000,
+            189_000,
+        ),
+        ("AI Apps", "Cortex Analyst", "Enterprise", "Globex", 2024, 470_000, 172_000),
+        ("AI Apps", "Copilot", "Mid Market", "Initech", 2024, 260_000, 88_000),
+        ("AI Apps", "Copilot", "SMB", "Initrode", 2024, 120_000, 36_000),
+        ("AI Apps", "Notebook UX", "Enterprise", "Umbrella", 2024, 300_000, 102_000),
+        ("AI Apps", "Notebook UX", "SMB", "Soylent", 2024, 95_000, 29_000),
+        ("BI Tools", "Streamlit", "Enterprise", "Acme Corp", 2025, 465_000, 151_000),
+        ("BI Tools", "Streamlit", "Enterprise", "Globex", 2025, 380_000, 131_000),
+        ("BI Tools", "Sigma", "Enterprise", "Acme Corp", 2025, 410_000, 135_000),
+        ("BI Tools", "Sigma", "Mid Market", "Initech", 2025, 232_000, 79_000),
+        ("BI Tools", "Power BI", "Enterprise", "Umbrella", 2025, 348_000, 118_000),
+        ("BI Tools", "Power BI", "Mid Market", "Soylent", 2025, 192_000, 61_000),
+        (
+            "AI Apps",
+            "Cortex Analyst",
+            "Enterprise",
+            "Acme Corp",
+            2025,
+            560_000,
+            205_000,
+        ),
+        ("AI Apps", "Cortex Analyst", "Enterprise", "Globex", 2025, 498_000, 181_000),
+        ("AI Apps", "Copilot", "Mid Market", "Initech", 2025, 279_000, 95_000),
+        ("AI Apps", "Copilot", "SMB", "Initrode", 2025, 130_000, 39_000),
+        ("AI Apps", "Notebook UX", "Enterprise", "Umbrella", 2025, 322_000, 110_000),
+        ("AI Apps", "Notebook UX", "SMB", "Soylent", 2025, 108_000, 33_000),
+    ]
+    for use_case, product, segment, customer, year, arr, profit in scenarios:
+        rows.append(
+            {
+                "Use Case": use_case,
+                "Product": product,
+                "Segment": segment,
+                "Customer": customer,
+                "Year": year,
+                "ARR": arr,
+                "Profit": profit,
+                "Deals": 1,
+            }
+        )
+    return pd.DataFrame(rows)
+
+
+def make_temporal_demo_data() -> pd.DataFrame:
+    rows: list[dict[str, object]] = []
+    for region, customers, base in [
+        ("North America", ["Acme Corp", "Globex"], 120_000),
+        ("Europe", ["Initech", "Umbrella"], 95_000),
+    ]:
+        for month_index, month in enumerate([1, 2, 3, 4, 5, 6], start=1):
+            for customer_index, customer in enumerate(customers, start=1):
+                booking = base + month_index * 8_000 + customer_index * 3_500
+                rows.append(
+                    {
+                        "Order Date": dt.date(2024, month, 1),
+                        "Region": region,
+                        "Customer": customer,
+                        "Bookings": booking,
+                        "Pipeline": round(booking * 1.45),
+                    }
+                )
+    return pd.DataFrame(rows)
+
+
+st.set_page_config(page_title="Pivot Row Layout Demo", layout="wide")
+st.title("Pivot Row Layout Demo")
+st.caption(
+    "This standalone app compares the two row rendering modes: "
+    '`row_layout="table"` and `row_layout="hierarchy"`.'
+)
+
+st.markdown(
+    """
+Use this page to compare the same pivot configuration rendered in two ways:
+
+- **Table**: one visible row-header column per row field
+- **Hierarchy**: a single indented tree-style first column with parent rows and inline toggles
+
+Open the **Settings** panel on either interactive pivot to switch the layout at runtime.
+"""
+)
+
+sales_df = make_sales_demo_data()
+temporal_df = make_temporal_demo_data()
+
+st.divider()
+st.subheader("Business Hierarchy Comparison")
+st.markdown(
+    """
+This example uses a business hierarchy with four row levels so the layout difference is obvious.
+The underlying grouping is identical in both pivots; only the row presentation changes.
+"""
+)
+
+st.markdown("#### Table Layout")
+st_pivot_table(
+    sales_df,
+    key="layout_demo_table",
+    rows=["Use Case", "Product", "Segment", "Customer"],
+    columns=["Year"],
+    values=["ARR", "Profit"],
+    aggregation={"ARR": "sum", "Profit": "sum"},
+    show_totals=True,
+    show_subtotals=True,
+    repeat_row_labels=False,
+    row_layout="table",
+    number_format={"ARR": "$,.0f", "Profit": "$,.0f"},
+    max_height=420,
+)
+
+st.markdown("#### Hierarchy Layout")
+st_pivot_table(
+    sales_df,
+    key="layout_demo_hierarchy",
+    rows=["Use Case", "Product", "Segment", "Customer"],
+    columns=["Year"],
+    values=["ARR", "Profit"],
+    aggregation={"ARR": "sum", "Profit": "sum"},
+    show_totals=True,
+    row_layout="hierarchy",
+    number_format={"ARR": "$,.0f", "Profit": "$,.0f"},
+    max_height=420,
+)
+
+with st.expander("View code for the business hierarchy example"):
+    st.code(
+        """
+st_pivot_table(
+    sales_df,
+    key="layout_demo_table",
+    rows=["Use Case", "Product", "Segment", "Customer"],
+    columns=["Year"],
+    values=["ARR", "Profit"],
+    aggregation={"ARR": "sum", "Profit": "sum"},
+    show_totals=True,
+    show_subtotals=True,
+    repeat_row_labels=False,
+    row_layout="table",
+)
+
+st_pivot_table(
+    sales_df,
+    key="layout_demo_hierarchy",
+    rows=["Use Case", "Product", "Segment", "Customer"],
+    columns=["Year"],
+    values=["ARR", "Profit"],
+    aggregation={"ARR": "sum", "Profit": "sum"},
+    show_totals=True,
+    row_layout="hierarchy",
+)
+""",
+        language="python",
+    )
+
+st.divider()
+st.subheader("Temporal Hierarchy Comparison")
+st.markdown(
+    """
+This example puts a date field on rows so you can compare how temporal parents appear.
+In **table** mode the renderer expands the date hierarchy into visible row-header columns.
+In **hierarchy** mode those same levels render as a single indented tree.
+"""
+)
+
+st.markdown("#### Table Layout with Row Date Hierarchy")
+st_pivot_table(
+    temporal_df,
+    key="layout_demo_temporal_table",
+    rows=["Order Date", "Region", "Customer"],
+    columns=[],
+    values=["Bookings", "Pipeline"],
+    aggregation={"Bookings": "sum", "Pipeline": "sum"},
+    show_totals=True,
+    row_layout="table",
+    number_format={"Bookings": "$,.0f", "Pipeline": "$,.0f"},
+    max_height=420,
+)
+
+st.markdown("#### Hierarchy Layout with Row Date Hierarchy")
+st_pivot_table(
+    temporal_df,
+    key="layout_demo_temporal_hierarchy",
+    rows=["Order Date", "Region", "Customer"],
+    columns=[],
+    values=["Bookings", "Pipeline"],
+    aggregation={"Bookings": "sum", "Pipeline": "sum"},
+    show_totals=True,
+    row_layout="hierarchy",
+    number_format={"Bookings": "$,.0f", "Pipeline": "$,.0f"},
+    max_height=420,
+)
+
+st.divider()
+st.subheader("Interactive Layout Switch")
+st.markdown(
+    """
+This final pivot starts in whichever mode you choose below so you can inspect the
+same sample data with the exact config parameter that application code would set.
+"""
+)
+
+selected_layout = st.radio(
+    "Initial row layout",
+    options=["table", "hierarchy"],
+    horizontal=True,
+)
+selected_layout = cast(Literal["table", "hierarchy"], selected_layout)
+
+st_pivot_table(
+    sales_df,
+    key="layout_demo_switchable",
+    rows=["Use Case", "Product", "Segment", "Customer"],
+    columns=["Year"],
+    values=["ARR"],
+    aggregation="sum",
+    show_totals=True,
+    row_layout=selected_layout,
+    number_format={"ARR": "$,.0f"},
+    max_height=420,
+)
+
+with st.expander("View sample data"):
+    left, right = st.columns(2)
+    with left:
+        st.markdown("**Business hierarchy sample**")
+        st.dataframe(sales_df, width="stretch")
+    with right:
+        st.markdown("**Temporal hierarchy sample**")
+        st.dataframe(temporal_df, width="stretch")