react-panel-layout 0.5.1 → 0.6.0

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,221 @@
+/**
+ * @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 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;
+
+      if (position === "top") {
+        // TOP: Cover expands upward during pull-down overscroll
+        // liveRect.top > 0 means element moved down (overscroll)
+        // liveRect.top < 0 means element scrolled up
+        const coverAreaHeight = Math.max(0, liveRect.height + liveRect.top);
+
+        if (coverAreaHeight !== prevHeight) {
+          coverArea.style.opacity = coverAreaHeight > 0 ? "1" : "0";
+          coverArea.style.height = `${coverAreaHeight}px`;
+          prevHeight = coverAreaHeight;
+        }
+
+        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;
+        }
+
+        const isStuck = liveRect.top < 0;
+        const scrollOffset = Math.max(0, -liveRect.top);
+
+        const shouldUpdateState = isFirstRun ? true : isStuck !== prevIsStuck;
+        if (shouldUpdateState) {
+          isFirstRun = false;
+          prevIsStuck = isStuck;
+          updateState({ isStuck, scrollOffset });
+        }
+      } else {
+        // BOTTOM: Cover expands downward during pull-up overscroll
+        // liveRect.bottom < viewportHeight means element moved up (overscroll at bottom)
+        // liveRect.bottom > viewportHeight means element is below viewport
+        const distanceFromBottom = viewportHeight - liveRect.bottom;
+        const coverAreaHeight = Math.max(0, liveRect.height + distanceFromBottom);
+
+        if (coverAreaHeight !== prevHeight) {
+          coverArea.style.opacity = coverAreaHeight > 0 ? "1" : "0";
+          coverArea.style.height = `${coverAreaHeight}px`;
+          prevHeight = coverAreaHeight;
+        }
+
+        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;
+        }
+
+        const isStuck = liveRect.bottom > viewportHeight;
+        const scrollOffset = Math.max(0, liveRect.bottom - viewportHeight);
+
+        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/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";

package/src/sticky-header/types.ts

@@ -0,0 +1,68 @@
+/**
+ * @file Type definitions for the StickyArea component.
+ *
+ * StickyArea provides a native app-like experience for SPAs/PWAs
+ * by displaying cover content during overscroll/bounce.
+ * Supports both top (header) and bottom (footer) positions.
+ * Works with document-level scroll only.
+ */
+import type * as React from "react";
+
+/**
+ * Position of the sticky area.
+ * - "top": Header behavior - sticks to top, expands on pull-down overscroll
+ * - "bottom": Footer behavior - sticks to bottom, expands on pull-up overscroll
+ */
+export type StickyAreaPosition = "top" | "bottom";
+
+/**
+ * State information exposed by StickyArea.
+ */
+export type StickyAreaState = {
+  /**
+   * Whether the area is stuck at its edge of the viewport.
+   * - For "top": True when scrolled past the top edge
+   * - For "bottom": True when scrolled past the bottom edge
+   */
+  isStuck: boolean;
+  /**
+   * The current scroll offset relative to the area.
+   * Positive when the area has scrolled past its edge.
+   */
+  scrollOffset: number;
+};
+
+/**
+ * Props for the StickyArea component.
+ */
+export type StickyAreaProps = {
+  /**
+   * Position of the sticky area.
+   * - "top": Header behavior (default)
+   * - "bottom": Footer behavior
+   *
+   * @default "top"
+   */
+  position?: StickyAreaPosition;
+  /**
+   * Cover content displayed behind the area.
+   * This content expands during overscroll/bounce to create
+   * a native app-like pull effect.
+   */
+  cover: React.ReactNode;
+  /**
+   * Main content that scrolls over the cover.
+   * Can be a ReactNode or a render function receiving state.
+   */
+  children: React.ReactNode | ((state: StickyAreaState) => React.ReactNode);
+  /**
+   * Callback fired when sticky state changes.
+   */
+  onStateChange?: (state: StickyAreaState) => void;
+};
+
+// Backwards compatibility aliases
+/** @deprecated Use StickyAreaState instead */
+export type StickyHeaderState = StickyAreaState;
+/** @deprecated Use StickyAreaProps instead */
+export type StickyHeaderProps = StickyAreaProps;