Clean up

Author: mayagbarnes

README.md

@@ -57,7 +57,7 @@ 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). |
-| `interactive` | `bool` | `True` | Enable toolbar controls for reconfiguring the pivot. |
+| `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
 
@@ -99,9 +99,9 @@ Returns a `PivotTableResult` dict containing the current `config` state.
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `on_cell_click` | `Callable[[], None] \| None` | `None` | Called when a user clicks a data cell. Read the payload from `st.session_state[key]`. |
-| `on_config_change` | `Callable[[], None] \| None` | `None` | Called when the user changes the pivot config via the toolbar. |
+| `on_config_change` | `Callable[[], None] \| None` | `None` | Called when the user changes the pivot config interactively, including toolbar and header-menu actions. |
 | `enable_drilldown` | `bool` | `True` | Show an inline drill-down panel with source records when a cell is clicked. |
-| `locked` | `bool` | `False` | Freeze toolbar config controls (rows/columns/values/per-measure aggregation/settings). Sorting and filtering via header menus remain available. |
+| `locked` | `bool` | `False` | Viewer mode with exploration enabled. Toolbar config controls and settings toggles are disabled, while header-menu sorting/filtering and drill-down remain available. |
 | `export_filename` | `str \| None` | `None` | Base filename (without extension) for exported files. Date and extension are appended automatically. Defaults to `"pivot-table"`. |
 
 #### Data Control
@@ -137,6 +137,7 @@ Returns a `PivotTableResult` dict containing the current `config` state.
 ```python
 st_pivot_table(
     df,
+    key="aggregation_example",
     rows=["Region"],
     columns=["Year"],
     values=["Revenue", "Units", "Price"],
@@ -166,6 +167,7 @@ Optional synthetic-measure fields:
 ```python
 st_pivot_table(
     df,
+    key="synthetic_measures_example",
     rows=["Region"],
     columns=["Year"],
     values=["Revenue"],
@@ -238,6 +240,7 @@ Display measures as percentages instead of raw numbers.
 ```python
 st_pivot_table(
     df,
+    key="show_values_as_example",
     rows=["Region"],
     columns=["Year"],
     values=["Revenue", "Profit"],
@@ -266,12 +269,18 @@ A single string applies to all value fields. A dict maps field names to patterns
 # Per-field formatting
 st_pivot_table(
     df,
+    key="number_format_per_field_example",
     values=["Revenue", "Profit"],
     number_format={"Revenue": "$,.0f", "Profit": ",.2f"},
 )
 
 # Global format for all fields
-st_pivot_table(df, values=["Revenue"], number_format="$,.0f")
+st_pivot_table(
+    df,
+    key="number_format_global_example",
+    values=["Revenue"],
+    number_format="$,.0f",
+)
 ```
 
 ### Conditional Formatting
@@ -331,6 +340,7 @@ Multiple rules can be combined:
 ```python
 st_pivot_table(
     df,
+    key="conditional_formatting_example",
     values=["Revenue", "Profit", "Units"],
     conditional_formatting=[
         {"type": "data_bars", "apply_to": ["Revenue"], "color": "#1976d2", "fill": "gradient"},
@@ -354,10 +364,14 @@ Control how null/NaN values in the source data are treated.
 
 ```python
 # Global mode
-st_pivot_table(df, null_handling="zero")
+st_pivot_table(df, key="null_handling_global_example", null_handling="zero")
 
 # Per-field modes
-st_pivot_table(df, null_handling={"Region": "separate", "Revenue": "zero"})
+st_pivot_table(
+    df,
+    key="null_handling_per_field_example",
+    null_handling={"Region": "separate", "Revenue": "zero"},
+)
 ```
 
 ### Subtotals and Row Grouping
@@ -367,6 +381,7 @@ With 2+ row dimensions, enable subtotals to see group-level aggregations with co
 ```python
 st_pivot_table(
     df,
+    key="subtotals_example",
     rows=["Region", "Category"],
     columns=["Year"],
     values=["Revenue"],
@@ -402,6 +417,7 @@ With 2+ column dimensions, column groups can be collapsed into subtotal columns.
 ```python
 st_pivot_table(
     df,
+    key="column_groups_example",
     rows=["Region"],
     columns=["Year", "Category"],
     values=["Revenue"],
@@ -442,11 +458,12 @@ result = st_pivot_table(
 
 ### Locked Mode
 
-Freeze toolbar config controls so end-users cannot change rows, columns, values, per-measure aggregation, or display settings. The entire utility menu (reset, swap, config import/export, data export, settings) is hidden. Sorting and filtering via header menus remain available.
+Use `locked=True` for a viewer-mode experience with exploration enabled. Toolbar config controls stay locked so end-users cannot change rows, columns, values, per-measure aggregation, or settings toggles. Reset, Swap, config import/export, and data export are hidden, while the Settings gear remains visible so users can inspect settings and use Expand/Collapse All group controls. Header-menu sorting and filtering remain available, and drill-down still works.
 
 ```python
 st_pivot_table(
     df,
+    key="locked_mode_example",
     rows=["Region"],
     columns=["Year"],
     values=["Revenue"],
@@ -467,7 +484,11 @@ When `interactive=True`, hovering over the top-right of the toolbar reveals util
 | **Export Data** | Open the export popover (CSV / TSV / Clipboard). Use `export_filename` to customize the download filename. |
 | **Settings** (gear icon) | Opens a popover with display toggles: Row Totals, Column Totals, Subtotals, Repeat Labels, Sticky Headers, and Expand/Collapse All group controls |
 
-In **locked mode**, the entire utility menu (including Settings) is hidden. Only sorting and filtering via header menus remain available.
+In **locked mode**, Reset, Swap, config import/export, and data export are hidden. The Settings gear remains visible, settings toggles are disabled, group expand/collapse actions remain available, and header-menu sorting and filtering stay enabled.
+
+### Non-Interactive Mode
+
+Set `interactive=False` to render a read-only pivot view. This hides the toolbar and disables header-menu config actions (sorting, filtering, and `Show Values As`). Cell clicks and drill-down remain available.
 
 ---
 
@@ -516,7 +537,7 @@ For total cells, `rowKey` or `colKey` will be `["Total"]` and the corresponding
 
 ### Config State
 
-The returned `config` dict contains the full current configuration including any changes the user made via the toolbar. Use this to persist user customizations or synchronize multiple components.
+The returned `config` dict contains the current supported configuration state, including interactive changes such as rows, columns, values, aggregation, totals, sorting, filtering, and display options. Use this to persist user customizations or synchronize multiple components.
 
 ---
 
@@ -550,7 +571,7 @@ uv pip install -e '.[with-streamlit]' --force-reinstall
 uv run streamlit run streamlit_app.py
 ```
 
-The example app (`streamlit_app.py`) contains 12 sections demonstrating every feature with interactive examples and inline documentation.
+The example app (`streamlit_app.py`) contains 13 sections demonstrating every feature with interactive examples and inline documentation.
 
 ### Building the frontend
 
@@ -583,7 +604,7 @@ npx vitest run
    uv build
    ```
 
-Output: `dist/streamlit_pivot_table-0.0.1-py3-none-any.whl`
+Output: `dist/streamlit_pivot_table-0.1.0-py3-none-any.whl`
 
 ### Requirements
 

SKILL.md

@@ -471,7 +471,7 @@ When `interactive=True`, hovering over the top-right of the toolbar reveals util
 | **Export Data** | Open the export popover (CSV / TSV / Clipboard). Use `export_filename` to customize the download filename. |
 | **Settings** (gear icon) | Opens a popover with display toggles: Row Totals, Column Totals, Subtotals, Repeat Labels, Sticky Headers, and Expand/Collapse All group controls |
 
-In **locked mode**, the entire utility menu (including Settings) is hidden. Only sorting and filtering via header menus remain available.
+In **locked mode**, Reset, Swap, config import/export, and data export are hidden. The Settings gear remains visible, its toggles are disabled, and sorting/filtering via header menus remain available.
 
 ---
 
@@ -543,7 +543,7 @@ This section covers deploying the pivot table component (as a `.whl` file) into
 
 ```
 To set up your SiS on SPCS app with the pivot table component, I need:
-1. The path to your .whl file (e.g., ~/Downloads/streamlit_pivot_table-0.0.1-py3-none-any.whl)
+1. The path to your .whl file (e.g., ~/Downloads/streamlit_pivot_table-0.1.0-py3-none-any.whl)
 2. Do you have an existing SiS project directory with snowflake.yml, or should I create one from scratch?
 3. What Snowflake table(s) will the app query?
 4. What compute pool should the app run on? (e.g., MY_COMPUTE_POOL)
@@ -553,7 +553,7 @@ To set up your SiS on SPCS app with the pivot table component, I need:
 
 **After the user responds**, derive these values from the `.whl` filename and use them in ALL subsequent steps:
 
-- **`WHL_FILENAME`**: The `.whl` file name (e.g., `streamlit_pivot_table-0.0.1-py3-none-any.whl`)
+- **`WHL_FILENAME`**: The `.whl` file name (e.g., `streamlit_pivot_table-0.1.0-py3-none-any.whl`)
 - **`PACKAGE_NAME`**: The portion before the first version segment, with hyphens replaced by underscores (e.g., `streamlit_pivot_table`)
 - **`TABLE_NAMES`**: The Snowflake table(s) the user wants to query
 - **`COMPUTE_POOL`**: The SPCS compute pool name for the app runtime

e2e_playwright/pivot_table_test.py

@@ -75,7 +75,9 @@ def get_pivot(page: Page, key: str) -> Locator:
 
 def open_settings_popover(container: Locator):
     """Open the gear settings popover in the toolbar."""
-    container.get_by_test_id("toolbar-settings").click()
+    button = container.get_by_test_id("toolbar-settings")
+    button.scroll_into_view_if_needed()
+    button.evaluate("el => el.click()")
     expect(container.get_by_test_id("toolbar-settings-panel")).to_be_visible(
         timeout=5000
     )
@@ -527,7 +529,7 @@ def test_header_menu_sort_key_asc(page_at_app: Page):
     expect(container.get_by_test_id("pivot-table")).to_be_visible(timeout=15000)
 
     container.get_by_test_id("header-menu-trigger-Region").click()
-    menu = container.get_by_test_id("header-menu-Region")
+    menu = page.get_by_test_id("header-menu-Region")
     expect(menu).to_be_visible(timeout=5000)
 
     menu.get_by_test_id("header-sort-key-asc").click()
@@ -549,10 +551,10 @@ def test_header_menu_sort_key_desc(page_at_app: Page):
     expect(container.get_by_test_id("pivot-table")).to_be_visible(timeout=15000)
 
     container.get_by_test_id("header-menu-trigger-Region").click()
-    menu = container.get_by_test_id("header-menu-Region")
+    menu = page.get_by_test_id("header-menu-Region")
     expect(menu).to_be_visible(timeout=5000)
 
-    menu.get_by_test_id("header-sort-key-desc").click()
+    menu.get_by_test_id("header-sort-key-desc").evaluate("el => el.click()")
 
     expect(container.get_by_test_id("pivot-row-header").first).to_have_text(
         "West", timeout=10000
@@ -881,28 +883,29 @@ def test_locked_mode_toolbar_disabled(page_at_app: Page):
     expect(container.get_by_test_id("toolbar-settings")).to_be_visible()
 
 
-def test_locked_mode_header_filter_still_works(page_at_app: Page):
-    """In locked mode, header menu opens and filtering still functions."""
+def test_locked_mode_header_sort_and_filter_still_work(page_at_app: Page):
+    """In locked mode, header-menu exploration remains available."""
     page = page_at_app
     container = get_pivot(page, "test_pivot_locked")
     expect(container.get_by_test_id("pivot-table")).to_be_visible(timeout=15000)
 
     trigger = container.get_by_test_id("header-menu-trigger-Region")
     expect(trigger).to_be_visible()
 
-    trigger.click()
+    trigger.evaluate("el => el.click()")
     menu = container.get_by_test_id("header-menu-Region")
     expect(menu).to_be_visible(timeout=5000)
 
-    # Sort section is hidden in locked mode
-    expect(menu.get_by_test_id("header-menu-sort")).to_have_count(0)
-
-    # Filter section remains functional
+    sort_section = menu.get_by_test_id("header-menu-sort")
+    expect(sort_section).to_be_visible()
     filter_section = menu.get_by_test_id("header-menu-filter")
     expect(filter_section).to_be_visible()
     checkboxes = filter_section.locator("input[type=checkbox]")
     assert checkboxes.count() > 0
 
+    menu.get_by_test_id("header-sort-key-desc").click()
+    expect(container.get_by_test_id("pivot-row-header").first).to_have_text("West")
+
 
 # =====================================================================
 # 12. Empty / Edge Cases (3 tests)

e2e_playwright/test-requirements.txt

@@ -6,5 +6,5 @@ pytest-xdist
 requests>=2.31.0
 pandas>=1.5
 
-dist/streamlit_pivot_table-0.0.1-py3-none-any.whl
+dist/streamlit_pivot_table-0.1.0-py3-none-any.whl
 streamlit>=1.51.0

pyproject.toml

@@ -18,15 +18,15 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "streamlit-pivot-table"
-version = "0.0.1"
+version = "0.1.0"
 description = "BI-focused pivot table component for Streamlit"
 readme = "README.md"
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICES"]
 authors = [{ name = "Snowflake Inc", email = "hello@streamlit.io" }]
 maintainers = [{ name = "Snowflake Inc", email = "hello@streamlit.io" }]
 classifiers = [
-  "Development Status :: 3 - Alpha",
+  "Development Status :: 4 - Beta",
   "Intended Audience :: Developers",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3.10",
@@ -41,7 +41,7 @@ requires-python = ">=3.10"
 [project.urls]
 Homepage = "https://streamlit.io"
 "Source Code" = "https://github.com/streamlit/streamlit-pivot-table"
-"Bug Tracker" = "https://github.com/streamlit/streamlit/issues"
+"Bug Tracker" = "https://github.com/streamlit/streamlit-pivot-table/issues"
 Community = "https://discuss.streamlit.io/"
 
 [project.optional-dependencies]

streamlit_app.py

@@ -172,9 +172,9 @@
 - Click the **⋮** menu icon on the "Region" header → uncheck regions to filter them out.
 - Use the search box to find specific values quickly.
 
-**Right table** is **locked** — the toolbar config controls and utility menu
-(reset, swap, import/export, settings) are all hidden, but you can still
-sort and filter via the column header menus.
+**Right table** is **locked** — the toolbar config controls and utility actions
+(reset, swap, import/export) are hidden, the **Settings** gear remains visible
+for inspection only, and you can still sort and filter via the column header menus.
 
 **API parameters used:** `hidden_from_aggregators`, `sorters`, `locked`
 """

streamlit_pivot_table/__init__.py

@@ -19,7 +19,7 @@
 
 import json
 import warnings
-from typing import TYPE_CHECKING, Any, TypedDict
+from typing import TYPE_CHECKING, Any, TypedDict, cast
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -54,6 +54,7 @@ class SortConfig(TypedDict, total=False):
     direction: str  # "asc" | "desc"
     value_field: str  # required when by="value"
     col_key: list[str]  # for row sort: sort within this specific column
+    dimension: str  # optional: scope sort to this dimension level and below
 
 
 class PivotConfig(TypedDict, total=False):
@@ -410,8 +411,8 @@ def st_pivot_table(
     sorters: dict[str, list[str]] | None = None,
     locked: bool = False,
     menu_limit: int | None = None,
-    row_sort: dict[str, Any] | None = None,
-    col_sort: dict[str, Any] | None = None,
+    row_sort: SortConfig | None = None,
+    col_sort: SortConfig | None = None,
     # Phase 3 parameters
     sticky_headers: bool = True,
     show_subtotals: bool | list[str] = False,
@@ -460,7 +461,9 @@ def st_pivot_table(
     empty_cell_value : str
         Display string for cells with no data.
     interactive : bool
-        If True, the user can reconfigure the pivot via toolbar controls.
+        If True, the user can reconfigure the pivot via toolbar controls and
+        header-menu actions. If False, the toolbar is hidden and header-menu
+        sort/filter/show-values-as actions are disabled.
     height : int or None
         Fixed height in pixels. None means auto-size (capped by ``max_height``).
     max_height : int
@@ -493,8 +496,10 @@ def st_pivot_table(
         Custom sort orderings per dimension. Maps column name to a list
         of values in the desired order.
     locked : bool
-        If True, toolbar config controls are disabled (filtering still
-        allowed). Defaults to False.
+        If True, toolbar config controls are disabled. The settings gear stays
+        visible so users can inspect settings and expand/collapse groups, but
+        settings toggles are disabled. Header-menu sorting and filtering remain
+        available. Defaults to False.
     menu_limit : int or None
         Max items to show in the header-menu filter checklist. Defaults
         to 50 when None.
@@ -628,11 +633,15 @@ def st_pivot_table(
     if sorters is not None:
         if not isinstance(sorters, dict):
             raise TypeError(f"sorters must be a dict, got {type(sorters).__name__}")
-        for k, v in sorters.items():
-            if not isinstance(k, str):
-                raise TypeError(f"sorters keys must be strings, got {type(k).__name__}")
-            if not isinstance(v, list) or not all(isinstance(s, str) for s in v):
-                raise TypeError(f"sorters[{k!r}] must be a list of strings")
+        for sorter_key, sorter_values in sorters.items():
+            if not isinstance(sorter_key, str):
+                raise TypeError(
+                    f"sorters keys must be strings, got {type(sorter_key).__name__}"
+                )
+            if not isinstance(sorter_values, list) or not all(
+                isinstance(s, str) for s in sorter_values
+            ):
+                raise TypeError(f"sorters[{sorter_key!r}] must be a list of strings")
 
     if not isinstance(locked, bool):
         raise TypeError(f"locked must be a bool, got {type(locked).__name__}")
@@ -930,4 +939,4 @@ def st_pivot_table(
     if on_cell_click is not None:
         mount_kwargs["on_cell_click_change"] = on_cell_click
 
-    return _component(**mount_kwargs)
+    return cast(PivotTableResult, _component(**mount_kwargs))

streamlit_pivot_table/frontend/src/config/Toolbar.tsx

@@ -63,7 +63,7 @@ export interface ToolbarProps {
   onConfigChange?: (config: PivotConfigV1) => void;
   /** Original config from Python for reset. If omitted, reset is hidden. */
   initialConfig?: PivotConfigV1;
-  /** Lock config controls (filtering still allowed). */
+  /** Lock config controls while keeping header-menu exploration enabled. */
   locked?: boolean;
   /** Columns that cannot be reassigned between zones. */
   frozenColumns?: Set<string>;