@afosto/checkout-ui 0.0.15 → 0.0.16

package/README.md

@@ -1 +1,333 @@
-# Afosto checkout-ui
+# @afosto/checkout-ui
+
+React components and state for building a checkout on the Afosto storefront API. The package contains a complete checkout with information, shipping, payment and review steps. Render it as a whole with `<Checkout />`, or compose your own checkout from the separate layout, form, sections, fields and hooks.
+
+## Installation
+
+```bash
+pnpm add @afosto/checkout-ui @afosto/storefront @emotion/react @emotion/styled
+```
+
+Peer dependencies are `react` and `react-dom` 18, `@emotion/react` and `@emotion/styled`. The package ships ES modules only. The components and providers are marked `'use client'`, so in Next.js you render them from a client component.
+
+## Quick start
+
+A checkout needs three things:
+
+1. A storefront client from `@afosto/storefront`, created with the storefront token of your channel.
+2. The id of the cart the customer is checking out.
+3. A `CheckoutProvider` that loads the cart, with a `Checkout` inside that renders it.
+
+```tsx
+'use client';
+
+import { createStorefrontClient } from '@afosto/storefront';
+import { Checkout, CheckoutProvider } from '@afosto/checkout-ui';
+
+const storefront = createStorefrontClient({
+  storefrontToken: '<your storefront token>',
+});
+
+if (typeof window !== 'undefined') {
+  window.dataLayer = window.dataLayer || [];
+}
+
+export const CheckoutPage = ({ cartId }: { cartId: string }) => (
+  <CheckoutProvider storefront={storefront} cartId={cartId}>
+    <Checkout />
+  </CheckoutProvider>
+);
+```
+
+The `dataLayer` line is only needed if you want analytics events. See [Analytics](#analytics).
+
+This renders the full checkout: a top bar with the logo, a stepper, the step forms, the order summary, sign-in for customers with an account and a message when the cart doesn't exist. Logo, colours, currency, locale and links come from the channel. You don't have to configure anything else for a working checkout.
+
+## Cart flow and order flow
+
+`CheckoutProvider` takes either a `cartId` or an `orderId`, never both. Passing both throws an error.
+
+- With `cartId` the provider runs the cart flow (`flow: 'cart'`). The customer fills in the steps and the last step confirms the cart, which turns it into an order.
+- With `orderId` the provider runs the order flow (`flow: 'order'`). It runs the same steps against an existing order, for example an order that still needs a payment.
+
+```tsx
+<CheckoutProvider storefront={storefront} orderId={orderId}>
+  <Checkout />
+</CheckoutProvider>
+```
+
+After the last step the package redirects the browser. For a `pin` payment method it goes to `{channelLinks.checkout}/payment/execute?order_id=...`. Otherwise it follows the first proceeding option the API returns, usually the payment provider's page.
+
+If `cartId` or `orderId` is empty, the checkout shows the not-found message.
+
+## What the provider does
+
+`CheckoutProvider` sets up everything the components need:
+
+1. It fetches the channel through `storefront.getChannel()`. The channel supplies the locale, currency, logo, store name, branding colours, links (terms, privacy, my account) and the B2B/B2C and required-field options.
+2. It merges those channel values with the `settings` prop. A value in `settings` always wins over the channel.
+3. It wraps the tree in a MUI theme from `@afosto/components`, with the primary palette built from the channel's primary colour.
+4. It creates a React Query client, unless you pass your own through `queryClient`.
+5. It loads the cart or order and exposes all state and actions through the `useCheckout()` hook.
+
+### Provider props
+
+| Prop | Description |
+| --- | --- |
+| `storefront` | Required. A client from `createStorefrontClient()` in `@afosto/storefront`. |
+| `cartId` / `orderId` | Required, pick one. Decides the flow. |
+| `settings` | Overrides the channel settings. See [Settings](#settings). |
+| `translations` | Text overrides per component. See [Translations](#translations). |
+| `locale` | Overrides the channel locale. Falls back to `en`. |
+| `theme` | Partial MUI theme, deep-merged over the Afosto theme. |
+| `steps` | Replaces the default steps. See [Steps](#steps). |
+| `operations` | Overrides or extends the API calls. See [Operations](#operations). |
+| `analytics` | Overrides or extends the analytics events. See [Analytics](#analytics). |
+| `createSummary` | Replaces the function that turns a cart or order into the summary data. |
+| `expressPaymentMethodsComponentMapping` | Maps express payment method codes to button components. PayPal Express is built in. |
+| `isLoading` | Delays fetching the channel and the cart until it is `false`. Use it while you are still resolving the cart id or token. |
+| `queryClient` | Your own React Query client. |
+
+### Settings
+
+Commonly used fields of `settings` (type `CheckoutSettings`):
+
+- `emailOptIn`: show the newsletter opt-in.
+- `salutation`, `isSalutationRequired`: show and require the salutation field.
+- `isPhoneNumberRequired`, `isCocNumberRequired`, `isVatNumberRequired`, `isSharedOrganisationRequired`: required fields. Default to the channel options.
+- `isB2bExcluded`, `isB2cExcluded`: hide the business or consumer option. Default to the channel options.
+- `isAccountEnabled`: show sign-in. Defaults to `true` when the channel has a my account link.
+- `disableCouponModifications`: hide adding and removing coupons.
+- `disableAnalytics`: stop all analytics events.
+- `links`, `logo`, `storeName`, `currency`, `branding`: override what the channel returns.
+
+```tsx
+<CheckoutProvider
+  storefront={storefront}
+  cartId={cartId}
+  settings={{
+    emailOptIn: true,
+    salutation: true,
+    isPhoneNumberRequired: true,
+    links: { termsConditions: 'https://example.com/terms' },
+  }}
+>
+```
+
+## Steps
+
+The package exports four default steps:
+
+| Key | Export | Contents |
+| --- | --- | --- |
+| `information` | `informationStep` | Sign in, account selection, contact details, business details, shipping and billing address. |
+| `shipping` | `shippingStep` | Shipping method and pickup point. |
+| `payment` | `paymentStep` | Payment method, issuer, terminal and agreement (down payment, post paid). |
+| `review` | `reviewStep` | Overview, comment and confirm. |
+
+A step is a plain object of type `CheckoutStep`:
+
+- `key`, `label`: identifier and stepper label.
+- `component`: the React component rendered for the step.
+- `defaultValues`: the starting form values, or a function that returns them.
+- `initialize(data, responseData, context)`: builds the form values from the loaded cart or order.
+- `validationSchema(context)`: a `yup` schema for the step's values.
+- `isComplete(values, context)`: decides whether the customer can skip past this step. On load the checkout opens on the first step that is not complete.
+- `submit(values, formData, context)`: runs when the customer clicks next. This is where the step sends its data to the API.
+- `onEvent` (optional): reacts to events such as `signedIn`, `accountSelected` and `clearSession`.
+- `reviewTargets`, `getSubStepForReviewTarget` (optional): let the review step link back to a field in this step.
+
+To change the flow, pass your own array. You can reuse the defaults:
+
+```tsx
+import { informationStep, shippingStep, paymentStep, reviewStep } from '@afosto/checkout-ui';
+
+<CheckoutProvider
+  storefront={storefront}
+  cartId={cartId}
+  steps={[informationStep, { ...shippingStep, label: 'Delivery' }, paymentStep, reviewStep]}
+>
+```
+
+An empty array falls back to the defaults.
+
+## Operations
+
+Every API call goes through an operation. An operation has four functions:
+
+```ts
+{
+  queryFn: (params, context) => Promise<Response>; // calls the API
+  formatter: (response, context) => FormattedResponse; // reshapes the response
+  success: (data, context) => void; // updates checkout state, tracks analytics
+  error: (error) => void;
+}
+```
+
+The package exports the defaults as `cartOperations`, `orderOperations` (same keys, for the order flow) and `authOperations`. Examples of keys are `initial`, `addCustomer`, `addInformation`, `addShippingMethod`, `addPaymentMethod`, `addCoupon`, `checkout`, `signIn` and `signUp`.
+
+The `operations` prop merges per operation and per function. You only pass what you want to change. The other functions keep their default:
+
+```tsx
+<CheckoutProvider
+  storefront={storefront}
+  cartId={cartId}
+  operations={{
+    addCustomer: {
+      error: (error) => reportError(error),
+    },
+  }}
+>
+```
+
+The `context` argument holds the storefront client, settings, the current flow, `defaultOperations` (so you can call the original from your override), `setSummary`, `track` and the rest of the checkout state.
+
+Keys that don't exist yet are added as custom operations. The package does not call them by itself. You can read them from `useCheckout().operations` in your own components.
+
+## Analytics
+
+The package pushes GA4 ecommerce events to `window.dataLayer`. Events only fire when `window.dataLayer` exists, so create it before the checkout renders:
+
+```ts
+window.dataLayer = window.dataLayer || [];
+```
+
+Default events:
+
+| Key | dataLayer event |
+| --- | --- |
+| `beginCheckout` | `begin_checkout` |
+| `checkoutStep` | `checkout_step` |
+| `addShippingInfo` | `add_shipping_info` |
+| `addPaymentInfo` | `add_payment_info` |
+| `signIn` | `login` |
+| `signUp` | `sign_up` |
+
+Each event has an optional `formatter(eventData, context)` and a `send(formattedData, rawData, context)`. The `analytics` prop merges per event, like operations. Use it to change the payload or to send events somewhere else.
+
+`stepSubmitted` fires after every step submit, but has no default `send`. Add one if you need it:
+
+```tsx
+analytics={{
+  stepSubmitted: {
+    send: (eventData, rawData, context) => {
+      window.dataLayer?.push({ event: 'step_submitted', step: rawData.step.key });
+    },
+  },
+}}
+```
+
+Set `settings.disableAnalytics` to turn off all events.
+
+## Translations
+
+Every component has English default texts. The `translations` prop on the provider overrides them per component. The keys are listed in the `CheckoutTranslations` type, for example `summary`, `addressFields`, `shippingMethodsField`, `paymentMethodSection` and `validation`.
+
+```tsx
+translations={{
+  summary: { title: 'Overzicht', subtotal: 'Subtotaal' },
+  validation: { required: 'Dit veld is verplicht' },
+}}
+```
+
+The package only ships English. For another language, pass all texts through `translations`.
+
+## Customising the UI
+
+### Slots
+
+`Checkout`, `CheckoutLayout` and most larger components accept `slots` and `slotProps`. A slot replaces a part with your own component. `slotProps` passes extra props to that part. `slotProps` can also be a function that gets the owner state (for example `{ flow, notFound }`) and returns props.
+
+```tsx
+<Checkout
+  slots={{ notFoundFeedback: MyNotFoundPage }}
+  slotProps={{
+    layout: { hideTopBar: true },
+    summary: { hideTitle: true },
+  }}
+/>
+```
+
+### Theme
+
+Pass `theme` to override the MUI theme. The primary palette comes from `settings.branding.colors.primary` (or the channel branding) and is overridden by `theme.palette.primary`.
+
+```tsx
+<CheckoutProvider
+  storefront={storefront}
+  cartId={cartId}
+  theme={{ palette: { primary: { main: '#0b5cff' } } }}
+>
+```
+
+### Composing your own checkout
+
+Every part of `<Checkout />` is exported. Inside a `CheckoutProvider` you can put them together yourself:
+
+```tsx
+import {
+  CheckoutForm,
+  CheckoutLayout,
+  CheckoutProvider,
+  CheckoutSignIn,
+  useCheckout,
+} from '@afosto/checkout-ui';
+
+const MyCheckout = () => {
+  const { showSignIn } = useCheckout();
+
+  return (
+    <CheckoutLayout>
+      <MyIntroText />
+      <CheckoutForm hideForm={showSignIn} />
+      {showSignIn && <CheckoutSignIn />}
+    </CheckoutLayout>
+  );
+};
+
+export const CheckoutPage = ({ cartId }: { cartId: string }) => (
+  <CheckoutProvider storefront={storefront} cartId={cartId}>
+    <MyCheckout />
+  </CheckoutProvider>
+);
+```
+
+What each part does:
+
+- `CheckoutLayout` renders the top bar and a container with the steps on the left and the summary on the right. The top bar holds the logo, the stepper and, on mobile, the summary drawer. With `hideTopBar` those disappear too.
+- `CheckoutForm` renders the active step, the next and back buttons and error messages, and submits the step.
+- `CheckoutSignIn`, `CheckoutForgotPassword` and `CheckoutAccountSelection` are the screens around signing in. `<Checkout />` shows them based on `showSignIn`, `showForgotPassword` and `showAccountSelection` from `useCheckout()`. If you compose your own checkout, render them yourself.
+- `CheckoutSummary`, `CheckoutStepper` and `CheckoutTopBar` can also be placed on their own.
+- Below the steps sit the sections (`CheckoutShippingAddressSection`, `CheckoutPaymentMethodSection`, ...) and fields (`CheckoutShippingMethodsField`, `CheckoutPaymentMethodsField`, ...). Use these to build your own step components.
+
+`useCheckout()` gives access to the full state, including `flow`, `summary`, `activeStep`, `steps`, `settings`, `translations`, `isLoading`, `notFound`, the actions (`addCoupon`, `addShippingMethod`, `checkout`, ...) and `track`.
+
+The package also exports its GraphQL `queries`, `mutations` and `fragments`, the `hooks`, `utils`, `constants` and the payment method, issuer and carrier `icons`. Besides the root import you can import a single folder, for example `@afosto/checkout-ui/steps`.
+
+## Development
+
+```bash
+npx nx build @afosto/checkout-ui
+npx nx lint @afosto/checkout-ui
+```
+
+The build turns every `.ts` file under `src` into its own entry point. Add new components to `src/index.ts` to export them from the root.
+
+### Project layout
+
+```
+src/
+  Checkout*/        one folder per component, each with an index.ts
+  CheckoutProvider/ provider, theme provider and query client provider
+  steps/            default step definitions
+  operations/       default API operations for cart, order and auth
+  queries/          GraphQL queries
+  mutations/        GraphQL mutations
+  fragments/        GraphQL fragments
+  hooks/            state hooks behind the providers
+  constants/        analytics events, icon mappings, address field config
+  icons/            payment method, issuer and carrier icons
+  utils/            formatting and helper functions
+  types.ts          shared types
+  index.ts          public exports
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afosto/checkout-ui",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "Afosto react checkout ui components",
   "author": "Afosto",
   "license": "MIT",