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

package/README.md

@@ -44,6 +44,43 @@ Solid applications can use `FanfareProvider`, `ExperienceWidget`, and `useExperi
 
 `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.
+
+### Experience timing
+
+`useExperienceTiming(() => experienceId)` takes the experience id as an accessor and reads that experience's public
+timing once when it mounts, and again when the id changes or you call `refresh()`:
+
+| `status()`  | `timing()`                                                                |
+| ----------- | ------------------------------------------------------------------------- |
+| `"loading"` | `undefined` — the first read for this experience has not finished         |
+| `"error"`   | `undefined` — the read failed; call `refresh()` to try again              |
+| `"ready"`   | the `ExperienceTiming`, or `null` when the experience publishes no timing |
+
+```tsx
+import { useExperienceTiming } from "@fanfare-io/fanfare-sdk-solid";
+import { Show } from "solid-js";
+
+function DropStatus(props: { experienceId: string }) {
+  const timing = useExperienceTiming(() => props.experienceId);
+  return <Show when={timing.status() === "ready" && timing.timing()}>{(t) => <span>{t().status}</span>}</Show>;
+}
+```
+
+`ExperienceTiming` is a type exported from `@fanfare-io/fanfare-sdk-core/experiences`. Its `status` is `upcoming`,
+`open` or `closed`, with `nextOpensAt` and `lastClosedAt` around it. `closesAt` is
+present only while the experience is open, and is `null` when the open run has no end. The primitive never polls
+or schedules a re-read at a boundary, and adds no retry of its own: once `ready`, the result stays as read until
+you call `refresh()`.
+During a refresh the previous result stays in place — a `ready` result keeps its timing and an `error` stays
+`error` — until the new read settles. Primitives that read the same experience at the same time share one request.
+
 ## Selection
 
 Some experiences capture which product and variant a consumer gets. `ExperienceWidget` renders that

package/dist/components/auth/auth-form.d.ts

