@ss-dev/agnostic-checkout 0.1.12

package/README.md

@@ -0,0 +1,439 @@
+# ⚡ Agnostic Checkout SDK
+
+A provider-agnostic, embeddable React checkout component with dynamic theming, plugin architecture, and full TypeScript support.
+
+---
+
+## Features
+
+- 🛒 **Embeddable checkout component** — drop into any React app
+- 🎨 **Theme system** — 5 built-in presets (`light`, `dark`, `minimal`, `corporate`, `neon`)
+- 🎯 **Brand Auto Theme** — generate a full theme from a single brand color
+- 🔌 **Plugin architecture** — extend checkout behavior without modifying core code
+- 🏷️ **Discount Plugin** — coupon input, apply/remove with event-driven updates
+- ✏️ **Cart Edit Plugin** — quantity stepper, item removal with configurable limits
+- 🌍 **i18n** — built-in locales (`en`, `es`, `pt-BR`, `auto`)
+- 💱 **Multi-currency** — 25+ currencies with automatic formatting
+- 📱 **Responsive** — mobile-first layout with collapsible order summary
+- 🔒 **Provider-agnostic** — works with any payment backend
+
+---
+
+## Installation
+
+```bash
+npm install agnostic-checkout
+```
+
+---
+
+## Quick Start
+
+```tsx
+import { Checkout } from "agnostic-checkout";
+
+function App() {
+  const items = [
+    {
+      id: "item_1",
+      name: "Pro Plan",
+      unitPrice: 49.00,
+      quantity: 1,
+      total: 49.00,
+      image: "https://example.com/pro-plan.png",
+    },
+  ];
+
+  const totals = {
+    subtotal: 49.00,
+    taxes: 4.90,
+    total: 53.90,
+  };
+
+  const paymentMethods = [
+    {
+      id: "pm_card",
+      label: "Credit Card",
+      type: "card",
+    },
+  ];
+
+  return (
+    <Checkout
+      items={items}
+      totals={totals}
+      paymentMethods={paymentMethods}
+      provider={yourPaymentProvider}
+      currency="USD"
+      locale="en"
+    />
+  );
+}
+```
+
+| Prop | Description |
+|---|---|
+| `items` | Array of cart items to display |
+| `totals` | Object with subtotal, taxes, shipping, discount, and total |
+| `paymentMethods` | Available payment methods |
+| `provider` | Your `PaymentProvider` implementation |
+| `currency` | Currency code for formatting (`"USD"`, `"EUR"`, etc.) |
+| `locale` | Language for UI text (`"en"`, `"es"`, `"pt-BR"`, `"auto"`) |
+
+---
+
+## Theming
+
+The checkout uses CSS variables internally and supports three theming strategies with the following priority chain:
+
+```
+customTheme (overrides)
+       ↓
+brandColor (auto-generated theme)
+       ↓
+theme preset ("light" | "dark" | ...)
+```
+
+### Preset Themes
+
+Choose from 5 built-in themes:
+
+```tsx
+<Checkout theme="light" />
+<Checkout theme="dark" />
+<Checkout theme="minimal" />
+<Checkout theme="corporate" />
+<Checkout theme="neon" />
+```
+
+### Brand Auto Theme
+
+Generate a complete theme from a single brand color. The SDK automatically derives background, surface, text, border, and accent colors:
+
+```tsx
+<Checkout brandColor="#6366F1" />
+```
+
+### Custom Theme Overrides
+
+Override specific tokens on top of any base theme:
+
+```tsx
+<Checkout
+  theme="light"
+  customTheme={{
+    colors: {
+      primary: "#ff0055",
+      success: "#00cc88",
+    },
+    radius: "1rem",
+  }}
+/>
+```
+
+Combine with `brandColor`:
+
+```tsx
+<Checkout
+  brandColor="#6366F1"
+  customTheme={{
+    radius: "20px",
+    fontFamily: "'Poppins', sans-serif",
+  }}
+/>
+```
+
+### Theme Tokens
+
+| Token | CSS Variable | Description |
+|---|---|---|
+| `colors.primary` | `--color-primary` | Buttons, links, active states |
+| `colors.background` | `--color-background` | Page background |
+| `colors.surface` | `--color-surface` | Card/panel backgrounds |
+| `colors.text` | `--color-text` | Primary text color |
+| `colors.border` | `--color-border` | Borders and dividers |
+| `colors.success` | `--color-success` | Success states, discounts |
+| `colors.error` | `--color-error` | Error states, remove actions |
+| `radius` | `--theme-radius` | Border radius for cards/buttons |
+| `fontFamily` | `--theme-font` | Font family stack |
+
+---
+
+## Plugin System
+
+Plugins extend checkout functionality through a **slot-based architecture**. Plugins inject UI into predefined areas and communicate via events — they never modify state directly.
+
+```tsx
+import { createDiscountPlugin, createCartEditPlugin } from "agnostic-checkout/plugins";
+
+<Checkout
+  plugins={[
+    createDiscountPlugin(handleEvent),
+    createCartEditPlugin(handleEvent, { allowRemove: true }),
+  ]}
+  onEvent={handleEvent}
+/>
+```
+
+Plugins emit events. Your `onEvent` handler processes them and updates `items`/`totals` externally:
+
+```tsx
+const handleEvent = (event) => {
+  switch (event.type) {
+    case "COUPON_APPLY_REQUESTED":
+      // Validate event.code, update items/totals
+      break;
+    case "ITEM_REMOVE_REQUESTED":
+      // Remove item by event.itemId
+      break;
+    case "ITEM_QUANTITY_UPDATE_REQUESTED":
+      // Update quantity for event.itemId to event.quantity
+      break;
+  }
+};
+```
+
+---
+
+## Discount Plugin
+
+Adds a coupon input field to the order summary. Users can type a discount code, apply it, and remove it via a trash icon.
+
+```tsx
+import { createDiscountPlugin } from "agnostic-checkout/plugins";
+
+const plugins = [
+  createDiscountPlugin(handleEvent),
+];
+```
+
+**Events emitted:**
+
+| Event | Payload | Description |
+|---|---|---|
+| `COUPON_APPLY_REQUESTED` | `{ code: string }` | User submitted a coupon code |
+| `COUPON_REMOVE_REQUESTED` | — | User clicked the remove button |
+
+The plugin does **not** calculate discounts. Your `onEvent` handler validates the code and updates `items`/`totals` with the new discount values.
+
+---
+
+## Cart Edit Plugin
+
+Allows users to modify item quantities and/or remove items from the cart.
+
+```tsx
+import { createCartEditPlugin } from "agnostic-checkout/plugins";
+
+const plugins = [
+  createCartEditPlugin(handleEvent, {
+    allowRemove: true,
+    allowQuantityEdit: true,
+    minQuantity: 1,
+    maxQuantity: 10,
+  }),
+];
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `allowRemove` | `boolean` | `false` | Show remove button per item |
+| `allowQuantityEdit` | `boolean` | `false` | Show quantity stepper per item |
+| `minQuantity` | `number` | `1` | Minimum allowed quantity |
+| `maxQuantity` | `number` | `99` | Maximum allowed quantity |
+
+**Events emitted:**
+
+| Event | Payload | Description |
+|---|---|---|
+| `ITEM_QUANTITY_UPDATE_REQUESTED` | `{ itemId, quantity }` | User changed item quantity |
+| `ITEM_REMOVE_REQUESTED` | `{ itemId }` | User clicked remove |
+
+---
+
+## Payment Provider
+
+The checkout is payment-agnostic. Implement the `PaymentProvider` interface to connect any backend:
+
+```tsx
+interface PaymentProvider {
+  initialize?(config: unknown): Promise<void>;
+  createPayment(data: unknown): Promise<PaymentResult>;
+  confirmPayment?(data: unknown): Promise<PaymentResult>;
+}
+```
+
+```tsx
+class StripeProvider implements PaymentProvider {
+  async createPayment(data) {
+    const response = await fetch("/api/payments", {
+      method: "POST",
+      body: JSON.stringify(data),
+    });
+    return { status: "success" };
+  }
+}
+
+<Checkout provider={new StripeProvider()} />
+```
+
+---
+
+## API Reference
+
+### `<Checkout />` Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `items` | `CheckoutItem[]` | ✅ | — | Cart items |
+| `totals` | `CheckoutTotals` | ✅ | — | Order totals |
+| `paymentMethods` | `PaymentMethod[]` | ✅ | — | Available payment methods |
+| `provider` | `PaymentProvider` | ✅ | — | Payment provider implementation |
+| `currency` | `SupportedCurrency` | ✅ | — | Currency code |
+| `locale` | `CheckoutLocale` | — | `"es"` | UI language |
+| `theme` | `CheckoutThemeName \| Partial<CheckoutTheme>` | — | `"light"` | Theme preset or partial theme object |
+| `brandColor` | `string` | — | — | Auto-generate theme from hex color |
+| `customTheme` | `Partial<CheckoutTheme>` | — | — | Override specific theme tokens |
+| `onEvent` | `EventHandler` | — | — | Callback for checkout events |
+| `plugins` | `CheckoutPlugin[]` | — | `[]` | Plugins to extend functionality |
+| `messages` | `Partial<CheckoutMessages>` | — | — | Override default UI text |
+| `formatters` | `CheckoutFormatters` | — | — | Custom currency formatter |
+| `devTools` | `boolean` | — | `false` | Show dev tools panel |
+| `initialState` | `PaymentResult` | — | — | Start in a specific state |
+
+### `CheckoutItem`
+
+```tsx
+interface CheckoutItem {
+  id: string;
+  name: string;
+  quantity: number;
+  unitPrice: number;
+  total: number;
+  image?: string;
+  discount?: {
+    type: "percentage" | "fixed";
+    value: number;
+    label?: string;
+  };
+}
+```
+
+### `CheckoutTotals`
+
+```tsx
+interface CheckoutTotals {
+  subtotal: number;
+  discount?: number;
+  taxes?: number;
+  shipping?: number;
+  total: number;
+}
+```
+
+### Events
+
+| Event | Description |
+|---|---|
+| `CHECKOUT_VIEWED` | Checkout component mounted |
+| `STEP_CHANGED` | User navigated to a new step |
+| `PAYMENT_METHOD_SELECTED` | User selected a payment method |
+| `PAYMENT_SUBMITTED` | Payment form submitted |
+| `PAYMENT_SUCCESS` | Payment completed successfully |
+| `PAYMENT_ERROR` | Payment failed |
+| `COUPON_APPLY_REQUESTED` | Coupon code submitted (Discount Plugin) |
+| `COUPON_REMOVE_REQUESTED` | Coupon removed (Discount Plugin) |
+| `ITEM_QUANTITY_UPDATE_REQUESTED` | Quantity changed (Cart Edit Plugin) |
+| `ITEM_REMOVE_REQUESTED` | Item removed (Cart Edit Plugin) |
+
+---
+
+## Internationalization
+
+Built-in support for three locales plus automatic detection:
+
+```tsx
+<Checkout locale="en" />     // English
+<Checkout locale="es" />     // Spanish
+<Checkout locale="pt-BR" />  // Portuguese (Brazil)
+<Checkout locale="auto" />   // Auto-detect from browser
+```
+
+Override specific messages:
+
+```tsx
+<Checkout
+  messages={{
+    payNow: "Complete Purchase",
+    continueToPay: "Proceed to Payment",
+  }}
+/>
+```
+
+Custom currency formatter:
+
+```tsx
+<Checkout
+  formatters={{
+    currency: (amount) => `US$ ${amount.toFixed(2)}`,
+  }}
+/>
+```
+
+---
+
+## Demo
+
+A built-in demo page is available with interactive controls:
+
+```bash
+npm run dev
+```
+
+The demo includes a **Settings toolbar** to test:
+
+- Theme switching (5 presets + Brand Auto Theme)
+- Locale and currency changes
+- Item count adjustments
+- Plugin enable/disable toggles
+- Brand color picker with 12 presets
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Type checking
+npx tsc --noEmit
+
+# Build
+npm run build
+```
+
+### Project Structure
+
+```
+src/
+├── core/               # State machine, context, events, types
+├── theme/              # Theme system, tokens, color utilities
+├── locales/            # i18n messages (en, es, pt-BR)
+├── plugins/            # Plugin system, discount & cart-edit plugins
+├── ui/                 # React components (Checkout, Layout, Summary, etc.)
+├── hooks/              # useCheckout hook
+├── lib/                # Utilities (cn, formatNumber)
+└── mock/               # Demo app, mock provider, toolbar
+```
+
+---
+
+## License
+
+MIT

