@aiquants/resize-panels 1.9.0 → 2.0.0

package/src/allocateLayout.ts

@@ -0,0 +1,412 @@
+/**
+ * @file Pure layout allocator: the single source of truth for panel sizes.
+ * パネルサイズの唯一の真実源となる純粋なレイアウト配分器。
+ *
+ * The allocator answers one question: given the panels' preferences, their box constraints and the
+ * container's content-box length C, how many pixels does each panel get? Its result satisfies
+ * `Σ active size == C` whenever the constraints allow it, which is what lets the rendered DOM and the
+ * reducer state describe the same geometry.
+ * 配分器が答える問いは 1 つ: 各パネルの希望・箱制約・コンテナ内容領域長 C が与えられたとき、各パネルへ
+ * 何ピクセル配るか。制約が許す限り `Σ アクティブサイズ == C` を満たすため、描画結果とリデューサー状態が
+ * 同一の幾何を表す。
+ */
+
+import { type LayoutConstraintViolation, PANEL_ALLOCATION_EPSILON, type PanelLayoutData } from "./types"
+import { clamp, getConstraintInPixels } from "./utils"
+
+/**
+ * One panel reduced to the quantities the allocator needs.
+ * 配分器が必要とする量だけに還元したパネル 1 枚分の入力。
+ */
+type AllocationItem = {
+    index: number
+    /** Ratio weight for flexible panels; 0 for pixel panels and for panels dragged to zero. 比例配分の重み。 */
+    weight: number
+    /** Size this panel is filled to before ratio sharing starts; null for pure ratio panels. 先行充当の目標値。 */
+    target: number | null
+    /** Serving order inside the sequential tiers, higher first. 逐次充当の順位 (大きいほど先)。 */
+    priority: number
+    /** Sequential tier: pixel panels are served before prioritized flexible panels. 逐次充当の段。 */
+    tier: number
+    min: number
+    max: number
+}
+
+/**
+ * Resolved pixel bounds of a panel for a given container length.
+ * 指定コンテナ長におけるパネルのピクセル境界。
+ */
+export type PanelBounds = {
+    min: number
+    max: number
+}
+
+/**
+ * Sequential tier index of pixel panels (served before prioritized flexible panels).
+ * ピクセルパネルの逐次充当段 (優先度つき柔軟パネルより先に充当)。
+ */
+const PIXEL_TIER = 0
+
+/**
+ * Sequential tier index of flexible panels that declare `flexAdjustPriority`.
+ * `flexAdjustPriority` を宣言した柔軟パネルの逐次充当段。
+ */
+const PRIORITY_FLEXIBLE_TIER = 1
+
+/**
+ * Reduce a length to a finite non-negative number.
+ * 長さを有限かつ非負の数値へ整流する処理。
+ *
+ * A non-finite preference or constraint would propagate through the whole allocation as NaN and defeat every
+ * comparison that guards it, so it is turned into 0 at the boundary instead of being carried further.
+ * 有限でない希望値や制約は配分全体へ NaN として伝播し、それを守るはずの比較をすべて無効化するため、
+ * 先へ渡さず境界で 0 に落とす。
+ *
+ * @param value - Length to sanitize / 整流する長さ
+ * @returns The value itself when finite and non-negative, otherwise 0 / 有限かつ非負ならその値、それ以外は 0
+ */
+const sanitizeLength = (value: number): number => (Number.isFinite(value) && value > 0 ? value : 0)
+
+/**
+ * Report whether a panel is sized in pixels rather than as a share of the container.
+ * パネルがコンテナ比ではなくピクセルでサイズ指定されているかの判定。
+ *
+ * @param panel - Panel layout data / パネルレイアウトデータ
+ * @returns True when the panel keeps an absolute pixel size / 絶対ピクセル指定なら true
+ */
+export const isPixelPanel = (panel: PanelLayoutData): boolean => panel.sizeUnit === "pixels"
+
+/**
+ * Resolve a panel's bounds in pixels for the given container length.
+ * 指定コンテナ長に対するパネルの境界をピクセルで解決する処理。
+ *
+ * The same bounds govern the allocator and an explicit drag: a size the user cannot reach by hand but the
+ * allocator may produce (or the reverse) would make the two disagree about where a panel is allowed to be.
+ * 配分器と明示的なドラッグは同じ境界に従う。片方だけが到達できるサイズがあると、パネルが居てよい範囲について
+ * 両者の認識が食い違うためである。
+ *
+ * @param panel - Panel layout data / パネルレイアウトデータ
+ * @param containerSize - Container content-box length in pixels / コンテナ内容領域長 (px)
+ * @returns Pixel bounds with `min <= max` guaranteed / `min <= max` を保証したピクセル境界
+ */
+export const resolvePanelBounds = (panel: PanelLayoutData, containerSize: number): PanelBounds => {
+    const min = Math.max(0, sanitizeLength(getConstraintInPixels(panel.minSize, 0, containerSize)))
+    const max = Math.max(min, sanitizeLength(getConstraintInPixels(panel.maxSize, containerSize, containerSize)))
+    return { min, max }
+}
+
+/**
+ * Distribute a budget across items proportionally to their weights while honouring box constraints.
+ * 箱制約を守りつつ、重みに比例して予算を配分する処理 (water-filling)。
+ *
+ * Solves `sᵢ = clamp(λ·wᵢ, minᵢ, maxᵢ)` with `Σ sᵢ = budget`. The solution is unique even when λ is not,
+ * and it preserves the ratio `sᵢ : sⱼ = wᵢ : wⱼ` for every pair that is not clamped, so the residue of a
+ * clamped panel is shared out in the remaining panels' own ratio.
+ * `Σ sᵢ = budget` を満たす `sᵢ = clamp(λ·wᵢ, minᵢ, maxᵢ)` を解く。λ が一意でなくとも解は一意であり、
+ * クランプされていない組では比 `sᵢ : sⱼ = wᵢ : wⱼ` が保たれるため、クランプ分の余りは残りのパネルの比で分配される。
+ *
+ * @param items - Items to size, each with a weight and pixel bounds / 重みとピクセル境界を持つ配分対象
+ * @param budget - Total pixels to distribute / 配分する総ピクセル数
+ * @returns Pixel size per item, index-aligned with `items` / `items` と同順のピクセルサイズ
+ */
+const waterFill = (items: ReadonlyArray<AllocationItem>, budget: number): number[] => {
+    const sizes = items.map((item) => item.min)
+    const frozen = items.map(() => false)
+
+    for (;;) {
+        let freeWeight = 0
+        let frozenTotal = 0
+        let freeCount = 0
+        for (let index = 0; index < items.length; index += 1) {
+            if (frozen[index]) {
+                frozenTotal += sizes[index]
+                continue
+            }
+            freeCount += 1
+            freeWeight += items[index].weight
+        }
+        if (freeCount === 0) {
+            return sizes
+        }
+
+        const remaining = budget - frozenTotal
+        if (freeWeight <= 0) {
+            // 重みが無いパネルは比例配分の対象にならないため下限で確定する
+            for (let index = 0; index < items.length; index += 1) {
+                if (!frozen[index]) {
+                    sizes[index] = items[index].min
+                }
+            }
+            return sizes
+        }
+
+        const lambda = Math.max(0, remaining / freeWeight)
+        let violation = 0
+        for (let index = 0; index < items.length; index += 1) {
+            if (frozen[index]) {
+                continue
+            }
+            const raw = lambda * items[index].weight
+            const clamped = clamp(raw, items[index].min, items[index].max)
+            sizes[index] = clamped
+            violation += clamped - raw
+        }
+
+        // violation > 0 は下限側が持ち上げた分だけ超過したことを意味し、真の λ はさらに小さい。
+        // その状況で下限に張り付いたパネルは解でも下限なので、確定させて残りを配り直す (上限側は対称)
+        let froze = false
+        for (let index = 0; index < items.length; index += 1) {
+            if (frozen[index]) {
+                continue
+            }
+            const raw = lambda * items[index].weight
+            if (violation > PANEL_ALLOCATION_EPSILON && sizes[index] > raw + PANEL_ALLOCATION_EPSILON) {
+                frozen[index] = true
+                sizes[index] = items[index].min
+                froze = true
+            } else if (violation < -PANEL_ALLOCATION_EPSILON && sizes[index] < raw - PANEL_ALLOCATION_EPSILON) {
+                frozen[index] = true
+                sizes[index] = items[index].max
+                froze = true
+            }
+        }
+        if (!froze) {
+            return sizes
+        }
+    }
+}
+
+/**
+ * Build the allocator's view of a panel from its layout data.
+ * パネルレイアウトデータから配分器用の入力を構築する処理。
+ */
+const toAllocationItem = (panel: PanelLayoutData, index: number, containerSize: number): AllocationItem => {
+    const { min, max } = resolvePanelBounds(panel, containerSize)
+
+    if (isPixelPanel(panel)) {
+        return {
+            index,
+            weight: 0,
+            target: clamp(sanitizeLength(panel.preferredPixelSize), min, max),
+            priority: panel.pixelAdjustPriority ?? 0,
+            tier: PIXEL_TIER,
+            min,
+            max,
+        }
+    }
+
+    const weight = sanitizeLength(panel.preferredPercentageSize)
+    const hasPriority = panel.flexAdjustPriority !== undefined
+    return {
+        index,
+        weight,
+        target: hasPriority ? clamp((weight / 100) * containerSize, min, max) : null,
+        priority: panel.flexAdjustPriority ?? 0,
+        tier: PRIORITY_FLEXIBLE_TIER,
+        min,
+        max,
+    }
+}
+
+/**
+ * Fill items up to a per-item ceiling in tier and priority order, consuming the available budget.
+ * 段・優先度の順に上限まで充当し、利用可能な予算を消費する処理。
+ *
+ * @param items - Items to fill, already ordered / 充当対象 (整列済み)
+ * @param sizes - Sizes mutated in place / その場で更新されるサイズ配列
+ * @param ceilingOf - Upper bound for each item / 各要素の充当上限
+ * @param available - Pixels available for filling / 充当に使えるピクセル数
+ * @returns Pixels left after filling / 充当後に残ったピクセル数
+ */
+const fillInOrder = (items: ReadonlyArray<AllocationItem>, sizes: number[], ceilingOf: (item: AllocationItem) => number, available: number): number => {
+    let remaining = available
+    for (const item of items) {
+        if (remaining <= PANEL_ALLOCATION_EPSILON) {
+            break
+        }
+        const room = ceilingOf(item) - sizes[item.index]
+        if (room <= 0) {
+            continue
+        }
+        const applied = Math.min(room, remaining)
+        sizes[item.index] += applied
+        remaining -= applied
+    }
+    return remaining
+}
+
+/**
+ * Share the remaining pixels among items in proportion to their weights, never below what they already have.
+ * 残りピクセルを重みの比で各要素へ分け与える処理 (既に持っている分を下回らせない)。
+ *
+ * @param items - Items that take part in the sharing / 分け合いに参加する要素
+ * @param sizes - Sizes mutated in place / その場で更新されるサイズ配列
+ * @param available - Pixels available for sharing / 分け合いに使えるピクセル数
+ * @returns Pixels left after sharing / 分け合い後に残ったピクセル数
+ */
+const shareByWeight = (items: ReadonlyArray<AllocationItem>, sizes: number[], available: number): number => {
+    if (items.length === 0 || available <= PANEL_ALLOCATION_EPSILON) {
+        return available
+    }
+    const floors = items.map((item) => ({ ...item, min: sizes[item.index] }))
+    const shared = waterFill(floors, available + floors.reduce((total, item) => total + item.min, 0))
+    let distributed = 0
+    for (let index = 0; index < items.length; index += 1) {
+        distributed += shared[index] - sizes[items[index].index]
+        sizes[items[index].index] = shared[index]
+    }
+    return available - distributed
+}
+
+/**
+ * Share the remaining pixels equally among items that declare no ratio weight.
+ * 取り分の重みを持たない要素へ、残りピクセルを均等に分け与える処理。
+ *
+ * @param items - Items that take part in the sharing / 分け合いに参加する要素
+ * @param sizes - Sizes mutated in place / その場で更新されるサイズ配列
+ * @param available - Pixels available for sharing / 分け合いに使えるピクセル数
+ * @returns Pixels left after sharing / 分け合い後に残ったピクセル数
+ */
+const shareEvenly = (items: ReadonlyArray<AllocationItem>, sizes: number[], available: number): number =>
+    shareByWeight(
+        items.map((item) => ({ ...item, weight: 1 })),
+        sizes,
+        available,
+    )
+
+/**
+ * Order sequential items by tier, then by descending priority, then by DOM position.
+ * 逐次充当の要素を 段 → 優先度降順 → DOM 順 で整列する処理。
+ */
+const bySequentialOrder = (left: AllocationItem, right: AllocationItem): number => {
+    if (left.tier !== right.tier) {
+        return left.tier - right.tier
+    }
+    if (left.priority !== right.priority) {
+        return right.priority - left.priority
+    }
+    return left.index - right.index
+}
+
+/**
+ * Result of one allocation pass.
+ * 1 回の配分結果。
+ */
+export type LayoutAllocation = {
+    /** Pixel size per panel, index-aligned with the input, collapsed panels at 0. パネルごとのピクセルサイズ。 */
+    sizes: number[]
+    /** Constraint conflict detected while allocating, or null. 配分中に検出した制約矛盾。 */
+    violation: LayoutConstraintViolation | null
+}
+
+/**
+ * Allocate pixel sizes to every panel of a group for a given container length.
+ * 指定コンテナ長に対してグループ内の全パネルへピクセルサイズを配分する処理。
+ *
+ * The allocation runs in three stages: collapsed panels take no space, panels with an absolute target
+ * (pixel panels first, then flexible panels that declare a priority) are filled in order, and the rest of
+ * the container is shared by the remaining flexible panels in proportion to their weights. Any residue
+ * left because every ratio panel hit its maximum is offered back to the sequential panels up to their own
+ * maximum, so the container is filled whenever the constraints allow it.
+ * 配分は 3 段階: 折りたたみパネルは領域を取らず、絶対目標を持つパネル (ピクセル → 優先度つき柔軟) を順に
+ * 充当し、残りを柔軟パネルが重みに比例して分け合う。全ての比例パネルが上限に達して余りが出た場合は逐次段の
+ * パネルへ上限まで戻すため、制約が許す限りコンテナは満たされる。
+ *
+ * @param panels - Panels in DOM order / DOM 順のパネル一覧
+ * @param containerSize - Container content-box length in pixels / コンテナ内容領域長 (px)
+ * @returns Sizes and the constraint violation detected, if any / 配分結果と検出した制約違反
+ */
+export const allocatePanelSizes = (panels: ReadonlyArray<PanelLayoutData>, containerSize: number): LayoutAllocation => {
+    const sizes = panels.map(() => 0)
+    if (!Number.isFinite(containerSize) || containerSize <= 0 || panels.length === 0) {
+        return { sizes, violation: null }
+    }
+
+    const items: AllocationItem[] = []
+    for (let index = 0; index < panels.length; index += 1) {
+        const panel = panels[index]
+        if (panel.collapsed) {
+            continue
+        }
+        items.push(toAllocationItem(panel, index, containerSize))
+    }
+    if (items.length === 0) {
+        return { sizes, violation: null }
+    }
+
+    let totalMinimum = 0
+    let totalMaximum = 0
+    for (const item of items) {
+        sizes[item.index] = item.min
+        totalMinimum += item.min
+        totalMaximum += item.max
+    }
+
+    const violation = detectViolation(totalMinimum, totalMaximum, containerSize)
+    let remaining = containerSize - totalMinimum
+    if (remaining <= PANEL_ALLOCATION_EPSILON) {
+        // 最小サイズの合計がコンテナを超える不能構成。下限を保ったまま返し、通知は violation が担う
+        return { sizes, violation }
+    }
+
+    const sequential = items.filter((item) => item.target !== null).sort(bySequentialOrder)
+    const ratioFlexible = items.filter((item) => item.target === null && item.weight > 0)
+    // 受け皿の資格は「柔軟であり、重みでは取り分を得られないこと」。優先度の宣言は関係しない
+    // (優先度つきパネルを端まで引くと重みが 0 になり、ここで外すと余りの引き取り手が消える)
+    const pinnedFlexible = items.filter((item) => item.tier !== PIXEL_TIER && item.weight <= 0)
+    const prioritizedFlexible = sequential.filter((item) => item.tier === PRIORITY_FLEXIBLE_TIER)
+    const pixelItems = sequential.filter((item) => item.tier === PIXEL_TIER)
+
+    // 配分の順序は「誰の希望を先に満たすか」ではなく「余りを誰が引き取るか」の全順序でもある。
+    // 最後の段まで用意するのは、引き取り手が尽きてコンテナに隙間が残る状態を作らないため
+    // (隙間が残れば Σ サイズ = コンテナ長 の不変条件が破れ、ハンドルと境界が食い違う)
+
+    // 1. 領域が不足する場合に誰から満たすかを決める段。ピクセルパネル → 優先度つき柔軟パネルの順
+    remaining = fillInOrder(sequential, sizes, (item) => item.target ?? item.min, remaining)
+
+    // 2. 残りを比例配分の柔軟パネルが重みの比で分け合う
+    remaining = shareByWeight(ratioFlexible, sizes, remaining)
+
+    // 3. 比例配分側が上限に達してなお余る場合、優先度つき柔軟パネルが希望を超えて重みの比で引き取る
+    remaining = shareByWeight(prioritizedFlexible, sizes, remaining)
+
+    // 4. 柔軟パネルが 1 枚も無い構成では、ピクセルパネルが優先度順に上限まで引き取る
+    remaining = fillInOrder(pixelItems, sizes, (item) => item.max, remaining)
+
+    // 5. それでも余る場合の最後の受け皿は、取り分を望まない (重み 0 の) 柔軟パネル。
+    //    ここまで来るのは他の全パネルが上限に達したときだけなので、ゼロへ縮めたパネルが
+    //    通常のリサイズで復活することはない。
+    //    この段が無いと Σ サイズ = コンテナ長 が破れ、しかも Σ 上限 >= コンテナ長 なので違反としても報告されない
+    remaining = shareEvenly(pinnedFlexible, sizes, remaining)
+
+    return { sizes, violation }
+}
+
+/**
+ * Detect whether the panels' constraints can be satisfied by the container.
+ * パネルの制約をコンテナが満たせるかどうかを判定する処理。
+ *
+ * @param totalMinimum - Sum of the active panels' minimum sizes / アクティブパネルの最小サイズ合計
+ * @param totalMaximum - Sum of the active panels' maximum sizes / アクティブパネルの最大サイズ合計
+ * @param containerSize - Container content-box length in pixels / コンテナ内容領域長 (px)
+ * @returns The violation to report, or null when the layout is feasible / 報告すべき違反、可能なら null
+ */
+const detectViolation = (totalMinimum: number, totalMaximum: number, containerSize: number): LayoutConstraintViolation | null => {
+    if (totalMinimum - containerSize > PANEL_ALLOCATION_EPSILON) {
+        return {
+            reason: "minimum-exceeded",
+            totalMinimumSize: totalMinimum,
+            totalMaximumSize: totalMaximum,
+            availableContainerSize: containerSize,
+        }
+    }
+    if (containerSize - totalMaximum > PANEL_ALLOCATION_EPSILON) {
+        return {
+            reason: "maximum-insufficient",
+            totalMinimumSize: totalMinimum,
+            totalMaximumSize: totalMaximum,
+            availableContainerSize: containerSize,
+        }
+    }
+    return null
+}

