Review edits: more mutation info, "Summary" sections

Author: markerikson

docs/tutorials/essentials/part-1-overview-concepts.md

@@ -441,7 +441,7 @@ Here's what that data flow looks like visually:
 
 Redux does have a number of new terms and concepts to remember. As a reminder, here's what we just covered:
 
-:::tip
+:::Summary
 
 - **Redux is a library for managing global application state**
   - Redux is typically used with the React-Redux library for integrating Redux and React together

docs/tutorials/essentials/part-2-app-structure.md

@@ -303,20 +303,28 @@ Earlier, we talked about "mutation" (modifying existing object/array values) and
 In Redux, **our reducers are _never_ allowed to mutate the original / current state values!**
 
 ```js
-// Illegal - don't do this in a normal reducer!
+// ❌ Illegal - don't do this in a normal reducer!
 state.value = 123
 ```
 
 :::
 
+There are several reasons why you must not mutate state in Redux:
+
+- It causes bugs, such as the UI not updating properly to show the latest values
+- It makes it harder to understand why and how the state has been updated
+- It makes it harder to write tests
+- It breaks the ability to use "time-travel debugging" correctly
+- It goes against the intended spirit and usage patterns for Redux
+
 So if we can't change the originals, how do we return an updated state?
 
 :::tip
 
 **Reducers can only make _copies_ of the original values, and then they can mutate the copies.**
 
 ```js
-// This is safe, because we made a copy
+// ✅ This is safe, because we made a copy
 return {
   ...state,
   value: 123
@@ -720,7 +728,7 @@ Now, any React components that call `useSelector` or `useDispatch` will be talki
 
 Even though the counter example app is pretty small, it showed all the key pieces of a React + Redux app working together. Here's what we covered:
 
-:::tip
+:::Summary
 
 - **We can create a Redux store using the Redux Toolkit `configureStore` API**
   - `configureStore` accepts a `reducer` function as a named argument

docs/tutorials/essentials/part-3-data-flow.md

@@ -428,7 +428,7 @@ Notice that our `AddPostForm` component has some React `useState` hooks inside,
 
 Let's recap what you've learned in this section:
 
-:::tip
+:::Summary
 
 - **Redux state is updated by "reducer functions"**:
   - Reducers always calculate a new state _immutably_, by copying existing state values and modifying the copies with the new data

docs/tutorials/essentials/part-4-using-data.md

@@ -819,7 +819,7 @@ It's actually starting to look more useful and interesting!
 
 We've covered a lot of information and concepts in this section. Let's recap the important things to remember:
 
-:::tip
+:::Summary
 
 - **Any React component can use data from the Redux store as needed**
   - Any component can read any data that is in the Redux store

docs/tutorials/essentials/part-5-async-logic.md

@@ -784,7 +784,7 @@ Here's what our app looks like now that we're fetching data from that fake API:
 
 As a reminder, here's what we covered in this section:
 
-:::tip
+:::Summary
 
 - **You can write reusable "selector" functions to encapsulate reading values from the Redux state**
   - Selectors are functions that get the Redux `state` as an argument, and return some data

docs/tutorials/essentials/part-6-performance-normalization.md

@@ -978,7 +978,7 @@ Congratulations, you've completed the Redux Essentials tutorial! Let's see what
 
 Here's what we covered in this section:
 
-:::tip
+:::Summary
 
 - **Memoized selector functions can be used to optimize performance**
   - Redux Toolkit re-exports the `createSelector` function from Reselect, which generates memoized selectors

docs/tutorials/fundamentals/part-1-overview.md

@@ -131,7 +131,7 @@ The center of every Redux application is the **store**. A "store" is a container
 
 A store is a JavaScript object with a few special functions and abilities that make it different than a plain global object:
 
-- You cannot directly modify or change the state that is kept inside the Redux store
+- You must never directly modify or change the state that is kept inside the Redux store
 - Instead, the only way to cause an update to the state is to create a plain **action** object that describes "something that happened in the application", and then **dispatch** the action to the store to tell it what happened.
 - When an action is dispatched, the store runs the root **reducer** function, and lets it calculate the new state based on the old state and the action
 - Finally, the store notifies **subscribers** that the state has been updated so the UI can be updated with the new data.
@@ -307,7 +307,7 @@ That counter example was small, but it does show all the working pieces of a rea
 
 With that in mind, let's review what we've learned so far:
 
-:::tip
+:::Summary
 
 - **Redux is a library for managing global application state**
   - Redux is typically used with the React-Redux library for integrating Redux and React together

docs/tutorials/fundamentals/part-2-concepts-data-flow.md

@@ -357,7 +357,7 @@ Here's what that data flow looks like visually:
 
 ## What You've Learned
 
-:::tip
+:::Summary
 
 - **Redux's intent can be summarized in three principles**
   - Global app state is kept in a single store

docs/tutorials/fundamentals/part-3-state-actions-reducers.md

@@ -365,20 +365,28 @@ Earlier, we talked about "mutation" (modifying existing object/array values) and
 In Redux, **our reducers are _never_ allowed to mutate the original / current state values!**
 
 ```js
-// Illegal - don't do this in a normal reducer!
+// ❌ Illegal - don't do this in a normal reducer!
 state.value = 123
 ```
 
 :::
 
+There are several reasons why you must not mutate state in Redux:
+
+- It causes bugs, such as the UI not updating properly to show the latest values
+- It makes it harder to understand why and how the state has been updated
+- It makes it harder to write tests
+- It breaks the ability to use "time-travel debugging" correctly
+- It goes against the intended spirit and usage patterns for Redux
+
 So if we can't change the originals, how do we return an updated state?
 
 :::tip
 
 **Reducers can only make _copies_ of the original values, and then they can mutate the copies.**
 
 ```js
