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

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;

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

@@ -0,0 +1,54 @@
+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));
+  });
+});

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

@@ -0,0 +1,30 @@
+import { useEffect } from 'react';
+import { sendTrackEvent } from '../../../analytics';
+
+/**
+ * A React hook that tracks user's preferred color scheme (light or dark) and sends respective
+ * event to the tracking service.
+ *
+ * @memberof module:React
+ */
+const useTrackColorSchemeChoice = () => {
+  useEffect(() => {
+    const trackColorSchemeChoice = ({ matches }) => {
+      const preferredColorScheme = matches ? 'dark' : 'light';
+      sendTrackEvent('openedx.ui.frontend-base.prefers-color-scheme.selected', { preferredColorScheme });
+    };
+    const colorSchemeQuery = window.matchMedia?.('(prefers-color-scheme: dark)');
+    if (colorSchemeQuery) {
+      // send user's initial choice
+      trackColorSchemeChoice(colorSchemeQuery);
+      colorSchemeQuery.addEventListener('change', trackColorSchemeChoice);
+    }
+    return () => {
+      if (colorSchemeQuery) {
+        colorSchemeQuery.removeEventListener('change', trackColorSchemeChoice);
+      }
+    };
+  }, []);
+};
+
+export default useTrackColorSchemeChoice;

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

@@ -0,0 +1,11 @@
+/**
+ * Iterates through each given `<link>` element and removes it from the DOM.
+ * @param {HTMLLinkElement[]} existingLinks
+ */
+export const removeExistingLinks = (existingLinks) => {
+  existingLinks.forEach((link) => {
+    link.remove();
+  });
+};
+
+export const isEmptyObject = (obj) => !obj || Object.keys(obj).length === 0;

package/runtime/react/hooks/useActiveRoles.ts

@@ -0,0 +1,15 @@
+import { useState } from 'react';
+import { getActiveRoles } from '../../config';
+import { ACTIVE_ROLES_CHANGED } from '../../constants';
+import useSiteEvent from './useSiteEvent';
+
+const useActiveRoles = () => {
+  const [roles, setRoles] = useState<string[]>(getActiveRoles());
+  useSiteEvent(ACTIVE_ROLES_CHANGED, () => {
+    setRoles(getActiveRoles());
+  });
+
+  return roles;
+};
+
+export default useActiveRoles;

package/runtime/react/hooks/useActiveRouteRoleWatcher.ts

@@ -0,0 +1,31 @@
+import { useCallback, useEffect } from 'react';
+import { useMatches } from 'react-router';
+import { setActiveRouteRoles } from '../../config';
+import { isRoleRouteObject } from '../../routing';
+
+const useActiveRouteRoleWatcher = () => {
+  const matches = useMatches();
+
+  // We create this callback so we can use it right away to populate the default state value.
+  const findActiveRouteRoles = useCallback(() => {
+    // Starts with the widget roles and adds the others in.
+    const roles: string[] = [];
+
+    // Route roles
+    for (const match of matches) {
+      if (isRoleRouteObject(match)) {
+        if (!roles.includes(match.handle.role)) {
+          roles.push(match.handle.role);
+        }
+      }
+    }
+
+    return roles;
+  }, [matches]);
+
+  useEffect(() => {
+    setActiveRouteRoles(findActiveRouteRoles());
+  }, [matches, findActiveRouteRoles]);
+};
+
+export default useActiveRouteRoleWatcher;

package/runtime/react/hooks/useAppConfig.ts

@@ -0,0 +1,9 @@
+import { useContext } from 'react';
+import CurrentAppContext from '../CurrentAppContext';
+
+const useAppConfig = () => {
+  const { appConfig } = useContext(CurrentAppContext);
+  return appConfig;
+};
+
+export default useAppConfig;

package/runtime/react/hooks/useAuthenticatedUser.test.tsx

@@ -0,0 +1,41 @@
+import { act, renderHook } from '@testing-library/react';
+import { setAuthenticatedUser } from '../../auth';
+import { initializeMockApp } from '../../testing';
+import SiteProvider from '../SiteProvider';
+import useAuthenticatedUser from './useAuthenticatedUser';
+
+describe('useAuthenticatedUser', () => {
+  it('returns null when the user is anonymous', () => {
+    const { result } = renderHook(() => useAuthenticatedUser());
+    expect(result.current).toBeNull();
+  });
+
+  describe('with a user', () => {
+    const user = {
+      administrator: true,
+      email: 'admin@example.com',
+      name: 'Admin',
+      roles: ['admin'],
+      userId: 1,
+      username: 'admin-user',
+      avatar: 'http://localhost/admin.png',
+    };
+
+    beforeEach(() => {
+      initializeMockApp({
+        authenticatedUser: user,
+      });
+    });
+
+    afterEach(() => {
+      act(() => {
+        setAuthenticatedUser(null);
+      });
+    });
+
+    it('returns a User when the user exists', () => {
+      const { result } = renderHook(() => useAuthenticatedUser(), { wrapper: SiteProvider });
+      expect(result.current).toBe(user);
+    });
+  });
+});

package/runtime/react/hooks/useAuthenticatedUser.ts

@@ -0,0 +1,9 @@
+import { useContext } from 'react';
+import SiteContext from '../SiteContext';
+
+const useAuthenticatedUser = () => {
+  const { authenticatedUser } = useContext(SiteContext);
+  return authenticatedUser;
+};
+
+export default useAuthenticatedUser;