@atlaskit/eslint-plugin-design-system 9.7.0 → 10.0.0

package/constellation/no-direct-use-of-web-platform-drag-and-drop/usage.mdx

@@ -4,7 +4,11 @@ Block the usage of web platform drag and drop functionality directly. Use Pragma
 
 ## Rationale
 
-The web platform has powerful drag and drop functionality built in. However, it is hard to be successful with web platform drag and drop due to bugs, inconsistencies and usage friction. Rather than leveraging the web platform API directly, the rule enforces the usage of [Pragmatic drag and drop](https://atlassian.design/components/pragmatic-drag-and-drop), which allows people to easily and successfully leverage web platform drag and drop.
+The web platform has powerful drag and drop functionality built in. However, it is hard to be
+successful with web platform drag and drop due to bugs, inconsistencies and usage friction. Rather
+than leveraging the web platform API directly, the rule enforces the usage of
+[Pragmatic drag and drop](https://atlassian.design/components/pragmatic-drag-and-drop), which allows
+people to easily and successfully leverage web platform drag and drop.
 
 ## Examples
 
@@ -12,7 +16,8 @@ This rule marks direct usage of web platform drag events as violations.
 
 ### Incorrect
 
-Adding drag related event listeners on intrinsic `react` elements (eg `div`, `span`, `strong` and so on).
+Adding drag related event listeners on intrinsic `react` elements (eg `div`, `span`, `strong` and so
+on).
 
 ```tsx
 <div onDragStart={fn}>{children}</div>
@@ -71,7 +76,8 @@ window.addEventListener('dragend', fn);
                         ^^^^^^^^^
 ```
 
-Binding drag related events using `bind()` from [bind-event-listener](https://github.com/alexreardon/bind-event-listener)
+Binding drag related events using `bind()` from
+[bind-event-listener](https://github.com/alexreardon/bind-event-listener)
 
 ```ts
 import {bind} from 'bind-event-listener';
@@ -92,7 +98,8 @@ bind(element, { type: 'dragend', listener: fn });
                       ^^^^^^^^^
 ```
 
-Binding drag related events using `bindAll()` from [bind-event-listener](https://github.com/alexreardon/bind-event-listener)
+Binding drag related events using `bindAll()` from
+[bind-event-listener](https://github.com/alexreardon/bind-event-listener)
 
 ```ts
 import {bindAll} from 'bind-event-listener';
@@ -123,15 +130,17 @@ Leveraging Pragmatic drag and drop for web platform drag and drop.
 import { monitor } from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
 
 monitor({
-  onGenerateDragPreview: fn,
-  onDragStart: fn,
-  onDropTargetChange: fn,
-  onDrag: fn,
-  onDrop: fn,
+    onGenerateDragPreview: fn,
+    onDragStart: fn,
+    onDropTargetChange: fn,
+    onDrag: fn,
+    onDrop: fn,
 });
 ```
 
-> See the [Pragmatic drag and drop documentation](https://atlassian.design/components/pragmatic-drag-and-drop) for more information about it's usage.
+> See the
+> [Pragmatic drag and drop documentation](https://atlassian.design/components/pragmatic-drag-and-drop)
+> for more information about it's usage.
 
 Using blocked JSX attributes on custom `react` components
 

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

@@ -1,8 +1,12 @@
 # no-empty-styled-expression
 
-Disallows/discourages passing empty arguments to any `styled` expression when using a CSS-in-JS library, including `@atlaskit/css`, `@compiled/react`, Emotion, and `styled-components`.
+Disallows/discourages passing empty arguments to any `styled` expression when using a CSS-in-JS
+library, including `@atlaskit/css`, `@compiled/react`, Emotion, and `styled-components`.
 
-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> </>`.
+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
 
@@ -20,10 +24,10 @@ const EmptyStyledExpressionArgument = styled.div([]);
 
 ```tsx
 const Wrapper = styled.div({
-  backgroundColor: 'red',
-  MyComponent: {
-    backgroundColor: 'green',
-  },
+    backgroundColor: 'red',
+    MyComponent: {
+        backgroundColor: 'green',
+    },
 });
 ```
 
@@ -57,15 +61,16 @@ const Wrapper = styled.div({
 
 By default, this rule will check `styled` usages from:
 
-- `@atlaskit/css`
-- `@atlaskit/primitives`
-- `@compiled/react`
-- `@emotion/react`
-- `@emotion/core`
-- `@emotion/styled`
-- `styled-components`
+-   `@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).
+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'] }]

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

@@ -1,8 +1,12 @@
 # no-exported-css
 
-Disallows `css` export declarations that originate from a CSS-in-JS library, including `@atlaskit/css`, `@compiled/react`, Emotion, and `styled-components`.
+Disallows `css` export declarations that originate from a CSS-in-JS library, including
+`@atlaskit/css`, `@compiled/react`, Emotion, and `styled-components`.
 
-In Compiled (`@atlaskit/css` and `@compiled/react`), 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.
+In Compiled (`@atlaskit/css` and `@compiled/react`), 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
 
@@ -30,15 +34,16 @@ const styles = css({});
 
 By default, this rule will check `css` usages from:
 
-- `@atlaskit/css`
-- `@atlaskit/primitives`
-- `@compiled/react`
-- `@emotion/react`
-- `@emotion/core`
-- `@emotion/styled`
-- `styled-components`
+-   `@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).
+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'] }]

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

@@ -1,8 +1,12 @@
 # no-exported-keyframes
 
-Disallows `keyframes` export declarations that originate from a CSS-in-JS library, including `@atlaskit/css`, `@compiled/react`, Emotion, and `styled-components`.
+Disallows `keyframes` export declarations that originate from a CSS-in-JS library, including
+`@atlaskit/css`, `@compiled/react`, Emotion, and `styled-components`.
 
-In Compiled (`@atlaskit/css` and `@compiled/react`), 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.
+In Compiled (`@atlaskit/css` and `@compiled/react`), 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
 
@@ -30,15 +34,16 @@ const animation = keyframes({});
 
 By default, this rule will check `keyframes` usages from:
 
-- `@atlaskit/css`
-- `@atlaskit/primitives`
-- `@compiled/react`
-- `@emotion/react`
-- `@emotion/core`
-- `@emotion/styled`
-- `styled-components`
+-   `@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).
+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'] }]

package/constellation/no-html-anchor/usage.mdx

@@ -0,0 +1,40 @@
+# no-html-anchor
+
+Don't use native HTML anchors. The Atlassian Design System provides ready-made link components that
+include event tracking, automatic router configuration, ensure accessible implementations, and
+provide access to ADS styling features like design tokens.
+
+Use Atlassian Design System components such as the [Link](/components/link/) or
+[LinkButton](/components/button/link-button/) components when suitable. There may also be other
+components better-suited depending on the use case. If these components aren't suitable, use the
+[Anchor primitive](/components/primitives/anchor/) which helps you build custom links with Atlassian
+Design System styling.
+
+## Examples
+
+This rule marks code as violations when it finds native HTML anchor elements.
+
+### Incorrect
+
+```jsx
+<a href="/">
+ ^ Using a native HTML `<a>`
+  Hello, World!
+</a>
+```
+
+### Correct
+
+```jsx
+import Anchor from '@atlaskit/primitives/anchor';
+
+<Anchor href="/">Hello, World!</Anchor>;
+
+import Link from '@atlaskit/link';
+
+<Link href="/">Hello, World!</Link>;
+
+import { LinkButton } from '@atlaskit/button/new';
+
+<LinkButton href="/">Hello, World!</LinkButton>;
+```

package/constellation/no-html-button/usage.mdx

@@ -0,0 +1,52 @@
+# no-html-button
+
+Don't use native HTML buttons. The Atlassian Design System provides ready-made button components
+that include event tracking, ensure accessible implementations, and provide access to ADS styling
+features like design tokens.
+
+Use Atlassian Design System components such as the [Button component](/components/button/) when
+suitable. There may also be other components better-suited depending on the use case. If these
+components aren't suitable, use the [Pressable primitive](/components/primitives/pressable/) which
+helps you build custom buttons with Atlassian Design System styling.
+
+## Examples
+
+This rule marks code as violations when it finds native HTML button elements.
+
+### Incorrect
+
+```jsx
+<button>
+ ^^^^^^ Using a native HTML `<button>`
+  Hello, World!
+</button>
+
+<div role="button" tabIndex="0">
+     ^^^^^^^^^^^^^ Using `role="button"` to create buttons
+  Hello, World!
+</div>
+
+<input type="button" value="Button" />
+       ^^^^^^^^^^^^^ Using a `<input>` as a button
+
+<input type="submit" value="Submit" />
+       ^^^^^^^^^^^^^ Using a `<input>` as a button
+
+<input type="reset" value="Reset" />
+       ^^^^^^^^^^^^ Using a `<input>` as a button
+
+<input type="image" alt="Submit" src="/submit-button.png" />
+       ^^^^^^^^^^^^ Using a `<input>` as a button
+```
+
+### Correct
+
+```jsx
+import Pressable from '@atlaskit/primitives/pressable';
+
+<Pressable>Hello, World!</Pressable>;
+
+import Button from '@atlaskit/button/new';
+
+<Button>Hello, World!</Button>;
+```

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

@@ -1,10 +1,14 @@
 # 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`.
+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.
+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`.
+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).
 
@@ -20,11 +24,11 @@ import { cssMap } from '@compiled/react';
 // (not within a function, class, etc.)
 
 const Foo = () => {
-  const bar = cssMap({
-    danger: {
-      color: 'red',
-    },
-  });
+    const bar = cssMap({
+        danger: {
+            color: 'red',
+        },
+    });
 };
 ```
 
@@ -38,11 +42,11 @@ import { importedVariable, importedFunction } from 'another-package';
 const myVariable = importedFunction();
 
 const styles = cssMap({
-  danger: {
-    // Both invalid because they rely on an imported function.
-    color: myVariable,
-    padding: importedFunction(),
-  },
+    danger: {
+        // Both invalid because they rely on an imported function.
+        color: myVariable,
+        padding: importedFunction(),
+    },
 });
 ```
 
@@ -54,9 +58,9 @@ import { cssMap } from '@compiled/react';
 // Any usages of cssMap must be in the same file.
 
 export const foo = cssMap({
-  danger: {
-    color: 'red',
-  },
+    danger: {
+        color: 'red',
+    },
 });
 ```
 
@@ -69,29 +73,29 @@ import { token } from '@atlaskit/tokens';
 // values in cssMap.
 
 const styles = cssMap({
-  // Object method
-  get danger() {
-    return { color: '#123456' };
-  },
+    // Object method
+    get danger() {
+        return { color: '#123456' };
+    },
 });
 
 const styles2 = cssMap({
-  // Arrow function
-  danger: () => {
-    color: '#123456';
-  },
+    // Arrow function
+    danger: () => {
+        color: '#123456';
+    },
 });
 
 function customFunction(...args) {
-  return arguments.join('');
+    return arguments.join('');
 }
 
 const styles3 = cssMap({
-  danger: {
-    // Locally defined function
-    color: customFunction('red', 'blue'),
-    backgroundColor: 'red',
-  },
+    danger: {
+        // Locally defined function
+        color: customFunction('red', 'blue'),
+        backgroundColor: 'red',
+    },
 });
 ```
 
@@ -102,16 +106,16 @@ import { cssMap } from '@compiled/react';
 // Spread elements ("...") cannot be used in cssMap.
 
 const base = {
-  success: {
-    color: 'green',
-  },
+    success: {
+        color: 'green',
+    },
 };
 
 const bar = cssMap({
-  ...base,
-  danger: {
-    color: 'red',
-  },
+    ...base,
+    danger: {
+        color: 'red',
+    },
 });
 ```
 
@@ -125,14 +129,14 @@ import { cssMap } from '@compiled/react';
 // in cssMap.
 
 const styles = cssMap({
-  danger: {
-    color: 'red',
-    backgroundColor: 'red',
-  },
-  success: {
-    color: 'green',
-    backgroundColor: 'green',
-  },
+    danger: {
+        color: 'red',
+        backgroundColor: 'red',
+    },
+    success: {
+        color: 'green',
+        backgroundColor: 'green',
+    },
 });
 ```
 
@@ -146,9 +150,9 @@ import { cssMap } from '@compiled/react';
 const bap = 'blue';
 
 const styles = cssMap({
-  danger: {
-    color: bap,
-  },
+    danger: {
+        color: bap,
+    },
 });
 ```
 
@@ -156,7 +160,8 @@ const styles = cssMap({
 
 #### `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:
+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';
@@ -164,17 +169,20 @@ import { cssMap } from '@compiled/react';
 import { token } from '@atlaskit/tokens';
 
 const styles = cssMap({
-  danger: {
-    color: token('my-color'),
-    backgroundColor: 'red',
-  },
-  success: {
-    color: 'green',
-  },
+    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.
+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.
 
@@ -196,4 +204,7 @@ For example, with the below configuration, the above code example would be okay.
 // ...
 ```
 
-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`.
+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`.

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

@@ -1,10 +1,15 @@
 # no-keyframes-tagged-template-expression
 
-Disallows any `keyframes` tagged template expressions that originate from a CSS-in-JS library, including `@atlaskit/css`, `@compiled/react`, Emotion, and `styled-components`.
+Disallows any `keyframes` tagged template expressions that originate from a CSS-in-JS library,
+including `@atlaskit/css`, `@compiled/react`, Emotion, and `styled-components`.
 
-Tagged template expressions are difficult to parse correctly (which can lead to more frequent build failures or invalid CSS generation), have limited type safety, and lack syntax highlighting. These problems can be avoided by using the preferred call expression syntax instead.
+Tagged template expressions are difficult to parse correctly (which can lead to more frequent build
+failures or invalid CSS generation), have limited type safety, and lack syntax highlighting. These
+problems can be avoided by using the preferred call expression syntax instead.
 
-Thank you to the [Compiled team for their rule](https://github.com/atlassian-labs/compiled/tree/master/packages/eslint-plugin/src/rules/no-keyframes-tagged-template-expression) from which this was ported.
+Thank you to the
+[Compiled team for their rule](https://github.com/atlassian-labs/compiled/tree/master/packages/eslint-plugin/src/rules/no-keyframes-tagged-template-expression)
+from which this was ported.
 
 The `--fix` option on the command line automatically fixes problems reported by this rule.
 
@@ -35,12 +40,12 @@ import { keyframes } from '@compiled/react';
 keyframes({ to: { opacity: 0 } });
 
 const fadeOut = keyframes({
-  from: {
-    opacity: 1,
-  },
-  to: {
-    opacity: 0,
-  },
+    from: {
+        opacity: 1,
+    },
+    to: {
+        opacity: 0,
+    },
 });
 ```
 
@@ -50,15 +55,16 @@ const fadeOut = keyframes({
 
 By default, this rule will check `keyframes` usages from:
 
-- `@atlaskit/css`
-- `@atlaskit/primitives`
-- `@compiled/react`
-- `@emotion/react`
-- `@emotion/core`
-- `@emotion/styled`
-- `styled-components`
+-   `@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).
+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'] }]
@@ -71,4 +77,4 @@ export const animation = keyframes``;
 
 ## Limitations
 
-- Comments are not fixable
+-   Comments are not fixable

package/constellation/no-margin/usage.mdx

@@ -1,7 +1,8 @@
 # no-margin
 
-Using margins to define spacing results in components that can't be readily reused in other contexts breaking the composition model.
-Instead defining spacing in parents with flex and grid using the `gap` property will result in more resilient experiences.
+Using margins to define spacing results in components that can't be readily reused in other contexts
+breaking the composition model. Instead defining spacing in parents with flex and grid using the
+`gap` property will result in more resilient experiences.
 
 ## Examples
 

package/constellation/no-nested-styles/usage.mdx

@@ -1,27 +1,27 @@
 # no-nested-styles
 
-Disallows using nested styles. Nested styles can change unexpectedly when child markup changes and result in duplicates when extracting to CSS.
+Disallows using nested styles. Nested styles can change unexpectedly when child markup changes and
+result in duplicates when extracting to CSS.
 
 ## Examples
 
-This rule checks for nested styles inside `css` objects.
-This rule has no options.
+This rule checks for nested styles inside `css` objects. This rule has no options.
 
 ### Incorrect
 
 ```js
 css({
-  div: {
-    color: 'red',
-  },
+    div: {
+        color: 'red',
+    },
 });
 ```
 
 ```js
 css({
-  '@media (min-width: 480px)': {
-    color: 'red',
-  },
+    '@media (min-width: 480px)': {
+        color: 'red',
+    },
 });
 ```
 
@@ -29,10 +29,10 @@ css({
 
 ```js
 css({
-  color: 'red',
-  ':hover': {
-    color: 'black',
-  },
+    color: 'red',
+    ':hover': {
+        color: 'black',
+    },
 });
 ```
 
@@ -40,8 +40,8 @@ css({
 import { media } from '@atlaskit/primitives';
 
 css({
-  [media.above.xs]: {
-    color: 'red',
-  },
+    [media.above.xs]: {
+        color: 'red',
+    },
 });
 ```