@fanfare-io/fanfare-sdk-react 0.21.0 → 0.23.0

package/README.md

@@ -50,10 +50,22 @@ same `automaticEntry` option to `useExperienceJourney`; both reach the ready vie
 omitting it keeps the SDK default of entering on arrival. The contract is in the core package's
 `docs/UPGRADING-automatic-entry.md` in the SDK repository.
 
+`loadFonts` is off by default. Turned on, the widget fetches the Google Fonts its theme and variant
+name after mount, through a link that never blocks rendering and fails silently to the fallback
+stack. A host that already loads its own fonts — or serves them from its own origin — leaves it off.
+
 Customization has four levels of increasing specificity: `theme`, `variant`, `slots`, and `children` or `useExperienceJourney`.
 
 `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.
 
+Mounted inside a shadow root, the widget's styleable elements export CSS parts named after their
+`data-slot`, so a page styles them with `::part()` — `fanfare-host::part(auction-cta)`. The
+attribution footer and every element that contains its "Powered by Fanfare" row are
+deliberately not parts: the widget root and the panel cards that carry that row. The payment
+card field is not a part either. A panel whose footer holds no attribution row keeps its card
+as a part — `auction-module` is one; [`docs/STYLING.md`](./docs/STYLING.md#parts) lists every
+part and every exception.
+
 ## Selection
 
 Some experiences capture which product and variant a consumer gets. `ExperienceWidget` renders that

package/dist/components/checkout/card-brand.d.ts

@@ -0,0 +1,2 @@
+/** The consumer-facing name of a wire card brand (`visa` → `Visa`, `cartes_bancaires` → `Cartes Bancaires`). */
+export declare function cardBrandName(brand: string): string;

package/dist/components/checkout/checkout-processing-panel.d.ts

@@ -5,6 +5,7 @@ import * as React from "react";
  * confirmation.
  *
  * The consumer must not navigate away while the payment settles, so the wait is announced rather
- * than shown only as motion.
+ * than shown only as motion. It reads as the same callout the payment panel shows while a bank
+ * confirmation resumes, so the two waits on one payment look like one wait.
  */
 export declare function CheckoutProcessingPanel(_props: CheckoutProcessingSlotProps): React.ReactElement;

package/dist/components/checkout/payment-collection-panel.d.ts

@@ -5,9 +5,9 @@ import * as React from "react";
  *
  * The hold amount is rendered from the view's own figure — the client never derives one.
  *
- * The configuration block reaches this panel on the entry mount only. A retry is offered from an
- * ended view, which carries none, so that mount renders payment as unavailable and a consumer with
- * a saved method submits without needing Stripe.js at all.
+ * An absent configuration block means its read failed. A saved method pays without Stripe.js, so
+ * with one the outage narrows to the new-card choice; with none, re-reading the configuration is
+ * the panel's only way forward.
  *
  * Entry has no server-side resume: a paused authorization is carried forward by submitting the
  * identical payment input again, held here from the first submit, so exactly one payment method is

package/dist/components/checkout/payment-method-list.d.ts

@@ -0,0 +1,18 @@
+import { PaymentMethodSummary } from '@fanfare-io/fanfare-sdk-core/experiences';
+import type * as React from "react";
+export interface PaymentMethodListProps {
+    methods: PaymentMethodSummary[];
+    /** Unique per panel: radios sharing a name form one group across the whole document. */
+    name: string;
+    selectedId: string | undefined;
+    newCardActive: boolean;
+    /** Offer the new-card row; absent when no card entry can be mounted. */
+    cardEntryAvailable: boolean;
+    onSelectSaved: (id: string) => void;
+    onSelectNew: () => void;
+}
+/**
+ * Saved payment methods and the new-card choice, as one radio group of selector rows. The row look
+ * lives in the theme stylesheet, keyed on `payment-method-row`.
+ */
+export declare function PaymentMethodList({ methods, name, selectedId, newCardActive, cardEntryAvailable, onSelectSaved, onSelectNew, }: PaymentMethodListProps): React.ReactElement;

package/dist/components/checkout/receipt-panel.d.ts

@@ -3,8 +3,9 @@ import * as React from "react";
 /**
  * Default panel for a completed Fanfare-managed payment.
  *
- * The order reference is the outcome. An admission credential appears only on the arm that carries
- * one, and stays subordinate to the purchase: payment is terminal, so a receipt must never read as
- * the thing that admits its holder.
+ * The purchase is the outcome: the panel is labelled as one and leads with what was paid, and the
+ * order reference follows. An admission credential appears only on the arm that carries one, and
+ * stays subordinate to the purchase: payment is terminal, so a receipt must never read as the thing
+ * that admits its holder.
  */
 export declare function ReceiptPanel(props: ReceiptSlotProps): React.ReactElement;

package/dist/components/primitives/countdown.d.ts

@@ -1,15 +1,18 @@
 /**
  * Countdown Component
  *
- * Displays time remaining until a target date.
- * Automatically updates every second.
+ * Displays time remaining until a target date, refreshed every second.
  *
- * Two layouts:
- * - "swiss" (default): Prominent display with animated digits and labels above
- * - "compact": Simple text-based countdown that inherits parent styling
+ * Two layouts share one `--ff-countdown-*` token set:
+ * - "cells" (default): one box per time unit
+ * - "inline": a single line that fits inside a sentence, a ledger row or a button
+ *
+ * The visual layouts are `aria-hidden`; one visually-hidden sibling carries
+ * `role="timer"`, so exactly one live region exists whatever the container
+ * width makes visible.
  */
 export type CountdownSize = "default" | "hero";
-export type CountdownTone = "calm" | "warning" | "critical";
+export type CountdownTone = "calm" | "warning" | "critical" | "auto";
 export interface CountdownProps {
     /** Target date/time to count down to */
     targetDate: Date | string | number;
@@ -27,16 +30,52 @@ export interface CountdownProps {
     showMinutes?: boolean;
     /** Show seconds in countdown */
     showSeconds?: boolean;
-    /** Layout: "swiss" for prominent animated display, "compact" for simple text */
-    layout?: "swiss" | "compact";
-    /** Size: "default" (compact display) or "hero" (52px monospace, urgency-driver). */
+    /** Layout: "cells" for a box per unit, "inline" for a single line */
+    layout?: "cells" | "inline";
+    /** Numeral granularity under `layout="cells"`: one text node per unit, or one box per digit. */
+    cells?: "unit" | "digit";
+    /**
+     * How the time is spelled wherever it is written as one line: the inline
+     * layout, the narrow fallback the cells layout falls back to, and — always in
+     * `clock` spelling — the string assistive technology is given.
+     * `labelled` renders `14m 57s`, with a literal space between units.
+     * `clock` renders `02:00` / `1:15:17`, and always carries minutes and seconds
+     * whatever `showMinutes` and `showSeconds` say.
+     */
+    format?: "labelled" | "clock";
+    /**
+     * Hold the last rendered value. A paused countdown runs no interval, never
+     * calls `onComplete` and stops announcing; on resume it re-reads the clock
+     * rather than continuing from the held value.
+     */
+    paused?: boolean;
+    /** Size: "default" (compact display) or "hero" (the larger urgency-driver); the two differ only in scale. */
     size?: CountdownSize;
     /**
-     * Presentational urgency tone. Caller derives from phase + time-remaining and passes it.
-     * - calm: foreground color (default)
-     * - warning: warning token color
-     * - critical: danger token color (in retro, also flips the unit container bg)
+     * Presentational urgency tone, published as `data-tone` on both layout roots
+     * and on each cell, and coloured from the `--ff-countdown-tone-*` tokens.
+     * - calm: numeral colour (default)
+     * - warning: warning tone colour
+     * - critical: critical tone colour (in retro, also flips the unit container bg)
+     * - auto: resolved from the time remaining on every tick
      */
     tone?: CountdownTone;
 }
-export declare function Countdown({ targetDate, onComplete, expiredLabel, className, showDays, showHours, showMinutes, showSeconds, layout, size, tone, }: CountdownProps): import("react/jsx-runtime").JSX.Element | null;
+interface TimeRemaining {
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    total: number;
+}
+/** Which units the caller allows on screen; a hidden unit rolls into the next shown one. */
+interface ShownUnits {
+    days: boolean;
+    hours: boolean;
+    minutes: boolean;
+    seconds: boolean;
+}
+/** Time left on a target, decomposed across the units the caller shows. */
+export declare function calculateTimeRemaining(targetDate: Date | string | number, shown: ShownUnits, nowMs?: number): TimeRemaining;
+export declare function Countdown({ targetDate, onComplete, expiredLabel, className, showDays, showHours, showMinutes, showSeconds, layout, cells, format, paused, size, tone, }: CountdownProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/primitives/spinner.d.ts

@@ -4,6 +4,11 @@ declare const spinnerVariants: (props?: ({
     size?: "sm" | "md" | "lg" | null | undefined;
     styleVariant?: "default" | "rounded" | "retro" | "clean" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
+/**
+ * Whether `Spinner` and `Button` export their CSS `part` names. A subtree a page must never style
+ * from outside — the payment field — renders with it off.
+ */
+export declare const ExportPartsContext: React.Context<boolean>;
 export interface SpinnerProps extends React.SVGAttributes<SVGSVGElement>, Omit<VariantProps<typeof spinnerVariants>, "styleVariant"> {
 }
 export declare const Spinner: React.ForwardRefExoticComponent<SpinnerProps & React.RefAttributes<SVGSVGElement>>;

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

@@ -86,6 +86,13 @@ interface PaymentCollectionBaseSlotProps extends SlotProps {
 export type PaymentCollectionSlotProps = PaymentCollectionBaseSlotProps & ({
     intent: "checkout";
     onResume: () => Promise<void>;
+    /** Grant expiry as a ms epoch: the deadline the claim window counts down to. */
+    expiresAt?: number;
+    /**
+     * True while the deadline is the server's alone, so the claim window holds its last value
+     * instead of counting a limit the SDK is no longer enforcing.
+     */
+    expiryPaused: boolean;
 } | {
     intent: "enter" | "reenter";
     preAuthAmount: string;
@@ -181,6 +188,12 @@ export interface ExperienceWidgetProps {
      * automatically. Omit to keep the default (`true`); pass `false` to keep every entry explicit.
      */
     automaticEntry?: boolean;
+    /**
+     * Whether the widget fetches the Google Fonts stylesheets for the families its theme names.
+     * Off unless asked: an embed's page owns its own font delivery and its own content policy.
+     * The fetch never blocks rendering and a failure is silent.
+     */
+    loadFonts?: boolean;
     /** Pre-fill access code */
     accessCode?: string;
     /** Auto-enter waitlist when available */
@@ -220,6 +233,16 @@ export interface ExperienceWidgetProps {
     onFanfareCheckout?: (result: FanfareCheckoutResult) => void;
     /** Called when an error occurs */
     onError?: (error: Error) => void;
+    /**
+     * Horizontal placement of the widget inside the host's container. The widget is start-aligned
+     * unless this is `"center"`.
+     */
+    align?: "start" | "center";
+    /**
+     * Explicit override of the widget's adaptive maximum width. Omit to keep the value of
+     * the `--ff-widget-max-width` custom property.
+     */
+    size?: "compact" | "regular" | "wide";
     /** Additional class name */
     className?: string;
 }

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

@@ -36,7 +36,7 @@ export declare namespace Ledger {
     var displayName: string;
 }
 /**
- * Discrete unit pips for a Dutch remaining count, at the wide adaptation only.
+ * Discrete unit pips for a Dutch remaining count, shown only at the wide container width.
  *
  * 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.
@@ -49,14 +49,3 @@ export declare function UnitPips({ remaining, total, label }: {
 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/selection-branches.d.ts

@@ -1,8 +1,6 @@
 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. */