feat(panel): add Panel widget

[francoischalifour]

The panel widget adds a way to wrap other widgets to add templates (headers, footers) and utility features (collapsing and hiding the widget).

Motivation

Using headers and footers wrapping a widget is a common need to give more context to the user when interacting with the widget.

React InstantSearch provides a Panel widget to wrap any other InstantSearch component:

<Panel header="All brands">
  <RefinementList attributes="brands" />
</Panel>

Up until InstantSearch.js 2, widgets had header and footer templates, in addition to autoHideContainer and collapsible options. The panel widget solves these needs, deferring the responsability from the widget itself to the panel widget.

Usage

const refinementListWithPanel = panel({
  templates: {
    header: 'Header',
    footer: 'Footer',
    // or with functions
    header: ({ results }) => `Header | ${results.nbHits} results`,
  },
  hidden: ({ results }) => results.nbHits === 0,
})(refinementList);

search.addWidget(
  refinementListWithPanel({
    attribute: 'brands',
  })
);

The hidden property drives the noRefinement CSS class.

Specs

https://instantsearch-css.netlify.com/widgets/panel/

RFC

https://github.com/algolia/instantsearch-rfcs/pull/9

Preview

https://deploy-preview-3253--instantsearchjs.netlify.com/stories/?selectedStory=Panel.with%20default

[algobot]

Deploy preview for instantsearchjs ready!

Built with commit 0b23ca3

https://deploy-preview-3253--instantsearchjs.netlify.com

[Haroenv]

looks good to ship to me :)

[francoischalifour]

I made the possible changes.

Remaining notes are discussions that we can either do here or in person :)

[francoischalifour]

The last commit rolls back to the original behavior:

• we give the full options to the templates and to the hidden option
• the evaluated hidden option (() => true) drives the noRefinement CSS class.

[samouss]

I didn't realise from the review that we don't have access to the render options inside the Panel but only to the raw render option provided by InstantSearch not the connector. The current implem is nice but not good enough IMO. We should have access to the same set of options that the wrapped widget provide (e.g. list of facets with count). One solution proposed by @francoischalifour was a getRenderingOptions function implemented by all the widgets. But it's adds one (more) method to the widget API surface for a pretty small use case. Would be better to find an alternative that allow the panel to be hooked inside the widget itself.

The previous API was also convenient because the autoHideContainer was automatically computed. Right now it's on the user to implement it. Would be nice to have a default implementation of the that will automatically read the value from the render options (this is how React & Vue works). The magic is far from what I prefer to implement but we have to admit that it's way more convenient for the users. With this implementation I think we'll have users asking how to hide the Panel.

[francoischalifour]

Indeed there's a trade off here. We provide the hidden method but the user must find the right boolean expression to hide the widget.

Would be better to find an alternative that allow the panel to be hooked inside the widget itself.

Do you more insights on how you would see it working @samouss? AFAIK we never compute the autoHideContainer value anywhere for each widget.

[samouss]

Do you more insights on how you would see it working @samouss?

We the current architecture I have no idea how it would work.

AFAIK we never compute the autoHideContainer value anywhere for each widget.

We do compute the autoHideContainer inside each widget (see RefinementList, Menu, ...).

[francoischalifour]

A solution that I see is to have a canRefine function implemented on all connectors that returns a boolean based on the options (helper, results, state). We can then pass it to the panel.

That would however broaden the API surface. I think it might be time to create an actual connector interface documenting all these required methods.

[francoischalifour]

Now that we have the concept of UI state in v4, we could pass the uiState to the panel so that it's easier to compute the hidden and other values.

[Haroenv]

good point @francoischalifour, open to this change