@findlane/browser 0.20.0 → 0.22.0

package/dist/index.d.ts

@@ -59,6 +59,18 @@ export type SearchRequest = {
     boost?: SearchRequest["filters"] | SearchRequest["filters"][];
     /** Records matching these come last, the same way (0.20.0). */
     bury?: SearchRequest["filters"] | SearchRequest["filters"][];
+    /** The index's subindexes to search too, such as a store's categories and pages beside its products, by
+     * name: each with its own search, which takes this one's `q` and `highlight` unless it says, and 5 results
+     * unless it says, or `true` for that. Up to 5. Their results come back in `subindexes`; the search and its
+     * subindexes count as one search (0.22.0). */
+    subindexes?: Record<string, SubindexSearch | true>;
+};
+/** A subindex's own search, in a search that asks for it. */
+export type SubindexSearch = Omit<SearchRequest, "subindexes">;
+/** A subindex whose search failed, such as one the index doesn't have (404). */
+export type SubindexError = {
+    error: string;
+    status: number;
 };
 /** A point in degrees: lat from -90 to 90, lng from -180 to 180. */
 export type GeoPoint = {
@@ -139,7 +151,19 @@ export type SearchResponse<T> = {
         hits: SearchHit<T>[];
         total: number;
     };
+    /** With `subindexes`: each subindex's results by name, or its error (0.22.0). */
+    subindexes?: Record<string, SearchResponse<Record<string, unknown>> | SubindexError>;
+};
+/** One search of a multi-index search (multiSearch): its index's public ID, the client's own when left out. */
+export type MultiSearchQuery = SearchRequest & {
+    index?: string;
 };
+/** One search's answer in a multi-index search: its results, or its error and status. */
+export type MultiSearchResult<T> = (SearchResponse<T> & {
+    index: string;
+}) | (SubindexError & {
+    index: string;
+});
 /** A query rule a search fired, with its `userData`, if it has any. */
 export type AppliedRule = {
     id: string;
@@ -295,6 +319,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;
@@ -338,6 +368,7 @@ export type BrowserClientOptions = {
 export declare class SearchBrowserClient {
     private readonly url;
     private readonly origin;
+    private readonly publicId;
     private readonly fetcher;
     /** Views, clicks, add-to-carts and orders, for the index's Events page and Bought together. */
     readonly events: BrowserEvents;
@@ -353,6 +384,13 @@ export declare class SearchBrowserClient {
     search<T = Record<string, unknown>>(request: SearchRequest, options?: {
         signal?: AbortSignal;
     }): Promise<SearchResponse<T>>;
+    /** Several indexes searched in one request, such as products and a blog (0.22.0): up to 10 searches, each
+     * naming its index's public ID (this client's when left out), whose allowed sites must include the page's.
+     * Each counts as a search of its own; one that asks for its index's subindexes counts once with them. The
+     * answers come in the order asked, each its results or its error; it throws only when every search failed. */
+    multiSearch<T = Record<string, unknown>>(queries: MultiSearchQuery[], options?: {
+        signal?: AbortSignal;
+    }): Promise<MultiSearchResult<T>[]>;
     /** Did you mean: for a search that found nothing, a query that finds something, or null. Takes the same
      * request (its q and filters matter). Needs the index's `didYouMean` setting; not counted as a search.
      * Ask once the shopper stops typing, not for every keystroke. */

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) {
@@ -161,6 +162,7 @@ const warmed = new Set();
 export class SearchBrowserClient {
     url;
     origin;
+    publicId;
     fetcher;
     /** Views, clicks, add-to-carts and orders, for the index's Events page and Bought together. */
     events;
@@ -170,6 +172,7 @@ export class SearchBrowserClient {
     constructor(options) {
         if (!/^pub_[a-f0-9]{32}$/.test(options.publicId))
             throw new Error("A valid public index ID (pub_…) is required");
+        this.publicId = options.publicId;
         this.url = `${(options.baseUrl ?? defaultBaseUrl).replace(/\/$/, "")}/api/public/indexes/${options.publicId}`;
         this.origin = new URL(this.url).origin;
         this.fetcher = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
@@ -215,6 +218,24 @@ export class SearchBrowserClient {
     search(request, options = {}) {
         return this.post("search", request, options.signal);
     }
+    /** Several indexes searched in one request, such as products and a blog (0.22.0): up to 10 searches, each
+     * naming its index's public ID (this client's when left out), whose allowed sites must include the page's.
+     * Each counts as a search of its own; one that asks for its index's subindexes counts once with them. The
+     * answers come in the order asked, each its results or its error; it throws only when every search failed. */
+    async multiSearch(queries, options = {}) {
+        const response = await this.fetcher(`${this.url.slice(0, this.url.indexOf("/api/public/"))}/api/public/search`, {
+            method: "POST",
+            headers: { "content-type": "text/plain" },
+            body: JSON.stringify({ queries: queries.map(({ index, ...search }) => ({ index: index ?? this.publicId, ...search })) }),
+            signal: options.signal,
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            const failed = data.results?.find((result) => "error" in result);
+            throw new FindlaneError(response.status, data.error ?? failed?.error ?? `HTTP ${response.status}`);
+        }
+        return data.results ?? [];
+    }
     /** Did you mean: for a search that found nothing, a query that finds something, or null. Takes the same
      * request (its q and filters matter). Needs the index's `didYouMean` setting; not counted as a search.
      * Ask once the shopper stops typing, not for every keystroke. */

package/dist/react/components.d.ts

@@ -15,6 +15,8 @@ export type SearchBoxProps<T> = AutocompleteOptions<T> & {
     action?: string;
     /** A suggestion's content; DefaultHit shows an image and a title. */
     renderHit?: (hit: Hit<T>) => ReactNode;
+    /** A subindex result's content, by the subindex's name; DefaultHit by default (0.22.0). */
+    renderSubindexHit?: (subindex: string, hit: Hit<Record<string, unknown>>) => ReactNode;
     /** Shown when nothing matches (default "No results for “…”"). */
     empty?: (query: string) => ReactNode;
     /** The link to the results page (default "See all N results"). */
@@ -38,12 +40,12 @@ export declare const resultsHref: (action: string, query: string) => string;
  * suggested searches, then the results, "no results", or an error; then a link to the results page.
  * Each kind is a section of one list, which the arrow keys move through. Shared by SearchBox and
  * SearchDialog. */
-export declare function Suggestions<T>({ box, label, action, renderHit, empty, seeAll, labels }: Pick<SearchBoxProps<T>, "action" | "renderHit" | "empty" | "seeAll" | "labels"> & {
+export declare function Suggestions<T>({ box, label, action, renderHit, renderSubindexHit, empty, seeAll, labels }: Pick<SearchBoxProps<T>, "action" | "renderHit" | "renderSubindexHit" | "empty" | "seeAll" | "labels"> & {
     box: ReturnType<typeof useAutocomplete<T>>;
     label: string;
 }): import("react").JSX.Element;
 /** A search box that suggests results as visitors type. Works on its own with a `publicId`. */
-export declare function SearchBox<T = Record<string, unknown>>({ placeholder, label, action, renderHit, empty, seeAll, labels, className, autoFocus, ...options }: SearchBoxProps<T>): import("react").JSX.Element;
+export declare function SearchBox<T = Record<string, unknown>>({ placeholder, label, action, renderHit, renderSubindexHit, empty, seeAll, labels, className, autoFocus, ...options }: SearchBoxProps<T>): import("react").JSX.Element;
 /** The query input of the surrounding SearchProvider. */
 export declare function SearchInput({ placeholder, label, className, autoFocus }: {
     placeholder?: string;
@@ -73,7 +75,7 @@ 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. */
+ * 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;

package/dist/react/components.js

@@ -24,22 +24,35 @@ export const resultsHref = (action, query) => `${action}${action.includes("?") ?
  * suggested searches, then the results, "no results", or an error; then a link to the results page.
  * Each kind is a section of one list, which the arrow keys move through. Shared by SearchBox and
  * SearchDialog. */
-export function Suggestions({ box, label, action, renderHit, empty, seeAll, labels }) {
+export function Suggestions({ box, label, action, renderHit, renderSubindexHit, empty, seeAll, labels }) {
     const { hits, query, total, error, items } = box;
     const text = { ...defaultLabels, ...labels };
-    // Consecutive options of one kind make a section; results get a heading only below searches.
+    // Consecutive options of one kind make a section, each subindex its own; results get a heading only below others.
     const sections = [];
     for (const item of items) {
+        const key = item.kind === "subindex" ? `subindex-${item.subindex}` : item.kind;
         const last = sections.at(-1);
-        if (last?.kind === item.kind)
+        if (last?.key === key)
             last.items.push(item);
         else
-            sections.push({ kind: item.kind, items: [item] });
+            sections.push({ kind: item.kind, key, items: [item] });
     }
     const searching = query.trim() !== "";
     const headings = { recent: text.recent, popular: text.popular,
         suggestion: text.suggestions, hit: text.results };
+    const heading = (section) => {
+        const first = section.items[0];
+        if (first.kind !== "subindex")
+            return headings[first.kind];
+        return box.subindexLabel(first.subindex);
+    };
     const option = (item) => {
+        if (item.kind === "subindex") {
+            const href = box.hrefForSubindex(item);
+            const content = renderSubindexHit ? renderSubindexHit(item.subindex, item.hit) : _jsx(DefaultHit, { hit: item.hit });
+            const key = `${item.subindex}:${item.hit.id}`;
+            return href ? (_jsx("a", { href: href, tabIndex: -1, "data-findlane-subindex": item.subindex, ...box.getOptionProps(item.index), children: content }, key)) : (_jsx("div", { "data-findlane-subindex": item.subindex, ...box.getOptionProps(item.index), children: content }, key));
+        }
         if (item.kind === "hit") {
             const href = box.hrefFor(item.hit);
             const content = renderHit ? renderHit(item.hit) : _jsx(DefaultHit, { hit: item.hit });
@@ -51,17 +64,17 @@ export function Suggestions({ box, label, action, renderHit, empty, seeAll, labe
     };
     return (_jsxs("div", { "data-findlane-panel": "", children: [error ? _jsx("p", { "data-findlane-note": "", children: messageFor(error) }) : null, items.length > 0 && (_jsx("div", { ...box.getListboxProps({ "aria-label": label }), children: sections.map((section) => {
                     const titled = section.kind !== "hit" || sections.length > 1;
-                    const headingId = `${box.getListboxProps().id}-${section.kind}`;
-                    return (_jsxs("div", { role: "group", "aria-labelledby": titled ? headingId : undefined, "aria-label": titled ? undefined : label, "data-findlane-section": section.kind, children: [titled && (_jsxs("div", { "data-findlane-section-title": "", id: headingId, role: "presentation", children: [_jsx("span", { children: headings[section.kind] }), section.kind === "recent" && (_jsx("button", { type: "button", tabIndex: -1, "data-findlane-clear": "", onClick: box.clearRecent, children: text.clear }))] })), section.items.map(option)] }, section.kind));
+                    const headingId = `${box.getListboxProps().id}-${section.key}`;
+                    return (_jsxs("div", { role: "group", "aria-labelledby": titled ? headingId : undefined, "aria-label": titled ? undefined : label, "data-findlane-section": section.kind, children: [titled && (_jsxs("div", { "data-findlane-section-title": "", id: headingId, role: "presentation", children: [_jsx("span", { children: heading(section) }), section.kind === "recent" && (_jsx("button", { type: "button", tabIndex: -1, "data-findlane-clear": "", onClick: box.clearRecent, children: text.clear }))] })), section.items.map(option)] }, section.key));
                 }) })), searching && !error && !hits.length && box.response && (_jsx("p", { "data-findlane-note": "", children: empty ? empty(query) : _jsxs(_Fragment, { children: ["No results for \u201C", query, "\u201D"] }) })), action && searching && total > hits.length && (_jsx("a", { href: resultsHref(action, query), "data-findlane-all": "", onMouseDown: (event) => event.preventDefault(), children: seeAll ? seeAll(total) : `See all ${number(total)} results` }))] }));
 }
 /** A search box that suggests results as visitors type. Works on its own with a `publicId`. */
-export function SearchBox({ placeholder, label = "Search", action, renderHit, empty, seeAll, labels, className, autoFocus, ...options }) {
+export function SearchBox({ placeholder, label = "Search", action, renderHit, renderSubindexHit, empty, seeAll, labels, className, autoFocus, ...options }) {
     // A search chosen from the suggestions goes to the results page, as Enter does.
     const box = useAutocomplete({ ...options,
         onSubmit: options.onSubmit ?? (action ? (query) => window.location.assign(resultsHref(action, query)) : undefined) });
     return (_jsxs("div", { className: className, "data-findlane-searchbox": "", "data-open": box.isOpen || undefined, children: [_jsx("form", { role: "search", action: action, method: "get", onSubmit: (event) => { if (!action)
-                    event.preventDefault(); }, children: _jsx("input", { type: "search", name: "q", placeholder: placeholder, "aria-label": label, autoFocus: autoFocus, ...box.getInputProps() }) }), box.isOpen && (_jsx(Suggestions, { box: box, label: label, action: action, renderHit: renderHit, empty: empty, seeAll: seeAll, labels: labels }))] }));
+                    event.preventDefault(); }, children: _jsx("input", { type: "search", name: "q", placeholder: placeholder, "aria-label": label, autoFocus: autoFocus, ...box.getInputProps() }) }), box.isOpen && (_jsx(Suggestions, { box: box, label: label, action: action, renderHit: renderHit, renderSubindexHit: renderSubindexHit, empty: empty, seeAll: seeAll, labels: labels }))] }));
 }
 /** The query input of the surrounding SearchProvider. */
 export function SearchInput({ placeholder, label = "Search", className, autoFocus }) {
@@ -79,9 +92,9 @@ export function DefaultBanner({ banner }) {
     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. */
+ * 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, response, request } = useHits();
+    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) });
@@ -94,7 +107,13 @@ export function Hits({ render, renderBanner, empty, relatedTitle, loading = null
     // 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);
-    const bannerItems = (place) => bannerAt(place).map((banner, at) => (_jsx("li", { "data-findlane-banner": "", children: renderBanner ? renderBanner(banner) : _jsx(DefaultBanner, { banner: banner }) }, `banner-${banner.rule}-${at}`)));
+    // 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))

package/dist/react/dialog.d.ts

@@ -10,4 +10,4 @@ export type SearchDialogProps<T> = Omit<SearchBoxProps<T>, "autoFocus"> & {
 };
 /** A search button that opens a dialog with a search box, as on docs sites; ⌘K and "/" open it too.
  * The dialog is the browser's own, so focus stays in it and the page behind can't be used. */
-export declare function SearchDialog<T = Record<string, unknown>>({ trigger, shortcuts, footer, placeholder, label, action, renderHit, empty, seeAll, labels, className, ...options }: SearchDialogProps<T>): import("react").JSX.Element;
+export declare function SearchDialog<T = Record<string, unknown>>({ trigger, shortcuts, footer, placeholder, label, action, renderHit, renderSubindexHit, empty, seeAll, labels, className, ...options }: SearchDialogProps<T>): import("react").JSX.Element;

package/dist/react/dialog.js

@@ -6,7 +6,7 @@ import { useAutocomplete } from "./use-autocomplete.js";
 const onMac = () => typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform);
 /** A search button that opens a dialog with a search box, as on docs sites; ⌘K and "/" open it too.
  * The dialog is the browser's own, so focus stays in it and the page behind can't be used. */
-export function SearchDialog({ trigger, shortcuts = true, footer, placeholder, label = "Search", action, renderHit, empty, seeAll, labels, className, ...options }) {
+export function SearchDialog({ trigger, shortcuts = true, footer, placeholder, label = "Search", action, renderHit, renderSubindexHit, empty, seeAll, labels, className, ...options }) {
     const dialog = useRef(null);
     const [open, setOpen] = useState(false);
     const close = () => dialog.current?.close();
@@ -59,5 +59,5 @@ export function SearchDialog({ trigger, shortcuts = true, footer, placeholder, l
                                                 close();
                                             }
                                         },
-                                    }) }) }), box.isOpen && (_jsx(Suggestions, { box: box, label: label, action: action, renderHit: renderHit, empty: empty, seeAll: seeAll, labels: labels }))] })), open && footer && _jsx("div", { "data-findlane-dialog-footer": "", children: footer })] })] }));
+                                    }) }) }), box.isOpen && (_jsx(Suggestions, { box: box, label: label, action: action, renderHit: renderHit, renderSubindexHit: renderSubindexHit, empty: empty, seeAll: seeAll, labels: labels }))] })), open && footer && _jsx("div", { "data-findlane-dialog-footer": "", children: footer })] })] }));
 }

package/dist/react/index.d.ts

@@ -1,6 +1,6 @@
 export { FindlaneProvider, useClient, type ClientOptions } from "./client.js";
 export { useSearch, type UseSearchOptions, type UseSearchResult } from "./use-search.js";
-export { useAutocomplete, type AutocompleteItem, type AutocompleteOptions } from "./use-autocomplete.js";
+export { useAutocomplete, type AutocompleteItem, type AutocompleteOptions, type AutocompleteSubindex } from "./use-autocomplete.js";
 export { useRecommendations, type UseRecommendationsOptions, type UseRecommendationsResult } from "./use-recommendations.js";
 export { Recommendations, type RecommendationsProps } from "./recommendations.js";
 export { ProductView, useProductView } from "./product-view.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.d.ts

@@ -34,6 +34,20 @@ export type AutocompleteOptions<T> = ClientOptions & {
     /** The shopper's recent searches when the box is empty, kept in this browser only: true for the last
      * five, or how many (up to 10). Off unless set. */
     recentSearches?: boolean | number;
+    /** The index's subindexes to show above the results, such as a store's categories and pages, by name, in
+     * the order given (0.22.0). They're searched in the same request as the results, and count as one search
+     * with them. */
+    subindexes?: Record<string, AutocompleteSubindex>;
+};
+/** A subindex in the suggestions: how many of its results to show (1–10, default 3), the fields to return,
+ * its results' pages, and its section's heading (default its name). */
+export type AutocompleteSubindex = {
+    limit?: number;
+    fields?: string[];
+    /** A result's page, as `hrefTemplate` takes it, such as "{url}". */
+    hrefTemplate?: string;
+    getHref?: (hit: Hit<Record<string, unknown>>) => string | undefined;
+    label?: string;
 };
 /** One of the combobox's options, in the order shown: a search to run (suggested for what was typed, or
  * with an empty box a recent or popular one), or a result. `index` is its place among all of them, for
@@ -51,7 +65,15 @@ export type AutocompleteItem<T> = {
     kind: "hit";
     hit: Hit<T>;
     index: number;
+} | {
+    kind: "subindex";
+    subindex: string;
+    hit: Hit<Record<string, unknown>>;
+    index: number;
 };
+type SubindexItem = Extract<AutocompleteItem<unknown>, {
+    kind: "subindex";
+}>;
 /** A hit's address from a template; links to other schemes, such as javascript:, are refused. */
 export declare function fillTemplate<T>(template: string, hit: Hit<T>): string | undefined;
 /** A search box with suggestions, as the WAI-ARIA combobox pattern: the hook keeps the state and
@@ -73,8 +95,14 @@ export declare function useAutocomplete<T = Record<string, unknown>>(options?: A
     setActiveIndex: import("react").Dispatch<import("react").SetStateAction<number>>;
     close: () => void;
     select: (hit: Hit<T>) => void;
-    /** Every option in the order shown: searches, then results. */
+    /** Every option in the order shown: searches, then subindexes' results, then the index's. */
     items: AutocompleteItem<T>[];
+    /** Each subindex's results, by name (0.22.0). */
+    subindexes: Record<string, Hit<Record<string, unknown>>[]>;
+    /** A subindex result's page, from its `getHref` or `hrefTemplate`. */
+    hrefForSubindex: (item: SubindexItem) => string | undefined;
+    /** A subindex's section heading: its `label`, or its name with a capital. */
+    subindexLabel: (name: string) => string;
     /** Query suggestions for what's typed, recent searches, and popular searches, as the API gave them. */
     suggestions: QuerySuggestion[];
     recent: string[];
@@ -92,3 +120,4 @@ export declare function useAutocomplete<T = Record<string, unknown>>(options?: A
      * only results, a result's place among the hits. */
     getOptionProps: (index: number, props?: HTMLAttributes<HTMLElement>) => HTMLAttributes<HTMLElement>;
 };
+export {};

package/dist/react/use-autocomplete.js

@@ -25,6 +25,7 @@ export function useAutocomplete(options = {}) {
     const popularLimit = Math.min(Math.max(options.popularSearches ?? 0, 0), 10);
     const recentLimit = options.recentSearches === true ? 5 : Math.min(Math.max(Number(options.recentSearches) || 0, 0), 10);
     const getHref = options.getHref ?? (hrefTemplate ? (hit) => fillTemplate(hrefTemplate, hit) : undefined);
+    const subindexes = Object.entries(options.subindexes ?? {}).slice(0, 5);
     const generated = useId();
     const id = options.id ?? `findlane${generated.replace(/:/g, "")}`;
     const [query, setQueryState] = useState(options.defaultQuery ?? "");
@@ -39,6 +40,9 @@ export function useAutocomplete(options = {}) {
             ...(fields ? { attributesToRetrieve: fields } : {}),
             ...(filters ? { filters } : {}),
             ...(sort ? { sort } : {}),
+            ...(subindexes.length ? { subindexes: Object.fromEntries(subindexes.map(([name, sub]) => [name, {
+                        limit: Math.min(Math.max(sub.limit ?? 3, 1), 10), ...(sub.fields ? { attributesToRetrieve: sub.fields } : {})
+                    }])) } : {}),
         }
         : null;
     const search = useSearch(request, {
@@ -101,8 +105,21 @@ export function useAutocomplete(options = {}) {
         for (const item of suggestions)
             searches.push({ kind: "suggestion", q: item.q, typed: item.typed, index: searches.length });
     }
-    const items = [...searches,
-        ...hits.map((hit, position) => ({ kind: "hit", hit, index: searches.length + position }))];
+    // Then the subindexes' results, each a section of its own, then the index's.
+    const subindexHits = {};
+    const found = [];
+    for (const [name] of subindexes) {
+        const answer = search.data?.subindexes?.[name];
+        subindexHits[name] = answer && "hits" in answer ? answer.hits : [];
+        for (const hit of subindexHits[name])
+            found.push({ kind: "subindex", subindex: name, hit, index: searches.length + found.length });
+    }
+    const items = [...searches, ...found,
+        ...hits.map((hit, position) => ({ kind: "hit", hit, index: searches.length + found.length + position }))];
+    const subindexHref = (item) => {
+        const sub = options.subindexes?.[item.subindex];
+        return sub?.getHref ? sub.getHref(item.hit) : sub?.hrefTemplate ? fillTemplate(sub.hrefTemplate, item.hit) : undefined;
+    };
     // Open once there's something to show: searches, results, "no results", or an error.
     const isOpen = focused && !dismissed && (emptyBox ? searches.length > 0
         : request !== null && (search.data !== null || search.error !== null || searches.length > 0));
@@ -151,12 +168,22 @@ export function useAutocomplete(options = {}) {
             onSubmit(item.q);
         }
     };
+    /** Follows a subindex's result to its page. */
+    const visit = (item) => {
+        remember(query);
+        close();
+        const href = subindexHref(item);
+        if (href)
+            window.location.assign(href);
+    };
     const choose = (index) => {
         const item = items[index];
         if (!item)
             return;
         if (item.kind === "hit")
             select(item.hit);
+        else if (item.kind === "subindex")
+            visit(item);
         else
             pick(item);
     };
@@ -215,8 +242,14 @@ export function useAutocomplete(options = {}) {
         setActiveIndex,
         close,
         select,
-        /** Every option in the order shown: searches, then results. */
+        /** Every option in the order shown: searches, then subindexes' results, then the index's. */
         items,
+        /** Each subindex's results, by name (0.22.0). */
+        subindexes: subindexHits,
+        /** A subindex result's page, from its `getHref` or `hrefTemplate`. */
+        hrefForSubindex: (item) => subindexHref(item),
+        /** A subindex's section heading: its `label`, or its name with a capital. */
+        subindexLabel: (name) => options.subindexes?.[name]?.label ?? name.charAt(0).toUpperCase() + name.slice(1),
         /** Query suggestions for what's typed, recent searches, and popular searches, as the API gave them. */
         suggestions,
         recent,
@@ -294,6 +327,17 @@ export function useAutocomplete(options = {}) {
                 const item = items[index];
                 if (event.defaultPrevented || !item)
                     return;
+                if (item.kind === "subindex") {
+                    // A link is followed as usual; one opened in a new tab or window is left to the browser.
+                    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+                        return;
+                    if (event.currentTarget.href) {
+                        remember(query);
+                        return close();
+                    }
+                    event.preventDefault();
+                    return visit(item);
+                }
                 if (item.kind !== "hit") {
                     event.preventDefault();
                     return pick(item);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@findlane/browser",
-  "version": "0.20.0",
+  "version": "0.22.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",