docs(solid-query): convert guide docs to ref-based with Solid-style code (#10146)

* docs(react-query/guides): add markers for solid-query guide overrides

* docs(solid-query/guides): convert guide docs to ref-based with Solid-style code

* docs(config): add solid offline example entry and update lockfile

* ci: apply automated fixes

* docs(react/guides/caching): unify staleTime wording to passive voice

* chore(pnpm-lock.yaml): fix broken lockfile for 'msw' dependency

* docs(solid/guides/caching): remove redundant 'StaleNote' override now unified with react

* docs(react/guides/caching): remove unused 'StaleNote' markers

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: sukvvon

docs/config.json

@@ -1419,6 +1419,10 @@
             {
               "label": "Astro",
               "to": "framework/solid/examples/astro"
+            },
+            {
+              "label": "Offline Queries and Mutations",
+              "to": "framework/solid/examples/offline"
             }
           ]
         },

docs/framework/react/guides/caching.md

@@ -19,7 +19,7 @@ Let's assume we are using the default `gcTime` of **5 minutes** and the default
 - A new instance of `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` mounts.
   - Since no other queries have been made with the `['todos']` query key, this query will show a hard loading state and make a network request to fetch the data.
   - When the network request has completed, the returned data will be cached under the `['todos']` key.
-  - The hook will mark the data as stale after the configured `staleTime` (defaults to `0`, or immediately).
+  - The data will be marked as stale after the configured `staleTime` (defaults to `0`, or immediately).
 - A second instance of `useQuery({ queryKey: ['todos'], queryFn: fetchTodos })` mounts elsewhere.
   - Since the cache already has data for the `['todos']` key from the first query, that data is immediately returned from the cache.
   - The new instance triggers a new network request using its query function.

docs/framework/react/guides/important-defaults.md

@@ -32,9 +32,13 @@ Out of the box, TanStack Query is configured with **aggressive but sane** defaul
 
   > To change this, you can alter the default `retry` and `retryDelay` options for queries to something other than `3` and the default exponential backoff function.
 
