@wherabouts/react 0.1.1 → 0.2.0

package/dist/index.d.cts

@@ -1,18 +1,156 @@
-import { AddressSuggestion, WheraboutsClient, ReverseGeocodeAddress, ZoneRecord } from '@wherabouts/sdk';
+import { KeyboardEvent, MouseEvent } from 'react';
+import { AddressSuggestion, WheraboutsClient, ReverseGeocodeAddress, DirectionsParams, DirectionsResponse, IsochroneParams, IsochroneResponse, MatrixParams, MatrixResponse, ZoneRecord } from '@wherabouts/sdk';
 
+/**
+ * Minimal structural view of the Web Storage API (sessionStorage/localStorage).
+ * Declared locally so the package type-checks with no DOM lib.
+ */
+interface StorageLike {
+    getItem(key: string): string | null;
+    removeItem(key: string): void;
+    setItem(key: string, value: string): void;
+}
+
+/**
+ * Headless WAI-ARIA combobox helper for autocomplete dropdowns. Provides the
+ * keyboard state machine (↑/↓/Home/End/Enter/Esc, wrapping) and ARIA prop
+ * getters so an input + listbox is accessible by default. Bring your own
+ * markup and data; this hook owns only the open/active-option state.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+ */
+interface ComboboxState {
+    /** Index of the visually-active option, or -1 when none is active. */
+    activeIndex: number;
+    isOpen: boolean;
+}
+type ComboboxAction = {
+    type: "next";
+    count: number;
+} | {
+    type: "prev";
+    count: number;
+} | {
+    type: "first";
+    count: number;
+} | {
+    type: "last";
+    count: number;
+} | {
+    type: "set";
+    index: number;
+} | {
+    type: "open";
+} | {
+    type: "close";
+} | {
+    type: "select";
+} | {
+    type: "reset";
+};
+declare const INITIAL_COMBOBOX_STATE: ComboboxState;
+/** Pure transition function for the combobox keyboard state machine. */
+declare function comboboxReducer(state: ComboboxState, action: ComboboxAction): ComboboxState;
+/** Map a keyboard key to a combobox action, or null when it is irrelevant. */
+declare function keyToAction(key: string, count: number): ComboboxAction | null;
+interface ComboboxInputProps {
+    "aria-activedescendant": string | undefined;
+    "aria-autocomplete": "list";
+    "aria-controls": string;
+    "aria-expanded": boolean;
+    role: "combobox";
+}
+interface ComboboxListboxProps {
+    id: string;
+    role: "listbox";
+}
+interface ComboboxItemProps {
+    "aria-selected": boolean;
+    id: string;
+    role: "option";
+}
+/** Build the ARIA attributes for the combobox input — pure. */
+declare function buildInputProps(id: string, state: ComboboxState): ComboboxInputProps;
+/** Build the ARIA attributes for the listbox container — pure. */
+declare function buildListboxProps(id: string): ComboboxListboxProps;
+/** Build the ARIA attributes for an option at `index` — pure. */
+declare function buildItemProps(id: string, index: number, state: ComboboxState): ComboboxItemProps;
+interface UseComboboxOptions {
+    /** Number of options currently rendered (drives wrapping/bounds). */
+    count: number;
+    /** Stable id root; option/listbox ids derive from it. */
+    id: string;
+    /** Called when an option is chosen via Enter or pointer. */
+    onSelect?: (index: number) => void;
+}
+interface UseComboboxResult {
+    activeIndex: number;
+    close: () => void;
+    getInputProps: () => ComboboxInputProps & {
+        onBlur: () => void;
+        onFocus: () => void;
+        onKeyDown: (event: KeyboardEvent) => void;
+    };
+    getItemProps: (index: number) => ComboboxItemProps & {
+        onMouseDown: (event: MouseEvent) => void;
+        onMouseEnter: () => void;
+    };
+    getListboxProps: () => ComboboxListboxProps;
+    isOpen: boolean;
+    open: () => void;
+    reset: () => void;
+    setActiveIndex: (index: number) => void;
+}
+declare function useCombobox(options: UseComboboxOptions): UseComboboxResult;
+
+type AutocompleteStatus = "idle" | "loading" | "success" | "empty" | "error";
+/** Opt-in client-side cache for repeated/back-and-forth queries. */
+interface AutocompleteCacheConfig {
+    /** A `sessionStorage`-like store. Entries are namespaced under `wh:ac:`. */
+    storage: StorageLike;
+    /** Entry lifetime in ms (default 60_000). */
+    ttlMs?: number;
+}
 interface UseAutocompleteOptions {
+    cache?: AutocompleteCacheConfig;
     country?: string;
     debounceMs?: number;
+    /** Keep the previous results visible while a new search runs / on error. */
+    keepPreviousData?: boolean;
+    /** Latitude for proximity boosting (pair with `lng`). */
+    lat?: number;
     limit?: number;
+    /** Longitude for proximity boosting (pair with `lat`). */
+    lng?: number;
+    /** Minimum trimmed query length before a request fires (default 2). */
+    minLength?: number;
+    /** Groups keystrokes into one billable session; see `newSessionToken()`. */
+    sessionToken?: string;
     state?: string;
 }
 interface UseAutocompleteResult {
     error: Error | null;
     loading: boolean;
     query: string;
+    /** True when the last request was rejected with HTTP 429. */
+    rateLimited: boolean;
+    /** Clear the query, results, and any in-flight request. */
+    reset: () => void;
     results: AddressSuggestion[];
     setQuery: (q: string) => void;
+    status: AutocompleteStatus;
 }
