fixup! feat!: Paragon 23 and External CSS support

Author: arbrandes

docs/how_tos/theming.md

@@ -73,21 +73,21 @@ better understanding.
 
 ### Configuration options
 
-To enable `@openedx/brand-openedx` overrides, the `theme` site
-configuration setting may be configured with the following:
-
-| Property                            | Data Type | Description                                                                                                     |
-| ----------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------- |
-| `core`                              | Object    | Metadata about the core styles from `@openedx/brand-openedx`.                                                   |
-| `core.url`                          | String    | URL for the `core.css` file from `@openedx/brand-openedx`.                                                      |
-| `defaults`                          | Object    | Mapping of theme variants to Paragon's default supported light and dark theme variants.                         |
-| `defaults.light`                    | String    | Default `light` theme variant from the theme variants in the `variants` object.                                 |
-| `defaults.dark`                     | String    | Default `dark` theme variant from the theme variants in the `variants` object.                                  |
-| `variants`                          | Object    | Metadata about each supported theme variant.                                                                    |
-| `variants.light`                    | Object    | Metadata about the light theme variant styles from `@openedx/brand-openedx`.                                    |
-| `variants.light.url`                | String    | URL for the `light.css` file from `@openedx/brand-openedx`.                                                     |
-| `variants.dark`                     | Object    | Metadata about the dark theme variant styles from `@openedx/brand-openedx`.                                     |
-| `variants.dark.url`                 | String    | URL for the `dark.css` file from `@openedx/brand-openedx`.                                                      |
+To use a custom theme, the `theme` site configuration setting may be configured
+with the following:
+
+| Property                            | Data Type | Description                                                                             |
+| ----------------------------------- | --------- | --------------------------------------------------------------------------------------- |
+| `core`                              | Object    | Metadata about the core theme's core styles .                                           |
+| `core.url`                          | String    | URL for the theme's core stylesheet.                                                    |
+| `defaults`                          | Object    | Mapping of theme variants to Paragon's default supported light and dark theme variants. |
+| `defaults.light`                    | String    | Default `light` theme variant from the theme variants in the `variants` object.         |
+| `defaults.dark`                     | String    | Default `dark` theme variant from the theme variants in the `variants` object.          |
+| `variants`                          | Object    | Metadata about each supported theme variant.                                            |
+| `variants.light`                    | Object    | Metadata about the theme's light variant styles.                                        |
+| `variants.light.url`                | String    | URL for the theme's light variant stylesheet.                                           |
+| `variants.dark`                     | Object    | Metadata about the theme's dark variant styles.                                         |
+| `variants.dark.url`                 | String    | URL for the theme's dark variant styles.                                                |
 
 The `dark` theme variant is optional.
 

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

@@ -158,7 +158,7 @@ describe('useTheme', () => {
     unmount();
   });
 
