react-panel-layout 0.5.2 → 0.6.1

package/dist/modules/dialog/SwipeDialogContainer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file Swipeable dialog container component.
+ *
+ * This component extends the base dialog functionality with swipe-to-dismiss
+ * and multi-phase animations. It uses native <dialog> element for top layer
+ * positioning and custom transform animations.
+ */
+import * as React from "react";
+import type { DialogContainerProps } from "./types.js";
+/**
+ * Swipeable dialog container with multi-phase animation.
+ *
+ * Uses native <dialog> for top layer positioning and custom JS animations
+ * for swipe-to-dismiss functionality.
+ */
+export declare const SwipeDialogContainer: React.FC<DialogContainerProps>;

package/dist/modules/dialog/dialogAnimationUtils.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @file Dialog animation utilities
+ *
+ * Provides multi-phase animation calculations and viewTransition support
+ * for dialog open/close animations with "suck in" effect.
+ */
+/**
+ * Direction from which the dialog opens.
+ * The close animation uses the opposite direction.
+ */
+export type DialogOpenDirection = "center" | "top" | "bottom" | "left" | "right";
+/**
+ * Transform values for dialog animation.
+ */
+export type DialogTransform = {
+    /** Translate value in pixels (x or y depending on direction) */
+    translate: number;
+    /** Scale value (1 = normal, 0.85 = final suck-in) */
+    scale: number;
+    /** Backdrop opacity (1 = fully visible, 0 = transparent) */
+    backdropOpacity: number;
+};
+/**
+ * Axis for the dialog animation based on direction.
+ */
+export type DialogAnimationAxis = "x" | "y";
+/**
+ * Get the animation axis for a given direction.
+ */
+export declare function getAnimationAxis(direction: DialogOpenDirection): DialogAnimationAxis;
+/**
+ * Get the sign multiplier for translate based on direction.
+ * Positive means moving in the positive axis direction.
+ */
+export declare function getDirectionSign(direction: DialogOpenDirection): number;
+/**
+ * Compute the close animation transform values.
+ *
+ * The close animation has two phases:
+ * - Phase 1 (0-70%): Translate movement with easeOutExpo (natural deceleration)
+ * - Phase 2 (70-100%): Scale shrink + accelerated translate with easeInExpo ("suck in" effect)
+ *
+ * @param progress - Animation progress (0 = open, 1 = fully closed)
+ * @param containerSize - Size of the container in the animation direction (width or height)
+ * @param direction - Direction the dialog is closing towards
+ * @returns Transform values for the current progress
+ */
+export declare function computeCloseTransform(progress: number, containerSize: number, direction?: DialogOpenDirection): DialogTransform;
+/**
+ * Compute the open animation transform values.
+ * This is the reverse of the close animation.
+ *
+ * @param progress - Animation progress (0 = closed, 1 = fully open)
+ * @param containerSize - Size of the container in the animation direction
+ * @param direction - Direction the dialog is opening from
+ * @returns Transform values for the current progress
+ */
+export declare function computeOpenTransform(progress: number, containerSize: number, direction?: DialogOpenDirection): DialogTransform;
+/**
+ * Compute transform values during a swipe gesture.
+ * This provides real-time feedback as the user swipes.
+ *
+ * @param displacement - Current swipe displacement in pixels
+ * @param containerSize - Size of the container in the animation direction
+ * @returns Transform values for current swipe state
+ */
+export declare function computeSwipeTransform(displacement: number, containerSize: number): DialogTransform;
+/**
+ * Check if the swipe should trigger a dismiss action.
+ *
+ * @param displacement - Final swipe displacement in pixels
+ * @param velocity - Final swipe velocity in px/ms
+ * @param containerSize - Size of the container
+ * @param threshold - Threshold ratio (0-1) for dismiss (default: 0.3)
+ * @returns Whether the dialog should be dismissed
+ */
+export declare function shouldDismiss(displacement: number, velocity: number, containerSize: number, threshold?: number): boolean;
+/**
+ * Get the close direction based on swipe displacement.
+ * The dialog closes in the direction of the swipe.
+ *
+ * @param displacementX - Horizontal displacement
+ * @param displacementY - Vertical displacement
+ * @param defaultDirection - Default direction if no clear winner
+ * @returns The determined close direction
+ */
+export declare function getCloseDirectionFromSwipe(displacementX: number, displacementY: number, defaultDirection?: DialogOpenDirection): DialogOpenDirection;
+/**
+ * Check if View Transitions API is supported.
+ */
+export declare function supportsViewTransitions(): boolean;
+/**
+ * Execute a callback with View Transitions API, with fallback.
+ *
+ * @param callback - The DOM-changing callback to wrap
+ * @returns Promise<boolean> - true if viewTransition was used, false if fallback
+ */
+export declare function safeViewTransition(callback: () => void): Promise<boolean>;
+/**
+ * Build CSS transform string from transform values.
+ *
+ * @param transform - Transform values
+ * @param axis - Animation axis ('x' or 'y')
+ * @returns CSS transform string
+ */
+export declare function buildTransformString(transform: DialogTransform, axis: DialogAnimationAxis): string;
+/**
+ * Build CSS for backdrop based on transform values.
+ *
+ * @param transform - Transform values
+ * @returns CSS properties for backdrop
+ */
+export declare function buildBackdropStyle(transform: DialogTransform): React.CSSProperties;

