fix(infinitehits/hits): correctly deprecate __hitIndex (#5495)

* fix(infinitehits/hits): correctly deprecated __hitIndex

JSDoc comments only work when in a docblock

Also added a proper warning so string templates see this too.

* fix: use omit in default template

Author: Haroenv

packages/instantsearch.js/src/components/Answers/Answers.tsx

@@ -8,6 +8,7 @@ import type {
   AnswersTemplates,
 } from '../../widgets/answers/answers';
 import type { ComponentCSSClasses, Hit } from '../../types';
+import { warning } from '../../lib/utils';
 
 export type AnswersComponentCSSClasses = ComponentCSSClasses<AnswersCSSClasses>;
 
@@ -49,7 +50,7 @@ const Answers = ({
       />
     ) : (
       <ul className={cssClasses.list}>
-        {hits.map((hit, position) => (
+        {hits.map((hit, index) => (
           <Template
             {...templateProps}
             templateKey="item"
@@ -58,7 +59,13 @@ const Answers = ({
             key={hit.objectID}
             data={{
               ...hit,
-              __hitIndex: position,
+              get __hitIndex() {
+                warning(
+                  false,
+                  'The `__hitIndex` property is deprecated. Use the absolute `__position` instead.'
+                );
+                return index;
+              },
             }}
           />
         ))}

packages/instantsearch.js/src/components/Hits/Hits.tsx

@@ -5,6 +5,7 @@ import { cx } from '@algolia/ui-components-shared';
 import Template from '../Template/Template';
 import type { SearchResults } from 'algoliasearch-helper';
 import type { BindEventForHits, SendEventForHits } from '../../lib/utils';
+import { warning } from '../../lib/utils';
 import type { PreparedTemplateProps } from '../../lib/templating';
 import type { ComponentCSSClasses, Hit } from '../../types';
 import type { HitsCSSClasses, HitsTemplates } from '../../widgets/hits/hits';
@@ -54,7 +55,13 @@ const Hits = ({
             key={hit.objectID}
             data={{
               ...hit,
-              __hitIndex: index,
+              get __hitIndex() {
+                warning(
+                  false,
+                  'The `__hitIndex` property is deprecated. Use the absolute `__position` instead.'
+                );
+                return index;
+              },
             }}
             bindEvent={bindEvent}
             sendEvent={sendEvent}

packages/instantsearch.js/src/components/InfiniteHits/InfiniteHits.tsx

@@ -10,6 +10,7 @@ import type {
   InfiniteHitsTemplates,
 } from '../../widgets/infinite-hits/infinite-hits';
 import type { SendEventForHits, BindEventForHits } from '../../lib/utils';
+import { warning } from '../../lib/utils';
 
 export type InfiniteHitsComponentCSSClasses =
   ComponentCSSClasses<InfiniteHitsCSSClasses>;
@@ -77,7 +78,7 @@ const InfiniteHits = ({
       )}
 
       <ol className={cssClasses.list}>
-        {hits.map((hit, position) => (
+        {hits.map((hit, index) => (
           <Template
             {...templateProps}
             templateKey="item"
@@ -86,7 +87,13 @@ const InfiniteHits = ({
             key={hit.objectID}
             data={{
               ...hit,
-              __hitIndex: position,
+              get __hitIndex() {
+                warning(
+                  false,
+                  'The `__hitIndex` property is deprecated. Use the absolute `__position` instead.'
+                );
+                return index;
+              },
             }}
             bindEvent={bindEvent}
             sendEvent={sendEvent}

packages/instantsearch.js/src/lib/utils/index.ts

@@ -35,6 +35,7 @@ export * from './isPlainObject';
 export * from './isSpecialClick';
 export * from './logger';
 export * from './mergeSearchParameters';
+export * from './omit';
 export * from './noop';
 export * from './range';
 export * from './render-args';

packages/instantsearch.js/src/lib/utils/omit.ts

@@ -0,0 +1,26 @@
+/**
+ * Creates a new object with the same keys as the original object, but without the excluded keys.
+ * @param source original object
+ * @param excluded keys to remove from the original object
+ * @returns the new object
+ */
+export function omit<
+  TSource extends Record<string, unknown>,
+  TExcluded extends keyof TSource
+>(source: TSource, excluded: TExcluded[]): Omit<TSource, TExcluded> {
+  if (source === null || source === undefined) {
+    return source;
+  }
+
+  type Output = Omit<TSource, TExcluded>;
+  return Object.keys(source).reduce((target, key) => {
+    if ((excluded as Array<keyof TSource>).indexOf(key) >= 0) {
+      return target;
+    }
+
+    const validKey = key as keyof Output;
+    target[validKey] = source[validKey];
+
+    return target;
+  }, {} as unknown as Output);
+}

packages/instantsearch.js/src/widgets/hits/__tests__/hits.test.tsx

@@ -80,8 +80,7 @@ describe('hits', () => {
       "matchLevel": "full"
     }
   },
-  "__position": 1,
-  "__hitIndex": 0
+  "__position": 1
 }
         </li>
         <li
@@ -110,8 +109,7 @@ describe('hits', () => {
       "matchLevel": "full"
     }
   },
-  "__position": 2,
-  "__hitIndex": 1
+  "__position": 2
 }
         </li>
       </ol>

packages/instantsearch.js/src/widgets/hits/defaultTemplates.ts

@@ -1,11 +1,12 @@
 import type { HitsComponentTemplates } from '../../components/Hits/Hits';
+import { omit } from '../../lib/utils';
 
 const defaultTemplates: HitsComponentTemplates = {
   empty() {
     return 'No results';
   },
   item(data) {
-    return JSON.stringify(data, null, 2);
+    return JSON.stringify(omit(data, ['__hitIndex']), null, 2);
   },
 };
 

packages/instantsearch.js/src/widgets/hits/hits.tsx

@@ -121,7 +121,7 @@ export type HitsTemplates = Partial<{
    */
   item: TemplateWithBindEvent<
     Hit & {
-      // @deprecated the index in the hits array, use __position instead, which is the absolute position
+      /** @deprecated the index in the hits array, use __position instead, which is the absolute position */
       __hitIndex: number;
     }
   >;

packages/instantsearch.js/src/widgets/infinite-hits/__tests__/infinite-hits.test.tsx

@@ -86,8 +86,7 @@ describe('infiniteHits', () => {
       "matchLevel": "full"
     }
   },
-  "__position": 1,
-  "__hitIndex": 0
+  "__position": 1
 }
         </li>
         <li
@@ -116,8 +115,7 @@ describe('infiniteHits', () => {
       "matchLevel": "full"
     }
   },
-  "__position": 2,
-  "__hitIndex": 1
+  "__position": 2
 }
         </li>
       </ol>

packages/instantsearch.js/src/widgets/infinite-hits/defaultTemplates.ts

@@ -1,3 +1,4 @@
+import { omit } from '../../lib/utils';
 import type { InfiniteHitsComponentTemplates } from '../../components/InfiniteHits/InfiniteHits';
 
 const defaultTemplates: InfiniteHitsComponentTemplates = {
@@ -11,7 +12,7 @@ const defaultTemplates: InfiniteHitsComponentTemplates = {
     return 'Show more results';
   },
   item(data) {
-    return JSON.stringify(data, null, 2);
+    return JSON.stringify(omit(data, ['__hitIndex']), null, 2);
   },
 };