SelectPanel messages API - Seeking feedback

[broccolinisoup]

Gathering the notes from our brainstorming sessions in a nicer format to present what API options we have so far with some extra content.

This discussion is primarily needed for empty states however we are designing the API in error and warning state in mind since they are a part of the feature improvements.

OPTION 1 - Children API

<SelectPanel
....other props...
>
{ isWarning ? (
<SelectPanel.Message variant="warning" title="Custom warning title">
Custom warning message
</SelectPanel.Message>
) : null }

{ isError ? (
<SelectPanel.Message variant="error" title="Custom error title">
Custom error message
</SelectPanel.Message>
) : null }

{ noInitialItems ? (
<SelectPanel.Message variant="noInitialItems" title="Custom title when there is no items available in the first load">
Custom message
</SelectPanel.Message>
) : null }

{ noFilteredItems ? (
<SelectPanel.Message variant="noFilteredItems" title="Custom title when there is no matches found">
Custom message
</SelectPanel.Message>
) : null }
</SelectPanel>

OPTION 2 - Messages object

<SelectPanel
....other props...
messages={{
 noInitialItems: {
  title: "You have't created any projects yet",
  body: (<>
	<Link href="https://github.com/projects">Start your first project </Link> to organise your issues.
	</>),
  isShown: <condition to determine true or false>,	
  },
 noFilteredItems: {
  title: `No items found for `,
  body: <>Adjust your search term to find other languages</>,
  isShown: <condition to determine true or false>
 },
 warning: {
  title: `No items found for `,
  body: <>Adjust your search term to find other languages</>,
  isShown: <condition to determine true or false>
 },
}}
</SelectPanel>

Requirements

• We need to provide default text (both for title and description) for all states i.e. no initial items, no matched items, warning and error state. It is important from an accessibility point of view.
• All state messages (title and description slot) need to be customisable.

Facts

• It is not possible to determine whether a component is in a warning state or not. Same goes for error state as well. Consumers need to tell us.
• It is possible to determine whether a component is in an empty state or not. Though, this is only a guess. There could always be additional/different set of circumstances that our condition for the visibility of the empty states doesn't work for every usage.

Takeaways

