@aiquants/resize-panels 1.7.2 → 1.8.0

package/src/roundHalfToEven.ts

@@ -0,0 +1,40 @@
+/**
+ * Round a number to specified digits using banker's rounding (round half to even).
+ * 指定した桁で銀行丸め (最近接偶数への丸め) を行う関数。
+ *
+ * @param value - 丸め対象の数値
+ * @param digits - 丸める桁数 (0: 整数, 1: 小数第1位, -1: 十の位)
+ * @returns 丸められた数値
+ */
+export const roundHalfToEven = (value: number, digits: number = 0): number => {
+    // 非有限値はそのまま返す
+    if (!Number.isFinite(value)) {
+        return value
+    }
+
+    // 桁を移動させるための乗数を計算
+    const multiplier = 10 ** digits
+    const shifted = value * multiplier
+
+    // 整数部分と小数部分を分離
+    const floor = Math.floor(shifted)
+    const fraction = shifted - floor
+
+    // 浮動小数点誤差を考慮したイプシロン値
+    const epsilon = Number.EPSILON * Math.max(1, Math.abs(shifted))
+
+    // 0.5 未満の場合は切り捨て
+    if (fraction < 0.5 - epsilon) {
+        return floor / multiplier
+    }
+
+    // 0.5 より大きい場合は切り上げ
+    if (fraction > 0.5 + epsilon) {
+        return (floor + 1) / multiplier
+    }
+
+    // ちょうど 0.5 の場合は、最近接偶数に丸める
+    // floor が偶数なら floor、奇数なら floor + 1
+    const rounded = floor % 2 === 0 ? floor : floor + 1
+    return rounded / multiplier
+}

package/src/styles/components.entry.css

@@ -0,0 +1,8 @@
+/*
+ * Artifact A: components-only CSS (Tailwind ホスト向け).
+ * 手書きコンポーネントクラスのみ (resize-panels は大半のスタイルを JSX ユーティリティで持つため
+ * この成果物はほぼ空になる)。preflight・:root テーマ変数・ユーティリティは含まない
+ * (preflight を Tailwind ホストへ流し込むとホストの base 層を破壊するため厳禁)。
+ */
+@import "tailwindcss/theme.css" theme(reference);
+@import "./resize-panels.css";

package/src/styles/resize-panels.css

@@ -0,0 +1,3 @@
+@layer components {
+  /* nothing */
+}

package/src/styles/standalone.entry.css

@@ -0,0 +1,12 @@
+/*! @aiquants/resize-panels standalone CSS — 非 Tailwind ホスト専用。ホストの Tailwind ビルドと混在させないこと */
+/*
+ * Artifact B: 自己完結スタンドアロン. 非 Tailwind ホストの利便のため preflight を同梱する
+ * (Tailwind ホストはホスト自身の preflight があるので Artifact A を使うこと)。
+ */
+@layer theme, base, components, utilities;
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/preflight.css" layer(base);
+@import "tailwindcss/utilities.css" layer(utilities) source(none);
+@import "./resize-panels.css" layer(components);
+@source "../**/*.{ts,tsx}";
+@custom-variant dark (&:where(.dark, .dark *));

package/src/types.ts

