react-panel-layout 0.5.2 → 0.6.1

package/src/panels/index.ts

@@ -0,0 +1,119 @@
+/**
+ * @file Panels entry point - VSCode-like panel system
+ * @packageDocumentation
+ *
+ * This is a subpath export entry point for `react-panel-layout/panels`.
+ *
+ * ## Overview
+ * Panels provides a VSCode-like panel system with tabbed groups, drag-and-drop
+ * tab reordering, split views, and keyboard navigation. Supports both controlled
+ * and uncontrolled state management.
+ *
+ * ## Installation
+ * ```ts
+ * import { PanelSystem, buildInitialState, usePanelSystem } from "react-panel-layout/panels";
+ * ```
+ *
+ * ## Basic Usage
+ * ```tsx
+ * const tabs = [
+ *   { id: 'file1', title: 'index.ts', render: () => <Editor file="index.ts" /> },
+ *   { id: 'file2', title: 'app.tsx', render: () => <Editor file="app.tsx" /> },
+ * ];
+ *
+ * function App() {
+ *   const initialState = buildInitialState(tabs);
+ *   let groupCounter = 1;
+ *
+ *   return (
+ *     <PanelSystem
+ *       initialState={initialState}
+ *       createGroupId={() => `g_${++groupCounter}`}
+ *       layoutMode="grid"
+ *       gridTracksInteractive={true}
+ *       dragThresholdPx={5}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * ## Controlled State
+ * ```tsx
+ * const [state, setState] = useState(() => buildInitialState(tabs));
+ *
+ * <PanelSystem
+ *   initialState={state}
+ *   state={state}
+ *   onStateChange={setState}
+ *   // ...
+ * />
+ * ```
+ *
+ * ## Using Context
+ * ```tsx
+ * function TabActions() {
+ *   const { actions } = usePanelSystem();
+ *   return <button onClick={() => actions.splitFocused('vertical')}>Split</button>;
+ * }
+ * ```
+ */
+
+// Components
+export { PanelSystem } from "../modules/panels/system/PanelSystem.js";
+export { PanelGroupView } from "../components/panels/PanelGroupView.js";
+export { DropSuggestOverlay } from "../components/panels/DropSuggestOverlay.js";
+
+// Context
+export {
+  PanelSystemProvider,
+  usePanelSystem,
+} from "../modules/panels/state/PanelSystemContext.js";
+
+// State operations
+export {
+  collectGroupsInOrder,
+  splitLeaf,
+  closeLeaf,
+  isGroup,
+  setSplitRatio,
+  createEmptyGroup,
+  addTabToGroup,
+  removeTabFromGroup,
+  moveTab,
+  setActiveTab,
+  reorderTabWithinGroup,
+  addTabToGroupAtIndex,
+  setFocusedGroup,
+  focusGroupIndex,
+  nextGroup,
+  prevGroup,
+  refreshGroupOrder,
+  splitGroup,
+  buildInitialState,
+} from "../modules/panels/index.js";
+
+// Types
+export type {
+  PanelId,
+  GroupId,
+  SplitDirection,
+  TabDefinition,
+  GroupModel,
+  PanelTree,
+  PanelSystemState,
+  DropZone,
+  DraggingTab,
+  PanelCommands,
+  PanelSystemProps,
+  PanelSplitLimits,
+  IdFactory,
+} from "../modules/panels/index.js";
+
+export type {
+  PanelSystemContextValue,
+  PanelSystemProviderProps,
+  PanelStateAction,
+  PanelStateActions,
+} from "../modules/panels/state/PanelSystemContext.js";
+
+export type { PanelGroupViewProps } from "../components/panels/PanelGroupView.js";

package/src/pivot/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @file Pivot entry point - Headless content switching
+ *
+ * Import via: import { usePivot } from "react-panel-layout/pivot";
+ */
+
+// Hook
+export { usePivot } from "../modules/pivot";
+
+// Components
+export { SwipePivotTabBar } from "../modules/pivot";
+
+// Utilities
+export { scaleInputState } from "../modules/pivot";
+
+// Types
+export type { PivotItem, UsePivotOptions, UsePivotResult, PivotItemProps } from "../modules/pivot";
+export type { SwipePivotTabBarProps, IndicatorRenderProps } from "../modules/pivot";
+export type { PivotBehavior, PivotBehaviorItem } from "../types";

package/src/resizer/index.ts

