style-dictionary.js

/**
 * This module creates and exports custom StyleDictionary instance for Paragon.
 */
const toml = require('js-toml');
const chalk = require('chalk');
const chroma = require('chroma-js');
const { colorYiq, darken, lighten } = require('./sass-helpers');
const cssUtilities = require('./css-utilities');
const { composeBreakpointName, processAndUpdateTokens, generateButtonVariantProperties } = require('./utils');

/* eslint-disable import/no-unresolved */
const getStyleDictionary = async () => (await import('style-dictionary')).default;
const getStyleDictionaryUtils = async () => import('style-dictionary/utils');
const getTokensStudioTransforms = async () => import('@tokens-studio/sd-transforms');
/* eslint-enable import/no-unresolved */

/**
 * @typedef {import('style-dictionary/types').DesignToken} DesignToken
 */

/**
 * @typedef ModifyColorYiq
 * @property {'color-yiq'} type - The type of modification.
 * @property {number} [amount] - The amount of modification to apply.
 * @property {string} [otherColor] - The other color to mix with.
 * @property {number} [light] - The light color to use for color-yiq.
 * @property {number} [dark] - The dark color to use for color-yiq.
 * @property {number} [threshold] - The threshold to use for color-yiq.
 */

/**
 * @typedef ModifyColorDarken
 * @property {'darken'} type - The type of modification.
 * @property {number} amount - The amount of modification to apply.
 */

/**
 * @typedef ModifyColorLighten
 * @property {'lighten'} type - The type of modification.
 * @property {number} amount - The amount of modification to apply.
 */

/**
 * @typedef ModifyColorMix
 * @property {'mix'} type - The type of modification.
 * @property {number} amount - The amount of modification to apply.
 * @property {string} otherColor - The other color to mix with.
 */

/**
 * @typedef ModifyColorAlpha
 * @property {'alpha'} type - The type of modification.
 * @property {number} amount - The amount of modification to apply.
 */

/**
 * @typedef DesignTokenModify
 * @type {ModifyColorYiq | ModifyColorDarken | ModifyColorLighten | ModifyColorMix | ModifyColorAlpha}
 */

/**
 * @typedef {DesignToken & {
 *   outputReferences?: boolean;
 *   modify?: DesignTokenModify[];
 * }} ParagonDesignToken
 */

/**
 * Transforms a color token based on various modifications.
 *
 * @param {ParagonDesignToken} token - The token object containing color information and modifications.
 * @param {string} themeVariant - The themeVariant object containing additional information for color transformations.
 * @returns {string} - The transformed color value in hexadecimal format, including alpha if applicable.
 */
const colorTransform = (token, themeVariant) => {
  const {
    name: tokenName,
    $value,
    original,
    modify,
  } = token;
  const reservedColorValues = ['inherit', 'initial', 'revert', 'unset', 'currentColor', 'none'];

  if (reservedColorValues.includes(original.$value)) {
    return original.$value;
  }

  let color = chroma($value);

  if (modify?.length > 0) {
    modify.forEach((modifier) => {
      const { type, amount, otherColor } = modifier;
      switch (type) {
        case 'mix':
          color = color.mix(otherColor, amount, 'rgb');
          break;
        case 'color-yiq': {
          const { light, dark, threshold } = modifier;
          color = colorYiq({
            tokenName,
            backgroundColor: color,
            light,
            dark,
            threshold,
            themeVariant,
          });
          break;
        }
        case 'darken':
          color = darken(color, amount);
          break;
        case 'lighten':
          color = lighten(color, amount);
          break;
        default: {
          if (!color[type]) {
            // eslint-disable-next-line no-console
            console.warn(
              chalk.keyword('orange').bold(`[Paragon] Warning: Invalid color modification type "${type}" for ${tokenName}.`),
            );
            return;
          }
          color = color[type](amount);
        }
      }
    });
  }

  return color.hex('rgba').toUpperCase();
};

/**
 * Custom formatter that extends default css/variables format to allow specifying
 * 1. 'outputReferences' per token (by default you are only able to specify it globally for all tokens)
 * 2. 'theme' to output only theme's variables (e.g, 'light' or 'dark'), if theme is not provided - only
 * core tokens are built.
 */
