@findlane/browser 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -110,14 +110,23 @@ export type RecommendationHit<T> = {
     score: number | null;
     record: T;
 };
+/** A Bought together pick: `count` is the orders in the last year that had both products. */
+export type TogetherHit<T> = RecommendationHit<T> & {
+    count: number;
+};
 export type RecommendationsResponse<T> = {
     objectID: string;
-    /** false until the product's lists are built; both lists are empty meanwhile. */
+    /** false until the product's lists are built; the lists are empty meanwhile. */
     ready: boolean;
     /** Products a shopper would want with this one, the likeliest first; `score` is the decision model's probability. */
     goesWith: RecommendationHit<T>[];
     /** Products a shopper could choose instead, then (unless the index hides them) variants of this one. */
     similar: RecommendationHit<T>[];
+    /** Products bought in the same orders as this one, the most orders first, from the orders the store
+     * sends as events. Empty without orders. */
+    together?: TogetherHit<T>[];
+    /** What `together`'s counts are of. */
+    togetherBasis?: "orders";
 };
 export declare class FindlaneError extends Error {
     status: number;

package/dist/react/components.d.ts

@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import { type MouseEvent, 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";
@@ -48,6 +48,9 @@ export type HitsProps<T> = {
     loading?: ReactNode;
     className?: string;
 };
+/** 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 type RefinementListProps = {
     field: string;

package/dist/react/components.js

@@ -38,8 +38,14 @@ export function SearchInput({ placeholder, label = "Search", className, autoFocu
     const { query, setQuery } = useSearchBox();
     return (_jsx("form", { role: "search", className: className, "data-findlane-search-input": "", onSubmit: (event) => event.preventDefault(), children: _jsx("input", { type: "search", value: query, onChange: (event) => setQuery(event.target.value), placeholder: placeholder, "aria-label": label, autoFocus: autoFocus, autoComplete: "off", spellCheck: false, maxLength: 200 }) }));
 }
+/** Whether a click was on a link inside the element that handled it, such as a hit's link. */
+export function onLink(event) {
+    const link = event.target.closest?.("a[href]");
+    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 } = useHits();
+    const { hits, isLoaded, isPending, error, click } = useHits();
     const { query } = useSearchBox();
     if (error && !isLoaded)
         return _jsx("p", { "data-findlane-note": "", children: messageFor(error) });
@@ -47,7 +53,13 @@ export function Hits({ render, empty, loading = null, className }) {
         return _jsx(_Fragment, { children: loading });
     if (!hits.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) => (_jsx("li", { children: render ? render(hit, index) : _jsx(DefaultHit, { hit: hit }) }, hit.id))) }));
