react-resizable-panels 4.13.2 → 4.14.0

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

@@ -7,10 +7,465 @@ import { Ref } from 'react';
 import { RefObject } from 'react';
 import { SetStateAction } from 'react';
 
+declare type BaseGridlineProps = {
+    /**
+     * Gridline contents (e.g. a drag handle icon).
+     */
+    children?: ReactNode | undefined;
+    /**
+     * CSS class name.
+     *
+     * ℹ️ Use the `data-separator` attribute for custom _hover_ and _active_ styles
+     */
+    className?: string | undefined;
+    /**
+     * When disabled, the gridline cannot be used to resize its neighboring tracks.
+     *
+     * ℹ️ The tracks may still be resized indirectly (e.g. by an intersecting gridline or another boundary).
+     * To prevent a track from being resized at all, it needs to also be disabled.
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Ref attached to the root `HTMLDivElement`.
+     */
+    elementRef?: Ref<HTMLDivElement> | undefined;
+    /**
+     * CSS properties.
+     *
+     * ⚠️ Grid placement properties are managed by the gridline and cannot be overridden.
+     */
+    style?: CSSProperties | undefined;
+};
+
 declare type BasePanelAttributes = Omit<HTMLAttributes<HTMLDivElement>, "onResize">;
 
 declare type BaseSeparatorAttributes = Omit<HTMLAttributes<HTMLDivElement>, "role" | "tabIndex">;
 
