Popovers normal form

[matheusps]

Context

The normal form describes a consistent API template for all popovers. The main objective is to reduce the Shoreline Library learning curve by reusing latent developer knowledge.

There are two forms of popover components. Full form, and reduced form.

1. Full form: More verbose, but more flexible
2. Reduced form: Less verbose, but less flexible.

The main reason for both forms to exist is to provide our users with optimal experience in common use cases, without removing the library flexibility for diverse cases.

Let's take the Menu, for example. The Full form consists of:

1. Provider: Provides states for the MenuContext
2. Trigger: Toggles the menu popover
3. Popover: Contains the menu options
4. Item: Items that can be clicked

Example: Menu

<MenuProvider>
  <MenuTrigger>Open</MenuTrigger>
  <MenuPopover>
    <MenuItem>Item</MenuItem>
  </MenuPopover>
</MenuProvider>

By default, all popover components are uncontrolled. The user can take control of it by passing a state:

const [open, setOpen] = React.useState(false)

render(
  <MenuProvider open={open} setOpen={setOpen}>
    <MenuTrigger>Open</MenuTrigger>
    <MenuPopover>
      <MenuItem>Item</MenuItem>
    </MenuPopover>
  </MenuProvider>
)

For advanced use cases, stores are also allowed.

const store = useMenuStore(false)

render(
  <MenuProvider store={store}>
    <MenuTrigger>Open</MenuTrigger>
    <MenuPopover>
      <MenuItem>Item</MenuItem>
    </MenuPopover>
  </MenuProvider>
)

The reduced form merges Provider, Trigger, and Popover into a single component. The children of the Trigger, becomes the label prop:

<Menu label="Open">
  <MenuItem>Item</MenuItem>
</Menu>

It also accepts all props of the Provider:

const [open, setOpen] = React.useState(false)

render(
  <Menu label="Open" open={open} setOpen={setOpen}>
    <MenuItem>Item</MenuItem>
  </Menu>
)

API Preview

Popover

<PopoverProvider>
  <PopoverTrigger>Open</PopoverTrigger>
  <Popover>
    {/* ... */}
  </Popover>
</PopoverProvider>

Reduced form:

<Popover label="...">    
  {/* ... */}
</Popover>

Select

<SelectProvider>
  <SelectTrigger>Open</SelectTrigger>
  <SelectPopover>
    <SelectItem>Item<SelectItem>
  </SelectPopover>
</SelectProvider>

Reduced form:

<Select label="...">    
  <SelectItem>Item<SelectItem>
</Select>

Menu

<MenuProvider>
  <MenuTrigger>Open</MenuTrigger>
  <MenuPopover>
    <MenuItem>Item</MenuItem>
  </MenuPopover>
</MenuProvider>

Reduced form:

<Menu label="...">
  <MenuItem>Item</MenuItem>
</Menu>

Filter

<FilterProvider>
  <FilterTrigger>Open</FilterTrigger>
  <FilterPopover>
    <FilterItem>Item</FilterItem>
  </FilterPopover>
</FilterProvider>

Reduced form:

<Filter label="...">
  <FilterItem>Item</FilterItem>
</Filter>

Tooltip

<TooltipProvider>
  <TooltipTrigger>Open</TooltipTrigger>
  <TooltipPopover>
    Text
  </TooltipPopover>
</TooltipProvider>

Reduced form:

<Tooltip label="...">
  {trigger}
</Tooltip>

Edge Case: Combobox

It will follow the same pattern, but changes Trigger for Input. On the Full form:

<ComboboxProvider>
  <ComboboxInput />
  <ComboboxPopover>
    <ComboboxItem>Item<ComboboxItem>
  </ComboboxPopover>
</ComboboxProvider>

Reduced form:

<Combobox {...(inputProps + providerProps + popoverProps)}>
  <ComboboxItem>Item<ComboboxItem>
</ComboboxProvider>

Decisions

Trigger vs Disclosure vs Anchor

Trigger was chosen because is easier to write than Disclosure and is more meaningful than Anchor.

Provider vs Root

Provider was chosen over Root because is more meaningful.

Item vs Option

Item covers more cases than Option.

[anitavincent]

In the reduced format, what would be the format of the trigger? Would it always be a primary button with the label? Would it vary for each component? Specially for the tooltip we usually use a custom icon currently

[matheusps]

It will vary. But, mainly a button (secondary by default). In the tooltip, is anything you pass to it as children:

<Tooltip text="Tooltip text">
  <IconButton label="Delete">
    <IconTrash />
  </IconButton>
</Tooltip>
`` `

[anitavincent]

Sounds good, we just have to see about having the tooltip icon available then

[marcelovicentegc]

What is the need for a store on these advanced use cases? Can you provide an example?

[matheusps]

To build other popovers, for example:

shoreline/packages/components/src/filter/filter-provider.tsx

Line 31 in 63bc656

const popoverStore = usePopoverStore({

[marcelovicentegc]

Got it! Perfect!

[davicostalf]

• Why do you think it's relevant to change "trigger" to "input" in the combobox use case?
• All the components will support both the full form and the reduced form?

[matheusps]

"Why do you think it's relevant to change "trigger" to "input" in the combobox use case?"

• The input has other functionality attached that does not toggle the popover visibility.
• It does not make sense for our combobox implementation to use other Trigger that is not an input.

[matheusps]

"All the components will support both the full form and the reduced form?"

• All popover components.

[davicostalf]

LGTM

[lucasaarcoverde]

LGTM ✨

Just a question, Is there any risk of the spread causing an unexpected override here?

<Combobox {...(inputProps + providerProps + popoverProps)}>

[matheusps]

not really. This is just an example

[matheusps]

Implemented by #1422. Notice that primitives do not need the compact version.