react-resizable-panels 4.15.2 → 4.16.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.
|
@@ -1,9 +1,11 @@
|
|
|
1
|
+
import { ButtonHTMLAttributes } from 'react';
|
|
1
2
|
import { CSSProperties } from 'react';
|
|
2
3
|
import { Dispatch } from 'react';
|
|
3
4
|
import { HTMLAttributes } from 'react';
|
|
4
5
|
import { JSX } from 'react/jsx-runtime';
|
|
5
6
|
import { ReactNode } from 'react';
|
|
6
7
|
import { Ref } from 'react';
|
|
8
|
+
import { RefCallback } from 'react';
|
|
7
9
|
import { RefObject } from 'react';
|
|
8
10
|
import { SetStateAction } from 'react';
|
|
9
11
|
|
|
@@ -55,11 +57,11 @@ declare type BaseSeparatorAttributes = Omit<HTMLAttributes<HTMLDivElement>, "rol
|
|
|
55
57
|
*
|
|
56
58
|
* ⚠️ Cell elements must be direct DOM children of their parent Grid elements.
|
|
57
59
|
*/
|
|
58
|
-
export declare
|
|
60
|
+
export declare const Cell: typeof CellComponent & {
|
|
61
|
+
displayName: string;
|
|
62
|
+
};
|
|
59
63
|
|
|
60
|
-
|
|
61
|
-
var displayName: string;
|
|
62
|
-
}
|
|
64
|
+
declare function CellComponent({ children, className, column, columnSpan, elementRef: elementRefProp, id: idProp, row, rowSpan, style, ...rest }: CellProps): JSX.Element;
|
|
63
65
|
|
|
64
66
|
export declare type CellProps = HTMLAttributes<HTMLDivElement> & {
|
|
65
67
|
/**
|
|
@@ -76,6 +78,8 @@ export declare type CellProps = HTMLAttributes<HTMLDivElement> & {
|
|
|
76
78
|
column: number;
|
|
77
79
|
/**
|
|
78
80
|
* Number of columns this cell spans; defaults to 1.
|
|
81
|
+
*
|
|
82
|
+
* @default 1
|
|
79
83
|
*/
|
|
80
84
|
columnSpan?: number | undefined;
|
|
81
85
|
/**
|
|
@@ -95,6 +99,8 @@ export declare type CellProps = HTMLAttributes<HTMLDivElement> & {
|
|
|
95
99
|
row: number;
|
|
96
100
|
/**
|
|
97
101
|
* Number of rows this cell spans; defaults to 1.
|
|
102
|
+
*
|
|
103
|
+
* @default 1
|
|
98
104
|
*/
|
|
99
105
|
rowSpan?: number | undefined;
|
|
100
106
|
/**
|
|
@@ -105,6 +111,12 @@ export declare type CellProps = HTMLAttributes<HTMLDivElement> & {
|
|
|
105
111
|
style?: CSSProperties | undefined;
|
|
106
112
|
};
|
|
107
113
|
|
|
114
|
+
export declare type DisableDropArgs<TabData = unknown, TabsetData = unknown> = {
|
|
115
|
+
model: WorkspaceModel<TabData, TabsetData>;
|
|
116
|
+
tab: TabNode<TabData>;
|
|
117
|
+
target: TabDropTarget;
|
|
118
|
+
};
|
|
119
|
+
|
|
108
120
|
/**
|
|
109
121
|
* A Grid arranges resizable Cells in two dimensions.
|
|
110
122
|
* Columns can be resized horizontally and rows can be resized vertically;
|
|
@@ -124,11 +136,9 @@ export declare type CellProps = HTMLAttributes<HTMLDivElement> & {
|
|
|
124
136
|
*
|
|
125
137
|
* ℹ️ [Test id](https://testing-library.com/docs/queries/bytestid/) can be used to narrow selection when unit testing.
|
|
126
138
|
*/
|
|
127
|
-
export declare
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
var displayName: string;
|
|
131
|
-
}
|
|
139
|
+
export declare const Grid: typeof GridComponent & {
|
|
140
|
+
displayName: string;
|
|
141
|
+
};
|
|
132
142
|
|
|
133
143
|
/**
|
|
134
144
|
* A Grid has two independently resizable axes:
|
|
@@ -137,6 +147,8 @@ export declare namespace Grid {
|
|
|
137
147
|
*/
|
|
138
148
|
export declare type GridAxis = "column" | "row";
|
|
139
149
|
|
|
150
|
+
declare function GridComponent({ children, className, columns, defaultLayout, disableCursor, disabled, elementRef: elementRefProp, gridRef, id: idProp, onLayoutChange: onLayoutChangeUnstable, onLayoutChanged: onLayoutChangedUnstable, resizeTargetMinimumSize, rows, style, ...rest }: GridProps): JSX.Element;
|
|
151
|
+
|
|
140
152
|
/**
|
|
141
153
|
* Imperative Grid API.
|
|
142
154
|
*
|
|
@@ -257,11 +269,11 @@ export declare type GridLayout = {
|
|
|
257
269
|
*
|
|
258
270
|
* ℹ️ Gridlines rendered by another component (rather than directly within the Grid) aren't detected until they mount, so server-rendered layouts may shift slightly during hydration.
|
|
259
271
|
*/
|
|
260
|
-
export declare
|
|
272
|
+
export declare const Gridline: typeof GridlineComponent & {
|
|
273
|
+
displayName: string;
|
|
274
|
+
};
|
|
261
275
|
|
|
262
|
-
|
|
263
|
-
var displayName: string;
|
|
264
|
-
}
|
|
276
|
+
declare function GridlineComponent(props: GridlineProps): JSX.Element;
|
|
265
277
|
|
|
266
278
|
export declare type GridlineProps = BaseGridlineProps & ({
|
|
267
279
|
/**
|
|
@@ -379,6 +391,8 @@ export declare type GridProps = HTMLAttributes<HTMLDivElement> & {
|
|
|
379
391
|
* This threshold ensures targets are large enough to avoid mis-clicks.
|
|
380
392
|
*
|
|
381
393
|
* ℹ️ Refer to the `Group` prop of the same name for more information.
|
|
394
|
+
*
|
|
395
|
+
* @default { coarse: 20, fine: 10 }
|
|
382
396
|
*/
|
|
383
397
|
resizeTargetMinimumSize?: {
|
|
384
398
|
coarse: number;
|
|
@@ -480,11 +494,11 @@ export declare type GridTrackProps = PanelConstraintProps & {
|
|
|
480
494
|
*
|
|
481
495
|
* ℹ️ [Test id](https://testing-library.com/docs/queries/bytestid/) can be used to narrow selection when unit testing.
|
|
482
496
|
*/
|
|
483
|
-
export declare
|
|
497
|
+
export declare const Group: typeof GroupComponent & {
|
|
498
|
+
displayName: string;
|
|
499
|
+
};
|
|
484
500
|
|
|
485
|
-
|
|
486
|
-
var displayName: string;
|
|
487
|
-
}
|
|
501
|
+
declare function GroupComponent({ children, className, defaultLayout, disableCursor, disabled, elementRef: elementRefProp, groupRef, id: idProp, onLayoutChange: onLayoutChangeUnstable, onLayoutChanged: onLayoutChangedUnstable, orientation, resizePreviewMode, resizeTargetMinimumSize, style, ...rest }: GroupProps): JSX.Element;
|
|
488
502
|
|
|
489
503
|
/**
|
|
490
504
|
* Imperative Group API.
|
|
@@ -585,6 +599,8 @@ export declare type GroupProps = HTMLAttributes<HTMLDivElement> & {
|
|
|
585
599
|
* Defaults to `"panel"` (immediate resizing); `"separator"` defers resizing until release.
|
|
586
600
|
*
|
|
587
601
|
* Customize previews using the `SeparatorOverlay` component.
|
|
602
|
+
*
|
|
603
|
+
* @default "panel"
|
|
588
604
|
*/
|
|
589
605
|
resizePreviewMode?: ResizePreviewMode | undefined;
|
|
590
606
|
/**
|
|
@@ -597,6 +613,8 @@ export declare type GroupProps = HTMLAttributes<HTMLDivElement> & {
|
|
|
597
613
|
*
|
|
598
614
|
* ℹ️ [Apple interface guidelines](https://developer.apple.com/design/human-interface-guidelines/accessibility) suggest `20pt` (`27px`) on desktops and `28pt` (`37px`) for touch devices.
|
|
599
615
|
* In practice this seems to be much larger than many of their own applications use though.
|
|
616
|
+
*
|
|
617
|
+
* @default { coarse: 20, fine: 10 }
|
|
600
618
|
*/
|
|
601
619
|
resizeTargetMinimumSize?: {
|
|
602
620
|
coarse: number;
|
|
@@ -604,6 +622,8 @@ export declare type GroupProps = HTMLAttributes<HTMLDivElement> & {
|
|
|
604
622
|
};
|
|
605
623
|
/**
|
|
606
624
|
* Specifies the resizable orientation ("horizontal" or "vertical"); defaults to "horizontal"
|
|
625
|
+
*
|
|
626
|
+
* @default "horizontal"
|
|
607
627
|
*/
|
|
608
628
|
orientation?: "horizontal" | "vertical" | undefined;
|
|
609
629
|
/**
|
|
@@ -614,6 +634,15 @@ export declare type GroupProps = HTMLAttributes<HTMLDivElement> & {
|
|
|
614
634
|
style?: CSSProperties | undefined;
|
|
615
635
|
};
|
|
616
636
|
|
|
637
|
+
/**
|
|
638
|
+
* What happens to the content of tabs that are not selected:
|
|
639
|
+
* - `"keep-mounted"`: content stays mounted (and its effects keep running)
|
|
640
|
+
* - `"activity"`: content stays mounted but is rendered within a hidden React `<Activity>` boundary, so its effects are unmounted;
|
|
641
|
+
* requires React 19.2 (falls back to `"keep-mounted"` otherwise)
|
|
642
|
+
* - `"unmount"`: content is unmounted
|
|
643
|
+
*/
|
|
644
|
+
export declare type HiddenTabBehavior = "activity" | "keep-mounted" | "unmount";
|
|
645
|
+
|
|
617
646
|
/**
|
|
618
647
|
* Caches and returns matchMedia()'s computed value for "pointer:coarse"
|
|
619
648
|
*/
|
|
@@ -696,11 +725,11 @@ export declare type Orientation = "horizontal" | "vertical";
|
|
|
696
725
|
*
|
|
697
726
|
* ⚠️ Panel elements must be direct DOM children of their parent Group elements.
|
|
698
727
|
*/
|
|
699
|
-
export declare
|
|
728
|
+
export declare const Panel: typeof PanelComponent & {
|
|
729
|
+
displayName: string;
|
|
730
|
+
};
|
|
700
731
|
|
|
701
|
-
|
|
702
|
-
var displayName: string;
|
|
703
|
-
}
|
|
732
|
+
declare function PanelComponent({ children, className, collapsedSize, collapsedThreshold, collapsible, defaultSize, disabled, elementRef: elementRefProp, groupResizeBehavior, id: idProp, maxSize, minSize, onResize: onResizeUnstable, panelRef, style, ...rest }: PanelProps): JSX.Element;
|
|
704
733
|
|
|
705
734
|
/**
|
|
706
735
|
* Size constraints may be specified in a variety of ways:
|
|
@@ -781,6 +810,8 @@ export declare type PanelProps = BasePanelAttributes & {
|
|
|
781
810
|
className?: string | undefined;
|
|
782
811
|
/**
|
|
783
812
|
* Panel size when collapsed; defaults to 0%.
|
|
813
|
+
*
|
|
814
|
+
* @default "0%"
|
|
784
815
|
*/
|
|
785
816
|
collapsedSize?: number | string | undefined;
|
|
786
817
|
/**
|
|
@@ -801,6 +832,8 @@ export declare type PanelProps = BasePanelAttributes & {
|
|
|
801
832
|
* This panel can be collapsed.
|
|
802
833
|
*
|
|
803
834
|
* ℹ️ A collapsible panel will collapse when its size is less than the specified `minSize`
|
|
835
|
+
*
|
|
836
|
+
* @default false
|
|
804
837
|
*/
|
|
805
838
|
collapsible?: boolean | undefined;
|
|
806
839
|
/**
|
|
@@ -833,6 +866,8 @@ export declare type PanelProps = BasePanelAttributes & {
|
|
|
833
866
|
* ℹ️ Panel min/max size constraints may impact this behavior.
|
|
834
867
|
*
|
|
835
868
|
* ⚠️ A Group must contain at least one Panel with `preserve-relative-size` resize behavior.
|
|
869
|
+
*
|
|
870
|
+
* @default "preserve-relative-size"
|
|
836
871
|
*/
|
|
837
872
|
groupResizeBehavior?: "preserve-relative-size" | "preserve-pixel-size" | undefined;
|
|
838
873
|
/**
|
|
@@ -851,6 +886,8 @@ export declare type PanelProps = BasePanelAttributes & {
|
|
|
851
886
|
* - Numbers are interpreted as pixels (e.g. `maxSize={200}` is 200 pixels)
|
|
852
887
|
* - Strings without explicit units are interpreted as percentage (e.g. `maxSize="50"` is 50 percent)
|
|
853
888
|
* - Use explicit units (e.g. "px", "%", "em", "rem", "vh", or "vw") to change interpretation
|
|
889
|
+
*
|
|
890
|
+
* @default "100%"
|
|
854
891
|
*/
|
|
855
892
|
maxSize?: number | string | undefined;
|
|
856
893
|
/**
|
|
@@ -860,6 +897,8 @@ export declare type PanelProps = BasePanelAttributes & {
|
|
|
860
897
|
* - Numbers are interpreted as pixels (e.g. `minSize={200}` is 200 pixels)
|
|
861
898
|
* - Strings without explicit units are interpreted as percentage (e.g. `minSize="50"` is 50 percent)
|
|
862
899
|
* - Use explicit units (e.g. "px", "%", "em", "rem", "vh", or "vw") to change interpretation
|
|
900
|
+
*
|
|
901
|
+
* @default "0%"
|
|
863
902
|
*/
|
|
864
903
|
minSize?: number | string | undefined;
|
|
865
904
|
/**
|
|
@@ -932,6 +971,149 @@ export declare type ParentPanel = PanelImperativeHandle & {
|
|
|
932
971
|
id: string;
|
|
933
972
|
};
|
|
934
973
|
|
|
974
|
+
/**
|
|
975
|
+
* The nearest ancestor tab (returned by `useParentTab`).
|
|
976
|
+
*
|
|
977
|
+
* ℹ️ This value does not change for the life of the tab, so it is safe to use as an effect dependency.
|
|
978
|
+
* Use `useParentTabState` for values that should trigger a re-render.
|
|
979
|
+
*/
|
|
980
|
+
export declare type ParentTab = {
|
|
981
|
+
/**
|
|
982
|
+
* Close the tab.
|
|
983
|
+
*
|
|
984
|
+
* ℹ️ This method is not restricted by `disableClose` or `disabled`.
|
|
985
|
+
*/
|
|
986
|
+
close: () => void;
|
|
987
|
+
/**
|
|
988
|
+
* Id of the tabset that currently contains the tab.
|
|
989
|
+
*/
|
|
990
|
+
getTabsetId: () => string;
|
|
991
|
+
/**
|
|
992
|
+
* Id of the tab.
|
|
993
|
+
*/
|
|
994
|
+
id: string;
|
|
995
|
+
/**
|
|
996
|
+
* The tab is selected within its tabset.
|
|
997
|
+
*/
|
|
998
|
+
isSelected: () => boolean;
|
|
999
|
+
/**
|
|
1000
|
+
* Select the tab.
|
|
1001
|
+
*/
|
|
1002
|
+
select: () => void;
|
|
1003
|
+
/**
|
|
1004
|
+
* Id of the Workspace that contains the tab.
|
|
1005
|
+
*/
|
|
1006
|
+
workspaceId: string;
|
|
1007
|
+
};
|
|
1008
|
+
|
|
1009
|
+
/**
|
|
1010
|
+
* The nearest ancestor tabset (returned by `useParentTabset`).
|
|
1011
|
+
*
|
|
1012
|
+
* ℹ️ This value does not change for the life of the tabset, so it is safe to use as an effect dependency.
|
|
1013
|
+
* Use `useParentTabsetState` for values that should trigger a re-render.
|
|
1014
|
+
*/
|
|
1015
|
+
export declare type ParentTabset<TabData = unknown> = {
|
|
1016
|
+
/**
|
|
1017
|
+
* Add a tab to this tabset.
|
|
1018
|
+
*
|
|
1019
|
+
* @return `true` if the tab was added (see `WorkspaceImperativeHandle.addTab`)
|
|
1020
|
+
*/
|
|
1021
|
+
addTab: (tab: TabNode<TabData>, options?: {
|
|
1022
|
+
index?: number | undefined;
|
|
1023
|
+
select?: boolean | undefined;
|
|
1024
|
+
}) => boolean;
|
|
1025
|
+
/**
|
|
1026
|
+
* Close the tabset, along with any tabs it contains (see `WorkspaceImperativeHandle.closeTabset`).
|
|
1027
|
+
*/
|
|
1028
|
+
close: () => void;
|
|
1029
|
+
/**
|
|
1030
|
+
* Id of the tabset.
|
|
1031
|
+
*/
|
|
1032
|
+
id: string;
|
|
1033
|
+
/**
|
|
1034
|
+
* The tabset is currently maximized.
|
|
1035
|
+
*/
|
|
1036
|
+
isMaximized: () => boolean;
|
|
1037
|
+
/**
|
|
1038
|
+
* Maximize the tabset.
|
|
1039
|
+
*
|
|
1040
|
+
* ℹ️ This has no effect on the only tabset in a workspace (see `ParentTabsetState.isRoot`).
|
|
1041
|
+
*/
|
|
1042
|
+
maximize: () => void;
|
|
1043
|
+
/**
|
|
1044
|
+
* Restore the tabset if it is maximized.
|
|
1045
|
+
*/
|
|
1046
|
+
restore: () => void;
|
|
1047
|
+
/**
|
|
1048
|
+
* Id of the Workspace that contains the tabset.
|
|
1049
|
+
*/
|
|
1050
|
+
workspaceId: string;
|
|
1051
|
+
};
|
|
1052
|
+
|
|
1053
|
+
/**
|
|
1054
|
+
* State of the nearest ancestor tabset (returned by `useParentTabsetState`).
|
|
1055
|
+
*/
|
|
1056
|
+
export declare type ParentTabsetState = {
|
|
1057
|
+
/**
|
|
1058
|
+
* The user most recently interacted with this tabset (by pointer or focus).
|
|
1059
|
+
*/
|
|
1060
|
+
isActive: boolean;
|
|
1061
|
+
/**
|
|
1062
|
+
* The tabset is maximized.
|
|
1063
|
+
*/
|
|
1064
|
+
isMaximized: boolean;
|
|
1065
|
+
/**
|
|
1066
|
+
* The tabset is the root of the model, so it's the only tabset in the workspace.
|
|
1067
|
+
*
|
|
1068
|
+
* ℹ️ Some controls aren't useful for the only tabset (e.g. maximizing it), so this can be used to hide them.
|
|
1069
|
+
*/
|
|
1070
|
+
isRoot: boolean;
|
|
1071
|
+
/**
|
|
1072
|
+
* Id of the selected tab.
|
|
1073
|
+
*/
|
|
1074
|
+
selectedTabId: string | undefined;
|
|
1075
|
+
};
|
|
1076
|
+
|
|
1077
|
+
/**
|
|
1078
|
+
* State of the nearest ancestor tab (returned by `useParentTabState`).
|
|
1079
|
+
*/
|
|
1080
|
+
export declare type ParentTabState = {
|
|
1081
|
+
/**
|
|
1082
|
+
* The user cannot close the tab (because of its `disableClose` flag or the Workspace's `disabled` prop).
|
|
1083
|
+
*/
|
|
1084
|
+
isCloseDisabled: boolean;
|
|
1085
|
+
/**
|
|
1086
|
+
* The user cannot drag the tab (because of its `disableDrag` flag or the Workspace's `disabled` prop).
|
|
1087
|
+
*/
|
|
1088
|
+
isDragDisabled: boolean;
|
|
1089
|
+
/**
|
|
1090
|
+
* The tab is selected within its tabset.
|
|
1091
|
+
*
|
|
1092
|
+
* ℹ️ This is true even if the tabset is covered by another, maximized tabset.
|
|
1093
|
+
*/
|
|
1094
|
+
isSelected: boolean;
|
|
1095
|
+
/**
|
|
1096
|
+
* The tab is selected, and its tabset is not covered by another, maximized tabset.
|
|
1097
|
+
*
|
|
1098
|
+
* ⚠️ This value does not account for the Workspace itself being hidden.
|
|
1099
|
+
*/
|
|
1100
|
+
isVisible: boolean;
|
|
1101
|
+
/**
|
|
1102
|
+
* Id of the tabset that currently contains the tab.
|
|
1103
|
+
*/
|
|
1104
|
+
tabsetId: string;
|
|
1105
|
+
};
|
|
1106
|
+
|
|
1107
|
+
/**
|
|
1108
|
+
* The nearest ancestor Workspace (returned by `useParentWorkspace`), including its imperative API.
|
|
1109
|
+
*/
|
|
1110
|
+
export declare type ParentWorkspace<TabData = unknown, TabsetData = unknown> = WorkspaceImperativeHandle<TabData, TabsetData> & {
|
|
1111
|
+
/**
|
|
1112
|
+
* Id of the Workspace.
|
|
1113
|
+
*/
|
|
1114
|
+
id: string;
|
|
1115
|
+
};
|
|
1116
|
+
|
|
935
1117
|
declare type ResizePreviewMode = "panel" | "separator";
|
|
936
1118
|
|
|
937
1119
|
/**
|
|
@@ -949,11 +1131,11 @@ declare type ResizePreviewMode = "panel" | "separator";
|
|
|
949
1131
|
*
|
|
950
1132
|
* ℹ️ In addition to the attributes shown above, separator also renders all required [WAI-ARIA properties](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role#associated_wai-aria_roles_states_and_properties).
|
|
951
1133
|
*/
|
|
952
|
-
export declare
|
|
1134
|
+
export declare const Separator: typeof SeparatorComponent & {
|
|
1135
|
+
displayName: string;
|
|
1136
|
+
};
|
|
953
1137
|
|
|
954
|
-
|
|
955
|
-
var displayName: string;
|
|
956
|
-
}
|
|
1138
|
+
declare function SeparatorComponent({ children, className, disabled, disableDoubleClick, elementRef, id: idProp, preview, style, ...rest }: SeparatorProps): JSX.Element;
|
|
957
1139
|
|
|
958
1140
|
/**
|
|
959
1141
|
* Customizes separator previews when resizePreviewMode is "separator".
|
|
@@ -964,11 +1146,11 @@ export declare namespace Separator {
|
|
|
964
1146
|
*
|
|
965
1147
|
* Set `width` (horizontal groups) or `height` (vertical groups) using `style` or `className`.
|
|
966
1148
|
*/
|
|
967
|
-
export declare
|
|
1149
|
+
export declare const SeparatorOverlay: typeof SeparatorOverlayComponent & {
|
|
1150
|
+
displayName: string;
|
|
1151
|
+
};
|
|
968
1152
|
|
|
969
|
-
|
|
970
|
-
var displayName: string;
|
|
971
|
-
}
|
|
1153
|
+
declare function SeparatorOverlayComponent(props: SeparatorOverlayProps): null;
|
|
972
1154
|
|
|
973
1155
|
export declare type SeparatorOverlayProps = HTMLAttributes<HTMLDivElement>;
|
|
974
1156
|
|
|
@@ -1019,6 +1201,230 @@ export declare type SeparatorProps = BaseSeparatorAttributes & {
|
|
|
1019
1201
|
|
|
1020
1202
|
export declare type SizeUnit = "px" | "%" | "em" | "rem" | "vh" | "vw";
|
|
1021
1203
|
|
|
1204
|
+
/**
|
|
1205
|
+
* Lays out its children side by side (horizontally) or stacked (vertically), with resizable separators between them.
|
|
1206
|
+
*/
|
|
1207
|
+
export declare type SplitNode<TabData = unknown, TabsetData = unknown> = {
|
|
1208
|
+
/**
|
|
1209
|
+
* Distinguishes splits from tabsets.
|
|
1210
|
+
*/
|
|
1211
|
+
type: "split";
|
|
1212
|
+
/**
|
|
1213
|
+
* Uniquely identifies the split within the workspace.
|
|
1214
|
+
*
|
|
1215
|
+
* ℹ️ Optional in the `defaultModel` prop and the `setModel` method; splits without ids are assigned ids based on their position (e.g. "split-root").
|
|
1216
|
+
*/
|
|
1217
|
+
id: string;
|
|
1218
|
+
/**
|
|
1219
|
+
* Children are laid out side by side ("horizontal") or stacked ("vertical").
|
|
1220
|
+
*/
|
|
1221
|
+
orientation: Orientation;
|
|
1222
|
+
/**
|
|
1223
|
+
* Size of the split within its parent split.
|
|
1224
|
+
*
|
|
1225
|
+
* ℹ️ Interpretation rules:
|
|
1226
|
+
* - Numbers are percentages of the parent split (e.g. `size: 25` is 25 percent)
|
|
1227
|
+
* - Strings may specify other units (e.g. `size: "250px"`); strings without units are percentages
|
|
1228
|
+
* - Siblings without a size share the remaining space evenly
|
|
1229
|
+
*
|
|
1230
|
+
* ⚠️ String sizes are only initial sizes: they're converted to percentages when the user resizes the split,
|
|
1231
|
+
* and (like percentages) they scale with the workspace when it's resized.
|
|
1232
|
+
*/
|
|
1233
|
+
size?: number | string | undefined;
|
|
1234
|
+
/**
|
|
1235
|
+
* Tabsets and nested splits, in the order they are shown.
|
|
1236
|
+
*/
|
|
1237
|
+
children: WorkspaceNode<TabData, TabsetData>[];
|
|
1238
|
+
};
|
|
1239
|
+
|
|
1240
|
+
export declare type SplitNodeInput<TabData = unknown, TabsetData = unknown> = Omit<SplitNode<TabData, TabsetData>, "children" | "id"> & {
|
|
1241
|
+
children: WorkspaceNodeInput<TabData, TabsetData>[];
|
|
1242
|
+
id?: string | undefined;
|
|
1243
|
+
};
|
|
1244
|
+
|
|
1245
|
+
/**
|
|
1246
|
+
* Closes the tab it is rendered within; render it within the element returned by the Workspace's `renderTab` prop:
|
|
1247
|
+
*
|
|
1248
|
+
* ```tsx
|
|
1249
|
+
* renderTab={(tab, props) => (
|
|
1250
|
+
* <div {...props}>
|
|
1251
|
+
* {tab.title}
|
|
1252
|
+
* <TabCloseButton />
|
|
1253
|
+
* </div>
|
|
1254
|
+
* )}
|
|
1255
|
+
* ```
|
|
1256
|
+
*
|
|
1257
|
+
* The button renders nothing if closing is disabled (by the tab's `disableClose` flag or the Workspace's `disabled` prop).
|
|
1258
|
+
* Its default `aria-label` is "Close" followed by the tab's title (or id).
|
|
1259
|
+
*
|
|
1260
|
+
* To keep the tab open (e.g. to confirm unsaved changes first), call `event.preventDefault()` in an `onClick` handler:
|
|
1261
|
+
*
|
|
1262
|
+
* ```tsx
|
|
1263
|
+
* <TabCloseButton
|
|
1264
|
+
* onClick={(event) => {
|
|
1265
|
+
* if (hasUnsavedChanges && !confirm("Discard unsaved changes?")) {
|
|
1266
|
+
* event.preventDefault();
|
|
1267
|
+
* }
|
|
1268
|
+
* }}
|
|
1269
|
+
* />
|
|
1270
|
+
* ```
|
|
1271
|
+
*
|
|
1272
|
+
* ℹ️ This button is not focusable by default (`tabIndex={-1}`), since tabs shouldn't contain focusable content;
|
|
1273
|
+
* keyboard users can close the focused tab with Delete or Backspace.
|
|
1274
|
+
*/
|
|
1275
|
+
export declare const TabCloseButton: typeof TabCloseButtonComponent & {
|
|
1276
|
+
displayName: string;
|
|
1277
|
+
};
|
|
1278
|
+
|
|
1279
|
+
declare function TabCloseButtonComponent({ "aria-label": ariaLabel, children, onClick, ...rest }: TabCloseButtonProps): JSX.Element | null;
|
|
1280
|
+
|
|
1281
|
+
export declare type TabCloseButtonProps = ButtonHTMLAttributes<HTMLButtonElement>;
|
|
1282
|
+
|
|
1283
|
+
/**
|
|
1284
|
+
* Edge (or center) of a tabset's content area.
|
|
1285
|
+
*/
|
|
1286
|
+
export declare type TabDropRegion = "bottom" | "center" | "left" | "right" | "top";
|
|
1287
|
+
|
|
1288
|
+
/**
|
|
1289
|
+
* Where a dragged tab can be dropped:
|
|
1290
|
+
* - At an `index` within a tabset's tab list
|
|
1291
|
+
* - Within a `region` of a tabset's content area; edges split the tabset, and the center adds the tab to it
|
|
1292
|
+
*/
|
|
1293
|
+
export declare type TabDropTarget = {
|
|
1294
|
+
index: number;
|
|
1295
|
+
tabsetId: string;
|
|
1296
|
+
} | {
|
|
1297
|
+
region: TabDropRegion;
|
|
1298
|
+
tabsetId: string;
|
|
1299
|
+
};
|
|
1300
|
+
|
|
1301
|
+
/**
|
|
1302
|
+
* A tab within a tabset.
|
|
1303
|
+
*/
|
|
1304
|
+
export declare type TabNode<TabData = unknown> = {
|
|
1305
|
+
/**
|
|
1306
|
+
* Uniquely identifies the tab within the workspace.
|
|
1307
|
+
*
|
|
1308
|
+
* ℹ️ Tab ids are chosen by the application, since they usually identify something real (e.g. a file path).
|
|
1309
|
+
*/
|
|
1310
|
+
id: string;
|
|
1311
|
+
/**
|
|
1312
|
+
* Label used wherever the workspace generates text for the tab:
|
|
1313
|
+
* the default tab rendering, the default drag preview, and the `TabCloseButton` label.
|
|
1314
|
+
* Falls back to the tab's `id`.
|
|
1315
|
+
*/
|
|
1316
|
+
title?: string | undefined;
|
|
1317
|
+
/**
|
|
1318
|
+
* Application data for the tab.
|
|
1319
|
+
*
|
|
1320
|
+
* ℹ️ This value should be serializable (e.g. JSON) if the workspace model will be saved.
|
|
1321
|
+
*/
|
|
1322
|
+
data: TabData;
|
|
1323
|
+
/**
|
|
1324
|
+
* The user cannot close this tab.
|
|
1325
|
+
*
|
|
1326
|
+
* ℹ️ The tab can still be closed using the imperative API.
|
|
1327
|
+
*/
|
|
1328
|
+
disableClose?: boolean | undefined;
|
|
1329
|
+
/**
|
|
1330
|
+
* The user cannot drag this tab.
|
|
1331
|
+
*
|
|
1332
|
+
* ℹ️ The tab can still be selected, and other tabs can still be dropped around it.
|
|
1333
|
+
*/
|
|
1334
|
+
disableDrag?: boolean | undefined;
|
|
1335
|
+
};
|
|
1336
|
+
|
|
1337
|
+
/**
|
|
1338
|
+
* Props passed to the Workspace's `renderTab` prop, to be spread onto the element it returns.
|
|
1339
|
+
*/
|
|
1340
|
+
export declare type TabRenderProps = Pick<HTMLAttributes<HTMLElement>, "aria-controls" | "aria-selected" | "className" | "id" | "onClick" | "onKeyDown" | "onPointerDown" | "role" | "style" | "tabIndex"> & {
|
|
1341
|
+
ref: RefCallback<HTMLElement>;
|
|
1342
|
+
[dataAttribute: `data-${string}`]: string | boolean | undefined;
|
|
1343
|
+
};
|
|
1344
|
+
|
|
1345
|
+
/**
|
|
1346
|
+
* A set of tabs, only one of which is shown at a time.
|
|
1347
|
+
*/
|
|
1348
|
+
export declare type TabsetNode<TabData = unknown, TabsetData = unknown> = {
|
|
1349
|
+
/**
|
|
1350
|
+
* Distinguishes tabsets from splits.
|
|
1351
|
+
*/
|
|
1352
|
+
type: "tabset";
|
|
1353
|
+
/**
|
|
1354
|
+
* Uniquely identifies the tabset within the workspace.
|
|
1355
|
+
*
|
|
1356
|
+
* ℹ️ Optional in the `defaultModel` prop and the `setModel` method; tabsets without ids are assigned ids based on their position (e.g. "tabset-0-1").
|
|
1357
|
+
* Tabsets created by the workspace (e.g. by dropping a tab onto the edge of another tabset) are assigned generated ids.
|
|
1358
|
+
*/
|
|
1359
|
+
id: string;
|
|
1360
|
+
/**
|
|
1361
|
+
* Size of the tabset within its parent split.
|
|
1362
|
+
*
|
|
1363
|
+
* ℹ️ Interpretation rules:
|
|
1364
|
+
* - Numbers are percentages of the parent split (e.g. `size: 25` is 25 percent)
|
|
1365
|
+
* - Strings may specify other units (e.g. `size: "250px"`); strings without units are percentages
|
|
1366
|
+
* - Siblings without a size share the remaining space evenly
|
|
1367
|
+
*
|
|
1368
|
+
* ⚠️ String sizes are only initial sizes: they're converted to percentages when the user resizes the split,
|
|
1369
|
+
* and (like percentages) they scale with the workspace when it's resized.
|
|
1370
|
+
*/
|
|
1371
|
+
size?: number | string | undefined;
|
|
1372
|
+
/**
|
|
1373
|
+
* Minimum width of the tabset's content area (not including its header).
|
|
1374
|
+
* Overrides the Workspace's `tabsetMinWidth` prop.
|
|
1375
|
+
*
|
|
1376
|
+
* ℹ️ Interpretation rules:
|
|
1377
|
+
* - Strings must specify a unit: "px", "em", "rem", "vh", or "vw" (e.g. `minWidth: "200px"`)
|
|
1378
|
+
* - Percentages (and strings without units) are not allowed
|
|
1379
|
+
*/
|
|
1380
|
+
minWidth?: string | undefined;
|
|
1381
|
+
/**
|
|
1382
|
+
* Minimum height of the tabset's content area (not including its header).
|
|
1383
|
+
* Overrides the Workspace's `tabsetMinHeight` prop.
|
|
1384
|
+
*
|
|
1385
|
+
* ℹ️ Interpretation rules:
|
|
1386
|
+
* - Strings must specify a unit: "px", "em", "rem", "vh", or "vw" (e.g. `minHeight: "200px"`)
|
|
1387
|
+
* - Percentages (and strings without units) are not allowed
|
|
1388
|
+
*/
|
|
1389
|
+
minHeight?: string | undefined;
|
|
1390
|
+
/**
|
|
1391
|
+
* Where the tabset's tabs are placed relative to its content.
|
|
1392
|
+
* Overrides the Workspace's `tabPlacement` prop.
|
|
1393
|
+
*
|
|
1394
|
+
* ℹ️ See the Workspace's `tabPlacement` prop for how placement affects tabsets.
|
|
1395
|
+
*
|
|
1396
|
+
* ℹ️ Tabsets created by the workspace (e.g. by dropping a tab onto the edge of another tabset) use the Workspace's `tabPlacement` prop.
|
|
1397
|
+
*/
|
|
1398
|
+
tabPlacement?: "bottom" | "left" | "right" | "top" | undefined;
|
|
1399
|
+
/**
|
|
1400
|
+
* The tabset isn't removed when its last tab is closed or dragged away;
|
|
1401
|
+
* it stays (showing the Workspace's `renderEmptyTabset` content) until it is closed (see `closeTabset`).
|
|
1402
|
+
*
|
|
1403
|
+
* ℹ️ By default, tabsets without tabs are removed (other than the root tabset of an empty workspace).
|
|
1404
|
+
*
|
|
1405
|
+
* ℹ️ Tabsets created by the workspace (e.g. by dropping a tab onto the edge of another tabset) don't keep this flag.
|
|
1406
|
+
*/
|
|
1407
|
+
keepWhenEmpty?: boolean | undefined;
|
|
1408
|
+
/**
|
|
1409
|
+
* Id of the selected tab.
|
|
1410
|
+
*/
|
|
1411
|
+
selectedId?: string | undefined;
|
|
1412
|
+
/**
|
|
1413
|
+
* Application data for the tabset.
|
|
1414
|
+
*
|
|
1415
|
+
* ℹ️ Tabsets created by the workspace start without data.
|
|
1416
|
+
*/
|
|
1417
|
+
data?: TabsetData | undefined;
|
|
1418
|
+
/**
|
|
1419
|
+
* Tabs in the tabset, in the order they are shown.
|
|
1420
|
+
*/
|
|
1421
|
+
tabs: TabNode<TabData>[];
|
|
1422
|
+
};
|
|
1423
|
+
|
|
1424
|
+
export declare type TabsetNodeInput<TabData = unknown, TabsetData = unknown> = Omit<TabsetNode<TabData, TabsetData>, "id"> & {
|
|
1425
|
+
id?: string | undefined;
|
|
1426
|
+
};
|
|
1427
|
+
|
|
1022
1428
|
/**
|
|
1023
1429
|
* Saves and restores Grid layouts between page loads.
|
|
1024
1430
|
* It can be configured to store values using `localStorage`, `sessionStorage`, cookies, or any other persistence layer that makes sense for your application.
|
|
@@ -1164,4 +1570,463 @@ export declare function useParentGroup(): ParentGroup | null;
|
|
|
1164
1570
|
*/
|
|
1165
1571
|
export declare function useParentPanel(): ParentPanel | null;
|
|
1166
1572
|
|
|
1573
|
+
/**
|
|
1574
|
+
* Returns the nearest ancestor tab (or null if the component is not rendered within a tab (see `renderTab`) or the content of a tab).
|
|
1575
|
+
*
|
|
1576
|
+
* ℹ️ The returned value does not change for the life of the tab, so it is safe to use as an effect dependency.
|
|
1577
|
+
* Use `useParentTabState` for values that should trigger a re-render.
|
|
1578
|
+
*/
|
|
1579
|
+
export declare function useParentTab(): ParentTab | null;
|
|
1580
|
+
|
|
1581
|
+
/**
|
|
1582
|
+
* Returns the nearest ancestor tabset (or null if the component is not rendered within a tabset or the content of a tab).
|
|
1583
|
+
*
|
|
1584
|
+
* ℹ️ The returned value does not change for the life of the tabset, so it is safe to use as an effect dependency.
|
|
1585
|
+
* Use `useParentTabsetState` for values that should trigger a re-render.
|
|
1586
|
+
*/
|
|
1587
|
+
export declare function useParentTabset<TabData = unknown>(): ParentTabset<TabData> | null;
|
|
1588
|
+
|
|
1589
|
+
/**
|
|
1590
|
+
* Returns the state of the nearest ancestor tabset (or null if the component is not rendered within a tabset or the content of a tab).
|
|
1591
|
+
*
|
|
1592
|
+
* ℹ️ Components that use this hook only re-render when the tabset's state changes.
|
|
1593
|
+
*/
|
|
1594
|
+
export declare function useParentTabsetState(): ParentTabsetState | null;
|
|
1595
|
+
|
|
1596
|
+
/**
|
|
1597
|
+
* Returns the state of the nearest ancestor tab (or null if the component is not rendered within a tab (see `renderTab`) or the content of a tab).
|
|
1598
|
+
*
|
|
1599
|
+
* ℹ️ Components that use this hook only re-render when the tab's state changes.
|
|
1600
|
+
*/
|
|
1601
|
+
export declare function useParentTabState(): ParentTabState | null;
|
|
1602
|
+
|
|
1603
|
+
/**
|
|
1604
|
+
* Returns the nearest ancestor Workspace (or null if the component is not rendered within a Workspace).
|
|
1605
|
+
*
|
|
1606
|
+
* ℹ️ The returned value includes the Workspace's imperative API; it does not change when the Workspace's model changes.
|
|
1607
|
+
*/
|
|
1608
|
+
export declare function useParentWorkspace<TabData = unknown, TabsetData = unknown>(): ParentWorkspace<TabData, TabsetData> | null;
|
|
1609
|
+
|
|
1610
|
+
/**
|
|
1611
|
+
* Convenience hook to return a properly typed ref callback for the Workspace component.
|
|
1612
|
+
*
|
|
1613
|
+
* Use this hook when you need to share the ref with another component or hook.
|
|
1614
|
+
*/
|
|
1615
|
+
export declare function useWorkspaceCallbackRef<TabData = unknown, TabsetData = unknown>(): [WorkspaceImperativeHandle<TabData, TabsetData> | null, Dispatch<SetStateAction<WorkspaceImperativeHandle<TabData, TabsetData> | null>>];
|
|
1616
|
+
|
|
1617
|
+
/**
|
|
1618
|
+
* Convenience hook to return a properly typed ref for the Workspace component.
|
|
1619
|
+
*/
|
|
1620
|
+
export declare function useWorkspaceRef<TabData = unknown, TabsetData = unknown>(): RefObject<WorkspaceImperativeHandle<TabData, TabsetData> | null>;
|
|
1621
|
+
|
|
1622
|
+
/**
|
|
1623
|
+
* A Workspace arranges tabsets that users can rearrange by dragging tabs:
|
|
1624
|
+
* between tabsets, within a tabset's list of tabs, or onto the edge of a tabset to split it.
|
|
1625
|
+
* Tabsets can be resized and maximized.
|
|
1626
|
+
*
|
|
1627
|
+
* The layout is described by a serializable model (see `WorkspaceModel`).
|
|
1628
|
+
* Workspaces are uncontrolled: provide an initial model with the `defaultModel` prop, save changes from the `onModelChanged` callback,
|
|
1629
|
+
* and make changes using the imperative API (see `WorkspaceImperativeHandle`).
|
|
1630
|
+
*
|
|
1631
|
+
* ℹ️ Tab content is not remounted when a tab is moved.
|
|
1632
|
+
* Its elements are moved within the document, though, which resets some browser state (e.g. iframes are reloaded).
|
|
1633
|
+
*
|
|
1634
|
+
* Workspace elements always include the following attributes:
|
|
1635
|
+
*
|
|
1636
|
+
* ```html
|
|
1637
|
+
* <div data-workspace data-testid="workspace-id-prop" id="workspace-id-prop">
|
|
1638
|
+
* ```
|
|
1639
|
+
*
|
|
1640
|
+
* ℹ️ [Test id](https://testing-library.com/docs/queries/bytestid/) can be used to narrow selection when unit testing.
|
|
1641
|
+
*/
|
|
1642
|
+
export declare const Workspace: typeof WorkspaceComponent & {
|
|
1643
|
+
displayName: string;
|
|
1644
|
+
};
|
|
1645
|
+
|
|
1646
|
+
/**
|
|
1647
|
+
* Metadata describing a model change, passed as the second argument to the `onModelChanged` callback.
|
|
1648
|
+
*/
|
|
1649
|
+
export declare type WorkspaceChangedMeta = {
|
|
1650
|
+
/**
|
|
1651
|
+
* `true` when the change was caused by the user (e.g. dragging a tab or clicking a close button),
|
|
1652
|
+
* `false` for imperative API calls.
|
|
1653
|
+
*/
|
|
1654
|
+
isUserInteraction: boolean;
|
|
1655
|
+
/**
|
|
1656
|
+
* Which change was made.
|
|
1657
|
+
*
|
|
1658
|
+
* ⚠️ New reasons may be added in later versions, so code that switches on this value should handle unrecognized values.
|
|
1659
|
+
*/
|
|
1660
|
+
reason: WorkspaceChangeReason;
|
|
1661
|
+
};
|
|
1662
|
+
|
|
1663
|
+
/**
|
|
1664
|
+
* Which change caused `onModelChanged` to be called.
|
|
1665
|
+
*
|
|
1666
|
+
* ⚠️ New reasons may be added in later versions.
|
|
1667
|
+
*/
|
|
1668
|
+
export declare type WorkspaceChangeReason = "add" | "close" | "maximize" | "move" | "resize" | "restore" | "select" | "set-model" | "update";
|
|
1669
|
+
|
|
1670
|
+
/**
|
|
1671
|
+
* CSS class names for the elements a Workspace renders (see the Workspace's `classNames` prop).
|
|
1672
|
+
*/
|
|
1673
|
+
export declare type WorkspaceClassNames = {
|
|
1674
|
+
dragPreview?: string | undefined;
|
|
1675
|
+
dropIndicator?: string | undefined;
|
|
1676
|
+
header?: string | undefined;
|
|
1677
|
+
tab?: string | undefined;
|
|
1678
|
+
tabContent?: string | undefined;
|
|
1679
|
+
tabList?: string | undefined;
|
|
1680
|
+
tabPanels?: string | undefined;
|
|
1681
|
+
tabset?: string | undefined;
|
|
1682
|
+
toolbar?: string | undefined;
|
|
1683
|
+
};
|
|
1684
|
+
|
|
1685
|
+
declare function WorkspaceComponent<TabData = unknown, TabsetData = unknown>({ className, classNames, defaultModel, disabled, disableDrop, elementRef: elementRefProp, hiddenTabBehavior, id: idProp, onModelChanged, renderDragPreview, renderEmptyTabset, renderSeparator, renderTab, renderTabContent, renderTabsetToolbar, resizePreviewMode, serverRenderTabContent, style, styles, tabPlacement, tabsetMinHeight, tabsetMinWidth, workspaceRef, ...rest }: WorkspaceProps<TabData, TabsetData>): JSX.Element;
|
|
1686
|
+
|
|
1687
|
+
/**
|
|
1688
|
+
* Imperative Workspace API.
|
|
1689
|
+
*
|
|
1690
|
+
* The easiest way to interact with this API is to use the `useWorkspaceRef` and `useWorkspaceCallbackRef` hooks.
|
|
1691
|
+
*
|
|
1692
|
+
* ℹ️ These methods are not restricted by `disabled`, `disableClose`, `disableDrag`, or `disableDrop`.
|
|
1693
|
+
*/
|
|
1694
|
+
export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData = unknown> {
|
|
1695
|
+
/**
|
|
1696
|
+
* Add a tab to a tabset.
|
|
1697
|
+
*
|
|
1698
|
+
* ℹ️ If a tab with the same id already exists, it is selected instead (and its data is not changed).
|
|
1699
|
+
*
|
|
1700
|
+
* @param tab Tab to add
|
|
1701
|
+
* @param options.tabsetId Tabset to add the tab to; defaults to the active tabset
|
|
1702
|
+
* @param options.index Position within the tabset; defaults to the end
|
|
1703
|
+
* @param options.select Select the new tab; defaults to true
|
|
1704
|
+
* @return `true` if the tab was added
|
|
1705
|
+
*/
|
|
1706
|
+
addTab: (tab: TabNode<TabData>, options?: {
|
|
1707
|
+
index?: number | undefined;
|
|
1708
|
+
select?: boolean | undefined;
|
|
1709
|
+
tabsetId?: string | undefined;
|
|
1710
|
+
}) => boolean;
|
|
1711
|
+
/**
|
|
1712
|
+
* Close a tab.
|
|
1713
|
+
*/
|
|
1714
|
+
closeTab: (tabId: string) => void;
|
|
1715
|
+
/**
|
|
1716
|
+
* Close a tabset, along with any tabs it contains (e.g. to remove an empty tabset with the `keepWhenEmpty` flag).
|
|
1717
|
+
*
|
|
1718
|
+
* ℹ️ Like the rest of the imperative API, this isn't restricted by tabs' `disableClose` flags.
|
|
1719
|
+
* If the root tabset is closed, the workspace is left with an empty root tabset.
|
|
1720
|
+
*/
|
|
1721
|
+
closeTabset: (tabsetId: string) => void;
|
|
1722
|
+
/**
|
|
1723
|
+
* Id of the tabset the user most recently interacted with (by pointer or focus).
|
|
1724
|
+
*/
|
|
1725
|
+
getActiveTabsetId: () => string | undefined;
|
|
1726
|
+
/**
|
|
1727
|
+
* Get the current model.
|
|
1728
|
+
*/
|
|
1729
|
+
getModel: () => WorkspaceModel<TabData, TabsetData>;
|
|
1730
|
+
/**
|
|
1731
|
+
* Maximize a tabset, so that it covers the rest of the workspace.
|
|
1732
|
+
*
|
|
1733
|
+
* ℹ️ This has no effect on the only tabset in a workspace (the root), which already fills it.
|
|
1734
|
+
* A maximized tabset is restored if it becomes the only one (e.g. after the other tabsets are closed).
|
|
1735
|
+
*/
|
|
1736
|
+
maximizeTabset: (tabsetId: string) => void;
|
|
1737
|
+
/**
|
|
1738
|
+
* Move a tab to a position within a tabset's tab list, or to a region of a tabset's content area.
|
|
1739
|
+
*/
|
|
1740
|
+
moveTab: (tabId: string, target: TabDropTarget) => void;
|
|
1741
|
+
/**
|
|
1742
|
+
* Restore the maximized tabset (if there is one).
|
|
1743
|
+
*/
|
|
1744
|
+
restoreTabset: () => void;
|
|
1745
|
+
/**
|
|
1746
|
+
* Select a tab within its tabset.
|
|
1747
|
+
*/
|
|
1748
|
+
selectTab: (tabId: string) => void;
|
|
1749
|
+
/**
|
|
1750
|
+
* Replace the model.
|
|
1751
|
+
*
|
|
1752
|
+
* @return Applied model (after normalization)
|
|
1753
|
+
*/
|
|
1754
|
+
setModel: (model: WorkspaceModelInput<TabData, TabsetData>) => WorkspaceModel<TabData, TabsetData>;
|
|
1755
|
+
/**
|
|
1756
|
+
* Update a tab; fields that are not specified are not changed.
|
|
1757
|
+
*
|
|
1758
|
+
* ℹ️ `data` is replaced rather than merged.
|
|
1759
|
+
*/
|
|
1760
|
+
updateTab: (tabId: string, changes: {
|
|
1761
|
+
data?: TabData;
|
|
1762
|
+
disableClose?: boolean | undefined;
|
|
1763
|
+
disableDrag?: boolean | undefined;
|
|
1764
|
+
title?: string | undefined;
|
|
1765
|
+
}) => void;
|
|
1766
|
+
/**
|
|
1767
|
+
* Update a tabset; fields that are not specified are not changed.
|
|
1768
|
+
*
|
|
1769
|
+
* ℹ️ `data` is replaced rather than merged.
|
|
1770
|
+
*
|
|
1771
|
+
* ℹ️ Setting `minHeight`, `minWidth`, or `tabPlacement` to `undefined` removes the tabset's override,
|
|
1772
|
+
* so the corresponding Workspace prop is used.
|
|
1773
|
+
*/
|
|
1774
|
+
updateTabset: (tabsetId: string, changes: {
|
|
1775
|
+
data?: TabsetData;
|
|
1776
|
+
keepWhenEmpty?: boolean | undefined;
|
|
1777
|
+
minHeight?: string | undefined;
|
|
1778
|
+
minWidth?: string | undefined;
|
|
1779
|
+
tabPlacement?: TabsetNode["tabPlacement"];
|
|
1780
|
+
}) => void;
|
|
1781
|
+
}
|
|
1782
|
+
|
|
1783
|
+
/**
|
|
1784
|
+
* Serializable description of a workspace's layout.
|
|
1785
|
+
*/
|
|
1786
|
+
export declare type WorkspaceModel<TabData = unknown, TabsetData = unknown> = {
|
|
1787
|
+
/**
|
|
1788
|
+
* Format version; allows the workspace to migrate models saved by older versions.
|
|
1789
|
+
*/
|
|
1790
|
+
version: 1;
|
|
1791
|
+
/**
|
|
1792
|
+
* Root of the layout tree: a split or a tabset.
|
|
1793
|
+
*
|
|
1794
|
+
* ℹ️ An empty workspace is a tabset with no tabs.
|
|
1795
|
+
*/
|
|
1796
|
+
root: WorkspaceNode<TabData, TabsetData>;
|
|
1797
|
+
/**
|
|
1798
|
+
* Id of the tabset that is maximized, if any.
|
|
1799
|
+
*/
|
|
1800
|
+
maximizedTabsetId?: string | undefined;
|
|
1801
|
+
};
|
|
1802
|
+
|
|
1803
|
+
/**
|
|
1804
|
+
* A `WorkspaceModel` whose splits and tabsets may omit their ids; accepted by the `defaultModel` prop and the `setModel` method.
|
|
1805
|
+
*/
|
|
1806
|
+
export declare type WorkspaceModelInput<TabData = unknown, TabsetData = unknown> = Omit<WorkspaceModel<TabData, TabsetData>, "root"> & {
|
|
1807
|
+
root: WorkspaceNodeInput<TabData, TabsetData>;
|
|
1808
|
+
};
|
|
1809
|
+
|
|
1810
|
+
/**
|
|
1811
|
+
* A node in the workspace's layout tree: either a split or a tabset.
|
|
1812
|
+
*/
|
|
1813
|
+
export declare type WorkspaceNode<TabData = unknown, TabsetData = unknown> = SplitNode<TabData, TabsetData> | TabsetNode<TabData, TabsetData>;
|
|
1814
|
+
|
|
1815
|
+
export declare type WorkspaceNodeInput<TabData = unknown, TabsetData = unknown> = SplitNodeInput<TabData, TabsetData> | TabsetNodeInput<TabData, TabsetData>;
|
|
1816
|
+
|
|
1817
|
+
export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Omit<HTMLAttributes<HTMLDivElement>, "children" | "defaultValue"> & {
|
|
1818
|
+
/**
|
|
1819
|
+
* CSS class name.
|
|
1820
|
+
*/
|
|
1821
|
+
className?: string | undefined;
|
|
1822
|
+
/**
|
|
1823
|
+
* CSS class names for the elements the workspace renders within its root element:
|
|
1824
|
+
* - `tabset`: root element of a tabset (`data-tabset`)
|
|
1825
|
+
* - `header`: contains a tabset's tab list and toolbar (`data-tabset-header`)
|
|
1826
|
+
* - `tabList`: contains a tabset's tabs (`data-tab-list`)
|
|
1827
|
+
* - `tab`: passed to `renderTab` with the rest of a tab's props (`data-tab`)
|
|
1828
|
+
* - `toolbar`: contains the content returned by `renderTabsetToolbar` (`data-tabset-toolbar`)
|
|
1829
|
+
* - `tabPanels`: contains a tabset's tab content (`data-tab-panels`)
|
|
1830
|
+
* - `tabContent`: the element each tab's content is rendered into (`data-tab-content`)
|
|
1831
|
+
* - `dropIndicator`: shows where a dragged tab will be dropped within a tabset's panels (`data-drop-indicator`)
|
|
1832
|
+
* - `dragPreview`: follows the pointer while a tab is dragged (`data-drag-preview`)
|
|
1833
|
+
*
|
|
1834
|
+
* ℹ️ Elements expose their state as data attributes (e.g. `data-tab-selected`), which can be used for styling.
|
|
1835
|
+
* Elements within a tabset also have a `data-tab-placement` attribute (see `tabPlacement`).
|
|
1836
|
+
*
|
|
1837
|
+
* ℹ️ Like the render props, this object is part of what tabsets re-render for;
|
|
1838
|
+
* in large workspaces, define it outside of the component (or memoize it) rather than inline.
|
|
1839
|
+
*/
|
|
1840
|
+
classNames?: WorkspaceClassNames | undefined;
|
|
1841
|
+
/**
|
|
1842
|
+
* Initial layout of the workspace.
|
|
1843
|
+
*
|
|
1844
|
+
* ℹ️ Splits and tabsets may omit their ids; they're assigned ids based on their position (see `WorkspaceModelInput`).
|
|
1845
|
+
*
|
|
1846
|
+
* ℹ️ This value is only used when the Workspace mounts; use the imperative `setModel` method to replace it later.
|
|
1847
|
+
*/
|
|
1848
|
+
defaultModel: WorkspaceModelInput<TabData, TabsetData>;
|
|
1849
|
+
/**
|
|
1850
|
+
* Locks the arrangement: tabs cannot be resized, dragged, dropped, or closed by the user.
|
|
1851
|
+
* Selecting tabs and maximizing tabsets still work.
|
|
1852
|
+
*
|
|
1853
|
+
* ℹ️ This prop overrides the `disableClose` and `disableDrag` flags of individual tabs.
|
|
1854
|
+
*/
|
|
1855
|
+
disabled?: boolean | undefined;
|
|
1856
|
+
/**
|
|
1857
|
+
* Prevents tabs from being dropped onto some (or all) targets.
|
|
1858
|
+
*
|
|
1859
|
+
* Functions are called when the target under the pointer changes;
|
|
1860
|
+
* returning `true` rejects the target.
|
|
1861
|
+
*/
|
|
1862
|
+
disableDrop?: boolean | ((args: DisableDropArgs<TabData, TabsetData>) => boolean) | undefined;
|
|
1863
|
+
/**
|
|
1864
|
+
* Ref attached to the root `HTMLDivElement`.
|
|
1865
|
+
*/
|
|
1866
|
+
elementRef?: Ref<HTMLDivElement | null> | undefined;
|
|
1867
|
+
/**
|
|
1868
|
+
* What happens to the content of tabs that are not selected.
|
|
1869
|
+
* Can be a function to choose per tab (e.g. based on its data).
|
|
1870
|
+
*
|
|
1871
|
+
* - `"keep-mounted"`: content stays mounted (and its effects keep running)
|
|
1872
|
+
* - `"activity"`: content stays mounted but is rendered within a hidden React `<Activity>` boundary, so its effects are unmounted;
|
|
1873
|
+
* requires React 19.2 (falls back to `"keep-mounted"` otherwise)
|
|
1874
|
+
* - `"unmount"`: content is unmounted
|
|
1875
|
+
*
|
|
1876
|
+
* ℹ️ Moving a tab never remounts its content.
|
|
1877
|
+
*
|
|
1878
|
+
* ⚠️ Its React state is preserved, but its elements are moved within the document, which resets some browser state:
|
|
1879
|
+
* iframes are reloaded, playing media is paused, and focused elements are blurred.
|
|
1880
|
+
*
|
|
1881
|
+
* @default "keep-mounted"
|
|
1882
|
+
*/
|
|
1883
|
+
hiddenTabBehavior?: HiddenTabBehavior | ((tab: TabNode<TabData>) => HiddenTabBehavior) | undefined;
|
|
1884
|
+
/**
|
|
1885
|
+
* Uniquely identifies this workspace within an application.
|
|
1886
|
+
* Falls back to `useId` when not provided.
|
|
1887
|
+
*
|
|
1888
|
+
* ℹ️ This value will also be assigned to the `id` and `data-testid` attributes; (an explicit `data-testid` prop will take precedence).
|
|
1889
|
+
*/
|
|
1890
|
+
id?: string | number | undefined;
|
|
1891
|
+
/**
|
|
1892
|
+
* Called after the model has changed (e.g. a tab was moved, selected, or closed, or a tabset was resized).
|
|
1893
|
+
*
|
|
1894
|
+
* ℹ️ For changes caused by pointer events, this method is not called until the pointer has been released.
|
|
1895
|
+
* This method is recommended when saving models to some storage api.
|
|
1896
|
+
*/
|
|
1897
|
+
onModelChanged?: (model: WorkspaceModel<TabData, TabsetData>, meta: WorkspaceChangedMeta) => void;
|
|
1898
|
+
/**
|
|
1899
|
+
* Content of the element that follows the pointer while a tab is being dragged.
|
|
1900
|
+
* Defaults to the tab's title (or id).
|
|
1901
|
+
*/
|
|
1902
|
+
renderDragPreview?: ((tab: TabNode<TabData>) => ReactNode) | undefined;
|
|
1903
|
+
/**
|
|
1904
|
+
* Content shown in the panels of a tabset that has no tabs (e.g. "Drag a tab here"):
|
|
1905
|
+
* the root tabset of an empty workspace, or a tabset with the `keepWhenEmpty` flag.
|
|
1906
|
+
*/
|
|
1907
|
+
renderEmptyTabset?: ((tabset: TabsetNode<TabData, TabsetData>) => ReactNode) | undefined;
|
|
1908
|
+
/**
|
|
1909
|
+
* Separator rendered between the children of a split.
|
|
1910
|
+
* Should return a `Separator` (or `null` for no separator); defaults to an unstyled `Separator`.
|
|
1911
|
+
*/
|
|
1912
|
+
renderSeparator?: ((orientation: Orientation) => ReactNode) | undefined;
|
|
1913
|
+
/**
|
|
1914
|
+
* Renders a tab (within its tabset's tab list).
|
|
1915
|
+
* Spread `props` onto the returned element:
|
|
1916
|
+
* they make it a tab (its role and ARIA attributes, keyboard and pointer handling, and data attributes),
|
|
1917
|
+
* and attach a `ref` that dragging and keyboard focus depend on.
|
|
1918
|
+
*
|
|
1919
|
+
* ```tsx
|
|
1920
|
+
* renderTab={(tab, props) => (
|
|
1921
|
+
* <div {...props}>
|
|
1922
|
+
* {tab.title}
|
|
1923
|
+
* <TabCloseButton />
|
|
1924
|
+
* </div>
|
|
1925
|
+
* )}
|
|
1926
|
+
* ```
|
|
1927
|
+
*
|
|
1928
|
+
* Individual props can be overridden or wrapped, e.g. to confirm before the Delete key closes a tab
|
|
1929
|
+
* (call `props.onKeyDown` for other keys).
|
|
1930
|
+
*
|
|
1931
|
+
* ⚠️ Merge `className` and `style` rather than replacing them (e.g. `style={{ ...props.style, padding: 4 }}`):
|
|
1932
|
+
* they include the `tab` entries of the `classNames` and `styles` props, and `style` includes the `touch-action` that touch dragging depends on.
|
|
1933
|
+
*
|
|
1934
|
+
* ℹ️ Pointer and keyboard events from interactive descendants (`button` elements, `role="button"`, or elements with a `data-tab-ignore` attribute) are ignored,
|
|
1935
|
+
* so clicking a button within a tab doesn't select or drag it.
|
|
1936
|
+
*
|
|
1937
|
+
* ℹ️ When this prop is not provided, tabs show their title (or id) followed by a `TabCloseButton`.
|
|
1938
|
+
*/
|
|
1939
|
+
renderTab?: ((tab: TabNode<TabData>, props: TabRenderProps) => ReactNode) | undefined;
|
|
1940
|
+
/**
|
|
1941
|
+
* Content of a tab.
|
|
1942
|
+
*
|
|
1943
|
+
* ℹ️ Content is only re-rendered when its tab changes or this function does;
|
|
1944
|
+
* a function created while rendering (e.g. an inline arrow function) re-renders the content of every tab whenever the Workspace's parent re-renders,
|
|
1945
|
+
* so it should be memoized (e.g. with `useCallback`) when tab content is expensive to render.
|
|
1946
|
+
*/
|
|
1947
|
+
renderTabContent: (tab: TabNode<TabData>) => ReactNode;
|
|
1948
|
+
/**
|
|
1949
|
+
* Content shown after a tabset's tab list (e.g. buttons to add a tab or maximize the tabset).
|
|
1950
|
+
*
|
|
1951
|
+
* ℹ️ The `useParentTabset` and `useParentTabsetState` hooks can be used within this content.
|
|
1952
|
+
*/
|
|
1953
|
+
renderTabsetToolbar?: ((tabset: TabsetNode<TabData, TabsetData>) => ReactNode) | undefined;
|
|
1954
|
+
/**
|
|
1955
|
+
* Controls whether pointer dragging updates sizes immediately,
|
|
1956
|
+
* or renders overlay separator previews until the pointer is released.
|
|
1957
|
+
*
|
|
1958
|
+
* @default "panel"
|
|
1959
|
+
*/
|
|
1960
|
+
resizePreviewMode?: ResizePreviewMode | undefined;
|
|
1961
|
+
/**
|
|
1962
|
+
* Render the content of selected tabs on the server.
|
|
1963
|
+
* Can be a function to choose per tab (e.g. based on its data).
|
|
1964
|
+
*
|
|
1965
|
+
* Tab content is rendered through portals (so that moving a tab doesn't remount it), which React can't render on the server.
|
|
1966
|
+
* Content opted into server rendering is rendered inline instead, then moved into a portal once hydration has finished.
|
|
1967
|
+
*
|
|
1968
|
+
* ⚠️ That move remounts the content once (e.g. resetting its state and re-running its effects),
|
|
1969
|
+
* so this is best suited to content that is cheap to mount and benefits from being in the server-rendered HTML.
|
|
1970
|
+
*
|
|
1971
|
+
* ℹ️ This prop has no effect for workspaces that are not server rendered.
|
|
1972
|
+
*
|
|
1973
|
+
* @default false
|
|
1974
|
+
*/
|
|
1975
|
+
serverRenderTabContent?: boolean | ((tab: TabNode<TabData>) => boolean) | undefined;
|
|
1976
|
+
/**
|
|
1977
|
+
* CSS properties.
|
|
1978
|
+
*/
|
|
1979
|
+
style?: CSSProperties | undefined;
|
|
1980
|
+
/**
|
|
1981
|
+
* CSS properties for the elements the workspace renders within its root element (see `classNames`).
|
|
1982
|
+
*/
|
|
1983
|
+
styles?: WorkspaceStyles | undefined;
|
|
1984
|
+
/**
|
|
1985
|
+
* Where tabs are placed relative to tab content.
|
|
1986
|
+
*
|
|
1987
|
+
* Tabs placed on the left or right are stacked ("vertical"):
|
|
1988
|
+
* this determines how a dropped tab's position is found and which arrow keys move focus between tabs.
|
|
1989
|
+
*
|
|
1990
|
+
* ℹ️ 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).
|
|
1991
|
+
*
|
|
1992
|
+
* ℹ️ Tabsets can override this with the `tabPlacement` field of their model node.
|
|
1993
|
+
*
|
|
1994
|
+
* @default "top"
|
|
1995
|
+
*/
|
|
1996
|
+
tabPlacement?: "bottom" | "left" | "right" | "top" | undefined;
|
|
1997
|
+
/**
|
|
1998
|
+
* Minimum height of each tabset's content area (not including its header).
|
|
1999
|
+
*
|
|
2000
|
+
* ℹ️ Tabsets can override this with the `minHeight` field of their model node.
|
|
2001
|
+
*
|
|
2002
|
+
* ℹ️ Interpretation rules:
|
|
2003
|
+
* - Strings must specify a unit: "px", "em", "rem", "vh", or "vw" (e.g. `tabsetMinHeight: "200px"`)
|
|
2004
|
+
* - Percentages (and strings without units) are not allowed
|
|
2005
|
+
*/
|
|
2006
|
+
tabsetMinHeight?: string | undefined;
|
|
2007
|
+
/**
|
|
2008
|
+
* Minimum width of each tabset's content area (not including its header).
|
|
2009
|
+
*
|
|
2010
|
+
* ℹ️ Tabsets can override this with the `minWidth` field of their model node.
|
|
2011
|
+
*
|
|
2012
|
+
* ℹ️ Interpretation rules:
|
|
2013
|
+
* - Strings must specify a unit: "px", "em", "rem", "vh", or "vw" (e.g. `tabsetMinWidth: "200px"`)
|
|
2014
|
+
* - Percentages (and strings without units) are not allowed
|
|
2015
|
+
*/
|
|
2016
|
+
tabsetMinWidth?: string | undefined;
|
|
2017
|
+
/**
|
|
2018
|
+
* Exposes the imperative API (see `WorkspaceImperativeHandle`).
|
|
2019
|
+
*
|
|
2020
|
+
* ℹ️ The `useWorkspaceRef` and `useWorkspaceCallbackRef` hooks are exported for convenience use in TypeScript projects.
|
|
2021
|
+
*/
|
|
2022
|
+
workspaceRef?: Ref<WorkspaceImperativeHandle<TabData, TabsetData> | null> | undefined;
|
|
2023
|
+
};
|
|
2024
|
+
|
|
2025
|
+
/**
|
|
2026
|
+
* CSS properties for the elements a Workspace renders (see the Workspace's `classNames` prop).
|
|
2027
|
+
*/
|
|
2028
|
+
export declare type WorkspaceStyles = {
|
|
2029
|
+
[Element in keyof WorkspaceClassNames]?: CSSProperties | undefined;
|
|
2030
|
+
};
|
|
2031
|
+
|
|
1167
2032
|
export { }
|