react-resizable-panels 0.0.32 → 0.0.34

package/src/PanelGroup.ts

@@ -11,15 +11,27 @@ import {
 } from "react";
 
 import { PanelGroupContext } from "./PanelContexts";
-import { Direction, PanelData, PanelGroupOnLayout, ResizeEvent } from "./types";
+import {
+  Direction,
+  PanelData,
+  PanelGroupOnLayout,
+  ResizeEvent,
+  PanelGroupStorage,
+} from "./types";
 import { loadPanelLayout, savePanelGroupLayout } from "./utils/serialization";
-import { getDragOffset, getMovement } from "./utils/coordinates";
+import {
+  getDragOffset,
+  getMovement,
+  isMouseEvent,
+  isTouchEvent,
+} from "./utils/coordinates";
 import {
   adjustByDelta,
   callPanelCallbacks,
   getBeforeAndAfterIds,
   getFlexGrow,
   getPanelGroup,
+  getResizeHandle,
   getResizeHandlePanelIds,
   panelsMapToSortedArray,
 } from "./utils/group";
@@ -28,10 +40,26 @@ import useUniqueId from "./hooks/useUniqueId";
 import { useWindowSplitterPanelGroupBehavior } from "./hooks/useWindowSplitterBehavior";
 import { resetGlobalCursorStyle, setGlobalCursorStyle } from "./utils/cursor";
 import debounce from "./utils/debounce";
+import { areEqual } from "./utils/arrays";
 
 // Limit the frequency of localStorage updates.
 const savePanelGroupLayoutDebounced = debounce(savePanelGroupLayout, 100);
 
