@riverbankcms/sdk 0.135.1 → 0.137.0

package/dist/_dts/blocks/src/system/runtime/nodes/event-registration/VerifyingTimeoutStep.d.ts

@@ -1,7 +1,9 @@
 import React from 'react';
 type VerifyingTimeoutStepProps = {
-    onCheckAgain: () => void;
+    onCheckAgain?: () => void;
     supportEmail?: string;
+    title?: string;
+    message?: string;
 };
 /**
  * Verifying Timeout Step

package/dist/_dts/blocks/src/system/runtime/nodes/event-registration/event-registration.headless.contract.d.ts

@@ -1,4 +1,5 @@
 import type { DirectCheckoutCollectionOptionKind, PaymentMethod } from '../../api/types';
+import type { EventRegistrationErrorAction } from '../../../../../../commerce/src/purchase/index';
 import type { EventRegistrationDirectPaymentOption, EventRegistrationDirectPaymentSelectionState } from './eventPaymentOptions';
 import type { EventRegistrationPageSurfaceSubject } from './eventScope';
 import type { EligibilityData, EventTicketSelectionLine, FormData, Guest, GuestErrors, OccurrenceContext, PaymentSelection, PaymentStepState, PublicEvent, RegistrationEvent, RegistrationResult } from './types';
@@ -52,6 +53,7 @@ export type EventRegistrationFlowStatus = Readonly<{
 }> | Readonly<{
     tag: 'error';
     message: string;
+    action?: EventRegistrationErrorAction;
 }>;
 export type EventRegistrationFlowView = Readonly<{
     kind: 'empty';

package/dist/_dts/blocks/src/system/runtime/nodes/event-registration/event-registration.headless.planning.d.ts

@@ -10,7 +10,7 @@ export declare function resolveEventRegistrationSubmitPlan(input: Readonly<{
     eventRequiresPayment: boolean;
     canJoinWaitlist?: boolean | null;
 }>): EventRegistrationSubmitPlan;
-export declare function resolveHeadlessEventRegistrationStatus(wizard: Pick<UseEventRegistrationWizardResult, 'step' | 'registrationResult' | 'errorMessage'>): EventRegistrationFlowStatus;
+export declare function resolveHeadlessEventRegistrationStatus(wizard: Pick<UseEventRegistrationWizardResult, 'step' | 'registrationResult' | 'errorMessage'> & Partial<Pick<UseEventRegistrationWizardResult, 'errorAction'>>): EventRegistrationFlowStatus;
 export declare function resolveHeadlessEventRegistrationView(wizard: Readonly<Pick<UseEventRegistrationWizardResult, 'step' | 'scopedEvents' | 'occurrenceContext' | 'registrationResult' | 'errorMessage'> & {
     api: Pick<UseEventRegistrationWizardResult['api'], 'config'>;
 }>): EventRegistrationFlowView;

package/dist/_dts/blocks/src/system/runtime/nodes/event-registration/hooks.d.ts

@@ -59,6 +59,7 @@ export type UseEligibilityResult = {
     creditState: PortalCreditState;
 };
 export declare function useEligibility(params: {
+    refreshKey?: number;
     enabled: boolean;
     subject: RegistrationSubject | null;
     attendanceMode?: 'in_person' | 'online' | null;
@@ -67,6 +68,7 @@ export declare function useEligibility(params: {
     subjectEmail: string | null;
 }): UseEligibilityResult;
 export declare function useEligibilityWithDeps(params: {
+    refreshKey?: number;
     enabled: boolean;
     subject: RegistrationSubject | null;
     attendanceMode?: 'in_person' | 'online' | null;

package/dist/_dts/blocks/src/system/runtime/nodes/event-registration/registrationErrorPresentation.d.ts

@@ -0,0 +1,5 @@
+import { type EventRegistrationErrorAction } from '../../../../../../commerce/src/purchase/index';
+export declare function registrationErrorPresentation(error: unknown): Readonly<{
+    message: string;
+    action: EventRegistrationErrorAction;
+}>;

package/dist/_dts/blocks/src/system/runtime/nodes/event-registration/registrationErrorRecovery.d.ts

@@ -0,0 +1,25 @@
+import type { EventRegistrationErrorAction } from '../../../../../../commerce/src/purchase/index';
+import type { EligibilityData, EventTicketSelectionLine, RegistrationEvent, RegistrationStep } from './types';
+import type { RegistrationFlowAction } from './registrationStateMachine';
+import type { EventRegistrationStatusReference } from '../../api/types';
+export declare function resolveRegistrationRecoveryAction(step: RegistrationStep, action: EventRegistrationErrorAction): EventRegistrationErrorAction;
+export declare function canRecoverToWaitlist(eligibility: EligibilityData | null): boolean;
+export declare function shouldRefreshAfterRegistrationError(step: RegistrationStep, action: EventRegistrationErrorAction, enabled: boolean): boolean;
+export declare function resetRegistrationAfterExpiry(input: Readonly<{
+    hasPreSelectedContext: boolean;
+    preSelectedEvent: RegistrationEvent | null;
+    dispatchFlow: (action: RegistrationFlowAction) => void;
+    setSelectedTicketLines: (lines: EventTicketSelectionLine[]) => void;
+    setSelectedSlidingAmountInput: (value: string) => void;
+    setSelectedAttendanceMode: (mode: 'online' | 'in_person' | null) => void;
+    setErrorMessage: (message: string) => void;
+    setPendingRegistrationReference: (reference: EventRegistrationStatusReference | null) => void;
+}>): void;
+/** Recovery never starts another payment. Unknown payment outcomes go to the portal. */
+export declare function recoverRegistrationError(action: EventRegistrationErrorAction, handlers: Readonly<{
+    canJoinWaitlist?: boolean;
+    refreshOptions: () => void;
+    clearError: () => void;
+    setStep: (step: RegistrationStep) => void;
+    reset: () => void;
+}>): void;

