react-resizable-panels 4.21.0 → 4.22.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.
- package/README.md +1007 -434
- package/dist/react-resizable-panels.cjs +2 -1
- package/dist/react-resizable-panels.cjs.map +1 -1
- package/dist/react-resizable-panels.d.ts +357 -9
- package/dist/react-resizable-panels.js +4781 -4027
- package/dist/react-resizable-panels.js.map +1 -1
- package/package.json +2 -2
|
@@ -3,12 +3,39 @@ import { CSSProperties } from 'react';
|
|
|
3
3
|
import { Dispatch } from 'react';
|
|
4
4
|
import { HTMLAttributes } from 'react';
|
|
5
5
|
import { JSX } from 'react/jsx-runtime';
|
|
6
|
+
import { PointerEvent as PointerEvent_2 } from 'react';
|
|
6
7
|
import { ReactNode } from 'react';
|
|
7
8
|
import { Ref } from 'react';
|
|
8
9
|
import { RefCallback } from 'react';
|
|
9
10
|
import { RefObject } from 'react';
|
|
10
11
|
import { SetStateAction } from 'react';
|
|
11
12
|
|
|
13
|
+
/**
|
|
14
|
+
* Accepts drags that use the browser's drag and drop from outside of the workspace (e.g. elements with the `draggable` attribute, or files),
|
|
15
|
+
* creating a tab where they're dropped (see the Workspace's `acceptExternalDrop` prop).
|
|
16
|
+
*/
|
|
17
|
+
export declare type AcceptExternalDrop<TabData = unknown> = {
|
|
18
|
+
/**
|
|
19
|
+
* Creates the tab to add, when a drag is dropped.
|
|
20
|
+
* Returning `null` (or `undefined`) rejects the drop.
|
|
21
|
+
*
|
|
22
|
+
* ℹ️ The drag's data can be read here (e.g. with `dataTransfer.getData`), since browsers only let it be read when it's dropped.
|
|
23
|
+
*
|
|
24
|
+
* ℹ️ The tab can't be added to a workspace that already has a node with its id, and is checked by `disableDrop` (with the `"new"` source) before it's added.
|
|
25
|
+
*
|
|
26
|
+
* @param dataTransfer The drop event's `DataTransfer`
|
|
27
|
+
* @param target Where the drag was dropped
|
|
28
|
+
*/
|
|
29
|
+
createTab: (dataTransfer: DataTransfer, target: TabDropTarget) => TabNode<TabData> | null | undefined;
|
|
30
|
+
/**
|
|
31
|
+
* Drag data types (e.g. `"application/x-my-widget"`, or `"Files"` for files) that are accepted; a drag is accepted if it has any of them.
|
|
32
|
+
*
|
|
33
|
+
* ℹ️ While a drag is in progress, browsers only let its types be read (not its data), so they decide where the drop indicator is shown.
|
|
34
|
+
* Data types are compared case-insensitively, since browsers lowercase them.
|
|
35
|
+
*/
|
|
36
|
+
types: string[];
|
|
37
|
+
};
|
|
38
|
+
|
|
12
39
|
declare type BaseGridlineProps = {
|
|
13
40
|
/**
|
|
14
41
|
* Gridline contents (e.g. a drag handle icon).
|
|
@@ -118,13 +145,20 @@ export declare type CellProps = HTMLAttributes<HTMLDivElement> & {
|
|
|
118
145
|
* and the target is rejected if any call returns `true`.
|
|
119
146
|
*/
|
|
120
147
|
export declare type DisableDropArgs<TabData = unknown, TabsetData = unknown> = {
|
|
148
|
+
/**
|
|
149
|
+
* `true` if a copy would be dropped (rather than the tab or tabset itself), since the copy modifier key is held; see the `copyTab` and `copyTabset` props.
|
|
150
|
+
*
|
|
151
|
+
* ℹ️ The tab (or tabset) passed is the one being dragged, since the copy is only made when it's dropped.
|
|
152
|
+
*/
|
|
153
|
+
isCopy: boolean;
|
|
121
154
|
model: WorkspaceModel<TabData, TabsetData>;
|
|
122
155
|
/**
|
|
123
156
|
* Where the tab (or tabset) is dragged from:
|
|
124
157
|
* - `"local"`: this workspace
|
|
125
158
|
* - `"external"`: another workspace with the same `dragGroup` (e.g. in another window)
|
|
159
|
+
* - `"new"`: outside of any workspace, for a tab that's created when it's dropped (see the `startExternalDrag` method and the `acceptExternalDrop` prop)
|
|
126
160
|
*/
|
|
127
|
-
source: "external" | "local";
|
|
161
|
+
source: "external" | "local" | "new";
|
|
128
162
|
/**
|
|
129
163
|
* The tab being dropped.
|
|
130
164
|
*
|
|
@@ -142,15 +176,45 @@ export declare type DisableDropArgs<TabData = unknown, TabsetData = unknown> = {
|
|
|
142
176
|
* State passed to the Workspace's `renderDragPreview` and `renderTabsetDragPreview` props.
|
|
143
177
|
*/
|
|
144
178
|
export declare type DragPreviewState = {
|
|
179
|
+
/**
|
|
180
|
+
* `true` while dropping would add a copy of the tab (or tabset), rather than moving it, since the copy modifier key is held; see the `copyTab` and `copyTabset` props.
|
|
181
|
+
*/
|
|
182
|
+
isCopy: boolean;
|
|
145
183
|
/**
|
|
146
184
|
* `true` while the pointer is outside of the window and releasing it would tear off the tab (or tabset);
|
|
147
185
|
* only when the Workspace has an `onTearOff` prop.
|
|
148
186
|
*
|
|
149
187
|
* ℹ️ 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.
|
|
188
|
+
*
|
|
189
|
+
* @deprecated Along with the Workspace's `onTearOff` prop; this will be removed in the next major version.
|
|
150
190
|
*/
|
|
151
191
|
isTearOff: boolean;
|
|
152
192
|
};
|
|
153
193
|
|
|
194
|
+
/**
|
|
195
|
+
* Options for the imperative `startExternalDrag` method.
|
|
196
|
+
*/
|
|
197
|
+
export declare type ExternalDragOptions<TabData = unknown> = {
|
|
198
|
+
/**
|
|
199
|
+
* Content of the element that follows the pointer while dragging.
|
|
200
|
+
* Defaults to what the Workspace's `renderDragPreview` prop renders for the tab (or the tab's title).
|
|
201
|
+
*/
|
|
202
|
+
preview?: ReactNode | undefined;
|
|
203
|
+
/**
|
|
204
|
+
* The tab to add where it's dropped; it's only added if the drop is accepted.
|
|
205
|
+
*
|
|
206
|
+
* ℹ️ Like tabs dragged in from other workspaces, it can't be dropped into a workspace that already has a node with its id.
|
|
207
|
+
*/
|
|
208
|
+
tab: TabNode<TabData>;
|
|
209
|
+
};
|
|
210
|
+
|
|
211
|
+
/**
|
|
212
|
+
* The result of the imperative `startExternalDrag` method: where the tab was dropped (as passed to `disableDrop`), or `null` if it wasn't.
|
|
213
|
+
*/
|
|
214
|
+
export declare type ExternalDragResult = {
|
|
215
|
+
target: TabDropTarget;
|
|
216
|
+
} | null;
|
|
217
|
+
|
|
154
218
|
/**
|
|
155
219
|
* A tabset that floats above the workspace's layout (see `WorkspaceModel.floating`), e.g. a notepad that can be moved out of the way of the content beneath it.
|
|
156
220
|
*
|
|
@@ -1169,6 +1233,12 @@ export declare type ParentTabset<TabData = unknown> = {
|
|
|
1169
1233
|
* Restore the tabset if it is maximized.
|
|
1170
1234
|
*/
|
|
1171
1235
|
restore: () => void;
|
|
1236
|
+
/**
|
|
1237
|
+
* Select a tab within this tabset (e.g. from an overflow menu; see `useTabListOverflow`).
|
|
1238
|
+
*
|
|
1239
|
+
* ℹ️ This has no effect if the tab isn't in this tabset; use `WorkspaceImperativeHandle.selectTab` to select a tab in any tabset.
|
|
1240
|
+
*/
|
|
1241
|
+
selectTab: (tabId: string) => void;
|
|
1172
1242
|
/**
|
|
1173
1243
|
* Id of the Workspace that contains the tabset.
|
|
1174
1244
|
*/
|
|
@@ -1280,6 +1350,98 @@ export declare type ParentWorkspace<TabData = unknown, TabsetData = unknown> = W
|
|
|
1280
1350
|
id: string;
|
|
1281
1351
|
};
|
|
1282
1352
|
|
|
1353
|
+
/**
|
|
1354
|
+
* A popout window opened by `usePopoutWindows`.
|
|
1355
|
+
*/
|
|
1356
|
+
export declare type PopoutWindow = {
|
|
1357
|
+
/**
|
|
1358
|
+
* The element (created by the popup's document, within its body) that the popout's content is rendered into.
|
|
1359
|
+
*/
|
|
1360
|
+
container: HTMLElement;
|
|
1361
|
+
/**
|
|
1362
|
+
* Unique id of the popout (e.g. a React key).
|
|
1363
|
+
*/
|
|
1364
|
+
id: string;
|
|
1365
|
+
/**
|
|
1366
|
+
* The popup window.
|
|
1367
|
+
*/
|
|
1368
|
+
window: Window;
|
|
1369
|
+
};
|
|
1370
|
+
|
|
1371
|
+
/**
|
|
1372
|
+
* Where a popout window is on screen (in screen coordinates) and how big its content is (in pixels); see `usePopoutWindows`.
|
|
1373
|
+
*/
|
|
1374
|
+
export declare type PopoutWindowRect = {
|
|
1375
|
+
/** Height of the window's content, in pixels */
|
|
1376
|
+
height: number;
|
|
1377
|
+
/** Horizontal position of the window on the screen */
|
|
1378
|
+
screenX: number;
|
|
1379
|
+
/** Vertical position of the window on the screen */
|
|
1380
|
+
screenY: number;
|
|
1381
|
+
/** Width of the window's content, in pixels */
|
|
1382
|
+
width: number;
|
|
1383
|
+
};
|
|
1384
|
+
|
|
1385
|
+
/**
|
|
1386
|
+
* Returned by `usePopoutWindows`.
|
|
1387
|
+
*/
|
|
1388
|
+
export declare type PopoutWindows<TabData = unknown, TabsetData = unknown> = {
|
|
1389
|
+
/**
|
|
1390
|
+
* Close every popout window (without moving their tabs back to the main workspace).
|
|
1391
|
+
*/
|
|
1392
|
+
closeAll: () => void;
|
|
1393
|
+
/**
|
|
1394
|
+
* Each popout window's current model and where it is on screen, e.g. to save them (and open them again later with `open`).
|
|
1395
|
+
*
|
|
1396
|
+
* ℹ️ A popup that reports the opener's exact position as its own (e.g. in Brave) is reported where it was opened instead.
|
|
1397
|
+
*/
|
|
1398
|
+
getState: () => PopoutWindowState<TabData, TabsetData>[];
|
|
1399
|
+
/**
|
|
1400
|
+
* Open a popout window showing a model (e.g. from a button that pops out a tab, or to restore a saved popout).
|
|
1401
|
+
*
|
|
1402
|
+
* ⚠️ Browsers block popup windows that aren't opened in response to user input (e.g. a click),
|
|
1403
|
+
* and some block all but the first one opened for each input.
|
|
1404
|
+
*
|
|
1405
|
+
* @returns `true` if the window was opened, or `false` if it was blocked (or the model has no tabs, in which case no window is opened)
|
|
1406
|
+
*/
|
|
1407
|
+
open: (model: WorkspaceModelInput<TabData, TabsetData>, rect: PopoutWindowRect) => boolean;
|
|
1408
|
+
/**
|
|
1409
|
+
* The open popout windows.
|
|
1410
|
+
*/
|
|
1411
|
+
popouts: PopoutWindow[];
|
|
1412
|
+
/**
|
|
1413
|
+
* Render the popout windows' content (each into its window's container, with a portal); render the result alongside the main Workspace.
|
|
1414
|
+
*
|
|
1415
|
+
* @param renderWorkspace Renders a popout's Workspace; spread the given props onto it (along with the same `dragGroup` as the main Workspace, to drag tabs between windows)
|
|
1416
|
+
*/
|
|
1417
|
+
render: (renderWorkspace: (props: PopoutWorkspaceProps<TabData, TabsetData>, popout: PopoutWindow) => ReactNode) => ReactNode;
|
|
1418
|
+
};
|
|
1419
|
+
|
|
1420
|
+
/**
|
|
1421
|
+
* A popout window's model and where it is on screen, e.g. to save the popouts and open them again later (see `usePopoutWindows`).
|
|
1422
|
+
*/
|
|
1423
|
+
export declare type PopoutWindowState<TabData = unknown, TabsetData = unknown> = {
|
|
1424
|
+
/** The popout's current model */
|
|
1425
|
+
model: WorkspaceModel<TabData, TabsetData>;
|
|
1426
|
+
/** Where the popout is on screen, and its size */
|
|
1427
|
+
rect: PopoutWindowRect;
|
|
1428
|
+
};
|
|
1429
|
+
|
|
1430
|
+
/**
|
|
1431
|
+
* Props for the Workspace rendered into a popout window (see `PopoutWindows.render`).
|
|
1432
|
+
*
|
|
1433
|
+
* ℹ️ The popout window is closed once its workspace has no tabs left (e.g. its last tab is dragged back to the main window);
|
|
1434
|
+
* if the Workspace needs its own `onModelChanged` prop, call this one from it.
|
|
1435
|
+
*/
|
|
1436
|
+
export declare type PopoutWorkspaceProps<TabData = unknown, TabsetData = unknown> = {
|
|
1437
|
+
/** The popout's initial model */
|
|
1438
|
+
defaultModel: WorkspaceModel<TabData, TabsetData>;
|
|
1439
|
+
/** Closes the popout window once its workspace has no tabs left */
|
|
1440
|
+
onModelChanged: (model: WorkspaceModel<TabData, TabsetData>, meta: WorkspaceChangedMeta) => void;
|
|
1441
|
+
/** Used to read the popout's current model (e.g. when it's closed) */
|
|
1442
|
+
workspaceRef: RefObject<WorkspaceImperativeHandle<TabData, TabsetData> | null>;
|
|
1443
|
+
};
|
|
1444
|
+
|
|
1283
1445
|
declare type ResizePreviewMode = "panel" | "separator";
|
|
1284
1446
|
|
|
1285
1447
|
/**
|
|
@@ -1510,6 +1672,17 @@ export declare type TabDropTarget = {
|
|
|
1510
1672
|
edge: WorkspaceDropEdge;
|
|
1511
1673
|
};
|
|
1512
1674
|
|
|
1675
|
+
/**
|
|
1676
|
+
* Options for which tabs count as out of view (see `useTabListOverflow`).
|
|
1677
|
+
*/
|
|
1678
|
+
export declare type TabListOverflowOptions = {
|
|
1679
|
+
/**
|
|
1680
|
+
* Also include tabs that are only partly visible (cut off by an edge of the tab list), e.g. for an overflow menu that lists them too.
|
|
1681
|
+
* By default, only tabs that are entirely out of view are included.
|
|
1682
|
+
*/
|
|
1683
|
+
includePartiallyVisible?: boolean | undefined;
|
|
1684
|
+
};
|
|
1685
|
+
|
|
1513
1686
|
/**
|
|
1514
1687
|
* A tab within a tabset.
|
|
1515
1688
|
*/
|
|
@@ -1843,6 +2016,10 @@ export declare type TabsetNodeInput<TabData = unknown, TabsetData = unknown> = O
|
|
|
1843
2016
|
/**
|
|
1844
2017
|
* Arguments passed to the Workspace's `onTearOff` prop: the tab (or whole tabset) dropped outside of the window,
|
|
1845
2018
|
* and a model for showing it in a new workspace (e.g. in a popup window).
|
|
2019
|
+
*
|
|
2020
|
+
* @deprecated Browsers don't reliably report where a drag that leaves the window ends (so a popup can't be opened where the tab was released),
|
|
2021
|
+
* and some block popups opened at the end of a drag. Open popout windows from a button instead (see `usePopoutWindows`).
|
|
2022
|
+
* This will be removed in the next major version.
|
|
1846
2023
|
*/
|
|
1847
2024
|
export declare type TearOffArgs<TabData = unknown, TabsetData = unknown> = ({
|
|
1848
2025
|
/**
|
|
@@ -2063,6 +2240,60 @@ export declare function useParentTabState(): ParentTabState | null;
|
|
|
2063
2240
|
*/
|
|
2064
2241
|
export declare function useParentWorkspace<TabData = unknown, TabsetData = unknown>(): ParentWorkspace<TabData, TabsetData> | null;
|
|
2065
2242
|
|
|
2243
|
+
/**
|
|
2244
|
+
* Opens tabs (and tabsets) in popout windows, with the returned `open` function (e.g. from a button that pops out a tab).
|
|
2245
|
+
* Each popout window shows its own Workspace, rendered by the returned `render` function.
|
|
2246
|
+
*
|
|
2247
|
+
* - The page's stylesheets are copied into each popout window (see `copyStyles`)
|
|
2248
|
+
* - When the user closes a popout window, its tabs are moved back to the main workspace (see `onClose`)
|
|
2249
|
+
* - A popout window is closed once its last tab is moved out of it (e.g. dragged back to the main window; see the Workspace's `dragGroup` prop)
|
|
2250
|
+
* - Popout windows are closed when the page that opened them is closed, or the component that uses this hook unmounts (since it renders their content); see `onCloseAll`
|
|
2251
|
+
*/
|
|
2252
|
+
export declare function usePopoutWindows<TabData = unknown, TabsetData = unknown>(options: UsePopoutWindowsOptions<TabData, TabsetData>): PopoutWindows<TabData, TabsetData>;
|
|
2253
|
+
|
|
2254
|
+
/**
|
|
2255
|
+
* Options for `usePopoutWindows`.
|
|
2256
|
+
*/
|
|
2257
|
+
export declare type UsePopoutWindowsOptions<TabData = unknown, TabsetData = unknown> = {
|
|
2258
|
+
/**
|
|
2259
|
+
* Copy the page's stylesheets into each popout window when it's opened (and stylesheets added to the page's head afterward).
|
|
2260
|
+
* Defaults to `true`; if `false`, none of the page's styles (including plain stylesheets) are copied.
|
|
2261
|
+
*
|
|
2262
|
+
* ℹ️ The rules of `<style>` elements are copied (including rules inserted with `CSSStyleSheet.insertRule`, e.g. by CSS-in-JS libraries)
|
|
2263
|
+
* as they are when the window opens; rules inserted into them later (and stylesheets edited or removed afterward) aren't.
|
|
2264
|
+
* Libraries that insert rules as components render (e.g. Emotion) can usually be configured to insert them into the popup's document instead.
|
|
2265
|
+
*/
|
|
2266
|
+
copyStyles?: boolean | undefined;
|
|
2267
|
+
/**
|
|
2268
|
+
* Called with each popout window's model and position when the page that opened them is closed (or reloaded),
|
|
2269
|
+
* or the component that uses the hook unmounts, just before the popout windows are closed;
|
|
2270
|
+
* e.g. to save them (and open them again later with `open`).
|
|
2271
|
+
* It isn't called if there are no popout windows.
|
|
2272
|
+
*/
|
|
2273
|
+
onCloseAll?: ((state: PopoutWindowState<TabData, TabsetData>[]) => void) | undefined;
|
|
2274
|
+
/**
|
|
2275
|
+
* What happens to the tabs in a popout window when the user closes it:
|
|
2276
|
+
* - `"dock"` (the default) adds them back to the main workspace (see `workspaceRef`)
|
|
2277
|
+
* - `"discard"` closes them
|
|
2278
|
+
* - A function is called with the popout's model instead (e.g. to save its tabs)
|
|
2279
|
+
*
|
|
2280
|
+
* ℹ️ When docking, a tab is skipped (with a development warning) if the main workspace already has a tab with the same id (its data is not updated, and it isn't selected),
|
|
2281
|
+
* and only the selected tab of the popout's first tabset (that has one) is selected.
|
|
2282
|
+
*
|
|
2283
|
+
* ℹ️ It isn't called when the popout closes because its last tab was moved out of it, or when it's closed by `closeAll`
|
|
2284
|
+
* (or because the page that opened it is closed, or the component that uses this hook unmounts; see `onCloseAll`).
|
|
2285
|
+
*/
|
|
2286
|
+
onClose?: "discard" | "dock" | ((model: WorkspaceModel<TabData, TabsetData>) => void) | undefined;
|
|
2287
|
+
/**
|
|
2288
|
+
* Called when a popout window is opened, before its content is rendered, e.g. to set its title or style its container.
|
|
2289
|
+
*/
|
|
2290
|
+
onOpen?: ((popout: PopoutWindow) => void) | undefined;
|
|
2291
|
+
/**
|
|
2292
|
+
* The main workspace, which tabs are added back to when a popout window is closed (see `onClose`).
|
|
2293
|
+
*/
|
|
2294
|
+
workspaceRef: RefObject<WorkspaceImperativeHandle<TabData, TabsetData> | null>;
|
|
2295
|
+
};
|
|
2296
|
+
|
|
2066
2297
|
/**
|
|
2067
2298
|
* Returns the space (in pixels) in the nearest ancestor tabset's tab list that its tabs don't use (negative once they overflow),
|
|
2068
2299
|
* e.g. for a toolbar (see `renderTabsetToolbar`) that moves items into an overflow menu when the tabset's header runs out of room;
|
|
@@ -2074,6 +2305,19 @@ export declare function useParentWorkspace<TabData = unknown, TabsetData = unkno
|
|
|
2074
2305
|
*/
|
|
2075
2306
|
export declare function useTabListFreeSpace(): number | undefined;
|
|
2076
2307
|
|
|
2308
|
+
/**
|
|
2309
|
+
* Returns the ids of the nearest ancestor tabset's tabs that are out of view (scrolled out of its tab list, which overflows),
|
|
2310
|
+
* in the order they're shown; e.g. for an overflow menu in its toolbar (see `renderTabsetToolbar`) that lists them.
|
|
2311
|
+
* See `WorkspaceImperativeHandle.getTabListOverflow`.
|
|
2312
|
+
*
|
|
2313
|
+
* ℹ️ The component re-renders when they change (e.g. when the tab list is scrolled or resized, or tabs are added or removed), before the browser paints.
|
|
2314
|
+
* The same array is returned until then.
|
|
2315
|
+
*
|
|
2316
|
+
* @param options.includePartiallyVisible Also include tabs that are only partly visible (cut off by an edge of the tab list)
|
|
2317
|
+
* @returns The ids of the tabs that are out of view; none if the component is not rendered within a tabset (or the tab list hasn't been measured yet, e.g. while server rendering, or right after the tabset is first rendered)
|
|
2318
|
+
*/
|
|
2319
|
+
export declare function useTabListOverflow({ includePartiallyVisible }?: TabListOverflowOptions): string[];
|
|
2320
|
+
|
|
2077
2321
|
/**
|
|
2078
2322
|
* Convenience hook to return a properly typed ref callback for the Workspace component.
|
|
2079
2323
|
*
|
|
@@ -2133,6 +2377,9 @@ export declare type WorkspaceChangedMeta = {
|
|
|
2133
2377
|
* ℹ️ A tab (or tabset) dragged to another workspace (see the `dragGroup` prop) is reported as `"transfer"` by both workspaces:
|
|
2134
2378
|
* the one it was dropped into (which added it) and the one it was dragged from (which removed it).
|
|
2135
2379
|
*
|
|
2380
|
+
* ℹ️ A copy of a tab (or tabset) dropped while the copy modifier key was held (see the `copyTab` and `copyTabset` props) is reported as `"copy"` by the workspace it was dropped into;
|
|
2381
|
+
* the workspace it was dragged from (if that's another one) doesn't change.
|
|
2382
|
+
*
|
|
2136
2383
|
* ℹ️ Floating tabsets (see `WorkspaceModel.floating`) are reported as `"float"` when they're created, `"move"` and `"resize"` when they're dragged by their headers and edges,
|
|
2137
2384
|
* and `"raise"` when they're brought to the front (e.g. by pressing one that's behind another).
|
|
2138
2385
|
*
|
|
@@ -2145,8 +2392,10 @@ export declare type WorkspaceChangedMeta = {
|
|
|
2145
2392
|
* Which change caused `onModelChanged` to be called.
|
|
2146
2393
|
*
|
|
2147
2394
|
* ⚠️ New reasons may be added in later versions.
|
|
2395
|
+
*
|
|
2396
|
+
* ℹ️ `"tear-off"` is only reported with the deprecated `onTearOff` prop, and will be removed along with it.
|
|
2148
2397
|
*/
|
|
2149
|
-
export declare type WorkspaceChangeReason = "add" | "close" | "collapse" | "expand" | "float" | "maximize" | "move" | "raise" | "resize" | "restore" | "select" | "set-model" | "tear-off" | "transfer" | "update";
|
|
2398
|
+
export declare type WorkspaceChangeReason = "add" | "close" | "collapse" | "copy" | "expand" | "float" | "maximize" | "move" | "raise" | "resize" | "restore" | "select" | "set-model" | "tear-off" | "transfer" | "update";
|
|
2150
2399
|
|
|
2151
2400
|
/**
|
|
2152
2401
|
* CSS class names for the elements a Workspace renders (see the Workspace's `classNames` prop).
|
|
@@ -2180,7 +2429,7 @@ export declare type WorkspaceClassNames = {
|
|
|
2180
2429
|
toolbar?: string | undefined;
|
|
2181
2430
|
};
|
|
2182
2431
|
|
|
2183
|
-
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;
|
|
2432
|
+
declare function WorkspaceComponent<TabData = unknown, TabsetData = unknown>({ acceptExternalDrop, className, classNames, copyTab, copyTabset, 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;
|
|
2184
2433
|
|
|
2185
2434
|
/**
|
|
2186
2435
|
* Edge of the workspace.
|
|
@@ -2283,6 +2532,19 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
|
|
|
2283
2532
|
* or right after the tabset is first rendered: it's measured after React commits, before the browser paints)
|
|
2284
2533
|
*/
|
|
2285
2534
|
getTabListFreeSpace: (tabsetId: string) => number | undefined;
|
|
2535
|
+
/**
|
|
2536
|
+
* Ids of a tabset's tabs that are out of view (scrolled out of its tab list, which overflows), in the order they're shown;
|
|
2537
|
+
* e.g. to list them in an overflow menu.
|
|
2538
|
+
*
|
|
2539
|
+
* ℹ️ The same array is returned until the tabs out of view change.
|
|
2540
|
+
* Tabs that aren't rendered at all (e.g. hidden with `display: none`) aren't included.
|
|
2541
|
+
*
|
|
2542
|
+
* ℹ️ Within a tabset (e.g. its toolbar), the `useTabListOverflow` hook returns this value (and re-renders when it changes).
|
|
2543
|
+
*
|
|
2544
|
+
* @returns The ids of the tabs that are out of view, or `undefined` if the tabset isn't rendered (or hasn't been measured yet, e.g. while server rendering,
|
|
2545
|
+
* or right after the tabset is first rendered: it's measured after React commits, before the browser paints)
|
|
2546
|
+
*/
|
|
2547
|
+
getTabListOverflow: (tabsetId: string, options?: TabListOverflowOptions) => string[] | undefined;
|
|
2286
2548
|
/**
|
|
2287
2549
|
* Maximize a tabset, so that it covers the rest of the workspace.
|
|
2288
2550
|
*
|
|
@@ -2317,6 +2579,8 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
|
|
|
2317
2579
|
restoreTabset: () => void;
|
|
2318
2580
|
/**
|
|
2319
2581
|
* Select a tab within its tabset.
|
|
2582
|
+
*
|
|
2583
|
+
* ℹ️ Like a tab selected any other way, it's scrolled into view if its tab list overflows.
|
|
2320
2584
|
*/
|
|
2321
2585
|
selectTab: (tabId: string) => void;
|
|
2322
2586
|
/**
|
|
@@ -2325,6 +2589,24 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
|
|
|
2325
2589
|
* @return Applied model (after normalization)
|
|
2326
2590
|
*/
|
|
2327
2591
|
setModel: (model: WorkspaceModelInput<TabData, TabsetData>) => WorkspaceModel<TabData, TabsetData>;
|
|
2592
|
+
/**
|
|
2593
|
+
* Start dragging a tab that isn't in the workspace yet, from an element outside of it (e.g. an item in a palette of widgets);
|
|
2594
|
+
* call it from the element's `pointerdown` handler.
|
|
2595
|
+
* The tab is dragged like tabs within the workspace are (with the same drop targets, drop indicator, and `disableDrop` checks, with the `"new"` source),
|
|
2596
|
+
* and is added where it's dropped (reported to `onModelChanged` with the `"add"` reason).
|
|
2597
|
+
*
|
|
2598
|
+
* The drag starts once the pointer has moved a few pixels, so a press that doesn't move (e.g. a click) does nothing;
|
|
2599
|
+
* the click that follows a drag is suppressed. Pressing Escape cancels the drag.
|
|
2600
|
+
*
|
|
2601
|
+
* ℹ️ Unlike other imperative methods, the drop is restricted by `disabled` and `disableDrop`, since the user chooses where it goes.
|
|
2602
|
+
*
|
|
2603
|
+
* ℹ️ The element must be in the same document as the workspace.
|
|
2604
|
+
* Like tabs, it should have `touch-action: none` (e.g. with CSS), so that touch input drags it rather than scrolling the page.
|
|
2605
|
+
*
|
|
2606
|
+
* @param event The `pointerdown` event of the pressed element
|
|
2607
|
+
* @return A promise that resolves when the drag ends: with where the tab was dropped, or `null` if it wasn't (e.g. the pointer isn't pressed or the press isn't the primary button, the drag was canceled, or it was released outside of the workspace)
|
|
2608
|
+
*/
|
|
2609
|
+
startExternalDrag: (event: PointerEvent | PointerEvent_2<Element>, options: ExternalDragOptions<TabData>) => Promise<ExternalDragResult>;
|
|
2328
2610
|
/**
|
|
2329
2611
|
* Subscribe to changes to the free space in a tabset's tab list (see `getTabListFreeSpace`),
|
|
2330
2612
|
* e.g. from a toolbar rendered outside of the Workspace.
|
|
@@ -2337,6 +2619,18 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
|
|
|
2337
2619
|
* @returns A function that unsubscribes the listener
|
|
2338
2620
|
*/
|
|
2339
2621
|
subscribeToTabListFreeSpace: (tabsetId: string, listener: (freeSpace: number | undefined) => void) => () => void;
|
|
2622
|
+
/**
|
|
2623
|
+
* Subscribe to changes to which of a tabset's tabs are out of view (see `getTabListOverflow`),
|
|
2624
|
+
* e.g. from an overflow menu rendered outside of the Workspace.
|
|
2625
|
+
*
|
|
2626
|
+
* ℹ️ The listener is called synchronously when the tab list is measured (when it's scrolled, when it or its tabs change size, or when tabs are added or removed),
|
|
2627
|
+
* before the browser paints, except while the user scrolls the list (it's reported in the scroll event, and the browser may show the new position first).
|
|
2628
|
+
*
|
|
2629
|
+
* ℹ️ The listener is called with `undefined` when the tabset is removed (e.g. closed, or merged into another tabset).
|
|
2630
|
+
*
|
|
2631
|
+
* @returns A function that unsubscribes the listener
|
|
2632
|
+
*/
|
|
2633
|
+
subscribeToTabListOverflow: (tabsetId: string, listener: (tabIds: string[] | undefined) => void, options?: TabListOverflowOptions) => () => void;
|
|
2340
2634
|
/**
|
|
2341
2635
|
* Update a tab; fields that are not specified are not changed.
|
|
2342
2636
|
*
|
|
@@ -2424,6 +2718,20 @@ export declare type WorkspaceNode<TabData = unknown, TabsetData = unknown> = Spl
|
|
|
2424
2718
|
export declare type WorkspaceNodeInput<TabData = unknown, TabsetData = unknown> = SplitNodeInput<TabData, TabsetData> | TabsetNodeInput<TabData, TabsetData>;
|
|
2425
2719
|
|
|
2426
2720
|
export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Omit<HTMLAttributes<HTMLDivElement>, "children" | "defaultValue"> & {
|
|
2721
|
+
/**
|
|
2722
|
+
* Lets the workspace accept drags that use the browser's drag and drop from outside of any workspace
|
|
2723
|
+
* (e.g. an element of the application with the `draggable` attribute, a file, or a link from another application),
|
|
2724
|
+
* showing the drop indicator while the drag is over the workspace, and creating a tab where it's dropped.
|
|
2725
|
+
* The new tab is reported to `onModelChanged` with the `"add"` reason.
|
|
2726
|
+
*
|
|
2727
|
+
* ℹ️ `disableDrop` can't be called until the tab is created (when the drag is dropped), so a target it rejects is shown as accepted while dragging;
|
|
2728
|
+
* the drop is ignored then. Drag sources within the application can use the imperative `startExternalDrag` method instead, which doesn't have this limitation.
|
|
2729
|
+
*
|
|
2730
|
+
* ℹ️ Elements within the workspace's tab content that handle the same drags themselves (by canceling the `dragover` and `drop` events) take precedence.
|
|
2731
|
+
*
|
|
2732
|
+
* ℹ️ This object is read when drag events are handled, so it doesn't need to be memoized.
|
|
2733
|
+
*/
|
|
2734
|
+
acceptExternalDrop?: AcceptExternalDrop<TabData> | undefined;
|
|
2427
2735
|
/**
|
|
2428
2736
|
* CSS class name.
|
|
2429
2737
|
*/
|
|
@@ -2461,6 +2769,42 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
|
|
|
2461
2769
|
* ℹ️ This value is only used when the Workspace mounts; use the imperative `setModel` method to replace it later.
|
|
2462
2770
|
*/
|
|
2463
2771
|
defaultModel: WorkspaceModelInput<TabData, TabsetData>;
|
|
2772
|
+
/**
|
|
2773
|
+
* Lets tabs be copied by dragging them: a tab dropped while the copy modifier key is held (Option on macOS, Ctrl elsewhere) adds the copy this function returns,
|
|
2774
|
+
* leaving the dragged tab where it was. The change is reported to `onModelChanged` with the `"copy"` reason.
|
|
2775
|
+
*
|
|
2776
|
+
* Returning `null` (or `undefined`) moves the dragged tab instead. If that move isn't allowed either (the `disableDrop` prop rejects it, the ids conflict, or it isn't a valid place to move the tab), nothing happens.
|
|
2777
|
+
*
|
|
2778
|
+
* ℹ️ The copy needs an id that isn't used by any other node of the workspace (e.g. `crypto.randomUUID()`); copies with ids that are in use are rejected (and the tab is moved instead).
|
|
2779
|
+
*
|
|
2780
|
+
* ℹ️ The workspace the tab is dropped into makes the copy, so a tab dragged from another workspace (see the `dragGroup` prop) is copied by the workspace it's dropped into
|
|
2781
|
+
* (and is only copied if that workspace has this prop).
|
|
2782
|
+
*
|
|
2783
|
+
* @param tab The tab being dragged
|
|
2784
|
+
* @param target Where the copy will be dropped
|
|
2785
|
+
*/
|
|
2786
|
+
copyTab?: ((tab: TabNode<TabData>, target: TabDropTarget) => TabNode<TabData> | null | undefined) | undefined;
|
|
2787
|
+
/**
|
|
2788
|
+
* Lets tabsets be copied by dragging them (by their headers), like the `copyTab` prop does for tabs: a tabset dropped while the copy modifier key is held adds the copy this function returns,
|
|
2789
|
+
* leaving the dragged tabset where it was. The change is reported to `onModelChanged` with the `"copy"` reason.
|
|
2790
|
+
*
|
|
2791
|
+
* The copy includes its tabs, which need ids that aren't used by any other node of the workspace too; the `copyTab` argument copies a tab:
|
|
2792
|
+
*
|
|
2793
|
+
* ```tsx
|
|
2794
|
+
* copyTabset={(tabset, copyTab) => ({ ...tabset, id: crypto.randomUUID(), tabs: tabset.tabs.map(copyTab) })}
|
|
2795
|
+
* ```
|
|
2796
|
+
*
|
|
2797
|
+
* Returning `null` (or `undefined`) moves the dragged tabset instead. If that move isn't allowed either (the `disableDrop` prop rejects it, the ids conflict, a `keepWhenEmpty` tabset is dropped into another workspace, or it isn't a valid place to move the tabset), nothing happens.
|
|
2798
|
+
*
|
|
2799
|
+
* ℹ️ The copy's selected tab is the copy of the dragged tabset's selected tab (matched by position), unless the copy selects one of its own tabs.
|
|
2800
|
+
*
|
|
2801
|
+
* ℹ️ A copy dropped into a tab list (or onto the center of another tabset) only adds its tabs; its id and data are only used where it's added as a tabset.
|
|
2802
|
+
*
|
|
2803
|
+
* @param tabset The tabset being dragged
|
|
2804
|
+
* @param copyTab Copies a tab with the `copyTab` prop (and the same drop target); without that prop (or if it returns `null`), the copy is a shallow copy of the tab with a new id
|
|
2805
|
+
* @param target Where the copy will be dropped
|
|
2806
|
+
*/
|
|
2807
|
+
copyTabset?: ((tabset: TabsetNode<TabData, TabsetData>, copyTab: (tab: TabNode<TabData>) => TabNode<TabData>, target: TabDropTarget) => TabsetNode<TabData, TabsetData> | null | undefined) | undefined;
|
|
2464
2808
|
/**
|
|
2465
2809
|
* Locks the arrangement: tabs cannot be resized, dragged, dropped, or closed by the user.
|
|
2466
2810
|
* Selecting tabs and maximizing tabsets still work.
|
|
@@ -2506,8 +2850,6 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
|
|
|
2506
2850
|
* ⚠️ 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);
|
|
2507
2851
|
* tabs whose data can't be cloned (and tabsets containing them) can only be dragged within their copy of the application.
|
|
2508
2852
|
* 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.
|
|
2509
|
-
*
|
|
2510
|
-
* ⚠️ 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.
|
|
2511
2853
|
*/
|
|
2512
2854
|
dragGroup?: string | undefined;
|
|
2513
2855
|
/**
|
|
@@ -2559,13 +2901,18 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
|
|
|
2559
2901
|
* ℹ️ 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.
|
|
2560
2902
|
* 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,
|
|
2561
2903
|
* so browsers block popups opened then unless the drag started a few seconds earlier at most (and Safari blocks them always).
|
|
2904
|
+
*
|
|
2905
|
+
* ⚠️ Deprecated: browsers don't reliably report where a drag that leaves the window ends, and some block popups opened at the end of a drag.
|
|
2906
|
+
* Open popout windows from a button instead (see `usePopoutWindows`). This will be removed in the next major version.
|
|
2907
|
+
*
|
|
2908
|
+
* @deprecated Open popout windows from a button instead (see `usePopoutWindows`).
|
|
2562
2909
|
*/
|
|
2563
2910
|
onTearOff?: ((args: TearOffArgs<TabData, TabsetData>) => boolean) | undefined;
|
|
2564
2911
|
/**
|
|
2565
2912
|
* Content of the element that follows the pointer while a tab is being dragged.
|
|
2566
2913
|
* Defaults to the tab's title (or id).
|
|
2567
2914
|
*
|
|
2568
|
-
* ℹ️ The element has a `data-tear-off` attribute while releasing the pointer would tear off the tab (see `onTearOff`).
|
|
2915
|
+
* ℹ️ The element has a `data-tear-off` attribute while releasing the pointer would tear off the tab (see the deprecated `onTearOff` prop).
|
|
2569
2916
|
*/
|
|
2570
2917
|
renderDragPreview?: ((tab: TabNode<TabData>, state: DragPreviewState) => ReactNode) | undefined;
|
|
2571
2918
|
/**
|
|
@@ -2573,7 +2920,7 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
|
|
|
2573
2920
|
* 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.
|
|
2574
2921
|
*
|
|
2575
2922
|
* ℹ️ The element has a `data-drag-type` attribute: `"tabset"` while a tabset is dragged, and `"tab"` while a tab is.
|
|
2576
|
-
* It also has a `data-tear-off` attribute while releasing the pointer would tear off the tabset (see `onTearOff`).
|
|
2923
|
+
* It also has a `data-tear-off` attribute while releasing the pointer would tear off the tabset (see the deprecated `onTearOff` prop).
|
|
2577
2924
|
*/
|
|
2578
2925
|
renderTabsetDragPreview?: ((tabset: TabsetNode<TabData, TabsetData>, state: DragPreviewState) => ReactNode) | undefined;
|
|
2579
2926
|
/**
|
|
@@ -2611,8 +2958,9 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
|
|
|
2611
2958
|
* ⚠️ Merge `className` and `style` rather than replacing them (e.g. `style={{ ...props.style, padding: 4 }}`):
|
|
2612
2959
|
* they include the `tab` entries of the `classNames` and `styles` props, and `style` includes the `touch-action` that touch dragging depends on.
|
|
2613
2960
|
*
|
|
2614
|
-
* ℹ️ Pointer
|
|
2615
|
-
* so clicking a button within a tab doesn't select or drag it.
|
|
2961
|
+
* ℹ️ Pointer events from interactive descendants (`button` elements, form controls such as `input` (and the `label` elements of form controls), editable content, elements with a `button` or form control role such as `role="checkbox"`, or elements with a `data-tab-ignore` attribute) are ignored,
|
|
2962
|
+
* so clicking a button within a tab doesn't select or drag it, and pressing within an input (e.g. one used to rename the tab) doesn't start a drag.
|
|
2963
|
+
* Keys pressed within any descendant (rather than the tab itself) are left to it, so they don't move focus between tabs or close the tab.
|
|
2616
2964
|
*
|
|
2617
2965
|
* ℹ️ When this prop is not provided, tabs show their title (or id) followed by a `TabCloseButton`.
|
|
2618
2966
|
*/
|