nfx-ui 0.7.4 → 0.8.0

package/dist/src/designs/components/VirtualWindowList/index.d.ts

@@ -0,0 +1,41 @@
+import { VirtualizerOptions } from '@tanstack/react-virtual';
+import { ReactNode } from 'react';
+export interface VirtualWindowListProps<T> extends Partial<Omit<VirtualizerOptions<Window, Element>, "count" | "getScrollElement" | "observeElementRect" | "observeElementOffset" | "scrollToFn" | "estimateSize" | "getItemKey">> {
+    /** 数据列表。Data array. */
+    data: T[];
+    /** 是否有下一页。Has next page. */
+    hasNextPage?: boolean;
+    /** 是否正在拉取下一页。Is fetching next page. */
+    isFetchingNextPage?: boolean;
+    /** 拉取下一页。Fetch next page. */
+    fetchNextPage?: () => void;
+    /** 单项渲染。Render item. */
+    renderItem: (item: T, index: number) => ReactNode;
+    /** 单项高度估计。Estimate item size. */
+    estimateSize?: number | ((index: number) => number);
+    /** 列表高度。List height. */
+    height?: string | number;
+    /** 单项 key。Get item key. */
+    getItemKey: (item: T, index: number) => string | number;
+    /** 空状态自定义节点。Empty state node. */
+    emptyState?: ReactNode;
+    /** 加载更多指示器。Loading indicator node. */
+    loadingIndicator?: ReactNode;
+    /** 列表底指示器。End of list indicator node. */
+    endOfListIndicator?: ReactNode;
+    /** 空状态文案（未提供 emptyState 时）。Empty text. */
+    emptyText?: string;
+    /** 加载更多文案。Loading more text. */
+    loadingMoreText?: string;
+    /** 列表底文案。End of list text. */
+    endOfListText?: string;
+    /** 列表项容器 className。Flex container class. */
+    flexClass?: string;
+    /** 外层容器 className。Outer class. */
+    outerClass?: string;
+    /** 内层容器 className。Inner class. */
+    innerClass?: string;
+}
+declare function VirtualWindowListComponent<T>({ data, hasNextPage, isFetchingNextPage, fetchNextPage, renderItem, estimateSize, overscan, height, getItemKey, emptyState, loadingIndicator, endOfListIndicator, emptyText, loadingMoreText, endOfListText, flexClass, outerClass, innerClass, ...virtualizerOptions }: VirtualWindowListProps<T>): import("react/jsx-runtime").JSX.Element;
+declare const VirtualWindowList: typeof VirtualWindowListComponent;
+export default VirtualWindowList;

package/dist/src/designs/components/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 组件统一入口：所有组件及类型在底部集中导出。Components barrel; all components and types exported at bottom.
+ */
+export { default as Button } from './Button';
+export type { ButtonProps } from './Button';
+export { default as Dropdown } from './Dropdown';
+export type { DropdownOption, DropdownProps } from './Dropdown';
+export { default as Icon } from './Icon';
+export type { IconName, IconProps } from './Icon';
+export { default as Input } from './Input';
+export type { InputProps } from './Input';
+export { default as KeyValueEditor } from './KeyValueEditor';
+export type { KeyValueEditorProps, KeyValuePair } from './KeyValueEditor';
+export { default as SearchInput } from './SearchInput';
+export type { SearchInputProps } from './SearchInput';
+export { default as ShowFilter } from './ShowFilter';
+export type { ShowFilterProps, ShowFilterValue } from './ShowFilter';
+export { default as SlideDownSwitcher } from './SlideDownSwitcher';
+export type { SlideDownSwitcherProps } from './SlideDownSwitcher';
+export { default as ThemeSwitcher } from './ThemeSwitcher';
+export type { ThemeSwitcherProps } from '../../../themes/types';
+export { default as LayoutSwitcher } from './LayoutSwitcher';
+export type { LayoutSwitcherProps } from '../../../designs/layouts/types';
+export { default as Slider } from './Slider';
+export type { SliderProps } from './Slider';
+export { default as Suspense } from './Suspense';
+export type { SuspenseProps } from './Suspense';
+export { default as Textarea } from './Textarea';
+export type { TextareaProps } from './Textarea';
+export { default as VirtualList } from './VirtualList';
+export type { VirtualListProps } from './VirtualList';
+export { default as VirtualWindowList } from './VirtualWindowList';
+export type { VirtualWindowListProps } from './VirtualWindowList';

