@findlane/browser 0.4.2 → 0.5.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type SearchRequest = {
     q?: string;
-    /** A sort ID from the index settings, or "relevance". */
+    /** A sort ID from the index settings, "relevance", or "distance" (with `near`). */
     sort?: string;
     /** Field values to keep: a value, `{ in: [...] }`, or a range `{ gte, lte }` for numbers and dates. */
     filters?: Record<string, unknown>;
@@ -26,12 +26,40 @@ export type SearchRequest = {
         preTag?: string;
         postTag?: string;
     };
+    /** Nearest first from a point, with each hit's `distance` in meters; `radius` (meters) keeps only what's
+     * within it. With a query, the best matches come first and distance orders them. Needs the index's
+     * location field. Records without a location are left out.
+     * `{ visitor: true }` uses the visitor's approximate location from their IP address (about their city's
+     * center); `near` in the response says where that was, or null when it isn't known. */
+    near?: GeoPoint & {
+        radius?: number;
+    } | {
+        visitor: true;
+        radius?: number;
+    };
+    /** Only records inside a box, in degrees, such as a map's visible area. West greater than east crosses the
+     * antimeridian. */
+    within?: GeoBox;
+};
+/** A point in degrees: lat from -90 to 90, lng from -180 to 180. */
+export type GeoPoint = {
+    lat: number;
+    lng: number;
+};
+/** A box in degrees, such as a map's bounds. */
+export type GeoBox = {
+    north: number;
+    south: number;
+    east: number;
+    west: number;
 };
 export type SearchResponse<T> = {
     hits: {
         id: string;
         score: number | null;
         record: T;
+        /** With `near`: meters from the point. */
+        distance?: number;
         /** With `highlight`: matched searchable fields by path; list fields give one string per value. */
         highlights?: Record<string, string | string[]>;
     }[];
@@ -48,6 +76,8 @@ export type SearchResponse<T> = {
     }>;
     tookMs: number;
     sort?: string;
+    /** With `near`: the point distances are from, or null when the visitor's location isn't known. */
+    near?: GeoPoint | null;
     /** With the index's `didYouMean` setting: the query with the words typo tolerance corrected, when the
      * results matched some words only by typo ("Showing results for …"), else null. */
     didYouMean?: DidYouMean | null;

package/dist/react/index.d.ts

@@ -1,10 +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, useDidYouMean, useHits, useLoadMore, usePagination, useRange, useRefinementList, useSearchBox, useSearchState, useSortBy, useToggle, type Range, type Refinement, type SearchProviderProps, } from "./search-provider.js";
+export { SearchProvider, useCurrentRefinements, useDidYouMean, useGeoSearch, useHits, useLoadMore, usePagination, useRange, useRefinementList, useSearchBox, useSearchState, useSortBy, useToggle, type Range, type Refinement, type SearchProviderProps, } from "./search-provider.js";
 export { CurrentRefinements, DefaultHit, DidYouMean, 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 { emptyState, stateFromUrl, urlFromState, type Hit, type Near, type SearchConfig, type SearchState, type UrlParams, } from "./state.js";
 export type { ServerResults, StateChange } from "./store.js";

package/dist/react/index.js

@@ -3,7 +3,7 @@
 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 { SearchProvider, useCurrentRefinements, useDidYouMean, useGeoSearch, 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";

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

@@ -1,8 +1,8 @@
 import { type ReactNode } from "react";
-import type { DidYouMean } from "../index.js";
+import type { DidYouMean, GeoBox } 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";
+import { type Near, 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
@@ -90,6 +90,20 @@ export declare function useToggle(field: string, value?: unknown): {
     set: (next: boolean) => void;
     toggle: () => void;
 };
+/** Location search, with the index's location field: nearest first from a point or the visitor, and
+ * only what a map shows. `center` is where distances are from: the point asked for, or the visitor's
+ * location once known (null when it isn't). A map's moves (`setWithin`) replace the page's history
+ * entry rather than adding one, so Back doesn't step through every drag. */
+export declare function useGeoSearch(): {
+    near: Near | undefined;
+    within: GeoBox | undefined;
+    center: import("../index.js").GeoPoint | null | undefined;
+    setNear: (near: Near | undefined) => void;
+    /** Near the visitor's approximate location, from their IP address; with radius (meters), only within it. */
+    nearVisitor: (radius?: number) => void;
+    setWithin: (within: GeoBox | undefined) => void;
+    clear: () => void;
+};
 export declare function useSortBy(): {
     /** The chosen sort ID; undefined for the index's default. */
     sort: string | undefined;

package/dist/react/search-provider.js

@@ -169,6 +169,24 @@ export function useToggle(field, value = true) {
     const set = (next) => store.update(withFilter(field, next ? value : undefined));
     return { on, set, toggle: () => set(!on) };
 }
+/** Location search, with the index's location field: nearest first from a point or the visitor, and
+ * only what a map shows. `center` is where distances are from: the point asked for, or the visitor's
+ * location once known (null when it isn't). A map's moves (`setWithin`) replace the page's history
+ * entry rather than adding one, so Back doesn't step through every drag. */
+export function useGeoSearch() {
+    const [{ state, results }, store] = useSnapshot();
+    const setNear = (near) => store.update(({ near: _, ...current }) => ({ ...current, page: 0, ...(near ? { near } : {}) }));
+    return {
+        near: state.near,
+        within: state.within,
+        center: results?.response.near,
+        setNear,
+        /** Near the visitor's approximate location, from their IP address; with radius (meters), only within it. */
+        nearVisitor: (radius) => setNear({ visitor: true, ...(radius ? { radius } : {}) }),
+        setWithin: (within) => store.update(({ within: _, ...current }) => ({ ...current, page: 0, ...(within ? { within } : {}) }), false),
+        clear: () => store.update(({ near: _, within: __, ...current }) => ({ ...current, page: 0 })),
+    };
+}
 export function useSortBy() {
     const [{ state }, store] = useSnapshot();
     return {

package/dist/react/state.d.ts

@@ -1,5 +1,7 @@
-import type { SearchRequest, SearchResponse } from "../index.js";
+import type { GeoBox, SearchRequest, SearchResponse } from "../index.js";
 export type Hit<T> = SearchResponse<T>["hits"][number];
+/** A point (or the visitor's location) to search near; see `near` in SearchRequest. */
+export type Near = NonNullable<SearchRequest["near"]>;
 /** What a visitor has chosen on a results page. It round-trips through the URL. */
 export type SearchState = {
     q: string;
@@ -11,6 +13,10 @@ export type SearchState = {
     filters: Record<string, unknown>;
     /** The page, from 0. */
     page: number;
+    /** Nearest first from a point or the visitor (useGeoSearch). */
+    near?: Near;
+    /** Only records inside a box, such as a map's visible area (useGeoSearch). */
+    within?: GeoBox;
 };
 export type SearchConfig = {
     /** Fields to count values for. A facet's own selections don't narrow its counts, so its other
@@ -23,6 +29,9 @@ export type SearchConfig = {
     facetStats?: string[];
     /** Filters always applied, such as `{ published: true }`. They aren't shown as refinements. */
     filters?: Record<string, unknown>;
+    /** Where searches are near unless the state says otherwise, such as `{ visitor: true }` for the
+     * visitor's approximate location. Needs the index's location field. */
+    near?: Near;
     /** Hits per page: 1–50 (default 20). */
     pageSize?: number;
     /** The record fields to return (`attributesToRetrieve`); all of them when left out. */

package/dist/react/state.js

@@ -16,6 +16,8 @@ export function planSearch(config, state) {
     return {
         q: state.q,
         ...(state.sort ? { sort: state.sort } : {}),
+        ...(state.near ?? config.near ? { near: state.near ?? config.near } : {}),
+        ...(state.within ? { within: state.within } : {}),
         ...(Object.keys(filters).length ? { filters } : {}),
         ...(facets.length ? { facets } : {}),
         ...(disjunctive.length ? { disjunctiveFacets: disjunctive } : {}),
@@ -62,6 +64,33 @@ function formatValue(value) {
         return value;
     return JSON.stringify(value);
 }
+// Locations in the URL: near=51.5074,-0.1278 (with ,5000 for a radius in meters) or near=visitor (,5000),
+// and within=north,east,south,west, the order CSS gives a box's sides.
+const coordinate = (value) => String(Math.round(value * 1e6) / 1e6);
+function parseNear(text) {
+    const parts = text?.split(",") ?? [];
+    const numbers = parts.map(Number);
+    const radius = (value) => value !== undefined && value > 0 ? { radius: value } : {};
+    if (parts[0] === "visitor" && parts.length <= 2 && (parts.length === 1 || numbers[1] > 0))
+        return { visitor: true, ...radius(numbers[1]) };
+    const [lat, lng] = numbers;
+    if (parts.length < 2 || parts.length > 3 || numbers.some((value) => !Number.isFinite(value)) ||
+        Math.abs(lat) > 90 || Math.abs(lng) > 180)
+        return undefined;
+    return { lat: lat, lng: lng, ...radius(numbers[2]) };
+}
+function parseWithin(text) {
+    const sides = text?.split(",").map(Number) ?? [];
+    if (sides.length !== 4 || sides.some((value) => !Number.isFinite(value)))
+        return undefined;
+    const [north, east, south, west] = sides;
+    return north > south && north <= 90 && south >= -90 && Math.abs(east) <= 180 && Math.abs(west) <= 180
+        ? { north, east, south, west } : undefined;
+}
+function formatNear(near) {
+    const at = "visitor" in near ? ["visitor"] : [coordinate(near.lat), coordinate(near.lng)];
+    return [...at, ...(near.radius ? [String(near.radius)] : [])].join(",");
+}
 function paramsFrom(search) {
     if (typeof search === "string" || search instanceof URLSearchParams)
         return new URLSearchParams(search);
@@ -87,12 +116,16 @@ export function stateFromUrl(search, config) {
             filters[field] = parseValue(value);
     }
     const page = Number(params.get("page"));
+    const near = parseNear(params.get("near"));
+    const within = parseWithin(params.get("within"));
     return {
         q: params.get("q") ?? "",
         ...(params.get("sort") ? { sort: params.get("sort") } : {}),
         refinements,
         filters,
         page: Number.isInteger(page) && page > 1 ? page - 1 : 0,
+        ...(near ? { near } : {}),
+        ...(within ? { within } : {}),
     };
 }
 /** The query string for a state, followed by the URL's other parameters. */
@@ -111,7 +144,11 @@ export function urlFromState(state, config, current = "") {
             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 ?? [])]);
+    if (state.near)
+        params.set("near", formatNear(state.near));
+    if (state.within)
+        params.set("within", [state.within.north, state.within.east, state.within.south, state.within.west].map(coordinate).join(","));
+    const own = new Set(["q", "sort", "page", "near", "within", ...(config.facets ?? []), ...(config.filterFields ?? [])]);
     for (const [key, value] of new URLSearchParams(current))
         if (!own.has(key))
             params.append(key, value);

package/dist/react/store.d.ts

@@ -47,8 +47,9 @@ export declare class SearchStore<T = unknown> {
     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 visitor's change. Changes to the query wait for a pause in typing; the others search at once.
+     * `push` overrides how it reaches the history, as a map's moves replace the entry. */
+    update(change: (state: SearchState) => SearchState, push?: boolean): void;
     /** A state from outside, such as the URL after Back. */
     adopt(state: SearchState): void;
     /** A new client or config, from changed props. */

package/dist/react/store.js

@@ -30,15 +30,16 @@ export class SearchStore {
         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) {
+    /** A visitor's change. Changes to the query wait for a pause in typing; the others search at once.
+     * `push` overrides how it reaches the history, as a map's moves replace the entry. */
+    update(change, push) {
         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.onChange?.(state, { push: push ?? !typing });
         this.search(typing);
     }
     /** A state from outside, such as the URL after Back. */

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

@@ -36,6 +36,7 @@ export declare function useAutocomplete<T = Record<string, unknown>>(options?: A
         id: string;
         score: number | null;
         record: T;
+        distance?: number;
         highlights?: Record<string, string | string[]>;
     }[];
     total: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@findlane/browser",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Findlane browser SDK: fast, typo-tolerant public search from the browser with an index's public ID, plus React hooks and components.",
   "keywords": ["findlane", "search", "full-text search", "typo tolerance", "instant search", "ecommerce search", "browser", "react", "autocomplete"],
   "license": "MIT",