@findlane/browser 0.16.1 → 0.18.0

package/dist/index.d.ts

@@ -46,6 +46,11 @@ export type SearchRequest = {
     /** Only records inside a box, in degrees, such as a map's visible area. West greater than east crosses the
      * antimeridian. */
     within?: GeoBox;
+    /** With the index's related results on: false asks for none (0.17.0). */
+    related?: boolean;
+    /** With the index's `distinct` setting, which shows each product once, such as one of its colours: false
+     * shows every record, a number 1 to 4 how many of each group's records. */
+    distinct?: boolean | number;
 };
 /** A point in degrees: lat from -90 to 90, lng from -180 to 180. */
 export type GeoPoint = {
@@ -59,17 +64,34 @@ export type GeoBox = {
     east: number;
     west: number;
 };
+/** A result. */
+export type SearchHit<T> = {
+    id: string;
+    score: number | null;
+    record: T;
+    /** With `near`: meters from the point. */
+    distance?: number;
+    /** With `highlight`: matched searchable fields by path; list fields give one string per value. */
+    highlights?: Record<string, string | string[]>;
+    /** With the index's `distinct` setting: the hit's group (its value of the group field, null for a record
+     * without one) and how many of the group's records matched. */
+    group?: {
+        value: string | number | null;
+        matched: number;
+    };
+    /** With the index's `variants` setting: which item of the record's variants list the search matched, by
+     * its words or by filters on the variants' fields, such as the flavour a shopper typed. Absent when none
+     * stands out. */
+    variant?: {
+        index: number;
+    };
+};
 export type SearchResponse<T> = {
-    hits: {
-        id: string;
-        score: number | null;
-        record: T;
-        /** With `near`: meters from the point. */
-        distance?: number;
-        /** With `highlight`: matched searchable fields by path; list fields give one string per value. */
-        highlights?: Record<string, string | string[]>;
-    }[];
+    hits: SearchHit<T>[];
+    /** The matches; with the index's `distinct` setting, the groups. */
     total: number;
+    /** With `distinct`: the matching records, which `total` counts as groups. */
+    totalRecords?: number;
     /** "gte" when `total` is a lower bound (page count mode). */
     totalRelation?: "eq" | "gte";
     hasMore?: boolean;
@@ -95,6 +117,13 @@ export type SearchResponse<T> = {
     appliedRules?: AppliedRule[];
     /** When a rule replaced words: the query that was searched. */
     rewrittenQuery?: string;
+    /** With the index's related results on (0.17.0): when the query's words found nothing (`hits` empty, `total`
+     * 0), the products closest to it in meaning, best first, with their similarity as `score`. Show them under
+     * a heading of their own, such as "No exact matches. Related products". */
+    related?: {
+        hits: SearchHit<T>[];
+        total: number;
+    };
 };
 /** A query rule a search fired, with its `userData`, if it has any. */
 export type AppliedRule = {
@@ -227,7 +256,7 @@ export type EventItem = {
 export type ClickDetails = {
     position?: number;
     query?: string;
-    list?: "goesWith" | "similar" | "together";
+    list?: "goesWith" | "similar" | "together" | "related";
     from?: string;
 };
 /** Events from the page, sent in the background: a batch a second, and what's left when the page is

package/dist/react/components.d.ts

@@ -56,6 +56,9 @@ export type HitsProps<T> = {
     render?: (hit: Hit<T>, index: number) => ReactNode;
     /** Shown when nothing matches (default "No results for “…”"). */
     empty?: (query: string) => ReactNode;
+    /** The heading over related results, shown when nothing matched but the index's related results found
+     * products close in meaning (default "No exact matches. Related products"). */
+    relatedTitle?: (query: string) => ReactNode;
     /** Shown before the first results arrive. */
     loading?: ReactNode;
     className?: string;
@@ -63,7 +66,7 @@ export type HitsProps<T> = {
 /** Whether a click was on a link inside the element that handled it, such as a hit's link. */
 export declare function onLink(event: MouseEvent<HTMLElement>): boolean;
 /** The results. Following a link in a hit sends a click event, with its place and the query. */
-export declare function Hits<T = Record<string, unknown>>({ render, empty, loading, className }: HitsProps<T>): import("react").JSX.Element;
+export declare function Hits<T = Record<string, unknown>>({ render, empty, relatedTitle, loading, className }: HitsProps<T>): import("react").JSX.Element;
 export type RefinementListProps = {
     field: string;
     /** The heading (default the field). */

package/dist/react/components.js

@@ -74,22 +74,27 @@ export function onLink(event) {
     return Boolean(link && event.currentTarget.contains(link));
 }
 /** The results. Following a link in a hit sends a click event, with its place and the query. */
-export function Hits({ render, empty, loading = null, className }) {
-    const { hits, isLoaded, isPending, error, click } = useHits();
+export function Hits({ render, empty, relatedTitle, loading = null, className }) {
+    const { hits, related, isLoaded, isPending, error, click } = useHits();
     const { query } = useSearchBox();
     if (error && !isLoaded)
         return _jsx("p", { "data-findlane-note": "", children: messageFor(error) });
     if (!isLoaded)
         return _jsx(_Fragment, { children: loading });
-    if (!hits.length)
+    if (!hits.length && !related.length)
         return _jsx("p", { "data-findlane-empty": "", children: empty ? empty(query) : query ? _jsxs(_Fragment, { children: ["No results for \u201C", query, "\u201D"] }) : "No results" });
-    return (_jsx("ol", { className: className, "data-findlane-hits": "", "data-pending": isPending || undefined, children: hits.map((hit, index) => {
+    // Nothing matched, but related results found products close in meaning: those, under their own heading.
+    const shown = hits.length ? hits : related;
+    const list = (_jsx("ol", { className: className, "data-findlane-hits": "", "data-findlane-related": !hits.length || undefined, "data-pending": isPending || undefined, children: shown.map((hit, index) => {
             // A click, and a middle click that opens the link in a new tab.
             const clicked = (event) => { if (!event.defaultPrevented && onLink(event))
                 click(hit); };
             return (_jsx("li", { onClick: clicked, onAuxClick: (event) => { if (event.button === 1)
                     clicked(event); }, children: render ? render(hit, index) : _jsx(DefaultHit, { hit: hit }) }, hit.id));
         }) }));
+    if (hits.length)
+        return list;
+    return (_jsxs(_Fragment, { children: [_jsx("p", { "data-findlane-related-title": "", children: relatedTitle ? relatedTitle(query) : "No exact matches. Related products" }), list] }));
 }
 /** Checkboxes for a facet's values, with counts. */
 export function RefinementList({ field, label, limit = 8, format, className }) {

package/dist/react/highlight.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { Fragment } from "react";
-// The API escapes highlighted values (dashboard/search-terms.ts) and wraps matched words in
+// The API escapes highlighted values (the engine's, engine/src/present.rs) and wraps matched words in
 // <mark>. Splitting on the tags and decoding the five escapes gives text React can render, so
 // nothing is inserted as HTML.
 const escapes = { "&amp;": "&", "&lt;": "<", "&gt;": ">", "&quot;": '"', "&#39;": "'" };

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

@@ -35,6 +35,8 @@ export declare function useSearchBox(): {
 export declare function useHits<T = Record<string, unknown>>(): {
     hits: import("./state.js").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>[];
     /** "gte" when `total` is a lower bound (with `countMode: "page"`). */
     totalRelation: "eq" | "gte";
     response: import("../index.js").SearchResponse<T> | null;

package/dist/react/search-provider.js

@@ -82,6 +82,8 @@ export function useHits() {
     return {
         hits: results?.hits ?? [],
         total: results?.response.total ?? 0,
+        /** With the index's related results on, when nothing matched: the products closest in meaning. */
+        related: results?.response.related?.hits ?? [],
         /** "gte" when `total` is a lower bound (with `countMode: "page"`). */
         totalRelation: results?.response.totalRelation ?? "eq",
         response: results?.response ?? null,

package/dist/react/store.d.ts

@@ -62,7 +62,8 @@ export declare class SearchStore<T = unknown> {
     get settings(): SearchConfig;
     /** Opens the connection to the API before the first search needs it (the client's warm). */
     warm(): void;
-    /** Sends a click on a result: its place in the results, from 1, and the query they're for. */
+    /** Sends a click on a result: its place in the results, from 1, and the query they're for. A related
+     * result's click says so (list "related"), with its place among them. */
     click(objectID: string): void;
     /** Searches unless the results already answer the current state; with a state, such as the
      * URL's, adopts it first. */

package/dist/react/store.js

@@ -67,12 +67,15 @@ export class SearchStore {
     get settings() { return this.config; }
     /** Opens the connection to the API before the first search needs it (the client's warm). */
     warm() { this.client.warm(); }
-    /** Sends a click on a result: its place in the results, from 1, and the query they're for. */
+    /** Sends a click on a result: its place in the results, from 1, and the query they're for. A related
+     * result's click says so (list "related"), with its place among them. */
     click(objectID) {
         const results = this.snapshot.results;
         const index = results ? results.hits.findIndex((hit) => hit.id === objectID) : -1;
+        const related = index < 0 && results ? (results.response.related?.hits ?? []).findIndex((hit) => hit.id === objectID) : -1;
         this.client.events.click(objectID, { query: results?.request.q ?? "",
-            ...(index >= 0 ? { position: (results.request.offset ?? 0) + index + 1 } : {}) });
+            ...(index >= 0 ? { position: (results.request.offset ?? 0) + index + 1 } : {}),
+            ...(related >= 0 ? { position: related + 1, list: "related" } : {}) });
     }
     /** Searches unless the results already answer the current state; with a state, such as the
      * URL's, adopts it first. */

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

@@ -63,13 +63,7 @@ export declare function fillTemplate<T>(template: string, hit: Hit<T>): string |
 export declare function useAutocomplete<T = Record<string, unknown>>(options?: AutocompleteOptions<T>): {
     query: string;
     setQuery: (value: string) => void;
-    hits: {
-        id: string;
-        score: number | null;
-        record: T;
-        distance?: number;
-        highlights?: Record<string, string | string[]>;
-    }[];
+    hits: import("../index.js").SearchHit<T>[];
     total: number;
     response: import("../index.js").SearchResponse<T> | null;
     error: unknown;

package/package.json

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