mantine-hooks

Mantine Hooks

仅将此技能用于 @mantine/hooks ——独立的 React hooks 包。除非用户在此技能之外明确要求，否则不要引入 @mantine/core、@mantine/form 或其他 @mantine/* 包。

优先参考当前文档，而非依赖记忆。说明内容以 @mantine/[email protected] 为准（npm latest 快照：9.6.3，peer react@^19.2.0；9.5.1–9.6.3 未添加新的 hook 导出）。

工作流

1. 修改代码前检查项目：
   • 已安装的 @mantine/hooks 版本和 React peer 版本。
   • 应用是仅 SPA，还是 SSR/已水合（会影响 getInitialValueInEffect 和媒体/存储 hooks）。
   • 涉及哪些 hook 系列：状态、存储、事件、观察器、计时或交互构建器。
2. 当行为或迁移相关时，从 source-map.md 更新版本和文档 URL。
3. 安装、导入、工具函数、SSR 默认值、类型和包边界请参考 setup-core.md。
4. 布尔值/列表/对象/Map/Set 状态、非受控值、存储、队列、分页和历史记录请参考 state-storage.md。
5. 点击外部、快捷键、焦点、悬停/鼠标、剪贴板、全屏、长按以及 window/document 事件请参考 ui-events.md。
6. 媒体查询、观察器、防抖/节流、计时器、空闲/网络/操作系统以及 fetch 请参考 observers-timing.md。
7. 移动/拖拽/径向、折叠、遮罩、循环索引、分隔器、浮动窗口、选择和滚动辅助工具请参考 advanced-interaction.md。
8. 完整的 hook 索引及文档链接请参考 catalog.md。

实现判断

• 仅从 @mantine/hooks 导入。 优先使用命名导入：import { useDisclosure, clamp } from '@mantine/hooks'。
• 该包独立运行：只要求 React peer 依赖。可安全用于任何 React Web 应用，无需其他 Mantine 包。状态管理钩子（例如 usePagination、useQueue）也适用于 React Native；DOM/window 钩子则不适用。
• 9.x 要求 React 19.2+。多个钩子使用 React 19 的 useEffectEvent（usePageLeave、useWindowEvent、useHotkeys、useClickOutside、useCollapse）——不要仅为保持监听器稳定而强行套用 useCallback。
• 优先使用导出的选项/返回值类型（UseDisclosureOptions，或 useDisclosure.Options 这类命名空间形式），而不是自行定义类型结构。
• 对 SSR 敏感的钩子（useMediaQuery、useColorScheme、useReducedMotion、useLocalStorage / useSessionStorage、视口尺寸）：默认情况下，会在挂载后通过 getInitialValueInEffect: true 计算。为服务端渲染传入明确的 initialValue / defaultValue；只有仅限 CSR 的应用需要在首次绘制时获取实际值时，才设置 getInitialValueInEffect: false。
• 将返回 ref 的钩子与 useMergedRef / mergeRefs 组合使用（例如 useClickOutside + useFocusTrap + 本地 ref）。
• 防抖三种用法：
  • useDebouncedValue — 受控源值保持即时更新；为副作用/搜索提供防抖副本。
  • useDebouncedState — setter 本身经过防抖（非受控风格）。
  • useDebouncedCallback — 对函数进行防抖（flush / cancel / isPending）。
• 节流也有相同的划分：useThrottledValue / useThrottledState / useThrottledCallback。
• **全屏：**使用 useFullscreenDocument 或 useFullscreenElement——9.x 中没有单独导出的 useFullscreen。
• 鼠标：useMouse 基于元素 ref；useMousePosition 跟踪文档级别的位置。
• 回调 ref 钩子（useResizeObserver、useMouse、useMutationObserver、许多交互钩子）可处理动态节点替换——优先使用返回的 ref 回调，不要沿用过时的 useRef 赋值模式。
• useFetch 是轻量级的 fetch 辅助工具，不是服务端状态库——适合少量一次性加载；不要把它当作 Query/SWR。
• 示例和生成的代码应避免依赖其他 Mantine 包，除非所在项目已依赖这些包，且用户要求使用相关功能。

迁移注意事项（8 → 9）

• Peer React 19.2+。
• useFullscreen → useFullscreenDocument / useFullscreenElement。
• useMouse 拆分为 useMouse + useMousePosition。
• useResizeObserver / useMutationObserver → 回调 ref API；外部节点使用 useMutationObserverTarget。
• useDisclosure 新增 handlers.set(boolean)。
• 类型重命名：UseScrollSpyReturnType → UseScrollSpyReturnValue、StateHistory → UseStateHistoryValue、OS → UseOSReturnValue。
• useMediaQuery 移除了对非常旧版本 Safari 的 matchMedia 回退支持。

验证

优先使用仓库中已有的检查。对于有实际意义的 @mantine/hooks 工作，纳入相关子集：

• 使用已安装的 @mantine/hooks 类型声明以及导出的选项/返回值类型进行类型检查。
• 确认导入仅来自 @mantine/hooks（仅处理钩子的任务不得意外引入 @mantine/core）。
• SSR/水合：断言服务端 HTML 对媒体/存储钩子使用预期的初始值；更改 getInitialValueInEffect 时，不会导致闪烁问题回归。
• 交互测试：外部点击节点（多节点列表使用状态回调；内部处理程序阻止事件传播时使用 capture: true）、跨平台的热键 mod、焦点陷阱 + 合并 ref、卸载时防抖的 cancel / flush。
• 迁移扫描：检查已移除的 useFullscreen、旧版鼠标/观察器 ref 模式以及已重命名的类型。