@aiquants/drag-drop-panels 0.7.2 → 0.8.0

package/src/drag-drop/hooks/usePanelManagement.tsx

@@ -0,0 +1,238 @@
+/**
+ * @fileoverview This file defines the `usePanelManagement` custom hook, a simplified
+ * utility for managing panel properties like visibility, size, and DOM element references.
+ * It also provides functions for applying visual effects during drag operations.
+ *
+ * このファイルは `usePanelManagement` カスタムフックを定義します。これは、パネルの可視性、サイズ、
+ * DOM要素の参照などのプロパティを管理するための簡略化されたユーティリティです。
+ * また、ドラッグ操作中に視覚効果を適用する機能も提供します。
+ */
+import { useCallback, useRef, useState } from "react"
+import type { PanelSizeInfo } from "../types"
+
+/**
+ * A simplified custom hook for managing panel state such as size, visibility, and refs。
+ * It provides basic functionalities without the complexity of ResizeObserver for performance。
+ *
+ * パネルの状態（サイズ、可視性、refなど）を管理するための簡略化されたカスタムフック。
+ * パフォーマンスのためにResizeObserverの複雑さなしに、基本的な機能を提供します。
+ * @param {Record<string, boolean>} initialPanelVisibility - An object mapping panel IDs to their initial visibility state.
+ * @param {number} scale - Current layout scale.
+ */
+export const usePanelManagement = (initialPanelVisibility: Record<string, boolean>, scale: number = 1) => {
+    /**
+     * Manages the visibility state for each panel。
+     * 各パネルの可視性状態を管理します。
+     */
+    const [panelVisibility, setPanelVisibility] = useState(initialPanelVisibility)
+
+    /**
+     * Stores size information for each panel. Note: This is a simplified implementation。
+     * 各パネルのサイズ情報を格納します。注意：これは簡略化された実装です。
+     */
+    const [panelSizes, setPanelSizes] = useState<Record<string, PanelSizeInfo>>({})
+
+    /**
+     * A ref to track previous panel sizes to prevent unnecessary updates。
+     * 不要な更新を防ぐために、前回のパネルサイズを追跡するref。
+     */
+    const previousSizesRef = useRef<Record<string, PanelSizeInfo>>({})
+
+    /**
+     * A ref to hold the cloned drag image element。
+     * クローンされたドラッグイメージ要素を保持するための ref。
+     */
+    const dragImageRef = useRef<HTMLElement | null>(null)
+
+    /**
+     * A ref to hold the offset of the mouse pointer within the dragged panel。
+     * ドラッグされたパネル内のマウスポインタのオフセットを保持するための ref。
+     */
+    const dragImageOffset = useRef({ x: 0, y: 0 })
+
+    /**
+     * 表示倍率を安定コールバック (createDragImage / updateDragImagePosition) から最新値で読むための ref。
+     * scale を直接クロージャで参照すると useCallback の依存に含める必要が生じ、初期値 (=1) で固定される。
+     * A ref to read the latest layout scale from stable callbacks without stale-closure capture.
+     */
+    const scaleRef = useRef(scale)
+    scaleRef.current = scale
+
+    /**
+     * Retrieves the DOM element for a given panel ID using a data attribute selector。
+     * データ属性セレクタを使用して、指定されたパネルIDのDOM要素を取得します。
+     * @param {string} panelId - The ID of the panel to find。
+     * @returns {HTMLElement | null} The found element or null。
+     */
+    const getPanelElement = useCallback((panelId: string): HTMLElement | null => {
+        return document.querySelector(`[data-panel-id="${panelId}"]`)
+    }, [])
+
+    /**
+     * 内部関数：指定された要素のサイズ情報を更新します。
+     * @param panelId - パネルのID
+     * @param element - サイズを測定するHTML要素
+     */
+    const _updateSize = useCallback(
+        (panelId: string, element: Element) => {
+            const rect = element.getBoundingClientRect()
+            const computedStyle = window.getComputedStyle(element)
+
+            const newSizeInfo: PanelSizeInfo = {
+                width: Math.round(rect.width),
+                height: Math.round(rect.height),
+                x: Math.round(rect.left),
+                y: Math.round(rect.top),
+                minHeight: computedStyle.minHeight || "auto",
+                maxHeight: computedStyle.maxHeight || "none",
+            }
+
+            const previousSize = previousSizesRef.current[panelId]
+            // オブジェクトの各キーを比較して、変更があった場合のみ更新
+            if (!previousSize || (Object.keys(newSizeInfo) as Array<keyof PanelSizeInfo>).some((key) => previousSize[key] !== newSizeInfo[key])) {
+                previousSizesRef.current[panelId] = newSizeInfo
+                setPanelSizes((prevSizes) => ({
+                    ...prevSizes,
+                    [panelId]: newSizeInfo,
+                }))
+            }
+        },
+        [], // setPanelSizes は React の state セッターなので依存配列に含める必要はありません
+    )
+
+    /**
+     * Updates a panel's size information。
+     * パネルのサイズ情報を更新します。
+     * @param {string} panelId - The ID of the panel to update。
+     */
+    const updatePanelSize = useCallback(
+        (panelId: string) => {
+            const element = getPanelElement(panelId)
+            if (element) {
+                _updateSize(panelId, element)
+            }
+        },
+        [getPanelElement, _updateSize],
+    )
+
+    /**
+     * Sets a panel's ref and updates its size information。
+     * パネルのrefを設定し、サイズ情報を更新します。
+     * @param {string} panelId - The ID of the panel。
+     * @param {HTMLDivElement | null} el - The panel element。
+     */
+    const setPanelRef = useCallback(
+        (panelId: string, el: HTMLDivElement | null) => {
+            if (el) {
+                // パネル要素がマウントされた際にサイズ情報を更新（requestAnimationFrameを使用して最適化）
+                requestAnimationFrame(() => _updateSize(panelId, el))
+            }
+        },
+        [_updateSize],
+    )
+
+    /**
+     * Creates and displays a visual clone (drag image) for dragging。
+     * ドラッグ用の視覚的なクローン（ドラッグイメージ）を作成して表示します。
+     * @param {string} panelId - The ID of the panel to clone。
+     * @param {number} offsetX - The horizontal offset of the mouse from the panel's left edge。
+     * @param {number} offsetY - The vertical offset of the mouse from the panel's top edge。
+     */
+    const createDragImage = useCallback(
+        (panelId: string, offsetX: number, offsetY: number) => {
+            const originalElement = getPanelElement(panelId)
+            if (!originalElement || dragImageRef.current) return
+
+            const currentScale = scaleRef.current
+            const rect = originalElement.getBoundingClientRect()
+            const clone = originalElement.cloneNode(true) as HTMLElement
+
+            // data-panel-id を除去する (getPanelElement の querySelector が DOM 上のクローンを
+            // 誤ってヒットしないように。id は下部で drag-image-<id> に上書きするため重複しない)
+            clone.removeAttribute("data-panel-id")
+
+            // Style the clone to be a "ghost" image
+            clone.style.position = "fixed"
+            clone.style.top = "0px"
+            clone.style.left = "0px"
+            // レイアウト原寸 (offsetWidth/Height) を使う。getBoundingClientRect は縮小ラッパ配下では
+            // 既に ×scale された値を返すため、それを幅に使うと transform:scale で二重縮小 (scale²) になる。
+            clone.style.width = `${originalElement.offsetWidth}px`
+            clone.style.height = `${originalElement.offsetHeight}px`
+            clone.style.pointerEvents = "none"
+            clone.style.zIndex = "1000"
+            clone.style.opacity = "0.5"
+            clone.style.margin = "0"
+            clone.style.transition = "none" // Disable transitions during drag for smooth tracking
+            clone.style.boxShadow = "0 8px 32px rgba(0,0,0,0.3)"
+            // transform-origin を top-left に固定 (既定の center だと縮小時に位置がずれる)
+            clone.style.transformOrigin = "top left"
+            clone.style.transform = `translate(${rect.left}px, ${rect.top}px) scale(${currentScale})`
+            clone.id = `drag-image-${panelId}` // Avoid duplicate IDs
+
+            document.body.appendChild(clone)
+            dragImageRef.current = clone
+            dragImageOffset.current = { x: offsetX, y: offsetY }
+        },
+        [getPanelElement],
+    )
+
+    /**
+     * Updates the position of the drag image to follow the mouse cursor。
+     * ドラッグイメージの位置をマウスカーソルに追従させます。
+     * @param {number} x - The current horizontal mouse coordinate。
+     * @param {number} y - The current vertical mouse coordinate。
+     */
+    const updateDragImagePosition = useCallback((x: number, y: number) => {
+        if (dragImageRef.current) {
+            const newX = x - dragImageOffset.current.x
+            const newY = y - dragImageOffset.current.y
+            // 掴んだ瞬間の scale(currentScale) から 5% だけ拡大して「持ち上げ」感を出す (top-left 原点は create 時に設定済み)
+            dragImageRef.current.style.transform = `translate(${newX}px, ${newY}px) scale(${scaleRef.current * 1.05})`
+        }
+    }, [])
+
+    /**
+     * Removes the drag image from the DOM。
+     * ドラッグイメージをDOMから削除します。
+     */
+    const removeDragImage = useCallback(() => {
+        if (dragImageRef.current) {
+            dragImageRef.current.remove()
+            dragImageRef.current = null
+        }
+    }, [])
+
+    /**
+     * Toggles the visibility of a specific panel。
+     * 特定のパネルの可視性を切り替えます。
+     * @param {string} panelId - The ID of the panel to toggle。
+     */
+    const togglePanelVisibility = useCallback((panelId: string) => {
+        setPanelVisibility((prev) => ({
+            ...prev,
+            [panelId]: !prev[panelId],
+        }))
+    }, [])
+
+    return {
+        // State / 状態
+        panelVisibility,
+        panelSizes,
+
+        // State update functions / 状態更新関数
+        setPanelVisibility,
+        setPanelSizes,
+        setPanelRef,
+        updatePanelSize,
+        togglePanelVisibility,
+
+        // Utility functions / ユーティリティ関数
+        getPanelElement,
+
+        // Functions for drag image management / ドラッグイメージ管理用の関数
+        createDragImage,
+        updateDragImagePosition,
+        removeDragImage,
+    }
+}