+    return (_jsx("ol", { className: className, "data-findlane-hits": "", "data-pending": isPending || undefined, children: hits.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));
+        }) }));
 }
 /** Checkboxes for a facet's values, with counts. */
 export function RefinementList({ field, label, limit = 8, format, className }) {

package/dist/react/recommendations.d.ts

@@ -1,21 +1,36 @@
 import type { ReactNode } from "react";
 import type { RecommendationsRequest } from "../index.js";
-import type { ClientOptions } from "./client.js";
+import { type ClientOptions } from "./client.js";
 import type { Hit } from "./state.js";
+type List = "goesWith" | "similar" | "together";
 export type RecommendationsProps<T> = ClientOptions & RecommendationsRequest & {
     /** The product whose recommendations to show. */
     objectID: string;
-    /** Products that go with it (the default), or similar products. */
-    list?: "goesWith" | "similar";
-    /** The heading (default "Goes well with" or "Similar products"); null for none. */
+    /** Products that go with it (the default), similar products, or products bought in the same orders
+     * ("together", from the orders the store sends as events). */
+    list?: List;
+    /** Another list that fills a short one, from the same response: `list="together" fill="goesWith"`
+     * gives a product with few orders a full list too. */
+    fill?: "goesWith" | "similar";
+    /** The heading; null for none. By default the list's: "Goes well with", "Similar products", or
+     * "Frequently bought together" when most products shown come from orders (otherwise the fill list's). */
     title?: ReactNode;
     /** A product's content; DefaultHit shows an image and a title. */
     render?: (hit: Hit<T>, index: number) => ReactNode;
+    /** A product's page: each product (DefaultHit, or what `render` gives) becomes a link to it. Leave it
+     * out when `render` has its own link. */
+    getHref?: (hit: Hit<T>) => string | undefined;
+    /** A product'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 product's ID. */
+    hrefTemplate?: string;
     /** Shown while the lists load. */
     loading?: ReactNode;
     className?: string;
 };
 /** One of a product's recommendation lists (the recommendations add-on). It renders nothing while the
- * product has none, so a product page can always include it. A Goes with and a Similar list for the
- * same product share one request. */
-export declare function Recommendations<T = Record<string, unknown>>({ objectID, list, title, render, loading, className, ...options }: RecommendationsProps<T>): import("react").JSX.Element | null;
+ * product has none, so a product page can always include it. Lists for the same product share one
+ * request. Each product says which list it came from, in data-findlane-source. Following a link in a
+ * product sends a click event with its list, place, and the product the list is for (the client's
+ * `events` option turns them off, or holds them until consent). */
+export declare function Recommendations<T = Record<string, unknown>>({ objectID, list, fill, title, render, getHref, hrefTemplate, loading, className, ...options }: RecommendationsProps<T>): import("react").JSX.Element | null;
+export {};

package/dist/react/recommendations.js

@@ -1,17 +1,39 @@
 "use client";
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { DefaultHit } from "./components.js";
+import { useClient } from "./client.js";
+import { DefaultHit, onLink } from "./components.js";
+import { fillTemplate } from "./use-autocomplete.js";
 import { useRecommendations } from "./use-recommendations.js";
+const headings = { goesWith: "Goes well with", similar: "Similar products", together: "Frequently bought together" };
 /** One of a product's recommendation lists (the recommendations add-on). It renders nothing while the
- * product has none, so a product page can always include it. A Goes with and a Similar list for the
- * same product share one request. */
-export function Recommendations({ objectID, list = "goesWith", title, render, loading = null, className, ...options }) {
+ * product has none, so a product page can always include it. Lists for the same product share one
+ * request. Each product says which list it came from, in data-findlane-source. Following a link in a
+ * product sends a click event with its list, place, and the product the list is for (the client's
+ * `events` option turns them off, or holds them until consent). */
+export function Recommendations({ objectID, list = "goesWith", fill, title, render, getHref, hrefTemplate, loading = null, className, ...options }) {
     const { data, isPending } = useRecommendations(objectID, options);
+    const client = useClient({ client: options.client, publicId: options.publicId, baseUrl: options.baseUrl });
     if (!data)
         return isPending ? _jsx(_Fragment, { children: loading }) : null;
-    const hits = data[list];
-    if (!hits.length)
+    const limit = options.limit ?? 8;
+    const own = (data[list] ?? []).slice(0, limit).map((hit) => ({ hit, source: list }));
+    const taken = new Set([objectID, ...own.map((item) => item.hit.id)]);
+    const extra = fill && fill !== list ? (data[fill] ?? []).filter((hit) => !taken.has(hit.id))
+        .slice(0, limit - own.length).map((hit) => ({ hit, source: fill })) : [];
+    const items = [...own, ...extra];
+    if (!items.length)
         return null;
-    const heading = title === undefined ? (list === "goesWith" ? "Goes well with" : "Similar products") : title;
-    return (_jsxs("section", { className: className, "data-findlane-recommendations": list, children: [heading !== null && _jsx("h2", { "data-findlane-recommendations-title": "", children: heading }), _jsx("ol", { "data-findlane-hits": "", children: hits.map((hit, index) => _jsx("li", { children: render ? render(hit, index) : _jsx(DefaultHit, { hit: hit }) }, hit.id)) })] }));
+    // A heading that says what most of the list is.
+    const heading = title === undefined ? headings[fill && own.length * 2 < items.length ? fill : list] : title;
+    return (_jsxs("section", { className: className, "data-findlane-recommendations": list, children: [heading !== null && _jsx("h2", { "data-findlane-recommendations-title": "", children: heading }), _jsx("ol", { "data-findlane-hits": "", children: items.map(({ hit, source }, index) => {
+                    const href = getHref ? getHref(hit) : hrefTemplate ? fillTemplate(hrefTemplate, hit) : undefined;
+                    const content = render ? render(hit, index) : _jsx(DefaultHit, { hit: hit });
+                    // A click, and a middle click that opens the link in a new tab.
+                    const clicked = (event) => {
+                        if (!event.defaultPrevented && onLink(event))
+                            client.events.click(hit.id, { list: source, from: objectID, position: index + 1 });
+                    };
+                    return (_jsx("li", { "data-findlane-source": source, onClick: clicked, onAuxClick: (event) => { if (event.button === 1)
+                            clicked(event); }, children: href ? _jsx("a", { href: href, "data-findlane-link": "", children: content }) : content }, hit.id));
+                }) })] }));
 }

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

@@ -45,6 +45,11 @@ export declare function useHits<T = Record<string, unknown>>(): {
     isLoaded: boolean;
     isPending: boolean;
     error: unknown;
+    /** Sends a click event for a hit, with its place and the query, for click-through in Analytics.
+     * Hits does it for links in a hit; call it from a hit rendered without a link. */
+    click: (hit: {
+        id: string;
+    }) => void;
 };
 /** 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

package/dist/react/search-provider.js

@@ -76,7 +76,7 @@ export function useSearchBox() {
     return { query: state.q, setQuery, clear: () => setQuery(""), isPending: pending };
 }
 export function useHits() {
-    const [{ results, pending, error }] = useSnapshot();
+    const [{ results, pending, error }, store] = useSnapshot();
     return {
         hits: results?.hits ?? [],
         total: results?.response.total ?? 0,
@@ -92,6 +92,9 @@ export function useHits() {
         isLoaded: results !== null,
         isPending: pending,
         error,
+        /** Sends a click event for a hit, with its place and the query, for click-through in Analytics.
+         * Hits does it for links in a hit; call it from a hit rendered without a link. */
+        click: (hit) => store.click(hit.id),
     };
 }
 /** Did you mean, with the index's didYouMean setting: the query the results are for when typo tolerance

package/dist/react/store.d.ts

@@ -55,6 +55,8 @@ export declare class SearchStore<T = unknown> {
     /** A new client or config, from changed props. */
     configure(client: SearchBrowserClient, config: SearchConfig): void;
     get settings(): SearchConfig;
