feat(react-router): add support for structural sharing for finegrained selectors (#2647)

Co-authored-by: chorobin <[email protected]>

Author: schiller-manuel

docs/config.json

@@ -175,6 +175,10 @@
             {
               "label": "SSR",
               "to": "framework/react/guide/ssr"
+            },
+            {
+              "label": "Render Optimizations",
+              "to": "framework/react/guide/render-optimizations"
             }
           ]
         }

docs/framework/react/api/router/RouteApiType.md

@@ -23,6 +23,11 @@ The `RouteApi` has the following properties and methods:
     - Optional
     - `(match: RouteMatch) => TSelected`
     - If supplied, this function will be called with the route match and the return value will be returned from `useMatch`. This value will also be used to determine if the hook should re-render its parent component using shallow equality checks.
+  - `opts.structuralSharing`
+    - Optional
+    - `boolean`
+    - Configures whether structural sharing is enabled for the value returned by `select`.
+    - See the [Render Optimizations guide](../../guide/render-optimizations.md) for more information.
 - Returns
   - If a `select` function is provided, the return value of the `select` function.
   - If no `select` function is provided, the `RouteMatch` object or a loosened version of the `RouteMatch` object if `opts.strict` is `false`.
@@ -59,6 +64,11 @@ The `RouteApi` has the following properties and methods:
     - Optional
     - `(match: TFullSearchSchema) => TSelected`
     - If supplied, this function will be called with the route match and the return value will be returned from `useSearch`. This value will also be used to determine if the hook should re-render its parent component using shallow equality checks.
+  - `opts.structuralSharing`
+    - Optional
+    - `boolean`
+    - Configures whether structural sharing is enabled for the value returned by `select`.
+    - See the [Render Optimizations guide](../../guide/render-optimizations.md) for more information.
 - Returns
   - If a `select` function is provided, the return value of the `select` function.
   - If no `select` function is provided, the `TFullSearchSchema` object or a loosened version of the `TFullSearchSchema` object if `opts.strict` is `false`.
@@ -77,6 +87,11 @@ The `RouteApi` has the following properties and methods:
     - Optional
     - `(match: TAllParams) => TSelected`
     - If supplied, this function will be called with the route match and the return value will be returned from `useParams`. This value will also be used to determine if the hook should re-render its parent component using shallow equality checks.
+  - `opts.structuralSharing`
+    - Optional
+    - `boolean`
+    - Configures whether structural sharing is enabled for the value returned by `select`.
+    - See the [Render Optimizations guide](../../guide/render-optimizations.md) for more information.
 - Returns
   - If a `select` function is provided, the return value of the `select` function.
   - If no `select` function is provided, the `TAllParams` object or a loosened version of the `TAllParams` object if `opts.strict` is `false`.
@@ -95,6 +110,11 @@ The `RouteApi` has the following properties and methods:
     - Optional
     - `(match: TLoaderData) => TSelected`
     - If supplied, this function will be called with the route match and the return value will be returned from `useLoaderData`. This value will also be used to determine if the hook should re-render its parent component using shallow equality checks.
+  - `opts.structuralSharing`
+    - Optional
+    - `boolean`
+    - Configures whether structural sharing is enabled for the value returned by `select`.
+    - See the [Render Optimizations guide](../../guide/render-optimizations.md) for more information.
 - Returns
   - If a `select` function is provided, the return value of the `select` function.
   - If no `select` function is provided, the `TLoaderData` object or a loosened version of the `TLoaderData` object if `opts.strict` is `false`.
@@ -113,6 +133,11 @@ The `RouteApi` has the following properties and methods:
     - Optional
     - `(match: TLoaderDeps) => TSelected`
     - If supplied, this function will be called with the route match and the return value will be returned from `useLoaderDeps`.
+  - `opts.structuralSharing`
+    - Optional
+    - `boolean`
+    - Configures whether structural sharing is enabled for the value returned by `select`.
+    - See the [Render Optimizations guide](../../guide/render-optimizations.md) for more information.
 - Returns
   - If a `select` function is provided, the return value of the `select` function.
   - If no `select` function is provided, the `TLoaderDeps` object.

docs/framework/react/api/router/RouterOptionsType.md

