@usefillo/core 0.9.0 → 0.10.0

package/README.md

@@ -1,9 +1,23 @@
-# @usefillo/core
+<p align="center">
+  <a href="https://fillo.so">
+    <img src="https://fillo.so/brand/readme-banner.png" alt="Fillo — forms inside your product, with your UI." />
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://fillo.so/docs">Docs</a> ·
+  <a href="https://fillo.so/guides">Guides</a> ·
+  <a href="https://fillo.so/examples">Examples</a> ·
+  <a href="https://fillo.so/changelog">Changelog</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@usefillo/core"><img src="https://img.shields.io/npm/v/@usefillo/core" alt="npm version" /></a>
+  <img src="https://img.shields.io/npm/l/@usefillo/core" alt="MIT license" />
+</p>
 
 The framework-agnostic core of [Fillo](https://fillo.so) — forms that render **inside your own product**, with your UI, no iframe.
 
-### 📚 Full documentation → **[fillo.so/docs](https://fillo.so/docs)**
-
 This package holds the shared foundation: the form schema, validation, the conditional-logic engine, response prefill/piping, and a JS client for provider-aware browser-direct uploads, with resume support where the storage provider offers it. It has **zero framework dependencies**.
 
 Most apps don't install this directly — you install a renderer (**[@usefillo/react](https://www.npmjs.com/package/@usefillo/react)** or **[@usefillo/dom](https://www.npmjs.com/package/@usefillo/dom)**), which re-exports everything here you need for embedding. Reach for `@usefillo/core` when you're building your own renderer or working with forms on the server.
@@ -28,9 +42,7 @@ const form = defineForm({
 
 Published renderer embeds can fetch by `formId` without a key. Use a client object for custom API origins, uploads, or submissions from your own renderer; add a publishable key only when syncing `defineForm()` schemas from code.
 
-Schema settings include `submitMode: "auto"` for one-tap forms that should submit after a complete discrete answer instead of rendering the first submit button, and `responseLimit: { by: "browser", onRepeat: "keep" }` for browser-scoped duplicate prevention. Themes include `colorScheme: "light" | "dark" | "auto"` for renderer defaults.
-
-Key exports: `createClient` / `FilloClient`, `defineForm`, `validateResponse`, `validateField`, `visibleBlocks`, and the schema types (`FormSchema`, `Field`, `FieldKind`, `FormTheme`, `ResponseData`, …).
+The full export surface — client methods, schema types, validation, conditional logic, appearance and localization contracts — is documented in the [API reference](https://fillo.so/docs/reference).
 
 ## Links
 
@@ -38,10 +50,3 @@ Key exports: `createClient` / `FilloClient`, `defineForm`, `validateResponse`, `
 - **Website:** [fillo.so](https://fillo.so)
 
 MIT licensed.
-
-## Additional authoring surface
-
-Framework-neutral pieces the renderers share: `defineForm` / `schemaFromJsx`
-(the JSX compiler), `when()` condition builder, the `FilloAppearance` styling
-contract (slots + data-attribute names), `FilloStrings` localization defaults,
-and `createClient({ baseUrl })` for staging/self-hosted targets.

package/dist/index.d.ts

@@ -708,6 +708,23 @@ interface PublishedForm {
     theme: FormTheme | null;
     /** True when the server says the form cannot accept responses. */
     closed?: boolean;
+    /**
+     * Whether a submission would be accepted right now. Absent on older servers
+     * — renderers must then keep today's behavior. When false, the default
+     * renderers show the not-open overlay instead of a fillable form.
+     */
+    accepting?: boolean;
+    /**
+     * Companion to `accepting` — present only when it is false.
+     * `draft`: not published yet; `expired`/`capped`: the unclaimed preview
+     * workspace hit its time window or response cap. Storage reasons may be
+     * returned for drafts or by older servers; published upload readiness is
+     * represented independently by `uploadsAvailable`.
+     */
+    acceptingReason?: "draft" | "expired" | "capped" | "storage_required" | "storage_full";
+    /** Whether new file uploads can start right now. Absent on older servers is
+     * treated as available; this never changes whether ordinary answers submit. */
+    uploadsAvailable?: boolean;
     /** Workspace branding state — absent means show the badge (default). */
     branding?: FormBranding;
     /** Human-verification challenge to render before submit, when the form
@@ -861,6 +878,24 @@ interface SyncFormResult {
     status?: "draft" | "published";
     /** Changes were staged as a draft for a human to publish. */
     staged?: boolean;
+    /**
+     * Whether a submission would be accepted right now. Absent on older servers
+     * — renderers must then keep today's behavior. When false, the default
+     * renderers show the not-open overlay instead of a fillable form.
+     */
+    accepting?: boolean;
+    /**
+     * Companion to `accepting` — present only when it is false.
+     * `draft`: not published yet; `expired`/`capped`: the unclaimed preview
+     * workspace hit its time window or response cap; `storage_required`: the
+     * form needs a connected storage destination before it can go live;
+     * `storage_full`: Fillo's temporary upload allowance is exhausted.
+     */
+    acceptingReason?: "draft" | "expired" | "capped" | "storage_required" | "storage_full";
+    /** Whether new file uploads can start right now. This is independent from
+     * response acceptance so a completed file can still be submitted after the
+     * workspace reaches its upload cap. Absent on older servers means available. */
+    uploadsAvailable?: boolean;
     /**
      * Server-authoritative live snapshot. Present when the incoming code schema
      * is not the version respondents may submit against yet.
@@ -872,7 +907,23 @@ interface SyncFormResult {
         code: string;
         message: string;
     };
+    /**
+     * Human-readable storage heads-up for the form owner. This can be advisory
+     * while uploads and responses remain available; never use it to gate UI.
+     */
     warning?: string;
+    /**
+     * Machine-readable owner advisory for `warning`. Hard unavailability uses
+     * `"storage_required"`; transit threshold advisories use distinct codes.
+     * Point the human at `warningUrl`; use `uploadsAvailable`, not this field,
+     * to gate new file controls.
+     */
+    warningCode?: string;
+    /**
+     * Absolute dashboard URL where a human connects a storage destination.
+     * Present whenever `warningCode` is.
+     */
+    warningUrl?: string;
 }
 declare class FilloClient {
     /** Server origin this client targets, normalized (no trailing slash). */
@@ -1070,6 +1121,15 @@ interface FormControllerOptions {
      * runs; failure sets `submitError` and the respondent can retry.
      */
     resolveFormId?: () => Promise<string>;
+    /**
+     * Surface the REAL {@link resolveFormId} failure (message + machine code)
+     * in `submitError` instead of the respondent-safe "This form is
+     * unavailable." fallback. Dev chrome only: renderers set it from the same
+     * gate as their other developer surfaces (preview prop / dev environment),
+     * so production visitors never see integration details such as keys,
+     * origins, or deployment commands.
+     */
+    verboseResolutionErrors?: boolean;
     /**
      * Host-app account context (identify()): who is filling this form, by your
      * own user id. Sent with the submission and recorded as an unverified
@@ -1350,6 +1410,14 @@ interface FilloStrings {
     successMessage: string;
     closed: string;
     notLive: string;
+    /** Title of the not-open overlay card (a draft/storage-blocked form rendered
+     *  in production shows the real form blurred beneath it). */
+    notOpenTitle: string;
+    /** Body of the not-open overlay card. */
+    notOpenBody: string;
+    /** Title of the closed-flavor overlay card (expired/capped workspace);
+     *  the body reuses `closed`. */
+    closedTitle: string;
     /** Fallback when a submit fails without a server message. */
     submitFailed: string;
     loadFailedNotFound: string;
@@ -1384,6 +1452,8 @@ interface FilloFieldStrings {
     uploadRetry: string;
     /** Dropzone copy when uploads can't run (no client / preview). */
     uploadsDisabled: string;
+    /** Dropzone copy when the server temporarily refuses new file sessions. */
+    uploadsUnavailable: string;
     /** An upload attempt failed with no actionable server message. */
     uploadFailed: string;
     /** Dropzone call to action; `multiple` is true when several files are allowed. */
@@ -1419,6 +1489,20 @@ interface SyncedForm {
     status?: "draft" | "published";
     /** Changes were staged as a draft for a human to publish. */
     staged?: boolean;
+    /** Whether a submission would be accepted right now. Absent on older
+     *  servers — renderers must then keep the status-based behavior. */
+    accepting?: boolean;
+    /**
+     * Companion to `accepting` — present only when it is false. `draft`: not
+     * published yet; `expired`/`capped`: the unclaimed preview workspace hit its
+     * time window or response cap; `storage_required`: the form needs a
+     * connected storage destination before it can go live; `storage_full`:
+     * Fillo's temporary upload allowance is exhausted.
+     */
+    acceptingReason?: "draft" | "expired" | "capped" | "storage_required" | "storage_full";
+    /** Whether new file uploads can start right now. Independent from response
+     * acceptance; absent on older servers means available. */
+    uploadsAvailable?: boolean;
     /** Server-authoritative live snapshot when local code is not live yet. */
     resolvedSchema?: FormSchema;
     resolvedTheme?: FormTheme | null;
@@ -1428,6 +1512,15 @@ interface SyncedForm {
         message: string;
     };
     warning?: string;
+    /**
+     * Machine-readable owner advisory for `warning`. Hard unavailability uses
+     * `"storage_required"`; advisory thresholds use distinct codes. Use
+     * `uploadsAvailable`, not this field, to decide whether an upload may start.
+     */
+    warningCode?: string;
+    /** Absolute dashboard URL where a human connects a storage destination.
+     *  Present whenever `warningCode` is. */
+    warningUrl?: string;
 }
 /**
  * A form whose structure lives in user code. Development and explicit
@@ -1543,6 +1636,37 @@ interface WhenBuilder {
 }
 declare function when(fieldId: string): WhenBuilder;
 
+/**
+ * The build-time half of the dev check: `NODE_ENV` alone, no hostname
+ * inspection. It evaluates identically on the server and in the browser for
+ * the same bundle, which is what SSR hydration needs — the server has no
+ * `window`, so a hostname-aware check would disagree with the client's first
+ * paint. Renderers use this as the server/hydration snapshot and upgrade to
+ * {@link isLikelyDevEnv} after hydration.
+ */
+declare function isBuildTimeDevEnv(): boolean;
+/**
+ * Whether this runtime looks like local development, so renderers can show
+ * actionable dev surfaces (draft banner, missing-client warning, local schema
+ * render) instead of the deliberately quiet production states.
+ *
+ * The build-time `NODE_ENV` signal alone misses real local setups: the
+ * standalone `<script>` bundle has no `process` at all (so it always read as
+ * production), `vite preview` / `next start` serve a production build on
+ * localhost, and some bundlers never define `NODE_ENV`. So a browser whose
+ * hostname is localhost/loopback also counts as development. Real
+ * deployments keep production semantics because they serve from real
+ * hostnames — see {@link isLocalHostname} for why mDNS `*.local` names and
+ * private-LAN addresses are deliberately excluded.
+ *
+ * SSR-safe to CALL (with no `window`, only the `NODE_ENV` check applies), but
+ * NOT hydration-safe for render output: the server pass can't see the page
+ * hostname, so under `next start` on localhost it disagrees with the client.
+ * Render paths should hydrate from {@link isBuildTimeDevEnv} and upgrade to
+ * this check after hydration (see the React renderer's useIsDevEnv()).
+ */
+declare function isLikelyDevEnv(): boolean;
+
 /**
  * Build initial response data from URL query parameters — Tally-style
  * prefilling. Hidden fields read their configured paramName; every other
@@ -1587,4 +1711,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 ChallengeConfig, type CheckboxField, type ChoiceField, type CodeForm, type Condition, type ConditionOp, type ContentBlock, type ContentKind, type CreatedDraft, type CustomField, DEFAULT_FIELD_STRINGS, DEFAULT_STRINGS, DRAFT_KINDS, type DateField, type DividerBlock, FILLO_CHALLENGE_MIN_SDK_VERSION, FILLO_DATA_ATTRS, 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 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_POPOVER_VIEWPORT_GAP, type ParagraphBlock, type ParsedPhone, type PhoneCountry, type PhoneField, type PhonePopoverPlacement, type ProvisionWorkspaceResult, type PublishedForm, REQUIRED_FIELD_MESSAGE, type RankingField, type RatingField, 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, conditionsMet, contentHash, countryByDialCode, countryByIso, countryByTimeZone, createBlock, createClient, createEmptyForm, createFormController, createId, defineForm, digitsOnly, flagEmoji, formSchemasEqual, formatAnswer, formatNational, isAutoSubmitBlock, isBlockVisible, isCodeForm, isField, isFilloError, isPossiblePhone, isTerminalPage, needsExplicitSubmit, normalizeFormSchema, normalizeFormTheme, normalizeSettings, parsePhone, pipeBlock, positionPhonePopover, prefillFromParams, provisionWorkspace, reachableFieldIds, reachableFields, reachablePageIds, reachablePageSequence, resolveNextPage, resolveSlotClass, resolveStrings, resolveText, responseScopeValue, schemaFromJsx, sha1Base64, shouldAutoSubmit, slotClass, syncCodeForm, toE164, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields, visiblePageBlocks, when };
+export { type AutoSubmitContext, BLOCK_KIND_META, type BaseField, type Block, type BlockKind, CONTENT_KINDS, type ChallengeConfig, type CheckboxField, type ChoiceField, type CodeForm, type Condition, type ConditionOp, type ContentBlock, type ContentKind, type CreatedDraft, type CustomField, DEFAULT_FIELD_STRINGS, DEFAULT_STRINGS, DRAFT_KINDS, type DateField, type DividerBlock, FILLO_CHALLENGE_MIN_SDK_VERSION, FILLO_DATA_ATTRS, 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 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_POPOVER_VIEWPORT_GAP, type ParagraphBlock, type ParsedPhone, type PhoneCountry, type PhoneField, type PhonePopoverPlacement, type ProvisionWorkspaceResult, type PublishedForm, REQUIRED_FIELD_MESSAGE, type RankingField, type RatingField, 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, conditionsMet, contentHash, countryByDialCode, countryByIso, countryByTimeZone, createBlock, createClient, createEmptyForm, createFormController, createId, defineForm, digitsOnly, flagEmoji, formSchemasEqual, formatAnswer, formatNational, isAutoSubmitBlock, isBlockVisible, isBuildTimeDevEnv, isCodeForm, isField, isFilloError, isLikelyDevEnv, isPossiblePhone, isTerminalPage, needsExplicitSubmit, normalizeFormSchema, normalizeFormTheme, normalizeSettings, parsePhone, pipeBlock, positionPhonePopover, prefillFromParams, provisionWorkspace, reachableFieldIds, reachableFields, reachablePageIds, reachablePageSequence, resolveNextPage, resolveSlotClass, resolveStrings, resolveText, responseScopeValue, schemaFromJsx, sha1Base64, shouldAutoSubmit, slotClass, syncCodeForm, toE164, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields, visiblePageBlocks, when };

package/dist/index.js

@@ -501,6 +501,9 @@ var DEFAULT_STRINGS = {
   successMessage: "Your response has been recorded.",
   closed: "This form is no longer accepting responses.",
   notLive: "This form isn't live yet.",
+  notOpenTitle: "Not open just yet",
+  notOpenBody: "This form is still being set up. Check back soon.",
+  closedTitle: "Responses are closed",
   submitFailed: "This form can't submit right now. Please try again in a moment.",
   loadFailedNotFound: "Form not found \u2014 check the form id and that it's published.",
   loadFailedNetwork: "Couldn't reach the server \u2014 check your connection or CORS.",
@@ -517,6 +520,7 @@ var DEFAULT_FIELD_STRINGS = {
   alreadyAnswered: "You've already answered this form.",
   uploadRetry: "Retry",
   uploadsDisabled: "Uploads are disabled in preview",
+  uploadsUnavailable: "Uploads are temporarily unavailable",
   uploadFailed: "Upload failed \u2014 try again",
   dropzoneTitle: (multiple) => `Drop ${multiple ? "files" : "a file"} here or click to browse`,
   dropzoneHint: (maxMb) => `Up to ${maxMb} MB per file`,
@@ -772,7 +776,7 @@ var schemaShape = z2.object({
 });
 var MAX_SCHEMA_VERSION = 1;
 var FILLO_SCHEMA_VERSION = 1;
-var FILLO_SDK_VERSION = true ? "0.9.0" : "0.0.0-dev";
+var FILLO_SDK_VERSION = true ? "0.10.0" : "0.0.0-dev";
 var FILLO_MIN_SDK_VERSION = "0.4.0";
 var FILLO_CHALLENGE_MIN_SDK_VERSION = "0.9.0";
 function str(value, max, fallback = "") {
@@ -2471,9 +2475,12 @@ function submitFailureMessage(err) {
   if (isFilloError(err) && err.status && err.status > 0 && err.message) return err.message;
   return "Couldn't reach the server \u2014 check your connection and try again. If this keeps happening, a browser extension, firewall, or the site's Content-Security-Policy may be blocking the request.";
 }
-function syncResolutionFailureMessage(err) {
+function syncResolutionFailureMessage(err, verbose) {
   if (isFilloError(err)) {
     const status = err.status ?? 0;
+    if (verbose && status > 0 && err.message) {
+      return err.code ? `${err.message} (${err.code})` : err.message;
+    }
     const definitive = status > 0 && status < 500 && status !== 408 && status !== 429;
     if (definitive) return "This form is unavailable.";
   }
@@ -2849,7 +2856,10 @@ function createFormController(options2) {
         formId = await options2.resolveFormId();
       } catch (err) {
         status = "idle";
-        submitError = syncResolutionFailureMessage(err);
+        submitError = syncResolutionFailureMessage(
+          err,
+          options2.verboseResolutionErrors === true
+        );
         notify();
         throw err;
       }
@@ -3148,7 +3158,7 @@ function formSchemasEqual(left, right) {
   return JSON.stringify(canonicalize(left)) === JSON.stringify(canonicalize(right));
 }
 var syncTtlMs = (status) => status === "published" ? 36e5 : 6e4;
-var isVolatileSync = (result) => Boolean(result.staged || result.resolvedSchema || result.syncError);
+var isVolatileSync = (result) => Boolean(result.staged || result.resolvedSchema || result.syncError || result.accepting === false);
 function storageKey(client, handle) {
   return `fillo:sync:v3:${client.baseUrl}|${client.key}|${handle}`;
 }
@@ -3167,7 +3177,7 @@ function readStoredSync(client, handle, hash) {
   }
 }
 function writeStoredSync(client, handle, hash, r) {
-  if (r.staged || r.resolvedSchema || r.syncError) return;
+  if (r.staged || r.resolvedSchema || r.syncError || r.accepting === false) return;
   if (r.challenge) return;
   try {
     globalThis.localStorage?.setItem(
@@ -3548,6 +3558,23 @@ function when(fieldId) {
   };
 }
 
+// src/dev-env.ts
+function isLocalHostname(hostname) {
+  const host = hostname.toLowerCase();
+  return host === "localhost" || host.endsWith(".localhost") || // Loopback ADDRESSES only — anchored so `127.0.0.1.example.com` stays a
+  // real (production) hostname.
+  /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host) || host === "::1" || host === "[::1]" || host === "0.0.0.0";
+}
+function isBuildTimeDevEnv() {
+  return typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
+}
+function isLikelyDevEnv() {
+  if (isBuildTimeDevEnv()) return true;
+  if (typeof window === "undefined") return false;
+  const hostname = window.location?.hostname;
+  return typeof hostname === "string" && isLocalHostname(hostname);
+}
+
 // src/piping.ts
 var TOKEN = /\{\{\s*([\w-]+)\s*\}\}/g;
 function resolveText(text, data, form) {
@@ -3618,9 +3645,11 @@ export {
   formatNational,
   isAutoSubmitBlock,
   isBlockVisible,
+  isBuildTimeDevEnv,
   isCodeForm,
   isField,
   isFilloError,
+  isLikelyDevEnv,
   isPossiblePhone,
   isTerminalPage,
   needsExplicitSubmit,

package/package.json

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