-// This is safe, because we made a copy
+// ✅ This is safe, because we made a copy
 return {
   ...state,
   value: 123
@@ -698,14 +706,14 @@ Here's the contents of our app so far:
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
 ></iframe>
 
-:::tip
+:::Summary
 
 - **Redux apps use plain JS objects, arrays, and primitives as the state values**
   - The root state value should be a plain JS object
   - The state should contain the smallest amount of data needed to make the app work
   - Classes, Promises, functions, and other non-plain values should _not_ go in the Redux state
   - Reducers must not create random values like `Math.random()` or `Date.now()`
-  - It's okay to have other state values that are not in the Redux store
+  - It's okay to have other state values that are not in the Redux store (like local component state) side-by side with Redux
 - **Actions are plain objects with a `type` field that describe what happened**
   - The `type` field should be a readable string, and is usually written as `'feature/eventName'`
   - Actions may contain other values, which are typically stored in the `action.payload` field

docs/tutorials/fundamentals/part-4-store.md

@@ -156,7 +156,7 @@ Notice that our app did _not_ log anything from the last action. That's because
 We specified the behavior of our app before we even started writing the UI. That
 helps give us confidence that the app will work as intended.
 
-:::tip
+:::info
 
 If you want, you can now try writing tests for your reducers. Because they're [pure functions](../../understanding/thinking-in-redux/ThreePrinciples.md#changes-are-made-with-pure-functions), it should be straightforward to test them. Call them with an example `state` and `action`,
 take the result, and check to see if it matches what you expect:
@@ -218,6 +218,27 @@ As you can see, the actual logic here is fairly short:
 - The store dispatches one action on startup to initialize the reducers with their state
 - The store API is an object with `{dispatch, subscribe, getState}` inside
 
+To emphasize one of those in particular: notice that `getState` just returns whatever the current `state` value is. That means that **by default, nothing prevents you from accidentally mutating the current state value!** This code will run without any errors, but it's incorrect:
+
+```js
+const state = store.getState()
+// ❌ Don't do this - it mutates the current state!
+state.filters.status = 'Active'
+```
+
+In other words:
+
+- The Redux store doesn't make an extra copy of the `state` value when you call `getState()`. It's exactly the same reference that was returned from the root reducer function
+- The Redux store doesn't do anything else to prevent accidental mutations. It _is_ possible to mutate the state, either inside a reducer or outside the store, and you must always be careful to avoid mutations.
+
+One common cause of accidental mutations is sorting arrays. [**Calling `array.sort()` actually mutates the existing array**](https://doesitmutate.xyz/sort/). If we called `const sortedTodos = state.todos.sort()`, we'd end up mutating the real store state unintentionally.
+
+:::tip
+
+In [Part 8: Modern Redux](./part-8-modern-redux.md), we'll see how Redux Toolkit helps avoid mutations in reducers, and detects and warns about accidental mutations outside of reducers.
+
+:::
+
 ## Configuring the Store
 
 We've already seen that we can pass `rootReducer` and `preloadedState` arguments to `createStore`. However, `createStore` can also take one more argument, which is used to customize the store's abilities and give it new powers.
@@ -585,7 +606,7 @@ Let's see how our example app looks now:
 
 And as a reminder, here's what we covered in this section:
 
-:::tip
+:::Summary
 
 - **Redux apps always have a single store**
   - Stores are created with the Redux `createStore` API

docs/tutorials/fundamentals/part-5-ui-and-react.md

@@ -25,7 +25,7 @@ In this section, we'll add a User Interface for our todo app. We'll see how Redu
 
 ## Integrating Redux with a UI
 
-Redux is a standalone JS library. As we've already seen, you can create and use a Redux store even if you don't have a user interface set up. This also means that **you can use Redux with any UI framework**. You can write Redux apps with React, Vue, Angular, Ember, jQuery, or vanilla JavaScript.
+Redux is a standalone JS library. As we've already seen, you can create and use a Redux store even if you don't have a user interface set up. This also means that **you can use Redux with any UI framework** (or even without _any_ UI framework), and use it on both client and server. You can write Redux apps with React, Vue, Angular, Ember, jQuery, or vanilla JavaScript.
 
 That said, **Redux was specifically designed to work well with [React](https://reactjs.org)**. React lets you describe your UI as a function of your state, and Redux contains state and updates it in response to actions.
 
@@ -553,7 +553,7 @@ Let's see how the app looks now, including the components and sections we skippe
   sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"
 ></iframe>
 
-:::tip
+:::Summary
 
 - **Redux stores can be used with any UI layer**
   - UI code always subscribes to the store, gets the latest state, and redraws itself

docs/tutorials/fundamentals/part-6-async-logic.md

@@ -445,7 +445,7 @@ Here's what the current app looks like:
   sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"
 ></iframe>
 
-:::tip
+:::Summary
 
 - **Redux middleware were designed to enable writing logic that has side effects**
   - "Side effects" are code that changes state/behavior outside a function, like AJAX calls, modifying function arguments, or generating random values

docs/tutorials/fundamentals/part-7-standard-patterns.md

@@ -972,7 +972,7 @@ Here's how our app looks after it's been fully converted to use these patterns:
   sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"
 ></iframe>
 
-:::tip
+:::Summary
 
 - **Action creator functions encapsulate preparing action objects and thunks**
   - Action creators can accept arguments and contain setup logic, and return the final action object or thunk function

docs/tutorials/fundamentals/part-8-modern-redux.md

@@ -838,7 +838,7 @@ Let's take one final look at the completed todo application, including all the c
 
 And we'll do a final recap of the key points you learned in this section:
 
-:::tip
+:::Summary
 
 - **Redux Toolkit (RTK) is the standard way to write Redux logic**
   - RTK includes APIs that simplify most Redux code