@aiquants/drag-drop-panels 0.7.2 → 0.8.0

package/src/drag-drop/hooks/useDragDropColumns.tsx

@@ -0,0 +1,446 @@
+import { useCallback, useEffect, useRef, useState } from "react"
+import { debugLog } from "../DebugComponents"
+import type { DebugConfig, TouchDragState, UseDragDropColumnsReturn } from "../types"
+import { DEFAULT_COLUMN_ID_CONFIG, sortColumnIds } from "../utils/columnIdUtils"
+import { useCustomDragHandlers } from "./useCustomDragHandlers"
+import { useDragDropState } from "./useDragDropState"
+import { useMouseTracking } from "./useMouseTracking"
+import { useNormalDragHandlers } from "./useNormalDragHandlers"
+import { usePanelManagement } from "./usePanelManagement"
+
+// Props型定義
+export interface UseDragDropColumnsProps {
+    // 初期設定
+    initialColumnPanels: Record<string, string[]>
+    initialPanelVisibility: Record<string, boolean>
+    initialDragModes?: Record<string, "normal" | "custom">
+
+    // デバッグ設定
+    debugConfig: DebugConfig
+
+    // アニメーション・タッチ設定
+    enableAnimation?: boolean
+    enableTouch?: boolean
+
+    // イベントコールバック
+    onPanelMove?: (panelId: string, fromColumn: string, toColumn: string, insertIndex: number) => void
+    onPanelVisibilityChange?: (panelId: string, isVisible: boolean) => void
+    onDragModeChange?: (panelId: string, mode: "normal" | "custom") => void
+    onColumnPanelsChange?: (newColumnPanels: Record<string, string[]>) => void
+
+    // 表示倍率 (ドラッグ中のゴースト表示等に反映させるために必要)
+    scale?: number
+}
+
+/**
+ * Main drag and drop columns hook - integrates all sub-hooks.
+ * メインドラッグ&ドロップカラムフック - 全てのサブフックを統合。
+ */
+export const useDragDropColumns = ({ initialColumnPanels, initialPanelVisibility, initialDragModes = {}, debugConfig, onPanelMove, onDragModeChange, onColumnPanelsChange, scale = 1 }: UseDragDropColumnsProps): UseDragDropColumnsReturn => {
+    // debugConfig を安定した参照で管理
+    const debugConfigRef = useRef(debugConfig)
+    // debugConfigRef を更新するが、useEffect の依存配列には含めない
+    debugConfigRef.current = debugConfig
+
+    // 基本状態管理
+    const [columnPanels, setColumnPanels] = useState(initialColumnPanels)
+    const [dragModes, setDragModes] = useState<Record<string, "normal" | "custom">>(initialDragModes)
+
+    // columnPanelsのrefを作成して依存関係の問題を解決
+    const columnPanelsRef = useRef(columnPanels)
+    columnPanelsRef.current = columnPanels
+
+    // 分割されたフック呼び出し
+    const dragDropState = useDragDropState()
+
+    const mouseTracking = useMouseTracking()
+
+    const panelManagement = usePanelManagement(initialPanelVisibility, scale)
+
+    // イベントハンドラーの安定した参照を提供するためのRef
+    const eventHandlersRef = useRef<{
+        mousemove: ((e: globalThis.MouseEvent) => void) | null
+        mouseup: ((e: globalThis.MouseEvent) => void) | null
+    }>({
+        mousemove: null,
+        mouseup: null,
+    })
+
+    // パネルIDから元の位置を見つけるヘルパー関数
+    const findPanelPosition = useCallback((panelId: string) => {
+        const columnKeys = Object.keys(columnPanelsRef.current)
+        const sortedColumnKeys = sortColumnIds(columnKeys, DEFAULT_COLUMN_ID_CONFIG) // カラムキーを正しい順序でソート
+
+        for (let columnIndex = 0; columnIndex < sortedColumnKeys.length; columnIndex++) {
+            const columnKey = sortedColumnKeys[columnIndex]
+            const panelIndex = columnPanelsRef.current[columnKey]?.indexOf(panelId) ?? -1
+            if (panelIndex !== -1) {
+                return { columnIndex, panelIndex }
+            }
+        }
+        return null
+    }, [])
+
+    // 共通：パネル移動処理
+    const performPanelMove = useCallback(
+        (draggedPanelId: string, targetColumnKey: string, targetInsertIndex: number) => {
+            debugLog(debugConfigRef.current, 1, "🔄 パネル移動実行:", draggedPanelId, "→", targetColumnKey, "@", targetInsertIndex)
+
+            setColumnPanels((prevColumnPanels: Record<string, string[]>) => {
+                const newColumnPanels = { ...prevColumnPanels }
+                const sourceColumnKey = Object.keys(newColumnPanels).find((key) => newColumnPanels[key].includes(draggedPanelId))
+
+                if (!sourceColumnKey) {
+                    console.error("Source column not found for panel:", draggedPanelId)
+                    return prevColumnPanels
+                }
+
+                // ターゲットカラムが存在しない場合はエラー
+                if (!newColumnPanels[targetColumnKey]) {
+                    console.error("Target column not found:", targetColumnKey)
+                    return prevColumnPanels
+                }
+
+                // 移動元と移動先が同じ列の場合
+                if (sourceColumnKey === targetColumnKey) {
+                    const columnPanels = [...newColumnPanels[sourceColumnKey]]
+                    const sourceIndex = columnPanels.indexOf(draggedPanelId)
+
+                    // 1. 配列からドラッグした要素を一旦削除
+                    const [movedPanel] = columnPanels.splice(sourceIndex, 1)
+
+                    // 2. 正しい挿入位置を計算
+                    //    元の位置より前に挿入する場合はインデックスの変更なし
+                    //    元の位置より後ろに挿入する場合は、spliceで1つ要素が減った分インデックスを調整
+                    const adjustedInsertIndex = sourceIndex < targetInsertIndex ? targetInsertIndex - 1 : targetInsertIndex
+
+                    // 3. 正しい挿入位置に要素を挿入
+                    columnPanels.splice(adjustedInsertIndex, 0, movedPanel)
+
+                    newColumnPanels[targetColumnKey] = columnPanels
+                } else {
+                    // 移動元と移動先が異なる列の場合
+                    // 1. 移動元の列からパネルを削除
+                    newColumnPanels[sourceColumnKey] = newColumnPanels[sourceColumnKey].filter((id) => id !== draggedPanelId)
+
+                    // 2. 移動先の列の指定位置にパネルを挿入
+                    const targetPanels = [...newColumnPanels[targetColumnKey]]
+                    targetPanels.splice(targetInsertIndex, 0, draggedPanelId)
+                    newColumnPanels[targetColumnKey] = targetPanels
+                }
+
+                debugLog(debugConfigRef.current, 1, "✅ パネル移動完了:", draggedPanelId, "→", targetColumnKey)
+
+                // 外部コールバック実行（更新後の値を使用）
+                if (onColumnPanelsChange) {
+                    // setStateは非同期なので、次のフレームで実行
+                    requestAnimationFrame(() => {
+                        onColumnPanelsChange(newColumnPanels)
+                    })
+                }
+                if (onPanelMove) {
+                    const originalColumn = Object.keys(prevColumnPanels).find((column) => prevColumnPanels[column].includes(draggedPanelId))
+                    if (originalColumn) {
+                        requestAnimationFrame(() => {
+                            onPanelMove(draggedPanelId, originalColumn, targetColumnKey, targetInsertIndex)
+                        })
+                    }
+                }
+
+                return newColumnPanels
+            })
+        },
+        [onColumnPanelsChange, onPanelMove],
+    )
+
+    /**
+     * Handles the `dragenter` event on drop placeholders.
+     * Updates the drag-over position to show where the panel will be inserted.
+     *
+     * ドロッププレースホルダーでの `dragenter` イベントを処理します。
+     * ドラッグオーバー位置を更新して、パネルが挿入される場所を示します。
+     */
+    const handlePlaceholderDragEnter = useCallback(
+        (columnIndex: number, insertIndex: number) => {
+            if (!(dragDropState.dragState.isDragging || dragDropState.customDrag.isActive)) return
+
+            // Skip if trying to drop in the original position.
+            // 元の位置にドロップしようとしている場合はスキップします。
+            const originalPos = dragDropState.originalPanelPosition
+            if (originalPos && originalPos.columnIndex === columnIndex && (originalPos.panelIndex === insertIndex || originalPos.panelIndex + 1 === insertIndex)) {
+                debugLog(debugConfigRef.current, 1, `元の位置への挿入をスキップ: カラム${columnIndex}, 位置${insertIndex}`)
+                return
+            }
+
+            // Update position only if it has changed.
+            // 位置が変更された場合のみ更新します。
+            const currentPosition = dragDropState.dragOverPosition
+            if (!currentPosition || currentPosition.columnIndex !== columnIndex || currentPosition.insertIndex !== insertIndex) {
+                debugLog(debugConfigRef.current, 1, `プレースホルダーエンター: カラム${columnIndex}, 位置${insertIndex}`)
+                dragDropState.setDragOverPosition({ columnIndex, insertIndex })
+                dragDropState.setDragState((prev) => ({ ...prev, dragOverColumn: columnIndex }))
+            }
+        },
+        [dragDropState],
+    )
+
+    /**
+     * Unified placeholder drag leave handler for both normal and custom drag operations.
+     * For normal drag: performs DOM event checks before clearing (when event is provided).
+     * For custom drag: simply clears the drag-over position (when no event is provided).
+     *
+     * ノーマルドラッグとカスタムドラッグ両方に対応する統一プレースホルダーリーブハンドラー。
+     * ノーマルドラッグ: DOM イベントチェック付きでクリア（イベントが提供された場合）。
+     * カスタムドラッグ: 単純にドラッグオーバー位置をクリア（イベントが提供されない場合）。
+     */
+    const handlePlaceholderDragLeave = useCallback(
+        (e?: React.DragEvent, columnIndex?: number, insertIndex?: number) => {
+            if (!(dragDropState.dragState.isDragging || dragDropState.customDrag.isActive)) return
+
+            if (dragDropState.customDrag.isActive) {
+                // カスタムドラッグの場合：シンプルにクリア
+                debugLog(debugConfigRef.current, 1, "🚫 カスタムドラッグ - プレースホルダーリーブ: ハイライトを解除します。")
+                dragDropState.setDragOverPosition(null)
+            } else if (dragDropState.dragState.isDragging && e && columnIndex !== undefined && insertIndex !== undefined) {
+                // ノーマルドラッグの場合：DOM イベントチェック付きでクリア
+                const currentPos = dragDropState.dragOverPosition
+                if (currentPos && currentPos.columnIndex === columnIndex && currentPos.insertIndex === insertIndex) {
+                    const placeholderElement = e.currentTarget as HTMLElement
+                    const relatedTarget = e.relatedTarget as Node | null
+
+                    // Check if the mouse has truly left the element and its children.
+                    // マウスが要素とその子要素から本当に離れたかどうかを確認します。
+                    if (!(relatedTarget && placeholderElement.contains(relatedTarget))) {
+                        debugLog(debugConfigRef.current, 1, `ノーマルドラッグ - プレースホルダーリーブ: カラム${columnIndex}, 位置${insertIndex}。ハイライトを解除します。`)
+                        dragDropState.setDragOverPosition(null)
+                    }
+                }
+            }
+        },
+        [dragDropState],
+    )
+
+    const customDragHandlers = useCustomDragHandlers({
+        debugConfig: debugConfigRef.current,
+        dragState: dragDropState.dragState,
+        customDrag: dragDropState.customDrag,
+        clickState: dragDropState.clickState,
+        dragModes,
+        isMouseDown: dragDropState.isMouseDown,
+        originalPanelPosition: dragDropState.originalPanelPosition,
+        dragOverPosition: dragDropState.dragOverPosition,
+        setCustomDrag: dragDropState.setCustomDrag,
+        setDragState: dragDropState.setDragState,
+        setDragOverPosition: dragDropState.setDragOverPosition,
+        setOriginalPanelPosition: dragDropState.setOriginalPanelPosition,
+        setClickState: dragDropState.setClickState,
+        setIsMouseDown: dragDropState.setIsMouseDown,
+        findPanelPosition,
+        performPanelMove,
+        showMousePosition: mouseTracking.showMousePosition,
+        updateMousePosition: mouseTracking.updateMousePosition,
+        recordMouseDown: mouseTracking.recordMouseDown,
+        recordClickPosition: mouseTracking.recordClickPosition,
+        isVirtualClick: mouseTracking.isVirtualClick,
+        calculateMoveDistance: mouseTracking.calculateMoveDistance,
+        clearMouseTracking: mouseTracking.clearMouseTracking,
+        resetDragState: dragDropState.resetDragState,
+        resetClickState: dragDropState.resetClickState,
+        createDragImage: panelManagement.createDragImage,
+        updateDragImagePosition: panelManagement.updateDragImagePosition,
+        removeDragImage: panelManagement.removeDragImage,
+        handlePlaceholderDragEnter,
+        handlePlaceholderDragLeave,
+    })
+
+    const normalDragHandlers = useNormalDragHandlers({
+        debugConfig: debugConfigRef.current,
+        dragState: dragDropState.dragState,
+        customDrag: dragDropState.customDrag,
+        dragModes,
+        columnPanels,
+        dragOverPosition: dragDropState.dragOverPosition,
+        originalPanelPosition: dragDropState.originalPanelPosition,
+        setDragState: dragDropState.setDragState,
+        setDragOverPosition: dragDropState.setDragOverPosition,
+        setOriginalPanelPosition: dragDropState.setOriginalPanelPosition,
+        performPanelMove,
+        showMousePosition: mouseTracking.showMousePosition,
+        updateMousePosition: mouseTracking.updateMousePosition,
+        resetDragState: dragDropState.resetDragState,
+        handlePlaceholderDragEnter,
+        handlePlaceholderDragLeave,
+        scale,
+    })
+
+    // イベントリスナーの安定した参照を保持するためのラッパー関数
+    const stableMouseMoveHandler = useCallback((e: globalThis.MouseEvent) => {
+        if (eventHandlersRef.current.mousemove) {
+            eventHandlersRef.current.mousemove(e)
+        }
+    }, [])
+
+    const stableMouseUpHandler = useCallback((e: globalThis.MouseEvent) => {
+        if (eventHandlersRef.current.mouseup) {
+            eventHandlersRef.current.mouseup(e)
+        }
+    }, [])
+
+    // refベースのグローバルイベントリスナー管理
+    useEffect(() => {
+        debugLog(debugConfigRef.current, 1, "🔧 グローバルイベントリスナー初期化 - refベース管理開始")
+
+        document.addEventListener("mousemove", stableMouseMoveHandler)
+        document.addEventListener("mouseup", stableMouseUpHandler)
+
+        return () => {
+            debugLog(debugConfigRef.current, 1, "🔴 グローバルイベントリスナー終了 - refベース管理終了")
+            document.removeEventListener("mousemove", stableMouseMoveHandler)
+            document.removeEventListener("mouseup", stableMouseUpHandler)
+        }
+    }, [stableMouseMoveHandler, stableMouseUpHandler])
+
+    // イベントハンドラー設定の統一管理
+    useEffect(() => {
+        const needsPattern1Handler = !dragDropState.clickState.isClicked && Object.entries(dragModes).some(([, mode]) => mode === "custom")
+        const needsPattern23Handler = dragDropState.clickState.isClicked && dragDropState.clickState.panelId
+
+        if (needsPattern1Handler || needsPattern23Handler) {
+            const patternType = needsPattern1Handler ? "パターン1（仮想クリック検出）" : "パターン2,3（ドラッグ準備）"
+            debugLog(debugConfigRef.current, 1, `🔧 イベントハンドラー設定開始: ${patternType}`)
+
+            eventHandlersRef.current.mousemove = customDragHandlers.handleGlobalMouseMove
+            eventHandlersRef.current.mouseup = customDragHandlers.handleGlobalMouseUp
+        } else {
+            if (!(dragDropState.customDrag.isActive || dragDropState.dragState.isDragging)) {
+                eventHandlersRef.current.mousemove = null
+                eventHandlersRef.current.mouseup = null
+            }
+        }
+    }, [dragDropState.clickState.isClicked, dragDropState.clickState.panelId, dragModes, dragDropState.customDrag.isActive, dragDropState.dragState.isDragging, customDragHandlers.handleGlobalMouseMove, customDragHandlers.handleGlobalMouseUp])
+
+    // タッチイベントハンドラー（簡略版）
+    const handleTouchStart = useCallback(
+        (e: React.TouchEvent, panelId: string) => {
+            const touch = e.touches[0]
+            const element = e.currentTarget as HTMLElement
+
+            dragDropState.setTouchDragState({
+                isTouchDragging: true,
+                startX: touch.clientX,
+                startY: touch.clientY,
+                currentX: touch.clientX,
+                currentY: touch.clientY,
+                draggedElement: element,
+            })
+
+            dragDropState.setDragState({
+                isDragging: true,
+                draggedPanel: panelId,
+                dragOverColumn: null,
+            })
+        },
+        [dragDropState],
+    )
+
+    const handleTouchMove = useCallback(
+        (e: React.TouchEvent) => {
+            if (!dragDropState.touchDragState.isTouchDragging) return
+            e.preventDefault()
+
+            const touch = e.touches[0]
+            dragDropState.setTouchDragState((prev: TouchDragState) => ({
+                ...prev,
+                currentX: touch.clientX,
+                currentY: touch.clientY,
+            }))
+        },
+        [dragDropState.touchDragState.isTouchDragging, dragDropState],
+    )
+
+    const handleTouchEnd = useCallback(
+        (_e: React.TouchEvent) => {
+            if (!dragDropState.touchDragState.isTouchDragging) return
+
+            dragDropState.setTouchDragState({
+                isTouchDragging: false,
+                startX: 0,
+                startY: 0,
+                currentX: 0,
+                currentY: 0,
+                draggedElement: null,
+            })
+
+            normalDragHandlers.handleDragEnd()
+        },
+        [dragDropState.touchDragState.isTouchDragging, dragDropState, normalDragHandlers],
+    )
+
+    // ドラッグモード切り替え
+    const toggleDragMode = useCallback(
+        (panelId: string) => {
+            debugLog(debugConfigRef.current, 1, "🔄 toggleDragMode called:", { panelId })
+            setDragModes((prev) => {
+                const currentMode = prev[panelId] || "normal"
+                const newMode: "normal" | "custom" = currentMode === "normal" ? "custom" : "normal"
+                const newModes = { ...prev, [panelId]: newMode }
+
+                if (onDragModeChange) {
+                    try {
+                        onDragModeChange(panelId, newMode)
+                    } catch (error) {
+                        console.error("🔄 Error in onDragModeChange:", error)
+                    }
+                }
+
+                return newModes
+            })
+        },
+        [onDragModeChange],
+    )
+
+    // パネルサイズ情報クリック処理
+    const handlePanelSizeInfoClick = useCallback((e: React.MouseEvent | React.TouchEvent, panelId: string) => {
+        e.stopPropagation()
+        debugLog(debugConfigRef.current, 2, "パネルサイズ情報クリック:", panelId)
+    }, [])
+
+    return {
+        // 状態
+        columnPanels,
+        panelVisibility: panelManagement.panelVisibility,
+        dragModes,
+        dragState: dragDropState.dragState,
+        dragOverPosition: dragDropState.dragOverPosition,
+        originalPanelPosition: dragDropState.originalPanelPosition,
+        touchDragState: dragDropState.touchDragState,
+        customDrag: dragDropState.customDrag,
+        clickState: dragDropState.clickState,
+        mousePosition: mouseTracking.mousePosition,
+        panelSizes: panelManagement.panelSizes,
+
+        // 状態更新関数
+        setColumnPanels,
+        setPanelVisibility: panelManagement.setPanelVisibility,
+        setDragModes,
+        setPanelRef: panelManagement.setPanelRef,
+
+        // イベントハンドラー
+        handleDragStart: normalDragHandlers.handleDragStart,
+        handleDragEnd: normalDragHandlers.handleDragEnd,
+        handleMouseDown: customDragHandlers.handleMouseDown,
+        handleTouchStart,
+        handleTouchMove,
+        handleTouchEnd,
+        handlePlaceholderDragEnter,
+        handlePlaceholderDragLeave,
+        handleDragOverWithInsert: normalDragHandlers.handleDragOverWithInsert,
+        handleDropWithInsert: normalDragHandlers.handleDropWithInsert,
+        handleColumnDragLeave: normalDragHandlers.handleColumnDragLeave,
+        handlePanelSizeInfoClick,
+
+        // ユーティリティ関数
+        toggleDragMode,
+        findPanelPosition,
+    }
+}

