@atlaskit/eslint-plugin-design-system 4.11.2 → 4.12.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @atlaskit/eslint-plugin-design-system
 
+## 4.12.1
+
+### Patch Changes
+
+- [`e86c57a4a60`](https://bitbucket.org/atlassian/atlassian-frontend/commits/e86c57a4a60) - Improves the `no-raw-spacing-values` rule to include an autofixer. Spacing values that can be resolved to a token will be.
+
+## 4.12.0
+
+### Minor Changes
+
+- [`109c705cd9c`](https://bitbucket.org/atlassian/atlassian-frontend/commits/109c705cd9c) - [ux] Adds a new case to the no-unsafe-design-token-usage rule to lint against uses of 'experimental' tokens and automatically replace them with their replacement (either a token or a fallback) via a fixer.
+
 ## 4.11.2
 
 ### Patch Changes

package/constellation/index/examples.mdx

@@ -2,4 +2,312 @@
 order: 0
 ---
 
-examples
+## ensure-design-token-usage
+
+Ensures that the codebase uses the global `token` function, rather than hard-coded values. This ruleset is great for codebases that are starting to adopt tokens and those that have already adopted tokens. This ruleset also prevents new contributors from accidentally adding hard-coded color values.
+
+👎 Example of **incorrect** code for this rule:
+
+```jsx
+css({
+  color: 'red',
+          ^^^
+});
+```
+
+```jsx
+css({
+  boxShadow: '0px 1px 1px #161A1D32',
+                          ^^^^^^^^^
+})
+```
+
+```jsx
+import { e100 } from '@atlaskit/theme/elevation';
+
+css`
+  ${e100};
+    ^^^^
+`;
+```
+
+```jsx
+import { B100 } from '@atlaskit/theme/colors';
+
+css({
+  color: B100,
+         ^^^^
+});
+```
+
+👍 Example of **correct** code for this rule:
+
+```jsx
+import { token } from '@atlaskit/tokens';
+
+css({
+  boxShadow: token('elevation.shadow.card'),
+});
+```
+
+```jsx
+import { token } from '@atlaskit/tokens';
+
+css`
+  color: ${token('color.text.highemphasis')};
+`;
+```
+
+## no-deprecated-design-token-usage
+
+Will catch deprecated token usage and autofix a replacement.
+
+It's recommended to set this rule to "warn" on error to allow for new and old tokens to exist side-by-side for the duration of the deprecation period and avoid big-bang migrations.
+
+Once the deprecation period is over for a token, it will be moved into `deleted` state, at which point the counterpart of this rule `eslint-plugin-design-system/no-unsafe-design-token-usage` will begin to throw errors.
+
+Run `eslint --fix` will automatically apply replacement tokens.
+
+👎 Example of **incorrect** code for this rule:
+
+```jsx
+import { token } from '@atlaskit/tokens';
+
+css({
+  color: token('i.am.deprecated'), // 👎
+});
+```
+
+```jsx
+css({
+  color: token('i.am.a.token'), // 👍
+});
+```
+
+## no-unsafe-design-token-usage
+
+Ensures usages of the `token` function are done correctly, so that current token names are being used, and the resulting `var(--some-token)` statements aren't being used. This ruleset is great for codebases that have already adopted tokens.
+
+👎 Example of **incorrect** code for this rule:
+
+```jsx
+const textColor = 'red';
+
+css({
+  color: textColor,
+         ^^^^^^^^^
+});
+```
+
+```jsx
+css({
+  boxShadow: '0px 1px 1px var(--ds-accent-subtleBlue)',
+                          ^^^^^^^^^^^^^^^^^^^^^^^^^^
+})
+```
+
+👍 Example of **correct** code for this rule:
+
+```jsx
+import { token } from '@atlaskit/tokens';
+
+css({
+  boxShadow: token('elevation.shadow.card'),
+});
+```
+
+```jsx
+import { token } from '@atlaskit/tokens';
+
+css`
+  color: ${(token('color.text.highemphasis'), N20)};
+`;
+```
+
+## icon-label
+
+Enforces accessible usage of icon labels when composed with other Design System components.
+
+👎 Example of **incorrect** code for this rule:
+
+```jsx
+import ActivityIcon from '@atlaskit/icon/glyph/activity'
+
+<ActivityIcon>
+^^^^^^^^^^^^^^ missing `label` prop
+```
+
+```jsx
+import ActivityIcon from '@atlaskit/icon/glyph/activity'
+
+<Button iconLeft={<ActivityIcon label="">} />
+                                ^^^^^ label should be defined
+```
+
+```jsx
+import ActivityIcon from '@atlaskit/icon/glyph/activity'
+
+<ButtonItem iconBefore={<ActivityIcon label="">}>
+                                      ^^^^^ label should not be defined
+  My activity
+</ButtonItem>
+```
+
+👍 Example of **correct** code for this rule:
+
+```jsx
+import ActivityIcon from '@atlaskit/icon/glyph/activity'
+
+<ActivityIcon label="Activity">
+```
+
+```jsx
+import ActivityIcon from '@atlaskit/icon/glyph/activity'
+
+<Button iconLeft={<ActivityIcon label="Activity">} />
+```
+
+```jsx
+import ActivityIcon from '@atlaskit/icon/glyph/activity'
+
+<ButtonItem iconBefore={<ActivityIcon label="">}>
+  My activity
+</ButtonItem>
+```
+
+## no-banned-imports
+
+Prevents usage of private or experimental Atlassian Design System packages.
+
+👎 Example of **incorrect** code for this rule:
+
+```ts
+import noop from '@atlaskit/ds-lib/noop';
+                  ^^^^^^^^^^^^^^^^^^^^^
+```
+
+```ts
+import { Text } from '@atlaskit/ds-explorations';
+                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+```
+
+## no-deprecated-api-usage
+
+Ensures usage of current Atlassian Design System API usage.
+
+👎 Example of **incorrect** code for this rule:
+
+```jsx
+import { ButtonItem } from '@atlaskit/menu';
+
+const Element = () => (
+  <ButtonItem cssFn={cssFn()} />
+              ^^^^
+);
+```
+
+```jsx
+import Drawer from '@atlaskit/drawer';
+
+const Element = () => (
+  <Drawer overrides={overrides} />
+              ^^^^
+);
+```
+
+👍 Example of **correct** code for this rule:
+
+```jsx
+import { SomeElement } from 'some-other-library';
+
+const Element = () => <SomeElement cssFn={cssFn()} />;
+```
+
+```jsx
+import { ButtonItem } from '@atlaskit/menu';
+
+const Element = () => <ButtonItem />;
+```
+
+```jsx
+import Drawer from '@atlaskit/drawer';
+
+const Element = () => <Drawer />;
+```
+
+## no-deprecated-imports
+
+Ensures usage of current Atlassian Design System dependencies.
+
+👎 Example of **incorrect** code for this rule:
+
+```ts
+import Item from '@atlaskit/item';
+                  ^^^^^^^^^^^^^^
+```
+
+```ts
+import GlobalNav from '@atlaskit/global-navigation';
+                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+```
+
+👍 Example of **correct** code for this rule:
+
+```ts
+import Modal from '@atlaskit/modal-dialog';
+```
+
+```ts
+import { ButtonItem } from '@atlaskit/menu';
+```
+
+## use-visually-hidden
+
+This rule makes Design System consumers aware of the existing solutions.
+
+👎 Example of **incorrect** code for this rule:
+
+```jsx
+import { css } from '@emotion/core';
+
+const visuallyHiddenStyles = css({
+  width: '1px',
+  height: '1px',
+  padding: '0',
+  position: 'absolute',
+  border: '0',
+  clip: 'rect(1px, 1px, 1px, 1px)',
+  overflow: 'hidden',
+  whiteSpace: 'nowrap',
+});
+^^^^
+```
+
+```jsx
+import styled from '@emotion/styled';
+
+const VisuallyHidden = styled.span`
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  position: absolute;
+  border: 0;
+  clip: rect(1px, 1px, 1px, 1px);
+  overflow: hidden;
+  whiteSpace: nowrap;
+`;
+^^^^
+```
+
+```jsx
+import { visuallyHidden } from '@atlaskit/theme/constants';
+
+const VisuallyHidden = styled.span`${visuallyHidden()}`;
+                                     ^^^^^^^^^^^^^^
+```
+
+👍 Example of **correct** code for this rule:
+
+```jsx
+import VisuallyHidden from '@atlaskit/visually-hidden';
+```

package/constellation/index/usage.mdx

@@ -2,4 +2,44 @@
 order: 2
 ---
 
-usage
+This plugin contains rules that should be used with the Atlassian Design System.
+Where possible, these rules come with auto fixers.
+
+You can read more about configuring eslint in their [documentation](https://eslint.org/docs/user-guide/configuring).
+
+## Configuration
+
+Add the plugin to your `.eslintrc.js` file.
+
+```diff
+module.exports = {
+  plugins: [
++    '@atlaskit/design-system',
+  ],
+};
+```
+
+Extend the configuration file.
+
+```diff
+module.exports = {
+  extends: [
++    'plugin:@atlaskit/design-system/recommended',
+  ],
+};
+```
+
+Enable any desired rules. The rules shown below are strongly recommended.
+
+```diff
+module.exports = {
+  rules: {
++    '@atlaskit/design-system/ensure-design-token-usage': ['error', { 'shouldEnsureFallbackUsage': true }],
++    '@atlaskit/design-system/no-deprecated-design-token-usage': 'warn',
++    '@atlaskit/design-system/no-unsafe-design-token-usage': ['error', { 'shouldEnsureFallbackUsage': true }],
++    '@atlaskit/design-system/use-visually-hidden': 'error',
++    '@atlaskit/design-system/no-deprecated-imports': 'error',
++    '@atlaskit/design-system/no-deprecated-apis': 'error'
+    }
+};
+```

package/dist/cjs/index.js

@@ -9,6 +9,8 @@ exports.rules = exports.configs = void 0;
 
 var _ensureDesignTokenUsage = _interopRequireDefault(require("./rules/ensure-design-token-usage"));
 
+var _ensureDesignTokenUsageSpacing = _interopRequireDefault(require("./rules/ensure-design-token-usage-spacing"));
+
 var _iconLabel = _interopRequireDefault(require("./rules/icon-label"));
 
 var _noBannedImports = _interopRequireDefault(require("./rules/no-banned-imports"));
@@ -19,8 +21,6 @@ var _noDeprecatedDesignTokenUsage = _interopRequireDefault(require("./rules/no-d
 
 var _noDeprecatedImports = _interopRequireDefault(require("./rules/no-deprecated-imports"));
 
-var _noRawSpacingValues = _interopRequireDefault(require("./rules/no-raw-spacing-values"));
-
 var _noUnsafeDesignTokenUsage = _interopRequireDefault(require("./rules/no-unsafe-design-token-usage"));
 
 var _useVisuallyHidden = _interopRequireDefault(require("./rules/use-visually-hidden"));
@@ -34,7 +34,7 @@ var rules = {
   'no-banned-imports': _noBannedImports.default,
   'no-unsafe-design-token-usage': _noUnsafeDesignTokenUsage.default,
   'use-visually-hidden': _useVisuallyHidden.default,
-  'no-raw-spacing-values': _noRawSpacingValues.default
+  'ensure-design-token-usage-spacing': _ensureDesignTokenUsageSpacing.default
 };
 exports.rules = rules;
 var configs = {
@@ -57,7 +57,8 @@ var configs = {
       '@atlaskit/design-system/use-visually-hidden': 'error',
       '@atlaskit/design-system/ensure-design-token-usage': 'error',
       '@atlaskit/design-system/no-banned-imports': 'error',
-      '@atlaskit/design-system/no-raw-spacing-values': 'error'
+      '@atlaskit/design-system/no-unsafe-design-token-usage': 'error',
+      '@atlaskit/design-system/ensure-design-token-usage-spacing': 'error'
     }
   }
 };

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

@@ -0,0 +1,277 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+
+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 _spacingRaw = _interopRequireDefault(require("@atlaskit/tokens/spacing-raw"));
+
+var _isNode = require("../utils/is-node");
+
+var _utils = require("./utils");
+
+function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it.return != null) it.return(); } finally { if (didErr) throw err; } } }; }
+
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) { arr2[i] = arr[i]; } return arr2; }
+
+function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); enumerableOnly && (symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; })), keys.push.apply(keys, symbols); } return keys; }
+
+function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = null != arguments[i] ? arguments[i] : {}; i % 2 ? ownKeys(Object(source), !0).forEach(function (key) { (0, _defineProperty2.default)(target, key, source[key]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)) : ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } return target; }
+
+var spacingValueToToken = Object.fromEntries(_spacingRaw.default.map(function (token) {
+  return [token.value, token.name];
+}));
+/**
+ * @example
+ * ```
+ * '8px' => token('spacing.scale.100', '8px')
+ * ```
+ */
+
+function pixelValueToSpacingTokenNode(pixelValueString) {
+  var _spacingValueToToken$;
+
+  return (0, _eslintCodemodUtils.callExpression)({
+    callee: (0, _eslintCodemodUtils.identifier)({
+      name: 'token'
+    }),
+    arguments: [(0, _eslintCodemodUtils.literal)({
+      value: "'".concat((_spacingValueToToken$ = spacingValueToToken[pixelValueString]) !== null && _spacingValueToToken$ !== void 0 ? _spacingValueToToken$ : '', "'")
+    }), (0, _eslintCodemodUtils.literal)("'".concat(pixelValueString, "'"))],
+    optional: false
+  });
+}
+
+var rule = {
+  meta: {
+    type: 'problem',
+    fixable: 'code',
+    docs: {
+      description: 'Rule ensures all spacing CSS properties apply a matching spacing token',
+      recommended: true
+    },
+    messages: {
+      noMarginProperties: 'The use of margin is considered a dangerous as it breaks the component model. Prefer the application of `gap` via CSS Flexbox or Grid to achieve the same result and control the layout from the parent.',
+      noRawSpacingValues: 'The use of spacing primitives or tokens is preferred over the direct application of spacing properties.\n\n@meta <<{{payload}}>>'
+    }
+  },
+  create: function create(context) {
+    return {
+      // CSSObjectExpression
+      // const styles = css({ color: 'red', margin: '4px' })
+      'CallExpression[callee.name=css] > ObjectExpression': function CallExpressionCalleeNameCssObjectExpression(parentNode) {
+        if (!(0, _eslintCodemodUtils.isNodeOfType)(parentNode, 'ObjectExpression')) {
+          return;
+        }
+        /**
+         * We do this in case the fontSize for a style object is declared alongside the `em` or `lineHeight` declaration
+         */
+
+
+        var fontSizeNode = parentNode.properties.find(function (node) {
+          if (!(0, _eslintCodemodUtils.isNodeOfType)(node, 'Property')) {
+            return;
+          }
+
+          if (!(0, _eslintCodemodUtils.isNodeOfType)(node.key, 'Identifier')) {
+            return;
+          }
+
+          return node.key.name === 'fontSize';
+        });
+        var fontSizeValue = (0, _utils.getValue)( // @ts-ignore
+        (0, _eslintCodemodUtils.isNodeOfType)(fontSizeNode, 'Property') && fontSizeNode.value, context);
+        var fontSize = Array.isArray(fontSizeValue) ? fontSizeValue[0] : fontSizeValue;
+        parentNode.properties.forEach(function (node) {
+          if (!(0, _eslintCodemodUtils.isNodeOfType)(node, 'Property')) {
+            return;
+          }
+
+          if (!(0, _eslintCodemodUtils.isNodeOfType)(node.key, 'Identifier')) {
+            return;
+          }
+
+          if (!(0, _utils.isSpacingProperty)(node.key.name)) {
+            return;
+          }
+
+          if ((0, _isNode.isDecendantOfGlobalToken)(node.value)) {
+            return;
+          }
+
+          if (node.value.type === 'Literal' && !(0, _utils.isValidSpacingValue)(node.value.value, fontSize)) {
+            context.report({
+              node: node,
+              messageId: 'noRawSpacingValues',
+              data: {
+                payload: "NaN:".concat(node.value.value)
+              }
+            });
+            return;
+          }
+
+          var value = (0, _utils.getValue)(node.value, context); // value is either NaN or it can't be resolved eg, em, 100% etc...
+
+          if (!(value && (0, _utils.isValidSpacingValue)(value, fontSize))) {
+            return context.report({
+              node: node,
+              messageId: 'noRawSpacingValues',
+              data: {
+                payload: "NaN:".concat(value)
+              }
+            });
+          }
+
+          var values = Array.isArray(value) ? value : [value]; // value is a single value so we can apply a more robust approach to our fix
+
+          if (values.length === 1) {
+            var _values = (0, _slicedToArray2.default)(values, 1),
+                _value = _values[0];
+
+            var pixelValue = (0, _utils.emToPixels)(_value, fontSize);
+            return context.report({
+              node: node,
+              messageId: 'noRawSpacingValues',
+              data: {
+                payload: "".concat(node.key.name, ":").concat(pixelValue)
+              },
+              fix: function fix(fixer) {
+                var _node$loc;
+
+                if (!/padding|margin|gap/.test(node.key.name)) {
+                  return null;
+                }
+
+                var pixelValueString = "".concat(pixelValue, "px");
+                var tokenName = spacingValueToToken[pixelValueString];
+
+                if (!tokenName) {
+                  return null;
+                }
+
+                return [fixer.insertTextBefore(node, "// TODO Delete this comment after verifying spacing token -> previous value `".concat((0, _eslintCodemodUtils.node)(node.value), "`\n").concat(' '.padStart(((_node$loc = node.loc) === null || _node$loc === void 0 ? void 0 : _node$loc.start.column) || 0))), fixer.replaceText(node, (0, _eslintCodemodUtils.property)(_objectSpread(_objectSpread({}, node), {}, {
+                  value: pixelValueToSpacingTokenNode(pixelValueString)
+                })).toString())];
+              }
+            });
+          }
+          /**
+           * Compound values are hard to deal with / replace because we need to find/replace strings inside an
+           * estree node.
+           *
+           * @example
+           * { padding: '8px 0px' } // two values we don't try and apply the fixer
+           */
+
+
+          values.forEach(function (val, index) {
+            var pixelValue = (0, _utils.emToPixels)(val, fontSize);
+            context.report({
+              node: node,
+              messageId: 'noRawSpacingValues',
+              data: {
+                payload: "".concat(node.key.name, ":").concat(pixelValue)
+              },
+              fix: index === 0 ? function (fixer) {
+                var allResolvableValues = values.every(function (value) {
+                  return !Number.isNaN((0, _utils.emToPixels)(value, fontSize));
+                });
+
+                if (!allResolvableValues) {
+                  return null;
+                }
+
+                return fixer.replaceText(node.value, "`".concat(values.map(function (value) {
+                  var pixelValue = (0, _utils.emToPixels)(value, fontSize);
+                  var pixelValueString = "".concat(pixelValue, "px");
+                  return "${".concat(pixelValueToSpacingTokenNode(pixelValueString), "}");
+                }).join(' '), "`"));
+              } : undefined
+            });
+          });
+        });
+      },
+      // CSSTemplateLiteral and StyledTemplateLiteral
+      // const cssTemplateLiteral = css`color: red; padding: 12px`;
+      // const styledTemplateLiteral = styled.p`color: red; padding: 8px`;
+      'TaggedTemplateExpression[tag.name="css"],TaggedTemplateExpression[tag.object.name="styled"]': function TaggedTemplateExpressionTagNameCssTaggedTemplateExpressionTagObjectNameStyled(node) {
+        if (node.type !== 'TaggedTemplateExpression') {
+          return;
+        }
+
+        var combinedString = node.quasi.quasis.map(function (q, i) {
+          return "".concat(q.value.raw).concat(node.quasi.expressions[i] ? (0, _utils.getValue)(node.quasi.expressions[i], context) : '');
+        }).join('');
+        /**
+         * Attempts to remove all non-essential words & characters from a style block.
+         * Including selectors and queries
+         * Adapted from ensure-design-token-usage
+         */
+
+        var cssProperties = combinedString.split('\n').filter(function (line) {
+          return !line.trim().startsWith('@');
+        }).join('\n').replace(/\n/g, '').split(/;|{|}/).map(function (el) {
+          return el.trim() || '';
+        });
+        cssProperties.forEach(function (style) {
+          var _style$split = style.split(':'),
+              _style$split2 = (0, _slicedToArray2.default)(_style$split, 2),
+              rawProperty = _style$split2[0],
+              value = _style$split2[1];
+
+          var property = (0, _utils.convertHyphenatedNameToCamelCase)(rawProperty);
+
+          if (!(0, _utils.isSpacingProperty)(property)) {
+            return;
+          }
+
+          if (!(0, _utils.isValidSpacingValue)(value)) {
+            return context.report({
+              node: node,
+              messageId: 'noRawSpacingValues',
+              data: {
+                payload: "NaN:".concat(value)
+              }
+            });
+          }
+
+          var values = (0, _utils.getValueFromShorthand)(value);
+
+          var _iterator = _createForOfIteratorHelper(values),
+              _step;
+
+          try {
+            for (_iterator.s(); !(_step = _iterator.n()).done;) {
+              var val = _step.value;
+              // could be array of values e.g. padding: 8px 12px 3px
+              context.report({
+                node: node,
+                messageId: 'noRawSpacingValues',
+                data: {
+                  payload: "".concat(property, ":").concat(val)
+                }
+              });
+            }
+          } catch (err) {
+            _iterator.e(err);
+          } finally {
+            _iterator.f();
+          }
+        });
+      }
+    };
+  }
+};
+var _default = rule;
+exports.default = _default;