Merge pull request #957 from Workiva/docs-migrate-connect-vs-hooks

FED-3236 Docs: add more details around connect vs hooks

doc/null_safety/null_safe_migration.md

@@ -206,12 +206,18 @@ of the null safety and required props docs for instructions on how to handle the
 
 #### connect
 
-For connect, either
+For connect, either:
 - Disable validation using the instructions linked above 
     - Note: for now, this must be done manually, but we'll be adding a codemod to help do this automatically for `connect`: https://github.com/Workiva/over_react_codemod/issues/295
 - Refactor your component to instead utilize [OverReact Redux hooks](../over_react_redux_documentation.md#hooks), 
     which avoid this problem by accessing store data and dispatchers directly in the component as opposed to passing it in via props.
 
+We generally recommend using hooks over `connect`, since the API is simpler, and in over_react is more convenient and doesn't involve worrying about required prop validation.
+
+However, for existing components, converting them to function components may be non-trivial depending on other logic within components that needs to be migrated.
+
+So, for this migration, you'll want to decide whether converting to function components is worth the effort.
+
 #### Implementing abstract `Ref`s
 
 After migrating to null-safety, it may be necessary to add left side typing on `Ref`s when overriding abstract getters as shown in the example below:

doc/over_react_redux_documentation.md

@@ -10,6 +10,10 @@ A Dart wrapper for React Redux, providing targeted state updates.
   - [Running the Examples](#running-the-examples)
 - **[Using it in your project](#using-it-in-your-project)**
 - **[ReduxProvider](#reduxprovider)**
+- **[Hooks](#hooks)**
+  - [useSelector](#useselector)
+  - [useDispatch](#usedispatch)
+  - [useStore](#usestore)
 - **[Connect](#connect)**
   - [`connect` Parameters](#connect-parameters)
     - [mapStateToProps](#mapstatetoprops)
@@ -22,10 +26,6 @@ A Dart wrapper for React Redux, providing targeted state updates.
     - [context](#context)
     - [pure](#pure)
     - [forwardRef](#forwardref)
-- **[Hooks](#hooks)**
-  - [useSelector](#useselector)
-  - [useDispatch](#usedispatch)
-  - [useStore](#usestore)
 - **[Using Multiple Stores](#using-multiple-stores)**
 - **[Using Redux DevTools](#using-redux-devtools)**
   - [Integrating with DevTools](#integration-with-devtools)
@@ -168,6 +168,9 @@ A wrapper around the JS react-redux `connect` function that supports OverReact c
 
 > See: <https://react-redux.js.org/api/connect>
 
+> ![TIP]
+> connect still works and is supported. However, we recommend using the hooks API as the default.
+
 **Example:**
 
 ```dart
@@ -299,10 +302,18 @@ class CounterProps = UiProps with CounterPropsMixin, OtherPropsMixin;
 > [More information about the `connect` function](https://react-redux.js.org/api/connect#connect)
 
 ## Hooks
+
 OverReact exposes wrappers around React Redux hook APIs, which serve as an alternative to the existing [`connect()`](#connect) Higher Order Component. 
 These APIs allow you to subscribe to the Redux store and dispatch actions, without having to wrap your components 
 in [`connect()`](#connect).
 
+> [!TIP]
+> **We recommend using the React-Redux hooks API as the default approach in your React components.**
+>
+> The existing connect API still works and will continue to be supported, but the hooks API is simpler, 
+> requires less OverReact boilerplate, and doesn't involve suppressing validation for required props 
+> (see [connect](#connect) docs for more info).
+
 > See: <https://react-redux.js.org/api/hooks>
 
 As with [`connect()`](#connect), you should start by wrapping your entire application in a 
@@ -731,4 +742,4 @@ When an enum `Action` is used the value of the action in the enum will be used
 {"type": "ACTION_1"}
 ```
 
-For a more encoding details check out the [redux_remote_devtools](https://pub.dev/packages/redux_remote_devtools)
+For a more encoding details check out the [redux_remote_devtools](https://pub.dev/packages/redux_remote_devtools)