@usefillo/react 0.6.0 → 0.6.2

package/README.md

@@ -1,6 +1,6 @@
 # @usefillo/react
 
-Headless 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.
+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)**
 
@@ -10,34 +10,88 @@ npm i @usefillo/react
 
 `react` and `react-dom` (18 or 19) are peer dependencies.
 
+## Write forms as components
+
 ```tsx
-import { FilloForm } from "@usefillo/react";
+"use client";
+import { Fillo, when, createClient } from "@usefillo/react";
 import "@usefillo/react/styles.css"; // optional default theme — or bring your own
 
-export function Feedback() {
-  return <FilloForm formId="cust-feedback" onSubmitted={(r) => confetti()} />;
+const client = createClient({ key: process.env.NEXT_PUBLIC_FILLO_KEY });
+
+export function ContactForm() {
+  return (
+    <Fillo.Form id="contact" title="Talk to us" client={client}>
+      <Fillo.Text id="name" label="Your name" required />
+      <Fillo.Email id="email" label="Work email" required />
+      <Fillo.Select id="topic" label="Topic" required>
+        <Fillo.Option id="sales" label="Sales" />
+        <Fillo.Option id="support" label="Support" />
+      </Fillo.Select>
+      <Fillo.LongText id="message" label="How can we help?"
+                      visibleIf={when("topic").eq("support")} />
+    </Fillo.Form>
+  );
 }
 ```
 
-Every part is replaceable. Pass your own field components, theme the form via the `theme` prop, or drop down to the hooks and own the entire render:
+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.
+
+## Or embed a form built in the dashboard
+
+```tsx
+import { FilloForm } from "@usefillo/react";
+
+<FilloForm formId="cust-feedback" onSubmitted={(r) => confetti()} />
+```
+
+## Style it with your own classes
+
+```tsx
+<Fillo.Form
+  id="contact"
+  client={client}
+  appearance={{
+    theme: { primary: "#4f46e5", radius: "12px" }, // also themes your hosted page
+    classNames: {
+      control: "rounded-xl border-zinc-200 data-[invalid]:border-red-400",
+      option: "rounded-lg border p-3 data-[selected]:border-indigo-600",
+      button: (s) => (s.variant === "primary" ? "bg-indigo-600 text-white" : ""),
+    },
+    fields: { nps: { control: "grid grid-cols-11 gap-1" } },
+  }}
+>
+```
 
-- `<FilloForm>` / `<FilloProvider>` — render a form, or wrap your own layout
-- `useFillo()` / `useField()` — build a fully custom UI against form state
-- `useFilloController()` — headless controller for total control
-- `FormField` / `BlockRenderer` — render individual blocks
-- `defineForm()` — author a form in code and sync it to your workspace on first run
+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:
+[fillo.so/docs/styling](https://fillo.so/docs/styling).
 
-Published `formId` embeds can fetch and submit without a publishable key. Use `createClient({ key })` when syncing `defineForm()` schemas from code, or when you need to point the SDK at a custom API origin.
+## Go fully headless
 
-For tiny feedback widgets, set `settings.submitMode: "auto"` on a select/rating/checkbox/dropdown/linear scale form. The default renderer hides the first submit button, submits after a complete discrete answer, and brings the submit button back if that answer opens a text or upload follow-up. Add `submissionLimit: "once_per_visitor"` for browser-scoped one-response feedback.
+Every part is replaceable — and every embed method is free:
 
-The default stylesheet follows system dark mode for unthemed embeds. Pass `theme={{ colorScheme: "dark" }}` or `"light"` when the host surface is known.
+- `components` / `customComponents` — swap any field kind for your own
+- `<FilloProvider>` + `<FormField>` / `useField()` — your layout, Fillo's engine
+- `useFilloController()` — the bare engine for total control
 
-This package re-exports the embedding surface from [`@usefillo/core`](https://www.npmjs.com/package/@usefillo/core) (`createClient`, `FormSchema`, `FormTheme`, …) so a single import is usually enough.
+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.
 
 ## Links
 
 - **Docs:** [fillo.so/docs](https://fillo.so/docs)
+- **Authoring guide:** [fillo.so/docs/authoring](https://fillo.so/docs/authoring)
 - **Website:** [fillo.so](https://fillo.so)
 
 MIT licensed.

package/dist/index.d.ts

@@ -148,6 +148,7 @@ type ContentProps = {
     id: string;
     children?: string;
     text?: string;
+    visibleIf?: Condition | Condition[];
 };
 /** Inert: rendering one throws; they exist to be read by the compiler. */
 type Inert<P> = (props: P) => never;
@@ -194,6 +195,7 @@ declare const Fillo: {
     readonly Paragraph: Inert<ContentProps>;
     readonly Divider: Inert<{
         id: string;
+        visibleIf?: Condition | Condition[];
     }>;
     readonly Page: Inert<{
         id: string;

package/dist/index.js

@@ -706,10 +706,11 @@ function FileUploadField({ field, value, error, setValue, api, ids: providedIds
       setInFlight((prev) => prev.filter((f) => f.key !== key));
       const current = Array.isArray(api.data[field.id]) ? api.data[field.id] : [];
       setValue([...current, uploaded]);
-    } catch {
+    } catch (err) {
       if (mountedRef.current) {
+        const message = err instanceof Error && err.name === "FilloError" && err.message ? err.message : "Upload failed \u2014 try again";
         setInFlight(
-          (prev) => prev.map((f) => f.key === key ? { ...f, error: "Upload failed \u2014 try again" } : f)
+          (prev) => prev.map((f) => f.key === key ? { ...f, error: message } : f)
         );
       }
     } finally {
@@ -773,7 +774,7 @@ function FileUploadField({ field, value, error, setValue, api, ids: providedIds
               hidden: true,
               multiple: maxFiles > 1,
               accept: schema.accept?.join(","),
-              onChange: (e) => handleFiles(e.target.files)
+              onChange: (e) => canUpload && handleFiles(e.target.files)
             }
           ),
           canUpload ? /* @__PURE__ */ jsxs3(Fragment, { children: [
@@ -2149,8 +2150,8 @@ function FilloProvider({ children, form, formId, client, appearance, strings, ..
     client,
     form: schema,
     formId: syncedFormId ?? formId,
-    // Headless embedding renders no Fillo layout (so it carries no branding) —
-    // a paid capability the server enforces when these responses are submitted.
+    // Headless = your markup, no Fillo-rendered layout. Free like every embed
+    // method; recorded per response so usage stays measurable.
     surface: "headless"
   });
   return /* @__PURE__ */ jsx7(FilloContext.Provider, { value: api, children: /* @__PURE__ */ jsx7(FilloStringsContext.Provider, { value: resolveStrings2(strings), children: /* @__PURE__ */ jsx7(FilloAppearanceContext.Provider, { value: appearance, children: /* @__PURE__ */ jsx7(FilloInstanceIdContext.Provider, { value: instanceId, children }) }) }) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefillo/react",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Headless React components for embedding Fillo forms natively in your product.",
   "license": "MIT",
   "keywords": [
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@usefillo/core": "^0.6.0"
+    "@usefillo/core": "^0.6.2"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",