@wherabouts/react-ui 0.1.0 → 0.1.1

package/README.md

@@ -73,8 +73,8 @@ keyboard navigation, and customizable rendering.
 <AddressAutocomplete
   client={client}
   onSelect={(address) => setAddress(address)}
-  minCharsToSearch={3}
-  debounceMs={200}
+  minCharsToSearch={4}
+  debounceMs={250}
   maxSuggestions={8}
   enableGeolocation
 />
@@ -86,9 +86,9 @@ keyboard navigation, and customizable rendering.
 | `onSelect` | `(address: AddressWithParsed) => void` | — | Called when a suggestion is chosen. |
 | `onQueryChange` | `(query: string) => void` | — | Called as the input text changes. |
 | `placeholder` | `string` | — | Input placeholder. |
-| `debounceMs` | `number` | `200` | Debounce before querying the API. |
-| `minCharsToSearch` | `number` | `3` | Minimum characters before searching. |
-| `maxSuggestions` | `number` | `10` | Max suggestions to show. |
+| `debounceMs` | `number` | `300` | Debounce before querying the API. |
+| `minCharsToSearch` | `number` | `2` | Minimum characters before searching. |
+| `maxSuggestions` | `number` | `5` | Max suggestions to show. |
 | `enableGeolocation` | `boolean` | `false` | Use the browser's location to bias results (proximity). |
 | `userLat` / `userLng` | `number` | — | Explicit proximity bias instead of geolocation. |
 | `sessionToken` | `string` | — | Group a run of keystrokes into one billable search (see `newSessionToken()` in the SDK). |
@@ -159,6 +159,24 @@ full address.
 - Exported types: `AddressWithParsed`, `AddressI18nStrings`, `AddressValidateFn`,
   `AddressSuggestionInput`, and each component's `*Props`.
 
+## Per-component documentation
+
+Full per-component guides — multiple examples, accessibility notes, and recipes —
+live in [`docs/`](./docs/README.md).
+
+## Interactive docs (Storybook)
+
+This package ships a Storybook with live, interactive examples of every component.
+
+```bash
+pnpm --filter @wherabouts/react-ui storybook
+```
+
+Live stories call the real API. Set `VITE_DEMO_API_KEY` (a publishable,
+origin-scoped key) and optionally `VITE_DEMO_API_BASE_URL` (default
+`https://api.wherabouts.com`) to enable results; without a key, components still
+render with a configuration banner.
+
 ## Styling
 
 The package ships a prebuilt `styles.css` (import it once, as shown above). Components use

package/dist/index.cjs

@@ -5,22 +5,42 @@ var react = require('react');
 var reactDom = require('react-dom');
 var jsxRuntime = require('react/jsx-runtime');
 
-// src/utils/parse-address.ts
-var COUNTRY_NAMES = {
-  AU: "Australia"
-};
-function toAddressWithParsed(suggestion) {
-  return {
-    id: suggestion.id,
-    formattedAddress: suggestion.formattedAddress,
-    latitude: suggestion.latitude,
-    longitude: suggestion.longitude,
-    streetAddress: suggestion.streetAddress,
-    suburb: suggestion.locality,
-    state: suggestion.state,
-    postcode: suggestion.postcode,
-    country: COUNTRY_NAMES[suggestion.country] ?? suggestion.country
-  };
+// src/components/address-autocomplete.tsx
+function useAddressGeolocation(enabled) {
+  const [lat, setLat] = react.useState(void 0);
+  const [lng, setLng] = react.useState(void 0);
+  const [loading, setLoading] = react.useState(false);
+  const [error, setError] = react.useState(null);
+  react.useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+    if (typeof navigator === "undefined" || !("geolocation" in navigator)) {
+      return;
+    }
+    setLoading(true);
+    const controller = new AbortController();
+    navigator.geolocation.getCurrentPosition(
+      (position) => {
+        if (!controller.signal.aborted) {
+          setLat(position.coords.latitude);
+          setLng(position.coords.longitude);
+          setError(null);
+          setLoading(false);
+        }
+      },
+      (err) => {
+        if (!controller.signal.aborted) {
+          setError(err);
+          setLoading(false);
+        }
+      }
+    );
+    return () => {
+      controller.abort();
+    };
+  }, [enabled]);
+  return { lat, lng, loading, error };
 }
 
 // ../../node_modules/.pnpm/clsx@2.1.1/node_modules/clsx/dist/clsx.mjs
