📚 General documentation upgrades

Author: danieldelcore

website/docs/authoring.mdx

@@ -60,12 +60,8 @@ Example:
 import { hasImportDeclaration } from '@codeshift/utils';
 import updateBorderWidth from './motions/update-border-width';
 
-export default function transformer(
-  fileInfo: FileInfo,
-  { jscodeshift: j }: API,
-  options: Options,
-) {
-  const source = j(fileInfo.source);
+export default function transformer(file, { jscodeshift: j }, options) {
+  const source = j(file.source);
 
   if (hasImportDeclaration(j, source, '@atlaskit/avatar')) {
     // Checks if the file needs to be modified
@@ -74,13 +70,13 @@ export default function transformer(
     return source.toSource(options.printOptions || { quote: 'single' }); // Writes modified AST to file
   }
 
-  return fileInfo.source; // Writes original untouched file
+  return file.source; // Writes original untouched file
 }
 ```
 
 ## Motions
 
-A motion is what we call specific actions performed within a codemod. For example, `updateBorderWidth` or `removeDeprecatedProps`.
+A motion (aka migration) is what we call specific actions performed within a codemod. For example, `updateBorderWidth` or `removeDeprecatedProps`.
 They can be simply thought of a functions that are responsible for a single action within a codemod. This is not required but can help to isolate more complicated parts of your codemod into a single place.
 
 Example:

website/docs/ecosystem.mdx

@@ -32,6 +32,7 @@ The ecosystem is full of amazing resources and examples, please check them out.
 - [Getting Started with Codemods](https://www.sitepoint.com/getting-started-with-codemods/)
 - [Codemods: Effective, Automated Refactoring](https://www.sitepen.com/blog/codemods-effective-automated-refactoring)
 - [Creating a custom transform for jscodeshift](https://skovy.dev/jscodeshift-custom-transform/)
+- [Building AST nodes from source code](https://dev.to/rajasegar/building-ast-nodes-from-source-code-3p49)
 
 ## Misc
 

website/docs/guides/your-first-codemod.mdx

@@ -132,8 +132,8 @@ export default function transform(file, { jscodeshift: j }, options) {
   const source = j(file.source);
 
   source
-    .find(j.JSXIdentifier) // (1) Find all JSX props
-    .filter(path => path.node.name === 'isDisabled') // (2) Filter by name `isDisabled`
+    .find(j.JSXAttribute) // (1) Find all JSX props
+    .filter(path => path.node.name.name === 'isDisabled') // (2) Filter by name `isDisabled`
     .remove(); // (3) We remove any `isDisabled` prop from the AST
 
   return source.toSource(options.printOptions);
@@ -168,8 +168,8 @@ export default function transform(file, { jscodeshift: j }, options) {
   source
 +   .find(j.JSXElement)
 +   .filter(path => path.value.openingElement.name.name === 'Button')
-    .find(j.JSXIdentifier) // (1) Find all JSX props
-    .filter(path => path.node.name === 'isDisabled') // (2) Filter by name `isDisabled`
+    .find(j.JSXAttribute) // (1) Find all JSX props
+    .filter(path => path.node.name.name === 'isDisabled') // (2) Filter by name `isDisabled`
     .remove(); // (3) We remove any `isDisabled` prop from the AST
 
   return source.toSource(options.printOptions);
@@ -217,8 +217,8 @@ To avoid formatting issues and to speed up running transforms across large codeb
 ```ts
 export default function transform(file, { jscodeshift: j }, options) {
   const hasIsDisabledProp = !!source
-    .find(j.JSXIdentifier)
-    .filter(path.node.name === 'isDisabled')
+    .find(j.JSXAttribute)
+    .filter(path.node.name.name === 'isDisabled')
     .length
 
   if (!hasIsDisabledProp) {

website/docs/guiding-principles.mdx

@@ -6,7 +6,7 @@ slug: /guiding-principles
 
 There are several guiding principles we follow in this project.
 
-## Target a package & version
+## Codemod should target a version of package
 
 - APIs are always changing
 - Codemods written at a specific point of time aren't always going to work into the future
@@ -18,6 +18,8 @@ This gives us a lot of benefits,
 2. Codemods can be 'playable in a sequence', for example migrating from an older version of `@atlaskit/button` to the latest is possible for example `v14 -> v15 -> v16`.
 3. TODO`
 
+## Codemods should be playable in sequence
+
 ## Everyone should ship codemods
 
 Codemods aren't complicated, anyone who has writtin anything in jQuery should be able to write a codemod with relative ease.

website/docs/recipes/react.mdx

@@ -14,14 +14,33 @@ slug: /react
 export default function transformer(file, { jscodeshift: j }, options) {
   const source = j(file.source);
 
+  source
+    .find(j.JSXElement)
+    // Find all components called button
+    .filter(path => path.value.openingElement.name.name === 'button')
+    .forEach(element => {
+      const newComponent = j.jsxElement(
+        j.jsxOpeningElement(element.node.openingElement.name, [
+          ...element.node.openingElement.attributes,
+          // build and insert our new prop
+          j.jsxAttribute(j.jsxIdentifier('disabled'), j.stringLiteral('true')),
+        ]),
+        element.node.closingElement,
+        element.node.children,
+      );
+
+      // Replace our original component with our modified one
+      j(element).replaceWith(newComponent);
+    });
+
   return source.toSource();
 }
 ```
 
 **Input:**
 
 ```jsx
-import React, { useEffect } from 'react';
+import React from 'react';
 
 const Button = props => {
   return <button className="button">Submit</button>;
@@ -31,11 +50,11 @@ const Button = props => {
 **Output:**
 
 ```diff
-import React, { useEffect } from 'react';
+import React from 'react';
 
 const Button = props => {
 -  return <button className="button">Submit</button>;
-+  return <button className="button" onClick={() => console.log('Hello, World!')}>Submit</button>;
++  return <button className="button" disabled="true">Submit</button>;
 };
 ```
 
@@ -47,28 +66,39 @@ const Button = props => {
 export default function transformer(file, { jscodeshift: j }, options) {
   const source = j(file.source);
 
+  source
+    .find(j.JSXElement)
+    .filter(path => path.value.openingElement.name.name === 'button') // Find all button jsx elements
+    .find(j.JSXAttribute) // Find all attributes (props) on the button
+    .filter(path => path.node.name.name === 'onClick') // Filter to only props called onClick
+    .remove(); // Remove everything that matched
+
   return source.toSource();
 }
 ```
 
 **Input:**
 
 ```jsx
-import React, { useEffect } from 'react';
+import React from 'react';
 
 const Button = props => {
-  return <button className="button">Submit</button>;
+  return (
+    <button className="button" onClick={() => console.log('Hello, World!')}>
+      Submit
+    </button>
+  );
 };
 ```
 
 **Output:**
 
 ```diff
-import React, { useEffect } from 'react';
+import React from 'react';
 
 const Button = props => {
--  return <button className="button">Submit</button>;
-+  return <button className="button" onClick={() => console.log('Hello, World!')}>Submit</button>;
+-  return <button className="button" onClick={() => console.log('Hello, World!')}>Submit</button>;
++  return <button className="button">Submit</button>;
 };
 ```
 
@@ -87,7 +117,7 @@ export default function transformer(file, { jscodeshift: j }, options) {
 **Input:**
 
 ```jsx
-import React, { useEffect } from 'react';
+import React from 'react';
 
 const Button = props => {
   return <button className="button">Submit</button>;
@@ -97,7 +127,7 @@ const Button = props => {
 **Output:**
 
 ```diff
-import React, { useEffect } from 'react';
+import React from 'react';
 
 const Button = props => {
 -  return <button className="button">Submit</button>;
@@ -132,28 +162,69 @@ export default function transformer(file, { jscodeshift: j }, options) {
 
 ### Wrapping components
 
+Wrapping react components with react components is a fairly common opperation.
+
+Simply follow this fairly simple set of steps:
+
+1. Find the component you want to wrap
+2. Create a new component and pass the component to be wrapped in as a child node
+3. Replace the original component with a wrapped version of itself
+
 **Transform:**
 
 ```javascript
 export default function transformer(file, { jscodeshift: j }, options) {
   const source = j(file.source);
 
+  // Find all components named "Avatar"
+  source.findJSXElements('Avatar').forEach(element => {
+    /**
+     * Create a new JSXElement called "Tooltip" and use the original Avatar component as children
+     */
+    const wrappedAvatar = j.jsxElement(
+      j.jsxOpeningElement(j.jsxIdentifier('Tooltip'), [
+        // Create a prop on the tooltip so it works as expected
+        j.jsxAttribute(
+          j.jsxIdentifier('content'),
+          j.stringLiteral('Hello, there!'),
+        ),
+      ]),
+      j.jsxClosingElement(j.jsxIdentifier('Tooltip')),
+      [element.value], // Pass in the original component as children
+    );
+
+    j(element).replaceWith(wrappedAvatar);
+  });
+
   return source.toSource();
 }
 ```
 
 **Input:**
 
 ```jsx
+import { Avatar, Tooltip } from 'component-lib';
+
+const App = () => {
+  return <Avatar name="foo" />;
+};
 ```
 
 **Output:**
 
 ```diff
-
+import {Avatar, Tooltip } from 'component-lib';
+
+const App = () => {
+  return (
++    <Tooltip content="foo">
+      <Avatar name="foo" />
++    </Tooltip>
+  );
+}
 ```
 
-### Render props
+### Inserting children nodes
 
 **Transform:**
 
@@ -176,25 +247,90 @@ export default function transformer(file, { jscodeshift: j }, options) {
 
 ```
 
-### Inserting children nodes
+### Render props
+
+Moving between different types of React composition strategies, like for example, from component props to [render props](https://reactjs.org/docs/render-props.html#using-props-other-than-render) is could be something you want to do between major versions.
+This might seem difficult on the surface, but think about it like every other codemod. First we need to find the component, replace it with a modified copy of itself and finally insert a function as children.
 
 **Transform:**
 
 ```javascript
+import { getJSXAttributesByName } from '@codeshift/utils';
+
 export default function transformer(file, { jscodeshift: j }, options) {
   const source = j(file.source);
 
+  source.findJSXElements('Avatar').forEach(element => {
+    // Find props all JSXAttributes with a prop called "component"
+    // (Using the getJSXAttributeByName util here for simplicity)
+    const componentProp = getJSXAttributesByName(j, element, 'component').get();
+    // Grabs the name of the component passed into the "component" prop
+    const componentName = j(componentProp)
+      .find(j.JSXExpressionContainer)
+      .find(j.Expression)
+      .get().value.name;
+
+    // Remove it since it's no longer required on the wrapping component
+    j(componentProp).remove();
+
+    // Create a new child component based on the component prop and spread props onto it
+    const customComponent = j.jsxElement(
+      j.jsxOpeningElement(
+        j.jsxIdentifier(componentName),
+        [j.jsxSpreadAttribute(j.identifier('props'))],
+        true,
+      ),
+    );
+
+    /**
+     * Here's where it gets interesting.
+     * We create a render prop function and pass in `customComponent` as the return value
+     */
+    const childrenExpression = j.jsxExpressionContainer(
+      j.arrowFunctionExpression([j.identifier('props')], customComponent),
+    );
+
+    /**
+     * Then finally, we replace our original component with the following.
+     * Taking properties from the original component and combining them with our new render prop function
+     */
+    j(element).replaceWith(
+      j.jsxElement(
+        j.jsxOpeningElement(
+          element.value.openingElement.name,
+          element.value.openingElement.attributes,
+          false,
+        ),
+        j.jsxClosingElement(element.value.openingElement.name),
+        [childrenExpression],
+      ),
+    );
+  });
+
   return source.toSource();
 }
 ```
 
 **Input:**
 
 ```jsx
+import Avatar from '@component-lib/avatar';
+
+const App = () => {
+  return <Avatar name="Dan" component={CustomAvatar} />;
+};
 ```
 
 **Output:**
 
 ```diff
 
+import Avatar from '@component-lib/avatar';
+
+const App = () => {
+  return (
+-    <Avatar name="Dan" component={CustomAvatar} />
++    <Avatar name="Dan">{props => <CustomAvatar {...props} />}</Avatar>
++  );
+}
 ```