docs-i18n 0.8.1 → 0.8.2

package/template/content/form/zh-hans/overview.md

@@ -0,0 +1,71 @@
+---
+title: TanStack Form 概览
+description: 无头、高性能、类型安全的表单状态管理
+---
+
+# TanStack Form
+
+TanStack Form 是一个无头、高性能、类型安全的表单状态管理库，支持 TS/JS、React、Vue 和 Angular。
+
+## 为什么选择 TanStack Form？
+
+大多数表单库要么为了便利牺牲了类型安全，要么与特定框架紧密耦合。TanStack Form 两者兼顾——从表单值到验证错误的完整类型安全，并提供 React、Vue 和 Angular 的适配器。
+
+## 特性
+
+- **类型安全** — 表单值、字段名称和验证的完整 TypeScript 推断
+- **框架无关** — 支持 React、Vue、Angular 等
+- **无头** — 无 UI 限制，使用你自己的组件
+- **高性能** — 字段级订阅，无不必要的重渲染
+- **验证** — 内置同步和异步验证，支持 Zod、Valibot 和 Yup 适配器
+- **数组和动态字段** — 一流的数组字段支持
+
+## 基本示例
+
+```tsx
+import { useForm } from '@tanstack/react-form'
+
+function SignupForm() {
+  const form = useForm({
+    defaultValues: {
+      firstName: '',
+      lastName: '',
+      email: '',
+    },
+    onSubmit: async ({ value }) => {
+      console.log(value)
+    },
+  })
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault()
+        form.handleSubmit()
+      }}
+    >
+      <form.Field
+        name="firstName"
+        validators={{
+          onChange: ({ value }) =>
+            !value ? 'First name is required' : undefined,
+        }}
+      >
+        {(field) => (
+          <div>
+            <label>First Name</label>
+            <input
+              value={field.state.value}
+              onChange={(e) => field.handleChange(e.target.value)}
+            />
+            {field.state.meta.errors.length > 0 && (
+              <span>{field.state.meta.errors.join(', ')}</span>
+            )}
+          </div>
+        )}
+      </form.Field>
+      <button type="submit">Submit</button>
+    </form>
+  )
+}
+```

package/template/content/query/docs.config.json

