react-resizable-panels 4.18.1 → 4.19.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.
package/README.md CHANGED
@@ -71,7 +71,7 @@ None
71
71
  <td>id</td>
72
72
  <td><p>Uniquely identifies this group within an application.
73
73
  Falls back to <code>useId</code> when not provided.</p>
74
- <p>ℹ️ This value will also be assigned to the <code>id</code> and <code>data-testid</code> attributes; (an explicit <code>data-testid</code> prop will take precedence).</p>
74
+ <p>ℹ️ This value will also be assigned to the <code>id</code> and <code>data-testid</code> attributes (an explicit <code>data-testid</code> prop will take precedence).</p>
75
75
  </td>
76
76
  </tr>
77
77
  <tr>
@@ -116,7 +116,7 @@ Use this prop to disable that behavior for Panels and Separators in this group.<
116
116
  <li><code>getLayout(): Layout</code></li>
117
117
  <li><code>setLayout(layout: Layout): Layout</code></li>
118
118
  </ul>
119
- <p>ℹ️ The <code>useGroupRef</code> and <code>useGroupCallbackRef</code> hooks are exported for convenience use in TypeScript projects.</p>
119
+ <p>ℹ️ The <code>useGroupRef</code> and <code>useGroupCallbackRef</code> hooks are exported for convenience in TypeScript projects.</p>
120
120
  </td>
121
121
  </tr>
122
122
  <tr>
@@ -129,8 +129,8 @@ For most cases, it is recommended to use the <code>onLayoutChanged</code> callba
129
129
  <tr>
130
130
  <td>onLayoutChanged</td>
131
131
  <td><p>Called after the Group&#39;s layout has been changed.</p>
132
- <p>ℹ️ For layout changes caused by pointer events, this method is not called until the pointer has been released.
133
- This method is recommended when saving layouts to some storage api.</p>
132
+ <p>ℹ️ For layout changes caused by pointer events, this callback is not called until the pointer has been released.
133
+ This callback is recommended for saving layouts to storage.</p>
134
134
  <p>ℹ️ The second argument contains meta information about the layout change.
135
135
  The <code>isUserInteraction</code> attribute signals whether the resize was caused by direct user input.
136
136
  It is true for resizes caused by pointer or keyboard input
@@ -227,7 +227,7 @@ None
227
227
  <td><p>Uniquely identifies this panel within the parent group.
228
228
  Falls back to <code>useId</code> when not provided.</p>
229
229
  <p>ℹ️ This prop is used to associate persisted group layouts with the original panel.</p>
230
- <p>ℹ️ This value will also be assigned to the <code>id</code> and <code>data-testid</code> attributes; (an explicit <code>data-testid</code> prop will take precedence).</p>
230
+ <p>ℹ️ This value will also be assigned to the <code>id</code> and <code>data-testid</code> attributes (an explicit <code>data-testid</code> prop will take precedence).</p>
231
231
  </td>
232
232
  </tr>
233
233
  <tr>
@@ -337,7 +337,7 @@ Defaults to <code>preserve-relative-size</code>.</p>
337
337
  <li><code>isCollapsed(): boolean</code></li>
338
338
  <li><code>resize(size: number | string): void</code></li>
339
339
  </ul>
340
- <p>ℹ️ The <code>usePanelRef</code> and <code>usePanelCallbackRef</code> hooks are exported for convenience use in TypeScript projects.</p>
340
+ <p>ℹ️ The <code>usePanelRef</code> and <code>usePanelCallbackRef</code> hooks are exported for convenience in TypeScript projects.</p>
341
341
  </td>
342
342
  </tr>
343
343
  </tbody>
@@ -392,7 +392,7 @@ None
392
392
  <td>id</td>
393
393
  <td><p>Uniquely identifies the separator within the parent group.
394
394
  Falls back to <code>useId</code> when not provided.</p>
395
- <p>ℹ️ This value will also be assigned to the <code>id</code> and <code>data-testid</code> attributes; (an explicit <code>data-testid</code> prop will take precedence).</p>
395
+ <p>ℹ️ This value will also be assigned to the <code>id</code> and <code>data-testid</code> attributes (an explicit <code>data-testid</code> prop will take precedence).</p>
396
396
  </td>
397
397
  </tr>
398
398
  <tr>
