feat(js): introduce Component API

[francoischalifour]

This introduces a new Component API that is first used for highlight utils. It will then be leveraged to package our layouts (see #499).

Description

The Component API provides a way to pass components to the Autocomplete rendering lifecycles. This PR leverages this API to pass the highlight components, previously handled by highlightHit.

These components are bound to the provided renderer, meaning that users don't need to worry about using Preact, React or Vue—the integration remains seamless.

Usage

Basic

autocomplete({
  container: '#autocomplete',
  getSources({ query }) {
    return [
      {
        // ...
        templates: {
          item({ item, components }) {
            return <components.Highlight hit={item} attribute="name" />;
          },
        },
      },
    ];
  },
});

4 components are provided by default:

• Highlight
• Snippet
• ReverseHighlight
• ReverseSnippet

Provide user components

The future layouts will be leveraging this Component API.

import { SearchByAlgolia } from '@algolia/autocomplete-layout-classic';

autocomplete({
  container: '#autocomplete',
  components: {
    SearchByAlgolia,
  },
  render({ sections, components }, root) {
    render(
      <Fragment>
        <div className="aa-PanelLayout aa-Panel--scrollable">{sections}</div>
        <components.SearchByAlgolia />
      </Fragment>,
      root
    );
  },
});

Specifying a renderer:

import { createSearchByAlgoliaComponent } from '@algolia/autocomplete-layout-classic';
import React, { createElement, Fragment } from 'react';
import { render } from 'react-dom';

const renderer = {
  createElement,
  Fragment,
};

autocomplete({
  container: '#autocomplete',
  components: {
    SearchByAlgolia: createSearchByAlgoliaComponent(renderer),
  },
  renderer,
  render({ sections, components }, root) {
    render(
      <Fragment>
        <div className="aa-PanelLayout aa-Panel--scrollable">{sections}</div>
        <components.SearchByAlgolia />
      </Fragment>,
      root
    );
  },
});

Impact

Autocomplete layouts become just component creators

The layouts introduced in #499 will now just become components bound to a renderer. It will make them easy to package and to distribute.

Plugins could register components

The Autocomplete Plugins API could be extended to allow component registration. This will make a component available in the Autocomplete rendering lifecycles.

Example: a preview panel plugin that registers a PreviewPanel component.

Community can create Autocomplete components for any framework

Since components can remain framework-agnostic, people will be able to create components for Autocomplete experiences, compatible with Preact, React or Vue.

Next steps

• Plugins cannot yet register components, but it's technically possible if needed.
• I removed the documentation of the previous highlightHit (and other) exported functions. We'll need to document this Component API in another PR.

Related

• The idea came from Haroen's comment feat(layout): introduce Layout API #499 (comment)
• The API is inspired by Vue 2 components registration

[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 68b084c:

Sandbox	Source
@algolia/autocomplete-example-playground	Configuration
@algolia/autocomplete-example-query-suggestion-with-categories	Configuration
@algolia/autocomplete-example-query-suggestions-with-hits	Configuration
@algolia/autocomplete-example-query-suggestions-with-inline-categories	Configuration
@algolia/autocomplete-example-query-suggestions-with-recent-searches	Configuration
@algolia/autocomplete-example-query-suggestions	Configuration
@algolia/autocomplete-example-react-renderer	Configuration
@algolia/autocomplete-example-recently-viewed-items	Configuration

[Shipow]

neat

[Haroenv]

🔥

[sarahdayan]

Super cool, ship it! 🚢