@openway/ui 1.0.0 → 1.0.2

package/dist/query.d.cts

@@ -0,0 +1,431 @@
+import { QueryFunctionContext, UseQueryOptions, UseQueryResult, UseInfiniteQueryOptions, InfiniteData, UseInfiniteQueryResult, QueryKey, InvalidateQueryFilters, DefaultError, UseMutationOptions, InvalidateOptions, UseMutationResult } from '@tanstack/react-query';
+import { RowData, SortingState, ColumnFiltersState, PaginationState, OnChangeFn } from '@tanstack/react-table';
+import { ReactNode } from 'react';
+import { d as SelectOptionItem, U as UseInfiniteScrollOptions, a as ToastOptions, o as AlertVariant } from './useInfiniteScroll-D9AW6cQV.cjs';
+import 'sonner';
+import '@floating-ui/react';
+
+/**
+ * Các tham số truy vấn chuẩn hóa gửi lên API máy chủ.
+ */
+interface TableQueryParams {
+    /**
+     * Số thứ tự trang (1-indexed: 1, 2, 3...)
+     */
+    page: number;
+    /**
+     * Kích thước trang (số dòng trên 1 trang)
+     */
+    pageSize: number;
+    /**
+     * ID cột được sắp xếp
+     */
+    sortBy?: string;
+    /**
+     * Chiều sắp xếp: "asc" (tăng dần) hoặc "desc" (giảm dần)
+     */
+    sortOrder?: "asc" | "desc";
+    /**
+     * Danh sách bộ lọc cột dạng từ điển phẳng Record<cột, giá trị>
+     */
+    filters?: Record<string, unknown>;
+}
+/**
+ * Các tùy chọn cấu hình cho hook `useTableQuery`.
+ */
+interface UseTableQueryOptions<TData extends RowData = RowData, TResponse = unknown, TError = Error> {
+    /**
+     * Base query key cho TanStack Query.
+     * `queryParams` sẽ tự động được thêm vào cuối queryKey: `[...queryKey, queryParams]`.
+     */
+    queryKey: readonly unknown[];
+    /**
+     * Hàm gọi API truy vấn dữ liệu từ máy chủ.
+     * Nhận vào `queryParams` đã chuẩn hóa và `context` của TanStack Query.
+     */
+    queryFn: (params: TableQueryParams, context: QueryFunctionContext<readonly unknown[]>) => Promise<TResponse>;
+    /**
+     * Hàm trích xuất mảng dữ liệu các dòng (`TData[]`) từ kết quả API trả về.
+     * Mặc định tự động kiểm tra `response.data`, `response.items`, `response.rows`, `response.results` hoặc bản thân mảng response.
+     */
+    selectData?: (response: TResponse) => TData[];
+    /**
+     * Hàm trích xuất tổng số lượng bản ghi (`rowCount` / `total`) từ kết quả API trả về.
+     * Mặc định tự động kiểm tra `response.total`, `response.rowCount`, `response.totalCount`, `response.count`.
+     */
+    selectRowCount?: (response: TResponse) => number;
+    /**
+     * Cấu hình phân trang ban đầu
+     */
+    initialPagination?: {
+        pageIndex?: number;
+        pageSize?: number;
+    };
+    /**
+     * Cấu hình sắp xếp ban đầu
+     */
+    initialSorting?: SortingState;
+    /**
+     * Cấu hình bộ lọc cột ban đầu
+     */
+    initialColumnFilters?: ColumnFiltersState;
+    /**
+     * Cấu hình từ khóa tìm kiếm ban đầu
+     */
+    initialGlobalFilter?: string;
+    /**
+     * Tự động đưa về trang đầu (pageIndex = 0) khi thay đổi tìm kiếm, bộ lọc hoặc sắp xếp.
+     * @default true
+     */
+    autoResetPageIndex?: boolean;
+    /**
+     * Các tùy chọn nâng cao truyền trực tiếp cho hook `useQuery` của TanStack Query
+     * (ví dụ: `staleTime`, `gcTime`, `refetchOnWindowFocus`, `enabled`...).
+     */
+    queryOptions?: Omit<UseQueryOptions<TResponse, TError, TResponse, readonly unknown[]>, "queryKey" | "queryFn">;
+}
+/**
+ * Kết quả trả về từ hook `useTableQuery`.
+ */
+interface UseTableQueryReturn<TData extends RowData = RowData, TResponse = unknown, TError = Error> {
+    /**
+     * Tập props trọn gói sẵn sàng truyền thẳng vào `<DataTable {...tableProps} />`
+     */
+    tableProps: {
+        data: TData[];
+        rowCount: number;
+        isLoading: boolean;
+        isRefresh: boolean;
+        onRefresh: () => void;
+        manualPagination: true;
+        manualSorting: true;
+        manualFiltering: true;
+        pagination: PaginationState;
+        onPaginationChange: OnChangeFn<PaginationState>;
+        sorting: SortingState;
+        onSortingChange: OnChangeFn<SortingState>;
+        columnFilters: ColumnFiltersState;
+        onColumnFiltersChange: OnChangeFn<ColumnFiltersState>;
+        globalFilter: string;
+        onGlobalFilterChange: (filter: string) => void;
+    };
+    /**
+     * Instance query đầy đủ từ TanStack Query
+     */
+    query: UseQueryResult<TResponse, TError>;
+    /**
+     * Tham số truy vấn hiện tại (dùng để debug, ghi log, đồng bộ URL query string, hoặc xuất Excel)
+     */
+    queryParams: TableQueryParams;
+    /**
+     * Đặt lại toàn bộ phân trang, sắp xếp, tìm kiếm và bộ lọc về giá trị mặc định ban đầu
+     */
+    resetAll: () => void;
+    /**
+     * Đổi trang thủ công (1-indexed: 1, 2, 3...)
+     */
+    setPage: (page: number) => void;
+    /**
+     * Đổi số dòng trên mỗi trang thủ công
+     */
+    setPageSize: (pageSize: number) => void;
+    /**
+     * Đổi từ khóa tìm kiếm toàn bảng (lọc client-side)
+     */
+    setGlobalFilter: (filter: string) => void;
+    /**
+     * Cập nhật trạng thái sắp xếp
+     */
+    setSorting: (sorting: SortingState | ((prev: SortingState) => SortingState)) => void;
+    /**
+     * Cập nhật trạng thái bộ lọc cột
+     */
+    setColumnFilters: (filters: ColumnFiltersState | ((prev: ColumnFiltersState) => ColumnFiltersState)) => void;
+}
+/**
+ * Hook Adapter `useTableQuery` tích hợp TanStack Table v9 và TanStack Query v5.
+ *
+ * Tính năng:
+ * - Đồng bộ hai chiều trạng thái bảng (Pagination, Sorting, Filtering, Search) với server API.
+ * - Tự động định dạng tham số `TableQueryParams`: `page` (1-indexed), `pageSize`, `search`, `sortBy`, `sortOrder`, `filters`.
+ * - Tự động gắn `queryParams` vào `queryKey` của TanStack Query để kích hoạt cache/refetch thông minh.
+ * - Hỗ trợ phân trang mượt mà bằng `placeholderData: keepPreviousData` (không bị nhấp nháy Skeleton khi chuyển trang).
+ * - Cung cấp `tableProps` dựng sẵn truyền trực tiếp vào `<DataTable {...tableProps} />`.
+ */
+declare function useTableQuery<TData extends RowData = RowData, TResponse = unknown, TError = Error>(options: UseTableQueryOptions<TData, TResponse, TError>): UseTableQueryReturn<TData, TResponse, TError>;
+
+/**
+ * Các tham số truy vấn chuẩn hóa được chuyển tới hàm `queryFn`.
+ */
+interface SelectQueryParams<TPageParam = number, TFilters extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Tham số phân trang hiện tại (trang hiện tại hoặc cursor).
+     */
+    pageParam: TPageParam;
+    /**
+     * Từ khóa tìm kiếm từ ô Select.
+     */
+    search: string;
+    /**
+     * Bộ lọc bổ sung từ menu filter của Select.
+     */
+    filters: TFilters;
+}
+/**
+ * Các tùy chọn cấu hình cho hook `useSelectInfiniteQuery`.
+ */
+interface UseSelectInfiniteQueryOptions<TData = unknown, TResponse = unknown, TPageParam = number, TFilters extends Record<string, unknown> = Record<string, unknown>, TError = Error> {
+    /**
+     * Base query key cho TanStack Query.
+     * `[{ search, filters }]` sẽ tự động được thêm vào cuối queryKey:
+     * `[...queryKey, { search, filters }]`.
+     */
+    queryKey: readonly unknown[];
+    /**
+     * Hàm gọi API truy vấn dữ liệu từ máy chủ theo từng trang.
+     * Nhận vào `SelectQueryParams` đã chuẩn hóa và `context` của TanStack Query.
+     */
+    queryFn: (params: SelectQueryParams<TPageParam, TFilters>, context: QueryFunctionContext<readonly unknown[], TPageParam>) => Promise<TResponse>;
+    /**
+     * Giá trị tham số trang đầu tiên (initialPageParam).
+     * @default 1
+     */
+    initialPageParam?: TPageParam;
+    /**
+     * Hàm xác định `pageParam` cho trang tiếp theo.
+     * Trả về `undefined` hoặc `null` khi không còn dữ liệu tiếp theo.
+     */
+    getNextPageParam?: (lastPage: TResponse, allPages: TResponse[], lastPageParam: TPageParam, allPageParams: TPageParam[]) => TPageParam | undefined | null;
+    /**
+     * Hàm xác định `pageParam` cho trang trước đó (nếu có).
+     */
+    getPreviousPageParam?: (firstPage: TResponse, allPages: TResponse[], firstPageParam: TPageParam, allPageParams: TPageParam[]) => TPageParam | undefined | null;
+    /**
+     * Hàm trích xuất danh sách options (`SelectOptionItem<TData>[]`) từ mỗi `response` trang.
+     * Nếu không truyền, mặc định sẽ kiểm tra `data`, `items`, `options`, `results`, `rows` hoặc chính `response`.
+     */
+    selectOptions?: (response: TResponse) => SelectOptionItem<TData>[];
+    /**
+     * Hàm biến đổi từng phần tử thô (raw entity) thành `SelectOptionItem<TData>`.
+     */
+    mapOption?: (item: unknown, index: number) => SelectOptionItem<TData>;
+    /**
+     * Thời gian debounce từ khóa tìm kiếm (tính theo ms).
+     * @default 300
+     */
+    debounceMs?: number;
+    /**
+     * Từ khóa tìm kiếm ban đầu.
+     */
+    initialSearch?: string;
+    /**
+     * Giá trị bộ lọc menu ban đầu.
+     */
+    initialFilters?: TFilters;
+    /**
+     * Danh sách options ban đầu ghim sẵn (ví dụ các options đã chọn trước đó cần bảo lưu).
+     */
+    initialOptions?: SelectOptionItem<TData>[];
+    /**
+     * Số dòng Skeleton hiển thị khi đang tải thêm trang tiếp theo.
+     * @default 2
+     */
+    skeletonLines?: number;
+    /**
+     * Chiều cao của mỗi dòng Skeleton khi đang tải thêm trang.
+     * @default "1.75rem"
+     */
+    skeletonHeight?: number | string;
+    /**
+     * Tùy biến render khi đang tải thêm trang tiếp theo (thay thế Skeleton mặc định).
+     */
+    renderLoadingMore?: () => ReactNode;
+    /**
+     * Thông báo hiển thị khi đã tải hết toàn bộ dữ liệu ở đáy danh sách (tùy chọn).
+     */
+    endMessage?: ReactNode;
+    /**
+     * Tùy chọn truyền trực tiếp cho hook `useInfiniteScroll`.
+     */
+    scrollOptions?: Partial<Omit<UseInfiniteScrollOptions, "onLoadMore" | "hasMore" | "isLoading">>;
+    /**
+     * Các tùy chọn nâng cao truyền trực tiếp cho hook `useInfiniteQuery` của TanStack Query.
+     */
+    queryOptions?: Omit<UseInfiniteQueryOptions<TResponse, TError, InfiniteData<TResponse>, readonly unknown[], TPageParam>, "queryKey" | "queryFn" | "initialPageParam" | "getNextPageParam" | "getPreviousPageParam">;
+}
+/**
+ * Kết quả trả về từ hook `useSelectInfiniteQuery`.
+ */
+interface UseSelectInfiniteQueryReturn<TData = unknown, TResponse = unknown, TFilters extends Record<string, unknown> = Record<string, unknown>, TError = Error> {
+    /**
+     * Bộ props trọn gói sẵn sàng truyền thẳng vào `<Select {...selectProps} />` hoặc `<MultiSelect {...selectProps} />`
+     */
+    selectProps: {
+        options: SelectOptionItem<TData>[];
+        isLoading: boolean;
+        searchMode: "server";
+        debounceMs: number;
+        onSearch: (query: string, filters: TFilters) => void;
+        listFooter: ReactNode;
+    };
+    /**
+     * Instance query đầy đủ từ TanStack Query
+     */
+    query: UseInfiniteQueryResult<InfiniteData<TResponse>, TError>;
+    /**
+     * Toàn bộ danh sách options đã gom tụ từ tất cả các trang
+     */
+    options: SelectOptionItem<TData>[];
+    /**
+     * Từ khóa tìm kiếm hiện tại (đã được Select debounce qua onSearch)
+     */
+    search: string;
+    /**
+     * Phương thức cập nhật từ khóa tìm kiếm
+     */
+    setSearch: (search: string) => void;
+    /**
+     * Bộ lọc menu hiện tại
+     */
+    filters: TFilters;
+    /**
+     * Phương thức cập nhật bộ lọc menu
+     */
+    setFilters: (filters: TFilters | ((prev: TFilters) => TFilters)) => void;
+    /**
+     * Ref gắn vào phần tử sentinel (IntersectionObserver)
+     */
+    sentinelRef: (node: HTMLElement | null) => void;
+    /**
+     * Đặt lại toàn bộ tìm kiếm, bộ lọc về giá trị ban đầu
+     */
+    reset: () => void;
+}
+/**
+ * Hook `useSelectInfiniteQuery` kết hợp TanStack Query `useInfiniteQuery` với `useInfiniteScroll`
+ * dành riêng cho `<Select />` và `<MultiSelect />` ở chế độ máy chủ (`searchMode="server"`).
+ */
+declare function useSelectInfiniteQuery<TData = unknown, TResponse = unknown, TPageParam = number, TFilters extends Record<string, unknown> = Record<string, unknown>, TError = Error>({ queryKey, queryFn, initialPageParam, getNextPageParam, getPreviousPageParam, selectOptions, mapOption, debounceMs, initialSearch, initialFilters, initialOptions, skeletonLines, skeletonHeight, renderLoadingMore, endMessage, scrollOptions, queryOptions, }: UseSelectInfiniteQueryOptions<TData, TResponse, TPageParam, TFilters, TError>): UseSelectInfiniteQueryReturn<TData, TResponse, TFilters, TError>;
+
+/**
+ * Mục tiêu invalidate cache: có thể là QueryKey (readonly unknown[]) hoặc InvalidateQueryFilters.
+ */
+type InvalidateQueryTarget = QueryKey | InvalidateQueryFilters;
+/**
+ * Tùy chọn cấu hình Toast cho hook `useMutationApp`.
+ */
+interface UseMutationAppToastOptions<TData, TError, TVariables> {
+    /**
+     * Nội dung thông báo khi đang thực thi mutation (loading spinner, không tự đóng).
+     * Có thể là ReactNode hoặc một hàm nhận vào `variables`.
+     */
+    loading?: ReactNode | ((variables: TVariables) => ReactNode);
+    /**
+     * Nội dung thông báo khi mutation hoàn tất thành công.
+     * Có thể là ReactNode hoặc một hàm nhận vào `(data, variables)`.
+     */
+    success?: ReactNode | ((data: TData, variables: TVariables) => ReactNode);
+    /**
+     * Nội dung thông báo khi mutation thất bại.
+     * - `true`: Tự động trích xuất thông điệp lỗi từ API/Error qua `extractErrorMessage`.
+     * - `false`: Không hiển thị toast lỗi.
+     * - `ReactNode`: Thông điệp lỗi cố định.
+     * - `(error, variables) => ReactNode`: Hàm tạo thông điệp lỗi linh hoạt.
+     * @default true
+     */
+    error?: boolean | ReactNode | ((error: TError, variables: TVariables) => ReactNode);
+    /**
+     * Nội dung mô tả chi tiết (description) cho thông báo khi đang loading.
+     */
+    loadingDescription?: ReactNode | ((variables: TVariables) => ReactNode);
+    /**
+     * Nội dung mô tả chi tiết (description) cho thông báo thành công.
+     */
+    successDescription?: ReactNode | ((data: TData, variables: TVariables) => ReactNode);
+    /**
+     * Nội dung mô tả chi tiết (description) cho thông báo lỗi.
+     */
+    errorDescription?: ReactNode | ((error: TError, variables: TVariables) => ReactNode);
+    /**
+     * Tùy chọn cấu hình bổ sung cho Toast (duration, position, size, radius, closable...).
+     */
+    options?: ToastOptions;
+    /**
+     * Kiểu hiển thị Toast: "soft" | "solid" | "outline".
+     * @default "soft"
+     */
+    variant?: AlertVariant;
+}
+/**
+ * Các tùy chọn cấu hình cho hook `useMutationApp`.
+ */
+interface UseMutationAppOptions<TData = unknown, TError = DefaultError, TVariables = void, TContext = unknown> extends Omit<UseMutationOptions<TData, TError, TVariables, TContext>, "mutationFn"> {
+    /**
+     * Hàm gọi API hoặc thực hiện tác vụ bất đồng bộ.
+     */
+    mutationFn?: (variables: TVariables) => Promise<TData>;
+    /**
+     * Khóa truy vấn hoặc danh sách khóa truy vấn cần tự động làm mới (invalidate) khi mutation thành công.
+     * Hỗ trợ:
+     * - Một QueryKey đơn: `["teachers"]` hoặc `["users", 1]`
+     * - Danh sách nhiều QueryKey: `[["teachers"], ["classes"]]`
+     * - Bộ lọc nâng cao InvalidateQueryFilters: `{ queryKey: ["teachers"], exact: true }`
+     * - Danh sách bộ lọc: `[{ queryKey: ["teachers"] }, { queryKey: ["classes"] }]`
+     * - Hàm trả về động: `(data, variables) => [["teachers"], ["classes", variables.classId]]`
+     */
+    invalidateQueries?: InvalidateQueryTarget | InvalidateQueryTarget[] | ((data: TData, variables: TVariables) => InvalidateQueryTarget | InvalidateQueryTarget[] | void | null | undefined);
+    /**
+     * Tùy chọn InvalidateOptions bổ sung truyền cho `queryClient.invalidateQueries`
+     * (ví dụ: `throwOnError`, `cancelRefetch`).
+     */
+    invalidateOptions?: InvalidateOptions;
+    /**
+     * Cấu hình hiển thị thông báo Toast.
+     * - `false`: Tắt toàn bộ thông báo Toast.
+     * - `true`: Bật Toast với cấu hình mặc định (tự động báo lỗi nếu có).
+     * - `object`: Cấu hình chi tiết `loading`, `success`, `error`.
+     */
+    toast?: boolean | UseMutationAppToastOptions<TData, TError, TVariables>;
+    /**
+     * Shortcut cấu hình nhanh thông báo thành công.
+     */
+    successMessage?: ReactNode | ((data: TData, variables: TVariables) => ReactNode);
+    /**
+     * Shortcut cấu hình nhanh thông báo lỗi.
+     */
+    errorMessage?: ReactNode | ((error: TError, variables: TVariables) => ReactNode);
+    /**
+     * Shortcut cấu hình nhanh thông báo loading.
+     */
+    loadingMessage?: ReactNode | ((variables: TVariables) => ReactNode);
+}
+/**
+ * Kết quả trả về từ hook `useMutationApp`.
+ */
+type UseMutationAppReturn<TData = unknown, TError = DefaultError, TVariables = void, TContext = unknown> = UseMutationResult<TData, TError, TVariables, TContext> & {
+    /**
+     * Bí danh (alias) của `isPending`, tương thích ngược với thói quen sử dụng `isLoading` của TanStack Query v4.
+     */
+    isLoading: boolean;
+};
+/**
+ * Hàm hỗ trợ tự động trích xuất thông điệp lỗi (error message) từ nhiều định dạng lỗi phổ biến:
+ * - Axios Error response (`error.response?.data?.message`, `error.response?.data?.error`...)
+ * - Fetch API response / HTTP status
+ * - Standard JS Error (`error.message`)
+ * - String error
+ */
+declare function extractErrorMessage(error: unknown, fallback?: string): string;
+/**
+ * Hook `useMutationApp` - Tối ưu hóa tác vụ Mutation cho ứng dụng với TanStack Query v5 & `@openway/ui`.
+ *
+ * Tính năng chính:
+ * - **Tự động hóa Toast**: Hiển thị Toast loading khi xử lý, tự động cập nhật Toast success/error mượt mà.
+ * - **Tự động bóc tách lỗi**: Bóc tách thông điệp lỗi chính xác từ Axios / API response qua `extractErrorMessage`.
+ * - **Tự động Invalidate Cache**: Refresh tự động các query liên quan (như DataTable, Select) khi hoàn tất.
+ * - **Bổ sung `isLoading`**: Cung cấp alias `isLoading` cho `isPending`, thuận tiện khi code giao diện.
+ * - **Giữ trọn vẹn sức mạnh của TanStack Query**: Hỗ trợ đầy đủ `onMutate`, `onSuccess`, `onError`, `onSettled`.
+ */
+declare function useMutationApp<TData = unknown, TError = DefaultError, TVariables = void, TContext = unknown>(options: UseMutationAppOptions<TData, TError, TVariables, TContext>): UseMutationAppReturn<TData, TError, TVariables, TContext>;
+
+export { type InvalidateQueryTarget, type SelectQueryParams, type TableQueryParams, type UseMutationAppOptions, type UseMutationAppReturn, type UseMutationAppToastOptions, type UseSelectInfiniteQueryOptions, type UseSelectInfiniteQueryReturn, type UseTableQueryOptions, type UseTableQueryReturn, extractErrorMessage, useMutationApp, useSelectInfiniteQuery, useTableQuery };