react-resizable-panels 0.0.54 → 0.0.56

package/src/Panel.ts

@@ -1,64 +1,100 @@
+import { isBrowser } from "#is-browser";
+import { isDevelopment } from "#is-development";
+import { PanelGroupContext } from "./PanelGroupContext";
 import useIsomorphicLayoutEffect from "./hooks/useIsomorphicEffect";
 import useUniqueId from "./hooks/useUniqueId";
+import { MixedSizes } from "./types";
 import {
-  createElement,
-  CSSProperties,
   ElementType,
   ForwardedRef,
+  PropsWithChildren,
+  createElement,
   forwardRef,
-  ReactNode,
   useContext,
-  useEffect,
   useImperativeHandle,
   useRef,
 } from "./vendor/react";
 
-import { PanelGroupContext } from "./PanelContexts";
-import {
-  PanelCallbackRef,
-  PanelData,
-  PanelOnCollapse,
-  PanelOnResize,
-} from "./types";
-
-export type PanelProps = {
-  children?: ReactNode;
-  className?: string;
-  collapsedSize?: number;
-  collapsible?: boolean;
-  defaultSize?: number | null;
-  id?: string | null;
-  maxSize?: number;
-  minSize?: number;
-  onCollapse?: PanelOnCollapse | null;
-  onResize?: PanelOnResize | null;
-  order?: number | null;
-  style?: CSSProperties;
-  tagName?: ElementType;
+export type PanelOnCollapse = () => void;
+export type PanelOnExpand = () => void;
+export type PanelOnResize = (
+  mixedSizes: MixedSizes,
+  prevMixedSizes: MixedSizes
+) => void;
+
+export type PanelCallbacks = {
+  onCollapse?: PanelOnCollapse;
+  onExpand?: PanelOnExpand;
+  onResize?: PanelOnResize;
+};
+
+export type PanelConstraints = {
+  collapsedSizePercentage?: number | undefined;
+  collapsedSizePixels?: number | undefined;
+  collapsible?: boolean | undefined;
+  defaultSizePercentage?: number | undefined;
+  defaultSizePixels?: number | undefined;
+  maxSizePercentage?: number | undefined;
+  maxSizePixels?: number | undefined;
+  minSizePercentage?: number | undefined;
+  minSizePixels?: number | undefined;
+};
+
+export type PanelData = {
+  callbacks: PanelCallbacks;
+  constraints: PanelConstraints;
+  id: string;
+  idIsFromProps: boolean;
+  order: number | undefined;
 };
 
 export type ImperativePanelHandle = {
   collapse: () => void;
   expand: () => void;
-  getCollapsed(): boolean;
-  getSize(): number;
-  resize: (percentage: number) => void;
+  getId(): string;
+  getSize(): MixedSizes;
+  resize: (size: Partial<MixedSizes>) => void;
 };
 
-function PanelWithForwardedRef({
-  children = null,
+export type PanelProps = PropsWithChildren<{
+  className?: string;
+  collapsedSizePercentage?: number | undefined;
+  collapsedSizePixels?: number | undefined;
+  collapsible?: boolean | undefined;
+  defaultSizePercentage?: number | undefined;
+  defaultSizePixels?: number | undefined;
+  id?: string;
+  maxSizePercentage?: number | undefined;
+  maxSizePixels?: number | undefined;
+  minSizePercentage?: number | undefined;
+  minSizePixels?: number | undefined;
+  onCollapse?: PanelOnCollapse;
+  onExpand?: PanelOnExpand;
+  onResize?: PanelOnResize;
+  order?: number;
+  style?: object;
+  tagName?: ElementType;
+}>;
+
+export function PanelWithForwardedRef({
+  children,
   className: classNameFromProps = "",
-  collapsedSize = 0,
-  collapsible = false,
-  defaultSize = null,
+  collapsedSizePercentage,
+  collapsedSizePixels,
+  collapsible,
+  defaultSizePercentage,
+  defaultSizePixels,
   forwardedRef,
-  id: idFromProps = null,
-  maxSize = 100,
-  minSize = 10,
-  onCollapse = null,
-  onResize = null,
-  order = null,
-  style: styleFromProps = {},
+  id: idFromProps,
+  maxSizePercentage,
+  maxSizePixels,
+  minSizePercentage,
+  minSizePixels,
+  onCollapse,
+  onExpand,
+  onResize,
+  order,
+  style: styleFromProps,
   tagName: Type = "div",
 }: PanelProps & {
   forwardedRef: ForwardedRef<ImperativePanelHandle>;
@@ -70,126 +106,152 @@ function PanelWithForwardedRef({
     );
   }
 
-  const panelId = useUniqueId(idFromProps);
-
   const {
     collapsePanel,
     expandPanel,
+    getPanelSize,
     getPanelStyle,
+    isPanelCollapsed,
     registerPanel,
     resizePanel,
     unregisterPanel,
   } = context;
 
-  // Use a ref to guard against users passing inline props
-  const callbacksRef = useRef<{
-    onCollapse: PanelOnCollapse | null;
-    onResize: PanelOnResize | null;
-  }>({ onCollapse, onResize });
-  useEffect(() => {
-    callbacksRef.current.onCollapse = onCollapse;
-    callbacksRef.current.onResize = onResize;
+  const panelId = useUniqueId(idFromProps);
+
+  const panelDataRef = useRef<PanelData>({
+    callbacks: {
+      onCollapse,
+      onExpand,
+      onResize,
+    },
+    constraints: {
+      collapsedSizePercentage,
+      collapsedSizePixels,
+      collapsible,
+      defaultSizePercentage,
+      defaultSizePixels,
+      maxSizePercentage,
+      maxSizePixels,
+      minSizePercentage,
+      minSizePixels,
+    },
+    id: panelId,
+    idIsFromProps: idFromProps !== undefined,
+    order,
   });
 
-  // Basic props validation
-  if (minSize < 0 || minSize > 100) {
-    throw Error(`Panel minSize must be between 0 and 100, but was ${minSize}`);
-  } else if (maxSize < 0 || maxSize > 100) {
-    throw Error(`Panel maxSize must be between 0 and 100, but was ${maxSize}`);
-  } else {
-    if (defaultSize !== null) {
-      if (defaultSize < 0 || defaultSize > 100) {
-        throw Error(
-          `Panel defaultSize must be between 0 and 100, but was ${defaultSize}`
-        );
-      } else if (minSize > defaultSize && !collapsible) {
-        console.error(
-          `Panel minSize ${minSize} cannot be greater than defaultSize ${defaultSize}`
-        );
+  const devWarningsRef = useRef<{
+    didLogMissingDefaultSizeWarning: boolean;
+  }>({
+    didLogMissingDefaultSizeWarning: false,
+  });
 
-        defaultSize = minSize;
+  // Normally we wouldn't log a warning during render,
+  // but effects don't run on the server, so we can't do it there
+  if (isDevelopment) {
+    if (!devWarningsRef.current.didLogMissingDefaultSizeWarning) {
+      if (
+        !isBrowser &&
+        defaultSizePercentage == null &&
+        defaultSizePixels == null
+      ) {
+        devWarningsRef.current.didLogMissingDefaultSizeWarning = true;
+        console.warn(
+          `WARNING: Panel defaultSizePercentage or defaultSizePixels prop recommended to avoid layout shift after server rendering`
+        );
       }
     }
   }
 
-  const style = getPanelStyle(panelId, defaultSize);
-
-  const committedValuesRef = useRef<{
-    size: number;
-  }>({
-    size: parseSizeFromStyle(style),
-  });
-  const panelDataRef = useRef<{
-    callbacksRef: PanelCallbackRef;
-    collapsedSize: number;
-    collapsible: boolean;
-    defaultSize: number | null;
-    id: string;
-    idWasAutoGenerated: boolean;
-    maxSize: number;
-    minSize: number;
-    order: number | null;
-  }>({
-    callbacksRef,
-    collapsedSize,
-    collapsible,
-    defaultSize,
-    id: panelId,
-    idWasAutoGenerated: idFromProps == null,
-    maxSize,
-    minSize,
-    order,
-  });
   useIsomorphicLayoutEffect(() => {
-    committedValuesRef.current.size = parseSizeFromStyle(style);
+    const { callbacks, constraints } = panelDataRef.current;
 
-    panelDataRef.current.callbacksRef = callbacksRef;
-    panelDataRef.current.collapsedSize = collapsedSize;
-    panelDataRef.current.collapsible = collapsible;
-    panelDataRef.current.defaultSize = defaultSize;
     panelDataRef.current.id = panelId;
-    panelDataRef.current.idWasAutoGenerated = idFromProps == null;
-    panelDataRef.current.maxSize = maxSize;
-    panelDataRef.current.minSize = minSize;
+    panelDataRef.current.idIsFromProps = idFromProps !== undefined;
     panelDataRef.current.order = order;
+
+    callbacks.onCollapse = onCollapse;
+    callbacks.onExpand = onExpand;
+    callbacks.onResize = onResize;
+
+    constraints.collapsedSizePercentage = collapsedSizePercentage;
+    constraints.collapsedSizePixels = collapsedSizePixels;
+    constraints.collapsible = collapsible;
+    constraints.defaultSizePercentage = defaultSizePercentage;
+    constraints.defaultSizePixels = defaultSizePixels;
+    constraints.maxSizePercentage = maxSizePercentage;
+    constraints.maxSizePixels = maxSizePixels;
+    constraints.minSizePercentage = minSizePercentage;
+    constraints.minSizePixels = minSizePixels;
   });
 
   useIsomorphicLayoutEffect(() => {
-    registerPanel(panelId, panelDataRef as PanelData);
+    const panelData = panelDataRef.current;
+
+    registerPanel(panelData);
 
     return () => {
-      unregisterPanel(panelId);
+      unregisterPanel(panelData);
     };
   }, [order, panelId, registerPanel, unregisterPanel]);
 
   useImperativeHandle(
     forwardedRef,
     () => ({
-      collapse: () => collapsePanel(panelId),
-      expand: () => expandPanel(panelId),
-      getCollapsed() {
-        return committedValuesRef.current.size === 0;
+      collapse: () => {
+        collapsePanel(panelDataRef.current);
+      },
+      expand: () => {
+        expandPanel(panelDataRef.current);
+      },
+      getId() {
+        return panelId;
       },
       getSize() {
-        return committedValuesRef.current.size;
+        return getPanelSize(panelDataRef.current);
+      },
+      isCollapsed() {
+        return isPanelCollapsed(panelDataRef.current);
+      },
+      isExpanded() {
+        return !isPanelCollapsed(panelDataRef.current);
+      },
+      resize: (mixedSizes: Partial<MixedSizes>) => {
+        resizePanel(panelDataRef.current, mixedSizes);
       },
-      resize: (percentage: number) => resizePanel(panelId, percentage),
     }),
-    [collapsePanel, expandPanel, panelId, resizePanel]
+    [
+      collapsePanel,
+      expandPanel,
+      getPanelSize,
+      isPanelCollapsed,
+      panelId,
+      resizePanel,
+    ]
   );
 
+  const style = getPanelStyle(panelDataRef.current);
+
   return createElement(Type, {
     children,
     className: classNameFromProps,
-    "data-panel": "",
-    "data-panel-collapsible": collapsible || undefined,
-    "data-panel-id": panelId,
-    "data-panel-size": parseFloat("" + style.flexGrow).toFixed(1),
-    id: `data-panel-id-${panelId}`,
     style: {
       ...style,
       ...styleFromProps,
     },
+
+    // CSS selectors
+    "data-panel": "",
+
+    // e2e test attributes
+    "data-panel-collapsible": isDevelopment
+      ? collapsible || undefined
+      : undefined,
+    "data-panel-id": isDevelopment ? panelId : undefined,
+    "data-panel-size": isDevelopment
+      ? parseFloat("" + style.flexGrow).toFixed(1)
+      : undefined,
   });
 }
 
@@ -200,13 +262,3 @@ export const Panel = forwardRef<ImperativePanelHandle, PanelProps>(
 
 PanelWithForwardedRef.displayName = "Panel";
 Panel.displayName = "forwardRef(Panel)";
-
-// HACK
-function parseSizeFromStyle(style: CSSProperties): number {
-  const { flexGrow } = style;
-  if (typeof flexGrow === "string") {
-    return parseFloat(flexGrow);
-  } else {
-    return flexGrow as number;
-  }
-}

package/src/PanelGroup.test.tsx

@@ -0,0 +1,210 @@
+import { Root, createRoot } from "react-dom/client";
+import { act } from "react-dom/test-utils";
+import {
+  ImperativePanelGroupHandle,
+  MixedSizes,
+  Panel,
+  PanelGroup,
+  PanelResizeHandle,
+} from ".";
+import { mockPanelGroupOffsetWidthAndHeight } from "./utils/test-utils";
+import { createRef } from "./vendor/react";
+
+describe("PanelGroup", () => {
+  let expectedWarnings: string[] = [];
+  let root: Root;
+  let uninstallMockOffsetWidthAndHeight: () => void;
+
+  function expectWarning(expectedMessage: string) {
+    expectedWarnings.push(expectedMessage);
+  }
+
+  beforeEach(() => {
+    // @ts-expect-error
+    global.IS_REACT_ACT_ENVIRONMENT = true;
+
+    // JSDom doesn't support element sizes
+    uninstallMockOffsetWidthAndHeight = mockPanelGroupOffsetWidthAndHeight();
+
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+
+    expectedWarnings = [];
+    root = createRoot(container);
+
+    jest.spyOn(console, "warn").mockImplementation((actualMessage: string) => {
+      const match = expectedWarnings.findIndex((expectedMessage) => {
+        return actualMessage.includes(expectedMessage);
+      });
+
+      if (match >= 0) {
+        expectedWarnings.splice(match, 1);
+        return;
+      }
+
+      throw Error(`Unexpected warning: ${actualMessage}`);
+    });
+  });
+
+  afterEach(() => {
+    uninstallMockOffsetWidthAndHeight();
+
+    jest.clearAllMocks();
+    jest.resetModules();
+
+    act(() => {
+      root.unmount();
+    });
+
+    expect(expectedWarnings).toHaveLength(0);
+  });
+
+  describe("imperative handle API", () => {
+    it("should report the most recently rendered group id", () => {
+      const ref = createRef<ImperativePanelGroupHandle>();
+
+      act(() => {
+        root.render(<PanelGroup direction="horizontal" id="one" ref={ref} />);
+      });
+
+      expect(ref.current!.getId()).toBe("one");
+
+      act(() => {
+        root.render(<PanelGroup direction="horizontal" id="two" ref={ref} />);
+      });
+
+      expect(ref.current!.getId()).toBe("two");
+    });
+
+    it("should get and set layouts", () => {
+      const ref = createRef<ImperativePanelGroupHandle>();
+
+      let mostRecentLayout: MixedSizes[] | null = null;
+
+      const onLayout = (layout: MixedSizes[]) => {
+        mostRecentLayout = layout;
+      };
+
+      act(() => {
+        root.render(
+          <PanelGroup direction="horizontal" onLayout={onLayout} ref={ref}>
+            <Panel defaultSizePercentage={50} id="a" />
+            <PanelResizeHandle />
+            <Panel defaultSizePercentage={50} id="b" />
+          </PanelGroup>
+        );
+      });
+
+      expect(mostRecentLayout).toEqual([
+        {
+          sizePercentage: 50,
+          sizePixels: 500,
+        },
+        {
+          sizePercentage: 50,
+          sizePixels: 500,
+        },
+      ]);
+
+      act(() => {
+        ref.current!.setLayout([
+          { sizePercentage: 25 },
+          { sizePercentage: 75 },
+        ]);
+      });
+
+      expect(mostRecentLayout).toEqual([
+        {
+          sizePercentage: 25,
+          sizePixels: 250,
+        },
+        {
+          sizePercentage: 75,
+          sizePixels: 750,
+        },
+      ]);
+    });
+  });
+
+  describe("DEV warnings", () => {
+    it("should warn about unstable layouts without id and order props", () => {
+      act(() => {
+        root.render(
+          <PanelGroup direction="horizontal">
+            <Panel defaultSizePercentage={100} id="a" />
+          </PanelGroup>
+        );
+      });
+
+      expectWarning(
+        "Panel id and order props recommended when panels are dynamically rendered"
+      );
+
+      act(() => {
+        root.render(
+          <PanelGroup direction="horizontal">
+            <Panel defaultSizePercentage={50} id="a" />
+            <PanelResizeHandle />
+            <Panel defaultSizePercentage={50} id="b" />
+          </PanelGroup>
+        );
+      });
+    });
+
+    it("should warn about missing resize handles", () => {
+      expectWarning(
+        'Missing resize handle for PanelGroup "group-without-handle"'
+      );
+
+      act(() => {
+        root.render(
+          <PanelGroup direction="horizontal" id="group-without-handle">
+            <Panel />
+            <Panel />
+          </PanelGroup>
+        );
+      });
+    });
+
+    it("should warn about an invalid declarative layout", () => {
+      expectWarning("Invalid layout total size: 60%, 80%");
+
+      act(() => {
+        root.render(
+          <PanelGroup direction="horizontal" id="group-without-handle">
+            <Panel defaultSizePercentage={60} />
+            <PanelResizeHandle />
+            <Panel defaultSizePercentage={80} />
+          </PanelGroup>
+        );
+      });
+    });
+
+    it("should warn about an invalid layout set via the imperative api", () => {
+      const ref = createRef<ImperativePanelGroupHandle>();
+
+      act(() => {
+        root.render(
+          <PanelGroup
+            direction="horizontal"
+            id="group-without-handle"
+            ref={ref}
+          >
+            <Panel defaultSizePercentage={30} />
+            <PanelResizeHandle />
+            <Panel defaultSizePercentage={70} />
+          </PanelGroup>
+        );
+      });
+
+      expectWarning("Invalid layout total size: 60%, 80%");
+
+      act(() => {
+        ref.current!.setLayout([
+          { sizePercentage: 60 },
+          { sizePercentage: 80 },
+        ]);
+      });
+    });
+  });
+});