@atlaskit/eslint-plugin-ui-styling-standard 0.16.3 → 0.16.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/constellation/atlaskit-theme/usage.mdx +74 -55
  3. package/constellation/convert-props-syntax/usage.mdx +29 -24
  4. package/constellation/enforce-style-prop/usage.mdx +32 -26
  5. package/constellation/local-cx-xcss/usage.mdx +27 -15
  6. package/constellation/no-array-arguments/usage.mdx +12 -9
  7. package/constellation/no-classname-prop/usage.mdx +13 -5
  8. package/constellation/no-container-queries/usage.mdx +65 -16
  9. package/constellation/no-dynamic-styles/usage.mdx +16 -11
  10. package/constellation/no-exported-styles/usage.mdx +25 -30
  11. package/constellation/no-global-styles/usage.mdx +4 -3
  12. package/constellation/no-important-styles/usage.mdx +5 -3
  13. package/constellation/no-imported-style-values/usage.mdx +30 -27
  14. package/constellation/no-nested-selectors/usage.mdx +51 -18
  15. package/constellation/no-styled/usage.mdx +17 -14
  16. package/constellation/no-unsafe-selectors/usage.mdx +184 -58
  17. package/constellation/no-unsafe-values/usage.mdx +150 -48
  18. package/constellation/use-compiled/usage.mdx +8 -8
  19. package/dist/cjs/rules/no-imported-style-values/index.js +50 -2
  20. package/dist/es2019/rules/no-imported-style-values/index.js +49 -2
  21. package/dist/esm/rules/no-imported-style-values/index.js +50 -2
  22. package/package.json +1 -1
  23. package/src/rules/atlaskit-theme/README.md +74 -55
  24. package/src/rules/convert-props-syntax/README.md +29 -24
  25. package/src/rules/enforce-style-prop/README.md +32 -26
  26. package/src/rules/local-cx-xcss/README.md +27 -15
  27. package/src/rules/no-array-arguments/README.md +12 -9
  28. package/src/rules/no-classname-prop/README.md +13 -5
  29. package/src/rules/no-container-queries/README.md +65 -16
  30. package/src/rules/no-dynamic-styles/README.md +16 -11
  31. package/src/rules/no-exported-styles/README.md +25 -30
  32. package/src/rules/no-global-styles/README.md +4 -3
  33. package/src/rules/no-important-styles/README.md +5 -3
  34. package/src/rules/no-imported-style-values/README.md +30 -27
  35. package/src/rules/no-imported-style-values/__tests__/rule.test.tsx +208 -0
  36. package/src/rules/no-imported-style-values/index.tsx +51 -4
  37. package/src/rules/no-nested-selectors/README.md +51 -18
  38. package/src/rules/no-styled/README.md +17 -14
  39. package/src/rules/no-unsafe-selectors/README.md +184 -58
  40. package/src/rules/no-unsafe-values/README.md +150 -48
  41. package/src/rules/use-compiled/README.md +8 -8
@@ -1,21 +1,23 @@
1
- Disallows unsafe selectors in CSS-in-JS style objects.
1
+ Blocks unsafe CSS selectors.
2
2
 
