docs(linter/react): improve docs for jsx-curly-brace-presence

[connorshea]

For some reason, this rule was never updated to use the standard documentation format. The fields on the config struct were also not updated with doc comments, and so had no explanation. Now they do.

Generated docs:

### What it does

Disallow unnecessary JSX expressions when literals alone are
sufficient or enforce JSX expressions on literals in JSX children or
attributes.

This rule allows you to enforce curly braces or disallow unnecessary
curly braces in JSX props and/or children.

For situations where JSX expressions are unnecessary, please refer to
[the React doc](https://react.dev/learn/writing-markup-with-jsx)
and [this page about JSX
gotchas](https://github.com/facebook/react/blob/v15.4.0-rc.3/docs/docs/02.3-jsx-gotchas.md#html-entities).

### Why is this bad?

Using different styles for your JSX code can make it harder to read and
less consistent.

Code consistency improves readability. By enforcing or disallowing
curly braces in JSX props and/or children, this rule helps maintain
consistent patterns across your application.

### Rule Details

By default, this rule will check for and warn about unnecessary curly
braces in both JSX props and children. For the sake of backwards
compatibility, prop values that are JSX elements are not considered by
default.

You can pass in options to enforce the presence of curly braces on JSX
props, children, JSX prop values that are JSX elements, or any
combination of the three. The same options are available for not
allowing unnecessary curly braces as well as ignoring the check.

**Note**: it is _highly recommended_ that you configure this rule with
an object, and that you set "propElementValues" to "always". The ability
to omit curly braces around prop values that are JSX elements is
obscure, and intentionally undocumented, and should not be relied upon.

#### Example Configurations

```jsonc
{
  "rules": {
    "react/jsx-curly-brace-presence": ["error", { "props": <string>, "children": <string>, "propElementValues": <string> }]
  }
}
```

or alternatively

```jsonc
{
  "rules": {
    "react/jsx-curly-brace-presence": ["error", "always"], // or "never" or "ignore"
  },
}
```

### Fix Details

If passed in the option to fix, this is how a style violation will get fixed

- `always`: wrap a JSX attribute in curly braces/JSX expression and/or a JSX child the same way but also with double quotes
- `never`: get rid of curly braces from a JSX attribute and/or a JSX child

- All fixing operations use double quotes.

### Examples

Examples of **incorrect** code for this rule, when configured with `{ props: "always", children: "always" }`:

```jsx
<App>Hello world</App>;
<App prop="Hello world">{"Hello world"}</App>;
```

They can be fixed to:

```jsx
<App>{"Hello world"}</App>;
<App prop={"Hello world"}>{"Hello world"}</App>;
```

Examples of **incorrect** code for this rule, when configured with `{ props: "never", children: "never" }`:

```jsx
<App>{"Hello world"}</App>;
<App prop={"Hello world"} attr={"foo"} />;
```

They can be fixed to:

```jsx
<App>Hello world</App>;
<App prop="Hello world" attr="foo" />;
```

Examples of **incorrect** code for this rule, when configured with `{ props: "always", children: "always", "propElementValues": "always" }`:

```jsx
<App prop=<div /> />
```

They can be fixed to:

```jsx
<App prop={<div />} />
```

Examples of **incorrect** code for this rule, when configured with `{ props: "never", children: "never", "propElementValues": "never" }`:

```jsx
<App prop={<div />} />
```

They can be fixed to:

```jsx
<App prop=<div /> />
```

Examples of **incorrect** code for this rule, when configured with `"always"`:

```jsx
<App>Hello world</App>;
<App prop="Hello world" attr="foo">
  Hello world
</App>;
```

They can be fixed to:

```jsx
<App>{"Hello world"}</App>;
<App prop={"Hello world"} attr={"foo"}>
  {"Hello world"}
</App>;
```

Examples of **incorrect** code for this rule, when configured with `"never"`:

```jsx
<App prop={"foo"} attr={"bar"}>
  {"Hello world"}
</App>
```

It can fixed to:

```jsx
<App prop="foo" attr="bar">
  Hello world
</App>
```

### Edge cases

The fix also deals with template literals, strings with quotes, and
strings with escapes characters.

- If the rule is set to get rid of unnecessary curly braces and the
  template literal inside a JSX expression has no expression, it will
  throw a warning and be fixed with double quotes. For example:

```jsx
<App prop={`Hello world`}>{`Hello world`}</App>
```

will be warned and fixed to:

```jsx
<App prop="Hello world">Hello world</App>
```

- If the rule is set to enforce curly braces and the strings have
  quotes, it will be fixed with double quotes for JSX children and the
  normal way for JSX attributes. Also, double quotes will be escaped in
  the fix.

For example:

```jsx
<App prop='Hello "foo" world'>Hello 'foo' "bar" world</App>
```

will warned and fixed to:

```jsx
<App prop={'Hello "foo" world'}>{"Hello 'foo' \"bar\" world"}</App>
```

- If the rule is set to get rid of unnecessary curly braces(JSX
  expression) and there are characters that need to be escaped in its JSX
  form, such as quote characters, [forbidden JSX text
  characters](https://facebook.github.io/jsx/), escaped characters and
  anything that looks like HTML entity names, the code will not be warned
  because the fix may make the code less readable.

Examples of **correct** code for this rule, even when configured with `"never"`:

```jsx
<Color text={"\u00a0"} />
<App>{"Hello \u00b7 world"}</App>;
<style type="text/css">{'.main { margin-top: 0; }'}</style>;
/**
 * there's no way to inject a whitespace into jsx without a container so this
 * will always be allowed.
 */
<App>{' '}</App>
<App>{'     '}</App>
<App>{/* comment */ <Bpp />}</App> // the comment makes the container necessary
```

### When Not To Use It

You should turn this rule off if you are not concerned about maintaining
consistency regarding the use of curly braces in JSX props and/or
children as well as the use of unnecessary JSX expressions.

## Configuration

This rule accepts a configuration object with the following properties:

### children

type: `"always" | "never" | "ignore"`

default: `"never"`

Whether to enforce or disallow curly braces for child content of a JSX element.

- `never` will disallow unnecessary curly braces, e.g. this will be preferred: `<Foo>I love oxlint</Foo>`
- `always` will force the usage of curly braces like this, in all cases: `<Foo>{'I love oxlint'}</Foo>`
- `ignore` will allow either style for child content.

### propElementValues

type: `"always" | "never" | "ignore"`

default: `"ignore"`

When set to `ignore` or `never`, this JSX code is allowed (or enforced):
`<App prop=<div /> />;`

When set to `always`, the curly braces are required for prop values that are
JSX elements: `<App prop={<div />} />;`

**Note**: it is _highly_ recommended that you set `propElementValues` to `always`.
The ability to omit curly braces around prop values that are JSX elements is obscure, and
intentionally undocumented, and should not be relied upon.

### props

type: `"always" | "never" | "ignore"`

default: `"never"`

Whether to enforce or disallow curly braces for props on JSX elements.

- `never` will disallow unnecessary curly braces, e.g. this will be preferred: `<Foo foo="bar" />`
- `always` will force the usage of curly braces like this, in all cases: `<Foo foo={'bar'} />`
- `ignore` will allow either style for prop values.

[Copilot]

Pull request overview

This PR improves the documentation for the react/jsx-curly-brace-presence linter rule by migrating it to the standard documentation format and adding comprehensive field documentation.

Key Changes

• Added detailed doc comments to the JsxCurlyBracePresence configuration struct fields (props, children, prop_element_values) explaining their behavior and valid values
• Updated the rule documentation to follow the standard format with clear sections (What it does, Why is this bad, Rule Details, Examples, etc.)
• Updated the React documentation link from the deprecated URL to the current react.dev domain
• Normalized whitespace in test cases (replaced tabs with spaces)

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
crates/oxc_linter/src/rules/react/jsx_curly_brace_presence.rs	Added comprehensive doc comments to config struct fields; standardized rule documentation format with improved sections and examples; updated React doc link; normalized test case whitespace
crates/oxc_linter/src/snapshots/react_jsx_curly_brace_presence.snap	Updated snapshot to reflect column number changes resulting from test input whitespace normalization

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codspeed-hq]

CodSpeed Performance Report

Merging #17579 will not alter performance

_{Comparing improve-curly-presence-rule (209ab7e) with main (bc7aae7)¹}

Summary

✅ 4 untouched
⏩ 41 skipped²

Footnotes

1. No successful run was found on main (7005873) during the generation of this report, so bc7aae7 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

2. 41 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[camc314]

Merge activity

• Jan 2, 12:42 PM UTC: The merge label '0-merge' was detected. This PR will be added to the Graphite merge queue once it meets the requirements.
• Jan 2, 12:44 PM UTC: camc314 added this pull request to the Graphite merge queue.
• Jan 2, 12:49 PM UTC: Merged by the Graphite merge queue.