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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @atlaskit/eslint-plugin-design-system
 
+## 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-api-usage': 'error'
+    }
+};
+```

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

@@ -34,6 +34,7 @@ var rule = {
       staticToken: "Token string should be inlined directly into the function call.\n\n```\ntoken('color.background.blanket');\n```\n",
       invalidToken: 'The token "{{name}}" does not exist.',
       tokenRemoved: 'The token "{{name}}" is removed in favour of "{{replacement}}".',
+      tokenIsExperimental: 'The token "{{name}}" is experimental and should not be used directly at this time. It should be replaced by "{{replacement}}".',
       tokenFallbackEnforced: "Token function requires a fallback, preferably something that best matches the light/default theme in case tokens aren't present.\n\n```\ntoken('color.background.blanket', N500A);\n```\n      ",
       tokenFallbackRestricted: "Token function must not use a fallback.\n\n```\ntoken('color.background.blanket');\n```\n      "
     }
@@ -134,14 +135,14 @@ var rule = {
           return;
         }
 
-        var migrationMeta = _renameMapping.default.filter(function (t) {
+        var deletedMigrationMeta = _renameMapping.default.filter(function (t) {
           return t.state === 'deleted';
         }).find(function (t) {
           return (0, _tokenIds.getTokenId)(t.path) === tokenKey;
         });
 
-        if (typeof tokenKey === 'string' && migrationMeta) {
-          var cleanTokenKey = (0, _tokenIds.getTokenId)(migrationMeta.replacement);
+        if (typeof tokenKey === 'string' && deletedMigrationMeta) {
+          var cleanTokenKey = (0, _tokenIds.getTokenId)(deletedMigrationMeta.replacement);
           context.report({
             messageId: 'tokenRemoved',
             node: node,
@@ -156,6 +157,31 @@ var rule = {
           return;
         }
 
+        var experimentalMigrationMeta = _renameMapping.default.filter(function (t) {
+          return t.state === 'experimental';
+        }).find(function (t) {
+          return (0, _tokenIds.getTokenId)(t.path) === tokenKey;
+        });
+
+        var tokenNames = Object.keys(_tokenNames.default);
+
+        if (typeof tokenKey === 'string' && experimentalMigrationMeta) {
+          var replacementValue = experimentalMigrationMeta.replacement;
+          var isReplacementAToken = tokenNames.includes(replacementValue);
+          context.report({
+            messageId: 'tokenIsExperimental',
+            node: node,
+            data: {
+              name: tokenKey,
+              replacement: replacementValue
+            },
+            fix: function fix(fixer) {
+              return isReplacementAToken ? fixer.replaceText(node.arguments[0], "'".concat(replacementValue, "'")) : fixer.replaceText(node, "'".concat(replacementValue, "'"));
+            }
+          });
+          return;
+        }
+
         if (typeof tokenKey !== 'string' || typeof tokenKey === 'string' && !_tokenNames.default[tokenKey]) {
           context.report({
             messageId: 'invalidToken',

package/dist/cjs/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/eslint-plugin-design-system",
-	"version": "4.11.2",
+	"version": "4.12.0",
 	"sideEffects": false
 }

package/dist/es2019/rules/no-unsafe-design-token-usage/index.js

@@ -31,6 +31,7 @@ token('color.background.blanket');
 `,
       invalidToken: 'The token "{{name}}" does not exist.',
       tokenRemoved: 'The token "{{name}}" is removed in favour of "{{replacement}}".',
