@openedx/frontend-base 1.0.0-alpha.12 → 1.0.0-alpha.13

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

@@ -1,179 +0,0 @@
-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

@@ -1,107 +0,0 @@
-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/useThemeCore.test.ts

@@ -1,65 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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

@@ -1,97 +0,0 @@
-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

@@ -1,116 +0,0 @@
-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;

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

@@ -1,54 +0,0 @@
-import { renderHook } from '@testing-library/react';
-import { sendTrackEvent } from '../../../analytics';
-import useTrackColorSchemeChoice from './useTrackColorSchemeChoice';
-
-jest.mock('../../../analytics');
-
-const mockAddEventListener = jest.fn();
-const mockRemoveEventListener = jest.fn();
-let matchesMock;
-
-Object.defineProperty(window, 'matchMedia', {
-  value: jest.fn(() => ({
-    addEventListener: mockAddEventListener,
-    removeEventListener: mockRemoveEventListener,
-    matches: matchesMock,
-  })),
-});
-
-describe('useTrackColorSchemeChoice hook', () => {
-  afterEach(() => {
-    mockAddEventListener.mockClear();
-    mockRemoveEventListener.mockClear();
-    jest.mocked(sendTrackEvent).mockClear();
-  });
-
-  it('sends dark preferred color schema event if query matches', async () => {
-    matchesMock = true;
-    renderHook(() => useTrackColorSchemeChoice());
-
-    expect(sendTrackEvent).toHaveBeenCalledTimes(1);
-    expect(sendTrackEvent).toHaveBeenCalledWith(
-      'openedx.ui.frontend-base.prefers-color-scheme.selected',
-      { preferredColorScheme: 'dark' },
-    );
-  });
-
-  it('sends light preferred color schema event if query does not match', async () => {
-    matchesMock = false;
-    renderHook(() => useTrackColorSchemeChoice());
-
-    expect(sendTrackEvent).toHaveBeenCalledTimes(1);
-    expect(sendTrackEvent).toHaveBeenCalledWith(
-      'openedx.ui.frontend-base.prefers-color-scheme.selected',
-      { preferredColorScheme: 'light' },
-    );
-  });
-
-  it('adds change event listener to matchMedia query', async () => {
-    renderHook(() => useTrackColorSchemeChoice());
-
-    expect(mockAddEventListener).toHaveBeenCalledTimes(1);
-    expect(mockAddEventListener).toHaveBeenCalledWith('change', expect.any(Function));
-  });
-});