@atlaskit/eslint-plugin-design-system 8.7.0 → 8.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @atlaskit/eslint-plugin-design-system
 
+## 8.8.0
+
+### Minor Changes
+
+- [`6c149f3e71d`](https://bitbucket.org/atlassian/atlassian-frontend/commits/6c149f3e71d) - The `ensure-design-token-usage` rules now report on use of the CSS `calc` function when used with padding, margin, and gap properties.
+
+## 8.7.1
+
+### Patch Changes
+
+- [`d6845989896`](https://bitbucket.org/atlassian/atlassian-frontend/commits/d6845989896) - Configuration added to consistent-css-prop-usage where it is now possible to specify what function names the rule should lint against, and what position is recommended for styles (top or bottom).
+
 ## 8.7.0
 
 ### Minor Changes

package/README.md

@@ -49,7 +49,7 @@ module.exports = {
 
 | Rule                                                                                                    | Description                                                                                                                                                                      | Recommended | Fixable | Suggestions |
 | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------- | ----------- |
-| <a href="./src/rules/consistent-css-prop-usage/README.md">consistent-css-prop-usage</a>                 | Ensures consistency with CSS and xcss prop usages                                                                                                                                | Yes         | Yes     |             |
+| <a href="./src/rules/consistent-css-prop-usage/README.md">consistent-css-prop-usage</a>                 | Ensures consistency with `css` and `xcss` prop usages                                                                                                                            | Yes         | Yes     |             |
 | <a href="./src/rules/ensure-design-token-usage/README.md">ensure-design-token-usage</a>                 | Enforces usage of design tokens rather than hard-coded values.                                                                                                                   | Yes         | Yes     | Yes         |
 | <a href="./src/rules/ensure-design-token-usage-preview/README.md">ensure-design-token-usage/preview</a> | Enforces usage of pre-release design tokens rather than hard-coded values.                                                                                                       |             | Yes     | Yes         |
 | <a href="./src/rules/icon-label/README.md">icon-label</a>                                               | Enforces accessible usage of icon labels when composed with Atlassian Design System components.                                                                                  | Yes         | Yes     |             |

package/constellation/index/usage.mdx

@@ -13,7 +13,7 @@ This plugin contains rules that should be used when working with the [Atlassian
 
 | Rule                                                                               | Description                                                                                                                                                                      | Recommended | Fixable | Suggestions |
 | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------- | ----------- |
-| <a href="#consistent-css-prop-usage">consistent-css-prop-usage</a>                 | Ensures consistency with CSS and xcss prop usages                                                                                                                                | Yes         | Yes     |             |
+| <a href="#consistent-css-prop-usage">consistent-css-prop-usage</a>                 | Ensures consistency with `css` and `xcss` prop usages                                                                                                                            | Yes         | Yes     |             |
 | <a href="#ensure-design-token-usage">ensure-design-token-usage</a>                 | Enforces usage of design tokens rather than hard-coded values.                                                                                                                   | Yes         | Yes     | Yes         |
 | <a href="#ensure-design-token-usage-preview">ensure-design-token-usage/preview</a> | Enforces usage of pre-release design tokens rather than hard-coded values.                                                                                                       |             | Yes     | Yes         |
 | <a href="#icon-label">icon-label</a>                                               | Enforces accessible usage of icon labels when composed with Atlassian Design System components.                                                                                  | Yes         | Yes     |             |
@@ -51,7 +51,9 @@ This rule checks for the following cases:
 - When styles are coming from outside of the module i.e. using imports.
 - When styles are spread inside another styles and not using array composition.
 
-This rule has no options.
+All the above can also work for custom `css` functions, such as `xcss` (https://atlassian.design/components/primitives/xcss/).
+
+This rule has options - see below.
 
 <h3>Examples</h3>
 
@@ -128,6 +130,19 @@ function Button({ children }) {
 }
 ```
 
+<h3>Options</h3>
+
+This rule comes with options to support different repository configurations.
+
+#### cssFunctions
+
+An array of function names the linting rule should target. Defaults to `['css', 'xcss']`.
+
+#### stylesPlacement
+
+The rule prevents inline styles from being created. This option defines what the error message should say: "(...) styles at the top (...)" or "(...) styles at the bottom (...)".
+Defaults to `top`.
+
 ## ensure-design-token-usage
 
 Using design tokens results in a harmonious experience for end users whilst providing theming and consistency.

package/dist/cjs/rules/consistent-css-prop-usage/index.js

@@ -5,12 +5,14 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
 var _eslintCodemodUtils = require("eslint-codemod-utils");
+var _assign = _interopRequireDefault(require("lodash/assign"));
 var _createRule = require("../utils/create-rule");
 var declarationSuffix = 'Styles';
-function isCssCallExpression(node) {
-  return !!((0, _eslintCodemodUtils.isNodeOfType)(node, 'CallExpression') && node.callee && node.callee.type === 'Identifier' && (node.callee.name === 'css' || node.callee.name === 'xcss') && node.arguments.length && node.arguments[0].type === 'ObjectExpression');
+function isCssCallExpression(node, cssFunctions) {
+  return !!((0, _eslintCodemodUtils.isNodeOfType)(node, 'CallExpression') && node.callee && node.callee.type === 'Identifier' && cssFunctions.includes(node.callee.name) && node.arguments.length && node.arguments[0].type === 'ObjectExpression');
 }
 function findSpreadProperties(node) {
   // @ts-ignore
@@ -20,7 +22,7 @@ function findSpreadProperties(node) {
     property.type === 'ExperimentalSpreadProperty';
   });
 }
-function analyzeIdentifier(context, sourceIdentifier) {
+function analyzeIdentifier(context, sourceIdentifier, configuration) {
   var _getIdentifierInParen;
   var scope = context.getScope();
   var _ref = ((_getIdentifierInParen = (0, _eslintCodemodUtils.getIdentifierInParentScope)(scope, sourceIdentifier.name)) === null || _getIdentifierInParen === void 0 ? void 0 : _getIdentifierInParen.identifiers) || [],
@@ -42,11 +44,11 @@ function analyzeIdentifier(context, sourceIdentifier) {
     // When variable is declared inside the component
     context.report({
       node: sourceIdentifier,
-      messageId: 'cssOnTopOfModule'
+      messageId: configuration.stylesPlacement === 'bottom' ? 'cssAtBottomOfModule' : 'cssOnTopOfModule'
     });
     return;
   }
-  if (identifier.parent && identifier.parent.init && !isCssCallExpression(identifier.parent.init)) {
+  if (identifier.parent && identifier.parent.init && !isCssCallExpression(identifier.parent.init, configuration.cssFunctions)) {
     // When variable value is not of type css({})
     context.report({
       node: identifier,
@@ -65,117 +67,127 @@ function analyzeIdentifier(context, sourceIdentifier) {
     });
   }
 }
-function traverseExpression(context, expression) {
-  switch (expression.type) {
-    case 'Identifier':
-      // {styles}
-      // We've found an identifier - time to analyze it!
-      analyzeIdentifier(context, expression);
-      break;
-    case 'ArrayExpression':
-      // {[styles, moreStyles]}
-      // We've found an array expression - let's traverse again over each element individually.
-      expression.elements.forEach(function (element) {
-        return traverseExpression(context, element);
-      });
-      break;
-    case 'LogicalExpression':
-      // {isEnabled && styles}
-      // We've found a logical expression - we're only interested in the right expression so
-      // let's traverse that and see what it is!
-      traverseExpression(context, expression.right);
-      break;
-    case 'ConditionalExpression':
-      // {isEnabled ? styles : null}
-      // We've found a conditional expression - we're only interested in the consequent and
-      // alternate (styles : null)
-      traverseExpression(context, expression.consequent);
-      traverseExpression(context, expression.alternate);
-      break;
-    case 'CallExpression':
-    case 'ObjectExpression':
-    case 'TaggedTemplateExpression':
-    case 'TemplateLiteral':
-      // We've found elements that shouldn't be here! Report an error.
-      context.report({
-        node: expression,
-        messageId: 'cssOnTopOfModule'
-      });
-      break;
-    default:
-      // Do nothing!
-      break;
+var traverseExpressionWithConfig = function traverseExpressionWithConfig(context, expression, configuration) {
+  function traverseExpression(expression) {
+    switch (expression.type) {
+      case 'Identifier':
+        // {styles}
+        // We've found an identifier - time to analyze it!
+        analyzeIdentifier(context, expression, configuration);
+        break;
+      case 'ArrayExpression':
+        // {[styles, moreStyles]}
+        // We've found an array expression - let's traverse again over each element individually.
+        expression.elements.forEach(function (element) {
+          return traverseExpression(element);
+        });
+        break;
+      case 'LogicalExpression':
+        // {isEnabled && styles}
+        // We've found a logical expression - we're only interested in the right expression so
+        // let's traverse that and see what it is!
+        traverseExpression(expression.right);
+        break;
+      case 'ConditionalExpression':
+        // {isEnabled ? styles : null}
+        // We've found a conditional expression - we're only interested in the consequent and
+        // alternate (styles : null)
+        traverseExpression(expression.consequent);
+        traverseExpression(expression.alternate);
+        break;
+      case 'CallExpression':
+      case 'ObjectExpression':
+      case 'TaggedTemplateExpression':
+      case 'TemplateLiteral':
+        // We've found elements that shouldn't be here! Report an error.
+        context.report({
+          node: expression,
+          messageId: configuration.stylesPlacement === 'bottom' ? 'cssAtBottomOfModule' : 'cssOnTopOfModule'
+        });
+        break;
+      default:
+        // Do nothing!
+        break;
+    }
   }
-}
+  traverseExpression(expression);
+};
+var defaultConfig = {
+  cssFunctions: ['css', 'xcss'],
+  stylesPlacement: 'top'
+};
 var rule = (0, _createRule.createLintRule)({
   meta: {
     name: 'consistent-css-prop-usage',
     docs: {
-      description: 'Ensures consistency with CSS and xcss prop usages',
+      description: 'Ensures consistency with `css` and `xcss` prop usages',
       url: 'https://developer.atlassian.com/cloud/framework/atlassian-frontend/development/styling',
       recommended: true,
       severity: 'error'
     },
     fixable: 'code',
     messages: {
-      cssOnTopOfModule: "Create styles at the top of the module scope using the css function.",
+      cssOnTopOfModule: "Create styles at the top of the module scope using the respective css function.",
+      cssAtBottomOfModule: "Create styles at the bottom of the module scope using the respective css function.",
       cssObjectTypeOnly: "Create styles using objects passed to the css function.",
       cssInModule: "Imported styles should not be used, instead define in the module, import a component, or use a design token.",
-      cssArrayStylesOnly: "Compose styles with an array on the CSS prop instead of using object spread.",
+      cssArrayStylesOnly: "Compose styles with an array on the css prop instead of using object spread.",
       shouldEndInStyles: 'Declared styles should end in "styles".'
     }
   },
   create: function create(context) {
-    return {
-      'CallExpression[callee.name=css], CallExpression[callee.name=xcss]': function CallExpressionCalleeNameCssCallExpressionCalleeNameXcss(node) {
-        if (node.parent.type !== 'VariableDeclarator') {
-          // We aren't interested in these that don't have a parent.
-          return;
+    var _ref3;
+    var mergedConfig = (0, _assign.default)({}, defaultConfig, context.options[0]);
+    var callSelector = mergedConfig.cssFunctions.map(function (fn) {
+      return "CallExpression[callee.name=".concat(fn, "]");
+    }).join(',');
+    return _ref3 = {}, (0, _defineProperty2.default)(_ref3, callSelector, function (node) {
+      if (node.parent.type !== 'VariableDeclarator') {
+        // We aren't interested in these that don't have a parent.
+        return;
+      }
+      var identifier = node.parent.id;
+      if (identifier.type === 'Identifier' && identifier.name.endsWith(declarationSuffix)) {
+        // Already prefixed! Nothing to do.
+        return;
+      }
+      context.report({
+        node: identifier,
+        messageId: 'shouldEndInStyles',
+        fix: function fix(fixer) {
+          var _context$getScope$var;
+          var identifierName = identifier.type === 'Identifier' ? identifier.name : '';
+          var references = ((_context$getScope$var = context.getScope().variables.find(function (varb) {
+            return varb.name === identifierName;
+          })) === null || _context$getScope$var === void 0 ? void 0 : _context$getScope$var.references) || [];
+          var newIdentifierName = "".concat(identifierName
+          // Remove "Style" if it is already defined.
+          .replace(/Style$/, '')).concat(declarationSuffix);
+          return references.filter(function (ref) {
+            return ref.identifier.name === identifierName;
+          }).map(function (ref) {
+            if (ref.identifier.parent && ref.identifier.parent.shorthand) {
+              return fixer.replaceText(ref.identifier, "".concat(identifierName, ": ").concat(newIdentifierName));
+            }
+            return fixer.replaceText(ref.identifier, newIdentifierName);
+          });
         }
-        var identifier = node.parent.id;
-        if (identifier.type === 'Identifier' && identifier.name.endsWith(declarationSuffix)) {
-          // Already prefixed! Nothing to do.
+      });
+    }), (0, _defineProperty2.default)(_ref3, "JSXAttribute", function JSXAttribute(node) {
+      var name = node.name,
+        value = node.value;
+      if (name.type === 'JSXIdentifier' && mergedConfig.cssFunctions.includes(name.name)) {
+        // When not a jsx expression. For eg. css=""
+        if ((value === null || value === void 0 ? void 0 : value.type) !== 'JSXExpressionContainer') {
+          context.report({
+            node: value,
+            messageId: mergedConfig.stylesPlacement === 'bottom' ? 'cssAtBottomOfModule' : 'cssOnTopOfModule'
+          });
           return;
         }
-        context.report({
-          node: identifier,
-          messageId: 'shouldEndInStyles',
-          fix: function fix(fixer) {
-            var _context$getScope$var;
-            var identifierName = identifier.type === 'Identifier' ? identifier.name : '';
-            var references = ((_context$getScope$var = context.getScope().variables.find(function (varb) {
-              return varb.name === identifierName;
-            })) === null || _context$getScope$var === void 0 ? void 0 : _context$getScope$var.references) || [];
-            var newIdentifierName = "".concat(identifierName
-            // Remove "Style" if it is already defined.
-            .replace(/Style$/, '')).concat(declarationSuffix);
-            return references.filter(function (ref) {
-              return ref.identifier.name === identifierName;
-            }).map(function (ref) {
-              if (ref.identifier.parent && ref.identifier.parent.shorthand) {
-                return fixer.replaceText(ref.identifier, "".concat(identifierName, ": ").concat(newIdentifierName));
-              }
-              return fixer.replaceText(ref.identifier, newIdentifierName);
-            });
-          }
-        });
-      },
-      JSXAttribute: function JSXAttribute(node) {
-        var name = node.name,
-          value = node.value;
-        if (name.type === 'JSXIdentifier' && (name.name === 'css' || name.name === 'xcss')) {
-          // When not a jsx expression. For eg. css=""
-          if ((value === null || value === void 0 ? void 0 : value.type) !== 'JSXExpressionContainer') {
-            context.report({
-              node: value,
-              messageId: 'cssOnTopOfModule'
-            });
-            return;
-          }
-          traverseExpression(context, value.expression);
-        }
+        traverseExpressionWithConfig(context, value.expression, mergedConfig);
       }
-    };
+    }), _ref3;
   }
 });
 var _default = rule;

package/dist/cjs/rules/consistent-css-prop-usage/types.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/dist/cjs/rules/ensure-design-token-usage/index.js

@@ -79,8 +79,20 @@ var createWithConfig = function createWithConfig(initialConfig) {
           if (domains.length === 0 || (0, _isNode.isDecendantOfGlobalToken)(node.value)) {
             return;
           }
-          if ((0, _eslintCodemodUtils.isNodeOfType)(node.value, 'TemplateLiteral') && node.value.expressions.some(_isNode.isDecendantOfGlobalToken)) {
-            return;
+          if ((0, _eslintCodemodUtils.isNodeOfType)(node.value, 'TemplateLiteral')) {
+            var value = (0, _utils.getValueFromTemplateLiteralRaw)(node.value, context);
+            if (Array.isArray(value) && value.some(_utils.isCalc)) {
+              return context.report({
+                node: node,
+                messageId: 'noCalcUsage',
+                data: {
+                  payload: "".concat(propertyName)
+                }
+              });
+            }
+            if (node.value.expressions.some(_isNode.isDecendantOfGlobalToken)) {
+              return;
+            }
           }
           if (domains.includes('color')) {
             return (0, _color.lintObjectForColor)(node, context, config);
@@ -172,6 +184,16 @@ var createWithConfig = function createWithConfig(initialConfig) {
               if (!originalValue) {
                 return originalValue;
               }
+              if ((0, _utils.isCalc)(originalValue)) {
+                context.report({
+                  node: node,
+                  messageId: 'noCalcUsage',
+                  data: {
+                    payload: "".concat(propertyName)
+                  }
+                });
+                return originalValue;
+              }
               if ((0, _utils.isTokenValueString)(originalValue)) {
                 // if the value is already valid, nothing to report or replace
                 return originalValue;

package/dist/cjs/rules/ensure-design-token-usage/rule-meta.js

@@ -42,6 +42,7 @@ var ruleMeta = {
     noRawRadiusValues: 'The use of shape tokens is preferred over the direct application of border properties.\n\n@meta <<{{payload}}>>',
     noRawSpacingValues: 'The use of spacing primitives or tokens is preferred over the direct application of spacing properties.\n\n@meta <<{{payload}}>>',
     autofixesPossible: 'Automated corrections available for spacing values. Apply autofix to replace values with appropriate tokens',
+    noCalcUsage: 'The use of space tokens is preferred over using the CSS calc function. If using a value that is not aligned to the spacing scale, consider aligning to the scale and using tokens instead.',
     hardCodedColor: "Colors can be sourced from the global theme using the token function.",
     legacyElevation: "Elevations can be sourced from the global theme using the token function made of both a background and shadow. Use \"card\" for card elevations, and \"overlay\" for anything else that should appear elevated."
   }

package/dist/cjs/rules/ensure-design-token-usage/spacing.js

@@ -22,13 +22,19 @@ var lintObjectForSpacing = function lintObjectForSpacing(node, context, ruleConf
     });
     return;
   }
+  var propertyName = node.key.name;
+  var isFontFamily = /fontFamily/.test(propertyName);
 
-  // Don't report on CSS calc function
+  // Report on CSS calc function for strings
   if ((0, _eslintCodemodUtils.isNodeOfType)(node.value, 'Literal') && (0, _utils.isCalc)(node.value.value)) {
-    return;
+    return context.report({
+      node: node,
+      messageId: 'noCalcUsage',
+      data: {
+        payload: "".concat(propertyName)
+      }
+    });
   }
-  var propertyName = node.key.name;
-  var isFontFamily = /fontFamily/.test(propertyName);
   var value = (0, _utils.getValue)(node.value, context);
 
   // Value is a token string (e.g. set via a variable)
@@ -87,6 +93,15 @@ var lintObjectForSpacing = function lintObjectForSpacing(node, context, ruleConf
    * { padding: '8px 0px' }
    */
   valuesForProperty.forEach(function (val) {
+    if ((0, _utils.isCalc)(val)) {
+      return context.report({
+        node: node,
+        messageId: 'noCalcUsage',
+        data: {
+          payload: "".concat(propertyName, ":").concat(val)
+        }
+      });
+    }
     var pixelValue = (0, _utils.emToPixels)(val, fontSize);
 
     // Do not report or suggest a token to replace 0 or auto

package/dist/cjs/rules/ensure-design-token-usage/utils.js

@@ -13,7 +13,7 @@ exports.getFontSizeValueInScope = getFontSizeValueInScope;
 exports.getRawExpression = void 0;
 exports.getTokenNodeForValue = getTokenNodeForValue;
 exports.getTokenReplacement = getTokenReplacement;
-exports.getValueFromShorthand = exports.getValue = void 0;
+exports.getValueFromTemplateLiteralRaw = exports.getValueFromShorthand = exports.getValue = void 0;
 exports.includesTokenString = includesTokenString;
 exports.insertTokensImport = insertTokensImport;
 exports.isSpacingProperty = exports.isCalc = exports.isAuto = void 0;
@@ -207,7 +207,7 @@ var getValueFromUnaryExpression = function getValueFromUnaryExpression(node, con
  * // results in [2, 4, 0]
  * ```
  */
-var getValueFromTemplateLiteral = function getValueFromTemplateLiteral(node, context) {
+var getValueFromTemplateLiteralRaw = function getValueFromTemplateLiteralRaw(node, context) {
   if (!(0, _eslintCodemodUtils.isNodeOfType)(node, "TemplateLiteral")) {
     return null;
   }
@@ -218,7 +218,12 @@ var getValueFromTemplateLiteral = function getValueFromTemplateLiteral(node, con
   if (fontFamily.test(combinedString)) {
     return combinedString;
   }
-  return combinedString.split(' ').map(removePixelSuffix);
+  return combinedString.split(' ');
+};
+exports.getValueFromTemplateLiteralRaw = getValueFromTemplateLiteralRaw;
+var getValueFromTemplateLiteral = function getValueFromTemplateLiteral(node, context) {
+  var value = getValueFromTemplateLiteralRaw(node, context);
+  return Array.isArray(value) ? value.map(removePixelSuffix) : value;
 };
 var getValueFromBinaryExpression = function getValueFromBinaryExpression(node, context) {
   if (!(0, _eslintCodemodUtils.isNodeOfType)(node, 'BinaryExpression')) {
@@ -252,7 +257,7 @@ var emToPixels = function emToPixels(value, fontSize) {
 exports.emToPixels = emToPixels;
 var percentageOrEmOrAuto = /(%$)|(\d+em$)|(auto$)/;
 var removePixelSuffix = function removePixelSuffix(value) {
-  if (typeof value === 'string' && percentageOrEmOrAuto.test(value)) {
+  if (typeof value === 'string' && (percentageOrEmOrAuto.test(value) || isCalc(value))) {
     return value;
   }
   return Number(typeof value === 'string' ? value.replace('px', '') : value);