[Suggestion]: Documentation does not make mention of the difference between `props.children` and directly rendering children as it relates to rendering behaviour.

Summary

Here I have an example of two ways we can create functionally identical components.

export function ChildrenStyleOne() {
    const [value, setValue] = useState('');
    return <div id="foo">
        <SomeThing />
    </div>
}

export function ChildrenStyleTwo(props: React.PropsWithChildren) {
    const [value, setValue] = useState('');
    return <div id="bar">
        {props.children}
    </div>
}

However, there is an important different in how these components behave as far as rendering behaviour goes.

In the first style, every render of ChildrenStyleOne (eg. say because state is changing), will also cause a render of SomeThing.

In the second style, additional renders of ChildrenStyleTwo will not cause renders of the {props.children}.

This is a useful distinction to be aware of - using the props.children/slots approach is a simple mechanism to avoid full branch renders.

I've observed people commonly believing that 'every time a context provider's state changes, everything below it will render' - and I believe this misconception arrises from not being aware of this difference in rendering behaviour.

Page

https://react.dev/learn/understanding-your-ui-as-a-tree

Details

The docs above actually serve to reinforce the conflation of directly rendered children,and props.children.

For example the example code includes this node:

      <InspirationGenerator>
        <Copyright year={2004} />
      </InspirationGenerator>

and the render tree diagram looks like this:

We can see that FancyText here is a directly rendered child, while Copyright is a props.children child.

The render tree described in the docs makes no distinction between the two.

I imagine this is likely a deliberate decision on the the part of the React maintainers - simplifying the conceptual model. If that's the case, is there a blog post or something that talks about what the strategy is?

The docs perhaps could do with a deep dive note that makes mention of this distinction or links to a more comprehensive optimisation section elsewhere.

從「Understanding your UI as a tree」頁面開始，檢視 InspirationGenerator 範例，特別是直接渲染的 FancyText 和基於 props.children 的 Copyright 子項。判斷文件是否應該解釋它們在渲染上的差異，或連結到更深入的最佳化資源。當頁面準確處理這項差異，或清楚解釋預期的簡化模型時，即視為完成。