@fanfare-io/fanfare-sdk-react 0.1.0

package/dist/components/widgets/queue/queue-actions.d.ts

@@ -0,0 +1,36 @@
+/**
+ * QueueActions Component
+ *
+ * Action buttons for queue operations (enter, leave, share).
+ */
+export type QueueStatus = "enterable" | "queued" | "granted" | "error";
+export interface QueueActionsProps {
+    /** Current queue status */
+    status: QueueStatus;
+    /** Enter queue handler */
+    onEnter?: () => void;
+    /** Leave queue handler */
+    onLeave?: () => void;
+    /** Share position handler */
+    onShare?: () => void;
+    /** Whether enter is in progress */
+    isEntering?: boolean;
+    /** Whether leave is in progress */
+    isLeaving?: boolean;
+    /** Enter button label */
+    enterLabel?: string;
+    /** Leave button label */
+    leaveLabel?: string;
+    /** Share position button label */
+    shareLabel?: string;
+    /** Show share button */
+    showShare?: boolean;
+    /** Layout direction */
+    layout?: "horizontal" | "vertical";
+    /** Additional class name */
+    className?: string;
+}
+export declare function QueueActions({ status, onEnter, onLeave, onShare, isEntering, isLeaving, enterLabel, leaveLabel, shareLabel, showShare, layout, className, }: QueueActionsProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace QueueActions {
+    var displayName: string;
+}

package/dist/components/widgets/timed-release/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Timed Release Widget Internal Components
+ *
+ * Building blocks for the TimedReleaseWidget.
+ */
+export { TimedReleaseActions, type TimedReleaseActionsProps, type TimedReleaseStatus } from './timed-release-actions';

package/dist/components/widgets/timed-release/timed-release-actions.d.ts

@@ -0,0 +1,38 @@
+/**
+ * TimedReleaseActions Component
+ *
+ * Action buttons for timed release operations (enter, shop, exit).
+ */
+export type TimedReleaseStatus = "open" | "entered" | "shopping" | "completed" | "expired" | "ended";
+export interface TimedReleaseActionsProps {
+    /** Current status */
+    status: TimedReleaseStatus;
+    /** Enter sale handler */
+    onEnter?: () => void;
+    /** Shop/continue handler */
+    onShop?: () => void;
+    /** Complete purchase handler */
+    onComplete?: () => void;
+    /** Exit sale handler */
+    onExit?: () => void;
+    /** Whether enter is in progress */
+    isEntering?: boolean;
+    /** Whether exit is in progress */
+    isExiting?: boolean;
+    /** Enter button label */
+    enterLabel?: string;
+    /** Shop button label */
+    shopLabel?: string;
+    /** Complete button label */
+    completeLabel?: string;
+    /** Exit button label */
+    exitLabel?: string;
+    /** Layout direction */
+    layout?: "horizontal" | "vertical";
+    /** Additional class name */
+    className?: string;
+}
+export declare function TimedReleaseActions({ status, onEnter, onShop, onComplete, onExit, isEntering, isExiting, enterLabel, shopLabel, completeLabel, exitLabel, layout, className, }: TimedReleaseActionsProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace TimedReleaseActions {
+    var displayName: string;
+}

package/dist/components/widgets/waitlist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Waitlist Widget Internal Components
+ *
+ * Building blocks for the WaitlistWidget.
+ */
+export { WaitlistActions, type WaitlistActionsProps, type WaitlistStatus } from './waitlist-actions';

package/dist/components/widgets/waitlist/waitlist-actions.d.ts

@@ -0,0 +1,40 @@
+/**
+ * WaitlistActions Component
+ *
+ * Action buttons for waitlist operations (enter, leave, share).
+ */
+export type WaitlistStatus = "available" | "entered" | "opening" | "opened";
+export interface WaitlistActionsProps {
+    /** Current waitlist status */
+    status: WaitlistStatus;
+    /** Enter waitlist handler */
+    onEnter?: () => void;
+    /** Leave waitlist handler */
+    onLeave?: () => void;
+    /** Share position handler */
+    onShare?: () => void;
+    /** Proceed handler (when opened) */
+    onProceed?: () => void;
+    /** Whether enter is in progress */
+    isEntering?: boolean;
+    /** Whether leave is in progress */
+    isLeaving?: boolean;
+    /** Enter button label */
+    enterLabel?: string;
+    /** Leave button label */
+    leaveLabel?: string;
+    /** Share button label */
+    shareLabel?: string;
+    /** Proceed button label */
+    proceedLabel?: string;
+    /** Show share button */
+    showShare?: boolean;
+    /** Layout direction */
+    layout?: "horizontal" | "vertical";
+    /** Additional class name */
+    className?: string;
+}
+export declare function WaitlistActions({ status, onEnter, onLeave, onShare, onProceed, isEntering, isLeaving, enterLabel, leaveLabel, shareLabel, proceedLabel, showShare, layout, className, }: WaitlistActionsProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace WaitlistActions {
+    var displayName: string;
+}

package/dist/context.d.ts

@@ -0,0 +1,5 @@
+import { FanfareSDK } from '@fanfare-io/fanfare-sdk-core';
+/**
+ * Fanfare SDK context
+ */
+export declare const FanfareContext: import('react').Context<FanfareSDK | null>;

package/dist/hooks/use-appointment-slots.d.ts

@@ -0,0 +1,13 @@
+import { AppointmentSlot } from '@fanfare-io/fanfare-sdk-core/appointments';
+interface UseAppointmentSlotsResult {
+    slots: AppointmentSlot[];
+    isLoading: boolean;
+    error: Error | null;
+    refresh(): void;
+}
+export declare function useAppointmentSlots(appointmentId: string | undefined, range: {
+    startDate?: string;
+    endDate?: string;
+    timezone?: string;
+}): UseAppointmentSlotsResult;
+export {};

package/dist/hooks/use-auth.d.ts

@@ -0,0 +1,22 @@
+import { OtpRequest, OtpVerify } from '@fanfare-io/fanfare-sdk-core/auth';
+/**
+ * Hook for authentication state and operations
+ *
+ * @example
+ * ```tsx
+ * const { isAuthenticated, session, guest, requestOtp } = useFanfareAuth();
+ *
+ * if (!isAuthenticated) {
+ *   await guest();
+ * }
+ * ```
+ */
+export declare function useFanfareAuth(): {
+    guest: () => Promise<import('@fanfare-io/fanfare-sdk-core/auth').GuestSession>;
+    requestOtp: (options: OtpRequest) => Promise<void>;
+    verifyOtp: (options: OtpVerify) => Promise<import('@fanfare-io/fanfare-sdk-core/auth').AuthenticatedSession>;
+    logout: () => Promise<void>;
+    isAuthenticated: boolean;
+    isGuest?: boolean;
+    session?: import('@fanfare-io/fanfare-sdk-core/auth').Session;
+};

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

@@ -0,0 +1,20 @@
+import { JourneyHandle, JourneySnapshot, JourneyView } from '@fanfare-io/fanfare-sdk-core/experiences';
+export interface ExperienceJourneyOptions {
+    accessCode?: string;
+    autoEnterWaitlist?: boolean;
+}
+export interface UseExperienceJourneyOptions extends ExperienceJourneyOptions {
+    /**
+     * Automatically start the journey when the hook mounts
+     * and an experienceId is provided.
+     */
+    autoStart?: boolean;
+}
+export interface UseExperienceJourneyResult {
+    journey: JourneyHandle | null;
+    view: JourneyView | null;
+    snapshot: JourneySnapshot | null;
+    error: string | null;
+    start: (options?: ExperienceJourneyOptions) => Promise<JourneyView>;
+}
+export declare function useExperienceJourney(experienceId: string | undefined, options?: UseExperienceJourneyOptions): UseExperienceJourneyResult;

package/dist/hooks/use-fanfare.d.ts

@@ -0,0 +1,11 @@
+import { AdapterRuntimeSDK } from '../internal-sdk';
+/**
+ * Hook to access the Fanfare SDK instance
+ *
+ * @example
+ * ```tsx
+ * const fanfare = useFanfare();
+ * await fanfare.auth.guest();
+ * ```
+ */
+export declare function useFanfare(): AdapterRuntimeSDK;

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

@@ -0,0 +1,8 @@
+import { JourneyHandle, JourneySnapshot } from '@fanfare-io/fanfare-sdk-core/experiences';
+/**
+ * Subscribe to the full journey snapshot. Re-renders on every snapshot change.
+ * Use this for exhaustive DU switching (e.g. ExperienceWidget) or when you
+ * need the complete snapshot object. Prefer `useNanostore(handle.view$)`
+ * for view-level subscriptions.
+ */
+export declare function useJourneySnapshot(handle: JourneyHandle): JourneySnapshot;

package/dist/hooks/use-nanostore.d.ts

@@ -0,0 +1,6 @@
+import { ReadableAtom } from 'nanostores';
+/**
+ * Subscribe to a nanostores `ReadableAtom` using React's `useSyncExternalStore`.
+ * Returns the current value and re-renders only when the atom's value changes.
+ */
+export declare function useNanostore<T>(atom: ReadableAtom<T>): T;

package/dist/i18n/i18n-context.d.ts

@@ -0,0 +1,73 @@
+import { Locale, PartialTranslationMessages, TextDirection, TranslateFunction, TranslationKey, TranslationMessageKey, TranslationMessages } from '@fanfare-io/fanfare-sdk-i18n';
+/**
+ * Context value for i18n state.
+ */
+export interface I18nContextValue {
+    /** Current locale code */
+    locale: Locale;
+    /** Resolved messages (merged from all providers) */
+    messages: TranslationMessages<TranslationMessageKey>;
+    /** Whether this is the root i18n provider */
+    isRoot: boolean;
+    /** Translate function */
+    t: TranslateFunction<TranslationKey>;
+    /** Text direction based on locale */
+    dir: TextDirection;
+    /** Experience-level translation overrides */
+    experienceTranslations: PartialTranslationMessages<TranslationMessageKey> | null;
+    /** Update experience-level translations (called by useExperienceJourney) */
+    setExperienceTranslations: (translations: PartialTranslationMessages<TranslationMessageKey> | null) => void;
+}
+export declare const I18nContext: import('react').Context<I18nContextValue>;
+/**
+ * Hook to access the current i18n context.
+ * Returns the translate function and locale from the nearest I18nProvider.
+ *
+ * @returns The i18n context value with translate function and locale
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { t, locale } = useI18nContext();
+ *   return <span>{t("queue.position")}</span>;
+ * }
+ * ```
+ */
+export declare function useI18nContext(): I18nContextValue;
+/**
+ * Hook to get the translate function.
+ * Convenience wrapper around useI18nContext.
+ *
+ * @returns Object containing the translate function, locale, and text direction
+ *
+ * @example
+ * ```tsx
+ * function QueuePosition({ position }: { position: number }) {
+ *   const { t, dir } = useTranslations();
+ *   return (
+ *     <div dir={dir}>
+ *       <span>{t("queue.position")}</span>
+ *       <span>{t("queue.positionValue", { values: { position } })}</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useTranslations(): {
+    t: TranslateFunction<TranslationKey>;
+    locale: Locale;
+    dir: TextDirection;
+};
+/**
+ * Hook to create merged translations for a nested provider.
+ * Merges custom translations over the parent translations.
+ *
+ * Merge order: SDK defaults → experience translations → consumer props
+ *
+ * @param locale - Optional locale override
+ * @param translations - Optional translation overrides
+ * @param experienceTranslations - Experience-level translations (from useExperienceJourney)
+ * @param setExperienceTranslations - Function to update experience translations
+ * @returns The merged i18n context value
+ */
+export declare function useMergedTranslations(locale?: Locale, translations?: PartialTranslationMessages<TranslationMessageKey>, experienceTranslations?: PartialTranslationMessages<TranslationMessageKey> | null, setExperienceTranslations?: (translations: PartialTranslationMessages<TranslationMessageKey> | null) => void): I18nContextValue;

package/dist/i18n/i18n-provider.d.ts

@@ -0,0 +1,67 @@
+import { Locale, PartialTranslationMessages, TranslationMessageKey } from '@fanfare-io/fanfare-sdk-i18n';
+import { ReactNode } from 'react';
+/**
+ * Props for the I18nProvider component.
+ */
+export interface I18nProviderProps {
+    /**
+     * The locale to use for translations.
+     * @default "en"
+     */
+    locale?: Locale;
+    /**
+     * Custom translations to merge with or override defaults.
+     * Keys should match the default translation keys.
+     *
+     * @example
+     * ```tsx
+     * <I18nProvider translations={{ "queue.enter": "Join the Line" }}>
+     *   <App />
+     * </I18nProvider>
+     * ```
+     */
+    translations?: PartialTranslationMessages<TranslationMessageKey>;
+    /**
+     * Child components that will have access to translations.
+     */
+    children: ReactNode;
+}
+/**
+ * Provider component for internationalization.
+ *
+ * Provides translation context to child components. Supports nesting with
+ * message overrides - child providers merge their translations over parent values.
+ *
+ * @param props - Provider configuration
+ * @returns A provider component that distributes translations
+ *
+ * @example
+ * Basic usage with defaults:
+ * ```tsx
+ * <I18nProvider>
+ *   <App />
+ * </I18nProvider>
+ * ```
+ *
+ * @example
+ * With custom locale:
+ * ```tsx
+ * <I18nProvider locale="es">
+ *   <App />
+ * </I18nProvider>
+ * ```
+ *
+ * @example
+ * With translation overrides:
+ * ```tsx
+ * <I18nProvider
+ *   translations={{
+ *     "queue.enter": "Join the Queue",
+ *     "queue.leave": "Exit the Queue",
+ *   }}
+ * >
+ *   <App />
+ * </I18nProvider>
+ * ```
+ */
+export declare function I18nProvider({ locale, translations, children }: I18nProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/i18n/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * i18n Module
+ *
+ * Internationalization system for the Fanfare SDK React components.
+ * Re-exports core i18n utilities from @fanfare-io/fanfare-sdk-i18n.
+ *
+ * @packageDocumentation
+ */
+export { RTL_LOCALES, TRANSLATION_KEYS, createTranslateFunction, en, interpolate, isRTLLocale, mergeTranslations, type I18nConfig, type Locale, type PartialTranslationMessages, type RTLLocale, type TextDirection, type TranslateFunction, type TranslateOptions, type TranslationKey, type TranslationMessageKey, type TranslationMessages, } from '@fanfare-io/fanfare-sdk-i18n';
+export { I18nContext, useI18nContext, useMergedTranslations, useTranslations } from './i18n-context';
+export type { I18nContextValue } from './i18n-context';
+export { I18nProvider } from './i18n-provider';
+export type { I18nProviderProps } from './i18n-provider';

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Fanfare SDK React Adapter
+ *
+ * React hooks and components for integrating Fanfare SDK
+ *
+ * @packageDocumentation
+ */
+export { FanfareProvider } from './provider';
+export type { FanfareProviderProps } from './provider';
+export { useFanfareAuth } from './hooks/use-auth';
+export { useExperienceJourney } from './hooks/use-experience-journey';
+export { useFanfare } from './hooks/use-fanfare';
+export { useJourneySnapshot } from './hooks/use-journey-snapshot';
+export { useNanostore } from './hooks/use-nanostore';
+export { ExperienceJourneyController } from './components/journey/experience-journey-controller';
+export { ExperienceJourneySkeleton } from './components/journey/experience-journey-skeleton';
+export { FanfareContext } from './context';
+export { AuthInput } from './components/auth/auth-input';
+export type { AuthInputProps } from './components/auth/auth-input';
+export { OTPInput } from './components/auth/otp-input';
+export { Button, buttonVariants, type ButtonProps } from './components/primitives/button';
+export { Input } from './components/primitives/input';
+export { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from './components/primitives/card';
+export { InfoPanel, PanelBody, PanelFooter, PanelHeading, PanelLayout, normalizeOutcomeReason, } from './components/module';
+export type { InfoPanelProps, OutcomeReason, PanelBodyProps, PanelFooterProps, PanelHeadingProps, PanelHeadingVariant, PanelLayoutProps, } from './components/module';
+export { ThemeProvider } from './theme/theme-provider';
+export type { ThemeProviderProps } from './theme/theme-provider';
+export { buildThemeCssVars } from './theme/theme-utils';
+export { THEME_CSS_VARS } from './theme/theme.types';
+export type { ResolvedTheme, ThemeCssVar, WidgetThemeConfig, WidgetVariant } from './theme/theme.types';
+export { I18nProvider, RTL_LOCALES, isRTLLocale, useTranslations } from './i18n';
+export type { I18nConfig, I18nProviderProps, Locale, PartialTranslationMessages, RTLLocale, TextDirection, TranslateFunction, TranslateOptions, TranslationKey, TranslationMessageKey, TranslationMessages, } from './i18n';
+export { AuthForm } from './components/auth/auth-form';
+export type { AuthFormProps } from './components/auth/auth-form';
+export { AccessCodeForm } from './components/compositions/access-code-form';
+export type { AccessCodeFormProps } from './components/compositions/access-code-form';
+export { ChallengeGate } from './components/compositions/challenge-gate';
+export type { ChallengeGateProps } from './components/compositions/challenge-gate';
+export { EndedModule } from './components/compositions/ended-module';
+export type { EndedModuleProps } from './components/compositions/ended-module';
+export { ErrorView } from './components/compositions/error-view';
+export type { ErrorViewProps } from './components/compositions/error-view';
+export { GrantedPanel } from './components/compositions/granted-panel';
+export type { GrantedPanelProps } from './components/compositions/granted-panel';
+export { OutcomePanel } from './components/compositions/outcome-panel';
+export type { OutcomePanelProps } from './components/compositions/outcome-panel';
+export { ExperienceWidget, type AccessCodeSlotProps, type AuthSlotProps, type ChallengeSlotProps, type EndedSlotProps, type EnterableSlotProps, type ErrorSlotProps, type ExperienceRenderProps, type ExperienceWidgetProps, type ExperienceWidgetSlots, type ExpiredSlotProps, type GrantedSlotProps, type LoadingSlotProps, type ParticipatingSlotProps, type SlotProps, type StartSlotProps, type UpcomingSlotProps, type WaitlistSlotProps, } from './components/widgets/experience-widget';
+export { LoadingView, StartView, UpcomingModule, WaitlistView } from './components/widgets/internal';
+export type { LoadingViewProps, StartViewProps, UpcomingModuleProps, WaitlistViewProps, } from './components/widgets/internal';
+export { AuctionModule, DrawModule, QueueModule, TimedReleaseModule } from './components/widgets/internal';
+export type { AuctionModuleProps, DrawModuleProps, QueueModuleProps, TimedReleaseModuleProps, } from './components/widgets/internal';
+export { ShadowDOMPreview } from './components/shadow-dom-preview';
+export type { ShadowDOMPreviewProps } from './components/shadow-dom-preview';