@openedx/paragon 22.6.0 → 23.0.0-alpha.2

package/README.md

@@ -39,29 +39,39 @@ In your React project:
 import { ComponentName } from '@openedx/paragon';
 ```
 
-#### SCSS Foundation
+#### CSS Foundation
 
-Usage for Open edX and others:
+**Usage with no theme:**
 
-**index.scss**
+The Paragon CSS Foundation offers a collection of fundamental styles, encompassing padding, typography, and sizing.
+When applied, these styles contribute to the creation of a straightforward and neat appearance for your application.
+
+To integrate these foundational styles into your project, include the following import:
 
 ```
-// ... Any custom SCSS variables should be defined here
-@import '~@openedx/paragon/scss/core/core.scss';
+@use "@openedx/paragon/dist/core.min.css";
 ```
 
-Usage on with `@edx/brand`:
+**Usage with a theme:**
+
+In addition to the basic styles, you can provide a theme layer that includes styles for colors, shadows, backgrounds
+and transparency of elements. This allows you to visually represent a specific theme in your application.
 
-**index.scss**
+To apply these theme-specific styles, include the following import:
 
 ```
-@import '~@edx/brand/paragon/fonts.scss';
-@import '~@edx/brand/paragon/variables.scss';
-@import '~@openedx/paragon/scss/core/core.scss';
-@import '~@edx/brand/paragon/overrides.scss';
+@use "@openedx/paragon/dist/core.min.css";
+@use "@my-brand/light.min.css";
 ```
 
-Note that including fonts will affect performance.  In some applications may choose not to load the custom font to keep it highly performant.
+**CDN links:**
+
+Alternative style integration is available when using CDN links:
+
+```
+@import url("https://cdn.jsdelivr.net/npm/@my-brand/core.min.css");
+@import url("https://cdn.jsdelivr.net/npm/@my-brand/light.min.css");
+```
 
 ## Paragon CLI
 
@@ -69,7 +79,11 @@ The Paragon CLI (Command Line Interface) is a tool that provides various utility
 
 ### Available Commands
 
-- `paragon install-theme [theme]`: Installs the specific @edx/brand package.
+- `paragon install-theme`: Install a [brand package](https://github.com/openedx/brand-openedx).
+- `paragon migrate-to-openedx-scope`: Migrate from "@edx/paragon" to "@openedx/paragon".
+- `paragon build-tokens`: Build Paragon's design tokens.
+- `paragon replace-variables`: Replace SCSS variables usages or definitions to CSS variables and vice versa in `.scss` files.
+- `paragon build-scss`: Compile Paragon's core and themes SCSS into CSS.
 
 Use `paragon help` to see more information.
 
@@ -148,7 +162,7 @@ module.exports = {
   dist: The sub-directory of the source code where it puts its build artifact. Often "dist".
   */
   localModules: [
-    { moduleName: '@openedx/paragon/scss/core', dir: '../src/paragon', dist: 'scss/core' },
+    { moduleName: '@openedx/paragon/styles/scss/core', dir: '../src/paragon', dist: 'styles/scss/core' },
     { moduleName: '@openedx/paragon/icons', dir: '../src/paragon', dist: 'icons' },
     // Note that using dist: 'dist' will require you to run 'npm build' in Paragon
     // to add local changes to the 'dist' directory, so that they can be picked up by the MFE.
@@ -158,7 +172,7 @@ module.exports = {
 };
 ```
 
-Then, when importing Paragon's core SCSS in your MFE the import needs to begin with a tilde `~` so that path to your local Paragon repository gets resolved correctly: `@import "~@openedx/paragon/scss/core";`
+Then, when importing Paragon's core SCSS in your MFE the import needs to begin with a tilde `~` so that path to your local Paragon repository gets resolved correctly: `@import "~@openedx/paragon/styles/scss/core/core.scss";`
 
 #### Internationalization
 
@@ -271,8 +285,7 @@ This will create a directory in `/src/` that will contain templates for all nece
 MyComponent
 ├── index.jsx
 ├── README.md
