@findlane/browser 0.21.0 → 0.23.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;
@@ -344,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;
@@ -359,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

@@ -162,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;
@@ -171,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));
@@ -216,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;

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 }) {

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,10 +1,10 @@
 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";
-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 { SearchProvider, useCurrentRefinements, useDidYouMean, useGeoSearch, useHits, useLoadMore, usePagination, useRange, useRefinementList, useSearchBox, useSearchState, useSortBy, useSubindex, useToggle, type Range, type Refinement, type SearchProviderProps, } from "./search-provider.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";

package/dist/react/index.js

@@ -6,7 +6,7 @@ export { useAutocomplete } from "./use-autocomplete.js";
 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 { SearchProvider, useCurrentRefinements, useDidYouMean, useGeoSearch, useHits, useLoadMore, usePagination, useRange, useRefinementList, useSearchBox, useSearchState, useSortBy, useSubindex, useToggle, } from "./search-provider.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";

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

@@ -2,7 +2,7 @@ import { type ReactNode } from "react";
 import type { DidYouMean, GeoBox } from "../index.js";
 import { type ClientOptions } from "./client.js";
 import { type ServerResults, type StateChange } from "./store.js";
-import { type Near, type SearchConfig, type SearchState } from "./state.js";
+import { type Hit, type Near, type SearchConfig, type SearchState } from "./state.js";
 export type SearchProviderProps<T> = SearchConfig & ClientOptions & {
     children: ReactNode;
     /** Keeps the state in the page's URL (`?q=shoe&brand=Acme`), so results can be shared and Back
@@ -32,8 +32,11 @@ export declare function useSearchBox(): {
     /** Opens the connection to the API ahead of the first search: call it when the box gets focus. */
     warm: () => void;
 };
+/** A subindex's results for the current query (SearchProvider's `subindexes`), such as categories to suggest
+ * above the results; none without a query, or when its search failed (0.23.0). */
+export declare function useSubindex<T = Record<string, unknown>>(name: string): Hit<T>[];
 export declare function useHits<T = Record<string, unknown>>(): {
-    hits: import("./state.js").Hit<T>[];
+    hits: Hit<T>[];
     total: number;
     /** With the index's related results on, when nothing matched: the products closest in meaning. */
     related: import("../index.js").SearchHit<T>[];

package/dist/react/search-provider.js

@@ -77,6 +77,13 @@ export function useSearchBox() {
         /** Opens the connection to the API ahead of the first search: call it when the box gets focus. */
         warm: () => store.warm() };
 }
+/** A subindex's results for the current query (SearchProvider's `subindexes`), such as categories to suggest
+ * above the results; none without a query, or when its search failed (0.23.0). */
+export function useSubindex(name) {
+    const [{ results }] = useSnapshot();
+    const answer = results?.response.subindexes?.[name];
+    return answer && "hits" in answer ? answer.hits : [];
+}
 export function useHits() {
     const [{ results, pending, error }, store] = useSnapshot();
     return {

package/dist/react/state.d.ts

@@ -41,6 +41,9 @@ export type SearchConfig = {
     facetMode?: "page" | "exact";
     /** Contexts the page sends, which the index's rules may fire on, such as "category-page" (0.19.0). */
     context?: string | string[];
+    /** The index's subindexes to search with each query, such as categories to suggest above the results, by
+     * name (0.23.0): in the same request, counted as one search. Read them with useSubindex. */
+    subindexes?: SearchRequest["subindexes"];
 };
 export declare const emptyState: SearchState;
 /** The API's largest offset. */

package/dist/react/state.js

@@ -28,6 +28,8 @@ export function planSearch(config, state) {
         countMode: config.countMode ?? "exact",
         ...(facets.length ? { facetMode: config.facetMode ?? "exact" } : {}),
         ...(config.context?.length ? { context: config.context } : {}),
+        // Subindexes only for a query: a page without words has nothing to suggest.
+        ...(config.subindexes && state.q.trim() ? { subindexes: config.subindexes } : {}),
         highlight: true,
     };
 }

package/dist/react/store.js

@@ -164,7 +164,7 @@ export class SearchStore {
         const { results, loadingMore, pending } = this.snapshot;
         if (!results?.hasMore || loadingMore || pending)
             return;
-        const { facets: _, disjunctiveFacets: __, facetMode: ___, facetStats: ____, ...request } = results.request;
+        const { facets: _, disjunctiveFacets: __, facetMode: ___, facetStats: ____, subindexes: _____, ...request } = results.request;
         const offset = (request.offset ?? 0) + results.hits.length;
         const run = this.run;
         this.set({ loadingMore: true });

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.21.0",
+  "version": "0.23.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",