feat(js): pass elements record to render

[francoischalifour]

This adds an API to easily retrieve generated UI elements to manipulate the panel UI.

Why

Finding the right source to render in the panel was cumbersome, and sometimes created friction to generate advanced conditional layouts.

How

We use the sourceId (which is required) as the key to the elements record:

const querySuggestionsPlugin = elements.querySuggestionsPlugin; // or
const querySuggestionsPlugin = elements['querySuggestionsPlugin']; // or
const { querySuggestionsPlugin } = elements;

This makes flows easier to render because with flows, some key values can be undefined (because getSources doesn't return them). In JSX, rendering undefined renders nothing, which is convenient.

API

Before

import { render } from 'preact';

autocomplete({
  // ...
  plugins: [recentSearchesPlugin, querySuggestionsPlugin],
  getSources({ query }) {
    return [
      {
        sourceId: 'products',
        // ...
      },
    ];
  },
  render({ sections }, root) {
    const recentSearches = sections.find(
      (x) => x.props["data-autocomplete-source-id"] === "recentSearchesPlugin"
    );
    const querySuggestions = sections.find(
      (x) => x.props["data-autocomplete-source-id"] === "querySuggestionsPlugin"
    );
    const products = sections.find(
      (x) => x.props["data-autocomplete-source-id"] === "products"
    );

    render(
      <div className="aa-PanelLayout">
        <div>
          {recentSearches}
          {querySuggestions}
        </div>
        <div>{products}</div>
      </div>,
      root
    );
  },
});

After

Single flow

import { render } from 'preact';

autocomplete({
  // ...
  plugins: [recentSearchesPlugin, querySuggestionsPlugin],
  getSources({ query }) {
    return [
      {
        sourceId: 'products',
        // ...
      },
    ];
  },
  render({ elements }, root) {
    const { recentSearchesPlugin, querySuggestionsPlugin, products } = elements;

    render(
      <div className="aa-PanelLayout">
        <div>
          {recentSearchesPlugin}
          {querySuggestionsPlugin}
        </div>
        <div>{products}</div>
      </div>,
      root
    );
  },
});

Multiple flows

import { render } from 'preact';

autocomplete({
  // ...
  plugins: [recentSearchesPlugin, querySuggestionsPlugin],
  getSources({ query, state }) {
    if (state.context.flow === 'editing') {
      return [
        {
          sourceId: 'draftProducts',
          // ...
        },
      ];
    }

    return [
      {
        sourceId: 'products',
        // ...
      },
    ];
  },
  render({ elements, state }, root) {
    const {
      recentSearchesPlugin,
      querySuggestionsPlugin,
      products,
      draftProducts,
    } = elements;

    switch (state.context.flow) {
      case 'editing':
        render(
          <div className="aa-PanelLayout">
            <Editor draftProducts={draftProducts} />
          </div>,
          root
        );
        break;

      default:
        render(
          <div className="aa-PanelLayout">
            <div>
              {recentSearchesPlugin}
              {querySuggestionsPlugin}
            </div>
            <div>{products}</div>
          </div>,
          root
        );
    }
  },
});

[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 09f19ee:

Sandbox	Source
@algolia/js-example	Configuration
@algolia/react-renderer-example	Configuration
@algolia/query-suggestions-with-rich-hits-example	Configuration
@algolia/query-suggestions-example	Configuration
@algolia/qs-with-rs-example	Configuration
@algolia/qs-with-inline-categories-example	Configuration
@algolia/recently-viewed-items-example	Configuration

[shortcuts]

Really nice addition