Feat: support mid_value in color_scale

Author: mayagbarnes

README.md

@@ -517,10 +517,39 @@ Gradient fill between 2 or 3 colors based on min/mid/max values in the column.
     "min_color": "#ffffff",       # required
     "max_color": "#2e7d32",       # required
     "mid_color": "#a5d6a7",       # optional (3-color scale)
+    "mid_value": 0,               # optional numeric anchor for the midpoint
     "include_totals": False,      # optional, default False
 }
 ```
 
+When `mid_color` is provided without `mid_value`, the gradient bends at the
+visual midpoint of the observed column range (current default behavior).
+
+When `mid_value` is also provided, the gradient is anchored at that numeric
+value for a smooth Excel-like diverging scale — ideal for PnL or variance
+columns where `0` should always be the neutral color:
+
+```python
+{
+    "type": "color_scale",
+    "apply_to": ["PnL"],
+    "min_color": "#ff0000",       # darker red for more negative
+    "mid_color": "#ffffff",       # white at 0
+    "max_color": "#0000ff",       # darker blue for more positive
+    "mid_value": 0,
+}
+```
+
+`mid_value` is interpreted in the same numeric space as the underlying
+**aggregated cell values** (i.e. the raw `agg.value()` used by all
+conditional formatting rules), which is the same space as `min_color` /
+`max_color`. This is the natural fit for typical use cases like PnL or
+variance anchored at `0`. Conditional formatting runs **before** any
+`show_values_as` transformation, so pairing `mid_value` with a mode such
+as `"pct_of_total"` will anchor on the raw aggregate, not on the displayed
+percentage. Values outside the observed column range (for example, grand
+totals) clamp to the endpoint colors rather than extrapolating past them.
+
 #### Data Bars
 
 Horizontal bar fill proportional to the cell value.

SKILL.md

@@ -291,10 +291,20 @@ Gradient fill between 2 or 3 colors based on min/mid/max values in the column.
     "min_color": "#ffffff",       # required
     "max_color": "#2e7d32",       # required
     "mid_color": "#a5d6a7",       # optional (3-color scale)
+    "mid_value": 0,               # optional numeric anchor (requires mid_color)
     "include_totals": False,      # optional, default False
 }
 ```
 
+When `mid_value` is set, the gradient is anchored at that numeric value for a
+smooth Excel-like diverging scale (e.g. `mid_value=0` for PnL). `mid_value` is
+interpreted in the same numeric space as the underlying aggregated cell values
+(the raw `agg.value()` used by all conditional formatting rules), i.e. the same
+space as `min_color` / `max_color`. Conditional formatting runs **before** any
+`show_values_as` transformation, so anchoring against a transformed display
+mode like `"pct_of_total"` is not supported. Values outside the observed column
+range clamp to the endpoint colors.
+
 #### Data Bars
 
 Horizontal bar fill proportional to the cell value.

e2e_playwright/e2e_utils.py

@@ -118,6 +118,7 @@
 DATA_PIVOT_KEYS = [
     "test_pivot",
     "test_pivot_cond_fmt",
+    "test_pivot_cond_fmt_mid_value",
     "test_pivot_number_fmt",
     "test_pivot_empty",
     "test_pivot_single_row",

e2e_playwright/pivot_table_data_app.py

@@ -81,6 +81,40 @@ def render_app(data):
         on_config_change=noop,
     )
 
