@atlaskit/eslint-plugin-design-system 4.16.5 → 4.17.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @atlaskit/eslint-plugin-design-system
 
+## 4.17.0
+
+### Minor Changes
+
+- [`c80505045f0`](https://bitbucket.org/atlassian/atlassian-frontend/commits/c80505045f0) - Added new rule to encourage use of @atlaskit/primitives components where relavant. Currently disabled by default, so there should be no expected change to consumers.
+
 ## 4.16.5
 
 ### Patch Changes

package/constellation/index/configuration-and-setup.mdx

@@ -0,0 +1,46 @@
+---
+order: 2
+---
+
+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/ensure-design-token-usage-spacing': 'error',
++    '@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/constellation/index/usage.mdx

@@ -1,45 +1,390 @@
 ---
-order: 2
+order: 0
 ---
 
-This plugin contains rules that should be used with the Atlassian Design System.
-Where possible, these rules come with auto fixers.
+import SectionMessage from '@atlaskit/section-message';
 
-You can read more about configuring ESLint in their [documentation](https://eslint.org/docs/user-guide/configuring).
+<SectionMessage
+  title="A new color system, design tokens, and themes are coming soon"
+  appearance="warning"
+>
+  <p>
+    This ESLint plugin includes rules to help you use <a href="/foundations/design-tokens">design tokens</a>, which will soon be the new way to apply color and spacing values.
+    <br/><br/>Do not use the design token-related rules until design tokens are available for you to adopt.
+  </p>
+</SectionMessage>
 
-## Configuration
+Design tokens are supported by linting rules, which warn you if a token is deprecated, missing, or has no fallback style. Design token lint rules are provided by the Design System ESLint and <a href="/components/stylelint-design-system/usage">Stylelint plugins</a>.
 
-Add the plugin to your `.eslintrc.js` file.
+If you are an Atlassian employee, you must configure the lint rule in your repository and keep it up-to-date. If you are a partner developer, we strongly recommend you to use it as well.
 
-```diff
-module.exports = {
-  plugins: [
-+    '@atlaskit/design-system',
-  ],
-};
+Follow the <a href="/get-started/develop/using-tokens-in-code#eslint-plugin">Get started</a> guide to get started with Design Tokens, and set up the ESLint plugin.
+
+## ensure-design-token-usage
+
+Ensures that the codebase uses the global `token` function for colors, rather than hard-coded values. This ruleset is great for codebases that are starting to adopt color tokens and those that have already adopted color tokens. This ruleset also prevents new contributors from accidentally adding hard-coded color values.
+
+<h3 id="ensure-design-token-usage-do">Do</h3>
+
+Use the global `token` function, and design tokens.
+
+```jsx
+import { token } from '@atlaskit/tokens';
+
+css({
+  boxShadow: token('elevation.shadow.card'),
+});
+```
+
+```jsx
+import { token } from '@atlaskit/tokens';
+
+css`
+  color: ${token('color.text.highemphasis')};
+`;
+```
+
+<h3 id="ensure-design-token-usage-dont">Don't</h3>
+
+Don't use hard-coded values, such as hexadecimal, CSS colors, or base color values.
+
+```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,
+         ^^^^
+});
+```
+
+## ensure-design-token-usage-spacing
+
+Ensures that the codebase uses the global `token` function for spacing, rather than hard-coded values. This ruleset is great for codebases that are starting to adopt space tokens and those that have already adopted space tokens. This ruleset also prevents new contributors from accidentally adding hard-coded space values.
+
+<h3 id="ensure-design-token-usage-spacing-do">Do</h3>
+
+Use the global `token` function, and design tokens.
+
+```jsx
+import { token } from '@atlaskit/tokens';
+
+css({
+  padding: token('space.200'),
+});
+```
+
+```jsx
+import { token } from '@atlaskit/tokens';
+
+css`
+  gap: ${token('space.100')};
+`;
+```
+
+<h3 id="ensure-design-token-usage-spacing-dont">Don't</h3>
+
+Don't use hard-coded values, such as pixel values, relative units, or legacy `gridSize` functions.
+
+```jsx
+css({
+  padding: '8px',
+            ^^^
+});
+```
+
+```jsx
+css({
+  paddingLeft: gridSize(),
+               ^^^^^^^^^^
+})
+```
+
+## 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 a `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` to automatically apply replacement tokens.
+
+<h3 id="no-deprecated-design-token-usage-dont">Don't</h3>
+
+Don't use deprecated tokens.
+
+
+```jsx
+import { token } from '@atlaskit/tokens';
+
+css({
+  color: token('i.am.deprecated'), // will warn on deprecated tokens
+});
+```
+
+
+## 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.
+
+<h3 id="no-unsafe-design-token-usage-do">Do</h3>
+
+Use the `token` function and token naming functions correctly.
+
+```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)};
+`;
+```
+
+<h3 id="no-unsafe-design-token-usage-dont">Don't</h3>
+
+Don’t use outdated token names, or use tokens without the `token` function.
+
+
+```jsx
+const textColor = 'red';
+
+css({
+  color: textColor,
+         ^^^^^^^^^
+});
 ```
 