package/src/drag-drop/hooks/useResponsiveColumns.ts

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview This file defines the `useResponsiveColumns` custom hook, which calculates
+ * the optimal number of columns to display based on the screen width and provided constraints.
+ * It allows for a responsive layout that adapts to different screen sizes.
+ *
+ * このファイルは `useResponsiveColumns` カスタムフックを定義します。これは、画面の幅と
+ * 提供された制約に基づいて表示する最適なカラム数を計算します。これにより、さまざまな
+ * 画面サイズに適応するレスポンシブレイアウトが可能になります。
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+
+/**
+ * Props for the `useResponsiveColumns` hook.
+ * `useResponsiveColumns` フックのプロパティ。
+ */
+export interface UseResponsiveColumnsProps {
+    /** The minimum width for each column in pixels. / 各カラムの最小幅（ピクセル単位）。 */
+    minColumnWidth?: number
+    /** The default number of columns to display when not in responsive mode. / レスポンシブモードでない場合に表示するデフォルトのカラム数。 */
+    defaultColumns?: number
+    /** The maximum number of columns allowed. / 許容される最大カラム数。 */
+    maxColumns?: number
+    /** The minimum number of columns allowed. / 許容される最小カラム数。 */
+    minColumns?: number
+    /** The current column widths to consider for responsive calculation. / レスポンシブ計算で考慮する現在のカラム幅。 */
+    currentColumnWidths?: Record<string, number>
+}
+
+/**
+ * The return value of the `useResponsiveColumns` hook.
+ * `useResponsiveColumns` フックの戻り値。
+ */
+export interface UseResponsiveColumnsReturn {
+    /** The calculated number of columns for the current screen width. / 現在の画面幅に対して計算されたカラム数。 */
+    responsiveColumnCount: number
+    /** A boolean indicating if responsive mode is currently active. / レスポンシブモードが現在アクティブかどうかを示すブール値。 */
+    isResponsiveMode: boolean
+    /** The current width of the screen in pixels. / 現在の画面幅（ピクセル単位）。 */
+    screenWidth: number
+    /** A function to toggle responsive mode on and off. / レスポンシブモードのオン/オフを切り替える関数。 */
+    toggleResponsiveMode: () => void
+}
+
+/**
+ * A custom hook that determines the number of columns for a responsive layout.
+ * It listens to screen resize events and calculates the column count based on the available width.
+ *
+ * レスポンシブレイアウトのカラム数を決定するカスタムフック。
+ * 画面のリサイズイベントをリッスンし、利用可能な幅に基づいてカラム数を計算します。
+ * @param {UseResponsiveColumnsProps} [props={}] - Configuration properties for the hook.
+ * @returns {UseResponsiveColumnsReturn} An object containing the calculated column count and related state.
+ */
+export const useResponsiveColumns = ({ minColumnWidth = 350, defaultColumns = 3, maxColumns = 6, minColumns = 1, currentColumnWidths = {} }: UseResponsiveColumnsProps = {}): UseResponsiveColumnsReturn => {
+    /**
+     * State to store the current width of the browser window.
+     * ブラウザウィンドウの現在の幅を格納するstate。
+     */
+    const [screenWidth, setScreenWidth] = useState(0)
+    const lastViewportWidthRef = useRef<number>(0)
+    const animationFrameIdRef = useRef<number | null>(null)
+    /**
+     * State to toggle the responsive calculation logic.
+     * レスポンシブ計算ロジックを切り替えるためのstate。
+     */
+    const [isResponsiveMode, setIsResponsiveMode] = useState(false)
+
+    /**
+     * A ref to store the last calculated column count. This helps stabilize the return value
+     * of `responsiveColumnCount` by preventing changes if the new calculation results in the same number.
+     *
+     * 最後に計算されたカラム数を格納するref。これにより、新しい計算が同じ数値になった場合に
+     * 変更を防ぎ、`responsiveColumnCount` の戻り値を安定させます。
+     */
+    const responsiveColumnCountRef = useRef(defaultColumns)
+
+    // 画面リサイズリスナーをセットアップおよびクリーンアップする effect
+    useEffect(() => {
+        if (typeof window === "undefined") {
+            return
+        }
+
+        const computeViewportWidth = () => {
+            const visualViewportWidth = window.visualViewport?.width ?? 0
+            const documentElementWidth = document?.documentElement?.clientWidth ?? 0
+            const bodyWidth = document?.body?.clientWidth ?? 0
+            const innerWidth = window.innerWidth ?? 0
+
+            if (documentElementWidth > 0) {
+                return Math.floor(documentElementWidth)
+            }
+
+            if (visualViewportWidth > 0) {
+                return Math.floor(visualViewportWidth)
+            }
+
+            if (bodyWidth > 0) {
+                return Math.floor(bodyWidth)
+            }
+
+            return Math.floor(innerWidth)
+        }
+
+        const updateScreenWidth = () => {
+            if (animationFrameIdRef.current !== null) {
+                cancelAnimationFrame(animationFrameIdRef.current)
+            }
+
+            animationFrameIdRef.current = requestAnimationFrame(() => {
+                const width = computeViewportWidth()
+                animationFrameIdRef.current = null
+                if (width === 0) {
+                    return
+                }
+
+                // Very small viewport fluctuations (e.g., scrollbar appear/disappear) are ignored to prevent layout thrashing.
+                if (Math.abs(lastViewportWidthRef.current - width) < 2) {
+                    return
+                }
+
+                lastViewportWidthRef.current = width
+                setScreenWidth(width)
+            })
+        }
+
+        updateScreenWidth()
+
+        window.addEventListener("resize", updateScreenWidth)
+        window.addEventListener("orientationchange", updateScreenWidth)
+        window.visualViewport?.addEventListener("resize", updateScreenWidth)
+
+        return () => {
+            if (animationFrameIdRef.current !== null) {
+                cancelAnimationFrame(animationFrameIdRef.current)
+            }
+            window.removeEventListener("resize", updateScreenWidth)
+            window.removeEventListener("orientationchange", updateScreenWidth)
+            window.visualViewport?.removeEventListener("resize", updateScreenWidth)
+        }
+    }, [])
+
+    /**
+     * Calculates the number of columns to display.
+     * This calculation is memoized with `useMemo` to avoid re-computation on every render
+     * unless its dependencies (`isResponsiveMode`, `screenWidth`, etc.) change.
+     *
+     * 表示するカラム数を計算します。
+     * この計算は `useMemo` でメモ化され、依存関係（`isResponsiveMode`、`screenWidth`など）が
+     * 変更されない限り、再レンダリングごとに再計算されるのを防ぎます。
+     */
+    const responsiveColumnCount = useMemo(() => {
+        // レスポンシブモードでない場合、または画面幅が未設定の場合はデフォルト値を返す
+        if (!isResponsiveMode || screenWidth === 0) {
+            responsiveColumnCountRef.current = defaultColumns
+            return defaultColumns
+        }
+
+        // パディングとギャップを考慮して利用可能な幅を計算する
+        const availableWidth = Math.max(screenWidth - 64, 0) // Tailwind の px-8（32px × 2）を想定
+        const gapWidth = 24 // Tailwind の gap-6（24px）を想定
+
+        // 実際のカラム幅を使用してカラム数を計算
+        const actualWidths = Object.values(currentColumnWidths)
+
+        let columns: number
+
+        if (actualWidths.length > 0) {
+            // 手動調整されたカラム幅がある場合はそれを基準に計算
+            const averageWidth = actualWidths.reduce((sum, width) => sum + width, 0) / actualWidths.length
+            const effectiveMinWidth = Math.max(minColumnWidth, averageWidth)
+
+            columns = Math.floor((availableWidth + gapWidth) / (effectiveMinWidth + gapWidth))
+
+            // 実際の幅の合計でも確認
+            const totalCurrentWidth = actualWidths.reduce((sum, width) => sum + width, 0) + (actualWidths.length - 1) * gapWidth
+            if (totalCurrentWidth > availableWidth && actualWidths.length > minColumns) {
+                // 現在の幅が画面幅を超える場合はカラム数を減らす
+                columns = Math.min(columns, actualWidths.length - 1)
+            }
+        } else {
+            // デフォルトの最小幅を使用
+            columns = Math.floor((availableWidth + gapWidth) / (minColumnWidth + gapWidth))
+        }
+
+        // 最小および最大カラム数の制約を適用
+        columns = Math.max(minColumns, Math.min(maxColumns, columns))
+
+        // カウントが変更されていない場合は前の値を返して参照を安定させる
+        if (responsiveColumnCountRef.current === columns) {
+            return responsiveColumnCountRef.current
+        }
+
+        responsiveColumnCountRef.current = columns
+        return columns
+    }, [isResponsiveMode, screenWidth, defaultColumns, minColumnWidth, maxColumns, minColumns, currentColumnWidths])
+
+    /**
+     * A memoized function to toggle the responsive mode.
+     * レスポンシブモードを切り替えるためのメモ化された関数。
+     */
+    const toggleResponsiveMode = useCallback(() => {
+        setIsResponsiveMode((prev) => !prev)
+    }, [])
+
+    return {
+        responsiveColumnCount,
+        isResponsiveMode,
+        screenWidth,
+        toggleResponsiveMode,
+    }
+}

