feat(hooks): implement useClearRefinements (#3256)

* feat(hooks): implement useClearRefinements

FX-737
#3252

* Update examples/hooks/components/ClearRefinements.tsx

Co-authored-by: François Chalifour <francoischalifour@users.noreply.github.com>

Co-authored-by: François Chalifour <francoischalifour@users.noreply.github.com>

examples/hooks/App.css

@@ -35,6 +35,13 @@ body {
   gap: 0.5rem;
 }
 
+.CurrentRefinements {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5em;
+}
+
 .Hit-label {
   flex: 1;
   margin-right: 1rem;

examples/hooks/App.tsx

@@ -4,6 +4,7 @@ import React from 'react';
 import { InstantSearch, DynamicWidgets } from 'react-instantsearch-hooks';
 
 import {
+  ClearRefinements,
   Configure,
   CurrentRefinements,
   HierarchicalMenu,
@@ -120,20 +121,23 @@ export function App() {
           </div>
           <PoweredBy />
 
-          <CurrentRefinements
-            transformItems={(items) =>
-              items.map((item) => {
-                const label = item.label.startsWith('hierarchicalCategories')
-                  ? 'Hierarchy'
-                  : item.label;
+          <div className="CurrentRefinements">
+            <ClearRefinements />
+            <CurrentRefinements
+              transformItems={(items) =>
+                items.map((item) => {
+                  const label = item.label.startsWith('hierarchicalCategories')
+                    ? 'Hierarchy'
+                    : item.label;
 
-                return {
-                  ...item,
-                  attribute: label,
-                };
-              })
-            }
-          />
+                  return {
+                    ...item,
+                    attribute: label,
+                  };
+                })
+              }
+            />
+          </div>
 
           <QueryRuleContext
             trackedFilters={{

examples/hooks/components/ClearRefinements.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import {
+  useClearRefinements,
+  UseClearRefinementsProps,
+} from 'react-instantsearch-hooks';
+import { cx } from '../cx';
+
+export type ClearRefinementsProps = React.ComponentProps<'div'> &
+  UseClearRefinementsProps;
+
+export function ClearRefinements(props: ClearRefinementsProps) {
+  const { canRefine, refine } = useClearRefinements(props);
+
+  return (
+    <div className={cx('ais-ClearRefinements', props.className)}>
+      <button
+        className={cx(
+          'ais-ClearRefinements-button',
+          !canRefine && 'ais-ClearRefinements-button--disabled'
+        )}
+        disabled={!canRefine}
+        onClick={() => refine()}
+      >
+        Clear Refinements
+      </button>
+    </div>
+  );
+}

examples/hooks/components/index.ts

@@ -1,3 +1,4 @@
+export * from './ClearRefinements';
 export * from './Configure';
 export * from './CurrentRefinements';
 export * from './HierarchicalMenu';

packages/react-instantsearch-hooks/src/__tests__/useClearRefinements.test.tsx

@@ -0,0 +1,89 @@
+import { renderHook } from '@testing-library/react-hooks';
+import React from 'react';
+
+import { createInstantSearchTestWrapper } from '../../../../test/utils';
+import { useClearRefinements } from '../useClearRefinements';
+import { useRefinementList } from '../useRefinementList';
+
+import type { UseRefinementListProps } from '..';
+
+describe('useClearRefinements', () => {
+  test('returns the connector render state', async () => {
+    const wrapper = createInstantSearchTestWrapper();
+    const { result, waitForNextUpdate } = renderHook(
+      () => useClearRefinements(),
+      {
+        wrapper,
+      }
+    );
+
+    // Initial render state from manual `getWidgetRenderState`
+    expect(result.current).toEqual({
+      hasRefinements: false,
+      canRefine: false,
+      refine: expect.any(Function),
+      createURL: expect.any(Function),
+    });
+
+    await waitForNextUpdate();
+
+    // InstantSearch.js state from the `render` lifecycle step
+    expect(result.current).toEqual({
+      hasRefinements: false,
+      canRefine: false,
+      refine: expect.any(Function),
+      createURL: expect.any(Function),
+    });
+  });
+
+  test('returns items on render', async () => {
+    const wrapper = createInstantSearchTestWrapper({
+      initialUiState: {
+        indexName: {
+          refinementList: {
+            brand: ['Apple'],
+          },
+        },
+      },
+    });
+
+    const { result, waitForNextUpdate } = renderHook(
+      () => useClearRefinements(),
+      {
+        wrapper: ({ children }) =>
+          wrapper({
+            children: (
+              <>
+                <RefinementList attribute="brand" />
+                {children}
+              </>
+            ),
+          }),
+      }
+    );
+
+    // Initial render state from manual `getWidgetRenderState`
+    expect(result.current).toEqual({
+      hasRefinements: false,
+      canRefine: false,
+      refine: expect.any(Function),
+      createURL: expect.any(Function),
+    });
+
+    await waitForNextUpdate();
+
+    // InstantSearch.js state from the `render` lifecycle step
+    expect(result.current).toEqual({
+      hasRefinements: true,
+      canRefine: true,
+      refine: expect.any(Function),
+      createURL: expect.any(Function),
+    });
+  });
+});
+
+function RefinementList(props: UseRefinementListProps) {
+  useRefinementList(props);
+
+  return null;
+}

packages/react-instantsearch-hooks/src/index.ts

@@ -4,6 +4,7 @@ export * from './InstantSearch';
 export * from './InstantSearchServerContext';
 export * from './InstantSearchSSRProvider';
 export * from './SearchIndex';
+export * from './useClearRefinements';
 export * from './useConfigure';
 export * from './useConnector';
 export * from './useCurrentRefinements';

packages/react-instantsearch-hooks/src/useClearRefinements.ts

@@ -0,0 +1,17 @@
+import connectClearRefinements from 'instantsearch.js/es/connectors/clear-refinements/connectClearRefinements';
+
+import { useConnector } from './useConnector';
+
+import type {
+  ClearRefinementsConnectorParams,
+  ClearRefinementsWidgetDescription,
+} from 'instantsearch.js/es/connectors/clear-refinements/connectClearRefinements';
+
+export type UseClearRefinementsProps = ClearRefinementsConnectorParams;
+
+export function useClearRefinements(props?: UseClearRefinementsProps) {
+  return useConnector<
+    ClearRefinementsConnectorParams,
+    ClearRefinementsWidgetDescription
+  >(connectClearRefinements, props);
+}