package/dist/src/designs/layouts/components/Background/index.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+import { DashboardBackgroundEnum } from '../../../../../preference';
+interface BackgroundProps {
+    children: ReactNode;
+    /** 可选：外部传入的偏好，有则优先使用；否则从 profile.preference 解析。Optional: preference from parent; otherwise parsed from profile. */
+    background?: DashboardBackgroundEnum | null;
+}
+/** 与 NFX-Identity/console 一致：仪表盘背景由用户偏好（可外部传入或从 profile 解析） */
+declare const Background: import('react').MemoExoticComponent<({ children, background }: BackgroundProps) => import("react/jsx-runtime").JSX.Element>;
+export default Background;
+export type { BackgroundProps };

package/dist/src/designs/layouts/components/Footer/index.d.ts

@@ -0,0 +1,5 @@
+import { FooterProps } from '../../types';
+export declare const DefaultFooterContent: import('react').MemoExoticComponent<() => import("react/jsx-runtime").JSX.Element>;
+/** 通用 Footer：只负责布局与样式，内容由外部传入。 */
+declare const Footer: import('react').MemoExoticComponent<({ children, className }: FooterProps) => import("react/jsx-runtime").JSX.Element>;
+export default Footer;

package/dist/src/designs/layouts/components/Header/index.d.ts

@@ -0,0 +1,4 @@
+import { HeaderProps } from '../../types';
+/** 通用 Header：只负责布局左右两栏，内容全部由外部传入，内部不获取数据。Generic header: layout only; all content from props. */
+declare const Header: import('react').MemoExoticComponent<({ leftContent, rightContent }: HeaderProps) => import("react/jsx-runtime").JSX.Element>;
+export default Header;

package/dist/src/designs/layouts/components/LayoutFrame/index.d.ts

@@ -0,0 +1,3 @@
+import { LayoutFrameProps } from '../../types';
+export declare const LayoutFrame: import('react').MemoExoticComponent<({ children, headerLeft, headerRight, footerContent, sidebarItems, sidebarCurrentPathname, onSidebarNavigate, sidebarLogoutLabel, onSidebarLogout, bottomLogoutButton, }: LayoutFrameProps) => import("react/jsx-runtime").JSX.Element>;
+export default LayoutFrame;

package/dist/src/designs/layouts/components/MainWrapper/index.d.ts

@@ -0,0 +1,3 @@
+import { MainWrapperProps } from '../../types';
+declare const MainWrapper: import('react').MemoExoticComponent<({ children, headerLeft, headerRight, footerContent }: MainWrapperProps) => import("react/jsx-runtime").JSX.Element>;
+export default MainWrapper;

package/dist/src/designs/layouts/components/SideHideLayout/index.d.ts

@@ -0,0 +1,3 @@
+import { SideHideLayoutProps } from '../../types';
+declare const SideHideLayout: import('react').MemoExoticComponent<({ children, headerHeight, footerHeight, sidebarItems, sidebarCurrentPathname, onSidebarNavigate, sidebarLogoutLabel, onSidebarLogout, }: SideHideLayoutProps) => import("react/jsx-runtime").JSX.Element>;
+export default SideHideLayout;

package/dist/src/designs/layouts/components/SideShowLayout/index.d.ts

@@ -0,0 +1,3 @@
+import { SideShowLayoutProps } from '../../types';
+declare const SideShowLayout: import('react').MemoExoticComponent<({ children, headerHeight, footerHeight, sidebarItems, sidebarCurrentPathname, onSidebarNavigate, sidebarLogoutLabel, onSidebarLogout, }: SideShowLayoutProps) => import("react/jsx-runtime").JSX.Element>;
+export default SideShowLayout;

package/dist/src/designs/layouts/components/Sidebar/index.d.ts

@@ -0,0 +1,3 @@
+import { SidebarProps } from '../../types';
+declare const Sidebar: import('react').MemoExoticComponent<({ children, collapsed, toggled, onBackdropClick, breakPoint, className, items, currentPathname, onNavigate, logoutLabel, handleLogout, bottomLogoutButton, }: SidebarProps) => import("react/jsx-runtime").JSX.Element>;
+export default Sidebar;

package/dist/src/designs/layouts/components/index.d.ts

@@ -0,0 +1,8 @@
+export { default as Sidebar } from './Sidebar';
+export { default as MainWrapper } from './MainWrapper';
+export { default as SideHideLayout } from './SideHideLayout';
+export { default as SideShowLayout } from './SideShowLayout';
+export { default as Footer } from './Footer';
+export { default as Header } from './Header';
+export { default as Background } from './Background';
+export { default as LayoutFrame } from './LayoutFrame';

package/dist/src/designs/layouts/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export * from './useLayout';
+export * from './useSet';
+export * from './useAction';

package/dist/src/designs/layouts/hooks/useAction.d.ts

