docs: update. (#16)

Author: knightedcodemonkey

.github/workflows/publish.yml

@@ -34,3 +34,4 @@ jobs:
         with:
           token: ${{ secrets.NPM_AUTH_TOKEN }}
           access: public
+          tag: ${{ contains(github.ref, '-') && 'next' || 'latest' }}

README.md

@@ -8,53 +8,88 @@ A codemod to add `displayName` to React function components.
 
 - Works with TypeScript or JavaScript source code.
 - Quickly fix [`react/display-name`](https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/display-name.md) lint errors.
+- Use `displayName` or a named function expression.
 - Pass a path to a file, or a string.
 
 ## Example
 
-```ts
-import { modify } from '@knighted/display-name'
+Given
 
-const codemod = await modify(`
-  import { memo } from 'react'
+```tsx
+import React, { memo } from 'react'
 
-  const Foo = () => {
-    return <div>foo</div>
-  }
+const Foo = memo(({ a }) => {
+  return <>{a}</>
+})
+const Bar = React.forwardRef((props, ref) => <p ref={ref}>bar</p>)
+const Baz = memo(
+  React.forwardRef((props, ref) => {
+    return <p ref={ref}>baz</p>
+  }),
+)
+```
 
-  const Bar = memo(function Bar(props) {
-    return <span>stuff</span>
-  })
+Then running `modify` on the source code (or `modifyFile` on the file path) results in
 
-  const Baz = memo(() => {
-    return <p>baz</p>
-  })
-`)
+```tsx
+import React, { memo } from 'react'
 
-console.log(codemod)
+const Foo = memo(({ a }) => {
+  return <>{a}</>
+})
+Foo.displayName = 'Foo'
+const Bar = React.forwardRef((props, ref) => <p ref={ref}>bar</p>)
+Bar.displayName = 'Bar'
+const Baz = memo(
+  React.forwardRef((props, ref) => {
+    return <p ref={ref}>baz</p>
+  }),
+)
+```
 
-/*
-import { memo } from 'react'
+If running the codemod against a codebase that has recently added `eslint-plugin-react` you can write a script.
 
-const Foo = () => {
-  return <div>foo</div>
-}
+```js
+import { globSync } from 'node:fs'
+import { writeFile } from 'node:fs/promises'
+import { modifyFile } from '@knighted/display-name'
 
-const Bar = memo(function Bar(props) {
-  return <span>bar</span>
-})
+const doCodeMod = async () => {
+  for (const file of globSync('**/*.tsx', {
+    exclude: ['**/node_modules/**', '**/dist/**', '**/build/**'],
+  })) {
+    await writeFile(file, await modifyFile(file))
+  }
+}
 
-const Baz = memo(() => {
-  return <p>baz</p>
-})
-Baz.displayName = 'Baz';
-*/
+await doCodeMod()
 ```
 
-You can also pass a filepath instead of a string:
+Then optionally run the results through a formatter like `prettier`.
+
+## Options
+
+There are some options, none are required. Most notably you can choose a `style` for adding the display name. The default is `displayName` which adds a displayName property to the function component, or you can choose `namedFuncExpr` to use a named function expression instead.
 
 ```ts
-import { modifyFile } from '@knighted/display-name'
+type Options = {
+  requirePascal?: boolean
+  insertSemicolon?: boolean
+  modifyNestedForwardRef?: boolean
+  style?: 'displayName' | 'namedFuncExpr'
+}
+```
 
-await modifyFile('/path/to/file.tsx')
+For example, using `namedFuncExpr`
+
+```tsx
+const Foo = memo(() => <>foo</>)
+```
+
+becomes
+
+```tsx
+const Foo = memo(function Foo() {
+  return <>foo</>
+})
 ```

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/display-name",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0",
   "description": "Codemod to add a React displayName to function components.",
   "type": "module",
   "exports": {

package.json

@@ -208,6 +208,11 @@ const modify = async (source: string, options: Options = defaultOptions) => {
                       const params = func.params.map(param =>
                         code.slice(param.start, param.end),
                       )
+                      /**
+                       * Inside a function expression, the body is always a block statement.
+                       * I think the types for oxc-parser can be improved.
+                       * @see https://github.com/oxc-project/oxc/pull/9128#issuecomment-2870220468
+                       */
                       const body = func.body
                         ? code.slice(func.body.start, func.body.end)
                         : '{}'

src/displayName.ts

@@ -482,6 +482,38 @@ describe('@knighted/displayName', () => {
         })
       `.replace(/\s+/g, ''),
     )
+
+    src = `
+      import React from 'react'
+      const Hello = React.memo(({ a }) => {
+        return <>{a}</>
+      })
+    `
+    code = await modify(src, { style: 'namedFuncExpr' })
+    assert.equal(
+      code.replace(/\s+/g, ''),
+      `
+        import React from 'react'
+        const Hello = React.memo(function Hello({ a }) {
+          return <>{a}</>
+        })
+      `.replace(/\s+/g, ''),
+    )
+
+    src = `
+      import {forwardRef} from 'react'
+      const Fr = forwardRef(({ a }) => <>{a}</>)
+    `
+    code = await modify(src, { style: 'namedFuncExpr' })
+    assert.equal(
+      code.replace(/\s+/g, ''),
+      `
+        import {forwardRef} from 'react'
+        const Fr = forwardRef(function Fr({ a }) {
+          return <>{a}</>
+        })
+      `.replace(/\s+/g, ''),
+    )
   })
 
   it('the style option works with namedFuncExpr', async t => {

test/displayName.ts

@@ -39,6 +39,9 @@ const FuncExprForwardRefReact = React.forwardRef<HTMLParagraphElement, Props>(
     return <p ref={ref}>{props.foo}</p>
   },
 )
+const Hello = React.memo(({ a }: { a: string }) => {
+  return <>{a}</>
+})
 
 // These already have a display name.
 const MemoDisplayName = memo((props: Props) => {