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

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;

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

@@ -0,0 +1,107 @@
+import { renderHook } from '@testing-library/react';
+
+import useThemeConfig from './useThemeConfig';
+import * as config from '../../../config';
+
+const baseSiteConfig = config.getSiteConfig();
+
+describe('useThemeConfig', () => {
+  afterEach(() => {
+    jest.spyOn(config, 'getSiteConfig').mockRestore();
+    jest.resetAllMocks();
+  });
+
+  it.each([
+    [undefined, {}],
+    [{}, {}],
+  ])('handles when `siteConfig.theme` is not present (%s)', (theme, expectedURLConfig) => {
+    jest.spyOn(config, 'getSiteConfig').mockReturnValue({
+      ...baseSiteConfig,
+      theme
+    });
+    const { result } = renderHook(() => useThemeConfig());
+    expect(result.current).toEqual(expectedURLConfig);
+  });
+
+  describe('when `siteConfig.theme` is present', () => {
+    it('returns empty object if core is not defined and no variants are defined', () => {
+      jest.spyOn(config, 'getSiteConfig').mockReturnValue({
+        ...baseSiteConfig,
+        theme: {
+          core: undefined,
+          variants: {}
+        },
+      });
+      const { result } = renderHook(() => useThemeConfig());
+      expect(result.current).toStrictEqual({});
+    });
+    it('returns expected object when only core is defined', () => {
+      jest.spyOn(config, 'getSiteConfig').mockReturnValue({
+        ...baseSiteConfig,
+        theme: {
+          core: {
+            url: 'core.css',
+          },
+        },
+      });
+      const { result } = renderHook(() => useThemeConfig());
+      expect(result.current).toStrictEqual({
+        core: {
+          url: 'core.css',
+        },
+        defaults: undefined,
+        variants: undefined,
+      });
+    });
+    it('returns expected object when only a light variant is defined', () => {
+      jest.spyOn(config, 'getSiteConfig').mockReturnValue({
+        ...baseSiteConfig,
+        theme: {
+          variants: {
+            light: { url: 'light.css' },
+          }
+        },
+      });
+      const { result } = renderHook(() => useThemeConfig());
+      expect(result.current).toStrictEqual({
+        core: undefined,
+        defaults: undefined,
+        variants: {
+          light: { url: 'light.css' },
+        }
+      });
+    });
+    it('returns expected object when configuration is valid', () => {
+      jest.spyOn(config, 'getSiteConfig').mockReturnValue({
+        ...baseSiteConfig,
+        theme: {
+          core: {
+            url: 'core.css',
+          },
+          defaults: {
+            light: 'light',
+          },
+          variants: {
+            light: {
+              url: 'light.css',
+            },
+          },
+        },
+      });
+      const { result } = renderHook(() => useThemeConfig());
+      expect(result.current).toStrictEqual({
+        core: {
+          url: 'core.css',
+        },
+        defaults: {
+          light: 'light',
+        },
+        variants: {
+          light: {
+            url: 'light.css',
+          },
+        },
+      });
+    });
+  });
+});

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

@@ -0,0 +1,34 @@
+import { useMemo } from 'react';
+
+import { Theme } from '../../../../types';
+import { getSiteConfig } from '../../../config';
+import { isEmptyObject } from './utils';
+
+/**
+ * Custom React hook that retrieves the theme configuration.
+ *
+ * Configuration is considered entirely invalid if it doesn't define at least one variant, including core.
+ *
+ * Example:
+ *
+ * const themeConfig = useThemeConfig();
+ * if (themeConfig) {
+ *   console.log(themeConfig.core.url); // Outputs the URL of theme's core CSS
+ *   console.log(themeConfig.variants['dark'].url); // Outputs the URL of the theme's dark variant CSS
+ * }
+ */
+const useThemeConfig = (): Theme => useMemo(() => {
+  const { theme } = getSiteConfig();
+
+  if (!theme || (isEmptyObject(theme.core) && isEmptyObject(theme.variants))) {
+    return {};
+  }
+
+  return {
+    core: theme.core,
+    defaults: theme.defaults,
+    variants: theme.variants,
+  };
+}, []);
+
+export default useThemeConfig;

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

