@aiquants/resize-panels 1.8.1 → 2.0.0

package/src/PanelResizeHandle.tsx

@@ -1,12 +1,23 @@
 /**
  * @file PanelResizeHandle component for custom resizable panels
  * カスタムリサイズ可能パネルのための PanelResizeHandle コンポーネント
+ *
+ * The handle does not compute where the boundary is. It renders a zero-length flex item — the anchor —
+ * between its two panels, so flex layout itself places it exactly on the boundary, and the interactive
+ * button is drawn symmetrically around that anchor. Whatever the panels do (a container resize between two
+ * React renders, padding on the group, right-to-left text, a vertical axis), the handle is on the boundary
+ * because it *is* the boundary.
+ * ハンドルは境界位置を計算しない。2 枚のパネルの間に長さ 0 のフレックスアイテム (アンカー) を描画するため、
+ * フレックスレイアウト自身がそれを境界へ配置し、操作用ボタンはそのアンカーを中心に対称に描かれる。
+ * コンテナのリサイズ・グループのパディング・RTL・垂直方向のいずれであっても、ハンドルは境界そのものなので必ず一致する。
  */
 
 import { type CSSProperties, memo, useCallback, useEffect, useId, useMemo, useRef, useState } from "react"
 import { twMerge } from "tailwind-merge"
