@wherabouts/react-ui 0.1.0 → 0.1.1

package/dist/styles.css

@@ -76,14 +76,14 @@
 	display: block;
 	width: 100%;
 	padding: var(--wherabouts-spacing-sm) var(--wherabouts-spacing-md);
-	border: var(--wherabouts-border-width) solid
-		var(--wherabouts-color-border);
-	border-radius: var(--wherabouts-border-radius);
-	background-color: var(--wherabouts-color-input-bg);
-	color: var(--wherabouts-color-input-text);
 	font-size: var(--wherabouts-font-size-base);
 	font-weight: var(--wherabouts-font-weight-normal);
-	transition: border-color var(--wherabouts-transition-fast),
+	color: var(--wherabouts-color-input-text);
+	background-color: var(--wherabouts-color-input-bg);
+	border: var(--wherabouts-border-width) solid var(--wherabouts-color-border);
+	border-radius: var(--wherabouts-border-radius);
+	transition:
+		border-color var(--wherabouts-transition-fast),
 		box-shadow var(--wherabouts-transition-fast);
 }
 
@@ -94,14 +94,13 @@
 [data-slot="address-input"]:focus {
 	outline: none;
 	border-color: var(--wherabouts-color-focus-ring);
-	box-shadow: 0 0 0 3px
-		hsl(221.2 83.2% 53.3% / 0.1);
+	box-shadow: 0 0 0 3px hsl(221.2 83.2% 53.3% / 0.1);
 }
 
 [data-slot="address-input"]:disabled {
-	opacity: 0.5;
 	cursor: not-allowed;
 	background-color: hsl(0 0% 95% / 0.5);
+	opacity: 0.5;
 }
 
 [data-slot="address-input"][aria-invalid="true"] {
@@ -109,8 +108,7 @@
 }
 
 [data-slot="address-input"][aria-invalid="true"]:focus {
-	box-shadow: 0 0 0 3px
-		hsl(0 84.2% 60.2% / 0.1);
+	box-shadow: 0 0 0 3px hsl(0 84.2% 60.2% / 0.1);
 }
 
 /* ── Dropdown Listbox ──────────────────────────────────────── */