@@ -0,0 +1,288 @@
+/**
+ * @file Type definitions for the resizable panels components
+ * リサイザブルパネルコンポーネントの型定義
+ */
+
+import type { CSSProperties, ReactNode } from "react"
+
+/**
+ * Pixel threshold used to decide when panels snap closed or open.
+ * パネルのスナップ判定に利用するピクセル閾値。
+ */
+export const PANEL_SNAP_THRESHOLD = 12
+
+/**
+ * Default thickness in pixels for the resize handle interactive area.
+ * リサイズハンドルのインタラクティブ領域のデフォルト厚み (px)。
+ */
+export const PANEL_HANDLE_THICKNESS = 8
+
+/**
+ * Spacing in pixels between visual indicator dots in the handle.
+ * ハンドル内の視覚インジケーター点同士のピクセル間隔。
+ */
+export const PANEL_VISIBLE_INDICATOR_SPACING = 8
+
+/**
+ * Pointer move throttling interval in milliseconds during dragging.
+ * ドラッグ中のポインタ移動を間引くミリ秒単位の間隔。
+ */
+export const PANEL_HANDLE_DRAG_THROTTLE_MS = 8
+
+/**
+ * Pixel step applied per arrow-key press when resizing with the keyboard.
+ * キーボード (矢印キー) リサイズで 1 押下ごとに適用するピクセル量。
+ */
+export const PANEL_KEYBOARD_RESIZE_STEP = 10
+
+/**
+ * Ratio of container size used when determining collapse thresholds.
+ * 折りたたみ閾値を決定する際に使用するコンテナサイズ比率。
+ */
+export const PANEL_COLLAPSE_THRESHOLD_RATIO = 0.05
+
+/**
+ * Maximum pixel value considered when collapsing panels.
+ * パネルを折りたたむ際に考慮するピクセル上限値。
+ */
+export const PANEL_COLLAPSE_THRESHOLD_MAX = 10
+
+/**
+ * Ratio of container size required to expand a collapsed panel.
+ * 折りたたまれたパネルを展開するために必要なコンテナサイズ比率。
+ */
+export const PANEL_EXPAND_THRESHOLD_RATIO = 0.05
+
+/**
+ * Maximum pixel threshold used when expanding panels.
+ * パネルを展開する際に用いるピクセル閾値の上限。
+ */
+export const PANEL_EXPAND_THRESHOLD_MAX = 20
+
+/**
+ * Minimum thickness required for a handle to be treated as visible.
+ * ハンドルが可視と判断されるために必要な最小厚み。
+ */
+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
+ * パネルのレイアウト方向
+ */
+export type PanelDirection = "horizontal" | "vertical"
+
+/**
+ * Size unit types for panels
+ * パネルのサイズ単位タイプ
+ */
+export type SizeUnit = "percentage" | "pixels"
+
+/**
+ * Size configuration with value and unit
+ * 値と単位を持つサイズ設定
+ */
+export type SizeConfig = {
+    value: number
+    unit: SizeUnit
+}
+
+/**
+ * Flexible size that can be defined in pixels or as a percentage
+ * ピクセルまたはパーセンテージで定義できる柔軟なサイズ
+ */
+export type FlexibleSize = SizeConfig | number
+
+/**
+ * Container size dimensions
+ * コンテナサイズの寸法
+ */
+export type ContainerSize = {
+    width: number
+    height: number
+}
+
+/**
+ * Direction from which collapsible panels may close.
+ * パネルを折りたためる方向を表す列挙値。
+ */
+export type PanelCollapseDirection = "start" | "end"
+
+/**
+ * Directional options accepted by the collapsible configuration.
+ * 折りたたみ設定が受け付ける方向指定値。
+ */
+export type CollapsibleDirection = PanelCollapseDirection | "both"
+
+/**
+ * Configuration object describing how a panel collapses.
+ * パネルの折りたたみ方を表す設定オブジェクト。
+ */
+export type CollapsibleConfig = {
+    from: CollapsibleDirection
+}
+
+/**
+ * Axis-aligned container measurement including inner (borderless) and outer dimensions.
+ * 枠線控除後と控除前の両方の寸法を含む軸方向コンテナ計測値。
+ */
+export type ContainerAxisMeasurement = {
+    inner: number
+    outer: number
+}
+
+/**
+ * Snapshot describing when panel constraints conflict with the container size.
+ * パネル制約とコンテナサイズが矛盾する際のスナップショット。
+ */
+export type LayoutConstraintViolationReason = "minimum-exceeded" | "maximum-insufficient"
+
+export type LayoutConstraintViolation = {
+    reason: LayoutConstraintViolationReason
+    totalMinimumSize: number | null
+    totalMaximumSize: number | null
+    availableContainerSize: number
+}
+
+/**
+ * Layout data for a single panel
+ * 単一パネルのレイアウトデータ
+ */
+export interface PanelLayoutData {
+    id: string
+    size: number
+    percentageSize?: number
+    preferredPercentageSize?: number
+    preferredPixelSize?: number
+    sizeUnit: SizeUnit
+    originalPixelSize?: number
+    minSize?: FlexibleSize
+    maxSize?: FlexibleSize
+    autoMinSize?: FlexibleSize
+    collapseFromStart: boolean
+    collapseFromEnd: boolean
+    collapsedByDirection?: PanelCollapseDirection | null
+    /**
+     * Skip automatic growth for flexible panels that were manually reduced to a zero footprint.
+     * 手動でゼロ相当まで縮めた柔軟パネルを自動拡張対象から外すフラグ。
+     */
+    excludeFromAutoGrowth?: boolean
+    collapsed?: boolean
+    sizeBeforeCollapse?: number
+    percentageSizeBeforeCollapse?: number
+    preferredPercentageSizeBeforeCollapse?: number
+    preferredPixelSizeBeforeCollapse?: number
+    pixelAdjustPriority?: number
+    flexAdjustPriority?: number
+    measuredPixelSize?: number
+    measuredPercentageSize?: number
+    measuredPixelSizeBeforeCollapse?: number
+}
+
+/**
+ * Props for the Panel component
+ * Panel コンポーネントのプロパティ
+ */
+export interface PanelProps {
+    id?: string
+    defaultSize?: FlexibleSize
+    minSize?: FlexibleSize
+    maxSize?: FlexibleSize
+    autoMinSize?: FlexibleSize
+    className?: string
+    style?: CSSProperties
+    children?: ReactNode
+    order?: number
+    collapsible?: CollapsibleConfig
+    defaultCollapsed?: boolean
+    pixelAdjustPriority?: number
+    flexAdjustPriority?: number
+    contentOverflow?: CSSProperties["overflow"]
+}
+
+/**
+ * Props for the PanelGroup component
+ * PanelGroup コンポーネントのプロパティ
+ */
+export interface PanelGroupProps {
+    id?: string
+    direction: PanelDirection
+    storageKey?: string
+    className?: string
+    style?: React.CSSProperties
+    children?: ReactNode
+    showDebugInfo?: boolean
+    onLayout?: (panelSizes: number[]) => void
+    autoSaveId?: string
+}
+
+/**
+ * Value provided by the PanelGroupContext
+ * PanelGroupContext によって提供される値
+ */
+export interface PanelGroupContextValue {
+    direction: PanelDirection
+    registerPanel: (panel: PanelLayoutData) => void
+    unregisterPanel: (id: string) => void
+    getPanel: (id: string) => PanelLayoutData | undefined
+    panels: PanelLayoutData[]
+    isContainerReady: boolean
+    showDebugInfo: boolean
+    resizePanels: (leftId: string, rightId: string, leftSize: number, rightSize: 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
+    handleMeasurements: Record<string, ResizeHandleLayoutData>
+    layoutConstraintViolation: LayoutConstraintViolation | null
+}
+
+/**
+ * Props for the PanelResizeHandle component
+ * PanelResizeHandle コンポーネントのプロパティ
+ */
+export interface PanelResizeHandleProps {
+    id?: string
+    disabled?: boolean
+    onDragging?: (isDragging: boolean) => void
+    className?: string
+    style?: React.CSSProperties
+    children?: ReactNode
+}
+
+export interface PanelMeasurement {
+    pixelSize: number
+    percentageSize: number
+}
+
+/**
+ * Layout data for a resize handle (divider) within a panel group.
+ * パネルグループ内のリサイズハンドル(ディバイダー)に関するレイアウトデータ。
+ */
+export interface ResizeHandleLayoutData {
+    id: string
+    thickness: number
+    direction: PanelDirection
+    visible: boolean
+    startPanelId?: string | null
+    endPanelId?: string | null
+}

package/src/utils/simple-logger.ts

@@ -0,0 +1,186 @@
+/**
+ * @module utils/logger
+ * @description Logger utility for consistent log management across the application.
+ * @description アプリケーション全体で一貫したログ管理を行うためのロガーユーティリティ。
+ */
+
+/**
+ * @enum LogLevel
+ * @description Log levels for filtering output.
+ * @description 出力をフィルタリングするためのログレベル。
+ */
+export enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4,
+}
+
+/**
+ * @interface ILogger
+ * @description Interface for a logger object compatible with Console.
+ * @description Console と互換性のあるロガーオブジェクトのインターフェース。
+ */
+export interface ILogger {
+    debug(message?: unknown, ...optionalParams: unknown[]): void
+    info(message?: unknown, ...optionalParams: unknown[]): void
+    warn(message?: unknown, ...optionalParams: unknown[]): void
+    error(message?: unknown, ...optionalParams: unknown[]): void
+}
+
+/**
+ * @class Logger
+ * @description A wrapper class for handling logging with levels and prefixes.
+ * @description レベルとプレフィックスを使用したログ記録を処理するためのラッパークラス。
+ */
+export class Logger implements ILogger {
+    private level: LogLevel
+    private prefix: string
+    private impl: ILogger
+
+    /**
+     * Registry of all constructed loggers so the static configuration API can reach them.
+     * static 設定 API が全ロガーへ到達できるようにするための生成済みインスタンスの登録簿。
+     */
+    private static readonly instances = new Set<Logger>()
+
+    /**
+     * @constructor
+     * @param {LogLevel} [level=LogLevel.WARN] - The minimum log level to output.
+     * @param {string} [prefix="[resize-panels]"] - The prefix to add to all log messages.
+     * @param {ILogger} [impl=console] - The implementation to use for logging.
+     */
+    constructor(level: LogLevel = LogLevel.WARN, prefix: string = "[resize-panels]", impl: ILogger = console) {
+        this.level = level
+        this.prefix = prefix
+        this.impl = impl
+        Logger.instances.add(this)
+    }
+
+    private static instance: Logger = new Logger(LogLevel.WARN, "[resize-panels]")
+
+    /**
+     * @method setLevel
+     * @description Updates the log level for every constructed logger (module-level loggers included).
+     * @description 生成済みのすべてのロガー (モジュールレベルのロガーを含む) のログレベルを更新します。
+     * @param {LogLevel} level - The new log level.
+     */
+    static setLevel(level: LogLevel): void {
+        for (const instance of Logger.instances) {
+            instance.setLevel(level)
+        }
+    }
+
+    /**
+     * @method setLevel
+     * @description Updates the current log level.
+     * @description 現在のログレベルを更新します。
+     * @param {LogLevel} level - The new log level.
+     */
+    setLevel(level: LogLevel): void {
+        this.level = level
+    }
+
+    /**
+     * @method setImplementation
+     * @description Updates the logger implementation for every constructed logger.
+     * @description 生成済みのすべてのロガーの実装を更新します。
+     * @param {ILogger} impl - The new logger implementation.
+     */
+    static setImplementation(impl: ILogger): void {
+        for (const instance of Logger.instances) {
+            instance.setImplementation(impl)
+        }
+    }
+
+    /**
+     * @method setImplementation
+     * @description Updates the logger implementation.
+     * @description ロガーの実装を更新します。
+     * @param {ILogger} impl - The new logger implementation.
+     */
+    setImplementation(impl: ILogger): void {
+        this.impl = impl
+    }
+
+    /**
+     * @method setPrefix
+     * @description Updates the log prefix for every constructed logger.
+     * @description 生成済みのすべてのロガーのログのプレフィックスを更新します。
+     * @param {string} prefix - The new prefix.
+     */
+    static setPrefix(prefix: string): void {
+        for (const instance of Logger.instances) {
+            instance.setPrefix(prefix)
+        }
+    }
+
+    /**
+     * @method setPrefix
+     * @description Updates the log prefix.
+     * @description ログのプレフィックスを更新します。
+     * @param {string} prefix - The new prefix.
+     */
+    setPrefix(prefix: string): void {
+        this.prefix = prefix
+    }
+
+    /**
+     * @method enabledFor
+     * @description Returns whether messages at the given level would be emitted.
+     * @description 指定レベルのメッセージが出力対象かどうかを返します。
+     * 高コストなログ引数 (スナップショット等) の組み立てを抑制中に省略するために使用します。
+     * @param {LogLevel} level - The message level to test.
+     */
+    enabledFor(level: LogLevel): boolean {
+        return this.level <= level
+    }
+
+    private formatMessage(message: unknown): unknown[] {
+        if (typeof message === "string") {
+            return [`${this.prefix} ${message}`]
+        }
+        return [this.prefix, message]
+    }
+
+    static debug(message?: unknown, ...optionalParams: unknown[]): void {
+        Logger.instance.debug(message, ...optionalParams)
+    }
+
+    debug(message?: unknown, ...optionalParams: unknown[]): void {
+        if (this.level <= LogLevel.DEBUG) {
+            this.impl.debug(...this.formatMessage(message), ...optionalParams)
+        }
+    }
+
+    static info(message?: unknown, ...optionalParams: unknown[]): void {
+        Logger.instance.info(message, ...optionalParams)
+    }
+
+    info(message?: unknown, ...optionalParams: unknown[]): void {
+        if (this.level <= LogLevel.INFO) {
+            this.impl.info(...this.formatMessage(message), ...optionalParams)
+        }
+    }
+
+    static warn(message?: unknown, ...optionalParams: unknown[]): void {
+        Logger.instance.warn(message, ...optionalParams)
+    }
+
+    warn(message?: unknown, ...optionalParams: unknown[]): void {
+        if (this.level <= LogLevel.WARN) {
+            this.impl.warn(...this.formatMessage(message), ...optionalParams)
+        }
+    }
+
+    static error(message?: unknown, ...optionalParams: unknown[]): void {
+        Logger.instance.error(message, ...optionalParams)
+    }
+
+    error(message?: unknown, ...optionalParams: unknown[]): void {
+        if (this.level <= LogLevel.ERROR) {
+            this.impl.error(...this.formatMessage(message), ...optionalParams)
+        }
+    }
+}