+    /** Sends a click on a result: its place in the results, from 1, and the query they're for. */
+    click(objectID: string): void;
     /** Searches unless the results already answer the current state; with a state, such as the
      * URL's, adopts it first. */
     start(state?: SearchState): void;

package/dist/react/store.js

@@ -58,6 +58,13 @@ export class SearchStore {
         this.search(false);
     }
     get settings() { return this.config; }
+    /** Sends a click on a result: its place in the results, from 1, and the query they're for. */
+    click(objectID) {
+        const results = this.snapshot.results;
+        const index = results ? results.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 } : {}) });
+    }
     /** Searches unless the results already answer the current state; with a state, such as the
      * URL's, adopts it first. */
     start(state) {

package/dist/react/styles.css

@@ -163,11 +163,19 @@
 :where([data-findlane-recommendations] [data-findlane-hits]) {
   grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
 }
-:where([data-findlane-recommendations] [data-findlane-hits] > li) {
+:where([data-findlane-recommendations] [data-findlane-hits] > li),
+:where([data-findlane-recommendations] [data-findlane-link]) {
   display: grid;
   gap: 6px;
   align-content: start;
 }
+:where([data-findlane-recommendations] [data-findlane-link]) {
+  color: inherit;
+  text-decoration: none;
+}
+:where([data-findlane-recommendations] [data-findlane-link]:hover [data-findlane-title]) {
+  text-decoration: underline;
+}
 :where([data-findlane-recommendations] [data-findlane-image]) {
   width: 100%;
   height: auto;

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

@@ -1,6 +1,6 @@
 import { type HTMLAttributes, type InputHTMLAttributes } from "react";
 import type { Hit } from "./state.js";
-import type { ClientOptions } from "./client.js";
+import { type ClientOptions } from "./client.js";
 export type AutocompleteOptions<T> = ClientOptions & {
     /** Suggestions to show: 1–50 (default 6). */
     limit?: number;
@@ -28,7 +28,9 @@ export type AutocompleteOptions<T> = ClientOptions & {
 /** 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. */
+ * 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). */
 export declare function useAutocomplete<T = Record<string, unknown>>(options?: AutocompleteOptions<T>): {
     query: string;
     setQuery: (value: string) => void;

package/dist/react/use-autocomplete.js

@@ -2,6 +2,7 @@
 import { useEffect, useId, useState, } from "react";
 import { valuesAt } from "./highlight.js";
 import { useSearch } from "./use-search.js";
+import { useClient } from "./client.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,7 +11,9 @@ export function fillTemplate(template, hit) {
     return /^[a-z][a-z\d+.-]*:/i.test(href.trim()) && !/^https?:/i.test(href.trim()) ? undefined : href || 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. */
+ * 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). */
 export function useAutocomplete(options = {}) {
     const { limit = 6, fields, filters, sort, minLength = 1, debounceMs, hrefTemplate, onSelect, onSubmit } = options;
     const getHref = options.getHref ?? (hrefTemplate ? (hit) => fillTemplate(hrefTemplate, hit) : undefined);
@@ -33,6 +36,7 @@ export function useAutocomplete(options = {}) {
     const search = useSearch(request, {
         publicId: options.publicId, baseUrl: options.baseUrl, client: options.client, debounceMs,
     });
+    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);
@@ -49,7 +53,12 @@ export function useAutocomplete(options = {}) {
         setDismissed(true);
         setActiveIndex(-1);
     };
+    const clicked = (hit) => {
+        const index = hits.indexOf(hit);
+        client.events.click(hit.id, { query, ...(index >= 0 ? { position: index + 1 } : {}) });
+    };
     const select = (hit) => {
+        clicked(hit);
         close();
         if (onSelect)
             return onSelect(hit);
@@ -158,16 +167,20 @@ export function useAutocomplete(options = {}) {
             onClick: (event) => {
                 props.onClick?.(event);
                 const hit = hits[index];
-                // A link opened in a new tab or window is left to the browser.
-                if (event.defaultPrevented || !hit || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+                if (event.defaultPrevented || !hit)
                     return;
+                // 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);
                 // A link without onSelect is followed as usual.
                 if (onSelect || !event.currentTarget.href) {
                     event.preventDefault();
                     select(hit);
                 }
-                else
+                else {
+                    clicked(hit);
                     close();
+                }
             },
         }),
     };

package/package.json

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