@ticketboothapp/booking 1.2.123 → 1.2.124

package/src/components/booking/useAdminChangeQuoteDisplayState.tsx

@@ -0,0 +1,437 @@
+import { useMemo } from 'react';
+import type { Availability, PricingConfig, ReturnOption } from '../../lib/booking-api';
+import {
+  resolveChangeFlowDisplayedAmounts,
+  roundMoney,
+} from '../../lib/booking/change-flow-pricing';
+import {
+  computePricingDriftDelta,
+  mergeLineComparisonsWithFullDrift,
+  mergePriceSummaryLinesForDrift,
+  sumPriceSummaryLinesMajorUnits,
+} from '../../lib/booking/change-booking-pricing-drift';
+import { mapQuoteLineItemsToPriceSummaryLines } from '../../lib/booking/change-booking-server-preview';
+import type { ChangeBookingFlowProps } from './booking-flow-types';
+import type { Currency } from './CurrencySwitcher';
+import type { PriceSummaryLine } from './PriceSummary';
+import type {
+  ProviderDashboardChangePricingUi,
+  ProviderDashboardPricingLine,
+} from './booking-flow-ui';
+import type { PricingRate } from './change-booking-flow-helpers';
+import { ChangeBookingPricingDriftPanel } from './ChangeBookingPricingDriftPanel';
+import { buildChangeBookingQuoteStatusPlaceholder } from './ChangeBookingQuoteStatusPlaceholder';
+import { useAdminProviderPricingAdjustments } from './useAdminProviderPricingAdjustments';
+import type { AdminCustomReceiptLine } from './useAdminCustomReceiptLines';
+import type { AdminChangeLatestQuote } from './useAdminChangeCheckoutController';
+import { useChangeBookingSelectionDetails } from './useChangeBookingSelectionDetails';
+
+type AddOnSelection = { addOnId: string; variantId?: string; quantity?: number };
+type TicketLineForDisplay = { category?: string | null; qty: number; itemTotal: number };
+
+export interface UseAdminChangeQuoteDisplayStateParams {
+  suppressSelfServeCurrencyUi: boolean;
+  latestChangeQuote: AdminChangeLatestQuote | null;
+  selectedAvailability: Availability | null;
+  selectedReturnOption: ReturnOption | null;
+  totalQuantity: number;
+  checkoutPriceSummaryLines: PriceSummaryLine[];
+  changeFlowNewBookingTotal: number;
+  currency: Currency;
+  locale: 'en' | 'fr';
+  ticketLineItemsForChangeFlowDisplay: TicketLineForDisplay[];
+  pricingForTicketSelector: PricingRate[];
+  isTaxIncludedInPrice: boolean;
+  effectiveTax: number;
+  effectivePromoDiscountAmount: number;
+  appliedPromoCode: string | null;
+  originalReceipt: ChangeBookingFlowProps['originalReceipt'];
+  t: (key: string) => string;
+  selfServePricingConfirmed: boolean;
+  changeQuoteLoading: boolean;
+  changeQuoteFetchError: string | null;
+  initialValues: ChangeBookingFlowProps['initialValues'];
+  implicitReturnBaselineId: string | null;
+  pickupLocationId: string | null;
+  quantities: Record<string, number>;
+  addOnSelections: AddOnSelection[];
+  initialAddOnMinQtyByKey: Map<string, number>;
+  changeFlowResolvedInitialProductOptionId: string | null;
+  selectedParentProductChanged: boolean;
+  isProviderDashboardChange: boolean;
+  showProviderPricingInlineEditor: boolean;
+  providerPricingUi?: ProviderDashboardChangePricingUi;
+  providerQuotedLines: ProviderDashboardPricingLine[];
+  editableSummaryPreSubtotalDelta: number;
+  adminCustomAdjustmentTotal: number;
+  adminCustomReceiptLines: AdminCustomReceiptLine[];
+  isManualOverrideEligibleLine: (line: ProviderDashboardPricingLine) => boolean;
+  isAdmin: boolean;
+  useAdminFeAuthoritativeQuote: boolean;
+  isCustomerSelfServeChange: boolean;
+  effectiveSubtotalForCheckout: number;
+  pricingConfig: PricingConfig | null;
+}
+
+export function useAdminChangeQuoteDisplayState({
+  suppressSelfServeCurrencyUi,
+  latestChangeQuote,
+  selectedAvailability,
+  selectedReturnOption,
+  totalQuantity,
+  checkoutPriceSummaryLines,
+  changeFlowNewBookingTotal,
+  currency,
+  locale,
+  ticketLineItemsForChangeFlowDisplay,
+  pricingForTicketSelector,
+  isTaxIncludedInPrice,
+  effectiveTax,
+  effectivePromoDiscountAmount,
+  appliedPromoCode,
+  originalReceipt,
+  t,
+  selfServePricingConfirmed,
+  changeQuoteLoading,
+  changeQuoteFetchError,
+  initialValues,
+  implicitReturnBaselineId,
+  pickupLocationId,
+  quantities,
+  addOnSelections,
+  initialAddOnMinQtyByKey,
+  changeFlowResolvedInitialProductOptionId,
+  selectedParentProductChanged,
+  isProviderDashboardChange,
+  showProviderPricingInlineEditor,
+  providerPricingUi,
+  providerQuotedLines,
+  editableSummaryPreSubtotalDelta,
+  adminCustomAdjustmentTotal,
+  adminCustomReceiptLines,
+  isManualOverrideEligibleLine,
+  isAdmin,
+  useAdminFeAuthoritativeQuote,
+  isCustomerSelfServeChange,
+  effectiveSubtotalForCheckout,
+  pricingConfig,
+}: UseAdminChangeQuoteDisplayStateParams) {
+  /** When quote blocks checkout, compare FE vs server lines for debugging (prefers `pricingDriftDetail` from API when sent). */
+  const quoteBlockedPricingDrift = useMemo(() => {
+    if (!suppressSelfServeCurrencyUi || latestChangeQuote?.canProceed !== false) return null;
+    if (!selectedAvailability || totalQuantity <= 0) return null;
+
+    const api = latestChangeQuote.pricingDriftDetail;
+    const currencyForFmt = (latestChangeQuote.currency ?? currency) as Currency;
+
+    const clientMappedFromApi = mapQuoteLineItemsToPriceSummaryLines(api?.clientLineItems);
+    const useBeClientLines = clientMappedFromApi.length > 0;
+    /**
+     * Checkout passes tax/discount via PriceSummary props, not always as `priceSummaryLines`. Include them here so
+     * drift rows and their sums align with `changeFlowNewBookingTotal` (subtotal + tax - promo).
+     */
+    const clientLinesForMerge: PriceSummaryLine[] = (() => {
+      if (useBeClientLines) return clientMappedFromApi;
+      const lines: PriceSummaryLine[] = [...checkoutPriceSummaryLines];
+      const hasTaxLine = lines.some(
+        (l) => l.kind === 'line' && String(l.type ?? '').toUpperCase() === 'TAX',
+      );
+      if (!hasTaxLine && !isTaxIncludedInPrice && Math.abs(effectiveTax) >= 0.005) {
+        lines.push({
+          kind: 'line',
+          label: t('booking.tax') !== 'booking.tax' ? t('booking.tax') : 'Taxes and fees',
+          amount: effectiveTax,
+          type: 'TAX',
+        });
+      }
+      const hasPromoSummaryLine = lines.some(
+        (l) =>
+          l.kind === 'line' &&
+          (/PROMO|DISCOUNT|VOUCHER|GIFT/i.test(String(l.type ?? '')) ||
+            (l.amount < -0.005 && /promo|discount/i.test(l.label))),
+      );
+      if (!hasPromoSummaryLine && Math.abs(effectivePromoDiscountAmount) >= 0.005) {
+        const trimmedPromoCode = appliedPromoCode?.trim() ?? '';
+        const promoLabel =
+          trimmedPromoCode.length > 0
+            ? `Promo: ${trimmedPromoCode}`
+            : originalReceipt?.promoLabel?.trim() || 'Discount';
+        lines.push({
+          kind: 'line',
+          label: promoLabel,
+          amount: -effectivePromoDiscountAmount,
+          type: 'PROMO_CODE',
+        });
+      }
+      return lines;
+    })();
+
+    const serverMappedFromApi = mapQuoteLineItemsToPriceSummaryLines(api?.serverLineItems);
+    const useBeServerLines = serverMappedFromApi.length > 0;
+    const serverLinesForMerge = useBeServerLines
+      ? serverMappedFromApi
+      : (latestChangeQuote.serverPreview?.priceSummaryLines ?? []);
+
+    const clientTotalForDrift =
+      api?.clientTotalMajorUnits != null && Number.isFinite(api.clientTotalMajorUnits)
+        ? api.clientTotalMajorUnits
+        : useBeClientLines
+          ? sumPriceSummaryLinesMajorUnits(clientMappedFromApi)
+          : changeFlowNewBookingTotal;
+
+    let totalDelta: number | null = null;
+    if (api?.deltaMajorUnits != null && Number.isFinite(api.deltaMajorUnits)) {
+      totalDelta = roundMoney(api.deltaMajorUnits);
+    }
+
+    /**
+     * Server "price check" total: explicit API fields -> sum of BE server lines -> derive from delta -> receipt preview totals.
+     */
+    let serverTotalFromQuote: number | undefined =
+      api?.serverTotalMajorUnits != null && Number.isFinite(api.serverTotalMajorUnits)
+        ? api.serverTotalMajorUnits
+        : undefined;
+    if (serverTotalFromQuote == null && useBeServerLines) {
+      serverTotalFromQuote = sumPriceSummaryLinesMajorUnits(serverMappedFromApi);
+    }
+    if (serverTotalFromQuote == null && totalDelta != null) {
+      serverTotalFromQuote = roundMoney(clientTotalForDrift - totalDelta);
+    }
+    if (serverTotalFromQuote == null) {
+      serverTotalFromQuote =
+        latestChangeQuote.serverDisplay?.total ??
+        latestChangeQuote.serverPreview?.totalNewBooking ??
+        undefined;
+    }
+    if (totalDelta == null && serverTotalFromQuote != null && Number.isFinite(serverTotalFromQuote)) {
+      totalDelta = roundMoney(clientTotalForDrift - serverTotalFromQuote);
+    }
+
+    const mergedForDrift = mergePriceSummaryLinesForDrift(clientLinesForMerge, serverLinesForMerge);
+    const rows =
+      api?.lineComparisons && api.lineComparisons.length > 0
+        ? mergeLineComparisonsWithFullDrift(api.lineComparisons, mergedForDrift)
+        : mergedForDrift;
+
+    const receiptAnchoring = api?.receiptAnchoring;
+    let driftRows = rows;
+    if (receiptAnchoring) {
+      const adj = roundMoney(
+        receiptAnchoring.reconciledTotalMajorUnits -
+          receiptAnchoring.requestedCatalogLineSumMajorUnits,
+      );
+      if (Math.abs(adj) >= 0.005) {
+        driftRows = [
+          ...rows,
+          {
+            key: 'meta:receipt-anchoring',
+            label: 'Receipt anchoring adjustment (BE only - not included in app total)',
+            clientAmount: null,
+            serverAmount: adj,
+            delta: computePricingDriftDelta(null, adj),
+          },
+        ];
+      }
+    }
+
+    const hasTotalDelta = totalDelta != null && Math.abs(totalDelta) >= 0.005;
+
+    if (driftRows.length === 0 && !hasTotalDelta) {
+      return null;
+    }
+
+    const usesBeLinePayload = useBeClientLines || useBeServerLines;
+
+    const ticketCartDetail = ticketLineItemsForChangeFlowDisplay
+      .filter((l) => (l.qty ?? 0) > 0)
+      .map((line) => {
+        const cat = line.category?.trim().toUpperCase() ?? '';
+        const rate = pricingForTicketSelector.find((r) => r.category.toUpperCase() === cat);
+        const rawList = rate?.baseInDisplayCurrency ?? rate?.priceCAD;
+        const listUnit =
+          rawList != null && Number.isFinite(Number(rawList))
+            ? Number(rawList)
+            : line.qty > 0
+              ? line.itemTotal / line.qty
+              : 0;
+        return {
+          category: cat,
+          qty: line.qty,
+          listUnitMajor: roundMoney(listUnit),
+          effectiveUnitMajor: roundMoney(line.qty > 0 ? line.itemTotal / line.qty : 0),
+          lineTotalMajor: line.itemTotal,
+        };
+      });
+
+    return (
+      <ChangeBookingPricingDriftPanel
+        rows={driftRows}
+        clientTotal={clientTotalForDrift}
+        serverTotal={serverTotalFromQuote}
+        totalDelta={totalDelta}
+        currency={currencyForFmt}
+        locale={locale}
+        ticketCartDetail={ticketCartDetail.length > 0 ? ticketCartDetail : undefined}
+        serverTicketPricingTrace={latestChangeQuote.ticketPricingTrace ?? undefined}
+        receiptAnchoring={receiptAnchoring}
+        footnote={
+          usesBeLinePayload
+            ? 'Lines use pricingDriftDetail.clientLineItems / serverLineItems when the quote includes them; totals prefer explicit major-unit fields, then sums of those lines, then the live cart / receipt preview.'
+            : undefined
+        }
+      />
+    );
+  }, [
+    suppressSelfServeCurrencyUi,
+    latestChangeQuote,
+    selectedAvailability,
+    totalQuantity,
+    checkoutPriceSummaryLines,
+    changeFlowNewBookingTotal,
+    currency,
+    locale,
+    ticketLineItemsForChangeFlowDisplay,
+    pricingForTicketSelector,
+    isTaxIncludedInPrice,
+    effectiveTax,
+    effectivePromoDiscountAmount,
+    appliedPromoCode,
+    originalReceipt?.promoLabel,
+    t,
+  ]);
+
+  const selfServeCheckoutPlaceholder = buildChangeBookingQuoteStatusPlaceholder({
+    suppressSelfServeCurrencyUi,
+    hasSelectedAvailability: selectedAvailability != null,
+    totalQuantity,
+    selfServePricingConfirmed,
+    changeQuoteLoading,
+    changeQuoteFetchError,
+    quoteCanProceed: latestChangeQuote?.canProceed,
+    quoteBlockedReason: latestChangeQuote?.reasonIfBlocked,
+    blockedDetails: quoteBlockedPricingDrift,
+    t,
+  });
+
+  const changeSelectionDetails = useChangeBookingSelectionDetails({
+    initialValues,
+    selectedAvailability,
+    selectedReturnOption,
+    implicitReturnBaselineId,
+    pickupLocationId,
+    quantities,
+    addOnSelections,
+    initialAddOnMinQtyByKey,
+    changeFlowResolvedInitialProductOptionId,
+    productChanged: selectedParentProductChanged,
+  });
+  const hasChangeSelection =
+    isProviderDashboardChange
+      ? changeSelectionDetails.hasOperationalChangesFromInitial
+      : changeSelectionDetails.hasChangesFromInitial;
+
+  const {
+    providerTotalsPreview,
+    hasEffectiveChangeSelection,
+    providerPricingOverrides,
+    adminCustomLinesAsAdditionalAdjustments,
+    mergedProviderAdditionalAdjustments,
+  } = useAdminProviderPricingAdjustments({
+    isProviderDashboardChange,
+    showProviderPricingInlineEditor,
+    providerPricingUi,
+    providerQuotedLines,
+    hasChangeSelection,
+    editableSummaryPreSubtotalDelta,
+    adminCustomAdjustmentTotal,
+    adminCustomReceiptLines,
+    isManualOverrideEligibleLine,
+  });
+
+  const unchangedReceiptAnchor = useMemo(
+    () =>
+      originalReceipt && !hasEffectiveChangeSelection
+        ? {
+            subtotal: roundMoney(originalReceipt.subtotal),
+            tax: roundMoney(originalReceipt.tax),
+            total: roundMoney(originalReceipt.total),
+          }
+        : null,
+    [hasEffectiveChangeSelection, originalReceipt],
+  );
+
+  /**
+   * True until `quoteChangeBooking` returns a confirmed `serverDisplay` for the current selection.
+   * Named so manual price-line UI can align with "still settling final price" without touching ticket/receipt math.
+   */
+  const changeFlowFinalPricePending =
+    suppressSelfServeCurrencyUi &&
+    selectedAvailability != null &&
+    totalQuantity > 0 &&
+    !selfServePricingConfirmed;
+
+  /**
+   * Provider inline edits + admin custom lines: show while waiting on or after the authoritative quote.
+   * UI-only gate - does not alter ticket line items or receipt-floor rules.
+   */
+  const showChangeFlowManualPriceLines =
+    hasEffectiveChangeSelection && (changeFlowFinalPricePending || selfServePricingConfirmed);
+  const showAdminCustomLineEditor =
+    isAdmin &&
+    selectedAvailability != null &&
+    totalQuantity > 0;
+
+  const displayedChangeAmountsRaw = resolveChangeFlowDisplayedAmounts({
+    providerPreview: providerTotalsPreview,
+    serverQuotePreview:
+      !useAdminFeAuthoritativeQuote && isCustomerSelfServeChange && latestChangeQuote?.serverDisplay
+        ? latestChangeQuote.serverDisplay
+        : null,
+    fromCart: {
+      total: changeFlowNewBookingTotal,
+      subtotal: effectiveSubtotalForCheckout,
+      tax: effectiveTax,
+    },
+  });
+  /** When cart drives display, `effectiveSubtotalForCheckout` already includes admin adjustments - do not add twice. */
+  const displayLayerUsesExternalPricing =
+    Boolean(providerTotalsPreview) ||
+    (!useAdminFeAuthoritativeQuote && isCustomerSelfServeChange && Boolean(latestChangeQuote?.serverDisplay));
+  const adminTaxDeltaForExternalDisplay =
+    displayLayerUsesExternalPricing && !isTaxIncludedInPrice && Math.abs(adminCustomAdjustmentTotal) >= 0.0005
+      ? roundMoney(adminCustomAdjustmentTotal * (pricingConfig?.taxRate ?? 0))
+      : 0;
+  const displayChangeFlowTax = roundMoney(
+    unchangedReceiptAnchor
+      ? unchangedReceiptAnchor.tax
+      : displayedChangeAmountsRaw.tax + adminTaxDeltaForExternalDisplay
+  );
+  const displayChangeFlowProposedTotal = roundMoney(
+    unchangedReceiptAnchor
+      ? unchangedReceiptAnchor.total
+      : displayLayerUsesExternalPricing
+        ? displayedChangeAmountsRaw.total + adminCustomAdjustmentTotal + adminTaxDeltaForExternalDisplay
+        : displayedChangeAmountsRaw.total
+  );
+  const displayChangeFlowProposedTotalWithEditableLines = roundMoney(
+    displayChangeFlowProposedTotal + editableSummaryPreSubtotalDelta
+  );
+
+  return {
+    selfServeCheckoutPlaceholder,
+    changeSelectionDetails,
+    hasChangeSelection,
+    hasEffectiveChangeSelection,
+    providerPricingOverrides,
+    adminCustomLinesAsAdditionalAdjustments,
+    mergedProviderAdditionalAdjustments,
+    unchangedReceiptAnchor,
+    showChangeFlowManualPriceLines,
+    showAdminCustomLineEditor,
+    displayedChangeAmountsRaw,
+    displayLayerUsesExternalPricing,
+    displayChangeFlowTax,
+    displayChangeFlowProposedTotal,
+    displayChangeFlowProposedTotalWithEditableLines,
+  };
+}