package/src/drag-drop/resize-handle.css

@@ -0,0 +1,71 @@
+/* リサイズハンドルの基礎レイアウトとカーソル指定 */
+.resize-handle {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 12px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: col-resize;
+  z-index: 10;
+  transition: background-color 0.2s ease;
+}
+
+/* 右側ハンドルの配置を決定 */
+.resize-handle.right {
+  right: -6px;
+}
+
+/* 左側ハンドルの配置を決定 */
+.resize-handle.left {
+  left: -6px;
+}
+
+/* ホバーやドラッグ時に背景色を強調 */
+.resize-handle.resizing,
+.resize-handle:hover {
+  background-color: rgba(0, 0, 0, 0.05);
+}
+
+/* ハンドルバー本体の見た目を定義 */
+.resize-handle-bar {
+  width: 2px;
+  height: 40px;
+  background-color: rgba(99, 102, 241, 0.5);
+  border-radius: 999px;
+}
+
+/* ドラッグ中のハンドルバーを強調表示 */
+.resize-handle.resizing .resize-handle-bar {
+  background-color: rgba(99, 102, 241, 0.9);
+  box-shadow: 0 0 6px rgba(99, 102, 241, 0.6);
+}
+
+/* デバッグ情報ラベルの位置とスタイル */
+.resize-handle-debug-info {
+  position: absolute;
+  bottom: 8px;
+  left: 50%;
+  transform: translateX(-50%);
+  background: rgba(30, 64, 175, 0.85);
+  color: white;
+  padding: 4px 8px;
+  border-radius: 4px;
+  font-size: 11px;
+  white-space: nowrap;
+  pointer-events: none;
+}
+
+/* カラム幅デバッグ表示のスタイル */
+.column-debug-size {
+  position: absolute;
+  top: 8px;
+  right: 12px;
+  background: rgba(30, 64, 175, 0.85);
+  color: white;
+  padding: 4px 8px;
+  border-radius: 4px;
+  font-size: 11px;
+  pointer-events: none;
+}