+import { resolvePanelBounds } from "./allocateLayout"
 import { usePanelGroup } from "./context"
 import {
+    PANEL_ALLOCATION_EPSILON,
     PANEL_COLLAPSE_THRESHOLD_MAX,
     PANEL_COLLAPSE_THRESHOLD_RATIO,
     PANEL_EXPAND_THRESHOLD_MAX,
@@ -14,297 +25,343 @@ import {
     PANEL_HANDLE_DRAG_THROTTLE_MS,
     PANEL_HANDLE_THICKNESS,
     PANEL_HANDLE_VISIBILITY_THRESHOLD,
+    PANEL_INDICATOR_BAR_LENGTH_HORIZONTAL,
+    PANEL_INDICATOR_BAR_LENGTH_VERTICAL,
+    PANEL_INDICATOR_BAR_THICKNESS,
+    PANEL_INDICATOR_LENGTH_HORIZONTAL,
+    PANEL_INDICATOR_LENGTH_VERTICAL,
+    PANEL_INDICATOR_THICKNESS,
     PANEL_KEYBOARD_RESIZE_STEP,
     PANEL_VISIBLE_INDICATOR_SPACING,
+    type PanelLayoutData,
     type PanelResizeHandleProps,
     type ResizeHandleLayoutData,
 } from "./types"
-import { calculateSnapThreshold, getConstraintInPixels, getContainerSize } from "./utils"
+import { calculateSnapThreshold, findOwningGroup, getGroupLayoutElements, getVisualScale } from "./utils"
+
+/**
+ * Styles that remove the handle and its anchor from layout and interaction.
+ * ハンドルとアンカーをレイアウトと操作の両方から外すスタイル。
+ */
+const HIDDEN_HANDLE_STYLE: CSSProperties = {
+    display: "none",
+    pointerEvents: "none",
+    visibility: "hidden",
+}
+
+/**
+ * Style that collapses the visual indicator.
+ * 視覚インジケーターを非表示にするスタイル。
+ */
+const HIDDEN_INDICATOR_STYLE: CSSProperties = {
+    display: "none",
+}
+
+/**
+ * Sanitize an optional dimension to ensure a positive finite number.
+ * オプション寸法を正の有限数値へ正規化する処理。
+ */
+const sanitizeDimension = (value: unknown, defaultValue: number): number => {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        return defaultValue
+    }
+    return value
+}
+
+/**
+ * Ensure a numeric spacing value is an even integer for symmetric pixel alignment.
+ * ピクセル配置の対称性を担保するため数値を偶数整数に整流する処理。
+ */
+const ensureEven = (value: number): number => {
+    const rounded = Math.round(value)
+    return rounded % 2 === 0 ? rounded : rounded + 1
+}
+
+/**
+ * Report whether an element is laid out right-to-left at this moment.
+ * その時点で要素が右から左へレイアウトされているかの判定。
+ *
+ * The direction is read at the start of each gesture instead of being cached, so a language switch takes
+ * effect without remounting the group.
+ * 方向はキャッシュせずジェスチャー開始のたびに読む。言語切替がグループの再マウント無しで反映されるようにするため。
+ */
+const isRightToLeft = (element: HTMLElement | null): boolean => {
+    if (!element || typeof window === "undefined") {
+        return false
+    }
+    return window.getComputedStyle(element).direction === "rtl"
+}
+
+/**
+ * Travel range of the boundary a handle sits on, in pixels from the start of the panel pair.
+ * ハンドルが載る境界の可動域 (パネル対の start からのピクセル距離)。
+ */
+type SeparatorBounds = {
+    /** Where the boundary sits now / 境界の現在位置 */
+    position: number
+    /** Lowest position this handle can reach, collapsing included / このハンドルが到達できる最小位置 (折りたたみを含む) */
+    lower: number
+    /** Highest position this handle can reach, collapsing included / このハンドルが到達できる最大位置 (折りたたみを含む) */
+    upper: number
+    /** Lowest position a plain resize can reach / 単なるリサイズで到達できる最小位置 */
+    resizeLower: number
+    /** Highest position a plain resize can reach / 単なるリサイズで到達できる最大位置 */
+    resizeUpper: number
+}
+
+/**
+ * Resolve where the boundary between two panels is and how far it can travel.
+ * 2 枚のパネルの境界が今どこにあり、どこまで動けるかを解決する処理。
+ *
+ * The range is what **this** handle can reach, not what the pair could reach through any means. Collapsing
+ * is a position the boundary can hold, so it widens the range — but only in the direction this handle is
+ * allowed to collapse, and a panel already collapsed can only be reopened from the side it was closed from
+ * (`EXPAND_PANEL` rejects any other direction). A handle that can reach nothing therefore reports a range of
+ * zero width instead of advertising travel it would swallow the key press for.
+ * 公開するのは **このハンドル** が到達できる範囲であり、対が何らかの手段で到達しうる範囲ではない。
+ * 折りたたみは境界が取りうる位置なので範囲を広げるが、広がるのはこのハンドルが折りたためる向きだけで、
+ * 既に折りたたまれたパネルは閉じたのと同じ向きからしか開けない (`EXPAND_PANEL` が他の向きを拒否する)。
+ * どこへも動けないハンドルは、幅 0 の範囲を報告する (動けると偽って キー入力だけ飲み込まないために)。
+ *
+ * @param startPanel - Panel before the boundary / 境界より手前のパネル
+ * @param endPanel - Panel after the boundary / 境界より奥のパネル
+ * @param containerSize - Container content-box length / コンテナ内容領域長
+ * @returns Boundary position and its travel range, or undefined when the pair has no length / 境界位置と可動域、対に長さが無ければ undefined
+ */
+const resolveSeparatorBounds = (startPanel: PanelLayoutData, endPanel: PanelLayoutData, containerSize: number): SeparatorBounds | undefined => {
+    const startSize = startPanel.collapsed ? 0 : startPanel.size
+    const endSize = endPanel.collapsed ? 0 : endPanel.size
+    const total = startSize + endSize
+    if (total <= 0) {
+        return undefined
+    }
+    const startBounds = resolvePanelBounds(startPanel, containerSize)
+    const endBounds = resolvePanelBounds(endPanel, containerSize)
+    // 単なるリサイズで届く範囲は、双方の制約が同時に効いた区間 (reducer の RESIZE_PANELS と同じ式)
+    const resizeLower = Math.max(startBounds.min, total - endBounds.max)
+    const resizeUpper = Math.max(resizeLower, Math.min(startBounds.max, total - endBounds.min))
+
+    if (startPanel.collapsed) {
+        // 閉じた向きと同じ向きからしか開けない。手前のパネルはこのハンドルから見て "end" 側で閉じている
+        const canReopen = startPanel.collapsedByDirection === "end"
+        return { position: 0, lower: 0, upper: canReopen ? Math.max(0, resizeUpper) : 0, resizeLower, resizeUpper }
+    }
+    if (endPanel.collapsed) {
+        const canReopen = endPanel.collapsedByDirection === "start"
+        return { position: total, lower: canReopen ? Math.min(total, resizeLower) : total, upper: total, resizeLower, resizeUpper }
+    }
+
+    // 折りたたみは境界が対の端へ到達した状態そのものなので、許される向きだけ範囲を端まで広げる
+    const lower = Math.min(startSize, startPanel.collapseFromEnd ? 0 : resizeLower)
+    const upper = Math.max(startSize, lower, endPanel.collapseFromStart ? total : resizeUpper)
+    return { position: startSize, lower, upper, resizeLower, resizeUpper }
+}
 
 /**
  * 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()
+export const PanelResizeHandle = memo((props: PanelResizeHandleProps) => {
+    const { id, disabled = false, className, style, children, onDragging, thickness, indicator = true, indicatorThickness, indicatorLength, indicatorBarThickness, indicatorBarLength, title, onPointerDown, onKeyDown, ...elementProps } = props
+    const { direction, resizePanels, getPanel, collapsePanel, expandPanel, panels, layoutOrderKey, reportHandleMeasurement, containerSize, layoutConstraintViolation } = usePanelGroup()
+
     const [isDragging, setIsDragging] = useState(false)
-    const handleRef = useRef<HTMLButtonElement>(null)
-    const containerRef = useRef<HTMLElement | null>(null)
+    const [adjacentPanelIds, setAdjacentPanelIds] = useState<{ start: string | null; end: string | null }>({ start: null, end: null })
 
-    const leftPanelId = useRef<string>("")
-    const rightPanelId = useRef<string>("")
+    const anchorRef = useRef<HTMLDivElement>(null)
+    const handleRef = useRef<HTMLButtonElement>(null)
+    // ドラッグ中の move ハンドラーは開始時のクロージャで動き続けるため、最新の状態は ref 経由で読む。
+    // これが無いと、同じジェスチャーの中で折りたたんだパネルを引き戻しても展開できない
+    const layoutRef = useRef({ getPanel, containerSize })
+    layoutRef.current = { getPanel, containerSize }
+    const startPanelIdRef = useRef("")
+    const endPanelIdRef = useRef("")
     // 進行中ドラッグの後始末関数。アンマウント時や次のドラッグ開始時の残留リスナー掃除に使う
     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 lastMeasurementRef = useRef<ResizeHandleLayoutData | null>(null)
+
     const generatedId = useId()
     const handleIdRef = useRef(id ?? `resize-handle-${generatedId}`)
-    const lastHandleMeasurementRef = useRef<ResizeHandleLayoutData | null>(null)
     const resolvedHandleId = id ?? handleIdRef.current
+    const isHorizontal = direction === "horizontal"
     const hasLayoutConstraintViolation = Boolean(layoutConstraintViolation)
     const isHandleDisabled = disabled || hasLayoutConstraintViolation
 
     /**
-     * Detect the panels adjacent to this handle by scanning sibling DOM elements.
-     * DOM の兄弟要素を走査してこのハンドルに隣接する左右のパネルを検出する。
+     * Detect the panels this handle sits between by scanning its siblings in the DOM.
+     * 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 anchor = anchorRef.current
+        // 中間要素が挟まると親はグループではないため、所有グループを辿って解決する
+        const group = findOwningGroup(anchor)
+        if (!(anchor && group)) {
+            return
         }
-        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
+        const elements = getGroupLayoutElements(group)
+        const index = elements.indexOf(anchor)
+        let startId = ""
+        let endId = ""
+        for (let cursor = index - 1; cursor >= 0; cursor -= 1) {
+            const candidate = elements[cursor].dataset.panelId
+            if (candidate !== undefined) {
+                startId = candidate
                 break
             }
         }
-
-        // ハンドルより後方の要素を走査して右パネルを特定
-        for (let i = index + 1; i < childrenElements.length; i += 1) {
-            const element = childrenElements[i] as HTMLElement
-            if (element.dataset.panelId) {
-                rightPanelElement = element
+        for (let cursor = index + 1; cursor < elements.length; cursor += 1) {
+            const candidate = elements[cursor].dataset.panelId
+            if (candidate !== undefined) {
+                endId = candidate
                 break
             }
         }
 
-        const nextLeftId = leftPanelElement?.dataset.panelId || ""
-        const nextRightId = rightPanelElement?.dataset.panelId || ""
-
-        // 検出結果が前回と同じなら state 更新を省略する
-        if (nextLeftId === leftPanelId.current && nextRightId === rightPanelId.current) {
+        if (startId === startPanelIdRef.current && endId === endPanelIdRef.current) {
             return
         }
-
-        leftPanelId.current = nextLeftId
-        rightPanelId.current = nextRightId
-
-        setAdjacentPanelIds({
-            left: nextLeftId || null,
-            right: nextRightId || null,
-        })
+        startPanelIdRef.current = startId
+        endPanelIdRef.current = endId
+        setAdjacentPanelIds({ start: startId || null, end: endId || null })
     }, [])
 
-    // パネル構成 (ID 列) の変化を検知するためのキー。ドラッグ中のサイズ更新では変化しない
-    const panelIdsKey = useMemo(() => panels.map((panel) => panel.id).join("|"), [panels])
-
     useEffect(() => {
-        // マウント時とパネルの増減・並び替え時に隣接パネルを再検出する
-        // (マウント時のみだと兄弟 Panel の条件付き追加/削除でハンドルが古い ID を掴んだままになる)
+        // マウント時と、グループの DOM 順が変わるたびに隣接パネルを再検出する。
+        // パネルの id 列だけを見ていると、ハンドル自身が別の境界へ移った並べ替えを取りこぼし、
+        // 見た目とは違う 2 枚を掴み続ける
         detectAdjacentPanels()
-    }, [detectAdjacentPanels, panelIdsKey])
+    }, [detectAdjacentPanels, layoutOrderKey])
 
     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 () => {
+            // ドラッグ中にアンマウントされた場合も document リスナーとドラッグ状態を確実に破棄する
             dragCleanupRef.current?.()
         }
     }, [])
 
     /**
-     * Initiates a resize drag interaction when the handle receives a pointer down event.
+     * Start a resize drag when the handle receives a pointer down event.
      * リサイズハンドルがポインタダウンを受けた際にドラッグ操作を開始する処理。
      */
     const handlePointerDown = useCallback(
         (event: React.PointerEvent<HTMLButtonElement>) => {
-            if (isHandleDisabled || !containerRef.current) return
-
+            if (isHandleDisabled) {
+                return
+            }
             // 既にドラッグ中の場合は 2 本目のポインタで新たなドラッグを開始しない
-            if (dragCleanupRef.current) return
+            if (dragCleanupRef.current) {
+                return
+            }
+            // 主ボタン以外は掴まない。右ボタンで掴むと、コンテキストメニューを開きながらレイアウトが動く
+            // (タッチ・ペンの pointerdown も主ボタンとして 0 が届く)
+            if (event.button !== 0) {
+                return
+            }
+
+            const startPanel = getPanel(startPanelIdRef.current)
+            const endPanel = getPanel(endPanelIdRef.current)
+            if (!(startPanel && endPanel)) {
+                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)
+            const startId = startPanelIdRef.current
+            const endId = endPanelIdRef.current
+            const initialStartSize = startPanel.size
+            const initialTotal = startPanel.size + endPanel.size
+            const origin = isHorizontal ? event.clientX : event.clientY
+            const group = findOwningGroup(anchorRef.current)
+            // RTL では DOM 順 (論理順) と視覚順が反転するため、水平ドラッグの変位符号を反転する
+            const directionSign = isHorizontal && isRightToLeft(group) ? -1 : 1
+            // ポインタ座標は視覚ピクセル、配分器が扱うのはレイアウトピクセル。
+            // 変形された祖先の下で換算を省くと、掴んだ点がカーソルから滑り出していく
+            const visualScale = group ? getVisualScale(group, direction) : 1
 
-            // このドラッグを開始したポインタだけを追跡する (2 本目のタッチ等の混入を防ぐ)
             const dragPointerId = event.pointerId
             const captureTarget = event.currentTarget
+            // 追従は document の pointermove / pointerup で行うため、キャプチャは無くても成立する。
+            // 実装しない環境 (jsdom など) で例外を投げると、利用者側のテストがドラッグを検証できなくなる
+            captureTarget.setPointerCapture?.(dragPointerId)
 
-            // 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
+            setIsDragging(true)
+            onDragging?.(true)
 
-                moveEvent.preventDefault()
-                moveEvent.stopPropagation()
+            let lastUpdateTime = 0
+            let throttledMove: PointerEvent | null = null
 
-                // スロットル処理: 頻繁な更新を抑制して計算負荷を下げる
-                const now = performance.now()
-                if (now - lastUpdateTime < throttleMs) return
-                lastUpdateTime = now
+            const applyMove = (moveEvent: PointerEvent) => {
+                const delta = (((isHorizontal ? moveEvent.clientX : moveEvent.clientY) - origin) * directionSign) / visualScale
+                const nextStartSize = initialStartSize + delta
+                const nextEndSize = initialTotal - nextStartSize
 
-                // ドラッグ開始位置からのピクセル変位を計算 (RTL の水平ドラッグは符号を反転)
-                const rawPixelDelta = direction === "horizontal" ? moveEvent.clientX - startPosition.x : moveEvent.clientY - startPosition.y
-                const pixelDelta = isRtlDrag ? -rawPixelDelta : rawPixelDelta
-                // 差分がゼロのときは状態変化がなく後続処理が無駄になるため中断
-                if (pixelDelta === 0) {
+                const layout = layoutRef.current
+                const currentStart = layout.getPanel(startId)
+                const currentEnd = layout.getPanel(endId)
+                if (!(currentStart && currentEnd)) {
                     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 collapseThreshold = Math.min(layout.containerSize * PANEL_COLLAPSE_THRESHOLD_RATIO, PANEL_COLLAPSE_THRESHOLD_MAX)
+                const expandThreshold = Math.min(layout.containerSize * PANEL_EXPAND_THRESHOLD_RATIO, PANEL_EXPAND_THRESHOLD_MAX)
 
-                    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 (currentEnd.collapsed) {
+                    if (nextEndSize > expandThreshold) {
+                        expandPanel(endId, "start", nextEndSize)
                     }
-
-                    // 右パネルが折りたたまれており、新しいサイズが展開閾値を超えた場合は展開
-                    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
+                    return
+                }
+                if (currentStart.collapsed) {
+                    if (nextStartSize > expandThreshold) {
+                        expandPanel(startId, "end", nextStartSize)
                     }
+                    return
+                }
+                if (currentEnd.collapseFromStart && nextEndSize <= collapseThreshold) {
+                    collapsePanel(endId, "start")
+                    return
+                }
+                if (currentStart.collapseFromEnd && nextStartSize <= collapseThreshold) {
+                    collapsePanel(startId, "end")
+                    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
-                        }
-                    }
+                resizePanels(startId, endId, nextStartSize)
+            }
 
-                    // いずれかのパネルが折りたたまれている場合はリサイズ処理を中断
-                    if (updatedLeftPanel.collapsed || updatedRightPanel.collapsed) {
-                        return
-                    }
+            const handlePointerMove = (moveEvent: PointerEvent) => {
+                // 別ポインタのイベントはドラッグ計算に混入させない
+                if (moveEvent.pointerId !== dragPointerId) {
+                    return
+                }
+                moveEvent.preventDefault()
+                moveEvent.stopPropagation()
 
-                    // 通常のリサイズ処理を実行して隣接パネルのサイズを更新
-                    resizePanels(leftPanelId.current, rightPanelId.current, newLeftSizeInPixels, newRightSizeInPixels)
+                const now = performance.now()
+                if (now - lastUpdateTime < PANEL_HANDLE_DRAG_THROTTLE_MS) {
+                    // 間引いた移動は捨てずに保持する。離上時に反映しないと、指を離した位置と確定した境界がずれる
+                    throttledMove = moveEvent
+                    return
                 }
+                lastUpdateTime = now
+                throttledMove = null
+                applyMove(moveEvent)
             }
 
             /**
              * Tear down the active drag: remove listeners, release capture, and reset state.
-             * 進行中ドラッグの後始末: リスナー除去・キャプチャ解放・状態リセットを一括で行う。
+             * 進行中ドラッグの後始末 (リスナー除去・キャプチャ解放・状態リセット)。
              * pointerup / pointercancel / lostpointercapture / アンマウントのどこから呼ばれても一度だけ実行される。
              */
             let dragActive = true
             const stopDragging = () => {
-                if (!dragActive) return
+                if (!dragActive) {
+                    return
+                }
                 dragActive = false
                 dragCleanupRef.current = null
-
                 setIsDragging(false)
                 onDragging?.(false)
 
@@ -319,20 +376,27 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
 
             const handlePointerUp = (upEvent: PointerEvent) => {
                 // 別ポインタの離上ではドラッグを終了しない
-                if (upEvent.pointerId !== dragPointerId) return
+                if (upEvent.pointerId !== dragPointerId) {
+                    return
+                }
+                if (throttledMove) {
+                    const pending = throttledMove
+                    throttledMove = null
+                    applyMove(pending)
+                }
                 stopDragging()
             }
-
             const handlePointerCancel = (cancelEvent: PointerEvent) => {
                 // OS 割込み (タッチジェスチャ奪取等) でキャンセルされた場合もドラッグ状態を残さない
-                if (cancelEvent.pointerId !== dragPointerId) return
-                stopDragging()
+                if (cancelEvent.pointerId === dragPointerId) {
+                    stopDragging()
+                }
             }
-
             const handleLostPointerCapture = (lostEvent: PointerEvent) => {
                 // キャプチャ喪失 (要素の DOM 離脱等) 時のフォールバック終了処理
-                if (lostEvent.pointerId !== dragPointerId) return
-                stopDragging()
+                if (lostEvent.pointerId === dragPointerId) {
+                    stopDragging()
+                }
             }
 
             document.addEventListener("pointermove", handlePointerMove)
@@ -341,169 +405,103 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
             captureTarget.addEventListener("lostpointercapture", handleLostPointerCapture)
             dragCleanupRef.current = stopDragging
         },
-        [isHandleDisabled, direction, resizePanels, getPanel, collapsePanel, expandPanel, onDragging],
+        [isHandleDisabled, isHorizontal, direction, getPanel, resizePanels, collapsePanel, expandPanel, onDragging],
     )
 
     /**
      * Resize adjacent panels with arrow keys for keyboard accessibility.
      * キーボード (矢印キー) で隣接パネルをリサイズするアクセシビリティ対応。
-     * Shift 併用で 5 倍のステップ幅を適用する。
      */
     const handleKeyDown = useCallback(
         (event: React.KeyboardEvent<HTMLButtonElement>) => {
-            if (isHandleDisabled) return
+            if (isHandleDisabled) {
+                return
+            }
+            const decreaseKey = isHorizontal ? "ArrowLeft" : "ArrowUp"
+            const increaseKey = isHorizontal ? "ArrowRight" : "ArrowDown"
+            if (event.key !== decreaseKey && event.key !== increaseKey) {
+                return
+            }
 
-            const isHorizontalDirection = direction === "horizontal"
-            const decreaseKey = isHorizontalDirection ? "ArrowLeft" : "ArrowUp"
-            const increaseKey = isHorizontalDirection ? "ArrowRight" : "ArrowDown"
-            if (event.key !== decreaseKey && event.key !== increaseKey) return
+            const startId = startPanelIdRef.current
+            const endId = endPanelIdRef.current
+            const startPanel = getPanel(startId)
+            const endPanel = getPanel(endId)
+            if (!(startPanel && endPanel)) {
+                return
+            }
+            const bounds = resolveSeparatorBounds(startPanel, endPanel, containerSize)
+            // どこへも動けないハンドルはキーを飲み込まない。飲み込むと、何も起きないまま
+            // ページのスクロールまで止まる「効かないキー」になる
+            if (!bounds || bounds.upper - bounds.lower <= PANEL_ALLOCATION_EPSILON) {
+                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
+            const step = event.shiftKey ? PANEL_KEYBOARD_RESIZE_STEP * 5 : PANEL_KEYBOARD_RESIZE_STEP
+            // RTL では DOM 順 (論理順) と視覚順が反転するため符号を反転する
+            const directionSign = isHorizontal && isRightToLeft(findOwningGroup(anchorRef.current)) ? -1 : 1
+            const delta = (event.key === increaseKey ? step : -step) * directionSign
+
+            // 折りたたまれたパネルは、境界を自分の方へ押し返すキーで開く。
+            // 開けないと、キーボードだけを使う利用者にとって折りたたみは戻れない行き止まりになる
+            if (startPanel.collapsed) {
+                if (delta > 0) {
+                    // 目標長を渡さずに開く: 折りたたむ前の長さへ戻すのが「開く」の意味であり、
+                    // 1 ステップ分だけ開いても最小値へ切り上げられるだけで何も伝わらない
+                    expandPanel(startId, "end")
+                }
+                return
             }
-            for (let index = 0; index < panels.length; index += 1) {
-                if (panels[index].id === panelId) {
-                    return index
+            if (endPanel.collapsed) {
+                if (delta < 0) {
+                    expandPanel(endId, "start")
                 }
+                return
             }
-            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
+            // リサイズで届く端まで来たパネルをさらに押すキーは、ドラッグで端まで引いたときと同じく折りたたみになる。
+            // 判定に使うのはパネル自身の最小値ではなく対の可動域の端である。隣の上限が先に効く構成では、
+            // パネルは自分の最小値へ決して到達できず、キーボードからは永久に折りたためなくなる
+            if (delta < 0 && startPanel.collapseFromEnd && bounds.position <= bounds.resizeLower + PANEL_ALLOCATION_EPSILON) {
+                collapsePanel(startId, "end")
+                return
             }
-            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
+            if (delta > 0 && endPanel.collapseFromStart && bounds.position >= bounds.resizeUpper - PANEL_ALLOCATION_EPSILON) {
+                collapsePanel(endId, "start")
+                return
             }
-            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])
+            resizePanels(startId, endId, startPanel.size + delta)
+        },
+        [isHandleDisabled, isHorizontal, getPanel, resizePanels, collapsePanel, expandPanel, containerSize],
+    )
 
-    const overlayBaseStyle = useMemo<CSSProperties>(() => {
-        const base: CSSProperties = {
-            position: "absolute",
-            zIndex: 20,
-            touchAction: "none",
-        }
+    const indicatorConfig = typeof indicator === "object" && indicator !== null ? indicator : undefined
+    const isIndicatorExplicitlyHidden = indicator === false || indicatorConfig?.visible === false
 
-        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%"
-        }
+    const resolvedThickness = Math.max(1, sanitizeDimension(thickness, PANEL_HANDLE_THICKNESS))
+    const defaultIndicatorLength = isHorizontal ? PANEL_INDICATOR_LENGTH_HORIZONTAL : PANEL_INDICATOR_LENGTH_VERTICAL
+    const defaultBarLength = isHorizontal ? PANEL_INDICATOR_BAR_LENGTH_HORIZONTAL : PANEL_INDICATOR_BAR_LENGTH_VERTICAL
 
-        return base
-    }, [clampedOffset, isHorizontal, isRtl, containerLength])
+    // 幾何学的内包不変条件: 内部バー寸法がインジケーター外枠およびハンドル操作領域を超えないようクランプ
+    const resolvedIndicatorThickness = Math.min(resolvedThickness, Math.max(1, sanitizeDimension(indicatorThickness ?? indicatorConfig?.thickness, PANEL_INDICATOR_THICKNESS)))
+    const resolvedIndicatorLength = Math.max(1, sanitizeDimension(indicatorLength ?? indicatorConfig?.length, defaultIndicatorLength))
+    const resolvedBarThickness = Math.min(resolvedIndicatorThickness, Math.max(1, sanitizeDimension(indicatorBarThickness ?? indicatorConfig?.barThickness, PANEL_INDICATOR_BAR_THICKNESS)))
+    const resolvedBarLength = Math.min(resolvedIndicatorLength, Math.max(1, sanitizeDimension(indicatorBarLength ?? indicatorConfig?.barLength, defaultBarLength)))
 
     const indicatorGrouping = useMemo(() => {
-        const snapThreshold = calculateSnapThreshold(containerLength)
-        // パネルが実質的に折りたたまれているか判定するヘルパー関数
+        // 隣接パネルが閉じていると複数のハンドルが同じ境界へ重なるため、その重なり具合を数える
+        const snapThreshold = calculateSnapThreshold(containerSize)
         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
+            return target.collapsed || 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)) {
@@ -514,205 +512,247 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
             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
+        const startIndex = panels.findIndex((panel) => panel.id === adjacentPanelIds.start)
+        const endIndex = panels.findIndex((panel) => panel.id === adjacentPanelIds.end)
+        const startCollapsedCount = startIndex >= 0 ? countCollapsed(startIndex, -1) : 0
+        const endCollapsedCount = endIndex >= 0 ? countCollapsed(endIndex, 1) : 0
 
-        return {
-            groupSize,
-            overlapIndex,
-        }
-    }, [adjacentIndices.left, adjacentIndices.right, panels, containerLength])
+        return { groupSize: startCollapsedCount + endCollapsedCount + 1, overlapIndex: startCollapsedCount }
+    }, [adjacentPanelIds.start, adjacentPanelIds.end, panels, containerSize])
 
     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
