@wherabouts/react-ui 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,113 +1,165 @@
-import { AddressSuggestion, WheraboutsClient } from '@wherabouts/sdk';
-import { ClassValue } from 'clsx';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { AddressSuggestion, WheraboutsClient } from '@wherabouts/sdk';
 import { ReactNode } from 'react';
+import { ClassValue } from 'clsx';
 
 interface AddressWithParsed {
-    id: number;
+    country: string;
     formattedAddress: string;
+    id: number;
     latitude: number;
     longitude: number;
+    postcode: string;
+    state: string;
     streetAddress: string;
     suburb: string;
-    state: string;
-    postcode: string;
-    country: string;
 }
 interface AddressI18nStrings {
-    noResults: string;
     enterManually: string;
     errorRetry: string;
     geolocationError: string;
+    noResults: string;
 }
 type AddressValidateFn = (address: AddressWithParsed) => Promise<{
     message: string;
 } | null>;
 type AddressSuggestionInput = AddressSuggestion;
 
-declare function toAddressWithParsed(suggestion: AddressSuggestion): AddressWithParsed;
-
-declare function cn(...inputs: ClassValue[]): string;
-
 interface AddressAutocompleteProps {
+    /** Class applied to the root container. */
     className?: string;
+    /** Required. SDK client created with `createWheraboutsClient`. */
     client: WheraboutsClient;
+    /** Debounce in ms before querying the API. Default 300. */
     debounceMs?: number;
+    /** Disable the input. */
     disabled?: boolean;
+    /** Use the browser's geolocation to bias results by proximity. Default false. */
     enableGeolocation?: boolean;
+    /** External error message to display. */
     error?: string;
+    /** Override built-in UI strings (no results, retry, etc.). */
     i18nStrings?: Partial<AddressI18nStrings>;
+    /** id forwarded to the input element. */
     id?: string;
+    /** Maximum number of suggestions to show. Default 5. */
     maxSuggestions?: number;
+    /** Minimum characters typed before searching. Default 2. */
     minCharsToSearch?: number;
+    /** Called as the input text changes. */
     onQueryChange?: (query: string) => void;
+    /** Called when a suggestion is selected. */
     onSelect?: (address: AddressWithParsed) => void;
+    /** Input placeholder text. */
     placeholder?: string;
+    /** Render a custom empty state. */
     renderEmpty?: () => ReactNode;
+    /** Render a custom error state. */
     renderError?: (error: Error | null) => ReactNode;
+    /** Render a custom loading state. */
     renderLoading?: () => ReactNode;
+    /** Render a custom suggestion row. */
     renderSuggestion?: (address: AddressWithParsed, isActive: boolean) => ReactNode;
+    /** Mark the input as required. */
     required?: boolean;
+    /** Group a run of keystrokes into one billable search (see SDK `newSessionToken()`). */
     sessionToken?: string;
+    /** Explicit latitude for proximity bias (instead of geolocation). */
     userLat?: number;
+    /** Explicit longitude for proximity bias (instead of geolocation). */
     userLng?: number;
 }
 declare function AddressAutocomplete({ client, onQueryChange, onSelect, error: externalError, required, disabled, debounceMs, minCharsToSearch, maxSuggestions, enableGeolocation, userLat, userLng, sessionToken, className, placeholder, renderSuggestion, renderEmpty, renderError, renderLoading, i18nStrings: customI18n, id: customId, }: AddressAutocompleteProps): react_jsx_runtime.JSX.Element;
 
+interface AddressFieldGroupValue {
+    /** Postcode field value. */
+    postcode: string;
+    /** State field value. */
+    state: string;
+    /** Street address field value. */
+    street: string;
+    /** Suburb field value. */
+    suburb: string;
+}
+interface AddressFieldGroupProps {
+    /** Class applied to the root container. */
+    className?: string;
+    /** Required. SDK client created with `createWheraboutsClient`. */
+    client: WheraboutsClient;
+    /** Disable all fields. */
+    disabled?: boolean;
+    /** Required. Change handler, called with the updated value on any field edit. */
+    onChange: (value: AddressFieldGroupValue) => void;
+    /** Override the postcode field label. */
+    postcodeLabel?: string;
+    /** Override the state field label. */
+    stateLabel?: string;
+    /** Override the street address field label. */
+    streetLabel?: string;
+    /** Override the suburb field label. */
+    suburbLabel?: string;
+    /** Required. Controlled value for the field group. */
+    value: AddressFieldGroupValue;
+}
+declare function AddressFieldGroup({ client, value, onChange, className, disabled, streetLabel, suburbLabel, stateLabel, postcodeLabel, }: AddressFieldGroupProps): ReactNode;
+
 interface AddressFormFieldProps extends AddressAutocompleteProps {
+    /** Class applied to the error text element. */
+    errorClassName?: string;
+    /** Required. Field label rendered above the input. */
     label: string;
+    /** Class applied to the label element. */
     labelClassName?: string;
-    errorClassName?: string;
 }
 declare function AddressFormField({ label, labelClassName, errorClassName, error, required, disabled, id: customId, className, ...autocompleteProps }: AddressFormFieldProps): ReactNode;
 
