@lockerverse/react 0.2.156 → 0.2.158

package/guides/payment-widgets.md

@@ -0,0 +1,704 @@
+# Lockerverse payment-widgets guide
+
+Package: @lockerverse/react@0.2.158
+
+Generated from this release's maintained documentation. Do not edit this copy.
+
+Read [the shared integration guide](integration.md) first.
+
+## Payment widget host integration
+
+## Keep the requested integration mode
+
+Read the shared integration guide first. If the resource prompt specifies
+`integrationMode: "hosted-checkout"`, keep the hosted checkout modal described
+below. Do not silently replace it with native checkout. If an existing site
+already uses native SDK checkout, keep that mode unless a change was requested.
+For a new native integration, use the catalog hook and payment component
+contract later in this guide. Do not add a duplicate checkout page or send the
+visitor away from the existing page.
+
+Use the saved `communitySlug`, `widgetSlug`, `apiBaseUrl`, and `environment` to
+load live catalog data with `useLockerverseWidget` from
+`@lockerverse/react/widget`, or `createLockerverseCheckoutClient` from
+`@lockerverse/sdk/checkout` and its `load()` method. Do not infer active products
+or current prices from an old prompt snapshot. Preserve inactive/unavailable
+states and do not enable payment when the live resource cannot be purchased.
+Use the saved `widgetUrl` for hosted navigation; do not build another
+payment API. Hosted checkout does not need native Stripe peers in the host.
+
+## Match existing controls
+
+Follow any explicit button or section target in the prompt. Otherwise inspect
+nearby product name, price, billing period, and section heading. Reuse a suitable
+button instead of adding another. If several targets remain equally plausible,
+ask one short question before changing the page. Keep the page's product cards,
+cart, quantities, selected tier, and entered amounts. Names, prices, limits,
+recurring cadence, inventory, and shared capacity come from the live catalog.
+
+For separate product buttons, select the matching product. For a cart with one
+pay button, combine only one-time products. Monthly and annual products require
+an exclusive single-product flow; never combine them with each other or a
+one-time cart. Disable checkout when no product is selected or a value violates
+live limits. Local totals are feedback only; Lockerverse decides the final
+payable amount.
+
+## Hosted checkout URLs
+
+Given the configured public widget URL
+`https://host.example/community/widgets/v2/widget/donate`, a product's direct
+URL is the same resource with `/options/{encodedProductSlug}/donate` in place
+of its final `/donate`. Use the live product's `slug` and `encodeURIComponent`.
+Use `URL` and `URLSearchParams`; preserve the supplied widget origin and route.
+
+- For a fixed-price direct product, set `quantity` only when the page collects
+  a quantity. Do not set `amount` or `paymentOption`.
+- For a custom-price direct product, set `amount` to the selected dollar amount.
+- For a combined one-time cart, start from the widget base URL. Set
+  `quantity.{productSlug}` to each selected fixed product's positive integer
+  quantity and `amount.{productSlug}` to each selected custom product's positive
+  dollar amount with at most two decimals. Omit zero or unselected products.
+- Do not pass one aggregate `amount`; the server computes the total.
+- For editable custom-field prefill, use `custom.<fieldId>` with real configured
+  field IDs. Text uses one string, a checkbox uses `true` or `false`, a single
+  choice uses its option ID, and multiple choices repeat the parameter. Do not
+  use `meta.*` for form fields. Keep personal and sensitive data out of URLs.
+
+## Hosted modal
+
+Use the existing site-owned Radix/shadcn Dialog or equivalent accessible modal.
+Provide an accessible title and description, a visible close button, an iframe
+title, and `allow="payment *"` on the iframe. Do not add resize-message logic.
+Make DialogContent a flex column with `gap-0`, `overflow-hidden`, and `p-0`.
+Use a compact header with room for the close control. Its hit area must be at
+least 40 by 40 CSS pixels.
+
+On mobile, use a small gutter: `w-[calc(100vw-1rem)]`,
+`h-[calc(100dvh-1rem)]`, and `max-h-[calc(100dvh-1rem)]`. On desktop, use
+`sm:w-full`, about 720px height, and a maximum width near 640px. The iframe
+wrapper uses `min-h-0 flex-1 overflow-hidden`; the iframe uses
+`h-full w-full border-0`. Only the iframe scrolls. Do not apply viewport-height
+sizing to its wrapper or leave a blank strip below the header. Closing and
+reopening must preserve the host cart. Closing is not payment completion.
+Do not infer paid access from an iframe URL or close event.
+
+## Native SDK checkout
+
+Keep existing product presentation. Use `useLockerverseWidget` for the complete
+live catalog, and store only customer selection in host state. Load
+`LockerversePayment` from `@lockerverse/react/payment` and its CSS when checkout
+is near or visible; pass the full `selection` and `widget` hook result. Use
+`LockerverseDonateLauncher` only when a product picker is needed; a button that
+already selects a product can open that product's checkout directly. Do not
+add an iframe around native SDK checkout or another Stripe Elements wrapper.
+
+Use supported `initialCustomFieldValues` for editable prefill. For explicitly
+requested custom checkout, reuse payment primitives with the Core SDK; the
+host then owns quote, confirmation, validation, and recovery duties. Retain
+recovery in an owner that stays mounted when a custom dialog closes. Read the
+payment outcome and recovery contracts in this guide before implementing
+success or retries.
+
+## Public attendee list and checks
+
+If the prompt includes an event ID and requests a public attendee list, follow
+[Public attendee lists](events.md#public-attendee-lists). Show names only;
+do not show party size, total counts, or private registration data.
+
+Build and inspect desktop and 390 by 844 layouts. Verify the matching button,
+selection, direct or combined URL parameters, modal close target, no header gap,
+and no horizontal overflow. Open checkout to check saved settings, but do not
+submit payment. For native SDK checkout, inspect callback and recovery handling
+without creating live transactions.
+
+## Custom Product UI
+
+Use `useLockerverseWidget` to build custom Product presentation from the live
+Lockerverse catalog. This entry point does not import the payment UI or Stripe.
+
+```tsx
+import {
+  LockerversePayment,
+  preloadLockerversePayment,
+  type LockerversePaymentSelectionItem,
+} from "@lockerverse/react/payment";
+import "@lockerverse/react/payment.css";
+import { useLockerverseWidget } from "@lockerverse/react/widget";
+import { useState } from "react";
+
+const widgetOptions = {
+  communitySlug: "auburn",
+  widgetSlug: "tailgate-party",
+};
+
+export function CustomProductCheckout() {
+  const widget = useLockerverseWidget(widgetOptions);
+  const [selection, setSelection] =
+    useState<LockerversePaymentSelectionItem | null>(null);
+
+  if (widget.loading) {
+    return <p>Loading checkout...</p>;
+  }
+  if (widget.error) {
+    return <button onClick={widget.refresh}>Try again</button>;
+  }
+  if (!widget.catalog) {
+    return null;
+  }
+  if (selection) {
+    return (
+      <LockerversePayment
+        selection={[selection]}
+        widget={widget}
+      />
+    );
+  }
+
+  return widget.catalog.products
+    .filter((product) => product.pricingMode === "fixed")
+    .map((product) => (
+      <button
+        key={product.id}
+        onFocus={() => {
+          void preloadLockerversePayment(widget.catalog);
+        }}
+        onClick={() =>
+          setSelection(
+            product.paymentOption === "one-time"
+              ? { productSlug: product.slug, quantity: 1 }
+              : { productSlug: product.slug }
+          )
+        }
+        onPointerEnter={() => {
+          void preloadLockerversePayment(widget.catalog);
+        }}
+      >
+        {product.name}
+      </button>
+    ));
+}
+```
+
+The hook returns immutable `catalog` data together with `loading`, `error`, and
+`refresh`. The host owns presentation and selection state. Pass the
+selected Product slugs to `LockerversePayment`; Lockerverse remains
+authoritative for availability, pricing, and payment.
+
+Pass the hook result to `LockerversePayment` with `widget={widget}`. The result
+contains the loaded catalog and its client, so the component requests
+only the authoritative quote without repeated configuration. The host can show
+a local catalog total before checkout. The component uses the same local
+estimate to mount the payment form and Stripe immediately, then replaces it
+with the authoritative quote in the background. Payment confirmation still
+requires the current authoritative quote.
+
+This small example shows fixed-price Products. For a custom-price Product, ask
+for the amount in the host UI and pass `amountCents` with `productSlug`.
+
+For a monthly or annual Product, omit quantity. The component shows the
+cadence and configures Stripe Elements for a subscription:
+
+```tsx
+<LockerversePayment
+  selection={[{ productSlug: "monthly-supporter" }]}
+  widget={widget}
+/>
+```
+
+Recurring checkout accepts one fixed Product. It does not accept quantities,
+custom amounts, or multiple Products.
+
+### Live product availability
+
+Use the live `widget.catalog` for names, prices, and limits. Find the requested
+product by its `listingId` or `slug`; do not keep a separate static price list.
+Amounts are integer cents. Format them with `catalog.payment.currency`, not a
+currency field on the product.
+
+Before enabling a new purchase, check the selected product's `minimumQuantity`,
+`maximumQuantity`, and `inventoryQuantity`; nullable limits mean no limit.
+For custom amounts, use `getLockerverseMinimumCustomAmountCents(product)` from
+`@lockerverse/sdk/checkout` to include the SDK minimum and the product minimum.
+Also check:
+
+- The matching `catalog.availability.listings` entry: `status`,
+  `maxPurchasableQuantity`, and `remainingQuantity`.
+- Each `catalog.availability.sharedLimits` entry whose `listingIds` includes
+  the selected product's listing: `status` and `remainingQuantity`. Add the
+  quantities of all selected listings in that shared group before checking its
+  remaining quantity.
+
+A missing listing availability entry means no listing-specific limit was
+reported. Other product and shared limits still apply. These checks help the
+host show an unavailable state; the authoritative quote decides whether the
+selection can be purchased. Show loading, retry, and empty states. Keep an
+unresolved payment available for recovery even if a new purchase is unavailable.
+
+If an existing button already selects one product, open its checkout directly.
+Use the donate launcher when the visitor needs a product picker. For a custom
+dialog, use an accessible title, close button, focus handling, and mobile scroll
+area. Keep recovery state in an owner that remains mounted when the dialog
+closes. Closing a dialog does not complete or cancel a payment.
+
+## Donate launcher
+
+`LockerverseDonateLauncher` turns an existing payment widget into a native
+React dialog. The launcher selects its controls from each Product's existing
+capabilities. Visitors can set quantities for fixed one-time Products and add
+an inline amount for custom one-time Products. The launcher combines these
+one-time choices in one checkout. Monthly and annual Products are exclusive:
+the visitor selects one tier before the same `LockerversePayment` form opens in
+subscription mode.
+
+```tsx
+import { LockerverseDonateLauncher } from "@lockerverse/react/donate-launcher";
+import { useLockerverseWidget } from "@lockerverse/react/widget";
+import "@lockerverse/react/payment.css";
+
+export function Donate() {
+  const widget = useLockerverseWidget({
+    communitySlug: "auburn",
+    widgetSlug: "general-donations",
+  });
+  return (
+    <LockerverseDonateLauncher
+      buttonLabel="Donate"
+      position="bottom-right"
+      widget={widget}
+    />
+  );
+}
+```
+
+Use `position="inline"` to place the launcher in the normal page layout. Use
+`bottom-left` or `bottom-right` for a fixed launcher. Payment callbacks,
+branding, themes, metadata, and recovery properties are the same as
+`LockerversePayment`. API and transport options belong to
+`useLockerverseWidget`.
+
+The launcher starts loading Stripe when the visitor opens it. Catalog-only
+pages do not load Stripe.
+
+## Catalog hook
+
+```tsx
+import { useLockerverseWidget } from "@lockerverse/react/widget";
+```
+
+## Input
+
+```ts
+type CreateLockerverseWidgetOptions = {
+  communitySlug: string;
+  widgetSlug: string;
+  requestTimeoutMs?: number;
+  sentryDsn?: string | null;
+  fetch?: typeof globalThis.fetch;
+  onError?: (error: LockerverseSdkError) => void;
+} & (
+  | { apiBaseUrl: string; environment: "development" | "production" }
+  | { apiBaseUrl?: undefined; environment?: "production" }
+);
+```
+
+## Result
+
+```ts
+type UseLockerverseWidgetResult = {
+  catalog: LockerverseCatalog | null;
+  client: LockerverseCheckoutClient;
+  error: Error | null;
+  loading: boolean;
+  refresh: () => void;
+};
+```
+
+The loaded catalog includes an optional event:
+
+```ts
+type LockerverseEvent = {
+  description: string | null;
+  endAt: string;
+  id: string;
+  location: string | null;
+  name: string;
+  startAt: string;
+  status: "draft" | "active" | "finished" | "cancelled";
+};
+
+type LockerverseCatalog = {
+  event: LockerverseEvent | null;
+  products: LockerverseProduct[];
+  // Community, payment, pricing policy, and widget configuration are also present.
+};
+```
+
+`startAt` and `endAt` are event timestamps. Use `status` to determine the
+event lifecycle state.
+
+## Product interface
+
+```ts
+type LockerverseProduct = {
+  id: string;
+  listingId: string;
+  slug: string;
+  name: string;
+  description: string | null;
+  fulfillmentType: "none" | "event_admission";
+  pricingMode: "fixed" | "custom";
+  paymentOption: "one-time" | "monthly" | "annually";
+  amountCents: number | null;
+  minimumAmountCents: number | null;
+  minimumQuantity: number | null;
+  maximumQuantity: number | null;
+  inventoryQuantity: number | null;
+  acceptsDiscounts: boolean;
+};
+```
+
+An `event_admission` Product is fulfilled by the catalog event.
+
+The hook treats all options as initialization values and keeps one client for
+its mounted lifetime. `refresh()` requests that same widget again. To use a
+different widget, remount the component that owns the hook with a new React
+`key`. Selection and other view state can change without a remount. This entry
+does not import Stripe or payment UI.
+
+## Reuse the loaded catalog
+
+```tsx
+const widget = useLockerverseWidget(options);
+
+<LockerversePayment
+  selection={selection}
+  widget={widget}
+/>
+```
+
+The hook result carries its catalog and client. The host can calculate
+selection totals from the catalog while the payment component uses that client to request the
+current, authoritative quote. The payment form mounts immediately with a local
+estimate. The authoritative quote replaces that estimate in the background
+before payment confirmation.
+
+## Payment component
+
+```tsx
+import { LockerversePayment } from "@lockerverse/react/payment";
+import "@lockerverse/react/payment.css";
+```
+
+## Required properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `widget` | `UseLockerverseWidgetResult` | Result from `useLockerverseWidget` |
+| `selection` | `LockerversePaymentSelectionItem[]` | Products to quote and pay |
+
+## Payment properties
+
+```ts
+type LockerversePaymentProps = {
+  widget: UseLockerverseWidgetResult;
+  selection: LockerversePaymentSelectionItem[];
+  branding?: {
+    accentColor?: string;
+    imageUrl?: string | null;
+    name: string;
+  };
+  metadata?: Record<string, string>;
+  initialCustomFieldValues?: Record<string, boolean | string | string[]>;
+  style?: LockerverseStyle;
+  theme?: "dark" | "light";
+  resumePayment?: {
+    connectedAccountId: string | null;
+    paymentReference: string;
+  } | null;
+  onPaymentComplete?: (payment: LockerversePaymentCompletion) => void;
+  onPaymentRecoveryChange?: (recovery: LockerversePaymentRecovery | null) => void;
+  onPaymentUncertain?: (payment: LockerversePaymentUncertain) => void;
+};
+```
+
+The component also accepts `<section>` properties and `className`. See [Theming](integration.md#styling) for the shared typed CSS tokens.
+
+## Completion
+
+```tsx
+import type { LockerversePaymentCompletion } from "@lockerverse/react/payment";
+
+const widget = useLockerverseWidget({
+  communitySlug: "your-community",
+  widgetSlug: "your-widget",
+});
+
+const handlePaymentComplete = (payment: LockerversePaymentCompletion) => {
+  const admissionItems = payment.lineItems?.filter(
+    (item) => item.fulfillmentType === "event_admission"
+  );
+  console.info("Payment complete; admission item count", admissionItems?.length ?? 0);
+};
+
+<LockerversePayment
+  onPaymentComplete={handlePaymentComplete}
+  selection={selection}
+  widget={widget}
+/>
+```
+
+Use `onPaymentComplete` as the confirmed success signal. A direct completion
+includes the normalized customer `email` and authoritative `lineItems`. A
+completion recovered after reload has `null` for both fields.
+
+## Recovery
+
+Store `onPaymentRecoveryChange` and pass it back through `resumePayment` after reload. Keep `onPaymentUncertain` unresolved.
+
+## Prefill custom fields
+
+Pass configured field IDs to `initialCustomFieldValues`:
+
+```tsx
+<LockerversePayment
+  widget={widget}
+  selection={selection}
+  initialCustomFieldValues={{
+    field_muw2q7vx_sf7r94: "Autographed basketball",
+  }}
+/>
+```
+
+The form reads these values when a checkout form starts. Buyers can edit them;
+parent re-renders and price refreshes do not overwrite their edits. To apply a
+new set of initial values, start a new form with a new React `key`. This also
+resets the other form inputs.
+
+Text and textarea fields take strings. A checkbox takes a boolean. Radio and
+select fields take an option ID. Checkboxes and multi-select fields take arrays
+of option IDs. Unknown fields, wrong value types, and unknown options are
+ignored. Only fields for the selected products are used. Required-field
+validation and server validation still apply.
+
+`LockerverseDonateLauncher` accepts the same property. For live control over
+individual values and a custom submission flow, use the
+[payment primitives](payment-widgets.md) with the Core SDK.
+
+## Payment outcomes
+
+`onPaymentComplete` runs only after Lockerverse reports `success`. A successful payment is terminal, even if the host callback throws.
+
+A direct completion includes the normalized customer `email` and authoritative
+`lineItems`. A completion recovered after reload has `null` for both fields.
+
+If the authoritative total, discount, currency, line items, or connected Stripe account changes, the component displays the new quote before creating a Stripe token. The customer must explicitly submit again.
+
+An authoritative `failed` result is retryable and the next submit receives a new payment reference. `pending`, unresolved `action_required`, and failed same-reference recovery stay locked so the customer cannot accidentally create a second payment. The optional `onPaymentUncertain` callback receives the retained `paymentReference` and one of these reasons:
+
+- `pending`
+- `action_required`
+- `recovery_failed`
+
+To abandon a locked attempt and intentionally start a new checkout, the host must remount `LockerversePayment` with a new React `key` after resolving the payment status through its own workflow.
+
+### Payment recovery
+
+Persist `onPaymentRecoveryChange` synchronously before navigation and pass the
+saved value back through `resumePayment` after a refresh. Do not defer the save
+to an effect. A recovery record has only `paymentReference: string` and
+`connectedAccountId: string | null`; it contains no Stripe secret. Scope its
+storage key to the environment, community, widget, and selection.
+
+This hook reads storage after mount, validates the saved record, and keeps an
+in-memory record if storage is unavailable:
+
+```tsx
+import { useEffect, useState } from "react";
+import type { LockerversePaymentRecovery } from "@lockerverse/react/payment";
+
+function usePaymentRecovery(recoveryKey: string) {
+  const [recovery, setRecovery] = useState<LockerversePaymentRecovery | null>(null);
+  const [loaded, setLoaded] = useState(false);
+
+  useEffect(() => {
+    try {
+      const raw = sessionStorage.getItem(recoveryKey);
+      const saved: unknown = raw ? JSON.parse(raw) : null;
+      if (
+        saved !== null && typeof saved === "object" &&
+        "paymentReference" in saved && typeof saved.paymentReference === "string" &&
+        "connectedAccountId" in saved &&
+        (saved.connectedAccountId === null || typeof saved.connectedAccountId === "string")
+      ) {
+        setRecovery({
+          paymentReference: saved.paymentReference,
+          connectedAccountId: saved.connectedAccountId,
+        });
+      }
+    } catch {
+      // Invalid or unavailable storage must not break checkout.
+    }
+    setLoaded(true);
+  }, [recoveryKey]);
+
+  function saveRecovery(next: LockerversePaymentRecovery | null) {
+    setRecovery(next);
+    try {
+      if (next) sessionStorage.setItem(recoveryKey, JSON.stringify(next));
+      else sessionStorage.removeItem(recoveryKey);
+    } catch {
+      // Keep the in-memory record if storage is unavailable.
+    }
+  }
+
+  return { loaded, recovery, saveRecovery };
+}
+```
+
+Use it in the payment owner, keyed by the recovery key. Render checkout only
+after `loaded` is true:
+
+```tsx
+const { loaded, recovery, saveRecovery } = usePaymentRecovery(recoveryKey);
+
+return loaded ? (
+  <LockerversePayment
+    selection={selection}
+    resumePayment={recovery}
+    onPaymentRecoveryChange={saveRecovery}
+    widget={widget}
+  />
+) : <p>Loading checkout...</p>;
+```
+
+Retain the record on `onPaymentUncertain` and let the component recover the
+same payment. Do not create a replacement charge for an unknown result.
+`onPaymentComplete` confirms success; its `paymentRequired` distinguishes a
+paid purchase from a no-charge order. This browser callback does not grant paid
+access; access checks require server verification. Keep private contact and
+payment data out of URLs, analytics, logs, and public metadata.
+
+Malformed host selections and invalid custom tips render customer-safe validation messages and do not call the Lockerverse API. Product selection remains owned by the host application.
+
+## Payment primitives
+
+Use `LockerversePayment` for the complete checkout. Use these controlled components
+when your website needs its own layout and payment flow. The ready-made checkout
+uses the same fields and `PaymentSummary`; this entry does not import Stripe or
+the ready-made payment controller.
+
+```tsx
+import {
+  buildCustomFieldAnswers,
+  createCustomFieldValues,
+  CustomField,
+  CustomFields,
+  EmailField,
+  getCheckoutCustomFields,
+  PaymentSummary,
+  reconcileCustomFieldValues,
+  validateCustomFields,
+} from "@lockerverse/react/payment-primitives";
+import "@lockerverse/react/payment.css";
+```
+
+See the [live composition example](https://sdk.lockerverse.com/examples/payment-primitives). It loads an
+authoritative quote with the Core SDK and lets a website input and an SDK field
+share the same React state. It previews submission fields and does not charge.
+
+## Controlled custom fields
+
+```tsx
+const fields = getCheckoutCustomFields(catalog, checkout.items);
+const [values, setValues] = useState(() =>
+  createCustomFieldValues(fields, { [itemNameFieldId]: "Autographed basketball" })
+);
+const [errors, setErrors] = useState<Record<string, string>>({});
+
+<CustomFields
+  errors={errors}
+  fields={fields}
+  onChange={setValues}
+  values={values}
+/>
+```
+
+`CustomFields` renders all selected fields. Use `CustomField` for one field at a
+time, so you can put your own UI between them. Pass its `field`, `value`,
+`onChange`, and optional `error`. The caller owns state; a website input can
+change the same state at any time. The components supply labels, control IDs,
+required states, and error associations.
+
+Use field IDs as keys. Text uses strings, a single checkbox uses a boolean,
+single-choice fields use an option ID, and multiple-choice fields use an array
+of option IDs. `createCustomFieldValues` filters initial values against the field
+definitions. Call `reconcileCustomFieldValues(fields, values)` when the selected
+products or field definitions change. This removes fields and options that no
+longer apply. These helpers do not change the input object.
+
+Before submission, call `validateCustomFields`. It returns messages keyed by
+field ID for missing required values. Render those messages and focus the first
+invalid field. Then use `buildCustomFieldAnswers(fields, values)` for the
+Core SDK submission shape. The backend remains the final validation authority.
+
+## Submit through the Core SDK
+
+The UI components do not submit or approve payments. Keep the existing Core SDK
+flow: obtain an authoritative quote for the final selection, email, fees, tip,
+and promo code; show any changed total; configure Stripe for that quote; and
+complete Stripe Elements validation and confirmation-token creation.
+
+At the submission step, add the shared field values to the normal request:
+
+```ts
+const fieldErrors = validateCustomFields(fields, values);
+if (Object.keys(fieldErrors).length > 0) {
+  setErrors(fieldErrors);
+  return;
+}
+
+// finalCheckout comes from client.calculateTotal() for the final pricing inputs.
+// confirmationToken comes from Stripe after Elements validation. Omit it only
+// for a free checkout. Include required phone/shipping fields in contactDetails.
+const result = await client.submitPayment({
+  checkout: finalCheckout,
+  submission: {
+    ...contactDetails,
+    email,
+    confirmationToken,
+    customFieldAnswers: buildCustomFieldAnswers(fields, values),
+  },
+});
+```
+
+This is the submission step, not a complete payment controller. Keep Stripe
+authentication, payment-status recovery, duplicate-submit protection, and
+confirmed completion handling in your host flow. A returned result can need
+more action; do not show success merely because this promise resolves. If an
+error has `recoveryRecommended: true`, call
+`client.getPaymentStatus(finalCheckout.paymentReference)` before allowing a
+new payment attempt.
+
+## Public components and styles
+
+| Export | Purpose |
+| --- | --- |
+| `FormField`, `FieldError` | Label, content wrapper, and associated error message |
+| `TextField`, `EmailField`, `Checkbox` | Standard controlled form inputs |
+| `PhoneInput`, `getInternationalPhone` | Country-aware phone input and normalization before submission |
+| `CustomField`, `CustomFields` | Widget-defined text and choice fields |
+| `PaymentSummary` | The same order summary used by ready-made checkout |
+
+Each component has a named `...Props` type. `CustomFieldValues` and
+`PhoneInputValue` describe the controlled state.
+
+Import `@lockerverse/react/payment.css` and use a `lockerverse-payment` wrapper
+with `data-lockerverse-theme="light"` or `"dark"` to retain the checkout
+appearance. For a custom design, omit that stylesheet and style the components
+in your host. Their labels, input behavior, and error associations remain.
+
+`PaymentSummary` needs only `quote`: `<PaymentSummary quote={checkout} />`.
+Its optional `displayedBaseCents`, `displayedTipCents`, and `displayedTotalCents`
+properties let a host show pending price changes, as the ready-made checkout
+does. They default to the quote's total minus tip, tip, and total. Display
+overrides affect the UI only; they never change the payable amount.