@godxjp/ui 5.0.2 → 6.0.0

package/src/components/query/__tests__/data-state.test.tsx

@@ -0,0 +1,214 @@
+import { describe, expect, it, vi } from "vitest";
+import * as React from "react";
+import { QueryClient, QueryClientProvider, useQuery } from "@tanstack/react-query";
+import type { UseQueryResult } from "@tanstack/react-query";
+import { renderWithUi, screen, userEvent, waitFor } from "@/test/render";
+import { DataState } from "../data-state";
+
+type ShipmentList = { items: number[] };
+
+function mockQuery<T>(partial: Partial<UseQueryResult<T>>): UseQueryResult<T> {
+  return partial as UseQueryResult<T>;
+}
+
+function withQueryClient(ui: React.ReactElement, client: QueryClient) {
+  return <QueryClientProvider client={client}>{ui}</QueryClientProvider>;
+}
+
+function EmptyWarehouseHarness() {
+  const query = useQuery<ShipmentList>({
+    queryKey: ["data-state-test", "empty"],
+    queryFn: () => Promise.resolve({ items: [] }),
+  });
+  return (
+    <DataState
+      query={query}
+      skeleton={<div data-testid="hawb-skeleton">loading</div>}
+      empty={<div>Không có kiện chờ gom</div>}
+      isEmpty={(data) => data.items.length === 0}
+    >
+      {(data) => <div data-testid="hawb-list">{data.items.length} kiện</div>}
+    </DataState>
+  );
+}
+
+function LoadedWarehouseHarness() {
+  const query = useQuery<ShipmentList>({
+    queryKey: ["data-state-test", "loaded"],
+    queryFn: () => Promise.resolve({ items: [1, 2] }),
+  });
+  return (
+    <DataState
+      query={query}
+      skeleton={<div data-testid="hawb-skeleton">loading</div>}
+      empty={<div>Không có kiện chờ gom</div>}
+      isEmpty={(data) => data.items.length === 0}
+    >
+      {(data) => <div data-testid="hawb-list">{data.items.length} kiện</div>}
+    </DataState>
+  );
+}
+
+describe("DataState", () => {
+  it("shows skeleton while pending", () => {
+    renderWithUi(
+      <DataState
+        query={mockQuery({ isPending: true, isError: false })}
+        skeleton={<div data-testid="skel">loading</div>}
+      >
+        {() => <div>data</div>}
+      </DataState>,
+    );
+    expect(screen.getByTestId("skel")).toBeInTheDocument();
+  });
+
+  it("renders children when data loaded", () => {
+    renderWithUi(
+      <DataState
+        query={mockQuery({ isPending: false, isError: false, data: { items: [1] } })}
+        skeleton={<div>loading</div>}
+        empty={<div>empty</div>}
+      >
+        {(data) => <div>count:{data.items.length}</div>}
+      </DataState>,
+    );
+    expect(screen.getByText("count:1")).toBeInTheDocument();
+  });
+
+  it("shows empty state when isEmpty", () => {
+    renderWithUi(
+      <DataState
+        query={mockQuery({ isPending: false, isError: false, data: { items: [] } })}
+        skeleton={<div>loading</div>}
+        empty={<div>No items</div>}
+      >
+        {() => <div>data</div>}
+      </DataState>,
+    );
+    expect(screen.getByText("No items")).toBeInTheDocument();
+  });
+
+  it("renders Alert.QueryError and refetches on retry when query errors", async () => {
+    const user = userEvent.setup();
+    const refetch = vi.fn();
+    renderWithUi(
+      <DataState
+        query={mockQuery({
+          isPending: false,
+          isError: true,
+          isFetching: false,
+          error: new Error("GET /v1/customers failed: 503"),
+          refetch,
+        })}
+        skeleton={<div data-testid="skel">loading</div>}
+      >
+        {() => <div>data</div>}
+      </DataState>,
+    );
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+    expect(screen.getByText(/503/)).toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: /thử lại/i }));
+    expect(refetch).toHaveBeenCalledOnce();
+  });
+
+  it("shows skeleton while retrying after error", () => {
+    renderWithUi(
+      <DataState
+        query={mockQuery({
+          isPending: false,
+          isError: true,
+          isFetching: true,
+          error: new Error("503"),
+        })}
+        skeleton={<div data-testid="retry-skel">loading</div>}
+      >
+        {() => <div>data</div>}
+      </DataState>,
+    );
+    expect(screen.getByTestId("retry-skel")).toBeInTheDocument();
+    expect(screen.queryByRole("alert")).not.toBeInTheDocument();
+  });
+
+  it("omits retry when showRetry is false", () => {
+    renderWithUi(
+      <DataState
+        query={mockQuery({
+          isPending: false,
+          isError: true,
+          isFetching: false,
+          error: new Error("403"),
+        })}
+        skeleton={<div>loading</div>}
+        showRetry={false}
+      >
+        {() => <div>data</div>}
+      </DataState>,
+    );
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: /thử lại/i })).not.toBeInTheDocument();
+  });
+
+  it("calls onRetry override instead of refetch", async () => {
+    const user = userEvent.setup();
+    const onRetry = vi.fn();
+    const refetch = vi.fn();
+    renderWithUi(
+      <DataState
+        query={mockQuery({
+          isPending: false,
+          isError: true,
+          isFetching: false,
+          error: new Error("fail"),
+          refetch,
+        })}
+        skeleton={<div>loading</div>}
+        onRetry={onRetry}
+      >
+        {() => <div>data</div>}
+      </DataState>,
+    );
+    await user.click(screen.getByRole("button", { name: /thử lại/i }));
+    expect(onRetry).toHaveBeenCalledOnce();
+    expect(refetch).not.toHaveBeenCalled();
+  });
+
+  it("uses custom errorRenderer when provided", () => {
+    renderWithUi(
+      <DataState
+        query={mockQuery({
+          isPending: false,
+          isError: true,
+          isFetching: false,
+          error: new Error("fail"),
+        })}
+        skeleton={<div>loading</div>}
+        errorRenderer={(err) => <div data-testid="custom-err">{String(err)}</div>}
+      >
+        {() => <div>data</div>}
+      </DataState>,
+    );
+    expect(screen.getByTestId("custom-err")).toHaveTextContent("fail");
+  });
+});
+
+describe("DataState integration (useQuery)", () => {
+  it("shows empty warehouse after query resolves", async () => {
+    const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    renderWithUi(withQueryClient(<EmptyWarehouseHarness />, client));
+
+    expect(screen.getByTestId("hawb-skeleton")).toBeInTheDocument();
+    await waitFor(() => {
+      expect(screen.getByText("Không có kiện chờ gom")).toBeInTheDocument();
+    });
+    expect(screen.queryByTestId("hawb-list")).not.toBeInTheDocument();
+  });
+
+  it("shows list when warehouse has shipments", async () => {
+    const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    renderWithUi(withQueryClient(<LoadedWarehouseHarness />, client));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("hawb-list")).toHaveTextContent("2 kiện");
+    });
+  });
+});