3
- This enables static analysis and prevents regressions and incidents when migrating between styling
4
- APIs.
5
-
6
- Use this rule alongside
3
+ Use alongside
7
4
  [no-nested-selectors](https://atlassian.design/components/eslint-plugin-ui-styling-standard/no-nested-selectors/usage)
8
- as the rules are complementary.
5
+ which blocks nested CSS selectors.
6
+
7
+ Blocking unsafe selectors enables static analysis and also prevents regressions and incidents when
8
+ migrating styles at scale.
9
9
 
10
10
  ## Examples
11
11
 
12
- ### Incorrect
12
+ ### Keyframes
13
+
14
+ #### Incorrect
13
15
 
14
- **No @keyframes at-rules**
16
+ Don't use `@keyframes` at-rules in styles.
15
17
 
16
- Use the `keyframes` CSS-in-JS API instead.
18
+ ```tsx
19
+ import { css } from '@compiled/react';
17
20
 
18
- ```ts
19
21
  css({
20
22
  '@keyframes fadeIn': {
21
23
  from: {
@@ -25,41 +27,102 @@ css({
25
27
  opacity: 1,
26
28
  },
27
29
  },
30
+ animation: '1s ease-in fadeIn',
28
31
  });
29
32
  ```
30
33
 
31
- **No legacy pseudo-element syntax**
34
+ #### Correct
35
+
36
+ Use the `keyframes` API.
37
+
38
+ ```tsx
39
+ import { css, keyframes } from '@compiled/react';
40
+
41
+ const fadeIn = keyframes({
42
+ from: {
43
+ opacity: 0,
44
+ },
45
+ to: {
46
+ opacity: 1,
47
+ },
48
+ });
49
+
50
+ css({
51
+ animation: `1s ease-in ${fadeIn}`,
52
+ });
53
+ ```
54
+
55
+ ### Legacy pseudo-element syntax
56
+
57
+ #### Incorrect
58
+
59
+ Don't use the legacy single colon syntax for pseudo-elements.
32
60
 
33
- Use the `::` double colon syntax for pseudo-elements.
61
+ This issue is autofixable.
34
62
 
35
- _Auto-fixer is available for this violation._
63
+ ```tsx
64
+ import { css } from '@compiled/react';
36
65
 
37
- ```ts
38
66
  css({
39
- ':after': {
67
+ '&:after': {
40
68
  content: '""',
41
- width: 100,
42
- height: 100,
43
- backgroundColor: 'red',
44
69
  },
45
70
  });
46
71
  ```
47
72
 
48
- **No increased specificity selectors**
73
+ #### Correct
49
74
 
50
- Use styles that do not require increased specificity.
75
+ Use the double colon syntax for pseudo-elements.
76
+
77
+ ```tsx
78
+ import { css } from '@compiled/react';
79
+
80
+ css({
81
+ '&::after': {
82
+ content: '""',
83
+ },
84
+ });
85
+ ```
86
+
87
+ ### Increased specificity selectors
88
+
89
+ #### Incorrect
90
+
91
+ Don't use the nesting selector to increase specificity of styles.
92
+
93
+ ```tsx
94
+ import { css } from '@compiled/react';
95
+ import { token } from '@atlaskit/tokens';
51
96
 
52
- ```ts
53
97
  css({
54
98
  '&&': {
55
- color: 'red',
99
+ color: token('color.text'),
56
100
  },
57
101
  });
58
102
  ```
59
103
 
60
- **No restricted at-rules**
104
+ #### Correct
105
+
106
+ Use styles that do not require increased specificity.
107
+
108
+ ```tsx
109
+ import { css } from '@compiled/react';
110
+ import { token } from '@atlaskit/tokens';
111
+
112
+ css({
113
+ color: token('color.text'),
114
+ });
115
+ ```
116
+
117
+ ### At-rules
118
+
119
+ #### Incorrect
120
+
121
+ Don't use at-rules in styles (see **Correct** below for exceptions).
122
+
123
+ ```tsx
124
+ import { css } from '@compiled/react';
61
125
 
62
- ```ts
63
126
  css({
64
127
  '@scope (.article-body) to (figure)': {
65
128
  img: {
@@ -69,34 +132,89 @@ css({
69
132
  });
70
133
  ```
71
134
 
72
- **No restricted pseudos**
135
+ #### Correct
136
+
137
+ Use only allowed at-rules:
138
+
139
+ - `@media` (through our
140
+ [breakpoints](https://atlassian.design/components/primitives/responsive/breakpoints/examples))
141
+ - `@property`
142
+ - `@supports`
143
+
144
+ ```tsx
145
+ import { css } from '@compiled/react';
146
+ import { media } from '@atlaskit/primitives/responsive';
147
+
148
+ css({
149
+ [media.above.sm]: {
150
+ display: 'block',
151
+ },
152
+ });
153
+ ```
154
+
155
+ ### Restricted pseudo-selectors
156
+
157
+ #### Incorrect
158
+
159
+ Don't use pseudo-classes which take arguments or implicitly rely on external context.
160
+
161
+ ```tsx
162
+ import { css } from '@compiled/react';
163
+ import { token } from '@atlaskit/tokens';
73
164
 
74
- ```ts
75
165
  css({
166
+ '&:hover': {
167
+ backgroundColor: token('color.background.neutral.hovered'),
168
+ },
169
+ '&:not(:hover)': {
170
+ backgroundColor: token('color.background.neutral'),
171
+ }
76
172
  '&:first-child': {
77
- width: 100,
173
+ fontWeight: token('font.weight.bold'),
78
174
  },
79
175
  });
80
176
  ```
81
177
 
82
- **No ambiguous pseudos**
178
+ #### Correct
83
179
 
84
- A pseudo-selector without a leading selector is ambiguous and is interpreted differently between
85
- contexts.
180
+ ```tsx
181
+ import { css } from '@compiled/react';
182
+ import { token } from '@atlaskit/tokens';
86
183
 
87
- Most CSS-in-JS libraries will implicitly add the nesting selector `&` before ambiguous
88
- pseudo-selectors. This is often the desired behavior.
184
+ type Props = { isFirstChild: boolean };
89
185
 
90
- The CSS nesting specification, CSS pre-processors, newer versions of `styled-components` (version
91
- 6+) and potentially future versions of `@emotion/*` will treat ambiguous pseudo-selectors as
92
- descendant selectors.
186
+ const baseStyles = css({
187
+ backgroundColor: token('color.background.neutral'),
188
+ '&:hover': {
189
+ backgroundColor: token('color.background.neutral.hovered'),
190
+ },
191
+ });
192
+
193
+ const firstChildStyles = css({
194
+ fontWeight: token('font.weight.bold'),
195
+ });
196
+
197
+ const Component = ({ isFirstChild }: Props) => (
198
+ <div css={[baseStyles, isFirstChild && firstChildStyles]} />
199
+ );
200
+ ```
201
+
202
+ ### Ambiguous pseudo-selectors
203
+
204
+ #### Incorrect
205
+
206
+ Don't use pseudo-selectors without a leading selector, as they are ambiguous and interpreted
207
+ differently between contexts.
208
+
209
+ For example some contexts will treat `:hover` as `&:hover` while others will treat it as `& :hover`
210
+ (which targets descendants).
93
211
 
94
- Use explicit selectors. Do not rely on implicit behavior for pseudo-selectors.
212
+ This issue is autofixable. By default a nesting selector `&` is added unless the
213
+ `shouldAlwaysInsertNestingSelectorForAmbiguousPseudos` option is disabled.
95
214
 
96
- _Auto-fixer is available for this violation. By default a nesting selector `&` is added unless the
97
- `shouldAlwaysInsertNestingSelectorForAmbiguousPseudos` option is disabled._
215
+ ```tsx
216
+ import { css } from '@compiled/react';
98
217
 
99
- ```ts
100
218
  css({
101
219
  /**
102
220
  * This pseudo-class has no leading selector and is ambiguous.
@@ -119,13 +237,24 @@ css({
119
237
  });
120
238
  ```
121
239
 
122
- **No grouped at-rules**
240
+ #### Correct
123
241
 
124
- Do not group at-rules with the `cssMap` API.
242
+ Use explicit selectors. Do not rely on implicit or undefined behavior for pseudo-selectors.
125
243
 
126
- Write flattened at-rules instead.
244
+ ```tsx
245
+
246
+ ```
247
+
248
+ ### Grouped at-rules
249
+
250
+ #### Incorrect
127
251
 
128
- ```ts
252
+ Don't group at-rules with the `cssMap` API.
253
+
254
+ ````tsx
255
+ import { cssMap } from '@compiled/react';
256
+
257
+ ```tsx
129
258
  cssMap({
130
259
  success: {
131
260
  '@media': {
@@ -134,15 +263,13 @@ cssMap({
134
263
  },
135
264
  },
136
265
  });
137
- ```
266
+ ````
138
267
 
139
- **No selectors object**
268
+ #### Correct
140
269
 
141
- Do not use a selectors object with the `cssMap` API.
142
-
143
- Refactor your styles so it is not required.
270
+ Write flattened at-rules instead.
144
271
 
145
- ```ts
272
+ ```tsx
146
273
  cssMap({
147
274
  success: {
148
275
  selectors: {
@@ -156,7 +283,7 @@ cssMap({
156
283
 
157
284
  ### Correct
158
285
 
159
- ```ts
286
+ ```tsx
160
287
  const fadeIn = keyframes({
161
288
  from: {
162
289
  opacity: 0,
@@ -171,7 +298,7 @@ css({
171
298
  });
172
299
  ```
173
300
 
174
- ```ts
301
+ ```tsx
175
302
  css({
176
303
  '::after': {
177
304
  content: '""',
@@ -182,7 +309,7 @@ css({
182
309
  });
183
310
  ```
184
311
 
185
- ```ts
312
+ ```tsx
186
313
  css({
187
314
  '&:first-of-type': {
188
315
  width: 100,
@@ -190,13 +317,13 @@ css({
190
317
  });
191
318
  ```
192
319
 
193
- ```ts
320
+ ```tsx
194
321
  css({
195
322
  '&:hover': {},
196
323
  });
197
324
  ```
198
325
 
199
- ```ts
326
+ ```tsx
200
327
  cssMap({
201
328
  success: {
202
329
  '@media (min-width: 900px)': {},
@@ -205,7 +332,7 @@ cssMap({
205
332
  });
206
333
  ```
207
334
 
208
- ```ts
335
+ ```tsx
209
336
  cssMap({
210
337
  success: {
211
338
  backgroundColor: 'white',
@@ -220,7 +347,7 @@ cssMap({
220
347
 
221
348
  ### `importSources: string[]`
222
349
 
223
- By default, this rule will check `css` usages from:
350
+ By default, this rule will check styles using:
224
351
 
225
352
  - `@atlaskit/css`
226
353
  - `@atlaskit/primitives`
@@ -230,8 +357,7 @@ By default, this rule will check `css` usages from:
230
357
  - `@emotion/styled`
231
358
  - `styled-components`
232
359
 
233
- To change this list of libraries, you can define a custom set of `importSources`, which accepts an
234
- array of package names (strings). This will override the built-in allow-list.
360
+ Override this list with the `importSources` option, which accepts an array of package names.
235
361
 
236
362
  ### `shouldAlwaysInsertNestingSelectorForAmbiguousPseudos: boolean`
237
363
 
@@ -1,12 +1,12 @@
1
- This rule prevents the usage of styles that are difficult/impossible to statically analyze.
1
+ Blocks styles that are difficult or impossible to statically analyze.
2
2
 
3
3
  ## Examples
4
4
 
5
- ### Incorrect
5
+ ### Function calls
6
6
 
7
- **Function calls**
7
+ #### Incorrect
8
8
 
9
- Function calls are not allowed as arguments or as values, unless they are specified in
9
+ Function calls are blocked as arguments or as values, unless they are specified in
10
10
  `allowedFunctionCalls` (or in the default list).
11
11
 
12
12
  ```tsx
@@ -31,48 +31,121 @@ const styles = css({
31
31
  });
32
32
  ```
33
33
 
34
- **Dynamic keys**
34
+ #### Correct
35
35
 
36
- Dynamic keys are not allowed, unless they are specified in `allowedDynamicKeys` (or in the default
36
+ Use inline literals for static values.
37
+
38
+ ```tsx
39
+ import { css } from '@compiled/react';
40
+
41
+ const styles = css({ width: 100 });
42
+ ```
43
+
44
+ Use the `style` prop for dynamic values.
45
+
46
+ ```tsx
47
+ const Component = ({ width }) => <div style={{ width }} />;
48
+ ```
49
+
50
+ Some functions such as `tokens()` are allowed.
51
+
52
+ ```tsx
53
+ import { css } from '@compiled/react';
54
+ import { token } from '@atlaskit/tokens';
55
+
56
+ const styles = css({ padding: token('space.100') });
57
+ ```
58
+
59
+ ### Dynamic keys
60
+
61
+ #### Incorrect
62
+
63
+ Dynamic keys are blocked, unless they are specified in `allowedDynamicKeys` (or in the default
37
64
  list).
38
65
 
39
66
  ```tsx
40
67
  import { css } from '@compiled/react';
41
- import { SELECTOR } from 'my-package';
68
+
69
+ const HOVER_SELECTOR = '&:hover';
70
+ const MARGIN = 'margin';
42
71
 
43
72
  const styles = css({
44
- [SELECTOR]: {
45
- color: 'red',
73
+ [HOVER_SELECTOR]: {
74
+ [MARGIN]: 0,
46
75
  },
47
- [`${SELECTOR} > p`]: {
76
+ [`${HOVER_SELECTOR} > p`]: {
48
77
  width: 100,
49
78
  },
50
79
  });
51
80
  ```
52
81
 
53
- **Variables**
82
+ #### Correct
54
83
 
55
- Variables are not allowed as values, unless they:
84
+ Use literal values for pseudo-states and property names.
56
85
 
57
- - Have a simple, static value
58
- - Are defined in the same file
86
+ Don't use nested selectors, apply styles directly instead.
59
87
 
60
88
  ```tsx
61
89
  import { css } from '@compiled/react';
62
- import { SELECTOR } from 'my-package';
63
90
 
64
- function myFunction() {
65
- return '5px';
66
- }
91
+ const styles = css({
92
+ '&:hover': {
93
+ margin: 0,
94
+ },
95
+ });
96
+
97
+ const paragraphStyles = css({
98
+ width: 100,
99
+ });
100
+ ```
101
+
102
+ ### Variables
103
+
104
+ #### Incorrect
105
+
106
+ Variables are only allowed as values if they:
107
+
108
+ - have a simple, static value
109
+ - are defined in the same file
110
+
111
+ ```tsx
112
+ import { css } from '@compiled/react';
113
+ import { HEIGHT } from '../shared';
114
+
115
+ const styles = css({
116
+ height: HEIGHT,
117
+ });
118
+ ```
119
+
120
+ #### Correct
121
+
122
+ Use inlined values.
123
+
124
+ ```tsx
125
+ import { css } from '@compiled/react';
126
+
127
+ const styles = css({
128
+ height: '32px',
129
+ });
130
+ ```
131
+
132
+ Alternatively, define variables in the same file.
133
+
134
+ ```tsx
135
+ import { css } from '@compiled/react';
136
+
137
+ const HEIGHT = '32px';
67
138
 
68
139
  const styles = css({
69
- height: myFunction,
140
+ height: HEIGHT,
70
141
  });
71
142
  ```
72
143
 
73
- **Object access**
144
+ ### Object access
74
145
 
75
- Accessing object members is not allowed in values.
146
+ #### Incorrect
147
+
148
+ Don't access object members in values.
76
149
 
77
150
  ```tsx
78
151
  import { css } from '@compiled/react';
@@ -87,59 +160,89 @@ const styles = css({
87
160
  });
88
161
  ```
89
162
 
90
- **Spread elements**
163
+ #### Correct
91
164
 
92
- Spread elements are not allowed.
165
+ Use inlined values.
93
166
 
94
167
  ```tsx
95
168
  import { css } from '@compiled/react';
169
+ import { token } from '@atlaskit/tokens';
170
+
171
+ const styles = css({
172
+ color: token('color.text'),
173
+ });
174
+ ```
175
+
176
+ ### Spread elements
177
+
178
+ #### Incorrect
96
179
 
97
- const buttonStyles = {
98
- color: 'blue',
180
+ Don't use the spread operator in styles.
181
+
182
+ ```tsx
183
+ import { css } from '@compiled/react';
184
+ import { token } from '@atlaskit/tokens';
185
+
186
+ const subtleTextStyles = {
187
+ color: token('color.text.subtle'),
99
188
  };
100
189
 
101
190
  const styles = css({
102
- ...buttonStyles,
191
+ ...subtleTextStyles,
192
+ margin: 0,
103
193
  });
104
194
  ```
105
195
 
106
- **Array values**
196
+ #### Correct
107
197
 
108
- Array values are not allowed. This syntax is not supported by most styling libraries.
198
+ Use the `css` prop to compose styles.
109
199
 
110
200
  ```tsx
111
201
  import { css } from '@compiled/react';
202
+ import { token } from '@atlaskit/tokens';
203
+
204
+ const subtleTextStyles = {
205
+ color: token('color.text.subtle'),
206
+ };
112
207
 
113
208
  const styles = css({
114
- '::before': [{ fontWeight: 'bold' }, { color: 'red' }],
209
+ margin: 0,
115
210
  });
211
+
212
+ const Component = () => <div css={[subtleTextStyles, styles]} />;
116
213
  ```
117
214
 
118
- ### Correct
215
+ ### Array values
119
216
 
120
- Things to note about the following example:
217
+ #### Incorrect
121
218
 
122
- - The `warningStyles` are conditionally applied using the `css` prop
123
- - The dynamic `width` is applied using the `style` prop
124
- - The `token()` calls are allowed because they are statically analyzable (and in the default
125
- allow-list)
219
+ Don't use array values. This syntax is not supported by Compiled, or most other CSS-in-JS libraries.
126
220
 
127
221
  ```tsx
128
222
  import { css } from '@compiled/react';
129
223
  import { token } from '@atlaskit/tokens';
130
224
 
131
- const baseStyles = css({
132
- height: 100,
133
- });
225
+ const boldMixin = { fontWeight: token('font.weight.bold') };
134
226
 
135
- const warningStyles = css({
136
- color: token('color.text.warning'),
137
- backgroundColor: token('color.background.warning'),
227
+ const styles = css({
228
+ '&::before': [boldMixin, { color: token('color.text.danger') }],
138
229
  });
230
+ ```
139
231
 
140
- const Component = ({ isWarning, width }: { isWarning: boolean; width: number }) => {
141
- return <div style={{ width }} css={[baseStyles, isWarning && warningStyles]} />;
142
- };
232
+ #### Correct
233
+
234
+ Use a single object with inlined styles.
235
+
236
+ ```tsx
237
+ import { css } from '@compiled/react';
238
+ import { token } from '@atlaskit/tokens';
239
+
240
+ const styles = css({
241
+ '&::before': {
242
+ fontWeight: token('font.weight.bold'),
243
+ color: token('color.text.danger'),
244
+ },
245
+ });
143
246
  ```
144
247
 
145
248
  ## Options
@@ -198,9 +301,9 @@ Default imports are not currently supported.
198
301
  // ...
199
302
  ```
200
303
 
201
- ### `importSources : string[]`
304
+ ### `importSources: string[]`
202
305
 
203
- By default, this rule will check `css` usages from:
306
+ By default, this rule will check styles using:
204
307
 
205
308
  - `@atlaskit/css`
206
309
  - `@atlaskit/primitives`
@@ -210,5 +313,4 @@ By default, this rule will check `css` usages from:
210
313
  - `@emotion/styled`
211
314
  - `styled-components`
212
315
 
213
- To change this list of libraries, you can define a custom set of `importSources`, which accepts an
214
- array of package names (strings). This will override the built-in allow-list.
316
+ Override this list with the `importSources` option, which accepts an array of package names.