package/src/debugOverlayStore.ts

@@ -6,6 +6,15 @@
 import { useSyncExternalStore } from "react"
 import type { ContainerSize, PanelDirection, PanelLayoutData, ResizeHandleLayoutData } from "./types"
 
+/**
+ * Panel layout data enriched with the DOM measurement the overlay compares it against.
+ * オーバーレイが突き合わせる DOM 実測値を添えたパネルレイアウトデータ。
+ */
+export type DebugPanelSnapshot = PanelLayoutData & {
+    measuredPixelSize?: number
+    measuredPercentageSize?: number
+}
+
 /**
  * Snapshot of the debug overlay state across panel groups.
  * デバッグオーバーレイのスナップショット状態を表す構造体。
@@ -24,7 +33,7 @@ export type DebugGroupState = {
     displayName: string
     direction: PanelDirection
     containerSize: ContainerSize
-    panels: PanelLayoutData[]
+    panels: DebugPanelSnapshot[]
     handles: ResizeHandleLayoutData[]
     index: number
 }
@@ -33,7 +42,7 @@ type DebugGroupUpdate = {
     displayName: string
     direction: PanelDirection
     containerSize: ContainerSize
-    panels: PanelLayoutData[]
+    panels: DebugPanelSnapshot[]
     handles: ResizeHandleLayoutData[]
 }
 
@@ -44,27 +53,21 @@ type DebugGroupEntry = DebugGroupState & {
     serializedHandles: string
 }
 
-const serializePanels = (panels: PanelLayoutData[]) => {
+const serializePanels = (panels: DebugPanelSnapshot[]) => {
     return JSON.stringify(
         panels.map((panel) => ({
             id: panel.id,
             size: panel.size,
-            percentageSize: panel.percentageSize ?? null,
-            preferredPercentageSize: panel.preferredPercentageSize ?? null,
-            preferredPixelSize: panel.preferredPixelSize ?? null,
             sizeUnit: panel.sizeUnit,
-            originalPixelSize: panel.originalPixelSize ?? null,
+            preferredPercentageSize: panel.preferredPercentageSize,
+            preferredPixelSize: panel.preferredPixelSize,
             minSize: panel.minSize ?? null,
             maxSize: panel.maxSize ?? null,
-            autoMinSize: panel.autoMinSize ?? null,
             collapseFromStart: panel.collapseFromStart,
             collapseFromEnd: panel.collapseFromEnd,
-            collapsedByDirection: panel.collapsedByDirection ?? null,
-            collapsed: panel.collapsed ?? false,
-            sizeBeforeCollapse: panel.sizeBeforeCollapse ?? null,
-            preferredPercentageSizeBeforeCollapse: panel.preferredPercentageSizeBeforeCollapse ?? null,
-            preferredPixelSizeBeforeCollapse: panel.preferredPixelSizeBeforeCollapse ?? null,
-            measuredPixelSizeBeforeCollapse: panel.measuredPixelSizeBeforeCollapse ?? null,
+            collapsed: panel.collapsed,
+            collapsedByDirection: panel.collapsedByDirection,
+            preferenceBeforeCollapse: panel.preferenceBeforeCollapse,
             pixelAdjustPriority: panel.pixelAdjustPriority ?? null,
             flexAdjustPriority: panel.flexAdjustPriority ?? null,
             measuredPixelSize: panel.measuredPixelSize ?? null,
@@ -203,7 +206,8 @@ const createDebugOverlayStore = () => {
                     if (
                         prevPanel.id !== nextPanel.id ||
                         prevPanel.size !== nextPanel.size ||
-                        prevPanel.percentageSize !== nextPanel.percentageSize ||
+                        prevPanel.preferredPercentageSize !== nextPanel.preferredPercentageSize ||
+                        prevPanel.preferredPixelSize !== nextPanel.preferredPixelSize ||
                         prevPanel.collapsed !== nextPanel.collapsed ||
                         prevPanel.measuredPixelSize !== nextPanel.measuredPixelSize ||
                         prevPanel.measuredPercentageSize !== nextPanel.measuredPercentageSize