@waypointjs/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,385 @@
+import * as zustand_vanilla from 'zustand/vanilla';
+import { z } from 'zod';
+
+/**
+ * Waypoint JSON Schema — v1
+ *
+ * Auto-sufficient tree definition generated by @waypointjs/builder.
+ * Versioned to allow non-breaking evolution.
+ */
+type ConditionOperator = "equals" | "notEquals" | "greaterThan" | "greaterThanOrEqual" | "lessThan" | "lessThanOrEqual" | "contains" | "notContains" | "in" | "notIn" | "exists" | "notExists" | "matches";
+/**
+ * A single condition rule.
+ * `field` is a dot-path: "stepId.fieldId" for journey data, or "$ext.varId" for external variables.
+ */
+interface ConditionRule {
+    field: string;
+    operator: ConditionOperator;
+    value?: unknown;
+}
+/**
+ * A condition group — rules combined with AND or OR.
+ * Rules within a group are combined with `combinator`.
+ * Groups can be nested via `groups`.
+ */
+interface ConditionGroup {
+    combinator: "and" | "or";
+    rules: ConditionRule[];
+    groups?: ConditionGroup[];
+}
+type ValidationRuleType = "required" | "min" | "max" | "minLength" | "maxLength" | "email" | "url" | "regex" | "custom";
+interface ValidationRule {
+    type: ValidationRuleType;
+    /** Value for min/max/minLength/maxLength/regex rules */
+    value?: string | number;
+    /** Error message shown to the user */
+    message: string;
+    /** For "custom" type: identifier of the validator function registered at runtime */
+    customValidatorId?: 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 */
+type FieldType = BuiltinFieldType | (string & {});
+interface SelectOption {
+    label: string;
+    value: string | number;
+}
+interface FieldDefinition {
+    id: string;
+    type: FieldType;
+    label: string;
+    placeholder?: string;
+    defaultValue?: unknown;
+    /** Options for select/multiselect/radio fields */
+    options?: SelectOption[];
+    validation?: ValidationRule[];
+    /** Controls visibility of this field within its step */
+    visibleWhen?: ConditionGroup;
+    /** Data dependencies: fields/variables that must have a value before this field is accessible */
+    dependsOn?: string[];
+}
+interface StepDefinition$1 {
+    id: string;
+    title: string;
+    /** URL pattern for this step — supports {{PARAM}} placeholders */
+    url: string;
+    fields: FieldDefinition[];
+    /** Controls visibility/insertion of this step in the resolved tree */
+    visibleWhen?: ConditionGroup;
+    /** Whether this step can be used as a resume point */
+    enableResumeFromHere?: boolean;
+}
+interface ExternalVariable {
+    id: string;
+    label: string;
+    /** JavaScript type hint */
+    type: "string" | "number" | "boolean" | "object";
+    /** If true, Waypoint will throw at runtime if this variable is missing before it is needed */
+    blocking: boolean;
+    /** Steps / fields that depend on this variable — informational, used by the builder */
+    usedIn?: Array<{
+        stepId: string;
+        fieldId?: string;
+    }>;
+}
+/**
+ * A custom field type registered in the builder.
+ * `metadata` is passed through as-is so the backend can enrich it.
+ */
+interface CustomTypeDefinition {
+    id: string;
+    label: string;
+    /** Icon name or URL — used by the builder UI */
+    icon?: string;
+    /** Default validation rules applied when this type is used */
+    defaultValidation?: ValidationRule[];
+    /** Arbitrary metadata — enrichable by the backend */
+    metadata?: Record<string, unknown>;
+}
+type PersistenceMode = "zustand" | "backend-step" | "backend-manual";
+interface WaypointSchema {
+    /** Schema version — increment on breaking changes */
+    version: "1";
+    /** Unique identifier for this journey definition */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Ordered list of steps — order reflects default display order */
+    steps: StepDefinition$1[];
+    /** External variables this journey depends on */
+    externalVariables?: ExternalVariable[];
+    /** Custom field types registered for this journey */
+    customTypes?: CustomTypeDefinition[];
+    /** Default persistence mode */
+    persistenceMode?: PersistenceMode;
+    /** Arbitrary metadata */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * All journey data, keyed by stepId then fieldId.
+ * Example: { personal: { age: 25, name: "Alice" }, billing: { plan: "pro" } }
+ */
+type JourneyData = Record<string, Record<string, unknown>>;
+/**
+ * External variables injected at runtime.
+ * Example: { isPremium: true, userId: "abc-123" }
+ */
+type ExternalVars = Record<string, unknown>;
+/**
+ * Resolves a field path to its value from the data context.
+ * - "stepId.fieldId"  → journey data
+ * - "$ext.varId"      → external variable
+ */
+declare function resolveFieldValue(path: string, data: JourneyData, externalVars: ExternalVars): 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): 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): boolean;
+
+/** A field after condition evaluation */
+interface ResolvedField {
+    definition: FieldDefinition;
+    /** Whether the field is currently visible */
+    visible: boolean;
+    /** Whether all dependsOn paths have a non-empty value */
+    dependenciesMet: boolean;
+}
+/** A step after condition evaluation */
+interface ResolvedStep {
+    definition: StepDefinition$1;
+    /** Whether this step is currently in the active tree */
+    visible: boolean;
+    /** Visible fields for this step, in definition order */
+    fields: ResolvedField[];
+}
+/** Result returned by resolveTree */
+interface ResolvedTree {
+    /** Ordered list of visible steps */
+    steps: ResolvedStep[];
+    /** Steps hidden by conditions — data preserved in tmp store */
+    hiddenSteps: ResolvedStep[];
+    /** Errors: external variables required but missing */
+    missingExternalVars: string[];
+}
+/**
+ * Resolves the journey tree against current data and external variables.
+ *
+ * - Steps with a falsy `visibleWhen` are moved to `hiddenSteps`
+ * - Fields within each visible step are evaluated for visibility and dependencies
+ * - Missing blocking external variables are reported
+ *
+ * This function is pure: same inputs always produce same outputs.
+ */
+declare function resolveTree(schema: WaypointSchema, data: JourneyData, externalVars: ExternalVars): ResolvedTree;
+/**
+ * Returns the index of the step with the given id in the resolved (visible) tree.
+ * Returns -1 if not found.
+ */
+declare function findStepIndex(steps: ResolvedStep[], stepId: string): number;
+/**
+ * Returns the next visible step after the given stepId, or undefined if last.
+ */
+declare function getNextStep(steps: ResolvedStep[], currentStepId: string): ResolvedStep | undefined;
+/**
+ * Returns the previous visible step before the given stepId, or undefined if first.
+ */
+declare function getPreviousStep(steps: ResolvedStep[], currentStepId: string): ResolvedStep | undefined;
+/**
+ * Calculates progress (0–100) based on the resolved visible tree.
+ * Uses the index of the current step in the visible tree.
+ */
+declare function calculateProgress(steps: ResolvedStep[], currentStepId: string): number;
+/**
+ * Given journey data, finds the deepest step the user can access:
+ * the last step in the visible tree for which all visible fields
+ * have their dependencies met.
+ */
+declare function findLastValidStep(steps: ResolvedStep[], data: JourneyData, _externalVars: ExternalVars): ResolvedStep | undefined;
+
+interface WaypointRuntimeState {
+    schema: WaypointSchema | null;
+    /** { stepId: { fieldId: value } } */
+    data: Record<string, Record<string, unknown>>;
+    /** { varId: value } */
+    externalVars: Record<string, unknown>;
+    currentStepId: string | null;
+    /** Step IDs visited in order */
+    history: string[];
+    isSubmitting: boolean;
+    /** True once onComplete has been called (all steps validated) */
+    completed: boolean;
+}
+interface WaypointRuntimeActions {
+    /**
+     * Fresh start: sets schema + data and navigates to the first step (or startStepId).
+     * Always resets navigation state (currentStepId, history).
+     */
+    init(schema: WaypointSchema, options?: {
+        data?: Record<string, Record<string, unknown>>;
+        externalVars?: Record<string, unknown>;
+        startStepId?: string;
+    }): void;
+    /**
+     * Resume a previously-started journey.
+     * Updates schema + externalVars but preserves data, currentStepId and history
+     * as they were persisted (e.g. from localStorage).
+     */
+    resume(schema: WaypointSchema, externalVars?: Record<string, unknown>): void;
+    setFieldValue(stepId: string, fieldId: string, value: unknown): void;
+    setStepData(stepId: string, data: Record<string, unknown>): void;
+    setExternalVar(varId: string, value: unknown): void;
+    setCurrentStep(stepId: string): void;
+    setIsSubmitting(b: boolean): void;
+    setCompleted(b: boolean): 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.
+     */
+    truncateHistoryAt(stepId: string): void;
+    reset(): void;
+}
+type WaypointRuntimeStore = WaypointRuntimeState & WaypointRuntimeActions;
+declare function getResolvedTree(state: WaypointRuntimeState): ResolvedTree;
+declare function getCurrentStep(state: WaypointRuntimeState): ResolvedStep | undefined;
+declare function getNextStepFromState(state: WaypointRuntimeState): ResolvedStep | undefined;
+declare function getPreviousStepFromState(state: WaypointRuntimeState): ResolvedStep | undefined;
+declare function calculateProgressFromState(state: WaypointRuntimeState): number;
+declare function getMissingBlockingVars(state: WaypointRuntimeState): string[];
+interface CreateRuntimeStoreOptions {
+    persistenceMode?: string;
+    schemaId?: string;
+}
+/**
+ * Creates a new runtime store instance (vanilla Zustand, no React dependency).
+ *
+ * Each schema gets its own isolated store — multiple `<WaypointRunner>` instances
+ * with different schemas can coexist simultaneously without sharing state.
+ *
+ * @param options.persistenceMode - If "zustand", activates localStorage persistence
+ * @param options.schemaId - Used to build the persistence key (and to validate resume)
+ */
+declare function createRuntimeStore(options?: CreateRuntimeStoreOptions): zustand_vanilla.StoreApi<WaypointRuntimeStore>;
+/**
+ * Returns true if the store has valid persisted state for the given schema id.
+ * Used by WaypointRunner to decide whether to call `resume()` or `init()`.
+ *
+ * Relies on the fact that localStorage hydration is synchronous, so by the time
+ * the first `useEffect` runs, the persisted slice is already merged into state.
+ */
+declare function hasPersistedState(store: ReturnType<typeof createRuntimeStore>, schemaId: string): boolean;
+type RuntimeStore = ReturnType<typeof createRuntimeStore>;
+
+/**
+ * Register a custom validator function by id.
+ * Used for ValidationRule type="custom" with a matching customValidatorId.
+ */
+declare function registerCustomValidator(id: string, fn: (value: unknown) => boolean): void;
+/**
+ * Builds a Zod object schema from a list of resolved fields.
+ *
+ * - Only visible fields are included in the schema.
+ * - 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[]): z.ZodObject<z.ZodRawShape>;
+
+/**
+ * Runtime validation for WaypointSchema JSON.
+ *
+ * Validates structure and basic constraints without relying on TypeScript types.
+ * Designed to be used at import time (builder) and at boot time (runtime).
+ */
+
+interface SchemaValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validates a raw parsed JSON value as a WaypointSchema.
+ *
+ * Returns `{ valid: true, errors: [] }` when the schema is acceptable.
+ * Returns `{ valid: false, errors: [...] }` with a list of human-readable errors otherwise.
+ */
+declare function validateSchema(raw: unknown): SchemaValidationResult;
+/**
+ * Convenience: assert a schema is valid, throw with all errors if not.
+ * Useful in tests or runtime boot checks.
+ */
+declare function assertSchema(raw: unknown): asserts raw is WaypointSchema;
+
+/**
+ * A single step within a journey tree category.
+ */
+interface JourneyTreeStep {
+    /**
+     * When true, automatically enables canResumeToDeepestStep when this step is reached.
+     */
+    enableResumeFromHere?: boolean;
+    /** Unique step identifier */
+    step: string;
+    /** URL template — supports {{PARAM}} placeholders */
+    url: string;
+}
+/** A logical grouping of steps */
+interface JourneyTreeCategory {
+    category: string;
+    steps: JourneyTreeStep[];
+}
+/** The full navigation tree for a journey, ordered list of categories */
+type JourneyTreeType = JourneyTreeCategory[];
+/** Generic URL parameters map — keys are placeholder names, values are strings or numbers */
+type WaypointParams = Record<string, string | number | undefined>;
+/** Runtime state for a single journey */
+interface JourneyState {
+    canResumeToDeepestStep: boolean;
+    currentStep: string | null;
+    deepestStepVisited: string;
+    history: string[];
+    progress: number;
+    tree: JourneyTreeType;
+}
+
+interface StepDefinition {
+    step: string;
+    url: string;
+}
+/**
+ * Utility class for URL template formatting and validation.
+ * Templates use `{{PARAM_NAME}}` syntax.
+ *
+ * @example
+ * URLTemplateEngine.format("/users/{{USER_ID}}/posts/{{POST_ID}}", { USER_ID: "42", POST_ID: "hello" })
+ * // => "/users/42/posts/hello"
+ */
+declare class URLTemplateEngine {
+    private static readonly PLACEHOLDER_PATTERN;
+    /**
+     * Replace all `{{PARAM}}` placeholders in a template with the provided values.
+     * Missing params are left as-is.
+     */
+    static format(template: string, params: WaypointParams): string;
+    /**
+     * Extract all placeholder names from a URL template.
+     */
+    static extractPlaceholders(template: string): string[];
+    /**
+     * Validate that all placeholders in the template have corresponding params.
+     */
+    static validate(template: string, params: WaypointParams): {
+        isValid: boolean;
+        missingParams: string[];
+    };
+}
+declare function findMatchingStep(pathname: string, allSteps: StepDefinition[]): StepDefinition | null;
+declare function extractURLParamsFromTree(pathname: string, allSteps: StepDefinition[]): WaypointParams;
+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 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 };