@rocapine/react-native-onboarding 1.11.1 → 1.12.0

package/src/__tests__/evaluateCondition.test.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect } from "vitest";
+import { evaluateLeaf, evaluateCondition } from "../evaluateCondition";
+import type { Condition } from "../evaluateCondition";
+
+// ---------------------------------------------------------------------------
+// evaluateLeaf — operator coverage
+// ---------------------------------------------------------------------------
+
+describe("evaluateLeaf — eq", () => {
+  it("matches equal strings", () => expect(evaluateLeaf({ variable: "x", operator: "eq", value: "male" }, { x: "male" })).toBe(true));
+  it("rejects unequal strings", () => expect(evaluateLeaf({ variable: "x", operator: "eq", value: "male" }, { x: "female" })).toBe(false));
+  it("coerces number to string for comparison", () => expect(evaluateLeaf({ variable: "x", operator: "eq", value: "42" }, { x: 42 })).toBe(true));
+  it("undefined variable yields false", () => expect(evaluateLeaf({ variable: "x", operator: "eq", value: "foo" }, {})).toBe(false));
+});
+
+describe("evaluateLeaf — neq", () => {
+  it("passes when values differ", () => expect(evaluateLeaf({ variable: "x", operator: "neq", value: "male" }, { x: "female" })).toBe(true));
+  it("fails when values equal", () => expect(evaluateLeaf({ variable: "x", operator: "neq", value: "male" }, { x: "male" })).toBe(false));
+});
+
+describe("evaluateLeaf — gt", () => {
+  it("passes when variable greater", () => expect(evaluateLeaf({ variable: "age", operator: "gt", value: 18 }, { age: 25 })).toBe(true));
+  it("fails when equal", () => expect(evaluateLeaf({ variable: "age", operator: "gt", value: 18 }, { age: 18 })).toBe(false));
+  it("fails when less", () => expect(evaluateLeaf({ variable: "age", operator: "gt", value: 18 }, { age: 10 })).toBe(false));
+  it("coerces string variable", () => expect(evaluateLeaf({ variable: "age", operator: "gt", value: 18 }, { age: "25" })).toBe(true));
+  it("coerces string value", () => expect(evaluateLeaf({ variable: "age", operator: "gt", value: "18" }, { age: 25 })).toBe(true));
+});
+
+describe("evaluateLeaf — lt", () => {
+  it("passes when variable less", () => expect(evaluateLeaf({ variable: "age", operator: "lt", value: 18 }, { age: 10 })).toBe(true));
+  it("fails when equal", () => expect(evaluateLeaf({ variable: "age", operator: "lt", value: 18 }, { age: 18 })).toBe(false));
+  it("fails when greater", () => expect(evaluateLeaf({ variable: "age", operator: "lt", value: 18 }, { age: 25 })).toBe(false));
+});
+
+describe("evaluateLeaf — gte", () => {
+  it("passes when greater", () => expect(evaluateLeaf({ variable: "x", operator: "gte", value: 5 }, { x: 6 })).toBe(true));
+  it("passes when equal", () => expect(evaluateLeaf({ variable: "x", operator: "gte", value: 5 }, { x: 5 })).toBe(true));
+  it("fails when less", () => expect(evaluateLeaf({ variable: "x", operator: "gte", value: 5 }, { x: 4 })).toBe(false));
+});
+
+describe("evaluateLeaf — lte", () => {
+  it("passes when less", () => expect(evaluateLeaf({ variable: "x", operator: "lte", value: 5 }, { x: 4 })).toBe(true));
+  it("passes when equal", () => expect(evaluateLeaf({ variable: "x", operator: "lte", value: 5 }, { x: 5 })).toBe(true));
+  it("fails when greater", () => expect(evaluateLeaf({ variable: "x", operator: "lte", value: 5 }, { x: 6 })).toBe(false));
+});
+
+describe("evaluateLeaf — contains (string)", () => {
+  it("passes when substring found", () => expect(evaluateLeaf({ variable: "bio", operator: "contains", value: "run" }, { bio: "I love running" })).toBe(true));
+  it("fails when substring absent", () => expect(evaluateLeaf({ variable: "bio", operator: "contains", value: "swim" }, { bio: "I love running" })).toBe(false));
+  it("coerces number variable to string", () => expect(evaluateLeaf({ variable: "code", operator: "contains", value: "4" }, { code: 42 })).toBe(true));
+});
+
+describe("evaluateLeaf — contains (array)", () => {
+  it("passes when element in array", () => expect(evaluateLeaf({ variable: "tags", operator: "contains", value: "sport" }, { tags: ["health", "sport"] })).toBe(true));
+  it("fails when element absent", () => expect(evaluateLeaf({ variable: "tags", operator: "contains", value: "music" }, { tags: ["health", "sport"] })).toBe(false));
+});
+
+describe("evaluateLeaf — in", () => {
+  it("passes when variable is in list", () => expect(evaluateLeaf({ variable: "gender", operator: "in", value: ["male", "female"] }, { gender: "male" })).toBe(true));
+  it("fails when variable not in list", () => expect(evaluateLeaf({ variable: "gender", operator: "in", value: ["male", "female"] }, { gender: "other" })).toBe(false));
+  it("returns false when value is not array", () => expect(evaluateLeaf({ variable: "x", operator: "in", value: "male" as any }, { x: "male" })).toBe(false));
+  it("empty list always false", () => expect(evaluateLeaf({ variable: "x", operator: "in", value: [] }, { x: "male" })).toBe(false));
+  it("coerces numeric raw to string before comparison", () => expect(evaluateLeaf({ variable: "age", operator: "in", value: ["18", "25"] }, { age: 18 })).toBe(true));
+  it("numeric raw not in string list returns false", () => expect(evaluateLeaf({ variable: "age", operator: "in", value: ["30", "40"] }, { age: 18 })).toBe(false));
+});
+
+describe("evaluateLeaf — not_in", () => {
+  it("passes when variable not in list", () => expect(evaluateLeaf({ variable: "gender", operator: "not_in", value: ["male", "female"] }, { gender: "other" })).toBe(true));
+  it("fails when variable is in list", () => expect(evaluateLeaf({ variable: "gender", operator: "not_in", value: ["male", "female"] }, { gender: "male" })).toBe(false));
+  it("returns true when value is not array (safe default)", () => expect(evaluateLeaf({ variable: "x", operator: "not_in", value: "male" as any }, { x: "male" })).toBe(true));
+  it("coerces numeric raw to string before comparison", () => expect(evaluateLeaf({ variable: "age", operator: "not_in", value: ["18", "25"] }, { age: 30 })).toBe(true));
+  it("numeric raw in string list returns false", () => expect(evaluateLeaf({ variable: "age", operator: "not_in", value: ["18", "25"] }, { age: 18 })).toBe(false));
+});
+
+describe("evaluateLeaf — unknown operator", () => {
+  it("returns false for unknown operator", () => expect(evaluateLeaf({ variable: "x", operator: "xor" as any, value: "y" }, { x: "y" })).toBe(false));
+});
+
+// ---------------------------------------------------------------------------
+// evaluateCondition — logic groups
+// ---------------------------------------------------------------------------
+
+describe("evaluateCondition — AND group", () => {
+  const and: Condition = {
+    logic: "and",
+    conditions: [
+      { variable: "age", operator: "gt", value: 18 },
+      { variable: "gender", operator: "eq", value: "male" },
+    ],
+  };
+
+  it("passes when all conditions true", () => expect(evaluateCondition(and, { age: 25, gender: "male" })).toBe(true));
+  it("fails when one condition false", () => expect(evaluateCondition(and, { age: 25, gender: "female" })).toBe(false));
+  it("fails when all conditions false", () => expect(evaluateCondition(and, { age: 10, gender: "female" })).toBe(false));
+});
+
+describe("evaluateCondition — OR group", () => {
+  const or: Condition = {
+    logic: "or",
+    conditions: [
+      { variable: "age", operator: "lt", value: 18 },
+      { variable: "gender", operator: "eq", value: "female" },
+    ],
+  };
+
+  it("passes when first condition true", () => expect(evaluateCondition(or, { age: 10, gender: "male" })).toBe(true));
+  it("passes when second condition true", () => expect(evaluateCondition(or, { age: 25, gender: "female" })).toBe(true));
+  it("passes when both true", () => expect(evaluateCondition(or, { age: 10, gender: "female" })).toBe(true));
+  it("fails when all false", () => expect(evaluateCondition(or, { age: 25, gender: "male" })).toBe(false));
+});
+
+describe("evaluateCondition — nested groups", () => {
+  // (age > 18 AND gender = male) OR (vip = true)
+  const nested: Condition = {
+    logic: "or",
+    conditions: [
+      {
+        logic: "and",
+        conditions: [
+          { variable: "age", operator: "gt", value: 18 },
+          { variable: "gender", operator: "eq", value: "male" },
+        ],
+      },
+      { variable: "vip", operator: "eq", value: "true" },
+    ],
+  };
+
+  it("passes via inner AND branch", () => expect(evaluateCondition(nested, { age: 25, gender: "male", vip: "false" })).toBe(true));
+  it("passes via vip branch", () => expect(evaluateCondition(nested, { age: 10, gender: "female", vip: "true" })).toBe(true));
+  it("fails when neither branch matches", () => expect(evaluateCondition(nested, { age: 10, gender: "male", vip: "false" })).toBe(false));
+});
+
+describe("evaluateCondition — deeply nested (3 levels)", () => {
+  // ((a=1 AND b=2) OR c=3) AND d=4
+  const deep: Condition = {
+    logic: "and",
+    conditions: [
+      {
+        logic: "or",
+        conditions: [
+          {
+            logic: "and",
+            conditions: [
+              { variable: "a", operator: "eq", value: "1" },
+              { variable: "b", operator: "eq", value: "2" },
+            ],
+          },
+          { variable: "c", operator: "eq", value: "3" },
+        ],
+      },
+      { variable: "d", operator: "eq", value: "4" },
+    ],
+  };
+
+  it("passes via a+b path with d", () => expect(evaluateCondition(deep, { a: "1", b: "2", c: "0", d: "4" })).toBe(true));
+  it("passes via c path with d", () => expect(evaluateCondition(deep, { a: "0", b: "0", c: "3", d: "4" })).toBe(true));
+  it("fails when d missing", () => expect(evaluateCondition(deep, { a: "1", b: "2", c: "3", d: "0" })).toBe(false));
+  it("fails when inner OR fails and d present", () => expect(evaluateCondition(deep, { a: "0", b: "0", c: "0", d: "4" })).toBe(false));
+});
+
+describe("evaluateCondition — leaf passthrough", () => {
+  it("delegates to evaluateLeaf directly", () => {
+    const leaf: Condition = { variable: "x", operator: "eq", value: "yes" };
+    expect(evaluateCondition(leaf, { x: "yes" })).toBe(true);
+    expect(evaluateCondition(leaf, { x: "no" })).toBe(false);
+  });
+});

