@magicx-eng/ai-autocomplete-vanilla 0.43.0 → 0.44.0

package/README.md

@@ -311,6 +311,31 @@ ac.subscribe((state) => {
   catalog. The strip clears on such a response rather than keeping an older
   query's items.
 
+#### Change product cards before display
+
+- `mapProducts(products, items)` synchronously returns the cards to show.
+- The SDK calls it once per response with its default cards and their matched items in the same order.
+- The returned array becomes the product state and the displayed strip.
+- A thrown error or a non-array result keeps the default cards. A thrown error warns once per instance.
+- `refreshProducts()` maps the current items again without a request. Call it when your own data arrives.
+- Both APIs leave a custom `products` integration unchanged.
+
+```ts
+const autocomplete = new AIAutocomplete(container, {
+  mapProducts: (products, items) =>
+    products.map((product, index) => ({
+      ...product,
+      price: shopperPrices[items[index].source_id] ?? "",
+    })),
+});
+
+// After updating shopperPrices:
+autocomplete.refreshProducts();
+```
+
+- `update({ mapProducts })` immediately maps the current items with the new mapper.
+- Price changes add, update, or remove price text on the same cards. Selection reports the updated product.
+
 #### Your own product search (`products`)
 
 To source the cards from your own search instead — a platform with its own

package/dist/index.d.mts

@@ -1070,6 +1070,13 @@ interface CoreOptions {
      * not rendered.
      */
     products?: ProductsConfig;
+    /**
+     * Runs synchronously with the SDK's cards and their response items in the same order.
+     * The product strip shows the returned array.
+     * Does not apply to a custom products integration.
+     * A throw or a result that is not an array keeps the SDK's cards.
+     */
+    mapProducts?: (products: Product[], items: MatchedItem[]) => Product[];
     /** Called when the user submits (Enter, or the submit button in Tier 1). */
     onSubmit?: (result: AutocompleteResult) => void;
     /**
@@ -1373,6 +1380,12 @@ declare class AIAutocomplete {
      * `on()` once each; their unsubscribe handles are not exposed.
      */
     on<E extends keyof AIAutocompleteEvents>(event: E, callback: (...args: AIAutocompleteEvents[E]) => void): () => void;
+    /**
+     * Runs mapProducts synchronously on the shown items again without a request.
+     * Keeps the same cards while updating their content.
+     * Does nothing without mapProducts or with a custom products integration.
+     */
+    refreshProducts(): void;
     update(opts: CoreUpdateOptions): void;
     selectOption(option: SuggestionOption): void;
     private applyOption;

package/dist/index.d.ts

@@ -1070,6 +1070,13 @@ interface CoreOptions {
      * not rendered.
      */
     products?: ProductsConfig;
+    /**
+     * Runs synchronously with the SDK's cards and their response items in the same order.
+     * The product strip shows the returned array.
+     * Does not apply to a custom products integration.
+     * A throw or a result that is not an array keeps the SDK's cards.
+     */
+    mapProducts?: (products: Product[], items: MatchedItem[]) => Product[];
     /** Called when the user submits (Enter, or the submit button in Tier 1). */
     onSubmit?: (result: AutocompleteResult) => void;
     /**
@@ -1373,6 +1380,12 @@ declare class AIAutocomplete {
      * `on()` once each; their unsubscribe handles are not exposed.
      */
     on<E extends keyof AIAutocompleteEvents>(event: E, callback: (...args: AIAutocompleteEvents[E]) => void): () => void;
+    /**
+     * Runs mapProducts synchronously on the shown items again without a request.
+     * Keeps the same cards while updating their content.
+     * Does nothing without mapProducts or with a custom products integration.
+     */
+    refreshProducts(): void;
     update(opts: CoreUpdateOptions): void;
     selectOption(option: SuggestionOption): void;
     private applyOption;