@usefillo/react 0.6.2 → 0.8.0

package/README.md

@@ -71,7 +71,8 @@ Every rendered part carries a named slot (`data-fillo`) and state attributes
 (`data-invalid`, `data-selected`, `data-checked`, …), and the default
 stylesheet is cascade-layered so your utilities always win. On Tailwind v3 or
 reset-heavy sites import `@usefillo/react/styles.unlayered.css` instead.
-Localize every built-in string with the `strings` prop. Styling contract:
+Localize the shared form chrome (navigation, submit states, errors, and resume
+notices) with the `strings` prop. Styling contract:
 [fillo.so/docs/styling](https://fillo.so/docs/styling).
 
 ## Go fully headless

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import * as react from 'react';
 import { ComponentType, ReactNode, ReactElement } from 'react';
 import * as _usefillo_core from '@usefillo/core';
-import { FormSchema, FilloClient, ResponseData, FieldValue, FormPage, Block, FormStatus, FieldKind, Field, CustomField, FormTheme, FilloAppearance, FilloStrings, FilloError, CodeForm, FormSettings, Condition, TextField, PhoneField, NumberField, ChoiceField, SelectOption, CheckboxField, RatingField, LinearScaleField, RankingField, SignatureField, DateField, FileUploadField as FileUploadField$1, HiddenField } from '@usefillo/core';
-export { CodeForm, Field, FieldValue, FileValue, FilloAppearance, FilloClient, FilloError, FilloJsxError, FilloSlot, FilloStrings, FormSchema, FormStatus, FormTheme, ProvisionWorkspaceResult, PublishedForm, ResponseData, SlotState, createClient, defineForm, provisionWorkspace, when } from '@usefillo/core';
+import { FormSchema, FilloClient, ResponseData, FieldValue, FormPage, Block, FormStatus, FieldKind, Field, CustomField, FormTheme, FilloAppearance, FilloRendererStrings, FilloRespondent, FilloError, CodeForm, FormSettings, Condition, TextField, PhoneField, NumberField, ChoiceField, SelectOption, CheckboxField, RatingField, LinearScaleField, RankingField, SignatureField, DateField, FileUploadField as FileUploadField$1, HiddenField } from '@usefillo/core';
+export { CodeForm, Field, FieldValue, FileValue, FilloAppearance, FilloClient, FilloError, FilloJsxError, FilloRendererStrings, FilloSlot, FilloStrings, FormSchema, FormStatus, FormTheme, ProvisionWorkspaceResult, PublishedForm, ResponseData, SlotState, createClient, defineForm, provisionWorkspace, when } from '@usefillo/core';
 
 /**
  * Everything a custom renderer needs. Returned by useFillo() and provided
@@ -30,6 +30,49 @@ interface FilloApi {
     uploading: boolean;
     /** Human-readable message for the last failed submit; cleared on edit/retry. */
     submitError?: string;
+    /**
+     * True when `status` is "submitted" because the once-per-visitor gate
+     * restored a previous visit's response, not because a submit happened in
+     * this mount. Skip one-time "just submitted" reactions (focus moves,
+     * redirects, confetti) when it's set — remounts replay them otherwise.
+     */
+    restoredSubmission: boolean;
+    /**
+     * True when a saved-progress draft (settings.saveProgress) restored answers
+     * and/or page position from a previous visit. Show a "picked up where you
+     * left off" affordance with a Start over action (resetDraft) when set.
+     */
+    resumedDraft: boolean;
+    /**
+     * True when an update-in-place limit prefilled the VERIFIED respondent's own
+     * previous answers — submitting updates that response in place.
+     */
+    editingPrevious: boolean;
+    /**
+     * True when the last submit was kept as an already-recorded response (a
+     * verified identify() repeat on a keep-mode form) rather than a fresh one.
+     * Renderers show an "already answered" note instead of implying a new save.
+     */
+    duplicateSubmission: boolean;
+    /**
+     * True when the last submit updated the person's existing response in place
+     * (responseLimit onRepeat "update") rather than creating a new one.
+     */
+    updatedSubmission: boolean;
+    /**
+     * True when a resume link (#fillo-draft=…) was expired, spent, or foreign, so
+     * no progress could be restored. Renderers explain the blank form instead of
+     * showing it with no context.
+     */
+    resumeLinkFailed: boolean;
+    /**
+     * Persist unsaved draft progress right now (settings.saveProgress forms).
+     * The built-in renderers call it on pagehide/visibility-hidden; custom
+     * headless layouts inside <FilloProvider> get the same wiring for free.
+     */
+    flushDraft: () => void;
+    /** Discard the saved draft and reset to a fresh fill ("Start over"). */
+    resetDraft: () => void;
     /** Used by upload fields to gate submission. */
     setUploading: (fieldId: string, busy: boolean) => void;
 }
