react-panel-layout 0.5.1 → 0.6.0

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

@@ -0,0 +1,89 @@
+/**
+ * @file SwipePivotTabBar - Swipeable tab bar for pivot navigation with proper looping.
+ *
+ * Infinite loop model:
+ * - Uses continuous scroll offset (not discrete positions)
+ * - Renders tab slots at fixed positions, content determined by scroll offset
+ * - Clones tabs at boundaries for seamless looping
+ * - Each slot has stable key (by position), preventing remount jumps
+ */
+import * as React from "react";
+import type { SwipeInputState, GestureAxis } from "../../hooks/gesture/types.js";
+/**
+ * Props passed to the indicator render function.
+ * Use these to position a sliding indicator (iOS-style).
+ */
+export type IndicatorRenderProps = {
+    /** Current offset in pixels (includes swipe displacement and animation) */
+    offsetPx: number;
+    /** Width of each tab */
+    tabWidth: number;
+    /** Center X position where active tab is located */
+    centerX: number;
+    /** Whether currently swiping */
+    isSwiping: boolean;
+    /** Whether animation is in progress */
+    isAnimating: boolean;
+};
+export type SwipePivotTabBarProps<TId extends string = string> = {
+    /** Tab items to render */
+    items: ReadonlyArray<{
+        id: TId;
+        label?: string;
+    }>;
+    /** Currently active tab ID */
+    activeId: TId;
+    /** Index of active tab */
+    activeIndex: number;
+    /** Total number of items */
+    itemCount: number;
+    /** Current swipe input state */
+    inputState: SwipeInputState;
+    /** Width of each tab */
+    tabWidth: number;
+    /** Width of the visible viewport */
+    viewportWidth: number;
+    /** Navigation mode */
+    navigationMode?: "linear" | "loop";
+    /** Axis for swipe (horizontal or vertical) */
+    axis?: GestureAxis;
+    /** Render function for each tab */
+    renderTab: (item: {
+        id: TId;
+        label?: string;
+    }, isActive: boolean, index: number) => React.ReactNode;
+    /** Animation duration in ms */
+    animationDuration?: number;
+    /**
+     * When true, tabs stay at fixed positions and only the indicator moves.
+     * Use this for iOS segmented control style where the "window" slides over fixed tabs.
+     * @default false
+     */
+    fixedTabs?: boolean;
+    /**
+     * Optional render function for a sliding indicator (iOS-style).
+     * The indicator follows the active tab position during swipe and animation.
+     * Rendered behind the tabs.
+     *
+     * When used with fixedTabs=true, only the indicator moves while tabs stay fixed.
+     *
+     * @example
+     * ```tsx
+     * renderIndicator={({ offsetPx, tabWidth, centerX }) => (
+     *   <div
+     *     style={{
+     *       position: 'absolute',
+     *       left: centerX,
+     *       bottom: 0,
+     *       width: tabWidth,
+     *       height: 3,
+     *       backgroundColor: '#007AFF',
+     *       transform: `translateX(${offsetPx}px)`,
+     *     }}
+     *   />
+     * )}
+     * ```
+     */
+    renderIndicator?: (props: IndicatorRenderProps) => React.ReactNode;
+};
+export declare function SwipePivotTabBar<TId extends string = string>({ items, activeId, activeIndex, itemCount, inputState, tabWidth, viewportWidth, navigationMode, axis, renderTab, animationDuration, fixedTabs, renderIndicator, }: SwipePivotTabBarProps<TId>): React.ReactElement;

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

@@ -2,4 +2,7 @@
  * @file Pivot - Headless content switching system
  */
 export { usePivot } from "./usePivot";
+export { scaleInputState } from "./scaleInputState";
+export { SwipePivotTabBar } from "./SwipePivotTabBar";
+export type { SwipePivotTabBarProps, IndicatorRenderProps } from "./SwipePivotTabBar";
 export type { PivotItem, UsePivotOptions, UsePivotResult, PivotItemProps } from "./types";

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

@@ -0,0 +1,37 @@
+/**
+ * @file Utility for scaling SwipeInputState between containers of different sizes.
+ *
+ * This enables synchronized swipe behavior between containers with different widths,
+ * such as a narrow tab bar and a wide content area moving together proportionally.
+ */
+import type { SwipeInputState } from "../../hooks/gesture/types.js";
+/**
+ * Scale SwipeInputState displacement and velocity proportionally for different container sizes.
+ *
+ * When swiping in a container of one size, this function transforms the input state
+ * to appear as if the swipe occurred in a container of a different size.
+ * This allows tabs and content to move in sync despite different widths.
+ *
+ * @param inputState - The original swipe input state
+ * @param sourceWidth - Width of the source container (where the swipe originated)
+ * @param targetWidth - Width of the target container (where the scaled state will be applied)
+ * @returns Scaled SwipeInputState with proportionally adjusted displacement and velocity
+ *
+ * @example
+ * ```tsx
+ * // Content area is 400px wide, each tab is 80px wide (5 tabs)
+ * const contentWidth = 400;
+ * const tabWidth = 80;
+ *
+ * // Swipe happens on content area
+ * const { inputState } = usePivotSwipeInput({ containerRef, pivot, axis: "horizontal" });
+ *
+ * // Scale for tabs: 100px content swipe → 20px tab movement
+ * const tabInputState = scaleInputState(inputState, contentWidth, tabWidth);
+ *
+ * // Apply to tabs and content respectively
+ * <SwipePivotContent inputState={tabInputState} containerSize={tabWidth} />
+ * <SwipePivotContent inputState={inputState} containerSize={contentWidth} />
+ * ```
+ */
+export declare const scaleInputState: (inputState: SwipeInputState, sourceWidth: number, targetWidth: number) => SwipeInputState;

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

@@ -3,6 +3,12 @@
  * Pivot manages content switching within a scope without providing UI.
  */
 import type * as React from "react";
+/**
+ * Navigation mode for pivot.
+ * - "linear": Default. Stops at first/last item.
+ * - "loop": Infinite loop. Navigation wraps around.
+ */
+export type PivotNavigationMode = "linear" | "loop";
 /**
  * A single content item that can be displayed in a Pivot.
  */
@@ -15,6 +21,12 @@ export type PivotItem<TId extends string = string> = {
     content: React.ReactNode;
     /** Whether this item can be selected (defaults to true) */
     disabled?: boolean;
+    /**
+     * Enable content caching to preserve React component state across re-renders.
+     * When disabled (default), content is re-created on each render.
+     * @default false
+     */
+    cache?: boolean;
 };
 /**
  * Props for the usePivot hook.
@@ -34,6 +46,12 @@ export type UsePivotOptions<TId extends string = string> = {
      * - "none" disables transitions (uses React.Activity for memory optimization).
      */
     transitionMode?: "css" | "none";
