tf-checkout-react 2.0.0-beta.26 → 2.0.0-beta.28

package/README.md

@@ -7,17 +7,23 @@ components, plus the shared API and React Query hooks. Which paths a buyer can
 actually use depend on the event, the deployed API, the buyer's session and the
 payment provider.
 
-This reference describes **2.0.0-beta.26**. It is a prerelease with a different
+This reference describes **2.0.0-beta.28**. It is a prerelease with a different
 API from 1.x. Pin the version while evaluating it. npm's `latest` and `beta`
 tags can move independently and an unqualified install may select 1.x:
 
 ```bash
 npm view tf-checkout-react dist-tags
-npm install tf-checkout-react@2.0.0-beta.26 @tanstack/react-query react react-dom
+npm install tf-checkout-react@2.0.0-beta.28 @tanstack/react-query react react-dom
 ```
 
-The [API reference](https://unpkg.com/tf-checkout-react@2.0.0-beta.26/docs/API.md)
-is included as `docs/API.md` in this package.
+The [API reference](https://unpkg.com/tf-checkout-react@2.0.0-beta.28/docs/API.html)
+is included as `docs/API.md` and `docs/API.html` in this package. A
+[standalone guide](https://unpkg.com/tf-checkout-react@2.0.0-beta.28/docs/GUIDE.html)
+is also available.
+
+If the HTML has not reached the CDN yet, open the packaged `docs/API.md` in a
+Markdown viewer or read the [plain-text API Markdown](https://cdn.jsdelivr.net/npm/tf-checkout-react@2.0.0-beta.28/docs/API.md).
+The full guide is also shown on this npm page.
 
 ## Choose a checkout layout
 
@@ -35,6 +41,26 @@ version. The 1.x `*Container` components and named single-page/accordion
 examples are not drop-in 2.x exports. The [migration guide](#migrating-from-1x)
 shows how to reproduce those layouts with the current components.
 
+### Coming from a 1.x layout?
+
+The 1.x guide showed ways to arrange individual containers; those examples were
+not named, ready-made 2.x components. Choose the closest 2.x starting point:
+
+| 1.x integration | What to use in beta.28 | What your application owns |
+| --- | --- | --- |
+| Separate ticket, billing, payment and confirmation pages | [Step-by-step composition](#step-by-step-checkout) | Routes or step visibility, Back/Edit, and preserving one active checkout provider. |
+| A single page using the container components | [`EmbeddedCheckout`](#embeddedcheckout) for the stock flow, or [single-page composition](#single-page-checkout) to arrange the sections yourself | With composition, the page layout and navigation; with either approach, order-status reconciliation. |
+| The progressive enhancement example | [Step-by-step composition](#step-by-step-checkout) | The visible steps and the rules for moving between them. |
+| The accordion/collapsible example | [Accordion composition](#accordion-checkout) | Disclosure behavior and checkout navigation. |
+| A flow that already reserved a cart | [`ResumedCheckout`](#resume-a-server-cart) | Creating the cart in the same session and the order-status handoff. |
+
+The composition examples are starting points, not complete replacements for a
+multi-route checkout. In particular, implement Back/Edit, cart expiry and
+payment recovery before production. See [Compose sections](#compose-sections)
+for the full responsibilities. The 1.x props and callback payloads do not map
+automatically; [Migrating layout callbacks](#migrating-layout-callbacks) gives
+specific examples.
+
 [Requirements](#requirements) · [Quick start](#quick-start) ·
 [Configure sessions](#configuration-and-sessions) · [Ready-made checkout](#embeddedcheckout) ·
 [Custom layouts](#compose-sections) · [Payments](#payments) ·
@@ -677,7 +703,7 @@ error or closed provider page means the charge failed. A custom provider page mu
 settle with `{ event: 'dismiss' }` on close/unmount, and other custom payment
 ports must settle, or a waiting reset cannot finish.
 
-The beta.26 declaration comments for `reset` and `PAID_ORDER_PENDING_MESSAGE`
+The beta.28 declaration comments for `reset` and `PAID_ORDER_PENDING_MESSAGE`
 say pressing Pay again finishes an unconfirmed order; the `resetWhenSettled`
 comment also omits retired checkouts as a reason for `false`. Those comments do
 not establish that a retry is safe. Use the session and reconciliation guidance
@@ -734,7 +760,7 @@ holder's answers in `ticketDataCapture`, and add-on answers via
 the opaque catalog ID. Use backend country/state IDs for `countryId` and
 `stateId`; `countryCode` / `stateCode` are payment billing codes.
 
-In beta.26 conditional custom-field requiredness is left to the backend and
+In beta.28 conditional custom-field requiredness is left to the backend and
 not all hosted-checkout conditional visibility is reproduced. Verify the
 actual event against the deployed checkout, including blanks, images, holder
 scoping and validation errors; do not claim parity from the presence of a
@@ -755,7 +781,7 @@ unknown; `reloadCheckoutDetails()` can also retry the waiver read. A retained
 order with a possible payment follows separate recovery and needs reconciliation.
 `WaiverSigning` handles the SDK's signing flow.
 
-**Consent limitation in beta.26:** when `privacyPolicy` is supplied, the
+**Consent limitation in beta.28:** when `privacyPolicy` is supplied, the
 stock `BillingInfo` replaces the Ticket Fairy marketing checkbox with the
 required privacy checkbox, but both use `consent.ttfOptIn`; the order sends
 that value as `ttf_opt_in`. The privacy acknowledgement and Ticket Fairy
@@ -1008,6 +1034,52 @@ a full account user. Supply a host sign-in/route callback where applicable.
 | `PostReaction` | `postId: string \| number`, `onSignIn?`. `PostReactionControls` accepts `flow` and `onSignIn?`. |
 | `DiscoveryTravel` | `searchCities`, `searchEvents`, `storage?`, `locale?`. Host supplies search functions; see `DiscoveryTravelProps` for their signatures. |
 
+#### Example: ready-made account screens
+
+The following setup is for an authorized **first-party** full-account
+integration with the corresponding deployed account routes. In that host's initial
+[SDK configuration](#configuration-and-sessions), set `accountAuth: true` and
+`cookieAuth: true`, then complete the approved full-account sign-in and any
+required proof challenges before mounting them. The checkout-only quick start
+uses a sign-in path scoped to the event, which is not sufficient. Add the options
+to the one-time setup; do not reconfigure from this screen.
+
+The flags do not grant account access or enable backend routes. Third-party
+integrations need an explicitly approved, supported account journey; contact
+Ticket Fairy to find out whether one is available. The example assumes the
+existing `QueryClientProvider` is mounted and the backend supports these screens.
+The host supplies navigation callbacks. `ProfileSettings` and
+`NotificationPreferences` receive `signIn`; `AccountRewardsSection` has no
+sign-in callback and only displays a message while signed out. The host must
+detect session expiry and offer sign-in separately for rewards.
+
+```tsx
+import {
+  AccountRewardsSection, NotificationPreferences, ProfileSettings,
+} from 'tf-checkout-react'
+
+export function AccountScreen({ screen, goBack, signIn, browseEvents, viewTickets }: {
+  screen: 'visibility' | 'notifications' | 'rewards'
+  goBack: () => void
+  signIn: () => void
+  browseEvents: () => void
+  viewTickets: () => void
+}) {
+  if (screen === 'visibility') return (
+    <ProfileSettings mode="visibility" onBack={goBack} onSignIn={signIn} />
+  )
+  if (screen === 'notifications') return (
+    <NotificationPreferences onBack={goBack} onSignIn={signIn} />
+  )
+  return <AccountRewardsSection onBrowseEvents={browseEvents} onViewTickets={viewTickets} />
+}
+```
+
+Use `mode="links"` for profile links. These components do not replace an orders
+list or establish account authorization. Scope or clear account queries when the
+buyer signs out or changes, and handle loading, sign-in and navigation in the
+host as needed.
+
 For account orders and ticket lists use `hooks.useOrders`, `hooks.useOrder`,
 `ttf.orders.list`, `ttf.orders.get` or `ttf.orders.myTickets`. In this version
 `ttf.orders.get` / `useOrder` take a **numeric order ID string**, not a public
@@ -1242,7 +1314,7 @@ existing 1.x integration pinned until the new flow and backend are verified.
 There is no automatic translation of old URLs, component props, account
 sessions or persisted 1.x state.
 
-| 1.x integration | 2.0.0-beta.26 approach |
+| 1.x integration | 2.0.0-beta.28 approach |
 | --- | --- |
 | `setConfigs({ BASE_URL, ... })` | `configureCheckout({ env` or `baseUrl`, `clientId`, `clientSecret: ''`, ... `})`; public client registration and session setup are required. |
 | `TicketsContainer`, `SeatMapContainer`, `AddOnsContainer` | `EmbeddedCheckout` or `Tickets`, `SeatMap`, `AddOns` under `CheckoutProvider`. Adapt callbacks and navigation. |