Customizable resize preview mode

README.md

@@ -135,6 +135,14 @@ This method is recommended when saving layouts to some storage api.</p>
 The <code>isUserInteraction</code> attribute signals whether the resize was caused by direct user input.
 It is true for resizes caused by pointer or keyboard input
 and false for other triggers (e.g. imperative API calls, initial mount, etc.)</p>
+</td>
+    </tr>
+    <tr>
+      <td>resizePreviewMode</td>
+      <td><p>Controls whether pointer dragging updates <code>Panel</code>s sizes immediately,
+or renders overlay separator previews until the pointer is released.</p>
+<p>Defaults to <code>&quot;panel&quot;</code> (immediate resizing); <code>&quot;separator&quot;</code> defers resizing until release.</p>
+<p>Customize previews using the <code>SeparatorOverlay</code> component.</p>
 </td>
     </tr>
     <tr>
@@ -392,6 +400,11 @@ To prevent a panel from being resized at all, it needs to also be disabled.</p>
     <tr>
       <td>elementRef</td>
       <td><p>Ref attached to the root <code>HTMLDivElement</code>.</p>
+</td>
+    </tr>
+    <tr>
+      <td>preview</td>
+      <td><p>Overrides the <code>Group</code> default preview for this <code>Separator</code> when <code>resizePreviewMode</code> is &quot;separator&quot;.</p>
 </td>
     </tr>
   </tbody>

lib/components/group/Group.tsx

@@ -1,6 +1,12 @@
 "use client";
 
-import { useEffect, useMemo, useRef, type CSSProperties } from "react";
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties
+} from "react";
 import { calculatePanelConstraints } from "../../global/dom/calculatePanelConstraints";
 import { mountGroup } from "../../global/mountGroup";
 import {
@@ -19,8 +25,12 @@ import { useMergedRefs } from "../../hooks/useMergedRefs";
 import { useStableCallback } from "../../hooks/useStableCallback";
 import { useStableObject } from "../../hooks/useStableObject";
 import type { RegisteredPanel } from "../panel/types";
-import type { RegisteredSeparator } from "../separator/types";
+import type {
+  RegisteredSeparator,
+  SeparatorOverlayProps
+} from "../separator/types";
 import { GroupContext } from "./GroupContext";
+import { ResizePreview } from "./ResizePreview";
 import { sortByElementOffset } from "./sortByElementOffset";
 import type {
   GroupProps,
@@ -29,6 +39,7 @@ import type {
   ResizeTargetMinimumSize
 } from "./types";
 import { useGroupImperativeHandle } from "./useGroupImperativeHandle";
+import { useResizePreviews } from "./useResizePreviews";
 
 /**
  * A Group wraps a set of resizable Panel components.
@@ -54,6 +65,7 @@ export function Group({
   onLayoutChange: onLayoutChangeUnstable,
   onLayoutChanged: onLayoutChangedUnstable,
   orientation = "horizontal",
+  resizePreviewMode = "panel",
   resizeTargetMinimumSize = {
     coarse: 20,
     fine: 10
@@ -93,6 +105,13 @@ export function Group({
 
   const id = useId(idProp);
 
+  const [overlay, setOverlay] = useState<SeparatorOverlayProps>();
+
+  const previews = useResizePreviews({
+    groupId: id,
+    resizePreviewMode
+  });
+
   const elementRef = useRef<HTMLDivElement | null>(null);
 
   const [panelOrSeparatorChangeSigil, forceUpdate] = useForceUpdate();
@@ -164,6 +183,13 @@ export function Group({
           forceUpdate();
         };
       },
+      registerOverlay: (props: SeparatorOverlayProps) => {
+        setOverlay(props);
+
+        return () => {
+          setOverlay(undefined);
+        };
+      },
       registerSeparator: (separator: RegisteredSeparator) => {
         const inMemoryValues = inMemoryValuesRef.current;
         inMemoryValues.separators = sortByElementOffset(orientation, [
@@ -266,6 +292,7 @@ export function Group({
       },
       orientation,
       panels: inMemoryValues.panels,
+      resizePreviewMode,
       resizeTargetMinimumSize: inMemoryValues.resizeTargetMinimumSize,
       separators: inMemoryValues.separators
     };
@@ -343,6 +370,7 @@ export function Group({
     onLayoutChangeStable,
     orientation,
     panelOrSeparatorChangeSigil,
+    resizePreviewMode,
     stableProps
   ]);
 
@@ -369,6 +397,7 @@ export function Group({
           height: "100%",
           width: "100%",
           overflow: "hidden",
+          position: resizePreviewMode === "separator" ? "relative" : undefined,
 
           ...style,
 
@@ -384,6 +413,13 @@ export function Group({
         }}
       >
         {children}
+        {previews.map((preview) => (
+          <ResizePreview
+            key={preview.key}
+            overlay={overlay}
+            preview={preview}
+          />
+        ))}
       </div>
     </GroupContext.Provider>
   );