+    /**
+     * Navigation mode for pivot.
+     * - "linear" (default): Stops at first/last item.
+     * - "loop": Navigation wraps around (last→first, first→last).
+     */
+    navigationMode?: PivotNavigationMode;
 };
 /**
  * Props object returned by getItemProps for navigation elements.
@@ -45,18 +63,71 @@ export type PivotItemProps = {
     tabIndex: number;
     onClick: () => void;
 };
+/**
+ * Options for navigation methods (go, setActiveId).
+ */
+export type PivotNavigationOptions = {
+    /**
+     * Whether to animate the transition.
+     * - undefined: use transitionMode setting (default)
+     * - true: force animation
+     * - false: instant transition without animation
+     */
+    animated?: boolean;
+};
 /**
  * Result from usePivot hook.
  */
 export type UsePivotResult<TId extends string = string> = {
     /** Current active item ID */
     activeId: TId;
-    /** Function to change the active item */
-    setActiveId: (id: TId) => void;
+    /**
+     * Function to change the active item.
+     * @param id - Target item ID
+     * @param options - Navigation options (animated, etc.)
+     */
+    setActiveId: (id: TId, options?: PivotNavigationOptions) => void;
     /** Helper to check if an item is active */
     isActive: (id: TId) => boolean;
     /** Function to get props for navigation items (buttons, links, etc.) */
     getItemProps: (id: TId) => PivotItemProps;
     /** Outlet component that renders the active content (react-router style) */
     Outlet: React.FC;
+    /**
+     * Navigate in a direction relative to the current item.
+     * @param direction - Number of items to move: -1=prev, 1=next, -2=skip2Back, etc.
+     * @param options - Navigation options (animated, etc.)
+     */
+    go: (direction: number, options?: PivotNavigationOptions) => void;
+    /**
+     * Check if navigation in a direction is possible.
+     * @param direction - Direction to check
+     * @returns true if navigation is possible
+     */
+    canGo: (direction: number) => boolean;
+    /** Current index of active item in the items array */
+    activeIndex: number;
+    /** Total number of enabled items */
+    itemCount: number;
+    /** Whether a transition animation is currently in progress */
+    isAnimating: boolean;
+    /** Call to signal that animation has completed */
+    endAnimation: () => void;
+    /** Current navigation mode */
+    navigationMode: PivotNavigationMode;
+    /**
+     * Get the virtual position for an item relative to active.
+     * In loop mode, this wraps: item at index 0 can have position 1 if active is last.
+     * @param id - Item ID to check
+     * @returns -1 (prev), 0 (active), 1 (next), or null if not adjacent
+     */
+    getVirtualPosition: (id: TId) => -1 | 0 | 1 | null;
+    /**
+     * Get the position for any item relative to active.
+     * Unlike getVirtualPosition, returns positions for all items (not just adjacent).
+     * In loop mode, returns the shortest path position (e.g., last→first is +1, not -(count-1)).
+     * @param id - Item ID to check
+     * @returns Position offset from active, or null if item not found
+     */
+    getItemPosition: (id: TId) => number | null;
 };

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

@@ -0,0 +1,68 @@
+/**
+ * @file Hook for binding swipe input to Pivot navigation.
+ *
+ * This hook connects swipe gesture detection to Pivot's navigation API,
+ * translating swipe gestures into go(-1) and go(1) calls.
+ *
+ * Supports both:
+ * - Touch/pointer swipe gestures
+ * - Trackpad two-finger swipe (wheel events)
+ */
+import * as React from "react";
+import type { SwipeInputState, SwipeInputThresholds, GestureAxis } from "../../hooks/gesture/types.js";
+import type { UsePivotResult } from "./types.js";
+/**
+ * Options for usePivotSwipeInput hook.
+ */
+export type UsePivotSwipeInputOptions = {
+    /** Reference to the swipe container element */
+    containerRef: React.RefObject<HTMLElement | null>;
+    /** Pivot navigation result from usePivot */
+    pivot: Pick<UsePivotResult, "go" | "canGo">;
+    /** Axis for swipe detection. @default "horizontal" */
+    axis?: GestureAxis;
+    /** Whether swipe input is enabled. @default true */
+    enabled?: boolean;
+    /** Custom swipe thresholds */
+    thresholds?: Partial<SwipeInputThresholds>;
+    /** Whether to enable trackpad wheel swipe. @default true */
+    enableWheelSwipe?: boolean;
+};
+/**
+ * Result from usePivotSwipeInput hook.
+ */
+export type UsePivotSwipeInputResult = {
+    /** Current swipe input state */
+    inputState: SwipeInputState;
+    /** Props to spread on the container element */
+    containerProps: React.HTMLAttributes<HTMLElement> & {
+        style: React.CSSProperties;
+    };
+};
+/**
+ * Hook for binding swipe input to Pivot navigation.
+ *
+ * Detects horizontal swipe gestures and triggers navigation:
+ * - Swipe left (direction -1) → go(1) (next)
+ * - Swipe right (direction 1) → go(-1) (prev)
+ *
+ * Note: The direction mapping is inverted because swiping left reveals the next item,
+ * similar to how carousel/swipe navigation works in iOS.
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const pivot = usePivot({ items });
+ * const { inputState, containerProps } = usePivotSwipeInput({
+ *   containerRef,
+ *   pivot,
+ * });
+ *
+ * return (
+ *   <div ref={containerRef} {...containerProps}>
+ *     <pivot.Outlet />
+ *   </div>
+ * );
+ * ```
+ */
+export declare function usePivotSwipeInput(options: UsePivotSwipeInputOptions): UsePivotSwipeInputResult;

