fixup! feat!: Paragon 23 and External CSS support

Author: arbrandes

docs/how_tos/images/paragon-theme-loader.png

@@ -9,8 +9,8 @@
 >
 > Information on the design tokens project:
 >
-> - <https://github.com/openedx/paragon/blob/master/docs/decisions/0019-scaling-styles-with-design-tokens.rst>
-> - <https://github.com/openedx/paragon/tree/alpha?tab=readme-ov-file#design-tokens>
+> - <https://github.com/openedx/paragon/blob/release-23.x/docs/decisions/0019-scaling-styles-with-design-tokens.rst>
+> - <https://github.com/openedx/paragon/tree/release-23.x?tab=readme-ov-file#design-tokens>
 
 ## Overview
 
@@ -19,19 +19,20 @@ theming with Paragon by loading branded CSS externally (e.g., from a CDN).
 
 To do this, configured URLs pointing to relevant CSS files from
 `@openedx/brand-openedx` are loaded and injected to the HTML document at
-runtime. This differs from importing the styles from `@openedx/brand-openedx`
-directly, which includes these styles in the application's production assets.
+runtime. This differs from the deprecated method of importing the styles from
+`@openedx/brand-openedx` directly, which includes these styles in the
+application's production assets.
 
 This override mechanism works by compiling the design tokens defined in
 `@openedx/brand-openedx` with the core Paragon tokens to generate overrides to
 Paragon's default CSS variables and then compiling the output CSS with any SCSS
 theme customizations not possible through a design token override.
 
 The CSS urls for `@openedx/brand-openedx` overrides will be applied after the
-core Paragon theme urls load, thus overriding any previously set CSS variables
+Paragon base styles load, thus overriding any previously set CSS variables
 and/or styles.
 
-By serving brand CSS loaded externally, consuming applications of Paragon no
+By loading a theme's CSS externally, consuming applications of Paragon no
 longer need to be responsible for compiling the brand SCSS to CSS themselves
 and instead use a pre-compiled CSS file. In doing so, this allows making
 changes to the site theme without needing to necessarily re-build and re-deploy
