@findlane/browser 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -8,6 +8,9 @@ export type SearchRequest = {
     /** Facets (also in `facets`) counted without the filter on their own field, so a list of choices
      * keeps its other values, with counts, after one is chosen. */
     disjunctiveFacets?: string[];
+    /** Number fields (up to eight) whose smallest and largest values across the matches to return in
+     * `facetStats`, such as a price slider's bounds. Each field's own filter is left out. */
+    facetStats?: string[];
     /** Hits per request: 1–50 (default 20). */
     limit?: number;
     /** Up to 1,000. */
@@ -37,8 +40,28 @@ export type SearchResponse<T> = {
     totalRelation?: "eq" | "gte";
     hasMore?: boolean;
     facets: Record<string, Record<string, number>>;
+    /** With `facetStats`: each field's smallest and largest value across the matches, without the field's
+     * own filter. A field no match has is left out. */
+    facetStats?: Record<string, {
+        min: number;
+        max: 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 +79,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/cache.js

@@ -12,7 +12,7 @@ export function searchKey(request) {
     for (const [key, value] of Object.entries(defaults))
         if (normal[key] === value)
             delete normal[key];
-    for (const key of ["facets", "disjunctiveFacets"]) {
+    for (const key of ["facets", "disjunctiveFacets", "facetStats"]) {
         const list = normal[key];
         if (Array.isArray(list))
             normal[key] = list.length ? [...list].sort() : undefined;

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): {
@@ -61,9 +72,13 @@ export type Range = {
     gte?: number | string;
     lte?: number | string;
 };
-/** A number or date range filter. List the field in `filterFields` to keep it in the URL. */
+/** A number or date range filter. List the field in `filterFields` to keep it in the URL, and in
+ * `facetStats` for `min` and `max`: the smallest and largest values across the matches, without
+ * this range, such as a slider's bounds. */
 export declare function useRange(field: string): {
     range: Range | undefined;
+    min: number | undefined;
+    max: number | undefined;
     /** Leave a bound out (or empty) for no limit on that side. */
     setRange: (range: Range | undefined) => void;
     clear: () => void;

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) {
@@ -116,12 +142,17 @@ export function useRefinementList(field) {
         clear: () => store.update(withRefinement(field, [])),
     };
 }
-/** A number or date range filter. List the field in `filterFields` to keep it in the URL. */
+/** A number or date range filter. List the field in `filterFields` to keep it in the URL, and in
+ * `facetStats` for `min` and `max`: the smallest and largest values across the matches, without
+ * this range, such as a slider's bounds. */
 export function useRange(field) {
-    const [{ state }, store] = useSnapshot();
+    const [{ state, results }, store] = useSnapshot();
     const value = state.filters[field];
+    const stats = results?.response.facetStats?.[field];
     return {
         range: isRange(value) ? value : undefined,
+        min: stats?.min,
+        max: stats?.max,
         /** Leave a bound out (or empty) for no limit on that side. */
         setRange: (range) => {
             const bounds = Object.entries(range ?? {}).filter(([, bound]) => bound !== undefined && bound !== "");

package/dist/react/state.d.ts

@@ -18,6 +18,9 @@ export type SearchConfig = {
     facets?: string[];
     /** Fields that useRange and useToggle filter, so the URL can carry them. */
     filterFields?: string[];
+    /** Number fields whose smallest and largest values across the matches useRange returns as `min`
+     * and `max`, such as a price slider's bounds. */
+    facetStats?: string[];
     /** Filters always applied, such as `{ published: true }`. They aren't shown as refinements. */
     filters?: Record<string, unknown>;
     /** Hits per page: 1–50 (default 20). */

package/dist/react/state.js

@@ -19,6 +19,7 @@ export function planSearch(config, state) {
         ...(Object.keys(filters).length ? { filters } : {}),
         ...(facets.length ? { facets } : {}),
         ...(disjunctive.length ? { disjunctiveFacets: disjunctive } : {}),
+        ...(config.facetStats?.length ? { facetStats: config.facetStats } : {}),
         limit: pageSize,
         ...(state.page > 0 ? { offset: Math.min(state.page * pageSize, maxOffset) } : {}),
         ...(config.fields ? { attributesToRetrieve: config.fields } : {}),

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,12 +107,16 @@ 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;
         if (!results?.hasMore || loadingMore || pending)
             return;
-        const { facets: _, disjunctiveFacets: __, facetMode: ___, ...request } = results.request;
+        const { facets: _, disjunctiveFacets: __, facetMode: ___, facetStats: ____, ...request } = results.request;
         const offset = (request.offset ?? 0) + results.hits.length;
         const run = this.run;
         this.set({ loadingMore: true });

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.4.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",