package/dist/modules/stack/StackContent.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file StackContent component for rendering stack panels with animations.
+ *
+ * Override via CSS custom properties:
+ * - --rpl-stack-animation-push: Animation when panel is pushed
+ * - --rpl-stack-animation-pop: Animation when panel is popped
+ * - --rpl-stack-transition-duration: Duration of transitions
+ * - --rpl-stack-transition-easing: Easing for transitions
+ */
+import * as React from "react";
+import type { StackContentProps } from "./types.js";
+/**
+ * Renders a stack panel with appropriate animation based on display mode.
+ */
+export declare const StackContent: React.FC<StackContentProps>;

package/dist/modules/stack/SwipeStackContent.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @file SwipeStackContent component for Stack panels with direct DOM manipulation.
+ *
+ * Provides iOS-style swipe-to-go-back behavior:
+ * - Active panel follows the finger directly
+ * - Behind panel reveals from -30% with parallax effect
+ *
+ * Uses useSwipeContentTransform for immediate DOM updates.
+ */
+import * as React from "react";
+import type { SwipeInputState, GestureAxis } from "../../hooks/gesture/types.js";
+import type { StackDisplayMode } from "./types.js";
+/**
+ * Props for SwipeStackContent component.
+ */
+export type SwipeStackContentProps = {
+    /** Panel ID */
+    id: string;
+    /** Panel depth in the stack */
+    depth: number;
+    /** Current navigation depth (active panel) */
+    navigationDepth: number;
+    /** Whether this panel is currently active */
+    isActive: boolean;
+    /** Swipe input state from useStackSwipeInput */
+    inputState: SwipeInputState;
+    /** Container size in pixels (width for horizontal, height for vertical) */
+    containerSize: number;
+    /** Gesture axis. @default "horizontal" */
+    axis?: GestureAxis;
+    /** Behind panel offset ratio. @default -0.3 */
+    behindOffset?: number;
+    /** Animation duration in ms. @default 300 */
+    animationDuration?: number;
+    /**
+     * Whether to animate when first mounted as active.
+     * Set to true for push navigation animations.
+     * @default false
+     */
+    animateOnMount?: boolean;
+    /**
+     * Whether to show iOS-style edge shadow on active panel.
+     * @default true
+     */
+    showShadow?: boolean;
+    /**
+     * Display mode for visual styling.
+     * - "overlay": panels overlay, no scale (iOS style)
+     * - "slide": panels slide with parallax
+     * - "stack": panels scale down and offset (stacked cards style)
+     * @default "overlay"
+     */
+    displayMode?: StackDisplayMode;
+    /**
+     * Whether to show dimming overlay on behind panels.
+     * Creates iOS-style darkening effect that fades during swipe.
+     * @default true
+     */
+    showDimming?: boolean;
+    /** Content to render */
+    children: React.ReactNode;
+};
+export declare const SwipeStackContent: React.FC<SwipeStackContentProps>;

