@swift-food-services/catering-widget 0.1.0-beta.1

package/README.md

@@ -0,0 +1,227 @@
+# @swift-food-services/catering-widget
+
+The Swift Food catering flow, embeddable in any React app. Restaurant browsing, multi-session order building, contact details, and submission — one component, one CSS file, one publishable key.
+
+```bash
+npm install @swift-food-services/catering-widget
+```
+
+## Quick start
+
+```tsx
+import { CateringWidget } from "@swift-food-services/catering-widget";
+import "@swift-food-services/catering-widget/dist/styles.css";
+
+export default function CateringPage() {
+  return (
+    <CateringWidget
+      publishableKey="pk_live_..."
+      onOrderComplete={({ orderId }) => {
+        window.location.href = `/thanks?order=${orderId}`;
+      }}
+    />
+  );
+}
+```
+
+Defaults: Swift-hosted backend, `localStorage` persistence, neutral theme.
+
+## Requirements
+
+- React 18+ and React-DOM 18+ as peer dependencies
+- A publishable key from Swift (see [Getting a publishable key](#getting-a-publishable-key))
+- At least one origin registered with Swift where the widget will load
+
+## Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `publishableKey` | `string` | yes | Your `pk_live_...` or `pk_test_...` key from Swift. |
+| `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. |
+| `onError` | `(error: WidgetError) => void` | no | Fires on unrecoverable errors (bad key, network, submit failure). |
+
+## Examples
+
+### Next.js with router-based navigation
+
+```tsx
+"use client";
+import { CateringWidget } from "@swift-food-services/catering-widget";
+import "@swift-food-services/catering-widget/dist/styles.css";
+import { useRouter } from "next/navigation";
+
+export default function Page() {
+  const router = useRouter();
+  return (
+    <CateringWidget
+      publishableKey={process.env.NEXT_PUBLIC_SWIFT_KEY!}
+      onOrderComplete={({ orderId, accessToken }) => {
+        router.push(`/orders/${orderId}?token=${accessToken}`);
+      }}
+    />
+  );
+}
+```
+
+### Theming
+
+```tsx
+<CateringWidget
+  publishableKey="pk_live_..."
+  theme={{
+    primary: "#0a7ea4",
+    radius: "12px",
+    font: "\"IBM Plex Mono\", monospace",
+  }}
+/>
+```
+
+### Pre-filling known event details
+
+```tsx
+<CateringWidget
+  publishableKey="pk_live_..."
+  initialData={{
+    eventName: "Alice's Birthday",
+    eventDate: "2026-07-12",
+    eventTime: "19:00",
+    guestCount: 40,
+    deliveryAddress: {
+      line1: "1 Example Lane",
+      city: "London",
+      postcode: "E1 6AN",
+    },
+    contact: { name: "Alice", email: "alice@example.com" },
+  }}
+  onOrderComplete={/* ... */}
+/>
+```
+
+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.
+
+### 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:
+
+```tsx
+<CateringWidget
+  publishableKey="pk_live_..."
+  stickyTopOffset={64}
+/>
+```
+
+Pass a live value if your navbar resizes (measure it with a ref + `ResizeObserver` and pass the current height). The prop is read on every render, so updates take effect immediately.
+
+## Types
+
+```ts
+import {
+  CateringWidget,
+  type CateringWidgetProps,
+  type Theme,
+  type InitialData,
+  type OrderCompleteResult,
+  type OrderSummary,
+  type MealSession,
+  type MealSessionItem,
+  type WidgetError,
+} from "@swift-food-services/catering-widget";
+```
+
+See the generated `dist/index.d.ts` for the full shapes — your IDE picks them up automatically.
+
+## Callbacks
+
+### `onOrderComplete(result)`
+
+Fires when an order has been successfully submitted. `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.
+
+### `onError(error)`
+
+Fires on errors the widget can't recover from. `error.code` is one of:
+
+- `invalid_publishable_key` — the key was rejected by Swift's backend.
+- `session_failed` — the widget session handshake failed.
+- `network_error` — a backend request failed or returned a non-2xx.
+- `submit_failed` — the order submission itself failed.
+- `unknown` — anything else; see `error.cause` for details.
+
+## What the widget handles for you
+
+- Restaurant browsing and menu exploration
+- Multi-session meal building
+- Contact details and delivery address
+- Promo codes and pricing preview
+- Google Maps address autocomplete
+- Order submission to Swift's API
+- State persistence in `localStorage` (namespaced)
+
+## What you're responsible for
+
+- Getting a publishable key from Swift.
+- Registering your site's origin(s) with Swift.
+- Rendering `<CateringWidget>` wherever you want the flow to live.
+- Navigating after `onOrderComplete`.
+- Page chrome around the widget.
+
+## 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.
+- 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:
+
+1. Your company name.
+2. The origin(s) where the widget will be embedded.
+3. A technical contact for integration support.
+
+Swift provisions a partner record and returns a publishable key (format: `pk_live_...` or `pk_test_...`) out of band.
+
+The key is public (it ships in the browser bundle). Swift's backend validates the key against the request's origin, so a stolen key cannot be used from a non-allowlisted domain.
+
+## Troubleshooting
+
+**Widget doesn't render / screen is blank**
+Check that you've imported the stylesheet: `import "@swift-food-services/catering-widget/dist/styles.css";`.
+
+**Errors mentioning `invalid_publishable_key` or `session_failed`**
+Either the key is wrong, the key is inactive, or your current origin isn't in the allowlist.
+
+**Widget works on `localhost` but not in production**
+Your production origin isn't registered. Ask Swift to add it.
+
+**TypeScript errors importing types**
+Ensure your `tsconfig.json` has `"moduleResolution": "bundler"` or `"node16"`/`"nodenext"`.
+
+## Browser support
+
+Modern evergreen browsers (Chrome, Firefox, Safari, Edge) on desktop and mobile.
+
+## Versioning
+
+`@swift-food-services/catering-widget` follows [semver](https://semver.org/). The public API is everything exported from the package entry — `CateringWidget`, its props, and the re-exported types.
+
+## Support
+
+- Integration questions: [partners@swiftfood.uk](mailto:partners@swiftfood.uk)
+- Bug reports: include your publishable key prefix (first 8 chars), the browser, and a reproducible example.
+
+## License
+
+Proprietary. Distributed for use by authorized Swift Food partners only.