@aiquants/resize-panels 1.7.3 → 1.8.0

package/src/PanelResizeHandle.tsx

@@ -0,0 +1,718 @@
+/**
+ * @file PanelResizeHandle component for custom resizable panels
+ * カスタムリサイズ可能パネルのための PanelResizeHandle コンポーネント
+ */
+
+import { type CSSProperties, memo, useCallback, useEffect, useId, useMemo, useRef, useState } from "react"
+import { twMerge } from "tailwind-merge"
+import { usePanelGroup } from "./context"
+import {
+    PANEL_COLLAPSE_THRESHOLD_MAX,
+    PANEL_COLLAPSE_THRESHOLD_RATIO,
+    PANEL_EXPAND_THRESHOLD_MAX,
+    PANEL_EXPAND_THRESHOLD_RATIO,
+    PANEL_HANDLE_DRAG_THROTTLE_MS,
+    PANEL_HANDLE_THICKNESS,
+    PANEL_HANDLE_VISIBILITY_THRESHOLD,
+    PANEL_KEYBOARD_RESIZE_STEP,
+    PANEL_VISIBLE_INDICATOR_SPACING,
+    type PanelResizeHandleProps,
+    type ResizeHandleLayoutData,
+} from "./types"
+import { calculateSnapThreshold, getConstraintInPixels, getContainerSize } from "./utils"
+
+/**
+ * Render an interactive divider that manages adjacent panel resizing gestures.
+ * 隣接パネルのリサイズ操作を管理するインタラクティブなディバイダーを描画するコンポーネント。
+ */
+export const PanelResizeHandle = memo(({ id, disabled = false, className, style, children, onDragging }: PanelResizeHandleProps) => {
+    const { direction, resizePanels, getPanel, collapsePanel, expandPanel, panels, reportHandleMeasurement, containerSize, layoutConstraintViolation } = usePanelGroup()
+    const [isDragging, setIsDragging] = useState(false)
+    const handleRef = useRef<HTMLButtonElement>(null)
+    const containerRef = useRef<HTMLElement | null>(null)
+
+    const leftPanelId = useRef<string>("")
+    const rightPanelId = useRef<string>("")
+    // 進行中ドラッグの後始末関数。アンマウント時や次のドラッグ開始時の残留リスナー掃除に使う
+    const dragCleanupRef = useRef<(() => void) | null>(null)
+    // RTL コンテキストでは DOM 順 (論理順) と視覚順が反転するため、座標計算の符号とオーバーレイ位置を切り替える
+    const [isRtl, setIsRtl] = useState(false)
+    const [adjacentPanelIds, setAdjacentPanelIds] = useState<{ left: string | null; right: string | null }>({ left: null, right: null })
+    const generatedId = useId()
+    const handleIdRef = useRef(id ?? `resize-handle-${generatedId}`)
+    const lastHandleMeasurementRef = useRef<ResizeHandleLayoutData | null>(null)
+    const resolvedHandleId = id ?? handleIdRef.current
+    const hasLayoutConstraintViolation = Boolean(layoutConstraintViolation)
+    const isHandleDisabled = disabled || hasLayoutConstraintViolation
+
+    /**
+     * Detect the panels adjacent to this handle by scanning sibling DOM elements.
+     * DOM の兄弟要素を走査してこのハンドルに隣接する左右のパネルを検出する。
+     */
+    const detectAdjacentPanels = useCallback(() => {
+        const handleElement = handleRef.current
+        if (!handleElement) return
+
+        const parent = handleElement.parentElement
+        if (!parent) return
+
+        containerRef.current = parent
+        if (typeof window !== "undefined") {
+            setIsRtl(window.getComputedStyle(parent).direction === "rtl")
+        }
+        const childrenElements = Array.from(parent.children)
+        const index = childrenElements.indexOf(handleElement)
+
+        let leftPanelElement: HTMLElement | null = null
+        let rightPanelElement: HTMLElement | null = null
+
+        // ハンドルより前方の要素を逆順に走査して左パネルを特定
+        for (let i = index - 1; i >= 0; i -= 1) {
+            const element = childrenElements[i] as HTMLElement
+            if (element.dataset.panelId) {
+                leftPanelElement = element
+                break
+            }
+        }
+
+        // ハンドルより後方の要素を走査して右パネルを特定
+        for (let i = index + 1; i < childrenElements.length; i += 1) {
+            const element = childrenElements[i] as HTMLElement
+            if (element.dataset.panelId) {
+                rightPanelElement = element
+                break
+            }
+        }
+
+        const nextLeftId = leftPanelElement?.dataset.panelId || ""
+        const nextRightId = rightPanelElement?.dataset.panelId || ""
+
+        // 検出結果が前回と同じなら state 更新を省略する
+        if (nextLeftId === leftPanelId.current && nextRightId === rightPanelId.current) {
+            return
+        }
+
+        leftPanelId.current = nextLeftId
+        rightPanelId.current = nextRightId
+
+        setAdjacentPanelIds({
+            left: nextLeftId || null,
+            right: nextRightId || null,
+        })
+    }, [])
+
+    // パネル構成 (ID 列) の変化を検知するためのキー。ドラッグ中のサイズ更新では変化しない
+    const panelIdsKey = useMemo(() => panels.map((panel) => panel.id).join("|"), [panels])
+
+    useEffect(() => {
+        // マウント時とパネルの増減・並び替え時に隣接パネルを再検出する
+        // (マウント時のみだと兄弟 Panel の条件付き追加/削除でハンドルが古い ID を掴んだままになる)
+        detectAdjacentPanels()
+    }, [detectAdjacentPanels, panelIdsKey])
+
+    useEffect(() => {
+        // ハンドル ID が外部から変更された場合に、旧 ID の測定結果をクリーンアップする
+        if (resolvedHandleId === handleIdRef.current) {
+            return
+        }
+
+        const previousId = handleIdRef.current
+        handleIdRef.current = resolvedHandleId
+        lastHandleMeasurementRef.current = null
+
+        if (previousId !== resolvedHandleId) {
+            reportHandleMeasurement(previousId, null)
+        }
+    }, [reportHandleMeasurement, resolvedHandleId])
+
+    useEffect(() => {
+        // コンポーネントのアンマウント時に、このハンドルの測定結果を破棄する
+        const finalId = handleIdRef.current
+        return () => {
+            reportHandleMeasurement(finalId, null)
+        }
+    }, [reportHandleMeasurement])
+
+    useEffect(() => {
+        // ドラッグ中にアンマウントされた場合も document リスナーとドラッグ状態を確実に破棄する
+        return () => {
+            dragCleanupRef.current?.()
+        }
+    }, [])
+
+    /**
+     * Initiates a resize drag interaction when the handle receives a pointer down event.
+     * リサイズハンドルがポインタダウンを受けた際にドラッグ操作を開始する処理。
+     */
+    const handlePointerDown = useCallback(
+        (event: React.PointerEvent<HTMLButtonElement>) => {
+            if (isHandleDisabled || !containerRef.current) return
+
+            // 既にドラッグ中の場合は 2 本目のポインタで新たなドラッグを開始しない
+            if (dragCleanupRef.current) return
+
+            event.preventDefault()
+            event.stopPropagation()
+
+            const container = containerRef.current
+            const { inner: containerSize } = getContainerSize(container, direction)
+            const startPosition = { x: event.clientX, y: event.clientY }
+
+            const leftPanel = getPanel(leftPanelId.current)
+            const rightPanel = getPanel(rightPanelId.current)
+
+            if (!(leftPanel && rightPanel)) return
+
+            const initialLeftSize = leftPanel.size
+            const initialRightSize = rightPanel.size
+
+            let lastUpdateTime = 0
+            const throttleMs = PANEL_HANDLE_DRAG_THROTTLE_MS
+
+            setIsDragging(true)
+            onDragging?.(true)
+
+            // このドラッグを開始したポインタだけを追跡する (2 本目のタッチ等の混入を防ぐ)
+            const dragPointerId = event.pointerId
+            const captureTarget = event.currentTarget
+
+            // RTL では DOM 順 (論理順) と視覚順が反転するため、水平ドラッグの変位符号を反転する
+            const isRtlDrag = direction === "horizontal" && typeof window !== "undefined" && window.getComputedStyle(container).direction === "rtl"
+
+            // ポインタキャプチャを取得してドラッグ中のイベント配送を固定
+            captureTarget.setPointerCapture(dragPointerId)
+
+            /**
+             * Handle pointer move events emitted during an active resize drag interaction.
+             * リサイズドラッグ操作中に発生するポインタ移動イベントを処理する関数。
+             */
+            const handlePointerMove = (moveEvent: PointerEvent) => {
+                // 別ポインタのイベントはドラッグ計算に混入させない
+                if (moveEvent.pointerId !== dragPointerId) return
+                if (!handleRef.current) return
+
+                moveEvent.preventDefault()
+                moveEvent.stopPropagation()
+
+                // スロットル処理: 頻繁な更新を抑制して計算負荷を下げる
+                const now = performance.now()
+                if (now - lastUpdateTime < throttleMs) return
+                lastUpdateTime = now
+
+                // ドラッグ開始位置からのピクセル変位を計算 (RTL の水平ドラッグは符号を反転)
+                const rawPixelDelta = direction === "horizontal" ? moveEvent.clientX - startPosition.x : moveEvent.clientY - startPosition.y
+                const pixelDelta = isRtlDrag ? -rawPixelDelta : rawPixelDelta
+                // 差分がゼロのときは状態変化がなく後続処理が無駄になるため中断
+                if (pixelDelta === 0) {
+                    return
+                }
+
+                const newLeftSizeInPixels = initialLeftSize + pixelDelta
+                const newRightSizeInPixels = initialRightSize - pixelDelta
+
+                // 最新のパネル状態を取得して折りたたみ状態などの変化を反映
+                const updatedLeftPanel = getPanel(leftPanelId.current)
+                const updatedRightPanel = getPanel(rightPanelId.current)
+
+                if (updatedLeftPanel && updatedRightPanel && leftPanelId.current && rightPanelId.current) {
+                    const leftMinSizePixels = getConstraintInPixels(updatedLeftPanel.minSize, 0, containerSize)
+                    const rightMinSizePixels = getConstraintInPixels(updatedRightPanel.minSize, 0, containerSize)
+                    const leftMinConstraintPixels = leftMinSizePixels
+                    const rightMinConstraintPixels = rightMinSizePixels
+
+                    // 折りたたみ・展開の閾値をコンテナサイズから算出
+                    const collapseThresholdPixels = Math.min(containerSize * PANEL_COLLAPSE_THRESHOLD_RATIO, PANEL_COLLAPSE_THRESHOLD_MAX)
+                    const expandThresholdPixels = Math.min(containerSize * PANEL_EXPAND_THRESHOLD_RATIO, PANEL_EXPAND_THRESHOLD_MAX)
+
+                    const rightCanCollapseFromStart = updatedRightPanel.collapseFromStart
+                    const rightCollapseDirection = updatedRightPanel.collapsedByDirection ?? "start"
+                    // 右パネルが折りたたみ可能で、新しいサイズが閾値を下回る場合は折りたたむ
+                    if (rightCanCollapseFromStart && !updatedRightPanel.collapsed && newRightSizeInPixels <= Math.max(rightMinSizePixels * 0.3, collapseThresholdPixels)) {
+                        collapsePanel(rightPanelId.current, "start")
+                        return
+                    }
+
+                    const leftCanCollapseFromEnd = updatedLeftPanel.collapseFromEnd
+                    const leftCollapseDirection = updatedLeftPanel.collapsedByDirection ?? "end"
+                    // 左パネルが折りたたみ可能で、新しいサイズが閾値を下回る場合は折りたたむ
+                    if (leftCanCollapseFromEnd && !updatedLeftPanel.collapsed && newLeftSizeInPixels <= Math.max(leftMinSizePixels * 0.3, collapseThresholdPixels)) {
+                        collapsePanel(leftPanelId.current, "end")
+                        return
+                    }
+
+                    // 右パネルが折りたたまれており、新しいサイズが展開閾値を超えた場合は展開
+                    if (updatedRightPanel.collapsed && newRightSizeInPixels > Math.max(rightMinSizePixels * 0.3, expandThresholdPixels)) {
+                        expandPanel(rightPanelId.current, rightCollapseDirection, newRightSizeInPixels)
+                        return
+                    }
+
+                    // 左パネルが折りたたまれており、新しいサイズが展開閾値を超えた場合は展開
+                    if (updatedLeftPanel.collapsed && newLeftSizeInPixels > Math.max(leftMinSizePixels * 0.3, expandThresholdPixels)) {
+                        expandPanel(leftPanelId.current, leftCollapseDirection, newLeftSizeInPixels)
+                        return
+                    }
+
+                    // スナップ処理: 最小サイズ以下になった場合はゼロサイズにスナップさせる
+                    if (containerSize > 0) {
+                        const totalPanelPixels = updatedLeftPanel.size + updatedRightPanel.size
+                        // コンテナ比率と定数に基づきゼロスナップの閾値を算出
+                        const snapThreshold = calculateSnapThreshold(containerSize)
+                        let snapped = false
+
+                        // 左パネルがスナップ可能で、新しいサイズがスナップ閾値以下の場合はゼロへスナップ
+                        if (leftMinConstraintPixels <= snapThreshold && newLeftSizeInPixels <= snapThreshold && initialLeftSize !== 0) {
+                            const snappedLeft = 0
+                            const snappedRight = Math.max(0, totalPanelPixels - snappedLeft)
+
+                            if (snappedRight >= rightMinConstraintPixels) {
+                                resizePanels(leftPanelId.current, rightPanelId.current, snappedLeft, snappedRight)
+                                snapped = true
+                            }
+                        } else if (rightMinConstraintPixels <= snapThreshold && newRightSizeInPixels <= snapThreshold && initialRightSize !== 0) {
+                            // 右パネルがスナップ可能で、新しいサイズがスナップ閾値以下の場合はゼロへスナップ
+                            const snappedRight = 0
+                            const snappedLeft = Math.max(0, totalPanelPixels - snappedRight)
+
+                            if (snappedLeft >= leftMinConstraintPixels) {
+                                resizePanels(leftPanelId.current, rightPanelId.current, snappedLeft, snappedRight)
+                                snapped = true
+                            }
+                        }
+
+                        if (snapped) {
+                            return
+                        }
+                    }
+
+                    // いずれかのパネルが折りたたまれている場合はリサイズ処理を中断
+                    if (updatedLeftPanel.collapsed || updatedRightPanel.collapsed) {
+                        return
+                    }
+
+                    // 通常のリサイズ処理を実行して隣接パネルのサイズを更新
+                    resizePanels(leftPanelId.current, rightPanelId.current, newLeftSizeInPixels, newRightSizeInPixels)
+                }
+            }
+
+            /**
+             * Tear down the active drag: remove listeners, release capture, and reset state.
+             * 進行中ドラッグの後始末: リスナー除去・キャプチャ解放・状態リセットを一括で行う。
+             * pointerup / pointercancel / lostpointercapture / アンマウントのどこから呼ばれても一度だけ実行される。
+             */
+            let dragActive = true
+            const stopDragging = () => {
+                if (!dragActive) return
+                dragActive = false
+                dragCleanupRef.current = null
+
+                setIsDragging(false)
+                onDragging?.(false)
+
+                document.removeEventListener("pointermove", handlePointerMove)
+                document.removeEventListener("pointerup", handlePointerUp)
+                document.removeEventListener("pointercancel", handlePointerCancel)
+                captureTarget.removeEventListener("lostpointercapture", handleLostPointerCapture)
+                if (captureTarget.hasPointerCapture?.(dragPointerId)) {
+                    captureTarget.releasePointerCapture(dragPointerId)
+                }
+            }
+
+            const handlePointerUp = (upEvent: PointerEvent) => {
+                // 別ポインタの離上ではドラッグを終了しない
+                if (upEvent.pointerId !== dragPointerId) return
+                stopDragging()
+            }
+
+            const handlePointerCancel = (cancelEvent: PointerEvent) => {
+                // OS 割込み (タッチジェスチャ奪取等) でキャンセルされた場合もドラッグ状態を残さない
+                if (cancelEvent.pointerId !== dragPointerId) return
+                stopDragging()
+            }
+
+            const handleLostPointerCapture = (lostEvent: PointerEvent) => {
+                // キャプチャ喪失 (要素の DOM 離脱等) 時のフォールバック終了処理
+                if (lostEvent.pointerId !== dragPointerId) return
+                stopDragging()
+            }
+
+            document.addEventListener("pointermove", handlePointerMove)
+            document.addEventListener("pointerup", handlePointerUp)
+            document.addEventListener("pointercancel", handlePointerCancel)
+            captureTarget.addEventListener("lostpointercapture", handleLostPointerCapture)
+            dragCleanupRef.current = stopDragging
+        },
+        [isHandleDisabled, direction, resizePanels, getPanel, collapsePanel, expandPanel, onDragging],
+    )
+
+    /**
+     * Resize adjacent panels with arrow keys for keyboard accessibility.
+     * キーボード (矢印キー) で隣接パネルをリサイズするアクセシビリティ対応。
+     * Shift 併用で 5 倍のステップ幅を適用する。
+     */
+    const handleKeyDown = useCallback(
+        (event: React.KeyboardEvent<HTMLButtonElement>) => {
+            if (isHandleDisabled) return
+
+            const isHorizontalDirection = direction === "horizontal"
+            const decreaseKey = isHorizontalDirection ? "ArrowLeft" : "ArrowUp"
+            const increaseKey = isHorizontalDirection ? "ArrowRight" : "ArrowDown"
+            if (event.key !== decreaseKey && event.key !== increaseKey) return
+
+            event.preventDefault()
+            event.stopPropagation()
+
+            let delta = (event.key === increaseKey ? 1 : -1) * (event.shiftKey ? PANEL_KEYBOARD_RESIZE_STEP * 5 : PANEL_KEYBOARD_RESIZE_STEP)
+            // RTL では DOM 順 (論理順) と視覚順が反転するため符号を反転する (ドラッグ開始時と同様に押下時点の値を都度参照)
+            const isRtlNow = isHorizontalDirection && typeof window !== "undefined" && containerRef.current !== null && window.getComputedStyle(containerRef.current).direction === "rtl"
+            if (isRtlNow) {
+                delta = -delta
+            }
+
+            const leftPanel = getPanel(leftPanelId.current)
+            const rightPanel = getPanel(rightPanelId.current)
+            if (!(leftPanel && rightPanel) || leftPanel.collapsed || rightPanel.collapsed) return
+
+            // 制約の最終判定はリデューサー側で行われる
+            resizePanels(leftPanelId.current, rightPanelId.current, leftPanel.size + delta, rightPanel.size - delta)
+        },
+        [isHandleDisabled, direction, getPanel, resizePanels],
+    )
+
+    const isHorizontal = direction === "horizontal"
+    const cursor = isHorizontal ? "cursor-col-resize" : "cursor-row-resize"
+
+    const baseHandleClasses = twMerge(
+        "group absolute z-20 flex select-none items-center justify-center border-none bg-transparent transition-colors duration-150 overflow-visible",
+        cursor,
+        isHorizontal ? "h-full" : "w-full",
+        !isHandleDisabled && "hover:bg-gray-200/70 dark:hover:bg-gray-700/70",
+        !isHandleDisabled && "active:bg-blue-300/60 dark:active:bg-blue-700/60",
+        isDragging && "bg-blue-200/80 dark:bg-blue-800/60",
+        isHandleDisabled && "cursor-not-allowed opacity-50",
+        "focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-opacity-50",
+        className,
+    )
+
+    const adjacentIndices = useMemo(() => {
+        // パネル ID からパネル配列内のインデックスを探索するヘルパー関数
+        const findIndex = (panelId: string | null) => {
+            if (!panelId) {
+                return -1
+            }
+            for (let index = 0; index < panels.length; index += 1) {
+                if (panels[index].id === panelId) {
+                    return index
+                }
+            }
+            return -1
+        }
+
+        return {
+            left: findIndex(adjacentPanelIds.left),
+            right: findIndex(adjacentPanelIds.right),
+        }
+    }, [adjacentPanelIds.left, adjacentPanelIds.right, panels])
+
+    const containerLength = isHorizontal ? containerSize.width : containerSize.height
+
+    const boundaryOffset = useMemo(() => {
+        // 指定範囲のパネルサイズ合計を安全に算出するヘルパー
+        const safeSum = (startIndex: number, endIndexInclusive: number) => {
+            if (startIndex > endIndexInclusive) {
+                return 0
+            }
+            let total = 0
+            for (let index = startIndex; index <= endIndexInclusive; index += 1) {
+                const panel = panels[index]
+                if (!panel) {
+                    continue
+                }
+                const candidateSize = panel.size ?? 0
+                const sanitizedSize = Math.max(0, candidateSize)
+                total += panel.collapsed ? 0 : sanitizedSize
+            }
+            return total
+        }
+
+        if (adjacentIndices.left >= 0) {
+            return safeSum(0, adjacentIndices.left)
+        }
+
+        if (adjacentIndices.right > 0) {
+            return safeSum(0, adjacentIndices.right - 1)
+        }
+
+        return 0
+    }, [adjacentIndices.left, adjacentIndices.right, panels])
+
+    const clampedOffset = useMemo(() => {
+        // 境界位置が無効値やコンテナ範囲外に逸脱した場合に補正
+        if (!Number.isFinite(boundaryOffset) || boundaryOffset < 0) {
+            return 0
+        }
+        if (containerLength > 0 && boundaryOffset > containerLength) {
+            return containerLength
+        }
+        return boundaryOffset
+    }, [boundaryOffset, containerLength])
+
+    const overlayBaseStyle = useMemo<CSSProperties>(() => {
+        const base: CSSProperties = {
+            position: "absolute",
+            zIndex: 20,
+            touchAction: "none",
+        }
+
+        if (isHorizontal) {
+            base.top = 0
+            // clampedOffset は DOM 順 (論理順) の先頭からの距離。RTL では右端基準へ変換して物理 left を求める
+            base.left = isRtl && containerLength > 0 ? `${containerLength - clampedOffset}px` : `${clampedOffset}px`
+            base.transform = "translateX(-50%)"
+            base.width = `${PANEL_HANDLE_THICKNESS}px`
+            base.height = "100%"
+        } else {
+            base.left = 0
+            base.top = `${clampedOffset}px`
+            base.transform = "translateY(-50%)"
+            base.height = `${PANEL_HANDLE_THICKNESS}px`
+            base.width = "100%"
+        }
+
+        return base
+    }, [clampedOffset, isHorizontal, isRtl, containerLength])
+
+    const indicatorGrouping = useMemo(() => {
+        const snapThreshold = calculateSnapThreshold(containerLength)
+        // パネルが実質的に折りたたまれているか判定するヘルパー関数
+        const isEffectivelyCollapsed = (panelIndex: number) => {
+            if (panelIndex < 0 || panelIndex >= panels.length) {
+                return false
+            }
+            const target = panels[panelIndex]
+            if (!target) {
+                return false
+            }
+            if (target.collapsed) {
+                return true
+            }
+            return target.size <= snapThreshold
+        }
+
+        // 指定インデックスから連続する折りたたみパネルの数を数える
+        const countCollapsed = (startIndex: number, step: 1 | -1) => {
+            if (!isEffectivelyCollapsed(startIndex)) {
+                return 0
+            }
+
+            let count = 0
+            for (let index = startIndex; index >= 0 && index < panels.length; index += step) {
+                if (!isEffectivelyCollapsed(index)) {
+                    break
+                }
+                count += 1
+            }
+            return count
+        }
+
+        const leftIndex = adjacentIndices.left
+        const rightIndex = adjacentIndices.right
+        const leftCollapsedCount = leftIndex >= 0 ? countCollapsed(leftIndex, -1) : 0
+        const rightCollapsedCount = rightIndex >= 0 ? countCollapsed(rightIndex, 1) : 0
+        const groupSize = leftCollapsedCount + rightCollapsedCount + 1
+        const overlapIndex = leftCollapsedCount
+
+        return {
+            groupSize,
+            overlapIndex,
+        }
+    }, [adjacentIndices.left, adjacentIndices.right, panels, containerLength])
+
+    const shouldHideHandle = useMemo(() => {
+        if (hasLayoutConstraintViolation) {
+            return true
+        }
+        // グループサイズが 1 以下の場合は単独ハンドルなので非表示にしない
+        if (indicatorGrouping.groupSize <= 1) {
+            return false
+        }
+        // ハンドルがグループ内の中間位置にある場合は重複防止のため非表示にする
+        const lastIndex = indicatorGrouping.groupSize - 1
+        return indicatorGrouping.overlapIndex > 0 && indicatorGrouping.overlapIndex < lastIndex
+    }, [indicatorGrouping, hasLayoutConstraintViolation])
+
+    const indicatorOffset = useMemo(() => {
+        // ハンドルが非表示の場合またはグループサイズが 1 以下の場合はオフセット不要
+        if (indicatorGrouping.groupSize <= 1 || shouldHideHandle) {
+            return 0
+        }
+
+        // 表示すべきインジケーターの個数を決定
+        const visibleCount = indicatorGrouping.groupSize > 1 ? 2 : 1
+        if (visibleCount === 1) {
+            return 0
+        }
+
+        // このハンドルが表示インジケーター群内のどの位置にあるか計算
+        const visibleIndex = indicatorGrouping.overlapIndex === 0 ? 0 : visibleCount - 1
+        const centerIndex = (visibleCount - 1) / 2
+        return (visibleIndex - centerIndex) * PANEL_VISIBLE_INDICATOR_SPACING
+    }, [indicatorGrouping, shouldHideHandle])
+
+    const indicatorWrapperStyle = useMemo(() => {
+        // ハンドルを非表示にする場合は表示なし
+        if (shouldHideHandle) {
+            return { display: "none" }
+        }
+
+        // オフセットがゼロの場合はスタイル不要
+        if (indicatorOffset === 0) {
+            return undefined
+        }
+
+        // オフセット分だけインジケーターを移動
+        return isHorizontal ? { transform: `translateX(${indicatorOffset}px)` } : { transform: `translateY(${indicatorOffset}px)` }
+    }, [indicatorOffset, isHorizontal, shouldHideHandle])
+
+    const indicatorWrapperClasses = twMerge(
+        "flex items-center justify-center rounded-full bg-white text-slate-700 ring-1 ring-inset ring-white/80 backdrop-blur-sm transition-colors duration-150 shadow-[0_0_0_1px_rgba(255,255,255,0.85),0_1px_3px_rgba(15,23,42,0.18)]",
+        "dark:bg-slate-800/95 dark:text-slate-200 dark:ring-slate-500/60 dark:shadow-[0_0_0_1px_rgba(148,163,184,0.45),0_1px_3px_rgba(2,6,23,0.55)]",
+        isHorizontal ? "h-12 w-[6px] px-[2px]" : "h-[6px] w-20 py-[2px]",
+        isDragging && "bg-blue-200/80 ring-blue-300 shadow-[0_0_0_1px_rgba(191,219,254,0.65),0_1px_4px_rgba(59,130,246,0.45)] dark:bg-blue-900/70 dark:ring-blue-400 dark:shadow-[0_0_0_1px_rgba(147,197,253,0.5),0_1px_4px_rgba(59,130,246,0.55)]",
+    )
+
+    const indicatorBarClasses = twMerge(
+        "rounded-full bg-slate-600 transition-colors duration-150 shadow-[0_0_0_1px_rgba(255,255,255,0.9)] dark:bg-slate-200 dark:shadow-[0_0_0_1px_rgba(15,23,42,0.55)]",
+        isHorizontal ? "h-8 w-[2px]" : "h-[2px] w-16",
+        isDragging && "bg-blue-500 dark:bg-blue-300",
+        !isHandleDisabled && "group-hover:bg-slate-700 dark:group-hover:bg-slate-100",
+    )
+
+    const updateHandleMeasurement = useCallback(() => {
+        const element = handleRef.current
+        if (!element) {
+            return
+        }
+
+        let thickness = 0
+
+        // ハンドルが非表示の場合は厚みをゼロとして扱う
+        if (!shouldHideHandle) {
+            const baseSize = direction === "horizontal" ? element.offsetWidth : element.offsetHeight
+            let marginStart = 0
+            let marginEnd = 0
+
+            // CSS マージンを含めた実測厚みを計算
+            if (typeof window !== "undefined") {
+                const computedStyle = window.getComputedStyle(element)
+                if (direction === "horizontal") {
+                    marginStart = Number.parseFloat(computedStyle.marginLeft || "0")
+                    marginEnd = Number.parseFloat(computedStyle.marginRight || "0")
+                } else {
+                    marginStart = Number.parseFloat(computedStyle.marginTop || "0")
+                    marginEnd = Number.parseFloat(computedStyle.marginBottom || "0")
+                }
+            }
+
+            const candidates = [baseSize, marginStart, marginEnd]
+            thickness = candidates.reduce((sum, value) => {
+                if (!Number.isFinite(value)) {
+                    return sum
+                }
+                return sum + value
+            }, 0)
+        }
+
+        if (!Number.isFinite(thickness) || thickness < 0) {
+            thickness = 0
+        }
+
+        // 測定結果オブジェクトを構築
+        const measurement: ResizeHandleLayoutData = {
+            id: resolvedHandleId,
+            thickness,
+            direction,
+            visible: !shouldHideHandle && thickness > PANEL_HANDLE_VISIBILITY_THRESHOLD,
+            startPanelId: adjacentPanelIds.left,
+            endPanelId: adjacentPanelIds.right,
+        }
+
+        const lastMeasurement = lastHandleMeasurementRef.current
+
+        // 測定値が前回と実質的に同一であれば更新をスキップ
+        if (
+            lastMeasurement &&
+            Math.abs(lastMeasurement.thickness - measurement.thickness) <= 0.25 &&
+            lastMeasurement.visible === measurement.visible &&
+            lastMeasurement.direction === measurement.direction &&
+            lastMeasurement.startPanelId === measurement.startPanelId &&
+            lastMeasurement.endPanelId === measurement.endPanelId
+        ) {
+            return
+        }
+
+        lastHandleMeasurementRef.current = measurement
+        reportHandleMeasurement(resolvedHandleId, measurement)
+    }, [direction, adjacentPanelIds.left, adjacentPanelIds.right, reportHandleMeasurement, resolvedHandleId, shouldHideHandle])
+
+    useEffect(() => {
+        updateHandleMeasurement()
+    }, [updateHandleMeasurement])
+
+    useEffect(() => {
+        const element = handleRef.current
+        if (!element) {
+            return
+        }
+
+        // ResizeObserver が利用できない環境では初回のみ測定
+        if (typeof ResizeObserver === "undefined") {
+            updateHandleMeasurement()
+            return
+        }
+
+        // ハンドル要素のサイズ変化を監視して測定結果を更新
+        const observer = new ResizeObserver(() => {
+            updateHandleMeasurement()
+        })
+
+        observer.observe(element)
+
+        return () => {
+            observer.disconnect()
+        }
+    }, [updateHandleMeasurement])
+
+    const combinedStyle = useMemo<CSSProperties>(() => {
+        const merged = style ? { ...overlayBaseStyle, ...style } : overlayBaseStyle
+        if (shouldHideHandle) {
+            return {
+                ...merged,
+                display: "none" as CSSProperties["display"],
+                pointerEvents: "none" as CSSProperties["pointerEvents"],
+                visibility: "hidden" as CSSProperties["visibility"],
+            }
+        }
+        return merged
+    }, [overlayBaseStyle, shouldHideHandle, style])
+
+    return (
+        <button
+            type="button"
+            ref={handleRef}
+            className={baseHandleClasses}
+            style={combinedStyle}
+            onPointerDown={handlePointerDown}
+            onKeyDown={handleKeyDown}
+            disabled={isHandleDisabled}
+            aria-hidden={shouldHideHandle || undefined}
+            aria-label={`Resize ${isHorizontal ? "columns" : "rows"} - Drag or use arrow keys to resize, drag to the edge to collapse/expand panels`}
+            data-resize-handle-id={resolvedHandleId}
+            title={`ドラッグして${isHorizontal ? "列" : "行"}をリサイズ、端まで移動して折りたたみ/展開`}>
+            {children || (
+                <div className={indicatorWrapperClasses} style={indicatorWrapperStyle}>
+                    <span className={indicatorBarClasses} />
+                </div>
+            )}
+        </button>
+    )
+})