react-resizable-panels 4.18.1 → 4.19.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -90,7 +90,7 @@ export declare type CellProps = HTMLAttributes<HTMLDivElement> & {
90
90
  * Uniquely identifies this cell within the parent grid.
91
91
  * Falls back to `useId` when not provided.
92
92
  *
93
- * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes; (an explicit `data-testid` prop will take precedence).
93
+ * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes (an explicit `data-testid` prop will take precedence).
94
94
  */
95
95
  id?: string | number | undefined;
96
96
  /**
@@ -119,6 +119,12 @@ export declare type CellProps = HTMLAttributes<HTMLDivElement> & {
119
119
  */
120
120
  export declare type DisableDropArgs<TabData = unknown, TabsetData = unknown> = {
121
121
  model: WorkspaceModel<TabData, TabsetData>;
122
+ /**
123
+ * Where the tab (or tabset) is dragged from:
124
+ * - `"local"`: this workspace
125
+ * - `"external"`: another workspace with the same `dragGroup` (e.g. in another window)
126
+ */
127
+ source: "external" | "local";
122
128
  /**
123
129
  * The tab being dropped.
124
130
  *
@@ -132,6 +138,19 @@ export declare type DisableDropArgs<TabData = unknown, TabsetData = unknown> = {
132
138
  target: TabDropTarget;
133
139
  };
134
140
 
141
+ /**
142
+ * State passed to the Workspace's `renderDragPreview` and `renderTabsetDragPreview` props.
143
+ */
144
+ export declare type DragPreviewState = {
145
+ /**
146
+ * `true` while the pointer is outside of the window and releasing it would tear off the tab (or tabset);
147
+ * only when the Workspace has an `onTearOff` prop.
148
+ *
149
+ * ℹ️ This is never set for mouse drags when the Workspace has a `dragGroup` prop, since the pointer can't be followed outside of the window then.
150
+ */
151
+ isTearOff: boolean;
152
+ };
153
+
135
154
  /**
136
155
  * A Grid arranges resizable Cells in two dimensions.
137
156
  * Columns can be resized horizontally and rows can be resized vertically;
@@ -167,7 +186,7 @@ declare function GridComponent({ children, className, columns, defaultLayout, di
167
186
  /**
168
187
  * Imperative Grid API.
169
188
  *
170
- * ℹ️ The `useGridRef` and `useGridCallbackRef` hooks are exported for convenience use in TypeScript projects.
189
+ * ℹ️ The `useGridRef` and `useGridCallbackRef` hooks are exported for convenience in TypeScript projects.
171
190
  */
172
191
  export declare interface GridImperativeHandle {
173
192
  /**
@@ -260,7 +279,7 @@ export declare type GridLayout = {
260
279
  * ```
261
280
  *
262
281
  * A gridline should not be rendered alongside of a Cell that spans across its boundary
263
- * (this includes disabled gridlines; an error will be logged to the console);
282
+ * (this includes disabled gridlines; in development builds, an error will be logged to the console);
264
283
  * render multiple gridlines along the same boundary instead (e.g. before and after the spanning Cell).
265
284
  *
266
285
  * ℹ️ Once a boundary contains a gridline, it can only be resized using gridlines;
@@ -377,14 +396,14 @@ export declare type GridProps = HTMLAttributes<HTMLDivElement> & {
377
396
  * - `getTrackByIndex(axis: "column" | "row", index: number): GridTrackImperativeHandle`
378
397
  * - `setLayout(layout: Partial<GridLayout>): GridLayout`
379
398
  *
380
- * ℹ️ The `useGridRef` and `useGridCallbackRef` hooks are exported for convenience use in TypeScript projects.
399
+ * ℹ️ The `useGridRef` and `useGridCallbackRef` hooks are exported for convenience in TypeScript projects.
381
400
  */
382
401
  gridRef?: Ref<GridImperativeHandle | null> | undefined;
383
402
  /**
384
403
  * Uniquely identifies this grid within an application.
385
404
  * Falls back to `useId` when not provided.
386
405
  *
387
- * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes; (an explicit `data-testid` prop will take precedence).
406
+ * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes (an explicit `data-testid` prop will take precedence).
388
407
  */
389
408
  id?: string | number | undefined;
390
409
  /**
@@ -397,8 +416,8 @@ export declare type GridProps = HTMLAttributes<HTMLDivElement> & {
397
416
  /**
398
417
  * Called after the Grid's layout has been changed.
399
418
  *
400
- * ℹ️ For layout changes caused by pointer events, this method is not called until the pointer has been released.
401
- * This method is recommended when saving layouts to some storage api.
419
+ * ℹ️ For layout changes caused by pointer events, this callback is not called until the pointer has been released.
420
+ * This callback is recommended for saving layouts to storage.
402
421
  */
403
422
  onLayoutChanged?: ((layout: GridLayout, meta: LayoutChangedMeta<GridLayout>) => void) | undefined;
404
423
  /**
@@ -518,7 +537,7 @@ declare function GroupComponent({ children, className, defaultLayout, disableCur
518
537
  /**
519
538
  * Imperative Group API.
520
539
  *
521
- * ℹ️ The `useGroupRef` and `useGroupCallbackRef` hooks are exported for convenience use in TypeScript projects.
540
+ * ℹ️ The `useGroupRef` and `useGroupCallbackRef` hooks are exported for convenience in TypeScript projects.
522
541
  */
523
542
  export declare interface GroupImperativeHandle {
524
543
  /**
@@ -576,14 +595,14 @@ export declare type GroupProps = HTMLAttributes<HTMLDivElement> & {
576
595
  * - `getLayout(): Layout`
577
596
  * - `setLayout(layout: Layout): Layout`
578
597
  *
579
- * ℹ️ The `useGroupRef` and `useGroupCallbackRef` hooks are exported for convenience use in TypeScript projects.
598
+ * ℹ️ The `useGroupRef` and `useGroupCallbackRef` hooks are exported for convenience in TypeScript projects.
580
599
  */
581
600
  groupRef?: Ref<GroupImperativeHandle | null> | undefined;
582
601
  /**
583
602
  * Uniquely identifies this group within an application.
584
603
  * Falls back to `useId` when not provided.
585
604
  *
586
- * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes; (an explicit `data-testid` prop will take precedence).
605
+ * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes (an explicit `data-testid` prop will take precedence).
587
606
  */
588
607
  id?: string | number | undefined;
589
608
  /**
@@ -596,8 +615,8 @@ export declare type GroupProps = HTMLAttributes<HTMLDivElement> & {
596
615
  /**
597
616
  * Called after the Group's layout has been changed.
598
617
  *
599
- * ℹ️ For layout changes caused by pointer events, this method is not called until the pointer has been released.
600
- * This method is recommended when saving layouts to some storage api.
618
+ * ℹ️ For layout changes caused by pointer events, this callback is not called until the pointer has been released.
619
+ * This callback is recommended for saving layouts to storage.
601
620
  *
602
621
  * ℹ️ The second argument contains meta information about the layout change.
603
622
  * The `isUserInteraction` attribute signals whether the resize was caused by direct user input.
@@ -786,7 +805,7 @@ declare type PanelConstraintProps = Pick<PanelProps, "collapsedSize" | "collapse
786
805
  /**
787
806
  * Imperative Panel API
788
807
  *
789
- * ℹ️ The `usePanelRef` and `usePanelCallbackRef` hooks are exported for convenience use in TypeScript projects.
808
+ * ℹ️ The `usePanelRef` and `usePanelCallbackRef` hooks are exported for convenience in TypeScript projects.
790
809
  */
791
810
  export declare interface PanelImperativeHandle {
792
811
  /**
@@ -911,7 +930,7 @@ export declare type PanelProps = BasePanelAttributes & {
911
930
  *
912
931
  * ℹ️ This prop is used to associate persisted group layouts with the original panel.
913
932
  *
914
- * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes; (an explicit `data-testid` prop will take precedence).
933
+ * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes (an explicit `data-testid` prop will take precedence).
915
934
  */
916
935
  id?: string | number | undefined;
917
936
  /**
@@ -952,7 +971,7 @@ export declare type PanelProps = BasePanelAttributes & {
952
971
  * - `isCollapsed(): boolean`
953
972
  * - `resize(size: number | string): void`
954
973
  *
955
- * ℹ️ The `usePanelRef` and `usePanelCallbackRef` hooks are exported for convenience use in TypeScript projects.
974
+ * ℹ️ The `usePanelRef` and `usePanelCallbackRef` hooks are exported for convenience in TypeScript projects.
956
975
  */
957
976
  panelRef?: Ref<PanelImperativeHandle | null> | undefined;
958
977
  /**
@@ -1135,7 +1154,7 @@ export declare type ParentTabsetState = {
1135
1154
  * The user cannot drag the tabset as a whole, because:
1136
1155
  * - It has the `disableDrag` flag, or one of its tabs does
1137
1156
  * - The Workspace has the `disabled` prop
1138
- * - It's the only tabset in the workspace (see `isRoot`)
1157
+ * - It's the only tabset in the workspace (see `isRoot`), and can't be dragged to another workspace (see the Workspace's `dragGroup` prop; tabsets with the `keepWhenEmpty` flag can't be)
1139
1158
  * - A tabset is maximized
1140
1159
  */
1141
1160
  isDragDisabled: boolean;
@@ -1266,7 +1285,7 @@ export declare type SeparatorProps = BaseSeparatorAttributes & {
1266
1285
  * Uniquely identifies the separator within the parent group.
1267
1286
  * Falls back to `useId` when not provided.
1268
1287
  *
1269
- * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes; (an explicit `data-testid` prop will take precedence).
1288
+ * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes (an explicit `data-testid` prop will take precedence).
1270
1289
  */
1271
1290
  id?: string | number | undefined;
1272
1291
  /**
@@ -1610,6 +1629,47 @@ export declare type TabsetNodeInput<TabData = unknown, TabsetData = unknown> = O
1610
1629
  id?: string | undefined;
1611
1630
  };
1612
1631
 
1632
+ /**
1633
+ * Arguments passed to the Workspace's `onTearOff` prop: the tab (or whole tabset) dropped outside of the window,
1634
+ * and a model for showing it in a new workspace (e.g. in a popup window).
1635
+ */
1636
+ export declare type TearOffArgs<TabData = unknown, TabsetData = unknown> = ({
1637
+ /**
1638
+ * The tab dropped outside of the window.
1639
+ */
1640
+ tab: TabNode<TabData>;
1641
+ type: "tab";
1642
+ } | {
1643
+ /**
1644
+ * The tabset dropped outside of the window.
1645
+ */
1646
+ tabset: TabsetNode<TabData, TabsetData>;
1647
+ type: "tabset";
1648
+ }) & {
1649
+ /**
1650
+ * Height (in pixels) of the tabset the tab was dragged from (or of the dragged tabset), e.g. to size a popup window.
1651
+ */
1652
+ height: number;
1653
+ /**
1654
+ * A model containing only the torn off tab (in a new tabset) or tabset, e.g. the `defaultModel` of a workspace in a popup window.
1655
+ */
1656
+ model: WorkspaceModel<TabData, TabsetData>;
1657
+ /**
1658
+ * Horizontal position (in screen coordinates) where the pointer was released, e.g. to position a popup window.
1659
+ *
1660
+ * ℹ️ Approximate when dragging between workspaces (see the `dragGroup` prop), since some browsers report the wrong position when such drags end.
1661
+ */
1662
+ screenX: number;
1663
+ /**
1664
+ * Vertical position (in screen coordinates) where the pointer was released, e.g. to position a popup window.
1665
+ */
1666
+ screenY: number;
1667
+ /**
1668
+ * Width (in pixels) of the tabset the tab was dragged from (or of the dragged tabset), e.g. to size a popup window.
1669
+ */
1670
+ width: number;
1671
+ };
1672
+
1613
1673
  /**
1614
1674
  * Saves and restores Grid layouts between page loads.
1615
1675
  * It can be configured to store values using `localStorage`, `sessionStorage`, cookies, or any other persistence layer that makes sense for your application.
@@ -1854,6 +1914,9 @@ export declare type WorkspaceChangedMeta = {
1854
1914
  * ℹ️ A resize that collapses or expands tabsets is reported as `"collapse"` or `"expand"` (as `"expand"` if it does both);
1855
1915
  * dropping tabs into a collapsed tabset expands it, but is reported as `"move"`.
1856
1916
  *
1917
+ * ℹ️ A tab (or tabset) dragged to another workspace (see the `dragGroup` prop) is reported as `"transfer"` by both workspaces:
1918
+ * the one it was dropped into (which added it) and the one it was dragged from (which removed it).
1919
+ *
1857
1920
  * ⚠️ New reasons may be added in later versions, so code that switches on this value should handle unrecognized values.
1858
1921
  */
1859
1922
  reason: WorkspaceChangeReason;
@@ -1864,7 +1927,7 @@ export declare type WorkspaceChangedMeta = {
1864
1927
  *
1865
1928
  * ⚠️ New reasons may be added in later versions.
1866
1929
  */
1867
- export declare type WorkspaceChangeReason = "add" | "close" | "collapse" | "expand" | "maximize" | "move" | "resize" | "restore" | "select" | "set-model" | "update";
1930
+ export declare type WorkspaceChangeReason = "add" | "close" | "collapse" | "expand" | "maximize" | "move" | "resize" | "restore" | "select" | "set-model" | "tear-off" | "transfer" | "update";
1868
1931
 
1869
1932
  /**
1870
1933
  * CSS class names for the elements a Workspace renders (see the Workspace's `classNames` prop).
@@ -1887,7 +1950,7 @@ export declare type WorkspaceClassNames = {
1887
1950
  toolbar?: string | undefined;
1888
1951
  };
1889
1952
 
1890
- declare function WorkspaceComponent<TabData = unknown, TabsetData = unknown>({ className, classNames, defaultModel, disabled, disableDrop, elementRef: elementRefProp, hiddenTabBehavior, id: idProp, onModelChanged, renderDragPreview, renderEmptyTabset, renderSeparator, renderTab, renderTabContent, renderTabsetDragPreview, renderTabsetToolbar, resizePreviewMode, serverRenderTabContent, style, styles, tabPlacement, tabRemovalSelectionBehavior, tabsetMinHeight, tabsetMinWidth, workspaceRef, ...rest }: WorkspaceProps<TabData, TabsetData>): JSX.Element;
1953
+ declare function WorkspaceComponent<TabData = unknown, TabsetData = unknown>({ className, classNames, defaultModel, disabled, disableDragBetweenApps, disableDrop, dragGroup, elementRef: elementRefProp, hiddenTabBehavior, id: idProp, onModelChanged, onTearOff, renderDragPreview, renderEmptyTabset, renderSeparator, renderTab, renderTabContent, renderTabsetDragPreview, renderTabsetToolbar, resizePreviewMode, serverRenderTabContent, style, styles, tabPlacement, tabRemovalSelectionBehavior, tabsetMinHeight, tabsetMinWidth, workspaceRef, ...rest }: WorkspaceProps<TabData, TabsetData>): JSX.Element;
1891
1954
 
1892
1955
  /**
1893
1956
  * Imperative Workspace API.
@@ -2098,6 +2161,10 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
2098
2161
  * Elements within a collapsed tabset have a `data-tabset-collapsed` attribute.
2099
2162
  * Elements within a tabset also have a `data-tab-placement` attribute (see `tabPlacement`).
2100
2163
  *
2164
+ * ℹ️ The drop indicator is the same element for the whole drag (rendered within the workspace's root element),
2165
+ * so it can be animated between regions and tabsets (e.g. `transition: inset 250ms`).
2166
+ * Its `data-region` attribute is the region it covers; while a tab isn't over any tabset's panels, it has none and isn't shown (`opacity: 0`).
2167
+ *
2101
2168
  * ℹ️ Like the render props, this object is part of what tabsets re-render for;
2102
2169
  * in large workspaces, define it outside of the component (or memoize it) rather than inline.
2103
2170
  */
@@ -2117,6 +2184,14 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
2117
2184
  * ℹ️ This prop overrides the `disableClose` and `disableDrag` flags of individual tabs.
2118
2185
  */
2119
2186
  disabled?: boolean | undefined;
2187
+ /**
2188
+ * Keeps drags between workspaces (see `dragGroup`) within this copy of the application:
2189
+ * tabs dragged from this workspace can't be dropped into other copies of the application (e.g. the application loaded in another browser window or tab), and tabs dragged from other copies can't be dropped into this workspace.
2190
+ * Workspaces in popout windows rendered by this copy of the application (with portals) are still part of the group.
2191
+ *
2192
+ * Defaults to `false`, so that workspaces with the same `dragGroup` in other copies of the application from the same origin can exchange tabs.
2193
+ */
2194
+ disableDragBetweenApps?: boolean | undefined;
2120
2195
  /**
2121
2196
  * Prevents tabs (and tabsets) from being dropped onto some (or all) targets.
2122
2197
  *
@@ -2127,6 +2202,26 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
2127
2202
  * so restrictions on where tabs can be dropped apply to dragged tabsets too.
2128
2203
  */
2129
2204
  disableDrop?: boolean | ((args: DisableDropArgs<TabData, TabsetData>) => boolean) | undefined;
2205
+ /**
2206
+ * Lets tabs (and tabsets) be dragged between workspaces with the same `dragGroup`,
2207
+ * including workspaces in popout windows (opened by the application and rendered into with a portal)
2208
+ * and in other copies of the application from the same origin, e.g. the application loaded in another browser window or tab (see `disableDragBetweenApps`).
2209
+ * Dropping one into another workspace moves it there, keeping its id and data;
2210
+ * both workspaces report the change to `onModelChanged` with the `"transfer"` reason.
2211
+ *
2212
+ * Mouse drags use the browser's drag and drop when this prop is set, since pointer events can't follow the pointer into another window.
2213
+ * Touch drags still use pointer events, so they can't leave the window.
2214
+ *
2215
+ * ℹ️ Tab ids must be unique within the group; a tab can't be dropped into a workspace that already has a tab with its id (and a tabset with the `keepWhenEmpty` flag can't be dragged to another workspace).
2216
+ * A tab dragged to another workspace is rendered by that workspace, so its content is mounted again.
2217
+ *
2218
+ * ⚠️ A tab dragged to another copy of the application is sent there with the structured clone algorithm (like `postMessage`), so its data must be cloneable (e.g. no functions);
2219
+ * tabs whose data can't be cloned (and tabsets containing them) can only be dragged within their copy of the application.
2220
+ * Copies loaded at different times may be running different versions of the application, so the other copy may need to handle tab data it doesn't recognize.
2221
+ *
2222
+ * ⚠️ Tabs (and tabsets) can still be torn off (see `onTearOff`), but some browsers (e.g. Safari) block popup windows opened at the end of a drag that uses the browser's drag and drop.
2223
+ */
2224
+ dragGroup?: string | undefined;
2130
2225
  /**
2131
2226
  * Ref attached to the root `HTMLDivElement`.
2132
2227
  */
@@ -2152,28 +2247,47 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
2152
2247
  * Uniquely identifies this workspace within an application.
2153
2248
  * Falls back to `useId` when not provided.
2154
2249
  *
2155
- * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes; (an explicit `data-testid` prop will take precedence).
2250
+ * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes (an explicit `data-testid` prop will take precedence).
2156
2251
  */
2157
2252
  id?: string | number | undefined;
2158
2253
  /**
2159
2254
  * Called after the model has changed (e.g. a tab was moved, selected, or closed, or a tabset was resized).
2160
2255
  *
2161
- * ℹ️ For changes caused by pointer events, this method is not called until the pointer has been released.
2162
- * This method is recommended when saving models to some storage api.
2256
+ * ℹ️ For changes caused by pointer events, this callback is not called until the pointer has been released.
2257
+ * This callback is recommended for saving models to storage.
2163
2258
  */
2164
2259
  onModelChanged?: (model: WorkspaceModel<TabData, TabsetData>, meta: WorkspaceChangedMeta) => void;
2260
+ /**
2261
+ * Called when a tab (or a whole tabset) is dropped outside of the window, e.g. to open it in a popup window.
2262
+ * Return `true` to accept it, which removes it from this workspace (reported to `onModelChanged` with the `"tear-off"` reason);
2263
+ * otherwise nothing changes.
2264
+ *
2265
+ * Tabs and tabsets can only be torn off if they could be dragged, and tabsets with the `keepWhenEmpty` flag can't be torn off.
2266
+ * Without this prop, dropping a tab outside of the window does nothing.
2267
+ *
2268
+ * ⚠️ The Workspace can't tell whether the application showed the tab, so check whether `window.open` returned `null` (because the popup was blocked)
2269
+ * and return `false` then to keep the tab; returning `true` removes it even if nothing shows it.
2270
+ *
2271
+ * ℹ️ This is called while the release of the pointer is being handled (which browsers treat as user input), so a popup can be opened from it.
2272
+ * With the `dragGroup` prop, a tab is torn off when it's dropped outside of every window in the group; the end of those drags isn't treated as user input,
2273
+ * so browsers block popups opened then unless the drag started a few seconds earlier at most (and Safari blocks them always).
2274
+ */
2275
+ onTearOff?: ((args: TearOffArgs<TabData, TabsetData>) => boolean) | undefined;
2165
2276
  /**
2166
2277
  * Content of the element that follows the pointer while a tab is being dragged.
2167
2278
  * Defaults to the tab's title (or id).
2279
+ *
2280
+ * ℹ️ The element has a `data-tear-off` attribute while releasing the pointer would tear off the tab (see `onTearOff`).
2168
2281
  */
2169
- renderDragPreview?: ((tab: TabNode<TabData>) => ReactNode) | undefined;
2282
+ renderDragPreview?: ((tab: TabNode<TabData>, state: DragPreviewState) => ReactNode) | undefined;
2170
2283
  /**
2171
2284
  * Content of the element that follows the pointer while a whole tabset is being dragged.
2172
2285
  * Defaults to the title (or id) of its selected tab followed by the number of other tabs being dragged (e.g. "One (+2)"), or the selected tab's `renderDragPreview` when that prop is set, or the tabset's id if it has no tabs.
2173
2286
  *
2174
2287
  * ℹ️ The element has a `data-drag-type` attribute: `"tabset"` while a tabset is dragged, and `"tab"` while a tab is.
2288
+ * It also has a `data-tear-off` attribute while releasing the pointer would tear off the tabset (see `onTearOff`).
2175
2289
  */
2176
- renderTabsetDragPreview?: ((tabset: TabsetNode<TabData, TabsetData>) => ReactNode) | undefined;
2290
+ renderTabsetDragPreview?: ((tabset: TabsetNode<TabData, TabsetData>, state: DragPreviewState) => ReactNode) | undefined;
2177
2291
  /**
2178
2292
  * Content shown in the panels of a tabset that has no tabs (e.g. "Drag a tab here"):
2179
2293
  * the root tabset of an empty workspace, or a tabset with the `keepWhenEmpty` flag.
@@ -2311,7 +2425,7 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
2311
2425
  /**
2312
2426
  * Exposes the imperative API (see `WorkspaceImperativeHandle`).
2313
2427
  *
2314
- * ℹ️ The `useWorkspaceRef` and `useWorkspaceCallbackRef` hooks are exported for convenience use in TypeScript projects.
2428
+ * ℹ️ The `useWorkspaceRef` and `useWorkspaceCallbackRef` hooks are exported for convenience in TypeScript projects.
2315
2429
  */
2316
2430
  workspaceRef?: Ref<WorkspaceImperativeHandle<TabData, TabsetData> | null> | undefined;
2317
2431
  };