react-panel-layout 0.5.2 → 0.6.1

package/dist/hooks/gesture/testing/createGestureSimulator.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @file Test utility for simulating gesture events.
+ *
+ * Provides a fluent API for simulating pointer events in tests,
+ * making it easier to test swipe and drag gestures.
+ */
+import type * as React from "react";
+/**
+ * 2D point for gesture coordinates.
+ */
+export type Point = {
+    x: number;
+    y: number;
+};
+/**
+ * Options for creating a gesture simulator.
+ */
+export type GestureSimulatorOptions = {
+    /** Container element or ref for coordinate calculations */
+    container?: HTMLElement | null;
+    /** Default pointer type. @default "touch" */
+    pointerType?: "touch" | "mouse" | "pen";
+    /** Default pointer ID. @default 1 */
+    pointerId?: number;
+};
+/**
+ * Gesture simulator for testing swipe and drag interactions.
+ */
+export type GestureSimulator = {
+    /**
+     * Simulate pointer down event.
+     * @param x - X coordinate
+     * @param y - Y coordinate
+     */
+    pointerDown: (x: number, y: number) => void;
+    /**
+     * Simulate pointer move event.
+     * @param x - X coordinate
+     * @param y - Y coordinate
+     */
+    pointerMove: (x: number, y: number) => void;
+    /**
+     * Simulate pointer up event.
+     */
+    pointerUp: () => void;
+    /**
+     * Simulate a complete swipe gesture.
+     * @param from - Starting point
+     * @param to - Ending point
+     * @param steps - Number of intermediate move events. @default 10
+     */
+    swipe: (from: Point, to: Point, steps?: number) => void;
+    /**
+     * Simulate an edge swipe gesture.
+     * @param edge - Edge to swipe from ("left" | "right" | "top" | "bottom")
+     * @param distance - Distance to swipe in pixels
+     * @param containerSize - Size of the container (width for left/right, height for top/bottom). @default 300
+     */
+    edgeSwipe: (edge: "left" | "right" | "top" | "bottom", distance: number, containerSize?: number) => void;
+    /**
+     * Create a React pointer event object for use with component handlers.
+     * @param type - Event type (pointerdown, pointermove, pointerup)
+     * @param x - X coordinate
+     * @param y - Y coordinate
+     */
+    createReactPointerEvent: (type: "pointerdown" | "pointermove" | "pointerup", x: number, y: number) => React.PointerEvent;
+};
+/**
+ * Creates a gesture simulator for testing.
+ *
+ * @example
+ * ```tsx
+ * const simulator = createGestureSimulator();
+ *
+ * // Simple pointer events
+ * simulator.pointerDown(100, 100);
+ * simulator.pointerMove(150, 100);
+ * simulator.pointerUp();
+ *
+ * // Complete swipe
+ * simulator.swipe({ x: 100, y: 100 }, { x: 200, y: 100 });
+ *
+ * // Edge swipe (iOS-style back gesture)
+ * simulator.edgeSwipe("left", 100);
+ * ```
+ */
+export declare function createGestureSimulator(options?: GestureSimulatorOptions): GestureSimulator;
+/**
+ * Creates a mock container element with specified dimensions.
+ *
+ * @example
+ * ```tsx
+ * const container = createMockContainer({ width: 300, height: 500 });
+ * const ref = { current: container };
+ * ```
+ */
+export declare function createMockContainer(options?: {
+    width?: number;
+    height?: number;
+    left?: number;
+    top?: number;
+}): HTMLDivElement;
+/**
+ * Creates a ref object with a mock container element.
+ *
+ * @example
+ * ```tsx
+ * const containerRef = createMockContainerRef({ width: 300, height: 500 });
+ * const { result } = renderHook(() => useSwipeInput({ containerRef, axis: "horizontal" }));
+ * ```
+ */
+export declare function createMockContainerRef(options?: {
+    width?: number;
+    height?: number;
+    left?: number;
+    top?: number;
+}): React.RefObject<HTMLDivElement>;