@@ -0,0 +1,65 @@
+import { act, renderHook, fireEvent } from '@testing-library/react';
+
+import { logError } from '../../../logging';
+
+import useThemeCore from './useThemeCore';
+
+jest.mock('../../../logging');
+
+describe('useThemeCore', () => {
+  const onComplete = jest.fn();
+  let testParams: any;
+
+  beforeEach(() => {
+    document.head.innerHTML = '';
+    testParams = {
+      themeCore: {
+        url: 'https://cdn.jsdelivr.net/npm/@openedx/brand@1.0.0/dist/core.min.css',
+      },
+      onComplete,
+    };
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should load the core url and change the loading state to true', () => {
+    renderHook(() => useThemeCore(testParams));
+
+    const createdLinkTag: HTMLAnchorElement | null = document.head.querySelector('link[data-theme-core="true"]');
+    act(() => {
+      if (createdLinkTag) {
+        fireEvent.load(createdLinkTag);
+      }
+    });
+    expect(createdLinkTag?.href).toBe(testParams.themeCore.url);
+    expect(onComplete).toHaveBeenCalledTimes(1);
+  });
+
+  it('should dispatch a log error if the theme link cannot be loaded', () => {
+    renderHook(() => useThemeCore(testParams));
+
+    const createdLinkTag: HTMLAnchorElement | null = document.head.querySelector('link[data-theme-core="true"]');
+    act(() => {
+      if (createdLinkTag) {
+        fireEvent.error(createdLinkTag);
+      }
+    });
+    expect(logError).toHaveBeenCalledTimes(1);
+    expect(onComplete).toHaveBeenCalledTimes(1);
+  });
+
+  it('should not create a link if there is no configured theme core URL', () => {
+    testParams = {
+      themeCore: {
+        foo: 'bar',
+      },
+      onComplete,
+    };
+
+    renderHook(() => useThemeCore(testParams));
+    expect(document.head.querySelectorAll('link').length).toBe(0);
+    expect(onComplete).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -0,0 +1,52 @@
+import { useEffect, useState } from 'react';
+
+import { logError } from '../../../logging';
+import { removeExistingLinks } from './utils';
+
+/**
+ * Custom React hook that manages the loading and updating of a theme's core
+ * CSS, ensuring the theme's core CSS is added to the document `<head>` as a
+ * `<link>` element.
+ */
+const useThemeCore = ({
+  themeCore,
+  onComplete,
+}) => {
+  const [isThemeCoreComplete, setIsThemeCoreComplete] = useState(false);
+
+  useEffect(() => {
+    if (isThemeCoreComplete) {
+      onComplete();
+    }
+  }, [isThemeCoreComplete, onComplete]);
+
+  useEffect(() => {
+    // If there is no theme core config, do nothing.
+    if (!themeCore?.url) {
+      setIsThemeCoreComplete(true);
+      return;
+    }
+
+    const themeCoreLink = document.createElement('link');
+    themeCoreLink.href = themeCore.url;
+    themeCoreLink.rel = 'stylesheet';
+    themeCoreLink.dataset.themeCore = 'true';
+    themeCoreLink.onload = () => {
+      setIsThemeCoreComplete(true);
+    };
+    themeCoreLink.onerror = () => {
+      setIsThemeCoreComplete(true);
+      const otherExistingLinks = document.head.querySelectorAll('link[data-theme-core="true"]');
+      removeExistingLinks(otherExistingLinks);
+      logError(`Failed to load core theme CSS from ${themeCore.url}. Aborting.`);
+      return;
+    };
+
+    document.head.insertAdjacentElement(
+      'beforeend',
+      themeCoreLink,
+    );
+  }, [themeCore?.url, onComplete]);
+};
+
+export default useThemeCore;

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

@@ -0,0 +1,97 @@
+import { act, fireEvent, renderHook } from '@testing-library/react';
+
+import { getSiteConfig } from '../../../config';
+import { logError } from '../../../logging';
+
+import useThemeVariants from './useThemeVariants';
+
+jest.mock('../../../logging');
+
+describe('useThemeVariants', () => {
+  const onComplete = jest.fn();
+  const onDarkModeSystemPreferenceChange = jest.fn();
+  const originalWindowLocation = window.location;
+  const mockWindowLocationOrigin = jest.fn();
+
+  beforeEach(() => {
+    Object.defineProperty(window, 'location', {
+      value: {
+        get origin() {
+          return mockWindowLocationOrigin();
+        },
+      },
+    });
+    mockWindowLocationOrigin.mockReturnValue(getSiteConfig().baseUrl);
+  });
+
+  afterEach(() => {
+    document.head.innerHTML = '';
+    jest.clearAllMocks();
+  });
+
+  afterAll(() => {
+    Object.defineProperty(window, 'location', originalWindowLocation);
+  });
+
+  it('should do nothing if themeVariants is not configured', () => {
+    const themeVariants = undefined;
+    const currentThemeVariant = 'light';
+
+    renderHook(() => useThemeVariants({ themeVariants, currentThemeVariant, onComplete, onDarkModeSystemPreferenceChange }));
+    expect(document.head.querySelectorAll('link').length).toBe(0);
+  });
+
+  it('should create the links tags for each theme variant', () => {
+    const themeVariants = {
+      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',
+      },
+    };
+    const currentThemeVariant = 'light';
+
+    renderHook(() => useThemeVariants({ themeVariants, currentThemeVariant, onComplete, onDarkModeSystemPreferenceChange }));
+    const themeLinks = document.head.querySelectorAll('link');
+    expect(themeLinks.length).toBe(2);
+  });
+
+  it('should dispatch a log error if the variant theme link cannot be loaded', () => {
+    const themeVariants = {
+      light: {
+        url: 'https://cdn.jsdelivr.net/npm/@edx/brand@1.0.0/dist/light.min.css',
+      },
+    };
+    const currentThemeVariant = 'light';
+
+    renderHook(() => useThemeVariants({ themeVariants, currentThemeVariant, onComplete, onDarkModeSystemPreferenceChange }));
+    const themeLinks = document.head.querySelectorAll('link');
+
+    act(() => {
+      themeLinks.forEach((link) => fireEvent.error(link));
+    });
+    expect(logError).toHaveBeenCalledTimes(1);
+  });
+
+  it('shoud not create a new link if it already exists', () => {
+    document.head.innerHTML = '<link rel="alternate stylesheet" href="https://cdn.jsdelivr.net/npm/@openedx/brand@1.0.0/dist/light.min.css">';
+
+    const themeVariants = {
+      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',
+      },
+    };
+
+    const currentThemeVariant = 'light';
+    renderHook(() => useThemeVariants({ themeVariants, currentThemeVariant, onComplete, onDarkModeSystemPreferenceChange }));
+    const themeLinks = document.head.querySelectorAll('link');
+    const lightThemeBrandLink: HTMLAnchorElement | null = document.head.querySelector('link[data-theme-variant="light"]');
+
+    expect(themeLinks.length).toBe(2);
+    expect(lightThemeBrandLink?.rel).toContain('stylesheet');
+  });
+});

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

@@ -0,0 +1,116 @@
+import { useEffect, useState } from 'react';
+
+import { logError } from '../../../logging';
+
+import { ThemeVariants } from '../../../../types';
+
+/**
+ * A custom React hook that manages the loading of theme variant CSS files dynamically.
+ * Adds/updates a `<link>` element in the HTML document to load each theme variant's CSS, setting the
+ * non-current theme variants as "alternate" stylesheets. That is, the browser will download
+ * the CSS for the non-current theme variants, but at a lower priority than the current one.
+ * This ensures that if the theme variant is changed at runtime, the new theme's CSS will already be loaded.
+ *
+ * The hook also listens for changes in the system's preference and triggers the provided callback accordingly.
+ */
+const useThemeVariants = ({
+  themeVariants,
+  currentThemeVariant,
+  onComplete,
+  onDarkModeSystemPreferenceChange,
+}: {
+  themeVariants: ThemeVariants | undefined,
+  currentThemeVariant: string,
+  onComplete: () => void,
+  onDarkModeSystemPreferenceChange: (prefersDarkMode: boolean) => void,
+}) => {
+  const [isThemeVariantComplete, setIsThemeVariantComplete] = useState(false);
+
+  // Effect hook that listens for changes in the system's dark mode preference.
+  useEffect(() => {
+    const changeColorScheme = (colorSchemeQuery) => {
+      onDarkModeSystemPreferenceChange(colorSchemeQuery.matches);
+    };
+    const colorSchemeQuery = window.matchMedia?.('(prefers-color-scheme: dark)');
+    if (colorSchemeQuery) {
+      colorSchemeQuery.addEventListener('change', changeColorScheme);
+    }
+    return () => {
+      if (colorSchemeQuery) {
+        colorSchemeQuery.removeEventListener('change', changeColorScheme);
+      }
+    };
+  }, [onDarkModeSystemPreferenceChange]);
+
+  // Effect hook to set the theme current variant on the HTML element.
+  useEffect(() => {
+    if (currentThemeVariant && themeVariants?.[currentThemeVariant]) {
+      const htmlDataThemeVariantAttr = 'data-theme-variant';
+      document.querySelector('html')?.setAttribute(htmlDataThemeVariantAttr, currentThemeVariant);
+      return () => {
+        document.querySelector('html')?.removeAttribute(htmlDataThemeVariantAttr);
+      };
+    }
+    return () => { }; // Cleanup: no action needed when theme variant is not set
+  }, [themeVariants, currentThemeVariant]);
+
+  // Effect hook that calls `onComplete` when brand theme variant processing is complete.
+  useEffect(() => {
+    if (isThemeVariantComplete) {
+      onComplete();
+    }
+  }, [isThemeVariantComplete, onComplete]);
+
+  useEffect(() => {
+    if (!themeVariants) {
+      return;
+    }
+
+    /**
+     * Determines the value for the `rel` attribute for a given theme variant based
+     * on if its the currently applied variant.
+     */
+    const getActiveOrAlternateRel = (themeVariant: string): string => (currentThemeVariant === themeVariant ? 'stylesheet' : 'alternate stylesheet');
+
+    // Iterate over each theme variant URLs and inject them into the HTML document, if each doesn't already exist.
+    Object.entries(themeVariants).forEach(([themeVariant, { url }]) => {
+      // If the config for the theme variant does not have a URL, set the variant to complete and continue.
+      if (!url) {
+        setIsThemeVariantComplete(true);
+        return;
+      }
+
+      const existingThemeVariantLink: HTMLAnchorElement | null = document.head.querySelector(`link[href='${url}']`);
+      if (existingThemeVariantLink) {
+        existingThemeVariantLink.rel = getActiveOrAlternateRel(themeVariant);
+        existingThemeVariantLink.dataset.themeVariant = themeVariant;
+        return;
+      }
+
+      const themeVariantLink = document.createElement('link');
+      themeVariantLink.href = url;
+      themeVariantLink.rel = getActiveOrAlternateRel(themeVariant);
+      themeVariantLink.dataset.themeVariant = themeVariant;
+
+      themeVariantLink.onload = () => {
+        if (themeVariant === currentThemeVariant) {
+          setIsThemeVariantComplete(true);
+        }
+      };
+
+      themeVariantLink.onerror = () => {
+        logError(`Failed to load theme variant (${themeVariant}) CSS from ${url}. Aborting.`);
+        setIsThemeVariantComplete(true);
+      };
+
+      document.head.insertAdjacentElement(
+        'beforeend',
+        themeVariantLink,
+      );
+
+      setIsThemeVariantComplete(true);
+    });
+  }, [themeVariants, currentThemeVariant, onComplete]);
+};
+
+export default useThemeVariants;