react-resizable-panels 4.18.1 → 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;
@@ -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
  */
@@ -2162,18 +2257,37 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
2162
2257
  * This method is recommended when saving models to some storage api.
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.