superset2/superset-frontend/plugins/plugin-chart-table/RCA.md

RCA: Table chart Total gets cut off on the Dashboard after a resize

Tracks apache/superset#21063.

What Happened

Reported repro (Table chart, SHOW TOTALS enabled, metric format set to "Original value" so the total renders as a long, unformatted number):

1. Create a Table chart with a category dimension and SUM(metric), totals on, D3 format "Original value".
2. Save it to a new dashboard.
3. In the dashboard editor, shrink the chart's height until the table body shows a vertical scrollbar, then grow it back until the scrollbar goes away and all rows are visible again.
4. Save the dashboard.

Expected: the Total row's number is fully visible. Actual: the rightmost part of the total's digits is invisibly clipped off, and stays clipped even though the body no longer needs to scroll.

The PR history on this exact file (#21064 in 2022, #26964 in 2024, #36891 and #42573 earlier in 2026) shows this general area — keeping the sticky header, scrollable body, and sticky footer column widths in sync when a vertical scrollbar appears/disappears — has regressed multiple times under different trigger conditions. This RCA is another iteration on that same mechanism, not a brand new subsystem.

Root Cause

This section has been revised twice after independent review challenged the evidence, each time by doing more real-browser testing rather than defending the previous write-up. This third round retracts a specific claim from round two ("clientWidth=190 vs scrollWidth=194 proves real clipping") after directly falsifying it with hit-testing, and replaces it with a narrower, structurally-guaranteed argument for why the shipped fix is correct.

Retracted, this round — the 190px/194px clientWidth/scrollWidth comparison from round two is not evidence of clipping, and real hit-testing shows the content in question stays fully visible.

Round two's central claim was that converging header/footer onto scrollbar-gutter: stable without also giving them scrollBarStyles produces a header/footer wrapper clientWidth of 190px against a 194px-wide <table>, and that this constitutes real clipping. An independent reviewer challenged this directly: a scrollbar gutter reservation sits inside the padding edge, and overflow: hidden clips at the padding edge, not necessarily at the (gutter-reduced) clientWidth. Reproducing the same 205px-wrapper/190px-clientWidth/194px-content geometry in real headed Chromium and testing it with document.elementFromPoint hit-testing across every pixel from the wrapper's left edge to well past its right edge — not just comparing two numbers — confirms the reviewer was right: the content remains hit-testable (i.e., actually painted, not clipped) all the way to its own true right edge, and only stops being hit-testable at the wrapper's real, un-reduced border-box edge (205px), never at the reduced 190px clientWidth scrollbar-gutter reports. In other words:

scrollbar-gutter: stable on an overflow: hidden box changes what clientWidth reports, but does not move where the box actually clips content. overflow: hidden clips at the box's real border-box edge, whether or not scrollbar-gutter has "reserved" (phantom, since overflow: hidden never renders a scrollbar to occupy that space) room inside it.

This was checked with a minimal, isolated repro (a plain <div> with the exact same width, overflow: hidden, scrollbar-gutter: stable, and ::-webkit-scrollbar styling as the header/footer wrapper, containing a child sized to reproduce the exact 190/194 numbers from round two) so the result isn't an artifact of react-table or this specific component. It is a general, verified fact about how Chromium implements overflow: hidden + scrollbar-gutter, not something specific to this file. This means: the round-two mechanism — a mismatched scrollbar-gutter reservation between header/footer and body/sizer — cannot, by itself, cause header/footer to visibly clip the total row. The scrollBarStyles half of the shipped fix is not load-bearing for preventing clipping (see below for what it's actually for).

Verified, this round — a genuinely narrower box, from a real width subtraction rather than a phantom scrollbar-gutter reservation, does clip.

This matters because it's exactly what unmodified master does: master's header/footer compute width: maxWidth - scrollBarSize, where scrollBarSize comes from the separately JS-measured getCustomScrollBarSize() probe — a real, literal reduction of the wrapper's own CSS width, not a CSS-engine-internal reservation. Testing this class directly (two overflow: hidden boxes, one at the full width, one built by subtracting a deliberately-too-large amount from that same width, both containing identically-sized content that fits the full-width box but not the subtracted one) and hit-testing across the boundary: the full-width box does not clip the content at all (hit-testable to its own true edge, same as above), while the subtracted box clips it exactly at its own — genuinely narrower — border-box edge, with the DOM node's content completely un-hit-testable beyond that point. Unlike the scrollbar-gutter case, this clipping is real: the box is actually narrower, not just reporting a smaller clientWidth while remaining the same size. This confirms the general mechanism class master relies on (a wrapper narrowed by maxWidth - <a JS-measured number>) is capable of real clipping if that JS-measured number is ever larger than what the colgroup was actually sized against — it's just not the specific scrollbar-gutter-mismatch mechanism claimed in round two.

Verified, this round — the shipped fix (header/footer always width: maxWidth, never reduced) cannot be narrower than the <colgroup> it has to display, in any browser, regardless of what any scrollbar probe measures. This is a structural argument, not a browser-specific empirical one:

1. The shared <colgroup> widths come from measuring <th> elements inside the sizer <div> (useSticky.tsx's useLayoutEffect, ths.map(th => th.getBoundingClientRect()?.width)).
2. The sizer has no explicit width of its own — it's a plain block <div> that takes the width of its containing block (the outermost wrapper, which is maxWidth wide), then loses more of that to whatever real vertical scrollbar it renders when its content needs to scroll (which is exactly when column widths are being measured for hasVerticalScroll: true). So sizer.clientWidth <= maxWidth, always, by construction — this isn't contingent on any JS probe agreeing with anything.
3. The sizer's own <table> is not given table-layout: fixed (only header/body/footer's cloned tables get that via mergeStyleProp(table, fixedTableLayout)), so it lays out with the browser's normal automatic table layout, sizing each column from the natural content of all of thead+tbody+tfoot together (the sizer renders all three sections at once, unlike header/body/footer which each render only one). That means the measured <th> widths already account for the total row's actual content width whenever that content fits inside sizer.clientWidth — which is the normal, in-scope case this fix targets (see "Latent Bugs Found" for the narrow-chart case where it doesn't fit at all, which is a separate, already-documented issue).
4. Therefore the widths that end up in <colgroup> sum to at most sizer.clientWidth, which is at most maxWidth.
5. Header/footer's own <table> (with the same <colgroup>, under table-layout: fixed, with no explicit table width) can only need up to that same colgroup-derived width to render without visually overflowing its own column boxes (browsers still let content wider than its <col> spec expand a table-layout: fixed table when the table's own width is auto, but the sizer already measured that expanded need, so the colgroup value already includes it — the fixed-layout tables don't need to grow further).

Chaining these: the widest header/footer's own <table> will ever legitimately need to be is bounded by sizer.clientWidth, which is bounded by maxWidth. Setting header/footer's wrapper width to the full, never-reduced maxWidth (what the fix does) therefore can never be narrower than what the table needs — not "in the one browser tested," but as a consequence of where each number comes from. This is the actual reason the fix prevents the reported clipping, and it does not depend on getCustomScrollBarSize()'s accuracy in any browser, unlike master's subtraction-based width.

Still unverified/inferred — the exact browser condition that triggers the bug against unmodified master. This is unchanged from round two and already accepted by review as a reasonable sandbox limit, so it is only summarized here: master's width: maxWidth - scrollBarSize is unsafe exactly when the JS-measured scrollBarSize is larger than whatever real reservation the sizer/body's own scrollbar actually took (see the previous paragraph's class-level demonstration for why that direction, specifically, causes real clipping). Sweeping chart widths (260px→190px) through the full shrink→grow-back sequence and six zoom levels (0.75×–1.5×) against unmodified master in real headed Chromium, getCustomScrollBarSize() and the sizer's real scrollbar reservation agreed at every single step in this sandbox — so the specific browser/OS/zoom condition that makes them disagree for the original reporter is not reproducible with the one Linux/Chromium build and X11 display available here. That the mechanism class itself is real (previous paragraph) is now on firmer ground than round two's specific (and now-retracted) numeric claim; that it's master's exact trigger remains an inference, not a reproduction.

A more likely contributor to the exact reported persistence ("stays clipped after growing back"), inferred but grounded in a separately verified defect: see the needScrollBar height-comparison bug under "Latent Bugs Found". It makes hasVerticalScroll switch on too easily and switch back off only once the chart is grown by an extra theadHeight + tfootHeight px beyond what's actually needed — i.e. it's easy for the scrollbar state, and the width reservation that comes with it, to stay "on" after a grow-back that should have turned it off. Left unfixed here — a distinct defect, and fixing it would change scrollbar-appearance behavior more broadly than this PR should.

Why scrollbarGutter/scrollBarStyles are still applied to header/footer, even though they aren't what prevents the reported clipping (secondary, less rigorously verified rationale): header/footer aren't purely decorative viewports — when hasHorizontalScroll is also true, their <table> is deliberately wider than the wrapper (the same over-wide <colgroup> as body), and scrollLeft is synced programmatically from body so header/footer scroll in lockstep as the user scrolls body horizontally (onScroll in useSticky.tsx). In that combined horizontal-and-vertical scroll case, body's visible content region is narrower than maxWidth by whatever its real, physically-rendered scrollbar occupies; if header/footer's clip viewport is the full, un-reduced maxWidth while body's real viewport is narrower, the same scrollLeft value would reveal a wider slice of the row in header/footer than what's actually visible in body, misaligning columns during horizontal scrolling. Matching scrollbarGutter/scrollBarStyles on header/footer keeps their reported clientWidth consistent with body's, which keeps that synced-scroll slice consistent too. I have not built a real-browser repro of this specific combined-scroll scenario (the reported bug, #21063, does not describe horizontal scrolling), so this is presented as a plausible, structurally motivated reason to keep the change, not a verified fix for a reproduced defect — unlike the width: maxWidth change above, which is verified.

Sizer/header/footer/body gutter symmetry is conditional, not unconditional. The sizer's wrapper sets scrollbarGutter: 'stable' unconditionally (useSticky.tsx, sizer <div> style), while header/footer/body all set it conditionally — hasVerticalScroll ? 'stable' : undefined. So the four elements only agree on gutter reservation while hasVerticalScroll is true; while it's false, the sizer still reserves a gutter (it's visibility: hidden and only used for measurement, so this doesn't affect anything visible) while header/footer/body correctly reserve none, since there's no real scrollbar to make room for. This is existing, pre-fix behavior, not something this PR introduces or removes — it's noted here so this document doesn't claim an unconditional four-way symmetry that isn't actually there.

How this was verified

jsdom (this repo's Jest environment) does not implement real CSS layout — getBoundingClientRect/clientWidth are stubbed, and hit-testing APIs like document.elementFromPoint don't reflect real paint/clip behavior — so none of the claims above can be checked through a jsdom test. This round's verification used real, on-screen Chromium rendering plus explicit hit-testing (not just numeric comparisons) for exactly that reason:

1. Started Xvfb :99 directly (no xauth available in this sandbox, so xvfb-run didn't work) and pointed DISPLAY=:99 at chromium.launch({ headless: false }) via Playwright (already cached in this sandbox) — genuine on-screen rendering.
2. Built minimal, static HTML repros (not part of this diff, not committed) reproducing the exact box models under dispute: (a) an overflow: hidden wrapper with scrollbar-gutter: stable and the same ::-webkit-scrollbar styling as this file's scrollBarStyles, containing content sized to reproduce round two's exact 190px/194px clientWidth/content-width numbers; (b) the same comparison with the unstyled (native, wider) scrollbar-gutter reservation, to match header/footer's specific pre-fix state; (c) two overflow: hidden wrappers differing only in whether their width is the full value or a value reduced by subtraction, both containing identical over-wide content, to isolate "phantom reservation" from "real narrowing."
3. For each, measured clientWidth/getBoundingClientRect() as before, but additionally swept document.elementFromPoint(x, y) across the disputed boundary pixel-by-pixel to determine what is actually hit-testable (i.e., actually painted and not clipped) at each point, rather than inferring clipping from a comparison of two numbers.
4. Result: the phantom-reservation repros (a) and (b) show content hit-testable all the way to its own true edge, never clipped at the reduced clientWidth; the real-narrowing repro (c) shows content genuinely clipped, exactly at the narrower box's own true edge. This directly falsifies round two's clipping claim while confirming the mechanism class master's subtraction-based width relies on is capable of real clipping when the subtracted amount is too large.
5. Re-verified the structural colgroup <= sizer.clientWidth <= maxWidth chain above by inspecting useSticky.tsx directly (this is a logical argument about where each number is computed and from what container, not something that needs a browser to check) rather than re-doing the full chart-width sweep from round two, since round two's sweep already established (and review already accepted) that master's own arithmetic doesn't diverge from the sizer/body's reservation anywhere reproducible in this sandbox — the open question was never "does the fixed code avoid divergence," it's "does removing the subtraction entirely avoid the class of bug regardless of divergence," which the structural argument answers independently of any sweep.

This traces both the retraction and the corrected argument through actual DOM state and hit-testing in a real, on-screen browser, and says plainly where it overturns round two's own conclusion rather than smoothing over it.

Why It Wasn't Caught

There is no test coverage of the sticky header/footer/body width-sync mechanism at all. Every existing test that renders TableChart or DataTable explicitly passes sticky={false} (plugins/plugin-chart-table/test/TableChart.test.tsx), and plugins/plugin-chart-table/test/DataTable/ only had a test for getScrollBarSize.ts in isolation — nothing exercises useSticky.tsx's StickyWrap component, so none of the four fixes to this exact mechanism since 2022 (#21064, #26964, #36891, #42573) added a regression guard for either of the two invariants this fix relies on: the load-bearing one (header/footer's wrapper width must never be reduced below what the shared colgroup needs — see Root Cause) or the secondary one (header/footer must report the same clientWidth as body, for consistent synced horizontal scrolling). Each fix addressed the specific manifestation someone happened to reproduce, without a test pinning either invariant itself.

Manual QA also wouldn't reliably catch a width-computation bug of this kind: it would depend on the reporter's specific browser/OS/rendering-mode scrollbar behavior, which is exactly the kind of environment-sensitive condition this investigation had to build custom real-browser tooling (headless and headed, plus hit-testing, not just numeric comparisons) to even observe directly.

The Fix

superset-frontend/plugins/plugin-chart-table/src/DataTable/hooks/useSticky.tsx, in StickyWrap (~lines 305-354), plus a /** @jsxImportSource @emotion/react */ pragma added near the top of the file (see "Prevention" for why):

1. Removed the headerContainerWidth = hasVerticalScroll ? maxWidth - scrollBarSize : maxWidth computation and the numeric width: headerContainerWidth on the header/footer wrapper divs. Replaced with an unconditional width: maxWidth. This is the change that actually prevents the reported clipping: the shared <colgroup> is always bounded by sizer.clientWidth, which is always bounded by maxWidth (see Root Cause), so a header/footer wrapper that is never narrowed below maxWidth can never be narrower than the table it has to display, regardless of whether getCustomScrollBarSize() agrees with the sizer/body's real scrollbar reservation in any given browser.
2. Also added scrollbarGutter: hasVerticalScroll ? 'stable' : undefined and css={scrollBarStyles} (the same custom ::-webkit-scrollbar styling the body/sizer already carry) to the header/footer wrapper divs. This step is not required to prevent the reported clipping — real hit-testing shows scrollbar-gutter on an overflow: hidden box changes what clientWidth reports without moving where content actually clips (see Root Cause) — but it is kept for a secondary, less rigorously verified reason: keeping header/footer's reported clientWidth consistent with body's keeps their synced scrollLeft viewport consistent with body's real, physically-scrollbar-reduced viewport when both horizontal and vertical scrolling are active simultaneously.

getCustomScrollBarSize() is untouched and still used for the separate, legitimate horizontal-scrollbar real-height reservation elsewhere in the same effect.

This removes the divergent, subtraction-based computation rather than compensating for it (e.g. no new "add a few px of buffer" fudge factor), because a buffer would itself be a browser/OS/zoom-dependent number with the exact same class of bug, and because the un-reduced width: maxWidth is already provably wide enough without needing to guess at a safety margin.

Alternatives Considered

• Keep getCustomScrollBarSize() for header/footer, but also apply it to the body/sizer instead of scrollbar-gutter. Rejected: this is the inverse of the chosen fix and has the same property of relying on a JS probe matching a real scrollbar's occupied space, rather than reusing one first-class CSS mechanism (scrollbar-gutter) everywhere. It would also touch the sizer's mounted-content measurement path, a larger and riskier change for a bug that doesn't require it.
• Add a numeric buffer/fudge factor to headerContainerWidth (e.g. round up, or add a few px of slack). Rejected per the task's own guidance: a fudge factor is itself a browser/OS/zoom-dependent number and doesn't remove the underlying defect, just narrows the range where it manifests.
• Fix the needScrollBar height-comparison bug instead/also (see Latent Bugs). Considered, because it's a plausible contributor to the "stays clipped after growing back" persistence. Rejected for this PR: it's a different defect (scrollbar visibility logic, not the header/footer wrapper width logic this fix targets), fixing it changes when scrollbars appear/disappear more broadly than this bug fix should, and the independent review already agreed it should stay out of scope.
• Drop scrollbarGutter/scrollBarStyles from header/footer, keeping only the unconditional width: maxWidth change. Considered once real hit-testing showed these aren't what prevents the reported clipping (see Root Cause). Kept anyway: while unverified against a reproduced defect, they're not free of purpose either — dropping them would let header/footer report a wider clientWidth than body during simultaneous horizontal and vertical scrolling, which is plausibly a real (if different) column misalignment risk during synced horizontal scroll. Removing them, on the evidence available here, would trade a proven-unnecessary line of CSS for a plausible new alignment gap, which isn't a clear improvement.

Latent Bugs Found

• needScrollBar height comparison in the same file's useLayoutEffect (useSticky.tsx ~lines 199-205): it compares innerHeight: fullTableHeight (thead + tbody + tfoot) against height: maxHeight - theadHeight - tfootHeight (the body-only budget). The correct comparison is fullTableHeight > maxHeight (equivalently, tbodyHeight > maxHeight - theadHeight - tfootHeight); the current form double-counts the header/footer height, so hasVerticalScroll reports true up to theadHeight + tfootHeight px earlier than actually necessary, and only reverts to false once the chart is grown well past the point a user would expect. Verified by direct computation and by a real-browser measurement showing a 400px container reporting hasVerticalScroll: true for content that only needed 379px. Plausibly a meaningful contributor to why "grow the chart back up" doesn't always self-heal a scrollbar-adjacent layout issue (see Root Cause). Left unfixed — a different defect than the header/footer wrapper-width bug this PR fixes, and changing it alters scrollbar-appearance behavior more broadly than this fix should.
• At chart widths where the Total's unbreakable natural content width (numbers have no break points, so table-layout: auto cannot wrap them) is only barely smaller than the chart's total width, the total clips identically on master and on the fixed code, at every resize step, including before any scrollbar ever appears. Verified via the same real-browser sweep (both headless and headed Chromium). This is a different, more fundamental "the chart is too narrow for this content regardless of scrollbars" case, not the header/footer wrapper-width bug this PR targets — not fixed here.
• The <col width={w} /> values passed to <colgroup> are floats (e.g. 95.65625). The legacy HTML width attribute on <col> may be rounded down/truncated by some rendering engines, which could compound with either of the above. Not confirmed to matter on evergreen Chromium in this investigation; noted for anyone touching this file again.

Prevention

Added plugins/plugin-chart-table/test/DataTable/hooks/useSticky.test.tsx, which mounts useSticky's StickyWrap for real (via react-table) with mocked DOM measurements that force hasVerticalScroll: true, and mocks getCustomScrollBarSize() to return a value distinguishable from any CSS-computed one. It asserts, pinning the two invariants separately rather than treating them as one:

1. Load-bearing. The header/footer wrapper's style.width matches the body's (maxWidth, not any pixel value) — pinning "header/footer's width is never reduced below what the shared colgroup needs." Fails against the pre-fix code (258px vs. expected 300px, since 300 - 42 (mocked probe) = 258, a header/footer wrapper genuinely narrower than the colgroup it has to display) and passes after the fix.
2. Secondary. The header/footer wrapper's style.scrollbarGutter and className (populated via the css={scrollBarStyles} prop) both match the body's — pinning "header/footer report the same clientWidth as body," which matters for keeping their synced horizontal scrollLeft consistent with body's real, scrollbar-reduced viewport (see Root Cause), not for preventing the reported clipping by itself.

The className assertion needed one more thing to be observable at all: useSticky.tsx now carries a /** @jsxImportSource @emotion/react */ pragma (added just below the license header). Without it, this repo's Jest/Babel setup passes the css prop straight through to the DOM as an inert string attribute (css="[object Object]", confirmed empirically — headerDiv.getAttribute('css') returned exactly that before the pragma was added) instead of resolving it through Emotion's JSX runtime into a real class, because — unlike the webpack/SWC production build, which sets importSource: '@emotion/react' globally for every file (webpack.config.js, createSwcLoader) — this repo's babel.config.js does not set the equivalent importSource for @babel/preset-react in its Jest (test) env, and no file in this codebase currently carries the per-file pragma that would substitute for it. Adding the pragma to this one file makes Babel treat it exactly the way SWC already treats every file in the real build (both resolve to the same @emotion/react JSX runtime): the per-file pragma specifies the identical import source SWC already applies globally, so it changes nothing about the shipped, webpack-built behavior — it only changes what Jest's separate Babel pipeline can observe. This test fails on the commit before css={scrollBarStyles} was added to header/footer (header/footer className is '' while body's is populated) and passes on the fix (verified by temporarily reverting just the two css={scrollBarStyles} additions and re-running the test, then restoring them).