@atlaskit/eslint-plugin-design-system 8.27.0 → 8.29.0

package/constellation/local-cx-xcss/usage.mdx

@@ -0,0 +1,37 @@
+# local-cx-xcss
+
+This rule ensures the `cx()` function is only used within the `xcss` prop. This aids tracking what styles are applied to a jsx element.
+
+The `cx` function is checked only if it is imported from `@compiled/react` or `@atlaskit/css`.
+
+Passing arguments to the `cx()` function is how you compose styles (combine more than one set of styles together) with XCSS. This is a workaround for the more conventional array syntax (e.g. [in Emotion](https://emotion.sh/docs/composition)) `<div xcss={[style1, style2]} />` not giving robust enough type checking.
+
+## Examples
+
+### Incorrect
+
+```js
+import { cx, cssMap } from '@compiled/react';
+
+const styles = cssMap({
+  text: { color: 'red' },
+  bg: { background: 'blue' },
+});
+
+const joinedStyles = cx(styles.text, styles.bg);
+
+<Button xcss={joinedStyles} />;
+```
+
+### Correct
+
+```js
+import { cx, cssMap } from '@compiled/react';
+
+const styles = cssMap({
+  text: { color: 'red' },
+  bg: { background: 'blue' },
+});
+
+<Button xcss={cx(styles.text, styles.bg)} />;
+```

package/constellation/no-banned-imports/usage.mdx

@@ -0,0 +1,17 @@
+# no-banned-imports
+
+Using private or experimental packages is dangerous as they are not supported across major versions meaning you will not be able to migrate easily causing friction for yourself and the Atlassian Design System team.
+
+## Examples
+
+Anything that is considered private or experimental will be marked as violations.
+
+### Incorrect
+
+```ts
+import noop from '@atlaskit/ds-lib/noop';
+                  ^^^^^^^^^^^^^^^^^^^^^
+
+import { Text } from '@atlaskit/ds-explorations';
+                      ^^^^^^^^^^^^^^^^^^^^^^^^^
+```

package/constellation/no-css-tagged-template-expression/usage.mdx

@@ -0,0 +1,66 @@
+# no-css-tagged-template-expression
+
+Disallows any `css` tagged template expressions that originate from `@emotion/react`, `@emotion/core`, `compiled/react` or `styled-components`.
+
+Tagged template expressions cannot be type safe and are difficult to parse correctly. Will auto fix ` css`` ` to the preferred `css({})` call expression syntax.
+
+Thank you to the [Compiled team for their rule](https://github.com/atlassian-labs/compiled/tree/master/packages/eslint-plugin/src/rules/no-css-tagged-template-expression) from which this was ported.
+
+## Examples
+
+### Incorrect
+
+```js
+import { css } from '@emotion/react';
+
+css`
+  color: blue;
+`;
+
+const styles = css`
+  color: blue;
+  font-weight: 500;
+`;
+```
+
+### Correct
+
+```js
+import { css } from '@emotion/react';
+
+css({ color: 'blue' });
+
+const styles = css({
+  color: 'blue',
+  fontWeight: 500,
+});
+```
+
+## Options
+
+### importSources
+
+By default, this rule will check `css` usages from:
+
+- `@atlaskit/css`
+- `@atlaskit/primitives`
+- `@compiled/react`
+- `@emotion/react`
+- `@emotion/core`
+- `@emotion/styled`
+- `styled-components`
+
+To change this list of libraries, you can define a custom set of `importSources`, which accepts an array of package names (strings).
+
+```tsx
+// [{ importSources: ['other-lib'] }]
+
+import { css } from 'other-lib';
+
+// Invalid!
+export const styles = css``;
+```
+
+## Limitations
+
+- Comments are not auto-fixable. You will need to manually convert usages containing functions.

package/constellation/no-deprecated-apis/usage.mdx

@@ -0,0 +1,76 @@
+# no-deprecated-apis
+
+Props across the Atlassian Design System can be deprecated when they are deemed no-longer fit for purporse or dangerous and risk effective use at scale.
+
+## Examples
+
+Anything that can be used as props from Atlassian Design System components can be violations when marked as deprecated.
+
+### Incorrect
+
+```tsx
+<ButtonItem cssFn={cssFn()} />
+            ^^^^
+
+<Drawer overrides={overrides} />
+        ^^^^^^^^^
+```
+
+## Options
+
+The rule can take one option: `deprecatedConfig`,
+if not provided the rule will use an internal config.
+If provided the rule will use the passed in config instead.
+
+### deprecatedConfig
+
+The following fields can be defined in the config:
+
+- `deprecatedProp`, which is the deprecated props. Each prop has the following fields:
+  - `moduleSpecifier`, which is the module specifier of the package in which the prop was deprecated. For example: `@atlaskit/button`.
+  - `namedSpecifier` **(optional)**, which is an array of named specifiers of the package in which the prop was deprecated. For example: `Button`.
+  - `actionableVersion` **(optional)**, which is the version of the package in which the prop can be actioned on. For example: `1.0.0`.
+
+```json
+{
+  "cssFn": [
+    {
+      "moduleSpecifier": "@atlaskit/menu"
+    }
+  ]
+}
+```
+
+```js
+import { configs } from '@atlaskit/eslint-plugin-design-system';
+
+module.exports = {
+  rules: {
+    '@atlaskit/design-system/no-deprecated-api': [
+      'error',
+      {
+        deprecatedConfig: {
+          cssFn: [
+            {
+              moduleSpecifier: '@atlaskit/menu',
+            },
+          ],
+        },
+      },
+    ],
+  },
+};
+```
+
+The plugin also provides a `filterActionableDeprecations` util function that accepts the `deprecated APIs config` and your root `package.json` as params and will filter the default deprecated APIs config based on the package versions installed.
+
+```js
+import { configs, filterActionableDeprecations } from '@atlaskit/eslint-plugin-design-system';
+import packageJson from './package.json';
+
+rules: {
+  '@atlaskit/design-system/no-deprecated-api': ['error', {
+    'deprecatedConfig': filterActionableDeprecations(configs.deprecatedConfig, packageJson),
+  }]
+}
+```

package/constellation/no-deprecated-design-token-usage/usage.mdx

@@ -0,0 +1,27 @@
+# no-deprecated-design-token-usage
+
+Using deprecated design tokens is dangerous as they will eventually be deleted after the sunset period.
+This rule helps you move to non-deprecated design tokens.
+
+## Examples
+
+This rule will mark usage of deprecated design tokens as violations.
+
+## Incorrect
+
+```js
+import { token } from '@atlaskit/tokens';
+
+css({ color: token('i.am.deprecated') });
+                    ^^^^^^^^^^^^^^^
+css({ color: token('i.am.a.token') });
+                    ^^^^^^^^^^^^^
+```
+
+## Options
+
+It's recommended to set this rule to "warn" 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 design token it will be moved into `deleted` state at which point the counterpart of this rule `no-unsafe-design-token-usage` will mark violations as errors.
+
+Running `eslint --fix` will automatically apply replacement tokens if present.

package/constellation/no-deprecated-imports/usage.mdx

@@ -0,0 +1,62 @@
+# no-deprecated-imports
+
+Packages across the Atlassian Design System can be deprecated when they are deemed no-longer fit for purporse or dangerous and risk effective use at scale.
+
+## Examples
+
+This rule will mark usage of deprecated modules as violations.
+
+### Incorrect
+
+```ts
+import Item from '@atlaskit/item';
+                  ^^^^^^^^^^^^^^
+import GlobalNav from '@atlaskit/global-navigation';
+                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+```
+
+## Options
+
+The rule can take one option: `deprecatedConfig`,
+if not provided the rule will use an internal config.
+If provided the rule will use the passed in config instead.
+
+### deprecatedConfig
+
+The following fields can be defined in the config:
+
+- `packagePath`, which is the name of the package. For example: `@atlaskit/navigation-next` and `@atlaskit/navigation`.
+  With the package path as the key, you can either provide the values as:
+  - `message` **(optional)**, the message to display when the deprecated packages path is used. For example: `multi-select is deprecated. Please use '@atlaskit/select' instead.`
+    Or as:
+  - `imports`, which is an array of named imports to be deprecated. Each named import has the following fields:
+    - `importName`, which is the name of the import to be deprecated. For example: `assistive` and `visuallyHidden`.
+    - `message` **(optional)**, which is the message to display when the deprecated import is used. For example: `The assistive mixin is deprecated. Please use `@atlaskit/visually-hidden` instead.`.
+
+```json
+{
+  "@atlaskit/navigation-next": {
+    "message": "navigation-next is deprecated. Please use '@atlaskit/atlassian-navigation' instead."
+  }
+}
+```
+
+```js
+import packageJson from './package.json';
+
+module.exports = {
+  rules: {
+    '@atlaskit/design-system/no-deprecated-imports': [
+      'error',
+      {
+        deprecatedConfig: {
+          '@atlaskit/navigation-next': {
+            message:
+              "navigation-next is deprecated. Please use '@atlaskit/atlassian-navigation' instead.",
+          },
+        },
+      },
+    ],
+  },
+};
+```

package/constellation/no-empty-styled-expression/usage.mdx

@@ -0,0 +1,77 @@
+# no-empty-styled-expression
+
+Disallows/discourages passing empty arguments to any `styled` expression when using `@compiled/react`, as well as any other CSS-in-JS library defined through the `importSources` option.
+
+If Compiled is used in the file, passing an empty object or no object at all causes Compiled to build extra `div/span` elements, as opposed to simply using a `div`. This leads to reduced performance and is greatly discouraged. If a wrapper is necessary, opt to use a `div` or wrap it in the empty React fragment `<> <YourComponentHere></YourComponentHere> </>`.
+
+## Examples
+
+### Incorrect
+
+```tsx
+const EmptyStyledExpression = styled.div();
+
+const EmptyStyledExpressionArgument = styled.div({});
+
+const EmptyStyledExpressionArgument = styled.div([]);
+```
+
+### Correct
+
+```tsx
+const Wrapper = styled.div({
+  backgroundColor: 'red',
+  MyComponent: {
+    backgroundColor: 'green',
+  },
+});
+```
+
+## What to do instead?
+
+### Use elements directly
+
+```diff
+- const Wrapper = styled.div({});
+
+   function App() {
+-    return <Wrapper>hello world</Wrapper>;
++    return <div>hello world</div>;
+  }
+```
+
+### Use a React fragment
+
+```diff
+- const Wrapper = styled.div({});
+
+   function App() {
+-    return <Wrapper>hello world</Wrapper>;
++    return <>hello world</>;
+  }
+```
+
+## Options
+
+### importSources
+
+By default, this rule will check `styled` usages from:
+
+- `@atlaskit/css`
+- `@atlaskit/primitives`
+- `@compiled/react`
+- `@emotion/react`
+- `@emotion/core`
+- `@emotion/styled`
+- `styled-components`
+
+To change this list of libraries, you can define a custom set of `importSources`, which accepts an array of package names (strings).
+
+```tsx
+// [{ importSources: ['other-lib'] }]
+
+import { styled } from 'other-lib';
+
+// Invalid!
+export const Component = styled.div({});
+```

package/constellation/no-exported-css/usage.mdx

@@ -0,0 +1,50 @@
+# no-exported-css
+
+Disallows `css` export declarations that originate from `@compiled/react` and `@atlaskit/css`, as well as any other CSS-in-JS library defined through the `importSources` option.
+
+In Compiled, exporting css declarations may result in unexpected errors when imported, because its value will be `null` at runtime. Additionally, co-locating css definitions with their usage is considered best practice in order to improve code readability and build performance.
+
+## Examples
+
+### Incorrect
+
+```tsx
+import { css } from '@compiled/react';
+
+export const styles = css({});
+
+export default css({});
+```
+
+### Correct
+
+```tsx
+import { css } from '@compiled/react';
+
+const styles = css({});
+```
+
+## Options
+
+### importSources
+
+By default, this rule will check `css` usages from:
+
+- `@atlaskit/css`
+- `@atlaskit/primitives`
+- `@compiled/react`
+- `@emotion/react`
+- `@emotion/core`
+- `@emotion/styled`
+- `styled-components`
+
+To change this list of libraries, you can define a custom set of `importSources`, which accepts an array of package names (strings).
+
+```tsx
+// [{ importSources: ['other-lib'] }]
+
+import { css } from 'other-lib';
+
+// Invalid!
+export const styles = css({});
+```

package/constellation/no-exported-keyframes/usage.mdx

@@ -0,0 +1,50 @@
+# no-exported-keyframes
+
+Disallows `keyframes` export declarations that originate from `@compiled/react`, as well as any other CSS-in-JS library defined through the `importSources` option.
+
+In Compiled, exporting keyframes declarations may result in unexpected errors when imported, because its value will be `null` at runtime. Additionally, co-locating keyframes definitions with their usage is considered best practice in order to improve code readability and build performance.
+
+## Examples
+
+### Incorrect
+
+```tsx
+import { keyframes } from '@compiled/react';
+
+export const animation = keyframes({});
+
+export default keyframes({});
+```
+
+### Correct
+
+```tsx
+import { keyframes } from '@compiled/react';
+
+const animation = keyframes({});
+```
+
+## Options
+
+### importSources
+
+By default, this rule will check `keyframes` usages from:
+
+- `@atlaskit/css`
+- `@atlaskit/primitives`
+- `@compiled/react`
+- `@emotion/react`
+- `@emotion/core`
+- `@emotion/styled`
+- `styled-components`
+
+To change this list of libraries, you can define a custom set of `importSources`, which accepts an array of package names (strings).
+
+```tsx
+// [{ importSources: ['other-lib'] }]
+
+import { keyframes } from 'other-lib';
+
+// Invalid!
+export const animation = keyframes({});
+```

package/constellation/no-invalid-css-map/usage.mdx

@@ -0,0 +1,199 @@
+# no-invalid-css-map
+
+Ensure that all usages of the `cssMap` API are valid, and enforces the format of the object that is passed to `cssMap`.
+
+Please refer to the [Compiled documentation](https://compiledcssinjs.com/docs/api-cssmap) for more details and some examples.
+
+Note that this version of the `no-invalid-css-map` rule differs from `@compiled/eslint-plugin/no-invalid-css-map` in that this will apply to both `@compiled/react` and `@atlaskit/css`.
+
+This is intended to be used in conjunction with type checking (through TypeScript).
+
+## Examples
+
+### Incorrect
+
+```tsx
+import React from 'react';
+import { cssMap } from '@compiled/react';
+
+// cssMap needs to be declared in the top-most scope.
+// (not within a function, class, etc.)
+
+const Foo = () => {
+  const bar = cssMap({
+    danger: {
+      color: 'red',
+    },
+  });
+};
+```
+
+```tsx
+import React from 'react';
+import { cssMap } from '@compiled/react';
+import { importedVariable, importedFunction } from 'another-package';
+
+// Cannot use imported functions as values in cssMap.
+
+const myVariable = importedFunction();
+
+const styles = cssMap({
+  danger: {
+    // Both invalid because they rely on an imported function.
+    color: myVariable,
+    padding: importedFunction(),
+  },
+});
+```
+
+```tsx
+import React from 'react';
+import { cssMap } from '@compiled/react';
+
+// Cannot export usages of cssMap.
+// Any usages of cssMap must be in the same file.
+
+export const foo = cssMap({
+  danger: {
+    color: 'red',
+  },
+});
+```
+
+```tsx
+import React from 'react';
+import { cssMap } from '@compiled/react';
+import { token } from '@atlaskit/tokens';
+
+// Functions and object methods are not allowed as
+// values in cssMap.
+
+const styles = cssMap({
+  // Object method
+  get danger() {
+    return { color: '#123456' };
+  },
+});
+
+const styles2 = cssMap({
+  // Arrow function
+  danger: () => {
+    color: '#123456';
+  },
+});
+
+function customFunction(...args) {
+  return arguments.join('');
+}
+
+const styles3 = cssMap({
+  danger: {
+    // Locally defined function
+    color: customFunction('red', 'blue'),
+    backgroundColor: 'red',
+  },
+});
+```
+
+```tsx
+import React from 'react';
+import { cssMap } from '@compiled/react';
+
+// Spread elements ("...") cannot be used in cssMap.
+
+const base = {
+  success: {
+    color: 'green',
+  },
+};
+
+const bar = cssMap({
+  ...base,
+  danger: {
+    color: 'red',
+  },
+});
+```
+
+### Correct
+
+```tsx
+import React from 'react';
+import { cssMap } from '@compiled/react';
+
+// Literals (strings, numbers, etc.) are used as values
+// in cssMap.
+
+const styles = cssMap({
+  danger: {
+    color: 'red',
+    backgroundColor: 'red',
+  },
+  success: {
+    color: 'green',
+    backgroundColor: 'green',
+  },
+});
+```
+
+```tsx
+import React from 'react';
+import { cssMap } from '@compiled/react';
+
+// A statically evaluable variable (known at build time)
+// is used here.
+
+const bap = 'blue';
+
+const styles = cssMap({
+  danger: {
+    color: bap,
+  },
+});
+```
+
+### Options
+
+#### `allowedFunctionCalls`: [string, string][]
+
+Normally, this ESLint rule forbids all function calls from being used inside the `cssMap(...)` function call. For example, this would be invalid using default settings:
+
+```tsx
+import React from 'react';
+import { cssMap } from '@compiled/react';
+import { token } from '@atlaskit/tokens';
+
+const styles = cssMap({
+  danger: {
+    color: token('my-color'),
+    backgroundColor: 'red',
+  },
+  success: {
+    color: 'green',
+  },
+});
+```
+
+If you would like to whitelist certain functions (e.g. `token` from `@atlaskit/tokens`), you can include the names of the functions as part of the `allowedFunctionCalls` argument. Each function should be represented as a two-element array, with the first element being the package the function is from, and the second element being the name of the function.
+
+For example, with the below configuration, the above code example would be okay.
+
+```tsx
+// .eslintrc.js
+
+// ...
+      rules: {
+        '@atlaskit/eslint-plugin-design-system/no-invalid-css-map': [
+          'error',
+          {
+            allowedFunctionCalls: [
+              ['@atlaskit/tokens', 'token'],
+            ]
+          },
+        ],
+        // ...
+      },
+// ...
+```
+
+Please note that this ESLint rule only supports whitelisting imports in the form `import { myFunctionOrVariable } from 'my-package'`; we do not currently support whitelisting default imports, so `import myFunctionOrVariable from 'my-package'` would always be invalid when used in `cssMap`.