@findlane/browser 0.19.0 → 0.21.0

package/dist/index.d.ts

@@ -54,6 +54,11 @@ export type SearchRequest = {
     /** Contexts the page sends, which the index's rules may fire on, such as "category-page" or
      * "black-friday": a name or up to 10, each 1 to 64 letters, digits, `_`, `:` or `-` (0.19.0). */
     context?: string | string[];
+    /** Records matching these filters come first, after the index's rank first, in searches by relevance: filters as
+     * `filters` takes them, or a list of up to 10, each counting once, so records matching more come first (0.20.0). */
+    boost?: SearchRequest["filters"] | SearchRequest["filters"][];
+    /** Records matching these come last, the same way (0.20.0). */
+    bury?: SearchRequest["filters"] | SearchRequest["filters"][];
 };
 /** A point in degrees: lat from -90 to 90, lng from -180 to 180. */
 export type GeoPoint = {
@@ -122,6 +127,11 @@ export type SearchResponse<T> = {
     appliedRules?: AppliedRule[];
     /** When a rule replaced words: the query that was searched. */
     rewrittenQuery?: string;
+    /** Banners of the rules that fired, in their order (0.20.0): show each at its `position` among the hits (from
+     * 1; the top when left out), linking to `link`. */
+    banners?: Banner[];
+    /** A page a rule sends this search to, such as "/pages/returns" (0.20.0): go there instead of showing results. */
+    redirect?: string;
     /** With the index's related results on (0.17.0): when the query's words found nothing (`hits` empty, `total`
      * 0), the products closest to it in meaning, best first, with their similarity as `score`. Show them under
      * a heading of their own, such as "No exact matches. Related products". */
@@ -135,6 +145,14 @@ export type AppliedRule = {
     id: string;
     userData?: unknown;
 };
+/** A rule's banner: an image, where it links, its text, its place among the hits from 1, and the rule's ID. */
+export type Banner = {
+    image: string;
+    link?: string;
+    title?: string;
+    position?: number;
+    rule: string;
+};
 /** A corrected query. `applied`: the results are already for `q` (a search's "Showing results for");
  * otherwise searching `q` finds results that the query didn't ("Did you mean"). `changes` lists each
  * changed part of the query as typed. */
@@ -277,6 +295,12 @@ export type BrowserEvents = {
         position?: number;
         kind?: "typed" | "popular" | "recent";
     }): void;
+    /** A rule's banner was clicked: its rule (each banner in a response says which), the search's query, and
+     * its place. The Merchandising page shows each banner's clicks beside how often it was shown. */
+    bannerClick(rule: string, details?: {
+        query?: string;
+        position?: number;
+    }): void;
     addToCart(items: EventItem[], options?: {
         currency?: string;
     }): void;

package/dist/index.js

@@ -137,6 +137,7 @@ function eventSender(url, fetcher, mode, ids) {
         },
         click: (objectID, details) => add({ type: "click", objectID, ...details }),
         suggestion: (query, details) => add({ type: "suggestion", query, ...details }),
+        bannerClick: (rule, details) => add({ type: "bannerClick", rule, ...details }),
         addToCart: (items, options) => add({ type: "addToCart", items, ...options }),
         purchase: (order) => add({ type: "purchase", ...order }),
         consent(granted) {

package/dist/react/components.d.ts

@@ -1,5 +1,5 @@
 import { type MouseEvent, type ReactNode } from "react";
-import { type DidYouMean as Correction } from "../index.js";
+import { type Banner, type DidYouMean as Correction } from "../index.js";
 import { type Refinement } from "./search-provider.js";
 import type { Hit } from "./state.js";
 import { useAutocomplete, type AutocompleteOptions } from "./use-autocomplete.js";
@@ -54,6 +54,9 @@ export declare function SearchInput({ placeholder, label, className, autoFocus }
 export type HitsProps<T> = {
     /** A hit's content; DefaultHit shows an image and a title. */
     render?: (hit: Hit<T>, index: number) => ReactNode;
+    /** A rule's banner, shown at its place among the hits; DefaultBanner shows its image, linked, with its
+     * title (0.20.0). */
+    renderBanner?: (banner: Banner) => ReactNode;
     /** Shown when nothing matches (default "No results for “…”"). */
     empty?: (query: string) => ReactNode;
     /** The heading over related results, shown when nothing matched but the index's related results found
@@ -65,8 +68,13 @@ export type HitsProps<T> = {
 };
 /** Whether a click was on a link inside the element that handled it, such as a hit's link. */
 export declare function onLink(event: MouseEvent<HTMLElement>): boolean;
-/** The results. Following a link in a hit sends a click event, with its place and the query. */
-export declare function Hits<T = Record<string, unknown>>({ render, empty, relatedTitle, loading, className }: HitsProps<T>): import("react").JSX.Element;
+/** A rule's banner: its image, linked when it has a link, with its title. */
+export declare function DefaultBanner({ banner }: {
+    banner: Banner;
+}): import("react").JSX.Element;
+/** The results. Following a link in a hit sends a click event, with its place and the query. Rules'
+ * banners show at their places among the first page's hits, and following a banner's link sends a banner click. */
+export declare function Hits<T = Record<string, unknown>>({ render, renderBanner, empty, relatedTitle, loading, className }: HitsProps<T>): import("react").JSX.Element;
 export type RefinementListProps = {
     field: string;
     /** The heading (default the field). */

package/dist/react/components.js

@@ -73,9 +73,15 @@ export function onLink(event) {
     const link = event.target.closest?.("a[href]");
     return Boolean(link && event.currentTarget.contains(link));
 }
-/** The results. Following a link in a hit sends a click event, with its place and the query. */
-export function Hits({ render, empty, relatedTitle, loading = null, className }) {
-    const { hits, related, isLoaded, isPending, error, click } = useHits();
+/** A rule's banner: its image, linked when it has a link, with its title. */
+export function DefaultBanner({ banner }) {
+    const content = (_jsxs(_Fragment, { children: [_jsx("img", { src: banner.image, alt: banner.title ?? "", loading: "lazy" }), banner.title && _jsx("span", { children: banner.title })] }));
+    return banner.link ? _jsx("a", { href: banner.link, children: content }) : content;
+}
+/** The results. Following a link in a hit sends a click event, with its place and the query. Rules'
+ * banners show at their places among the first page's hits, and following a banner's link sends a banner click. */
+export function Hits({ render, renderBanner, empty, relatedTitle, loading = null, className }) {
+    const { hits, related, isLoaded, isPending, error, click, bannerClick, response, request } = useHits();
     const { query } = useSearchBox();
     if (error && !isLoaded)
         return _jsx("p", { "data-findlane-note": "", children: messageFor(error) });
@@ -85,12 +91,25 @@ export function Hits({ render, empty, relatedTitle, loading = null, className })
         return _jsx("p", { "data-findlane-empty": "", children: empty ? empty(query) : query ? _jsxs(_Fragment, { children: ["No results for \u201C", query, "\u201D"] }) : "No results" });
     // Nothing matched, but related results found products close in meaning: those, under their own heading.
     const shown = hits.length ? hits : related;
+    // Banners go before the hit at their place, on the first page; past the last hit, after it.
+    const banners = hits.length && !request?.offset ? response?.banners ?? [] : [];
+    const bannerAt = (place) => banners.filter((banner) => Math.min(Math.max(banner.position ?? 1, 1), shown.length) === place);
+    // Following a banner's link sends a banner click, as a hit's sends a click.
+    const bannerItems = (place) => bannerAt(place).map((banner, at) => {
+        const clicked = (event) => { if (!event.defaultPrevented && onLink(event))
+            bannerClick(banner); };
+        return (_jsx("li", { "data-findlane-banner": "", onClick: clicked, onAuxClick: (event) => { if (event.button === 1)
+                clicked(event); }, children: renderBanner ? renderBanner(banner) : _jsx(DefaultBanner, { banner: banner }) }, `banner-${banner.rule}-${at}`));
+    });
     const list = (_jsx("ol", { className: className, "data-findlane-hits": "", "data-findlane-related": !hits.length || undefined, "data-pending": isPending || undefined, children: shown.map((hit, index) => {
             // A click, and a middle click that opens the link in a new tab.
             const clicked = (event) => { if (!event.defaultPrevented && onLink(event))
                 click(hit); };
-            return (_jsx("li", { onClick: clicked, onAuxClick: (event) => { if (event.button === 1)
-                    clicked(event); }, children: render ? render(hit, index) : _jsx(DefaultHit, { hit: hit }) }, hit.id));
+            return [
+                ...bannerItems(index + 1),
+                _jsx("li", { onClick: clicked, onAuxClick: (event) => { if (event.button === 1)
+                        clicked(event); }, children: render ? render(hit, index) : _jsx(DefaultHit, { hit: hit }) }, hit.id),
+            ];
         }) }));
     if (hits.length)
         return list;

package/dist/react/index.d.ts

@@ -5,7 +5,7 @@ export { useRecommendations, type UseRecommendationsOptions, type UseRecommendat
 export { Recommendations, type RecommendationsProps } from "./recommendations.js";
 export { ProductView, useProductView } from "./product-view.js";
 export { SearchProvider, useCurrentRefinements, useDidYouMean, useGeoSearch, useHits, useLoadMore, usePagination, useRange, useRefinementList, useSearchBox, useSearchState, useSortBy, useToggle, type Range, type Refinement, type SearchProviderProps, } from "./search-provider.js";
-export { CurrentRefinements, DefaultHit, DidYouMean, Hits, LoadMore, RefinementList, SearchBox, SearchInput, SortSelect, Stats, type HitsProps, type RefinementListProps, type SearchBoxProps, type SuggestionLabels, } from "./components.js";
+export { CurrentRefinements, DefaultBanner, DefaultHit, DidYouMean, Hits, LoadMore, RefinementList, SearchBox, SearchInput, SortSelect, Stats, type HitsProps, type RefinementListProps, type SearchBoxProps, type SuggestionLabels, } from "./components.js";
 export { SearchDialog, type SearchDialogProps } from "./dialog.js";
 export { Highlight, Snippet, excerpt, highlightParts, type HighlightProps } from "./highlight.js";
 export { messageFor } from "./messages.js";

package/dist/react/index.js

@@ -7,7 +7,7 @@ export { useRecommendations } from "./use-recommendations.js";
 export { Recommendations } from "./recommendations.js";
 export { ProductView, useProductView } from "./product-view.js";
 export { SearchProvider, useCurrentRefinements, useDidYouMean, useGeoSearch, useHits, useLoadMore, usePagination, useRange, useRefinementList, useSearchBox, useSearchState, useSortBy, useToggle, } from "./search-provider.js";
-export { CurrentRefinements, DefaultHit, DidYouMean, Hits, LoadMore, RefinementList, SearchBox, SearchInput, SortSelect, Stats, } from "./components.js";
+export { CurrentRefinements, DefaultBanner, DefaultHit, DidYouMean, Hits, LoadMore, RefinementList, SearchBox, SearchInput, SortSelect, Stats, } from "./components.js";
 export { SearchDialog } from "./dialog.js";
 export { Highlight, Snippet, excerpt, highlightParts } from "./highlight.js";
 export { messageFor } from "./messages.js";

package/dist/react/search-provider.d.ts

@@ -54,6 +54,11 @@ export declare function useHits<T = Record<string, unknown>>(): {
     click: (hit: {
         id: string;
     }) => void;
+    /** Sends a click on a rule's banner. Hits does it for links in a banner; call it from your own banner. */
+    bannerClick: (banner: {
+        rule: string;
+        position?: number;
+    }) => void;
 };
 /** Did you mean, with the index's didYouMean setting: the query the results are for when typo tolerance
  * corrected some words (`applied`, "Showing results for"), or, when nothing matched, a query that

package/dist/react/search-provider.js

@@ -99,6 +99,8 @@ export function useHits() {
         /** Sends a click event for a hit, with its place and the query, for click-through in Analytics.
          * Hits does it for links in a hit; call it from a hit rendered without a link. */
         click: (hit) => store.click(hit.id),
+        /** Sends a click on a rule's banner. Hits does it for links in a banner; call it from your own banner. */
+        bannerClick: (banner) => store.bannerClick(banner),
     };
 }
 /** Did you mean, with the index's didYouMean setting: the query the results are for when typo tolerance

package/dist/react/store.d.ts

@@ -65,6 +65,11 @@ export declare class SearchStore<T = unknown> {
     /** Sends a click on a result: its place in the results, from 1, and the query they're for. A related
      * result's click says so (list "related"), with its place among them. */
     click(objectID: string): void;
+    /** Sends a click on a rule's banner, with the query it showed for. */
+    bannerClick(banner: {
+        rule: string;
+        position?: number;
+    }): void;
     /** Searches unless the results already answer the current state; with a state, such as the
      * URL's, adopts it first. */
     start(state?: SearchState): void;

package/dist/react/store.js

@@ -77,6 +77,11 @@ export class SearchStore {
             ...(index >= 0 ? { position: (results.request.offset ?? 0) + index + 1 } : {}),
             ...(related >= 0 ? { position: related + 1, list: "related" } : {}) });
     }
+    /** Sends a click on a rule's banner, with the query it showed for. */
+    bannerClick(banner) {
+        this.client.events.bannerClick(banner.rule, { query: this.snapshot.results?.request.q ?? "",
+            ...(banner.position ? { position: banner.position } : {}) });
+    }
     /** Searches unless the results already answer the current state; with a state, such as the
      * URL's, adopts it first. */
     start(state) {

package/dist/react/use-autocomplete.js

@@ -185,6 +185,13 @@ export function useAutocomplete(options = {}) {
                 event.preventDefault();
                 choose(item.index);
             }
+            else if (search.data?.redirect && !search.isPending) {
+                // A rule sends this search to a page, such as "returns" to the returns page (0.20.0).
+                event.preventDefault();
+                remember(query);
+                close();
+                window.location.assign(search.data.redirect);
+            }
             else {
                 remember(query);
                 if (onSubmit) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@findlane/browser",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Findlane browser SDK: fast, typo-tolerant public search from the browser with an index's public ID, plus React hooks and components.",
   "keywords": ["findlane", "search", "full-text search", "typo tolerance", "instant search", "ecommerce search", "browser", "react", "autocomplete"],
   "license": "MIT",