package/dist/hooks/gesture/thresholdValue.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @file ThresholdValue type and parsing utilities.
+ *
+ * Provides a flexible way to specify threshold values in either:
+ * - Absolute pixels: { value: 50, unit: "px" } or "50px"
+ * - Ratio of container: { value: 0.25, unit: "ratio" } or "25%"
+ */
+/**
+ * Parsed threshold value with explicit unit.
+ */
+export type ParsedThresholdValue = {
+    value: number;
+    unit: "px" | "ratio";
+};
+/**
+ * Threshold value input format.
+ * Accepts either an object with explicit unit or a string shorthand.
+ *
+ * @example
+ * // Object format
+ * { value: 50, unit: "px" }
+ * { value: 0.25, unit: "ratio" }
+ *
+ * // String shorthand
+ * "50px"   // 50 pixels
+ * "25%"    // 25% of container (ratio 0.25)
+ */
+export type ThresholdValue = ParsedThresholdValue | string;
+/**
+ * Parse a ThresholdValue input into a normalized ParsedThresholdValue.
+ *
+ * @param input - The threshold value to parse
+ * @returns Normalized threshold value object
+ * @throws Error if string format is invalid
+ */
+export declare function parseThresholdValue(input: ThresholdValue): ParsedThresholdValue;
+/**
+ * Resolve a threshold value to pixels given a container size.
+ *
+ * @param input - The threshold value (object or string)
+ * @param containerSize - The container size in pixels for ratio calculation
+ * @returns The threshold in pixels
+ */
+export declare function resolveThreshold(input: ThresholdValue, containerSize: number): number;

package/dist/hooks/gesture/types.d.ts

