@code-collective/booking-widget 1.0.9 → 1.0.12

package/src/lib/index.ts

@@ -1,196 +1,242 @@
-import './app.css';
-import { mount, unmount } from 'svelte';
-import type { WizardPages, CartOverviewDisplay } from './config';
-import type { BookingApi } from './api';
-import type { CheckoutCartDetailDto } from './client-types';
-import { ApiClient, ApiError } from './api';
-import { SessionManager } from './session-manager';
-import { CartManager } from './cart-manager';
-import { onWidgetMessage } from './messages';
-import TicketConfiguratorComponent from './TicketConfigurator.svelte';
-import CheckoutComponent from './Checkout.svelte';
-import CartOverviewComponent from './CartOverview.svelte';
-
-// Re-export components for direct Svelte usage
-export { default as TicketConfigurator } from './TicketConfigurator.svelte';
-export { default as Checkout } from './Checkout.svelte';
-export { default as CartOverview } from './CartOverview.svelte';
-export { default as CartBar } from './CartBar.svelte';
-export { default as CartOverviewButton } from './CartOverviewButton.svelte';
-
-// Re-export utilities
-export { ApiClient, ApiError, SessionManager, CartManager };
-export { resolveWizardPages, resolveEditPages, DEFAULT_WIZARD_PAGES } from './config';
-export type { BookingApi } from './api';
-export type { WizardPages, WizardPageConfig, CartOverviewDisplay, WidgetMode, WizardWidgetType } from './config';
-export type { components, operations, paths } from './generated-types';
-export type * from './client-types';
-
-// --- Mount function configs ---
-
-interface BaseConfig {
-  apiBaseUrl?: string;
-  checkoutKey?: string;
-  // Cart-global, not tied to any one mount function - fires after any add/edit/remove, anywhere on the page,
-  // carrying the same cart TicketConfigurator/CheckoutModal already fetch for their own internal use. Lets a
-  // consumer build a custom cart summary (item count, remaining time, item details) without calling the
-  // checkout API directly.
-  onCartUpdated?: (cart: CheckoutCartDetailDto | null) => void;
-  // Fires when the cart's own clock ran out (or, for mountCheckout, when it loads onto a cart the server has
-  // already let go) - see messages.ts's own cart:expired doc comment for why this is narrower than an
-  // onCartUpdated(null) call, which a manual clear can also produce.
-  onCartExpired?: () => void;
-}
-
-export interface ConfiguratorConfig extends BaseConfig {
-  productId: string;
-  currency?: string;
-  wizardPages?: WizardPages;
-  autoSelectSingleTimeSlot?: boolean;
-  cancelable?: boolean;
-  onCartChange?: (detail: { itemCount: number; cartItemId: string; totalFormatted: string }) => void;
-  onCancel?: () => void;
-}
-
-export interface CheckoutConfig extends BaseConfig {
-  wizardPages?: WizardPages;
-  editPages?: WizardPages;
-  autoSelectSingleTimeSlot?: boolean;
-  onClose?: () => void;
-  onOrderConfirmed?: (detail: { cartToken: string; value: number; currency: string }) => void;
-}
-
-export interface CartOverviewConfig extends BaseConfig {
-  display?: CartOverviewDisplay;
-  onCheckout?: () => void;
-}
-
-export interface MountedWidget {
-  destroy: () => void;
-}
-
-// --- Shared bootstrap ---
-
-function bootstrap(config: BaseConfig): { api: BookingApi; sessionManager: SessionManager; cartManager: CartManager } {
-  const api: BookingApi = new ApiClient(config.apiBaseUrl ?? '');
-
-  const sessionManager = new SessionManager(api);
-  const cartManager = new CartManager(api);
-  sessionManager.startBackgroundRefresh();
-
-  return { api, sessionManager, cartManager };
-}
-
-// --- Mount functions ---
-
-export async function mountConfigurator(target: HTMLElement, config: ConfiguratorConfig): Promise<MountedWidget> {
-  const { api, sessionManager, cartManager } = bootstrap(config);
-
-  await sessionManager.ensureSession(config.checkoutKey ?? '');
-
-  const component = mount(TicketConfiguratorComponent, {
-    target,
-    props: {
-      api,
-      cartManager,
-      productId: config.productId,
-      wizardPages: config.wizardPages,
-      autoSelectSingleTimeSlot: config.autoSelectSingleTimeSlot ?? false,
-      onCancel: config.onCancel,
-    },
-  });
-
-  // Listen for postMessage events and forward to callbacks
-  const stopListening = onWidgetMessage((d) => {
-    if (d.type === 'cart:change' && config.onCartChange) {
-      config.onCartChange({
-        itemCount: (d.itemCount as number) ?? 0,
-        cartItemId: (d.cartItemId as string) ?? '',
-        totalFormatted: (d.totalFormatted as string) ?? '',
-      });
-    }
-    if (d.type === 'cart:updated' && 'cart' in d) {
-      config.onCartUpdated?.(d.cart as CheckoutCartDetailDto | null);
-    }
-    if (d.type === 'cart:expired') config.onCartExpired?.();
-  });
-
-  return {
-    destroy() {
-      stopListening();
-      sessionManager.stop();
-      unmount(component);
-    },
-  };
-}
-
-export async function mountCheckout(target: HTMLElement, config: CheckoutConfig): Promise<MountedWidget> {
-  const { api, sessionManager, cartManager } = bootstrap(config);
-
-  await sessionManager.ensureSession(config.checkoutKey ?? '');
-
-  const component = mount(CheckoutComponent, {
-    target,
-    props: {
-      api,
-      cartManager,
-      wizardPages: config.wizardPages,
-      editPages: config.editPages,
-      autoSelectSingleTimeSlot: config.autoSelectSingleTimeSlot ?? false,
-    },
-  });
-
-  const stopListening = onWidgetMessage((d) => {
-    if (d.type === 'modal:close' && config.onClose) config.onClose();
-    if (d.type === 'order:complete' && config.onOrderConfirmed) {
-      config.onOrderConfirmed({
-        cartToken: (d.cartToken as string) ?? '',
-        value: (d.value as number) ?? 0,
-        currency: (d.currency as string) ?? 'ZAR',
-      });
-    }
-    if (d.type === 'cart:updated' && 'cart' in d) {
-      config.onCartUpdated?.(d.cart as CheckoutCartDetailDto | null);
-    }
-    if (d.type === 'cart:expired') config.onCartExpired?.();
-  });
-
-  return {
-    destroy() {
-      stopListening();
-      sessionManager.stop();
-      unmount(component);
-    },
-  };
-}
-
-export async function mountCartOverview(target: HTMLElement, config: CartOverviewConfig): Promise<MountedWidget> {
-  const { api, sessionManager, cartManager } = bootstrap(config);
-
-  await sessionManager.ensureSession(config.checkoutKey ?? '');
-
-  const component = mount(CartOverviewComponent, {
-    target,
-    props: {
-      api,
-      cartManager,
-      display: config.display ?? 'bar',
-    },
-  });
-
-  const stopListening = onWidgetMessage((d) => {
-    if (d.type === 'modal:open' && config.onCheckout) config.onCheckout();
-    if (d.type === 'cart:updated' && 'cart' in d) {
-      config.onCartUpdated?.(d.cart as CheckoutCartDetailDto | null);
-    }
-    if (d.type === 'cart:expired') config.onCartExpired?.();
-  });
-
-  return {
-    destroy() {
-      stopListening();
-      sessionManager.stop();
-      unmount(component);
-    },
-  };
-}
+import './app.css';
+import { mount, unmount } from 'svelte';
+import type { CartOverviewDisplay, CartOverviewState } from './config';
+import type { BookingHost, BookingHostConfig } from './host.svelte';
+import { createBookingHost } from './host.svelte';
+import { ApiClient, ApiError } from './api';
+import { SessionManager } from './session-manager';
+import { CartManager } from './cart-manager';
+import { onWidgetMessage } from './messages';
+import TicketConfiguratorComponent from './TicketConfigurator.svelte';
+import CheckoutComponent from './Checkout.svelte';
+import CartOverviewComponent from './CartOverview.svelte';
+
+// Re-export components for direct Svelte usage
+export { default as TicketConfigurator } from './TicketConfigurator.svelte';
+export { default as Checkout } from './Checkout.svelte';
+export { default as CartOverview } from './CartOverview.svelte';
+export { default as CartBar } from './CartBar.svelte';
+export { default as CartOverviewButton } from './CartOverviewButton.svelte';
+// Required if you are not using the elements build: it owns the "still shopping?" warning, the expired view
+// and the payment-timeout hand-over, and nothing else on the page does. createBookingHost mounts it for you;
+// export it for consumers composing everything by hand.
+export { default as CartExpiryGuard } from './CartExpiryGuard.svelte';
+// Supplies the host to everything beneath it, so components need no api/cartManager props of their own.
+export { default as BookingProvider } from './BookingProvider.svelte';
+
+// Re-export utilities
+export { ApiClient, ApiError, SessionManager, CartManager };
+export { resolveWizardPages, resolveEditPages, DEFAULT_WIZARD_PAGES } from './config';
+export { createBookingHost, setBookingDefaults, getBookingDefaults, requestCheckoutOpen, requestCheckoutClose } from './host.svelte';
+export { portal } from './portal';
+export { setPeachSdk } from './peach-sdk';
+export type { PeachEnv } from './peach-sdk';
+export { getBookingHostContext } from './booking-context';
+export { onWidgetMessage, postMessage } from './messages';
+export type { BookingApi } from './api';
+export type { BookingHost, BookingHostConfig, BookingDefaults, ResolvedBookingOptions } from './host.svelte';
+export type {
+  WizardPages, WizardPageConfig, CartOverviewDisplay, CartOverviewState, CheckoutMode, WidgetMode, WizardWidgetType,
+} from './config';
+export type {
+  WidgetMessage, WidgetMessageType, CartChangeMessage, CartUpdatedMessage, CartExpiredMessage,
+  ModalOpenMessage, ModalCloseMessage, OrderCompleteMessage, PaymentStartedMessage, PaymentEndedMessage,
+  PaymentTimedOutMessage,
+} from './messages';
+export type { components, operations, paths } from './generated-types';
+export type * from './client-types';
+
+// --- Mount function configs ---
+
+// Every mount function takes the same host options, so a consumer mounting more than one widget can hand all
+// of them the same host and get one session, one cart and one expiry guard - see `host` below.
+type BaseConfig = Omit<BookingHostConfig, 'onCheckoutOpenChange'> & {
+  // An existing host to mount into. Without one each mount function builds its own, which means its own
+  // session and its own cart - fine for a single widget on a page, wrong for two.
+  host?: BookingHost;
+};
+
+export interface ConfiguratorConfig extends BaseConfig {
+  productId: string;
+  currency?: string;
+  cancelable?: boolean;
+  // onCartChange and the other cart callbacks come from BookingHostConfig - see createBookingHost.
+  onCancel?: () => void;
+}
+
+export interface CheckoutConfig extends BaseConfig {
+  // Inline by default - the mount target is a container the consumer positioned itself. Pass 'modal' for the
+  // portalled overlay the custom-elements build shows.
+  mode?: 'inline' | 'modal';
+  onClose?: () => void;
+}
+
+export interface CartOverviewConfig extends BaseConfig {
+  display?: CartOverviewDisplay;
+  onCheckout?: () => void;
+  /** Distinguishes an empty cart from one that could not be read - see CartOverview. */
+  onStateChange?: (state: CartOverviewState) => void;
+}
+
+export interface MountedWidget {
+  destroy: () => void;
+}
+
+// --- Mount functions ---
+
+interface MountContext {
+  host: BookingHost;
+  /** Tearing the widget down tears the host down too - but only the host this mount built itself. */
+  release: () => void;
+}
+
+/**
+ * Resolves the host a mount function will use. A host passed in is the consumer's to destroy - other widgets
+ * are probably still using it - so this mount only unsubscribes the callbacks it added to it.
+ */
+/**
+ * Waits for the session, releasing whatever the mount just acquired if it is refused. Without this a
+ * rejected ready - an unallowlisted checkout key, the failure consumers are told to expect - left the
+ * host's message subscription, its session-refresh interval and its expiry-guard refcount behind, and that
+ * leaked refcount pins CartExpiryGuard on <body> for the life of the page.
+ */
+async function readyOrRelease(context: MountContext): Promise<void> {
+  try {
+    await context.host.ready;
+  } catch (e) {
+    context.release();
+    throw e;
+  }
+}
+
+function hostFor(config: BaseConfig): MountContext {
+  if (!config.host) {
+    const host = createBookingHost(config);
+    return { host, release: () => host.destroy() };
+  }
+
+  // The host was built elsewhere and already carries its own callbacks, so the ones on this config would
+  // otherwise be dropped on the floor - a consumer following the documented `{ host, onOrderConfirmed }`
+  // shape would get a checkout that never reports a confirmed order. They are wired to the same messages
+  // the host itself listens to.
+  return { host: config.host, release: subscribeCallbacks(config) };
+}
+
+function subscribeCallbacks(config: BaseConfig): () => void {
+  const { onCartChange, onCartUpdated, onCartExpired, onOrderConfirmed } = config;
+  if (!onCartChange && !onCartUpdated && !onCartExpired && !onOrderConfirmed) return () => {};
+
+  return onWidgetMessage((d) => {
+    if (d.type === 'cart:change') {
+      onCartChange?.({
+        itemCount: d.itemCount,
+        cartItemId: d.cartItemId,
+        totalFormatted: d.totalFormatted,
+      });
+    }
+    if (d.type === 'cart:updated') onCartUpdated?.(d.cart);
+    if (d.type === 'cart:expired') onCartExpired?.();
+    if (d.type === 'order:complete') {
+      onOrderConfirmed?.({ cartToken: d.cartToken, value: d.value, currency: d.currency });
+    }
+  });
+}
+
+export async function mountConfigurator(target: HTMLElement, config: ConfiguratorConfig): Promise<MountedWidget> {
+  const context = hostFor(config);
+  const { host, release } = context;
+
+  await readyOrRelease(context);
+
+  const component = mount(TicketConfiguratorComponent, {
+    target,
+    props: {
+      api: host.api,
+      cartManager: host.cartManager,
+      productId: config.productId,
+      wizardPages: config.wizardPages ?? host.options.wizardPages,
+      autoSelectSingleTimeSlot: config.autoSelectSingleTimeSlot ?? host.options.autoSelectSingleTimeSlot,
+      // Stated per configurator so this and the host's own autoOpenCheckout meet in the same branch - see
+      // host.svelte.ts. Both have to say yes for an add to open checkout, which is what lets one configurator
+      // on a page opt out (the ES equivalent of the element's no-auto-checkout) without silencing the rest.
+      autoOpenCheckout: config.autoOpenCheckout !== false,
+      onCancel: config.onCancel,
+    },
+  });
+
+  return {
+    destroy() {
+      unmount(component);
+      release();
+    },
+  };
+}
+
+export async function mountCheckout(target: HTMLElement, config: CheckoutConfig): Promise<MountedWidget> {
+  const context = hostFor(config);
+  const { host, release } = context;
+
+  await readyOrRelease(context);
+
+  const component = mount(CheckoutComponent, {
+    target,
+    props: {
+      api: host.api,
+      cartManager: host.cartManager,
+      wizardPages: config.wizardPages ?? host.options.wizardPages,
+      editPages: config.editPages ?? host.options.editPages,
+      autoSelectSingleTimeSlot: config.autoSelectSingleTimeSlot ?? host.options.autoSelectSingleTimeSlot,
+      mode: config.mode ?? 'inline',
+      // The modal opens and closes with the host, which is what an add-to-cart and the cart bar's button
+      // both reach. A consumer wanting to drive it directly can call host.openCheckout().
+      get open() {
+        return host.isCheckoutOpen;
+      },
+      // Fires for every dismissal, not just the scrim - Checkout answers the modal:close message rather
+      // than only its own overlay click.
+      onClose: config.onClose,
+    },
+  });
+
+  return {
+    destroy() {
+      unmount(component);
+      release();
+    },
+  };
+}
+
+export async function mountCartOverview(target: HTMLElement, config: CartOverviewConfig): Promise<MountedWidget> {
+  const context = hostFor(config);
+  const { host, release } = context;
+
+  await readyOrRelease(context);
+
+  const component = mount(CartOverviewComponent, {
+    target,
+    props: {
+      api: host.api,
+      cartManager: host.cartManager,
+      display: config.display ?? 'bar',
+      onStateChange: config.onStateChange,
+    },
+  });
+
+  const stopListening = config.onCheckout
+    ? onCheckoutRequested(config.onCheckout)
+    : () => {};
+
+  return {
+    destroy() {
+      stopListening();
+      unmount(component);
+      release();
+    },
+  };
+}
+
+function onCheckoutRequested(onCheckout: () => void): () => void {
+  return onWidgetMessage((d) => {
+    if (d.type === 'modal:open') onCheckout();
+  });
+}

