feat(core): introduce getWidgetRenderState (2/n)

[francoischalifour]

This is part 2 of the series "Render State".

Related

• algolia/instantsearch-rfcs#38
• feat(core): introduce getWidgetUiState lifecycle hook (1/n) #4454

Description

This introduces the widget lifecycle hook getWidgetRenderState and implements it for connectSearchBox.

The getWidgetRenderState method allows to accumulate and store the global render state of the widgets tree. This render state has a similar structure to the UI state but stores the render params.

Motivation

When you mount a widget in the InstantSearch tree, you may want to use its render params (e.g., refine function) in another widget to create richer and more interactive interfaces.

In InstantSearch.js, it requires using the JavaScript helper, which means that you get out of the InstantSearch API. In React InstantSearch, you can hack around it to use a React context and provide the render params to other components. Still, this is a workaround that goes against React's paradigm.

This PR aims at providing an InstantSearch API layer that provides the render state to all widgets.

Usage

In an InstantSearch widget

The render state is available in the render params.

const customPagination = connectPagination(
  ({ renderState, widgetParams }, isFirstRender) => {
    if (isFirstRender) {
      const button = document.createElement('button');
      button.textContent = 'Trigger search';
      button.addEventListener('click', () => {
        // Control the search box from the pagination widget
        renderState.instant_search.searchBox.refine('samsung');
      });
      widgetParams.container.appendChild(button);
    }
  }
);

In a component outside of InstantSearch

The render state is available on the InstantSearch instance on search.renderState so that developers can interact with the search state from outside of InstantSearch widgets. This avoids nesting multiple widgets to use their render params. Using widgets also have the cons of relying on the network and the search results to be back before rendering (because we wait for results before rendering). This results in a UI flash, even if you don't want to display only search data coming from the network; this goes against the progressive enhancement paradigm.

A pattern that can emerge is to mount virtual widgets to make their render state available on the instance, then use the render state params in another website's element.

function App({ search }) {
  function filterSamsungProducts() {
    search.renderState.instant_search.refinementList.brand.refine('Samsung');
  }

  return (
    <div>
      <button onClick={filterSamsungProducts}>Check Samsung products</button>
    </div>
  );
}

The JSX syntax is used for convenience.

With React InstantSearch

This PR doesn't deal with React InstantSearch because it's not based on InstantSearch.js, but this section explains how we can expose this Render State API in React as a next step.

The render state could be exposed using a React Context provider:

function App() {
  return (
    <InstantSearch.RenderStateProvider>
      {(renderState) => (
        /* ... */
      )}
    </InstantSearch.RenderStateProvider>
  );
}

And using React hooks:

function Search() {
  const renderState = useRenderState();

  return (
    /* ... */
  );
}

With Vue InstantSearch

This is an example of a renderState mixin that exposes the API to Vue InstantSearch.

<template>
  <ais-refinement-list>
    <template slot-scope="{ refine, items }">
      <button
        @click="
          refine(items[0].value);
          setQuery('');
        "
      >
        Refine first element and reset query
      </button>
    </template>
  </ais-refinement-list>
</template>

<script>
  export default {
    mixins: [renderState],
    methods: {
      setQuery(query) {
        return this.renderState.instant_search.searchBox.refine(query);
      },
    },
  };
</script>

Detailed design

The render state has a similar structure to the UI state but stores the render params.

Note: the render state is exclusively stored "per widget", as opposed to the UI state that delegates concepts like the search query to a query key, instead of a searchBox key.

Storage

The render state is stored on the InstantSearch instance as an object.

type RenderState = {
  [indexName: string]: {
    searchBox: {
      query: string;
      refine(query: string): void;
      // ...
    };
    // ...
  };
};

const renderState: RenderState = {
  instant_search: {
    searchBox: {
      query: 'iphone',
      refine: ƒ(query),
      // ...
    },
  },
};

API addition

Each widget can now implement a new method called getWidgetRenderState(indexRenderState, renderOptions): IndexRenderState.

Example

const widget = {
  // ...
  getWidgetRenderState(renderState, { helper, searchMetadata }) {
    return {
      ...renderState,
      searchBox: {
        query: helper.state.query || '',
        refine: this._refine,
        clear: this._cachedClear,
        widgetParams,
        isSearchStalled: searchMetadata.isSearchStalled,
      },
    };
  },
};

Having an API for the render state (previously called render params) results in a few benefits:

• No direct behavioral change in how InstantSearch and its widgets work because the API is an addition
• Fewer inconsistencies between init and render returned render params (they would both use getWidgetRenderState)

Storing the render state on the InstantSearch instance unlocks APIs that we wanted to implement:

• Access widgetParams from the InstantSearch instance. This can be useful to track which widget options are used. (E.g., renderState.instant_search.searchBox.widgetParams)
• Provide information to hide widgets with panel. We now have the getWidgetRenderState API that can be used to compute a canRefine value, instead of finding the information with the JavaScript helper.

How we teach this

• Create a new section about the render state in the documentation

Next steps

• Implement the getWidgetRenderState method in all widgets

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit a8d42cd:

Sandbox	Source
InstantSearch.js	Configuration

[yannickcr]

I think it would be better to have it as a method in index, it would simplify the signature (no need to pass instantSearchInstance and parent).

[francoischalifour]

We call it only twice (and will call it only one time once when remove the init method). Besides, it would make it available on the index widget scope, which we want to avoid.

[yannickcr]

If you do not want to expose it you can set it as a "private" function, like createURL.

[francoischalifour]

Right, but we still need to pass the instantSearchInstance reference from init and render to mutate it, so it won't behave the same if we rely on localInstantSearchInstance.

[yannickcr]

Still winning one parameter 😄 , and it is more coherent with what we are already doing in this module.

[Haroenv]

I agree with François, we want to avoid exposing a public API we didn't think about, private isn't really private

[eunjae-lee]

I've read all the changes but not confident enough to approve the PR not because of this pr, but because I'm not in a right headspace at the moment. I wish @Haroenv or @yannickcr approve it whenever they think it's ready.

[Haroenv]

Two questions I'd like to see resolved, otherwise lgtm :)