Docs: Add note regarding PascalCase function components in naming-convention rule

[sharky98]

Before You File a Documentation Request Please Confirm You Have Done The Following...

• I have looked for existing open or closed documentation requests that match my proposal.
• I have read the FAQ and my problem is not listed.

Suggested Changes

Background

I was looking to use naming-convention for my React and non-React packages. It is known that React convention is to use PascalCase component, while the rest is camelCase. Turns out, it is not possible to define a rule to cover this case, since there is nothing to distinguish a React component function from a non-component function (neither function arguments or return type are fool proof).

It has been discussed in #2607 and #2692.

Requested change

Since the PascalCase pattern for component is quite common, I would like to see a note regarding this in the documentation of the naming convention rule. The best place could be in the first example, which shows how to enforce function to camelCase.

### Enforce that all variables, functions and properties follow are camelCase

```json
{
  "@typescript-eslint/naming-convention": [
    "error",
    { "selector": "variableLike", "format": ["camelCase"] }
  ]
}
```

:::caution
Using this rule will trigger errors on functional components using `PascalCase` convention, as used in React. See [issue #2607](https://github.com/typescript-eslint/typescript-eslint/issues/2607) for more information and [eslint-plugin-react/jsx-pascal-case rule](https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-pascal-case.md) rule.
:::

Affected URL(s)

https://typescript-eslint.io/rules/naming-convention/

[bradzacher]

since there is nothing to distinguish a React component function from a non-component function (neither function arguments or return type are fool proof).

Yeah it's a major problem for static analysis of function components. You should see the crazy logic eslint-plugin-react has to try and detect them!

It's also a sticking point for various research exploration projects within the react team.

For a react codebase I'd recommend specifying functions separately to specifically allow both camelCase AND PascalCase just for them.

But also some codebases use arrow functions for components... so you'd also need to allow both styles for variables as well!

[sharky98]

For a react codebase I'd recommend specifying functions separately to specifically allow both camelCase AND PascalCase just for them.

This is why I would suggest adding the caution note in that first example. I think React functional components are common enough (or will be sooner or later), that a caution admonition in the docs would help user that may be less knowledgeable in the inner working of all those terms.

Maybe could be worded a bit differently.

:::caution
Using this rule will trigger errors on functional components using `PascalCase` convention, as used in React. You may want to use `"format": ["camelCase", "PascalCase"]` to allow both convention.

See [issue #2607](https://github.com/typescript-eslint/typescript-eslint/issues/2607) for more information and [eslint-plugin-react/jsx-pascal-case rule](https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-pascal-case.md) rule.
:::

But also some codebases use arrow functions for components... so you'd also need to allow both styles for variables as well!

I am guilty of that! 🤣 However, I did limit the PascalCase only on variables that are types of function ({ selector: "variable", types: ["function"], modifiers: ["const"], format: ["PascalCase", "camelCase"] }). So far so good in my own codebase.

[JoshuaKGoldberg]

Accepting a PR to add an explicit note about UI library function components. A couple thoughts:

• It's function components, not functional. This is nitpicky 😄 but you can have function components with non-functional side effects because of useEffect & co.
• It's good to mention React for searchability, but as with this issue's description, it should be clear that it works with other UI libraries. I'd suggest naming at least Solid and Preact.