@usefillo/react 0.5.3 → 0.6.0

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, 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;
 }
@@ -47,17 +50,36 @@ interface FieldComponentProps<F extends Field = Field> {
     api: FilloApi;
     ids?: FilloFieldIds;
 }
-/** Per-kind component overrides — swap any built-in field for your own. */
-type FieldComponents = Partial<Record<FieldKind, ComponentType<FieldComponentProps>>>;
+/**
+ * The Field variant carrying a given kind. Some variants share a union `kind`
+ * (ChoiceField is "select" | "multi_select" | "dropdown"), so `Extract` would
+ * collapse to `never` — distribute over the union and keep the matching member.
+ */
+type FieldOfKind<K extends FieldKind> = Field extends infer V ? V extends Field ? K extends V["kind"] ? V : never : never : never;
+/**
+ * Per-kind component overrides — swap any built-in field for your own. Each
+ * kind's `field` is narrowed to its variant, so an override reads it cast-free.
+ */
+type FieldComponents = {
+    [K in FieldKind]?: ComponentType<FieldComponentProps<FieldOfKind<K>>>;
+};
 /**
  * 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>>;
+type CustomComponents = Record<string, ComponentType<FieldComponentProps<CustomField>>>;
 
 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`. */
@@ -107,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;
@@ -118,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
@@ -134,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;
 }
 /**
@@ -155,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
@@ -206,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 };