@@ -499,7 +499,7 @@ Grid elements always include the following attributes:
499
499
  <td>id</td>
500
500
  <td><p>Uniquely identifies this grid within an application.
501
501
  Falls back to <code>useId</code> when not provided.</p>
502
- <p>ℹ️ This value will also be assigned to the <code>id</code> and <code>data-testid</code> attributes; (an explicit <code>data-testid</code> prop will take precedence).</p>
502
+ <p>ℹ️ This value will also be assigned to the <code>id</code> and <code>data-testid</code> attributes (an explicit <code>data-testid</code> prop will take precedence).</p>
503
503
  </td>
504
504
  </tr>
505
505
  <tr>
@@ -545,7 +545,7 @@ Use this prop to disable that behavior for this grid.</p>
545
545
  <li><code>getTrackByIndex(axis: &quot;column&quot; | &quot;row&quot;, index: number): GridTrackImperativeHandle</code></li>
546
546
  <li><code>setLayout(layout: Partial&lt;GridLayout&gt;): GridLayout</code></li>
547
547
  </ul>
548
- <p>ℹ️ The <code>useGridRef</code> and <code>useGridCallbackRef</code> hooks are exported for convenience use in TypeScript projects.</p>
548
+ <p>ℹ️ The <code>useGridRef</code> and <code>useGridCallbackRef</code> hooks are exported for convenience in TypeScript projects.</p>
549
549
  </td>
550
550
  </tr>
551
551
  <tr>
@@ -558,8 +558,8 @@ For most cases, it is recommended to use the <code>onLayoutChanged</code> callba
558
558
  <tr>
559
559
  <td>onLayoutChanged</td>
560
560
  <td><p>Called after the Grid&#39;s layout has been changed.</p>
561
- <p>ℹ️ For layout changes caused by pointer events, this method is not called until the pointer has been released.
562
- This method is recommended when saving layouts to some storage api.</p>
561
+ <p>ℹ️ For layout changes caused by pointer events, this callback is not called until the pointer has been released.
562
+ This callback is recommended for saving layouts to storage.</p>
563
563
  </td>
564
564
  </tr>
565
565
  <tr>
@@ -639,7 +639,7 @@ Cell elements always include the following attributes:
639
639
  <td>id</td>
640
640
  <td><p>Uniquely identifies this cell within the parent grid.
641
641
  Falls back to <code>useId</code> when not provided.</p>
642
- <p>ℹ️ This value will also be assigned to the <code>id</code> and <code>data-testid</code> attributes; (an explicit <code>data-testid</code> prop will take precedence).</p>
642
+ <p>ℹ️ This value will also be assigned to the <code>id</code> and <code>data-testid</code> attributes (an explicit <code>data-testid</code> prop will take precedence).</p>
643
643
  </td>
644
644
  </tr>
645
645
  <tr>
