@waypointjs/core 0.1.5 → 0.1.6

package/dist/index.d.ts

@@ -36,6 +36,11 @@ interface ValidationRule {
     message: string;
     /** For "custom" type: identifier of the validator function registered at runtime */
     customValidatorId?: string;
+    /**
+     * Cross-field reference — "stepId.fieldId" path.
+     * When set, the comparison target is resolved from journey data instead of using `value`.
+     */
+    refField?: string;
 }
 type BuiltinFieldType = "text" | "number" | "email" | "password" | "tel" | "url" | "textarea" | "select" | "multiselect" | "checkbox" | "radio" | "date" | "file";
 /** Field type — either a builtin or a custom type id registered at runtime */
@@ -44,12 +49,25 @@ interface SelectOption {
     label: string;
     value: string | number;
 }
+/**
+ * A dynamic default rule: if the condition matches, use the given value
+ * as the field's default. First matching rule wins.
+ */
+interface DynamicDefaultRule {
+    when: ConditionGroup;
+    value: unknown;
+}
 interface FieldDefinition {
     id: string;
     type: FieldType;
     label: string;
     placeholder?: string;
     defaultValue?: unknown;
+    /**
+     * Conditional defaults — evaluated in order, first match wins.
+     * Falls back to `defaultValue` if no rule matches.
+     */
+    dynamicDefault?: DynamicDefaultRule[];
     /** Options for select/multiselect/radio fields (hardcoded) */
     options?: SelectOption[];
     /** Reference to an external enum — options resolved at runtime from app-provided enums */
@@ -70,6 +88,8 @@ interface StepDefinition$1 {
     visibleWhen?: ConditionGroup;
     /** Whether this step can be used as a resume point */
     enableResumeFromHere?: boolean;
+    /** Whether the user can skip this step without filling required fields */
+    skippable?: boolean;
 }
 interface ExternalVariable {
     id: string;
@@ -140,20 +160,21 @@ type JourneyData = Record<string, Record<string, unknown>>;
 type ExternalVars = Record<string, unknown>;
 /**
  * Resolves a field path to its value from the data context.
- * - "stepId.fieldId"  → journey data
- * - "$ext.varId"      → external variable
+ * - "stepId.fieldId"       → journey data
+ * - "$ext.varId"           → external variable
+ * - "$step.stepId.skipped" → whether the step was skipped (boolean)
  */
-declare function resolveFieldValue(path: string, data: JourneyData, externalVars: ExternalVars): unknown;
+declare function resolveFieldValue(path: string, data: JourneyData, externalVars: ExternalVars, skippedSteps?: string[]): unknown;
 /**
  * Evaluates a condition group against the current data context.
  * Returns true if the group's conditions are satisfied.
  */
-declare function evaluateConditionGroup(group: ConditionGroup, data: JourneyData, externalVars: ExternalVars, externalEnums?: ExternalEnum[]): boolean;
+declare function evaluateConditionGroup(group: ConditionGroup, data: JourneyData, externalVars: ExternalVars, externalEnums?: ExternalEnum[], skippedSteps?: string[]): boolean;
 /**
  * Convenience: returns true if no condition is defined (always visible),
  * or if the condition group evaluates to true.
  */
-declare function isVisible(visibleWhen: ConditionGroup | undefined, data: JourneyData, externalVars: ExternalVars, externalEnums?: ExternalEnum[]): boolean;
+declare function isVisible(visibleWhen: ConditionGroup | undefined, data: JourneyData, externalVars: ExternalVars, externalEnums?: ExternalEnum[], skippedSteps?: string[]): boolean;
 
 /** A field after condition evaluation */
 interface ResolvedField {
@@ -168,6 +189,11 @@ interface ResolvedField {
      * Use `field.resolvedOptions ?? field.definition.options` when rendering.
      */
     resolvedOptions?: SelectOption[];
+    /**
+     * Resolved dynamic default value (first matching `dynamicDefault` rule).
+     * Use `field.resolvedDefaultValue ?? field.definition.defaultValue` for initial form values.
+     */
+    resolvedDefaultValue?: unknown;
 }
 /** A step after condition evaluation */
 interface ResolvedStep {
@@ -195,7 +221,7 @@ interface ResolvedTree {
  *
  * This function is pure: same inputs always produce same outputs.
  */
-declare function resolveTree(schema: WaypointSchema, data: JourneyData, externalVars: ExternalVars, externalEnums?: ExternalEnum[]): ResolvedTree;
+declare function resolveTree(schema: WaypointSchema, data: JourneyData, externalVars: ExternalVars, externalEnums?: ExternalEnum[], skippedSteps?: string[]): ResolvedTree;
 /**
  * Returns the index of the step with the given id in the resolved (visible) tree.
  * Returns -1 if not found.
@@ -230,6 +256,8 @@ interface WaypointRuntimeState {
     currentStepId: string | null;
     /** Step IDs visited in order */
     history: string[];
+    /** Step IDs that have been skipped by the user */
+    skippedSteps: string[];
     isSubmitting: boolean;
     /** True once onComplete has been called (all steps validated) */
     completed: boolean;
@@ -256,6 +284,10 @@ interface WaypointRuntimeActions {
     setCurrentStep(stepId: string): void;
     setIsSubmitting(b: boolean): void;
     setCompleted(b: boolean): void;
+    /** Marks a step as skipped (user chose to bypass it) */
+    skipStep(stepId: string): void;
+    /** Removes a step from the skipped list (e.g. when user goes back and fills it) */
+    unskipStep(stepId: string): void;
     /**
      * Truncates history to include only steps up to and including stepId.
      * Called before navigating forward so stale steps from a previous path are removed.
@@ -306,7 +338,7 @@ declare function registerCustomValidator(id: string, fn: (value: unknown) => boo
  * - Fields without a `required` validation rule are wrapped in `.optional()`.
  * - Numeric fields use `z.coerce.number()` so string inputs are coerced.
  */
-declare function buildZodSchema(fields: ResolvedField[], externalEnums?: ExternalEnum[]): z.ZodObject<z.ZodRawShape>;
+declare function buildZodSchema(fields: ResolvedField[], externalEnums?: ExternalEnum[], data?: JourneyData): z.ZodObject<z.ZodRawShape>;
 
 /**
  * Runtime validation for WaypointSchema JSON.
@@ -400,4 +432,4 @@ declare function extractURLParamsFromTree(pathname: string, allSteps: StepDefini
 declare function extractOnlyMissingParams(pathname: string, allSteps: StepDefinition[], missingParamNames: string[]): WaypointParams;
 declare function mergeContextParams(userParams: WaypointParams | undefined, pathname: string, allSteps: StepDefinition[], targetURL?: string): WaypointParams;
 
-export { type BuiltinFieldType, type ConditionGroup, type ConditionOperator, type ConditionRule, type CreateRuntimeStoreOptions, type CustomTypeDefinition, type ExternalEnum, type ExternalVariable, type ExternalVars, type FieldDefinition, type FieldType, type JourneyData, type JourneyState, type JourneyTreeStep, type JourneyTreeType, type PersistenceMode, type ResolvedField, type ResolvedStep, type ResolvedTree, type RuntimeStore, type SchemaValidationResult, type SelectOption, type StepDefinition$1 as StepDefinition, URLTemplateEngine, type ValidationRule, type ValidationRuleType, type WaypointParams, type WaypointRuntimeActions, type WaypointRuntimeState, type WaypointRuntimeStore, type WaypointSchema, assertSchema, buildZodSchema, calculateProgress, calculateProgressFromState, createRuntimeStore, evaluateConditionGroup, extractOnlyMissingParams, extractURLParamsFromTree, findLastValidStep, findMatchingStep, findStepIndex, getCurrentStep, getMissingBlockingVars, getNextStep, getNextStepFromState, getPreviousStep, getPreviousStepFromState, getResolvedTree, hasPersistedState, isVisible, mergeContextParams, registerCustomValidator, resolveFieldValue, resolveTree, validateSchema };
+export { type BuiltinFieldType, type ConditionGroup, type ConditionOperator, type ConditionRule, type CreateRuntimeStoreOptions, type CustomTypeDefinition, type DynamicDefaultRule, type ExternalEnum, type ExternalVariable, type ExternalVars, type FieldDefinition, type FieldType, type JourneyData, type JourneyState, type JourneyTreeStep, type JourneyTreeType, type PersistenceMode, type ResolvedField, type ResolvedStep, type ResolvedTree, type RuntimeStore, type SchemaValidationResult, type SelectOption, type StepDefinition$1 as StepDefinition, URLTemplateEngine, type ValidationRule, type ValidationRuleType, type WaypointParams, type WaypointRuntimeActions, type WaypointRuntimeState, type WaypointRuntimeStore, type WaypointSchema, assertSchema, buildZodSchema, calculateProgress, calculateProgressFromState, createRuntimeStore, evaluateConditionGroup, extractOnlyMissingParams, extractURLParamsFromTree, findLastValidStep, findMatchingStep, findStepIndex, getCurrentStep, getMissingBlockingVars, getNextStep, getNextStepFromState, getPreviousStep, getPreviousStepFromState, getResolvedTree, hasPersistedState, isVisible, mergeContextParams, registerCustomValidator, resolveFieldValue, resolveTree, validateSchema };

package/dist/index.js

@@ -3,11 +3,15 @@ import { persist, createJSONStorage } from 'zustand/middleware';
 import { z } from 'zod';
 
 // src/conditions.ts
-function resolveFieldValue(path, data, externalVars) {
+function resolveFieldValue(path, data, externalVars, skippedSteps) {
   if (path.startsWith("$ext.")) {
     const varId = path.slice(5);
     return externalVars[varId];
   }
+  if (path.startsWith("$step.") && path.endsWith(".skipped")) {
+    const stepId2 = path.slice(6, -8);
+    return skippedSteps?.includes(stepId2) ?? false;
+  }
   const dotIndex = path.indexOf(".");
   if (dotIndex === -1) return void 0;
   const stepId = path.slice(0, dotIndex);
@@ -63,8 +67,8 @@ function evaluateOperator(operator, actual, expected) {
       return false;
   }
 }
-function evaluateRule(rule, data, externalVars, externalEnums) {
-  const actual = resolveFieldValue(rule.field, data, externalVars);
+function evaluateRule(rule, data, externalVars, externalEnums, skippedSteps) {
+  const actual = resolveFieldValue(rule.field, data, externalVars, skippedSteps);
   if ((rule.operator === "inEnum" || rule.operator === "notInEnum") && externalEnums) {
     const enumDef = externalEnums.find((e) => e.id === String(rule.value));
     const values = enumDef?.values.map((v) => String(v.value)) ?? [];
@@ -72,20 +76,20 @@ function evaluateRule(rule, data, externalVars, externalEnums) {
   }
   return evaluateOperator(rule.operator, actual, rule.value);
 }
-function evaluateConditionGroup(group, data, externalVars, externalEnums) {
+function evaluateConditionGroup(group, data, externalVars, externalEnums, skippedSteps) {
   const ruleResults = group.rules.map(
-    (rule) => evaluateRule(rule, data, externalVars, externalEnums)
+    (rule) => evaluateRule(rule, data, externalVars, externalEnums, skippedSteps)
   );
   const groupResults = (group.groups ?? []).map(
-    (subGroup) => evaluateConditionGroup(subGroup, data, externalVars, externalEnums)
+    (subGroup) => evaluateConditionGroup(subGroup, data, externalVars, externalEnums, skippedSteps)
   );
   const allResults = [...ruleResults, ...groupResults];
   if (allResults.length === 0) return true;
   return group.combinator === "and" ? allResults.every(Boolean) : allResults.some(Boolean);
 }
-function isVisible(visibleWhen, data, externalVars, externalEnums) {
+function isVisible(visibleWhen, data, externalVars, externalEnums, skippedSteps) {
   if (!visibleWhen) return true;
-  return evaluateConditionGroup(visibleWhen, data, externalVars, externalEnums);
+  return evaluateConditionGroup(visibleWhen, data, externalVars, externalEnums, skippedSteps);
 }
 
 // src/tree-resolver.ts
@@ -109,22 +113,32 @@ function findMissingBlockingVars(externalVariables, externalVars, visibleSteps)
     return value === void 0 || value === null;
   }).map((extVar) => extVar.id);
 }
-function resolveTree(schema, data, externalVars, externalEnums) {
+function resolveTree(schema, data, externalVars, externalEnums, skippedSteps) {
   const visibleSteps = [];
   const hiddenSteps = [];
   for (const stepDef of schema.steps) {
-    const stepVisible = isVisible(stepDef.visibleWhen, data, externalVars, externalEnums);
+    const stepVisible = isVisible(stepDef.visibleWhen, data, externalVars, externalEnums, skippedSteps);
     const resolvedFields = stepDef.fields.map((fieldDef) => {
       let resolvedOptions;
       if (fieldDef.externalEnumId && externalEnums) {
         const enumDef = externalEnums.find((e) => e.id === fieldDef.externalEnumId);
         resolvedOptions = enumDef?.values;
       }
+      let resolvedDefaultValue;
+      if (fieldDef.dynamicDefault && fieldDef.dynamicDefault.length > 0) {
+        for (const rule of fieldDef.dynamicDefault) {
+          if (evaluateConditionGroup(rule.when, data, externalVars, externalEnums, skippedSteps)) {
+            resolvedDefaultValue = rule.value;
+            break;
+          }
+        }
+      }
       return {
         definition: fieldDef,
-        visible: isVisible(fieldDef.visibleWhen, data, externalVars, externalEnums),
+        visible: isVisible(fieldDef.visibleWhen, data, externalVars, externalEnums, skippedSteps),
         dependenciesMet: areDependenciesMet(fieldDef.dependsOn, data, externalVars),
-        resolvedOptions
+        resolvedOptions,
+        resolvedDefaultValue
       };
     });
     const resolvedStep = {
@@ -191,7 +205,7 @@ function getResolvedTree(state) {
   if (!state.schema) {
     return { steps: [], hiddenSteps: [], missingExternalVars: [] };
   }
-  return resolveTree(state.schema, state.data, state.externalVars);
+  return resolveTree(state.schema, state.data, state.externalVars, void 0, state.skippedSteps);
 }
 function getCurrentStep(state) {
   if (!state.currentStepId) return void 0;
@@ -223,6 +237,7 @@ var initialState = {
   externalVars: {},
   currentStepId: null,
   history: [],
+  skippedSteps: [],
   isSubmitting: false,
   completed: false
 };
@@ -238,6 +253,7 @@ function buildStateCreator() {
         externalVars,
         currentStepId: firstStepId,
         history: firstStepId ? [firstStepId] : [],
+        skippedSteps: [],
         isSubmitting: false,
         completed: false
       });
@@ -279,6 +295,16 @@ function buildStateCreator() {
     setCompleted(b) {
       set({ completed: b });
     },
+    skipStep(stepId) {
+      set((state) => ({
+        skippedSteps: state.skippedSteps.includes(stepId) ? state.skippedSteps : [...state.skippedSteps, stepId]
+      }));
+    },
+    unskipStep(stepId) {
+      set((state) => ({
+        skippedSteps: state.skippedSteps.filter((id) => id !== stepId)
+      }));
+    },
     truncateHistoryAt(stepId) {
       set((state) => {
         const idx = state.history.indexOf(stepId);
@@ -317,6 +343,7 @@ function createRuntimeStore(options = {}) {
           data: state.data,
           currentStepId: state.currentStepId,
           history: state.history,
+          skippedSteps: state.skippedSteps,
           completed: state.completed
         })
       })
@@ -333,7 +360,13 @@ var customValidatorRegistry = {};
 function registerCustomValidator(id, fn) {
   customValidatorRegistry[id] = fn;
 }
-function buildFieldSchema(field, externalEnums) {
+function resolveRuleValue(rule, data) {
+  if (rule.refField && data) {
+    return resolveFieldValue(rule.refField, data, {});
+  }
+  return rule.value;
+}
+function buildFieldSchema(field, externalEnums, data) {
   const rules = field.validation ?? [];
   const isRequired = rules.some((r) => r.type === "required");
   const isNumeric = field.type === "number";
@@ -351,28 +384,47 @@ function buildFieldSchema(field, externalEnums) {
     let numSchema = z.coerce.number({
       invalid_type_error: "Must be a number"
     });
+    const numRefineRules = [];
     for (const rule of rules) {
+      const rv = resolveRuleValue(rule, data);
+      const isRef = !!rule.refField;
       if (rule.type === "min" || rule.type === "greaterThanOrEqual") {
-        const n = Number(rule.value);
-        if (!isNaN(n)) numSchema = numSchema.gte(n, rule.message);
+        const n = Number(rv);
+        if (!isNaN(n)) {
+          if (isRef) numRefineRules.push({ fn: (v) => v >= n, message: rule.message });
+          else numSchema = numSchema.gte(n, rule.message);
+        }
       } else if (rule.type === "max" || rule.type === "lessThanOrEqual") {
-        const n = Number(rule.value);
-        if (!isNaN(n)) numSchema = numSchema.lte(n, rule.message);
+        const n = Number(rv);
+        if (!isNaN(n)) {
+          if (isRef) numRefineRules.push({ fn: (v) => v <= n, message: rule.message });
+          else numSchema = numSchema.lte(n, rule.message);
+        }
       } else if (rule.type === "greaterThan") {
-        const n = Number(rule.value);
-        if (!isNaN(n)) numSchema = numSchema.gt(n, rule.message);
+        const n = Number(rv);
+        if (!isNaN(n)) {
+          if (isRef) numRefineRules.push({ fn: (v) => v > n, message: rule.message });
+          else numSchema = numSchema.gt(n, rule.message);
+        }
       } else if (rule.type === "lessThan") {
-        const n = Number(rule.value);
-        if (!isNaN(n)) numSchema = numSchema.lt(n, rule.message);
+        const n = Number(rv);
+        if (!isNaN(n)) {
+          if (isRef) numRefineRules.push({ fn: (v) => v < n, message: rule.message });
+          else numSchema = numSchema.lt(n, rule.message);
+        }
       } else if (rule.type === "equals") {
-        const n = Number(rule.value);
-        if (!isNaN(n)) numSchema = numSchema.refine((v) => v === n, rule.message);
+        const n = Number(rv);
+        if (!isNaN(n)) numRefineRules.push({ fn: (v) => v === n, message: rule.message });
       } else if (rule.type === "notEquals") {
-        const n = Number(rule.value);
-        if (!isNaN(n)) numSchema = numSchema.refine((v) => v !== n, rule.message);
+        const n = Number(rv);
+        if (!isNaN(n)) numRefineRules.push({ fn: (v) => v !== n, message: rule.message });
       }
     }
-    return isRequired ? numSchema : numSchema.optional();
+    let numFinal = isRequired ? numSchema : numSchema.optional();
+    for (const { fn, message } of numRefineRules) {
+      numFinal = numFinal.refine((v) => v == null || fn(v), message);
+    }
+    return numFinal;
   }
   let strSchema = z.string();
   const refineRules = [];
@@ -402,54 +454,70 @@ function buildFieldSchema(field, externalEnums) {
           strSchema = strSchema.regex(new RegExp(String(rule.value)), rule.message);
         }
         break;
-      case "equals":
-        if (rule.value !== void 0) {
-          const eq = String(rule.value);
+      case "equals": {
+        const rv = resolveRuleValue(rule, data);
+        if (rv !== void 0) {
+          const eq = String(rv);
           refineRules.push({ fn: (v) => String(v) === eq, message: rule.message });
         }
         break;
-      case "notEquals":
-        if (rule.value !== void 0) {
-          const neq = String(rule.value);
+      }
+      case "notEquals": {
+        const rv = resolveRuleValue(rule, data);
+        if (rv !== void 0) {
+          const neq = String(rv);
           refineRules.push({ fn: (v) => String(v) !== neq, message: rule.message });
         }
         break;
-      case "greaterThan":
-        if (rule.value !== void 0) {
-          const gt = Number(rule.value);
+      }
+      case "greaterThan": {
+        const rv = resolveRuleValue(rule, data);
+        if (rv !== void 0) {
+          const gt = Number(rv);
           refineRules.push({ fn: (v) => Number(v) > gt, message: rule.message });
         }
         break;
-      case "greaterThanOrEqual":
-        if (rule.value !== void 0) {
-          const gte = Number(rule.value);
+      }
+      case "greaterThanOrEqual": {
+        const rv = resolveRuleValue(rule, data);
+        if (rv !== void 0) {
+          const gte = Number(rv);
           refineRules.push({ fn: (v) => Number(v) >= gte, message: rule.message });
         }
         break;
-      case "lessThan":
-        if (rule.value !== void 0) {
-          const lt = Number(rule.value);
+      }
+      case "lessThan": {
+        const rv = resolveRuleValue(rule, data);
+        if (rv !== void 0) {
+          const lt = Number(rv);
           refineRules.push({ fn: (v) => Number(v) < lt, message: rule.message });
         }
         break;
-      case "lessThanOrEqual":
-        if (rule.value !== void 0) {
-          const lte = Number(rule.value);
+      }
+      case "lessThanOrEqual": {
+        const rv = resolveRuleValue(rule, data);
+        if (rv !== void 0) {
+          const lte = Number(rv);
           refineRules.push({ fn: (v) => Number(v) <= lte, message: rule.message });
         }
         break;
-      case "contains":
-        if (rule.value !== void 0) {
-          const sub = String(rule.value);
+      }
+      case "contains": {
+        const rv = resolveRuleValue(rule, data);
+        if (rv !== void 0) {
+          const sub = String(rv);
           refineRules.push({ fn: (v) => String(v).includes(sub), message: rule.message });
         }
         break;
-      case "notContains":
-        if (rule.value !== void 0) {
-          const nsub = String(rule.value);
+      }
+      case "notContains": {
+        const rv = resolveRuleValue(rule, data);
+        if (rv !== void 0) {
+          const nsub = String(rv);
           refineRules.push({ fn: (v) => !String(v).includes(nsub), message: rule.message });
         }
         break;
+      }
       case "matches":
         if (rule.value !== void 0 && rule.value !== null) {
           const rx = new RegExp(String(rule.value));
@@ -487,11 +555,11 @@ function buildFieldSchema(field, externalEnums) {
   }
   return finalSchema;
 }
-function buildZodSchema(fields, externalEnums) {
+function buildZodSchema(fields, externalEnums, data) {
   const shape = {};
   for (const resolvedField of fields) {
     if (!resolvedField.visible) continue;
-    shape[resolvedField.definition.id] = buildFieldSchema(resolvedField.definition, externalEnums);
+    shape[resolvedField.definition.id] = buildFieldSchema(resolvedField.definition, externalEnums, data);
   }
   return z.object(shape);
 }