docs(preact-query): document functions and components with JSDoc for generated reference docs

docs/framework/preact/reference/functions/HydrationBoundary.md

@@ -7,7 +7,13 @@ title: HydrationBoundary
 function HydrationBoundary(__namedParameters): Element;
 ```
 
-Defined in: [preact-query/src/HydrationBoundary.tsx:26](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L26)
+Defined in: [preact-query/src/HydrationBoundary.tsx:85](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L85)
+
+`HydrationBoundary` adds a previously dehydrated state into the `queryClient` that would be returned by
+`useQueryClient()`. If the client already contains data, the new queries will be intelligently merged based on
+update timestamp.
+
+Note: Only `queries` can be dehydrated with an `HydrationBoundary`.
 
 ## Parameters
 
@@ -18,3 +24,40 @@ Defined in: [preact-query/src/HydrationBoundary.tsx:26](https://github.com/TanSt
 ## Returns
 
 `Element`
+
+The provided `children`, rendered unconditionally. New queries in `state` are hydrated into the
+cache during render; for queries already in the cache, only newer dehydrated data is hydrated, in an effect
+after commit.
+
+## Examples
+
+```tsx
+import { HydrationBoundary } from '@tanstack/preact-query'
+
+function App() {
+  return <HydrationBoundary state={dehydratedState}>...</HydrationBoundary>
+}
+```
+
+Server-side prefetch handed off to the client via `dehydrate`:
+```tsx
+import { noop } from '@tanstack/query-core'
+import { HydrationBoundary, dehydrate } from '@tanstack/preact-query'
+
+async function ServerComponent() {
+  const queryClient = getQueryClient()
+
+  await queryClient
+    .query({
+      queryKey: ['posts'],
+      queryFn: fetchPosts,
+    })
+    .catch(noop)
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <Posts />
+    </HydrationBoundary>
+  )
+}
+```

docs/framework/preact/reference/functions/QueryClientProvider.md

@@ -7,7 +7,9 @@ title: QueryClientProvider
 function QueryClientProvider(__namedParameters): VNode;
 ```
 
-Defined in: [preact-query/src/QueryClientProvider.tsx:29](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L29)
+Defined in: [preact-query/src/QueryClientProvider.tsx:63](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L63)
+
+Use the `QueryClientProvider` component to connect and provide a `QueryClient` to your application.
 
 ## Parameters
 
@@ -18,3 +20,17 @@ Defined in: [preact-query/src/QueryClientProvider.tsx:29](https://github.com/Tan
 ## Returns
 
 `VNode`
+
+The provided `children`, wrapped so they can read the `QueryClient` via `useQueryClient`.
+
+## Example
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/preact-query'
+
+const queryClient = new QueryClient()
+
+function App() {
+  return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
+}
+```

docs/framework/preact/reference/functions/QueryErrorResetBoundary.md

@@ -7,7 +7,11 @@ title: QueryErrorResetBoundary
 function QueryErrorResetBoundary(__namedParameters): Element;
 ```
 
-Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:48](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L48)
+Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:154](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L154)
+
+When using **suspense** or **throwOnError** in your queries, you need a way to let queries know that you want to
+try again when re-rendering after some error occurred. With the `QueryErrorResetBoundary` component you can
+reset any query errors within the boundaries of the component.
 
 ## Parameters
 
@@ -18,3 +22,45 @@ Defined in: [preact-query/src/QueryErrorResetBoundary.tsx:48](https://github.com
 ## Returns
 
 `Element`
+
+The `children`, rendered as-is, or called with the boundary's QueryErrorResetBoundaryValue
+if `children` is a function.
+
+## Example
+
+```tsx
+import { useErrorBoundary } from 'preact/hooks'
+import type { ComponentChildren } from 'preact'
+import { QueryErrorResetBoundary } from '@tanstack/preact-query'
+
+function ErrorBoundary({
+  children,
+  reset,
+}: {
+  children: ComponentChildren
+  reset: () => void
+}) {
+  const [error, resetError] = useErrorBoundary(() => reset())
+
+  if (error) {
+    return (
+      <div>
+        There was an error!
+        <button onClick={() => resetError()}>Try again</button>
+      </div>
+    )
+  }
+
+  return children
+}
+
+const App = () => (
+  <QueryErrorResetBoundary>
+    {({ reset }) => (
+      <ErrorBoundary reset={reset}>
+        <Page />
+      </ErrorBoundary>
+    )}
+  </QueryErrorResetBoundary>
+)
+```

docs/framework/preact/reference/functions/infiniteQueryOptions.md

@@ -9,7 +9,13 @@ title: infiniteQueryOptions
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:76](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L76)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:122](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L122)
+
+You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
+These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
+`options.queryKey` is required and is the query key to generate options for.
+
+This overload is selected when `initialData` is set.
 
 ### Type Parameters
 
