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

package/README.md

@@ -65,13 +65,19 @@ 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.
+instead, under both checkout modes, `at_end` and `pre_auth`. Entry-time picking is live: when the server declares that a draw, timed release
+or auction bid needs a product choice before entry, the module renders the picker and `enter` / `bid`
+carry the pair. A host reaching the view directly checks `"loadSelectionOptions" in view` for the
+required arm and reads `view.selection.required` for display.
 
 `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
+`{ selection, product, variant, currencyCode }`, the catalogue objects behind the pair. For Shopify
+checkout, use the product and variant `externalReference` values rather than matching handles,
+SKUs or option values. Require both references with provider `shopify`; pass their IDs through
+the Shopify adapter's `productGid` and `variantGid` helpers for the checkout line. A default variant
+still carries its identity when `optionValues` is empty. These references require a compatible
+backend and SDK release; handle absent references before starting checkout. 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
@@ -110,6 +116,11 @@ the catalogue, so wrap it in `useCallback` or hoist it out of the render. `Produ
 a `ProductSelectorHandle` (`focus()`, `refresh()`) through `ref`; `refresh()` is what a host calls
 after a sold-out failure.
 
+`selectError` is already-translated copy rendered inline beneath the grid, and it sits in the same
+tree as the rows and chips with no memo boundary, so changing it re-renders the whole selector.
+Hold it as state written only when an action rejects and cleared when the next action starts, so it
+tracks the outcome of a submit rather than the current draft.
+
 ## 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/widgets/experience-widget.d.ts

@@ -7,7 +7,7 @@ import { AuthInputMode } from '../auth/auth-input';
 import { OutcomeAction } from '../compositions/outcome-panel';
 import * as React from "react";
 type ParticipationType = "queue" | "draw" | "auction" | "timed_release" | "appointment";
-type EnterableSlotSequence = Extract<SequenceView, {
+export type EnterableSlotSequence = Extract<SequenceView, {
     phase: "enterable";
     mechanism: ParticipationType;
 }>;

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

@@ -8,4 +8,5 @@
  */
 export { ExperienceWidget, type AccessCodeSlotProps, type AuthSlotProps, type EndedSlotProps, type EnterableSlotProps, type ErrorSlotProps, type ExperienceRenderProps, type ExperienceWidgetProps, type ExperienceWidgetSlots, type ExpiredSlotProps, type GrantedSlotProps, type LoadingSlotProps, type ParticipatingSlotProps, type SlotProps, type StartSlotProps, type UpcomingSlotProps, type WaitlistSlotProps, } from './experience-widget';
 export { LoadingView, StartView, UpcomingModule, WaitlistView, type LoadingViewProps, type StartViewProps, type UpcomingModuleProps, type WaitlistViewProps, } from './internal';
+export type { EnterableSlotSequence } from './experience-widget';
 export { AuctionModule, DrawModule, QueueModule, TimedReleaseModule, type AuctionModuleProps, type DrawModuleProps, type QueueModuleProps, type TimedReleaseModuleProps, } from './internal';

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

@@ -56,6 +56,8 @@ export interface DrawModuleProps {
     selectionLockedReason?: "checkout" | "final";
     /** Already-translated selection failure from the widget, rendered beside the acting control. */
     selectError?: string | null;
+    /** The refusal code behind `selectError`; a stock refusal refetches the catalogue once. */
+    selectErrorCode?: 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. */
@@ -71,7 +73,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, selectionRequired, loadSelectionOptions, recordedSelection, selectionAvailability, onSelectionChange, grantedSelection, settlement, onSelect, selectionLockedReason, selectError, stockDenied, onDraftChange, }: 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, selectErrorCode, 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

@@ -1,8 +1,8 @@
 /**
  * Internal Widget Views
  *
- * These are internal components used by ExperienceWidget for stage rendering.
- * Not exported publicly - use slots to override these views.
+ * The stage modules ExperienceWidget renders. The four distribution modules are also root-exported
+ * for hosts composing their own widget; slots remain the override path inside ExperienceWidget.
  */
 export { AppointmentModule, type AppointmentModuleProps } from './appointment-module';
 export { AuctionModule, type AuctionModuleProps } from './auction-module';

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

@@ -9,5 +9,5 @@
  */
 export { ProductSelector } from './product-selector';
 export type { ProductSelectorHandle, ProductSelectorProps } from './product-selector';
-export { SelectionSummary } from './selection-summary';
+export { SELECTION_LOCKED_COPY, SelectionSummary } from './selection-summary';
 export type { SelectionLockedReason, SelectionSummaryProps } from './selection-summary';

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

@@ -17,6 +17,12 @@ export interface SelectionSummaryProps {
     onChangeRequest?(): void;
     className?: string;
 }
+/** The sentence a locked summary reads out, by the reason it is locked. */
+export declare const SELECTION_LOCKED_COPY: {
+    readonly checkout: "selection.locked.checkout";
+    readonly final: "selection.locked.final";
+    readonly bid: "selection.locked.bid";
+};
 /**
  * A compact read-out of a pick that has already been captured.
  *

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

@@ -41,6 +41,8 @@ export interface TimedReleaseModuleProps {
     selectionLockedReason?: "checkout" | "final";
     /** Already-translated selection failure from the widget, rendered beside the acting control. */
     selectError?: string | null;
+    /** The refusal code behind `selectError`; a stock refusal refetches the catalogue once. */
+    selectErrorCode?: 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. */
@@ -54,7 +56,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, selectionRequired, loadSelectionOptions, recordedSelection, selectionAvailability, grantedSelection, settlement, onSelect, selectionLockedReason, selectError, stockDenied, onDraftChange, }: 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, selectErrorCode, stockDenied, onDraftChange, }: TimedReleaseModuleProps): import("react/jsx-runtime").JSX.Element | null;
 export declare namespace TimedReleaseModule {
     var displayName: string;
 }