feat: add support for tree sections #9013

yihuiliao · 2025-10-10T05:50:27Z

Closes

✅ Pull Request Checklist:

Included link to corresponding React Spectrum GitHub Issue.
Added/updated unit tests and storybook for this change (for new code or code which already has tests).
Filled out test instructions.
Updated documentation (if it already exists for this component).
Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

🧢 Your Project:

…tenTree

rspbot · 2025-10-10T05:55:21Z

Build successful! 🎉

rspbot · 2025-10-10T22:19:22Z

Build successful! 🎉

rspbot · 2025-10-10T22:25:04Z

Build successful! 🎉

rspbot · 2025-10-10T22:45:37Z

Build successful! 🎉

yihuiliao · 2025-10-10T22:14:32Z

packages/@react-aria/gridlist/src/useGridListItem.ts

      if (parent) {
        // siblings must exist because our original node exists
-        let siblings = state.collection.getChildren?.(parent.key)!;
+        let siblings = getDirectChildren(parent as CollectionNode<T>, state.collection as Collection<CollectionNode<T>>);


we used to use the getChildren method from TreeCollection but now that we've changed it to get ALL the descendants of a parent node instead of its immediate descendants, we can't use that anymore. i decided to make a new function called getDirectChildren which is essentially the same code as what getChildren was before

yihuiliao · 2025-10-10T22:21:08Z

packages/react-aria-components/src/Tree.tsx

-    let {flattenedRows, keyMap, itemCount} = flattenTree<T>(collection, {expandedKeys});
-    this.flattenedRows = flattenedRows;
+    let {collection, lastExpandedKeys, expandedKeys} = opts;
+    let {keyMap, itemCount} = flattenTree<T>(collection, {expandedKeys});


i've removed flattenedRows from TreeCollection since we've moved away from the flattened structure but i didn't feel entirely comfortable removing flattenTree entirely since we use it to build the keyMap and modify the nodes (like the levels and index). but if we do wanna rework it, im happy to do it in a follow-up unless we'd like the changes in this PR

yihuiliao · 2025-10-10T22:24:10Z

packages/react-aria-components/src/Tree.tsx

    return this.keyMap.get(key) || null;
  }

  at(idx: number) {


obviously, this was a lot easier when we had flattenedRows because we could just index it but now we don't have a nice array to index. getKeyAfter will get the next visible row from the top and we just iterate however many times idx is

if you're wondering why we don't just use getKeyAfter that's already built into TreeCollection...continue reading...

Do we actually use the at method anywhere? In BaseCollection we throw an error that it isn't supported. Maybe we don't need this?

no it doesn't look like we use it anywhere and it's not defined in any other collection either so we can probably just remove it

yihuiliao · 2025-10-10T22:30:18Z

packages/react-aria-components/src/Tree.tsx

  let [expandedKeys, setExpandedKeys] = useControlledState(
-    propExpandedKeys ? convertExpanded(propExpandedKeys) : undefined,
-    propDefaultExpandedKeys ? convertExpanded(propDefaultExpandedKeys) : new Set(),
+    propExpandedKeys ? new Set(propExpandedKeys) : undefined,


ended up getting rid of convertExpanded because i was running into a type error where expandedKeys could either be a Set or string but since propExpandedKeys/propDefaultExpandedKeys are type Iterable<Key> and cannot be set to all, there wasn't any way expandedKeys would ever be a string

yihuiliao · 2025-10-10T23:19:46Z

packages/react-aria-components/src/Tree.tsx

+    }
+
+    if ((this.expandedKeys.has(node.key) || node.type !== 'item') && node.firstChildKey != null) {
+      return node.firstChildKey;


should getKeyAfter include content nodes or should it skip them?

in this case, if the node is included in expandedKeys, we'll look at its firstChildKey which will be a TreeItemContent node. however, this caused issues in DropTargetKeyboardNavigation so we check if the node is a content node and if it is, we check its nextKey. however, we could deal with that here but depends on what we want to do

rspbot · 2025-10-10T23:26:46Z

Build successful! 🎉

rspbot · 2025-10-10T23:26:47Z

## API Changes

react-aria-components

/react-aria-components:GridListSectionProps

-GridListSectionProps <T> {
-  aria-label?: string
-  children?: ReactNode | (T) => ReactElement
-  className?: string = 'react-aria-GridListSection'
-  dependencies?: ReadonlyArray<any>
-  id?: Key
-  items?: Iterable<T>
-  style?: CSSProperties
-  value?: T
-}

/react-aria-components:TreeHeader

+TreeHeader {
+  UNTYPED
+}

/react-aria-components:TreeSection

+TreeSection <T extends {}> {
+  aria-label?: string
+  children?: ReactNode | ({}) => ReactElement
+  className?: string
+  dependencies?: ReadonlyArray<any>
+  id?: Key
+  items?: Iterable<{}>
+  style?: CSSProperties
+  value?: {}
+}

devongovett

Let's discuss what we want the division of responsibilties to be between collections/keyboard delegates/drop delegates/etc.

devongovett · 2025-10-20T19:33:27Z

packages/@react-aria/gridlist/src/useGridListItem.ts

 }
+
+function getDirectChildren<T>(parent: CollectionNode<T>, collection: Collection<CollectionNode<T>>) {
+  let node = parent?.firstChildKey != null ? collection.getItem(parent.firstChildKey) : null;


I think this only works with new collections (that's why it required a type cast above)? Maybe ok because we currently only implement Tree in RAC, not directly via hooks, but if someone did that this wouldn't work.

oh true. i guess i could maybe do some type guarding and have some different logic if it's Node and not a CollectionNode? kinda unfortunate that we can't use getChildren here anymore tho

devongovett · 2025-10-20T19:50:14Z

packages/react-aria-components/src/Tree.tsx

    return this.keyMap.get(key) || null;
  }

  at(idx: number) {


Do we actually use the at method anywhere? In BaseCollection we throw an error that it isn't supported. Maybe we don't need this?

devongovett · 2025-10-20T19:53:37Z

packages/react-aria-components/src/Tree.tsx

+      return null;
+    }
+
+    // Skip over any nodes that aren't an item node (e.g. section or header node)


I wonder if this should be the job of the collection or the keyboard delegate? In BaseCollection we don't skip any nodes here. I kinda think collections should traverse everything and everything downstream (keyboard delegate, dnd, etc.) should skip over things it doesn't care about.

I agree with this sentiment

yeah i think that would make sense. daniel and i kinda talked about that regarding getKeyAfter. either we could skip the content node inside of getKeyAfter or handle it inside of dnd. we ended up doing the latter but i can see applying that logic elsewhere

devongovett · 2025-10-20T19:58:26Z

packages/react-aria-components/src/Tree.tsx

+    let expandedKeys = this.expandedKeys;
    return {
      *[Symbol.iterator]() {
+        function* traverseDepthFirst(node: CollectionNode<T> | null, expandedKeys: Set<Key>) {


In theory, this should be equivalent to starting at key and traversing by iterating through getKeyAfter until it returns null. Wonder if we could implement it that way and avoid duplicating the logic here? Same could probably be done for the iterator over the whole collection above (but starting at getFirstKey()).

yihuiliao added 15 commits September 23, 2025 15:08

initial tree stuff

473d209

fix virtualized tree section expanding, update methods to remove flat…

e896397

…tenTree

cleanup

c3385c1

more cleanup

fb17656

Merge branch 'main' into tree-section

a1c8b17

update key after if its content node

89df42f

fix types when checking content node

8491826

fix spacing

6f78fe7

update dynamic story

43f2895

update setSize with added getDirectChildren function

99d4169

fix types, update at method

049f2a5

remove console logs

fce9dce

add collection dependency to gridlist

f138f6a

fix lint

900d69e

update yarn lock

ae36ec5

yihuiliao added 4 commits October 10, 2025 15:03

rename dynamic row section array

cff1b4c

add tests, fix setSize for top level nodes inside a section

e6752ca

fix lint

fb703b2

remove comments

98289ce

more cleanup

ed55388

comments and stuff

3facc4a

yihuiliao commented Oct 10, 2025

View reviewed changes

yihuiliao changed the title ~~wip: tree section~~ feat: add support for tree sections Oct 10, 2025

yihuiliao marked this pull request as ready for review October 10, 2025 23:20

LFDanLu added the ready for review label Oct 20, 2025

devongovett reviewed Oct 20, 2025

View reviewed changes

feat: add support for tree sections #9013

Are you sure you want to change the base?

feat: add support for tree sections #9013

Conversation

yihuiliao commented Oct 10, 2025

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

rspbot commented Oct 10, 2025

Uh oh!

rspbot commented Oct 10, 2025

Uh oh!

rspbot commented Oct 10, 2025

Uh oh!

rspbot commented Oct 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Oct 10, 2025

Uh oh!

rspbot commented Oct 10, 2025

react-aria-components

/react-aria-components:GridListSectionProps

/react-aria-components:TreeHeader

/react-aria-components:TreeSection

Uh oh!

devongovett left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants