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

package/README.md

@@ -40,8 +40,18 @@ Solid applications can use `FanfareProvider`, `ExperienceWidget`, and `useExperi
 
 `auto-start` (`autoStart` in Solid) routes the journey on mount; entering is a separate matter. A queue, draw or timed release the merchant set to enter on arrival needs no Enter click: the SDK enters the consumer inside the routing operation that lands on it, and the widget shows a joining wait — no Enter control — until they have their place, then the participating screen. If the entry is turned down, the widget falls back to the ordinary Enter screen with the refusal beside it. A host that wants every entry to stay an explicit press passes `automaticEntry={false}` to the Solid `ExperienceWidget`, the same `automaticEntry` option to `useExperienceJourney`, or `automatic-entry="false"` on `<fanfare-experience-widget>`; all three reach the ready view's `start`, and 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` (`load-fonts` on `<fanfare-experience-widget>`) 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.
+
 `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`.
 
+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/clock-context.d.ts

@@ -0,0 +1,28 @@
+import { Accessor } from 'solid-js';
+/**
+ * A server-anchored clock for time-derived rendering (countdowns). `nowMs()`
+ * returns "now" corrected to the server's clock, so a skewed device clock
+ * doesn't shift what renders.
+ *
+ * Two phases, provided by `<FanfareProvider serverNow>`:
+ * - the first render uses a CONSTANT anchor (`serverNow` itself);
+ * - once the provider has mounted, `nowMs()` advances with real time on a fixed
+ *   server↔device offset, so a countdown mounted later (a routed view shown
+ *   minutes after the provider mounted) reads the current corrected time rather
+ *   than the frozen anchor.
+ */
+export interface FanfareClock {
+    nowMs(): number;
+}
+/** Constant-anchor clock for server render + first paint (deterministic). Null for an absent/invalid anchor. */
+export declare function makeAnchorClock(serverNow: string | undefined): FanfareClock | null;
+/** Live offset clock captured at provider mount: advances with real time, corrected for device skew. */
+export declare function makeOffsetClock(serverNow: string, deviceNowMs: number): FanfareClock | null;
+/**
+ * Carries an accessor rather than the clock itself: the provider swaps the
+ * anchor clock for the offset clock after mount, and a Solid context value is
+ * read once at creation, so the swap only reaches consumers through a signal.
+ */
+export declare const FanfareClockContext: import('solid-js').Context<Accessor<FanfareClock | null>>;
+/** The provided server-anchored clock, or null when no anchor is in scope. */
+export declare function useClock(): Accessor<FanfareClock | null>;

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

@@ -1,10 +1,11 @@
 import { JSX } from 'solid-js';
 import { CheckoutProcessingSlotProps } from '../widgets/experience-widget';
 /**
- * Default processing panel shown for the gap between a submitted reservation checkout and the
- * server's confirmation.
+ * Default processing panel shown for the gap between a submitted checkout and the server's
+ * 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): JSX.Element;

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

@@ -5,9 +5,9 @@ import { PaymentCollectionSlotProps } from '../widgets/experience-widget';
  *
  * 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 { JSX } from 'solid-js';
+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(props: PaymentMethodListProps): JSX.Element;

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

@@ -3,8 +3,9 @@ import { ReceiptSlotProps } from '../widgets/experience-widget';
 /**
  * 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): JSX.Element;

package/dist/components/checkout/stripe-card-field.d.ts

@@ -11,10 +11,5 @@ export interface StripeCardFieldProps {
         complete: boolean;
         errorMessage: string | null;
     }) => void;
-    /**
-     * The owning panel's account of everything it renders above this field. Its value carries no
-     * meaning; a change to it means the anchor may have moved and the portal frame needs re-measuring.
-     */
-    reflowKey?: string;
 }
 export declare function StripeCardField(props: StripeCardFieldProps): JSX.Element;

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