• Consumers have to manage the state of warning and error states. (Because of Fact#1)
• We need to give flexibility to consumers to manage the visibility of these states. (Because of Fact#2)

Proposal

• API options above.
• Once a message variant is provided in the JSX (for either of these empty states), we abort rendering the default. Please see the code below for move context.

// The visibility of the error message depends on the condition provided by the consumer
{ isError ? (
<SelectPanel.Message variant="error" title="Custom error title">
Custom error message
</SelectPanel.Message>
) : null }

// It is not obvious that the visibility of this empty state is managed by the component. Especially considering that the error message is following a very standard JSX rendering practise. If a message with `noInitialItems` variant is provided, we won't render the default.
<SelectPanel.Message variant="noInitialItems" title="Custom title when there is no items available in the first load">
Custom message
</SelectPanel.Message>
}

Appreciate any feedback 🫶

@siddharthkp @camertron

[kendallgassner]

Of the two options I prefer the children API. I like the flexibility of using Children over props.

However, one challenge I find is that some SelectPanels are used within Forms.

As a Primer React user, I would expect to use the FormControl wrapper, or more specifically, FormControl.Validation, for this purpose. I wonder if there is a way we can use the FormControl instead so that our components feel more cohesive?

[broccolinisoup]

Oh, I see! Thanks for this insight @kendallgassner, super valuable. I'll need to consult this to design first since validation messages design (example story) are quite different than the select panel error state.

Could you share an example of a SelectPanel that is being used in a form? Do you have an estimate of the percentage of SelectPanel instances being used within forms, compared to the total number of usages?

[kendallgassner]

Sure can! Right now, I am working on a bulk edit dialog that allows users to edit a characteristic of several issues via a form (an accessible alternative to drag-and-drop on a memex project board). This dialog can have, depending on the characteristic the user wishes to change, a DatePicker, TextInput, Select, or SelectPanel.

Additionally, we show an example in storybook of using the SelectPanel with a FormControl.

[kendallgassner]

I can share a few more examples from the rail side:

The "Select a repository" field on: https://github.com/codespaces/new
The "Select repositories" field on: https://github.com/settings/codespaces/secrets/new

[broccolinisoup]

Thanks @kendallgassner! I chatted about it with our design partners and the error states that I proposed the API here is one pattern and SelectPanel in a form is another pattern that we both support. I'll copy paste what Maxime said

If part of the form and submission goes wrong then you should show that error as part of the form and not inside the SelectPanel, however if information doesn’t load inside the SelectPanel then you would obviously use the built in error states, similarly if you want to limit the total selection you would use the warning banner inside the panel to avoid users getting into a form state that isn’t allowed.
Both patterns are expected and the consumer should pick what fits their use case best.

I would expect to use the FormControl wrapper, or more specifically, FormControl.Validation, for this purpose.

Consumers still be able to use SelectPanel in forms as you described and it is one pattern. See the screenshot below. This would be the case where form fails due to an issue in selectpanel.

The error states that we are working on the API is as described on the docs https://primer.style/components/selectpanel#errorwarning-handling and will be used when the information inside the panel doesn't load or throws an error.

Let me know if there is a better way to clarify this and of course if you have further feedback as well or any concerns 🙌🏻

[kendallgassner]

I wonder if our error handling documentation can be updated to show both use cases.

Additionally can we include SelectPanel in this form control input list.

[camertron]

This is the classic question that always comes up when designing component APIs: how much freedom should we give consumers? In my experience, the more freedom we give consumers, the greater the chance for incongruous outcomes.

This case is even trickier than most because we can almost get away with a props-only approach. Unfortunately the designs show that consumers should be able to add links to the message description, and for error messages it would be nice to eventually be able to add a "Try again" button, etc etc. So I think we have to allow arbitrary content for both error messages and no items/matches.

That being said, IMO we can still establish some guardrails. The designs have two bits of text, a title and a description, with specific font colors and sizes. Whatever API we choose, let's make it easy to do the default thing, eg. provide plaintext values for these fields, and style them appropriately.

As far as behavior goes, I'm firmly in the camp of having the component manage showing/hiding the messages based on the current filter. Eg. if there is no filter text, show the "no items" message; if there is filter text, show the "no matches" message. I would really prefer to reduce the amount of knowledge a consumer has to have about how select panels are supposed to work in order to use them correctly. Requiring consumers to make decisions about when messages are shown or hidden exacerbates this knowledge gap and will lead to problems. Not only will they have to understand the API, but also implicit rules about how to use it appropriately that they may or may not have read in the documentation. The API should be clear enough to (largely) speak for itself.

I'm curious what y'all think of an alternative approach where each message has two slots, a title and a description. I imagine it would look something like this:

<SelectPanel.Message variant="no-items">
  <SelectPanel.Message.Title>
    No projects found.
  </SelectPanel.Message.Title>
  <SelectPanel.Message.Description>
    Would you like to <Link href="/projects/create">create one</Link>?
  </SelectPanel.Message.Description>
</SelectPanel.Message>

That's kind of verbose. Maybe we can simplify it?

It is not possible to determine whether a component is in a warning state or not. Same goes for error state as well. Consumers need to tell us.

That's true. I would think we could add a prop for allowing the consumer to tell us what state the component should be in, which would let us to show the correct message depending on the component's internal state, eg. if items are visible or not.

It is possible to determine whether a component is in an empty state or not. Though, this is only a guess. There could always be additional/different set of circumstances that our condition for the visibility of the empty states doesn't work for every usage.

I'm not sure I follow. If the items prop contains an empty array, the component will display no items. Do we know of any cases currently in dotcom that need special consideration?

Additional context

SelectPanels can display two types of error/warning message, one in a banner above the filter input, and another inside the panel's body. The body message only appears if the panel contains no items. If the panel contains >= 1 item, the banner message is shown instead. While it's possible for the consumer to understand this distinction and include the right type of message in a child element, IMO we shouldn't require them to.

[broccolinisoup]

Thanks @camertron!

Whatever API we choose, let's make it easy to do the default thing, eg. provide plaintext values for these fields, and style them appropriately.

💯 agree!

As far as behavior goes, I'm firmly in the camp of having the component manage showing/hiding the messages based on the current filter. Eg. if there is no filter text, show the "no items" message; if there is filter text, show the "no matches" message. I would really prefer to reduce the amount of knowledge a consumer has to have about how select panels are supposed to work in order to use them correctly.

I understand and completely agree with you. The proposal I mentioned earlier aligns with this approach as well. If the user doesn’t provide any empty state message, we can simply render our default messages without issue.

The only difference I’m suggesting is that once they provide custom "NoFilteredItems" or "NoInitialItems" message details, we stop managing the display logic for the messages. Instead, it becomes the consumer's responsibility. At this stage, I’m assuming that consumers know what they’re doing, as they are customising the messages. Do you have any feedback on this approach?

If the items prop contains an empty array, the component will display no items. Do we know of any cases currently in dotcom that need special consideration?

While we don't have any known cases at the moment, it feels risky to keep the state logic within the component for custom messages. I explored the idea of exposing the condition so that it can be customisable as well however I don't think it is as feasible as I thought. Let me know if you would like to discuss this further.

I'm curious what y'all think of an alternative approach where each message has two slots, a title and a description.

From what I’ve seen in the design and usage of the SelectPanel, titles appear to be just strings, so it may not be necessary for them to be treated as a free slot? Do you have any examples or insights that titles might be free slot as well?

Regarding your comment about error message on a banner and inside the panel, great point. I asked clarifications on these two behaviours because they are not very clear to me. I will provide my comments after getting some more context.

[camertron]

The only difference I’m suggesting is that once they provide custom "NoFilteredItems" or "NoInitialItems" message details, we stop managing the display logic for the messages. Instead, it becomes the consumer's responsibility. At this stage, I’m assuming that consumers know what they’re doing, as they are customising the messages.

Hmm yeah I see what you mean. The thing is, I'm not sure the presence or absence of NoFilteredItems or NoInitialItems is necessarily a good signal for anticipating the user's desire to control when the messages appear. Maybe they just want to customize the message a bit? I think I would be a bit surprised if the component controlled message appearance initially but then changed its behavior if I provided some customizations. I'm also a bit concerned how announcements would work in the custom case, i.e. would the user be responsible for announcing message text as well?

While we don't have any known cases at the moment, it feels risky to keep the state logic within the component for custom messages. I explored the idea of exposing the condition so that it can be customisable as well however I don't think it is as feasible as I thought. Let me know if you would like to discuss this further.

Hmm ok I see... I wonder if it would make sense then to allow the component to manage the state logic for now and offer customization in the future when there's a demonstrated need for it?

From what I’ve seen in the design and usage of the SelectPanel, titles appear to be just strings, so it may not be necessary for them to be treated as a free slot? Do you have any examples or insights that titles might be free slot as well?

Ah that's a great point. I could see us going either way here, but since the designs only show links, etc in descriptions, I think it makes sense to accept a string prop for the title instead of a free-form slot. It should be easy to turn it into a slot in the future.

[broccolinisoup]

Hmm yeah I see what you mean. The thing is, I'm not sure the presence or absence of NoFilteredItems or NoInitialItems is necessarily a good signal for anticipating the user's desire to control when the messages appear. Maybe they just want to customize the message a bit? I think I would be a bit surprised if the component controlled message appearance initially but then changed its behavior if I provided some customizations.

Fair point! To move forward, I’ll let the component manage the state logic for now, with the option to offer customization later if there's a demonstrated need for it 👍🏻

[broccolinisoup]

Just summarising the API after evaluating all the feedback. I appreciate you all very much 🙏🏻

Children API

Empty State (Initial)

👉 Component manages the state of visibility of "noInitialItems" message along with the announcement of the message, style, UX etc.
👉 We will leave the door open to the option to offer customization later if there's a demonstrated need for it.

<SelectPanel.Message variant="noInitialItems" title="Custom title when there is no items available in the first load">
Custom message
</SelectPanel.Message>

Empty State (Filtered)

👉 Component manages the state of visibility of "noFilteredItems" message along with the announcement of the message, style, UX etc
👉 We will leave the door open to the option to offer customization later if there's a demonstrated need for it.

<SelectPanel.Message variant="noFilteredItems" title="Custom title when there is no matches found">
Custom message
</SelectPanel.Message>
</SelectPanel>

Warning State

👉 Consumers manage the state of the visibility of warning messages.
👉 Component will only be responsible for the announcement of the message, style, UX etc.

{ isWarning ? (
<SelectPanel.Message variant="warning" title="Custom warning title">
Custom warning message
</SelectPanel.Message>
) : null }

Error State

👉 Consumers manage the state of the visibility of error messages.
👉 Component will only be responsible for the announcement of the message, style, UX etc.

{ isError ? (
<SelectPanel.Message variant="error" title="Custom error title">
Custom error message
</SelectPanel.Message>
) : null }

[camertron]

Ok that makes sense to me, thanks @broccolinisoup!