@openedx/frontend-base 1.0.0-alpha.0 → 1.0.0-alpha.2

package/tools/webpack/plugins/paragon-webpack-plugin/utils/scriptUtils.ts

@@ -1,144 +0,0 @@
-import * as parse5 from 'parse5';
-import { sources } from 'webpack';
-
-import { ParagonScriptContents } from '../../../types';
-import { getDescendantByTag, minifyScript } from './tagUtils';
-
-/**
- * Finds the insertion point for a script in an HTML document.
- *
- * @param {Object} options - The options object.
- * @param {Object} options.document - The parsed HTML document.
- * @param {string} options.originalSource - The original source code of the HTML document.
- * @throws {Error} If the body element is missing in the HTML document.
- * @return {number} The insertion point for the script in the HTML document.
- */
-function findScriptInsertionPoint({ document, originalSource }: { document: any, originalSource: string }) {
-  const bodyElement = getDescendantByTag(document, 'body');
-  if (!bodyElement) {
-    throw new Error('Missing body element in index.html.');
-  }
-
-  // determine script insertion point
-  if (bodyElement.sourceCodeLocation?.endTag) {
-    return bodyElement.sourceCodeLocation.endTag.startOffset;
-  }
-
-  // less accurate fallback
-  return originalSource.indexOf('</body>');
-}
-
-/**
- * Inserts the given script contents into the HTML document and returns a new source with the modified content.
- *
- * @param {Object} options - The options object.
- * @param {string} options.originalSource - The original HTML source.
- * @param {Object} options.scriptContents - The contents of the script to be inserted.
- * @return {sources.ReplaceSource} The new source with the modified HTML content.
- */
-export function insertScriptContentsIntoDocument({
-  originalSource,
-  scriptContents,
-}: { originalSource: string, scriptContents: ParagonScriptContents }) {
-  // parse file as html document
-  const document = parse5.parse(originalSource, {
-    sourceCodeLocationInfo: true,
-  });
-
-  // find the body element
-  const scriptInsertionPoint = findScriptInsertionPoint({
-    document,
-    originalSource,
-  });
-
-  // create Paragon script to inject into the HTML document
-  const paragonScript = `<script type="text/javascript">var PARAGON_THEME = ${JSON.stringify(scriptContents, null, 2)};</script>`;
-
-  // insert the Paragon script into the HTML document
-  const newSource = new sources.ReplaceSource(
-    new sources.RawSource(originalSource),
-    'index.html',
-  );
-  newSource.insert(scriptInsertionPoint, minifyScript(paragonScript));
-  return newSource;
-}
-
-/**
- * Creates an object with the provided version, defaults, coreCssAsset, and themeVariantCssAssets
- * and returns it. The returned object has the following structure:
- * {
- *   version: The provided version,
- *   themeUrls: {
- *     core: The provided coreCssAsset,
- *     variants: The provided themeVariantCssAssets,
- *     defaults: The provided defaults
- *   }
- * }
- *
- * @param {Object} options - The options object.
- * @param {string} options.version - The version to be added to the returned object.
- * @param {Object} options.defaults - The defaults to be added to the returned object.
- * @param {Object} options.coreCssAsset - The coreCssAsset to be added to the returned object.
- * @param {Object} options.themeVariantCssAssets - The themeVariantCssAssets to be added to the returned object.
- * @return {Object} The object with the provided version, defaults, coreCssAsset, and themeVariantCssAssets.
- */
-export function addToScriptContents({
-  version,
-  defaults,
-  coreCssAsset,
-  themeVariantCssAssets,
-}: {
-  defaults: any,
-  coreCssAsset: any,
-  themeVariantCssAssets: any,
-  version: string,
-}) {
-  return {
-    version,
-    themeUrls: {
-      core: coreCssAsset,
-      variants: themeVariantCssAssets,
-      defaults,
-    },
-  };
-}
-
-/**
- * Generates the script contents object based on the provided assets and versions.
- *
- * @param {Object} options - The options object.
- * @param {Object} options.paragonCoreCssAsset - The asset for the Paragon core CSS.
- * @param {Object} options.paragonThemeVariantCssAssets - The assets for the Paragon theme variants.
- * @param {Object} options.brandCoreCssAsset - The asset for the brand core CSS.
- * @param {Object} options.brandThemeVariantCssAssets - The assets for the brand theme variants.
- * @param {Object} options.paragonThemeCss - The Paragon theme CSS.
- * @param {string} options.paragonVersion - The version of the Paragon theme.
- * @param {Object} options.brandThemeCss - The brand theme CSS.
- * @param {string} options.brandVersion - The version of the brand theme.
- * @return {Object} The script contents object.
- */
-export function generateScriptContents({
-  paragonCoreCssAsset,
-  paragonThemeVariantCssAssets,
-  brandCoreCssAsset,
-  brandThemeVariantCssAssets,
-  paragonThemeCss,
-  paragonVersion,
-  brandThemeCss,
-  brandVersion,
-}: { paragonCoreCssAsset: any, paragonThemeVariantCssAssets: any, brandCoreCssAsset: any, brandThemeVariantCssAssets: any, paragonThemeCss: any, paragonVersion: string, brandThemeCss: any, brandVersion: string }) {
-  const scriptContents: ParagonScriptContents = {};
-  scriptContents.paragon = addToScriptContents({
-    version: paragonVersion,
-    coreCssAsset: paragonCoreCssAsset,
-    themeVariantCssAssets: paragonThemeVariantCssAssets,
-    defaults: paragonThemeCss?.defaults,
-  });
-  scriptContents.brand = addToScriptContents({
-    version: brandVersion,
-    coreCssAsset: brandCoreCssAsset,
-    themeVariantCssAssets: brandThemeVariantCssAssets,
-    defaults: brandThemeCss?.defaults,
-  });
-  return scriptContents;
-}