package/dist/components/accordion-layout.d.ts

@@ -0,0 +1,3 @@
+import { AccordionLayoutProps } from './types';
+export declare const AccordionLayout: ({ hasShipping }: AccordionLayoutProps) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=accordion-layout.d.ts.map

package/dist/components/accordion-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accordion-layout.d.ts","sourceRoot":"","sources":["../../src/components/accordion-layout.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD,eAAO,MAAM,eAAe,GAAI,iBAAiB,oBAAoB,4CA4OpE,CAAC"}

package/dist/components/checkout-content.d.ts

@@ -0,0 +1,5 @@
+export declare const CheckoutContent: ({ devTools, layout, }: {
+    devTools?: boolean;
+    layout?: "single-page" | "accordion";
+}) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=checkout-content.d.ts.map

package/dist/components/checkout-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-content.d.ts","sourceRoot":"","sources":["../../src/components/checkout-content.tsx"],"names":[],"mappings":"AAgBA,eAAO,MAAM,eAAe,GAAI,uBAG7B;IACC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,aAAa,GAAG,WAAW,CAAC;CACxC,4CAuFA,CAAC"}

package/dist/components/checkout-layout.d.ts

@@ -0,0 +1,3 @@
+import { CheckoutLayoutProps } from './types';
+export declare const CheckoutLayout: ({ children, sidebar, className, ...props }: CheckoutLayoutProps) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=checkout-layout.d.ts.map