+function throwServerError() {
+  throw new Error('PanelGroup "storage" prop required for server rendering.');
+}
+
+const defaultStorage: PanelGroupStorage = {
+  getItem:
+    typeof localStorage !== "undefined"
+      ? (name: string) => localStorage.getItem(name)
+      : (throwServerError as any),
+  setItem:
+    typeof localStorage !== "undefined"
+      ? (name: string, value: string) => localStorage.setItem(name, value)
+      : (throwServerError as any),
+};
+
 export type CommittedValues = {
   direction: Direction;
   panels: Map<string, PanelData>;
@@ -40,6 +68,19 @@ export type CommittedValues = {
 
 export type PanelDataMap = Map<string, PanelData>;
 
+// Initial drag state serves a few purposes:
+// * dragOffset:
+//   Resize is calculated by the distance between the current pointer event and the resize handle being "dragged"
+//   This value accounts for the initial offset when the touch/click starts, so the handle doesn't appear to "jump"
+// * dragHandleRect, sizes:
+//   When resizing is done via mouse/touch event– some initial state is stored
+//   so that any panels that contract will also expand if drag direction is reversed.
+export type InitialDragState = {
+  dragHandleRect: DOMRect;
+  dragOffset: number;
+  sizes: number[];
+};
+
 // TODO
 // Within an active drag, remember original positions to refine more easily on expand.
 // Look at what the Chrome devtools Sources does.
@@ -51,6 +92,7 @@ export type PanelGroupProps = {
   direction: Direction;
   id?: string | null;
   onLayout?: PanelGroupOnLayout;
+  storage?: PanelGroupStorage;
   style?: CSSProperties;
   tagName?: ElementType;
 };
@@ -62,6 +104,7 @@ export function PanelGroup({
   direction,
   id: idFromProps = null,
   onLayout = null,
+  storage = defaultStorage,
   style: styleFromProps = {},
   tagName: Type = "div",
 }: PanelGroupProps) {
@@ -70,6 +113,11 @@ export function PanelGroup({
   const [activeHandleId, setActiveHandleId] = useState<string | null>(null);
   const [panels, setPanels] = useState<PanelDataMap>(new Map());
 
+  // When resizing is done via mouse/touch event–
+  // We store the initial Panel sizes in this ref, and apply move deltas to them instead of to the current sizes.
+  // This has the benefit of causing force-collapsed panels to spring back open if drag is reversed.
+  const initialDragStateRef = useRef<InitialDragState | null>(null);
+
   // Use a ref to guard against users passing inline props
   const callbacksRef = useRef<{
     onLayout: PanelGroupOnLayout | null;
@@ -81,13 +129,11 @@ export function PanelGroup({
   // 0-1 values representing the relative size of each panel.
   const [sizes, setSizes] = useState<number[]>([]);
 
-  // Resize is calculated by the distance between the current pointer event and the resize handle being "dragged"
-  // This value accounts for the initial offset when the touch/click starts, so the handle doesn't appear to "jump"
-  const dragOffsetRef = useRef<number>(0);
-
   // Used to support imperative collapse/expand API.
   const panelSizeBeforeCollapse = useRef<Map<string, number>>(new Map());
 
+  const prevDeltaRef = useRef<number>(0);
+
   // Store committed values to avoid unnecessarily re-running memoization/effects functions.
   const committedValuesRef = useRef<CommittedValues>({
     direction,
@@ -155,7 +201,7 @@ export function PanelGroup({
     let defaultSizes: number[] | undefined = undefined;
     if (autoSaveId) {
       const panelsArray = panelsMapToSortedArray(panels);
-      defaultSizes = loadPanelLayout(autoSaveId, panelsArray);
+      defaultSizes = loadPanelLayout(autoSaveId, panelsArray, storage);
     }
 
     if (defaultSizes != null) {
@@ -213,7 +259,7 @@ export function PanelGroup({
 
       const panelsArray = panelsMapToSortedArray(panels);
 
-      savePanelGroupLayoutDebounced(autoSaveId, panelsArray, sizes);
+      savePanelGroupLayoutDebounced(autoSaveId, panelsArray, sizes, storage);
     }
   }, [autoSaveId, panels, sizes]);
 
@@ -295,7 +341,7 @@ export function PanelGroup({
           panelsArray,
           direction,
           prevSizes,
-          dragOffsetRef.current
+          initialDragStateRef.current
         );
         if (movement === 0) {
           return;
@@ -308,35 +354,53 @@ export function PanelGroup({
         const delta = (movement / size) * 100;
 
         const nextSizes = adjustByDelta(
+          event,
           panels,
           idBefore,
           idAfter,
           delta,
           prevSizes,
-          panelSizeBeforeCollapse.current
+          panelSizeBeforeCollapse.current,
+          initialDragStateRef.current
         );
-        if (prevSizes === nextSizes) {
-          // If the pointer has moved too far to resize the panel any further,
-          // update the cursor style for a visual clue.
-          // This mimics VS Code behavior.
-          if (isHorizontal) {
-            setGlobalCursorStyle(
-              movement < 0 ? "horizontal-min" : "horizontal-max"
-            );
-          } else {
-            setGlobalCursorStyle(
-              movement < 0 ? "vertical-min" : "vertical-max"
-            );
+
+        const sizesChanged = !areEqual(prevSizes, nextSizes);
+
+        // Don't update cursor for resizes triggered by keyboard interactions.
+        if (isMouseEvent(event) || isTouchEvent(event)) {
+          // Watch for multiple subsequent deltas; this might occur for tiny cursor movements.
+          // In this case, Panel sizes might not change–
+          // but updating cursor in this scenario would cause a flicker.
+          if (prevDeltaRef.current != delta) {
+            if (!sizesChanged) {
+              // If the pointer has moved too far to resize the panel any further,
+              // update the cursor style for a visual clue.
+              // This mimics VS Code behavior.
+
+              if (isHorizontal) {
+                setGlobalCursorStyle(
+                  movement < 0 ? "horizontal-min" : "horizontal-max"
+                );
+              } else {
+                setGlobalCursorStyle(
+                  movement < 0 ? "vertical-min" : "vertical-max"
+                );
+              }
+            } else {
+              // Reset the cursor style to the the normal resize cursor.
+              setGlobalCursorStyle(isHorizontal ? "horizontal" : "vertical");
+            }
           }
-        } else {
-          // Reset the cursor style to the the normal resize cursor.
-          setGlobalCursorStyle(isHorizontal ? "horizontal" : "vertical");
+        }
 
+        if (sizesChanged) {
           // If resize change handlers have been declared, this is the time to call them.
           callPanelCallbacks(panelsArray, prevSizes, nextSizes);
 
           setSizes(nextSizes);
         }
+
+        prevDeltaRef.current = delta;
       };
 
       return resizeHandler;
@@ -389,12 +453,14 @@ export function PanelGroup({
     const delta = isLastPanel ? currentSize : 0 - currentSize;
 
     const nextSizes = adjustByDelta(
+      null,
       panels,
       idBefore,
       idAfter,
       delta,
       prevSizes,
-      panelSizeBeforeCollapse.current
+      panelSizeBeforeCollapse.current,
+      null
     );
     if (prevSizes !== nextSizes) {
       // If resize change handlers have been declared, this is the time to call them.
@@ -440,12 +506,14 @@ export function PanelGroup({
     const delta = isLastPanel ? 0 - sizeBeforeCollapse : sizeBeforeCollapse;
 
     const nextSizes = adjustByDelta(
+      null,
       panels,
       idBefore,
       idAfter,
       delta,
       prevSizes,
-      panelSizeBeforeCollapse.current
+      panelSizeBeforeCollapse.current,
+      null
     );
     if (prevSizes !== nextSizes) {
       // If resize change handlers have been declared, this is the time to call them.
@@ -475,6 +543,12 @@ export function PanelGroup({
       return;
     }
 
+    if (panel.collapsible && nextSize === 0) {
+      // This is a valid resize state.
+    } else {
+      nextSize = Math.min(panel.maxSize, Math.max(panel.minSize, nextSize));
+    }
+
     const [idBefore, idAfter] = getBeforeAndAfterIds(id, panelsArray);
     if (idBefore == null || idAfter == null) {
       return;
@@ -484,12 +558,14 @@ export function PanelGroup({
     const delta = isLastPanel ? currentSize - nextSize : nextSize - currentSize;
 
     const nextSizes = adjustByDelta(
+      null,
       panels,
       idBefore,
       idAfter,
       delta,
       prevSizes,
-      panelSizeBeforeCollapse.current
+      panelSizeBeforeCollapse.current,
+      null
     );
     if (prevSizes !== nextSizes) {
       // If resize change handlers have been declared, this is the time to call them.
@@ -513,11 +589,21 @@ export function PanelGroup({
       startDragging: (id: string, event: ResizeEvent) => {
         setActiveHandleId(id);
 
-        dragOffsetRef.current = getDragOffset(event, id, direction);
+        if (isMouseEvent(event) || isTouchEvent(event)) {
+          const handleElement = getResizeHandle(id);
+
+          initialDragStateRef.current = {
+            dragHandleRect: handleElement.getBoundingClientRect(),
+            dragOffset: getDragOffset(event, id, direction),
+            sizes: committedValuesRef.current.sizes,
+          };
+        }
       },
       stopDragging: () => {
         resetGlobalCursorStyle();
         setActiveHandleId(null);
+
+        initialDragStateRef.current = null;
       },
       unregisterPanel,
     }),
@@ -547,6 +633,7 @@ export function PanelGroup({
     children: createElement(Type, {
       children,
       className: classNameFromProps,
+      "data-panel-group": "",
       "data-panel-group-direction": direction,
       "data-panel-group-id": groupId,
       style: { ...style, ...styleFromProps },

package/src/hooks/useWindowSplitterBehavior.ts

@@ -102,12 +102,14 @@ export function useWindowSplitterPanelGroupBehavior({
                 }
 
                 const nextSizes = adjustByDelta(
+                  event,
                   panels,
                   idBefore,
                   idAfter,
                   delta,
                   sizes,
-                  panelSizeBeforeCollapse.current
+                  panelSizeBeforeCollapse.current,
+                  null
                 );
                 if (sizes !== nextSizes) {
                   setSizes(nextSizes);

package/src/index.ts

@@ -5,6 +5,7 @@ import { PanelResizeHandle } from "./PanelResizeHandle";
 import type { ImperativePanelHandle, PanelProps } from "./Panel";
 import type { PanelGroupProps } from "./PanelGroup";
 import type { PanelResizeHandleProps } from "./PanelResizeHandle";
+import type { PanelGroupStorage } from "./types";
 
 export {
   Panel,
@@ -14,6 +15,7 @@ export {
   // TypeScript types
   ImperativePanelHandle,
   PanelGroupProps,
+  PanelGroupStorage,
   PanelProps,
   PanelResizeHandleProps,
 };

package/src/types.ts

@@ -2,6 +2,11 @@ import { RefObject } from "react";
 
 export type Direction = "horizontal" | "vertical";
 
+export type PanelGroupStorage = {
+  getItem(name: string): string | null;
+  setItem(name: string, value: string): void;
+};
+
 export type PanelGroupOnLayout = (sizes: number[]) => void;
 export type PanelOnCollapse = (collapsed: boolean) => void;
 export type PanelOnResize = (size: number) => void;

package/src/utils/arrays.ts

@@ -0,0 +1,13 @@
+export function areEqual(arrayA: any[], arrayB: any[]): boolean {
+  if (arrayA.length !== arrayB.length) {
+    return false;
+  }
+
+  for (let index = 0; index < arrayA.length; index++) {
+    if (arrayA[index] !== arrayB[index]) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/utils/coordinates.ts

@@ -1,4 +1,5 @@
 import { PRECISION } from "../constants";
+import { InitialDragState } from "../PanelGroup";
 import { Direction, PanelData, ResizeEvent } from "../types";
 import {
   getPanelGroup,
@@ -20,7 +21,8 @@ export function getDragOffset(
   event: ResizeEvent,
   handleId: string,
   direction: Direction,
-  initialOffset: number = 0
+  initialOffset: number = 0,
+  initialHandleElementRect: DOMRect | null = null
 ): number {
   const isHorizontal = direction === "horizontal";
 
@@ -35,7 +37,8 @@ export function getDragOffset(
   }
 
   const handleElement = getResizeHandle(handleId);
-  const rect = handleElement.getBoundingClientRect();
+  const rect =
+    initialHandleElementRect || handleElement.getBoundingClientRect();
   const elementOffset = isHorizontal ? rect.left : rect.top;
 
   return pointerOffset - elementOffset - initialOffset;
@@ -48,9 +51,19 @@ export function getMovement(
   handleId: string,
   panelsArray: PanelData[],
   direction: Direction,
-  sizes: number[],
-  initialOffset: number
+  prevSizes: number[],
+  initialDragState: InitialDragState | null
 ): number {
+  const {
+    dragOffset = 0,
+    dragHandleRect,
+    sizes: initialSizes,
+  } = initialDragState || {};
+
+  // If we're resizing by mouse or touch, use the initial sizes as a base.
+  // This has the benefit of causing force-collapsed panels to spring back open if drag is reversed.
+  const baseSizes = initialSizes || prevSizes;
+
   if (isKeyDown(event)) {
     const isHorizontal = direction === "horizontal";
 
@@ -98,10 +111,10 @@ export function getMovement(
     );
     const targetPanel = panelsArray[targetPanelIndex];
     if (targetPanel.collapsible) {
-      const prevSize = sizes[targetPanelIndex];
+      const baseSize = baseSizes[targetPanelIndex];
       if (
-        prevSize === 0 ||
-        prevSize.toPrecision(PRECISION) ===
+        baseSize === 0 ||
+        baseSize.toPrecision(PRECISION) ===
           targetPanel.minSize.toPrecision(PRECISION)
       ) {
         movement =
@@ -113,7 +126,13 @@ export function getMovement(
 
     return movement;
   } else {
-    return getDragOffset(event, handleId, direction, initialOffset);
+    return getDragOffset(
+      event,
+      handleId,
+      direction,
+      dragOffset,
+      dragHandleRect
+    );
   }
 }
 

package/src/utils/group.ts

@@ -1,21 +1,30 @@
 import { PRECISION } from "../constants";
-import { PanelData } from "../types";
+import { InitialDragState } from "../PanelGroup";
+import { PanelData, ResizeEvent } from "../types";
 
 export function adjustByDelta(
+  event: ResizeEvent | null,
   panels: Map<string, PanelData>,
   idBefore: string,
   idAfter: string,
   delta: number,
   prevSizes: number[],
-  panelSizeBeforeCollapse: Map<string, number>
+  panelSizeBeforeCollapse: Map<string, number>,
+  initialDragState: InitialDragState | null
 ): number[] {
+  const { sizes: initialSizes } = initialDragState || {};
+
+  // If we're resizing by mouse or touch, use the initial sizes as a base.
+  // This has the benefit of causing force-collapsed panels to spring back open if drag is reversed.
+  const baseSizes = initialSizes || prevSizes;
+
   if (delta === 0) {
-    return prevSizes;
+    return baseSizes;
   }
 
   const panelsArray = panelsMapToSortedArray(panels);
 
-  const nextSizes = prevSizes.concat();
+  const nextSizes = baseSizes.concat();
 
   let deltaApplied = 0;
 
@@ -32,17 +41,18 @@ export function adjustByDelta(
     const pivotId = delta < 0 ? idAfter : idBefore;
     const index = panelsArray.findIndex((panel) => panel.id === pivotId);
     const panel = panelsArray[index];
-    const prevSize = prevSizes[index];
+    const baseSize = baseSizes[index];
 
-    const nextSize = safeResizePanel(panel, Math.abs(delta), prevSize);
-    if (prevSize === nextSize) {
-      return prevSizes;
+    const nextSize = safeResizePanel(panel, Math.abs(delta), baseSize, event);
+    if (baseSize === nextSize) {
+      // If there's no room for the pivot panel to grow, we can ignore this drag update.
+      return baseSizes;
     } else {
-      if (nextSize === 0 && prevSize > 0) {
-        panelSizeBeforeCollapse.set(pivotId, prevSize);
+      if (nextSize === 0 && baseSize > 0) {
+        panelSizeBeforeCollapse.set(pivotId, baseSize);
       }
 
-      delta = delta < 0 ? prevSize - nextSize : nextSize - prevSize;
+      delta = delta < 0 ? baseSize - nextSize : nextSize - baseSize;
     }
   }
 
@@ -50,19 +60,32 @@ export function adjustByDelta(
   let index = panelsArray.findIndex((panel) => panel.id === pivotId);
   while (true) {
     const panel = panelsArray[index];
-    const prevSize = prevSizes[index];
-
-    const nextSize = safeResizePanel(panel, 0 - Math.abs(delta), prevSize);
-    if (prevSize !== nextSize) {
-      if (nextSize === 0 && prevSize > 0) {
-        panelSizeBeforeCollapse.set(panel.id, prevSize);
+    const baseSize = baseSizes[index];
+
+    const deltaRemaining = Math.abs(delta) - Math.abs(deltaApplied);
+
+    const nextSize = safeResizePanel(
+      panel,
+      0 - deltaRemaining,
+      baseSize,
+      event
+    );
+    if (baseSize !== nextSize) {
+      if (nextSize === 0 && baseSize > 0) {
+        panelSizeBeforeCollapse.set(panel.id, baseSize);
       }
 
-      deltaApplied += prevSize - nextSize;
+      deltaApplied += baseSize - nextSize;
 
       nextSizes[index] = nextSize;
 
-      if (deltaApplied.toPrecision(PRECISION) >= delta.toPrecision(PRECISION)) {
+      if (
+        deltaApplied
+          .toPrecision(PRECISION)
+          .localeCompare(Math.abs(delta).toPrecision(PRECISION), undefined, {
+            numeric: true,
+          }) >= 0
+      ) {
         break;
       }
     }
@@ -81,13 +104,13 @@ export function adjustByDelta(
   // If we were unable to resize any of the panels panels, return the previous state.
   // This will essentially bailout and ignore the "mousemove" event.
   if (deltaApplied === 0) {
-    return prevSizes;
+    return baseSizes;
   }
 
   // Adjust the pivot panel before, but only by the amount that surrounding panels were able to shrink/contract.
   pivotId = delta < 0 ? idAfter : idBefore;
   index = panelsArray.findIndex((panel) => panel.id === pivotId);
-  nextSizes[index] = prevSizes[index] + deltaApplied;
+  nextSizes[index] = baseSizes[index] + deltaApplied;
 
   return nextSizes;
 }
@@ -100,15 +123,17 @@ export function callPanelCallbacks(
   nextSizes.forEach((nextSize, index) => {
     const prevSize = prevSizes[index];
     if (prevSize !== nextSize) {
-      const { callbacksRef } = panelsArray[index];
+      const { callbacksRef, collapsible } = panelsArray[index];
       const { onCollapse, onResize } = callbacksRef.current;
 
       if (onResize) {
         onResize(nextSize);
       }
 
-      if (onCollapse) {
-        if (prevSize === 0 && nextSize !== 0) {
+      if (collapsible && onCollapse) {
+        // Falsy check handles both previous size of 0
+        // and initial size of undefined (when mounting)
+        if (!prevSize && nextSize !== 0) {
           onCollapse(false);
         } else if (prevSize !== 0 && nextSize === 0) {
           onCollapse(true);
@@ -230,7 +255,8 @@ export function panelsMapToSortedArray(
 function safeResizePanel(
   panel: PanelData,
   delta: number,
-  prevSize: number
+  prevSize: number,
+  event: ResizeEvent | null
 ): number {
   const nextSizeUnsafe = prevSize + delta;
 
@@ -240,8 +266,14 @@ function safeResizePanel(
         return 0;
       }
     } else {
-      if (nextSizeUnsafe < panel.minSize) {
-        return 0;
+      const isKeyboardEvent = event?.type?.startsWith("key");
+      if (!isKeyboardEvent) {
+        // Keyboard events should expand a collapsed panel to the min size,
+        // but mouse events should wait until the panel has reached its min size
+        // to avoid a visual flickering when dragging between collapsed and min size.
+        if (nextSizeUnsafe < panel.minSize) {
+          return 0;
+        }
       }
     }
   }

package/src/utils/serialization.ts

@@ -1,4 +1,4 @@
-import { PanelData } from "../types";
+import { PanelData, PanelGroupStorage } from "../types";
 
 type SerializedPanelGroupState = { [panelIds: string]: number[] };
 
@@ -17,10 +17,11 @@ function getSerializationKey(panels: PanelData[]): string {
 }
 
 function loadSerializedPanelGroupState(
-  autoSaveId: string
+  autoSaveId: string,
+  storage: PanelGroupStorage
 ): SerializedPanelGroupState | null {
   try {
-    const serialized = localStorage.getItem(`PanelGroup:sizes:${autoSaveId}`);
+    const serialized = storage.getItem(`PanelGroup:sizes:${autoSaveId}`);
     if (serialized) {
       const parsed = JSON.parse(serialized);
       if (typeof parsed === "object" && parsed != null) {
@@ -34,9 +35,10 @@ function loadSerializedPanelGroupState(
 
 export function loadPanelLayout(
   autoSaveId: string,
-  panels: PanelData[]
+  panels: PanelData[],
+  storage: PanelGroupStorage
 ): number[] | null {
-  const state = loadSerializedPanelGroupState(autoSaveId);
+  const state = loadSerializedPanelGroupState(autoSaveId, storage);
   if (state) {
     const key = getSerializationKey(panels);
     return state[key] || null;
@@ -48,17 +50,15 @@ export function loadPanelLayout(
 export function savePanelGroupLayout(
   autoSaveId: string,
   panels: PanelData[],
-  sizes: number[]
+  sizes: number[],
+  storage: PanelGroupStorage
 ): void {
   const key = getSerializationKey(panels);
-  const state = loadSerializedPanelGroupState(autoSaveId) || {};
+  const state = loadSerializedPanelGroupState(autoSaveId, storage) || {};
   state[key] = sizes;
 
   try {
-    localStorage.setItem(
-      `PanelGroup:sizes:${autoSaveId}`,
-      JSON.stringify(state)
-    );
+    storage.setItem(`PanelGroup:sizes:${autoSaveId}`, JSON.stringify(state));
   } catch (error) {
     console.error(error);
   }