@@ -0,0 +1,68 @@
+/**
+ * @file Resizer entry point - Resize handle components and hooks
+ * @packageDocumentation
+ *
+ * This is a subpath export entry point for `react-panel-layout/resizer`.
+ *
+ * ## Overview
+ * Resizer provides draggable resize handles for creating resizable layouts.
+ * Includes both ready-to-use components and a low-level hook for custom implementations.
+ *
+ * ## Installation
+ * ```ts
+ * import { ResizeHandle, useResizeDrag } from "react-panel-layout/resizer";
+ * ```
+ *
+ * ## Basic Usage with ResizeHandle
+ * ```tsx
+ * function ResizableLayout() {
+ *   const [width, setWidth] = useState(300);
+ *
+ *   return (
+ *     <div style={{ display: 'flex' }}>
+ *       <div style={{ width }}>Left Panel</div>
+ *       <ResizeHandle
+ *         direction="vertical"
+ *         onResize={(delta) => setWidth((w) => w + delta)}
+ *       />
+ *       <div style={{ flex: 1 }}>Right Panel</div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * ## Custom Handle with useResizeDrag
+ * ```tsx
+ * function CustomHandle({ onResize }) {
+ *   const { ref, isDragging, onPointerDown } = useResizeDrag({
+ *     axis: 'x',
+ *     onResize,
+ *   });
+ *
+ *   return (
+ *     <div
+ *       ref={ref}
+ *       onPointerDown={onPointerDown}
+ *       style={{ cursor: 'col-resize', background: isDragging ? 'blue' : 'gray' }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+
+// Hooks
+export { useResizeDrag } from "../modules/resizer/useResizeDrag.js";
+
+// Components
+export { ResizeHandle } from "../components/resizer/ResizeHandle.js";
+export { HorizontalDivider } from "../components/resizer/HorizontalDivider.js";
+
+// Types
+export type {
+  ResizeDragAxis,
+  UseResizeDragOptions,
+  UseResizeDragResult,
+} from "../modules/resizer/useResizeDrag.js";
+
+export type { ResizeHandleProps } from "../components/resizer/ResizeHandle.js";
+export type { HorizontalDividerProps } from "../components/resizer/HorizontalDivider.js";

package/src/stack/index.ts

@@ -0,0 +1,91 @@
+/**
+ * @file Stack entry point - Hierarchical navigation with swipe support
+ * @packageDocumentation
+ *
+ * This is a subpath export entry point for `react-panel-layout/stack`.
+ *
+ * ## Overview
+ * Stack provides iOS/iPadOS-style hierarchical navigation where panels stack
+ * as users drill down into content. Supports swipe-to-go-back gestures.
+ *
+ * ## Installation
+ * ```ts
+ * import { useStackNavigation, SwipeStackOutlet } from "react-panel-layout/stack";
+ * ```
+ *
+ * ## Basic Usage
+ * ```tsx
+ * const panels = [
+ *   { id: 'list', title: 'Items', content: <ListPage /> },
+ *   { id: 'detail', title: 'Detail', content: <DetailPage /> },
+ * ];
+ *
+ * function App() {
+ *   const { push, go, Outlet } = useStackNavigation({
+ *     panels,
+ *     displayMode: 'overlay',
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => push('detail')}>View Detail</button>
+ *       <button onClick={() => go(-1)}>Back</button>
+ *       <Outlet />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * ## With Swipe Gestures (SwipeStackContent)
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const navigation = useStackNavigation({ panels, displayMode: 'overlay' });
+ * const swipeInput = useStackSwipeInput({ containerRef, navigation });
+ * const { rect } = useResizeObserver(containerRef);
+ *
+ * return (
+ *   <div ref={containerRef} {...swipeInput.containerProps}>
+ *     {panels.map((panel, index) => (
+ *       <SwipeStackContent
+ *         key={panel.id}
+ *         id={panel.id}
+ *         depth={index}
+ *         navigationDepth={navigation.state.depth}
+ *         isActive={navigation.currentPanelId === panel.id}
+ *         inputState={swipeInput.inputState}
+ *         containerSize={rect?.width ?? 0}
+ *       >
+ *         {panel.content}
+ *       </SwipeStackContent>
+ *     ))}
+ *   </div>
+ * );
+ * ```
+ */
+
+// Hooks
+export { useStackNavigation } from "../modules/stack/useStackNavigation.js";
+export { useStackSwipeInput } from "../modules/stack/useStackSwipeInput.js";
+
+// Components
+export { StackContent } from "../modules/stack/StackContent.js";
+export { SwipeStackContent } from "../modules/stack/SwipeStackContent.js";
+export { SwipeStackOutlet } from "../modules/stack/SwipeStackOutlet.js";
+
+// Types
+export type {
+  StackDisplayMode,
+  StackTransitionMode,
+  StackPanel,
+  StackNavigationState,
+  StackPanelProps,
+  StackBackButtonProps,
+  UseStackNavigationOptions,
+  UseStackNavigationResult,
+  UseStackSwipeInputOptions,
+  UseStackSwipeInputResult,
+  StackContentProps,
+} from "../modules/stack/types.js";
+
+export type { SwipeStackContentProps } from "../modules/stack/SwipeStackContent.js";
+export type { SwipeStackOutletProps } from "../modules/stack/SwipeStackOutlet.js";