@@ -0,0 +1,297 @@
+/**
+ * @file Type definitions for gesture input detection hooks.
+ *
+ * These types support the separation of concerns:
+ * - Operation: what to do (navigate, push, pop)
+ * - Input: how to command (swipe, click, keyboard)
+ * - Presentation: how to show (animation, transition)
+ *
+ * This file defines types for the Input layer, including the abstract
+ * ContinuousOperationState that represents any continuous state transition
+ * (whether controlled by human gesture or system animation).
+ */
+import type * as React from "react";
+/**
+ * Axis for gesture detection.
+ */
+export type GestureAxis = "horizontal" | "vertical";
+/**
+ * 2D vector for displacement and velocity.
+ */
+export type Vector2 = {
+    x: number;
+    y: number;
+};
+/**
+ * Phase of a continuous operation lifecycle.
+ * - "idle": No operation in progress
+ * - "operating": Operation is in progress (human or system controlled)
+ * - "ended": Operation has completed
+ */
+export type ContinuousOperationPhase = "idle" | "operating" | "ended";
+/**
+ * State of a continuous operation.
+ *
+ * This is the abstract representation of any operation that occurs over time,
+ * whether controlled by human gesture or system animation. Components that
+ * accept this state can respond to both input types uniformly.
+ */
+export type ContinuousOperationState = {
+    /** Current phase of the operation */
+    phase: ContinuousOperationPhase;
+    /** Displacement from start position in pixels */
+    displacement: Vector2;
+    /** Current velocity in pixels per millisecond */
+    velocity: Vector2;
+};
+/**
+ * Initial idle state for ContinuousOperationState.
+ */
+export declare const IDLE_CONTINUOUS_OPERATION_STATE: ContinuousOperationState;
+/**
+ * Convert SwipeInputPhase to ContinuousOperationPhase.
+ * - "idle" → "idle"
+ * - "tracking" | "swiping" → "operating"
+ * - "ended" → "ended"
+ */
+export declare function toContinuousPhase(phase: SwipeInputPhase): ContinuousOperationPhase;
+/**
+ * Convert SwipeInputState to ContinuousOperationState.
+ */
+export declare function toContinuousOperationState(state: SwipeInputState): ContinuousOperationState;
+/**
+ * Phase of swipe input lifecycle.
+ * - "idle": No swipe in progress
+ * - "tracking": Pointer down, tracking movement (direction not yet locked)
+ * - "swiping": Direction locked, actively swiping
+ * - "ended": Swipe gesture completed
+ */
+export type SwipeInputPhase = "idle" | "tracking" | "swiping" | "ended";
+/**
+ * Point with timestamp for velocity calculation.
+ */
+export type TimestampedPoint = {
+    x: number;
+    y: number;
+    timestamp: number;
+};
+/**
+ * Swipe input state during gesture.
+ */
+export type SwipeInputState = {
+    /** Current phase of the swipe input */
+    phase: SwipeInputPhase;
+    /** Displacement from start position in pixels */
+    displacement: Vector2;
+    /** Current velocity in pixels per millisecond */
+    velocity: Vector2;
+    /**
+     * Direction of movement as a number.
+     * -1 = backward (left/up), 0 = no movement, 1 = forward (right/down)
+     */
+    direction: -1 | 0 | 1;
+};
+/**
+ * Thresholds for swipe input recognition.
+ */
+export type SwipeInputThresholds = {
+    /** Minimum distance in pixels to trigger swipe. @default 50 */
+    distanceThreshold: number;
+    /** Minimum velocity in px/ms to trigger swipe. @default 0.3 */
+    velocityThreshold: number;
+    /** Distance threshold before direction is locked. @default 10 */
+    lockThreshold: number;
+};
+/**
+ * Options for usePointerTracking hook.
+ */
+export type UsePointerTrackingOptions = {
+    /** Whether tracking is enabled */
+    enabled: boolean;
+    /** Restrict to primary pointer only (ignore multitouch). @default true */
+    primaryOnly?: boolean;
+};
+/**
+ * Result from usePointerTracking hook.
+ */
+export type UsePointerTrackingResult = {
+    /** Current tracking state */
+    state: PointerTrackingState;
+    /** Handler to attach to onPointerDown */
+    onPointerDown: (event: React.PointerEvent) => void;
+    /** Reset tracking state */
+    reset: () => void;
+};
+/**
+ * Internal pointer tracking state.
+ */
+export type PointerTrackingState = {
+    /** Whether pointer is currently down */
+    isDown: boolean;
+    /** Start position and timestamp */
+    start: TimestampedPoint | null;
+    /** Current position and timestamp */
+    current: TimestampedPoint | null;
+    /** Active pointer ID */
+    pointerId: number | null;
+    /** Whether tracking ended via pointercancel (not pointerup) */
+    wasCanceled: boolean;
+};
+/**
+ * Options for useDirectionalLock hook.
+ */
+export type UseDirectionalLockOptions = {
+    /** Pointer tracking state from usePointerTracking */
+    tracking: PointerTrackingState;
+    /** Lock threshold in pixels. @default 10 */
+    lockThreshold?: number;
+};
+/**
+ * Result from useDirectionalLock hook.
+ */
+export type UseDirectionalLockResult = {
+    /** Locked axis, or null if not yet locked */
+    lockedAxis: GestureAxis | null;
+    /** Whether lock has been determined */
+    isLocked: boolean;
+    /** Reset the lock state */
+    reset: () => void;
+};
+/**
+ * Options for useScrollBoundary hook.
+ */
+export type UseScrollBoundaryOptions = {
+    /** Scroll container ref. If null, checks document scroll. */
+    containerRef: React.RefObject<HTMLElement | null>;
+    /** Axis to monitor */
+    axis: GestureAxis;
+    /** Tolerance in pixels for "at boundary" detection. @default 1 */
+    tolerance?: number;
+};
+/**
+ * Result from useScrollBoundary hook.
+ */
+export type UseScrollBoundaryResult = {
+    /** Whether at the start boundary (top/left) */
+    atStart: boolean;
+    /** Whether at the end boundary (bottom/right) */
+    atEnd: boolean;
+    /** Current scroll position */
+    scrollPosition: number;
+    /** Maximum scroll position */
+    maxScrollPosition: number;
+};
+/**
+ * Filter function to determine if a pointer event should start tracking.
+ * Receives the pointer event and container element.
+ * Return true to allow tracking, false to ignore the event.
+ */
+export type PointerStartFilter = (event: React.PointerEvent, container: HTMLElement) => boolean;
+/**
+ * Options for useSwipeInput hook.
+ */
+export type UseSwipeInputOptions = {
+    /** Ref to the container element */
+    containerRef: React.RefObject<HTMLElement | null>;
+    /** Axis to detect swipes on */
+    axis: GestureAxis;
+    /** Whether swipe detection is enabled. @default true */
+    enabled?: boolean;
+    /** Swipe thresholds configuration */
+    thresholds?: Partial<SwipeInputThresholds>;
+    /** Callback when swipe is completed */
+    onSwipeEnd?: (state: SwipeInputState) => void;
+    /** Whether to enable trackpad two-finger swipe (wheel events). @default true */
+    enableWheel?: boolean;
+    /**
+     * Optional filter to determine if a pointer event should start tracking.
+     * If provided, only events that pass this filter will be tracked.
+     * Useful for edge-based swipe detection.
+     */
+    pointerStartFilter?: PointerStartFilter;
+};
+/**
+ * Result from useSwipeInput hook.
+ */
+export type UseSwipeInputResult = {
+    /** Current swipe input state */
+    state: SwipeInputState;
+    /** Props to spread on the container element */
+    containerProps: React.HTMLAttributes<HTMLElement> & {
+        style: React.CSSProperties;
+    };
+};
+/**
+ * Edge for edge-originated gestures.
+ */
+export type GestureEdge = "left" | "right" | "top" | "bottom";
+/**
+ * Options for useEdgeSwipeInput hook.
+ */
+export type UseEdgeSwipeInputOptions = {
+    /** Ref to the container element */
+    containerRef: React.RefObject<HTMLElement | null>;
+    /** Which edge to detect swipes from */
+    edge: GestureEdge;
+    /** Width of the edge detection zone in pixels. @default 20 */
+    edgeWidth?: number;
+    /** Whether edge swipe detection is enabled. @default true */
+    enabled?: boolean;
+    /** Swipe thresholds configuration */
+    thresholds?: Partial<SwipeInputThresholds>;
+    /** Callback when edge swipe is completed */
+    onSwipeEnd?: (state: SwipeInputState) => void;
+};
+/**
+ * Result from useEdgeSwipeInput hook.
+ */
+export type UseEdgeSwipeInputResult = {
+    /** Whether the current gesture started from the edge */
+    isEdgeGesture: boolean;
+    /** Current swipe input state */
+    state: SwipeInputState;
+    /** Props to spread on the container element */
+    containerProps: React.HTMLAttributes<HTMLElement> & {
+        style: React.CSSProperties;
+    };
+};
+/**
+ * Options for useNativeGestureGuard hook.
+ */
+export type UseNativeGestureGuardOptions = {
+    /** Ref to the container element */
+    containerRef: React.RefObject<HTMLElement | null>;
+    /** Whether the guard is active */
+    active: boolean;
+    /** Prevent iOS/macOS edge back gesture. @default true */
+    preventEdgeBack?: boolean;
+    /** Prevent overscroll bounce effect. @default true */
+    preventOverscroll?: boolean;
+    /** Width of edge zone where back gesture is prevented. @default 20 */
+    edgeWidth?: number;
+};
+/**
+ * Result from useNativeGestureGuard hook.
+ */
+export type UseNativeGestureGuardResult = {
+    /** Props to spread on the container element */
+    containerProps: React.HTMLAttributes<HTMLElement> & {
+        style: React.CSSProperties;
+    };
+};
+/**
+ * Default swipe input thresholds.
+ *
+ * - distanceThreshold: 100px is ~27% of a 375px mobile screen
+ * - velocityThreshold: 0.5px/ms = 500px/s, a moderate flick speed
+ * - lockThreshold: 10px before direction is locked
+ */
+export declare const DEFAULT_SWIPE_THRESHOLDS: SwipeInputThresholds;
+/**
+ * Default edge width for edge gesture detection.
+ */
+export declare const DEFAULT_EDGE_WIDTH = 20;
+/**
+ * Initial idle state for SwipeInputState.
+ */
+export declare const IDLE_SWIPE_INPUT_STATE: SwipeInputState;

