@ticketboothapp/booking 1.2.122 → 1.2.124

package/CHANGE_BOOKING_BE_HANDOFF.md

@@ -4,6 +4,16 @@ This document describes what the **booking API** should return so the website’
 
 Existing endpoint (names may vary in your stack): **`POST …/change/quote`** — response type `ChangeBookingQuoteResponse` in `@ticketboothapp/booking` / shared client types.
 
+## Current Pricing V2 alignment
+
+As of 2026-07-05, the frontend types and visible change-booking preview helpers consume the broader Pricing V2 quote snapshot shape used by the backend:
+
+- `pricingQuote` / `quote` may carry `PricingQuote`-style fields such as `grossSubtotal`, `discountTotal`, `paymentCreditTotal`, `netSubtotalBeforeTax`, `taxAmount`, `payableTotal`, `balanceDelta`, `amountToCharge`, `refundCandidate`, `lines`, `oldReceiptHash`, and `status`.
+- Display helpers prefer server-authored V2 totals and canonical `PricingQuote.lines` when present, then fall back to the existing `newReceipt`, `proposed`, and cent fields.
+- Gift-card credit is treated as `paymentCreditTotal` / payment credit in UI copy, not as a discount total. If a quote reports `paymentCreditTotal` without an explicit credit line, the package adds a display-only payment-credit row.
+- Change-booking amount-due/refund display prefers `balanceDelta`, `amountToCharge`, and `refundCandidate` from the canonical quote before legacy `amountDueCents` / `priceDiff`.
+- Public self-serve and admin/provider change flows clear stale quote totals while changed selections are being re-quoted and use canonical quote charge/refund fields for final payment/free-confirm guards.
+
 ## Already required for “totals confirmed” UI
 
 The frontend treats pricing as confirmed when the quote includes receipt-style totals (via `newReceipt` / `proposed` / `newTotalCents`, etc.) and `amountDueCents` or `priceDiff` for the amount owed. That unlocks subtotal/tax/total rows and replaces the pre-quote placeholder block.
