@ticketboothapp/booking 1.2.123 → 1.2.125

package/src/components/booking/useChangeBookingCheckoutController.ts

@@ -0,0 +1,461 @@
+import { useCallback, useEffect, useRef, useState, type Dispatch, type SetStateAction } from 'react';
+import {
+  cancelReservation,
+  cancelReservationBestEffort,
+  confirmFreeChangeBooking,
+  createChangeBookingPaymentIntent,
+  describeStandardTourCapacityConflictMessage,
+  isInsufficientCapacityReserveError,
+  reportReserveCapacityConflictClientContext,
+  type Availability,
+  type PricingConfig,
+  type Product,
+  type ReturnOption,
+} from '../../lib/booking-api';
+import type { OrderSummary } from '../../lib/booking/pricing';
+import { BOOKING_FLOW_ABANDON_EVENT } from '../../providers/booking-dialog-provider';
+import type { ChangeBookingFlowProps } from './booking-flow-types';
+import { quoteCustomerChangeForCheckout } from './change-booking-checkout-quote-runner';
+import {
+  buildChangeBookingPaidCheckoutModalData,
+  type ChangeBookingPaidCheckoutModalData,
+} from './change-booking-payment-modal-builders';
+import type { ChangeBookingMergedQuoteState } from './change-booking-quote-state';
+import {
+  findMergedAvailabilityForSelection,
+  findMergedReturnVacancies,
+  getAvailabilityOptionId,
+} from './change-booking-flow-helpers';
+import type { CheckoutModalLineItem } from './CheckoutModal';
+import type { Currency } from './CurrencySwitcher';
+
+type BookingItem = { category: string; count: number };
+type AddOnSelection = { addOnId: string; variantId?: string; quantity?: number };
+
+export interface UseChangeBookingCheckoutControllerParams {
+  selectedAvailability: Availability | null;
+  selectedReturnOption: ReturnOption | null;
+  setSelectedAvailability: Dispatch<SetStateAction<Availability | null>>;
+  setSelectedReturnOption: Dispatch<SetStateAction<ReturnOption | null>>;
+  product: Product;
+  quantities: Record<string, number>;
+  totalQuantity: number;
+  missingRequiredReturnSelection: boolean;
+  isPublicSelectableAvailability: (availability: Availability, now?: Date) => boolean;
+  email: string;
+  firstName: string;
+  lastName: string;
+  pickupLocationId: string | null;
+  pickupLocationSkipped: boolean;
+  hidePickupSkipOption: boolean;
+  t: (key: string) => string;
+  currency: Currency;
+  originalReceipt: ChangeBookingFlowProps['originalReceipt'];
+  initialValues: ChangeBookingFlowProps['initialValues'];
+  addOnSelections: AddOnSelection[];
+  latestChangeQuote: ChangeBookingMergedQuoteState | null;
+  setLatestChangeQuote: Dispatch<SetStateAction<ChangeBookingMergedQuoteState | null>>;
+  changeFlowNewBookingTotal: number;
+  effectiveSubtotal: number;
+  effectiveTax: number;
+  onSuccess?: ChangeBookingFlowProps['onSuccess'];
+  totalPrice: number;
+  checkoutModalTicketLinesDisplay: CheckoutModalLineItem[];
+  feeLineItemsWithAddOns: OrderSummary['feeLineItems'];
+  checkoutReturnLineAmount: number;
+  cancellationPolicyFee: number;
+  effectiveCancellationPolicyLabel: string;
+  isTaxIncludedInPrice: boolean;
+  effectivePromoDiscountAmount: number;
+  tax: number;
+  appliedPromoCode: string | null;
+  pricingConfig: PricingConfig | null;
+  reloadAvailabilitiesAfterReserveConflict: () => Promise<Availability[]>;
+  selectedDate: string;
+  setLoading: (loading: boolean) => void;
+  setError: (error: string) => void;
+}
+
+export interface UseChangeBookingCheckoutControllerResult {
+  showCheckoutModal: boolean;
+  checkoutClientSecret: string;
+  checkoutModalData: ChangeBookingPaidCheckoutModalData | null;
+  cancelPendingReservation: () => void;
+  handleCheckout: () => Promise<void>;
+  handlePaymentSubmitStart: () => void;
+  handlePaymentSubmitError: () => void;
+}
+
+function bookingItemsFromQuantities(quantities: Record<string, number>): BookingItem[] {
+  return Object.entries(quantities)
+    .filter(([, count]) => count > 0)
+    .map(([category, count]) => ({ category, count }));
+}
+
+function updatePendingChangeBookingSession({
+  totalPrice,
+  currency,
+  selectedAvailability,
+}: {
+  totalPrice: number;
+  currency: Currency;
+  selectedAvailability: Availability;
+}): void {
+  try {
+    const storedBooking = sessionStorage.getItem('pendingBooking');
+    if (!storedBooking) return;
+    const booking = JSON.parse(storedBooking);
+    booking.totalPrice = totalPrice;
+    booking.currency = currency || selectedAvailability.currency || 'CAD';
+    sessionStorage.setItem('pendingBooking', JSON.stringify(booking));
+  } catch (e) {
+    console.warn('Failed to update booking data', e);
+  }
+}
+
+export function useChangeBookingCheckoutController({
+  selectedAvailability,
+  selectedReturnOption,
+  setSelectedAvailability,
+  setSelectedReturnOption,
+  product,
+  quantities,
+  totalQuantity,
+  missingRequiredReturnSelection,
+  isPublicSelectableAvailability,
+  email,
+  firstName,
+  lastName,
+  pickupLocationId,
+  pickupLocationSkipped,
+  hidePickupSkipOption,
+  t,
+  currency,
+  originalReceipt,
+  initialValues,
+  addOnSelections,
+  latestChangeQuote,
+  setLatestChangeQuote,
+  changeFlowNewBookingTotal,
+  effectiveSubtotal,
+  effectiveTax,
+  onSuccess,
+  totalPrice,
+  checkoutModalTicketLinesDisplay,
+  feeLineItemsWithAddOns,
+  checkoutReturnLineAmount,
+  cancellationPolicyFee,
+  effectiveCancellationPolicyLabel,
+  isTaxIncludedInPrice,
+  effectivePromoDiscountAmount,
+  tax,
+  appliedPromoCode,
+  pricingConfig,
+  reloadAvailabilitiesAfterReserveConflict,
+  selectedDate,
+  setLoading,
+  setError,
+}: UseChangeBookingCheckoutControllerParams): UseChangeBookingCheckoutControllerResult {
+  const [showCheckoutModal, setShowCheckoutModal] = useState(false);
+  const [checkoutClientSecret, setCheckoutClientSecret] = useState('');
+  const [checkoutModalData, setCheckoutModalData] = useState<ChangeBookingPaidCheckoutModalData | null>(null);
+  const pendingReservationRef = useRef<{ reservationReference: string } | null>(null);
+  const paymentSubmitInFlightRef = useRef(false);
+
+  const cancelPendingReservation = useCallback(() => {
+    if (paymentSubmitInFlightRef.current) return;
+    const pending = pendingReservationRef.current;
+    if (pending) {
+      pendingReservationRef.current = null;
+      cancelReservation(pending.reservationReference).catch(() => {});
+    }
+    setShowCheckoutModal(false);
+    setCheckoutModalData(null);
+    setCheckoutClientSecret('');
+  }, []);
+
+  const cancelPendingReservationBestEffort = useCallback(() => {
+    if (paymentSubmitInFlightRef.current) return;
+    const pending = pendingReservationRef.current;
+    if (pending) {
+      pendingReservationRef.current = null;
+      cancelReservationBestEffort(pending.reservationReference);
+    }
+    setShowCheckoutModal(false);
+    setCheckoutModalData(null);
+    setCheckoutClientSecret('');
+  }, []);
+
+  useEffect(() => {
+    const handleAbandon = () => {
+      cancelPendingReservation();
+    };
+    window.addEventListener(BOOKING_FLOW_ABANDON_EVENT, handleAbandon);
+    return () => window.removeEventListener(BOOKING_FLOW_ABANDON_EVENT, handleAbandon);
+  }, [cancelPendingReservation]);
+
+  useEffect(() => {
+    const handlePageHide = () => {
+      cancelPendingReservationBestEffort();
+    };
+    window.addEventListener('pagehide', handlePageHide);
+    return () => window.removeEventListener('pagehide', handlePageHide);
+  }, [cancelPendingReservationBestEffort]);
+
+  const handleCheckout = useCallback(async () => {
+    if (!selectedAvailability || totalQuantity === 0) {
+      setError(t('booking.selectTimeAndTickets'));
+      return;
+    }
+    if (!isPublicSelectableAvailability(selectedAvailability, new Date())) {
+      setSelectedAvailability(null);
+      setSelectedReturnOption(null);
+      setError('This departure is no longer available online because it starts too soon. Please choose a later time.');
+      return;
+    }
+    if (missingRequiredReturnSelection) {
+      setError('Removing return option in self-serve is not available. Please contact support.');
+      return;
+    }
+
+    if (!email) {
+      setError(t('booking.enterEmail') || 'Please enter your email address');
+      return;
+    }
+
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      setError(t('booking.invalidEmail') || 'Please enter a valid email address');
+      return;
+    }
+
+    if (!firstName?.trim()) {
+      setError(t('booking.enterFirstName') || 'Please enter your first name');
+      return;
+    }
+
+    if (!lastName?.trim()) {
+      setError(t('booking.enterLastName') || 'Please enter your last name');
+      return;
+    }
+
+    if (
+      product.pickupLocations &&
+      product.pickupLocations.length > 0 &&
+      !pickupLocationId &&
+      (!pickupLocationSkipped || hidePickupSkipOption)
+    ) {
+      setError(t('booking.selectPickupLocation'));
+      return;
+    }
+
+    setLoading(true);
+    setError('');
+    paymentSubmitInFlightRef.current = false;
+
+    try {
+      const bookingItems = bookingItemsFromQuantities(quantities);
+      const availabilityProductOptionId = getAvailabilityOptionId(selectedAvailability);
+
+      if (!availabilityProductOptionId) {
+        setError('No product option selected');
+        setLoading(false);
+        return;
+      }
+
+      const quoteResult = await quoteCustomerChangeForCheckout({
+        bookingReference: initialValues?.bookingReference,
+        lastName,
+        availabilityProductOptionId,
+        dateTime: selectedAvailability.dateTime,
+        availabilityId: selectedAvailability.availabilityId || null,
+        pickupLocationId: pickupLocationId || null,
+        returnAvailabilityId: selectedReturnOption?.returnAvailabilityId ?? null,
+        bookingItems,
+        addOnSelections,
+        clientProposedTotal: latestChangeQuote?.serverDisplay?.total ?? changeFlowNewBookingTotal,
+        fallbackCart: {
+          total: changeFlowNewBookingTotal,
+          subtotal: effectiveSubtotal,
+          tax: effectiveTax,
+        },
+        currency,
+        originalReceiptTotal: originalReceipt?.total ?? 0,
+      });
+      setLatestChangeQuote(quoteResult.mergedQuote);
+      if (quoteResult.decision.kind === 'free') {
+        const freeConfirm = await confirmFreeChangeBooking(quoteResult.decision.changeIntentId);
+        if (freeConfirm.status && freeConfirm.status !== 'APPLIED') {
+          throw new Error('We could not apply this booking change yet. Please try again.');
+        }
+        onSuccess?.({ reservationReference: quoteResult.bookingReference });
+        setLoading(false);
+        return;
+      }
+
+      pendingReservationRef.current = null;
+      updatePendingChangeBookingSession({
+        totalPrice,
+        currency,
+        selectedAvailability,
+      });
+
+      const datePart = selectedAvailability.dateTime.split('T')[0];
+      const amountDueForCheckout = quoteResult.decision.amountDueForCheckout;
+      const paymentIntent = await createChangeBookingPaymentIntent(
+        quoteResult.decision.changeIntentId
+      );
+
+      setCheckoutClientSecret(paymentIntent.clientSecret ?? '');
+      setCheckoutModalData(
+        buildChangeBookingPaidCheckoutModalData({
+          bookingReference: quoteResult.bookingReference,
+          lastName,
+          datePart,
+          ticketLines: checkoutModalTicketLinesDisplay,
+          feeLineItems: feeLineItemsWithAddOns,
+          returnPriceAdjustment: checkoutReturnLineAmount,
+          cancellationPolicyFee,
+          cancellationPolicyLabel: effectiveCancellationPolicyLabel,
+          subtotal: effectiveSubtotal,
+          tax: effectivePromoDiscountAmount > 0 ? effectiveTax : tax,
+          total: amountDueForCheckout,
+          totalQuantity,
+          isTaxIncludedInPrice,
+          taxRate: pricingConfig?.taxRate ?? 0,
+          promoDiscountAmount: effectivePromoDiscountAmount > 0 ? effectivePromoDiscountAmount : 0,
+          discountLabel: appliedPromoCode ? `Promo: ${appliedPromoCode}` : (originalReceipt?.promoLabel || undefined),
+          previousTotal: originalReceipt?.total,
+          newTotal: originalReceipt
+            ? quoteResult.confirmedNewTotalForCheckout
+            : undefined,
+          successUrl: {
+            enabled: true,
+            bookingReference: quoteResult.bookingReference,
+            lastName,
+            datePart,
+            changeIntentId: quoteResult.decision.changeIntentId,
+          },
+        })
+      );
+      setShowCheckoutModal(true);
+      setLoading(false);
+    } catch (err) {
+      if (isInsufficientCapacityReserveError(err)) {
+        try {
+          const merged = await reloadAvailabilitiesAfterReserveConflict();
+          const outbound = findMergedAvailabilityForSelection(merged, selectedAvailability);
+          const outboundVacancies = outbound?.vacancies ?? null;
+          const returnVacancies = findMergedReturnVacancies(outbound, selectedReturnOption);
+          setError(
+            describeStandardTourCapacityConflictMessage({
+              partySize: totalQuantity,
+              outboundVacancies,
+              returnVacancies,
+              hasReturnSelection: !!selectedReturnOption,
+            })
+          );
+          reportReserveCapacityConflictClientContext({
+            flow: 'standard_tour',
+            productId: product.productId,
+            selectedDate: selectedDate || null,
+            outboundDateTime: selectedAvailability?.dateTime ?? null,
+            outboundVacanciesAfterRefresh: outboundVacancies,
+            returnVacanciesAfterRefresh: returnVacancies,
+            partySizeOrPassengers: totalQuantity,
+            hasReturnSelection: !!selectedReturnOption,
+            returnAvailabilityId: selectedReturnOption?.returnAvailabilityId ?? null,
+            reloadAvailabilitiesSucceeded: true,
+          });
+        } catch (reloadErr) {
+          setError(
+            describeStandardTourCapacityConflictMessage({
+              partySize: totalQuantity,
+              outboundVacancies: null,
+              returnVacancies: null,
+              hasReturnSelection: !!selectedReturnOption,
+            })
+          );
+          reportReserveCapacityConflictClientContext({
+            flow: 'standard_tour',
+            productId: product.productId,
+            selectedDate: selectedDate || null,
+            outboundDateTime: selectedAvailability?.dateTime ?? null,
+            outboundVacanciesAfterRefresh: null,
+            returnVacanciesAfterRefresh: null,
+            partySizeOrPassengers: totalQuantity,
+            hasReturnSelection: !!selectedReturnOption,
+            returnAvailabilityId: selectedReturnOption?.returnAvailabilityId ?? null,
+            reloadAvailabilitiesSucceeded: false,
+            reloadErrorMessage:
+              reloadErr instanceof Error ? reloadErr.message : String(reloadErr),
+          });
+        }
+        setLoading(false);
+        return;
+      }
+      setError(err instanceof Error ? err.message : 'Something went wrong');
+      setLoading(false);
+    }
+  }, [
+    selectedAvailability,
+    totalQuantity,
+    setError,
+    t,
+    isPublicSelectableAvailability,
+    setSelectedAvailability,
+    setSelectedReturnOption,
+    missingRequiredReturnSelection,
+    email,
+    firstName,
+    lastName,
+    product.pickupLocations,
+    product.productId,
+    pickupLocationId,
+    pickupLocationSkipped,
+    hidePickupSkipOption,
+    setLoading,
+    quantities,
+    initialValues?.bookingReference,
+    addOnSelections,
+    latestChangeQuote?.serverDisplay?.total,
+    changeFlowNewBookingTotal,
+    effectiveSubtotal,
+    effectiveTax,
+    currency,
+    originalReceipt,
+    setLatestChangeQuote,
+    onSuccess,
+    totalPrice,
+    checkoutModalTicketLinesDisplay,
+    feeLineItemsWithAddOns,
+    checkoutReturnLineAmount,
+    cancellationPolicyFee,
+    effectiveCancellationPolicyLabel,
+    effectivePromoDiscountAmount,
+    tax,
+    isTaxIncludedInPrice,
+    pricingConfig?.taxRate,
+    appliedPromoCode,
+    reloadAvailabilitiesAfterReserveConflict,
+    selectedReturnOption,
+    selectedDate,
+  ]);
+
+  const handlePaymentSubmitStart = useCallback(() => {
+    paymentSubmitInFlightRef.current = true;
+  }, []);
+
+  const handlePaymentSubmitError = useCallback(() => {
+    paymentSubmitInFlightRef.current = false;
+  }, []);
+
+  return {
+    showCheckoutModal,
+    checkoutClientSecret,
+    checkoutModalData,
+    cancelPendingReservation,
+    handleCheckout,
+    handlePaymentSubmitStart,
+    handlePaymentSubmitError,
+  };
+}

