@findlane/browser 0.1.0 → 0.3.0

package/dist/react/store.js

@@ -0,0 +1,136 @@
+import { cachedSearch, peek } from "./cache.js";
+import { canonical, hasMoreAfter, planSearch } from "./state.js";
+const typingPause = 150;
+export const planKey = (request) => canonical(request);
+export class SearchStore {
+    client;
+    config;
+    snapshot;
+    listeners = new Set();
+    controller = null;
+    timer;
+    run = 0;
+    /** Called after each change a visitor makes, not when the state is adopted from outside. */
+    onChange = null;
+    constructor(client, config, state, initial) {
+        this.client = client;
+        this.config = config;
+        const request = planSearch(config, state);
+        this.snapshot = { state, results: null, pending: true, error: null, loadingMore: false };
+        if (initial && initial.key === planKey(request))
+            this.snapshot = { ...this.snapshot, results: this.resultsFor(request, initial.response), pending: false };
+    }
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    };
+    getSnapshot = () => this.snapshot;
+    set(patch) {
+        this.snapshot = { ...this.snapshot, ...patch };
+        for (const listener of this.listeners)
+            listener();
+    }
+    /** A visitor's change. Changes to the query wait for a pause in typing; the others search at once. */
+    update(change) {
+        const previous = this.snapshot.state;
+        const state = change(previous);
+        if (canonical(state) === canonical(previous))
+            return;
+        const typing = state.q !== previous.q && canonical({ ...state, q: "", page: 0 }) === canonical({ ...previous, q: "", page: 0 });
+        this.set({ state });
+        this.onChange?.(state, { push: !typing });
+        this.search(typing);
+    }
+    /** A state from outside, such as the URL after Back. */
+    adopt(state) {
+        if (canonical(state) === canonical(this.snapshot.state))
+            return;
+        this.set({ state });
+        this.search(false);
+    }
+    /** A new client or config, from changed props. */
+    configure(client, config) {
+        if (client === this.client && canonical(config) === canonical(this.config))
+            return;
+        this.client = client;
+        this.config = config;
+        this.search(false);
+    }
+    get settings() { return this.config; }
+    /** Searches unless the results already answer the current state; with a state, such as the
+     * URL's, adopts it first. */
+    start(state) {
+        if (state && canonical(state) !== canonical(this.snapshot.state))
+            this.set({ state });
+        const key = planKey(planSearch(this.config, this.snapshot.state));
+        if (this.snapshot.results?.key !== key || this.snapshot.error)
+            this.search(false);
+    }
+    stop() {
+        clearTimeout(this.timer);
+        this.controller?.abort();
+        this.controller = null;
+        this.run++;
+    }
+    resultsFor(request, response) {
+        return { key: planKey(request), request, response, hits: response.hits, hasMore: hasMoreAfter(response, request.offset ?? 0) };
+    }
+    search(debounce) {
+        this.stop();
+        const run = this.run;
+        const client = this.client;
+        const request = planSearch(this.config, this.snapshot.state);
+        // Results already in memory show at once, without a loading state.
+        const cached = peek(client, request);
+        if (cached) {
+            this.set({ results: this.resultsFor(request, cached), pending: false, error: null, loadingMore: false });
+            return;
+        }
+        this.set({ pending: true, loadingMore: false });
+        const controller = new AbortController();
+        this.controller = controller;
+        const go = () => {
+            const started = performance.now();
+            cachedSearch(client, request, controller.signal).then((response) => {
+                if (run !== this.run)
+                    return;
+                const ms = Math.round(performance.now() - started);
+                this.set({ results: { ...this.resultsFor(request, response), ms }, pending: false, error: null });
+            }, (error) => {
+                if (run !== this.run)
+                    return;
+                this.set({ pending: false, error });
+            });
+        };
+        if (debounce)
+            this.timer = setTimeout(go, typingPause);
+        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 offset = (request.offset ?? 0) + results.hits.length;
+        const run = this.run;
+        this.set({ loadingMore: true });
+        cachedSearch(this.client, { ...request, offset }).then((page) => {
+            const current = this.snapshot.results;
+            if (run !== this.run || current?.key !== results.key)
+                return;
+            this.set({
+                results: { ...current, hits: [...current.hits, ...page.hits], hasMore: hasMoreAfter(page, offset) },
+                loadingMore: false,
+            });
+        }, (error) => {
+            if (run === this.run)
+                this.set({ loadingMore: false, error });
+        });
+    }
+}