+        // 折りたたみ重なり時の視覚重複を防ぐため端点以外の重複ハンドルを不可視化
+        return indicatorGrouping.overlapIndex > 0 && indicatorGrouping.overlapIndex < indicatorGrouping.groupSize - 1
     }, [indicatorGrouping, hasLayoutConstraintViolation])
 
     const indicatorOffset = useMemo(() => {
-        // ハンドルが非表示の場合またはグループサイズが 1 以下の場合はオフセット不要
         if (indicatorGrouping.groupSize <= 1 || shouldHideHandle) {
             return 0
         }
+        // 重なった 2 つの端点インジケーターを等間隔で振り分ける (半ピクセル除算を避けるため偶数間隔)
+        const spacing = ensureEven(Math.max(PANEL_VISIBLE_INDICATOR_SPACING, resolvedIndicatorThickness + 4))
+        return (indicatorGrouping.overlapIndex === 0 ? -0.5 : 0.5) * spacing
+    }, [indicatorGrouping, shouldHideHandle, resolvedIndicatorThickness])
 
-        // 表示すべきインジケーターの個数を決定
-        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 anchorStyle = useMemo<CSSProperties>(() => {
+        const base: CSSProperties = {
+            // 長さ 0 のフレックスアイテム: フレックスレイアウトがこれを境界そのものへ配置する
+            position: "relative",
+            flex: "0 0 0px",
+            alignSelf: "stretch",
+            // DOM 順を配置順の真実として扱うため、クラス由来の order で並びが変わらないようにする
+            order: 0,
+            margin: 0,
+            overflow: "visible",
+            ...(isHorizontal ? { width: 0, minWidth: 0 } : { height: 0, minHeight: 0 }),
+        }
+        return shouldHideHandle ? { ...base, ...HIDDEN_HANDLE_STYLE } : base
+    }, [isHorizontal, shouldHideHandle])
+
+    // 利用者が独自に装飾できるよう、解決済みの寸法を CSS 変数として公開する
+    const customProperties = useMemo<Record<string, string>>(
+        () => ({
+            "--rp-handle-thickness": `${resolvedThickness}px`,
+            "--rp-indicator-thickness": `${resolvedIndicatorThickness}px`,
+            "--rp-indicator-length": `${resolvedIndicatorLength}px`,
+            "--rp-indicator-bar-thickness": `${resolvedBarThickness}px`,
+            "--rp-indicator-bar-length": `${resolvedBarLength}px`,
+        }),
+        [resolvedThickness, resolvedIndicatorThickness, resolvedIndicatorLength, resolvedBarThickness, resolvedBarLength],
+    )
 
