@swift-food-services/catering-widget 0.1.0-beta.3 → 0.1.0-beta.4

package/README.md

@@ -16,7 +16,10 @@ export default function CateringPage() {
   return (
     <CateringWidget
       publishableKey="pk_live_..."
+      googleMapsApiKey="AIzaSy..."
       onOrderComplete={({ orderId }) => {
+        // Fires after the success-screen countdown (default 15s,
+        // configurable via `onOrderCompleteDelaySeconds`).
         window.location.href = `/thanks?order=${orderId}`;
       }}
     />
@@ -37,11 +40,13 @@ Defaults: Swift-hosted backend, `localStorage` persistence, neutral theme.
 | Prop | Type | Required | Description |
 |---|---|---|---|
 | `publishableKey` | `string` | yes | Your `pk_live_...` or `pk_test_...` key from Swift. |
+| `googleMapsApiKey` | `string` | yes | Google Maps JavaScript API key with the Places library enabled. Used by the address-autocomplete field. |
 | `theme` | `Theme` | no | Primary color, border radius, and font overrides. |
 | `initialData` | `InitialData` | no | Pre-populate event, address, and contact fields. Applied only on first mount. |
 | `stickyTopOffset` | `number` | no | Pixels to offset the widget's internal sticky date/session nav from the top of the viewport. Set this to the height of any sticky/fixed navbar in your host layout so the widget's nav doesn't slide underneath it. Defaults to `0`. |
 | `onReady` | `() => void` | no | Fires when the widget has initialized. |
-| `onOrderComplete` | `(result: OrderCompleteResult) => void` | no | Fires after a successful order submission. |
+| `onOrderComplete` | `(result: OrderCompleteResult) => void` | no | Fires after a successful order submission. See [`onOrderComplete` behaviour](#onordercompleteresult) for the timing. |
+| `onOrderCompleteDelaySeconds` | `number` | no | Seconds to keep the success screen visible before firing `onOrderComplete`. Defaults to `15`. Ignored if `onOrderComplete` is not provided. |
 | `onError` | `(error: WidgetError) => void` | no | Fires on unrecoverable errors (bad key, network, submit failure). |
 
 ## Examples
@@ -58,7 +63,8 @@ export default function Page() {
   const router = useRouter();
   return (
     <CateringWidget
-      publishableKey={process.env.NEXT_PUBLIC_SWIFT_KEY!}
+      publishableKey={process.env.NEXT_PUBLIC_SWIFT_PUBLISHABLE_KEY!}
+      googleMapsApiKey={process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY!}
       onOrderComplete={({ orderId, accessToken }) => {
         router.push(`/orders/${orderId}?token=${accessToken}`);
       }}
@@ -94,6 +100,8 @@ export default function Page() {
       line1: "1 Example Lane",
       city: "London",
       postcode: "E1 6AN",
+      lat: 51.5074,
+      lng: -0.1278,
     },
     contact: { name: "Alice", email: "alice@example.com" },
   }}
@@ -103,6 +111,8 @@ export default function Page() {
 
 Every field in `initialData` is optional. Fields remain editable after pre-fill. `initialData` is only applied on first mount — if the user has a half-finished order in progress (persisted in `localStorage`), the persisted state wins.
 
+**Address requires `lat` and `lng`.** Delivery pricing depends on coordinates, so if you pass a `deliveryAddress` without both `lat` and `lng`, the widget ignores the entire address (no fields are pre-filled) and the guest is asked to pick one via the address-autocomplete field instead. The other `initialData` fields (event date/time, guest count, contact) still apply.
+
 ### Offsetting below a host navbar
 
 If your page has its own sticky/fixed navbar, pass its height as `stickyTopOffset` so the widget's internal date/session nav pins just below it:
@@ -138,12 +148,29 @@ See the generated `dist/index.d.ts` for the full shapes — your IDE picks them
 
 ### `onOrderComplete(result)`
 
-Fires when an order has been successfully submitted. `result` contains:
+Fires after a successful order submission. `result` contains:
 
 - `orderId: string` — Swift's order ID.
 - `accessToken: string` — a token the customer can use to view the order on Swift's hosted view page.
 - `summary: OrderSummary` — structured breakdown of the submitted order.
 
+**Timing.** When `onOrderComplete` is wired, the widget shows its built-in success screen with a "Continuing in N seconds…" countdown for `onOrderCompleteDelaySeconds` seconds (default `15`), then fires the callback. This gives the guest a moment to read the confirmation before the host navigates away. A "Continue now" button under the countdown lets the guest skip the wait — clicking it cancels the timer and fires `onOrderComplete` immediately.
+
+If `onOrderComplete` is **not** wired, the success screen stays up indefinitely. The success screen shows the event, customer, and pricing summary, and any navigation is the host's responsibility (do it from `onOrderComplete`).
+
+**Heads up:** the widget does not navigate on its own. If your `onOrderComplete` runs without triggering a navigation (e.g. you only fire analytics or close a modal), the guest will stay on the widget's order-confirmation page even after the callback fires. To send them elsewhere, do it from inside `onOrderComplete` — `router.push(...)`, `window.location.href = ...`, hide the widget from your layout, etc.
+
+```tsx
+<CateringWidget
+  publishableKey="pk_live_..."
+  googleMapsApiKey="AIzaSy..."
+  onOrderCompleteDelaySeconds={5}
+  onOrderComplete={({ orderId, accessToken }) => {
+    router.push(`/orders/${orderId}?token=${accessToken}`);
+  }}
+/>
+```
+
 ### `onError(error)`
 
 Fires on errors the widget can't recover from. `error.code` is one of:
@@ -168,6 +195,7 @@ Fires on errors the widget can't recover from. `error.code` is one of:
 
 - Getting a publishable key from Swift.
 - Registering your site's origin(s) with Swift.
+- Providing a Google Maps JavaScript API key (with the Places library enabled) via the `googleMapsApiKey` prop. Restrict the key to your own domain(s) in the Google Cloud Console.
 - Rendering `<CateringWidget>` wherever you want the flow to live.
 - Navigating after `onOrderComplete`.
 - Page chrome around the widget.
@@ -175,14 +203,10 @@ Fires on errors the widget can't recover from. `error.code` is one of:
 ## What you're **not** responsible for
 
 - Payment. Swift sends a payment link by email after reviewing the order.
-- Loading Google Maps — the widget handles this internally.
+- Loading the Google Maps script — the widget injects the script using the key you provide.
 - Making API calls to Swift.
 - Session or auth management.
 
-## Build-time configuration
-
-Set `SWIFT_WIDGET_GOOGLE_MAPS_KEY` before building the library so the Maps script loads with the correct key. CI publishes with the production key; local development can use a restricted dev key.
-
 ## Getting a publishable key
 
 Contact Swift at [partners@swiftfood.uk](mailto:partners@swiftfood.uk) with: