@openedx/frontend-base 1.0.0-alpha.6 → 1.0.0-alpha.8

package/config/eslint/base.eslint.config.js

@@ -31,7 +31,6 @@ module.exports = tseslint.config(eslint.configs.recommended, ...tseslint.configs
             ...globals.browser,
             ...globals.node,
             ...globals.jest,
-            PARAGON_THEME: 'readonly',
             newrelic: 'readonly',
         },
     },
@@ -79,6 +78,7 @@ module.exports = tseslint.config(eslint.configs.recommended, ...tseslint.configs
                 caughtErrors: 'none',
             }],
         '@typescript-eslint/no-empty-function': 'off',
+        '@typescript-eslint/prefer-nullish-coalescing': 'off',
         '@stylistic/semi': ['error', 'always', { omitLastInOneLineBlock: true, omitLastInOneLineClassBody: true }],
         '@stylistic/quotes': ['error', 'single', {
                 avoidEscape: true,

package/config/webpack/common-config/all/getStylesheetRule.js

@@ -87,7 +87,7 @@ function getStyleUseConfig(mode) {
                     ],
                     // Silences compiler deprecation warnings.  They mostly come from bootstrap and/or paragon.
                     quietDeps: true,
-                    silenceDeprecations: ['abs-percent', 'color-functions', 'import', 'mixed-decls', 'global-builtin', 'legacy-js-api'],
+                    silenceDeprecations: ['abs-percent', 'color-functions', 'import', 'global-builtin', 'legacy-js-api'],
                 },
             },
         },

package/config/webpack/webpack.config.build.js

@@ -9,13 +9,9 @@ const path_1 = __importDefault(require("path"));
 const webpack_bundle_analyzer_1 = require("webpack-bundle-analyzer");
 const webpack_remove_empty_scripts_1 = __importDefault(require("webpack-remove-empty-scripts"));
 const common_config_1 = require("./common-config");
-const ParagonWebpackPlugin_1 = __importDefault(require("./plugins/paragon-webpack-plugin/ParagonWebpackPlugin"));
 const getLocalAliases_1 = __importDefault(require("./utils/getLocalAliases"));
 const getPublicPath_1 = __importDefault(require("./utils/getPublicPath"));
 const getResolvedSiteConfigPath_1 = __importDefault(require("./utils/getResolvedSiteConfigPath"));
