Lit query docs

.changeset/lemon-memes-divide.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/lit-query': minor
+---
+
+Add initial @tanstack/lit-query package

.gitignore

@@ -10,6 +10,7 @@ yarn.lock
 build
 coverage
 dist
+dist-cjs
 dist-ts
 
 # misc

docs/config.json

@@ -135,6 +135,27 @@
             }
           ]
         },
+        {
+          "label": "lit",
+          "children": [
+            {
+              "label": "Overview",
+              "to": "framework/lit/overview"
+            },
+            {
+              "label": "Installation",
+              "to": "framework/lit/installation"
+            },
+            {
+              "label": "Quick Start",
+              "to": "framework/lit/quick-start"
+            },
+            {
+              "label": "TypeScript",
+              "to": "framework/lit/typescript"
+            }
+          ]
+        },
         {
           "label": "angular",
           "children": [
@@ -759,6 +780,47 @@
             }
           ]
         },
+        {
+          "label": "lit",
+          "children": [
+            {
+              "label": "Reactive Controllers vs Hooks",
+              "to": "framework/lit/guides/reactive-controllers-vs-hooks"
+            },
+            {
+              "label": "Queries",
+              "to": "framework/lit/guides/queries"
+            },
+            {
+              "label": "Parallel Queries",
+              "to": "framework/lit/guides/parallel-queries"
+            },
+            {
+              "label": "Query Keys",
+              "to": "framework/lit/guides/query-keys"
+            },
+            {
+              "label": "Query Functions",
+              "to": "framework/lit/guides/query-functions"
+            },
+            {
+              "label": "Mutations",
+              "to": "framework/lit/guides/mutations"
+            },
+            {
+              "label": "Query Invalidation",
+              "to": "framework/lit/guides/query-invalidation"
+            },
+            {
+              "label": "Infinite Queries",
+              "to": "framework/lit/guides/infinite-queries"
+            },
+            {
+              "label": "SSR",
+              "to": "framework/lit/guides/ssr"
+            }
+          ]
+        },
         {
           "label": "preact",
           "children": [
@@ -1183,6 +1245,83 @@
             }
           ]
         },
+        {
+          "label": "lit",
+          "children": [
+            {
+              "label": "Lit Reference",
+              "to": "framework/lit/reference/index"
+            },
+            {
+              "label": "QueryClientProvider",
+              "to": "framework/lit/reference/classes/QueryClientProvider"
+            },
+            {
+              "label": "Functions / createQueryController",
+              "to": "framework/lit/reference/functions/createQueryController"
+            },
+            {
+              "label": "Functions / createQueriesController",
+              "to": "framework/lit/reference/functions/createQueriesController"
+            },
+            {
+              "label": "Functions / createInfiniteQueryController",
+              "to": "framework/lit/reference/functions/createInfiniteQueryController"
+            },
+            {
+              "label": "Functions / createMutationController",
+              "to": "framework/lit/reference/functions/createMutationController"
+            },
+            {
+              "label": "Functions / useIsFetching",
+              "to": "framework/lit/reference/functions/useIsFetching"
+            },
+            {
+              "label": "Functions / useIsMutating",
+              "to": "framework/lit/reference/functions/useIsMutating"
+            },
+            {
+              "label": "Functions / useMutationState",
+              "to": "framework/lit/reference/functions/useMutationState"
+            },
+            {
+              "label": "Functions / useQueryClient",
+              "to": "framework/lit/reference/functions/useQueryClient"
+            },
+            {
+              "label": "Functions / queryOptions",
+              "to": "framework/lit/reference/functions/queryOptions"
+            },
+            {
+              "label": "Functions / infiniteQueryOptions",
+              "to": "framework/lit/reference/functions/infiniteQueryOptions"
+            },
+            {
+              "label": "Functions / mutationOptions",
+              "to": "framework/lit/reference/functions/mutationOptions"
+            },
+            {
+              "label": "Context / queryClientContext",
+              "to": "framework/lit/reference/variables/queryClientContext"
+            },
+            {
+              "label": "Context / getDefaultQueryClient",
+              "to": "framework/lit/reference/functions/getDefaultQueryClient"
+            },
+            {
+              "label": "Context / registerDefaultQueryClient",
+              "to": "framework/lit/reference/functions/registerDefaultQueryClient"
+            },
+            {
+              "label": "Context / unregisterDefaultQueryClient",
+              "to": "framework/lit/reference/functions/unregisterDefaultQueryClient"
+            },
+            {
+              "label": "Context / resolveQueryClient",
+              "to": "framework/lit/reference/functions/resolveQueryClient"
+            }
+          ]
+        },
         {
           "label": "angular",
           "children": [
@@ -1532,6 +1671,23 @@
             }
           ]
         },
