@openedx/frontend-base 1.0.0-alpha.1 → 1.0.0-alpha.11

package/README.md

@@ -67,6 +67,33 @@ npm run dev
 
 The development site will be available at `http://apps.local.openedx.io:8080`.
 
+### Developing an app and `frontend-base` concurrently
+
+Concurrent development with `frontend-base` uses a tarball-based workflow rather than traditional local linking approaches. See [test-site/tools/autoinstall/README.md](./test-site/tools/autoinstall/README.md) for details.
+
+#### In `frontend-base`
+
+This watches for changes in `frontend-base` and rebuilds the packaged tarball on each change.
+
+```sh
+nvm use
+npm ci
+npm run dev:pack
+```
+
+#### In the consuming application
+
+> [!NOTE]
+> This assumes the consuming application has the same tooling as [test-site/tools/autoinstall/](./test-site/tools/autoinstall/)
+
+This watches for changes to the generated .tgz, installs the updated package, and restarts the dev server.
+
+```sh
+nvm use
+npm ci
+npm run dev:autoinstall
+```
+
 ## Migrating an MFE to `frontend-base`
 
 See the [Frontend App Migration How To](./docs/how_tos/migrate-frontend-app.md).

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/jest/jest.config.js

@@ -9,6 +9,7 @@ module.exports = {
     moduleNameMapper: {
         '\\.(css|scss)$': require.resolve('identity-obj-proxy'),
         'site.config': path.resolve(process.cwd(), './site.config.test.tsx'),
+        '^@src/(.*)$': '<rootDir>/src/$1',
     },
     collectCoverageFrom: [
         'src/**/*.{js,jsx,ts,tsx}',

package/config/types.js

@@ -12,8 +12,6 @@ var ConfigTypes;
 })(ConfigTypes || (exports.ConfigTypes = ConfigTypes = {}));
 var CommandTypes;
 (function (CommandTypes) {
-    CommandTypes["RELEASE"] = "release";
-    CommandTypes["PACK"] = "pack";
     CommandTypes["LINT"] = "lint";
     CommandTypes["TEST"] = "test";
     CommandTypes["BUILD"] = "build";

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',
@@ -36,6 +30,7 @@ const config = {
         alias: {
             ...aliases,
             'site.config': resolvedSiteConfigPath,
+            '@src': path_1.default.resolve(process.cwd(), 'src'),
         },
         extensions: ['.js', '.jsx', '.ts', '.tsx'],
     },
@@ -51,10 +46,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 +56,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'),
@@ -32,6 +26,7 @@ const config = {
         alias: {
             ...aliases,
             'site.config': resolvedSiteConfigPath,
+            '@src': path_1.default.resolve(process.cwd(), 'src'),
         },
         extensions: ['.js', '.jsx', '.ts', '.tsx'],
     },
@@ -47,10 +42,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 +51,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',
@@ -72,5 +62,9 @@ const config = {
     // This configures webpack-dev-server which serves bundles from memory and provides live
     // reloading.
     devServer: (0, common_config_1.getDevServer)(),
+    // Limit the number of watched files to avoid `inotify` resource starvation.
+    watchOptions: {
+        ignored: /node_modules/
+    }
 };
 exports.default = config;

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'),
@@ -35,6 +29,7 @@ const config = {
         alias: {
             ...aliases,
             'site.config': resolvedSiteConfigPath,
+            '@src': path_1.default.resolve(process.cwd(), 'src'),
         },
         extensions: ['.js', '.jsx', '.ts', '.tsx'],
     },
@@ -77,10 +72,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 +81,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',
@@ -106,5 +96,9 @@ const config = {
     // This configures webpack-dev-server which serves bundles from memory and provides live
     // reloading.
     devServer: (0, common_config_1.getDevServer)(),
+    // Limit the number of watched files to avoid `inotify` resource starvation.
+    watchOptions: {
+        ignored: /node_modules/
+    }
 };
 exports.default = config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openedx/frontend-base",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.11",
   "description": "Build tools, setup and config for frontend apps",
   "publishConfig": {
     "access": "public"
@@ -26,7 +26,10 @@
     "docs:watch": "nodemon -w runtime -w docs/template -w README.md -e js,jsx,ts,tsx --exec npm run docs",
     "lint": "eslint .; npm run lint:tools; npm --prefix ./test-site run lint",
     "lint:tools": "cd ./tools && eslint . && cd ..",
-    "test": "jest"
+    "test": "jest",
+    "pack:local": "mkdir -p pack && npm pack --silent --pack-destination pack >/dev/null && mv \"$(ls -t pack/*.tgz | head -n 1)\" pack/openedx-frontend-base.tgz",
+    "build:pack": "make build && npm run pack:local",
+    "dev:pack": "nodemon --config nodemon.pack.json"
   },
   "repository": {
     "type": "git",
@@ -86,6 +89,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 +105,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 +150,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/index.ts

@@ -110,6 +110,11 @@ export {
   useAppConfig
 } from './react';
 
+export {
+  getUrlByRouteRole,
+  isRoleRouteObject
+} from './routing';
+
 export {
   clearAllSubscriptions,
   publish,

package/runtime/jest.config.js

@@ -7,6 +7,7 @@ module.exports = {
     '\\.(jpg|jpeg|png|gif|eot|otf|webp|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$': '<rootDir/__mocks__/file.js',
     '\\.(css|scss)$': require.resolve('identity-obj-proxy'),
     'site.config': '<rootDir>/site.config.test.tsx',
+    '^@src/(.*)$': '<rootDir>/src/$1',
   },
   testEnvironment: 'jsdom',
   testEnvironmentOptions: {

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();
+  });
+});