@@ -1,4 +1,4 @@
-import { Accessor, JSX } from 'solid-js';
+import { JSX } from 'solid-js';
 export type LedgerTone = "default" | "muted" | "live" | "danger" | "success";
 export interface LedgerRowProps {
     /** Decorative leading glyph; the label carries the row's meaning for assistive technology. */
@@ -29,7 +29,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.
@@ -42,10 +42,3 @@ export declare function UnitPips(props: {
 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.
- */
-export declare function useIsWide(threshold: number): [(element: HTMLDivElement) => void, Accessor<boolean>];

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

@@ -1,22 +1,6 @@
-import { GrantedSelection, SelectionAvailability, SelectionChoice, SelectionDraft, SelectionOptions } from '@fanfare-io/fanfare-sdk-core/selections';
+import { SelectionAvailability, SelectionChoice, SelectionDraft, SelectionOptions } from '@fanfare-io/fanfare-sdk-core/selections';
 import { JSX } from 'solid-js';
 import { ProductSelectorHandle } from './product-selector';
-/** 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";
-/** The granted-arm selection props every distribution module threads into its granted panel. */
-export interface GrantedPickProps {
-    grantedSelection?: GrantedSelection;
-    loadSelectionOptions?: () => Promise<SelectionOptions>;
-    onSelect?: (choice: SelectionChoice) => Promise<void>;
-    selectionLockedReason?: "checkout" | "final";
-}
-/**
- * Whether the granted panel can still open a pick surface, which is the only place the panel's
- * height cap may be lifted — the Confirm control below an open picker has to stay reachable.
- *
- * Reads its fields on call, so a module passes its own props object and gets a live answer.
- */
-export declare function grantedPickReachable(props: GrantedPickProps): boolean;
 export interface EntrySelectionSurfaceProps {
     /** Fetch-on-open; must be referentially stable — a new identity re-fetches the catalogue. */
     loadOptions(): Promise<SelectionOptions>;

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

@@ -1,20 +1,22 @@
 /**
  * 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 Solid adapter resolves the remaining time on the client, from the device
- * clock, because the adapter renders on the client. The React adapter anchors
- * to a server-supplied instant because it renders on the server, where a
- * device clock is not available and the markup has to match on hydration.
+ * 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.
+ *
+ * With a server-anchored clock in scope (`<FanfareProvider serverNow>`) the
+ * remaining time is corrected for device skew; with none it derives from the
+ * device clock.
  */
 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;
@@ -32,19 +34,55 @@ 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;
 }
+type 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. */
+type 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(props: CountdownProps): import("solid-js").JSX.Element;
 export declare namespace Countdown {
     var displayName: string;
 }
+export {};

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

@@ -4,6 +4,11 @@ declare const spinnerVariants: (props?: ({
     size?: "sm" | "md" | "lg" | null | undefined;
     styleVariant?: "default" | "retro" | "rounded" | "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: import('solid-js').Context<boolean>;
 export interface SpinnerProps extends JSX.SvgSVGAttributes<SVGSVGElement>, Omit<VariantProps<typeof spinnerVariants>, "styleVariant"> {
     className?: string;
 }

package/dist/components/provider.d.ts

@@ -5,6 +5,11 @@ export interface FanfareProviderProps {
     sdk: FanfareSDK;
     locale?: Locale;
     translations?: PartialTranslationMessages<TranslationMessageKey>;
+    /**
+     * Server-minted ISO timestamp anchoring time-derived rendering (countdowns),
+     * so a skewed device clock doesn't shift the display.
+     */
+    serverNow?: string;
     children: JSX.Element;
 }
 /**

package/dist/components/web/fanfare-web-component-provider.d.ts

@@ -9,6 +9,11 @@ export interface FanfareWebComponentProviderProps {
     autoResume?: boolean;
     locale?: Locale;
     translations?: PartialTranslationMessages<TranslationMessageKey>;
+    /**
+     * Server-minted ISO timestamp anchoring time-derived rendering (countdowns),
+     * so a skewed device clock doesn't shift the display.
+     */
+    serverNow?: string;
     themeConfig?: BrandTheme | null;
     variant?: WidgetVariant;
     className?: string;

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;
@@ -172,6 +179,12 @@ export interface ExperienceRenderProps {
 export interface ExperienceWidgetProps {
     experienceId: string;
     autoStart?: 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;
     /**
      * Whether the SDK may enter the consumer on arrival at a distribution the merchant set to enter
      * automatically. Omit to keep the default (`true`); pass `false` to keep every entry explicit.
@@ -206,6 +219,16 @@ export interface ExperienceWidgetProps {
     /** Called when a Fanfare-managed checkout completes */
     onFanfareCheckout?: (result: FanfareCheckoutResult) => void;
     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";
     class?: string;
     className?: string;
 }