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

package/README.md

@@ -38,6 +38,10 @@ npm install @fanfare-io/fanfare-sdk-core @fanfare-io/fanfare-sdk-solid solid-js
 
 Solid applications can use `FanfareProvider`, `ExperienceWidget`, and `useExperienceJourney` directly: the same journey contract as the React adapter, with Solid reactivity.
 
+`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`.
 
 ## Selection

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/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/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,17 @@ 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.
+     */
+    automaticEntry?: boolean;
     accessCode?: string;
     autoEnterWaitlist?: boolean;
     theme?: BrandTheme;
@@ -201,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;
 }

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

@@ -4,6 +4,12 @@ import { MaybeAccessor } from '../utils/to-accessor';
 export interface ExperienceJourneyOptions {
     accessCode?: MaybeAccessor<string | undefined>;
     autoEnterWaitlist?: MaybeAccessor<boolean | undefined>;
+    /**
+     * 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?: MaybeAccessor<boolean | undefined>;
 }
 export interface UseExperienceJourneyOptions extends ExperienceJourneyOptions {
     autoStart?: MaybeAccessor<boolean | undefined>;