react-resizable-panels 4.17.0 → 4.18.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.
@@ -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
  */
@@ -1454,6 +1483,9 @@ export declare type TabsetNode<TabData = unknown, TabsetData = unknown> = {
1454
1483
  *
1455
1484
  * ⚠️ String sizes are only initial sizes: they're converted to percentages when the user resizes the split,
1456
1485
  * and (like percentages) they scale with the workspace when it's resized.
1486
+ *
1487
+ * ℹ️ A tabset is shown within its minimum and maximum sizes (see `minWidth` and `maxWidth`), even if its size is outside of them
1488
+ * (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
1489
  */
1458
1490
  size?: number | string | undefined;
1459
1491
  /**
@@ -1474,6 +1506,30 @@ export declare type TabsetNode<TabData = unknown, TabsetData = unknown> = {
1474
1506
  * - Percentages (and strings without units) are not allowed
1475
1507
  */
1476
1508
  minHeight?: string | undefined;
1509
+ /**
1510
+ * Maximum width of the tabset's content area (not including its header).
1511
+ *
1512
+ * ℹ️ Interpretation rules:
1513
+ * - Strings must specify a unit: "px", "em", "rem", "vh", or "vw" (e.g. `maxWidth: "400px"`)
1514
+ * - Percentages (and strings without units) are not allowed
1515
+ * - If the tabset's minimum width is larger, the minimum is used
1516
+ *
1517
+ * ⚠️ 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;
1518
+ * otherwise it's ignored (e.g. if every tabset in a split has a maximum, or the tabset fills the workspace).
1519
+ */
1520
+ maxWidth?: string | undefined;
1521
+ /**
1522
+ * Maximum height of the tabset's content area (not including its header).
1523
+ *
1524
+ * ℹ️ Interpretation rules:
1525
+ * - Strings must specify a unit: "px", "em", "rem", "vh", or "vw" (e.g. `maxHeight: "400px"`)
1526
+ * - Percentages (and strings without units) are not allowed
1527
+ * - If the tabset's minimum height is larger, the minimum is used
1528
+ *
1529
+ * ⚠️ 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;
1530
+ * otherwise it's ignored (e.g. if every tabset in a split has a maximum, or the tabset fills the workspace).
1531
+ */
1532
+ maxHeight?: string | undefined;
1477
1533
  /**
1478
1534
  * Where the tabset's tabs are placed relative to its content.
1479
1535
  * Overrides the Workspace's `tabPlacement` prop.
@@ -1501,6 +1557,11 @@ export declare type TabsetNode<TabData = unknown, TabsetData = unknown> = {
1501
1557
  *
1502
1558
  * ℹ️ The only tabset in a workspace (the root) can't be collapsed, and neither can a tabset whose siblings are all collapsed.
1503
1559
  *
1560
+ * ℹ️ When tabsets don't fit (e.g. the workspace is made narrower than their minimum sizes), a collapsible tabset may be collapsed to fit.
1561
+ * It's shown collapsed (see `useParentTabsetState().isCollapsedToFit`), but the model isn't changed, so it's shown expanded again once it fits.
1562
+ * Until then, it can't be expanded: clicking one of its tabs selects the tab, and `expandTabset` does nothing.
1563
+ * A resize of its split doesn't change it either (it stays expanded in the model, with its size), unless the resize expands it.
1564
+ *
1504
1565
  * ℹ️ Tabsets created by the workspace (e.g. by dropping a tab onto the edge of another tabset) don't keep this flag.
1505
1566
  */
1506
1567
  collapsible?: boolean | undefined;
@@ -1729,6 +1790,17 @@ export declare function useParentTabState(): ParentTabState | null;
1729
1790
  */
1730
1791
  export declare function useParentWorkspace<TabData = unknown, TabsetData = unknown>(): ParentWorkspace<TabData, TabsetData> | null;
1731
1792
 
1793
+ /**
1794
+ * Returns the space (in pixels) in the nearest ancestor tabset's tab list that its tabs don't use (negative once they overflow),
1795
+ * e.g. for a toolbar (see `renderTabsetToolbar`) that moves items into an overflow menu when the tabset's header runs out of room;
1796
+ * see `WorkspaceImperativeHandle.getTabListFreeSpace`.
1797
+ *
1798
+ * ℹ️ The component re-renders when the free space changes, before the browser paints.
1799
+ *
1800
+ * @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)
1801
+ */
1802
+ export declare function useTabListFreeSpace(): number | undefined;
1803
+
1732
1804
  /**
1733
1805
  * Convenience hook to return a properly typed ref callback for the Workspace component.
1734
1806
  *
@@ -1859,6 +1931,10 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
1859
1931
  collapseTabset: (tabsetId: string) => void;
1860
1932
  /**
1861
1933
  * Expand a collapsed tabset to its previous size.
1934
+ *
1935
+ * ℹ️ Tabsets are shown at least at their minimum sizes (if they fit), even if the model's sizes are smaller (see `TabsetNode.size`).
1936
+ *
1937
+ * ℹ️ This has no effect on a tabset that's only collapsed to fit, which is expanded once it fits (see `TabsetNode.collapsible`).
1862
1938
  */
1863
1939
  expandTabset: (tabsetId: string) => void;
1864
1940
  /**
@@ -1869,6 +1945,21 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
1869
1945
  * Get the current model.
1870
1946
  */
1871
1947
  getModel: () => WorkspaceModel<TabData, TabsetData>;
1948
+ /**
1949
+ * 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
1950
+ * before they overflow (and how much space an overflow menu needs to free up, once it's negative).
1951
+ *
1952
+ * ℹ️ The space is measured along the tab list: its width, or its height if its tabs are placed on the left or right
1953
+ * (or the tabset is collapsed to a vertical strip).
1954
+ *
1955
+ * ℹ️ The tab list's `--tab-list-free-space` custom property has the same value (e.g. "120px").
1956
+ *
1957
+ * ℹ️ Within a tabset (e.g. its toolbar), the `useTabListFreeSpace` hook returns this value (and re-renders when it changes).
1958
+ *
1959
+ * @returns The free space, or `undefined` if the tabset isn't rendered (or hasn't been measured yet, e.g. while server rendering,
1960
+ * or right after the tabset is first rendered: it's measured after React commits, before the browser paints)
1961
+ */
1962
+ getTabListFreeSpace: (tabsetId: string) => number | undefined;
1872
1963
  /**
1873
1964
  * Maximize a tabset, so that it covers the rest of the workspace.
1874
1965
  *
@@ -1901,6 +1992,18 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
1901
1992
  * @return Applied model (after normalization)
1902
1993
  */
1903
1994
  setModel: (model: WorkspaceModelInput<TabData, TabsetData>) => WorkspaceModel<TabData, TabsetData>;
1995
+ /**
1996
+ * Subscribe to changes to the free space in a tabset's tab list (see `getTabListFreeSpace`),
1997
+ * e.g. from a toolbar rendered outside of the Workspace.
1998
+ *
1999
+ * ℹ️ The listener is called synchronously when the tab list is measured (when it or its tabs change size, or tabs are added or removed),
2000
+ * before the browser paints; changes it makes to the DOM (e.g. with `flushSync`) are shown in the same frame.
2001
+ *
2002
+ * ℹ️ The listener is called with `undefined` when the tabset is removed (e.g. closed, or merged into another tabset).
2003
+ *
2004
+ * @returns A function that unsubscribes the listener
2005
+ */
2006
+ subscribeToTabListFreeSpace: (tabsetId: string, listener: (freeSpace: number | undefined) => void) => () => void;
1904
2007
  /**
1905
2008
  * Update a tab; fields that are not specified are not changed.
1906
2009
  *
@@ -1918,13 +2021,15 @@ export declare interface WorkspaceImperativeHandle<TabData = unknown, TabsetData
1918
2021
  * ℹ️ `data` is replaced rather than merged.
1919
2022
  *
1920
2023
  * ℹ️ Setting `minHeight`, `minWidth`, or `tabPlacement` to `undefined` removes the tabset's override,
1921
- * so the corresponding Workspace prop is used.
2024
+ * so the corresponding Workspace prop is used; setting `maxHeight` or `maxWidth` to `undefined` removes the maximum.
1922
2025
  */
1923
2026
  updateTabset: (tabsetId: string, changes: {
1924
2027
  collapsible?: boolean | undefined;
1925
2028
  data?: TabsetData;
1926
2029
  disableDrag?: boolean | undefined;
1927
2030
  keepWhenEmpty?: boolean | undefined;
2031
+ maxHeight?: string | undefined;
2032
+ maxWidth?: string | undefined;
1928
2033
  minHeight?: string | undefined;
1929
2034
  minWidth?: string | undefined;
1930
2035
  tabPlacement?: TabsetNode["tabPlacement"];
@@ -2057,7 +2162,7 @@ export declare type WorkspaceProps<TabData = unknown, TabsetData = unknown> = Om
2057
2162
  renderDragPreview?: ((tab: TabNode<TabData>) => ReactNode) | undefined;
2058
2163
  /**
2059
2164
  * 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.
2165
+ * 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
2166
  *
2062
2167
  * ℹ️ The element has a `data-drag-type` attribute: `"tabset"` while a tabset is dragged, and `"tab"` while a tab is.
2063
2168
  */