package/dist/components/checkout-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-layout.d.ts","sourceRoot":"","sources":["../../src/components/checkout-layout.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD,eAAO,MAAM,cAAc,GAAI,4CAA4C,mBAAmB,4CA8B7F,CAAC"}

package/dist/components/checkout.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { CheckoutProps } from './types';
+export declare const Checkout: React.FC<CheckoutProps>;
+//# sourceMappingURL=checkout.d.ts.map

package/dist/components/checkout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../../src/components/checkout.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAK1B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAK7C,eAAO,MAAM,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC,aAAa,CAkD5C,CAAC"}

package/dist/components/dev-tools.d.ts

@@ -0,0 +1,3 @@
+export declare const DevTools: () => import("react/jsx-runtime").JSX.Element;
+export default DevTools;
+//# sourceMappingURL=dev-tools.d.ts.map

package/dist/components/dev-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-tools.d.ts","sourceRoot":"","sources":["../../src/components/dev-tools.tsx"],"names":[],"mappings":"AAeA,eAAO,MAAM,QAAQ,+CAsGpB,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/dist/components/feedback-screen.d.ts

@@ -0,0 +1,3 @@
+import { FeedbackScreenProps } from './types';
+export declare const FeedbackScreen: ({ title, description, actions, variant, actionsLayout, children, }: FeedbackScreenProps) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=feedback-screen.d.ts.map

