@findlane/browser 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @findlane/browser
 
-The Findlane browser SDK: fast, typo-tolerant search from the browser with an index's public ID. No dependencies, about 1 KB.
+The Findlane browser SDK: fast, typo-tolerant search from the browser with an index's public ID. No dependencies, about 1 KB, plus optional React hooks and components.
 
 Docs: https://findlane.dev/docs/browser-sdk
 
@@ -31,6 +31,19 @@ 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.
 
+## 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.
+
+```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" />
+```
+
+`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. Docs: https://findlane.dev/docs/react
+
 ## Search requests
 
 | Option | |
@@ -38,6 +51,7 @@ Each index has a copyable public ID in the dashboard. An owner must save allowed
 | `q` | The query. Words match with typos and as prefixes, depending on the index's settings. |
 | `filters` | Field values to keep: a value, `{ in: [...] }`, or a range `{ gte, lte }` for numbers and dates. |
 | `facets` | Fields to count values for, such as `["brand.name"]`. |
+| `disjunctiveFacets` | Facets counted without the filter on their own field, so a list of checkboxes keeps its other values. |
 | `sort` | A sort ID from the index settings, or `"relevance"`. |
 | `limit`, `offset` | Paging: up to 50 hits a request, and offsets up to 1,000. |
 | `countMode`, `facetMode` | `"page"` (the default, fastest) or `"exact"` for totals and facet counts across every match. |

package/dist/index.d.ts

@@ -5,6 +5,9 @@ export type SearchRequest = {
     /** Field values to keep: a value, `{ in: [...] }`, or a range `{ gte, lte }` for numbers and dates. */
     filters?: Record<string, unknown>;
     facets?: string[];
+    /** 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[];
     /** Hits per request: 1–50 (default 20). */
     limit?: number;
     /** Up to 1,000. */

package/dist/index.js

@@ -1,38 +1,32 @@
-// src/index.ts
-class FindlaneError extends Error {
-  status;
-  constructor(status, message) {
-    super(message);
-    this.status = status;
-    this.name = "FindlaneError";
-  }
+export class FindlaneError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "FindlaneError";
+    }
 }
-var defaultBaseUrl = "https://api.findlane.dev";
-
-class SearchBrowserClient {
-  url;
-  fetcher;
-  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.fetcher = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
-  }
-  async search(request, options = {}) {
-    const response = await this.fetcher(this.url, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(request),
-      signal: options.signal
-    });
-    const data = await response.json();
-    if (!response.ok)
-      throw new FindlaneError(response.status, data.error ?? `HTTP ${response.status}`);
-    return data;
-  }
+/** The hosted Findlane API, used unless `baseUrl` says otherwise. */
+export const defaultBaseUrl = "https://api.findlane.dev";
+export class SearchBrowserClient {
+    url;
+    fetcher;
+    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.fetcher = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    }
+    async search(request, options = {}) {
+        const response = await this.fetcher(this.url, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(request),
+            signal: options.signal,
+        });
+        const data = await response.json();
+        if (!response.ok)
+            throw new FindlaneError(response.status, data.error ?? `HTTP ${response.status}`);
+        return data;
+    }
 }
-export {
-  FindlaneError,
-  SearchBrowserClient,
-  defaultBaseUrl
-};

package/dist/react/cache.d.ts

@@ -0,0 +1,7 @@
+import type { 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 cached response, if there's a recent one. */
+export declare function peek<T>(client: SearchBrowserClient, request: SearchRequest): SearchResponse<T> | null;
+export declare function cachedSearch<T>(client: SearchBrowserClient, request: SearchRequest, signal?: AbortSignal): Promise<SearchResponse<T>>;

package/dist/react/cache.js

@@ -0,0 +1,42 @@
+import { canonical } from "./state.js";
+const size = 50;
+const maxAge = 5 * 60_000;
+const caches = new WeakMap();
+/** 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) {
+    const normal = { ...request };
+    if (typeof normal.q === "string" && normal.q.length <= 200)
+        normal.q = normal.q.toLowerCase().match(/[\p{L}\p{N}]+/gu)?.slice(0, 8).join(" ") ?? "";
+    const defaults = { q: "", limit: 20, offset: 0, countMode: "page", facetMode: "page" };
+    for (const [key, value] of Object.entries(defaults))
+        if (normal[key] === value)
+            delete normal[key];
+    for (const key of ["facets", "disjunctiveFacets"]) {
+        const list = normal[key];
+        if (Array.isArray(list))
+            normal[key] = list.length ? [...list].sort() : undefined;
+    }
+    return canonical(normal);
+}
+/** A cached response, if there's a recent one. */
+export function peek(client, request) {
+    const entry = caches.get(client)?.get(searchKey(request));
+    return entry && Date.now() - entry.at < maxAge ? entry.response : null;
+}
+export async function cachedSearch(client, request, signal) {
+    const found = peek(client, request);
+    if (found)
+        return found;
+    const response = await client.search(request, { signal });
+    let cache = caches.get(client);
+    if (!cache)
+        caches.set(client, (cache = new Map()));
+    const key = searchKey(request);
+    cache.delete(key);
+    cache.set(key, { at: Date.now(), response });
+    // A Map keeps insertion order, so the first key is the oldest.
+    if (cache.size > size)
+        cache.delete(cache.keys().next().value);
+    return response;
+}

package/dist/react/client.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from "react";
+import { SearchBrowserClient } from "../index.js";
+/** Where to search: a public ID (with an optional `baseUrl`), or a client you made. Leave both out
+ * inside a FindlaneProvider. */
+export type ClientOptions = {
+    publicId?: string;
+    baseUrl?: string;
+    client?: SearchBrowserClient;
+};
+/** Sets the index once for the hooks and components inside it. */
+export declare function FindlaneProvider({ children, ...options }: ClientOptions & {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useClient(options?: ClientOptions): SearchBrowserClient;

package/dist/react/client.js

@@ -0,0 +1,23 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { SearchBrowserClient } from "../index.js";
+const ClientContext = createContext(null);
+function useOwnClient({ publicId, baseUrl, client }) {
+    return useMemo(() => client ?? (publicId ? new SearchBrowserClient({ publicId, baseUrl }) : null), [client, publicId, baseUrl]);
+}
+/** Sets the index once for the hooks and components inside it. */
+export function FindlaneProvider({ children, ...options }) {
+    const client = useOwnClient(options);
+    if (!client)
+        throw new Error("FindlaneProvider needs a publicId or a client");
+    return _jsx(ClientContext.Provider, { value: client, children: children });
+}
+export function useClient(options = {}) {
+    const own = useOwnClient(options);
+    const provided = useContext(ClientContext);
+    const client = own ?? provided;
+    if (!client)
+        throw new Error("Pass a publicId, or put this inside a FindlaneProvider");
+    return client;
+}

package/dist/react/components.d.ts

@@ -0,0 +1,87 @@
+import { type ReactNode } from "react";
+import { type Refinement } from "./search-provider.js";
+import type { Hit } from "./state.js";
+import { useAutocomplete, type AutocompleteOptions } from "./use-autocomplete.js";
+/** A hit's image and title, for records with `image` and `title` (or `name`) fields. */
+export declare function DefaultHit<T>({ hit }: {
+    hit: Hit<T>;
+}): import("react").JSX.Element;
+export type SearchBoxProps<T> = AutocompleteOptions<T> & {
+    placeholder?: string;
+    /** The input's accessible name (default "Search"). */
+    label?: string;
+    /** A results page, such as "/search". Enter goes to it with `?q=`, and the list links to it. */
+    action?: string;
+    /** A suggestion's content; DefaultHit shows an image and a title. */
+    renderHit?: (hit: Hit<T>) => ReactNode;
+    /** Shown when nothing matches (default "No results for “…”"). */
+    empty?: (query: string) => ReactNode;
+    /** The link to the results page (default "See all N results"). */
+    seeAll?: (total: number) => ReactNode;
+    className?: string;
+    autoFocus?: boolean;
+};
+/** 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"> & {
+    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;
+/** The query input of the surrounding SearchProvider. */
+export declare function SearchInput({ placeholder, label, className, autoFocus }: {
+    placeholder?: string;
+    label?: string;
+    className?: string;
+    autoFocus?: boolean;
+}): import("react").JSX.Element;
+export type HitsProps<T> = {
+    /** A hit's content; DefaultHit shows an image and a title. */
+    render?: (hit: Hit<T>, index: number) => ReactNode;
+    /** Shown when nothing matches (default "No results for “…”"). */
+    empty?: (query: string) => ReactNode;
+    /** Shown before the first results arrive. */
+    loading?: ReactNode;
+    className?: string;
+};
+export declare function Hits<T = Record<string, unknown>>({ render, empty, loading, className }: HitsProps<T>): import("react").JSX.Element;
+export type RefinementListProps = {
+    field: string;
+    /** The heading (default the field). */
+    label?: string;
+    /** Values shown before "Show all" (default 8). */
+    limit?: number;
+    /** A value as people should read it, when the data holds a code. */
+    format?: (value: string) => string;
+    className?: string;
+};
+/** Checkboxes for a facet's values, with counts. */
+export declare function RefinementList({ field, label, limit, format, className }: RefinementListProps): import("react").JSX.Element;
+/** A select for the sorts in the index settings; the first option is the default. */
+export declare function SortSelect({ options, label, className }: {
+    options: Array<{
+        id: string;
+        label: string;
+    }>;
+    label?: string;
+    className?: string;
+}): import("react").JSX.Element;
+/** The chosen filters as chips that remove them, and "Clear all". Shows nothing when none are chosen. */
+export declare function CurrentRefinements({ format, clearLabel, className }: {
+    /** A chip's text (default the value, or a range like "2019–2021"). */
+    format?: (refinement: Refinement) => ReactNode;
+    clearLabel?: string;
+    className?: string;
+}): import("react").JSX.Element | null;
+export declare function LoadMore({ label, className }: {
+    label?: string;
+    className?: string;
+}): import("react").JSX.Element | null;
+/** "1,234 results". */
+export declare function Stats({ format, className }: {
+    format?: (total: number) => ReactNode;
+    className?: string;
+}): import("react").JSX.Element | null;

package/dist/react/components.js

@@ -0,0 +1,83 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+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 { 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.
+const number = (value) => value.toLocaleString("en-US");
+/** A hit's image and title, for records with `image` and `title` (or `name`) fields. */
+export function DefaultHit({ hit }) {
+    const record = (hit.record ?? {});
+    const image = typeof record.image === "string" ? record.image : null;
+    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 })] }));
+}
+/** 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` }))] }));
+}
+/** 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);
+    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 }))] }));
+}
+/** The query input of the surrounding SearchProvider. */
+export function SearchInput({ placeholder, label = "Search", className, autoFocus }) {
+    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 }) }));
+}
+export function Hits({ render, empty, loading = null, className }) {
+    const { hits, isLoaded, isPending, error } = 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)
+        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))) }));
+}
+/** Checkboxes for a facet's values, with counts. */
+export function RefinementList({ field, label, limit = 8, format, className }) {
+    const { items, toggle } = useRefinementList(field);
+    const [expanded, setExpanded] = useState(false);
+    const shown = expanded ? items : items.slice(0, limit);
+    return (_jsxs("fieldset", { className: className, "data-findlane-refinement-list": "", children: [_jsx("legend", { children: label ?? field }), items.length === 0 && _jsx("p", { "data-findlane-note": "", children: "No values" }), shown.map((item) => (_jsxs("label", { "data-empty": item.count === 0 || undefined, children: [_jsx("input", { type: "checkbox", checked: item.selected, onChange: () => toggle(item.value) }), _jsx("span", { "data-findlane-value": "", title: format ? item.value : undefined, children: format ? format(item.value) : item.value }), _jsx("span", { "data-findlane-count": "", children: number(item.count) })] }, item.value))), items.length > limit && (_jsx("button", { type: "button", onClick: () => setExpanded((open) => !open), children: expanded ? "Show fewer" : `Show all ${items.length}` }))] }));
+}
+/** A select for the sorts in the index settings; the first option is the default. */
+export function SortSelect({ options, label = "Sort by", className }) {
+    const { sort, setSort } = useSortBy();
+    return (_jsx("select", { className: className, "data-findlane-sort": "", "aria-label": label, value: sort ?? options[0]?.id, onChange: (event) => setSort(event.target.value === options[0]?.id ? undefined : event.target.value), children: options.map((option) => _jsx("option", { value: option.id, children: option.label }, option.id)) }));
+}
+/** The chosen filters as chips that remove them, and "Clear all". Shows nothing when none are chosen. */
+export function CurrentRefinements({ format, clearLabel = "Clear all", className }) {
+    const { items, clear } = useCurrentRefinements();
+    if (!items.length)
+        return null;
+    return (_jsxs("div", { className: className, "data-findlane-current-refinements": "", children: [items.map((item) => (_jsxs("button", { type: "button", onClick: item.remove, children: [format ? format(item) : item.label, " ", _jsx("span", { "aria-hidden": "true", children: "\u00D7" })] }, `${item.field}:${String(item.label)}`))), _jsx("button", { type: "button", "data-findlane-clear": "", onClick: clear, children: clearLabel })] }));
+}
+export function LoadMore({ label = "Show more", className }) {
+    const { hasMore, loadMore, isLoading, shown, total } = useLoadMore();
+    if (!hasMore)
+        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)] })] }));
+}
+/** "1,234 results". */
+export function Stats({ format, className }) {
+    const { total, totalRelation, isLoaded } = useHits();
+    if (!isLoaded)
+        return null;
+    return (_jsx("p", { className: className, "data-findlane-stats": "", children: format ? format(total) : `${number(total)}${totalRelation === "gte" ? "+" : ""} ${total === 1 ? "result" : "results"}` }));
+}

