[pull] main from bvaughn:main

CHANGELOG.md

@@ -1,8 +1,11 @@
 # Changelog
 
-## Unreleased
+## 4.3.0
 
-- Drag interactions only call `event.preventDefault` for the primary button
+- [583](https://github.com/bvaughn/react-resizable-panels/pull/583): `Group` component now sets default `width`, `height`, and `overflow` styles; (both can be overridden using the `style` property)
+- [582](https://github.com/bvaughn/react-resizable-panels/pull/582): Drag interactions only call `event.preventDefault` for the primary button
+- Refine TS types for `useGroupRef` and `usePanelRef` to include `| null` to increase compatibility with older React versions
+- Update TSDoc comments for `Panel` and `Separator` components
 
 ## 4.2.2
 

README.md

@@ -157,6 +157,8 @@ Panel elements always include the following attributes:
 ```
 
 ℹ️ [Test id](https://testing-library.com/docs/queries/bytestid/) can be used to narrow selection when unit testing.
+
+⚠️ Panel elements must be direct DOM children of their parent Group elements.
 <!-- Panel:description:end -->
 
 #### Required props
@@ -259,7 +261,7 @@ Falls back to <code>useId</code> when not provided.</p>
 <!-- Separator:description:begin -->
 Separators are not _required_ but they are _recommended_ as they improve keyboard accessibility.
 
-Separators should be rendered as the direct child of a Group component.
+⚠️ Separator elements must be direct DOM children of their parent Group elements.
 
 Separator elements always include the following attributes:
 

integrations/vite/tests/cursor.spec.tsx

@@ -90,7 +90,7 @@ test.describe("cursor", () => {
       test("intersecting", async ({ page: mainPage }) => {
         const page = await goToUrl(
           mainPage,
-          <Group orientation="vertical">
+          <Group className="h-[250px]!" orientation="vertical">
             <Panel id="top" minSize="25%" />
             <Separator id="vertical-separator" />
             <Panel id="bottom" minSize="25%">

lib/components/group/Group.tsx

@@ -258,6 +258,9 @@ export function Group({
         id={id}
         ref={mergedRef}
         style={{
+          height: "100%",
+          width: "100%",
+          overflow: "hidden",
           ...style,
           ...cssVariables,
           display: "flex",

lib/components/group/types.ts

@@ -104,7 +104,7 @@ export type GroupProps = HTMLAttributes<HTMLDivElement> & {
   /**
    * Ref attached to the root `HTMLDivElement`.
    */
-  elementRef?: Ref<HTMLDivElement> | undefined;
+  elementRef?: Ref<HTMLDivElement | null> | undefined;
 
   /**
    * Exposes the following imperative API:
@@ -113,7 +113,7 @@ export type GroupProps = HTMLAttributes<HTMLDivElement> & {
    *
    * ℹ️ The `useGroupRef` and `useGroupCallbackRef` hooks are exported for convenience use in TypeScript projects.
    */
-  groupRef?: Ref<GroupImperativeHandle> | undefined;
+  groupRef?: Ref<GroupImperativeHandle | null> | undefined;
 
   /**
    * Uniquely identifies this group within an application.

lib/components/group/useGroupRef.ts

@@ -5,5 +5,5 @@ import type { GroupImperativeHandle } from "./types";
  * Convenience hook to return a properly typed ref for the Group component.
  */
 export function useGroupRef() {
-  return useRef<GroupImperativeHandle>(null);
+  return useRef<GroupImperativeHandle | null>(null);
 }

lib/components/panel/Panel.tsx

@@ -34,6 +34,8 @@ import { usePanelImperativeHandle } from "./usePanelImperativeHandle";
  * ```
  *
  * ℹ️ [Test id](https://testing-library.com/docs/queries/bytestid/) can be used to narrow selection when unit testing.
+ *
+ * ⚠️ Panel elements must be direct DOM children of their parent Group elements.
  */
 export function Panel({
   children,

lib/components/panel/types.ts

@@ -118,7 +118,7 @@ export type PanelProps = BasePanelAttributes & {
   /**
    * Ref attached to the root `HTMLDivElement`.
    */
-  elementRef?: Ref<HTMLDivElement> | undefined;
+  elementRef?: Ref<HTMLDivElement | null> | undefined;
 
   /**
    * Uniquely identifies this panel within the parent group.
@@ -165,7 +165,7 @@ export type PanelProps = BasePanelAttributes & {
    *
    * ℹ️ The `usePanelRef` and `usePanelCallbackRef` hooks are exported for convenience use in TypeScript projects.
    */
-  panelRef?: Ref<PanelImperativeHandle> | undefined;
+  panelRef?: Ref<PanelImperativeHandle | null> | undefined;
 
   /**
    * CSS properties.

lib/components/panel/usePanelRef.ts

@@ -5,5 +5,5 @@ import type { PanelImperativeHandle } from "./types";
  * Convenience hook to return a properly typed ref for the Panel component.
  */
 export function usePanelRef() {
-  return useRef<PanelImperativeHandle>(null);
+  return useRef<PanelImperativeHandle | null>(null);
 }

lib/components/separator/Separator.tsx

@@ -13,7 +13,7 @@ import type { RegisteredSeparator, SeparatorProps } from "./types";
 /**
  * Separators are not _required_ but they are _recommended_ as they improve keyboard accessibility.
  *
- * Separators should be rendered as the direct child of a Group component.
+ * ⚠️ Separator elements must be direct DOM children of their parent Group elements.
  *
  * Separator elements always include the following attributes:
  *

lib/global/utils/findSeparatorGroup.ts

@@ -1,14 +1,14 @@
-import { assert } from "../../utils/assert";
 import { read } from "../mutableState";
 
 export function findSeparatorGroup(separatorElement: HTMLElement) {
-  const groupElement = separatorElement.parentElement;
-  assert(groupElement, "Parent group element not found");
-
   const { mountedGroups } = read();
 
   for (const [group] of mountedGroups) {
-    if (group.element === groupElement) {
+    if (
+      group.separators.some(
+        (separator) => separator.element === separatorElement
+      )
+    ) {
       return group;
     }
   }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-resizable-panels",
-  "version": "4.2.2",
+  "version": "4.3.0",
   "type": "module",
   "author": "Brian Vaughn <brian.david.vaughn@gmail.com> (https://github.com/bvaughn/)",
   "contributors": [

public/generated/docs/Group.json

@@ -109,7 +109,7 @@
           "content": "<p>Ref attached to the root <code>HTMLDivElement</code>.</p>\n"
         }
       ],
-      "html": "<div><span class=\"tok-variableName\"><span class=\"tok-propertyName\">elementRef</span></span><span class=\"tok-operator\">?</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-variableName\">Ref</span><span class=\"\">&#60;</span><span class=\"tok-typeName\">HTMLDivElement</span><span class=\"\">&#62;</span></div>",
+      "html": "<div><span class=\"tok-variableName\"><span class=\"tok-propertyName\">elementRef</span></span><span class=\"tok-operator\">?</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-variableName\">Ref</span><span class=\"\">&#60;</span><span class=\"tok-typeName\">HTMLDivElement</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-keyword\">null</span><span class=\"\">&#62;</span></div>",
       "name": "elementRef",
       "required": false
     },
@@ -123,7 +123,7 @@
           "intent": "primary"
         }
       ],
-      "html": "<div><span class=\"tok-variableName\"><span class=\"tok-propertyName\">groupRef</span></span><span class=\"tok-operator\">?</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-variableName\">Ref</span><span class=\"\">&#60;</span><span class=\"tok-typeName\">GroupImperativeHandle</span><span class=\"\">&#62;</span></div>",
+      "html": "<div><span class=\"tok-variableName\"><span class=\"tok-propertyName\">groupRef</span></span><span class=\"tok-operator\">?</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-variableName\">Ref</span><span class=\"\">&#60;</span><span class=\"tok-typeName\">GroupImperativeHandle</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-keyword\">null</span><span class=\"\">&#62;</span></div>",
       "name": "groupRef",
       "required": false
     },

public/generated/docs/Panel.json

@@ -19,6 +19,10 @@
     {
       "content": "<p><a href=\"https://testing-library.com/docs/queries/bytestid/\">Test id</a> can be used to narrow selection when unit testing.</p>\n",
       "intent": "primary"
+    },
+    {
+      "content": "<p>Panel elements must be direct DOM children of their parent Group elements.</p>\n",
+      "intent": "warning"
     }
   ],
   "filePath": "lib/components/panel/Panel.tsx",
@@ -110,7 +114,7 @@
           "content": "<p>Ref attached to the root <code>HTMLDivElement</code>.</p>\n"
         }
       ],
-      "html": "<div><span class=\"tok-variableName\"><span class=\"tok-propertyName\">elementRef</span></span><span class=\"tok-operator\">?</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-variableName\">Ref</span><span class=\"\">&#60;</span><span class=\"tok-typeName\">HTMLDivElement</span><span class=\"\">&#62;</span></div>",
+      "html": "<div><span class=\"tok-variableName\"><span class=\"tok-propertyName\">elementRef</span></span><span class=\"tok-operator\">?</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-variableName\">Ref</span><span class=\"\">&#60;</span><span class=\"tok-typeName\">HTMLDivElement</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-keyword\">null</span><span class=\"\">&#62;</span></div>",
       "name": "elementRef",
       "required": false
     },
@@ -154,7 +158,7 @@
           "intent": "primary"
         }
       ],
-      "html": "<div><span class=\"tok-variableName\"><span class=\"tok-propertyName\">panelRef</span></span><span class=\"tok-operator\">?</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-variableName\">Ref</span><span class=\"\">&#60;</span><span class=\"tok-typeName\">PanelImperativeHandle</span><span class=\"\">&#62;</span></div>",
+      "html": "<div><span class=\"tok-variableName\"><span class=\"tok-propertyName\">panelRef</span></span><span class=\"tok-operator\">?</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-variableName\">Ref</span><span class=\"\">&#60;</span><span class=\"tok-typeName\">PanelImperativeHandle</span><span class=\"\"> </span><span class=\"tok-operator\">|</span><span class=\"\"> </span><span class=\"tok-keyword\">null</span><span class=\"\">&#62;</span></div>",
       "name": "panelRef",
       "required": false
     }

public/generated/docs/Separator.json

@@ -4,7 +4,8 @@
       "content": "<p>Separators are not <em>required</em> but they are <em>recommended</em> as they improve keyboard accessibility.</p>\n"
     },
     {
-      "content": "<p>Separators should be rendered as the direct child of a Group component.</p>\n"
+      "content": "<p>Separator elements must be direct DOM children of their parent Group elements.</p>\n",
+      "intent": "warning"
     },
     {
       "content": "<p>Separator elements always include the following attributes:</p>\n"

public/generated/examples/GroupExplicitHeight.json

@@ -0,0 +1,3 @@
+{
+  "html": "<div><span class=\"tok-comment\">// an inline style will override the default</span><span class=\"\"></span></div>\n<div><span class=\"\"></span><span class=\"tok-variableName\">render</span><span class=\"tok-punctuation\">(</span><span class=\"tok-punctuation\">&#60;</span><span class=\"tok-typeName\">Group</span><span class=\"\"> </span><span class=\"tok-propertyName\">style</span><span class=\"tok-operator\">=</span><span class=\"tok-punctuation\">{</span><span class=\"tok-punctuation\">{</span><span class=\"\"> </span><span class=\"tok-propertyName tok-definition\">height</span><span class=\"tok-punctuation\">:</span><span class=\"\"> </span><span class=\"tok-number\">100</span><span class=\"\"> </span><span class=\"tok-punctuation\">}</span><span class=\"tok-punctuation\">}</span><span class=\"\"> </span><span class=\"tok-punctuation\">{</span><span class=\"tok-punctuation\">...</span><span class=\"tok-variableName\">rest</span><span class=\"tok-punctuation\">}</span><span class=\"\"> </span><span class=\"tok-punctuation\">/&#62;</span><span class=\"tok-punctuation\">)</span><span class=\"tok-punctuation\">;</span><span class=\"\"></span></div>\n<div>&nbsp;</div>\n<div><span class=\"\"></span><span class=\"tok-comment\">// an !important CSS rule will also override it</span><span class=\"\"></span></div>\n<div><span class=\"\"></span><span class=\"tok-variableName\">render</span><span class=\"tok-punctuation\">(</span><span class=\"tok-punctuation\">&#60;</span><span class=\"tok-typeName\">Group</span><span class=\"\"> </span><span class=\"tok-propertyName\">className</span><span class=\"tok-operator\">=</span><span class=\"tok-string\">\"h-100!\"</span><span class=\"\"> </span><span class=\"tok-punctuation\">{</span><span class=\"tok-punctuation\">...</span><span class=\"tok-variableName\">rest</span><span class=\"tok-punctuation\">}</span><span class=\"\"> </span><span class=\"tok-punctuation\">/&#62;</span><span class=\"tok-punctuation\">)</span><span class=\"tok-punctuation\">;</span><span class=\"\"></span></div>\n<div>&nbsp;</div>\n<div><span class=\"\"></span><span class=\"tok-comment\">// a min-height CSS rule will accomplish the same result</span><span class=\"\"></span></div>\n<div><span class=\"\"></span><span class=\"tok-variableName\">render</span><span class=\"tok-punctuation\">(</span><span class=\"tok-punctuation\">&#60;</span><span class=\"tok-typeName\">Group</span><span class=\"\"> </span><span class=\"tok-propertyName\">className</span><span class=\"tok-operator\">=</span><span class=\"tok-string\">\"min-h-100\"</span><span class=\"\"> </span><span class=\"tok-punctuation\">{</span><span class=\"tok-punctuation\">...</span><span class=\"tok-variableName\">rest</span><span class=\"tok-punctuation\">}</span><span class=\"\"> </span><span class=\"tok-punctuation\">/&#62;</span><span class=\"tok-punctuation\">)</span><span class=\"tok-punctuation\">;</span></div>"
+}

public/generated/examples/LayoutBasicsVertical.json

@@ -1,3 +1,3 @@
 {
-  "html": "<div><span class=\"tok-punctuation\">&#60;</span><span class=\"tok-typeName\">Group</span><span class=\"\"> </span><span class=\"tok-propertyName\">className</span><span class=\"tok-operator\">=</span><span class=\"tok-string\">\"h-30\"</span><span class=\"\"> </span><span class=\"tok-propertyName\">orientation</span><span class=\"tok-operator\">=</span><span class=\"tok-string\">\"vertical\"</span><span class=\"tok-punctuation\">&#62;</span><span class=\"\"></span></div>\n<div><span class=\"\">  </span><span class=\"tok-punctuation\">&#60;</span><span class=\"tok-typeName\">Panel</span><span class=\"tok-punctuation\">&#62;</span><span class=\"\">top</span><span class=\"tok-punctuation\">&#60;/</span><span class=\"tok-typeName\">Panel</span><span class=\"tok-punctuation\">&#62;</span><span class=\"\"></span></div>\n<div><span class=\"\">  </span><span class=\"tok-punctuation\">&#60;</span><span class=\"tok-typeName\">Panel</span><span class=\"tok-punctuation\">&#62;</span><span class=\"\">bottom</span><span class=\"tok-punctuation\">&#60;/</span><span class=\"tok-typeName\">Panel</span><span class=\"tok-punctuation\">&#62;</span><span class=\"\"></span></div>\n<div><span class=\"\"></span><span class=\"tok-punctuation\">&#60;/</span><span class=\"tok-typeName\">Group</span><span class=\"tok-punctuation\">&#62;</span></div>"
+  "html": "<div><span class=\"tok-punctuation\">&#60;</span><span class=\"tok-typeName\">Group</span><span class=\"\"> </span><span class=\"tok-propertyName\">className</span><span class=\"tok-operator\">=</span><span class=\"tok-string\">\"min-h-30\"</span><span class=\"\"> </span><span class=\"tok-propertyName\">orientation</span><span class=\"tok-operator\">=</span><span class=\"tok-string\">\"vertical\"</span><span class=\"tok-punctuation\">&#62;</span><span class=\"\"></span></div>\n<div><span class=\"\">  </span><span class=\"tok-punctuation\">&#60;</span><span class=\"tok-typeName\">Panel</span><span class=\"tok-punctuation\">&#62;</span><span class=\"\">top</span><span class=\"tok-punctuation\">&#60;/</span><span class=\"tok-typeName\">Panel</span><span class=\"tok-punctuation\">&#62;</span><span class=\"\"></span></div>\n<div><span class=\"\">  </span><span class=\"tok-punctuation\">&#60;</span><span class=\"tok-typeName\">Panel</span><span class=\"tok-punctuation\">&#62;</span><span class=\"\">bottom</span><span class=\"tok-punctuation\">&#60;/</span><span class=\"tok-typeName\">Panel</span><span class=\"tok-punctuation\">&#62;</span><span class=\"\"></span></div>\n<div><span class=\"\"></span><span class=\"tok-punctuation\">&#60;/</span><span class=\"tok-typeName\">Group</span><span class=\"tok-punctuation\">&#62;</span></div>"
 }