@@ -67,9 +77,10 @@ Pickers show **catalog** prices by default (same booking **currency** as the ori
    - Values: **unit price in major units** (e.g. dollars), display currency.  
    - When present, these update ticket **picker** display units on self‑serve change; totals must still follow **Rule A / Rule B** above unless the quote fully replaces breakdown.
 
-2. **Line items** — `newReceipt.lineItems` or `proposed.lineItems` (fallback `original`)  
-   - Shape: `{ label?, amount?, type?, quantity? }`.  
-   - Mapped to checkout **`PriceSummary`** rows when present; otherwise checkout falls back to FE-built lines after totals confirm.
+2. **Line items** — `pricingQuote.lines` / `quote.lines`, then `newReceipt.lineItems` or `proposed.lineItems` (fallback `original`)
+   - Pricing V2 shape: `{ lineId?, label?, amount?, quantity?, type?, billable?, taxBehavior?, discountBehavior?, source?, metadata? }`.
+   - Legacy receipt shape: `{ label?, amount?, type?, quantity? }`.
+   - Mapped to checkout **`PriceSummary`** rows when present; non-billable Pricing V2 lines are omitted from the primary payable summary. Otherwise checkout falls back to FE-built lines after totals confirm.
 
 ### Additional optional maps
 
@@ -83,7 +94,7 @@ Pickers show **catalog** prices by default (same booking **currency** as the ori
 - **`clientProposedTotal`** (existing): FE still sends this as a hint for reconciliation; display should follow **quote response**, not the client-only cart.  
 - **Currency**: align optional maps and line `amount` values with `currency` / receipt currency; change booking stays in the booking’s sold currency end-to-end on FE.  
 - **Cancellation policy on change**: FE sends the booked policy on reserve/confirm paths; it is **not** chosen from product config during change — preserve the booking’s policy server-side unless product rules say otherwise.  
-- **`serverPreview.completeness`**: the package sets this to **`full`** whenever a preview is built (informational); UI does not gate on `totals_only` vs `full`.
+- **`serverPreview.completeness`**: the package sets this to **`full`** when mapped quote lines are available and **`totals_only`** when only totals are available. UI does not gate progression on this field.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ticketboothapp/booking",
-  "version": "1.2.122",
+  "version": "1.2.124",
   "private": false,
   "sideEffects": [
     "**/*.css",

package/src/components/booking/AdminChangeBookingContent.tsx

@@ -0,0 +1,276 @@
+import type { ComponentProps } from 'react';
+import { AdminChangeCheckoutDialogs } from './AdminChangeCheckoutDialogs';
+import { AdminChangeCheckoutPanel } from './AdminChangeCheckoutPanel';
+import { AdminChangeProductSwitcher } from './AdminChangeProductSwitcher';
+import { ChangeBookingCalendarPanel } from './ChangeBookingCalendarPanel';
+import { ChangeBookingItineraryPanel } from './ChangeBookingItineraryPanel';
+import { ChangeBookingSelectionControlsPanel } from './ChangeBookingSelectionControlsPanel';
+
+type DialogProps = ComponentProps<typeof AdminChangeCheckoutDialogs>;
+type ProductSwitcherProps = ComponentProps<typeof AdminChangeProductSwitcher>;
+type CalendarProps = Omit<ComponentProps<typeof ChangeBookingCalendarPanel>, 'children'>;
+type ItineraryProps = ComponentProps<typeof ChangeBookingItineraryPanel>;
+type SelectionControlsProps = ComponentProps<typeof ChangeBookingSelectionControlsPanel>;
+type CheckoutPanelProps = ComponentProps<typeof AdminChangeCheckoutPanel>;
+type BuildAdminChangeBookingContentPropsParams =
+  DialogProps &
+  Omit<ProductSwitcherProps, 'error'> &
+  CalendarProps &
+  ItineraryProps &
+  SelectionControlsProps &
+  Omit<CheckoutPanelProps, 'error'> & {
+    isPartialLaunch: boolean;
+    checkoutVisible: boolean;
+    productSwitcherError?: ProductSwitcherProps['error'];
+    checkoutError: CheckoutPanelProps['error'];
+  };
+
+function pickProps<T extends object, K extends keyof T>(source: T, keys: readonly K[]): Pick<T, K> {
+  return keys.reduce((picked, key) => {
+    picked[key] = source[key];
+    return picked;
+  }, {} as Pick<T, K>);
+}
+
+const dialogPropKeys = [
+  'showAdminPaymentChoice',
+  'adminChoiceData',
+  'checkoutModalData',
+  'showCheckoutModal',
+  'checkoutClientSecret',
+  'currency',
+  'locale',
+  'loading',
+  'error',
+  'onPayNow',
+  'onConfirmWithoutPayment',
+  'onAdminPaymentChoiceCancel',
+  'onCheckoutClose',
+  'onPaymentSubmitStart',
+  'onPaymentSubmitError',
+  'getSuccessUrl',
+  't',
+] as const;
+
+const productSwitcherPropKeys = [
+  'visible',
+  'products',
+  'selectedProductId',
+  'disabled',
+  'onProductChange',
+] as const;
+
+const calendarPropKeys = [
+  'visibleAvailabilityCount',
+  'loadingAvailabilities',
+  'isFetchingMoreAvailabilities',
+  'availabilitiesByDate',
+  'selectedDate',
+  'onSelectedDateChange',
+  'onDateSelect',
+  'suppressCalendarDateScroll',
+  'contentRef',
+  'useWindowScroll',
+  'timezone',
+  'earliestDate',
+  'onVisibleRangeChange',
+  'currency',
+  'showCapacity',
+  'extraDiscountPercent',
+  'selectableSoldOutDate',
+  'capDiscountBadgesToBookingDate',
+  'partySizeRequiredForCalendarSelection',
+  'getEffectiveVacancies',
+  't',
+] as const;
+
+const itineraryPropKeys = [
+  'selectedDate',
+  'hideItineraryBox',
+  'activeOptions',
+  'destinationsCount',
+  'selectedAvailability',
+  'selectedReturnOption',
+  'pickupLocationId',
+  'pickupLocationSkipped',
+  'pickupLocationsCount',
+  'quantities',
+  'email',
+  'firstName',
+  'lastName',
+  'getItineraryItems',
+  'isItinerarySticky',
+  'stickyTopPx',
+  'isMobile',
+  'useWindowScroll',
+  'showTooltip',
+  'selectedPickupLocation',
+  'itineraryRef',
+  't',
+  'onTooltipToggle',
+  'onTooltipShow',
+] as const;
+
+const selectionControlsPropKeys = [
+  'selectedDate',
+  'selectedAvailability',
+  'pickupTimes',
+  'optionsMap',
+  'hasAnyMostPopular',
+  'isAdmin',
+  'pickupLocationSkipped',
+  't',
+  'onTimeSelect',
+  'returnOptions',
+  'selectedReturnOption',
+  'selectedReturnOptionForDisplay',
+  'onSelectedReturnOptionChange',
+  'getStaySummary',
+  'pricing',
+  'quantities',
+  'totalQuantity',
+  'selectedVacancies',
+  'companyTimezone',
+  'pickupVacancies',
+  'returnVacancies',
+  'currency',
+  'locale',
+  'isSimplifiedPricingView',
+  'onQuantityChange',
+  'minimumQuantities',
+  'applyReceiptPaidFloors',
+  'ticketUnitFloorByCategory',
+  'addOns',
+  'addOnSelections',
+  'onAddOnSelectionsChange',
+  'minimumTotalByAddOnId',
+] as const;
+
+const checkoutPanelPropKeys = [
+  'priceSummaryLines',
+  'replacePriceSummary',
+  'changeFlowAmountDue',
+  'receiptSubtotal',
+  'receiptTax',
+  'receiptTotal',
+  'originalReceipt',
+  'priceSummaryLinesIncludeTaxRow',
+  'isTaxIncludedInPrice',
+  'taxRate',
+  'currency',
+  'locale',
+  't',
+  'showProviderPricingInlineEditor',
+  'providerPricingUi',
+  'providerQuotedLines',
+  'debugPanel',
+  'showChangeFlowManualPriceLines',
+  'showAdminCustomLineEditor',
+  'adminCustomReceiptLines',
+  'onAddAdminCustomReceiptLine',
+  'onUpdateAdminCustomReceiptLine',
+  'onRemoveAdminCustomReceiptLine',
+  'firstName',
+  'lastName',
+  'email',
+  'onFirstNameChange',
+  'onLastNameChange',
+  'onEmailChange',
+  'onClearError',
+  'selectedDate',
+  'pickupLocations',
+  'destinations',
+  'pickupLocationId',
+  'pickupLocationSkipped',
+  'selectedPickupLocation',
+  'highlightedPickupLocationIds',
+  'onPickupLocationIdChange',
+  'onPickupLocationSkippedChange',
+  'termsAccepted',
+  'onTermsAcceptedChange',
+  'onTermsAcceptedAtChange',
+  'isAdmin',
+  'skipConfirmationCommunications',
+  'disableAutoCommunications',
+  'onSkipConfirmationChange',
+  'onDisableCommunicationsChange',
+  'loading',
+  'totalQuantity',
+  'onCheckout',
+  'submitLabel',
+  'showCheckoutModal',
+  'showAdminPaymentChoice',
+  'hasEffectiveChangeSelection',
+  'isChangeQuoteBlocked',
+  'submitDisabled',
+  'attributionSummary',
+  'attributionConfirmLabel',
+  'attributionConfirmed',
+  'onAttributionConfirmedChange',
+  'lineAmountInputs',
+  'onLineAmountInputChange',
+  'onLineAmountInputBlur',
+  'onLineAmountReset',
+  'lineLabelInputs',
+] as const;
+
+export interface AdminChangeBookingContentProps {
+  dialogsProps: DialogProps;
+  isPartialLaunch: boolean;
+  productSwitcherProps: ProductSwitcherProps;
+  calendarProps: CalendarProps;
+  itineraryProps: ItineraryProps;
+  selectionControlsProps: SelectionControlsProps;
+  checkoutVisible: boolean;
+  checkoutPanelProps: CheckoutPanelProps;
+}
+
+export function buildAdminChangeBookingContentProps(
+  params: BuildAdminChangeBookingContentPropsParams,
+): AdminChangeBookingContentProps {
+  return {
+    dialogsProps: pickProps(params, dialogPropKeys) as DialogProps,
+    isPartialLaunch: params.isPartialLaunch,
+    productSwitcherProps: {
+      ...pickProps(params, productSwitcherPropKeys),
+      error: params.productSwitcherError,
+    } as ProductSwitcherProps,
+    calendarProps: pickProps(params, calendarPropKeys) as CalendarProps,
+    itineraryProps: pickProps(params, itineraryPropKeys) as ItineraryProps,
+    selectionControlsProps: pickProps(params, selectionControlsPropKeys) as SelectionControlsProps,
+    checkoutVisible: params.checkoutVisible,
+    checkoutPanelProps: {
+      ...pickProps(params, checkoutPanelPropKeys),
+      error: params.checkoutError,
+    } as CheckoutPanelProps,
+  };
+}
+
+export function AdminChangeBookingContent({
+  dialogsProps,
+  isPartialLaunch,
+  productSwitcherProps,
+  calendarProps,
+  itineraryProps,
+  selectionControlsProps,
+  checkoutVisible,
+  checkoutPanelProps,
+}: AdminChangeBookingContentProps) {
+  return (
+    <div className="booking-flow-root space-y-8">
+      <AdminChangeCheckoutDialogs {...dialogsProps} />
+      {isPartialLaunch ? null : (
+        <div className="booking-calendar-section">
+          <AdminChangeProductSwitcher {...productSwitcherProps} />
+          <ChangeBookingCalendarPanel {...calendarProps}>
+            <div className="mt-6 space-y-6">
+              <ChangeBookingItineraryPanel {...itineraryProps} />
+              <ChangeBookingSelectionControlsPanel {...selectionControlsProps} />
+              {checkoutVisible ? <AdminChangeCheckoutPanel {...checkoutPanelProps} /> : null}
+            </div>
+          </ChangeBookingCalendarPanel>
+        </div>
+      )}
+    </div>
+  );
+}