@findlane/browser 0.1.0 → 0.3.0

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, useDidYouMean, useHits, useLoadMore, usePagination, useRange, useRefinementList, useSearchBox, useSearchState, useSortBy, useToggle, } from "./search-provider.js";
+export { CurrentRefinements, DefaultHit, DidYouMean, Hits, LoadMore, RefinementList, SearchBox, SearchInput, SortSelect, Stats, } from "./components.js";
+export { SearchDialog } from "./dialog.js";
+export { Highlight, Snippet, excerpt, highlightParts } from "./highlight.js";
+export { messageFor } from "./messages.js";
+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.";
+}

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

@@ -0,0 +1,121 @@
+import { type ReactNode } from "react";
+import type { DidYouMean } from "../index.js";
+import { type ClientOptions } from "./client.js";
+import { type ServerResults, type StateChange } from "./store.js";
+import { type SearchConfig, type SearchState } from "./state.js";
+export type SearchProviderProps<T> = SearchConfig & ClientOptions & {
+    children: ReactNode;
+    /** Keeps the state in the page's URL (`?q=shoe&brand=Acme`), so results can be shared and Back
+     * undoes a filter. */
+    routing?: boolean;
+    /** A state to adopt whenever it changes, such as one from your router. */
+    state?: SearchState;
+    /** Called after each change a visitor makes; `push` is false while typing. */
+    onStateChange?: (state: SearchState, change: StateChange) => void;
+    /** Results from getServerResults (`@findlane/browser/react/ssr`), so the first render doesn't
+     * search again. */
+    initialResults?: ServerResults<T>;
+};
+/** A results page's search. The hooks and components inside it share its state and results. */
+export declare function SearchProvider<T = Record<string, unknown>>(props: SearchProviderProps<T>): import("react").JSX.Element;
+type Update = (state: SearchState) => SearchState;
+/** The whole state, for anything the other hooks don't cover. */
+export declare function useSearchState(): {
+    state: SearchState;
+    setState: (change: SearchState | Update) => void;
+};
+export declare function useSearchBox(): {
+    query: string;
+    setQuery: (q: string) => void;
+    clear: () => void;
+    isPending: boolean;
+};
+export declare function useHits<T = Record<string, unknown>>(): {
+    hits: import("./state.js").Hit<T>[];
+    total: number;
+    /** "gte" when `total` is a lower bound (with `countMode: "page"`). */
+    totalRelation: "eq" | "gte";
+    response: import("../index.js").SearchResponse<T> | null;
+    /** The request behind `response`. */
+    request: import("../index.js").SearchRequest | null;
+    /** How long the search took from request to response, in milliseconds; undefined when the
+     * results came from memory or the server. */
+    ms: number | undefined;
+    /** Whether the first results have arrived. */
+    isLoaded: boolean;
+    isPending: boolean;
+    error: unknown;
+};
+/** Did you mean, with the index's didYouMean setting: the query the results are for when typo tolerance
+ * corrected some words (`applied`, "Showing results for"), or, when nothing matched, a query that
+ * finds results, asked for once the visitor has stopped typing for `delay` ms. `apply` searches for it.
+ * Searches carry `didYouMean` only when the setting is on, so other indexes are never asked. */
+export declare function useDidYouMean({ delay }?: {
+    delay?: number;
+}): {
+    didYouMean: DidYouMean | null;
+    apply: () => void;
+};
+/** A facet's values with their counts, most common first. Selected values stay listed (at 0 when the
+ * query no longer matches them), so they can be removed. */
+export declare function useRefinementList(field: string): {
+    items: {
+        value: string;
+        count: number;
+        selected: boolean;
+    }[];
+    selected: string[];
+    toggle: (value: string) => void;
+    clear: () => void;
+};
+export type Range = {
+    gte?: number | string;
+    lte?: number | string;
+};
+/** A number or date range filter. List the field in `filterFields` to keep it in the URL. */
+export declare function useRange(field: string): {
+    range: Range | undefined;
+    /** Leave a bound out (or empty) for no limit on that side. */
+    setRange: (range: Range | undefined) => void;
+    clear: () => void;
+};
+/** A filter on one value, such as in stock only. List the field in `filterFields` to keep it in the
+ * URL. */
+export declare function useToggle(field: string, value?: unknown): {
+    on: boolean;
+    set: (next: boolean) => void;
+    toggle: () => void;
+};
+export declare function useSortBy(): {
+    /** The chosen sort ID; undefined for the index's default. */
+    sort: string | undefined;
+    setSort: (sort: string | undefined) => void;
+};
+export type Refinement = {
+    field: string;
+    value: unknown;
+    label: string;
+    remove: () => void;
+};
+/** Everything chosen, as removable items (for chips), and a way to clear it all. The query stays. */
+export declare function useCurrentRefinements(): {
+    items: Refinement[];
+    clear: () => void;
+};
+/** Adds the next page's hits under the current ones. */
+export declare function useLoadMore(): {
+    hasMore: boolean;
+    loadMore: () => void;
+    isLoading: boolean;
+    shown: number;
+    total: number;
+};
+/** Numbered pages, from 0. The API returns hits up to the 1,000th offset, so pages stop there. */
+export declare function usePagination(): {
+    page: number;
+    pages: number;
+    setPage: (page: number) => void;
+    hasPrevious: boolean;
+    hasNext: boolean;
+};
+export {};

