feat(core): deprecate addWidget & removeWidget (#4131)

* feat(core): deprecate addWidget & removeWidget Migration guide already mentions this since dc75d2f, discussed with @samouss * Apply suggestions from code review Co-Authored-By: François Chalifour <francoischalifour@users.noreply.github.com> Co-Authored-By: Samuel Vaillant <samuel.vllnt@gmail.com> * docs: use only plural form * Update src/lib/InstantSearch.ts Co-Authored-By: Samuel Vaillant <samuel.vllnt@gmail.com> * chore: fix typo * track warning message
algolia · Sep 24, 2019 · 43398f7 · 43398f7
1 parent c696cc7
commit 43398f7
Show file tree

Hide file tree

Showing 4 changed files with 56 additions and 49 deletions.
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -165,13 +165,13 @@ The `indices` option has been removed, in favour of using `index` widgets (see t
 ```js
 const autocomplete = connectAutocomplete(() => {/* ... */});
 
-search.addWidget(
+search.addWidgets([
   autocomplete({
     indices: [{
       name: "additional"
     }]
   })
-);
+]);
 ```
 
 Will be replaced with this:

diff --git a/README.md b/README.md
@@ -59,31 +59,27 @@ const search = instantsearch({
   searchClient: algoliasearch('latency', '6be0576ff61c053d5f9a3225e2a90f76'),
 });
 
-// 2. Create an interactive search box
-search.addWidget(
+search.addWidgets([
+  // 2. Create an interactive search box
   instantsearch.widgets.searchBox({
     container: '#searchbox',
     placeholder: 'Search for products',
-  })
-);
+  }),
 
-// 3. Plug the search results into the product container
-search.addWidget(
+  // 3. Plug the search results into the product container
   instantsearch.widgets.hits({
     container: '#products',
     templates: {
       item: '{{#helpers.highlight}}{ "attribute": "name" }{{/helpers.highlight}}',
     },
-  })
-);
+  }),
 
-// 4. Make the brands refinable
-search.addWidget(
+  // 4. Make the brands refinable
   instantsearch.widgets.refinementList({
     container: '#brand',
     attribute: 'brand',
-  })
-);
+  }),
+]);
 
 // 5. Start the search!
 search.start();

diff --git a/src/lib/InstantSearch.ts b/src/lib/InstantSearch.ts
@@ -12,6 +12,7 @@ import {
   isPlainObject,
   defer,
   noop,
+  warning,
 } from './utils';
 import {
   InsightsClient as AlgoliaInsightsClient,
@@ -245,23 +246,24 @@ See: https://www.algolia.com/doc/guides/building-search-ui/going-further/backend
   }
 
   /**
-   * Adds a widget. This can be done before and after InstantSearch has been started. Adding a
-   * widget after InstantSearch started is considered **EXPERIMENTAL** and therefore
-   * it is possibly buggy, if you find anything please
-   * [open an issue](https://github.com/algolia/instantsearch.js/issues/new?title=Problem%20with%20hot%20addWidget).
-   * @param  widget The widget to add to InstantSearch. Widgets are simple objects
-   * that have methods that map the search life cycle in a UI perspective. Usually widgets are
-   * created by [widget factories](widgets.html) like the one provided with InstantSearch.js.
+   * Adds a widget to the search instance.
+   * A widget can be added either before or after InstantSearch has started.
+   * @param widget The widget to add to InstantSearch.
+   *
+   * @deprecated This method will still be supported in 4.x releases, but not further. It is replaced by `addWidgets([widget])`.
    */
   public addWidget(widget: Widget) {
+    warning(
+      false,
+      'addWidget will still be supported in 4.x releases, but not further. It is replaced by `addWidgets([widget])`'
+    );
     this.addWidgets([widget]);
   }
 
   /**
-   * Adds multiple widgets. This can be done before and after the InstantSearch has been started. This feature
-   * is considered **EXPERIMENTAL** and therefore it is possibly buggy, if you find anything please
-   * [open an issue](https://github.com/algolia/instantsearch.js/issues/new?title=Problem%20with%20addWidgets).
-   * @param {Widget[]} widgets The array of widgets to add to InstantSearch.
+   * Adds multiple widgets to the search instance.
+   * Widgets can be added either before or after InstantSearch has started.
+   * @param widgets The array of widgets to add to InstantSearch.
    */
   public addWidgets(widgets: Widget[]) {
     if (!Array.isArray(widgets)) {
@@ -290,20 +292,25 @@ See: https://www.algolia.com/doc/guides/building-search-ui/going-further/backend
   }
 
   /**
-   * Removes a widget. This can be done after the InstantSearch has been started. This feature
-   * is considered **EXPERIMENTAL** and therefore it is possibly buggy, if you find anything please
-   * [open an issue](https://github.com/algolia/instantsearch.js/issues/new?title=Problem%20with%20removeWidget).
-   * @param  {Widget} widget The widget instance to remove from InstantSearch. This widget must implement a `dispose()` method in order to be gracefully removed.
+   * Removes a widget from the search instance.
+   * @deprecated This method will still be supported in 4.x releases, but not further. It is replaced by `removeWidgets([widget])`
+   * @param widget The widget instance to remove from InstantSearch.
+   *
+   * The widget must implement a `dispose()` method to clear its state.
    */
   public removeWidget(widget: Widget) {
+    warning(
+      false,
+      'removeWidget will still be supported in 4.x releases, but not further. It is replaced by `removeWidgets([widget])`'
+    );
     this.removeWidgets([widget]);
   }
 
   /**
-   * Removes multiple widgets. This can be done only after the InstantSearch has been started. This feature
-   * is considered **EXPERIMENTAL** and therefore it is possibly buggy, if you find anything please
-   * [open an issue](https://github.com/algolia/instantsearch.js/issues/new?title=Problem%20with%20addWidgets).
-   * @param {Widget[]} widgets Array of widgets instances to remove from InstantSearch.
+   * Removes multiple widgets from the search instance.
+   * @param widgets Array of widgets instances to remove from InstantSearch.
+   *
+   * The widgets must implement a `dispose()` method to clear their states.
    */
   public removeWidgets(widgets: Widget[]) {
     if (!Array.isArray(widgets)) {

diff --git a/src/lib/__tests__/InstantSearch-test.js b/src/lib/__tests__/InstantSearch-test.js
@@ -242,7 +242,7 @@ describe('InstantSearch', () => {
 });
 
 describe('addWidget(s)', () => {
-  it('forwards the call to `addWidget` to the main index', () => {
+  it('forwards the call of `addWidget` to the main index', () => {
     const searchClient = createSearchClient();
     const search = new InstantSearch({
       indexName: 'indexName',
@@ -251,12 +251,14 @@ describe('addWidget(s)', () => {
 
     expect(search.mainIndex.getWidgets()).toHaveLength(0);
 
-    search.addWidget(createWidget());
+    expect(() => search.addWidget(createWidget())).toWarnDev(
+      '[InstantSearch.js]: addWidget will still be supported in 4.x releases, but not further. It is replaced by `addWidgets([widget])`'
+    );
 
     expect(search.mainIndex.getWidgets()).toHaveLength(1);
   });
 
-  it('forwards the call to `addWidgets` to the main index', () => {
+  it('forwards the call of `addWidgets` to the main index', () => {
     const searchClient = createSearchClient();
     const search = new InstantSearch({
       indexName: 'indexName',
@@ -281,11 +283,13 @@ describe('removeWidget(s)', () => {
 
     const widget = createWidget();
 
-    search.addWidget(widget);
+    search.addWidgets([widget]);
 
     expect(search.mainIndex.getWidgets()).toHaveLength(1);
 
-    search.removeWidget(widget);
+    expect(() => search.removeWidget(widget)).toWarnDev(
+      '[InstantSearch.js]: removeWidget will still be supported in 4.x releases, but not further. It is replaced by `removeWidgets([widget])`'
+    );
 
     expect(search.mainIndex.getWidgets()).toHaveLength(0);
   });
@@ -443,7 +447,7 @@ describe('start', () => {
 
     const widget = createWidget();
 
-    search.addWidget(widget);
+    search.addWidgets([widget]);
 
     search.start();
 
@@ -740,7 +744,7 @@ describe('scheduleSearch', () => {
       searchClient: createSearchClient(),
     });
 
-    search.addWidget(createWidget());
+    search.addWidgets([createWidget()]);
 
     search.start();
 
@@ -761,7 +765,7 @@ describe('scheduleSearch', () => {
       searchClient: createSearchClient(),
     });
 
-    search.addWidget(createWidget());
+    search.addWidgets([createWidget()]);
 
     search.start();
 
@@ -789,7 +793,7 @@ describe('scheduleRender', () => {
 
     const widget = createWidget();
 
-    search.addWidget(widget);
+    search.addWidgets([widget]);
 
     search.start();
 
@@ -808,7 +812,7 @@ describe('scheduleRender', () => {
 
     const widget = createWidget();
 
-    search.addWidget(widget);
+    search.addWidgets([widget]);
 
     search.start();
 
@@ -832,7 +836,7 @@ describe('scheduleRender', () => {
 
     const widget = createWidget();
 
-    search.addWidget(widget);
+    search.addWidgets([widget]);
 
     search.start();
 
@@ -855,7 +859,7 @@ describe('scheduleStalledRender', () => {
 
     const widget = createWidget();
 
-    search.addWidget(widget);
+    search.addWidgets([widget]);
 
     search.start();
 
@@ -888,7 +892,7 @@ describe('scheduleStalledRender', () => {
 
     const widget = createWidget();
 
-    search.addWidget(widget);
+    search.addWidgets([widget]);
 
     search.start();
 
@@ -924,7 +928,7 @@ describe('scheduleStalledRender', () => {
 
     const widget = createWidget();
 
-    search.addWidget(widget);
+    search.addWidgets([widget]);
 
     expect(widget.render).toHaveBeenCalledTimes(0);
 
@@ -1023,7 +1027,7 @@ describe('createURL', () => {
       },
     });
 
-    search.addWidget(connectSearchBox(noop)({}));
+    search.addWidgets([connectSearchBox(noop)({})]);
     search.start();
 
     expect(search.createURL({ indexName: { query: 'Apple' } })).toBe(
@@ -1046,7 +1050,7 @@ describe('createURL', () => {
       },
     });
 
-    search.addWidget(connectSearchBox(noop)({}));
+    search.addWidgets([connectSearchBox(noop)({})]);
     search.start();
     search.createURL();