@chaos_team/chaos-ui 1.0.5

package/dist/hooks.d.ts

@@ -0,0 +1,1148 @@
+import { M as MessageOptions } from './message-KJli9tvf.js';
+import * as React$1 from 'react';
+import * as react_hook_form from 'react-hook-form';
+import { FieldValues, UseFormProps, Resolver } from 'react-hook-form';
+import { UseQueryOptions, UseQueryResult, UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
+export { UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
+
+/**
+ * @hook useBreakpoint
+ * @category hooks/responsive
+ * @since 0.2.0
+ * @description 响应式断点检测 / Responsive breakpoint detection
+ * @returns Current breakpoint key ('xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl')
+ * @example
+ * const bp = useBreakpoint();
+ * if (bp === 'xs') { ... }
+ */
+declare const breakpoints: {
+    readonly xs: 0;
+    readonly sm: 640;
+    readonly md: 768;
+    readonly lg: 1024;
+    readonly xl: 1280;
+    readonly "2xl": 1536;
+};
+type Breakpoint = keyof typeof breakpoints;
+declare function useBreakpoint(): Breakpoint | undefined;
+declare function useIsBreakpoint(breakpoint: Breakpoint): boolean;
+
+/**
+ * @hook useEventListener
+ * @category hooks/effect
+ * @since 0.2.0
+ * @description DOM 事件订阅 / DOM event listener hook
+ * @example
+ * useEventListener(window, 'resize', () => console.log('resized'));
+ * useEventListener(document, 'keydown', handler);
+ */
+declare function useEventListener<T extends HTMLElement | Window | Document | MediaQueryList, K extends keyof WindowEventMap>(target: T | null | undefined, eventName: K, handler: (event: WindowEventMap[K]) => void, options?: AddEventListenerOptions): void;
+declare function useEventListener(target: HTMLElement | Window | Document | MediaQueryList | null | undefined, eventName: string, handler: (event: Event) => void, options?: AddEventListenerOptions): void;
+
+/**
+ * @hook useKey
+ * @category hooks/effect
+ * @since 0.2.0
+ * @description 键盘事件 Hook / Keyboard event hook
+ * @example
+ * useKey('Escape', () => close());
+ * useKey(['Meta+k', 'Control+k'], () => openPalette());
+ */
+type KeyFilter = string | string[] | ((event: KeyboardEvent) => boolean);
+type KeyHandler = (event: KeyboardEvent) => void;
+interface UseKeyOptions {
+    /** Event type: 'keydown' | 'keyup' | 'keypress' / 事件类型 */
+    event?: "keydown" | "keyup" | "keypress";
+    /** Target element (default: window) / 目标元素 */
+    target?: HTMLElement | Window | Document | null;
+    /** Whether to prevent default / 是否阻止默认行为 */
+    preventDefault?: boolean;
+    /** Whether the hook is active / 是否激活 */
+    enabled?: boolean;
+}
+declare function useKey(keys: KeyFilter, handler: KeyHandler, options?: UseKeyOptions): void;
+declare function useKeyCombo(combo: string, handler: KeyHandler, options?: UseKeyOptions): void;
+
+interface MessageInstance {
+    success: (content: React.ReactNode, options?: MessageOptions) => string | number;
+    error: (content: React.ReactNode, options?: MessageOptions) => string | number;
+    warning: (content: React.ReactNode, options?: MessageOptions) => string | number;
+    info: (content: React.ReactNode, options?: MessageOptions) => string | number;
+    loading: (content: React.ReactNode, options?: MessageOptions) => string | number;
+    promise: <T>(promise: Promise<T>, options: {
+        loading?: React.ReactNode;
+        success?: React.ReactNode | ((data: T) => React.ReactNode);
+        error?: React.ReactNode | ((err: unknown) => React.ReactNode);
+    }) => Promise<T>;
+    destroy: (id?: string | number) => void;
+}
+declare function useMessage(): MessageInstance;
+
+/**
+ * @hook useNotification
+ * @category hooks/feedback
+ * @since 0.2.0
+ * @description 命令式通知 API / Imperative notification API (antd App.useApp().notification equivalent)
+ * @example
+ * const notification = useNotification();
+ * notification.open({ title: 'New Order', description: 'Order #123 received' });
+ */
+interface NotificationOptions {
+    id?: string | number;
+    title: React$1.ReactNode;
+    description?: React$1.ReactNode;
+    type?: "success" | "error" | "warning" | "info";
+    duration?: number;
+    position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-center" | "bottom-center";
+    action?: {
+        label: string;
+        onClick: () => void;
+    };
+    dismissible?: boolean;
+}
+interface NotificationInstance {
+    open: (options: NotificationOptions) => string | number;
+    success: (options: Omit<NotificationOptions, "type">) => string | number;
+    error: (options: Omit<NotificationOptions, "type">) => string | number;
+    warning: (options: Omit<NotificationOptions, "type">) => string | number;
+    info: (options: Omit<NotificationOptions, "type">) => string | number;
+    close: (id?: string | number) => void;
+    closeAll: () => void;
+}
+declare function useNotification(): NotificationInstance;
+
+/**
+ * @hook useModal
+ * @category hooks/feedback
+ * @since 0.2.0
+ * @description 命令式模态框 API / Imperative modal API (antd Modal.confirm equivalent)
+ * @example
+ * const modal = useModal();
+ * modal.confirm({ title: 'Delete?', content: 'Are you sure?', onOk: handleDelete });
+ */
+interface ModalOptions {
+    title?: React$1.ReactNode;
+    content?: React$1.ReactNode;
+    okText?: string;
+    cancelText?: string;
+    okVariant?: "default" | "destructive";
+    onOk?: () => void | Promise<void>;
+    onCancel?: () => void;
+    width?: string | number;
+    closable?: boolean;
+    maskClosable?: boolean;
+}
+interface ModalInstance {
+    confirm: (options: ModalOptions) => void;
+    info: (options: Omit<ModalOptions, "okVariant" | "cancelText">) => void;
+    warning: (options: Omit<ModalOptions, "okVariant">) => void;
+    success: (options: Omit<ModalOptions, "okVariant">) => void;
+    error: (options: Omit<ModalOptions, "okVariant">) => void;
+}
+declare function useModal(): ModalInstance;
+/**
+ * Helper component to render the modal from useModal
+ * Usage:
+ * const modal = useModal();
+ * return (<>
+ *   {modal.confirm.modal}
+ *   <Button onClick={() => modal.confirm({ title: 'Hi' })}>Open</Button>
+ * </>)
+ */
+declare function ModalRenderer({ modal }: {
+    modal: ModalInstance;
+}): React$1.JSX.Element;
+
+type AsyncStatus = "idle" | "pending" | "success" | "error";
+declare function useAsync<T, Args extends unknown[] = []>(fn: (...args: Args) => Promise<T>, immediate?: boolean): {
+    run: (...args: Args) => Promise<T | undefined>;
+    isLoading: boolean;
+    status: AsyncStatus;
+    data: T | undefined;
+    error: Error | undefined;
+};
+
+type Handler = (event: MouseEvent | TouchEvent) => void;
+declare function useClickOutside<T extends HTMLElement = HTMLElement>(ref: React$1.RefObject<T | null>, handler: Handler, enabled?: boolean): void;
+
+declare function useCopyToClipboard(): [
+    boolean,
+    (value: string) => Promise<boolean>,
+    () => void
+];
+
+declare function useCountdown(target: Date | number | string): {
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    isFinished: boolean;
+    totalSeconds: number;
+};
+
+declare function useDebounce<T>(value: T, delay?: number): T;
+
+type KeyCombo = string;
+type HotkeyHandler = (event: KeyboardEvent) => void;
+interface HotkeyOptions {
+    enabled?: boolean;
+    preventDefault?: boolean;
+    allowInInputs?: boolean;
+}
+declare function useHotkeys(keys: Record<KeyCombo, HotkeyHandler>, options?: HotkeyOptions): void;
+
+interface UseInfiniteScrollOptions {
+    threshold?: number;
+    rootMargin?: string;
+    enabled?: boolean;
+}
+declare function useInfiniteScroll<T>(loadMore: () => Promise<{
+    items: T[];
+    hasMore: boolean;
+}> | {
+    items: T[];
+    hasMore: boolean;
+}, options?: UseInfiniteScrollOptions): {
+    items: T[];
+    hasMore: boolean;
+    loading: boolean;
+    error: Error | null;
+    sentinelRef: React$1.RefObject<HTMLDivElement | null>;
+    loadMore: () => Promise<void>;
+    reset: () => void;
+};
+
+interface Options {
+    root?: Element | null;
+    rootMargin?: string;
+    threshold?: number | number[];
+    triggerOnce?: boolean;
+    enabled?: boolean;
+}
+declare function useIntersectionObserver<T extends Element>(ref: React$1.RefObject<T | null>, options?: Options): IntersectionObserverEntry | null;
+declare function useInView<T extends Element>(ref: React$1.RefObject<T | null>, options?: Omit<Options, "enabled">): boolean;
+
+declare function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T | ((prev: T) => T)) => void, () => void];
+
+declare function useMediaQuery(query: string): boolean;
+declare const useIsDesktop: (breakpoint?: number) => boolean;
+declare const useIsTablet: (min?: number, max?: number) => boolean;
+
+declare function useIsMobile(): boolean;
+
+interface PaginationState {
+    page: number;
+    pageSize: number;
+}
+interface PaginationResult extends PaginationState {
+    total: number;
+    totalPages: number;
+    offset: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+    setPage: (page: number) => void;
+    setPageSize: (size: number) => void;
+    next: () => void;
+    prev: () => void;
+    first: () => void;
+    last: () => void;
+}
+declare function usePagination(total: number, initial?: Partial<PaginationState>): PaginationResult;
+
+declare function usePrevious<T>(value: T): T | undefined;
+
+declare function useStep(max: number, initial?: number): {
+    step: number;
+    next: () => void;
+    prev: () => void;
+    goTo: (i: number) => void;
+    reset: () => void;
+    isFirst: boolean;
+    isLast: boolean;
+};
+
+declare function useThrottle<T>(value: T, interval?: number): T;
+
+declare function useToggle(initial?: boolean): [boolean, () => void, (value: boolean) => void];
+
+declare const supportedLocales: readonly ["zh-CN", "en-US"];
+type SupportedLocale = (typeof supportedLocales)[number];
+declare function getStoredLocale(): string;
+interface LocaleContextValue {
+    locale: string;
+    setLocale: (locale: string) => void;
+    supportedLocales: readonly string[];
+}
+interface LocaleProviderProps {
+    initialLocale?: string;
+    children: React.ReactNode;
+}
+declare function LocaleProvider({ initialLocale, children, }: LocaleProviderProps): React$1.JSX.Element;
+declare function useLocale(): LocaleContextValue;
+
+/**
+ * @hook useCrud
+ * @category hooks/business
+ * @since 0.5.0
+ * @description Generic CRUD state manager. Uses separate type params for
+ * the data row (T) and the form (F), so interfaces with optional fields
+ * like `shortName?: string` work without type errors.
+ *
+ * Supports multi-field filtering (`filters`) and pre-submit validation
+ * (`onValidate`), replacing the per-page useAsync + usePagination + useEffect
+ * boilerplate duplicated across business list pages.
+ * / 通用 CRUD 状态管理 hook，分离行类型和表单类型，支持多字段筛选与提交前校验。
+ * @keywords crud, hook, pagination, form, modal, state, filter, validate
+ * @example
+ * const crud = useCrud<Company, Partial<Company>>({
+ *   fetcher: (page, pageSize, filters) =>
+ *     api.list({ page, pageSize, ...filters }),
+ *   filterFields: [
+ *     { name: "keyword", type: "search" },
+ *     { name: "status", type: "select", options: [...] },
+ *   ],
+ *   onValidate: (form) => (form.code ? null : "请填写必填项"),
+ *   emptyForm: { id: 0, name: "", shortName: "" },
+ *   rowKey: "id",
+ *   successMessage: { create: "公司创建成功", update: "更新成功", delete: "已删除" },
+ * });
+ * crud.setFilters({ keyword: "x", status: "OPEN" });
+ */
+/** Per-operation success messages / 按操作分别配置成功消息 */
+interface SuccessMessageMap {
+    create?: string;
+    update?: string;
+    delete?: string;
+}
+type SuccessMessage = string | false | SuccessMessageMap;
+/** Filter field descriptor (drives generated filter UI). / 筛选字段描述 */
+interface FilterField {
+    name: string;
+    type: "search" | "select";
+    /** Options for `select` type / select 类型的选项 */
+    options?: {
+        label: string;
+        value: string | number;
+    }[];
+    /** Placeholder / 占位文案 */
+    placeholder?: string;
+}
+/** Aggregated filter values (string-keyed). / 筛选值聚合 */
+type Filters = Record<string, unknown>;
+interface UseCrudConfig<T, F = Partial<T>> {
+    /**
+     * Fetcher receives page, pageSize, and the current filters object.
+     * Replaces the old single-`keyword` signature so multi-filter pages
+     * (keyword + status + categoryId + ...) don't need hand-rolled wiring.
+     * / 获取数据，filters 替代旧的单 keyword 签名
+     */
+    fetcher: (page: number, pageSize: number, filters: Filters) => Promise<{
+        list: T[];
+        total: number;
+    }>;
+    onCreate?: (form: F) => Promise<unknown>;
+    onUpdate?: (id: string | number, form: F) => Promise<unknown>;
+    onDelete?: (id: string | number) => Promise<unknown>;
+    rowKey?: keyof T & string;
+    /** Empty form template — type F, independent of T's required fields / 空表单模板 */
+    emptyForm: F;
+    defaultPageSize?: number;
+    /**
+     * Pre-submit validation. Return an error message string to block submit
+     * (shown via message.error), or `null` to proceed.
+     * / 提交前校验：返回错误文案拦截提交，null 放行
+     */
+    onValidate?: (form: F) => string | null;
+    /** Filter field descriptors (for generated filter UI). / 筛选字段描述 */
+    filterFields?: FilterField[];
+    /** Initial filter values. / 初始筛选值 */
+    defaultFilters?: Filters;
+    /**
+     * Success message after create/update/delete.
+     * - `string` — used for all operations
+     * - `false` — disable success messages
+     * - `{ create?, update?, delete? }` — per-operation messages
+     * / 成功提示：字符串=全部, false=禁用, 对象=按操作分别配置
+     */
+    successMessage?: SuccessMessage;
+    deleteConfirmTitle?: string;
+}
+interface UseCrudReturn<T, F = Partial<T>> {
+    data: T[];
+    total: number;
+    loading: boolean;
+    /** Current filter values / 当前筛选值 */
+    filters: Filters;
+    /**
+     * Merge a partial patch into filters (shallow merge) and reset to page 1.
+     * / 合并筛选值（浅合并）并重置到第 1 页
+     */
+    setFilters: (patch: Filters) => void;
+    /** Replace filters entirely and reset to page 1. / 整体替换筛选值 */
+    resetFilters: (next: Filters) => void;
+    pagination: ReturnType<typeof usePagination>;
+    modalOpen: boolean;
+    setModalOpen: (v: boolean) => void;
+    editing: T | null;
+    form: F;
+    setForm: React$1.Dispatch<React$1.SetStateAction<F>>;
+    /** Update a single form field / 更新单个表单字段 */
+    updateFormField: <K extends keyof F>(key: K, value: F[K]) => void;
+    handleAdd: () => void;
+    handleEdit: (record: T) => void;
+    handleSubmit: () => Promise<void>;
+    handleDelete: (record: T) => Promise<void>;
+    refresh: () => void;
+    isEdit: boolean;
+}
+declare function useCrud<T extends Record<string, unknown>, F = Partial<T>>(config: UseCrudConfig<T, F>): UseCrudReturn<T, F>;
+
+/**
+ * @hook usePageTitle
+ * @category hooks/browser
+ * @since 0.5.0
+ * @description Sets `document.title` with a template. Eliminates the manual
+ * `useEffect(() => { document.title = ... }, [pathname])` pattern.
+ * / 设置页面标题，自动拼接 title template，消除手动 useEffect 模式
+ * @keywords title, page, document, browser, hook
+ * @example
+ * usePageTitle("订单列表", { template: "{title} · 清香园营销管理系统" })
+ * // → "订单列表 · 清香园营销管理系统"
+ */
+interface UsePageTitleOptions {
+    /** Title template. `{title}` placeholder is replaced with the title arg.
+     * / 标题模板，{title} 占位符会被替换 */
+    template?: string;
+    /** Fallback title when no title is provided / 无标题时的回退值 */
+    defaultTitle?: string;
+}
+declare function usePageTitle(title?: string, { template, defaultTitle }?: UsePageTitleOptions): void;
+
+/**
+ * @hook useConfirmAsync
+ * @category hooks/feedback
+ * @since 0.5.0
+ * @description Imperative confirm API. Two usage modes:
+ *
+ * 1. **Hook mode** — requires rendering `<ConfirmDialog />` in JSX:
+ *   const [confirm, ConfirmDialog] = useConfirmAsync();
+ *   const ok = await confirm({ title: "Delete?" });
+ *   return <>{ConfirmDialog}</>
+ *
+ * 2. **Provider mode** — auto-mounts via `ConfirmProvider`, no JSX needed:
+ *   // In app root:
+ *   <ConfirmProvider>...</ConfirmProvider>
+ *   // Anywhere:
+ *   const confirmed = await confirmAsync({ title: "Delete?" });
+ *
+ * / 命令式确认 API，支持手动挂载和 Provider 自动挂载两种模式
+ * @keywords confirm, dialog, imperative, async, modal, provider
+ */
+interface ConfirmOptions {
+    title?: string;
+    content?: React$1.ReactNode;
+    okText?: string;
+    cancelText?: string;
+    okVariant?: "default" | "destructive";
+    icon?: React$1.ReactNode;
+}
+type ConfirmFn = (options: ConfirmOptions) => Promise<boolean>;
+/**
+ * `confirmAsync` — global imperative confirm when ConfirmProvider is mounted.
+ * Call from any component without rendering a dialog yourself.
+ * / 全局命令式确认，需 ConfirmProvider 包裹
+ * @throws Error if called outside ConfirmProvider
+ */
+declare function confirmAsync(options: ConfirmOptions): Promise<boolean>;
+interface ConfirmProviderProps {
+    children: React$1.ReactNode;
+    /** Default options merged into every call / 全局默认选项 */
+    defaultOptions?: ConfirmOptions;
+}
+declare function ConfirmProvider({ children, defaultOptions }: ConfirmProviderProps): React$1.JSX.Element;
+declare function useConfirmAsync(): [
+    (options: ConfirmOptions) => Promise<boolean>,
+    () => React$1.ReactNode
+];
+declare function useConfirmContext(): ConfirmFn;
+
+interface ValidationRule {
+    type: "required" | "min" | "max" | "pattern" | "custom";
+    message: string;
+    value?: number | RegExp | ((v: unknown) => boolean);
+}
+interface UseFieldValidationOptions {
+    rules?: ValidationRule[];
+    externalError?: string;
+    validateOnBlur?: boolean;
+    validateOnChange?: boolean;
+}
+declare function useFieldValidation(options?: UseFieldValidationOptions): {
+    error: string | undefined;
+    onBlur: (e: React$1.FocusEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
+    onChange: (e: React$1.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
+    validate: (value: unknown) => string | undefined;
+    reset: () => void;
+    touched: boolean;
+};
+
+interface NetworkState {
+    online: boolean;
+    downlink?: number | undefined;
+    effectiveType?: string | undefined;
+    rtt?: number | undefined;
+    saveData?: boolean | undefined;
+}
+/**
+ * Tracks browser online/offline status and network info via Navigator.connection API.
+ * @since 0.2.0
+ */
+declare function useNetworkStatus(): NetworkState;
+
+/**
+ * Tracks page visibility changes (tab focus/blur, minimize).
+ * @param onChange - Optional callback when visibility changes
+ * @returns Whether the page is currently visible
+ * @since 0.2.0
+ */
+declare function useVisibilityChange(onChange?: (visible: boolean) => void): boolean;
+
+interface WindowSize {
+    width: number;
+    height: number;
+}
+/**
+ * Reactive window dimensions, updated on resize (debounced).
+ * @param debounceMs - Debounce delay in ms (default 100)
+ * @since 0.2.0
+ */
+declare function useWindowSize(debounceMs?: number): WindowSize;
+
+interface ScrollState {
+    x: number;
+    y: number;
+    isScrolled: boolean;
+    /** Scroll direction: 'up' | 'down' | null (initial) */
+    direction: "up" | "down" | null;
+}
+/**
+ * Tracks scroll position and direction.
+ * @param throttleMs - Throttle interval in ms (default 50)
+ * @param target - Scroll target element ref (defaults to window)
+ * @since 0.2.0
+ */
+declare function useScroll(throttleMs?: number, target?: React$1.RefObject<HTMLElement | null>): ScrollState;
+/**
+ * Convenience hook: returns just the scroll direction.
+ * @since 0.2.0
+ */
+declare function useScrollDirection(throttleMs?: number, target?: React$1.RefObject<HTMLElement | null>): "up" | "down" | null;
+
+type Orientation = "portrait" | "landscape";
+/**
+ * Tracks device screen orientation.
+ * @since 0.2.0
+ */
+declare function useOrientation(): Orientation;
+
+interface UseClipboardReturn {
+    /** Copies text to clipboard */
+    copy: (text: string) => Promise<boolean>;
+    /** Whether a copy operation is in progress */
+    copying: boolean;
+    /** Whether the last copy was successful */
+    copied: boolean;
+    /** Recently copied text */
+    value: string | null;
+    /** Reset copied state */
+    reset: () => void;
+}
+/**
+ * Copy text to clipboard with state tracking.
+ * Unifies the existing use-copy-to-clipboard under a standard API.
+ *
+ * @param timeout - How long "copied" stays true (ms, default 2000)
+ * @since 0.2.0
+ */
+declare function useClipboard(timeout?: number): UseClipboardReturn;
+
+/**
+ * Enhanced form hook wrapping react-hook-form with enterprise defaults.
+ * - `mode: "onTouched"` by default (fewer re-renders)
+ * - `reValidateMode: "onChange"`
+ * - Standardized dirty/submit tracking
+ *
+ * @since 0.2.0
+ */
+declare function useForm<TFieldValues extends FieldValues = FieldValues, TContext = unknown>(props?: UseFormProps<TFieldValues, TContext>): react_hook_form.UseFormReturn<TFieldValues, TContext, TFieldValues>;
+
+/**
+ * Schema-driven wrapper around {@link useForm}.
+ *
+ * - Accepts a zod schema and wires it through `zodResolver` automatically.
+ * - For yup / valibot / custom schema libraries, pass `resolver` directly
+ *   (e.g. `yupResolver(schema)`); `schema` and custom resolvers are mutually
+ *   exclusive — `resolver` wins when both are supplied.
+ * - When neither is supplied, behaves like plain {@link useForm} so the hook
+ *   is safely composable inside mixed caller code paths.
+ *
+ * `zod` and `@hookform/resolvers` are declared as optional peer dependencies;
+ * consumers adopting schema-driven forms must install them.
+ *
+ * @since 1.1.0
+ * @example
+ * const form = useFormSchema({
+ *   schema: loginSchema,
+ *   defaultValues: { email: "", password: "" },
+ * })
+ */
+interface UseFormSchemaOptions<TFieldValues extends FieldValues = FieldValues, TContext = unknown> extends Omit<UseFormProps<TFieldValues, TContext>, "resolver"> {
+    /**
+     * Zod schema. Auto-detected via `zodResolver`; for other libraries use
+     * `resolver` instead. `z.infer<typeof schema>` must align with
+     * `TFieldValues` (the hook will infer it for you when omitted).
+     *
+     * Typed loosely (`unknown`) intentionally: zod v3/v4 surface slightly
+     * different generic arities and we pass the schema straight into
+     * `zodResolver`, which is the single source of truth for shape.
+     */
+    schema?: unknown;
+    /**
+     * Explicit react-hook-form resolver. Takes precedence over `schema`.
+     * Pass `yupResolver` / `valibotResolver` / a custom resolver here.
+     */
+    resolver?: Resolver<TFieldValues, TContext>;
+}
+/**
+ * Infer field values from a zod schema.
+ *
+ * @example
+ * const form = useFormSchema({
+ *   schema: z.object({ email: z.string() }),
+ *   defaultValues: { email: "" },
+ * })
+ */
+declare function useFormSchema<TFieldValues extends FieldValues = FieldValues, TContext = unknown>(options?: UseFormSchemaOptions<TFieldValues, TContext>): react_hook_form.UseFormReturn<TFieldValues, TContext, TFieldValues>;
+/**
+ * Convenience adapter mirroring `packages/chaos-design-ui` usage so consumers
+ * can write `const resolver = zodResolverAdapter(loginSchema)` without
+ * importing `@hookform/resolvers/zod` themselves.
+ */
+declare function zodResolverAdapter<TFieldValues extends FieldValues>(schema: unknown): Resolver<TFieldValues>;
+
+/**
+ * @hook usePermission
+ * @category hooks/auth
+ * @since 0.7.0
+ * @description 权限校验 Hook，配合 PermissionProvider 使用。
+ * 提供当前用户权限列表和校验函数。
+ * / Permission hook — works with PermissionProvider to check user permissions.
+ * @keywords permission, auth, role, access, guard
+ * @example
+ * const { hasPermission, hasAny, hasAll } = usePermission();
+ * if (hasPermission("order:create")) { ... }
+ */
+type PermissionCheck = (permission: string) => boolean;
+interface PermissionContextValue {
+    /** All permissions the current user holds / 当前用户拥有的权限列表 */
+    permissions: string[];
+    /** Check a single permission / 校验单个权限 */
+    hasPermission: PermissionCheck;
+    /** Check if user has ANY of the given permissions / 满足任一权限 */
+    hasAny: (permissions: string[]) => boolean;
+    /** Check if user has ALL of the given permissions / 满足全部权限 */
+    hasAll: (permissions: string[]) => boolean;
+}
+declare const PermissionContext: React$1.Context<PermissionContextValue>;
+interface PermissionProviderProps {
+    /** Permission codes granted to the current user / 当前用户的权限码列表 */
+    permissions: string[];
+    children: React$1.ReactNode;
+}
+declare function PermissionProvider({ permissions, children, }: PermissionProviderProps): React$1.JSX.Element;
+declare function usePermission(): PermissionContextValue;
+
+/**
+ * @hook useApproval
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Drives an approval action (approve/reject/transfer) with async state and result tracking.
+ * @param submit Async handler invoked with the action type and optional comment.
+ * @example
+ * const { submit, status, data, error, isLoading } = useApproval(async (action) => api.post(...));
+ */
+type ApprovalAction = "approve" | "reject" | "transfer";
+interface UseApprovalResult<T> {
+    submit: (action: ApprovalAction, comment?: string) => Promise<T | undefined>;
+    status: "idle" | "pending" | "success" | "error";
+    data: T | undefined;
+    error: Error | undefined;
+    isLoading: boolean;
+}
+declare function useApproval<T = unknown>(handler: (action: ApprovalAction, comment?: string) => Promise<T>): UseApprovalResult<T>;
+
+/**
+ * @hook useAsyncTask
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Trigger a one-shot async task with progress, retry, and abort.
+ * @param task Async function returning a result.
+ * @example
+ * const { run, status, data, error, isLoading, abort } = useAsyncTask(async (signal) => {...});
+ */
+interface UseAsyncTaskResult<T> {
+    run: (...args: never[]) => Promise<T | undefined>;
+    status: "idle" | "pending" | "success" | "error";
+    data: T | undefined;
+    error: Error | undefined;
+    isLoading: boolean;
+    abort: () => void;
+    reset: () => void;
+}
+declare function useAsyncTask<T>(task: (signal: AbortSignal) => Promise<T>): UseAsyncTaskResult<T>;
+
+/**
+ * @hook useBill
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Tracks a bill/document's lifecycle state (draft → submitted → approved → paid → void) with transitions and history.
+ * @param initial Initial status.
+ * @example
+ * const { status, transition, history, can } = useBill("draft");
+ */
+type BillStatus = "draft" | "submitted" | "approved" | "rejected" | "paid" | "void";
+interface UseBillState {
+    status: BillStatus;
+    transition: (next: BillStatus) => boolean;
+    can: (next: BillStatus) => boolean;
+    history: BillStatus[];
+    reset: (status?: BillStatus) => void;
+}
+declare function useBill(initial?: BillStatus): UseBillState;
+
+/**
+ * @hook useDataScope
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Tracks the active data scope (e.g. company/department/period) used to filter business queries, with persistence and change subscription.
+ * @param initial Initial scope.
+ * @param options storageKey to persist to localStorage.
+ * @example
+ * const { scope, setScope, subscribe } = useDataScope({ companyId: "1" });
+ */
+type DataScope = Record<string, string | number | boolean | undefined>;
+interface UseDataScopeState<S extends DataScope> {
+    scope: S;
+    setScope: (next: S | ((prev: S) => S)) => void;
+    patch: (partial: Partial<S>) => void;
+    reset: () => void;
+    subscribe: (fn: (scope: S) => void) => () => void;
+}
+declare function useDataScope<S extends DataScope>(initial: S, options?: {
+    storageKey?: string;
+}): UseDataScopeState<S>;
+
+/**
+ * @hook useDict
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Loads and caches a dictionary (key/label/code options) by dict type, with loading/error state and a label lookup helper.
+ * @param dictType Dictionary type key. Falsy skips loading.
+ * @param fetcher Returns the options for the given dict type.
+ * @example
+ * const { options, isLoading, getLabel } = useDict("gender", fetchDict);
+ */
+interface DictOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+interface UseDictState {
+    options: DictOption[];
+    isLoading: boolean;
+    error: Error | undefined;
+    getLabel: (value: string) => string;
+    refresh: () => void;
+}
+declare function useDict(dictType: string | null, fetcher: (type: string) => Promise<DictOption[]>): UseDictState;
+
+/**
+ * @hook useExport
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Triggers a file export (download) with progress, abort, and blob/text support.
+ * @example
+ * const { exportFile, isLoading, error } = useExport();
+ * await exportFile(() => fetch("/api/export").then(r => r.blob()), "report.xlsx");
+ */
+interface UseExportResult {
+    exportFile: (source: () => Promise<Blob | string>, filename: string, mime?: string) => Promise<void>;
+    isLoading: boolean;
+    error: Error | undefined;
+    progress: number;
+    abort: () => void;
+}
+declare function useExport(): UseExportResult;
+
+/**
+ * @hook useFetch
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Lightweight fetch hook with abort, re-fetch, and manual trigger.
+ * @param input Request URL or Request object.
+ * @param init Fetch init options.
+ * @example
+ * const { data, error, isLoading, refetch } = useFetch("/api/users");
+ */
+interface UseFetchState<T> {
+    data: T | undefined;
+    error: Error | undefined;
+    isLoading: boolean;
+}
+declare function useFetch<T = unknown>(input: string | URL | Request, init?: RequestInit): UseFetchState<T> & {
+    refetch: () => void;
+};
+
+/**
+ * @hook useFormTable
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Editable table rows backed by a form-like state: add/update/remove rows with field-level validation and dirty tracking.
+ * @param initial Initial rows.
+ * @param config validate, id generator.
+ * @example
+ * const { rows, addRow, updateRow, removeRow, errors, isValid, dirty } = useFormTable([{ id: "1", name: "" }]);
+ */
+interface UseFormTableConfig<T> {
+    validate?: (row: T, index: number) => Record<string, string>;
+    createId?: () => string;
+}
+interface UseFormTableResult<T> {
+    rows: T[];
+    addRow: (row: T) => void;
+    updateRow: (index: number, patch: Partial<T>) => void;
+    removeRow: (index: number) => void;
+    setRows: (rows: T[]) => void;
+    reset: (rows?: T[]) => void;
+    errors: Record<number, Record<string, string>>;
+    isValid: boolean;
+    dirty: boolean;
+}
+declare function useFormTable<T extends {
+    id?: string;
+}>(initial: T[], config?: UseFormTableConfig<T>): UseFormTableResult<T>;
+
+/**
+ * @hook useIdle
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Tracks whether the user has been idle (no mouse/keyboard/touch/scroll) for a duration.
+ * @param timeout Idle threshold in ms (default 60_000).
+ * @param events Activity events to listen for.
+ * @example
+ * const isIdle = useIdle(30_000);
+ */
+declare function useIdle(timeout?: number, events?: string[]): boolean;
+
+/**
+ * @hook useImport
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Drive a file import: parse an uploaded file (text/json/csv), track progress, validation errors, and parsed rows.
+ * @example
+ * const { importFile, rows, errors, isLoading, progress } = useImport();
+ */
+interface ImportError {
+    row: number;
+    message: string;
+}
+interface UseImportResult<T> {
+    rows: T[];
+    errors: ImportError[];
+    isLoading: boolean;
+    progress: number;
+    importFile: (file: File, parser: (text: string, file: File) => T[] | Promise<T[]>) => Promise<T[]>;
+    reset: () => void;
+}
+declare function useImport<T = Record<string, unknown>>(): UseImportResult<T>;
+
+/**
+ * @hook useLineEditor
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Inline line editor: tracks edit/draft state for a single value, with commit/cancel, validation, and dirty flag. Used by editable table cells and inline-edit fields.
+ * @param value The committed value.
+ * @param options onCommit, validate, autoFocus.
+ * @example
+ * const { draft, setDraft, commit, cancel, isEditing, start, isValid } = useLineEditor("foo");
+ */
+interface UseLineEditorOptions<T> {
+    onCommit?: (value: T) => void | Promise<void>;
+    validate?: (value: T) => string | null;
+    autoFocus?: boolean;
+}
+interface UseLineEditorResult<T> {
+    value: T;
+    draft: T;
+    isEditing: boolean;
+    error: string | null;
+    isValid: boolean;
+    dirty: boolean;
+    start: () => void;
+    setDraft: (value: T) => void;
+    commit: () => Promise<void>;
+    cancel: () => void;
+}
+declare function useLineEditor<T>(value: T, options?: UseLineEditorOptions<T>): UseLineEditorResult<T>;
+
+/**
+ * @hook useNetworkQuality
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Estimates network quality via navigator.connection (effectiveType, downlink, rtt) plus online/offline status.
+ * @example
+ * const { online, effectiveType, downlink, rtt } = useNetworkQuality();
+ */
+interface UseNetworkQualityState {
+    online: boolean;
+    effectiveType: string | undefined;
+    downlink: number | undefined;
+    rtt: number | undefined;
+    saveData: boolean | undefined;
+}
+declare function useNetworkQuality(): UseNetworkQualityState;
+
+/**
+ * @hook usePrint
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Programmatic print helper: print a DOM node (via clone into a hidden iframe) or the whole window, with before/after hooks and cleanup.
+ * @example
+ * const { print, isPrinting } = usePrint();
+ * await print(ref.current, { title: "Invoice" });
+ */
+interface UsePrintOptions {
+    title?: string;
+    beforePrint?: () => void;
+    afterPrint?: () => void;
+    cssText?: string;
+}
+interface UsePrintResult {
+    print: (target?: HTMLElement | null, options?: UsePrintOptions) => Promise<void>;
+    isPrinting: boolean;
+}
+declare function usePrint(): UsePrintResult;
+
+/**
+ * @hook useRedo
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Tracks redo history for an externally-managed undo stack. Pair with {@link useUndo} when you need separate redo state, or use `useUndo` which includes both. This hook exposes the redo queue length and a way to push/peek/pop.
+ * @param initial Redo queue seed (default empty).
+ * @example
+ * const { redoCount, push, pop, peek } = useRedo<string>();
+ */
+interface UseRedoState<T> {
+    redoCount: number;
+    push: (value: T) => void;
+    pop: () => T | undefined;
+    peek: () => T | undefined;
+    clear: () => void;
+}
+declare function useRedo<T>(): UseRedoState<T>;
+
+/**
+ * @hook useSse
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Subscribe to a Server-Sent Events stream. Auto-reconnect and cleanup.
+ * @param url SSE endpoint URL. Falsy disables the connection.
+ * @param options onMessage handler, event name filter, withCredentials.
+ * @example
+ * const { readyState, lastEvent } = useSse("/api/stream", { onMessage: console.log });
+ */
+interface UseSseOptions {
+    onMessage?: (data: string, event: MessageEvent) => void;
+    event?: string;
+    withCredentials?: boolean;
+}
+interface UseSseState {
+    readyState: number;
+    lastEvent: string | undefined;
+    error: Event | undefined;
+}
+declare function useSse(url: string | null, options?: UseSseOptions): UseSseState;
+
+/**
+ * Type-safe wrapper around TanStack Query's `useQuery`.
+ *
+ * Consumers must install `@tanstack/react-query` and wrap their app with
+ * `QueryClientProvider`. This hook is a thin pass-through that adds
+ * enterprise defaults (e.g. `staleTime: 30_000`) so teams can adopt
+ * query caching without boilerplate.
+ *
+ * @since 1.1.0
+ * @example
+ * const { data, isLoading } = useQuery({
+ *   queryKey: ["users", userId],
+ *   queryFn: () => fetchUser(userId),
+ * })
+ */
+declare function useQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>): UseQueryResult<TData, TError>;
+
+/**
+ * Type-safe wrapper around TanStack Query's `useMutation`.
+ *
+ * @since 1.1.0
+ * @example
+ * const { mutate, isPending } = useMutation({
+ *   mutationFn: (data: CreateUserInput) => createUser(data),
+ *   onSuccess: () => queryClient.invalidateQueries({ queryKey: ["users"] }),
+ * })
+ */
+declare function useMutation<TData = unknown, TError = Error, TVariables = void, TContext = unknown>(options: UseMutationOptions<TData, TError, TVariables, TContext>): UseMutationResult<TData, TError, TVariables, TContext>;
+
+/**
+ * @hook useSwr
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description SWR-style data fetching with revalidation on focus and interval.
+ * @param key Cache key (falsy disables fetching).
+ * @param fetcher Function that returns a Promise of data.
+ * @param options revalidateOnFocus, dedupingInterval, refreshInterval.
+ * @example
+ * const { data, error, isLoading, mutate } = useSwr("/api/users", fetcher);
+ */
+interface UseSwrOptions {
+    revalidateOnFocus?: boolean;
+    refreshInterval?: number;
+    dedupingInterval?: number;
+}
+interface UseSwrState<T> {
+    data: T | undefined;
+    error: Error | undefined;
+    isLoading: boolean;
+    mutate: (data?: T | ((prev: T | undefined) => T)) => void;
+}
+declare function useSwr<T>(key: string | null, fetcher: (key: string) => Promise<T>, options?: UseSwrOptions): UseSwrState<T>;
+
+/**
+ * @hook useTable
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Client-side table controller: sorting, filtering, pagination, and row selection over a flat data array.
+ * @param data Source rows.
+ * @param config initial sort, page size, filter predicate.
+ * @example
+ * const { rows, page, pageSize, totalPages, sort, setFilter, toggleRow, selected } = useTable(data, { pageSize: 20 });
+ */
+interface UseTableConfig<T> {
+    pageSize?: number;
+    initialSort?: {
+        key: keyof T;
+        direction?: "asc" | "desc";
+    };
+    filter?: (row: T, term: string) => boolean;
+    getRowId?: (row: T, index: number) => string;
+}
+interface SortState<T> {
+    key: keyof T | null;
+    direction: "asc" | "desc";
+}
+interface UseTableResult<T> {
+    rows: T[];
+    page: number;
+    pageSize: number;
+    total: number;
+    totalPages: number;
+    sort: SortState<T>;
+    setSort: (key: keyof T) => void;
+    filterTerm: string;
+    setFilter: (term: string) => void;
+    setPage: (page: number) => void;
+    setPageSize: (size: number) => void;
+    selected: Set<string>;
+    toggleRow: (id: string) => void;
+    toggleAll: () => void;
+    clearSelected: () => void;
+}
+declare function useTable<T>(data: T[], config?: UseTableConfig<T>): UseTableResult<T>;
+
+interface UseTrackOptions {
+    /** Event name sent to the telemetry adapter. */
+    event: string;
+    /** Additional properties merged into the event payload. */
+    properties?: Record<string, unknown>;
+    /** If true, fires the event on mount. Default false. */
+    trackOnMount?: boolean;
+    /** If true, fires the event on unmount. Default false. */
+    trackOnUnmount?: boolean;
+}
+/**
+ * Declarative tracking hook.
+ *
+ * Returns a `trackNow(extra?)` function for imperative use. Optionally
+ * fires events on mount/unmount via `trackOnMount` / `trackOnUnmount`.
+ *
+ * @since 1.1.0
+ * @example
+ * // Track a page view on mount
+ * useTrack({ event: "page_view", properties: { page: "dashboard" }, trackOnMount: true })
+ *
+ * // Track a button click
+ * const { trackNow } = useTrack({ event: "export_csv" })
+ * <Button onClick={() => trackNow({ rows: 142 })}>Export</Button>
+ */
+declare function useTrack(options: UseTrackOptions): {
+    trackNow: (extra?: Record<string, unknown>) => void;
+};
+
+/**
+ * @hook useUndo
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Undo/redo history for a value. Returns value, setters, and can/clear flags.
+ * @param initial Initial value.
+ * @param limit Max history entries (default 100).
+ * @example
+ * const { value, set, undo, redo, canUndo, canRedo } = useUndo("");
+ */
+interface UseUndoState<T> {
+    value: T;
+    setValue: (next: T | ((prev: T) => T)) => void;
+    undo: () => void;
+    redo: () => void;
+    clear: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+}
+declare function useUndo<T>(initial: T, limit?: number): UseUndoState<T>;
+
+/**
+ * @hook useWebsocket
+ * @category Data
+ * @since 1.0.0-beta.0
+ * @description Manage a WebSocket connection with auto-reconnect, send helper, and last-message state.
+ * @param url WebSocket URL. Falsy disables.
+ * @param options onOpen/onMessage/onClose/onError callbacks, protocols, retry interval.
+ * @example
+ * const { send, readyState, lastMessage } = useWebsocket("wss://echo.example");
+ */
+interface UseWebsocketOptions {
+    onOpen?: (e: Event) => void;
+    onMessage?: (data: string, e: MessageEvent) => void;
+    onClose?: (e: CloseEvent) => void;
+    onError?: (e: Event) => void;
+    protocols?: string | string[];
+    retryInterval?: number;
+    autoConnect?: boolean;
+}
+interface UseWebsocketState {
+    readyState: number;
+    lastMessage: string | undefined;
+    send: (data: string | ArrayBuffer) => void;
+    close: () => void;
+}
+declare function useWebsocket(url: string | null, options?: UseWebsocketOptions): UseWebsocketState;
+
+export { type Breakpoint, type ConfirmOptions, ConfirmProvider, type ConfirmProviderProps, type KeyFilter, type KeyHandler, LocaleProvider, type MessageInstance, MessageOptions, type ModalInstance, type ModalOptions, ModalRenderer, type NotificationInstance, type NotificationOptions, PermissionContext, type PermissionContextValue, PermissionProvider, type PermissionProviderProps, type SupportedLocale, type UseCrudConfig, type UseCrudReturn, type UseFieldValidationOptions, type UseFormSchemaOptions, type UseKeyOptions, type UsePageTitleOptions, type UseTrackOptions, type ValidationRule, confirmAsync, getStoredLocale, supportedLocales, useApproval, useAsync, useAsyncTask, useBill, useBreakpoint, useClickOutside, useClipboard, useConfirmAsync, useConfirmContext, useCopyToClipboard, useCountdown, useCrud, useDataScope, useDebounce, useDict, useEventListener, useExport, useFetch, useFieldValidation, useForm, useFormSchema, useFormTable, useHotkeys, useIdle, useImport, useInView, useInfiniteScroll, useIntersectionObserver, useIsBreakpoint, useIsDesktop, useIsMobile, useIsTablet, useKey, useKeyCombo, useLineEditor, useLocalStorage, useLocale, useMediaQuery, useMessage, useModal, useMutation, useNetworkQuality, useNetworkStatus, useNotification, useOrientation, usePageTitle, usePagination, usePermission, usePrevious, usePrint, useQuery, useRedo, useScroll, useScrollDirection, useSse, useStep, useSwr, useTable, useThrottle, useToggle, useTrack, useUndo, useVisibilityChange, useWebsocket, useWindowSize, zodResolverAdapter };