package/dist/modules/dialog/types.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @file Dialog module type definitions
+ */
+import type * as React from "react";
+import type { Position } from "../../types";
+/**
+ * Transition mode for dialog animations
+ * - "none": No animation
+ * - "css": CSS-based fade/scale animation
+ * - "swipe": Swipeable with multi-phase animation
+ */
+export type DialogTransitionMode = "none" | "css" | "swipe";
+/**
+ * Direction from which the dialog opens.
+ * The close animation uses the same direction (swipe down to close if opened from bottom).
+ */
+export type DialogOpenDirection = "center" | "top" | "bottom" | "left" | "right";
+/**
+ * Base props for DialogContainer component
+ */
+export type DialogContainerProps = {
+    /** Whether the dialog is visible */
+    visible: boolean;
+    /** Callback when dialog should close */
+    onClose: () => void;
+    /** Dialog content */
+    children: React.ReactNode;
+    /** Position: 'center' for screen center, or Position for absolute coordinates */
+    position?: "center" | Position;
+    /** Whether clicking backdrop closes the dialog */
+    dismissible?: boolean;
+    /** Whether pressing Escape closes the dialog */
+    closeOnEscape?: boolean;
+    /** Whether to prevent body scroll when open */
+    preventBodyScroll?: boolean;
+    /** Whether to return focus to previous element on close */
+    returnFocus?: boolean;
+    /** Aria label for the dialog */
+    ariaLabel?: string;
+    /** ID of element that labels the dialog */
+    ariaLabelledBy?: string;
+    /** ID of element that describes the dialog */
+    ariaDescribedBy?: string;
+    /** Transition mode */
+    transitionMode?: DialogTransitionMode;
+    /** Transition duration (CSS value, e.g. '200ms') */
+    transitionDuration?: string;
+    /** Transition easing (CSS value, e.g. 'ease-out') */
+    transitionEasing?: string;
+    /** Whether the dialog can be dismissed by swiping. @default false for "css", true for "swipe" */
+    swipeDismissible?: boolean;
+    /** Direction the dialog opens from (used for swipe mode). @default "center" */
+    openDirection?: DialogOpenDirection;
+    /** Whether to use viewTransition API for close animation (when available). @default false */
+    useViewTransition?: boolean;
+};
+/**
+ * Header configuration for Modal
+ */
+export type ModalHeader = {
+    /** Title displayed in the header */
+    title: string;
+    /** Whether to show close button (default: true) */
+    showCloseButton?: boolean;
+};
+/**
+ * Props for Modal component
+ */
+export type ModalProps = Omit<DialogContainerProps, "position"> & {
+    /** Header configuration */
+    header?: ModalHeader;
+    /** Modal width */
+    width?: string | number;
+    /** Modal height */
+    height?: string | number;
+    /** Max width (default: 90vw) */
+    maxWidth?: string | number;
+    /** Max height (default: 85vh) */
+    maxHeight?: string | number;
+    /** Whether to use FloatingPanelFrame chrome (default: true) */
+    chrome?: boolean;
+    /** Custom content style */
+    contentStyle?: React.CSSProperties;
+};
+/**
+ * Options for alert dialog
+ */
+export type AlertOptions = {
+    /** Optional title */
+    title?: string;
+    /** Message to display */
+    message: string;
+    /** OK button label (default: 'OK') */
+    okLabel?: string;
+};
+/**
+ * Options for confirm dialog
+ */
+export type ConfirmOptions = AlertOptions & {
+    /** Confirm button label (default: 'OK') */
+    confirmLabel?: string;
+    /** Cancel button label (default: 'Cancel') */
+    cancelLabel?: string;
+};
+/**
+ * Options for prompt dialog
+ */
+export type PromptOptions = ConfirmOptions & {
+    /** Default input value */
+    defaultValue?: string;
+    /** Placeholder text for input */
+    placeholder?: string;
+    /** Input type (default: 'text') */
+    inputType?: "text" | "password" | "email" | "number";
+};
+/**
+ * Internal state for dialog queue
+ */
+export type DialogQueueItem = {
+    type: "alert";
+    options: AlertOptions;
+    resolve: (value: void) => void;
+} | {
+    type: "confirm";
+    options: ConfirmOptions;
+    resolve: (value: boolean) => void;
+} | {
+    type: "prompt";
+    options: PromptOptions;
+    resolve: (value: string | null) => void;
+};
+/**
+ * Return type of useDialog hook
+ */
+export type UseDialogReturn = {
+    /** Show an alert dialog */
+    alert: (options: AlertOptions | string) => Promise<void>;
+    /** Show a confirm dialog */
+    confirm: (options: ConfirmOptions | string) => Promise<boolean>;
+    /** Show a prompt dialog */
+    prompt: (options: PromptOptions | string) => Promise<string | null>;
+    /** Outlet component to render dialogs */
+    Outlet: React.FC;
+};
+/**
+ * Props for useDialog hook
+ */
+export type UseDialogProps = {
+    /**
+     * Custom component to render alert/confirm/prompt dialogs.
+     * When provided, replaces the default AlertDialog component.
+     */
+    alertDialogComponent?: React.ComponentType<AlertDialogProps>;
+};
+/**
+ * Props for AlertDialog component (internal)
+ */
+export type AlertDialogProps = {
+    /** Dialog type */
+    type: "alert" | "confirm" | "prompt";
+    /** Whether the dialog is visible */
+    visible: boolean;
+    /** Title */
+    title?: string;
+    /** Message */
+    message: string;
+    /** OK/Confirm button label */
+    confirmLabel?: string;
+    /** Cancel button label */
+    cancelLabel?: string;
+    /** Placeholder for prompt input */
+    placeholder?: string;
+    /** Default value for prompt input */
+    defaultValue?: string;
+    /** Input type for prompt */
+    inputType?: "text" | "password" | "email" | "number";
+    /** Callback for confirm/OK action */
+    onConfirm: (value?: string) => void;
+    /** Callback for cancel action */
+    onCancel: () => void;
+    /** Whether the dialog can be dismissed by swiping. @default false for alert, true for confirm/prompt */
+    swipeDismissible?: boolean;
+};