package/dist/hooks/gesture/useDirectionalLock.d.ts

@@ -0,0 +1,20 @@
+import type { UseDirectionalLockOptions, UseDirectionalLockResult } from "./types.js";
+/**
+ * Hook for locking gesture direction after threshold is exceeded.
+ *
+ * This hook tracks pointer movement and locks to horizontal or vertical
+ * direction once the movement exceeds the configured threshold. This
+ * prevents diagonal gestures from triggering both scroll and swipe behaviors.
+ *
+ * @example
+ * ```tsx
+ * const { state: tracking, onPointerDown } = usePointerTracking({ enabled: true });
+ * const { lockedAxis, isLocked } = useDirectionalLock({
+ *   tracking,
+ *   lockThreshold: 10,
+ * });
+ *
+ * // lockedAxis will be "horizontal" or "vertical" once determined
+ * ```
+ */
+export declare function useDirectionalLock(options: UseDirectionalLockOptions): UseDirectionalLockResult;

package/dist/hooks/gesture/useEdgeSwipeInput.d.ts

@@ -0,0 +1,23 @@
+import type { UseEdgeSwipeInputOptions, UseEdgeSwipeInputResult } from "./types.js";
+/**
+ * Hook for detecting swipe gestures that originate from the edge of a container.
+ *
+ * This is useful for implementing "swipe back" navigation patterns where
+ * the user must start their swipe from the edge of the screen.
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const { isEdgeGesture, state, containerProps } = useEdgeSwipeInput({
+ *   containerRef,
+ *   edge: "left",
+ *   edgeWidth: 20,
+ *   onSwipeEnd: (state) => {
+ *     if (state.direction === 1) goBack();
+ *   },
+ * });
+ *
+ * return <div ref={containerRef} {...containerProps}>{children}</div>;
+ * ```
+ */
+export declare function useEdgeSwipeInput(options: UseEdgeSwipeInputOptions): UseEdgeSwipeInputResult;