package/dist/_dts/blocks/src/system/runtime/nodes/event-registration/registrationWizardContext.d.ts

@@ -1,5 +1,9 @@
 import type { EligibilityData, PaymentSelection, RegistrationEvent, RegistrationStep, RegistrationSubject } from './types';
 type PortalAuthState = 'checking' | 'authenticated' | 'unauthenticated';
+export declare function getEventSelectionDefaults(event: RegistrationEvent): Readonly<{
+    slidingAmountInput: string;
+    attendanceMode: 'online' | 'in_person' | null;
+}>;
 export declare function parseCurrencyInputToCents(value: string): number | null;
 export declare function formatCentsAsCurrencyInput(amount: number): string;
 export declare function getSlidingScaleForEvent(event: RegistrationEvent | null): Readonly<{

package/dist/_dts/blocks/src/system/runtime/nodes/event-registration/useEventRegistrationStripeReturn.d.ts

@@ -23,15 +23,20 @@ type EventRegistrationStripeReturnOptions = {
 };
 export type EventRegistrationStripeReturnDeps = Readonly<{
     usePaymentVerification: typeof usePaymentVerification;
-    consumeReturnParams: () => Readonly<{
+    readReturnParams: () => Readonly<{
         registration: string | null;
         registration_attempt: string | null;
+        session_id: string | null;
     }>;
+    clearReturnParams: () => void;
     scrollToBlock: typeof scrollToBlock;
     cleanupStaleRegistrations: typeof cleanupStaleRegistrations;
     clearPendingRegistration: typeof clearPendingRegistration;
     getPendingRegistration: typeof getPendingRegistration;
 }>;
-export declare function useEventRegistrationStripeReturn(options: EventRegistrationStripeReturnOptions): ReturnType<typeof usePaymentVerification>;
-export declare function useEventRegistrationStripeReturnWithDeps(options: EventRegistrationStripeReturnOptions, deps: EventRegistrationStripeReturnDeps): ReturnType<typeof usePaymentVerification>;
+export type EventRegistrationStripeReturnResult = ReturnType<typeof usePaymentVerification> & Readonly<{
+    retryReturn?: () => void;
+}>;
+export declare function useEventRegistrationStripeReturn(options: EventRegistrationStripeReturnOptions): EventRegistrationStripeReturnResult;
+export declare function useEventRegistrationStripeReturnWithDeps(options: EventRegistrationStripeReturnOptions, deps: EventRegistrationStripeReturnDeps): EventRegistrationStripeReturnResult;
 export {};

package/dist/_dts/blocks/src/system/runtime/nodes/event-registration/useEventRegistrationSubmit.d.ts

@@ -1,4 +1,5 @@
 import type { BlockApiClient } from '../../api';
+import type { EventRegistrationErrorAction } from '../../../../../../commerce/src/purchase/index';
 import { savePendingRegistration } from './sessionStorage';
 import type { EventTicketSelectionLine, FormData, Guest, RegistrationResult, RegistrationStep, PaymentSelection } from './types';
 import type { PaymentMethod } from '../../api/types';
@@ -37,6 +38,7 @@ export type UseEventRegistrationSubmitInput = {
     claimToken: string | null;
     setPendingRegistrationReference: (reference: EventRegistrationStatusReference) => void;
     setStep: (step: RegistrationStep) => void;
+    setErrorAction?: (action: EventRegistrationErrorAction) => void;
     setRegistrationResult: (result: RegistrationResult) => void;
     setErrorMessage: (message: string) => void;
 };

package/dist/_dts/blocks/src/system/runtime/nodes/event-registration/useEventRegistrationWizard.d.ts

@@ -1,3 +1,4 @@
+import type { EventRegistrationErrorAction } from '../../../../../../commerce/src/purchase/index';
 import type { DiscountContext } from '../../api/types';
 import type { EventTicketSelectionLine, EventRegistrationClientProps, EligibilityData, FormData, Guest, GuestErrors, PaymentSelection, PaymentStepState, PublicEvent, RegistrationEvent, RegistrationResult, RegistrationStep } from './types';
 import { usePortalAuth, useEligibility, useExistingEventRegistration } from './hooks';
@@ -101,6 +102,7 @@ export declare function useEventRegistrationWizard(options: UseEventRegistration
     handleGuestShakeEnd: () => void;
     registrationResult: RegistrationResult | null;
     errorMessage: string;
+    errorAction: EventRegistrationErrorAction;
     altchaSolution: string | null;
     setAltchaSolution: import("react").Dispatch<import("react").SetStateAction<string | null>>;
     portalAuthState: import("./hooks").PortalAuthState;
@@ -141,7 +143,7 @@ export declare function useEventRegistrationWizard(options: UseEventRegistration
     discountsAvailableLoading: boolean;
     discountContext: DiscountContext | null;
     shouldShowDiscountToggle: boolean;
-    verification: import("../../hooks/usePaymentVerification").PaymentVerificationResult;
+    verification: import("./useEventRegistrationStripeReturn").EventRegistrationStripeReturnResult;
     handleDetailsComplete: () => Promise<EventRegistrationDetailsCompleteResult>;
     handlePaymentSelect: () => Promise<void>;
     handleUseCardInsteadOfPass: () => void;
@@ -221,6 +223,7 @@ export declare function useEventRegistrationWizardWithDeps(options: UseEventRegi
     handleGuestShakeEnd: () => void;
     registrationResult: RegistrationResult | null;
     errorMessage: string;
+    errorAction: EventRegistrationErrorAction;
     altchaSolution: string | null;
     setAltchaSolution: import("react").Dispatch<import("react").SetStateAction<string | null>>;
     portalAuthState: import("./hooks").PortalAuthState;
@@ -261,7 +264,7 @@ export declare function useEventRegistrationWizardWithDeps(options: UseEventRegi
     discountsAvailableLoading: boolean;
     discountContext: DiscountContext | null;
     shouldShowDiscountToggle: boolean;
-    verification: import("../../hooks/usePaymentVerification").PaymentVerificationResult;
+    verification: import("./useEventRegistrationStripeReturn").EventRegistrationStripeReturnResult;
     handleDetailsComplete: () => Promise<EventRegistrationDetailsCompleteResult>;
     handlePaymentSelect: () => Promise<void>;
     handleUseCardInsteadOfPass: () => void;

package/dist/_dts/blocks/src/system/runtime/nodes/event-registration/useWaitlistClaimRestoration.d.ts

@@ -1,7 +1,9 @@
 import { type Dispatch, type SetStateAction } from 'react';
 import type { ResolveWaitlistClaimResponse } from '../../api/types';
 import type { EventTicketSelectionLine, FormData, Guest, RegistrationEvent, RegistrationStep } from './types';
+import type { EventRegistrationErrorAction } from '../../../../../../commerce/src/purchase/index';
 export type WaitlistClaimRestorationSetters = Readonly<{
+    setErrorAction?: (action: EventRegistrationErrorAction) => void;
     setErrorMessage: Dispatch<SetStateAction<string>>;
     setStep: (step: RegistrationStep) => void;
     setSelectedEvent: Dispatch<SetStateAction<RegistrationEvent | null>>;

package/dist/_dts/blocks/src/system/runtime/nodes/events/EventCalendar.client.d.ts

@@ -1,5 +1,5 @@
-import React from "react";
-import { type EventCalendarInteractiveIslandProps } from "./EventCalendar.interactive";
+import React from 'react';
+import { type EventCalendarInteractiveIslandProps } from './EventCalendar.interactive';
 export type EventCalendarClientProps = EventCalendarInteractiveIslandProps;
 export declare const EventCalendarClient: React.FC<EventCalendarClientProps>;
 export default EventCalendarClient;

package/dist/_dts/blocks/src/system/runtime/nodes/events/EventCalendar.interactive.d.ts

@@ -56,6 +56,14 @@ export declare const eventCalendarBlockRuntime: Readonly<{
             eventSurface: import("../../..").EventSurfaceScope;
             filterEventPresets: string | null;
             scheduleScope: import("../../..").EventScheduleScope;
+            calendarContext: Readonly<{
+                timeZone: import("../../../../../../core/src/index").BookingTimeZone;
+                initialToday: Readonly<{
+                    year: number;
+                    month: number;
+                    day: number;
+                }>;
+            }>;
         }>;
     }>;
     contracts: Readonly<{
@@ -73,6 +81,14 @@ export declare const eventCalendarBlockRuntime: Readonly<{
                     eventSurface: import("../../..").EventSurfaceScope;
                     filterEventPresets: string | null;
                     scheduleScope: import("../../..").EventScheduleScope;
+                    calendarContext: Readonly<{
+                        timeZone: import("../../../../../../core/src/index").BookingTimeZone;
+                        initialToday: Readonly<{
+                            year: number;
+                            month: number;
+                            day: number;
+                        }>;
+                    }>;
                 }>;
             }>) => unknown;
             decode: (input: unknown) => import("../../../../contracts").DecodeResult<Readonly<{
@@ -84,6 +100,14 @@ export declare const eventCalendarBlockRuntime: Readonly<{
                     eventSurface: import("../../..").EventSurfaceScope;
                     filterEventPresets: string | null;
                     scheduleScope: import("../../..").EventScheduleScope;
+                    calendarContext: Readonly<{
+                        timeZone: import("../../../../../../core/src/index").BookingTimeZone;
+                        initialToday: Readonly<{
+                            year: number;
+                            month: number;
+                            day: number;
+                        }>;
+                    }>;
                 }>;
             }>>;
         }>;
@@ -107,6 +131,14 @@ export declare const eventCalendarInteractiveIslandPropsCodec: Readonly<{
                 eventSurface: import("../../..").EventSurfaceScope;
                 filterEventPresets: string | null;
                 scheduleScope: import("../../..").EventScheduleScope;
+                calendarContext: Readonly<{
+                    timeZone: import("../../../../../../core/src/index").BookingTimeZone;
+                    initialToday: Readonly<{
+                        year: number;
+                        month: number;
+                        day: number;
+                    }>;
+                }>;
             }>;
         }>>;
     }>) => unknown;
@@ -127,6 +159,14 @@ export declare const eventCalendarInteractiveIslandPropsCodec: Readonly<{
                 eventSurface: import("../../..").EventSurfaceScope;
                 filterEventPresets: string | null;
                 scheduleScope: import("../../..").EventScheduleScope;
+                calendarContext: Readonly<{
+                    timeZone: import("../../../../../../core/src/index").BookingTimeZone;
+                    initialToday: Readonly<{
+                        year: number;
+                        month: number;
+                        day: number;
+                    }>;
+                }>;
             }>;
         }>>;
     }>>;

package/dist/_dts/blocks/src/system/runtime/nodes/events/EventCombined.client.d.ts

@@ -2,6 +2,7 @@ import React from "react";
 import type { PublicEvent, ButtonVariant, EventLayout, ColumnOption, WeekStart, CalendarTabViews, FilterAutoShow, CalendarView, EventScheduleScope, EventSurfaceScope } from "../../../blocks/events/shared/types";
 import type { CardRole } from "../../../../../../theme-core/src/cards/index";
 import type { EventCombinedInteractiveIslandProps } from "./EventCombined.interactive";
+import type { EventCollectionHydration } from './shared/eventCollectionContract';
 import { type EventListPaginationAction, type EventPageSize } from "./shared/listOptions";
 export type EventCombinedClientProps = Readonly<{
     events?: PublicEvent[] | null;
@@ -32,6 +33,7 @@ export type EventCombinedClientProps = Readonly<{
     buttonText?: string;
     emptyMessage?: string;
     className?: string;
+    calendarContext: EventCollectionHydration['calendarContext'];
 }>;
 export type EventCombinedIslandClientProps = EventCombinedInteractiveIslandProps;
 /**

package/dist/_dts/blocks/src/system/runtime/nodes/events/EventCombined.interactive.d.ts

@@ -52,6 +52,7 @@ export declare const eventCombinedBlockRuntime: Readonly<{
         buttonText?: string;
         emptyMessage?: string;
         className?: string;
+        bookingTimeZone?: string;
     }>) => Readonly<{
         display: EventCombinedDisplay;
         hydration: Readonly<{
@@ -61,6 +62,14 @@ export declare const eventCombinedBlockRuntime: Readonly<{
             eventSurface: import("../../..").EventSurfaceScope;
             filterEventPresets: string | null;
             scheduleScope: import("../../..").EventScheduleScope;
+            calendarContext: Readonly<{
+                timeZone: import("../../../../../../core/src/index").BookingTimeZone;
+                initialToday: Readonly<{
+                    year: number;
+                    month: number;
+                    day: number;
+                }>;
+            }>;
         }>;
     }>;
     contracts: Readonly<{
@@ -97,6 +106,7 @@ export declare const eventCombinedBlockRuntime: Readonly<{
                 buttonText?: string;
                 emptyMessage?: string;
                 className?: string;
+                bookingTimeZone?: string;
             }>) => unknown;
             decode: (input: unknown) => import("../../../../contracts").DecodeResult<Readonly<{
                 events?: import("../event-registration").PublicEvent[] | null;
@@ -130,6 +140,7 @@ export declare const eventCombinedBlockRuntime: Readonly<{
                 buttonText?: string;
                 emptyMessage?: string;
                 className?: string;
+                bookingTimeZone?: string;
             }>>;
         }>;
         render: Readonly<{
@@ -142,6 +153,14 @@ export declare const eventCombinedBlockRuntime: Readonly<{
                     eventSurface: import("../../..").EventSurfaceScope;
                     filterEventPresets: string | null;
                     scheduleScope: import("../../..").EventScheduleScope;
+                    calendarContext: Readonly<{
+                        timeZone: import("../../../../../../core/src/index").BookingTimeZone;
+                        initialToday: Readonly<{
+                            year: number;
+                            month: number;
+                            day: number;
+                        }>;
+                    }>;
                 }>;
             }>) => unknown;
             decode: (input: unknown) => import("../../../../contracts").DecodeResult<Readonly<{
@@ -153,6 +172,14 @@ export declare const eventCombinedBlockRuntime: Readonly<{
                     eventSurface: import("../../..").EventSurfaceScope;
                     filterEventPresets: string | null;
                     scheduleScope: import("../../..").EventScheduleScope;
+                    calendarContext: Readonly<{
+                        timeZone: import("../../../../../../core/src/index").BookingTimeZone;
+                        initialToday: Readonly<{
+                            year: number;
+                            month: number;
+                            day: number;
+                        }>;
+                    }>;
                 }>;
             }>>;
         }>;
@@ -176,6 +203,14 @@ export declare const eventCombinedInteractiveIslandPropsCodec: Readonly<{
                 eventSurface: import("../../..").EventSurfaceScope;
                 filterEventPresets: string | null;
                 scheduleScope: import("../../..").EventScheduleScope;
+                calendarContext: Readonly<{
+                    timeZone: import("../../../../../../core/src/index").BookingTimeZone;
+                    initialToday: Readonly<{
+                        year: number;
+                        month: number;
+                        day: number;
+                    }>;
+                }>;
             }>;
         }>>;
     }>) => unknown;
@@ -196,6 +231,14 @@ export declare const eventCombinedInteractiveIslandPropsCodec: Readonly<{
                 eventSurface: import("../../..").EventSurfaceScope;
                 filterEventPresets: string | null;
                 scheduleScope: import("../../..").EventScheduleScope;
+                calendarContext: Readonly<{
+                    timeZone: import("../../../../../../core/src/index").BookingTimeZone;
+                    initialToday: Readonly<{
+                        year: number;
+                        month: number;
+                        day: number;
+                    }>;
+                }>;
             }>;
         }>>;
     }>>;

package/dist/_dts/blocks/src/system/runtime/nodes/events/domain/capacity.d.ts

@@ -0,0 +1,164 @@
+import type { PublicEvent, PublicEventAttendanceMode, PublicEventAttendanceModeAvailability } from '../../../../blocks/events/shared/types';
+/**
+ * The four fields capacity maths needs. Satisfied by a `PublicEvent`, by the
+ * wizard's `RegistrationEvent`, and by a single attendance-mode availability
+ * row, so one helper can answer for the whole event or for one mode.
+ */
+export type EventCapacitySource = Pick<PublicEvent, 'capacity' | 'registeredCount' | 'availableSpots' | 'waitlistEnabled'>;
+export type EventAvailability = {
+    /** Remaining spots. `null` when the event has no capacity cap. */
+    available: number | null;
+    /** True when the event has a cap and no spots remain. */
+    isFull: boolean;
+};
+/**
+ * Compute remaining spots for an event from `availableSpots` with a fallback
+ * to `capacity - registeredCount`. Returns `{ available: null, isFull: false }`
+ * for uncapped events so call sites can render no capacity indicator at all.
+ *
+ * The single source of truth for capacity math across event cards, agenda
+ * rows, and timetable cells — keep wording variations in the call sites.
+ */
+export declare function getEventAvailability(event: EventCapacitySource): EventAvailability;
+type EventWithAttendanceModes = EventCapacitySource & {
+    attendanceModes?: readonly PublicEventAttendanceModeAvailability[] | null;
+};
+/**
+ * Pick the capacity row a booking decision should read: the selected
+ * attendance mode's availability when the visitor has chosen one and the
+ * event publishes it, otherwise the event-level aggregate.
+ *
+ * The mode row is used wholesale. A mode with `capacity: null` on a capped
+ * event is uncapped *by design*: the registration write path applies the
+ * same rule via `getEffectiveOccurrenceCapacityForAttendanceMode`, so falling
+ * back to the event's `availableSpots` here would block bookings the server
+ * accepts. (Waitlist claims are still occurrence-scoped; see issue 1377.)
+ */
+export declare function selectEventCapacitySource(event: EventWithAttendanceModes, attendanceMode?: PublicEventAttendanceMode | null): EventCapacitySource;
+/**
+ * Whether the visitor's next step is the waitlist: the source is full *and*
+ * a waitlist is open. The one place this is decided — cards, rows, the
+ * wizard's steps and its action bar all route through here so they agree,
+ * including for producers that omit `availableSpots` and rely on the
+ * `capacity - registeredCount` fallback.
+ */
+export declare function canJoinEventWaitlist(event: EventWithAttendanceModes, options?: {
+    attendanceMode?: PublicEventAttendanceMode | null;
+}): boolean;
+/**
+ * Remaining places at or below which an event reads as scarce and the exact
+ * count is worth showing. Above it, no number is shown at all: "147 places
+ * left" is not something a visitor acts on, and it is the figure most likely
+ * to be stale on a cached page.
+ *
+ *   max( min(3, ceil(capacity * 0.25)), ceil(capacity * 0.05) )
+ *
+ * The 25% arm stops small groups shouting early (3 of 4 is not urgency); the
+ * 5% floor stops large events staying silent until three remain.
+ * capacity 4 -> 1, 12 -> 3, 40 -> 3, 100 -> 5, 200 -> 10.
+ */
+export declare function lowCapacityThreshold(capacity: number): number;
+/**
+ * The remaining-places state every surface renders from. `open` deliberately
+ * carries no count: nothing should show one above the threshold, and logic
+ * that needs the number (quantity caps) reads {@link getEventAvailability}.
+ */
+export type RemainingPlaces = {
+    kind: 'unlimited';
+} | {
+    kind: 'open';
+} | {
+    kind: 'low';
+    remaining: number;
+} | {
+    kind: 'full';
+    waitlist: boolean;
+};
+export declare function getRemainingPlaces(source: EventCapacitySource): RemainingPlaces;
+export type RemainingPlacesWording = Readonly<{
+    /** Label when full with no waitlist. Defaults to "Full". */
+    full?: string;
+    /** Label when full with a waitlist open. Defaults to "Waitlist". */
+    waitlist?: string;
+    /** "2 left" instead of "2 places left", for pills and timetable cells. */
+    compact?: boolean;
+}>;
+/**
+ * The one place a remaining-places count becomes text. Returns `null` when
+ * nothing should be shown: uncapped events, and capped events above the
+ * scarcity threshold. Surfaces that need their own full-state wording pass
+ * it in rather than re-deriving the count.
+ */
+export declare function formatRemainingPlaces(source: EventCapacitySource, wording?: RemainingPlacesWording): string | null;
+/**
+ * Ticket types publish only what is left, never a total, so the capacity
+ * threshold cannot apply. The absolute arm of {@link lowCapacityThreshold}
+ * is used on its own: the count shows at three or fewer, otherwise nothing.
+ */
+export declare const TICKET_TYPE_LOW_COUNT = 3;
+export declare function formatTicketTypeRemaining(remainingCapacity: number | null): string | null;
+/** Total capacity as copy ("12 places"), for detail surfaces that state the size of an event. */
+export declare function formatTotalCapacity(capacity: number | null): string | null;
+/**
+ * Three-state availability status for compact boards and pills.
+ * - `available`: uncapped, or above the scarcity threshold. No label.
+ * - `filling`: at or below {@link lowCapacityThreshold}. Label is the compact count.
+ * - `waitlist`: full. Label reflects whether a waitlist is open.
+ */
+export type EventAvailabilityStatus = 'available' | 'filling' | 'waitlist';
+export type EventAvailabilityDetail = {
+    status: EventAvailabilityStatus;
+    /** Remaining spots. `null` when the event has no capacity cap. */
+    available: number | null;
+    isFull: boolean;
+    /** Short pill label, e.g. "2 left", "Waitlist", "Full". `null` when nothing should show. */
+    label: string | null;
+};
+export declare function getEventAvailabilityStatus(event: HybridEventCapacitySource): EventAvailabilityDetail;
+/**
+ * An event as the browse surfaces see it: the aggregate capacity fields plus
+ * the delivery mode and the per-mode rows. `PublicEvent` satisfies it.
+ */
+export type HybridEventCapacitySource = EventWithAttendanceModes & {
+    deliveryMode?: PublicEvent['deliveryMode'];
+};
+/** Remaining places for each side of a hybrid event. */
+export type HybridRemainingPlaces = Readonly<{
+    inPerson: RemainingPlaces;
+    online: RemainingPlaces;
+}>;
+/**
+ * Per-mode remaining places for a hybrid event, or `null` when the event is
+ * not hybrid or does not publish both rows — in which case the aggregate is
+ * all there is and the existing single-label helpers apply.
+ */
+export declare function getHybridAvailability(event: HybridEventCapacitySource): HybridRemainingPlaces | null;
+/**
+ * The capacity row a whole-event decision should read: the most open
+ * attendance mode of a hybrid event, otherwise the aggregate. A hybrid event
+ * is sold out only when both of its modes are, and its waitlist is reachable
+ * when either full mode has one open.
+ */
+export declare function selectMostOpenCapacitySource(event: HybridEventCapacitySource): EventCapacitySource;
+/** True when no attendance mode has room. Hybrid-aware; use this for sold-out decisions. */
+export declare function isEventFull(event: HybridEventCapacitySource): boolean;
+/**
+ * True when the event is full on every mode and at least one of those full
+ * modes has a waitlist open. An event with a mode still bookable is not a
+ * waitlist prospect: it should send the visitor to that mode instead.
+ */
+export declare function canJoinEventWaitlistOnAnyMode(event: HybridEventCapacitySource): boolean;
+/**
+ * The browse-surface label for an event's remaining places. Single-mode
+ * events get exactly the aggregate label {@link formatRemainingPlaces}
+ * produces, and so does a hybrid event whose two modes tell the same story.
+ * When the modes differ, both sides are named: "available" on a card is a
+ * promise the registration wizard would otherwise have to break.
+ *
+ * Hybrid examples, in person full with 3 online places left:
+ *   default                -> "Online: 3 places left · In person: Full"
+ *   { full: 'Sold out' }   -> "Online: 3 places left · In person: Sold out"
+ *   { compact: true }      -> "Online: 3 left"
+ */
+export declare function formatEventRemainingPlaces(event: HybridEventCapacitySource, wording?: RemainingPlacesWording): string | null;
+export {};

package/dist/_dts/blocks/src/system/runtime/nodes/events/domain/cta.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Booking call-to-action resolution for events: where an event links to and
+ * what the button says. Sold-out and waitlist decisions come from capacity.ts
+ * so cards, rows and the wizard never disagree.
+ */
+import type { PublicEvent } from '../../../../blocks/events/shared/types';
+export type ResolvedEventCta = {
+    label: string;
+    href: string;
+    external: boolean;
+    /**
+     * True when no booking CTA should render (e.g. sold out with no waitlist).
+     * This does NOT mean the event is unreachable: cards and rows link the
+     * title to the event page regardless, so a hidden CTA is never a dead end.
+     */
+    hidden: boolean;
+};
+export declare function resolveEventHref(event: PublicEvent): string;
+export declare function resolveEventLinkProps(event: PublicEvent): {
+    href: string;
+    target?: '_blank';
+    rel?: string;
+};
+/**
+ * Resolve the CTA state for an event.
+ * Shared by EventCard and EventCompactRow to keep sold-out, registration-closed,
+ * and course-specific defaults consistent.
+ */
+export declare function resolveEventCta(event: PublicEvent, buttonText?: string | null): ResolvedEventCta;

package/dist/_dts/blocks/src/system/runtime/nodes/events/domain/dates.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Date and time presentation for events: the single place an event's
+ * timestamps become strings or date buckets. Calendar-grid primitives are
+ * re-exported from @riverbankcms/calendar so block code has one import.
+ */
+import type { PublicEvent } from '../../../../blocks/events/shared/types';
+export { DAY_NAMES, MONTH_NAMES } from '../../../../../../../calendar/src/index';
+export type { WeekStart } from '../../../../../../../calendar/src/index';
+type DateTimeFormatOptions = {
+    /** When omitted, runtime local timezone is used. */
+    timeZone?: string | null;
+    locale?: string;
+};
+/**
+ * Format date for display.
+ * Returns: "Monday, January 15, 2025"
+ */
+export declare function formatDate(isoTimestamp: string, options?: DateTimeFormatOptions): string;
+/**
+ * Format time for display.
+ * Returns: "10:00 AM"
+ */
+export declare function formatTime(isoTimestamp: string, options?: DateTimeFormatOptions): string;
+export declare function formatEventDateParts(args: {
+    startsAt: string;
+    endsAt: string;
+    timeZone?: string | null;
+    locale?: string;
+}): {
+    date: string;
+    timeRange: string;
+};
+export type EventCompactDateRail = Readonly<{
+    weekday: string;
+    day: string;
+    month: string;
+    label: string;
+}>;
+export declare function formatEventCompactDateRail(isoTimestamp: string, options?: DateTimeFormatOptions): EventCompactDateRail;
+export { addDays, addMonths, buildCalendarViewport, formatCalendarTitle, formatDateKey, getEndOfMonth, getMonthCalendarDays, getOrderedDayNames, getStartOfMonth, getWeekCalendarDays, getWeekCalendarDayTuple, isToday, MAX_EVENTS_PER_DAY, shiftCalendarAnchorDate, } from '../../../../../../../calendar/src/index';
+export type { CalendarDate, CalendarViewport, CalendarViewportKind, MonthCalendarViewport, WeekCalendarDays, WeekCalendarViewport, } from '../../../../../../../calendar/src/index';
+/**
+ * Group events by their local date (YYYY-MM-DD key in each event's own
+ * timezone). Thin domain wrapper over `groupItemsByDate` from the calendar
+ * package; preserves the historical `Map<string, PublicEvent[]>` shape.
+ */
+export declare function groupEventsByDate(events: PublicEvent[], calendarTimeZone: string): Map<string, PublicEvent[]>;

package/dist/_dts/blocks/src/system/runtime/nodes/events/domain/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Event domain helpers: pure functions that turn event data into strings,
+ * numbers, hrefs and decisions. One file per concept, no React.
+ *
+ * If you are about to format a date, a price, a name, a capacity count or a
+ * CTA for an event inline in a component, the function belongs here instead.
+ * Components in ../shared and the registration wizard import from this barrel.
+ */
+export * from './capacity';
+export * from './cta';
+export * from './dates';
+export * from './destination';
+export * from './people';
+export * from './pricing';