react-panel-layout 0.5.2 → 0.6.0

package/dist/grid/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @file Grid entry point - Grid layout components and hooks
+ * @packageDocumentation
+ *
+ * This is a subpath export entry point for `react-panel-layout/grid`.
+ *
+ * ## Overview
+ * Grid provides CSS Grid-based layout components for arranging panels in rows
+ * and columns. Supports resizable tracks, draggable layers, and floating windows.
+ *
+ * ## Installation
+ * ```ts
+ * import { GridLayout } from "react-panel-layout/grid";
+ * ```
+ *
+ * ## Basic Usage
+ * ```tsx
+ * const config = {
+ *   areas: [
+ *     ['sidebar', 'main', 'main'],
+ *     ['sidebar', 'main', 'main'],
+ *   ],
+ *   columns: [{ size: '200px' }, { size: '1fr' }, { size: '1fr' }],
+ *   rows: [{ size: '1fr' }, { size: '1fr' }],
+ *   gap: '8px',
+ * };
+ *
+ * const layers = [
+ *   { id: 'sidebar', component: <Sidebar /> },
+ *   { id: 'main', component: <MainContent /> },
+ * ];
+ *
+ * function App() {
+ *   return <GridLayout config={config} layers={layers} />;
+ * }
+ * ```
+ *
+ * ## Resizable Tracks
+ * ```tsx
+ * const config = {
+ *   columns: [
+ *     { size: '200px', resizable: true, minSize: 100, maxSize: 400 },
+ *     { size: '1fr' },
+ *   ],
+ *   // ...
+ * };
+ * ```
+ */
+export { GridLayout } from "../components/grid/GridLayout.js";
+export { GridLayerList } from "../components/grid/GridLayerList.js";
+export { GridLayerResizeHandles } from "../components/grid/GridLayerResizeHandles.js";
+export { GridTrackResizeHandle } from "../components/grid/GridTrackResizeHandle.js";
+export { GridLayoutProvider, useGridLayoutContext, } from "../modules/grid/GridLayoutContext.js";
+export { useGridPlacements } from "../modules/grid/useGridPlacements.js";
+export { useGridTracks } from "../modules/grid/useGridTracks.js";
+export type { GridLayerHandleProps, ResizeHandleConfig, GridLayerRenderState, GridLayoutContextValue, } from "../modules/grid/GridLayoutContext.js";
+export type { GridLayoutProps } from "../components/grid/GridLayout.js";
+export type { TrackHandleConfig, TrackDirection } from "../modules/grid/useGridTracks.js";

package/dist/grid.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./GridLayout-B4VRsC0r.cjs"),r=require("./FloatingWindow-TCDNY5gE.cjs");exports.GridLayerList=e.GridLayerList;exports.GridLayerResizeHandles=e.GridLayerResizeHandles;exports.GridLayout=e.GridLayout;exports.GridTrackResizeHandle=e.GridTrackResizeHandle;exports.useGridPlacements=e.useGridPlacements;exports.useGridTracks=e.useGridTracks;exports.GridLayoutProvider=r.GridLayoutProvider;exports.useGridLayoutContext=r.useGridLayoutContext;
+//# sourceMappingURL=grid.cjs.map

package/dist/grid.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"grid.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/grid.js

@@ -0,0 +1,13 @@
+import { a as e, b as s, G as d, c as i, u as G, d as o } from "./GridLayout-BltqeCPK.js";
+import { G as u, u as L } from "./FloatingWindow-BpdOpg_L.js";
+export {
+  e as GridLayerList,
+  s as GridLayerResizeHandles,
+  d as GridLayout,
+  u as GridLayoutProvider,
+  i as GridTrackResizeHandle,
+  L as useGridLayoutContext,
+  G as useGridPlacements,
+  o as useGridTracks
+};
+//# sourceMappingURL=grid.js.map

package/dist/grid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grid.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}

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

@@ -0,0 +1,33 @@
+/**
+ * @file Platform-specific swipe gesture presets.
+ *
+ * Provides pre-configured threshold values for different platforms
+ * to match their native gesture behaviors.
+ */
+import type { SwipeInputThresholds } from "./types.js";
+/**
+ * Platform-specific swipe gesture presets.
+ *
+ * - ios: Matches iOS native swipe behavior (responsive, smooth)
+ * - android: Matches Android gesture behavior (slightly more tolerant)
+ * - desktop: For mouse-based interactions (larger thresholds)
+ * - relaxed: For contexts where accidental swipes should be avoided
+ */
+export declare const SWIPE_PRESETS: Record<string, SwipeInputThresholds>;
+/**
+ * Detect platform from user agent string and return appropriate preset.
+ *
+ * @param userAgent - Navigator userAgent string
+ * @returns Appropriate SwipeInputThresholds for the detected platform
+ *
+ * @example
+ * ```ts
+ * const thresholds = getSwipePreset(navigator.userAgent);
+ * const { state, containerProps } = useSwipeInput({
+ *   containerRef,
+ *   axis: "horizontal",
+ *   thresholds,
+ * });
+ * ```
+ */
+export declare function getSwipePreset(userAgent: string): SwipeInputThresholds;

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

@@ -0,0 +1,110 @@
+/**
+ * 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,254 @@
+/**
+ * @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.
+ */
+import type * as React from "react";
+/**
+ * Axis for gesture detection.
+ */
+export type GestureAxis = "horizontal" | "vertical";
+/**
+ * Phase of swipe input lifecycle.
+ */
+export type SwipeInputPhase = "idle" | "tracking" | "swiping" | "ended";
+/**
+ * 2D vector for displacement and velocity.
+ */
+export type Vector2 = {
+    x: number;
+    y: number;
+};
+/**
+ * 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;