@aiquants/resize-panels 2.0.0 → 2.0.1

package/src/utils.ts

@@ -1,320 +0,0 @@
-/**
- * @file Utility functions for custom resizable panels
- * カスタムリサイズ可能パネルのためのユーティリティ関数
- */
-
-import { roundHalfToEven } from "./roundHalfToEven"
-import { type ContainerAxisMeasurement, type FlexibleSize, PANEL_COLLAPSE_THRESHOLD_MAX, PANEL_COLLAPSE_THRESHOLD_RATIO, PANEL_SNAP_THRESHOLD, type PanelDirection, type PersistedPanelSize, type SizeConfig, type SizeUnit } from "./types"
-
-/**
- * Number of significant fractional digits to preserve when rounding percentage-based sizes.
- * パーセンテージサイズの丸めで保持する有効小数桁数。
- */
-export const PERCENTAGE_DIGITS = 6
-
-/**
- * Convert a pixel measurement to a percentage of the container using banker's rounding.
- * ピクセル寸法をバンカーズラウンディングでコンテナ比率のパーセンテージへ変換する。
- *
- * @param size - Length in pixels / 長さ (px)
- * @param base - Container length the percentage is relative to / 基準となるコンテナ長
- * @returns Percentage of the container, 0 when the base is not positive / コンテナ比 (%)、基準が非正なら 0
- */
-export const toRoundedPercentage = (size: number, base: number): number => {
-    if (base <= 0) {
-        return 0
-    }
-    return roundHalfToEven((size / base) * 100, PERCENTAGE_DIGITS)
-}
-
-/**
- * Translate a percentage-based size back into pixels relative to the container.
- * パーセンテージ指定のサイズをコンテナ基準のピクセル値へ変換する。
- *
- * @param percentage - Share of the container in percent / コンテナ比 (%)
- * @param base - Container length the percentage is relative to / 基準となるコンテナ長
- * @returns Length in pixels / 長さ (px)
- */
-export const percentageToPixels = (percentage: number, base: number): number => {
-    if (base <= 0) {
-        return 0
-    }
-    return (percentage / 100) * base
-}
-
-/**
- * Normalize a flexible size into a size configuration object.
- * 柔軟なサイズ指定をサイズ設定オブジェクトへ正規化する。
- *
- * @param size - Author-provided size / 利用者が指定したサイズ
- * @param defaultUnit - Unit applied to bare numbers / 数値のみの指定に適用する単位
- * @returns Normalized configuration, or undefined when nothing was provided / 正規化後の設定、未指定なら undefined
- */
-export const normalizeSizeConfig = (size: FlexibleSize | undefined, defaultUnit: SizeUnit = "percentage"): SizeConfig | undefined => {
-    if (size === undefined) {
-        return undefined
-    }
-    if (typeof size === "number") {
-        return { value: size, unit: defaultUnit }
-    }
-    return size
-}
-
-/**
- * Convert flexible size constraints into pixel values based on container size.
- * 柔軟サイズ制約をコンテナサイズ基準のピクセル値へ変換する。
- *
- * @param size - Constraint to resolve; bare numbers are percentages / 解決する制約 (数値のみの指定はパーセンテージ)
- * @param defaultValue - Value used when the constraint is absent / 制約が無い場合の値
- * @param containerSize - Container content-box length / コンテナ内容領域長
- * @returns Constraint in pixels / ピクセル換算した制約
- */
-export const getConstraintInPixels = (size: FlexibleSize | undefined, defaultValue: number, containerSize: number): number => {
-    if (size === undefined) {
-        return defaultValue
-    }
-    if (typeof size === "number") {
-        return (size / 100) * containerSize
-    }
-    if (size.unit === "pixels") {
-        return size.value
-    }
-    return (size.value / 100) * containerSize
-}
-
-/**
- * Clamp a numeric value between the provided bounds.
- * 数値を指定した範囲に収めるためのクリッピング処理。
- *
- * @param value - Value to clamp / 収める値
- * @param min - Lower bound / 下限
- * @param max - Upper bound / 上限
- * @returns Clamped value / 範囲内へ収めた値
- */
-export const clamp = (value: number, min: number, max: number): number => {
-    return Math.min(Math.max(value, min), max)
-}
-
-/**
- * Derive a snap-to-zero threshold from the container axis length using shared heuristics.
- * 共通ヒューリスティクスに基づきコンテナ軸長からゼロスナップ閾値を算出する。
- *
- * @param axisSize - Container content-box length along the axis / 軸方向のコンテナ内容領域長
- * @returns Threshold in pixels below which a panel snaps closed / 閉じたとみなすピクセル閾値
- */
-export const calculateSnapThreshold = (axisSize: number): number => {
-    if (!Number.isFinite(axisSize) || axisSize <= 0) {
-        return 0
-    }
-    return Math.max(0, Math.min(PANEL_SNAP_THRESHOLD, PANEL_COLLAPSE_THRESHOLD_MAX, axisSize * PANEL_COLLAPSE_THRESHOLD_RATIO))
-}
-
-/**
- * Parse a CSS pixel string and return the numeric portion.
- * CSS ピクセル表現から数値を抽出する処理。
- */
-const parsePixelValue = (value: string | null | undefined): number => {
-    if (!value) {
-        return 0
-    }
-    const parsed = Number.parseFloat(value)
-    return Number.isFinite(parsed) ? parsed : 0
-}
-
-/**
- * Measure a container along one axis, returning its content-box and border-box lengths.
- * 指定軸でコンテナを計測し、内容領域長と境界領域長を返す処理。
- *
- * The content box is the authority for every layout number in this package: a panel's `flex-basis` resolves
- * against it, so the allocator must fill exactly this length for the rendered geometry and the reducer state
- * to agree. The measurement is therefore taken in LAYOUT pixels — `getBoundingClientRect` reports the visual
- * rect, so a scaled ancestor would otherwise make the group allocate a container it does not have.
- * このパッケージのレイアウト数値の基準は内容領域である。パネルの `flex-basis` はこの領域に解決されるため、
- * 描画結果とリデューサー状態を一致させるには配分器がこの長さを満たす必要がある。計測は**レイアウトピクセル**で
- * 行う: `getBoundingClientRect` は視覚上の矩形を返すため、拡大縮小された祖先の下では存在しない長さを配ってしまう。
- *
- * @param element - Element to measure / 計測対象の要素
- * @param direction - Axis to measure along / 計測する軸
- * @param entry - Observation that triggered the measurement, when it came from a ResizeObserver / 計測契機となった観測結果
- * @returns Content-box and border-box lengths in pixels / 内容領域長と境界領域長 (px)
- */
-export const getContainerSize = (element: HTMLElement, direction: PanelDirection, entry?: ResizeObserverEntry): ContainerAxisMeasurement => {
-    const isHorizontal = direction === "horizontal"
-    const styles = typeof window !== "undefined" ? window.getComputedStyle(element) : null
-    const padding = styles ? (isHorizontal ? parsePixelValue(styles.paddingLeft) + parsePixelValue(styles.paddingRight) : parsePixelValue(styles.paddingTop) + parsePixelValue(styles.paddingBottom)) : 0
-    const borders = styles ? (isHorizontal ? parsePixelValue(styles.borderLeftWidth) + parsePixelValue(styles.borderRightWidth) : parsePixelValue(styles.borderTopWidth) + parsePixelValue(styles.borderBottomWidth)) : 0
-
-    // ResizeObserver の内容ボックス寸法はレイアウトピクセルの厳密値なので、得られるときは最優先で使う
-    const observedContent = entry?.contentBoxSize?.[0]
-    const observed = observedContent ? (isHorizontal ? observedContent.inlineSize : observedContent.blockSize) : undefined
-    // clientWidth / clientHeight もレイアウトピクセルだが整数に丸められる。端数を持つコンテナのために
-    // 内容ボックス寸法を優先し、無い環境でのみこちらへ落とす
-    const clientLength = isHorizontal ? element.clientWidth : element.clientHeight
-    const fallback = clientLength > 0 ? Math.max(0, clientLength - padding) : Math.max(0, (isHorizontal ? element.offsetWidth : element.offsetHeight) - padding - borders)
-    const content = observed ?? fallback
-
-    return { content: Math.max(0, content), border: Math.max(0, content + padding + borders) }
-}
-
-/**
- * Selector that identifies a panel group element.
- * パネルグループ要素を特定するセレクタ。
- */
-const GROUP_SELECTOR = "[data-panel-group-direction]"
-
-/**
- * Selector that matches the elements a group lays out: its panels and its handle anchors.
- * グループが配置する要素 (パネルとハンドルのアンカー) に一致するセレクタ。
- */
-export const LAYOUT_ELEMENT_SELECTOR = "[data-panel-id], [data-resize-handle-anchor]"
-
-/**
- * Selector that matches a panel element.
- * パネル要素に一致するセレクタ。
- */
-const PANEL_SELECTOR = "[data-panel-id]"
-
-/**
- * Resolve the innermost panel group that owns an element.
- * ある要素を所有する最も内側のパネルグループを解決する処理。
- *
- * The owner is never simply the parent: a wrapper element (including `display: contents`, which flex layout
- * flattens away) sits between the group and its panels without changing the geometry, and nested groups make
- * "the closest group" the only answer that is right in both directions.
- * 所有者は単なる親要素ではない。中間要素 (フレックスレイアウトが畳む `display: contents` を含む) は幾何を
- * 変えずにグループとパネルの間へ入り込み、入れ子グループもあるため「最も近いグループ」だけが正解となる。
- *
- * @param element - Element to resolve the owner for / 所有者を解決する対象の要素
- * @returns Owning group element, or null when the element is outside every group / 所有するグループ要素、どのグループにも属さないなら null
- */
-export const findOwningGroup = (element: HTMLElement | null | undefined): HTMLElement | null => element?.closest<HTMLElement>(GROUP_SELECTOR) ?? null
-
-/**
- * Collect the panels and handle anchors a group owns, in document order.
- * グループが所有するパネルとハンドルのアンカーを、文書順で収集する処理。
- *
- * Direct children are not enough: a wrapper (including `display: contents`, which flex layout flattens away)
- * leaves the geometry intact while hiding the panels from a sibling scan, and the handle would silently lose
- * its neighbours.
- * 直下の子だけでは足りない。中間要素 (フレックスレイアウトが畳む `display: contents` を含む) があると幾何は
- * 保たれたままパネルが兄弟走査から消え、ハンドルが隣接パネルを見失う。
- *
- * @param group - Group element / グループ要素
- * @returns Owned panel and anchor elements in document order / 所有するパネル・アンカー要素 (文書順)
- */
-export const getGroupLayoutElements = (group: HTMLElement): HTMLElement[] =>
-    Array.from(group.querySelectorAll<HTMLElement>(LAYOUT_ELEMENT_SELECTOR)).filter((element) => {
-        if (findOwningGroup(element) !== group) {
-            return false
-        }
-        // `data-panel-id` は他パッケージも出力する。パネルの中に現れたものを配置要素と見なすと、
-        // ハンドルが本物の隣を見失って動かなくなる
-        const enclosingPanel = element.parentElement?.closest<HTMLElement>(PANEL_SELECTOR)
-        return !(enclosingPanel && group.contains(enclosingPanel))
-    })
-
-/**
- * Report whether a DOM mutation touched an element the group lays out.
- * DOM の変更がグループの配置要素に触れたかどうかを判定する処理。
- *
- * Content inside a panel changes constantly (a virtualised list recycles rows every frame), so a group-wide
- * rescan on every mutation costs time proportional to the whole subtree for changes that can never move a
- * panel. Only additions and removals that carry a layout element can.
- * パネルの内容は絶え間なく変わる (仮想化リストは毎フレーム行を入れ替える) ため、変更のたびにグループ全体を
- * 走査すると、パネルを動かしようのない変更に対して部分木全体に比例した時間を払う。配置要素を含む
- * 追加・削除だけがパネルを動かしうる。
- *
- * @param records - Mutation records delivered by the observer / オブザーバーが届けた変更記録
- * @returns True when at least one record added or removed a layout element / 配置要素の追加・削除が 1 件でもあれば true
- */
-export const touchesLayoutElements = (records: ReadonlyArray<MutationRecord>): boolean => {
-    const carriesLayoutElement = (nodes: NodeList): boolean => {
-        for (const node of Array.from(nodes)) {
-            if (!(node instanceof Element)) {
-                continue
-            }
-            if (node.matches(LAYOUT_ELEMENT_SELECTOR) || node.querySelector(LAYOUT_ELEMENT_SELECTOR) !== null) {
-                return true
-            }
-        }
-        return false
-    }
-    return records.some((record) => carriesLayoutElement(record.addedNodes) || carriesLayoutElement(record.removedNodes))
-}
-
-/**
- * Ratio between visual pixels (pointer coordinates) and layout pixels (the lengths the allocator hands out).
- * 視覚ピクセル (ポインタ座標) とレイアウトピクセル (配分器が配る長さ) の比。
- *
- * A transformed ancestor scales pointer coordinates but not the lengths the layout is computed in, so a drag
- * delta read straight from the pointer moves the boundary by `travel × scale` instead of `travel` — the grab
- * point slides out from under the cursor, and the error grows without bound as the gesture continues.
- * 変形された祖先の下ではポインタ座標だけが拡大縮小され、レイアウトが計算される長さは変わらない。
- * ポインタの変位をそのまま使うと境界は `移動量 × 倍率` しか動かず、掴んだ点がカーソルから滑り出し、
- * その誤差はジェスチャーが続く限り増え続ける。
- *
- * @param element - Element whose box is compared in both spaces / 双方の空間で矩形を比べる要素
- * @param direction - Axis to measure along / 計測する軸
- * @returns Visual length divided by layout length, 1 when either is unavailable / 視覚長 ÷ レイアウト長 (いずれか不明なら 1)
- */
-export const getVisualScale = (element: HTMLElement, direction: PanelDirection): number => {
-    if (typeof window === "undefined") {
-        return 1
-    }
-    const isHorizontal = direction === "horizontal"
-    const rect = element.getBoundingClientRect()
-    const visual = isHorizontal ? rect.width : rect.height
-    const styles = window.getComputedStyle(element)
-    // グループは box-sizing: border-box を所有するため、計算値の幅・高さは視覚矩形と同じ境界領域を指す。
-    // ただし配置されていない要素では指定値 (`100%` など) が返るため、px でなければ換算しない
-    const declared = isHorizontal ? styles.width : styles.height
-    if (!declared.endsWith("px")) {
-        return 1
-    }
-    const layout = Number.parseFloat(declared)
-    return visual > 0 && Number.isFinite(layout) && layout > 0 ? visual / layout : 1
-}
-
-/**
- * Persist a panel layout to local storage.
- * パネルレイアウトをローカルストレージへ保存する。
- *
- * @param id - Auto-save identifier / 自動保存の識別子
- * @param entries - Panel lengths with their identifiers, in DOM order / DOM 順の識別子つきパネル長
- */
-export const saveLayout = (id: string, entries: PersistedPanelSize[]): void => {
-    try {
-        localStorage.setItem(`panel-layout-${id}`, JSON.stringify(entries))
-    } catch (error) {
-        console.warn("Failed to save panel layout:", error)
-    }
-}
-
-/**
- * Restore a panel layout from local storage.
- * パネルレイアウトをローカルストレージから復元する。
- *
- * A stored layout is only usable when every entry names the panel it belongs to, so a payload written by a
- * different panel set is rejected instead of being applied by position.
- * 保存レイアウトは各項目が所属パネルを名指ししている場合にだけ利用できる。別構成が書いた内容は位置で当てはめず拒否する。
- *
- * @param id - Auto-save identifier / 自動保存の識別子
- * @returns Stored layout, or null when nothing usable is stored / 保存済みレイアウト、利用できなければ null
- */
-export const loadLayout = (id: string): PersistedPanelSize[] | null => {
-    try {
-        const saved = localStorage.getItem(`panel-layout-${id}`)
-        if (!saved) {
-            return null
-        }
-        const parsed: unknown = JSON.parse(saved)
-        if (!Array.isArray(parsed)) {
-            return null
-        }
-        const isEntry = (value: unknown): value is PersistedPanelSize => typeof value === "object" && value !== null && typeof (value as PersistedPanelSize).id === "string" && Number.isFinite((value as PersistedPanelSize).size)
-        return parsed.every(isEntry) ? parsed : null
-    } catch (error) {
-        console.warn("Failed to load panel layout:", error)
-        return null
-    }
-}