@wherabouts/react 0.1.2 → 0.2.0

package/LICENSE

@@ -1,21 +1,15 @@
-MIT License
+Copyright (c) 2026 Wherabouts. All rights reserved.
 
-Copyright (c) 2026 Joseph Amani
+This software and associated documentation files (the "SDK") are the proprietary
+property of Wherabouts. The SDK is licensed, not sold, and is made available solely
+for use in connection with the Wherabouts location API by parties holding valid
+Wherabouts API credentials, subject to the Wherabouts Terms of Service.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Permission is NOT granted to use, copy, modify, merge, publish, distribute,
+sublicense, or sell copies of the SDK except as expressly permitted in writing by
+Wherabouts or as necessary to integrate with the Wherabouts API under a valid account.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+THE SDK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL WHERABOUTS BE LIABLE FOR
+ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OF THE SDK.

package/README.md

@@ -36,15 +36,24 @@ yarn add @wherabouts/react @wherabouts/sdk
 All hooks accept a `WheraboutsClient` instance as their first argument. Create one with your publishable API key from the [Wherabouts dashboard](https://wherabouts.com/dashboard).
 
 ```ts
-import { WheraboutsClient } from "@wherabouts/sdk";
+import { createWheraboutsClient } from "@wherabouts/sdk";
 
-const client = new WheraboutsClient({
+const client = createWheraboutsClient({
   apiKey: "pk_live_...", // publishable key — safe in browser
 });
 ```
 
 > Use a **publishable key** (`pk_live_…`) in browser code. Secret keys must stay server-side only.
 
+> **Keep a stable client reference.** Create the client once — at module scope or
+> with `useMemo` — and reuse it. The hooks list `client` in their effect
+> dependencies, so passing a freshly-created client on every render restarts the
+> request (and debounce) each render.
+>
+> ```tsx
+> const client = useMemo(() => createWheraboutsClient({ apiKey }), [apiKey]);
+> ```
+
 ---
 
 ## Hooks
@@ -94,30 +103,84 @@ function useAutocomplete(
 
 #### `UseAutocompleteOptions`
 
-| Option        | Type     | Default | Description                                      |
-|---------------|----------|---------|--------------------------------------------------|
-| `debounceMs`  | `number` | `300`   | Milliseconds to wait after last keystroke        |
-| `limit`       | `number` | —       | Maximum number of suggestions to return          |
-| `country`     | `string` | —       | ISO 3166-1 alpha-2 country code filter (e.g. `"AU"`) |
-| `state`       | `string` | —       | State or region name filter                      |
+| Option             | Type                            | Default | Description                                          |
+|--------------------|---------------------------------|---------|------------------------------------------------------|
+| `debounceMs`       | `number`                        | `300`   | Milliseconds to wait after last keystroke            |
+| `minLength`        | `number`                        | `2`     | Minimum trimmed query length before a request fires (the API requires `q` ≥ 2) |
+| `limit`            | `number`                        | —       | Maximum number of suggestions to return              |
+| `country`          | `string`                        | —       | ISO 3166-1 alpha-2 country code filter (e.g. `"AU"`) |
+| `state`            | `string`                        | —       | State or region name filter                          |
+| `lat` / `lng`      | `number`                        | —       | Bias results toward a coordinate (proximity)         |
+| `sessionToken`     | `string`                        | —       | Groups a run of keystrokes into one billable search (see `newSessionToken()`) |
+| `keepPreviousData` | `boolean`                       | `false` | Keep previous results visible while the next search loads (avoids dropdown flicker) |
+| `cache`            | `{ storage; ttlMs?: number }`   | —       | Opt-in client cache, e.g. `{ storage: sessionStorage, ttlMs: 60_000 }` |
 
 #### `UseAutocompleteResult`
 
-| Field      | Type                   | Description                                       |
-|------------|------------------------|---------------------------------------------------|
-| `query`    | `string`               | Current search string                             |
-| `setQuery` | `(q: string) => void`  | Stable setter — safe to pass directly to `onChange` |
-| `results`  | `AddressSuggestion[]`  | Matching address suggestions                      |
-| `loading`  | `boolean`              | `true` while a request is in flight               |
-| `error`    | `Error \| null`        | Last error, or `null`                             |
+| Field         | Type                   | Description                                       |
+|---------------|------------------------|---------------------------------------------------|
+| `query`       | `string`               | Current search string                             |
+| `setQuery`    | `(q: string) => void`  | Stable setter — safe to pass directly to `onChange` |
+| `results`     | `AddressSuggestion[]`  | Matching address suggestions                      |
+| `status`      | `"idle" \| "loading" \| "success" \| "empty" \| "error"` | Coarse state machine for rendering |
+| `loading`     | `boolean`              | `true` while a request is in flight               |
+| `rateLimited` | `boolean`              | `true` when the last request was rejected with HTTP 429 |
+| `error`       | `Error \| null`        | Last error, or `null`                             |
+| `reset`       | `() => void`           | Clear the query, results, and any in-flight request |
 
 **Behaviour notes:**
+- Queries shorter than `minLength` (default 2) never fire a request.
 - Empty or whitespace-only query immediately clears results without firing a request.
 - Each new keystroke cancels the previous pending request via `AbortController`.
 - `setQuery` is memoised with `useCallback` — it will not cause unnecessary re-renders.
 
 ---
 
+### `useCombobox`
+
+Headless [WAI-ARIA combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
+helpers for an accessible autocomplete dropdown — keyboard navigation
+(↑/↓/Home/End/Enter/Esc, with wrapping) and ARIA wiring. Bring your own markup;
+pair it with `useAutocomplete`.
+
+```tsx
+import { useAutocomplete, useCombobox } from "@wherabouts/react";
+
+function AddressCombobox({ client }) {
+  const { query, setQuery, results } = useAutocomplete(client);
+  const { getInputProps, getListboxProps, getItemProps, activeIndex } =
+    useCombobox({
+      id: "address",
+      count: results.length,
+      onSelect: (i) => setQuery(results[i]?.formattedAddress ?? ""),
+    });
+
+  return (
+    <>
+      <input
+        {...getInputProps()}
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+      />
+      <ul {...getListboxProps()}>
+        {results.map((r, i) => (
+          <li key={r.id} {...getItemProps(i)} data-active={i === activeIndex}>
+            {r.formattedAddress}
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+}
+```
+
+`getInputProps()` / `getListboxProps()` / `getItemProps(index)` return the
+`role`, `aria-*`, and event handlers for each element. The pure building blocks
+(`comboboxReducer`, `keyToAction`, `buildInputProps`/`buildListboxProps`/`buildItemProps`)
+are also exported for advanced use.
+
+---
+
 ### `useReverseGeocode`
 
 Resolves a latitude/longitude coordinate to the nearest address. Pass `null` to reset.
@@ -229,6 +292,32 @@ function useZoneContains(
 
 ---
 
+### Routing hooks — `useDirections` / `useMatrix` / `useIsochrone`
+
+Fetch routing results that re-run when their params change and abort the previous
+request. Pass `null` params to stay idle. Each returns `{ data, loading, error }`.
+
+```tsx
+import { useDirections } from "@wherabouts/react";
+
+function Route({ client }) {
+  const { data, loading, error } = useDirections(client, {
+    from: "-33.865,151.209",
+    to: "-33.8,151.0",
+    profile: "driving", // "driving" | "walking" | "cycling"
+  });
+
+  if (loading) return <p>Routing…</p>;
+  if (error) return <p>Error: {error.message}</p>;
+  return <p>{data ? `${data.distance_m} m, ${data.duration_s} s` : null}</p>;
+}
+```
+
+- `useMatrix(client, { sources, destinations, profile? } | null)` — duration/distance matrix.
+- `useIsochrone(client, { origin, durationSeconds | distanceMeters, profile? } | null)` — reachability polygon.
+
+---
+
 ## Using the browser Geolocation API
 
 A common pattern — combine the browser's `navigator.geolocation` with these hooks:

package/dist/index.cjs

@@ -1,66 +1,361 @@
 'use strict';
 
 var react = require('react');
+var sdk = require('@wherabouts/sdk');
+
+// src/combobox.ts
+var INITIAL_COMBOBOX_STATE = {
+  isOpen: false,
+  activeIndex: -1
+};
+function comboboxReducer(state, action) {
+  switch (action.type) {
+    case "next": {
+      if (action.count === 0) {
+        return state;
+      }
+      const activeIndex = state.activeIndex >= action.count - 1 ? 0 : state.activeIndex + 1;
+      return { isOpen: true, activeIndex };
+    }
+    case "prev": {
+      if (action.count === 0) {
+        return state;
+      }
+      const activeIndex = state.activeIndex <= 0 ? action.count - 1 : state.activeIndex - 1;
+      return { isOpen: true, activeIndex };
+    }
+    case "first":
+      return action.count === 0 ? state : { isOpen: true, activeIndex: 0 };
+    case "last":
+      return action.count === 0 ? state : { isOpen: true, activeIndex: action.count - 1 };
+    case "set":
+      return { isOpen: true, activeIndex: action.index };
+    case "open":
+      return { ...state, isOpen: true };
+    case "close":
+    case "select":
+      return INITIAL_COMBOBOX_STATE;
+    default:
+      return INITIAL_COMBOBOX_STATE;
+  }
+}
+function keyToAction(key, count) {
+  switch (key) {
+    case "ArrowDown":
+      return { type: "next", count };
+    case "ArrowUp":
+      return { type: "prev", count };
+    case "Home":
+      return { type: "first", count };
+    case "End":
+      return { type: "last", count };
+    case "Escape":
+      return { type: "close" };
+    case "Enter":
+      return { type: "select" };
+    default:
+      return null;
+  }
+}
+var listboxId = (id) => `${id}-listbox`;
+var optionId = (id, index) => `${id}-option-${index}`;
+function buildInputProps(id, state) {
+  return {
+    role: "combobox",
+    "aria-autocomplete": "list",
+    "aria-expanded": state.isOpen,
+    "aria-controls": listboxId(id),
+    "aria-activedescendant": state.isOpen && state.activeIndex >= 0 ? optionId(id, state.activeIndex) : void 0
+  };
+}
+function buildListboxProps(id) {
+  return { id: listboxId(id), role: "listbox" };
+}
+function buildItemProps(id, index, state) {
+  return {
+    role: "option",
+    id: optionId(id, index),
+    "aria-selected": state.activeIndex === index
+  };
+}
+function useCombobox(options) {
+  const { id, count, onSelect } = options;
+  const [state, dispatch] = react.useReducer(comboboxReducer, INITIAL_COMBOBOX_STATE);
+  const open = react.useCallback(() => dispatch({ type: "open" }), []);
+  const close = react.useCallback(() => dispatch({ type: "close" }), []);
+  const reset = react.useCallback(() => dispatch({ type: "reset" }), []);
+  const setActiveIndex = react.useCallback(
+    (index) => dispatch({ type: "set", index }),
+    []
+  );
+  const getInputProps = react.useCallback(
+    () => ({
+      ...buildInputProps(id, state),
+      onFocus: () => dispatch({ type: "open" }),
+      onBlur: () => dispatch({ type: "close" }),
+      onKeyDown: (event) => {
+        const action = keyToAction(event.key, count);
+        if (!action) {
+          return;
+        }
+        if (action.type === "select") {
+          if (state.activeIndex >= 0) {
+            event.preventDefault();
+            onSelect?.(state.activeIndex);
+          }
+          dispatch({ type: "select" });
+          return;
+        }
+        event.preventDefault();
+        dispatch(action);
+      }
+    }),
+    [id, state, count, onSelect]
+  );
+  const getListboxProps = react.useCallback(() => buildListboxProps(id), [id]);
+  const getItemProps = react.useCallback(
+    (index) => ({
+      ...buildItemProps(id, index, state),
+      onMouseEnter: () => dispatch({ type: "set", index }),
+      onMouseDown: (event) => {
+        event.preventDefault();
+        onSelect?.(index);
+        dispatch({ type: "select" });
+      }
+    }),
+    [id, state, onSelect]
+  );
+  return {
+    isOpen: state.isOpen,
+    activeIndex: state.activeIndex,
+    open,
+    close,
+    reset,
+    setActiveIndex,
+    getInputProps,
+    getListboxProps,
+    getItemProps
+  };
+}
+
+// src/autocomplete-cache.ts
+var KEY_PREFIX = "wh:ac:";
+function buildCacheKey(parts) {
+  const q = parts.q.trim().toLowerCase();
+  return JSON.stringify([
+    q,
+    parts.country ?? "",
+    parts.state ?? "",
+    parts.limit ?? "",
+    parts.lat ?? "",
+    parts.lng ?? ""
+  ]);
+}
+function readCache(storage, key, ttlMs, now) {
+  const raw = storage.getItem(KEY_PREFIX + key);
+  if (raw === null) {
+    return null;
+  }
+  let entry;
+  try {
+    entry = JSON.parse(raw);
+  } catch {
+    storage.removeItem(KEY_PREFIX + key);
+    return null;
+  }
+  if (typeof entry?.t !== "number" || !Array.isArray(entry.results) || now - entry.t > ttlMs) {
+    storage.removeItem(KEY_PREFIX + key);
+    return null;
+  }
+  return entry.results;
+}
+function writeCache(storage, key, results, now) {
+  const entry = { results, t: now };
+  try {
+    storage.setItem(KEY_PREFIX + key, JSON.stringify(entry));
+  } catch {
+  }
+}
 
 // src/use-autocomplete.ts
+var DEFAULT_DEBOUNCE_MS = 300;
+var DEFAULT_MIN_LENGTH = 2;
+var DEFAULT_CACHE_TTL_MS = 6e4;
+function deriveStatus(s) {
+  if (s.query.trim().length < s.minLength) {
+    return "idle";
+  }
+  if (s.loading) {
+    return "loading";
+  }
+  if (s.error) {
+    return "error";
+  }
+  return s.results.length === 0 ? "empty" : "success";
+}
+function planSearch(args) {
+  if (args.trimmed.length < args.minLength) {
+    return { kind: "idle" };
+  }
+  if (args.cacheStorage) {
+    const hit = readCache(
+      args.cacheStorage,
+      buildCacheKey(args.keyParts),
+      args.cacheTtl,
+      Date.now()
+    );
+    if (hit) {
+      return { kind: "cache", results: hit };
+    }
+  }
+  return { kind: "fetch" };
+}
+async function executeAutocomplete(client, params, controller, actions) {
+  try {
+    const res = await client.addresses.autocomplete(params, {
+      signal: controller.signal
+    });
+    if (!controller.signal.aborted) {
+      actions.onSuccess(res.results);
+    }
+  } catch (e) {
+    if (!controller.signal.aborted) {
+      const err = e instanceof Error ? e : new Error(String(e));
+      actions.onError(err, sdk.isRateLimitError(e));
+    }
+  } finally {
+    if (!controller.signal.aborted) {
+      actions.onSettled();
+    }
+  }
+}
+function cancelPending(timer, controller) {
+  if (timer) {
+    clearTimeout(timer);
+  }
+  controller?.abort();
+}
 function useAutocomplete(client, options = {}) {
-  const { debounceMs = 300, limit, country, state } = options;
+  const {
+    debounceMs = DEFAULT_DEBOUNCE_MS,
+    minLength = DEFAULT_MIN_LENGTH,
+    limit,
+    country,
+    state,
+    lat,
+    lng,
+    sessionToken,
+    keepPreviousData = false,
+    cache
+  } = options;
   const [query, setQuery] = react.useState("");
   const [results, setResults] = react.useState([]);
   const [loading, setLoading] = react.useState(false);
   const [error, setError] = react.useState(null);
+  const [rateLimited, setRateLimited] = react.useState(false);
   const abortRef = react.useRef(null);
   const timerRef = react.useRef(null);
   const handleSetQuery = react.useCallback((q) => {
     setQuery(q);
   }, []);
+  const reset = react.useCallback(() => {
+    cancelPending(timerRef.current, abortRef.current);
+    setQuery("");
+    setResults([]);
+    setLoading(false);
+    setError(null);
+    setRateLimited(false);
+  }, []);
+  const cacheStorage = cache?.storage;
+  const cacheTtl = cache?.ttlMs ?? DEFAULT_CACHE_TTL_MS;
   react.useEffect(() => {
-    if (timerRef.current) {
-      clearTimeout(timerRef.current);
-    }
-    if (abortRef.current) {
-      abortRef.current.abort();
+    cancelPending(timerRef.current, abortRef.current);
+    const trimmed = query.trim();
+    const keyParts = {
+      q: trimmed,
+      country,
+      state,
+      limit,
+      lat,
+      lng
+    };
+    const plan = planSearch({
+      trimmed,
+      minLength,
+      cacheStorage,
+      cacheTtl,
+      keyParts
+    });
+    setError(null);
+    setRateLimited(false);
+    if (plan.kind === "idle") {
+      if (!keepPreviousData) {
+        setResults([]);
+      }
+      setLoading(false);
+      return;
     }
-    if (!query.trim()) {
-      setResults([]);
+    if (plan.kind === "cache") {
+      setResults(plan.results);
       setLoading(false);
-      setError(null);
       return;
     }
+    if (!keepPreviousData) {
+      setResults([]);
+    }
     setLoading(true);
     timerRef.current = setTimeout(async () => {
       const controller = new AbortController();
       abortRef.current = controller;
-      setError(null);
-      try {
-        const res = await client.addresses.autocomplete(
-          { q: query, limit, country, state },
-          { signal: controller.signal }
-        );
-        if (!controller.signal.aborted) {
-          setResults(res.results);
+      await executeAutocomplete(
+        client,
+        { q: trimmed, limit, country, state, lat, lng, sessionToken },
+        controller,
+        {
+          onSuccess: (r) => {
+            setResults(r);
+            if (cacheStorage) {
+              writeCache(cacheStorage, buildCacheKey(keyParts), r, Date.now());
+            }
+          },
+          onError: (err, limited) => {
+            setError(err);
+            setRateLimited(limited);
+            if (!keepPreviousData) {
+              setResults([]);
+            }
+          },
+          onSettled: () => setLoading(false)
         }
-      } catch (e) {
-        if (!controller.signal.aborted) {
-          setError(e instanceof Error ? e : new Error(String(e)));
-          setResults([]);
-        }
-      } finally {
-        if (!controller.signal.aborted) {
-          setLoading(false);
-        }
-      }
+      );
     }, debounceMs);
-    return () => {
-      if (timerRef.current) {
-        clearTimeout(timerRef.current);
-      }
-      if (abortRef.current) {
-        abortRef.current.abort();
-      }
-    };
-  }, [query, debounceMs, limit, country, state, client]);
-  return { query, setQuery: handleSetQuery, results, loading, error };
+    return () => cancelPending(timerRef.current, abortRef.current);
+  }, [
+    query,
+    debounceMs,
+    minLength,
+    limit,
+    country,
+    state,
+    lat,
+    lng,
+    sessionToken,
+    keepPreviousData,
+    cacheStorage,
+    cacheTtl,
+    client
+  ]);
+  const status = deriveStatus({ query, minLength, loading, error, results });
+  return {
+    query,
+    setQuery: handleSetQuery,
+    results,
+    loading,
+    error,
+    rateLimited,
+    reset,
+    status
+  };
 }
 function useReverseGeocode(client, coords) {
   const [address, setAddress] = react.useState(null);
@@ -103,6 +398,71 @@ function useReverseGeocode(client, coords) {
   }, [coords?.lat, coords?.lng, client]);
   return { address, distance, loading, error };
 }
+
+// src/async-resource.ts
+async function runResource(promise, signal, actions) {
+  try {
+    const data = await promise;
+    if (!signal.aborted) {
+      actions.onSuccess(data);
+    }
+  } catch (e) {
+    if (!signal.aborted) {
+      actions.onError(e instanceof Error ? e : new Error(String(e)));
+    }
+  } finally {
+    if (!signal.aborted) {
+      actions.onSettled();
+    }
+  }
+}
+
+// src/use-routing.ts
+function useRoutingResource(client, params, call) {
+  const [data, setData] = react.useState(null);
+  const [loading, setLoading] = react.useState(false);
+  const [error, setError] = react.useState(null);
+  const abortRef = react.useRef(null);
+  const key = params ? JSON.stringify(params) : null;
+  react.useEffect(() => {
+    if (abortRef.current) {
+      abortRef.current.abort();
+    }
+    if (!params) {
+      setData(null);
+      setLoading(false);
+      setError(null);
+      return;
+    }
+    const controller = new AbortController();
+    abortRef.current = controller;
+    setLoading(true);
+    setError(null);
+    runResource(
+      call(client, params, { signal: controller.signal }),
+      controller.signal,
+      {
+        onSuccess: setData,
+        onError: setError,
+        onSettled: () => setLoading(false)
+      }
+    );
+    return () => controller.abort();
+  }, [key, client, call]);
+  return { data, loading, error };
+}
+var directionsCall = (client, params, options) => client.routing.directions(params, options);
+var matrixCall = (client, params, options) => client.routing.matrix(params, options);
+var isochroneCall = (client, params, options) => client.routing.isochrone(params, options);
+function useDirections(client, params) {
+  return useRoutingResource(client, params, directionsCall);
+}
+function useMatrix(client, params) {
+  return useRoutingResource(client, params, matrixCall);
+}
+function useIsochrone(client, params) {
+  return useRoutingResource(client, params, isochroneCall);
+}
 function useZoneContains(client, coords) {
   const [zones, setZones] = react.useState([]);
   const [loading, setLoading] = react.useState(false);
@@ -142,7 +502,18 @@ function useZoneContains(client, coords) {
   return { zones, loading, error };
 }
 
+exports.INITIAL_COMBOBOX_STATE = INITIAL_COMBOBOX_STATE;
+exports.buildInputProps = buildInputProps;
+exports.buildItemProps = buildItemProps;
+exports.buildListboxProps = buildListboxProps;
+exports.comboboxReducer = comboboxReducer;
+exports.deriveStatus = deriveStatus;
+exports.keyToAction = keyToAction;
 exports.useAutocomplete = useAutocomplete;
+exports.useCombobox = useCombobox;
+exports.useDirections = useDirections;
+exports.useIsochrone = useIsochrone;
+exports.useMatrix = useMatrix;
 exports.useReverseGeocode = useReverseGeocode;
 exports.useZoneContains = useZoneContains;
 //# sourceMappingURL=index.cjs.map