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 export は追加されていません）に基づいてください。

ワークフロー

1. コードを変更する前に、プロジェクトを確認します。
   • インストールされている @mantine/hooks のバージョンと React の peer バージョン。
   • アプリが SPA のみか、SSR／ハイドレーションを使用しているか（getInitialValueInEffect とメディア／ストレージの hook に影響します）。
   • 使用する hook の種類：状態、ストレージ、イベント、オブザーバー、タイミング、インタラクションビルダー。
2. 動作や移行に関わる場合は、source-map.md でバージョンとドキュメントの URL を最新のものに更新します。
3. インストール、インポート、ユーティリティ、SSR のデフォルト値、型、パッケージの境界については、setup-core.md を使用します。
4. ブール値／リスト／オブジェクト／Map／Set の状態、非制御値、ストレージ、キュー、ページネーション、履歴については、state-storage.md を使用します。
5. クリックアウトサイド、ホットキー、フォーカス、ホバー／マウス、クリップボード、フルスクリーン、長押し、ウィンドウ／ドキュメントのイベントについては、ui-events.md を使用します。
6. メディアクエリ、オブザーバー、デバウンス／スロットル、タイマー、アイドル状態／ネットワーク／OS、フェッチについては、observers-timing.md を使用します。
7. 移動／ドラッグ／放射状配置、折りたたみ、マスク、ロービングインデックス、スプリッター、フローティングウィンドウ、選択、スクロールのヘルパーについては、advanced-interaction.md を使用します。
8. ドキュメントへのリンク付きの hook 一覧については、catalog.md を使用します。

実装時の判断

• @mantine/hooks からのみインポートしてください。 名前付きインポートを優先してください：import { useDisclosure, clamp } from '@mantine/hooks'。
• パッケージは単体で利用できます：React のみがピア依存関係です。他の Mantine パッケージがなくても、どの React ウェブアプリでも安全に使用できます。状態管理フック（例：usePagination、useQueue）は React Native でも動作しますが、DOM／ウィンドウ関連のフックは動作しません。
• 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、多くのインタラクション用フック）は、動的なノードの差し替えに対応しています。古くなった useRef の代入パターンではなく、返される ref コールバックを優先してください。
• useFetch は薄いラッパーのフェッチヘルパーであり、サーバー状態ライブラリではありません。単発の小規模な読み込みには適していますが、Query／SWR のように扱わないでください。
• 周辺プロジェクトがすでに他の Mantine パッケージに依存しており、ユーザーがその利用を求めている場合を除き、サンプルコードや生成コードに他の Mantine パッケージを含めないでください。

移行時の注意点（8 → 9）

• ピア依存の 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 パターン、名称変更された型を検索します。