package/dist/react/dialog.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from "react";
+import { type SearchBoxProps } from "./components.js";
+export type SearchDialogProps<T> = Omit<SearchBoxProps<T>, "autoFocus"> & {
+    /** The button that opens the dialog (default "Search", with the shortcut). */
+    trigger?: ReactNode;
+    /** Open with ⌘K (Ctrl+K elsewhere) and "/" (default true). */
+    shortcuts?: boolean;
+};
+/** 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, placeholder, label, action, renderHit, empty, seeAll, className, ...options }: SearchDialogProps<T>): import("react").JSX.Element;

package/dist/react/dialog.js

@@ -0,0 +1,63 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { Suggestions, resultsHref } from "./components.js";
+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, placeholder, label = "Search", action, renderHit, empty, seeAll, className, ...options }) {
+    const dialog = useRef(null);
+    const [open, setOpen] = useState(false);
+    const close = () => dialog.current?.close();
+    const box = useAutocomplete({
+        ...options,
+        // A chosen suggestion closes the dialog; its link, if any, is followed as usual.
+        onSelect: options.onSelect && ((hit) => { close(); options.onSelect(hit); }),
+        onSubmit: options.onSubmit
+            ? (query) => { close(); options.onSubmit(query); }
+            : action ? (query) => window.location.assign(resultsHref(action, query)) : undefined,
+    });
+    const show = () => {
+        if (dialog.current?.open)
+            return;
+        dialog.current?.showModal();
+        setOpen(true);
+    };
+    // The shortcut hint is shown after hydration, so the server's HTML doesn't guess the platform.
+    const [mac, setMac] = useState(false);
+    useEffect(() => setMac(onMac()), []);
+    useEffect(() => {
+        if (!shortcuts)
+            return;
+        const onKey = (event) => {
+            const target = event.target;
+            const typing = !!target && (target.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(target.tagName));
+            if ((event.key === "k" || event.key === "K") && (event.metaKey || event.ctrlKey)) {
+                event.preventDefault();
+                if (dialog.current?.open)
+                    close();
+                else
+                    show();
+            }
+            else if (event.key === "/" && !typing) {
+                event.preventDefault();
+                show();
+            }
+        };
+        window.addEventListener("keydown", onKey);
+        return () => window.removeEventListener("keydown", onKey);
+    }, [shortcuts]);
+    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: className, "data-findlane-dialog-trigger": "", "aria-haspopup": "dialog", onClick: show, children: trigger ?? (_jsxs(_Fragment, { children: [_jsx("span", { children: label }), shortcuts && _jsx("kbd", { "aria-hidden": "true", children: mac ? "⌘K" : "Ctrl K" })] })) }), _jsx("dialog", { ref: dialog, "data-findlane-dialog": "", "aria-label": label, onClose: () => setOpen(false), 
+                // A click on the backdrop lands on the dialog itself.
+                onClick: (event) => { if (event.target === event.currentTarget)
+                    close(); }, children: open && (_jsxs("div", { "data-findlane-searchbox": "", "data-open": box.isOpen || undefined, children: [_jsx("form", { role: "search", onSubmit: (event) => event.preventDefault(), children: _jsx("input", { type: "search", placeholder: placeholder, "aria-label": label, autoFocus: true, ...box.getInputProps({
+                                    // Escape closes the dialog rather than only the suggestions.
+                                    onKeyDown: (event) => {
+                                        if (event.key === "Escape") {
+                                            event.preventDefault();
+                                            close();
+                                        }
+                                    },
+                                }) }) }), box.isOpen && (_jsx(Suggestions, { box: box, label: label, action: action, renderHit: renderHit, empty: empty, seeAll: seeAll }))] })) })] }));
+}

package/dist/react/highlight.d.ts

@@ -0,0 +1,29 @@
+import { type ElementType } from "react";
+import type { Hit } from "./state.js";
+/** Highlighted text from the API as plain and matched parts. */
+export declare function highlightParts(html: string): {
+    text: string;
+    marked: boolean;
+}[];
+/** A field's values in a record, by path; list fields and lists of objects give each value. */
+export declare function valuesAt(record: unknown, path: string): string[];
+export type HighlightProps<T> = {
+    hit: Hit<T>;
+    /** A field path, such as "title" or "brand.name". */
+    field: string;
+    /** Between a list field's values (default ", "). */
+    separator?: string;
+    /** The element for matched words (default "mark"). */
+    mark?: ElementType;
+    className?: string;
+};
+/** A field with the words the query matched marked. Needs `highlight: true` in the request, which
+ * the hooks set. */
+export declare function Highlight<T>({ hit, field, separator, mark, className }: HighlightProps<T>): import("react").JSX.Element;
+/** A few words of highlighted text where the most query words matched, so a phrase wins over a lone
+ * typo match. The API marks single words, so cutting at spaces never splits a tag or an escape. */
+export declare function excerpt(html: string, words?: number): string;
+/** A long field, such as a description, cut to the words around its best match. */
+export declare function Snippet<T>({ hit, field, words, separator, mark, className }: HighlightProps<T> & {
+    words?: number;
+}): import("react").JSX.Element;