package/dist/modules/stack/SwipeStackOutlet.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file SwipeStackOutlet component for rendering stack with swipe support.
+ *
+ * Uses SwipeStackContent for direct DOM manipulation during swipe gestures,
+ * providing iOS-style smooth swipe-to-go-back behavior.
+ */
+import * as React from "react";
+import type { SwipeInputState } from "../../hooks/gesture/types.js";
+import type { StackPanel, StackNavigationState } from "./types.js";
+/**
+ * Props for SwipeStackOutlet component.
+ */
+export type SwipeStackOutletProps = {
+    /** Array of panel definitions */
+    panels: ReadonlyArray<StackPanel>;
+    /** Current navigation state */
+    navigationState: StackNavigationState;
+    /** Swipe input state from useStackSwipeInput */
+    inputState: SwipeInputState;
+    /** Container size in pixels (width for horizontal swipe) */
+    containerSize: number;
+    /** Function to get cached content for a panel */
+    getCachedContent?: (panelId: string) => React.ReactNode | null;
+    /** Behind panel offset ratio. @default -0.3 */
+    behindOffset?: number;
+    /**
+     * Whether to animate new panels on mount.
+     * @default false
+     */
+    animateOnMount?: boolean;
+    /**
+     * Animation duration in ms.
+     * @default 300
+     */
+    animationDuration?: number;
+    /**
+     * Whether to show iOS-style edge shadow on active panels.
+     * @default true
+     */
+    showShadow?: boolean;
+    /**
+     * Display mode for visual styling.
+     * - "overlay": panels overlay, no scale (iOS style)
+     * - "slide": panels slide with parallax
+     * - "stack": panels scale down and offset (stacked cards style)
+     * @default "overlay"
+     */
+    displayMode?: "overlay" | "slide" | "stack";
+    /**
+     * Whether to show dimming overlay on behind panels.
+     * @default true
+     */
+    showDimming?: boolean;
+};
+/**
+ * SwipeStackOutlet renders stack panels with swipe gesture support.
+ *
+ * Unlike the default StackOutlet, this component:
+ * - Uses SwipeStackContent for direct DOM manipulation
+ * - Only renders active and behind panels for performance
+ * - Supports iOS-style parallax reveal animation
+ *
+ * @example
+ * ```tsx
+ * const navigation = useStackNavigation({ panels, displayMode: 'overlay' });
+ * const swipeInput = useStackSwipeInput({ containerRef, navigation });
+ *
+ * return (
+ *   <div ref={containerRef} {...swipeInput.containerProps}>
+ *     <SwipeStackOutlet
+ *       panels={navigation.panels}
+ *       navigationState={navigation.state}
+ *       inputState={swipeInput.inputState}
+ *       containerSize={containerWidth}
+ *     />
+ *   </div>
+ * );
+ * ```
+ */
+export declare const SwipeStackOutlet: React.FC<SwipeStackOutletProps>;

package/dist/modules/stack/computeStackContentState.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Animation type for stack panel transitions.
+ */
+export type StackAnimationType = "push" | "pop" | null;
+/**
+ * Display mode for stack panels.
+ */
+export type StackDisplayMode = "overlay" | "slide" | "stack";
+/**
+ * Transition mode for animations.
+ */
+export type StackTransitionMode = "css" | "none";
+/**
+ * Input for computing animation type.
+ */
+export type ComputeAnimationTypeInput = {
+    wasActive: boolean;
+    isActive: boolean;
+    transitionMode: StackTransitionMode;
+};
+/**
+ * Compute the animation type based on active state change.
+ *
+ * @returns The animation type to apply, or null if no animation needed.
+ */
+export declare function computeAnimationType(input: ComputeAnimationTypeInput): StackAnimationType;
+/**
+ * Input for computing visibility.
+ */
+export type ComputeVisibilityInput = {
+    displayMode: StackDisplayMode;
+    depth: number;
+    navigationDepth: number;
+    isActive: boolean;
+    isAnimatingOut: boolean;
+    isRevealing: boolean;
+    revealDepth: number | null;
+};
+/**
+ * Compute panel visibility based on display mode and state.
+ *
+ * @returns "visible" or "hidden"
+ */
+export declare function computeVisibility(input: ComputeVisibilityInput): "visible" | "hidden";
+/**
+ * Input for computing transform.
+ */
+export type ComputeTransformInput = {
+    depth: number;
+    activeDepth: number;
+    displayMode: StackDisplayMode;
+    isRevealing: boolean;
+    revealDepth: number | null;
+};
+/**
+ * Compute the transform value for a stack panel.
+ *
+ * @returns CSS transform string
+ */
+export declare function computeTransform(input: ComputeTransformInput): string;
+/**
+ * Full input for computing stack content state.
+ */
+export type StackContentStateInput = {
+    depth: number;
+    isActive: boolean;
+    wasActive: boolean;
+    currentAnimationType: StackAnimationType;
+    displayMode: StackDisplayMode;
+    transitionMode: StackTransitionMode;
+    navigationState: {
+        depth: number;
+        isRevealing: boolean;
+        revealDepth: number | null;
+    };
+    swipeProgress: number | undefined;
+};
+/**
+ * Computed state output for stack content.
+ */
+export type StackContentStateOutput = {
+    nextAnimationType: StackAnimationType;
+    visibility: "visible" | "hidden";
+    transform: string;
+    animation: string | undefined;
+    transition: string | undefined;
+    zIndex: number;
+    pointerEvents: "auto" | "none";
+};
+/**
+ * Compute the complete state for a stack content panel.
+ *
+ * This is the main entry point that combines all state computation.
+ * Pure function with no side effects.
+ *
+ * @param input - All inputs needed to compute state
+ * @returns Computed state for rendering
+ */
+export declare function computeStackContentState(input: StackContentStateInput): StackContentStateOutput;

