@findlane/browser 0.13.0 → 0.14.0

package/README.md

@@ -31,15 +31,26 @@ Without a build step, load it with a script tag, which defines a global `Findlan
 
 Each index has a copyable public ID in the dashboard. An owner must save allowed origins for the index before browser search is enabled.
 
+## Query suggestions
+
+Whole searches to offer as visitors type, and the index's popular searches for an empty box. They don't count as searches. Recent searches stay in the visitor's browser.
+
+```ts
+await client.querySuggestions({ q: "hrek" }) // [{ q: "hrekkjavöku búningar", typed: [0, 4] }]
+await client.popularSearches() // [{ q: "gríma" }, { q: "latex" }]
+client.recentSearches.add("hárkolla")
+```
+
 ## React
 
-`@findlane/browser/react` has a search box that suggests results as visitors type, a results page with filters, and the hooks behind them, for React 18.2 and 19. Pages that don't import it don't load it.
+`@findlane/browser/react` has a search box that suggests searches and results as visitors type, a results page with filters, and the hooks behind them, for React 18.2 and 19. Pages that don't import it don't load it.
 
 ```tsx
 import { SearchBox } from "@findlane/browser/react"
 import "@findlane/browser/react/styles.css" // optional
 
-<SearchBox publicId="pub_your_public_id" getHref={(hit) => hit.record.url} action="/search" />
+<SearchBox publicId="pub_your_public_id" getHref={(hit) => hit.record.url} action="/search"
+  querySuggestions={4} popularSearches={6} recentSearches />
 ```
 
 `SearchDialog` is the same search box in a dialog that ⌘K opens, as on docs sites. A results page shares its state through `SearchProvider`, with `RefinementList`, `SortSelect`, `Hits`, `LoadMore`, and hooks such as `useRefinementList` and `useRange` for your own markup. With `routing`, the search is kept in the URL. `@findlane/browser/react/ssr` renders the first results on the server. On a product page, `useProductView(objectID)`, or `<ProductView>` in a server component, sends the page's view for the index's Events page. Docs: https://findlane.dev/docs/react

package/dist/index.d.ts

@@ -109,6 +109,31 @@ export type DidYouMean = {
         to: string;
     }[];
 };
+/** A whole search to offer as a shopper types, or in an empty box (query suggestions). `typed`: where
+ * what was typed is in `q`, as UTF-16 offsets (end exclusive), so the rest can be set apart, as Google
+ * bolds it; popular searches have none. */
+export type QuerySuggestion = {
+    q: string;
+    typed?: [number, number];
+};
+/** A query suggestion's text in parts: what was typed (`typed: true`) and the rest. */
+export declare function suggestionParts(suggestion: QuerySuggestion): {
+    text: string;
+    typed: boolean;
+}[];
+/** The shopper's recent searches, kept in this browser only (localStorage, per public ID) and never sent
+ * to Findlane: the newest first, without repeats, up to 10. Add a search when it's submitted, picked from
+ * suggestions, or leads to a result being opened, not on every keystroke. */
+export declare class RecentSearches {
+    private readonly key;
+    constructor(publicId: string);
+    /** Up to `limit` of them (5 by default), the newest first. */
+    list(limit?: number): string[];
+    add(q: string): void;
+    remove(q: string): void;
+    clear(): void;
+    private save;
+}
 /** How a product's recommendations are served (the recommendations add-on). */
 export type RecommendationsRequest = {
     /** Up to this many products in each list, 1 to 20; 8 by default. */
@@ -170,6 +195,12 @@ export type BrowserEvents = {
      * (React's double mount in development, a re-render), so it isn't sent. */
     view(objectID: string): void;
     click(objectID: string, details?: ClickDetails): void;
+    /** A query suggestion was picked: the search, its place in its list (from 1), and whether it was
+     * suggested for what was typed, or was a popular or recent search in an empty box. */
+    suggestion(query: string, details?: {
+        position?: number;
+        kind?: "typed" | "popular" | "recent";
+    }): void;
     addToCart(items: EventItem[], options?: {
         currency?: string;
     }): void;
@@ -215,6 +246,9 @@ export declare class SearchBrowserClient {
     private readonly fetcher;
     /** Views, clicks, add-to-carts and orders, for the index's Events page and Bought together. */
     readonly events: BrowserEvents;
+    /** The shopper's recent searches, kept in this browser only. */
+    readonly recentSearches: RecentSearches;
+    private popular;
     constructor(options: BrowserClientOptions);
     private post;
     search<T = Record<string, unknown>>(request: SearchRequest, options?: {
@@ -226,6 +260,21 @@ export declare class SearchBrowserClient {
     suggest(request: SearchRequest, options?: {
         signal?: AbortSignal;
     }): Promise<DidYouMean | null>;
+    /** Query suggestions: whole searches to offer as the shopper types `q`, the best first, from what
+     * shoppers search and the catalog's words and names. Not counted as searches, and answered from memory
+     * near the shopper, so ask on each pause in typing. `limit`: 1 to 10, 5 by default. */
+    querySuggestions(request: {
+        q: string;
+        limit?: number;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<QuerySuggestion[]>;
+    /** The index's popular searches, for an empty search box: what shoppers search most lately, with the
+     * owner's pinned searches first. Empty until the index has enough searches. The list changes daily,
+     * so this client asks once per `limit` and keeps the answer. */
+    popularSearches(options?: {
+        limit?: number;
+    }): Promise<QuerySuggestion[]>;
     /** A product's recommendations (the recommendations add-on): products that go with it, and similar
      * products, for a product page or a cart. Not counted as a search. */
     recommendations<T = Record<string, unknown>>(objectID: string, request?: RecommendationsRequest, options?: {

package/dist/index.js

@@ -1,3 +1,49 @@
+/** A query suggestion's text in parts: what was typed (`typed: true`) and the rest. */
+export function suggestionParts(suggestion) {
+    const [start, end] = suggestion.typed ?? [0, 0];
+    return [{ text: suggestion.q.slice(0, start), typed: false }, { text: suggestion.q.slice(start, end), typed: true },
+        { text: suggestion.q.slice(end), typed: false }].filter((part) => part.text);
+}
+/** The shopper's recent searches, kept in this browser only (localStorage, per public ID) and never sent
+ * to Findlane: the newest first, without repeats, up to 10. Add a search when it's submitted, picked from
+ * suggestions, or leads to a result being opened, not on every keystroke. */
+export class RecentSearches {
+    key;
+    constructor(publicId) {
+        this.key = `findlane:recent:${publicId}`;
+    }
+    /** Up to `limit` of them (5 by default), the newest first. */
+    list(limit = 5) {
+        try {
+            const value = JSON.parse(localStorage.getItem(this.key) ?? "[]");
+            return Array.isArray(value) ? value.filter((item) => typeof item == "string").slice(0, limit) : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    add(q) {
+        const query = q.trim().replace(/\s+/g, " ");
+        if (!query || query.length > 100)
+            return;
+        this.save([query, ...this.list(10).filter((item) => item.toLowerCase() !== query.toLowerCase())]);
+    }
+    remove(q) {
+        this.save(this.list(10).filter((item) => item !== q));
+    }
+    clear() {
+        try {
+            localStorage.removeItem(this.key);
+        }
+        catch { /* storage that can't be used keeps nothing */ }
+    }
+    save(items) {
+        try {
+            localStorage.setItem(this.key, JSON.stringify(items.slice(0, 10)));
+        }
+        catch { /* as above */ }
+    }
+}
 export class FindlaneError extends Error {
     status;
     constructor(status, message) {
@@ -90,6 +136,7 @@ function eventSender(url, fetcher, mode, ids) {
             add({ type: "view", objectID });
         },
         click: (objectID, details) => add({ type: "click", objectID, ...details }),
+        suggestion: (query, details) => add({ type: "suggestion", query, ...details }),
         addToCart: (items, options) => add({ type: "addToCart", items, ...options }),
         purchase: (order) => add({ type: "purchase", ...order }),
         consent(granted) {
@@ -114,12 +161,16 @@ export class SearchBrowserClient {
     fetcher;
     /** Views, clicks, add-to-carts and orders, for the index's Events page and Bought together. */
     events;
+    /** The shopper's recent searches, kept in this browser only. */
+    recentSearches;
+    popular = new Map();
     constructor(options) {
         if (!/^pub_[a-f0-9]{32}$/.test(options.publicId))
             throw new Error("A valid public index ID (pub_…) is required");
         this.url = `${(options.baseUrl ?? defaultBaseUrl).replace(/\/$/, "")}/api/public/indexes/${options.publicId}`;
         this.fetcher = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
         this.events = eventSender(options.eventsUrl ?? `${this.url}/events`, options.fetch, options.events ?? true, options.visitorIds ? deviceIds(options.publicId) : null);
+        this.recentSearches = new RecentSearches(options.publicId);
     }
     async post(operation, request, signal) {
         const response = await this.fetcher(`${this.url}/${operation}`, {
@@ -144,6 +195,25 @@ export class SearchBrowserClient {
     async suggest(request, options = {}) {
         return (await this.post("suggest", request, options.signal)).didYouMean;
     }
+    /** Query suggestions: whole searches to offer as the shopper types `q`, the best first, from what
+     * shoppers search and the catalog's words and names. Not counted as searches, and answered from memory
+     * near the shopper, so ask on each pause in typing. `limit`: 1 to 10, 5 by default. */
+    async querySuggestions(request, options = {}) {
+        return (await this.post("query-suggestions", request, options.signal)).suggestions;
+    }
+    /** The index's popular searches, for an empty search box: what shoppers search most lately, with the
+     * owner's pinned searches first. Empty until the index has enough searches. The list changes daily,
+     * so this client asks once per `limit` and keeps the answer. */
+    popularSearches(options = {}) {
+        const limit = options.limit ?? 6;
+        let asked = this.popular.get(limit);
+        if (!asked) {
+            asked = this.post("query-suggestions", { q: "", limit }).then((data) => data.suggestions);
+            asked.catch(() => this.popular.delete(limit));
+            this.popular.set(limit, asked);
+        }
+        return asked;
+    }
     /** A product's recommendations (the recommendations add-on): products that go with it, and similar
      * products, for a product page or a cart. Not counted as a search. */
     recommendations(objectID, request = {}, options = {}) {

package/dist/react/cache.d.ts

@@ -1,9 +1,12 @@
-import type { RecommendationsRequest, RecommendationsResponse, SearchBrowserClient, SearchRequest, SearchResponse } from "../index.js";
+import type { QuerySuggestion, RecommendationsRequest, RecommendationsResponse, SearchBrowserClient, SearchRequest, SearchResponse } from "../index.js";
 /** Requests the API answers the same way share a key, as at the edge (workers/api/src/edge.ts):
  * the query's first eight lowercase words, defaults left out, and list order ignored. */
 export declare function searchKey(request: SearchRequest): string;
 /** A product's recommendations share a key when only defaults differ: the limit of 8 and empty filters. */
 export declare function recommendationsKey(objectID: string, request?: RecommendationsRequest): string;
+/** Query suggestion requests that the API answers the same way share a key: the text in lowercase with
+ * single spaces, and whether a space ends it (which makes the last word whole). */
+export declare const suggestionsKey: (q: string, limit: number) => string;
 /** A cached response, if there's a recent one. */
 export declare function peek<T>(client: SearchBrowserClient, request: SearchRequest): SearchResponse<T> | null;
 export declare function peekRecommendations<T>(client: SearchBrowserClient, objectID: string, request?: RecommendationsRequest): RecommendationsResponse<T> | null;
@@ -12,3 +15,6 @@ export declare function peekRecommendations<T>(client: SearchBrowserClient, obje
 export declare function cachedSearch<T>(client: SearchBrowserClient, request: SearchRequest, signal?: AbortSignal): Promise<SearchResponse<T>>;
 /** A product's recommendations, kept and shared the same way. */
 export declare function cachedRecommendations<T>(client: SearchBrowserClient, objectID: string, request?: RecommendationsRequest, signal?: AbortSignal): Promise<RecommendationsResponse<T>>;
+/** Query suggestions for what was typed, kept and shared the same way. */
+export declare function peekQuerySuggestions(client: SearchBrowserClient, q: string, limit: number): QuerySuggestion[] | null;
+export declare function cachedQuerySuggestions(client: SearchBrowserClient, q: string, limit: number, signal?: AbortSignal): Promise<QuerySuggestion[]>;

package/dist/react/cache.js

@@ -4,6 +4,7 @@ const maxAge = 5 * 60_000;
 const store = () => ({ responses: new WeakMap(), flights: new WeakMap() });
 const searches = store();
 const recommendations = store();
+const suggestions = store();
 /** Requests the API answers the same way share a key, as at the edge (workers/api/src/edge.ts):
  * the query's first eight lowercase words, defaults left out, and list order ignored. */
 export function searchKey(request) {
@@ -27,6 +28,9 @@ export function recommendationsKey(objectID, request = {}) {
     return canonical({ objectID, ...rest, ...(limit !== undefined && limit !== 8 ? { limit } : {}),
         ...(filters && Object.keys(filters).length ? { filters } : {}) });
 }
+/** Query suggestion requests that the API answers the same way share a key: the text in lowercase with
+ * single spaces, and whether a space ends it (which makes the last word whole). */
+export const suggestionsKey = (q, limit) => `${limit}\n${q.toLowerCase().replace(/\s+/g, " ").replace(/^ /, "")}`;
 function lookup(from, client, key) {
     const entry = from.responses.get(client)?.get(key);
     return entry && Date.now() - entry.at < maxAge ? entry.response : null;
@@ -47,6 +51,13 @@ export function cachedSearch(client, request, signal) {
 export function cachedRecommendations(client, objectID, request = {}, signal) {
     return shared(recommendations, client, recommendationsKey(objectID, request), (stop) => client.recommendations(objectID, request, { signal: stop }), signal);
 }
+/** Query suggestions for what was typed, kept and shared the same way. */
+export function peekQuerySuggestions(client, q, limit) {
+    return lookup(suggestions, client, suggestionsKey(q, limit));
+}
+export function cachedQuerySuggestions(client, q, limit, signal) {
+    return shared(suggestions, client, suggestionsKey(q, limit), (stop) => client.querySuggestions({ q, limit }, { signal: stop }), signal);
+}
 function shared(from, client, key, load, signal) {
     const found = lookup(from, client, key);
     if (found)

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 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";
@@ -19,19 +19,31 @@ export type SearchBoxProps<T> = AutocompleteOptions<T> & {
     empty?: (query: string) => ReactNode;
     /** The link to the results page (default "See all N results"). */
     seeAll?: (total: number) => ReactNode;
+    /** The sections' headings and buttons, for other languages. */
+    labels?: Partial<SuggestionLabels>;
     className?: string;
     autoFocus?: boolean;
 };
+export type SuggestionLabels = {
+    recent: string;
+    popular: string;
+    suggestions: string;
+    results: string;
+    clear: string;
+    remove: string;
+};
 /** A results page's address for a query. */
 export declare const resultsHref: (action: string, query: string) => string;
-/** The suggestions under a search box: the hits, "no results", or an error, then a link to the
- * results page. Shared by SearchBox and SearchDialog. */
-export declare function Suggestions<T>({ box, label, action, renderHit, empty, seeAll }: Pick<SearchBoxProps<T>, "action" | "renderHit" | "empty" | "seeAll"> & {
+/** The suggestions under a search box: recent and popular searches with an empty box; while typing,
+ * 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"> & {
     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, className, autoFocus, ...options }: SearchBoxProps<T>): import("react").JSX.Element;
+export declare function SearchBox<T = Record<string, unknown>>({ placeholder, label, action, renderHit, 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

@@ -3,6 +3,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { useState } from "react";
 import { Highlight } from "./highlight.js";
 import { messageFor } from "./messages.js";
+import { suggestionParts } from "../index.js";
 import { useCurrentRefinements, useDidYouMean, useHits, useLoadMore, useRefinementList, useSearchBox, useSortBy, } from "./search-provider.js";
 import { useAutocomplete } from "./use-autocomplete.js";
 // The components render plain elements marked with data-findlane-* attributes and no styles of
@@ -15,23 +16,52 @@ export function DefaultHit({ hit }) {
     const field = ["title", "name"].find((name) => name in record || hit.highlights?.[name] !== undefined);
     return (_jsxs(_Fragment, { children: [image && _jsx("img", { src: image, alt: "", loading: "lazy", "data-findlane-image": "" }), _jsx("span", { "data-findlane-title": "", children: field ? _jsx(Highlight, { hit: hit, field: field }) : hit.id })] }));
 }
+const defaultLabels = { recent: "Recent searches", popular: "Popular searches", suggestions: "Searches",
+    results: "Results", clear: "Clear", remove: "Remove" };
 /** A results page's address for a query. */
 export const resultsHref = (action, query) => `${action}${action.includes("?") ? "&" : "?"}q=${encodeURIComponent(query)}`;
-/** The suggestions under a search box: the hits, "no results", or an error, then a link to the
- * results page. Shared by SearchBox and SearchDialog. */
-export function Suggestions({ box, label, action, renderHit, empty, seeAll }) {
-    const { hits, query, total, error } = box;
-    return (_jsxs("div", { "data-findlane-panel": "", children: [error ? (_jsx("p", { "data-findlane-note": "", children: messageFor(error) })) : hits.length ? (_jsx("div", { ...box.getListboxProps({ "aria-label": label }), children: hits.map((hit, index) => {
-                    const href = box.hrefFor(hit);
-                    const content = renderHit ? renderHit(hit) : _jsx(DefaultHit, { hit: hit });
-                    return href ? (_jsx("a", { href: href, tabIndex: -1, ...box.getOptionProps(index), children: content }, hit.id)) : (_jsx("div", { ...box.getOptionProps(index), children: content }, hit.id));
-                }) })) : (_jsx("p", { "data-findlane-note": "", children: empty ? empty(query) : _jsxs(_Fragment, { children: ["No results for \u201C", query, "\u201D"] }) })), action && 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` }))] }));
+/** The suggestions under a search box: recent and popular searches with an empty box; while typing,
+ * 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 }) {
+    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.
+    const sections = [];
+    for (const item of items) {
+        const last = sections.at(-1);
+        if (last?.kind === item.kind)
+            last.items.push(item);
+        else
+            sections.push({ kind: item.kind, items: [item] });
+    }
+    const searching = query.trim() !== "";
+    const headings = { recent: text.recent, popular: text.popular,
+        suggestion: text.suggestions, hit: text.results };
+    const option = (item) => {
+        if (item.kind === "hit") {
+            const href = box.hrefFor(item.hit);
+            const content = renderHit ? renderHit(item.hit) : _jsx(DefaultHit, { hit: item.hit });
+            return href ? (_jsx("a", { href: href, tabIndex: -1, ...box.getOptionProps(item.index), children: content }, item.hit.id)) : (_jsx("div", { ...box.getOptionProps(item.index), children: content }, item.hit.id));
+        }
+        return (_jsxs("div", { "data-findlane-query": item.kind, ...box.getOptionProps(item.index), children: [_jsx("span", { "data-findlane-query-text": "", children: item.kind === "suggestion" && item.typed
+                        ? suggestionParts(item).map((part, at) => part.typed ? _jsx("span", { children: part.text }, at) : _jsx("b", { children: part.text }, at))
+                        : item.q }), item.kind === "recent" && (_jsx("button", { type: "button", tabIndex: -1, "aria-label": `${text.remove} ${item.q}`, "data-findlane-remove": "", onClick: (event) => { event.stopPropagation(); box.removeRecent(item.q); }, children: "\u00D7" }))] }, `${item.kind}:${item.q}`));
+    };
+    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));
+                }) })), 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, className, autoFocus, ...options }) {
-    const box = useAutocomplete(options);
+export function SearchBox({ placeholder, label = "Search", action, renderHit, 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 }))] }));
+                    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 }))] }));
 }
 /** 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, className, ...options }: SearchDialogProps<T>): import("react").JSX.Element;
+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;

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, className, ...options }) {
+export function SearchDialog({ trigger, shortcuts = true, footer, placeholder, label = "Search", action, renderHit, 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 }))] })), open && footer && _jsx("div", { "data-findlane-dialog-footer": "", children: footer })] })] }));
+                                    }) }) }), 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 })] })] }));
 }

package/dist/react/index.d.ts

@@ -1,11 +1,11 @@
 export { FindlaneProvider, useClient, type ClientOptions } from "./client.js";
 export { useSearch, type UseSearchOptions, type UseSearchResult } from "./use-search.js";
-export { useAutocomplete, type AutocompleteOptions } from "./use-autocomplete.js";
+export { useAutocomplete, type AutocompleteItem, type AutocompleteOptions } 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 { CurrentRefinements, DefaultHit, DidYouMean, Hits, LoadMore, RefinementList, SearchBox, SearchInput, SortSelect, Stats, type HitsProps, type RefinementListProps, type SearchBoxProps, } from "./components.js";
+export { CurrentRefinements, 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/styles.css

@@ -86,6 +86,49 @@
   border-top: 1px solid var(--findlane-border, color-mix(in srgb, currentColor 10%, transparent));
 }
 
+/* Searches (suggested, recent, popular) and results are sections of one list, each under a small heading. */
+:where([data-findlane-section] + [data-findlane-section]) {
+  margin-top: 4px;
+  padding-top: 4px;
+  border-top: 1px solid var(--findlane-border, color-mix(in srgb, currentColor 10%, transparent));
+}
+:where([data-findlane-section-title]) {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 6px 12px 2px;
+  color: var(--findlane-muted, color-mix(in srgb, currentColor 60%, transparent));
+  font-size: 0.8em;
+  font-weight: 600;
+}
+:where([data-findlane-section-title] [data-findlane-clear], [data-findlane-remove]) {
+  padding: 0 4px;
+  color: inherit;
+  font: inherit;
+  background: none;
+  border: 0;
+  cursor: pointer;
+}
+:where([data-findlane-panel] [data-findlane-query]) {
+  justify-content: space-between;
+  padding: 6px 12px;
+}
+:where([data-findlane-query-text]) {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+/* What was typed is plain, and the rest of the suggestion bold, as search engines show it. */
+:where([data-findlane-query-text] b) {
+  font-weight: 600;
+}
+:where([data-findlane-remove]) {
+  color: var(--findlane-muted, color-mix(in srgb, currentColor 60%, transparent));
+  font-size: 1.1em;
+  line-height: 1;
+}
+
 :where([data-findlane-dialog-trigger]) {
   display: inline-flex;
   gap: 12px;

package/dist/react/use-autocomplete.d.ts

@@ -1,8 +1,9 @@
 import { type HTMLAttributes, type InputHTMLAttributes } from "react";
+import type { QuerySuggestion } from "../index.js";
 import type { Hit } from "./state.js";
 import { type ClientOptions } from "./client.js";
 export type AutocompleteOptions<T> = ClientOptions & {
-    /** Suggestions to show: 1–50 (default 6). */
+    /** Results to show: 1–50 (default 6). */
     limit?: number;
     /** The record fields to return (`attributesToRetrieve`). */
     fields?: string[];
@@ -14,23 +15,51 @@ export type AutocompleteOptions<T> = ClientOptions & {
     defaultQuery?: string;
     /** A base for the elements' IDs; one is generated otherwise. */
     id?: string;
-    /** A hit's page. Enter on a suggestion goes there unless `onSelect` is given. */
+    /** A hit's page. Enter on a result goes there unless `onSelect` is given. */
     getHref?: (hit: Hit<T>) => string | undefined;
     /** A hit's page as a template, for server components, which can't pass `getHref`:
      * "/products/{handle}" puts in the record's `handle`, URL-encoded, and `{objectID}` the hit's ID.
      * A template that is one field, such as "{url}", takes that field's URL as it is. */
     hrefTemplate?: string;
-    /** Called when a suggestion is chosen, instead of following its link; for client-side routers. */
+    /** Called when a result is chosen, instead of following its link; for client-side routers. */
     onSelect?: (hit: Hit<T>) => void;
-    /** Called on Enter without a chosen suggestion. Without it, Enter submits the input's form. */
+    /** Called on Enter without a chosen result, and when a search is chosen from the suggestions. Without
+     * it, Enter submits the input's form, and a chosen search fills the box and shows its results. */
     onSubmit?: (query: string) => void;
+    /** Query suggestions: whole searches above the results as the shopper types, up to this many (1–10).
+     * Off unless set. */
+    querySuggestions?: number;
+    /** The store's popular searches when the box is empty, up to this many (1–10). Off unless set. */
+    popularSearches?: number;
+    /** 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;
+};
+/** 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
+ * getOptionProps. */
+export type AutocompleteItem<T> = {
+    kind: "suggestion";
+    q: string;
+    typed?: [number, number];
+    index: number;
+} | {
+    kind: "recent" | "popular";
+    q: string;
+    index: number;
+} | {
+    kind: "hit";
+    hit: Hit<T>;
+    index: number;
 };
 /** 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
- * the prop getters give the input, list, and options their attributes and events. Choosing a
- * suggestion sends a click event with its place and the query, for click-through in Analytics (the
- * client's `events` option turns them off, or holds them until consent). */
+ * the prop getters give the input, list, and options their attributes and events. Choosing a result
+ * sends a click event with its place and the query, and choosing a search a suggestion event, for
+ * Analytics (the client's `events` option turns them off, or holds them until consent). With query
+ * suggestions, popular or recent searches on, `items` lists the searches before the results, and
+ * options are numbered across both. */
 export declare function useAutocomplete<T = Record<string, unknown>>(options?: AutocompleteOptions<T>): {
     query: string;
     setQuery: (value: string) => void;
@@ -50,9 +79,22 @@ 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. */
+    items: AutocompleteItem<T>[];
+    /** Query suggestions for what's typed, recent searches, and popular searches, as the API gave them. */
+    suggestions: QuerySuggestion[];
+    recent: string[];
+    popular: QuerySuggestion[];
+    /** Runs an option: follows a result, or runs a search. */
+    choose: (index: number) => void;
+    /** Removes one of the shopper's recent searches, or all of them. */
+    removeRecent: (q: string) => void;
+    clearRecent: () => void;
     /** A hit's page, from `getHref` or `hrefTemplate`. */
     hrefFor: (hit: Hit<T>) => string | undefined;
     getInputProps: (props?: InputHTMLAttributes<HTMLInputElement>) => InputHTMLAttributes<HTMLInputElement>;
     getListboxProps: (props?: HTMLAttributes<HTMLElement>) => HTMLAttributes<HTMLElement>;
+    /** An option's attributes and events, by its place among all options (`index` of `items`); with
+     * only results, a result's place among the hits. */
     getOptionProps: (index: number, props?: HTMLAttributes<HTMLElement>) => HTMLAttributes<HTMLElement>;
 };

package/dist/react/use-autocomplete.js

@@ -3,6 +3,7 @@ import { useEffect, useId, useState, } from "react";
 import { valuesAt } from "./highlight.js";
 import { useSearch } from "./use-search.js";
 import { useClient } from "./client.js";
+import { cachedQuerySuggestions, peekQuerySuggestions } from "./cache.js";
 /** A hit's address from a template; links to other schemes, such as javascript:, are refused. */
 export function fillTemplate(template, hit) {
     const value = (field) => (field === "objectID" ? hit.id : valuesAt(hit.record, field)[0] ?? "");
@@ -10,12 +11,18 @@ export function fillTemplate(template, hit) {
     const href = whole ? value(whole[1]) : template.replace(/\{([^}]+)\}/g, (_, field) => encodeURIComponent(value(field)));
     return /^[a-z][a-z\d+.-]*:/i.test(href.trim()) && !/^https?:/i.test(href.trim()) ? undefined : href || undefined;
 }
+const noSuggestions = [];
 /** A search box with suggestions, as the WAI-ARIA combobox pattern: the hook keeps the state and
- * the prop getters give the input, list, and options their attributes and events. Choosing a
- * suggestion sends a click event with its place and the query, for click-through in Analytics (the
- * client's `events` option turns them off, or holds them until consent). */
+ * the prop getters give the input, list, and options their attributes and events. Choosing a result
+ * sends a click event with its place and the query, and choosing a search a suggestion event, for
+ * Analytics (the client's `events` option turns them off, or holds them until consent). With query
+ * suggestions, popular or recent searches on, `items` lists the searches before the results, and
+ * options are numbered across both. */
 export function useAutocomplete(options = {}) {
     const { limit = 6, fields, filters, sort, minLength = 1, debounceMs, hrefTemplate, onSelect, onSubmit } = options;
+    const suggestionLimit = Math.min(Math.max(options.querySuggestions ?? 0, 0), 10);
+    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 generated = useId();
     const id = options.id ?? `findlane${generated.replace(/:/g, "")}`;
@@ -38,10 +45,66 @@ export function useAutocomplete(options = {}) {
     });
     const client = useClient({ publicId: options.publicId, baseUrl: options.baseUrl, client: options.client });
     const hits = search.data?.hits ?? [];
-    // Open once there's something to show: suggestions, "no results", or an error.
-    const isOpen = focused && !dismissed && request !== null && (search.data !== null || search.error !== null);
+    const emptyBox = query.trim() === "";
+    // Query suggestions for what's typed, after the same pause as the search; the last ones stay while
+    // the next load. Popular searches are asked for on the first focus (the client keeps them), and recent
+    // ones read from this browser on each.
+    const [suggestions, setSuggestions] = useState(noSuggestions);
+    const typed = request && suggestionLimit ? query : null;
+    useEffect(() => {
+        if (typed === null)
+            return setSuggestions(noSuggestions);
+        const cached = peekQuerySuggestions(client, typed, suggestionLimit);
+        if (cached)
+            return setSuggestions(cached);
+        let active = true;
+        const controller = new AbortController();
+        const timer = setTimeout(() => {
+            cachedQuerySuggestions(client, typed, suggestionLimit, controller.signal)
+                .then((items) => { if (active)
+                setSuggestions(items); }, () => undefined);
+        }, debounceMs ?? 150);
+        return () => {
+            active = false;
+            clearTimeout(timer);
+            controller.abort();
+        };
+    }, [client, typed, suggestionLimit, debounceMs]);
+    const [popular, setPopular] = useState(noSuggestions);
+    useEffect(() => {
+        if (!popularLimit || !focused)
+            return;
+        let active = true;
+        client.popularSearches({ limit: popularLimit }).then((items) => { if (active)
+            setPopular(items); }, () => undefined);
+        return () => { active = false; };
+    }, [client, popularLimit, focused]);
+    const [recent, setRecent] = useState([]);
+    useEffect(() => {
+        if (recentLimit && focused)
+            setRecent(client.recentSearches.list(recentLimit));
+    }, [client, recentLimit, focused]);
+    // The searches first, then the results; with an empty box, recent searches and popular ones not among them.
+    const searches = [];
+    if (emptyBox) {
+        const shown = new Set(recent.map((q) => q.toLowerCase()));
+        for (const q of recent)
+            searches.push({ kind: "recent", q, index: searches.length });
+        for (const item of popular)
+            if (!shown.has(item.q.toLowerCase()))
+                searches.push({ kind: "popular", q: item.q, index: searches.length });
+    }
+    else if (request) {
+        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 }))];
+    // 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));
     // New suggestions start unselected.
-    useEffect(() => setActiveIndex(-1), [search.data]);
+    useEffect(() => setActiveIndex(-1), [search.data, suggestions, emptyBox]);
     const listboxId = `${id}-listbox`;
     const optionId = (index) => `${id}-option-${index}`;
     const setQuery = (value) => {
@@ -53,12 +116,20 @@ export function useAutocomplete(options = {}) {
         setDismissed(true);
         setActiveIndex(-1);
     };
+    /** A search the shopper made: kept among their recent searches, when those are on. */
+    const remember = (q) => {
+        if (!recentLimit || !q.trim())
+            return;
+        client.recentSearches.add(q);
+        setRecent(client.recentSearches.list(recentLimit));
+    };
     const clicked = (hit) => {
         const index = hits.indexOf(hit);
         client.events.click(hit.id, { query, ...(index >= 0 ? { position: index + 1 } : {}) });
     };
     const select = (hit) => {
         clicked(hit);
+        remember(query);
         close();
         if (onSelect)
             return onSelect(hit);
@@ -66,14 +137,34 @@ export function useAutocomplete(options = {}) {
         if (href)
             window.location.assign(href);
     };
+    /** Runs a suggested, popular or recent search: onSubmit gets it, or it fills the box and its results show. */
+    const pick = (item) => {
+        const position = searches.filter((other) => other.kind === item.kind).indexOf(item) + 1;
+        client.events.suggestion(item.q, { kind: item.kind === "suggestion" ? "typed" : item.kind, ...(position ? { position } : {}) });
+        remember(item.q);
+        setQuery(item.q);
+        if (onSubmit) {
+            close();
+            onSubmit(item.q);
+        }
+    };
+    const choose = (index) => {
+        const item = items[index];
+        if (!item)
+            return;
+        if (item.kind === "hit")
+            select(item.hit);
+        else
+            pick(item);
+    };
     function onKeyDown(event) {
         if (event.key === "ArrowDown" || event.key === "ArrowUp") {
             event.preventDefault();
             if (!isOpen)
                 return setDismissed(false);
             const step = event.key === "ArrowDown" ? 1 : -1;
-            // -1 is the input itself, between the last suggestion and the first.
-            setActiveIndex((current) => ((current + 1 + step + hits.length + 1) % (hits.length + 1)) - 1);
+            // -1 is the input itself, between the last option and the first.
+            setActiveIndex((current) => ((current + 1 + step + items.length + 1) % (items.length + 1)) - 1);
         }
         else if (event.key === "Escape") {
             if (isOpen) {
@@ -86,15 +177,18 @@ export function useAutocomplete(options = {}) {
             }
         }
         else if (event.key === "Enter" && !event.nativeEvent.isComposing) {
-            const hit = isOpen && activeIndex >= 0 ? hits[activeIndex] : undefined;
-            if (hit) {
+            const item = isOpen && activeIndex >= 0 ? items[activeIndex] : undefined;
+            if (item) {
                 event.preventDefault();
-                select(hit);
+                choose(item.index);
             }
-            else if (onSubmit) {
-                event.preventDefault();
-                close();
-                onSubmit(query);
+            else {
+                remember(query);
+                if (onSubmit) {
+                    event.preventDefault();
+                    close();
+                    onSubmit(query);
+                }
             }
         }
     }
@@ -111,6 +205,23 @@ export function useAutocomplete(options = {}) {
         setActiveIndex,
         close,
         select,
+        /** Every option in the order shown: searches, then results. */
+        items,
+        /** Query suggestions for what's typed, recent searches, and popular searches, as the API gave them. */
+        suggestions,
+        recent,
+        popular,
+        /** Runs an option: follows a result, or runs a search. */
+        choose,
+        /** Removes one of the shopper's recent searches, or all of them. */
+        removeRecent: (q) => {
+            client.recentSearches.remove(q);
+            setRecent(client.recentSearches.list(recentLimit));
+        },
+        clearRecent: () => {
+            client.recentSearches.clear();
+            setRecent([]);
+        },
         /** A hit's page, from `getHref` or `hrefTemplate`. */
         hrefFor: (hit) => getHref?.(hit),
         getInputProps: (props = {}) => ({
@@ -148,12 +259,14 @@ export function useAutocomplete(options = {}) {
             ...props,
             id: listboxId,
             role: "listbox",
-            // Keeps focus in the input, so choosing a suggestion doesn't close the list first.
+            // Keeps focus in the input, so choosing an option doesn't close the list first.
             onMouseDown: (event) => {
                 props.onMouseDown?.(event);
                 event.preventDefault();
             },
         }),
+        /** An option's attributes and events, by its place among all options (`index` of `items`); with
+         * only results, a result's place among the hits. */
         getOptionProps: (index, props = {}) => ({
             ...props,
             id: optionId(index),
@@ -166,9 +279,14 @@ export function useAutocomplete(options = {}) {
             },
             onClick: (event) => {
                 props.onClick?.(event);
-                const hit = hits[index];
-                if (event.defaultPrevented || !hit)
+                const item = items[index];
+                if (event.defaultPrevented || !item)
                     return;
+                if (item.kind !== "hit") {
+                    event.preventDefault();
+                    return pick(item);
+                }
+                const hit = item.hit;
                 // A link opened in a new tab or window is left to the browser.
                 if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
                     return clicked(hit);
@@ -179,6 +297,7 @@ export function useAutocomplete(options = {}) {
                 }
                 else {
                     clicked(hit);
+                    remember(query);
                     close();
                 }
             },

package/package.json

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