@@ -148,17 +146,17 @@
 
 /* ── Suggestion Item ───────────────────────────────────────── */
 [data-slot="address-item"] {
+	display: flex;
+	align-items: center;
+	min-height: 44px;
 	padding: var(--wherabouts-spacing-sm) var(--wherabouts-spacing-md);
 	margin: 2px 0;
-	border-radius: var(--wherabouts-border-radius-sm);
-	background-color: var(--wherabouts-color-item-bg);
+	font-size: var(--wherabouts-font-size-base);
 	color: var(--wherabouts-color-item-text);
 	cursor: pointer;
-	font-size: var(--wherabouts-font-size-base);
+	background-color: var(--wherabouts-color-item-bg);
+	border-radius: var(--wherabouts-border-radius-sm);
 	transition: background-color var(--wherabouts-transition-fast);
-	min-height: 44px;
-	display: flex;
-	align-items: center;
 }
 
 [data-slot="address-item"]:hover {
@@ -173,11 +171,11 @@
 [data-slot="address-item"][data-status="loading"],
 [data-slot="address-item"][data-status="error"],
 [data-slot="address-item"][data-status="empty"] {
-	cursor: default;
 	justify-content: center;
+	min-height: 40px;
 	font-size: var(--wherabouts-font-size-sm);
 	color: var(--wherabouts-color-text-muted);
-	min-height: 40px;
+	cursor: default;
 }
 
 [data-slot="address-item"][data-status="error"] {
@@ -199,15 +197,15 @@
 }
 
 [data-slot="address-form-field"] label [aria-hidden="true"] {
-	color: var(--wherabouts-color-error);
 	margin-left: 2px;
+	color: var(--wherabouts-color-error);
 }
 
 [data-slot="address-form-field"] [role="alert"] {
 	display: block;
+	margin-top: 2px;
 	font-size: var(--wherabouts-font-size-sm);
 	color: var(--wherabouts-color-error);
-	margin-top: 2px;
 }
 
 /* ── Field Group ───────────────────────────────────────────── */
@@ -246,13 +244,12 @@
 	display: block;
 	width: 100%;
 	padding: var(--wherabouts-spacing-sm) var(--wherabouts-spacing-md);
-	border: var(--wherabouts-border-width) solid
-		var(--wherabouts-color-border);
-	border-radius: var(--wherabouts-border-radius);
-	background-color: hsl(0 0% 97%);
-	color: var(--wherabouts-color-input-text);
 	font-size: var(--wherabouts-font-size-base);
+	color: var(--wherabouts-color-input-text);
 	cursor: default;
+	background-color: hsl(0 0% 97%);
+	border: var(--wherabouts-border-width) solid var(--wherabouts-color-border);
+	border-radius: var(--wherabouts-border-radius);
 }
 
 .dark [data-slot="geocode-input"] {

package/docs/README.md

@@ -0,0 +1,16 @@
+# @wherabouts/react-ui — Component documentation
+
+Detailed, per-component guides with worked examples, full prop tables,
+accessibility notes, and recipes. For a quick overview and install steps, see
+the [package README](../README.md).
+
+These docs mirror the package's [Storybook](../README.md#interactive-docs-storybook),
+where every component has interactive, live examples.
+
+## Components
+
+- [AddressAutocomplete](./address-autocomplete.md) — accessible, debounced address search.
+- [AddressFormField](./address-form-field.md) — labelled form wrapper around the autocomplete.
+- [ForwardGeocodeInput](./forward-geocode-input.md) — resolve free text to coordinates.
+- [ReverseGeocodeInput](./reverse-geocode-input.md) — resolve coordinates to an address.
+- [AddressFieldGroup](./address-field-group.md) — controlled street/suburb/state/postcode group.

package/docs/address-autocomplete.md

@@ -0,0 +1,208 @@
+# AddressAutocomplete
+
+## Summary
+
+Accessible (WAI-ARIA combobox), debounced address search with keyboard navigation, proximity bias, session tokens, i18n strings, and customizable render slots. Provide a `client` created with `createWheraboutsClient`.
+
+## When to use / when not
+
+**Use it when:**
+
+- You need a freeform "start typing an address" search box backed by the Wherabouts
+  autocomplete API (checkout forms, shipping address capture, location search).
+- You want built-in keyboard navigation (arrow keys, enter, escape) and ARIA semantics
+  without wiring up a combobox yourself.
+- You want to bias results toward the user's location (geolocation or explicit lat/lng).
+
+**Don't use it when:**
+
+- You need a labelled form field with built-in error styling — use `AddressFormField`,
+  which wraps this component with a `<label>` and error text.
+- 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 { AddressAutocomplete } from "@wherabouts/react-ui";
+import "@wherabouts/react-ui/styles.css";
+
+const client = createWheraboutsClient({ apiKey: import.meta.env.VITE_WHERABOUTS_KEY });
+
+export function Checkout() {
+  return (
+    <AddressAutocomplete
+      client={client}
+      placeholder="Start typing an address…"
+      onSelect={(address) => console.log(address.formattedAddress)}
+    />
+  );
+}
+```
+
+## Worked examples
+
+### 1. Controlled selection state
+
+`AddressAutocomplete` manages its own input text internally; there is no `value` prop.
+To keep the *selected* address as state in your component, store it from `onSelect` and
+track the raw query text (if you need it) via `onQueryChange`:
+
+```tsx
+function DeliveryAddress() {
+  const [selected, setSelected] = useState<AddressWithParsed | null>(null);
+  const [query, setQuery] = useState("");
+
+  return (
+    <div>
+      <AddressAutocomplete
+        client={client}
+        onQueryChange={setQuery}
+        onSelect={(address) => setSelected(address)}
+        placeholder="Delivery address"
+      />
+      {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 `setValue`, and surface field validation
+errors via the `error` prop:
+
+```tsx
+import { useForm } from "@tanstack/react-form";
+
+function AddressFormExample() {
+  const form = useForm({
+    defaultValues: { address: null as AddressWithParsed | null },
+  });
+
+  return (
+    <form.Field name="address">
+      {(field) => (
+        <AddressAutocomplete
+          client={client}
+          placeholder="Shipping address"
+          onSelect={(address) => field.handleChange(address)}
+          error={field.state.meta.errors?.[0]}
+          required
+        />
+      )}
+    </form.Field>
+  );
+}
+```
+
+### 3. Geolocation / proximity bias
+
+Enable browser geolocation to bias suggestions toward the user's current position, or
+pass explicit coordinates (e.g. from a previously selected map pin) instead:
+
+```tsx
+// Browser geolocation
+<AddressAutocomplete client={client} enableGeolocation onSelect={setAddress} />
+
+// Explicit proximity (e.g. a map center), skips the geolocation prompt
+<AddressAutocomplete
+  client={client}
+  userLat={-33.8688}
+  userLng={151.2093}
+  onSelect={setAddress}
+/>
+```
+
+`userLat`/`userLng` take precedence over `enableGeolocation` when both are provided.
+
+### 4. Custom suggestion renderer
+
+Replace the default street/suburb row with your own markup. `renderSuggestion` receives
+the parsed `AddressWithParsed` result and whether it's the currently keyboard-active row:
+
+```tsx
+<AddressAutocomplete
+  client={client}
+  onSelect={setAddress}
+  renderSuggestion={(address, isActive) => (
+    <span style={{ fontWeight: isActive ? 700 : 400 }}>
+      📍 {address.formattedAddress}
+    </span>
+  )}
+/>
+```
+
+## 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 (instead of geolocation). |
+| `userLng` | `number` | — | Explicit longitude for proximity bias (instead of geolocation). |
+| `sessionToken` | `string` | — | Group a run of keystrokes into one billable search (see SDK `newSessionToken()`). |
+| `disabled` | `boolean` | — | Disable the input. |
+| `required` | `boolean` | — | Mark the input as required. |
+| `error` | `string` | — | External error message to display. |
+| `id` | `string` | `"wherabouts-autocomplete"` | id forwarded to the input element. |
+| `className` | `string` | — | Class applied to the root container. |
+| `i18nStrings` | `Partial<AddressI18nStrings>` | — | Override built-in UI strings (no results, retry, etc.). |
+| `renderSuggestion` | `(address: AddressWithParsed, isActive: boolean) => ReactNode` | — | Render a custom suggestion row. |
+| `renderEmpty` | `() => ReactNode` | — | Render a custom empty state. |
+| `renderLoading` | `() => ReactNode` | — | Render a custom loading state. |
+| `renderError` | `(error: Error \| null) => ReactNode` | — | Render a custom error state. |
+
+## Accessibility
+
+- The input and suggestion list implement the WAI-ARIA 1.2 **combobox** pattern: the
+  input has `role="combobox"` semantics (via the `useCombobox` hook), is associated with
+  a listbox via `aria-controls`, and exposes `aria-expanded` for open/closed state.
+- The currently keyboard-highlighted suggestion is tracked with `aria-activedescendant`
+  on the input, and `aria-selected` on the active `<li>` — this drives the `isActive`
+  flag passed to `renderSuggestion`.
+- **Keyboard support:** Arrow Down/Up move the active suggestion, Enter selects the
+  active suggestion (calling `onSelect` and clearing the query), and Escape closes the
+  dropdown.
+- The component does **not** render its own `<label>`. When using `AddressAutocomplete`
+  directly, pair it with a `<label htmlFor={id}>` (matching the `id` prop, default
+  `"wherabouts-autocomplete"`), or use `AddressFormField`, which does this for you.
+- Loading, error, and empty states are announced as plain list items inside the same
+  listbox region so screen readers traversing the list encounter them in context.
+
+## Recipes & edge cases
+
+- **Tuning `debounceMs` / `minCharsToSearch`:** The defaults (`debounceMs={300}`,
+  `minCharsToSearch={2}`) suit most forms. For high-traffic search-as-you-type UIs where
+  API cost matters, raise `debounceMs` (e.g. `400`) and `minCharsToSearch` (e.g. `4`) to
+  reduce request volume — see the `TunedSearch` Storybook story.
+- **`sessionToken` for billing:** Each keystroke debounce fires a billable autocomplete
+  request. Generate a session token once per "search session" (e.g. when the user
+  focuses the field) with the SDK's `newSessionToken()` and pass it as `sessionToken` so
+  the API can group the whole keystroke sequence into a single billable session instead
+  of billing per request.
+- **Error / empty / loading slots:** Use `renderError`, `renderEmpty`, and `renderLoading`
+  to match your app's design system instead of the built-in text rows. `renderError`
+  receives the underlying `Error` (or `null` if the error came from the external `error`
+  prop rather than the API call) so you can render API-specific messaging.
+- **External vs. API errors:** The `error` prop (e.g. from form validation) and API
+  request failures both surface through the same error slot — the external `error`
+  prop takes precedence when both are present.
+- **Geolocation denial:** If `enableGeolocation` is set and the user denies the browser
+  permission prompt, results simply fall back to unbiased search; there's no separate
+  error state for this today, so don't rely on `i18nStrings.geolocationError` being
+  surfaced automatically by this component.

package/docs/address-field-group.md

@@ -0,0 +1,152 @@
+# AddressFieldGroup
+
+## Summary
+
+A controlled group of structured inputs (street, suburb, state, postcode) for editing a full address. Provide `value` and `onChange`.
+
+## When to use / when not
+
+**Use it when:**
+
+- You need the user to enter or confirm a full postal address split across discrete fields (street, suburb, state, postcode).
+- You want to pre-fill address fields from an autocomplete selection and then let the user correct individual fields.
+- You are building a checkout, registration, or profile form where a structured address is required for storage or validation.
+
+**Don't use it when:**
+
+- You only need the user to search for and select an address as a single value — use `AddressAutocomplete` or `AddressFormField` instead.
+- You need reverse geocoding (coordinates → address display) — use `ReverseGeocodeInput` instead.
+- You need forward geocoding (free text → coordinates) — use `ForwardGeocodeInput` instead.
+
+## Import & minimal example
+
+```tsx
+import { useState } from "react";
+import { createWheraboutsClient } from "@wherabouts/sdk";
+import {
+  AddressFieldGroup,
+  type AddressFieldGroupValue,
+} from "@wherabouts/react-ui";
+
+const client = createWheraboutsClient({ apiKey: "..." });
+
+const EMPTY: AddressFieldGroupValue = {
+  street: "",
+  suburb: "",
+  state: "",
+  postcode: "",
+};
+
+function MyForm() {
+  const [address, setAddress] = useState<AddressFieldGroupValue>(EMPTY);
+
+  return (
+    <AddressFieldGroup
+      client={client}
+      value={address}
+      onChange={setAddress}
+    />
+  );
+}
+```
+
+## Worked examples
+
+### 1. Pre-fill from autocomplete, then allow manual correction
+
+`AddressFieldGroup` renders an `AddressAutocomplete` at the top of the group. Selecting a suggestion fills all four fields automatically. The user can then edit individual fields:
+
+```tsx
+const [address, setAddress] = useState<AddressFieldGroupValue>(EMPTY);
+
+<AddressFieldGroup
+  client={client}
+  value={address}
+  onChange={setAddress}
+/>
+
+<pre>{JSON.stringify(address, null, 2)}</pre>
+```
+
+### 2. Custom field labels (international / regional terminology)
+
+Override any label to match your audience:
+
+```tsx
+<AddressFieldGroup
+  client={client}
+  value={address}
+  onChange={setAddress}
+  streetLabel="Street address"
+  suburbLabel="City"
+  stateLabel="Region"
+  postcodeLabel="ZIP"
+/>
+```
+
+### 3. Disable all fields while submitting
+
+Pass `disabled` to prevent edits during async operations:
+
+```tsx
+const [submitting, setSubmitting] = useState(false);
+
+<AddressFieldGroup
+  client={client}
+  value={address}
+  onChange={setAddress}
+  disabled={submitting}
+/>
+```
+
+### 4. Persist only when all fields are filled
+
+Gate your submit handler on completeness:
+
+```tsx
+const isComplete = Object.values(address).every((v) => v.trim().length > 0);
+
+<button disabled={!isComplete} onClick={handleSubmit}>
+  Save address
+</button>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `client` | `WheraboutsClient` | **Required** | SDK client created with `createWheraboutsClient`. |
+| `value` | `AddressFieldGroupValue` | **Required** | Controlled value for the field group. |
+| `onChange` | `(value: AddressFieldGroupValue) => void` | **Required** | Change handler called with the updated value on any field edit. |
+| `streetLabel` | `string` | `"Street Address"` | Override the street address field label. |
+| `suburbLabel` | `string` | `"Suburb"` | Override the suburb field label. |
+| `stateLabel` | `string` | `"State"` | Override the state field label. |
+| `postcodeLabel` | `string` | `"Postcode"` | Override the postcode field label. |
+| `disabled` | `boolean` | `false` | Disables all fields. |
+| `className` | `string` | — | Additional CSS class applied to the root container. |
+
+### AddressFieldGroupValue
+
+```ts
+interface AddressFieldGroupValue {
+  street: string;
+  suburb: string;
+  state: string;
+  postcode: string;
+}
+```
+
+## Accessibility
+
+- Each field renders a native `<input>` with an explicit `<label>` wired via `htmlFor` — screen readers announce the field name correctly without additional markup.
+- The embedded `AddressAutocomplete` at the top of the group provides its own accessible combobox behaviour; selecting a suggestion fills all four fields and moves focus back to the form flow.
+- The `disabled` prop sets the HTML `disabled` attribute on every input, which is communicated to assistive technologies automatically.
+- Field IDs are static (`field-street`, `field-suburb`, `field-state`, `field-postcode`). If you render multiple `AddressFieldGroup` instances on the same page, use a wrapping `<fieldset>` with a `<legend>` to distinguish them.
+
+## Recipes & edge cases
+
+- **Autocomplete fills all four fields:** When the user selects a suggestion from the embedded `AddressAutocomplete`, `onChange` is called once with all four fields populated from the matched address. The user can then edit individual fields as needed.
+- **Uncontrolled initialisation:** Initialise `value` with the `EMPTY` constant (or your own empty object) rather than leaving fields undefined — all four keys must be strings for controlled inputs to behave correctly.
+- **Validation:** The component does not validate field content. Apply your own validation logic in `onChange` or before form submission.
+- **Layout:** The street field spans the full width; suburb, state, and postcode share a two-column grid. Apply `className` to the root container to constrain width or add spacing.
+- **Multiple instances on one page:** Wrap each instance in a `<fieldset>` + `<legend>` so screen readers distinguish between shipping and billing address groups, as static field IDs are shared.

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.