feat(js): change renderer implementation to virtual DOM

[francoischalifour]

This is a complete rework of the rendering system of Autocomplete from a DOM implementation to an agnostic virtual DOM implementation.

Problems

Here's a list of the problems we have with the current DOM implementation:

• Performance. Until now, we relied solely on DOM manipulation to re-render the panel on each state change (note: a state change also happens on an item hover because the item becomes active).
• Scrolling. Since hovering an item triggers a state change, we had UI flashes when the dropdown had a scroll bar because we used to reset the whole panel. This made advanced panel rendering impossible to use.
• Debugging. We couldn't easily inspect the panel with DevTools even with the debug mode because it triggered a state change and you lost the DOM reference of the element you wanted to inspect.
• Plugins. The rendering of our plugins was coupled with the DOM and we couldn't leverage users' framework preference.

Templates

Templates used to accept a string in return, or void. Users were allowed to trigger side effects when returning void (e.g., appending to the root element and attaching events).

We don't pass the root element anymore because it's now transparent; you need to return a VNode that contains this logic and that the library appends to its parent.

autocomplete({
  // ...
  getSources({ query }) {
    return [
      {
        // ...
        templates: {
          header({ items }) {
            // A string is a valid VNode
            return `Query Suggestions ${items.length}`;
          },
          item({ item }) {
            // A Preact component compiles to `preact.createElement`
            return <Item {...item} />;
          },
          footer({ pragma, items }) {
            // `pragma` defaults to `preact.createElement`
            return pragma('div', {
              // You can still render HTML:
              dangerouslySetInnerHTML: {
                __html: `<div>items: ${items.length}</div>`,
              },
            });
          },
        },
      },
    ];
  },
});

How do I render HTML?

We now internally manipulate virtual nodes, which isn't compatible with HTML. There are still two ways to write HTML.

Using dangerouslySetInnerHTML

pragma('div', {
  dangerouslySetInnerHTML: {
    __html: `<div>Items: ${items.length}</div>`,
  },
});

Using the htm library

The htm library allows to create HTML elements from virtual DOM.

See example →

API

We introduced two new options: pragma and pragmaFrag (names taken from @babel/plugin-transform-react-jsx). These two options default to preact.createElement and preact.Fragment.

These two pragmas are passed to the template functions so that users (and plugin authors) can leverage the pragmas passed to the Autocomplete instance, making the rendering environment-agnostic.

Impact on plugins

Until now, plugins were manipulating DOM elements, no matter the frontend framework you were using. This new element API allows plugins to be framework agnostic by using the template-provided pragma and pragmaFrag params.

Bundle size impact

Since we now embed Preact in Autocomplete JS, the gzipped UMD bundle size increased from 10KB to 13KB. This is not a great impact because we already embed Preact in InstantSearch.js. Besides, it'll allow community to build better and more interactive templates.

Future

Perhaps that this API is actually enough to unlock our React, Vue and Angular implementations. These framework-based flavors could only be syntax sugar on top of Autocomplete JS.

Next steps

• Leverage this API to render the search box too.
• The Autocomplete JS with Preact bindings could be exported at another endpoint so that users don't embed Preact if they don't need it.

[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 4a3d11c:

Sandbox	Source
@algolia/js-example	Configuration
@algolia/react-renderer-example	Configuration
Autocomplete with HTM	PR

[Haroenv]

I think pragma should be called h or createElement, wdyt?

[francoischalifour]

@Haroenv I initially called it createElement, but when I introduced Fragment, the two were distinct enough to make me reconsider the naming. Conceptually we're close to what @babel/plugin-transform-react-jsx is doing so I figured pragma* might make more sense? I'm not too sure.

[Haroenv]

Those are indeed the name of the options, but not really what you interact with as a user, which is h, createElement or jsx

[francoischalifour]

[...] but not really what you interact with as a user [...]

Yeah that makes perfect sense.

Wdyt about keeping pragma and pragmaFrag as options and to pass createElement and Fragment in the templates? Otherwise going fully with createElement and Fragment?

[eunjae-lee]

going fully with createElement and Fragment

I'm in favor of going fully.

[Haroenv]

what does an example using a provided pragma / createElement look like (without using jsx directly)?

[Haroenv]

I'm not sure whether the main example should be using jsx, since it might confuse people unfamiliar with it (Shopify, magento...)

[francoischalifour]

what does an example using a provided pragma / createElement look like (without using jsx directly)?

You can see in the plugins implementations.

[francoischalifour]

I'm not sure whether the main example should be using jsx, since it might confuse people unfamiliar with it (Shopify, magento...)

The main example is used as a playground. We'll provide code samples for people relying on HTML.

[francoischalifour]

I created this sandbox to demo how you can use Autocomplete with HTML.

[francoischalifour]

Since 3a9d69b, the two options are renamed renderer.createElement and renderer.Fragment.

[eunjae-lee]

Looks good to me

[Haroenv]

🙌