package/src/__tests__/resolveNextStepNumber.test.ts

@@ -0,0 +1,309 @@
+import { describe, it, expect } from "vitest";
+import { resolveNextStepNumber } from "../resolveNextStepNumber";
+import type { BaseStepType } from "../types";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeStep(id: string, overrides: Partial<BaseStepType> = {}): BaseStepType {
+  return {
+    id,
+    type: "Question",
+    name: id,
+    displayProgressHeader: true,
+    nextStep: null,
+    ...overrides,
+  } as BaseStepType;
+}
+
+const steps = [
+  makeStep("s1"),
+  makeStep("s2"),
+  makeStep("s3"),
+  makeStep("s4"),
+];
+
+// ---------------------------------------------------------------------------
+// Linear progression (nextStep = null)
+// ---------------------------------------------------------------------------
+
+describe("linear progression", () => {
+  it("returns 2 from step 1", () => expect(resolveNextStepNumber(steps[0], {}, steps)).toBe(2));
+  it("returns 3 from step 2", () => expect(resolveNextStepNumber(steps[1], {}, steps)).toBe(3));
+  it("returns null from last step", () => expect(resolveNextStepNumber(steps[3], {}, steps)).toBe(null));
+  it("returns null when step not found in array", () => {
+    const orphan = makeStep("orphan");
+    expect(resolveNextStepNumber(orphan, {}, steps)).toBe(null);
+  });
+  it("returns null for single-step array", () => {
+    const single = [makeStep("only")];
+    expect(resolveNextStepNumber(single[0], {}, single)).toBe(null);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Branching — condition match
+// ---------------------------------------------------------------------------
+
+describe("branch — first matching branch wins", () => {
+  it("routes to targetStepId of first matching branch", () => {
+    const step = makeStep("s1", {
+      nextStep: {
+        defaultTargetStepId: "s2",
+        branches: [
+          { condition: { variable: "gender", operator: "eq", value: "female" }, targetStepId: "s4" },
+          { condition: { variable: "gender", operator: "eq", value: "male" }, targetStepId: "s3" },
+        ],
+      },
+    });
+    expect(resolveNextStepNumber(step, { gender: "male" }, steps)).toBe(3);
+  });
+
+  it("first branch wins even if second also matches", () => {
+    const step = makeStep("s1", {
+      nextStep: {
+        defaultTargetStepId: "s2",
+        branches: [
+          { condition: { variable: "age", operator: "gt", value: 10 }, targetStepId: "s3" },
+          { condition: { variable: "age", operator: "gt", value: 5 }, targetStepId: "s4" },
+        ],
+      },
+    });
+    expect(resolveNextStepNumber(step, { age: 20 }, steps)).toBe(3);
+  });
+
+  it("skips non-matching branch, takes second", () => {
+    const step = makeStep("s1", {
+      nextStep: {
+        defaultTargetStepId: "s2",
+        branches: [
+          { condition: { variable: "gender", operator: "eq", value: "female" }, targetStepId: "s4" },
+          { condition: { variable: "gender", operator: "eq", value: "male" }, targetStepId: "s3" },
+        ],
+      },
+    });
+    expect(resolveNextStepNumber(step, { gender: "female" }, steps)).toBe(4);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Branching — unconditional branch (null condition)
+// ---------------------------------------------------------------------------
+
+describe("branch — null condition (unconditional)", () => {
+  it("always matches null condition", () => {
+    const step = makeStep("s1", {
+      nextStep: {
+        defaultTargetStepId: "s2",
+        branches: [
+          { condition: null, targetStepId: "s4" },
+        ],
+      },
+    });
+    expect(resolveNextStepNumber(step, {}, steps)).toBe(4);
+  });
+
+  it("null condition after a non-matching branch acts as catch-all", () => {
+    const step = makeStep("s1", {
+      nextStep: {
+        defaultTargetStepId: "s2",
+        branches: [
+          { condition: { variable: "age", operator: "gt", value: 100 }, targetStepId: "s3" },
+          { condition: null, targetStepId: "s4" },
+        ],
+      },
+    });
+    expect(resolveNextStepNumber(step, { age: 25 }, steps)).toBe(4);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Branching — defaultTargetStepId fallback
+// ---------------------------------------------------------------------------
+
+describe("branch — defaultTargetStepId fallback", () => {
+  it("uses defaultTargetStepId when no branch matches", () => {
+    const step = makeStep("s1", {
+      nextStep: {
+        defaultTargetStepId: "s3",
+        branches: [
+          { condition: { variable: "x", operator: "eq", value: "never" }, targetStepId: "s4" },
+        ],
+      },
+    });
+    expect(resolveNextStepNumber(step, { x: "something_else" }, steps)).toBe(3);
+  });
+
+  it("defaultTargetStepId with empty branches array still resolves", () => {
+    const step = makeStep("s1", {
+      nextStep: {
+        defaultTargetStepId: "s4",
+        branches: [],
+      },
+    });
+    expect(resolveNextStepNumber(step, {}, steps)).toBe(4);
+  });
+
+  it("falls back to linear when defaultTargetStepId not in steps", () => {
+    const step = makeStep("s1", {
+      nextStep: {
+        defaultTargetStepId: "does-not-exist",
+        branches: [],
+      },
+    });
+    expect(resolveNextStepNumber(step, {}, steps)).toBe(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Branching — branch targetStepId not found
+// ---------------------------------------------------------------------------
+
+describe("branch — targetStepId not found", () => {
+  it("skips branch with unknown targetStepId, tries next branch", () => {
+    const step = makeStep("s1", {
+      nextStep: {
+        defaultTargetStepId: "s2",
+        branches: [
+          { condition: { variable: "x", operator: "eq", value: "y" }, targetStepId: "ghost" },
+          { condition: { variable: "x", operator: "eq", value: "y" }, targetStepId: "s3" },
+        ],
+      },
+    });
+    expect(resolveNextStepNumber(step, { x: "y" }, steps)).toBe(3);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Branching — compound conditions in branches
+// ---------------------------------------------------------------------------
+
+describe("branch — compound conditions", () => {
+  it("AND group in branch condition", () => {
+    const step = makeStep("s1", {
+      nextStep: {
+        defaultTargetStepId: "s2",
+        branches: [
+          {
+            condition: {
+              logic: "and",
+              conditions: [
+                { variable: "age", operator: "gte", value: 18 },
+                { variable: "gender", operator: "eq", value: "female" },
+              ],
+            },
+            targetStepId: "s4",
+          },
+        ],
+      },
+    });
+
+    expect(resolveNextStepNumber(step, { age: 25, gender: "female" }, steps)).toBe(4);
+    expect(resolveNextStepNumber(step, { age: 15, gender: "female" }, steps)).toBe(2);
+    expect(resolveNextStepNumber(step, { age: 25, gender: "male" }, steps)).toBe(2);
+  });
+
+  it("OR group in branch condition", () => {
+    const step = makeStep("s1", {
+      nextStep: {
+        defaultTargetStepId: "s2",
+        branches: [
+          {
+            condition: {
+              logic: "or",
+              conditions: [
+                { variable: "vip", operator: "eq", value: "true" },
+                { variable: "age", operator: "lt", value: 13 },
+              ],
+            },
+            targetStepId: "s3",
+          },
+        ],
+      },
+    });
+
+    expect(resolveNextStepNumber(step, { vip: "true", age: 25 }, steps)).toBe(3);
+    expect(resolveNextStepNumber(step, { vip: "false", age: 10 }, steps)).toBe(3);
+    expect(resolveNextStepNumber(step, { vip: "false", age: 20 }, steps)).toBe(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Self-loop guard
+// ---------------------------------------------------------------------------
+
+describe("self-loop guard", () => {
+  it("skips branch where targetStepId equals currentStep.id", () => {
+    const step = makeStep("s1", {
+      nextStep: {
+        defaultTargetStepId: "s2",
+        branches: [
+          { condition: null, targetStepId: "s1" }, // would self-loop
+          { condition: null, targetStepId: "s3" },
+        ],
+      },
+    });
+    expect(resolveNextStepNumber(step, {}, steps)).toBe(3);
+  });
+
+  it("falls back to linear when only self-targeting branch matches", () => {
+    const step = makeStep("s1", {
+      nextStep: {
+        defaultTargetStepId: "s2",
+        branches: [
+          { condition: null, targetStepId: "s1" }, // would self-loop, only branch
+        ],
+      },
+    });
+    // defaultTargetStepId is "s2" which is valid → returns 2
+    expect(resolveNextStepNumber(step, {}, steps)).toBe(2);
+  });
+
+  it("skips defaultTargetStepId when it equals currentStep.id, falls back to linear", () => {
+    const step = makeStep("s2", {
+      nextStep: {
+        defaultTargetStepId: "s2", // self-reference
+        branches: [],
+      },
+    });
+    expect(resolveNextStepNumber(step, {}, steps)).toBe(3);
+  });
+
+  it("returns null when only route is self-loop and no linear next", () => {
+    const last = makeStep("s4", {
+      nextStep: {
+        defaultTargetStepId: "s4", // self-reference, and s4 is last
+        branches: [],
+      },
+    });
+    expect(resolveNextStepNumber(last, {}, steps)).toBe(null);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Edge cases
+// ---------------------------------------------------------------------------
+
+describe("edge cases", () => {
+  it("empty steps array returns null", () => {
+    expect(resolveNextStepNumber(makeStep("s1"), {}, [])).toBe(null);
+  });
+
+  it("empty variables object, no branch matches → linear", () => {
+    const step = makeStep("s1", {
+      nextStep: {
+        defaultTargetStepId: "s3",
+        branches: [
+          { condition: { variable: "gender", operator: "eq", value: "male" }, targetStepId: "s4" },
+        ],
+      },
+    });
+    expect(resolveNextStepNumber(step, {}, [step, makeStep("s2"), makeStep("s3"), makeStep("s4")])).toBe(3);
+  });
+
+  it("steps array with one element and current step last returns null", () => {
+    const s = makeStep("only");
+    expect(resolveNextStepNumber(s, {}, [s])).toBe(null);
+  });
+});

package/src/evaluateCondition.ts

@@ -0,0 +1,50 @@
+import type { LeafCondition, ConditionGroup } from "./steps/common.types";
+
+export type Condition = LeafCondition | ConditionGroup;
+
+export function isConditionGroup(c: Condition): c is ConditionGroup {
+  return "logic" in c && "conditions" in c;
+}
+
+function coerceToNumber(v: unknown): number {
+  return typeof v === "string" ? parseFloat(v) : Number(v);
+}
+
+export function evaluateLeaf(condition: LeafCondition, variables: Record<string, unknown>): boolean {
+  const raw = variables[condition.variable];
+  const { operator, value } = condition;
+
+  switch (operator) {
+    case "eq":
+      return String(raw) === String(value);
+    case "neq":
+      return String(raw) !== String(value);
+    case "gt":
+      return coerceToNumber(raw) > coerceToNumber(value);
+    case "lt":
+      return coerceToNumber(raw) < coerceToNumber(value);
+    case "gte":
+      return coerceToNumber(raw) >= coerceToNumber(value);
+    case "lte":
+      return coerceToNumber(raw) <= coerceToNumber(value);
+    case "contains":
+      return Array.isArray(raw)
+        ? raw.includes(value)
+        : String(raw).includes(String(value));
+    case "in":
+      return Array.isArray(value) ? value.includes(String(raw)) : false;
+    case "not_in":
+      return Array.isArray(value) ? !value.includes(String(raw)) : true;
+    default:
+      return false;
+  }
+}
+
+export function evaluateCondition(condition: Condition, variables: Record<string, unknown>): boolean {
+  if (isConditionGroup(condition)) {
+    return condition.logic === "and"
+      ? condition.conditions.every((c) => evaluateCondition(c, variables))
+      : condition.conditions.some((c) => evaluateCondition(c, variables));
+  }
+  return evaluateLeaf(condition, variables);
+}

package/src/index.ts

@@ -4,3 +4,22 @@ export * from "./types";
 export * from "./onboarding-example";
 // Hooks and providers
 export * from "./infra";
+// Branching
+export { resolveNextStepNumber } from "./resolveNextStepNumber";
+export type {
+  LeafCondition,
+  ConditionGroup,
+  ConditionValue,
+  ConditionOperator,
+  Branch,
+  NextStep,
+} from "./steps/common.types";
+export {
+  BaseStepTypeSchema,
+  LeafConditionSchema,
+  ConditionGroupSchema,
+  BranchSchema,
+  NextStepSchema,
+  ConditionOperatorSchema,
+  ConditionValueSchema,
+} from "./steps/common.types";

package/src/infra/provider/OnboardingProvider.tsx

@@ -1,4 +1,4 @@
-import { createContext, useState } from "react";
+import { createContext, useCallback, useState } from "react";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { OnboardingStudioClient } from "../../OnboardingStudioClient";
 import { getOnboardingQuery } from "../queries/getOnboarding.query";
@@ -32,6 +32,10 @@ export const OnboardingProvider = ({
   });
   const [totalSteps, setTotalSteps] = useState(0);
   const [onboarding, setOnboarding] = useState<Onboarding<OnboardingStepType> | null>(null);
+  const [variables, setVariables] = useState<Record<string, any>>({});
+  const setVariable = useCallback((name: string, value: any) => {
+    setVariables((prev) => ({ ...prev, [name]: value }));
+  }, []);
 
   queryClient.prefetchQuery(getOnboardingQuery(client, locale, customAudienceParams, setOnboarding))
 
@@ -49,6 +53,8 @@ export const OnboardingProvider = ({
           customAudienceParams,
           onboarding,
           setOnboarding,
+          variables,
+          setVariable,
         }}
       >
         {children}
@@ -67,6 +73,8 @@ export const OnboardingProgressContext = createContext<{
   customAudienceParams: Record<string, any>;
   onboarding: Onboarding<OnboardingStepType> | null;
   setOnboarding: (onboarding: Onboarding<OnboardingStepType>) => void;
+  variables: Record<string, any>;
+  setVariable: (name: string, value: any) => void;
 }>({
   activeStep: { number: 0, displayProgressHeader: false },
   setActiveStep: () => { },
@@ -77,4 +85,6 @@ export const OnboardingProgressContext = createContext<{
   customAudienceParams: {},
   onboarding: null,
   setOnboarding: () => { },
+  variables: {},
+  setVariable: () => { },
 });

package/src/resolveNextStepNumber.ts

@@ -0,0 +1,41 @@
+import type { BaseStepType } from "./types";
+import { evaluateCondition } from "./evaluateCondition";
+
+/**
+ * Resolves the 1-indexed step number to navigate to after the current step.
+ * Returns null when the onboarding should end (no next step exists).
+ *
+ * @param currentStep - The step that just completed
+ * @param variables   - Global variable store (build a merged copy before calling if you just set a variable)
+ * @param steps       - Full ordered steps array
+ */
+export function resolveNextStepNumber(
+  currentStep: BaseStepType,
+  variables: Record<string, any>,
+  steps: BaseStepType[]
+): number | null {
+  const linearNext = (): number | null => {
+    const idx = steps.findIndex((s) => s.id === currentStep.id);
+    if (idx === -1 || idx + 1 >= steps.length) return null;
+    return idx + 2;
+  };
+
+  const { nextStep } = currentStep;
+
+  if (nextStep == null) return linearNext();
+
+  for (const branch of nextStep.branches) {
+    if (branch.targetStepId === currentStep.id) continue;
+    if (branch.condition === null || evaluateCondition(branch.condition, variables)) {
+      const idx = steps.findIndex((s) => s.id === branch.targetStepId);
+      if (idx !== -1) return idx + 1;
+    }
+  }
+
+  if (nextStep.defaultTargetStepId !== currentStep.id) {
+    const defaultIdx = steps.findIndex((s) => s.id === nextStep.defaultTargetStepId);
+    if (defaultIdx !== -1) return defaultIdx + 1;
+  }
+
+  return linearNext();
+}

package/src/steps/Carousel/types.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ButtonSectionSchema, CustomPayloadSchema } from "../common.types";
+import { BaseStepTypeSchema } from "../common.types";
 
 export const CarouselScreenSchema = z.object({
   mediaUrl: z.string(),
@@ -11,16 +11,9 @@ export const CarouselStepPayloadSchema = z.object({
   screens: z.array(CarouselScreenSchema),
 });
 
-export const CarouselStepTypeSchema = z.object({
-  id: z.string(),
+export const CarouselStepTypeSchema = BaseStepTypeSchema.extend({
   type: z.literal("Carousel"),
-  name: z.string(),
-  displayProgressHeader: z.boolean(),
   payload: CarouselStepPayloadSchema,
-  customPayload: CustomPayloadSchema,
-  continueButtonLabel: z.string().optional().default("Continue"),
-  buttonSection: ButtonSectionSchema.optional(),
-  figmaUrl: z.string().nullish(),
 });
 
 export type CarouselStepType = z.infer<typeof CarouselStepTypeSchema>;