[wip] Add a few Rules of React docs

Author: poteto

src/content/reference/rules/components-must-be-idempotent.md

@@ -0,0 +1,34 @@
+---
+title: Components must be idempotent
+---
+
+<Intro>
+React components are assumed to always return the same output with respect to their props. This is known as [idempotency](https://stackoverflow.com/questions/1077412/what-is-an-idempotent-operation).
+</Intro>
+
+---
+
+Put simply, idempotence means that you [always get the same result everytime](learn/keeping-components-pure) you run that piece of code.
+
+```js
+function NewsFeed({ items }) {
+  const filteredItems = items.filter(item => item.isDisplayed === true);
+  return (
+    <ul>
+      {filteredItems.map(item => <li>{item.text}</li>}
+    </ul>
+  );
+}
+```
+
+This means that _all_ code that runs during render must also be idempotent in order for this rule to hold. For example, this line of code is not idempotent (and therefore, neither is the component) and breaks this rule:
+
+```js {2}
+function Clock() {
+  return <div>{new Date()}</div> // ❌ always returns a different result!
+}
+```
+
+`new Date()` is not idempotent as it always returns the current date and changes its result every time it's called. When you render the above component, the time displayed on the screen will stay stuck on the time that the component was rendered. Similarly, functions like `Math.random()` also aren't idempotent, because they return different results every time they're called, even when the inputs are the same.
+
+Try building a component that displays the time in real-time in our [challenge](learn/keeping-components-pure#challenges) to see if you follow this rule!

src/content/reference/rules/index.md

@@ -0,0 +1,38 @@
+---
+title: Rules of React
+---
+
+<Intro>
+JavaScript rendering libraries and frameworks like React have constraints or "rules" to make the programming model cohesive and easy to reason about, while also helping you prevent bugs in your code. The rules also have the added benefit of creating a safe space for React to optimise and run your code more efficiently. This page lists all the Rules of React.
+</Intro>
+
+---
+
+These constraints are known as the **Rules of React**. They are rules – and not just guidelines – in the sense that if they are broken, your app likely has bugs. Your code also becomes unidiomatic and harder to understand and reason about.
+
+We strongly recommend using Strict Mode alongside React's ESLint plugin to help your codebase follow the Rules of React. By following the Rules of React, you'll be able to find and address these bugs, as well as prepare your codebase to work out of the box with the upcoming compiler.
+
+<DeepDive>
+#### Why are rules necessary in React? {/*why-are-rules-necessary-in-react*/}
+
+You can think of React's constraints like the grammatical rules and patterns of languages: they constrain what we can do with words, so that we can correctly and efficiently communicate our thoughts. These rules have been used in the design of all of React's features over the years. React's Strict Mode enforces several of these rules at runtime in DEV mode, and with the release of React's upcoming compiler, more rules will now be statically checked to help you find more bugs as well as allow for correct optimisation of your code.
+
+The upcoming compiler automatically makes writing simple and intuitive React code run efficiently by default. It understands JavaScript semantics and relies on the Rules of React in order to correctly and precisely optimise your codebase.
+
+However, while the compiler can detect most cases of Rules of React breakages, because of the dynamic and flexible nature of JavaScript, it is not possible to exhaustively detect all edge cases. Future iterations of the compiler will continue to improve its static detection, but it's important to understand and follow the Rules of React so that your code continues to run correctly and efficiently even if it's not possible to statically detect.
+
+If the Rules of React are broken, at best the upcoming compiler will skip optimising the components that broke the rules; and at worst, if the breakage is not statically detectable the compiled code may break in unexpected ways.
+</DeepDive>
+
+---
+
+## Rules {/*rules*/}
+* [Side effects must run outside of render](/reference/rules/side-effects-must-run-outside-of-render): React can start and stop rendering components multiple times to create the best possible user experience.
+* [Components must be idempotent](/reference/rules/components-must-be-idempotent): React components are assumed to always return the same output with respect to their props.
+* [Props and State are immutable](/reference/rules/props-and-state-are-immutable): A component's props and state are immutable "snapshots" with respect to a single render.
+* [Never call component functions directly](/reference/rules/never-call-component-functions-directly): TODO React must orchestrate rendering
+* [Never pass around Hooks as regular values](/reference/rules/never-pass-around-hooks-as-regular-values): TODO
+* [Only call Hooks at the top level](/reference/rules/only-call-hooks-at-the-top-level): TODO
+* [Only call Hooks from React functions](/reference/rules/only-call-hooks-from-react-functions): TODO
+* [Values are immutable after being passed to JSX](/reference/rules/values-are-immutable-after-being-passed-to-jsx): TODO
+* [Return values and arguments to Hooks are immutable](/reference/rules/return-values-and-arguments-to-hooks-are-immutable): TODO

src/content/reference/rules/never-call-component-functions-directly.md

@@ -0,0 +1,7 @@
+---
+title: Never call component functions directly
+---
+
+<Intro>
+TODO
+</Intro>

src/content/reference/rules/never-pass-around-hooks-as-regular-values.md

@@ -0,0 +1,7 @@
+---
+title: Never pass around hooks as regular values
+---
+
+<Intro>
+TODO
+</Intro>

src/content/reference/rules/only-call-hooks-at-the-top-level.md

@@ -0,0 +1,7 @@
+---
+title: Only call Hooks at the top level
+---
+
+<Intro>
+TODO
+</Intro>

src/content/reference/rules/only-call-hooks-from-react-functions.md

@@ -0,0 +1,7 @@
+---
+title: Only call Hooks from React functions
+---
+
+<Intro>
+TODO
+</Intro>

src/content/reference/rules/props-and-state-are-immutable.md

@@ -0,0 +1,69 @@
+---
+title: Props and State are immutable
+---
+
+<Intro>
+A component's props and state are immutable [snapshots](learn/state-as-a-snapshot) with respect to a single render.
+</Intro>
+
+---
+
+You can think of the props and state values as snapshots that are updated after rendering. For this reason, you don't modify the props or state variables directly: instead you use the setter function provided to you to tell React that state needs to update the next time the component is rendered.
+
+## Props {/*props*/}
+When followed, this rule allows React to understand that values that flow from props aren't mutated when they're passed as arguments to functions. Mutating props may also indicate a bug in your app – changing values on the props object doesn't cause the component to update, leaving your users with an outdated UI.
+
+```js {2}
+function Post({ item }) {
+  item.url = new Url(item.url, base); // ❌ never mutate props directly
+  return <Link url={item.url}>{item.title}</Link>;
+}
+```
+
+```js {2}
+function Post({ item }) {
+  const url = new Url(item.url, base); // ✅ make a copy instead
+  return <Link url={url}>{item.title}</Link>;
+}
+```
+
+## State {/*state*/}
+`useState` returns an immutable tuple of the state variable and a setter to update that state.
+
+```js
+const [stateVariable, setter] = useState(0);
+```
+
+Rather than updating the state variable in-place, we need to update it using the setter function that is returned by `useState`. Changing values on the state variable doesn't cause the component to update, leaving your users with an outdated UI. Using the setter function informs React that the state has changed, and that we need to queue a re-render to update the UI.
+
+```js {5}
+function Counter() {
+  const [count, setCount] = useState(0);
+
+  function handleClick() {
+    count = count + 1; // ❌ never mutate state directly
+  }
+
+  return (
+    <button onClick={handleClick}>
+      You pressed me {count} times
+    </button>
+  );
+}
+```
+
+```js {5}
+function Counter() {
+  const [count, setCount] = useState(0);
+
+  function handleClick() {
+    setCount(count + 1); // ✅ use the setter function returned by useState
+  }
+
+  return (
+    <button onClick={handleClick}>
+      You pressed me {count} times
+    </button>
+  );
+}
+```

src/content/reference/rules/return-values-and-arguments-to-hooks-are-immutable.md

@@ -0,0 +1,7 @@
+---
+title: Return values and arguments to Hooks are immutable
+---
+
+<Intro>
+TODO
+</Intro>

src/content/reference/rules/side-effects-must-run-outside-of-render.md

@@ -0,0 +1,68 @@
+---
+title: Side effects must run outside of render
+---
+
+<Intro>
+Side effects should not run in render, as React can render components multiple times to create the best possible user experience.
+</Intro>
+
+---
+
+While render must be kept pure, side effects are necessary at some point in order for your app to do anything interesting, like showing something on the screen! The key point of this rule is that side effects should not run in render, as React can render components multiple times. In most cases, you'll use event handlers to handle side effects. For example, you might have an event handler that displays a confirmation dialog after the user clicks a button. Using an event handler explicitly tells React that this code doesn't need to run during render, keeping render pure. If you've exhausted all options – and only as a last resort – you can also handle side effects using `useEffect`.
+
+<DeepDive>
+#### Why does render need to be pure? {/*why-does-render-need-to-be-pure*/}
+UI libraries like React take care of when your code runs for you so that your application has great user experience. React is declarative: you tell React what to render in your component's logic, and React will figure out how best to display it to your user!
+
+When render is kept pure, React can understand how to prioritise which updates are most important for the user to see first. This is made possible because of render purity: since components don't have side effects in render, React can pause rendering components that aren't as important to update, and only come back to them later when it's needed.
+
+Concretely, this means that rendering logic can be run multiple times in a way that allows React to give your user a pleasant user experience. However, if your component has an untracked side effect – like modifying the value of a global variable during render – when React runs your rendering code again, your side effects will be triggered in a way that won't match what you want. This often leads to unexpected bugs that can degrade how your users experience your app.
+</DeepDive>
+
+For example, values that aren't created inside of a component shouldn't be mutated:
+
+```js
+let items = []; // created outside of the component
+function MyComponent({ seen }) {
+  items.push(seen); // ❌ mutated inside the component
+}
+```
+
+
+In general, mutation is not idiomatic in React. However, local mutation is absolutely fine:
+
+```js
+function FriendList({ friends }) {
+  let items = []; // ✅ locally created and mutated
+  for (let i = 0; i < friends.length; i++) {
+    let friend = friends[i];
+    items.push(
+      <Friend key={friend.id} friend={friend} />
+    );
+  }
+  return <section>{items}</section>;
+}
+```
+
+We created `items` while rendering and no other component "saw" it so we can mutate it as much as we like before handing it off as part of the render result. This component has no observable side effects, even though it mutates `items`. There is no need to contort your code to avoid local mutation.
+
+Similarly, lazy initialization is fine despite not being fully "pure":
+
+```js
+function ExpenseForm() {
+  // Fine if it doesn't affect other components:
+  SuperCalculator.initializeIfNotReady();
+
+  // Continue rendering...
+}
+```
+
+As long as calling a component multiple times is safe and doesn’t affect the rendering of other components, React doesn’t care if it’s 100% pure in the strict functional programming sense of the word.
+
+That said, side effects that are directly visible to the user are not allowed in the render logic of React components. In other words, merely calling a component function shouldn’t by itself produce a change on the screen.
+
+```js
+function ProductDetailPage({ product }) {
+  document.window.title = product.title; // ❌
+}
+```

src/content/reference/rules/values-are-immutable-after-being-passed-to-jsx.md

@@ -0,0 +1,7 @@
+---
+title: Values are immutable after being passed to JSX
+---
+
+<Intro>
+TODO
+</Intro>

src/sidebarReference.json

@@ -10,6 +10,48 @@
       "title": "Overview",
       "path": "/reference/react"
     },
+    {
+      "title": "Rules of React",
+      "path": "/reference/rules",
+      "routes": [
+        {
+          "title": "Side effects must run outside of render",
+          "path": "/reference/rules/side-effects-must-run-outside-of-render"
+        },
+        {
+          "title": "Components must be idempotent",
+          "path": "/reference/rules/components-must-be-idempotent"
+        },
+        {
+          "title": "Props and State are immutable",
+          "path": "/reference/rules/props-and-state-are-immutable"
+        },
+        {
+          "title": "Never call component functions directly",
+          "path": "/reference/rules/never-call-component-functions-directly"
+        },
+        {
+          "title": "Never pass around Hooks as regular values",
+          "path": "/reference/rules/never-pass-around-hooks-as-regular-values"
+        },
+        {
+          "title": "Only call Hooks at the top level",
+          "path": "/reference/rules/only-call-hooks-at-the-top-level"
+        },
+        {
+          "title": "Only call Hooks from React functions",
+          "path": "/reference/rules/only-call-hooks-from-react-functions"
+        },
+        {
+          "title": "Values are immutable after being passed to JSX",
+          "path": "/reference/rules/values-are-immutable-after-being-passed-to-jsx"
+        },
+        {
+          "title": "Return values and arguments to Hooks are immutable",
+          "path": "/reference/rules/return-values-and-arguments-to-hooks-are-immutable"
+        }
+      ]
+    },
     {
       "title": "Hooks",
       "path": "/reference/react/hooks",