feat: add experimental composition APIs

[eunjae-lee]

Summary

This PR adds experimental composition APIs.

For now, useConfigure, useRefinementList, useSearchBox, and useConnector are implemented.

In case of useRefinementList, I referred to François' PoC with React InstantSearch.

vue 3

<template>
  <div>
    <p>query: {{ searchBox.query }}</p>
  </div>
</template>

<script>
import { EXPERIMENTAL_useSearchBox } from 'vue-instantsearch/vue3/es';

export default {
  setup() {
    return { searchBox: EXPERIMENTAL_useSearchBox() };
  }
}

vue 2

yarn add @vue/composition-api
# or
npm install @vue/composition-api

// main.js
import Vue from 'vue';
import VueCompositionAPI from '@vue/composition-api';

Vue.use(VueCompositionAPI);

// Child.vue

<template>
  <div>
    <p>query: {{ searchBox.query }}</p>
  </div>
</template>

<script>
import { EXPERIMENTAL_useSearchBox } from 'vue-instantsearch/vue2/es/compositions';
// Import composition APIs from the path above.
// The rest still remain as `import xxx from 'vue-instantsearch'`.

export default {
  setup() {
    return { searchBox: EXPERIMENTAL_useSearchBox() };
  }
}

[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.

[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.

[Haroenv]

I thought you could use the composition api in vue 2 with @vue/composition-api or something like that?

[eunjae-lee]

I thought you could use the composition api in vue 2 with @vue/composition-api or something like that?

You're right. I haven't figured out how to accept that optional dependency for vue 2 yet. So I'm just starting with Vue 3 for now.

[eunjae-lee]

Import with '/src/compositions/index.js' gets replaced with an empty string. It's to exclude this line from Vue 2 bundle:

vue-instantsearch/src/instantsearch.js

Line 7 in 58618c5

export * from './compositions';

[francoischalifour]

Relying on the build script to modify exports is a bit shady and hard to track.

Can we rather have different entry files? (similar to what React is doing)

[Haroenv]

as I rewrote a bunch of the code, it's best to have someone else review too

[francoischalifour]

It would make sense to start introducing the connector Hooks in stacked PRs and to test them a little.

[francoischalifour]

Relying on the build script to modify exports is a bit shady and hard to track.

Can we rather have different entry files? (similar to what React is doing)

[francoischalifour]

Why do we have different data types for widgetParams?

[Haroenv]

in Vue 3, you can only listen to changes from refs, not from plain objects, so we accept both a ref and not a ref, depending on if it needs an update.

This part I'm not 100% sure about, maybe it could accept raw props and put in a ref inside useConnector. Would need to test

[francoischalifour]

Yes I think we should standardize it. (And internally right now we can have an intermediary variable in useConnector to not have to think about all data types whenever we use the props.)

issues pointed out

[Baroshem]

Bumping this topic as it looks great!

I just released an Algolia module for Nuxt 3 -> https://algolia-nc.netlify.app/
And I was looking to include vue-instantsearch there as well.

If you can finish this PR and make these components Vue 3 compatible, I can try to import them to the module as well so that the users can use your components in Nuxt 3 as well 😉

[Haroenv]

@Baroshem, the components are already vue 3 compatible if you import from vue-instantsearch/vue3, but that's indeed not really properly documented yet

[Baroshem]

@Haroenv I see. I will try then to use them in the module so that they can be imported into the Nuxt 3 right now. Thanks for claryfing!

[Baroshem]

Hi @Haroenv

I tried yesterday to import vue-instantsearch/vue3 but failed after many attempts to fix the errors. I had issues with

• "type": "module" in package.json (it was not there so I had to add manually)
• directory imports
• external packages imports (instantsearch.js).

I have very little experience with the source code of vue-instantsearch so I am not sure if the changes I was doing are even correct.

Could you please try to install vue-instantseach/vue3 on fresh Nuxt 3 project and see how it works for you?