@@ -39,17 +45,42 @@ Defined in: [preact-query/src/infiniteQueryOptions.ts:76](https://github.com/Tan
 
 [`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
 
+The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfiniteOptions.md) to use — everything you can pass to `useInfiniteQuery`, with `initialData` set.
+
 ### Returns
 
-[`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `InfiniteData`\<`TQueryFnData`, `unknown`\>, `TError`\>
+The same options object, typed so that `queryKey` carries the inferred data type.
+
+### Example
+
+```tsx
+import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+
+export const projectsOptions = infiniteQueryOptions({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
+  initialPageParam: 0,
+  getNextPageParam: (lastPage) => lastPage.nextId,
+  initialData: { pages: [], pageParams: [] },
+})
+
+function Projects() {
+  const { data } = useInfiniteQuery(projectsOptions)
+  return <>{data.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+}
+```
 
 ## Call Signature
 
 ```ts
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): OmitKeyof<UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, "queryFn"> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:99](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L99)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:194](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L194)
+
+You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
+These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
+`options.queryKey` is required and is the query key to generate options for.
 
 ### Type Parameters
 
@@ -79,17 +110,63 @@ Defined in: [preact-query/src/infiniteQueryOptions.ts:99](https://github.com/Tan
 
 [`UnusedSkipTokenInfiniteOptions`](../type-aliases/UnusedSkipTokenInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
 
+The [UnusedSkipTokenInfiniteOptions](../type-aliases/UnusedSkipTokenInfiniteOptions.md) to use — everything you can pass to `useInfiniteQuery`.
+
 ### Returns
 
-`OmitKeyof`\<[`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>, `"queryFn"`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `InfiniteData`\<`TQueryFnData`, `unknown`\>, `TError`\>
+The same options object, typed so that `queryKey` carries the inferred data type.
+
+### Examples
+
+```tsx
+import { infiniteQueryOptions } from '@tanstack/preact-query'
+
+export const projectsOptions = infiniteQueryOptions({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
+  initialPageParam: 0,
+  getNextPageParam: (lastPage) => lastPage.nextId,
+})
+```
+
+A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+```tsx
+import { noop } from '@tanstack/query-core'
+import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+
+export const commentsOptions = (postId: string) =>
+  infiniteQueryOptions({
+    queryKey: ['post', postId, 'comments'],
+    queryFn: ({ pageParam }) => fetchComments(postId, pageParam),
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextId,
+  })
+
+function Comments({ postId }: { postId: string }) {
+  const result = useInfiniteQuery(commentsOptions(postId))
+  if (!result.isSuccess) return 'Loading...'
+  return (
+    <>
+      {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
+    </>
+  )
+}
+
+// Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
+queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
+```
 
 ## Call Signature
 
 ```ts
 function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(options): UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & object & QueryKeyWithDataTag<TQueryKey, InfiniteData<TQueryFnData, unknown>, TError>;
 ```
 
-Defined in: [preact-query/src/infiniteQueryOptions.ts:122](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L122)
+Defined in: [preact-query/src/infiniteQueryOptions.ts:266](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L266)
+
+You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`.
+These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`.
+`options.queryKey` is required and is the query key to generate options for.
 
 ### Type Parameters
 
@@ -119,6 +196,48 @@ Defined in: [preact-query/src/infiniteQueryOptions.ts:122](https://github.com/Ta
 
 [`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>
 
+The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to `useInfiniteQuery`.
+
 ### Returns
 
-[`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & `QueryKeyWithDataTag`\<`TQueryKey`, `InfiniteData`\<`TQueryFnData`, `unknown`\>, `TError`\>
+The same options object, typed so that `queryKey` carries the inferred data type.
+
+### Examples
+
+```tsx
+import { infiniteQueryOptions } from '@tanstack/preact-query'
+
+export const projectsOptions = infiniteQueryOptions({
+  queryKey: ['projects'],
+  queryFn: ({ pageParam }) => fetchProjects(pageParam),
+  initialPageParam: 0,
+  getNextPageParam: (lastPage) => lastPage.nextId,
+})
+```
+
+A parameterized factory, reused across a hook and an imperative call with the same cache entry:
+```tsx
+import { noop } from '@tanstack/query-core'
+import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
+
+export const commentsOptions = (postId: string) =>
+  infiniteQueryOptions({
+    queryKey: ['post', postId, 'comments'],
+    queryFn: ({ pageParam }) => fetchComments(postId, pageParam),
+    initialPageParam: 0,
+    getNextPageParam: (lastPage) => lastPage.nextId,
+  })
+
+function Comments({ postId }: { postId: string }) {
+  const result = useInfiniteQuery(commentsOptions(postId))
+  if (!result.isSuccess) return 'Loading...'
+  return (
+    <>
+      {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
+    </>
+  )
+}
+
+// Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
+queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
+```