package/dist/hooks/gesture/useNativeGestureGuard.d.ts

@@ -0,0 +1,23 @@
+import type { UseNativeGestureGuardOptions, UseNativeGestureGuardResult } from "./types.js";
+/**
+ * Hook for preventing conflicts with native OS gestures.
+ *
+ * When active, this hook:
+ * - Prevents iOS/macOS edge back gesture by capturing pointerdown events in the edge zone
+ * - Prevents overscroll bounce effect using CSS overscroll-behavior
+ * - Dynamically applies overscroll-behavior: none to html element during gesture
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const { containerProps } = useNativeGestureGuard({
+ *   containerRef,
+ *   active: isSwipeActive,
+ *   preventEdgeBack: true,
+ *   preventOverscroll: true,
+ * });
+ *
+ * return <div ref={containerRef} {...containerProps}>{children}</div>;
+ * ```
+ */
+export declare function useNativeGestureGuard(options: UseNativeGestureGuardOptions): UseNativeGestureGuardResult;

package/dist/hooks/gesture/usePointerTracking.d.ts

@@ -0,0 +1,22 @@
+import type { UsePointerTrackingOptions, UsePointerTrackingResult } from "./types.js";
+/**
+ * Hook for tracking pointer state during gestures.
+ *
+ * Tracks pointer down/move/up events and provides position and timing data
+ * that can be used by higher-level gesture detection hooks.
+ *
+ * @example
+ * ```tsx
+ * const { state, onPointerDown, reset } = usePointerTracking({
+ *   enabled: true,
+ *   primaryOnly: true,
+ * });
+ *
+ * return (
+ *   <div onPointerDown={onPointerDown}>
+ *     {state.isDown && <span>Tracking...</span>}
+ *   </div>
+ * );
+ * ```
+ */
+export declare function usePointerTracking(options: UsePointerTrackingOptions): UsePointerTrackingResult;