package/src/components/query/__tests__/infinite-prefetch.test.tsx

@@ -0,0 +1,105 @@
+import { describe, expect, it, vi } from "vitest";
+import type { InfiniteData, UseInfiniteQueryResult } from "@tanstack/react-query";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderWithUi, screen, userEvent, waitFor } from "@/test/render";
+import { InfiniteQueryState, flattenItemPages } from "../infinite-query-state";
+import { PrefetchLink } from "../prefetch-link";
+
+type Page = { items: string[]; next_cursor?: string };
+
+function mockInfiniteQuery(partial: Record<string, unknown>) {
+  return partial as unknown as UseInfiniteQueryResult<InfiniteData<Page>, Error>;
+}
+
+describe("flattenItemPages", () => {
+  it("concatenates items across pages", () => {
+    expect(
+      flattenItemPages({
+        pages: [{ items: ["a"] }, { items: ["b", "c"] }],
+      }),
+    ).toEqual(["a", "b", "c"]);
+  });
+});
+
+describe("InfiniteQueryState", () => {
+  it("shows skeleton while pending", () => {
+    renderWithUi(
+      <InfiniteQueryState<Page, string[]>
+        query={mockInfiniteQuery({ isPending: true, isError: false })}
+        skeleton={<div data-testid="skel">loading</div>}
+        flatten={(d) => flattenItemPages(d)}
+      >
+        {() => null}
+      </InfiniteQueryState>,
+    );
+    expect(screen.getByTestId("skel")).toBeInTheDocument();
+  });
+
+  it("renders flattened items and load more", async () => {
+    const user = userEvent.setup();
+    const fetchNextPage = vi.fn();
+    renderWithUi(
+      <InfiniteQueryState<Page, string[]>
+        query={mockInfiniteQuery({
+          isPending: false,
+          isError: false,
+          isFetchingNextPage: false,
+          data: { pages: [{ items: ["note-1"] }], pageParams: [undefined] },
+          hasNextPage: true,
+          fetchNextPage,
+        })}
+        skeleton={<div>loading</div>}
+        flatten={(d) => flattenItemPages(d)}
+      >
+        {(items) => (
+          <ul>
+            {items.map((id) => (
+              <li key={id}>{id}</li>
+            ))}
+          </ul>
+        )}
+      </InfiniteQueryState>,
+    );
+    expect(screen.getByText("note-1")).toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: /tải thêm/i }));
+    expect(fetchNextPage).toHaveBeenCalledOnce();
+  });
+
+  it("shows empty state", () => {
+    renderWithUi(
+      <InfiniteQueryState<Page, string[]>
+        query={mockInfiniteQuery({
+          isPending: false,
+          isError: false,
+          data: { pages: [{ items: [] }], pageParams: [undefined] },
+          hasNextPage: false,
+        })}
+        skeleton={<div>loading</div>}
+        empty={<div>No notes</div>}
+        flatten={(d) => flattenItemPages(d)}
+      >
+        {() => null}
+      </InfiniteQueryState>,
+    );
+    expect(screen.getByText("No notes")).toBeInTheDocument();
+  });
+});
+
+describe("PrefetchLink", () => {
+  it("prefetches on hover", async () => {
+    const user = userEvent.setup();
+    const queryFn = vi.fn(() => Promise.resolve({ id: "cust_1" }));
+    const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+
+    renderWithUi(
+      <QueryClientProvider client={client}>
+        <PrefetchLink to="/customers/cust_1" queryKey={["customer", "cust_1"]} queryFn={queryFn}>
+          Mai Nguyen
+        </PrefetchLink>
+      </QueryClientProvider>,
+    );
+
+    await user.hover(screen.getByRole("link", { name: "Mai Nguyen" }));
+    await waitFor(() => expect(queryFn).toHaveBeenCalledOnce());
+  });
+});