+      tokenIsExperimental: 'The token "{{name}}" is experimental and should not be used directly at this time. It should be replaced by "{{replacement}}".',
       tokenFallbackEnforced: `Token function requires a fallback, preferably something that best matches the light/default theme in case tokens aren't present.
 
 \`\`\`
@@ -138,10 +139,10 @@ token('color.background.blanket');
           return;
         }
 
-        const migrationMeta = renameMapping.filter(t => t.state === 'deleted').find(t => getTokenId(t.path) === tokenKey);
+        const deletedMigrationMeta = renameMapping.filter(t => t.state === 'deleted').find(t => getTokenId(t.path) === tokenKey);
 
-        if (typeof tokenKey === 'string' && migrationMeta) {
-          const cleanTokenKey = getTokenId(migrationMeta.replacement);
+        if (typeof tokenKey === 'string' && deletedMigrationMeta) {
+          const cleanTokenKey = getTokenId(deletedMigrationMeta.replacement);
           context.report({
             messageId: 'tokenRemoved',
             node,
@@ -154,6 +155,24 @@ token('color.background.blanket');
           return;
         }
 
+        const experimentalMigrationMeta = renameMapping.filter(t => t.state === 'experimental').find(t => getTokenId(t.path) === tokenKey);
+        const tokenNames = Object.keys(tokens);
+
+        if (typeof tokenKey === 'string' && experimentalMigrationMeta) {
+          const replacementValue = experimentalMigrationMeta.replacement;
+          const isReplacementAToken = tokenNames.includes(replacementValue);
+          context.report({
+            messageId: 'tokenIsExperimental',
+            node,
+            data: {
+              name: tokenKey,
+              replacement: replacementValue
+            },
+            fix: fixer => isReplacementAToken ? fixer.replaceText(node.arguments[0], `'${replacementValue}'`) : fixer.replaceText(node, `'${replacementValue}'`)
+          });
+          return;
+        }
+
         if (typeof tokenKey !== 'string' || typeof tokenKey === 'string' && !tokens[tokenKey]) {
           context.report({
             messageId: 'invalidToken',

package/dist/es2019/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/eslint-plugin-design-system",
-	"version": "4.11.2",
+	"version": "4.12.0",
 	"sideEffects": false
 }

package/dist/esm/rules/no-unsafe-design-token-usage/index.js

@@ -19,6 +19,7 @@ var rule = {
       staticToken: "Token string should be inlined directly into the function call.\n\n```\ntoken('color.background.blanket');\n```\n",
       invalidToken: 'The token "{{name}}" does not exist.',
       tokenRemoved: 'The token "{{name}}" is removed in favour of "{{replacement}}".',
+      tokenIsExperimental: 'The token "{{name}}" is experimental and should not be used directly at this time. It should be replaced by "{{replacement}}".',
       tokenFallbackEnforced: "Token function requires a fallback, preferably something that best matches the light/default theme in case tokens aren't present.\n\n```\ntoken('color.background.blanket', N500A);\n```\n      ",
       tokenFallbackRestricted: "Token function must not use a fallback.\n\n```\ntoken('color.background.blanket');\n```\n      "
     }
@@ -119,14 +120,14 @@ var rule = {
           return;
         }
 
-        var migrationMeta = renameMapping.filter(function (t) {
+        var deletedMigrationMeta = renameMapping.filter(function (t) {
           return t.state === 'deleted';
         }).find(function (t) {
           return getTokenId(t.path) === tokenKey;
         });
 
-        if (typeof tokenKey === 'string' && migrationMeta) {
-          var cleanTokenKey = getTokenId(migrationMeta.replacement);
+        if (typeof tokenKey === 'string' && deletedMigrationMeta) {
+          var cleanTokenKey = getTokenId(deletedMigrationMeta.replacement);
           context.report({
             messageId: 'tokenRemoved',
             node: node,
@@ -141,6 +142,30 @@ var rule = {
           return;
         }
 
+        var experimentalMigrationMeta = renameMapping.filter(function (t) {
+          return t.state === 'experimental';
+        }).find(function (t) {
+          return getTokenId(t.path) === tokenKey;
+        });
+        var tokenNames = Object.keys(tokens);
+
+        if (typeof tokenKey === 'string' && experimentalMigrationMeta) {
+          var replacementValue = experimentalMigrationMeta.replacement;
+          var isReplacementAToken = tokenNames.includes(replacementValue);
+          context.report({
+            messageId: 'tokenIsExperimental',
+            node: node,
+            data: {
+              name: tokenKey,
+              replacement: replacementValue
+            },
+            fix: function fix(fixer) {
+              return isReplacementAToken ? fixer.replaceText(node.arguments[0], "'".concat(replacementValue, "'")) : fixer.replaceText(node, "'".concat(replacementValue, "'"));
+            }
+          });
+          return;
+        }
+
         if (typeof tokenKey !== 'string' || typeof tokenKey === 'string' && !tokens[tokenKey]) {
           context.report({
             messageId: 'invalidToken',

package/dist/esm/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/eslint-plugin-design-system",
-	"version": "4.11.2",
+	"version": "4.12.0",
 	"sideEffects": false
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@atlaskit/eslint-plugin-design-system",
   "description": "The essential plugin for use with the Atlassian Design System.",
-  "version": "4.11.2",
+  "version": "4.12.0",
   "author": "Atlassian Pty Ltd",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
@@ -11,8 +11,7 @@
     "releaseModel": "scheduled",
     "website": {
       "name": "ESLint plugin",
-      "category": "Tooling",
-      "draft": true
+      "category": "Tooling"
     }
   },
   "repository": "https://bitbucket.org/atlassian/atlassian-frontend-mirror",