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.
package/README.md CHANGED
@@ -866,7 +866,7 @@ its default `aria-label` ("Collapse tabset") doesn't change, since `aria-expande
866
866
 
867
867
  To keep the tabset as it is, call `event.preventDefault()` in an `onClick` handler.
868
868
 
869
- ℹ️ Clicking a tab of a collapsed tabset also expands it.
869
+ ℹ️ Clicking a tab of a collapsed tabset also expands it (unless the workspace is `disabled`, which doesn't restrict this button).
870
870
 
871
871
  #### Required props
872
872
 
@@ -1033,8 +1033,8 @@ The layout is described by a serializable model (see `WorkspaceModel`).
1033
1033
  Workspaces are uncontrolled: provide an initial model with the `defaultModel` prop, save changes from the `onModelChanged` callback,
1034
1034
  and make changes using the imperative API (see `WorkspaceImperativeHandle`).
1035
1035
 
1036
- ℹ️ Tab content is not remounted when a tab is moved.
1037
- Its elements are moved within the document, though, which resets some browser state (e.g. iframes are reloaded).
1036
+ ℹ️ 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;
1037
+ browsers that don't support `moveBefore` (e.g. Safari) reset some of that state (e.g. iframes are reloaded).
1038
1038
 
1039
1039
  Workspace elements always include the following attributes:
1040
1040
 
@@ -1170,7 +1170,8 @@ leaving the dragged tabset where it was. The change is reported to <code>onModel
1170
1170
  <tr>
1171
1171
  <td>disabled</td>
1172
1172
  <td><p>Locks the arrangement: tabs cannot be resized, dragged, dropped, or closed by the user.
1173
- Selecting tabs and maximizing tabsets still work.</p>
1173
+ Selecting tabs and maximizing tabsets still work, but tabsets aren&#39;t collapsed or expanded by clicking their tabs (or the empty space in their headers);
1174
+ clicking a tab of a collapsed tabset only selects it. A <code>TabsetCollapseButton</code> isn&#39;t restricted by <code>disabled</code>; to keep tabsets from being collapsed or expanded, don&#39;t render one.</p>
1174
1175
  <p>ℹ️ This prop overrides the <code>disableClose</code> and <code>disableDrag</code> flags of individual tabs.</p>
1175
1176
  </td>
1176
1177
  </tr>
@@ -1191,7 +1192,8 @@ returning <code>true</code> rejects the target.</p>
1191
1192
  so restrictions on where tabs can be dropped apply to dragged tabsets too.</p>
1192
1193
  <p>ℹ️ 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
1193
1194
  (except over tabset headers, where the tab lists are) or within its root element&#39;s padding.
1194
- These targets have an <code>edge</code> rather than a <code>tabsetId</code>; <code>disableDrop={({ target }) =&gt; &quot;edge&quot; in target}</code> turns them off.</p>
1195
+ These targets have an <code>edge</code> rather than a <code>tabsetId</code>; <code>disableDrop={({ target }) =&gt; &quot;edge&quot; in target}</code> turns them off.
1196
+ (Where a collapsed tabset lines an edge, drops there are added to the end of its tab list, so those targets have an <code>index</code> and <code>tabsetId</code> instead.)</p>
1195
1197
  </td>
1196
1198
  </tr>
1197
1199
  <tr>
@@ -1208,6 +1210,16 @@ A tab dragged to another workspace is rendered by that workspace, so its content
1208
1210
  <p>⚠️ A tab dragged to another copy of the application is sent there with the structured clone algorithm (like <code>postMessage</code>), so its data must be cloneable (e.g. no functions);
1209
1211
  tabs whose data can&#39;t be cloned (and tabsets containing them) can only be dragged within their copy of the application.
1210
1212
  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&#39;t recognize.</p>
1213
+ </td>
1214
+ </tr>
1215
+ <tr>
1216
+ <td>dragSourceInfo</td>
1217
+ <td><p>Information about this workspace that&#39;s sent with the tabs (and tabsets) dragged from it (see the <code>dragGroup</code> prop),
1218
+ so that the workspaces they&#39;re dragged into can tell where they came from (see <code>DisableDropArgs.sourceInfo</code> and <code>WorkspaceChangedMeta.sourceInfo</code>),
1219
+ e.g. <code>{ app: &quot;reports&quot;, schemaVersion: 3 }</code>.</p>
1220
+ <p>⚠️ It&#39;s sent to other copies of the application with the structured clone algorithm (like tab data; see <code>dragGroup</code>), so it must be cloneable;
1221
+ drags whose source info can&#39;t be cloned can only be dropped within their copy of the application.
1222
+ It&#39;s read when a drag starts, so changes during a drag don&#39;t apply to it.</p>
1211
1223
  </td>
1212
1224
  </tr>
1213
1225
  <tr>
@@ -1217,7 +1229,7 @@ Copies loaded at different times may be running different versions of the applic
1217
1229
  </tr>
1218
1230
  <tr>
1219
1231
  <td>hiddenTabBehavior</td>
1220
- <td><p>What happens to the content of tabs that are not selected.
1232
+ <td><p>What happens to the content of tabs that aren&#39;t visible, once it has been mounted (see <code>lazyTabContent</code>).
1221
1233
  Can be a function to choose per tab (e.g. based on its data).</p>
1222
1234
  <ul>
1223
1235
  <li><code>&quot;keep-mounted&quot;</code>: content stays mounted (and its effects keep running)</li>
@@ -1225,9 +1237,38 @@ Can be a function to choose per tab (e.g. based on its data).</p>
1225
1237
  requires React 19.2 (falls back to <code>&quot;keep-mounted&quot;</code> otherwise)</li>
1226
1238
  <li><code>&quot;unmount&quot;</code>: content is unmounted</li>
1227
1239
  </ul>
1228
- <p>ℹ️ Moving a tab never remounts its content.</p>
1229
- <p>⚠️ Its React state is preserved, but its elements are moved within the document, which resets some browser state:
1230
- iframes are reloaded, playing media is paused, and focused elements are blurred.</p>
1240
+ <p>ℹ️ A tab is visible when it&#39;s selected, in a tabset that isn&#39;t collapsed or covered by a maximized tabset (floating tabsets aren&#39;t covered);
1241
+ so e.g. collapsing a tabset hides its selected tab&#39;s content, and maximizing one hides the others&#39;.
1242
+ Temporary collapsed states (e.g. while dragging a separator, or when collapsed to fit) don&#39;t hide content.</p>
1243
+ <p>ℹ️ Moving a tab never remounts its content (unless the move hides it and <code>hiddenTabBehavior</code> is <code>&quot;unmount&quot;</code>).</p>
1244
+ <p>ℹ️ Its React state is preserved, and where possible its elements are moved within the document using <code>moveBefore</code>, which preserves browser state (iframes aren&#39;t reloaded, playing media isn&#39;t paused, and focused elements stay focused).</p>
1245
+ <p>⚠️ Browsers that don&#39;t support <code>moveBefore</code> (e.g. Safari) reset some of that state when a tab moves: iframes are reloaded, playing media is paused, and focused elements are blurred.</p>
1246
+ </td>
1247
+ </tr>
1248
+ <tr>
1249
+ <td>lazyTabContent</td>
1250
+ <td><p>Don&#39;t mount a tab&#39;s content until the tab is first visible (e.g. for expensive content in tabsets with many tabs, or in tabsets that start collapsed);
1251
+ otherwise every tab&#39;s content is mounted along with the workspace.
1252
+ Can be a function to choose per tab (e.g. based on its data), e.g. <code>(tab) =&gt; tab.data.isExpensive</code>.</p>
1253
+ <p>Once mounted, content that isn&#39;t visible is kept mounted, hidden in an <code>Activity</code>, or unmounted, as <code>hiddenTabBehavior</code> says.</p>
1254
+ <p>ℹ️ A tab is visible when it&#39;s selected, in a tabset that isn&#39;t collapsed or covered by a maximized tabset (floating tabsets aren&#39;t covered).</p>
1255
+ </td>
1256
+ </tr>
1257
+ <tr>
1258
+ <td>onBeforeModelChange</td>
1259
+ <td><p>Called before a change the user makes (e.g. closing a tab, or dropping a tab that was dragged) is applied to the model;
1260
+ return <code>false</code> to block it, which leaves the model as it is (and <code>onModelChanged</code> isn&#39;t called).</p>
1261
+ <p>e.g. to lock the layout while only allowing some interactions (selecting a tab in a collapsed tabset is an &quot;expand&quot; change, and pressing a floating tabset is a &quot;raise&quot; change):
1262
+ <code>onBeforeModelChange={({ reason }) =&gt; !isLocked || [&quot;select&quot;, &quot;expand&quot;, &quot;raise&quot;, &quot;maximize&quot;, &quot;restore&quot;].includes(reason)}</code></p>
1263
+ <p>Or to keep tabs with unsaved changes from being closed (however they&#39;re closed, e.g. with their close buttons or the Delete key):
1264
+ <code>onBeforeModelChange={({ reason, removedTabs }) =&gt; reason !== &quot;close&quot; || !removedTabs.some((tab) =&gt; tab.data.isDirty)}</code></p>
1265
+ <p>ℹ️ It&#39;s called synchronously; to ask the user first (e.g. &quot;Save changes before closing?&quot;), block the change and then make it with the imperative API (e.g. <code>closeTab</code>) if they confirm.</p>
1266
+ <p>ℹ️ Changes made with the imperative API (including the handles returned by hooks like <code>useParentTab</code>, e.g. from a custom close button) aren&#39;t passed to it, since the application makes those itself.
1267
+ Neither is the removal of a tab (or tabset) that another workspace has accepted (see the <code>dragGroup</code> prop), or one that was torn off (see <code>onTearOff</code>),
1268
+ since it has already been added elsewhere; use <code>disableDrop</code> (or the <code>disableDrag</code> flags) to keep tabs from being dragged out instead.
1269
+ A workspace that a tab is dropped into can block the drop, in which case it stays in the workspace it was dragged from.</p>
1270
+ <p>ℹ️ Blocked resizes are undone (e.g. a separator dragged by the user moves back). Drops are blocked when the pointer is released,
1271
+ so use <code>disableDrop</code> to show while dragging that a target doesn&#39;t accept drops.</p>
1231
1272
  </td>
1232
1273
  </tr>
1233
1274
  <tr>
@@ -1624,13 +1665,20 @@ The easiest way to interact with this API is to use the `useWorkspaceRef` and `u
1624
1665
  <tbody>
1625
1666
  <tr>
1626
1667
  <td>addTab</td>
1627
- <td><p>Add a tab to a tabset.</p>
1668
+ <td><p>Add a tab to a tabset, or in a new tabset at any target <code>moveTab</code> accepts (e.g. in a new split below a tabset, or at an edge of the workspace).</p>
1628
1669
  <p>ℹ️ If a tab with the same id already exists, it is selected instead (and its data is not changed).</p>
1670
+ <p>ℹ️ A tab added in a new tabset is that tabset&#39;s selected tab (so <code>select</code> doesn&#39;t apply); like a moved tab, it&#39;s added to a floating tabset rather than splitting it.</p>
1629
1671
  <ul>
1630
1672
  <li><code>tab</code> Tab to add</li>
1631
- <li><code>options</code> .tabsetId Tabset to add the tab to; defaults to the active tabset</li>
1632
- <li><code>options</code> .index Position within the tabset; defaults to the end</li>
1633
- <li><code>options</code> .select Select the new tab; defaults to true</li>
1673
+ <li><code>options.tabsetId</code> Tabset to add the tab to; defaults to the active tabset</li>
1674
+ <li><code>options.index</code> Position within the tabset; defaults to the end</li>
1675
+ <li><code>options.select</code> Select the new tab; defaults to true</li>
1676
+ <li><code>options.target</code> Where to add the tab (see <code>TabDropTarget</code>); takes precedence over <code>tabsetId</code> and <code>index</code></li>
1677
+ <li><code>options.size</code> Size of the new tabset, when <code>target</code> creates one (an edge region of a tabset, or an edge of the workspace), as its share of the split it&#39;s in.
1678
+ Numbers are percentages (as in the model, see <code>TabsetNode.size</code>); strings may have units (e.g. <code>&quot;200px&quot;</code>), and are converted to percentages of the split&#39;s current size.
1679
+ 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&#39;t have enough room, its siblings shrink in proportion to their sizes instead.
1680
+ Defaults to half of the tabset it splits; at an edge of the workspace, an equal share of the root split (if it&#39;s in the same direction), or else half of the workspace.
1681
+ Invalid sizes (e.g. <code>NaN</code> or <code>&quot;abc&quot;</code>) are ignored, with a warning in development.</li>
1634
1682
  </ul>
1635
1683
  </td>
1636
1684
  </tr>
@@ -1734,6 +1782,10 @@ The <code>&quot;left&quot;</code> and <code>&quot;right&quot;</code> regions (an
1734
1782
  Floating tabsets can&#39;t be split, so a tabset moved to an edge region of one has its tabs moved into it instead (like the <code>&quot;center&quot;</code> region).</p>
1735
1783
  </td>
1736
1784
  </tr>
1785
+ <tr>
1786
+ <td>resizeSplit</td>
1787
+ <td></td>
1788
+ </tr>
1737
1789
  <tr>
1738
1790
  <td>restoreTabset</td>
1739
1791
  <td><p>Restore the maximized tabset (if there is one).</p>