@@ -696,7 +696,7 @@ For example:
696
696
  ```
697
697
 
698
698
  A gridline should not be rendered alongside of a Cell that spans across its boundary
699
- (this includes disabled gridlines; an error will be logged to the console);
699
+ (this includes disabled gridlines; in development builds, an error will be logged to the console);
700
700
  render multiple gridlines along the same boundary instead (e.g. before and after the spanning Cell).
701
701
 
702
702
  ℹ️ Once a boundary contains a gridline, it can only be resized using gridlines;
@@ -894,7 +894,7 @@ so it should be memoized (e.g. with <code>useCallback</code>) when tab content i
894
894
  <td>id</td>
895
895
  <td><p>Uniquely identifies this workspace within an application.
896
896
  Falls back to <code>useId</code> when not provided.</p>
897
- <p>ℹ️ This value will also be assigned to the <code>id</code> and <code>data-testid</code> attributes; (an explicit <code>data-testid</code> prop will take precedence).</p>
897
+ <p>ℹ️ This value will also be assigned to the <code>id</code> and <code>data-testid</code> attributes (an explicit <code>data-testid</code> prop will take precedence).</p>
898
898
  </td>
899
899
  </tr>
900
900
  <tr>
@@ -919,6 +919,9 @@ Falls back to <code>useId</code> when not provided.</p>
919
919
  <p>ℹ️ Elements expose their state as data attributes (e.g. <code>data-tab-selected</code>, or <code>data-tabset-dragging</code> while a tabset is dragged), which can be used for styling.
920
920
  Elements within a collapsed tabset have a <code>data-tabset-collapsed</code> attribute.
921
921
  Elements within a tabset also have a <code>data-tab-placement</code> attribute (see <code>tabPlacement</code>).</p>
922
+ <p>ℹ️ The drop indicator is the same element for the whole drag (rendered within the workspace&#39;s root element),
923
+ so it can be animated between regions and tabsets (e.g. <code>transition: inset 250ms</code>).
924
+ Its <code>data-region</code> attribute is the region it covers; while a tab isn&#39;t over any tabset&#39;s panels, it has none and isn&#39;t shown (<code>opacity: 0</code>).</p>
922
925
  <p>ℹ️ Like the render props, this object is part of what tabsets re-render for;
923
926
  in large workspaces, define it outside of the component (or memoize it) rather than inline.</p>
924
927
  </td>
@@ -928,6 +931,14 @@ in large workspaces, define it outside of the component (or memoize it) rather t
928
931
  <td><p>Locks the arrangement: tabs cannot be resized, dragged, dropped, or closed by the user.
929
932
  Selecting tabs and maximizing tabsets still work.</p>
930
933
  <p>ℹ️ This prop overrides the <code>disableClose</code> and <code>disableDrag</code> flags of individual tabs.</p>
934
+ </td>
935
+ </tr>
936
+ <tr>
937
+ <td>disableDragBetweenApps</td>
938
+ <td><p>Keeps drags between workspaces (see <code>dragGroup</code>) within this copy of the application:
939
+ tabs dragged from this workspace can&#39;t be dropped into other copies of the application (e.g. the application loaded in another browser window or tab), and tabs dragged from other copies can&#39;t be dropped into this workspace.
940
+ Workspaces in popout windows rendered by this copy of the application (with portals) are still part of the group.</p>
941
+ <p>Defaults to <code>false</code>, so that workspaces with the same <code>dragGroup</code> in other copies of the application from the same origin can exchange tabs.</p>
931
942
  </td>
932
943
  </tr>
933
944
  <tr>
@@ -937,6 +948,23 @@ Selecting tabs and maximizing tabsets still work.</p>
937
948
  returning <code>true</code> rejects the target.</p>
938
949
  <p>ℹ️ While a tabset is dragged, this function is called for each of its tabs (see <code>DisableDropArgs</code>),
939
950
  so restrictions on where tabs can be dropped apply to dragged tabsets too.</p>
951
+ </td>
952
+ </tr>
953
+ <tr>
954
+ <td>dragGroup</td>
955
+ <td><p>Lets tabs (and tabsets) be dragged between workspaces with the same <code>dragGroup</code>,
956
+ including workspaces in popout windows (opened by the application and rendered into with a portal)
957
+ and in other copies of the application from the same origin, e.g. the application loaded in another browser window or tab (see <code>disableDragBetweenApps</code>).
958
+ Dropping one into another workspace moves it there, keeping its id and data;
959
+ both workspaces report the change to <code>onModelChanged</code> with the <code>&quot;transfer&quot;</code> reason.</p>
960
+ <p>Mouse drags use the browser&#39;s drag and drop when this prop is set, since pointer events can&#39;t follow the pointer into another window.
961
+ Touch drags still use pointer events, so they can&#39;t leave the window.</p>
962
+ <p>ℹ️ Tab ids must be unique within the group; a tab can&#39;t be dropped into a workspace that already has a tab with its id (and a tabset with the <code>keepWhenEmpty</code> flag can&#39;t be dragged to another workspace).
963
+ A tab dragged to another workspace is rendered by that workspace, so its content is mounted again.</p>
964
+ <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);
965
+ tabs whose data can&#39;t be cloned (and tabsets containing them) can only be dragged within their copy of the application.
966
+ 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>
967
+ <p>⚠️ Tabs (and tabsets) can still be torn off (see <code>onTearOff</code>), but some browsers (e.g. Safari) block popup windows opened at the end of a drag that uses the browser&#39;s drag and drop.</p>
940
968
  </td>
941
969
  </tr>
942
970
  <tr>
@@ -962,21 +990,37 @@ iframes are reloaded, playing media is paused, and focused elements are blurred.
962
990
  <tr>
963
991
  <td>onModelChanged</td>
964
992
  <td><p>Called after the model has changed (e.g. a tab was moved, selected, or closed, or a tabset was resized).</p>
965
- <p>ℹ️ For changes caused by pointer events, this method is not called until the pointer has been released.
966
- This method is recommended when saving models to some storage api.</p>
993
+ <p>ℹ️ For changes caused by pointer events, this callback is not called until the pointer has been released.
994
+ This callback is recommended for saving models to storage.</p>
995
+ </td>
996
+ </tr>
997
+ <tr>
998
+ <td>onTearOff</td>
999
+ <td><p>Called when a tab (or a whole tabset) is dropped outside of the window, e.g. to open it in a popup window.
1000
+ Return <code>true</code> to accept it, which removes it from this workspace (reported to <code>onModelChanged</code> with the <code>&quot;tear-off&quot;</code> reason);
1001
+ otherwise nothing changes.</p>
1002
+ <p>Tabs and tabsets can only be torn off if they could be dragged, and tabsets with the <code>keepWhenEmpty</code> flag can&#39;t be torn off.
1003
+ Without this prop, dropping a tab outside of the window does nothing.</p>
1004
+ <p>⚠️ The Workspace can&#39;t tell whether the application showed the tab, so check whether <code>window.open</code> returned <code>null</code> (because the popup was blocked)
1005
+ and return <code>false</code> then to keep the tab; returning <code>true</code> removes it even if nothing shows it.</p>
1006
+ <p>ℹ️ This is called while the release of the pointer is being handled (which browsers treat as user input), so a popup can be opened from it.
1007
+ With the <code>dragGroup</code> prop, a tab is torn off when it&#39;s dropped outside of every window in the group; the end of those drags isn&#39;t treated as user input,
1008
+ so browsers block popups opened then unless the drag started a few seconds earlier at most (and Safari blocks them always).</p>
967
1009
  </td>
968
1010
  </tr>
969
1011
  <tr>
970
1012
  <td>renderDragPreview</td>
971
1013
  <td><p>Content of the element that follows the pointer while a tab is being dragged.
972
1014
  Defaults to the tab&#39;s title (or id).</p>
1015
+ <p>ℹ️ The element has a <code>data-tear-off</code> attribute while releasing the pointer would tear off the tab (see <code>onTearOff</code>).</p>
973
1016
  </td>
974
1017
  </tr>
975
1018
  <tr>
976
1019
  <td>renderTabsetDragPreview</td>
977
1020
  <td><p>Content of the element that follows the pointer while a whole tabset is being dragged.
978
1021
  Defaults to the title (or id) of its selected tab followed by the number of other tabs being dragged (e.g. &quot;One (+2)&quot;), or the selected tab&#39;s <code>renderDragPreview</code> when that prop is set, or the tabset&#39;s id if it has no tabs.</p>
979
- <p>ℹ️ The element has a <code>data-drag-type</code> attribute: <code>&quot;tabset&quot;</code> while a tabset is dragged, and <code>&quot;tab&quot;</code> while a tab is.</p>
1022
+ <p>ℹ️ The element has a <code>data-drag-type</code> attribute: <code>&quot;tabset&quot;</code> while a tabset is dragged, and <code>&quot;tab&quot;</code> while a tab is.
1023
+ It also has a <code>data-tear-off</code> attribute while releasing the pointer would tear off the tabset (see <code>onTearOff</code>).</p>
980
1024
  </td>
981
1025
  </tr>
982
1026
  <tr>
@@ -1093,7 +1137,7 @@ so they&#39;re restored with the rest of the layout.</p>
1093
1137
  <tr>
1094
1138
  <td>workspaceRef</td>
1095
1139
  <td><p>Exposes the imperative API (see <code>WorkspaceImperativeHandle</code>).</p>
1096
- <p>ℹ️ The <code>useWorkspaceRef</code> and <code>useWorkspaceCallbackRef</code> hooks are exported for convenience use in TypeScript projects.</p>
1140
+ <p>ℹ️ The <code>useWorkspaceRef</code> and <code>useWorkspaceCallbackRef</code> hooks are exported for convenience in TypeScript projects.</p>
1097
1141
  </td>
1098
1142
  </tr>
1099
1143
  </tbody>