-interface ReverseGeocodeInputProps {
-    client: WheraboutsClient;
-    latitude: number | null;
-    longitude: number | null;
-    onResult?: (result: {
-        address: string | null;
-        distance: number | null;
-    }) => void;
+interface ForwardGeocodeInputProps {
+    /** Class applied to the input element. */
     className?: string;
+    /** Required. SDK client created with `createWheraboutsClient`. */
+    client: WheraboutsClient;
+    /** Disable the input. */
     disabled?: boolean;
-    placeholder?: string;
+    /** id forwarded to the input element. */
     id?: string;
-}
-declare function ReverseGeocodeInput({ client, latitude, longitude, onResult, className, disabled, placeholder, id, }: ReverseGeocodeInputProps): ReactNode;
-
-interface ForwardGeocodeInputProps {
-    client: WheraboutsClient;
-    query: string | null;
+    /** Geocode result callback, called whenever the resolved result changes. */
     onResult?: (result: {
         latitude: number | null;
         longitude: number | null;
         formattedAddress: string | null;
     }) => void;
-    className?: string;
-    disabled?: boolean;
+    /** Input placeholder text. */
     placeholder?: string;
-    id?: string;
+    /** Address text to geocode. */
+    query: string | null;
 }
 declare function ForwardGeocodeInput({ client, query, onResult, className, disabled, placeholder, id, }: ForwardGeocodeInputProps): ReactNode;
 
-interface AddressFieldGroupValue {
-    street: string;
-    suburb: string;
-    state: string;
-    postcode: string;
-}
-interface AddressFieldGroupProps {
-    client: WheraboutsClient;
-    value: AddressFieldGroupValue;
-    onChange: (value: AddressFieldGroupValue) => void;
+interface ReverseGeocodeInputProps {
+    /** Class applied to the input element. */
     className?: string;
+    /** Required. SDK client created with `createWheraboutsClient`. */
+    client: WheraboutsClient;
+    /** Disable the input. */
     disabled?: boolean;
-    streetLabel?: string;
-    suburbLabel?: string;
-    stateLabel?: string;
-    postcodeLabel?: string;
+    /** id forwarded to the input element. */
+    id?: string;
+    /** Latitude to reverse-geocode. */
+    latitude: number | null;
+    /** Longitude to reverse-geocode. */
+    longitude: number | null;
+    /** Result callback, called whenever the resolved address changes. */
+    onResult?: (result: {
+        address: string | null;
+        distance: number | null;
+    }) => void;
+    /** Input placeholder text. */
+    placeholder?: string;
 }
-declare function AddressFieldGroup({ client, value, onChange, className, disabled, streetLabel, suburbLabel, stateLabel, postcodeLabel, }: AddressFieldGroupProps): ReactNode;
+declare function ReverseGeocodeInput({ client, latitude, longitude, onResult, className, disabled, placeholder, id, }: ReverseGeocodeInputProps): ReactNode;
+
+declare function cn(...inputs: ClassValue[]): string;
+
+declare function toAddressWithParsed(suggestion: AddressSuggestion): AddressWithParsed;
 
 export { AddressAutocomplete, type AddressAutocompleteProps, AddressFieldGroup, type AddressFieldGroupProps, type AddressFieldGroupValue, AddressFormField, type AddressFormFieldProps, type AddressI18nStrings, type AddressSuggestionInput, type AddressValidateFn, type AddressWithParsed, ForwardGeocodeInput, type ForwardGeocodeInputProps, ReverseGeocodeInput, type ReverseGeocodeInputProps, cn, toAddressWithParsed };

package/dist/index.d.ts

@@ -1,113 +1,165 @@
-import { AddressSuggestion, WheraboutsClient } from '@wherabouts/sdk';
-import { ClassValue } from 'clsx';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { AddressSuggestion, WheraboutsClient } from '@wherabouts/sdk';
 import { ReactNode } from 'react';
+import { ClassValue } from 'clsx';
 
 interface AddressWithParsed {
-    id: number;
+    country: string;
     formattedAddress: string;
+    id: number;
     latitude: number;
     longitude: number;
+    postcode: string;
+    state: string;
     streetAddress: string;
     suburb: string;
-    state: string;
-    postcode: string;
-    country: string;
 }
 interface AddressI18nStrings {
-    noResults: string;
     enterManually: string;
     errorRetry: string;
     geolocationError: string;
+    noResults: string;
 }
 type AddressValidateFn = (address: AddressWithParsed) => Promise<{
     message: string;
 } | null>;
 type AddressSuggestionInput = AddressSuggestion;
 
-declare function toAddressWithParsed(suggestion: AddressSuggestion): AddressWithParsed;
-
-declare function cn(...inputs: ClassValue[]): string;
-
 interface AddressAutocompleteProps {
+    /** Class applied to the root container. */
     className?: string;
+    /** Required. SDK client created with `createWheraboutsClient`. */
     client: WheraboutsClient;
+    /** Debounce in ms before querying the API. Default 300. */
     debounceMs?: number;
+    /** Disable the input. */
     disabled?: boolean;
+    /** Use the browser's geolocation to bias results by proximity. Default false. */
     enableGeolocation?: boolean;
+    /** External error message to display. */
     error?: string;
+    /** Override built-in UI strings (no results, retry, etc.). */
     i18nStrings?: Partial<AddressI18nStrings>;
+    /** id forwarded to the input element. */
     id?: string;
+    /** Maximum number of suggestions to show. Default 5. */
     maxSuggestions?: number;
+    /** Minimum characters typed before searching. Default 2. */
     minCharsToSearch?: number;
+    /** Called as the input text changes. */
     onQueryChange?: (query: string) => void;
+    /** Called when a suggestion is selected. */
     onSelect?: (address: AddressWithParsed) => void;
+    /** Input placeholder text. */
     placeholder?: string;
+    /** Render a custom empty state. */
     renderEmpty?: () => ReactNode;
+    /** Render a custom error state. */
     renderError?: (error: Error | null) => ReactNode;
+    /** Render a custom loading state. */
     renderLoading?: () => ReactNode;
+    /** Render a custom suggestion row. */
     renderSuggestion?: (address: AddressWithParsed, isActive: boolean) => ReactNode;
+    /** Mark the input as required. */
     required?: boolean;
+    /** Group a run of keystrokes into one billable search (see SDK `newSessionToken()`). */
     sessionToken?: string;
+    /** Explicit latitude for proximity bias (instead of geolocation). */
     userLat?: number;
+    /** Explicit longitude for proximity bias (instead of geolocation). */
     userLng?: number;
 }
 declare function AddressAutocomplete({ client, onQueryChange, onSelect, error: externalError, required, disabled, debounceMs, minCharsToSearch, maxSuggestions, enableGeolocation, userLat, userLng, sessionToken, className, placeholder, renderSuggestion, renderEmpty, renderError, renderLoading, i18nStrings: customI18n, id: customId, }: AddressAutocompleteProps): react_jsx_runtime.JSX.Element;
 
+interface AddressFieldGroupValue {
+    /** Postcode field value. */
+    postcode: string;
+    /** State field value. */
+    state: string;
+    /** Street address field value. */
+    street: string;
+    /** Suburb field value. */
+    suburb: string;
+}
+interface AddressFieldGroupProps {
+    /** Class applied to the root container. */
+    className?: string;
+    /** Required. SDK client created with `createWheraboutsClient`. */
+    client: WheraboutsClient;
+    /** Disable all fields. */
+    disabled?: boolean;
+    /** Required. Change handler, called with the updated value on any field edit. */
+    onChange: (value: AddressFieldGroupValue) => void;
+    /** Override the postcode field label. */
+    postcodeLabel?: string;
+    /** Override the state field label. */
+    stateLabel?: string;
+    /** Override the street address field label. */
+    streetLabel?: string;
+    /** Override the suburb field label. */
+    suburbLabel?: string;
+    /** Required. Controlled value for the field group. */
+    value: AddressFieldGroupValue;
+}
+declare function AddressFieldGroup({ client, value, onChange, className, disabled, streetLabel, suburbLabel, stateLabel, postcodeLabel, }: AddressFieldGroupProps): ReactNode;
+
 interface AddressFormFieldProps extends AddressAutocompleteProps {
+    /** Class applied to the error text element. */
+    errorClassName?: string;
+    /** Required. Field label rendered above the input. */
     label: string;
+    /** Class applied to the label element. */
     labelClassName?: string;
-    errorClassName?: string;
 }
 declare function AddressFormField({ label, labelClassName, errorClassName, error, required, disabled, id: customId, className, ...autocompleteProps }: AddressFormFieldProps): ReactNode;
 
-interface ReverseGeocodeInputProps {
-    client: WheraboutsClient;
-    latitude: number | null;
-    longitude: number | null;
-    onResult?: (result: {
-        address: string | null;
-        distance: number | null;
-    }) => void;
+interface ForwardGeocodeInputProps {
+    /** Class applied to the input element. */
     className?: string;
+    /** Required. SDK client created with `createWheraboutsClient`. */
+    client: WheraboutsClient;
+    /** Disable the input. */
     disabled?: boolean;
-    placeholder?: string;
+    /** id forwarded to the input element. */
     id?: string;
-}
-declare function ReverseGeocodeInput({ client, latitude, longitude, onResult, className, disabled, placeholder, id, }: ReverseGeocodeInputProps): ReactNode;
-
-interface ForwardGeocodeInputProps {
-    client: WheraboutsClient;
-    query: string | null;
+    /** Geocode result callback, called whenever the resolved result changes. */
     onResult?: (result: {
         latitude: number | null;
         longitude: number | null;
         formattedAddress: string | null;
     }) => void;
-    className?: string;
-    disabled?: boolean;
+    /** Input placeholder text. */
     placeholder?: string;
-    id?: string;
+    /** Address text to geocode. */
+    query: string | null;
 }
 declare function ForwardGeocodeInput({ client, query, onResult, className, disabled, placeholder, id, }: ForwardGeocodeInputProps): ReactNode;
 
-interface AddressFieldGroupValue {
-    street: string;
-    suburb: string;
-    state: string;
-    postcode: string;
-}
-interface AddressFieldGroupProps {
-    client: WheraboutsClient;
-    value: AddressFieldGroupValue;
-    onChange: (value: AddressFieldGroupValue) => void;
+interface ReverseGeocodeInputProps {
+    /** Class applied to the input element. */
     className?: string;
+    /** Required. SDK client created with `createWheraboutsClient`. */
+    client: WheraboutsClient;
+    /** Disable the input. */
     disabled?: boolean;
-    streetLabel?: string;
-    suburbLabel?: string;
-    stateLabel?: string;
-    postcodeLabel?: string;
+    /** id forwarded to the input element. */
+    id?: string;
+    /** Latitude to reverse-geocode. */
+    latitude: number | null;
+    /** Longitude to reverse-geocode. */
+    longitude: number | null;
+    /** Result callback, called whenever the resolved address changes. */
+    onResult?: (result: {
+        address: string | null;
+        distance: number | null;
+    }) => void;
+    /** Input placeholder text. */
+    placeholder?: string;
 }
-declare function AddressFieldGroup({ client, value, onChange, className, disabled, streetLabel, suburbLabel, stateLabel, postcodeLabel, }: AddressFieldGroupProps): ReactNode;
+declare function ReverseGeocodeInput({ client, latitude, longitude, onResult, className, disabled, placeholder, id, }: ReverseGeocodeInputProps): ReactNode;
+
+declare function cn(...inputs: ClassValue[]): string;
+
+declare function toAddressWithParsed(suggestion: AddressSuggestion): AddressWithParsed;
 
 export { AddressAutocomplete, type AddressAutocompleteProps, AddressFieldGroup, type AddressFieldGroupProps, type AddressFieldGroupValue, AddressFormField, type AddressFormFieldProps, type AddressI18nStrings, type AddressSuggestionInput, type AddressValidateFn, type AddressWithParsed, ForwardGeocodeInput, type ForwardGeocodeInputProps, ReverseGeocodeInput, type ReverseGeocodeInputProps, cn, toAddressWithParsed };