superset2/SIP.md

SIP: Granular (Component-Level) Theming for Dashboard Components

Status: Draft — living doc, kept in lockstep with the work on feat/granular-theming-v2. Champion: @rusackas Supersedes: Closed PR #36749 (became unrebasable after the .jsx → .tsx conversion, React 18 upgrade, and theme-controller churn since 2025-12).

Motivation

Superset already supports themes at two levels:

• Instance — the global default theme configured by the deployment.
• Dashboard — a per-dashboard override (managed via ThemeController.dashboardCrudTheme + createDashboardThemeProvider).

Users have repeatedly asked to override theme tokens at a finer granularity — for example to make a single chart match a brand color in a sales dashboard, to highlight a tab with a different palette, or to give a Markdown callout a distinct background. Today the only options are to (a) override the entire dashboard or (b) inject custom CSS.

This SIP proposes a third level: per-component theme overrides on dashboard grid components (Charts, Markdown, Row, Column, Tabs), with an inheritance chain:

Instance Theme         (deployment default)
  └── Dashboard Theme  (existing per-dashboard override)
        └── Tab Theme           ┐
              └── Row/Col Theme │  (new, per-component)
                    └── Chart/Markdown Theme

Each level can override any subset of theme tokens; unspecified tokens are inherited from the parent.

Non-goals

• Custom CSS replacement. This isn't trying to subsume CSS injection — only theme-token-level overrides (colors, font sizes, spacing, etc.).
• New theme authoring UI. Users pick from existing themes (the CRUD theme resource); creating themes still happens in the existing Themes section.
• Backend schema changes. All persistence lives on existing fields (position_json per-component meta, see Storage below).
• Cross-dashboard reuse of component theme assignments. A theme can be reused, but an assignment of a theme to a specific component lives with that component.

Storage

Dashboard layout items are stored in position_json and surfaced in Redux as LayoutItems with a meta: LayoutItemMeta field already typed as open-ended:

export type LayoutItemMeta = {
  // ...known fields...
  [key: string]: unknown;
};

We add an optional themeId?: number | null to LayoutItemMeta. No new tables, no migrations, no dashboard json_metadata changes.

A themeId === null means "explicitly no override — inherit from parent." A missing key means the same thing semantically; we treat them identically when reading.

Round-trip:

• Read: LayoutItem.meta.themeId is parsed straight from position_json like any other meta property.
• Write: dashboard save serializes the entire position_json already; storing themeId is free.
• Backwards compatibility: pre-feature dashboards have no themeId keys, so they fall through to the dashboard/instance theme as today.

Architecture

ComponentThemeProvider

A wrapper component placed inside each grid component, between the dashboard's existing ThemeProvider and the component's body:

<ComponentThemeProvider layoutId={id}>
  {/* component body */}
</ComponentThemeProvider>

Responsibilities:

1. Read themeId from the layout item via Redux selector.
2. Walk up the layout tree (parents) to compute the effective theme — first non-null themeId wins; fall back to the dashboard/instance theme.
3. Call ThemeController.createDashboardThemeProvider(themeId) (same code path used for dashboard CRUD themes — themes are themes, regardless of which scope picked them).
4. Wrap children in AntdThemeProvider with the resolved theme.

Caching: ThemeController already memoizes themes by id (dashboardThemes: Map<string, Theme>). We reuse that — same theme assigned to 100 charts costs one fetch.

ComponentHeaderControls (Phase 2, lands first)

A shared vertical-dots menu for grid components. Each grid component type plugs in its own list of menu items via a useComponentMenuItems hook; the visual chrome (the dots icon button, the dropdown surface, the edit-mode visibility gating) lives in ComponentHeaderControls itself.

