@aiquants/resize-panels 1.7.2 → 1.8.0

package/src/hooks.ts

@@ -0,0 +1,968 @@
+/**
+ * @file Custom hooks for resizable panels logic
+ * リサイズ可能パネルのロジックのためのカスタムフック
+ */
+
+import { type CSSProperties, useCallback, useEffect, useLayoutEffect, useMemo, useReducer, useRef, useState } from "react"
+import { usePanelGroup } from "./context"
+import { panelReducer } from "./reducer"
+import type { LayoutConstraintViolation, PanelCollapseDirection, PanelGroupProps, PanelLayoutData, PanelMeasurement, ResizeHandleLayoutData } from "./types"
+import { adjustPixelPanelsByPriority, clamp, getConstraintInPixels, getContainerSize, loadLayout, percentageToPixels, saveLayout, toRoundedPercentage } from "./utils"
+import { Logger, LogLevel } from "./utils/simple-logger"
+
+const logger = new Logger(LogLevel.INFO, "[resize-panels]")
+
+/**
+ * Orchestrate registration, constraint resolution, measurement sync, and persistence for a panel group.
+ * パネルグループにおける登録処理・制約判定・計測同期・永続化の統括。
+ */
+export const useResizablePanels = ({ direction, style, onLayout, autoSaveId, showDebugInfo = false }: PanelGroupProps) => {
+    const [panels, dispatch] = useReducer(panelReducer, [])
+    const [containerSize, setContainerSize] = useState({ width: 0, height: 0 })
+    const [isContainerReady, setIsContainerReady] = useState(false)
+    const [isInitialized, setIsInitialized] = useState(false)
+    const [layoutConstraintViolation, setLayoutConstraintViolation] = useState<LayoutConstraintViolation | null>(null)
+    const [panelMeasurements, setPanelMeasurements] = useState<Record<string, PanelMeasurement>>({})
+    const [handleMeasurements, setHandleMeasurements] = useState<Record<string, ResizeHandleLayoutData>>({})
+    const groupRef = useRef<HTMLDivElement>(null)
+    const layoutCallbackRef = useRef(onLayout)
+    const initializedRef = useRef(false)
+    const initializedPanelCountRef = useRef(0)
+    const prevContainerSizeRef = useRef(containerSize)
+    const containerInfoRef = useRef(containerSize)
+    const isContainerReadyRef = useRef(isContainerReady)
+    const violationReasonRef = useRef<LayoutConstraintViolation["reason"] | null>(layoutConstraintViolation?.reason ?? null)
+    const panelRegistrationSnapshotRef = useRef<Record<string, string>>({})
+    const lastStablePanelsRef = useRef<PanelLayoutData[] | null>(null)
+    const previousViolationRef = useRef<LayoutConstraintViolation | null>(null)
+    const containerSyncTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+    const lastRawContainerSizeRef = useRef({ width: 0, height: 0 })
+    const committedContainerSizeRef = useRef({ width: 0, height: 0 })
+    const panelSyncTimersRef = useRef<Record<string, ReturnType<typeof setTimeout>>>({})
+    const lastRawPanelMeasurementsRef = useRef<Record<string, PanelMeasurement>>({})
+
+    const clonePanels = useCallback((panelList: PanelLayoutData[]) => {
+        return panelList.map((panel) => ({ ...panel }))
+    }, [])
+
+    useEffect(() => {
+        containerInfoRef.current = containerSize
+    }, [containerSize])
+
+    useEffect(() => {
+        isContainerReadyRef.current = isContainerReady
+    }, [isContainerReady])
+
+    useEffect(() => {
+        violationReasonRef.current = layoutConstraintViolation?.reason ?? null
+    }, [layoutConstraintViolation?.reason])
+
+    useEffect(() => {
+        if (layoutConstraintViolation) {
+            return
+        }
+        const axisSize = direction === "horizontal" ? containerSize.width : containerSize.height
+        if (!Number.isFinite(axisSize) || axisSize <= 4) {
+            return
+        }
+        if (panels.length === 0) {
+            return
+        }
+        lastStablePanelsRef.current = clonePanels(panels)
+    }, [layoutConstraintViolation, panels, direction, containerSize.width, containerSize.height, clonePanels])
+
+    // 回復 effect から最新のパネル一覧を参照するための ref (依存に panels を入れると復元が違反解除の一回に限定できない)
+    const latestPanelsRef = useRef(panels)
+    useEffect(() => {
+        latestPanelsRef.current = panels
+    }, [panels])
+
+    useEffect(() => {
+        const previousViolation = previousViolationRef.current
+        if (layoutConstraintViolation) {
+            previousViolationRef.current = layoutConstraintViolation
+            return
+        }
+        if (previousViolation && !layoutConstraintViolation && lastStablePanelsRef.current) {
+            previousViolationRef.current = null
+            // 現在も登録されているパネルだけを復元する。
+            // 違反中に登録解除されたパネルをスナップショットから復活させると、対応するコンポーネントが
+            // 存在しないゾンビパネルとなり、違反も再発して解除不能になる
+            const registeredIds = new Set(latestPanelsRef.current.map((panel) => panel.id))
+            const snapshot = clonePanels(lastStablePanelsRef.current).filter((panel) => registeredIds.has(panel.id))
+            if (snapshot.length > 0) {
+                dispatch({ type: "SET_PANELS", panels: snapshot })
+            }
+            return
+        }
+        previousViolationRef.current = layoutConstraintViolation
+    }, [layoutConstraintViolation, clonePanels])
+
+    // コンテナサイズの変化を監視し、実測値が不安定な場合も安定した寸法を状態へ反映
+    useLayoutEffect(() => {
+        if (!groupRef.current) return
+
+        const resizeObserver = new ResizeObserver((entries) => {
+            for (const entry of entries) {
+                const targetElement = entry.target as HTMLElement
+                // getContainerSize の inner (枠線控除済み) を優先し、取得できない場合は contentRect をフォールバックに使用
+                const widthMeasurement = targetElement ? getContainerSize(targetElement, "horizontal") : null
+                const heightMeasurement = targetElement ? getContainerSize(targetElement, "vertical") : null
+                const measuredWidth = widthMeasurement ? widthMeasurement.inner : 0
+                const measuredHeight = heightMeasurement ? heightMeasurement.inner : 0
+                const fallbackWidth = entry.contentRect.width
+                const fallbackHeight = entry.contentRect.height
+                const width = measuredWidth > 0 ? measuredWidth : fallbackWidth
+                const height = measuredHeight > 0 ? measuredHeight : fallbackHeight
+                lastRawContainerSizeRef.current = { width, height }
+
+                const prev = committedContainerSizeRef.current
+                const isWidthChanged = Math.abs(prev.width - width) >= 0.5
+                const isHeightChanged = Math.abs(prev.height - height) >= 0.5
+
+                if (isWidthChanged || isHeightChanged) {
+                    // 閾値を超える変化は即座に反映し、待機中の同期をキャンセル
+                    if (containerSyncTimerRef.current) {
+                        clearTimeout(containerSyncTimerRef.current)
+                        containerSyncTimerRef.current = null
+                    }
+                    if (!isContainerReady && width > 0 && height > 0) {
+                        setIsContainerReady(true)
+                    }
+                    setContainerSize({ width, height })
+                    committedContainerSizeRef.current = { width, height }
+                } else {
+                    // 微小な変化はノイズとして即時更新はせず、静止後に最終同期をスケジュール
+                    if (containerSyncTimerRef.current) {
+                        clearTimeout(containerSyncTimerRef.current)
+                    }
+                    containerSyncTimerRef.current = setTimeout(() => {
+                        const finalSize = lastRawContainerSizeRef.current
+                        setContainerSize(finalSize)
+                        committedContainerSizeRef.current = finalSize
+                        containerSyncTimerRef.current = null
+                    }, 150)
+                }
+            }
+        })
+
+        resizeObserver.observe(groupRef.current)
+        return () => {
+            resizeObserver.disconnect()
+            if (containerSyncTimerRef.current) {
+                clearTimeout(containerSyncTimerRef.current)
+            }
+        }
+    }, [isContainerReady])
+
+    useEffect(() => {
+        // アンマウント時に全てのパネル同期タイマーをクリア
+        return () => {
+            for (const timer of Object.values(panelSyncTimersRef.current)) {
+                clearTimeout(timer)
+            }
+        }
+    }, [])
+
+    useLayoutEffect(() => {
+        const prevSize = prevContainerSizeRef.current
+        const currentSize = containerSize
+        // 0.5px 未満の微小な変化はノイズとして扱い、リサイズイベントの発火を抑制
+        const hasResized = direction === "horizontal" ? Math.abs(prevSize.width - currentSize.width) >= 0.5 : Math.abs(prevSize.height - currentSize.height) >= 0.5
+
+        // 初期化完了後にコンテナサイズが一定以上変化した場合、リサイズイベントを発行
+        if (isInitialized && hasResized) {
+            const newContainerSize = direction === "horizontal" ? currentSize.width : currentSize.height
+            dispatch({ type: "CONTAINER_RESIZED", containerSize: newContainerSize, direction })
+        }
+
+        prevContainerSizeRef.current = currentSize
+    }, [containerSize, isInitialized, direction])
+
+    /**
+     * Resolve pending panel initialization, reconcile constraint bounds against fresh measurements, and recover stored sizes.
+     * 初期化時にパネル整合性を再判定し、最新計測と制約を突き合わせた上で保存済み寸法を復元する処理。
+     */
+    const initializePanelsIfNeeded = useCallback(() => {
+        logger.debug("panels[0]?.id", panels[0]?.id)
+        // 折り畳み可能パネルや一時的にゼロへスナップしたパネルで保存済みピクセルサイズまたはパーセンテージがあるのにサイズが未解決の場合を検出
+        const hasUnresolvedPanels = panels.some((panel) => {
+            if (panel.collapsed) {
+                return false
+            }
+            if (panel.sizeUnit !== "percentage") {
+                return false
+            }
+            // 折り畳み前または直近測定のピクセルサイズを取得し、スナップゼロの復元に備える
+            const panelIsCollapsible = panel.collapseFromStart || panel.collapseFromEnd
+            const storedPixel = panelIsCollapsible ? (panel.sizeBeforeCollapse ?? panel.measuredPixelSizeBeforeCollapse ?? panel.originalPixelSize ?? panel.measuredPixelSize ?? 0) : (panel.measuredPixelSize ?? panel.originalPixelSize ?? panel.size)
+            const hasStoredPercentage = panel.percentageSize !== undefined && panel.percentageSize > 0
+            return panel.size <= 0 && (storedPixel > 0 || hasStoredPercentage)
+        })
+
+        // containerSize は getContainerSize(inner) により枠線控除済みの実寸法
+        const axisSize = direction === "horizontal" ? containerSize.width : containerSize.height
+        const hasContainerMeasurement = axisSize > 0
+
+        // 制約違反が検出されている場合は初期化をスキップ
+        if (layoutConstraintViolation) {
+            return
+        }
+
+        // コンテナサイズが未計測の場合は初期化をスキップ
+        if (!hasContainerMeasurement) {
+            return
+        }
+
+        // 未初期化パネルや折り畳み復元待ちパネルが残っているか判定
+        const needsInitialization = panels.length > 0 && (panels.length !== initializedPanelCountRef.current || !isInitialized || hasUnresolvedPanels)
+
+        if (!needsInitialization) {
+            return
+        }
+
+        // ピクセル基準パネルを抽出し固定領域を先に確保
+        const pixelPanels = panels.filter((panel) => !panel.collapsed && (panel.originalPixelSize !== undefined || panel.sizeUnit === "pixels"))
+        const allocatedPixelSpace = pixelPanels.reduce((sum, panel) => {
+            const preferredPixelSize = panel.preferredPixelSize ?? panel.originalPixelSize ?? panel.size
+            return sum + Math.max(0, preferredPixelSize ?? 0)
+        }, 0)
+
+        const activePercentagePanels = panels.filter((panel) => panel.sizeUnit === "percentage" && !panel.collapsed)
+        const activePercentageIds = activePercentagePanels.map((panel) => panel.id)
+        // パーセンテージ指定パネルの希望ピクセル値を再計算
+        const preferredPixelSnapshots = activePercentagePanels.map((panel) => {
+            const preferredPercentage = panel.preferredPercentageSize ?? panel.percentageSize
+            if (preferredPercentage !== undefined && preferredPercentage > 0) {
+                return percentageToPixels(preferredPercentage, axisSize)
+            }
+            if (panel.size > 0) {
+                return panel.size
+            }
+            return 0
+        })
+        const totalPreferredPixels = preferredPixelSnapshots.reduce((sum, value) => sum + value, 0)
+
+        // 固定領域を除いた残余スペースを算出し柔軟パネル側の調整有無を判断
+        const remainingSpace = axisSize - allocatedPixelSpace
+        const remainingFlexibleSpace = Math.max(0, remainingSpace)
+        const hasFlexibleRoom = remainingFlexibleSpace > 0
+
+        // パネルごとに復元・再計算した最終的な状態を集約
+        // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Panel resolution logic
+        const resolvedPanels = panels.map((panel) => {
+            if (panel.collapsed) {
+                // 折り畳み中パネルの復元用サイズを優先順で決定 (ピクセル基準)
+                // 優先順: sizeBeforeCollapse → measuredPixelSizeBeforeCollapse → originalPixelSize → size (pixels単位のみ)
+                const storedPixel = panel.sizeBeforeCollapse ?? panel.measuredPixelSizeBeforeCollapse ?? panel.originalPixelSize ?? (panel.sizeUnit === "pixels" ? panel.size : undefined)
+
+                // パーセンテージ単位パネルの場合は割合からピクセルへ変換
+                const restoredSizeFromPercentage = panel.sizeUnit === "percentage" && panel.percentageSize !== undefined ? percentageToPixels(panel.percentageSize, axisSize) : undefined
+
+                // 復元後に採用するサイズと測定スナップショットを決定
+                const recoveredSize = storedPixel ?? restoredSizeFromPercentage ?? 0
+                const recoveredMeasured = panel.measuredPixelSizeBeforeCollapse ?? panel.measuredPixelSize ?? recoveredSize
+
+                return {
+                    ...panel,
+                    size: 0,
+                    percentageSize: 0,
+                    preferredPercentageSize: panel.preferredPercentageSize,
+                    sizeBeforeCollapse: recoveredSize,
+                    percentageSizeBeforeCollapse: panel.percentageSizeBeforeCollapse ?? panel.percentageSize ?? panel.preferredPercentageSize ?? 0,
+                    preferredPercentageSizeBeforeCollapse: panel.preferredPercentageSizeBeforeCollapse ?? panel.preferredPercentageSize ?? panel.percentageSize ?? undefined,
+                    preferredPixelSizeBeforeCollapse: panel.preferredPixelSizeBeforeCollapse ?? panel.preferredPixelSize ?? recoveredSize,
+                    measuredPixelSizeBeforeCollapse: recoveredMeasured,
+                }
+            }
+
+            if (panel.sizeUnit === "pixels" || panel.originalPixelSize !== undefined) {
+                // 既にピクセル基準のパネルは測定値を再計算しつつそのまま採用
+                const pixelSize = panel.size
+                const percentageSize = axisSize > 0 ? toRoundedPercentage(pixelSize, axisSize) : 0
+
+                const nextPanel = {
+                    ...panel,
+                    size: pixelSize,
+                    percentageSize,
+                    preferredPixelSize: panel.preferredPixelSize ?? panel.originalPixelSize ?? pixelSize,
+                    preferredPercentageSize: panel.preferredPercentageSize !== undefined ? panel.preferredPercentageSize : percentageSize > 0 ? percentageSize : undefined,
+                }
+
+                if (panel.collapseFromStart || panel.collapseFromEnd) {
+                    // 折り畳み可能パネルは復元用のピクセルサイズと測定スナップショットを保持
+                    const storedSize = panel.sizeBeforeCollapse ?? pixelSize
+                    const storedMeasured = panel.measuredPixelSizeBeforeCollapse ?? panel.measuredPixelSize ?? storedSize
+                    nextPanel.sizeBeforeCollapse = storedSize
+                    nextPanel.measuredPixelSizeBeforeCollapse = storedMeasured
+                    nextPanel.preferredPixelSizeBeforeCollapse = panel.preferredPixelSizeBeforeCollapse ?? panel.preferredPixelSize ?? storedSize
+                }
+
+                return nextPanel
+            }
+
+            if (panel.sizeUnit === "percentage") {
+                // パーセンテージ基準パネルは希望寸法と制約を照らし合わせて実ピクセルへ再配分
+                const activeIndex = activePercentageIds.indexOf(panel.id)
+                const preferredPixels = activeIndex !== -1 ? preferredPixelSnapshots[activeIndex] : 0
+                const minSize = getConstraintInPixels(panel.minSize, 0, axisSize)
+                const maxSize = getConstraintInPixels(panel.maxSize, axisSize, axisSize)
+                // 過去の測定や折り畳み前サイズを重みとして再利用し柔軟パネルの再配分に最低限の基準を設ける
+                const fallbackPixels = Math.max(
+                    minSize,
+                    panel.sizeBeforeCollapse ?? 0,
+                    panel.measuredPixelSizeBeforeCollapse ?? 0,
+                    panel.measuredPixelSize ?? 0,
+                    panel.originalPixelSize ?? 0,
+                    panel.size > 0 ? panel.size : 0,
+                    panel.percentageSize !== undefined ? percentageToPixels(panel.percentageSize, axisSize) : 0,
+                    1,
+                )
+                const effectivePreferred = preferredPixels > 0 ? preferredPixels : fallbackPixels
+
+                let targetPixels: number
+
+                if (!hasFlexibleRoom) {
+                    // 柔軟領域が尽きている場合(ピクセルパネルがコンテナを使い切っている)、
+                    // パーセンテージパネルは最小サイズ(通常0)にする
+                    targetPixels = minSize
+                } else if (activeIndex !== -1 && totalPreferredPixels > 0) {
+                    // 希望比率に沿って残余領域を配分
+                    const ratio = effectivePreferred / totalPreferredPixels
+                    const candidatePixels = remainingFlexibleSpace * ratio
+                    targetPixels = clamp(candidatePixels, minSize, maxSize)
+                } else {
+                    // 現状または復元候補の寸法を基準に上限・下限内へ補正
+                    const currentPixels = panel.percentageSize !== undefined ? percentageToPixels(panel.percentageSize, axisSize) : panel.size
+                    const baselinePixels = currentPixels > 0 ? currentPixels : effectivePreferred
+                    targetPixels = clamp(baselinePixels, minSize, maxSize)
+                }
+
+                const nextPercentage = axisSize > 0 ? toRoundedPercentage(targetPixels, axisSize) : 0
+
+                const nextPanel = {
+                    ...panel,
+                    size: targetPixels,
+                    percentageSize: nextPercentage,
+                    preferredPercentageSize: panel.preferredPercentageSize !== undefined ? panel.preferredPercentageSize : nextPercentage > 0 ? nextPercentage : undefined,
+                }
+
+                if (panel.collapseFromStart || panel.collapseFromEnd) {
+                    const storedSize = panel.sizeBeforeCollapse ?? targetPixels
+                    const storedMeasured = panel.measuredPixelSizeBeforeCollapse ?? panel.measuredPixelSize ?? storedSize
+                    nextPanel.sizeBeforeCollapse = storedSize
+                    nextPanel.measuredPixelSizeBeforeCollapse = storedMeasured
+                    nextPanel.preferredPixelSizeBeforeCollapse = panel.preferredPixelSizeBeforeCollapse ?? panel.preferredPixelSize ?? storedSize
+                }
+
+                return nextPanel
+            }
+
+            return panel
+        })
+
+        // 柔軟パネルのインデックスを収集
+        const flexibleIndices: number[] = []
+        for (let index = 0; index < resolvedPanels.length; index += 1) {
+            const panel = resolvedPanels[index]
+            if (panel.sizeUnit === "percentage" && !panel.collapsed) {
+                flexibleIndices.push(index)
+            }
+        }
+
+        // 柔軟パネルに割り当てたピクセル合計と残余スペースの差分を計算
+        const allocatedFlexiblePixels = flexibleIndices.reduce((sum, index) => sum + resolvedPanels[index].size, 0)
+        const flexibleDiff = remainingSpace - allocatedFlexiblePixels
+
+        // 差分が閾値を超える場合はピクセルパネルの優先度順に吸収
+        if (Math.abs(flexibleDiff) > 0) {
+            adjustPixelPanelsByPriority(resolvedPanels, flexibleDiff, axisSize, { enforceAutoMinSize: true })
+        }
+
+        dispatch({ type: "SET_PANELS", panels: resolvedPanels })
+        initializedPanelCountRef.current = panels.length
+        setIsInitialized(true)
+    }, [panels, direction, containerSize.width, containerSize.height, isInitialized, layoutConstraintViolation])
+
+    // 制約チェックを独立して実行（コンテナサイズ変更時にも常に動作）
+    useEffect(() => {
+        // containerSize は getContainerSize(inner) により枠線控除済みの実寸法
+        const axisSize = direction === "horizontal" ? containerSize.width : containerSize.height
+        const hasContainerMeasurement = axisSize > 0
+
+        // 実測コンテナ寸法と登録済みパネルの有無から制約評価の要否を判断
+        const shouldEvaluateConstraints = hasContainerMeasurement && panels.length > 0
+
+        // パネルが存在しなければ制約違反そのものが成立しない
+        // (下の stale な違反 totals へのフォールバックに入ると、全パネル登録解除後も違反が永続してしまう)
+        if (hasContainerMeasurement && panels.length === 0) {
+            if (layoutConstraintViolation) {
+                setLayoutConstraintViolation(null)
+            }
+            return
+        }
+
+        // 有効なパネルが存在する場合は最小値と最大値の合計を算出
+        const totalMinimum = shouldEvaluateConstraints
+            ? panels.reduce((sum, panel) => {
+                  if (panel.collapsed) {
+                      return sum
+                  }
+                  const minPixels = getConstraintInPixels(panel.minSize, 0, axisSize)
+                  return sum + Math.max(0, minPixels)
+              }, 0)
+            : null
+        const totalMaximum = shouldEvaluateConstraints
+            ? panels.reduce((sum, panel) => {
+                  if (panel.collapsed) {
+                      return sum
+                  }
+                  const maxPixels = getConstraintInPixels(panel.maxSize, axisSize, axisSize)
+                  return sum + Math.max(0, maxPixels)
+              }, 0)
+            : null
+
+        // 直近の違反情報をフォールバックとして利用しつつ最新計算結果を優先
+        const effectiveMinimum = totalMinimum ?? layoutConstraintViolation?.totalMinimumSize ?? null
+        const effectiveMaximum = totalMaximum ?? layoutConstraintViolation?.totalMaximumSize ?? null
+
+        if (!hasContainerMeasurement) {
+            // 寸法が取得できていない場合は違反情報のみ更新し後段処理を停止
+            if (layoutConstraintViolation) {
+                setLayoutConstraintViolation((previous) => {
+                    if (!previous) {
+                        return previous
+                    }
+                    if (previous.availableContainerSize === axisSize) {
+                        return previous
+                    }
+                    return {
+                        reason: previous.reason,
+                        // totalMinimumSize: previous.totalMinimumSize,
+                        // totalMaximumSize: previous.totalMaximumSize,
+                        totalMinimumSize: null,
+                        totalMaximumSize: null,
+                        availableContainerSize: axisSize,
+                    }
+                })
+            }
+            return
+        }
+
+        // コンテナ寸法と総制約を比較して違反を検出
+        const minimumExceeded = effectiveMinimum !== null && effectiveMinimum - axisSize > Number.EPSILON
+        const maximumInsufficient = effectiveMaximum !== null && axisSize - effectiveMaximum > Number.EPSILON
+
+        if (minimumExceeded || maximumInsufficient) {
+            const reason = minimumExceeded ? "minimum-exceeded" : "maximum-insufficient"
+            const nextViolation: LayoutConstraintViolation = {
+                reason,
+                totalMinimumSize: effectiveMinimum,
+                totalMaximumSize: effectiveMaximum,
+                availableContainerSize: axisSize,
+            }
+
+            // 同一内容の違反通知を繰り返さないよう差分がある場合のみ更新
+            setLayoutConstraintViolation((previous) => {
+                if (
+                    previous &&
+                    previous.reason === nextViolation.reason &&
+                    Math.abs((previous.totalMinimumSize ?? 0) - (nextViolation.totalMinimumSize ?? 0)) <= Number.EPSILON &&
+                    Math.abs((previous.totalMaximumSize ?? 0) - (nextViolation.totalMaximumSize ?? 0)) <= Number.EPSILON &&
+                    Math.abs(previous.availableContainerSize - nextViolation.availableContainerSize) <= Number.EPSILON
+                ) {
+                    return previous
+                }
+                return nextViolation
+            })
+            return
+        }
+
+        if (layoutConstraintViolation) {
+            // 違反が発生していた場合は解消済みかどうかを判定
+            const requiresMinimum = layoutConstraintViolation.reason === "minimum-exceeded"
+            const requiresMaximum = layoutConstraintViolation.reason === "maximum-insufficient"
+            const hasMinimumData = effectiveMinimum !== null
+            const hasMaximumData = effectiveMaximum !== null
+            const canEvaluateMinimum = !requiresMinimum || hasMinimumData
+            const canEvaluateMaximum = !requiresMaximum || hasMaximumData
+
+            if (canEvaluateMinimum && canEvaluateMaximum && !minimumExceeded && !maximumInsufficient) {
+                // 条件が揃い再違反が検出されなければ違反状態を解除
+                setLayoutConstraintViolation((previous) => (previous ? null : previous))
+            }
+        }
+    }, [panels, direction, containerSize.width, containerSize.height, layoutConstraintViolation])
+
+    // 初期化漏れを防止するために必要時にリソルブ処理を呼び出す
+    useEffect(() => {
+        initializePanelsIfNeeded()
+    }, [initializePanelsIfNeeded])
+
+    // 最新のレイアウト通知コールバックを参照に保持
+    useEffect(() => {
+        layoutCallbackRef.current = onLayout
+    }, [onLayout])
+
+    // レイアウト通知のためにパネルサイズ一覧をメモ化
+    const panelSizes = useMemo(() => panels.map((panel) => panel.size), [panels])
+
+    // 初期化前の未確定サイズ (登録直後のパーセンテージパネルは 0) を onLayout や自動保存へ流さないためのゲート。
+    // 一度確定したら以降はゼロを含むレイアウト (スナップ等) も正しい状態として通知する
+    const hasSettledLayoutRef = useRef(false)
+
+    // 初期化後にレイアウトリスナーへ寸法を通知
+    useLayoutEffect(() => {
+        if (panels.length === 0) {
+            // 全パネルが登録解除されたら次の構成のために未確定状態へ戻す
+            hasSettledLayoutRef.current = false
+            return
+        }
+        if (!hasSettledLayoutRef.current && (isInitialized || panels.every((panel) => panel.collapsed || panel.size > 0))) {
+            hasSettledLayoutRef.current = true
+        }
+        if (!hasSettledLayoutRef.current) {
+            return
+        }
+        if (layoutCallbackRef.current) {
+            layoutCallbackRef.current(panelSizes)
+        }
+    }, [panelSizes, panels, isInitialized])
+
+    // 自動保存を遅延実行して書き込み回数を抑制
+    useEffect(() => {
+        // 未確定レイアウト (初期化前のゼロ) を保存すると復元時に壊れた配置になるため確定後のみ保存する
+        if (autoSaveId && panelSizes.length > 0 && hasSettledLayoutRef.current) {
+            // デバウンス処理: 200ms 後に自動保存を実行
+            const timeoutId = setTimeout(() => {
+                saveLayout(autoSaveId, panelSizes)
+            }, 200)
+
+            return () => clearTimeout(timeoutId)
+        }
+    }, [autoSaveId, panelSizes])
+
+    // 保存済みレイアウトがあれば初回のみ読み込む
+    useEffect(() => {
+        if (!autoSaveId || panels.length === 0 || initializedRef.current) {
+            return
+        }
+
+        const axisSize = direction === "horizontal" ? containerSize.width : containerSize.height
+        if (axisSize <= 0) {
+            return
+        }
+
+        const savedSizes = loadLayout(autoSaveId)
+        if (savedSizes && savedSizes.length === panels.length) {
+            const updatedPanels = panels.map((panel, index) => {
+                const minPixels = getConstraintInPixels(panel.minSize, 0, axisSize)
+                const maxPixels = getConstraintInPixels(panel.maxSize, axisSize, axisSize)
+                const clampedSize = clamp(savedSizes[index], minPixels, maxPixels)
+                const nextPercentage = toRoundedPercentage(clampedSize, axisSize)
+                const nextPreferredPixelSize = panel.sizeUnit === "pixels" || panel.originalPixelSize !== undefined ? clampedSize : panel.preferredPixelSize
+                return {
+                    ...panel,
+                    size: clampedSize,
+                    percentageSize: nextPercentage,
+                    preferredPercentageSize: nextPercentage > 0 ? nextPercentage : panel.preferredPercentageSize,
+                    preferredPixelSize: nextPreferredPixelSize,
+                }
+            })
+            dispatch({ type: "SET_PANELS", panels: updatedPanels })
+            initializedRef.current = true
+        }
+    }, [autoSaveId, panels, containerSize.width, containerSize.height, direction])
+
+    const registerPanel = useCallback((panel: PanelLayoutData) => {
+        const containerInfo = containerInfoRef.current
+        const registry = panelRegistrationSnapshotRef.current
+        const registrationSignature = JSON.stringify({
+            id: panel.id,
+            size: panel.size ?? null,
+            percentageSize: panel.percentageSize ?? null,
+            preferredPercentageSize: panel.preferredPercentageSize ?? null,
+            preferredPixelSize: panel.preferredPixelSize ?? null,
+            sizeUnit: panel.sizeUnit,
+            originalPixelSize: panel.originalPixelSize ?? null,
+            minSize: panel.minSize ?? null,
+            maxSize: panel.maxSize ?? null,
+            collapseFromStart: panel.collapseFromStart,
+            collapseFromEnd: panel.collapseFromEnd,
+            collapsed: panel.collapsed ?? false,
+            collapsedByDirection: panel.collapsedByDirection ?? null,
+            sizeBeforeCollapse: panel.sizeBeforeCollapse ?? null,
+            percentageSizeBeforeCollapse: panel.percentageSizeBeforeCollapse ?? null,
+            preferredPercentageSizeBeforeCollapse: panel.preferredPercentageSizeBeforeCollapse ?? null,
+            preferredPixelSizeBeforeCollapse: panel.preferredPixelSizeBeforeCollapse ?? null,
+            pixelAdjustPriority: panel.pixelAdjustPriority ?? null,
+            flexAdjustPriority: panel.flexAdjustPriority ?? null,
+            autoMinSize: panel.autoMinSize ?? null,
+        })
+
+        if (registry[panel.id] === registrationSignature) {
+            logger.debug("useResizablePanels.registerPanel skipped", {
+                panelId: panel.id,
+                reason: "duplicate-registration",
+            })
+            return
+        }
+
+        registry[panel.id] = registrationSignature
+        logger.debug("useResizablePanels.registerPanel", {
+            panelId: panel.id,
+            containerReady: isContainerReadyRef.current,
+            violationReason: violationReasonRef.current,
+            containerSize: {
+                width: containerInfo.width,
+                height: containerInfo.height,
+            },
+        })
+        // パネル登録アクションをディスパッチ
+        dispatch({ type: "REGISTER_PANEL", panel })
+    }, [])
+
+    const unregisterPanel = useCallback((id: string) => {
+        const containerInfo = containerInfoRef.current
+        logger.debug("useResizablePanels.unregisterPanel", {
+            panelId: id,
+            containerReady: isContainerReadyRef.current,
+            violationReason: violationReasonRef.current,
+            containerSize: {
+                width: containerInfo.width,
+                height: containerInfo.height,
+            },
+        })
+        // パネル登録解除アクションをディスパッチし、測定情報もクリア
+        dispatch({ type: "UNREGISTER_PANEL", id })
+        delete panelRegistrationSnapshotRef.current[id]
+        // 保留中の最終整合タイマーも破棄してゴーストエントリの再挿入を防ぐ
+        if (panelSyncTimersRef.current[id]) {
+            clearTimeout(panelSyncTimersRef.current[id])
+            delete panelSyncTimersRef.current[id]
+        }
+        delete lastRawPanelMeasurementsRef.current[id]
+        setPanelMeasurements((previous) => {
+            if (!(id in previous)) {
+                return previous
+            }
+            const next = { ...previous }
+            delete next[id]
+            return next
+        })
+    }, [])
+
+    /**
+     * Apply constraint-aware pixel adjustments while resizing adjacent panels.
+     * 隣接パネルのリサイズ時に制約を考慮したピクセル調整を適用。
+     */
+    const resizePanels = useCallback(
+        (leftId: string, rightId: string, leftSize: number, rightSize: number) => {
+            // フック側は「制約を大きく外さない初期値」を作る役割、リデューサー側が「最終確定」の役割を担う
+            // フック側はドラッグ中の左右ペアに即座に制約を適用して「安全な候補サイズ」を算出するだけで、他パネルとの整合や割合正規化までは扱わない
+            // ここではリデューサーの最終判定前にドラッグ中のペアに即応する安全な暫定寸法だけを算出する
+
+            const currentContainerSize = direction === "horizontal" ? containerSize.width : containerSize.height
+
+            const leftPanel = panels.find((panel) => panel.id === leftId)
+            const rightPanel = panels.find((panel) => panel.id === rightId)
+
+            // パネル情報が未取得でも従来ロジックで更新を継続
+            if (!(leftPanel && rightPanel)) {
+                dispatch({ type: "RESIZE_PANELS", leftId, rightId, leftSize, rightSize, containerSize: currentContainerSize })
+                return
+            }
+
+            // いずれかのパネルが折りたたまれている場合はリサイズを中断
+            if (leftPanel.collapsed || rightPanel.collapsed) {
+                return
+            }
+
+            const leftMinSize = getConstraintInPixels(leftPanel.minSize, 0, currentContainerSize)
+            const leftMaxSize = getConstraintInPixels(leftPanel.maxSize, currentContainerSize, currentContainerSize)
+            const rightMinSize = getConstraintInPixels(rightPanel.minSize, 0, currentContainerSize)
+            const rightMaxSize = getConstraintInPixels(rightPanel.maxSize, currentContainerSize, currentContainerSize)
+
+            let constrainedLeftSize = clamp(leftSize, leftMinSize, leftMaxSize)
+            let constrainedRightSize = clamp(rightSize, rightMinSize, rightMaxSize)
+
+            const targetTotalSize = constrainedLeftSize + constrainedRightSize
+            const originalTotalSize = leftSize + rightSize
+
+            // 制約適用後のサイズ合計と元のサイズ合計が異なる場合は追加の調整を実施
+            if (Math.abs(targetTotalSize - originalTotalSize) > 1e-9) {
+                const sizeDifference = originalTotalSize - targetTotalSize
+
+                if (sizeDifference > 0) {
+                    // 差分が正の場合は両パネルの拡張可能量を按分して補填
+                    const leftExpansionCapacity = leftMaxSize - constrainedLeftSize
+                    const rightExpansionCapacity = rightMaxSize - constrainedRightSize
+                    const totalExpansionCapacity = leftExpansionCapacity + rightExpansionCapacity
+
+                    if (totalExpansionCapacity > 0) {
+                        const leftExpansion = Math.min(sizeDifference * (leftExpansionCapacity / totalExpansionCapacity), leftExpansionCapacity)
+                        const rightExpansion = Math.min(sizeDifference - leftExpansion, rightExpansionCapacity)
+
+                        constrainedLeftSize += leftExpansion
+                        constrainedRightSize += rightExpansion
+                    }
+                } else if (sizeDifference < 0) {
+                    // 差分が負の場合は両パネルの縮小可能量を按分して削減
+                    const absoluteDifference = Math.abs(sizeDifference)
+                    const leftReductionCapacity = constrainedLeftSize - leftMinSize
+                    const rightReductionCapacity = constrainedRightSize - rightMinSize
+                    const totalReductionCapacity = leftReductionCapacity + rightReductionCapacity
+
+                    if (totalReductionCapacity > 0) {
+                        const leftReduction = Math.min(absoluteDifference * (leftReductionCapacity / totalReductionCapacity), leftReductionCapacity)
+                        const rightReduction = Math.min(absoluteDifference - leftReduction, rightReductionCapacity)
+
+                        constrainedLeftSize -= leftReduction
+                        constrainedRightSize -= rightReduction
+                    }
+                }
+            }
+
+            // 最終的に制約範囲内に再クランプしてリサイズアクションを発行
+            constrainedLeftSize = clamp(constrainedLeftSize, leftMinSize, leftMaxSize)
+            constrainedRightSize = clamp(constrainedRightSize, rightMinSize, rightMaxSize)
+
+            if (Math.abs(constrainedLeftSize + constrainedRightSize - originalTotalSize) > 1e-9) {
+                logger.error("Total size after constraints should be close to the original total size.", { constrainedLeftSize, constrainedRightSize, originalTotalSize })
+            }
+
+            dispatch({ type: "RESIZE_PANELS", leftId, rightId, leftSize: constrainedLeftSize, rightSize: constrainedRightSize, containerSize: currentContainerSize })
+        },
+        [direction, containerSize.width, containerSize.height, panels],
+    )
+
+    /**
+     * Collapse a panel while passing the current container size to the reducer.
+     * 現在のコンテナ寸法を渡しつつパネルの折り畳みを指示。
+     */
+    const collapsePanel = useCallback(
+        (id: string, from: PanelCollapseDirection) => {
+            // 現在のコンテナサイズを渡してパネル折りたたみアクションを発行
+            const currentContainerSize = direction === "horizontal" ? containerSize.width : containerSize.height
+            dispatch({ type: "COLLAPSE_PANEL", id, from, containerSize: currentContainerSize })
+        },
+        [direction, containerSize.width, containerSize.height],
+    )
+
+    /**
+     * Expand a panel with an optional target size in pixels.
+     * 任意のピクセル指定を考慮したパネル展開の指示。
+     */
+    const expandPanel = useCallback(
+        (id: string, from: PanelCollapseDirection, targetSize?: number) => {
+            // 現在のコンテナサイズを渡してパネル展開アクションを発行
+            const currentContainerSize = direction === "horizontal" ? containerSize.width : containerSize.height
+            dispatch({ type: "EXPAND_PANEL", id, from, containerSize: currentContainerSize, targetSize })
+        },
+        [direction, containerSize.width, containerSize.height],
+    )
+
+    /**
+     * Retrieve current layout data for the target panel.
+     * 対象パネルの最新レイアウトデータの取得。
+     */
+    const getPanel = useCallback(
+        (id: string) => {
+            // 指定 ID のパネルデータを返す
+            return panels.find((panel) => panel.id === id)
+        },
+        [panels],
+    )
+
+    /**
+     * Synchronize reported panel measurements with local measurement state.
+     * パネルから報告された測定情報の状態同期。
+     */
+    const reportPanelMeasurement = useCallback((panelId: string, measurement: PanelMeasurement | null) => {
+        if (measurement === null) {
+            // 保留中の最終整合タイマーと raw 測定値を破棄する
+            // (残したままだとパネル登録解除後にタイマーが発火してゴーストエントリを再挿入する)
+            if (panelSyncTimersRef.current[panelId]) {
+                clearTimeout(panelSyncTimersRef.current[panelId])
+                delete panelSyncTimersRef.current[panelId]
+            }
+            delete lastRawPanelMeasurementsRef.current[panelId]
+
+            // 測定結果が null の場合はエントリを削除
+            setPanelMeasurements((previous) => {
+                if (!(panelId in previous)) {
+                    return previous
+                }
+                const next = { ...previous }
+                delete next[panelId]
+                return next
+            })
+            return
+        }
+
+        setPanelMeasurements((previous) => {
+            const current = previous[panelId]
+            // 測定値が前回と実質的に同一であれば即時更新はスキップ (0.1px 未満の差異はノイズ)
+            const isPixelStable = current && Math.abs(current.pixelSize - measurement.pixelSize) < 0.1
+            const isPercentageStable = current && Math.abs(current.percentageSize - measurement.percentageSize) < 0.01
+
+            if (isPixelStable && isPercentageStable) {
+                // 静止後の最終整合のためにタイマーを再設定
+                if (panelSyncTimersRef.current[panelId]) {
+                    clearTimeout(panelSyncTimersRef.current[panelId])
+                }
+                lastRawPanelMeasurementsRef.current[panelId] = measurement
+                panelSyncTimersRef.current[panelId] = setTimeout(() => {
+                    const finalMeasurement = lastRawPanelMeasurementsRef.current[panelId]
+                    if (finalMeasurement) {
+                        setPanelMeasurements((prev) => ({
+                            ...prev,
+                            [panelId]: finalMeasurement,
+                        }))
+                    }
+                    delete panelSyncTimersRef.current[panelId]
+                }, 200)
+
+                return previous
+            }
+
+            // 大きな変化があった場合は待機中のタイマーを解除
+            if (panelSyncTimersRef.current[panelId]) {
+                clearTimeout(panelSyncTimersRef.current[panelId])
+                delete panelSyncTimersRef.current[panelId]
+            }
+
+            return {
+                ...previous,
+                [panelId]: measurement,
+            }
+        })
+    }, [])
+
+    /**
+     * Synchronize resize-handle measurements while ignoring negligible differences.
+     * リサイズハンドル測定値の同期と僅少差分の無視。
+     */
+    const reportHandleMeasurement = useCallback((handleId: string, measurement: ResizeHandleLayoutData | null) => {
+        setHandleMeasurements((previous) => {
+            if (measurement === null) {
+                // 測定結果が null の場合はエントリを削除
+                if (!(handleId in previous)) {
+                    return previous
+                }
+                const next = { ...previous }
+                delete next[handleId]
+                return next
+            }
+
+            const current = previous[handleId]
+            // 測定値が前回と実質的に同一であればスキップ
+            if (
+                current &&
+                Math.abs(current.thickness - measurement.thickness) <= 0.25 &&
+                current.visible === measurement.visible &&
+                current.direction === measurement.direction &&
+                current.startPanelId === measurement.startPanelId &&
+                current.endPanelId === measurement.endPanelId
+            ) {
+                return previous
+            }
+
+            return {
+                ...previous,
+                [handleId]: measurement,
+            }
+        })
+    }, [])
+
+    const contextValue = useMemo(
+        () => ({
+            direction,
+            panels,
+            containerSize,
+            isContainerReady,
+            showDebugInfo,
+            registerPanel,
+            unregisterPanel,
+            resizePanels,
+            collapsePanel,
+            expandPanel,
+            getPanel,
+            reportPanelMeasurement,
+            panelMeasurements,
+            reportHandleMeasurement,
+            handleMeasurements,
+            layoutConstraintViolation,
+        }),
+        [direction, panels, containerSize, isContainerReady, showDebugInfo, registerPanel, unregisterPanel, resizePanels, collapsePanel, expandPanel, getPanel, reportPanelMeasurement, panelMeasurements, reportHandleMeasurement, handleMeasurements, layoutConstraintViolation],
+    )
+
+    const groupStyle: CSSProperties = useMemo(
+        () => ({
+            display: "flex",
+            flexDirection: direction === "horizontal" ? "row" : "column",
+            alignItems: "stretch",
+            width: "100%",
+            height: "100%",
+            minWidth: "0px",
+            minHeight: "0px",
+            position: "relative",
+            overflow: "hidden", // リサイズハンドルのはみ出しでスクロールバーを表示させない
+            ...style,
+        }),
+        [direction, style],
+    )
+
+    return {
+        groupRef,
+        contextValue,
+        groupStyle,
+    }
+}
+
+/**
+ * Provide imperative helpers for toggling a specific panel while preserving stored sizing.
+ * 特定パネルの保存済みサイズを維持しつつ開閉を制御する命令型ユーティリティを提供するカスタムフック。
+ */
+export const usePanelControls = (panelId: string) => {
+    const { getPanel, collapsePanel, expandPanel } = usePanelGroup()
+    const panel = getPanel(panelId)
+
+    const collapse = useCallback(
+        (from: PanelCollapseDirection) => {
+            collapsePanel(panelId, from)
+        },
+        [collapsePanel, panelId],
+    )
+
+    const expand = useCallback(
+        (from: PanelCollapseDirection, targetSize?: number) => {
+            expandPanel(panelId, from, targetSize)
+        },
+        [expandPanel, panelId],
+    )
+
+    const toggle = useCallback(
+        (from: PanelCollapseDirection, targetSize?: number) => {
+            if (panel?.collapsed) {
+                expand(from, targetSize)
+            } else {
+                collapse(from)
+            }
+        },
+        [panel?.collapsed, collapse, expand],
+    )
+
+    return useMemo(
+        () => ({
+            panel,
+            isCollapsed: panel?.collapsed ?? false,
+            canCollapseFromStart: panel?.collapseFromStart ?? false,
+            canCollapseFromEnd: panel?.collapseFromEnd ?? false,
+            collapse,
+            expand,
+            toggle,
+        }),
+        [panel, collapse, expand, toggle],
+    )
+}