@usefillo/react 0.8.0 → 0.10.0

package/README.md

@@ -1,9 +1,23 @@
-# @usefillo/react
+<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/react"><img src="https://img.shields.io/npm/v/@usefillo/react" alt="npm version" /></a>
+  <img src="https://img.shields.io/npm/l/@usefillo/react" alt="MIT license" />
+</p>
 
 React components and hooks for embedding [Fillo](https://fillo.so) forms **natively inside your product** — rendered in your own DOM, with your styles, on your route. No iframe.
 
-### 📚 Full documentation → **[fillo.so/docs](https://fillo.so/docs)**
-
 ```sh
 npm i @usefillo/react
 ```
@@ -36,10 +50,10 @@ export function ContactForm() {
 ```
 
 The first time this runs, the form appears in your Fillo workspace as a draft —
-publish it there and responses, logic, exports, webhooks, and integrations all
-work. Field ids are permanent (they key your responses); conditional questions
-are `visibleIf`, never conditional JSX. The equivalent config style,
-`defineForm({ id, pages })`, remains first-class — JSX compiles to it exactly.
+publish it there and responses, exports, webhooks, and integrations all work.
+Prefer config over JSX? `defineForm({ id, pages })` is first-class — JSX
+compiles to it exactly. Authoring guide:
+[fillo.so/docs/authoring](https://fillo.so/docs/authoring).
 
 ## Or embed a form built in the dashboard
 
@@ -67,12 +81,9 @@ import { FilloForm } from "@usefillo/react";
 >
 ```
 
-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 the shared form chrome (navigation, submit states, errors, and resume
-notices) with the `strings` prop. Styling contract:
+Every rendered part carries a named slot and state attributes
+(`data-invalid`, `data-selected`, …), and the default stylesheet is
+cascade-layered so your utilities always win. Styling contract:
 [fillo.so/docs/styling](https://fillo.so/docs/styling).
 
 ## Go fully headless
@@ -83,11 +94,7 @@ Every part is replaceable — and every embed method is free:
 - `<FilloProvider>` + `<FormField>` / `useField()` — your layout, Fillo's engine
 - `useFilloController()` — the bare engine for total control
 
-URL prefill works in embeds (`?field=value`, hidden-field `paramName`),
-submissions retry safely, and failed submits show a visible, answer-preserving
-error. This package re-exports the embedding surface from
-[`@usefillo/core`](https://www.npmjs.com/package/@usefillo/core) so a single
-import is usually enough.
+Headless guide: [fillo.so/docs/custom-ui](https://fillo.so/docs/custom-ui).
 
 ## Links
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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, 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';
+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';
 
 /**
@@ -136,10 +136,32 @@ 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). */
     onError?: (error: FilloError) => void;
+    /**
+     * Show the developer chrome on a surface Fillo doesn't detect as local
+     * development — a tunnel, a staging deploy, a production build you're
+     * smoke-testing. COSMETIC ONLY: it renders the dev notices, developer-grade
+     * submit failures, and a visible "Preview" badge, and it never changes
+     * where submissions go or whether they are accepted (test submissions
+     * authenticate with a credential, never a prop).
+     */
+    preview?: boolean;
+    /**
+     * Set false to hide the built-in dev notices (draft/staged/sync/no-client)
+     * when your page provides its own context. The explicit Preview badge and
+     * the production fail-closed states are unaffected.
+     */
+    devNotices?: boolean;
     /**
      * Render the form's own title/description header (default true). Set false
      * when the embedding page already provides a heading, to avoid a second
@@ -280,12 +302,25 @@ interface ControllerOptions {
     surface?: "default" | "headless";
     /** Resolve/verify the canonical submission target immediately before submit. */
     resolveFormId?: () => Promise<string>;
+    /**
+     * Surface the real resolveFormId failure (message + machine code) in
+     * `submitError` instead of the respondent-safe fallback. The built-in
+     * renderers set it from their dev-chrome gate (preview prop / dev
+     * environment) so integration details never reach production visitors.
+     */
+    verboseResolutionErrors?: boolean;
     /**
      * 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;
+    /** 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
@@ -308,6 +343,15 @@ interface FilloProviderProps extends Omit<ControllerOptions, "form"> {
     onError?: (error: FilloError) => void;
     /** Custom unavailable state; receives the full actionable integration error. */
     renderError?: (error: FilloError) => ReactNode;
+    /**
+     * Apply the developer-chrome behavior on a surface Fillo doesn't detect as
+     * local development (a tunnel, staging, a production smoke test): the code
+     * form renders and gates like development and failed submits carry the real
+     * error + code. COSMETIC ONLY — it never changes where submissions go or
+     * whether they are accepted. Headless stays headless: the provider still
+     * injects no layout (no badge or notices); the host owns all preview UI.
+     */
+    preview?: boolean;
     children: ReactNode;
 }
 /**
@@ -330,7 +374,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, onError, renderError, ...options }: FilloProviderProps): react.JSX.Element | null;
+declare function FilloProvider({ children, form, formId, client, appearance, strings, onError, renderError, preview, ...options }: FilloProviderProps): react.JSX.Element | null;
 
 /**
  * The full form engine — data, errors, pages, submit, status. Use inside a