@aiquants/resize-panels 1.8.1 → 2.0.0

package/src/types.ts

@@ -3,14 +3,24 @@
  * リサイザブルパネルコンポーネントの型定義
  */
 
-import type { CSSProperties, ReactNode } from "react"
+import type { CSSProperties, HTMLAttributes, ReactNode } from "react"
 
 /**
- * Pixel threshold used to decide when panels snap closed or open.
- * パネルのスナップ判定に利用するピクセル閾値。
+ * Pixel threshold under which a panel is treated as visually closed.
+ * パネルが見た目上閉じていると扱われるピクセル閾値。
  */
 export const PANEL_SNAP_THRESHOLD = 12
 
+/**
+ * Numeric tolerance for layout arithmetic, in pixels.
+ * レイアウト演算の許容誤差 (px)。
+ *
+ * Sizes are IEEE-754 doubles produced by divisions, so exact comparisons would freeze drags on a 1 ulp
+ * difference. Everything below this tolerance is treated as equality.
+ * サイズは除算由来の倍精度値であり、厳密比較では 1 ulp の差でドラッグが凍結する。この許容値未満は同値とみなす。
+ */
+export const PANEL_ALLOCATION_EPSILON = 1e-6
+
 /**
  * Default thickness in pixels for the resize handle interactive area.
  * リサイズハンドルのインタラクティブ領域のデフォルト厚み (px)。
@@ -18,8 +28,44 @@ export const PANEL_SNAP_THRESHOLD = 12
 export const PANEL_HANDLE_THICKNESS = 8
 
 /**
- * Spacing in pixels between visual indicator dots in the handle.
- * ハンドル内の視覚インジケーター点同士のピクセル間隔。
+ * Default thickness in pixels for the visual indicator wrapper.
+ * 視覚インジケーター外枠のデフォルト厚み (px)。
+ */
+export const PANEL_INDICATOR_THICKNESS = 6
+
+/**
+ * Default length in pixels for the visual indicator wrapper in horizontal layout.
+ * 水平レイアウトにおける視覚インジケーター外枠のデフォルト長さ (px)。
+ */
+export const PANEL_INDICATOR_LENGTH_HORIZONTAL = 48
+
+/**
+ * Default length in pixels for the visual indicator wrapper in vertical layout.
+ * 垂直レイアウトにおける視覚インジケーター外枠のデフォルト長さ (px)。
+ */
+export const PANEL_INDICATOR_LENGTH_VERTICAL = 80
+
+/**
+ * Default thickness in pixels for the inner bar inside the visual indicator.
+ * 視覚インジケーター内部バーのデフォルト厚み (px)。
+ */
+export const PANEL_INDICATOR_BAR_THICKNESS = 2
+
+/**
+ * Default length in pixels for the inner bar inside the visual indicator in horizontal layout.
+ * 水平レイアウトにおける視覚インジケーター内部バーのデフォルト長さ (px)。
+ */
+export const PANEL_INDICATOR_BAR_LENGTH_HORIZONTAL = 32
+
+/**
+ * Default length in pixels for the inner bar inside the visual indicator in vertical layout.
+ * 垂直レイアウトにおける視覚インジケーター内部バーのデフォルト長さ (px)。
+ */
+export const PANEL_INDICATOR_BAR_LENGTH_VERTICAL = 64
+
+/**
+ * Spacing in pixels between visual indicators of handles that share a boundary.
+ * 境界を共有するハンドルの視覚インジケーター同士のピクセル間隔。
  */
 export const PANEL_VISIBLE_INDICATOR_SPACING = 8
 
@@ -65,24 +111,6 @@ export const PANEL_EXPAND_THRESHOLD_MAX = 20
  */
 export const PANEL_HANDLE_VISIBILITY_THRESHOLD = 0.05
 
