@aiquants/resize-panels 1.8.1 → 2.0.0

package/src/Panel.tsx

@@ -3,609 +3,272 @@
  * カスタムリサイズ可能パネルのための Panel コンポーネント
  */
 
-import { type CSSProperties, type MutableRefObject, memo, useCallback, useEffect, useId, useMemo, useRef, useState } from "react"
+import { type CSSProperties, memo, useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef } from "react"
 import { twMerge } from "tailwind-merge"
+import { resolvePanelBounds } from "./allocateLayout"
 import { usePanelGroup } from "./context"
 import { PanelDebugInfo } from "./PanelDebugInfo"
-import type { CollapsibleConfig, PanelCollapseDirection, PanelProps } from "./types"
-import { calculateSnapThreshold, getContainerSize, normalizeSizeConfig } from "./utils"
+import { type CollapsibleConfig, PANEL_ALLOCATION_EPSILON, type PanelLayoutData, type PanelProps, type PanelRegistration, type SizeConfig } from "./types"
+import { getContainerSize, normalizeSizeConfig, toRoundedPercentage } from "./utils"
 import { Logger, LogLevel } from "./utils/simple-logger"
 
 const logger = new Logger(LogLevel.INFO, "[resize-panels]")
 
-type NormalizedCollapsibleConfig = {
+/**
+ * Directional collapse flags derived from the collapsible configuration.
+ * 折りたたみ設定から導出した方向フラグ。
+ */
+type CollapseFlags = {
     collapseFromStart: boolean
     collapseFromEnd: boolean
 }
 
-const collapsibleMatrix = {
-    both: {
-        collapseFromStart: true,
-        collapseFromEnd: true,
-    },
-    start: {
-        collapseFromStart: true,
-        collapseFromEnd: false,
-    },
-    end: {
-        collapseFromStart: false,
-        collapseFromEnd: true,
-    },
-} as const
+const COLLAPSE_FLAGS: Record<CollapsibleConfig["from"], CollapseFlags> = {
+    both: { collapseFromStart: true, collapseFromEnd: true },
+    start: { collapseFromStart: true, collapseFromEnd: false },
+    end: { collapseFromStart: false, collapseFromEnd: true },
+}
 
 /**
  * Normalize collapsible configuration into directional flags.
- * 折りたたみ設定を方向フラグへ正規化。
+ * 折りたたみ設定を方向フラグへ正規化する処理。
+ *
+ * @param config - Collapsible configuration from props / props で指定された折りたたみ設定
+ * @returns Directional collapse flags / 方向ごとの折りたたみ可否
+ * @throws When the configuration names an unsupported direction / 未対応の方向が指定された場合
  */
-const normalizeCollapsibleConfig = (config: CollapsibleConfig | undefined): NormalizedCollapsibleConfig => {
+const normalizeCollapsibleConfig = (config: CollapsibleConfig | undefined): CollapseFlags => {
     if (!config) {
-        return {
-            collapseFromStart: false,
-            collapseFromEnd: false,
-        }
+        return { collapseFromStart: false, collapseFromEnd: false }
     }
-    const result = collapsibleMatrix[config.from]
-    if (!result) {
+    const flags = COLLAPSE_FLAGS[config.from]
+    if (!flags) {
         throw new Error("Invalid collapsible configuration: unsupported 'from' value")
     }
-    return result
+    return flags
 }
 
-type CommittedSetterParams = {
-    ref: MutableRefObject<number>
-    setState: (value: number) => void
-    panelIdRef: React.RefObject<string>
-    label: "pixel" | "percentage"
-    timerRef?: React.RefObject<ReturnType<typeof setTimeout> | null>
+/**
+ * Split a normalized default size into the preference fields of the layout state.
+ * 正規化済みの既定サイズを、レイアウト状態の希望値フィールドへ分解する処理。
+ *
+ * Exactly one of the two preferences carries meaning, selected by the unit, so the state never holds the
+ * same intent twice.
+ * 意味を持つ希望値は単位によって選ばれる 1 つだけであり、状態が同じ意図を二重に持つことはない。
+ *
+ * @param defaultSize - Normalized default size / 正規化済みの既定サイズ
+ * @returns Size unit and both preference fields / サイズ単位と 2 つの希望値フィールド
+ */
+const toPreference = (defaultSize: SizeConfig): Pick<PanelRegistration, "sizeUnit" | "preferredPercentageSize" | "preferredPixelSize"> => {
+    const value = Math.max(0, defaultSize.value)
+    return defaultSize.unit === "pixels" ? { sizeUnit: "pixels", preferredPixelSize: value, preferredPercentageSize: 0 } : { sizeUnit: "percentage", preferredPercentageSize: value, preferredPixelSize: 0 }
 }
 
 /**
- * Create a setter that commits numeric size while preventing redundant updates.
- * 冗長な更新を避けつつ数値サイズをコミットするセッターを生成。
+ * Flex triple a panel renders: the allocated length plus the weights that absorb a container change.
+ * パネルが描画する flex の三つ組: 配分された長さと、コンテナ変化を吸収する重み。
  */
-const createCommittedSetter = ({ ref, setState, panelIdRef, label, timerRef }: CommittedSetterParams) => {
-    return (nextValue: number) => {
-        if (!Number.isFinite(nextValue)) {
-            return
-        }
-        const sanitized = nextValue < 0 ? 0 : nextValue
-        const threshold = label === "pixel" ? 0.1 : 0.01
-        if (Math.abs(ref.current - sanitized) < threshold) {
-            // 閾値未満の変化は即時反映せず、静止後の最終同期をスケジュール
-            if (timerRef) {
-                if (timerRef.current) {
-                    clearTimeout(timerRef.current)
-                }
-                timerRef.current = setTimeout(() => {
-                    ref.current = sanitized
-                    setState(sanitized)
-                    timerRef.current = null
-                }, 200)
-            }
-            return
-        }
+type PanelFlexStyle = Required<Pick<CSSProperties, "flexBasis" | "flexGrow" | "flexShrink">>
+
+type ResolvePanelFlexArgs = {
+    size: number
+    panel: PanelLayoutData | undefined
+    registration: PanelRegistration
+    containerSize: number
+    isCollapsed: boolean
+}
+
+/**
+ * Resolve the flex triple that renders a panel's current state.
+ * パネルの現在の状態を描画する flex の三つ組を解決する処理。
+ *
+ * The basis is always the allocated length, so the rendered geometry is the allocator's answer and nothing
+ * else. The weights are the first-order continuation of that answer: a panel grows with its ratio weight
+ * until it reaches its maximum and shrinks only while it is strictly between its bounds, which is exactly
+ * how the allocator would move it for a small container change.
+ * basis は常に配分された長さであり、描画される幾何は配分器の答えそのものとなる。重みはその答えの
+ * 一次近似であり、上限に達するまでは比率の重みで伸び、上下限の内側にいる間だけ縮む。これは小さな
+ * コンテナ変化に対して配分器が動かす量と一致する。
+ *
+ * @param args - Allocated size, panel state, registration and container length / 配分サイズ・パネル状態・登録情報・コンテナ長
+ * @returns Flex basis, grow and shrink to render / 描画する flex basis・grow・shrink
+ */
+export const resolvePanelFlex = ({ size, panel, registration, containerSize, isCollapsed }: ResolvePanelFlexArgs): PanelFlexStyle => {
+    if (isCollapsed) {
+        return { flexBasis: "0px", flexGrow: 0, flexShrink: 0 }
+    }
 
-        // 閾値を超える変化があった場合は待機中のタイマーを解除し、即座に反映
-        if (timerRef?.current) {
-            clearTimeout(timerRef.current)
-            timerRef.current = null
+    if (!panel || containerSize <= 0) {
+        // まだ計測できていない間は宣言された既定サイズで描く。サーバー描画や初回フレームで
+        // 幅ゼロのパネルが一瞬見えるのを防ぎ、計測後の配分結果と連続した見た目になる
+        const isPixelRegistration = registration.sizeUnit === "pixels"
+        return {
+            flexBasis: isPixelRegistration ? `${registration.preferredPixelSize}px` : `${registration.preferredPercentageSize}%`,
+            flexGrow: isPixelRegistration ? 0 : registration.preferredPercentageSize,
+            flexShrink: isPixelRegistration ? 0 : 1,
         }
+    }
 
-        ref.current = sanitized
-        logger.debug(`commit ${label}`, {
-            panelId: panelIdRef.current,
-            [label]: sanitized,
-        })
-        setState(sanitized)
+    if (panel.sizeUnit === "pixels") {
+        // 固定長パネルはコンテナ変化を引き受けない。引き受けると配分器の答えと描画がずれる
+        return { flexBasis: `${size}px`, flexGrow: 0, flexShrink: 0 }
     }
+
+    // 内側にいるパネルの縮小重みが一律 1 で正しいのは、CSS の縮小配分が「重み × basis」であり
+    // basis が配分結果 (= λ × 重み) だからで、結果として重みの比で縮むため
+    const bounds = resolvePanelBounds(panel, containerSize)
+    const canGrow = size < bounds.max - PANEL_ALLOCATION_EPSILON
+    const isInterior = canGrow && size > bounds.min + PANEL_ALLOCATION_EPSILON
+    return { flexBasis: `${size}px`, flexGrow: canGrow ? panel.preferredPercentageSize : 0, flexShrink: isInterior ? 1 : 0 }
 }
 
 /**
- * Render a resizable panel within a managed group, keeping DOM measurements in sync with reducer state.
- * 管理対象グループ内で DOM 計測とリデューサー状態を同期させながらリサイズ可能パネルを描画するコンポーネント。
+ * Render a resizable panel whose size is decided by the group's allocator.
+ * グループの配分器が決めたサイズで描画されるリサイズ可能パネル。
+ *
+ * The panel publishes what it wants (its preference and constraints) and renders what it was given. Its
+ * flex basis is the allocated length itself, while `flex-grow` / `flex-shrink` describe how it should
+ * absorb a container change during the frames before the allocator runs again — a growth weight that
+ * vanishes at the panel's maximum and a shrink weight that vanishes at either bound, which is exactly how
+ * the allocator would move this panel for a small change.
+ * パネルは希望と制約を公開し、与えられたサイズで描画する。flex basis は配分結果そのもので、
+ * `flex-grow` / `flex-shrink` は配分器が再実行されるまでの数フレームでコンテナ変化をどう吸収するかを表す
+ * (上限で消える成長重みと、上下限のいずれかで消える縮小重み)。これは小さな変化に対して配分器が動かす量と一致する。
  */
 export const Panel = memo(
-    ({ id: providedId, defaultSize = { value: 50, unit: "percentage" }, minSize, maxSize, autoMinSize, className, style, children, order = 0, collapsible, defaultCollapsed = false, pixelAdjustPriority, flexAdjustPriority, contentOverflow = "auto" }: PanelProps) => {
-        const { direction, registerPanel, unregisterPanel, getPanel, showDebugInfo: shouldShowDebugInfo, isContainerReady, reportPanelMeasurement, containerSize } = usePanelGroup()
+    ({ id: providedId, defaultSize = { value: 50, unit: "percentage" }, minSize, maxSize, className, style, children, collapsible, defaultCollapsed = false, pixelAdjustPriority, flexAdjustPriority, contentOverflow = "auto", ...elementProps }: PanelProps) => {
+        const { direction, registerPanel, unregisterPanel, getPanel, containerSize, showDebugInfo, reportPanelMeasurement } = usePanelGroup()
         const panelRef = useRef<HTMLDivElement>(null)
         const generatedId = useId()
-        const panelId = useRef(providedId || `panel-${generatedId}`)
-
-        useEffect(() => {
-            // id prop はマウント後に変更できない (登録・DOM 属性・測定が初期 id に固定されるため)
-            // 黙殺すると気付けないため開発者向けに警告を出す
-            if (providedId && providedId !== panelId.current) {
-                logger.warn("Panel id prop change after mount is ignored.", {
-                    currentId: panelId.current,
-                    attemptedId: providedId,
-                })
-            }
-        }, [providedId])
-
-        const collapsibleConfig = useMemo(() => normalizeCollapsibleConfig(collapsible), [collapsible])
-        const isCollapsible = collapsibleConfig.collapseFromStart || collapsibleConfig.collapseFromEnd
-        const preferredCollapsedDirection: PanelCollapseDirection | null = useMemo(() => {
-            if (!isCollapsible) {
-                return null
-            }
-            if (collapsibleConfig.collapseFromStart) {
-                return "start"
-            }
-            if (collapsibleConfig.collapseFromEnd) {
-                return "end"
-            }
-            return null
-        }, [isCollapsible, collapsibleConfig.collapseFromStart, collapsibleConfig.collapseFromEnd])
-        const shouldStartCollapsed = isCollapsible && defaultCollapsed
-        const defaultSizeConfig = useMemo(() => normalizeSizeConfig(defaultSize), [defaultSize])
-        const isPixelUnit = defaultSizeConfig?.unit === "pixels"
-        const preferredPercentage = !isPixelUnit ? defaultSizeConfig?.value : undefined
-
-        // リデューサーが保持する最新パネル状態を取得
-        const currentPanel = getPanel(panelId.current)
-        // 折りたたみフラグが明示的に有効か判定
-        const isExplicitlyCollapsed = Boolean(currentPanel?.collapsed)
-        // サイズがゼロ以下で見かけ上折りたたまれているか判定
-        const hasZeroState = (currentPanel?.size ?? 0) <= 0
-        // 明示折りたたみかゼロ状態かを統合した折りたたみ判定
-        const isEffectivelyCollapsed = isExplicitlyCollapsed || hasZeroState
-
-        // observer コールバックから最新状態を参照するための ref。
-        // effect の依存に currentPanel (リデューサー更新のたびに identity が変わる) を入れると
-        // ドラッグ毎フレーム ResizeObserver / MutationObserver が再生成されるため、ref 経由で渡す。
-        const currentPanelRef = useRef(currentPanel)
-        currentPanelRef.current = currentPanel
-        const isEffectivelyCollapsedRef = useRef(isEffectivelyCollapsed)
-        isEffectivelyCollapsedRef.current = isEffectivelyCollapsed
-
-        const [pixelSize, setPixelSize] = useState(() => {
-            // 初期ピクセルサイズを defaultSize もしくは最新のリデューサー値から取得
-            if (isPixelUnit && defaultSizeConfig) {
-                return defaultSizeConfig.value
-            }
-            if (currentPanel?.size !== undefined) {
-                return currentPanel.size
-            }
-            return 0
-        })
-
-        const [percentageSize, setPercentageSize] = useState(() => {
-            // 初期パーセンテージサイズを defaultSize もしくは最新のリデューサー値から取得
-            if (!isPixelUnit && defaultSizeConfig) {
-                return defaultSizeConfig.value
-            }
-            if (currentPanel?.percentageSize !== undefined) {
-                return currentPanel.percentageSize
-            }
-            return 0
-        })
-        const pixelSizeRef = useRef(pixelSize)
-        const percentageSizeRef = useRef(percentageSize)
-        const pixelSyncTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
-        const percentageSyncTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+        const panelIdRef = useRef(providedId || `panel-${generatedId}`)
+        const panelId = panelIdRef.current
 
         useEffect(() => {
-            return () => {
-                if (pixelSyncTimerRef.current) clearTimeout(pixelSyncTimerRef.current)
-                if (percentageSyncTimerRef.current) clearTimeout(percentageSyncTimerRef.current)
+            // id はマウント後に変更できない (登録・DOM 属性・計測が初期 id に固定されるため)
+            if (providedId && providedId !== panelId) {
+                logger.warn("Panel id prop change after mount is ignored.", { currentId: panelId, attemptedId: providedId })
             }
-        }, [])
+        }, [providedId, panelId])
 
-        const commitPixelSize = useMemo(
-            () =>
-                createCommittedSetter({
-                    ref: pixelSizeRef,
-                    setState: setPixelSize,
-                    panelIdRef: panelId,
-                    label: "pixel",
-                    timerRef: pixelSyncTimerRef,
-                }),
-            [],
-        )
-        const commitPercentageSize = useMemo(
-            () =>
-                createCommittedSetter({
-                    ref: percentageSizeRef,
-                    setState: setPercentageSize,
-                    panelIdRef: panelId,
-                    label: "percentage",
-                    timerRef: percentageSyncTimerRef,
-                }),
-            [],
-        )
-
-        /**
-         * Reset both pixel and percentage caches to zero without debug logging.
-         * デバッグ出力なしでピクセルと割合のキャッシュをゼロへリセット。
-         */
-        const resetPanelSizes = useCallback(() => {
-            // 保留中の最終同期タイマーを破棄する (折りたたみ後に古い実測値が復活するのを防ぐ)
-            if (pixelSyncTimerRef.current) {
-                clearTimeout(pixelSyncTimerRef.current)
-                pixelSyncTimerRef.current = null
-            }
-            if (percentageSyncTimerRef.current) {
-                clearTimeout(percentageSyncTimerRef.current)
-                percentageSyncTimerRef.current = null
-            }
-            if (pixelSizeRef.current !== 0) {
-                pixelSizeRef.current = 0
-                setPixelSize(0)
-            }
-            if (percentageSizeRef.current !== 0) {
-                percentageSizeRef.current = 0
-                setPercentageSize(0)
-            }
-        }, [])
+        const collapseFlags = useMemo(() => normalizeCollapsibleConfig(collapsible), [collapsible])
+        const isCollapsible = collapseFlags.collapseFromStart || collapseFlags.collapseFromEnd
 
         useEffect(() => {
-            // ResizeObserver がコンテナサイズを取得するまでパネル登録を遅延
-            if (!isContainerReady) {
-                return
-            }
-
-            // ピクセル単位の場合は制約範囲内に収めた初期値を算出
-            let resolvedPixelSize = 0
-            if (isPixelUnit && defaultSizeConfig) {
-                const targetSize = defaultSizeConfig.value
-
-                // ピクセル制約があれば初期値へ反映
-                let constrainedSize = targetSize
-                if (minSize && typeof minSize === "object" && minSize.unit === "pixels") {
-                    constrainedSize = Math.max(constrainedSize, minSize.value)
-                }
-                if (maxSize && typeof maxSize === "object" && maxSize.unit === "pixels") {
-                    constrainedSize = Math.min(constrainedSize, maxSize.value)
-                }
-
-                // 制約を適用した初期ピクセルサイズ
-                resolvedPixelSize = constrainedSize
-            }
-
-            const isInitiallyCollapsed = shouldStartCollapsed
-            const initialCollapseDirection: PanelCollapseDirection | null = isInitiallyCollapsed ? preferredCollapsedDirection : null
-
             if (defaultCollapsed && !isCollapsible) {
-                logger.warn("Panel defaultCollapsed is ignored because collapsible configuration is not provided.")
+                logger.warn("Panel defaultCollapsed is ignored because collapsible configuration is not provided.", { panelId })
             }
+        }, [defaultCollapsed, isCollapsible, panelId])
 
-            // 折りたたみ前サイズと割合の初期値を算出 (折りたたみ可能な場合のみ保持)
-            const initialSizeBeforeCollapse = isCollapsible && isInitiallyCollapsed ? (isPixelUnit ? resolvedPixelSize : undefined) : undefined
-            const initialPercentageBeforeCollapse = isCollapsible ? preferredPercentage : undefined
-
-            // パネルデータを構築してリデューサーへ登録
-            const preferredPixelSize = isPixelUnit ? resolvedPixelSize : undefined
-
-            const panel = {
-                id: panelId.current,
-                size: isInitiallyCollapsed ? 0 : resolvedPixelSize,
-                percentageSize: isInitiallyCollapsed ? 0 : preferredPercentage,
-                preferredPercentageSize: preferredPercentage,
-                preferredPixelSize,
-                sizeUnit: defaultSizeConfig?.unit || "percentage",
-                originalPixelSize: isPixelUnit ? resolvedPixelSize : undefined,
+        const registration = useMemo<PanelRegistration>(() => {
+            const normalized = normalizeSizeConfig(defaultSize) ?? { value: 50, unit: "percentage" as const }
+            return {
+                id: panelId,
+                ...toPreference(normalized),
                 minSize,
                 maxSize,
-                collapseFromStart: collapsibleConfig.collapseFromStart,
-                collapseFromEnd: collapsibleConfig.collapseFromEnd,
-                collapsedByDirection: initialCollapseDirection,
-                collapsed: isInitiallyCollapsed,
-                sizeBeforeCollapse: initialSizeBeforeCollapse,
-                percentageSizeBeforeCollapse: initialPercentageBeforeCollapse,
-                preferredPercentageSizeBeforeCollapse: isCollapsible ? preferredPercentage : undefined,
-                preferredPixelSizeBeforeCollapse: isCollapsible ? preferredPixelSize : undefined,
+                ...collapseFlags,
+                collapsed: isCollapsible && defaultCollapsed,
                 pixelAdjustPriority,
                 flexAdjustPriority,
-                autoMinSize,
             }
+        }, [panelId, defaultSize, minSize, maxSize, collapseFlags, isCollapsible, defaultCollapsed, pixelAdjustPriority, flexAdjustPriority])
 
-            registerPanel(panel)
-        }, [
-            autoMinSize,
-            collapsibleConfig.collapseFromEnd,
-            collapsibleConfig.collapseFromStart,
-            defaultCollapsed,
-            defaultSizeConfig,
-            flexAdjustPriority,
-            isCollapsible,
-            isContainerReady,
-            isPixelUnit,
-            maxSize,
-            minSize,
-            pixelAdjustPriority,
-            preferredCollapsedDirection,
-            preferredPercentage,
-            registerPanel,
-            shouldStartCollapsed,
-        ])
+        useLayoutEffect(() => {
+            registerPanel(registration)
+        }, [registerPanel, registration])
 
-        useEffect(() => {
-            // アンマウント時にパネル登録と測定結果をクリア
+        useLayoutEffect(() => {
+            // 登録と同じフェーズで解除する。パッシブ効果だと、同一コミット内で同じ id が
+            // 貼り替わったとき「新しい登録 → 古い解除」の順になり、パネルが状態から消えたまま戻らない
             return () => {
-                unregisterPanel(panelId.current)
-                reportPanelMeasurement(panelId.current, null)
+                unregisterPanel(panelId)
             }
-        }, [unregisterPanel, reportPanelMeasurement])
+        }, [unregisterPanel, panelId])
 
-        const currentSize = currentPanel?.size ?? 0
+        const panel = getPanel(panelId)
+        const size = panel?.size ?? 0
+        const isCollapsed = panel?.collapsed ?? false
 
         /**
-         * Measure the DOM and sync local size caches with the latest reducer state.
-         * DOM を実測し、最新のリデューサー状態とローカルサイズキャッシュを同期する。
-         * observer から毎フレーム呼ばれるため、リデューサー状態は ref 経由で読み依存を安定させる。
+         * Measure the rendered length and report it for the debug overlay.
+         * 描画後の実寸を計測し、デバッグオーバーレイへ報告する処理。
          */
-        const updateSizes = useCallback(() => {
-            const panelElement = panelRef.current
-            if (!panelElement) return
-
-            const latestPanel = currentPanelRef.current
-            if (!latestPanel) {
+        const containerSizeRef = useRef(containerSize)
+        containerSizeRef.current = containerSize
+        const measure = useCallback(() => {
+            const element = panelRef.current
+            if (!element) {
                 return
             }
+            const pixelSize = getContainerSize(element, direction).border
+            reportPanelMeasurement(panelId, { pixelSize, percentageSize: toRoundedPercentage(pixelSize, containerSizeRef.current) })
+        }, [direction, panelId, reportPanelMeasurement])
 
-            const parentElement = panelElement.parentElement
-            if (!parentElement) return
-
-            const rect = panelElement.getBoundingClientRect()
-            const parentHorizontal = getContainerSize(parentElement, "horizontal")
-            const parentVertical = getContainerSize(parentElement, "vertical")
-
-            const currentPixelSize = direction === "horizontal" ? rect.width : rect.height
-            const parentSize = direction === "horizontal" ? parentHorizontal.inner : parentVertical.inner
-            const snapThreshold = calculateSnapThreshold(parentSize)
-
-            // 折りたたみ時はサイズをゼロに固定
-            if (isEffectivelyCollapsedRef.current) {
-                resetPanelSizes()
-                return
-            }
-
-            // 実測値がノイズ範囲と判定される場合はスキップ
-            // snapThreshold から導いた閾値より大きなサイズをリデューサーが保持しているのに、ResizeObserver が一瞬だけ極端に小さい値を返すケースがある
-            // その揺らぎを反映すると表示がチラついたり、意図せず折りたたみ判定へ繋がるのでここで検出して破棄する
-            const expectedPanelSize = latestPanel.size ?? 0
-            const noiseThreshold = Math.max(2, snapThreshold * 0.5)
-            const looksLikeNoise = expectedPanelSize > snapThreshold && currentPixelSize < noiseThreshold
-
-            if (looksLikeNoise) {
-                logger.debug("skip noisy measurement", {
-                    panelId: panelId.current,
-                    expectedPanelSize,
-                    measured: currentPixelSize,
-                    noiseThreshold,
-                })
+        useEffect(() => {
+            // 実測値はデバッグ表示専用であり、レイアウトへは戻さない。
+            // 表示していないときに監視すると、全パネルで無用な強制レイアウトを起こす
+            if (!showDebugInfo) {
+                reportPanelMeasurement(panelId, null)
                 return
             }
-
-            if (currentPixelSize > 0) {
-                // 実測ピクセル値でローカルキャッシュを更新
-                commitPixelSize(currentPixelSize)
-
-                if (parentSize > 0) {
-                    // 親コンテナ比率から割合を再計算
-                    commitPercentageSize((currentPixelSize / parentSize) * 100)
-                }
+            const element = panelRef.current
+            if (!element || typeof ResizeObserver === "undefined") {
+                measure()
                 return
             }
-
-            if (latestPanel.size !== undefined) {
-                commitPixelSize(latestPanel.size)
-            }
-            if (latestPanel.percentageSize !== undefined) {
-                // 状態が保持する割合をそのまま採用
-                commitPercentageSize(latestPanel.percentageSize)
-            } else if (latestPanel.sizeUnit === "pixels" && latestPanel.size !== undefined && parentSize > 0) {
-                // ピクセル単位パネルは親サイズから割合を求める
-                commitPercentageSize((latestPanel.size / parentSize) * 100)
-            }
-        }, [commitPercentageSize, commitPixelSize, direction, resetPanelSizes])
-
-        const hasInitialMeasurementRef = useRef(false)
-        useEffect(() => {
-            // 登録がリデューサーへ反映された直後に一度だけ DOM 実測を同期する
-            // (以降の追従は ResizeObserver / MutationObserver が担う)
-            if (!hasInitialMeasurementRef.current && currentPanel) {
-                hasInitialMeasurementRef.current = true
-                updateSizes()
-            }
-        }, [currentPanel, updateSizes])
-
-        useEffect(() => {
-            // ResizeObserver で DOM 実測を監視し状態と乖離時にローカルキャッシュを更新
-            const panelElement = panelRef.current
-            if (!panelElement) return
-
-            const resizeObserver = new ResizeObserver(() => {
-                updateSizes()
-            })
-
-            resizeObserver.observe(panelElement)
-
-            updateSizes()
-
-            // 初期計測失敗時の再試行タイマー
-            const timeoutIds: Array<ReturnType<typeof setTimeout>> = []
-
-            // PANEL_RESIZE_RETRY_INTERVALS.forEach((delay) => {
-            //     const timeoutId = setTimeout(() => {
-            //         const rect = panelElement.getBoundingClientRect()
-            //         const currentPixelSize = direction === "horizontal" ? rect.width : rect.height
-
-            //         // 初期計測失敗や割合キャッシュ未設定を検出
-            //         const shouldRetry =
-            //             currentPixelSize === 0 || (currentPanel?.sizeUnit === "pixels" && percentageSizeRef.current === 0) || (currentPanel?.sizeUnit === "pixels" && currentPanel?.originalPixelSize !== undefined && percentageSizeRef.current === 0 && currentPixelSize > 0)
-
-            //         if (shouldRetry) {
-            //             // 計測のやり直しをスケジュール
-            //             updateSizes()
-            //         }
-            //     }, delay)
-            //     timeoutIds.push(timeoutId)
-            // })
-
-            const mutationObserver = new MutationObserver(() => {
-                // 親要素の属性や子要素変化でも遅延同期を実行してレイアウト変動へ追従
-                // ただし、測定値の更新による DOM 変更では再実行しない
-                const shouldUpdate = (() => {
-                    if (!panelRef.current) return false
-                    const rect = panelRef.current.getBoundingClientRect()
-                    const measuredSize = direction === "horizontal" ? rect.width : rect.height
-                    // 実測サイズがローカルキャッシュと一致していれば更新不要
-                    if (measuredSize === pixelSizeRef.current) {
-                        return false
-                    }
-                    return true
-                })()
-
-                if (shouldUpdate) {
-                    setTimeout(updateSizes, 0)
-                }
-            })
-
-            const parentElement = panelElement.parentElement
-            if (parentElement) {
-                // 親 (グループコンテナ) 自身の属性変化と直下の子要素の増減のみを監視する。
-                // subtree 監視はパネル内容の DOM 変異のたびに全パネルで強制レイアウトを誘発するため使わない。
-                // パネル自身のサイズ変化は ResizeObserver が捕捉する。
-                mutationObserver.observe(parentElement, {
-                    childList: true,
-                    attributes: true,
-                    attributeFilter: ["style", "class"],
-                })
-            }
-
+            const observer = new ResizeObserver(measure)
+            observer.observe(element)
+            measure()
             return () => {
-                resizeObserver.disconnect()
-                mutationObserver.disconnect()
-                for (const timeoutId of timeoutIds) {
-                    clearTimeout(timeoutId)
-                }
-            }
-        }, [direction, updateSizes])
-
-        const currentPanelSize = currentPanel?.size
-        const currentPanelPercentageSize = currentPanel?.percentageSize
-        const currentPanelSizeUnit = currentPanel?.sizeUnit
-
-        useEffect(() => {
-            if (currentPanel) {
-                // リデューサーの最新サイズを反映し折りたたみ時はゼロへリセット
-                if (isEffectivelyCollapsed) {
-                    resetPanelSizes()
-                    return
-                }
-                if (currentPanelSize !== undefined) {
-                    commitPixelSize(currentPanelSize)
-                }
-
-                if (currentPanelPercentageSize !== undefined) {
-                    // リデューサーが保持する割合サイズが最新なのでそのまま適用
-                    const targetPercentage = currentPanelPercentageSize
-                    commitPercentageSize(targetPercentage)
-                } else if (currentPanelSizeUnit === "pixels" && currentPanelSize !== undefined) {
-                    // DOM 実測値と親コンテナサイズから割合サイズへの換算を試行
-                    const panelElement = panelRef.current
-                    const parentElement = panelElement?.parentElement
-                    if (panelElement && parentElement) {
-                        const { width, height } = panelElement.getBoundingClientRect()
-                        const parentWidth = parentElement.clientWidth
-                        const parentHeight = parentElement.clientHeight
-
-                        const currentPixelSize = direction === "horizontal" ? width : height
-                        const parentSize = direction === "horizontal" ? parentWidth : parentHeight
-
-                        // ピクセルと親サイズの双方が取得できた場合にのみ割合を更新
-                        if (currentPixelSize > 0 && parentSize > 0) {
-                            const calculatedPercentage = (currentPixelSize / parentSize) * 100
-                            commitPercentageSize(calculatedPercentage)
-                        }
-                    }
-                }
-            }
-        }, [commitPercentageSize, commitPixelSize, currentPanel, currentPanelPercentageSize, currentPanelSize, currentPanelSizeUnit, direction, isEffectivelyCollapsed, resetPanelSizes])
-
-        useEffect(() => {
-            // 最新測定値をコンテキスト経由でグループへ報告しオーバーレイ等を更新
-            reportPanelMeasurement(panelId.current, {
-                pixelSize,
-                percentageSize,
-            })
-        }, [reportPanelMeasurement, pixelSize, percentageSize])
-
-        /**
-         * Compute CSS flex-basis value based on panel size unit and collapse state.
-         * パネルサイズユニットと折りたたみ状態に基づいて CSS flex-basis 値を計算。
-         */
-        const getFlexBasis = () => {
-            if (isEffectivelyCollapsed) {
-                return "0px"
-            }
-            if (currentPanel?.originalPixelSize !== undefined) {
-                return `${currentSize}px`
-            }
-
-            if (currentPanel?.percentageSize !== undefined) {
-                return `${currentPanel.percentageSize}%`
-            }
-
-            return `${currentSize}px`
-        }
-
-        const computedFlexShrink = currentPanel?.sizeUnit === "percentage" && !currentPanel?.collapsed ? 1 : 0
-
-        // パネル自身の Flex 振る舞いと最小サイズを制御するベーススタイル
-        const panelStyle: CSSProperties = {
-            flexBasis: getFlexBasis(),
-            flexGrow: 0,
-            flexShrink: computedFlexShrink,
-            overflow: "hidden",
-            position: "relative",
-            boxSizing: "border-box",
-            minHeight: "0px",
-            minWidth: "0px",
-            ...style,
-        }
-
-        if (direction === "horizontal") {
-            panelStyle.height = "100%"
-            // 横並びではコンテンツに引きずられずに縮むため minWidth を確実に 0 にする
-            panelStyle.minWidth = 0
-        } else {
-            panelStyle.width = "100%"
-            // 縦並びでは高さ縮小時にコンテンツの min-height を無視するため 0 を設定
-            panelStyle.minHeight = 0
-        }
-
-        if (isEffectivelyCollapsed) {
-            // 折りたたみ時にパネルをレイアウトから外しユーザー操作も遮断するためのスタイル
-            if (direction === "horizontal") {
-                panelStyle.width = "0px"
-                panelStyle.minWidth = "0px"
-            } else {
-                panelStyle.height = "0px"
-                panelStyle.minHeight = "0px"
-            }
-            panelStyle.flexGrow = 0
-            panelStyle.flexShrink = 0
-            panelStyle.pointerEvents = "none"
-            panelStyle.visibility = "hidden"
-            if (isExplicitlyCollapsed) {
-                panelStyle.display = "none"
-            }
-        }
-
-        const containerAxisSize = direction === "horizontal" ? containerSize.width : containerSize.height
+                observer.disconnect()
+                reportPanelMeasurement(panelId, null)
+            }
+        }, [showDebugInfo, measure, panelId, reportPanelMeasurement])
+
+        const panelStyle = useMemo<CSSProperties>(() => {
+            // 見た目に関わる既定値は利用者が上書きできる。
+            // `isolation` はパネル内部の z-index がハンドルより手前に出ないようにするための既定値だが、
+            // パネルの外まで覆う overlay (position: fixed の最大化表示など) を置きたい利用者は
+            // `isolation: "auto"` で降りられる (その場合、内容がハンドルを覆いうることを引き受ける)
+            const presentation: CSSProperties = { overflow: "hidden", isolation: "isolate" }
+            const collapsed: CSSProperties = isCollapsed ? { ...(direction === "horizontal" ? { width: "0px" } : { height: "0px" }), pointerEvents: "none", visibility: "hidden", display: "none" } : {}
+
+            return {
+                ...presentation,
+                ...style,
+                // ここから下はレイアウトの前提そのもの。利用者のスタイルやクラスで変わると配分結果と
+                // 描画が一致しなくなるため、最後に適用して上書きを受け付けない:
+                // flex の三つ組は配分器が決めた長さそのもの、margin はパネルの合計に含まれない隙間を作り、
+                // order は DOM 順と視覚順をずらす
+                ...resolvePanelFlex({ size, panel, registration, containerSize, isCollapsed }),
+                order: 0,
+                margin: 0,
+                // 内容を通常フローで内容ボックスいっぱいに伸ばすための入れ物 (パディングを効かせる唯一の形)
+                display: "flex",
+                flexDirection: "column",
+                position: "relative",
+                boxSizing: "border-box",
+                // 主軸の縮小をコンテンツの固有幅に妨げられないようにし、
+                // 上限側のクランプ (max-w-* のようなユーティリティクラスを含む) も受け付けない。
+                // 配分器が配った長さより短く描くと、状態と描画が食い違ったままハンドルが動かなくなる
+                minWidth: 0,
+                minHeight: 0,
+                maxWidth: "none",
+                maxHeight: "none",
+                ...(direction === "horizontal" ? { height: "100%" } : { width: "100%" }),
+                ...collapsed,
+            }
+        }, [size, direction, isCollapsed, panel, registration, containerSize, style])
 
-        // 実際の子要素をパネル内に固定しスクロールも許可するためのラッパースタイル
         const contentWrapperStyle = useMemo<CSSProperties>(
             () => ({
-                position: "absolute",
-                inset: "0px",
+                // 内容は通常フローの伸縮子として置く。絶対配置にするとパディングボックスを基準にしてしまい、
+                // 利用者がパネルへ与えたパディングが何の効果も持たなくなる
+                flex: "1 1 auto",
+                position: "relative",
                 overflow: contentOverflow,
                 display: "flex",
                 flexDirection: "column",
-                width: "100%",
-                height: "100%",
                 minWidth: "0px",
                 minHeight: "0px",
             }),
@@ -614,21 +277,20 @@ export const Panel = memo(
 
         return (
             <div
+                {...elementProps}
                 ref={panelRef}
                 className={twMerge("panel", className)}
                 style={panelStyle}
-                data-panel-id={panelId.current}
-                data-panel-size={currentSize}
-                data-panel-size-unit={currentPanel?.sizeUnit || "percentage"}
-                data-panel-pixel-size={currentPanel?.sizeUnit === "pixels" ? currentPanel?.originalPixelSize : null}
-                data-panel-order={order}
+                data-panel-id={panelId}
+                data-panel-size={size}
+                data-panel-size-unit={panel?.sizeUnit ?? "percentage"}
                 data-panel-collapsible={isCollapsible}
-                data-panel-collapse-start={collapsibleConfig.collapseFromStart}
-                data-panel-collapse-end={collapsibleConfig.collapseFromEnd}
-                data-panel-collapsed={currentPanel?.collapsed}
-                aria-hidden={isEffectivelyCollapsed}>
+                data-panel-collapse-start={collapseFlags.collapseFromStart}
+                data-panel-collapse-end={collapseFlags.collapseFromEnd}
+                data-panel-collapsed={isCollapsed}
+                aria-hidden={isCollapsed}>
                 <div style={contentWrapperStyle}>{children}</div>
-                {shouldShowDebugInfo && <PanelDebugInfo panel={currentPanel} measuredPixelSize={pixelSize} measuredPercentageSize={percentageSize} containerAxisSize={containerAxisSize} direction={direction} />}
+                {showDebugInfo && <PanelDebugInfo panel={panel} containerAxisSize={containerSize} direction={direction} />}
             </div>
         )
     },