@@ -68,51 +69,42 @@ supports having multiple or alternative `light` and/or `dark` theme variants.
 You can see the [Configuration options](#configuration-options) example for
 better understanding.
 
-## Technical architecture
-
-![overview of paragon theme loader](./images/paragon-theme-loader.png "Paragon theme loader")
-
 ## Development
 
 ### Configuration options
 
-To enable `@openedx/brand-openedx` overrides, the `paragonThemeUrls` site
+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.urls`                         | Object    | URL(s) for the `core.css` files from `@openedx/brand-openedx`.                                                  |
-| `core.urls.brandOverride`           | String    | URL for the `core.css` file 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.urls`               | Object    | URL(s) for the `light.css` files from `@openedx/brand-openedx`.                                                 |
-| `variants.light.urls.brandOverride` | String    | URL for the `light.css` file 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.urls`                | Object    | URL(s) for the `dark.css` files from `@openedx/brand-openedx`.                                                  |
-| `variants.dark.urls.brandOverride`  | String    | URL for the `dark.css` file from `@openedx/brand-openedx`.                                                      |
+| `variants.dark.url`                 | String    | URL for the `dark.css` file from `@openedx/brand-openedx`.                                                      |
 
-The `dark` theme variant options are optional.
+The `dark` theme variant is optional.
 
 A simple example:
 
 ```ts
 const siteConfig: SiteConfig = {
-  paragonThemeUrls: {
+  theme: {
     core: {
-      urls: {
-        brandOverride: "https://cdn.jsdelivr.net/npm/@my-brand/[email protected]/dist/core.min.css",
-      },
+      url: "https://cdn.jsdelivr.net/npm/@my-org/[email protected]/dist/core.min.css",
     },
     defaults: {
       light: "light",
     },
     variants: {
       light: {
-        brandOverride: "https://cdn.jsdelivr.net/npm/@my-brand/brand[email protected]/dist/light.min.css",
+        url: "https://cdn.jsdelivr.net/npm/@my-org/theme[email protected]/dist/light.min.css",
       },
     },
   },
@@ -125,41 +117,29 @@ A complete example, including custom variants:
 const siteConfig: SiteConfig = {
   paragonThemeUrls: {
     core: {
-      urls: {
-        brandOverride: "https://cdn.jsdelivr.net/npm/@my-brand/[email protected]/dist/core.min.css",
-      },
+      url: "https://cdn.jsdelivr.net/npm/@my-org/[email protected]/dist/core.min.css",
     },
     defaults: {
       light: "light",
       dark: "dark",
     },
     variants: {
       light: {
-        urls: {
-          brandOverride: "https://cdn.jsdelivr.net/npm/@my-brand/[email protected]/dist/light.min.css",
-        },
+        url: "https://cdn.jsdelivr.net/npm/@my-org/[email protected]/dist/light.min.css",
       },
-      // Configure optional dark mode
+      // Optional dark mode
       dark: {
-        urls: {
-          brandOverride: "https://cdn.jsdelivr.net/npm/@my-brand/[email protected]/dist/dark.min.css",
-        },
+        url: "https://cdn.jsdelivr.net/npm/@my-org/[email protected]/dist/dark.min.css",
       },
       // Configure any extra theme using a custom @openedx/brand-openedx package
       green: {
-        urls: {
-          brandOverride: "https://cdn.jsdelivr.net/npm/@my-brand/[email protected]/dist/green.min.css",
-        },
+        url: "https://cdn.jsdelivr.net/npm/@my-org/[email protected]/dist/green.min.css",
       },
       red: {
-        urls: {
-          brandOverride: "https://cdn.jsdelivr.net/npm/@my-brand/[email protected]/dist/red.min.css",
-        },
+        url: "https://cdn.jsdelivr.net/npm/@my-org/[email protected]/dist/red.min.css",
       },
       "high-contrast-dark": {
-        urls: {
-          brandOverride: "https://cdn.jsdelivr.net/npm/@my-brand/[email protected]/dist/high-contrast-dark.min.css",
-        },
+        url: "https://cdn.jsdelivr.net/npm/@my-org/[email protected]/dist/high-contrast-dark.min.css",
       },
     },
   },

docs/how_tos/theming.md

@@ -112,17 +112,17 @@ const useParagonTheme = () => {
   };
   const [themeState, dispatch] = useReducer(paragonThemeReducer, initialParagonThemeState);
 
-  const [isCoreThemeLoaded, setIsCoreThemeLoaded] = useState(false);
+  const [isThemeCoreLoaded, setIsthemeCoreLoaded] = useState(false);
   const onLoadThemeCore = useCallback(() => {
-    setIsCoreThemeLoaded(true);
+    setIsthemeCoreLoaded(true);
   }, []);
 
   const [hasLoadedThemeVariants, setHasLoadedThemeVariants] = useState(false);
   const onLoadThemeVariants = useCallback(() => {
     setHasLoadedThemeVariants(true);
   }, []);
 
-  // load the core theme CSS
+  // load the theme's core CSS
   useParagonThemeCore({
     themeCore,
     onComplete: onLoadThemeCore,
@@ -165,15 +165,15 @@ const useParagonTheme = () => {
     }
 
     // Return early if neither the core theme CSS nor any theme variant CSS is loaded.
-    if (!isCoreThemeLoaded || !hasLoadedThemeVariants) {
+    if (!isThemeCoreLoaded || !hasLoadedThemeVariants) {
       return;
     }
 
     // All application theme URLs are loaded
     dispatch(paragonThemeActions.setParagonThemeLoaded(true));
   }, [
     themeState.isThemeLoaded,
-    isCoreThemeLoaded,
+    isThemeCoreLoaded,
     hasLoadedThemeVariants,
     themeCore?.urls,
     themeVariants,

runtime/react/hooks/paragon/useParagonTheme.ts

@@ -4,19 +4,9 @@ import { logError } from '../../../logging';
 import { removeExistingLinks } from './utils';
 
 /**
- * Custom React hook that manages the loading and updating of the core Paragon theme CSS and the brand override
- * theme CSS. It ensures that the core theme CSS (both default and brand override) is added to the document
- * `<head>` as `<link>` elements.
- *
- * The function logs and handles fallback logic in case the core theme fails to load.
- *
- * @memberof module:React
- *
- * @param {Object} args - The arguments object containing theme and callback information.
- * @param {Object} args.themeCore - The core theme configuration.
- * @param {string} [args.themeCore.urls.brandOverride] - The URL to the brand override theme CSS (optional).
- * @param {Function} args.onComplete - A callback function that is called once both the core Paragon (default)
- * theme and brand override theme (if provided) are complete.
+ * 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 useParagonThemeCore = ({
   themeCore,
@@ -37,15 +27,6 @@ const useParagonThemeCore = ({
       return;
     }
 
-    const brandCoreLink: HTMLAnchorElement | null = document.head.querySelector(`link[href='${themeCore.urls.brandOverride}']`);
-    if (brandCoreLink) {
-      brandCoreLink.rel = 'stylesheet';
-      brandCoreLink.removeAttribute('as');
-      brandCoreLink.dataset.brandThemeCore = 'true';
-      setIsBrandThemeCoreComplete(true);
-      return;
-    }
-
     if (themeCore.urls.brandOverride) {
       const brandCoreThemeLink = document.createElement('link');
       brandCoreThemeLink.href = themeCore.urls.brandOverride;

runtime/react/hooks/paragon/useParagonThemeCore.ts

@@ -18,6 +18,7 @@ const messages = {
   ru: {},
   th: {},
   uk: {},
+  vi: {},
 };
 
 export default messages;

runtime/testing/mockMessages.ts

@@ -1,5 +1,5 @@
-@use "@openedx/paragon/dist/core.min.css" as paragonCore;
-@use "@openedx/paragon/dist/light.min.css" as paragonLight;
+@use "@openedx/paragon/dist/core.min.css";
+@use "@openedx/paragon/dist/light.min.css";
 
 .flex-basis-0 {
   flex-basis: 0 !important;