+/**
+ * A Cell occupies one or more tracks (columns and rows) within a Grid.
+ * Cells are resized along with the tracks they occupy.
+ *
+ * Cell elements always include the following attributes:
+ *
+ * ```html
+ * <div data-cell data-testid="cell-id-prop" id="cell-id-prop">
+ * ```
+ *
+ * ℹ️ [Test id](https://testing-library.com/docs/queries/bytestid/) can be used to narrow selection when unit testing.
+ *
+ * ⚠️ Cell elements must be direct DOM children of their parent Grid elements.
+ */
+export declare function Cell({ children, className, column, columnSpan, elementRef: elementRefProp, id: idProp, row, rowSpan, style, ...rest }: CellProps): JSX.Element;
+
+export declare namespace Cell {
+    var displayName: string;
+}
+
+export declare type CellProps = HTMLAttributes<HTMLDivElement> & {
+    /**
+     * Cell contents.
+     */
+    children?: ReactNode | undefined;
+    /**
+     * CSS class name.
+     */
+    className?: string | undefined;
+    /**
+     * Index of the (first) column this cell occupies.
+     */
+    column: number;
+    /**
+     * Number of columns this cell spans; defaults to 1.
+     */
+    columnSpan?: number | undefined;
+    /**
+     * Ref attached to the root `HTMLDivElement`.
+     */
+    elementRef?: Ref<HTMLDivElement | null> | undefined;
+    /**
+     * Uniquely identifies this cell within the parent grid.
+     * Falls back to `useId` when not provided.
+     *
+     * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes.
+     */
+    id?: string | number | undefined;
+    /**
+     * Index of the (first) row this cell occupies.
+     */
+    row: number;
+    /**
+     * Number of rows this cell spans; defaults to 1.
+     */
+    rowSpan?: number | undefined;
+    /**
+     * CSS properties.
+     *
+     * ⚠️ Grid placement properties are managed by the Cell and cannot be overridden.
+     */
+    style?: CSSProperties | undefined;
+};
+
+/**
+ * A Grid arranges resizable Cells in two dimensions.
+ * Columns can be resized horizontally and rows can be resized vertically;
+ * dragging the point where a column boundary and a row boundary intersect resizes both.
+ *
+ * Size constraints (e.g. min/max size, collapsible) are specified per track (column or row),
+ * using the same format as Panel props.
+ *
+ * Cells can span multiple columns and/or rows.
+ * Track boundaries cannot be resized alongside of a cell that spans across them.
+ *
+ * Grid elements always include the following attributes:
+ *
+ * ```html
+ * <div data-grid data-testid="grid-id-prop" id="grid-id-prop">
+ * ```
+ *
+ * ℹ️ [Test id](https://testing-library.com/docs/queries/bytestid/) can be used to narrow selection when unit testing.
+ */
+export declare function Grid({ children, className, columns, defaultLayout, disableCursor, disabled, elementRef: elementRefProp, gridRef, id: idProp, onLayoutChange: onLayoutChangeUnstable, onLayoutChanged: onLayoutChangedUnstable, resizeTargetMinimumSize, rows, style, ...rest }: GridProps): JSX.Element;
+
+export declare namespace Grid {
+    var displayName: string;
+}
+
+/**
+ * A Grid has two independently resizable axes:
+ * - "column" tracks are resized horizontally
+ * - "row" tracks are resized vertically
+ */
+export declare type GridAxis = "column" | "row";
+
+/**
+ * Imperative Grid API.
+ *
+ * ℹ️ The `useGridRef` and `useGridCallbackRef` hooks are exported for convenience use in TypeScript projects.
+ */
+export declare interface GridImperativeHandle {
+    /**
+     * Get the Grid's current layout: maps of column and row ids to percentages (0..100)
+     *
+     * @return Map of column ids to percentages and map of row ids to percentages (specified as numbers ranging between 0..100)
+     */
+    getLayout: () => {
+        columns: {
+            [columnId: string]: number;
+        };
+        rows: {
+            [rowId: string]: number;
+        };
+    };
+    /**
+     * Imperative API for the column or row with the specified id (see `GridTrackImperativeHandle`).
+     *
+     * ℹ️ Tracks without an explicit `id` use their index (e.g. `"0"`) as their id.
+     *
+     * ⚠️ An error will be thrown if the Grid does not contain a matching track.
+     *
+     * @param axis "column" or "row"
+     * @param id Track id
+     */
+    getTrackById: (axis: "column" | "row", id: string | number) => GridTrackImperativeHandle;
+    /**
+     * Imperative API for the column or row at the specified index (see `GridTrackImperativeHandle`).
+     *
+     * ℹ️ The index is resolved to a track id when this method is called; the returned API continues to refer to that id.
+     * Tracks without an explicit `id` use their index as their id,
+     * so specify ids if the API needs to refer to the same track after tracks are added or removed before it.
+     *
+     * ⚠️ An error will be thrown if the index is out of range.
+     *
+     * @param axis "column" or "row"
+     * @param index Track index (starting at 0)
+     */
+    getTrackByIndex: (axis: "column" | "row", index: number) => GridTrackImperativeHandle;
+    /**
+     * Set a new layout for one or both of the Grid's axes.
+     *
+     * @param layout Map of column and/or row ids to percentages (numbers between 0..100)
+     * @return Applied layout (after validation)
+     */
+    setLayout: (layout: {
+        columns?: {
+            [columnId: string]: number;
+        } | undefined;
+        rows?: {
+            [rowId: string]: number;
+        } | undefined;
+    }) => {
+        columns: {
+            [columnId: string]: number;
+        };
+        rows: {
+            [rowId: string]: number;
+        };
+    };
+}
+
+/**
+ * Grid layouts are a pair of (1-dimensional) layouts, one per axis.
+ * Each is a map of track id to percentage (0..100) of the space available to that axis.
+ */
+export declare type GridLayout = {
+    columns: Layout;
+    rows: Layout;
+};
+
+/**
+ * Resizes the columns (or rows) of a Grid.
+ *
+ * For example:
+ *
+ * ```tsx
+ * // Rendered between columns 0 and 1 and spans all rows
+ * <Gridline type="column" column={1} />
+ * ```
+ *
+ * ```tsx
+ * // Rendered between rows 0 and 1 and spans all columns
+ * <Gridline type="row" row={1} />
+ * ```
+ *
+ * ```tsx
+ * // Rendered between columns 0 and 1 alongside of row 2 only
+ * <Gridline type="column" column={1} row={2} rowSpan={1} />
+ * ```
+ *
+ * A gridline should not be rendered alongside of a Cell that spans across its boundary
+ * (this includes disabled gridlines; an error will be logged to the console);
+ * render multiple gridlines along the same boundary instead (e.g. before and after the spanning Cell).
+ *
+ * ℹ️ Once a boundary contains a gridline, it can only be resized using gridlines;
+ * the parts of the boundary that aren't alongside of a gridline can't be dragged.
+ *
+ * Where column and row gridlines intersect, dragging resizes both axes.
+ *
+ * Gridlines are not _required_ but they are _recommended_ as they improve keyboard accessibility.
+ *
+ * Gridline elements always include the following attributes:
+ *
+ * ```html
+ * <div aria-orientation="vertical" data-separator role="separator">
+ * ```
+ *
+ * ℹ️ Column gridlines are vertical (`aria-orientation="vertical"`) and row gridlines are horizontal (`aria-orientation="horizontal"`).
+ *
+ * ℹ️ In addition to the attributes shown above, gridlines also render all required [WAI-ARIA properties](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role#associated_wai-aria_roles_states_and_properties).
+ *
+ * ⚠️ Gridline elements must be direct DOM children of their parent Grid elements.
+ *
+ * ℹ️ Gridlines rendered by another component (rather than directly within the Grid) aren't detected until they mount, so server-rendered layouts may shift slightly during hydration.
+ */
+export declare function Gridline(props: GridlineProps): JSX.Element;
+
+export declare namespace Gridline {
+    var displayName: string;
+}
+
+export declare type GridlineProps = BaseGridlineProps & ({
+    /**
+     * Column gridlines are vertical; they resize the columns on either side of them.
+     * Row gridlines are horizontal; they resize the rows on either side of them.
+     */
+    type: "column";
+    /**
+     * When `type` is "column", the gridline is rendered along the leading (left) edge of this column
+     * (between it and the previous column); must be greater than 0 and less than the number of columns.
+     */
+    column: number;
+    /**
+     * When `type` is "column", index of the first row the gridline is rendered alongside of; defaults to 0.
+     */
+    row?: number | undefined;
+    /**
+     * Number of rows a column gridline spans; defaults to all rows (starting from `row`).
+     *
+     * ℹ️ Gridlines can span a subset of rows in order to avoid cells that span across the boundary they sit on;
+     * multiple gridlines can be rendered along the same boundary (e.g. above and below a spanning cell).
+     */
+    rowSpan?: number | undefined;
+} | {
+    /**
+     * Column gridlines are vertical; they resize the columns on either side of them.
+     * Row gridlines are horizontal; they resize the rows on either side of them.
+     */
+    type: "row";
+    /**
+     * When `type` is "row", index of the first column the gridline is rendered alongside of; defaults to 0.
+     */
+    column?: number | undefined;
+    /**
+     * Number of columns a row gridline spans; defaults to all columns (starting from `column`).
+     *
+     * ℹ️ Gridlines can span a subset of columns in order to avoid cells that span across the boundary they sit on;
+     * multiple gridlines can be rendered along the same boundary (e.g. before and after a spanning cell).
+     */
+    columnSpan?: number | undefined;
+    /**
+     * When `type` is "row", the gridline is rendered along the leading (top) edge of this row
+     * (between it and the previous row); must be greater than 0 and less than the number of rows.
+     */
+    row: number;
+});
+
+export declare type GridProps = HTMLAttributes<HTMLDivElement> & {
+    /**
+     * Cell and Gridline components that comprise this grid.
+     *
+     * ⚠️ Cell and Gridline elements must be direct DOM children of their parent Grid element.
+     */
+    children?: ReactNode | undefined;
+    /**
+     * CSS class name.
+     */
+    className?: string | undefined;
+    /**
+     * Grid columns; either the number of columns or an array of size constraints (one per column).
+     */
+    columns: number | GridTrackProps[];
+    /**
+     * Default layout for either or both of the Grid's axes.
+     *
+     * ℹ️ This value allows layouts to be remembered between page reloads.
+     */
+    defaultLayout?: Partial<GridLayout> | undefined;
+    /**
+     * This library sets custom mouse cursor styles to indicate drag state.
+     * Use this prop to disable that behavior for this grid.
+     */
+    disableCursor?: boolean | undefined;
+    /**
+     * Disable resize functionality.
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Ref attached to the root `HTMLDivElement`.
+     */
+    elementRef?: Ref<HTMLDivElement | null> | undefined;
+    /**
+     * Exposes the following imperative API:
+     * - `getLayout(): GridLayout`
+     * - `getTrackById(axis: "column" | "row", id: string | number): GridTrackImperativeHandle`
+     * - `getTrackByIndex(axis: "column" | "row", index: number): GridTrackImperativeHandle`
+     * - `setLayout(layout: Partial<GridLayout>): GridLayout`
+     *
+     * ℹ️ The `useGridRef` and `useGridCallbackRef` hooks are exported for convenience use in TypeScript projects.
+     */
+    gridRef?: Ref<GridImperativeHandle | null> | undefined;
+    /**
+     * Uniquely identifies this grid within an application.
+     * Falls back to `useId` when not provided.
+     *
+     * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes.
+     */
+    id?: string | number | undefined;
+    /**
+     * Called when the Grid's layout is changing.
+     *
+     * ⚠️ For layout changes caused by pointer events, this method is called each time the pointer is moved.
+     * For most cases, it is recommended to use the `onLayoutChanged` callback instead.
+     */
+    onLayoutChange?: ((layout: GridLayout) => void) | undefined;
+    /**
+     * Called after the Grid's layout has been changed.
+     *
+     * ℹ️ 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.
+     */
+    onLayoutChanged?: ((layout: GridLayout, meta: LayoutChangedMeta) => void) | undefined;
+    /**
+     * Minimum size of the resizable hit target area (either a `Gridline` or a `Cell` edge)
+     * This threshold ensures targets are large enough to avoid mis-clicks.
+     *
+     * ℹ️ Refer to the `Group` prop of the same name for more information.
+     */
+    resizeTargetMinimumSize?: {
+        coarse: number;
+        fine: number;
+    };
+    /**
+     * Grid rows; either the number of rows or an array of size constraints (one per row).
+     */
+    rows: number | GridTrackProps[];
+    /**
+     * CSS properties.
+     *
+     * ⚠️ Grid template and display properties are managed by the Grid and cannot be overridden.
+     */
+    style?: CSSProperties | undefined;
+};
+
+/**
+ * Imperative API for an individual Grid track (column or row); returned by `GridImperativeHandle.getTrackById` and `GridImperativeHandle.getTrackByIndex`.
+ *
+ * ℹ️ Sizes are relative to the space available to the track's axis
+ * (e.g. the width of the Grid, minus gaps and gridlines, for a column).
+ */
+export declare interface GridTrackImperativeHandle {
+    /**
+     * Collapse the track to its `collapsedSize`.
+     *
+     * ⚠️ This method will do nothing if the track is not `collapsible` or if it is already collapsed.
+     */
+    collapse: () => void;
+    /**
+     * Expand a collapsed track to its most recent size.
+     *
+     * ⚠️ This method will do nothing if the track is not currently collapsed.
+     */
+    expand: () => void;
+    /**
+     * Get the current size of the track in pixels as well as a percentage of its axis (0..100).
+     *
+     * @return Track size (in pixels and as a percentage of its axis)
+     */
+    getSize: () => {
+        asPercentage: number;
+        inPixels: number;
+    };
+    /**
+     * The track is currently collapsed.
+     */
+    isCollapsed: () => boolean;
+    /**
+     * Update the track's size.
+     *
+     * Size can be in the following formats:
+     * - Percentage of the axis (0..100)
+     * - Pixels
+     * - Relative font units (em, rem)
+     * - Viewport relative units (vh, vw)
+     *
+     * ℹ️ Numeric values are assumed to be pixels.
+     * Strings without explicit units are assumed to be percentages (0%..100%).
+     * Percentages may also be specified as strings ending with "%" (e.g. "33%")
+     * Pixels may also be specified as strings ending with the unit "px".
+     * Other units should be specified as strings ending with their CSS property units (e.g. 1rem, 50vh)
+     *
+     * @param size New track size
+     */
+    resize: (size: number | string) => void;
+}
+
+/**
+ * Size constraints for a Grid track (a column or a row).
+ *
+ * Tracks support the same constraints as Panels,
+ * using the same [interpretation rules](https://react-resizable-panels.vercel.app/examples/size-constraints):
+ * - Numbers are interpreted as pixels (e.g. `minSize={200}` is 200 pixels)
+ * - Strings without explicit units are interpreted as percentage (e.g. `minSize="50"` is 50 percent)
+ * - Use explicit units (e.g. "px", "%", "em", "rem", "vh", or "vw") to change interpretation
+ */
+export declare type GridTrackProps = PanelConstraintProps & {
+    /**
+     * Uniquely identifies this track within its axis; defaults to the track's index.
+     *
+     * ℹ️ This value is used as the key for this track in the Grid's layout.
+     */
+    id?: string | number | undefined;
+};
+
 /**
  * A Group wraps a set of resizable Panel components.
  * Group content can be resized _horizontally_ or _vertically_.
@@ -97,7 +552,7 @@ export declare type GroupProps = HTMLAttributes<HTMLDivElement> & {
      * Uniquely identifies this group within an application.
      * Falls back to `useId` when not provided.
      *
-     * ℹ️ This value will also be assigned to the `data-group` attribute.
+     * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes.
      */
     id?: string | number | undefined;
     /**
@@ -161,7 +616,7 @@ export declare type GroupProps = HTMLAttributes<HTMLDivElement> & {
 export declare function isCoarsePointer(): boolean;
 
 /**
- * Map of Panel id to flexGrow value;
+ * Map of item (e.g. Panel) id to size (a percentage between 0..100)
  */
 export declare type Layout = {
     [id: string]: number;
@@ -190,8 +645,17 @@ 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.
+ * Types shared by the resize machinery (layout math, pointer and keyboard interactions, cursors, etc.)
+ * which is used by both the Group and Grid components.
+ *
+ * - A "resize axis" is a set of items that can be resized along one orientation;
+ *   e.g. a Group (whose items are Panels) or one axis of a Grid (whose items are columns or rows).
+ * - A "resize item" is one of those items (e.g. a Panel or a Grid track).
+ * - A separator (e.g. a Separator or a Gridline) resizes the items on either side of it.
+ */
+/**
+ * Orientation loosely relates to the `aria-orientation` attribute.
+ * It determines how items are laid out and the direction they can be resized in.
  */
 export declare type Orientation = "horizontal" | "vertical";
 
@@ -226,6 +690,23 @@ export declare namespace Panel {
     var displayName: string;
 }
 
+/**
+ * Size constraints may be specified in a variety of ways:
+ * - Percentage of the parent Group (0..100)
+ * - Pixels
+ * - Relative font units (em, rem)
+ * - Viewport relative units (vh, vw)
+ *
+ * Numeric values are assumed to be pixels.
+ * Strings without explicit units are assumed to be percentages (0%..100%).
+ *
+ * Percentages may also be specified as strings ending with "%" (e.g. "33%")
+ * Pixels may also be specified as strings ending with the unit "px".
+ *
+ * Other units should be specified as strings ending with their CSS property units (e.g. 1rem, 50vh)
+ */
+declare type PanelConstraintProps = Pick<PanelProps, "collapsedSize" | "collapsedThreshold" | "collapsible" | "defaultSize" | "disabled" | "groupResizeBehavior" | "maxSize" | "minSize">;
+
 /**
  * Imperative Panel API
  *
@@ -347,7 +828,7 @@ export declare type PanelProps = BasePanelAttributes & {
      *
      * ℹ️ This prop is used to associate persisted group layouts with the original panel.
      *
-     * ℹ️ This value will also be assigned to the `data-panel` attribute.
+     * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes.
      */
     id?: string | number | undefined;
     /**
@@ -417,7 +898,7 @@ declare type ResizePreviewMode = "panel" | "separator";
  *
  * ℹ️ In addition to the attributes shown above, separator also renders all required [WAI-ARIA properties](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role#associated_wai-aria_roles_states_and_properties).
  */
-export declare function Separator({ children, className, disabled, disableDoubleClick, elementRef: elementRefProp, id: idProp, preview, style, ...rest }: SeparatorProps): JSX.Element;
+export declare function Separator({ children, className, disabled, disableDoubleClick, elementRef, id: idProp, preview, style, ...rest }: SeparatorProps): JSX.Element;
 
 export declare namespace Separator {
     var displayName: string;
@@ -468,7 +949,7 @@ export declare type SeparatorProps = BaseSeparatorAttributes & {
      * 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` attribute.
+     * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes.
      */
     id?: string | number | undefined;
     /**
@@ -487,6 +968,36 @@ export declare type SeparatorProps = BaseSeparatorAttributes & {
 
 export declare type SizeUnit = "px" | "%" | "em" | "rem" | "vh" | "vw";
 
+/**
+ * Saves and restores Grid 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 useDefaultGridLayout({ id, onlySaveAfterUserInteractions, storage }: {
+    /**
+     * Uniquely identifies a specific grid/layout.
+     */
+    id: string;
+    /**
+     * 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;
+    /**
+     * Storage implementation; supports localStorage, sessionStorage, and custom implementations
+     * Refer to documentation site for example integrations.
+     */
+    storage?: LayoutStorage;
+}): {
+    /**
+     * Pass this value to `Grid` as the `defaultLayout` prop.
+     */
+    defaultLayout: Partial<GridLayout> | undefined;
+    /**
+     * Attach this callback on the `Grid` as the `onLayoutChanged` prop.
+     */
+    onLayoutChanged: (layout: GridLayout, meta: LayoutChangedMeta) => void;
+};
+
 /**
  * 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.
@@ -545,6 +1056,18 @@ export declare function useDefaultLayout({ debounceSaveMs, onlySaveAfterUserInte
     onLayoutChanged: (layout: Layout, meta: LayoutChangedMeta) => void;
 };
 
+/**
+ * Convenience hook to return a properly typed ref callback for the Grid component.
+ *
+ * Use this hook when you need to share the ref with another component or hook.
+ */
+export declare function useGridCallbackRef(): [GridImperativeHandle | null, Dispatch<SetStateAction<GridImperativeHandle | null>>];
+
+/**
+ * Convenience hook to return a properly typed ref for the Grid component.
+ */
+export declare function useGridRef(): RefObject<GridImperativeHandle | null>;
+
 /**
  * Convenience hook to return a properly typed ref callback for the Group component.
  *