-Extend the configuration file.
+```jsx
+css({
+  boxShadow: '0px 1px 1px var(--ds-accent-subtleBlue)',
+                          ^^^^^^^^^^^^^^^^^^^^^^^^^^
+})
+```
+
+## icon-label
+
+Enforces accessible usage of icon labels when composed with other Design System components.
+
+<h3 id="icon-label-do">Do</h3>
+
+Use the icon label prop to ensure accessibility of Design System icons.
+
+
+```jsx
+import ActivityIcon from '@atlaskit/icon/glyph/activity'
 
-```diff
-module.exports = {
-  extends: [
-+    'plugin:@atlaskit/design-system/recommended',
-  ],
-};
+<ActivityIcon label="Activity">
 ```
 
-Enable any desired rules. The rules shown below are strongly recommended.
+```jsx
+import ActivityIcon from '@atlaskit/icon/glyph/activity'
 
-```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'
-    }
-};
+<Button iconLeft={<ActivityIcon label="Activity">} />
 ```
+
+```jsx
+import ActivityIcon from '@atlaskit/icon/glyph/activity'
+
+<ButtonItem iconBefore={<ActivityIcon label="">}>
+  My activity
+</ButtonItem>
+```
+
+<h3 id="icon-label-dont">Don't</h3>
+
+Don't ignore labels for icons.
+
+
+```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>
+```
+
+## no-banned-imports
+
+Prevents usage of private or experimental Atlassian Design System packages.
+
+<h3 id="no-banned-imports-dont">Don't</h3>
+
+Don't import or use private or experimental ADS packages.
+
+```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 APIs.
+
+<h3 id="no-deprecated-api-usage-do">Do</h3>
+
+```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 />;
+```
+
+<h3 id="no-deprecated-api-usage-dont">Don't</h3>
+
+```jsx
+import { ButtonItem } from '@atlaskit/menu';
+
+const Element = () => (
+  <ButtonItem cssFn={cssFn()} />
+              ^^^^
+);
+```
+
+```jsx
+import Drawer from '@atlaskit/drawer';
+
+const Element = () => (
+  <Drawer overrides={overrides} />
+          ^^^^^^^^^
+);
+```
+
+
+## no-deprecated-imports
+
+Ensures usage of current Atlassian Design System dependencies.
+
+<h3 id="no-deprecated-imports-do">Do</h3>
+
+```ts
+import Modal from '@atlaskit/modal-dialog';
+```
+
+```ts
+import { ButtonItem } from '@atlaskit/menu';
+```
+
+<h3 id="no-deprecated-imports-dont">Don't</h3>
+
+```ts
+import Item from '@atlaskit/item';
+                  ^^^^^^^^^^^^^^
+```
+
+```ts
+import GlobalNav from '@atlaskit/global-navigation';
+                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+```
+
+## use-visually-hidden
+
+This rule makes Design System consumers aware of existing solutions.
+
+<h3 id="use-visually-hidden-do">Do</h3>
+
+```jsx
+import VisuallyHidden from '@atlaskit/visually-hidden';
+```
+
+<h3 id="use-visually-hidden-dont">Don't</h3>
+
+```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()}`;
+                                     ^^^^^^^^^^^^^^
+```
+

package/dist/cjs/index.js

