react-resizable-panels 4.18.0 → 4.19.0

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.
@@ -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;
@@ -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;
@@ -1367,12 +1386,14 @@ export declare type TabCloseButtonProps = ButtonHTMLAttributes<HTMLButtonElement
1367
1386
 
1368
1387
  /**
1369
1388
  * Edge (or center) of a tabset's content area.
1389
+ *
1390
+ * ℹ️ Edges are sides of the screen, so in a right-to-left layout (e.g. within `dir="rtl"`), "left" is after the tabset in its split's `children`.
1370
1391
  */
1371
1392
  export declare type TabDropRegion = "bottom" | "center" | "left" | "right" | "top";
1372
1393
 
1373
1394
  /**
1374
1395
  * Where a dragged tab can be dropped:
1375
- * - At an `index` within a tabset's tab list
1396
+ * - At an `index` within a tabset's tab list (in the order of its `tabs`, which run from right to left in a right-to-left layout)
1376
1397
  * - Within a `region` of a tabset's content area; edges split the tabset, and the center adds the tab to it
1377
1398
  */
1378
1399
  export declare type TabDropTarget = {
@@ -1608,6 +1629,47 @@ export declare type TabsetNodeInput<TabData = unknown, TabsetData = unknown> = O
1608
1629
  id?: string | undefined;
1609
1630
  };
1610
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
+
1611
1673
  /**
1612
1674
  * Saves and restores Grid layouts between page loads.
1613
1675
  * It can be configured to store values using `localStorage`, `sessionStorage`, cookies, or any other persistence layer that makes sense for your application.
@@ -1852,6 +1914,9 @@ export declare type WorkspaceChangedMeta = {
1852
1914
  * ℹ️ A resize that collapses or expands tabsets is reported as `"collapse"` or `"expand"` (as `"expand"` if it does both);
1853
1915
  * dropping tabs into a collapsed tabset expands it, but is reported as `"move"`.
1854
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
+ *
1855
1920
  * ⚠️ New reasons may be added in later versions, so code that switches on this value should handle unrecognized values.
1856
1921
  */
1857
1922
  reason: WorkspaceChangeReason;
@@ -1862,7 +1927,7 @@ export declare type WorkspaceChangedMeta = {
1862
1927
  *
1863
1928
  * ⚠️ New reasons may be added in later versions.
1864
1929
  */
1865
- 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";
1866
1931
 
1867
1932
  /**
1868
1933
  * CSS class names for the elements a Workspace renders (see the Workspace's `classNames` prop).
@@ -1885,7 +1950,7 @@ export declare type WorkspaceClassNames = {
1885
1950
  toolbar?: string | undefined;
1886
1951
  };
1887
1952
 
1888
- 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;
1889
1954
 
1890
1955
  /**
1891
1956
  * Imperative Workspace API.
@@ -1951,6 +2016,8 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
1951
2016
  *
1952
2017
  * ℹ️ The space is measured along the tab list: its width, or its height if its tabs are placed on the left or right
1953
2018
  * (or the tabset is collapsed to a vertical strip).
2019
+ * If the tab list can't shrink any further (e.g. it's 0px wide, beside a toolbar that doesn't shrink), the amount the header's content
2020
+ * overflows the header is subtracted too, so it's still how much space a toolbar needs to free up.
1954
2021
  *
1955
2022
  * ℹ️ The tab list's `--tab-list-free-space` custom property has the same value (e.g. "120px").
1956
2023
  *
@@ -1969,11 +2036,14 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
1969
2036
  maximizeTabset: (tabsetId: string) => void;
1970
2037
  /**
1971
2038
  * Move a tab to a position within a tabset's tab list, or to a region of a tabset's content area.
2039
+ *
2040
+ * ℹ️ The `"left"` and `"right"` regions are sides of the screen (so they're mirrored in right-to-left layouts).
1972
2041
  */
1973
2042
  moveTab: (tabId: string, target: TabDropTarget) => void;
1974
2043
  /**
1975
2044
  * Move a tabset beside another tabset (by dropping it onto a region at the edge of that tabset's content area),
1976
2045
  * or move its tabs into another tabset (at an `index` within its tab list, or onto the `"center"` of its content area).
2046
+ * The `"left"` and `"right"` regions are sides of the screen (so they're mirrored in right-to-left layouts).
1977
2047
  *
1978
2048
  * ℹ️ When its tabs are moved, the emptied tabset is removed (unless it has the `keepWhenEmpty` flag).
1979
2049
  */
@@ -2091,6 +2161,10 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
2091
2161
  * Elements within a collapsed tabset have a `data-tabset-collapsed` attribute.
2092
2162
  * Elements within a tabset also have a `data-tab-placement` attribute (see `tabPlacement`).
2093
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
+ *
2094
2168
  * ℹ️ Like the render props, this object is part of what tabsets re-render for;
2095
2169
  * in large workspaces, define it outside of the component (or memoize it) rather than inline.
2096
2170
  */
@@ -2110,6 +2184,14 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
2110
2184
  * ℹ️ This prop overrides the `disableClose` and `disableDrag` flags of individual tabs.
2111
2185
  */
2112
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;
2113
2195
  /**
2114
2196
  * Prevents tabs (and tabsets) from being dropped onto some (or all) targets.
2115
2197
  *
@@ -2120,6 +2202,26 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
2120
2202
  * so restrictions on where tabs can be dropped apply to dragged tabsets too.
2121
2203
  */
2122
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;
2123
2225
  /**
2124
2226
  * Ref attached to the root `HTMLDivElement`.
2125
2227
  */
@@ -2155,18 +2257,37 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
2155
2257
  * This method is recommended when saving models to some storage api.
2156
2258
  */
2157
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;
2158
2276
  /**
2159
2277
  * Content of the element that follows the pointer while a tab is being dragged.
2160
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`).
2161
2281
  */
2162
- renderDragPreview?: ((tab: TabNode<TabData>) => ReactNode) | undefined;
2282
+ renderDragPreview?: ((tab: TabNode<TabData>, state: DragPreviewState) => ReactNode) | undefined;
2163
2283
  /**
2164
2284
  * Content of the element that follows the pointer while a whole tabset is being dragged.
2165
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.
2166
2286
  *
2167
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`).
2168
2289
  */
2169
- renderTabsetDragPreview?: ((tabset: TabsetNode<TabData, TabsetData>) => ReactNode) | undefined;
2290
+ renderTabsetDragPreview?: ((tabset: TabsetNode<TabData, TabsetData>, state: DragPreviewState) => ReactNode) | undefined;
2170
2291
  /**
2171
2292
  * Content shown in the panels of a tabset that has no tabs (e.g. "Drag a tab here"):
2172
2293
  * the root tabset of an empty workspace, or a tabset with the `keepWhenEmpty` flag.
@@ -2260,6 +2381,10 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
2260
2381
  *
2261
2382
  * ℹ️ Elements within a tabset have a `data-tab-placement` attribute, which can be used for styling (e.g. rotating tabs on the left or right).
2262
2383
  *
2384
+ * ℹ️ "left" and "right" are the start and end of the tabset (its header is rendered before or after its content),
2385
+ * so in a right-to-left layout (e.g. within `dir="rtl"`) tabs placed on the "left" are on the right;
2386
+ * styles for them should use logical properties (e.g. `border-inline-end` rather than `border-right`).
2387
+ *
2263
2388
  * ℹ️ Tabsets can override this with the `tabPlacement` field of their model node.
2264
2389
  *
2265
2390
  * @default "top"