feat: introduce initialUiState option

[samouss]

Summary

This PR introduces the initialUiState option at the InstantSearch level. The option allows users to provide an uiState used for the initial request. Only for the initial request. I've chosen to name the option initialXXX rather than uiState to have a clear intent. At some point, we might want to introduce the concept of controlled state (like React InstantSearch) that could use the option uiState.

At the moment the type definitions are incorrect. We have only one type that defines the uiState but we have to define two different types. The first is one is the "global" uiState and the second one is the "local" to each index. The "global" uiState is built on multiple "local" uiState. We'll update the definition in a separate PR.

Usage

const search = instantsearch({
  // ...
  initialUiState: {
    instant_search: {
      query: "Apple"
    },
    instant_search_price_asc: {
      refinementList: {
        brand: ["Apple"]
      }
    }
  }
});

Checkout the example on Storybook.

[Haroenv]

small typo, but works as expected as far as I can tell

[Haroenv]

How does it behave when combined with routing on initial load with a state in the url?

[samouss]

How does it behave when combined with routing on initial load with a state in the url?

Nothing is implemented right now since routing is not updated (yet). For a first version I think an override (or shallow merge) will be enough otherwise we have to implement a merge function for UiState. This is something that I would like to avoid as much as possible. Another alternative is to allow the user to provide its own function to perform the merge.

[francoischalifour]

initialXXX is also the prefix I would have gone for. I'm wondering if uiState is a concept that users should know about though. On the other hand, state is too vague. For reference, we use searchState in the React implementation, but I'm not convinced this is better.

[fabregas4]

Any evidence this actually works in v4? Can't get it to work at all myself. No console errors, but also zero impact on results. Have followed the example at https://www.algolia.com/doc/api-reference/widgets/instantsearch/js/#widget-param-initialuistate

[Haroenv]

Note that you need to mount a (could be virtual / non-rendering) widget too. We have a warning for that case normally, so I’d like to see your reproduction on codesandbox

[fabregas4]

@Haroenv Thanks for responding. Here is some code on codesandbox:
https://codesandbox.io/s/wizardly-jackson-ovx2f?fontsize=14

Not sure what you mean about mounting a widget. The hits widget should be enough right?

You'll see in the sample that there are results produced but they don't have the query or Designer refinement applied. Have tried various options but none are making a difference. Have tried just the query and not the refinementList, and vice versa. Not 100% sure if initialUiState is meant to have a property of "indexName" or "products" (which is the actual index name). Have tried both in any case. Have also tried not including this node, i.e. just:
initialUiState: { refinementList: { Designer: ["Zimmermann"] } }
which is how the code example says its done on this page: https://www.algolia.com/doc/guides/building-search-ui/upgrade-guides/js/#upgrade-from-v3-to-v4

I'm not the most advanced coder but the documentation in this area seems to be very light.

Shouldn't be any issue on the index side, as falling back to v3 and specifying searchParameters produces expected results. E.g.
searchParameters: { disjunctiveFacetsRefinements: {"Designer":["Zimmermann"]} }

Any ideas?

[Haroenv]

const search = instantsearch({
  indexName: "products",
  searchClient,
  initialUiState: {
    products: {
      query: "fakequerythatshouldreturnnoresults",
      refinementList: {
        Designer: ["Zimmermann"]
      }
    }
  }
});

const virtualRefinementList = instantsearch.connectors.connectRefinementList(
  () => null
);
const virtualSearchBox = instantsearch.connectors.connectSearchBox(
  () => null
);

search.addWidgets([
  virtualSearchBox(),
  virtualRefinementList({ attribute: "Designer" }),
  instantsearch.widgets.hits({
    container: "#hits",
    templates: {
      item: `<div>{{Designer}} - {{ProductTitle}}</div>`
    }
  })
]);

This is what's meant with "virtual widget".

Thanks for pointing out that this section is indeed insufficient to follow if you didn't already use advanced InstantSearch features.

Another option is the following:

search.addWidgets([
  instantsearch.widgets.configure(
      { disjunctiveFacetsRefinements: {"Designer":["Zimmermann"]} }
  ),
]);

[Haroenv]

see my example: https://codesandbox.io/s/determined-wood-quvoq

[fabregas4]

Thanks, that seems to have done the job. I must say it does seem more difficult than using searchParameters from previous versions, so I'm not sure why that would be deprecated in favour of this, although I'm sure you guys have your reasons :) Cheers

[Haroenv]

I think you missed the first part of that note, saying the default replacement is the configure widget. I've updated the docs to be clearer by the way

[fabregas4]

I did miss that, my bad. Looking at the docs now...

https://www.algolia.com/doc/api-reference/widgets/configure/js/
points me to:
https://www.algolia.com/doc/api-reference/search-api-parameters/

There is no mention of "disjunctiveFacetsRefinements" as a possible parameter in the searchParameters object.

[Haroenv]

True, that’s also somewhat confusing. The arguments aren’t just search parameters, but also helper ones: https://community.algolia.com/algoliasearch-helper-js/reference.html