package/dist/components/feedback-screen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-screen.d.ts","sourceRoot":"","sources":["../../src/components/feedback-screen.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,SAAS,CAAC;AA4BlE,eAAO,MAAM,cAAc,GAAI,oEAO5B,mBAAmB,4CAwFrB,CAAC"}

package/dist/components/mobile-bar.d.ts

@@ -0,0 +1,3 @@
+import { MobileBarProps } from './types';
+export declare const MobileBar: ({ step, hasShipping, layout }: MobileBarProps) => import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=mobile-bar.d.ts.map

package/dist/components/mobile-bar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mobile-bar.d.ts","sourceRoot":"","sources":["../../src/components/mobile-bar.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,eAAO,MAAM,SAAS,GAAI,+BAA+C,cAAc,mDAgDtF,CAAC"}

package/dist/components/mobile-order-bar.d.ts

@@ -0,0 +1,3 @@
+import { MobileOrderBarProps } from './types';
+export declare const MobileOrderBar: ({ onAction, actionLabel, actionDisabled, isSubmitting, showItems, }: MobileOrderBarProps) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=mobile-order-bar.d.ts.map

package/dist/components/mobile-order-bar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mobile-order-bar.d.ts","sourceRoot":"","sources":["../../src/components/mobile-order-bar.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD,eAAO,MAAM,cAAc,GAAI,qEAM5B,mBAAmB,4CAuHrB,CAAC"}

package/dist/components/order-sidebar-summary.d.ts

@@ -0,0 +1,3 @@
+import { OrderSidebarSummaryProps } from './types';
+export declare const OrderSidebarSummary: ({ showItems: propShowItems, isLoading, hasShipping, layout }: OrderSidebarSummaryProps) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=order-sidebar-summary.d.ts.map

package/dist/components/order-sidebar-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"order-sidebar-summary.d.ts","sourceRoot":"","sources":["../../src/components/order-sidebar-summary.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAGxD,eAAO,MAAM,mBAAmB,GAAI,8DAA8E,wBAAwB,4CA8HzI,CAAC"}