const createCustomCSSVariables = async ({ formatterArgs }) => {
  const { fileHeader, formattedVariables } = await getStyleDictionaryUtils();
  const { dictionary, options, file } = formatterArgs;
  const { outputReferences, formatting } = options;
  const variables = formattedVariables({
    format: 'css',
    dictionary,
    outputReferences: (token) => {
      // Formatter options configured to never output references
      if (!outputReferences) {
        return false;
      }
      // Token has modifications (e.g., mix, darken, lighten); the computed
      // value should be output instead of the reference.
      if (token.modify) {
        return false;
      }
      // Formatter options configured to show output references, but handle when individual tokens might opt-out.
      return token.outputReferences ?? true;
    },
    usesDtcg: true,
  });
  const header = await fileHeader({ file, formatting });
  return `${header}:root {\n${variables}\n}\n`;
};

/**
 * @typedef {type import("style-dictionary/types").StyleDictionary} StyleDictionary
 */

/**
 * Initializes and configures Style Dictionary with custom transforms, formatters, filters, and parsers.
 *
 * @returns {Promise<StyleDictionary>} - A promise that resolves to the configured Style Dictionary instance.
 */
const initializeStyleDictionary = async ({ themes }) => {
  const StyleDictionary = await getStyleDictionary();
  const sdUtils = await getStyleDictionaryUtils();
  const {
    register: registerTokensStudioTransforms,
    getTransforms: tokensStudioTransforms,
  } = await getTokensStudioTransforms();

  StyleDictionary.registerPreprocessor({
    name: 'pgn-annotate-token-extensions-with-references',
    preprocessor: (dictionary) => {
      // Define the extension properties to add to the tokens $extensions object
      const extensionProperties = [
        {
          name: 'isReferencedBySourceToken',
          filter: tkn => tkn.isSource,
          referenceTokenFilter: tkn => !tkn.isSource,
        },
        {
          name: 'isReferencedByThemeVariant',
          filter: tkn => themes.some(theme => tkn.filePath.includes(theme)),
          referenceTokenFilter: tkn => !themes.some(theme => tkn.filePath.includes(theme)),
        },
      ];

      // Pass the dictionary to the recursive function to process and update tokens in place
      const dictionaryCopy = { ...dictionary };
      processAndUpdateTokens(dictionary, extensionProperties, sdUtils, dictionaryCopy);

      // Return the updated dictionary
      return dictionary;
    },
  });

  /**
   * Registers transforms from @tokens-studio/sd-transforms.
   */
  registerTokensStudioTransforms(StyleDictionary);

  /**
   * Transforms tokens by applying SASS color functions to tokens.
   */
  StyleDictionary.registerTransform({
    name: 'color/sass-color-functions',
    transitive: true,
    type: 'value',
    filter: (token) => token.attributes?.category === 'color' || token.$value.toString().startsWith('#'),
    transform: (token) => colorTransform(token),
  });

  /**
   * Transforms that implements str-replace from SASS.
   */
  StyleDictionary.registerTransform({
    name: 'str-replace',
    transitive: true,
    type: 'value',
    filter: (token) => token.modify && token.modify[0].type === 'str-replace',
    transform: (token) => {
      const { $value, modify } = token;
      const { toReplace, replaceWith } = modify[0];
      return $value.replaceAll(toReplace, replaceWith);
    },
  });

  /**
   * Registers a custom transform group for Paragon CSS.
   */
  const customTransforms = [
    'color/sass-color-functions',
    'str-replace',
  ];
  StyleDictionary.registerTransformGroup({
    name: 'paragon-css',
    transforms: [
      ...tokensStudioTransforms({ platform: 'css' }),
      ...StyleDictionary.hooks.transformGroups.css,
      ...customTransforms,
    ],
  });

  /**
   * The custom formatter to create CSS variables for core tokens.
   */
  StyleDictionary.registerFormat({
    name: 'css/custom-variables',
    format: formatterArgs => createCustomCSSVariables({ formatterArgs }),
  });

  /**
   * Formatter to generate CSS utility classes.
   * Looks in ./src/utilities/ to get utility classes configuration, filters tokens by 'filters' object attributes
   * (see https://amzn.github.io/style-dictionary/#/tokens?id=category-type-item for possible keys in the object,
   * each key should have a list of valid values) and generates CSS classes with using functions defined in
   * 'utilityFunctionsToApply' list, those functions must be located in css-utilities.js module and return string.
   */
  StyleDictionary.registerFormat({
    name: 'css/utility-classes',
    format: async ({ dictionary, file, options = {} }) => {
      const { formatting } = options;
      const { fileHeader } = await getStyleDictionaryUtils();
      const { utilities } = dictionary.tokens;
      if (!utilities) {
        return '';
      }

      let utilityClasses = '';

      utilities.forEach(({ filters, utilityFunctionsToApply }) => {
        let tokens = dictionary.allTokens;

        Object.entries(filters).forEach(([attributeName, allowedValues]) => {
          tokens = tokens.filter((token) => allowedValues.includes(token.attributes[attributeName]));
        });

        // eslint-disable-next-line no-restricted-syntax
        for (const token of tokens) {
          // Get action token by reference
          const ref = sdUtils.getReferences(token.original.actions.default, dictionary.tokens)[0];
          token.actions = { default: `var(--${ref.name})` };
          // eslint-disable-next-line no-restricted-syntax
          for (const funcName of utilityFunctionsToApply) {
            utilityClasses += cssUtilities[funcName](token);
          }
        }
      });
      const header = await fileHeader({ file, formatting });
      return `${header}${utilityClasses}`;
    },
  });

  /**
   * Formatter to generate CSS custom media queries for responsive breakpoints.
   * Gets input about existing tokens of the 'size' category,
   * 'breakpoints' subcategory, and generates a CSS custom media queries.
   */
  StyleDictionary.registerFormat({
    name: 'css/custom-media-breakpoints',
    format: async ({ dictionary, file, options = {} }) => {
      const { fileHeader } = await getStyleDictionaryUtils();
      const { formatting } = options;
      const { breakpoint } = dictionary.tokens.size;

      let customMediaVariables = '';
      const breakpoints = Object.values(breakpoint || {});

      for (let i = 0; i < breakpoints.length; i++) {
        const [currentBreakpoint, nextBreakpoint] = [breakpoints[i], breakpoints[i + 1]];
        customMediaVariables
          += `${composeBreakpointName(currentBreakpoint.name, 'min')} (min-width: ${currentBreakpoint.$value});\n`;
        if (nextBreakpoint) {
          customMediaVariables
            += `${composeBreakpointName(currentBreakpoint.name, 'max')} (max-width: ${nextBreakpoint.$value});\n`;
        }
      }
      const header = await fileHeader({ file, formatting });
      return `${header}${customMediaVariables}`;
    },
  });

  /**
   * Configuration for button variant overrides by component type.
   * Each entry defines:
   * - getTokens: Function that receives the dictionary tokens and returns the button variant overrides
   * - selectors: Array of CSS selectors where the button variants should be overridden
   */
  const BUTTON_VARIANT_OVERRIDES_CONFIG = [
    {
      name: 'Alert actions',
      getTokens: (tokens) => tokens?.color?.alert?.actions?.overrides?.button?.variants,
      selectors: [
        '.pgn__alert-message-wrapper .pgn__alert-actions',
        '.pgn__alert-message-wrapper-stacked .pgn__alert-actions',
      ],
    },
    {
      name: 'Modal footer',
      getTokens: (tokens) => tokens?.color?.modal?.footer?.overrides?.button?.variants,
      selectors: [
        '.pgn__modal .pgn__modal-footer',
      ],
    },
    // Add new component configurations here!
  ];

  /**
   * Registers a custom format for generating CSS style overrides for button variants in different components.
   * All overrides are combined into a single CSS file.
   */
  StyleDictionary.registerFormat({
    name: 'css/component-button-variant-overrides',
    format: async ({ dictionary }) => {
      const { fileHeader } = await getStyleDictionaryUtils();
      const header = await fileHeader({
        file: 'overrides/component-button-variants.css',
        formatting: 'css',
      });
      let hasOutputHeader = false;
      let output = '';

      // Process each component configuration
      BUTTON_VARIANT_OVERRIDES_CONFIG.forEach((config) => {
        const buttonVariantOverrides = config.getTokens(dictionary.tokens);

        if (!buttonVariantOverrides || typeof buttonVariantOverrides !== 'object' || Object.keys(buttonVariantOverrides).length === 0) {
          return; // No overrides tokens found, skip.
        }

        if (!hasOutputHeader) {
          output += header;
          hasOutputHeader = true;
        }

        output += `/* ${config.name} */\n\n`;

        Object.entries(buttonVariantOverrides).forEach(([originalVariant, overrideVariant]) => {
          const selectorOutput = config.selectors
            .map(selector => `${selector} .btn-${originalVariant}`)
            .join(',\n');

          output += `${selectorOutput} {\n`;
          output += `  ${generateButtonVariantProperties(overrideVariant)}\n`;
          output += '}\n\n';
        });
      });

      return output;
    },
  });

  /**
   * @typedef {function} StyleDictionaryFilterFunction
   * @param {import('style-dictionary/types').TransformedToken} token - The token object to filter.
   * @param {object} [opts] - The options object passed to the filter.
   */

  /**
   * @typedef {object} StyleDictionaryFilterOptions
   * @property {boolean} hasThemeVariants - Indicates whether the filter should also be registered with theme variants.
   */

  /**
   * Registers a custom filter with Style Dictionary.
   * @param {string} name Name for the filter.
   * @param {StyleDictionaryFilterFunction} filter Filter value or function.
   * @param {StyleDictionaryFilterOptions} [filterOptions] Custom options for the filter.
   */
  function registerStyleDictionaryFilter(name, filter, filterOptions = {}) {
    StyleDictionary.registerFilter({ name, filter });
    if (filterOptions.hasThemeVariants) {
      themes.forEach((themeVariant) => {
        StyleDictionary.registerFilter({
          name: `${name}.${themeVariant}`,
          filter: (token, opts) => {
            const paragonExtensions = token.$extensions?.['org.openedx.paragon'];
            const isReferencedByThemeVariant = !!paragonExtensions?.isReferencedByThemeVariant;
            const baseFilterResult = typeof filter === 'function' ? filter(token, opts) || isReferencedByThemeVariant : filter;
            if (!baseFilterResult) {
              return false;
            }
            return token.filePath.includes(themeVariant) || isReferencedByThemeVariant;
          },
        });
      });
    }
  }

  const paragonFilters = [
    /**
     * Registers a filter `isSource` that filters output to only include source tokens.
     */
    {
      name: 'isSource',
      filter: (token) => {
        const paragonExtensions = token.$extensions?.['org.openedx.paragon'];
        const isReferencedBySourceToken = !!paragonExtensions?.isReferencedBySourceToken;
        return token.isSource || isReferencedBySourceToken;
      },
      opts: { hasThemeVariants: true },
    },
    /**
     * Registers filter(s) `isThemeVariant.{variant}` that only include the requested theme variant tokens.
     */
    ...themes.map((themeVariant) => ({
      name: `isThemeVariant.${themeVariant}`,
      filter: (token) => {
        const isThemeVariantToken = token.filePath.includes(themeVariant);
        const paragonExtensions = token.$extensions?.['org.openedx.paragon'];
        const isReferencedByThemeVariant = !!paragonExtensions?.isReferencedByThemeVariant;
        return isThemeVariantToken || isReferencedByThemeVariant;
      },
    })),
  ];
  paragonFilters.forEach(({ name, filter, opts }) => registerStyleDictionaryFilter(name, filter, opts));

  /**
   * Registers a custom TOML parser with Style Dictionary.
   */
  StyleDictionary.registerParser({
    name: 'toml-parser',
    pattern: /\.toml$/,
    parser: ({ contents }) => toml.load(contents),
  });

  /**
   * Registers a custom fileHeader.
   */
  StyleDictionary.registerFileHeader({
    name: 'customFileHeader',
    fileHeader: (defaultMessage) => [
      `${defaultMessage}`,
      'See <PARAGON_ROOT>/tokens/README.md for more details.',
    ],
  });

  return StyleDictionary;
};

module.exports = {
  initializeStyleDictionary,
  getTokensStudioTransforms,
  createCustomCSSVariables,
  colorTransform,
  getStyleDictionaryUtils,
};