-    const indicatorWrapperStyle = useMemo(() => {
-        // ハンドルを非表示にする場合は表示なし
-        if (shouldHideHandle) {
-            return { display: "none" }
+    const handleStyle = useMemo<CSSProperties>(() => {
+        // アンカー原点が境界。半厚みだけ手前へずらすと操作領域の中心線が境界に重なる。
+        // 端数は描画時にピクセルへスナップされるため、ここで丸める必要はない
+        return {
+            ...customProperties,
+            ...style,
+            // ここから下は境界に載るという前提そのもの。利用者のスタイルやクラスで変わると
+            // 操作領域の中心が境界から外れ、touch-action が戻るとタッチではスクロールが優先されてしまう
+            position: "absolute",
+            zIndex: 20,
+            touchAction: "none",
+            // 位置は論理プロパティで与える。アンカーは寸法 0 なので RTL でも同じ点に重なるが、
+            // 「境界からの距離」という意図をそのまま表せる
+            ...(isHorizontal ? { insetBlockStart: 0, insetInlineStart: `${-resolvedThickness / 2}px`, width: `${resolvedThickness}px`, height: "100%" } : { insetInlineStart: 0, insetBlockStart: `${-resolvedThickness / 2}px`, height: `${resolvedThickness}px`, width: "100%" }),
+        }
+    }, [isHorizontal, resolvedThickness, customProperties, style])
+
+    const indicatorWrapperStyle = useMemo<CSSProperties>(() => {
+        if (shouldHideHandle || isIndicatorExplicitlyHidden) {
+            return HIDDEN_INDICATOR_STYLE
+        }
+        const dynamicStyle: CSSProperties = {
+            width: `${isHorizontal ? resolvedIndicatorThickness : resolvedIndicatorLength}px`,
+            height: `${isHorizontal ? resolvedIndicatorLength : resolvedIndicatorThickness}px`,
+            flexShrink: 0,
+        }
+        if (indicatorOffset !== 0) {
+            // 論理方向のオフセットなので RTL では自動的に鏡像になる (符号を分岐させない)
+            dynamicStyle.position = "relative"
+            if (isHorizontal) {
+                dynamicStyle.insetInlineStart = `${indicatorOffset}px`
+            } else {
+                dynamicStyle.insetBlockStart = `${indicatorOffset}px`
+            }
         }
+        return dynamicStyle
+    }, [shouldHideHandle, isIndicatorExplicitlyHidden, isHorizontal, resolvedIndicatorThickness, resolvedIndicatorLength, indicatorOffset])
 
-        // オフセットがゼロの場合はスタイル不要
-        if (indicatorOffset === 0) {
-            return undefined
-        }
+    const indicatorBarStyle = useMemo<CSSProperties>(
+        () => ({
+            width: `${isHorizontal ? resolvedBarThickness : resolvedBarLength}px`,
+            height: `${isHorizontal ? resolvedBarLength : resolvedBarThickness}px`,
+            flexShrink: 0,
+        }),
+        [isHorizontal, resolvedBarThickness, resolvedBarLength],
+    )
 
-        // オフセット分だけインジケーターを移動
-        return isHorizontal ? { transform: `translateX(${indicatorOffset}px)` } : { transform: `translateY(${indicatorOffset}px)` }
-    }, [indicatorOffset, isHorizontal, shouldHideHandle])
+    const baseHandleClasses = useMemo(
+        () =>
+            twMerge(
+                "group absolute z-20 flex select-none items-center justify-center border-none bg-transparent transition-colors duration-150 overflow-visible",
+                isHorizontal ? "cursor-col-resize h-full" : "cursor-row-resize 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,
+            ),
+        [isHorizontal, isHandleDisabled, isDragging, className],
+    )
 
-    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 indicatorWrapperClasses = useMemo(
+        () =>
+            twMerge(
+                "pointer-events-none 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)]",
+                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)]",
+                indicatorConfig?.className,
+            ),
+        [isDragging, indicatorConfig?.className],
     )
 
