@aiquants/resize-panels 1.7.2 → 1.8.0

package/src/PanelDebugInfo.tsx

@@ -0,0 +1,148 @@
+/**
+ * @file Debug info overlay component for panels
+ * パネル用デバッグ情報オーバーレイコンポーネント
+ */
+
+import { type CSSProperties, memo, useMemo } from "react"
+import type { PanelDirection, PanelLayoutData } from "./types"
+
+type PanelDebugInfoProps = {
+    panel: PanelLayoutData | undefined
+    measuredPixelSize: number
+    measuredPercentageSize: number
+    containerAxisSize: number
+    direction: PanelDirection
+}
+
+type FormatPanelDebugInfoArgs = {
+    panel: PanelLayoutData | undefined
+    measuredPixelSize: number
+    measuredPercentageSize: number
+    containerAxisSize: number
+    containerLabel: string
+}
+
+type FormattedPanelDebugInfo = {
+    stateValueDisplay: string
+    measuredValueDisplay: string
+    containerDisplay: string
+    headlineLabel: string
+    titleText: string
+}
+
+export const formatPanelDebugInfo = ({ panel, measuredPixelSize, measuredPercentageSize, containerAxisSize, containerLabel }: FormatPanelDebugInfoArgs): FormattedPanelDebugInfo => {
+    const rawStatePixelSize = panel?.size
+    const statePixelDisplay = typeof rawStatePixelSize === "number" && Number.isFinite(rawStatePixelSize) ? `${rawStatePixelSize.toFixed(3)}px` : "-"
+    const statePercentageDisplay = panel?.percentageSize !== undefined ? `${panel.percentageSize.toFixed(3)}%` : "-"
+    const measuredPixelDisplay = Number.isFinite(measuredPixelSize) ? `${measuredPixelSize.toFixed(3)}px` : "-"
+    const measuredPercentageDisplay = Number.isFinite(measuredPercentageSize) ? `${measuredPercentageSize.toFixed(3)}%` : "-"
+    const containerDisplay = Number.isFinite(containerAxisSize) ? `${containerAxisSize.toFixed(3)}px` : "-"
+    const stateValueDisplay = `${statePixelDisplay} / ${statePercentageDisplay}`
+    const measuredValueDisplay = `${measuredPixelDisplay} / ${measuredPercentageDisplay}`
+    const headlineLabel = panel?.sizeUnit === "pixels" ? "Fixed" : "Flexible"
+    const titleLines = [headlineLabel, `${containerLabel}: ${containerDisplay}`, `size (state): ${stateValueDisplay}`, `size (measured): ${measuredValueDisplay}`]
+    return {
+        stateValueDisplay,
+        measuredValueDisplay,
+        containerDisplay,
+        headlineLabel,
+        titleText: titleLines.join("\n"),
+    }
+}
+
+export const PanelDebugInfo = memo(({ panel, measuredPixelSize, measuredPercentageSize, containerAxisSize, direction }: PanelDebugInfoProps) => {
+    const containerLabel = direction === "horizontal" ? "container width" : "container height"
+    const { stateValueDisplay, measuredValueDisplay, containerDisplay, headlineLabel, titleText } = useMemo(
+        () =>
+            formatPanelDebugInfo({
+                panel,
+                measuredPixelSize,
+                measuredPercentageSize,
+                containerAxisSize,
+                containerLabel,
+            }),
+        [panel, measuredPixelSize, measuredPercentageSize, containerAxisSize, containerLabel],
+    )
+
+    const containerStyle: CSSProperties = {
+        position: "absolute",
+        top: "2px",
+        right: "4px",
+        backgroundColor: "rgba(30, 41, 59, 0.6)",
+        color: "#fff",
+        padding: "4px 8px",
+        borderRadius: "6px",
+        fontSize: "11px",
+        fontFamily: "monospace",
+        pointerEvents: "auto",
+        zIndex: 10,
+        boxShadow: "0 2px 4px rgba(0,0,0,0.3)",
+        border: "1px solid rgba(255,255,255,0.1)",
+        maxWidth: "calc(100% - 12px)",
+        minWidth: "60px",
+        width: "fit-content",
+        overflow: "hidden",
+    }
+
+    const wrapperStyle: CSSProperties = {
+        display: "flex",
+        flexDirection: "column",
+        gap: "1px",
+        minWidth: "0",
+        width: "100%",
+    }
+
+    const headlineStyle: CSSProperties = {
+        display: "flex",
+        justifyContent: "flex-start",
+        alignItems: "center",
+        gap: "6px",
+        fontSize: "10px",
+        color: "#ccc",
+        whiteSpace: "nowrap",
+        overflow: "hidden",
+        textOverflow: "ellipsis",
+        minWidth: "0",
+        width: "100%",
+    }
+
+    const debugLineStyle: CSSProperties = {
+        display: "flex",
+        justifyContent: "space-between",
+        alignItems: "center",
+        gap: "6px",
+        whiteSpace: "nowrap",
+        overflow: "hidden",
+        textOverflow: "ellipsis",
+        minWidth: "0",
+        width: "100%",
+    }
+
+    const debugValueStyle: CSSProperties = {
+        marginLeft: "auto",
+        fontVariantNumeric: "tabular-nums",
+        whiteSpace: "nowrap",
+    }
+
+    return (
+        <div style={containerStyle} title={titleText}>
+            <div style={wrapperStyle}>
+                <div style={headlineStyle}>
+                    <span>{headlineLabel}</span>
+                </div>
+                <div style={debugLineStyle}>
+                    <span>{containerLabel}</span>
+                    <span style={debugValueStyle}>{containerDisplay}</span>
+                </div>
+                <div style={debugLineStyle}>
+                    <span>size (state)</span>
+                    <span style={debugValueStyle}>{stateValueDisplay}</span>
+                </div>
+                <div style={debugLineStyle}>
+                    <span>size (measured)</span>
+                    <span style={debugValueStyle}>{measuredValueDisplay}</span>
+                </div>
+            </div>
+        </div>
+    )
+})

