react-resizable-panels 4.0.0-alpha.0 → 4.0.0-alpha.2

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

@@ -7,31 +7,30 @@ import { Ref } from 'react';
 import { RefObject } from 'react';
 import { SetStateAction } from 'react';
 
-/**
- * Panel group direction corresponds to the `flex-direction` CSS property.
- * It determines how panels are are placed in the group group and the direction they can be resized in.
- * Horizontal corresponds to flex "row" and vertical to "column".
- */
-export declare type Direction = "horizontal" | "vertical";
-
 /**
  * A Group wraps a set of resizable Panel components.
  * Group content can be resized _horizontally_ or _vertically_.
  *
- * For unit testing purposes, Group elements always include the following data attributes:
+ * Group elements always include the following data attributes:
  *
  * ```html
- * <div data-group data-group-id="your-group-id">
+ * <div data-group data-testid="your-group-id">
  * ```
+ *
+ * ℹ️ [Test id](https://testing-library.com/docs/queries/bytestid/) can be used to narrow selection when unit testing.
  */
-export declare function Group({ children, className, defaultLayout, direction, disableCursor, disabled, elementRef, groupRef, id: idProp, onLayoutChange: onLayoutChangeUnstable, style }: GroupProps): JSX.Element;
+export declare function Group({ children, className, defaultLayout, disableCursor, disabled, elementRef, groupRef, id: idProp, onLayoutChange: onLayoutChangeUnstable, orientation, style }: GroupProps): JSX.Element;
 
 /**
  * Imperative Group API.
+ *
+ * ℹ️ The `useGroupRef` and `useGroupCallbackRef` hooks are exported for convenience use in TypeScript projects.
  */
 declare interface GroupImperativeHandle {
     /**
      * Get the Group's current layout as a map of Panel id to percentage (0..100)
+     *
+     * @return Map of Panel id to percentage (0..100)
      */
     getLayout: () => {
         [panelId: string]: number;
@@ -51,11 +50,11 @@ export declare type GroupProps = {
     /**
      * Panel and Separator components that comprise this group.
      */
-    children?: ReactNode;
+    children?: ReactNode | undefined;
     /**
      * CSS class name.
      */
-    className?: string;
+    className?: string | undefined;
     /**
      * Default layout for the Group.
      *
@@ -63,24 +62,20 @@ export declare type GroupProps = {
      *
      * ⚠️ Refer to the documentation for how to avoid layout shift when using server components.
      */
-    defaultLayout?: Layout;
-    /**
-     * Specifies the resizable direction ("horizontal" or "vertical"); defaults to "horizontal"
-     */
-    direction?: "horizontal" | "vertical";
+    defaultLayout?: Layout | undefined;
     /**
      * This library sets custom mouse cursor styles to indicate drag state.
      * Use this prop to disable that behavior for Panels and Separators in this group.
      */
-    disableCursor?: boolean;
+    disableCursor?: boolean | undefined;
     /**
      * Disable resize functionality.
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /**
      * Ref attached to the root `HTMLDivElement`.
      */
-    elementRef?: Ref<HTMLDivElement>;
+    elementRef?: Ref<HTMLDivElement> | undefined;
     /**
      * Exposes the following imperative API:
      * - `getLayout(): Layout`
@@ -88,24 +83,28 @@ export declare type GroupProps = {
      *
      * ℹ️ The `useGroupRef` and `useGroupCallbackRef` hooks are exported for convenience use in TypeScript projects.
      */
-    groupRef?: Ref<GroupImperativeHandle>;
+    groupRef?: Ref<GroupImperativeHandle> | undefined;
     /**
      * Uniquely identifies this group within an application.
      * Falls back to `useId` when not provided.
      *
-     * ℹ️ This value will also be assigned to the `data-group-id` attribute.
+     * ℹ️ This value will also be assigned to the `data-group` attribute.
      */
-    id?: string | number;
+    id?: string | number | undefined;
     /**
      * Called when panel sizes change; receives a map of Panel id to size.
      */
-    onLayoutChange?: (layout: Layout) => void;
+    onLayoutChange?: (layout: Layout) => void | undefined;
+    /**
+     * Specifies the resizable orientation ("horizontal" or "vertical"); defaults to "horizontal"
+     */
+    orientation?: "horizontal" | "vertical" | undefined;
     /**
      * CSS properties.
      *
      * ⚠️ The following styles cannot be overridden: `display`, `flex-direction`, `flex-wrap`, and `overflow`.
      */
-    style?: CSSProperties;
+    style?: CSSProperties | undefined;
 };
 
 /**
@@ -115,10 +114,18 @@ export declare type Layout = {
     [id: string]: number;
 };
 
+export declare type LayoutStorage = Pick<Storage, "getItem" | "setItem">;
+
 export declare type OnGroupLayoutChange = GroupProps["onLayoutChange"];
 
 export declare type OnPanelResize = PanelProps["onResize"];
 
+/**
+ * Panel group orientation loosely relates to the `aria-orientation` attribute.
+ * It determines how panels are are laid out within the group group and the direction they can be resized in.
+ */
+export declare type Orientation = "horizontal" | "vertical";
+
 /**
  * A Panel wraps resizable content and can be configured with min/max size constraints and collapsible behavior.
  *
@@ -128,30 +135,38 @@ export declare type OnPanelResize = PanelProps["onResize"];
  * - Font sizes (em, rem)
  * - Viewport sizes (vh, vw)
  *
- * For unit testing purposes, Panel elements always include the following data attributes:
+ * Panel elements always include the following data attributes:
  *
  * ```html
- * <div data-panel data-panel-id="your-panel-id">
+ * <div data-panel data-testid="your-panel-id">
  * ```
+ *
+ * ℹ️ [Test id](https://testing-library.com/docs/queries/bytestid/) can be used to narrow selection when unit testing.
  */
 export declare function Panel({ children, className, collapsedSize, collapsible, defaultSize, elementRef, id: idProp, maxSize, minSize, onResize: onResizeUnstable, panelRef, style }: PanelProps): JSX.Element;
 
 /**
  * Imperative Panel API
+ *
+ * ℹ️ The `usePanelRef` and `usePanelCallbackRef` hooks are exported for convenience use in TypeScript projects.
  */
 declare interface PanelImperativeHandle {
     /**
      * Collapse the Panel to it's `collapsedSize`.
-     * This method will do nothing if the Panel is not `collapsible` or if it is already collapsed.
+     *
+     * ⚠️ This method will do nothing if the Panel is not `collapsible` or if it is already collapsed.
      */
     collapse: () => void;
     /**
      * Expand a collapsed Panel to its most recent size.
-     * This method will do nothing if the Panel is not currently collapsed.
+     *
+     * ⚠️ This method will do nothing if the Panel is not currently collapsed.
      */
     expand: () => void;
     /**
      * Get the current size of the Panel in pixels as well as a percentage of the parent group (0..100).
+     *
+     * @return Panel size (in pixels and as a percentage of the parent group)
      */
     getSize: () => PanelSize;
     /**
@@ -160,7 +175,11 @@ declare interface PanelImperativeHandle {
     isCollapsed: () => boolean;
     /**
      * Update the Panel's size.
-     * Size may be specified in pixel format (number) or as a percentage (string).
+     *
+     * ℹ️ Size may be specified in pixel format (number) or as a percentage (string).
+     *
+     * @param size New panel size
+     * @return Applied size (after validation)
      */
     resize: (size: number | string) => void;
 }
@@ -171,46 +190,46 @@ export declare type PanelProps = PropsWithChildren<{
      *
      * ⚠️ Class is applied to nested `HTMLDivElement` to avoid styles that interfere with Flex layout.
      */
-    className?: string;
+    className?: string | undefined;
     /**
      * Panel size when collapsed; defaults to 0.
      */
-    collapsedSize?: number | string;
+    collapsedSize?: number | string | undefined;
     /**
      * This panel can be collapsed.
      *
      * ℹ️ A collapsible panel will collapse when it's size is less than of the specified `minSize`
      */
-    collapsible?: boolean;
+    collapsible?: boolean | undefined;
     /**
      * Default size of Panel within its parent group; default is auto-assigned based on the total number of Panels.
      */
-    defaultSize?: number | string;
+    defaultSize?: number | string | undefined;
     /**
      * Ref attached to the root `HTMLDivElement`.
      */
-    elementRef?: Ref<HTMLDivElement>;
+    elementRef?: Ref<HTMLDivElement> | undefined;
     /**
      * Uniquely identifies this panel within the parent group.
      * Falls back to `useId` when not provided.
      *
      * ℹ️ This prop is used to associate persisted group layouts with the original panel.
      *
-     * ℹ️ This value will also be assigned to the `data-panel-id` attribute.
+     * ℹ️ This value will also be assigned to the `data-panel` attribute.
      */
-    id?: string | number;
+    id?: string | number | undefined;
     /**
      * Maximum size of Panel within its parent group; defaults to 100%.
      */
-    maxSize?: number | string;
+    maxSize?: number | string | undefined;
     /**
      * Minimum size of Panel within its parent group; defaults to 0%.
      */
-    minSize?: number | string;
+    minSize?: number | string | undefined;
     /**
      * Called when panel sizes change; receives a map of Panel id to size.
      */
-    onResize?: (panelSize: PanelSize) => void;
+    onResize?: ((panelSize: PanelSize, id: string | number | undefined) => void) | undefined;
     /**
      * Exposes the following imperative API:
      * - `collapse(): void`
@@ -222,13 +241,13 @@ export declare type PanelProps = PropsWithChildren<{
      *
      * ℹ️ The `usePanelRef` and `usePanelCallbackRef` hooks are exported for convenience use in TypeScript projects.
      */
-    panelRef?: Ref<PanelImperativeHandle>;
+    panelRef?: Ref<PanelImperativeHandle> | undefined;
     /**
      * CSS properties.
      *
      * ⚠️ Style is applied to nested `HTMLDivElement` to avoid styles that interfere with Flex layout.
      */
-    style?: CSSProperties;
+    style?: CSSProperties | undefined;
 }>;
 
 export declare type PanelSize = {
@@ -241,11 +260,13 @@ export declare type PanelSize = {
  *
  * Separators should be rendered as the direct child of a Group component.
  *
- * For unit testing purposes, Separator elements always include the following data attributes:
+ * Separator elements always include the following data attributes and role:
  *
  * ```html
- * <div data-separator data-separator-id="your-separator-id" />
+ * <div data-separator data-testid="your-separator-id" role="separator" />
  * ```
+ *
+ * ℹ️ [Test id](https://testing-library.com/docs/queries/bytestid/) can be used to narrow selection when unit testing.
  */
 export declare function Separator({ children, className, elementRef, id: idProp, style }: SeparatorProps): JSX.Element;
 
@@ -253,40 +274,40 @@ export declare type SeparatorProps = PropsWithChildren<{
     /**
      * CSS class name.
      *
-     * ℹ️ Use the `data-separator-state` attribute for custom _hover_ and _active_ styles
+     * ℹ️ Use the `data-separator` attribute for custom _hover_ and _active_ styles
      *
      * ⚠️ The following properties cannot be overridden: `flex-grow`, `flex-shrink`
      */
-    className?: string;
+    className?: string | undefined;
     /**
      * Ref attached to the root `HTMLDivElement`.
      */
-    elementRef?: Ref<HTMLDivElement>;
+    elementRef?: Ref<HTMLDivElement> | undefined;
     /**
      * Uniquely identifies the separator within the parent group.
      * Falls back to `useId` when not provided.
      *
-     * ℹ️ This value will also be assigned to the `data-separator-id` attribute.
+     * ℹ️ This value will also be assigned to the `data-separator` attribute.
      */
-    id?: string | number;
+    id?: string | number | undefined;
     /**
      * CSS properties.
      *
-     * ℹ️ Use the `data-separator-state` attribute for custom _hover_ and _active_ styles
+     * ℹ️ Use the `data-separator` attribute for custom _hover_ and _active_ styles
      *
      * ⚠️ The following properties cannot be overridden: `flex-grow`, `flex-shrink`
      */
-    style?: CSSProperties;
+    style?: CSSProperties | undefined;
 }>;
 
 export declare type SizeUnit = "px" | "%" | "em" | "rem" | "vh" | "vw";
 
 export declare function useDefaultLayout({ groupId, storage }: {
     groupId: string;
-    storage?: Pick<Storage, "getItem" | "setItem">;
+    storage: LayoutStorage;
 }): {
-    defaultLayout: Layout | undefined;
-    onLayoutChange: (layout: Layout) => void;
+    defaultLayout: any;
+    onLayoutChange: (layout: Layout) => void | undefined;
 };
 
 /**