-  it('should return themeVariant undefined if can not configure the default theme or fallback in the light theme', () => {
+  it('should return themeVariant undefined if a default variant cannot be configured', () => {
     jest.spyOn(config, 'getSiteConfig').mockReturnValue({
       ...baseSiteConfig,
       theme: {
@@ -192,7 +192,10 @@ describe('useTheme', () => {
       ...baseSiteConfig,
       theme: {
         ...theme,
-        defaults: { dark: 'dark' },
+        defaults: {
+          light: 'light',
+          dark: 'dark'
+        },
         variants: {
           light: theme.variants.light,
           green: { url: 'green-url' }

runtime/react/hooks/theme/useTheme.ts

@@ -99,16 +99,16 @@ const useTheme = () => {
     core: themeCore,
     defaults: themeVariantDefaults,
     variants: themeVariants,
-  } = themeConfig ?? {};
+  } = themeConfig;
   const initialThemeState = {
     isThemeLoaded: false,
     themeVariant: getDefaultThemeVariant(themeVariants, themeVariantDefaults)?.name,
   };
   const [themeState, dispatch] = useReducer(themeReducer, initialThemeState);
 
-  const [isThemeCoreLoaded, setIsthemeCoreLoaded] = useState(false);
+  const [isThemeCoreLoaded, setIsThemeCoreLoaded] = useState(false);
   const onLoadThemeCore = useCallback(() => {
-    setIsthemeCoreLoaded(true);
+    setIsThemeCoreLoaded(true);
   }, []);
 
   const [hasLoadedThemeVariants, setHasLoadedThemeVariants] = useState(false);

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

@@ -12,8 +12,8 @@ describe('useThemeConfig', () => {
   });
 
   it.each([
-    [undefined, undefined],
-    [{}, undefined],
+    [undefined, {}],
+    [{}, {}],
   ])('handles when `siteConfig.theme` is not present (%s)', (theme, expectedURLConfig) => {
     jest.spyOn(config, 'getSiteConfig').mockReturnValue({
       ...baseSiteConfig,
@@ -24,21 +24,34 @@ describe('useThemeConfig', () => {
   });
 
   describe('when `siteConfig.theme` is present', () => {
-    it('returns expected undefined when variants are not present', () => {
+    it('returns empty object if at least one variant is not defined', () => {
       jest.spyOn(config, 'getSiteConfig').mockReturnValue({
         ...baseSiteConfig,
         theme: {
-          core: {
-            url: 'brand-core.css',
-          },
-          defaults: {
-            light: 'light',
-          },
-          variants: {},
+          core: undefined,
+          variants: {}
+        },
+      });
+      const { result } = renderHook(() => useThemeConfig());
+      expect(result.current).toStrictEqual({});
+    });
+    it('returns expected object when nothing but the light variant is defined', () => {
+      jest.spyOn(config, 'getSiteConfig').mockReturnValue({
+        ...baseSiteConfig,
+        theme: {
+          variants: {
+            light: { url: 'light.css' },
+          }
         },
       });
       const { result } = renderHook(() => useThemeConfig());
-      expect(result.current).toBe(undefined);
+      expect(result.current).toStrictEqual({
+        core: undefined,
+        defaults: undefined,
+        variants: {
+          light: { url: 'light.css' },
+        }
+      });
     });
 
     it('returns expected object when configuration is valid', () => {
@@ -59,21 +72,19 @@ describe('useThemeConfig', () => {
         },
       });
       const { result } = renderHook(() => useThemeConfig());
-      expect(result.current).toEqual(
-        expect.objectContaining({
-          core: {
-            url: 'core.css',
-          },
-          defaults: {
-            light: 'light',
-          },
-          variants: {
-            light: {
-              url: 'light.css',
-            },
+      expect(result.current).toStrictEqual({
+        core: {
+          url: 'core.css',
+        },
+        defaults: {
+          light: 'light',
+        },
+        variants: {
+          light: {
+            url: 'light.css',
           },
-        }),
-      );
+        },
+      });
     });
   });
 });

runtime/react/hooks/theme/useThemeConfig.ts

@@ -1,11 +1,14 @@
 import { useMemo } from 'react';
 
-import { isEmptyObject } from './utils';
+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();
@@ -14,11 +17,11 @@ import { getSiteConfig } from '../../../config';
  *   console.log(themeConfig.variants['dark'].url); // Outputs the URL of the dark theme variant CSS
  * }
  */
-const useThemeConfig = () => useMemo(() => {
+const useThemeConfig = (): Theme => useMemo(() => {
   const { theme } = getSiteConfig();
 
-  if (!theme?.core?.url || isEmptyObject(theme.defaults) || isEmptyObject(theme.variants)) {
-    return;
+  if (!theme || (isEmptyObject(theme.core) && isEmptyObject(theme.variants))) {
+    return {};
   }
 
   return {

types.ts

@@ -94,7 +94,7 @@ export type ThemeVariants = Record<string, ThemeVariant>;
 
 export interface Theme {
   core?: ThemeVariant,
-  defaults?: Partial<ThemeDefaults>,
+  defaults?: ThemeDefaults,
   variants?: ThemeVariants,
 }