@wherabouts/react-ui 0.1.0 → 0.3.0

package/docs/address-form-field.md

@@ -0,0 +1,198 @@
+# AddressFormField
+
+## Summary
+
+`AddressAutocomplete` wrapped with a `<label>` and error styling — a drop-in form field. Accepts every `AddressAutocomplete` prop plus `label`, `labelClassName`, and `errorClassName`.
+
+## When to use / when not
+
+**Use it when:**
+
+- You need a labelled address-search field inside a form — this is the right default
+  for checkout forms, shipping address capture, and any other form where the label and
+  error text should be co-located with the input.
+- You want required-field marking (`*`) and accessible error text (`role="alert"`,
+  `aria-live="polite"`) without wiring them up yourself.
+- You're already using `AddressAutocomplete` props and just want a label + error wrapper
+  around them with no extra setup.
+
+**Don't use it when:**
+
+- You need the raw autocomplete without any label or error chrome — use
+  `AddressAutocomplete` directly and bring your own `<label>`.
+- You're editing an already-known, structured address (street/suburb/state/postcode) —
+  use `AddressFieldGroup` instead.
+- You only need to resolve free text to coordinates without a suggestion dropdown — use
+  `ForwardGeocodeInput`.
+
+## Import & minimal example
+
+```tsx
+import { createWheraboutsClient } from "@wherabouts/sdk";
+import { AddressFormField } from "@wherabouts/react-ui";
+import "@wherabouts/react-ui/styles.css";
+
+const client = createWheraboutsClient({ apiKey: import.meta.env.VITE_WHERABOUTS_KEY });
+
+export function Checkout() {
+  return (
+    <AddressFormField client={client} label="Delivery address" required onSelect={setAddress} />
+  );
+}
+```
+
+## Worked examples
+
+### 1. Controlled selection state
+
+Store the selected address from `onSelect`; surface it elsewhere in the form:
+
+```tsx
+function DeliveryAddress() {
+  const [selected, setSelected] = useState<AddressWithParsed | null>(null);
+
+  return (
+    <div>
+      <AddressFormField
+        client={client}
+        label="Delivery address"
+        placeholder="Start typing…"
+        onSelect={(address) => setSelected(address)}
+        required
+      />
+      {selected && (
+        <p>
+          Selected: {selected.streetAddress}, {selected.suburb} {selected.state}{" "}
+          {selected.postcode}
+        </p>
+      )}
+    </div>
+  );
+}
+```
+
+### 2. TanStack Form wiring
+
+Wire `onSelect` to a TanStack Form field's `handleChange`, and pass the field's
+validation error to `error`:
+
+```tsx
+import { useForm } from "@tanstack/react-form";
+
+function CheckoutForm() {
+  const form = useForm({
+    defaultValues: { address: null as AddressWithParsed | null },
+  });
+
+  return (
+    <form.Field name="address">
+      {(field) => (
+        <AddressFormField
+          client={client}
+          label="Shipping address"
+          onSelect={(address) => field.handleChange(address)}
+          error={field.state.meta.errors?.[0]}
+          required
+        />
+      )}
+    </form.Field>
+  );
+}
+```
+
+### 3. Custom label and error styles
+
+Override label and error appearance via `labelClassName` and `errorClassName`:
+
+```tsx
+<AddressFormField
+  client={client}
+  label="Pickup location"
+  labelClassName="text-lg font-semibold text-brand-900"
+  errorClassName="font-medium"
+  error={validationError}
+  onSelect={setAddress}
+/>
+```
+
+### 4. Geolocation / proximity bias
+
+All `AddressAutocomplete` props are forwarded — including geolocation:
+
+```tsx
+<AddressFormField
+  client={client}
+  label="Delivery address"
+  enableGeolocation
+  onSelect={setAddress}
+  required
+/>
+```
+
+## Props
+
+`AddressFormField` extends every prop from `AddressAutocomplete` (see
+[AddressAutocomplete docs](./address-autocomplete.md)) and adds:
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — | **Required.** Text content of the `<label>` element. |
+| `labelClassName` | `string` | — | Additional class(es) applied to the `<label>` element. |
+| `errorClassName` | `string` | — | Additional class(es) applied to the error text `<p>` element. |
+
+All `AddressAutocomplete` props are forwarded unchanged. Key inherited props:
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `client` | `WheraboutsClient` | — | **Required.** SDK client created with `createWheraboutsClient`. |
+| `onSelect` | `(address: AddressWithParsed) => void` | — | Called when a suggestion is selected. |
+| `onQueryChange` | `(query: string) => void` | — | Called as the input text changes. |
+| `placeholder` | `string` | — | Input placeholder text. |
+| `debounceMs` | `number` | `300` | Debounce in ms before querying the API. |
+| `minCharsToSearch` | `number` | `2` | Minimum characters typed before searching. |
+| `maxSuggestions` | `number` | `5` | Maximum number of suggestions to show. |
+| `enableGeolocation` | `boolean` | `false` | Use the browser's geolocation to bias results by proximity. |
+| `userLat` | `number` | — | Explicit latitude for proximity bias. |
+| `userLng` | `number` | — | Explicit longitude for proximity bias. |
+| `disabled` | `boolean` | — | Disable the input. |
+| `required` | `boolean` | — | Mark the input as required (also renders `*` next to the label). |
+| `error` | `string` | — | External error message; renders below the input with `role="alert"`. |
+| `id` | `string` | `"wherabouts-field"` | Forwarded to the input element and linked to the label via `htmlFor`. |
+| `className` | `string` | — | Class applied to the `AddressAutocomplete` root container. |
+
+## Accessibility
+
+- The component renders a `<label>` with `htmlFor` set to the same `id` as the
+  underlying `AddressAutocomplete` input (default `"wherabouts-field"`). This
+  association satisfies WCAG 2.1 SC 1.3.1 and ensures screen readers announce the
+  label when the input is focused.
+- Pass a custom `id` when you render multiple `AddressFormField` instances on the
+  same page to keep `htmlFor`/`id` pairs unique.
+- When `required` is `true`, a `*` character is rendered `aria-hidden="true"` (so it
+  is not read by screen readers) alongside the visible label text; the `required`
+  attribute is forwarded to the input so assistive technology announces it natively.
+- When `error` is set, a `<p role="alert" aria-live="polite">` is rendered below the
+  input. Screen readers will announce the error text without the user having to navigate
+  to it. The `errorClassName` prop lets you style this element to match your design
+  system.
+- All keyboard navigation and ARIA combobox semantics are inherited from
+  `AddressAutocomplete` — see the [AddressAutocomplete accessibility section](./address-autocomplete.md#accessibility).
+
+## Recipes & edge cases
+
+- **Multiple fields on one page:** Always supply a unique `id` (e.g. `id="billing-address"`,
+  `id="shipping-address"`) when rendering more than one `AddressFormField` on the same
+  page. Without it, both fields default to `id="wherabouts-field"`, which breaks the
+  `htmlFor` association and is invalid HTML.
+- **Passing `error` from form validation vs. API errors:** The `error` prop accepts an
+  external string (e.g. from TanStack Form's `field.state.meta.errors`) and renders it
+  below the input. API-level errors from the autocomplete itself surface inside the
+  dropdown via `AddressAutocomplete`'s built-in error slot, not through this prop.
+- **Debounce / min-chars tuning:** Inherits `AddressAutocomplete` defaults
+  (`debounceMs={300}`, `minCharsToSearch={2}`). For high-traffic forms, raise both to
+  reduce API call volume.
+- **`sessionToken` for billing:** Pass `newSessionToken()` from the SDK as `sessionToken`
+  to group a whole keystroke sequence into a single billable autocomplete session.
+- **Clearing the field:** There is no imperative `clear()` API. If you need to clear
+  the field programmatically (e.g. after form submit), unmount and remount the component
+  or use a React `key` change.

package/docs/forward-geocode-input.md

@@ -0,0 +1,115 @@
+# ForwardGeocodeInput
+
+## Summary
+
+Resolves a free-text address string to coordinates (forward geocoding) as the `query` prop changes. Controlled: the parent owns `query` and receives geocode results via `onResult`. Renders a read-only display input showing the resolved `latitude, longitude` pair.
+
+## When to use / when not
+
+**Use it when:**
+
+- You have a text query (from a search box, form field, or programmatic source) and need the corresponding coordinates without building your own geocode loop.
+- You want a lightweight read-only coordinate display driven by an external input.
+- You need to react to resolved coordinates (e.g. drop a map pin, store lat/lng alongside a form submission).
+
+**Don't use it when:**
+
+- You need the user to type and search interactively in a single input — use `AddressAutocomplete` instead (it handles debounce, suggestions, and selection in one component).
+- You have coordinates and want the human-readable address — use `ReverseGeocodeInput` instead.
+- You need editable lat/lng fields — wire your own inputs to `useForwardGeocode` directly.
+
+## Import & minimal example
+
+```tsx
+import { createWheraboutsClient } from "@wherabouts/sdk";
+import { ForwardGeocodeInput } from "@wherabouts/react-ui";
+
+const client = createWheraboutsClient({ apiKey: "..." });
+
+function MyComponent() {
+  const [query, setQuery] = React.useState("");
+
+  return (
+    <>
+      <input value={query} onChange={(e) => setQuery(e.target.value)} />
+      <ForwardGeocodeInput
+        client={client}
+        query={query}
+        onResult={(r) => console.log(r.latitude, r.longitude)}
+      />
+    </>
+  );
+}
+```
+
+## Worked examples
+
+### 1. Store resolved coordinates on form submit
+
+```tsx
+const [query, setQuery] = React.useState("");
+const [coords, setCoords] = React.useState<{
+  lat: number | null;
+  lng: number | null;
+}>({ lat: null, lng: null });
+
+<input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Enter address" />
+<ForwardGeocodeInput
+  client={client}
+  query={query}
+  onResult={(r) => setCoords({ lat: r.latitude, lng: r.longitude })}
+  placeholder="Resolved coordinates"
+/>
+```
+
+### 2. Debounce the query to reduce API requests
+
+The component fires a geocode request on every `query` change. If `query` comes from a fast-changing input (e.g. keystrokes), debounce before passing to `query`:
+
+```tsx
+// Replace with your preferred debounce hook (e.g. `use-debounce`).
+import { useDebouncedValue } from "your-debounce-hook";
+
+const [raw, setRaw] = React.useState("");
+const debouncedQuery = useDebouncedValue(raw, 300);
+
+<input value={raw} onChange={(e) => setRaw(e.target.value)} />
+<ForwardGeocodeInput client={client} query={debouncedQuery} onResult={handleResult} />
+```
+
+### 3. Skip geocoding when query is empty
+
+Pass `query={null}` (or an empty string) to suppress the network request entirely:
+
+```tsx
+<ForwardGeocodeInput client={client} query={query || null} onResult={handleResult} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `client` | `WheraboutsClient` | **Required** | SDK client created with `createWheraboutsClient`. |
+| `query` | `string \| null` | **Required** | Address text to geocode. `null` or empty string skips the request. |
+| `onResult` | `(r: { latitude: number \| null; longitude: number \| null; formattedAddress: string \| null }) => void` | — | Called whenever the resolved result changes. All fields are `null` when no result is available. |
+| `placeholder` | `string` | `"Coordinates will appear here"` | Placeholder text for the read-only display input. |
+| `id` | `string` | — | `id` forwarded to the input element. |
+| `className` | `string` | — | Additional CSS class applied to the input element. |
+| `disabled` | `boolean` | `false` | Disables the input. |
+
+> **Controlled component:** `ForwardGeocodeInput` does not own `query`. Your component must supply and update it. The component only renders the resolved coordinate string; it does not accept user typing.
+
+## Accessibility
+
+- The component renders a native `<input type="text" readOnly>` — screen readers announce it as a text field with the current value.
+- Supply a visible `<label>` or `aria-label` / `aria-labelledby` targeting the `id` prop so assistive technologies identify the field.
+- The `disabled` prop produces the standard disabled input state, which is communicated to screen readers automatically.
+- Because the input is read-only, keyboard users cannot accidentally modify the displayed value.
+
+## Recipes & edge cases
+
+- **`null` query = no request:** Pass `query={null}` to explicitly suppress geocoding (e.g. before the user has typed anything). An empty string `""` also produces no result.
+- **Debouncing the query:** The component fires on every `query` change. Debounce upstream (e.g. 300 ms) if `query` comes from keystroke events to avoid excessive API calls.
+- **`onResult` on every render cycle:** `onResult` is called inside a `useEffect` that runs whenever the resolved `data` changes. If you pass an inline callback, wrap it in `useCallback` to avoid firing on every parent render.
+- **All-null result:** When the geocode fails or returns no match, `onResult` is still called with `{ latitude: null, longitude: null, formattedAddress: null }`. Guard against nulls before using the values.
+- **Display format:** The component renders `"lat.toFixed(4), lng.toFixed(4)"` in the input. If you need raw numeric values, consume them from the `onResult` callback instead.

package/docs/reverse-geocode-input.md

@@ -0,0 +1,124 @@
+# ReverseGeocodeInput
+
+## Summary
+
+Resolves a `latitude`/`longitude` pair to the nearest address (reverse geocoding). No request is made until both coordinates are non-null.
+
+## When to use / when not
+
+**Use it when:**
+
+- You have coordinates (e.g. from a GPS fix, map click, or device location) and need the human-readable address for display or storage.
+- You want a lightweight read-only address display that reacts to changing coordinates.
+- You need to react to the resolved address (e.g. prefill a form field, log the location label, show the nearest street address).
+
+**Don't use it when:**
+
+- You need the user to type and search interactively in a single input — use `AddressAutocomplete` instead (it handles debounce, suggestions, and selection in one component).
+- You have a text query and want coordinates — use `ForwardGeocodeInput` instead.
+- You need editable address fields — wire your own inputs to `useReverseGeocode` directly.
+
+## Import & minimal example
+
+```tsx
+import { createWheraboutsClient } from "@wherabouts/sdk";
+import { ReverseGeocodeInput } from "@wherabouts/react-ui";
+
+const client = createWheraboutsClient({ apiKey: "..." });
+
+function MyComponent() {
+  const [coords, setCoords] = React.useState<{
+    lat: number | null;
+    lng: number | null;
+  }>({ lat: null, lng: null });
+
+  return (
+    <ReverseGeocodeInput
+      client={client}
+      latitude={coords.lat}
+      longitude={coords.lng}
+      onResult={(r) => console.log(r.address, r.distance)}
+    />
+  );
+}
+```
+
+## Worked examples
+
+### 1. Show address when user clicks a map
+
+```tsx
+const [lat, setLat] = React.useState<number | null>(null);
+const [lng, setLng] = React.useState<number | null>(null);
+const [label, setLabel] = React.useState<string>("");
+
+// Imagine mapInstance.on("click", ...) sets lat/lng
+<ReverseGeocodeInput
+  client={client}
+  latitude={lat}
+  longitude={lng}
+  onResult={(r) => setLabel(r.address ?? "Unknown location")}
+  placeholder="Click the map to resolve an address"
+/>
+<p>Selected: {label || "—"}</p>
+```
+
+### 2. Display distance alongside the resolved address
+
+```tsx
+const [distance, setDistance] = React.useState<number | null>(null);
+
+<ReverseGeocodeInput
+  client={client}
+  latitude={-27.4698}
+  longitude={153.0251}
+  onResult={(r) => setDistance(r.distance)}
+/>
+{distance !== null && (
+  <p>Distance from nearest address: {distance.toFixed(1)} m</p>
+)}
+```
+
+### 3. Hold the request until both coordinates are available
+
+Pass `null` for either coordinate to suppress the network request entirely. The component renders its placeholder until a valid pair arrives:
+
+```tsx
+<ReverseGeocodeInput
+  client={client}
+  latitude={gpsReady ? lat : null}
+  longitude={gpsReady ? lng : null}
+  onResult={handleResult}
+  placeholder="Waiting for GPS fix…"
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `client` | `WheraboutsClient` | **Required** | SDK client created with `createWheraboutsClient`. |
+| `latitude` | `number \| null` | **Required** | Latitude to reverse-geocode. `null` suppresses the request. |
+| `longitude` | `number \| null` | **Required** | Longitude to reverse-geocode. `null` suppresses the request. |
+| `onResult` | `(r: { address: string \| null; distance: number \| null }) => void` | — | Called whenever the resolved address changes. Both fields are `null` when no result is available. |
+| `placeholder` | `string` | `"Address will appear here"` | Placeholder text for the read-only display input. |
+| `id` | `string` | — | `id` forwarded to the input element. |
+| `className` | `string` | — | Additional CSS class applied to the input element. |
+| `disabled` | `boolean` | `false` | Disables the input. |
+
+> **Null-coordinate handling:** No geocode request is made until **both** `latitude` and `longitude` are non-null. The component renders its placeholder while either coordinate is `null`.
+
+## Accessibility
+
+- The component renders a native `<input type="text" readOnly>` — screen readers announce it as a text field with the current value.
+- Supply a visible `<label>` or `aria-label` / `aria-labelledby` targeting the `id` prop so assistive technologies identify the field.
+- The `disabled` prop produces the standard disabled input state, which is communicated to screen readers automatically.
+- Because the input is read-only, keyboard users cannot accidentally modify the displayed value.
+
+## Recipes & edge cases
+
+- **Both coordinates must be non-null:** If either `latitude` or `longitude` is `null`, no request is fired and the input shows the placeholder. Use this deliberately to gate the request on GPS availability or user interaction.
+- **`onResult` on every render cycle:** `onResult` is called inside a `useEffect` that runs whenever the resolved data changes. If you pass an inline callback, wrap it in `useCallback` to avoid firing on every parent render.
+- **All-null result:** When reverse geocoding returns no match, `onResult` is still called with `{ address: null, distance: null }`. Guard against nulls before using the values.
+- **`address` is `formattedAddress` from the API:** The `address` field in `onResult` is the formatted address string from the nearest result (or `null` if unavailable). It is also what the read-only input displays.
+- **`distance` is in metres:** The `distance` field reports how far the resolved address is from the supplied coordinates, in metres.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@wherabouts/react-ui",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Production-ready React components for Wherabouts SDK — address autocomplete, geocoding, and form fields with accessibility and customization.",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
@@ -17,38 +17,45 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "LICENSE"
   ],
-  "scripts": {
-    "build": "tsup && node scripts/build-css.mjs",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "pnpm build"
-  },
   "peerDependencies": {
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
-    "@wherabouts/sdk": ">=0.4.2",
+    "@wherabouts/sdk": ">=0.5.0",
     "@wherabouts/react": ">=0.2.0"
   },
   "devDependencies": {
+    "@storybook/addon-a11y": "^9.0.0",
+    "@storybook/react-vite": "^9.0.0",
     "@testing-library/jest-dom": "^6.1.5",
     "@testing-library/react": "^15.0.0",
     "@testing-library/user-event": "^14.5.1",
-    "@types/react": "catalog:",
-    "@types/react-dom": "catalog:",
-    "@wherabouts/react": "workspace:*",
-    "@wherabouts/sdk": "workspace:*",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.1.1",
     "jsdom": "^23.0.1",
-    "react": "catalog:",
-    "react-dom": "catalog:",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "storybook": "^9.0.0",
     "tailwind-merge": "^2.3.0",
     "tsup": "^8.0.2",
     "typescript": "^5.4.4",
-    "vitest": "^1.2.0"
+    "vite": "^7.0.2",
+    "vitest": "^1.2.0",
+    "@wherabouts/sdk": "0.6.0",
+    "@wherabouts/react": "0.3.0"
+  },
+  "scripts": {
+    "build": "tsup && node scripts/build-css.mjs",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "storybook": "storybook dev -p 6006 --no-open",
+    "build-storybook": "storybook build"
   }
-}
+}