package/tools/webpack/plugins/paragon-webpack-plugin/utils/stylesheetUtils.ts

@@ -1,106 +0,0 @@
-import * as parse5 from 'parse5';
-import { sources } from 'webpack';
-
-import { getDescendantByTag } from './tagUtils';
-
-/**
- * Finds the insertion point for a stylesheet in an HTML document.
- *
- * @param {Object} options - The options object.
- * @param {Object} options.document - The parsed HTML document.
- * @param {string} options.source - The original source code of the HTML document.
- * @throws {Error} If the head element is missing in the HTML document.
- * @return {number} The insertion point for the stylesheet in the HTML document.
- */
-export function findStylesheetInsertionPoint({ document, source }: { document: Document, source: string }) {
-  const headElement = getDescendantByTag(document, 'head');
-  if (!headElement) {
-    throw new Error('Missing head element in index.html.');
-  }
-
-  // determine script insertion point
-  if (headElement.sourceCodeLocation?.startTag) {
-    return headElement.sourceCodeLocation.startTag.endOffset;
-  }
-
-  // less accurate fallback
-  const headTagString = '<head>';
-  const headTagIndex = source.indexOf(headTagString);
-  return headTagIndex + headTagString.length;
-}
-
-/**
- * Inserts stylesheets into an HTML document.
- *
- * @param {object} options - The options for inserting stylesheets.
- * @param {string} options.source - The HTML source code.
- * @param {object} options.urls - The URLs of the stylesheets to be inserted.
- * @param {string} options.urls.default - The URL of the default stylesheet.
- * @param {string} options.urls.brandOverride - The URL of the brand override stylesheet.
- * @return {object|undefined} The new source code with the stylesheets inserted.
- */
-export function insertStylesheetsIntoDocument({
-  source,
-  urls,
-}: { source: string, urls: any }) {
-  // parse file as html document
-  const document = parse5.parse(source, {
-    sourceCodeLocationInfo: true,
-  });
-  if (!getDescendantByTag(document, 'head')) {
-    return undefined;
-  }
-
-  const newSource = new sources.ReplaceSource(
-    new sources.RawSource(source),
-    'index.html',
-  );
-
-  // insert the brand overrides styles into the HTML document
-  const stylesheetInsertionPoint = findStylesheetInsertionPoint({
-    // @ts-expect-error Typescript complains this document instance is missing properties.  Is parse5.parse not returning a valid Document instance?
-    document,
-    // @ts-expect-error We're passing a ReplaceSource here, when we expect a string in the function.
-    source: newSource,
-  });
-
-  /**
-   * Creates a new stylesheet link element.
-   *
-   * @param {string} url - The URL of the stylesheet.
-   * @return {string} The HTML code for the stylesheet link element.
-   */
-  function createNewStylesheet(url: string) {
-    const baseLink = `<link
-      type="text/css"
-      rel="preload"
-      as="style"
-      href="${url}"
-      onload="this.rel='stylesheet';"
-      onerror="this.remove();"
-    />`;
-    return baseLink;
-  }
-
-  if (urls.default) {
-    // @ts-expect-error getDescendantByTag requires two parameters.
-    const existingDefaultLink = getDescendantByTag(`link[href='${urls.default}']`);
-    if (!existingDefaultLink) {
-      // create link to inject into the HTML document
-      const stylesheetLink = createNewStylesheet(urls.default);
-      newSource.insert(stylesheetInsertionPoint, stylesheetLink);
-    }
-  }
-
-  if (urls.brandOverride) {
-    // @ts-expect-error getDescendantByTag requires two parameters.
-    const existingBrandLink = getDescendantByTag(`link[href='${urls.brandOverride}']`);
-    if (!existingBrandLink) {
-      // create link to inject into the HTML document
-      const stylesheetLink = createNewStylesheet(urls.brandOverride);
-      newSource.insert(stylesheetInsertionPoint, stylesheetLink);
-    }
-  }
-
-  return newSource;
-}