Per-component menu surfaces (informational — the actual conversions of the existing patterns happen as part of Phase 4 for each component, so we don't change user-visible UX in Phase 2):

Component	Current pattern	Converges to
Markdown	MarkdownModeDropdown (Edit/Preview popover)	dots menu w/ Edit + Preview items
Row / Col	Gear icon → WithPopoverMenu with BackgroundStyleDropdown	dots menu w/ Background item
Chart	SliceHeaderControls (already a dots menu — wraps MenuDotsDropdown)	reuses the same shared component
Tabs	none	dots menu (new affordance)

Phase 2 itself only builds the component and converts Markdown as the PoC. The other components remain on their existing patterns until the per-component Phase-4 PRs wire them up together with their theme provider — that lets reviewers evaluate the menu unification + theming together rather than as separate churn passes.

ThemeSelectorModal (Phase 3)

Modal triggered from "Apply theme" in ComponentHeaderControls. Shows:

• A theme picker populated from the CRUD /api/v1/theme/ endpoint (same source the dashboard-level picker uses).
• A "Clear override (inherit)" button when themeId is already set.
• Live preview: as the user picks options the targeted component re-renders with the candidate theme tokens immediately, without marking the dashboard dirty. Cancel reverts; Apply commits to Redux. Implemented via a tiny module-level subscribable previewThemeStore
  • useSyncExternalStore in useEffectiveThemeId (preview wins over the Redux-resolved id when present).

On save it dispatches a Redux action that updates the component's meta.themeId and marks the dashboard dirty.

Phases

Phase	Scope	PR target
1	Storage shape (LayoutItemMeta.themeId) + ComponentThemeProvider skeleton wired to one component (Chart) for proof of concept. No UI.	One PR
2	Build ComponentHeaderControls (shared dots menu) + tests. Component creation only — per-component conversions of the existing menu patterns happen in Phase 4 alongside theme wiring, so reviewers can evaluate the menu unification + theming together rather than as separate churn passes.	One PR
3	ThemeSelectorModal + persistence + "Apply theme" menu item. End-to-end demo on Chart.	One PR
4	Per-component PRs (Markdown / Row / Column / Tabs): swap their existing menu pattern for ComponentHeaderControls, wire ComponentThemeProvider around the body, add the "Apply theme" item. One PR per component so each menu/UX change can be reviewed in isolation.	~4 small PRs

Each phase is independently revertable. Phase 2 has standalone value.

Open questions / shortcomings

These get refined as the work progresses; do not merge any phase without revisiting this section.

• Theme resolution caching at the component level. ThemeController caches themes by id, but ComponentThemeProvider walks the parents tree every render to find the effective themeId. Need to confirm the walk is cheap enough at typical dashboard sizes (~50 components), or memoize via Redux reselect.
• Export / screenshot behavior. The screenshot service (Playwright / WebDriver) reads the same DOM, so theme overrides should "just work" — but we need a screenshot regression test.
• Embedded SDK. Embedded dashboards default to light mode (#38644). Need to confirm component-level themes still apply in embedded context, since embedded skips ThemeController.setCrudTheme.
• Theme deletion — what happens if a themeId references a theme that's been deleted from the CRUD store? Likely fall back silently to parent; need a useEffect cleanup path.
• Permission model. Should theme_write be required to assign a theme to a component? Currently any dashboard editor can do it. Probably fine, but worth confirming with @michael-s-molina.
• i18n / a11y of the modal. Standard checklist — needs labels, focus management, keyboard.
• Mobile — ComponentHeaderControls hover-to-reveal pattern needs a tap-equivalent.

Test plan

Each phase brings its own tests; the cumulative bar:

Unit

• ComponentThemeProvider: resolves theme from own themeId; resolves from parent when own is null; falls back to dashboard/instance when no ancestor sets one; reacts to Redux meta changes.
• useComponentThemeId (selector / hook the provider uses): correctness on the parents-walk.
• ComponentHeaderControls: shows correct menu items per component type; routes onClick for each.
• ThemeSelectorModal: opens populated with available themes; "save" dispatches the right action; "clear override" sets themeId: null.

Integration (RTL)

• Dashboard with one chart → assign a theme → chart re-renders with new tokens.
• Same dashboard → assign theme to the Row containing the chart → chart inherits Row theme (no own override).
• Set chart override + row override → chart wins (most-specific).
• Clear chart override → chart inherits row.
• Reload dashboard (re-render from position_json) → state preserved.

E2E (Playwright)

• One scenario per component type: open dashboard → menu → apply theme → save → reload → verify.
• Permission scenario: editor can apply, viewer cannot see the menu.

Manual / screenshot

• Light theme dashboard with one dark-themed chart and one default-themed chart — visual diff in CI.
• Embedded dashboard with a component theme — verify no host-CSS bleed.

Out-of-scope (potential follow-ups)

• Theme presets — "apply this theme to all charts of viz type X" via a dashboard-level rule.
• Theme inheritance debugger — devtools view that shows which level set each token for a hovered component.
• Bulk operations — multi-select components and apply a theme to all.

Implementation log

• (Phase 1) — ✅ landed locally. LayoutItemMeta.themeId, ComponentThemeProvider + useEffectiveThemeId hook, wired into ChartHolder. 8 passing unit tests. No UI yet — themeId has to be set via Redux devtools or position_json hand-edit to verify visually.

• (Phase 2) — ✅ landed locally. ComponentHeaderControls shared dots menu + 4 passing unit tests. Generic items: ComponentMenuItem[] API so each grid component can plug in its own list (Edit/Preview for Markdown, Background for Row/Col, Apply Theme/Delete for Chart, etc.). Built on the existing MenuDotsDropdown so the trigger styling matches Chart's SliceHeaderControls today (Phase 4 will converge SliceHeaderControls onto this).

  Deferred to Phase 4: actually swapping the existing per-component menu UI (Markdown's MarkdownModeDropdown PopoverDropdown, Row/Col's gear-icon-into-WithPopoverMenu, Tabs' nothing) for this component. Those conversions are user-visible UX changes (e.g. Markdown loses its toggle-style Edit/Preview switcher and gains a dots menu), so we do them per-component alongside the theme wiring so each can be reviewed in isolation.

• (Phase 3) — ✅ landed locally. ThemeSelectorModal (fetches non-system themes via the same /api/v1/theme/?q=... query that the dashboard Properties modal uses; preselects the currently-resolved override; "Apply" / "Cancel" / "Clear override (inherit)" buttons) and the thin setComponentThemeId(componentId, themeId | null) action that merges into meta.themeId via the existing updateComponents thunk.

  No call site for the modal yet — Phase 4's per-component PRs add the "Apply theme" item to each component's menu that opens this modal. The modal is parent-controlled (show/onHide), parent-owned, so there's no wiring needed beyond <ThemeSelectorModal layoutId={id} show={open} onHide={...} /> in each call site.

  3 passing tests on setComponentThemeId: preserves other meta keys

  • sets numeric themeId; stores explicit null for the clear path; no-op when the component id isn't in the layout.

• (Phase 4) — ✅ landed locally for all five grid-component types. Same three-step recipe applied to each: (a) wrap body in <ComponentThemeProvider layoutId={id}>, (b) add "Apply theme" item to the component's menu via ComponentHeaderControls, (c) mount <ThemeSelectorModal> gated on editMode.

  • Chart (4a): SliceHeaderControls gets the menu item; the provider was already wrapping ChartHolder from Phase 1.
  • Tabs (4b): TabsRenderer wraps <StyledTabsContainer> in the provider; adds the dots-menu trigger inside the existing left HoverMenu next to the drag handle and delete button.
  • Row (4c): wraps the <WithPopoverMenu> body; adds the dots-menu trigger to the left HoverMenu next to drag/delete/ setting-icon. The existing gear icon (which opens the BackgroundStyleDropdown focus popover) is preserved as-is.
  • Column (4d): same recipe as Row, wrapping its <WithPopoverMenu> body and adding the dots menu to the top HoverMenu next to drag/delete/setting-icon.
  • Markdown (4e): class component, so theme-modal state goes through this.state.themeModalOpen. Adds a second ComponentHeaderControls to the existing <WithPopoverMenu menuItems> array next to the MarkdownModeDropdown (Edit/Preview toggle is preserved as-is — the full menu-pattern convergence onto a single dots menu is intentionally deferred so Markdown's Edit/Preview UX is not changed in this phase).

  Functional outcome: every grid-component type now supports the full Instance → Dashboard → Tab → Row/Col → Chart/Markdown inheritance chain end-to-end. Setting a themeId at any level applies to that subtree; clearing it falls through to the parent.

  Note on the broader menu-pattern unification: the SIP originally imagined Phase 4 PRs would also converge MarkdownModeDropdown (Edit/Preview popover) and the Row/Column gear icon into the shared dots menu. We deferred those user-visible UX displacements so each Phase-4 PR adds the theming affordance additively — i.e. the existing menu controls are untouched, the dots menu sits alongside. A follow-up SIP (or single sweep PR) can take the menu unification later without coupling it to the theming work.

Phase 1 status

• Add optional themeId field to LayoutItemMeta. (src/dashboard/types.ts)
• Build ComponentThemeProvider — pickEffectiveThemeId resolver (pure function, walks parents up the layout map until it finds a non-null themeId or hits DASHBOARD_ROOT_ID) + useEffectiveThemeId Redux hook
  • ComponentThemeProvider that lazy-fetches the resolved theme via the existing ThemeController.createDashboardThemeProvider (which caches by id, so N components referencing the same theme = 1 fetch). Renders as a pass-through when no ancestor sets a themeId.
• Wire into ChartHolder — wrapped around the existing <AntdThemeProvider> so per-component theme tokens apply to the chart body while the existing popup-container ConfigProvider continues to work in fullscreen mode.
• Add unit tests — 8 cases for pickEffectiveThemeId covering own-id / inheritance / null-skip / no-ancestor / root-stop / malformed-parents / other-meta-keys / missing-id.
• Update SIP with surprises uncovered during wiring (none significant — the existing createDashboardThemeProvider did exactly what we needed, including caching by id; the only structural decision was treating the ChartHolder's <AntdThemeProvider> as a popup-container shim rather than a token provider, and nesting our provider outside it).

Phase 1 surprises / notes

• ThemeController.createDashboardThemeProvider already does Theme.fromConfig with the right dark/light base + font loading + caching. We did not need to duplicate any of that logic in the component-level provider.
• The provider is useState + useEffect rather than useMemo because the fetch is async. That means there's a one-frame flash of the parent theme before the component theme kicks in. Probably acceptable; if not, we can Suspense-ify in Phase 4.
• useEffectiveThemeId re-runs on every Redux state change because the selector returns a primitive number | null — that's fine for now, but if dashboards get bigger we may want a memoized selector via reselect keyed on (layoutId, layout) — file in the open questions section.