package/dist/components/order-summary.d.ts

@@ -0,0 +1,4 @@
+export declare const OrderSummary: ({ hideHeader }?: {
+    hideHeader?: boolean;
+}) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=order-summary.d.ts.map

package/dist/components/order-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"order-summary.d.ts","sourceRoot":"","sources":["../../src/components/order-summary.tsx"],"names":[],"mappings":"AAMA,eAAO,MAAM,YAAY,GAAI,iBAAgB;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,4CA+EzE,CAAC"}

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

@@ -0,0 +1,2 @@
+export declare const PaymentForm: () => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=payment-form.d.ts.map

package/dist/components/payment-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-form.d.ts","sourceRoot":"","sources":["../../src/components/payment-form.tsx"],"names":[],"mappings":"AAKA,eAAO,MAAM,WAAW,+CA+FvB,CAAC"}

package/dist/components/payment-methods.d.ts

@@ -0,0 +1,4 @@
+export declare const PaymentMethods: ({ hideHeader }?: {
+    hideHeader?: boolean;
+}) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=payment-methods.d.ts.map

package/dist/components/payment-methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-methods.d.ts","sourceRoot":"","sources":["../../src/components/payment-methods.tsx"],"names":[],"mappings":"AAiBA,eAAO,MAAM,cAAc,GAAI,iBAAgB;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,4CA4E3E,CAAC"}

package/dist/components/shipping-methods.d.ts

@@ -0,0 +1,3 @@
+import { ShippingMethodsProps } from './types';
+export declare const ShippingMethods: ({ methods, hideHeader }: ShippingMethodsProps) => import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=shipping-methods.d.ts.map

package/dist/components/shipping-methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shipping-methods.d.ts","sourceRoot":"","sources":["../../src/components/shipping-methods.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD,eAAO,MAAM,eAAe,GAAI,yBAAyB,oBAAoB,4CAyD5E,CAAC"}

package/dist/components/types.d.ts