-/**
- * Retry intervals in milliseconds when awaiting layout stabilization.
- * レイアウトの安定化を待機するときに使用するミリ秒単位の再試行間隔。
- */
-export const PANEL_RESIZE_RETRY_INTERVALS = [10, 50, 100, 200, 300, 500, 800] as const
-
-/**
- * Tolerance used to decide whether pixel-based panel adjustments are significant.
- * ピクセル基準パネルの補正を有効とみなすための誤差許容値。
- */
-export const PANEL_PIXEL_MUTATION_TOLERANCE = 0.0
-
-/**
- * Minimum pixel threshold used when clamping snap calculations.
- * スナップ計算を補正する際に用いる最小ピクセル閾値。
- */
-export const PANEL_MIN_SNAP_THRESHOLD = 0.0
-
 /**
  * Layout direction of panels
  * パネルのレイアウト方向
@@ -140,76 +168,160 @@ export type CollapsibleConfig = {
 }
 
 /**
- * Axis-aligned container measurement including inner (borderless) and outer dimensions.
- * 枠線控除後と控除前の両方の寸法を含む軸方向コンテナ計測値。
+ * Axis-aligned container measurement.
+ * 軸方向のコンテナ計測値。
+ *
+ * `content` is what every layout number is relative to: percentage sizes resolve against it and the
+ * allocator fills exactly this length. `border` is the same box plus padding and borders, used only when a
+ * caller needs the element's outer footprint.
+ * すべてのレイアウト数値の基準は `content`: パーセンテージ指定はこの長さに解決され、配分器はこの長さを満たす。
+ * `border` は同じ軸のパディング・枠線を含む外形で、要素の外寸が必要な場合にのみ使う。
  */
 export type ContainerAxisMeasurement = {
-    inner: number
-    outer: number
+    content: number
+    border: number
 }
 
 /**
- * Snapshot describing when panel constraints conflict with the container size.
- * パネル制約とコンテナサイズが矛盾する際のスナップショット。
+ * Reason code for layout constraint violations.
+ * レイアウト制約違反の理由コード。
  */
 export type LayoutConstraintViolationReason = "minimum-exceeded" | "maximum-insufficient"
 
+/**
+ * Snapshot describing when panel constraints conflict with the container size.
+ * パネル制約とコンテナサイズが矛盾した際のスナップショット。
+ */
 export type LayoutConstraintViolation = {
     reason: LayoutConstraintViolationReason
-    totalMinimumSize: number | null
-    totalMaximumSize: number | null
+    totalMinimumSize: number
+    totalMaximumSize: number
     availableContainerSize: number
 }
 
 /**
- * Layout data for a single panel
- * 単一パネルのレイアウトデータ
+ * Canonical layout state of a single panel.
+ * 単一パネルの正準レイアウト状態。
+ *
+ * The state separates three roles and never stores the same quantity twice: configuration comes from the
+ * component's props, the preference is what the user asked for (a share of the container for flexible
+ * panels, an absolute length for pixel panels), and `size` is the allocator's answer for the current
+ * container. Everything else — the rendered flex basis, the handle position, the percentage shown in the
+ * debug overlay — is derived from those.
+ * 状態は 3 つの役割に分かれ、同じ量を二重に持たない: 構成はコンポーネントの props 由来、希望値は利用者の要求
+ * (柔軟パネルはコンテナ比、ピクセルパネルは絶対長)、`size` は現在のコンテナに対する配分器の答え。描画される
+ * flex basis・ハンドル位置・デバッグ表示の割合は、すべてここから導出される。
  */
 export interface PanelLayoutData {
     id: string
-    size: number
-    percentageSize?: number
-    preferredPercentageSize?: number
-    preferredPixelSize?: number
+    /** Which preference field drives this panel. どちらの希望値でサイズが決まるか。 */
     sizeUnit: SizeUnit
-    originalPixelSize?: number
+    /** Allocated length in pixels for the current container. 現在のコンテナに対する配分結果 (px)。 */
+    size: number
+    /**
+     * Ratio weight of a flexible panel, expressed as a share of the container in percent.
+     * 柔軟パネルの重み (コンテナ比 %)。
+     *
+     * Only the ratio between panels matters — unless the panel declares `flexAdjustPriority`, which turns the
+     * same number into an absolute claim on that share of the container.
+     * 意味を持つのはパネル間の比だけ。ただし `flexAdjustPriority` を宣言したパネルでは、同じ数値が
+     * 「コンテナのその割合」という絶対的な要求になる。
+     */
+    preferredPercentageSize: number
+    /** Requested absolute length of a pixel panel. ピクセルパネルの希望絶対長 (px)。 */
+    preferredPixelSize: number
     minSize?: FlexibleSize
     maxSize?: FlexibleSize
-    autoMinSize?: FlexibleSize
     collapseFromStart: boolean
     collapseFromEnd: boolean
-    collapsedByDirection?: PanelCollapseDirection | null
+    collapsed: boolean
+    collapsedByDirection: PanelCollapseDirection | null
+    /**
+     * Preference captured when the panel collapsed, restored verbatim on expand.
+     * 折りたたみ時に退避し、展開時にそのまま復元する希望値。
+     */
+    preferenceBeforeCollapse: number
     /**
-     * Skip automatic growth for flexible panels that were manually reduced to a zero footprint.
-     * 手動でゼロ相当まで縮めた柔軟パネルを自動拡張対象から外すフラグ。
+     * Preference the component last authored through its props, used to tell a prop change from a re-registration.
+     * コンポーネントが props で最後に宣言した希望値。prop 変更と単なる再登録を区別するために保持。
      */
-    excludeFromAutoGrowth?: boolean
-    collapsed?: boolean
-    sizeBeforeCollapse?: number
-    percentageSizeBeforeCollapse?: number
-    preferredPercentageSizeBeforeCollapse?: number
-    preferredPixelSizeBeforeCollapse?: number
+    authoredPreference: number
+    /** Serving order among pixel panels, higher first. ピクセルパネル間の充当順位 (大きいほど先)。 */
     pixelAdjustPriority?: number
+    /**
+     * Serving order among flexible panels, higher first; absent means pure ratio sharing.
+     * 柔軟パネル間の充当順位 (大きいほど先)。未指定なら純粋な比例配分。
+     *
+     * Declaring it changes how `preferredPercentageSize` is read: the panel claims that share of the container
+     * before the ratio panels divide what is left.
+     * 宣言すると `preferredPercentageSize` の読み方が変わり、比例配分のパネルが残りを分ける前に
+     * コンテナのその割合を確保する。
+     */
     flexAdjustPriority?: number
-    measuredPixelSize?: number
-    measuredPercentageSize?: number
-    measuredPixelSizeBeforeCollapse?: number
 }
 
+/**
+ * Layout state of one panel group: the container it was measured against, its panels in DOM order, and
+ * whether the panels' constraints can be satisfied at that size.
+ * パネルグループのレイアウト状態: 計測対象のコンテナ長・DOM 順のパネル一覧・制約充足可否。
+ */
+export interface PanelGroupLayoutState {
+    /** Content-box length of the group along its axis; 0 until the first measurement. 軸方向の内容領域長 (未計測は 0)。 */
+    containerSize: number
+    panels: PanelLayoutData[]
+    violation: LayoutConstraintViolation | null
+}
+
+/**
+ * Configuration and preference a panel publishes when it registers with its group.
+ * パネルがグループへ登録する際に公開する構成と希望値。
+ */
+export type PanelRegistration = Omit<PanelLayoutData, "size" | "collapsedByDirection" | "preferenceBeforeCollapse" | "authoredPreference">
+
+/**
+ * One panel's persisted length, kept with its identifier so a stored layout can never be applied to a
+ * different set of panels.
+ * 保存されたパネル 1 枚分の長さ。別構成のパネルへ誤って適用されないよう識別子を伴う。
+ */
+export type PersistedPanelSize = {
+    id: string
+    size: number
+    /** Whether the panel was collapsed when the layout was written. 保存時に折りたたまれていたか。 */
+    collapsed: boolean
+}
+
+/**
+ * Actions accepted by the panel group reducer.
+ * パネルグループのリデューサーが受け付けるアクション。
+ */
+export type PanelAction =
+    | { type: "SET_CONTAINER_SIZE"; containerSize: number }
+    | { type: "REGISTER_PANEL"; panel: PanelRegistration }
+    | { type: "UNREGISTER_PANEL"; id: string }
+    | { type: "REORDER_PANELS"; ids: string[] }
+    | { type: "RESIZE_PANELS"; startId: string; endId: string; startSize: number }
+    | { type: "COLLAPSE_PANEL"; id: string; from: PanelCollapseDirection }
+    | { type: "EXPAND_PANEL"; id: string; from: PanelCollapseDirection; targetSize?: number }
+    | { type: "RESTORE_LAYOUT"; entries: PersistedPanelSize[] }
+
 /**
  * Props for the Panel component
  * Panel コンポーネントのプロパティ
  */