@@ -0,0 +1,7 @@
+declare const useAction: () => {
+    sidebarOpen: boolean;
+    setSidebarOpen: (open: boolean) => void;
+    toggleSidebar: () => void;
+    closeSidebar: () => void;
+};
+export default useAction;

package/dist/src/designs/layouts/hooks/useLayout.d.ts

@@ -0,0 +1,5 @@
+import { LayoutContextType } from '../types';
+declare const LayoutContext: import('react').Context<LayoutContextType | undefined>;
+declare const useLayout: () => LayoutContextType;
+export default useLayout;
+export { LayoutContext, useLayout };

package/dist/src/designs/layouts/hooks/useSet.d.ts

@@ -0,0 +1,10 @@
+import { LayoutModeEnum } from '../types';
+interface UseSetProps {
+    defaultLayoutMode: LayoutModeEnum;
+    sidebarOpen: boolean;
+}
+declare const useSet: ({ defaultLayoutMode, sidebarOpen }: UseSetProps) => {
+    layoutMode: LayoutModeEnum;
+    setLayoutMode: (mode: LayoutModeEnum) => void;
+};
+export default useSet;

package/dist/src/designs/layouts/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 布局模块统一导出。Layouts module barrel exports.
+ */
+export * from './types';
+export * from './utils';
+export * from './components';
+export * from './hooks';
+export { default as LayoutProvider } from './providers';

package/dist/src/designs/layouts/providers/index.d.ts

@@ -0,0 +1,3 @@
+import { LayoutProviderProps } from '../types';
+declare const LayoutProvider: import('react').MemoExoticComponent<({ children, defaultLayoutMode }: LayoutProviderProps) => import("react/jsx-runtime").JSX.Element>;
+export default LayoutProvider;

package/dist/src/designs/layouts/types/components.d.ts

@@ -0,0 +1,117 @@
+import { ReactNode } from 'react';
+import { SidebarProps as ProSidebarProps } from 'react-pro-sidebar';
+import { LayoutModeEnum } from './layout';
+/** 侧栏菜单项。Sidebar menu item. */
+export interface SidebarMenuItem {
+    label: string;
+    path: string;
+    icon: ReactNode;
+    /** Sub-items for SubMenu. Omit for a leaf item. */
+    children?: SidebarMenuItem[];
+}
+/** 布局 Provider 的 props。LayoutProvider props. */
+export interface LayoutProviderProps {
+    /** 子节点。Children. */
+    children: ReactNode;
+    /** 默认布局模式（显示/隐藏侧栏）。Default layout mode (show/hide sidebar). */
+    defaultLayoutMode?: LayoutModeEnum;
+}
+/** 布局切换器 props。LayoutSwitcher props. */
+export interface LayoutSwitcherProps {
+    /** 样式状态。Visual status. */
+    status?: "primary" | "default";
+    /** 显示模式标签（未传 getLayoutDisplayName 且无内置翻译时使用）。Show mode label. */
+    showLabel?: string;
+    /** 隐藏模式标签（未传 getLayoutDisplayName 且无内置翻译时使用）。Hide mode label. */
+    hideLabel?: string;
+    /** 根据布局模式返回展示名；未传则使用 showLabel / hideLabel。Display name for layout mode; default uses showLabel/hideLabel. */
+    getLayoutDisplayName?: (mode: LayoutModeEnum) => string;
+    /** 处理布局模式改变。Handle layout mode change. */
+    handleChangeLayoutMode?: (mode: LayoutModeEnum) => void;
+}
+/** LayoutFrame props. */
+export interface LayoutFrameProps {
+    children: ReactNode;
+    /** 可选：Header 左侧内容（如 Logo、SlideDownSwitcher），使用方传入。Optional: header left slot. */
+    headerLeft?: ReactNode;
+    /** 可选：Header 右侧内容（如语言、用户菜单），使用方传入。Optional: header right slot. */
+    headerRight?: ReactNode;
+    /** 可选：Footer 内容（children），使用方传入。Optional: footer content. */
+    footerContent?: ReactNode;
+    /** 可选：侧栏菜单项。Optional: sidebar menu items. */
+    sidebarItems?: SidebarMenuItem[];
+    /** 可选：当前路径，用于高亮。传 useLocation().pathname。Optional: current pathname for active state. */
+    sidebarCurrentPathname?: string;
+    /** 可选：点击菜单项时调用。Optional: called when a sidebar item is clicked. */
+    onSidebarNavigate?: (path: string) => void;
+    /** 可选：侧栏底部登出按钮文案。Optional: logout button label. */
+    sidebarLogoutLabel?: string;
+    /** 可选：侧栏登出回调。Optional: logout handler. */
+    onSidebarLogout?: () => void;
+    /** 可选：侧栏底部登出按钮。Optional: bottom logout button. */
+    bottomLogoutButton?: ReactNode;
+}
+/** Sidebar props（扩展 react-pro-sidebar）. */
+export interface SidebarProps extends ProSidebarProps {
+    children?: ReactNode;
+    collapsed?: boolean;
+    toggled?: boolean;
+    onBackdropClick?: () => void;
+    className?: string;
+    /** Menu items. Rendered when no children. */
+    items?: SidebarMenuItem[];
+    /** Current pathname for active state. Pass from useLocation().pathname. */
+    currentPathname?: string;
+    /** Called when a menu item is clicked. Parent should navigate to path. */
+    onNavigate?: (path: string) => void;
+    /** Logout label. */
+    logoutLabel?: string;
+    /** Handle logout. */
+    handleLogout?: () => void;
+    /** Bottom Logout Button. */
+    bottomLogoutButton?: ReactNode;
+}
+/** MainWrapper props. */
+export interface MainWrapperProps {
+    children: (headerHeight: number, footerHeight: number) => ReactNode;
+    headerLeft?: ReactNode;
+    headerRight?: ReactNode;
+    footerContent?: ReactNode;
+}
+/** SideHideLayout props. */
+export interface SideHideLayoutProps {
+    children: ReactNode;
+    headerHeight: number;
+    footerHeight: number;
+    sidebarItems?: SidebarMenuItem[];
+    sidebarCurrentPathname?: string;
+    onSidebarNavigate?: (path: string) => void;
+    sidebarLogoutLabel?: string;
+    onSidebarLogout?: () => void;
+    bottomLogoutButton?: ReactNode;
+}
+/** SideShowLayout props. */
+export interface SideShowLayoutProps {
+    children: ReactNode;
+    headerHeight: number;
+    footerHeight: number;
+    sidebarItems?: SidebarMenuItem[];
+    sidebarCurrentPathname?: string;
+    onSidebarNavigate?: (path: string) => void;
+    sidebarLogoutLabel?: string;
+    onSidebarLogout?: () => void;
+    bottomLogoutButton?: ReactNode;
+}
+/** Footer props. */
+export interface FooterProps {
+    /** 页脚内容由使用方传入。Footer content passed from parent. */
+    children?: ReactNode;
+    className?: string;
+}
+/** Header props. */
+export interface HeaderProps {
+    /** 左侧内容（如 Logo、SlideDownSwitcher 等），由使用方传入。Left slot; passed from parent. */
+    leftContent?: ReactNode;
+    /** 右侧内容（如语言切换、用户菜单等），由使用方传入。Right slot; passed from parent. */
+    rightContent?: ReactNode;
+}