@@ -0,0 +1,32 @@
+{
+  "sections": [
+    {
+      "label": "Getting Started",
+      "children": [
+        { "label": "Overview", "to": "overview" },
+        { "label": "Installation", "to": "installation" },
+        { "label": "Quick Start", "to": "quick-start" }
+      ]
+    },
+    {
+      "label": "Guides",
+      "children": [
+        { "label": "Queries", "to": "guides/queries" },
+        { "label": "Pagination", "to": "guides/pagination" },
+        { "label": "Mutations", "to": "guides/mutations" }
+      ]
+    },
+    {
+      "label": "React",
+      "frameworks": [
+        {
+          "label": "React",
+          "children": [
+            { "label": "Overview", "to": "overview" },
+            { "label": "Quick Start", "to": "quick-start" }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/template/content/query/en/guides/mutations.md

@@ -0,0 +1,126 @@
+---
+title: Mutations
+description: Learn how to create, update, and delete data with TanStack Query mutations
+---
+
+# Mutations
+
+Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects. For this purpose, TanStack Query exports a `useMutation` hook.
+
+## Basic Mutation
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+
+function AddTodo() {
+  const queryClient = useQueryClient()
+
+  const mutation = useMutation({
+    mutationFn: (newTodo: { title: string }) => {
+      return fetch('/api/todos', {
+        method: 'POST',
+        body: JSON.stringify(newTodo),
+        headers: { 'Content-Type': 'application/json' },
+      }).then((res) => res.json())
+    },
+    onSuccess: () => {
+      // Invalidate and refetch the todos list
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+
+  return (
+    <button
+      onClick={() => mutation.mutate({ title: 'New Todo' })}
+      disabled={mutation.isPending}
+    >
+      {mutation.isPending ? 'Adding...' : 'Add Todo'}
+    </button>
+  )
+}
+```
+
+## Mutation States
+
+A mutation can only be in one of the following states at any given moment:
+
+| State | Description |
+|---|---|
+| `isIdle` | The mutation is idle or in a fresh/reset state |
+| `isPending` | The mutation is currently running |
+| `isError` | The mutation encountered an error |
+| `isSuccess` | The mutation was successful and data is available |
+
+## Optimistic Updates
+
+Optimistic updates allow you to update the UI before the server confirms the mutation, providing a snappier user experience:
+
+```tsx
+const mutation = useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    // Cancel any outgoing refetches to avoid overwriting optimistic update
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+
+    // Snapshot the previous value
+    const previousTodos = queryClient.getQueryData(['todos'])
+
+    // Optimistically update to the new value
+    queryClient.setQueryData(['todos'], (old: Todo[]) => [
+      ...old,
+      { ...newTodo, id: Date.now() },
+    ])
+
+    // Return a context object with the snapshotted value
+    return { previousTodos }
+  },
+  onError: (_err, _newTodo, context) => {
+    // Roll back to the previous value on error
+    queryClient.setQueryData(['todos'], context?.previousTodos)
+  },
+  onSettled: () => {
+    // Always refetch after error or success
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+```
+
+> [!NOTE]
+> The `onMutate` handler runs before the mutation function and receives the same variables. It is the perfect place to perform optimistic updates.
+
+## Retry
+
+By default, TanStack Query will not retry failed mutations. You can configure this per-mutation:
+
+```tsx
+const mutation = useMutation({
+  mutationFn: addTodo,
+  retry: 3, // Retry failed mutations 3 times
+})
+```
+
+## Mutation Callbacks
+
+The `useMutation` hook supports several callback options:
+
+```tsx
+useMutation({
+  mutationFn: addTodo,
+  onMutate: (variables) => {
+    // Called before the mutation function fires
+    // Receives the same variables the mutation function would receive
+  },
+  onError: (error, variables, context) => {
+    // Called if the mutation encounters an error
+  },
+  onSuccess: (data, variables, context) => {
+    // Called if the mutation is successful
+  },
+  onSettled: (data, error, variables, context) => {
+    // Called regardless of success or error
+  },
+})
+```
+
+> [!WARNING]
+> The callbacks on `useMutation` fire for every component instance that uses it. To ensure side-effects only run once, use the callbacks on the `mutate` function or move the mutation to a shared hook.

package/template/content/query/en/guides/pagination.md

@@ -0,0 +1,98 @@
+---
+title: Pagination
+description: Learn how to implement paginated queries with TanStack Query
+---
+
+# Pagination
+
+Rendering paginated data is a very common UI pattern and in TanStack Query, it "just works" by including the page information in the query key.
+
+## Basic Pagination Example
+
+```tsx
+const fetchProjects = async (page: number) => {
+  const res = await fetch(`/api/projects?page=${page}`)
+  return res.json()
+}
+
+function Projects() {
+  const [page, setPage] = React.useState(1)
+
+  const { data, isPreviousData, isLoading } = useQuery({
+    queryKey: ['projects', page],
+    queryFn: () => fetchProjects(page),
+    placeholderData: keepPreviousData,
+  })
+
+  return (
+    <div>
+      {isLoading ? (
+        <div>Loading...</div>
+      ) : (
+        <>
+          {data.projects.map((project) => (
+            <p key={project.id}>{project.name}</p>
+          ))}
+        </>
+      )}
+      <div className="flex gap-2">
+        <button
+          onClick={() => setPage((old) => Math.max(old - 1, 1))}
+          disabled={page === 1}
+        >
+          Previous
+        </button>
+        <span>Page {page}</span>
+        <button
+          onClick={() => {
+            if (!isPreviousData && data.hasMore) {
+              setPage((old) => old + 1)
+            }
+          }}
+          disabled={isPreviousData || !data?.hasMore}
+        >
+          Next
+        </button>
+      </div>
+    </>
+  )
+}
+```
+
+## Using `keepPreviousData`
+
+The `keepPreviousData` option is crucial for smooth pagination. When enabled, the data from the last successful fetch is available while new data is being requested, even when the query key changes.
+
+> [!NOTE]
+> `keepPreviousData` was renamed from `previousData` in v5. If you are migrating from v4, update your code accordingly.
+
+## Prefetching Next Pages
+
+For an even smoother UX, you can prefetch the next page before the user navigates to it:
+
+```tsx
+const queryClient = useQueryClient()
+
+React.useEffect(() => {
+  if (data?.hasMore) {
+    queryClient.prefetchQuery({
+      queryKey: ['projects', page + 1],
+      queryFn: () => fetchProjects(page + 1),
+    })
+  }
+}, [data, page, queryClient])
+```
+
+## Infinite Queries
+
+For "load more" and infinite scroll patterns, TanStack Query provides the `useInfiniteQuery` hook. See the [Infinite Queries guide](/en/query/docs/guides/infinite-queries) for details.
+
+| Feature | `useQuery` + pagination | `useInfiniteQuery` |
+|---|---|---|
+| Page navigation | Previous / Next buttons | Load More / Infinite Scroll |
+| Data structure | Single page | Accumulated pages |
+| Memory usage | Lower (one page) | Higher (all loaded pages) |
+| URL sync | Easy | More complex |
+
+> [!WARNING]
+> Do not use `useInfiniteQuery` for traditional page-based navigation. It is designed for "load more" patterns where previously loaded data stays visible.

package/template/content/query/en/guides/queries.md

@@ -0,0 +1,120 @@
+---
+title: Queries
+description: Learn how queries work in TanStack Query
+---
+
+# 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.
+
+## Query Basics
+
+To subscribe to a query in your components, call the query hook with at least a unique key and a function that returns a promise:
+
+<!-- ::start:react -->
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+
+function Example() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodoList,
+  })
+}
+```
+
+<!-- ::end:react -->
+
+<!-- ::start:vue -->
+
+```vue
+<script setup>
+import { useQuery } from '@tanstack/vue-query'
+
+const { data, isLoading, error } = useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodoList,
+})
+</script>
+```
+
+<!-- ::end:vue -->
+
+<!-- ::start:solid -->
+
+```tsx
+import { createQuery } from '@tanstack/solid-query'
+
+function Example() {
+  const query = createQuery(() => ({
+    queryKey: ['todos'],
+    queryFn: fetchTodoList,
+  }))
+}
+```
+
+<!-- ::end:solid -->
+
+## Query Keys
+
+Query keys are used to uniquely identify a query. They can be as simple as a string, or as complex as an array of many strings and nested objects:
+
+```ts
+// A simple string key
+useQuery({ queryKey: ['todos'], ... })
+
+// A key with variables
+useQuery({ queryKey: ['todo', todoId], ... })
+
+// A key with an object
+useQuery({ queryKey: ['todos', { type: 'done', page: 1 }], ... })
+```
+
+## Query Functions
+
+A query function can be literally any function that returns a promise. The promise that is returned should either resolve the data or throw an error:
+
+```ts
+const { data } = useQuery({
+  queryKey: ['todos'],
+  queryFn: async () => {
+    const response = await fetch('/api/todos')
+    if (!response.ok) {
+      throw new Error('Network response was not ok')
+    }
+    return response.json()
+  },
+})
+```
+
+## Query States
+
+A query can be in one of the following states at any given moment:
+
+- **`isPending`** — The query has no data yet
+- **`isError`** — The query encountered an error
+- **`isSuccess`** — The query was successful and data is available
+
+```tsx
+function Todos() {
+  const { data, isPending, isError, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  })
+
+  if (isPending) return <span>Loading...</span>
+  if (isError) return <span>Error: {error.message}</span>
+
+  return (
+    <ul>
+      {data.map((todo) => (
+        <li key={todo.id}>{todo.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+> [!NOTE]
+> In TanStack Query v5, `isLoading` has been renamed to `isPending` for consistency.

package/template/content/query/en/installation.md

@@ -0,0 +1,78 @@
+---
+title: Installation
+description: How to install TanStack Query in your project
+---
+
+# Installation
+
+TanStack Query is available as a package on npm for each supported framework.
+
+## Install the Package
+
+Choose the package for your framework:
+
+### React
+
+```bash
+npm install @tanstack/react-query
+```
+
+```bash
+pnpm add @tanstack/react-query
+```
+
+```bash
+yarn add @tanstack/react-query
+```
+
+```bash
+bun add @tanstack/react-query
+```
+
+### Vue
+
+```bash
+npm install @tanstack/vue-query
+```
+
+### Solid
+
+```bash
+npm install @tanstack/solid-query
+```
+
+### Svelte
+
+```bash
+npm install @tanstack/svelte-query
+```
+
+### Angular
+
+```bash
+npm install @tanstack/angular-query-experimental
+```
+
+## Requirements
+
+- TypeScript 4.7+ (for type inference)
+- React 18+ / Vue 3+ / Solid 1.6+ / Svelte 4+
+
+## Devtools
+
+We recommend also installing the devtools for a better development experience:
+
+```bash
+npm install @tanstack/react-query-devtools
+```
+
+> [!NOTE]
+> Devtools are currently only available for React. Community devtools exist for other frameworks.
+
+## CDN
+
+For prototyping, you can load TanStack Query from a CDN:
+
+```html
+<script src="https://unpkg.com/@tanstack/react-query/build/umd/index.production.js"></script>
+```

package/template/content/query/en/overview.md

@@ -0,0 +1,72 @@
+---
+title: TanStack Query Overview
+description: Powerful asynchronous state management for TS/JS, React, Vue, Solid, Svelte & Angular
+---
+
+# TanStack Query
+
+TanStack Query (formerly React Query) makes fetching, caching, synchronizing, and updating server state in your web applications a breeze.
+
+## Motivation
+
+Most core web frameworks do not come with an opinionated way of fetching or updating data in a holistic way. Developers end up building either meta-frameworks which encapsulate strict opinions about data-fetching, or they invent their own ways of fetching data. This usually means cobbling together component-based state and side-effects, or using more general purpose state management libraries to store and provide asynchronous data throughout their apps.
+
+## Features
+
+- **Transport/protocol/backend agnostic** data fetching (REST, GraphQL, promises, whatever!)
+- **Auto Caching** with request deduplication
+- **Automatic Refetching** with stale-while-revalidate strategy
+- **Window Focus Refetching** to keep data current
+- **Polling/Realtime** queries with configurable intervals
+- **Parallel & Dependent Queries** for complex data requirements
+- **Mutations** with optimistic updates
+- **Pagination & Infinite Scroll** out of the box
+- **Dedicated Devtools** for debugging
+
+## Supported Frameworks
+
+TanStack Query supports the following frameworks:
+
+```ts
+// React
+import { useQuery } from '@tanstack/react-query'
+
+// Vue
+import { useQuery } from '@tanstack/vue-query'
+
+// Solid
+import { createQuery } from '@tanstack/solid-query'
+
+// Svelte
+import { createQuery } from '@tanstack/svelte-query'
+
+// Angular
+import { injectQuery } from '@tanstack/angular-query-experimental'
+```
+
+## Quick Example
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+
+function App() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: () => fetch('/api/todos').then(res => res.json()),
+  })
+
+  if (isLoading) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
+
+  return (
+    <ul>
+      {data.map(todo => (
+        <li key={todo.id}>{todo.title}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+> [!NOTE]
+> TanStack Query v5 is the latest version and includes significant improvements over v4 including a simplified API and better TypeScript support.

package/template/content/query/en/quick-start.md

@@ -0,0 +1,108 @@
+---
+title: Quick Start
+description: Get up and running with TanStack Query in minutes
+---
+
+# Quick Start
+
+This guide will help you get started with TanStack Query as quickly as possible.
+
+## Set Up the Provider
+
+Wrap your application with `QueryClientProvider` and pass a `QueryClient` instance:
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+const queryClient = new QueryClient()
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <MyApp />
+    </QueryClientProvider>
+  )
+}
+```
+
+## Your First Query
+
+Use the `useQuery` hook to fetch data:
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+
+function Todos() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  })
+
+  if (isLoading) return <span>Loading...</span>
+  if (error) return <span>Error: {error.message}</span>
+
+  return (
+    <ul>
+      {data.map((todo) => (
+        <li key={todo.id}>{todo.title}</li>
+      ))}
+    </ul>
+  )
+}
+
+async function fetchTodos() {
+  const res = await fetch('https://jsonplaceholder.typicode.com/todos')
+  if (!res.ok) throw new Error('Failed to fetch')
+  return res.json()
+}
+```
+
+## Your First Mutation
+
+Use `useMutation` to create, update, or delete data:
+
+```tsx
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+
+function AddTodo() {
+  const queryClient = useQueryClient()
+
+  const mutation = useMutation({
+    mutationFn: (newTodo: { title: string }) =>
+      fetch('/api/todos', {
+        method: 'POST',
+        body: JSON.stringify(newTodo),
+      }).then((res) => res.json()),
+    onSuccess: () => {
+      // Invalidate and refetch
+      queryClient.invalidateQueries({ queryKey: ['todos'] })
+    },
+  })
+
+  return (
+    <button onClick={() => mutation.mutate({ title: 'New Todo' })}>
+      Add Todo
+    </button>
+  )
+}
+```
+
+## Adding Devtools
+
+Add the React Query Devtools for debugging:
+
+```tsx
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <MyApp />
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  )
+}
+```
+
+> [!NOTE]
+> Devtools are automatically excluded from production builds.