package/dist/react/highlight.js

@@ -0,0 +1,68 @@
+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
+// <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;": "'" };
+const decode = (text) => text.replace(/&(amp|lt|gt|quot|#39);/g, (entity) => escapes[entity]);
+/** Highlighted text from the API as plain and matched parts. */
+export function highlightParts(html) {
+    return html.split(/(<mark>|<\/mark>)/).reduce((acc, piece) => {
+        if (piece === "<mark>")
+            acc.marked = true;
+        else if (piece === "</mark>")
+            acc.marked = false;
+        else if (piece)
+            acc.parts.push({ text: decode(piece), marked: acc.marked });
+        return acc;
+    }, { parts: [], marked: false }).parts;
+}
+/** A field's values in a record, by path; list fields and lists of objects give each value. */
+export function valuesAt(record, path) {
+    const flat = (value) => (Array.isArray(value) ? value.flatMap(flat) : [value]);
+    let values = flat(record);
+    for (const key of path.split("."))
+        values = values.flatMap((value) => (value && typeof value === "object" ? flat(value[key]) : []));
+    return values.filter((value) => value !== null && value !== undefined && typeof value !== "object").map(String);
+}
+const escape = (text) => text.replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char]);
+/** A field as highlighted text, whether or not it matched. */
+function fieldHtml(hit, field, separator) {
+    const highlighted = hit.highlights?.[field];
+    if (highlighted !== undefined)
+        return Array.isArray(highlighted) ? highlighted.join(separator) : highlighted;
+    return escape(valuesAt(hit.record, field).join(separator));
+}
+function Marked({ html, mark: Mark }) {
+    return _jsx(_Fragment, { children: highlightParts(html).map((part, at) => part.marked ? _jsx(Mark, { children: part.text }, at) : _jsx(Fragment, { children: part.text }, at)) });
+}
+/** A field with the words the query matched marked. Needs `highlight: true` in the request, which
+ * the hooks set. */
+export function Highlight({ hit, field, separator = ", ", mark = "mark", className }) {
+    return _jsx("span", { className: className, children: _jsx(Marked, { html: fieldHtml(hit, field, separator), mark: mark }) });
+}
+/** A few words of highlighted text where the most query words matched, so a phrase wins over a lone
+ * typo match. The API marks single words, so cutting at spaces never splits a tag or an escape. */
+export function excerpt(html, words = 16) {
+    const parts = html.split(/\s+/);
+    const marked = parts.map((part) => part.includes("<mark>"));
+    let from = -1;
+    let best = 0;
+    for (let at = 0; at < parts.length; at++) {
+        if (!marked[at])
+            continue;
+        const start = Math.max(0, at - 4);
+        const count = marked.slice(start, start + words).filter(Boolean).length;
+        if (count > best)
+            [from, best] = [start, count];
+    }
+    // Without a match, the field's opening.
+    if (from < 0)
+        from = 0;
+    const to = Math.min(parts.length, from + words);
+    return `${from > 0 ? "…" : ""}${parts.slice(from, to).join(" ")}${to < parts.length ? "…" : ""}`;
+}
+/** A long field, such as a description, cut to the words around its best match. */
+export function Snippet({ hit, field, words = 16, separator = " ", mark = "mark", className }) {
+    return _jsx("span", { className: className, children: _jsx(Marked, { html: excerpt(fieldHtml(hit, field, separator), words), mark: mark }) });
+}