package/src/components/query/__tests__/query-helpers.test.tsx

@@ -0,0 +1,61 @@
+import { describe, expect, it, vi } from "vitest";
+import { renderWithUi, screen, userEvent } from "@/test/render";
+import { MutationFeedback } from "../mutation-feedback";
+import { QueryRefetchButton } from "../query-refetch-button";
+
+describe("MutationFeedback", () => {
+  it("renders nothing when idle", () => {
+    const { container } = renderWithUi(
+      <MutationFeedback mutation={{ isError: false, error: null, isPending: false }} />,
+    );
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("shows Alert.QueryError when mutation failed", () => {
+    renderWithUi(
+      <MutationFeedback
+        mutation={{ isError: true, error: new Error("save failed"), isPending: false }}
+        onRetry={() => undefined}
+      />,
+    );
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+    expect(screen.getByText(/save failed/)).toBeInTheDocument();
+  });
+
+  it("shows pending slot while running", () => {
+    renderWithUi(
+      <MutationFeedback
+        mutation={{ isError: false, error: null, isPending: true }}
+        pending={<div data-testid="pending">Running…</div>}
+      />,
+    );
+    expect(screen.getByTestId("pending")).toBeInTheDocument();
+  });
+
+  it("hides retry when showRetry is false", () => {
+    renderWithUi(
+      <MutationFeedback
+        mutation={{ isError: true, error: new Error("403"), isPending: false }}
+        showRetry={false}
+      />,
+    );
+    expect(screen.queryByRole("button", { name: /thử lại/i })).not.toBeInTheDocument();
+  });
+});
+
+describe("QueryRefetchButton", () => {
+  it("calls refetch on click", async () => {
+    const user = userEvent.setup();
+    const refetch = vi.fn();
+    renderWithUi(
+      <QueryRefetchButton query={{ isFetching: false, refetch }} label="Refresh list" />,
+    );
+    await user.click(screen.getByRole("button", { name: /refresh list/i }));
+    expect(refetch).toHaveBeenCalledOnce();
+  });
+
+  it("disables while fetching", () => {
+    renderWithUi(<QueryRefetchButton query={{ isFetching: true, refetch: vi.fn() }} />);
+    expect(screen.getByRole("button")).toBeDisabled();
+  });
+});

package/src/components/query/data-state.tsx

@@ -0,0 +1,58 @@
+import * as React from "react";
+
+import { AlertQueryError } from "../feedback/alert";
+import type { DataStateProp } from "../../props/components/query.prop";
+
+export type {
+  DataStateProp,
+  DataStateProp as DataStateProps,
+} from "../../props/components/query.prop";
+
+function defaultIsEmpty(data: unknown): boolean {
+  if (!data) return true;
+  if (Array.isArray(data)) return data.length === 0;
+  if (typeof data === "object" && data !== null) {
+    const obj = data as { items?: unknown[]; length?: number };
+    if (Array.isArray(obj.items)) return obj.items.length === 0;
+    if (typeof obj.length === "number") return obj.length === 0;
+  }
+  return false;
+}
+
+/**
+ * Query lifecycle widget — orchestrates skeleton / error / empty / success for one `useQuery` block.
+ * Not a visual component; prefer `@godxjp/ui/query`. Apps may also import via `@godxjp/ui/admin`.
+ */
+export function DataState<T>({
+  query,
+  skeleton,
+  empty,
+  isEmpty = defaultIsEmpty,
+  errorRenderer,
+  showRetry = true,
+  onRetry,
+  children,
+}: DataStateProp<T>) {
+  const retry = React.useCallback(() => {
+    if (onRetry) {
+      void onRetry();
+      return;
+    }
+    void query.refetch();
+  }, [onRetry, query]);
+
+  if (query.isPending) return <>{skeleton}</>;
+
+  if (query.isError) {
+    if (query.isFetching) return <>{skeleton}</>;
+    if (errorRenderer) return <>{errorRenderer(query.error, retry)}</>;
+    return <AlertQueryError error={query.error} onRetry={showRetry ? retry : undefined} />;
+  }
+
+  const data = query.data;
+  if (data === undefined) return <>{skeleton}</>;
+
+  if (empty && (data === null || isEmpty(data))) return <>{empty}</>;
+
+  return <>{children(data as NonNullable<T>)}</>;
+}

package/src/components/query/index.ts

@@ -0,0 +1,10 @@
+export { DataState } from "./data-state";
+export type { DataStateProp, DataStateProps } from "./data-state";
+export { MutationFeedback } from "./mutation-feedback";
+export type { MutationFeedbackProp, MutationFeedbackProps } from "./mutation-feedback";
+export { QueryRefetchButton } from "./query-refetch-button";
+export type { QueryRefetchButtonProp, QueryRefetchButtonProps } from "./query-refetch-button";
+export { InfiniteQueryState, flattenItemPages } from "./infinite-query-state";
+export type { InfiniteQueryStateProp, InfiniteQueryStateProps } from "./infinite-query-state";
+export { PrefetchLink } from "./prefetch-link";
+export type { PrefetchLinkProp, PrefetchLinkProps } from "./prefetch-link";

package/src/components/query/infinite-query-state.tsx

@@ -0,0 +1,99 @@
+import * as React from "react";
+
+import { AlertQueryError } from "../feedback/alert";
+import { Button } from "../general/button";
+import { useTranslation } from "../../i18n/use-translation";
+import type { InfiniteQueryStateProp } from "../../props/components/query.prop";
+
+export type {
+  InfiniteQueryStateProp,
+  InfiniteQueryStateProp as InfiniteQueryStateProps,
+} from "../../props/components/query.prop";
+
+/** Flatten `{ pages: [{ items }] }` — default GODX paginated API shape. */
+export function flattenItemPages<TItem, TPage extends { items: TItem[] }>(
+  data: { pages: TPage[] } | undefined,
+): TItem[] {
+  if (!data) return [];
+  return data.pages.flatMap((page) => page.items);
+}
+
+function defaultIsEmptyFlat(flat: unknown): boolean {
+  if (Array.isArray(flat)) return flat.length === 0;
+  return !flat;
+}
+
+/**
+ * `useInfiniteQuery` lifecycle widget — flatten pages, load-more footer.
+ * Cursor / activity feeds where user accumulates pages (vs DataTable cursor buttons).
+ */
+export function InfiniteQueryState<TPage, TFlat>({
+  query,
+  skeleton,
+  empty,
+  flatten,
+  isEmpty = defaultIsEmptyFlat,
+  errorRenderer,
+  showRetry = true,
+  onRetry,
+  loadingMore,
+  loadMore,
+  showLoadMore = true,
+  children,
+}: InfiniteQueryStateProp<TPage, TFlat>) {
+  const { t } = useTranslation();
+
+  const retry = React.useCallback(() => {
+    if (onRetry) {
+      void onRetry();
+      return;
+    }
+    void query.refetch();
+  }, [onRetry, query]);
+
+  if (query.isPending) return <>{skeleton}</>;
+
+  if (query.isError) {
+    if (query.isFetching && !query.isFetchingNextPage) return <>{skeleton}</>;
+    if (errorRenderer) return <>{errorRenderer(query.error, retry)}</>;
+    return <AlertQueryError error={query.error} onRetry={showRetry ? retry : undefined} />;
+  }
+
+  const data = query.data;
+  if (!data) return <>{skeleton}</>;
+
+  const flat = flatten(data);
+  if (empty && isEmpty(flat)) return <>{empty}</>;
+
+  const footer =
+    showLoadMore && query.hasNextPage
+      ? (loadMore ?? (
+          <div className="flex justify-center pt-4">
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              disabled={query.isFetchingNextPage}
+              onClick={() => void query.fetchNextPage()}
+            >
+              {query.isFetchingNextPage ? t("common.working") : t("query.loadMore")}
+            </Button>
+          </div>
+        ))
+      : null;
+
+  return (
+    <>
+      {children(flat, {
+        fetchNextPage: () => void query.fetchNextPage(),
+        hasNextPage: !!query.hasNextPage,
+        isFetchingNextPage: query.isFetchingNextPage,
+      })}
+      {query.isFetchingNextPage &&
+        (loadingMore ?? (
+          <p className="text-muted-foreground pt-2 text-center text-xs">{t("common.working")}</p>
+        ))}
+      {footer}
+    </>
+  );
+}

package/src/components/query/mutation-feedback.tsx

@@ -0,0 +1,31 @@
+import { AlertQueryError } from "../feedback/alert";
+import type { MutationFeedbackProp } from "../../props/components/query.prop";
+
+export type {
+  MutationFeedbackProp,
+  MutationFeedbackProp as MutationFeedbackProps,
+} from "../../props/components/query.prop";
+
+/**
+ * Inline mutation error — renders nothing when idle/success.
+ * Prefer toast for transient saves; use this for blocking form sections (SimulatorPage).
+ */
+export function MutationFeedback({
+  mutation,
+  onRetry,
+  showRetry = true,
+  pending,
+  className,
+}: MutationFeedbackProp) {
+  if (mutation.isPending && pending) return <>{pending}</>;
+
+  if (!mutation.isError || mutation.error == null) return null;
+
+  return (
+    <AlertQueryError
+      className={className}
+      error={mutation.error}
+      onRetry={showRetry ? onRetry : undefined}
+    />
+  );
+}

package/src/components/query/prefetch-link.tsx

@@ -0,0 +1,45 @@
+import * as React from "react";
+import { Link } from "react-router-dom";
+import { useQueryClient } from "@tanstack/react-query";
+
+import type { PrefetchLinkProp } from "../../props/components/query.prop";
+
+export type {
+  PrefetchLinkProp,
+  PrefetchLinkProp as PrefetchLinkProps,
+} from "../../props/components/query.prop";
+
+/**
+ * React Router `Link` + `queryClient.prefetchQuery` on hover/focus.
+ * Detail routes feel instant when list rows are hovered.
+ */
+export function PrefetchLink({
+  queryKey,
+  queryFn,
+  prefetchOn = "both",
+  staleTime = 30_000,
+  onMouseEnter,
+  onFocus,
+  ...linkProps
+}: PrefetchLinkProp) {
+  const queryClient = useQueryClient();
+
+  const prefetch = React.useCallback(() => {
+    if (prefetchOn === "none") return;
+    void queryClient.prefetchQuery({ queryKey, queryFn, staleTime });
+  }, [prefetchOn, queryClient, queryFn, queryKey, staleTime]);
+
+  return (
+    <Link
+      {...linkProps}
+      onMouseEnter={(event) => {
+        if (prefetchOn === "hover" || prefetchOn === "both") prefetch();
+        onMouseEnter?.(event);
+      }}
+      onFocus={(event) => {
+        if (prefetchOn === "focus" || prefetchOn === "both") prefetch();
+        onFocus?.(event);
+      }}
+    />
+  );
+}

package/src/components/query/query-refetch-button.tsx

@@ -0,0 +1,41 @@
+import { RefreshCw } from "lucide-react";
+
+import { Button } from "../general/button";
+import type { QueryRefetchButtonProp } from "../../props/components/query.prop";
+
+export type {
+  QueryRefetchButtonProp,
+  QueryRefetchButtonProp as QueryRefetchButtonProps,
+} from "../../props/components/query.prop";
+
+/** Page-header Refresh — spins while `query.isFetching`, calls `query.refetch()`. */
+export function QueryRefetchButton({
+  query,
+  label = "Refresh",
+  children,
+  variant = "outline",
+  size = "sm",
+  className,
+  ...props
+}: QueryRefetchButtonProp) {
+  const text = children ?? label;
+
+  return (
+    <Button
+      type="button"
+      variant={variant}
+      size={size}
+      className={className}
+      onClick={() => void query.refetch()}
+      disabled={query.isFetching}
+      {...props}
+    >
+      <RefreshCw
+        className="ui-query-refetch-icon"
+        data-fetching={query.isFetching}
+        aria-hidden="true"
+      />
+      {text}
+    </Button>
+  );
+}

package/src/components/ui/alert-dialog.tsx

@@ -0,0 +1 @@
+export * from "../feedback/dialog";

package/src/components/ui/alert.tsx

@@ -0,0 +1 @@
+export * from "../feedback/alert";

package/src/components/ui/autocomplete.tsx

@@ -0,0 +1 @@
+export * from "../data-entry/autocomplete";

package/src/components/ui/badge.tsx

@@ -0,0 +1 @@
+export * from "../data-display/badge";

package/src/components/ui/button.tsx

@@ -0,0 +1 @@
+export * from "../general/button";

package/src/components/ui/calendar.tsx

@@ -0,0 +1 @@
+export * from "../data-entry/calendar";