@@ -79,12 +122,20 @@ interface FilloFormBaseProps {
      */
     appearance?: FilloAppearance;
     /** Override any visitor-facing renderer string (for localized sites). */
-    strings?: Partial<FilloStrings>;
+    strings?: Partial<FilloRendererStrings>;
     /** Swap any built-in field kind for your own component. */
     components?: FieldComponents;
     /** Renderers for your own `custom` field kinds, keyed by `component`. */
     customComponents?: CustomComponents;
     initialData?: ResponseData;
+    /**
+     * identify(): your app's account context for the person filling the form
+     * ({ id, email?, name?, traits? } — id is your own user id). Recorded with
+     * the response as an unverified claim so responses, webhooks, and
+     * integrations can say who answered. Safe to pass late (after your session
+     * loads).
+     */
+    respondent?: FilloRespondent;
     onChange?: (data: ResponseData) => void;
     onSubmitted?: (responseId: string | undefined, data: ResponseData) => void;
     /** Observe load and code-form sync failures (otherwise only logged). */
@@ -133,8 +184,8 @@ declare function FilloForm(props: FilloFormProps): react.JSX.Element;
  * The authoring namespace: `<Fillo.Form id="contact"><Fillo.Email id="email"
  * label="Work email"/></Fillo.Form>`. Field elements are inert descriptors
  * compiled (never rendered) into the exact CodeForm defineForm() emits, then
- * fed to the existing framed <FilloForm> — same sync, same draft-by-default,
- * same badge, same responses. Define forms in a client module ("use client");
+ * fed to the existing framed <FilloForm> — same policy-aware resolution and
+ * staging, same badge, same responses. Define forms in a client module ("use client");
  * pass the compiled VALUE across server/client boundaries, never the JSX.
  */
 type WithVisible<T> = Omit<T, "kind" | "visibleIf"> & {
@@ -227,8 +278,14 @@ interface ControllerOptions {
      * renderers pass "default" explicitly.
      */
     surface?: "default" | "headless";
-    /** Resolve the submission target at submit time when formId is still unset. */
+    /** Resolve/verify the canonical submission target immediately before submit. */
     resolveFormId?: () => Promise<string>;
+    /**
+     * Host-app account context (identify()): who is filling this form, by your
+     * own user id. Recorded with the response as an unverified claim so the
+     * dashboard, webhooks, and integrations can say who answered.
+     */
+    respondent?: FilloRespondent;
 }
 /**
  * React binding for the framework-agnostic engine in @usefillo/core
@@ -246,14 +303,19 @@ interface FilloProviderProps extends Omit<ControllerOptions, "form"> {
     /** Slot classes for FormField-rendered fields in your composed layout. */
     appearance?: FilloAppearance;
     /** Override any visitor-facing renderer string (for localized sites). */
-    strings?: Partial<FilloStrings>;
+    strings?: Partial<FilloRendererStrings>;
+    /** Observe code-form sync/configuration failures. */
+    onError?: (error: FilloError) => void;
+    /** Custom unavailable state; receives the full actionable integration error. */
+    renderError?: (error: FilloError) => ReactNode;
     children: ReactNode;
 }
 /**
  * The headless escape hatch. Sets up the form engine (validation, conditional
- * logic, uploads, submit) and renders **no layout at all** — you compose the
- * entire form yourself with <FormField>, useField() and useFillo(),
- * interleaving any markup of your own between fields.
+ * logic, uploads, submit) and renders no resolved form layout — you compose it
+ * with <FormField>, useField() and useFillo(). In production, a code form
+ * withholds children (returns null) until its canonical schema is safe; pass
+ * renderError to own unavailable/not-published UI without adding SDK layout.
  *
  *   <FilloProvider form={feedback} client={client}>
  *     <YourErrorContext />
@@ -268,7 +330,7 @@ interface FilloProviderProps extends Omit<ControllerOptions, "form"> {
  * defineForm() form and a keyed client, the structure also syncs into your
  * workspace, exactly like <FilloForm>.
  */
-declare function FilloProvider({ children, form, formId, client, appearance, strings, ...options }: FilloProviderProps): react.JSX.Element;
+declare function FilloProvider({ children, form, formId, client, appearance, strings, onError, renderError, ...options }: FilloProviderProps): react.JSX.Element | null;
 
 /**
  * The full form engine — data, errors, pages, submit, status. Use inside a
@@ -313,9 +375,9 @@ declare function FormField({ id, components, customComponents, }: {
 }): react.JSX.Element | null;
 
 /**
- * Default file upload field: drag & drop, resumable chunked uploads with live
- * progress, multiple files. Replace it entirely via the `components` prop if
- * you want your own — completed uploads are just FileValue[] in the data.
+ * Default file upload field: drag & drop, multiple files, live progress, and
+ * provider-aware browser-direct transfer (resumable where supported). Replace
+ * it via `components` if needed; completed uploads are FileValue[] in the data.
  */
 declare function FileUploadField({ field, value, error, setValue, api, ids: providedIds }: FieldComponentProps): react.JSX.Element;