package/dist/modules/dialog/useDialog.d.ts

@@ -0,0 +1,39 @@
+import type { UseDialogReturn, UseDialogProps } from "./types";
+/**
+ * Hook for imperative alert/confirm/prompt dialogs.
+ *
+ * Returns functions to show dialogs and an Outlet component that must be rendered.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { alert, confirm, prompt, Outlet } = useDialog();
+ *
+ *   const handleClick = async () => {
+ *     await alert("Hello!");
+ *
+ *     const confirmed = await confirm({
+ *       message: "Are you sure?",
+ *       confirmLabel: "Yes",
+ *       cancelLabel: "No",
+ *     });
+ *
+ *     if (confirmed) {
+ *       const name = await prompt({
+ *         message: "Enter your name:",
+ *         defaultValue: "Anonymous",
+ *       });
+ *       console.log("Name:", name);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <button onClick={handleClick}>Show dialogs</button>
+ *       <Outlet />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare const useDialog: (props?: UseDialogProps) => UseDialogReturn;

package/dist/modules/dialog/useDialogContainer.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @file Hook for managing dialog element lifecycle
+ */
+import * as React from "react";
+export type UseDialogContainerOptions = {
+    /** Whether the dialog is visible */
+    visible: boolean;
+    /** Callback when dialog should close */
+    onClose: () => void;
+    /** Whether clicking backdrop closes the dialog (default: true) */
+    dismissible?: boolean;
+    /** Whether pressing Escape closes the dialog (default: true) */
+    closeOnEscape?: boolean;
+    /** Whether to return focus to previous element on close (default: true) */
+    returnFocus?: boolean;
+    /** Whether to prevent body scroll when open (default: true) */
+    preventBodyScroll?: boolean;
+};
+export type UseDialogContainerReturn = {
+    /** Ref to attach to the dialog element */
+    dialogRef: React.RefObject<HTMLDialogElement | null>;
+    /** Props to spread onto the dialog element */
+    dialogProps: {
+        onCancel: (event: React.SyntheticEvent) => void;
+        onClick: (event: React.MouseEvent<HTMLDialogElement>) => void;
+    };
+};
+/**
+ * Hook for managing native dialog element lifecycle
+ *
+ * @example
+ * ```tsx
+ * function MyDialog({ visible, onClose }) {
+ *   const { dialogRef, dialogProps } = useDialogContainer({
+ *     visible,
+ *     onClose,
+ *   });
+ *
+ *   return (
+ *     <dialog ref={dialogRef} {...dialogProps}>
+ *       <div>Dialog content</div>
+ *     </dialog>
+ *   );
+ * }
+ * ```
+ */
+export declare const useDialogContainer: (options: UseDialogContainerOptions) => UseDialogContainerReturn;

