@hook-sdk/template 0.23.2 → 0.24.0

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode, ComponentType, Component } from 'react';
 import * as _hook_sdk_sdk from '@hook-sdk/sdk';
-import { HookContextValue, CheckoutMethod as CheckoutMethod$1, CheckoutCycle, CheckoutResult, CheckoutCardData, CheckoutHolderInfo, PlanState, ReminderSlot } from '@hook-sdk/sdk';
+import { HookContextValue, CheckoutMethod as CheckoutMethod$1, CheckoutCycle, CheckoutCardData, CheckoutHolderInfo, CheckoutResult, PlanState, ReminderSlot } from '@hook-sdk/sdk';
 export { PlanInfo, PlanState, useTrackOnboardingStep } from '@hook-sdk/sdk';
 import { z } from 'zod';
 
@@ -533,7 +533,9 @@ interface PaywallPlanDerived {
  * - `availableMethods` mirrors `methods`
  * - `opening` mirrors `submitting`
  * - `checkout(args)` takes legacy args + validates card/holderInfo presence
- * - `dismissPix` no-op (SDK polling auto-clears pixPending on settle)
+ * - `dismissPix` clears SDK `pixPending` (template 0.24.0 + SDK 0.26.0 wire,
+ *   resolves G154; was no-op pre-0.24 and apps had to maintain a local
+ *   `pixActive` flag to bridge the gap).
  * - `monthlyEquivalent(cycle)` helper
  */
 declare function usePaywallState(): {
@@ -1135,30 +1137,114 @@ type PaywallProps = {
  * Composed top-level paywall component. Apps wrap it in their `PaywallOffer.tsx`
  * (or `Offer.tsx`) and pass copy + themeClasses + slots. Logic + telemetry live
  * here. To customize layout entirely, drop down to the primitives.
+ *
+ * Internally wraps a `<PaywallProvider>` so the refactored primitives can read
+ * state from context. Apps wanting Level 2 / Level 3 composition can use
+ * `<PaywallProvider>` + Lego blocks directly without going through `<Paywall>`.
  */
 declare function Paywall({ copy, themeClasses, slots, onBeforeCheckout, }: PaywallProps): react_jsx_runtime.JSX.Element;
 
 type PaywallMethodTabsProps = {
-    methods: readonly CheckoutMethod[];
-    selected: CheckoutMethod;
-    onSelect: (m: CheckoutMethod) => void;
+    /** Tab labels keyed by checkout method. App-provided copy (not state). */
     labels: Partial<Record<CheckoutMethod, string>>;
+    /** Wrapper className. */
     className?: string;
+    /** Individual tab className. */
     tabClassName?: string;
+    /** Individual tab className when active. */
     tabActiveClassName?: string;
 };
-declare function PaywallMethodTabs({ methods, selected, onSelect, labels, className, tabClassName, tabActiveClassName, }: PaywallMethodTabsProps): react_jsx_runtime.JSX.Element | null;
+declare function PaywallMethodTabs({ labels, className, tabClassName, tabActiveClassName, }: PaywallMethodTabsProps): react_jsx_runtime.JSX.Element | null;
 
 type PaywallMethodContentProps = {
-    method: CheckoutMethod;
+    /**
+     * App-provided copy keyed by method. `pix` covers both `pix-auto` and
+     * `pix-once`. `cardConsumedTrial` is used when the active method is `card`
+     * AND `hasConsumedTrial` (read from context) is true.
+     */
     copy: Pick<PaywallCopy, 'pix' | 'card'> & {
         cardConsumedTrial?: PaywallCopy['cardConsumedTrial'];
     };
-    hasConsumedTrial?: boolean;
+    /** Tab-panel wrapper className. */
     className?: string;
+    /** Per-row className. */
     rowClassName?: string;
 };
-declare function PaywallMethodContent({ method, copy, hasConsumedTrial, className, rowClassName, }: PaywallMethodContentProps): react_jsx_runtime.JSX.Element;
+declare function PaywallMethodContent({ copy, className, rowClassName }: PaywallMethodContentProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Full return shape of `usePaywallState()`. Apps consuming via
+ * `usePaywallContext()` get the same fields they'd get from the headless
+ * hook directly — no internal-only fields hidden.
+ *
+ * This is the "Level 3" escape-hatch contract: any app can drop down to raw
+ * context and render an entirely custom paywall, with the template still
+ * owning state + telemetry + checkout dispatch.
+ */
+type PaywallContextValue = ReturnType<typeof usePaywallState>;
+/**
+ * Context that carries the full paywall state down to Lego blocks. Null
+ * outside `<PaywallProvider>`. Consumer hook `usePaywallContext()` throws on
+ * null to surface mis-mounted blocks early.
+ */
+declare const PaywallContext: react.Context<{
+    status: SubscriptionStatus;
+    hasAccess: boolean | null;
+    daysLeftInTrial: number | null;
+    initialLoadComplete: boolean;
+    plan: PaywallPlanDerived | null;
+    cycle: _hook_sdk_sdk.CheckoutCycle;
+    setCycle: react.Dispatch<react.SetStateAction<_hook_sdk_sdk.CheckoutCycle>>;
+    methods: readonly _hook_sdk_sdk.CheckoutMethod[];
+    selectedMethod: _hook_sdk_sdk.CheckoutMethod;
+    setSelectedMethod: react.Dispatch<react.SetStateAction<_hook_sdk_sdk.CheckoutMethod>>;
+    hasConsumedTrial: boolean;
+    currentPriceCents: number;
+    currentMonthlyEquivCents: number;
+    anchorPriceCents: number | null;
+    selectMethod: (next: _hook_sdk_sdk.CheckoutMethod) => void;
+    selectCycle: (next: _hook_sdk_sdk.CheckoutCycle) => void;
+    isFree: boolean;
+    trialDaysForMethod: (method: _hook_sdk_sdk.CheckoutMethod) => number;
+    trialDaysCard: number;
+    trialDaysPix: number;
+    cpfState: CpfState;
+    cardState: CardFormStateWithSetter;
+    submit: () => Promise<_hook_sdk_sdk.CheckoutResult | undefined>;
+    checkout: (args: PaywallCheckoutArgs) => Promise<void>;
+    cancel: () => Promise<void>;
+    pixPending: PixPending | null;
+    error: PaywallError | null;
+    submitting: boolean;
+    opening: boolean;
+    availableMethods: readonly _hook_sdk_sdk.CheckoutMethod[];
+    monthlyEquivalent: (c: _hook_sdk_sdk.CheckoutCycle) => number;
+    dismissPix: () => void;
+    refreshPlan: () => void;
+} | null>;
+type PaywallProviderProps = {
+    children: ReactNode;
+};
+/**
+ * Owns the headless paywall state for one paywall surface. All Lego blocks
+ * (PriceHeadline, AnchorPrice, FinePrint, refactored primitives) and the
+ * composed `<Paywall>` read state via this provider.
+ *
+ * Multiple compositions can share state by sharing one `<PaywallProvider>`
+ * parent (e.g. side-by-side variants on a dev/test page). Multiple
+ * providers in the same tree get independent state.
+ */
+declare function PaywallProvider({ children }: PaywallProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Consumer hook for the paywall context. Returns the non-null state object
+ * (same shape as `usePaywallState()`) when called inside `<PaywallProvider>`.
+ *
+ * Throws `"usePaywallContext must be used within <PaywallProvider>"` when the
+ * provider is missing — surfaces mis-mounted Lego blocks at render time
+ * instead of silently rendering with stale or default state.
+ */
+declare function usePaywallContext(): PaywallContextValue;
 
 type CycleLabels = {
     annualLabel: string;
@@ -1166,37 +1252,257 @@ type CycleLabels = {
     annualSuffix: string;
     monthlySuffix: string;
 };
-type PaywallCyclePickerProps = {
+/** Cycle picker visual variants. `default` preserves the current visual. */
+type PaywallCyclePickerVariant = 'default' | 'premium-gold' | 'pink-pill';
+/** State passed to the optional `render` escape hatch. */
+type PaywallCyclePickerRenderArgs = {
     cycles: readonly Cycle[];
     selected: Cycle;
-    onSelect: (c: Cycle) => void;
-    /** Raw price for the cycle (used to show full annual/monthly). */
-    priceCentsByCycle: Record<Cycle, number>;
-    /** Anchor strikethrough price, null when not set. */
-    anchorCentsByCycle: Record<Cycle, number | null>;
-    /** Monthly-equiv for YEARLY (priceCents / 12). Same as priceCentsByCycle for MONTHLY. */
-    monthlyEquivByCycle: Record<Cycle, number>;
+    setCycle: (c: Cycle) => void;
+    plan: ReturnType<typeof usePaywallContext>['plan'];
+    anchorPriceCents: number | null;
+};
+type PaywallCyclePickerProps = {
     labels: CycleLabels;
+    /** Root wrapper className. */
     className?: string;
+    /** Per-card base className. */
     cardClassName?: string;
+    /** Applied when the card is selected (in addition to `cardClassName`). */
     cardSelectedClassName?: string;
+    /** Anchor strikethrough className inside the card. */
     anchorClassName?: string;
+    /** Visual variant. Variants are sugar for className combos. */
+    variant?: PaywallCyclePickerVariant;
+    /**
+     * Render-prop escape hatch. When provided, the picker returns the prop's
+     * output wrapped in a root element with the configured `className`. State
+     * plumbing stays; visual is 100% the app's.
+     */
+    render?: (state: PaywallCyclePickerRenderArgs) => ReactNode;
 };
-declare function PaywallCyclePicker({ cycles, selected, onSelect, priceCentsByCycle, anchorCentsByCycle, monthlyEquivByCycle, labels, className, cardClassName, cardSelectedClassName, anchorClassName, }: PaywallCyclePickerProps): react_jsx_runtime.JSX.Element | null;
+declare function PaywallCyclePicker({ labels, className, cardClassName, cardSelectedClassName, anchorClassName, variant, render, }: PaywallCyclePickerProps): react_jsx_runtime.JSX.Element | null;
 
 type PaywallCtaProps = {
+    /** Already-interpolated CTA label (e.g. "Pagar R$ 19,90 com PIX"). */
     ctaLabel: string;
+    /** Label shown while `submitting === true`. Defaults to `ctaLabel`. */
     loadingLabel?: string;
+    /**
+     * Switch-hint copy shown under the CTA when the other method is available.
+     * Caller decides visibility (typically only when `methods.length > 1`).
+     */
     switchHint?: string;
+    /** Trust line under the CTA / switch hint. */
     trustLine: string;
-    onClick: () => void;
-    disabled?: boolean;
-    loading?: boolean;
+    /** Wrapper className. */
     className?: string;
+    /** Button className. */
     buttonClassName?: string;
+    /** Switch-hint paragraph className. */
     switchHintClassName?: string;
+    /** Trust-line paragraph className. */
     trustClassName?: string;
 };
-declare function PaywallCta({ ctaLabel, loadingLabel, switchHint, trustLine, onClick, disabled, loading, className, buttonClassName, switchHintClassName, trustClassName, }: PaywallCtaProps): react_jsx_runtime.JSX.Element;
+/**
+ * CTA button + switch hint + trust line. Reads `submit` + `submitting` from
+ * context — the button dispatches the checkout on click and disables itself
+ * while submitting. Apps wanting a different action (e.g. open a CPF modal
+ * first) should compose via `<Paywall onBeforeCheckout>` or use raw context
+ * with their own button.
+ */
+declare function PaywallCta({ ctaLabel, loadingLabel, switchHint, trustLine, className, buttonClassName, switchHintClassName, trustClassName, }: PaywallCtaProps): react_jsx_runtime.JSX.Element;
+
+type PaywallEyebrowProps = {
+    text: string;
+    className?: string;
+};
+declare function PaywallEyebrow({ text, className }: PaywallEyebrowProps): react_jsx_runtime.JSX.Element;
+
+type PaywallHeroRenderState = {
+    src: string;
+    headline?: string;
+};
+type PaywallHeroProps = {
+    src: string;
+    alt?: string;
+    headline?: string;
+    aspectRatio?: string;
+    gradientClassName?: string;
+    className?: string;
+    headlineClassName?: string;
+    imgClassName?: string;
+    render?: (state: PaywallHeroRenderState) => ReactNode;
+};
+declare function PaywallHero({ src, alt, headline, aspectRatio, gradientClassName, className, headlineClassName, imgClassName, render, }: PaywallHeroProps): react_jsx_runtime.JSX.Element;
+
+type PaywallHeadlineProps = {
+    text: string;
+    className?: string;
+    as?: 'h1' | 'h2';
+};
+declare function PaywallHeadline({ text, className, as }: PaywallHeadlineProps): react_jsx_runtime.JSX.Element;
+
+type PaywallPriceHeadlineProps = {
+    /**
+     * Copy template. Supported substitutions:
+     * - `{pricePerDay}` → daily price formatted (BRL), derived from yearly.
+     * - `{currentMonthlyEquiv}` → formatted monthly-equivalent BRL.
+     * - `{cycle}` → human-readable cycle ("mensal" | "anual").
+     *
+     * Example: `"Comece hoje por {pricePerDay} por dia"`.
+     */
+    template: string;
+    className?: string;
+    as?: 'h1' | 'h2' | 'h3';
+    render?: (state: {
+        pricePerDay: string;
+        currentMonthlyEquivCents: number;
+        cycle: string;
+    }) => ReactNode;
+};
+declare function PaywallPriceHeadline({ template, className, as, render, }: PaywallPriceHeadlineProps): react_jsx_runtime.JSX.Element;
+
+type PaywallCountdownRenderState = {
+    h: number;
+    m: number;
+    s: number;
+    expired: boolean;
+};
+type PaywallCountdownDeadline = Date | string | {
+    sessionStorageKey: string;
+    durationMs: number;
+};
+type PaywallCountdownProps = {
+    deadline: PaywallCountdownDeadline;
+    format?: 'h:m:s' | 'm:s';
+    onExpire?: () => void;
+    className?: string;
+    render?: (state: PaywallCountdownRenderState) => ReactNode;
+};
+declare function PaywallCountdown({ deadline, format, onExpire, className, render, }: PaywallCountdownProps): react_jsx_runtime.JSX.Element;
+
+type PaywallFeaturesRenderState = {
+    items: readonly string[];
+};
+type PaywallFeaturesProps = {
+    items: readonly string[];
+    IconComponent?: ComponentType<{
+        className?: string;
+    }>;
+    className?: string;
+    itemClassName?: string;
+    iconClassName?: string;
+    render?: (state: PaywallFeaturesRenderState) => ReactNode;
+    renderItem?: (item: string, idx: number) => ReactNode;
+};
+declare function PaywallFeatures({ items, IconComponent, className, itemClassName, iconClassName, render, renderItem, }: PaywallFeaturesProps): react_jsx_runtime.JSX.Element;
+
+type PaywallFeaturesCardProps = {
+    title?: string;
+    items: readonly string[];
+    className?: string;
+    cardClassName?: string;
+    titleClassName?: string;
+    itemClassName?: string;
+    renderItem?: (item: string, idx: number) => ReactNode;
+};
+declare function PaywallFeaturesCard({ title, items, className, cardClassName, titleClassName, itemClassName, renderItem, }: PaywallFeaturesCardProps): react_jsx_runtime.JSX.Element;
+
+type PaywallTrophyBadgeRenderState = {
+    text: string;
+};
+type PaywallTrophyBadgeProps = {
+    text: string;
+    className?: string;
+    iconClassName?: string;
+    floating?: boolean;
+    render?: (state: PaywallTrophyBadgeRenderState) => ReactNode;
+};
+declare function PaywallTrophyBadge({ text, className, iconClassName, floating, render, }: PaywallTrophyBadgeProps): react_jsx_runtime.JSX.Element;
+
+type PaywallAnchorPriceProps = {
+    className?: string;
+    render?: (state: {
+        anchorCents: number;
+        formatted: string;
+    }) => ReactNode;
+};
+declare function PaywallAnchorPrice({ className, render, }: PaywallAnchorPriceProps): react_jsx_runtime.JSX.Element | null;
+
+type PaywallTestimonial = {
+    name: string;
+    avatar?: string;
+    stars: number;
+    quote: string;
+};
+type PaywallTestimonialsProps = {
+    items: readonly PaywallTestimonial[];
+    className?: string;
+    cardClassName?: string;
+    avatarClassName?: string;
+    quoteClassName?: string;
+    nameClassName?: string;
+    starsClassName?: string;
+    renderItem?: (item: PaywallTestimonial, idx: number) => ReactNode;
+};
+declare function PaywallTestimonials({ items, className, cardClassName, avatarClassName, quoteClassName, nameClassName, starsClassName, renderItem, }: PaywallTestimonialsProps): react_jsx_runtime.JSX.Element;
+
+type PaywallStat = {
+    value: string;
+    label: string;
+    icon?: ReactNode;
+};
+type PaywallStatsRowProps = {
+    stats: readonly PaywallStat[];
+    className?: string;
+    cellClassName?: string;
+    valueClassName?: string;
+    labelClassName?: string;
+    renderCell?: (stat: PaywallStat, idx: number) => ReactNode;
+};
+declare function PaywallStatsRow({ stats, className, cellClassName, valueClassName, labelClassName, renderCell, }: PaywallStatsRowProps): react_jsx_runtime.JSX.Element;
+
+type PaywallFinePrintProps = {
+    /**
+     * Copy template. Supported substitutions:
+     * - `{price}` → formatted current price (BRL).
+     * - `{trialDays}` → method-specific trial days (card vs pix).
+     * - `{cycle}` → human-readable cycle ("mensal" | "anual").
+     */
+    template: string;
+    className?: string;
+    render?: (state: {
+        currentPriceCents: number;
+        cycle: string;
+        trialDays: number;
+        selectedMethod: string;
+    }) => ReactNode;
+};
+declare function PaywallFinePrint({ template, className, render, }: PaywallFinePrintProps): react_jsx_runtime.JSX.Element;
+
+type PaywallTrustLineItem = {
+    icon: ReactNode;
+    text: string;
+};
+type PaywallTrustLineProps = {
+    items: readonly PaywallTrustLineItem[];
+    className?: string;
+    itemClassName?: string;
+    renderItem?: (item: PaywallTrustLineItem, idx: number) => ReactNode;
+};
+declare function PaywallTrustLine({ items, className, itemClassName, renderItem, }: PaywallTrustLineProps): react_jsx_runtime.JSX.Element;
+
+type PaywallStickyFooterProps = {
+    children: ReactNode;
+    className?: string;
+    /**
+     * When true (default), appends `pb-[env(safe-area-inset-bottom)]` so the
+     * footer clears the home-indicator on iOS. Set false for footers that
+     * already opt into their own safe-area handling (e.g. inside a sheet).
+     */
+    safeAreaInsets?: boolean;
+};
+declare function PaywallStickyFooter({ children, className, safeAreaInsets, }: PaywallStickyFooterProps): react_jsx_runtime.JSX.Element;
 
-export { type AndroidBrowser, type AppConfig, AppConfigProvider, AppConfigSchema, AppRoot, type AppRootProps, type AppRootSlots, type AuthFlowConfig, type AuthFormError, type AuthFormErrorCode, type AuthScreenProps, type CheckoutMethod, type Cycle, type CycleLabels, DeepLinkHandler, type DeepLinks, DevSkipOnboardingFab, EmptyState, ErrorBoundary, type I18nConfig, I18nProvider, type I18nProviderProps, type IOSBrowser, type InAppApp, type InstallActions, InstallGate, InstallSplash, type InstallState, type InstallVariant, LanguageSwitcher, type LanguageSwitcherProps, LoadingState, type OnboardingConfig, OnboardingFlow, type OnboardingFlowProps, type OnboardingStep, type OnboardingStepCtx, type OnboardingStepDef, type PaymentMethod, PaymentReturnHandler, Paywall, type PaywallConfig, type PaywallCopy, PaywallCta, type PaywallCtaProps, PaywallCyclePicker, type PaywallCyclePickerProps, PaywallMethodContent, type PaywallMethodContentProps, type PaywallMethodCopy, PaywallMethodTabs, type PaywallMethodTabsProps, type PaywallProps, type PaywallSlots, type PaywallThemeClasses, type PersistedKey, PersistenceRegistry, type PersistenceRegistryProps, type PixPending, type Platform, PreAuthShell, type PreAuthShellProps, PushPrompt, type PushPromptProps, type PushPromptTexts, type PushUiState, RouteBoundary, type RouteBoundaryProps, type SkipDefaults, type SubscriptionStatus, type ToastItem, type UseLoginFormResult, type UseResetFormResult, asaasErrorMessage, computeAnchorCents, dailyFromYearly, detectAndroidBrowser, detectIOSBrowser, detectInAppApp, detectPlatform, detectStandalone, discountPercent, formatBRL, isDevToolsEnabled, monthlyFromYearly, parseAppConfig, shouldBlockInstall, shouldShowPermanentOption, skipOnboarding, useAppConfig, useAuth, useAuthPrimitives, useFeature, useForgotForm, useInstallPrompt, useLoginForm, useOnboardingStep, usePaywallState, usePlan, usePush, useReminders, useResetForm, useSignupForm, useSubscription, useToast };
+export { type AndroidBrowser, type AppConfig, AppConfigProvider, AppConfigSchema, AppRoot, type AppRootProps, type AppRootSlots, type AuthFlowConfig, type AuthFormError, type AuthFormErrorCode, type AuthScreenProps, type CheckoutMethod, type Cycle, type CycleLabels, DeepLinkHandler, type DeepLinks, DevSkipOnboardingFab, EmptyState, ErrorBoundary, type I18nConfig, I18nProvider, type I18nProviderProps, type IOSBrowser, type InAppApp, type InstallActions, InstallGate, InstallSplash, type InstallState, type InstallVariant, LanguageSwitcher, type LanguageSwitcherProps, LoadingState, type OnboardingConfig, OnboardingFlow, type OnboardingFlowProps, type OnboardingStep, type OnboardingStepCtx, type OnboardingStepDef, type PaymentMethod, PaymentReturnHandler, Paywall, PaywallAnchorPrice, type PaywallAnchorPriceProps, type PaywallConfig, PaywallContext, type PaywallContextValue, type PaywallCopy, PaywallCountdown, type PaywallCountdownProps, PaywallCta, type PaywallCtaProps, PaywallCyclePicker, type PaywallCyclePickerProps, PaywallEyebrow, type PaywallEyebrowProps, PaywallFeatures, PaywallFeaturesCard, type PaywallFeaturesCardProps, type PaywallFeaturesProps, PaywallFinePrint, type PaywallFinePrintProps, PaywallHeadline, type PaywallHeadlineProps, PaywallHero, type PaywallHeroProps, PaywallMethodContent, type PaywallMethodContentProps, type PaywallMethodCopy, PaywallMethodTabs, type PaywallMethodTabsProps, PaywallPriceHeadline, type PaywallPriceHeadlineProps, type PaywallProps, PaywallProvider, type PaywallProviderProps, type PaywallSlots, type PaywallStat, PaywallStatsRow, type PaywallStatsRowProps, PaywallStickyFooter, type PaywallStickyFooterProps, type PaywallTestimonial, PaywallTestimonials, type PaywallTestimonialsProps, type PaywallThemeClasses, PaywallTrophyBadge, type PaywallTrophyBadgeProps, PaywallTrustLine, type PaywallTrustLineProps, type PersistedKey, PersistenceRegistry, type PersistenceRegistryProps, type PixPending, type Platform, PreAuthShell, type PreAuthShellProps, PushPrompt, type PushPromptProps, type PushPromptTexts, type PushUiState, RouteBoundary, type RouteBoundaryProps, type SkipDefaults, type SubscriptionStatus, type ToastItem, type UseLoginFormResult, type UseResetFormResult, asaasErrorMessage, computeAnchorCents, dailyFromYearly, detectAndroidBrowser, detectIOSBrowser, detectInAppApp, detectPlatform, detectStandalone, discountPercent, formatBRL, isDevToolsEnabled, monthlyFromYearly, parseAppConfig, shouldBlockInstall, shouldShowPermanentOption, skipOnboarding, useAppConfig, useAuth, useAuthPrimitives, useFeature, useForgotForm, useInstallPrompt, useLoginForm, useOnboardingStep, usePaywallContext, usePaywallState, usePlan, usePush, useReminders, useResetForm, useSignupForm, useSubscription, useToast };