-export interface PanelProps {
+// aria-hidden は折りたたみ状態から決まるため、利用者の指定は黙って捨てられる
+export interface PanelProps extends Omit<HTMLAttributes<HTMLDivElement>, "id" | "children" | "className" | "style" | "aria-hidden"> {
     id?: string
+    /**
+     * Initial size. A percentage (or bare number) makes the panel flexible, pixels make it fixed.
+     * 初期サイズ。パーセンテージ (数値のみの指定を含む) なら柔軟パネル、ピクセルなら固定パネル。
+     * @default { value: 50, unit: "percentage" }
+     */
     defaultSize?: FlexibleSize
     minSize?: FlexibleSize
     maxSize?: FlexibleSize
-    autoMinSize?: FlexibleSize
     className?: string
     style?: CSSProperties
     children?: ReactNode
-    order?: number
     collapsible?: CollapsibleConfig
     defaultCollapsed?: boolean
     pixelAdjustPriority?: number
@@ -221,12 +333,11 @@ export interface PanelProps {
  * Props for the PanelGroup component
  * PanelGroup コンポーネントのプロパティ
  */
-export interface PanelGroupProps {
+export interface PanelGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, "id" | "children" | "className" | "style"> {
     id?: string
     direction: PanelDirection
-    storageKey?: string
     className?: string
-    style?: React.CSSProperties
+    style?: CSSProperties
     children?: ReactNode
     showDebugInfo?: boolean
     onLayout?: (panelSizes: number[]) => void
@@ -239,16 +350,25 @@ export interface PanelGroupProps {
  */
 export interface PanelGroupContextValue {
     direction: PanelDirection
-    registerPanel: (panel: PanelLayoutData) => void
+    registerPanel: (panel: PanelRegistration) => void
     unregisterPanel: (id: string) => void
     getPanel: (id: string) => PanelLayoutData | undefined
     panels: PanelLayoutData[]
-    isContainerReady: boolean
+    /** Content-box length of the group along its axis. グループ軸方向の内容領域長。 */
+    containerSize: number
+    /**
+     * Key that changes whenever the document order of the group's panels and handle anchors changes.
+     * グループのパネルとハンドルのアンカーの文書順が変わるたびに変化する鍵。
+     *
+     * A handle that moves to another boundary leaves the panel id sequence untouched, so the panels alone
+     * cannot tell a handle that its neighbours changed.
+     * ハンドルが別の境界へ移ってもパネルの id 列は変わらないため、パネルだけではハンドルへ隣の変化を伝えられない。
+     */
+    layoutOrderKey: string
     showDebugInfo: boolean
-    resizePanels: (leftId: string, rightId: string, leftSize: number, rightSize: number) => void
+    resizePanels: (startId: string, endId: string, startSize: number) => void
     collapsePanel: (id: string, from: PanelCollapseDirection) => void
     expandPanel: (id: string, from: PanelCollapseDirection, targetSize?: number) => void
-    containerSize: ContainerSize
     reportPanelMeasurement: (id: string, measurement: PanelMeasurement | null) => void
     panelMeasurements: Record<string, PanelMeasurement>
     reportHandleMeasurement: (id: string, measurement: ResizeHandleLayoutData | null) => void
@@ -256,19 +376,116 @@ export interface PanelGroupContextValue {
     layoutConstraintViolation: LayoutConstraintViolation | null
 }
 
+/**
+ * Visual indicator configuration options for PanelResizeHandle.
+ * PanelResizeHandle の視覚インジケーターに関する設定オプション。
+ */
+export interface PanelResizeHandleIndicatorConfig {
+    /**
+     * Primary axis thickness of the indicator pill in pixels.
+     * (Horizontal: width, Vertical: height)
+     * インジケーター外枠の主軸方向の厚み (px)。(水平: 幅, 垂直: 高さ)
+     * @default 6
+     */
+    thickness?: number
+    /**
+     * Cross axis length of the indicator pill in pixels.
+     * (Horizontal: height, Vertical: width)
+     * インジケーター外枠の交差軸方向の長さ (px)。(水平: 高さ, 垂直: 幅)
+     * @default horizontal ? 48 : 80
+     */
+    length?: number
+    /**
+     * Primary axis thickness of the inner bar in pixels.
+     * インジケーター内部バーの主軸方向の厚み (px)。
+     * @default 2
+     */
+    barThickness?: number
+    /**
+     * Cross axis length of the inner bar in pixels.
+     * インジケーター内部バーの交差軸方向の長さ (px)。
+     * @default horizontal ? 32 : 64
+     */
+    barLength?: number
+    /**
+     * Whether the indicator is visible.
+     * インジケーターを表示するかどうかの指定。
+     * @default true
+     */
+    visible?: boolean
+    /**
+     * Additional CSS class name for the indicator wrapper.
+     * インジケーター外枠に付与する追加 CSS クラス名。
+     */
+    className?: string
+    /**
+     * Additional CSS class name for the inner bar.
+     * インジケーター内部バーに付与する追加 CSS クラス名。
+     */
+    barClassName?: string
+}
+
 /**
  * Props for the PanelResizeHandle component
  * PanelResizeHandle コンポーネントのプロパティ
  */
-export interface PanelResizeHandleProps {
+/**
+ * ARIA attributes the handle computes from the layout; a consumer value would be silently discarded.
+ * ハンドルがレイアウトから算出する ARIA 属性 (利用者の指定は黙って捨てられるため受け付けない)。
+ */
+type OwnedSeparatorAria = "role" | "aria-orientation" | "aria-valuenow" | "aria-valuemin" | "aria-valuemax" | "aria-disabled" | "aria-hidden"
+
+export interface PanelResizeHandleProps extends Omit<HTMLAttributes<HTMLButtonElement>, "id" | "children" | "className" | "style" | "title" | OwnedSeparatorAria> {
     id?: string
     disabled?: boolean
     onDragging?: (isDragging: boolean) => void
     className?: string
-    style?: React.CSSProperties
+    style?: CSSProperties
     children?: ReactNode
+    /**
+     * Primary axis thickness of the handle's interactive area in pixels.
+     * (Horizontal: width, Vertical: height)
+     * リサイズハンドルの操作領域 (ヒットエリア) の厚み (px)。(水平: 幅, 垂直: 高さ)
+     * @default PANEL_HANDLE_THICKNESS (8)
+     */
+    thickness?: number
+    /**
+     * Configuration for the visual indicator, or boolean to toggle visibility.
+     * 視覚インジケーターの設定オブジェクト、または表示/非表示の真偽値。
+     * @default true
+     */
+    indicator?: boolean | PanelResizeHandleIndicatorConfig
+    /**
+     * Shorthand for indicator wrapper thickness in pixels.
+     * インジケーター外枠厚み (px) のショートハンド。
+     */
+    indicatorThickness?: number
+    /**
+     * Shorthand for indicator wrapper length in pixels.
+     * インジケーター外枠長さ (px) のショートハンド。
+     */
+    indicatorLength?: number
+    /**
+     * Shorthand for indicator inner bar thickness in pixels.
+     * インジケーター内部バー厚み (px) のショートハンド。
+     */
+    indicatorBarThickness?: number
+    /**
+     * Shorthand for indicator inner bar length in pixels.
+     * インジケーター内部バー長さ (px) のショートハンド。
+     */
+    indicatorBarLength?: number
+    /**
+     * Custom tooltip text for the handle element.
+     * ハンドル要素のカスタムツールチップテキスト。
+     */
+    title?: string
 }
 
+/**
+ * Observed pixel and percentage measurements for a registered panel.
+ * 登録済みパネルの実測ピクセル寸法およびパーセンテージ寸法。
+ */
 export interface PanelMeasurement {
     pixelSize: number
     percentageSize: number
@@ -283,6 +500,6 @@ export interface ResizeHandleLayoutData {
     thickness: number
     direction: PanelDirection
     visible: boolean
-    startPanelId?: string | null
-    endPanelId?: string | null
+    startPanelId: string | null
+    endPanelId: string | null
 }