package/dist/modules/dialog/useDialogSwipeInput.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @file Hook for detecting swipe gestures to dismiss a dialog.
+ *
+ * This hook provides free 2D movement during swipe:
+ * - User can drag in any direction freely
+ * - Close intent is detected on release based on displacement direction
+ * - If movement matches close direction and exceeds threshold, dismiss
+ * - Otherwise, snap back to original position
+ */
+import * as React from "react";
+import { type ContinuousOperationState, type Vector2 } from "../../hooks/gesture/types.js";
+import type { DialogOpenDirection } from "./dialogAnimationUtils.js";
+/**
+ * Options for useDialogSwipeInput hook.
+ */
+export type UseDialogSwipeInputOptions = {
+    /** Ref to the dialog container element */
+    containerRef: React.RefObject<HTMLElement | null>;
+    /** Direction the dialog opened from (swipe closes in same direction) */
+    openDirection: DialogOpenDirection;
+    /** Whether swipe dismiss is enabled */
+    enabled: boolean;
+    /** Callback when swipe exceeds threshold and dialog should dismiss */
+    onSwipeDismiss: () => void;
+    /** Threshold ratio (0-1) of container size to trigger dismiss. @default 0.3 */
+    dismissThreshold?: number;
+};
+/**
+ * Result from useDialogSwipeInput hook.
+ */
+export type UseDialogSwipeInputResult = {
+    /** Current operation state (idle, operating, or ended) */
+    state: ContinuousOperationState;
+    /** Props to spread on the container element */
+    containerProps: React.HTMLAttributes<HTMLElement> & {
+        style: React.CSSProperties;
+    };
+    /** Swipe progress (0-1) towards dismiss threshold */
+    progress: number;
+    /** Whether user is currently swiping */
+    isOperating: boolean;
+    /** Current displacement in pixels (primary axis based on openDirection) */
+    displacement: number;
+    /** Full 2D displacement for free movement transform */
+    displacement2D: Vector2;
+};
+/**
+ * Hook for detecting swipe gestures to dismiss a dialog.
+ *
+ * Allows free 2D movement - user can drag in any direction.
+ * On release, detects if the movement matches the close direction:
+ * - "center" or "bottom": close if moved down significantly
+ * - "top": close if moved up significantly
+ * - "left": close if moved left significantly
+ * - "right": close if moved right significantly
+ *
+ * @example
+ * ```tsx
+ * const { state, containerProps, displacement2D } = useDialogSwipeInput({
+ *   containerRef,
+ *   openDirection: "bottom",
+ *   enabled: true,
+ *   onSwipeDismiss: () => setVisible(false),
+ * });
+ *
+ * // Apply 2D transform for free movement
+ * style={{ transform: `translate(${displacement2D.x}px, ${displacement2D.y}px)` }}
+ * ```
+ */
+export declare function useDialogSwipeInput(options: UseDialogSwipeInputOptions): UseDialogSwipeInputResult;