+    st.subheader("Conditional Format Pivot - Mid Value")
+    # Deterministic fixture for e2e mid_value regression: a 3x1 pivot where
+    # the middle cell's value equals `mid_value`, so the browser must render
+    # it with `mid_color` (white) and the other cells with the endpoint
+    # colors (pure red and pure blue).
+    cond_fmt_mid_df = pd.DataFrame(
+        [
+            {"Region": "AA_Low", "Year": 2024, "Value": -100.0},
+            {"Region": "BB_Mid", "Year": 2024, "Value": 0.0},
+            {"Region": "CC_High", "Year": 2024, "Value": 100.0},
+        ]
+    )
+    st_pivot_table(
+        cond_fmt_mid_df,
+        key="test_pivot_cond_fmt_mid_value",
+        rows=["Region"],
+        columns=["Year"],
+        values=["Value"],
+        aggregation="sum",
+        show_totals=False,
+        conditional_formatting=[
+            {
+                "type": "color_scale",
+                "apply_to": ["Value"],
+                "min_color": "#ff0000",
+                "mid_color": "#ffffff",
+                "max_color": "#0000ff",
+                "mid_value": 0,
+            },
+        ],
+        interactive=True,
+        on_config_change=noop,
+    )
+
     st.subheader("Number Format Pivot")
     st_pivot_table(
         df,

e2e_playwright/pivot_table_data_test.py

@@ -47,6 +47,34 @@ def test_conditional_formatting_color_scale(page_at_app: Page):
     ), "Expected at least one data cell to have background-color from color scale"
 
 
+def test_conditional_formatting_color_scale_mid_value(page_at_app: Page):
+    """mid_value anchors the gradient at the specified numeric value.
+
+    Uses the deterministic `test_pivot_cond_fmt_mid_value` fixture whose three
+    row values are exactly min (-100), mid_value (0), and max (100), so the
+    rendered background colors must be the exact endpoint/mid colors
+    configured on the rule.
+    """
+    page = page_at_app
+    container = get_pivot(page, "test_pivot_cond_fmt_mid_value")
+    expect(container.get_by_test_id("pivot-table")).to_be_visible(timeout=15000)
+
+    cells = container.get_by_test_id("pivot-data-cell")
+    expect(cells.first).to_be_visible(timeout=5000)
+    # Three Region rows, one Year column -> exactly three data cells.
+    assert cells.count() == 3
+
+    def bg(cell) -> str:
+        return cell.evaluate("el => window.getComputedStyle(el).backgroundColor")
+
+    # Row order matches dataframe order: AA_Low (min), BB_Mid (mid), CC_High (max).
+    assert bg(cells.nth(0)) == "rgb(255, 0, 0)", "min cell should render min_color"
+    assert (
+        bg(cells.nth(1)) == "rgb(255, 255, 255)"
+    ), "cell at mid_value should render mid_color"
+    assert bg(cells.nth(2)) == "rgb(0, 0, 255)", "max cell should render max_color"
+
+
 def test_conditional_formatting_data_bars(page_at_app: Page):
     """Data bars formatting applies background-image (gradient) to cells."""
     page = page_at_app

streamlit_app.py

@@ -597,6 +597,39 @@ def section_cond_fmt():
         conditional_formatting=cond_fmt_rules,
     )
 
+    st.markdown(
+        """
+#### Diverging color scale anchored at a numeric midpoint (`mid_value`)
+
+Pass `mid_color` with a numeric `mid_value` to anchor a smooth diverging
+gradient at a meaningful midpoint (e.g. `0` for PnL, or a target value).
+Below, the average-profit column is rendered red-white-blue around the
+overall average so cells below average appear red and cells above appear
+blue, regardless of the column's min/max.
+"""
+    )
+
+    avg_profit = float(df["Profit"].mean())
+    st_pivot_table(
+        df,
+        key="cond_fmt_mid_value",
+        rows=["Region"],
+        columns=["Year"],
+        values=["Profit"],
+        aggregation="avg",
+        number_format={"Profit": ",.0f"},
+        conditional_formatting=[
+            {
+                "type": "color_scale",
+                "apply_to": ["Profit"],
+                "min_color": "#c62828",
+                "mid_color": "#ffffff",
+                "max_color": "#1565c0",
+                "mid_value": avg_profit,
+            },
+        ],
+    )
+
     with st.expander("View Code"):
         st.code(
             """
@@ -629,6 +662,26 @@ def section_cond_fmt():
         },
     ],
 )
+
+# Diverging color scale anchored at a numeric midpoint:
+st_pivot_table(
+    df,
+    key="cond_fmt_mid_value",
+    rows=["Region"],
+    columns=["Year"],
+    values=["Profit"],
+    aggregation="avg",
+    conditional_formatting=[
+        {
+            "type": "color_scale",
+            "apply_to": ["Profit"],
+            "min_color": "#c62828",   # red for below-midpoint
+            "mid_color": "#ffffff",   # neutral at mid_value
+            "max_color": "#1565c0",   # blue for above-midpoint
+            "mid_value": df["Profit"].mean(),  # anchor at overall average
+        },
+    ],
+)
 """,
             language="python",
         )

