@godxjp/ui 19.1.0 → 19.2.0

package/docs/query/mutation-feedback.tsx

@@ -0,0 +1,70 @@
+import { useEffect } from "react";
+
+import { QueryClient, QueryClientProvider, useMutation } from "@tanstack/react-query";
+
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
+import { FormField, Input } from "@godxjp/ui/data-entry";
+import { Button } from "@godxjp/ui/general";
+import { Flex, PageContainer } from "@godxjp/ui/layout";
+import { AlertMutationFeedback } from "@godxjp/ui/query";
+
+/**
+ * AlertMutationFeedback · inline mutation error below a form's submit. Renders
+ * NOTHING while idle/successful; surfaces the error + a retry when useMutation
+ * fails. Composed from real @godxjp/ui + @tanstack/react-query. (This demo fires
+ * the mutation once on mount so the error state is visible.)
+ */
+const queryClient = new QueryClient();
+
+function Block() {
+  const mutation = useMutation({
+    mutationFn: async () => {
+      throw new Error("保存に失敗しました (422) · 取引先コードが重複しています");
+    },
+  });
+
+  useEffect(() => {
+    mutation.mutate();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle level={2}>取引先の登録</CardTitle>
+        <CardDescription>The feedback sits between the form and the submit button.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <Flex direction="col" gap="md">
+          <FormField id="code" label="取引先コード">
+            <Input id="code" defaultValue="BTY-0012" />
+          </FormField>
+          <AlertMutationFeedback mutation={mutation} onRetry={() => mutation.mutate()} />
+          <Flex direction="row" wrap justify="end" gap="sm">
+            <Button variant="outline" type="button">
+              キャンセル
+            </Button>
+            <Button type="submit" disabled={mutation.isPending} onClick={() => mutation.mutate()}>
+              保存
+            </Button>
+          </Flex>
+        </Flex>
+      </CardContent>
+    </Card>
+  );
+}
+
+export default function Demo() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <PageContainer
+        title="AlertMutationFeedback"
+        subtitle="Inline useMutation error + retry, below a submit button"
+      >
+        <Flex direction="col" gap="lg">
+          <Block />
+        </Flex>
+      </PageContainer>
+    </QueryClientProvider>
+  );
+}

package/docs/query/prefetch-link.tsx

