react-resizable-panels 0.0.54 → 0.0.56

package/src/utils/validatePanelGroupLayout.test.ts

@@ -0,0 +1,233 @@
+import { verifyExpectedWarnings } from "./test-utils";
+import { validatePanelGroupLayout } from "./validatePanelGroupLayout";
+
+describe("validatePanelGroupLayout", () => {
+  it("should accept requested layout if there are no constraints provided", () => {
+    expect(
+      validatePanelGroupLayout({
+        groupSizePixels: NaN,
+        layout: [10, 60, 30],
+        panelConstraints: [{}, {}, {}],
+      })
+    ).toEqual([10, 60, 30]);
+  });
+
+  it("should reject layouts that do not total 100%", () => {
+    verifyExpectedWarnings(
+      () =>
+        validatePanelGroupLayout({
+          groupSizePixels: NaN,
+          layout: [10, 20, 30],
+          panelConstraints: [{}, {}, {}],
+        }),
+      "Invalid layout total size"
+    );
+
+    verifyExpectedWarnings(
+      () =>
+        validatePanelGroupLayout({
+          groupSizePixels: NaN,
+          layout: [50, 100, 150],
+          panelConstraints: [{}, {}, {}],
+        }),
+      "Invalid layout total size"
+    );
+  });
+
+  it("should reject layouts that do not match the number of panels", () => {
+    expect(() =>
+      validatePanelGroupLayout({
+        groupSizePixels: NaN,
+        layout: [10, 20, 30],
+        panelConstraints: [{}, {}],
+      })
+    ).toThrow("Invalid 2 panel layout");
+
+    expect(() =>
+      validatePanelGroupLayout({
+        groupSizePixels: NaN,
+        layout: [50, 50],
+        panelConstraints: [{}, {}, {}],
+      })
+    ).toThrow("Invalid 3 panel layout");
+  });
+
+  describe("minimum size constraints", () => {
+    it("should adjust the layout to account for minimum percentage sizes", () => {
+      expect(
+        validatePanelGroupLayout({
+          groupSizePixels: NaN,
+          layout: [25, 75],
+          panelConstraints: [
+            {
+              minSizePercentage: 35,
+            },
+            {},
+          ],
+        })
+      ).toEqual([35, 65]);
+    });
+
+    it("should adjust the layout to account for minimum pixel sizes", () => {
+      expect(
+        validatePanelGroupLayout({
+          groupSizePixels: 400,
+          layout: [20, 80],
+          panelConstraints: [
+            {
+              minSizePixels: 100,
+            },
+            {},
+          ],
+        })
+      ).toEqual([25, 75]);
+    });
+
+    it("should account for multiple panels with minimum size constraints", () => {
+      expect(
+        validatePanelGroupLayout({
+          groupSizePixels: NaN,
+          layout: [20, 60, 20],
+          panelConstraints: [
+            {
+              minSizePercentage: 25,
+            },
+            {},
+            {
+              minSizePercentage: 25,
+            },
+          ],
+        })
+      ).toEqual([25, 50, 25]);
+    });
+  });
+
+  describe("maximum size constraints", () => {
+    it("should adjust the layout to account for maximum percentage sizes", () => {
+      expect(
+        validatePanelGroupLayout({
+          groupSizePixels: NaN,
+          layout: [25, 75],
+          panelConstraints: [{}, { maxSizePercentage: 65 }],
+        })
+      ).toEqual([35, 65]);
+    });
+
+    it("should adjust the layout to account for maximum pixel sizes", () => {
+      expect(
+        validatePanelGroupLayout({
+          groupSizePixels: 400,
+          layout: [20, 80],
+          panelConstraints: [
+            {},
+            {
+              maxSizePixels: 100,
+            },
+          ],
+        })
+      ).toEqual([75, 25]);
+    });
+
+    it("should account for multiple panels with maximum size constraints", () => {
+      expect(
+        validatePanelGroupLayout({
+          groupSizePixels: NaN,
+          layout: [20, 60, 20],
+          panelConstraints: [
+            {
+              maxSizePercentage: 15,
+            },
+            { maxSizePercentage: 50 },
+            {},
+          ],
+        })
+      ).toEqual([15, 50, 35]);
+    });
+  });
+
+  describe("collapsible panels", () => {
+    it("should not collapse a panel that's at or above the minimum size", () => {
+      expect(
+        validatePanelGroupLayout({
+          groupSizePixels: NaN,
+          layout: [25, 75],
+          panelConstraints: [{ collapsible: true, minSizePercentage: 25 }, {}],
+        })
+      ).toEqual([25, 75]);
+    });
+
+    it("should collapse a panel that's below the minimum percentage size", () => {
+      expect(
+        validatePanelGroupLayout({
+          groupSizePixels: NaN,
+          layout: [20, 80],
+          panelConstraints: [
+            {
+              collapsible: true,
+              collapsedSizePercentage: 10,
+              minSizePercentage: 25,
+            },
+            {},
+          ],
+        })
+      ).toEqual([10, 90]);
+    });
+
+    it("should collapse a panel that's below the minimum pixel size", () => {
+      expect(
+        validatePanelGroupLayout({
+          groupSizePixels: 400,
+          layout: [20, 80],
+          panelConstraints: [
+            {
+              collapsible: true,
+              collapsedSizePixels: 40,
+              minSizePixels: 100,
+            },
+            {},
+          ],
+        })
+      ).toEqual([10, 90]);
+    });
+  });
+
+  describe("combination of minimum and maximum size constraints", () => {
+    it("three panel min/max configuration", () => {
+      expect(
+        validatePanelGroupLayout({
+          groupSizePixels: NaN,
+          layout: [25, 50, 25],
+          panelConstraints: [
+            { minSizePercentage: 10, maxSizePercentage: 25 },
+            { maxSizePercentage: 75 },
+            { minSizePercentage: 10, maxSizePercentage: 50 },
+          ],
+        })
+      ).toEqual([25, 50, 25]);
+
+      expect(
+        validatePanelGroupLayout({
+          groupSizePixels: NaN,
+          layout: [5, 80, 15],
+          panelConstraints: [
+            { minSizePercentage: 10, maxSizePercentage: 25 },
+            { maxSizePercentage: 75 },
+            { minSizePercentage: 10, maxSizePercentage: 50 },
+          ],
+        })
+      ).toEqual([10, 75, 15]);
+
+      expect(
+        validatePanelGroupLayout({
+          groupSizePixels: NaN,
+          layout: [30, 10, 60],
+          panelConstraints: [
+            { minSizePercentage: 10, maxSizePercentage: 25 },
+            { maxSizePercentage: 75 },
+            { minSizePercentage: 10, maxSizePercentage: 50 },
+          ],
+        })
+      ).toEqual([25, 25, 50]);
+    });
+  });
+});

