@openedx/paragon 22.4.0 → 23.0.0-alpha.1

package/lib/build-tokens.js

@@ -0,0 +1,119 @@
+const path = require('path');
+const minimist = require('minimist');
+const { StyleDictionary, colorTransform, createCustomCSSVariables } = require('../tokens/style-dictionary');
+const { createIndexCssFile } = require('../tokens/utils');
+
+/**
+ * Builds tokens for CSS styles from JSON source files.
+ *
+ * @param {string[]} commandArgs - Command line arguments for building tokens.
+ * @param {string} [commandArgs.build-dir='./build/'] - The directory where the build output will be placed.
+ * @param {string} [commandArgs.source] - The source directory containing JSON token files.
+ * @param {boolean} [commandArgs.source-tokens-only=false] - Indicates whether to include only source tokens.
+ * @param {string|string[]} [commandArgs.themes=['light']] - The themes (variants) for which to build tokens.
+ */
+async function buildTokensCommand(commandArgs) {
+  const defaultParams = {
+    themes: ['light'],
+    'build-dir': './build/',
+  };
+
+  const alias = {
+    'build-dir': 'b',
+    themes: 't',
+  };
+
+  const {
+    'build-dir': buildDir,
+    source: tokensSource,
+    'source-tokens-only': hasSourceTokensOnly,
+    themes,
+  } = minimist(commandArgs, { alias, default: defaultParams, boolean: 'source-tokens-only' });
+
+  const coreConfig = {
+    include: [path.resolve(__dirname, '../tokens/src/core/**/*.json')],
+    source: tokensSource ? [`${tokensSource}/core/**/*.json`] : [],
+    platforms: {
+      css: {
+        prefix: 'pgn',
+        transformGroup: 'css',
+        // NOTE: buildPath must end with a slash
+        buildPath: buildDir.slice(-1) === '/' ? buildDir : `${buildDir}/`,
+        files: [
+          {
+            format: 'css/custom-variables',
+            destination: 'core/variables.css',
+            filter: hasSourceTokensOnly ? 'isSource' : undefined,
+            options: {
+              outputReferences: !hasSourceTokensOnly,
+            },
+          },
+          {
+            format: 'css/custom-media-breakpoints',
+            destination: 'core/custom-media-breakpoints.css',
+            filter: hasSourceTokensOnly ? 'isSource' : undefined,
+            options: {
+              outputReferences: !hasSourceTokensOnly,
+            },
+          },
+        ],
+        transforms: StyleDictionary.transformGroup.css.filter(item => item !== 'size/rem').concat('color/sass-color-functions', 'str-replace'),
+        options: {
+          fileHeader: 'customFileHeader',
+        },
+      },
+    },
+  };
+
+  const getStyleDictionaryConfig = (themeVariant) => ({
+    ...coreConfig,
+    include: [...coreConfig.include, path.resolve(__dirname, `../tokens/src/themes/${themeVariant}/**/*.json`)],
+    source: tokensSource ? [`${tokensSource}/themes/${themeVariant}/**/*.json`] : [],
+    transform: {
+      'color/sass-color-functions': {
+        ...StyleDictionary.transform['color/sass-color-functions'],
+        transformer: (token) => colorTransform(token, themeVariant),
+      },
+    },
+    format: {
+      'css/custom-variables': formatterArgs => createCustomCSSVariables({
+        formatterArgs,
+        themeVariant,
+      }),
+    },
+    platforms: {
+      css: {
+        ...coreConfig.platforms.css,
+        files: [
+          {
+            format: 'css/custom-variables',
+            destination: `themes/${themeVariant}/variables.css`,
+            filter: hasSourceTokensOnly ? 'isSource' : undefined,
+            options: {
+              outputReferences: !hasSourceTokensOnly,
+            },
+          },
+          {
+            format: 'css/utility-classes',
+            destination: `themes/${themeVariant}/utility-classes.css`,
+            filter: hasSourceTokensOnly ? 'isSource' : undefined,
+            options: {
+              outputReferences: !hasSourceTokensOnly,
+            },
+          },
+        ],
+      },
+    },
+  });
+
+  StyleDictionary.extend(coreConfig).buildAllPlatforms();
+  createIndexCssFile({ buildDir, isTheme: false });
+
+  themes.forEach((themeVariant) => {
+    const config = getStyleDictionaryConfig(themeVariant);
+    StyleDictionary.extend(config).buildAllPlatforms();
+    createIndexCssFile({ buildDir, isTheme: true, themeVariant });
+  });
+}
+
+module.exports = buildTokensCommand;

