@usefillo/core 0.20.0 → 0.22.0

package/dist/index.d.ts

@@ -131,9 +131,11 @@ interface HiddenField extends BaseField {
     paramName?: string;
     defaultValue?: string;
 }
+/** Maximum number of completed files in one upload-field answer. */
+declare const MAX_FILES_PER_FIELD = 200;
 interface FileUploadField extends BaseField {
     kind: "file_upload";
-    /** Max files, default 1. */
+    /** Max files, from 1 to 200. Default 1. */
     maxFiles?: number;
     /** Per-file size cap in MB. Default 500. */
     maxFileSizeMb?: number;
@@ -589,7 +591,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
@@ -1322,6 +1326,8 @@ declare class FilloClient {
     /** Server origin this client targets, normalized (no trailing slash). */
     readonly baseUrl: string;
     private fetch;
+    private activeUploads;
+    private uploadQueue;
     /** Publishable project key, when configured. */
     readonly key?: string;
     constructor(options?: FilloClientOptions);
@@ -1405,6 +1411,8 @@ declare class FilloClient {
      * form owner's Drive and never touch the Fillo server.
      */
     uploadFile(formId: string, file: File | Blob, options: UploadFileOptions): Promise<FileValue>;
+    private acquireUploadSlot;
+    private performUpload;
     /**
      * Box direct upload with a folder-scoped token (Box UI Elements pattern).
      * Small files go up in one multipart POST; large files run Box's chunked
@@ -1566,6 +1574,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 +1686,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 +1815,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>;
     /**
@@ -2234,4 +2252,4 @@ declare class Sha1 {
 }
 declare const sha1Base64: (bytes: Uint8Array) => string;
 
-export { type AutoSubmitContext, BLOCK_KIND_META, type BaseField, type Block, type BlockKind, CONTENT_KINDS, type CalcExpr, type CalculatedField, type ChallengeConfig, type ChallengeTheme, type CheckboxField, type ChoiceField, type CodeForm, type Condition, type ConditionOp, type ContentBlock, type ContentKind, type CreatedDraft, type CustomField, DEFAULT_FIELD_STRINGS, DEFAULT_RESPONDENT_ERROR_STRINGS, DEFAULT_STRINGS, DRAFT_KINDS, type DateField, type DividerBlock, FILLO_CALC_MIN_SDK_VERSION, FILLO_CHALLENGE_MIN_SDK_VERSION, FILLO_DATA_ATTRS, FILLO_GROUP_MIN_SDK_VERSION, FILLO_MIN_SDK_VERSION, FILLO_SCHEMA_VERSION, FILLO_SDK_VERSION, FILLO_SLOTS, FILLO_THEME_VARS, type Field, type FieldKind, type FieldSpec, type FieldValue, type FileUploadField, type FileValue, type FilloAppearance, FilloClient, type FilloClientOptions, FilloError, type FilloFieldStrings, FilloJsxError, type FilloRendererStrings, type FilloRespondent, type FilloSlot, type FilloStrings, type FormBranding, type FormController, type FormControllerOptions, type FormControllerState, type FormDraftSpec, type FormPage, type FormSchema, type FormSettings, type FormStatus, type FormTheme, type GroupInstanceValue, type HeadingBlock, type HiddenField, JSX_BLOCK_COMPONENTS, JSX_BLOCK_SPECS, type JsonValue, type JsxFormMeta, type JumpRule, type LinearScaleField, type MatrixField, type NextPage, type NumberField, PHONE_COUNTRIES, PHONE_PICKER_COUNTRIES, PHONE_POPOVER_VIEWPORT_GAP, type ParagraphBlock, type ParsePhoneOptions, type ParsedPhone, type PhoneCountry, type PhoneField, type PhonePopoverPlacement, type ProvisionWorkspaceResult, type PublishedForm, REQUIRED_FIELD_MESSAGE, type RankingField, type RatingField, type RepeatingGroupField, type RespondentErrorOverrides, type RespondentErrorStrings, type ResponseData, type ResponseDraft, type ResponseLimit, type SchemaValidationResult, type SelectOption, Sha1, type SignatureField, type SlotClass, type SlotState, type SubmitMeta, type SubmitResult, type SyncFormResult, type SyncedForm, type TextField, type TrustPolicy, type UploadFileOptions, type UploadProgress, type UploadSession, type UploadStatus, type UploadTransport, type ValidationResult, type WhenBuilder, allFields, assembleForm, codeFormFromJsx, computeCalculated, conditionsMet, contentHash, countryByDialCode, countryByIso, countryByTimeZone, createBlock, createClient, createEmptyForm, createFormController, createId, defineForm, digitsOnly, evaluateCalc, flagEmoji, formSchemasEqual, formatAnswer, formatGroupedNumber, formatNational, isAutoSubmitBlock, isBlockVisible, isBuildTimeDevEnv, isCodeForm, isField, isFilloError, isLikelyDevEnv, isPossiblePhone, isTerminalPage, isValidPartialNumberText, localeForNotation, needsExplicitSubmit, normalizeFormSchema, normalizeFormTheme, normalizeSettings, parseGroupedNumber, parsePhone, pipeBlock, positionPhonePopover, prefillFromParams, provisionWorkspace, radioGroupStep, reachableFieldIds, reachableFields, reachablePageIds, reachablePageSequence, requiredFieldMessage, resolveNextPage, resolveSlotClass, resolveStrings, resolveText, resolveThemeAppearance, respondentErrorStringsFor, responseScopeValue, schemaFromJsx, sha1Base64, shouldAutoSubmit, slotClass, syncCodeForm, toE164, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields, visibleGroupChildren, visiblePageBlocks, when };
+export { type AutoSubmitContext, BLOCK_KIND_META, type BaseField, type Block, type BlockKind, CONTENT_KINDS, type CalcExpr, type CalculatedField, type ChallengeConfig, type ChallengeTheme, type CheckboxField, type ChoiceField, type CodeForm, type Condition, type ConditionOp, type ContentBlock, type ContentKind, type CreatedDraft, type CustomField, DEFAULT_FIELD_STRINGS, DEFAULT_RESPONDENT_ERROR_STRINGS, DEFAULT_STRINGS, DRAFT_KINDS, type DateField, type DividerBlock, FILLO_CALC_MIN_SDK_VERSION, FILLO_CHALLENGE_MIN_SDK_VERSION, FILLO_DATA_ATTRS, FILLO_GROUP_MIN_SDK_VERSION, FILLO_MIN_SDK_VERSION, FILLO_SCHEMA_VERSION, FILLO_SDK_VERSION, FILLO_SLOTS, FILLO_THEME_VARS, type Field, type FieldKind, type FieldSpec, type FieldValue, type FileUploadField, type FileValue, type FilloAppearance, FilloClient, type FilloClientOptions, FilloError, type FilloFieldStrings, FilloJsxError, type FilloRendererStrings, type FilloRespondent, type FilloSlot, type FilloStrings, type FormBranding, type FormController, type FormControllerOptions, type FormControllerState, type FormDraftSpec, type FormPage, type FormSchema, type FormSettings, type FormStatus, type FormTheme, type GroupInstanceValue, type HeadingBlock, type HiddenField, JSX_BLOCK_COMPONENTS, JSX_BLOCK_SPECS, type JsonValue, type JsxFormMeta, type JumpRule, type LinearScaleField, MAX_FILES_PER_FIELD, type MatrixField, type NextPage, type NumberField, PHONE_COUNTRIES, PHONE_PICKER_COUNTRIES, PHONE_POPOVER_VIEWPORT_GAP, type ParagraphBlock, type ParsePhoneOptions, type ParsedPhone, type PhoneCountry, type PhoneField, type PhonePopoverPlacement, type ProvisionWorkspaceResult, type PublishedForm, REQUIRED_FIELD_MESSAGE, type RankingField, type RatingField, type RepeatingGroupField, type RespondentErrorOverrides, type RespondentErrorStrings, type ResponseData, type ResponseDraft, type ResponseLimit, type SchemaValidationResult, type SelectOption, Sha1, type SignatureField, type SlotClass, type SlotState, type SubmitMeta, type SubmitResult, type SyncFormResult, type SyncedForm, type TextField, type TrustPolicy, type UploadFileOptions, type UploadProgress, type UploadSession, type UploadStatus, type UploadTransport, type ValidationResult, type WhenBuilder, allFields, assembleForm, codeFormFromJsx, computeCalculated, conditionsMet, contentHash, countryByDialCode, countryByIso, countryByTimeZone, createBlock, createClient, createEmptyForm, createFormController, createId, defineForm, digitsOnly, evaluateCalc, flagEmoji, formSchemasEqual, formatAnswer, formatGroupedNumber, formatNational, isAutoSubmitBlock, isBlockVisible, isBuildTimeDevEnv, isCodeForm, isField, isFilloError, isLikelyDevEnv, isPossiblePhone, isTerminalPage, isValidPartialNumberText, localeForNotation, needsExplicitSubmit, normalizeFormSchema, normalizeFormTheme, normalizeSettings, parseGroupedNumber, parsePhone, pipeBlock, positionPhonePopover, prefillFromParams, provisionWorkspace, radioGroupStep, reachableFieldIds, reachableFields, reachablePageIds, reachablePageSequence, requiredFieldMessage, resolveNextPage, resolveSlotClass, resolveStrings, resolveText, resolveThemeAppearance, respondentErrorStringsFor, responseScopeValue, schemaFromJsx, sha1Base64, shouldAutoSubmit, slotClass, syncCodeForm, toE164, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields, visibleGroupChildren, visiblePageBlocks, when };

package/dist/index.js

@@ -1,4 +1,5 @@
 // src/types.ts
+var MAX_FILES_PER_FIELD = 200;
 var CONTENT_KINDS = ["heading", "paragraph", "divider"];
 function isField(block) {
   return !CONTENT_KINDS.includes(block.kind);
@@ -311,11 +312,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 +794,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 +1114,7 @@ var schemaShape = z2.object({
 });
 var MAX_SCHEMA_VERSION = 1;
 var FILLO_SCHEMA_VERSION = 1;
-var FILLO_SDK_VERSION = true ? "0.20.0" : "0.0.0-dev";
+var FILLO_SDK_VERSION = true ? "0.22.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";
@@ -1734,7 +1736,7 @@ function normalizeBlock(input) {
     case "file_upload":
       return cleanObject({
         ...baseField(rec, kind),
-        maxFiles: int(rec.maxFiles, 1, 20, 1),
+        maxFiles: int(rec.maxFiles, 1, MAX_FILES_PER_FIELD, 1),
         maxFileSizeMb: int(rec.maxFileSizeMb, 1, 5e3, 500),
         accept: Array.isArray(rec.accept) ? rec.accept.flatMap((v) => {
           const item = optionalStr(v, 100);
@@ -2471,6 +2473,7 @@ function retryAfterSec(res) {
   return Number.isFinite(raw) && raw > 0 ? raw : void 0;
 }
 var MAX_CHUNK_RETRIES = 3;
+var MAX_CONCURRENT_UPLOADS = 4;
 var DEFAULT_TIMEOUT_MS = 3e4;
 var S3_PART_TIMEOUT_MS = 5 * 6e4;
 var UPLOAD_CONTROL_TIMEOUT_MS = 10 * 6e4;
@@ -2544,6 +2547,8 @@ var FilloClient = class {
   /** Server origin this client targets, normalized (no trailing slash). */
   baseUrl;
   fetch;
+  activeUploads = 0;
+  uploadQueue = /* @__PURE__ */ new Set();
   /** Publishable project key, when configured. */
   key;
   constructor(options2 = {}) {
@@ -2750,6 +2755,40 @@ var FilloClient = class {
    * form owner's Drive and never touch the Fillo server.
    */
   async uploadFile(formId, file, options2) {
+    await this.acquireUploadSlot(options2.signal);
+    try {
+      options2.signal?.throwIfAborted();
+      return await this.performUpload(formId, file, options2);
+    } finally {
+      this.activeUploads -= 1;
+      const next = this.uploadQueue.values().next().value;
+      if (next) {
+        this.uploadQueue.delete(next);
+        next();
+      }
+    }
+  }
+  async acquireUploadSlot(signal) {
+    signal?.throwIfAborted();
+    if (this.activeUploads < MAX_CONCURRENT_UPLOADS) {
+      this.activeUploads += 1;
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      const start = () => {
+        signal?.removeEventListener("abort", aborted);
+        this.activeUploads += 1;
+        resolve();
+      };
+      const aborted = () => {
+        this.uploadQueue.delete(start);
+        reject(signal?.reason);
+      };
+      this.uploadQueue.add(start);
+      signal?.addEventListener("abort", aborted, { once: true });
+    });
+  }
+  async performUpload(formId, file, options2) {
     const name = typeof File !== "undefined" && file instanceof File ? file.name : "upload.bin";
     const mime = (file.type || "application/octet-stream").trim().toLowerCase();
     let session;
@@ -3431,6 +3470,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 +3572,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 +3601,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 +3805,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 +3814,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 +3830,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 +3850,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 +3892,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 +3998,7 @@ function createFormController(options2) {
     setValue,
     setUploading,
     next,
+    skipPreviewPage,
     back,
     submit,
     setContext(ctx) {
@@ -3955,6 +4043,8 @@ function createFormController(options2) {
       data = computeCalculated(form, data);
       errors = {};
       pageIndex = 0;
+      previewStartPageId = void 0;
+      previewHistory.length = 0;
       submitError = void 0;
       resumedDraft = false;
       editingPrevious = false;
@@ -4714,6 +4804,7 @@ export {
   FilloJsxError,
   JSX_BLOCK_COMPONENTS,
   JSX_BLOCK_SPECS,
+  MAX_FILES_PER_FIELD,
   PHONE_COUNTRIES,
   PHONE_PICKER_COUNTRIES,
   PHONE_POPOVER_VIEWPORT_GAP,

package/package.json

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