package/dist/hooks/gesture/useScrollBoundary.d.ts

@@ -0,0 +1,23 @@
+import type { UseScrollBoundaryOptions, UseScrollBoundaryResult } from "./types.js";
+/**
+ * Hook for detecting scroll position relative to boundaries.
+ *
+ * Monitors the scroll position of an element and reports whether it is
+ * at the start boundary (top/left) or end boundary (bottom/right).
+ * This is useful for enabling swipe gestures when content is scrolled to an edge.
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const { atStart, atEnd } = useScrollBoundary({
+ *   containerRef,
+ *   axis: "horizontal",
+ *   tolerance: 5,
+ * });
+ *
+ * // Enable swipe when at edge
+ * const canSwipeLeft = atStart;
+ * const canSwipeRight = atEnd;
+ * ```
+ */
+export declare function useScrollBoundary(options: UseScrollBoundaryOptions): UseScrollBoundaryResult;

package/dist/hooks/gesture/useSwipeInput.d.ts

@@ -0,0 +1,5 @@
+import type { UseSwipeInputOptions, UseSwipeInputResult } from "./types.js";
+/**
+ * Hook for detecting swipe gestures on a container element.
+ */
+export declare function useSwipeInput(options: UseSwipeInputOptions): UseSwipeInputResult;

package/dist/hooks/gesture/utils.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @file Utility functions for gesture detection hooks.
+ *
+ * Contains shared calculations and helper functions used across
+ * gesture-related hooks to avoid code duplication.
+ */
+import type * as React from "react";
+/**
+ * Calculate velocity from displacement and time elapsed.
+ *
+ * @param displacement - Distance traveled in pixels
+ * @param startTime - Start timestamp in milliseconds
+ * @param currentTime - Current timestamp in milliseconds
+ * @returns Velocity in pixels per millisecond
+ */
+export declare const calculateVelocity: (displacement: number, startTime: number, currentTime: number) => number;
+/**
+ * Determine direction from displacement.
+ *
+ * @param displacement - Distance from start position
+ * @returns -1 for backward (left/up), 0 for no movement, 1 for forward (right/down)
+ */
+export declare const determineDirection: (displacement: number) => -1 | 0 | 1;
+/**
+ * Container props type for gesture handling.
+ */
+export type GestureContainerProps = React.HTMLAttributes<HTMLElement> & {
+    style: React.CSSProperties;
+};
+/**
+ * Merge multiple container props objects for gesture handling.
+ *
+ * Combines style objects and chains onPointerDown handlers.
+ * Useful when combining multiple gesture hooks that each provide
+ * their own container props (e.g., swipe input + native gesture guard).
+ *
+ * @param propsArray - Array of container props to merge
+ * @returns Merged container props with combined styles and handlers
+ */
+export declare const mergeGestureContainerProps: (...propsArray: GestureContainerProps[]) => GestureContainerProps;
+/**
+ * Check if an element is scrollable in any direction.
+ */
+export declare function isScrollableElement(element: HTMLElement): boolean;
+/**
+ * Check if we should start drag based on scroll state.
+ * Returns false if the target is inside a scrollable element.
+ */
+export declare function shouldStartDrag(event: React.PointerEvent, container: HTMLElement): boolean;
+/**
+ * Check if an element or its ancestors are scrollable in the specified direction.
+ * Returns true if scrolling is possible and would block the swipe gesture.
+ *
+ * @param element - The target element to check
+ * @param container - The container boundary
+ * @param axis - The axis to check ("x" or "y")
+ * @param direction - The swipe direction (1 = right/down, -1 = left/up)
+ */
+export declare function isScrollableInDirection(element: HTMLElement, container: HTMLElement, axis: "x" | "y", direction: 1 | -1): boolean;