fix(index): warn for inconsistent UI state in development mode

[francoischalifour]

This adds a development warning when the UI state is inconsistent with the widgets mounted on the instance.

Why

We often have users not understanding why certain parameters are not sent to the API. The reason is because widgets drive search parameters. Certain widgets need to be added to the instance for some search parameters to be applied. See a typical issue in #4129.

On support, we often advise to create "virtual widgets" to activate the search parameter, without displaying the widget on the page. This development warning is meant for them to understand why something might look like broken, and provide a solution for them.

I suspect this error to happen even more often with InstantSearch.js v4, where UI state is a predominant concept. My hope is that such a warning reduces to support load that we have regarding this use case.

Warning preview

[InstantSearch.js]: The UI state for the index "instant_search" is not consistent with the widgets mounted.

This can happen when the UI state is specified via initialUiState or routing but that the widgets responsible for this state were not added. This results in query parameters not being sent to the API.

To fully reflect the state, some widgets need to be added to the index "instant_search":

• page needs one of these widgets: "pagination", "infiniteHits"
• refinementList needs one of these widgets: "refinementList"
• hierarchicalMenu needs one of these widgets: "hierarchicalMenu"

If you do not wish to display widgets but still want to support their search parameters, you can mount "virtual widgets" that don't render anything:

const virtualPagination = connectPagination(() => null);
const virtualRefinementList = connectRefinementList(() => null);
const virtualHierarchicalMenu = connectHierarchicalMenu(() => null);

search.addWidgets([
  virtualPagination({ /* ... */ }),
  virtualRefinementList({ /* ... */ }),
  virtualHierarchicalMenu({ /* ... */ })
]);

If you're using custom widgets that do set these query parameters, we recommend using connectors instead.

See https://www.algolia.com/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js/#customize-the-complete-ui-of-the-widgets

Implementation details

The implementation is at the index level. When the search event is triggered by the helper, the index reports if its UI state is not synced with its widgets.

This is detected with the $$type property that defines the type of the widget. If a UI state key is present but that none of the mounted widgets support this key, the warning appears.

Cons of this solution

• The mapping between the UI parameters and the widgets that control them is written manually. We need to maintain that list. Could we make this a private connector API?
• Users creating custom widgets will see this warning because they aren't aware of the $$type property. I don't think this is a bad thing because the warning give them clues that they should use connectors instead (this is what we recommend).
• Users creating custom connectors will likely see this message because they aren't aware of the $$type property.

Possible improvements

• We could think of improving this DX later by even checking if the attributes match in the UI state (not possible right now because we cannot read the attribute option from outside the widget)

[Haroenv]

I really like this idea!