@usefillo/react 0.9.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

@@ -147,6 +147,21 @@ interface FilloFormBaseProps {
     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
@@ -287,6 +302,13 @@ 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
@@ -321,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;
 }
 /**
@@ -343,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