Expand `ItemGroup`

[jameskoster]

In recent times ItemGroup instances have been extended ad hoc to accommodate required features, for example:

Shadows	Font Library	Data view fields	Block bindings	Font size presets

• Shadows – adds a – button to remove the item
• Font Library – adds a suffix/value and chevron to indicate drilldown behavior
• Data view fields – Allows re-ordering, includes button to toggle visibility
• Block bindings: adds a suffix/value and a – button to remove items
• Font size presets – adds a suffix/value and chevron to indicate drilldown behavior

The more this components is arbitrarily customised the more tech debt we create. It would be good to define and implement a modern spec based on the use cases outlined above.

[jameskoster]

Here's an initial take on this, where I've split the items into two types; Item and DrilldownItem.

The list of props concentrate on new functionality. Any existing Item props (e.g. as and onClick are still supported).

Item

Props

• Decoration: Provides an option to display a decorative element such as a color swatch, image preview, icon, etc.
• Has value: Provides an option to display a secondary text element.
• Has re-ordering: Provides an option for the user to re-order items in the group
• Has primary action: Allows the consumer to attach a primary action to the item. Appears on hover.
• Has secondary action(s): Allows the consumer to attach secondary actions to the item. Adds an overflow button that opens a DropdownMenu.

The states are hopefully clear enough, though one detail to decide upon here is how the hover / pressed states behave when the item itself has no on-click action. In this case a hover style is probably unnecessary.

DrilldownItem

Props

• Decoration: Same as Item.

Contextual examples

If we apply these conventions to some upcoming / existing UIs, here are the results. I also included a demonstration of how the title / value truncation should work.

[jasmussen]

Nice, this feels mostly exhaustive and a good system. Only a few pieces feel like they are missing, and some of those are question-marks. First off, there's the stacked color-swatch:

This feels like a pattern worth keeping. But how much can it stack? Currently in Global Styles > Colors, there's this drilldown:

I think that drilldown works fairly well as indication of where you'll go. But does it work in this swatches-only state? Can the pattern be accommodated in these guidelines? Or should this example usage be changed, and if so, to which variant here?

[jameskoster]

Good catch. Agree the two-color-stack is worth keeping. It bugs me a bit how it makes the text alignment ragged though... I wonder if there's something we could do about that?

But does it work in this swatches-only state?

This doesn't feel like the best use of ItemGroup imo, mostly because in that particular UI there will only ever be a single button. The lack of text may not be ideal from an a11y perspective too. I'd probably be inclined to explore a different treatment for that button.

[jasmussen]

That same river bugs me too, but making the swatches smaller creates a different kind of river, in the swatches themselves now lining up weirdly.

I think it's probably fine to keep the text river. An alternative is to start the text further in, though that might look awkward in its own way. Perhaps grouping the color stacks so they are all at the bottom would make it feel more coherent?

[jameskoster]

Yeah a guideline to group by decoration type by default could help 👍

[jameskoster]

Pinging @WordPress/gutenberg-components for any feedback on the designs, as time allows.

[ciampo]

👋 Thank you for starting the conversation on this!

I'll list a few thoughts that came up while going through the issue:

• We could definitely consider adding a prefix/suffix system to the Item component, similarly to what we're doing for DropdownMenuV2
• For the text alignment, we could also borrow the same technique employed for DropdownMenuV2 to make sure that item labels are all aligned horizontally
• The stacked color swatch would just be a prefix that we inject in the Item (without being part of the item itself)
• In the same way, "primary actions" and "dropdowns" could just be part of the suffix. The more generic the component is, the more flexible and open to extensibility it is.
• Is a DrilldownItem basically an Item with the chevron as a suffix? Or is there more to it?
• Since Items can be buttons, we need to be careful in adding more interactive UI (ie. action buttons, reordering, dropdowns...) on the same item. It can definitely be done by making sure that those interactive elements are not children of the item button, but in general we should be careful also in terms of UX with having interactive elements overlapping other interactive elements. In that sense, it may be good to make sure that such interactive overlays (primary action, reordering, dropdown menu) can only be added if the Item is not interactive;
• Not sure that we need a dedicated "has value" prop — the contents on the Item could just be determined via its children instead. We could offer sub components (like ItemLabel and ItemHelpText) to make it easier for consumers to re-use the same styles, but ultimately I think it's better to allow more freedom to the component's consumers;
• for the same reason, the best strategy in terms on sizing would be to apply a minimum height to Item, and allow the item to grow in height based on its contents

[jameskoster]

In the same way, "primary actions" and "dropdowns" could just be part of the suffix. The more generic the component is, the more flexible and open to extensibility it is.

I go a bit back and forth on this... when a component has a specific purpose – in this case grouping and listing related objects – doesn't it make sense to draw some lines in the sand? There's a reasonably narrow scope of properties we can associate with such UIs.

Could there be a case for an underlying Item component that is extensible as you described, then a ResourceItem component which consumes Item and adds the guardrails?

Is a DrilldownItem basically an Item with the chevron as a suffix? Or is there more to it?

In practise the difference is the onClick behavior. I appreciate there's no way for the component to know that natively. However a drilldown item should not have inline actions. I guess this relates a bit to the previous point... I'm unsure if it needs to be a separate component :)

Since Items can be buttons, we need to be careful in adding more interactive UI

Absolutely. Perhaps we can reuse some of the work done in the Shadow management UI: