@findlane/browser 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -39,6 +39,20 @@ export type SearchResponse<T> = {
     facets: Record<string, Record<string, number>>;
     tookMs: number;
     sort?: string;
+    /** With the index's `didYouMean` setting: the query with the words typo tolerance corrected, when the
+     * results matched some words only by typo ("Showing results for …"), else null. */
+    didYouMean?: DidYouMean | null;
+};
+/** A corrected query. `applied`: the results are already for `q` (a search's "Showing results for");
+ * otherwise searching `q` finds results that the query didn't ("Did you mean"). `changes` lists each
+ * changed part of the query as typed. */
+export type DidYouMean = {
+    q: string;
+    applied: boolean;
+    changes: {
+        from: string;
+        to: string;
+    }[];
 };
 export declare class FindlaneError extends Error {
     status: number;
@@ -56,7 +70,14 @@ export declare class SearchBrowserClient {
     private readonly url;
     private readonly fetcher;
     constructor(options: BrowserClientOptions);
+    private post;
     search<T = Record<string, unknown>>(request: SearchRequest, options?: {
         signal?: AbortSignal;
     }): Promise<SearchResponse<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. */
+    suggest(request: SearchRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<DidYouMean | null>;
 }

package/dist/index.js

@@ -14,19 +14,28 @@ 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.url = `${(options.baseUrl ?? defaultBaseUrl).replace(/\/$/, "")}/api/public/indexes/${options.publicId}/search`;
+        this.url = `${(options.baseUrl ?? defaultBaseUrl).replace(/\/$/, "")}/api/public/indexes/${options.publicId}`;
         this.fetcher = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
     }
-    async search(request, options = {}) {
-        const response = await this.fetcher(this.url, {
+    async post(operation, request, signal) {
+        const response = await this.fetcher(`${this.url}/${operation}`, {
             method: "POST",
             headers: { "content-type": "application/json" },
             body: JSON.stringify(request),
-            signal: options.signal,
+            signal,
         });
         const data = await response.json();
         if (!response.ok)
             throw new FindlaneError(response.status, data.error ?? `HTTP ${response.status}`);
         return data;
     }
+    search(request, options = {}) {
+        return this.post("search", request, options.signal);
+    }
+    /** 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. */
+    async suggest(request, options = {}) {
+        return (await this.post("suggest", request, options.signal)).didYouMean;
+    }
 }

package/dist/react/components.d.ts

@@ -1,4 +1,5 @@
 import { type ReactNode } from "react";
+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";
@@ -80,6 +81,15 @@ export declare function LoadMore({ label, className }: {
     label?: string;
     className?: string;
 }): import("react").JSX.Element | null;
+/** "Showing results for …" when typo tolerance corrected the query, and "Did you mean …?", a button that
+ * searches for it, when nothing matched. Needs the index's didYouMean setting; otherwise shows nothing. */
+export declare function DidYouMean({ delay, format, className }: {
+    /** How long the visitor must stop typing before a suggestion is asked for (default 400 ms). */
+    delay?: number;
+    /** The line's content (default "Showing results for …" or "Did you mean …?"). */
+    format?: (didYouMean: Correction, apply: () => void) => ReactNode;
+    className?: string;
+}): import("react").JSX.Element | null;
 /** "1,234 results". */
 export declare function Stats({ format, className }: {
     format?: (total: number) => ReactNode;

package/dist/react/components.js

@@ -3,7 +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 { useCurrentRefinements, useHits, useLoadMore, useRefinementList, useSearchBox, useSortBy, } from "./search-provider.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
 // their own; styles.css gives them a default look.
@@ -74,6 +74,16 @@ export function LoadMore({ label = "Show more", className }) {
         return null;
     return (_jsxs("div", { className: className, "data-findlane-load-more": "", children: [_jsx("button", { type: "button", onClick: loadMore, disabled: isLoading, children: isLoading ? "Loading…" : label }), _jsxs("span", { children: [number(shown), " of ", number(total)] })] }));
 }
+/** "Showing results for …" when typo tolerance corrected the query, and "Did you mean …?", a button that
+ * searches for it, when nothing matched. Needs the index's didYouMean setting; otherwise shows nothing. */
+export function DidYouMean({ delay, format, className }) {
+    const { didYouMean, apply } = useDidYouMean({ delay });
+    if (!didYouMean)
+        return null;
+    return (_jsx("p", { className: className, "data-findlane-did-you-mean": "", children: format ? format(didYouMean, apply) : didYouMean.applied
+            ? _jsxs(_Fragment, { children: ["Showing results for ", _jsx("b", { children: didYouMean.q })] })
+            : _jsxs(_Fragment, { children: ["Did you mean ", _jsx("button", { type: "button", onClick: apply, children: didYouMean.q }), "?"] }) }));
+}
 /** "1,234 results". */
 export function Stats({ format, className }) {
     const { total, totalRelation, isLoaded } = useHits();

package/dist/react/index.d.ts

@@ -1,8 +1,8 @@
 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 { SearchProvider, useCurrentRefinements, useHits, useLoadMore, usePagination, useRange, useRefinementList, useSearchBox, useSearchState, useSortBy, useToggle, type Range, type Refinement, type SearchProviderProps, } from "./search-provider.js";
-export { CurrentRefinements, DefaultHit, Hits, LoadMore, RefinementList, SearchBox, SearchInput, SortSelect, Stats, type HitsProps, type RefinementListProps, type SearchBoxProps, } from "./components.js";
+export { SearchProvider, useCurrentRefinements, useDidYouMean, 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 { SearchDialog, type SearchDialogProps } from "./dialog.js";
 export { Highlight, Snippet, excerpt, highlightParts, type HighlightProps } from "./highlight.js";
 export { messageFor } from "./messages.js";

package/dist/react/index.js

@@ -3,8 +3,8 @@
 export { FindlaneProvider, useClient } from "./client.js";
 export { useSearch } from "./use-search.js";
 export { useAutocomplete } from "./use-autocomplete.js";
-export { SearchProvider, useCurrentRefinements, useHits, useLoadMore, usePagination, useRange, useRefinementList, useSearchBox, useSearchState, useSortBy, useToggle, } from "./search-provider.js";
-export { CurrentRefinements, DefaultHit, Hits, LoadMore, RefinementList, SearchBox, SearchInput, SortSelect, Stats, } from "./components.js";
+export { SearchProvider, useCurrentRefinements, useDidYouMean, useHits, useLoadMore, usePagination, useRange, useRefinementList, useSearchBox, useSearchState, useSortBy, useToggle, } from "./search-provider.js";
+export { CurrentRefinements, DefaultHit, DidYouMean, Hits, LoadMore, RefinementList, SearchBox, SearchInput, SortSelect, Stats, } from "./components.js";
 export { SearchDialog } from "./dialog.js";
 export { Highlight, Snippet, excerpt, highlightParts } from "./highlight.js";
 export { messageFor } from "./messages.js";

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

@@ -1,4 +1,5 @@
 import { type ReactNode } from "react";
+import type { DidYouMean } from "../index.js";
 import { type ClientOptions } from "./client.js";
 import { type ServerResults, type StateChange } from "./store.js";
 import { type SearchConfig, type SearchState } from "./state.js";
@@ -45,6 +46,16 @@ export declare function useHits<T = Record<string, unknown>>(): {
     isPending: boolean;
     error: unknown;
 };
+/** 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
+ * finds results, asked for once the visitor has stopped typing for `delay` ms. `apply` searches for it.
+ * Searches carry `didYouMean` only when the setting is on, so other indexes are never asked. */
+export declare function useDidYouMean({ delay }?: {
+    delay?: number;
+}): {
+    didYouMean: DidYouMean | null;
+    apply: () => void;
+};
 /** A facet's values with their counts, most common first. Selected values stay listed (at 0 when the
  * query no longer matches them), so they can be removed. */
 export declare function useRefinementList(field: string): {

package/dist/react/search-provider.js

@@ -94,6 +94,32 @@ export function useHits() {
         error,
     };
 }
+/** 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
+ * finds results, asked for once the visitor has stopped typing for `delay` ms. `apply` searches for it.
+ * Searches carry `didYouMean` only when the setting is on, so other indexes are never asked. */
+export function useDidYouMean({ delay = 400 } = {}) {
+    const [{ results, pending }, store] = useSnapshot();
+    const [suggested, setSuggested] = useState(null);
+    const empty = Boolean(results && !pending && !results.response.total && results.request.q?.trim() &&
+        results.response.didYouMean !== undefined);
+    const key = results?.key;
+    useEffect(() => {
+        if (!empty || !results)
+            return;
+        const controller = new AbortController();
+        const timer = setTimeout(() => store.suggest(results.request, controller.signal)
+            .then((didYouMean) => setSuggested({ key: results.key, didYouMean }), () => undefined), delay);
+        return () => { clearTimeout(timer); controller.abort(); };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [store, key, empty, delay]);
+    const didYouMean = results?.response.didYouMean ?? (empty && suggested?.key === key ? suggested.didYouMean : null);
+    return {
+        didYouMean,
+        apply: () => { if (didYouMean)
+            store.update((current) => ({ ...current, q: didYouMean.q, page: 0 })); },
+    };
+}
 /** A facet's values with their counts, most common first. Selected values stay listed (at 0 when the
  * query no longer matches them), so they can be removed. */
 export function useRefinementList(field) {

package/dist/react/store.d.ts

@@ -1,4 +1,4 @@
-import type { SearchBrowserClient, SearchRequest, SearchResponse } from "../index.js";
+import type { DidYouMean, SearchBrowserClient, SearchRequest, SearchResponse } from "../index.js";
 import { type Hit, type SearchConfig, type SearchState } from "./state.js";
 /** Results computed on the server (see ssr.ts), so the first render needn't search again. */
 export type ServerResults<T = unknown> = {
@@ -60,6 +60,8 @@ export declare class SearchStore<T = unknown> {
     stop(): void;
     private resultsFor;
     private search;
+    /** A did-you-mean suggestion for a request that found nothing. */
+    suggest(request: SearchRequest, signal: AbortSignal): Promise<DidYouMean | null>;
     /** Adds the next page's hits to the current ones. */
     loadMore(): void;
 }

package/dist/react/store.js

@@ -107,6 +107,10 @@ export class SearchStore {
         else
             go();
     }
+    /** A did-you-mean suggestion for a request that found nothing. */
+    suggest(request, signal) {
+        return this.client.suggest(request, { signal });
+    }
     /** Adds the next page's hits to the current ones. */
     loadMore() {
         const { results, loadingMore, pending } = this.snapshot;

package/dist/react/styles.css

@@ -239,6 +239,21 @@
   cursor: pointer;
 }
 
+:where([data-findlane-did-you-mean]) {
+  margin: 0;
+  color: var(--findlane-muted, color-mix(in srgb, currentColor 60%, transparent));
+}
+:where([data-findlane-did-you-mean]) :where(button) {
+  padding: 0;
+  font: inherit;
+  font-weight: 600;
+  color: var(--findlane-accent, #2f5bff);
+  background: none;
+  border: 0;
+  text-decoration: underline;
+  cursor: pointer;
+}
+
 :where([data-findlane-stats]) {
   margin: 0;
   color: var(--findlane-muted, color-mix(in srgb, currentColor 60%, transparent));

package/package.json

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