package/dist/react/styles.css

@@ -0,0 +1,260 @@
+/* @findlane/browser/react/styles.css: a default look for the components. Every rule is inside
+   :where(), so your own CSS wins without !important. Theme it with these variables, set anywhere
+   above the components:
+   --findlane-accent, --findlane-background, --findlane-border, --findlane-muted, --findlane-radius.
+   Without them, colors follow the page's color-scheme. */
+
+:where([data-findlane-searchbox]) {
+  position: relative;
+}
+:where([data-findlane-searchbox], [data-findlane-search-input]) :where(form) {
+  margin: 0;
+}
+:where([data-findlane-searchbox], [data-findlane-search-input]) :where(input) {
+  box-sizing: border-box;
+  width: 100%;
+  font: inherit;
+  padding: 0.6em 0.9em;
+  color: inherit;
+  background: var(--findlane-background, Canvas);
+  border: 1px solid var(--findlane-border, color-mix(in srgb, currentColor 22%, transparent));
+  border-radius: var(--findlane-radius, 10px);
+}
+:where([data-findlane-searchbox], [data-findlane-search-input]) :where(input:focus-visible) {
+  outline: 2px solid var(--findlane-accent, #2f5bff);
+  outline-offset: 1px;
+}
+
+:where([data-findlane-panel]) {
+  position: absolute;
+  top: calc(100% + 6px);
+  left: 0;
+  right: 0;
+  z-index: 50;
+  max-height: min(70vh, 480px);
+  overflow: auto;
+  padding: 4px 0;
+  color: CanvasText;
+  background: var(--findlane-background, Canvas);
+  border: 1px solid var(--findlane-border, color-mix(in srgb, currentColor 14%, transparent));
+  border-radius: var(--findlane-radius, 10px);
+  box-shadow: 0 12px 32px rgb(0 0 0 / 0.14);
+}
+:where([data-findlane-panel] [role="option"]) {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  padding: 8px 12px;
+  color: inherit;
+  text-decoration: none;
+  cursor: pointer;
+}
+:where([data-findlane-panel] [role="option"][aria-selected="true"]) {
+  background: color-mix(in srgb, var(--findlane-accent, #2f5bff) 10%, transparent);
+}
+:where([data-findlane-image]) {
+  width: 40px;
+  height: 40px;
+  flex: none;
+  object-fit: contain;
+  border-radius: 6px;
+}
+:where([data-findlane-panel] [data-findlane-title]) {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+:where([data-findlane-panel], [data-findlane-hits]) :where(mark) {
+  color: var(--findlane-accent, #2f5bff);
+  font-weight: 600;
+  background: none;
+}
+:where([data-findlane-note], [data-findlane-empty]) {
+  margin: 0;
+  padding: 12px;
+  color: var(--findlane-muted, color-mix(in srgb, currentColor 60%, transparent));
+  text-align: center;
+}
+:where([data-findlane-all]) {
+  display: block;
+  padding: 10px 12px;
+  color: var(--findlane-accent, #2f5bff);
+  font-weight: 600;
+  text-align: center;
+  text-decoration: none;
+  border-top: 1px solid var(--findlane-border, color-mix(in srgb, currentColor 10%, transparent));
+}
+
+:where([data-findlane-dialog-trigger]) {
+  display: inline-flex;
+  gap: 12px;
+  align-items: center;
+  justify-content: space-between;
+  min-width: 180px;
+  padding: 0.5em 0.6em 0.5em 0.9em;
+  color: var(--findlane-muted, color-mix(in srgb, currentColor 60%, transparent));
+  font: inherit;
+  background: var(--findlane-background, Canvas);
+  border: 1px solid var(--findlane-border, color-mix(in srgb, currentColor 22%, transparent));
+  border-radius: var(--findlane-radius, 10px);
+  cursor: pointer;
+}
+:where([data-findlane-dialog-trigger]) :where(kbd) {
+  padding: 0.1em 0.4em;
+  font: inherit;
+  font-size: 0.8em;
+  border: 1px solid var(--findlane-border, color-mix(in srgb, currentColor 22%, transparent));
+  border-radius: 5px;
+}
+:where([data-findlane-dialog]) {
+  width: min(640px, calc(100vw - 32px));
+  max-height: min(70vh, 640px);
+  margin: 12vh auto auto;
+  padding: 0;
+  color: CanvasText;
+  background: var(--findlane-background, Canvas);
+  border: 1px solid var(--findlane-border, color-mix(in srgb, currentColor 14%, transparent));
+  border-radius: calc(var(--findlane-radius, 10px) * 1.4);
+  box-shadow: 0 24px 64px rgb(0 0 0 / 0.25);
+}
+:where([data-findlane-dialog])::backdrop {
+  background: rgb(0 0 0 / 0.35);
+}
+/* The padding is inside, so a click on the dialog itself is a click on the backdrop. */
+:where([data-findlane-dialog] > [data-findlane-searchbox]) {
+  padding: 12px;
+}
+/* In the dialog, suggestions sit under the input instead of floating over the page. */
+:where([data-findlane-dialog] [data-findlane-panel]) {
+  position: static;
+  margin-top: 8px;
+  max-height: none;
+  border: 0;
+  box-shadow: none;
+}
+
+:where([data-findlane-hits]) {
+  display: grid;
+  gap: 12px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+:where([data-findlane-hits][data-pending]) {
+  opacity: 0.6;
+  transition: opacity 0.15s 0.1s;
+}
+
+:where([data-findlane-refinement-list]) {
+  min-width: 0;
+  margin: 0 0 18px;
+  padding: 0;
+  border: 0;
+}
+:where([data-findlane-refinement-list]) :where(legend) {
+  margin-bottom: 6px;
+  padding: 0;
+  font-weight: 600;
+}
+:where([data-findlane-refinement-list]) :where(label) {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  padding: 3px 0;
+  cursor: pointer;
+}
+:where([data-findlane-refinement-list]) :where(label[data-empty]) {
+  color: var(--findlane-muted, color-mix(in srgb, currentColor 60%, transparent));
+}
+:where([data-findlane-refinement-list]) :where(input) {
+  margin: 0;
+  accent-color: var(--findlane-accent, #2f5bff);
+}
+:where([data-findlane-value]) {
+  flex: 1;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+:where([data-findlane-count]) {
+  color: var(--findlane-muted, color-mix(in srgb, currentColor 60%, transparent));
+  font-size: 0.85em;
+  font-variant-numeric: tabular-nums;
+}
+:where([data-findlane-refinement-list]) :where(button) {
+  padding: 4px 0;
+  color: var(--findlane-accent, #2f5bff);
+  font: inherit;
+  background: none;
+  border: 0;
+  cursor: pointer;
+}
+
+:where([data-findlane-sort]) {
+  padding: 0.4em 0.6em;
+  color: inherit;
+  font: inherit;
+  background: var(--findlane-background, Canvas);
+  border: 1px solid var(--findlane-border, color-mix(in srgb, currentColor 22%, transparent));
+  border-radius: calc(var(--findlane-radius, 10px) * 0.8);
+}
+
+:where([data-findlane-current-refinements]) {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+:where([data-findlane-current-refinements]) :where(button) {
+  padding: 0.3em 0.75em;
+  color: inherit;
+  font: inherit;
+  font-size: 0.9em;
+  background: color-mix(in srgb, var(--findlane-accent, #2f5bff) 10%, transparent);
+  border: 0;
+  border-radius: 999px;
+  cursor: pointer;
+}
+:where([data-findlane-current-refinements]) :where([data-findlane-clear]) {
+  color: var(--findlane-accent, #2f5bff);
+  background: none;
+}
+
+:where([data-findlane-load-more]) {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  align-items: center;
+  margin-top: 24px;
+  color: var(--findlane-muted, color-mix(in srgb, currentColor 60%, transparent));
+  font-size: 0.9em;
+}
+:where([data-findlane-load-more]) :where(button) {
+  padding: 0.6em 1.4em;
+  color: CanvasText;
+  font: inherit;
+  font-weight: 600;
+  background: var(--findlane-background, Canvas);
+  border: 1px solid var(--findlane-border, color-mix(in srgb, currentColor 22%, transparent));
+  border-radius: var(--findlane-radius, 10px);
+  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/dist/react/use-autocomplete.d.ts

@@ -0,0 +1,55 @@
+import { type HTMLAttributes, type InputHTMLAttributes } from "react";
+import type { Hit } from "./state.js";
+import type { ClientOptions } from "./client.js";
+export type AutocompleteOptions<T> = ClientOptions & {
+    /** Suggestions to show: 1–50 (default 6). */
+    limit?: number;
+    /** The record fields to return (`attributesToRetrieve`). */
+    fields?: string[];
+    filters?: Record<string, unknown>;
+    sort?: string;
+    /** Characters to type before searching (default 1). */
+    minLength?: number;
+    debounceMs?: number;
+    defaultQuery?: string;
+    /** A base for the elements' IDs; one is generated otherwise. */
+    id?: string;
+    /** A hit's page. Enter on a suggestion goes there unless `onSelect` is given. */
+    getHref?: (hit: Hit<T>) => string | undefined;
+    /** A hit'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 hit's ID.
+     * A template that is one field, such as "{url}", takes that field's URL as it is. */
+    hrefTemplate?: string;
+    /** Called when a suggestion is chosen, instead of following its link; for client-side routers. */
+    onSelect?: (hit: Hit<T>) => void;
+    /** Called on Enter without a chosen suggestion. Without it, Enter submits the input's form. */
+    onSubmit?: (query: string) => void;
+};
+/** 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. */
+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;
+        highlights?: Record<string, string | string[]>;
+    }[];
+    total: number;
+    response: import("../index.js").SearchResponse<T> | null;
+    error: unknown;
+    isPending: boolean;
+    isOpen: boolean;
+    activeIndex: number;
+    setActiveIndex: import("react").Dispatch<import("react").SetStateAction<number>>;
+    close: () => void;
+    select: (hit: Hit<T>) => void;
+    /** A hit's page, from `getHref` or `hrefTemplate`. */
+    hrefFor: (hit: Hit<T>) => string | undefined;
+    getInputProps: (props?: InputHTMLAttributes<HTMLInputElement>) => InputHTMLAttributes<HTMLInputElement>;
+    getListboxProps: (props?: HTMLAttributes<HTMLElement>) => HTMLAttributes<HTMLElement>;
+    getOptionProps: (index: number, props?: HTMLAttributes<HTMLElement>) => HTMLAttributes<HTMLElement>;
+};

package/dist/react/use-autocomplete.js

@@ -0,0 +1,174 @@
+"use client";
+import { useEffect, useId, useState, } from "react";
+import { valuesAt } from "./highlight.js";
+import { useSearch } from "./use-search.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] ?? "");
+    const whole = template.match(/^\{([^}]+)\}$/);
+    const href = whole ? value(whole[1]) : template.replace(/\{([^}]+)\}/g, (_, field) => encodeURIComponent(value(field)));
+    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. */
+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);
+    const generated = useId();
+    const id = options.id ?? `findlane${generated.replace(/:/g, "")}`;
+    const [query, setQueryState] = useState(options.defaultQuery ?? "");
+    const [focused, setFocused] = useState(false);
+    const [dismissed, setDismissed] = useState(false);
+    const [activeIndex, setActiveIndex] = useState(-1);
+    const request = query.trim().length >= minLength
+        ? {
+            q: query,
+            limit,
+            highlight: true,
+            ...(fields ? { attributesToRetrieve: fields } : {}),
+            ...(filters ? { filters } : {}),
+            ...(sort ? { sort } : {}),
+        }
+        : null;
+    const search = useSearch(request, {
+        publicId: options.publicId, baseUrl: options.baseUrl, client: options.client, debounceMs,
+    });
+    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);
+    // New suggestions start unselected.
+    useEffect(() => setActiveIndex(-1), [search.data]);
+    const listboxId = `${id}-listbox`;
+    const optionId = (index) => `${id}-option-${index}`;
+    const setQuery = (value) => {
+        setQueryState(value);
+        setDismissed(false);
+        setActiveIndex(-1);
+    };
+    const close = () => {
+        setDismissed(true);
+        setActiveIndex(-1);
+    };
+    const select = (hit) => {
+        close();
+        if (onSelect)
+            return onSelect(hit);
+        const href = getHref?.(hit);
+        if (href)
+            window.location.assign(href);
+    };
+    function onKeyDown(event) {
+        if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+            event.preventDefault();
+            if (!isOpen)
+                return setDismissed(false);
+            const step = event.key === "ArrowDown" ? 1 : -1;
+            // -1 is the input itself, between the last suggestion and the first.
+            setActiveIndex((current) => ((current + 1 + step + hits.length + 1) % (hits.length + 1)) - 1);
+        }
+        else if (event.key === "Escape") {
+            if (isOpen) {
+                event.preventDefault();
+                close();
+            }
+            else if (query) {
+                event.preventDefault();
+                setQuery("");
+            }
+        }
+        else if (event.key === "Enter" && !event.nativeEvent.isComposing) {
+            const hit = isOpen && activeIndex >= 0 ? hits[activeIndex] : undefined;
+            if (hit) {
+                event.preventDefault();
+                select(hit);
+            }
+            else if (onSubmit) {
+                event.preventDefault();
+                close();
+                onSubmit(query);
+            }
+        }
+    }
+    return {
+        query,
+        setQuery,
+        hits,
+        total: search.data?.total ?? 0,
+        response: search.data,
+        error: search.error,
+        isPending: search.isPending,
+        isOpen,
+        activeIndex,
+        setActiveIndex,
+        close,
+        select,
+        /** A hit's page, from `getHref` or `hrefTemplate`. */
+        hrefFor: (hit) => getHref?.(hit),
+        getInputProps: (props = {}) => ({
+            autoComplete: "off",
+            autoCorrect: "off",
+            spellCheck: false,
+            maxLength: 200,
+            ...props,
+            role: "combobox",
+            "aria-autocomplete": "list",
+            "aria-expanded": isOpen,
+            "aria-controls": listboxId,
+            "aria-activedescendant": isOpen && activeIndex >= 0 ? optionId(activeIndex) : undefined,
+            value: query,
+            onChange: (event) => {
+                props.onChange?.(event);
+                setQuery(event.target.value);
+            },
+            onFocus: (event) => {
+                props.onFocus?.(event);
+                setFocused(true);
+                setDismissed(false);
+            },
+            onBlur: (event) => {
+                props.onBlur?.(event);
+                setFocused(false);
+            },
+            onKeyDown: (event) => {
+                props.onKeyDown?.(event);
+                if (!event.defaultPrevented)
+                    onKeyDown(event);
+            },
+        }),
+        getListboxProps: (props = {}) => ({
+            ...props,
+            id: listboxId,
+            role: "listbox",
+            // Keeps focus in the input, so choosing a suggestion doesn't close the list first.
+            onMouseDown: (event) => {
+                props.onMouseDown?.(event);
+                event.preventDefault();
+            },
+        }),
+        getOptionProps: (index, props = {}) => ({
+            ...props,
+            id: optionId(index),
+            role: "option",
+            "aria-selected": index === activeIndex,
+            onMouseMove: (event) => {
+                props.onMouseMove?.(event);
+                if (index !== activeIndex)
+                    setActiveIndex(index);
+            },
+            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)
+                    return;
+                // A link without onSelect is followed as usual.
+                if (onSelect || !event.currentTarget.href) {
+                    event.preventDefault();
+                    select(hit);
+                }
+                else
+                    close();
+            },
+        }),
+    };
+}

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

@@ -0,0 +1,19 @@
+import type { SearchRequest, SearchResponse } from "../index.js";
+import { type ClientOptions } from "./client.js";
+export type UseSearchOptions<T> = ClientOptions & {
+    /** How long to wait for a pause in typing, in milliseconds (default 150). */
+    debounceMs?: number;
+    /** Results for the first request, such as ones from the server. The hook doesn't search again
+     * until the request changes. */
+    initialData?: SearchResponse<T>;
+};
+export type UseSearchResult<T> = {
+    /** The latest results. While a newer search runs they stay, so the page doesn't flash. */
+    data: SearchResponse<T> | null;
+    error: unknown;
+    /** A search is waiting for a pause in typing or is in flight. */
+    isPending: boolean;
+};
+/** Keeps one search current. A new request cancels the one in flight, and a slow response never
+ * replaces a newer one. Pass `null` to not search (and clear the results). */
+export declare function useSearch<T = Record<string, unknown>>(request: SearchRequest | null, { debounceMs, initialData, ...clientOptions }?: UseSearchOptions<T>): UseSearchResult<T>;

package/dist/react/use-search.js

@@ -0,0 +1,46 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+import { cachedSearch, peek, searchKey } from "./cache.js";
+import { useClient } from "./client.js";
+/** Keeps one search current. A new request cancels the one in flight, and a slow response never
+ * replaces a newer one. Pass `null` to not search (and clear the results). */
+export function useSearch(request, { debounceMs = 150, initialData, ...clientOptions } = {}) {
+    const client = useClient(clientOptions);
+    const key = request ? searchKey(request) : null;
+    const [result, setResult] = useState(() => ({
+        data: initialData ?? null,
+        error: null,
+        isPending: request !== null && !initialData,
+    }));
+    const initialKey = useRef(initialData ? key : null);
+    useEffect(() => {
+        if (!request) {
+            setResult((current) => (current.data || current.error || current.isPending ? { data: null, error: null, isPending: false } : current));
+            return;
+        }
+        if (key === initialKey.current)
+            return;
+        initialKey.current = null;
+        const cached = peek(client, request);
+        if (cached) {
+            setResult({ data: cached, error: null, isPending: false });
+            return;
+        }
+        setResult((current) => (current.isPending ? current : { ...current, isPending: true }));
+        let active = true;
+        const controller = new AbortController();
+        const timer = setTimeout(() => {
+            cachedSearch(client, request, controller.signal).then((data) => { if (active)
+                setResult({ data, error: null, isPending: false }); }, (error) => { if (active)
+                setResult((current) => ({ ...current, error, isPending: false })); });
+        }, debounceMs);
+        return () => {
+            active = false;
+            clearTimeout(timer);
+            controller.abort();
+        };
+        // The key stands for the request, so a new object with the same search doesn't search again.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, key, debounceMs]);
+    return result;
+}