@@ -2502,41 +2522,23 @@ var twMerge = /* @__PURE__ */ createTailwindMerge(getDefaultConfig);
 function cn(...inputs) {
   return twMerge(clsx(inputs));
 }
-function useAddressGeolocation(enabled) {
-  const [lat, setLat] = react.useState(void 0);
-  const [lng, setLng] = react.useState(void 0);
-  const [loading, setLoading] = react.useState(false);
-  const [error, setError] = react.useState(null);
-  react.useEffect(() => {
-    if (!enabled) {
-      return;
-    }
-    if (typeof navigator === "undefined" || !("geolocation" in navigator)) {
-      return;
-    }
-    setLoading(true);
-    const controller = new AbortController();
-    navigator.geolocation.getCurrentPosition(
-      (position) => {
-        if (!controller.signal.aborted) {
-          setLat(position.coords.latitude);
-          setLng(position.coords.longitude);
-          setError(null);
-          setLoading(false);
-        }
-      },
-      (err) => {
-        if (!controller.signal.aborted) {
-          setError(err);
-          setLoading(false);
-        }
-      }
-    );
-    return () => {
-      controller.abort();
-    };
-  }, [enabled]);
-  return { lat, lng, loading, error };
+
+// src/utils/parse-address.ts
+var COUNTRY_NAMES = {
+  AU: "Australia"
+};
+function toAddressWithParsed(suggestion) {
+  return {
+    id: suggestion.id,
+    formattedAddress: suggestion.formattedAddress,
+    latitude: suggestion.latitude,
+    longitude: suggestion.longitude,
+    streetAddress: suggestion.streetAddress,
+    suburb: suggestion.locality,
+    state: suggestion.state,
+    postcode: suggestion.postcode,
+    country: COUNTRY_NAMES[suggestion.country] ?? suggestion.country
+  };
 }
 var DEFAULT_I18N = {
   noResults: "No addresses found",
@@ -2780,186 +2782,6 @@ function AddressAutocomplete({
     }
   );
 }
-function AddressFormField({
-  label,
-  labelClassName,
-  errorClassName,
-  error,
-  required,
-  disabled,
-  id: customId,
-  className,
-  ...autocompleteProps
-}) {
-  const id = customId ?? "wherabouts-field";
-  return /* @__PURE__ */ jsxRuntime.jsxs(
-    "div",
-    {
-      "data-slot": "address-form-field",
-      className: "flex flex-col gap-2",
-      children: [
-        /* @__PURE__ */ jsxRuntime.jsxs(
-          "label",
-          {
-            htmlFor: id,
-            className: cn(
-              "block text-sm font-medium text-gray-900",
-              labelClassName
-            ),
-            children: [
-              label,
-              required && /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", className: "ml-1 text-red-600", children: "*" })
-            ]
-          }
-        ),
-        /* @__PURE__ */ jsxRuntime.jsx(
-          AddressAutocomplete,
-          {
-            ...autocompleteProps,
-            id,
-            required,
-            disabled,
-            error,
-            className
-          }
-        ),
-        error && /* @__PURE__ */ jsxRuntime.jsx(
-          "p",
-          {
-            role: "alert",
-            "aria-live": "polite",
-            className: cn(
-              "text-sm text-red-600",
-              errorClassName
-            ),
-            children: error
-          }
-        )
-      ]
-    }
-  );
-}
-function ReverseGeocodeInput({
-  client,
-  latitude,
-  longitude,
-  onResult,
-  className,
-  disabled,
-  placeholder = "Address will appear here",
-  id
-}) {
-  const { address, distance } = react$1.useReverseGeocode(
-    client,
-    latitude != null && longitude != null ? { lat: latitude, lng: longitude } : null
-  );
-  react.useEffect(() => {
-    onResult?.({
-      address: address?.formattedAddress ?? null,
-      distance: distance ?? null
-    });
-  }, [address, distance, onResult]);
-  const displayText = address?.formattedAddress ?? "";
-  return /* @__PURE__ */ jsxRuntime.jsx(
-    "input",
-    {
-      id,
-      "data-slot": "geocode-input",
-      type: "text",
-      readOnly: true,
-      disabled,
-      value: displayText,
-      placeholder,
-      className: cn(
-        "block h-8 w-full cursor-default rounded-none border border-input bg-muted/40 px-2.5 py-1 text-foreground text-xs",
-        className
-      )
-    }
-  );
-}
-var toGeocodeAddress = (address) => address ? {
-  id: address.id,
-  formattedAddress: address.formattedAddress,
-  latitude: address.latitude,
-  longitude: address.longitude
-} : null;
-function useForwardGeocode(client, query) {
-  const [data, setData] = react.useState(null);
-  const [loading, setLoading] = react.useState(false);
-  const [error, setError] = react.useState(null);
-  react.useEffect(() => {
-    if (!query) {
-      setData(null);
-      setError(null);
-      return;
-    }
-    const controller = new AbortController();
-    async function fetch() {
-      setLoading(true);
-      setError(null);
-      try {
-        const response = await client.geocode.forward(
-          { q: query },
-          { signal: controller.signal }
-        );
-        if (controller.signal.aborted) {
-          return;
-        }
-        setData(toGeocodeAddress(response.address));
-      } catch (err) {
-        if (controller.signal.aborted) {
-          return;
-        }
-        setError(err instanceof Error ? err : new Error(String(err)));
-        setData(null);
-      } finally {
-        if (!controller.signal.aborted) {
-          setLoading(false);
-        }
-      }
-    }
-    fetch();
-    return () => {
-      controller.abort();
-    };
-  }, [client, query]);
-  return { data, loading, error };
-}
-function ForwardGeocodeInput({
-  client,
-  query,
-  onResult,
-  className,
-  disabled,
-  placeholder = "Coordinates will appear here",
-  id
-}) {
-  const { data } = useForwardGeocode(client, query);
-  react.useEffect(() => {
-    onResult?.({
-      latitude: data?.latitude ?? null,
-      longitude: data?.longitude ?? null,
-      formattedAddress: data?.formattedAddress ?? null
-    });
-  }, [data, onResult]);
-  const displayText = data ? `${data.latitude.toFixed(4)}, ${data.longitude.toFixed(4)}` : "";
-  return /* @__PURE__ */ jsxRuntime.jsx(
-    "input",
-    {
-      id,
-      "data-slot": "geocode-input",
-      type: "text",
-      readOnly: true,
-      disabled,
-      value: displayText,
-      placeholder,
-      className: cn(
-        "block h-8 w-full cursor-default rounded-none border border-input bg-muted/40 px-2.5 py-1 text-foreground text-xs",
-        className
-      )
-    }
-  );
-}
 function AddressFieldGroup({
   client,
   value,
@@ -2988,8 +2810,8 @@ function AddressFieldGroup({
   return /* @__PURE__ */ jsxRuntime.jsxs(
     "div",
     {
-      "data-slot": "address-field-group",
       className: cn("flex flex-col gap-4", className),
+      "data-slot": "address-field-group",
       children: [
         /* @__PURE__ */ jsxRuntime.jsx(
           AddressAutocomplete,
@@ -3003,28 +2825,28 @@ function AddressFieldGroup({
         /* @__PURE__ */ jsxRuntime.jsxs(
           "div",
           {
-            "data-slot": "address-field-group-inputs",
             className: "grid grid-cols-2 gap-4",
+            "data-slot": "address-field-group-inputs",
             children: [
               /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "col-span-2", children: [
                 /* @__PURE__ */ jsxRuntime.jsx(
                   "label",
                   {
-                    htmlFor: "field-street",
                     className: "mb-1 block font-medium text-foreground text-sm",
+                    htmlFor: "field-street",
                     children: streetLabel
                   }
                 ),
                 /* @__PURE__ */ jsxRuntime.jsx(
                   "input",
                   {
-                    id: "field-street",
-                    type: "text",
+                    className: "block h-8 w-full rounded-none border border-input bg-transparent px-2.5 py-1 text-foreground text-xs outline-none transition-colors placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 dark:bg-input/30",
                     disabled,
-                    value: value.street,
+                    id: "field-street",
                     onChange: (e) => handleFieldChange("street", e.target.value),
-                    className: "block h-8 w-full rounded-none border border-input bg-transparent px-2.5 py-1 text-foreground text-xs outline-none transition-colors placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 dark:bg-input/30",
-                    placeholder: "Street address"
+                    placeholder: "Street address",
+                    type: "text",
+                    value: value.street
                   }
                 )
               ] }),
@@ -3032,21 +2854,21 @@ function AddressFieldGroup({
                 /* @__PURE__ */ jsxRuntime.jsx(
                   "label",
                   {
-                    htmlFor: "field-suburb",
                     className: "mb-1 block font-medium text-foreground text-sm",
+                    htmlFor: "field-suburb",
                     children: suburbLabel
                   }
                 ),
                 /* @__PURE__ */ jsxRuntime.jsx(
                   "input",
                   {
-                    id: "field-suburb",
-                    type: "text",
+                    className: "block h-8 w-full rounded-none border border-input bg-transparent px-2.5 py-1 text-foreground text-xs outline-none transition-colors placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 dark:bg-input/30",
                     disabled,
-                    value: value.suburb,
+                    id: "field-suburb",
                     onChange: (e) => handleFieldChange("suburb", e.target.value),
-                    className: "block h-8 w-full rounded-none border border-input bg-transparent px-2.5 py-1 text-foreground text-xs outline-none transition-colors placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 dark:bg-input/30",
-                    placeholder: "Suburb"
+                    placeholder: "Suburb",
+                    type: "text",
+                    value: value.suburb
                   }
                 )
               ] }),
@@ -3054,21 +2876,21 @@ function AddressFieldGroup({
                 /* @__PURE__ */ jsxRuntime.jsx(
                   "label",
                   {
-                    htmlFor: "field-state",
                     className: "mb-1 block font-medium text-foreground text-sm",
+                    htmlFor: "field-state",
                     children: stateLabel
                   }
                 ),
                 /* @__PURE__ */ jsxRuntime.jsx(
                   "input",
                   {
-                    id: "field-state",
-                    type: "text",
+                    className: "block h-8 w-full rounded-none border border-input bg-transparent px-2.5 py-1 text-foreground text-xs outline-none transition-colors placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 dark:bg-input/30",
                     disabled,
-                    value: value.state,
+                    id: "field-state",
                     onChange: (e) => handleFieldChange("state", e.target.value),
-                    className: "block h-8 w-full rounded-none border border-input bg-transparent px-2.5 py-1 text-foreground text-xs outline-none transition-colors placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 dark:bg-input/30",
-                    placeholder: "State"
+                    placeholder: "State",
+                    type: "text",
+                    value: value.state
                   }
                 )
               ] }),
@@ -3076,21 +2898,21 @@ function AddressFieldGroup({
                 /* @__PURE__ */ jsxRuntime.jsx(
                   "label",
                   {
-                    htmlFor: "field-postcode",
                     className: "mb-1 block font-medium text-foreground text-sm",
+                    htmlFor: "field-postcode",
                     children: postcodeLabel
                   }
                 ),
                 /* @__PURE__ */ jsxRuntime.jsx(
                   "input",
                   {
-                    id: "field-postcode",
-                    type: "text",
+                    className: "block h-8 w-full rounded-none border border-input bg-transparent px-2.5 py-1 text-foreground text-xs outline-none transition-colors placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 dark:bg-input/30",
                     disabled,
-                    value: value.postcode,
+                    id: "field-postcode",
                     onChange: (e) => handleFieldChange("postcode", e.target.value),
-                    className: "block h-8 w-full rounded-none border border-input bg-transparent px-2.5 py-1 text-foreground text-xs outline-none transition-colors placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 dark:bg-input/30",
-                    placeholder: "Postcode"
+                    placeholder: "Postcode",
+                    type: "text",
+                    value: value.postcode
                   }
                 )
               ] })
@@ -3101,6 +2923,176 @@ function AddressFieldGroup({
     }
   );
 }
+function AddressFormField({
+  label,
+  labelClassName,
+  errorClassName,
+  error,
+  required,
+  disabled,
+  id: customId,
+  className,
+  ...autocompleteProps
+}) {
+  const id = customId ?? "wherabouts-field";
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex flex-col gap-2", "data-slot": "address-form-field", children: [
+    /* @__PURE__ */ jsxRuntime.jsxs(
+      "label",
+      {
+        className: cn(
+          "block font-medium text-gray-900 text-sm",
+          labelClassName
+        ),
+        htmlFor: id,
+        children: [
+          label,
+          required && /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", className: "ml-1 text-red-600", children: "*" })
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsxRuntime.jsx(
+      AddressAutocomplete,
+      {
+        ...autocompleteProps,
+        className,
+        disabled,
+        error,
+        id,
+        required
+      }
+    ),
+    error && /* @__PURE__ */ jsxRuntime.jsx(
+      "p",
+      {
+        "aria-live": "polite",
+        className: cn("text-red-600 text-sm", errorClassName),
+        role: "alert",
+        children: error
+      }
+    )
+  ] });
+}
+var toGeocodeAddress = (address) => address ? {
+  id: address.id,
+  formattedAddress: address.formattedAddress,
+  latitude: address.latitude,
+  longitude: address.longitude
+} : null;
+function useForwardGeocode(client, query) {
+  const [data, setData] = react.useState(null);
+  const [loading, setLoading] = react.useState(false);
+  const [error, setError] = react.useState(null);
+  react.useEffect(() => {
+    if (!query) {
+      setData(null);
+      setError(null);
+      return;
+    }
+    const controller = new AbortController();
+    async function fetch() {
+      setLoading(true);
+      setError(null);
+      try {
+        const response = await client.geocode.forward(
+          { q: query },
+          { signal: controller.signal }
+        );
+        if (controller.signal.aborted) {
+          return;
+        }
+        setData(toGeocodeAddress(response.address));
+      } catch (err) {
+        if (controller.signal.aborted) {
+          return;
+        }
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setData(null);
+      } finally {
+        if (!controller.signal.aborted) {
+          setLoading(false);
+        }
+      }
+    }
+    fetch();
+    return () => {
+      controller.abort();
+    };
+  }, [client, query]);
+  return { data, loading, error };
+}
+function ForwardGeocodeInput({
+  client,
+  query,
+  onResult,
+  className,
+  disabled,
+  placeholder = "Coordinates will appear here",
+  id
+}) {
+  const { data } = useForwardGeocode(client, query);
+  react.useEffect(() => {
+    onResult?.({
+      latitude: data?.latitude ?? null,
+      longitude: data?.longitude ?? null,
+      formattedAddress: data?.formattedAddress ?? null
+    });
+  }, [data, onResult]);
+  const displayText = data ? `${data.latitude.toFixed(4)}, ${data.longitude.toFixed(4)}` : "";
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "input",
+    {
+      className: cn(
+        "block h-8 w-full cursor-default rounded-none border border-input bg-muted/40 px-2.5 py-1 text-foreground text-xs",
+        className
+      ),
+      "data-slot": "geocode-input",
+      disabled,
+      id,
+      placeholder,
+      readOnly: true,
+      type: "text",
+      value: displayText
+    }
+  );
+}
+function ReverseGeocodeInput({
+  client,
+  latitude,
+  longitude,
+  onResult,
+  className,
+  disabled,
+  placeholder = "Address will appear here",
+  id
+}) {
+  const { address, distance } = react$1.useReverseGeocode(
+    client,
+    latitude != null && longitude != null ? { lat: latitude, lng: longitude } : null
+  );
+  react.useEffect(() => {
+    onResult?.({
+      address: address?.formattedAddress ?? null,
+      distance: distance ?? null
+    });
+  }, [address, distance, onResult]);
+  const displayText = address?.formattedAddress ?? "";
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "input",
+    {
+      className: cn(
+        "block h-8 w-full cursor-default rounded-none border border-input bg-muted/40 px-2.5 py-1 text-foreground text-xs",
+        className
+      ),
+      "data-slot": "geocode-input",
+      disabled,
+      id,
+      placeholder,
+      readOnly: true,
+      type: "text",
+      value: displayText
+    }
+  );
+}
 
 exports.AddressAutocomplete = AddressAutocomplete;
 exports.AddressFieldGroup = AddressFieldGroup;