Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(js): introduce Component API #505

Merged
merged 2 commits into from
Mar 30, 2021
Merged

Conversation

francoischalifour
Copy link
Member

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

@codesandbox-ci
Copy link

codesandbox-ci bot commented Mar 29, 2021

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
Copy link
Contributor

Shipow commented Mar 29, 2021

neat

Copy link
Contributor

@Haroenv Haroenv left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔥

examples/playground/env.ts Show resolved Hide resolved
packages/website/sidebars.js Show resolved Hide resolved
Copy link
Member

@sarahdayan sarahdayan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Super cool, ship it! 🚢

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants