@aiquants/resize-panels 1.8.0 → 1.9.0

package/src/PanelResizeHandle.tsx

@@ -6,6 +6,7 @@
 import { type CSSProperties, memo, useCallback, useEffect, useId, useMemo, useRef, useState } from "react"
 import { twMerge } from "tailwind-merge"
 import { usePanelGroup } from "./context"
+import { roundHalfToEven } from "./roundHalfToEven"
 import {
     PANEL_COLLAPSE_THRESHOLD_MAX,
     PANEL_COLLAPSE_THRESHOLD_RATIO,
@@ -14,6 +15,12 @@ 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 PanelResizeHandleProps,
@@ -21,11 +28,50 @@ import {
 } from "./types"
 import { calculateSnapThreshold, getConstraintInPixels, getContainerSize } from "./utils"
 
+/**
+ * Common styles applied to hide the handle and its interactive area entirely.
+ * 非表示時のハンドルおよび操作領域全体に適用する共通スタイル定数。
+ */
+const HIDDEN_HANDLE_STYLE: CSSProperties = {
+    display: "none",
+    pointerEvents: "none",
+    visibility: "hidden",
+}
+
+/**
+ * Common styles applied to collapse 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
+}
+
 /**
  * Render an interactive divider that manages adjacent panel resizing gestures.
  * 隣接パネルのリサイズ操作を管理するインタラクティブなディバイダーを描画するコンポーネント。
  */
-export const PanelResizeHandle = memo(({ id, disabled = false, className, style, children, onDragging }: PanelResizeHandleProps) => {
+export const PanelResizeHandle = memo((props: PanelResizeHandleProps) => {
+    const { id, disabled = false, className, style, children, onDragging, thickness, indicator = true, indicatorThickness, indicatorLength, indicatorBarThickness, indicatorBarLength, title } = props
     const { direction, resizePanels, getPanel, collapsePanel, expandPanel, panels, reportHandleMeasurement, containerSize, layoutConstraintViolation } = usePanelGroup()
     const [isDragging, setIsDragging] = useState(false)
     const handleRef = useRef<HTMLButtonElement>(null)
@@ -66,7 +112,6 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
         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) {
@@ -75,7 +120,6 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
             }
         }
 
-        // ハンドルより後方の要素を走査して右パネルを特定
         for (let i = index + 1; i < childrenElements.length; i += 1) {
             const element = childrenElements[i] as HTMLElement
             if (element.dataset.panelId) {
@@ -87,7 +131,6 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
         const nextLeftId = leftPanelElement?.dataset.panelId || ""
         const nextRightId = rightPanelElement?.dataset.panelId || ""
 
-        // 検出結果が前回と同じなら state 更新を省略する
         if (nextLeftId === leftPanelId.current && nextRightId === rightPanelId.current) {
             return
         }
@@ -194,15 +237,12 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
                 moveEvent.preventDefault()
                 moveEvent.stopPropagation()
 
-                // スロットル処理: 頻繁な更新を抑制して計算負荷を下げる
                 const now = performance.now()
                 if (now - lastUpdateTime < throttleMs) return
                 lastUpdateTime = now
 
-                // ドラッグ開始位置からのピクセル変位を計算 (RTL の水平ドラッグは符号を反転)
                 const rawPixelDelta = direction === "horizontal" ? moveEvent.clientX - startPosition.x : moveEvent.clientY - startPosition.y
                 const pixelDelta = isRtlDrag ? -rawPixelDelta : rawPixelDelta
-                // 差分がゼロのときは状態変化がなく後続処理が無駄になるため中断
                 if (pixelDelta === 0) {
                     return
                 }
@@ -210,23 +250,18 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
                 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
@@ -234,46 +269,39 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
 
                     const leftCanCollapseFromEnd = updatedLeftPanel.collapseFromEnd
                     const leftCollapseDirection = updatedLeftPanel.collapsedByDirection ?? "end"
-                    // 左パネルが折りたたみ可能で、新しいサイズが閾値を下回る場合は折りたたむ
                     if (leftCanCollapseFromEnd && !updatedLeftPanel.collapsed && newLeftSizeInPixels <= Math.max(leftMinSizePixels * 0.3, collapseThresholdPixels)) {
                         collapsePanel(leftPanelId.current, "end")
                         return
                     }
 
-                    // 右パネルが折りたたまれており、新しいサイズが展開閾値を超えた場合は展開
                     if (updatedRightPanel.collapsed && newRightSizeInPixels > Math.max(rightMinSizePixels * 0.3, expandThresholdPixels)) {
                         expandPanel(rightPanelId.current, rightCollapseDirection, newRightSizeInPixels)
                         return
                     }
 
-                    // 左パネルが折りたたまれており、新しいサイズが展開閾値を超えた場合は展開
                     if (updatedLeftPanel.collapsed && newLeftSizeInPixels > Math.max(leftMinSizePixels * 0.3, expandThresholdPixels)) {
                         expandPanel(leftPanelId.current, leftCollapseDirection, newLeftSizeInPixels)
                         return
                     }
 
-                    // スナップ処理: 最小サイズ以下になった場合はゼロサイズにスナップさせる
                     if (containerSize > 0) {
                         const totalPanelPixels = updatedLeftPanel.size + updatedRightPanel.size
-                        // コンテナ比率と定数に基づきゼロスナップの閾値を算出
                         const snapThreshold = calculateSnapThreshold(containerSize)
                         let snapped = false
 
-                        // 左パネルがスナップ可能で、新しいサイズがスナップ閾値以下の場合はゼロへスナップ
-                        if (leftMinConstraintPixels <= snapThreshold && newLeftSizeInPixels <= snapThreshold && initialLeftSize !== 0) {
+                        if (leftMinSizePixels <= snapThreshold && newLeftSizeInPixels <= snapThreshold && initialLeftSize !== 0) {
                             const snappedLeft = 0
                             const snappedRight = Math.max(0, totalPanelPixels - snappedLeft)
 
-                            if (snappedRight >= rightMinConstraintPixels) {
+                            if (snappedRight >= rightMinSizePixels) {
                                 resizePanels(leftPanelId.current, rightPanelId.current, snappedLeft, snappedRight)
                                 snapped = true
                             }
-                        } else if (rightMinConstraintPixels <= snapThreshold && newRightSizeInPixels <= snapThreshold && initialRightSize !== 0) {
-                            // 右パネルがスナップ可能で、新しいサイズがスナップ閾値以下の場合はゼロへスナップ
+                        } else if (rightMinSizePixels <= snapThreshold && newRightSizeInPixels <= snapThreshold && initialRightSize !== 0) {
                             const snappedRight = 0
                             const snappedLeft = Math.max(0, totalPanelPixels - snappedRight)
 
-                            if (snappedLeft >= leftMinConstraintPixels) {
+                            if (snappedLeft >= leftMinSizePixels) {
                                 resizePanels(leftPanelId.current, rightPanelId.current, snappedLeft, snappedRight)
                                 snapped = true
                             }
@@ -284,12 +312,10 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
                         }
                     }
 
-                    // いずれかのパネルが折りたたまれている場合はリサイズ処理を中断
                     if (updatedLeftPanel.collapsed || updatedRightPanel.collapsed) {
                         return
                     }
 
-                    // 通常のリサイズ処理を実行して隣接パネルのサイズを更新
                     resizePanels(leftPanelId.current, rightPanelId.current, newLeftSizeInPixels, newRightSizeInPixels)
                 }
             }
@@ -381,20 +407,23 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
     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 baseHandleClasses = useMemo(
+        () =>
+            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,
+            ),
+        [cursor, isHorizontal, isHandleDisabled, isDragging, className],
     )
 
     const adjacentIndices = useMemo(() => {
-        // パネル ID からパネル配列内のインデックスを探索するヘルパー関数
         const findIndex = (panelId: string | null) => {
             if (!panelId) {
                 return -1
@@ -416,7 +445,6 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
     const containerLength = isHorizontal ? containerSize.width : containerSize.height
 
     const boundaryOffset = useMemo(() => {
-        // 指定範囲のパネルサイズ合計を安全に算出するヘルパー
         const safeSum = (startIndex: number, endIndexInclusive: number) => {
             if (startIndex > endIndexInclusive) {
                 return 0
@@ -446,7 +474,6 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
     }, [adjacentIndices.left, adjacentIndices.right, panels])
 
     const clampedOffset = useMemo(() => {
-        // 境界位置が無効値やコンテナ範囲外に逸脱した場合に補正
         if (!Number.isFinite(boundaryOffset) || boundaryOffset < 0) {
             return 0
         }
@@ -456,34 +483,68 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
         return boundaryOffset
     }, [boundaryOffset, containerLength])
 
+    const indicatorConfig = typeof indicator === "object" && indicator !== null ? indicator : undefined
+    const isIndicatorExplicitlyHidden = indicator === false || indicatorConfig?.visible === false
+
+    const rawThickness = 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
+
+    const rawIndicatorThickness = sanitizeDimension(indicatorThickness ?? indicatorConfig?.thickness, PANEL_INDICATOR_THICKNESS)
+    const rawIndicatorLength = sanitizeDimension(indicatorLength ?? indicatorConfig?.length, defaultIndicatorLength)
+    const rawBarThickness = sanitizeDimension(indicatorBarThickness ?? indicatorConfig?.barThickness, PANEL_INDICATOR_BAR_THICKNESS)
+    const rawBarLength = sanitizeDimension(indicatorBarLength ?? indicatorConfig?.barLength, defaultBarLength)
+
+    // 幾何学的内包不変条件: 内部バー寸法がインジケーター外枠およびハンドル操作領域を超えないようクランプ
+    const resolvedThickness = Math.max(1, rawThickness)
+    const resolvedIndicatorThickness = Math.min(resolvedThickness, Math.max(1, rawIndicatorThickness))
+    const resolvedIndicatorLength = Math.max(1, rawIndicatorLength)
+    const resolvedBarThickness = Math.min(resolvedIndicatorThickness, Math.max(1, rawBarThickness))
+    const resolvedBarLength = Math.min(resolvedIndicatorLength, Math.max(1, rawBarLength))
+
+    // 静的 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 overlayBaseStyle = useMemo<CSSProperties>(() => {
+        // RTL では右端起点から論理距離を差し引いた位置が物理境界中心線となる
+        const centerLine = isHorizontal && isRtl && containerLength > 0 ? containerLength - clampedOffset : clampedOffset
+
+        // transform: translate(-50%) による 0.5px サブピクセル滲みを防ぐため、中心線から半厚みを引き銀行丸めで整数ピクセル原点を決定
+        const startCoord = roundHalfToEven(centerLine - resolvedThickness / 2, 0)
+
         const base: CSSProperties = {
             position: "absolute",
             zIndex: 20,
             touchAction: "none",
+            ...customProperties,
         }
 
         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.left = `${startCoord}px`
+            base.width = `${resolvedThickness}px`
             base.height = "100%"
         } else {
             base.left = 0
-            base.top = `${clampedOffset}px`
-            base.transform = "translateY(-50%)"
-            base.height = `${PANEL_HANDLE_THICKNESS}px`
+            base.top = `${startCoord}px`
+            base.height = `${resolvedThickness}px`
             base.width = "100%"
         }
 
         return base
-    }, [clampedOffset, isHorizontal, isRtl, containerLength])
+    }, [clampedOffset, isHorizontal, isRtl, containerLength, resolvedThickness, customProperties])
 
     const indicatorGrouping = useMemo(() => {
         const snapThreshold = calculateSnapThreshold(containerLength)
-        // パネルが実質的に折りたたまれているか判定するヘルパー関数
         const isEffectivelyCollapsed = (panelIndex: number) => {
             if (panelIndex < 0 || panelIndex >= panels.length) {
                 return false
@@ -498,7 +559,6 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
             return target.size <= snapThreshold
         }
 
-        // 指定インデックスから連続する折りたたみパネルの数を数える
         const countCollapsed = (startIndex: number, step: 1 | -1) => {
             if (!isEffectivelyCollapsed(startIndex)) {
                 return 0
@@ -531,60 +591,86 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
         if (hasLayoutConstraintViolation) {
             return true
         }
-        // グループサイズが 1 以下の場合は単独ハンドルなので非表示にしない
         if (indicatorGrouping.groupSize <= 1) {
             return false
         }
-        // ハンドルがグループ内の中間位置にある場合は重複防止のため非表示にする
+        // 折りたたみ重なり時の視覚重複を防ぐため端点以外の重複ハンドルを不可視化
         const lastIndex = indicatorGrouping.groupSize - 1
         return indicatorGrouping.overlapIndex > 0 && indicatorGrouping.overlapIndex < lastIndex
     }, [indicatorGrouping, hasLayoutConstraintViolation])
 
     const indicatorOffset = useMemo(() => {
-        // ハンドルが非表示の場合またはグループサイズが 1 以下の場合はオフセット不要
         if (indicatorGrouping.groupSize <= 1 || shouldHideHandle) {
             return 0
         }
 
-        // 表示すべきインジケーターの個数を決定
         const visibleCount = indicatorGrouping.groupSize > 1 ? 2 : 1
         if (visibleCount === 1) {
             return 0
         }
 
-        // このハンドルが表示インジケーター群内のどの位置にあるか計算
+        // 半ピクセル除算による非対称性を防ぐため偶数スペーシングを保証
+        const dynamicSpacing = ensureEven(Math.max(PANEL_VISIBLE_INDICATOR_SPACING, resolvedIndicatorThickness + 4))
         const visibleIndex = indicatorGrouping.overlapIndex === 0 ? 0 : visibleCount - 1
         const centerIndex = (visibleCount - 1) / 2
-        return (visibleIndex - centerIndex) * PANEL_VISIBLE_INDICATOR_SPACING
-    }, [indicatorGrouping, shouldHideHandle])
+        const rawOffset = (visibleIndex - centerIndex) * dynamicSpacing
 
-    const indicatorWrapperStyle = useMemo(() => {
-        // ハンドルを非表示にする場合は表示なし
-        if (shouldHideHandle) {
-            return { display: "none" }
+        // 水平かつ RTL の環境では start パネルが物理右側にあるため論理順の正シフトを物理左方向（負）へ反転
+        return isHorizontal && isRtl ? -rawOffset : rawOffset
+    }, [indicatorGrouping, shouldHideHandle, resolvedIndicatorThickness, isHorizontal, isRtl])
+
+    const indicatorWrapperStyle = useMemo<CSSProperties>(() => {
+        if (shouldHideHandle || isIndicatorExplicitlyHidden) {
+            return HIDDEN_INDICATOR_STYLE
         }
 
-        // オフセットがゼロの場合はスタイル不要
-        if (indicatorOffset === 0) {
-            return undefined
+        const width = isHorizontal ? resolvedIndicatorThickness : resolvedIndicatorLength
+        const height = isHorizontal ? resolvedIndicatorLength : resolvedIndicatorThickness
+
+        const dynamicStyle: CSSProperties = {
+            width: `${width}px`,
+            height: `${height}px`,
+            flexShrink: 0,
+        }
+
+        if (indicatorOffset !== 0) {
+            dynamicStyle.transform = isHorizontal ? `translateX(${indicatorOffset}px)` : `translateY(${indicatorOffset}px)`
         }
 
-        // オフセット分だけインジケーターを移動
-        return isHorizontal ? { transform: `translateX(${indicatorOffset}px)` } : { transform: `translateY(${indicatorOffset}px)` }
-    }, [indicatorOffset, isHorizontal, shouldHideHandle])
+        return dynamicStyle
+    }, [shouldHideHandle, isIndicatorExplicitlyHidden, isHorizontal, resolvedIndicatorThickness, resolvedIndicatorLength, indicatorOffset])
 
-    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 indicatorBarStyle = useMemo<CSSProperties>(() => {
+        const width = isHorizontal ? resolvedBarThickness : resolvedBarLength
+        const height = isHorizontal ? resolvedBarLength : resolvedBarThickness
+
+        return {
+            width: `${width}px`,
+            height: `${height}px`,
+            flexShrink: 0,
+        }
+    }, [isHorizontal, resolvedBarThickness, resolvedBarLength])
+
+    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(() => {
@@ -595,13 +681,11 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
 
         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") {
@@ -626,7 +710,6 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
             thickness = 0
         }
 
-        // 測定結果オブジェクトを構築
         const measurement: ResizeHandleLayoutData = {
             id: resolvedHandleId,
             thickness,
@@ -638,7 +721,6 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
 
         const lastMeasurement = lastHandleMeasurementRef.current
 
-        // 測定値が前回と実質的に同一であれば更新をスキップ
         if (
             lastMeasurement &&
             Math.abs(lastMeasurement.thickness - measurement.thickness) <= 0.25 &&
@@ -664,13 +746,11 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
             return
         }
 
-        // ResizeObserver が利用できない環境では初回のみ測定
         if (typeof ResizeObserver === "undefined") {
             updateHandleMeasurement()
             return
         }
 
-        // ハンドル要素のサイズ変化を監視して測定結果を更新
         const observer = new ResizeObserver(() => {
             updateHandleMeasurement()
         })
@@ -687,9 +767,7 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
         if (shouldHideHandle) {
             return {
                 ...merged,
-                display: "none" as CSSProperties["display"],
-                pointerEvents: "none" as CSSProperties["pointerEvents"],
-                visibility: "hidden" as CSSProperties["visibility"],
+                ...HIDDEN_HANDLE_STYLE,
             }
         }
         return merged
@@ -707,12 +785,13 @@ export const PanelResizeHandle = memo(({ id, disabled = false, className, style,
             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>
-            )}
+            title={title ?? `Resize ${isHorizontal ? "columns" : "rows"} - Drag or use arrow keys to resize, drag to the edge to collapse/expand panels`}>
+            {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>
     )
 })

package/src/index.ts

@@ -17,13 +17,18 @@ export type {
     ContainerAxisMeasurement,
     ContainerSize,
     FlexibleSize,
+    LayoutConstraintViolation,
+    LayoutConstraintViolationReason,
     PanelCollapseDirection,
     PanelDirection,
     PanelGroupContextValue,
     PanelGroupProps,
     PanelLayoutData,
+    PanelMeasurement,
     PanelProps,
+    PanelResizeHandleIndicatorConfig,
     PanelResizeHandleProps,
+    ResizeHandleLayoutData,
     SizeConfig,
     SizeUnit,
 } from "./types"
@@ -37,12 +42,23 @@ export {
     saveLayout,
 } from "./utils"
 
+/**
+ * Safely escape a selector identifier for use in CSS query selectors.
+ * セレクタ文字列を安全にエスケープする補助関数。
+ */
+const escapeIdentifier = (id: string): string => {
+    return typeof CSS !== "undefined" && typeof CSS.escape === "function" ? CSS.escape(id) : id.replace(/["\\]/g, "\\$&")
+}
+
 /**
  * Locate a panel element in the DOM by its data attribute.
  * data 属性を手がかりにパネル要素を DOM から取得する補助関数。
  */
 export const getPanelElement = (id: string): HTMLElement | null => {
-    return document.querySelector(`[data-panel-id="${id}"]`)
+    if (typeof document === "undefined") {
+        return null
+    }
+    return document.querySelector(`[data-panel-id="${escapeIdentifier(id)}"]`)
 }
 
 /**
@@ -50,7 +66,10 @@ export const getPanelElement = (id: string): HTMLElement | null => {
  * data 属性を手がかりにパネルグループ要素を DOM から取得する補助関数。
  */
 export const getPanelGroupElement = (id: string): HTMLElement | null => {
-    return document.querySelector(`[data-panel-group-id="${id}"]`)
+    if (typeof document === "undefined") {
+        return null
+    }
+    return document.querySelector(`[data-panel-group-id="${escapeIdentifier(id)}"]`)
 }
 
 /**
@@ -58,5 +77,8 @@ export const getPanelGroupElement = (id: string): HTMLElement | null => {
  * data 属性を手がかりにリサイズハンドル要素を DOM から取得する補助関数。
  */
 export const getResizeHandleElement = (id: string): HTMLElement | null => {
-    return document.querySelector(`[data-resize-handle-id="${id}"]`)
+    if (typeof document === "undefined") {
+        return null
+    }
+    return document.querySelector(`[data-resize-handle-id="${escapeIdentifier(id)}"]`)
 }

package/src/styles/components.entry.css

@@ -5,4 +5,6 @@
  * (preflight を Tailwind ホストへ流し込むとホストの base 層を破壊するため厳禁)。
  */
 @import "tailwindcss/theme.css" theme(reference);
-@import "./resize-panels.css";
+@layer components {
+  @import "./resize-panels.css";
+}

package/src/styles/resize-panels.css

@@ -1,3 +1 @@
-@layer components {
-  /* nothing */
-}
+/* nothing */