+[//]: # 'StructuralSharing'
+
 - Query results by default are **structurally shared to detect if data has actually changed** and if not, **the data reference remains unchanged** to better help with value stabilization with regards to useMemo and useCallback. If this concept sounds foreign, then don't worry about it! 99.9% of the time you will not need to disable this and it makes your app more performant at zero cost to you.
 
-  > Structural sharing only works with JSON-compatible values, any other value types will always be considered as changed. If you are seeing performance issues because of large responses for example, you can disable this feature with the `config.structuralSharing` flag. If you are dealing with non-JSON compatible values in your query responses and still want to detect if data has changed or not, you can provide your own custom function as `config.structuralSharing` to compute a value from the old and new responses, retaining references as required.
+[//]: # 'StructuralSharing'
+
+> Structural sharing only works with JSON-compatible values, any other value types will always be considered as changed. If you are seeing performance issues because of large responses for example, you can disable this feature with the `config.structuralSharing` flag. If you are dealing with non-JSON compatible values in your query responses and still want to detect if data has changed or not, you can provide your own custom function as `config.structuralSharing` to compute a value from the old and new responses, retaining references as required.
 
 [//]: # 'Materials'
 

docs/framework/react/guides/mutations.md

@@ -340,11 +340,14 @@ queryClient.resumePausedMutations()
 ```
 
 [//]: # 'Example10'
+[//]: # 'PersistOfflineIntro'
 
 ### Persisting Offline mutations
 
 If you persist offline mutations with the [persistQueryClient plugin](../plugins/persistQueryClient.md), mutations cannot be resumed when the page is reloaded unless you provide a default mutation function.
 
+[//]: # 'PersistOfflineIntro'
+
 This is a technical limitation. When persisting to an external storage, only the state of mutations is persisted, as functions cannot be serialized. After hydration, the component that triggers the mutation might not be mounted, so calling `resumePausedMutations` might yield an error: `No mutationFn found`.
 
 [//]: # 'Example11'
@@ -385,9 +388,12 @@ export default function App() {
 ```
 
 [//]: # 'Example11'
+[//]: # 'OfflineExampleLink'
 
 We also have an extensive [offline example](../examples/offline) that covers both queries and mutations.
 
+[//]: # 'OfflineExampleLink'
+
 ## Mutation Scopes
 
 Per default, all mutations run in parallel - even if you invoke `.mutate()` of the same mutation multiple times. Mutations can be given a `scope` with an `id` to avoid that. All mutations with the same `scope.id` will run in serial, which means when they are triggered, they will start in `isPaused: true` state if there is already a mutation for that scope in progress. They will be put into a queue and will automatically resume once their time in the queue has come.

docs/framework/react/guides/parallel-queries.md

@@ -35,9 +35,11 @@ function App () {
 If the number of queries you need to execute is changing from render to render, you cannot use manual querying since that would violate the rules of hooks. Instead, TanStack Query provides a `useQueries` hook, which you can use to dynamically execute as many queries in parallel as you'd like.
 
 [//]: # 'DynamicParallelIntro'
+[//]: # 'DynamicParallelDescription'
 
 `useQueries` accepts an **options object** with a **queries key** whose value is an **array of query objects**. It returns an **array of query results**:
 
+[//]: # 'DynamicParallelDescription'
 [//]: # 'Example2'
 
 ```tsx

docs/framework/react/guides/queries.md

@@ -7,8 +7,12 @@ title: Queries
 
 A query is a declarative dependency on an asynchronous source of data that is tied to a **unique key**. A query can be used with any Promise based method (including GET and POST methods) to fetch data from a server. If your method modifies data on the server, we recommend using [Mutations](./mutations.md) instead.
 
+[//]: # 'SubscribeDescription'
+
 To subscribe to a query in your components or custom hooks, call the `useQuery` hook with at least:
 
+[//]: # 'SubscribeDescription'
+
 - A **unique key for the query**
 - A function that returns a promise that:
   - Resolves the data, or

docs/framework/react/guides/query-cancellation.md

@@ -208,4 +208,8 @@ A cancel options object supports the following properties:
 
 ## Limitations
 
+[//]: # 'Limitations'
+
 Cancellation does not work when working with `Suspense` hooks: `useSuspenseQuery`, `useSuspenseQueries` and `useSuspenseInfiniteQuery`.
+
+[//]: # 'Limitations'

docs/framework/react/guides/query-options.md

@@ -33,8 +33,11 @@ queryClient.setQueryData(groupOptions(42).queryKey, newGroups)
 
 For Infinite Queries, a separate [`infiniteQueryOptions`](../reference/infiniteQueryOptions.md) helper is available.
 
+[//]: # 'SelectDescription'
+
 You can still override some options at the component level. A very common and useful pattern is to create per-component [`select`](./render-optimizations.md#select) functions:
 
+[//]: # 'SelectDescription'
 [//]: # 'Example2'
 
 ```ts

docs/framework/react/guides/request-waterfalls.md

@@ -11,8 +11,12 @@ The [Prefetching & Router Integration guide](./prefetching.md) builds on this an
 
 The [Server Rendering & Hydration guide](./ssr.md) teaches you how to prefetch data on the server and pass that data down to the client so you don't have to fetch it again.
 
+[//]: # 'AdvancedSSRLink'
+
 The [Advanced Server Rendering guide](./advanced-ssr.md) further teaches you how to apply these patterns to Server Components and Streaming Server Rendering.
 
+[//]: # 'AdvancedSSRLink'
+
 ## What is a Request Waterfall?
 
 A request waterfall is what happens when a request for a resource (code, css, images, data) does not start until _after_ another request for a resource has finished.
@@ -67,6 +71,8 @@ With this as a basis, let's look at a few different patterns that can lead to Re
 
 When a single component first fetches one query, and then another, that's a request waterfall. This can happen when the second query is a [Dependent Query](./dependent-queries.md), that is, it depends on data from the first query when fetching:
 
+[//]: # 'DependentExample'
+
 ```tsx
 // Get the user
 const { data: user } = useQuery({
@@ -89,10 +95,17 @@ const {
 })
 ```
 
+[//]: # 'DependentExample'
+
 While not always feasible, for optimal performance it's better to restructure your API so you can fetch both of these in a single query. In the example above, instead of first fetching `getUserByEmail` to be able to `getProjectsByUser`, introducing a new `getProjectsByUserEmail` query would flatten the waterfall.
 
+[//]: # 'ServerComponentsNote1'
+
 > Another way to mitigate dependent queries without restructuring your API is to move the waterfall to the server where latency is lower. This is the idea behind Server Components which are covered in the [Advanced Server Rendering guide](./advanced-ssr.md).
 
+[//]: # 'ServerComponentsNote1'
+[//]: # 'SuspenseSerial'
+
 Another example of serial queries is when you use React Query with Suspense:
 
 ```tsx
@@ -122,14 +135,22 @@ const [usersQuery, teamsQuery, projectsQuery] = useSuspenseQueries({
 })
 ```
 
+[//]: # 'SuspenseSerial'
+
 ### Nested Component Waterfalls
 
+[//]: # 'NestedIntro'
+
 Nested Component Waterfalls is when both a parent and a child component contains queries, and the parent does not render the child until its query is done. This can happen both with `useQuery` and `useSuspenseQuery`.
 
+[//]: # 'NestedIntro'
+
 If the child renders conditionally based on the data in the parent, or if the child relies on some part of the result being passed down as a prop from the parent to make its query, we have a _dependent_ nested component waterfall.
 
 Let's first look at an example where the child is **not** dependent on the parent.
 
+[//]: # 'NestedExample'
+
 ```tsx
 function Article({ id }) {
   const { data: articleData, isPending } = useQuery({
@@ -161,8 +182,12 @@ function Comments({ id }) {
 }
 ```
 
+[//]: # 'NestedExample'
+
 Note that while `<Comments>` takes a prop `id` from the parent, that id is already available when the `<Article>` renders so there is no reason we could not fetch the comments at the same time as the article. In real world applications, the child might be nested far below the parent and these kinds of waterfalls are often trickier to spot and fix, but for our example, one way to flatten the waterfall would be to hoist the comments query to the parent instead:
 
+[//]: # 'NestedHoistedExample'
+
 ```tsx
 function Article({ id }) {
   const { data: articleData, isPending: articlePending } = useQuery({
@@ -193,12 +218,19 @@ function Article({ id }) {
 }
 ```
 
+[//]: # 'NestedHoistedExample'
+[//]: # 'NestedHoistedOutro'
+
 The two queries will now fetch in parallel. Note that if you are using suspense, you'd want to combine these two queries into a single `useSuspenseQueries` instead.
 
+[//]: # 'NestedHoistedOutro'
+
 Another way to flatten this waterfall would be to prefetch the comments in the `<Article>` component, or prefetch both of these queries at the router level on page load or page navigation, read more about this in the [Prefetching & Router Integration guide](./prefetching.md).
 
 Next, let's look at a _Dependent Nested Component Waterfall_.
 
+[//]: # 'DependentNestedExample'
+
 ```tsx
 function Feed() {
   const { data, isPending } = useQuery({
@@ -233,15 +265,21 @@ function GraphFeedItem({ feedItem }) {
 }
 ```
 
+[//]: # 'DependentNestedExample'
+
 The second query `getGraphDataById` is dependent on its parent in two different ways. First of all, it doesn't ever happen unless the `feedItem` is a graph, and second, it needs an `id` from the parent.
 
 ```
 1. |> getFeed()
 2.   |> getGraphDataById()
 ```
 
+[//]: # 'ServerComponentsNote2'
+
 In this example, we can't trivially flatten the waterfall by just hoisting the query to the parent, or even adding prefetching. Just like the dependent query example at the beginning of this guide, one option is to refactor our API to include the graph data in the `getFeed` query. Another more advanced solution is to leverage Server Components to move the waterfall to the server where latency is lower (read more about this in the [Advanced Server Rendering guide](./advanced-ssr.md)) but note that this can be a very big architectural change.
 
+[//]: # 'ServerComponentsNote2'
+
 You can have good performance even with a few query waterfalls here and there, just know they are a common performance concern and be mindful about them. An especially insidious version is when Code Splitting is involved, let's take a look at this next.
 
 ### Code Splitting
@@ -323,13 +361,17 @@ In the code split case, it might actually help to hoist the `getGraphDataById` q
 
 This is very much a tradeoff however. You are now including the data fetching code for `getGraphDataById` in the same bundle as `<Feed>`, so evaluate what is best for your case. Read more about how to do this in the [Prefetching & Router Integration guide](./prefetching.md).
 
+[//]: # 'ServerComponentsNote3'
+
 > The tradeoff between:
 >
 > - Include all data fetching code in the main bundle, even if we seldom use it
 > - Put the data fetching code in the code split bundle, but with a request waterfall
 >
 > is not great and has been one of the motivations for Server Components. With Server Components, it's possible to avoid both, read more about how this applies to React Query in the [Advanced Server Rendering guide](./advanced-ssr.md).
 
+[//]: # 'ServerComponentsNote3'
+
 ## Summary and takeaways
 
 Request Waterfalls are a very common and complex performance concern with many tradeoffs. There are many ways to accidentally introduce them into your application:

docs/framework/solid/guides/background-fetching-indicators.md

@@ -2,5 +2,56 @@
 id: background-fetching-indicators
 title: Background Fetching Indicators
 ref: docs/framework/react/guides/background-fetching-indicators.md
-replace: { 'useMutation[(]': 'useMutation(() => ' }
+replace: { 'hook': 'function' }
 ---
+
+[//]: # 'Example'
+
+```tsx
+import { Switch, Match, Show, For } from 'solid-js'
+
+function Todos() {
+  const todosQuery = useQuery(() => ({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  }))
+
+  return (
+    <Switch>
+      <Match when={todosQuery.isPending}>
+        <span>Loading...</span>
+      </Match>
+      <Match when={todosQuery.isError}>
+        <span>Error: {todosQuery.error.message}</span>
+      </Match>
+      <Match when={todosQuery.isSuccess}>
+        <Show when={todosQuery.isFetching}>
+          <div>Refreshing...</div>
+        </Show>
+        <div>
+          <For each={todosQuery.data}>{(todo) => <Todo todo={todo} />}</For>
+        </div>
+      </Match>
+    </Switch>
+  )
+}
+```
+
+[//]: # 'Example'
+[//]: # 'Example2'
+
+```tsx
+import { useIsFetching } from '@tanstack/solid-query'
+
+function GlobalLoadingIndicator() {
+  const isFetching = useIsFetching()
+
+  return (
+    <Show when={isFetching()}>
+      <div>Queries are fetching in the background...</div>
+    </Show>
+  )
+}
+```
+
+[//]: # 'Example2'