Update docs with covered cases (#8)

* update docs

* add missing test cases

* add note about prop forwarding

Author: kanzelm3

README.md

@@ -1,26 +1,24 @@
 # @fullstory/eslint-plugin-annotate-react
 
-An ESLint plugin for adding 'data-attribute' to React components. The purpose of this plugin is to automatically
-make css selectors. Here is an example
+An ESLint plugin for adding 'data-attribute' to React components. The purpose of this plugin is to automatically make css selectors. Here is an example:
 
 ```
-const myDiv = () => (
-  <div/>
-); `;
+const MyComponent = () => (
+  <div />
+);
 ```
 
-This plugin will autofix and add data-component to the div
+This plugin will autofix and add the `data-component` prop to the div:
 
 ```
-const myDiv = () => (
-  <div data-component="temp"/>
-); `;
+const MyComponent = () => (
+  <div data-component="MyComponent" />
+);
 ```
 
-This plugin is intended to not be too opinionated. In general the approach is to suggest to the developer to add 'data-attribute' when there is an obvious approach, but in questionable cases, the plugin will tend towards being quiet.
+This plugin is intended to not be too opinionated. In general the approach is to suggest to the developer to add 'data-component' when there is an obvious approach, but in questionable cases, the plugin will tend towards being quiet. Click to learn more about the [covered cases](./docs/covered-cases.md).
 
-- When there is a [fragment](https://reactjs.org/docs/fragments.html) this plugin won't add data-attribute
-- Where there are multiple return elements this plugin won't add data-attribute
+_Note: This plugin cannot guarantee that the `data-component` prop will actually make it to the DOM node if the top level element is another React component. For it to work effectively, make sure you are properly [forwarding props with the JSX spread syntax](https://react.dev/learn/passing-props-to-a-component#forwarding-props-with-the-jsx-spread-syntax)._
 
 ## Installation
 

docs/covered-cases.md

@@ -0,0 +1,122 @@
+# Covered Cases
+
+This plugin is intended to not be too opinionated. In general the approach is to suggest to the developer to add 'data-component' when there is an obvious approach, but in questionable cases, the plugin will them and stay quiet.
+
+### Covered
+
+#### Basic function components
+
+```tsx
+const MyComponent = () => <div />;
+```
+
+> MyComponent is missing the data-component attribute for the top-level element.
+
+```tsx
+function MyComponent() {
+  return <div />;
+}
+```
+
+> MyComponent is missing the data-component attribute for the top-level element.
+
+```tsx
+export default function MyComponent() {
+  return <div />;
+}
+```
+
+> MyComponent is missing the data-component attribute for the top-level element.
+
+#### Typescript generic components
+
+```tsx
+const yAxis = (xScale, xTicks) => (
+  <BottomAxis<Date> width={1} height={1} xScale={xScale} xTicks={xTicks}>
+    123
+  </BottomAxis>
+);
+```
+
+> yAxis is missing the data-component attribute for the top-level element.
+
+#### Multiple components in a file
+
+```tsx
+const Component1 = () => <div />;
+const Component2 = () => <span />;
+```
+
+> Component1 is missing the data-component attribute for the top-level element.
+> Component2 is missing the data-component attribute for the top-level element.
+
+#### Class-based components
+
+```tsx
+class Car extends React.Component {
+  render() {
+    return <h2>Hi, I am a Car!</h2>;
+  }
+}
+```
+
+> Car is missing the data-component attribute for the top-level element.
+
+#### Components wrapped with forwardRef
+
+```tsx
+export const Navigate = React.forwardRef<HTMLAnchorElement, NavigateProps>(
+  (props, ref) => <Link ref={ref} {...props} />,
+);
+```
+
+> Navigate is missing the data-component attribute for the top-level element.
+
+### Ignored
+
+#### Components with Provider as the top-level element
+
+```tsx
+export const App = () => <AppContext.Provider value={ctx} />;
+```
+
+> All good!
+
+_Note: This just uses a simple `/Provider$/` regex test_
+
+#### Components with a [React Fragment](https://reactjs.org/docs/fragments.html) as the top-level element
+
+```tsx
+const FragmentComponent = () => (
+  <>
+    <span />
+    <div />
+    <a />
+  </>
+);
+```
+
+> All good!
+
+#### Components that conditionally return different values
+
+```tsx
+const ConditionalComponent = () => {
+  const isActive = useIsActive();
+  return isActive ? <div /> : null;
+};
+```
+
+> All good!
+
+```tsx
+const ConditionalComponent = () => {
+  const isActive = useIsActive();
+  if (isActive) {
+    return <ActiveComponent />;
+  }
+  return <div />;
+};
+```
+
+> All good!

test.js

@@ -14,6 +14,14 @@ const singleComponentError = `const temp = () => {
   return <Icon name="metric" size={24} />;
 };`;
 
+const defaultSingleComponent = `export default function temp () {
+  return <Icon data-component="temp" name="metric" size={24} />;
+};`;
+
+const defaultSingleComponentError = `export default function temp () {
+  return <Icon name="metric" size={24} />;
+};`;
+
 const genericTest = `
 const yAxis = (xScale, xTicks) => (
   <BottomAxis<Date> data-component="yAxis" width={1} height={1} xScale={xScale} xTicks={xTicks}>
@@ -249,6 +257,23 @@ const providerWithDot = /* tsx */ `
 export const Test = () => <Test.Provider />;
 `;
 
+const ternary = /* tsx */ `
+export const TernaryComponent = () => {
+  const active = useIsActive();
+  return active ? <ActiveComponent /> : null;
+};
+`;
+
+const ifBlock = /* tsx */ `
+export const IfBlockComponent = () => {
+  const active = useIsActive();
+  if (active) {
+    return <ActiveComponent />;
+  }
+  return <div />;
+};
+`;
+
 const tests = {
   'data-component': {
     // Require the actual rule definition
@@ -278,6 +303,9 @@ const tests = {
         {
           code: singleComponent,
         },
+        {
+          code: defaultSingleComponent,
+        },
         {
           code: genericTest,
         },
@@ -312,6 +340,12 @@ const tests = {
         {
           code: providerWithDot,
         },
+        {
+          code: ternary,
+        },
+        {
+          code: ifBlock,
+        },
       ],
       invalid: [
         {
@@ -321,6 +355,13 @@ const tests = {
             'temp is missing the data-component attribute for the top-level element.',
           ],
         },
+        {
+          code: defaultSingleComponentError,
+          output: defaultSingleComponent,
+          errors: [
+            'temp is missing the data-component attribute for the top-level element.',
+          ],
+        },
         {
           code: classComponentError,
           output: classComponent,