@@ -0,0 +1,105 @@
+import { ReactNode } from 'react';
+import { EventHandler } from '../core/event-system';
+import { PaymentProvider } from '../core/provider.interface';
+import { CartController, CheckoutItem, CheckoutTotals, FractalButtonVariant, PaymentMethod, PaymentResult } from '../core/types';
+import { CheckoutTheme, CheckoutThemeName } from '../theme/tokens';
+import { CheckoutMessages, CheckoutFormatters, SupportedCurrency, CheckoutLocale } from '../locales/types';
+import { CheckoutPlugin } from '../plugins/types';
+import { ShippingMethod } from '../plugins/shipping-plugin';
+export interface CheckoutProps {
+    /** Array of items currently in the cart to be displayed in the order summary. */
+    items: CheckoutItem[];
+    /** Calculated totals including subtotal, taxes, shipping, discounts, and final total. */
+    totals: CheckoutTotals;
+    /** Available payment methods to present to the user (e.g., credit card, PayPal, etc.). */
+    paymentMethods: PaymentMethod[];
+    /** The core payment provider integration responsible for processing the payment. */
+    provider: PaymentProvider;
+    /** Currency code used for formatting prices (e.g., 'USD', 'EUR', 'ARS'). */
+    currency: SupportedCurrency;
+    /** Locale applied for internationalization and formatting (e.g., 'en', 'es'). Defaults to 'en'. */
+    locale?: CheckoutLocale;
+    /** UI theme preset to use, or partial theme configuration to override the default. */
+    theme?: CheckoutThemeName | Partial<CheckoutTheme>;
+    /** Base brand color used to auto-generate a custom theme palette. */
+    brandColor?: string;
+    /** Specific custom theme tokens to override properties of the active theme. */
+    customTheme?: Partial<CheckoutTheme>;
+    /** Callback function triggered when various core checkout actions occur (e.g., item update, payment submitted). */
+    onEvent?: EventHandler;
+    /** Optional controller to handle external cart actions programmatically. */
+    cartController?: CartController;
+    /** If provided, initializes the checkout directly into a feedback state (e.g., success, error) instead of the review step. */
+    initialState?: Extract<PaymentResult, {
+        status: "success" | "error" | "pending";
+    }>;
+    /** Enable Developer Tools panel to mock scenarios and intercept events. */
+    devTools?: boolean;
+    /** Custom override text messages to tailor the localization. */
+    messages?: Partial<CheckoutMessages>;
+    /** Optional custom formatting functions for prices and dates instead of defaults. */
+    formatters?: CheckoutFormatters;
+    /** Array of plugins to extend the core functionality (like shipping, cart editing, discounts). */
+    plugins?: CheckoutPlugin[];
+    /** Defines the visual structure of the checkout page. Defaults to 'single-page'. */
+    layout?: "single-page" | "accordion";
+    /** Pre-selected shipping method ID. Useful if the integrator wants to default a shipping option. */
+    defaultShippingMethodId?: string;
+    /** Pre-selected payment method ID. Useful if the integrator wants to default a payment option. */
+    defaultPaymentMethodId?: string;
+    /** License key to validate checkout feature flags against a remote Convex API. */
+    licenseKey?: string;
+}
+export interface CheckoutLayoutProps extends React.HTMLAttributes<HTMLDivElement> {
+    children: React.ReactNode;
+    sidebar?: React.ReactNode;
+}
+export interface FeedbackScreenProps {
+    title: string;
+    description?: string;
+    actions?: ButtonProps[];
+    actionsLayout?: "row" | "column";
+    variant?: PaymentResult["status"];
+    children?: ReactNode;
+}
+export type VariantConfig = {
+    icon: ReactNode;
+    iconBg: string;
+    iconColor: string;
+};
+export interface ButtonProps {
+    label: string;
+    onPress: () => void;
+    variant?: FractalButtonVariant;
+    icon?: ReactNode;
+    disabled?: boolean;
+    className?: string;
+    type?: "button" | "submit";
+}
+export interface OrderSidebarSummaryProps {
+    showItems?: boolean;
+    isLoading?: boolean;
+    hasShipping?: boolean;
+    layout?: "single-page" | "accordion";
+}
+export type MockScenario = 'success' | 'pending' | 'error' | 'redirect';
+export interface MobileOrderBarProps {
+    onAction?: () => void;
+    actionLabel?: string;
+    actionDisabled?: boolean;
+    isSubmitting?: boolean;
+    showItems?: boolean;
+}
+export interface ShippingMethodsProps {
+    methods: ShippingMethod[];
+    hideHeader?: boolean;
+}
+export interface AccordionLayoutProps {
+    hasShipping: boolean;
+}
+export interface MobileBarProps {
+    step: string;
+    hasShipping?: boolean;
+    layout?: "single-page" | "accordion";
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/components/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/components/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACtI,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAChH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE,MAAM,WAAW,aAAa;IAC1B,iFAAiF;IACjF,KAAK,EAAE,YAAY,EAAE,CAAC;IAEtB,yFAAyF;IACzF,MAAM,EAAE,cAAc,CAAC;IAEvB,0FAA0F;IAC1F,cAAc,EAAE,aAAa,EAAE,CAAC;IAEhC,oFAAoF;IACpF,QAAQ,EAAE,eAAe,CAAC;IAE1B,4EAA4E;IAC5E,QAAQ,EAAE,iBAAiB,CAAC;IAE5B,mGAAmG;IACnG,MAAM,CAAC,EAAE,cAAc,CAAC;IAExB,sFAAsF;IACtF,KAAK,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAEnD,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAErC,mHAAmH;IACnH,OAAO,CAAC,EAAE,YAAY,CAAC;IAEvB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC,8HAA8H;IAC9H,YAAY,CAAC,EAAE,OAAO,CAAC,aAAa,EAAE;QAAE,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAA;KAAE,CAAC,CAAC;IAEnF,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAErC,qFAAqF;IACrF,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAEhC,kGAAkG;IAClG,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAE3B,oFAAoF;IACpF,MAAM,CAAC,EAAE,aAAa,GAAG,WAAW,CAAC;IAErC,oGAAoG;IACpG,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAEjC,kGAAkG;IAClG,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAoB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IAC7E,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IACjC,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAClC,QAAQ,CAAC,EAAE,SAAS,CAAC;CACxB;AAED,MAAM,MAAM,aAAa,GAAG;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAC9B;AAED,MAAM,WAAW,wBAAwB;IACrC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,aAAa,GAAG,WAAW,CAAC;CACxC;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAExE,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACjC,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACjC,WAAW,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,aAAa,GAAG,WAAW,CAAC;CACxC"}