package/dist/src/designs/layouts/types/context.d.ts

@@ -0,0 +1,12 @@
+import { LayoutModeEnum } from './layout';
+/** useLayout 返回值类型。Return type of useLayout. */
+export interface LayoutContextType {
+    /** 侧栏是否展开。Whether sidebar is open. */
+    sidebarOpen: boolean;
+    /** 当前布局模式（显示/隐藏）。Current layout mode (show/hide). */
+    layoutMode: LayoutModeEnum;
+    setSidebarOpen: (open: boolean) => void;
+    toggleSidebar: () => void;
+    closeSidebar: () => void;
+    setLayoutMode: (mode: LayoutModeEnum) => void;
+}

package/dist/src/designs/layouts/types/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 布局模块类型统一导出。All layout module types re-exported.
+ */
+export * from './layout';
+export * from './context';
+export * from './components';

package/dist/src/designs/layouts/types/layout.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 布局模式枚举与常量。Layout mode enum and constants.
+ */
+declare enum LayoutModeEnum {
+    SHOW = "show",
+    HIDE = "hide"
+}
+declare const DEFAULT_LAYOUT_MODE = LayoutModeEnum.SHOW;
+declare const LAYOUT_MODE_VALUES: LayoutModeEnum[];
+declare const LAYOUT_STORAGE_KEY = "layout-storage";
+export { LayoutModeEnum, DEFAULT_LAYOUT_MODE, LAYOUT_MODE_VALUES, LAYOUT_STORAGE_KEY };

package/dist/src/designs/layouts/utils/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 布局模块工具函数。Layout module utils.
+ */
+export { getLayoutStorage, removeLayoutStorage, setLayoutStorage, } from './layoutStorage';

package/dist/src/designs/layouts/utils/layoutStorage.d.ts

