@fanfare-io/fanfare-sdk-react 0.20.1 → 0.22.0

package/README.md

@@ -40,6 +40,20 @@ export function App() {
 }
 ```
 
+`autoStart` 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 `ExperienceWidget`, or the
+same `automaticEntry` option to `useExperienceJourney`; both 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` 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.

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/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;
@@ -176,6 +183,17 @@ export interface ExperienceWidgetProps {
     experienceId: string;
     /** Automatically start journey on mount */
     autoStart?: 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.
+     */
+    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 */
@@ -215,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. */

package/dist/hooks/use-experience-journey.d.ts

@@ -3,6 +3,12 @@ import { JourneyHandle, JourneySnapshot, JourneyView } from '@fanfare-io/fanfare
 export interface ExperienceJourneyOptions {
     accessCode?: string;
     autoEnterWaitlist?: boolean;
+    /**
+     * Whether core may enter the consumer on the consumer's behalf when routing lands on a
+     * distribution the merchant set to enter on arrival. Left unset, core's default (`true`)
+     * applies; `false` keeps every entry an explicit one the consumer presses.
+     */
+    automaticEntry?: boolean;
 }
 export interface UseExperienceJourneyOptions extends ExperienceJourneyOptions {
     /**