Skip to content

Commit e5dafef

Browse files
HaroenvHaroenv
committed
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
1 parent 7eb6810 commit e5dafef

File tree

4 files changed

+55
-49
lines changed

4 files changed

+55
-49
lines changed

‎MIGRATION.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -165,13 +165,13 @@ The `indices` option has been removed, in favour of using `index` widgets (see t
165165
```js
166166
const autocomplete = connectAutocomplete(() => {/* ... */});
167167

168-
search.addWidget(
168+
search.addWidgets([
169169
autocomplete({
170170
indices: [{
171171
name: "additional"
172172
}]
173173
})
174-
);
174+
]);
175175
```
176176

177177
Will be replaced with this:

‎README.md‎

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -59,31 +59,27 @@ const search = instantsearch({
5959
searchClient: algoliasearch('latency', '6be0576ff61c053d5f9a3225e2a90f76'),
6060
});
6161

62-
// 2. Create an interactive search box
63-
search.addWidget(
62+
search.addWidgets([
63+
// 2. Create an interactive search box
6464
instantsearch.widgets.searchBox({
6565
container: '#searchbox',
6666
placeholder: 'Search for products',
67-
})
68-
);
67+
}),
6968

70-
// 3. Plug the search results into the product container
71-
search.addWidget(
69+
// 3. Plug the search results into the product container
7270
instantsearch.widgets.hits({
7371
container: '#products',
7472
templates: {
7573
item: '{{#helpers.highlight}}{ "attribute": "name" }{{/helpers.highlight}}',
7674
},
77-
})
78-
);
75+
}),
7976

80-
// 4. Make the brands refinable
81-
search.addWidget(
77+
// 4. Make the brands refinable
8278
instantsearch.widgets.refinementList({
8379
container: '#brand',
8480
attribute: 'brand',
85-
})
86-
);
81+
}),
82+
]);
8783

8884
// 5. Start the search!
8985
search.start();

‎src/lib/InstantSearch.ts‎

Lines changed: 25 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -264,23 +264,24 @@ See ${createDocumentationLink({
264264
}
265265

266266
/**
267-
* Adds a widget. This can be done before and after InstantSearch has been started. Adding a
268-
* widget after InstantSearch started is considered **EXPERIMENTAL** and therefore
269-
* it is possibly buggy, if you find anything please
270-
* [open an issue](https://github.com/algolia/instantsearch.js/issues/new?title=Problem%20with%20hot%20addWidget).
271-
* @param widget The widget to add to InstantSearch. Widgets are simple objects
272-
* that have methods that map the search life cycle in a UI perspective. Usually widgets are
273-
* created by [widget factories](widgets.html) like the one provided with InstantSearch.js.
267+
* Adds a widget to the search instance.
268+
* A widget can be added either before or after InstantSearch has started.
269+
* @param widget The widget to add to InstantSearch.
270+
*
271+
* @deprecated This method will still be supported in 4.x releases, but not further. It is replaced by `addWidgets([widget])`.
274272
*/
275273
public addWidget(widget: Widget) {
274+
warning(
275+
false,
276+
'addWidget will still be supported in 4.x releases, but not further. It is replaced by `addWidgets([widget])`'
277+
);
276278
this.addWidgets([widget]);
277279
}
278280

279281
/**
280-
* Adds multiple widgets. This can be done before and after the InstantSearch has been started. This feature
281-
* is considered **EXPERIMENTAL** and therefore it is possibly buggy, if you find anything please
282-
* [open an issue](https://github.com/algolia/instantsearch.js/issues/new?title=Problem%20with%20addWidgets).
283-
* @param {Widget[]} widgets The array of widgets to add to InstantSearch.
282+
* Adds multiple widgets to the search instance.
283+
* Widgets can be added either before or after InstantSearch has started.
284+
* @param widgets The array of widgets to add to InstantSearch.
284285
*/
285286
public addWidgets(widgets: Widget[]) {
286287
if (!Array.isArray(widgets)) {
@@ -309,20 +310,25 @@ See ${createDocumentationLink({
309310
}
310311

311312
/**
312-
* Removes a widget. This can be done after the InstantSearch has been started. This feature
313-
* is considered **EXPERIMENTAL** and therefore it is possibly buggy, if you find anything please
314-
* [open an issue](https://github.com/algolia/instantsearch.js/issues/new?title=Problem%20with%20removeWidget).
315-
* @param {Widget} widget The widget instance to remove from InstantSearch. This widget must implement a `dispose()` method in order to be gracefully removed.
313+
* Removes a widget from the search instance.
314+
* @deprecated This method will still be supported in 4.x releases, but not further. It is replaced by `removeWidgets([widget])`
315+
* @param widget The widget instance to remove from InstantSearch.
316+
*
317+
* The widget must implement a `dispose()` method to clear its state.
316318
*/
317319
public removeWidget(widget: Widget) {
320+
warning(
321+
false,
322+
'removeWidget will still be supported in 4.x releases, but not further. It is replaced by `removeWidgets([widget])`'
323+
);
318324
this.removeWidgets([widget]);
319325
}
320326

321327
/**
322-
* Removes multiple widgets. This can be done only after the InstantSearch has been started. This feature
323-
* is considered **EXPERIMENTAL** and therefore it is possibly buggy, if you find anything please
324-
* [open an issue](https://github.com/algolia/instantsearch.js/issues/new?title=Problem%20with%20addWidgets).
325-
* @param {Widget[]} widgets Array of widgets instances to remove from InstantSearch.
328+
* Removes multiple widgets from the search instance.
329+
* @param widgets Array of widgets instances to remove from InstantSearch.
330+
*
331+
* The widgets must implement a `dispose()` method to clear their states.
326332
*/
327333
public removeWidgets(widgets: Widget[]) {
328334
if (!Array.isArray(widgets)) {

‎src/lib/__tests__/InstantSearch-test.js‎

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -280,7 +280,7 @@ See https://www.algolia.com/doc/api-reference/widgets/configure/js/`);
280280
});
281281

282282
describe('addWidget(s)', () => {
283-
it('forwards the call to `addWidget` to the main index', () => {
283+
it('forwards the call of `addWidget` to the main index', () => {
284284
const searchClient = createSearchClient();
285285
const search = new InstantSearch({
286286
indexName: 'indexName',
@@ -289,12 +289,14 @@ describe('addWidget(s)', () => {
289289

290290
expect(search.mainIndex.getWidgets()).toHaveLength(0);
291291

292-
search.addWidget(createWidget());
292+
expect(() => search.addWidget(createWidget())).toWarnDev(
293+
'[InstantSearch.js]: addWidget will still be supported in 4.x releases, but not further. It is replaced by `addWidgets([widget])`'
294+
);
293295

294296
expect(search.mainIndex.getWidgets()).toHaveLength(1);
295297
});
296298

297-
it('forwards the call to `addWidgets` to the main index', () => {
299+
it('forwards the call of `addWidgets` to the main index', () => {
298300
const searchClient = createSearchClient();
299301
const search = new InstantSearch({
300302
indexName: 'indexName',
@@ -319,11 +321,13 @@ describe('removeWidget(s)', () => {
319321

320322
const widget = createWidget();
321323

322-
search.addWidget(widget);
324+
search.addWidgets([widget]);
323325

324326
expect(search.mainIndex.getWidgets()).toHaveLength(1);
325327

326-
search.removeWidget(widget);
328+
expect(() => search.removeWidget(widget)).toWarnDev(
329+
'[InstantSearch.js]: removeWidget will still be supported in 4.x releases, but not further. It is replaced by `removeWidgets([widget])`'
330+
);
327331

328332
expect(search.mainIndex.getWidgets()).toHaveLength(0);
329333
});
@@ -481,7 +485,7 @@ describe('start', () => {
481485

482486
const widget = createWidget();
483487

484-
search.addWidget(widget);
488+
search.addWidgets([widget]);
485489

486490
search.start();
487491

@@ -778,7 +782,7 @@ describe('scheduleSearch', () => {
778782
searchClient: createSearchClient(),
779783
});
780784

781-
search.addWidget(createWidget());
785+
search.addWidgets([createWidget()]);
782786

783787
search.start();
784788

@@ -799,7 +803,7 @@ describe('scheduleSearch', () => {
799803
searchClient: createSearchClient(),
800804
});
801805

802-
search.addWidget(createWidget());
806+
search.addWidgets([createWidget()]);
803807

804808
search.start();
805809

@@ -827,7 +831,7 @@ describe('scheduleRender', () => {
827831

828832
const widget = createWidget();
829833

830-
search.addWidget(widget);
834+
search.addWidgets([widget]);
831835

832836
search.start();
833837

@@ -846,7 +850,7 @@ describe('scheduleRender', () => {
846850

847851
const widget = createWidget();
848852

849-
search.addWidget(widget);
853+
search.addWidgets([widget]);
850854

851855
search.start();
852856

@@ -870,7 +874,7 @@ describe('scheduleRender', () => {
870874

871875
const widget = createWidget();
872876

873-
search.addWidget(widget);
877+
search.addWidgets([widget]);
874878

875879
search.start();
876880

@@ -893,7 +897,7 @@ describe('scheduleStalledRender', () => {
893897

894898
const widget = createWidget();
895899

896-
search.addWidget(widget);
900+
search.addWidgets([widget]);
897901

898902
search.start();
899903

@@ -926,7 +930,7 @@ describe('scheduleStalledRender', () => {
926930

927931
const widget = createWidget();
928932

929-
search.addWidget(widget);
933+
search.addWidgets([widget]);
930934

931935
search.start();
932936

@@ -962,7 +966,7 @@ describe('scheduleStalledRender', () => {
962966

963967
const widget = createWidget();
964968

965-
search.addWidget(widget);
969+
search.addWidgets([widget]);
966970

967971
expect(widget.render).toHaveBeenCalledTimes(0);
968972

@@ -1061,7 +1065,7 @@ describe('createURL', () => {
10611065
},
10621066
});
10631067

1064-
search.addWidget(connectSearchBox(noop)({}));
1068+
search.addWidgets([connectSearchBox(noop)({})]);
10651069
search.start();
10661070

10671071
expect(search.createURL({ indexName: { query: 'Apple' } })).toBe(
@@ -1084,7 +1088,7 @@ describe('createURL', () => {
10841088
},
10851089
});
10861090

1087-
search.addWidget(connectSearchBox(noop)({}));
1091+
search.addWidgets([connectSearchBox(noop)({})]);
10881092
search.start();
10891093
search.createURL();
10901094

0 commit comments

Comments
 (0)