@@ -0,0 +1,4 @@
+import { Nilable } from '../../../../types/utils';
+export declare function getLayoutStorage(): Nilable<string>;
+export declare function setLayoutStorage(value: string): void;
+export declare function removeLayoutStorage(): void;

package/dist/src/events/EventEmitter.d.ts

@@ -0,0 +1,48 @@
+import { Defined } from '../../types';
+/** 回调类型：内部存储与 on/off 默认(unknown)时均用此，任意函数即可，无需 as 断言。 */
+type EventCallback = (...args: any[]) => void;
+/**
+ * 将 PayloadMap[K] 规范为参数元组。
+ * void→[]；unknown（默认）→ [] | [unknown]；单类型 T→[T]；元组→不变。
+ */
+type ToArgs<P> = P extends void ? [] : unknown extends P ? [] | [P] : P extends unknown[] ? P : [P];
+/** 由 defineEvents 返回的「已规范事件名对象」类型；constructor 只接受此类型。 */
+type DefinedEvents<T extends Record<string, string>> = Defined<T, "events">;
+/** 从 events 对象推导出事件名联合类型。Event name union from an events key-value object. */
+type EventNamesOf<T> = T extends Defined<infer O, "events"> ? O[keyof O] : T extends Record<string, string> ? T[keyof T] : never;
+/**
+ * 规范创建「一级 key-value」事件名对象：仅允许 key → 字符串 value，禁止嵌套（类型约束）。
+ * 返回 DefinedEvents<T>，供 EventEmitter 构造使用。
+ * Define events object: one-level key-value (string values), no nested objects (type-only). Returns DefinedEvents<T> for EventEmitter.
+ *
+ * @param events - 事件名 key-value 对象。Event name key-value object (e.g. { FOO: "DOMAIN:FOO" }).
+ * @returns DefinedEvents<E>，仅此类型可传入 EventEmitter 构造。DefinedEvents<E>; only this type is accepted by EventEmitter constructor.
+ * @example
+ * ```ts
+ * const routerEvents = defineEvents({ NAVIGATE: "ROUTER:NAVIGATE", NAVIGATE_BACK: "ROUTER:NAVIGATE_BACK" });
+ * class RouterEmitter extends EventEmitter<EventNamesOf<typeof routerEvents>> { constructor() { super(routerEvents); } }
+ * ```
+ */
+declare function defineEvents<E extends Record<string, string>>(events: E): DefinedEvents<E>;
+/**
+ * 泛型 EventEmitter：构造函数仅接受 defineEvents 返回的 DefinedEvents 类型，提供 on / off / emit。
+ * PayloadMap[K] 可为 void（无参）、单类型 T（单参）、或元组 [A, B, ...]（多参），统一规范为参数列表。
+ * PayloadMap[K] can be void (no args), single type T (one arg), or tuple [A, B, ...] (multi arg).
+ *
+ * @param events - 须为 defineEvents(...) 的返回值（DefinedEvents）。Must be the return value of defineEvents(...) (DefinedEvents).
+ */
+declare class EventEmitter<E extends string, PayloadMap extends Record<E, unknown> = Record<E, unknown>> {
+    private listeners;
+    constructor(events: DefinedEvents<Record<string, E>>);
+    /** 注册事件监听；回调为任意函数，由 emit 时传入的参数决定实际类型。 */
+    on<K extends E>(event: K, callback: EventCallback): void;
+    /** 移除事件监听（需与 on 时同一引用）。 */
+    off<K extends E>(event: K, callback: EventCallback): void;
+    /**
+     * 触发事件；参数与 PayloadMap[K] 一致：void 无参，T 单参，[A,B] 多参。
+     * Emit an event; args match PayloadMap[K]: void → no args, T → one arg, [A,B] → spread.
+     */
+    emit<K extends E>(event: K, ...args: ToArgs<PayloadMap[K]>): void;
+}
+export { EventEmitter, defineEvents };
+export type { EventCallback, DefinedEvents, EventNamesOf };

package/dist/src/events/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 事件模块：仅导出通用 EventEmitter。各域发射器请直接按路径引用（如 @/events/router）。
+ * Events module: exports only the generic EventEmitter. Use direct paths for domain emitters (e.g. @/events/router).
+ */
+export * from './EventEmitter';

package/dist/src/hooks/index.d.ts

@@ -0,0 +1,4 @@
+export * from './makeUnifiedInfiniteQuery';
+export * from './makeCursorFetchFunction';
+export * from './makeUnifiedQuery';
+export * from './type';

package/dist/src/hooks/makeCursorFetchFunction.d.ts

