@usefillo/core 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -39,8 +39,9 @@ interface PhoneField extends BaseField {
     kind: "phone";
     /**
      * Country selected when the form opens (ISO-3166 alpha-2, e.g. "US"). When
-     * unset the renderer falls back to the respondent's browser locale, then the
-     * first country in the list. The respondent can always change it.
+     * unset the renderer falls back to the respondent's browser timezone, browser
+     * locale, then the first country in the list. The respondent can always
+     * change it.
      */
     defaultCountry?: string;
 }
@@ -351,6 +352,7 @@ declare const PHONE_COUNTRIES: PhoneCountry[];
 /** Flag emoji from an ISO-3166 alpha-2 code (regional-indicator letters). */
 declare function flagEmoji(iso2: string): string;
 declare function countryByIso(iso2: string | undefined): PhoneCountry | undefined;
+declare function countryByTimeZone(timeZone: string | undefined): PhoneCountry | undefined;
 /** Country whose dial code is the longest prefix of these digits (no "+"). */
 declare function countryByDialCode(digits: string): PhoneCountry | undefined;
 /** Keep only 0-9 (and a leading "+") from arbitrary input. */
@@ -447,6 +449,11 @@ interface FilloClientOptions {
      * so they hit localhost in dev and fillo.so in prod. Not for embedding.
      */
     sameOrigin?: boolean;
+    /**
+     * Target a different Fillo server (staging, tests, a proxy on your own
+     * domain). Defaults to the hosted API; wins over sameOrigin.
+     */
+    baseUrl?: string;
     fetch?: typeof fetch;
 }
 interface PublishedForm {
@@ -465,14 +472,19 @@ interface PublishedForm {
     /** Workspace branding state — absent means show the badge (default). */
     branding?: FormBranding;
 }
-interface SubmitResult {
-    ok: boolean;
-    responseId?: string;
+type SubmitResult = {
+    ok: true;
+    responseId: string;
     /** True when the API accepted the request as an already-recorded visitor response. */
     duplicate?: boolean;
+    errors?: undefined;
+} | {
+    ok: false;
     /** fieldId -> message when the server rejects the submission. */
-    errors?: Record<string, string>;
-}
+    errors: Record<string, string>;
+    responseId?: undefined;
+    duplicate?: undefined;
+};
 /** Anti-spam signals collected by the renderer. */
 interface SubmitMeta {
     /** Honeypot value — must be empty for humans. */
@@ -504,7 +516,23 @@ interface UploadFileOptions {
 }
 declare class FilloError extends Error {
     status?: number | undefined;
-    constructor(message: string, status?: number | undefined);
+    /** Server-suggested wait (from a 429's Retry-After header), seconds. */
+    retryAfterSec?: number | undefined;
+    constructor(message: string, status?: number | undefined, 
+    /** Server-suggested wait (from a 429's Retry-After header), seconds. */
+    retryAfterSec?: number | undefined);
+}
+/** Duck-typed — `instanceof` breaks when two SDK copies end up in one bundle. */
+declare function isFilloError(err: unknown): err is FilloError;
+interface SyncFormResult {
+    formId: string;
+    slug: string;
+    branding?: FormBranding;
+    /** Lifecycle on newer servers: a draft can't accept public responses yet. */
+    status?: "draft" | "published";
+    /** Changes were staged as a draft for a human to publish. */
+    staged?: boolean;
+    warning?: string;
 }
 declare class FilloClient {
     /** Server origin this client targets, normalized (no trailing slash). */
@@ -521,11 +549,7 @@ declare class FilloClient {
      * Upsert a code-defined form into the workspace identified by the client's
      * publishable key. Returns the canonical form id used for submissions.
      */
-    syncForm(handle: string, schema: FormSchema, theme?: FormTheme | null): Promise<{
-        formId: string;
-        slug: string;
-        branding?: FormBranding;
-    }>;
+    syncForm(handle: string, schema: FormSchema, theme?: FormTheme | null): Promise<SyncFormResult>;
     /** Submit a response. Returns per-field errors instead of throwing on validation failure. */
     submit(formId: string, data: ResponseData, meta?: SubmitMeta): Promise<SubmitResult>;
     /**
@@ -561,6 +585,12 @@ declare class FilloClient {
      * Box; we return the new file id for /complete to verify server-side.
      */
     private boxUpload;
+    /**
+     * Caller signal (if any) combined with a fresh per-request timeout. Created per
+     * fetch so each retry attempt gets its own deadline; the caller's own abort
+     * still drives the resumable-upload cancel semantics.
+     */
+    private uploadSignal;
     /** Retry a request with exponential backoff; never retries an aborted upload. */
     private retry;
     /**
@@ -635,12 +665,20 @@ interface FormControllerOptions {
      */
     skipValidation?: boolean;
     /**
-     * Embedding surface. "headless" (a bare engine with no Fillo-rendered layout,
-     * i.e. createFormController / <FilloProvider>) is a paid capability the server
-     * enforces at submit. The framed renderers (<FilloForm>, renderForm) are
-     * "default". Defaults to "default".
+     * Embedding surface, recorded per response for measurement. "headless" = a
+     * bare engine with no Fillo-rendered layout (createFormController /
+     * <FilloProvider>); the framed renderers (<FilloForm>, renderForm) pass
+     * "default" explicitly. Defaults to "headless" — a bare createFormController
+     * is itself headless.
      */
     surface?: "default" | "headless";
+    /**
+     * Resolve the submission target at submit time when `formId` is still
+     * unset — e.g. re-run a code-form sync that failed at mount. Answers are
+     * held (never dropped) while it runs; failure sets `submitError` and the
+     * respondent can retry.
+     */
+    resolveFormId?: () => Promise<string>;
 }
 interface FormControllerState {
     data: ResponseData;
@@ -656,6 +694,8 @@ interface FormControllerState {
     isLastPage: boolean;
     /** True while any file field is uploading. */
     uploading: boolean;
+    /** Human-readable message for the last failed submit; cleared on edit/retry. */
+    submitError?: string;
 }
 interface FormController {
     /** Stable snapshot — same reference until something changes (safe for useSyncExternalStore). */
@@ -686,11 +726,132 @@ interface FormController {
 }
 declare function createFormController(options: FormControllerOptions): FormController;
 
+/**
+ * The auto-submit decision, shared by every renderer (react, dom, and any
+ * future surface) so "one tap, no button" behaves identically everywhere.
+ */
+declare function isAutoSubmitBlock(block: Block): boolean;
+/**
+ * Whether an auto-submit form still needs a visible submit button. Only a
+ * single visible field that can auto-submit goes button-less; more than one
+ * visible field → always a button. (Pass the visible blocks.)
+ */
+declare function needsExplicitSubmit(visible: Block[]): boolean;
+interface AutoSubmitContext {
+    form: FormSchema;
+    data: ResponseData;
+    status: FormStatus;
+    isLastPage: boolean;
+    uploading: boolean;
+}
+declare function shouldAutoSubmit(field: Field, value: FieldValue, ctx: AutoSubmitContext): boolean;
+
+/**
+ * The styling contract, shared by every renderer: named slots a consumer can
+ * attach classes to, and data-* attributes that expose state so utility CSS
+ * (Tailwind `data-[invalid]:…`) can react to it. Slot names and attribute
+ * names are public API — renames are breaking; additions are minors.
+ */
+declare const FILLO_SLOTS: readonly ["root", "header", "title", "description", "pageTitle", "progress", "progressFill", "blocks", "field", "label", "fieldDescription", "control", "options", "option", "optionLabel", "error", "footer", "button", "success"];
+type FilloSlot = (typeof FILLO_SLOTS)[number];
+/** data-* names emitted alongside the stable fillo-* classes. */
+declare const FILLO_DATA_ATTRS: {
+    /** Slot name, on every slot element: `data-fillo="control"`. */
+    readonly slot: "data-fillo";
+    /** Field kind, on the field wrapper: `data-kind="email"`. */
+    readonly kind: "data-kind";
+    /** Field id, on the field wrapper (pre-existing). */
+    readonly field: "data-field";
+    readonly invalid: "data-invalid";
+    readonly required: "data-required";
+    /** Selected option row / active scale step / active star. */
+    readonly selected: "data-selected";
+    /** Checkbox / toggle checked state. */
+    readonly checked: "data-checked";
+    readonly dragOver: "data-drag-over";
+    /** Engine status on the root: idle | submitting | submitted | error. */
+    readonly state: "data-state";
+    readonly page: "data-page";
+    readonly lastPage: "data-last-page";
+};
+/** State handed to `classNames` functions so classes can vary by it. */
+interface SlotState {
+    slot: FilloSlot;
+    kind?: BlockKind;
+    fieldId?: string;
+    optionId?: string;
+    invalid?: boolean;
+    required?: boolean;
+    selected?: boolean;
+    checked?: boolean;
+    dragOver?: boolean;
+    status?: FormStatus;
+    /** "primary" | "ghost" on the button slot. */
+    variant?: string;
+}
+type SlotClass = string | ((state: SlotState) => string);
+interface FilloAppearance {
+    /** Highest-precedence theme tokens (over prop/code/dashboard themes). */
+    theme?: FormTheme;
+    /** Class strings appended after the built-in fillo-* class, per slot. */
+    classNames?: Partial<Record<FilloSlot, SlotClass>>;
+    /** Per-field overrides, keyed by field id — appended after the slot class. */
+    fields?: Record<string, Partial<Record<FilloSlot, SlotClass>>>;
+}
+/**
+ * Resolve the consumer classes for a slot: general slot class first, then the
+ * per-field override. Returns "" when nothing applies. The badge is
+ * deliberately not a slot — appearance can never reach it.
+ */
+declare function resolveSlotClass(appearance: FilloAppearance | undefined, state: SlotState): string;
+/** Append resolved consumer classes to a base fillo-* class string. */
+declare function slotClass(base: string, appearance: FilloAppearance | undefined, state: SlotState): string;
+
+/**
+ * Every visitor-facing string the default renderers emit, overridable as a
+ * unit so a localized site never shows stray English at the submit moment.
+ * Schema-authored text (labels, descriptions, success copy set in settings)
+ * always wins over these defaults.
+ */
+interface FilloStrings {
+    back: string;
+    next: string;
+    submit: string;
+    submitting: string;
+    uploading: string;
+    /** Suffix on non-required field labels. */
+    optional: string;
+    /** The "Other" free-text choice. */
+    other: string;
+    otherPrompt: string;
+    otherPlaceholder: string;
+    /** Dropdown placeholder when the field sets none. */
+    choosePlaceholder: string;
+    /** Success screen defaults — settings.successTitle/successMessage win. */
+    successTitle: string;
+    successMessage: string;
+    closed: string;
+    notLive: string;
+    /** Fallback when a submit fails without a server message. */
+    submitFailed: string;
+    loadFailedNotFound: string;
+    loadFailedNetwork: string;
+    loadFailed: string;
+    renderFailed: string;
+}
+declare const DEFAULT_STRINGS: FilloStrings;
+declare function resolveStrings(overrides?: Partial<FilloStrings>): FilloStrings;
+
 /** Result of syncing a code-defined form: its canonical id, slug, and branding. */
 interface SyncedForm {
     formId: string;
     slug: string;
     branding?: FormBranding;
+    /** Lifecycle on newer servers: a draft can't accept public responses yet. */
+    status?: "draft" | "published";
+    /** Changes were staged as a draft for a human to publish. */
+    staged?: boolean;
+    warning?: string;
 }
 /**
  * A form whose structure lives in user code. Framework renderers can show it
@@ -717,9 +878,87 @@ declare function isCodeForm(form: unknown): form is CodeForm;
 declare function contentHash(input: string): string;
 /**
  * Sync a code-defined form into a workspace at most once per session for the
- * same client, handle, schema, and theme.
+ * same client, handle, schema, and theme. `bypassCache` forces the network —
+ * used by submit-time resolution, where a stale cached formId must not be
+ * trusted over a fresh sync.
+ */
+declare function syncCodeForm(client: FilloClient, form: CodeForm, opts?: {
+    bypassCache?: boolean;
+}): Promise<SyncedForm>;
+
+/**
+ * JSX authoring: `<Fillo.Email id="email" …/>` elements are INERT descriptors —
+ * never rendered, only walked. The walk is a pure function over element-shaped
+ * objects ({type, props}) with zero react imports, so the same components and
+ * compiler work in the browser, in RSC-adjacent client modules, and in Node
+ * (CLI extraction). Output is the exact CodeForm defineForm() emits: the sync
+ * pipeline, server, and dashboard never see JSX.
+ *
+ * Emission is canonical and sparse (only authored props, fixed key order) —
+ * it feeds the pre-normalization content hash, so ANY change here re-syncs
+ * every deployed JSX form. The wire-format snapshot test guards it.
+ */
+/** Stable error codes; messages carry the fix. Data-integrity errors throw in
+ * production too — a silently dropped duplicate id would corrupt response keys. */
+declare class FilloJsxError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+declare const BRAND: unique symbol;
+interface BlockSpec {
+    /** Component name, for error messages: Fillo.<name>. */
+    name: string;
+    kind: string;
+    /** Canonical emit order after id/kind; visibleIf always emits last. */
+    props: readonly string[];
+    /** Accepts <Fillo.Option> children as the options list. */
+    optionChildren?: boolean;
+    /** String children become the `text` prop (heading/paragraph). */
+    textChildren?: boolean;
+    /** Content blocks carry no label/required/etc. */
+    content?: boolean;
+}
+/** One entry per authorable block — the anti-fan-out manifest: components,
+ * walk emission, and the docs table all derive from it. */
+declare const JSX_BLOCK_SPECS: readonly BlockSpec[];
+type Branded = {
+    (props: unknown): never;
+    [BRAND]?: BlockSpec;
+};
+/** The inert authoring components, keyed by their Fillo.* name. */
+declare const JSX_BLOCK_COMPONENTS: Record<string, Branded>;
+/** Schema-relevant props on <Fillo.Form> — everything else (client, appearance,
+ * onSubmitted, …) is renderer configuration the walk must ignore. */
+interface JsxFormMeta {
+    id: string;
+    title?: string;
+    description?: string;
+    settings?: FormSettings;
+    theme?: FormTheme;
+}
+declare function schemaFromJsx(children: unknown, meta: Omit<JsxFormMeta, "theme">): FormSchema;
+/** Compile <Fillo.Form> props (or the element from Fillo.defineForm(jsx)) into
+ * the same CodeForm defineForm() produces — the sync pipeline sees no JSX. */
+declare function codeFormFromJsx(meta: JsxFormMeta, children: unknown): CodeForm;
+
+/**
+ * Typed builder for visibleIf conditions — pure data out, canonical key order
+ * ({fieldId, op, value?}) so it participates in content hashing unchanged.
+ * Conditions AND together (schema semantics); there is deliberately no OR.
+ *
+ *   visibleIf={when("topic").eq("sales")}
+ *   visibleIf={[when("topic").answered(), when("score").lt(5)]}
  */
-declare function syncCodeForm(client: FilloClient, form: CodeForm): Promise<SyncedForm>;
+interface WhenBuilder {
+    eq(value: string | number | boolean): Condition;
+    neq(value: string | number | boolean): Condition;
+    contains(value: string | number | boolean): Condition;
+    gt(value: number): Condition;
+    lt(value: number): Condition;
+    answered(): Condition;
+    notAnswered(): Condition;
+}
+declare function when(fieldId: string): WhenBuilder;
 
 /**
  * Build initial response data from URL query parameters — Tally-style
@@ -765,4 +1004,4 @@ declare class Sha1 {
 }
 declare const sha1Base64: (bytes: Uint8Array) => string;
 
-export { BLOCK_KIND_META, type BaseField, type Block, type BlockKind, CONTENT_KINDS, type CheckboxField, type ChoiceField, type CodeForm, type Condition, type ConditionOp, type ContentBlock, type ContentKind, type CustomField, DRAFT_KINDS, type DateField, type DividerBlock, FILLO_SCHEMA_VERSION, FILLO_SDK_VERSION, type Field, type FieldKind, type FieldSpec, type FieldValue, type FileUploadField, type FileValue, FilloClient, type FilloClientOptions, FilloError, type FormBranding, type FormController, type FormControllerOptions, type FormControllerState, type FormDraftSpec, type FormPage, type FormSchema, type FormSettings, type FormStatus, type FormTheme, type HeadingBlock, type HiddenField, type JsonValue, type LinearScaleField, type MatrixField, type NumberField, PHONE_COUNTRIES, type ParagraphBlock, type ParsedPhone, type PhoneCountry, type PhoneField, type ProvisionWorkspaceResult, type PublishedForm, type RankingField, type RatingField, type ResponseData, type SchemaValidationResult, type SelectOption, Sha1, type SignatureField, type SubmitMeta, type SubmitResult, type SyncedForm, type TextField, type UploadFileOptions, type UploadProgress, type UploadSession, type UploadStatus, type UploadTransport, type ValidationResult, allFields, assembleForm, contentHash, countryByDialCode, countryByIso, createBlock, createClient, createEmptyForm, createFormController, createId, defineForm, digitsOnly, flagEmoji, formatAnswer, formatNational, isBlockVisible, isCodeForm, isField, isPossiblePhone, normalizeFormSchema, normalizeFormTheme, parsePhone, pipeBlock, prefillFromParams, provisionWorkspace, resolveText, sha1Base64, syncCodeForm, toE164, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields };
+export { type AutoSubmitContext, BLOCK_KIND_META, type BaseField, type Block, type BlockKind, CONTENT_KINDS, type CheckboxField, type ChoiceField, type CodeForm, type Condition, type ConditionOp, type ContentBlock, type ContentKind, type CustomField, DEFAULT_STRINGS, DRAFT_KINDS, type DateField, type DividerBlock, FILLO_DATA_ATTRS, FILLO_SCHEMA_VERSION, FILLO_SDK_VERSION, FILLO_SLOTS, type Field, type FieldKind, type FieldSpec, type FieldValue, type FileUploadField, type FileValue, type FilloAppearance, FilloClient, type FilloClientOptions, FilloError, FilloJsxError, 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 LinearScaleField, type MatrixField, type NumberField, PHONE_COUNTRIES, type ParagraphBlock, type ParsedPhone, type PhoneCountry, type PhoneField, type ProvisionWorkspaceResult, type PublishedForm, type RankingField, type RatingField, type ResponseData, type SchemaValidationResult, type SelectOption, Sha1, type SignatureField, type SlotClass, type SlotState, type SubmitMeta, type SubmitResult, type SyncFormResult, type SyncedForm, type TextField, type UploadFileOptions, type UploadProgress, type UploadSession, type UploadStatus, type UploadTransport, type ValidationResult, type WhenBuilder, allFields, assembleForm, codeFormFromJsx, contentHash, countryByDialCode, countryByIso, countryByTimeZone, createBlock, createClient, createEmptyForm, createFormController, createId, defineForm, digitsOnly, flagEmoji, formatAnswer, formatNational, isAutoSubmitBlock, isBlockVisible, isCodeForm, isField, isFilloError, isPossiblePhone, needsExplicitSubmit, normalizeFormSchema, normalizeFormTheme, parsePhone, pipeBlock, prefillFromParams, provisionWorkspace, resolveSlotClass, resolveStrings, resolveText, schemaFromJsx, sha1Base64, shouldAutoSubmit, slotClass, syncCodeForm, toE164, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields, when };