package/dist/react/search-provider.js

@@ -0,0 +1,214 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useState, useSyncExternalStore, } from "react";
+import { useClient } from "./client.js";
+import { SearchStore } from "./store.js";
+import { canonical, emptyState, isRange, maxOffset, stateFromUrl, urlFromState, } from "./state.js";
+const StoreContext = createContext(null);
+// Layout effects don't run on the server, and React 18 warns there.
+const useClientLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+/** A results page's search. The hooks and components inside it share its state and results. */
+export function SearchProvider(props) {
+    const { children, routing = false, state, onStateChange, initialResults, publicId, baseUrl, client: given, ...rest } = props;
+    const client = useClient({ publicId, baseUrl, client: given });
+    const configKey = canonical(rest);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const config = useMemo(() => rest, [configKey]);
+    // The first render matches the server's: the URL's state is adopted after it.
+    const [store] = useState(() => new SearchStore(client, config, state ?? initialResults?.state ?? emptyState, initialResults));
+    useClientLayoutEffect(() => {
+        store.onChange = (next, change) => {
+            if (routing) {
+                const params = urlFromState(next, config, window.location.search).toString();
+                const url = `${window.location.pathname}${params ? `?${params}` : ""}${window.location.hash}`;
+                window.history[change.push ? "pushState" : "replaceState"](window.history.state, "", url);
+            }
+            onStateChange?.(next, change);
+        };
+    });
+    useClientLayoutEffect(() => {
+        store.start(routing && !state ? stateFromUrl(window.location.search, config) : undefined);
+        return () => store.stop();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [store]);
+    useEffect(() => store.configure(client, config), [store, client, config]);
+    useEffect(() => {
+        if (!routing)
+            return;
+        const onPopState = () => store.adopt(stateFromUrl(window.location.search, config));
+        window.addEventListener("popstate", onPopState);
+        return () => window.removeEventListener("popstate", onPopState);
+    }, [store, routing, config]);
+    const stateKey = state ? canonical(state) : null;
+    useEffect(() => {
+        if (state)
+            store.adopt(state);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [store, stateKey]);
+    return _jsx(StoreContext.Provider, { value: store, children: children });
+}
+function useStore() {
+    const store = useContext(StoreContext);
+    if (!store)
+        throw new Error("Put this inside a SearchProvider");
+    return store;
+}
+function useSnapshot() {
+    const store = useStore();
+    return [useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot), store];
+}
+const withFilter = (field, value) => (state) => {
+    const { [field]: _, ...filters } = state.filters;
+    return { ...state, page: 0, filters: value === undefined ? filters : { ...filters, [field]: value } };
+};
+const withRefinement = (field, values) => (state) => {
+    const { [field]: _, ...refinements } = state.refinements;
+    return { ...state, page: 0, refinements: values.length ? { ...refinements, [field]: values } : refinements };
+};
+/** The whole state, for anything the other hooks don't cover. */
+export function useSearchState() {
+    const [{ state }, store] = useSnapshot();
+    return { state, setState: (change) => store.update(typeof change === "function" ? change : () => change) };
+}
+export function useSearchBox() {
+    const [{ state, pending }, store] = useSnapshot();
+    const setQuery = (q) => store.update((current) => ({ ...current, q, page: 0 }));
+    return { query: state.q, setQuery, clear: () => setQuery(""), isPending: pending };
+}
+export function useHits() {
+    const [{ results, pending, error }] = useSnapshot();
+    return {
+        hits: results?.hits ?? [],
+        total: results?.response.total ?? 0,
+        /** "gte" when `total` is a lower bound (with `countMode: "page"`). */
+        totalRelation: results?.response.totalRelation ?? "eq",
+        response: results?.response ?? null,
+        /** The request behind `response`. */
+        request: results?.request ?? null,
+        /** How long the search took from request to response, in milliseconds; undefined when the
+         * results came from memory or the server. */
+        ms: results?.ms,
+        /** Whether the first results have arrived. */
+        isLoaded: results !== null,
+        isPending: pending,
+        error,
+    };
+}
+/** Did you mean, with the index's didYouMean setting: the query the results are for when typo tolerance
+ * corrected some words (`applied`, "Showing results for"), or, when nothing matched, a query that
+ * finds results, asked for once the visitor has stopped typing for `delay` ms. `apply` searches for it.
+ * Searches carry `didYouMean` only when the setting is on, so other indexes are never asked. */
+export function useDidYouMean({ delay = 400 } = {}) {
+    const [{ results, pending }, store] = useSnapshot();
+    const [suggested, setSuggested] = useState(null);
+    const empty = Boolean(results && !pending && !results.response.total && results.request.q?.trim() &&
+        results.response.didYouMean !== undefined);
+    const key = results?.key;
+    useEffect(() => {
+        if (!empty || !results)
+            return;
+        const controller = new AbortController();
+        const timer = setTimeout(() => store.suggest(results.request, controller.signal)
+            .then((didYouMean) => setSuggested({ key: results.key, didYouMean }), () => undefined), delay);
+        return () => { clearTimeout(timer); controller.abort(); };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [store, key, empty, delay]);
+    const didYouMean = results?.response.didYouMean ?? (empty && suggested?.key === key ? suggested.didYouMean : null);
+    return {
+        didYouMean,
+        apply: () => { if (didYouMean)
+            store.update((current) => ({ ...current, q: didYouMean.q, page: 0 })); },
+    };
+}
+/** A facet's values with their counts, most common first. Selected values stay listed (at 0 when the
+ * query no longer matches them), so they can be removed. */
+export function useRefinementList(field) {
+    const [{ state, results }, store] = useSnapshot();
+    const selected = state.refinements[field] ?? [];
+    const counts = results?.response.facets[field] ?? {};
+    const items = Object.entries(counts)
+        .map(([value, count]) => ({ value, count, selected: selected.includes(value) }))
+        .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
+    for (const value of selected)
+        if (!(value in counts))
+            items.push({ value, count: 0, selected: true });
+    return {
+        items,
+        selected,
+        toggle: (value) => store.update((current) => {
+            const values = current.refinements[field] ?? [];
+            return withRefinement(field, values.includes(value) ? values.filter((item) => item !== value) : [...values, value])(current);
+        }),
+        clear: () => store.update(withRefinement(field, [])),
+    };
+}
+/** A number or date range filter. List the field in `filterFields` to keep it in the URL. */
+export function useRange(field) {
+    const [{ state }, store] = useSnapshot();
+    const value = state.filters[field];
+    return {
+        range: isRange(value) ? value : undefined,
+        /** Leave a bound out (or empty) for no limit on that side. */
+        setRange: (range) => {
+            const bounds = Object.entries(range ?? {}).filter(([, bound]) => bound !== undefined && bound !== "");
+            store.update(withFilter(field, bounds.length ? Object.fromEntries(bounds) : undefined));
+        },
+        clear: () => store.update(withFilter(field, undefined)),
+    };
+}
+/** A filter on one value, such as in stock only. List the field in `filterFields` to keep it in the
+ * URL. */
+export function useToggle(field, value = true) {
+    const [{ state }, store] = useSnapshot();
+    const on = field in state.filters && canonical(state.filters[field]) === canonical(value);
+    const set = (next) => store.update(withFilter(field, next ? value : undefined));
+    return { on, set, toggle: () => set(!on) };
+}
+export function useSortBy() {
+    const [{ state }, store] = useSnapshot();
+    return {
+        /** The chosen sort ID; undefined for the index's default. */
+        sort: state.sort,
+        setSort: (sort) => store.update(({ sort: _, ...current }) => ({ ...current, page: 0, ...(sort ? { sort } : {}) })),
+    };
+}
+function rangeLabel({ gte, lte }) {
+    if (gte !== undefined && lte !== undefined)
+        return gte === lte ? `${gte}` : `${gte}–${lte}`;
+    return gte !== undefined ? `From ${gte}` : `Until ${lte}`;
+}
+/** Everything chosen, as removable items (for chips), and a way to clear it all. The query stays. */
+export function useCurrentRefinements() {
+    const [{ state }, store] = useSnapshot();
+    const items = [
+        ...Object.entries(state.refinements).flatMap(([field, values]) => values.map((value) => ({
+            field, value, label: value,
+            remove: () => store.update((current) => withRefinement(field, (current.refinements[field] ?? []).filter((item) => item !== value))(current)),
+        }))),
+        ...Object.entries(state.filters).map(([field, value]) => ({
+            field, value, label: isRange(value) ? rangeLabel(value) : String(value),
+            remove: () => store.update(withFilter(field, undefined)),
+        })),
+    ];
+    return { items, clear: () => store.update((current) => ({ ...current, page: 0, refinements: {}, filters: {} })) };
+}
+/** Adds the next page's hits under the current ones. */
+export function useLoadMore() {
+    const [{ results, loadingMore }, store] = useSnapshot();
+    return {
+        hasMore: results?.hasMore ?? false,
+        loadMore: () => store.loadMore(),
+        isLoading: loadingMore,
+        shown: results?.hits.length ?? 0,
+        total: results?.response.total ?? 0,
+    };
+}
+/** Numbered pages, from 0. The API returns hits up to the 1,000th offset, so pages stop there. */
+export function usePagination() {
+    const [{ state, results }, store] = useSnapshot();
+    const pageSize = store.settings.pageSize ?? 20;
+    const total = results?.response.total ?? 0;
+    const pages = Math.max(1, Math.min(Math.ceil(total / pageSize), Math.floor(maxOffset / pageSize) + 1));
+    const setPage = (page) => store.update((current) => ({ ...current, page: Math.max(0, Math.min(Math.floor(page), pages - 1)) }));
+    return { page: state.page, pages, setPage, hasPrevious: state.page > 0, hasNext: state.page + 1 < pages };
+}

package/dist/react/ssr.d.ts

@@ -0,0 +1,12 @@
+import type { SearchRequest, SearchResponse } from "../index.js";
+import { type SearchConfig, type SearchState } from "./state.js";
+import { type ServerResults } from "./store.js";
+export { emptyState, stateFromUrl, urlFromState, type SearchConfig, type SearchState, type UrlParams } from "./state.js";
+export type { ServerResults } from "./store.js";
+/** Runs the search SearchProvider would run for a state; pass the result as its `initialResults`
+ * with the same config. Search with `@findlane/server` and a key with the search scope, since the
+ * public route only answers browsers on the index's allowed origins:
+ *
+ *     getServerResults(config, stateFromUrl(searchParams, config), (request) => products.search(request))
+ */
+export declare function getServerResults<T = Record<string, unknown>>(config: SearchConfig, state: SearchState, search: (request: SearchRequest) => Promise<SearchResponse<unknown>>): Promise<ServerResults<T>>;

package/dist/react/ssr.js

@@ -0,0 +1,13 @@
+import { planSearch } from "./state.js";
+import { planKey } from "./store.js";
+export { emptyState, stateFromUrl, urlFromState } from "./state.js";
+/** Runs the search SearchProvider would run for a state; pass the result as its `initialResults`
+ * with the same config. Search with `@findlane/server` and a key with the search scope, since the
+ * public route only answers browsers on the index's allowed origins:
+ *
+ *     getServerResults(config, stateFromUrl(searchParams, config), (request) => products.search(request))
+ */
+export async function getServerResults(config, state, search) {
+    const request = planSearch(config, state);
+    return { state, key: planKey(request), response: (await search(request)) };
+}

package/dist/react/state.d.ts

@@ -0,0 +1,52 @@
+import type { SearchRequest, SearchResponse } from "../index.js";
+export type Hit<T> = SearchResponse<T>["hits"][number];
+/** What a visitor has chosen on a results page. It round-trips through the URL. */
+export type SearchState = {
+    q: string;
+    /** A sort ID from the index settings; left out for the index's default. */
+    sort?: string;
+    /** Selected values of each facet, by field. */
+    refinements: Record<string, string[]>;
+    /** Ranges (`{ gte, lte }`) and single values (such as `true` for in stock), by field. */
+    filters: Record<string, unknown>;
+    /** The page, from 0. */
+    page: number;
+};
+export type SearchConfig = {
+    /** Fields to count values for. A facet's own selections don't narrow its counts, so its other
+     * values stay listed and can be added. */
+    facets?: string[];
+    /** Fields that useRange and useToggle filter, so the URL can carry them. */
+    filterFields?: string[];
+    /** Filters always applied, such as `{ published: true }`. They aren't shown as refinements. */
+    filters?: Record<string, unknown>;
+    /** Hits per page: 1–50 (default 20). */
+    pageSize?: number;
+    /** The record fields to return (`attributesToRetrieve`); all of them when left out. */
+    fields?: string[];
+    /** "exact" (default) counts every match; "page" is faster on large indexes. */
+    countMode?: "page" | "exact";
+    facetMode?: "page" | "exact";
+};
+export declare const emptyState: SearchState;
+/** The API's largest offset. */
+export declare const maxOffset = 1000;
+/** The request behind a state. A facet with selections is counted without them
+ * (`disjunctiveFacets`), so its other values stay listed and can be added. */
+export declare function planSearch(config: SearchConfig, state: SearchState): SearchRequest;
+/** Whether a page has hits after it that the API can return. */
+export declare function hasMoreAfter(response: SearchResponse<unknown>, offset: number): boolean;
+type Range = {
+    gte?: number | string;
+    lte?: number | string;
+};
+export declare function isRange(value: unknown): value is Range;
+/** A URL's query string, or its parameters as an object (such as Next.js's `searchParams`). */
+export type UrlParams = string | URLSearchParams | Record<string, string | string[] | undefined>;
+/** The state a URL describes. Parameters that aren't the config's fields are ignored. */
+export declare function stateFromUrl(search: UrlParams, config: SearchConfig): SearchState;
+/** The query string for a state, followed by the URL's other parameters. */
+export declare function urlFromState(state: SearchState, config: SearchConfig, current?: string | URLSearchParams): URLSearchParams;
+/** A stable text form of a value, with object keys sorted. */
+export declare function canonical(value: unknown): string;
+export {};

package/dist/react/state.js

@@ -0,0 +1,127 @@
+export const emptyState = { q: "", refinements: {}, filters: {}, page: 0 };
+/** The API's largest offset. */
+export const maxOffset = 1000;
+/** The request behind a state. A facet with selections is counted without them
+ * (`disjunctiveFacets`), so its other values stay listed and can be added. */
+export function planSearch(config, state) {
+    const pageSize = config.pageSize ?? 20;
+    const facets = config.facets ?? [];
+    const filters = { ...state.filters };
+    for (const [field, values] of Object.entries(state.refinements))
+        if (values.length)
+            filters[field] = { in: values };
+    Object.assign(filters, config.filters);
+    // Only facets filtered by their selections alone: a fixed filter still narrows its own counts.
+    const disjunctive = facets.filter((field) => state.refinements[field]?.length && !(field in state.filters) && !(field in (config.filters ?? {})));
+    return {
+        q: state.q,
+        ...(state.sort ? { sort: state.sort } : {}),
+        ...(Object.keys(filters).length ? { filters } : {}),
+        ...(facets.length ? { facets } : {}),
+        ...(disjunctive.length ? { disjunctiveFacets: disjunctive } : {}),
+        limit: pageSize,
+        ...(state.page > 0 ? { offset: Math.min(state.page * pageSize, maxOffset) } : {}),
+        ...(config.fields ? { attributesToRetrieve: config.fields } : {}),
+        countMode: config.countMode ?? "exact",
+        ...(facets.length ? { facetMode: config.facetMode ?? "exact" } : {}),
+        highlight: true,
+    };
+}
+/** Whether a page has hits after it that the API can return. */
+export function hasMoreAfter(response, offset) {
+    const next = offset + response.hits.length;
+    return (response.hasMore ?? next < response.total) && next <= maxOffset;
+}
+const bound = /^(-?\d+(\.\d+)?|\d{4}-\d{2}-\d{2}(T[\d:.]+(Z|[+-]\d{2}:\d{2})?)?)?$/;
+export function isRange(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.every((key) => key === "gte" || key === "lte");
+}
+/** A filter value from the URL: `10..50` is a range, JSON is a value, anything else a string. */
+function parseValue(text) {
+    const range = text.match(/^(.*)\.\.(.*)$/);
+    if (range && (range[1] || range[2]) && bound.test(range[1]) && bound.test(range[2])) {
+        const side = (part) => (/^-?\d+(\.\d+)?$/.test(part) ? Number(part) : part);
+        return { ...(range[1] ? { gte: side(range[1]) } : {}), ...(range[2] ? { lte: side(range[2]) } : {}) };
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function formatValue(value) {
+    if (isRange(value))
+        return `${value.gte ?? ""}..${value.lte ?? ""}`;
+    // A string that would read back as something else is written as JSON.
+    if (typeof value === "string" && parseValue(value) === value)
+        return value;
+    return JSON.stringify(value);
+}
+function paramsFrom(search) {
+    if (typeof search === "string" || search instanceof URLSearchParams)
+        return new URLSearchParams(search);
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(search))
+        for (const item of Array.isArray(value) ? value : value === undefined ? [] : [value])
+            params.append(key, item);
+    return params;
+}
+/** The state a URL describes. Parameters that aren't the config's fields are ignored. */
+export function stateFromUrl(search, config) {
+    const params = paramsFrom(search);
+    const refinements = {};
+    for (const field of config.facets ?? []) {
+        const values = params.getAll(field);
+        if (values.length)
+            refinements[field] = values;
+    }
+    const filters = {};
+    for (const field of config.filterFields ?? []) {
+        const value = params.get(field);
+        if (value !== null)
+            filters[field] = parseValue(value);
+    }
+    const page = Number(params.get("page"));
+    return {
+        q: params.get("q") ?? "",
+        ...(params.get("sort") ? { sort: params.get("sort") } : {}),
+        refinements,
+        filters,
+        page: Number.isInteger(page) && page > 1 ? page - 1 : 0,
+    };
+}
+/** The query string for a state, followed by the URL's other parameters. */
+export function urlFromState(state, config, current = "") {
+    const params = new URLSearchParams();
+    if (state.q)
+        params.set("q", state.q);
+    if (state.sort)
+        params.set("sort", state.sort);
+    for (const [field, values] of Object.entries(state.refinements))
+        if (config.facets?.includes(field))
+            for (const value of values)
+                params.append(field, value);
+    for (const [field, value] of Object.entries(state.filters))
+        if (config.filterFields?.includes(field) && value !== undefined)
+            params.set(field, formatValue(value));
+    if (state.page > 0)
+        params.set("page", String(state.page + 1));
+    const own = new Set(["q", "sort", "page", ...(config.facets ?? []), ...(config.filterFields ?? [])]);
+    for (const [key, value] of new URLSearchParams(current))
+        if (!own.has(key))
+            params.append(key, value);
+    return params;
+}
+/** A stable text form of a value, with object keys sorted. */
+export function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.keys(value).sort().filter((key) => value[key] !== undefined)
+            .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+    return JSON.stringify(value) ?? "null";
+}

package/dist/react/store.d.ts

@@ -0,0 +1,67 @@
+import type { DidYouMean, SearchBrowserClient, SearchRequest, SearchResponse } from "../index.js";
+import { type Hit, type SearchConfig, type SearchState } from "./state.js";
+/** Results computed on the server (see ssr.ts), so the first render needn't search again. */
+export type ServerResults<T = unknown> = {
+    state: SearchState;
+    key: string;
+    response: SearchResponse<T>;
+};
+export type Results<T> = {
+    /** The request these results answer, as a key. */
+    key: string;
+    request: SearchRequest;
+    /** The first page's response. */
+    response: SearchResponse<T>;
+    /** The page's hits and any loaded after it. */
+    hits: Hit<T>[];
+    hasMore: boolean;
+    /** How long the searches took, in milliseconds, from request to response; left out when the
+     * results came from memory or the server. */
+    ms?: number;
+};
+export type Snapshot<T> = {
+    state: SearchState;
+    results: Results<T> | null;
+    /** A search for the current state is waiting or in flight; `results` are the previous ones. */
+    pending: boolean;
+    error: unknown;
+    loadingMore: boolean;
+};
+/** How a change should reach the browser history: typing replaces the entry, other changes add one,
+ * so Back undoes a filter rather than a keystroke. */
+export type StateChange = {
+    push: boolean;
+};
+export declare const planKey: (request: SearchRequest) => string;
+export declare class SearchStore<T = unknown> {
+    private client;
+    private config;
+    private snapshot;
+    private listeners;
+    private controller;
+    private timer;
+    private run;
+    /** Called after each change a visitor makes, not when the state is adopted from outside. */
+    onChange: ((state: SearchState, change: StateChange) => void) | null;
+    constructor(client: SearchBrowserClient, config: SearchConfig, state: SearchState, initial?: ServerResults<T>);
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => Snapshot<T>;
+    private set;
+    /** A visitor's change. Changes to the query wait for a pause in typing; the others search at once. */
+    update(change: (state: SearchState) => SearchState): void;
+    /** A state from outside, such as the URL after Back. */
+    adopt(state: SearchState): void;
+    /** A new client or config, from changed props. */
+    configure(client: SearchBrowserClient, config: SearchConfig): void;
+    get settings(): SearchConfig;
+    /** Searches unless the results already answer the current state; with a state, such as the
+     * URL's, adopts it first. */
+    start(state?: SearchState): void;
+    stop(): void;
+    private resultsFor;
+    private search;
+    /** A did-you-mean suggestion for a request that found nothing. */
+    suggest(request: SearchRequest, signal: AbortSignal): Promise<DidYouMean | null>;
+    /** Adds the next page's hits to the current ones. */
+    loadMore(): void;
+}