package/dist/react/index.d.ts

@@ -0,0 +1,10 @@
+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 { SearchDialog, type SearchDialogProps } from "./dialog.js";
+export { Highlight, Snippet, excerpt, highlightParts, type HighlightProps } from "./highlight.js";
+export { messageFor } from "./messages.js";
+export { emptyState, stateFromUrl, urlFromState, type Hit, type SearchConfig, type SearchState, type UrlParams, } from "./state.js";
+export type { ServerResults, StateChange } from "./store.js";

package/dist/react/index.js

@@ -0,0 +1,11 @@
+"use client";
+// @findlane/browser/react: hooks that keep searches current, and components built on them.
+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 { SearchDialog } from "./dialog.js";
+export { Highlight, Snippet, excerpt, highlightParts } from "./highlight.js";
+export { messageFor } from "./messages.js";
+export { emptyState, stateFromUrl, urlFromState, } from "./state.js";

package/dist/react/messages.d.ts

@@ -0,0 +1,2 @@
+/** A failed search as a visitor should read it. The details for developers are on the error. */
+export declare function messageFor(error: unknown): "That was a lot of searches in a short time. Try again in a minute." | "Search isn't available right now." | "The search didn't go through. Check your connection and try again.";

package/dist/react/messages.js

@@ -0,0 +1,13 @@
+import { FindlaneError } from "../index.js";
+/** A failed search as a visitor should read it. The details for developers are on the error. */
+export function messageFor(error) {
+    if (error instanceof FindlaneError) {
+        if (error.status === 429)
+            return "That was a lot of searches in a short time. Try again in a minute.";
+        // 403 (this site isn't an allowed origin) and 402 (the plan's searches are used up) aren't
+        // something a visitor can fix.
+        if (error.status === 403 || error.status === 402)
+            return "Search isn't available right now.";
+    }
+    return "The search didn't go through. Check your connection and try again.";
+}