SelectPanel: Empty State - Explore SelectPanel.Message API and managing visibility of the component under the hood

[broccolinisoup]

Closes #

Changelog

New

Changed

Removed

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

Merge checklist

• Added/updated tests
• Added/updated documentation
• Added/updated previews (Storybook)
• Changes are SSR compatible
• Tested in Chrome
• Tested in Firefox
• Tested in Safari
• Tested in Edge
• (GitHub staff only) Integration tests pass at github/github (Learn more about how to run integration tests)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9895c58

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[broccolinisoup]

Spiking about API options for the empty states. After having an initial conversation with @siddharthkp

Option 1 (As above code)

Pros

• Straightforward. Consumers don't need to deal with calculating items length etc to display the empty state messages and which empty state they are going to display i.e. no items vs no matches

Cons

• No flexibility to manage the visibility of the messages since everything is under the hood. There is a chance that it might not work for every usage if consumers have more params in determining the empty states. They can still manage it via this API but it would defeat its main motivation which is handling the complex stuff under the hood.

Option 2

We could simplify the API and let consumers worry about managing the empty state. Like below

<SelectPanel.Message variant="empty" title={noItemsState? `No items created yet' : No language found for'`}>
      {noItemsState? `Start creating your items here'  : Adjust your search term to find other languages}
</SelectPanel.Message>

Pros

• Simple API

Cons

• Consumers might choose to use the same messages for both empty states.
• A bit more work for consumers to deal with managing the state.

Alternatively we can use a prop rather than children for providing the messages.

<SelectPanel
  message={<SelectPanel.Message variant="empty" title={noItemsState? `No items created yet' : No language found for'`}>
      {noItemsState? `Start creating your items here'  : Adjust your search term to find other languages}
</SelectPanel.Message>}
</SelectPanel>

Curious to hear what you think 🙌🏻 @siddharthkp @camertron

[siddharthkp]

I like option 2 a lot more, it's more intuitive for me to assume what I ever I give in JSX will be rendered.

A bit more work for consumers to deal with managing the state.

For me, the way to remove extra work would be be more configuration based and asked for messages object

<SelectPanel
  message={{
     noInitialItems: {title: 'No items created yet', body: <><Button>Start creating items</Button></>},
     noFilteredItems: {title: `No items found for ${query}`, body: <>Adjust your search term to find other languages</>}
  }}
>

[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.

@broccolinisoup and I brainstormed this during our 1:1 on Monday and came up with an 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?

Hopefully that resonates with you @siddharthkp! Always willing to have my mind changed tho 😄

I like option 2 a lot more, it's more intuitive for me to assume what I ever I give in JSX will be rendered.

Yeah, I get that. Hopefully an approach like the one I outlined above will still give consumers the ability to pass in custom JSX and have it be rendered as expected.

[broccolinisoup]

Thank you thank you both!! I gathered everything we chatted and wrote down as a discussion #5031 so that we can have a little bit nicer place to continue our discussion and make a decision.

[siddharthkp]

Ooh, interesting.

1. Does this mean we would figure out which Message to render and ignore the rest?
2. Am I correct in assuming we would append the query string at the end of this title?title={'No language found for '}>

[broccolinisoup]

1. Actually it is similar to what you have mentioned in your comment - to have the data for both state. Here is more of a variant version and yours is coming from a message object if I understand it right. Tbh, I don't like this API very much. It is cumbersome. I am just entertaining various options 😄

Consumer don't have to figure out which message to render, we will have defaults but if they need to customise this is how they can do (in this API option)

[broccolinisoup]

2. Yeah!

[camertron]

Yeah this seems great! My only suggestion is to add individual slots (children) for the title and description.