react-resizable-panels 4.11.1 → 4.12.0

package/dist/react-resizable-panels.d.ts

@@ -112,8 +112,13 @@ export declare type GroupProps = HTMLAttributes<HTMLDivElement> & {
      *
      * ℹ️ For layout changes caused by pointer events, this method is not called until the pointer has been released.
      * This method is recommended when saving layouts to some storage api.
+     *
+     * ℹ️ The second argument contains meta information about the layout change.
+     * The `isUserInteraction` 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.)
      */
-    onLayoutChanged?: (layout: Layout) => void | undefined;
+    onLayoutChanged?: (layout: Layout, meta: LayoutChangedMeta) => void;
     /**
      * Minimum size of the resizable hit target area (either `Separator` or `Panel` edge)
      * This threshold ensures are large enough to avoid mis-clicks.
@@ -153,6 +158,22 @@ export declare type Layout = {
     [id: string]: number;
 };
 
+/**
+ * Metadata describing a completed layout change, passed as the second argument
+ * to the `onLayoutChanged` callback. See #716.
+ */
+export declare type LayoutChangedMeta = {
+    /**
+     * `true` when the change was caused by the user directly manipulating a
+     * separator — releasing a pointer drag or pressing a resize key (arrow keys,
+     * Home/End, Enter). `false` for every other source (programmatic `setLayout`
+     * and other imperative API calls, constraint recompute, default-size change,
+     * initial mount), because the library cannot attribute the caller's intent
+     * there.
+     */
+    isUserInteraction: boolean;
+};
+
 export declare type LayoutStorage = Pick<Storage, "getItem" | "setItem">;
 
 export declare type OnGroupLayoutChange = GroupProps["onLayoutChange"];
@@ -409,13 +430,18 @@ export declare type SizeUnit = "px" | "%" | "em" | "rem" | "vh" | "vw";
  * Saves and restores group layouts between page loads.
  * It can be configured to store values using `localStorage`, `sessionStorage`, cookies, or any other persistence layer that makes sense for your application.
  */
-export declare function useDefaultLayout({ debounceSaveMs, panelIds, storage, ...rest }: {
+export declare function useDefaultLayout({ debounceSaveMs, onlySaveAfterUserInteractions, panelIds, storage, ...rest }: {
     /**
      * Debounce save operation by the specified number of milliseconds; defaults to 100ms
      *
      * @deprecated Use the {@link onLayoutChanged} callback instead; it does not require debouncing
      */
     debounceSaveMs?: number;
+    /**
+     * Only auto-save layouts that were directly caused by user input (e.g. keyboard or mouse events).
+     * Ignore layout changes resulting from imperative API calls or window resize events.
+     */
+    onlySaveAfterUserInteractions?: boolean;
     /**
      * For Groups that contain conditionally-rendered Panels, this prop can be used to save and restore multiple layouts.
      *
@@ -455,7 +481,7 @@ export declare function useDefaultLayout({ debounceSaveMs, panelIds, storage, ..
     /**
      * Attach this callback on the `Group` as the `onLayoutChanged` prop.
      */
-    onLayoutChanged: (layout: Layout) => void | undefined;
+    onLayoutChanged: (layout: Layout, meta: LayoutChangedMeta) => void;
 };
 
 /**