react-resizable-panels 4.17.0 → 4.18.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.
@@ -696,6 +696,26 @@ export declare type LayoutChangedMeta<RequestedLayout = Layout> = {
696
696
 
697
697
  export declare type LayoutStorage = Pick<Storage, "getItem" | "setItem">;
698
698
 
699
+ /**
700
+ * Validates a model (e.g. one saved from `onModelChanged` and loaded from storage) and tidies it,
701
+ * the same way the `defaultModel` prop and the `setModel` method do:
702
+ * - Removes empty tabsets (other than an empty root tabset, and tabsets with the `keepWhenEmpty` flag)
703
+ * - Replaces splits with a single child with that child, and merges splits into parent splits with the same orientation
704
+ * - Scales sizes so they add up to 100 (when all siblings have percentage sizes)
705
+ * - Fixes selections (and recently selected tabs) of tabs that no longer exist
706
+ * - Expands tabsets that can't be collapsed (e.g. the only tabset in the workspace)
707
+ * - Clears the maximized tabset if it no longer exists
708
+ * - Assigns ids to splits and tabsets that don't have them
709
+ *
710
+ * ℹ️ The optional `mapTab` function is called for each tab before the model is tidied,
711
+ * e.g. to refresh a saved tab's title and flags from code; tabs it returns `null` for are removed.
712
+ *
713
+ * @returns The tidied model, or `null` if the value isn't a model (e.g. saved data that's corrupt, or saved by an unsupported version)
714
+ */
715
+ export declare function normalizeWorkspaceModel<TabData = unknown, TabsetData = unknown>(value: unknown, { mapTab }?: {
716
+ mapTab?: ((tab: TabNode<TabData>) => TabNode<TabData> | null) | undefined;
717
+ }): WorkspaceModel<TabData, TabsetData> | null;
718
+
699
719
  export declare type OnGroupLayoutChange = GroupProps["onLayoutChange"];
700
720
 
701
721
  export declare type OnPanelResize = PanelProps["onResize"];
@@ -1046,7 +1066,7 @@ export declare type ParentTabset<TabData = unknown> = {
1046
1066
  */
1047
1067
  collapse: () => void;
1048
1068
  /**
1049
- * Expand the tabset if it is collapsed.
1069
+ * Expand the tabset if it is collapsed (see `WorkspaceImperativeHandle.expandTabset`).
1050
1070
  */
1051
1071
  expand: () => void;
1052
1072
  /**
@@ -1056,8 +1076,8 @@ export declare type ParentTabset<TabData = unknown> = {
1056
1076
  /**
1057
1077
  * The tabset is currently collapsed (in the model).
1058
1078
  *
1059
- * ℹ️ While a separator is being dragged, a tabset may be shown collapsed (or expanded) before the model changes;
1060
- * `useParentTabsetState().isCollapsed` reflects how it's shown.
1079
+ * ℹ️ A tabset may be shown collapsed (or expanded) unlike the model: while a separator is being dragged (before the model changes),
1080
+ * and when it's collapsed to fit (see `TabsetNode.collapsible`); `useParentTabsetState().isCollapsed` reflects how it's shown.
1061
1081
  */
1062
1082
  isCollapsed: () => boolean;
1063
1083
  /**
@@ -1094,9 +1114,18 @@ export declare type ParentTabsetState = {
1094
1114
  * ℹ️ While a separator is being dragged, this reflects how the tabset is shown (e.g. collapsed as soon as it reaches its collapsed size),
1095
1115
  * which the model (and `useParentTabset().isCollapsed()`) only reflects once the drag ends.
1096
1116
  *
1117
+ * ℹ️ A tabset that's collapsed to fit (see `isCollapsedToFit`) is collapsed, although the model has it expanded.
1118
+ *
1097
1119
  * ℹ️ A maximized tabset is shown expanded, but it's still collapsed when it is restored.
1098
1120
  */
1099
1121
  isCollapsed: boolean;
1122
+ /**
1123
+ * The tabset is collapsed only because it doesn't fit (e.g. the workspace is narrower than its tabsets' minimum sizes; see `TabsetNode.collapsible`).
1124
+ * The model has it expanded, and it's shown expanded again once it fits.
1125
+ *
1126
+ * ℹ️ It can't be expanded until then (e.g. `useParentTabset().expand()` does nothing), so a toolbar can hide (or disable) its "expand" button.
1127
+ */
1128
+ isCollapsedToFit: boolean;
1100
1129
  /**
1101
1130
  * The tabset can be collapsed (or is collapsed, and can be expanded), e.g. to show or hide a toolbar button:
1102
1131
  * it has the `collapsible` flag, isn't the only tabset in the workspace, and has a sibling that isn't collapsed.
@@ -1148,7 +1177,7 @@ export declare type ParentTabState = {
1148
1177
  * The tab is selected, and its tabset is neither collapsed nor covered by another, maximized tabset.
1149
1178
  *
1150
1179
  * ℹ️ 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),
1151
- * which the model only reflects once the drag ends.
1180
+ * which the model only reflects once the drag ends; it also reflects tabsets that are collapsed to fit (see `TabsetNode.collapsible`).
1152
1181
  *
1153
1182
  * ⚠️ This value does not account for the Workspace itself being hidden.
1154
1183
  */
@@ -1338,12 +1367,14 @@ export declare type TabCloseButtonProps = ButtonHTMLAttributes<HTMLButtonElement
1338
1367
 
1339
1368
  /**
1340
1369
  * Edge (or center) of a tabset's content area.
1370
+ *
1371
+ * ℹ️ Edges are sides of the screen, so in a right-to-left layout (e.g. within `dir="rtl"`), "left" is after the tabset in its split's `children`.
1341
1372
  */
1342
1373
  export declare type TabDropRegion = "bottom" | "center" | "left" | "right" | "top";
1343
1374
 
1344
1375
  /**
1345
1376
  * Where a dragged tab can be dropped:
1346
- * - At an `index` within a tabset's tab list
1377
+ * - 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)
1347
1378
  * - Within a `region` of a tabset's content area; edges split the tabset, and the center adds the tab to it
1348
1379
  */
1349
1380
  export declare type TabDropTarget = {
@@ -1454,6 +1485,9 @@ export declare type TabsetNode<TabData = unknown, TabsetData = unknown> = {
1454
1485
  *
1455
1486
  * ⚠️ String sizes are only initial sizes: they're converted to percentages when the user resizes the split,
1456
1487
  * and (like percentages) they scale with the workspace when it's resized.
1488
+ *
1489
+ * ℹ️ A tabset is shown within its minimum and maximum sizes (see `minWidth` and `maxWidth`), even if its size is outside of them
1490
+ * (e.g. a model saved in a wider window); its size isn't changed, so it's shown at its size again once that fits.
1457
1491
  */
1458
1492
  size?: number | string | undefined;
1459
1493
  /**
@@ -1474,6 +1508,30 @@ export declare type TabsetNode<TabData = unknown, TabsetData = unknown> = {
1474
1508
  * - Percentages (and strings without units) are not allowed
1475
1509
  */
1476
1510
  minHeight?: string | undefined;
1511
+ /**
1512
+ * Maximum width of the tabset's content area (not including its header).
1513
+ *
1514
+ * ℹ️ Interpretation rules:
1515
+ * - Strings must specify a unit: "px", "em", "rem", "vh", or "vw" (e.g. `maxWidth: "400px"`)
1516
+ * - Percentages (and strings without units) are not allowed
1517
+ * - If the tabset's minimum width is larger, the minimum is used
1518
+ *
1519
+ * ⚠️ A maximum only applies if something else can take up the rest of the space, e.g. another tabset in the same split without a maximum width;
1520
+ * otherwise it's ignored (e.g. if every tabset in a split has a maximum, or the tabset fills the workspace).
1521
+ */
1522
+ maxWidth?: string | undefined;
1523
+ /**
1524
+ * Maximum height of the tabset's content area (not including its header).
1525
+ *
1526
+ * ℹ️ Interpretation rules:
1527
+ * - Strings must specify a unit: "px", "em", "rem", "vh", or "vw" (e.g. `maxHeight: "400px"`)
1528
+ * - Percentages (and strings without units) are not allowed
1529
+ * - If the tabset's minimum height is larger, the minimum is used
1530
+ *
1531
+ * ⚠️ A maximum only applies if something else can take up the rest of the space, e.g. another tabset in the same split without a maximum height;
1532
+ * otherwise it's ignored (e.g. if every tabset in a split has a maximum, or the tabset fills the workspace).
1533
+ */
1534
+ maxHeight?: string | undefined;
1477
1535
  /**
1478
1536
  * Where the tabset's tabs are placed relative to its content.
1479
1537
  * Overrides the Workspace's `tabPlacement` prop.
@@ -1501,6 +1559,11 @@ export declare type TabsetNode<TabData = unknown, TabsetData = unknown> = {
1501
1559
  *
1502
1560
  * ℹ️ The only tabset in a workspace (the root) can't be collapsed, and neither can a tabset whose siblings are all collapsed.
1503
1561
  *
1562
+ * ℹ️ When tabsets don't fit (e.g. the workspace is made narrower than their minimum sizes), a collapsible tabset may be collapsed to fit.
1563
+ * It's shown collapsed (see `useParentTabsetState().isCollapsedToFit`), but the model isn't changed, so it's shown expanded again once it fits.
1564
+ * Until then, it can't be expanded: clicking one of its tabs selects the tab, and `expandTabset` does nothing.
1565
+ * A resize of its split doesn't change it either (it stays expanded in the model, with its size), unless the resize expands it.
1566
+ *
1504
1567
  * ℹ️ Tabsets created by the workspace (e.g. by dropping a tab onto the edge of another tabset) don't keep this flag.
1505
1568
  */
1506
1569
  collapsible?: boolean | undefined;
@@ -1729,6 +1792,17 @@ export declare function useParentTabState(): ParentTabState | null;
1729
1792
  */
1730
1793
  export declare function useParentWorkspace<TabData = unknown, TabsetData = unknown>(): ParentWorkspace<TabData, TabsetData> | null;
1731
1794
 
1795
+ /**
1796
+ * Returns the space (in pixels) in the nearest ancestor tabset's tab list that its tabs don't use (negative once they overflow),
1797
+ * e.g. for a toolbar (see `renderTabsetToolbar`) that moves items into an overflow menu when the tabset's header runs out of room;
1798
+ * see `WorkspaceImperativeHandle.getTabListFreeSpace`.
1799
+ *
1800
+ * ℹ️ The component re-renders when the free space changes, before the browser paints.
1801
+ *
1802
+ * @returns The free space, or `undefined` 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)
1803
+ */
1804
+ export declare function useTabListFreeSpace(): number | undefined;
1805
+
1732
1806
  /**
1733
1807
  * Convenience hook to return a properly typed ref callback for the Workspace component.
1734
1808
  *
@@ -1859,6 +1933,10 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
1859
1933
  collapseTabset: (tabsetId: string) => void;
1860
1934
  /**
1861
1935
  * Expand a collapsed tabset to its previous size.
1936
+ *
1937
+ * ℹ️ Tabsets are shown at least at their minimum sizes (if they fit), even if the model's sizes are smaller (see `TabsetNode.size`).
1938
+ *
1939
+ * ℹ️ This has no effect on a tabset that's only collapsed to fit, which is expanded once it fits (see `TabsetNode.collapsible`).
1862
1940
  */
1863
1941
  expandTabset: (tabsetId: string) => void;
1864
1942
  /**
@@ -1869,6 +1947,23 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
1869
1947
  * Get the current model.
1870
1948
  */
1871
1949
  getModel: () => WorkspaceModel<TabData, TabsetData>;
1950
+ /**
1951
+ * Space (in pixels) in a tabset's tab list that its tabs don't use, e.g. how much a toolbar beside the tabs could grow
1952
+ * before they overflow (and how much space an overflow menu needs to free up, once it's negative).
1953
+ *
1954
+ * ℹ️ The space is measured along the tab list: its width, or its height if its tabs are placed on the left or right
1955
+ * (or the tabset is collapsed to a vertical strip).
1956
+ * If the tab list can't shrink any further (e.g. it's 0px wide, beside a toolbar that doesn't shrink), the amount the header's content
1957
+ * overflows the header is subtracted too, so it's still how much space a toolbar needs to free up.
1958
+ *
1959
+ * ℹ️ The tab list's `--tab-list-free-space` custom property has the same value (e.g. "120px").
1960
+ *
1961
+ * ℹ️ Within a tabset (e.g. its toolbar), the `useTabListFreeSpace` hook returns this value (and re-renders when it changes).
1962
+ *
1963
+ * @returns The free space, or `undefined` if the tabset isn't rendered (or hasn't been measured yet, e.g. while server rendering,
1964
+ * or right after the tabset is first rendered: it's measured after React commits, before the browser paints)
1965
+ */
1966
+ getTabListFreeSpace: (tabsetId: string) => number | undefined;
1872
1967
  /**
1873
1968
  * Maximize a tabset, so that it covers the rest of the workspace.
1874
1969
  *
@@ -1878,11 +1973,14 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
1878
1973
  maximizeTabset: (tabsetId: string) => void;
1879
1974
  /**
1880
1975
  * Move a tab to a position within a tabset's tab list, or to a region of a tabset's content area.
1976
+ *
1977
+ * ℹ️ The `"left"` and `"right"` regions are sides of the screen (so they're mirrored in right-to-left layouts).
1881
1978
  */
1882
1979
  moveTab: (tabId: string, target: TabDropTarget) => void;
1883
1980
  /**
1884
1981
  * Move a tabset beside another tabset (by dropping it onto a region at the edge of that tabset's content area),
1885
1982
  * or move its tabs into another tabset (at an `index` within its tab list, or onto the `"center"` of its content area).
1983
+ * The `"left"` and `"right"` regions are sides of the screen (so they're mirrored in right-to-left layouts).
1886
1984
  *
1887
1985
  * ℹ️ When its tabs are moved, the emptied tabset is removed (unless it has the `keepWhenEmpty` flag).
1888
1986
  */
@@ -1901,6 +1999,18 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
1901
1999
  * @return Applied model (after normalization)
1902
2000
  */
1903
2001
  setModel: (model: WorkspaceModelInput<TabData, TabsetData>) => WorkspaceModel<TabData, TabsetData>;
2002
+ /**
2003
+ * Subscribe to changes to the free space in a tabset's tab list (see `getTabListFreeSpace`),
2004
+ * e.g. from a toolbar rendered outside of the Workspace.
2005
+ *
2006
+ * ℹ️ The listener is called synchronously when the tab list is measured (when it or its tabs change size, or tabs are added or removed),
2007
+ * before the browser paints; changes it makes to the DOM (e.g. with `flushSync`) are shown in the same frame.
2008
+ *
2009
+ * ℹ️ The listener is called with `undefined` when the tabset is removed (e.g. closed, or merged into another tabset).
2010
+ *
2011
+ * @returns A function that unsubscribes the listener
2012
+ */
2013
+ subscribeToTabListFreeSpace: (tabsetId: string, listener: (freeSpace: number | undefined) => void) => () => void;
1904
2014
  /**
1905
2015
  * Update a tab; fields that are not specified are not changed.
1906
2016
  *
@@ -1918,13 +2028,15 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
1918
2028
  * ℹ️ `data` is replaced rather than merged.
1919
2029
  *
1920
2030
  * ℹ️ Setting `minHeight`, `minWidth`, or `tabPlacement` to `undefined` removes the tabset's override,
1921
- * so the corresponding Workspace prop is used.
2031
+ * so the corresponding Workspace prop is used; setting `maxHeight` or `maxWidth` to `undefined` removes the maximum.
1922
2032
  */
1923
2033
  updateTabset: (tabsetId: string, changes: {
1924
2034
  collapsible?: boolean | undefined;
1925
2035
  data?: TabsetData;
1926
2036
  disableDrag?: boolean | undefined;
1927
2037
  keepWhenEmpty?: boolean | undefined;
2038
+ maxHeight?: string | undefined;
2039
+ maxWidth?: string | undefined;
1928
2040
  minHeight?: string | undefined;
1929
2041
  minWidth?: string | undefined;
1930
2042
  tabPlacement?: TabsetNode["tabPlacement"];
@@ -2057,7 +2169,7 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
2057
2169
  renderDragPreview?: ((tab: TabNode<TabData>) => ReactNode) | undefined;
2058
2170
  /**
2059
2171
  * Content of the element that follows the pointer while a whole tabset is being dragged.
2060
- * Defaults to the preview of its selected tab (see `renderDragPreview`), or the tabset's id if it has no tabs.
2172
+ * 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.
2061
2173
  *
2062
2174
  * ℹ️ The element has a `data-drag-type` attribute: `"tabset"` while a tabset is dragged, and `"tab"` while a tab is.
2063
2175
  */
@@ -2155,6 +2267,10 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
2155
2267
  *
2156
2268
  * ℹ️ 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).
2157
2269
  *
2270
+ * ℹ️ "left" and "right" are the start and end of the tabset (its header is rendered before or after its content),
2271
+ * so in a right-to-left layout (e.g. within `dir="rtl"`) tabs placed on the "left" are on the right;
2272
+ * styles for them should use logical properties (e.g. `border-inline-end` rather than `border-right`).
2273
+ *
2158
2274
  * ℹ️ Tabsets can override this with the `tabPlacement` field of their model node.
2159
2275
  *
2160
2276
  * @default "top"