package/dist/modules/dialog/useDialogTransform.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @file Hook for managing dialog transform during swipe and animation.
+ *
+ * This hook provides:
+ * - Real-time transform updates during swipe gestures
+ * - Smooth open/close animations with multi-phase easing
+ * - Backdrop opacity animation
+ * - Support for viewTransition API (optional)
+ */
+import * as React from "react";
+import type { ContinuousOperationState } from "../../hooks/gesture/types.js";
+import type { DialogOpenDirection } from "./dialogAnimationUtils.js";
+/**
+ * Phase of dialog animation lifecycle.
+ */
+export type DialogAnimationPhase = "idle" | "opening" | "open" | "closing" | "closed";
+/**
+ * 2D displacement for free movement.
+ */
+export type Displacement2D = {
+    x: number;
+    y: number;
+};
+/**
+ * Options for useDialogTransform hook.
+ */
+export type UseDialogTransformOptions = {
+    /** Ref to the dialog content element */
+    elementRef: React.RefObject<HTMLElement | null>;
+    /** Ref to the backdrop element */
+    backdropRef: React.RefObject<HTMLElement | null>;
+    /** Whether the dialog is visible */
+    visible: boolean;
+    /** Direction the dialog opens from */
+    openDirection: DialogOpenDirection;
+    /** Current swipe state */
+    swipeState: ContinuousOperationState;
+    /** Current swipe displacement in pixels (primary axis) */
+    displacement: number;
+    /** Full 2D displacement for free movement */
+    displacement2D: Displacement2D;
+    /** Animation duration in ms. @default 350 */
+    animationDuration?: number;
+    /** Whether to use viewTransition API for close animation */
+    useViewTransition?: boolean;
+    /** Callback when open animation completes */
+    onOpenComplete?: () => void;
+    /** Callback when close animation completes */
+    onCloseComplete?: () => void;
+};
+/**
+ * Result from useDialogTransform hook.
+ */
+export type UseDialogTransformResult = {
+    /** Current animation phase */
+    phase: DialogAnimationPhase;
+    /** Whether any animation is running */
+    isAnimating: boolean;
+    /** Trigger close animation (use instead of setting visible=false directly) */
+    triggerClose: () => Promise<void>;
+};
+/**
+ * Hook for managing dialog transform during swipe and animation.
+ *
+ * During swipe: directly updates element transform based on displacement.
+ * After swipe: animates to target position (close or snap back).
+ * On visible change: animates open/close transition.
+ *
+ * @example
+ * ```tsx
+ * const { phase, isAnimating, triggerClose } = useDialogTransform({
+ *   elementRef,
+ *   backdropRef,
+ *   visible,
+ *   openDirection: "bottom",
+ *   swipeState: inputState,
+ *   displacement: inputDisplacement,
+ *   onCloseComplete: () => onClose(),
+ * });
+ * ```
+ */
+export declare function useDialogTransform(options: UseDialogTransformOptions): UseDialogTransformResult;