package/src/sticky-header/StickyArea.tsx

@@ -0,0 +1,193 @@
+/**
+ * @file StickyArea component for native app-like overscroll experience.
+ *
+ * Displays cover content that expands during overscroll/bounce,
+ * providing a native app-like pull effect commonly seen in iOS apps.
+ *
+ * Supports both top (header) and bottom (footer) positions.
+ * Works with document-level scroll only.
+ */
+import * as React from "react";
+import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect";
+import { calculateStickyMetrics } from "./calculateStickyMetrics";
+import type { StickyAreaProps, StickyAreaState } from "./types";
+
+/**
+ * Get area styles based on position.
+ */
+function getAreaStyle(position: "top" | "bottom"): React.CSSProperties {
+  return {
+    position: "relative",
+    paddingTop: position === "top" ? "env(safe-area-inset-top)" : undefined,
+    paddingBottom: position === "bottom" ? "env(safe-area-inset-bottom)" : undefined,
+    boxSizing: "border-box",
+  };
+}
+
+const bodyStyle: React.CSSProperties = {
+  zIndex: 1,
+};
+
+/**
+ * Get cover styles based on position.
+ * Explicitly disables transitions to prevent jank from inherited CSS.
+ */
+function getCoverStyle(position: "top" | "bottom"): React.CSSProperties {
+  return {
+    opacity: 0,
+    zIndex: 0,
+    userSelect: "none",
+    pointerEvents: "none",
+    // Disable transitions to prevent jank - styles are updated via RAF
+    transition: "none",
+    // Enable GPU acceleration for smoother animations
+    willChange: "height, opacity",
+    transform: "translateZ(0)",
+    position: "fixed",
+    top: position === "top" ? 0 : undefined,
+    bottom: position === "bottom" ? 0 : undefined,
+    left: 0,
+    right: 0,
+  };
+}
+
+const wrapperStyle: React.CSSProperties = {
+  position: "relative",
+};
+
+/**
+ * StickyArea provides a native app-like overscroll experience.
+ *
+ * When the user overscrolls (pulls beyond the edge), the cover content
+ * expands to fill the visible area, similar to native iOS/Android app behavior.
+ *
+ * Supports both top (header) and bottom (footer) positions.
+ * Works with document-level scroll only.
+ *
+ * @example
+ * ```tsx
+ * // Header (top) - expands on pull-down
+ * <StickyArea position="top" cover={<img src="/hero.jpg" />}>
+ *   <header><h1>My App</h1></header>
+ * </StickyArea>
+ *
+ * // Footer (bottom) - expands on pull-up
+ * <StickyArea position="bottom" cover={<div className="footer-bg" />}>
+ *   <footer>Footer content</footer>
+ * </StickyArea>
+ * ```
+ */
+export const StickyArea: React.FC<StickyAreaProps> = ({
+  position = "top",
+  cover,
+  children,
+  onStateChange,
+}) => {
+  const areaRef = React.useRef<HTMLDivElement>(null);
+  const coverAreaRef = React.useRef<HTMLDivElement>(null);
+
+  // State for render function and callback
+  const [state, setState] = React.useState<StickyAreaState>({
+    isStuck: false,
+    scrollOffset: 0,
+  });
+
+  // Update state when values change
+  const stateRef = React.useRef(state);
+  const updateState = React.useCallback(
+    (newState: StickyAreaState) => {
+      const prev = stateRef.current;
+      if (prev.isStuck !== newState.isStuck || prev.scrollOffset !== newState.scrollOffset) {
+        stateRef.current = newState;
+        setState(newState);
+        onStateChange?.(newState);
+      }
+    },
+    [onStateChange],
+  );
+
+  useIsomorphicLayoutEffect(() => {
+    const area = areaRef.current;
+    const coverArea = coverAreaRef.current;
+    if (!coverArea || !area) {
+      return;
+    }
+
+    // eslint-disable-next-line no-restricted-syntax -- Performance: mutable state for RAF loop
+    let prevHeight = Number.NaN;
+    // eslint-disable-next-line no-restricted-syntax -- Performance: mutable state for RAF loop
+    let prevLeft = Number.NaN;
+    // eslint-disable-next-line no-restricted-syntax -- Performance: mutable state for RAF loop
+    let prevWidth = Number.NaN;
+    // eslint-disable-next-line no-restricted-syntax -- Performance: mutable state for RAF loop
+    let prevIsStuck = false;
+    // eslint-disable-next-line no-restricted-syntax -- Performance: mutable state for RAF loop
+    let isFirstRun = true;
+
+    const loop = () => {
+      const liveRect = area.getBoundingClientRect();
+      const viewportHeight = window.innerHeight;
+
+      // Calculate metrics using pure function
+      const { coverAreaHeight, isStuck, scrollOffset } = calculateStickyMetrics(
+        position,
+        liveRect,
+        viewportHeight
+      );
+
+      // Update height/opacity
+      if (coverAreaHeight !== prevHeight) {
+        coverArea.style.opacity = coverAreaHeight > 0 ? "1" : "0";
+        coverArea.style.height = `${coverAreaHeight}px`;
+        prevHeight = coverAreaHeight;
+      }
+
+      // Update left/width
+      if (liveRect.left !== prevLeft || liveRect.width !== prevWidth) {
+        coverArea.style.left = `${liveRect.left}px`;
+        coverArea.style.width = `${liveRect.width}px`;
+        prevLeft = liveRect.left;
+        prevWidth = liveRect.width;
+      }
+
+      // Update state
+      const shouldUpdateState = isFirstRun ? true : isStuck !== prevIsStuck;
+      if (shouldUpdateState) {
+        isFirstRun = false;
+        prevIsStuck = isStuck;
+        updateState({ isStuck, scrollOffset });
+      }
+    };
+
+    // eslint-disable-next-line no-restricted-syntax -- Performance: RAF id needs reassignment
+    let id = requestAnimationFrame(function animate() {
+      loop();
+      id = requestAnimationFrame(animate);
+    });
+
+    return () => {
+      cancelAnimationFrame(id);
+    };
+  }, [position, updateState]);
+
+  // Render children
+  const renderedChildren = typeof children === "function" ? children(state) : children;
+
+  return (
+    <div style={wrapperStyle}>
+      <div ref={coverAreaRef} style={getCoverStyle(position)}>
+        {cover}
+      </div>
+      <div ref={areaRef} style={getAreaStyle(position)}>
+        <div style={bodyStyle}>{renderedChildren}</div>
+      </div>
+    </div>
+  );
+};
+
+StickyArea.displayName = "StickyArea";
+
+/**
+ * @deprecated Use StickyArea with position="top" instead
+ */
+export const StickyHeader = StickyArea;