@@ -20,6 +20,7 @@ var _noDeprecatedApis = _interopRequireDefault(require("./rules/no-deprecated-ap
 var _noDeprecatedDesignTokenUsage = _interopRequireDefault(require("./rules/no-deprecated-design-token-usage"));
 var _noDeprecatedImports = _interopRequireDefault(require("./rules/no-deprecated-imports"));
 var _noUnsafeDesignTokenUsage = _interopRequireDefault(require("./rules/no-unsafe-design-token-usage"));
+var _usePrimitives = _interopRequireDefault(require("./rules/use-primitives"));
 var _useVisuallyHidden = _interopRequireDefault(require("./rules/use-visually-hidden"));
 var _filterActionableDeprecations = require("./rules/no-deprecated-apis/helpers/filter-actionable-deprecations");
 var rules = {
@@ -31,7 +32,8 @@ var rules = {
   'no-banned-imports': _noBannedImports.default,
   'no-unsafe-design-token-usage': _noUnsafeDesignTokenUsage.default,
   'use-visually-hidden': _useVisuallyHidden.default,
-  'ensure-design-token-usage-spacing': _ensureDesignTokenUsageSpacing.default
+  'ensure-design-token-usage-spacing': _ensureDesignTokenUsageSpacing.default,
+  'use-primitives': _usePrimitives.default
 };
 exports.rules = rules;
 var configs = {

package/dist/cjs/rules/use-primitives/index.js

@@ -0,0 +1,109 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _eslintCodemodUtils = require("eslint-codemod-utils");
+var _utils = require("./utils");
+var boxDocsUrl = 'https://atlassian.design/components/primitves/box/examples';
+var inlineDocsUrl = 'https://atlassian.design/components/primitves/inline/examples';
+var stackDocsUrl = 'https://atlassian.design/components/primitves/stack/examples';
+var rule = {
+  meta: {
+    type: 'suggestion',
+    fixable: 'code',
+    docs: {
+      description: 'UI components should use primitives where possible.',
+      recommended: true
+    },
+    messages: {
+      preferPrimitivesBox: "This \"{{element}}\" may be able to be replaced with a \"Box\". See ".concat(boxDocsUrl, " for guidance."),
+      preferPrimitivesInline: "This \"{{element}}\" may be able to be replaced with an \"Inline\". See ".concat(inlineDocsUrl, " for guidance."),
+      preferPrimitivesStack: "This \"{{element}}\" may be able to be replaced with a \"Stack\". See ".concat(stackDocsUrl, " for guidance.")
+    },
+    schema: [{
+      type: 'object',
+      properties: {
+        exclude: {
+          type: ['string', 'array'],
+          items: {
+            type: 'string'
+          }
+        }
+      },
+      additionalProperties: false
+    }]
+  },
+  create: function create(context) {
+    return {
+      /**
+       * Traverse file
+       * Look for any JSX opening element and check what it is
+       * a) it's already a component
+       * b) it's native HTML
+       *
+       * if b) suggest alternative use of primitives
+       */
+      JSXOpeningElement: function JSXOpeningElement(node) {
+        if (!(0, _eslintCodemodUtils.isNodeOfType)(node, 'JSXOpeningElement')) {
+          return;
+        }
+        if (!(0, _eslintCodemodUtils.isNodeOfType)(node.name, 'JSXIdentifier')) {
+          return;
+        }
+        var suggestBox = (0, _utils.shouldSuggestBox)(node === null || node === void 0 ? void 0 : node.parent // context.getScope(),
+        );
+        var suggestInline = (0, _utils.shouldSuggestInline)(node === null || node === void 0 ? void 0 : node.parent, context);
+        var suggestStack = (0, _utils.shouldSuggestStack)(node === null || node === void 0 ? void 0 : node.parent, context);
+
+        // const suggestText = shouldSuggestText(
+        //   node?.parent as any,
+        //   // context.getScope(),
+        // );
+
+        if (suggestBox) {
+          context.report({
+            node: node,
+            messageId: 'preferPrimitivesBox',
+            data: {
+              element: node.name.name
+            },
+            suggest: [{
+              desc: "Convert to Box",
+              fix: (0, _utils.primitiveFixer)(node, 'Box', context)
+            }]
+          });
+        }
+        if (suggestInline) {
+          context.report({
+            node: node,
+            messageId: 'preferPrimitivesInline',
+            data: {
+              element: node.name.name
+            },
+            suggest: [{
+              desc: "Convert to Inline",
+              fix: (0, _utils.primitiveFixer)(node, 'Inline', context)
+            }]
+          });
+        }
+        if (suggestStack) {
+          context.report({
+            node: node,
+            messageId: 'preferPrimitivesStack',
+            data: {
+              element: node.name.name
+            },
+            suggest: [{
+              desc: "Convert to Stack",
+              fix: (0, _utils.primitiveFixer)(node, 'Stack', context)
+            }]
+          });
+        }
+      }
+    };
+  }
+};
+var _default = rule;
+exports.default = _default;

package/dist/cjs/rules/use-primitives/types.js

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