package/tools/webpack/plugins/paragon-webpack-plugin/utils/tagUtils.ts

@@ -1,54 +0,0 @@
-/**
- * Recursively searches for a descendant node with the specified tag name.
- *
- * @param {Object} node - The root node to start the search from.
- * @param {string} tag - The tag name to search for.
- * @return {Object|null} The first descendant node with the specified tag name, or null if not found.
- */
-export function getDescendantByTag(node: any, tag: string): any {
-  for (let i = 0; i < node.childNodes?.length; i++) {
-    if (node.childNodes[i].tagName === tag) {
-      return node.childNodes[i];
-    }
-    const result = getDescendantByTag(node.childNodes[i], tag);
-    if (result) {
-      return result;
-    }
-  }
-  return null;
-}
-
-/**
- * Replaces a wildcard keyword in a URL with a local version.
- *
- * @param {Object} options - The options object.
- * @param {string} options.url - The URL to substitute the keyword in.
- * @param {string} options.wildcardKeyword - The wildcard keyword to replace.
- * @param {string} options.localVersion - The local version to substitute the keyword with.
- * @return {string} The URL with the wildcard keyword substituted with the local version,
- *                 or the original URL if no substitution is needed.
- */
-export function handleVersionSubstitution({ url, wildcardKeyword, localVersion }: { url: string | undefined, wildcardKeyword: string, localVersion: string }) {
-  if (!url || !url.includes(wildcardKeyword) || !localVersion) {
-    return url;
-  }
-  return url.replaceAll(wildcardKeyword, localVersion);
-}
-
-/**
- * Minifies a script by removing unnecessary whitespace and line breaks.
- *
- * @param {string} script - The script to be minified.
- * @return {string} The minified script.
- */
-export function minifyScript(script: string) {
-  return script
-    .replace(/>[\r\n ]+</g, '><')
-    .replace(/(<.*?>)|\s+/g, (m, $1) => {
-      if ($1) {
-        return $1;
-      }
-      return ' ';
-    })
-    .trim();
-}

package/tools/webpack/types.ts