streamlit_pivot/__init__.py

@@ -21,6 +21,7 @@
 import re
 import warnings
 from datetime import date, datetime
+import math
 from math import prod
 from typing import TYPE_CHECKING, Any, Literal, TypedDict, cast
 
@@ -2325,6 +2326,16 @@ def st_pivot_table(
         Each rule is a dict with ``"type"`` (``"color_scale"``,
         ``"data_bars"``, or ``"threshold"``), ``"apply_to"`` (list of
         field names, empty = all), and type-specific keys.
+        ``color_scale`` rules accept optional ``"mid_color"`` and
+        ``"mid_value"`` keys. When ``"mid_value"`` is provided (a finite
+        number, and only valid alongside ``"mid_color"``), the gradient
+        is anchored at that midpoint for a smooth Excel-like diverging
+        scale (for example, ``mid_value=0`` for PnL columns). ``mid_value``
+        is interpreted in the same numeric space as the underlying
+        aggregated cell values (the raw ``agg.value()`` that feeds all
+        conditional formatting rules), not as a post-``show_values_as``
+        display value. Values outside the observed column range clamp
+        to the endpoint colors.
     number_format : str or dict[str, str] or None
         Number format pattern(s). A single string applies to all
         value fields; a dict maps field names to patterns. Use
@@ -2754,6 +2765,26 @@ def st_pivot_table(
                     raise ValueError(
                         f"conditional_formatting[{i}]: color_scale requires 'min_color' and 'max_color'"
                     )
+                if "mid_color" in rule and not isinstance(
+                    rule.get("mid_color", ""), str
+                ):
+                    raise TypeError(
+                        f"conditional_formatting[{i}]['mid_color'] must be a string"
+                    )
+                if "mid_value" in rule and rule["mid_value"] is not None:
+                    mv = rule["mid_value"]
+                    if not rule.get("mid_color"):
+                        raise ValueError(
+                            f"conditional_formatting[{i}]: 'mid_value' requires 'mid_color'"
+                        )
+                    if (
+                        isinstance(mv, bool)
+                        or not isinstance(mv, (int, float))
+                        or not math.isfinite(mv)
+                    ):
+                        raise TypeError(
+                            f"conditional_formatting[{i}]['mid_value'] must be a finite number"
+                        )
             elif rtype == "threshold":
                 conditions = rule.get("conditions")
                 if not isinstance(conditions, list) or len(conditions) == 0:

streamlit_pivot/frontend/src/engine/exportExcel.test.ts

@@ -526,6 +526,51 @@ describe("buildExcelWorkbook", () => {
       ]);
     });
 
