fix(embedded): default to light theme instead of system preference (#38644)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: sadpandajoe

superset-frontend/packages/superset-core/src/theme/types.ts

@@ -426,6 +426,7 @@ export interface ThemeControllerOptions {
   canUpdateTheme?: () => boolean;
   canUpdateMode?: () => boolean;
   isGlobalContext?: boolean;
+  initialMode?: ThemeMode;
 }
 
 export interface ThemeContextType {

superset-frontend/src/embedded/EmbeddedContextProviders.tsx

@@ -26,7 +26,7 @@ import { DynamicPluginProvider } from 'src/components';
 import { EmbeddedUiConfigProvider } from 'src/components/UiConfigContext';
 import { SupersetThemeProvider } from 'src/theme/ThemeProvider';
 import { ThemeController } from 'src/theme/ThemeController';
-import { type ThemeStorage } from '@apache-superset/core/theme';
+import { type ThemeStorage, ThemeMode } from '@apache-superset/core/theme';
 import { store } from 'src/views/store';
 import querystring from 'query-string';
 
@@ -52,6 +52,7 @@ class ThemeMemoryStorageAdapter implements ThemeStorage {
 
 const themeController = new ThemeController({
   storage: new ThemeMemoryStorageAdapter(),
+  initialMode: ThemeMode.DEFAULT,
 });
 
 export const getThemeController = (): ThemeController => themeController;

superset-frontend/src/theme/ThemeController.ts

@@ -102,15 +102,19 @@ export class ThemeController {
   // Track loaded font URLs to avoid duplicate injections
   private loadedFontUrls: Set<string> = new Set();
 
+  private initialMode: ThemeMode | undefined;
+
   constructor({
     storage = new LocalStorageAdapter(),
     modeStorageKey = STORAGE_KEYS.THEME_MODE,
     themeObject = supersetThemeObject,
     defaultTheme = (supersetThemeObject.theme as AnyThemeConfig) ?? {},
     onChange = undefined,
+    initialMode = undefined,
   }: ThemeControllerOptions = {}) {
     this.storage = storage;
     this.modeStorageKey = modeStorageKey;
+    this.initialMode = initialMode;
 
     // Controller creates and owns the global theme
     this.globalTheme = themeObject;
@@ -743,6 +747,13 @@ export class ThemeController {
       return ThemeMode.DEFAULT;
     }
 
+    // Use explicit initial mode if provided (e.g. embedded dashboards default to light)
+    if (
+      this.initialMode !== undefined &&
+      this.isValidThemeMode(this.initialMode)
+    )
+      return this.initialMode;
+
     // Default to system preference when both themes are available
     return ThemeMode.SYSTEM;
   }

superset-frontend/src/theme/tests/ThemeController.test.ts

@@ -1686,3 +1686,115 @@ test('font loading: adds new font URLs when switching themes', () => {
     .querySelectorAll('style[data-superset-fonts]')
     .forEach(el => el.remove());
 });
+
+test('ThemeController uses initialMode when provided and no saved mode exists', () => {
+  mockGetBootstrapData.mockReturnValue(
+    createMockBootstrapData({
+      default: DEFAULT_THEME,
+      dark: DARK_THEME,
+    }),
+  );
+
+  const controller = createController({ initialMode: ThemeMode.DEFAULT });
+
+  expect(controller.getCurrentMode()).toBe(ThemeMode.DEFAULT);
+});
+
+test('ThemeController defaults to SYSTEM when initialMode is not provided', () => {
+  mockGetBootstrapData.mockReturnValue(
+    createMockBootstrapData({
+      default: DEFAULT_THEME,
+      dark: DARK_THEME,
+    }),
+  );
+
+  const controller = createController();
+
+  expect(controller.getCurrentMode()).toBe(ThemeMode.SYSTEM);
+});
+
+test('ThemeController saved mode takes precedence over initialMode', () => {
+  mockGetBootstrapData.mockReturnValue(
+    createMockBootstrapData({
+      default: DEFAULT_THEME,
+      dark: DARK_THEME,
+    }),
+  );
+
+  mockLocalStorage.getItem.mockReturnValue(ThemeMode.DARK);
+
+  const controller = createController({ initialMode: ThemeMode.DEFAULT });
+
+  expect(controller.getCurrentMode()).toBe(ThemeMode.DARK);
+});
+
+test('ThemeController with initialMode DEFAULT applies light theme even when system prefers dark', () => {
+  mockGetBootstrapData.mockReturnValue(
+    createMockBootstrapData({
+      default: DEFAULT_THEME,
+      dark: DARK_THEME,
+    }),
+  );
+
+  mockMatchMedia.mockReturnValue({
+    matches: true, // system prefers dark
+    addEventListener: jest.fn(),
+    removeEventListener: jest.fn(),
+  });
+
+  const controller = createController({ initialMode: ThemeMode.DEFAULT });
+
+  expect(controller.getCurrentMode()).toBe(ThemeMode.DEFAULT);
+  const lastCall =
+    mockSetConfig.mock.calls[mockSetConfig.mock.calls.length - 1][0];
+  expect(lastCall.token.colorBgBase).toBe(DEFAULT_THEME.token!.colorBgBase);
+});
+
+test('ThemeController with initialMode still allows setThemeMode after init', () => {
+  mockGetBootstrapData.mockReturnValue(
+    createMockBootstrapData({
+      default: DEFAULT_THEME,
+      dark: DARK_THEME,
+    }),
+  );
+
+  const controller = createController({ initialMode: ThemeMode.DEFAULT });
+  expect(controller.getCurrentMode()).toBe(ThemeMode.DEFAULT);
+
+  controller.setThemeMode(ThemeMode.DARK);
+  expect(controller.getCurrentMode()).toBe(ThemeMode.DARK);
+
+  controller.setThemeMode(ThemeMode.SYSTEM);
+  expect(controller.getCurrentMode()).toBe(ThemeMode.SYSTEM);
+});
+
+test('ThemeController initialMode is ignored when no dark theme exists', () => {
+  mockGetBootstrapData.mockReturnValue(
+    createMockBootstrapData({
+      default: DEFAULT_THEME,
+      dark: {},
+    }),
+  );
+
+  const controller = createController({ initialMode: ThemeMode.SYSTEM });
+
+  // Should still be DEFAULT because there's no dark theme available
+  expect(controller.getCurrentMode()).toBe(ThemeMode.DEFAULT);
+});
+
+test('ThemeController invalid initialMode falls back to SYSTEM', () => {
+  mockGetBootstrapData.mockReturnValue(
+    createMockBootstrapData({
+      default: DEFAULT_THEME,
+      dark: DARK_THEME,
+    }),
+  );
+
+  const controller = createController({
+    initialMode: 'invalid' as ThemeMode,
+  });
+
+  // Invalid initialMode should be rejected by isValidThemeMode,
+  // falling through to the default SYSTEM mode
+  expect(controller.getCurrentMode()).toBe(ThemeMode.SYSTEM);
+});