@@ -1,69 +0,0 @@
-/**
- * The metadata about the core Paragon theme CSS
- */
-export interface ParagonThemeCssAsset {
-  filePath: string,
-  entryName: string,
-  outputChunkName: string,
-}
-
-export interface ParagonThemeVariantCssAsset {
-  filePath: string,
-  entryName: string,
-  outputChunkName: string,
-}
-
-export interface ParagonThemeCss {
-  core: ParagonThemeCssAsset | undefined,
-  variants: Record<string, ParagonThemeVariantCssAsset>,
-  defaults: object,
-}
-
-// This isn't perfect, as it implies having neither url nor urls would be valid.  Feel free to improve it so that one is required.
-export interface ParagonThemeUrlsVariant {
-  url?: string,
-  urls?: Record<string, string | undefined>,
-}
-
-export interface ParagonThemeUrls {
-  core: ParagonThemeUrlsVariant,
-  defaults: Record<string, string>,
-  variants: Record<string, ParagonThemeUrlsVariant>,
-}
-
-export interface ParagonThemeUrlsFile {
-  themeUrls: {
-    core: {
-      paths: {
-        default: string,
-        minified: string,
-      },
-    },
-    defaults: Record<string, string>,
-    variants: Record<string, {
-      paths: {
-        default: string,
-        minified: string,
-      },
-    }>,
-  },
-}
-
-export interface ParagonScriptContents {
-  paragon?: {
-    version: string,
-    themeUrls: {
-      core: any,
-      variants: any,
-      defaults: any,
-    },
-  },
-  brand?: {
-    version: string,
-    themeUrls: {
-      core: any,
-      variants: any,
-      defaults: any,
-    },
-  },
-}

package/tools/webpack/utils/getLocalAliases.ts

@@ -1,65 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-
-/*
-This function reads in a 'module.config.js' file if it exists and uses its contents to define
-a set of webpack resolve.alias aliases for doing local development of application dependencies.
-It reads the package.json file of the dependency to determine if it has any peer dependencies, and
-then forces those peer dependencies to be resolved with the application's version.  Primarily, this
-is useful for making sure there's only one version of those dependencies loaded at once, which is a
-problem with both react and react-intl.
-
-The module.config.js file should have the form:
-
-{
-  localModules: [
-    { moduleName: 'nameOfPackage', dir: '../path/to/repo', dist: '/path/to/dist/in/repo' },
-    ... others...
-  ],
-}
-
-Some working examples, as of the time of this writing:
-
-{ moduleName: '@openedx/paragon/scss', dir: '../paragon', dist: 'scss' }
-{ moduleName: '@openedx/paragon', dir: '../paragon', dist: 'dist' }
-{ moduleName: '@openedx/frontend-base', dir: '../frontend-base', dist: 'dist' }
-
-*/
-export default function getLocalAliases() {
-  const aliases: Record<string, string> = {};
-
-  try {
-    const moduleConfigPath = path.resolve(process.cwd(), 'module.config.js');
-    if (!fs.existsSync(moduleConfigPath)) {
-      console.log('No local module configuration file found. This is fine.\n');
-      return aliases;
-    }
-
-    const { localModules } = require(moduleConfigPath);
-
-    let allPeerDependencies: string[] = [];
-    const excludedPeerPackages: string[] = [];
-    if (localModules.length > 0) {
-      console.info('Resolving modules from local directories via module.config.js.');
-    }
-    localModules.forEach(({ moduleName, dir, dist = '' }: { moduleName: string, dir: string, dist?: string }) => {
-      console.info(`Using local version of ${moduleName} from ${dir}/${dist}.`);
-
-      const { peerDependencies = {}, name } = require(path.resolve(process.cwd(), dir, 'package.json'));
-      allPeerDependencies = allPeerDependencies.concat(Object.keys(peerDependencies));
-      aliases[moduleName] = path.resolve(process.cwd(), dir, dist);
-      excludedPeerPackages.push(name);
-    });
-
-    allPeerDependencies = allPeerDependencies.filter((dep) => !excludedPeerPackages.includes(dep));
-
-    allPeerDependencies.forEach((dep) => {
-      aliases[dep] = path.resolve(process.cwd(), 'node_modules', dep);
-    });
-  } catch (e) {
-    console.error(e);
-    console.error('Error in module.config.js parsing. module.config.js will be ignored.');
-    return {};
-  }
-  return aliases;
-}

package/tools/webpack/utils/getPublicPath.ts

@@ -1,3 +0,0 @@
-export default function getPublicPath(defaultPath = 'auto') {
-  return process.env.PUBLIC_PATH ?? defaultPath;
-}