+    it("color_scale: mid_value emits a numeric middle cfvo", () => {
+      const grid = makeCondGrid();
+      grid.conditionalFormatting = [
+        {
+          type: "color_scale",
+          apply_to: ["Revenue"],
+          min_color: "#ff0000",
+          mid_color: "#ffffff",
+          max_color: "#0000ff",
+          mid_value: 0,
+        } as ColorScaleRule,
+      ];
+      const wb = buildExcelWorkbook(ExcelJS, grid);
+      const cfs = getCf(wb.worksheets[0]);
+      const rule = cfs[0].rules[0];
+      expect(rule.cfvo).toEqual([
+        { type: "min" },
+        { type: "num", value: 0 },
+        { type: "max" },
+      ]);
+      expect(rule.color).toEqual([
+        { argb: "FFFF0000" },
+        { argb: "FFFFFFFF" },
+        { argb: "FF0000FF" },
+      ]);
+    });
+
+    it("color_scale: mid_value without mid_color is ignored (2-color scale)", () => {
+      const grid = makeCondGrid();
+      grid.conditionalFormatting = [
+        {
+          type: "color_scale",
+          apply_to: ["Revenue"],
+          min_color: "#ff0000",
+          max_color: "#0000ff",
+          mid_value: 0,
+        } as ColorScaleRule,
+      ];
+      const wb = buildExcelWorkbook(ExcelJS, grid);
+      const cfs = getCf(wb.worksheets[0]);
+      const rule = cfs[0].rules[0];
+      // No mid_color means a 2-stop scale regardless of mid_value.
+      expect(rule.cfvo).toEqual([{ type: "min" }, { type: "max" }]);
+    });
+
     // ---- Data bars ----
 
     it("data_bars: produces dataBar rule with gradient flag and correct color", () => {

streamlit_pivot/frontend/src/engine/exportExcel.ts

@@ -290,12 +290,23 @@ function applyConditionalFormatting(
 
       if (rule.type === "color_scale") {
         const csRule = rule as ColorScaleRule;
+        const hasMidValue =
+          csRule.mid_color !== undefined &&
+          typeof csRule.mid_value === "number" &&
+          Number.isFinite(csRule.mid_value);
+        // Midpoint CFVO: numeric anchor when mid_value is provided,
+        // otherwise fall back to the legacy 50th-percentile midpoint so
+        // existing mid_color-only rules keep producing the same workbook.
+        // ExcelJS's TS types don't enumerate { type: "num" } on color-scale
+        // CFVOs, so cast via unknown like the data-bar branch below.
+        const midCfvo = hasMidValue
+          ? ({ type: "num", value: csRule.mid_value } as unknown as {
+              type: "percentile";
+              value: number;
+            })
+          : { type: "percentile" as const, value: 50 };
         const cfvo = csRule.mid_color
-          ? [
-              { type: "min" as const },
-              { type: "percentile" as const, value: 50 },
-              { type: "max" as const },
-            ]
+          ? [{ type: "min" as const }, midCfvo, { type: "max" as const }]
           : [{ type: "min" as const }, { type: "max" as const }];
         const color = csRule.mid_color
           ? [

streamlit_pivot/frontend/src/engine/types.ts

@@ -413,6 +413,21 @@ export interface ColorScaleRule extends ConditionalFormatRule {
   min_color: string;
   max_color: string;
   mid_color?: string;
+  /**
+   * Explicit numeric midpoint for the diverging gradient. Requires `mid_color`.
+   *
+   * Interpreted in the same numeric space as the underlying aggregated cell
+   * values (the raw `agg.value()` shared by all conditional formatting rules),
+   * which is the same space as `min_color` / `max_color`. Conditional
+   * formatting runs before any `show_values_as` transformation, so
+   * `mid_value` is not aligned to a transformed display mode like
+   * `"pct_of_total"`.
+   *
+   * When provided, produces a smooth diverging gradient anchored at this
+   * value; the gradient clamps at the endpoint colors when a cell value falls
+   * outside the column's observed range.
+   */
+  mid_value?: number;
 }
 
 export interface DataBarsRule extends ConditionalFormatRule {
@@ -1066,6 +1081,22 @@ export function validatePivotConfigV1(obj: unknown): PivotConfigV1 {
           `'conditional_formatting[${i}].apply_to' must be an array of strings`,
         );
       }
+      if (ruleType === "color_scale") {
+        const midValue = (rule as Record<string, unknown>).mid_value;
+        if (midValue !== undefined && midValue !== null) {
+          if (typeof midValue !== "number" || !Number.isFinite(midValue)) {
+            throw new Error(
+              `'conditional_formatting[${i}].mid_value' must be a finite number`,
+            );
+          }
+          const midColor = (rule as Record<string, unknown>).mid_color;
+          if (typeof midColor !== "string" || midColor.length === 0) {
+            throw new Error(
+              `'conditional_formatting[${i}].mid_value' requires 'mid_color'`,
+            );
+          }
+        }
+      }
     }
     result.conditional_formatting =
       cfRules as unknown as AnyConditionalFormatRule[];