package/src/components/booking/useChangeBookingInitialHydration.ts

@@ -0,0 +1,204 @@
+'use client';
+
+import { useEffect, useRef, type Dispatch, type SetStateAction } from 'react';
+import { formatInTimeZone } from 'date-fns-tz';
+import type { AddOn, Availability, PrecomputedPricesByCategory } from '../../lib/booking-api';
+import type { Currency } from './CurrencySwitcher';
+import type { ChangeBookingFlowProps } from './booking-flow-types';
+import {
+  deriveAddOnSelectionsFromReceiptLines,
+  normalizeAddOnSelections,
+  parseAvailabilityDateTime,
+  resolveInitialAvailabilityFromBooking,
+  type AddOnSelection,
+} from './change-booking-flow-helpers';
+
+export interface UseChangeBookingInitialHydrationOptions {
+  initialValues?: ChangeBookingFlowProps['initialValues'];
+  lockedPromoCode: string | null;
+  appliedPromoCode: string | null;
+  promoCodeInput: string;
+  selectedAvailability: Availability | null;
+  selectedDate: string;
+  timesForSelectedDate: Availability[];
+  companyTimezone: string;
+  changeFlowResolvedInitialProductOptionId: string | null;
+  precomputedPricesByOption: Record<string, PrecomputedPricesByCategory> | null | undefined;
+  currency: Currency;
+  originalReceiptSubtotal?: number | null;
+  originalReceiptLineItems?: NonNullable<ChangeBookingFlowProps['originalReceipt']>['lineItems'];
+  addOns: AddOn[];
+  addOnSelections: AddOnSelection[];
+  setEmail: Dispatch<SetStateAction<string>>;
+  setFirstName: Dispatch<SetStateAction<string>>;
+  setLastName: Dispatch<SetStateAction<string>>;
+  setPickupLocationId: Dispatch<SetStateAction<string | null>>;
+  setPickupLocationSkipped: Dispatch<SetStateAction<boolean>>;
+  setPromoCodeInput: Dispatch<SetStateAction<string>>;
+  setAppliedPromoCode: Dispatch<SetStateAction<string | null>>;
+  setSelectedDate: (date: string) => void;
+  setSelectedAvailability: Dispatch<SetStateAction<Availability | null>>;
+  setQuantities: Dispatch<SetStateAction<Record<string, number>>>;
+  setAddOnSelections: Dispatch<SetStateAction<AddOnSelection[]>>;
+  setError: Dispatch<SetStateAction<string>>;
+}
+
+export function useChangeBookingInitialHydration({
+  initialValues,
+  lockedPromoCode,
+  appliedPromoCode,
+  promoCodeInput,
+  selectedAvailability,
+  selectedDate,
+  timesForSelectedDate,
+  companyTimezone,
+  changeFlowResolvedInitialProductOptionId,
+  precomputedPricesByOption,
+  currency,
+  originalReceiptSubtotal,
+  originalReceiptLineItems,
+  addOns,
+  addOnSelections,
+  setEmail,
+  setFirstName,
+  setLastName,
+  setPickupLocationId,
+  setPickupLocationSkipped,
+  setPromoCodeInput,
+  setAppliedPromoCode,
+  setSelectedDate,
+  setSelectedAvailability,
+  setQuantities,
+  setAddOnSelections,
+  setError,
+}: UseChangeBookingInitialHydrationOptions) {
+  const hasAppliedInitialValuesRef = useRef(false);
+  const hasAppliedInitialQuantitiesRef = useRef(false);
+  const hasHydratedAddOnsFromReceiptRef = useRef(false);
+
+  useEffect(() => {
+    if (hasAppliedInitialValuesRef.current || !initialValues) return;
+    const trimmedEmail = initialValues.customer?.email?.trim();
+    const trimmedFirstName = initialValues.customer?.firstName?.trim();
+    const trimmedLastName = initialValues.customer?.lastName?.trim();
+    const trimmedPromo = initialValues.promoCode?.trim().toUpperCase();
+    if (trimmedEmail) setEmail(trimmedEmail);
+    if (trimmedFirstName) setFirstName(trimmedFirstName);
+    if (trimmedLastName) setLastName(trimmedLastName);
+    if (initialValues.pickupLocationId?.trim()) {
+      setPickupLocationId(initialValues.pickupLocationId.trim());
+      setPickupLocationSkipped(false);
+    }
+    if (trimmedPromo) {
+      setPromoCodeInput(trimmedPromo);
+      setAppliedPromoCode(trimmedPromo);
+    }
+    hasAppliedInitialValuesRef.current = true;
+  }, [
+    initialValues,
+    setAppliedPromoCode,
+    setEmail,
+    setFirstName,
+    setLastName,
+    setPickupLocationId,
+    setPickupLocationSkipped,
+    setPromoCodeInput,
+  ]);
+
+  useEffect(() => {
+    if (!lockedPromoCode) return;
+    if (appliedPromoCode !== lockedPromoCode) setAppliedPromoCode(lockedPromoCode);
+    if (promoCodeInput !== lockedPromoCode) setPromoCodeInput(lockedPromoCode);
+  }, [lockedPromoCode, appliedPromoCode, promoCodeInput, setAppliedPromoCode, setPromoCodeInput]);
+
+  useEffect(() => {
+    if (!initialValues?.dateTime || selectedAvailability) return;
+    const target = parseAvailabilityDateTime(initialValues.dateTime);
+    const targetDate = formatInTimeZone(target, companyTimezone, 'yyyy-MM-dd');
+    if (!selectedDate) {
+      setSelectedDate(targetDate);
+      return;
+    }
+    if (selectedDate !== targetDate || timesForSelectedDate.length === 0) return;
+    const { selection, defer } = resolveInitialAvailabilityFromBooking(
+      timesForSelectedDate,
+      target,
+      companyTimezone,
+      initialValues.availabilityId ?? null,
+      changeFlowResolvedInitialProductOptionId ?? initialValues.productOptionId ?? null,
+      initialValues.bookingItems ?? null,
+      precomputedPricesByOption,
+      currency,
+      originalReceiptSubtotal ?? undefined,
+    );
+    if (defer) return;
+    if (selection) {
+      setSelectedAvailability(selection);
+      setError('');
+    }
+  }, [
+    initialValues?.dateTime,
+    initialValues?.availabilityId,
+    initialValues?.productOptionId,
+    initialValues?.bookingItems,
+    changeFlowResolvedInitialProductOptionId,
+    selectedAvailability,
+    selectedDate,
+    timesForSelectedDate,
+    companyTimezone,
+    precomputedPricesByOption,
+    currency,
+    originalReceiptSubtotal,
+    setSelectedDate,
+    setSelectedAvailability,
+    setError,
+  ]);
+
+  useEffect(() => {
+    if (
+      hasAppliedInitialQuantitiesRef.current ||
+      !initialValues?.bookingItems ||
+      initialValues.bookingItems.length === 0 ||
+      !selectedAvailability
+    ) {
+      return;
+    }
+    const next: Record<string, number> = {};
+    for (const item of initialValues.bookingItems) {
+      const key = item.category?.trim();
+      if (!key) continue;
+      next[key] = Math.max(0, Number(item.count) || 0);
+    }
+    if (Object.keys(next).length > 0) {
+      setQuantities((prev) => ({ ...prev, ...next }));
+      hasAppliedInitialQuantitiesRef.current = true;
+    }
+  }, [initialValues, selectedAvailability, setQuantities]);
+
+  useEffect(() => {
+    if (!initialValues?.addOnSelections?.length) return;
+    setAddOnSelections((prev) =>
+      prev.length > 0 ? prev : normalizeAddOnSelections(initialValues.addOnSelections!),
+    );
+  }, [initialValues?.addOnSelections, setAddOnSelections]);
+
+  useEffect(() => {
+    if (hasHydratedAddOnsFromReceiptRef.current) return;
+    if ((initialValues?.addOnSelections?.length ?? 0) > 0) return;
+    if (addOnSelections.length > 0) return;
+    if (addOns.length === 0) return;
+    const receiptLines = originalReceiptLineItems ?? [];
+    if (receiptLines.length === 0) return;
+    const derived = deriveAddOnSelectionsFromReceiptLines(addOns, receiptLines);
+    hasHydratedAddOnsFromReceiptRef.current = true;
+    if (derived.length > 0) {
+      setAddOnSelections(normalizeAddOnSelections(derived));
+    }
+  }, [
+    initialValues?.addOnSelections,
+    addOnSelections.length,
+    addOns,
+    originalReceiptLineItems,
+    setAddOnSelections,
+  ]);
+}