@aiquants/resize-panels 2.0.0 → 2.0.1

package/src/hooks.ts

@@ -1,376 +0,0 @@
-/**
- * @file Custom hooks for resizable panels logic
- * リサイズ可能パネルのロジックのためのカスタムフック
- *
- * The hook owns everything the reducer cannot: it measures the container, keeps the panel order in step
- * with the DOM, and forwards user intent as actions. It never computes a panel size itself.
- * フックはリデューサーが担えない役割だけを持つ: コンテナの計測、DOM 順との同期、利用者の意図のアクション化。
- * パネルサイズ自体はここでは一切計算しない。
- */
-
-import { type CSSProperties, useCallback, useEffect, useLayoutEffect, useMemo, useReducer, useRef, useState } from "react"
-import { usePanelGroup } from "./context"
-import { getPanelPreferenceInPixels, initialPanelGroupLayoutState, panelReducer } from "./reducer"
-import type { PanelCollapseDirection, PanelGroupProps, PanelMeasurement, PanelRegistration, PersistedPanelSize, ResizeHandleLayoutData } from "./types"
-import { getContainerSize, getGroupLayoutElements, loadLayout, saveLayout, touchesLayoutElements } from "./utils"
-import { Logger, LogLevel } from "./utils/simple-logger"
-
-const logger = new Logger(LogLevel.INFO, "[resize-panels]")
-
-/**
- * Delay before the layout is written to storage, in milliseconds.
- * レイアウトを保存領域へ書き出すまでの待機時間 (ms)。
- */
-const AUTO_SAVE_DELAY_MS = 200
-
-/**
- * Placeholder that stands for a handle anchor in the group's DOM-order key.
- * グループの DOM 順を表す鍵の中で、ハンドルのアンカーを表す標識。
- */
-const HANDLE_ANCHOR_ORDER_MARK = "\u0000handle"
-
-/**
- * Orchestrate measurement, ordering, persistence and user intent for one panel group.
- * 1 つのパネルグループにおける計測・順序同期・永続化・利用者操作の統括。
- *
- * @param props - Panel group props / パネルグループのプロパティ
- * @returns Group ref, context value and the group's base style / グループ ref・コンテキスト値・基準スタイル
- */
-export const useResizablePanels = ({ direction, style, onLayout, autoSaveId, showDebugInfo = false }: PanelGroupProps) => {
-    const [layout, dispatch] = useReducer(panelReducer, initialPanelGroupLayoutState)
-    const [panelMeasurements, setPanelMeasurements] = useState<Record<string, PanelMeasurement>>({})
-    const [handleMeasurements, setHandleMeasurements] = useState<Record<string, ResizeHandleLayoutData>>({})
-
-    const groupRef = useRef<HTMLDivElement>(null)
-    const [layoutOrderKey, setLayoutOrderKey] = useState("")
-    const registrationSignaturesRef = useRef<Record<string, string>>({})
-    const layoutCallbackRef = useRef(onLayout)
-    layoutCallbackRef.current = onLayout
-
-    useLayoutEffect(() => {
-        // ResizeObserver でグループの内容領域長を追跡する。観測値は丸めも遅延もせずそのまま確定させる:
-        // 端数を落とすと、状態が持つ長さと描画される長さがずれたままになる。
-        // 主軸の長さが動かないフレーム (交差軸だけのリサイズ) はここで捨てる。reducer は同一状態を
-        // 返すものの、dispatch 自体がレンダーを予約してしまうため
-        const element = groupRef.current
-        if (!element || typeof ResizeObserver === "undefined") {
-            return
-        }
-
-        let lastContent = Number.NaN
-        const commitContentLength = (content: number) => {
-            if (content === lastContent) {
-                return
-            }
-            lastContent = content
-            dispatch({ type: "SET_CONTAINER_SIZE", containerSize: content })
-        }
-
-        const observer = new ResizeObserver((entries) => {
-            commitContentLength(getContainerSize(element, direction, entries[0]).content)
-        })
-
-        observer.observe(element)
-        // 初回描画を正しい配分で塗るための種。観測が届いた時点で厳密値へ置き換わる
-        commitContentLength(getContainerSize(element, direction).content)
-
-        return () => {
-            observer.disconnect()
-        }
-    }, [direction])
-
-    const panels = layout.panels
-    const panelsRef = useRef(panels)
-    panelsRef.current = panels
-
-    const syncPanelOrder = useCallback(() => {
-        // パネルは DOM 順に並んでいることが前提の状態 (保存・onLayout・優先度の同順位比較) なので、
-        // 登録順と DOM 順がずれたら DOM 側へ合わせ直す
-        const element = groupRef.current
-        const currentPanels = panelsRef.current
-        if (!element) {
-            return
-        }
-        const layoutElements = getGroupLayoutElements(element)
-        // ハンドルが別の境界へ移っただけの並べ替えはパネルの id 列を変えない。
-        // アンカーの位置も含めた並びを鍵にして、ハンドル側の再検出も同じ変化で起こす
-        setLayoutOrderKey((previous) => {
-            const next = layoutElements.map((layoutElement) => layoutElement.dataset.panelId ?? HANDLE_ANCHOR_ORDER_MARK).join("\u0000")
-            return previous === next ? previous : next
-        })
-        if (currentPanels.length === 0) {
-            return
-        }
-        const ids: string[] = []
-        for (const layoutElement of layoutElements) {
-            const id = layoutElement.dataset.panelId
-            if (id !== undefined) {
-                ids.push(id)
-            }
-        }
-        if (new Set(ids).size !== ids.length) {
-            // 同じ id のパネルが同時に存在すると 1 つの状態を 2 枚が描画し、合計がコンテナを超える
-            logger.error("Duplicate panel id in one group.", { ids })
-            return
-        }
-        if (ids.length !== currentPanels.length || ids.every((id, index) => id === currentPanels[index].id)) {
-            return
-        }
-        dispatch({ type: "REORDER_PANELS", ids })
-    }, [])
-
-    useLayoutEffect(() => {
-        // 並べ替えは登録・解除を伴わないことがある (JSX 上の順序だけを入れ替えた場合など)。
-        // 状態の変化を待つと取りこぼすため、DOM の子要素の変化そのものを監視する
-        const element = groupRef.current
-        if (!element) {
-            return
-        }
-        syncPanelOrder()
-        if (typeof MutationObserver === "undefined") {
-            return
-        }
-        const observer = new MutationObserver((records) => {
-            // 配置要素に触れない変更は無視する。パネルの内容 (仮想化リストの行など) は毎フレーム
-            // 入れ替わるため、すべての変更で走査するとグループ全体に比例した費用を払い続ける
-            if (touchesLayoutElements(records)) {
-                syncPanelOrder()
-            }
-        })
-        // 中間要素の中での並べ替えも拾うため subtree ごと監視する
-        observer.observe(element, { childList: true, subtree: true })
-        return () => {
-            observer.disconnect()
-        }
-    }, [syncPanelOrder])
-
-    useLayoutEffect(() => {
-        syncPanelOrder()
-    }, [syncPanelOrder, panels])
-
-    const panelSizes = useMemo(() => panels.map((panel) => panel.size), [panels])
-    const hasMeasuredContainer = layout.containerSize > 0
-
-    useLayoutEffect(() => {
-        // 未計測の 0 配列を通知しない。配分はコンテナ計測後に一度で確定するため、通知は常に確定値になる
-        if (!hasMeasuredContainer || panelSizes.length === 0) {
-            return
-        }
-        layoutCallbackRef.current?.(panelSizes)
-    }, [panelSizes, hasMeasuredContainer])
-
-    const restoredKeyRef = useRef<string | null>(null)
-    useEffect(() => {
-        // 保存済みレイアウトは識別子ごとに一度だけ適用する
-        // (識別子が変われば、その識別子で保存された配置を読み直す)
-        if (!autoSaveId || restoredKeyRef.current === autoSaveId || !hasMeasuredContainer || panels.length === 0) {
-            return
-        }
-        restoredKeyRef.current = autoSaveId
-        const entries = loadLayout(autoSaveId)
-        if (entries) {
-            dispatch({ type: "RESTORE_LAYOUT", entries })
-        }
-    }, [autoSaveId, hasMeasuredContainer, panels.length])
-
-    const pendingSaveRef = useRef<{ id: string; entries: PersistedPanelSize[] } | null>(null)
-    useEffect(() => {
-        if (!(autoSaveId && restoredKeyRef.current === autoSaveId && hasMeasuredContainer) || panels.length === 0) {
-            return
-        }
-        const entries = panels.map((panel) => ({ id: panel.id, size: getPanelPreferenceInPixels(panel, layout.containerSize), collapsed: panel.collapsed }))
-        pendingSaveRef.current = { id: autoSaveId, entries }
-        const timer = setTimeout(() => {
-            pendingSaveRef.current = null
-            saveLayout(autoSaveId, entries)
-        }, AUTO_SAVE_DELAY_MS)
-        // ここで保存まで行うと、ドラッグやリサイズの 1 フレームごとに同期 I/O が走り、待機時間が無意味になる
-        return () => {
-            clearTimeout(timer)
-        }
-    }, [autoSaveId, panels, layout.containerSize, hasMeasuredContainer])
-
-    useEffect(() => {
-        // 書き出し前に画面を離れた場合でも最後の配置を残す (遷移直前に動かした幅が消えないように)
-        return () => {
-            const pending = pendingSaveRef.current
-            if (pending) {
-                pendingSaveRef.current = null
-                saveLayout(pending.id, pending.entries)
-            }
-        }
-    }, [])
-
-    const registerPanel = useCallback((panel: PanelRegistration) => {
-        // 同一内容の再登録は状態を触らない。props が変わっていないのに希望値を配り直すと、
-        // 直前のドラッグ結果を巻き戻してしまう
-        const signature = JSON.stringify(panel)
-        if (registrationSignaturesRef.current[panel.id] === signature) {
-            return
-        }
-        registrationSignaturesRef.current[panel.id] = signature
-        dispatch({ type: "REGISTER_PANEL", panel })
-    }, [])
-
-    const unregisterPanel = useCallback((id: string) => {
-        delete registrationSignaturesRef.current[id]
-        dispatch({ type: "UNREGISTER_PANEL", id })
-        setPanelMeasurements((previous) => {
-            if (!(id in previous)) {
-                return previous
-            }
-            const next = { ...previous }
-            delete next[id]
-            return next
-        })
-    }, [])
-
-    const resizePanels = useCallback((startId: string, endId: string, startSize: number) => {
-        dispatch({ type: "RESIZE_PANELS", startId, endId, startSize })
-    }, [])
-
-    const collapsePanel = useCallback((id: string, from: PanelCollapseDirection) => {
-        dispatch({ type: "COLLAPSE_PANEL", id, from })
-    }, [])
-
-    const expandPanel = useCallback((id: string, from: PanelCollapseDirection, targetSize?: number) => {
-        dispatch({ type: "EXPAND_PANEL", id, from, targetSize })
-    }, [])
-
-    const getPanel = useCallback((id: string) => panels.find((panel) => panel.id === id), [panels])
-
-    const reportPanelMeasurement = useCallback((panelId: string, measurement: PanelMeasurement | null) => {
-        setPanelMeasurements((previous) => {
-            if (measurement === null) {
-                if (!(panelId in previous)) {
-                    return previous
-                }
-                const next = { ...previous }
-                delete next[panelId]
-                return next
-            }
-            const current = previous[panelId]
-            if (current && current.pixelSize === measurement.pixelSize && current.percentageSize === measurement.percentageSize) {
-                return previous
-            }
-            return { ...previous, [panelId]: measurement }
-        })
-    }, [])
-
-    const reportHandleMeasurement = useCallback((handleId: string, measurement: ResizeHandleLayoutData | null) => {
-        setHandleMeasurements((previous) => {
-            if (measurement === null) {
-                if (!(handleId in previous)) {
-                    return previous
-                }
-                const next = { ...previous }
-                delete next[handleId]
-                return next
-            }
-            const current = previous[handleId]
-            if (current && current.thickness === measurement.thickness && current.visible === measurement.visible && current.direction === measurement.direction && current.startPanelId === measurement.startPanelId && current.endPanelId === measurement.endPanelId) {
-                return previous
-            }
-            return { ...previous, [handleId]: measurement }
-        })
-    }, [])
-
-    const contextValue = useMemo(
-        () => ({
-            direction,
-            panels,
-            containerSize: layout.containerSize,
-            layoutOrderKey,
-            showDebugInfo,
-            registerPanel,
-            unregisterPanel,
-            resizePanels,
-            collapsePanel,
-            expandPanel,
-            getPanel,
-            reportPanelMeasurement,
-            panelMeasurements,
-            reportHandleMeasurement,
-            handleMeasurements,
-            layoutConstraintViolation: layout.violation,
-        }),
-        [direction, panels, layout.containerSize, layoutOrderKey, layout.violation, showDebugInfo, registerPanel, unregisterPanel, resizePanels, collapsePanel, expandPanel, getPanel, reportPanelMeasurement, panelMeasurements, reportHandleMeasurement, handleMeasurements],
-    )
-
-    const groupStyle: CSSProperties = useMemo(
-        () => ({
-            // 見た目に関わる既定値は利用者が上書きできる
-            width: "100%",
-            height: "100%",
-            minWidth: "0px",
-            minHeight: "0px",
-            // ハンドルは境界をまたいで描かれるため、その張り出しでスクロールバーを出さない
-            overflow: "hidden",
-            ...style,
-            // ここから下はレイアウトの前提そのもの。利用者のスタイルやクラスで変わると
-            // 配分結果と描画が一致しなくなるため、最後に適用して上書きを受け付けない:
-            // gap はパネルの合計に含まれない隙間を作り、flex-direction の反転は DOM 順と視覚順をずらし、
-            // writing-mode は主軸の向きそのものを変えてしまう
-            display: "flex",
-            flexDirection: direction === "horizontal" ? "row" : "column",
-            alignItems: "stretch",
-            gap: "0px",
-            position: "relative",
-            boxSizing: "border-box",
-            writingMode: "horizontal-tb",
-        }),
-        [direction, style],
-    )
-
-    return { groupRef, contextValue, groupStyle }
-}
-
-/**
- * Provide imperative helpers for toggling a specific panel while preserving its stored preference.
- * 特定パネルの希望値を保ったまま開閉を制御する命令型ユーティリティを提供するカスタムフック。
- *
- * @param panelId - Identifier of the panel to control / 操作対象パネルの識別子
- * @returns Panel state and collapse/expand/toggle helpers / パネル状態と開閉ヘルパー
- */
-export const usePanelControls = (panelId: string) => {
-    const { getPanel, collapsePanel, expandPanel } = usePanelGroup()
-    const panel = getPanel(panelId)
-
-    const collapse = useCallback(
-        (from: PanelCollapseDirection) => {
-            collapsePanel(panelId, from)
-        },
-        [collapsePanel, panelId],
-    )
-
-    const expand = useCallback(
-        (from: PanelCollapseDirection, targetSize?: number) => {
-            expandPanel(panelId, from, targetSize)
-        },
-        [expandPanel, panelId],
-    )
-
-    const toggle = useCallback(
-        (from: PanelCollapseDirection, targetSize?: number) => {
-            if (panel?.collapsed) {
-                expand(from, targetSize)
-            } else {
-                collapse(from)
-            }
-        },
-        [panel?.collapsed, collapse, expand],
-    )
-
-    return useMemo(
-        () => ({
-            panel,
-            isCollapsed: panel?.collapsed ?? false,
-            canCollapseFromStart: panel?.collapseFromStart ?? false,
-            canCollapseFromEnd: panel?.collapseFromEnd ?? false,
-            collapse,
-            expand,
-            toggle,
-        }),
-        [panel, collapse, expand, toggle],
-    )
-}