@@ -2,7 +2,9 @@ import { JSX } from 'solid-js';
 import { PanelHeadingVariant } from '../module';
 import { AuthInputMode } from './auth-input';
 export interface AuthFormProps {
-    onSubmit?: (credential: string, type: AuthInputMode) => Promise<void>;
+    onSubmit?: (credential: string, type: AuthInputMode, options?: {
+        marketingSmsConsent: boolean;
+    }) => Promise<void>;
     onVerify?: (otp: string) => Promise<void>;
     onSkip?: () => void | Promise<void>;
     onSuccess?: () => void;
@@ -19,6 +21,12 @@ export interface AuthFormProps {
     allowSkip?: boolean;
     skipLabel?: string;
     showBranding?: boolean;
+    /**
+     * Shows the marketing SMS consent checkbox, its disclosure and legal line on the credential step in
+     * phone mode. Off by default: set it only when `onSubmit` reads its third argument, since a tick
+     * the handler never reads is a consent silently dropped.
+     */
+    showMarketingSmsConsent?: boolean;
     /** Initial step when mounting. Useful for SSR-resume or storybook lanes that need the verify step. */
     defaultStep?: "credential" | "verify";
     /** Initial credential (email or E.164 phone) — pairs with `defaultStep="verify"`. */

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/compositions/journey-gate.d.ts

@@ -3,7 +3,9 @@ import { AuthInputMode } from '../auth/auth-input';
 export type JourneyGateStage = "auth" | "access_code" | "loading" | "none";
 export interface JourneyGateProps {
     stage: JourneyGateStage;
-    onAuthSubmit?: (credential: string, type: AuthInputMode) => Promise<void>;
+    onAuthSubmit?: (credential: string, type: AuthInputMode, options?: {
+        marketingSmsConsent: boolean;
+    }) => Promise<void>;
     onAuthVerify?: (otp: string) => Promise<void>;
     onAuthSkip?: () => void | Promise<void>;
     onAuthSuccess?: () => void;

package/dist/components/internal/queue-module.d.ts

@@ -8,6 +8,8 @@ import { OutcomeReason } from '../module';
 export interface QueueModuleProps {
     display$?: ReadableAtom<QueueDisplayState>;
     sequencePhase: "enterable" | "participating" | "granted" | "ended";
+    /** Hide live rank-derived queue metrics while the canonical queue is still pre-open. */
+    hideQueueMetrics?: boolean;
     canEnter: boolean;
     canLeave: boolean;
     onEnter: () => Promise<void>;

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

@@ -0,0 +1,6 @@
+import { JSX } from 'solid-js';
+export interface CheckboxProps extends Omit<JSX.InputHTMLAttributes<HTMLInputElement>, "type"> {
+    /** Label rendered beside the control. */
+    label: JSX.Element;
+}
+export declare function Checkbox(props: CheckboxProps): JSX.Element;

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

@@ -1,6 +1,7 @@
 export { Badge, badgeVariants, type BadgeProps, type BadgeVariant } from './badge';
 export { Button, buttonVariants, type ButtonProps } from './button';
 export { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, cardVariants, type CardContentProps, type CardDescriptionProps, type CardFooterProps, type CardHeaderProps, type CardProps, type CardTitleProps, } from './card';
+export { Checkbox, type CheckboxProps } from './checkbox';
 export { Countdown, type CountdownProps, type CountdownSize, type CountdownTone } from './countdown';
 export { FadePresence, type FadePresenceProps } from './fade-presence';
 export { FanfareLogo, type FanfareLogoProps } from './fanfare-logo';

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/widgets/experience-widget.d.ts

@@ -31,9 +31,16 @@ export interface StartSlotProps extends SlotProps {
     isStarting: boolean;
 }
 export interface AuthSlotProps extends SlotProps {
-    onSubmit: (credential: string, type: AuthInputMode) => Promise<void>;
+    onSubmit: (credential: string, type: AuthInputMode, options?: {
+        marketingSmsConsent: boolean;
+    }) => Promise<void>;
     onVerify: (otp: string) => Promise<void>;
     onSkip?: () => void;
+    /**
+     * Whether the sign-in should offer the marketing SMS consent checkbox. The widget sets it because its
+     * `onSubmit` reads the consent from its third argument; pass it to `AuthForm` with `onSubmit`.
+     */
+    showMarketingSmsConsent?: boolean;
 }
 export interface AccessCodeSlotProps extends SlotProps {
     onSubmit: (code: string) => Promise<void>;

package/dist/hooks/index.d.ts

@@ -9,6 +9,8 @@ export { useFanfareAuth } from './use-auth';
 export { createBeaconTracker } from './use-beacon-tracker';
 export { useExperienceJourney } from './use-experience-journey';
 export type { ExperienceJourneyOptions, UseExperienceJourneyOptions, UseExperienceJourneyResult, } from './use-experience-journey';
+export { useExperienceTiming } from './use-experience-timing';
+export type { UseExperienceTimingResult } from './use-experience-timing';
 export { useJourneySnapshot } from './use-journey-snapshot';
 export { useNanostore } from './use-nanostore';
 export { useSdkEvent } from './use-sdk-event';

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

@@ -0,0 +1,27 @@
+import { ExperienceTiming } from '@fanfare-io/fanfare-sdk-core/experiences';
+import { Accessor } from 'solid-js';
+/**
+ * Result of {@link useExperienceTiming}.
+ *
+ * - `status() === "loading"`: the first read for this experience has not settled; `timing()` is `undefined`.
+ * - `status() === "error"`: the last read was rejected; `timing()` is `undefined` and `refresh()` reads again.
+ * - `status() === "ready"`: `timing()` is the experience's public timing, or `null` when it publishes none.
+ */
+export interface UseExperienceTimingResult {
+    status: Accessor<"loading" | "error" | "ready">;
+    timing: Accessor<ExperienceTiming | null | undefined>;
+    refresh(): Promise<void>;
+}
+/**
+ * Reads an experience's public timing once when it attaches, and again whenever
+ * `experienceId` changes or `refresh()` is called.
+ *
+ * The primitive never polls, retries or schedules work around the timing's
+ * boundaries; a caller that needs fresher timing calls `refresh()`. While a
+ * refresh is in flight the result is unchanged: a `ready` result keeps its last
+ * timing and an `error` result stays `error` until the read settles. Primitives
+ * that read the same experience at the same time on one SDK instance share a
+ * single request. Results from a superseded read, or from one still in flight
+ * after disposal, are dropped.
+ */
+export declare function useExperienceTiming(experienceId: Accessor<string>): UseExperienceTimingResult;

package/dist/index.d.ts

@@ -7,7 +7,8 @@
  */
 export { FanfareProvider, useFanfare } from './components/provider';
 export type { FanfareProviderProps } from './components/provider';
-export { createBeaconTracker, useExperienceJourney, useFanfareAuth, useJourneySnapshot, useNanostore, useSdkEvent, } from './hooks';
+export { createBeaconTracker, useExperienceJourney, useExperienceTiming, useFanfareAuth, useJourneySnapshot, useNanostore, useSdkEvent, } from './hooks';
+export type { UseExperienceTimingResult } from './hooks';
 export { I18nProvider, RTL_LOCALES, isRTLLocale, useTranslations } from './i18n';
 export type { I18nConfig, I18nProviderProps, Locale, PartialTranslationMessages, RTLLocale, TextDirection, TranslateFunction, TranslateOptions, TranslationKey, TranslationMessageKey, TranslationMessages, } from './i18n';
 export { THEME_CSS_VARS, ThemeProvider, buildThemeCssVars } from './theme';