@@ -292,3 +292,11 @@ const router = createRouter({
 - Type: `Array<';' | ':' | '@' | '&' | '=' | '+' | '$' | ','>`
 - Optional
 - Configures which URI characters are allowed in path params that would ordinarily be escaped by encodeURIComponent.
+
+### `defaultStructuralSharing` property
+
+- Type: `boolean`
+- Optional
+- Defaults to `false`
+- Configures whether structural sharing is enabled by default for fine-grained selectors.
+- See the [Render Optimizations guide](../../guide/render-optimizations.md) for more information.

docs/framework/react/api/router/useChildMatchesHook.md

@@ -18,6 +18,13 @@ The `useChildMatches` hook accepts a single _optional_ argument, an `options` ob
 - `(matches: RouteMatch[]) => TSelected`
 - If supplied, this function will be called with the route matches and the return value will be returned from `useChildMatches`. This value will also be used to determine if the hook should re-render its parent component using shallow equality checks.
 
+### `opts.structuralSharing` option
+
+- Type: `boolean`
+- Optional
+- Configures whether structural sharing is enabled for the value returned by `select`.
+- See the [Render Optimizations guide](../../guide/render-optimizations.md) for more information.
+
 ## useChildMatches returns
 
 - If a `select` function is provided, the return value of the `select` function.

docs/framework/react/api/router/useLoaderDataHook.md

@@ -29,6 +29,13 @@ The `useLoaderData` hook accepts an `options` object.
 - `(loaderData: TLoaderData) => TSelected`
 - If supplied, this function will be called with the loader data and the return value will be returned from `useLoaderData`. This value will also be used to determine if the hook should re-render its parent component using shallow equality checks.
 
+### `opts.structuralSharing` option
+
+- Type: `boolean`
+- Optional
+- Configures whether structural sharing is enabled for the value returned by `select`.
+- See the [Render Optimizations guide](../../guide/render-optimizations.md) for more information.
+
 ## useLoaderData returns
 
 - If a `select` function is provided, the return value of the `select` function.

docs/framework/react/api/router/useLoaderDepsHook.md

@@ -21,6 +21,13 @@ The `useLoaderDepsHook` hook accepts an `options` object.
 - Optional
 - If supplied, this function will be called with the loader dependencies object and the return value will be returned from `useLoaderDeps`.
 
+### `opts.structuralSharing` option
+
+- Type: `boolean`
+- Optional
+- Configures whether structural sharing is enabled for the value returned by `select`.
+- See the [Render Optimizations guide](../../guide/render-optimizations.md) for more information.
+
 ## useLoaderDeps returns
 
 - An object of the loader dependencies or `TSelected` if a `select` function is provided.

docs/framework/react/api/router/useMatchHook.md

@@ -30,6 +30,13 @@ The `useMatch` hook accepts a single argument, an `options` object.
 - `(match: RouteMatch) => TSelected`
 - If supplied, this function will be called with the route match and the return value will be returned from `useMatch`. This value will also be used to determine if the hook should re-render its parent component using shallow equality checks.
 
+### `opts.structuralSharing` option
+
+- Type: `boolean`
+- Optional
+- Configures whether structural sharing is enabled for the value returned by `select`.
+- See the [Render Optimizations guide](../../guide/render-optimizations.md) for more information.
+
 ### `opts.shouldThrow` option
 
 - Type: `boolean`

docs/framework/react/api/router/useMatchesHook.md

@@ -18,6 +18,13 @@ The `useMatches` hook accepts a single _optional_ argument, an `options` object.
 - `(matches: RouteMatch[]) => TSelected`
 - If supplied, this function will be called with the route matches and the return value will be returned from `useMatches`. This value will also be used to determine if the hook should re-render its parent component using shallow equality checks.
 
+### `opts.structuralSharing` option
+
+- Type: `boolean`
+- Optional
+- Configures whether structural sharing is enabled for the value returned by `select`.
+- See the [Render Optimizations guide](../../guide/render-optimizations.md) for more information.
+
 ## useMatches returns
 
 - If a `select` function is provided, the return value of the `select` function.

docs/framework/react/api/router/useParamsHook.md

@@ -21,6 +21,13 @@ The `useParams` hook accepts an optional `options` object.
 - `(params: AllParams) => TSelected`
 - If supplied, this function will be called with the params object and the return value will be returned from `useParams`. This value will also be used to determine if the hook should re-render its parent component using shallow equality checks.
 
+### `opts.structuralSharing` option
+
+- Type: `boolean`
+- Optional
+- Configures whether structural sharing is enabled for the value returned by `select`.
+- See the [Render Optimizations guide](../../guide/render-optimizations.md) for more information.
+
 ## useParams returns
 
 - An object of of the match's and parent match path params or `TSelected` if a `select` function is provided.

docs/framework/react/api/router/useParentMatchesHook.md

@@ -18,6 +18,13 @@ The `useParentMatches` hook accepts an optional `options` object.
 - `(matches: RouteMatch[]) => TSelected`
 - If supplied, this function will be called with the route matches and the return value will be returned from `useParentMatches`. This value will also be used to determine if the hook should re-render its parent component using shallow equality checks.
 
+### `opts.structuralSharing` option
+
+- Type: `boolean`
+- Optional
+- Configures whether structural sharing is enabled for the value returned by `select`.
+- See the [Render Optimizations guide](../../guide/render-optimizations.md) for more information.
+
 ## useParentMatches returns
 
 - If a `select` function is provided, the return value of the `select` function.