instantsearch.js 4.85.2 → 4.86.0

package/es/connectors/sort-by/connectSortBy.d.ts

@@ -1,10 +1,19 @@
 import type { Connector, TransformItems, WidgetRenderState } from '../../types';
 /**
  * The **SortBy** connector provides the logic to build a custom widget that will display a
- * list of indices. With Algolia, this is most commonly used for changing ranking strategy. This allows
- * a user to change how the hits are being sorted.
+ * list of indices or sorting strategies. With Algolia, this is most commonly used for changing
+ * ranking strategy. This allows a user to change how the hits are being sorted.
+ *
+ * This connector supports two sorting modes:
+ * 1. **Index-based (traditional)**: Uses the `value` property to switch between different indices.
+ *    This is the standard behavior for non-composition setups.
+ *
+ * 2. **Strategy-based (composition mode)**: Uses the `strategy` property to apply sorting strategies
+ *    via the `sortBy` search parameter. This is only available when using Algolia Compositions.
+ *
+ * Items can mix both types in the same widget, allowing for flexible sorting options.
  */
-export type SortByItem = {
+export type SortByIndexItem = {
     /**
      * The name of the index to target.
      */
@@ -13,10 +22,30 @@ export type SortByItem = {
      * The label of the index to display.
      */
     label: string;
+    /**
+     * Ensures mutual exclusivity with strategy.
+     */
+    strategy?: never;
+};
+export type SortByStrategyItem = {
+    /**
+     * The name of the sorting strategy to use.
+     * Only available in composition mode.
+     */
+    strategy: string;
+    /**
+     * The label of the strategy to display.
+     */
+    label: string;
+    /**
+     * Ensures mutual exclusivity with value.
+     */
+    value?: never;
 };
+export type SortByItem = SortByIndexItem | SortByStrategyItem;
 export type SortByConnectorParams = {
     /**
-     * Array of objects defining the different indices to choose from.
+     * Array of objects defining the different indices or strategies to choose from.
      */
     items: SortByItem[];
     /**
@@ -26,19 +55,22 @@ export type SortByConnectorParams = {
 };
 export type SortByRenderState = {
     /**
-     * The initially selected index.
+     * The initially selected index or strategy.
      */
     initialIndex?: string;
     /**
-     * The currently selected index.
+     * The currently selected index or strategy.
      */
     currentRefinement: string;
     /**
-     * All the available indices
+     * All the available indices and strategies
      */
-    options: SortByItem[];
+    options: Array<{
+        value: string;
+        label: string;
+    }>;
     /**
-     * Switches indices and triggers a new search.
+     * Switches indices or strategies and triggers a new search.
      */
     refine: (value: string) => void;
     /**

package/es/connectors/sort-by/connectSortBy.js

@@ -12,10 +12,33 @@ var withUsage = createDocumentationMessageGenerator({
 
 /**
  * The **SortBy** connector provides the logic to build a custom widget that will display a
- * list of indices. With Algolia, this is most commonly used for changing ranking strategy. This allows
- * a user to change how the hits are being sorted.
+ * list of indices or sorting strategies. With Algolia, this is most commonly used for changing
+ * ranking strategy. This allows a user to change how the hits are being sorted.
+ *
+ * This connector supports two sorting modes:
+ * 1. **Index-based (traditional)**: Uses the `value` property to switch between different indices.
+ *    This is the standard behavior for non-composition setups.
+ *
+ * 2. **Strategy-based (composition mode)**: Uses the `strategy` property to apply sorting strategies
+ *    via the `sortBy` search parameter. This is only available when using Algolia Compositions.
+ *
+ * Items can mix both types in the same widget, allowing for flexible sorting options.
  */
 
+function isStrategyItem(item) {
+  return 'strategy' in item && item.strategy !== undefined;
+}
+function getItemValue(item) {
+  if (isStrategyItem(item)) {
+    return item.strategy;
+  }
+  return item.value;
+}
+function isValidStrategy(itemsLookup, value) {
+  if (!value) return false;
+  var item = itemsLookup[value];
+  return item !== undefined && isStrategyItem(item);
+}
 var connectSortBy = function connectSortBy(renderFn) {
   var unmountFn = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : noop;
   checkRendering(renderFn, withUsage());
@@ -30,14 +53,38 @@ var connectSortBy = function connectSortBy(renderFn) {
     if (!Array.isArray(items)) {
       throw new Error(withUsage('The `items` option expects an array of objects.'));
     }
+    var itemsLookup = {};
+    items.forEach(function (item, index) {
+      var hasValue = 'value' in item && item.value !== undefined;
+      var hasStrategy = 'strategy' in item && item.strategy !== undefined;
+
+      // Validate mutual exclusivity
+      if (hasValue && hasStrategy) {
+        throw new Error(withUsage("Item at index ".concat(index, " cannot have both \"value\" and \"strategy\" properties.")));
+      }
+      if (!hasValue && !hasStrategy) {
+        throw new Error(withUsage("Item at index ".concat(index, " must have either a \"value\" or \"strategy\" property.")));
+      }
+      var itemValue = getItemValue(item);
+      itemsLookup[itemValue] = item;
+    });
+    connectorState.itemsLookup = itemsLookup;
     return {
       $$type: 'ais.sortBy',
       init: function init(initOptions) {
         var instantSearchInstance = initOptions.instantSearchInstance;
+
+        // Check if strategies are used outside composition mode
+        var hasStrategyItems = items.some(function (item) {
+          return 'strategy' in item && item.strategy;
+        });
+        if (hasStrategyItems && !instantSearchInstance.compositionID) {
+          throw new Error(withUsage('Sorting strategies can only be used in composition mode. Please provide a "compositionID" to your InstantSearch instance.'));
+        }
         var widgetRenderState = this.getWidgetRenderState(initOptions);
         var currentIndex = widgetRenderState.currentRefinement;
         var isCurrentIndexInItems = find(items, function (item) {
-          return item.value === currentIndex;
+          return getItemValue(item) === currentIndex;
         });
         process.env.NODE_ENV === 'development' ? warning(isCurrentIndexInItems !== undefined, "The index named \"".concat(currentIndex, "\" is not listed in the `items` of `sortBy`.")) : void 0;
         renderFn(_objectSpread(_objectSpread({}, widgetRenderState), {}, {
@@ -53,7 +100,17 @@ var connectSortBy = function connectSortBy(renderFn) {
       dispose: function dispose(_ref2) {
         var state = _ref2.state;
         unmountFn();
-        return connectorState.initialIndex ? state.setIndex(connectorState.initialIndex) : state;
+
+        // Clear sortBy parameter if it was set
+        if (connectorState.isUsingComposition && state.sortBy) {
+          state = state.setQueryParameter('sortBy', undefined);
+        }
+
+        // Restore initial index if changed
+        if (connectorState.initialValue && state.index !== connectorState.initialValue) {
+          return state.setIndex(connectorState.initialValue);
+        }
+        return state;
       },
       getRenderState: function getRenderState(renderState, renderOptions) {
         return _objectSpread(_objectSpread({}, renderState), {}, {
@@ -64,22 +121,54 @@ var connectSortBy = function connectSortBy(renderFn) {
         var results = _ref3.results,
           helper = _ref3.helper,
           state = _ref3.state,
-          parent = _ref3.parent;
-        if (!connectorState.initialIndex && parent) {
-          connectorState.initialIndex = parent.getIndexName();
+          parent = _ref3.parent,
+          instantSearchInstance = _ref3.instantSearchInstance;
+        // Capture initial value (composition ID or main index)
+        if (!connectorState.initialValue && parent) {
+          connectorState.initialValue = parent.getIndexName();
         }
-        if (!connectorState.setIndex) {
-          connectorState.setIndex = function (indexName) {
-            helper.setIndex(indexName).search();
+
+        // Create refine function if not exists
+        if (!connectorState.refine) {
+          // Cache composition mode status for lifecycle methods that don't have access to instantSearchInstance
+          connectorState.isUsingComposition = Boolean(instantSearchInstance === null || instantSearchInstance === void 0 ? void 0 : instantSearchInstance.compositionID);
+          connectorState.refine = function (value) {
+            // O(1) lookup using the items lookup table
+            var item = connectorState.itemsLookup[value];
+            if (item && isStrategyItem(item)) {
+              // Strategy-based: set sortBy parameter for composition API
+              // The composition backend will interpret this and apply the sorting strategy
+              helper.setQueryParameter('sortBy', item.strategy).search();
+            } else {
+              // Index-based: clear any existing sortBy parameter and switch to the new index
+              // Clearing sortBy is critical when transitioning from strategy to index-based sorting
+              helper.setQueryParameter('sortBy', undefined).setIndex(value).search();
+            }
           };
         }
+
+        // Transform items first (on original structure)
+        var transformedItems = transformItems(items, {
+          results: results
+        });
+
+        // Normalize items: all get a 'value' property for the render state
+        var normalizedItems = transformedItems.map(function (item) {
+          return {
+            label: item.label,
+            value: getItemValue(item)
+          };
+        });
+
+        // Determine current refinement
+        // In composition mode, prefer sortBy parameter if it corresponds to a valid strategy item
+        // Otherwise use the index (for index-based items or when no valid strategy is active)
+        var currentRefinement = connectorState.isUsingComposition && isValidStrategy(connectorState.itemsLookup, state.sortBy) ? state.sortBy : state.index;
         var hasNoResults = results ? results.nbHits === 0 : true;
         return {
-          currentRefinement: state.index,
-          options: transformItems(items, {
-            results: results
-          }),
-          refine: connectorState.setIndex,
+          currentRefinement: currentRefinement,
+          options: normalizedItems,
+          refine: connectorState.refine,
           hasNoResults: hasNoResults,
           canRefine: !hasNoResults && items.length > 0,
           widgetParams: widgetParams
@@ -87,14 +176,25 @@ var connectSortBy = function connectSortBy(renderFn) {
       },
       getWidgetUiState: function getWidgetUiState(uiState, _ref4) {
         var searchParameters = _ref4.searchParameters;
-        var currentIndex = searchParameters.index;
+        // In composition mode with an active strategy, use sortBy parameter
+        // Otherwise use index-based behavior (traditional mode)
+        var currentValue = connectorState.isUsingComposition && isValidStrategy(connectorState.itemsLookup, searchParameters.sortBy) ? searchParameters.sortBy : searchParameters.index;
         return _objectSpread(_objectSpread({}, uiState), {}, {
-          sortBy: currentIndex !== connectorState.initialIndex ? currentIndex : undefined
+          sortBy: currentValue !== connectorState.initialValue ? currentValue : undefined
         });
       },
       getWidgetSearchParameters: function getWidgetSearchParameters(searchParameters, _ref5) {
         var uiState = _ref5.uiState;
-        return searchParameters.setQueryParameter('index', uiState.sortBy || connectorState.initialIndex || searchParameters.index);
+        var sortByValue = uiState.sortBy || connectorState.initialValue || searchParameters.index;
+        if (isValidStrategy(connectorState.itemsLookup, sortByValue)) {
+          var item = connectorState.itemsLookup[sortByValue];
+          // Strategy-based: set the sortBy parameter for composition API
+          // The index remains as the compositionID
+          return searchParameters.setQueryParameter('sortBy', item.strategy);
+        }
+
+        // Index-based: set the index parameter (traditional behavior)
+        return searchParameters.setQueryParameter('index', sortByValue);
       }
     };
   };

package/es/lib/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "4.85.2";
+declare const _default: "4.86.0";
 export default _default;

package/es/lib/version.js

@@ -1 +1 @@
-export default '4.85.2';
+export default '4.86.0';

package/es/widgets/autocomplete/autocomplete.d.ts

@@ -58,6 +58,14 @@ type AutocompleteWidgetParams<TItem extends BaseHit> = {
          */
         storageKey?: string;
         templates?: Partial<{
+            /**
+             * Template to use for the header, before the list of items.
+             */
+            header: Template<{
+                items: Array<{
+                    query: string;
+                }>;
+            }>;
             /**
              * Template to use for each result. This template will receive an object containing a single record.
              */
@@ -69,6 +77,7 @@ type AutocompleteWidgetParams<TItem extends BaseHit> = {
                 onRemoveRecentSearch: () => void;
             }>;
         }>;
+        cssClasses?: Partial<AutocompleteIndexClassNames>;
     };
     /**
      * Search parameters to apply to the autocomplete indices.