@usefillo/react 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fillo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @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.
+
+### 📚 Full documentation → **[fillo.so/docs](https://fillo.so/docs)**
+
+```sh
+npm i @usefillo/react
+```
+
+`react` and `react-dom` (18 or 19) are peer dependencies.
+
+```tsx
+import { FilloForm, createClient } from "@usefillo/react";
+import "@usefillo/react/styles.css"; // optional default theme — or bring your own
+
+const client = createClient({ baseUrl: "https://fillo.so" });
+
+export function Feedback() {
+  return <FilloForm client={client} formId="cust-feedback" onSubmitted={(r) => confetti()} />;
+}
+```
+
+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:
+
+- `<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
+
+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.
+
+## Links
+
+- **Docs:** [fillo.so/docs](https://fillo.so/docs)
+- **Website:** [fillo.so](https://fillo.so)
+
+MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,172 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { FormSchema, FilloClient, ResponseData, FieldValue, FormPage, Block, FormStatus, FieldKind, Field, CodeForm, FormTheme, FilloError } from '@usefillo/core';
+export { CodeForm, Field, FieldValue, FileValue, FilloClient, FilloError, FormSchema, FormStatus, FormTheme, PublishedForm, ResponseData, createClient, defineForm } from '@usefillo/core';
+
+/**
+ * Everything a custom renderer needs. Returned by useFillo() and provided
+ * to every field component — the default ones and yours.
+ */
+interface FilloApi {
+    form: FormSchema;
+    formId?: string;
+    client?: FilloClient;
+    data: ResponseData;
+    errors: Record<string, string>;
+    setValue: (fieldId: string, value: FieldValue) => void;
+    pageIndex: number;
+    pageCount: number;
+    page: FormPage;
+    /** Blocks on the current page after visibility logic. */
+    blocks: Block[];
+    isFirstPage: boolean;
+    isLastPage: boolean;
+    next: () => void;
+    back: () => void;
+    submit: () => Promise<void>;
+    status: FormStatus;
+    /** True while any file upload is in flight — submit is blocked. */
+    uploading: boolean;
+    /** Used by upload fields to gate submission. */
+    setUploading: (fieldId: string, busy: boolean) => void;
+}
+interface FieldComponentProps {
+    field: Field;
+    value: FieldValue;
+    error: string | undefined;
+    setValue: (value: FieldValue) => void;
+    api: FilloApi;
+}
+/** Per-kind component overrides — swap any built-in field for your own. */
+type FieldComponents = Partial<Record<FieldKind, ComponentType<FieldComponentProps>>>;
+/**
+ * Renderers for your own field kinds, keyed by a custom field's `component`.
+ * A block `{ kind: "custom", component: "color", config: {...} }` renders
+ * `customComponents.color`. The component reads `field.config` for options.
+ */
+type CustomComponents = Record<string, ComponentType<FieldComponentProps>>;
+
+interface FilloFormProps {
+    /** Render a schema directly, or a code-defined form from defineForm(). */
+    form?: FormSchema | CodeForm;
+    /** Or fetch it: a client plus the form id/slug. */
+    client?: FilloClient;
+    formId?: string;
+    theme?: FormTheme;
+    /** Swap any built-in field kind for your own component. */
+    components?: FieldComponents;
+    /** Renderers for your own `custom` field kinds, keyed by `component`. */
+    customComponents?: CustomComponents;
+    initialData?: ResponseData;
+    onChange?: (data: ResponseData) => void;
+    onSubmitted?: (responseId: string | undefined, data: ResponseData) => void;
+    /** Take over submission entirely (instead of the client). */
+    onSubmit?: (data: ResponseData) => Promise<void> | void;
+    /** Observe load and code-form sync failures (otherwise only logged). */
+    onError?: (error: FilloError) => void;
+    /**
+     * Render the form's own title/description header (default true). Set false
+     * when the embedding page already provides a heading, to avoid a second
+     * page-level `<h1>`.
+     */
+    showTitle?: boolean;
+    /** Custom success screen. */
+    renderSuccess?: () => ReactNode;
+    /** Custom error screen — receives the failure (e.g. 404 vs network). */
+    renderError?: (error: FilloError) => ReactNode;
+    className?: string;
+}
+declare function FilloForm(props: FilloFormProps): react.JSX.Element;
+
+interface ControllerOptions {
+    form: FormSchema;
+    formId?: string;
+    client?: FilloClient;
+    initialData?: ResponseData;
+    onChange?: (data: ResponseData) => void;
+    onSubmitted?: (responseId: string | undefined, data: ResponseData) => void;
+    /** Custom submit handler — used instead of the client when provided. */
+    onSubmit?: (data: ResponseData) => Promise<void> | void;
+    /** Anti-spam signals provided by the renderer (honeypot value). */
+    getHoneypot?: () => string;
+}
+/**
+ * React binding for the framework-agnostic engine in @usefillo/core
+ * (createFormController). The engine owns all state and logic — validation,
+ * conditional visibility, paging, spam signals, submission, funnel tracking.
+ * This wraps it with useSyncExternalStore and keeps the latest callbacks and
+ * submit context wired in, so React, the DOM renderer, and the headless API all
+ * share one implementation.
+ */
+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;
+    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.
+ *
+ *   <FilloProvider form={feedback} client={client}>
+ *     <YourErrorContext />
+ *     <FormField id="reason" />
+ *     <p>We read every report.</p>
+ *     <FormField id="email" />
+ *     <MySubmitButton />            // calls useFillo().submit()
+ *   </FilloProvider>
+ *
+ * The schema stays the source of truth — render every required field, or
+ * submission will fail validation on a field the visitor can't see. With a
+ * 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;
+
+/**
+ * The full form engine — data, errors, pages, submit, status. Use inside a
+ * <FilloForm> or <FilloProvider> to build completely custom layouts.
+ */
+declare function useFillo(): FilloApi;
+interface FieldHandle {
+    /** The field's schema entry, or undefined if no field has this id. */
+    field: Field | undefined;
+    value: FieldValue;
+    error: string | undefined;
+    setValue: (value: FieldValue) => void;
+}
+/**
+ * Drive a single field by id — render it however you like, wherever you like.
+ * The engine still validates it, runs logic and handles submit. This is the
+ * lowest-level hook: with it you owe Fillo nothing but the field id.
+ */
+declare function useField(fieldId: string): FieldHandle;
+
+declare function BlockRenderer({ block, api, components, customComponents, }: {
+    block: Block;
+    api: FilloApi;
+    components?: FieldComponents;
+    customComponents?: CustomComponents;
+}): react.JSX.Element | null;
+/**
+ * Render a single field by id using the default (or overridden) component —
+ * drop it anywhere inside a <FilloProvider> to place fields in your own
+ * layout. For total control over the markup, use the useField() hook instead.
+ */
+declare function FormField({ id, components, customComponents, }: {
+    id: string;
+    components?: FieldComponents;
+    customComponents?: 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.
+ */
+declare function FileUploadField({ field, value, error, setValue, api }: FieldComponentProps): react.JSX.Element;
+
+export { BlockRenderer, type ControllerOptions, type CustomComponents, type FieldComponentProps, type FieldComponents, type FieldHandle, type FilloApi, FileUploadField as FilloFileUpload, FilloForm, type FilloFormProps, FilloProvider, type FilloProviderProps, FormField, useField, useFillo, useFilloController };