feat: Add CollectionNode to collection renderer

[nwidynski]

This adds an optional CollectionNode component to the collection renderer interface, which enables customization of a nodes render output without having to re-implement the entire renderer. This can be useful to build wrapper components which modify a nodes pseudo content without breaking an existing custom renderer, e.g. <Virtualizer />.

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

[nwidynski]

@devongovett Would love to hear your thoughts on this. For more context, this PR relates to #8317 (comment). Let me know if the docs need updates as well here!

[devongovett]

So you are looking for some kind of "inheritance" for collection renderers basically? Like use virtualizer but add an extra wrapper element around items? Can you describe in a bit more detail how your use case (a carousel I guess?) works?

One concern is that it could be somewhat easy to mess up the DOM structure expected by an existing renderer, but maybe it's an advanced use case anyway so you know the risks.

I was going to say the default collection renderer was pretty simple so it wouldn't be too hard to copy, but the drop indicator stuff is kinda complicated now so maybe this makes sense.

Do you usually want to wrap just the item itself or also wrap the drop indicators?

Sorry for all the questions just trying to think through the use cases here.

[nwidynski]

@devongovett Yes, thats right! The primary idea for this PR was to be able to create a component similar to Autocomplete, which composes around a collection component and is able to modify the content after/before the drop indicator. More specifically, we were simulating an infinite loop of collection items by rendering clones of the opposite collection side (e.g. item n-1 before item 1) at the first and last collection item respectively, then moving scroll position when hitting the boundaries. This meant we had to place clones outside of the drop indicators, which otherwise would be pushed out of view.

PS: We have already moved on from this implementation to one based on a Virtualizer, but nevertheless this PR would make sense i feel like. More on our implementation soon, as I will try to contribute the full Carousel!

[devongovett]

Got it, thanks. I think something like that makes sense but I haven't fully thought it through yet. We're in release mode at the moment so responses might be slow. Will discuss it with the team soon.

[devongovett]

We discussed this as a team and we think this is a reasonable API addition. Just one question on prop naming in case you have some ideas.

[devongovett]

Do you think we should name these props so they are more specific to drop indicators? Not sure if we might want to add other things between items in the future, whether we'd want to group them here or allow them to be passed in separately for more control.

[nwidynski]

I was questioning the same while working on this. Personally, I do feel like a user of this feature is looking for as much control here as possible. A compromise between the two could maybe be to change the signature to ReactNode[] or ReactElement[] to make destructuring much easier.

[nwidynski]

@devongovett Btw, since I saw your reply on X, we might want to offer a wrapper prop here as well to wrap the node. Maybe thats easier than cloning the node just to modify its render function.

[LFDanLu]

Apologies for the very late reply. Personally, I think keeping the naming as is but expanding the signature to what you've proposed above is what I'd lean towards. The wrapper prop (and the itemRef addition you've mentioned in other comments) seems fine as well but in the hopes of getting this in sooner rather than later we can make those follow ups if you are fine with that.

[nwidynski]

Sounds good, I will do the follow ups in another PR tmrw 👍 Feel free to push the changes for the signatures if you intend to merge it today, since im out of office already.

[nwidynski]

@devongovett Have you had the chance to make a decision on naming? Just bumping to get this PR wrapped up.

PS: I would also love to support an itemRef, which is passed to the nodes render function and merged with the normal ref. Happy to postpone any further changes to follow ups however, lmk 👍

[nwidynski]

Can we tie this up? Please also let me know about the itemRef prop, which would be used to get a handle on the underlying DOM element of a collection item from a parent collection renderer. Underlying implementation of this would be:

CollectionBuilder.tsx

let Component = forwardRef(({node}: {node: Node<any>}, ref: ForwardedRef<E>) => render(node.props, mergeRefs(node.props.ref, ref), node));

[nwidynski]

@LFDanLu I added the nodeRef and render wrapper function as discussed. This should be good for review now 👍

[nwidynski]

Adding parent here doesn't do a whole lot, since collection.getChildren returns a new iterator on every render anyways. Still added it just in case that ever becomes identity stable.