@rocapine/react-native-onboarding 1.11.1 → 1.13.0

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/onboarding-example.ts

@@ -329,6 +329,56 @@ export const onboardingExample = {
                   marginVertical: 8,
                 },
               },
+              {
+                id: "gradient-card",
+                type: "YStack",
+                props: {
+                  padding: 20,
+                  gap: 8,
+                  borderRadius: 16,
+                  overflow: "hidden",
+                  marginVertical: 4,
+                  backgroundGradient: {
+                    type: "linear",
+                    from: "topLeft",
+                    to: "bottomRight",
+                    stops: [
+                      { color: "#6C63FF" },
+                      { color: "#FF6584" },
+                    ],
+                  },
+                },
+                children: [
+                  {
+                    id: "gradient-card-title",
+                    type: "Text",
+                    props: { content: "Linear gradient", fontSize: 15, fontWeight: "700", color: "#fff" },
+                  },
+                  {
+                    id: "gradient-card-body",
+                    type: "Text",
+                    props: { content: "topLeft → bottomRight", fontSize: 12, color: "#fff", opacity: 0.85 },
+                  },
+                ],
+              },
+              {
+                id: "gradient-button",
+                type: "Button",
+                props: {
+                  label: "Gradient Button",
+                  variant: "filled",
+                  marginVertical: 4,
+                  backgroundGradient: {
+                    type: "linear",
+                    from: "left",
+                    to: "right",
+                    stops: [
+                      { color: "#FF6584", position: 0 },
+                      { color: "#6C63FF", position: 1 },
+                    ],
+                  },
+                },
+              },
             ],
           },
         ],

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>;

package/src/steps/Commitment/types.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ButtonSectionSchema, CustomPayloadSchema } from "../common.types";
+import { BaseStepTypeSchema } from "../common.types";
 
 export const CommitmentItemSchema = z.object({
   text: z.string(),
@@ -14,16 +14,9 @@ export const CommitmentStepPayloadSchema = z.object({
   variant: z.enum(["signature", "simple"]).default("signature"),
 });
 
-export const CommitmentStepTypeSchema = z.object({
-  id: z.string(),
+export const CommitmentStepTypeSchema = BaseStepTypeSchema.extend({
   type: z.literal("Commitment"),
-  name: z.string(),
-  displayProgressHeader: z.boolean(),
   payload: CommitmentStepPayloadSchema,
-  customPayload: CustomPayloadSchema,
-  continueButtonLabel: z.string().optional().default("Continue"),
-  buttonSection: ButtonSectionSchema.optional(),
-  figmaUrl: z.string().nullish(),
 });
 
 export type CommitmentStepType = z.infer<typeof CommitmentStepTypeSchema>;

package/src/steps/ComposableScreen/elements/BaseBoxProps.ts

@@ -1,5 +1,45 @@
 import { z } from "zod";
 
+export type GradientStop = {
+  color: string;
+  position?: number;
+};
+
+export type GradientEdge =
+  | "top"
+  | "bottom"
+  | "left"
+  | "right"
+  | "topLeft"
+  | "topRight"
+  | "bottomLeft"
+  | "bottomRight";
+
+export type LinearGradientConfig = {
+  type: "linear";
+  from: GradientEdge;
+  to: GradientEdge;
+  stops: GradientStop[];
+};
+
+export type GradientBackground = LinearGradientConfig;
+
+const GradientEdgeSchema = z.enum(["top", "bottom", "left", "right", "topLeft", "topRight", "bottomLeft", "bottomRight"]);
+
+const GradientStopSchema = z.object({
+  color: z.string(),
+  position: z.number().min(0).max(1).optional(),
+});
+
+export const GradientBackgroundSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("linear"),
+    from: GradientEdgeSchema,
+    to: GradientEdgeSchema,
+    stops: z.array(GradientStopSchema).min(2, "gradient requires at least 2 stops"),
+  }),
+]);
+
 export type BaseBoxProps = {
   width?: number | string;
   height?: number | string;
@@ -13,6 +53,7 @@ export type BaseBoxProps = {
   alignSelf?: "auto" | "flex-start" | "flex-end" | "center" | "stretch" | "baseline";
   opacity?: number;
   backgroundColor?: string;
+  backgroundGradient?: GradientBackground;
   overflow?: "hidden" | "visible" | "scroll";
   margin?: number;
   marginHorizontal?: number;
@@ -38,6 +79,7 @@ export const BaseBoxPropsSchema = z.object({
   alignSelf: z.enum(["auto", "flex-start", "flex-end", "center", "stretch", "baseline"]).optional(),
   opacity: z.number().min(0).max(1).optional(),
   backgroundColor: z.string().optional(),
+  backgroundGradient: GradientBackgroundSchema.optional(),
   overflow: z.enum(["hidden", "visible", "scroll"]).optional(),
   margin: z.number().optional(),
   marginHorizontal: z.number().optional(),

package/src/steps/ComposableScreen/types.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { CustomPayloadSchema } from "../common.types";
+import { BaseStepTypeSchema } from "../common.types";
 import { type StackElementProps, StackElementPropsSchema } from "./elements/StackElement";
 import { type TextElementProps, TextElementPropsSchema } from "./elements/TextElement";
 import { type ImageElementProps, ImageElementPropsSchema } from "./elements/ImageElement";
@@ -14,8 +14,8 @@ import { type CheckboxGroupElementProps, CheckboxGroupElementPropsSchema } from
 import { type DatePickerElementProps, DatePickerElementPropsSchema } from "./elements/DatePickerElement";
 import { type CarouselElementProps, CarouselElementPropsSchema } from "./elements/CarouselElement";
 
-export type { BaseBoxProps } from "./elements/BaseBoxProps";
-export { BaseBoxPropsSchema } from "./elements/BaseBoxProps";
+export type { BaseBoxProps, GradientBackground, GradientEdge, GradientStop, LinearGradientConfig } from "./elements/BaseBoxProps";
+export { BaseBoxPropsSchema, GradientBackgroundSchema } from "./elements/BaseBoxProps";
 export type { StackElementProps } from "./elements/StackElement";
 export type { TextElementProps } from "./elements/TextElement";
 export type { ImageElementProps } from "./elements/ImageElement";
@@ -203,15 +203,9 @@ export const ComposableScreenStepPayloadSchema = z.object({
   elements: z.array(UIElementSchema),
 });
 
-export const ComposableScreenStepTypeSchema = z.object({
-  id: z.string(),
+export const ComposableScreenStepTypeSchema = BaseStepTypeSchema.extend({
   type: z.literal("ComposableScreen"),
-  name: z.string(),
-  displayProgressHeader: z.boolean(),
   payload: ComposableScreenStepPayloadSchema,
-  customPayload: CustomPayloadSchema,
-  continueButtonLabel: z.string().optional().default("Continue"),
-  figmaUrl: z.string().nullable(),
 });
 
 export type ComposableScreenStepType = z.infer<typeof ComposableScreenStepTypeSchema>;