@@ -0,0 +1,84 @@
+import { ListDTOWithNextCursor, ListDTOWithTotalNumber } from '../../types/api';
+import { FetchNumberListParams, FetchStringListParams } from './type';
+/**
+ * 创建基于游标（Cursor）的分页获取函数
+ *
+ * 将标准的分页 API（基于 offset/limit）转换为游标分页函数，用于无限查询。
+ * 自动计算下一页游标，并支持数据后处理。
+ *
+ * @template T - 数据项类型
+ * @template F - 过滤器对象类型，必须是对象类型，默认为 Record<string, unknown>
+ *
+ * @param {Function} fetchFunc - 远程数据获取函数，接收 FetchListParams 参数，返回包含 items 和 total 的结果
+ * @param {number} [pageSize=20] - 每页数据条数，默认 20
+ * @param {Function} [postProcess] - 可选的数据后处理函数，在每次数据获取后调用
+ *
+ * @returns {Function} 返回一个游标分页函数，接收 pageParam（页码）和 filter（过滤器）参数
+ *
+ * @example
+ * ```tsx
+ * * 定义标准的分页 API
+ * const fetchProductsAPI = async (params: { offset: number; limit: number; category?: string }) => {
+ *   const response = await fetch('/api/products?' + new URLSearchParams(params));
+ *   const { items, total } = await response.json();
+ *   return { items, total };
+ * };
+ *
+ * * 创建游标分页函数
+ * const fetchProducts = makeCursorFetchFunction(
+ *   fetchProductsAPI,
+ *   20,
+ *   (data) => {
+ *     * 数据后处理：为每个商品添加缓存
+ *     data.forEach(product => cache.set(product.id, product));
+ *   }
+ * );
+ *
+ * * 使用游标函数
+ * const firstPage = await fetchProducts(0, { category: "electronics" });
+ * * 返回: ListDTOWithTotalNumber<Product> = { items, total }
+ * * getNextPageParam 由 makeUnifiedInfiniteQuery 根据 total 与 pageSize 计算
+ * ```
+ *
+ * @remarks
+ * **为什么需要游标转换？**
+ * - React Query 的无限查询使用 pageParam（游标）来跟踪分页位置
+ * - 后端 API 通常使用 offset/limit 分页，两者需要转换才能配合使用
+ * - 游标模式更适合无限滚动，避免在组件中手动计算 offset
+ *
+ * **游标计算逻辑：**
+ * - **offset 计算**：`offset = pageParam × pageSize`
+ *   - 示例：pageParam=0 → offset=0（第一页）
+ *   - 示例：pageParam=2, pageSize=20 → offset=40（第三页，跳过前 40 条）
+ * - **nextCursor 判断**：`(pageParam + 1) × pageSize < total ? pageParam + 1 : undefined`
+ *   - 如果下一页的起始位置小于总数，返回下一页页码
+ *   - 否则返回 undefined，告知 React Query 没有更多数据
+ *
+ * **为什么 pageParam 从 0 开始？**
+ * - 符合数组索引习惯，第 0 页、第 1 页...
+ * - 计算 offset 时公式更简洁：`offset = pageParam × pageSize`
+ * - 避免使用 1-based 索引时需要额外的 -1 运算
+ *
+ * **postProcess 的作用：**
+ * - 在数据返回后、缓存前执行，适合进行副作用操作
+ * - 常见用途：更新单项缓存、触发分析事件、数据预处理
+ * - 不影响返回值，保持数据流的纯净性
+ */
+declare function makeCursorFetchFunction<T, F extends object = Record<string, unknown>>(fetchFunc: (params: FetchNumberListParams<F>) => Promise<ListDTOWithTotalNumber<T>>, pageSize?: number, postProcess?: (data: T[]) => void): (pageParam?: number, filter?: F) => Promise<ListDTOWithTotalNumber<T>>;
+/**
+ * 创建基于字符串游标的分页获取函数（用于 nextCursor 为 string 的 API）。
+ * Creates cursor-based fetch function for string cursor (API returns nextCursor: string).
+ *
+ * @param fetchFunc - 远程获取函数，参数含 offset: string, limit，返回 { items, nextCursor }。Fetch (params: FetchStringListParams<F>) => Promise<ListDTOWithNextCursor<T>>.
+ * @param pageSize - 每页条数，默认 20。Page size.
+ * @param postProcess - 可选，数据返回后调用。Optional post-process (data: T[]) => void.
+ * @returns 返回 (pageParam: string, filter?: F) => Promise<ListDTOWithNextCursor<T>>。Returns async cursor fetcher.
+ * @example
+ * ```ts
+ * const fetch = makeStringCursorFetchFunction(fetchByToken, 20);
+ * const page = await fetch("", { q: "x" });
+ * if (page.nextCursor) await fetch(page.nextCursor, { q: "x" });
+ * ```
+ */
+declare function makeStringCursorFetchFunction<T, F extends object = Record<string, unknown>>(fetchFunc: (params: FetchStringListParams<F>) => Promise<ListDTOWithNextCursor<T>>, pageSize?: number, postProcess?: (data: T[]) => void): (pageParam?: string, filter?: F) => Promise<ListDTOWithNextCursor<T>>;
+export { makeCursorFetchFunction, makeStringCursorFetchFunction };