package/src/lib/layout.svelte.ts

@@ -0,0 +1,52 @@
+/**
+ * The configurator is presented two different ways by its host, and the two need different chrome.
+ * The marketing site (city-sightseeing-site/marketing-site/apps/web/src/components/BookingWidget.svelte)
+ * splits on Tailwind's `lg`: at and above it the widget sits inline in the product page's sticky
+ * sidebar, below it that sidebar is display:none and the widget is opened as a full-screen sheet
+ * instead. Matching that exact breakpoint here is what keeps the widget's own layout in step with
+ * the host's - a widget that thought it was inline while sitting in a full-screen sheet would show
+ * a duplicate header and a card that refuses to fill the screen.
+ */
+export const INLINE_LAYOUT_QUERY = '(min-width: 1024px)';
+
+// The one place that knows whether this environment can answer the question at all. SSR has no window,
+// and jsdom (this package's test environment) has no matchMedia, so both the seed and the subscription
+// below go through here rather than each guarding differently - or, as happened once, one not guarding.
+function inlineLayoutQuery(): MediaQueryList | null {
+  if (typeof window === 'undefined' || !window.matchMedia) return null;
+  return window.matchMedia(INLINE_LAYOUT_QUERY);
+}
+
+function matchesInlineLayout(): boolean {
+  // Where the question cannot be asked, inline is the safer answer: it is the variant whose chrome the
+  // host never duplicates.
+  return inlineLayoutQuery()?.matches ?? true;
+}
+
+export interface InlineLayout {
+  readonly isInline: boolean;
+}
+
+/**
+ * Tracks which of the two presentations the widget is currently in. Call during component
+ * initialisation - it registers an $effect that follows viewport changes for the component's
+ * lifetime, so a desktop window dragged narrow re-lays out rather than keeping stale chrome.
+ */
+export function createInlineLayout(): InlineLayout {
+  // Seeded synchronously rather than waiting for the effect below, so the first paint is already
+  // the right variant instead of rendering full-screen and visibly correcting itself on desktop.
+  let isInline = $state(matchesInlineLayout());
+
+  $effect(() => {
+    const query = inlineLayoutQuery();
+    if (!query) return;
+    isInline = query.matches;
+    const onChange = (e: MediaQueryListEvent) => { isInline = e.matches; };
+    query.addEventListener('change', onChange);
+    return () => query.removeEventListener('change', onChange);
+  });
+
+  return {
+    get isInline() { return isInline; },
+  };
+}