package/src/drag-drop/hooks/useDragDropState.tsx

@@ -0,0 +1,200 @@
+/**
+ * @fileoverview This file defines the `useDragDropState` custom hook, which centralizes
+ * the state management for various aspects of the drag-and-drop functionality. It provides
+ * a structured way to handle states for normal drag, custom drag, touch drag, and click events.
+ *
+ * このファイルは `useDragDropState` カスタムフックを定義します。これは、ドラッグ＆ドロップ機能の
+ * 様々な側面の状態管理を一元化します。通常のドラッグ、カスタムドラッグ、タッチドラッグ、
+ * およびクリックイベントの状態を構造化された方法で処理する手段を提供します。
+ */
+import { useCallback, useState } from "react"
+import type { ClickState, CustomDragState, DragOverPosition, DragState, OriginalPanelPosition, TouchDragState } from "../types"
+
+/**
+ * A custom hook for managing all states related to drag-and-drop operations.
+ * It encapsulates the state logic, providing a clean interface for components to use.
+ *
+ * ドラッグ＆ドロップ操作に関連するすべての状態を管理するためのカスタムフック。
+ * 状態ロジックをカプセル化し、コンポーネントが使用するためのクリーンなインターフェースを提供します。
+ */
+export const useDragDropState = () => {
+    // --- State Definitions ---
+
+    /**
+     * Manages the primary state for standard HTML5 drag-and-drop operations.
+     * isDragging: Indicates if a drag operation is globally active.
+     * draggedPanel: The ID of the panel currently being dragged.
+     * dragOverColumn: The index of the column the panel is being dragged over.
+     *
+     * 標準のHTML5ドラッグ＆ドロップ操作の主要な状態を管理します。
+     * isDragging: ドラッグ操作がグローバルにアクティブかどうかを示します。
+     * draggedPanel: 現在ドラッグされているパネルのID。
+     * dragOverColumn: パネルがドラッグされているカラムのインデックス。
+     */
+    const [dragState, setDragState] = useState<DragState>({
+        isDragging: false,
+        draggedPanel: null,
+        dragOverColumn: null,
+    })
+
+    /**
+     * Stores the position where a panel is being dragged over (column and insert index).
+     * Null if not over a valid drop target.
+     *
+     * パネルがドラッグされている位置（カラムと挿入インデックス）を格納します。
+     * 有効なドロップターゲット上にない場合はnullです。
+     */
+    const [dragOverPosition, setDragOverPosition] = useState<DragOverPosition | null>(null)
+
+    /**
+     * Stores the original column and panel index of the panel when a drag operation starts.
+     *
+     * ドラッグ操作が開始されたときのパネルの元のカラムとパネルインデックスを格納します。
+     */
+    const [originalPanelPosition, setOriginalPanelPosition] = useState<OriginalPanelPosition | null>(null)
+
+    /**
+     * Manages the state for the custom mouse-based drag implementation.
+     * isActive: Indicates if the custom drag is currently active.
+     * panelId: The ID of the panel being dragged.
+     * startX/startY: The initial mouse coordinates when the drag started.
+     *
+     * マウスベースのカスタムドラッグ実装の状態を管理します。
+     * isActive: カスタムドラッグが現在アクティブかどうかを示します。
+     * panelId: ドラッグされているパネルのID。
+     * startX/startY: ドラッグが開始されたときの初期マウス座標。
+     */
+    const [customDrag, setCustomDrag] = useState<CustomDragState>({
+        isActive: false,
+        panelId: "",
+        startX: 0,
+        startY: 0,
+    })
+
+    /**
+     * Manages the state related to click events, used to initiate custom drags.
+     * isClicked: True if a panel has been clicked, pending a potential drag.
+     * panelId: The ID of the clicked panel.
+     *
+     * カスタムドラッグを開始するために使用されるクリックイベント関連の状態を管理します。
+     * isClicked: パネルがクリックされ、ドラッグの可能性がある場合はtrue。
+     * panelId: クリックされたパネルのID。
+     */
+    const [clickState, setClickState] = useState<ClickState>({
+        isClicked: false,
+        panelId: null,
+    })
+
+    /**
+     * Manages the state for touch-based drag-and-drop.
+     * isTouchDragging: Indicates if a touch-based drag is active.
+     * startX/startY: Initial touch coordinates.
+     * currentX/currentY: Current touch coordinates.
+     * draggedElement: The DOM element being dragged.
+     *
+     * タッチベースのドラッグ＆ドロップの状態を管理します。
+     * isTouchDragging: タッチベースのドラッグがアクティブかどうかを示します。
+     * startX/startY: 初期のタッチ座標。
+     * currentX/currentY: 現在のタッチ座標。
+     * draggedElement: ドラッグされているDOM要素。
+     */
+    const [touchDragState, setTouchDragState] = useState<TouchDragState>({
+        isTouchDragging: false,
+        startX: 0,
+        startY: 0,
+        currentX: 0,
+        currentY: 0,
+        draggedElement: null,
+    })
+
+    /**
+     * Tracks whether the mouse button is currently pressed down.
+     * マウスボタンが現在押されているかどうかを追跡します。
+     */
+    const [isMouseDown, setIsMouseDown] = useState<boolean>(false)
+
+    // --- Utility Functions ---
+
+    /**
+     * Resets all states related to drag operations (custom, standard, and position).
+     * This is typically called at the end of a drag-and-drop sequence.
+     *
+     * ドラッグ操作に関連するすべての状態（カスタム、標準、および位置）をリセットします。
+     * これは通常、ドラッグ＆ドロップシーケンスの最後に呼び出されます。
+     */
+    const resetDragState = useCallback(() => {
+        setCustomDrag({ isActive: false, panelId: "", startX: 0, startY: 0 })
+        setDragState({ isDragging: false, draggedPanel: null, dragOverColumn: null })
+        setDragOverPosition(null)
+        setOriginalPanelPosition(null)
+    }, [])
+
+    /**
+     * Resets the click and mouse-down states.
+     *
+     * クリックおよびマウスダウンの状態をリセットします。
+     */
+    const resetClickState = useCallback(() => {
+        setClickState({ isClicked: false, panelId: null })
+        setIsMouseDown(false)
+    }, [])
+
+    // --- Stabilized State Setters ---
+    // By wrapping setters in useCallback, we ensure they have a stable identity across re-renders,
+    // which can help prevent unnecessary re-renders in child components that depend on them.
+    //
+    // セッターをuseCallbackでラップすることにより、再レンダリング間で安定したアイデンティティを確保します。
+    // これにより、それらに依存する子コンポーネントの不要な再レンダリングを防ぐことができます。
+
+    const setDragStateStable = useCallback((state: DragState | ((prev: DragState) => DragState)) => {
+        setDragState(state)
+    }, [])
+
+    const setDragOverPositionStable = useCallback((position: DragOverPosition | null) => {
+        setDragOverPosition(position)
+    }, [])
+
+    const setOriginalPanelPositionStable = useCallback((position: OriginalPanelPosition | null) => {
+        setOriginalPanelPosition(position)
+    }, [])
+
+    const setCustomDragStable = useCallback((state: CustomDragState | ((prev: CustomDragState) => CustomDragState)) => {
+        setCustomDrag(state)
+    }, [])
+
+    const setClickStateStable = useCallback((state: ClickState | ((prev: ClickState) => ClickState)) => {
+        setClickState(state)
+    }, [])
+
+    const setTouchDragStateStable = useCallback((state: TouchDragState | ((prev: TouchDragState) => TouchDragState)) => {
+        setTouchDragState(state)
+    }, [])
+
+    const setIsMouseDownStable = useCallback((isDown: boolean) => {
+        setIsMouseDown(isDown)
+    }, [])
+
+    return {
+        // States / 状態
+        dragState,
+        dragOverPosition,
+        originalPanelPosition,
+        customDrag,
+        clickState,
+        touchDragState,
+        isMouseDown,
+
+        // Stabilized Setters / 安定化されたセッター
+        setDragState: setDragStateStable,
+        setDragOverPosition: setDragOverPositionStable,
+        setOriginalPanelPosition: setOriginalPanelPositionStable,
+        setCustomDrag: setCustomDragStable,
+        setClickState: setClickStateStable,
+        setTouchDragState: setTouchDragStateStable,
+        setIsMouseDown: setIsMouseDownStable,
+
+        // Utility Functions / ユーティリティ関数
+        resetDragState,
+        resetClickState,
+    }
+}