@fanfare-io/fanfare-sdk-solid 0.16.0 → 0.18.0

package/README.md

@@ -40,6 +40,63 @@ Solid applications can use `FanfareProvider`, `ExperienceWidget`, and `useExperi
 
 `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. Solid `ExperienceWidget` accepts both `class` and `className`.
 
+## Selection
+
+Some experiences capture which product and variant a consumer gets. In this release the Solid
+package exports the two building blocks of that picker for you to compose in a granted slot; the
+widget-integrated flow, where `ExperienceWidget` renders the picker on its own, ships in a later
+release.
+
+- `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 pick is the host's to cart: the slot that composed `ProductSelector` holds
+the resolved `{ productId, variantId }` pair and the catalogue it came from, and carries it into its
+own checkout. 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. The React adapter's widget-integrated hand-off — the
+`onCheckoutClick(details?: SelectionCheckoutDetails)` callback — ships with the widget-integrated
+flow, so Solid exports no equivalent type yet.
+
+Three integration tiers, in increasing specificity:
+
+1. **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. Create the loader once,
+   outside the JSX, and have it read the journey's current sequence when it is called.
+2. **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.
+3. **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 3.
+
+`loadOptions` must be referentially stable — a new function identity is a new loader and re-fetches
+the catalogue, so define it outside the JSX rather than inline. Solid has no `forwardRef`, so
+`ProductSelector` hands its `ProductSelectorHandle` (`focus()`, `refresh()`) to a `ref` callback
+prop; `refresh()` is what a host calls after a sold-out failure. Both components accept `class`
+alongside `className`.
+
 ## Documentation
 
 - [Core SDK page observation](https://www.npmjs.com/package/@fanfare-io/fanfare-sdk-core): use `useExperienceJourney` for Solid state and `useSdkEvent` for typed SDK events. For surrounding CSS/non-framework scripts, install core's `createDomBridge` on a stable mounted target and dispose it before destroying the journey or SDK; Solid has no `useFanfareDomBridge` hook.

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

@@ -13,3 +13,5 @@ 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';

package/dist/components/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/internal/selection/product-selector-row.d.ts

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

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

@@ -0,0 +1,51 @@
+import { SelectionChoice, SelectionDraft, SelectionOptions } from '@fanfare-io/fanfare-sdk-core/selections';
+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;
+    /** Receives the imperative handle once, at mount. */
+    ref?: (handle: ProductSelectorHandle) => void;
+    class?: string;
+    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 function ProductSelector(props: ProductSelectorProps): import("solid-js").JSX.Element;
+export declare namespace ProductSelector {
+    var displayName: string;
+}

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

@@ -0,0 +1,30 @@
+import { SelectionAvailability, SelectionChoice } from '@fanfare-io/fanfare-sdk-core/selections';
+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;
+    class?: string;
+    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(props: SelectionSummaryProps): import("solid-js").JSX.Element;
+export declare namespace SelectionSummary {
+    var displayName: string;
+}

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

@@ -0,0 +1,24 @@
+import { SelectionProduct } from '@fanfare-io/fanfare-sdk-core/selections';
+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;
+    class?: string;
+    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(props: VariantRunGridProps): import("solid-js").JSX.Element;
+export declare namespace VariantRunGrid {
+    var displayName: string;
+}

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

@@ -0,0 +1,23 @@
+import { SelectionOptions } from '@fanfare-io/fanfare-sdk-core/selections';
+import { Accessor } from 'solid-js';
+export interface UseSelectionOptionsResult {
+    options: Accessor<SelectionOptions | null>;
+    isLoading: Accessor<boolean>;
+    error: Accessor<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 primitive 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 disposal, are dropped.
+ */
+export declare function useSelectionOptions(load: Accessor<(() => Promise<SelectionOptions>) | undefined>): UseSelectionOptionsResult;

package/dist/index.d.ts

@@ -20,6 +20,8 @@ export { InfoPanel, PanelBody, PanelFooter, PanelHeading, PanelLayout, normalize
 export type { InfoPanelProps, OutcomeReason, PanelBodyProps, PanelFooterProps, PanelHeadingProps, PanelHeadingVariant, PanelLayoutProps, } from './components/module';
 export { AccessCodeForm, ChallengeGate, EndedModule, ErrorView, GrantedPanel, OutcomePanel, } from './components/compositions';
 export type { AccessCodeFormProps, ChallengeGateProps, EndedModuleProps, ErrorViewProps, GrantedPanelProps, OutcomePanelProps, } from './components/compositions';
+export { ProductSelector, SelectionSummary } from './components/internal/selection';
+export type { ProductSelectorHandle, ProductSelectorProps, SelectionLockedReason, SelectionSummaryProps, } from './components/internal/selection';
 export { ExperienceWidget } from './components/widgets';
 export type { AccessCodeSlotProps, AuthSlotProps, ChallengeSlotProps, CheckoutProcessingSlotProps, EndedSlotProps, EnterableSlotProps, ErrorSlotProps, ExperienceRenderProps, ExperienceWidgetProps, ExperienceWidgetSlots, ExpiredSlotProps, GrantedSlotProps, LoadingSlotProps, ParticipatingSlotProps, PaymentCollectionSlotProps, ReceiptSlotProps, SlotProps, StartSlotProps, UpcomingSlotProps, WaitlistSlotProps, } from './components/widgets';
 export { CheckoutProcessingPanel, PaymentCollectionPanel, ReceiptPanel } from './components/checkout';