@wherabouts/react-ui 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to `@wherabouts/react-ui` are documented here. This project adheres
+to [Semantic Versioning](https://semver.org/) and the
+[Keep a Changelog](https://keepachangelog.com/) format.
+
+## [0.1.0] - 2026-06-18
+
+First publishable release.
+
+### Added
+
+- **`AddressAutocomplete`** — debounced, WAI-ARIA combobox address search with keyboard
+  navigation, proximity bias (`enableGeolocation` / `userLat` / `userLng`), session
+  tokens, i18n strings, and fully customizable `render*` slots.
+- **`AddressFormField`** — `AddressAutocomplete` with a label and error styling for forms.
+- **`ForwardGeocodeInput`** — resolves free-text addresses to coordinates.
+- **`ReverseGeocodeInput`** — resolves coordinates to the nearest address.
+- **`AddressFieldGroup`** — controlled street/suburb/state/postcode field group.
+- Utilities `toAddressWithParsed` and `cn`, plus exported component prop and value types.
+- Prebuilt `styles.css` and dual ESM + CJS builds with bundled type declarations.
+
+### Notes
+
+- International address coverage (US/EU and more) is in **beta** and rolling out;
+  availability may vary by deployment. Australian (G-NAF) coverage is authoritative.
+</content>

package/README.md

@@ -0,0 +1,176 @@
+# @wherabouts/react-ui
+
+Production-ready, accessible React components for the [Wherabouts](https://wherabouts.com)
+location API — address autocomplete, forward/reverse geocoding inputs, and structured
+address form fields. Built on [`@wherabouts/sdk`](https://www.npmjs.com/package/@wherabouts/sdk),
+styled with Tailwind, and shipped with a prebuilt stylesheet so you can drop them in
+without any build setup.
+
+> **Coverage:** Authoritative Australian addresses (G-NAF). International coverage
+> (US, parts of the EU, and more) is in **beta** and rolling out — availability may
+> vary by deployment.
+
+## Requirements
+
+- React **19+** and React DOM 19+ (peer dependencies)
+- A Wherabouts API key (`wh_...`)
+
+## Installation
+
+```bash
+# npm
+npm install @wherabouts/react-ui @wherabouts/sdk @wherabouts/react
+
+# pnpm
+pnpm add @wherabouts/react-ui @wherabouts/sdk @wherabouts/react
+
+# yarn
+yarn add @wherabouts/react-ui @wherabouts/sdk @wherabouts/react
+```
+
+Peer dependencies: `react` & `react-dom` (>=19), `@wherabouts/sdk` (>=0.4.2), and
+`@wherabouts/react` (>=0.2.0).
+
+Import the stylesheet once, near your app root:
+
+```ts
+import "@wherabouts/react-ui/styles.css";
+```
+
+## Quick start
+
+Every component takes a `client` created with the SDK. Create it once and share it.
+
+```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, address.latitude, address.longitude)}
+    />
+  );
+}
+```
+
+> **Note:** Use a **publishable** key scoped to your origin for browser use. Never ship a
+> secret server key to the client.
+
+## Components
+
+### `AddressAutocomplete`
+
+Debounced address search with a fully accessible (WAI-ARIA combobox) suggestion list,
+keyboard navigation, and customizable rendering.
+
+```tsx
+<AddressAutocomplete
+  client={client}
+  onSelect={(address) => setAddress(address)}
+  minCharsToSearch={3}
+  debounceMs={200}
+  maxSuggestions={8}
+  enableGeolocation
+/>
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `client` | `WheraboutsClient` | — | **Required.** SDK client. |
+| `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. |
+| `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). |
+| `disabled` / `required` | `boolean` | `false` | Standard input states. |
+| `error` | `string` | — | External error message to display. |
+| `id` / `className` | `string` | — | Pass-through for the input. |
+| `i18nStrings` | `Partial<AddressI18nStrings>` | — | Override built-in labels/strings. |
+| `renderSuggestion` | `(address, isActive) => ReactNode` | — | Custom suggestion row. |
+| `renderEmpty` / `renderLoading` / `renderError` | `() => ReactNode` | — | Custom empty/loading/error states. |
+
+### `AddressFormField`
+
+`AddressAutocomplete` wrapped with a `<label>` and error styling — drop-in for forms.
+Accepts every `AddressAutocomplete` prop plus:
+
+| Prop | Type | Description |
+|---|---|---|
+| `label` | `string` | **Required.** Field label. |
+| `labelClassName` | `string` | Class for the label element. |
+| `errorClassName` | `string` | Class for the error text. |
+
+```tsx
+<AddressFormField client={client} label="Delivery address" required onSelect={setAddress} />
+```
+
+### `ForwardGeocodeInput`
+
+Resolves a free-text address to coordinates as `query` changes (forward geocoding).
+
+| Prop | Type | Description |
+|---|---|---|
+| `client` | `WheraboutsClient` | **Required.** SDK client. |
+| `query` | `string \| null` | Address text to geocode. |
+| `onResult` | `(r: { latitude, longitude, formattedAddress }) => void` | Geocode result callback. |
+| `placeholder` / `id` / `className` | `string` | Pass-through. |
+| `disabled` | `boolean` | Disabled state. |
+
+### `ReverseGeocodeInput`
+
+Resolves `latitude`/`longitude` to the nearest address (reverse geocoding).
+
+| Prop | Type | Description |
+|---|---|---|
+| `client` | `WheraboutsClient` | **Required.** SDK client. |
+| `latitude` / `longitude` | `number \| null` | Coordinates to reverse-geocode. |
+| `onResult` | `(r: { address, distance }) => void` | Result callback. |
+| `placeholder` / `id` / `className` | `string` | Pass-through. |
+| `disabled` | `boolean` | Disabled state. |
+
+### `AddressFieldGroup`
+
+A controlled group of structured inputs (street, suburb, state, postcode) for editing a
+full address.
+
+| Prop | Type | Description |
+|---|---|---|
+| `client` | `WheraboutsClient` | **Required.** SDK client. |
+| `value` | `AddressFieldGroupValue` | **Required.** Controlled value. |
+| `onChange` | `(value: AddressFieldGroupValue) => void` | **Required.** Change handler. |
+| `streetLabel` / `suburbLabel` / `stateLabel` / `postcodeLabel` | `string` | Override field labels. |
+| `disabled` / `className` | — | Standard states. |
+
+## Utilities & types
+
+- `toAddressWithParsed(suggestion)` — map a raw SDK `AddressSuggestion` to the
+  `AddressWithParsed` shape used by these components.
+- `cn(...classes)` — the `clsx` + `tailwind-merge` class combiner used internally.
+- Exported types: `AddressWithParsed`, `AddressI18nStrings`, `AddressValidateFn`,
+  `AddressSuggestionInput`, and each component's `*Props`.
+
+## Styling
+
+The package ships a prebuilt `styles.css` (import it once, as shown above). Components use
+neutral design tokens and accept `className` for overrides; you can also fully replace
+suggestion/empty/loading/error rendering via the `render*` props on `AddressAutocomplete`.
+
+## TypeScript
+
+Ships dual ESM + CJS builds with bundled type declarations. All props and callback
+payloads are fully typed.
+
+## License
+
+UNLICENSED — © Wherabouts. See the repository for usage terms.
+</content>