package/src/sticky-header/calculateStickyMetrics.spec.ts

@@ -0,0 +1,105 @@
+/**
+ * @file Tests for calculateStickyMetrics pure function.
+ *
+ * Verifies the calculation of coverAreaHeight, isStuck, and scrollOffset
+ * for both top and bottom positions under various scroll scenarios.
+ */
+import { calculateStickyMetrics, type ElementRect } from "./calculateStickyMetrics.js";
+
+describe("calculateStickyMetrics", () => {
+  describe("position: top", () => {
+    it("returns expanded coverAreaHeight during overscroll (pull-down)", () => {
+      const rect: ElementRect = { top: 50, bottom: 150, height: 100 };
+      const result = calculateStickyMetrics("top", rect, 800);
+
+      expect(result).toEqual({
+        coverAreaHeight: 150, // height + top = 100 + 50
+        isStuck: false,
+        scrollOffset: 0,
+      });
+    });
+
+    it("returns reduced coverAreaHeight during normal scroll", () => {
+      const rect: ElementRect = { top: -30, bottom: 70, height: 100 };
+      const result = calculateStickyMetrics("top", rect, 800);
+
+      expect(result).toEqual({
+        coverAreaHeight: 70, // height + top = 100 + (-30)
+        isStuck: true,
+        scrollOffset: 30,
+      });
+    });
+
+    it("returns exact height at boundary (top === 0)", () => {
+      const rect: ElementRect = { top: 0, bottom: 100, height: 100 };
+      const result = calculateStickyMetrics("top", rect, 800);
+
+      expect(result).toEqual({
+        coverAreaHeight: 100,
+        isStuck: false,
+        scrollOffset: 0,
+      });
+    });
+
+    it("clamps coverAreaHeight to 0 when fully scrolled past", () => {
+      const rect: ElementRect = { top: -150, bottom: -50, height: 100 };
+      const result = calculateStickyMetrics("top", rect, 800);
+
+      expect(result.coverAreaHeight).toBe(0);
+      expect(result.isStuck).toBe(true);
+      expect(result.scrollOffset).toBe(150);
+    });
+  });
+
+  describe("position: bottom", () => {
+    it("returns expanded coverAreaHeight during overscroll (pull-up)", () => {
+      const rect: ElementRect = { top: 600, bottom: 700, height: 100 };
+      const viewportHeight = 800;
+      const result = calculateStickyMetrics("bottom", rect, viewportHeight);
+
+      // distanceFromBottom = 800 - 700 = 100
+      // coverAreaHeight = 100 + 100 = 200
+      expect(result).toEqual({
+        coverAreaHeight: 200,
+        isStuck: false,
+        scrollOffset: 0,
+      });
+    });
+
+    it("returns reduced coverAreaHeight during normal scroll", () => {
+      const rect: ElementRect = { top: 750, bottom: 850, height: 100 };
+      const viewportHeight = 800;
+      const result = calculateStickyMetrics("bottom", rect, viewportHeight);
+
+      // distanceFromBottom = 800 - 850 = -50
+      // coverAreaHeight = 100 + (-50) = 50
+      expect(result).toEqual({
+        coverAreaHeight: 50,
+        isStuck: true,
+        scrollOffset: 50,
+      });
+    });
+
+    it("returns exact height at boundary (bottom === viewportHeight)", () => {
+      const rect: ElementRect = { top: 700, bottom: 800, height: 100 };
+      const viewportHeight = 800;
+      const result = calculateStickyMetrics("bottom", rect, viewportHeight);
+
+      expect(result).toEqual({
+        coverAreaHeight: 100,
+        isStuck: false,
+        scrollOffset: 0,
+      });
+    });
+
+    it("clamps coverAreaHeight to 0 when fully scrolled past", () => {
+      const rect: ElementRect = { top: 900, bottom: 1000, height: 100 };
+      const viewportHeight = 800;
+      const result = calculateStickyMetrics("bottom", rect, viewportHeight);
+
+      expect(result.coverAreaHeight).toBe(0);
+      expect(result.isStuck).toBe(true);
+      expect(result.scrollOffset).toBe(200);
+    });
+  });
+});

