feat(ts): convert hierarchical-menu to TypeScript (#4711)

* feat(ts): convert rating-menu to TypeScript

* feat(ts): convert RefinementList to TypeScript

* fixup! feat(ts): convert RefinementList to TypeScript

* fixup! feat(ts): convert RefinementList to TypeScript

* fixup! fixup! feat(ts): convert RefinementList to TypeScript

* Update src/components/RefinementList/RefinementList.tsx

Co-authored-by: Haroen Viaene <hello@haroen.me>

* fixup! feat(ts): convert RefinementList to TypeScript

* fixup! feat(ts): convert RefinementList to TypeScript

* feat(ts): convert hierarchical-menu to TypeScript

* Apply suggestions from code review

Co-authored-by: Haroen Viaene <hello@haroen.me>

* fixup! feat(ts): convert hierarchical-menu to TypeScript

* avoid casting

* deduplicate

Co-authored-by: Haroen Viaene <hello@haroen.me>

Author: Yannick Croissant

src/components/RefinementList/RefinementList.tsx

@@ -8,6 +8,7 @@ import Template from '../Template/Template';
 import RefinementListItem from './RefinementListItem';
 import SearchBox from '../SearchBox/SearchBox';
 import { RefinementListItem as TRefinementListItem } from '../../connectors/refinement-list/connectRefinementList';
+import { HierarchicalMenuItem } from '../../connectors/hierarchical-menu/connectHierarchicalMenu';
 import {
   SearchBoxRendererCSSClasses,
   SearchBoxTemplates,
@@ -19,14 +20,17 @@ type CSSClasses = {
   [key: string]: any;
 };
 
+type FacetValue = TRefinementListItem | HierarchicalMenuItem;
+type FacetValues = TRefinementListItem[] | HierarchicalMenuItem[];
+
 export type RefinementListProps<
   TTemplates extends Templates,
   TCSSClasses extends CSSClasses
 > = {
   createURL: CreateURL<string>;
   cssClasses: TCSSClasses;
   depth?: number;
-  facetValues?: TRefinementListItem[];
+  facetValues?: FacetValues;
   attribute?: string;
   templateProps?: PreparedTemplateProps<TTemplates>;
   searchBoxTemplateProps?: PreparedTemplateProps<SearchBoxTemplates>;
@@ -58,13 +62,19 @@ type RefinementListPropsWithDefaultProps<
 type RefinementListItemTemplateData<
   TTemplates extends Templates,
   TCSSClasses extends CSSClasses
-> = TRefinementListItem & {
+> = FacetValue & {
   url: string;
 } & Pick<
     RefinementListProps<TTemplates, TCSSClasses>,
     'attribute' | 'cssClasses' | 'isFromSearch'
   >;
 
+function isHierarchicalMenuItem(
+  facetValue: FacetValue
+): facetValue is HierarchicalMenuItem {
+  return (facetValue as HierarchicalMenuItem).data !== undefined;
+}
+
 class RefinementList<
   TTemplates extends Templates,
   TCSSClasses extends CSSClasses
@@ -97,9 +107,13 @@ class RefinementList<
     this.props.toggleRefinement(facetValueToRefine);
   }
 
-  private _generateFacetItem(facetValue: TRefinementListItem) {
+  private _generateFacetItem(facetValue: FacetValue) {
     let subItems;
-    if (facetValue.data && facetValue.data.length > 0) {
+    if (
+      isHierarchicalMenuItem(facetValue) &&
+      Array.isArray(facetValue.data) &&
+      facetValue.data.length > 0
+    ) {
       const { root, ...cssClasses } = this.props.cssClasses;
       subItems = (
         <RefinementList
@@ -138,7 +152,9 @@ class RefinementList<
       [this.props.cssClasses.selectedItem]: facetValue.isRefined,
       [this.props.cssClasses.disabledItem]: !facetValue.count,
       [this.props.cssClasses.parentItem]:
-        facetValue.data && facetValue.data.length > 0,
+        isHierarchicalMenuItem(facetValue) &&
+        Array.isArray(facetValue.data) &&
+        facetValue.data.length > 0,
     });
 
     return (
@@ -303,7 +319,8 @@ class RefinementList<
     const facetValues = this.props.facetValues &&
       this.props.facetValues.length > 0 && (
         <ul className={this.props.cssClasses.list}>
-          {this.props.facetValues.map(this._generateFacetItem, this)}
+          {// @ts-expect-error until TS > 4.2.3 is used https://github.com/microsoft/TypeScript/commit/b217f22e798c781f55d17da72ed099a9dee5c650
+          this.props.facetValues.map(this._generateFacetItem, this)}
         </ul>
       );
 

src/components/RefinementList/__tests__/RefinementList-test.tsx

@@ -340,8 +340,20 @@ describe('RefinementList', () => {
             label: 'foo',
             count: 1,
             data: [
-              { value: 'bar', label: 'bar', count: 2, isRefined: false },
-              { value: 'baz', label: 'baz', count: 3, isRefined: false },
+              {
+                value: 'bar',
+                label: 'bar',
+                count: 2,
+                isRefined: false,
+                data: null,
+              },
+              {
+                value: 'baz',
+                label: 'baz',
+                count: 3,
+                isRefined: false,
+                data: null,
+              },
             ],
             isRefined: false,
           },
@@ -382,8 +394,20 @@ describe('RefinementList', () => {
             label: 'foo',
             count: 1,
             data: [
-              { value: 'bar', label: 'bar', count: 2, isRefined: false },
-              { value: 'baz', label: 'baz', count: 3, isRefined: false },
+              {
+                value: 'bar',
+                label: 'bar',
+                count: 2,
+                isRefined: false,
+                data: null,
+              },
+              {
+                value: 'baz',
+                label: 'baz',
+                count: 3,
+                isRefined: false,
+                data: null,
+              },
             ],
             isRefined: false,
           },

src/connectors/hierarchical-menu/__tests__/connectHierarchicalMenu-test.js src/connectors/hierarchical-menu/__tests__/connectHierarchicalMenu-test.ts

@@ -5,45 +5,122 @@ import {
   createSendEventForFacet,
   isEqual,
   noop,
+  SendEventForFacet,
 } from '../../lib/utils';
+import { SearchResults } from 'algoliasearch-helper';
+import {
+  Connector,
+  CreateURL,
+  TransformItems,
+  RenderOptions,
+  Widget,
+  SortBy,
+} from '../../types';
 
 const withUsage = createDocumentationMessageGenerator({
   name: 'hierarchical-menu',
   connector: true,
 });
 
-/**
- * @typedef {Object} HierarchicalMenuItem
- * @property {string} value Value of the menu item.
- * @property {string} label Human-readable value of the menu item.
- * @property {number} count Number of matched results after refinement is applied.
- * @property {isRefined} boolean Indicates if the refinement is applied.
- * @property {Object} [data = undefined] n+1 level of items, same structure HierarchicalMenuItem (default: `undefined`).
- */
-
-/**
- * @typedef {Object} CustomHierarchicalMenuWidgetParams
- * @property {string[]} attributes Attributes to use to generate the hierarchy of the menu.
- * @property {string} [separator = '>'] Separator used in the attributes to separate level values.
- * @property {string} [rootPath = null] Prefix path to use if the first level is not the root level.
- * @property {boolean} [showParentLevel=false] Show the siblings of the selected parent levels of the current refined value. This
- * does not impact the root level.
- * @property {number} [limit = 10] Max number of values to display.
- * @property {boolean} [showMore = false] Whether to display the "show more" button.
- * @property {number} [showMoreLimit = 20] Max number of values to display when showing more.
- * @property  {string[]|function} [sortBy = ['name:asc']] How to sort refinements. Possible values: `count|isRefined|name:asc|name:desc`.
- *
- * You can also use a sort function that behaves like the standard Javascript [compareFunction](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Syntax).
- * @property {function(object[]):object[]} [transformItems] Function to transform the items passed to the templates.
- */
-
-/**
- * @typedef {Object} HierarchicalMenuRenderingOptions
- * @property {function(item.value): string} createURL Creates an url for the next state for a clicked item.
- * @property {HierarchicalMenuItem[]} items Values to be rendered.
- * @property {function(item.value)} refine Sets the path of the hierarchical filter and triggers a new search.
- * @property {Object} widgetParams All original `CustomHierarchicalMenuWidgetParams` forwarded to the `renderFn`.
- */
+export type HierarchicalMenuItem = {
+  /**
+   * Value of the menu item.
+   */
+  value: string;
+  /**
+   * Human-readable value of the menu item.
+   */
+  label: string;
+  /**
+   * Number of matched results after refinement is applied.
+   */
+  count: number;
+  /**
+   * Indicates if the refinement is applied.
+   */
+  isRefined: boolean;
+  /**
+   * n+1 level of items, same structure HierarchicalMenuItem
+   */
+  data: HierarchicalMenuItem[] | null;
+};
+
+export type HierarchicalMenuConnectorParams = {
+  /**
+   *  Attributes to use to generate the hierarchy of the menu.
+   */
+  attributes: string[];
+  /**
+   * Separator used in the attributes to separate level values.
+   */
+  separator?: string;
+  /**
+   * Prefix path to use if the first level is not the root level.
+   */
+  rootPath?: string | null;
+  /**
+   * Show the siblings of the selected parent levels of the current refined value. This
+   * does not impact the root level.
+   */
+  showParentLevel?: boolean;
+  /**
+   * Max number of values to display.
+   */
+  limit?: number;
+  /**
+   * Whether to display the "show more" button.
+   */
+  showMore?: boolean;
+  /**
+   * Max number of values to display when showing more.
+   */
+  showMoreLimit?: number;
+  /**
+   * How to sort refinements. Possible values: `count|isRefined|name:asc|name:desc`.
+   * You can also use a sort function that behaves like the standard Javascript [compareFunction](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Syntax).
+   */
+  sortBy?: SortBy<HierarchicalMenuItem>;
+  /**
+   * Function to transform the items passed to the templates.
+   */
+  transformItems?: TransformItems<HierarchicalMenuItem>;
+};
+
+export type HierarchicalMenuRendererOptions = {
+  /**
+   * Creates an url for the next state for a clicked item.
+   */
+  createURL: CreateURL<string>;
+  /**
+   * Values to be rendered.
+   */
+  items: HierarchicalMenuItem[];
+  /**
+   * Sets the path of the hierarchical filter and triggers a new search.
+   */
+  refine: (value: string) => void;
+  /**
+   *  Indicates if search state can be refined.
+   */
+  canRefine: boolean;
+  /**
+   * True if the menu is displaying all the menu items.
+   */
+  isShowingMore: boolean;
+  /**
+   * Toggles the number of values displayed between `limit` and `showMoreLimit`.
+   */
+  toggleShowMore: () => void;
+  /**
+   * `true` if the toggleShowMore button can be activated (enough items to display more or
+   * already displaying more than `limit` items)
+   */
+  canToggleShowMore: boolean;
+  /**
+   * Send event to insights middleware
+   */
+  sendEvent: SendEventForFacet;
+};
 
 /**
  * **HierarchicalMenu** connector provides the logic to build a custom widget
@@ -58,10 +135,18 @@ const withUsage = createDocumentationMessageGenerator({
  * @param {function} unmountFn Unmount function called when the widget is disposed.
  * @return {function(CustomHierarchicalMenuWidgetParams)} Re-usable widget factory for a custom **HierarchicalMenu** widget.
  */
-export default function connectHierarchicalMenu(renderFn, unmountFn = noop) {
+export type ConnectHierarchicalMenu = Connector<
+  HierarchicalMenuRendererOptions,
+  HierarchicalMenuConnectorParams
+>;
+
+const connectHierarchicalMenu: ConnectHierarchicalMenu = function connectHierarchicalMenu(
+  renderFn,
+  unmountFn = noop
+) {
   checkRendering(renderFn, withUsage());
 
-  return (widgetParams = {}) => {
+  return widgetParams => {
     const {
       attributes,
       separator = ' > ',
@@ -71,8 +156,8 @@ export default function connectHierarchicalMenu(renderFn, unmountFn = noop) {
       showMore = false,
       showMoreLimit = 20,
       sortBy = ['name:asc'],
-      transformItems = items => items,
-    } = widgetParams;
+      transformItems = (items => items) as TransformItems<HierarchicalMenuItem>,
+    } = widgetParams || {};
 
     if (!attributes || !Array.isArray(attributes) || attributes.length === 0) {
       throw new Error(
@@ -90,7 +175,7 @@ export default function connectHierarchicalMenu(renderFn, unmountFn = noop) {
     // so that we can always map $hierarchicalFacetName => real attributes
     // we use the first attribute name
     const [hierarchicalFacetName] = attributes;
-    let sendEvent;
+    let sendEvent: HierarchicalMenuRendererOptions['sendEvent'];
 
     // Provide the same function to the `renderFn` so that way the user
     // has to only bind it once when `isFirstRendering` for instance
@@ -99,21 +184,45 @@ export default function connectHierarchicalMenu(renderFn, unmountFn = noop) {
       toggleShowMore();
     }
 
-    return {
-      $$type: 'ais.hierarchicalMenu',
+    let _refine: HierarchicalMenuRendererOptions['refine'] | undefined;
 
-      isShowingMore: false,
+    let isShowingMore = false;
 
-      createToggleShowMore(renderOptions) {
-        return () => {
-          this.isShowingMore = !this.isShowingMore;
-          this.render(renderOptions);
-        };
-      },
+    function createToggleShowMore(
+      renderOptions: RenderOptions,
+      widget: Widget
+    ) {
+      return () => {
+        isShowingMore = !isShowingMore;
+        widget.render!(renderOptions);
+      };
+    }
 
-      getLimit() {
-        return this.isShowingMore ? showMoreLimit : limit;
-      },
+    function getLimit() {
+      return isShowingMore ? showMoreLimit : limit;
+    }
+
+    function _prepareFacetValues(
+      facetValues: SearchResults.HierarchicalFacet[]
+    ): HierarchicalMenuItem[] {
+      return facetValues
+        .slice(0, getLimit())
+        .map(({ name: label, path: value, data, ...subValue }) => {
+          const item: HierarchicalMenuItem = {
+            ...subValue,
+            label,
+            value,
+            data: null,
+          };
+          if (Array.isArray(data)) {
+            item.data = _prepareFacetValues(data);
+          }
+          return item;
+        });
+    }
+
+    return {
+      $$type: 'ais.hierarchicalMenu',
 
       init(initOptions) {
         const { instantSearchInstance } = initOptions;
@@ -127,21 +236,10 @@ export default function connectHierarchicalMenu(renderFn, unmountFn = noop) {
         );
       },
 
-      _prepareFacetValues(facetValues) {
-        return facetValues
-          .slice(0, this.getLimit())
-          .map(({ name: label, path: value, ...subValue }) => {
-            if (Array.isArray(subValue.data)) {
-              subValue.data = this._prepareFacetValues(subValue.data);
-            }
-            return { ...subValue, label, value };
-          });
-      },
-
       render(renderOptions) {
         const { instantSearchInstance } = renderOptions;
 
-        toggleShowMore = this.createToggleShowMore(renderOptions);
+        toggleShowMore = createToggleShowMore(renderOptions, this);
 
         renderFn(
           {
@@ -182,8 +280,11 @@ export default function connectHierarchicalMenu(renderFn, unmountFn = noop) {
         instantSearchInstance,
         helper,
       }) {
+        let items: HierarchicalMenuRendererOptions['items'] = [];
+        let canToggleShowMore = false;
+
         // Bind createURL to this specific attribute
-        function _createURL(facetValue) {
+        function _createURL(facetValue: string) {
           return createURL(
             state
               .resetPage()
@@ -196,54 +297,55 @@ export default function connectHierarchicalMenu(renderFn, unmountFn = noop) {
             instantSearchInstance,
             helper,
             attribute: hierarchicalFacetName,
-            widgetType: this.$$type,
+            widgetType: this.$$type!,
           });
         }
 
-        if (!this._refine) {
-          this._refine = function(facetValue) {
+        if (!_refine) {
+          _refine = function(facetValue) {
             sendEvent('click', facetValue);
             helper
               .toggleFacetRefinement(hierarchicalFacetName, facetValue)
               .search();
           };
         }
 
-        const facetValues = results
-          ? results.getFacetValues(hierarchicalFacetName, { sortBy }).data || []
-          : [];
-        const items = transformItems(
-          results ? this._prepareFacetValues(facetValues) : []
-        );
-
-        const getHasExhaustiveItems = () => {
-          if (!results) {
-            return false;
-          }
+        if (results) {
+          const facetValues = results.getFacetValues(hierarchicalFacetName, {
+            sortBy,
+          });
+          const facetItems =
+            facetValues && !Array.isArray(facetValues) && facetValues.data
+              ? facetValues.data
+              : [];
 
-          const currentLimit = this.getLimit();
           // If the limit is the max number of facet retrieved it is impossible to know
           // if the facets are exhaustive. The only moment we are sure it is exhaustive
           // is when it is strictly under the number requested unless we know that another
           // widget has requested more values (maxValuesPerFacet > getLimit()).
           // Because this is used for making the search of facets unable or not, it is important
           // to be conservative here.
-          return state.maxValuesPerFacet > currentLimit
-            ? facetValues.length <= currentLimit
-            : facetValues.length < currentLimit;
-        };
+          const hasExhaustiveItems =
+            (state.maxValuesPerFacet || 0) > getLimit()
+              ? facetItems.length <= getLimit()
+              : facetItems.length < getLimit();
+
+          canToggleShowMore =
+            showMore && (isShowingMore || !hasExhaustiveItems);
+
+          items = transformItems(_prepareFacetValues(facetItems));
+        }
 
         return {
           items,
-          refine: this._refine,
+          refine: _refine,
           canRefine: items.length > 0,
           createURL: _createURL,
           sendEvent,
           widgetParams,
-          isShowingMore: this.isShowingMore,
+          isShowingMore,
           toggleShowMore: cachedToggleShowMore,
-          canToggleShowMore:
-            showMore && (this.isShowingMore || !getHasExhaustiveItems()),
+          canToggleShowMore,
         };
       },
 
@@ -290,6 +392,7 @@ export default function connectHierarchicalMenu(renderFn, unmountFn = noop) {
             attributes,
             separator,
             rootPath,
+            // @ts-ignore `showParentLevel` is missing in the SearchParameters.HierarchicalFacet declaration
             showParentLevel,
           });
 
@@ -322,4 +425,6 @@ export default function connectHierarchicalMenu(renderFn, unmountFn = noop) {
       },
     };
   };
-}
+};
+
+export default connectHierarchicalMenu;

src/connectors/hierarchical-menu/connectHierarchicalMenu.js src/connectors/hierarchical-menu/connectHierarchicalMenu.ts

@@ -6,7 +6,6 @@ import {
   PlainSearchParameters,
 } from 'algoliasearch-helper';
 import { InstantSearch, Hit, GeoLoc } from './instantsearch';
-import { TransformItems } from './connector';
 import { BindEventForHits, SendEventForHits } from '../lib/utils';
 import {
   AutocompleteRendererOptions,
@@ -82,6 +81,10 @@ import {
   MenuConnectorParams,
   MenuRendererOptions,
 } from '../connectors/menu/connectMenu';
+import {
+  HierarchicalMenuConnectorParams,
+  HierarchicalMenuRendererOptions,
+} from '../connectors/hierarchical-menu/connectHierarchicalMenu';
 import {
   RefinementListRendererOptions,
   RefinementListConnectorParams,
@@ -256,25 +259,8 @@ export type IndexRenderState = Partial<{
   };
   hierarchicalMenu: {
     [attribute: string]: WidgetRenderState<
-      {
-        items: any[];
-        refine(facetValue: any): void;
-        createURL(facetValue: any): string;
-        isShowingMore: boolean;
-        toggleShowMore(): void;
-        canToggleShowMore: boolean;
-      },
-      {
-        attributes: string[];
-        separator: string;
-        rootPath: string | null;
-        showParentLevel: boolean;
-        limit: number;
-        showMore: boolean;
-        showMoreLimit: number;
-        sortBy: any;
-        transformItems: TransformItems<any>;
-      }
+      HierarchicalMenuRendererOptions,
+      HierarchicalMenuConnectorParams
     >;
   };
   hits: WidgetRenderState<HitsRendererOptions, HitsConnectorParams>;

src/types/widget.ts

@@ -21,12 +21,18 @@ Object {
   "depth": 0,
   "facetValues": Array [
     Object {
+      "count": 1,
+      "data": Array [],
+      "isRefined": false,
       "label": "foo",
-      "value": undefined,
+      "value": "",
     },
     Object {
+      "count": 2,
+      "data": Array [],
+      "isRefined": false,
       "label": "bar",
-      "value": undefined,
+      "value": "",
     },
   ],
   "isShowingMore": false,
@@ -75,12 +81,18 @@ Object {
   "depth": 0,
   "facetValues": Array [
     Object {
+      "count": 1,
+      "data": Array [],
+      "isRefined": false,
       "label": "foo",
-      "value": undefined,
+      "value": "",
     },
     Object {
+      "count": 2,
+      "data": Array [],
+      "isRefined": false,
       "label": "bar",
-      "value": undefined,
+      "value": "",
     },
   ],
   "isShowingMore": false,
@@ -129,14 +141,20 @@ Object {
   "depth": 0,
   "facetValues": Array [
     Object {
+      "count": 1,
+      "data": Array [],
+      "isRefined": false,
       "label": "foo",
       "transformed": true,
-      "value": undefined,
+      "value": "",
     },
     Object {
+      "count": 2,
+      "data": Array [],
+      "isRefined": false,
       "label": "bar",
       "transformed": true,
-      "value": undefined,
+      "value": "",
     },
   ],
   "isShowingMore": false,
@@ -230,12 +248,18 @@ Object {
   "depth": 0,
   "facetValues": Array [
     Object {
+      "count": 1,
+      "data": Array [],
+      "isRefined": false,
       "label": "foo",
-      "value": undefined,
+      "value": "",
     },
     Object {
+      "count": 2,
+      "data": Array [],
+      "isRefined": false,
       "label": "bar",
-      "value": undefined,
+      "value": "",
     },
   ],
   "isShowingMore": false,

src/widgets/hierarchical-menu/__tests__/__snapshots__/hierarchical-menu-test.js.snap src/widgets/hierarchical-menu/__tests__/__snapshots__/hierarchical-menu-test.ts.snap

@@ -0,0 +1,297 @@
+import { render } from 'preact';
+import algoliasearchHelper, {
+  AlgoliaSearchHelper,
+  SearchParameters,
+  SearchResults,
+} from 'algoliasearch-helper';
+import hierarchicalMenu, {
+  HierarchicalMenuWidgetParams,
+} from '../hierarchical-menu';
+import {
+  HierarchicalMenuConnectorParams,
+  HierarchicalMenuRendererOptions,
+} from '../../../connectors/hierarchical-menu/connectHierarchicalMenu';
+import {
+  createInitOptions,
+  createRenderOptions,
+} from '../../../../test/mock/createWidget';
+import { createSearchClient } from '../../../../test/mock/createSearchClient';
+import { createSingleSearchResponse } from '../../../../test/mock/createAPIResponse';
+import { Widget, WidgetRenderState } from '../../../types';
+
+const mockedRender = render as jest.Mock;
+
+jest.mock('preact', () => {
+  const module = jest.requireActual('preact');
+
+  module.render = jest.fn();
+
+  return module;
+});
+
+describe('hierarchicalMenu()', () => {
+  let container: HTMLDivElement;
+  let attributes: string[];
+  let options: HierarchicalMenuConnectorParams & HierarchicalMenuWidgetParams;
+  let widget: Widget<{
+    renderState: WidgetRenderState<
+      HierarchicalMenuRendererOptions,
+      HierarchicalMenuConnectorParams
+    >;
+  }>;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    attributes = ['hello', 'world'];
+    options = { container, attributes };
+
+    mockedRender.mockClear();
+  });
+
+  describe('Usage', () => {
+    it('throws without container', () => {
+      // @ts-expect-error
+      options = { container: undefined, attributes };
+      expect(() => hierarchicalMenu(options))
+        .toThrowErrorMatchingInlineSnapshot(`
+"The \`container\` option is required.
+
+See documentation: https://www.algolia.com/doc/api-reference/widgets/hierarchical-menu/js/"
+`);
+    });
+  });
+
+  describe('render', () => {
+    let results: SearchResults<any>;
+    let data: SearchResults.HierarchicalFacet;
+    let helper: AlgoliaSearchHelper;
+    let state: SearchParameters;
+
+    beforeEach(() => {
+      data = {
+        name: 'baz',
+        count: 3,
+        path: '',
+        isRefined: false,
+        data: [
+          { name: 'foo', count: 1, path: '', isRefined: false, data: [] },
+          { name: 'bar', count: 2, path: '', isRefined: false, data: [] },
+        ],
+      };
+      helper = algoliasearchHelper(createSearchClient(), '');
+      helper.toggleFacetRefinement = jest.fn().mockReturnThis();
+      helper.search = jest.fn();
+      results = new SearchResults(helper.state, [
+        createSingleSearchResponse({}),
+      ]);
+      results.getFacetValues = jest.fn(() => data);
+      state = new SearchParameters();
+      options = { container, attributes };
+    });
+
+    it('understand provided cssClasses', () => {
+      const userCssClasses = {
+        root: 'root',
+        noRefinementRoot: 'noRefinementRoot',
+        searchBox: 'searchBox',
+        list: 'list',
+        childList: 'childList',
+        item: 'item',
+        selectedItem: 'selectedItem',
+        parentItem: 'parentItem',
+        link: 'link',
+        label: 'label',
+        count: 'count',
+        noResults: 'noResults',
+        showMore: 'showMore',
+        disabledShowMore: 'disabledShowMore',
+      };
+      widget = hierarchicalMenu({ ...options, cssClasses: userCssClasses });
+
+      widget.init!(createInitOptions({ helper }));
+      widget.render!(createRenderOptions({ results, state }));
+
+      const [firstRender] = mockedRender.mock.calls;
+
+      expect(firstRender[0].props).toMatchSnapshot();
+    });
+
+    it('calls render', () => {
+      widget = hierarchicalMenu(options);
+
+      widget.init!(createInitOptions({ helper }));
+      widget.render!(createRenderOptions({ results, state }));
+
+      const [firstRender] = mockedRender.mock.calls;
+
+      expect(mockedRender).toHaveBeenCalledTimes(1);
+      expect(firstRender[0].props).toMatchSnapshot();
+    });
+
+    it('asks for results.getFacetValues', () => {
+      widget = hierarchicalMenu(options);
+
+      widget.init!(createInitOptions({ helper }));
+      widget.render!(createRenderOptions({ results, state }));
+
+      expect(results.getFacetValues).toHaveBeenCalledTimes(1);
+      expect(results.getFacetValues).toHaveBeenCalledWith('hello', {
+        sortBy: ['name:asc'],
+      });
+    });
+
+    it('has a sortBy option', () => {
+      widget = hierarchicalMenu({ ...options, sortBy: ['name:asc'] });
+
+      widget.init!(createInitOptions({ helper }));
+      widget.render!(createRenderOptions({ results, state }));
+
+      expect(results.getFacetValues).toHaveBeenCalledTimes(1);
+      expect(results.getFacetValues).toHaveBeenCalledWith('hello', {
+        sortBy: ['name:asc'],
+      });
+    });
+
+    it('has a templates option', () => {
+      widget = hierarchicalMenu({
+        ...options,
+        templates: {
+          item: 'item2',
+        },
+      });
+
+      widget.init!(createInitOptions({ helper }));
+      widget.render!(createRenderOptions({ results, state }));
+
+      const [firstRender] = mockedRender.mock.calls;
+
+      expect(firstRender[0].props).toMatchSnapshot();
+    });
+
+    it('has a transformItems options', () => {
+      widget = hierarchicalMenu({
+        ...options,
+        transformItems: items =>
+          items.map(item => ({ ...item, transformed: true })),
+      });
+
+      widget.init!(createInitOptions({ helper }));
+      widget.render!(createRenderOptions({ results, state }));
+
+      const [firstRender] = mockedRender.mock.calls;
+
+      expect(firstRender[0].props).toMatchSnapshot();
+    });
+
+    it('sets facetValues to empty array when no results', () => {
+      data = {
+        name: 'baz',
+        count: 0,
+        path: '',
+        isRefined: false,
+        data: [],
+      };
+      widget = hierarchicalMenu(options);
+
+      widget.init!(createInitOptions({ helper }));
+      widget.render!(createRenderOptions({ results, state }));
+
+      const [firstRender] = mockedRender.mock.calls;
+
+      expect(firstRender[0].props).toMatchSnapshot();
+    });
+
+    it('has a toggleRefinement method', () => {
+      widget = hierarchicalMenu(options);
+
+      widget.init!(createInitOptions({ helper }));
+      widget.render!(createRenderOptions({ results, state }));
+
+      const [firstRender] = mockedRender.mock.calls;
+
+      const elementToggleRefinement = firstRender[0].props.toggleRefinement;
+      elementToggleRefinement('mom');
+
+      expect(helper.toggleFacetRefinement).toHaveBeenCalledTimes(1);
+      expect(helper.toggleFacetRefinement).toHaveBeenCalledWith('hello', 'mom');
+      expect(helper.search).toHaveBeenCalledTimes(1);
+    });
+
+    it('has a limit option', () => {
+      const secondLevel: SearchResults.HierarchicalFacet[] = [
+        { name: 'six', path: 'six', count: 6, isRefined: false, data: [] },
+        { name: 'seven', path: 'seven', count: 7, isRefined: false, data: [] },
+        { name: 'eight', path: 'eight', count: 8, isRefined: false, data: [] },
+        { name: 'nine', path: 'nine', count: 9, isRefined: false, data: [] },
+      ];
+      const firstLevel: SearchResults.HierarchicalFacet[] = [
+        { name: 'one', path: 'one', count: 1, isRefined: false, data: [] },
+        {
+          name: 'two',
+          path: 'two',
+          count: 2,
+          isRefined: false,
+          data: secondLevel,
+        },
+        { name: 'three', path: 'three', count: 3, isRefined: false, data: [] },
+        { name: 'four', path: 'four', count: 4, isRefined: false, data: [] },
+        { name: 'five', path: 'five', count: 5, isRefined: false, data: [] },
+      ];
+      data = {
+        name: 'zero',
+        path: 'zero',
+        count: 0,
+        isRefined: false,
+        data: firstLevel,
+      };
+      const expectedFacetValues = [
+        { label: 'one', value: 'one', count: 1, isRefined: false, data: [] },
+        {
+          label: 'two',
+          value: 'two',
+          count: 2,
+          isRefined: false,
+          data: [
+            {
+              label: 'six',
+              value: 'six',
+              count: 6,
+              isRefined: false,
+              data: [],
+            },
+            {
+              label: 'seven',
+              value: 'seven',
+              count: 7,
+              isRefined: false,
+              data: [],
+            },
+            {
+              label: 'eight',
+              value: 'eight',
+              count: 8,
+              isRefined: false,
+              data: [],
+            },
+          ],
+        },
+        {
+          label: 'three',
+          value: 'three',
+          count: 3,
+          isRefined: false,
+          data: [],
+        },
+      ];
+      widget = hierarchicalMenu({ ...options, limit: 3 });
+
+      widget.init!(createInitOptions({ helper }));
+      widget.render!(createRenderOptions({ results, state }));
+
+      const [firstRender] = mockedRender.mock.calls;
+
+      const actualFacetValues = firstRender[0].props.facetValues;
+      expect(actualFacetValues).toEqual(expectedFacetValues);
+    });
+  });
+});

src/widgets/hierarchical-menu/__tests__/hierarchical-menu-test.js

@@ -3,26 +3,190 @@
 import { h, render } from 'preact';
 import cx from 'classnames';
 import RefinementList from '../../components/RefinementList/RefinementList';
-import connectHierarchicalMenu from '../../connectors/hierarchical-menu/connectHierarchicalMenu';
+import connectHierarchicalMenu, {
+  HierarchicalMenuItem,
+  HierarchicalMenuConnectorParams,
+  HierarchicalMenuRendererOptions,
+} from '../../connectors/hierarchical-menu/connectHierarchicalMenu';
 import defaultTemplates from './defaultTemplates';
+import { PreparedTemplateProps } from '../../lib/utils/prepareTemplateProps';
 import {
   prepareTemplateProps,
   getContainerNode,
   createDocumentationMessageGenerator,
 } from '../../lib/utils';
+import {
+  TransformItems,
+  Template,
+  WidgetFactory,
+  RendererOptions,
+  SortBy,
+} from '../../types';
 import { component } from '../../lib/suit';
 
 const withUsage = createDocumentationMessageGenerator({
   name: 'hierarchical-menu',
 });
 const suit = component('HierarchicalMenu');
 
+type HierarchicalMenuTemplates = {
+  /**
+   * Item template, provided with `name`, `count`, `isRefined`, `url` data properties.
+   */
+  item: Template<{
+    name: string;
+    count: number;
+    isRefined: boolean;
+    url: string;
+  }>;
+  /**
+   * Template used for the show more text, provided with `isShowingMore` data property.
+   */
+  showMoreText: Template<{ isShowingMore: boolean }>;
+};
+
+export type HierarchicalMenuCSSClasses = {
+  /**
+   * CSS class to add to the root element.
+   */
+  root: string | string[];
+  /**
+   * CSS class to add to the root element when no refinements.
+   */
+  noRefinementRoot: string | string[];
+  /**
+   * CSS class to add to the list element.
+   */
+  list: string | string[];
+  /**
+   * CSS class to add to the child list element.
+   */
+  childList: string | string[];
+  /**
+   * CSS class to add to each item element.
+   */
+  item: string | string[];
+  /**
+   * CSS class to add to each selected item element.
+   */
+  selectedItem: string | string[];
+  /**
+   * CSS class to add to each parent item element.
+   */
+  parentItem: string | string[];
+  /**
+   * CSS class to add to each link (when using the default template).
+   */
+  link: string | string[];
+  /**
+   * CSS class to add to each label (when using the default template).
+   */
+  label: string | string[];
+  /**
+   * CSS class to add to each count element (when using the default template).
+   */
+  count: string | string[];
+  /**
+   * CSS class to add to the show more element.
+   */
+  showMore: string | string[];
+  /**
+   * CSS class to add to the disabled show more element.
+   */
+  disabledShowMore: string | string[];
+};
+
+type HierarchicalMenuRendererCSSClasses = Required<
+  {
+    [key in keyof HierarchicalMenuCSSClasses]: string;
+  }
+>;
+
+export type HierarchicalMenuWidgetParams = {
+  /**
+   * CSS Selector or HTMLElement to insert the widget.
+   */
+  container: string | HTMLElement;
+  /**
+   * Array of attributes to use to generate the hierarchy of the menu.
+   */
+  attributes: string[];
+  /**
+   * Separator used in the attributes to separate level values.
+   */
+  separator?: string;
+  /**
+   * Prefix path to use if the first level is not the root level.
+   */
+  rootPath?: string;
+  /**
+   * Show the siblings of the selected parent level of the current refined value.
+   *
+   * With `showParentLevel` set to `true` (default):
+   * - Parent lvl0
+   *   - **lvl1**
+   *     - **lvl2**
+   *     - lvl2
+   *     - lvl2
+   *   - lvl 1
+   *   - lvl 1
+   * - Parent lvl0
+   * - Parent lvl0
+   *
+   * With `showParentLevel` set to `false`:
+   * - Parent lvl0
+   *   - **lvl1**
+   *     - **lvl2**
+   * - Parent lvl0
+   * - Parent lvl0
+   */
+  showParentLevel?: boolean;
+  /**
+   * Max number of values to display.
+   */
+  limit?: number;
+  /**
+   * Whether to display the "show more" button.
+   */
+  showMore?: boolean;
+  /**
+   * Max number of values to display when showing more.
+   * does not impact the root level.
+   */
+  showMoreLimit?: number;
+  /**
+   * How to sort refinements. Possible values: `count|isRefined|name:asc|name:desc`.
+   * You can also use a sort function that behaves like the standard Javascript [compareFunction](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Syntax).
+   */
+  sortBy?: SortBy<HierarchicalMenuItem>;
+  /**
+   * Function to transform the items passed to the templates.
+   */
+  transformItems?: TransformItems<HierarchicalMenuItem>;
+  /**
+   * Templates to use for the widget.
+   */
+  templates?: Partial<HierarchicalMenuTemplates>;
+  /**
+   * CSS classes to add to the wrapping elements.
+   */
+  cssClasses?: Partial<HierarchicalMenuCSSClasses>;
+};
+
 const renderer = ({
   cssClasses,
   containerNode,
   showMore,
   templates,
   renderState,
+}: {
+  cssClasses: HierarchicalMenuRendererCSSClasses;
+  containerNode: HTMLElement;
+  showMore: boolean;
+  templates: Partial<HierarchicalMenuTemplates>;
+  renderState: {
+    templateProps?: PreparedTemplateProps<HierarchicalMenuTemplates>;
+  };
 }) => (
   {
     createURL,
@@ -32,8 +196,9 @@ const renderer = ({
     isShowingMore,
     toggleShowMore,
     canToggleShowMore,
-  },
-  isFirstRendering
+  }: HierarchicalMenuRendererOptions &
+    RendererOptions<HierarchicalMenuConnectorParams>,
+  isFirstRendering: boolean
 ) => {
   if (isFirstRendering) {
     renderState.templateProps = prepareTemplateProps({
@@ -60,67 +225,6 @@ const renderer = ({
   );
 };
 
-/**
- * @typedef {Object} HierarchicalMenuCSSClasses
- * @property {string|string[]} [root] CSS class to add to the root element.
- * @property {string|string[]} [noRefinementRoot] CSS class to add to the root element when no refinements.
- * @property {string|string[]} [list] CSS class to add to the list element.
- * @property {string|string[]} [childList] CSS class to add to the child list element.
- * @property {string|string[]} [item] CSS class to add to each item element.
- * @property {string|string[]} [selectedItem] CSS class to add to each selected item element.
- * @property {string|string[]} [parentItem] CSS class to add to each parent item element.
- * @property {string|string[]} [link] CSS class to add to each link (when using the default template).
- * @property {string|string[]} [label] CSS class to add to each label (when using the default template).
- * @property {string|string[]} [count] CSS class to add to each count element (when using the default template).
- * @property {string|string[]} [showMore] CSS class to add to the show more element.
- * @property {string|string[]} [disabledShowMore] CSS class to add to the disabled show more element.
- */
-
-/**
- * @typedef {Object} HierarchicalMenuTemplates
- * @property {string|function(object):string} [item] Item template, provided with `name`, `count`, `isRefined`, `url` data properties.
- * @property {string|function} [showMoreText] Template used for the show more text, provided with `isShowingMore` data property.
- */
-
-/**
- * @typedef {Object} HierarchicalMenuWidgetParams
- * @property {string|HTMLElement} container CSS Selector or HTMLElement to insert the widget.
- * @property {string[]} attributes Array of attributes to use to generate the hierarchy of the menu.
- * @property {string} [separator = " > "] Separator used in the attributes to separate level values.
- * @property {string} [rootPath] Prefix path to use if the first level is not the root level.
- * @property {boolean} [showParentLevel = true] Show the siblings of the selected parent level of the current refined value. This
- * @property {number} [limit = 10] Max number of values to display.
- * @property {boolean} [showMore = false] Whether to display the "show more" button.
- * @property {number} [showMoreLimit = 20] Max number of values to display when showing more.
- * does not impact the root level.
- *
- * The hierarchical menu is able to show or hide the siblings with `showParentLevel`.
- *
- * With `showParentLevel` set to `true` (default):
- * - Parent lvl0
- *   - **lvl1**
- *     - **lvl2**
- *     - lvl2
- *     - lvl2
- *   - lvl 1
- *   - lvl 1
- * - Parent lvl0
- * - Parent lvl0
- *
- * With `showParentLevel` set to `false`:
- * - Parent lvl0
- *   - **lvl1**
- *     - **lvl2**
- * - Parent lvl0
- * - Parent lvl0
- * @property {string[]|function} [sortBy = ['name:asc']] How to sort refinements. Possible values: `count|isRefined|name:asc|name:desc`.
- *
- * You can also use a sort function that behaves like the standard Javascript [compareFunction](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Syntax).
- * @property {function(object[]):object[]} [transformItems] Function to transform the items passed to the templates.
- * @property {HierarchicalMenuTemplates} [templates] Templates to use for the widget.
- * @property {HierarchicalMenuCSSClasses} [cssClasses] CSS classes to add to the wrapping elements.
- */
-
 /**
  * The hierarchical menu widget is used to create a navigation based on a hierarchy of facet attributes.
  *
@@ -172,7 +276,15 @@ const renderer = ({
  *   })
  * ]);
  */
-export default function hierarchicalMenu(widgetParams) {
+export type HierarchicalMenuWidget = WidgetFactory<
+  HierarchicalMenuRendererOptions,
+  HierarchicalMenuConnectorParams,
+  HierarchicalMenuWidgetParams
+>;
+
+const hierarchicalMenu: HierarchicalMenuWidget = function hierarchicalMenu(
+  widgetParams
+) {
   const {
     container,
     attributes,
@@ -250,4 +362,6 @@ export default function hierarchicalMenu(widgetParams) {
     }),
     $$widgetType: 'ais.hierarchicalMenu',
   };
-}
+};
+
+export default hierarchicalMenu;