+/**
+ * Derive a single coarse status from the hook's raw flags. Exported for
+ * unit-testing and for consumers who prefer a state machine to booleans.
+ */
+declare function deriveStatus(s: {
+    error: Error | null;
+    loading: boolean;
+    minLength: number;
+    query: string;
+    results: AddressSuggestion[];
+}): AutocompleteStatus;
 declare function useAutocomplete(client: WheraboutsClient, options?: UseAutocompleteOptions): UseAutocompleteResult;
 
 interface LatLng {
@@ -27,6 +165,18 @@ interface UseReverseGeocodeResult {
 }
 declare function useReverseGeocode(client: WheraboutsClient, coords: LatLng | null): UseReverseGeocodeResult;
 
+interface RoutingResourceResult<T> {
+    data: T | null;
+    error: Error | null;
+    loading: boolean;
+}
+/** Fetch turn-by-turn directions; pass `null` to stay idle. */
+declare function useDirections(client: WheraboutsClient, params: DirectionsParams | null): RoutingResourceResult<DirectionsResponse>;
+/** Fetch a duration/distance matrix; pass `null` to stay idle. */
+declare function useMatrix(client: WheraboutsClient, params: MatrixParams | null): RoutingResourceResult<MatrixResponse>;
+/** Fetch an isochrone polygon; pass `null` to stay idle. */
+declare function useIsochrone(client: WheraboutsClient, params: IsochroneParams | null): RoutingResourceResult<IsochroneResponse>;
+
 interface UseZoneContainsResult {
     error: Error | null;
     loading: boolean;
@@ -34,4 +184,4 @@ interface UseZoneContainsResult {
 }
 declare function useZoneContains(client: WheraboutsClient, coords: LatLng | null): UseZoneContainsResult;
 
-export { type LatLng, type UseAutocompleteOptions, type UseAutocompleteResult, type UseReverseGeocodeResult, type UseZoneContainsResult, useAutocomplete, useReverseGeocode, useZoneContains };
+export { type AutocompleteCacheConfig, type AutocompleteStatus, type ComboboxAction, type ComboboxInputProps, type ComboboxItemProps, type ComboboxListboxProps, type ComboboxState, INITIAL_COMBOBOX_STATE, type LatLng, type RoutingResourceResult, type StorageLike, type UseAutocompleteOptions, type UseAutocompleteResult, type UseComboboxOptions, type UseComboboxResult, type UseReverseGeocodeResult, type UseZoneContainsResult, buildInputProps, buildItemProps, buildListboxProps, comboboxReducer, deriveStatus, keyToAction, useAutocomplete, useCombobox, useDirections, useIsochrone, useMatrix, useReverseGeocode, useZoneContains };

package/dist/index.d.ts

@@ -1,18 +1,156 @@
-import { AddressSuggestion, WheraboutsClient, ReverseGeocodeAddress, ZoneRecord } from '@wherabouts/sdk';
+import { KeyboardEvent, MouseEvent } from 'react';
+import { AddressSuggestion, WheraboutsClient, ReverseGeocodeAddress, DirectionsParams, DirectionsResponse, IsochroneParams, IsochroneResponse, MatrixParams, MatrixResponse, ZoneRecord } from '@wherabouts/sdk';
 
+/**
+ * Minimal structural view of the Web Storage API (sessionStorage/localStorage).
+ * Declared locally so the package type-checks with no DOM lib.
+ */
+interface StorageLike {
+    getItem(key: string): string | null;
+    removeItem(key: string): void;
+    setItem(key: string, value: string): void;
+}
+
+/**
+ * Headless WAI-ARIA combobox helper for autocomplete dropdowns. Provides the
+ * keyboard state machine (↑/↓/Home/End/Enter/Esc, wrapping) and ARIA prop
+ * getters so an input + listbox is accessible by default. Bring your own
+ * markup and data; this hook owns only the open/active-option state.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+ */
+interface ComboboxState {
+    /** Index of the visually-active option, or -1 when none is active. */
+    activeIndex: number;
+    isOpen: boolean;
+}
+type ComboboxAction = {
+    type: "next";
+    count: number;
+} | {
+    type: "prev";
+    count: number;
+} | {
+    type: "first";
+    count: number;
+} | {
+    type: "last";
+    count: number;
+} | {
+    type: "set";
+    index: number;
+} | {
+    type: "open";
+} | {
+    type: "close";
+} | {
+    type: "select";
+} | {
+    type: "reset";
+};
+declare const INITIAL_COMBOBOX_STATE: ComboboxState;
+/** Pure transition function for the combobox keyboard state machine. */
+declare function comboboxReducer(state: ComboboxState, action: ComboboxAction): ComboboxState;
+/** Map a keyboard key to a combobox action, or null when it is irrelevant. */
+declare function keyToAction(key: string, count: number): ComboboxAction | null;
+interface ComboboxInputProps {
+    "aria-activedescendant": string | undefined;
+    "aria-autocomplete": "list";
+    "aria-controls": string;
+    "aria-expanded": boolean;
+    role: "combobox";
+}
+interface ComboboxListboxProps {
+    id: string;
+    role: "listbox";
+}
+interface ComboboxItemProps {
+    "aria-selected": boolean;
+    id: string;
+    role: "option";
+}
+/** Build the ARIA attributes for the combobox input — pure. */
+declare function buildInputProps(id: string, state: ComboboxState): ComboboxInputProps;
+/** Build the ARIA attributes for the listbox container — pure. */
+declare function buildListboxProps(id: string): ComboboxListboxProps;
+/** Build the ARIA attributes for an option at `index` — pure. */
+declare function buildItemProps(id: string, index: number, state: ComboboxState): ComboboxItemProps;
+interface UseComboboxOptions {
+    /** Number of options currently rendered (drives wrapping/bounds). */
+    count: number;
+    /** Stable id root; option/listbox ids derive from it. */
+    id: string;
+    /** Called when an option is chosen via Enter or pointer. */
+    onSelect?: (index: number) => void;
+}
+interface UseComboboxResult {
+    activeIndex: number;
+    close: () => void;
+    getInputProps: () => ComboboxInputProps & {
+        onBlur: () => void;
+        onFocus: () => void;
+        onKeyDown: (event: KeyboardEvent) => void;
+    };
+    getItemProps: (index: number) => ComboboxItemProps & {
+        onMouseDown: (event: MouseEvent) => void;
+        onMouseEnter: () => void;
+    };
+    getListboxProps: () => ComboboxListboxProps;
+    isOpen: boolean;
+    open: () => void;
+    reset: () => void;
+    setActiveIndex: (index: number) => void;
+}
+declare function useCombobox(options: UseComboboxOptions): UseComboboxResult;
+
+type AutocompleteStatus = "idle" | "loading" | "success" | "empty" | "error";
+/** Opt-in client-side cache for repeated/back-and-forth queries. */
+interface AutocompleteCacheConfig {
+    /** A `sessionStorage`-like store. Entries are namespaced under `wh:ac:`. */
+    storage: StorageLike;
+    /** Entry lifetime in ms (default 60_000). */
+    ttlMs?: number;
+}
 interface UseAutocompleteOptions {
+    cache?: AutocompleteCacheConfig;
     country?: string;
     debounceMs?: number;
+    /** Keep the previous results visible while a new search runs / on error. */
+    keepPreviousData?: boolean;
+    /** Latitude for proximity boosting (pair with `lng`). */
+    lat?: number;
     limit?: number;
+    /** Longitude for proximity boosting (pair with `lat`). */
+    lng?: number;
+    /** Minimum trimmed query length before a request fires (default 2). */
+    minLength?: number;
+    /** Groups keystrokes into one billable session; see `newSessionToken()`. */
+    sessionToken?: string;
     state?: string;
 }
 interface UseAutocompleteResult {
     error: Error | null;
     loading: boolean;
     query: string;
+    /** True when the last request was rejected with HTTP 429. */
+    rateLimited: boolean;
+    /** Clear the query, results, and any in-flight request. */
+    reset: () => void;
     results: AddressSuggestion[];
     setQuery: (q: string) => void;
+    status: AutocompleteStatus;
 }
+/**
+ * Derive a single coarse status from the hook's raw flags. Exported for
+ * unit-testing and for consumers who prefer a state machine to booleans.
+ */
+declare function deriveStatus(s: {
+    error: Error | null;
+    loading: boolean;
+    minLength: number;
+    query: string;
+    results: AddressSuggestion[];
+}): AutocompleteStatus;
 declare function useAutocomplete(client: WheraboutsClient, options?: UseAutocompleteOptions): UseAutocompleteResult;
 
 interface LatLng {
@@ -27,6 +165,18 @@ interface UseReverseGeocodeResult {
 }
 declare function useReverseGeocode(client: WheraboutsClient, coords: LatLng | null): UseReverseGeocodeResult;
 
+interface RoutingResourceResult<T> {
+    data: T | null;
+    error: Error | null;
+    loading: boolean;
+}
+/** Fetch turn-by-turn directions; pass `null` to stay idle. */
+declare function useDirections(client: WheraboutsClient, params: DirectionsParams | null): RoutingResourceResult<DirectionsResponse>;
+/** Fetch a duration/distance matrix; pass `null` to stay idle. */
+declare function useMatrix(client: WheraboutsClient, params: MatrixParams | null): RoutingResourceResult<MatrixResponse>;
+/** Fetch an isochrone polygon; pass `null` to stay idle. */
+declare function useIsochrone(client: WheraboutsClient, params: IsochroneParams | null): RoutingResourceResult<IsochroneResponse>;
+
 interface UseZoneContainsResult {
     error: Error | null;
     loading: boolean;
@@ -34,4 +184,4 @@ interface UseZoneContainsResult {
 }
 declare function useZoneContains(client: WheraboutsClient, coords: LatLng | null): UseZoneContainsResult;
 
-export { type LatLng, type UseAutocompleteOptions, type UseAutocompleteResult, type UseReverseGeocodeResult, type UseZoneContainsResult, useAutocomplete, useReverseGeocode, useZoneContains };
+export { type AutocompleteCacheConfig, type AutocompleteStatus, type ComboboxAction, type ComboboxInputProps, type ComboboxItemProps, type ComboboxListboxProps, type ComboboxState, INITIAL_COMBOBOX_STATE, type LatLng, type RoutingResourceResult, type StorageLike, type UseAutocompleteOptions, type UseAutocompleteResult, type UseComboboxOptions, type UseComboboxResult, type UseReverseGeocodeResult, type UseZoneContainsResult, buildInputProps, buildItemProps, buildListboxProps, comboboxReducer, deriveStatus, keyToAction, useAutocomplete, useCombobox, useDirections, useIsochrone, useMatrix, useReverseGeocode, useZoneContains };