package/src/utils/validatePanelGroupLayout.ts

@@ -0,0 +1,88 @@
+import { isDevelopment } from "#is-development";
+import { PanelConstraints } from "../Panel";
+import { fuzzyNumbersEqual } from "./numbers/fuzzyNumbersEqual";
+import { resizePanel } from "./resizePanel";
+
+// All units must be in percentages; pixel values should be pre-converted
+export function validatePanelGroupLayout({
+  groupSizePixels,
+  layout: prevLayout,
+  panelConstraints,
+}: {
+  groupSizePixels: number;
+  layout: number[];
+  panelConstraints: PanelConstraints[];
+}): number[] {
+  const nextLayout = [...prevLayout];
+
+  // Validate layout expectations
+  if (nextLayout.length !== panelConstraints.length) {
+    throw Error(
+      `Invalid ${panelConstraints.length} panel layout: ${nextLayout
+        .map((size) => `${size}%`)
+        .join(", ")}`
+    );
+  } else if (
+    !fuzzyNumbersEqual(
+      nextLayout.reduce((accumulated, current) => accumulated + current, 0),
+      100
+    )
+  ) {
+    // This is not ideal so we should warn about it, but it may be recoverable in some cases
+    // (especially if the amount is small)
+    if (isDevelopment) {
+      console.warn(
+        `WARNING: Invalid layout total size: ${nextLayout
+          .map((size) => `${size}%`)
+          .join(", ")}`
+      );
+    }
+  }
+
+  let remainingSize = 0;
+
+  // First pass: Validate the proposed layout given each panel's constraints
+  for (let index = 0; index < panelConstraints.length; index++) {
+    const unsafeSize = nextLayout[index]!;
+
+    const safeSize = resizePanel({
+      groupSizePixels,
+      panelConstraints,
+      panelIndex: index,
+      size: unsafeSize,
+    });
+
+    if (unsafeSize != safeSize) {
+      remainingSize += unsafeSize - safeSize;
+
+      nextLayout[index] = safeSize;
+    }
+  }
+
+  // If there is additional, left over space, assign it to any panel(s) that permits it
+  // (It's not worth taking multiple additional passes to evenly distribute)
+  if (!fuzzyNumbersEqual(remainingSize, 0)) {
+    for (let index = 0; index < panelConstraints.length; index++) {
+      const prevSize = nextLayout[index]!;
+      const unsafeSize = prevSize + remainingSize;
+      const safeSize = resizePanel({
+        groupSizePixels,
+        panelConstraints,
+        panelIndex: index,
+        size: unsafeSize,
+      });
+
+      if (prevSize !== safeSize) {
+        remainingSize -= safeSize - prevSize;
+        nextLayout[index] = safeSize;
+
+        // Once we've used up the remainder, bail
+        if (fuzzyNumbersEqual(remainingSize, 0)) {
+          break;
+        }
+      }
+    }
+  }
+
+  return nextLayout;
+}

package/src/vendor/react.ts

@@ -13,6 +13,7 @@ import type {
   ElementType,
   ForwardedRef,
   MouseEvent,
+  PropsWithChildren,
   ReactNode,
   RefObject,
   TouchEvent,
@@ -21,6 +22,7 @@ import type {
 const {
   createElement,
   createContext,
+  createRef,
   forwardRef,
   useCallback,
   useContext,
@@ -38,6 +40,7 @@ const useId = (React as any)["useId".toString()] as () => string;
 export {
   createElement,
   createContext,
+  createRef,
   forwardRef,
   useCallback,
   useContext,
@@ -55,6 +58,7 @@ export type {
   ElementType,
   ForwardedRef,
   MouseEvent,
+  PropsWithChildren,
   ReactNode,
   RefObject,
   TouchEvent,

package/.eslintrc.json

@@ -1,22 +0,0 @@
-{
-  "ignorePatterns": [".parcel-cache", "dist", "node_modules"],
-  "parser": "@typescript-eslint/parser",
-  "parserOptions": { "project": ["../../tsconfig.json"] },
-  "plugins": ["@typescript-eslint", "no-restricted-imports", "react-hooks"],
-  "root": true,
-  "rules": {
-    "no-restricted-imports": [
-      "error",
-      {
-        "paths": ["react"]
-      }
-    ],
-    "react-hooks/rules-of-hooks": "error",
-    "react-hooks/exhaustive-deps": [
-      "warn",
-      {
-        "additionalHooks": "(useIsomorphicLayoutEffect)"
-      }
-    ]
-  }
-}

package/src/PanelContexts.ts

@@ -1,20 +0,0 @@
-import { CSSProperties, createContext } from "./vendor/react";
-
-import { PanelData, ResizeEvent, ResizeHandler } from "./types";
-
-export const PanelGroupContext = createContext<{
-  activeHandleId: string | null;
-  collapsePanel: (id: string) => void;
-  direction: "horizontal" | "vertical";
-  expandPanel: (id: string) => void;
-  getPanelStyle: (id: string, defaultSize: number | null) => CSSProperties;
-  groupId: string;
-  registerPanel: (id: string, panel: PanelData) => void;
-  registerResizeHandle: (id: string) => ResizeHandler;
-  resizePanel: (id: string, percentage: number) => void;
-  startDragging: (id: string, event: ResizeEvent) => void;
-  stopDragging: () => void;
-  unregisterPanel: (id: string) => void;
-} | null>(null);
-
-PanelGroupContext.displayName = "PanelGroupContext";

package/src/utils/coordinates.ts

@@ -1,149 +0,0 @@
-import { PRECISION } from "../constants";
-import { InitialDragState } from "../PanelGroup";
-import { Direction, PanelData, ResizeEvent } from "../types";
-import {
-  getPanelGroup,
-  getResizeHandle,
-  getResizeHandlePanelIds,
-} from "./group";
-
-export type Coordinates = {
-  movement: number;
-  offset: number;
-};
-
-export type Size = {
-  height: number;
-  width: number;
-};
-
-export function getDragOffset(
-  event: ResizeEvent,
-  handleId: string,
-  direction: Direction,
-  initialOffset: number = 0,
-  initialHandleElementRect: DOMRect | null = null
-): number {
-  const isHorizontal = direction === "horizontal";
-
-  let pointerOffset = 0;
-  if (isMouseEvent(event)) {
-    pointerOffset = isHorizontal ? event.clientX : event.clientY;
-  } else if (isTouchEvent(event)) {
-    const firstTouch = event.touches[0];
-    pointerOffset = isHorizontal ? firstTouch.screenX : firstTouch.screenY;
-  } else {
-    return 0;
-  }
-
-  const handleElement = getResizeHandle(handleId)!;
-  const rect =
-    initialHandleElementRect || handleElement.getBoundingClientRect();
-  const elementOffset = isHorizontal ? rect.left : rect.top;
-
-  return pointerOffset - elementOffset - initialOffset;
-}
-
-// https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/movementX
-export function getMovement(
-  event: ResizeEvent,
-  groupId: string,
-  handleId: string,
-  panelsArray: PanelData[],
-  direction: Direction,
-  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";
-
-    const groupElement = getPanelGroup(groupId)!;
-    const rect = groupElement.getBoundingClientRect();
-    const groupSizeInPixels = isHorizontal ? rect.width : rect.height;
-
-    const denominator = event.shiftKey ? 10 : 100;
-    const delta = groupSizeInPixels / denominator;
-
-    let movement = 0;
-    switch (event.key) {
-      case "ArrowDown":
-        movement = isHorizontal ? 0 : delta;
-        break;
-      case "ArrowLeft":
-        movement = isHorizontal ? -delta : 0;
-        break;
-      case "ArrowRight":
-        movement = isHorizontal ? delta : 0;
-        break;
-      case "ArrowUp":
-        movement = isHorizontal ? 0 : -delta;
-        break;
-      case "End":
-        movement = groupSizeInPixels;
-        break;
-      case "Home":
-        movement = -groupSizeInPixels;
-        break;
-    }
-
-    // If the Panel being resized is collapsible,
-    // we need to special case resizing around the minSize boundary.
-    // If contracting, Panels should shrink to their minSize and then snap to fully collapsed.
-    // If expanding from collapsed, they should snap back to their minSize.
-    const [idBefore, idAfter] = getResizeHandlePanelIds(
-      groupId,
-      handleId,
-      panelsArray
-    );
-    const targetPanelId = movement < 0 ? idBefore : idAfter;
-    const targetPanelIndex = panelsArray.findIndex(
-      (panel) => panel.current.id === targetPanelId
-    );
-    const targetPanel = panelsArray[targetPanelIndex];
-    if (targetPanel.current.collapsible) {
-      const baseSize = baseSizes[targetPanelIndex];
-      if (
-        baseSize === 0 ||
-        baseSize.toPrecision(PRECISION) ===
-          targetPanel.current.minSize.toPrecision(PRECISION)
-      ) {
-        movement =
-          movement < 0
-            ? -targetPanel.current.minSize * groupSizeInPixels
-            : targetPanel.current.minSize * groupSizeInPixels;
-      }
-    }
-
-    return movement;
-  } else {
-    return getDragOffset(
-      event,
-      handleId,
-      direction,
-      dragOffset,
-      dragHandleRect
-    );
-  }
-}
-
-export function isKeyDown(event: ResizeEvent): event is KeyboardEvent {
-  return event.type === "keydown";
-}
-
-export function isMouseEvent(event: ResizeEvent): event is MouseEvent {
-  return event.type.startsWith("mouse");
-}
-
-export function isTouchEvent(event: ResizeEvent): event is TouchEvent {
-  return event.type.startsWith("touch");
-}