-    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 indicatorBarClasses = useMemo(
+        () =>
+            twMerge(
+                "pointer-events-none 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)]",
+                isDragging && "bg-blue-500 dark:bg-blue-300",
+                !isHandleDisabled && "group-hover:bg-slate-700 dark:group-hover:bg-slate-100",
+                indicatorConfig?.barClassName,
+            ),
+        [isDragging, isHandleDisabled, indicatorConfig?.barClassName],
     )
 
-    const updateHandleMeasurement = useCallback(() => {
-        const element = handleRef.current
-        if (!element) {
+    useEffect(() => {
+        // ハンドル ID が外部から変更された場合に、旧 ID の測定結果を破棄する
+        if (resolvedHandleId === handleIdRef.current) {
             return
         }
+        const previousId = handleIdRef.current
+        handleIdRef.current = resolvedHandleId
+        lastMeasurementRef.current = null
+        reportHandleMeasurement(previousId, null)
+    }, [reportHandleMeasurement, resolvedHandleId])
 
-        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
-        }
-
-        // 測定結果オブジェクトを構築
+    useEffect(() => {
         const measurement: ResizeHandleLayoutData = {
             id: resolvedHandleId,
-            thickness,
+            thickness: shouldHideHandle ? 0 : resolvedThickness,
             direction,
-            visible: !shouldHideHandle && thickness > PANEL_HANDLE_VISIBILITY_THRESHOLD,
-            startPanelId: adjacentPanelIds.left,
-            endPanelId: adjacentPanelIds.right,
+            visible: !shouldHideHandle && resolvedThickness > PANEL_HANDLE_VISIBILITY_THRESHOLD,
+            startPanelId: adjacentPanelIds.start,
+            endPanelId: adjacentPanelIds.end,
         }
-
-        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
+        lastMeasurementRef.current = measurement
         reportHandleMeasurement(resolvedHandleId, measurement)
-    }, [direction, adjacentPanelIds.left, adjacentPanelIds.right, reportHandleMeasurement, resolvedHandleId, shouldHideHandle])
+    }, [resolvedHandleId, resolvedThickness, shouldHideHandle, direction, adjacentPanelIds.start, adjacentPanelIds.end, reportHandleMeasurement])
 
     useEffect(() => {
-        updateHandleMeasurement()
-    }, [updateHandleMeasurement])
-
-    useEffect(() => {
-        const element = handleRef.current
-        if (!element) {
-            return
+        return () => {
+            // アンマウント時にこのハンドルの測定結果を破棄する。
+            // ID は effect の実行時ではなく後始末の時点で読む (途中で ID を変えたハンドルの登録が残らないように)
+            reportHandleMeasurement(handleIdRef.current, null)
         }
+    }, [reportHandleMeasurement])
 
-        // ResizeObserver が利用できない環境では初回のみ測定
-        if (typeof ResizeObserver === "undefined") {
-            updateHandleMeasurement()
-            return
-        }
+    // 利用者のハンドラーを黙って捨てず、先に呼んでから自分の処理へ進む。
+    // preventDefault() されたイベントは利用者が握り潰したものとして、ジェスチャーを開始しない
+    const composedPointerDown = useCallback(
+        (event: React.PointerEvent<HTMLButtonElement>) => {
+            onPointerDown?.(event)
+            if (!event.defaultPrevented) {
+                handlePointerDown(event)
+            }
+        },
+        [onPointerDown, handlePointerDown],
+    )
 
-        // ハンドル要素のサイズ変化を監視して測定結果を更新
-        const observer = new ResizeObserver(() => {
-            updateHandleMeasurement()
-        })
+    const composedKeyDown = useCallback(
+        (event: React.KeyboardEvent<HTMLButtonElement>) => {
+            onKeyDown?.(event)
+            if (!event.defaultPrevented) {
+                handleKeyDown(event)
+            }
+        },
+        [onKeyDown, handleKeyDown],
+    )
 
-        observer.observe(element)
+    const accessibleLabel = `Resize ${isHorizontal ? "columns" : "rows"} - Drag or use arrow keys to resize, drag to the edge to collapse/expand panels`
 
-        return () => {
-            observer.disconnect()
+    const separatorValues = useMemo(() => {
+        // スプリッターの現在値は「境界より手前のパネルがコンテナに占める割合」。可動域も同じ尺度で公開する。
+        // 折りたたまれたパネルは長さ 0 として扱う: 値を落とすと role="separator" が必須属性を失い、
+        // 支援技術からは「動かせない仕切り」に見えてしまう
+        const startPanel = adjacentPanelIds.start === null ? undefined : getPanel(adjacentPanelIds.start)
+        const endPanel = adjacentPanelIds.end === null ? undefined : getPanel(adjacentPanelIds.end)
+        if (!(startPanel && endPanel) || containerSize <= 0) {
+            return undefined
         }
-    }, [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"],
-            }
+        const bounds = resolveSeparatorBounds(startPanel, endPanel, containerSize)
+        if (!bounds) {
+            return undefined
         }
-        return merged
-    }, [overlayBaseStyle, shouldHideHandle, style])
+        const toPercentage = (value: number) => Math.round((value / containerSize) * 100)
+        return { now: toPercentage(bounds.position), min: toPercentage(bounds.lower), max: toPercentage(bounds.upper) }
+    }, [adjacentPanelIds.start, adjacentPanelIds.end, getPanel, containerSize])
 
     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>
