@usefillo/react 0.11.0 → 0.12.1

package/dist/index.d.ts

@@ -178,6 +178,12 @@ interface FilloFormBaseProps {
     renderSuccess?: () => ReactNode;
     /** Custom error screen — receives the failure (e.g. 404 vs network). */
     renderError?: (error: FilloError) => ReactNode;
+    /**
+     * Render a deliberately local, non-submitting preview. Transport, uploads,
+     * saved progress, and code-form sync are disabled. Use this only for UI
+     * previews; real embeds need either `formId` or `defineForm()` + `client`.
+     */
+    renderOnly?: boolean;
     /**
      * @internal Builder/test preview: let "Next" move between pages without
      * client-side validation. Submission and branding are still authoritative.
@@ -190,22 +196,42 @@ type HostedFormProps = FilloFormBaseProps & {
     formId: string;
     form?: undefined;
     client?: FilloClient;
+    renderOnly?: false;
+    skipValidation?: false;
 };
-type CodeBackedFormProps = FilloFormBaseProps & {
-    /** Render a schema directly, or a code-defined form from defineForm(). */
+type InlineTargetedFormProps = FilloFormBaseProps & {
+    /** Render a schema directly against an explicit published Fillo form. */
     form: FormSchema | CodeForm;
-    /** Required for code-defined forms that should save responses in Fillo. */
+    formId: string;
+    client?: FilloClient;
+    renderOnly?: false;
+    skipValidation?: false;
+};
+type CodeBackedFormProps = FilloFormBaseProps & {
+    /** A defineForm() value can resolve its Fillo target through the keyed client. */
+    form: CodeForm;
     client: FilloClient;
+    formId?: undefined;
+    renderOnly?: false;
+    skipValidation?: false;
+};
+type RenderOnlyFormProps = FilloFormBaseProps & {
+    /** Explicit local preview: it can render, but cannot submit or upload. */
+    form: FormSchema | CodeForm;
+    client?: FilloClient;
     formId?: string;
+    renderOnly: true;
+    skipValidation?: boolean;
 };
-type PreviewFormProps = FilloFormBaseProps & {
-    /** Builder/test preview: render locally and complete locally. */
+type LegacyPreviewFormProps = FilloFormBaseProps & {
+    /** @internal Backward-compatible builder/test preview. */
     form: FormSchema | CodeForm;
     client?: FilloClient;
     formId?: string;
+    renderOnly?: boolean;
     skipValidation: true;
 };
-type FilloFormProps = HostedFormProps | CodeBackedFormProps | PreviewFormProps;
+type FilloFormProps = HostedFormProps | InlineTargetedFormProps | CodeBackedFormProps | RenderOnlyFormProps | LegacyPreviewFormProps;
 declare function FilloForm(props: FilloFormProps): react.JSX.Element;
 
 /**
@@ -231,16 +257,28 @@ type ContentProps = {
 };
 /** 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"> {
+interface FilloJsxFormBaseProps extends Omit<FilloFormProps, "form" | "formId" | "client" | "renderOnly" | "skipValidation"> {
     /** Workspace handle — the form's identity across syncs. */
     id: string;
     title?: string;
     description?: string;
     settings?: FormSettings;
     theme?: FormTheme;
-    client?: FilloClient;
     children?: ReactNode;
 }
+type FilloJsxFormProps = FilloJsxFormBaseProps & ({
+    client: FilloClient;
+    renderOnly?: false;
+    skipValidation?: false;
+} | {
+    client?: FilloClient;
+    renderOnly: true;
+    skipValidation?: boolean;
+} | {
+    client?: FilloClient;
+    renderOnly?: boolean;
+    skipValidation: true;
+});
 declare function JsxForm(props: FilloJsxFormProps): react.JSX.Element;
 declare function defineFormFromJsx(element: ReactElement<FilloJsxFormProps>): CodeForm;
 declare const Fillo: {
@@ -339,9 +377,7 @@ interface ControllerOptions {
  */
 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;
+interface FilloProviderBaseProps extends Omit<ControllerOptions, "form" | "formId" | "client" | "skipValidation"> {
     /** Slot classes for FormField-rendered fields in your composed layout. */
     appearance?: FilloAppearance;
     /** Override any visitor-facing renderer string (for localized sites). */
@@ -359,8 +395,44 @@ interface FilloProviderProps extends Omit<ControllerOptions, "form"> {
      * injects no layout (no badge or notices); the host owns all preview UI.
      */
     preview?: boolean;
+    /**
+     * Render a deliberately local preview. Submission, uploads, saved progress,
+     * and code-form sync are disabled.
+     */
+    renderOnly?: boolean;
+    /** @internal Backward-compatible builder/test preview. */
+    skipValidation?: boolean;
     children: ReactNode;
 }
+type TargetedProviderProps = FilloProviderBaseProps & {
+    form: FormSchema | CodeForm;
+    formId: string;
+    client?: FilloClient;
+    renderOnly?: false;
+    skipValidation?: false;
+};
+type CodeBackedProviderProps = FilloProviderBaseProps & {
+    form: CodeForm;
+    client: FilloClient;
+    formId?: undefined;
+    renderOnly?: false;
+    skipValidation?: false;
+};
+type RenderOnlyProviderProps = FilloProviderBaseProps & {
+    form: FormSchema | CodeForm;
+    client?: FilloClient;
+    formId?: string;
+    renderOnly: true;
+    skipValidation?: boolean;
+};
+type LegacyPreviewProviderProps = FilloProviderBaseProps & {
+    form: FormSchema | CodeForm;
+    client?: FilloClient;
+    formId?: string;
+    renderOnly?: boolean;
+    skipValidation: true;
+};
+type FilloProviderProps = TargetedProviderProps | CodeBackedProviderProps | RenderOnlyProviderProps | LegacyPreviewProviderProps;
 /**
  * The headless escape hatch. Sets up the form engine (validation, conditional
  * logic, uploads, submit) and renders no resolved form layout — you compose it
@@ -381,7 +453,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, preview, ...options }: FilloProviderProps): react.JSX.Element | null;
+declare function FilloProvider({ children, form, formId, client, appearance, strings, onError, renderError, preview, renderOnly, skipValidation, ...options }: FilloProviderProps): react.JSX.Element | null;
 
 /**
  * The full form engine — data, errors, pages, submit, status. Use inside a
@@ -430,6 +502,6 @@ declare function FormField({ id, components, customComponents, }: {
  * provider-aware browser-direct transfer (resumable where supported). Replace
  * it via `components` if needed; completed uploads are FileValue[] in the data.
  */
-declare function FileUploadField({ field, value, error, setValue, api, ids: providedIds }: FieldComponentProps): react.JSX.Element;
+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, Fillo, type FilloApi, type FilloFieldIds, FileUploadField as FilloFileUpload, FilloForm, type FilloFormProps, type FilloJsxFormProps, FilloProvider, type FilloProviderProps, FormField, useField, useFillo, useFilloAppearance, useFilloController };