eslint-plugin-primer-react 8.0.0 → 8.1.0-rc.ce584c0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # eslint-plugin-primer-react
 
+## 8.1.0
+
+### Minor Changes
+
+- [#382](https://github.com/primer/eslint-plugin-primer-react/pull/382) [`93e4b76`](https://github.com/primer/eslint-plugin-primer-react/commit/93e4b76269bf816bfc24991180f73ef22266a6f5) Thanks [@jonrohan](https://github.com/jonrohan)! - Add rule `use-styled-react-import` to enforce importing components with sx prop from @primer/styled-react
+
 ## 8.0.0
 
 ### Major Changes

package/docs/rules/use-styled-react-import.md

@@ -0,0 +1,128 @@
+# use-styled-react-import
+
+💼 This rule is _disabled_ in the ✅ `recommended` config.
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
+Enforce importing components that use `sx` prop from `@primer/styled-react` instead of `@primer/react`, and vice versa.
+
+## Rule Details
+
+This rule detects when certain Primer React components are used with the `sx` prop and ensures they are imported from the temporary `@primer/styled-react` package instead of `@primer/react`. When the same components are used without the `sx` prop, it ensures they are imported from `@primer/react` instead of `@primer/styled-react`.
+
+When a component is used both with and without the `sx` prop in the same file, the rule will import the styled version with an alias (e.g., `StyledButton`) and update the JSX usage accordingly to avoid naming conflicts.
+
+It also moves certain types and utilities to the styled-react package.
+
+### Components that should be imported from `@primer/styled-react` when used with `sx`:
+
+- ActionList
+- ActionMenu
+- Box
+- Breadcrumbs
+- Button
+- Flash
+- FormControl
+- Heading
+- IconButton
+- Label
+- Link
+- LinkButton
+- PageLayout
+- Text
+- TextInput
+- Truncate
+- Octicon
+- Dialog
+
+### Types and utilities that should always be imported from `@primer/styled-react`:
+
+- `BoxProps` (type)
+- `SxProp` (type)
+- `BetterSystemStyleObject` (type)
+- `sx` (utility)
+
+## Examples
+
+### ❌ Incorrect
+
+```jsx
+import {Button, Link} from '@primer/react'
+
+const Component = () => <Button sx={{color: 'red'}}>Click me</Button>
+```
+
+```jsx
+import {Box} from '@primer/react'
+
+const Component = () => <Box sx={{padding: 2}}>Content</Box>
+```
+
+```jsx
+import {sx} from '@primer/react'
+```
+
+```jsx
+import {Button} from '@primer/styled-react'
+
+const Component = () => <Button>Click me</Button>
+```
+
+```jsx
+import {Button} from '@primer/react'
+
+const Component1 = () => <Button>Click me</Button>
+const Component2 = () => <Button sx={{color: 'red'}}>Styled me</Button>
+```
+
+### ✅ Correct
+
+```jsx
+import {Link} from '@primer/react'
+import {Button} from '@primer/styled-react'
+
+const Component = () => <Button sx={{color: 'red'}}>Click me</Button>
+```
+
+```jsx
+import {Box} from '@primer/styled-react'
+
+const Component = () => <Box sx={{padding: 2}}>Content</Box>
+```
+
+```jsx
+import {sx} from '@primer/styled-react'
+```
+
+```jsx
+// Components without sx prop can stay in @primer/react
+import {Button} from '@primer/react'
+
+const Component = () => <Button>Click me</Button>
+```
+
+```jsx
+// Components imported from styled-react but used without sx prop should be moved back
+import {Button} from '@primer/react'
+
+const Component = () => <Button>Click me</Button>
+```
+
+```jsx
+// When a component is used both ways, use an alias for the styled version
+import {Button} from '@primer/react'
+import {Button as StyledButton} from '@primer/styled-react'
+
+const Component1 = () => <Button>Click me</Button>
+const Component2 = () => <StyledButton sx={{color: 'red'}}>Styled me</StyledButton>
+```
+
+## Options
+
+This rule has no options.
+
+## When Not To Use It
+
+This rule is specifically for migrating components that use the `sx` prop to the temporary `@primer/styled-react` package. If you're not using the `sx` prop or not participating in this migration, you can disable this rule.