@wherabouts/react-ui 0.1.0 → 0.1.1

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,6 +1,6 @@
 {
   "name": "@wherabouts/react-ui",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Production-ready React components for Wherabouts SDK — address autocomplete, geocoding, and form fields with accessibility and customization.",
   "license": "UNLICENSED",
@@ -17,6 +17,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -25,7 +26,9 @@
     "dev": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "pnpm build"
+    "prepublishOnly": "pnpm build",
+    "storybook": "storybook dev -p 6006 --no-open",
+    "build-storybook": "storybook build"
   },
   "peerDependencies": {
     "react": ">=19.0.0",
@@ -34,6 +37,8 @@
     "@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",
@@ -46,9 +51,11 @@
     "jsdom": "^23.0.1",
     "react": "catalog:",
     "react-dom": "catalog:",
+    "storybook": "^9.0.0",
     "tailwind-merge": "^2.3.0",
     "tsup": "^8.0.2",
     "typescript": "^5.4.4",
+    "vite": "^7.0.2",
     "vitest": "^1.2.0"
   }
 }