From 2dd04bb029e84087259eb360be097dad27ef3ed4 Mon Sep 17 00:00:00 2001
From: Reid Barber <reid@reidbarber.com>
Date: Thu, 26 Feb 2026 18:44:28 -0600
Subject: [PATCH 1/2] docs(RAC): Add TreeSection docs (#9699)

* docs(Tree): Add TreeSection docs

* export tree components from starter
---
 .../dev/s2-docs/pages/react-aria/Tree.mdx     | 51 ++++++++++++++++++-
 starters/docs/src/Tree.css                    | 11 ++++
 starters/docs/src/Tree.tsx                    | 16 +++++-
 3 files changed, 75 insertions(+), 3 deletions(-)

diff --git a/packages/dev/s2-docs/pages/react-aria/Tree.mdx b/packages/dev/s2-docs/pages/react-aria/Tree.mdx
index 0cfb27d58c4..63bd61068c9 100644
--- a/packages/dev/s2-docs/pages/react-aria/Tree.mdx
+++ b/packages/dev/s2-docs/pages/react-aria/Tree.mdx
@@ -7,6 +7,7 @@ import vanillaDocs from 'docs:vanilla-starter/Tree';
 import '../../tailwind/tailwind.css';
 import Anatomy from 'react-aria-components/docs/TreeAnatomy.svg';
 import {InlineAlert, Heading, Content} from '@react-spectrum/s2'
+import {VersionBadge} from '../../src/VersionBadge';
 
 export const tags = ['data', 'tree', 'nested', 'hierarchy'];
 export const relatedPages = [
@@ -237,6 +238,40 @@ import {Tree} from 'vanilla-starter/Tree';
 </Tree>
 ```
 
+### Sections <VersionBadge version="alpha" />
+
+Use the `<TreeSection>` component to group options. A `<TreeHeader>` element may also be included to label the section. Sections without a header must have an `aria-label`.
+
+```tsx render
+"use client";
+import {Tree, TreeHeader, TreeItem, TreeSection} from 'vanilla-starter/Tree';
+
+<Tree aria-label="Files">
+  <TreeSection>
+    <TreeHeader>Photos</TreeHeader>
+    <TreeItem id="my-photos" title="My Photos">
+      <TreeItem id="photo-1" title="Photo 1" />
+      <TreeItem id="photo-2" title="Photo 2" />
+    </TreeItem>
+    <TreeItem id="shared-photos" title="Shared Photos">
+      <TreeItem id="shared-photo-1" title="Shared Photo 1" />
+      <TreeItem id="shared-photo-2" title="Shared Photo 2" />
+    </TreeItem> 
+  </TreeSection>
+  <TreeSection>
+    <TreeHeader>Documents</TreeHeader>
+    <TreeItem id="my-documents" title="My Documents">
+      <TreeItem id="document-1" title="Document 1" />
+      <TreeItem id="document-2" title="Document 2" />
+    </TreeItem>
+    <TreeItem id="shared-documents" title="Shared Documents">
+      <TreeItem id="shared-document-1" title="Shared Document 1" />
+      <TreeItem id="shared-document-2" title="Shared Document 2" />
+    </TreeItem>
+  </TreeSection>
+</Tree>
+```
+
 ## Selection and actions
 
 Use the `selectionMode` prop to enable single or multiple selection. The selected items can be controlled via the `selectedKeys` prop, matching the `id` prop of the items. The `onAction` event handles item actions. Items can be disabled with the `isDisabled` prop. See the [selection guide](selection?component=Tree) for more details.
@@ -367,7 +402,7 @@ function Example() {
 
 <Anatomy role="img" aria-label="Anatomy diagram of a Tree, consisting of multiple items. Each item in the tree contains a selection checkbox, an expand toggle button, and the name of the item." />
 
-```tsx links={{Tree: '#tree', TreeItem: '#treeitem', TreeItemContent: '#treeitemcontent', Button: 'Button', Checkbox: 'Checkbox', TreeLoadMoreItem: '#treeloadmoreitem', SelectionIndicator: 'selection#animated-selectionindicator'}}
+```tsx links={{Tree: '#tree', TreeItem: '#treeitem', TreeItemContent: '#treeitemcontent', TreeSection: '#treesection', TreeHeader: '#treeheader', Button: 'Button', Checkbox: 'Checkbox', TreeLoadMoreItem: '#treeloadmoreitem', SelectionIndicator: 'selection#animated-selectionindicator'}}
 <Tree>
   <TreeItem>
     <TreeItemContent>
@@ -378,8 +413,12 @@ function Example() {
     <TreeItem>
       {/* ... */}
     </TreeItem>
-    <TreeLoadMoreItem />
   </TreeItem>
+  <TreeSection>
+    <TreeHeader />
+    <TreeItem>{/* ... */}</TreeItem>
+  </TreeSection>
+  <TreeLoadMoreItem />
 </Tree>
 ```
 
@@ -401,6 +440,14 @@ function Example() {
 
 <PropTable component={docs.exports.TreeItemContent} links={docs.links} showDescription hideRenderProps />
 
+### TreeSection
+
+<PropTable component={docs.exports.TreeSection} links={docs.links} showDescription />
+
+### TreeHeader
+
+`<TreeHeader>` labels the section within a Tree. It accepts all DOM attributes.
+
 ### TreeLoadMoreItem
 
 <PropTable
diff --git a/starters/docs/src/Tree.css b/starters/docs/src/Tree.css
index 8b86be191e7..8d752c6c07c 100644
--- a/starters/docs/src/Tree.css
+++ b/starters/docs/src/Tree.css
@@ -16,6 +16,17 @@
   --drag-button-width: 0px;
   --checkbox-width: 0px;
 
+  .react-aria-TreeSection:not(:first-child) {
+    margin-top: var(--spacing-4);
+  }
+
+  .react-aria-TreeHeader {
+    font-size: var(--font-size-lg);
+    font-weight: 500;
+    padding: var(--spacing-1) var(--spacing-2);
+    color: var(--text-color);
+  }
+
   &[data-focus-visible] {
     outline: 2px solid var(--focus-ring-color);
     outline-offset: -1px;
diff --git a/starters/docs/src/Tree.tsx b/starters/docs/src/Tree.tsx
index 0a702879540..8b74fe95cdc 100644
--- a/starters/docs/src/Tree.tsx
+++ b/starters/docs/src/Tree.tsx
@@ -9,7 +9,9 @@ import {
   TreeItemProps as AriaTreeItemProps,
   TreeProps,
   TreeLoadMoreItem as AriaTreeLoadMoreItem,
-  TreeLoadMoreItemProps
+  TreeLoadMoreItemProps,
+  TreeSection as AriaTreeSection,
+  TreeHeader as AriaTreeHeader
 } from 'react-aria-components';
 import {ChevronRight, GripVertical} from 'lucide-react';
 import {Checkbox} from './Checkbox';
@@ -67,3 +69,15 @@ export function TreeLoadMoreItem(props: TreeLoadMoreItemProps) {
     </AriaTreeLoadMoreItem>
   );
 }
+
+export function TreeSection<T extends object>(
+  props: React.ComponentProps<typeof AriaTreeSection>
+) {
+  return <AriaTreeSection {...props} />;
+}
+
+export function TreeHeader(
+  props: React.ComponentProps<typeof AriaTreeHeader>
+) {
+  return <AriaTreeHeader {...props} />;
+}

From d974b93dee0ba4dc7906095097348220ef778e99 Mon Sep 17 00:00:00 2001
From: Daniel Lu <dl1644@gmail.com>
Date: Thu, 26 Feb 2026 21:17:09 -0800
Subject: [PATCH 2/2] fix: prevent docs crash by making template elements
 always append children into .content (#9703)

* fix: prevent docs crash by making template elements always append children into .content

* fix lint
---
 .../@react-aria/collections/src/Hidden.tsx    | 46 +++----------------
 1 file changed, 6 insertions(+), 40 deletions(-)

diff --git a/packages/@react-aria/collections/src/Hidden.tsx b/packages/@react-aria/collections/src/Hidden.tsx
index 6ff7465d909..9730dd09bdb 100644
--- a/packages/@react-aria/collections/src/Hidden.tsx
+++ b/packages/@react-aria/collections/src/Hidden.tsx
@@ -11,8 +11,7 @@
  */
 
 import {forwardRefType} from '@react-types/shared';
-import React, {Context, createContext, forwardRef, JSX, ReactElement, ReactNode, useContext, useRef} from 'react';
-import {useLayoutEffect} from '@react-aria/utils';
+import React, {Context, createContext, forwardRef, JSX, ReactElement, ReactNode, useContext} from 'react';
 
 // React doesn't understand the <template> element, which doesn't have children like a normal element.
 // It will throw an error during hydration when it expects the firstChild to contain content rendered
@@ -21,20 +20,11 @@ import {useLayoutEffect} from '@react-aria/utils';
 // does the same for appendChild/removeChild/insertBefore as per the issue below
 // See https://github.com/facebook/react/issues/19932
 if (typeof HTMLTemplateElement !== 'undefined') {
-  const getFirstChild = Object.getOwnPropertyDescriptor(Node.prototype, 'firstChild')!.get!;
-  const originalAppendChild = Object.getOwnPropertyDescriptor(Node.prototype, 'appendChild')!.value!;
-  const originalRemoveChild = Object.getOwnPropertyDescriptor(Node.prototype, 'removeChild')!.value!;
-  const originalInsertBefore = Object.getOwnPropertyDescriptor(Node.prototype, 'insertBefore')!.value!;
-
   Object.defineProperty(HTMLTemplateElement.prototype, 'firstChild', {
     configurable: true,
     enumerable: true,
     get: function () {
-      if (this.dataset.reactAriaHidden) {
-        return this.content.firstChild;
-      } else {
-        return getFirstChild.call(this);
-      }
+      return this.content.firstChild;
     }
   });
 
@@ -42,11 +32,7 @@ if (typeof HTMLTemplateElement !== 'undefined') {
     configurable: true,
     enumerable: true,
     value: function (node) {
-      if (this.dataset.reactAriaHidden) {
-        return this.content.appendChild(node);
-      } else {
-        return originalAppendChild.call(this, node);
-      }
+      return this.content.appendChild(node);
     }
   });
 
@@ -54,11 +40,7 @@ if (typeof HTMLTemplateElement !== 'undefined') {
     configurable: true,
     enumerable: true,
     value: function (node) {
-      if (this.dataset.reactAriaHidden) {
-        return this.content.removeChild(node);
-      } else {
-        return originalRemoveChild.call(this, node);
-      }
+      return this.content.removeChild(node);
     }
   });
 
@@ -66,11 +48,7 @@ if (typeof HTMLTemplateElement !== 'undefined') {
     configurable: true,
     enumerable: true,
     value: function (node, child) {
-      if (this.dataset.reactAriaHidden) {
-        return this.content.insertBefore(node, child);
-      } else {
-        return originalInsertBefore.call(this, node, child);
-      }
+      return this.content.insertBefore(node, child);
     }
   });
 }
@@ -79,18 +57,6 @@ export const HiddenContext: Context<boolean> = createContext<boolean>(false);
 
 export function Hidden(props: {children: ReactNode}): JSX.Element {
   let isHidden = useContext(HiddenContext);
-  let templateRef = useRef<HTMLTemplateElement>(null);
-  // somehow React might add children to the template and we never hit the reactAriaHidden parts of the above overrides
-  // so we need to move those children into the content of the template since templates can't have direct children
-  useLayoutEffect(() => {
-    let el = templateRef.current;
-    if (!el?.dataset.reactAriaHidden) {
-      return;
-    }
-    while (el.childNodes.length > 0) {
-      el.content.appendChild(el.childNodes[0]);
-    }
-  }, []);
 
   if (isHidden) {
     // Don't hide again if we are already hidden.
@@ -106,7 +72,7 @@ export function Hidden(props: {children: ReactNode}): JSX.Element {
   // In SSR, portals are not supported by React. Instead, always render into a <template>
   // element, which the browser will never display to the user. In addition, the
   // content is not part of the accessible DOM tree, so it won't affect ids or other accessibility attributes.
-  return <template ref={templateRef} data-react-aria-hidden>{children}</template>;
+  return <template>{children}</template>;
 }
 
 /** Creates a component that forwards its ref and returns null if it is in a hidden subtree. */