package/src/index.ts

@@ -1,93 +0,0 @@
-/**
- * @package @aiquants/resize-panels
- * @description Reusable resizable panel components and utilities for React
- *
- * 再利用可能なリサイズパネルコンポーネントとユーティリティ
- */
-
-export type { LayoutAllocation, PanelBounds } from "./allocateLayout"
-export { allocatePanelSizes, isPixelPanel, resolvePanelBounds } from "./allocateLayout"
-export { PanelGroupContext, usePanelGroup } from "./context"
-export { usePanelControls, useResizablePanels } from "./hooks"
-export { Panel } from "./Panel"
-export { PanelGroup } from "./PanelGroup"
-export { PanelResizeHandle } from "./PanelResizeHandle"
-export { findLayoutInvariantBreach, getPanelPreferenceInPixels, initialPanelGroupLayoutState, panelReducer } from "./reducer"
-export type {
-    CollapsibleConfig,
-    CollapsibleDirection,
-    ContainerAxisMeasurement,
-    FlexibleSize,
-    LayoutConstraintViolation,
-    LayoutConstraintViolationReason,
-    PanelAction,
-    PanelCollapseDirection,
-    PanelDirection,
-    PanelGroupContextValue,
-    PanelGroupLayoutState,
-    PanelGroupProps,
-    PanelLayoutData,
-    PanelMeasurement,
-    PanelProps,
-    PanelRegistration,
-    PanelResizeHandleIndicatorConfig,
-    PanelResizeHandleProps,
-    PersistedPanelSize,
-    ResizeHandleLayoutData,
-    SizeConfig,
-    SizeUnit,
-} from "./types"
-export {
-    calculateSnapThreshold,
-    clamp,
-    findOwningGroup,
-    getConstraintInPixels,
-    getContainerSize,
-    getGroupLayoutElements,
-    loadLayout,
-    normalizeSizeConfig,
-    percentageToPixels,
-    saveLayout,
-    toRoundedPercentage,
-} 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 => {
-    if (typeof document === "undefined") {
-        return null
-    }
-    return document.querySelector(`[data-panel-id="${escapeIdentifier(id)}"]`)
-}
-
-/**
- * Locate a panel group element in the DOM by its data attribute.
- * data 属性を手がかりにパネルグループ要素を DOM から取得する補助関数。
- */
-export const getPanelGroupElement = (id: string): HTMLElement | null => {
-    if (typeof document === "undefined") {
-        return null
-    }
-    return document.querySelector(`[data-panel-group-id="${escapeIdentifier(id)}"]`)
-}
-
-/**
- * Locate a resize handle element in the DOM by its data attribute.
- * data 属性を手がかりにリサイズハンドル要素を DOM から取得する補助関数。
- */
-export const getResizeHandleElement = (id: string): HTMLElement | null => {
-    if (typeof document === "undefined") {
-        return null
-    }
-    return document.querySelector(`[data-resize-handle-id="${escapeIdentifier(id)}"]`)
-}