react-resizable-panels 4.22.1 → 4.24.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.
|
@@ -70,6 +70,27 @@ declare type BasePanelAttributes = Omit<HTMLAttributes<HTMLDivElement>, "onResiz
|
|
|
70
70
|
|
|
71
71
|
declare type BaseSeparatorAttributes = Omit<HTMLAttributes<HTMLDivElement>, "role" | "tabIndex">;
|
|
72
72
|
|
|
73
|
+
/**
|
|
74
|
+
* A change that the user is about to make to the model, passed to the Workspace's `onBeforeModelChange` prop.
|
|
75
|
+
*/
|
|
76
|
+
export declare type BeforeModelChangeArgs<TabData = unknown, TabsetData = unknown> = {
|
|
77
|
+
/** The model as it will be if the change is allowed */
|
|
78
|
+
model: WorkspaceModel<TabData, TabsetData>;
|
|
79
|
+
/** The model as it is */
|
|
80
|
+
prevModel: WorkspaceModel<TabData, TabsetData>;
|
|
81
|
+
/** Which change would be made (see `WorkspaceChangedMeta.reason`) */
|
|
82
|
+
reason: WorkspaceChangeReason;
|
|
83
|
+
/**
|
|
84
|
+
* The tabs the change would remove from the workspace, e.g. the tab (or the tabs of the tabset) the user is closing;
|
|
85
|
+
* empty if it doesn't remove any.
|
|
86
|
+
*/
|
|
87
|
+
removedTabs: TabNode<TabData>[];
|
|
88
|
+
/** For a tab (or tabset) dropped in from another workspace, that workspace's `dragSourceInfo` prop (see `WorkspaceChangedMeta.sourceInfo`) */
|
|
89
|
+
sourceInfo?: unknown;
|
|
90
|
+
/** For a tab (or tabset) dropped in from another workspace, that workspace's id (see `WorkspaceChangedMeta.sourceWorkspaceId`) */
|
|
91
|
+
sourceWorkspaceId?: string | undefined;
|
|
92
|
+
};
|
|
93
|
+
|
|
73
94
|
/**
|
|
74
95
|
* A Cell occupies one or more tracks (columns and rows) within a Grid.
|
|
75
96
|
* Cells are resized along with the tracks they occupy.
|
|
@@ -159,6 +180,20 @@ export declare type DisableDropArgs<TabData = unknown, TabsetData = unknown> = {
|
|
|
159
180
|
* - `"new"`: outside of any workspace, for a tab that's created when it's dropped (see the `startExternalDrag` method and the `acceptExternalDrop` prop)
|
|
160
181
|
*/
|
|
161
182
|
source: "external" | "local" | "new";
|
|
183
|
+
/**
|
|
184
|
+
* The `dragSourceInfo` prop of the workspace the tab (or tabset) is dragged from (this workspace's own, for `"local"` drags);
|
|
185
|
+
* `undefined` for `"new"` tabs, or if that workspace doesn't have the prop.
|
|
186
|
+
*
|
|
187
|
+
* ℹ️ e.g. to only accept tabs from workspaces of the same kind, or from a version of the application whose tab data this one understands:
|
|
188
|
+
* `disableDrop={({ source, sourceInfo }) => source === "external" && sourceInfo?.app !== "reports"}`
|
|
189
|
+
*/
|
|
190
|
+
sourceInfo: unknown;
|
|
191
|
+
/**
|
|
192
|
+
* The id of the workspace the tab (or tabset) is dragged from (see the Workspace's `id` prop); `undefined` for `"new"` tabs (and for drags from another page that uses an earlier release of this library).
|
|
193
|
+
*
|
|
194
|
+
* ⚠️ Ids are only unique within a copy of the application (e.g. ids from `useId` may be the same in another browser tab), so use `sourceInfo` to tell copies apart.
|
|
195
|
+
*/
|
|
196
|
+
sourceWorkspaceId: string | undefined;
|
|
162
197
|
/**
|
|
163
198
|
* The tab being dropped.
|
|
164
199
|
*
|
|
@@ -226,7 +261,9 @@ export declare type ExternalDragResult = {
|
|
|
226
261
|
*
|
|
227
262
|
* ℹ️ Floating tabsets can always be collapsed (with the imperative API, e.g. `useParentTabset().collapse()`), so they don't have the `collapsible` flag.
|
|
228
263
|
* A collapsed floating tabset is only as large as its header across it (e.g. as tall as its tabs, when they're placed on top), and can only be resized along it;
|
|
229
|
-
* its `width` and `height` are the size it expands to. Like tabsets in the layout, clicking a tab (or the empty space in the header) of a collapsed floating tabset expands it
|
|
264
|
+
* its `width` and `height` are the size it expands to. Like tabsets in the layout, clicking a tab (or the empty space in the header) of a collapsed floating tabset expands it (unless the workspace is `disabled`),
|
|
265
|
+
* and clicking the selected tab of an expanded one (or pressing Enter or Space on it) collapses it (unless the workspace is `disabled`);
|
|
266
|
+
* but when another floating tabset is shown over part of it, clicking its selected tab only brings it to the front.
|
|
230
267
|
*/
|
|
231
268
|
export declare type FloatingTabsetNode<TabData = unknown, TabsetData = unknown> = Omit<TabsetNode<TabData, TabsetData>, "collapsible" | "size"> & FloatingTabsetRect;
|
|
232
269
|
|
|
@@ -776,11 +813,15 @@ export declare type GroupProps = HTMLAttributes<HTMLDivElement> & {
|
|
|
776
813
|
};
|
|
777
814
|
|
|
778
815
|
/**
|
|
779
|
-
* What happens to the content of tabs that
|
|
816
|
+
* What happens to the content of tabs that aren't visible (see `ParentTabState.isVisible`), once it has been mounted (see the Workspace's `lazyTabContent` prop):
|
|
780
817
|
* - `"keep-mounted"`: content stays mounted (and its effects keep running)
|
|
781
|
-
* - `"activity"`: content stays mounted but is rendered within a hidden React `<Activity>` boundary, so its effects are unmounted;
|
|
818
|
+
* - `"activity"`: content stays mounted but is rendered within a hidden React `<Activity>` boundary, so its effects are unmounted (and it's re-rendered at a low priority);
|
|
782
819
|
* requires React 19.2 (falls back to `"keep-mounted"` otherwise)
|
|
783
820
|
* - `"unmount"`: content is unmounted
|
|
821
|
+
*
|
|
822
|
+
* ℹ️ A tab is visible when it's selected, in a tabset that isn't collapsed or covered by a maximized tabset (floating tabsets aren't covered).
|
|
823
|
+
* `"activity"` and `"unmount"` hide content when its tabset is collapsed (in the model) or covered by a maximized tabset,
|
|
824
|
+
* but not while it's only shown collapsed temporarily (e.g. while dragging a separator, or when collapsed to fit).
|
|
784
825
|
*/
|
|
785
826
|
export declare type HiddenTabBehavior = "activity" | "keep-mounted" | "unmount";
|
|
786
827
|
|
|
@@ -1180,13 +1221,17 @@ export declare type ParentTab = {
|
|
|
1180
1221
|
*/
|
|
1181
1222
|
export declare type ParentTabset<TabData = unknown> = {
|
|
1182
1223
|
/**
|
|
1183
|
-
* Add a tab to this tabset.
|
|
1224
|
+
* Add a tab to this tabset, or (with `region`) in a new tabset beside it.
|
|
1184
1225
|
*
|
|
1226
|
+
* @param options.region Where to add the tab (see `TabDropRegion`): `"center"` adds it to this tabset, and edge regions split this tabset
|
|
1227
|
+
* @param options.size Size of the new tabset, for edge regions (see `WorkspaceImperativeHandle.addTab`); its space comes from this tabset, by default half of it
|
|
1185
1228
|
* @return `true` if the tab was added (see `WorkspaceImperativeHandle.addTab`)
|
|
1186
1229
|
*/
|
|
1187
1230
|
addTab: (tab: TabNode<TabData>, options?: {
|
|
1188
1231
|
index?: number | undefined;
|
|
1232
|
+
region?: TabDropRegion | undefined;
|
|
1189
1233
|
select?: boolean | undefined;
|
|
1234
|
+
size?: number | string | undefined;
|
|
1190
1235
|
}) => boolean;
|
|
1191
1236
|
/**
|
|
1192
1237
|
* Close the tabset, along with any tabs it contains (see `WorkspaceImperativeHandle.closeTabset`).
|
|
@@ -1326,7 +1371,7 @@ export declare type ParentTabState = {
|
|
|
1326
1371
|
*/
|
|
1327
1372
|
isSelected: boolean;
|
|
1328
1373
|
/**
|
|
1329
|
-
* The tab is selected, and its tabset is neither collapsed nor covered by another, maximized tabset.
|
|
1374
|
+
* The tab is selected, and its tabset is neither collapsed nor covered by another, maximized tabset (floating tabsets are shown above a maximized tabset, so they're never covered).
|
|
1330
1375
|
*
|
|
1331
1376
|
* ℹ️ While a separator is being dragged, this reflects how the tab's tabset is shown (e.g. collapsed as soon as it reaches its collapsed size),
|
|
1332
1377
|
* which the model only reflects once the drag ends; it also reflects tabsets that are collapsed to fit (see `TabsetNode.collapsible`).
|
|
@@ -1661,6 +1706,9 @@ export declare type TabDropRegion = "bottom" | "center" | "left" | "right" | "to
|
|
|
1661
1706
|
* - 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)
|
|
1662
1707
|
* - Within a `region` of a tabset's content area; edges split the tabset, and the center adds the tab to it
|
|
1663
1708
|
* - At an `edge` of the workspace, beside all of the other tabsets (filling the workspace's height or width)
|
|
1709
|
+
*
|
|
1710
|
+
* ℹ️ A tab dropped at an edge of the workspace that a collapsed tabset lines (where it's dropped) is added to the end of that tabset's tab list instead,
|
|
1711
|
+
* so its target has an `index` (e.g. a sidebar collapsed to a strip of tabs, or a collapsed bottom panel).
|
|
1664
1712
|
*/
|
|
1665
1713
|
export declare type TabDropTarget = {
|
|
1666
1714
|
index: number;
|
|
@@ -1672,6 +1720,8 @@ export declare type TabDropTarget = {
|
|
|
1672
1720
|
edge: WorkspaceDropEdge;
|
|
1673
1721
|
};
|
|
1674
1722
|
|
|
1723
|
+
declare type TabElementValue<Value, TabData> = WorkspaceElementValue<Value, [tab: TabNode<TabData>, state: ParentTabState]> | undefined;
|
|
1724
|
+
|
|
1675
1725
|
/**
|
|
1676
1726
|
* Options for which tabs count as out of view (see `useTabListOverflow`).
|
|
1677
1727
|
*/
|
|
@@ -1754,7 +1804,7 @@ export declare type TabRenderProps = Pick<HTMLAttributes<HTMLElement>, "aria-con
|
|
|
1754
1804
|
*
|
|
1755
1805
|
* To keep the tabset as it is, call `event.preventDefault()` in an `onClick` handler.
|
|
1756
1806
|
*
|
|
1757
|
-
* ℹ️ Clicking a tab of a collapsed tabset also expands it.
|
|
1807
|
+
* ℹ️ Clicking a tab of a collapsed tabset also expands it (unless the workspace is `disabled`, which doesn't restrict this button).
|
|
1758
1808
|
*/
|
|
1759
1809
|
export declare const TabsetCollapseButton: typeof TabsetCollapseButtonComponent & {
|
|
1760
1810
|
displayName: string;
|
|
@@ -1820,6 +1870,11 @@ export declare type TabsetDragHandleState = {
|
|
|
1820
1870
|
isDisabled: boolean;
|
|
1821
1871
|
};
|
|
1822
1872
|
|
|
1873
|
+
declare type TabsetElementValue<Value, TabData, TabsetData> = WorkspaceElementValue<Value, [
|
|
1874
|
+
tabset: TabsetNode<TabData, TabsetData>,
|
|
1875
|
+
state: ParentTabsetState
|
|
1876
|
+
]> | undefined;
|
|
1877
|
+
|
|
1823
1878
|
/**
|
|
1824
1879
|
* Maximizes (or restores) the tabset it is rendered within; render it within the content returned by the Workspace's `renderTabsetToolbar` prop.
|
|
1825
1880
|
* Its `children`, `className`, `style`, and `title` can be functions of its state (see `TabsetMaximizeButtonState`), e.g. to show a different icon while the tabset is maximized:
|
|
@@ -1956,7 +2011,11 @@ export declare type TabsetNode<TabData = unknown, TabsetData = unknown> = {
|
|
|
1956
2011
|
*
|
|
1957
2012
|
* ℹ️ Tabsets are collapsed by dragging a separator past their minimum size (like collapsible Panels),
|
|
1958
2013
|
* or with the imperative API (e.g. a button rendered by `renderTabsetToolbar`, see `useParentTabset`);
|
|
1959
|
-
* clicking a tab (or the empty space in the header) of a collapsed tabset expands it, as does dropping tabs into it from another tabset.
|
|
2014
|
+
* clicking a tab (or the empty space in the header) of a collapsed tabset expands it (unless the workspace is `disabled`), as does dropping tabs into it from another tabset.
|
|
2015
|
+
* Clicking the selected tab of an expanded tabset (or pressing Enter or Space on it) collapses it, unless it's maximized or the workspace is `disabled`.
|
|
2016
|
+
*
|
|
2017
|
+
* ℹ️ Tabs dropped at an edge of the workspace that a collapsed tabset lines (e.g. a sidebar collapsed to a strip of tabs) are added to that tabset,
|
|
2018
|
+
* rather than beside all of the other tabsets (see `TabDropTarget`).
|
|
1960
2019
|
*
|
|
1961
2020
|
* ℹ️ The only tabset in a workspace (the root) can't be collapsed, and neither can a tabset whose siblings are all collapsed.
|
|
1962
2021
|
*
|
|
@@ -2344,8 +2403,8 @@ export declare type ValueOrFunction<Value, State> = Value | ((state: State) => V
|
|
|
2344
2403
|
* Workspaces are uncontrolled: provide an initial model with the `defaultModel` prop, save changes from the `onModelChanged` callback,
|
|
2345
2404
|
* and make changes using the imperative API (see `WorkspaceImperativeHandle`).
|
|
2346
2405
|
*
|
|
2347
|
-
* ℹ️ Tab content is not remounted when a tab is moved.
|
|
2348
|
-
*
|
|
2406
|
+
* ℹ️ Tab content is not remounted when a tab is moved, and its browser state (e.g. iframes, playing media, and focus) is preserved where possible;
|
|
2407
|
+
* browsers that don't support `moveBefore` (e.g. Safari) reset some of that state (e.g. iframes are reloaded).
|
|
2349
2408
|
*
|
|
2350
2409
|
* Workspace elements always include the following attributes:
|
|
2351
2410
|
*
|
|
@@ -2386,6 +2445,17 @@ export declare type WorkspaceChangedMeta = {
|
|
|
2386
2445
|
* ⚠️ New reasons may be added in later versions, so code that switches on this value should handle unrecognized values.
|
|
2387
2446
|
*/
|
|
2388
2447
|
reason: WorkspaceChangeReason;
|
|
2448
|
+
/**
|
|
2449
|
+
* For a tab (or tabset) dropped in from another workspace (`"transfer"` and `"copy"` changes reported by the workspace it was dropped into),
|
|
2450
|
+
* the `dragSourceInfo` prop of that workspace (see `DisableDropArgs.sourceInfo`), e.g. to migrate the tab's data from an older version of the application.
|
|
2451
|
+
* `undefined` otherwise.
|
|
2452
|
+
*/
|
|
2453
|
+
sourceInfo?: unknown;
|
|
2454
|
+
/**
|
|
2455
|
+
* For a tab (or tabset) dropped in from another workspace (`"transfer"` and `"copy"` changes reported by the workspace it was dropped into),
|
|
2456
|
+
* that workspace's id (see `DisableDropArgs.sourceWorkspaceId`). `undefined` otherwise.
|
|
2457
|
+
*/
|
|
2458
|
+
sourceWorkspaceId?: string | undefined;
|
|
2389
2459
|
};
|
|
2390
2460
|
|
|
2391
2461
|
/**
|
|
@@ -2399,37 +2469,57 @@ export declare type WorkspaceChangeReason = "add" | "close" | "collapse" | "copy
|
|
|
2399
2469
|
|
|
2400
2470
|
/**
|
|
2401
2471
|
* CSS class names for the elements a Workspace renders (see the Workspace's `classNames` prop).
|
|
2472
|
+
*
|
|
2473
|
+
* Entries for the elements of a tabset, tab, or split can be functions of it (and its state), e.g. to style tabsets by their `data`:
|
|
2474
|
+
*
|
|
2475
|
+
* ```tsx
|
|
2476
|
+
* classNames={{
|
|
2477
|
+
* header: (tabset) => (tabset.data?.compact ? "compact-header" : undefined),
|
|
2478
|
+
* tab: (tab, { isSelected }) => (tab.data.isDirty && !isSelected ? "dirty-tab" : undefined)
|
|
2479
|
+
* }}
|
|
2480
|
+
* ```
|
|
2481
|
+
*
|
|
2482
|
+
* ℹ️ Functions are called when the element renders (which, for tabs, includes when their tabset re-renders);
|
|
2483
|
+
* keep them cheap, and (like the rest of this object) define them outside of the component or memoize them.
|
|
2402
2484
|
*/
|
|
2403
|
-
export declare type WorkspaceClassNames = {
|
|
2485
|
+
export declare type WorkspaceClassNames<TabData = unknown, TabsetData = unknown> = {
|
|
2404
2486
|
dragPreview?: string | undefined;
|
|
2405
2487
|
dropIndicator?: string | undefined;
|
|
2406
2488
|
/**
|
|
2407
2489
|
* The element that positions each floating tabset (with a `data-floating-tabset` attribute, and a `data-tabset-collapsed` attribute while its tabset is collapsed), around the tabset itself, e.g. for a shadow.
|
|
2408
2490
|
*/
|
|
2409
|
-
floatingTabset?: string | undefined
|
|
2491
|
+
floatingTabset?: WorkspaceElementValue<string | undefined, [
|
|
2492
|
+
tabset: FloatingTabsetNode<TabData, TabsetData>,
|
|
2493
|
+
state: ParentTabsetState
|
|
2494
|
+
]> | undefined;
|
|
2410
2495
|
/**
|
|
2411
2496
|
* Each of the handles along the edges (and at the corners) of a floating tabset that resize it,
|
|
2412
2497
|
* with a `data-floating-resize-handle` attribute naming its edge (e.g. "bottom" or "bottom-right").
|
|
2413
2498
|
*
|
|
2414
2499
|
* ℹ️ The handles are positioned (and given resize cursors) by the workspace, but they're transparent.
|
|
2415
2500
|
*/
|
|
2416
|
-
floatingResizeHandle?: string | undefined
|
|
2417
|
-
|
|
2501
|
+
floatingResizeHandle?: WorkspaceElementValue<string | undefined, [
|
|
2502
|
+
tabset: FloatingTabsetNode<TabData, TabsetData>,
|
|
2503
|
+
state: ParentTabsetState
|
|
2504
|
+
]> | undefined;
|
|
2505
|
+
header?: TabsetElementValue<string | undefined, TabData, TabsetData>;
|
|
2418
2506
|
/**
|
|
2419
2507
|
* Each split (a Group with `data-split` and `data-split-id` attributes); for example, its `gap` adds space between tabsets.
|
|
2420
2508
|
*
|
|
2421
2509
|
* ℹ️ Gaps count toward the split's minimum size, like its separators.
|
|
2422
2510
|
*/
|
|
2423
|
-
split?: string | undefined
|
|
2424
|
-
|
|
2425
|
-
|
|
2426
|
-
|
|
2427
|
-
|
|
2428
|
-
|
|
2429
|
-
|
|
2511
|
+
split?: WorkspaceElementValue<string | undefined, [
|
|
2512
|
+
split: SplitNode<TabData, TabsetData>
|
|
2513
|
+
]> | undefined;
|
|
2514
|
+
tab?: TabElementValue<string | undefined, TabData>;
|
|
2515
|
+
tabContent?: TabElementValue<string | undefined, TabData>;
|
|
2516
|
+
tabList?: TabsetElementValue<string | undefined, TabData, TabsetData>;
|
|
2517
|
+
tabPanels?: TabsetElementValue<string | undefined, TabData, TabsetData>;
|
|
2518
|
+
tabset?: TabsetElementValue<string | undefined, TabData, TabsetData>;
|
|
2519
|
+
toolbar?: TabsetElementValue<string | undefined, TabData, TabsetData>;
|
|
2430
2520
|
};
|
|
2431
2521
|
|
|
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;
|
|
2522
|
+
declare function WorkspaceComponent<TabData = unknown, TabsetData = unknown>({ acceptExternalDrop, className, classNames, copyTab, copyTabset, defaultModel, disabled, disableDragBetweenApps, disableDrop, dragGroup, dragSourceInfo, elementRef: elementRefProp, hiddenTabBehavior, id: idProp, lazyTabContent, onBeforeModelChange, onModelChanged, onTearOff, renderDragPreview, renderEmptyTabset, renderSeparator, renderTab, renderTabContent, renderTabsetDragPreview, renderTabsetToolbar, resizePreviewMode, serverRenderTabContent, style, styles, tabPlacement, tabRemovalSelectionBehavior, tabsetMinHeight, tabsetMinWidth, workspaceRef, ...rest }: WorkspaceProps<TabData, TabsetData>): JSX.Element;
|
|
2433
2523
|
|
|
2434
2524
|
/**
|
|
2435
2525
|
* Edge of the workspace.
|
|
@@ -2438,6 +2528,11 @@ declare function WorkspaceComponent<TabData = unknown, TabsetData = unknown>({ a
|
|
|
2438
2528
|
*/
|
|
2439
2529
|
export declare type WorkspaceDropEdge = "bottom" | "left" | "right" | "top";
|
|
2440
2530
|
|
|
2531
|
+
/**
|
|
2532
|
+
* An entry of the Workspace's `classNames` or `styles` props: a value, or a function that returns one, given the node the element belongs to.
|
|
2533
|
+
*/
|
|
2534
|
+
export declare type WorkspaceElementValue<Value, Args extends unknown[]> = Value | ((...args: Args) => Value);
|
|
2535
|
+
|
|
2441
2536
|
/**
|
|
2442
2537
|
* Imperative Workspace API.
|
|
2443
2538
|
*
|
|
@@ -2447,20 +2542,30 @@ export declare type WorkspaceDropEdge = "bottom" | "left" | "right" | "top";
|
|
|
2447
2542
|
*/
|
|
2448
2543
|
export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData = unknown> {
|
|
2449
2544
|
/**
|
|
2450
|
-
* Add a tab to a tabset.
|
|
2545
|
+
* Add a tab to a tabset, or in a new tabset at any target `moveTab` accepts (e.g. in a new split below a tabset, or at an edge of the workspace).
|
|
2451
2546
|
*
|
|
2452
2547
|
* ℹ️ If a tab with the same id already exists, it is selected instead (and its data is not changed).
|
|
2453
2548
|
*
|
|
2549
|
+
* ℹ️ A tab added in a new tabset is that tabset's selected tab (so `select` doesn't apply); like a moved tab, it's added to a floating tabset rather than splitting it.
|
|
2550
|
+
*
|
|
2454
2551
|
* @param tab Tab to add
|
|
2455
2552
|
* @param options.tabsetId Tabset to add the tab to; defaults to the active tabset
|
|
2456
2553
|
* @param options.index Position within the tabset; defaults to the end
|
|
2457
2554
|
* @param options.select Select the new tab; defaults to true
|
|
2555
|
+
* @param options.target Where to add the tab (see `TabDropTarget`); takes precedence over `tabsetId` and `index`
|
|
2556
|
+
* @param options.size Size of the new tabset, when `target` creates one (an edge region of a tabset, or an edge of the workspace), as its share of the split it's in.
|
|
2557
|
+
* Numbers are percentages (as in the model, see `TabsetNode.size`); strings may have units (e.g. `"200px"`), and are converted to percentages of the split's current size.
|
|
2558
|
+
* For an edge region, the new tabset takes its space from the tabset it splits (so its siblings keep their sizes); if that tabset doesn't have enough room, its siblings shrink in proportion to their sizes instead.
|
|
2559
|
+
* Defaults to half of the tabset it splits; at an edge of the workspace, an equal share of the root split (if it's in the same direction), or else half of the workspace.
|
|
2560
|
+
* Invalid sizes (e.g. `NaN` or `"abc"`) are ignored, with a warning in development.
|
|
2458
2561
|
* @return `true` if the tab was added
|
|
2459
2562
|
*/
|
|
2460
2563
|
addTab: (tab: TabNode<TabData>, options?: {
|
|
2461
2564
|
index?: number | undefined;
|
|
2462
2565
|
select?: boolean | undefined;
|
|
2566
|
+
size?: number | string | undefined;
|
|
2463
2567
|
tabsetId?: string | undefined;
|
|
2568
|
+
target?: TabDropTarget | undefined;
|
|
2464
2569
|
}) => boolean;
|
|
2465
2570
|
/**
|
|
2466
2571
|
* Close a tab.
|
|
@@ -2573,6 +2678,28 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
|
|
|
2573
2678
|
* Floating tabsets can't be split, so a tabset moved to an edge region of one has its tabs moved into it instead (like the `"center"` region).
|
|
2574
2679
|
*/
|
|
2575
2680
|
moveTabset: (tabsetId: string, target: TabDropTarget) => void;
|
|
2681
|
+
/**
|
|
2682
|
+
* Set the sizes of a split's children (tabsets and splits) by id, e.g. to apply a saved preset without replacing the model.
|
|
2683
|
+
* Reported to `onModelChanged` with the `"resize"` reason.
|
|
2684
|
+
*
|
|
2685
|
+
* e.g. `resizeSplit("root", { sidebar: 30, main: 70 })` applies a 30/70 preset, and `resizeSplit("root", { sidebar: "250px" })` makes the sidebar 250 pixels wide (at the split's current size) and gives the rest to the other children.
|
|
2686
|
+
* The "Sizing tabsets" docs have examples.
|
|
2687
|
+
*
|
|
2688
|
+
* Numbers are percentages. Strings may have units (e.g. `"250px"`), which are converted to a percentage of the split's current size (like the `size` option of `addTab`);
|
|
2689
|
+
* like the model's sizes, they scale with the workspace afterwards (see `TabsetNode.size`). A size that can't be converted (e.g. the split isn't mounted) is stored as it is.
|
|
2690
|
+
* Children that aren't listed share what the others leave, in proportion to their current sizes.
|
|
2691
|
+
* Sizes are applied like the model's sizes are, e.g. limited by tabsets' minimum and maximum sizes.
|
|
2692
|
+
*
|
|
2693
|
+
* ℹ️ A collapsed tabset's size is the size it expands to; this doesn't collapse or expand tabsets (see `collapseTabset` and `expandTabset`).
|
|
2694
|
+
*
|
|
2695
|
+
* ⚠️ Splits that don't exist, ids that aren't children of the split, and invalid sizes (e.g. `NaN` or `"abc"`) are ignored, with a warning in development.
|
|
2696
|
+
*
|
|
2697
|
+
* @param splitId Id of the split (see `SplitNode.id`)
|
|
2698
|
+
* @param sizes Sizes of the split's children, by child id
|
|
2699
|
+
*/
|
|
2700
|
+
resizeSplit: (splitId: string, sizes: {
|
|
2701
|
+
[childId: string]: number | string;
|
|
2702
|
+
}) => void;
|
|
2576
2703
|
/**
|
|
2577
2704
|
* Restore the maximized tabset (if there is one).
|
|
2578
2705
|
*/
|
|
@@ -2760,7 +2887,7 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
|
|
|
2760
2887
|
* ℹ️ Like the render props, this object is part of what tabsets re-render for;
|
|
2761
2888
|
* in large workspaces, define it outside of the component (or memoize it) rather than inline.
|
|
2762
2889
|
*/
|
|
2763
|
-
classNames?: WorkspaceClassNames | undefined;
|
|
2890
|
+
classNames?: WorkspaceClassNames<TabData, TabsetData> | undefined;
|
|
2764
2891
|
/**
|
|
2765
2892
|
* Initial layout of the workspace.
|
|
2766
2893
|
*
|
|
@@ -2807,7 +2934,8 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
|
|
|
2807
2934
|
copyTabset?: ((tabset: TabsetNode<TabData, TabsetData>, copyTab: (tab: TabNode<TabData>) => TabNode<TabData>, target: TabDropTarget) => TabsetNode<TabData, TabsetData> | null | undefined) | undefined;
|
|
2808
2935
|
/**
|
|
2809
2936
|
* Locks the arrangement: tabs cannot be resized, dragged, dropped, or closed by the user.
|
|
2810
|
-
* Selecting tabs and maximizing tabsets still work
|
|
2937
|
+
* Selecting tabs and maximizing tabsets still work, but tabsets aren't collapsed or expanded by clicking their tabs (or the empty space in their headers);
|
|
2938
|
+
* clicking a tab of a collapsed tabset only selects it. A `TabsetCollapseButton` isn't restricted by `disabled`; to keep tabsets from being collapsed or expanded, don't render one.
|
|
2811
2939
|
*
|
|
2812
2940
|
* ℹ️ This prop overrides the `disableClose` and `disableDrag` flags of individual tabs.
|
|
2813
2941
|
*/
|
|
@@ -2832,6 +2960,7 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
|
|
|
2832
2960
|
* ℹ️ Tabs can also be dropped at the edges of the workspace (beside all of the other tabsets), within a few pixels of the edges of its layout
|
|
2833
2961
|
* (except over tabset headers, where the tab lists are) or within its root element's padding.
|
|
2834
2962
|
* These targets have an `edge` rather than a `tabsetId`; `disableDrop={({ target }) => "edge" in target}` turns them off.
|
|
2963
|
+
* (Where a collapsed tabset lines an edge, drops there are added to the end of its tab list, so those targets have an `index` and `tabsetId` instead.)
|
|
2835
2964
|
*/
|
|
2836
2965
|
disableDrop?: boolean | ((args: DisableDropArgs<TabData, TabsetData>) => boolean) | undefined;
|
|
2837
2966
|
/**
|
|
@@ -2852,12 +2981,22 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
|
|
|
2852
2981
|
* 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.
|
|
2853
2982
|
*/
|
|
2854
2983
|
dragGroup?: string | undefined;
|
|
2984
|
+
/**
|
|
2985
|
+
* Information about this workspace that's sent with the tabs (and tabsets) dragged from it (see the `dragGroup` prop),
|
|
2986
|
+
* so that the workspaces they're dragged into can tell where they came from (see `DisableDropArgs.sourceInfo` and `WorkspaceChangedMeta.sourceInfo`),
|
|
2987
|
+
* e.g. `{ app: "reports", schemaVersion: 3 }`.
|
|
2988
|
+
*
|
|
2989
|
+
* ⚠️ It's sent to other copies of the application with the structured clone algorithm (like tab data; see `dragGroup`), so it must be cloneable;
|
|
2990
|
+
* drags whose source info can't be cloned can only be dropped within their copy of the application.
|
|
2991
|
+
* It's read when a drag starts, so changes during a drag don't apply to it.
|
|
2992
|
+
*/
|
|
2993
|
+
dragSourceInfo?: unknown;
|
|
2855
2994
|
/**
|
|
2856
2995
|
* Ref attached to the root `HTMLDivElement`.
|
|
2857
2996
|
*/
|
|
2858
2997
|
elementRef?: Ref<HTMLDivElement | null> | undefined;
|
|
2859
2998
|
/**
|
|
2860
|
-
* What happens to the content of tabs that
|
|
2999
|
+
* What happens to the content of tabs that aren't visible, once it has been mounted (see `lazyTabContent`).
|
|
2861
3000
|
* Can be a function to choose per tab (e.g. based on its data).
|
|
2862
3001
|
*
|
|
2863
3002
|
* - `"keep-mounted"`: content stays mounted (and its effects keep running)
|
|
@@ -2865,10 +3004,15 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
|
|
|
2865
3004
|
* requires React 19.2 (falls back to `"keep-mounted"` otherwise)
|
|
2866
3005
|
* - `"unmount"`: content is unmounted
|
|
2867
3006
|
*
|
|
2868
|
-
* ℹ️
|
|
3007
|
+
* ℹ️ A tab is visible when it's selected, in a tabset that isn't collapsed or covered by a maximized tabset (floating tabsets aren't covered);
|
|
3008
|
+
* so e.g. collapsing a tabset hides its selected tab's content, and maximizing one hides the others'.
|
|
3009
|
+
* Temporary collapsed states (e.g. while dragging a separator, or when collapsed to fit) don't hide content.
|
|
2869
3010
|
*
|
|
2870
|
-
*
|
|
2871
|
-
*
|
|
3011
|
+
* ℹ️ Moving a tab never remounts its content (unless the move hides it and `hiddenTabBehavior` is `"unmount"`).
|
|
3012
|
+
*
|
|
3013
|
+
* ℹ️ Its React state is preserved, and where possible its elements are moved within the document using `moveBefore`, which preserves browser state (iframes aren't reloaded, playing media isn't paused, and focused elements stay focused).
|
|
3014
|
+
*
|
|
3015
|
+
* ⚠️ Browsers that don't support `moveBefore` (e.g. Safari) reset some of that state when a tab moves: iframes are reloaded, playing media is paused, and focused elements are blurred.
|
|
2872
3016
|
*
|
|
2873
3017
|
* @default "keep-mounted"
|
|
2874
3018
|
*/
|
|
@@ -2880,6 +3024,39 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
|
|
|
2880
3024
|
* ℹ️ This value will also be assigned to the `id` and `data-testid` attributes (an explicit `data-testid` prop will take precedence).
|
|
2881
3025
|
*/
|
|
2882
3026
|
id?: string | number | undefined;
|
|
3027
|
+
/**
|
|
3028
|
+
* Don't mount a tab's content until the tab is first visible (e.g. for expensive content in tabsets with many tabs, or in tabsets that start collapsed);
|
|
3029
|
+
* otherwise every tab's content is mounted along with the workspace.
|
|
3030
|
+
* Can be a function to choose per tab (e.g. based on its data), e.g. `(tab) => tab.data.isExpensive`.
|
|
3031
|
+
*
|
|
3032
|
+
* Once mounted, content that isn't visible is kept mounted, hidden in an `Activity`, or unmounted, as `hiddenTabBehavior` says.
|
|
3033
|
+
*
|
|
3034
|
+
* ℹ️ A tab is visible when it's selected, in a tabset that isn't collapsed or covered by a maximized tabset (floating tabsets aren't covered).
|
|
3035
|
+
*
|
|
3036
|
+
* @default false
|
|
3037
|
+
*/
|
|
3038
|
+
lazyTabContent?: boolean | ((tab: TabNode<TabData>) => boolean) | undefined;
|
|
3039
|
+
/**
|
|
3040
|
+
* Called before a change the user makes (e.g. closing a tab, or dropping a tab that was dragged) is applied to the model;
|
|
3041
|
+
* return `false` to block it, which leaves the model as it is (and `onModelChanged` isn't called).
|
|
3042
|
+
*
|
|
3043
|
+
* e.g. to lock the layout while only allowing some interactions (selecting a tab in a collapsed tabset is an "expand" change, and pressing a floating tabset is a "raise" change):
|
|
3044
|
+
* `onBeforeModelChange={({ reason }) => !isLocked || ["select", "expand", "raise", "maximize", "restore"].includes(reason)}`
|
|
3045
|
+
*
|
|
3046
|
+
* Or to keep tabs with unsaved changes from being closed (however they're closed, e.g. with their close buttons or the Delete key):
|
|
3047
|
+
* `onBeforeModelChange={({ reason, removedTabs }) => reason !== "close" || !removedTabs.some((tab) => tab.data.isDirty)}`
|
|
3048
|
+
*
|
|
3049
|
+
* ℹ️ It's called synchronously; to ask the user first (e.g. "Save changes before closing?"), block the change and then make it with the imperative API (e.g. `closeTab`) if they confirm.
|
|
3050
|
+
*
|
|
3051
|
+
* ℹ️ Changes made with the imperative API (including the handles returned by hooks like `useParentTab`, e.g. from a custom close button) aren't passed to it, since the application makes those itself.
|
|
3052
|
+
* Neither is the removal of a tab (or tabset) that another workspace has accepted (see the `dragGroup` prop), or one that was torn off (see `onTearOff`),
|
|
3053
|
+
* since it has already been added elsewhere; use `disableDrop` (or the `disableDrag` flags) to keep tabs from being dragged out instead.
|
|
3054
|
+
* A workspace that a tab is dropped into can block the drop, in which case it stays in the workspace it was dragged from.
|
|
3055
|
+
*
|
|
3056
|
+
* ℹ️ Blocked resizes are undone (e.g. a separator dragged by the user moves back). Drops are blocked when the pointer is released,
|
|
3057
|
+
* so use `disableDrop` to show while dragging that a target doesn't accept drops.
|
|
3058
|
+
*/
|
|
3059
|
+
onBeforeModelChange?: ((args: BeforeModelChangeArgs<TabData, TabsetData>) => boolean | void) | undefined;
|
|
2883
3060
|
/**
|
|
2884
3061
|
* Called after the model has changed (e.g. a tab was moved, selected, or closed, or a tabset was resized).
|
|
2885
3062
|
*
|
|
@@ -3008,7 +3185,7 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
|
|
|
3008
3185
|
/**
|
|
3009
3186
|
* CSS properties for the elements the workspace renders within its root element (see `classNames`).
|
|
3010
3187
|
*/
|
|
3011
|
-
styles?: WorkspaceStyles | undefined;
|
|
3188
|
+
styles?: WorkspaceStyles<TabData, TabsetData> | undefined;
|
|
3012
3189
|
/**
|
|
3013
3190
|
* Where tabs are placed relative to tab content.
|
|
3014
3191
|
*
|
|
@@ -3067,10 +3244,36 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
|
|
|
3067
3244
|
};
|
|
3068
3245
|
|
|
3069
3246
|
/**
|
|
3070
|
-
* CSS properties for the elements a Workspace renders (see the Workspace's `classNames` prop)
|
|
3247
|
+
* CSS properties for the elements a Workspace renders (see the Workspace's `classNames` prop);
|
|
3248
|
+
* like class names, entries for the elements of a tabset, tab, or split can be functions of it (and its state).
|
|
3249
|
+
*
|
|
3250
|
+
* ```tsx
|
|
3251
|
+
* styles={{
|
|
3252
|
+
* tabset: (tabset) => ({ "--accent": tabset.data?.accent } as CSSProperties)
|
|
3253
|
+
* }}
|
|
3254
|
+
* ```
|
|
3071
3255
|
*/
|
|
3072
|
-
export declare type WorkspaceStyles = {
|
|
3073
|
-
|
|
3256
|
+
export declare type WorkspaceStyles<TabData = unknown, TabsetData = unknown> = {
|
|
3257
|
+
dragPreview?: CSSProperties | undefined;
|
|
3258
|
+
dropIndicator?: CSSProperties | undefined;
|
|
3259
|
+
floatingTabset?: WorkspaceElementValue<CSSProperties | undefined, [
|
|
3260
|
+
tabset: FloatingTabsetNode<TabData, TabsetData>,
|
|
3261
|
+
state: ParentTabsetState
|
|
3262
|
+
]> | undefined;
|
|
3263
|
+
floatingResizeHandle?: WorkspaceElementValue<CSSProperties | undefined, [
|
|
3264
|
+
tabset: FloatingTabsetNode<TabData, TabsetData>,
|
|
3265
|
+
state: ParentTabsetState
|
|
3266
|
+
]> | undefined;
|
|
3267
|
+
header?: TabsetElementValue<CSSProperties | undefined, TabData, TabsetData>;
|
|
3268
|
+
split?: WorkspaceElementValue<CSSProperties | undefined, [
|
|
3269
|
+
split: SplitNode<TabData, TabsetData>
|
|
3270
|
+
]> | undefined;
|
|
3271
|
+
tab?: TabElementValue<CSSProperties | undefined, TabData>;
|
|
3272
|
+
tabContent?: TabElementValue<CSSProperties | undefined, TabData>;
|
|
3273
|
+
tabList?: TabsetElementValue<CSSProperties | undefined, TabData, TabsetData>;
|
|
3274
|
+
tabPanels?: TabsetElementValue<CSSProperties | undefined, TabData, TabsetData>;
|
|
3275
|
+
tabset?: TabsetElementValue<CSSProperties | undefined, TabData, TabsetData>;
|
|
3276
|
+
toolbar?: TabsetElementValue<CSSProperties | undefined, TabData, TabsetData>;
|
|
3074
3277
|
};
|
|
3075
3278
|
|
|
3076
3279
|
export { }
|