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

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @atlaskit/eslint-plugin-design-system
 
+## 8.27.0
+
+### Minor Changes
+
+- [#72966](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/72966) [`ec187f466e23`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/ec187f466e23) - Update `consistent-css-prop-usage` to incorporate some updates previously made to the `@compiled/eslint-plugin` equivalent.
+
+  1. Add autofixer to add the `css` function for the following scenario:
+
+  ```
+  const styles = { ... };
+  <div css={styles} />
+  ```
+
+  Note that this autofixer will not run if local variables are used inside the style object (e.g. `{ height: makeTaller ? '5px' : '2px' }`), or if there are spread elements, template literals, and other tricky-to-parse code. These continue to require fixing manually.
+
+  (This rule would previously only autofix if the file was originally `<div css={{ ... }} />`)
+
+  2. Add `import { css } from '@compiled/react'` (or `xcss`) automatically when fixing. The package from which to import the `css` function can be specified through the `importSource` option.
+
+  3. Add `excludeReactComponents` to exclude linting React components (i.e. components that start with uppercase). Sometimes it may not be desirable to have this rule apply to React components (e.g. `@atlaskit/button`), which could either use the Emotion or Compiled APIs when they expose a `css` prop. Passing a function from the wrong library can result in the styling erroneously not being applied.
+
+  4. Treat `{ ... } as const` statements the same way as `{ ... }` objects.
+
+  5. Add `fixNamesOnly` to disable all autofixers _except_ the autofixer that adds `styles` to the end of existing style variables. For example, in `<div css={buttonComponent} />; const buttonComponent = css({ ... })`, `buttonComponent` will continue to be renamed to `buttonComponentStyles`. Autofixers that will be _disabled_ include hoisting the styles to the top-most scope, and adding the `css` function call around style objects.
+
+## 8.26.0
+
+### Minor Changes
+
+- [#71429](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/71429) [`457122c5d002`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/457122c5d002) - Add some ESLint rules from Compiled CSS-in-JS, and adapt them for the UI Styling Standard.
+
+  Rules added:
+
+  - `no-empty-styled-expression`: ban `styled({})` usages
+  - `no-exported-css` and `no-exported-keyframes`: ban `css` and `keyframes` function calls that are exported
+  - `no-invalid-css-map`: ban usages of the Compiled/`@atlaskit/css` `cssMap` function call that are not valid
+
+  Changes made:
+
+  - Add them to monorepo, modify to use the existing utility functions
+  - Add support for CSS-in-JS libraries other than Compiled (styled-components, Emotion, `@atlaskit/css`, etc.) and `xcss` where appropriate
+
 ## 8.25.2
 
 ### Patch Changes

package/README.md

@@ -59,6 +59,10 @@ module.exports = {
 | <a href="./src/rules/no-deprecated-apis/README.md">no-deprecated-apis</a>                                         | Disallow using deprecated APIs.                                                                                                                                                                                                                                                                                     | Yes         |         |             |
 | <a href="./src/rules/no-deprecated-design-token-usage/README.md">no-deprecated-design-token-usage</a>             | Disallow using deprecated design tokens.                                                                                                                                                                                                                                                                            | Yes         | Yes     |             |
 | <a href="./src/rules/no-deprecated-imports/README.md">no-deprecated-imports</a>                                   | Disallow importing deprecated modules.                                                                                                                                                                                                                                                                              | Yes         |         |             |
+| <a href="./src/rules/no-empty-styled-expression/README.md">no-empty-styled-expression</a>                         | Forbids any styled expression to be used when passing empty arguments to styled.div() (or other JSX elements).                                                                                                                                                                                                      | Yes         |         |             |
+| <a href="./src/rules/no-exported-css/README.md">no-exported-css</a>                                               | Forbid exporting `css` function calls. Exporting `css` function calls can result in unexpected behaviour at runtime, and is not statically analysable.                                                                                                                                                              | Yes         |         |             |
+| <a href="./src/rules/no-exported-keyframes/README.md">no-exported-keyframes</a>                                   | Forbid exporting `keyframes` function calls. Exporting `css` function calls can result in unexpected behaviour at runtime, and is not statically analysable.                                                                                                                                                        | Yes         |         |             |
+| <a href="./src/rules/no-invalid-css-map/README.md">no-invalid-css-map</a>                                         | Checks the validity of a CSS map created through cssMap. This is intended to be used alongside TypeScript's type-checking.                                                                                                                                                                                          | Yes         |         |             |
 | <a href="./src/rules/no-margin/README.md">no-margin</a>                                                           | Disallow using the margin CSS property.                                                                                                                                                                                                                                                                             |             |         |             |
 | <a href="./src/rules/no-nested-styles/README.md">no-nested-styles</a>                                             | Disallows use of nested styles in `css` functions.                                                                                                                                                                                                                                                                  | Yes         |         |             |
 | <a href="./src/rules/no-physical-properties/README.md">no-physical-properties</a>                                 | Disallow physical properties and values in `css` function calls.                                                                                                                                                                                                                                                    |             | Yes     |             |

package/constellation/index/usage.mdx

@@ -23,6 +23,10 @@ This plugin contains rules that should be used when working with the [Atlassian
 | <a href="#no-deprecated-apis">no-deprecated-apis</a>                                         | Disallow using deprecated APIs.                                                                                                                                                                                                                                                                                     | Yes         |         |             |
 | <a href="#no-deprecated-design-token-usage">no-deprecated-design-token-usage</a>             | Disallow using deprecated design tokens.                                                                                                                                                                                                                                                                            | Yes         | Yes     |             |
 | <a href="#no-deprecated-imports">no-deprecated-imports</a>                                   | Disallow importing deprecated modules.                                                                                                                                                                                                                                                                              | Yes         |         |             |
+| <a href="#no-empty-styled-expression">no-empty-styled-expression</a>                         | Forbids any styled expression to be used when passing empty arguments to styled.div() (or other JSX elements).                                                                                                                                                                                                      | Yes         |         |             |
+| <a href="#no-exported-css">no-exported-css</a>                                               | Forbid exporting `css` function calls. Exporting `css` function calls can result in unexpected behaviour at runtime, and is not statically analysable.                                                                                                                                                              | Yes         |         |             |
+| <a href="#no-exported-keyframes">no-exported-keyframes</a>                                   | Forbid exporting `keyframes` function calls. Exporting `css` function calls can result in unexpected behaviour at runtime, and is not statically analysable.                                                                                                                                                        | Yes         |         |             |
+| <a href="#no-invalid-css-map">no-invalid-css-map</a>                                         | Checks the validity of a CSS map created through cssMap. This is intended to be used alongside TypeScript's type-checking.                                                                                                                                                                                          | Yes         |         |             |
 | <a href="#no-margin">no-margin</a>                                                           | Disallow using the margin CSS property.                                                                                                                                                                                                                                                                             |             |         |             |
 | <a href="#no-nested-styles">no-nested-styles</a>                                             | Disallows use of nested styles in `css` functions.                                                                                                                                                                                                                                                                  | Yes         |         |             |
 | <a href="#no-physical-properties">no-physical-properties</a>                                 | Disallow physical properties and values in `css` function calls.                                                                                                                                                                                                                                                    |             | Yes     |             |
@@ -54,14 +58,19 @@ Every product should be defining styles in the same way, using the same tools, e
 
 This rule checks for the following cases:
 
-- When styles are defined inline.
-- When styles are not using `css` object api.
-- 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.
+- Styles should not be defined inline; it should instead be in a standalone variable.
+  - The exception for this is style composition (e.g. `<div css={[baseStyles, moreStyles]} />`), which is a way to combine styles from two variables.
+- Styles must be wrapped in a `css` function call.
+- Styles must be defined in the same file as their usage, and not be imported.
+- Styles should not contain spread operators (e.g. `css({ ...spreadStyles })`).
+- Styles must all be defined at the top of the file, or at the bottom of the file.
+- Styles must be in a variable whose name ends in `styles` (or `Styles`).
+
+This rule also has an autofixer that enforces and fixes the code (where practical) to meet the above requirements.
 
 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.
+This rule has several options - see below.
 
 <h3>Examples</h3>
 
@@ -193,13 +202,44 @@ 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']`. Functionality of cssMap will be linted regardless of the configuration of `cssFunctions` as it can be used with either attribute.
+An array of function names the linting rule should target. Defaults to `['css', 'xcss']`. The functionality of `cssMap` will be linted regardless of the configuration of `cssFunctions`, as it can be used with either attribute.
 
 #### stylesPlacement
 
+Either `top` or `bottom`.
+
 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`.
 
+#### cssImportSource
+
+When auto-fixing the contents of the `css` attribute, this rule will wrap CSS styles in a `css(...)` function call or `` css\`...\`  `` template expression, and it will add an import declaration for the `css` function. `cssImportSource` is a string that determines what package `css` should be imported from.
+
+This is `@compiled/react` by default.
+
+#### xcssImportSource
+
+When auto-fixing the contents of the `xcss` attribute, this rule will wrap XCSS styles in a `xcss(...)` function call, and it will add an import declaration for the `xcss` function. `cssImportSource` is a string that determines what package `xcss` should be imported from.
+
+This is `@atlaskit/primitives` by default.
+
+#### excludeReactComponents
+
+Whether to exclude `css` attributes of React components from being affected by this ESLint rule. We assume that an element is a React component if its name starts with a capital letter, e.g. `<Button />`.
+
+This is `false` by default.
+
+#### fixNamesOnly
+
+When enabled, this rule will only add `styles` at the end of existing style variables. All other autofixers will be disabled. For example:
+
+```tsx
+//    vvvvv will be renamed to `myCssStyles`
+const myCss = { color: 'blue' };
+```
+
+This is `false` by default.
+
 ## ensure-design-token-usage
 
 Using design tokens results in a harmonious experience for end users whilst providing theming and consistency.
@@ -583,6 +623,362 @@ module.exports = {
 };
 ```
 
+## 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> </>`.
+
+<h3>Examples</h3>
+
+#### 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',
+  },
+});
+```
+
+<h3>What to do instead?</h3>
+
+#### 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</>;
+  }
+```
+
+<h3>Options</h3>
+
+#### importSources
+
+By default, this rule will check `styled` usages from `@compiled/react`. To check `styled` usages from other CSS-in-JS libraries, you can add the library's package name to `importSources`.
+
+`importSources` accepts an array of package names (strings). `styled` usages from `@compiled/react` will always be checked, regardless of the value of `importSources`.
+
+```tsx
+// [{ importSources: ['styled-components'] }]
+
+import styled from 'styled-components';
+
+// Invalid!
+const styles = styled({});
+```
+
+## 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.
+
+<h3>Examples</h3>
+
+#### Incorrect
+
+```tsx
+import { css } from '@compiled/react';
+
+export const styles = css({});
+
+export default css({});
+```
+
+#### Correct
+
+```tsx
+import { css } from '@compiled/react';
+
+const styles = css({});
+```
+
+<h3>Options</h3>
+
+#### importSources
+
+By default, this rule will check `css` usages from `@compiled/react` and `@atlaskit/css`. To check `css` usages from other CSS-in-JS libraries, you can add the library's package name to `importSources`.
+
+`importSources` accepts an array of package names (strings). `css` usages from `@compiled/react` and `@atlaskit/css` will always be checked, regardless of the value of `importSources`.
+
+```tsx
+// [{ importSources: ['@emotion/css'] }]
+
+import { css } from '@emotion/css';
+
+// Invalid!
+export const styles = css({});
+```
+
+## 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.
+
+<h3>Examples</h3>
+
+#### Incorrect
+
+```tsx
+import { keyframes } from '@compiled/react';
+
+export const animation = keyframes({});
+
+export default keyframes({});
+```
+
+#### Correct
+
+```tsx
+import { keyframes } from '@compiled/react';
+
+const animation = keyframes({});
+```
+
+<h3>Options</h3>
+
+#### importSources
+
+By default, this rule will check `keyframes` usages from `@compiled/react`. To check `keyframes` usages from other CSS-in-JS libraries, you can add the library's package name to `importSources`.
+
+`importSources` accepts an array of package names (strings). `keyframes` usages from `@compiled/react` will always be checked, regardless of the value of `importSources`.
+
+```tsx
+// [{ importSources: ['@emotion/css'] }]
+
+import { keyframes } from '@emotion/css';
+
+// Invalid!
+export const styles = keyframes({});
+```
+
+## 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).
+
+<h3>Examples</h3>
+
+#### 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`.
+
 ## no-margin
 
 Using margins to define spacing results in components that can't be readily reused in other contexts breaking the composition model.

package/dist/cjs/presets/all.codegen.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.default = void 0;
 /**
  * THIS FILE WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
- * @codegen <<SignedSource::5026ba2cb55b3c1bcacbfe7fb7728a6c>>
+ * @codegen <<SignedSource::914085544778f4543f43e3e30d0982e0>>
  * @codegenCommand yarn workspace @atlaskit/eslint-plugin-design-system codegen
  */
 var _default = exports.default = {
@@ -22,6 +22,10 @@ var _default = exports.default = {
     '@atlaskit/design-system/no-deprecated-apis': 'error',
     '@atlaskit/design-system/no-deprecated-design-token-usage': 'warn',
     '@atlaskit/design-system/no-deprecated-imports': 'error',
+    '@atlaskit/design-system/no-empty-styled-expression': 'warn',
+    '@atlaskit/design-system/no-exported-css': 'warn',
+    '@atlaskit/design-system/no-exported-keyframes': 'warn',
+    '@atlaskit/design-system/no-invalid-css-map': 'error',
     '@atlaskit/design-system/no-margin': 'warn',
     '@atlaskit/design-system/no-nested-styles': 'error',
     '@atlaskit/design-system/no-physical-properties': 'error',

package/dist/cjs/presets/recommended.codegen.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.default = void 0;
 /**
  * THIS FILE WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
- * @codegen <<SignedSource::839224bfab98c1ddf6018dec5320968e>>
+ * @codegen <<SignedSource::577269c832952ce359cde6a50f26f4e0>>
  * @codegenCommand yarn workspace @atlaskit/eslint-plugin-design-system codegen
  */
 var _default = exports.default = {
@@ -20,6 +20,10 @@ var _default = exports.default = {
     '@atlaskit/design-system/no-deprecated-apis': 'error',
     '@atlaskit/design-system/no-deprecated-design-token-usage': 'warn',
     '@atlaskit/design-system/no-deprecated-imports': 'error',
+    '@atlaskit/design-system/no-empty-styled-expression': 'warn',
+    '@atlaskit/design-system/no-exported-css': 'warn',
+    '@atlaskit/design-system/no-exported-keyframes': 'warn',
+    '@atlaskit/design-system/no-invalid-css-map': 'error',
     '@atlaskit/design-system/no-nested-styles': 'error',
     '@atlaskit/design-system/no-unsafe-design-token-usage': 'error',
     '@atlaskit/design-system/no-unsafe-style-overrides': 'warn',