Add support for nested filtering in useListData

[gijsroge]

Closes 4930

✅ 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:

There is no example of the normal filter feature for useListData, if you want I can add a ListBox example in Spectrum's Storybook.

Alternatively you can test it using jest: yarn jest -t "useListData should support filtering nested items"

🧢 Your Project:

[snowystinger]

GET_BUILD

[rspbot]

Build successful! 🎉

• View the storybook
• View the storybook-17
• View the storybook-16
• View the documentation

[snowystinger]

Thanks for the PR and test, I need to get a little feedback on a small bit of functionality.

You're welcome to chime in with an opinion as well

[devongovett]

This is assuming something about the data structure of an item that isn't specified in the types. What if section objects use a different property name for their children or they come from a different data source entirely? I don't think useListData should be prescriptive about the objects that get passed into it.

If your items have children maybe useTreeData would be more appropriate?

[gijsroge]

Yeah I see what you mean. The reason for this PR was mostly to expand support for Listbox filtering (nested items), AFAIK listbox does not support useTreeData and useTreeData does not support filtering out of the box?

What would be your ideal scenario to add support for this? Maybe a more generic way of filtering that does not depend on a specific property?

Maybe something like this?

useListData<T>({
  initialItems: items,
  filterKeys: ['children'],
  filter: (item: any, text) => {
    return contains(item.name, text)
  }
})

[LFDanLu]

So listbox does actually support being passed items from useTreeData, but you are right about useTreeData not supporting filtering out of the box. I've raised a question to the team about whether we'd prefer to commit to having nested item filter support supported useListData (which would then mean we'd need to update the rest of the useListData methods to work for nested data) or if we'd instead add filtering to useTreeData.

[snowystinger]

Thanks for your patience. We had an internal discussion and decided we'd like to add filtering to useTreeData instead of having useListData be another tree implementation.

Would you like to have a go at that in this PR?

[gijsroge]

@snowystinger understood, feels better to do it in useTreeData indeed. I will take a stab at it. Do I start a new PR for this?

[snowystinger]

either one, whatever you're more comfortable with. If you use this one, we'll just rename it

[gijsroge]

@devongovett to address your valid concerns about having assumptions about the users data structure, i've added a filterKey option instead.

Example in storybook

react-spectrum/packages/@react-spectrum/listbox/stories/ListBox.stories.tsx

Lines 1054 to 1078 in 5ffd5e1

	function SearchableListBox() {
	const { contains } = useFilter({ sensitivity: 'base' })
	const list = useListData({
	initialItems: withSection,
	filterKey: 'children',
	filter: (item, text) => {
	return contains(item.name, text)
	}
	});
	return (
	<>
	<input type="text" onChange={(e) => list.setFilterText(e.target.value)} />
	<ListBox width="150px" items={list.items} aria-labelledby="labelSearchableListBox">
	{(item) => (
	<Section key={item.name} items={item.children} title={item.name}>
	{(item) => <Item key={item.name}>{item.name}</Item>}
	</Section>
	)}
	</ListBox >
	</>
	);
	}

cc @snowystinger @reidbarber

[snowystinger]

GET_BUILD

[rspbot]

Build successful! 🎉

• View the storybook
• View the storybook-canary
• View the storybook-17
• View the storybook-16
• View the documentation

[rspbot]

## API Changes

unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any', access: 'private' }
unknown top level export { type: 'any', access: 'private' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'identifier', name: 'Column' }
unknown top level export { type: 'identifier', name: 'Column' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown type { type: 'link' }
unknown type { type: 'link' }
unknown type { type: 'link' }
unknown type { type: 'link' }
unknown type { type: 'link' }
unknown type { type: 'link' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }
unknown top level export { type: 'any' }

@react-stately/data

ListOptions

 ListOptions<T> {
   filter?: (T, string) => boolean
+  filterKey?: string
   getKey?: (T) => Key
   initialFilterText?: string
   initialItems?: Array<T>
   initialSelectedKeys?: 'all' | Iterable<Key>
 

it changed:

• useListData

---

[snowystinger]

We may want to reconsider this prop name, there may be other useful circumstances beyond filtering for knowing the key which contains children/nested items.
For this PR I think it's fine.