feat(table): add multi-level column header groups

[SBIN2010]

SUMMARY

Adds the ability to configure multi-level column headers for tables (standard and AG Grid).
In the table chart settings, users can create nested groups, select columns, and specify the group name, header alignment, and group placement (left or right). Group order can be rearranged using drag-and-drop.
When the time comparison feature is enabled, a group (Main, #, △, %) is automatically created for each metric. Columns cannot be added to or removed from these automatic groups; the groups disappear when time comparison is disabled.
A group cannot be saved without a name and at least one column. This rule also applies to subgroups.

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

automatic group creation when time comparison is enabled:

TESTING INSTRUCTIONS

Works on both Table and AG Grid Interactive Table. Repeat the flows for each viz type.
Manual groups

1. Open Explore on a dataset with several metrics/columns. Choose Table or AG Grid.
2. Add at least two metrics (and optionally a percent metric). Run the query.
3. Open Customize → Multi-level header → Column groups.
4. Click Add group. Confirm Apply stays disabled until the group has a name and at least one column.
5. Name the group (e.g. Sales), select two columns, set Label position and Table side, then Apply.
6. Confirm the table header shows the parent label over the chosen columns.
7. Click Group 1, clear the name: the field should show Name is required and not silently revert.
8. Restore the name, click Add subgroup, give the subgroup a name and a remaining column, then confirm the nested header.
9. Add a second top-level group and drag-reorder the group chips. Confirm header order follows the list.
10. Confirm a column already used in one group is not offered in another. A percent metric (%…) can still be grouped on its own.

Time comparison auto-groups

1. Keep Query mode = Aggregate. In Advanced Analytics → Time Comparison, add a shift (e.g. 1 year ago) and set Calculation type to Values. Run the query.
2. Confirm Column groups now has one locked group per metric (Main, #, △, %), labeled from the metric/dataset verbose name.
3. Open an auto-group: columns cannot be added or removed; Add subgroup is not available.
4. Confirm you can still add a separate manual group for a percent metric or an unused column.
5. Clear Time Comparison (or switch Calculation type away from Values) and confirm the auto-groups disappear while manual groups remain.
6. Save the chart, close Explore, reopen it. Confirm header groups still render and the chart is not marked as having unsaved changes.
7. Add the chart to a dashboard and confirm the grouped headers render there as well.

ADDITIONAL INFORMATION

• Has associated issue:
• Required feature flags:
• Changes UI
• Includes DB Migration (follow approval process in SIP-59)
  • Migration is atomic, supports rollback & is backwards-compatible
  • Confirm DB migration upgrade and downgrade tested
  • Runtime estimates and downtime expectations provided
• Introduces new feature or API
• Removes existing feature or API

[EnxDev]

@SBIN2010 I did some manual testing, and overall it seems to be working really well!

I found one case where, after setting a minimum width and then switching back to auto, the column doesn't resize anymore.
Also, I'd prefer to have the text alignment buttons arranged horizontally instead of the current layout. What do you think?

See the attached image for a better idea of what I mean.

[SBIN2010]

@SBIN2010 I did some manual testing, and overall it seems to be working really well!

I found one case where, after setting a minimum width and then switching back to auto, the column doesn't resize anymore. Also, I'd prefer to have the text alignment buttons arranged horizontally instead of the current layout. What do you think?

Hi @EnxDev!
I completely agree with you regarding the interface. However, in this PR, I didn't touch the column settings interface.
And I wasn't able to reproduce the scenario you described.

[EnxDev]

@SBIN2010 I've fixed both things I mentioned before. Feel free to test them, and if everything looks good to you, we can merge it!

[bito-code-review]

Code Review Agent Run #b6779b

Actionable Suggestions - 0

Additional Suggestions - 11

• superset-frontend/plugins/plugin-chart-ag-grid-table/src/AgGridTable/index.tsx - 1

  • Unmemoized per-render signature · Line 587-587
    `getMinWidthSignature(colDefsFromProps)` runs on every render of this grid component (data refresh, filter/cross-filter changes, re-renders), doing an O(n) string build each time even when colDefs are unchanged. Memoize it with `useMemo(() => getMinWidthSignature(colDefsFromProps), [colDefsFromProps])` so the effect dependency is only recomputed when the column defs actually change.
• superset-frontend/src/explore/components/controls/ColumnConfigControl/constants.tsx - 2

  • Width regression 130 to 168px · Line 108-108
    Replacing `width: 130` with `supersetTheme.sizeUnit * 42` renders 168px (default `sizeUnit` is 4, per `Theme.test.tsx.snap`), a +38px (+29%) layout change to the `horizontalAlign` radio control consumed by `ControlFormItem`'s container `css`. A token migration usually preserves the rendered size; please confirm the wider control is intended or use a multiplier matching 130px.
  • Static theme snapshot staleness · Line 22-22
    `supersetTheme` is captured once at module load (`theme/index.tsx`: `const supersetTheme = theme`), while `Theme.setConfig()` reassigns `themeObject.theme` (Theme.tsx:149). This width therefore ignores runtime theme updates and a custom `sizeUnit` token, unlike the `({ theme }) => theme.sizeUnit` idiom used ~1000x elsewhere. Likely harmless for `sizeUnit`, but worth a note as the first non-test use of this import.
• superset/translations/ko/LC_MESSAGES/messages.po - 1

  • Untranslated new string · Line 2361-2363
    New user-facing error string added to the ko catalog with an empty `msgstr`, so Korean users fall back to English on this alert-validation error path (source: `superset/commands/report/alert.py:200`). The sibling new entry "Table side" (line 22723) was translated, so this one looks overlooked. Add the translation, keeping the `%(commands)s` placeholder.
• superset/translations/sk/LC_MESSAGES/messages.po - 1

  • Untranslated new string · Line 1768-1770
    New msgid `Alert query must not contain the file-transfer command(s): %(commands)s` (added for `alert.py` `_validate_query`/`AlertQueryError`) has an empty `msgstr`, so Slovak UI falls back to English for this alert-validation error. Add the Slovak translation to complete the catalog entry.
• superset/translations/ja/LC_MESSAGES/messages.po - 1

  • Untranslated new message · Line 1603-1605
    New user-facing alert error message `Alert query must not contain the file-transfer command(s): %(commands)s` (raised in `superset/commands/report/alert.py:200`) is added with an empty `msgstr`, so Japanese users will see the English fallback when an alert query contains a file-transfer command. Consider adding the Japanese translation in this PR.
• superset/translations/pt/LC_MESSAGES/messages.po - 1

  • Untranslated new msgid · Line 2184-2186
    The new msgid `Alert query must not contain the file-transfer command(s): %(commands)s` (used in `superset/commands/report/alert.py` `_validate_query`) is added with an empty `msgstr`, so Portuguese users will see the English fallback for this alert error. Consider adding the translation.
• superset/translations/ru/LC_MESSAGES/messages.po - 1

  • Untranslated new string · Line 1726-1728
    The new msgid `Alert query must not contain the file-transfer command(s): %(commands)s` (used in `superset/commands/report/alert.py:200`) is added with an empty `msgstr`, so Russian users will see the English fallback when an alert query contains a file-transfer command. Add the Russian translation.
• superset-frontend/plugins/plugin-chart-table/test/DataTable/DataTable.test.tsx - 1

  • Missing return type hint · Line 130-130
    `getHeaderOrder` (line 130) omits an explicit return type even though its shape (`(string | null)[]` from `getAttribute`) is not obvious at the call sites. The repo's learned rules require explicit return type hints on all functions, including helpers in test files, so annotate it.
• superset-frontend/src/explore/components/controls/ColumnConfigControl/ColumnConfigControl.tsx - 1

  • O(n·m) filter, dropped guard · Line 112-116
    `setColumnConfig` now calls `colnames.includes(key)` per key (O(n·m) on every edit), and the removed ternary also guarded a falsy `colnames`, which sibling code still treats as possibly absent (`colnames?.forEach`, `!colnames`). Build a `Set` once — `normalizeColumnConfigKeys` already does exactly this internally — keeping semantics identical for the falsy case.
• superset/translations/ca/LC_MESSAGES/messages.po - 1

  • Missing Catalan translation · Line 1786-1787
    New msgid "Alert query must not contain the file-transfer command(s): %(commands)s" (used in `superset/commands/report/alert.py:200` via `_()`) has an empty `msgstr`, so Catalan users see the English fallback for this alert error. Add the Catalan translation.

Review Details

• Files reviewed - 45 · Commit Range: d458289..50c1bdf

  • superset/translations/ar/LC_MESSAGES/messages.po
  • superset/translations/ca/LC_MESSAGES/messages.po
  • superset/translations/cs/LC_MESSAGES/messages.po
  • superset/translations/de/LC_MESSAGES/messages.po
  • superset/translations/en/LC_MESSAGES/messages.po
  • superset/translations/es/LC_MESSAGES/messages.po
  • superset/translations/fa/LC_MESSAGES/messages.po
  • superset/translations/fi/LC_MESSAGES/messages.po
  • superset/translations/fr/LC_MESSAGES/messages.po
  • superset/translations/it/LC_MESSAGES/messages.po
  • superset/translations/ja/LC_MESSAGES/messages.po
  • superset/translations/ko/LC_MESSAGES/messages.po
  • superset/translations/lv/LC_MESSAGES/messages.po
  • superset/translations/messages.pot
  • superset/translations/mi/LC_MESSAGES/messages.po
  • superset/translations/nl/LC_MESSAGES/messages.po
  • superset/translations/pl/LC_MESSAGES/messages.po
  • superset/translations/pt/LC_MESSAGES/messages.po
  • superset/translations/pt_BR/LC_MESSAGES/messages.po
  • superset/translations/ro/LC_MESSAGES/messages.po
  • superset/translations/ru/LC_MESSAGES/messages.po
  • superset/translations/sk/LC_MESSAGES/messages.po
  • superset/translations/sl/LC_MESSAGES/messages.po
  • superset/translations/sr/LC_MESSAGES/messages.po
  • superset/translations/sr_Latn/LC_MESSAGES/messages.po
  • superset/translations/ta/LC_MESSAGES/messages.po
  • superset/translations/th/LC_MESSAGES/messages.po
  • superset/translations/tr/LC_MESSAGES/messages.po
  • superset/translations/uk/LC_MESSAGES/messages.po
  • superset/translations/zh/LC_MESSAGES/messages.po
  • superset/translations/zh_TW/LC_MESSAGES/messages.po
  • superset-frontend/packages/superset-ui-chart-controls/src/utils/headerGroups.test.ts
  • superset-frontend/packages/superset-ui-chart-controls/src/utils/headerGroups.ts
  • superset-frontend/src/explore/components/controls/ColumnConfigControl/ColumnConfigControl.tsx
  • superset-frontend/plugins/plugin-chart-table/src/DataTable/DataTable.tsx
  • superset-frontend/plugins/plugin-chart-table/src/TableChart.tsx
  • superset-frontend/plugins/plugin-chart-table/test/DataTable/DataTable.test.tsx
  • superset-frontend/src/explore/components/controls/HeaderGroupsControl/HeaderGroupEditor.tsx
  • superset-frontend/src/explore/components/controls/HeaderGroupsControl/HeaderGroupsControl.test.tsx
  • superset-frontend/src/explore/components/Control.test.tsx
  • superset-frontend/src/explore/components/controls/ColumnConfigControl/ColumnConfigControl.test.tsx
  • superset-frontend/src/explore/components/controls/ColumnConfigControl/constants.tsx
  • superset-frontend/plugins/plugin-chart-ag-grid-table/src/AgGridTable/index.tsx
  • superset-frontend/plugins/plugin-chart-ag-grid-table/src/utils/getMinWidthSignature.ts
  • superset-frontend/plugins/plugin-chart-ag-grid-table/test/utils/getMinWidthSignature.test.ts
• Files skipped - 0
• Tools

  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful
  • Eslint (Linter) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers an incremental AI Review.

• /review full - Manually triggers a full AI Review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Superset You can customize the agent settings here or contact your Bito workspace admin at evan@preset.io.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by

[SBIN2010]

@SBIN2010 I've fixed both things I mentioned before. Feel free to test them, and if everything looks good to you, we can merge it!

I realized why I didn't reproduce this issue: I was looking at a different table.

Yes, it really does look better that way. Thank you for your review and assistance.
We just need to wait for PR 44860 to be merged; after that, we’ll rebase onto master and can proceed with the merge.

[EnxDev]

LGTM! Another really useful contribution from you, @SBIN2010, thanks a lot!

(We’re just waiting for #44860 to be merged before merging this one)