package/dist/modules/stack/computeSwipeStackTransform.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @file Pure functions for computing Stack panel transforms during swipe.
+ *
+ * These functions calculate positions for iOS-style "swipe to go back" behavior
+ * where the active panel follows the finger and the behind panel reveals from -30%.
+ */
+/**
+ * Default offset for behind panel (-30% of container width).
+ */
+export declare const DEFAULT_BEHIND_OFFSET = -0.3;
+/**
+ * Compute the target position for the active panel.
+ *
+ * Active panel starts at 0 and moves right as the user swipes.
+ *
+ * @param displacement - Current swipe displacement in pixels
+ * @returns Target position in pixels
+ */
+export declare function computeActiveTargetPx(displacement: number): number;
+/**
+ * Compute the target position for the behind panel.
+ *
+ * Behind panel starts at -30% and moves to 0% as swipe progresses.
+ * Uses parallax effect: moves slower than the active panel.
+ *
+ * @param displacement - Current swipe displacement in pixels
+ * @param containerSize - Container width/height in pixels
+ * @param behindOffset - Starting offset ratio (default -0.3 for -30%)
+ * @returns Target position in pixels
+ */
+export declare function computeBehindTargetPx(displacement: number, containerSize: number, behindOffset?: number): number;
+/**
+ * Compute swipe progress as a ratio (0 to 1).
+ *
+ * @param displacement - Current swipe displacement in pixels
+ * @param containerSize - Container width/height in pixels
+ * @returns Progress ratio from 0 to 1
+ */
+export declare function computeSwipeProgress(displacement: number, containerSize: number): number;
+/**
+ * Input for computing swipe visibility.
+ */
+export type ComputeSwipeVisibilityInput = {
+    /** Panel depth in the stack */
+    depth: number;
+    /** Current navigation depth (active panel) */
+    navigationDepth: number;
+    /** Whether this panel is currently active */
+    isActive: boolean;
+    /** Whether swipe gesture is active */
+    isSwiping: boolean;
+    /** Whether snap-back animation is running */
+    isAnimating: boolean;
+};
+/**
+ * Compute whether a panel should be visible during swipe.
+ *
+ * During swipe:
+ * - Active panel is always visible
+ * - Behind panel (depth = navigationDepth - 1) is visible when swiping/animating
+ *
+ * @returns true if panel should be visible
+ */
+export declare function computeSwipeVisibility(input: ComputeSwipeVisibilityInput): boolean;
+/**
+ * Determine the role of a panel during swipe gesture.
+ */
+export type SwipePanelRole = "active" | "behind" | "hidden";
+/**
+ * Determine the role of a panel during swipe.
+ *
+ * @param depth - Panel depth in the stack
+ * @param navigationDepth - Current navigation depth (active panel)
+ * @returns Panel role for swipe handling
+ */
+export declare function determineSwipePanelRole(depth: number, navigationDepth: number): SwipePanelRole;