@usefillo/core 0.19.0 → 0.21.0

package/dist/index.d.ts

@@ -589,7 +589,9 @@ declare function resolveNextPage(form: FormSchema, currentPageId: string, data:
  * it reduces to today's linear behavior. {@link reachablePageIds} is the set of
  * this exact walk (one walk, no divergence).
  */
-declare function reachablePageSequence(form: FormSchema, data: ResponseData): string[];
+declare function reachablePageSequence(form: FormSchema, data: ResponseData, 
+/** Optional starting page for inspecting a branch in a local form preview. */
+startPageId?: string): string[];
 /**
  * The page ids reachable for the given data. The unordered set of
  * {@link reachablePageSequence} — one shared walk keeps the ordered navigation
@@ -1566,6 +1568,8 @@ declare function respondentErrorStringsFor(strings: Pick<FilloStrings, "submitFa
  * an exhaustively-enumerated, closed set.
  */
 interface FilloFieldStrings {
+    /** Browse the next page in a render-only form preview without answering. */
+    previewSkip: string;
     /** Optional, backward-compatible overrides for respondent error states that
      * do not already have a top-level renderer string. */
     respondentErrors?: Partial<RespondentErrorOverrides>;
@@ -1676,6 +1680,12 @@ interface FormControllerOptions {
      * option to change visitor-facing behavior such as branding.
      */
     skipValidation?: boolean;
+    /**
+     * Enable explicit page skipping in a transportless preview. Requires
+     * skipValidation and no client, formId, or resolver. Native next() still
+     * validates; skipPreviewPage() alone bypasses validation and page routing.
+     */
+    previewNavigation?: boolean;
     /**
      * Embedding surface, recorded per response for measurement. "headless" = a
      * bare engine with no Fillo-rendered layout (createFormController /
@@ -1799,6 +1809,8 @@ interface FormController {
     setUploading(fieldId: string, busy: boolean): void;
     /** Validate the current page, then advance. No-op on the last page or with errors. */
     next(): void;
+    /** Browse the next physical page in an explicitly enabled local preview. */
+    skipPreviewPage(): void;
     back(): void;
     submit(): Promise<void>;
     /**

package/dist/index.js

@@ -311,11 +311,11 @@ function resolveNextPage(form, currentPageId, data) {
   }
   return { linear: true };
 }
-function reachablePageSequence(form, data) {
+function reachablePageSequence(form, data, startPageId) {
   const seq = [];
   if (form.pages.length === 0) return seq;
   const seen = /* @__PURE__ */ new Set();
-  let index = 0;
+  let index = startPageId === void 0 ? 0 : form.pages.findIndex((p) => p.id === startPageId);
   for (let steps = 0; steps <= form.pages.length; steps++) {
     const page = form.pages[index];
     if (!page || seen.has(page.id)) break;
@@ -793,6 +793,7 @@ function defaultRequiredForField(field2) {
   return REQUIRED_BY_KIND[field2.kind] ?? REQUIRED_FIELD_MESSAGE;
 }
 var DEFAULT_FIELD_STRINGS = {
+  previewSkip: "Skip",
   required: REQUIRED_FIELD_MESSAGE,
   requiredForField: defaultRequiredForField,
   resumeLinkExpired: "That saved-progress link expired or was already used \u2014 start again below.",
@@ -1112,7 +1113,7 @@ var schemaShape = z2.object({
 });
 var MAX_SCHEMA_VERSION = 1;
 var FILLO_SCHEMA_VERSION = 1;
-var FILLO_SDK_VERSION = true ? "0.19.0" : "0.0.0-dev";
+var FILLO_SDK_VERSION = true ? "0.21.0" : "0.0.0-dev";
 var FILLO_MIN_SDK_VERSION = "0.4.0";
 var FILLO_CHALLENGE_MIN_SDK_VERSION = "0.9.0";
 var FILLO_CALC_MIN_SDK_VERSION = "0.11.0";
@@ -3431,6 +3432,23 @@ function createFormController(options2) {
   let data = computeCalculated(form, { ...options2.initialData ?? {} });
   let errors = {};
   let pageIndex = 0;
+  let previewStartPageId;
+  const previewHistory = [];
+  function previewNavigationEnabled() {
+    return options2.previewNavigation === true && options2.skipValidation === true && !client && !formId && !options2.resolveFormId;
+  }
+  function navigationSequence() {
+    return reachablePageSequence(
+      form,
+      data,
+      previewNavigationEnabled() ? previewStartPageId : void 0
+    );
+  }
+  function rememberPreviewPage() {
+    if (previewNavigationEnabled()) {
+      previewHistory.push({ pageIndex, startPageId: previewStartPageId });
+    }
+  }
   let status = "idle";
   let restoredSubmission = false;
   let resumeLinkFailed = false;
@@ -3516,7 +3534,7 @@ function createFormController(options2) {
       // Terminal-aware: true when the current page is the last reachable page OR
       // a matched jump rule ends the form here — so the footer reads Submit and
       // its handler submits. Same shared engine the validator reaches with.
-      isLastPage: isTerminalPage(form, page.id, data),
+      isLastPage: previewNavigationEnabled() && previewStartPageId !== void 0 ? navigationSequence().at(-1) === page.id : isTerminalPage(form, page.id, data),
       uploading: uploadingFields.size > 0,
       submitError,
       restoredSubmission,
@@ -3545,6 +3563,7 @@ function createFormController(options2) {
     const pageErrors = {};
     for (const block of visiblePageBlocks(form, target, data)) {
       if (!isField(block)) continue;
+      if (previewNavigationEnabled() && block.kind === "file_upload") continue;
       const error = validateField(block, data[block.id]);
       if (error) pageErrors[block.id] = error;
     }
@@ -3748,7 +3767,7 @@ function createFormController(options2) {
   function next() {
     const pageCount = form.pages.length;
     const clamped = Math.min(pageIndex, Math.max(pageCount - 1, 0));
-    if (!options2.skipValidation) {
+    if (!options2.skipValidation || options2.previewNavigation === true) {
       const pageErrors = validatePage(clamped);
       errors = pageErrors;
       if (Object.keys(pageErrors).length > 0) {
@@ -3757,14 +3776,15 @@ function createFormController(options2) {
       }
     }
     const current = form.pages[clamped];
-    const seq = reachablePageSequence(form, data);
+    const seq = navigationSequence();
     const pos = currentSeqPosition(seq);
-    const terminal = (current ? isTerminalPage(form, current.id, data) : true) || pos < 0 || pos + 1 >= seq.length;
+    const terminal = (previewNavigationEnabled() && previewStartPageId !== void 0 ? seq.at(-1) === current?.id : current ? isTerminalPage(form, current.id, data) : true) || pos < 0 || pos + 1 >= seq.length;
     if (terminal) {
       void submit();
       return;
     }
     const nextIndex = form.pages.findIndex((p) => p.id === seq[pos + 1]);
+    rememberPreviewPage();
     pageIndex = nextIndex >= 0 ? nextIndex : Math.min(clamped + 1, pageCount - 1);
     if (sessionId && client) client.reportProgress(sessionId, { furthestPage: pageIndex });
     notify();
@@ -3772,6 +3792,14 @@ function createFormController(options2) {
   }
   function back() {
     errors = {};
+    const previous = previewNavigationEnabled() ? previewHistory.pop() : void 0;
+    if (previous) {
+      pageIndex = Math.min(previous.pageIndex, form.pages.length - 1);
+      previewStartPageId = previous.startPageId;
+      submitError = void 0;
+      notify();
+      return;
+    }
     const seq = reachablePageSequence(form, data);
     const pos = currentSeqPosition(seq);
     if (pos > 0) {
@@ -3784,8 +3812,25 @@ function createFormController(options2) {
     notify();
     checkpointDraft();
   }
+  function skipPreviewPage() {
+    if (!previewNavigationEnabled() || status === "submitting" || status === "submitted" || pageIndex >= form.pages.length - 1)
+      return;
+    rememberPreviewPage();
+    pageIndex += 1;
+    previewStartPageId = form.pages[pageIndex]?.id;
+    errors = {};
+    submitError = void 0;
+    notify();
+  }
   async function submit() {
     if (status === "submitting" || status === "submitted") return;
+    if (previewNavigationEnabled()) {
+      errors = validatePage(pageIndex);
+      if (Object.keys(errors).length > 0) {
+        notify();
+        return;
+      }
+    }
     const result = validateResponse(form, data);
     if (!result.ok) {
       const transportlessPreview = options2.skipValidation && !(client && formId);
@@ -3809,7 +3854,11 @@ function createFormController(options2) {
       const firstBad = form.pages.findIndex(
         (p) => visiblePageBlocks(form, p, data).some((b) => b.id in previewErrors)
       );
-      if (firstBad >= 0) pageIndex = firstBad;
+      if (firstBad >= 0) {
+        pageIndex = firstBad;
+        previewStartPageId = void 0;
+        previewHistory.length = 0;
+      }
       notify();
       return;
     }
@@ -3911,6 +3960,7 @@ function createFormController(options2) {
     setValue,
     setUploading,
     next,
+    skipPreviewPage,
     back,
     submit,
     setContext(ctx) {
@@ -3955,6 +4005,8 @@ function createFormController(options2) {
       data = computeCalculated(form, data);
       errors = {};
       pageIndex = 0;
+      previewStartPageId = void 0;
+      previewHistory.length = 0;
       submitError = void 0;
       resumedDraft = false;
       editingPrevious = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefillo/core",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Form schema, validation, logic engine and JS client for Fillo. Framework-agnostic.",
   "license": "MIT",
   "keywords": [