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

package/README.md

@@ -44,6 +44,72 @@ Customization has four levels of increasing specificity: `theme`, `variant`, `sl
 
 `slots` override targeted states while keeping the default widget flow. `children` receives `{ journey, view, snapshot, error, start, isStarting }` when you want to render the full state yourself.
 
+## Selection
+
+Some experiences capture which product and variant a consumer gets. `ExperienceWidget` renders that
+picker on its own, and the two building blocks behind it are exported so you can place them
+yourself:
+
+- `ProductSelector` — loads a catalogue through its `loadOptions` callback, renders the product
+  rows, the chosen product's option chips and the resolved variant, and reports a complete
+  `{ productId, variantId }` pair through `onSelectionChange`. Anything less than a complete pair
+  reports `null`. It never submits a selection itself.
+- `SelectionSummary` — a presentational read-out of a pick that has already been captured, with an
+  optional change affordance and the locked and unavailable copy.
+
+Prices arrive from the catalogue as exact strings and render in the widget's locale and the
+catalogue's `currencyCode`: on a product row when every variant of that product agrees on one
+amount, and on the resolved variant's own line beneath the chips. The formatter is internal — the
+public surface is exactly these two components plus their prop and handle types.
+
+Selection is configured per sequence, under either checkout arrangement. With merchant
+(`external`) checkout the widget records the pick and hands it to `onCheckoutClick` for the host to
+cart; with Fanfare (`internal`) checkout the granted panel continues into Fanfare's own checkout
+instead, under both checkout modes, `at_end` and `pre_auth`. Entry-time picking (choosing before you
+enter) is not yet available.
+
+`onCheckoutClick?: (details?: SelectionCheckoutDetails) => void | Promise<void>` carries the pick
+the grant settled on — `SelectionCheckoutDetails` is a root export and reads
+`{ selection, product, variant, currencyCode }`, the catalogue objects behind the pair so a host can
+map it onto its own catalogue by handle, SKU or option values. The argument is optional: a grant
+that settles without the widget having loaded the catalogue passes none, so a `() => void` handler
+still assigns and a `(details) => …` handler has to handle `details === undefined`.
+`GrantedPanelProps.onCtaClick` takes the same shape. Returning a promise is supported — a rejection
+returns the consumer to the checkout CTA with SDK-owned inline copy and reports the cause through
+`onError`, so a hand-off that never happened is never shown as started.
+
+Four integration tiers, in increasing specificity:
+
+1. **Default.** `ExperienceWidget` renders the modules, and the selection UI appears wherever the
+   experience captures a pick.
+2. **Slot override, keeping our pieces.** Override the `enterable`, `participating` or `granted`
+   slot with a render function and compose `ProductSelector`, `SelectionSummary` and `GrantedPanel`
+   directly. The selection methods live on the sequence the slot hands you as `sequence`, not on
+   `view` — `sequence.loadSelectionOptions()` fetches the catalogue and `sequence.select(choice)`
+   confirms. Not every arm of the sequence union carries them, so narrow with
+   `"loadSelectionOptions" in sequence` first. The view is rebuilt on every journey emission, so
+   `sequence.loadSelectionOptions` is a different function each time and passing it straight to
+   `loadOptions` re-fetches the catalogue; so is an arrow written inline in the slot function.
+   Render the slot through a named component (`granted: (props) => <GrantedSlot {...props} />`) and
+   hold a `useCallback` loader there that reads the journey's current sequence when it is called —
+   the widget wires its own picker exactly that way.
+3. **Standalone on your own page.** Import `ProductSelector` / `SelectionSummary` from the package
+   root and render them anywhere, driven by `useExperienceJourney`'s view. Both are self-contained
+   blocks themed through the ambient `--ff-*` variables and `ThemeProvider`, like every other
+   exported component.
+4. **Fully custom picker.** Render anything you like, then still call `view.sequence.select(choice)`
+   for a granted pick, or pass `selection` to `enter` / `bid` for an entry pick. `resolveVariantFromOptions`
+   and `isOptionValueSelectable` are importable from `@fanfare-io/fanfare-sdk-core/selections`, so a
+   custom UI resolves a choice exactly as the server does.
+
+The row and option-grid units inside `ProductSelector` are internal; a host that wants different
+row rendering uses tier 4.
+
+`loadOptions` must be referentially stable — a new function identity is a new loader and re-fetches
+the catalogue, so wrap it in `useCallback` or hoist it out of the render. `ProductSelector` forwards
+a `ProductSelectorHandle` (`focus()`, `refresh()`) through `ref`; `refresh()` is what a host calls
+after a sold-out failure.
+
 ## Error handling
 
 The widget classifies every failure into one of four **dispositions** and surfaces it accordingly, so a recoverable error stays in context instead of replacing the screen:

package/dist/components/compositions/granted-panel.d.ts

@@ -1,30 +1,6 @@
-/**
- * GrantedPanel
- *
- * Shared granted composition for distribution modules. Renders the
- * winning-state panel: status badge, expiry countdown (or fallback message
- * when no expiry is known), and — only when the caller supplies a
- * destination — a checkout CTA. Used by queue / draw / auction /
- * timed-release modules — the JSX is structurally identical across all
- * four; only the i18n strings differ.
- *
- * A granted frame with no `onCtaClick` renders no button: the grant is
- * already settled where the consumer stands, so an inert affordance would
- * promise a hand-off that does not exist.
- *
- *   <GrantedPanel
- *     label="Congratulations!"
- *     fallbackMessage="Proceed to checkout"
- *     ctaLabel="Continue"
- *     expiresAt={grantExpiry}
- *     onCtaClick={openCheckout}
- *   />
- *
- * `useGrantCelebration` fires the celebration animation against the
- * hero region — must be invoked unconditionally per React hook rules,
- * which is why this lives in its own component (each module's granted
- * branch returns `<GrantedPanel ... />` instead of inlining the JSX).
- */
+import { ClaimableSettlement, PreAuthSettlement } from '@fanfare-io/fanfare-sdk-core/experiences';
+import { GrantedSelection, SelectionChoice, SelectionDraft, SelectionOptions } from '@fanfare-io/fanfare-sdk-core/selections';
+import { SelectionCheckoutDetails, SelectionDisplay } from '../../lib/selection-display';
 import * as React from "react";
 export interface GrantedPanelProps {
     label: React.ReactNode;
@@ -37,10 +13,57 @@ export interface GrantedPanelProps {
      * payment countdown states what the consumer owes, so a synthesised one is worse than none.
      */
     detail?: React.ReactNode;
-    onCtaClick?: () => void;
+    /**
+     * 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.
+     */
+    onCtaClick?: (details?: SelectionCheckoutDetails) => void | Promise<void>;
     className?: string;
+    /** Granted-state selection: drives the pick, reveal, wait and summary states. */
+    selection?: GrantedSelection | null;
+    /**
+     * How the win settles. Selects the confirm label and which affordance sits beneath a resolved
+     * summary; absent leaves the CTA exactly as the caller wired it.
+     */
+    settlement?: ClaimableSettlement | PreAuthSettlement;
+    /**
+     * Parent binds the view's option loader; fetch-on-open only. Must be referentially stable — a
+     * new identity re-fetches the catalogue.
+     */
+    loadSelectionOptions?: () => Promise<SelectionOptions>;
+    /**
+     * Parent binds the view's selection submit; resolves when the pin is written and rejects on
+     * failure — the panel keys its pick UI on settle and shows the failure through `selectError`.
+     *
+     * The promise must resolve only once the journey atom carries the new selection: the pick
+     * surface collapses on the `selection` prop flip, so a promise that settles ahead of the atom
+     * re-enables the confirm control over a pick that has already been taken.
+     */
+    onConfirmSelection?: (choice: SelectionChoice) => Promise<void>;
+    /**
+     * Reports every local pick-surface transition, product-only drafts included, so the widget can
+     * emit the page-bridge selection-change event; `onConfirmSelection` stays the only settled-pair
+     * channel.
+     */
+    onDraftChange?: (draft: SelectionDraft) => void;
+    /** Heading copy for the pick state; the generic selection title stands when absent. */
+    selectionTitle?: React.ReactNode;
+    /** Helper copy under the pick heading; a reveal supplies its own prompt when absent. */
+    selectionDescription?: React.ReactNode;
+    /**
+     * Display strings for the resolved summary. Absent on a consumer-chosen resolution renders no
+     * summary at all: a locked line with no item detail states less than nothing.
+     */
+    selectionDisplay?: SelectionDisplay | null;
+    /**
+     * Locked copy for a resolved summary; modules pass "checkout" once checkout has started. Passing
+     * it also freezes the pick: the summary reads out locked with this reason and offers no change.
+     */
+    selectionLockedReason?: "checkout" | "final";
+    /** Inline error from the parent's selection submit. */
+    selectError?: string | null;
 }
-export declare function GrantedPanel({ label, fallbackMessage, ctaLabel, expiresAt, detail, onCtaClick, className, }: GrantedPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare function GrantedPanel({ label, fallbackMessage, ctaLabel, expiresAt, detail, onCtaClick, className, selection, settlement, loadSelectionOptions, onConfirmSelection, onDraftChange, selectionTitle, selectionDescription, selectionDisplay, selectionLockedReason, selectError, }: GrantedPanelProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace GrantedPanel {
     var displayName: string;
 }

package/dist/components/compositions/outcome-panel.d.ts

@@ -1,4 +1,24 @@
 import { OutcomeReason } from '../module';
+/**
+ * OutcomePanel
+ *
+ * Shared outcome composition for distribution modules. Renders a status
+ * panel showing why the user can't proceed, with an optional re-enter CTA
+ * for expired admission grants. Used by queue / draw / auction /
+ * timed-release modules — the JSX is structurally identical across all four.
+ *
+ *   <OutcomePanel
+ *     outcomeReason="expired"
+ *     onReenter={handleReenter}
+ *     isReentering={false}
+ *   />
+ *
+ * Each outcome reason renders its own heading + body via `OUTCOME_COPY`;
+ * `expired` additionally shows a mechanism-specific re-enter CTA. A completed
+ * purchase renders success copy, a non-selection its own copy, and unknown
+ * terminals fall back to the generic "ended" panel.
+ */
+import type * as React from "react";
 /**
  * The distribution mechanism a module owns. Drives mechanism-specific copy
  * (e.g. the expired re-enter button label) so each module shows terminology
@@ -25,9 +45,18 @@ export interface OutcomePanelProps {
     isReentering?: boolean;
     /** Secondary action offered once the outcome is final. */
     action?: OutcomeAction;
+    /**
+     * Already-translated copy replacing the reason's own. A terminal the caller knows more about
+     * than the taxonomy does — a drop that ended because the items ran out — says that instead of
+     * the generic line, and supplies both halves or neither.
+     */
+    copyOverride?: {
+        title: React.ReactNode;
+        body: React.ReactNode;
+    };
     className?: string;
 }
-export declare function OutcomePanel({ outcomeReason, participationType, onReenter, isReentering, action, className, }: OutcomePanelProps): import("react/jsx-runtime").JSX.Element;
+export declare function OutcomePanel({ outcomeReason, participationType, onReenter, isReentering, action, copyOverride, className, }: OutcomePanelProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace OutcomePanel {
     var displayName: string;
 }

package/dist/components/widgets/experience-widget.d.ts

@@ -1,6 +1,7 @@
 import { BotMitigationState, RoutingChallenge } from '@fanfare-io/fanfare-sdk-core/challenges';
 import { SDKEvents } from '@fanfare-io/fanfare-sdk-core/events';
 import { CheckoutNextAction, FanfareCheckoutResult, JourneyHandle, JourneySnapshot, JourneyView, PaymentInput, PaymentMethodSummary, SequenceView } from '@fanfare-io/fanfare-sdk-core/experiences';
+import { SelectionCheckoutDetails } from '../../lib/selection-display';
 import { BrandTheme, WidgetVariant } from '../../theme';
 import { AuthInputMode } from '../auth/auth-input';
 import { OutcomeAction } from '../compositions/outcome-panel';
@@ -194,6 +195,13 @@ export interface ExperienceWidgetProps {
     children?: (props: ExperienceRenderProps) => React.ReactNode;
     /** Checkout URL for granted state */
     checkoutUrl?: string;
+    /**
+     * Called when the consumer activates the granted checkout CTA, with the pick the grant settled
+     * on and the catalogue objects behind it whenever the widget has loaded them. Takes precedence
+     * over `checkoutUrl`. A rejected promise returns the consumer to the CTA with generic inline
+     * copy, so a hand-off that never happened is not reported as started.
+     */
+    onCheckoutClick?: (details?: SelectionCheckoutDetails) => void | Promise<void>;
     /**
      * Action offered on terminal panels (not selected, sold out, closed), such as
      * a link back to what is still available. Omit to show none.

package/dist/components/widgets/internal/auction-module.d.ts

@@ -1,7 +1,9 @@
 import { AuctionBidInput } from '@fanfare-io/fanfare-sdk-core/auctions';
-import { AuctionConsumerStatus } from '@fanfare-io/fanfare-sdk-core/experiences';
+import { AuctionConsumerStatus, ClaimableSettlement, PreAuthSettlement } from '@fanfare-io/fanfare-sdk-core/experiences';
 import { AuctionDisplayState } from '@fanfare-io/fanfare-sdk-core/internals';
+import { GrantedSelection, 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 AuctionModuleProps {
@@ -28,7 +30,32 @@ export interface AuctionModuleProps {
      */
     auctionType?: "english" | "dutch";
     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 auction captures a product choice with the bid, so the bid surface renders the picker. */
+    selectionRequired?: boolean;
+    /** Bound by the widget against the journey; must be referentially stable. */
+    loadSelectionOptions?: () => Promise<SelectionOptions>;
+    /** The pick a standing English bid is already for; it cannot be changed under that bid. */
+    lockedSelection?: SelectionChoice | null;
+    /** Granted-state selection arm; drives the panel's pick, reveal and summary states. */
+    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 bid controls. */
+    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 bidder lost. */
+    stockDenied?: boolean;
     outcomeReason?: OutcomeReason;
     /** Host-provided action shown on the terminal panel. */
     outcomeAction?: OutcomeAction;

package/dist/components/widgets/internal/draw-module.d.ts

@@ -1,5 +1,8 @@
+import { ClaimableSettlement, PreAuthSettlement } from '@fanfare-io/fanfare-sdk-core/experiences';
 import { DrawDisplayState } 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 DrawModuleProps {
@@ -11,8 +14,8 @@ export interface DrawModuleProps {
     canEnter: boolean;
     /** Whether user can leave (participating only) */
     canLeave: boolean;
-    /** Enter action handler */
-    onEnter: () => Promise<void>;
+    /** Enter action handler; carries the entry pick on a selection-bearing draw. */
+    onEnter: (selection?: SelectionChoice) => Promise<void>;
     /** Leave action handler */
     onLeave: () => Promise<void>;
     /** Whether entering is in progress */
@@ -27,8 +30,36 @@ export interface DrawModuleProps {
     expiresAt?: number | Date;
     /** Checkout URL — opens in a new tab when CTA clicked (granted) */
     checkoutUrl?: string;
-    /** Override checkout click handler (granted) */
-    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 draw 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, shown while the consumer waits. */
+    recordedSelection?: SelectionChoice | null;
+    /** Live availability of the recorded pick, so a sold-out choice is said rather than discovered. */
+    selectionAvailability?: SelectionAvailability;
+    /** Submits a changed choice while waiting. */
+    onSelectionChange?: (choice: SelectionChoice) => Promise<void>;
+    /** Granted-state selection arm; drives the panel's pick, reveal and summary states. */
+    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;
     /** Denial reason (denied) */
     outcomeReason?: OutcomeReason;
     /** Host-provided action shown on the terminal panel. */
@@ -40,7 +71,7 @@ export interface DrawModuleProps {
     /** Additional class name */
     className?: string;
 }
-export declare function DrawModule({ display$, sequencePhase, canEnter, canLeave, onEnter, onLeave, isEntering, isLeaving, countdownTo, grant: _grant, expiresAt, checkoutUrl, onCheckoutClick, outcomeReason, outcomeAction, onReenter, isReentering, className, }: DrawModuleProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function DrawModule({ display$, sequencePhase, canEnter, canLeave, onEnter, onLeave, isEntering, isLeaving, countdownTo, grant: _grant, expiresAt, checkoutUrl, onCheckoutClick, outcomeReason, outcomeAction, onReenter, isReentering, className, selectionRequired, loadSelectionOptions, recordedSelection, selectionAvailability, onSelectionChange, grantedSelection, settlement, onSelect, selectionLockedReason, selectError, stockDenied, onDraftChange, }: DrawModuleProps): import("react/jsx-runtime").JSX.Element | null;
 export declare namespace DrawModule {
     var displayName: string;
 }

package/dist/components/widgets/internal/index.d.ts

@@ -10,6 +10,8 @@ export { DrawModule, type DrawModuleProps } from './draw-module';
 export { QueueModule, type QueueModuleProps } from './queue-module';
 export { TimedReleaseModule, type TimedReleaseModuleProps } from './timed-release-module';
 export { UpcomingModule, type UpcomingModuleProps } from './upcoming-module';
+export { ProductSelector, SelectionSummary } from './selection';
+export type { ProductSelectorHandle, ProductSelectorProps, SelectionLockedReason, SelectionSummaryProps, } from './selection';
 export { LoadingView, type LoadingViewProps } from './loading-view';
 export { StartView, type StartViewProps } from './start-view';
 export { WaitlistView, type WaitlistViewProps } from './waitlist-view';

package/dist/components/widgets/internal/queue-module.d.ts

@@ -1,5 +1,8 @@
+import { ClaimableSettlement, PreAuthSettlement } from '@fanfare-io/fanfare-sdk-core/experiences';
 import { QueueDisplayState } from '@fanfare-io/fanfare-sdk-core/internals';
+import { GrantedSelection, 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 QueueModuleProps {
@@ -16,7 +19,30 @@ export interface QueueModuleProps {
     grant?: string;
     expiresAt?: number | 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>;
+    /** Admissions are paused upstream; the waiting line says so rather than looking stalled. */
+    admissionsPaused?: boolean;
+    /** Bound by the widget against the journey; must be referentially stable. */
+    loadSelectionOptions?: () => Promise<SelectionOptions>;
+    /** Granted-state selection arm; drives the panel's pick, reveal and summary states. */
+    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;
     outcomeReason?: OutcomeReason;
     /** Host-provided action shown on the terminal panel. */
     outcomeAction?: OutcomeAction;
@@ -24,7 +50,7 @@ export interface QueueModuleProps {
     isReentering?: boolean;
     className?: string;
 }
-export declare function QueueModule({ display$, sequencePhase, canEnter, canLeave, onEnter, onLeave, isEntering, isLeaving, closeAt, grant: _grant, expiresAt, checkoutUrl, onCheckoutClick, outcomeReason, outcomeAction, onReenter, isReentering, className, }: QueueModuleProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function QueueModule({ display$, sequencePhase, canEnter, canLeave, onEnter, onLeave, isEntering, isLeaving, closeAt, grant: _grant, expiresAt, checkoutUrl, onCheckoutClick, outcomeReason, outcomeAction, onReenter, isReentering, className, admissionsPaused, loadSelectionOptions, grantedSelection, settlement, onSelect, selectionLockedReason, selectError, stockDenied, onDraftChange, }: QueueModuleProps): import("react/jsx-runtime").JSX.Element | null;
 export declare namespace QueueModule {
     var displayName: string;
 }

package/dist/components/widgets/internal/selection/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Selection
+ *
+ * The product picker family and the read-out of a captured pick. `ProductSelectorRow`
+ * and `VariantRunGrid` are rendering units of `ProductSelector` alone and stay inside
+ * this directory.
+ *
+ * @packageDocumentation
+ */
+export { ProductSelector } from './product-selector';
+export type { ProductSelectorHandle, ProductSelectorProps } from './product-selector';
+export { SelectionSummary } from './selection-summary';
+export type { SelectionLockedReason, SelectionSummaryProps } from './selection-summary';

package/dist/components/widgets/internal/selection/product-selector-row.d.ts

@@ -0,0 +1,15 @@
+import { SelectionProduct } from '@fanfare-io/fanfare-sdk-core/selections';
+import * as React from "react";
+export interface ProductSelectorRowProps {
+    product: SelectionProduct;
+    currencyCode: string;
+    selected: boolean;
+    onSelect(productId: string): void;
+    disabled?: boolean;
+    className?: string;
+}
+/** A full-width product row: thumbnail, name and description, and the product's single price. */
+export declare function ProductSelectorRow({ product, currencyCode, selected, onSelect, disabled, className, }: ProductSelectorRowProps): React.ReactElement;
+export declare namespace ProductSelectorRow {
+    var displayName: string;
+}

package/dist/components/widgets/internal/selection/product-selector.d.ts

@@ -0,0 +1,46 @@
+import { SelectionChoice, SelectionDraft, SelectionOptions } from '@fanfare-io/fanfare-sdk-core/selections';
+import * as React from "react";
+export interface ProductSelectorHandle {
+    /** Moves focus to the first interactive element. */
+    focus(): void;
+    /** Re-fetches options; the host triggers this after a sold-out failure. */
+    refresh(): void;
+}
+export interface ProductSelectorProps {
+    /**
+     * Fetch-on-open; the caller binds the view's option loader. Must be referentially
+     * stable — a new identity is a new loader and re-fetches the catalogue.
+     */
+    loadOptions(): Promise<SelectionOptions>;
+    /**
+     * Restrict rendering to one assigned product's subtree. Sourced from the journey's
+     * selection arm — the options payload carries no assignment of its own.
+     */
+    assignedProductId?: string;
+    /** Pre-select a previously recorded or pinned choice. */
+    initialChoice?: SelectionChoice | null;
+    /**
+     * Bubbled so the parent drives the confirm, enter or bid action — the selector never
+     * submits a selection itself. A complete choice sends the pair; anything less sends null.
+     */
+    onSelectionChange(choice: SelectionChoice | null): void;
+    /**
+     * Fires on every local transition with the exact draft. Product-only picks are
+     * representable here and not through `onSelectionChange`, and this never drives a CTA.
+     */
+    onDraftChange?(draft: SelectionDraft): void;
+    /** Fires after each successful fetch, so hosts derive display strings without a second request. */
+    onOptionsLoaded?(options: SelectionOptions): void;
+    /** Already-translated error from the parent's action, rendered inline beneath the grid. */
+    selectError?: string | null;
+    disabled?: boolean;
+    className?: string;
+}
+/**
+ * The picker: product rows, the selected product's option chips, and the resolved price.
+ *
+ * Resolution and selectability are the core module's, never re-derived here, so the
+ * adapter and the server agree on what a choice means. The component owns no action:
+ * it reports a complete pair upward and the host decides what to do with it.
+ */
+export declare const ProductSelector: React.ForwardRefExoticComponent<ProductSelectorProps & React.RefAttributes<ProductSelectorHandle>>;

package/dist/components/widgets/internal/selection/selection-summary.d.ts

@@ -0,0 +1,30 @@
+import { SelectionAvailability, SelectionChoice } from '@fanfare-io/fanfare-sdk-core/selections';
+import * as React from "react";
+export type SelectionLockedReason = "checkout" | "final" | "bid";
+export interface SelectionSummaryProps {
+    /** The captured pair being displayed. Presentational only — no fetching. */
+    choice: SelectionChoice;
+    /** Already-translated eyebrow above the pick; the generic one stands when absent. */
+    label?: string | null;
+    /** Host-derived display strings. Absent renders the generic label with no item detail. */
+    productName?: string | null;
+    variantLabel?: string | null;
+    /** Live availability of the displayed pick; an unavailable pick shows the stale note. */
+    availability?: SelectionAvailability;
+    /** Suppresses the change affordance and shows the matching locked copy. Wins over onChangeRequest. */
+    lockedReason?: SelectionLockedReason | null;
+    /** The consumer asked to change the pick; the host decides what that opens. */
+    onChangeRequest?(): void;
+    className?: string;
+}
+/**
+ * A compact read-out of a pick that has already been captured.
+ *
+ * Purely presentational: it never fetches, never opens a picker, and never mutates
+ * the pick. A pick that has gone unavailable is said so here rather than left to be
+ * discovered at checkout.
+ */
+export declare function SelectionSummary({ choice, label, productName, variantLabel, availability, lockedReason, onChangeRequest, className, }: SelectionSummaryProps): React.ReactElement;
+export declare namespace SelectionSummary {
+    var displayName: string;
+}

package/dist/components/widgets/internal/selection/variant-run-grid.d.ts

@@ -0,0 +1,24 @@
+import { SelectionProduct } from '@fanfare-io/fanfare-sdk-core/selections';
+import * as React from "react";
+export interface VariantRunGridProps {
+    product: SelectionProduct;
+    /** optionId → valueId for the options chosen so far. */
+    chosenValues: Record<string, string>;
+    onValueSelect(optionId: string, valueId: string): void;
+    disabled?: boolean;
+    className?: string;
+}
+/**
+ * One fieldset per product option, each a wrapping run of value chips.
+ *
+ * Server order is the only order: options and values render exactly as the catalogue
+ * states them. Availability belongs to a whole variant rather than to a value, so a
+ * chip is selectable only when some variant carrying it survives the other choices
+ * already fixed — a value exhausted under one combination stays enabled under
+ * another. A value no combination can reach is shown disabled and described rather
+ * than removed, so the grid keeps telling the truth about what the drop offered.
+ */
+export declare function VariantRunGrid({ product, chosenValues, onValueSelect, disabled, className, }: VariantRunGridProps): React.ReactElement;
+export declare namespace VariantRunGrid {
+    var displayName: string;
+}

package/dist/components/widgets/internal/selection-branches.d.ts

@@ -0,0 +1,46 @@
+import { SelectionAvailability, SelectionChoice, SelectionDraft, SelectionOptions } from '@fanfare-io/fanfare-sdk-core/selections';
+import { ProductSelectorHandle } from './selection';
+import * as React from "react";
+/** Widened so a selection-bearing panel stacks its rows instead of clipping them at the card cap. */
+export declare const SELECTION_PANEL_CLASS = "ff:max-h-none ff:overflow-visible";
+export interface EntrySelectionSurfaceProps {
+    loadOptions: () => Promise<SelectionOptions>;
+    /** Already-translated heading above the picker. */
+    title: React.ReactNode;
+    /** The consumer's current complete pair, or null while the pick is incomplete. */
+    onDraftSelection: (choice: SelectionChoice | null) => void;
+    onOptionsLoaded: (options: SelectionOptions) => void;
+    /** Every local transition, product-only drafts included; feeds the page-bridge event. */
+    onDraftChange?: (draft: SelectionDraft) => void;
+    /** Set by the CTA when it was clicked on an incomplete pick. */
+    missingChoice: boolean;
+    selectError?: string | null;
+    disabled?: boolean;
+}
+/**
+ * The entry picker: statically present in the branch, with no open or collapse of its own.
+ *
+ * The CTA below it stays enabled with no choice made, so the consumer finds out what is missing
+ * by acting rather than by a control that refuses to be pressed.
+ */
+export declare const EntrySelectionSurface: React.ForwardRefExoticComponent<EntrySelectionSurfaceProps & React.RefAttributes<ProductSelectorHandle>>;
+export interface RecordedSelectionSurfaceProps {
+    choice: SelectionChoice;
+    availability?: SelectionAvailability;
+    loadOptions?: () => Promise<SelectionOptions>;
+    /** Submits the new pair; rejects when the server refuses, which keeps the picker open. */
+    onSelectionChange?: (choice: SelectionChoice) => Promise<void>;
+    /** Options already in memory from a pick made earlier in this mount. */
+    loadedOptions: SelectionOptions | null;
+    onOptionsLoaded: (options: SelectionOptions) => void;
+    /** Every local transition, product-only drafts included; feeds the page-bridge event. */
+    onDraftChange?: (draft: SelectionDraft) => void;
+    selectError?: string | null;
+}
+/**
+ * The recorded pick and its re-pick, for a consumer already waiting on a result.
+ *
+ * A fresh mount has no catalogue in memory and makes no request for one: the summary states the
+ * pick generically rather than spending an entrant's request budget on prettier names.
+ */
+export declare function RecordedSelectionSurface({ choice, availability, loadOptions, onSelectionChange, loadedOptions, onOptionsLoaded, onDraftChange, selectError, }: RecordedSelectionSurfaceProps): React.ReactElement;