+        <div ref={anchorRef} style={anchorStyle} data-resize-handle-anchor="">
+            {/* biome-ignore lint/a11y/useSemanticElements: 操作できるスプリッターは <hr> では表現できない (WAI-ARIA の window splitter パターンは focusable な role="separator" を要求する) */}
+            <button
+                {...elementProps}
+                type="button"
+                ref={handleRef}
+                className={baseHandleClasses}
+                style={handleStyle}
+                onPointerDown={composedPointerDown}
+                onKeyDown={composedKeyDown}
+                disabled={isHandleDisabled}
+                role="separator"
+                aria-orientation={isHorizontal ? "vertical" : "horizontal"}
+                aria-valuenow={separatorValues?.now}
+                aria-valuemin={separatorValues?.min}
+                aria-valuemax={separatorValues?.max}
+                aria-disabled={isHandleDisabled || undefined}
+                aria-hidden={shouldHideHandle || undefined}
+                aria-label={elementProps["aria-label"] ?? accessibleLabel}
+                data-resize-handle-id={resolvedHandleId}
+                title={title ?? accessibleLabel}>
+                {children ||
+                    (!isIndicatorExplicitlyHidden && (
+                        <div className={indicatorWrapperClasses} style={indicatorWrapperStyle} data-resize-handle-indicator="" aria-hidden="true">
+                            <span className={indicatorBarClasses} style={indicatorBarStyle} data-resize-handle-indicator-bar="" aria-hidden="true" />
+                        </div>
+                    ))}
+            </button>
+        </div>
     )
 })