@usefillo/react 0.5.4 → 0.6.1

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

@@ -1,7 +1,8 @@
 import * as react from 'react';
-import { ComponentType, ReactNode } from 'react';
-import { FormSchema, FilloClient, ResponseData, FieldValue, FormPage, Block, FormStatus, FieldKind, Field, CustomField, FormTheme, FilloError, CodeForm } from '@usefillo/core';
-export { CodeForm, Field, FieldValue, FileValue, FilloClient, FilloError, FormSchema, FormStatus, FormTheme, ProvisionWorkspaceResult, PublishedForm, ResponseData, createClient, defineForm, provisionWorkspace } from '@usefillo/core';
+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';
 
 /**
  * Everything a custom renderer needs. Returned by useFillo() and provided
@@ -27,6 +28,8 @@ interface FilloApi {
     status: FormStatus;
     /** True while any file upload is in flight — submit is blocked. */
     uploading: boolean;
+    /** Human-readable message for the last failed submit; cleared on edit/retry. */
+    submitError?: string;
     /** Used by upload fields to gate submission. */
     setUploading: (fieldId: string, busy: boolean) => void;
 }
@@ -69,6 +72,14 @@ type CustomComponents = Record<string, ComponentType<FieldComponentProps<CustomF
 
 interface FilloFormBaseProps {
     theme?: FormTheme;
+    /**
+     * The styling contract: theme tokens plus per-slot class strings (Tailwind
+     * or your own), appended after the built-in fillo-* classes so they win by
+     * cascade order. `appearance.theme` outranks every other theme source.
+     */
+    appearance?: FilloAppearance;
+    /** Override any visitor-facing renderer string (for localized sites). */
+    strings?: Partial<FilloStrings>;
     /** Swap any built-in field kind for your own component. */
     components?: FieldComponents;
     /** Renderers for your own `custom` field kinds, keyed by `component`. */
@@ -118,6 +129,85 @@ type PreviewFormProps = FilloFormBaseProps & {
 type FilloFormProps = HostedFormProps | CodeBackedFormProps | PreviewFormProps;
 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");
+ * pass the compiled VALUE across server/client boundaries, never the JSX.
+ */
+type WithVisible<T> = Omit<T, "kind" | "visibleIf"> & {
+    visibleIf?: Condition | Condition[];
+};
+type ChoiceProps = Omit<WithVisible<ChoiceField>, "options"> & {
+    options?: SelectOption[];
+    children?: ReactNode;
+};
+type ContentProps = {
+    id: string;
+    children?: string;
+    text?: string;
+};
+/** Inert: rendering one throws; they exist to be read by the compiler. */
+type Inert<P> = (props: P) => never;
+interface FilloJsxFormProps extends Omit<FilloFormProps, "form" | "formId" | "client"> {
+    /** Workspace handle — the form's identity across syncs. */
+    id: string;
+    title?: string;
+    description?: string;
+    settings?: FormSettings;
+    theme?: FormTheme;
+    client?: FilloClient;
+    children?: ReactNode;
+}
+declare function JsxForm(props: FilloJsxFormProps): react.JSX.Element;
+declare function defineFormFromJsx(element: ReactElement<FilloJsxFormProps>): CodeForm;
+declare const Fillo: {
+    readonly Form: typeof JsxForm;
+    /** Compile a <Fillo.Form> element to a CodeForm at module scope — the same
+     * value FilloProvider (headless) and the CLI consume. */
+    readonly defineForm: typeof defineFormFromJsx;
+    readonly Text: Inert<WithVisible<TextField>>;
+    readonly LongText: Inert<WithVisible<TextField>>;
+    readonly Email: Inert<WithVisible<TextField>>;
+    readonly Url: Inert<WithVisible<TextField>>;
+    readonly Phone: Inert<WithVisible<PhoneField>>;
+    readonly Number: Inert<WithVisible<NumberField>>;
+    readonly Select: Inert<ChoiceProps>;
+    readonly MultiSelect: Inert<ChoiceProps>;
+    readonly Dropdown: Inert<ChoiceProps>;
+    readonly Checkbox: Inert<WithVisible<CheckboxField>>;
+    readonly Rating: Inert<WithVisible<RatingField>>;
+    readonly Scale: Inert<WithVisible<LinearScaleField>>;
+    readonly Ranking: Inert<Omit<WithVisible<RankingField>, "options"> & {
+        options?: SelectOption[];
+        children?: ReactNode;
+    }>;
+    readonly Matrix: Inert<WithVisible<_usefillo_core.MatrixField>>;
+    readonly Signature: Inert<WithVisible<SignatureField>>;
+    readonly Date: Inert<WithVisible<DateField>>;
+    readonly FileUpload: Inert<WithVisible<FileUploadField$1>>;
+    readonly Hidden: Inert<WithVisible<HiddenField>>;
+    readonly Custom: Inert<WithVisible<CustomField>>;
+    readonly Heading: Inert<ContentProps>;
+    readonly Paragraph: Inert<ContentProps>;
+    readonly Divider: Inert<{
+        id: string;
+    }>;
+    readonly Page: Inert<{
+        id: string;
+        title?: string;
+        children?: ReactNode;
+    }>;
+    readonly Option: Inert<Omit<SelectOption, "id"> & {
+        id: string;
+    }>;
+};
+
+/** The raw appearance object — for renderers that resolve slots inside loops. */
+declare function useFilloAppearance(): FilloAppearance | undefined;
+
 interface ControllerOptions {
     form: FormSchema;
     formId?: string;
@@ -129,8 +219,14 @@ interface ControllerOptions {
     getHoneypot?: () => string;
     /** @internal Preview-only page navigation escape hatch. Submission still validates. */
     skipValidation?: boolean;
-    /** Embedding surface; "headless" (FilloProvider) is server-enforced as paid. */
+    /**
+     * Embedding surface, recorded per response for measurement. Defaults to
+     * "headless" (your own markup), matching @usefillo/core — the framed
+     * renderers pass "default" explicitly.
+     */
     surface?: "default" | "headless";
+    /** Resolve the submission target at submit time when formId is still unset. */
+    resolveFormId?: () => Promise<string>;
 }
 /**
  * React binding for the framework-agnostic engine in @usefillo/core
@@ -145,6 +241,10 @@ declare function useFilloController(options: ControllerOptions): FilloApi;
 interface FilloProviderProps extends Omit<ControllerOptions, "form"> {
     /** A schema, or a code-defined form from defineForm() — which also syncs. */
     form: FormSchema | CodeForm;
+    /** Slot classes for FormField-rendered fields in your composed layout. */
+    appearance?: FilloAppearance;
+    /** Override any visitor-facing renderer string (for localized sites). */
+    strings?: Partial<FilloStrings>;
     children: ReactNode;
 }
 /**
@@ -166,7 +266,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, ...options }: FilloProviderProps): react.JSX.Element;
+declare function FilloProvider({ children, form, formId, client, appearance, strings, ...options }: FilloProviderProps): react.JSX.Element;
 
 /**
  * The full form engine — data, errors, pages, submit, status. Use inside a
@@ -217,4 +317,4 @@ declare function FormField({ id, components, customComponents, }: {
  */
 declare function FileUploadField({ field, value, error, setValue, api, ids: providedIds }: FieldComponentProps): react.JSX.Element;
 
-export { BlockRenderer, type ControllerOptions, type CustomComponents, type FieldComponentProps, type FieldComponents, type FieldHandle, type FilloApi, type FilloFieldIds, FileUploadField as FilloFileUpload, FilloForm, type FilloFormProps, FilloProvider, type FilloProviderProps, FormField, useField, useFillo, useFilloController };
+export { BlockRenderer, type ControllerOptions, type CustomComponents, type FieldComponentProps, type FieldComponents, type FieldHandle, Fillo, type FilloApi, type FilloFieldIds, FileUploadField as FilloFileUpload, FilloForm, type FilloFormProps, type FilloJsxFormProps, FilloProvider, type FilloProviderProps, FormField, useField, useFillo, useFilloAppearance, useFilloController };