Implement a TreeMultiSelectField in React

[chillu]

Acceptance Criteria

• I can choose multiple items from hierarchical data
• I can search for items in the same way as with single select TreeDropdown (see TreeDropdownField - React Search Feature silverstripe-framework#6842)
• I can remove single items for multi selects
• Selected values show their labels even when the element is not available in the list yet (due to lazy loading)
• The field complies with WCAG accessibility guidelines
• The field can handle at least five selected items without breaking the layout
• The field presents selection efficiently in readonly/disabled views

Tasks

• Multiple values can be selected
• Cater for "unchanged" empty value when no option is selected in TreeMultiselectField
• Show selected values which are not found in the tree
• Ensure single select still works
• Ensure readonly/disabled view works with correct titles
• unit tests

Nice to haves

• simplify the logic around reducers and components
• The field efficiently displays long tiles as selected items (and provides context on nested items)

Notes

• This should be a specialisation of the existing <TreeDropdownField> component, ideally with minimal code duplication
• The field UX isn't really designed for selecting lots of items (e.g. for "related documents", a relational GridField is the better choice).

Designs

Looking for feedback on these (WIP) https://projects.invisionapp.com/boards/D3X68PS46K28/

Related

• Use react-select for react-based dropdowns (SingleSelectField and MultiSelectField)
• TreeDropdownField - React Search Feature
• Use React-based TreeDropdownField in non-React sections

Pull requests

• Enhancement add support for TreeMultiselectField in react silverstripe-framework#7206
• Enhancement add support for TreeMultiselectField in react #170
• Enhancement Switch CheckboxSetField to TreeMultiselectField for better UX silverstripe-asset-admin#564
• API Use setTitleField to use MenuTitle for selecting internal links silverstripe-cms#1910

[chillu]

Damian brought up a good point: We might not not this field at all.

• MultiSelectField can already be used for "breadcrumb flattened" shallow trees like a groups hierarchy
• Common uses like "related pages" typically rely on GridField with a single TreeDropdownField
• We don't use TreeMultiSelectField in core

Given this, I'm removing the 4.0 milestone. Keeping the ticket around a bit until there's more clarity if we can remove this use case completely.

[chillu]

@clarkepaul Can you please give this some design love? Fairly high priority, since there's dependant cards.

[chillu]

@clarkepaul Are you considering multi-select for large trees as well? This might need a multi-stage process, where you search, add one or more items from the results, then do another search and add more items.

[clarkepaul]

This needs a design review before dev starts ie there is no code to peer review.

[flamerohr]

@clarkepaul The designs look good :) and inline with what react-select does so it shouldn't be too different aesthetic-wise
one question - should the border of the selected items be light grey instead? as it'll continue being light blue after users have tabbed to another field

[chillu]

@clarkepaul Designs look great! A few notes:

• Should we include paths in the selected items? You could end up with two items having the same label and looking like duplicates, but in fact they're in different paths. We'll likely need ellipsis long titles as well. It does start to stretch this UI paradigm (as opposed to a more structured list-based selection)
• How do we deal with long titles in selections?
• It's a bit weird that the "parent" option is indented more than it's children ("Option 4" vs. "Option 4.1"), but I don't have a good solution for this either.
• Does a click on a selected item in the list unselect the item, or close the panel?
• I would expect that I can remove selected items by hitting backspace on my keyboard after focusing in the field. That's either built in to the JS lib already, or really hard to implement. Hopefully it's the former.
• How do you visually communicate that you can still search by focusing on the main form element, even when existing selected items are in the field? We should make sure that this clickable space doesn't disappear depending on how much existing selection fills it.

[clarkepaul]

Should we include paths in the selected items?

I think for now it's okay to not show the path for these, for the edge cases where there are items with the same name users will need to keep note of where they are at. If we add breadcrumbs the UI will bloat easily and become unusable to the majority of people using the tool. I also think we can leave names as full names and not truncate them (as per library we are using which works well enough)

How do we deal with long titles in selections?

They wrap onto the next line.

It's a bit weird that the "parent" option is indented more than its children

Agree it's weird but felt like it communicates the way back better as it's the opposite direction as the arrow going deeper. The alternative is to centre the parent "< Parent" in that area. Happy to hear thoughts as to which is preferred. Other option...

Does a click on a selected item in the list unselect the item, or close the panel?

I don't think the click would do anything (ie. it is not selectable), nor would it close the panel.

Backspace on my keyboard after focusing in the field deletes item?

Yes that's built in

How do you visually communicate that you can still search by focusing on the main form element, even when existing selected items are in the field?

On focus, there is a flashing cursor line to indicate you can still type, this should be sufficient as space is at a premium.

[clarkepaul]

@flamerohr do you mean the border for these selected items?

I was thinking to keep them with the selected blue border (similar to when you have files selected in the Files area) but will take your lead if that doesn't work in reality. Perhaps they are only blue when the field is focused or opened?

[flamerohr]

Cheers, this answers all the questions, I think we could start implementing this after tasking it up :) moving it back to "Next"

[tractorcow]

Reviewing now.