@fanfare-io/fanfare-sdk-react 0.15.0 → 0.16.0

package/README.md

@@ -62,6 +62,7 @@ The displayed copy is **always SDK-owned i18n** (localized via your `FanfareProv
 
 ## Documentation
 
+- [Core SDK page observation](https://www.npmjs.com/package/@fanfare-io/fanfare-sdk-core): use `useExperienceJourney` for React state and `useSdkEvent` for typed SDK events. `useFanfareDomBridge` is for surrounding CSS/non-framework scripts, not a replacement state hook; give it an already-mounted, stable target. It stamps without an initial event and disposes on unmount; remount it to change targets.
 - [React components guide](https://docs.fanfare.io/sdk/components/react)
 - [Theming](https://docs.fanfare.io/sdk/components/theming) · [Slots](https://docs.fanfare.io/sdk/components/slots)
 - [Next.js / SSR integration](https://docs.fanfare.io/guides/integration-patterns/ssr-integration)

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

@@ -31,10 +31,16 @@ export interface GrantedPanelProps {
     fallbackMessage: React.ReactNode;
     ctaLabel?: React.ReactNode;
     expiresAt?: Date;
+    /**
+     * A fact the grant settles at — a winning bid, a clearing price — rendered under the countdown
+     * and beside the fallback message. Omitted when the amount is not known: a figure beside a
+     * payment countdown states what the consumer owes, so a synthesised one is worse than none.
+     */
+    detail?: React.ReactNode;
     onCtaClick?: () => void;
     className?: string;
 }
-export declare function GrantedPanel({ label, fallbackMessage, ctaLabel, expiresAt, onCtaClick, className, }: GrantedPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare function GrantedPanel({ label, fallbackMessage, ctaLabel, expiresAt, detail, onCtaClick, className, }: GrantedPanelProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace GrantedPanel {
     var displayName: string;
 }

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

@@ -0,0 +1,62 @@
+/**
+ * The auction ledger: label/value rows whose value column holds one x-position across every state.
+ *
+ * The panel carries phase in row order and in a leading marker glyph rather than in a hero number,
+ * so an amount never moves between states and a consumer comparing two moments compares the same
+ * column. The marker is decorative — every row states its meaning in its label.
+ */
+import * as React from "react";
+export type LedgerTone = "default" | "muted" | "live" | "danger" | "success";
+export interface LedgerRowProps {
+    /** Decorative leading glyph; the label carries the row's meaning for assistive technology. */
+    marker?: string;
+    label: React.ReactNode;
+    value: React.ReactNode;
+    tone?: LedgerTone;
+    /** Renders the value struck through — a bid that has been beaten, a price already passed. */
+    struck?: boolean;
+    className?: string;
+}
+export declare function LedgerRow({ marker, label, value, tone, struck, className }: LedgerRowProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace LedgerRow {
+    var displayName: string;
+}
+/** A row whose value has not arrived yet: the label stands, the figure is a placeholder. */
+export declare function LedgerSkeletonRow({ label }: {
+    label: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare namespace LedgerSkeletonRow {
+    var displayName: string;
+}
+export declare function Ledger({ children, className }: {
+    children: React.ReactNode;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare namespace Ledger {
+    var displayName: string;
+}
+/**
+ * Discrete unit pips for a Dutch remaining count, at the wide adaptation only.
+ *
+ * The pips are decorative; the grid states the count once in its own label so a screen reader
+ * hears "7 of 20 units remaining" rather than twenty unlabelled cells.
+ */
+export declare function UnitPips({ remaining, total, label }: {
+    remaining: number;
+    total: number;
+    label: string;
+}): import("react/jsx-runtime").JSX.Element | null;
+export declare namespace UnitPips {
+    var displayName: string;
+}
+/**
+ * Whether the panel's own rendered width has reached `threshold`.
+ *
+ * The adaptation is the panel's, not the viewport's: the widget is embedded at whatever width its
+ * host gives it, and a viewport query would split the columns on a page that never made room.
+ *
+ * The measured node is attached through a callback ref rather than observed once after mount: the
+ * panel swaps its skeleton for the live ledger, so the node the observer holds is replaced under
+ * it and a width read after the swap would come from a detached element.
+ */
+export declare function useIsWide(threshold: number): readonly [(element: HTMLDivElement | null) => void, boolean];

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

@@ -1,26 +1,32 @@
+import { AuctionBidInput } from '@fanfare-io/fanfare-sdk-core/auctions';
+import { AuctionConsumerStatus } from '@fanfare-io/fanfare-sdk-core/experiences';
 import { AuctionDisplayState } from '@fanfare-io/fanfare-sdk-core/internals';
 import { ReadableAtom } from 'nanostores';
 import { OutcomeAction } from '../../compositions/outcome-panel';
 import { OutcomeReason } from '../../module';
 export interface AuctionModuleProps {
     display$?: ReadableAtom<AuctionDisplayState>;
-    fallbackState?: AuctionDisplayState;
     sequencePhase: "enterable" | "participating" | "settling" | "granted" | "ended";
-    canEnter: boolean;
-    canLeave: boolean;
-    onEnter: () => Promise<void>;
-    onLeave: () => Promise<void>;
-    onBid?: (amount: string) => Promise<void>;
-    isEntering: boolean;
-    isLeaving: boolean;
+    /** Place a bid. English sends `{ amount }`; Dutch clinches at the shown price and sends `{}`. */
+    onBid?: (input: AuctionBidInput) => Promise<void>;
+    /** This consumer's own bid, which the live display state does not carry. */
+    yourBid?: string;
+    /** This consumer's own standing, which the live display state carries only as a loose string. */
+    yourStatus?: AuctionConsumerStatus;
     countdownTo?: Date;
-    defaultBidAmount?: string;
-    /** Currency code for bid display (overridden by displayState.currencyCode if present) */
+    /** Currency code for money display; the live display state's own code wins when present. */
     currencyCode?: string;
     /** Locale for currency formatting */
     locale?: string;
     grant?: string;
     expiresAt?: number | Date;
+    /** The amount this win settles at, shown beside the payment countdown. */
+    wonAmount?: string;
+    /**
+     * Which mechanism settled. The granted frame has no display atom to read the pricing model
+     * from, and a Dutch consumer bought at a posted price rather than winning a contest.
+     */
+    auctionType?: "english" | "dutch";
     checkoutUrl?: string;
     onCheckoutClick?: () => void;
     outcomeReason?: OutcomeReason;
@@ -30,7 +36,7 @@ export interface AuctionModuleProps {
     isReentering?: boolean;
     className?: string;
 }
-export declare function AuctionModule({ display$, fallbackState, sequencePhase, canEnter, canLeave, onEnter, onLeave, onBid, isEntering, isLeaving, countdownTo, defaultBidAmount, currencyCode, locale, grant: _grant, expiresAt, checkoutUrl, onCheckoutClick, outcomeReason, outcomeAction, onReenter, isReentering, className, }: AuctionModuleProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function AuctionModule(props: AuctionModuleProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace AuctionModule {
     var displayName: string;
 }

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

@@ -0,0 +1,68 @@
+import { AuctionDisplayState } from '@fanfare-io/fanfare-sdk-core/internals';
+/** The live price model, reached through the display state rather than a separate core export. */
+export type AuctionPricing = NonNullable<AuctionDisplayState["pricing"]>;
+export type EnglishPricing = Extract<AuctionPricing, {
+    model: "english";
+}>;
+export type DutchPricing = Extract<AuctionPricing, {
+    model: "dutch";
+}>;
+/** True when a string is a money value the panel may compute with. */
+export declare function isWireMoney(value: string | undefined): value is string;
+/**
+ * Reads a typed amount as a wire money string, or `null` when it is not one.
+ *
+ * A consumer types the separators their keyboard and locale give them — `245,00` across most of
+ * Europe, `1,234.50` or `1 234,50` with grouping — and a bid that is refused as below the minimum
+ * because of a comma is a bid the auction lost for no reason. Grouping is dropped and the decimal
+ * separator is read from position. Exponent notation is refused rather than expanded: `1e5` is not
+ * an amount anyone means to bid.
+ *
+ * `digits` is the currency's fraction digits, which decide what a lone comma before exactly three
+ * digits means: grouping in a two-digit currency, the decimal in a three-digit one, where reading
+ * it as grouping would multiply the bid a thousandfold.
+ */
+export declare function normalizeAmountInput(raw: string, digits?: number): string | null;
+/** Orders two wire money strings exactly at the eight-digit wire scale. */
+export declare function compareMoney(left: string, right: string, _digits: number): number;
+/**
+ * Moves `base` by `steps` whole increments, never below `floor`.
+ *
+ * The stepper and the quick-pick chips are the same operation at different step counts, so they
+ * cannot disagree about what one increment is worth.
+ */
+export declare function stepAmount(base: string, increment: string, steps: number, digits: number, floor?: string): string;
+/**
+ * True when `amount` is more than ten increments above the minimum next bid. The comparison stays
+ * in minor units so a threshold past the wire money width cannot fail validation.
+ */
+export declare function exceedsObligationThreshold(amount: string, minNextBid: string, increment: string): boolean;
+/** One rung of the Dutch descent, in the order it is rendered. */
+export interface DutchLadder {
+    /** The price the ladder started from, when it is not also the live price. */
+    start?: string;
+    /** Prices the ladder has already passed, newest last. */
+    passed: string[];
+    /** The price a clinch would pay right now. */
+    current: string;
+    /** The price the next drop lands on, when another drop is still coming. */
+    next?: string;
+    /** The price the ladder never falls below, when one is configured. */
+    floor?: string;
+}
+/**
+ * Derives the descent from the ladder configuration and the live price.
+ *
+ * No drop history crosses the wire, so the passed rungs are recomputed as `startPrice − k × drop`
+ * down to the live price. Returns `null` when the configuration needed to draw the ladder is
+ * absent: the rows that survive are the ones the server actually stated.
+ */
+export declare function buildDutchLadder(pricing: DutchPricing, digits: number): DutchLadder | null;
+/**
+ * Whether a Dutch clinch may be offered at all.
+ *
+ * Three independent gates, each of which alone makes the buy button a lie: Dutch never enters
+ * `participating` or `settling`, so the phase must still be `enterable`; a sold-out auction has no
+ * unit to sell; and `ended` closes the mechanism whatever the price says.
+ */
+export declare function canClinch(pricing: DutchPricing, sequencePhase: string): boolean;

package/dist/hooks/use-fanfare-dom-bridge.d.ts

@@ -1,11 +1,10 @@
 /**
  * Mirrors one journey into a stable DOM target.
  *
- * The bridge latches `data-fanfare-version`, `data-fanfare-experience-id`,
- * `data-fanfare-stage`, `data-fanfare-phase`, `data-fanfare-mechanism`,
- * `data-fanfare-expires-at`, and `data-fanfare-outcome` on `opts.target`,
+ * The bridge latches `data-fanfare-experience-id`, `data-fanfare-stage`,
+ * `data-fanfare-phase`, `data-fanfare-mechanism`, and `data-fanfare-expires-at` on `opts.target`,
  * defaulting to `document.documentElement`, and dispatches `fanfare:state-change`
- * on that same element. Queue position is event-only, and a terminal outcome
+ * on that same element. Version and queue position are event-only, and a terminal outcome
  * crosses as its type alone — the free-text qualifier that may accompany one
  * stays on the typed SDK surface.
  * Installation happens in an effect, so the first paint can be unbridged;