package/src/PanelGroup.tsx

@@ -0,0 +1,260 @@
+/**
+ * @file PanelGroup component for custom resizable panels
+ * カスタムリサイズ可能パネルのための PanelGroup コンポーネント
+ */
+
+import { type CSSProperties, lazy, Suspense, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react"
+import { twMerge } from "tailwind-merge"
+import { PanelGroupContext } from "./context"
+import { useResizablePanels } from "./hooks"
+import type { PanelGroupProps } from "./types"
+import { getContainerSize } from "./utils"
+
+// デバッグオーバーレイ (UI とストア) は dynamic import で遅延読み込みする。
+// showDebugInfo を使わないアプリのバンドルへオーバーレイ一式を含めず、ストア購読も発生させないための分離
+const LazyDebugOverlayGate = lazy(() => import("./GlobalDebugOverlay").then((module) => ({ default: module.GlobalDebugOverlayGate })))
+
+type DebugOverlayStoreModule = typeof import("./debugOverlayStore")
+
+let debugGroupIdCounter = 0
+
+/**
+ * Generate unique debug group identifier for panel groups without explicit IDs.
+ * 明示的な ID を持たないパネルグループ用の一意なデバッググループ識別子を生成。
+ */
+const generateDebugGroupId = () => {
+    debugGroupIdCounter += 1
+    return `panel-group-${debugGroupIdCounter}`
+}
+
+type ResizablePanelsContextValue = ReturnType<typeof useResizablePanels>["contextValue"]
+type LayoutConstraintViolation = NonNullable<ResizablePanelsContextValue["layoutConstraintViolation"]>
+type DebugPanel = ResizablePanelsContextValue["panels"][number]
+type DebugPanelMeasurementMap = ResizablePanelsContextValue["panelMeasurements"]
+
+/**
+ * Builds summary and detail labels for layout constraint placeholders.
+ * レイアウト制約プレースホルダー用のサマリーと詳細ラベルを生成。
+ */
+const buildConstraintCopy = (violation: LayoutConstraintViolation) => {
+    const isMinimum = violation.reason === "minimum-exceeded"
+    const summary = isMinimum ? "Layout unavailable: minimum panel sizes exceed the container." : "Layout unavailable: panels cannot fill the container with their maximum sizes."
+    const detail = isMinimum
+        ? `Min required: ${Math.ceil(violation.totalMinimumSize ?? 0)}px | Available: ${Math.floor(violation.availableContainerSize)}px`
+        : `Max total: ${Math.floor(violation.totalMaximumSize ?? 0)}px | Needed: ${Math.floor(violation.availableContainerSize)}px`
+    return { summary, detail }
+}
+
+/**
+ * Synchronizes measured panel dimensions into overlay panel descriptors.
+ * 測定済みパネル寸法をオーバーレイ用パネル情報へ同期。
+ */
+const mergePanelMeasurements = (panels: ReadonlyArray<DebugPanel>, measurementMap: DebugPanelMeasurementMap): DebugPanel[] => {
+    let changed = false
+    const nextPanels = panels.map((panel) => {
+        const measurement = measurementMap[panel.id]
+        if (!measurement) {
+            return panel
+        }
+        if (panel.measuredPixelSize === measurement.pixelSize && panel.measuredPercentageSize === measurement.percentageSize) {
+            return panel
+        }
+        changed = true
+        return {
+            ...panel,
+            measuredPixelSize: measurement.pixelSize,
+            measuredPercentageSize: measurement.percentageSize,
+        }
+    })
+    return changed ? nextPanels : (panels as DebugPanel[])
+}
+
+/**
+ * Measures overlay container dimensions with graceful fallbacks.
+ * フォールバックを考慮しつつオーバーレイ用コンテナ寸法を計測。
+ */
+const measureDebugOverlayContainerSize = (element: HTMLElement, fallbackWidth?: number, fallbackHeight?: number) => {
+    const horizontal = getContainerSize(element, "horizontal")
+    const vertical = getContainerSize(element, "vertical")
+    const rect = element.getBoundingClientRect()
+    const width = horizontal.inner > 0 ? horizontal.inner : (fallbackWidth ?? rect.width)
+    const height = vertical.inner > 0 ? vertical.inner : (fallbackHeight ?? rect.height)
+    return { width, height }
+}
+
+/**
+ * Provide layout context and container for coordinated panels.
+ * 連動するパネルのためのレイアウトコンテキストとコンテナを提供するコンポーネント。
+ */
+export const PanelGroup = (props: PanelGroupProps) => {
+    const { id, className, style, children, direction } = props
+    const { groupRef, contextValue, groupStyle } = useResizablePanels(props)
+
+    const [debugOverlayContainerSize, setDebugOverlayContainerSize] = useState({ width: 0, height: 0 })
+
+    const constraintViolation = contextValue.layoutConstraintViolation
+    const shouldRenderPlaceholder = Boolean(constraintViolation)
+    const placeholderInner = useMemo(() => {
+        if (!constraintViolation) {
+            return null
+        }
+        const { summary, detail } = buildConstraintCopy(constraintViolation)
+        return (
+            <div
+                className="flex w-full flex-1 flex-col items-center justify-center gap-2 rounded-lg border border-slate-300 border-dashed bg-slate-100/70 px-6 py-8 text-center text-slate-600 text-sm dark:border-slate-600 dark:bg-slate-800/50 dark:text-slate-200"
+                data-panel-group-placeholder="constraint-violation">
+                <span>{summary}</span>
+                <span className="text-slate-500 text-xs dark:text-slate-400">{detail}</span>
+            </div>
+        )
+    }, [constraintViolation])
+
+    const debugGroupIdRef = useRef(id ?? generateDebugGroupId())
+    const debugGroupId = debugGroupIdRef.current
+    const debugDisplayName = id ?? debugGroupId
+
+    const shouldShowDebugOverlay = contextValue.showDebugInfo && contextValue.panels.length > 0
+    const debugOverlayPanels = shouldShowDebugOverlay ? contextValue.panels : []
+    const debugOverlayMeasurementMap = shouldShowDebugOverlay ? contextValue.panelMeasurements : {}
+    const debugOverlayHandles = useMemo(() => {
+        if (!shouldShowDebugOverlay) {
+            return []
+        }
+        const handles = Object.values(contextValue.handleMeasurements)
+        if (handles.length <= 1) {
+            return handles
+        }
+        return handles.slice().sort((a, b) => a.id.localeCompare(b.id))
+    }, [contextValue.handleMeasurements, shouldShowDebugOverlay])
+    const containerSize = contextValue.containerSize
+    const debugOverlayContainerWidth = debugOverlayContainerSize.width > 0 ? debugOverlayContainerSize.width : containerSize.width
+    const debugOverlayContainerHeight = debugOverlayContainerSize.height > 0 ? debugOverlayContainerSize.height : containerSize.height
+
+    useLayoutEffect(() => {
+        // shouldShowDebugOverlay と groupRef に応じてデバッグオーバーレイ用コンテナ寸法を監視
+        if (!shouldShowDebugOverlay) {
+            setDebugOverlayContainerSize({ width: 0, height: 0 })
+            return
+        }
+        if (typeof window === "undefined" || typeof ResizeObserver === "undefined") {
+            return
+        }
+        const element = groupRef.current
+        if (!element) {
+            return
+        }
+        const updateSize = (nextSize: { width: number; height: number }) => {
+            setDebugOverlayContainerSize((previous) => (previous.width === nextSize.width && previous.height === nextSize.height ? previous : nextSize))
+        }
+        const observer = new ResizeObserver((entries) => {
+            for (const entry of entries) {
+                if (entry.target !== element) {
+                    continue
+                }
+                const nextSize = measureDebugOverlayContainerSize(element, entry.contentRect.width, entry.contentRect.height)
+                updateSize(nextSize)
+            }
+        })
+        observer.observe(element)
+        updateSize(measureDebugOverlayContainerSize(element))
+        return () => {
+            observer.disconnect()
+        }
+    }, [groupRef, shouldShowDebugOverlay])
+
+    const debugOverlayPanelsWithMeasurements = useMemo(() => mergePanelMeasurements(debugOverlayPanels, debugOverlayMeasurementMap), [debugOverlayPanels, debugOverlayMeasurementMap])
+
+    useEffect(() => {
+        // shouldShowDebugOverlay と debugGroupId に応じてデバッグオーバーレイ有効状態を同期
+        // ストアは遅延読み込みのため、有効化されるまで import しない (未読込なら解除処理も不要)
+        if (!shouldShowDebugOverlay) {
+            return
+        }
+
+        let cancelled = false
+        let loadedStore: DebugOverlayStoreModule | null = null
+        import("./debugOverlayStore").then((storeModule) => {
+            if (cancelled) {
+                return
+            }
+            loadedStore = storeModule
+            storeModule.enableDebugOverlayGroup(debugGroupId)
+        })
+
+        return () => {
+            cancelled = true
+            if (loadedStore) {
+                loadedStore.disableDebugOverlayGroup(debugGroupId)
+                loadedStore.removeDebugOverlayGroup(debugGroupId)
+            }
+        }
+    }, [shouldShowDebugOverlay, debugGroupId])
+
+    useEffect(() => {
+        // 依存配列の変化ごとに最新のオーバーレイ集計をストアへ送出
+        if (!shouldShowDebugOverlay) {
+            return
+        }
+
+        let cancelled = false
+        import("./debugOverlayStore").then((storeModule) => {
+            if (cancelled) {
+                return
+            }
+            storeModule.updateDebugOverlayGroup(debugGroupId, {
+                displayName: debugDisplayName,
+                direction,
+                containerSize: {
+                    width: debugOverlayContainerWidth,
+                    height: debugOverlayContainerHeight,
+                },
+                panels: debugOverlayPanelsWithMeasurements,
+                handles: debugOverlayHandles,
+            })
+        })
+        return () => {
+            cancelled = true
+        }
+    }, [shouldShowDebugOverlay, debugGroupId, debugDisplayName, direction, debugOverlayContainerWidth, debugOverlayContainerHeight, debugOverlayPanelsWithMeasurements, debugOverlayHandles])
+
+    const mergedStyle = useMemo(() => {
+        const baseStyle: CSSProperties = {
+            ...groupStyle,
+            ...style,
+        }
+        if (!baseStyle.position) {
+            baseStyle.position = "relative"
+        }
+        return baseStyle
+    }, [groupStyle, style])
+
+    return (
+        <PanelGroupContext.Provider value={contextValue}>
+            <div ref={groupRef} className={twMerge("panel-group", direction === "horizontal" ? "flex-row" : "flex-col", className)} style={mergedStyle} data-panel-group-id={id} data-panel-group-direction={direction}>
+                {children}
+                {shouldRenderPlaceholder && placeholderInner ? (
+                    <div
+                        className="pointer-events-auto"
+                        style={{
+                            position: "absolute",
+                            inset: 0,
+                            zIndex: 40,
+                            display: "flex",
+                            flexDirection: "column",
+                            alignItems: "center",
+                            justifyContent: "center",
+                            backgroundColor: "rgba(248, 250, 252, 0.82)",
+                            backdropFilter: "blur(2px)",
+                        }}>
+                        {placeholderInner}
+                    </div>
+                ) : null}
+            </div>
+            {shouldShowDebugOverlay && (
+                <Suspense fallback={null}>
+                    <LazyDebugOverlayGate groupId={debugGroupId} />
+                </Suspense>
+            )}
+        </PanelGroupContext.Provider>
+    )
+}