@schematichq/schematic-components 2.1.2 → 2.2.1

package/dist/schematic-components.d.ts

@@ -1869,6 +1869,89 @@ export declare type ButtonSize = "sm" | "md" | "lg";
 
 export declare type ButtonVariant = "filled" | "outline" | "ghost" | "text";
 
+/**
+ * Configuration for controlling checkout stage flow and pre-selection.
+ *
+ * ## Three Behavior Modes
+ *
+ * ### 1. Pre-Selection Mode (object without `skipped`)
+ * When you provide planId/addOnIds without explicit skip config, stages are
+ * shown with values pre-selected for user review.
+ *
+ * @example
+ * // Pre-select plan, show plan stage for review
+ * initializeWithPlan({ planId: 'plan_xyz' })
+ *
+ * @example
+ * // Pre-select plan and add-ons, show both stages for review
+ * initializeWithPlan({
+ *   planId: 'plan_xyz',
+ *   addOnIds: ['addon_1', 'addon_2']
+ * })
+ *
+ * ### 2. Explicit Skip Mode (object with `skipped`)
+ * With explicit skip configuration, you control exactly which stages to skip.
+ * You can skip stages without pre-selecting, or pre-select and skip together.
+ *
+ * @example
+ * // Skip plan stage without pre-selecting (user chooses plan)
+ * initializeWithPlan({
+ *   skipped: { planStage: true }
+ * })
+ *
+ * @example
+ * // Pre-select plan AND skip plan stage (go directly to add-ons)
+ * initializeWithPlan({
+ *   planId: 'plan_xyz',
+ *   skipped: { planStage: true }
+ * })
+ *
+ * @example
+ * // Pre-select plan but show it, skip add-ons stage
+ * initializeWithPlan({
+ *   planId: 'plan_xyz',
+ *   skipped: { planStage: false, addOnStage: true }
+ * })
+ *
+ * @example
+ * // Skip both stages, go straight to checkout
+ * initializeWithPlan({
+ *   planId: 'plan_xyz',
+ *   addOnIds: ['addon_1'],
+ *   skipped: { planStage: true, addOnStage: true }
+ * })
+ *
+ * ### 3. Legacy String Format
+ * Backwards compatible mode: pre-selects plan and skips plan stage.
+ *
+ * @example
+ * initializeWithPlan('plan_xyz')
+ * // Equivalent to: { planId: 'plan_xyz', skipped: { planStage: true } }
+ */
+export declare interface BypassConfig {
+    /**
+     * Plan ID to pre-select.
+     * Optional - you can skip stages without pre-selecting a plan.
+     */
+    planId?: string;
+    /**
+     * Add-on IDs to pre-select.
+     * Optional - you can skip stages without pre-selecting add-ons.
+     */
+    addOnIds?: string[];
+    /**
+     * Explicit skip configuration for stages.
+     * - If not provided: stages are shown with pre-selected values (review mode)
+     * - If provided: you control exactly which stages to skip
+     */
+    skipped?: CheckoutStageSkipConfig;
+    /**
+     * Hide skipped stages from breadcrumb navigation.
+     * Default: false (skipped stages still appear in breadcrumbs)
+     */
+    hideSkipped?: boolean;
+}
+
 export declare const Card: ForwardRefExoticComponent<CardProps & RefAttributes<HTMLDivElement | null>>;
 
 export declare const cardBoxShadow = "0px 1px 20px 0px #1018280F, 0px 1px 3px 0px #1018281A";
@@ -2118,6 +2201,49 @@ export declare interface CheckoutStage {
     description?: string;
 }
 
+/**
+ * Explicit configuration for skipping checkout stages.
+ *
+ * This configuration is independent of pre-selection (planId/addOnIds).
+ * You have full control to:
+ * - Skip stages without pre-selecting values
+ * - Pre-select values without skipping stages
+ * - Pre-select AND skip stages
+ * - Any combination that suits your checkout flow
+ *
+ * @example
+ * // Skip both stages (go directly to checkout/payment)
+ * { planStage: true, addOnStage: true }
+ *
+ * @example
+ * // Skip only plan stage (show add-ons)
+ * { planStage: true, addOnStage: false }
+ *
+ * @example
+ * // Show plan stage, skip add-ons stage
+ * { planStage: false, addOnStage: true }
+ *
+ * @example
+ * // Show both stages (same as not providing skipped config)
+ * { planStage: false, addOnStage: false }
+ */
+export declare interface CheckoutStageSkipConfig {
+    /**
+     * Skip the plan selection stage.
+     * - true: Skip directly to next stage
+     * - false: Show plan stage (user can review/change selection)
+     * - undefined: Defaults to false (show stage)
+     */
+    planStage?: boolean;
+    /**
+     * Skip the add-on selection stage.
+     * - true: Skip directly to next stage
+     * - false: Show add-on stage (user can review/change selection)
+     * - undefined: Defaults to false (show stage)
+     */
+    addOnStage?: boolean;
+}
+
 export declare type CheckoutState = {
     period?: string;
     planId?: string | null;
@@ -2126,6 +2252,9 @@ export declare type CheckoutState = {
     addOnUsage?: boolean;
     credits?: boolean;
     bypassPlanSelection?: boolean;
+    bypassAddOnSelection?: boolean;
+    addOnIds?: string[];
+    hideSkippedStages?: boolean;
 };
 
 /**
@@ -4100,7 +4229,7 @@ export declare interface EmbedContextProps extends EmbedState {
     setError: (error: Error) => void;
     setLayout: (layout: EmbedLayout) => void;
     setCheckoutState: (state: CheckoutState) => void;
-    initializeWithPlan: (planId: string) => void;
+    initializeWithPlan: (config: string | BypassConfig) => void;
     setData: (data: HydrateDataWithCompanyContext) => void;
     updateSettings: (settings: DeepPartial<EmbedSettings>, options?: {
         update?: boolean;