@fanfare-io/fanfare-sdk-react 0.17.0 → 0.19.0

package/dist/components/widgets/internal/timed-release-module.d.ts

@@ -1,5 +1,8 @@
+import { ClaimableSettlement, PreAuthSettlement } from '@fanfare-io/fanfare-sdk-core/experiences';
 import { TimedReleaseDisplayState } from '@fanfare-io/fanfare-sdk-core/internals';
+import { GrantedSelection, SelectionAvailability, SelectionChoice, SelectionDraft, SelectionOptions } from '@fanfare-io/fanfare-sdk-core/selections';
 import { ReadableAtom } from 'nanostores';
+import { SelectionCheckoutDetails } from '../../../lib/selection-display';
 import { OutcomeAction } from '../../compositions/outcome-panel';
 import { OutcomeReason } from '../../module';
 export interface TimedReleaseModuleProps {
@@ -7,14 +10,41 @@ export interface TimedReleaseModuleProps {
     sequencePhase: "enterable" | "participating" | "granted" | "ended";
     canEnter: boolean;
     canLeave: boolean;
-    onEnter: () => Promise<void>;
+    onEnter: (selection?: SelectionChoice) => Promise<void>;
     onLeave: () => Promise<void>;
     onComplete?: () => Promise<void>;
     isEntering: boolean;
     isLeaving: boolean;
     countdownTo?: Date;
     checkoutUrl?: string;
-    onCheckoutClick?: () => void;
+    /** Override checkout click handler (granted); carries the pair the grant resolved to. */
+    /**
+     * Activating the checkout CTA. Receives the pick the grant settled on, with the catalogue
+     * objects behind it, whenever the panel has loaded the catalogue that carries them.
+     */
+    onCheckoutClick?: (details?: SelectionCheckoutDetails) => void | Promise<void>;
+    /** The release captures a product choice at entry, so the entry branch renders the picker. */
+    selectionRequired?: boolean;
+    /** Bound by the widget against the journey; must be referentially stable. */
+    loadSelectionOptions?: () => Promise<SelectionOptions>;
+    /** The choice already recorded for this entry. */
+    recordedSelection?: SelectionChoice | null;
+    /** Live availability of the recorded pick. */
+    selectionAvailability?: SelectionAvailability;
+    /** Granted-state selection arm; a release resolves or awaits an assignment, never requires a pick. */
+    grantedSelection?: GrantedSelection;
+    /** How the win settles; selects the granted confirm label and payment affordance. */
+    settlement?: ClaimableSettlement | PreAuthSettlement;
+    /** Submits the granted pick or re-pick. */
+    onSelect?: (choice: SelectionChoice) => Promise<void>;
+    /** Locked copy for a resolved granted summary; "checkout" once checkout has started. */
+    selectionLockedReason?: "checkout" | "final";
+    /** Already-translated selection failure from the widget, rendered beside the acting control. */
+    selectError?: string | null;
+    /** Every local pick-surface transition, product-only drafts included; feeds the page-bridge event. */
+    onDraftChange?: (draft: SelectionDraft) => void;
+    /** The terminal was reached because the stock ran out, not because this entrant lost. */
+    stockDenied?: boolean;
     grant?: string;
     expiresAt?: number | Date;
     outcomeReason?: OutcomeReason;
@@ -24,7 +54,7 @@ export interface TimedReleaseModuleProps {
     isReentering?: boolean;
     className?: string;
 }
-export declare function TimedReleaseModule({ display$, sequencePhase, canEnter, canLeave, onEnter, onLeave, onComplete, isEntering, isLeaving, countdownTo, checkoutUrl, onCheckoutClick, grant: _grant, expiresAt, outcomeReason, outcomeAction, onReenter, isReentering, className, }: TimedReleaseModuleProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function TimedReleaseModule({ display$, sequencePhase, canEnter, canLeave, onEnter, onLeave, onComplete, isEntering, isLeaving, countdownTo, checkoutUrl, onCheckoutClick, grant: _grant, expiresAt, outcomeReason, outcomeAction, onReenter, isReentering, className, selectionRequired, loadSelectionOptions, recordedSelection, selectionAvailability, grantedSelection, settlement, onSelect, selectionLockedReason, selectError, stockDenied, onDraftChange, }: TimedReleaseModuleProps): import("react/jsx-runtime").JSX.Element | null;
 export declare namespace TimedReleaseModule {
     var displayName: string;
 }

package/dist/hooks/use-selection-options.d.ts

@@ -0,0 +1,22 @@
+import { SelectionOptions } from '@fanfare-io/fanfare-sdk-core/selections';
+export interface UseSelectionOptionsResult {
+    options: SelectionOptions | null;
+    isLoading: boolean;
+    error: Error | null;
+    /** Re-fetch; used by the sold-out auto-refetch and the handle's refresh(). */
+    refresh(): Promise<void>;
+}
+/**
+ * Fetches a selection catalogue on demand, once per loader identity.
+ *
+ * Nothing is cached across mounts, persisted, or deduped between callers: a
+ * catalogue carries live availability, so a second consumer of a stale copy would
+ * be shown a pick that is already gone. The hook never polls.
+ *
+ * A refetch keeps the previously loaded catalogue in `options` so the caller can
+ * hold its rendered grid rather than flashing back to a skeleton, and a standing
+ * `error` survives until the retry settles so the failure view does not flash the
+ * stale grid on its way back. Resolutions and rejections from a superseded
+ * request, or from one still in flight after unmount, are dropped.
+ */
+export declare function useSelectionOptions(load: (() => Promise<SelectionOptions>) | undefined): UseSelectionOptionsResult;