package/dist/modules/drawer/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @file Type definitions for Drawer swipe gesture handling.
+ */
+import type * as React from "react";
+import type { ContinuousOperationState } from "../../hooks/gesture/types.js";
+/**
+ * Direction for drawer anchor (same as anchor edge).
+ */
+export type DrawerSwipeDirection = "left" | "right" | "top" | "bottom";
+/**
+ * Options for useDrawerSwipeInput hook.
+ */
+export type UseDrawerSwipeInputOptions = {
+    /** Container ref for edge detection zone (e.g., GridLayout container) */
+    edgeContainerRef: React.RefObject<HTMLElement | null>;
+    /** Drawer content ref (for close gesture) */
+    drawerContentRef: React.RefObject<HTMLElement | null>;
+    /** Drawer direction (anchor edge) */
+    direction: DrawerSwipeDirection;
+    /** Whether the drawer is currently open */
+    isOpen: boolean;
+    /** Callback when swipe should open the drawer */
+    onSwipeOpen: () => void;
+    /** Callback when swipe should close the drawer */
+    onSwipeClose: () => void;
+    /** Whether edge swipe to open is enabled. @default true */
+    enableEdgeSwipeOpen?: boolean;
+    /** Whether swipe to close is enabled. @default true */
+    enableSwipeClose?: boolean;
+    /** Width of edge detection zone in pixels. @default 20 */
+    edgeWidth?: number;
+    /** Dismiss threshold ratio (0-1). @default 0.3 */
+    dismissThreshold?: number;
+};
+/**
+ * Result from useDrawerSwipeInput hook.
+ */
+export type UseDrawerSwipeInputResult = {
+    /** Current operation state */
+    state: ContinuousOperationState;
+    /** Whether currently opening via edge swipe */
+    isOpening: boolean;
+    /** Whether currently closing via drag */
+    isClosing: boolean;
+    /** Progress (0-1) towards open/close threshold */
+    progress: number;
+    /** Displacement in pixels (primary axis) */
+    displacement: number;
+    /** Props for edge container (open gesture zone) */
+    edgeContainerProps: React.HTMLAttributes<HTMLElement> & {
+        style: React.CSSProperties;
+    };
+    /** Props for drawer content (close gesture zone) */
+    drawerContentProps: React.HTMLAttributes<HTMLElement> & {
+        style: React.CSSProperties;
+    };
+};
+/**
+ * Get animation axis from direction.
+ */
+export declare function getDrawerAnimationAxis(direction: DrawerSwipeDirection): "x" | "y";
+/**
+ * Get the sign for the close swipe direction.
+ * Left drawer closes by swiping left (-1).
+ * Right drawer closes by swiping right (+1).
+ * Top drawer closes by swiping up (-1).
+ * Bottom drawer closes by swiping down (+1).
+ */
+export declare function getDrawerCloseSwipeSign(direction: DrawerSwipeDirection): 1 | -1;
+/**
+ * Get the sign for the open swipe direction.
+ * This is the opposite of the close direction.
+ */
+export declare function getDrawerOpenSwipeSign(direction: DrawerSwipeDirection): 1 | -1;

package/dist/modules/drawer/useDrawerSwipeInput.d.ts

@@ -0,0 +1,24 @@
+import type { UseDrawerSwipeInputOptions, UseDrawerSwipeInputResult } from "./types.js";
+/**
+ * Hook for detecting swipe gestures to open/close a drawer.
+ *
+ * When drawer is closed:
+ * - Detects edge swipe from the anchor edge to trigger open
+ *
+ * When drawer is open:
+ * - Detects drag gesture within drawer to trigger close
+ * - Respects scrollable content boundaries
+ *
+ * @example
+ * ```tsx
+ * const { state, edgeContainerProps, drawerContentProps } = useDrawerSwipeInput({
+ *   edgeContainerRef: gridLayoutRef,
+ *   drawerContentRef: drawerRef,
+ *   direction: "left",
+ *   isOpen,
+ *   onSwipeOpen: () => setOpen(true),
+ *   onSwipeClose: () => setOpen(false),
+ * });
+ * ```
+ */
+export declare function useDrawerSwipeInput(options: UseDrawerSwipeInputOptions): UseDrawerSwipeInputResult;

package/dist/modules/pivot/PivotContent.d.ts

@@ -23,7 +23,7 @@ export type PivotContentProps = {
 /**
  * Renders pivot content with CSS animation support.
  *
- * When transitionMode="css": Applies enter/leave animations.
+ * When transitionMode="css": Applies enter/leave animations with display:none when hidden.
  * When transitionMode="none": Uses React.Activity for memory optimization.
  */
 export declare const PivotContent: React.FC<PivotContentProps>;