package/src/sticky-header/calculateStickyMetrics.ts

@@ -0,0 +1,50 @@
+/**
+ * @file Pure function for calculating sticky area metrics.
+ *
+ * Extracts the position-dependent calculation logic from StickyArea component
+ * to enable unit testing and reduce code duplication.
+ */
+import type { StickyAreaPosition } from "./types";
+
+/** Output metrics for sticky area layout. */
+export type StickyMetrics = {
+  coverAreaHeight: number;
+  isStuck: boolean;
+  scrollOffset: number;
+};
+
+/** Lightweight element bounding rect used for calculations. */
+export type ElementRect = {
+  top: number;
+  bottom: number;
+  height: number;
+};
+
+/**
+ * Calculate sticky area metrics based on element position and viewport.
+ *
+ * @param position - Whether the sticky area is at "top" or "bottom"
+ * @param rect - Element bounding rect (top, bottom, height)
+ * @param viewportHeight - Current viewport height
+ * @returns Calculated metrics for cover area height, stuck state, and scroll offset
+ */
+export function calculateStickyMetrics(
+  position: StickyAreaPosition,
+  rect: ElementRect,
+  viewportHeight: number
+): StickyMetrics {
+  if (position === "top") {
+    return {
+      coverAreaHeight: Math.max(0, rect.height + rect.top),
+      isStuck: rect.top < 0,
+      scrollOffset: Math.max(0, -rect.top),
+    };
+  }
+  // bottom
+  const distanceFromBottom = viewportHeight - rect.bottom;
+  return {
+    coverAreaHeight: Math.max(0, rect.height + distanceFromBottom),
+    isStuck: rect.bottom > viewportHeight,
+    scrollOffset: Math.max(0, rect.bottom - viewportHeight),
+  };
+}

package/src/sticky-header/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @file StickyArea entry point - Native app-like overscroll experience
+ *
+ * Import via: import { StickyArea } from "react-panel-layout/sticky-header";
+ */
+
+// Components
+export { StickyArea, StickyHeader } from "./StickyArea";
+
+// Types
+export type {
+  StickyAreaPosition,
+  StickyAreaProps,
+  StickyAreaState,
+  // Backwards compatibility
+  StickyHeaderProps,
+  StickyHeaderState,
+} from "./types";