react-toolkits 2.27.0 → 2.27.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # react-toolkits
 
+## 2.27.2
+
+### Patch Changes
+
+- de255b8: fix: enhance game API usage and pagination handling in InfiniteList
+
+## 2.27.1
+
+### Patch Changes
+
+- 908ad9e: refactor: update visibility store implementation and improve InfiniteList component
+
 ## 2.27.0
 
 ### Minor Changes

package/lib/index.d.ts

@@ -7,6 +7,7 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { AnyObject } from 'antd/es/_util/type';
 import { TableProps } from 'antd/es/table';
 import * as zustand from 'zustand';
+import { StateCreator } from 'zustand';
 import { ItemType, SubMenuType, MenuItemGroupType, MenuItemType } from 'antd/es/menu/interface';
 import { Merge } from 'ts-essentials';
 import * as _tanstack_react_query from '@tanstack/react-query';
@@ -59,63 +60,172 @@ interface HighlightProps extends PropsWithChildren {
 }
 declare const Highlight: (props: HighlightProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * 无限列表的载荷数据
+ * @template Values 表单值的类型
+ */
 interface InfiniteListPayload<Values = any> {
+    /** 当前页码（仅用于表单状态，实际分页参数通过 pageParam 传递） */
     page?: number;
+    /** 表单筛选条件 */
     filters?: Values;
 }
+/**
+ * 缓存配置
+ */
 interface CacheConfig$1 {
+    /** 缓存时间（毫秒），数据在缓存中保留的时间 */
     cacheTime?: number;
+    /** 过期时间（毫秒），数据在过期前被认为是新鲜的 */
     staleTime?: number;
 }
+/**
+ * HTTP 请求方法
+ */
 type HttpMethod$1 = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
-type RequestBodyResolver<Values = any> = FormData | Record<string | number, any> | ((payload: InfiniteListPayload<Values>, pageParam: any) => FormData | Record<string | number, any>);
-type RequestParamsResolver<Values = any> = Record<string | number, any> | ((payload: InfiniteListPayload<Values>, pageParam: any) => Record<string | number, any>);
-interface InfiniteListRequestConfig<Values = any> extends CacheConfig$1 {
+/**
+ * 分页参数类型，支持多种分页方式：
+ * - number: 页码分页
+ * - string: 游标分页（cursor）
+ * - object: 复杂分页参数对象
+ * - undefined: 无下一页
+ */
+type PageParam = number | string | Record<string, any> | undefined;
+/**
+ * 请求体解析器
+ * 可以是静态值，也可以是动态函数
+ * @template Values 表单值的类型
+ * @template PageParamType 分页参数的类型（可能是 undefined，表示第一页）
+ */
+type RequestBodyResolver<Values = any, PageParamType = PageParam> = FormData | Record<string | number, any> | ((payload: InfiniteListPayload<Values>, pageParam: PageParamType | undefined) => FormData | Record<string | number, any>);
+/**
+ * 请求参数解析器（用于 URL 查询参数）
+ * 可以是静态值，也可以是动态函数
+ * @template Values 表单值的类型
+ * @template PageParamType 分页参数的类型（可能是 undefined，表示第一页）
+ */
+type RequestParamsResolver<Values = any, PageParamType = PageParam> = Record<string | number, any> | ((payload: InfiniteListPayload<Values>, pageParam: PageParamType | undefined) => Record<string | number, any>);
+/**
+ * 无限列表请求配置
+ * @template Values 表单值的类型
+ * @template PageParamType 分页参数的类型
+ */
+interface InfiniteListRequestConfig<Values = any, PageParamType = PageParam> extends CacheConfig$1 {
+    /** 请求 URL */
     url: string;
+    /** HTTP 请求方法，默认为 GET */
     method?: HttpMethod$1;
-    body?: RequestBodyResolver<Values>;
-    searchParams?: RequestParamsResolver<Values>;
-    params?: RequestParamsResolver<Values>;
+    /** 请求体（用于 POST、PUT、PATCH、DELETE 等方法） */
+    body?: RequestBodyResolver<Values, PageParamType>;
+    /** URL 查询参数 */
+    searchParams?: RequestParamsResolver<Values, PageParamType>;
+    /** 请求头，可以是静态对象或动态函数 */
     headers?: Record<string, string> | ((form: FormInstance<Values>) => Record<string, string>);
 }
-type InfiniteListRequestConfigType<Values = any> = InfiniteListRequestConfig<Values> | ((payload: InfiniteListPayload<Values>, pageParam: any) => InfiniteListRequestConfig<Values>);
-declare enum InfiniteListAction {
-    Confirm = 0,
-    Reset = 1,
-    LoadMore = 2,
-    Init = 3
-}
-interface InfiniteListDataAdapter<Item = any, Values = any, Data = any> {
+/**
+ * 无限列表请求配置类型
+ * 可以是静态配置，也可以是动态函数
+ * @template Values 表单值的类型
+ * @template PageParamType 分页参数的类型
+ */
+type InfiniteListRequestConfigType<Values = any, PageParamType = PageParam> = InfiniteListRequestConfig<Values, PageParamType> | ((payload: InfiniteListPayload<Values>, pageParam: PageParamType | undefined) => InfiniteListRequestConfig<Values, PageParamType>);
+/**
+ * 数据适配器，用于转换和适配后端返回的数据格式
+ * @template Item 列表项类型
+ * @template Values 表单值类型
+ * @template Data 后端返回的数据类型
+ * @template PageParamType 分页参数的类型
+ */
+interface InfiniteListDataAdapter<Item = any, Values = any, Data = any, PageParamType = PageParam> {
+    /**
+     * 从后端数据中提取列表项
+     * @param data 所有已加载的页面数据
+     * @param form 表单实例
+     * @returns 提取的列表项数组
+     */
     items?: (data: Data[] | undefined, form: FormInstance<Values>) => Item[] | undefined;
+    /**
+     * 判断是否还有更多数据
+     * @param lastPage 最后一页的数据
+     * @param allPages 所有已加载的页面数据
+     * @returns 是否还有更多数据
+     */
     hasMore?: (lastPage: Data | undefined, allPages: Data[]) => boolean;
-    nextPageParam?: (lastPage: Data | undefined, allPages: Data[], pageParam: any) => any;
+    /**
+     * 计算下一页的分页参数
+     * @param lastPage 最后一页的数据
+     * @param allPages 所有已加载的页面数据
+     * @param pageParam 当前的分页参数
+     * @returns 下一页的分页参数，返回 undefined 表示没有下一页
+     */
+    nextPageParam?: (lastPage: Data | undefined, allPages: Data[], pageParam: PageParamType) => PageParamType | undefined;
 }
+/**
+ * InfiniteList 组件的引用对象，提供外部访问的 API
+ * @template Item 列表项类型
+ * @template Values 表单值类型
+ * @template Data 后端返回的数据类型
+ */
 interface InfiniteListRef<Item = any, Values = any, Data = any> {
+    /** 所有已加载的页面数据 */
     data: Data[] | undefined;
+    /** 处理后的列表数据源 */
     dataSource: Item[] | undefined;
+    /** 表单实例 */
     form: FormInstance<Values>;
+    /** 重新获取数据 */
     refetch: () => void;
+    /** 获取下一页数据 */
     fetchNextPage: () => void;
+    /** 是否还有下一页 */
     hasNextPage: boolean;
+    /** 是否正在获取下一页 */
     isFetchingNextPage: boolean;
 }
-interface InfiniteListProps<Item, Values, Data> extends Omit<TableProps<Item>, 'pagination' | 'dataSource' | 'loading' | 'footer'>, Pick<FilterFormWrapperProps, 'buttonsAlign' | 'showReset'> {
+/**
+ * InfiniteList 组件的属性
+ * @template Item 列表项类型
+ * @template Values 表单值类型
+ * @template Data 后端返回的数据类型
+ * @template PageParamType 分页参数的类型
+ */
+interface InfiniteListProps<Item, Values, Data, PageParamType = PageParam> extends Omit<TableProps<Item>, 'pagination' | 'dataSource' | 'loading' | 'footer'>, Pick<FilterFormWrapperProps, 'buttonsAlign' | 'showReset'> {
+    /** 唯一标识符，用于在 store 中区分不同的列表实例 */
     identifier?: string;
+    /** 权限代码，用于权限控制 */
     code?: string;
+    /** 表单实例，如果不提供则内部创建 */
     form?: FormInstance<Values>;
+    /** 自动刷新间隔（毫秒），0 表示不自动刷新 */
     refreshInterval?: number;
-    request: InfiniteListRequestConfigType<Values>;
+    /** 请求配置，可以是静态配置或动态函数 */
+    request: InfiniteListRequestConfigType<Values, PageParamType>;
+    /** 表格额外内容，可以是静态内容或动态函数 */
     tableExtra?: ReactNode | ((form: FormInstance<Values>, data?: Data[]) => ReactNode);
+    /** 自定义表单渲染函数 */
     renderForm?: (form: FormInstance<Values>) => ReactElement;
-    afterSuccess?: (action: InfiniteListAction, form: FormInstance<Values>, data?: Data[]) => void;
-    afterError?: (error: Error, action: InfiniteListAction, form: FormInstance<Values>) => void;
-    dataAdapter?: InfiniteListDataAdapter<Item, Values, Data>;
-    initialPageParam?: any;
+    /** 请求成功后的回调 */
+    afterSuccess?: (form: FormInstance<Values>, data?: Data[]) => void;
+    /** 请求失败后的回调 */
+    afterError?: (error: Error, form: FormInstance<Values>) => void;
+    /** 数据适配器，用于转换后端数据格式 */
+    dataAdapter?: InfiniteListDataAdapter<Item, Values, Data, PageParamType>;
+    /** 初始分页参数，默认为 0 */
+    initialPageParam?: PageParamType;
+    /** 表格底部内容，可以是静态内容或动态函数 */
     footer?: (data: Data[] | undefined) => ReactNode;
 }
-declare const InfiniteList: <Item extends AnyObject = AnyObject, Values extends object | undefined = undefined, Data = any>(props: InfiniteListProps<Item, Values, Data> & {
+/**
+ * InfiniteList 组件
+ * @template Item 列表项类型
+ * @template Values 表单值类型
+ * @template Data 后端返回的数据类型
+ * @template PageParamType 分页参数的类型
+ */
+declare function InfiniteListComponent<Item extends AnyObject = AnyObject, Values extends object | undefined = undefined, Data = any, PageParamType = PageParam>(props: InfiniteListProps<Item, Values, Data, PageParamType> & {
     ref?: Ref<InfiniteListRef<Item, Values, Data>>;
-}) => ReactElement;
+}): ReactElement;
+declare const InfiniteList: typeof InfiniteListComponent;
 
 type InfiniteQueryRefetchFunction = () => void | Promise<unknown>;
 type InfiniteQueryFetchNextPageFunction = () => void | Promise<unknown>;
@@ -620,11 +730,11 @@ interface VisibilityState {
     cleanup: (uuid: number) => void;
 }
 /**
- * 创建一个可见性管理的 Zustand store
- * 用于管理 Modal、Drawer 等组件的显示/隐藏状态
- * 每次调用都会创建一个独立的 store 实例，确保不同组件间的状态隔离
+ * 创建可见性管理的 Zustand store 配置
+ * 这是一个纯函数，返回 store 的配置对象
+ * 使用函数形式延迟执行，避免模块初始化顺序问题
  */
-declare function createVisibilityStore(): zustand.UseBoundStore<zustand.StoreApi<VisibilityState>>;
+declare function createVisibilityStoreConfig(): StateCreator<VisibilityState, [], [], VisibilityState>;
 
 declare const generateId: () => number;
 
@@ -636,7 +746,11 @@ declare const generateId: () => number;
  */
 declare const mixedStorage: StateStorage;
 
-declare const useDrawerStore: zustand.UseBoundStore<zustand.StoreApi<VisibilityState>>;
+/**
+ * Drawer store hook
+ * 使用 lazy initialization 确保 create 函数在调用时已经准备好
+ */
+declare function useDrawerStore(): VisibilityState;
 
 interface UseModalOperation {
     hide: () => void;
@@ -674,7 +788,11 @@ interface UseFormModalReturn<Values extends AnyObject, ExtraValues> {
 }
 declare function useFormModal<Values extends AnyObject = AnyObject, ExtraValues = Record<string, unknown>>(props: UseFormModalProps<Values, ExtraValues>): UseFormModalReturn<Values, ExtraValues>;
 
-declare const useModalStore: zustand.UseBoundStore<zustand.StoreApi<VisibilityState>>;
+/**
+ * Modal store hook
+ * 使用 lazy initialization 确保 create 函数在调用时已经准备好
+ */
+declare function useModalStore(): VisibilityState;
 
 declare const _default$1: react_jsx_runtime.JSX.Element;
 
@@ -883,4 +1001,4 @@ declare function useAuth(code?: string | string[], config?: Options): {
 declare function useMenuList(): _tanstack_react_query.UseQueryResult<MenuListItem[], Error>;
 declare const useGames: () => _tanstack_react_query.UseQueryResult<Game[], Error>;
 
-export { APP_ID_HEADER, AuthButton, type AuthButtonProps, type CacheConfig$1 as CacheConfig, DynamicTags, type DynamicTagsProps, ExpandableParagraph, type ExpandableParagraphProps, FRONTEND_ROUTE_PREFIX, FilterFormWrapper, type FilterFormWrapperProps, type Game, GameSelect, type GameSelectConfig, type GameSelectProps, type HeaderExtra, type HeaderExtraConfig, Highlight, type HighlightProps, type HttpMethod$1 as HttpMethod, InfiniteList, InfiniteListAction, type InfiniteListPayload, type InfiniteListProps, type InfiniteListRef, type InfiniteListRequestConfig, type InfiniteListRequestConfigType, Layout, type LayoutProps, Logo, type LogoProps, type MenuListItem, Nav, type NavItem, type NavigationConfig, NotFound, OperationLogList, type Permission, PermissionMode, QueryList, QueryListAction, type QueryListPayload, type QueryListProps, type QueryListRef, type RecursivePartial, RequireAuth, type RequireAuthProps, _default$2 as RequireGame, type RouteMatchRule, SSO_URL, SignIn, ToolkitsProvider, type ToolkitsProviderProps, type UseFormDrawerProps, type UseFormModalProps, UserDropdown, type VisibilityState, WILDCARD, createVisibilityStore, generateId, _default$1 as menu, mixedStorage, _default as permission, useAuth, useDrawer, useDrawerStore, useFormDrawer, useFormModal, useGames, useInfiniteListStore, useMenuList, useModal, useModalStore, useQueryListStore, useToolkitsStore };
+export { APP_ID_HEADER, AuthButton, type AuthButtonProps, type CacheConfig$1 as CacheConfig, DynamicTags, type DynamicTagsProps, ExpandableParagraph, type ExpandableParagraphProps, FRONTEND_ROUTE_PREFIX, FilterFormWrapper, type FilterFormWrapperProps, type Game, GameSelect, type GameSelectConfig, type GameSelectProps, type HeaderExtra, type HeaderExtraConfig, Highlight, type HighlightProps, type HttpMethod$1 as HttpMethod, InfiniteList, type InfiniteListDataAdapter, type InfiniteListPayload, type InfiniteListProps, type InfiniteListRef, type InfiniteListRequestConfig, type InfiniteListRequestConfigType, Layout, type LayoutProps, Logo, type LogoProps, type MenuListItem, Nav, type NavItem, type NavigationConfig, NotFound, OperationLogList, type Permission, PermissionMode, QueryList, QueryListAction, type QueryListPayload, type QueryListProps, type QueryListRef, type RecursivePartial, RequireAuth, type RequireAuthProps, _default$2 as RequireGame, type RouteMatchRule, SSO_URL, SignIn, ToolkitsProvider, type ToolkitsProviderProps, type UseFormDrawerProps, type UseFormModalProps, UserDropdown, type VisibilityState, WILDCARD, createVisibilityStoreConfig, generateId, _default$1 as menu, mixedStorage, _default as permission, useAuth, useDrawer, useDrawerStore, useFormDrawer, useFormModal, useGames, useInfiniteListStore, useMenuList, useModal, useModalStore, useQueryListStore, useToolkitsStore };