@fanfare-io/fanfare-sdk-react 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,58 @@
+# @fanfare-io/fanfare-sdk-react
+
+React components and hooks for [Fanfare](https://www.fanfare.io) controlled-access experiences, built on [@fanfare-io/fanfare-sdk-core](https://www.npmjs.com/package/@fanfare-io/fanfare-sdk-core).
+
+- `FanfareProvider` initializes the SDK and provides it to the tree
+- `ExperienceWidget` renders the full journey UI
+- `useExperienceJourney` exposes the same journey model for fully custom UI
+
+## States Covered
+
+The component surface is derived from the SDK journey model: `journeyStage`, then `sequence.phase`, then `sequence.mechanism`. The server stays authoritative over what is permitted.
+
+- `ready`: renders the start view and exposes `start(opts?)`.
+- `routing`: renders loading UI while the route is selected.
+- `gated`: renders auth, access-code, or challenge UI for the active gate.
+- `routed`: renders the sequence UI for `unavailable`, `scheduled`, `enterable`, `participating`, `settling`, `granted`, and `ended`.
+
+For routed journeys, the default widget renders `queue`, `draw`, `auction`, `timed_release`, and `appointment` modules across their supported phases. It renders waitlist entry through `UpcomingModule` and waitlist participation through `WaitlistView`. `settling` renders for `draw` and `auction`. `granted` renders for `queue`, `draw`, `auction`, and `timed_release`.
+
+## Install
+
+```bash
+npm install @fanfare-io/fanfare-sdk-core @fanfare-io/fanfare-sdk-react motion
+```
+
+Peer dependencies: `react`, `react-dom`, `motion`.
+
+## Usage
+
+```tsx
+import { ExperienceWidget, FanfareProvider } from "@fanfare-io/fanfare-sdk-react";
+import "@fanfare-io/fanfare-sdk-react/styles";
+
+export function App() {
+  return (
+    <FanfareProvider organizationId="org_123" publishableKey="pk_live_123">
+      <ExperienceWidget experienceId="exp_123" autoStart checkoutUrl="/checkout" />
+    </FanfareProvider>
+  );
+}
+```
+
+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.
+
+## Documentation
+
+- [React components guide](https://docs.fanfare.io/sdk/components/react)
+- [Theming](https://docs.fanfare.io/sdk/components/theming) · [Slots](https://docs.fanfare.io/sdk/components/slots)
+- [Next.js / SSR integration](https://docs.fanfare.io/guides/integration-patterns/ssr-integration)
+- [SDK overview](https://docs.fanfare.io/sdk/overview)
+- [Website](https://www.fanfare.io)
+- [Source & issues](https://github.com/fanfare-io/fanfare-sdk)
+
+## License
+
+[Apache-2.0](./LICENSE)

package/dist/components/auth/access-code-input.d.ts

@@ -0,0 +1,24 @@
+import { InputProps } from '../primitives/input';
+/**
+ * AccessCodeInput Component
+ *
+ * Simple text input for access/invite codes.
+ * Optionally auto-uppercases input for case-insensitive codes.
+ * Composes the Input primitive for consistent styling across variants.
+ */
+import * as React from "react";
+export interface AccessCodeInputProps extends Omit<InputProps, "onChange" | "type" | "value"> {
+    /** Current input value */
+    value: string;
+    /** Called when value changes */
+    onValueChange: (value: string) => void;
+    /** Called when Enter is pressed */
+    onSubmit?: () => void;
+    /** External error message */
+    error?: string;
+    /** Visual error state without inline text (e.g. when an AlertPanel owns the message). */
+    hasError?: boolean;
+    /** Auto-uppercase input */
+    autoUppercase?: boolean;
+}
+export declare const AccessCodeInput: React.ForwardRefExoticComponent<AccessCodeInputProps & React.RefAttributes<HTMLInputElement>>;

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

@@ -0,0 +1,39 @@
+import { PanelHeadingVariant } from '../module';
+import { AuthInputMode } from './auth-input';
+/**
+ * AuthForm Component
+ *
+ * Complete two-step authentication flow: credential entry → OTP verification → success.
+ */
+import * as React from "react";
+export interface AuthFormProps {
+    onSubmit?: (credential: string, type: AuthInputMode) => Promise<void>;
+    onVerify?: (otp: string) => Promise<void>;
+    onSkip?: () => void;
+    onSuccess?: () => void;
+    /** Badge color/intent in the panel heading. */
+    variant?: PanelHeadingVariant;
+    /** Badge text in the panel heading. Defaults to `auth.badgeLabel`. */
+    label?: React.ReactNode;
+    title?: string;
+    description?: string;
+    /** When set, renders a countdown above the form. */
+    countdownTo?: Date;
+    submitLabel?: string;
+    verifyLabel?: string;
+    allowSkip?: boolean;
+    showBranding?: 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"`. */
+    defaultCredential?: string;
+    /** Initial credential type — pairs with `defaultStep="verify"`. */
+    defaultCredentialType?: AuthInputMode;
+    /** Initial error message when mounting. Cleared on the next input change. */
+    defaultError?: string;
+    className?: string;
+}
+export declare function AuthForm({ onSubmit, onVerify, onSkip, onSuccess, variant, label: labelProp, title: titleProp, description: descriptionProp, countdownTo, submitLabel: submitLabelProp, verifyLabel: verifyLabelProp, allowSkip, showBranding, defaultStep, defaultCredential, defaultCredentialType, defaultError, className, }: AuthFormProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace AuthForm {
+    var displayName: string;
+}

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

@@ -0,0 +1,28 @@
+import { InputProps } from '../primitives/input';
+/**
+ * AuthInput Component
+ *
+ * Smart input that handles both email and phone credentials.
+ * Can auto-detect input type or show a manual toggle.
+ * Composes the Input primitive for consistent styling across variants.
+ */
+import * as React from "react";
+export type AuthInputMode = "email" | "phone";
+export interface AuthInputProps extends Omit<InputProps, "onChange" | "type" | "value"> {
+    /** Current input value */
+    value: string;
+    /** Called when value changes (returns email or E.164 phone) */
+    onValueChange: (value: string, mode: AuthInputMode) => void;
+    /** Called when validity changes */
+    onValidChange?: (isValid: boolean) => void;
+    /** Called when Enter is pressed */
+    onSubmit?: () => void;
+    /** Input mode: email, phone, or auto (shows toggle) */
+    type?: AuthInputMode | "auto";
+    /** External error message (overrides internal validation) */
+    error?: string;
+    /** Visual error state without inline text (e.g. when an AlertPanel owns the message). */
+    hasError?: boolean;
+}
+export declare function detectInputMode(value: string): AuthInputMode;
+export declare const AuthInput: React.ForwardRefExoticComponent<AuthInputProps & React.RefAttributes<HTMLInputElement>>;

package/dist/components/auth/email-input.d.ts

@@ -0,0 +1,21 @@
+import { InputProps } from '../primitives/input';
+/**
+ * EmailInput Component
+ *
+ * Validated email input with real-time validation feedback.
+ * Composes the Input primitive for consistent styling across variants.
+ */
+import * as React from "react";
+export interface EmailInputProps extends Omit<InputProps, "onChange" | "type" | "value"> {
+    /** Current input value */
+    value: string;
+    /** Called when value changes */
+    onValueChange: (value: string) => void;
+    /** Called when validity changes */
+    onValidChange?: (isValid: boolean) => void;
+    /** Called when Enter is pressed */
+    onSubmit?: () => void;
+    /** External error message (overrides internal validation) */
+    error?: string;
+}
+export declare const EmailInput: React.ForwardRefExoticComponent<EmailInputProps & React.RefAttributes<HTMLInputElement>>;

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

@@ -0,0 +1,19 @@
+/**
+ * Authentication Components
+ *
+ * Input components for authentication flows including email, phone, OTP, and access codes.
+ *
+ * @packageDocumentation
+ */
+export { AccessCodeInput } from './access-code-input';
+export type { AccessCodeInputProps } from './access-code-input';
+export { AuthForm } from './auth-form';
+export type { AuthFormProps } from './auth-form';
+export { AuthInput } from './auth-input';
+export type { AuthInputMode, AuthInputProps } from './auth-input';
+export { EmailInput } from './email-input';
+export type { EmailInputProps } from './email-input';
+export { OTPInput } from './otp-input';
+export type { OTPInputProps } from './otp-input';
+export { PhoneInput } from './phone-input';
+export type { PhoneInputProps } from './phone-input';

package/dist/components/auth/otp-input.d.ts

@@ -0,0 +1,32 @@
+/**
+ * OTPInput Component
+ *
+ * 6-digit verification code input with auto-advance.
+ * Supports keyboard navigation, paste handling, and iOS OTP autofill.
+ * Uses theme CSS variables for consistent styling.
+ */
+import * as React from "react";
+export interface OTPInputProps {
+    /** Current OTP value */
+    value?: string;
+    /** Called when value changes */
+    onChange?: (value: string) => void;
+    /** Called when all digits are filled */
+    onComplete?: (value: string) => void;
+    /** Number of digits */
+    length?: number;
+    /** Error message — when set, renders below the digits in red. */
+    error?: string;
+    /**
+     * Visual error state without inline text. Use when the message is rendered
+     * elsewhere (e.g. an AlertPanel) but the digits should still show danger styling.
+     */
+    hasError?: boolean;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Auto focus first input */
+    autoFocus?: boolean;
+    /** Additional class name */
+    className?: string;
+}
+export declare const OTPInput: React.ForwardRefExoticComponent<OTPInputProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/auth/phone-input.d.ts

@@ -0,0 +1,22 @@
+import { InputProps } from '../primitives/input';
+/**
+ * PhoneInput Component
+ *
+ * Phone input with automatic formatting and E.164 normalization.
+ * Displays formatted phone number while returning E.164 format to parent.
+ * Composes the Input primitive for consistent styling across variants.
+ */
+import * as React from "react";
+export interface PhoneInputProps extends Omit<InputProps, "onChange" | "type" | "value"> {
+    /** Current value (E.164 format or raw digits) */
+    value: string;
+    /** Called when value changes (returns E.164 format when valid, raw otherwise) */
+    onValueChange: (value: string) => void;
+    /** Called when validity changes */
+    onValidChange?: (isValid: boolean) => void;
+    /** Called when Enter is pressed */
+    onSubmit?: () => void;
+    /** External error message (overrides internal validation) */
+    error?: string;
+}
+export declare const PhoneInput: React.ForwardRefExoticComponent<PhoneInputProps & React.RefAttributes<HTMLInputElement>>;

package/dist/components/compositions/access-code-form.d.ts

@@ -0,0 +1,29 @@
+import { PanelHeadingVariant } from '../module';
+/**
+ * AccessCodeForm Component
+ *
+ * Access code entry with submit button for gated experiences.
+ */
+import * as React from "react";
+export interface AccessCodeFormProps {
+    onSubmit?: (code: string) => Promise<void>;
+    onSkip?: () => void;
+    /** Badge color/intent in the panel heading. */
+    variant?: PanelHeadingVariant;
+    /** Badge text in the panel heading. Defaults to `accessCode.badgeLabel`. */
+    label?: React.ReactNode;
+    title?: string;
+    description?: string;
+    /** When set, renders a countdown above the form. */
+    countdownTo?: Date;
+    submitLabel?: string;
+    allowSkip?: boolean;
+    autoUppercase?: boolean;
+    /** Initial error message when mounting. Cleared on the next input change. */
+    defaultError?: string;
+    className?: string;
+}
+export declare function AccessCodeForm({ onSubmit, onSkip, variant, label: labelProp, title: titleProp, description: descriptionProp, countdownTo, submitLabel: submitLabelProp, allowSkip, autoUppercase, defaultError, className, }: AccessCodeFormProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace AccessCodeForm {
+    var displayName: string;
+}

package/dist/components/compositions/challenge-gate.d.ts

@@ -0,0 +1,23 @@
+import { BotMitigationState, RoutingChallenge } from '@fanfare-io/fanfare-sdk-core/challenges';
+import { PanelHeadingVariant } from '../module';
+import * as React from "react";
+export interface ChallengeGateProps {
+    challenge: RoutingChallenge | null;
+    botMitigation?: BotMitigationState;
+    onVerifyToken: (token: string) => Promise<void>;
+    onRetry?: () => void;
+    /** Badge color/intent in the panel heading. */
+    variant?: PanelHeadingVariant;
+    /** Badge text in the panel heading. Defaults to `challenge.badgeLabel`. */
+    label?: React.ReactNode;
+    title?: string;
+    description?: string;
+    /** When set, renders a countdown above the challenge. */
+    countdownTo?: Date;
+    retryLabel?: string;
+    className?: string;
+}
+export declare function ChallengeGate({ challenge, botMitigation, onVerifyToken, onRetry, variant, label: labelProp, title, description, countdownTo, retryLabel, className, }: ChallengeGateProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ChallengeGate {
+    var displayName: string;
+}

package/dist/components/compositions/ended-module.d.ts

@@ -0,0 +1,26 @@
+/**
+ * EndedModule
+ *
+ * Terminal-state fallback for journeys with no distribution to route to.
+ * Per-distribution modules own their own lost / outcome state; this module is the non-distribution
+ * edge case (the user landed on an experience that has no upcoming, active,
+ * or recent distribution).
+ */
+export interface EndedModuleProps {
+    /** Title text */
+    title?: string;
+    /** Body message */
+    message?: string;
+    /** When the distribution ended */
+    endedAt?: Date | number;
+    /** CTA button label */
+    ctaLabel?: string;
+    /** CTA click handler */
+    onCtaClick?: () => void;
+    /** Additional class name */
+    className?: string;
+}
+export declare function EndedModule({ title, message, endedAt, ctaLabel, onCtaClick, className }: EndedModuleProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace EndedModule {
+    var displayName: string;
+}

package/dist/components/compositions/error-view.d.ts

@@ -0,0 +1,58 @@
+/**
+ * ErrorView Composition
+ *
+ * Standard error panel. Same PanelLayout chrome as every other panel, with:
+ * - PanelHeading badge ("Error" by default, variant="danger")
+ * - AlertPanel callout containing title + description
+ * - Optional InfoPanel slot for structured context (caller provides children)
+ * - Optional retry CTA
+ *
+ * For the truly generic case, callers pass nothing — defaults from i18n
+ * (`error.label` / `error.title` / `error.description`) fill the panel.
+ *
+ *   // Generic
+ *   <ErrorView />
+ *
+ *   // Generic with retry
+ *   <ErrorView onRetry={refetch} />
+ *
+ *   // Specific error with structured context (e.g. card declined)
+ *   <ErrorView
+ *     label={t("checkout.actionNeeded")}
+ *     title={t("payment.cardDeclined")}
+ *     error={t("payment.cardDeclinedDetail", { amount })}
+ *     info={
+ *       <>
+ *         <InfoRow label="Attempted card" value="•••• 4242" />
+ *         <InfoRow label="Decline code" value="generic_decline" />
+ *       </>
+ *     }
+ *     ctaLabel={t("payment.tryDifferentCard")}
+ *     onRetry={handleTryDifferentCard}
+ *   />
+ *
+ * For structurally different layouts (e.g. needing a step indicator alongside
+ * the badge in the header), write a sibling composition that uses the same
+ * primitives directly — do not extend or wrap ErrorView.
+ */
+import * as React from "react";
+export interface ErrorViewProps {
+    /** Description shown inside the AlertPanel. Falls back to `t("error.description")`. */
+    error?: Error | string;
+    /** Title shown inside the AlertPanel. Falls back to `t("error.title")`. */
+    title?: React.ReactNode;
+    /** Badge text in the PanelHeading. Falls back to `t("error.label")`. */
+    label?: React.ReactNode;
+    /** Structured context to display below the AlertPanel. Omitted entirely when not provided. */
+    info?: React.ReactNode;
+    /** Retry button label. Falls back to `t("error.retry")`. */
+    ctaLabel?: React.ReactNode;
+    /** Retry callback. When provided, a CTA button is rendered. */
+    onRetry?: () => void | Promise<void>;
+    /** Additional class name */
+    className?: string;
+}
+export declare function ErrorView({ error, title, label, info, ctaLabel, onRetry, className }: ErrorViewProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace ErrorView {
+    var displayName: string;
+}

package/dist/components/compositions/granted-panel.d.ts

@@ -0,0 +1,35 @@
+/**
+ * GrantedPanel
+ *
+ * Shared granted composition for distribution modules. Renders the
+ * winning-state panel: status badge, expiry countdown (or fallback message
+ * when no expiry is known), and a checkout CTA. Used by queue / draw /
+ * auction / timed-release modules — the JSX is structurally identical
+ * across all four; only the i18n strings differ.
+ *
+ *   <GrantedPanel
+ *     label="Congratulations!"
+ *     fallbackMessage="Proceed to checkout"
+ *     ctaLabel="Continue"
+ *     expiresAt={grantExpiry}
+ *     onCtaClick={openCheckout}
+ *   />
+ *
+ * `useGrantCelebration` fires the celebration animation against the
+ * hero region — must be invoked unconditionally per React hook rules,
+ * which is why this lives in its own component (each module's granted
+ * branch returns `<GrantedPanel ... />` instead of inlining the JSX).
+ */
+import * as React from "react";
+export interface GrantedPanelProps {
+    label: React.ReactNode;
+    fallbackMessage: React.ReactNode;
+    ctaLabel: React.ReactNode;
+    expiresAt?: Date;
+    onCtaClick: () => void;
+    className?: string;
+}
+export declare function GrantedPanel({ label, fallbackMessage, ctaLabel, expiresAt, onCtaClick, className, }: GrantedPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace GrantedPanel {
+    var displayName: string;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Composition Components
+ *
+ * Reusable sections that combine primitives for common widget patterns.
+ * These handle journey gates, granted views, error states, and more.
+ *
+ * @packageDocumentation
+ */
+export { JourneyGate, type JourneyGateProps, type JourneyGateStage } from './journey-gate';
+export { ChallengeGate, type ChallengeGateProps } from './challenge-gate';
+export { AccessCodeForm, type AccessCodeFormProps } from './access-code-form';
+export { GrantedPanel, type GrantedPanelProps } from './granted-panel';
+export { OutcomePanel, type OutcomePanelProps } from './outcome-panel';
+export { EndedModule, type EndedModuleProps } from './ended-module';
+export { ErrorView, type ErrorViewProps } from './error-view';