@usefillo/react 0.7.0 → 0.9.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, 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, 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, ChallengeConfig, 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
@@ -48,6 +48,23 @@ interface FilloApi {
      * 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
@@ -105,7 +122,7 @@ 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`. */
@@ -119,6 +136,13 @@ interface FilloFormBaseProps {
      * loads).
      */
     respondent?: FilloRespondent;
+    /**
+     * Human-verification challenge config (public site key + provider). Normally
+     * the SDK reads this from the form fetch automatically; pass it explicitly
+     * only when you render an inline `form` schema and still want the widget (the
+     * hosted page does this). The SECRET key stays server-side — never passed here.
+     */
+    challenge?: ChallengeConfig;
     onChange?: (data: ResponseData) => void;
     onSubmitted?: (responseId: string | undefined, data: ResponseData) => void;
     /** Observe load and code-form sync failures (otherwise only logged). */
@@ -167,8 +191,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"> & {
@@ -261,7 +285,7 @@ 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
@@ -269,6 +293,12 @@ interface ControllerOptions {
      * dashboard, webhooks, and integrations can say who answered.
      */
     respondent?: FilloRespondent;
+    /** True when the form requires a human-verification challenge (Turnstile). */
+    challengeRequired?: boolean;
+    /** Read the current challenge token from the rendered widget (lazy). */
+    getChallengeToken?: () => string | undefined;
+    /** The server rejected the challenge — reset the widget for a fresh token. */
+    onChallengeFailed?: () => void;
 }
 /**
  * React binding for the framework-agnostic engine in @usefillo/core
@@ -286,14 +316,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 />
@@ -308,7 +343,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
@@ -353,9 +388,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;