docs: new docs for placeholderData

Author: TkDodo

docs/react/guides/placeholder-query-data.md

@@ -16,9 +16,11 @@ There are a few ways to supply placeholder data for a query to the cache before
 - Imperatively:
   - [Prefetch or fetch the data using `queryClient` and the `placeholderData` option](../guides/prefetching)
 
+When we use `placeholderData`, our Query will not be in a `pending` state - it will start out as being in `success` state, because we have `data` to display - even if that data is just "placeholder" data. To distinguish it from "real" data, we will also have the `isPlaceholderData` flag set to `true` on the Query result.
+
 ## Placeholder Data as a Value
 
-[//]: # 'Example'
+[//]: # 'ExampleValue'
 
 ```tsx
 function Todos() {
@@ -30,16 +32,13 @@ function Todos() {
 }
 ```
 
-[//]: # 'Example'
+[//]: # 'ExampleValue'
 [//]: # 'Memoization'
 
 ### Placeholder Data Memoization
 
 If the process for accessing a query's placeholder data is intensive or just not something you want to perform on every render, you can memoize the value:
 
-[//]: # 'Memoization'
-[//]: # 'Example2'
-
 ```tsx
 function Todos() {
   const placeholderData = useMemo(() => generateFakeTodos(), [])
@@ -51,13 +50,25 @@ function Todos() {
 }
 ```
 
-[//]: # 'Example2'
+[//]: # 'Memoization'
+
+## Placeholder Data as a Function
+
+`placeholderData` can also be a function, where you can get access to the data and Query meta information of a "previous" successful Query. This is useful for situations where you want to use the data from one query as the placeholder data for another query. When the QueryKey changes, e.g. from `['todos', 1]` to `['todos', 2]`, we can keep displaying "old" data instead of having to show a loading spinner while data is _transitioning_ from one Query to the next. For more information, see [Paginated Queries](../guides/paginated-queries).
+
+```tsx
+const result = useQuery({
+  queryKey: ['todos', id],
+  queryFn: () => fetch(`/todos/${id}`),
+  placeholderData: (previousData, previousQuery) => previousData,
+})
+```
 
 ### Placeholder Data from Cache
 
 In some circumstances, you may be able to provide the placeholder data for a query from the cached result of another. A good example of this would be searching the cached data from a blog post list query for a preview version of the post, then using that as the placeholder data for your individual post query:
 
-[//]: # 'Example3'
+[//]: # 'ExampleCache'
 
 ```tsx
 function Todo({ blogPostId }) {
@@ -75,7 +86,7 @@ function Todo({ blogPostId }) {
 }
 ```
 
-[//]: # 'Example3'
+[//]: # 'ExampleCache'
 [//]: # 'Materials'
 
 ## Further reading

docs/react/reference/useQuery.md

@@ -148,11 +148,11 @@ const {
 - `initialDataUpdatedAt: number | (() => number | undefined)`
   - Optional
   - If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated.
-- `placeholderData: TData | (previousValue: TData) => TData`
+- `placeholderData: TData | (previousValue: TData | undefined; previousQuery: Query | undefined,) => TData`
   - Optional
-  - If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `pending` data and no initialData has been provided.
+  - If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `pending` state.
   - `placeholderData` is **not persisted** to the cache
-  - If you provide a function for `placeholderData`, as a first argument you will receive previously watched query data if available
+  - If you provide a function for `placeholderData`, as a first argument you will receive previously watched query data if available, and the second argument will be the complete previousQuery instance.
 - `structuralSharing: boolean | ((oldData: TData | undefined, newData: TData) => TData)`
   - Optional
   - Defaults to `true`

docs/vue/guides/placeholder-query-data.md

@@ -4,7 +4,7 @@ title: Placeholder Query Data
 ref: docs/react/guides/placeholder-query-data.md
 ---
 
-[//]: # 'Example'
+[//]: # 'ExampleValue'
 
 ```tsx
 const result = useQuery({
@@ -14,12 +14,10 @@ const result = useQuery({
 })
 ```
 
-[//]: # 'Example'
+[//]: # 'ExampleValue'
 [//]: # 'Memoization'
 [//]: # 'Memoization'
-[//]: # 'Example2'
-[//]: # 'Example2'
-[//]: # 'Example3'
+[//]: # 'ExampleCache'
 
 ```tsx
 const result = useQuery({
@@ -35,6 +33,6 @@ const result = useQuery({
 })
 ```
 
-[//]: # 'Example3'
+[//]: # 'ExampleCache'
 [//]: # 'Materials'
 [//]: # 'Materials'