@ug666/ui-react 0.1.0

package/dist/hooks/index.d.ts

@@ -0,0 +1,232 @@
+import { RefObject } from 'react';
+
+/**
+ * 防抖值，延迟 delay 毫秒后才更新
+ * @example
+ * const keyword = useDebounce(inputValue, 300)
+ */
+declare function useDebounce<T>(value: T, delay?: number): T;
+
+type SetLocalStorageValue<T> = (value: T | ((prev: T) => T)) => void;
+type UseLocalStorageReturn<T> = [T, SetLocalStorageValue<T>, () => void];
+/**
+ * 自动读写 localStorage 的 useState
+ * @example
+ * const [token, setToken, removeToken] = useLocalStorage('token', '')
+ */
+declare function useLocalStorage<T>(key: string, initialValue: T): UseLocalStorageReturn<T>;
+
+/**
+ * 监听 CSS media query 变化，返回当前是否匹配
+ * @example
+ * const isMobile = useMediaQuery('(max-width: 768px)')
+ * const prefersDark = useMediaQuery('(prefers-color-scheme: dark)')
+ */
+declare function useMediaQuery(query: string): boolean;
+
+/**
+ * 点击 ref 元素外部时触发 handler
+ * @example
+ * const ref = useRef<HTMLDivElement>(null)
+ * useClickOutside(ref, () => setOpen(false))
+ */
+declare function useClickOutside<T extends HTMLElement>(ref: RefObject<T | null>, handler: () => void): void;
+
+interface UseCopyToClipboardReturn {
+    copied: boolean;
+    copy: (text: string) => Promise<void>;
+}
+/**
+ * 复制文本到剪贴板，copied 状态 2 秒后自动重置
+ * @example
+ * const { copied, copy } = useCopyToClipboard()
+ * <button onClick={() => copy('hello')}>{copied ? '已复制' : '复制'}</button>
+ */
+declare function useCopyToClipboard(): UseCopyToClipboardReturn;
+
+type UseToggleReturn = [boolean, () => void, (value: boolean) => void];
+/**
+ * 简单的布尔值切换，返回 [value, toggle, setValue]
+ * @example
+ * const [isOpen, toggleOpen, setIsOpen] = useToggle(false)
+ * <button onClick={toggleOpen}>切换</button>
+ */
+declare function useToggle(initial?: boolean): UseToggleReturn;
+
+interface UsePaginationOptions {
+    /** 数据总条数 */
+    total: number;
+    /** 每页条数，默认 10 */
+    pageSize?: number;
+    /** 初始页码，默认 1 */
+    initialPage?: number;
+}
+interface UsePaginationReturn {
+    /** 当前页码 (从 1 开始) */
+    page: number;
+    /** 总页数 */
+    totalPages: number;
+    /** 跳转到指定页 */
+    setPage: (p: number) => void;
+    /** 下一页 */
+    nextPage: () => void;
+    /** 上一页 */
+    prevPage: () => void;
+    /** 是否有下一页 */
+    hasNext: boolean;
+    /** 是否有上一页 */
+    hasPrev: boolean;
+    /** 当前页起始索引 (0-based，用于切片) */
+    startIndex: number;
+    /** 当前页结束索引 (exclusive，用于切片) */
+    endIndex: number;
+}
+/**
+ * 分页状态管理，提供页码、边界判断和数据切片索引
+ * @example
+ * const { page, totalPages, nextPage, prevPage, startIndex, endIndex } = usePagination({ total: 100, pageSize: 10 })
+ * const pageData = data.slice(startIndex, endIndex)
+ */
+declare function usePagination({ total, pageSize, initialPage, }: UsePaginationOptions): UsePaginationReturn;
+
+type UseFormErrors<T extends Record<string, unknown>> = Partial<Record<keyof T, string>>;
+interface UseFormReturn<T extends Record<string, unknown>> {
+    /** 当前表单值 */
+    values: T;
+    /** 字段错误信息 */
+    errors: UseFormErrors<T>;
+    /** 更新单个字段值 */
+    handleChange: <K extends keyof T>(name: K, value: T[K]) => void;
+    /** 设置字段错误 */
+    setError: (name: keyof T, message: string) => void;
+    /** 清除所有错误 */
+    clearErrors: () => void;
+    /** 重置表单到初始值 */
+    reset: () => void;
+    /** 表单是否被修改过 */
+    isDirty: boolean;
+}
+/**
+ * 极简表单状态管理，提供值管理、错误处理和脏状态检测
+ * @example
+ * const form = useForm({ username: '', password: '' })
+ * <input value={form.values.username} onChange={e => form.handleChange('username', e.target.value)} />
+ * {form.errors.username && <span>{form.errors.username}</span>}
+ */
+declare function useForm<T extends Record<string, unknown>>(initialValues: T): UseFormReturn<T>;
+
+/**
+ * 返回组件是否已在客户端挂载完成。
+ *
+ * 在 SSR 场景中，服务端渲染时始终返回 false，
+ * 客户端 hydration 完成后变为 true，可用于条件渲染仅客户端内容。
+ *
+ * @returns 组件是否已挂载
+ *
+ * @example
+ * ```tsx
+ * const isMounted = useMounted()
+ *
+ * if (!isMounted) return null // 服务端不渲染
+ * return <ClientOnlyComponent />
+ * ```
+ */
+declare function useMounted(): boolean;
+
+/**
+ * 以指定间隔重复调用回调函数。
+ *
+ * 当 delay 为 null 时定时器自动暂停，可动态修改 delay 或 callback。
+ * 参考 Dan Abramov 的 useInterval 实现，使用 ref 保持 callback 最新引用。
+ *
+ * @param callback 每次触发时调用的函数
+ * @param delay 间隔毫秒数；传入 null 则暂停定时器
+ *
+ * @example
+ * ```tsx
+ * const [count, setCount] = useState(0)
+ * const [running, setRunning] = useState(true)
+ *
+ * useInterval(() => setCount(c => c + 1), running ? 1000 : null)
+ * ```
+ */
+declare function useInterval(callback: () => void, delay: number | null): void;
+
+/**
+ * 在指定延迟后执行一次回调函数。
+ *
+ * 当 delay 为 null 时定时器不启动（暂停模式）。
+ * 每次 delay 变化都会重置定时器；组件卸载时自动清理。
+ *
+ * @param callback 延迟结束后调用的函数
+ * @param delay 延迟毫秒数；传入 null 则不执行
+ *
+ * @example
+ * ```tsx
+ * const [show, setShow] = useState(true)
+ *
+ * // 3 秒后自动隐藏提示
+ * useTimeout(() => setShow(false), show ? 3000 : null)
+ * ```
+ */
+declare function useTimeout(callback: () => void, delay: number | null): void;
+
+interface UseHotkeysOptions {
+    /** 是否阻止默认浏览器行为，默认 false */
+    preventDefault?: boolean;
+    /** 监听目标，默认 window */
+    target?: HTMLElement | null;
+}
+/**
+ * 将快捷键字符串绑定到回调函数。
+ *
+ * 支持修饰键组合：ctrl、cmd（Meta）、alt、shift，加主键（不区分大小写）。
+ * 组件卸载时自动解绑。
+ *
+ * @param keys 快捷键字符串，如 "ctrl+k"、"cmd+s"、"escape"
+ * @param callback 触发时调用的函数
+ * @param options 额外配置项
+ *
+ * @example
+ * ```tsx
+ * // 全局搜索快捷键
+ * useHotkeys('ctrl+k', () => setSearchOpen(true), { preventDefault: true })
+ *
+ * // ESC 关闭弹窗
+ * useHotkeys('escape', () => setOpen(false))
+ *
+ * // 仅在特定元素内响应
+ * useHotkeys('ctrl+enter', handleSubmit, { target: formRef.current })
+ * ```
+ */
+declare function useHotkeys(keys: string, callback: (event: KeyboardEvent) => void, options?: UseHotkeysOptions): void;
+
+/**
+ * 在指定目标上绑定事件监听器，组件卸载时自动清理。
+ *
+ * 支持三种目标类型：
+ * - 不传 target → 默认监听 window
+ * - 传入 HTMLElement → 监听该元素
+ * - 传入 null → 跳过绑定（适合 ref 未初始化的场景）
+ *
+ * @typeParam K WindowEventMap 中的事件名称
+ * @param event 事件名称，如 "scroll"、"resize"、"click"
+ * @param handler 事件处理函数
+ * @param target 监听目标；默认 window；传 null 跳过绑定
+ *
+ * @example
+ * ```tsx
+ * // 监听全局滚动
+ * useEventListener('scroll', () => setScrollY(window.scrollY))
+ *
+ * // 监听特定元素的点击
+ * const divRef = useRef<HTMLDivElement>(null)
+ * useEventListener('click', handleClick, divRef.current)
+ *
+ * // 传入 null 跳过（ref 尚未挂载时）
+ * useEventListener('mouseenter', onEnter, ref.current)
+ * ```
+ */
+declare function useEventListener<K extends keyof WindowEventMap>(event: K, handler: (event: WindowEventMap[K]) => void, target?: EventTarget | null): void;
+
+export { type SetLocalStorageValue, type UseCopyToClipboardReturn, type UseFormErrors, type UseFormReturn, type UseHotkeysOptions, type UseLocalStorageReturn, type UsePaginationOptions, type UsePaginationReturn, type UseToggleReturn, useClickOutside, useCopyToClipboard, useDebounce, useEventListener, useForm, useHotkeys, useInterval, useLocalStorage, useMediaQuery, useMounted, usePagination, useTimeout, useToggle };

package/dist/hooks/index.js

@@ -0,0 +1,31 @@
+import {
+  useClickOutside,
+  useCopyToClipboard,
+  useDebounce,
+  useEventListener,
+  useForm,
+  useHotkeys,
+  useInterval,
+  useLocalStorage,
+  useMediaQuery,
+  useMounted,
+  usePagination,
+  useTimeout,
+  useToggle
+} from "../chunk-MGXIF756.js";
+export {
+  useClickOutside,
+  useCopyToClipboard,
+  useDebounce,
+  useEventListener,
+  useForm,
+  useHotkeys,
+  useInterval,
+  useLocalStorage,
+  useMediaQuery,
+  useMounted,
+  usePagination,
+  useTimeout,
+  useToggle
+};
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}