-├── MyComponent.scss
-├── _variables.scss
+├── index.scss
 └── MyComponent.test.jsx
 ```
 
@@ -311,11 +324,10 @@ export default MyComponent;
 ##### 4. (Optional) Add styles to your component.
 
 If your component requires additional styling (which most likely is the case), edit created SCSS style sheet in your
-component's directory `/src/MyComponent/MyComponent.scss` which by default contains an empty class for your component.
+component's directory `/src/MyComponent/index.scss` which by default contains an empty class for your component.
 
-If you wish to use SASS variables (which is the preferred way of styling the components since values can be
-easily overridden and customized by the consumers of Paragon), add them in `/src/MyComponent/_variables.scss` (this file should contain all variables specific to your component).
-This way the variables will also get automatically picked up by documentation site and displayed on your component's page.
+If you wish to use CSS variables (which is the preferred way of styling the components since values can be
+easily overridden and customized by the consumers of Paragon), you can do so by utilizing [design tokens](/tokens).
 
 **Please note that you need to follow [Paragon's CSS styling conventions](docs/decisions/0012-css-styling-conventions).**
 
@@ -477,3 +489,31 @@ The assigned maintainers for this component and other project details may be fou
 Please do not report security issues in public. Please email security@openedx.org.
 
 We tend to prioritize security issues which impact the published `@openedx/paragon` NPM library more so than the [documentation website](https://paragon-openedx.netlify.app/) or example React application.
+
+## Design Tokens
+
+Design tokens are all the values needed to build and maintain a design system — spacing, color, typography, object styles, etc. They can represent anything defined by the design: color as an RGB value, opacity as a number, spacing as a REM value. They are used instead of hard-coded values to provide flexibility and uniformity across the application.
+
+By defining style properties as tokens, we can transform the styles into various implementations compatible with different platforms or formats as our use cases expand (e.g., transforming tokens to CSS variables, CSS utility classes, etc.).
+
+### Theming with design tokens
+
+Paragon uses [style-dictionary](https://github.com/amzn/style-dictionary) to build design tokens into CSS variables that are included in the package. Read more in [design tokens README](tokens/README.md).
+
+#### Compiling CSS from design tokens for Paragon contributions (in this repo)
+1. **`npm install`.** Install dependencies, including `style-dictionary`.
+2. Make changes to design token(s).
+3. **`npm run build-scss`.** Transforms the tokens to CSS variables and CSS utility classes, and generates `core.css` and `light.css` output files.
+    - `light.css`. CSS variable definitions for colors in the light theme variant.
+    - `core.css`. Contains the majority of Paragon/Bootstrap foundational styles for layout, components, etc. Consumes CSS variables defined by `light.css`.
+4. Test changes locally (e.g., running the documentation website, the example MFE app, etc.).
+5. Ensure changes to `core.css` and `light.css` are committed & released to NPM (which also "releases" them on versioned public CDNs for NPM packages).
+6. Consuming applications would inject the `core.css` and `light.css` theme files into their applications via a mechanism similar to https://github.com/openedx/frontend-platform/pull/440 (ideally pulling from a public CDN for NPM packages, but falling back to locally installed copies, if needed).
+
+#### Compiling CSS from design tokens for `@edx/brand` theme authors (in `@edx/brand` repos)
+1. **`npm install`.** Install dependencies, including `@openedx/paragon`.
+2. Create tokens that will override Paragon's default tokens (matching same JSON schema).
+3. **`npm run build-scss`.** This `@edx/brand` repo will have a new NPM script that utilizes a new CLI exported by `@openedx/paragon` which exposes the `build-tokens.js` script (or possibly another if we end up needing one for the brand packages to run specifically, TBD) for `@edx/brand` consumers.
+    - The intent of running this command is to effectively deep merge the tokens defined in Paragon's default tokens with the override tokens defined by `@edx/brand`, generating its own `core.css` and `light.css` output files (exact output files still a TBD) containing CSS variable overrides based on the token overrides.
+5. Ensure any changes to the generated `core.css` and `light.css` files are committed & released to NPM (which also "releases" them on versioned public CDNs for NPM packages).
+    - _Note: It is a bit unclear still in the above linked implementation POC for `@edx/frontend-platform` how it would integrate with `@edx/brand` in this way. Open to suggestions/feedback/ideas here._

package/bin/paragon-scripts.js

@@ -2,10 +2,13 @@
 const chalk = require('chalk');
 const themeCommand = require('../lib/install-theme');
 const helpCommand = require('../lib/help');
+const buildTokensCommand = require('../lib/build-tokens');
+const replaceVariablesCommand = require('../lib/replace-variables');
+const buildScssCommand = require('../lib/build-scss');
+const { sendTrackInfo } = require('../lib/utils');
 const versionCommand = require('../lib/version');
 const migrateToOpenEdxScopeCommand = require('../lib/migrate-to-openedx-scope');
 
-const HELP_COMMAND = 'help';
 const commandAliases = {
   '-v': 'version',
   '--version': 'version',
@@ -31,6 +34,9 @@ const COMMANDS = {
   *    {
   *      name: '--optionName',
   *      description: 'optionDescription',
+  *      choices: 'optionChoices',
+  *      defaultValue: 'optionDefaultValue',
+  *      required: true/false,
   *    },
   *    ...
   *  ],
@@ -60,8 +66,118 @@ const COMMANDS = {
       },
     ],
   },
+  'build-tokens': {
+    executor: buildTokensCommand,
+    description: 'CLI to build Paragon design tokens.',
+    options: [
+      {
+        name: '-s, --source',
+        description: 'Specify the source directory for design tokens.',
+        defaultValue: '\'\'',
+      },
+      {
+        name: '-b, --build-dir',
+        description: 'Specify the build directory for the generated tokens.',
+        defaultValue: './build/',
+      },
+      {
+        name: '--source-tokens-only',
+        description: 'Include only source design tokens in the build.',
+        defaultValue: false,
+      },
+      {
+        name: '-t, --themes',
+        description: 'Specify themes to include in the token build.',
+        defaultValue: 'light',
+      },
+    ],
+  },
+  'replace-variables': {
+    executor: replaceVariablesCommand,
+    description: 'CLI to replace SCSS variables usages or definitions to CSS variables and vice versa in .scss files.',
+    parameters: [
+      {
+        name: '-p, --filePath',
+        description: 'Path to the file or directory where to replace variables.',
+        defaultValue: '\'\'',
+      },
+    ],
+    options: [
+      {
+        name: '-s, --source',
+        description: 'Type of replacement: usage or definition. If set to "definition" the command will only update SCSS variables definitions with CSS variables, if set to "usage" - all occurrences of SCSS variables will we replaced',
+        defaultValue: '\'\'',
+      },
+      {
+        name: '-t, --replacementType',
+        description: 'Type of replacement: usage or definition. If set to "definition" the command will only update SCSS variables definitions with CSS variables, if set to "usage" - all occurrences of SCSS variables will we replaced',
+        choices: '[usage|definition]',
+        defaultValue: 'definition',
+      },
+      {
+        name: '-d, --direction',
+        description: 'Map direction: css-to-scss or scss-to-css, if replacement type parameter is set to "definition" this has no effect.',
+        choices: '[scss-to-css|css-to-scss]',
+        defaultValue: 'scss-to-css',
+      },
+    ],
+  },
+  'build-scss': {
+    executor: buildScssCommand,
+    description: 'CLI to compile Paragon\'s core and themes SCSS into CSS.',
+    options: [
+      {
+        name: '--corePath',
+        description: 'Path to the theme\'s core SCSS file, defaults to Paragon\'s core.scss.',
+        defaultValue: 'styles/scss/core/core.scss',
+      },
+      {
+        name: '--themesPath',
+        description: `Path to the directory that contains themes' files. Expects directory to have following structure:
+          themes/
+            light/
+            │  ├─ index.css
+            │  ├─ other_css_files
+            dark/
+            │  ├─ index.css
+            │  ├─ other_css_files
+            some_other_custom_theme/
+            │  ├─ index.css
+            │  ├─ other_css_files
+          ...
+
+          where index.css has imported all other CSS files in the theme's subdirectory. The script will output
+          light.css, dark.css and some_other_custom_theme.css files (together with maps and minified versions).
+          You can provide any amount of themes. Default to paragon's themes.
+      `,
+        defaultValue: 'styles/css/themes',
+      },
+      {
+        name: '--outDir',
+        description: 'Specifies directory where to out resulting CSS files.',
+        defaultValue: './dist',
+      },
+      {
+        name: '--defaultThemeVariants',
+        description: `Specifies default theme variants. Defaults to a single 'light' theme variant.
+          You can provide multiple default theme variants by passing multiple values, for
+          example: \`--defaultThemeVariants light dark\`
+        `,
+        defaultValue: 'light',
+      },
+    ],
+  },
   help: {
-    executor: helpCommand,
+    executor: (args) => helpCommand(COMMANDS, args),
+    parameters: [
+      {
+        name: 'command',
+        description: 'Specifies command name.',
+        defaultValue: '\'\'',
+        choices: '[install-theme|build-tokens|replace-variables|build-scss]',
+        required: false,
+      },
+    ],
     description: 'Displays help for available commands.',
   },
   version: {
@@ -70,8 +186,14 @@ const COMMANDS = {
   },
 };
 
+/**
+ * Executes a Paragon CLI command based on the provided command-line arguments.
+ *
+ * @async
+ * @function executeParagonCommand
+ */
 (async () => {
-  const [command] = process.argv.slice(2);
+  const [command, ...commandArgs] = process.argv.slice(2);
   const resolvedCommand = commandAliases[command] || command;
   const executor = COMMANDS[resolvedCommand];
 
@@ -81,16 +203,13 @@ const COMMANDS = {
     return;
   }
 
-  if (command === HELP_COMMAND) {
-    helpCommand(COMMANDS);
-    return;
-  }
-
   try {
-    await executor.executor();
+    await executor.executor(commandArgs);
+    sendTrackInfo('openedx.paragon.cli-command.used', { command, status: 'success' });
   } catch (error) {
     // eslint-disable-next-line no-console
     console.error(chalk.red.bold('An error occurred:', error.message));
+    sendTrackInfo('openedx.paragon.cli-command.used', { command, status: 'error', errorMsg: error.message });
     process.exit(1);
   }
 })();

package/dist/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/dist/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/dist/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;
+      }
+    }
+  }
+}