package/dist/src/hooks/makeUnifiedInfiniteQuery.d.ts

@@ -0,0 +1,124 @@
+import { QueryKey, UseInfiniteQueryResult, UseSuspenseInfiniteQueryResult } from '@tanstack/react-query';
+import { AxiosError } from 'axios';
+import { ListDTOWithTotalNumber } from '../../types/api';
+import { FetchNumberListParams, InfiniteQueryOptions, SuspenseInfiniteQueryOptions } from './type';
+/**
+ * 创建统一的无限查询 Hook（Suspense 模式）
+ *
+ * 这是一个高阶函数工厂，用于创建支持无限滚动的数据查询 Hook。
+ * 它自动处理分页、缓存、错误重试等常见场景，并支持 Suspense 模式。
+ *
+ * @template T - 数据项类型
+ * @template F - 过滤器对象类型，必须是对象类型，默认为 Record<string, unknown>
+ *
+ * @param {Function} fetchRemote - 远程数据获取函数，接收分页参数和过滤器，返回 Promise
+ * @param {string} mode - 查询模式，设置为 "suspense" 启用 React Suspense 支持
+ * @param {number} [pageSize=20] - 每页数据条数，默认 20
+ * @param {Function} [postProcess] - 可选的数据后处理函数，在数据返回后调用
+ *
+ * @returns {Function} 返回一个 Hook 函数，接收 queryKey、filter 和 options 参数
+ *
+ * @example
+ * ```tsx
+ * * 定义 API 获取函数
+ * const fetchProducts = async (params: FetchListParams<ProductFilter>) => {
+ *   const { items, total } = await api.getProducts(params);
+ *   return { items, total };
+ * };
+ *
+ * * 创建 Hook（Suspense 模式）
+ * const useProductList = makeUnifiedInfiniteQuery(
+ *   fetchProducts,
+ *   "suspense",
+ *   20,
+ *   (data) => console.warn('数据已加载:', data.length)
+ * );
+ *
+ * * 在组件中使用
+ * function ProductList() {
+ *   const { data, fetchNextPage, hasNextPage } = useProductList(
+ *     ["products"],
+ *     { category: "electronics" },
+ *     { staleTime: 60000 }
+ *   );
+ *
+ *   return (
+ *     <div>
+ *       {data.map(product => <ProductCard key={product.id} {...product} />)}
+ *       {hasNextPage && <button onClick={() => fetchNextPage()}>加载更多</button>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * **为什么需要这个函数？**
+ * - React Query 的无限查询 API 较为底层，需要手动配置 queryFn、initialPageParam、getNextPageParam 等
+ * - 大多数列表查询都有相似的分页逻辑（offset/limit），重复编写这些配置容易出错
+ * - 通过工厂函数统一封装，确保分页逻辑的一致性，减少样板代码
+ *
+ * **为什么区分 Suspense 和普通模式？**
+ * - Suspense 模式：数据未就绪时会挂起组件渲染，适合配合 React Suspense 边界使用
+ * - 普通模式：提供 isLoading 状态，需要手动处理加载状态，更灵活
+ * - 两种模式的 Hook 返回类型不同，TypeScript 需要通过函数重载区分
+ *
+ * **内部实现原理：**
+ * 1. **游标转换**：使用 makeCursorFetchFunction 将 offset/limit 转换为页码游标
+ * 2. **查询键构造**：自动将 filter 合并到 queryKey 中，确保不同过滤条件有独立缓存
+ * 3. **数据扁平化**：通过 select 将分页数据 pages 扁平化为单一数组，简化组件使用
+ * 4. **智能重试**：仅对 5xx 服务器错误和网络错误重试，避免对 4xx 客户端错误无意义重试
+ * 5. **选项合并**：使用 spread 运算符允许外部覆盖默认配置（如 staleTime、retry）
+ */
+declare function makeUnifiedInfiniteQuery<T, F extends object = Record<string, unknown>>(fetchRemote: (params: FetchNumberListParams<F>) => Promise<ListDTOWithTotalNumber<T>>, mode: "suspense", pageSize?: number, postProcess?: (data: T[]) => void): (queryKey: QueryKey, filter?: F, options?: SuspenseInfiniteQueryOptions<T>) => UseSuspenseInfiniteQueryResult<T[], AxiosError>;
+/**
+ * 创建统一的无限查询 Hook（普通模式）
+ *
+ * 这是一个高阶函数工厂，用于创建支持无限滚动的数据查询 Hook。
+ * 它自动处理分页、缓存、错误重试等常见场景，普通模式不使用 Suspense。
+ *
+ * @template T - 数据项类型
+ * @template F - 过滤器对象类型，必须是对象类型，默认为 Record<string, unknown>
+ *
+ * @param {Function} fetchRemote - 远程数据获取函数，接收分页参数和过滤器，返回 Promise
+ * @param {string} [mode="normal"] - 查询模式，设置为 "normal" 或省略使用普通模式
+ * @param {number} [pageSize=20] - 每页数据条数，默认 20
+ * @param {Function} [postProcess] - 可选的数据后处理函数，在数据返回后调用
+ *
+ * @returns {Function} 返回一个 Hook 函数，接收 queryKey、filter 和 options 参数
+ *
+ * @example
+ * ```tsx
+ * * 定义 API 获取函数
+ * const fetchProducts = async (params: FetchListParams<ProductFilter>) => {
+ *   const { items, total } = await api.getProducts(params);
+ *   return { items, total };
+ * };
+ *
+ * * 创建 Hook（普通模式）
+ * const useProductList = makeUnifiedInfiniteQuery(
+ *   fetchProducts,
+ *   "normal",  * 或省略此参数
+ *   20
+ * );
+ *
+ * * 在组件中使用
+ * function ProductList() {
+ *   const { data, fetchNextPage, hasNextPage, isLoading } = useProductList(
+ *     ["products"],
+ *     { category: "electronics" },
+ *     { staleTime: 60000 }
+ *   );
+ *
+ *   if (isLoading) return <Loading />;
+ *
+ *   return (
+ *     <div>
+ *       {data?.map(product => <ProductCard key={product.id} {...product} />)}
+ *       {hasNextPage && <button onClick={() => fetchNextPage()}>加载更多</button>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function makeUnifiedInfiniteQuery<T, F extends object = Record<string, unknown>>(fetchRemote: (params: FetchNumberListParams<F>) => Promise<ListDTOWithTotalNumber<T>>, mode?: "normal", pageSize?: number, postProcess?: (data: T[]) => void): (queryKey: QueryKey, filter?: F, options?: InfiniteQueryOptions<T>) => UseInfiniteQueryResult<T[], AxiosError>;
+export { makeUnifiedInfiniteQuery };

package/dist/src/hooks/makeUnifiedQuery.d.ts

@@ -0,0 +1,19 @@
+import { QueryKey, UseQueryOptions, UseQueryResult, UseSuspenseQueryOptions, UseSuspenseQueryResult } from '@tanstack/react-query';
+import { AxiosError } from 'axios';
+/**
+ * 创建统一的单条查询 Hook 工厂（支持 normal / suspense 模式）。
+ * Creates a unified single-item query Hook factory (normal or suspense mode).
+ *
+ * @param fetchRemote - 拉取函数，接收 filter 返回 Promise<T>。Fetch function (params: F) => Promise<T>.
+ * @param mode - "suspense" 或 "normal"（默认）。Query mode.
+ * @param postProcess - 可选，数据返回后调用。Optional post-process (data: T) => void.
+ * @returns 返回一个 Hook：(queryKey, filter?, options?) => UseQueryResult 或 UseSuspenseQueryResult。Returns a Hook.
+ * @example
+ * ```ts
+ * const useProfile = makeUnifiedQuery(fetchProfile, "normal");
+ * const { data } = useProfile(profileKey, { id }, { enabled: !!id });
+ * ```
+ */
+declare function makeUnifiedQuery<T, F extends object = Record<string, unknown>>(fetchRemote: (params: F) => Promise<T>, mode: "suspense", postProcess?: (data: T) => void): (queryKey: QueryKey, filter?: F, options?: Omit<UseSuspenseQueryOptions<T, AxiosError, T>, "queryKey" | "queryFn">) => UseSuspenseQueryResult<T, AxiosError>;
+declare function makeUnifiedQuery<T, F extends object = Record<string, unknown>>(fetchRemote: (params: F) => Promise<T>, mode?: "normal", postProcess?: (data: T) => void): (queryKey: QueryKey, filter?: F, options?: Omit<UseQueryOptions<T, AxiosError, T>, "queryKey" | "queryFn">) => UseQueryResult<T, AxiosError>;
+export { makeUnifiedQuery };