@seatlayer/js 0.63.1 → 0.64.0

package/dist/index.d.ts

@@ -115,6 +115,22 @@ interface SelectedObjectUnavailableEvent {
      | 'exhausted';
     code?: string;
 }
+/**
+ * Observed when the held bearer is replaced by a newly minted one.
+ *
+ * Exists for exactly one caller today: a Performance Group session owns the
+ * holds it created, so a re-mint has to ADOPT them onto the new session before
+ * anything else is allowed to speak to the group. See
+ * `PerformanceGroupApi`'s adopt handshake.
+ */
+interface BuyerAccessRenewalEvent {
+    /** The bearer that was in hand before the renewal. Never null when observed. */
+    previousToken: string;
+    /** The bearer that just replaced it. */
+    token: string;
+    reason: BuyerAccessRefreshReason;
+}
+type BuyerAccessRenewalObserver = (event: BuyerAccessRenewalEvent) => void | Promise<void>;
 interface BuyerAccessContextOptions {
     provider?: BuyerAccessTokenProvider;
     /** One-shot escape hatch for hosts that already own the token lifecycle. */
@@ -152,6 +168,21 @@ declare class BuyerAccessContext {
      * held `configured` true. Found against a live worker in the M9 pass.
      */
     get configured(): boolean;
+    /**
+     * Observe bearer rotation: "the token changed from X to Y".
+     *
+     * The observer is awaited INSIDE `#renew`, which is single-flight, so no
+     * `authorization()` caller can obtain the new bearer until the observer has
+     * settled. That serialization is the whole point — a Performance Group must
+     * finish adopting its holds onto the new session before any other group
+     * request goes out on it.
+     *
+     * The observer never sees the very first acquisition (there is no previous
+     * token to inherit from) and never sees a no-op re-issue of the same string.
+     * Its rejection is swallowed here: it belongs to the caller that registered
+     * it, and that caller latches its own terminal state.
+     */
+    onRenewed(observer: BuyerAccessRenewalObserver | undefined): void;
     /** Set once a state arrives that refreshing cannot clear. */
     get unavailable(): BuyerAccessUnavailableEvent | null;
     /** True while a usable bearer is held (ignores skew). */
@@ -1979,6 +2010,8 @@ declare class SeatPicker implements GaPromptPicker {
     /** Original host pricing, kept separate from live server offer overrides. */
     private readonly hostPricing;
     private readonly performanceGroup;
+    /** Structural (not CSS) removal of per-performance money — see pickerInternal. */
+    private readonly suppressPricing;
     /** @internal */ root: HTMLDivElement | null;
     private mapHost;
     private rendered;
@@ -2038,6 +2071,9 @@ declare class SeatPicker implements GaPromptPicker {
     private lastMapPoint;
     private tipEl;
     private tipPos;
+    /** True while a TAPPED seat card is held open (touch has no hover to lose). */
+    private tipPinned;
+    private lastPointerType;
     private confirmEl;
     private confirmSeat;
     private tableDialogEl;
@@ -2340,8 +2376,6 @@ declare class SeatPicker implements GaPromptPicker {
     /** Complete buyer-visible price range, including every ticket tier and
      * tier-specific host override. */
     private catPriceRange;
-    /** Derive category price bands without hiding the upper end of tier ranges. */
-    private priceBands;
     /** Build the compact price selector in the panel header. Choosing a band both
      *  filters availability and smoothly frames the matching seats on the map. */
     private buildPriceFilter;
@@ -2389,6 +2423,13 @@ declare class SeatPicker implements GaPromptPicker {
     private sectionCardOnView;
     /** Fraction of the focused section's on-screen bbox covered by the card. */
     private sectionCardCoverage;
+    /**
+     * The polite-live sentence for a partly-available seat, or '' for any other.
+     *
+     * Focus is the only moment a keyboard buyer gets: the night strip lives on a
+     * hover surface they never reach, so the same facts arrive here as prose.
+     */
+    private markedSeatAnnouncement;
     /** aria-live readout when keyboard focus lands on a seat. */
     private announceSeat;
     private showTableDialog;
@@ -2499,6 +2540,16 @@ declare class SeatPicker implements GaPromptPicker {
      */
     private detectBooked;
     private showBooked;
+    /**
+     * A Performance Group hold settled, told to us by the WRAPPER rather than by
+     * a socket (§8: this surface has no realtime feed). `detectBooked` waits for
+     * the controller's own hold to settle and for a group it never does — the
+     * collapsed projection only speaks free/blocked — so a booking completed on
+     * the host's server was invisible and the picker sat on "Continue to
+     * checkout" forever. `booked` runs the ordinary success path (overlay +
+     * `onBooked`); `lost` is the reset a hold expiry does. Either way the hold is
+     * dropped, so the CTA cannot offer a checkout that cannot happen. */
+    /** @internal */ notifyGroupSettled(outcome: 'booked' | 'lost'): void;
     /**
      * The seats are held. Send the buyer wherever this picker's `checkout` option
      * says they go.
@@ -2540,17 +2591,27 @@ declare class SeatPicker implements GaPromptPicker {
     }): void;
     private placeTooltip;
     /**
-     * Row label without the redundant section prefix. Charts commonly name row
-     * objects "104-A" while the Section column already shows "104" — so the Row
-     * cell repeats the section and, in the compact hover card, truncates to
-     * "10…". Strip a leading "<section><sep>" so Row reads a clean "A". Only when
-     * the prefix is exact (won't touch "1040-A" under section "104"); otherwise
-     * the label is shown verbatim.
+     * The Performance Group night strip for a two-tone seat.
+     *
+     * A marked seat is server-status blocked and stays unselectable — the mark is
+     * the only place the buyer can learn that it is blocked by ONE night rather
+     * than by all of them, and which one. '' for every other seat, and for a
+     * group whose wrapper did not supply the nights.
      */
-    /** Buyer-facing type word for the row/table key label — the designer's
-     *  per-object "Displayed type" override, or the default "Row". */
-    private rowTypeWord;
+    private nightStripFor;
+    /** Close a tapped-open card. Safe to call when nothing is pinned. */
+    private unpinTooltip;
     private updateTooltip;
+    /**
+     * Push the wrapper's current seat marks at the renderer.
+     *
+     * PULLED from the seam rather than pushed into the widget, and called
+     * immediately AFTER a status batch has been applied — the two must land on
+     * the same tick, in that order, or a repaint from the status pass wipes the
+     * two-tone paint. Labels are resolved here because only the controller knows
+     * the label→id mapping, and the wrapper must never learn engine ids.
+     */
+    private syncSeatMarks;
     getSelection(): PickerSeat[];
     /** Select free objects by engine id or public label. */
     selectObjects(objects: string[]): PickerSeat[];
@@ -2558,8 +2619,19 @@ declare class SeatPicker implements GaPromptPicker {
     deselectObjects(objects: string[]): void;
     /** Clear every unheld selection. */
     clearSelection(): void;
+    /** @internal Display colour of the first sellable category. ASKED OF THE RENDERER: colourblind-safe mode remaps hues there and never touches the document. */ categoryLegendColor(): string;
     /** @internal */ refreshAvailability(): Promise<void>;
     /** @internal */ refreshPerformanceGroupComposition(): void;
+    /**
+     * @internal Adopt a hold this picker did not create.
+     *
+     * The Performance Group wrapper recovers an operation id from storage on
+     * reload and learns the hold behind it BEFORE this picker's own
+     * remembered-hold path could know one exists. Nothing happens when a hold is
+     * already live — the two restore paths must not race each other into a
+     * double resume.
+     */
+    adoptRestoredHold(holdId: string): Promise<void>;
     /** Select every selectable object in the named categories. */
     selectCategories(categoryKeys: string[]): PickerSeat[];
     /** Deselect every selected object in the named categories. */
@@ -2770,7 +2842,6 @@ declare class SeatPicker implements GaPromptPicker {
      */
     private showAccessPanel;
     private dismissAccessPanel;
-    private accessCopy;
     destroy(): void;
 }
 
@@ -2787,6 +2858,8 @@ interface PerformanceGroupDescriptor {
     timezone: string | null;
     inventoryModelVersion: 2;
     performanceCount: number;
+    /** Present when the server versions the inclusion set. See {@link PerformanceGroupAvailability}. */
+    revision?: string;
     performances: Array<{
         position: number;
         eventKey: string;
@@ -2814,6 +2887,60 @@ interface PerformanceGroupOperationEvent {
     state: PerformanceGroupOperationState;
     decision: 'commit' | 'abort' | null;
 }
+/**
+ * What the wrapper needs to render §12's recovery wording without inventing
+ * its own state machine. `pending` is inert-and-wait; `failed` is the terminal
+ * state whose ABSENCE used to leave the picker aria-busy forever (H7).
+ */
+type PerformanceGroupRecoveryState = {
+    kind: 'idle';
+} | {
+    kind: 'pending';
+    operationId: string;
+    phase: PerformanceGroupOperationState | 'unknown';
+    /** True once the recovery has run long enough to owe the buyer an explanation. */
+    longRunning: boolean;
+    reference: string;
+} | {
+    kind: 'failed';
+    operationId: string;
+    reference: string;
+    reason: 'deadline' | 'request_failed' | 'session_adopt_failed';
+    /** False when the same operation can no longer be polled (adopt failure). */
+    retryable: boolean;
+};
+/** Group-level sale state, surfaced from `/objects` rather than dropped (M11). */
+interface PerformanceGroupAvailability {
+    state: 'active' | 'closing' | 'closed' | 'archived';
+    salesClosed: boolean;
+    revision: string | null;
+    /** True when this read's revision differs from the one first observed. */
+    revisionChanged: boolean;
+    /**
+     * Same-seat only: for every seat that is free on SOME performances, the
+     * eventKeys (chronological) where it is NOT. Seats free everywhere or nowhere
+     * are absent, which is what keeps this small on a 20,000-seat chart.
+     *
+     * The collapsed `seats` map still says `blocked` for all of these — the map
+     * must never offer a seat the buyer cannot have on every night. This is the
+     * EXPLANATION for that "no", and nothing more.
+     */
+    partial: Record<string, string[]>;
+    /** How many seats the collapsed view reports as bookable on every night. */
+    freeCount: number;
+    /** How many are blocked on every night — i.e. not explained by `partial`. */
+    blockedCount: number;
+}
+/** Raised instead of speaking to the network after `destroy()`. */
+declare class PerformanceGroupDestroyedError extends Error {
+    constructor();
+}
+/**
+ * The "short operation reference" §12 asks us to read out loud. It has to be
+ * sayable over the phone, so it is the tail of the id, upper-cased — never the
+ * whole `pghop_…` uuid.
+ */
+declare function shortOperationReference(operationId: string): string;
 
 interface PerformanceGroupSeatAllocation {
     eventKey: string;
@@ -2829,12 +2956,39 @@ interface PerformanceGroupCheckoutHandoff {
     seatLabels: string[];
     /** Present for per-performance selection. Prices and child hold IDs remain server-only. */
     allocations?: PerformanceGroupSeatAllocation[];
+    /**
+     * `held` until the coordinator says otherwise; `booked` once the operation
+     * settles that way. A group has no socket (§8), so this only ever becomes
+     * `booked` through the transport's settlement watch.
+     */
+    bookingState?: 'held' | 'booked';
+}
+/** What the wrapper is showing the buyer right now, for host telemetry. */
+interface PerformanceGroupStatusEvent {
+    kind: 'idle' | 'pending' | 'recovery_failed' | 'sales_closed' | 'revision_changed';
+    message: string;
+    /** The short operation reference from §12, when one applies. */
+    reference?: string;
 }
 interface PerformanceGroupPickerOptions {
     container: string | HTMLElement;
     performanceGroup: string;
     /** `same_seat` renders one shared choice; `per_performance` renders one chart with date tabs. */
     selectionMode?: PerformanceGroupSelectionMode;
+    /**
+     * Offer the buyer a way out of same-seat selection.
+     *
+     * Default false. A same-seat map hides a real outcome: a seat free on two of
+     * three nights is shown as unavailable, and without this option the only
+     * thing to say about it is "pick a different seat". With it on, the seat's
+     * card and the "Your seats" pane carry one quiet action that re-opens the
+     * same group as a night-by-night choice, in place.
+     *
+     * Requires `numberOfPlacesToSelect`, because per-performance selection is
+     * defined by a party size and the switch must not land the buyer in a mode
+     * the transport cannot submit.
+     */
+    allowSelectionModeSwitch?: boolean;
     apiBase?: string;
     buyerAccessTokenProvider?: BuyerAccessTokenProvider;
     buyerAccessToken?: string | BuyerAccessToken;
@@ -2871,8 +3025,16 @@ interface PerformanceGroupPickerOptions {
     onHoldChange?: (handoff: PerformanceGroupCheckoutHandoff | null) => void;
     onCheckout?: (handoff: PerformanceGroupCheckoutHandoff) => void;
     onHoldExpired?: () => void;
+    /**
+     * The whole package is booked. Fires ONCE, from the settlement watch, with
+     * the same handoff shape plus `bookingState: 'booked'`.
+     */
+    onBooked?: (handoff: PerformanceGroupCheckoutHandoff) => void;
     onAccessExpired?: (event: BuyerAccessExpiredEvent) => void;
     onAccessUnavailable?: (event: BuyerAccessUnavailableEvent) => void;
+    onStatusChange?: (event: PerformanceGroupStatusEvent) => void;
+    /** Fired after the buyer moves between selection modes in place. */
+    onSelectionModeChange?: (mode: PerformanceGroupSelectionMode) => void;
     onError?: (error: unknown) => void;
 }
 declare class PerformanceGroupPicker {
@@ -2884,35 +3046,171 @@ declare class PerformanceGroupPicker {
     private root;
     private innerHost;
     private tabsHost;
+    private prevButton;
+    private nextButton;
     private heldSummary;
     private live;
+    private statusHost;
+    private statusCopy;
+    private statusAction;
     private rendered;
     private destroyed;
     private continued;
     private switchingPerformance;
     private operationPending;
+    private recovery;
+    private availability;
     private activePerformanceKey;
     private readonly selectionsByEvent;
     private readonly validByEvent;
     private refreshingComposition;
     private activeHandoff;
+    private readonly panelId;
+    private selectionModeValue;
+    private progressHost;
+    private legendHost;
+    private paneHost;
+    /** Labels pushed at the renderer on the last pull, so departures clear. */
+    private markedLabels;
+    private holdTicker;
+    private switchingMode;
+    /** Latched at the first `booked`, so the callback and the copy fire once. */
+    private booked;
     constructor(options: PerformanceGroupPickerOptions);
+    /**
+     * The mode the buyer is ACTUALLY in.
+     *
+     * Not `options.selectionMode`: with `allowSelectionModeSwitch` the buyer can
+     * change it, and every derived surface — tabs, pane, submission state, the
+     * handoff's `selectionMode` — has to follow the live value or the wrapper
+     * starts describing a session that no longer exists.
+     */
+    private get mode();
+    get selectionMode(): PerformanceGroupSelectionMode;
     get descriptor(): PerformanceGroupDescriptor | null;
     get currentHold(): PerformanceGroupCheckoutHandoff | null;
     render(): Promise<this>;
+    /**
+     * Everything around the map.
+     *
+     * Rebuilt wholesale when the buyer switches selection mode, because the
+     * difference between the two modes is not a class on one element — the tab
+     * bar appears, the summary and the map helper change what they claim, and the
+     * "Your selection" pane changes what it is a list OF. Patching those in place
+     * is how a surface ends up half-describing the mode it used to be in.
+     */
+    private buildChrome;
+    private mountPicker;
+    private performanceCards;
+    /** Chronological nights with the SAME date formatting the chrome uses. */
+    private nights;
+    /**
+     * The marks the picker should be showing right now.
+     *
+     * Pulled by SeatPicker straight after it applies a status batch. Every label
+     * currently in `partial` gets its mark; every label that has LEFT `partial`
+     * since the last pull gets an explicit null, because `setSeatMarks` merges
+     * and a dropped label would otherwise keep its two-tone paint forever.
+     */
+    private seatMarks;
+    /** Per-night picks for the picker's "Your seats" pane (per-performance). */
+    private nightSummary;
+    /**
+     * The three-step strip. "Review" becomes current the moment a hold commits —
+     * that is the only point at which there is something to review, and it is the
+     * point the buyer most needs told that the seats are actually theirs.
+     */
+    private syncProgress;
+    /** The map's ONE availability key. Hidden with the map when the sale is shut. */
+    private syncLegend;
+    /**
+     * The colour the "available" swatch has to match.
+     *
+     * Asked of the RENDERER, not the document: colourblind-safe mode remaps hues
+     * inside the renderer and never touches `doc.categories[].color`, so reading
+     * the document would print a key that disagrees with the map for exactly the
+     * buyers who most depend on the key.
+     */
+    private categoryColor;
+    /**
+     * "Your selection" — one line per performance, and a total ONLY once the
+     * server has committed a hold and told us what it costs.
+     */
+    private syncPane;
+    /**
+     * The package total, from the SERVER's own hold lines.
+     *
+     * Null until a hold commits. There is no browser-side per-performance price
+     * for a group (the transport suppresses single-event pricing on purpose), so
+     * anything computed before commit would be a quote we invented — and a quote
+     * the buyer could reasonably hold us to.
+     */
+    private heldTotal;
+    /** One tick a second while a hold is live, so the countdown line is true. */
+    private syncHoldTicker;
+    /**
+     * Re-open the same group in the other selection mode, in place.
+     *
+     * Refused while an operation is undecided or a hold exists: §12 forbids a
+     * competing action over an outcome the coordinator still owns, and the
+     * transport refuses too, so this is belt and braces on the same rule.
+     */
+    private switchSelectionMode;
     release(): Promise<void>;
     close(): void;
     destroy(): void;
+    /**
+     * Every buyer-facing string in this wrapper, through the shared catalog.
+     *
+     * A host `messages` entry still wins — it is checked first here AND it is
+     * installed as a global override — so integrator copy keeps working while
+     * the default is a real translation rather than a hard-coded English literal.
+     */
     private copy;
     private performanceTabs;
+    private tabButtons;
+    private tabKeydown;
+    private stepPerformance;
     private submissionState;
+    /** §12: no second HOLD action while an outcome is unknown or sale is shut. */
+    private holdBlocked;
     private selectionChanged;
     private selectionValidityChanged;
     private refreshComposition;
     private tabState;
     private updateTabs;
     private switchPerformance;
+    /**
+     * Lock without `inert`.
+     *
+     * `inert` removes the whole subtree from the a11y tree AND blurs whatever the
+     * buyer had focused, so a screen-reader user mid-selection was dropped to the
+     * top of the document with no announcement. `aria-disabled` plus a
+     * pointer-events block keeps the focused seat where it is and readable, and
+     * the status region below carries the reason.
+     */
+    private setInteractionLocked;
+    private announce;
+    private showStatus;
+    private clearStatus;
     private operationChanged;
+    /**
+     * The package is booked.
+     *
+     * Everything that was true only while a hold was RUNNING stops: the clock,
+     * the "held together · mm:ss" line, and the checkout the buyer has already
+     * been through. What stays is the per-night summary — the answer to "what did
+     * I actually buy?" is the last thing to take away at the moment it becomes
+     * the only question left.
+     */
+    private bookingSettled;
+    /** The hold went away before it was booked — expiry, or an organizer release. */
+    private holdLost;
+    private recoveryChanged;
+    private retryRecovery;
+    private restoreOperation;
+    private availabilityChanged;
+    private reloadDescriptor;
     private handoff;
     private renderHeldAllocations;
     private resetPerPerformanceSelection;
@@ -2959,4 +3257,4 @@ interface AttachPickerFrameOptions {
  */
 declare function attachPickerFrame(iframe: HTMLIFrameElement, opts?: AttachPickerFrameOptions): () => void;
 
-export { ApiError, type AttachPickerFrameOptions, type BestAvailableResult, BuyerAccessContext, type BuyerAccessExpiredEvent, type BuyerAccessRefreshReason, type BuyerAccessToken, type BuyerAccessTokenProvider, BuyerAccessUnavailableError, type BuyerAccessUnavailableEvent, type BuyerAccessUnavailableReason, BuyerRealtimeClient, type BuyerRealtimeOptions, type CheckoutHandoff, type CheckoutLineItem, type CheckoutSessionResult, EmbeddedDesigner, type EmbeddedDesignerEventType, type EmbeddedDesignerMessage, type EmbeddedDesignerOptions, type GAAreaAvailability, type GAPromptRequest, type GaPromptTier, type HoldConflict, type HoldLineItem, type HoldResult, type OrderStatusResult, type PaymentOptionsReason, type PaymentOptionsResult, type PaymentProviderName, type PerformanceGroupCheckoutHandoff, type PerformanceGroupDescriptor, type PerformanceGroupHold, type PerformanceGroupHoldAllocation, type PerformanceGroupOperationEvent, type PerformanceGroupOperationState, PerformanceGroupPicker, type PerformanceGroupPickerOptions, type PerformanceGroupSeatAllocation, type PerformanceGroupSelectionMode, type Projection, type PubApiOptions, type RealtimeSink, type ResumedHoldResult, SEATING_CHART_CALLBACK_PROPS, SEATING_CHART_HANDLE_METHODS, SEATING_CHART_IDENTITY_PROPS, SEATING_CHART_VALUE_PROPS, type SaleState, SeatPicker, type SeatPickerBestAvailableOptions, type SeatPickerBuyerView, type SeatPickerBuyerViewOptions, type SeatPickerOptions, type SeatPickerPricing, type SeatPickerTheme, SeatingChart, type SeatingChartCallbackProp, type SeatingChartCallbacks, type SeatingChartHandle, type SeatingChartHandleMethod, type SeatingChartIdentityProp, type SeatingChartOptions, type SeatingChartValueProp, type SeatingChartValues, type SelectedObjectUnavailableEvent, type SelectedSeat, type StatusChange, type SubscribeTicket, type TicketOfferAvailability, type TicketOfferPrice, type TicketOfferSummary, attachPickerFrame, bindSeatingChartHandle, buildSeatingChartOptions, createBuyerAccessContext, createControllerSink, parseTicketOfferAvailability, ticketOfferPrices };
+export { ApiError, type AttachPickerFrameOptions, type BestAvailableResult, BuyerAccessContext, type BuyerAccessExpiredEvent, type BuyerAccessRefreshReason, type BuyerAccessToken, type BuyerAccessTokenProvider, BuyerAccessUnavailableError, type BuyerAccessUnavailableEvent, type BuyerAccessUnavailableReason, BuyerRealtimeClient, type BuyerRealtimeOptions, type CheckoutHandoff, type CheckoutLineItem, type CheckoutSessionResult, EmbeddedDesigner, type EmbeddedDesignerEventType, type EmbeddedDesignerMessage, type EmbeddedDesignerOptions, type GAAreaAvailability, type GAPromptRequest, type GaPromptTier, type HoldConflict, type HoldLineItem, type HoldResult, type OrderStatusResult, type PaymentOptionsReason, type PaymentOptionsResult, type PaymentProviderName, type PerformanceGroupAvailability, type PerformanceGroupCheckoutHandoff, type PerformanceGroupDescriptor, PerformanceGroupDestroyedError, type PerformanceGroupHold, type PerformanceGroupHoldAllocation, type PerformanceGroupOperationEvent, type PerformanceGroupOperationState, PerformanceGroupPicker, type PerformanceGroupPickerOptions, type PerformanceGroupRecoveryState, type PerformanceGroupSeatAllocation, type PerformanceGroupSelectionMode, type PerformanceGroupStatusEvent, type Projection, type PubApiOptions, type RealtimeSink, type ResumedHoldResult, SEATING_CHART_CALLBACK_PROPS, SEATING_CHART_HANDLE_METHODS, SEATING_CHART_IDENTITY_PROPS, SEATING_CHART_VALUE_PROPS, type SaleState, SeatPicker, type SeatPickerBestAvailableOptions, type SeatPickerBuyerView, type SeatPickerBuyerViewOptions, type SeatPickerOptions, type SeatPickerPricing, type SeatPickerTheme, SeatingChart, type SeatingChartCallbackProp, type SeatingChartCallbacks, type SeatingChartHandle, type SeatingChartHandleMethod, type SeatingChartIdentityProp, type SeatingChartOptions, type SeatingChartValueProp, type SeatingChartValues, type SelectedObjectUnavailableEvent, type SelectedSeat, type StatusChange, type SubscribeTicket, type TicketOfferAvailability, type TicketOfferPrice, type TicketOfferSummary, attachPickerFrame, bindSeatingChartHandle, buildSeatingChartOptions, createBuyerAccessContext, createControllerSink, parseTicketOfferAvailability, shortOperationReference, ticketOfferPrices };