package/lib/help.js

@@ -1,52 +1,65 @@
 /* eslint-disable no-console */
 const chalk = require('chalk');
 
-const DESCRIPTION_PAD = 20;
-
 /**
- * Pads a description string to align with a specified offset string.
+ * Finds a command based on the given name in the commands object.
  *
- * @param {string} description - The description to pad.
- * @param {string} offsetString - The offset string that the description should align with.
- * @returns {string} - The padded description.
+ * @param {Array} commandName - The name to find the command.
+ * @param {Object} commands - The object containing commands to search in.
+ * @returns {Object|null} - The found command or null if the command is not found.
  */
-function padLeft(description, offsetString) {
-  // Calculate the necessary padding based on the offsetString length
-  const padding = ' '.repeat(Math.max(0, DESCRIPTION_PAD - offsetString.length));
-  return `${padding}${description}`;
-}
+const findCommandByName = (commandName, commands) => ((commandName in commands)
+  ? { [commandName]: commands[commandName] } : null);
 
 /**
  * Displays a help message for available commands, including descriptions, parameters, and options.
  *
  * @param {Object} commands - An object containing information about available commands.
+ * @param {Array} commandArgs - An array containing the command name.
  */
-function helpCommand(commands) {
+function helpCommand(commands, commandArgs) {
+  const retrievedCommands = commandArgs.length ? findCommandByName(commandArgs, commands) : commands;
+  if (!retrievedCommands) {
+    console.error(chalk.red.bold('Unknown command. Usage: paragon help <command>.'));
+    return;
+  }
+
   console.log(chalk.yellow.bold('Paragon Help'));
   console.log();
-  console.log('Available commands:');
+
+  if (!commandArgs.length) {
+    console.log('Available commands:');
+  }
+
   console.log();
 
-  Object.entries(commands).forEach(([command, { parameters, description, options }]) => {
-    console.log(`  ${chalk.green.bold(command)}`);
+  Object.entries(retrievedCommands).forEach(([command, { parameters, description, options }]) => {
+    console.log(`  ${chalk.green.underline.bold(command)}`);
     if (description) {
-      console.log(`    ${description}`);
+      console.log(`      ${description}`);
     }
 
     if (parameters && parameters.length > 0) {
-      console.log(`    ${chalk.cyan('Parameters: ')}`);
+      console.log('');
+      console.log(`      ${chalk.bold.cyan('Parameters: ')}`);
       parameters.forEach(parameter => {
-        const requiredStatus = parameter.required ? 'Required' : 'Optional';
-        const formattedDescription = padLeft(parameter.description, parameter.name);
-        console.log(`      ${parameter.name}${formattedDescription} (${requiredStatus}, Default: ${parameter.defaultValue || 'None'})`);
+        console.log(`      ${chalk.yellow.bold(parameter.name)} ${chalk.grey(parameter.choices ? `${parameter.choices}, Default: ${parameter.defaultValue || 'None'}` : `Default: ${parameter.defaultValue || 'None'}`)}`);
+        if (parameter.description) {
+          console.log(`          ${parameter.description}`);
+        }
+        console.log('');
       });
     }
 
     if (options && options.length > 0) {
-      console.log(`    ${chalk.cyan('Options: ')}`);
+      console.log('');
+      console.log(`      ${chalk.bold.cyan('Options: ')}`);
       options.forEach(option => {
-        const formattedDescription = padLeft(option.description, option.name);
-        console.log(`      ${option.name}${formattedDescription}`);
+        console.log(`      ${chalk.yellow.bold(option.name)} ${chalk.grey(option.choices ? `${option.choices}, Default: ${option.defaultValue || 'None'}` : `Default: ${option.defaultValue}`)}`);
+        if (option.description) {
+          console.log(`          ${option.description}`);
+        }
+        console.log('');
       });
     }
 

package/lib/replace-variables.js

@@ -0,0 +1,38 @@
+const minimist = require('minimist');
+const { transformInPath } = require('../tokens/utils');
+const mapSCSStoCSS = require('../tokens/map-scss-to-css');
+
+/**
+ * Replaces CSS or SASS variables in a file with their corresponding values.
+ *
+ * @param {string[]} commandArgs - Command line arguments for replacing variables.
+ * @param {string} [commandArgs.filePath] - The path to the file in which variables should be replaced.
+ * @param {string} [commandArgs.source] - The path to the source directory containing variable mappings.
+ * @param {string} [commandArgs.replacementType] - The type of replacement ('usage' or 'all').
+ * @param {string} [commandArgs.direction] - The direction of replacement ('forward' or 'backward').
+ */
+async function replaceVariablesCommand(commandArgs) {
+  const alias = {
+    filePath: 'p',
+    source: 's',
+    replacementType: 't',
+    direction: 'd',
+  };
+
+  const {
+    filePath,
+    source: sourcePath,
+    replacementType,
+    direction,
+  } = minimist(commandArgs, { alias });
+
+  const variablesMap = mapSCSStoCSS(sourcePath);
+
+  if (replacementType === 'usage') {
+    await transformInPath(filePath, variablesMap, 'usage', [], direction);
+  } else {
+    await transformInPath(filePath, variablesMap);
+  }
+}
+
+module.exports = replaceVariablesCommand;

package/lib/utils.js

@@ -0,0 +1,30 @@
+const axios = require('axios');
+
+/**
+ * Sends request to the Netlify function to inform about specified event.
+ * @param {string} eventId - tracking event id
+ * @param {object} properties - tracking properties
+ */
+function sendTrackInfo(eventId, properties) {
+  const { BASE_URL, TRACK_ANONYMOUS_ANALYTICS } = process.env;
+  if (TRACK_ANONYMOUS_ANALYTICS) {
+    const url = `${BASE_URL}/.netlify/functions/sendTrackData`;
+    axios.post(url, { eventId, properties })
+      .then(result => {
+        // eslint-disable-next-line no-console
+        console.log(`Track info is successfully sent (status ${result.status})`);
+      }).catch(error => {
+        // eslint-disable-next-line no-console
+        console.log(`Track info request failed (${error})`);
+      });
+  }
+}
+
+function capitalize(str) {
+  if (typeof str !== 'string' || str.length === 0) {
+    return '';
+  }
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+module.exports = { sendTrackInfo, capitalize };

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@openedx/paragon",
-  "version": "22.4.0",
+  "version": "23.0.0-alpha.1",
   "description": "Accessible, responsive UI component library based on Bootstrap.",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
-  "publishConfig": {
-    "access": "public"
-  },
   "bin": {
     "paragon": "./bin/paragon-scripts.js"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/openedx/paragon.git"
@@ -20,7 +20,8 @@
     "/dist",
     "/icons",
     "/src",
-    "/scss",
+    "/styles",
+    "/tokens",
     "/lib"
   ],
   "sideEffects": false,
@@ -48,23 +49,36 @@
     "build-types": "tsc --emitDeclarationOnly",
     "playroom:start": "npm run playroom:start --workspace=www",
     "playroom:build": "npm run playroom:build --workspace=www",
-    "prepare": "husky || true"
+    "prepare": "husky || true",
+    "build-tokens": "./bin/paragon-scripts.js build-tokens --build-dir ./styles/css",
+    "replace-variables-usage-with-css": "./bin/paragon-scripts.js replace-variables -p src -t usage",
+    "replace-variables-definition-with-css": "./bin/paragon-scripts.js replace-variables -p src -t definition"
   },
   "dependencies": {
-    "@fortawesome/fontawesome-svg-core": "^6.1.1",
-    "@fortawesome/react-fontawesome": "^0.1.18",
     "@popperjs/core": "^2.11.4",
+    "axios": "^0.27.2",
     "bootstrap": "^4.6.2",
     "chalk": "^4.1.2",
     "child_process": "^1.0.2",
+    "chroma-js": "^2.4.2",
     "classnames": "^2.3.1",
+    "cli-progress": "^3.12.0",
+    "commander": "^9.4.1",
     "email-prop-type": "^3.0.0",
     "file-selector": "^0.6.0",
-    "font-awesome": "^4.7.0",
     "glob": "^8.0.3",
     "inquirer": "^8.2.5",
     "lodash.uniqby": "^4.7.0",
+    "log-update": "^4.0.0",
     "mailto-link": "^2.0.0",
+    "minimist": "^1.2.8",
+    "ora": "^5.4.1",
+    "postcss": "^8.4.21",
+    "postcss-combine-duplicated-selectors": "^10.0.3",
+    "postcss-custom-media": "^9.1.2",
+    "postcss-import": "^15.1.0",
+    "postcss-map": "^0.11.0",
+    "postcss-minify": "^1.1.0",
     "prop-types": "^15.8.1",
     "react-bootstrap": "^1.6.5",
     "react-colorful": "^5.6.1",
@@ -77,6 +91,8 @@
     "react-responsive": "^8.2.0",
     "react-table": "^7.7.0",
     "react-transition-group": "^4.4.2",
+    "sass": "^1.58.3",
+    "style-dictionary": "^3.7.1",
     "tabbable": "^5.3.3",
     "uncontrollable": "^7.2.1",
     "uuid": "^9.0.0"
@@ -137,7 +153,6 @@
     "react-dom": "^17.0.0",
     "react-test-renderer": "^17.0.0",
     "regenerator-runtime": "^0.13.9",
-    "sass": "^1.32.13",
     "semantic-release": "^20.1.3",
     "stylelint": "^14.7.1",
     "stylelint-config-standard-scss": "^4.0.0",

package/src/ActionRow/_index.scss

@@ -1,5 +1,3 @@
-@import "variables";
-
 .pgn__action-row {
   display: flex;
   flex-grow: 1;
@@ -11,7 +9,7 @@
   }
 
   & > * + * {
-    margin-inline-start: $action-row-gap-x;
+    margin-inline-start: var(--pgn-spacing-action-row-gap-x);
   }
 }
 
@@ -27,7 +25,7 @@
   }
 
   & > * + * {
-    margin-bottom: $action-row-gap-y;
+    margin-bottom: var(--pgn-spacing-action-row-gap-y);
   }
 }
 

package/src/Alert/index.scss

@@ -1,5 +1,3 @@
-@import "variables";
-
 //
 // Override Bootstrap's alert definition.
 // We do this to get more control over colors
@@ -12,11 +10,13 @@
 
 .alert {
   position: relative;
-  padding: $alert-padding-y $alert-padding-x;
-  margin-bottom: $alert-margin-bottom;
-  border: $alert-border-width solid transparent;
+  padding: var(--pgn-spacing-alert-padding-y) var(--pgn-spacing-alert-padding-x);
+  margin-bottom: var(--pgn-spacing-alert-margin-bottom);
+  border: var(--pgn-size-alert-border-width) solid var(--pgn-alert-border-color, transparent);
+  color: inherit;
+  background-color: var(--pgn-alert-bg, transparent);
 
-  @include border-radius($alert-border-radius);
+  @include border-radius(var(--pgn-size-alert-border-radius));
   @include pgn-box-shadow(1, "down");
 
   .alert-message-content > :last-child {
@@ -24,8 +24,9 @@
   }
 
   .alert-icon {
+    color: var(--pgn-alert-icon-color, inherit);
     float: left;
-    margin-inline-end: $alert-icon-space;
+    margin-inline-end: var(--pgn-spacing-alert-icon-space);
     width: 1.5rem;
     height: 1.5rem;
     flex-shrink: 0;
@@ -34,17 +35,17 @@
 
 // Headings for larger alerts
 .alert-heading {
-  // Specified to prevent conflicts of changing $headings-color
-  color: $alert-title-color;
+  // Specified to prevent conflicts of changing var(--pgn-color-headings-base)
+  color: var(--pgn-color-alert-title);
   display: flex;
 }
 
 // added to align content and icon
 .alert-content {
   display: flex;
-  font-size: $alert-font-size;
-  line-height: $alert-line-height;
-  color: $alert-content-color;
+  font-size: var(--pgn-typography-alert-font-size);
+  line-height: var(--pgn-typography-alert-line-height);
+  color: var(--pgn-color-alert-content);
   text-align: start;
 
   div {
@@ -54,7 +55,7 @@
 
 // Provide class for links that match alerts
 .alert-link {
-  font-weight: $alert-link-font-weight;
+  font-weight: var(--pgn-typography-alert-font-weight-link);
   text-decoration: underline;
 
   &:hover {
@@ -66,16 +67,16 @@
 //
 // Expand the right padding and account for the close button's positioning.
 
-// Baking in $close-font-size: $font-size-base * 1.5 !default; to avoid any dependency
+// Baking in $close-font-size: var(--pgn-typography-font-size-base) * 1.5 !default; to avoid any dependency
 .alert-dismissible {
-  padding-right: ($font-size-base * 1.5) + $alert-padding-x * 2;
+  padding-right: calc((var(--pgn-typography-font-size-base) * 1.5) + (var(--pgn-spacing-alert-padding-x) * 2));
 
   // Adjust close link position
   .close {
     position: absolute;
     top: 0;
     right: 0;
-    padding: $alert-padding-y $alert-padding-x;
+    padding: var(--pgn-spacing-alert-padding-y) var(--pgn-spacing-alert-padding-x);
     color: inherit;
   }
 }
@@ -85,28 +86,36 @@
   align-items: center;
 
   .pgn__alert-actions {
-    margin-inline-start: $alert-actions-gap;
+    margin-inline-start: var(--pgn-spacing-alert-actions-gap);
   }
 }
 
-.pgn__alert-message-wrapper-stacked {
-  .pgn__alert-actions {
-    margin-top: $alert-actions-gap;
-  }
+.pgn__alert-message-wrapper-stacked .pgn__alert-actions {
+  margin-top: var(--pgn-spacing-alert-actions-gap);
 }
 
 // Alternate styles
-//
-// Generate contextual modifier classes for coloring the alert.
 
-@each $color, $value in $theme-colors {
-  .alert-#{$color} {
-    color: inherit;
-    background-color: theme-color($color, "background");
-    border-color: theme-color($color, "border");
+.alert-success {
+  --pgn-alert-bg: var(--pgn-color-alert-bg-success);
+  --pgn-alert-border-color: var(--pgn-color-alert-border-success);
+  --pgn-alert-icon-color: var(--pgn-color-alert-icon-success);
+}
 
-    .alert-icon {
-      color: theme-color($color, "default");
-    }
-  }
+.alert-info {
+  --pgn-alert-bg: var(--pgn-color-alert-bg-info);
+  --pgn-alert-border-color: var(--pgn-color-alert-border-info);
+  --pgn-alert-icon-color: var(--pgn-color-alert-icon-info);
+}
+
+.alert-danger {
+  --pgn-alert-bg: var(--pgn-color-alert-bg-danger);
+  --pgn-alert-border-color: var(--pgn-color-alert-border-danger);
+  --pgn-alert-icon-color: var(--pgn-color-alert-icon-danger);
+}
+
+.alert-warning {
+  --pgn-alert-bg: var(--pgn-color-alert-bg-warning);
+  --pgn-alert-border-color: var(--pgn-color-alert-border-warning);
+  --pgn-alert-icon-color: var(--pgn-color-alert-icon-warning);
 }

package/src/Annotation/_mixins.scss

@@ -0,0 +1,104 @@
+@mixin annotation-triangle($triangle-color, $triangle-direction) {
+  content: "";
+  height: 0;
+  width: 0;
+  position: absolute;
+  border: solid transparent;
+
+  @if $triangle-direction == top {
+    border-bottom-color: $triangle-color;
+    border-width: 0 var(--pgn-size-annotation-arrow-border-width) var(--pgn-size-annotation-arrow-border-width);
+    right: 0;
+    left: 0;
+    top: calc(var(--pgn-size-annotation-arrow-border-width) * -1);
+    margin: 0 auto;
+  }
+
+  @else if $triangle-direction == right {
+    border-left-color: $triangle-color;
+    border-width:
+      var(--pgn-size-annotation-arrow-border-width) 0 var(--pgn-size-annotation-arrow-border-width)
+      var(--pgn-size-annotation-arrow-border-width);
+    top: 0;
+    bottom: 0;
+    right: calc(var(--pgn-size-annotation-arrow-border-width) * -1);
+    margin: auto 0;
+  }
+
+  @else if $triangle-direction == bottom {
+    border-top-color: $triangle-color;
+    border-width: var(--pgn-size-annotation-arrow-border-width) var(--pgn-size-annotation-arrow-border-width) 0;
+    right: 0;
+    left: 0;
+    bottom: calc(var(--pgn-size-annotation-arrow-border-width) * -1);
+    margin: 0 auto;
+  }
+
+  @else if $triangle-direction == left {
+    border-right-color: $triangle-color;
+    border-width:
+      var(--pgn-size-annotation-arrow-border-width) var(--pgn-size-annotation-arrow-border-width)
+      var(--pgn-size-annotation-arrow-border-width) 0;
+    top: 0;
+    bottom: 0;
+    left: calc(var(--pgn-size-annotation-arrow-border-width) * -1);
+    margin: auto 0;
+  }
+
+  @else {
+    @error "Unknown direction #{$triangle-direction}.";
+  }
+}
+
+@mixin annotation-variant($bg-color, $text-color, $direction) {
+  background-color: $bg-color;
+  color: $text-color;
+
+  // set additional margin to arrow side of the Annotation
+  margin-#{$direction}:
+    calc(
+      var(--pgn-size-annotation-arrow-border-width) + var(--pgn-spacing-annotation-arrow-side-margin)
+    );
+
+  [dir="rtl"] & {
+    @if $direction == left {
+      margin-left: 0;
+      margin-right:
+        calc(
+          var(--pgn-size-annotation-arrow-border-width) + var(--pgn-spacing-annotation-arrow-side-margin)
+        );
+    }
+
+    @else if $direction == right {
+      margin-right: 0;
+      margin-left:
+        calc(
+          var(--pgn-size-annotation-arrow-border-width) + var(--pgn-spacing-annotation-arrow-side-margin)
+        );
+    }
+  }
+
+  &::after {
+    @include annotation-triangle($bg-color, $direction);
+
+    [dir="rtl"] & {
+      @if $direction == left {
+        left: initial;
+        right: calc(var(--pgn-size-annotation-arrow-border-width) * -1);
+        border-width:
+          var(--pgn-size-annotation-arrow-border-width) 0 var(--pgn-size-annotation-arrow-border-width)
+          var(--pgn-size-annotation-arrow-border-width);
+        border-left-color: $bg-color;
+      }
+
+      @else if $direction == right {
+        right: initial;
+        left: calc(var(--pgn-size-annotation-arrow-border-width) * -1);
+        border-width:
+          var(--pgn-size-annotation-arrow-border-width) var(--pgn-size-annotation-arrow-border-width)
+          var(--pgn-size-annotation-arrow-border-width) 0;
+        border-right-color: $bg-color;
+      }
+    }
+  }
+}