+        {
+          "label": "lit",
+          "children": [
+            {
+              "label": "Basic",
+              "to": "framework/lit/examples/basic"
+            },
+            {
+              "label": "Pagination",
+              "to": "framework/lit/examples/pagination"
+            },
+            {
+              "label": "SSR",
+              "to": "framework/lit/examples/ssr"
+            }
+          ]
+        },
         {
           "label": "angular",
           "children": [

docs/framework/lit/guides/infinite-queries.md

@@ -0,0 +1,87 @@
+---
+id: infinite-queries
+title: Infinite Queries
+---
+
+Infinite queries are for lists that load more data into one cache entry. Use [`createInfiniteQueryController`](../reference/functions/createInfiniteQueryController.md).
+
+An infinite query result contains:
+
+- `data.pages`: fetched pages
+- `data.pageParams`: page parameters used for those pages
+- `fetchNextPage` and `fetchPreviousPage`
+- `hasNextPage` and `hasPreviousPage`
+- `isFetchingNextPage` and `isFetchingPreviousPage`
+
+## Load More Example
+
+```ts
+import { LitElement, html } from 'lit'
+import { createInfiniteQueryController } from '@tanstack/lit-query'
+
+class ProjectsList extends LitElement {
+  private readonly projects = createInfiniteQueryController(this, {
+    queryKey: ['projects'],
+    queryFn: ({ pageParam }) => fetchProjectsPage(pageParam),
+    initialPageParam: 1,
+    getNextPageParam: (lastPage) =>
+      lastPage.hasMore ? lastPage.page + 1 : undefined,
+  })
+
+  render() {
+    const query = this.projects()
+
+    if (query.isPending) return html`Loading...`
+    if (query.isError) return html`Error: ${query.error.message}`
+
+    return html`
+      ${query.data.pages.map(
+        (page) => html`
+          ${page.projects.map((project) => html`<p>${project.name}</p>`)}
+        `,
+      )}
+
+      <button
+        ?disabled=${!query.hasNextPage || query.isFetching}
+        @click=${() => this.projects.fetchNextPage()}
+      >
+        ${query.isFetchingNextPage
+          ? 'Loading more...'
+          : query.hasNextPage
+            ? 'Load More'
+            : 'Nothing more to load'}
+      </button>
+    `
+  }
+}
+```
+
+## Page Parameters
+
+`initialPageParam` is required. `getNextPageParam` decides whether another page exists and what value should be passed as `pageParam` to the next query function call.
+
+```ts
+createInfiniteQueryController(this, {
+  queryKey: ['projects'],
+  queryFn: ({ pageParam }) => fetchProjectsPage(pageParam),
+  initialPageParam: 1,
+  getNextPageParam: (lastPage) =>
+    lastPage.hasMore ? lastPage.page + 1 : undefined,
+})
+```
+
+Returning `undefined` or `null` means there is no next page.
+
+## Avoid Overlapping Fetches
+
+There is one ongoing fetch for an infinite query cache entry. If you call `fetchNextPage` while a background refetch is running, you can overwrite data. Disable the button or check `!query.isFetching` before loading more:
+
+```ts
+if (query.hasNextPage && !query.isFetching) {
+  this.projects.fetchNextPage()
+}
+```
+
+## Paginated Alternative
+
+If your UI shows one page at a time, a normal query with a page in the key can be a better fit. The [Pagination example](../examples/pagination) uses `createQueryController`, `placeholderData: keepPreviousData`, prefetching, and mutations to demonstrate that pattern.