-const paragonUtils_1 = require("./utils/paragonUtils");
-const paragonThemeCss = (0, paragonUtils_1.getParagonThemeCss)(process.cwd());
-const brandThemeCss = (0, paragonUtils_1.getParagonThemeCss)(process.cwd(), { isBrandOverride: true });
 const aliases = (0, getLocalAliases_1.default)();
 const resolvedSiteConfigPath = (0, getResolvedSiteConfigPath_1.default)('site.config.build.tsx');
 const config = {
@@ -23,8 +19,6 @@ const config = {
     devtool: 'source-map',
     entry: {
         app: path_1.default.resolve(process.cwd(), 'node_modules/@openedx/frontend-base/shell/site'),
-        ...(0, paragonUtils_1.getParagonEntryPoints)(paragonThemeCss),
-        ...(0, paragonUtils_1.getParagonEntryPoints)(brandThemeCss),
     },
     output: {
         filename: '[name].[chunkhash].js',
@@ -51,10 +45,6 @@ const config = {
         runtimeChunk: 'single',
         splitChunks: {
             chunks: 'all',
-            cacheGroups: {
-                ...(0, paragonUtils_1.getParagonCacheGroups)(paragonThemeCss),
-                ...(0, paragonUtils_1.getParagonCacheGroups)(brandThemeCss),
-            },
         },
         minimizer: (0, common_config_1.getImageMinimizer)(),
     },
@@ -65,7 +55,6 @@ const config = {
         // See: https://www.npmjs.com/package/webpack-remove-empty-scripts#usage-with-mini-css-extract-plugin
         new webpack_remove_empty_scripts_1.default(),
         // Writes the extracted CSS from each entry to a file in the output directory.
-        new ParagonWebpackPlugin_1.default(),
         new mini_css_extract_plugin_1.default({
             filename: '[name].[chunkhash].css',
         }),

package/config/webpack/webpack.config.dev.js

@@ -9,20 +9,14 @@ const mini_css_extract_plugin_1 = __importDefault(require("mini-css-extract-plug
 const path_1 = __importDefault(require("path"));
 const webpack_remove_empty_scripts_1 = __importDefault(require("webpack-remove-empty-scripts"));
 const common_config_1 = require("./common-config");
-const ParagonWebpackPlugin_1 = __importDefault(require("./plugins/paragon-webpack-plugin/ParagonWebpackPlugin"));
 const getLocalAliases_1 = __importDefault(require("./utils/getLocalAliases"));
 const getPublicPath_1 = __importDefault(require("./utils/getPublicPath"));
 const getResolvedSiteConfigPath_1 = __importDefault(require("./utils/getResolvedSiteConfigPath"));
-const paragonUtils_1 = require("./utils/paragonUtils");
-const paragonThemeCss = (0, paragonUtils_1.getParagonThemeCss)(process.cwd());
-const brandThemeCss = (0, paragonUtils_1.getParagonThemeCss)(process.cwd(), { isBrandOverride: true });
 const aliases = (0, getLocalAliases_1.default)();
 const resolvedSiteConfigPath = (0, getResolvedSiteConfigPath_1.default)('site.config.dev.tsx');
 const config = {
     entry: {
         app: path_1.default.resolve(process.cwd(), 'node_modules/@openedx/frontend-base/shell/site'),
-        ...(0, paragonUtils_1.getParagonEntryPoints)(paragonThemeCss),
-        ...(0, paragonUtils_1.getParagonEntryPoints)(brandThemeCss),
     },
     output: {
         path: path_1.default.resolve(process.cwd(), './dist'),
@@ -47,10 +41,6 @@ const config = {
     optimization: {
         splitChunks: {
             chunks: 'all',
-            cacheGroups: {
-                ...(0, paragonUtils_1.getParagonCacheGroups)(paragonThemeCss),
-                ...(0, paragonUtils_1.getParagonCacheGroups)(brandThemeCss),
-            },
         },
         minimizer: (0, common_config_1.getImageMinimizer)(),
     },
@@ -60,7 +50,6 @@ const config = {
         // This helps to clean up the final bundle application
         // See: https://www.npmjs.com/package/webpack-remove-empty-scripts#usage-with-mini-css-extract-plugin
         new webpack_remove_empty_scripts_1.default(),
-        new ParagonWebpackPlugin_1.default(),
         // Writes the extracted CSS from each entry to a file in the output directory.
         new mini_css_extract_plugin_1.default({
             filename: '[name].css',

package/config/webpack/webpack.config.dev.shell.js

@@ -11,21 +11,15 @@ const path_1 = __importDefault(require("path"));
 const react_refresh_typescript_1 = __importDefault(require("react-refresh-typescript"));
 const webpack_remove_empty_scripts_1 = __importDefault(require("webpack-remove-empty-scripts"));
 const common_config_1 = require("./common-config");
-const ParagonWebpackPlugin_1 = __importDefault(require("./plugins/paragon-webpack-plugin/ParagonWebpackPlugin"));
 const html_webpack_plugin_1 = __importDefault(require("html-webpack-plugin"));
 const getLocalAliases_1 = __importDefault(require("./utils/getLocalAliases"));
 const getPublicPath_1 = __importDefault(require("./utils/getPublicPath"));
 const getResolvedSiteConfigPath_1 = __importDefault(require("./utils/getResolvedSiteConfigPath"));
-const paragonUtils_1 = require("./utils/paragonUtils");
-const paragonThemeCss = (0, paragonUtils_1.getParagonThemeCss)(process.cwd());
-const brandThemeCss = (0, paragonUtils_1.getParagonThemeCss)(process.cwd(), { isBrandOverride: true });
 const aliases = (0, getLocalAliases_1.default)();
 const resolvedSiteConfigPath = (0, getResolvedSiteConfigPath_1.default)('shell/site.config.dev.tsx');
 const config = {
     entry: {
         app: path_1.default.resolve(process.cwd(), 'shell/site'),
-        ...(0, paragonUtils_1.getParagonEntryPoints)(paragonThemeCss),
-        ...(0, paragonUtils_1.getParagonEntryPoints)(brandThemeCss),
     },
     output: {
         path: path_1.default.resolve(process.cwd(), './dist'),
@@ -77,10 +71,6 @@ const config = {
     optimization: {
         splitChunks: {
             chunks: 'all',
-            cacheGroups: {
-                ...(0, paragonUtils_1.getParagonCacheGroups)(paragonThemeCss),
-                ...(0, paragonUtils_1.getParagonCacheGroups)(brandThemeCss),
-            },
         },
         minimizer: (0, common_config_1.getImageMinimizer)(),
     },
@@ -90,7 +80,6 @@ const config = {
         // This helps to clean up the final bundle application
         // See: https://www.npmjs.com/package/webpack-remove-empty-scripts#usage-with-mini-css-extract-plugin
         new webpack_remove_empty_scripts_1.default(),
-        new ParagonWebpackPlugin_1.default(),
         // Writes the extracted CSS from each entry to a file in the output directory.
         new mini_css_extract_plugin_1.default({
             filename: '[name].css',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openedx/frontend-base",
-  "version": "1.0.0-alpha.6",
+  "version": "1.0.0-alpha.8",
   "description": "Build tools, setup and config for frontend apps",
   "publishConfig": {
     "access": "public"
@@ -86,6 +86,7 @@
     "image-minimizer-webpack-plugin": "3.8.3",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "jest-localstorage-mock": "^2.4.26",
     "jwt-decode": "^3.1.2",
     "localforage": "^1.10.0",
     "localforage-memoryStorageDriver": "^0.9.2",
@@ -101,7 +102,7 @@
     "postcss-rtlcss": "^5.5.0",
     "prop-types": "^15.8.1",
     "react-dev-utils": "12.0.1",
-    "react-focus-on": "^3.9.4",
+    "react-focus-on": "<3.10.0",
     "react-intl": "^6.6.6",
     "react-refresh": "0.16.0",
     "react-refresh-typescript": "^2.0.9",
@@ -146,7 +147,7 @@
     "nodemon": "^3.1.4"
   },
   "peerDependencies": {
-    "@openedx/paragon": "^22.20.2",
+    "@openedx/paragon": "^23.4.5",
     "@tanstack/react-query": "^5.81.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",

package/runtime/config/index.ts

@@ -124,6 +124,7 @@ let siteConfig: SiteConfig = {
   externalRoutes: [],
   externalLinkUrlOverrides: [],
   mfeConfigApiUrl: null,
+  theme: {},
   accessTokenCookieName: 'edx-jwt-cookie-header-payload',
   csrfTokenApiPath: '/csrf/api/v1/token',
   ignoredErrorRegex: null,
@@ -238,9 +239,7 @@ export function getActiveRouteRoles() {
 const activeWidgetRoles: Record<string, number> = {};
 
 export function addActiveWidgetRole(role: string) {
-  if (activeWidgetRoles[role] === undefined) {
-    activeWidgetRoles[role] = 0;
-  }
+  activeWidgetRoles[role] ??= 0;
   activeWidgetRoles[role] += 1;
   publish(ACTIVE_ROLES_CHANGED);
 }

package/runtime/react/SiteProvider.tsx

@@ -13,7 +13,13 @@ import {
 import CombinedAppProvider from './CombinedAppProvider';
 import ErrorBoundary from './ErrorBoundary';
 import SiteContext from './SiteContext';
-import { useSiteEvent } from './hooks';
+import { SELECTED_THEME_VARIANT_KEY } from './constants';
+import {
+  useTheme,
+  useSiteEvent,
+  useTrackColorSchemeChoice
+} from './hooks';
+import { themeActions } from './reducers';
 
 interface SiteProviderProps {
   children: ReactNode,
@@ -37,6 +43,7 @@ interface SiteProviderProps {
  * - An error boundary as described above.
  * - An `SiteContext` provider for React context data.
  * - IntlProvider for @edx/frontend-i18n internationalization
+ * - A theme manager for Paragon.
  *
  * @param {Object} props
  * @memberof module:React
@@ -58,11 +65,27 @@ export default function SiteProvider({ children }: SiteProviderProps) {
     setLocale(getLocale());
   });
 
+  useTrackColorSchemeChoice();
+  const [themeState, themeDispatch] = useTheme();
+
   const siteContextValue = useMemo(() => ({
     authenticatedUser,
     siteConfig,
-    locale
-  }), [authenticatedUser, siteConfig, locale]);
+    locale,
+    theme: {
+      state: themeState,
+      setThemeVariant: (themeVariant: string) => {
+        themeDispatch(themeActions.setThemeVariant(themeVariant));
+
+        // Persist selected theme variant to localStorage.
+        window.localStorage.setItem(SELECTED_THEME_VARIANT_KEY, themeVariant);
+      },
+    },
+  }), [authenticatedUser, siteConfig, locale, themeState, themeDispatch]);
+
+  if (!themeState?.isThemeLoaded) {
+    return null;
+  }
 
   return (
     <IntlProvider locale={locale} messages={getMessages()}>

package/runtime/react/constants.ts

@@ -0,0 +1,3 @@
+export const SET_THEME_VARIANT = 'SET_THEME_VARIANT';
+export const SET_IS_THEME_LOADED = 'SET_IS_THEME_LOADED';
+export const SELECTED_THEME_VARIANT_KEY = 'selected-theme-variant';

package/runtime/react/hooks/index.ts

@@ -0,0 +1,8 @@
+export { default as useAppConfig } from './useAppConfig';
+export { default as useAuthenticatedUser } from './useAuthenticatedUser';
+export { default as useActiveRouteRoleWatcher } from './useActiveRouteRoleWatcher';
+export { default as useActiveRoles } from './useActiveRoles';
+export { default as useSiteConfig } from './useSiteConfig';
+export { default as useSiteEvent } from './useSiteEvent';
+
+export * from './theme';

package/runtime/react/hooks/theme/index.ts

@@ -0,0 +1,2 @@
+export { default as useTrackColorSchemeChoice } from './useTrackColorSchemeChoice';
+export { default as useTheme } from './useTheme';

package/runtime/react/hooks/theme/useTheme.test.ts

@@ -0,0 +1,221 @@
+import { act, fireEvent, renderHook } from '@testing-library/react';
+
+import useTheme from './useTheme';
+import * as config from '../../../config';
+import { logError } from '../../../logging';
+
+jest.mock('../../../logging');
+
+const baseSiteConfig = config.getSiteConfig();
+
+const theme = {
+  core: {
+    url: 'https://cdn.jsdelivr.net/npm/@openedx/brand@1.0.0/dist/core.min.css',
+  },
+  defaults: {
+    light: 'light',
+    dark: 'dark',
+  },
+  variants: {
+    light: {
+      url: 'https://cdn.jsdelivr.net/npm/@openedx/brand@1.0.0/dist/light.min.css',
+    },
+    dark: {
+      url: 'https://cdn.jsdelivr.net/npm/@openedx/brand@1.0.0/dist/dark.min.css',
+    },
+  },
+};
+
+let mockMediaQueryListEvent;
+const mockAddEventListener = jest.fn((_, fn) => fn(mockMediaQueryListEvent));
+const mockRemoveEventListener = jest.fn();
+
+Object.defineProperty(window, 'matchMedia', {
+  value: jest.fn(() => ({
+    addEventListener: mockAddEventListener,
+    removeEventListener: mockRemoveEventListener,
+    matches: mockMediaQueryListEvent.matches,
+  })),
+});
+
+Object.defineProperty(window, 'localStorage', {
+  value: {
+    getItem: jest.fn(),
+  },
+});
+
+describe('useTheme', () => {
+  beforeEach(() => {
+    document.head.innerHTML = '';
+    mockMediaQueryListEvent = { matches: true };
+    mockAddEventListener.mockClear();
+    mockRemoveEventListener.mockClear();
+    jest.mocked(window.localStorage.getItem).mockClear();
+  });
+
+  afterEach(() => {
+    jest.spyOn(config, 'getSiteConfig').mockRestore();
+  });
+
+  it.each([
+    ['dark', 'stylesheet', 'alternate stylesheet', true], // preference is dark
+    ['light', 'alternate stylesheet', 'stylesheet', false], // preference is light
+  ])(
+    'should configure theme variant for system preference %s and handle theme change events',
+    (initialPreference, expectedDarkRel, expectedLightRel, isDarkMediaMatch) => {
+      jest.spyOn(config, 'getSiteConfig').mockReturnValue({
+        ...baseSiteConfig,
+        theme
+      });
+      // Mock the matchMedia behavior to simulate system preference
+      mockMediaQueryListEvent = { matches: isDarkMediaMatch };
+      // Set up the hook and initial theme configuration
+      const { result, unmount } = renderHook(() => useTheme());
+      const themeLinks = document.head.querySelectorAll('link');
+
+      const checkThemeLinks = () => {
+        const darkLink: HTMLAnchorElement | null = document.head.querySelector('link[data-theme-variant="dark"]');
+        const lightLink: HTMLAnchorElement | null = document.head.querySelector('link[data-theme-variant="light"]');
+        expect(darkLink?.rel).toBe(expectedDarkRel);
+        expect(lightLink?.rel).toBe(expectedLightRel);
+      };
+
+      // Simulate initial theme configuration based on system preference
+      act(() => {
+        themeLinks.forEach((link) => fireEvent.load(link));
+      });
+
+      // Ensure matchMedia was called with the correct system preference
+      expect(window.matchMedia).toHaveBeenCalledWith('(prefers-color-scheme: dark)');
+      expect(mockAddEventListener).toHaveBeenCalled();
+
+      // Check initial theme setup
+      checkThemeLinks();
+      expect(result.current[0]).toEqual({
+        isThemeLoaded: true,
+        themeVariant: initialPreference,
+      });
+
+      unmount();
+      expect(mockRemoveEventListener).toHaveBeenCalled();
+    },
+  );
+
+  it('should configure theme variants according with user preference if is defined (localStorage)', () => {
+    jest.spyOn(config, 'getSiteConfig').mockReturnValue({
+      ...baseSiteConfig,
+      theme
+    });
+    jest.mocked(window.localStorage.getItem).mockReturnValue('light');
+    const { result, unmount } = renderHook(() => useTheme());
+    const themeLinks = document.head.querySelectorAll('link');
+    const darkLink: HTMLAnchorElement | null = document.head.querySelector('link[data-theme-variant="dark"]');
+    const lightLink: HTMLAnchorElement | null = document.head.querySelector('link[data-theme-variant="light"]');
+
+    act(() => {
+      themeLinks.forEach((link) => fireEvent.load(link));
+    });
+
+    expect(window.matchMedia).toHaveBeenCalledWith('(prefers-color-scheme: dark)');
+    expect(mockAddEventListener).toHaveBeenCalled();
+
+    expect(darkLink?.rel).toBe('alternate stylesheet');
+    expect(lightLink?.rel).toBe('stylesheet');
+    expect(result.current[0]).toEqual({ isThemeLoaded: true, themeVariant: 'light' });
+
+    unmount();
+    expect(mockRemoveEventListener).toHaveBeenCalled();
+  });
+
+  it('should define the theme variant as default if only 1 is configured', () => {
+    jest.spyOn(config, 'getSiteConfig').mockReturnValue({
+      ...baseSiteConfig,
+      theme: { ...theme, variants: { light: theme.variants.light } }
+    });
+    jest.mocked(window.localStorage.getItem).mockReturnValue('light');
+    const { result, unmount } = renderHook(() => useTheme());
+    const themeLinks = document.head.querySelectorAll('link');
+    const themeVariantLinks: NodeListOf<HTMLAnchorElement> | null = document.head.querySelectorAll('link[data-theme-variant]');
+
+    act(() => {
+      themeLinks.forEach((link) => fireEvent.load(link));
+    });
+
+    expect(themeVariantLinks.length).toBe(1);
+    expect((themeVariantLinks[0]).rel).toBe('stylesheet');
+    expect(result.current[0]).toEqual({ isThemeLoaded: true, themeVariant: 'light' });
+
+    unmount();
+    expect(mockRemoveEventListener).toHaveBeenCalled();
+  });
+
+  it('should not configure any theme if theme is undefined', () => {
+    const { result, unmount } = renderHook(() => useTheme());
+    const themeLinks = document.head.querySelectorAll('link');
+
+    expect(result.current[0]).toEqual({ isThemeLoaded: true, themeVariant: undefined });
+    expect(themeLinks.length).toBe(0);
+    unmount();
+  });
+
+  it('should return themeVariant undefined if a default variant cannot be configured', () => {
+    jest.spyOn(config, 'getSiteConfig').mockReturnValue({
+      ...baseSiteConfig,
+      theme: {
+        ...theme,
+        defaults: {
+          light: 'red'
+        },
+        variants: {
+          light: theme.variants.light,
+          green: { url: 'green-url' }
+        }
+      }
+    });
+    jest.mocked(window.localStorage.getItem).mockReturnValue(null);
+
+    const { result, unmount } = renderHook(() => useTheme());
+    const themeLinks = document.head.querySelectorAll('link');
+    const themeVariantLinks = document.head.querySelectorAll('link[data-theme-variant]');
+    act(() => {
+      themeLinks.forEach((link) => fireEvent.load(link));
+    });
+
+    expect(result.current[0]).toEqual({ isThemeLoaded: true, themeVariant: undefined });
+    expect(themeLinks.length).toBe(3);
+    themeVariantLinks.forEach((link: HTMLAnchorElement) => expect(link.rel).toBe('alternate stylesheet'));
+    unmount();
+  });
+
+  it('should log an error if the preferred theme variant cannot be set', async () => {
+    jest.spyOn(config, 'getSiteConfig').mockReturnValue({
+      ...baseSiteConfig,
+      theme: {
+        ...theme,
+        defaults: {
+          light: 'light',
+          dark: 'dark'
+        },
+        variants: {
+          light: theme.variants.light,
+          green: { url: 'green-url' }
+        }
+      }
+    });
+    jest.mocked(window.localStorage.getItem).mockReturnValue(null);
+
+    const { result, unmount } = renderHook(() => useTheme());
+    const themeLinks = document.head.querySelectorAll('link');
+    const themeVariantLinks = document.head.querySelectorAll('link[data-theme-variant]');
+
+    act(() => {
+      themeLinks.forEach((link) => fireEvent.load(link));
+    });
+
+    expect(result.current[0]).toEqual({ isThemeLoaded: true, themeVariant: 'dark' });
+    expect(logError).toHaveBeenCalled();
+    expect(themeVariantLinks.length).toBe(2);
+    themeVariantLinks.forEach((link: HTMLAnchorElement) => expect(link.rel).toBe('alternate stylesheet'));
+    unmount();
+  });
+});

package/runtime/react/hooks/theme/useTheme.ts

@@ -0,0 +1,179 @@
+import {
+  useCallback, useEffect, useReducer, useState,
+} from 'react';
+
+import { SELECTED_THEME_VARIANT_KEY } from '../../constants';
+import { logError } from '../../../logging';
+import { themeActions, themeReducer } from '../../reducers';
+import { ThemeVariants, ThemeDefaults } from '../../../../types';
+import { isEmptyObject } from './utils';
+
+import useThemeCore from './useThemeCore';
+import useThemeConfig from './useThemeConfig';
+import useThemeVariants from './useThemeVariants';
+
+/**
+* Finds the default theme variant from the given theme variants object. If no default theme exists, the light theme
+* variant is returned as a fallback.
+*
+* It prioritizes:
+*   1. A persisted theme variant from localStorage.
+*   2. A system preference (`prefers-color-scheme`).
+*   3. The configured default theme variant.
+*
+* Returns the default theme variant, or `undefined` if no valid theme variant is found.
+*/
+export const getDefaultThemeVariant = (themeVariants: ThemeVariants | undefined, themeDefaults: ThemeDefaults = {}) => {
+  if (!themeVariants) {
+    return undefined;
+  }
+
+  const themeVariantKeys = Object.keys(themeVariants);
+
+  // If there is only one theme variant, return it since it's the only one that may be used.
+  if (themeVariantKeys.length === 1) {
+    const themeVariantKey = themeVariantKeys[0];
+    return {
+      name: themeVariantKey,
+      metadata: themeVariants[themeVariantKey],
+    };
+  }
+
+  // Prioritize persisted localStorage theme variant preference.
+  const persistedSelectedThemeVariant = localStorage.getItem(SELECTED_THEME_VARIANT_KEY);
+  if (persistedSelectedThemeVariant && themeVariants[persistedSelectedThemeVariant]) {
+    return {
+      name: persistedSelectedThemeVariant,
+      metadata: themeVariants[persistedSelectedThemeVariant],
+    };
+  }
+
+  // Then, detect system preference via `prefers-color-scheme` media query and use
+  // the default dark theme variant, if one exists.
+  const hasDarkSystemPreference = !!window.matchMedia?.('(prefers-color-scheme: dark)')?.matches;
+  const defaultDarkThemeVariant = themeDefaults.dark ?? 'dark';
+  const darkThemeVariantMetadata = themeVariants[defaultDarkThemeVariant];
+
+  if (hasDarkSystemPreference && defaultDarkThemeVariant && darkThemeVariantMetadata) {
+    return {
+      name: defaultDarkThemeVariant,
+      metadata: darkThemeVariantMetadata,
+    };
+  }
+
+  const defaultLightThemeVariant = themeDefaults.light ?? 'light';
+  const lightThemeVariantMetadata = themeVariants[defaultLightThemeVariant];
+
+  // Handle edge case where the default light theme variant is not configured or provided.
+  if (!lightThemeVariantMetadata) {
+    return undefined;
+  }
+
+  // Otherwise, fallback to using the default light theme variant as configured.
+  return {
+    name: defaultLightThemeVariant,
+    metadata: lightThemeVariantMetadata,
+  };
+};
+
+/**
+ * A custom React hook that manages the application's theme state and injects the appropriate CSS for the theme core
+ * and theme variants (e.g., light and dark modes) into the HTML document. It handles dynamically loading the theme
+ * CSS based on the current theme variant, and ensures that the theme variant's CSS is preloaded for runtime theme
+ * switching. This is done using "alternate" stylesheets. That is, the browser will download the CSS for the
+ * non-current theme variants with a lower priority than the current one.
+ *
+ * The hook also responds to system theme preference changes (e.g., via the `prefers-color-scheme` media query),
+ * and can automatically switch the theme based on the system's dark mode or light mode preference.
+ *
+ * * @example
+ * const [themeState, dispatch] = useTheme();
+ * console.log(themeState.isThemeLoaded); // true when the theme has been successfully loaded.
+ *
+ * // Dispatch an action to change the theme variant
+ * dispatch(themeActions.setThemeVariant('dark'));
+ */
+const useTheme = () => {
+  const themeConfig = useThemeConfig();
+  const {
+    core: themeCore,
+    defaults: themeVariantDefaults,
+    variants: themeVariants,
+  } = themeConfig;
+  const initialThemeState = {
+    isThemeLoaded: false,
+    themeVariant: getDefaultThemeVariant(themeVariants, themeVariantDefaults)?.name,
+  };
+  const [themeState, dispatch] = useReducer(themeReducer, initialThemeState);
+
+  const [isThemeCoreLoaded, setIsThemeCoreLoaded] = useState(false);
+  const onLoadThemeCore = useCallback(() => {
+    setIsThemeCoreLoaded(true);
+  }, []);
+
+  const [hasLoadedThemeVariants, setHasLoadedThemeVariants] = useState(false);
+  const onLoadThemeVariants = useCallback(() => {
+    setHasLoadedThemeVariants(true);
+  }, []);
+
+  // load the theme's core CSS
+  useThemeCore({
+    themeCore,
+    onComplete: onLoadThemeCore,
+  });
+
+  // respond to system preference changes with regard to `prefers-color-scheme: dark`.
+  const handleDarkModeSystemPreferenceChange = useCallback((prefersDarkMode: boolean) => {
+    // Ignore system preference change if the theme variant is already set in localStorage.
+    if (localStorage.getItem(SELECTED_THEME_VARIANT_KEY)) {
+      return;
+    }
+
+    if (prefersDarkMode && themeVariantDefaults?.dark) {
+      dispatch(themeActions.setThemeVariant(themeVariantDefaults.dark));
+    } else if (!prefersDarkMode && themeVariantDefaults?.light) {
+      dispatch(themeActions.setThemeVariant(themeVariantDefaults.light));
+    } else {
+      logError(`Could not set theme variant based on system preference (prefers dark mode: ${prefersDarkMode})`);
+    }
+  }, [themeVariantDefaults]);
+
+  // load the theme variant(s) CSS
+  useThemeVariants({
+    themeVariants,
+    onComplete: onLoadThemeVariants,
+    currentThemeVariant: themeState.themeVariant,
+    onDarkModeSystemPreferenceChange: handleDarkModeSystemPreferenceChange,
+  });
+
+  useEffect(() => {
+    // theme is already loaded, do nothing
+    if (themeState.isThemeLoaded) {
+      return;
+    }
+
+    const hasThemeConfig = (themeCore?.url && !isEmptyObject(themeVariants));
+    if (!hasThemeConfig) {
+      // no theme URLs to load, set loading to false.
+      dispatch(themeActions.setThemeLoaded(true));
+    }
+
+    // Return early if neither the core theme CSS nor any theme variant CSS is loaded.
+    if (!isThemeCoreLoaded || !hasLoadedThemeVariants) {
+      return;
+    }
+
+    // All application theme URLs are loaded
+    dispatch(themeActions.setThemeLoaded(true));
+  }, [
+    themeState.isThemeLoaded,
+    isThemeCoreLoaded,
+    hasLoadedThemeVariants,
+    themeCore?.url,
+    themeVariants,
+  ]);
+
+  return [themeState, dispatch];
+};
+
+export default useTheme;