algolia · shortcuts · Feb 5, 2021 · Feb 4, 2021 · Feb 4, 2021 · Feb 4, 2021
diff --git a/examples/js/app.tsx b/examples/js/app.tsx
@@ -62,6 +62,7 @@ autocomplete({
 
     return [
       {
+        sourceId: 'products',
         getItems() {
           return getAlgoliaHits<Product>({
             searchClient,

diff --git a/examples/js/shortcutsPlugin.tsx b/examples/js/shortcutsPlugin.tsx
@@ -14,6 +14,7 @@ export const shortcutsPlugin: AutocompletePlugin<DarkModeItem> = {
 
     return [
       {
+        sourceId: 'shortcutsPlugin',
         getItems() {
           return [
             {

diff --git a/packages/autocomplete-core/src/__tests__/concurrency.test.ts b/packages/autocomplete-core/src/__tests__/concurrency.test.ts
@@ -1,6 +1,6 @@
 import userEvent from '@testing-library/user-event';
 
-import { defer } from '../../../../test/utils';
+import { createSource, defer } from '../../../../test/utils';
 import { createAutocomplete } from '../createAutocomplete';
 
 describe.skip('concurrency', () => {
@@ -14,11 +14,11 @@ describe.skip('concurrency', () => {
 
       return defer(() => {
         return [
-          {
+          createSource({
             getItems() {
               return [{ label: query }];
             },
-          },
+          }),
         ];
       }, delays[deferCount]);
     };

diff --git a/packages/autocomplete-core/src/__tests__/getInputProps.test.ts b/packages/autocomplete-core/src/__tests__/getInputProps.test.ts
@@ -1049,6 +1049,7 @@ describe('getInputProps', () => {
                     { label: '2', url: '#2' },
                   ],
                   source: {
+                    sourceId: expect.any(String),
                     getItemInputValue: expect.any(Function),
                     getItemUrl: expect.any(Function),
                     getItems: expect.any(Function),

diff --git a/packages/autocomplete-core/src/__tests__/getSources.test.ts b/packages/autocomplete-core/src/__tests__/getSources.test.ts
@@ -47,6 +47,7 @@ describe('getSources', () => {
       getSources: () => {
         return [
           {
+            sourceId: 'testSource',
             getItems() {
               return [];
             },
@@ -78,6 +79,7 @@ describe('getSources', () => {
                 templates: expect.objectContaining({
                   item: expect.any(Function),
                 }),
+                sourceId: expect.any(String),
               },
             }),
           ]),
@@ -92,6 +94,7 @@ describe('getSources', () => {
       getSources: () => {
         return [
           {
+            sourceId: 'pluginSource',
             getItems() {
               return [];
             },
@@ -107,6 +110,7 @@ describe('getSources', () => {
       getSources: () => {
         return [
           {
+            sourceId: 'testSource',
             getItems() {
               return [];
             },

diff --git a/packages/autocomplete-core/src/__tests__/stallThreshold.test.ts b/packages/autocomplete-core/src/__tests__/stallThreshold.test.ts
@@ -1,6 +1,6 @@
 import userEvent from '@testing-library/user-event';
 
-import { defer } from '../../../../test/utils';
+import { createSource, defer } from '../../../../test/utils';
 import { createAutocomplete } from '../createAutocomplete';
 
 describe('stallThreshold', () => {
@@ -11,11 +11,11 @@ describe('stallThreshold', () => {
       getSources() {
         return defer(() => {
           return [
-            {
+            createSource({
               getItems() {
                 return [{ label: '1' }, { label: 2 }];
               },
-            },
+            }),
           ];
         }, 500);
       },
@@ -59,11 +59,11 @@ describe('stallThreshold', () => {
       getSources() {
         return defer(() => {
           return [
-            {
+            createSource({
               getItems() {
                 return [{ label: '1' }, { label: 2 }];
               },
-            },
+            }),
           ];
         }, 500);
       },

diff --git a/packages/autocomplete-core/src/types/AutocompleteSource.ts b/packages/autocomplete-core/src/types/AutocompleteSource.ts
@@ -58,6 +58,10 @@ export interface AutocompleteSource<TItem extends BaseItem> {
    * You can trigger different behaviors based on the event `type`.
    */
   onActive?(params: OnHighlightParams<TItem>): void;
+  /**
+   * Identifier for the source.
+   */
+  sourceId: string;
 }
 
 export type InternalAutocompleteSource<TItem extends BaseItem> = {

diff --git a/packages/autocomplete-core/src/utils/__tests__/getNormalizedSources.test.ts b/packages/autocomplete-core/src/utils/__tests__/getNormalizedSources.test.ts
@@ -7,7 +7,7 @@ import { getNormalizedSources } from '../getNormalizedSources';
 
 describe('getNormalizedSources', () => {
   test('returns a promise of sources', async () => {
-    const getSources = () => [{ getItems: () => [] }];
+    const getSources = () => [{ sourceId: 'testSource', getItems: () => [] }];
     const params = {
       query: '',
       state: createState({
@@ -23,12 +23,17 @@ describe('getNormalizedSources', () => {
         getItems: expect.any(Function),
         onActive: expect.any(Function),
         onSelect: expect.any(Function),
+        sourceId: 'testSource',
       },
     ]);
   });
 
   test('filters out falsy sources', async () => {
-    const getSources = () => [{ getItems: () => [] }, false, undefined];
+    const getSources = () => [
+      { sourceId: 'testSource', getItems: () => [] },
+      false,
+      undefined,
+    ];
     const params = {
       query: '',
       state: createState({
@@ -44,6 +49,7 @@ describe('getNormalizedSources', () => {
         getItems: expect.any(Function),
         onActive: expect.any(Function),
         onSelect: expect.any(Function),
+        sourceId: 'testSource',
       },
     ]);
   });
@@ -64,8 +70,55 @@ describe('getNormalizedSources', () => {
     );
   });
 
+  test('with missing `sourceId` triggers invariant', async () => {
+    const getSources = () => [
+      {
+        getItems() {
+          return [];
+        },
+        templates: {
+          item() {},
+        },
+      },
+    ];
+    const params = {
+      query: '',
+      state: createState({}),
+      ...createScopeApi(),
+    };
+
+    // @ts-expect-error
+    await expect(getNormalizedSources(getSources, params)).rejects.toEqual(
+      new Error('[Autocomplete] A source must provide a `sourceId` string.')
+    );
+  });
+
+  test('with wrong `sourceId` type triggers invariant', async () => {
+    const getSources = () => [
+      {
+        sourceId: ['testSource'],
+        getItems() {
+          return [];
+        },
+        templates: {
+          item() {},
+        },
+      },
+    ];
+    const params = {
+      query: '',
+      state: createState({}),
+      ...createScopeApi(),
+    };
+
+    // @ts-expect-error
+    await expect(getNormalizedSources(getSources, params)).rejects.toEqual(
+      new Error('[Autocomplete] A source must provide a `sourceId` string.')
+    );
+  });
+
   test('provides a default implementation for getItemInputValue which returns the query', async () => {
-    const getSources = () => [{ getItems: () => [] }];
+    const getSources = () => [{ sourceId: 'testSource', getItems: () => [] }];
     const params = {
       query: '',
       state: createState({
@@ -82,7 +135,7 @@ describe('getNormalizedSources', () => {
   });
 
   test('provides a default implementation for getItemUrl', async () => {
-    const getSources = () => [{ getItems: () => [] }];
+    const getSources = () => [{ sourceId: 'testSource', getItems: () => [] }];
     const params = {
       query: '',
       state: createState({}),
@@ -97,7 +150,7 @@ describe('getNormalizedSources', () => {
   });
 
   test('provides a default implementation for onSelect', async () => {
-    const getSources = () => [{ getItems: () => [] }];
+    const getSources = () => [{ sourceId: 'testSource', getItems: () => [] }];
     const params = {
       query: '',
       state: createState({}),
@@ -119,7 +172,7 @@ describe('getNormalizedSources', () => {
   });
 
   test('provides a default implementation for onActive', async () => {
-    const getSources = () => [{ getItems: () => [] }];
+    const getSources = () => [{ sourceId: 'testSource', getItems: () => [] }];
     const params = {
       query: '',
       state: createState({}),

diff --git a/packages/autocomplete-core/src/utils/getNormalizedSources.ts b/packages/autocomplete-core/src/utils/getNormalizedSources.ts
@@ -32,6 +32,11 @@ export function getNormalizedSources<TItem extends BaseItem>(
           Boolean(maybeSource)
         )
         .map((source) => {
+          invariant(
+            typeof source.sourceId === 'string',
+            'A source must provide a `sourceId` string.'
+          );
+
           const normalizedSource: InternalAutocompleteSource<TItem> = {
             getItemInputValue({ state }) {
               return state.query;

diff --git a/packages/autocomplete-js/src/__tests__/autocomplete.test.ts b/packages/autocomplete-js/src/__tests__/autocomplete.test.ts
@@ -11,6 +11,7 @@ describe('autocomplete-js', () => {
       getSources() {
         return [
           {
+            sourceId: 'testSource',
             getItems() {
               return [
                 { label: 'Item 1' },
@@ -167,6 +168,7 @@ describe('autocomplete-js', () => {
       getSources() {
         return [
           {
+            sourceId: 'testSource',
             getItems() {
               return [];
             },
@@ -206,6 +208,7 @@ describe('autocomplete-js', () => {
       getSources() {
         return [
           {
+            sourceId: 'testSource',
             getItems() {
               return [];
             },
@@ -245,6 +248,7 @@ describe('autocomplete-js', () => {
       getSources() {
         return [
           {
+            sourceId: 'testSource',
             getItems() {
               return [];
             },
@@ -290,6 +294,7 @@ describe('autocomplete-js', () => {
       getSources() {
         return [
           {
+            sourceId: 'testSource',
             getItems() {
               return [];
             },
@@ -338,6 +343,7 @@ describe('autocomplete-js', () => {
       getSources() {
         return [
           {
+            sourceId: 'testSource',
             getItems() {
               return [];
             },
@@ -383,6 +389,7 @@ describe('autocomplete-js', () => {
       getSources() {
         return [
           {
+            sourceId: 'testSource',
             getItems() {
               return [
                 { label: 'Item 1' },
@@ -418,6 +425,7 @@ describe('autocomplete-js', () => {
       getSources() {
         return [
           {
+            sourceId: 'testSource',
             getItems() {
               return [
                 { label: 'Item 1' },
@@ -449,6 +457,7 @@ describe('autocomplete-js', () => {
       getSources() {
         return [
           {
+            sourceId: 'testSource',
             getItems() {
               return [
                 { label: 'Item 1' },
@@ -482,6 +491,7 @@ describe('autocomplete-js', () => {
       getSources() {
         return [
           {
+            sourceId: 'testSource',
             getItems() {
               return [
                 { label: 'Item 1' },
@@ -512,6 +522,7 @@ describe('autocomplete-js', () => {
       getSources() {
         return [
           {
+            sourceId: 'testSource',
             getItems() {
               return [
                 { label: 'Item 1' },

diff --git a/packages/autocomplete-js/src/__tests__/positioning.test.ts b/packages/autocomplete-js/src/__tests__/positioning.test.ts
@@ -35,6 +35,7 @@ const querySuggestionsFixturePlugin: AutocompletePlugin<
   getSources() {
     return [
       {
+        sourceId: 'testSource',
         getItems() {
           return querySuggestions;
         },

diff --git a/packages/autocomplete-js/src/render.tsx b/packages/autocomplete-js/src/render.tsx
@@ -92,7 +92,11 @@ export function renderPanel<TItem extends BaseItem>(
   dom.panel.classList.toggle('aa-Panel--stalled', state.status === 'stalled');
 
   const sections = state.collections.map(({ source, items }, sourceIndex) => (
-    <section key={sourceIndex} className={classNames.source}>
+    <section
+      key={sourceIndex}
+      className={classNames.source}
+      data-autocomplete-source-id={source.sourceId}
+    >
       {source.templates.header && (
         <div className={classNames.sourceHeader}>
           {source.templates.header({

diff --git a/packages/autocomplete-js/src/types/AutocompleteSource.ts b/packages/autocomplete-js/src/types/AutocompleteSource.ts
@@ -57,6 +57,7 @@ export type AutocompleteSource<TItem extends BaseItem> = WithTemplates<
   AutocompleteCoreSource<TItem>,
   TItem
 >;
+
 export type InternalAutocompleteSource<TItem extends BaseItem> = WithTemplates<
   InternalAutocompleteCoreSource<TItem>,
   TItem

diff --git a/packages/autocomplete-plugin-query-suggestions/src/createQuerySuggestionsPlugin.ts b/packages/autocomplete-plugin-query-suggestions/src/createQuerySuggestionsPlugin.ts
@@ -36,6 +36,7 @@ export function createQuerySuggestionsPlugin<
     getSources({ query, setQuery, refresh, state }) {
       return [
         {
+          sourceId: 'querySuggestionsPlugin',
           getItemInputValue({ item }) {
             return item.query;
           },

diff --git a/packages/autocomplete-plugin-recent-searches/src/createRecentSearchesPlugin.ts b/packages/autocomplete-plugin-recent-searches/src/createRecentSearchesPlugin.ts
@@ -68,6 +68,7 @@ export function createRecentSearchesPlugin<TItem extends RecentSearchesItem>({
 
         return [
           {
+            sourceId: 'recentSearchesPlugin',
             getItemInputValue({ item }) {
               return item.query;
             },

diff --git a/packages/website/docs/autocomplete-js.md b/packages/website/docs/autocomplete-js.md
@@ -29,6 +29,7 @@ const autocompleteSearch = autocomplete({
   getSources() {
     return [
       {
+        sourceId: 'querySuggestionsSources',
         getItemInputValue: ({ item }) => item.query,
         getItems({ query }) {
           return getAlgoliaHits({