package/tools/webpack/utils/getResolvedSiteConfigPath.ts

@@ -1,28 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-
-export default function getResolvedSiteConfigPath(defaultFilename: string) {
-  const siteConfigPath = process.env.SITE_CONFIG_PATH;
-
-  if (siteConfigPath !== undefined) {
-    // We assume siteConfigPath is a relative path.
-    const absolutePath = path.resolve(process.cwd(), siteConfigPath);
-    if (fs.existsSync(absolutePath)) {
-      // If it's a valid absolute path when joined with the current working directory, return that.
-      return absolutePath;
-    }
-  }
-  // Otherwise, return our default site config file path.
-  const defaultPath = path.resolve(process.cwd(), defaultFilename);
-  if (fs.existsSync(defaultPath)) {
-    return defaultPath;
-  }
-
-  // They supplied something but we can't figure out what it is.  Exit with an error.
-  if (siteConfigPath !== undefined) {
-    console.error(`Invalid site config path (${siteConfigPath} specified as an environment variable. Aborting.`);
-  } else {
-    console.error(`Default site config file (${defaultPath}) does not exist. Aborting.`);
-  }
-  process.exit(1);
-}

package/tools/webpack/utils/paragonUtils.ts

@@ -1,152 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { Chunk } from 'webpack';
-import { ParagonThemeCss, ParagonThemeUrlsFile } from '../types';
-
-/**
- * Retrieves the name of the brand package from the given directory.
- *
- * @param {string} dir - The directory path containing the package.json file.
- * @return {string} The name of the brand package, or an empty string if not found.
- */
-function getBrandPackageName(dir: string) {
-  const appDependencies = JSON.parse(fs.readFileSync(path.resolve(dir, 'package.json'), 'utf-8')).dependencies;
-  return Object.keys(appDependencies).find((key) => /@(open)?edx\/brand/.exec(key)) ?? '';
-}
-
-/**
- * Attempts to extract the Paragon version from the `node_modules` of
- * the consuming application.
- *
- * @param {string} dir Path to directory containing `node_modules`.
- * @returns {string} Paragon dependency version of the consuming application
- */
-export function getParagonVersion(dir: string, { isBrandOverride = false } = {}) {
-  const npmPackageName = isBrandOverride ? getBrandPackageName(dir) : '@openedx/paragon';
-  const pathToPackageJson = `${dir}/node_modules/${npmPackageName}/package.json`;
-  if (!fs.existsSync(pathToPackageJson)) {
-    return undefined;
-  }
-  return JSON.parse(fs.readFileSync(pathToPackageJson, 'utf-8')).version;
-}
-
-/**
- * Attempts to extract the Paragon theme CSS from the locally installed `@openedx/paragon` package.
- * @param {string} dir Path to directory containing `node_modules`.
- * @param {boolean} isBrandOverride
- * @returns {ParagonThemeCss}
- */
-export function getParagonThemeCss(dir: string, { isBrandOverride = false } = {}): ParagonThemeCss | undefined {
-  const npmPackageName = isBrandOverride ? getBrandPackageName(dir) : '@openedx/paragon';
-  const pathToParagonThemeOutput = path.resolve(dir, 'node_modules', npmPackageName, 'dist', 'theme-urls.json');
-
-  if (!fs.existsSync(pathToParagonThemeOutput)) {
-    return undefined;
-  }
-  const paragonConfig: ParagonThemeUrlsFile = JSON.parse(fs.readFileSync(pathToParagonThemeOutput, 'utf-8'));
-  const {
-    core: themeCore,
-    variants: themeVariants,
-    defaults,
-  } = paragonConfig?.themeUrls || {};
-
-  const pathToCoreCss = path.resolve(dir, 'node_modules', npmPackageName, 'dist', themeCore.paths.minified);
-  const coreCssExists = fs.existsSync(pathToCoreCss);
-
-  const themeVariantResults = Object.entries(themeVariants || {}).reduce((themeVariantAcc, [themeVariant, value]) => {
-    const themeVariantCssDefault = path.resolve(dir, 'node_modules', npmPackageName, 'dist', value.paths.default);
-    const themeVariantCssMinified = path.resolve(dir, 'node_modules', npmPackageName, 'dist', value.paths.minified);
-
-    if (!fs.existsSync(themeVariantCssDefault) && !fs.existsSync(themeVariantCssMinified)) {
-      return themeVariantAcc;
-    }
-
-    return ({
-      ...themeVariantAcc,
-      [themeVariant]: {
-        filePath: themeVariantCssMinified,
-        entryName: isBrandOverride ? `brand.theme.variants.${themeVariant}` : `paragon.theme.variants.${themeVariant}`,
-        outputChunkName: isBrandOverride ? `brand-theme-variants-${themeVariant}` : `paragon-theme-variants-${themeVariant}`,
-      },
-    });
-  }, {});
-
-  if (!coreCssExists || Object.keys(themeVariantResults).length === 0) {
-    return undefined;
-  }
-
-  const coreResult = {
-    filePath: path.resolve(dir, pathToCoreCss),
-    entryName: isBrandOverride ? 'brand.theme.core' : 'paragon.theme.core',
-    outputChunkName: isBrandOverride ? 'brand-theme-core' : 'paragon-theme-core',
-  };
-
-  return {
-    core: fs.existsSync(pathToCoreCss) ? coreResult : undefined,
-    variants: themeVariantResults,
-    defaults,
-  };
-}
-
-/**
- * @typedef CacheGroup
- * @property {string} type The type of cache group.
- * @property {string|function} name The name of the cache group.
- * @property {function} chunks A function that returns true if the chunk should be included in the cache group.
- * @property {boolean} enforce If true, this cache group will be created even if it conflicts with default cache groups.
- */
-
-/**
- * @param {ParagonThemeCss} paragonThemeCss The Paragon theme CSS metadata.
- * @returns {Object.<string, CacheGroup>} The cache groups for the Paragon theme CSS.
- */
-export function getParagonCacheGroups(paragonThemeCss: ParagonThemeCss | undefined) {
-  if (!paragonThemeCss) {
-    return {};
-  }
-  const cacheGroups: Record<string, { type: string, name: string, chunks: (chunk: Chunk) => boolean, enforce: boolean }> = {};
-
-  if (paragonThemeCss.core !== undefined) {
-    const { core } = paragonThemeCss;
-    cacheGroups[paragonThemeCss.core.outputChunkName] = {
-      type: 'css/mini-extract',
-      name: paragonThemeCss.core.outputChunkName,
-      chunks: (chunk: Chunk) => chunk.name === core.entryName,
-      enforce: true,
-    };
-  }
-
-  Object.values(paragonThemeCss.variants).forEach(({ entryName, outputChunkName }) => {
-    cacheGroups[outputChunkName] = {
-      type: 'css/mini-extract',
-      name: outputChunkName,
-      chunks: (chunk: Chunk) => chunk.name === entryName,
-      enforce: true,
-    };
-  });
-  return cacheGroups;
-}
-
-/**
- * @param {ParagonThemeCss} paragonThemeCss The Paragon theme CSS metadata.
- * @returns {Object.<string, string>} The entry points for the Paragon theme CSS. Example: ```
- * {
- *   "paragon.theme.core": "/path/to/node_modules/@openedx/paragon/dist/core.min.css",
- *   "paragon.theme.variants.light": "/path/to/node_modules/@openedx/paragon/dist/light.min.css"
- * }
- * ```
- */
-export function getParagonEntryPoints(paragonThemeCss: ParagonThemeCss | undefined) {
-  if (!paragonThemeCss) {
-    return {};
-  }
-
-  const entryPoints: Record<string, string> = {};
-  if (paragonThemeCss.core !== undefined) {
-    entryPoints[paragonThemeCss.core.entryName] = path.resolve(process.cwd(), paragonThemeCss.core.filePath);
-  }
-  Object.values(paragonThemeCss.variants).forEach(({ filePath, entryName }) => {
-    entryPoints[entryName] = path.resolve(process.cwd(), filePath);
-  });
-  return entryPoints;
-}