@@ -0,0 +1,262 @@
+import * as React from "react";
+import { QueryClient, QueryClientProvider, useQuery, useQueryClient } from "@tanstack/react-query";
+
+import {
+  Badge,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Descriptions,
+  EmptyState,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@godxjp/ui/data-display";
+import { Flex, PageContainer } from "@godxjp/ui/layout";
+import { PrefetchLink } from "@godxjp/ui/query";
+
+/**
+ * PrefetchLink · a React Router Link that fires queryClient.prefetchQuery on
+ * hover/focus so the detail page renders instantly on click. Requires a
+ * QueryClientProvider (and a Router) in context. The queryKey/queryFn must match
+ * the destination page's useQuery. The `prefetchOn` prop selects the trigger:
+ * "both" (default) | "hover" | "focus" | "none". Composed from real @godxjp/ui +
+ * @tanstack/react-query + react-router-dom.
+ */
+const queryClient = new QueryClient();
+
+type Invoice = { id: string; partner: string; status: "active" | "pending" | "draft" };
+const invoices: Invoice[] = [
+  { id: "INV-0312", partner: "株式会社ベトヤ", status: "active" },
+  { id: "INV-0311", partner: "ハノイ物流", status: "pending" },
+  { id: "INV-0310", partner: "GMO決済", status: "draft" },
+];
+
+const invoiceById = (id: string) => invoices.find((inv) => inv.id === id)!;
+
+/** Destination-page query: a deliberate delay so prefetch (vs cold fetch) is observable. */
+async function fetchInvoice(id: string): Promise<Invoice> {
+  await new Promise((resolve) => setTimeout(resolve, 1200));
+  return invoiceById(id);
+}
+
+const invoiceQueryKey = (id: string) => ["invoice", id] as const;
+
+/** List rows · hover/focus a 請求書番号 to prime ["invoice", id]. */
+function InvoiceList() {
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead>請求書番号</TableHead>
+          <TableHead>取引先</TableHead>
+          <TableHead>状態</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {invoices.map((inv) => (
+          <TableRow key={inv.id}>
+            <TableCell>
+              <PrefetchLink
+                to={`/invoices/${inv.id}`}
+                queryKey={invoiceQueryKey(inv.id)}
+                queryFn={() => fetchInvoice(inv.id)}
+                staleTime={60_000}
+                className="text-primary font-medium hover:underline"
+              >
+                {inv.id}
+              </PrefetchLink>
+            </TableCell>
+            <TableCell>{inv.partner}</TableCell>
+            <TableCell>
+              <Badge status={inv.status} />
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+
+/**
+ * Every prefetchOn union value, labelled. "none" never prefetches; "hover" and
+ * "focus" prime only on that trigger; "both" (the default) primes on either.
+ */
+const triggerCases: { value: "hover" | "focus" | "both" | "none"; id: string; copy: string }[] = [
+  { value: "both", id: "INV-0312", copy: "既定。ホバーまたはフォーカスで先読み" },
+  { value: "hover", id: "INV-0311", copy: "ホバー時のみ先読み" },
+  { value: "focus", id: "INV-0310", copy: "キーボードのフォーカス時のみ先読み" },
+  { value: "none", id: "INV-0312", copy: "先読みを無効化（通常の Link）" },
+];
+
+function TriggerMatrix() {
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead>prefetchOn</TableHead>
+          <TableHead>リンク</TableHead>
+          <TableHead>挙動</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {triggerCases.map((c) => (
+          <TableRow key={c.value}>
+            <TableCell>
+              <Badge variant="outline">{c.value}</Badge>
+            </TableCell>
+            <TableCell>
+              <PrefetchLink
+                to={`/invoices/${c.id}`}
+                prefetchOn={c.value}
+                queryKey={invoiceQueryKey(c.id)}
+                queryFn={() => fetchInvoice(c.id)}
+                className="text-primary font-medium hover:underline"
+              >
+                {c.id}
+              </PrefetchLink>
+            </TableCell>
+            <TableCell>{c.copy}</TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+
+/**
+ * Observable proof · reads the QueryClient cache directly and lists every
+ * ["invoice", id] entry the links above have primed. Updates as you hover/focus.
+ */
+function CacheObserver() {
+  const client = useQueryClient();
+  const [, forceRender] = React.useReducer((n: number) => n + 1, 0);
+
+  React.useEffect(() => client.getQueryCache().subscribe(forceRender), [client]);
+
+  const cached = client
+    .getQueryCache()
+    .getAll()
+    .filter((q) => Array.isArray(q.queryKey) && q.queryKey[0] === "invoice");
+
+  if (cached.length === 0) {
+    return (
+      <EmptyState
+        title="まだ先読みされていません"
+        description="上のリンクにホバーまたはフォーカスしてください。"
+      />
+    );
+  }
+
+  return (
+    <Descriptions columns={1}>
+      {cached.map((q) => (
+        <Descriptions.Item
+          key={JSON.stringify(q.queryKey)}
+          label={<Badge variant="outline">{JSON.stringify(q.queryKey)}</Badge>}
+          mono
+        >
+          {q.state.status === "success" ? "キャッシュ済み (cached)" : "先読み中… (fetching)"}
+        </Descriptions.Item>
+      ))}
+    </Descriptions>
+  );
+}
+
+/**
+ * Destination block · the SAME queryKey/queryFn contract as the list link.
+ * Because the link already primed ["invoice", "INV-0312"], this useQuery resolves
+ * from cache (no skeleton) instead of paying the 1.2s fetch.
+ */
+function DestinationDetail() {
+  const query = useQuery({
+    queryKey: invoiceQueryKey("INV-0312"),
+    queryFn: () => fetchInvoice("INV-0312"),
+    staleTime: 60_000,
+  });
+
+  if (query.isPending) {
+    return <EmptyState title="読み込み中…" description="先読みが間に合えば即時表示されます。" />;
+  }
+
+  const inv = query.data!;
+  return (
+    <Descriptions columns={1}>
+      <Descriptions.Item label="請求書番号" mono>
+        {inv.id}
+      </Descriptions.Item>
+      <Descriptions.Item label="取引先">{inv.partner}</Descriptions.Item>
+      <Descriptions.Item label="状態">
+        <Badge status={inv.status} />
+      </Descriptions.Item>
+    </Descriptions>
+  );
+}
+
+export default function Demo() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      {/* The preview/isolate harness already provides a Router; PrefetchLink reads it from context. */}
+      <PageContainer
+        title="PrefetchLink"
+        subtitle="Router Link that prefetches the destination query on hover/focus"
+      >
+        <Flex direction="col" gap="lg">
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>請求書 一覧</CardTitle>
+              <CardDescription>
+                請求書番号にホバーまたはフォーカスすると、その明細クエリが先読みされ次の画面が即時表示されます。
+              </CardDescription>
+            </CardHeader>
+            <CardContent flush>
+              <InvoiceList />
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>prefetchOn · トリガーの種類</CardTitle>
+              <CardDescription>
+                既定は both。hover / focus / none で先読みのきっかけを切り替えます。
+              </CardDescription>
+            </CardHeader>
+            <CardContent flush>
+              <TriggerMatrix />
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>先読みキャッシュ（観測）</CardTitle>
+              <CardDescription>
+                QueryClient のキャッシュから ["invoice", id] を直接読み出して表示します。
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <CacheObserver />
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>遷移先の明細（契約）</CardTitle>
+              <CardDescription>
+                リンクと同じ queryKey/queryFn を使う
+                useQuery。先読み済みならキャッシュから即時解決します。
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <DestinationDetail />
+            </CardContent>
+          </Card>
+        </Flex>
+      </PageContainer>
+    </QueryClientProvider>
+  );
+}

package/docs/query/touch-actions.tsx

@@ -0,0 +1,68 @@
+import { useState } from "react";
+import {
+  AlertMutationFeedback,
+  ButtonRefetch,
+  DataState,
+  InfiniteQueryState,
+} from "@godxjp/ui/query";
+import { PageContainer } from "@godxjp/ui/layout";
+
+export default function Demo() {
+  const [retry, setRetry] = useState(0);
+  const [more, setMore] = useState(0);
+  const [mutation, setMutation] = useState(0);
+  const [refresh, setRefresh] = useState(0);
+  const errorQuery = {
+    isPending: false,
+    isError: true,
+    isFetching: false,
+    error: new Error("503 Service unavailable"),
+    refetch: async () => ({}),
+  } as never;
+  const infinite = {
+    isPending: false,
+    isError: false,
+    isFetching: false,
+    isFetchingNextPage: false,
+    data: { pages: [{ items: ["one"] }], pageParams: [0] },
+    hasNextPage: true,
+    fetchNextPage: async () => {
+      setMore((n) => n + 1);
+      return {} as never;
+    },
+  } as never;
+  return (
+    <PageContainer title="Query touch actions">
+      <DataState query={errorQuery} skeleton={null} onRetry={() => setRetry((n) => n + 1)}>
+        {() => null}
+      </DataState>
+      <output aria-label="Retry result">{retry}</output>
+      <InfiniteQueryState
+        query={infinite}
+        skeleton={null}
+        flatten={(data: { pages: { items: string[] }[] }) => data.pages.flatMap((p) => p.items)}
+      >
+        {() => null}
+      </InfiniteQueryState>
+      <output aria-label="Load more result">{more}</output>
+      <AlertMutationFeedback
+        mutation={{ isPending: false, isError: true, error: new Error("503") } as never}
+        onRetry={() => setMutation((n) => n + 1)}
+      />
+      <output aria-label="Mutation result">{mutation}</output>
+      <ButtonRefetch
+        query={
+          {
+            isFetching: false,
+            refetch: async () => {
+              setRefresh((n) => n + 1);
+              return {} as never;
+            },
+          } as never
+        }
+        label="Refresh touch"
+      />
+      <output aria-label="Refresh result">{refresh}</output>
+    </PageContainer>
+  );
+}